@retronew/call-vue 0.3.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
@@ -127,6 +150,19 @@ 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
@@ -166,6 +202,39 @@ 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
@@ -222,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/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.3.0",
+  "version": "0.4.0",
   "description": "Call & await Vue components like async functions — a Vue 3 port of react-call.",
   "keywords": [
     "async",
@@ -32,6 +32,10 @@
       "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": {