@xmachines/docs 7.0.0 → 7.2.0

package/examples/@xmachines/play-solid-gallery-demo/variables/temperatureCatalog.md

@@ -0,0 +1,122 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / temperatureCatalog
+
+# Variable: temperatureCatalog
+
+```ts
+const temperatureCatalog: Catalog<{
+  catalog: SchemaType<"object", {
+     actions: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        params: SchemaType<"zod", unknown>;
+     }>;
+     components: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        example: SchemaType<"any", unknown>;
+        props: SchemaType<"zod", unknown>;
+        slots: SchemaType<"array", SchemaType<"string", unknown>>;
+     }>;
+  }>;
+  spec: SchemaType<"object", {
+     elements: SchemaType<"record", SchemaType<"object", {
+        children: SchemaType<"array", SchemaType<"string", unknown>>;
+        props: SchemaType<"propsOf", string>;
+        repeat: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+        slots: {
+           inner?: SchemaType<"array", SchemaType<..., ...>>;
+           kind: "record";
+           optional: true;
+        };
+        type: SchemaType<"ref", string>;
+        visible: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+     }>>;
+     root: SchemaType<"string", unknown>;
+  }>;
+}, {
+  actions: {
+     setCelsius: {
+        description: "Convert a Celsius value (sends temp.setCelsius to the machine)";
+        params: ZodObject<{
+           value: ZodString;
+        }, $strip>;
+     };
+     setFahrenheit: {
+        description: "Convert a Fahrenheit value (sends temp.setFahrenheit to the machine)";
+        params: ZodObject<{
+           value: ZodString;
+        }, $strip>;
+     };
+  };
+  components: {
+     Button: {
+        props: ZodObject<{
+           disabled: ZodOptional<ZodBoolean>;
+           label: ZodString;
+           testId: ZodOptional<ZodString>;
+           variant: ZodOptional<ZodEnum<{
+              danger: "danger";
+              primary: "primary";
+              secondary: "secondary";
+           }>>;
+        }, $strip>;
+     };
+     Field: {
+        props: ZodObject<{
+           checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
+           formErrors: ZodOptional<ZodRecord<ZodString, ZodArray<ZodString>>>;
+           inputType: ZodOptional<ZodEnum<{
+              email: "email";
+              text: "text";
+              textarea: "textarea";
+           }>>;
+           label: ZodString;
+           placeholder: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           value: ZodOptional<ZodString>;
+        }, $strip>;
+     };
+     Page: {
+        props: ZodObject<{
+           page: ZodString;
+           title: ZodString;
+        }, $strip>;
+     };
+     Panel: {
+        props: ZodObject<{
+           note: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           title: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+        }, $strip>;
+     };
+     Text: {
+        props: ZodObject<{
+           testId: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+           value: ZodString;
+        }, $strip>;
+     };
+  };
+}>;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/catalogs.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/catalogs.ts#L31)
+
+Built catalogs, one per machine — router demos import theirs from here.

package/examples/@xmachines/play-solid-gallery-demo/variables/ticTacToeCatalog.md

@@ -0,0 +1,119 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / ticTacToeCatalog
+
+# Variable: ticTacToeCatalog
+
+```ts
+const ticTacToeCatalog: Catalog<{
+  catalog: SchemaType<"object", {
+     actions: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        params: SchemaType<"zod", unknown>;
+     }>;
+     components: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        example: SchemaType<"any", unknown>;
+        props: SchemaType<"zod", unknown>;
+        slots: SchemaType<"array", SchemaType<"string", unknown>>;
+     }>;
+  }>;
+  spec: SchemaType<"object", {
+     elements: SchemaType<"record", SchemaType<"object", {
+        children: SchemaType<"array", SchemaType<"string", unknown>>;
+        props: SchemaType<"propsOf", string>;
+        repeat: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+        slots: {
+           inner?: SchemaType<"array", SchemaType<..., ...>>;
+           kind: "record";
+           optional: true;
+        };
+        type: SchemaType<"ref", string>;
+        visible: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+     }>>;
+     root: SchemaType<"string", unknown>;
+  }>;
+}, {
+  actions: {
+     play: {
+        description: "Claim a board cell for the current player (sends ttt.play to the machine)";
+        params: ZodObject<{
+           id: ZodString;
+        }, $strip>;
+     };
+     reset: {
+        description: "Start a fresh game (sends ttt.reset to the machine)";
+     };
+  };
+  components: {
+     Button: {
+        props: ZodObject<{
+           disabled: ZodOptional<ZodBoolean>;
+           label: ZodString;
+           testId: ZodOptional<ZodString>;
+           variant: ZodOptional<ZodEnum<{
+              danger: "danger";
+              primary: "primary";
+              secondary: "secondary";
+           }>>;
+        }, $strip>;
+     };
+     Field: {
+        props: ZodObject<{
+           checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
+           formErrors: ZodOptional<ZodRecord<ZodString, ZodArray<ZodString>>>;
+           inputType: ZodOptional<ZodEnum<{
+              email: "email";
+              text: "text";
+              textarea: "textarea";
+           }>>;
+           label: ZodString;
+           placeholder: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           value: ZodOptional<ZodString>;
+        }, $strip>;
+     };
+     Page: {
+        props: ZodObject<{
+           page: ZodString;
+           title: ZodString;
+        }, $strip>;
+     };
+     Panel: {
+        props: ZodObject<{
+           note: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           title: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+        }, $strip>;
+     };
+     Text: {
+        props: ZodObject<{
+           testId: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+           value: ZodString;
+        }, $strip>;
+     };
+  };
+}>;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/catalogs.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/catalogs.ts#L28)
+
+Built catalogs, one per machine — router demos import theirs from here.

