@saar-ai/web-widget 0.5.0 → 0.6.1
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/{host-widget-B0SkhMIs.js → host-widget-CAPud_Jz.js} +4609 -5776
- 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 +270 -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/dock/motion-gate.d.ts +123 -0
- package/dist/dock/motion-gate.d.ts.map +1 -0
- package/dist/generated/widget-css.d.ts.map +1 -1
- package/dist/host-widget.d.ts +94 -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 +69 -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/use-chat-session.d.ts +18 -16
- package/dist/use-chat-session.d.ts.map +1 -1
- package/dist/use-voice-session.d.ts +79 -3
- package/dist/use-voice-session.d.ts.map +1 -1
- package/dist/voice-widget.d.ts +49 -19
- 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 +758 -28
- package/src/styles/tokens.css +67 -0
- 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,270 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* THE DOCK'S MOTION — docs/DOCK_SPEC.md §7, as the primitives every surface
|
|
3
|
+
* 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 rules the dock cannot
|
|
7
|
+
* 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
|
+
* - **rule 12 — transitions finalise without `transitionend`.** A hidden tab
|
|
26
|
+
* does not advance a CSS transition, so a dock that waits for the event
|
|
27
|
+
* waits forever and strands itself mid-swap with both forms
|
|
28
|
+
* `visibility: hidden`. {@link useMotionOff} folds "the tab is hidden"
|
|
29
|
+
* into rule 10's single read, and `motion-gate.ts` owns the fallback
|
|
30
|
+
* timer, the explicit end state and the `visibilitychange` finalisation —
|
|
31
|
+
* it is React-free because the core dock (`cdn/dock-dom.ts`) has the same
|
|
32
|
+
* hazard and cannot afford a framework.
|
|
33
|
+
* - **§7.2's pill ↔ row FLIP.** Measure both boxes, animate the difference
|
|
34
|
+
* on `transform` alone. Never `width`/`height`/`left` — see the guard.
|
|
35
|
+
*
|
|
36
|
+
* Nothing here renders. Nothing here imports React DOM. It is hooks plus two
|
|
37
|
+
* pure helpers, so the arithmetic (`flipTransform`, `lerp`) is unit-testable
|
|
38
|
+
* without a layout engine jsdom does not have.
|
|
39
|
+
*/
|
|
40
|
+
import { type RefObject } from 'react';
|
|
41
|
+
import { type MotionEndState } from './motion-gate.js';
|
|
42
|
+
/** §7.2 — the pill ↔ row swap, and the recede/expand that reuses it. */
|
|
43
|
+
export declare const SWAP_MS = 240;
|
|
44
|
+
export declare const RECEDE_MS = 200;
|
|
45
|
+
export declare const SWAP_EASING = "cubic-bezier(0.2, 0, 0, 1)";
|
|
46
|
+
/** §7.2 — the sheet opens with the same easing and closes faster, with a different one. */
|
|
47
|
+
export declare const SHEET_OPEN_MS = 240;
|
|
48
|
+
export declare const SHEET_CLOSE_MS = 180;
|
|
49
|
+
export declare const SHEET_CLOSE_EASING = "cubic-bezier(0.4, 0, 1, 1)";
|
|
50
|
+
/** §7.2 — the sheet's release snap. */
|
|
51
|
+
export declare const SHEET_SNAP_MS = 200;
|
|
52
|
+
/** §7.2 — caption cross-fade, border colour, control in/out. */
|
|
53
|
+
export declare const CAPTION_MS = 160;
|
|
54
|
+
export declare const BORDER_MS = 160;
|
|
55
|
+
export declare const CONTROL_MS = 120;
|
|
56
|
+
/** §7.2 — the waveform's per-frame smoothing. */
|
|
57
|
+
export declare const LEVEL_LERP = 0.25;
|
|
58
|
+
/** §5.5 — a page scroll past this much closes the sheet and ducks a live reply. */
|
|
59
|
+
export declare const PAGE_SCROLL_DUCK_PX = 24;
|
|
60
|
+
/** §3.3 — a downward drag past this fraction of the sheet's height dismisses it. */
|
|
61
|
+
export declare const SHEET_DISMISS_FRACTION = 0.4;
|
|
62
|
+
/**
|
|
63
|
+
* `prefers-reduced-motion`, as a subscription rather than a one-shot read.
|
|
64
|
+
*
|
|
65
|
+
* A shopper can turn it on mid-session (iOS has it in Control Center), and a
|
|
66
|
+
* dock that only read it at mount would keep animating for the rest of the
|
|
67
|
+
* page. Falls back to `true`-is-safe on a window with no `matchMedia`: a
|
|
68
|
+
* static dock is always correct, an animated one is not.
|
|
69
|
+
*/
|
|
70
|
+
export declare function usePrefersReducedMotion(): boolean;
|
|
71
|
+
/**
|
|
72
|
+
* §7.1 rule 12 — `document.visibilityState`, as a subscription.
|
|
73
|
+
*
|
|
74
|
+
* A one-shot read at mount would be the wrong answer for the whole of the
|
|
75
|
+
* rest of the visit, and the visit is where this matters: the shopper taps
|
|
76
|
+
* the pill and then locks the phone. Both edges are reported, because both
|
|
77
|
+
* change what the dock is allowed to do — hidden means "apply the end state,
|
|
78
|
+
* animate nothing", visible means "a stalled transition, if there is one, has
|
|
79
|
+
* to be finalised now".
|
|
80
|
+
*/
|
|
81
|
+
export declare function useDocumentHidden(): boolean;
|
|
82
|
+
/**
|
|
83
|
+
* "Motion is off." §7.1 rule 10 and rule 12 in ONE read, because a surface
|
|
84
|
+
* that has to remember two of them will eventually remember one.
|
|
85
|
+
*
|
|
86
|
+
* `prefers-reduced-motion` is a preference and a hidden tab is a fact, but
|
|
87
|
+
* they ask the dock for the same thing: skip the animation, apply the end
|
|
88
|
+
* state now. Every duration in {@link useDockDurations} collapses to 0, the
|
|
89
|
+
* FLIP does not start, and the caption swaps in place.
|
|
90
|
+
*/
|
|
91
|
+
export declare function useMotionOff(): boolean;
|
|
92
|
+
/**
|
|
93
|
+
* §7.1 rule 5 — a per-frame custom-property writer.
|
|
94
|
+
*
|
|
95
|
+
* Returns `set(name, value)`. Calls COALESCE: whatever the last value for a
|
|
96
|
+
* name is when the frame runs is what gets written, so a drag handler firing
|
|
97
|
+
* at pointer rate still costs one style write per frame. Nothing here
|
|
98
|
+
* re-renders anything.
|
|
99
|
+
*
|
|
100
|
+
* @param ref the one element the properties are written on
|
|
101
|
+
*/
|
|
102
|
+
export declare function useCssVars(ref: RefObject<HTMLElement | null>): (name: string, value: string) => void;
|
|
103
|
+
/**
|
|
104
|
+
* §7.1 rule 4 — `will-change`, for the length of one transition and no longer.
|
|
105
|
+
*
|
|
106
|
+
* Returns `arm()`. Sets `will-change` on the element, then clears it on the
|
|
107
|
+
* element's OWN `transitionend` (or after `ms`, for a transition that never
|
|
108
|
+
* fires one — an element that was already at its target value produces no
|
|
109
|
+
* event, and a layer promoted forever is exactly what rule 4 exists to
|
|
110
|
+
* prevent).
|
|
111
|
+
*
|
|
112
|
+
* ## Why the `event.target` check is load-bearing
|
|
113
|
+
*
|
|
114
|
+
* `transitionend` BUBBLES, and this hook is armed on surfaces that contain
|
|
115
|
+
* other people's motion. `dock-sheet.tsx` arms it on `.wgt-sheet`, whose body
|
|
116
|
+
* is the transcript, and `widget-cards.tsx` renders buttons in there with
|
|
117
|
+
* Tailwind's `transition-colors`. A hover settling, a focus ring, an
|
|
118
|
+
* "Adding…" label changing colour — any descendant transition finishing
|
|
119
|
+
* inside the sheet's 240 ms reveal reached this listener as though it were
|
|
120
|
+
* the sheet's own, and the layer was demoted in the middle of the animation
|
|
121
|
+
* it had been promoted for. That is the stutter rule 4 exists to remove,
|
|
122
|
+
* caused by the code written to obey it.
|
|
123
|
+
*
|
|
124
|
+
* ## Why the cleanup clears more than the timer
|
|
125
|
+
*
|
|
126
|
+
* The element can go away mid-transition — `core.ts` tears the React stage
|
|
127
|
+
* down on `destroy()`, and the sheet unmounts on every close. Clearing only
|
|
128
|
+
* the timer left the listener attached and `will-change` set on a node that
|
|
129
|
+
* no longer renders, so the layer survived the component and the closure
|
|
130
|
+
* survived with it.
|
|
131
|
+
*
|
|
132
|
+
* ## Why the promotion is not the only thing this arms (§7.1 rule 12)
|
|
133
|
+
*
|
|
134
|
+
* The `transitionend` this waits for never arrives in a hidden tab, and a
|
|
135
|
+
* sheet whose reveal was interrupted by a lock screen is not merely a layer
|
|
136
|
+
* left promoted — it is a `visibility: hidden` box that the shopper cannot
|
|
137
|
+
* see or reach. `arm(endState)` therefore hands the whole finalisation to
|
|
138
|
+
* `motion-gate.ts`: the fallback timer, the `visibilitychange` edge, and the
|
|
139
|
+
* explicit end state the surface passes in. Armed while the tab is already
|
|
140
|
+
* hidden (or with a zeroed duration), it promotes nothing at all and applies
|
|
141
|
+
* that end state synchronously — there is no animation to give a layer to.
|
|
142
|
+
*/
|
|
143
|
+
export declare function useTransientWillChange(ref: RefObject<HTMLElement | null>, properties?: string, ms?: number): (endState?: MotionEndState) => void;
|
|
144
|
+
/** A box, as the FLIP needs it. Deliberately not a `DOMRect` — the arithmetic is testable without one. */
|
|
145
|
+
export interface FlipBox {
|
|
146
|
+
readonly x: number;
|
|
147
|
+
readonly y: number;
|
|
148
|
+
readonly width: number;
|
|
149
|
+
readonly height: number;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* §7.2's FLIP, reduced to the one `transform` that takes `to` back onto
|
|
153
|
+
* `from`.
|
|
154
|
+
*
|
|
155
|
+
* Pure, and pure on purpose: jsdom has no layout engine, so the only way to
|
|
156
|
+
* test the choreography at all is to test the arithmetic separately from the
|
|
157
|
+
* measuring. A zero-area `from` (an element that was `display: none`, or a
|
|
158
|
+
* measurement taken before layout) yields the identity transform rather than
|
|
159
|
+
* a division by zero — the animation is skipped, which is the right
|
|
160
|
+
* degradation.
|
|
161
|
+
*
|
|
162
|
+
* @returns a `transform` value that visually places `to` where `from` was
|
|
163
|
+
*/
|
|
164
|
+
export declare function flipTransform(from: FlipBox, to: FlipBox): string;
|
|
165
|
+
/** §7.2's waveform smoothing — the same 0.25 lerp the analyser feeds. */
|
|
166
|
+
export declare function lerp(current: number, target: number, factor?: number): number;
|
|
167
|
+
/**
|
|
168
|
+
* §7.2's two forms at rest, as the inline properties a §7.1 rule 12
|
|
169
|
+
* finalisation writes.
|
|
170
|
+
*
|
|
171
|
+
* These MIRROR `.wgt-row[data-form='pill']` and `.wgt-pill[data-form='row']`
|
|
172
|
+
* in `styles/concierge.css` — the cascade is still what draws the dock, and
|
|
173
|
+
* this table is only ever written for the one frame in which a stalled
|
|
174
|
+
* transition is being cancelled. `dock-motion.test.ts` reads the stylesheet
|
|
175
|
+
* and asserts the two agree, because a divergence here is invisible until a
|
|
176
|
+
* shopper locks their phone mid-swap and comes back to a dock in the wrong
|
|
177
|
+
* shape.
|
|
178
|
+
*/
|
|
179
|
+
export declare const FORM_END_STATE: {
|
|
180
|
+
/** Either form, showing. The base rule for both boxes. */
|
|
181
|
+
readonly shown: {
|
|
182
|
+
readonly visibility: 'visible';
|
|
183
|
+
readonly opacity: '1';
|
|
184
|
+
readonly transform: 'none';
|
|
185
|
+
};
|
|
186
|
+
/** `.wgt-pill[data-form='row']`. */
|
|
187
|
+
readonly pillHidden: {
|
|
188
|
+
readonly visibility: 'hidden';
|
|
189
|
+
readonly opacity: '0';
|
|
190
|
+
readonly transform: 'scale(0.92)';
|
|
191
|
+
};
|
|
192
|
+
/** `.wgt-row[data-form='pill']`. */
|
|
193
|
+
readonly rowHidden: {
|
|
194
|
+
readonly visibility: 'hidden';
|
|
195
|
+
readonly opacity: '0';
|
|
196
|
+
readonly transform: 'scale(0.98)';
|
|
197
|
+
};
|
|
198
|
+
};
|
|
199
|
+
/**
|
|
200
|
+
* §3.3's sheet at each end of its reveal, as the inline properties a §7.1
|
|
201
|
+
* rule 12 finalisation writes.
|
|
202
|
+
*
|
|
203
|
+
* Mirrors `.wgt-sheet` and `.wgt-sheet[data-snap='closed']` in
|
|
204
|
+
* `styles/concierge.css`, and `dock-motion.test.ts` asserts they agree. The
|
|
205
|
+
* open state keeps `transform` expressed through `--wgt-sheet-y` rather than
|
|
206
|
+
* as a resolved `translateY(0px)`: the drag writes that custom property once
|
|
207
|
+
* per frame (§7.1 rule 5), and a finaliser that resolved it would pin the
|
|
208
|
+
* sheet to wherever the last gesture left it.
|
|
209
|
+
*/
|
|
210
|
+
export declare const SHEET_END_STATE: {
|
|
211
|
+
readonly open: {
|
|
212
|
+
readonly visibility: 'visible';
|
|
213
|
+
readonly opacity: '1';
|
|
214
|
+
readonly 'clip-path': 'inset(0 0 0 0)';
|
|
215
|
+
readonly transform: 'translateY(var(--wgt-sheet-y, 0px))';
|
|
216
|
+
};
|
|
217
|
+
readonly closed: {
|
|
218
|
+
readonly visibility: 'hidden';
|
|
219
|
+
readonly opacity: '0';
|
|
220
|
+
readonly 'clip-path': 'inset(100% 0 0 0)';
|
|
221
|
+
readonly transform: 'translateY(8px)';
|
|
222
|
+
};
|
|
223
|
+
};
|
|
224
|
+
/**
|
|
225
|
+
* The pill ↔ row swap (§7.2), driven by whichever box is showing.
|
|
226
|
+
*
|
|
227
|
+
* Both boxes exist at all times — the swap is a VISIBILITY change, never a
|
|
228
|
+
* build-and-destroy, exactly as the core dock (`cdn/dock-dom.ts`) already
|
|
229
|
+
* does it — so this measures the outgoing box before the change, and after
|
|
230
|
+
* the change puts the incoming one back where the outgoing one was and
|
|
231
|
+
* releases it. One layout read, one style write, no host reflow.
|
|
232
|
+
*
|
|
233
|
+
* Under reduced motion, or in a hidden tab, it does nothing at all but write
|
|
234
|
+
* both end states: §7.1 rules 10 and 12, and the state is always also in text
|
|
235
|
+
* (the live region), so nothing is lost. `motionOff` is the caller's single
|
|
236
|
+
* read of both (see {@link useMotionOff}).
|
|
237
|
+
*
|
|
238
|
+
* ## The FLIP is not the only thing being finalised here
|
|
239
|
+
*
|
|
240
|
+
* The WAAPI animation below is the cross-fade's TRAVEL. The cross-fade
|
|
241
|
+
* itself — `opacity`, `transform`, and the `visibility` that takes the
|
|
242
|
+
* outgoing form out of the tab order — is a CSS transition on both elements,
|
|
243
|
+
* driven by `data-form`, and it is the one that froze on production: a hidden
|
|
244
|
+
* tab left `.wgt-row` at `opacity: 0.6`, `visibility: hidden` with the pill
|
|
245
|
+
* hidden too, so there was nothing on screen to tap. Each form therefore gets
|
|
246
|
+
* its own finaliser, with its own end state, on every swap.
|
|
247
|
+
*/
|
|
248
|
+
export declare function useFormFlip(pillRef: RefObject<HTMLElement | null>, rowRef: RefObject<HTMLElement | null>, form: 'pill' | 'row', motionOff: boolean, durationMs?: number): void;
|
|
249
|
+
/**
|
|
250
|
+
* The durations every dock surface reads, already collapsed for the two cases
|
|
251
|
+
* where there is no animation. One object so a component never writes
|
|
252
|
+
* `off ? 0 : 240` itself and never forgets the `off` half.
|
|
253
|
+
*/
|
|
254
|
+
export interface DockDurations {
|
|
255
|
+
readonly swap: number;
|
|
256
|
+
readonly recede: number;
|
|
257
|
+
readonly sheetOpen: number;
|
|
258
|
+
readonly sheetClose: number;
|
|
259
|
+
readonly sheetSnap: number;
|
|
260
|
+
readonly caption: number;
|
|
261
|
+
readonly border: number;
|
|
262
|
+
readonly control: number;
|
|
263
|
+
}
|
|
264
|
+
/**
|
|
265
|
+
* @param motionOff §7.1 rule 10 (`prefers-reduced-motion`) OR rule 12 (the
|
|
266
|
+
* tab is hidden and the browser will not advance a transition in it). See
|
|
267
|
+
* {@link useMotionOff}, which is how every caller reads both at once.
|
|
268
|
+
*/
|
|
269
|
+
export declare function useDockDurations(motionOff: boolean): DockDurations;
|
|
270
|
+
//# 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":"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"}
|
|
@@ -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":"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"}
|