@retronew/call-vue 0.2.0 → 0.4.0

package/README.md

@@ -10,6 +10,26 @@ Call & await Vue components like async functions. A Vue 3 port of
 (`createCallable`, `call`/`upsert`/`end`/`update`) built on native Vue
 reactivity — no context providers, no global store to wire up.
 
+[Documentation with live demos](https://call-vue.retronew.dev) ·
+[Examples](https://call-vue.retronew.dev/examples) ·
+[Concepts](https://call-vue.retronew.dev/concepts) ·
+[Full API reference](https://call-vue.retronew.dev/api)
+
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [API](#api)
+- [Exit transitions](#exit-transitions)
+- [Root props and TypeScript](#root-props-and-typescript)
+- [Mutation flow](#mutation-flow)
+- [Async components](#async-components)
+- [SSR](#ssr)
+- [Stacking](#stacking)
+- [Errors and troubleshooting](#errors-and-troubleshooting)
+- [Capability matrix](#capability-matrix)
+- [FAQ](#faq)
+
 ## Why
 
 Confirmation dialogs, prompts, and toasts are usually one-off components you
@@ -30,6 +50,9 @@ No global state, no extra store — `<Confirm />` mounted once *is* the stack.
 pnpm add @retronew/call-vue
 ```
 
+Use `npm install @retronew/call-vue`, `yarn add @retronew/call-vue`, or
+`bun add @retronew/call-vue` with another package manager.
+
 ## Quick start
 
 1. Define the component. It receives your own props **plus** an injected
@@ -43,7 +66,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,10 +132,37 @@ 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.
 
+### Public types
+
+All public types are flat named exports:
+
+| Type | Purpose |
+| --- | --- |
+| `CallFunction<Props, Response>` | The typed `call()` method. |
+| `UpsertFunction<Props, Response>` | The typed singleton `upsert()` method. |
+| `CallContext<Props, Response, RootProps>` | The injected `call` prop. |
+| `PropsWithCall<Props, Response, RootProps>` | Your props merged with `call`. |
+| `UserComponent<Props, Response, RootProps>` | A component accepted by `createCallable`. |
+| `Callable<Props, Response, RootProps>` | The Root component plus its imperative methods. |
+
 ## Exit transitions
 
 Pass a second argument to `createCallable` to keep an ended call mounted
@@ -125,6 +175,106 @@ 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.
+
+## Mutation flow
+
+For the common “submit → await a side effect → close only on success” flow,
+import the opt-in composable from its own subpath:
+
+```vue
+<script setup lang="ts">
+import { toRef } from 'vue'
+import type { PropsWithCall } from '@retronew/call-vue'
+import { useMutationFlow, type MutationFn } from '@retronew/call-vue/mutation-flow'
+
+type Props = { mutationFn: MutationFn<boolean> }
+const props = defineProps<PropsWithCall<Props, boolean, {}>>()
+const submit = useMutationFlow(props.call, toRef(props, 'mutationFn'))
+</script>
+
+<template>
+  <button :disabled="submit.pending" @click="submit()">Save</button>
+  <button :disabled="submit.pending" @click="props.call.end(false)">Cancel</button>
+</template>
+```
+
+`MutationFn<Response, Payload>` receives only `{ end }` and decides when to
+close the Call. If it returns or rejects without calling `end`, the Call stays
+open and `pending` clears, so the user can retry. Errors are not swallowed.
+
+When `mutationFn` is optional, `submit(payload).orEnd(value)` supplies a
+per-button fallback response only when no handler was provided. Omitting the
+chain intentionally leaves the Call open for another explicit close path.
+
+Pass a `Ref` such as `toRef(props, 'mutationFn')` when a live Call can receive
+an updated handler through `Callable.update()`.
+
+## 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 —
@@ -141,6 +291,73 @@ stack, or rendering all of them with a depth-based transform).
 - Unmounting `<Confirm />` resets its stack — a fresh mount always starts
   empty.
 
+## Errors and troubleshooting
+
+| Error or symptom | Cause and solution |
+| --- | --- |
+| `No <Root> found!` | Mount the returned Callable once and wait for client `onMounted` before calling it. During SSR, move the call to a client interaction. |
+| `Multiple instances of <Root> found!` | The same Callable is mounted in more than one live location. Keep exactly one Root for that Callable. |
+| The Promise never resolves | Every success, cancel, Escape, and backdrop path must explicitly run `call.end(response)` or an external `Callable.end(...)`. Hiding the UI is not enough. |
+| Exit animation is cut off | Match `createCallable(component, unmountingDelay)` to the CSS leave duration and style against `call.ended`. |
+| A targeted `void` end fails to type-check | Use `Toast.end(promise, undefined)`. `Toast.end()` is the broadcast form. |
+| Root data appears missing | Read mounted Root props from `call.root`; normal call props remain top-level component props. |
+
+The documentation site has the expanded
+[troubleshooting guide](https://call-vue.retronew.dev/troubleshooting).
+
+## Capability matrix
+
+This package targets `react-call`'s framework-neutral core semantics, while
+using Vue-native components and lifecycle primitives.
+
+| Capability | `call-vue` | Notes |
+| --- | --- | --- |
+| `createCallable`, `call`, `end` | Supported | Promise and broadcast/targeted semantics match the upstream core. |
+| Concurrent Stack | Supported | Every normal call remains independently active. |
+| `upsert`, `update` | Supported | Singleton Promise identity and targeted/broadcast updates are covered. |
+| Root props | Supported | Available reactively through `call.root`. |
+| Exit lifecycle | Supported | `call.ended` plus `unmountingDelay`. |
+| Vue async components | Supported | Use `defineAsyncComponent`; empty stacks stay lazy. |
+| SSR-safe Root creation | Supported | Calling remains client-only. |
+| `<Callable.Root />` alias | Not provided | The direct `<Callable />` Root is the only API; the legacy alias was removed rather than soft-deprecated. |
+| Mutation-flow helper subpath | Supported | Import `useMutationFlow` and its types from `@retronew/call-vue/mutation-flow`. |
+| Vite HMR transform | Not published | Normal Vue HMR applies, but open-call preservation is not promised yet. |
+| Multi-preview host helper | Not published | Mount one Callable Root outside repeated Storybook/Histoire previews manually. |
+
+Unsupported entries are deliberate capability boundaries, not hidden aliases.
+Do not import `react-call`-specific subpaths from this package.
+
+## FAQ
+
+### What if more than one call is active?
+
+The Root renders all Calls as a Stack in insertion order. Your component may
+show all of them, position them by `call.index`, or visually prioritize the
+latest using `call.stackSize`.
+
+### Can I place more than one Root?
+
+Not for the same Callable. You may mount one `Confirm`, one `Toast`, and one
+`Picker` together because those are three independent Callable values.
+
+### Does `upsert()` replace normal calls?
+
+No. The singleton upsert instance coexists with normal `call()` instances.
+Repeated upserts update only the singleton and return its original Promise.
+
+### Is mutation flow just an async function?
+
+The domain work is an async function. `useMutationFlow` additionally
+standardizes pending state, duplicate-submit behavior, payload typing, retry
+after failure, and the rule that only an explicit `call.end()` closes the Call.
+Those semantics are why it ships as an optional subpath rather than in the
+core entry.
+
+### Can I use Teleport?
+
+Yes. Teleport is presentation owned by your user component. Mount the Callable
+Root once, then Teleport each rendered dialog or toast to the desired target.
+
 ## Claude Code skill
 
 This package ships a [Claude Code skill](skills/call-vue/SKILL.md) covering

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/dist/mutation-flow/index.d.mts

@@ -0,0 +1,29 @@
+import { Ref } from "vue";
+//#region src/mutation-flow/index.d.ts
+/** The narrow call view exposed to a mutation handler. */
+type MutationCall<Response> = {
+  end: (response: Response) => void;
+};
+/** An async side-effect that decides when its Call should close. */
+type MutationFn<Response, Payload = void> = (call: MutationCall<Response>, payload: Payload) => Promise<void>;
+/** Runs a required mutation and exposes its in-flight state. */
+type Trigger<Payload> = ((payload: Payload) => void) & {
+  pending: boolean;
+};
+/** Adds a per-callsite fallback for an optional mutation. */
+type ChainTrigger<Payload, Response> = ((payload: Payload) => {
+  orEnd: (value: Response) => void;
+}) & {
+  pending: boolean;
+};
+type MutationSource<Response, Payload> = MutationFn<Response, Payload> | Readonly<Ref<MutationFn<Response, Payload> | undefined>> | undefined;
+/**
+ * Coordinates an async submission with a Call's lifecycle.
+ *
+ * Pass a `Ref` when the handler can change while the Call is mounted, such as
+ * when `Callable.update()` replaces a `mutationFn` prop.
+ */
+declare function useMutationFlow<Response, Payload = void>(call: MutationCall<Response>, mutationFn: MutationFn<Response, Payload> | Readonly<Ref<MutationFn<Response, Payload>>>): Trigger<Payload>;
+declare function useMutationFlow<Response, Payload = void>(call: MutationCall<Response>, mutationFn: MutationSource<Response, Payload>): ChainTrigger<Payload, Response>;
+//#endregion
+export { ChainTrigger, MutationCall, MutationFn, Trigger, useMutationFlow };

package/dist/mutation-flow/index.mjs

@@ -0,0 +1,29 @@
+import { isRef, ref } from "vue";
+//#region src/mutation-flow/index.ts
+const noopChain = { orEnd: () => {} };
+function resolveMutation(source) {
+	return isRef(source) ? source.value : source;
+}
+function useMutationFlow(call, mutationSource) {
+	const pending = ref(false);
+	let inFlight = false;
+	const trigger = ((payload) => {
+		if (inFlight) return noopChain;
+		const mutationFn = resolveMutation(mutationSource);
+		if (!mutationFn) return { orEnd: (value) => call.end(value) };
+		inFlight = true;
+		pending.value = true;
+		mutationFn(call, payload).finally(() => {
+			inFlight = false;
+			pending.value = false;
+		});
+		return noopChain;
+	});
+	Object.defineProperty(trigger, "pending", {
+		enumerable: true,
+		get: () => pending.value
+	});
+	return trigger;
+}
+//#endregion
+export { useMutationFlow };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retronew/call-vue",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Call & await Vue components like async functions — a Vue 3 port of react-call.",
   "keywords": [
     "async",
@@ -32,19 +32,23 @@
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
     },
+    "./mutation-flow": {
+      "types": "./dist/mutation-flow/index.d.mts",
+      "default": "./dist/mutation-flow/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "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