@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-solid/README.md

@@ -1,311 +1,274 @@
-[Documentation](../../README.md) / @xmachines/play-solid
+[API](../../README.md) / @xmachines/play-solid
 
 # @xmachines/play-solid
 
-**SolidJS renderer consuming signals and UI schema with provider pattern**
+> Solid renderer for XMachines Play architecture
 
-Signal-driven SolidJS rendering layer observing actor state with zero SolidJS state for business logic.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-solid)
 
-## Overview
+SolidJS rendering layer that passively observes actor signals and renders UI components via `@xmachines/json-render-solid`. SolidJS reactivity is used solely to trigger re-renders — TC39 Signals are the source of truth.
 
-`@xmachines/play-solid` provides `PlayRenderer` for building SolidJS UIs that passively observe actor signals. This package enables framework-swappable architecture where SolidJS is just a rendering target subscribing to signal changes — business logic lives entirely in the actor.
-
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
-
-- **Signal-Only Reactivity (INV-05):** No createSignal/createStore for business logic, TC39 signals only
-- **Passive Infrastructure (INV-04):** Components observe signals, send events to actor
-
-**Key Principle:** SolidJS state is never used for business logic. Signals are the source of truth.
-
-Renderer receives actor via props (provider pattern), not children.
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
 ```bash
-npm install solid-js@^1.8.0
-npm install @xmachines/play-solid
+pnpm add @xmachines/play-solid
 ```
 
-## Current Exports
+**Peer dependencies** — install alongside the package:
 
-- `PlayRenderer`
-- `PlayRendererProps` (type)
-
-**Peer dependencies:**
-
-- `solid-js` ^1.8.0 - SolidJS runtime
+```bash
+pnpm add solid-js xstate @xstate/store @xmachines/json-render-solid @xmachines/json-render-core @xmachines/json-render-xstate
+```
 
 ## Quick Start
 
 ```tsx
-import { render } from "solid-js/web";
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
 import { definePlayer } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { PlayRenderer } from "@xmachines/play-solid";
-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(),
-	}),
+import { defineCatalog } from "@xmachines/json-render-core";
+import { schema } from "@xmachines/json-render-solid/schema";
+
+// 1. Define a catalog (authCatalogDef is a plain object describing components/actions)
+const catalog = defineCatalog(schema, authCatalogDef);
+
+// 2. Build a component registry
+const registryResult = defineRegistry(catalog, {
+	components: {
+		Home: () => <div>Welcome home!</div>,
+		Login: (ctx) => <div>Login {ctx.props.error && <span>{ctx.props.error}</span>}</div>,
+	},
+	actions: {
+		login: async (args) => actor.send({ type: "auth.login", username: args.username }),
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
 });
 
-// 2. Create SolidJS components (view layer)
-const components = {
-	LoginForm: (props) => (
-		<form
-			onSubmit={(e) => {
-				e.preventDefault();
-				const data = new FormData(e.currentTarget);
-				props.send({
-					type: "auth.login",
-					username: data.get("username"),
-				});
-			}}
-		>
-			{props.error && <p style={{ color: "red" }}>{props.error}</p>}
-			<input name="username" required placeholder="Username" />
-			<button type="submit">Log In</button>
-		</form>
-	),
-	Dashboard: (props) => (
-		<div>
-			<h1>Welcome, {props.username}!</h1>
-			<p>User ID: {props.userId}</p>
-			<button onClick={() => props.send({ type: "auth.logout" })}>Log Out</button>
-		</div>
-	),
-};
-
-// 3. Create player actor (business logic runtime)
-const createPlayer = definePlayer({ machine: authMachine, catalog });
+// 3. Create and start an actor
+const createPlayer = definePlayer({ machine: myMachine });
 const actor = createPlayer();
 actor.start();
 
-// 4. Render UI (actor via props)
-render(
-	() => <PlayRenderer actor={actor} components={components} />,
-	document.getElementById("app")!,
-);
-```
-
-## API Reference
-
-### PlayRenderer
-
-Main renderer component subscribing to actor signals and dynamically rendering catalog components:
-
-```typescript
-interface PlayRendererProps {
-	actor: AbstractActor<any>;
-	components: Record<string, Component<any>>;
-	fallback?: JSX.Element;
+// 4. Render
+function App() {
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
 }
 ```
 