package/examples/@xmachines/{play-react-demo/variables/authCatalog.md → play-solid-gallery-demo/variables/todoMvcCatalog.md}

@@ -1,9 +1,9 @@
-[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / authCatalog
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / todoMvcCatalog
 
-# Variable: authCatalog
+# Variable: todoMvcCatalog
 
 ```ts
-const authCatalog: Catalog<{
+const todoMvcCatalog: Catalog<{
   catalog: SchemaType<"object", {
      actions: SchemaType<"map", {
         description: SchemaType<"string", unknown>;
@@ -41,60 +41,49 @@ const authCatalog: Catalog<{
   }>;
 }, {
   actions: {
-     addTask: {
-        description: "Add a task (sends task.add to the machine)";
+     add: {
+        description: "Add a todo (sends todo.add to the machine)";
         params: ZodObject<{
            title: ZodString;
         }, $strip>;
      };
-     completeTask: {
-        description: "Mark a task done (sends task.complete to the machine)";
-        params: ZodObject<{
-           id: ZodString;
-        }, $strip>;
+     clearCompleted: {
+        description: "Remove every completed todo (sends todo.clearCompleted)";
      };
-     login: {
-        description: "Login with username";
+     edit: {
+        description: "Open one todo in the edit view (routes to '#todo' with the id param)";
         params: ZodObject<{
-           username: ZodString;
+           id: ZodString;
         }, $strip>;
      };
-     logout: {
-        description: "Logout and return to home";
-     };
-     removeTask: {
-        description: "Remove a task (sends task.remove to the machine)";
+     remove: {
+        description: "Remove a todo (sends todo.remove)";
         params: ZodObject<{
            id: ZodString;
         }, $strip>;
      };
-     resetForm: {
-        description: "Reset a demo form to its defaults (confirm-gated in the spec)";
+     rename: {
+        description: "Rename a todo (sends todo.rename; rejects a blank title)";
         params: ZodObject<{
-           form: ZodString;
+           id: ZodString;
+           title: ZodString;
         }, $strip>;
      };
      route: {
-        description: "Navigate to a route by path (e.g. '#home', '#login', '#dashboard')";
+        description: "Navigate to a filter route (e.g. '#all', '#active', '#completed')";
         params: ZodObject<{
            params: ZodOptional<ZodRecord<ZodString, ZodString>>;
            to: ZodString;
         }, $strip>;
      };
-     submitForm: {
-        description: "Submit a demo form; rejects when the form did not pass validation";
+     toggle: {
+        description: "Toggle a todo between open and done (sends todo.toggle)";
         params: ZodObject<{
-           form: ZodString;
-           valid: ZodOptional<ZodNullable<ZodBoolean>>;
+           id: ZodString;
         }, $strip>;
      };
   };
   components: {
-     About: {
-        props: ZodObject<{
-           title: ZodString;
-        }, $strip>;
-     };
      Button: {
         props: ZodObject<{
            disabled: ZodOptional<ZodBoolean>;
@@ -107,17 +96,6 @@ const authCatalog: Catalog<{
            }>>;
         }, $strip>;
      };
-     Contact: {
-        props: ZodObject<{
-           title: ZodString;
-        }, $strip>;
-     };
-     Dashboard: {
-        props: ZodObject<{
-           username: ZodString;
-           welcome: ZodBoolean;
-        }, $strip>;
-     };
      Field: {
         props: ZodObject<{
            checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
@@ -133,39 +111,17 @@ const authCatalog: Catalog<{
            value: ZodOptional<ZodString>;
         }, $strip>;
      };
-     Home: {
-        props: ZodObject<{
-           title: ZodString;
-        }, $strip>;
-     };
-     Login: {
-        props: ZodObject<{
-           title: ZodString;
-           username: ZodOptional<ZodString>;
-        }, $strip>;
-     };
-     NavBar: {
-        props: ZodObject<{
-           isAuthenticated: ZodBoolean;
-           username: ZodNullable<ZodString>;
-        }, $strip>;
-     };
-     Navigation: {
-        props: ZodObject<{
-           currentPath: ZodString;
-           isAuthenticated: ZodBoolean;
-        }, $strip>;
-     };
-     Overview: {
+     Page: {
         props: ZodObject<{
+           page: ZodString;
            title: ZodString;
         }, $strip>;
      };
      Panel: {
         props: ZodObject<{
-           note: ZodOptional<ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean, ZodNull]>>;
+           note: ZodOptional<ZodString>;
            testId: ZodOptional<ZodString>;
-           title: ZodOptional<ZodUnion<readonly [ZodString, ZodNumber]>>;
+           title: ZodOptional<ZodString>;
            tone: ZodOptional<ZodEnum<{
               danger: "danger";
               default: "default";
@@ -174,24 +130,22 @@ const authCatalog: Catalog<{
            }>>;
         }, $strip>;
      };
-     Profile: {
-        props: ZodObject<{
-           username: ZodString;
-        }, $strip>;
-     };
-     Settings: {
+     Text: {
         props: ZodObject<{
-           section: ZodOptional<ZodString>;
-           username: ZodString;
-        }, $strip>;
-     };
-     Stats: {
-        props: ZodObject<{
-           title: ZodString;
+           testId: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+           value: ZodString;
         }, $strip>;
      };
   };
 }>;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-react/examples/demo/src/catalog.ts#L5)
+Defined in: [packages/play-solid/examples/gallery/src/catalogs.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/catalogs.ts#L34)
+
+Built catalogs, one per machine — router demos import theirs from here.

package/examples/@xmachines/play-solid-gallery-demo/variables/triviaCatalog.md

@@ -0,0 +1,129 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / triviaCatalog
+
+# Variable: triviaCatalog
+
+```ts
+const triviaCatalog: Catalog<{
+  catalog: SchemaType<"object", {
+     actions: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        params: SchemaType<"zod", unknown>;
+     }>;
+     components: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        example: SchemaType<"any", unknown>;
+        props: SchemaType<"zod", unknown>;
+        slots: SchemaType<"array", SchemaType<"string", unknown>>;
+     }>;
+  }>;
+  spec: SchemaType<"object", {
+     elements: SchemaType<"record", SchemaType<"object", {
+        children: SchemaType<"array", SchemaType<"string", unknown>>;
+        props: SchemaType<"propsOf", string>;
+        repeat: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+        slots: {
+           inner?: SchemaType<"array", SchemaType<..., ...>>;
+           kind: "record";
+           optional: true;
+        };
+        type: SchemaType<"ref", string>;
+        visible: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+     }>>;
+     root: SchemaType<"string", unknown>;
+  }>;
+}, {
+  actions: {
+     answer: {
+        description: "Answer the current question by option id (sends trivia.answer)";
+        params: ZodObject<{
+           id: ZodString;
+        }, $strip>;
+     };
+     restart: {
+        description: "Return to the home screen for a fresh game (sends trivia.restart)";
+     };
+     route: {
+        description: "Navigate to a route by path (e.g. '#home', '#game')";
+        params: ZodObject<{
+           params: ZodOptional<ZodRecord<ZodString, ZodString>>;
+           to: ZodString;
+        }, $strip>;
+     };
+     start: {
+        description: "Start a new trivia game (sends trivia.start)";
+     };
+  };
+  components: {
+     Button: {
+        props: ZodObject<{
+           disabled: ZodOptional<ZodBoolean>;
+           label: ZodString;
+           testId: ZodOptional<ZodString>;
+           variant: ZodOptional<ZodEnum<{
+              danger: "danger";
+              primary: "primary";
+              secondary: "secondary";
+           }>>;
+        }, $strip>;
+     };
+     Field: {
+        props: ZodObject<{
+           checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
+           formErrors: ZodOptional<ZodRecord<ZodString, ZodArray<ZodString>>>;
+           inputType: ZodOptional<ZodEnum<{
+              email: "email";
+              text: "text";
+              textarea: "textarea";
+           }>>;
+           label: ZodString;
+           placeholder: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           value: ZodOptional<ZodString>;
+        }, $strip>;
+     };
+     Page: {
+        props: ZodObject<{
+           page: ZodString;
+           title: ZodString;
+        }, $strip>;
+     };
+     Panel: {
+        props: ZodObject<{
+           note: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           title: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+        }, $strip>;
+     };
+     Text: {
+        props: ZodObject<{
+           testId: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+           value: ZodString;
+        }, $strip>;
+     };
+  };
+}>;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/catalogs.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/catalogs.ts#L37)
+
+Built catalogs, one per machine — router demos import theirs from here.

