@niwa-labs/ui-kit 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +29 -2
  3. package/package.json +31 -4
  4. package/src/agent/diff-view.tsx +62 -0
  5. package/src/agent/execution-track.tsx +201 -0
  6. package/src/agent/guard.ts +121 -0
  7. package/src/agent/guarded-action.tsx +272 -0
  8. package/src/agent/id-chip.tsx +102 -0
  9. package/src/agent/markdown.tsx +34 -0
  10. package/src/agent/payload.ts +42 -0
  11. package/src/agent/phase-plan.tsx +183 -0
  12. package/src/agent/plan-impact.ts +104 -0
  13. package/src/agent/state.tsx +75 -0
  14. package/src/agent/tool-call.tsx +106 -0
  15. package/src/agent/transcript.tsx +88 -0
  16. package/src/execution-track.css +327 -0
  17. package/src/index.ts +76 -0
  18. package/src/lib/cn.ts +19 -0
  19. package/src/page-layout.css +183 -0
  20. package/src/theme.css +136 -0
  21. package/src/ui/badge.tsx +32 -0
  22. package/src/ui/button.tsx +38 -0
  23. package/src/ui/collapsible.tsx +13 -0
  24. package/src/ui/data-value.tsx +211 -0
  25. package/src/ui/message.tsx +81 -0
  26. package/src/ui/page-layout.tsx +33 -0
  27. package/src/ui/schema-view.tsx +144 -0
  28. package/src/ui/spinner.tsx +16 -0
  29. package/src/ui/tabs.tsx +63 -0
  30. package/src/ui/tooltip.tsx +50 -0
  31. package/src/ui/trace.tsx +100 -0
  32. package/test/browser.test.ts +13 -0
  33. package/test/diff-view.test.tsx +50 -0
  34. package/test/guard.test.ts +113 -0
  35. package/test/guarded-action.test.tsx +229 -0
  36. package/test/helpers.test.ts +83 -0
  37. package/test/phase-plan.test.tsx +146 -0
  38. package/test/plan.test.ts +71 -0
  39. package/test/render.test.tsx +62 -0
  40. package/test/structured-values.test.tsx +31 -0
  41. package/test/tabs.test.tsx +90 -0
  42. package/tsconfig.json +16 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Niwa Labs contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,30 @@
