@whity/ui 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (205) hide show
  1. package/README.md +106 -2
  2. package/package.json +219 -4
  3. package/src/access-denied.stories.tsx +179 -0
  4. package/src/access-denied.tsx +305 -0
  5. package/src/action-proposal.tsx +338 -0
  6. package/src/actor-chip.tsx +71 -0
  7. package/src/agent-activity.tsx +163 -0
  8. package/src/agent-collaboration.stories.tsx +156 -0
  9. package/src/agent-run-status.tsx +196 -0
  10. package/src/alert-dialog.stories.tsx +45 -0
  11. package/src/alert-dialog.tsx +147 -0
  12. package/src/alert.stories.tsx +91 -0
  13. package/src/alert.tsx +89 -0
  14. package/src/app-sidebar.stories.tsx +195 -0
  15. package/src/app-sidebar.tsx +604 -0
  16. package/src/approval-queue.tsx +109 -0
  17. package/src/audience-group-picker.stories.tsx +198 -0
  18. package/src/audience-group-picker.tsx +362 -0
  19. package/src/audience-people-picker.stories.tsx +102 -0
  20. package/src/audience-people-picker.tsx +279 -0
  21. package/src/avatar-pattern.ts +138 -0
  22. package/src/avatar.tsx +125 -0
  23. package/src/badge.stories.tsx +105 -0
  24. package/src/badge.tsx +68 -0
  25. package/src/beta-warning.stories.tsx +79 -0
  26. package/src/beta-warning.tsx +189 -0
  27. package/src/bilingual-input.stories.tsx +82 -0
  28. package/src/bilingual-input.tsx +188 -0
  29. package/src/board.tsx +216 -0
  30. package/src/breadcrumb.stories.tsx +51 -0
  31. package/src/breadcrumb.tsx +90 -0
  32. package/src/built-on-whity.tsx +52 -0
  33. package/src/button.stories.tsx +87 -0
  34. package/src/button.tsx +123 -0
  35. package/src/card.stories.tsx +423 -0
  36. package/src/card.tsx +180 -0
  37. package/src/chart.stories.tsx +66 -0
  38. package/src/chart.tsx +228 -0
  39. package/src/checkbox.stories.tsx +62 -0
  40. package/src/checkbox.tsx +54 -0
  41. package/src/collapsible.stories.tsx +48 -0
  42. package/src/collapsible.tsx +34 -0
  43. package/src/color-card.stories.tsx +61 -0
  44. package/src/color-card.tsx +270 -0
  45. package/src/color-picker.stories.tsx +65 -0
  46. package/src/color-picker.tsx +425 -0
  47. package/src/column-matcher.tsx +84 -0
  48. package/src/command-palette.tsx +398 -0
  49. package/src/confirm-action.tsx +98 -0
  50. package/src/copy-block.stories.tsx +38 -0
  51. package/src/copy-block.tsx +85 -0
  52. package/src/data-table.stories.tsx +200 -0
  53. package/src/data-table.tsx +1686 -0
  54. package/src/date-picker.stories.tsx +61 -0
  55. package/src/date-picker.tsx +456 -0
  56. package/src/design-cards.stories.tsx +551 -0
  57. package/src/dialog.stories.tsx +48 -0
  58. package/src/dialog.tsx +179 -0
  59. package/src/display-preferences.tsx +50 -0
  60. package/src/documents/barcode-svg.stories.tsx +72 -0
  61. package/src/documents/barcode-svg.tsx +79 -0
  62. package/src/dropdown-menu.stories.tsx +77 -0
  63. package/src/dropdown-menu.tsx +271 -0
  64. package/src/editor/agent-panel.tsx +222 -0
  65. package/src/editor/agents.stories.tsx +81 -0
  66. package/src/editor/agents.ts +55 -0
  67. package/src/editor/behaviour.ts +279 -0
  68. package/src/editor/block-ids.ts +44 -0
  69. package/src/editor/block-list.tsx +104 -0
  70. package/src/editor/block-toolbar.tsx +490 -0
  71. package/src/editor/bubble.tsx +119 -0
  72. package/src/editor/catalogue.ts +169 -0
  73. package/src/editor/collab-rail.tsx +746 -0
  74. package/src/editor/collab.stories.tsx +207 -0
  75. package/src/editor/collab.ts +87 -0
  76. package/src/editor/contract.ts +476 -0
  77. package/src/editor/convert.ts +414 -0
  78. package/src/editor/doc-editor.stories.tsx +98 -0
  79. package/src/editor/doc-editor.tsx +1492 -0
  80. package/src/editor/editor.css +636 -0
  81. package/src/editor/extensions.ts +86 -0
  82. package/src/editor/field-bar.tsx +154 -0
  83. package/src/editor/field-picker.tsx +109 -0
  84. package/src/editor/fields.ts +100 -0
  85. package/src/editor/gutter.tsx +443 -0
  86. package/src/editor/index.ts +23 -0
  87. package/src/editor/label-sheet.tsx +289 -0
  88. package/src/editor/labels.ts +394 -0
  89. package/src/editor/link-tools.tsx +141 -0
  90. package/src/editor/node-views.tsx +461 -0
  91. package/src/editor/page-view.tsx +372 -0
  92. package/src/editor/phone.tsx +310 -0
  93. package/src/editor/plugin-block-view.tsx +230 -0
  94. package/src/editor/plugin-blocks.stories.tsx +96 -0
  95. package/src/editor/plugin-blocks.ts +52 -0
  96. package/src/editor/publish-check.tsx +201 -0
  97. package/src/editor/rich-blocks.stories.tsx +146 -0
  98. package/src/editor/sample.ts +40 -0
  99. package/src/editor/save-block-dialog.tsx +141 -0
  100. package/src/editor/saved-block-view.tsx +205 -0
  101. package/src/editor/saved-blocks.stories.tsx +105 -0
  102. package/src/editor/saved-parts.ts +192 -0
  103. package/src/editor/schema-rich.ts +156 -0
  104. package/src/editor/schema.ts +368 -0
  105. package/src/editor/services.tsx +205 -0
  106. package/src/editor/slash.ts +64 -0
  107. package/src/editor/suggesting.ts +372 -0
  108. package/src/editor/suggestions.ts +763 -0
  109. package/src/editor/table-keys.ts +66 -0
  110. package/src/editor/templates.stories.tsx +324 -0
  111. package/src/editor/toolbar.tsx +364 -0
  112. package/src/empty-state.stories.tsx +51 -0
  113. package/src/empty-state.tsx +126 -0
  114. package/src/empty-state.usage-notes.md +30 -0
  115. package/src/form.stories.tsx +112 -0
  116. package/src/form.tsx +176 -0
  117. package/src/globals.css +20 -0
  118. package/src/icon-button.tsx +85 -0
  119. package/src/icon-map.ts +335 -0
  120. package/src/icon.tsx +41 -0
  121. package/src/index.ts +90 -0
  122. package/src/input.stories.tsx +157 -0
  123. package/src/input.tsx +768 -0
  124. package/src/kpi-strip.tsx +47 -0
  125. package/src/localized-text.ts +76 -0
  126. package/src/locked-screen.stories.tsx +29 -0
  127. package/src/locked-screen.tsx +75 -0
  128. package/src/lockup.tsx +42 -0
  129. package/src/lottie.tsx +441 -0
  130. package/src/mark.tsx +62 -0
  131. package/src/math-text.stories.tsx +33 -0
  132. package/src/math-text.tsx +43 -0
  133. package/src/menu-bar.stories.tsx +198 -0
  134. package/src/menu-bar.tsx +373 -0
  135. package/src/message-thread.tsx +181 -0
  136. package/src/money/currency.ts +244 -0
  137. package/src/money/money-input.tsx +131 -0
  138. package/src/money/money.tsx +33 -0
  139. package/src/open-on-computer.tsx +150 -0
  140. package/src/otp-input.tsx +161 -0
  141. package/src/page-header.stories.tsx +95 -0
  142. package/src/page-header.tsx +122 -0
  143. package/src/page-shell.stories.tsx +42 -0
  144. package/src/page-shell.tsx +32 -0
  145. package/src/page-states.tsx +277 -0
  146. package/src/pagination.stories.tsx +45 -0
  147. package/src/pagination.tsx +98 -0
  148. package/src/paper-sheet.stories.tsx +88 -0
  149. package/src/paper-sheet.tsx +85 -0
  150. package/src/phone-tab-bar.tsx +152 -0
  151. package/src/plugin-card.stories.tsx +208 -0
  152. package/src/plugin-card.tsx +931 -0
  153. package/src/popover.stories.tsx +48 -0
  154. package/src/popover.tsx +55 -0
  155. package/src/radio-group.stories.tsx +26 -0
  156. package/src/radio-group.tsx +44 -0
  157. package/src/route-flow/editor.tsx +1087 -0
  158. package/src/route-flow/model.ts +771 -0
  159. package/src/save-bar.tsx +94 -0
  160. package/src/scope-grant.tsx +139 -0
  161. package/src/screen-too-small.stories.tsx +61 -0
  162. package/src/screen-too-small.tsx +104 -0
  163. package/src/search-field.tsx +65 -0
  164. package/src/select.stories.tsx +44 -0
  165. package/src/select.tsx +197 -0
  166. package/src/separator.stories.tsx +34 -0
  167. package/src/separator.tsx +34 -0
  168. package/src/sheet.stories.tsx +49 -0
  169. package/src/sheet.tsx +168 -0
  170. package/src/skeleton.stories.tsx +28 -0
  171. package/src/skeleton.tsx +19 -0
  172. package/src/slider.stories.tsx +78 -0
  173. package/src/slider.tsx +300 -0
  174. package/src/spinner.stories.tsx +33 -0
  175. package/src/spinner.tsx +55 -0
  176. package/src/stepper.tsx +85 -0
  177. package/src/switch.stories.tsx +42 -0
  178. package/src/switch.tsx +41 -0
  179. package/src/switcher.stories.tsx +111 -0
  180. package/src/switcher.tsx +131 -0
  181. package/src/system-state.tsx +55 -0
  182. package/src/table.stories.tsx +48 -0
  183. package/src/table.tsx +121 -0
  184. package/src/tabs.stories.tsx +74 -0
  185. package/src/tabs.tsx +90 -0
  186. package/src/tag-input.stories.tsx +67 -0
  187. package/src/tag-input.tsx +117 -0
  188. package/src/tenant-logo.tsx +63 -0
  189. package/src/tenant-switcher.stories.tsx +38 -0
  190. package/src/tenant-switcher.tsx +164 -0
  191. package/src/textarea.stories.tsx +27 -0
  192. package/src/textarea.tsx +18 -0
  193. package/src/theme-mode.ts +52 -0
  194. package/src/time-grid.tsx +163 -0
  195. package/src/time-picker.stories.tsx +62 -0
  196. package/src/time-picker.tsx +615 -0
  197. package/src/toggle-group.tsx +138 -0
  198. package/src/tooltip.stories.tsx +43 -0
  199. package/src/tooltip.tsx +73 -0
  200. package/src/top-nav.stories.tsx +58 -0
  201. package/src/top-nav.tsx +324 -0
  202. package/src/undo-bar.tsx +107 -0
  203. package/src/utils.ts +45 -0
  204. package/src/view-toggle.stories.tsx +84 -0
  205. package/src/view-toggle.tsx +110 -0