-**Props:**
-
-- `actor` - Actor instance with `currentView` signal
-- `components` - Map of component names to SolidJS components
-- `fallback` - Component shown when `currentView` is null
+## Usage
 
-**Behavior:**
+### `PlayUIProvider` + `PlayRenderer` (recommended)
 
-1. Subscribes to `actor.currentView` signal using a `Signal.subtle.Watcher` inside the component
-2. Looks up component from `components` map using `view.component` string
-3. Renders component with props from `view.props` + `send` function using Solid's `<Dynamic />`
-
-**Example:**
+`PlayUIProvider` is the batteries-included entry point. It wraps `ActorProvider` and `JSONUIProvider` into a single composite provider. `PlayRenderer` is a zero-prop leaf component that reads view context and renders the current spec.
 
 ```tsx
-<PlayRenderer
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
+
+<PlayUIProvider
 	actor={actor}
-	components={{
-		HomePage: (props) => <div>Home</div>,
-		AboutPage: (props) => <div>About</div>,
-	}}
-	fallback={<div>Loading...</div>}
-/>
+	registryResult={registryResult}
+	fallback={<div>Loading…</div>}
+	onError={(err) => console.error(err)}
+	navigate={navigateFn} // optional: passed to JSONUIProvider
+	validationFunctions={valFns} // optional: form validation helpers
+>
+	<PlayRenderer />
+</PlayUIProvider>;
 ```
 
-## Examples
+### `ActorProvider` (escape hatch)
 
-### Component Receiving Props from Catalog
+For library authors who need direct control over provider composition:
 
 ```tsx
-import { PlayRenderer } from "@xmachines/play-solid";
-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(),
-		}),
-	}),
-});
+import { ActorProvider, PlayRenderer } from "@xmachines/play-solid";
 
-// Component receives type-safe props + send
-const components = {
-	UserProfile: (props) => (
-		<div>
-			{props.avatar && <img src={props.avatar} alt={props.name} />}
-			<h1>{props.name}</h1>
-			<p>ID: {props.userId}</p>
-			<div>
-				<span>{props.stats.posts} posts</span>
-				<span>{props.stats.followers} followers</span>
-			</div>
-			<button
-				onClick={() =>
-					props.send({
-						type: "profile.edit",
-						userId: props.userId,
-					})
-				}
-			>
-				Edit Profile
-			</button>
-		</div>
-	),
-};
-
-<PlayRenderer actor={actor} components={components} />;
+<ActorProvider actor={actor} registryResult={registryResult}>
+	<PlayRenderer />
+</ActorProvider>;
 ```
 
-### Provider Pattern
+### `useActor` hook
+
+Access the raw actor instance anywhere inside an `ActorProvider` or `PlayUIProvider` tree:
 
 ```tsx
-import { PlayTanStackRouterProvider } from "@xmachines/play-tanstack-solid-router";
-import { PlayRenderer } from "@xmachines/play-solid";
-import { createSignal, onCleanup } from "solid-js";
+import { useActor } from "@xmachines/play-solid";
 
-// Renderer receives actor via props (not children)
-function App() {
-	return (
-		<PlayTanStackRouterProvider
-			actor={actor}
-			router={router}
-			routeMap={routeMap}
-			renderer={(currentActor, currentRouter) => {
-				return (
-					<div>
-						<Header actor={currentActor} />
-						<PlayRenderer actor={currentActor} components={components} />
-						<Footer />
-					</div>
-				);
-			}}
-		/>
-	);
+function SubmitButton() {
+	const actor = useActor();
+	return <button onClick={() => actor.send({ type: "SUBMIT" })}>Submit</button>;
 }
+```
 
