@ultralabs/glass 0.0.0-stage → 0.1.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 (137) hide show
  1. package/CHANGELOG.md +326 -0
  2. package/DESIGN.md +682 -0
  3. package/LICENSE +21 -0
  4. package/README.md +690 -2
  5. package/dist/esm/index.js +20991 -0
  6. package/dist/types/src/charts/ULCartesianChart.d.ts +177 -0
  7. package/dist/types/src/charts/ULDonutChart.d.ts +65 -0
  8. package/dist/types/src/charts/ULFunnelChart.d.ts +64 -0
  9. package/dist/types/src/charts/ULHeatmapChart.d.ts +40 -0
  10. package/dist/types/src/charts/ULRadarChart.d.ts +19 -0
  11. package/dist/types/src/charts/ULRadialChart.d.ts +48 -0
  12. package/dist/types/src/charts/ULScatterChart.d.ts +49 -0
  13. package/dist/types/src/charts/core.d.ts +287 -0
  14. package/dist/types/src/charts/decimate.d.ts +8 -0
  15. package/dist/types/src/charts/nav.d.ts +368 -0
  16. package/dist/types/src/charts/quadtree.d.ts +9 -0
  17. package/dist/types/src/charts/scales.d.ts +59 -0
  18. package/dist/types/src/charts/timeseries.d.ts +56 -0
  19. package/dist/types/src/components/ULAnchoredSurface/ULAnchoredSurface.d.ts +72 -0
  20. package/dist/types/src/components/ULBatch2/carousel.d.ts +31 -0
  21. package/dist/types/src/components/ULBatch2/hovercard.d.ts +40 -0
  22. package/dist/types/src/components/ULBatch2/layout.d.ts +16 -0
  23. package/dist/types/src/components/ULBatch2/menubar.d.ts +29 -0
  24. package/dist/types/src/components/ULBatch2/navmenu.d.ts +51 -0
  25. package/dist/types/src/components/ULBatch2/resizable.d.ts +48 -0
  26. package/dist/types/src/components/ULBatch2/typography.d.ts +55 -0
  27. package/dist/types/src/components/ULButton/ULButton.d.ts +87 -0
  28. package/dist/types/src/components/ULContainers/ULCard.d.ts +54 -0
  29. package/dist/types/src/components/ULContainers/ULDialog.d.ts +57 -0
  30. package/dist/types/src/components/ULContainers/ULLayout.d.ts +81 -0
  31. package/dist/types/src/components/ULContainers/ULMenu.d.ts +99 -0
  32. package/dist/types/src/components/ULContainers/ULOverlays.d.ts +113 -0
  33. package/dist/types/src/components/ULContainers/contextTarget.d.ts +91 -0
  34. package/dist/types/src/components/ULData/ULData.d.ts +225 -0
  35. package/dist/types/src/components/ULData/ULKpi.d.ts +159 -0
  36. package/dist/types/src/components/ULField/ULField.d.ts +93 -0
  37. package/dist/types/src/components/ULForms/fieldContext.d.ts +39 -0
  38. package/dist/types/src/components/ULForms/forms.d.ts +143 -0
  39. package/dist/types/src/components/ULIsland/ULIsland.d.ts +39 -0
  40. package/dist/types/src/components/ULIsland/headerConfig.d.ts +43 -0
  41. package/dist/types/src/components/ULIsland/navIndicator.d.ts +26 -0
  42. package/dist/types/src/components/ULListbox/ULListbox.d.ts +75 -0
  43. package/dist/types/src/components/ULPickers/ULPickers.d.ts +141 -0
  44. package/dist/types/src/components/ULSegmented/ULSegmented.d.ts +50 -0
  45. package/dist/types/src/components/ULSelection/ULSelection.d.ts +71 -0
  46. package/dist/types/src/components/ULSlider/ULSlider.d.ts +43 -0
  47. package/dist/types/src/components/ULSpinner/ULSpinner.d.ts +8 -0
  48. package/dist/types/src/components/ULStructure/kbd.d.ts +22 -0
  49. package/dist/types/src/components/ULStructure/structure.d.ts +154 -0
  50. package/dist/types/src/components/ULTabs/ULTabs.d.ts +28 -0
  51. package/dist/types/src/components/ULTooltip/anchoredTooltip.d.ts +22 -0
  52. package/dist/types/src/components/actions/actions.d.ts +175 -0
  53. package/dist/types/src/components/actions/core.d.ts +346 -0
  54. package/dist/types/src/components/dashboard/blocks.d.ts +583 -0
  55. package/dist/types/src/components/dashboard/blocks2.d.ts +297 -0
  56. package/dist/types/src/components/dashboard/columnsDrag.d.ts +27 -0
  57. package/dist/types/src/components/shared/ULCheckMark.d.ts +9 -0
  58. package/dist/types/src/components/shared/dev.d.ts +13 -0
  59. package/dist/types/src/components/shared/icons.d.ts +23 -0
  60. package/dist/types/src/glass/ULGlass.d.ts +78 -0
  61. package/dist/types/src/glass/ULGlassGroup.d.ts +16 -0
  62. package/dist/types/src/glass/accent.d.ts +31 -0
  63. package/dist/types/src/glass/contrast.d.ts +78 -0
  64. package/dist/types/src/glass/engine.d.ts +177 -0
  65. package/dist/types/src/glass/glassDebug.d.ts +27 -0
  66. package/dist/types/src/glass/material.d.ts +49 -0
  67. package/dist/types/src/glass/radius.d.ts +2 -0
  68. package/dist/types/src/hooks/useAnchoredMorph.d.ts +20 -0
  69. package/dist/types/src/hooks/usePointerLight.d.ts +6 -0
  70. package/dist/types/src/hooks/useReducedMotion.d.ts +3 -0
  71. package/dist/types/src/index.d.ts +150 -0
  72. package/dist/types/src/island/sectionAccent.d.ts +18 -0
  73. package/dist/types/src/live/ULLiveStatus.d.ts +18 -0
  74. package/dist/types/src/live/liveQueue.d.ts +13 -0
  75. package/dist/types/src/live/liveSource.d.ts +149 -0
  76. package/dist/types/src/live/liveStore.d.ts +72 -0
  77. package/dist/types/src/motion/anchoredMorph.d.ts +175 -0
  78. package/dist/types/src/motion/goo.d.ts +3 -0
  79. package/dist/types/src/motion/lensBubble.d.ts +143 -0
  80. package/dist/types/src/motion/lensSelect.d.ts +31 -0
  81. package/dist/types/src/motion/overlayStack.d.ts +13 -0
  82. package/dist/types/src/motion/placement.d.ts +18 -0
  83. package/dist/types/src/motion/spring.d.ts +20 -0
  84. package/dist/types/src/motion/topLayer.d.ts +13 -0
  85. package/dist/types/src/motion/viewSwap.d.ts +33 -0
  86. package/dist/types/src/motion/virtualAnchor.d.ts +28 -0
  87. package/dist/ul-glass.css +10519 -0
  88. package/dist/ul-glass.js +21034 -0
  89. package/dist/ul-glass.min.js +14 -0
  90. package/dist/ul-glass.min.js.map +7 -0
  91. package/icons/arrow-up-down.svg +5 -0
  92. package/icons/bell.svg +3 -0
  93. package/icons/bold.svg +2 -0
  94. package/icons/calendar.svg +5 -0
  95. package/icons/check.svg +2 -0
  96. package/icons/chevron-down.svg +2 -0
  97. package/icons/chevron-left.svg +2 -0
  98. package/icons/chevron-right.svg +2 -0
  99. package/icons/chevrons-right.svg +3 -0
  100. package/icons/circle-check.svg +3 -0
  101. package/icons/circle-x.svg +4 -0
  102. package/icons/circle.svg +2 -0
  103. package/icons/copy.svg +3 -0
  104. package/icons/ellipsis.svg +4 -0
  105. package/icons/eye.svg +3 -0
  106. package/icons/filter.svg +2 -0
  107. package/icons/flags/LICENSE.md +2 -0
  108. package/icons/flags/cs.svg +1 -0
  109. package/icons/flags/de.svg +1 -0
  110. package/icons/flags/en.svg +1 -0
  111. package/icons/flags/sk.svg +1 -0
  112. package/icons/folder-kanban.svg +5 -0
  113. package/icons/icons.json +1 -0
  114. package/icons/inbox.svg +3 -0
  115. package/icons/info.svg +4 -0
  116. package/icons/layout-dashboard.svg +5 -0
  117. package/icons/layout-grid.svg +5 -0
  118. package/icons/loader-circle.svg +2 -0
  119. package/icons/lock.svg +3 -0
  120. package/icons/mail.svg +3 -0
  121. package/icons/menu.svg +4 -0
  122. package/icons/minus.svg +2 -0
  123. package/icons/panel-left-close.svg +4 -0
  124. package/icons/plus.svg +3 -0
  125. package/icons/refresh-cw.svg +5 -0
  126. package/icons/search.svg +3 -0
  127. package/icons/shield-check.svg +3 -0
  128. package/icons/shopping-bag.svg +4 -0
  129. package/icons/sparkles.svg +6 -0
  130. package/icons/trash-2.svg +6 -0
  131. package/icons/triangle-alert.svg +4 -0
  132. package/icons/upload.svg +4 -0
  133. package/icons/users.svg +5 -0
  134. package/icons/x.svg +3 -0
  135. package/package.json +65 -4
  136. package/tokens/tokens.css +799 -0
  137. package/tokens/tokens.json +1017 -0
