refactor(mutation-flow): positional signature + chain-based fallback

useMutationFlow goes back to two positional arguments:

  useMutationFlow(call, mutationFn)

The Fallback response is now delivered at the Trigger callsite via a
method chain instead of via the hook's options object:

  // Required handler
  const submit = useMutationFlow(call, mutationFn)
  <button onClick={() => submit()}>Yes</button>

  // Optional handler — chain .orEnd at the callsite
  const submit = useMutationFlow(call, mutationFn)
  <button onClick={() => submit().orEnd(true)}>Yes</button>

  // Picker — each button chains its own value
  <button onClick={() => submit({ choice: 'A' }).orEnd('A')}>A</button>
  <button onClick={() => submit({ choice: 'B' }).orEnd('B')}>B</button>

Two TypeScript overloads on the mutationFn argument keep the chain
out of reach when the handler is non-nullable: required → submit
returns void; possibly-undefined → submit returns
`{ orEnd(value): void }`. Two exported types describe the shapes:
`Trigger<Payload>` (void return) and `ChainTrigger<Payload, Response>`
(chain return).

When the handler may be undefined and the callsite omits `.orEnd`,
the call stays open until something else closes it (the Manual-close
path documented in ADR-0014).

New tests cover per-callsite fallback (Picker) and the Manual-close
path. Bundle still well within budget: 268 B brotli ESM (limit 300),
344 B brotli CJS (limit 400).

Author: desko27

.changeset/feat-mutation-flow.md

@@ -2,7 +2,7 @@
 "react-call": minor
 ---
 
-- **New `react-call/mutation-flow` subpath entry** — `useMutationFlow(call, { mutationFn, fallback? })` is an opt-in hook that wraps the canonical async-submission flow (click → run async → keep open on failure, end on success). The main `react-call` entry stays unchanged: bundle size and API surface of `createCallable` / `CallContext` are not affected. Consumers who never import the subpath pay zero.
+- **New `react-call/mutation-flow` subpath entry** — `useMutationFlow(call, mutationFn)` is an opt-in hook that wraps the canonical async-submission flow (click → run async → keep open on failure, end on success). The main `react-call` entry stays unchanged: bundle size and API surface of `createCallable` / `CallContext` are not affected. Consumers who never import the subpath pay zero.
 
   ```tsx
   import { createCallable } from 'react-call'
@@ -12,7 +12,7 @@
 
   export const Confirm = createCallable<Props, boolean>(
     ({ call, mutationFn }) => {
-      const submit = useMutationFlow(call, { mutationFn })
+      const submit = useMutationFlow(call, mutationFn)
       return (
         <button disabled={submit.pending} onClick={() => submit()}>
           Yes
@@ -33,6 +33,10 @@
   })
   ```
 
-  The `mutationFn` receives a narrow `MutationCall<Response>` view (`{ end }`) — no `RootProps` ever leaks into the handler's signature. Throws are swallowed by the trigger so the call stays open for retry; the handler decides when (if ever) to `call.end()`. The options object has two overloads: `{ mutationFn }` when the parameter is required, and `{ mutationFn, fallback }` (with `fallback` required by the type system) when `mutationFn` may be undefined. See [ADR-0014](docs/adr/0014-mutation-flow-as-composition-hook.md) for the design rationale and the trade-off versus making this a primitive on `CallContext`.
+  The `mutationFn` receives a narrow `MutationCall<Response>` view (`{ end }`) — no `RootProps` ever leaks into the handler's signature. Throws are swallowed by the trigger so the call stays open for retry; the handler decides when (if ever) to `call.end()`.
 
-- **Exports**: `MutationFn`, `MutationCall`, `Trigger`, `useMutationFlow` from `react-call/mutation-flow`.
+  When the `mutationFn` parameter is typed as possibly-undefined, `submit(payload)` returns a chain object whose `.orEnd(value)` closes the call with a fallback at the callsite — `submit().orEnd(true)`. Each button can chain its own value (Picker: `.orEnd('A')` / `.orEnd('B')`). Omitting the chain is also valid: the call stays open until something else closes it.
+
+  See [ADR-0014](docs/adr/0014-mutation-flow-as-composition-hook.md) for the design rationale and the trade-off versus making this a primitive on `CallContext`.
+
+- **Exports**: `MutationFn`, `MutationCall`, `Trigger`, `ChainTrigger`, `useMutationFlow` from `react-call/mutation-flow`.

README.md

