@xmachines/play-vue 2.0.0 → 2.1.1

package/dist/useActor.js

@@ -2,26 +2,29 @@ import { inject, provide } from "vue";
 import { assertNonNullable } from "@xmachines/play";
 //#region packages/play-vue/src/useActor.ts
 /**
-* useActor — Vue composable for accessing the provided actor inside a PlayRenderer tree.
-*
-* Components rendered inside PlayRenderer can call useActor() to reach the actor
-* instance without prop drilling.
-*
-* What is returned is a **swap-following proxy**, not the raw actor object:
-* - It is a stable reference for the lifetime of the injection, yet forwards every
-*   operation (property reads/writes, `in`, `Object.keys` / spread, `instanceof`)
-*   to whichever actor is CURRENTLY provided — so it transparently follows a
-*   `props.actor` swap on `<ActorProvider>` without consumers re-injecting.
-* - Method identity is stable per underlying method: `actor.send === actor.send`
-*   across repeated reads (allocation-free), and rebinds only when the underlying
-*   method changes or the actor is swapped.
-* - It is NOT `===` the `actor` prop passed to `<ActorProvider>` (it is a distinct
-*   Proxy object). Any consumer keyed on actor identity — most notably a router
-*   bridge extending `RouterBridgeBase`, whose one-bridge-per-actor guard keys a
-*   WeakMap on the actor instance — must be given the actor prop itself, not the
-*   value returned by `useActor()`.
-*
-* @throws {Error} If called outside a PlayRenderer tree
+* useActor — the Vue composable that gives the actor inside a PlayRenderer tree.
+*
+* A component inside PlayRenderer calls useActor() to reach the actor instance. The
+* actor is then not necessary as a prop.
+*
+* The composable returns a **proxy that follows a swap**, and not the raw actor
+* object:
+* - The proxy is a stable reference for the life of the injection. It forwards
+*   every operation (a property read, a property write, `in`, `Object.keys`, a
+*   spread, and `instanceof`) to the actor that the tree provides at that moment.
+*   Therefore it follows a swap of `props.actor` on `<ActorProvider>`, and a
+*   consumer does not inject the actor again.
+* - The identity of each method is stable: `actor.send === actor.send` across
+*   repeated reads, with no allocation. The proxy binds the method again only when
+*   the method below it changes, or when the tree provides a different actor.
+* - The proxy is NOT `===` the `actor` prop of `<ActorProvider>`, because it is a
+*   separate Proxy object. Therefore give the actor prop itself, and not the value
+*   of `useActor()`, to each consumer that uses the identity of the actor as a key.
+*   The most important such consumer is a router bridge that extends
+*   `RouterBridgeBase`: its guard of one bridge for each actor uses the actor
+*   instance as the key of a WeakMap.
+*
+* @throws {Error} When the caller is outside a PlayRenderer tree
 *
 * @example
 * ```typescript
@@ -35,11 +38,12 @@ import { assertNonNullable } from "@xmachines/play";
 */
 var ActorKey = Symbol("xmachines.actor");
 /**
-* Provide the actor to all descendant components via Vue's inject/provide mechanism.
+* Provides the actor to every descendant component, through the inject and provide
+* mechanism of Vue.
 *
-* Called inside `PlayRenderer.vue`'s `setup()` to make the actor available to any
-* child component that calls `useActor()`. Not typically needed outside framework
-* internals unless building a custom renderer wrapper.
+* The `setup()` function of `PlayRenderer.vue` calls it. The actor is then
+* available to each child component that calls `useActor()`. You need this function
+* outside the framework internals only when you build your own renderer wrapper.
 *
 * @param actor - The actor instance to inject into the component tree.
 */

package/dist/useActor.js.map

