@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.
Files changed (63) hide show
  1. package/dist/card-aspect.d.ts +58 -0
  2. package/dist/card-aspect.d.ts.map +1 -0
  3. package/dist/chunks/{host-widget-B0SkhMIs.js → host-widget-CAPud_Jz.js} +4609 -5776
  4. package/dist/chunks/{telemetry-Bw-3F_Zk.js → telemetry-BI_SEWTb.js} +104 -2
  5. package/dist/dock/dock-caption.d.ts +67 -0
  6. package/dist/dock/dock-caption.d.ts.map +1 -0
  7. package/dist/dock/dock-motion.d.ts +270 -0
  8. package/dist/dock/dock-motion.d.ts.map +1 -0
  9. package/dist/dock/dock-pill.d.ts +38 -0
  10. package/dist/dock/dock-pill.d.ts.map +1 -0
  11. package/dist/dock/dock-row.d.ts +120 -0
  12. package/dist/dock/dock-row.d.ts.map +1 -0
  13. package/dist/dock/dock-sheet.d.ts +89 -0
  14. package/dist/dock/dock-sheet.d.ts.map +1 -0
  15. package/dist/dock/dock-shelf.d.ts +38 -0
  16. package/dist/dock/dock-shelf.d.ts.map +1 -0
  17. package/dist/dock/dock-state.d.ts +221 -0
  18. package/dist/dock/dock-state.d.ts.map +1 -0
  19. package/dist/dock/dock.d.ts +344 -0
  20. package/dist/dock/dock.d.ts.map +1 -0
  21. package/dist/dock/geometry.d.ts +161 -0
  22. package/dist/dock/geometry.d.ts.map +1 -0
  23. package/dist/dock/motion-gate.d.ts +123 -0
  24. package/dist/dock/motion-gate.d.ts.map +1 -0
  25. package/dist/generated/widget-css.d.ts.map +1 -1
  26. package/dist/host-widget.d.ts +94 -16
  27. package/dist/host-widget.d.ts.map +1 -1
  28. package/dist/index.d.ts +7 -3
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +4029 -7
  31. package/dist/messages.d.ts +69 -0
  32. package/dist/messages.d.ts.map +1 -1
  33. package/dist/next/index.js +1 -1
  34. package/dist/session-log.d.ts +7 -0
  35. package/dist/session-log.d.ts.map +1 -1
  36. package/dist/session-panel.d.ts +13 -3
  37. package/dist/session-panel.d.ts.map +1 -1
  38. package/dist/theme/color.d.ts +114 -0
  39. package/dist/theme/color.d.ts.map +1 -0
  40. package/dist/theme/derive.d.ts +92 -0
  41. package/dist/theme/derive.d.ts.map +1 -0
  42. package/dist/theme/index.d.ts +10 -0
  43. package/dist/theme/index.d.ts.map +1 -0
  44. package/dist/use-chat-session.d.ts +18 -16
  45. package/dist/use-chat-session.d.ts.map +1 -1
  46. package/dist/use-voice-session.d.ts +79 -3
  47. package/dist/use-voice-session.d.ts.map +1 -1
  48. package/dist/voice-widget.d.ts +49 -19
  49. package/dist/voice-widget.d.ts.map +1 -1
  50. package/dist/widget-cards.d.ts +28 -1
  51. package/dist/widget-cards.d.ts.map +1 -1
  52. package/dist/widget.css +1 -1
  53. package/package.json +4 -4
  54. package/src/styles/concierge.css +758 -28
  55. package/src/styles/tokens.css +67 -0
  56. package/dist/concierge-launcher.d.ts +0 -53
  57. package/dist/concierge-launcher.d.ts.map +0 -1
  58. package/dist/concierge-shell.d.ts +0 -256
  59. package/dist/concierge-shell.d.ts.map +0 -1
  60. package/dist/position.d.ts +0 -65
  61. package/dist/position.d.ts.map +0 -1
  62. package/dist/transcript-geometry.d.ts +0 -220
  63. package/dist/transcript-geometry.d.ts.map +0 -1
