@xmachines/play-react 1.0.0-beta.9 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Karon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,395 +1,193 @@
-# @xmachines/play-react
-
-**React renderer consuming signals and UI schema with provider pattern**
-
-Signal-driven React rendering layer observing actor state with zero React state for business logic.
+<!-- generated-by: gsd-doc-writer -->
 
-## Overview
-
-`@xmachines/play-react` provides `PlayRenderer` and `useSignalEffect` for building React UIs that passively observe actor signals. This package enables framework-swappable architecture where React is just a rendering target subscribing to signal changes — business logic lives entirely in the actor.
+# @xmachines/play-react
 
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+React renderer for XMachines Play architecture with signal-driven rendering.
 
-- **Signal-Only Reactivity (INV-05):** No useState/useReducer for business logic, signals only
-- **Passive Infrastructure (INV-04):** Components observe signals, send events to actor
+Part of the [xmachines-js monorepo](../../README.md).
 
-**Key Principle:** React state is never used for business logic. Signals are the source of truth.
+## Installation
 
-Renderer receives actor via props (provider pattern), not children.
+```bash
+pnpm add @xmachines/play-react
+```
 
-## Installation
+**Peer dependencies** (must be installed separately):
 
 ```bash
-npm install react@^18.0.0 react-dom@^18.0.0
-npm install @xmachines/play-react
+pnpm add react react-dom xstate @xstate/store @xmachines/json-render-react @xmachines/json-render-core @xmachines/json-render-xstate
 ```
 
-## Current Exports
+Supported versions:
 
-- `PlayRenderer`
-- `useSignalEffect`
-- `PlayErrorBoundary`
-- `PlayRendererProps` (type)
-- `PlayErrorBoundaryProps` (type)
+- `react` / `react-dom`: `^18.0.0 || ^19.0.0`
+- `xstate`: `^5.31.0`
+- `@xstate/store`: `^3.17.0`
+- `@xmachines/json-render-*`: `^0.18.0`
 
-**Peer dependencies:**
+## Usage
 
-- `react` ^18.0.0 || ^19.0.0 — React runtime
-- `react-dom` ^18.0.0 || ^19.0.0 — React DOM renderer
+### Standard usage — `PlayUIProvider` + `PlayRenderer`
 
-## Quick Start
+The recommended pattern for actor-driven React rendering:
 
-```typescript
-import { createRoot } from "react-dom/client";
+```tsx
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 import { definePlayer } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { PlayRenderer } from "@xmachines/play-react";
-import { z } from "zod";
-
-// 1. Define catalog (business logic layer)
-const catalog = defineCatalog({
-	LoginForm: z.object({ error: z.string().optional() }),
-	Dashboard: z.object({
-		userId: z.string(),
-		username: z.string(),
-	}),
-});
 
-// 2. Create React components (view layer)
-const components = {
-	LoginForm: ({ error, send }) => (
-		<form
-			onSubmit={(e) => {
-				e.preventDefault();
-				const data = new FormData(e.currentTarget);
-				send({
-					type: "auth.login",
-					username: data.get("username"),
-				});
-			}}
-		>
-			{error && <p style={{ color: "red" }}>{error}</p>}
-			<input name="username" required placeholder="Username" />
-			<button type="submit">Log In</button>
-		</form>
-	),
-	Dashboard: ({ userId, username, send }) => (
-		<div>
-			<h1>Welcome, {username}!</h1>
-			<p>User ID: {userId}</p>
-			<button onClick={() => send({ type: "auth.logout" })}>Log Out</button>
-		</div>
-	),
-};
-
-// 3. Create player actor (business logic runtime)
-const createPlayer = definePlayer({ machine: authMachine, catalog });
-const actor = createPlayer();
+// 1. Create and start the actor
+const actor = definePlayer({ machine: myMachine })();
 actor.start();
 
