@xmachines/play-view 0.0.0-bootstrap.0 → 4.0.0

package/dist/view-store-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-store-lifecycle.js","sourceRoot":"","sources":["../src/view-store-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAoDnD;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACvC,WAA0D;IAE1D,IAAI,aAAa,GAAsB,IAAI,CAAC;IAC5C,IAAI,WAAW,GAAuB,SAAS,CAAC;IAChD,IAAI,QAAQ,GAAoB,IAAI,CAAC;IACrC,IAAI,SAAS,GAAY,IAAI,CAAC;IAC9B,wEAAwE;IACxE,IAAI,aAAa,GAAsB,IAAI,CAAC;IAC5C,IAAI,YAAY,GAAsB,IAAI,CAAC;IAE3C,MAAM,KAAK,GAAG,GAAS,EAAE;QACxB,aAAa,GAAG,IAAI,CAAC;QACrB,WAAW,GAAG,SAAS,CAAC;QACxB,QAAQ,GAAG,IAAI,CAAC;QAChB,SAAS,GAAG,IAAI,CAAC;QACjB,aAAa,GAAG,IAAI,CAAC;QACrB,YAAY,GAAG,IAAI,CAAC;IACrB,CAAC,CAAC;IAEF,OAAO;QACN,KAAK;QACL,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO;YAC1C,iFAAiF;YACjF,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;gBACzB,MAAM,YAAY,GAAG,SAAS,KAAK,IAAI,IAAI,aAAa,KAAK,IAAI,CAAC;gBAClE,IAAI,CAAC,YAAY;oBAAE,KAAK,EAAE,CAAC;gBAC3B,SAAS,GAAG,KAAK,CAAC;YACnB,CAAC;YAED,IAAI,QAAoB,CAAC;YACzB,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,IAAI,aAAa,EAAE,CAAC;gBACnB,QAAQ,GAAG,aAAa,CAAC;gBACzB,IAAI,OAAO,EAAE,oBAAoB,KAAK,KAAK,EAAE,CAAC;oBAC7C,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;gBACvC,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;gBAC7B,IAAI,SAAS,GAAsB,aAAa,CAAC;gBACjD,IACC,SAAS,KAAK,IAAI;oBAClB,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,EACpE,CAAC;oBACF,SAAS,GAAG,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;oBACjD,aAAa,GAAG,SAAS,CAAC;oBAC1B,WAAW,GAAG,OAAO,CAAC;oBACtB,QAAQ,GAAG,IAAI,CAAC;gBACjB,CAAC;qBAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;oBAClC,qBAAqB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;gBACxC,CAAC;gBACD,QAAQ,GAAG,IAAI,CAAC;gBAChB,QAAQ,GAAG,SAAS,CAAC;YACtB,CAAC;YAED,IAAI,aAAa,KAAK,QAAQ,EAAE,CAAC;gBAChC,aAAa,GAAG,QAAQ,CAAC;gBACzB,YAAY,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC7C,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,YAA0B,EAAE,QAAQ,EAAE,CAAC;QAChF,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/view-types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The view types that every renderer of the Play Architecture shares.
+ *
+ * `PlaySpec` is the spec that an actor publishes, `Viewable` is the capability that
+ * publishes it, and the two provider types are the framework-free half of the props and
+ * of the context value of a provider.
+ *
+ * They live here, and not with `PlayActor`, because each one names a type of
+ * `@xmachines/json-render-core`. An application that routes and renders no view
+ * therefore installs that package never.
+ *
+ * @packageDocumentation
+ */
+import type { Signal } from "@xmachines/play-signals";
+import type { PlayActor, ActorEvent } from "@xmachines/play-actor";
+import type { Spec, StateStore, RenderErrorHandler, ActionHandler } from "@xmachines/json-render-core";
+/**
+ * The XMachines extension of the `Spec` type of `@xmachines/json-render-core`.
+ *
+ * Each derived view receives the machine context in its state store, under the
+ * read-only `/context` subtree. A spec therefore reads the context through the
+ * ordinary `{ $state: "/context/…" }` grammar: in a prop, in a `visible` condition,
+ * and in `repeat.statePath`. The store always holds the complete context, and a
+ * spec reads only the paths that it needs.
+ */
+export interface PlaySpec extends Spec {
+    /**
+     * The identity of the view of this derived spec. `deriveCurrentView` sets it from
+     * the meta entry that the derivation selected. A provider uses it as the key of its
+     * store lifecycle: a new `viewKey` seeds the store again, and the same `viewKey`
+     * refreshes `/context` in place, which keeps the ephemeral view state. Never write
+     * this field in `meta.view`.
+     */
+    readonly viewKey?: string;
+}
+/**
+ * The identity helper gives a view spec literal the type `PlaySpec` at the
+ * definition site. The compiler therefore checks the spec, and the IDE completes it.
+ *
+ * The XState `meta` field has the type `Record<string, unknown>`. TypeScript
+ * therefore infers no spec shape from the context. `typedSpec(...)` is the
+ * mechanism that starts the check where you write the spec. The parameter holds no
+ * `viewKey`: the derivation stamps that field, and it overwrites a value from an
+ * author without a notice. Therefore the compiler refuses a `viewKey` here.
+ *
+ * The check of an excess property works on an inline object literal only. For a
+ * spec in a variable, or for a spec from a spread, write `satisfies PlaySpec` at
+ * the literal instead.
+ *
+ * At run time this function does nothing: it returns the spec object without a
+ * change.
+ *
+ * @example
+ * ```ts
+ * meta: {
+ *   view: typedSpec({
+ *     root: "root",
+ *     elements: {
+ *       root: {
+ *         type: "Dashboard",
+ *         props: { username: { $state: "/context/username" } },
+ *         children: [],
+ *       },
+ *     },
+ *   }),
+ * }
+ * ```
+ */
+export declare function typedSpec(spec: Omit<PlaySpec, "viewKey">): PlaySpec;
+/**
+ * The actor capability that exposes a renderable view state.
+ *
+ * `Viewable` marks an actor that publishes a `currentView` signal.
+ * A renderer, such as `PlayRenderer`, reads this contract. It converts the
+ * description of the current view into a concrete UI, and the framework adapter
+ * therefore holds no view logic.
+ */
+export interface Viewable {
+    /**
+     * The signal of the current view. It holds the json-render PlaySpec of the current
+     * machine state, or null when no view is active.
+     *
+     * The infrastructure renders the view. This is the Logic-Driven UI invariant.
+     */
+    readonly currentView: Signal.State<PlaySpec | null>;
+}
+/**
+ * The framework-agnostic base of the `ViewContextValue` type in each framework.
+ *
+ * It holds the three fields that are identical in React, Vue, Solid, and Svelte.
+ * The `registry` field belongs to one framework, because each framework has its own
+ * `ComponentRegistry` type. Therefore `TRegistry` gives its type, and this is the
+ * same generic parameter as in `BaseActorProviderProps`.
+ *
+ * @typeParam TRegistry - The registry type of the component of the framework, for example `ComponentRegistry` from `@xmachines/json-render-react`.
+ */
+export interface BaseViewContextValue<TRegistry extends object> {
+    /** The current PlaySpec to render. */
+    spec: PlaySpec;
+    /** The action handlers, resolved against the live StateStore. */
+    handlers: Record<string, ActionHandler>;
+    /** The component registry, from registryResult.registry. */
+    registry: TRegistry;
+    /**
+     * The active StateStore. Give it to JSONUIProvider or JsonUIProvider as `store`, and the providers then share the state.
+     */
+    store: StateStore;
+}
+/**
+ * The actor that a view provider reads: the contract, and the view capability.
+ *
+ * It names NO engine. A provider reads `currentView` and `send`, and nothing else — the
+ * measurement is 20 reads of `currentView` and 16 of `send` across the five renderers, and
+ * no read of any other member. The type said `ViewActor`
+ * before, which named XState in every renderer AND erased the snapshot and the event union
+ * of the machine at the same time.
+ *
+ * It does NOT name `Routable`. The view implies no routing.
+ *
+ * @typeParam TSnapshot - The snapshot type that `state` holds.
+ * @typeParam TEvent - The event union that `send` accepts.
+ */
+export type ViewActor<TSnapshot = unknown, TEvent extends ActorEvent = ActorEvent> = PlayActor<TSnapshot, TEvent> & Viewable;
+/**
+ * The framework-agnostic base props. Every `ActorProvider` implementation shares
+ * them: React, Vue, Solid, and Svelte. `TRegistry` holds the
+ * `DefineRegistryResult` type of the framework. `RenderErrorHandler` comes from
+ * `@xmachines/json-render-core`, and a second generic parameter is therefore not
+ * necessary.
+ *
+ * Each framework package extends this interface with its `fallback` field, its
+ * `onError` field, and its `children` field.
+ *
+ * @typeParam TRegistry - The `DefineRegistryResult` type of the framework.
+ *
+ * @example
+ * ```ts
+ * import type { BaseActorProviderProps , ViewActor} from "@xmachines/play-view";
+ * import type { DefineRegistryResult } from "@xmachines/json-render-react";
+ *
+ * interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+ *   fallback?: React.ReactNode;
+ *   children: React.ReactNode;
+ * }
+ * ```
+ */
+export interface BaseActorProviderProps<TRegistry extends {
+    registry: object;
+    handlers: (...args: never[]) => unknown;
+}, TActor extends ViewActor = ViewActor> {
+    /** The actor instance with the currentView signal. It requires the Viewable capability. */
+    actor: TActor;
+    /** The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers. */
+    registryResult: TRegistry;
+    /**
+     * The optional external StateStore, which is the controlled mode.
+     * With this option, the provider ignores spec.state, and this store is the single
+     * source of truth. Without it, the provider makes a new @xstate/store atom for each
+     * view transition, with the values of spec.state.
+     */
+    store?: StateStore;
+    /**
+     * The provider calls it when one catalog component throws during a render.
+     * This handler replaces every onRenderError of defineRegistry.
+     */
+    onRenderError?: RenderErrorHandler;
+}
+//# sourceMappingURL=view-types.d.ts.map