@@ -278,7 +278,7 @@ type Props = {
 
 export const Confirm = createCallable<Props, boolean>(
   ({ call, message, mutationFn }) => {
-    const submit = useMutationFlow(call, { mutationFn })
+    const submit = useMutationFlow(call, mutationFn)
     return (
       <div role="dialog">
         <p>{message}</p>
@@ -314,9 +314,10 @@ can retry. The `mutationFn` decides when (if ever) to call `call.end()`.
 
 If your component should still close cleanly when no `mutationFn` was
 provided (e.g. a plain "Are you sure?" without any side effect), type the
-prop as optional and pass a `fallback` alongside it in the options
-object. The type system enforces this — `fallback` is required exactly
-when the `mutationFn` parameter may be undefined.
+prop as optional and chain `.orEnd(value)` at the submit callsite. When
+the `mutationFn` parameter may be undefined, `submit(payload)` returns
+a chain object exposing `.orEnd(value)`; when it's provided, the chain
+is a no-op and the managed flow runs as normal.
 
 ```tsx
 type Props = {
@@ -326,17 +327,44 @@ type Props = {
 
 export const Confirm = createCallable<Props, boolean>(
   ({ call, message, mutationFn }) => {
-    //                                                       ↓ closes with `true` if no mutationFn
-    const submit = useMutationFlow(call, { mutationFn, fallback: true })
+    const submit = useMutationFlow(call, mutationFn)
     return (
-      <button disabled={submit.pending} onClick={() => submit()}>
+      //                                          ↓ closes with `true` if no mutationFn
+      <button disabled={submit.pending} onClick={() => submit().orEnd(true)}>
         Yes
       </button>
     )
   },
 )
 ```
 
+Because the fallback is declared at the callsite (not on the hook), each
+button can chain its own value. Useful in pickers where the response is
+exactly the option the user picked:
+
+```tsx
+type Props = {
+  mutationFn?: MutationFn<'A' | 'B', { choice: 'A' | 'B' }>
+}
+
+export const Picker = createCallable<Props, 'A' | 'B'>(
+  ({ call, mutationFn }) => {
+    const submit = useMutationFlow(call, mutationFn)
+    return (
+      <>
+        <button onClick={() => submit({ choice: 'A' }).orEnd('A')}>A</button>
+        <button onClick={() => submit({ choice: 'B' }).orEnd('B')}>B</button>
+      </>
+    )
+  },
+)
+```
+
+If you'd rather leave the call open when no `mutationFn` was provided —
+e.g. let the user dismiss via a "No" button — omit the chain entirely.
+`submit()` is a no-op in that case; the dialog stays mounted until
+something else closes it.
+
 ## Passing a runtime payload
 
 `submit(payload)` forwards a typed payload to the `mutationFn`. Useful
@@ -348,7 +376,7 @@ type Props = {
 }
 
 export const Picker = createCallable<Props, string>(({ call, mutationFn }) => {
-  const submit = useMutationFlow(call, { mutationFn })
+  const submit = useMutationFlow(call, mutationFn)
   return (
     <>
       <button onClick={() => submit({ choice: 'A' })}>A</button>

packages/react-call/src/__tests__/mutation-flow.test.tsx

@@ -6,9 +6,11 @@ import { type MutationFn, useMutationFlow } from '../mutation-flow'
 import type * as ReactCall from '../types.public'
 import { withAct } from './shared/act'
 
-// Component fixtures cover the two consumer patterns: a Required-handler
-// dialog (no fallback) and an Optional-handler dialog (fallback required
-// by the type system because mutationFn may be undefined).
+// Component fixtures cover the three consumer patterns:
+//   - Required handler: submit() runs the mutation; no chain.
+//   - Optional handler with Fallback response: submit().orEnd(value).
+//   - Picker with per-callsite fallbacks: each button chains its own
+//     .orEnd value, aligned with its payload.
 
 type RequiredProps = { mutationFn: MutationFn<boolean> }
 
@@ -18,7 +20,7 @@ const RequiredComponent: ReactCall.UserComponent<
   {}
 > = ({ call, mutationFn }) => {
   const a11yId = useId()
-  const submit = useMutationFlow(call, { mutationFn })
+  const submit = useMutationFlow(call, mutationFn)
   return (
     <div role="dialog" aria-labelledby={a11yId}>
       <p id={a11yId}>Are you sure?</p>
@@ -31,7 +33,11 @@ const RequiredComponent: ReactCall.UserComponent<
       >
         Yes
       </button>
-      <button type="button" onClick={() => call.end(false)}>
+      <button
+        type="button"
+        data-testid="cancel"
+        onClick={() => call.end(false)}
+      >
         No
       </button>
     </div>
@@ -47,14 +53,14 @@ const OptionalComponent: ReactCall.UserComponent<
   boolean,
   {}
 > = ({ call, mutationFn }) => {
-  const submit = useMutationFlow(call, { mutationFn, fallback: true })
+  const submit = useMutationFlow(call, mutationFn)
   return (
     <button
       type="button"
       data-testid="submit"
       data-pending={submit.pending}
       disabled={submit.pending}
-      onClick={() => submit()}
+      onClick={() => submit().orEnd(true)}
     >
       Yes
     </button>
@@ -69,7 +75,7 @@ const PayloadComponent: ReactCall.UserComponent<PayloadProps, string, {}> = ({
   call,
   mutationFn,
 }) => {
-  const submit = useMutationFlow(call, { mutationFn })
+  const submit = useMutationFlow(call, mutationFn)
   return (
     <>
       <button type="button" onClick={() => submit({ choice: 'A' })}>
@@ -84,6 +90,55 @@ const PayloadComponent: ReactCall.UserComponent<PayloadProps, string, {}> = ({
 
 const Payload = createCallable(PayloadComponent)
 
+type PickerProps = {
+  mutationFn?: MutationFn<'A' | 'B', { choice: 'A' | 'B' }>
+}
+
+const PickerComponent: ReactCall.UserComponent<PickerProps, 'A' | 'B', {}> = ({
+  call,
+  mutationFn,
+}) => {
+  const submit = useMutationFlow(call, mutationFn)
+  return (
+    <>
+      <button type="button" onClick={() => submit({ choice: 'A' }).orEnd('A')}>
+        A
+      </button>
+      <button type="button" onClick={() => submit({ choice: 'B' }).orEnd('B')}>
+        B
+      </button>
+    </>
+  )
+}
+
+const Picker = createCallable(PickerComponent)
+
+type ManualCloseProps = { mutationFn?: MutationFn<boolean> }
+
+const ManualCloseComponent: ReactCall.UserComponent<
+  ManualCloseProps,
+  boolean,
+  {}
+> = ({ call, mutationFn }) => {
+  const submit = useMutationFlow(call, mutationFn)
+  return (
+    <div role="dialog">
+      <button type="button" data-testid="submit" onClick={() => submit()}>
+        Yes
+      </button>
+      <button
+        type="button"
+        data-testid="cancel"
+        onClick={() => call.end(false)}
+      >
+        No
+      </button>
+    </div>
+  )
+}
+
+const ManualClose = createCallable(ManualCloseComponent)
+
 describe('useMutationFlow — pending lifecycle', () => {
   test('pending flips true while the mutationFn is in-flight, false when it settles', async () => {
     let resolveMutation!: () => void
@@ -129,8 +184,8 @@ describe('useMutationFlow — pending lifecycle', () => {
   })
 })
 
-describe('useMutationFlow — fallback', () => {
-  test('submit() without a mutationFn closes the call with the fallback response', async () => {
+describe('useMutationFlow — fallback via .orEnd', () => {
+  test('submit().orEnd(value) closes the call with the fallback when no mutationFn was provided', async () => {
     render(<Optional />)
     const promise = withAct(() => Optional.call({}))
 
@@ -141,7 +196,7 @@ describe('useMutationFlow — fallback', () => {
     await expect(promise).resolves.toBe(true)
   })
 
-  test('submit() with a mutationFn still runs the managed flow, ignoring the fallback', async () => {
+  test('submit().orEnd(value) with a mutationFn runs the managed flow and the orEnd value is ignored', async () => {
     const mutationFn = vi.fn<MutationFn<boolean>>(async (call) => {
       call.end(false)
     })
@@ -158,6 +213,48 @@ describe('useMutationFlow — fallback', () => {
   })
 })
 
+describe('useMutationFlow — per-callsite fallback', () => {
+  test('the A button chains .orEnd("A")', async () => {
+    render(<Picker />)
+    const promise = withAct(() => Picker.call({}))
+
+    await act(async () => {
+      fireEvent.click(screen.getByText('A'))
+    })
+    await expect(promise).resolves.toBe('A')
+  })
+
+  test('the B button chains .orEnd("B")', async () => {
+    render(<Picker />)
+    const promise = withAct(() => Picker.call({}))
+
+    await act(async () => {
+      fireEvent.click(screen.getByText('B'))
+    })
+    await expect(promise).resolves.toBe('B')
+  })
+})
+
+describe('useMutationFlow — Manual-close path', () => {
+  test('submit() without a chain leaves the call open when no mutationFn was provided', async () => {
+    render(<ManualClose />)
+    const promise = withAct(() => ManualClose.call({}))
+
+    await act(async () => {
+      fireEvent.click(screen.getByTestId('submit'))
+    })
+
+    // The call is still open — submit() was a no-op because no mutationFn
+    // and no .orEnd chain. The dialog waits for the user to close it.
+    expect(screen.getByRole('dialog')).toBeInTheDocument()
+
+    await act(async () => {
+      fireEvent.click(screen.getByTestId('cancel'))
+    })
+    await expect(promise).resolves.toBe(false)
+  })
+})
+
 describe('useMutationFlow — re-entry guard', () => {
   test('a second submit() while pending is a no-op', async () => {
     let resolveMutation!: () => void

packages/react-call/src/mutation-flow/index.ts

@@ -21,49 +21,53 @@ export type MutationFn<Response, Payload = void> = (
 ) => Promise<void>
 
 /**
- * The callable returned by `useMutationFlow`. `pending` reflects the
- * in-flight state for the UI; calling the trigger runs the MutationFn
- * (or the fallback, when no MutationFn is provided).
+ * The callable returned by `useMutationFlow` when the MutationFn
+ * parameter is non-nullable. `pending` reflects the in-flight state for
+ * the UI; calling the trigger runs the MutationFn.
  */
 export type Trigger<Payload> = ((payload: Payload) => void) & {
   pending: boolean
 }
 
-// Overloads encode the invariant "fallback is required iff mutationFn
-// may be undefined". When the consumer types the prop as required, the
-// fallback-less options shape applies. When the prop is possibly-
-// undefined, TypeScript forces the shape that requires `fallback`. No
-// dead-weight optional field leaks into the required-handler case.
+/**
+ * The callable returned by `useMutationFlow` when the MutationFn
+ * parameter may be undefined. Calling the trigger returns a chain
+ * object exposing `.orEnd(value)`, which the consumer uses to deliver
+ * the Fallback response at the callsite. When the MutationFn is
+ * actually present at runtime, `.orEnd` is a no-op.
+ */
+export type ChainTrigger<Payload, Response> = ((payload: Payload) => {
+  orEnd: (value: Response) => void
+}) & { pending: boolean }
+
+const NOOP_CHAIN = { orEnd: () => {} }
+
+// Overloads encode the invariant "the Fallback response is reachable
+// iff mutationFn may be undefined". Required handler → submit returns
+// void. Possibly-undefined handler → submit returns a chain object
+// whose `.orEnd(value)` delivers the fallback at the callsite.
 export function useMutationFlow<Response, Payload = void>(
   call: MutationCall<Response>,
-  options: { mutationFn: MutationFn<Response, Payload> },
+  mutationFn: MutationFn<Response, Payload>,
 ): Trigger<Payload>
 export function useMutationFlow<Response, Payload = void>(
   call: MutationCall<Response>,
-  options: {
-    mutationFn: MutationFn<Response, Payload> | undefined
-    fallback: Response
-  },
-): Trigger<Payload>
+  mutationFn: MutationFn<Response, Payload> | undefined,
+): ChainTrigger<Payload, Response>
 export function useMutationFlow<Response, Payload = void>(
   call: MutationCall<Response>,
-  options: {
-    mutationFn: MutationFn<Response, Payload> | undefined
-    fallback?: Response
-  },
-): Trigger<Payload> {
-  const { mutationFn, fallback } = options
+  mutationFn: MutationFn<Response, Payload> | undefined,
+): ChainTrigger<Payload, Response> {
   const [pending, setPending] = useState(false)
   // Synchronous re-entry guard. `pending` state alone can't guard against
   // a second call dispatched programmatically inside the same event-loop
   // turn (state hasn't flushed yet); the ref does.
   const inFlightRef = useRef(false)
 
   const trigger = ((payload: Payload) => {
-    if (inFlightRef.current) return
+    if (inFlightRef.current) return NOOP_CHAIN
     if (!mutationFn) {
-      call.end(fallback as Response)
-      return
+      return { orEnd: (value: Response) => call.end(value) }
     }
     inFlightRef.current = true
     setPending(true)
@@ -73,7 +77,8 @@ export function useMutationFlow<Response, Payload = void>(
         inFlightRef.current = false
         setPending(false)
       })
-  }) as Trigger<Payload>
+    return NOOP_CHAIN
+  }) as ChainTrigger<Payload, Response>
   trigger.pending = pending
 
   return trigger