feat: mutation-flow composition hook (lighter alternative to PR #81)

[desko27]

Summary

Closes #22 with a lighter alternative to PR #81. Ships useMutationFlow as an opt-in composition hook from a new subpath entry react-call/mutation-flow, leaving createCallable and CallContext untouched.

import { createCallable } from 'react-call'
import { useMutationFlow, type MutationFn } from 'react-call/mutation-flow'

type Props = { mutationFn: MutationFn<boolean> }

export const Confirm = createCallable<Props, boolean>(
  ({ call, mutationFn }) => {
    const submit = useMutationFlow(call, mutationFn)
    return (
      <button disabled={submit.pending} onClick={() => submit()}>
        Yes
      </button>
    )
  },
)

await Confirm.call({
  mutationFn: async (call) => {
    try {
      await api.delete(id)
      call.end(true)
    } catch (e) {
      toast.error(e) // dialog stays open, pending clears
    }
  },
})

The mutationFn receives a narrow MutationCall view (just { end }) — no RootProps leaks into the handler. Throws are swallowed by the trigger so the call stays open for retry.

When the mutationFn parameter is typed as possibly-undefined, submit(payload) returns a chain object whose .orEnd(value) delivers the Fallback response at the callsite. Each button can chain its own value:

// Picker — per-callsite fallback aligned with payload
<button onClick={() => submit({ choice: 'A' }).orEnd('A')}>A</button>
<button onClick={() => submit({ choice: 'B' }).orEnd('B')}>B</button>

If the consumer prefers to leave the call open when no mutationFn is provided (e.g. let a "No" button handle the close), they omit .orEnd — the Manual-close path. See ADR-0014 for the full design rationale, the rejected alternatives (primitive on CallContext PR #81 shape; options-object signature with TS-enforced fallback), and the trade-offs.

Domain vocabulary in CONTEXT.md: MutationFlow, MutationFn, MutationCall, Trigger, Fallback response, Manual-close path.

How this compares to #81

	PR #81	This PR
Changes in createCallable core	+159 LOC	0
Changes in CallContext	adds pending, mutate	none
Generic reorder	BREAKING (<Props, Response, Payload, RootProps>)	none
Main bundle budget	1 KB → 1.25 KB brotli	unchanged (1 KB)
Where mutationFn lives	CallOptions (2nd arg of call() / upsert())	regular prop
Mid-call mutationFn swap via Callable.update	not possible (set-once)	works (it's a prop)
Payload typing scope	3rd generic of createCallable (per-Callable)	generic of the hook (per-trigger)
Fallback declaration site	CallOptions on call()	callsite chain .orEnd(value) (per-button)
Callable.mutate from caller scope	deferred (additive door open)	structurally absent
HMR preservation of pending across saves	yes (store-level)	no (local useState)

Bundle impact

• dist/main.js — 804 B brotli (unchanged from main)
• dist/main.cjs — 885 B brotli (unchanged from main)
• dist/mutation-flow.js — 268 B brotli (new, opt-in)
• dist/mutation-flow.cjs — 344 B brotli (new, opt-in)

Consumers who never import the subpath pay zero.

Commits

1. 2a3b897 docs(adr): ADR-0014 + CONTEXT.md
2. 9b56279 feat(react-call): mutation-flow subpath hook (initial implementation)
3. c706ab9 refactor(mutation-flow): options-object signature iteration
4. 8169fc4 docs(context): chain-based fallback delivery + Manual-close path
5. ff5bcd0 docs(adr-0014): amend for chain-based signature
6. db6846b refactor(mutation-flow): positional signature + chain-based fallback
7. 9ee7b96 chore(claude): add empty attribution config
8. 7e41c5a chore(skills): add crafting-effective-readmes from softaworks/agent-toolkit
9. 3f24a75 docs(readme): rewrite useMutationFlow section via crafting-effective-readmes

Commit 3 (options-object iteration) is preserved as part of the design trail recorded in ADR-0014's "Considered options" section.

Out of scope (same deferrals as PR #81)

• AbortSignal on MutationCall — additive type-wise, no breaking change to add later
• submit.error on the trigger — additive without breaking change
• Callable.mutate(...) from caller scope — structurally absent in this design (see ADR-0014 "Consequences"); PR feat: async mutation primitive (call.pending + call.mutate) #81 left this door open at the cost of the primitive-on-CallContext shape

Test plan

• pnpm vitest run — 87/87 pass (11 in mutation-flow.test.tsx) covering: pending lifecycle, throw-swallow, fallback via .orEnd, per-callsite fallback (Picker A/B), Manual-close path, re-entry guard, payload forwarding, mid-call mutationFn swap, external end during pending
• pnpm check:types — clean
• pnpm lint — clean
• pnpm --filter react-call run build — three entries emitted (main, vite, mutation-flow)
• pnpm --filter react-call size — all four budgets pass (main unchanged at 804/885 B; mutation-flow 268 B ESM / 344 B CJS, below 300/400 B limits)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-call	Ready	Preview, Comment	May 24, 2026 1:43pm