@xmachines/docs 1.0.0-beta.10

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

@@ -0,0 +1,331 @@
+[Documentation](../../README.md) / @xmachines/play-catalog
+
+# @xmachines/play-catalog
+
+**Framework-agnostic UI schema with Zod validation for XMachines Play Architecture**
+
+Type-safe catalog defining component contracts without framework dependencies.
+
+## Overview
+
+`@xmachines/play-catalog` provides `defineCatalog()` and `defineComponents()` for creating type-safe component catalogs with Zod schema validation. It enables business logic to define component props declaratively while maintaining zero framework dependencies — components can be React, Vue, Svelte, or any other framework.
+
+Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+
+- **Strict Separation (INV-02):** Business logic has zero framework imports
+- Catalog validates prop types at state entry (build-time + runtime)
+
+## Installation
+
+```bash
+npm install zod@^4.3.6
+npm install @xmachines/play-catalog
+```
+
+## Current Exports
+
+- `defineCatalog`
+- `defineComponents`
+- types: `Catalog`, `InferComponentProps`
+
+**Peer dependencies:**
+
+- `zod` ^4.3.6 — Schema validation (you control the version)
+
+## Quick Start
+
+```typescript
+import { z } from "zod";
+import { defineCatalog } from "@xmachines/play-catalog";
+import type { InferComponentProps } from "@xmachines/play-catalog";
+
+// 1. Define catalog with Zod schemas (business logic layer)
+const catalog = defineCatalog({
+	LoginForm: z.object({
+		error: z.string().optional(),
+	}),
+	Dashboard: z.object({
+		userId: z.string(),
+		username: z.string(),
+		stats: z.object({
+			logins: z.number(),
+			lastLogin: z.date(),
+		}),
+	}),
+});
+
+// 2. TypeScript infers prop types from schemas
+type DashboardProps = InferComponentProps<typeof catalog, "Dashboard">;
+// => { userId: string; username: string; stats: { logins: number; lastLogin: Date } }
+
+// 3. Use in state machine meta.view
+const machine = setup({...}).createMachine({
+	states: {
+		dashboard: {
+			meta: {
+				route: "/dashboard",
+				view: {
+					component: "Dashboard", // Type-checked against catalog
+					props: {
+						userId: "user123",
+						username: "Alice",
+						stats: {
+							logins: 42,
+							lastLogin: new Date(),
+						},
+					},
+				},
+			},
+		},
+	},
+});
+```
+
+## API Reference
+
+### defineCatalog()
+
+Create type-safe component catalog from Zod schemas:
+
+```typescript
+const catalog = defineCatalog({
+	ComponentName: z.object({
+		/* props schema */
+	}),
+});
+```
+
+**Parameters:**
+
+- `schemas: Record<string, ZodObject>` - Map of component names to Zod schemas
+
+**Returns:** Frozen catalog object (immutable in development)
+
+**Example:**
+
+```typescript
+const catalog = defineCatalog({
+	UserProfile: z.object({
+		userId: z.string(),
+		avatar: z.string().url().optional(),
+		bio: z.string().max(500).optional(),
+	}),
+	SettingsForm: z.object({
+		theme: z.enum(["light", "dark"]),
+		notifications: z.boolean(),
+	}),
+});
+```
+
+### InferComponentProps<Catalog, Component>
+
+Utility type extracting prop types from catalog:
+
+```typescript
+type Props = InferComponentProps<typeof catalog, "ComponentName">;
+```
+
+**Example:**
+
+```typescript
+const catalog = defineCatalog({
+	Dashboard: z.object({
+		userId: z.string(),
+		data: z.array(z.number()),
+	}),
+});
+
+type DashboardProps = InferComponentProps<typeof catalog, "Dashboard">;
+// => { userId: string; data: number[] }
+
+// Use in component definition
+function Dashboard(props: DashboardProps) {
+	// props.userId is string
+	// props.data is number[]
+}
+```
+
+### defineComponents()
+
+Validate React component implementations match catalog (compile-time):
+
+```typescript
+const components = defineComponents(catalog, {
+	ComponentName: ComponentImplementation,
+});
+```
+
+**Compile-time validation:**
+
+- Component names must exist in catalog
+- Component prop types must match schema-inferred types
+
+**Example:**
+
+```typescript
+import { defineComponents } from "@xmachines/play-catalog";
+
+const catalog = defineCatalog({
+	LoginForm: z.object({ error: z.string().optional() }),
+	Dashboard: z.object({ userId: z.string() }),
+});
+
+const components = defineComponents(catalog, {
+	LoginForm: ({ error }) => {
+		// error is string | undefined (inferred from schema)
+		return <form>{error && <p>{error}</p>}</form>;
+	},
+	Dashboard: ({ userId }) => {
+		// userId is string (inferred from schema)
+		return <div>User: {userId}</div>;
+	},
+	// @ts-expect-error - "InvalidComponent" not in catalog
+	InvalidComponent: () => <div />,
+});
+```
+
+## Examples
+
+### Progressive Validation
+
+```typescript
+import { z } from "zod";
+import { defineCatalog } from "@xmachines/play-catalog";
+
+// Start simple
+const catalog = defineCatalog({
+	UserCard: z.object({
+		name: z.string(),
+	}),
+});
+
+// Add validation rules
+const enhancedCatalog = defineCatalog({
+	UserCard: z.object({
+		name: z.string().min(1).max(100),
+		email: z.string().email(),
+		age: z.number().int().positive().max(150),
+	}),
+});
+
+// Complex nested schemas
+const advancedCatalog = defineCatalog({
+	UserCard: z.object({
+		name: z.string().min(1),
+		email: z.string().email(),
+		profile: z.object({
+			avatar: z.string().url().optional(),
+			bio: z.string().max(500).optional(),
+			links: z.array(z.string().url()).max(5).optional(),
+		}),
+		preferences: z.object({
+			theme: z.enum(["light", "dark", "auto"]),
+			language: z.string().length(2), // ISO 639-1
+		}),
+	}),
+});
+```
+
+### Machine Integration
+
+```typescript
+import { setup } from "xstate";
+import { defineCatalog } from "@xmachines/play-catalog";
+import { z } from "zod";
+
+const catalog = defineCatalog({
+	LoginForm: z.object({ error: z.string().optional() }),
+	Dashboard: z.object({
+		userId: z.string(),
+		notifications: z.number(),
+	}),
+});
+
+const machine = setup({
+	types: {
+		context: {} as { userId: string; errorMsg: string | null },
+	},
+}).createMachine({
+	initial: "login",
+	context: { userId: "", errorMsg: null },
+	states: {
+		login: {
+			meta: {
+				view: {
+					component: "LoginForm", // Type-checked against catalog
+					props: (context) => ({
+						error: context.errorMsg ?? undefined,
+					}),
+				},
+			},
+			on: {
+				"auth.login": {
+					target: "dashboard",
+					actions: assign({ userId: ({ event }) => event.userId }),
+				},
+			},
+		},
+		dashboard: {
+			meta: {
+				view: {
+					component: "Dashboard",
+					props: (context) => ({
+						userId: context.userId,
+						notifications: 5, // Hardcoded for example
+					}),
+				},
+			},
+		},
+	},
+});
+```
+
+## Architecture
+
+This package enforces **Strict Separation (INV-02)**:
+
+1. **Zero Framework Dependencies:**
+    - Catalog definition has no React/Vue/Svelte imports
+    - Business logic stays framework-agnostic
+    - Same catalog works with any renderer
+
+2. **Validation at State Entry:**
+    - Zod validates props when actor enters state
+    - Invalid props trigger validation error (catchable)
+    - Build-time + runtime safety
+
+3. **Compile-Time Type Safety:**
+    - TypeScript infers prop types from Zod schemas
+    - Component implementations type-checked at compile time
+    - Refactoring propagates through catalog and components
+
+**Benefits:**
+
+- Swap React for Vue without changing business logic
+- Test catalog validation without framework overhead
+- Framework updates don't affect business logic
+
+## Related Packages
+
+- **[@xmachines/play-xstate](../play-xstate/README.md)** - XState adapter using catalogs
+- **[@xmachines/play-react](../play-react/README.md)** - React renderer consuming catalogs
+- **[@xmachines/play](../play/README.md)** - Protocol types
+
+## 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>.
+
+## Type Aliases
+
+- [Catalog](type-aliases/Catalog.md)
+- [ComponentsFor](type-aliases/ComponentsFor.md)
+- [InferComponentProps](type-aliases/InferComponentProps.md)
+- [NoExtraKeys](type-aliases/NoExtraKeys.md)
+
+## Functions
+
+- [defineCatalog](functions/defineCatalog.md)
+- [defineComponents](functions/defineComponents.md)