1
- # Temporary Holding Version
1
+ # @niwa-labs/ui-kit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The shared React components of the cockpit, on Tailwind 4 and Base UI.
4
+
5
+ - `src/theme.css`: design tokens as CSS variables (light and dark), the work-state colours and
6
+ the `shimmer` utility. The application imports Tailwind, then this file.
7
+ - `PageHeading` and `PageSection` lay out titles, context and action slots for
8
+ the shell and independently loaded plugin pages. Both accept ordinary React
9
+ children and HTML attributes.
10
+ - Primitives: button, badge, tooltip, tabs, collapsible, spinner, and the `Trace` and `Message`
11
+ parts that agent steps and turns are built from.
12
+ - Agent blocks: `IdChip`, `StateRing`, `ToolCall`, `Markdown` (streaming, highlighted code),
13
+ `DiffView`, `Transcript` (virtualised, follows the bottom while the reader is there).
14
+ - `PhaseSequence` shows the declared plan, including phases still ahead.
15
+ `ExecutionTrack` takes the full ordered phase plan and the observed steps.
16
+ Its detail view shows every declared phase up front. It follows the active
17
+ phase until the reader selects another. Steps outside the plan can be
18
+ passed as `looseSteps`. Phase details include overlapping branches, timestamps
19
+ and duration bars on a shared scale. Pass timestamps in epoch
20
+ milliseconds and pass a link as a step title to enable navigation.
21
+ - `ActivityLabel` and `MiniPhaseTrack` can be used on lists and plugin pages.
22
+ The kit owns motion and honours reduced motion. The plugin maps its own
23
+ events to working, starting, human, timer or paused activity and clears
24
+ activity on settled work. The kit never connects to a host or routes links.
25
+ - `PhasePlan`: phases and steps of a run with small recompute and stop controls. They ask in
26
+ place: the first press explains what will be affected, a second press or a held press
27
+ confirms, and a confirmed action can be undone for a few seconds before it is sent.
28
+ `guardReducer` is the pure state machine behind them.
29
+
30
+ React and React DOM are peer dependencies: the cockpit and the modules it loads share one copy.
package/package.json CHANGED
@@ -1,6 +1,33 @@
1
1
  {
2
2
  "name": "@niwa-labs/ui-kit",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.0",
4
+ "license": "MIT",
5
+ "type": "module",
6
+ "exports": {
7
+ ".": "./src/index.ts",
8
+ "./theme.css": "./src/theme.css"
9
+ },
10
+ "dependencies": {
11
+ "@base-ui/react": "^1.9.0",
12
+ "@pierre/diffs": "^1.6.4",
13
+ "@streamdown/code": "^2.0.1",
14
+ "@tanstack/react-virtual": "^3.14.26",
15
+ "class-variance-authority": "^0.7.1",
16
+ "clsx": "^2.1.1",
17
+ "lucide-react": "^1.77.0",
18
+ "streamdown": "^2.8.0",
19
+ "tailwind-merge": "^3.7.1",
20
+ "use-stick-to-bottom": "^1.1.6"
21
+ },
22
+ "peerDependencies": {
23
+ "react": "^19.3.1",
24
+ "react-dom": "^19.3.1"
25
+ },
26
+ "devDependencies": {
27
+ "@happy-dom/global-registrator": "^21.0.4",
28
+ "@types/react": "^19.3.0",
29
+ "@types/react-dom": "^19.3.0",
30
+ "react": "^19.3.1",
31
+ "react-dom": "^19.3.1"
32
+ }
33
+ }
@@ -0,0 +1,62 @@
1
+ /**
2
+ * A diff of one or more files: from a unified patch, or from the old and new text of one file.
3
+ * Highlighting and long-file virtualisation come from the diff renderer.
4
+ */
5
+
6
+ import { parsePatchFiles } from "@pierre/diffs";
7
+ import { FileDiff, MultiFileDiff } from "@pierre/diffs/react";
8
+ import { useMemo } from "react";
9
+
10
+ import { cn } from "../lib/cn.ts";
11
+
12
+ export type DiffLayout = "unified" | "split";
13
+
14
+ type DiffCommon = {
15
+ layout?: DiffLayout | undefined;
16
+ /** Wrap long lines instead of scrolling them. */
17
+ wrap?: boolean | undefined;
18
+ className?: string | undefined;
19
+ };
20
+
21
+ export type DiffViewProps = DiffCommon &
22
+ (
23
+ | { patch: string; before?: undefined; after?: undefined }
24
+ | {
25
+ patch?: undefined;
26
+ /** The file before the change. */
27
+ before: { name: string; contents: string };
28
+ /** The file after the change. */
29
+ after: { name: string; contents: string };
30
+ }
31
+ );
32
+
33
+ export function DiffView(props: DiffViewProps) {
34
+ // The renderer takes one file at a time, so a patch is split into the files it holds.
35
+ const patch = props.patch;
36
+ const files = useMemo(() => (patch === undefined ? [] : parsePatchFiles(patch).flatMap((parsed) => parsed.files)), [patch]);
37
+ const options = {
38
+ diffStyle: props.layout ?? "unified",
39
+ overflow: props.wrap === true ? ("wrap" as const) : ("scroll" as const),
40
+ themeType: "system" as const,
41
+ preferredHighlighter: "highlights" as const,
42
+ };
43
+ const fileClassName = "block min-w-0 overflow-hidden rounded-lg border text-xs";
44
+ if (props.patch !== undefined) {
45
+ if (files.length === 0) return null;
46
+ return (
47
+ <div data-slot="diff-view" className={cn("flex min-w-0 flex-col gap-3", props.className)}>
48
+ {files.map((file, index) => (
49
+ <FileDiff key={`${String(index)}:${file.name}`} fileDiff={file} options={options} className={fileClassName} />
50
+ ))}
51
+ </div>
52
+ );
53
+ }
54
+ return (
55
+ <MultiFileDiff
56
+ oldFile={props.before}
57
+ newFile={props.after}
58
+ options={options}
59
+ className={cn(fileClassName, props.className)}
60
+ />
61
+ );
62
+ }
@@ -0,0 +1,201 @@
1
+ import { useEffect, useState, type ReactNode } from "react";
2
+ import { WORK_STATE_LABEL, type WorkState } from "./state.tsx";
3
+
4
+ /** Motion describes what is happening now. Settled work carries no activity. */
5
+ export type Activity = "working" | "human" | "timer" | "paused" | "starting";
6
+ export function ActivityLabel({ activity, children }: { activity?: Activity | undefined; children: ReactNode }) {
7
+ return (
8
+ <span className="nw-activity" data-activity={activity}>
9
+ {children}
10
+ </span>
11
+ );
12
+ }
13
+
14
+ export interface ExecutionStep {
15
+ id: string;
16
+ title: ReactNode;
17
+ kind: "agent" | "question" | "timer" | "wait" | "action";
18
+ state: WorkState;
19
+ activity?: Activity | undefined;
20
+ detail?: string | undefined;
21
+ branch?: string | undefined;
22
+ start: number;
23
+ end?: number | undefined;
24
+ due?: number | undefined;
25
+ }
26
+ export function MiniPhaseTrack({
27
+ phases,
28
+ }: {
29
+ phases: readonly { title: string; state: "done" | "current" | "ahead"; activity?: Activity | undefined }[];
30
+ }) {
31
+ return (
32
+ <span className="nw-mini" aria-label="Фазы">
33
+ {phases.map((p) => (
34
+ <span key={p.title}><i data-state={p.state} data-activity={p.activity} aria-label={WORK_STATE_LABEL[p.state === "ahead" ? "pending" : p.state === "current" ? "running" : "done"]} />{p.title}</span>
35
+ ))}
36
+ </span>
37
+ );
38
+ }
39
+ export interface ExecutionPhase {
40
+ id: string;
41
+ title: string;
42
+ detail?: string | undefined;
43
+ state: WorkState;
44
+ activity?: Activity | undefined;
45
+ steps: ExecutionStep[];
46
+ }
47
+ const marks: Record<WorkState, string> = {
48
+ pending: "○",
49
+ running: "●",
50
+ waiting: "Ⅱ",
51
+ done: "✓",
52
+ failed: "!",
53
+ unknown: "?",
54
+ stopped: "×",
55
+ skipped: "↷",
56
+ reused: "↺",
57
+ };
58
+ function Node({ phase }: { phase: ExecutionPhase }) {
59
+ return (
60
+ <i className="nw-node" data-state={phase.state} aria-label={WORK_STATE_LABEL[phase.state]}>
61
+ {phase.activity === "timer" ? "◷" : phase.activity === "human" ? "?" : marks[phase.state]}
62
+ </i>
63
+ );
64
+ }
65
+
66
+ export function PhaseSequence({ phases }: { phases: ExecutionPhase[] }) {
67
+ return (
68
+ <ol className="nw-sequence" aria-label="План фаз">
69
+ {phases.map((p) => (
70
+ <li key={p.id} title={p.detail}>
71
+ <Node phase={p} />
72
+ <div>
73
+ <ActivityLabel activity={p.activity}>{p.title}</ActivityLabel>
74
+ {p.detail && <small>{p.detail}</small>}
75
+ </div>
76
+ </li>
77
+ ))}
78
+ </ol>
79
+ );
80
+ }
81
+
82
+ const time = (at: number) => new Date(at).toLocaleTimeString("ru", { hour: "2-digit", minute: "2-digit" });
83
+ function Countdown({ at }: { at: number }) {
84
+ const [now, setNow] = useState(Date.now);
85
+ useEffect(() => {
86
+ const clock = setInterval(() => setNow(Date.now()), 1000);
87
+ return () => clearInterval(clock);
88
+ }, []);
89
+ const s = Math.max(0, Math.ceil((at - now) / 1000));
90
+ return (
91
+ <time className="nw-countdown" dateTime={new Date(at).toISOString()} title={new Date(at).toLocaleString()}>
92
+ {" "}
93
+ · {s >= 3600 && Math.floor(s / 3600) + " ч "}
94
+ {s >= 60 && (Math.floor(s / 60) % 60) + " мин "}
95
+ {s % 60} с
96
+ </time>
97
+ );
98
+ }
99
+
100
+ function Branch({ step, full, first, last }: { step: ExecutionStep; full: boolean; first: number; last: number }) {
101
+ const icon = { agent: "A", question: "?", timer: "◷", wait: "◷", action: "⌘" }[step.kind];
102
+ return (
103
+ <li className="nw-branch" data-kind={step.kind} data-activity={step.activity}>
104
+ <div className="nw-step">
105
+ <i aria-hidden>{icon}</i>
106
+ <span>
107
+ {step.title}
108
+ {step.activity === "timer" && step.due !== undefined && <Countdown at={step.due} />}
109
+ </span>
110
+ <em aria-label={WORK_STATE_LABEL[step.state]}>
111
+ {step.activity === "working" ? "" : step.state === "running" ? "…" : marks[step.state]}
112
+ </em>
113
+ </div>
114
+ {step.detail && (full || step.kind === "agent") && (
115
+ <small className="nw-prompt">{full ? step.detail : step.detail.slice(0, 64)}</small>
116
+ )}
117
+ {full && (
118
+ <>
119
+ {last > first && (
120
+ <div className="nw-duration" aria-hidden>
121
+ <i
122
+ style={{
123
+ left: ((step.start - first) / (last - first)) * 100 + "%",
124
+ width: (((step.end ?? last) - step.start) / (last - first)) * 100 + "%",
125
+ }}
126
+ />
127
+ </div>
128
+ )}
129
+ <small>
130
+ {step.branch && "Ветка " + step.branch + " · "}
131
+ {time(step.start)}
132
+ {step.end !== undefined && " – " + time(step.end)}
133
+ </small>
134
+ </>
135
+ )}
136
+ </li>
137
+ );
138
+ }
139
+
140
+ function PhaseSteps({ steps, detail, observedAt }: {
141
+ steps: ExecutionStep[];
142
+ detail: boolean;
143
+ observedAt?: number | undefined;
144
+ }) {
145
+ if (!steps.length) return null;
146
+ const first = steps.reduce((start, step) => Math.min(start, step.start), Infinity);
147
+ const last = steps.reduce((end, step) => Math.max(end, step.end ?? observedAt ?? step.start), first);
148
+ let latestEnd = -Infinity;
149
+ const parallel = detail && [...steps].sort((a, b) => a.start - b.start).some(step => {
150
+ if (latestEnd > step.start) return true;
151
+ latestEnd = Math.max(latestEnd, step.end ?? Infinity);
152
+ return false;
153
+ });
154
+ return <>
155
+ {parallel && <small className="nw-fork">⑂ Параллельные ветки</small>}
156
+ <ul className="nw-branches">
157
+ {steps.map(step => <Branch key={step.id} step={step} full={detail} first={first} last={last} />)}
158
+ </ul>
159
+ </>;
160
+ }
161
+
162
+ /** Keep the declared plan above the step history, even when the first phase has long prompts. */
163
+ function DetailedTrack({ phases, observedAt }: { phases: ExecutionPhase[]; observedAt?: number | undefined }) {
164
+ const [picked, setPicked] = useState<string>();
165
+ const current = phases.find(p => p.state === "running" || p.state === "waiting" || p.state === "failed");
166
+ const selected = phases.find(p => p.id === picked) ?? current ?? phases.find(p => p.steps.length) ?? phases[0];
167
+ return <section className="nw-track nw-track-inspect" data-detail="true" aria-label="Ход выполнения">
168
+ <ol className="nw-phase-index" aria-label="План фаз">
169
+ {phases.map(p => <li key={p.id} className="nw-phase" data-activity={p.activity}>
170
+ <button type="button" className="nw-phase-title" aria-pressed={p.id === selected?.id}
171
+ onClick={() => setPicked(p.id === picked ? undefined : p.id)}>
172
+ <Node phase={p}/><span>{p.title}{p.detail && <small>{p.detail}</small>}</span>
173
+ </button>
174
+ </li>)}
175
+ </ol>
176
+ {selected && (selected.steps.length
177
+ ? <PhaseSteps steps={selected.steps} observedAt={observedAt} detail />
178
+ : <small>{selected.state === "pending" ? "Фаза ещё не началась" : "Шагов пока нет"}</small>)}
179
+ </section>;
180
+ }
181
+
182
+ export function ExecutionTrack({ phases, looseSteps = [], detail = false, observedAt }: {
183
+ looseSteps?: ExecutionStep[];
184
+ phases: ExecutionPhase[];
185
+ detail?: boolean;
186
+ observedAt?: number | undefined;
187
+ }) {
188
+ return <>
189
+ {phases.length > 0 && (detail ? <DetailedTrack phases={phases} observedAt={observedAt} /> :
190
+ <ol className="nw-track" data-detail="false" aria-label="Ход выполнения">
191
+ {phases.map(p => <li className="nw-phase" key={p.id} data-activity={p.activity}>
192
+ <div className="nw-phase-title"><Node phase={p} />{p.title}</div>
193
+ <PhaseSteps steps={p.steps} detail={false} observedAt={observedAt} />
194
+ </li>)}
195
+ </ol>)}
196
+ {looseSteps.length > 0 && <section className="nw-loose-steps" aria-label="Шаги вне фаз">
197
+ <h3>{phases.length ? "Шаги вне фаз" : "Шаги"}</h3>
198
+ <PhaseSteps steps={looseSteps} detail={detail} observedAt={observedAt} />
199
+ </section>}
200
+ </>;
201
+ }
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Soft protection for an action that cannot be taken back, such as recomputing or stopping work.
3
+ *
4
+ * Nothing opens over the page. The control asks in place: the first press arms it and says what
5
+ * will be affected, a second press (or holding the first one) confirms it. A confirmed action is
6
+ * not sent at once: for a short while it can still be undone, and only when that window closes is
7
+ * the action fired. Host actions cannot be revoked once sent, so undo means "not sent yet".
8
+ *
9
+ * The machine is a pure reducer over explicit times; the hook that drives it owns the clock.
10
+ */
11
+
12
+ export type GuardTiming = {
13
+ /** How long an armed control waits for the second press before it disarms. */
14
+ armMs: number;
15
+ /** How long a press must be held to confirm without a second press. */
16
+ holdMs: number;
17
+ /** How long a confirmed action can still be undone before it is fired. */
18
+ undoMs: number;
19
+ };
20
+
21
+ export const DEFAULT_GUARD_TIMING: GuardTiming = { armMs: 4000, holdMs: 700, undoMs: 3000 };
22
+
23
+ export type GuardState =
24
+ | { phase: "idle" }
25
+ /** Pressed once; waiting for the second press until `until`. */
26
+ | { phase: "armed"; until: number }
27
+ /** The pointer is down since `since`; `armedUntil` remembers an arming the hold started from. */
28
+ | { phase: "holding"; since: number; armedUntil: number | null }
29
+ /** Confirmed; fired at `until` unless undone. */
30
+ | { phase: "pending"; until: number }
31
+ /** The undo window closed: the action is to be fired now, once. */
32
+ | { phase: "fired" };
33
+
34
+ export type GuardEvent =
35
+ /** A click, a keyboard activation, or a short press: arms, or confirms an armed control. */
36
+ | { type: "press"; now: number }
37
+ | { type: "holdStart"; now: number }
38
+ /** The pointer is released over the control. */
39
+ | { type: "holdEnd"; now: number }
40
+ /** The pointer left the control or the press was taken over by scrolling. */
41
+ | { type: "holdCancel"; now: number }
42
+ /** Time passed: expire an arming, complete a hold, close the undo window. */
43
+ | { type: "tick"; now: number }
44
+ /** Escape, focus leaving the control, the undo button: back to idle without firing. */
45
+ | { type: "cancel" }
46
+ /** The fired action was handed over. */
47
+ | { type: "reset" };
48
+
49
+ export const IDLE: GuardState = { phase: "idle" };
50
+
51
+ function confirm(now: number, timing: GuardTiming): GuardState {
52
+ return { phase: "pending", until: now + timing.undoMs };
53
+ }
54
+
55
+ function press(state: GuardState, now: number, timing: GuardTiming): GuardState {
56
+ if (state.phase === "idle") return { phase: "armed", until: now + timing.armMs };
57
+ if (state.phase === "armed") return now < state.until ? confirm(now, timing) : { phase: "armed", until: now + timing.armMs };
58
+ return state;
59
+ }
60
+
61
+ /** The phase a hold returns to when it ends without confirming. */
62
+ function beforeHold(state: Extract<GuardState, { phase: "holding" }>, now: number): GuardState {
63
+ return state.armedUntil !== null && now < state.armedUntil ? { phase: "armed", until: state.armedUntil } : IDLE;
64
+ }
65
+
66
+ export function guardReducer(state: GuardState, event: GuardEvent, timing: GuardTiming = DEFAULT_GUARD_TIMING): GuardState {
67
+ switch (event.type) {
68
+ case "press":
69
+ return press(state, event.now, timing);
70
+ case "holdStart":
71
+ if (state.phase === "idle") return { phase: "holding", since: event.now, armedUntil: null };
72
+ if (state.phase === "armed") return { phase: "holding", since: event.now, armedUntil: state.until };
73
+ return state;
74
+ case "holdEnd":
75
+ if (state.phase !== "holding") return state;
76
+ if (event.now - state.since >= timing.holdMs) return confirm(event.now, timing);
77
+ // A short press is a press: it arms an idle control and confirms an armed one.
78
+ return press(beforeHold(state, event.now), event.now, timing);
79
+ case "holdCancel":
80
+ return state.phase === "holding" ? beforeHold(state, event.now) : state;
81
+ case "tick":
82
+ if (state.phase === "armed" && event.now >= state.until) return IDLE;
83
+ if (state.phase === "holding" && event.now - state.since >= timing.holdMs) return confirm(event.now, timing);
84
+ if (state.phase === "pending" && event.now >= state.until) return { phase: "fired" };
85
+ return state;
86
+ case "cancel":
87
+ return state.phase === "fired" ? state : IDLE;
88
+ case "reset":
89
+ return state.phase === "fired" ? IDLE : state;
90
+ }
91
+ }
92
+
93
+ /** When the reducer next needs a tick, or null when nothing is waiting on time. */
94
+ export function nextDeadline(state: GuardState, timing: GuardTiming = DEFAULT_GUARD_TIMING): number | null {
95
+ switch (state.phase) {
96
+ case "armed":
97
+ case "pending":
98
+ return state.until;
99
+ case "holding":
100
+ return state.since + timing.holdMs;
101
+ default:
102
+ return null;
103
+ }
104
+ }
105
+
106
+ /**
107
+ * Whether a control that goes away must still fire its action.
108
+ *
109
+ * A confirmed action is the owner's decision; the undo window is a courtesy while the control is
110
+ * on screen. A row that scrolls out of a virtual list, or a page the owner leaves, fires what was
111
+ * confirmed. An armed or held control that goes away was never confirmed and fires nothing.
112
+ */
113
+ export function firesOnUnmount(state: GuardState): boolean {
114
+ return state.phase === "pending" || state.phase === "fired";
115
+ }
116
+
117
+ /** How far a hold has come, from 0 to 1, for a progress ring. */
118
+ export function holdProgress(state: GuardState, now: number, timing: GuardTiming = DEFAULT_GUARD_TIMING): number {
119
+ if (state.phase !== "holding") return 0;
120
+ return Math.min(1, Math.max(0, (now - state.since) / timing.holdMs));
121
+ }