package/src/lottie.tsx ADDED
@@ -0,0 +1,441 @@
1
+ "use client"
2
+
3
+ import * as React from "react"
4
+
5
+ import { cn } from "./utils"
6
+
7
+ /**
8
+ * The motion player (LT.1-LT.4, docs/design/06-motion.md, handoff/motion/README.md),
9
+ * a React port of `handoff/motion/whity-lottie.js`.
10
+ *
11
+ * - The 31 files and lottie-web's light build are served from `/motion/` and
12
+ * fetched only when a scene is first shown, so a screen without motion
13
+ * downloads nothing.
14
+ * - Every fill and stroke named `c:<token>` takes the live CSS token, so a scene
15
+ * follows dark mode and the workspace's colour. The player rebuilds, keeping
16
+ * its frame, when the theme changes.
17
+ * - `<html data-motion="full|calm|off">` is the person's Animations setting.
18
+ * Calm and Off show the last frame (Calm fades it in); the device's reduce
19
+ * motion means Off. Loops hold still.
20
+ * - A scene never carries the meaning alone and never holds a button: it is
21
+ * `aria-hidden`, and the words around it say what happened.
22
+ */
23
+
24
+ export type MomentName =
25
+ | "agents-propose"
26
+ | "all-caught-up"
27
+ | "approve-set-down"
28
+ | "brand-sheet-platform"
29
+ | "documents-sign"
30
+ | "empty-documents"
31
+ | "empty-invoices"
32
+ | "empty-people"
33
+ | "empty-stock"
34
+ | "invoice-sent"
35
+ | "money-invoice"
36
+ | "no-results"
37
+ | "not-found"
38
+ | "offline"
39
+ | "payment-received"
40
+ | "security-lock"
41
+ | "setup-done"
42
+ | "spot-cliq"
43
+ | "spot-code"
44
+ | "spot-jod"
45
+ | "spot-jofotara"
46
+ | "spot-languages"
47
+ | "spot-mcp"
48
+ | "spot-plugin"
49
+ | "spot-whatsapp"
50
+ | "stock-batches"
51
+ | "stock-received"
52
+ | "updating"
53
+ | "uploading"
54
+ | "waiting-reply"
55
+ | "went-wrong"
56
+
57
+ /** The Animations setting (LT.4). */
58
+ export type MotionMode = "full" | "calm" | "off"
59
+
60
+ export const MOTION_MODES: readonly MotionMode[] = ["full", "calm", "off"]
61
+
62
+ /** Where the files and the player library are served from. */
63
+ const MotionBaseContext = React.createContext("/motion")
64
+
65
+ /** Serve the motion files from somewhere other than `/motion` (a plugin, Storybook). */
66
+ export function MotionBaseProvider({ base, children }: { base: string; children: React.ReactNode }) {
67
+ return <MotionBaseContext.Provider value={base.replace(/\/$/, "")}>{children}</MotionBaseContext.Provider>
68
+ }
69
+
70
+ interface LottieAnimation {
71
+ totalFrames: number
72
+ currentFrame: number
73
+ loop: boolean | number
74
+ play(): void
75
+ destroy(): void
76
+ goToAndStop(value: number, isFrame?: boolean): void
77
+ goToAndPlay(value: number, isFrame?: boolean): void
78
+ setDirection(direction: 1 | -1): void
79
+ addEventListener(name: string, callback: () => void): void
80
+ }
81
+
82
+ interface LottieLibrary {
83
+ loadAnimation(options: {
84
+ container: Element
85
+ renderer: "svg"
86
+ loop: boolean
87
+ autoplay: boolean
88
+ animationData: unknown
89
+ rendererSettings?: { preserveAspectRatio?: string }
90
+ }): LottieAnimation
91
+ }
92
+
93
+ declare global {
94
+ interface Window {
95
+ lottie?: LottieLibrary
96
+ }
97
+ }
98
+
99
+ // Fill and stroke names in the files, and the tokens they take.
100
+ const TOKENS: Record<string, string> = {
101
+ primary: "--primary",
102
+ plane: "--plane-deep",
103
+ card: "--card",
104
+ line: "--border",
105
+ muted: "--muted",
106
+ ink: "--foreground",
107
+ soft: "--muted-foreground",
108
+ ok: "--success",
109
+ tint: "--primary-tint",
110
+ tenant: "--tenant-color",
111
+ onprimary: "--primary-foreground",
112
+ }
113
+
114
+ let libraryPromise: Promise<LottieLibrary | null> | null = null
115
+
116
+ function loadLibrary(base: string): Promise<LottieLibrary | null> {
117
+ if (typeof window === "undefined") return Promise.resolve(null)
118
+ if (window.lottie) return Promise.resolve(window.lottie)
119
+ if (!libraryPromise) {
120
+ libraryPromise = new Promise((resolve) => {
121
+ const script = document.createElement("script")
122
+ script.src = `${base}/lottie_light.min.js`
123
+ script.async = true
124
+ script.onload = () => resolve(window.lottie ?? null)
125
+ script.onerror = () => {
126
+ libraryPromise = null
127
+ resolve(null)
128
+ }
129
+ document.head.appendChild(script)
130
+ })
131
+ }
132
+ return libraryPromise
133
+ }
134
+
135
+ const dataCache = new Map<string, Promise<unknown>>()
136
+
137
+ function loadData(src: string): Promise<unknown> {
138
+ if (typeof fetch === "undefined") return Promise.reject(new Error("no fetch"))
139
+ let pending = dataCache.get(src)
140
+ if (!pending) {
141
+ pending = fetch(src).then((response) => {
142
+ if (!response.ok) throw new Error(String(response.status))
143
+ return response.json()
144
+ })
145
+ pending.catch(() => dataCache.delete(src))
146
+ dataCache.set(src, pending)
147
+ }
148
+ return pending
149
+ }
150
+
151
+ let canvasContext: CanvasRenderingContext2D | null = null
152
+
153
+ /** Any CSS colour (oklch included) as Lottie's 0-1 RGBA, through a 1px canvas. */
154
+ function toLottieColour(value: string): number[] | null {
155
+ try {
156
+ if (!canvasContext) {
157
+ const canvas = document.createElement("canvas")
158
+ canvas.width = canvas.height = 1
159
+ canvasContext = canvas.getContext("2d", { willReadFrequently: true })
160
+ }
161
+ if (!canvasContext) return null
162
+ canvasContext.clearRect(0, 0, 1, 1)
163
+ canvasContext.fillStyle = "#000"
164
+ canvasContext.fillStyle = value.trim()
165
+ canvasContext.fillRect(0, 0, 1, 1)
166
+ const [r, g, b] = canvasContext.getImageData(0, 0, 1, 1).data
167
+ return [r / 255, g / 255, b / 255, 1]
168
+ } catch {
169
+ return null
170
+ }
171
+ }
172
+
173
+ function recolour(raw: unknown, element: Element): unknown {
174
+ const data = JSON.parse(JSON.stringify(raw)) as unknown
175
+ const style = getComputedStyle(element)
176
+ const colours: Record<string, number[] | null> = {}
177
+ for (const [name, token] of Object.entries(TOKENS)) {
178
+ const value = style.getPropertyValue(token)
179
+ if (value && value.trim()) colours[name] = toLottieColour(value)
180
+ }
181
+ const walk = (node: unknown): void => {
182
+ if (Array.isArray(node)) {
183
+ node.forEach(walk)
184
+ return
185
+ }
186
+ if (!node || typeof node !== "object") return
187
+ const shape = node as { ty?: string; nm?: unknown; c?: { a?: number; k?: unknown } }
188
+ if ((shape.ty === "fl" || shape.ty === "st") && typeof shape.nm === "string" && shape.nm.startsWith("c:")) {
189
+ const colour = colours[shape.nm.slice(2)]
190
+ if (colour && shape.c && shape.c.a === 0) shape.c.k = colour
191
+ }
192
+ for (const value of Object.values(node)) if (value && typeof value === "object") walk(value)
193
+ }
194
+ walk(data)
195
+ return data
196
+ }
197
+
198
+ function readMotionMode(): MotionMode {
199
+ if (typeof window === "undefined") return "full"
200
+ if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return "off"
201
+ const mode = document.documentElement.dataset.motion
202
+ return mode === "calm" || mode === "off" ? mode : "full"
203
+ }
204
+
205
+ function subscribeToMotion(callback: () => void): () => void {
206
+ const observer = new MutationObserver(callback)
207
+ observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-motion"] })
208
+ const query = window.matchMedia?.("(prefers-reduced-motion: reduce)")
209
+ query?.addEventListener?.("change", callback)
210
+ return () => {
211
+ observer.disconnect()
212
+ query?.removeEventListener?.("change", callback)
213
+ }
214
+ }
215
+
216
+ /** The motion the person gets: their Animations setting, or Off when the device asks for less motion. */
217
+ export function useMotionMode(): MotionMode {
218
+ return React.useSyncExternalStore(subscribeToMotion, readMotionMode, () => "full")
219
+ }
220
+
221
+ // Theme changes (light, dark, a workspace colour) rebuild the scene with the new colours.
222
+ function readTheme(): string {
223
+ const root = document.documentElement
224
+ return `${root.className}|${root.dataset.theme ?? ""}|${root.getAttribute("style") ?? ""}`
225
+ }
226
+
227
+ function subscribeToTheme(callback: () => void): () => void {
228
+ const observer = new MutationObserver(callback)
229
+ observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "data-theme", "style"] })
230
+ const query = window.matchMedia?.("(prefers-color-scheme: dark)")
231
+ query?.addEventListener?.("change", callback)
232
+ return () => {
233
+ observer.disconnect()
234
+ query?.removeEventListener?.("change", callback)
235
+ }
236
+ }
237
+
238
+ function seenBefore(key: string | undefined, ever: string | undefined): boolean {
239
+ try {
240
+ if (ever && localStorage.getItem(`whity.onceEver.${ever}`) === "1") return true
241
+ return !!key && sessionStorage.getItem(`whity.once.${key}`) === "1"
242
+ } catch {
243
+ return false
244
+ }
245
+ }
246
+
247
+ function markSeen(key: string | undefined, ever: string | undefined): void {
248
+ try {
249
+ if (ever) localStorage.setItem(`whity.onceEver.${ever}`, "1")
250
+ if (key) sessionStorage.setItem(`whity.once.${key}`, "1")
251
+ } catch {
252
+ // A private window can refuse storage; the scene then plays again next time.
253
+ }
254
+ }
255
+
256
+ /** Whether a first-run scene (`onceEver`) has already played on this device. */
257
+ export function hasPlayedOnceEver(key: string): boolean {
258
+ return seenBefore(undefined, key)
259
+ }
260
+
261
+ /** Record a first-run scene as played without showing it. */
262
+ export function markPlayedOnceEver(key: string): void {
263
+ markSeen(undefined, key)
264
+ }
265
+
266
+ export interface LottieProps {
267
+ name: MomentName
268
+ /** A file elsewhere; defaults to `<base>/<name>.json`. */
269
+ src?: string
270
+ /**
271
+ * `view` plays once when seen (a click replays it); `manual` follows
272
+ * `approved` forwards and backwards; `loop` plays only while `active`.
273
+ */
274
+ play?: "view" | "manual" | "loop"
275
+ /** Play once a session under this key, then show the last frame (empty states). */
276
+ once?: string
277
+ /** Play once ever on this device under this key (first-run scenes), then show the last frame. */
278
+ onceEver?: string
279
+ /** `manual` only: the approved end (forwards) or the waiting start (backwards). */
280
+ approved?: boolean
281
+ /** `loop` only: false when the waiting is over; the scene stops on its last frame. */
282
+ active?: boolean
283
+ /** Milliseconds to wait after the scene is seen. */
284
+ delay?: number
285
+ /** Shown until the scene is ready, and kept if the player can't load. */
286
+ fallback?: React.ReactNode
287
+ className?: string
288
+ }
289
+
290
+ function Lottie({
291
+ name,
292
+ src,
293
+ play = "view",
294
+ once,
295
+ onceEver,
296
+ approved = false,
297
+ active = true,
298
+ delay = 0,
299
+ fallback,
300
+ className,
301
+ }: LottieProps) {
302
+ const base = React.useContext(MotionBaseContext)
303
+ const file = src ?? `${base}/${name}.json`
304
+ const mode = useMotionMode()
305
+ const theme = React.useSyncExternalStore(subscribeToTheme, readTheme, () => "")
306
+ const hostRef = React.useRef<HTMLDivElement>(null)
307
+ const stageRef = React.useRef<HTMLDivElement>(null)
308
+ const animRef = React.useRef<LottieAnimation | null>(null)
309
+ const playedRef = React.useRef(false)
310
+ const [ready, setReady] = React.useState(false)
311
+
312
+ // Read inside the build without rebuilding when they change.
313
+ const live = React.useRef({ approved, active, mode, delay, once, onceEver })
314
+ live.current = { approved, active, mode, delay, once, onceEver }
315
+
316
+ React.useEffect(() => {
317
+ const host = hostRef.current
318
+ const stage = stageRef.current
319
+ if (!host || !stage) return
320
+ let cancelled = false
321
+ let observer: IntersectionObserver | null = null
322
+ let timer: ReturnType<typeof setTimeout> | undefined
323
+ const keepFrame = animRef.current ? Math.round(animRef.current.currentFrame) : null
324
+
325
+ // The library first: without it (no script, a test runner) nothing is fetched.
326
+ void loadLibrary(base)
327
+ .then((library) => (library && !cancelled ? Promise.all([library, loadData(file)] as const) : null))
328
+ .then((loaded) => {
329
+ if (cancelled || !loaded) return
330
+ const [library, raw] = loaded
331
+ animRef.current?.destroy()
332
+ stage.textContent = ""
333
+ const anim = library.loadAnimation({
334
+ container: stage,
335
+ renderer: "svg",
336
+ loop: play === "loop",
337
+ autoplay: false,
338
+ animationData: recolour(raw, host),
339
+ rendererSettings: { preserveAspectRatio: "xMidYMid meet" },
340
+ })
341
+ animRef.current = anim
342
+ anim.addEventListener("DOMLoaded", () => {
343
+ if (cancelled) return
344
+ setReady(true)
345
+ const last = anim.totalFrames - 1
346
+ const { approved: isApproved, active: isActive, mode: motion, delay: wait, once: key, onceEver: ever } = live.current
347
+ if (play === "manual") {
348
+ anim.goToAndStop(keepFrame != null && keepFrame > 0 ? keepFrame : isApproved ? last : 0, true)
349
+ } else if (play === "loop") {
350
+ if (!isActive) anim.goToAndStop(last, true)
351
+ else if (motion !== "full") anim.goToAndStop(0, true)
352
+ else anim.play()
353
+ } else if (playedRef.current || motion !== "full" || seenBefore(key, ever)) {
354
+ anim.goToAndStop(keepFrame ?? last, true)
355
+ if (motion === "calm" && keepFrame == null) {
356
+ stage.animate?.([{ opacity: 0 }, { opacity: 1 }], { duration: 400, easing: "ease-out" })
357
+ }
358
+ } else {
359
+ anim.goToAndStop(0, true)
360
+ if (typeof IntersectionObserver === "undefined") {
361
+ anim.goToAndStop(last, true)
362
+ return
363
+ }
364
+ observer = new IntersectionObserver(
365
+ (entries) => {
366
+ if (!entries.some((entry) => entry.isIntersecting && entry.intersectionRatio > 0.35)) return
367
+ observer?.disconnect()
368
+ playedRef.current = true
369
+ markSeen(key, ever)
370
+ timer = setTimeout(() => animRef.current?.goToAndPlay(0, true), wait)
371
+ },
372
+ { threshold: [0, 0.35, 0.6] }
373
+ )
374
+ observer.observe(host)
375
+ }
376
+ })
377
+ })
378
+ .catch(() => {
379
+ // The fallback stays; the words around the scene already say everything.
380
+ })
381
+
382
+ return () => {
383
+ cancelled = true
384
+ observer?.disconnect()
385
+ if (timer) clearTimeout(timer)
386
+ }
387
+ }, [base, file, play, theme, mode])
388
+
389
+ React.useEffect(() => () => animRef.current?.destroy(), [])
390
+
391
+ // Approve plays forwards, Undo backwards; less motion jumps between the two.
392
+ const firstApproved = React.useRef(true)
393
+ React.useEffect(() => {
394
+ if (firstApproved.current) {
395
+ firstApproved.current = false
396
+ return
397
+ }
398
+ const anim = animRef.current
399
+ if (play !== "manual" || !anim) return
400
+ if (live.current.mode !== "full") anim.goToAndStop(approved ? anim.totalFrames - 1 : 0, true)
401
+ else {
402
+ anim.setDirection(approved ? 1 : -1)
403
+ anim.play()
404
+ }
405
+ }, [approved, play])
406
+
407
+ // The waiting is over: stop the loop and show its end.
408
+ React.useEffect(() => {
409
+ const anim = animRef.current
410
+ if (play !== "loop" || !anim) return
411
+ if (!active) {
412
+ anim.loop = false
413
+ anim.goToAndStop(anim.totalFrames - 1, true)
414
+ } else if (live.current.mode === "full") {
415
+ anim.loop = true
416
+ anim.play()
417
+ }
418
+ }, [active, play])
419
+
420
+ const replay = () => {
421
+ if (play !== "view" || mode !== "full") return
422
+ animRef.current?.goToAndPlay(0, true)
423
+ }
424
+
425
+ return (
426
+ <div
427
+ ref={hostRef}
428
+ data-slot="lottie"
429
+ data-moment={name}
430
+ data-ready={ready ? "" : undefined}
431
+ aria-hidden="true"
432
+ onClick={replay}
433
+ className={cn("relative", className)}
434
+ >
435
+ {!ready && fallback ? <div className="absolute inset-0 grid place-items-center">{fallback}</div> : null}
436
+ <div ref={stageRef} className="size-full" />
437
+ </div>
438
+ )
439
+ }
440
+
441
+ export { Lottie }
package/src/mark.tsx ADDED
@@ -0,0 +1,62 @@
1
+ import { cn } from "./utils"
2
+
3
+ /**
4
+ * The Whity mark: a blank sheet offset up-right on the platform (stage 1).
5
+ * Pixel-fitted cuts below 24px (decision 1.7a): 16px is side 11, offset 4,
6
+ * edge 2, radius 3; 20px is side 14, offset 5, edge 2, radius 3.5; the master
7
+ * is used from 24px up. Each cut is [canvas, side, offset, edge, radius, pad].
8
+ */
9
+ const CUTS = {
10
+ main: [24, 16, 6, 2, 4, 1],
11
+ c20: [20, 14, 5, 2, 3.5, 0.5],
12
+ c16: [16, 11, 4, 2, 3, 0.5],
13
+ } as const
14
+
15
+ type Cut = keyof typeof CUTS
16
+
17
+ function cutFor(size: number): Cut {
18
+ return size >= 24 ? "main" : size >= 20 ? "c20" : "c16"
19
+ }
20
+
21
+ function Mark({
22
+ size = 32,
23
+ cut,
24
+ tone = "auto",
25
+ label = "Whity",
26
+ className,
27
+ }: {
28
+ size?: number
29
+ cut?: Cut
30
+ /** `auto` is the colour mark; `onbrand` sits on Whity Blue; `mono` takes the text colour. */
31
+ tone?: "auto" | "onbrand" | "mono"
32
+ /** The accessible name; pass "" when the mark is decorative. */
33
+ label?: string
34
+ className?: string
35
+ }) {
36
+ const [canvas, side, offset, edge, radius, pad] = CUTS[cut ?? cutFor(size)]
37
+ const plane = tone === "onbrand" ? "fill-mark-sheet" : tone === "mono" ? "fill-current" : "fill-brand"
38
+ const window = tone === "onbrand" ? "fill-brand" : tone === "mono" ? "fill-background" : "fill-mark-sheet"
39
+ return (
40
+ <svg
41
+ data-slot="mark"
42
+ viewBox={`0 0 ${canvas} ${canvas}`}
43
+ width={size}
44
+ height={size}
45
+ className={cn("shrink-0", className)}
46
+ {...(label ? { role: "img", "aria-label": label } : { "aria-hidden": true })}
47
+ >
48
+ <rect className={plane} x={pad} y={pad + offset} width={side} height={side} rx={radius} />
49
+ <rect className={plane} x={pad + offset} y={pad} width={side} height={side} rx={radius} />
50
+ <rect
51
+ className={window}
52
+ x={pad + offset + edge}
53
+ y={pad + edge}
54
+ width={side - 2 * edge}
55
+ height={side - 2 * edge}
56
+ rx={radius - edge}
57
+ />
58
+ </svg>
59
+ )
60
+ }
61
+
62
+ export { Mark }
@@ -0,0 +1,33 @@
1
+ import type { Meta, StoryObj } from "@storybook/react-vite"
2
+
3
+ import { MathText } from "./math-text"
4
+
5
+ const meta = {
6
+ title: "Primitives/MathText",
7
+ component: MathText,
8
+ tags: ["autodocs"],
9
+ argTypes: {
10
+ block: { control: "boolean" },
11
+ errorColor: { control: "text" },
12
+ },
13
+ args: { expression: "\\frac{a}{b} + \\sqrt{x^2 + y^2}", block: false },
14
+ } satisfies Meta<typeof MathText>
15
+
16
+ export default meta
17
+ type Story = StoryObj<typeof meta>
18
+
19
+ export const Inline: Story = {
20
+ render: (args) => (
21
+ <p className="text-sm">
22
+ The solution is <MathText {...args} /> for all real inputs.
23
+ </p>
24
+ ),
25
+ }
26
+
27
+ export const Block: Story = {
28
+ args: { expression: "\\int_0^\\infty e^{-x^2}\\,dx = \\frac{\\sqrt{\\pi}}{2}", block: true },
29
+ }
30
+
31
+ export const RenderError: Story = {
32
+ args: { expression: "\\frac{1}{", errorColor: "#e11d48" },
33
+ }
@@ -0,0 +1,43 @@
1
+ 'use client';
2
+
3
+ import 'katex/dist/katex.min.css';
4
+ import katex from 'katex';
5
+
6
+ export interface MathTextProps {
7
+ /** LaTeX expression without surrounding $ signs */
8
+ expression: string;
9
+ /** Render as display (block) math; defaults to inline */
10
+ block?: boolean;
11
+ /** Color applied to render errors; defaults to 'inherit' */
12
+ errorColor?: string;
13
+ }
14
+
15
+ /**
16
+ * Renders a LaTeX math expression using KaTeX.
17
+ *
18
+ * dangerouslySetInnerHTML is safe here: KaTeX's renderToString escapes text
19
+ * content and, with `trust` disabled (the default, set explicitly below),
20
+ * refuses the only commands that can emit markup/URLs (\href, \url,
21
+ * \includegraphics). So even a hostile `expression` cannot inject executable
22
+ * HTML — KaTeX's own XSS model covers it, and no user-supplied raw HTML is ever
23
+ * passed through.
24
+ */
25
+ export function MathText({ expression, block = false, errorColor = 'inherit' }: MathTextProps) {
26
+ const html = katex.renderToString(expression, {
27
+ throwOnError: false,
28
+ displayMode: block,
29
+ errorColor,
30
+ // Explicit (KaTeX default): keep HTML/URL-emitting commands disabled so the
31
+ // output stays XSS-safe. Do not enable without a sanitization pass.
32
+ trust: false,
33
+ });
34
+
35
+ return (
36
+ <span
37
+ className={block ? 'block' : undefined}
38
+ // KaTeX output with trust:false is XSS-safe to inject (see the doc comment).
39
+ // nosemgrep: typescript.react.security.audit.react-dangerouslysetinnerhtml.react-dangerouslysetinnerhtml
40
+ dangerouslySetInnerHTML={{ __html: html }}
41
+ />
42
+ );
43
+ }