@saar-ai/web-widget 0.4.1 → 0.6.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.
- package/dist/card-aspect.d.ts +58 -0
- package/dist/card-aspect.d.ts.map +1 -0
- package/dist/chunks/chat-tMKkYmTC.js +592 -0
- package/dist/chunks/host-widget-C0XT9lHX.js +9637 -0
- package/dist/chunks/{telemetry-Bw-3F_Zk.js → telemetry-BI_SEWTb.js} +104 -2
- package/dist/dock/dock-caption.d.ts +67 -0
- package/dist/dock/dock-caption.d.ts.map +1 -0
- package/dist/dock/dock-motion.d.ts +155 -0
- package/dist/dock/dock-motion.d.ts.map +1 -0
- package/dist/dock/dock-pill.d.ts +38 -0
- package/dist/dock/dock-pill.d.ts.map +1 -0
- package/dist/dock/dock-row.d.ts +120 -0
- package/dist/dock/dock-row.d.ts.map +1 -0
- package/dist/dock/dock-sheet.d.ts +89 -0
- package/dist/dock/dock-sheet.d.ts.map +1 -0
- package/dist/dock/dock-shelf.d.ts +38 -0
- package/dist/dock/dock-shelf.d.ts.map +1 -0
- package/dist/dock/dock-state.d.ts +221 -0
- package/dist/dock/dock-state.d.ts.map +1 -0
- package/dist/dock/dock.d.ts +344 -0
- package/dist/dock/dock.d.ts.map +1 -0
- package/dist/dock/geometry.d.ts +161 -0
- package/dist/dock/geometry.d.ts.map +1 -0
- package/dist/format-money.d.ts +54 -17
- package/dist/format-money.d.ts.map +1 -1
- package/dist/generated/widget-css.d.ts.map +1 -1
- package/dist/host-widget.d.ts +156 -16
- package/dist/host-widget.d.ts.map +1 -1
- package/dist/index.d.ts +7 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4029 -7
- package/dist/messages.d.ts +86 -0
- package/dist/messages.d.ts.map +1 -1
- package/dist/next/index.js +1 -1
- package/dist/session-log.d.ts +7 -0
- package/dist/session-log.d.ts.map +1 -1
- package/dist/session-panel.d.ts +13 -3
- package/dist/session-panel.d.ts.map +1 -1
- package/dist/theme/color.d.ts +114 -0
- package/dist/theme/color.d.ts.map +1 -0
- package/dist/theme/derive.d.ts +92 -0
- package/dist/theme/derive.d.ts.map +1 -0
- package/dist/theme/index.d.ts +10 -0
- package/dist/theme/index.d.ts.map +1 -0
- package/dist/turn-order.d.ts +106 -0
- package/dist/turn-order.d.ts.map +1 -0
- package/dist/use-chat-session.d.ts +146 -17
- package/dist/use-chat-session.d.ts.map +1 -1
- package/dist/use-voice-session.d.ts +110 -4
- package/dist/use-voice-session.d.ts.map +1 -1
- package/dist/voice-widget.d.ts +114 -24
- package/dist/voice-widget.d.ts.map +1 -1
- package/dist/widget-cards.d.ts +28 -1
- package/dist/widget-cards.d.ts.map +1 -1
- package/dist/widget.css +1 -1
- package/package.json +4 -4
- package/src/styles/concierge.css +803 -28
- package/src/styles/tokens.css +67 -0
- package/dist/chunks/chat-DfajYOmN.js +0 -240
- package/dist/chunks/host-widget-C9EyGeiN.js +0 -9745
- package/dist/concierge-launcher.d.ts +0 -53
- package/dist/concierge-launcher.d.ts.map +0 -1
- package/dist/concierge-shell.d.ts +0 -256
- package/dist/concierge-shell.d.ts.map +0 -1
- package/dist/position.d.ts +0 -65
- package/dist/position.d.ts.map +0 -1
- package/dist/transcript-geometry.d.ts +0 -220
- package/dist/transcript-geometry.d.ts.map +0 -1
|
@@ -71,6 +71,93 @@ var CallerTextPayloadSchema = object({
|
|
|
71
71
|
function encodeCallerText(payload) {
|
|
72
72
|
return new TextEncoder().encode(JSON.stringify(payload));
|
|
73
73
|
}
|
|
74
|
+
/**
|
|
75
|
+
* The topic the caller's browser publishes CONTROL frames on — everything it
|
|
76
|
+
* asks the worker to do that is not a typed message.
|
|
77
|
+
*
|
|
78
|
+
* Separate from {@link VOICE_CALLER_TEXT_TOPIC} on purpose. Caller text is
|
|
79
|
+
* CONTENT: it commits a turn, it is metered, it reaches the model. These
|
|
80
|
+
* frames are gestures — a finger on the row, a finger off the mic, a page
|
|
81
|
+
* about to unload — and they must never be able to reach a turn's text by
|
|
82
|
+
* being mistaken for it. Two topics means the worker's own dispatch decides
|
|
83
|
+
* which of the two trust classes a frame belongs to before it parses
|
|
84
|
+
* anything, rather than a shared union deciding it afterwards.
|
|
85
|
+
*
|
|
86
|
+
* ## Who sends these (docs/DOCK_SPEC.md §5.1, §5.2, §8.6)
|
|
87
|
+
*
|
|
88
|
+
* | Frame | Gesture |
|
|
89
|
+
* | --------------------------- | ------------------------------------------------ |
|
|
90
|
+
* | `interrupt { reason }` | the shopper cut the agent off without speaking |
|
|
91
|
+
* | `eou_hint` | hold-to-talk released (`pointerup` on the mic) |
|
|
92
|
+
* | `resume` | the shopper tapped the mic after a duck |
|
|
93
|
+
* | `navigating` | this page is unloading into another of ours |
|
|
94
|
+
*
|
|
95
|
+
* All four are UNAUTHENTICATED in the sense that matters here: the caller's
|
|
96
|
+
* room token is what let them publish at all, so a frame can only ever affect
|
|
97
|
+
* the one session that token named. None of them carries free text, none of
|
|
98
|
+
* them selects a room, and none of them can extend a session — `navigating`
|
|
99
|
+
* buys a bounded hold, never an unbounded one (`VOICE_NAV_HOLD_MS`).
|
|
100
|
+
*/
|
|
101
|
+
var VOICE_CALLER_CONTROL_TOPIC = "voice.caller_control";
|
|
102
|
+
/**
|
|
103
|
+
* Why the shopper cut the agent off, when they did it without speaking.
|
|
104
|
+
*
|
|
105
|
+
* - `look` — the DUCK (§5.1 "Paused while you look"). The shopper is reading
|
|
106
|
+
* the page, not talking to the agent. The turn is cancelled exactly as a
|
|
107
|
+
* spoken barge-in cancels it, and then **the agent stays silent**: no
|
|
108
|
+
* filler, no re-prompt, no timer. It resumes when they speak or send
|
|
109
|
+
* `resume`.
|
|
110
|
+
* - `tap` — the explicit interrupt control (or a tap anywhere on the row while
|
|
111
|
+
* `speaking`). The shopper wants the floor.
|
|
112
|
+
* - `keyboard` — they switched to text mid-reply; the typed turn that follows
|
|
113
|
+
* supersedes this one anyway, and this frame stops the audio first so they
|
|
114
|
+
* are not typing over the agent.
|
|
115
|
+
*
|
|
116
|
+
* A closed enum, not a free string: the worker records this on a turn's
|
|
117
|
+
* metrics and republishes it, so an open vocabulary would be an
|
|
118
|
+
* attacker-controlled label in an operator's console.
|
|
119
|
+
*/
|
|
120
|
+
var CALLER_INTERRUPT_REASONS = [
|
|
121
|
+
"look",
|
|
122
|
+
"tap",
|
|
123
|
+
"keyboard"
|
|
124
|
+
];
|
|
125
|
+
var CallerInterruptPayloadSchema = object({
|
|
126
|
+
type: literal("interrupt"),
|
|
127
|
+
reason: _enum(CALLER_INTERRUPT_REASONS)
|
|
128
|
+
});
|
|
129
|
+
/**
|
|
130
|
+
* Hold-to-talk released (§5.2). The shopper's finger IS the endpointer, so the
|
|
131
|
+
* utterance ends now rather than at the silence floor.
|
|
132
|
+
*
|
|
133
|
+
* Honoured only while the caller's microphone is actually open — see
|
|
134
|
+
* `apps/voice`'s `handleCallerEouHint`. A frame that arrives with no live
|
|
135
|
+
* uplink is a gesture about audio nobody sent, and speculating on it would
|
|
136
|
+
* spend an LLM call on silence.
|
|
137
|
+
*/
|
|
138
|
+
var CallerEouHintPayloadSchema = object({ type: literal("eou_hint") });
|
|
139
|
+
/** The shopper is back after a duck (§5.1: resume never fires on a timer). */
|
|
140
|
+
var CallerResumePayloadSchema = object({ type: literal("resume") });
|
|
141
|
+
/**
|
|
142
|
+
* This page is unloading into another page of the same storefront (§8.6).
|
|
143
|
+
*
|
|
144
|
+
* Sent from the same `pagehide` handler that flushes the visitor-event queue,
|
|
145
|
+
* and it buys the session a BOUNDED hold — `VOICE_NAV_HOLD_MS` — so the next
|
|
146
|
+
* page's `core` rejoins the conversation it was already having instead of
|
|
147
|
+
* starting a new one. It is a hint, not a promise: a shopper who closes the
|
|
148
|
+
* tab sends exactly the same frame, and the hold expiring is what makes that
|
|
149
|
+
* indistinguishable case end correctly anyway.
|
|
150
|
+
*/
|
|
151
|
+
var CallerNavigatingPayloadSchema = object({ type: literal("navigating") });
|
|
152
|
+
var CallerControlPayloadSchema = discriminatedUnion("type", [
|
|
153
|
+
CallerInterruptPayloadSchema,
|
|
154
|
+
CallerEouHintPayloadSchema,
|
|
155
|
+
CallerResumePayloadSchema,
|
|
156
|
+
CallerNavigatingPayloadSchema
|
|
157
|
+
]);
|
|
158
|
+
function encodeCallerControl(payload) {
|
|
159
|
+
return new TextEncoder().encode(JSON.stringify(payload));
|
|
160
|
+
}
|
|
74
161
|
/** Per-turn latency, in milliseconds. `null` means the stage never completed. */
|
|
75
162
|
var TurnLatencyPayloadSchema = object({
|
|
76
163
|
type: literal("turn.latency"),
|
|
@@ -89,7 +176,22 @@ var TurnLatencyPayloadSchema = object({
|
|
|
89
176
|
* The turn tier began generating before the turn was confirmed, so most of
|
|
90
177
|
* `agentMs` hid under `eotMs` and the stages will not sum to `overallMs`.
|
|
91
178
|
*/
|
|
92
|
-
speculative: boolean()
|
|
179
|
+
speculative: boolean(),
|
|
180
|
+
/**
|
|
181
|
+
* How this turn's reply was cut short, when it was.
|
|
182
|
+
*
|
|
183
|
+
* `'speech'` is the classic barge-in: the caller talked over the agent and
|
|
184
|
+
* `BargeInGate` confirmed it. The other three are the DOCK's client-side
|
|
185
|
+
* interrupts (`CALLER_INTERRUPT_REASONS`), and the distinction is the whole
|
|
186
|
+
* point of carrying this: a console that cannot tell a shopper who was
|
|
187
|
+
* READING the page (`'look'`) from a shopper who was TALKING over the agent
|
|
188
|
+
* reads a healthy duck as a barge-in problem, and tunes the barge-in gate
|
|
189
|
+
* against a signal the gate never produced.
|
|
190
|
+
*
|
|
191
|
+
* Absent (not `null`) on a turn that ran to completion. Optional so a
|
|
192
|
+
* widget or console pinned to an older build still parses the frame.
|
|
193
|
+
*/
|
|
194
|
+
interruptedBy: _enum(["speech", ...CALLER_INTERRUPT_REASONS]).optional()
|
|
93
195
|
});
|
|
94
196
|
/** One line of conversation, as it is known. */
|
|
95
197
|
var TranscriptPayloadSchema = object({
|
|
@@ -287,4 +389,4 @@ function decodeTelemetry(payload) {
|
|
|
287
389
|
return result.success ? result.data : null;
|
|
288
390
|
}
|
|
289
391
|
//#endregion
|
|
290
|
-
export { CallerTextPayloadSchema, SessionConfigPayloadSchema, TranscriptPayloadSchema, TurnCostPayloadSchema, TurnLatencyPayloadSchema, VOICE_CALLER_TEXT_TOPIC, VendorErrorPayloadSchema, VoiceTelemetryMessageSchema, WidgetEventPayloadSchema, decodeTelemetry, encodeCallerText };
|
|
392
|
+
export { CALLER_INTERRUPT_REASONS, CallerControlPayloadSchema, CallerEouHintPayloadSchema, CallerInterruptPayloadSchema, CallerNavigatingPayloadSchema, CallerResumePayloadSchema, CallerTextPayloadSchema, SessionConfigPayloadSchema, TranscriptPayloadSchema, TurnCostPayloadSchema, TurnLatencyPayloadSchema, VOICE_CALLER_CONTROL_TOPIC, VOICE_CALLER_TEXT_TOPIC, VendorErrorPayloadSchema, VoiceTelemetryMessageSchema, WidgetEventPayloadSchema, decodeTelemetry, encodeCallerControl, encodeCallerText };
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { type RefObject } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* THE CAPTION — docs/DOCK_SPEC.md §2's third slot and §5.2's "the caption is
|
|
4
|
+
* the field".
|
|
5
|
+
*
|
|
6
|
+
* ## The `<input>` is there from the first paint, always
|
|
7
|
+
*
|
|
8
|
+
* Not a `<span>` that becomes an `<input>` on focus. Swapping the element
|
|
9
|
+
* loses the caret, cannot preserve a selection, and gives the shopper a
|
|
10
|
+
* visible flicker at the exact moment they started typing — and it is what
|
|
11
|
+
* makes §4.2's handover impossible to do in one frame, because the core dock
|
|
12
|
+
* (`cdn/dock-dom.ts`) also paints a real `<input>` here and hands its draft
|
|
13
|
+
* and caret across. Two renderers, one element, same contract.
|
|
14
|
+
*
|
|
15
|
+
* The status LINE is layered OVER the field rather than written into it, for
|
|
16
|
+
* the same reason the core dock layers its proactive nudge: a caption is ours
|
|
17
|
+
* and a draft is the shopper's. A shopper with a half-typed question does not
|
|
18
|
+
* have it overwritten by "Listening".
|
|
19
|
+
*
|
|
20
|
+
* ## Why the cross-fade is keyed, not text-triggered
|
|
21
|
+
*
|
|
22
|
+
* §7.2 gives the caption swap a 160 ms cross-fade. Applied to every text
|
|
23
|
+
* change it would fire on every token of a live partial transcript and on
|
|
24
|
+
* every clause boundary of a spoken reply — a strobe, not a transition. It
|
|
25
|
+
* fires on `swapKey` instead: the caption's SOURCE (which state is speaking,
|
|
26
|
+
* which message key) rather than its content. A partial transcript growing
|
|
27
|
+
* word by word is one continuous caption; `listening` becoming `thinking` is
|
|
28
|
+
* a swap.
|
|
29
|
+
*
|
|
30
|
+
* Both layers are in the DOM during the fade so it is a real cross-fade
|
|
31
|
+
* rather than a fade-through; the outgoing one is `aria-hidden` so a screen
|
|
32
|
+
* reader is never read two captions at once (the live region in `dock.tsx`
|
|
33
|
+
* is what actually announces the change — §11).
|
|
34
|
+
*/
|
|
35
|
+
export interface DockCaptionProps {
|
|
36
|
+
/**
|
|
37
|
+
* The line to show over the field, or `undefined` when the FIELD itself is
|
|
38
|
+
* the caption (§5.1's `dormant`).
|
|
39
|
+
*/
|
|
40
|
+
readonly line?: string;
|
|
41
|
+
/**
|
|
42
|
+
* What makes this a different caption rather than the same one updating.
|
|
43
|
+
* See the module doc comment.
|
|
44
|
+
*/
|
|
45
|
+
readonly swapKey: string;
|
|
46
|
+
readonly draft: string;
|
|
47
|
+
readonly onDraftChange: (value: string) => void;
|
|
48
|
+
readonly onSubmit: () => void;
|
|
49
|
+
/** The tenant's `copy[locale].greeting`, or the shipped placeholder. */
|
|
50
|
+
readonly placeholder: string;
|
|
51
|
+
/** The field's accessible name (§11 — "the caption field is a labelled `<input>`"). */
|
|
52
|
+
readonly label: string;
|
|
53
|
+
readonly disabled?: boolean;
|
|
54
|
+
readonly inputRef?: RefObject<HTMLInputElement | null>;
|
|
55
|
+
/** 0 under reduced motion (§7.1 rule 10) — the swap then happens in place. */
|
|
56
|
+
readonly durationMs: number;
|
|
57
|
+
readonly inputTestId?: string;
|
|
58
|
+
/**
|
|
59
|
+
* The line's own `data-testid`. Defaults to `widget-dock-caption`; the dock
|
|
60
|
+
* passes `widget-status` when the line came from the HOST's status line
|
|
61
|
+
* (§5.1's `error`), which is the id the conversation suite has driven that
|
|
62
|
+
* message through since before the dock existed.
|
|
63
|
+
*/
|
|
64
|
+
readonly lineTestId?: string;
|
|
65
|
+
}
|
|
66
|
+
export declare function DockCaption({ line, swapKey, draft, onDraftChange, onSubmit, placeholder, label, disabled, inputRef, durationMs, inputTestId, lineTestId, }: DockCaptionProps): import("react").JSX.Element;
|
|
67
|
+
//# sourceMappingURL=dock-caption.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dock-caption.d.ts","sourceRoot":"","sources":["../../src/dock/dock-caption.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAmD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACvD,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,WAAW,CAAC,EAC1B,IAAI,EACJ,OAAO,EACP,KAAK,EACL,aAAa,EACb,QAAQ,EACR,WAAW,EACX,KAAK,EACL,QAAgB,EAChB,QAAQ,EACR,UAAU,EACV,WAAW,EACX,UAAkC,GACnC,EAAE,gBAAgB,+BA+ClB"}
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* THE DOCK'S MOTION — docs/DOCK_SPEC.md §7, as the four primitives every
|
|
3
|
+
* surface under `dock/` shares.
|
|
4
|
+
*
|
|
5
|
+
* §7.1 is a gate, not guidance, and `tools/check-widget-motion.mjs` enforces
|
|
6
|
+
* rule 1 (compositor only) over this whole package. The other four rules the
|
|
7
|
+
* dock cannot get right by writing CSS alone live here:
|
|
8
|
+
*
|
|
9
|
+
* - **rule 4 — `will-change` is transient.** Set by the animation's start,
|
|
10
|
+
* removed on `transitionend`. A permanent `will-change: transform` on a
|
|
11
|
+
* fixed row promotes a layer for the life of the merchant's page. The
|
|
12
|
+
* pill ↔ row swap does not need {@link useTransientWillChange} at all —
|
|
13
|
+
* it runs on the Web Animations API, which promotes and demotes the layer
|
|
14
|
+
* itself — but the sheet and the caption still transition in CSS, so the
|
|
15
|
+
* helper stays.
|
|
16
|
+
* - **rule 5 — per-frame values never touch React state.** The mic level,
|
|
17
|
+
* the keyboard offset and the sheet's drag position change every frame;
|
|
18
|
+
* routing any of them through `setState` re-renders the whole dock 60
|
|
19
|
+
* times a second on someone else's storefront. {@link useCssVars} writes
|
|
20
|
+
* them as custom properties, once per `requestAnimationFrame`, on one
|
|
21
|
+
* element.
|
|
22
|
+
* - **rule 10 — reduced motion wins.** Every duration below collapses to 0
|
|
23
|
+
* and the FLIP is skipped entirely. {@link usePrefersReducedMotion} is the
|
|
24
|
+
* single read, so no surface can forget it.
|
|
25
|
+
* - **§7.2's pill ↔ row FLIP.** Measure both boxes, animate the difference
|
|
26
|
+
* on `transform` alone. Never `width`/`height`/`left` — see the guard.
|
|
27
|
+
*
|
|
28
|
+
* Nothing here renders. Nothing here imports React DOM. It is hooks plus two
|
|
29
|
+
* pure helpers, so the arithmetic (`flipTransform`, `lerp`) is unit-testable
|
|
30
|
+
* without a layout engine jsdom does not have.
|
|
31
|
+
*/
|
|
32
|
+
import { type RefObject } from 'react';
|
|
33
|
+
/** §7.2 — the pill ↔ row swap, and the recede/expand that reuses it. */
|
|
34
|
+
export declare const SWAP_MS = 240;
|
|
35
|
+
export declare const RECEDE_MS = 200;
|
|
36
|
+
export declare const SWAP_EASING = "cubic-bezier(0.2, 0, 0, 1)";
|
|
37
|
+
/** §7.2 — the sheet opens with the same easing and closes faster, with a different one. */
|
|
38
|
+
export declare const SHEET_OPEN_MS = 240;
|
|
39
|
+
export declare const SHEET_CLOSE_MS = 180;
|
|
40
|
+
export declare const SHEET_CLOSE_EASING = "cubic-bezier(0.4, 0, 1, 1)";
|
|
41
|
+
/** §7.2 — the sheet's release snap. */
|
|
42
|
+
export declare const SHEET_SNAP_MS = 200;
|
|
43
|
+
/** §7.2 — caption cross-fade, border colour, control in/out. */
|
|
44
|
+
export declare const CAPTION_MS = 160;
|
|
45
|
+
export declare const BORDER_MS = 160;
|
|
46
|
+
export declare const CONTROL_MS = 120;
|
|
47
|
+
/** §7.2 — the waveform's per-frame smoothing. */
|
|
48
|
+
export declare const LEVEL_LERP = 0.25;
|
|
49
|
+
/** §5.5 — a page scroll past this much closes the sheet and ducks a live reply. */
|
|
50
|
+
export declare const PAGE_SCROLL_DUCK_PX = 24;
|
|
51
|
+
/** §3.3 — a downward drag past this fraction of the sheet's height dismisses it. */
|
|
52
|
+
export declare const SHEET_DISMISS_FRACTION = 0.4;
|
|
53
|
+
/**
|
|
54
|
+
* `prefers-reduced-motion`, as a subscription rather than a one-shot read.
|
|
55
|
+
*
|
|
56
|
+
* A shopper can turn it on mid-session (iOS has it in Control Center), and a
|
|
57
|
+
* dock that only read it at mount would keep animating for the rest of the
|
|
58
|
+
* page. Falls back to `true`-is-safe on a window with no `matchMedia`: a
|
|
59
|
+
* static dock is always correct, an animated one is not.
|
|
60
|
+
*/
|
|
61
|
+
export declare function usePrefersReducedMotion(): boolean;
|
|
62
|
+
/**
|
|
63
|
+
* §7.1 rule 5 — a per-frame custom-property writer.
|
|
64
|
+
*
|
|
65
|
+
* Returns `set(name, value)`. Calls COALESCE: whatever the last value for a
|
|
66
|
+
* name is when the frame runs is what gets written, so a drag handler firing
|
|
67
|
+
* at pointer rate still costs one style write per frame. Nothing here
|
|
68
|
+
* re-renders anything.
|
|
69
|
+
*
|
|
70
|
+
* @param ref the one element the properties are written on
|
|
71
|
+
*/
|
|
72
|
+
export declare function useCssVars(ref: RefObject<HTMLElement | null>): (name: string, value: string) => void;
|
|
73
|
+
/**
|
|
74
|
+
* §7.1 rule 4 — `will-change`, for the length of one transition and no longer.
|
|
75
|
+
*
|
|
76
|
+
* Returns `arm()`. Sets `will-change` on the element, then clears it on the
|
|
77
|
+
* element's OWN `transitionend` (or after `ms`, for a transition that never
|
|
78
|
+
* fires one — an element that was already at its target value produces no
|
|
79
|
+
* event, and a layer promoted forever is exactly what rule 4 exists to
|
|
80
|
+
* prevent).
|
|
81
|
+
*
|
|
82
|
+
* ## Why the `event.target` check is load-bearing
|
|
83
|
+
*
|
|
84
|
+
* `transitionend` BUBBLES, and this hook is armed on surfaces that contain
|
|
85
|
+
* other people's motion. `dock-sheet.tsx` arms it on `.wgt-sheet`, whose body
|
|
86
|
+
* is the transcript, and `widget-cards.tsx` renders buttons in there with
|
|
87
|
+
* Tailwind's `transition-colors`. A hover settling, a focus ring, an
|
|
88
|
+
* "Adding…" label changing colour — any descendant transition finishing
|
|
89
|
+
* inside the sheet's 240 ms reveal reached this listener as though it were
|
|
90
|
+
* the sheet's own, and the layer was demoted in the middle of the animation
|
|
91
|
+
* it had been promoted for. That is the stutter rule 4 exists to remove,
|
|
92
|
+
* caused by the code written to obey it.
|
|
93
|
+
*
|
|
94
|
+
* ## Why the cleanup clears more than the timer
|
|
95
|
+
*
|
|
96
|
+
* The element can go away mid-transition — `core.ts` tears the React stage
|
|
97
|
+
* down on `destroy()`, and the sheet unmounts on every close. Clearing only
|
|
98
|
+
* the timer left the listener attached and `will-change` set on a node that
|
|
99
|
+
* no longer renders, so the layer survived the component and the closure
|
|
100
|
+
* survived with it.
|
|
101
|
+
*/
|
|
102
|
+
export declare function useTransientWillChange(ref: RefObject<HTMLElement | null>, properties?: string, ms?: number): () => void;
|
|
103
|
+
/** A box, as the FLIP needs it. Deliberately not a `DOMRect` — the arithmetic is testable without one. */
|
|
104
|
+
export interface FlipBox {
|
|
105
|
+
readonly x: number;
|
|
106
|
+
readonly y: number;
|
|
107
|
+
readonly width: number;
|
|
108
|
+
readonly height: number;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* §7.2's FLIP, reduced to the one `transform` that takes `to` back onto
|
|
112
|
+
* `from`.
|
|
113
|
+
*
|
|
114
|
+
* Pure, and pure on purpose: jsdom has no layout engine, so the only way to
|
|
115
|
+
* test the choreography at all is to test the arithmetic separately from the
|
|
116
|
+
* measuring. A zero-area `from` (an element that was `display: none`, or a
|
|
117
|
+
* measurement taken before layout) yields the identity transform rather than
|
|
118
|
+
* a division by zero — the animation is skipped, which is the right
|
|
119
|
+
* degradation.
|
|
120
|
+
*
|
|
121
|
+
* @returns a `transform` value that visually places `to` where `from` was
|
|
122
|
+
*/
|
|
123
|
+
export declare function flipTransform(from: FlipBox, to: FlipBox): string;
|
|
124
|
+
/** §7.2's waveform smoothing — the same 0.25 lerp the analyser feeds. */
|
|
125
|
+
export declare function lerp(current: number, target: number, factor?: number): number;
|
|
126
|
+
/**
|
|
127
|
+
* The pill ↔ row swap (§7.2), driven by whichever box is showing.
|
|
128
|
+
*
|
|
129
|
+
* Both boxes exist at all times — the swap is a VISIBILITY change, never a
|
|
130
|
+
* build-and-destroy, exactly as the core dock (`cdn/dock-dom.ts`) already
|
|
131
|
+
* does it — so this measures the outgoing box before the change, and after
|
|
132
|
+
* the change puts the incoming one back where the outgoing one was and
|
|
133
|
+
* releases it. One layout read, one style write, no host reflow.
|
|
134
|
+
*
|
|
135
|
+
* Under reduced motion it does nothing at all: §7.1 rule 10, and the state is
|
|
136
|
+
* always also in text (the live region), so nothing is lost.
|
|
137
|
+
*/
|
|
138
|
+
export declare function useFormFlip(pillRef: RefObject<HTMLElement | null>, rowRef: RefObject<HTMLElement | null>, form: 'pill' | 'row', reducedMotion: boolean, durationMs?: number): void;
|
|
139
|
+
/**
|
|
140
|
+
* The durations every dock surface reads, already collapsed for reduced
|
|
141
|
+
* motion. One object so a component never writes `reduced ? 0 : 240` itself
|
|
142
|
+
* and never forgets the `reduced` half.
|
|
143
|
+
*/
|
|
144
|
+
export interface DockDurations {
|
|
145
|
+
readonly swap: number;
|
|
146
|
+
readonly recede: number;
|
|
147
|
+
readonly sheetOpen: number;
|
|
148
|
+
readonly sheetClose: number;
|
|
149
|
+
readonly sheetSnap: number;
|
|
150
|
+
readonly caption: number;
|
|
151
|
+
readonly border: number;
|
|
152
|
+
readonly control: number;
|
|
153
|
+
}
|
|
154
|
+
export declare function useDockDurations(reducedMotion: boolean): DockDurations;
|
|
155
|
+
//# sourceMappingURL=dock-motion.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dock-motion.d.ts","sourceRoot":"","sources":["../../src/dock/dock-motion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE1F,wEAAwE;AACxE,eAAO,MAAM,OAAO,MAAM,CAAC;AAC3B,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,eAAO,MAAM,WAAW,+BAA+B,CAAC;AACxD,2FAA2F;AAC3F,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,eAAO,MAAM,kBAAkB,+BAA+B,CAAC;AAC/D,uCAAuC;AACvC,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,gEAAgE;AAChE,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,iDAAiD;AACjD,eAAO,MAAM,UAAU,OAAO,CAAC;AAC/B,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAiBjD;AAeD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GACjC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAqCvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,UAAU,SAAuB,EACjC,EAAE,SAAU,GACX,MAAM,IAAI,CAoCZ;AAED,0GAA0G;AAC1G,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,MAAM,CAQhE;AAOD,yEAAyE;AACzE,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAa,GAAG,MAAM,CAEjF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACtC,MAAM,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACrC,IAAI,EAAE,MAAM,GAAG,KAAK,EACpB,aAAa,EAAE,OAAO,EACtB,UAAU,SAAU,GACnB,IAAI,CAsCN;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,OAAO,GAAG,aAAa,CA0BtE"}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import type { RefObject } from 'react';
|
|
2
|
+
import { type DockIdentityView } from './dock-row.js';
|
|
3
|
+
import type { DockMark } from './dock-state.js';
|
|
4
|
+
/**
|
|
5
|
+
* THE PILL — docs/DOCK_SPEC.md §3.2. The resting and receded form.
|
|
6
|
+
*
|
|
7
|
+
* "Deliberately ignorable: before a session it is a link, not a presence."
|
|
8
|
+
* One `<button>`, named by its label plus "expand" (§11), anchored at the
|
|
9
|
+
* THUMB edge — `right` in LTR, `left` in RTL — through logical properties so
|
|
10
|
+
* the mirror costs nothing (§8.9).
|
|
11
|
+
*
|
|
12
|
+
* Both this and the row are in the DOM at all times and the swap between them
|
|
13
|
+
* is a VISIBILITY change, never a build-and-destroy: two live boxes can be
|
|
14
|
+
* measured and FLIPped against each other (§7.2), and neither costs the
|
|
15
|
+
* merchant's page a layout mid-gesture. That is the same choice
|
|
16
|
+
* `cdn/dock-dom.ts` makes for the same reason, which is what lets the two
|
|
17
|
+
* renderers hand over without moving anything (§4.2).
|
|
18
|
+
*
|
|
19
|
+
* During a LIVE call the pill shows the session mark and the caption's
|
|
20
|
+
* current line in place of the label, and the call continues (§5.4) — a
|
|
21
|
+
* shopper who minimises mid-conversation has asked for less screen, not for
|
|
22
|
+
* the conversation to end.
|
|
23
|
+
*/
|
|
24
|
+
export interface DockPillProps {
|
|
25
|
+
readonly identity: DockIdentityView;
|
|
26
|
+
readonly mark: DockMark;
|
|
27
|
+
/** The tenant's `minimisedLabel`, or the shipped default for this device (§3.2). */
|
|
28
|
+
readonly label: string;
|
|
29
|
+
/** The live caption, shown INSTEAD of the label during a session (§3.2). */
|
|
30
|
+
readonly line?: string;
|
|
31
|
+
/** §11 — "one `<button>` named by its label plus 'expand'". */
|
|
32
|
+
readonly expandLabel: string;
|
|
33
|
+
readonly form: 'pill' | 'row';
|
|
34
|
+
readonly onPress: () => void;
|
|
35
|
+
readonly pillRef?: RefObject<HTMLButtonElement | null>;
|
|
36
|
+
}
|
|
37
|
+
export declare function DockPill({ identity, mark, label, line, expandLabel, form, onPress, pillRef, }: DockPillProps): import("react").JSX.Element;
|
|
38
|
+
//# sourceMappingURL=dock-pill.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dock-pill.d.ts","sourceRoot":"","sources":["../../src/dock/dock-pill.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;CACxD;AAED,wBAAgB,QAAQ,CAAC,EACvB,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,WAAW,EACX,IAAI,EACJ,OAAO,EACP,OAAO,GACR,EAAE,aAAa,+BA4Bf"}
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import type { RefObject } from 'react';
|
|
2
|
+
import { type WidgetMessages } from '../messages.js';
|
|
3
|
+
import type { DockControl, DockMark, DockView } from './dock-state.js';
|
|
4
|
+
/**
|
|
5
|
+
* THE ROW — docs/DOCK_SPEC.md §2's four fixed slots, in order, in every state.
|
|
6
|
+
*
|
|
7
|
+
* `MARK | ACTIVITY | CAPTION | CONTROLS ≤3`, 48 px tall (44 px of content plus
|
|
8
|
+
* the 2 px border, which is what lets every control keep a 44 px target
|
|
9
|
+
* inside it — §11). Nothing is ever ADDED to the row: the activity slot keeps
|
|
10
|
+
* its 20 px even when empty, exactly as the core dock reserves it, so React
|
|
11
|
+
* arriving does not change the row's shape (§4.2).
|
|
12
|
+
*
|
|
13
|
+
* This component decides nothing. Which controls exist, what the caption
|
|
14
|
+
* says, whether the border is live and how the mark is treated all come from
|
|
15
|
+
* `deriveDockState` (`dock-state.ts`); the row renders that view and reports
|
|
16
|
+
* presses back. That split is what makes §5.1's thirteen-row table assertable
|
|
17
|
+
* without a DOM.
|
|
18
|
+
*
|
|
19
|
+
* ## Two things here are behaviour, not decoration
|
|
20
|
+
*
|
|
21
|
+
* **Tap anywhere on the row interrupts a reply.** §5.1: the interrupt is the
|
|
22
|
+
* first control in `speaking`, but a thumb on a phone does not aim — the
|
|
23
|
+
* whole row is the target while the agent is talking. The handler ignores
|
|
24
|
+
* presses that landed on a real control, so muting is muting and not also an
|
|
25
|
+
* interrupt.
|
|
26
|
+
*
|
|
27
|
+
* **The interrupt is LABELLED the first two times per visitor**, then becomes
|
|
28
|
+
* an icon. A person who has interrupted twice knows how; a person who never
|
|
29
|
+
* has cannot discover it from a glyph. The counter lives in `localStorage`
|
|
30
|
+
* and is read by `dock.tsx` — this component only renders what it is told.
|
|
31
|
+
*/
|
|
32
|
+
export type DockAvatarKind = 'orb' | 'knot' | 'image' | 'none';
|
|
33
|
+
/** Which gesture pressed the microphone — see `DockRowProps.onMicDown`. */
|
|
34
|
+
export type DockMicSource = 'touch' | 'pointer' | 'key';
|
|
35
|
+
export interface DockIdentityView {
|
|
36
|
+
readonly name: string;
|
|
37
|
+
readonly avatar: DockAvatarKind;
|
|
38
|
+
readonly avatarUrl?: string;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* The tenant's mark, at whatever size the row (32 px) or the pill (28 px)
|
|
42
|
+
* asks for.
|
|
43
|
+
*
|
|
44
|
+
* §9.3 validates `avatarUrl` at publish and `cdn/dock-dom.ts` validates it
|
|
45
|
+
* AGAIN at paint; this does the same, for the same reason: the string becomes
|
|
46
|
+
* an `<img src>` on a merchant's page — a real network request a shopper's
|
|
47
|
+
* browser makes on our instruction — and a config record can predate a
|
|
48
|
+
* validator or be replayed from an older row. An unusable URL degrades to the
|
|
49
|
+
* plain dot, never to a broken image or a request to somewhere unexpected.
|
|
50
|
+
*/
|
|
51
|
+
export declare function DockMarkFace({ identity, mark, size, testId, }: {
|
|
52
|
+
identity: DockIdentityView;
|
|
53
|
+
mark: DockMark;
|
|
54
|
+
size: number;
|
|
55
|
+
/** Distinct per surface: the row and the pill both draw a mark. */
|
|
56
|
+
testId?: string;
|
|
57
|
+
}): import("react").JSX.Element;
|
|
58
|
+
/** §2's activity slot: five bars while audio flows, a thin track during retrieval. */
|
|
59
|
+
export declare function DockActivitySlot({ activity }: {
|
|
60
|
+
activity: DockView['activity'];
|
|
61
|
+
}): import("react").JSX.Element;
|
|
62
|
+
export interface DockRowProps {
|
|
63
|
+
readonly view: DockView;
|
|
64
|
+
readonly identity: DockIdentityView;
|
|
65
|
+
/** Which form is showing — the row is always in the DOM, so the swap is a visibility change (§7.2). */
|
|
66
|
+
readonly form: 'pill' | 'row';
|
|
67
|
+
readonly messages: WidgetMessages;
|
|
68
|
+
/** The resolved caption line, or `undefined` when the FIELD is the caption. */
|
|
69
|
+
readonly captionLine?: string;
|
|
70
|
+
readonly captionSwapKey: string;
|
|
71
|
+
/** See `DockCaptionProps.lineTestId`. */
|
|
72
|
+
readonly captionTestId?: string;
|
|
73
|
+
readonly draft: string;
|
|
74
|
+
readonly onDraftChange: (value: string) => void;
|
|
75
|
+
readonly onSubmit: () => void;
|
|
76
|
+
readonly placeholder: string;
|
|
77
|
+
/**
|
|
78
|
+
* The composer cannot take a turn right now — the scripted preview while its
|
|
79
|
+
* canned reply is pending, a host mid-send.
|
|
80
|
+
*
|
|
81
|
+
* Deliberately NOT used for a live call: §5.2's "text is always one tap
|
|
82
|
+
* away" means the field stays usable through every voice state, which is
|
|
83
|
+
* also what lets a shopper type "get me a human" mid-call.
|
|
84
|
+
*/
|
|
85
|
+
readonly composerDisabled?: boolean;
|
|
86
|
+
/** Press on any control other than the microphone. */
|
|
87
|
+
readonly onControl: (control: DockControl) => void;
|
|
88
|
+
/**
|
|
89
|
+
* §5.2's hold-to-talk. Down starts + unmutes, up mutes and sends the
|
|
90
|
+
* end-of-utterance hint — but only for a HOLD. The source is passed through
|
|
91
|
+
* rather than inferred, because the same button is three gestures: a thumb
|
|
92
|
+
* holding it (`touch`), a desktop pointer clicking it (`pointer`, which
|
|
93
|
+
* toggles), and `Space` held on the keyboard (`key`, which mirrors the
|
|
94
|
+
* thumb — §11: "the hold-to-talk mic is also operable by keyboard").
|
|
95
|
+
*/
|
|
96
|
+
readonly onMicDown: (source: DockMicSource) => void;
|
|
97
|
+
/**
|
|
98
|
+
* The end of a microphone gesture. `cancelled` marks the ones the BROWSER
|
|
99
|
+
* ended rather than the shopper — see the `pointercancel` handler.
|
|
100
|
+
*/
|
|
101
|
+
readonly onMicUp: (source: DockMicSource, cancelled?: boolean) => void;
|
|
102
|
+
/** §5.1 — labelled the first two times per visitor, an icon after. */
|
|
103
|
+
readonly interruptLabelled: boolean;
|
|
104
|
+
/** `true` while the microphone is published — drives the mute control's `aria-pressed`. */
|
|
105
|
+
readonly micOpen: boolean;
|
|
106
|
+
/** Drawn and dimmed rather than hidden — see `DockVoiceProps.disabled`. */
|
|
107
|
+
readonly micDisabled?: boolean;
|
|
108
|
+
/** Its accessible name while it cannot be used — see `DockVoiceProps.unavailableReason`. */
|
|
109
|
+
readonly micUnavailableReason?: string;
|
|
110
|
+
/** An upload is in flight, so the paperclip is not offered again — see the `attach` control. */
|
|
111
|
+
readonly attachBusy?: boolean;
|
|
112
|
+
readonly rowRef?: RefObject<HTMLDivElement | null>;
|
|
113
|
+
readonly inputRef?: RefObject<HTMLInputElement | null>;
|
|
114
|
+
readonly captionDurationMs: number;
|
|
115
|
+
/** §11 — the mark's accessible name carries the live/rest state in words. */
|
|
116
|
+
readonly markStateLabel: string;
|
|
117
|
+
readonly onMarkPress: () => void;
|
|
118
|
+
}
|
|
119
|
+
export declare function DockRow({ view, identity, form, messages, captionLine, captionSwapKey, captionTestId, draft, onDraftChange, onSubmit, placeholder, composerDisabled, onControl, onMicDown, onMicUp, interruptLabelled, micOpen, micDisabled, micUnavailableReason, attachBusy, rowRef, inputRef, captionDurationMs, markStateLabel, onMarkPress, }: DockRowProps): import("react").JSX.Element;
|
|
120
|
+
//# sourceMappingURL=dock-row.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dock-row.d.ts","sourceRoot":"","sources":["../../src/dock/dock-row.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,SAAS,EAAE,MAAM,OAAO,CAAC;AAE9D,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE3F,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAM/D,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,MAAM,GACP,EAAE;IACD,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,+BAmDA;AAOD,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAA;CAAE,+BAmBhF;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IACnD;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACvE,sEAAsE;IACtE,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,gGAAgG;IAChG,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACvD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;CAClC;AAED,wBAAgB,OAAO,CAAC,EACtB,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,WAAW,EACX,cAAc,EACd,aAAa,EACb,KAAK,EACL,aAAa,EACb,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,OAAO,EACP,iBAAiB,EACjB,OAAO,EACP,WAAW,EACX,oBAAoB,EACpB,UAAU,EACV,MAAM,EACN,QAAQ,EACR,iBAAiB,EACjB,cAAc,EACd,WAAW,GACZ,EAAE,YAAY,+BAwEd"}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { type ReactNode, type RefObject } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* THE SHEET — docs/DOCK_SPEC.md §3.3, and the one surface in this package
|
|
4
|
+
* that is NOT a modal on purpose.
|
|
5
|
+
*
|
|
6
|
+
* §1 rule 2: "Never a modal. No backdrop, no blur, no focus trap, no
|
|
7
|
+
* `aria-modal`. The page stays interactive in every state." So:
|
|
8
|
+
*
|
|
9
|
+
* - `role="dialog"` **without** `aria-modal` (§11). The role names the
|
|
10
|
+
* surface; `aria-modal` would tell a screen reader the rest of the page is
|
|
11
|
+
* inert, which is a lie — a shopper can still tap a product behind it, and
|
|
12
|
+
* that is the whole design.
|
|
13
|
+
* - **No focus trap.** `Tab` from the last control leaves the widget and
|
|
14
|
+
* lands on the merchant's page. A trap on a storefront is how a widget
|
|
15
|
+
* becomes the thing a shopper cannot escape.
|
|
16
|
+
* - `Escape` closes the sheet and returns focus to the caption field — it
|
|
17
|
+
* does not "close the concierge", because there is nothing to close. The
|
|
18
|
+
* handler lives on the DOCK's root (`dock.tsx`), not here: the shopper's
|
|
19
|
+
* focus is as likely to be on the row's mark or the composer as inside the
|
|
20
|
+
* sheet, and a handler that only listened where the sheet has focus would
|
|
21
|
+
* answer `Escape` in one of those places and not the other.
|
|
22
|
+
* - **No blur** (§7.1 rule 11). Opaque `--wgt-surface`.
|
|
23
|
+
*
|
|
24
|
+
* ## Three snap points, and why the floor never moves
|
|
25
|
+
*
|
|
26
|
+
* `closed` / `peek` (three shelf rows) / `expanded`. The ROW is the sheet's
|
|
27
|
+
* floor and never moves when the sheet opens — the shopper's thumb stays
|
|
28
|
+
* where they left it, which is the difference between a surface that grew and
|
|
29
|
+
* one that jumped.
|
|
30
|
+
*
|
|
31
|
+
* Below a 500 px viewport height the sheet offers `peek` only (§3.3): an
|
|
32
|
+
* expanded sheet on a short landscape phone is a takeover with a keyboard
|
|
33
|
+
* over it.
|
|
34
|
+
*
|
|
35
|
+
* ## The drag is pointer events, and `touch-action: none` is on the HANDLE
|
|
36
|
+
*
|
|
37
|
+
* §7.1 rule 8. On the sheet BODY, `touch-action: none` would kill the
|
|
38
|
+
* internal scroll the shopper needs to read the transcript. The handle is the
|
|
39
|
+
* only element that claims the gesture, and the position it writes is a CSS
|
|
40
|
+
* custom property written once per frame (rule 5) — never React state, or a
|
|
41
|
+
* drag would re-render the whole conversation sixty times a second.
|
|
42
|
+
*
|
|
43
|
+
* ## Growth follows the reader, not the content
|
|
44
|
+
*
|
|
45
|
+
* A streamed reply grows the sheet's contents. The scroll follows ONLY if the
|
|
46
|
+
* reader was already at the bottom — the same `FOLLOW_TOLERANCE_PX` rule the
|
|
47
|
+
* retired panel used, and for the same reason: yanking someone back down
|
|
48
|
+
* while they are re-reading an earlier answer is worse than a message they
|
|
49
|
+
* have to scroll for.
|
|
50
|
+
*/
|
|
51
|
+
export type DockSheetSnap = 'closed' | 'peek' | 'expanded';
|
|
52
|
+
/**
|
|
53
|
+
* How far off the bottom still counts as "following". Not zero: fractional
|
|
54
|
+
* scroll metrics on zoomed and hi-dpi displays never land exactly on the
|
|
55
|
+
* bottom, and a smooth scroll is still in flight when the next streamed token
|
|
56
|
+
* resizes the content.
|
|
57
|
+
*/
|
|
58
|
+
export declare const FOLLOW_TOLERANCE_PX = 24;
|
|
59
|
+
/**
|
|
60
|
+
* How many frames the follow may spend converging on the newest row.
|
|
61
|
+
*
|
|
62
|
+
* §7.1 rule 3's `content-visibility: auto` makes the transcript's scroll range
|
|
63
|
+
* an estimate until the rows in question have been rendered once, so the first
|
|
64
|
+
* assignment lands short and each subsequent one lands truer. Four frames is
|
|
65
|
+
* ~66 ms at 60 Hz and is a CEILING, not a cost: the loop stops the moment a
|
|
66
|
+
* pass moves nothing, which on a transcript that fits is the first one.
|
|
67
|
+
*/
|
|
68
|
+
export declare const FOLLOW_SETTLE_FRAMES = 4;
|
|
69
|
+
export interface DockSheetProps {
|
|
70
|
+
readonly snap: DockSheetSnap;
|
|
71
|
+
readonly onSnapChange: (snap: DockSheetSnap) => void;
|
|
72
|
+
/** §11 — labelled by the identity name, never by "dialog". */
|
|
73
|
+
readonly label: string;
|
|
74
|
+
/** §3.3 — `peek` only below a 500 px viewport height. */
|
|
75
|
+
readonly peekOnly: boolean;
|
|
76
|
+
/** The sheet's own header row: "Show what was said", "Minimise". */
|
|
77
|
+
readonly header?: ReactNode;
|
|
78
|
+
readonly children: ReactNode;
|
|
79
|
+
/** `Escape`, and every "the shopper turned to the page" close — returns focus to the caption. */
|
|
80
|
+
readonly onDismiss: () => void;
|
|
81
|
+
/** Bumped whenever the contents grew, so the scroll can follow a reader who was at the bottom. */
|
|
82
|
+
readonly followKey?: unknown;
|
|
83
|
+
readonly sheetRef?: RefObject<HTMLDivElement | null>;
|
|
84
|
+
/** 0 under reduced motion (§7.1 rule 10). */
|
|
85
|
+
readonly durationMs: number;
|
|
86
|
+
readonly dragHandleLabel: string;
|
|
87
|
+
}
|
|
88
|
+
export declare function DockSheet({ snap, onSnapChange, label, peekOnly, header, children, onDismiss, followKey, sheetRef, durationMs, dragHandleLabel, }: DockSheetProps): import("react").JSX.Element;
|
|
89
|
+
//# sourceMappingURL=dock-sheet.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dock-sheet.d.ts","sourceRoot":"","sources":["../../src/dock/dock-sheet.tsx"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAKf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAQtC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;IACrD,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,iGAAiG;IACjG,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;IAC/B,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrD,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,SAAS,EACT,SAAS,EACT,QAAQ,EACR,UAAU,EACV,eAAe,GAChB,EAAE,cAAc,+BAmThB"}
|