package/README.md CHANGED
@@ -1,3 +1,691 @@
1
- # Temporary Holding Version
1
+ # @ultralabs/glass
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Seed of the UltraLabs design system: a React + TypeScript + plain CSS component library with a dark "chrome glass" material. Original UltraLabs design, inspired by refractive-glass interfaces in current operating systems.
4
+
5
+ ## Principles
6
+ - **One material.** Every component is built on `ULGlass`. No component sets its own blur, shadow or rim.
7
+ - **Tokens only.** Colors, radii, durations, blur and refraction come from `tokens/tokens.json` via `--ul-*` variables. No literals inside `src/components`.
8
+ - **Glass never samples glass.** Nested glass is flattened automatically. Sibling glass goes in `ULGlassGroup`.
9
+ - **Capsule-first, concentric.** Inner radius = outer radius − padding (`concentric()`).
10
+ - **Materialize, don't fade.** Surfaces appear by growing the lens, not by opacity alone.
11
+ - **Library never knows the product.** `src/` has no dashboard code; `dashboard-demo/` consumes `src/`.
12
+
13
+ ## Install and usage
14
+ ```bash
15
+ npm i @ultralabs/glass react@19 react-dom@19 # peer range react / react-dom ^19.0.0 (tested); no runtime dependencies
16
+ ```
17
+ ```tsx
18
+ import '@ultralabs/glass/tokens.css'; // tokens first
19
+ import '@ultralabs/glass/dist/ul-glass.css'; // component styles (the ESM build does not inject CSS)
20
+ import { ULProvider, ULAccentScope, ULButton, ULTextField } from '@ultralabs/glass';
21
+
22
+ <ULProvider material="glass"> {/* "glass" | "flat" or per category, e.g. { default: 'glass', inputs: 'flat' } */}
23
+ <ULAccentScope accent="violet" strength="tinted"> {/* accent is scoped by ULAccentScope (ULProvider carries material only) */}
24
+ <ULButton variant="primary" onClick={save}>Save changes</ULButton>
25
+ <ULTextField label="E-mail" type="email" helper="We only use it to reply." />
26
+ </ULAccentScope>
27
+ </ULProvider>
28
+ ```
29
+ Entry points: `@ultralabs/glass` (ESM `dist/esm/index.js`, types `dist/types/src/index.d.ts`), `/tokens.css`, `/tokens.json`, `/dist/ul-glass.css`, `/dist` and `/dist/min` (window.UL bundles). The public API is snapshotted in docs/api-surface.txt (`npm run check:api`).
30
+ Without a bundler: load `tokens/tokens.css`, then `dist/ul-glass.js` (exposes `window.UL`, fires `ul:ready`, needs `window.React` and `window.ReactDOM`). The window.UL bundle injects its CSS; apps that load CSS themselves use `dist/ul-glass.css` with `<link data-ul-css>` and the bundle skips its copy.
31
+ Releasing: [docs/release-checklist.md](docs/release-checklist.md).
32
+
33
+ Put the app over a detailed background (imagery, gradients, type). Glass over a flat color has nothing to refract.
34
+
35
+ ### ULGlass props
36
+ | prop | type | default | notes |
37
+ |---|---|---|---|
38
+ | `as` | ElementType | `'div'` | rendered element |
39
+ | `tier` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | controls / cards / menus+sidebars / sheets |
40
+ | `variant` | `'clear' \| 'chrome'` | `'clear'` | chrome adds silver/ice sheen |
41
+ | `radius` | number \| string | tier radius | use `concentric(outer, padding)` when nested |
42
+ | `padding` | number \| string | `0` | |
43
+ | `refraction` | number | `1` | multiplier on tier lens scale; `0` = no lens |
44
+ | `light` | boolean | `true` | pointer light + rim rotation |
45
+ | `visible` | boolean | `true` | toggling materializes / dematerializes |
46
+ | `debug` | boolean | `false` | paints the displacement map |
47
+ | `accent` | preset \| color | inherited | colors body, backdrop, rim, glow, pointer light |
48
+ | `accentStrength` | `'subtle' \| 'tinted' \| 'vivid'` \| 0..1 | inherited (tinted once accented) | how strongly |
49
+ | `backdrop` | `'dark' \| 'mid' \| 'light'` | inherited (dark) | selects the contrast scrim |
50
+ | `interactive` | boolean | `false` | elastic control (buttons, chips, thumbs) |
51
+ | `pressable` | boolean | `false` | press scale + flare |
52
+
53
+ `ULGlassGroup` — `spacing` (px gap, later the merge distance), `direction`.
54
+
55
+ Engine (framework-agnostic): `attachGlass`, `detachGlass`, `configureGlass({ strength, forceFallback })`, `supportsRefraction`, `generateDisplacementMap`, `materialize`, `trackPointer`.
56
+ Motion: `createSpring`, `springs.{bouncy,smooth,snappy}` (same curves as the `--ul-ease-*` tokens).
57
+ Hooks: `usePointerLight`, `useReducedMotion`, `useReducedTransparency`, `useMediaQuery`.
58
+
59
+ ## Performance
60
+ ```tsx
61
+ <ULGlass quality="auto" /> // default: governed (full within the budget, else lite)
62
+ <ULGlass quality="lite" /> // blur + saturate + CSS colorize, no SVG filter
63
+ <ULGlass quality="flat" /> // no backdrop-filter
64
+ <ULGlass priority="overlay" /> // ranked first (anchored surfaces / role=dialog get this automatically)
65
+ configureGlass({ budget: 'auto' }) // or an area in px² (e.g. 150000), or Infinity
66
+ getGlassStats() // { visible, refract, lite, flat, budget, areaUsed, refractCount, degraded, … }
67
+ ```
68
+ Budget and thresholds are tokens (`perf.*`, see DESIGN.md "Performance rules"). Dev HUD: load `showcase/perf-hud.js` before the bundle and press Shift+P (fps, p95 frame time, JS per frame, glass / backdrop-filter / refracted counts, light writes per second, budget; "Run bench" stores idle / scroll / pointer results in localStorage `ul-perf-results`).
69
+
70
+ ## Build
71
+ - `npm run check:locked` → `node scripts/check-locked.mjs`: compares tokens.json, tokens.css and DESIGN.md with `scripts/locked-timings.json` (42 locked names) and prints "42 checked, N differences"; exit 1 on any difference. `npm run tokens`, `npm run build` and `build:min` run it too.
72
+ - `npm run typecheck` → `tsc --noEmit` over `src/` (tsconfig.json). Not run inside the design tool (no Node); run it locally before a release.
73
+ - `npm run build` → `dist/ul-glass.js` (readable) + `dist/ul-glass.css`.
74
+ - `npm run build:min` → also `dist/ul-glass.min.js` + `dist/ul-glass.min.js.map`. The min build sets `window.__UL_PROD__ = true`, which turns off dev warnings. Not shipped yet; the landing loads the readable bundle.
75
+
76
+ ## Selection (Phase 2b)
77
+ ```tsx
78
+ <ULCheckbox label="Newsletter" defaultChecked />
79
+ <ULRadioGroup label="Billing" defaultValue="monthly"><ULRadio value="monthly" label="Monthly" /><ULRadio value="yearly" label="Yearly" /></ULRadioGroup>
80
+ <ULSwitch label="Sync" onCheckedChange={setOn} />
81
+ <ULSlider label="Opacity" defaultValue={40} format={(v) => `${v} %`} /> <ULRangeSlider label="Budget" defaultValue={[20, 80]} />
82
+ <ULSegmentedControl aria-label="Range" options={[{ value: 'day', label: 'Day' }, { value: 'week', label: 'Week' }]} />
83
+ <ULStepper aria-label="Brief" current={1} steps={[{ label: 'Goal' }, { label: 'Scope' }, { label: 'Budget' }]} />
84
+ <ULSelect label="Country" options={[{ value: 'sk', label: 'Slovakia' }]} /> <ULCombobox label="City" options={…} />
85
+ <ULDatePicker label="Start" locale="sk" /> <ULColorPicker label="Accent" defaultValue="violet" />
86
+ ```
87
+ Every list / calendar / color panel is a `ULAnchoredSurface` (anchored morph, portal). Labels need a surface on busy backdrops (glass panel or `data-ul-surface="solid"` scrim).
88
+ `ULColorPicker presets` takes names or `{ value, disabled?, label? }`; a disabled preset is shown crossed out and skipped by the arrow keys.
89
+
90
+ ## Lens bubble, switch, slider, tabs
91
+ - Shared: `LensBubble` + `createLensSelect` (exported). Controls: `ULSwitch lens`, `ULSlider lens / orientation`, `ULRangeSlider`, `ULSegmentedControl lens`, `ULTabs { items: [{ value, label, content? }], orientation, lens }`.
92
+ - Switch: drag to set (decided on release), click toggles, Esc / pointercancel restore. onCheckedChange fires once per release, only when the state changes.
93
+ - Slider: value commits immediately, the thumb glides on `--ul-slider-follow`; the value tooltip is a child of the thumb.
94
+ - Tokens: `--ul-lens-scale` 1.3, `--ul-lens-overshoot` .04, `--ul-lens-grow-duration` 380ms, `--ul-lens-shrink-duration` 320ms, `--ul-lens-drag-stretch` .14, `--ul-lens-magnify` 1.06, `--ul-lens-radius-mode` concentric, `--ul-lens-radius` 12px, `--ul-lens-overgrow-switch` 2px / `-slider` 6px / `-tabs` 2px, `--ul-lens-rubber` .55, `--ul-lens-flick` 140ms, `--ul-lens-lead` 70ms, `--ul-lens-trail` 150ms, `--ul-switch-thumb-ratio` 1.55, `--ul-switch-drag-threshold` 4px, `--ul-slider-thumb-ratio` 1.5, `--ul-slider-follow` 75ms, `--ul-tooltip-hide-delay` 400ms. Switch track 64×28, inset 2.
95
+ - Timings: `--ul-lens-grow-duration` 570ms, `--ul-lens-shrink-duration` 300ms, `--ul-lens-settle-hold` 60ms, `--ul-switch-toggle-duration` 560ms, `--ul-tabs-press-glide` 280ms, `--ul-tabs-glide` 300ms, `--ul-lens-follow` 80ms. Switch 62×27, thumb ratio 1.57, `--ul-lens-scale-switch` 1.55, `--ul-lens-overgrow-switch` 5px.
96
+ - Tabs / segmented: one indicator node (the bubble rests as a flat capsule in the list).
97
+ - Engine: `wakeGlass(el, on)` (visible + measured + tiered now, for display-toggled surfaces).
98
+ - Tests: `showcase/motion-test.dc.html` thumb cards (`showcase/thumb-harness.js`). Perf HUD: "Drag bench" (3 s constant drag + flick on the first slider in view: fps, p95, long frames, stalls, max discontinuity, LoAF script / forced-layout ms).
99
+ - Screenshots: the bubble layer is fixed at the document root; DOM-based screenshot tools that capture only the page root miss it.
100
+
101
+ ## Overlay scroll behavior
102
+ - `<ULAnchoredSurface scrollBehavior="lock|follow|fixed|close" onAnchorHidden="keep|hide|close">` (or `scrollLock`). Defaults: role menu / listbox / dialog = lock, otherwise follow + keep. Tooltips: follow + hide. Anchored toasts: pass `fixed`.
103
+ - Framework-free: `new AnchoredMorph(parts, { scrollBehavior, onAnchorHidden, onRequestClose })`; `lockPageScroll(owner)` / `unlockPageScroll(owner)` for custom modals.
104
+ - Bench: `showcase/scroll-bench.dc.html`. Test: motion-test → Overlay scroll behavior.
105
+
106
+ ## Anchored motion: how to verify
107
+ Every anchored overlay opens and closes through `AnchoredMorph` (via `ULAnchoredSurface` / `useAnchoredMorph`, or `new AnchoredMorph(…, { manual: true })` for framework-free owners). Each run dispatches a bubbling `ul:morph` event on the surface: `detail = { phase: 'enter' | 'exit', state: 'start' | 'end' | 'interrupted', duration, reduced, morph }`.
108
+ - `showcase/motion-test.dc.html`: select, combobox, date picker, color picker, split-button menu, tooltip, island notification. `landing/chrome/motion-test.dc.html`: megamenu, language popper, studio tooltip. Both auto-run (`?norun` to skip) and show a pass/fail card + w/h curve per overlay.
109
+ - Perf HUD (Shift+P) → **Motion test**: runs every visible `[aria-haspopup]` trigger on the current page.
110
+ - Checks: t=0 rect = anchor (±2px) and the anchor wins the hit-test · ≥ 5 intermediate widths and heights · overshoot > 0 then settles · enter ≈ `--ul-pop-enter-duration` × time scale, exit ≈ 70 % · anchor hit-testable every frame · surface painted on top of the page in flight · tier frozen · rim ramps from 0 · content hidden at t0 · translation leads size · reduced motion = uniform 150ms scale/fade · interruption 40 % / 60 % without a jump.
111
+ - Driver: live `requestAnimationFrame` sampling when the tab renders normally; if rAF is throttled (background tab, headless preview) the harness pauses the morph's WAAPI animations and seeks them in 16.7ms steps, so the geometry is still the real rendered one. The card says which driver ran. Rim (rAF-driven) reads n/a on the virtual clock.
112
+ - `configureMorph({ timeScale: 4 })` (the ×0.25 switch) slows every morph; the tests scale their expectations with it. `configureMorph({ reducedMotion: 'reduce' | 'no-preference' | 'auto' })` overrides the media query (tests).
113
+
114
+ ## Containers + overlays (2c)
115
+ ```tsx
116
+ <ULCard size="sm|md|lg" title="Orders" description="12 open" href="/orders" footer={<ULButton size="sm">Archive</ULButton>} />
117
+ <ULPanel surface="glass|calm|well" title="Invoices">…</ULPanel> // calm / well never refract: data goes here
118
+ <ULModal open={o} onOpenChange={setO} triggerRef={btn} title="Rename" size="sm|md|reading" role="dialog|alertdialog" footer={…} />
119
+ <ULSheet …/> <ULDrawer side="right|left" … /> <ULPopover triggerRef={btn} arrow reading /> <ULTooltip content="Copy"><button/></ULTooltip>
120
+ <ULToastProvider position="bottom-right"> … const { toast } = useToast(); toast({ title, tone, action }) </ULToastProvider>
121
+ <ULToast open anchorRef={btn} title="Link copied" /> // anchored toast, fixed while open
122
+ <ULAccordion type="single|multiple" items={[{ value, title, content }]} />
123
+ <ULSidebar sections={…} value collapsed onCollapsedChange drawer="auto" /> <ULToolbar label="Formatting" groups={…} />
124
+ <ULMenu open anchorRef items={[{ id, label, shortcut, type: 'checkbox'|'radio'|'separator'|'label', items: [submenu] }]} />
125
+ <ULMenuButton items={…}>Actions</ULMenuButton> <ULContextMenu items={…}><div tabIndex={0}/></ULContextMenu>
126
+ <ULCommandPalette open onOpenChange items={[{ id, label, group, keywords, onRun }]} triggerRef={search} /> // Cmd / Ctrl + K
127
+ ```
128
+ - Every overlay is `ULAnchoredSurface` (anchored morph + clip-path hole + shared scroll behavior + overlay stack). New props: `layout` (anchored | center | top | bottom | left | right), `scrim`, `modal` (aria-modal + focus trap + focus return), `initialFocus`, `returnFocus`, `manual`, `stack`, `arrow`, `morphRef`.
129
+ - Triggerless overlays start from a virtual anchor (`createVirtualAnchor`, `edgeRect`, `centerRect`, `pointRect`): drawers from the viewport edge, context menus from the pointer point (0 × 0), the palette from the centre.
130
+ - Esc / outside click close only the top layer (`pushOverlay` / `isTopOverlay`); modals stack (the covered one steps back to `--ul-modal-stack-scale`).
131
+
132
+ ## Data (2d)
133
+ ```tsx
134
+ <ULStatTile label="Revenue" value={22840} format={eur} delta={7.8} sparkline={[…]} loading? />
135
+ <ULTable label="Invoices" columns={[{ key, header, sortable, numeric, render, value }]} rows rowKey selectable rowActions={(r) => items}
136
+ density="compact|cozy|comfortable" maxHeight={520} page pageSize onPageChange virtual={{ rowHeight: 48 }} loading empty={…} />
137
+ <ULChart kind="line|area|bar" title="Revenue" labels={months} series={[{ name, data }]} format={eur} />
138
+ <ULBadge tone variant dot/> <ULAvatar name src status/> <ULAvatarGroup people max/> <ULProgress value label kind="bar|ring"/>
139
+ <ULSkeleton shape lines/> <ULEmptyState title description action/> <ULBreadcrumbs items maxItems/> <ULPagination page pageCount onPageChange/>
140
+ ```
141
+ - Data never sits on refracted glass: tables, tiles and charts use `--ul-data-surface` / `--ul-data-well` (calm). Glass appears only in controls, the row-actions menu and the chart value tooltip.
142
+ - Table rows use a flat native checkbox (`RowCheck`), not ULCheckbox: 200 rows must not mount 200 glass surfaces. Select-all stays ULCheckbox.
143
+ - Table keyboard: one tab stop (role grid); arrows, Home / End, Ctrl+Home / End, PageUp / PageDown move the focused cell; Space selects the row; Enter activates the cell's control.
144
+
145
+ ## Pickers, check mark, item radius (2e)
146
+ ```tsx
147
+ <ULDateRangePicker label="Period" defaultValue={{ start, end }} onValueChange={(r) => …} locale="sk" months={2} presets min={…} max={…} isDateDisabled={(d) => …} />
148
+ <ULColorPicker label="Accent" defaultValue="violet" /> // presets + "Custom color" expander (2D field, hue, hex, eyedropper)
149
+ <ULCheckMark checked={selected} /> // the one check for lists, menus and pickers
150
+ ```
151
+ - **ULDateRangePicker**: value `{ start, end }`; `onValueChange` fires once per commit (end chosen, preset, clear), never for the hover / focus preview. Trigger shows two segments ("12 Nov – 20 Nov") and a clear button (`clearable`, default true). Opens in a ULAnchoredSurface (reading variant, portal, scroll lock, anchored morph); below 640px: 1 month in a bottom sheet. Locales EN (en-GB) · SK · DE · CS, Monday first. Presets: Today, Last 7 days, Last 30 days, This month, Last month (`presets` true or a subset).
152
+ - Keys: arrows ±1 day / week, PageUp / PageDown ±1 month (Shift ±1 year), Home / End row start / end, Enter / Space pick, Esc cancels a selection in progress (restores the previous range), otherwise closes. Disabled days are skipped. Live region announces the start and the range.
153
+ - **ULDatePicker** shares the calendar grid (`isDateDisabled` added).
154
+ - **ULColorPicker**: "Custom color" expands the same surface (height measured, never animated to auto); Esc collapses first, then closes. Custom colours go through `guardAccent(color)` (exported): if a colour would break 4.5:1 it is clamped into `--ul-accent-custom-l-min / -l-max / -c-max` (OKLCH) and the picker shows "Adjusted for contrast" with the chosen and the applied swatch. `onValueChange` receives the applied colour.
155
+ - **ULCheckMark** (`animateCheck(el, on)` for non-React owners): draw-in enter, fade + scale exit, `--ul-check-*` tokens. No animation on mount / overlay open.
156
+ - **Item radius**: rows and the shared hover lens inside every anchored surface use `--ul-item-radius` = clamp(`--ul-menu-item-radius-min`, popper radius − popper padding, `--ul-menu-item-radius-max`). Resolved on the surface, so rows and lens always match.
157
+ - **Sheet drag**: mobile bottom sheets (≤ 640px) dismiss by dragging the grabber or the nav bar; content scroll always wins. Desktop sheets have no drag.
158
+ - Tests: `showcase/motion-test.dc.html` (overlays, containers, 2e cards), `showcase/lens-tests.dc.html` (lens / thumb cards on their own page), `showcase/viewport-tests.dc.html` (toasts, radius and narrow range at 1280×800, 924×540, 375×667 in iframes).
159
+
160
+ ## Overlay guarantees (2026-11-08)
161
+ - `<ULAnchoredSurface anchorVisibility="above|covered">`: covered (default for modal / alertdialog) renders scrim + surface in the top layer from the first frame; above (default otherwise) keeps the trigger visible through the clip hole while morphing.
162
+ - After every close the surface and its helpers are unmounted and no inline style survives; owners may clear their anchor or items on close.
163
+ - Nested menus sit beside the parent with `--ul-submenu-gap` (2px).
164
+ - While anything scrolls, glass state is frozen (`isGlassScrolling()`); tiers, maps and budget update ~150ms after scrolling stops. `showcase/glass-scroll-harness.js` → `ULGlassScrollTest.run({ steps: [1, 3, 20], ms: 2000 })` asserts it on any page.
165
+
166
+ ## Tokens
167
+ Edit `tokens/tokens.json`, then `npm run tokens` → `tokens/tokens.css`. Hex colors also emit `--ul-color-*-rgb` triplets for alpha use. Springs emit `linear()` easings plus their natural settle time; pair bouncy with `--ul-duration-slow`, smooth with `base`, snappy with `fast`.
168
+
169
+ ## Browser support
170
+ | engine | material | notes |
171
+ |---|---|---|
172
+ | Chromium (Chrome, Edge, Arc, Opera, Android WebView) | full refraction (SVG displacement) | mobile policy: lens ×0.5, surfaces > 40000 px² blur-only |
173
+ | Safari / WebKit (macOS, all iOS browsers), Tauri on macOS (WKWebView) | blur-only fallback | tint, rim, depth and accent backing kept; never a flat gray plate |
174
+ | Firefox | blur-only fallback | same as WebKit |
175
+ | prefers-reduced-transparency | solid surface | deep accent kept |
176
+ Refraction uses `backdrop-filter: url(#svg-filter)`, which only Chromium renders. Detection is by engine, not `CSS.supports` (WebKit reports support but renders nothing).
177
+
178
+ ## Showcase
179
+ - `showcase/Showcase.dc.html`: material, elasticity, anchored morph, accent, island, tiers. Loads `../dist/ul-glass.js` (no in-browser transpile). `showcase/dev-loader.js` is kept only for live-editing `src/` locally.
180
+ - `showcase/Components.dc.html`: Phase 2 components in tabs (one section mounted at a time), every variant × state, theme / accent / backdrop / blur-only / slow-motion / background switches, a live contrast table, Tweaks for the refraction budget (auto / fixed / unlimited) and the perf HUD (Shift+P).
181
+ - `showcase/ambient-bg.js`: `<ul-ambient-bg animate>`, the pausable animated backdrop shared by both showcases.
182
+
183
+ ## Buttons (Phase 2a)
184
+ `ULButton` props: `variant` primary | secondary (default) | tinted | plain | destructive · `size` sm 36 | md 44 | lg 52 (hit area ≥ 44 always) · `shape` capsule | rounded | circle · `icon`, `iconEnd` (icon with no children = icon-only, needs `aria-label`) · `loading` (width kept, spinner, `aria-busy`, clicks ignored) · `disabled` · `href` (real `<a>`) · `pressed` + `onPressedChange` (toggle, `aria-pressed`) · `accent` · `backdrop` (use `light` on busy backdrops) · `fullWidth`.
185
+ - Material: ULGlass tier sm, `interactive` + `pressable` (elastic 2-3px from `--ul-elasticity`, press .97 + flare). primary = vivid accent, tinted = tinted accent, secondary = subtle, destructive = vivid `--ul-color-danger`. plain has no surface and does not move; use it only on solid or glass surfaces.
186
+ - `ULToggleButton` (controlled or `defaultPressed`), `ULButtonGroup` (`attached`: one glass capsule, the buttons inside are flattened; `attached={false}`: gap only), `ULSplitButton` (`items`, menu via ULAnchoredSurface, ↓/↑ open, Home/End, Esc returns focus), `ULFab` (56px, `label` for extended, `placement` with safe-area insets).
187
+
188
+ ## Fields (Phase 2a)
189
+ Shared props (`FieldBaseProps`): `label` (required, floats by default; `floating={false}` puts it above) · `helper` · `error` (sets `aria-invalid`, replaces helper, polite live region) · `leading` / `trailing` · `size` md 56 | compact 44 · `shape` rounded | capsule · `loading` · `disabled` · `required`.
190
+ - `ULTextField` `type` text | email | password (reveal button) | search (capsule, clear button, Esc clears, `expandOnFocus`) | url | tel; `onValueChange`.
191
+ - `ULTextArea` auto-grows from `minRows` (3) to `maxRows` (10), then scrolls.
192
+ - `ULNumberField` `role="spinbutton"`, −/+ buttons, ↑↓, PageUp/PageDown ×10, Home/End, `min`, `max`, `step`, Intl `format`.
193
+ - `ULOtpField` `length` (6), numeric | alphanumeric, paste fills, Backspace goes back, `autocomplete="one-time-code"`, `onComplete`.
194
+ - `ULTagField` Enter / comma adds, Backspace removes the last, chips with "Remove {tag}" buttons, announcements in a live region, `validate`, `maxTags`.
195
+ - The well is an inset recess, not glass: `--ul-field-well` (graphite 88%) keeps text ≥ 4.5:1 over white and it can sit inside any glass surface. Inputs never move; they only catch pointer light. Put fields on a panel (`ULGlass backdrop="light"`) when the page behind is busy, so the helper and error text have a backing.
196
+
197
+
198
+ ## Accent
199
+ `--ul-accent` (color) and `--ul-accent-k` (strength) are registered properties, so hue and strength changes animate (`--ul-accent-duration` 600ms, 1ms under reduced motion).
200
+ ```tsx
201
+ <ULGlass accent="violet">…</ULGlass> // preset → strength "tinted" by default
202
+ <ULGlass accent="amber" accentStrength="vivid">…</ULGlass> // subtle | tinted | vivid | 0..1
203
+ <ULGlass accent="#ff7a59">…</ULGlass> // any CSS color
204
+ <ULAccentScope accent="emerald" strength="subtle">…</ULAccentScope> // set once, everything inside inherits
205
+ <section data-ul-accent="rose" data-ul-accent-strength="vivid">…</section>
206
+ setAccent(el, 'violet', 'vivid') // imperative (observers, island)
207
+ ```
208
+ Glass without any accent keeps the neutral ice look (subtle).
209
+
210
+ | strength | k | use |
211
+ |---|---|---|
212
+ | subtle | .22 | ambient surfaces, close to the stage-B look |
213
+ | tinted | .64 | default for accented glass: clearly colored body |
214
+ | vivid | 1 | hero elements (island, primary buttons) |
215
+
216
+ ### Contrast guard
217
+ Text and icons stay neutral. Declare what's behind the glass with `backdrop` / `data-ul-backdrop`: `dark` (default, luminance ≤ .03), `mid` (≤ .2) or `light`. Each class gets a deep accent backing (accent 32% + black, never neutral gray), sized per strength so that secondary text at rest and primary text under full pointer light both reach 4.5:1 for every preset. `accentContrastReport(el)` re-checks every accent × strength × backdrop for the theme on `el`.
218
+
219
+ | backing α (subtle / tinted / vivid) | dark | mid | light |
220
+ |---|---|---|---|
221
+ | app | .02 / .20 / .18 | .63 / .66 / .64 | .84 / .83 / .80 |
222
+ | marketing | .12 / .38 / .40 | .72 / .76 / .76 | .88 / .88 / .88 |
223
+
224
+ ## ULIsland (dynamic island)
225
+ ```tsx
226
+ <ULIsland state="compact" accent="violet" label="Main" onDismiss={…}>
227
+ <div data-slot="compact">…</div>
228
+ <div data-slot="expanded">…nav…</div> // pill swaps content + size on the overshoot spring
229
+ <div data-slot="notification">…</div> // pours out of the pill (ULAnchoredSurface)
230
+ <div data-slot="tools"><ULIslandTool aria-label="Language">EN</ULIslandTool></div>
231
+ </ULIsland>
232
+ ```
233
+ - **States:** `compact`, `expanded`, `notification`. Props `compact / expanded / notification / tools` work as an alternative to slots.
234
+ - **Accent:** an accented island defaults to `--ul-island-accent-strength` (vivid). Menus and dialogs opened from it use `tinted` for readability.
235
+ - **Elasticity:** `--ul-island-elasticity` (.5 × size tier × global) for the pill and tools; menu items use `--ul-island-item-elasticity` (2.5 → ≈3px pull).
236
+ - **Menu blur:** `--ul-island-menu-blur` (16px) overrides the tier blur on island menus only, for text legibility.
237
+ - **Page-aware accent:** `observeSectionAccent({ island, scope, root, fallback, onValueChange })` picks the deepest `[data-ul-accent]` element under the island's center line. It uses IntersectionObserver plus geometry, keeps the current element until the line is `--ul-island-hysteresis` (24px) past it, and commits after `--ul-island-switch-delay` (140ms) of stability.
238
+ - **Reveal-on-hover rows:** `data-ul-reveal="hover"` on a (nested) ULGlass makes it a glass card only on hover, focus or `aria-current`. Nested glass stays flat (no backdrop) but may be `interactive` (elastic).
239
+
240
+ ### Header config (one typed config, pages only select it)
241
+ `src/components/ULIsland/headerConfig.ts` → `HeaderConfig { variant, leading: logo|back, nav[], megamenu, cta, poppers, studioLink, accent, sticky, indicatorRest, legibility }`. `ULIsland config={…}` renders the expanded face from it. On the landing, `chrome/SiteHeader` maps `variant` (`landing` | `docs`; legacy `mode="docs"` still works) to a config. Per-page overrides: `sticky`, `indicatorRest`, `config`.
242
+
243
+ | variant | leading | nav | megamenu | CTA | poppers · studio link | indicator rests on current |
244
+ |---|---|---|---|---|---|---|
245
+ | landing | logo → / | Solutions ▾ · Our work ▾ · (Pricing) · Company ▾ | yes | yes | lang · studio | no |
246
+ | docs | back arrow → / | Legal · Releases · API · Guides | no (no anchor, no pane) | no | lang · studio | yes |
247
+
248
+ ### Floating nav indicator
249
+ `createNavIndicator({ container, lens, items, rest })` (`ULIsland/navIndicator.ts`) drives one flattened glass lens that glides between nav items on hover and keyboard focus.
250
+ - **Motion:** spring with ζ ≈ .78 for a tiny overshoot. Squash and stretch along the travel axis, capped at `--ul-pop-stretch` × `--ul-elasticity`. No goo. Every move starts from the current pose.
251
+ - **Visibility:** it materializes out when the pointer leaves the nav, and rests on `aria-current` only when `indicatorRest` is set.
252
+ - **Re-measures** on resize, font load, item and aria-current changes.
253
+ - **Reduced motion:** it jumps and fades instead of sliding.
254
+ - **Look:** tint is `--ul-island-lens-tint`. The selected highlight and underline on nav items are gone.
255
+
256
+ ### Overlay legibility
257
+ `legibility: 'high'` (the default) puts the megamenu, language popper, mobile sheet and contact brief on the worst-case (`light`) backing class with `--ul-island-menu-blur` 20px and `--ul-island-menu-magnify` 1, so refraction stays in the bezel. Items are real links/buttons with a full-card hit area of at least 44px. Keyboard: Tab, ←/→ in the nav, ↑/↓ inside a pane, Enter/Space, Esc returns focus. Items are flat glass cards: elastic about 3px, press `--ul-island-item-press` .98 with flare.
258
+
259
+ ### Loading
260
+ Pages load `dist/ul-glass.js` (prebuilt, about 210 KB unminified, no in-browser transpile; CSS inlined). `SiteHeader` injects it while it is being constructed, resolved from `landing/page-tokens.css`. Until then the island shows the calm blur fallback, and `rampGlass` crossfades the lens in over 420ms. Rebuild with `node scripts/build-bundle.mjs` after changing `src/`. The showcase keeps the source loader.
261
+
262
+ ### Language popper and studio link (landing header)
263
+ - **Language:** one row of four flag links EN · SK · DE · CS (flag 32px, code in 11px mono below; hit area 56×60 per link; popper 248px wide, 6px padding). Real `<a lang hreflang>`, `aria-label` = full name, `aria-current` + accent dot on the current one. The shared `createNavIndicator` glides horizontally. Keys: ←/→, Home/End, Enter/Space select, Esc closes. Names show in the shared anchored tooltip (no `title`).
264
+ - **Flags:** `icons/flags/{en,sk,de,cs}.svg` from circle-flags (MIT, HatScripts). en = us (the code stays EN), cs = cz. See `icons/flags/LICENSE.md`.
265
+ - **Studio link:** one round icon button (`icons/layout-grid.svg`), a real `<a>` to `https://studio.ultralabs.app` (`STUDIO_URL`), `aria-label` and tooltip "Go to studio". Same flattened elastic glass as the language button. No popper, no session detection, no cookie: Studio handles its own sign-in redirect. Hide it per variant with `studioLink: false`.
266
+ - **Removed:** the account popper (signed-in and signed-out), `sessionAware`, `signedIn`. Archived in `_archive/liquid-glass-old/user-popper/`. `docs/auth-cookie-flag.md` is kept but not used.
267
+ - **Contrast** (worst case: light backdrop, all accents, tinted, lens under text + full pointer light): 4.84:1 minimum (amber). Tooltip 17.8:1.
268
+
269
+ ### Anchored tooltip
270
+ `createAnchoredTooltip({ container, layer, items?, text?, side?, clear?, delay? })` (`src/components/ULTooltip/anchoredTooltip.ts`). Delegated hover (350ms) and keyboard focus (immediate); Esc, pointer down and leaving hide it. Enter/exit through `AnchoredMorph` (manual placement, works inside scaled ancestors). The surface is opaque and never samples glass. It sets `aria-describedby` only when its text differs from the item's label. `ULIslandTool tip="…"` uses it.
271
+
272
+ ### Mobile bottom bar
273
+ `landing/chrome/SiteMobileBar.dc.html` is the only mobile bar. Every page with a mobile bar imports it: AppDetail, AppsHub, CareersPage, CareerDetail (+ v1), ContactPage, DevelopersPage, HubPage (+ pre-wow), PillarPage, PricingPage, VerticalPage, WorkIndex, WorkDetail, the riesenia-v2 spec frame and the chrome/mobil-sheet spec. Props: `variant` (floating pill | docked strip), `top`, `cta`, `ctaHref` (default `/contact`), `glyphColor`, `accent`, `menuOpen` (menu ↔ close icon and label), `onMenu`. Diamond mark → `/`, CTA and menu are interactive glass (press .98, 48px). It loads `dist/ul-glass.js` itself, because the header is not mounted on mobile. `chrome/DocsBottomBar` stays separate (docs section switcher, not this bar).
274
+
275
+ ### Mobile glass policy
276
+ `isMobileGlass()` = touch and ≤ 1024px (or `configureGlass({ forceMobile: true })`). Tokens: `--ul-mobile-refraction-scale` (.5, multiplies every lens), `--ul-mobile-refraction-max-area` (40000 CSS px², about 200×200; larger surfaces use the blur fallback), `--ul-mobile-fallback-tint` (.04), `--ul-mobile-fallback-rim` (.22). Result on Android: the sheet is blur-only, the floating bar keeps a lens at ×0.5, the controls inside it are flat. iOS / WebKit never refracts; `[data-ul-mode="fallback"][data-ul-mobile]` adds frost (+14px blur), a brighter top rim, an accent hairline and an inner bevel, on the same accent backing as the megamenu. Check page: `landing/chrome/mobile-glass-check.dc.html`.
277
+
278
+ ### Rebuilding dist without Node
279
+ `scripts/build-bundle.mjs` needs esbuild. The design tool rebuilds the same format in the browser: Babel standalone, every module from `src/index.ts` as a `def(id, deps, fn)` CJS block, CSS pushed into `css[]`, header and boot footer kept from the previous `dist/ul-glass.js`.
280
+
281
+ ### On the landing
282
+ `landing/chrome/SiteHeader.dc.html` is the single header component, imported by every page (`chrome/SiteHeader`). It keeps its layout, links and behavior and uses the engine directly:
283
+ - **Glass:** the pill, the language button, the studio link, the menu panel and the contact surface are ULGlass in the marketing theme.
284
+ - **Menus:** mega menu and language open and close with `AnchoredMorph` from their trigger (`manual` placement: the header owns layout; scaled ancestors supported).
285
+ - **Menu items:** reveal-on-hover elastic glass cards.
286
+ - **CTA:** "Start a project" pours into the contact brief (`contact/ContactDialog`, `entry="brief"`) with the same morph, and reverses on close. The brief resolves from `landing/contact/` for pages in subfolders (chrome/, docs/) via `window.__resources`, no copy.
287
+ - **Accent:** taken from the section under the island (`data-ul-accent` on HubPage sections and pillar rows). The fallback is the page's `--page-accent`.
288
+ - **Loading:** the library is loaded by the header itself, resolved from `landing/page-tokens.css`.
289
+ - **Docs mode** (`mode="docs"`) keeps its previous white glass.
290
+
291
+ ## Project layout
292
+ ```
293
+ design-system/ this library only — never imports from landing/ or apps/
294
+ tokens/ tokens.json (source) → tokens.css (generated, incl. themes)
295
+ scripts/ build-tokens.mjs, build-bundle.mjs, check-locked.mjs + locked-timings.json
296
+ src/glass/ engine.ts, ULGlass, ULGlassGroup, radius.ts
297
+ src/motion/ spring, placement, goo, anchoredMorph
298
+ src/hooks/ usePointerLight, useReducedMotion, useAnchoredMorph
299
+ src/components/ ULAnchoredSurface (more from stage 2)
300
+ icons/ 36 line icons + icons.json (carried over from the v0 spec)
301
+ showcase/ live page of every component and state
302
+ dashboard-demo/ (stage 5)
303
+ landing/ live marketing site (entry: "Landing Page.dc.html"); may import design-system/
304
+ apps/ auth, identify, studio + their shared ds/ tokens
305
+ _archive/ moved, never deleted: design-system-v0, liquid-glass-old, qa, Canvas
306
+ ```
307
+ Dependency rule: `design-system → nothing`. `landing` and `apps` may import `design-system`.
308
+
309
+ ## Themes
310
+ Same tokens, different values, selected with `data-ul-theme` on the root (or any subtree):
311
+ - `app` (default, no attribute needed): full glass, the tuned refraction, bezel, blur and tint.
312
+ - `marketing`: restrained, matches the landing (graphite #060509, Poppins / Geist Mono, 24/32px radii, lens scale about 55%, aberration 1, softer light, elasticity .3, no goo, minimal overshoot). Blur, bezel and tint are unchanged.
313
+
314
+ Defined in `tokens.json → $themes`. Themes override leaf tokens directly, because a `var()` inside a custom property resolves where it is declared.
315
+
316
+ ## Stages
317
+ 1. ✅ Tokens, ULGlass primitive, showcase skeleton
318
+ 2. Phase 2 core components: ✅ 2a buttons + inputs · ✅ 2b selection · ✅ 2c containers + overlays · ✅ 2d data (narrowed). Next: v0.1 freeze (docs/v0.1-freeze-checklist.md), then app shell (not started).
319
+ See `DESIGN.md → Component index` for status and `CHANGELOG.md`.
320
+
321
+ ## Live data, KPI and context menus (Part 3, 2026-11-08)
322
+ ### Live source (WebSocket)
323
+ The library ships no server URL and no token. The app supplies the target and the auth.
324
+ ```tsx
325
+ const source = createLiveSource<Msg>({
326
+ transport: websocket('wss://api.example.com/live'), // wss only; ws:// only on localhost; credentials in the URL are refused
327
+ getAuth: async () => ({ token: await session.getAccessToken() }), // called before every (re)connect, never put in the URL
328
+ idOf: (m) => m.id, // dedupe
329
+ seqOf: (m) => ({ key: m.key, seq: m.seq }), // drop out-of-order
330
+ schema: (m) => isMsg(m), // or a zod-like { safeParse }
331
+ rateLimit: { max: 60, policy: 'coalesce', key: (m) => m.key },
332
+ reconnect: { base: 500, max: 30000 }, // exponential backoff, full jitter
333
+ heartbeat: { interval: 15000, timeout: 5000, ping: () => ({ t: 'ping' }), isPong: (m) => m.t === 'pong' },
334
+ });
335
+ source.onStatus((s, info) => console.log(s, info?.retryIn)); // connecting | live | reconnecting | stale | offline | paused | error
336
+ <ULLiveStatus source={source} /> // dot + label + pause / resume (WCAG 2.2.2)
337
+ ```
338
+ Auth: the transport receives `ctx.auth` and decides how to send it (subprotocol or a first message the app controls). SSE (`sse(url, { withCredentials })`) authenticates with cookies only. `polling(fn, ms)` and `mock({ rate, latency, jitter, drops, duplicates, reorder, failConnects, silent, generate })` share the same API.
339
+ ### Store → table and KPI grid
340
+ ```tsx
341
+ const rows = useLiveStore<Order, Msg>(source, { key: (r) => r.id, initial, toOps: (m) => m.op === 'del' ? { op: 'remove', key: m.id } : { op: 'upsert', value: m.row } });
342
+ <ULTable store={rows} rowKey={(r) => r.id} columns={cols} label="Orders" rowMenu={(r) => items(r)} /> // only changed rows re-render; structural changes queue while hovered
343
+ function Tile({ k }) { const r = useLiveRow(kpis, k); return <ULKpiCard label={r?.label} value={r?.v ?? null} delta={r?.d} live updatedAt={r?.t} />; }
344
+ <ULKpiGrid label="Live KPIs">{keys.map((k) => <Tile key={k} k={k} />)}</ULKpiGrid>
345
+ ```
346
+ One commit per frame (`--ul-live-max-fps`), messages batched per frame, buffered with a cap while paused or hidden.
347
+ ### Context menus
348
+ `contextMenu?: MenuItem[] | ((target) => MenuItem[] | null)` (null / [] keeps the native menu), plus `onContextMenuOpen`, `onContextMenuClose`, `onContextMenuAction(id, target)`, `contextMenuNative: 'never' | 'on-text-selection' | 'on-editable'`. Right-click, long-press (500ms, movement cancels, scroll wins), ContextMenu key, Shift+F10. Built on ULMenu + the anchored morph at a 0 × 0 pointer anchor; one handler set per component root.
349
+ | component | target |
350
+ |---|---|
351
+ | ULTable `contextMenu` / `contextMenuCell` / `contextMenuHeader` / `rowMenu` | `{ component: 'table', kind: 'row' \| 'cell' \| 'header', id: rowKey, data: row, column, selection }` — selection = the selected keys when the row is selected, else [key]. `rowMenu` feeds the ⋯ button AND right-click. |
352
+ | ULKpiCard | `{ component: 'kpi', kind: 'self', data: { label, value, delta, state } }` |
353
+ | ULStatTile | `{ component: 'stat', kind: 'self', data: { label, value, delta } }` |
354
+ | ULChart | `{ component: 'chart', kind: 'point', data: { index, label, values } }` · `kind: 'series', data: { series }` (legend chip) · `kind: 'plot'` |
355
+ | ULCard / ULPanel / ULBadge / ULAvatar / ULToast | `{ kind: 'self', id }` (ULToast: data = the toast options) |
356
+ | ULTabs / ULSidebar / ULAccordion / ULBreadcrumbs / ULTagField | `{ kind: 'tab' \| 'item' \| 'header' \| 'crumb' \| 'tag', id, data }` (items only) |
357
+ | anything else | `<ULContextTarget contextMenu={…} target={{ kind, id, data }}>{child}</ULContextTarget>` |
358
+ While a row's menu is open the row is pinned (structural changes queue like the hover rule; value updates apply); the menu closes with the normal exit if the row is removed anyway. Focus returns to the row / cell.
359
+ ### Rolling number
360
+ One cell = `--ul-kpi-roll-h` (em). At rest each digit is ONE static glyph; while it rolls a strip of whole cells (start → target) moves in the same unit and is removed on settle. The value is one non-wrapping row; separators, currency, % and k are static glyphs. KPI values scale with the tile (`min(3xl, 13.5cqi)`) instead of wrapping.
361
+ ### Tests
362
+ motion-test cards: rolling number, context menu, pointer glass stability, drill-in 375px, toast over modal + backing, KPI states, live source, live table, data glass. `?glassdebug` → "Record pointer / wheel" records style writes per frame with the real mouse.
363
+
364
+ ## Actions (Part 4, 2026-11-08)
365
+ One core: `useAsyncAction` (idle → loading → success | error → idle) + `ULActionButton` (ULButton + icon / label swap, width morph, success ring, error shake). Every component below is a thin layer over it. Feedback goes through the shared anchored tooltip AND one polite live region (`announce`). Labels are localised EN / SK / DE / CS (`locale` prop, else `<html lang>`).
366
+ ```tsx
367
+ <ULActionButton onAction={() => api.publish()} labels={{ idle: 'Publish', loading: 'Publishing…', success: 'Published' }} icons={{ idle: <ULIcon name="send" /> }}
368
+ successDuration={1800} errorDuration={3000} minLoadingMs={350} feedback="inline|tooltip|both" widthMode="morph|reserve" status={controlled} onSuccess onError />
369
+ const { status, error, run, reset } = useAsyncAction(save, { minLoadingMs: 350 }); // headless; throw ACTION_CANCEL to go back to idle silently
370
+
371
+ <ULCopyButton value="INV-2026-0042" /> // button: Copy → Copied, tooltip "Copied to clipboard"
372
+ <ULCopyButton variant="icon" label="Copy API key" sensitive value={() => vault.key()} /> // value never in tooltip / aria / live region
373
+ <ULCopyButton variant="inline" value="npm i @ultralabs/glass" html={richHtml} onCopy={() => track('copy')} />
374
+
375
+ <ULSaveButton dirty={dirty} onSave={() => api.save(doc)} shortcut /> // ⌘ / Ctrl+S; error → "Retry" until retried
376
+ <ULSaveStatus status="clean|dirty|saving|saved|error" savedAt={t} onRetry={save} />
377
+ const guard = useUnsavedChangesGuard(dirty); if (guard.shouldBlock()) … // beforeunload + router-agnostic check
378
+
379
+ <ULSubmitButton onSubmit={(data, form) => api.send(data)} /> // validates the form first; or pending={isSubmitting}
380
+ <ULConfirmAction confirm="inline" label="Delete draft" onConfirm={del} /> // "Confirm?" + 3s countdown ring, Esc / timeout reverts
381
+ <ULConfirmAction confirm="hold" holdMs={1200} onConfirm={del} /> // press and hold (Space / Enter too)
382
+ <ULConfirmAction confirm="type" typeText="client-portal" description="…" onConfirm={del} /> // opens ULModal, action disabled until it matches
383
+ <ULDownloadButton filename="invoices.csv" onExport={({ report }) => buildCsv(report)} /> // Blob | URL | text; report(0..1) = determinate ring
384
+ <ULExportButton formats={[{ id: 'csv', label: 'CSV' }, { id: 'json', label: 'JSON' }]} filename={(f) => 'report.' + f} onExport={({ format }) => exportAs(format)} />
385
+ <ULRefreshButton onRefresh={reload} autoRefresh={30000} /> // "Updated just now / n min ago", countdown ring, pauses when hidden; source={liveSource}
386
+ <ULToggleIconButton kind="star|favorite|pin|bookmark|mute" label="Star" onPressedChange={(on) => api.star(id, on)} /> // optimistic, rollback on reject
387
+ <ULShareButton url={href} title="Client portal" /> // navigator.share when available, else copies the link
388
+ <ULUndoToast open={open} onOpenChange={setOpen} anchorRef={btn} message="3 invoices archived" onUndo={restore} />
389
+ ```
390
+ Rules: the real `<button>`; `aria-busy` + `aria-disabled` (not `disabled`) while loading, so focus stays; no title attributes; never log or announce secrets; glass only where the button is glass (the swap happens inside it); 44px hit area. Tokens: `--ul-action-*`.
391
+
392
+ ## Spam-safe actions, hold, ripple, success tone (Part 6, 2026-11-08)
393
+ ```tsx
394
+ <ULToggleIconButton kind="star" label="Star" onPressedChange={(on) => api.star(id, on)} debounceMs={350} /> // flips at once; onPressedChange(final) once after 350ms of quiet
395
+ const C = useCoalescedAction({ defaultValue: false, commit: (v) => api.save(v) }); // C.value, C.status idle|pending|saving|error, C.set(v), C.flush()
396
+ <ULRefreshButton onRefresh={reload} /> // coalesce="leading-trailing": runs now, clicks meanwhile = ONE follow-up
397
+ <ULActionButton coalesce="trailing" debounceMs={500} onAction={search} />
398
+ <ULConfirmAction confirm="hold" holdMs={900} onConfirm={del} /> // the fill sweeps the whole button (--ul-action-hold-ms)
399
+ <ULPublishButton onPublish={publish} published={isLive} onUnpublish={unpublish} />
400
+ <ULActionButton successEffect="ripple|ring|none" successTone="success|accent" … /> // ripple: save / submit / publish; ring: copy + icon buttons
401
+ ```
402
+ Defaults: toggles trailing; refresh leading-trailing; copy, save, submit, confirm, download, share none (preventDoubleSubmit). Tokens: --ul-action-debounce-ms 350, --ul-action-debounce-max-wait-ms 2000, --ul-action-hold-ms 900, --ul-action-hold-release-ms 160, --ul-action-ripple-ms 520, --ul-action-ripple-fade-ms 240, --ul-action-ripple-delay 80ms, --ul-success, --ul-success-soft.
403
+ Clipboard: `copyText` uses the Clipboard API, else (missing API, http page, permission denied) the legacy hidden-textarea + execCommand copy, always inside the click handler (user gesture); both failing = error state. The value is never logged.
404
+
405
+ ## Dashboard blocks (Part 6)
406
+ ```tsx
407
+ <ULFilterBar fields={fields} value={filters} onValueChange={setFilters} count={rows.length} views={views} onSaveView={save} />
408
+ const rows = applyFilters(all, filters); const q = filtersToQuery(filters); const back = filtersFromQuery(q, fields);
409
+ const [cols, setCols] = useColumnsState(columns, { storageKey: 'accounts-cols' }); // per viewer, try / catch
410
+ <ULColumnsMenu columns={columns} value={cols} onValueChange={setCols} /> // drag the grip to reorder (Esc cancels); Move left / right stays for keys
411
+ <ULTable columns={applyColumns(columns, cols)} density={cols.density} contextMenuHeader={(t) => columnsMenuItems(columns, cols, setCols, { column: t.column })}
412
+ selected={sel} onSelectionChange={setSel} pinSelection /> // pin: 'left' | 'right' on a column = sticky
413
+ <ULBulkActionBar selected={sel} total={rows.length} onClear={() => setSel([])} onSelectAll={…} actions={[{ id: 'export', label: 'Export', onAction: (ids) => … }]} more={[…]} />
414
+ cells: <ULCellStatus value tone /> <ULCellProgress value /> <ULCellPerson name subtitle /> <ULCellNumber value delta format /> <ULCellTime value /> <ULCellSparkline data />
415
+ <ULCellTags tags max /> <ULCellId value /> <ULCellActions items onAction /> <ULCellBool value /> <ULCellLink href /> (each: loading, empty)
416
+ <ULTimeAgo value={date} /> <ULTimestamp value={date} /> // ONE shared timer, paused while the tab is hidden
417
+ <ULTimeRange value="24h" onValueChange={({ from, to, interval }) => …} /> <ULRefreshControl onRefresh={reload} />
418
+ <ULCopyField label="API key" value={key} masked revealTimeout={15000} />
419
+ <ULStatusPill status="operational|degraded|outage|maintenance|unknown" live /> <ULBanner tone title description action /> <ULBannerQueue items onDismiss />
420
+ <ULUsageMeter label value limit burnRate history warning critical action /> <ULErrorState message onRetry diagnostics support />
421
+ <ULDescriptionList items={[{ label, value, copy, truncate }]} layout="grid|stacked" /> <ULTruncatedText text lines />
422
+ ```
423
+
424
+ ### Success wave
425
+ `<ULActionButton successEffect="ripple|ring|none" successOrigin="center|pointer" successTone="success|accent" … />` — ripple is now a circular wave from the origin to the farthest corner (save, submit, publish); copy and icon buttons keep 'ring'.
426
+ Slow motion (showcase / review): `UL.setActionTimeScale(0.5 | 0.25)` scales only the action animations and their timers; `1` restores. The ring uses `--ul-success-ring` (green + success-ink edge, ≥ 3:1 on any backdrop).
427
+
428
+ ## Dashboard blocks 2 (Part 11)
429
+ ```tsx
430
+ <ULInlineEdit label="Seats" type="number" value={seats} onValueChange={setSeats} onCommit={(v) => api.save({ seats: v })} validate={(v) => (v < 1 ? 'At least 1' : null)} />
431
+ <ULNotificationCenter items={items} onReadChange={markRead} onMarkAllRead={markAll} itemMenu={(n) => [{ id: 'archive', label: 'Archive', onSelect: () => archive(n.id) }]} />
432
+ <ULActivityFeed events={events} filters={[{ value: 'deploy', label: 'Deploys' }]} onTargetClick={open} contextMenu={eventMenu} />
433
+ <ULCodeBlock samples={[{ value: 'curl', label: 'curl', language: 'bash', code }, { value: 'ts', label: 'TypeScript', language: 'ts', code: ts }]} highlight={[4]} />
434
+ <ULJsonViewer data={payload} label="Response" defaultExpandDepth={1} pageSize={100} />
435
+ ```
436
+ - Inline edit: click / Enter edits, Enter saves (ULSaveButton states + success wave), Esc cancels; optimistic onValueChange, rolled back when onCommit throws (editor stays on Retry). Same 44px box in both modes.
437
+ - Lists that receive live items use `useLiveQueue(keys)` (callback ref on the list): changes apply at once unless the pointer or focus is inside; then an "N new" pill queues them.
438
+ - JSON viewer keys: ↑ ↓ Home End move, → expands / enters, ← collapses / goes to the parent, Enter toggles (or loads more / expands a long string).
439
+
440
+ ## Icons, embedded, covered notification centre (Task 2F)
441
+ ```tsx
442
+ <ULIcon name="refresh" /> // md = var(--ul-icon-md) (1.25em); xs | sm | md | lg or a px number
443
+ <ULIcon name="x" size={14} />
444
+ <ULIcon filled><circle cx="12" cy="12" r="4" /></ULIcon> // custom glyph, same box rules
445
+ <ULErrorState embedded message="…" onRetry={retry} /> // inside a popover / drawer / dialog: no card, no glass
446
+ <ULCopyButton variant="icon" buttonVariant="plain" value={id} /> // in table cells and rows
447
+ <ULNotificationCenter items={items} anchorVisibility="covered" /> // default; "above" keeps it below the bell
448
+ <ULPopover anchorVisibility="covered" closeButton closeLabel="Close" … />
449
+ ```
450
+ Every svg a component renders is a ULIcon (explicit size) or carries `data-ul-illustration`. Overlay content is never wider than the surface's inner width. Guard cards: motion-test `?norun&card=layoutoverflow | iconsize | ctrltext | coveredanchor`.
451
+
452
+ ## Charts (Task 3A)
453
+ ```tsx
454
+ <ULLineChart title="Revenue" data={rows} x={(d) => d.date} xScale="time" locale="sk"
455
+ series={[{ key: 'web', name: 'Web', value: (d) => d.web }, { key: 'app', name: 'App', value: (d) => d.app }]}
456
+ valueFormat={{ style: 'currency', currency: 'EUR' }} references={[{ value: 1000, label: 'Target', tone: 'accent' }]}
457
+ thresholds={[{ from: 0, to: 500, tone: 'danger' }]} curve="monotone" yScale="linear|log" contextMenu={(t) => items} />
458
+ <ULAreaChart stack="none|stacked|percent" … />
459
+ <ULBarChart stack="stacked" orientation="horizontal" … />
460
+ <ULComboChart series={[{ key: 's', name: 'Sessions', type: 'bar', value }, { key: 'c', name: 'Conversion', type: 'line', axis: 'right', value }]}
461
+ axes={{ left: { label: 'Sessions' }, right: { label: 'Conversion %', format: (v) => v + ' %' } }} … />
462
+ <ULDonutChart title="Payments" data={rows} label={(d) => d.k} value={(d) => d.v} mergeBelow={0.03} center={<ULRollingNumber value={total} />} centerLabel="payments" />
463
+ <ULPieChart … />
464
+ <ULSparkChart data={[…]} variant="line|area|bars|winloss" height={24} label="Revenue trend" /> // aria-hidden without label
465
+ <ULKpiCard variant="sparkline" label="Orders" value={312} trend={<ULSparkChart data={d} variant="bars" />} />
466
+ ```
467
+ - Every chart: `state` ready | loading | empty | error (+ `onRetry`), `stale` (true or text), `panel` (default true = one lite glass panel), `toolbar` (table toggle, copy, CSV), `legend`, `defaultTable`, `filename`, `accent`, `locale`, `summary` (default generated).
468
+ - Keyboard on the plot: ← → points (↑ ↓ on horizontal bars), ↑ ↓ series, Home / End, Enter pins, Esc unpins. Click pins, touch tap shows (vertical scroll stays native).
469
+ - Migration: `<ULChart kind series labels …>` (2d) works unchanged and renders through the core. Building blocks are exported (ChartFrame, ChartLegend, useHoverLayer, useChartTween, scales).
470
+ - Fast preview: `showcase/probe-charts.dc.html?n=10|100|1000` (minified bundle).
471
+ ### Chart patterns (Task 3B)
472
+ ```tsx
473
+ <ULAreaChart patterns="auto" … /> // default: dash for series 3+, fill patterns only with > 4 series / slices or prefers-contrast: more / forced-colors
474
+ <ULBarChart patterns="on" … /> // every series dashed / patterned (print, accessibility exports)
475
+ <ULDonutChart patterns="off" … /> // colour + legend only
476
+ ```
477
+ - Legend swatches mirror the pattern; tooltip keys use the same dash. The figure carries `data-ul-patterns` = on | auto-fills | auto-lines | off.
478
+ - Tests: `showcase/probe-charts.dc.html?guard` (layout guards at 1280×800, 924×540, 375×667), `?cards=all` (chart cards), `ULDemos.chartContrastReport()` on the probe page. motion-test: `?norun&card=charttable` (chartlegend, chartctx, chartkeys, chartreduced, chartmorph, chartsizes, charttip, chartdraw, chartperf).
479
+
480
+
481
+ ## Charts 3B — advanced types, zoom, streaming, linking
482
+ Every type renders inside the shared ChartFrame (one lite glass panel; toolbar = table view, copy data, Download CSV; states `loading | empty | error` + `stale`; `patterns`; `contextMenu` / `onContextMenu*`; EN/SK/DE/CS via `locale`). Shared props (`ChartBaseProps`): `title, description, summary, height, locale, valueFormat, format, accent, panel, className, legend, toolbar, filename, state, onRetry, errorMessage, empty, stale, defaultTable, patterns`.
483
+
484
+ | component | own props | context-menu kinds |
485
+ |---|---|---|
486
+ | `ULRadialChart` | `data, label, value, max (number or accessor, default 100), sweep (90–360°, default 270), center, centerLabel` | point, series |
487
+ | `ULGaugeChart` | `value, min, max, thresholds [{ to, tone, label }], target, targetLabel, compare { value, label }, mode 'fill' \| 'needle', label, center` | value, target, band |
488
+ | `ULRadarChart` | `data (one row per axis), axis, series [{ key, name, value, slot }], max, rings` | point (axis), series |
489
+ | `ULScatterChart` | `data, x, y, size (bubble), group, pointLabel, axes { x, y, size }, trend, brush, onSelect(rows, indices), radius, renderer 'auto' \| 'svg' \| 'canvas'` | point, selection, series, plot |
490
+ | `ULHeatmapChart` | `data, row, col, value, rows, cols, scheme 'sequential' \| 'diverging', domain, mid, labels 'auto' \| 'on' \| 'off', cellHeight, scaleLabel` | cell |
491
+ | `ULCalendarHeatmap` | `data, date, value, from, to, scheme, domain, mid, scaleLabel, cell` | cell (date) |
492
+ | `ULFunnelChart` | `data, label, value` (conversion of the first step, drop-off from the previous) | step |
493
+ | `ULHistogramChart` | `values, bins (number \| 'auto'), binOptions ([] hides the control), percentiles [50, 95, 99], references, xLabel` | bar (bin) |
494
+ | `ULTreemapChart` | `data: TreeNode { name, value?, children? }, path, onPathChange` (drill-in, embedded ULBreadcrumbs) | segment |
495
+
496
+ Keyboard: arrows move (grid rows ↑ ↓ in heatmaps, weeks ← → in the calendar, ↑ ↓ = series in radar, cone nearest neighbour in scatter), Home / End, Enter pins (treemap: Enter opens a group, Backspace goes up), Esc unpins / clears a brush. Every move is announced in the polite live region.
497
+
498
+ ### Zoom, pan, brush (ULLineChart / ULAreaChart / ULBarChart)
499
+ `zoom: true | { brush?: boolean; overview?: boolean }`, `range` (controlled `{ from, to }`, time = Date / ms, category = index; `null` = full), `onRangeChange(v: TimeRangeValue | null)` (same shape as ULTimeRange: `{ preset: 'custom', from, to, interval }`), `highlight` (data index from outside, e.g. a hovered table row).
500
+ Gestures: drag = range brush (opaque readout), Shift+drag or one-finger touch = pan, pinch / Ctrl or Cmd + wheel = zoom (a plain wheel always scrolls the page), double-click or "Reset zoom" = full range, keys `+ - 0`, Shift+← →, Esc cancels a brush. Pure helpers: `zoomAt, panBy, clampView, sliceFor, rangeValue`.
501
+
502
+ ```tsx
503
+ const [range, setRange] = useState<TimeRangeValue | null>(null);
504
+ const filters = range ? [{ id: 'range', field: 'day', op: 'between', value: { start: iso(range.from), end: iso(range.to) } }] : [];
505
+ const rows = applyFilters(allRows, filters);
506
+ <ULTimeRange key={String(range?.from)} value={range ? 'custom' : '30d'} custom={range && { start: range.from, end: range.to }} onValueChange={(v) => v.preset !== 'custom' && setRange(v)} />
507
+ <ULFilterBar fields={[{ key: 'day', label: 'Date', type: 'date' }]} value={filters} count={rows.length} onValueChange={…} />
508
+ <ULAreaChart … xScale="time" zoom={{ overview: true }} range={range} onRangeChange={setRange} highlight={hoveredRow?.dayIndex} />
509
+ <ULTable rows={rows} … /> {/* wrap it and map tr[data-key] hover → highlight */}
510
+ ```
511
+ (Full linked demo: showcase/demos-3c.js LinkedDemo, probe-charts `?adv&only=linked`.)
512
+
513
+ ### Large data and streaming
514
+ - `renderer: 'auto' | 'svg' | 'canvas'` (auto: canvas above `--ul-chart-canvas-at` = 5000 points, line / area / scatter / bubble), `decimate` (LTTB for drawing when points > 2 × plot px; tooltip, keyboard and table keep every point). `lttb(xs, ys, threshold)` keeps first, last, global min and max.
515
+ - `createChartStream({ time, windowMs, maxPoints = 20000, staleAfter = 5000 })` → `appendPoint(p | p[])`, `setWindow(ms)`, `connect(liveSource, map)`, `hold(on)`, `pause() / resume()`, `snapshot()`; one commit per animation frame; LiveSource-compatible status (pass it to ULLiveStatus).
516
+ - `<ULStreamChart stream={s} series={…} x={(p) => p.t} />`: sliding window that scrolls per frame, pulsing bead on the latest point, pause on hover / pin with "N new points" (liveQueue rule), ULLiveStatus (live / paused / stale), stale badge when the source stops, Download CSV = the current window.
517
+
518
+ ## Contrast tool (Task 3C)
519
+ `<script src="showcase/ul-contrast.js">` → `await ULContrast.ready()`, `const R = ULContrast.resolver(el, 'ul-chart2'); R.get('var(--ul-chart-s0)')` → [r, g, b, a] gamma sRGB (gamut mapped), `ULContrast.ratio(fg, bg)`, `ULContrast.over(top, bottom)`. Reports: probe-charts.dc.html?contrast (charts), ?actions (action buttons), probe-forms.dc.html?contrast (forms / feedback).
520
+ Showcase: Components → Charts has the everyday types and a "Charts (advanced)" section (lazy, visible-only), same demos as probe-charts.dc.html?adv.
521
+
522
+ Coverage against the shadcn/ui component list: docs/shadcn-coverage.md.
523
+
524
+ ## Forms (Task 3C)
525
+ ```tsx
526
+ <ULField label="Email" required description="We send the sign-in link here." error={errors.email}>
527
+ <ULTextField label="Email" type="email" floating={false} size="compact" {...register('email')} />
528
+ </ULField>
529
+ <ULField label="Bio" optional><textarea rows={3} /></ULField> {/* native child: cloned with id + aria */}
530
+ <ULField label="Name">{(p) => <MyInput {...p} />}</ULField> {/* render prop: id, aria-describedby, aria-invalid, aria-errormessage, aria-required */}
531
+ <ULField label="Role" orientation="horizontal"><ULSelect label="Role" options={roles} /></ULField>
532
+ <ULFieldSet legend="Billing address" columns={2} error={setError}>…ULField…</ULFieldSet> {/* columns: number | 'auto'; one column below 480px */}
533
+ <ULFieldGroup orientation="horizontal">…</ULFieldGroup>
534
+ <ULFieldError truncate>Long message…</ULFieldError> · <ULFieldError errors={['a', 'b']} />
535
+ <ULLabel htmlFor="x" required | optional>Label</ULLabel>
536
+ <ULInputGroup prefix="https://" suffix=".ultralabs.app"><ULTextField label="Website" floating={false} /></ULInputGroup>
537
+ <ULInputGroup prefix={<ULIcon name="search" size="md" />} suffix={<ULKbd keys="Mod+K" size="sm" />} clearable loading={busy} shape="capsule"><ULInputGroupInput type="search" value={q} onValueChange={setQ} /></ULInputGroup>
538
+ <ULInputGroup maxLength={40} clearable><ULInputGroupInput value={bio} onValueChange={setBio} /></ULInputGroup> {/* counter + "N characters left" announcements */}
539
+ <ULInputGroup suffix="kg"><ULNumberField label="Weight" floating={false} /></ULInputGroup>
540
+ <ULInputGroup actions={<ULCopyButton value={key} variant="icon" sensitive />}><ULInputGroupInput value={key} readOnly /></ULInputGroup>
541
+ ```
542
+ - ULField owns label, description and error; UL controls inside it read the field context (no own label / messages). A NEW error text is announced once through the shared polite live region (`announce`); focus never moves. `announceErrors={false}` opts out.
543
+ - In ULInputGroup the inner control has no second border or well; ULSelect switches to a plain trigger, ULCopyButton to the plain variant. Addon / counter ids join the control's aria-describedby.
544
+
545
+ ### Recipe: form with validation timing, submit and unsaved guard (no dependency; react-hook-form style)
546
+ ```tsx
547
+ function useForm(initial, rules) { // validate on blur, then on every change once touched
548
+ const [values, set] = useState(initial), [touched, setT] = useState({}), [errors, setE] = useState({});
549
+ const check = (k, v) => rules[k]?.(v) || null;
550
+ const register = (k) => ({ value: values[k],
551
+ onValueChange: (v) => { set((s) => ({ ...s, [k]: v })); if (touched[k]) setE((e) => ({ ...e, [k]: check(k, v) })); },
552
+ onBlur: () => { setT((t) => ({ ...t, [k]: true })); setE((e) => ({ ...e, [k]: check(k, values[k]) })); } });
553
+ const dirty = Object.keys(initial).some((k) => values[k] !== initial[k]);
554
+ const validateAll = () => { const e = Object.fromEntries(Object.keys(rules).map((k) => [k, check(k, values[k])])); setE(e); setT(Object.fromEntries(Object.keys(rules).map((k) => [k, true]))); return !Object.values(e).some(Boolean); };
555
+ return { values, errors, register, dirty, validateAll };
556
+ }
557
+ const f = useForm({ email: '' }, { email: (v) => (!/^\S+@\S+\.\S+$/.test(v) ? 'Enter a valid email address.' : null) });
558
+ const guard = useUnsavedChangesGuard(f.dirty); // beforeunload + guard.shouldBlock() before in-app navigation
559
+ <form noValidate onSubmit={(e) => e.preventDefault()}>
560
+ <ULField label="Email" required error={f.errors.email}><ULTextField label="Email" floating={false} {...f.register('email')} /></ULField>
561
+ <ULSubmitButton onSubmit={async () => { if (!f.validateAll()) throw ACTION_CANCEL; await api.save(f.values); }} />
562
+ </form>
563
+ ```
564
+ With react-hook-form: `const { register, formState: { errors } } = useForm({ mode: 'onTouched' })` gives the same timing; pass `error={errors.email?.message}` to ULField and map `register`'s onChange to onValueChange.
565
+
566
+ ## Feedback + structure (Task 3C)
567
+ ```tsx
568
+ <ULAlert tone="warning" title="Card expires soon" description="…" action={<ULButton size="sm">Update</ULButton>} dismissible onDismiss={…} /> {/* info | success | warning | danger | neutral */}
569
+ <ULAlertDialog open={o} onOpenChange={setO} triggerRef={btn} tone="destructive" title="Delete project?" description="…" actionLabel="Delete" onAction={() => api.delete()} typeToConfirm="my-project" />
570
+ const confirm = useAlertDialog(); await confirm({ title, description, tone: 'destructive', onAction }) // inside a dialog: push on the same surface; resolves true / false
571
+ <ULConfirmPopover open={o} onOpenChange={setO} triggerRef={btn} title="Archive 3 items?" onAction={archive} />
572
+ <ULToggleGroup aria-label="View" items={[{ value: 'list', label: 'List' }, …]} value={v} onValueChange={setV} /> {/* single: radio + lens */}
573
+ <ULToggleGroup type="multiple" aria-label="Format" items={[{ value: 'star', icon: <ULIcon name="star" />, tooltip: 'Starred' }]} /> {/* aria-pressed */}
574
+ <ULSeparator /> <ULSeparator orientation="vertical" /> <ULSeparator label="or continue with" />
575
+ <ULKbd keys="Mod+K" /> <ULKbd keys={['G', 'D']} /> <ULKbd keys="Mod+K" platform="other" locale="de" /> {/* Mod = ⌘ on Apple, Ctrl / Strg elsewhere */}
576
+ <ULItemGroup label="Members"><ULItem media={…} title="Ada" description="…" meta="now" selectable selected={s} onSelectedChange={setS} contextMenu={items} actions={…} descriptionLines={2} /></ULItemGroup>
577
+ <ULCollapsible title="Advanced settings" defaultOpen={false}>…</ULCollapsible>
578
+ <ULScrollArea maxHeight={240} label="Audit log" axis="y | x | both" shadows>…</ULScrollArea> {/* scrollThumb(client, content, pos, track) is exported */}
579
+ ```
580
+
581
+ ### 3C tests
582
+ - probe-forms.dc.html (minified bundle, lazy demos): ?only=forms|feedback · ?cards=fieldaria,inputgroup,alerts,alertdialog,togglegroup,separator,kbd,item,collapsible,scrollarea|all · ?guard (1280×800, 924×540, 375×667) · ?contrast. Same cards in motion-test.dc.html?norun&card=<id> (fn f3c_<id>); frame cards collheight, tglide need ≥ 50 fps.
583
+ - The shared guard cards (layoutoverflow, iconsize, ctrltext) also scan every 3C demo when demos-3g.js is loaded (motion-test loads it).
584
+
585
+ ## Navigation, layout + typography (Task 3D)
586
+ ```tsx
587
+ <ULHoverCard label="Jana Nováková" content={<><ULAvatar name="Jana Nováková" /><ULKeyValue items={[{ label: 'Team', value: 'Studio' }]} /></>}>
588
+ <a href="/people/jana">Jana Nováková</a>
589
+ </ULHoverCard>
590
+ ```
591
+ - ULHoverCard: `content`, `side` / `align` / `arrow`, `openDelay` / `closeDelay` (default --ul-hovercard-open-delay 500 / -close-delay 250), `group` (one open card per group), `open` / `defaultOpen` / `onOpenChange`, `contextMenu` on the trigger, `embedded` (default true: content components use their embedded variant). Hover or keyboard focus opens; Tab moves into the card; Esc closes and returns focus. Touch: tap opens, second tap or outside tap closes. The card is supplementary: never put information or actions only there.
592
+
593
+ ```tsx
594
+ <ULMenubar label="Editor" menus={[
595
+ { id: 'file', label: 'File', items: [{ id: 'new', label: 'New', shortcut: 'Mod+N' }, { id: 'recent', label: 'Open recent', items: [...] }, { type: 'separator' }, { id: 'close', label: 'Close' }] },
596
+ { id: 'view', label: 'View', items: [{ id: 'grid', type: 'checkbox', label: 'Show grid', checked: grid, onSelect: toggleGrid }] },
597
+ ]} onAction={(menuId, itemId) => …} />
598
+ ```
599
+ - ULMenubar: role menubar, roving tabindex (← → wrap, Home / End, disabled triggers skipped), Enter / Space / ↓ open on the first item, ↑ on the last; while open, ← → inside the menu or hovering another trigger switches menus at once; Esc returns focus to the trigger. Menu `shortcut` strings now render through ULKbd everywhere (ULMenu, command palette).
600
+
601
+ ```tsx
602
+ <ULNavigationMenu label="Site" locale="sk" onNavigate={(e, l) => { e.preventDefault(); router.push(l.href); }} items={[
603
+ { id: 'products', label: 'Products', panel: { links: [{ id: 'studio', title: 'Studio', description: '…', href: '/studio', icon: 'layout-grid' }] } },
604
+ { id: 'pricing', label: 'Pricing', href: '/pricing', current: true },
605
+ ]} />
606
+ ```
607
+ - ULNavigationMenu: link items (`href`, `current` → aria-current="page") and panel items (grid of ULItem links, `minColumn`, `footer`). ← → Home End, ↓ / Enter opens (↓ focuses the first link), Esc closes, Tab runs through the links. `collapseBelow` (default 640) switches to a Menu button + bottom sheet with drill-in. No URLs inside the component.
608
+
609
+ ```tsx
610
+ <ULNativeSelect label="Country" groups={[{ label: 'Europe', options: [{ value: 'sk', label: 'Slovakia' }] }]} placeholder="Choose" error={err} />
611
+ <ULSelect label="Plan" options={plans} native="mobile" /> // native picker on coarse pointers
612
+ <ULCalendar mode="range" locale="sk" min={min} max={max} isDateDisabled={(d) => d.getDay() === 0} onValueChange={(r) => …} />
613
+ <ULAspectRatio ratio={16 / 9} fit="cover"><img src={…} alt="…" /></ULAspectRatio> // skeleton for loading
614
+ ```
615
+ - ULCalendar `mode` single (Date) | multiple (Date[]) | range ({ start, end }); `jump` month / year selects; same keys as the pickers; Esc cancels a half-picked range.
616
+
617
+ ```tsx
618
+ <ULResizablePanelGroup direction="horizontal" storageKey="editor" onLayout={(s) => …} stackBelow={420}>
619
+ <ULResizablePanel defaultSize={24} minSize={14} maxSize={40} collapsible label="Sidebar">…</ULResizablePanel>
620
+ <ULResizableHandle />
621
+ <ULResizablePanel minSize={30} label="Editor">…</ULResizablePanel>
622
+ </ULResizablePanelGroup>
623
+ ```
624
+ - Handle keys: ← → (↑ ↓ vertical) 1 %, Shift 10 %, Home / End to the limits, Enter collapses / expands the collapsible neighbour; double-click resets. Storage: `ul-resizable:<storageKey>` in localStorage (try / catch, per viewer).
625
+
626
+ ```tsx
627
+ <ULCarousel label="KPIs" visible={2} locale="sk" onIndexChange={…}>{kpis.map((k) => <ULKpiCard key={k.id} {...k} />)}</ULCarousel>
628
+ <ULCarousel label="Screens" loop autoplay={4000}>…</ULCarousel> // autoplay is opt-in
629
+ ```
630
+
631
+ ```tsx
632
+ <ULHeading level={2} size="display">Pricing</ULHeading> // outline level and visual size are independent
633
+ <ULText variant="lead">…</ULText> <ULText variant="muted" truncate>…</ULText> <ULText lines={2}>…</ULText>
634
+ <ULLink href="https://example.org">Guide</ULLink> // external: icon + target _blank + rel noopener noreferrer external + spoken hint
635
+ <ULProse>{markdownHtml}</ULProse>
636
+ ```
637
+
638
+ Direction: RTL is not supported in v0.1 (docs/rtl-audit.md).
639
+
640
+ ### React versions
641
+ Peer range `react` / `react-dom` ^19.0.0. Types are checked against React 19 (`@types/react` + `@types/react-dom` ^19, the owner's strict `npm run typecheck`); the showcase runs on React 19. React 18 is not supported in 0.1.0.
642
+
643
+ ### Callback naming (0.1.0)
644
+ One rule, no aliases: value controls `value / defaultValue / onValueChange`; checked controls `checked / defaultChecked / onCheckedChange`; toggle buttons `pressed / defaultPressed / onPressedChange`; open state `open / defaultOpen / onOpenChange`. Native wrappers that also forward the DOM `onChange` event (inherited from the HTML attributes, never redeclared): ULTextField, ULTextArea, ULInputGroupInput, ULCheckbox, ULRadio. Guard: `npm run check:callbacks` (scripts/check-callbacks.mjs, part of build).
645
+
646
+ ### Viewport tests
647
+ `showcase/viewport-tests.dc.html?frame=1280` (or 924, 375) runs one frame; without `?frame` the three run in sequence with one iframe mounted at a time. Steps load their demos lazily and report progress; a step that does not finish is NEEDS HEALTHY PREVIEW.
648
+
649
+ ### JSDoc coverage
650
+ `npm run check:jsdoc` prints public prop JSDoc coverage per family (`--list` shows undocumented props) and checks every documented default against the code (scripts/check-jsdoc-defaults.mjs). v0.1: actions, fields + pickers, selection, overlays, data and charts at 100 %; the other families are v0.1.1 (docs/component-inventory.md).
651
+
652
+ ### Token integrity
653
+ Tokens are added only in tokens/tokens.json (tokens.css is generated). `npm run check:tokens` (scripts/check-tokens.mjs, part of build) fails on any var(--ul-*) that nothing defines and lists unused tokens (docs/_unused-tokens.txt).
654
+
655
+ ### Hit areas
656
+ Every control below 44px gets the shared invisible hit layer (src/components/shared/hit.css): `.ul-hit` (both axes, isolated / icon-only), `.ul-hit-y` (vertical only, controls in a row), `.ul-hit-layer` child where glass owns the pseudo-elements. App code uses the same classes for custom controls. Exceptions (24px min): compact table cells, inline text links. Card `hitarea`.
657
+
658
+ ### Pre-freeze audit tests
659
+ - Keyboard: motion-test `?norun&card=kbdaudit` (or probe-charts `?cards=kbdaudit&kbdonly=Selection,Data`, `&kbdper=3`): table component → PASS / FAIL (first failing step) / NATIVE / NEEDS FOCUS in `window.__kbdAudit`. Takes several minutes in a slow preview.
660
+ - Scatter canvas: `?cards=scattercanvas` · columns drag: `?cards=colsdrag`.
661
+ - Fallbacks: any page `?glass=lite` / `?glass=flat`; reduced transparency forced with `?transparency=reduce` or `<html data-ul-transparency="reduce">` (same rules as the media query).
662
+
663
+ ## Material: glass and flat
664
+ Resolution (most specific wins): instance `material` prop > nearest `<ULProvider material>` > category default > global default ("glass").
665
+ ```tsx
666
+ <ULProvider material="flat">…</ULProvider>
667
+ <ULProvider material={{ default: 'glass', inputs: 'flat' }}>…</ULProvider>
668
+ <ULTextField label="Name" material="glass" />
669
+ ```
670
+ | Category | Default | Components |
671
+ |---|---|---|
672
+ | inputs | flat | text, textarea, number, OTP, tag field, select, combobox, native select, date / range / colour picker triggers, time range, input group, copy field (their popovers are overlays) |
673
+ | controls | glass | buttons, button group, switch, checkbox, radio, step dots |
674
+ | surfaces | glass | ULGlass default, cards, panels, KPI / stat / table panels |
675
+ | overlays | glass | ULAnchoredSurface (popovers, menus, dialogs, sheets), list / menu / calendar lenses |
676
+ | chrome | glass | island, sidebar, toolbar, side nav |
677
+
678
+ Flat = the reduced-transparency fallback (same base, same tokens): no backdrop-filter, no refraction, no gloss rim, no pointer light, no goo. Colour stays: accented glass (primary, destructive) keeps its accent fill in flat (opaque body colour × accent strength under the contrast backing; flat primary label 8:1 violet, 5.8:1 amber). Subtle glass (secondary) = --ul-color-surface-solid, identical to reduced transparency. Reduced transparency itself is unchanged: its primary is the darker deep-accent plate. Flat surfaces are never granted refraction and add no area to the refraction budget (engine `isFlatMaterial`). Lens bubbles on flat controls keep the same geometry and the locked timings (flat pill). Field wells were never glass: flat only removes their pointer light. Custom picker triggers (date, date range, colour; time range) use the same inset well as text and select in flat (--ul-fw / --ul-fr, inset, hover, focus, invalid); in glass they stay glass triggers. Popovers stay glass.
679
+ OTP sizes to its container: cells shrink from --ul-field-otp-w (48px) to 75 % (36px), the gap from 8 to 4px; height stays --ul-field-h. Normal form widths are unchanged; below ~272px the 36px minimum overflows.
680
+ Non-React: `data-ul-material="flat"` (or "glass") on any element; the nearest attribute wins. Components stamp the resolved value on their root when it is flat or set explicitly.
681
+ Test: motion-test `?norun&card=material` and `?norun&card=otplayout` (also in showcase/focused-runs). Showcase: showcase/material.dc.html (same form in glass, flat, mixed, before).
682
+
683
+ ## Known limits (0.1.0)
684
+ - OTP cells shrink to 36px wide at a 280px container; the hitarea card only tests the normal width.
685
+ - Flat vs reduced transparency differ for primary / destructive buttons: flat keeps the accent fill, reduced transparency stays a dark deep-accent plate.
686
+ - `--ul-field-rim` was raised .14 → .18 (3.11:1); it also affects the field border in glass.
687
+ - Timing / fps test cards are valid only on a ≥ 100 Hz display in Chrome; Safari runs rAF at 60 Hz.
688
+ - Dark-only in v1. No RTL (plan in [docs/rtl-audit.md](docs/rtl-audit.md)). JSDoc covers 85 % overall, 33 % in the "other" family (v0.1.1).
689
+ - v0.2: ULMenubar re-anchor, header megamenu → ULNavigationMenu, lazy-loaded action icons ([docs/v0.2-backlog.md](docs/v0.2-backlog.md)).
690
+ - The copy field well has no hover / invalid / disabled state (no props for them).
691
+ - One moderate npm audit finding, package not yet identified (dev-only or runtime: see the release checklist).