@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
|
@@ -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":"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"}
|
|
@@ -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,
|
|
1
|
+
{"version":3,"file":"widget-css.d.ts","sourceRoot":"","sources":["../../src/generated/widget-css.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,EAAE,MAA285D,CAAC"}
|