@@ -0,0 +1,344 @@
1
+ import { type CSSProperties, type ReactNode } from 'react';
2
+ import { type WidgetImageAspect } from '../card-aspect.js';
3
+ import { type WidgetMessages } from '../messages.js';
4
+ import { type WidgetColorConfig, type WidgetTypeConfig } from '../theme/derive.js';
5
+ import type { ChatCards } from '../use-chat-session.js';
6
+ import { type DesktopAlign, type DesktopWidth, type Direction } from './geometry.js';
7
+ import { DockCaption } from './dock-caption.js';
8
+ import { type DockIdentityView } from './dock-row.js';
9
+ /**
10
+ * THE DOCK — docs/DOCK_SPEC.md §2–§5, composed, plus §4.2's handover.
11
+ *
12
+ * This is what `ConciergeShell` and `ConciergeLauncher` were, and it is a
13
+ * different shape rather than a restyle. There is **no open state**: a pill
14
+ * and a row that swap, and a sheet that rises above the row only while there
15
+ * is something to show. That is what retires the class of bug behind SAA-131
16
+ * — the handover carries a draft and a focus target, and there is no third
17
+ * thing left to lose.
18
+ *
19
+ * ## §4.2, frame by frame, from this side
20
+ *
21
+ * `cdn/dock-dom.ts` froze everything the shopper had done at the moment of
22
+ * intent and `cdn/core.ts` handed it here. The first `useLayoutEffect` below:
23
+ *
24
+ * 1. calls `onReady()` — `cdn/ui.ts` makes this container visible and
25
+ * `cdn/core.ts` removes its own row, both synchronously, inside the
26
+ * `flushSync` that rendered us. One paint.
27
+ * 2. restores focus and the caret onto THIS input, which is why step 1 has
28
+ * to come first: a `visibility: hidden` element cannot take focus.
29
+ *
30
+ * None of the payload can be recovered after the fact — the caret is gone the
31
+ * moment focus moves, the hold gesture is over, and iOS will not unlock audio
32
+ * outside the gesture that started it (§8.5) — which is why it crosses the
33
+ * boundary at all.
34
+ *
35
+ * A hold **released before the room was ready** is remembered here and applied
36
+ * the moment it is (§5.2: "never lost").
37
+ *
38
+ * ## What is deliberately NOT React state
39
+ *
40
+ * The mic level, the keyboard offset and the sheet's drag position (§7.1 rule
41
+ * 5). All three change every frame; all three are written as CSS custom
42
+ * properties by `dock-motion.ts`'s writer, on one element, once per frame.
43
+ */
44
+ /**
45
+ * The small wordmark under the sheet — which adopter's framework fork
46
+ * produced this bundle, not a per-tenant value.
47
+ *
48
+ * A NAME and DATA prop: this package owns no identity of its own and never
49
+ * imports `@wesence/branding` (it publishes to public npm behind an absolute
50
+ * "resolves no `@wesence/*` module at all" guard,
51
+ * `scripts/check-npm-bundle-provenance.mjs`), so the CALLER resolves
52
+ * `branding.name`/`branding.domain` and passes them down. `cdn/core.ts` does
53
+ * this unconditionally for the real merchant-facing embed — that file is
54
+ * CDN-only and out of the guard's scope. Absent ⇒ no attribution renders at
55
+ * all, rather than a placeholder.
56
+ *
57
+ * Declared here, having moved from the retired `concierge-shell.tsx`: the
58
+ * dock is the only surface that renders it now, and the name is kept so every
59
+ * consumer's import keeps compiling.
60
+ */
61
+ export interface WidgetAttribution {
62
+ readonly name: string;
63
+ readonly href: string;
64
+ }
65
+ export interface DockLayoutView {
66
+ readonly desktopAlign: DesktopAlign;
67
+ readonly desktopWidth: DesktopWidth;
68
+ /** §5.4. `never` has no pill at all — no recede, no minimise control. */
69
+ readonly minimised: 'never' | 'shopper' | 'startMinimised';
70
+ }
71
+ /** The tenant's `copy[locale]` (§9.1), as the dock reads it. */
72
+ export interface DockCopyView {
73
+ readonly greeting?: string;
74
+ readonly placeholder?: string;
75
+ readonly offlineMessage?: string;
76
+ readonly minimisedLabel?: string;
77
+ }
78
+ /** The voice leg, as the dock drives it. Absent ⇒ no microphone is ever drawn. */
79
+ export interface DockVoiceProps {
80
+ /** The tenant published voice AND this is not an embedded webview (§8.4). */
81
+ readonly enabled: boolean;
82
+ readonly phase: 'idle' | 'connecting' | 'connected' | 'disconnected' | 'failed';
83
+ readonly micOpen: boolean;
84
+ readonly micPending: boolean;
85
+ /** The browser REFUSED — §5.1's `mic_blocked`. */
86
+ readonly micBlocked?: boolean;
87
+ readonly agentPresent?: boolean;
88
+ readonly agentSpeaking?: boolean;
89
+ readonly callerSpeaking?: boolean;
90
+ readonly awaitingAgent?: boolean;
91
+ /**
92
+ * 0..1 RMS, for the waveform — a LIVE REF, never a number (§7.1 rule 5).
93
+ *
94
+ * The analyser writes it on every animation frame. A number prop here would
95
+ * mean the caller holds it in state, and sixty renders a second of this
96
+ * whole tree for a value whose only destination is `--wgt-level-*`. The
97
+ * waveform's own `requestAnimationFrame` reads `.current` and writes the
98
+ * custom properties; nothing in React ever observes it. See the module doc
99
+ * comment, and `useVoiceSession`'s `agentLevelRef`.
100
+ */
101
+ readonly levelRef?: {
102
+ readonly current: number;
103
+ };
104
+ readonly onStart?: () => void;
105
+ readonly onToggleMute?: () => void;
106
+ /**
107
+ * §5.2 — the end-of-utterance hint sent on release. Absent ⇒ the release
108
+ * still mutes; the endpointer just has to find the boundary itself.
109
+ */
110
+ readonly onEouHint?: () => void;
111
+ /**
112
+ * §5.1's ducked, and the row's own barge-in. `'look'` is the client-
113
+ * initiated pause (§5.5); `'tap'` is a deliberate interrupt — the control,
114
+ * or the row itself while the agent is speaking.
115
+ *
116
+ * The names are `@saar-ai/widget-protocol/telemetry`'s
117
+ * `CALLER_INTERRUPT_REASONS`, which is what reaches the worker and what an
118
+ * operator's console reads back; they are not this component's to invent.
119
+ */
120
+ readonly onInterrupt?: (reason: 'look' | 'tap') => void;
121
+ /**
122
+ * §5.1 — the duck is over: the shopper spoke, or tapped the microphone.
123
+ * Never a timer.
124
+ *
125
+ * The other half of `onInterrupt('look')`. That frame left the worker
126
+ * holding a cancelled turn and deliberately silent, so lifting the duck
127
+ * without this would leave the shopper looking at a live row nobody is
128
+ * going to speak into. Fired ONCE per duck, and only for a duck this dock
129
+ * actually entered.
130
+ */
131
+ readonly onResume?: () => void;
132
+ /** §5.1 — opens the browser's own permission help. Offered once. */
133
+ readonly onFixPermission?: () => void;
134
+ /**
135
+ * Present and DISABLED rather than hidden, for a surface that has no voice
136
+ * leg but wants to show the product has one — the marketing preview, whose
137
+ * page denies `microphone=()` outright. A host with nothing to offer sets
138
+ * `enabled: false` instead and no microphone is drawn at all.
139
+ *
140
+ * Deliberately NOT a §5.1 state: nothing about the session has changed, so
141
+ * nothing about the caption, the border or the sheet should.
142
+ */
143
+ readonly disabled?: boolean;
144
+ /**
145
+ * WHY the microphone cannot be used, replacing its own name for as long as
146
+ * it cannot.
147
+ *
148
+ * A button that performs nothing must not announce an action: a shopper who
149
+ * hears "Start talking" on a control that refuses every press has been told
150
+ * the product is broken. Absent ⇒ `voice_unavailable_escalated`, which is
151
+ * the right answer for §5.1's `human` row and the wrong one for a browser
152
+ * that refused — hence the override.
153
+ */
154
+ readonly unavailableReason?: string;
155
+ }
156
+ export interface DockProps {
157
+ readonly identity: DockIdentityView;
158
+ /** §9.1's `color`/`type` groups. Absent ⇒ the shipped defaults. */
159
+ readonly color?: WidgetColorConfig;
160
+ readonly type?: WidgetTypeConfig;
161
+ readonly layout?: DockLayoutView;
162
+ readonly copy?: DockCopyView;
163
+ readonly direction?: Direction;
164
+ readonly locale?: string;
165
+ readonly messages?: WidgetMessages;
166
+ readonly voice?: DockVoiceProps;
167
+ /** A PERSON holds the conversation — §5.1's `human`. */
168
+ readonly escalated?: boolean;
169
+ readonly offline?: boolean;
170
+ /** The host's status line — §5.1's `error`: a broken conversation, or a broken voice leg. */
171
+ readonly status?: string;
172
+ /**
173
+ * WHICH claimant `status` came from. See `DockStateInput.errorSource`: the
174
+ * host resolves the precedence (session > voice) into one string, and the
175
+ * string alone cannot say whether §5.1's `dock_voice_failed` applies to it.
176
+ */
177
+ readonly statusKind?: 'session' | 'voice';
178
+ /**
179
+ * A line the shopper needs to READ that is not an error — see
180
+ * `DockStateInput.notice`. It takes the caption and changes nothing else.
181
+ */
182
+ readonly notice?: string;
183
+ readonly operatorLine?: string;
184
+ readonly reconnecting?: boolean;
185
+ readonly roomDropped?: boolean;
186
+ readonly partialTranscript?: string;
187
+ readonly preamble?: string;
188
+ readonly clause?: string;
189
+ /** §3.4 — a voice session's sheet is the SHELF, a text session's is the transcript. */
190
+ readonly channel?: 'voice' | 'text';
191
+ readonly shelf?: ChatCards;
192
+ /** The text session's transcript, supplied by the caller (`voice-widget.tsx`). */
193
+ readonly transcript?: ReactNode;
194
+ /** Anything the sheet holds beside its main content: the basket, chips, the handoff marker. */
195
+ readonly sheetExtra?: ReactNode;
196
+ /** Bumped when the sheet's contents grew, so the scroll can follow a reader at the bottom. */
197
+ readonly followKey?: unknown;
198
+ /**
199
+ * The sheet holds something the shopper explicitly ASKED for: the basket
200
+ * after a basket intent, or the progress of a file they just picked.
201
+ *
202
+ * The sheet's own automatic open (§5.2) fires once per dock and only on a
203
+ * text channel, which is right for what it covers and blind to this. A
204
+ * caller who says "what's in my basket" mid-call is on the voice channel,
205
+ * which never auto-opens at all; a typed shopper who dismissed the sheet to
206
+ * look at a product has already spent the one open. Both had the basket
207
+ * rendered into a surface that stayed shut, and nothing on the row points at
208
+ * it — §5.1 has a `cards` claimant for a curation and none for the basket.
209
+ *
210
+ * The attachment's status is the same shape of problem with a shorter fuse:
211
+ * the paperclip sits on the always-visible row while "Sending rug.png…" and
212
+ * "Could not send rug.png" are drawn in the sheet, so a shopper who had
213
+ * scrolled the page since — §5.5 shuts the sheet on a scroll past 24 px, a
214
+ * tap outside the dock, or a bridge page change — picked a photo and was
215
+ * told nothing at all about where it went.
216
+ *
217
+ * Edge-triggered, on the rise: an answer the shopper asked for is shown
218
+ * once, and dismissing it keeps it dismissed until they ask again.
219
+ */
220
+ readonly revealSheet?: boolean;
221
+ /** §9.1 `cards.showPrice`. */
222
+ readonly showPrice?: boolean;
223
+ /**
224
+ * §9.1 `cards.imageAspect` — the fixed box every card thumbnail is drawn
225
+ * in, and the reason §7.1 rule 7 can promise the shelf never shifts.
226
+ *
227
+ * It is a TENANT choice because a catalogue is shot one way: a fashion
228
+ * merchant's photography is portrait and a rug merchant's is landscape, and
229
+ * cropping either to a square is the difference between a shelf that looks
230
+ * like their store and one that looks like ours.
231
+ */
232
+ readonly cardImageAspect?: WidgetImageAspect;
233
+ /** §9.1 `layout.bottomOffset`. `'auto'` runs §8.3's sticky-footer detector. */
234
+ readonly bottomOffset?: 'auto' | number;
235
+ readonly curationHref?: (curationId: string) => string;
236
+ readonly productHref?: (handle: string) => string;
237
+ readonly navigate?: (url: string) => void | Promise<void>;
238
+ readonly draft: string;
239
+ readonly onDraftChange: (value: string) => void;
240
+ readonly onSubmit: () => void;
241
+ readonly composerDisabled?: boolean;
242
+ /** Escalated-only (§5.1's `human`) — absent ⇒ no attach control is offered. */
243
+ readonly onAttach?: () => void;
244
+ /**
245
+ * An upload is already in flight, so the paperclip is not offered again.
246
+ *
247
+ * The host holds ONE slot for "what is being sent" and reports the outcome
248
+ * into it, so a second pick before the first resolves silently loses one of
249
+ * the two answers. Owned by the host rather than derived here: this dock
250
+ * draws the control, and the widget that owns the file input owns what
251
+ * uploading means.
252
+ */
253
+ readonly attachBusy?: boolean;
254
+ /** The hidden `<input type="file">` its owner renders; the dock only gives it a home. */
255
+ readonly attachSlot?: ReactNode;
256
+ /** §5.6 — a rule fired. Grows the pill into the row for 8 s, then recedes. Never opens the sheet, never plays audio. */
257
+ readonly proactive?: string;
258
+ /** §5.5 — the bridge saw the shopper move to another page. Any change closes the sheet and ducks a live reply. */
259
+ readonly pageKey?: string | number;
260
+ /**
261
+ * Leave the call — a different intention from muting it, and the reason it
262
+ * is in the SHEET's header rather than in the row: §2 caps the row at three
263
+ * controls, and mute/keyboard/interrupt are the three a caller reaches for
264
+ * mid-sentence. Hanging up is deliberate, and a deliberate action can cost
265
+ * one more tap. Absent ⇒ no hang-up is offered, which is correct for a host
266
+ * with no voice leg.
267
+ */
268
+ readonly onEndCall?: () => void;
269
+ /**
270
+ * Inline brand-token overrides for the LEGACY `--brand-*` custom properties
271
+ * the transcript's bubbles still read (`concierge.css`).
272
+ *
273
+ * The dock's own chrome is coloured entirely from `--wgt-*` (§9.2), so this
274
+ * exists only for the conversation rendered INSIDE the sheet, which was not
275
+ * restyled by this change. It is merged under the geometry, so nothing here
276
+ * can move the dock.
277
+ */
278
+ readonly skinStyle?: CSSProperties;
279
+ /**
280
+ * `[data-skin]` on the dock's root, for a host whose brand tokens are set
281
+ * by a stylesheet block rather than by `color`/`type` — the marketing
282
+ * site's theme picker, which drives the scripted preview and the real
283
+ * widget from one attribute (`apps/marketing/src/app/globals.css`).
284
+ */
285
+ readonly skin?: string;
286
+ /**
287
+ * A PREVIEW of the dock, not a session: the console's publish dialog and
288
+ * any other surface showing a merchant what their widget will look like.
289
+ *
290
+ * It changes exactly two things, both of which exist because the viewer is
291
+ * not a shopper:
292
+ *
293
+ * 1. §4.2's "the row is earned by intent" does not apply. A React dock
294
+ * mounting on a storefront means somebody reached for it, so the first
295
+ * layout effect expands the pill into the row. Nobody reached for a
296
+ * preview — it mounts because a form is open — so the resting form stays
297
+ * what `layout.minimised` says it is. Without this a console preview can
298
+ * never show the PILL, which is the shipped default and therefore the
299
+ * one thing a merchant most needs to see.
300
+ * 2. A minimise is not persisted. `wgt_dock_minimised` is a shopper's
301
+ * preference on a merchant's origin; a preview writing it would leave a
302
+ * key in whatever page is doing the previewing.
303
+ *
304
+ * Nothing else is gated on it. In particular the preview is a REAL dock —
305
+ * every state, control, gesture and token is the shipped one, which is the
306
+ * whole point of previewing with this component rather than a mock.
307
+ */
308
+ readonly preview?: boolean;
309
+ /** §11 — what a screen reader is told, replacing what the chrome conveys. */
310
+ readonly announcement?: string;
311
+ /** The small wordmark under the sheet — resolved by the caller, never by this package. */
312
+ readonly attribution?: WidgetAttribution;
313
+ /** ── §4.2's handover payload ────────────────────────────────────────── */
314
+ readonly initialDraft?: string;
315
+ readonly initialSelection?: {
316
+ start: number;
317
+ end: number;
318
+ };
319
+ readonly initialFocus?: 'composer' | 'mic' | null;
320
+ readonly initialMinimised?: boolean;
321
+ readonly insets?: {
322
+ kb: number;
323
+ hostOffset: number;
324
+ };
325
+ readonly hold?: {
326
+ downAt: number;
327
+ releasedAt?: number;
328
+ };
329
+ readonly audio?: {
330
+ context: AudioContext;
331
+ };
332
+ /**
333
+ * §4.2 step 3. Called from the FIRST layout effect, before focus is moved:
334
+ * `cdn/ui.ts` makes this container visible and `cdn/core.ts` removes its own
335
+ * row inside the same synchronous render.
336
+ */
337
+ readonly onReady?: () => void;
338
+ }
339
+ /** §5.1 — "labelled the first two times per visitor, icon after". */
340
+ export declare const INTERRUPT_LABEL_LIMIT = 2;
341
+ export declare const INTERRUPT_SEEN_STORAGE_KEY = "wgt_dock_interrupt_seen";
342
+ export declare function Dock(props: DockProps): import("react").JSX.Element;
343
+ export { DockCaption };
344
+ //# sourceMappingURL=dock.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dock.d.ts","sourceRoot":"","sources":["../../src/dock/dock.tsx"],"names":[],"mappings":"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"}
@@ -0,0 +1,161 @@
1
+ /**
2
+ * DOCK GEOMETRY — every length the dock's row, pill and sheet are built from
3
+ * (docs/DOCK_SPEC.md §3), and the CSS expressions that carry them.
4
+ *
5
+ * ONE module owns all of it, for the same reason `transcript-geometry.ts`
6
+ * owns the panel's four lengths: the dock is drawn TWICE, by two renderers
7
+ * with no shared runtime. The CDN `core` stage paints the resting row and the
8
+ * pill in plain DOM before any framework loads, writing these values as an
9
+ * inline `style` attribute; the React dock then adopts a stylesheet built
10
+ * from the same values and swaps in over one frame (§4.2). If the two ever
11
+ * disagree by a pixel, the handover — which is supposed to be invisible —
12
+ * becomes a visible jump, and nothing in the type system connects a number in
13
+ * a `.tsx` to the same number in `cdn/dock-dom.ts`. Importing both from here
14
+ * is what connects them.
15
+ *
16
+ * The functions return CSS LENGTH STRINGS rather than numbers because most of
17
+ * these lengths are not numbers at all: they involve `env(safe-area-inset-*)`,
18
+ * `dvh`, and custom properties written per-frame by the keyboard and
19
+ * sticky-footer detectors. `geometry.test.ts` evaluates the strings
20
+ * structurally instead of rendering, because jsdom has no layout engine and
21
+ * mangles a `max()` containing a subtraction — reading these back off a
22
+ * rendered element would test jsdom, not this widget.
23
+ */
24
+ /** Row height, mobile and desktop alike (§3.1). */
25
+ export declare const ROW_H = 48;
26
+ /** Pill height — the resting and receded form (§3.2). */
27
+ export declare const PILL_H = 44;
28
+ /** The session mark inside the row (§3.1). */
29
+ export declare const MARK = 32;
30
+ /** The same mark inside the pill (§3.2). */
31
+ export declare const PILL_MARK = 28;
32
+ /** Every tappable control in the row. WCAG 2.5.5 / iOS HIG floor (§11). */
33
+ export declare const CONTROL = 44;
34
+ /** The activity/waveform strip's width inside the row (§3.1). */
35
+ export declare const ACTIVITY_W = 20;
36
+ /** Mobile margin each side of the row (§3.1 — `100% - 20px`). */
37
+ export declare const MOBILE_MARGIN = 10;
38
+ /** Desktop gutter: the row's edge inset, and the pill's (§3.1, §3.2). */
39
+ export declare const DESKTOP_GUTTER = 16;
40
+ /** Minimum bottom inset on a device with no safe area (§8.1). */
41
+ export declare const BOTTOM_FLOOR = 10;
42
+ /** Desktop bottom inset (§3.1). */
43
+ export declare const DESKTOP_BOTTOM = 16;
44
+ /** Gap between the sheet's floor and the row above it (§3.3). */
45
+ export declare const SHEET_GAP = 8;
46
+ /** The one breakpoint. Below it the dock is full-width and thumb-anchored. */
47
+ export declare const DESKTOP_BREAKPOINT = 768;
48
+ /**
49
+ * §3.1. Deliberately below the 2147483647 ceiling: a merchant's own overlay
50
+ * that "goes to the top" typically uses the maximum, and the dock must lose
51
+ * to a genuine modal rather than sit on top of a cookie banner or a checkout
52
+ * dialog.
53
+ */
54
+ export declare const Z_INDEX = 2147483000;
55
+ /** §9.1 `layout.desktopWidth`. `full` is width-minus-gutters, not a number. */
56
+ export declare const DESKTOP_WIDTHS: {
57
+ readonly narrow: 480;
58
+ readonly medium: 600;
59
+ readonly wide: 800;
60
+ readonly full: null;
61
+ };
62
+ /** §9.1 `type.radius`, in px. Mirrors `theme/derive.ts`'s `--wgt-radius`. */
63
+ export declare const RADII: {
64
+ readonly square: 0;
65
+ readonly soft: 12;
66
+ readonly round: 20;
67
+ readonly pill: 9999;
68
+ };
69
+ /** The sheet's `peek` snap point: three shelf rows (§3.3). */
70
+ export declare const SHEET_PEEK_MAX = 260;
71
+ /** The `expanded` snap point, as a share of the dynamic viewport (§3.3). */
72
+ export declare const SHEET_EXPANDED_VH: {
73
+ readonly mobile: 60;
74
+ readonly desktop: 50;
75
+ };
76
+ /** Desktop `expanded` also stops at a fixed height (§3.3). */
77
+ export declare const SHEET_EXPANDED_DESKTOP_MAX = 560;
78
+ /** Below this viewport height the sheet offers `peek` only (§3.3). */
79
+ export declare const SHORT_VIEWPORT = 500;
80
+ /**
81
+ * Breathing room left above an expanded sheet (§3.3's trailing `- 24px`), so
82
+ * the sheet never reaches the top edge of the viewport and always reads as an
83
+ * overlay on the merchant's page rather than as a takeover.
84
+ */
85
+ export declare const SHEET_TOP_CLEARANCE = 24;
86
+ /**
87
+ * §5.4 — a shopper's own minimise, persisted per visitor.
88
+ *
89
+ * Lives HERE, with the lengths, rather than in either renderer, for the same
90
+ * reason every length does: `cdn/dock-dom.ts` reads it before first paint (so
91
+ * a visitor who minimised never watches the dock expand and collapse again)
92
+ * and the React dock writes it when they press "Minimise". Two copies of a
93
+ * storage key is two ways for one preference to be lost.
94
+ */
95
+ export declare const DOCK_MINIMISED_STORAGE_KEY = "wgt_dock_minimised";
96
+ /** §5.6 — how long a proactive nudge holds the row open before it recedes. */
97
+ export declare const PROACTIVE_NUDGE_MS = 8000;
98
+ export type DesktopWidth = keyof typeof DESKTOP_WIDTHS;
99
+ export type DesktopAlign = 'left' | 'center' | 'right';
100
+ export type Direction = 'ltr' | 'rtl';
101
+ /** §9.1's `layout` fields this module needs. */
102
+ export interface DockLayout {
103
+ desktopAlign: DesktopAlign;
104
+ desktopWidth: DesktopWidth;
105
+ }
106
+ /** The six custom properties the dock's CSS reads. */
107
+ export type DockGeometryVar = '--wgt-row-h' | '--wgt-pill-h' | '--wgt-bottom' | '--wgt-row-w' | '--wgt-sheet-max-h' | '--wgt-z';
108
+ /**
109
+ * The bottom inset (§3.1).
110
+ *
111
+ * Mobile stacks three things: the device's safe area with a 10 px floor (so a
112
+ * phone without a home indicator still clears the bezel), the software
113
+ * keyboard offset written per-frame from `visualViewport` (§8.2), and the
114
+ * detected host sticky-footer height or the tenant's `layout.bottomOffset`
115
+ * (§8.3). Both custom properties carry an explicit `0px` fallback: an UNSET
116
+ * `var()` inside `calc()` makes the whole declaration invalid, and `--wgt-kb`
117
+ * is unset whenever the keyboard is closed — which is nearly always.
118
+ */
119
+ export declare function bottomLen(isDesktop: boolean): string;
120
+ /**
121
+ * The row's width (§3.1): full width less a 10 px margin each side on mobile,
122
+ * one of the three fixed widths on desktop, or gutter-inset for `full`.
123
+ *
124
+ * @throws {TypeError} on an unknown width — better than emitting an empty
125
+ * string, which CSS drops silently and leaves the row at its intrinsic size.
126
+ */
127
+ export declare function rowWidthLen(isDesktop: boolean, desktopWidth: DesktopWidth): string;
128
+ /**
129
+ * The sheet's `expanded` ceiling (§3.3).
130
+ *
131
+ * `dvh`, never `vh`: `vh` resolves against mobile Safari's LARGE viewport, so
132
+ * a sheet sized in `vh` runs underneath the browser's collapsing toolbar and
133
+ * its last row cannot be reached. The mobile arm also subtracts the row and
134
+ * the gap above it, because the row is the sheet's floor and must never be
135
+ * covered by it.
136
+ */
137
+ export declare function sheetMaxHeightLen(isDesktop: boolean): string;
138
+ /**
139
+ * Every geometry custom property, for one viewport class and one layout.
140
+ *
141
+ * This is the object `core` serialises into the shadow host's inline `style`
142
+ * attribute and the React dock writes onto the same host — the single reason
143
+ * the handover does not move anything.
144
+ */
145
+ export declare function geometryVars(isDesktop: boolean, layout: DockLayout): Record<DockGeometryVar, string>;
146
+ /**
147
+ * Which edge the pill hangs off, and how far in (§3.2).
148
+ *
149
+ * On mobile this is the THUMB edge, so it mirrors with the reading direction
150
+ * (§8.9). On desktop it follows `layout.desktopAlign`, which is a physical
151
+ * choice the tenant made about their own page and is therefore NOT mirrored;
152
+ * `center` resolves to the right edge, since a centred pill has no edge to
153
+ * hang off.
154
+ *
155
+ * @throws {TypeError} on an unknown alignment.
156
+ */
157
+ export declare function pillAnchor(dir: Direction, isDesktop: boolean, desktopAlign: DesktopAlign): {
158
+ side: 'left' | 'right';
159
+ inset: number;
160
+ };
161
+ //# sourceMappingURL=geometry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"geometry.d.ts","sourceRoot":"","sources":["../../src/dock/geometry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,mDAAmD;AACnD,eAAO,MAAM,KAAK,KAAK,CAAC;AACxB,yDAAyD;AACzD,eAAO,MAAM,MAAM,KAAK,CAAC;AACzB,8CAA8C;AAC9C,eAAO,MAAM,IAAI,KAAK,CAAC;AACvB,4CAA4C;AAC5C,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,2EAA2E;AAC3E,eAAO,MAAM,OAAO,KAAK,CAAC;AAC1B,iEAAiE;AACjE,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,iEAAiE;AACjE,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,yEAAyE;AACzE,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,iEAAiE;AACjE,eAAO,MAAM,YAAY,KAAK,CAAC;AAC/B,mCAAmC;AACnC,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,iEAAiE;AACjE,eAAO,MAAM,SAAS,IAAI,CAAC;AAC3B,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,aAAa,CAAC;AAClC,+EAA+E;AAC/E,eAAO,MAAM,cAAc;aACzB,MAAM,EAAE,GAAG;aACX,MAAM,EAAE,GAAG;aACX,IAAI,EAAE,GAAG;aACT,IAAI;CACI,CAAC;AACX,6EAA6E;AAC7E,eAAO,MAAM,KAAK;aAAK,MAAM,EAAE,CAAC;aAAE,IAAI,EAAE,EAAE;aAAE,KAAK,EAAE,EAAE;aAAE,IAAI,EAAE,IAAI;CAAW,CAAC;AAC7E,8DAA8D;AAC9D,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB;aAAK,MAAM,EAAE,EAAE;aAAE,OAAO,EAAE,EAAE;CAAW,CAAC;AACtE,8DAA8D;AAC9D,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAC9C,sEAAsE;AACtE,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,uBAAuB,CAAC;AAE/D,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,cAAc,CAAC;AACvD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AACvD,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;AAEtC,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,sDAAsD;AACtD,MAAM,MAAM,eAAe,GACzB,aAAa,GAAG,cAAc,GAAG,cAAc,GAAG,aAAa,GAAG,mBAAmB,GAAG,SAAS,CAAC;AAEpG;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAMpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAOlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAQ5D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,UAAU,GACjB,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CASjC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,OAAO,EAClB,YAAY,EAAE,YAAY,GACzB;IAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAQ3C"}
@@ -0,0 +1,123 @@
1
+ /**
2
+ * TRANSITIONS THAT FINALISE WITHOUT `transitionend` — docs/DOCK_SPEC.md §7.1
3
+ * rule 12.
4
+ *
5
+ * ## The defect this module exists for
6
+ *
7
+ * Observed on production (widget 0.6.0, a tenant's demo storefront): a
8
+ * shopper taps the pill, the pill → row swap starts, and the shopper switches
9
+ * apps or locks the screen a frame later. The tab becomes
10
+ * `document.visibilityState === 'hidden'`, and a hidden tab does not advance
11
+ * CSS transitions — so `transitionend` never fires, and every piece of
12
+ * bookkeeping gated on it never runs. The dock was found frozen mid-swap:
13
+ * `.wgt-row` at `transform: matrix(0.339, 0, 0, 0.935, …)`, `opacity: 0.6`,
14
+ * `visibility: hidden`, and `.wgt-pill` `visibility: hidden` too. Nothing was
15
+ * visible, and nothing was tappable, until the tab was rendered again.
16
+ *
17
+ * `visibility` is what turns a stalled animation into a dead widget. It rides
18
+ * in the dock's transition lists on purpose (see `styles/concierge.css` and
19
+ * "The two paint properties the motion guard allows" in
20
+ * `packages/web-widget/AGENTS.md`), and a transition frozen between its two
21
+ * ends can leave BOTH forms hidden. Browsers usually complete a transition
22
+ * when the tab comes back; "usually" is not a guarantee a storefront can be
23
+ * shipped on, and the core dock (plain DOM, `cdn/dock-dom.ts`) carries the
24
+ * same hazard.
25
+ *
26
+ * ## The three rules, and why each one is needed on its own
27
+ *
28
+ * 1. **A fallback timer.** Every transition-gated finalisation also runs from
29
+ * a `setTimeout` of `duration + {@link TRANSITION_FALLBACK_MS}`. Whichever
30
+ * of `transitionend` and the timer arrives first wins; the other is a
31
+ * no-op. A timer in a throttled tab is late, not absent, which is exactly
32
+ * the difference that matters.
33
+ * 2. **Do not start what cannot run.** A transition that would START while
34
+ * the tab is hidden (or under `prefers-reduced-motion`) is skipped and its
35
+ * end state applied synchronously. §7.1 rule 10 already collapses every
36
+ * duration to 0 for reduced motion; a hidden tab takes the same road.
37
+ * 3. **Finalise on `visibilitychange`.** Belt and braces for a browser that
38
+ * neither advances the transition while hidden nor completes it on
39
+ * resume — the finaliser runs the moment the visibility flips, before the
40
+ * shopper has looked at the result.
41
+ *
42
+ * ## The end state is WRITTEN, never inferred from the transition
43
+ *
44
+ * {@link finaliseTransition} writes `visibility`, `transform`, `opacity` (and
45
+ * the sheet's `clip-path`) as inline properties, behind a one-frame
46
+ * `transition: none`, and then takes the override back off. The `none` is
47
+ * what CANCELS a transition the engine has frozen mid-flight — dropping a
48
+ * property out of `transition-property` ends its running transition — and
49
+ * removing the inline values a frame later hands the element back to the
50
+ * cascade, so the NEXT swap animates normally. Writing the value without the
51
+ * `none` would leave the frozen interpolation running on top of it, which is
52
+ * the bug rather than the fix.
53
+ *
54
+ * Nothing here imports React, and nothing here is React-shaped: `core` is
55
+ * downloaded by every visitor to every merchant page and cannot afford a
56
+ * framework, and both renderers have to agree about when motion is off.
57
+ */
58
+ /**
59
+ * How long after a transition's stated duration its fallback finaliser fires.
60
+ *
61
+ * Long enough that a transition which is merely LATE — a loaded main thread,
62
+ * a throttled timer queue — still gets to end itself and fire the event,
63
+ * short enough that a shopper returning to a stalled dock does not wait for
64
+ * it. The finaliser is idempotent, so the cost of firing it after a
65
+ * transition that already ended is one no-op call.
66
+ */
67
+ export declare const TRANSITION_FALLBACK_MS = 100;
68
+ /**
69
+ * "The browser is not painting this document."
70
+ *
71
+ * An absent `document` (SSR, a worker) is NOT hidden: the caller is asking
72
+ * whether to skip an animation, and there is no animation to skip. Tolerant
73
+ * of a partial `document` stub, which is what an embedded webview can hand a
74
+ * widget that has no say in where it is loaded.
75
+ */
76
+ export declare function isDocumentHidden(doc?: Document | null): boolean;
77
+ /**
78
+ * The inline properties a finaliser writes, as CSS property names — so
79
+ * `clip-path`, not `clipPath`. Written through `style.setProperty`, which
80
+ * takes the CSS spelling and also accepts custom properties.
81
+ */
82
+ export type MotionEndState = Readonly<Record<string, string>>;
83
+ export interface TransitionFinaliser {
84
+ /**
85
+ * Run the finalisation now, if it has not run already. Idempotent: the
86
+ * first of `transitionend`, the fallback timer, a `visibilitychange` and an
87
+ * explicit call wins, and every later one is a no-op.
88
+ */
89
+ finish(): void;
90
+ /**
91
+ * Stop waiting WITHOUT finalising — an unmount, or a swap that supersedes
92
+ * this one. Any inline override still outstanding is released synchronously
93
+ * so nothing is left pinned on an element this finaliser no longer owns.
94
+ */
95
+ cancel(): void;
96
+ /** `true` once `finish()` or `cancel()` has run. */
97
+ readonly settled: boolean;
98
+ }
99
+ export interface FinaliseTransitionOptions {
100
+ /** The element whose OWN transition this is. A descendant's is ignored. */
101
+ readonly el: HTMLElement;
102
+ /** The transition's stated duration. `0` (reduced motion) finalises at once. */
103
+ readonly durationMs: number;
104
+ /** What the element must look like when the transition is over. */
105
+ readonly endState?: MotionEndState;
106
+ /** Surface-specific work: clearing `will-change`, finishing a WAAPI animation. */
107
+ readonly onFinalise?: () => void;
108
+ /** Defaults to the element's own document. */
109
+ readonly doc?: Document | null;
110
+ /** Skip the wait outright — the caller already knows the animation cannot run. */
111
+ readonly immediate?: boolean;
112
+ }
113
+ /**
114
+ * Guarantees that one transition's end state lands, whether or not the
115
+ * browser ever fires `transitionend` for it.
116
+ *
117
+ * @returns a handle whose `finish()`/`cancel()` are both idempotent. Callers
118
+ * that can be superseded (a swap interrupting a swap) `cancel()` the previous
119
+ * handle before opening a new one; callers that unmount `cancel()` in their
120
+ * effect cleanup.
121
+ */
122
+ export declare function finaliseTransition(options: FinaliseTransitionOptions): TransitionFinaliser;
123
+ //# sourceMappingURL=motion-gate.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"motion-gate.d.ts","sourceRoot":"","sources":["../../src/dock/motion-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAG/D;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,IAAI,IAAI,CAAC;IACf;;;;OAIG;IACH,MAAM,IAAI,IAAI,CAAC;IACf,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,mBAAmB,CA4G1F"}
@@ -1 +1 @@
1
- {"version":3,"file":"widget-css.d.ts","sourceRoot":"","sources":["../../src/generated/widget-css.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,EAAE,MAA6rqE,CAAC"}
1
+ {"version":3,"file":"widget-css.d.ts","sourceRoot":"","sources":["../../src/generated/widget-css.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,EAAE,MAA285D,CAAC"}