package/examples/@xmachines/play-solid-router-demo/README.md

@@ -8,10 +8,11 @@ SolidJS Router adapter demonstration with authentication flow using the XMachine
 
 ## What This Demonstrates
 
-- Shared auth machine reused without framework-specific business logic
+- Shared auth machine (the login wall: `/`, `/login`, `/dashboard`) reused without framework-specific business logic
 - `PlayRouterProvider` renderer-based integration with Solid Router
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
-- Canonical atoms lifecycle integration with Solid's fine-grained reactivity
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md) renderer gallery
+- Atom lifecycle integration with Solid's fine-grained reactivity
 - Non-browser invariant tests plus browser E2E coverage
 - Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
 
@@ -31,11 +32,11 @@ Then open `http://localhost:3007`.
 Use this order to understand the implementation:
 
 1. `src/main.tsx` bootstraps the demo and mounts `<App />` onto `#app`.
-2. `src/runtime.ts` sets up the actor, registry, routes, and route map — all shared module-level singletons.
+2. `src/runtime.ts` sets up the actor, registry (built from `authCatalog` + `demoComponents`, both from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)), routes, and route map — all shared module-level singletons.
 3. `src/App.tsx` wires Solid Router routes and the `PlayRouterProvider` using the runtime exports.
 4. A `routeMap` is created by calling `createRouteMap(authMachine)` in `src/runtime.ts`.
 5. `PlayRouterProvider` forwards navigation intent from `@solidjs/router` to the actor, and reflects actor-approved routes back to the URL.
