@retronew/call-vue 0.2.0 → 0.3.0

package/README.md

@@ -43,7 +43,7 @@ import type { PropsWithCall } from '@retronew/call-vue'
 type Props = { message: string }
 type Response = boolean
 
-defineProps<PropsWithCall<Props, Response, Record<string, never>>>()
+defineProps<PropsWithCall<Props, Response, {}>>()
 </script>
 
 <template>
@@ -109,6 +109,20 @@ async function handleDelete() {
   instance's position in the stack, how many are open, and whatever props
   were passed to `<Confirm rootProp="…" />`.
 
+For a `void` response, the two external forms are intentionally distinct:
+
+```ts
+const promise = Toast.upsert({ text: 'Uploading…' })
+
+Toast.end(promise, undefined) // end only this call
+Toast.end() // end every open call
+```
+
+Do not write `Toast.end(promise)`: JavaScript would otherwise interpret that
+single argument as the response for the broadcast overload. The public type
+rejects this form. Inside the user component, `call.end()` remains the natural
+way to finish its own `void` call.
+
 See the [Claude Code skill](skills/call-vue/SKILL.md) for the stacking model,
 `unmountingDelay` exit-transition pattern, and the single-`<Root>` constraint
 in depth.
@@ -125,6 +139,73 @@ export const Toast = createCallable<Props, Response>(ToastCard, 200 /* ms */)
 
 Inside `ToastCard`, branch on `call.ended` to trigger the leave state.
 
+## Root props and TypeScript
+
+The third generic is the type of props mounted on the Callable Root. A normal
+interface works directly; it does not need to extend `Record<string, unknown>`:
+
+```ts
+interface RootProps {
+  accent: string
+}
+
+export const Notice = createCallable<NoticeProps, void, RootProps>(NoticeCard)
+```
+
+```vue
+<Notice accent="#6366f1" />
+```
+
+Every active card reads the current value through `call.root.accent`. Updating
+the Root prop re-renders active calls. For cross-file `.vue` prop validation,
+run `vue-tsc --noEmit` in addition to a plain TypeScript check; plain `tsc`
+cannot inspect generated SFC props by itself.
+
+The Callable itself is the Root component. Mount `<Notice />`; there is no
+separate `.Root` alias. Its public type is Vue's general `Component` shape, so
+it remains valid whether the internal Root is represented as an options object
+or a functional component.
+
+## Async components
+
+`defineAsyncComponent()` can be passed directly to `createCallable`. The loader
+is not invoked until the first call creates a component instance:
+
+```ts
+import { defineAsyncComponent } from 'vue'
+import PickerLoadError from './PickerLoadError.vue'
+import PickerLoading from './PickerLoading.vue'
+
+const AsyncPicker = defineAsyncComponent({
+  loader: () => import('./PickerDialog.vue'),
+  loadingComponent: PickerLoading,
+  errorComponent: PickerLoadError,
+  delay: 0,
+})
+
+export const Picker = createCallable<PickerProps, PickedItem>(AsyncPicker)
+```
+
+Use Vue's `loadingComponent`/`errorComponent` options when a call may be added
+after its surrounding `<Suspense>` has already resolved. Ending a call while
+its component is still loading does not resurrect it when the loader finishes.
+
+## SSR
+
+Callable Roots are safe to render repeatedly with Vue SSR: server-side setup
+does not register a live Root or leak the Root count into later requests. The
+user component is not rendered on the server while the stack is empty.
+`call()` and `upsert()` remain client-imperative APIs and throw
+`No <Root> found!` until the Root's client `onMounted` hook has run.
+
+## Accessibility responsibility
+
+`call-vue` controls stack and Promise lifecycles; it is deliberately headless.
+Dialog semantics remain the user component's responsibility. A production
+dialog should at least provide an accessible name/description, move focus
+inside on open, trap Tab, close with Escape when appropriate, restore focus on
+unmount, and respect reduced-motion preferences.
+
 ## Stacking
 
 Every `call()` while a previous one is still open stacks on top of it —

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Component, DefineComponent } from "vue";
+import { Component } from "vue";
 //#region src/createCallable/types.d.ts
 /**
  * Properties every `call.*` context carries, regardless of stack position.
@@ -40,19 +40,18 @@ type PropsWithCall<Props, Response, RootProps> = Props & {
  * or functional) whose props satisfy `PropsWithCall<Props, Response, RootProps>`.
  */
 type UserComponent<Props, Response, RootProps> = Component<PropsWithCall<Props, Response, RootProps>>;