package/api/@xmachines/play-catalog/functions/defineCatalog.md

@@ -0,0 +1,98 @@
+[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / defineCatalog
+
+# Function: defineCatalog()
+
+```ts
+function defineCatalog<TCatalog>(schemas): TCatalog;
+```
+
+Defined in: [define-catalog.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/define-catalog.ts#L74)
+
+Define component catalog with Zod schemas for type-safe UI projection
+
+Creates a catalog mapping component names to their prop schemas using Zod validators.
+The catalog enables **Strict Separation (INV-02)** by defining UI vocabulary in
+framework-agnostic terms that the Actor can reference without coupling to React/Vue/etc.
+
+**Architectural Context:** Implements **Strict Separation (INV-02)** where business
+logic (state machine) has zero framework imports. The catalog serves as the contract
+between Actor (which references component names in `meta.view`) and Infrastructure
+(which renders actual framework components).
+
+## Type Parameters
+
+| Type Parameter                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------- |
+| `TCatalog` _extends_ `Record`\<`string`, `ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\> |
+
+## Parameters
+
+| Parameter | Type       | Description                                   |
+| --------- | ---------- | --------------------------------------------- |
+| `schemas` | `TCatalog` | Record mapping component names to Zod schemas |
+
+## Returns
+
+`TCatalog`
+
+Typed catalog object with schema entries (frozen in development for immutability)
+
+## Examples
+
+Basic catalog definition
+
+```typescript
+import { z } from "zod";
+import { defineCatalog } from "@xmachines/play-catalog";
+
+const catalog = defineCatalog({
+	Dashboard: z.object({ userId: z.string() }),
+	LoginForm: z.object({ error: z.string().optional() }),
+});
+
+// TypeScript infers catalog type automatically
+type CatalogType = typeof catalog;
+```
+
+Progressive catalog with multiple components
+
+```typescript
+import { z } from "zod";
+import { defineCatalog } from "@xmachines/play-catalog";
+
+const catalog = defineCatalog({
+	// Public pages
+	HomePage: z.object({}),
+	AboutPage: z.object({}),
+
+	// Auth components
+	LoginForm: z.object({
+		error: z.string().optional(),
+		returnUrl: z.string().optional(),
+	}),
+
+	// Protected pages
+	Dashboard: z.object({
+		userId: z.string(),
+		stats: z.object({
+			views: z.number(),
+			clicks: z.number(),
+		}),
+	}),
+});
+```
+
+## See
+
+- [RFC Play v1 - Invariant INV-02](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [defineComponents](defineComponents.md) for binding components to catalog
+- [Catalog](../type-aliases/Catalog.md) for the catalog type definition
+
+## Remarks
+
+**Primary Purpose:** Type inference. The returned catalog object is primarily used
+for TypeScript type inference. Runtime validation happens at state entry when the
+Actor attempts to project a view through the renderer.
+
+**Immutability:** In development mode, the catalog is frozen via `Object.freeze()`
+to prevent accidental mutation. In production, freezing is skipped for performance.

package/api/@xmachines/play-catalog/functions/defineComponents.md

@@ -0,0 +1,134 @@
+[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / defineComponents
+
+# Function: defineComponents()
+
+```ts
+function defineComponents<TCatalog, TComponents>(
+	catalog,
+	components,
+): NoExtraKeys<TComponents, TCatalog>;
+```
+
+Defined in: [define-components.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/define-components.ts#L116)
+
+Define components matching catalog schema with compile-time validation
+
+Enforces bidirectional validation between catalog and component implementations:
+
+- All catalog keys must have corresponding components (no missing components)
+- No extra components outside catalog (no undefined keys)
+- TypeScript compilation fails for mismatches (build-time safety)
+
+**Architectural Context:** Implements **Strict Separation (INV-02)** by validating
+that framework components (React/Vue/etc.) exactly match the framework-agnostic
+catalog that the Actor references. This ensures the Actor can reference component
+names in `meta.view` without importing framework code.
+
+## Type Parameters
+
+| Type Parameter                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------- |
+| `TCatalog` _extends_ `Record`\<`string`, `ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\> |
+| `TComponents` _extends_ [`ComponentsFor`](../type-aliases/ComponentsFor.md)\<`TCatalog`\>                                 |
+
+## Parameters
+
+| Parameter    | Type                                                                         | Description                                             |
+| ------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `catalog`    | `TCatalog`                                                                   | Component catalog with Zod schemas                      |
+| `components` | [`NoExtraKeys`](../type-aliases/NoExtraKeys.md)\<`TComponents`, `TCatalog`\> | Component implementations matching catalog keys exactly |
+
+## Returns
+
+[`NoExtraKeys`](../type-aliases/NoExtraKeys.md)\<`TComponents`, `TCatalog`\>
+
+Component map validated at compile time (frozen in development)
+
+## Throws
+
+Error if runtime validation detects missing or extra keys
+
+## Examples
+
+Valid component definition
+
+```typescript
+import { defineComponents } from "@xmachines/play-catalog";
+import { catalog } from "./catalog.js";
+import { DashboardComponent, LoginFormComponent } from "./components.js";
+
+// ✅ Valid - all keys match catalog
+const components = defineComponents(catalog, {
+	Dashboard: DashboardComponent,
+	LoginForm: LoginFormComponent,
+});
+```
+
+TypeScript compile errors
+
+```typescript
+import { defineComponents } from "@xmachines/play-catalog";
+import { catalog } from "./catalog.js";
+
+// ❌ TypeScript error - missing 'LoginForm'
+const components = defineComponents(catalog, {
+	Dashboard: DashboardComponent,
+});
+
+// ❌ TypeScript error - extra 'UnknownComponent' not in catalog
+const components = defineComponents(catalog, {
+	Dashboard: DashboardComponent,
+	LoginForm: LoginFormComponent,
+	UnknownComponent: SomeComponent,
+});
+```
+
+Progressive example with Actor integration
+
+```typescript
+import { z } from "zod";
+import { defineCatalog, defineComponents } from "@xmachines/play-catalog";
+import { definePlayer } from "@xmachines/play-xstate";
+import { setup } from "xstate";
+
+// 1. Define catalog
+const catalog = defineCatalog({
+  HomePage: z.object({}),
+  Dashboard: z.object({ userId: z.string() })
+});
+
+// 2. Define components
+const components = defineComponents(catalog, {
+  HomePage: () => <div>Home</div>,
+  Dashboard: ({ userId }) => <div>Dashboard for {userId}</div>
+});
+
+// 3. Create machine referencing catalog components
+const machine = setup({}).createMachine({
+  initial: 'home',
+  states: {
+    home: {
+      meta: {
+        route: '/',
+        view: { component: 'HomePage' } // References catalog key
+      }
+    },
+    dashboard: {
+      meta: {
+        route: '/dashboard',
+        view: { component: 'Dashboard', userId: '123' }
+      }
+    }
+  }
+});
+
+// 4. Create actor with catalog
+const createPlayer = definePlayer({ machine, catalog });
+const actor = createPlayer();
+```
+
+## See
+
+- [RFC Play v1 - Invariant INV-02](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [defineCatalog](defineCatalog.md) for creating the catalog schema
+- [Catalog](../type-aliases/Catalog.md) for the catalog type definition

package/api/@xmachines/play-catalog/type-aliases/Catalog.md

@@ -0,0 +1,48 @@
+[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / Catalog
+
+# Type Alias: Catalog\<TCatalog\>
+
+```ts
+type Catalog<TCatalog> = TCatalog;
+```
+
+Defined in: [types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/types.ts#L35)
+
+Component catalog mapping component names to Zod prop schemas
+
+Generic type that maps component name strings to their Zod schema validators.
+The catalog enables type-safe UI projection by defining the vocabulary of
+components that the Actor can reference in `meta.view` without coupling to
+framework implementations.
+
+## Type Parameters
+
+| Type Parameter                                         | Default type                      | Description                                        |
+| ------------------------------------------------------ | --------------------------------- | -------------------------------------------------- |
+| `TCatalog` _extends_ `Record`\<`string`, `z.ZodType`\> | `Record`\<`string`, `z.ZodType`\> | Record mapping component names to Zod schema types |
+
+## Example
+
+Basic catalog type
+
+```typescript
+import { z } from "zod";
+import { defineCatalog } from "@xmachines/play-catalog";
+import type { Catalog } from "@xmachines/play-catalog";
+
+const catalog = defineCatalog({
+	Dashboard: z.object({ userId: z.string() }),
+	LoginForm: z.object({ error: z.string().optional() }),
+});
+
+type MyCatalog = typeof catalog;
+// Inferred as: Catalog<{
+//   Dashboard: z.ZodObject<...>,
+//   LoginForm: z.ZodObject<...>
+// }>
+```
+
+## See
+
+- [defineCatalog](../functions/defineCatalog.md) for creating catalog instances
+- [InferComponentProps](InferComponentProps.md) for extracting prop types

package/api/@xmachines/play-catalog/type-aliases/ComponentsFor.md

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / ComponentsFor
+
+# Type Alias: ComponentsFor\<TCatalog\>
+
+```ts
+type ComponentsFor<TCatalog> = { [K in keyof TCatalog]: unknown };
+```
+
+Defined in: [define-components.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/define-components.ts#L10)
+
+Component map type enforcing catalog keys
+
+Mapped type ensures components object has exactly catalog keys - no missing, no extra.
+This provides compile-time validation that framework components match the catalog schema.
+
+## Type Parameters
+
+| Type Parameter                                         |
+| ------------------------------------------------------ |
+| `TCatalog` _extends_ `Record`\<`string`, `z.ZodType`\> |

package/api/@xmachines/play-catalog/type-aliases/InferComponentProps.md

@@ -0,0 +1,65 @@
+[Documentation](../../../README.md) / [@xmachines/play-catalog](../README.md) / InferComponentProps
+
+# Type Alias: InferComponentProps\<TCatalog, TKey\>
+
+```ts
+type InferComponentProps<TCatalog, TKey> = z.infer<TCatalog[TKey]>;
+```
+
+Defined in: [types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-catalog/src/types.ts#L84)
+
+Infer component prop types from catalog entry
+
+Utility type that extracts the TypeScript type of a component's props from its
+Zod schema definition in the catalog. Enables type-safe component implementations
+that match the catalog schema.
+
+## Type Parameters
+
+| Type Parameter                                         | Description                                           |
+| ------------------------------------------------------ | ----------------------------------------------------- |
+| `TCatalog` _extends_ `Record`\<`string`, `z.ZodType`\> | Catalog record mapping component names to Zod schemas |
+| `TKey` _extends_ keyof `TCatalog`                      | Specific component key to extract props for           |
+
+## Returns
+
+TypeScript type inferred from the Zod schema
+
+## Example
+
+Extracting prop types for components
+
+```typescript
+import { z } from "zod";
+import { defineCatalog } from "@xmachines/play-catalog";
+import type { InferComponentProps } from "@xmachines/play-catalog";
+
+const catalog = defineCatalog({
+  Dashboard: z.object({
+    userId: z.string(),
+    stats: z.object({
+      views: z.number(),
+      clicks: z.number()
+    })
+  })
+});
+
+type DashboardProps = InferComponentProps<typeof catalog, 'Dashboard'>;
+// Inferred as: {
+//   userId: string;
+//   stats: {
+//     views: number;
+//     clicks: number;
+//   };
+// }
+
+// Use in React component
+function Dashboard({ userId, stats }: DashboardProps) {
+  return <div>{userId}: {stats.views} views</div>;
+}
+```
+
+## See
+
+- [Catalog](Catalog.md) for the catalog type definition
+- [defineCatalog](../functions/defineCatalog.md) for creating catalog instances