-// Header component also receives actor
-function Header(props) {
-	const [route, setRoute] = createSignal<string | null>(null);
+### `usePlayView` hook
 
-	// Manual watcher setup for custom component reading signals
-	let watcher: Signal.subtle.Watcher;
+Access the resolved view context (spec, handlers, registry, store) from within the provider tree:
 
-	// ... setup watcher to update route signal ...
+```tsx
+import { usePlayView } from "@xmachines/play-solid";
+import { Renderer } from "@xmachines/json-render-solid";
 
-	return (
-		<header>
-			<nav>Current: {route()}</nav>
-		</header>
-	);
-}
+const MyRenderer = () => {
+	const view = usePlayView();
+	return <Renderer spec={view.spec} registry={view.registry} />;
+};
 ```
 
-## Architecture
+## API Summary
 
-This package implements **Signal-Only Reactivity (INV-05)** and **Passive Infrastructure (INV-04)**:
+### Components
 
-1. **No Business Logic in SolidJS:**
-    - No createSignal/createStore for business state
-    - No createEffect for business side effects
-    - SolidJS only triggers renders, doesn't control state
+| Export           | Description                                                                    |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `PlayUIProvider` | Batteries-included composite provider (recommended entry point)                |
+| `PlayRenderer`   | Zero-prop leaf component; renders the current view spec inside a provider tree |
+| `ActorProvider`  | Lower-level smart provider for escape-hatch composition                        |
 
-2. **Signals as Source of Truth:**
-    - `actor.currentView.get()` provides UI structure
-    - `actor.currentRoute.get()` provides navigation state
-    - Components observe signals via explicit watcher patterns
+### Hooks
 
-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
+| Export          | Description                                                                                   |
+| --------------- | --------------------------------------------------------------------------------------------- |
+| `useActor()`    | Returns the raw `AnyPlayActor` instance from context; throws outside a provider tree          |
+| `usePlayView()` | Returns the current `ViewContextValue` (spec, handlers, registry, store); throws outside tree |
 
-4. **Microtask Batching:**
-    - `Signal.subtle.Watcher` coalesces rapid signal changes
-    - Prevents SolidJS thrashing from multiple signal updates
-    - Single SolidJS render per microtask batch
+### Context
 
-5. **Explicit Disposal Contract:**
-    - Component teardown calls watcher `unwatch` in `onCleanup`
-    - Do not rely on GC-only cleanup
+| Export         | Description                                                                            |
+| -------------- | -------------------------------------------------------------------------------------- |
+| `ActorContext` | SolidJS context for the actor; use `ActorContext.Provider` directly as an escape hatch |
 
-**Pattern:**
+### Re-exports from `@xmachines/json-render-solid`
 
-- Renderer receives actor via props (provider pattern)
-- Enables composition with navigation, headers, footers
-- Supports multiple renderers in same app
+This package re-exports the full `@xmachines/json-render-solid` public API so consumers do not need a direct dependency:
 
-**Architectural Invariants:**
-
-- **Signal-Only Reactivity (INV-05):** No SolidJS state for business logic
-- **Passive Infrastructure (INV-04):** Components reflect, never decide
+```tsx
+import {
+	// Providers
+	JSONUIProvider,
+	StateProvider,
+	ActionProvider,
+	VisibilityProvider,
+	ValidationProvider,
+	// Renderer
+	Renderer,
+	// Registry factory + hooks
+	defineRegistry,
+	useBoundProp,
+	useStateBinding,
+	useStateValue,
+	useStateStore,
+	useActions,
+	useAction,
+	useIsVisible,
+	useFieldValidation,
+	useOptionalValidation,
+	useVisibility,
+} from "@xmachines/play-solid";
+```
 
-## Canonical Watcher Lifecycle
+### Key Types
 
-If you write your own custom integration, use the same watcher flow as `PlayRenderer`:
+| Type                  | Description                                                                    |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `PlayUIProviderProps` | Props for `PlayUIProvider`                                                     |
+| `ActorProviderProps`  | Props for `ActorProvider`                                                      |
+| `ViewContextValue`    | Shape of the context value from `usePlayView()`                                |
+| `AnyPlayActor`        | `AbstractActor<AnyActorLogic>` — bare actor type accepted by context providers |
 
-1. `notify` callback runs
-2. Schedule work with `queueMicrotask`
-3. Drain `watcher.getPending()`
-4. Read actor signals and update SolidJS-local signal state (`setSignal()`)
-5. Re-arm with `watch(...)` or `watch()`
+## Testing
 
-Watcher notify is one-shot. Re-arm is required for continuous observation.
+Run tests for this package in isolation:
 
-## Benefits
+```bash
+pnpm --filter @xmachines/play-solid test
+```
 
-- **Framework Swappable:** Business logic has zero SolidJS imports
-- **Type Safety:** Props validated against catalog schemas
-- **Simple Testing:** Test actors without SolidJS renderer
-- **Performance:** Microtask batching reduces unnecessary renders
-- **Composability:** Renderer prop enables complex layouts
+Or from within the package directory:
 
-## Related Packages
+```bash
+pnpm test          # single run (jsdom environment)
+pnpm run test:watch  # watch mode
+pnpm run test:ui     # interactive Vitest UI
+```
 
-- **[@xmachines/play-xstate](../play-xstate/README.md)** - XState adapter providing actors
-- **[@xmachines/play-catalog](../play-catalog/README.md)** - UI schema validation
-- **[@xmachines/play-solid-router](../play-solid-router/README.md)** - Solid Router integration
-- **[@xmachines/play-tanstack-solid-router](../play-tanstack-solid-router/README.md)** - TanStack Solid Router integration
-- **[@xmachines/play-actor](../play-actor/README.md)** - Actor base
-- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals primitives
+Coverage is collected with v8 (80% threshold for lines, functions, branches, and statements). Browser-specific tests live in `test/browser/` and are excluded from the default jsdom run.
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+MIT
+
+@xmachines/play-solid - SolidJS renderer for XMachines Play architecture
+
+Provides a SolidJS rendering layer that passively observes actor signals and
+renders UI components via @xmachines/json-render-solid. SolidJS reactivity is only used
+to trigger re-renders — signals are the source of truth.
 
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+Primary entry point:
 
-SolidJS renderer for XMachines Play architecture
+```tsx
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
+```
+
+For escape-hatch provider composition:
+
+```tsx
+import { ActorProvider, ActorContext, usePlayView } from "@xmachines/play-solid";
+```
 
 ## Interfaces
 
-- [PlayRendererProps](interfaces/PlayRendererProps.md)
+- [ActionProviderProps](interfaces/ActionProviderProps.md)
+- [ActorProviderProps](interfaces/ActorProviderProps.md)
+- [ComponentContext](interfaces/ComponentContext.md)
+- [DefineRegistryResult](interfaces/DefineRegistryResult.md)
+- [JSONUIProviderProps](interfaces/JSONUIProviderProps.md)
+- [PlayUIProviderProps](interfaces/PlayUIProviderProps.md)
+- [RendererProps](interfaces/RendererProps.md)
+- [StateProviderProps](interfaces/StateProviderProps.md)
+- [ValidationProviderProps](interfaces/ValidationProviderProps.md)
+- [ViewContextValue](interfaces/ViewContextValue.md)
+
+## Type Aliases
+
+- [AnyPlayActor](type-aliases/AnyPlayActor.md)
+- [ComponentFn](type-aliases/ComponentFn.md)
+- [ComponentRegistry](type-aliases/ComponentRegistry.md)
+- [RenderErrorHandler](type-aliases/RenderErrorHandler.md)
+- [SetState](type-aliases/SetState.md)
+- [VisibilityProviderProps](type-aliases/VisibilityProviderProps.md)
 
 ## Variables
 
+- [ActorContext](variables/ActorContext.md)
+- [ActorProvider](variables/ActorProvider.md)
 - [PlayRenderer](variables/PlayRenderer.md)
+- [PlayUIProvider](variables/PlayUIProvider.md)
+
+## Functions
+
+- [ActionProvider](functions/ActionProvider.md)
+- [defineRegistry](functions/defineRegistry.md)
+- [JSONUIProvider](functions/JSONUIProvider.md)
+- [Renderer](functions/Renderer.md)
+- [StateProvider](functions/StateProvider.md)
+- [useAction](functions/useAction.md)
+- [useActions](functions/useActions.md)
+- [useActor](functions/useActor.md)
+- [useBoundProp](functions/useBoundProp.md)
+- [useFieldValidation](functions/useFieldValidation.md)
+- [useIsVisible](functions/useIsVisible.md)
+- [useOptionalValidation](functions/useOptionalValidation.md)
+- [usePlayView](functions/usePlayView.md)
+- [useStateBinding](functions/useStateBinding.md)
+- [useStateStore](functions/useStateStore.md)
+- [useStateValue](functions/useStateValue.md)
+- [useVisibility](functions/useVisibility.md)
+- [ValidationProvider](functions/ValidationProvider.md)
+- [VisibilityProvider](functions/VisibilityProvider.md)

package/api/@xmachines/play-solid/functions/ActionProvider.md

@@ -0,0 +1,19 @@
+[API](../../../README.md) / [@xmachines/play-solid](../README.md) / ActionProvider
+
+# Function: ActionProvider()
+
+```ts
+function ActionProvider(props): any;
+```
+
+Defined in: `@xmachines/json-render-solid`
+
+## Parameters
+
+| Parameter | Type                                                                           |
+| --------- | ------------------------------------------------------------------------------ |
+| `props`   | `ParentProps`\<[`ActionProviderProps`](../interfaces/ActionProviderProps.md)\> |
+
+## Returns
+
+`any`

package/api/@xmachines/play-solid/functions/JSONUIProvider.md

@@ -0,0 +1,21 @@
+[API](../../../README.md) / [@xmachines/play-solid](../README.md) / JSONUIProvider
+
+# Function: JSONUIProvider()
+
+```ts
+function JSONUIProvider(props): any;
+```
+
+Defined in: `@xmachines/json-render-solid`
+
+Combined provider for all JSONUI contexts
+
+## Parameters
+
+| Parameter | Type                                                          |
+| --------- | ------------------------------------------------------------- |
+| `props`   | [`JSONUIProviderProps`](../interfaces/JSONUIProviderProps.md) |
+
+## Returns
+
+`any`

package/api/@xmachines/play-solid/functions/Renderer.md

@@ -0,0 +1,21 @@
+[API](../../../README.md) / [@xmachines/play-solid](../README.md) / Renderer
+
+# Function: Renderer()
+
+```ts
+function Renderer(props): any;
+```
+
+Defined in: `@xmachines/json-render-solid`
+
+Main renderer component
+
+## Parameters
+
+| Parameter | Type                                              |
+| --------- | ------------------------------------------------- |
+| `props`   | [`RendererProps`](../interfaces/RendererProps.md) |
+
+## Returns
+
+`any`

package/api/@xmachines/play-solid/functions/StateProvider.md

@@ -0,0 +1,19 @@
+[API](../../../README.md) / [@xmachines/play-solid](../README.md) / StateProvider
+
+# Function: StateProvider()
+
+```ts
+function StateProvider(props): any;
+```
+
+Defined in: `@xmachines/json-render-solid`
+
+## Parameters
+
+| Parameter | Type                                                                         |
+| --------- | ---------------------------------------------------------------------------- |
+| `props`   | `ParentProps`\<[`StateProviderProps`](../interfaces/StateProviderProps.md)\> |
+
+## Returns
+
+`any`

package/api/@xmachines/play-solid/functions/ValidationProvider.md

@@ -0,0 +1,19 @@
+[API](../../../README.md) / [@xmachines/play-solid](../README.md) / ValidationProvider
+
+# Function: ValidationProvider()
+
+```ts
+function ValidationProvider(props): any;
+```
+
+Defined in: `@xmachines/json-render-solid`
+
+## Parameters
+
+| Parameter | Type                                                                                   |
+| --------- | -------------------------------------------------------------------------------------- |
+| `props`   | `ParentProps`\<[`ValidationProviderProps`](../interfaces/ValidationProviderProps.md)\> |
+
+## Returns
+
+`any`

package/api/@xmachines/play-solid/functions/VisibilityProvider.md

@@ -0,0 +1,20 @@
+[API](../../../README.md) / [@xmachines/play-solid](../README.md) / VisibilityProvider
+
+# Function: VisibilityProvider()
+
+```ts
+function VisibilityProvider(props): any;
+```
+
+Defined in: `@xmachines/json-render-solid`
+
+## Parameters
+
+| Parameter         | Type                      |
+| ----------------- | ------------------------- |
+| `props`           | \{ `children?`: `any`; \} |
+| `props.children?` | `any`                     |
+
+## Returns
+
+`any`