+type EndFunction<Response> = ((promise: Promise<Response>, response: [Response] extends [void] ? undefined : Response) => void) & ([Response] extends [void] ? (response?: undefined) => void : (response: Response) => void);
 /**
  * What `createCallable` returns.
  *
  * The callable is the Root component itself — mount it with `<Confirm />`
- * (or `<Confirm.Root />`) and use the imperative methods (`call`, `upsert`,
- * `end`, `update`) as properties on the very same object.
+ * and use the imperative methods (`call`, `upsert`, `end`, `update`) as
+ * properties on the very same object.
  */
-type Callable<Props, Response, RootProps> = DefineComponent<RootProps> & {
-  /** Alias for the callable itself — `Confirm.Root === Confirm`. */
-  Root: DefineComponent<RootProps>;
+type Callable<Props, Response, RootProps> = Component<RootProps> & {
   call: CallFunction<Props, Response>;
   upsert: UpsertFunction<Props, Response>;
-  end: ((promise: Promise<Response>, response: Response) => void) & ((response: Response) => void);
+  end: EndFunction<Response>;
   update: ((promise: Promise<Response>, props: Partial<Props>) => void) & ((props: Partial<Props>) => void);
 };
 //#endregion
@@ -65,8 +64,8 @@ type Callable<Props, Response, RootProps> = DefineComponent<RootProps> & {
  *
  * This is a Vue-native port of react-call's `createCallable` — see
  * `skills/call-vue/SKILL.md` for the full mental model (stack, upsert,
- * mutation flow).
+ * lifecycle constraints).
  */
-declare function createCallable<Props = void, Response = void, RootProps extends Record<string, unknown> = Record<string, never>>(UserComponent: UserComponent<Props, Response, RootProps>, unmountingDelay?: number): Callable<Props, Response, RootProps>;
+declare function createCallable<Props = void, Response = void, RootProps extends object = {}>(UserComponent: UserComponent<Props, Response, RootProps>, unmountingDelay?: number): Callable<Props, Response, RootProps>;
 //#endregion
 export { type CallContext, type CallFunction, type Callable, type PropsWithCall, type UpsertFunction, type UserComponent, createCallable };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { defineComponent, h, onUnmounted, shallowRef } from "vue";
+import { defineComponent, h, onMounted, onUnmounted, shallowRef } from "vue";
 //#region src/createCallable/store.ts
 /**
 * Vue-native replacement for react-call's `useSyncExternalStore`-backed
@@ -58,7 +58,7 @@ function createStackStore() {
 *
 * This is a Vue-native port of react-call's `createCallable` — see
 * `skills/call-vue/SKILL.md` for the full mental model (stack, upsert,
-* mutation flow).
+* lifecycle constraints).
 */
 function createCallable(UserComponent, unmountingDelay = 0) {
 	const store = createStackStore();
@@ -121,13 +121,13 @@ function createCallable(UserComponent, unmountingDelay = 0) {
 		});
 		return promise;
 	};