-6. `Shell` (from [`@xmachines/play-solid-demo`](../play-solid-demo/README.md)) renders actor-projected views (`PlayRenderer`) and provides the shared UI shell, including the debug panel's **Show Inspector** button.
+6. `Shell` (from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)) renders actor-projected views (`PlayRenderer`) and provides the shared UI shell, including the debug panel's **Show Inspector** button.
 7. `test/library-pattern.test.ts` and `test/browser/` verify invariants and runtime routing behavior.
 
 ```tsx fragment
@@ -64,7 +65,7 @@ export const routeMap = createRouteMap(authMachine);
 
 ```tsx fragment
 // src/App.tsx (shape)
-import { Shell } from "@xmachines/play-solid-demo"; // shared demo shell (workspace-only package)
+import { Shell } from "@xmachines/play-solid-gallery-demo"; // shared demo shell (workspace-only package)
 import { actor, inspector, registryResult, routeMap } from "./runtime.js";
 
 const Layout: ParentComponent = () => {
@@ -96,7 +97,7 @@ const Layout: ParentComponent = () => {
 - `src/App.tsx` - Solid Router wiring, `PlayRouterProvider` integration, and renderer composition
 - `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
-- `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared auth router browser suite
 
 ## State Machine & Architecture Details
 
@@ -136,5 +137,6 @@ These commands are defined in `package.json`:
 
 - [Solid Router](../../../api/@xmachines/play-solid-router/README.md)
 - [SolidJS](../../../api/@xmachines/play-solid/README.md)
+- [Solid renderer gallery](../play-solid-gallery-demo/README.md)
 - [TanStack Solid Router](../play-tanstack-solid-router-demo/README.md)
 - [Inspecting a Running Actor](../../../guides/inspector.md)