package/dist/view-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-types.d.ts","sourceRoot":"","sources":["../src/view-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EACX,IAAI,EACJ,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAS,SAAQ,IAAI;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,QAAQ,CAEnE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS,SAAS,MAAM;IAC7D,sCAAsC;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,4DAA4D;IAC5D,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,KAAK,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,CAAC,SAAS,GAAG,OAAO,EAAE,MAAM,SAAS,UAAU,GAAG,UAAU,IAAI,SAAS,CAC7F,SAAS,EACT,MAAM,CACN,GACA,QAAQ,CAAC;AAEV;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,sBAAsB,CACtC,SAAS,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAA;CAAE,EAC/E,MAAM,SAAS,SAAS,GAAG,SAAS;IAEpC,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAC;IACd,uHAAuH;IACvH,cAAc,EAAE,SAAS,CAAC;IAC1B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACnC"}

package/dist/view-types.js

@@ -0,0 +1,37 @@
+/**
+ * The identity helper gives a view spec literal the type `PlaySpec` at the
+ * definition site. The compiler therefore checks the spec, and the IDE completes it.
+ *
+ * The XState `meta` field has the type `Record<string, unknown>`. TypeScript
+ * therefore infers no spec shape from the context. `typedSpec(...)` is the
+ * mechanism that starts the check where you write the spec. The parameter holds no
+ * `viewKey`: the derivation stamps that field, and it overwrites a value from an
+ * author without a notice. Therefore the compiler refuses a `viewKey` here.
+ *
+ * The check of an excess property works on an inline object literal only. For a
+ * spec in a variable, or for a spec from a spread, write `satisfies PlaySpec` at
+ * the literal instead.
+ *
+ * At run time this function does nothing: it returns the spec object without a
+ * change.
+ *
+ * @example
+ * ```ts
+ * meta: {
+ *   view: typedSpec({
+ *     root: "root",
+ *     elements: {
+ *       root: {
+ *         type: "Dashboard",
+ *         props: { username: { $state: "/context/username" } },
+ *         children: [],
+ *       },
+ *     },
+ *   }),
+ * }
+ * ```
+ */
+export function typedSpec(spec) {
+    return spec;
+}
+//# sourceMappingURL=view-types.js.map