-// 4. Render UI (actor via props)
-const root = createRoot(document.getElementById("app")!);
-root.render(<PlayRenderer actor={actor} components={components} />);
-```
-
-## API Reference
-
-### PlayRenderer
-
-Main renderer component subscribing to actor signals and dynamically rendering catalog components:
+// 2. Define the component registry with action handlers
+const registryResult = defineRegistry(myCatalog, {
+	components: { Login, Dashboard },
+	actions: {
+		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
+});
 
-```typescript
-interface PlayRendererProps {
-	actor: AbstractActor<AnyActorLogic> & Viewable;
-	components: Record<string, React.ElementType>;
-	fallback?: React.ReactNode;
+// 3. Render — signals drive view transitions automatically
+function App() {
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
 }
 ```
 
-**Props:**
-
-- `actor` - Actor instance with `currentView` signal
-- `components` - Map of component names to React components
-- `fallback` - Component shown when `currentView` is null (default: `null`)
-
-**Behavior:**
+### With optional `JSONUIProvider` props
 
-1. Subscribes to `actor.currentView` signal via `useSignalEffect`
-2. Looks up component from `components` map using `view.component` string
-3. Renders component with props from `view.props` + `send` function
+Pass navigation and validation helpers through `PlayUIProvider`:
 
-**Example:**
-
-```typescript
-<PlayRenderer
+```tsx
+<PlayUIProvider
 	actor={actor}
-	components={{
-		HomePage: ({ send }) => <div>Home</div>,
-		AboutPage: ({ send }) => <div>About</div>,
-	}}
-	fallback={<div>Loading...</div>}
-/>
-```
-
-### useSignalEffect()
-
-Hook for subscribing to signal changes with automatic cleanup:
-
-```typescript
-useSignalEffect(() => {
-	const value = signal.get();
-	// React re-renders when signal changes
-});
+	registryResult={registryResult}
+	navigate={(path) => router.push(path)}
+	validationFunctions={{ isEmail: (v) => /^.+@.+$/.test(String(v)) }}
+>
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
-**Behavior:**
-
-- Tracks signal dependencies automatically via `Signal.Computed` wrapper
-- Uses `Signal.subtle.Watcher` with microtask batching
-- Triggers React state update to force re-render
-- Cleans up watcher on unmount with explicit `unwatch`
-
-**Canonical watcher lifecycle:**
-
-1. `notify`
-2. `queueMicrotask`
-3. drain pending work (`getPending` and/or `Computed.get`)
-4. run effect + trigger render
-5. re-arm watcher via `watch()`
+### Escape hatch — custom provider composition
 
-Watcher notification is one-shot, so re-arm and explicit cleanup are both required.
+Use `ActorProvider` directly when you need to compose providers manually:
 
-**Example:**
-
-```typescript
-import { useSignalEffect } from "@xmachines/play-react";
-import { useState } from "react";
-
-function RouteDisplay({ actor }: { actor: AbstractActor<any> }) {
-	const [route, setRoute] = useState<string | null>(null);
-
-	useSignalEffect(() => {
-		const currentRoute = actor.currentRoute.get();
-		setRoute(currentRoute);
-	});
+```tsx
+import { ActorProvider, JSONUIProvider, PlayRenderer } from "@xmachines/play-react";
 
-	return <div>Current Route: {route ?? "None"}</div>;
-}
+<ActorProvider actor={actor} registryResult={registryResult}>
+	<JSONUIProvider registry={registryResult.registry}>
+		<PlayRenderer />
+	</JSONUIProvider>
+</ActorProvider>;
 ```
 
-### PlayErrorBoundary
-
-React class component error boundary for catching catalog component render errors.
+### Accessing the actor from inside the tree
 
-`PlayRenderer` wraps its render output in `PlayErrorBoundary` automatically. You can also use it directly to wrap any component that may throw during render.
+```tsx
+import { useActor } from "@xmachines/play-react";
 
-```typescript
-interface PlayErrorBoundaryProps {
-	fallback?: React.ReactNode; // UI shown when a child throws (default: null)
-	children: React.ReactNode;
-	onError?: (error: Error, info: React.ErrorInfo) => void; // Forward to Sentry, Datadog, etc.
+function SubmitButton() {
+	const actor = useActor();
+	return <button onClick={() => actor.send({ type: "SUBMIT" })}>Submit</button>;
 }
 ```
 
-**Props:**
-
-- `fallback` — ReactNode rendered when a child component throws. Defaults to `null`.
-- `onError` — Optional callback forwarded on every caught error. Use for production observability (Sentry, Datadog, custom logging).
-
-**Example:**
+### Subscribing to signals directly
 
 ```tsx
-import { PlayErrorBoundary } from "@xmachines/play-react";
-
-<PlayErrorBoundary
-	fallback={<div className="error">Something went wrong.</div>}
-	onError={(error) => Sentry.captureException(error)}
->
-	<YourCatalogComponent />
-</PlayErrorBoundary>;
-```
-
-Works with React 18 and React 19. Uses the standard class component `componentDidCatch` + `getDerivedStateFromError` pattern.
-
-**Complete API:** See [API Documentation](../../docs/api/@xmachines/play-react)
-
-## Examples
-
-### Component Receiving Props from Catalog
-
-```typescript
-import { PlayRenderer } from "@xmachines/play-react";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { z } from "zod";
-
-// Define schema in catalog
-const catalog = defineCatalog({
-	UserProfile: z.object({
-		userId: z.string(),
-		name: z.string(),
-		avatar: z.string().url().optional(),
-		stats: z.object({
-			posts: z.number(),
-			followers: z.number(),
-		}),
-	}),
-});
-
-// Component receives type-safe props + send
-const components = {
-	UserProfile: ({ userId, name, avatar, stats, send }) => (
-		<div>
-			{avatar && <img src={avatar} alt={name} />}
-			<h1>{name}</h1>
-			<p>ID: {userId}</p>
-			<div>
-				<span>{stats.posts} posts</span>
-				<span>{stats.followers} followers</span>
-			</div>
-			<button
-				onClick={() =>
-					send({
-						type: "profile.edit",
-						userId,
-					})
-				}
-			>
-				Edit Profile
-			</button>
-		</div>
-	),
-};
-
-<PlayRenderer actor={actor} components={components} />;
-```
-
-### useSignalEffect for Custom Rendering
-
-```typescript
 import { useSignalEffect } from "@xmachines/play-react";
-import { AbstractActor } from "@xmachines/play-actor";
 
-function CustomRenderer({ actor }: { actor: AbstractActor<any> }) {
+function MyComponent({ actor }) {
 	const [view, setView] = useState(null);
 
-	// Subscribe to currentView signal
 	useSignalEffect(() => {
-		const currentView = actor.currentView.get();
-		setView(currentView);
-	});
-
-	if (!view) return <div>No view</div>;
+		setView(actor.currentView.get());
+	}, [actor]); // deps: re-subscribe when the actor prop swaps
 
-	// Custom rendering logic
-	if (view.component === "SpecialCase") {
-		return <SpecialCaseComponent {...view.props} actor={actor} />;
-	}
-
-	// Fallback to standard rendering
-	return <DefaultComponent view={view} actor={actor} />;
+	return <div>{view?.component}</div>;
 }
 ```
 
-### Provider Pattern
-
-```typescript
-import { PlayTanStackRouterProvider } from "@xmachines/play-tanstack-react-router";
-import { PlayRenderer } from "@xmachines/play-react";
-
-// Renderer receives actor via props (not children)
-function App() {
-	return (
-		<PlayTanStackRouterProvider
-			actor={actor}
-			router={router}
-			renderer={(currentActor, currentRouter) => {
-				void currentRouter;
-				return (
-				<div>
-					<Header actor={currentActor} />
-					<PlayRenderer actor={currentActor} components={components} />
-					<Footer />
-				</div>
-				);
-			}}
-		/>
-	);
-}
-
-// Header component also receives actor
-function Header({ actor }: { actor: AbstractActor<any> }) {
-	const [route, setRoute] = useState<string | null>(null);
-
-	useSignalEffect(() => {
-		setRoute(actor.currentRoute.get());
-	});
-
-	return (
-		<header>
-			<nav>Current: {route}</nav>
-		</header>
-	);
-}
+## API Summary
+
+### Components
+
+| Export                | Description                                                                                                                             |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `<PlayUIProvider>`    | Batteries-included provider: wraps `ActorProvider` + `JSONUIProvider`. Standard entry point.                                            |
+| `<PlayRenderer>`      | Zero-prop leaf component. Reads the current actor view from context and renders it. Must be inside `PlayUIProvider` or `ActorProvider`. |
+| `<ActorProvider>`     | Escape-hatch primitive. Owns actor bridging, signal subscription, and per-view `StateStore` lifecycle.                                  |
+| `<PlayErrorBoundary>` | React class error boundary for catching catalog component render errors.                                                                |
+
+### Hooks
+
+| Export                             | Description                                                                                                                                                                                                                          |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useSignalEffect(callback, deps?)` | Subscribes to TC39 signal changes; re-runs the callback when any accessed signal changes (re-render via the callback's own setState). Optional `deps` recreates the subscription, like `useEffect`. Cleanup is automatic on unmount. |
+| `useActor()`                       | Returns the raw actor instance. Must be called inside an `ActorProvider`/`PlayUIProvider` tree.                                                                                                                                      |
+| `usePlayView()`                    | Returns `{ spec, handlers, registry, store }` for the current view. Must be called inside an `ActorProvider`/`PlayUIProvider` tree.                                                                                                  |
+
+### Types
+
+| Export                   | Description                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------------- |
+| `PlayUIProviderProps`    | Props for `<PlayUIProvider>`                                                                   |
+| `ActorProviderProps`     | Props for `<ActorProvider>` (also exported as `PlayRendererProps` for migration compatibility) |
+| `PlayErrorBoundaryProps` | Props for `<PlayErrorBoundary>`                                                                |
+| `PlayErrorBoundaryState` | State shape for `<PlayErrorBoundary>`                                                          |
+| `AnyPlayActor`           | Type alias for `AbstractActor<AnyActorLogic>` — the bare actor type used by context providers  |
+| `ViewContextValue`       | Value shape returned by `usePlayView()`                                                        |
+| `RenderErrorHandler`     | Error handler callback type for render errors                                                  |
+
+### Re-exports from `@xmachines/json-render-react`
+
+`@xmachines/play-react` re-exports the full `@xmachines/json-render-react` surface so consumers only need one import:
+
+```ts
+import {
+	defineRegistry,
+	useBoundProp,
+	JSONUIProvider,
+	StateProvider,
+	ActionProvider,
+	VisibilityProvider,
+	ValidationProvider,
+	Renderer,
+} from "@xmachines/play-react";
 ```
 
-## Architecture
-
-This package implements **Signal-Only Reactivity (INV-05)** and **Passive Infrastructure (INV-04)**:
-
-1. **No Business Logic in React:**
-    - No useState/useReducer for business state
-    - No useEffect for side effects
-    - React only triggers renders, doesn't control state
+## Key Principle
 
-2. **Signals as Source of Truth:**
-    - `actor.currentView.get()` provides UI structure
-    - `actor.currentRoute.get()` provides navigation state
-    - Components observe signals via `useSignalEffect`
+React state is **never** used for business logic — only for triggering React's render cycle. Signals (`@xmachines/play-signals`) are the source of truth. `PlayUIProvider` passively observes actor signals via `useSignalEffect` and re-renders when the current view changes. Rapid signal updates are batched via microtasks to prevent unnecessary React renders.
 
-3. **Event Forwarding:**
-    - Components receive `send` function via props
-    - User actions send events to actor (e.g., `{ type: "auth.login" }`)
-    - Actor guards validate and process events
+## Testing
 
-4. **Microtask Batching:**
-    - `Signal.subtle.Watcher` coalesces rapid signal changes
-    - Prevents React thrashing from multiple signal updates
-    - Single React render per microtask batch
+Run unit tests (jsdom environment):
 
-5. **Explicit Disposal Contract:**
-    - Component teardown must call watcher `unwatch` in cleanup
-    - Do not rely on GC-only cleanup
-
-**Pattern:**
-
-- Renderer receives actor via props (provider pattern)
-- Enables composition with navigation, headers, footers
-- Supports multiple renderers in same app
-
-**Architectural Invariants:**
+```bash
+pnpm --filter @xmachines/play-react test
+```
 
-- **Signal-Only Reactivity (INV-05):** No React state for business logic
-- **Passive Infrastructure (INV-04):** Components reflect, never decide
+Run tests with coverage:
 
-## Benefits
+```bash
+pnpm --filter @xmachines/play-react run test:coverage
+```
 
-- **Framework Swappable:** Business logic has zero React imports
-- **Type Safety:** Props validated against catalog schemas
-- **Simple Testing:** Test actors without React renderer
-- **Performance:** Microtask batching reduces unnecessary renders
-- **Composability:** Renderer prop enables complex layouts ()
+Run browser integration tests (requires Chromium):
 
-## Related Packages
+```bash
+pnpm --filter @xmachines/play-react run test:browser
+```
 
-- **[@xmachines/play-xstate](../play-xstate)** - XState adapter providing actors
-- **[@xmachines/play-catalog](../play-catalog)** - UI schema validation
-- **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router)** - TanStack Router integration
-- **[@xmachines/play-actor](../play-actor)** - Actor base
-- **[@xmachines/play-signals](../play-signals)** - TC39 Signals primitives
+Coverage thresholds: 80% lines, functions, branches, and statements.
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+MIT — see [LICENSE](./LICENSE).

package/dist/ActorProvider.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ActorProvider — escape hatch primitive for actor lifecycle management.
+ *
+ * Owns: actor bridging, signal subscription (useSignalEffect), per-view StateStore
+ * lifecycle (controlled/uncontrolled), handler resolution via inner component pattern
+ * (uses useStateStore()), StateProvider wrap, PlayErrorBoundary wrap, onRenderError injection.
+ *
+ * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+import type { DefineRegistryResult, ComponentRegistry } from "@xmachines/json-render-react";
+import { type BaseActorProviderProps, type BaseViewContextValue } from "@xmachines/play-actor";
+/**
+ * Props for the ActorProvider component.
+ *
+ * @public
+ */
+export interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+    /** Optional component shown when currentView is null or a catalog component throws */
+    fallback?: React.ReactNode;
+    /** Optional error handler callback invoked when a catalog component throws during render */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+    /** Child components to render inside the provider tree */
+    children: React.ReactNode;
+}
+/**
+ * Value provided by ViewContext (accessible via usePlayView()).
+ *
+ * @public
+ */
+export interface ViewContextValue extends BaseViewContextValue<ComponentRegistry> {
+}
+/**
+ * Hook to access the current view spec, handlers, and registry.
+ *
+ * Must be called inside <ActorProvider> or <PlayUIProvider>.
+ *
+ * @throws {Error} If called outside an ActorProvider/PlayUIProvider tree
+ *
+ * @example
+ * ```typescript
+ * import { usePlayView } from "@xmachines/play-react";
+ *
+ * function MyRenderer() {
+ *   const view = usePlayView();
+ *   return <Renderer spec={view.spec} registry={view.registry} />;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function usePlayView(): ViewContextValue;
+/**
+ * ActorProvider — escape hatch primitive for composing actor lifecycle with custom providers.
+ *
+ * Subscribes to actor.currentView signal, manages the per-view StateStore lifecycle,
+ * wraps children in StateProvider and PlayErrorBoundary, and injects onRenderError
+ * into the component registry.
+ *
+ * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ *
+ * @example
+ * ```tsx
+ * // Custom composition (escape hatch):
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ *
+ * // Standard usage: prefer PlayUIProvider
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * @public
+ */
+export declare const ActorProvider: React.FC<ActorProviderProps>;
+//# sourceMappingURL=ActorProvider.d.ts.map

package/dist/ActorProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActorProvider.d.ts","sourceRoot":"","sources":["../src/ActorProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAA+D,MAAM,OAAO,CAAC;AAEpF,OAAO,KAAK,EACX,oBAAoB,EAEpB,iBAAiB,EACjB,MAAM,8BAA8B,CAAC;AAOtC,OAAO,EAIN,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,MAAM,uBAAuB,CAAC;AAI/B;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB,CAAC,oBAAoB,CAAC;IACvF,sFAAsF;IACtF,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,4FAA4F;IAC5F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;IACxD,0DAA0D;IAC1D,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;CAAG;AAQpF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,IAAI,gBAAgB,CAE9C;AA0ED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAqFtD,CAAC"}