@@ -1 +1 @@
-{"version":3,"file":"useActor.js","names":[],"sources":["../src/useActor.ts"],"sourcesContent":["/**\n * useActor — Vue composable for accessing the provided actor inside a PlayRenderer tree.\n *\n * Components rendered inside PlayRenderer can call useActor() to reach the actor\n * instance without prop drilling.\n *\n * What is returned is a **swap-following proxy**, not the raw actor object:\n * - It is a stable reference for the lifetime of the injection, yet forwards every\n *   operation (property reads/writes, `in`, `Object.keys` / spread, `instanceof`)\n *   to whichever actor is CURRENTLY provided — so it transparently follows a\n *   `props.actor` swap on `<ActorProvider>` without consumers re-injecting.\n * - Method identity is stable per underlying method: `actor.send === actor.send`\n *   across repeated reads (allocation-free), and rebinds only when the underlying\n *   method changes or the actor is swapped.\n * - It is NOT `===` the `actor` prop passed to `<ActorProvider>` (it is a distinct\n *   Proxy object). Any consumer keyed on actor identity — most notably a router\n *   bridge extending `RouterBridgeBase`, whose one-bridge-per-actor guard keys a\n *   WeakMap on the actor instance — must be given the actor prop itself, not the\n *   value returned by `useActor()`.\n *\n * @throws {Error} If called outside a PlayRenderer tree\n *\n * @example\n * ```typescript\n * import { useActor } from \"@xmachines/play-vue\";\n *\n * const actor = useActor();\n * actor.send({ type: \"SUBMIT\" });\n * ```\n *\n * @packageDocumentation\n */\n\nimport { inject, provide } from \"vue\";\nimport type { InjectionKey } from \"vue\";\nimport { assertNonNullable } from \"@xmachines/play\";\nimport type { AbstractActor } from \"@xmachines/play-actor\";\nimport type { AnyActorLogic } from \"xstate\";\n\n/** Bare actor type accepted by Vue context providers. For the full routing + view shape, use `PlayActor` from `@xmachines/play-router`. */\nexport type AnyPlayActor = AbstractActor<AnyActorLogic>;\n\nexport const ActorKey: InjectionKey<AnyPlayActor> = Symbol(\"xmachines.actor\");\n\n/**\n * Provide the actor to all descendant components via Vue's inject/provide mechanism.\n *\n * Called inside `PlayRenderer.vue`'s `setup()` to make the actor available to any\n * child component that calls `useActor()`. Not typically needed outside framework\n * internals unless building a custom renderer wrapper.\n *\n * @param actor - The actor instance to inject into the component tree.\n */\nexport function provideActor(actor: AnyPlayActor): void {\n\tprovide(ActorKey, actor);\n}\n\nexport function useActor(): AnyPlayActor {\n\treturn assertNonNullable(inject(ActorKey), \"ActorKey\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,IAAa,WAAuC,OAAO,iBAAiB;;;;;;;;;;AAW5E,SAAgB,aAAa,OAA2B;CACvD,QAAQ,UAAU,KAAK;AACxB;AAEA,SAAgB,WAAyB;CACxC,OAAO,kBAAkB,OAAO,QAAQ,GAAG,UAAU;AACtD"}
+{"version":3,"file":"useActor.js","names":[],"sources":["../src/useActor.ts"],"sourcesContent":["/**\n * useActor — the Vue composable that gives the actor inside a PlayRenderer tree.\n *\n * A component inside PlayRenderer calls useActor() to reach the actor instance. The\n * actor is then not necessary as a prop.\n *\n * The composable returns a **proxy that follows a swap**, and not the raw actor\n * object:\n * - The proxy is a stable reference for the life of the injection. It forwards\n *   every operation (a property read, a property write, `in`, `Object.keys`, a\n *   spread, and `instanceof`) to the actor that the tree provides at that moment.\n *   Therefore it follows a swap of `props.actor` on `<ActorProvider>`, and a\n *   consumer does not inject the actor again.\n * - The identity of each method is stable: `actor.send === actor.send` across\n *   repeated reads, with no allocation. The proxy binds the method again only when\n *   the method below it changes, or when the tree provides a different actor.\n * - The proxy is NOT `===` the `actor` prop of `<ActorProvider>`, because it is a\n *   separate Proxy object. Therefore give the actor prop itself, and not the value\n *   of `useActor()`, to each consumer that uses the identity of the actor as a key.\n *   The most important such consumer is a router bridge that extends\n *   `RouterBridgeBase`: its guard of one bridge for each actor uses the actor\n *   instance as the key of a WeakMap.\n *\n * @throws {Error} When the caller is outside a PlayRenderer tree\n *\n * @example\n * ```typescript\n * import { useActor } from \"@xmachines/play-vue\";\n *\n * const actor = useActor();\n * actor.send({ type: \"SUBMIT\" });\n * ```\n *\n * @packageDocumentation\n */\n\nimport { inject, provide } from \"vue\";\nimport type { InjectionKey } from \"vue\";\nimport { assertNonNullable } from \"@xmachines/play\";\nimport type { AbstractActor } from \"@xmachines/play-actor\";\nimport type { AnyActorLogic } from \"xstate\";\n\n/**\n * The bare actor type that the Vue context providers accept. For the complete routing and view shape, use `PlayActor` from `@xmachines/play-router`.\n */\nexport type AnyPlayActor = AbstractActor<AnyActorLogic>;\n\nexport const ActorKey: InjectionKey<AnyPlayActor> = Symbol(\"xmachines.actor\");\n\n/**\n * Provides the actor to every descendant component, through the inject and provide\n * mechanism of Vue.\n *\n * The `setup()` function of `PlayRenderer.vue` calls it. The actor is then\n * available to each child component that calls `useActor()`. You need this function\n * outside the framework internals only when you build your own renderer wrapper.\n *\n * @param actor - The actor instance to inject into the component tree.\n */\nexport function provideActor(actor: AnyPlayActor): void {\n\tprovide(ActorKey, actor);\n}\n\nexport function useActor(): AnyPlayActor {\n\treturn assertNonNullable(inject(ActorKey), \"ActorKey\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,IAAa,WAAuC,OAAO,iBAAiB;;;;;;;;;;;AAY5E,SAAgB,aAAa,OAA2B;CACvD,QAAQ,UAAU,KAAK;AACxB;AAEA,SAAgB,WAAyB;CACxC,OAAO,kBAAkB,OAAO,QAAQ,GAAG,UAAU;AACtD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-vue",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Vue renderer for XMachines Play architecture",
   "keywords": [
     "reactive",
@@ -41,12 +41,13 @@
     "lint": "oxlint .",
     "format": "oxfmt .",
     "test": "vitest",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@xmachines/play": "2.0.0",
-    "@xmachines/play-actor": "2.0.0",
-    "@xmachines/play-signals": "2.0.0"
+    "@xmachines/play": "2.1.1",
+    "@xmachines/play-actor": "2.1.1",
+    "@xmachines/play-signals": "2.1.1"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",