package/dist/view-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-types.js","sourceRoot":"","sources":["../src/view-types.ts"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,SAAS,CAAC,IAA+B;IACxD,OAAO,IAAI,CAAC;AACb,CAAC"}

package/package.json

@@ -1,16 +1,77 @@
 {
-	"name": "@xmachines/play-view",
-	"version": "0.0.0-bootstrap.0",
-	"description": "Placeholder. This version contains no code. The first release of @xmachines/play-view is 4.0.0.",
-	"license": "MIT",
-	"author": "XMachines",
-	"repository": {
-		"type": "git",
-		"url": "git+https://gitlab.com/xmachin-es/xmachines-js.git",
-		"directory": "packages/play-view"
-	},
-	"files": [
-		"README.md",
-		"LICENSE"
-	]
+  "name": "@xmachines/play-view",
+  "version": "4.0.0",
+  "private": false,
+  "description": "The shared view half of every XMachines renderer: the view store lifecycle, the context projection, and the provider guards",
+  "keywords": [
+    "json-render",
+    "play-architecture",
+    "view",
+    "xmachines",
+    "xstate"
+  ],
+  "license": "MIT",
+  "author": "XMachines Contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/xmachin-es/xmachines-js.git",
+    "directory": "packages/play-view"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && tsc --build",
+    "clean": "rm -rf dist *.tsbuildinfo coverage node_modules/.svelte2tsx-* node_modules/.vite*",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "oxlint .",
+    "lint:security": "node ../../scripts/semgrep-scan.mjs",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check ."
+  },
+  "dependencies": {
+    "@xmachines/play-actor": "4.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^7.0.1",
+    "@types/node": "^26.6.2",
+    "@xmachines/json-render-core": "^0.20.0-xm.4",
+    "@xmachines/play": "4.0.0",
+    "@xmachines/play-signals": "4.0.0",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1",
+    "xstate": "^5.33.0"
+  },
+  "peerDependencies": {
+    "@xmachines/json-render-core": "^0.20.0-xm.4",
+    "@xmachines/play": "4.0.0",
+    "@xmachines/play-signals": "4.0.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
 }