-	const end = (...args) => {
+	const end = ((...args) => {
 		const targeted = args.length === 2;
 		const promise = targeted ? args[0] : null;
 		const response = targeted ? args[1] : args[0];
 		if (!targeted || promise === store.getUpsertPromise()) store.setUpsertPromise(null);
 		return createEnd(promise)(response);
-	};
+	});
 	const update = (...args) => {
 		const targeted = args.length === 2;
 		store.set(targeted ? args[0] : null, (c) => ({
@@ -142,8 +142,11 @@ function createCallable(UserComponent, unmountingDelay = 0) {
 		name: "CallableRoot",
 		inheritAttrs: false,
 		setup(_, { attrs }) {
-			const unmountRoot = store.mountRoot();
-			onUnmounted(unmountRoot);
+			let unmountRoot;
+			onMounted(() => {
+				unmountRoot = store.mountRoot();
+			});
+			onUnmounted(() => unmountRoot?.());
 			return () => store.stack.value.map((item, index, stack) => h(UserComponent, {
 				...item.props,
 				key: item.key,
@@ -159,7 +162,6 @@ function createCallable(UserComponent, unmountingDelay = 0) {
 		}
 	});
 	return Object.assign(Root, {
-		Root,
 		call,
 		upsert,
 		end,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retronew/call-vue",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Call & await Vue components like async functions — a Vue 3 port of react-call.",
   "keywords": [
     "async",
@@ -38,13 +38,13 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vue/test-utils": "^2.4.11",
     "jsdom": "^30.0.1",
     "typescript": "^7.0.2",
-    "vite-plus": "^0.2.9",
-    "vitest": "4.1.10",
+    "vite-plus": "^0.3.0",
+    "vitest": "4.1.11",
     "vue": "^3.5.41"
   },
   "peerDependencies": {

package/skills/call-vue/SKILL.md

@@ -33,7 +33,7 @@ served by routing.
   `upsert`, `end`, `update`) attached to the same object. Don't call it a
   "modal/dialog/component".
 - **Root** — the mounting form of the Callable: the bare `<Confirm />`
-  (`Confirm.Root === Confirm`, kept as an alias). Not a "provider/portal".
+  itself. There is no separate `.Root` alias. Not a "provider/portal".
 - **Call** — one imperative invocation (`Confirm.call({...})`), resolves to a
   **Response**.
 - **Stack** — the ordered list of active Calls a Root renders (not a
@@ -53,7 +53,7 @@ type Props = { message: string }
 type Response = boolean
 
 // `call` is the special injected prop (the CallContext)
-defineProps<PropsWithCall<Props, Response, Record<string, never>>>()
+defineProps<PropsWithCall<Props, Response, {}>>()
 </script>
 
 <template>
@@ -86,7 +86,8 @@ const accepted = await Confirm.call({ message: 'Continue?' })
 ```
 
 Generics are `createCallable<Props, Response, RootProps>` (all optional,
-default to `void`/`void`/`Record<string, never>`).
+default to `void`/`void`/`{}`). `RootProps` accepts a normal interface without
+extending `Record<string, unknown>`.
 
 Plain functional components work too — `createCallable` accepts anything
 matching Vue's `Component<Props>` type, including a bare
@@ -109,6 +110,10 @@ tiny callable.
 - **End / update from the caller** — `Confirm.end(promise, value)` /
   `Confirm.update(promise, partialProps)` target one Call; omit the promise
   argument to affect every currently active Call instead.
+- **Void responses** — externally, use `Toast.end(promise, undefined)` to
+  target one Call and `Toast.end()` to end all Calls. Never write
+  `Toast.end(promise)`: a single argument is the broadcast response position.
+  Inside the component, `call.end()` is valid and ends only that instance.
 
 ## Hard rules (the common failures)
 
@@ -136,6 +141,16 @@ tiny callable.
   swap into an exit-animation state; the instance stays mounted for 200ms
   after `end()` so a CSS transition (or Vue `<Transition>` wrapping the
   Callable's stack render) has time to play before removal.
+- **SSR only registers on the client.** Repeated server renders do not count as
+  mounted Roots. `call()`/`upsert()` before client `onMounted` throw
+  *"No `<Root>` found!"*.
+- **Async components load on demand.** Pass `defineAsyncComponent()` directly
+  to `createCallable`; an empty stack does not invoke the loader. Prefer its
+  `loadingComponent` and `errorComponent` options for Calls inserted after an
+  already-resolved `<Suspense>` boundary.
+- **SFC types need Vue tooling.** Use `vue-tsc --noEmit` to validate cross-file
+  `.vue` props; a plain TypeScript shim cannot prove that the business props
+  and injected `call` prop match.
 
 ## Anti-patterns
 
@@ -146,9 +161,12 @@ tiny callable.
 - Treating the Callable as a plain component to render with data props — the
   props you pass to `<Confirm />` itself are **RootProps** (shared context),
   never the per-instance data; that always goes through `.call(props)`.
-- Reaching into `call.root` for data that changes per-Call — it's constant
-  for the Root's whole lifetime (whatever `<Confirm />` was mounted with);
-  put per-Call data in the component's own props instead.
+- Reaching into `call.root` for data that changes per-Call — Root props are
+  shared by every active Call (and react to Root prop updates); put data that
+  differs per Call in the component's own props instead.
+- Treating a dialog Callable as accessible by default — the library is
+  headless. The user component owns naming, initial focus, Tab trapping,
+  Escape behavior, focus restoration, and reduced motion.
 
 ## Quick reference