Skip to content

Commit 8169fc4

Browse files
committed
docs(context): chain-based fallback delivery + Manual-close path
Glossary update reflecting the API redesign captured in PR #82 grilling: - Trigger now describes the two callable shapes (void return when MutationFn is required; chain object with `.orEnd` when MutationFn may be undefined). - Fallback response is now delivered at the Trigger callsite via `.orEnd(value)` instead of via the hook's options object. - New term: Manual-close path — the legitimate branch where neither MutationFn nor Fallback response closes the Call (e.g. the consumer wants a "No" button to handle the close). - Relationships and example dialogue updated to reflect the new three-state model. ADR-0014 amendment in a follow-up commit.
1 parent c706ab9 commit 8169fc4

1 file changed

Lines changed: 25 additions & 9 deletions

File tree

CONTEXT.md

Lines changed: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -74,17 +74,29 @@ _Avoid_: MutationContext (would falsely suggest a separate React
7474
Context), Closer.
7575

7676
**Trigger**:
77-
The callable function returned by `useMutationFlow`. Calling it runs the
78-
MutationFn (or the fallback) while exposing `trigger.pending`. One
79-
trigger per call to `useMutationFlow`.
77+
The callable function returned by `useMutationFlow`. Calling it runs
78+
the MutationFn while exposing `trigger.pending`. When the MutationFn
79+
may be undefined, the Trigger's call returns a chain object that
80+
exposes `.orEnd(value)` to deliver the Fallback response at the
81+
callsite.
8082
_Avoid_: Submit, runner, dispatcher.
8183

8284
**Fallback response**:
83-
The Response value used when `submit()` fires but no MutationFn was
84-
provided. Required in `useMutationFlow`'s options object exactly when
85-
the MutationFn parameter is typed as possibly-undefined.
85+
The Response value used to close the Call when `submit()` fires but
86+
no MutationFn was provided. Delivered at the Trigger callsite via
87+
`.orEnd(value)`. Only meaningful when the MutationFn parameter is
88+
typed as possibly-undefined; omitting it puts the Call on the
89+
Manual-close path.
8690
_Avoid_: Default, no-op.
8791

92+
**Manual-close path**:
93+
The execution branch where neither a MutationFn nor a Fallback
94+
response closes the Call — the consumer leaves it open intentionally
95+
(e.g. for a "No" button or a click-outside to handle the close). Only
96+
reachable when the MutationFn parameter is typed as possibly-undefined
97+
and the Trigger callsite omits `.orEnd`.
98+
_Avoid_: Stuck call, dangling call, no-op path.
99+
88100
## Relationships
89101

90102
- A **Callable** produces zero or more **Calls** over its lifetime.
@@ -96,6 +108,9 @@ _Avoid_: Default, no-op.
96108
**MutationCall** view of the **CallContext**, not the full one.
97109
- The **Fallback response** is only meaningful when the **MutationFn**
98110
may be absent at the **Call** site.
111+
- When the **MutationFn** is absent at runtime and the **Trigger**
112+
callsite omits the **Fallback response**, the **Call** is on the
113+
**Manual-close path**.
99114

100115
## Example dialogue
101116

@@ -107,9 +122,10 @@ _Avoid_: Default, no-op.
107122
>
108123
> **Maintainer:** "And if the caller never provides a **MutationFn**?"
109124
>
110-
> **Designer:** "Then `submit()` closes the **Call** with the
111-
> **Fallback response** — but the type signature only lets you omit the
112-
> fallback when the **MutationFn** parameter is non-nullable."
125+
> **Designer:** "It depends what the **Trigger** callsite chains. With
126+
> `.orEnd(value)`, the **Call** closes with the **Fallback response**.
127+
> Without it, the **Call** is on the **Manual-close path** — open
128+
> until something else closes it."
113129
114130
## Flagged ambiguities
115131

0 commit comments

Comments
 (0)