@zonsh/ui 0.7.1 → 0.8.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 (45) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/dist/components/bottom-nav.js +10 -293
  3. package/dist/components/button.d.ts +2 -1
  4. package/dist/components/button.js +2 -0
  5. package/dist/components/radio-group.d.ts +23 -2
  6. package/dist/components/radio-group.js +62 -4
  7. package/dist/index.d.ts +2 -2
  8. package/dist/index.js +2 -2
  9. package/dist/lib/liquid-mark.d.ts +29 -0
  10. package/dist/lib/liquid-mark.js +327 -0
  11. package/dist/skills/zon-ui/SKILL.md +3 -3
  12. package/dist/skills/zon-ui/references/components/button.md +20 -1
  13. package/dist/skills/zon-ui/references/components/radio-group.md +73 -2
  14. package/dist/skills/zon-ui/references/components/theme.md +2 -2
  15. package/dist/sources/audio-player.css +3 -0
  16. package/dist/sources/bottom-nav.css +1 -0
  17. package/dist/sources/button.css +3 -0
  18. package/dist/sources/carousel.css +3 -0
  19. package/dist/sources/code-block.css +3 -0
  20. package/dist/sources/conversation.css +3 -0
  21. package/dist/sources/copy-button.css +3 -0
  22. package/dist/sources/data-table.css +2 -0
  23. package/dist/sources/file-drop.css +3 -0
  24. package/dist/sources/filter-bar.css +2 -0
  25. package/dist/sources/lightbox.css +2 -0
  26. package/dist/sources/markdown-editor.css +2 -0
  27. package/dist/sources/message.css +3 -0
  28. package/dist/sources/pagination.css +3 -0
  29. package/dist/sources/pdf-viewer.css +2 -0
  30. package/dist/sources/radio-group.css +5 -0
  31. package/dist/sources/response.css +2 -0
  32. package/dist/sources/scheduler.css +3 -0
  33. package/dist/sources/sidebar.css +2 -0
  34. package/dist/sources/site-header.css +3 -0
  35. package/dist/sources/sortable.css +3 -0
  36. package/dist/sources/suggestions.css +3 -0
  37. package/dist/sources/theme.css +3 -0
  38. package/dist/sources/tool-call.css +3 -0
  39. package/dist/sources/tour.css +2 -0
  40. package/dist/sources/video-player.css +2 -0
  41. package/dist/styles/core.css +16 -13
  42. package/dist/styles/parts/controls.css +88 -0
  43. package/dist/vite.d.ts +41 -11
  44. package/dist/vite.js +78 -23
  45. package/package.json +1 -1
@@ -0,0 +1,327 @@
1
+ /*
2
+ * The liquid lens of a capsule (BottomNav's, RadioGroup variant="capsule"): its mark, pressed,
3
+ * swells and lifts; dragged, it trails the finger on a spring and chooses the item it is let go
4
+ * over; a tap travels to the tapped item the same way. Shared, so every capsule moves alike.
5
+ */
6
+ import * as React from "react";
7
+ import { layoutBox } from "./glide.js";
8
+ /** The bar's mark: a 2px rule, 32px wide, on the hairline over the current item's tile. */
9
+ export const RULE = 32;
10
+ const isDisabled = (el) => el.matches('[aria-disabled="true"], [data-disabled], :disabled');
11
+ /** How far a press moves sideways before it becomes a drag of the mark (px). */
12
+ const DRAG_FROM = 6;
13
+ const reducedMotion = () => typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
14
+ /** Held: the lens trails the finger a little under-damped, and swells with a small wobble. */
15
+ const HOLD = { k: 420, c: 30, sizeK: 520, sizeC: 22 };
16
+ /**
17
+ * Let go: one spring, a touch under critical damping, carries the lens on from its own speed onto
18
+ * the item and shrinks it back with the same stiffness, so it travels, sets down and loses its
19
+ * lift as one motion that ends at once, rather than a quick shrink and then a slide.
20
+ */
21
+ const SETTLE = { k: 320, c: 34 };
22
+ /** The lens's swell while held: the lift (its shadow) follows it from 0 at rest to 1 held. */
23
+ const SWELL = { capsule: 1.3, bar: 1.6 };
24
+ /**
25
+ * How far a release carries on at the finger's speed when it chooses the item (s): a flick towards
26
+ * the next item lands on it, a finger that has stopped chooses what is under it.
27
+ */
28
+ const PROJECT = 0.08;
29
+ /** The finger's speed over its last 80ms (px/s), or 0 once it has stopped. */
30
+ function fingerSpeed(samples, now) {
31
+ const recent = samples.filter(([t]) => now - t <= 80);
32
+ if (recent.length < 2)
33
+ return 0;
34
+ const [t0, x0] = recent[0];
35
+ const [t1, x1] = recent.at(-1);
36
+ return t1 > t0 ? ((x1 - x0) / (t1 - t0)) * 1000 : 0;
37
+ }
38
+ /**
39
+ * The mark as a drop of liquid, as in iOS: pressed, it swells past the capsule and lifts; dragged, it
40
+ * trails the finger on a spring, stretching along its path and squashing across it, rubber-banding
41
+ * past the ends; let go, it springs onto the item under it and wobbles still. The icon under the
42
+ * lens swells with it, and a light tick marks each new item where the device can. Letting go
43
+ * clicks that item, so a link navigates and `onValueChange` fires as for a tap. A press that stays
44
+ * put is an ordinary tap, and the lens travels to the tapped item the same way, stretching as it
45
+ * goes. Under reduced motion the lens moves without springs or swelling.
46
+ */
47
+ export function useLiquidMark(row, mark, { capsule, item: ITEM, tile: TILE, isCurrent }) {
48
+ const [active, setActive] = React.useState(false);
49
+ // Held or dragged: the mark lifts (a deeper shadow). A tap's travel moves it as it rests.
50
+ const [lifted, setLifted] = React.useState(false);
51
+ const [under, setUnder] = React.useState(null);
52
+ const state = React.useRef(null);
53
+ const swallowClick = React.useRef(false);
54
+ const items = () => Array.from(row.current?.querySelectorAll(`:scope > ${ITEM}`) ?? []);
55
+ // Measured exactly as the resting glide measures the current tile (layout boxes, from the row's
56
+ // padding box), so the spring lands on the very pixel the glide then holds: no 1px hop, no
57
+ // change of width, as the lens hands over from the spring to its resting place.
58
+ const measure = () => items().map((el) => {
59
+ const t = layoutBox((TILE ? el.querySelector(TILE) : null) ?? el, row.current);
60
+ return { left: t.x, top: t.y, width: t.width, height: t.height, centre: t.x + t.width / 2 };
61
+ });
62
+ const nearest = (s, x) => {
63
+ const all = items();
64
+ let best = s.under;
65
+ let distance = Infinity;
66
+ s.tiles.forEach((t, i) => {
67
+ if (all[i] && isDisabled(all[i]))
68
+ return;
69
+ const away = Math.abs(t.centre - x);
70
+ if (away < distance)
71
+ [best, distance] = [i, away];
72
+ });
73
+ return best;
74
+ };
75
+ const paint = (s) => {
76
+ const el = mark.current;
77
+ const tile = s.tiles[s.from] ?? s.tiles[0];
78
+ if (!el || !tile)
79
+ return;
80
+ // Stretched along the path by its speed, squashed across it so it keeps its volume.
81
+ const along = 1 + s.stretch;
82
+ const across = 1 / Math.sqrt(along);
83
+ // The lift (the shadow under the pill, parts/navigation.css) rises and sets down with the swell.
84
+ const swell = capsule ? SWELL.capsule : SWELL.bar;
85
+ el.style.setProperty("--lens-lift", `${Math.min(1, Math.max(0, (s.size - 1) / (swell - 1)))}`);
86
+ if (capsule) {
87
+ el.style.width = `${tile.width}px`;
88
+ el.style.height = `${tile.height}px`;
89
+ el.style.translate = `${s.x - tile.width / 2}px ${tile.top}px`;
90
+ el.style.scale = `${s.size * along} ${s.size * across}`;
91
+ }
92
+ else {
93
+ // The bar's rule: it stretches with the speed and thickens while held.
94
+ el.style.width = `${RULE}px`;
95
+ el.style.height = "2px";
96
+ el.style.translate = `${s.x - RULE / 2}px -1px`;
97
+ el.style.scale = `${along * (1 + (s.size - 1) * 0.6)} ${s.size}`;
98
+ }
99
+ };
100
+ const finish = () => {
101
+ const s = state.current;
102
+ if (s)
103
+ cancelAnimationFrame(s.frame);
104
+ state.current = null;
105
+ // The spring ended exactly where the resting glide puts it: React writes that place over these
106
+ // values on the next render, so only the scale, which it does not know, is cleared here.
107
+ if (mark.current) {
108
+ mark.current.style.scale = "";
109
+ mark.current.style.removeProperty("--lens-lift");
110
+ }
111
+ setActive(false);
112
+ setLifted(false);
113
+ setUnder(null);
114
+ };
115
+ const step = (now) => {
116
+ const s = state.current;
117
+ if (!s)
118
+ return;
119
+ const dt = Math.min(0.034, Math.max(0.001, (now - s.last) / 1000));
120
+ s.last = now;
121
+ if (reducedMotion()) {
122
+ [s.x, s.v, s.size, s.sv, s.stretch] = [s.target, 0, 1, 0, 0];
123
+ }
124
+ else {
125
+ // Held, a little under-damped: it trails the finger, overshoots a touch and settles. Let go,
126
+ // position and size share one spring, from where and how fast they are (no restart).
127
+ const p = s.releasing ? { k: SETTLE.k, c: SETTLE.c, sizeK: SETTLE.k, sizeC: SETTLE.c } : HOLD;
128
+ // In steps of at most 4ms, so a slow or dropped frame moves it as far as the spring says,
129
+ // not a long straight step that overshoots, and 60Hz and 120Hz screens draw the same curve.
130
+ const steps = Math.ceil(dt / 0.004);
131
+ const h = dt / steps;
132
+ for (let i = 0; i < steps; i++) {
133
+ s.v += (p.k * (s.target - s.x) - p.c * s.v) * h;
134
+ s.x += s.v * h;
135
+ s.sv += (p.sizeK * (s.grow - s.size) - p.sizeC * s.sv) * h;
136
+ s.size += s.sv * h;
137
+ const want = Math.min(Math.abs(s.v) / 1400, capsule ? 0.45 : 0.9);
138
+ s.stretch += (want - s.stretch) * Math.min(1, h * 18);
139
+ }
140
+ }
141
+ paint(s);
142
+ // Still to well under a pixel, so handing the place back to the resting glide shows nothing.
143
+ const still = Math.abs(s.target - s.x) < 0.2 &&
144
+ Math.abs(s.v) < 3 &&
145
+ Math.abs(s.grow - s.size) < 0.001 &&
146
+ Math.abs(s.sv) < 0.02 &&
147
+ s.stretch < 0.002;
148
+ if (s.releasing && still)
149
+ return finish();
150
+ s.frame = requestAnimationFrame(step);
151
+ };
152
+ const start = (s, lift) => {
153
+ state.current = s;
154
+ setActive(true);
155
+ setLifted(lift);
156
+ paint(s);
157
+ s.last = performance.now();
158
+ s.frame = requestAnimationFrame(step);
159
+ };
160
+ React.useEffect(() => () => cancelAnimationFrame(state.current?.frame ?? 0), []);
161
+ // A press let go outside the row (slid off it, before it became a drag) never reaches the row's
162
+ // pointerup: seen on the document, it ends the press choosing nothing, so no stale press waits
163
+ // for a later move or release. After the event has run its course, so a release on the row
164
+ // has already ended the press there.
165
+ const endRef = React.useRef(null);
166
+ React.useEffect(() => {
167
+ const onUp = (event) => {
168
+ const s = state.current;
169
+ if (!s || s.pointer !== event.pointerId || s.releasing)
170
+ return;
171
+ setTimeout(() => {
172
+ if (state.current === s && !s.releasing)
173
+ endRef.current(event, false);
174
+ }, 0);
175
+ };
176
+ document.addEventListener("pointerup", onUp, true);
177
+ document.addEventListener("pointercancel", onUp, true);
178
+ return () => {
179
+ document.removeEventListener("pointerup", onUp, true);
180
+ document.removeEventListener("pointercancel", onUp, true);
181
+ };
182
+ }, []);
183
+ // The item under the lens takes the full ink and swells, as the current one does.
184
+ React.useEffect(() => {
185
+ items().forEach((el, i) => el.toggleAttribute("data-under", i === under));
186
+ // eslint-disable-next-line react-hooks/exhaustive-deps
187
+ }, [under]);
188
+ const onPointerDown = (event) => {
189
+ const list = row.current;
190
+ if (!list || (event.pointerType === "mouse" && event.button !== 0))
191
+ return;
192
+ const item = event.target.closest(ITEM);
193
+ if (!item || item.parentElement !== list || isDisabled(item))
194
+ return;
195
+ if (state.current)
196
+ finish();
197
+ const tiles = measure();
198
+ const all = items();
199
+ const from = all.indexOf(item);
200
+ const current = all.findIndex(isCurrent);
201
+ const home = tiles[current >= 0 ? current : from].centre;
202
+ const s = {
203
+ pointer: event.pointerId,
204
+ startX: event.clientX,
205
+ moved: false,
206
+ tiles,
207
+ from,
208
+ under: from,
209
+ x: home,
210
+ v: 0,
211
+ target: home,
212
+ size: 1,
213
+ sv: 0,
214
+ grow: 1,
215
+ stretch: 0,
216
+ samples: [[event.timeStamp, event.clientX]],
217
+ releasing: false,
218
+ last: 0,
219
+ frame: 0,
220
+ };
221
+ // Pressing the current item lifts the lens at once; another waits to see if it is a drag.
222
+ if (from === current) {
223
+ s.grow = capsule ? SWELL.capsule : SWELL.bar;
224
+ start(s, true);
225
+ }
226
+ else {
227
+ state.current = s;
228
+ }
229
+ };
230
+ const onPointerMove = (event) => {
231
+ const s = state.current;
232
+ const list = row.current;
233
+ if (!s || !list || s.pointer !== event.pointerId || s.releasing)
234
+ return;
235
+ // A mouse or pen keeps its pointer id between presses: a move with nothing held is not this
236
+ // press (its release went elsewhere), so it ends it, choosing nothing, rather than turning a
237
+ // resting pointer or a scroll under it into a drag that the next click anywhere would finish.
238
+ if (event.pointerType !== "touch" && event.buttons === 0)
239
+ return end(event, false);
240
+ s.samples.push([event.timeStamp, event.clientX]);
241
+ if (s.samples.length > 8)
242
+ s.samples.shift();
243
+ if (!s.moved) {
244
+ if (Math.abs(event.clientX - s.startX) < DRAG_FROM)
245
+ return;
246
+ s.moved = true;
247
+ list.setPointerCapture(event.pointerId);
248
+ s.grow = capsule ? SWELL.capsule : SWELL.bar;
249
+ if (!active)
250
+ start(s, true);
251
+ else
252
+ setLifted(true);
253
+ }
254
+ const box = list.getBoundingClientRect();
255
+ const ends = [s.tiles[0].centre, s.tiles.at(-1).centre];
256
+ const [first, last] = [Math.min(...ends), Math.max(...ends)];
257
+ const x = event.clientX - box.left - list.clientLeft;
258
+ // Past either end it gives a little, harder the further it goes.
259
+ const band = (over) => (over * 18) / (over + 30);
260
+ s.target = x < first ? first - band(first - x) : x > last ? last + band(x - last) : x;
261
+ const next = nearest(s, s.target);
262
+ if (next !== s.under) {
263
+ s.under = next;
264
+ setUnder(next);
265
+ navigator.vibrate?.(5);
266
+ }
267
+ };
268
+ const end = (event, choose) => {
269
+ const s = state.current;
270
+ if (!s || s.pointer !== event.pointerId || s.releasing)
271
+ return;
272
+ if (!s.moved) {
273
+ // A tap. On the current item the lens, which rose, sinks back. On another it travels there
274
+ // as liquid, stretching on the way with a little lift, and the click chooses the item.
275
+ if (!active) {
276
+ const current = items().findIndex(isCurrent);
277
+ if (!choose || current < 0 || current === s.from || reducedMotion()) {
278
+ state.current = null;
279
+ return;
280
+ }
281
+ s.x = s.tiles[current].centre;
282
+ s.target = s.tiles[s.from].centre;
283
+ s.sv = capsule ? 2.6 : 4;
284
+ s.releasing = true;
285
+ start(s, false);
286
+ return;
287
+ }
288
+ s.releasing = true;
289
+ s.grow = 1;
290
+ // It sets down as it shrinks: the lift eases out from the release, with the spring, rather
291
+ // than waiting for the spring to finish and then dropping as a second step.
292
+ setLifted(false);
293
+ return;
294
+ }
295
+ // The release is not a tap on whatever it ended over: only the item under the lens is chosen.
296
+ swallowClick.current = true;
297
+ setTimeout(() => (swallowClick.current = false), 0);
298
+ const all = items();
299
+ const current = all.findIndex(isCurrent);
300
+ // Let go while moving, it chooses where the finger was heading: a flick carries on to the
301
+ // next item, as the lens itself carries on with its speed.
302
+ const heading = nearest(s, s.target + fingerSpeed(s.samples, event.timeStamp) * PROJECT);
303
+ const pick = choose ? heading : current >= 0 ? current : s.from;
304
+ s.target = s.tiles[pick].centre;
305
+ s.grow = 1;
306
+ s.releasing = true;
307
+ setLifted(false);
308
+ setUnder(null);
309
+ const target = all[pick];
310
+ if (choose && target && !isCurrent(target))
311
+ target.click();
312
+ };
313
+ endRef.current = end;
314
+ const handlers = {
315
+ onPointerDown,
316
+ onPointerMove,
317
+ onPointerUp: (event) => end(event, true),
318
+ onPointerCancel: (event) => end(event, false),
319
+ onClickCapture: (event) => {
320
+ if (swallowClick.current && event.nativeEvent.isTrusted) {
321
+ event.preventDefault();
322
+ event.stopPropagation();
323
+ }
324
+ },
325
+ };
326
+ return [active, lifted, handlers];
327
+ }
@@ -7,7 +7,7 @@ description: Build interfaces with the zon design system (@zonsh/ui) — Base UI
7
7
 
8
8
  The zon component library: React 19 + Base UI 1.x + Tailwind v4, styled in the
9
9
  zon material (layered primary, raised secondary, recessed fields, hairline structure).
10
- Version 0.7.1. 124 components.
10
+ Version 0.8.0. 124 components.
11
11
 
12
12
  > **Building a landing page, marketing site, waitlist, shop front or product page?** Read
13
13
  > `references/marketing.md` first. It has the hero variants, a library of section patterns
@@ -128,7 +128,7 @@ If no one can answer (you run unattended), don't fall back to the default silent
128
128
  | [Avatar](references/components/avatar.md) | `Avatar`, `AvatarGroup` | A round picture of a person, with initials when there is no image. Also known as: profile picture, user image. |
129
129
  | [Badge](references/components/badge.md) | `Badge`, `BadgeAnchor` | A small count or status mark pinned to the corner of an icon button or avatar. Also known as: notification count, counter, status dot, presence indicator, new marker. |
130
130
  | [Breadcrumb](references/components/breadcrumb.md) | `Breadcrumb` | A trail of links showing where the page sits in the site. Also known as: breadcrumbs, path. |
131
- | [Button](references/components/button.md) | `Button` | The layered primary and raised secondary actions, in three sizes and as round icon buttons. |
131
+ | [Button](references/components/button.md) | `Button`, `usePressFeedback` | The layered primary and raised secondary actions, in three sizes and as round icon buttons. |
132
132
  | [Button Group](references/components/button-group.md) | `ButtonGroup`, `ButtonGroupSeparator` | Joins related buttons, selects and inputs edge to edge, in a row or a column. Also known as: segmented buttons, split button. |
133
133
  | [Calendar](references/components/calendar.md) | `Calendar` | A month grid for picking a date, several dates or a range. Also known as: date grid, month view, day picker. |
134
134
  | [Cards](references/components/card.md) | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Groups content as a card, a square region of the page, or a plain hairline section. Also known as: panel, tile, box, surface, region, feature card. |
@@ -175,7 +175,7 @@ If no one can answer (you run unattended), don't fall back to the default silent
175
175
  | [Popover](references/components/popover.md) | `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverTitle`, `PopoverDescription`, `PopoverClose` | A small panel anchored to a control. Also known as: flyout, dropdown panel. |
176
176
  | [Preview Card](references/components/preview-card.md) | `PreviewCard`, `PreviewCardTrigger`, `PreviewCardContent` | A card that previews what a link points to, on hover or focus. Also known as: hover card, link preview. |
177
177
  | [Progress](references/components/progress.md) | `Progress` | A bar showing how far along a task is, or that it is still working. Also known as: progress bar, loading bar. |
178
- | [Radio Group](references/components/radio-group.md) | `RadioGroup`, `Radio` | Pick exactly one option from a short, visible list. Also known as: radio buttons, option group. |
178
+ | [Radio Group](references/components/radio-group.md) | `RadioGroup`, `Radio` | Pick exactly one option from a short, visible list. Also known as: radio buttons, option group, segmented control, capsule, answer row, segmented picker. |
179
179
  | [Rating](references/components/rating.md) | `Rating` | A row of stars to give or show a score out of five. Also known as: stars, star rating, review score, score, rate. |
180
180
  | [Resizable](references/components/resizable.md) | `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle` | Split panes the user can resize by dragging the divider. Also known as: split pane, splitter, panels. |
181
181
  | [Scheduler](references/components/scheduler.md) | `Scheduler` | Tasks, bookings and events in time — a Gantt chart with dependencies and milestones, a resource timeline of people and rooms whose bookings stack in lanes, or a calendar with days across and hours down (Day, Work week, Week) or a Month of weeks, where overlapping events sit side by side — with drag to move, resize and draw, snapping, and full keyboard control. Also known as: gantt, gantt chart, gantt editor, dependencies, event editor, booking editor, resource timeline, timeline view, schedule, booking calendar, room booking, project plan, roadmap, planner, capacity planning, shift plan, calendar, week view, day view, month view, work week, time grid, agenda, event calendar, team calendar, google calendar, outlook calendar. |
@@ -267,6 +267,25 @@ export function AsLink() {
267
267
  }
268
268
  ```
269
269
 
270
+ ### Press feedback on a phone
271
+
272
+ A phone shows a button's `:active` state late, or only once it is sure the touch is not a scroll, so a tap can feel unanswered. The phone parts (`AppBar`, `BottomNav`, `ActionSheet`, `SwipeActions`, `PullToRefresh`) answer at touch-down instead. A screen without them does the same with `usePressFeedback()`: called once while the screen is mounted, it presses whatever carries `data-press` the moment a finger lands. The button sinks, gives a little (97%), and lets go if the finger moves to scroll.
273
+
274
+ ```tsx
275
+ import { Button, usePressFeedback } from "@zonsh/ui";
276
+
277
+ function SignIn() {
278
+ usePressFeedback();
279
+ return (
280
+ <Button data-press type="submit">
281
+ Sign in
282
+ </Button>
283
+ );
284
+ }
285
+ ```
286
+
287
+ Mark rows and cards the same way, with `press-shade` for a flat surface. A button inside a pressed row presses itself, not the row, and text fields never press. Under reduced motion the shade stays and the shrink is dropped.
288
+
270
289
  ## Props
271
290
 
272
291
  | Prop | Type | Default |
@@ -304,6 +323,6 @@ A button is never wider than its container: its text (one `button-text` span) en
304
323
 
305
324
  ---
306
325
 
307
- - Import: `import { Button } from "@zonsh/ui"`
326
+ - Import: `import { Button, usePressFeedback } from "@zonsh/ui"`
308
327
  - Source: `packages/ui/src/components/button.tsx`
309
328
  - Primitive: `@base-ui/react/button` (Base UI docs: `node_modules/@base-ui/react/docs/react/components/button.md`)
@@ -63,7 +63,8 @@ The props you'll reach for: `defaultValue` (or `value` / `onValueChange`) on the
63
63
  ## When to use
64
64
 
65
65
  - One of 2–7 options that each need a sentence or description.
66
- - 2–5 short labels compared side by side: `ToggleGroup`.
66
+ - 2–5 short options chosen side by side, often and fast (an answer to a check, a view, a period): `variant="capsule"`.
67
+ - 2–5 short labels that switch a toolbar or a view's setting: `ToggleGroup`.
67
68
  - Long lists: `Select`, or `Combobox` when typing helps.
68
69
 
69
70
  ## Examples
@@ -182,9 +183,76 @@ export function States() {
182
183
  }
183
184
  ```
184
185
 
186
+ ### Capsule
187
+
188
+ `variant="capsule"` sets the options side by side in a capsule on the field's track, the chosen one on a raised pill. The pill glides to the next choice; pressed, it swells, and dragged it follows the finger as a lens and chooses the option it is let go over, as a capsule `BottomNav`. It is still a radio group: one Tab stop, arrow keys, a form value and `required`. Nothing is chosen until someone picks, so a checklist starts unanswered. Each `Radio` holds an icon, a word or both; an icon alone needs an `aria-label`. Name the group with `aria-labelledby` or `aria-label`.
189
+
190
+ ```tsx
191
+ import { CheckIcon, MinusIcon, XIcon } from "lucide-react";
192
+ import { Radio, RadioGroup } from "@zonsh/ui";
193
+
194
+ const checks = [
195
+ { id: "extinguisher", label: "Fire extinguisher in place" },
196
+ { id: "exit", label: "Emergency exit clear" },
197
+ { id: "first-aid", label: "First-aid kit stocked" },
198
+ ];
199
+
200
+ export function Capsule() {
201
+ return (
202
+ <div className="w-full max-w-md divide-y divide-border/(--hairline-opacity)">
203
+ {checks.map((check) => (
204
+ <div key={check.id} className="flex items-center justify-between gap-4 py-3">
205
+ <span id={`check-${check.id}`} className="min-w-0 font-body text-sm">
206
+ {check.label}
207
+ </span>
208
+ {/* Nothing chosen until someone answers. */}
209
+ <RadioGroup variant="capsule" name={check.id} aria-labelledby={`check-${check.id}`}>
210
+ <Radio value="ok" aria-label="OK">
211
+ <CheckIcon />
212
+ </Radio>
213
+ <Radio value="defect" aria-label="Defect">
214
+ <XIcon />
215
+ </Radio>
216
+ <Radio value="na" aria-label="Not applicable">
217
+ <MinusIcon />
218
+ </Radio>
219
+ </RadioGroup>
220
+ </div>
221
+ ))}
222
+ </div>
223
+ );
224
+ }
225
+ ```
226
+
227
+ `size` sets its height, 30, 38 or 46px. The options share its width equally, each as wide as the widest.
228
+
229
+ ```tsx
230
+ import { Radio, RadioGroup } from "@zonsh/ui";
231
+
232
+ export function CapsuleSizes() {
233
+ return (
234
+ <div className="flex flex-col items-start gap-4">
235
+ {(["sm", "default", "lg"] as const).map((size) => (
236
+ <RadioGroup
237
+ key={size}
238
+ variant="capsule"
239
+ size={size}
240
+ defaultValue="week"
241
+ aria-label={`Period, ${size}`}
242
+ >
243
+ <Radio value="day">Day</Radio>
244
+ <Radio value="week">Week</Radio>
245
+ <Radio value="month">Month</Radio>
246
+ </RadioGroup>
247
+ ))}
248
+ </div>
249
+ );
250
+ }
251
+ ```
252
+
185
253
  ## Props
186
254
 
187
- `RadioGroup`: `value`, `defaultValue`, `onValueChange`, `name`, `required`, `disabled`, `readOnly`. `Radio`: `value` (required), `disabled`, `readOnly`. The group stacks its options with a 12px gap. Other Base UI props are forwarded. Data attributes: `data-checked`, `data-unchecked`, `data-disabled`, `data-invalid`.
255
+ `RadioGroup`: `value`, `defaultValue`, `onValueChange`, `name`, `required`, `disabled`, `readOnly`, `variant` (`"default"` or `"capsule"`) and, in a capsule, `size` (`"sm"`, `"default"`, `"lg"`). `Radio`: `value` (required), `disabled`, `readOnly`. The group stacks its options with a 12px gap; a capsule lines them up in a row. A capsule's `RadioGroup` carries `data-variant="capsule"`, `data-size` and `data-dragging` while its pill is held; its `Radio`s `data-variant="capsule"`, and `data-under` for the one under the lens. Other Base UI props are forwarded. Data attributes: `data-checked`, `data-unchecked`, `data-disabled`, `data-invalid`.
188
256
 
189
257
  ## Brand rules
190
258
 
@@ -192,10 +260,13 @@ export function States() {
192
260
  - **Do** write parallel options that are easy to scan.
193
261
  - **Don't** lay radios out in a row when the labels wrap. Use a column.
194
262
  - **Don't** use radios for actions. Choosing one never submits anything.
263
+ - **Do** keep a capsule's options short and alike: an icon, or a word or two each, no more than five.
264
+ - **Don't** use a capsule to move between pages: that is `BottomNav` or `Tabs`.
195
265
 
196
266
  ## Accessibility
197
267
 
198
268
  - The legend names the group (`Fieldset` + `FieldsetLegend`); each option keeps a visible label.
269
+ - A capsule is a radio group like any other: the chosen option is read as checked, never as the current page. Its segments are at least 44px to touch on a touch screen, and dragging is never the only way: a tap or the arrow keys choose too.
199
270
  - The wrapping `FieldLabel` is the touch target: the whole line chooses the option, not just the 18px radio.
200
271
  - Errors show a destructive border and ring on each radio, plus a `FieldError` message.
201
272
 
@@ -45,7 +45,7 @@ Changed `storageKey`, `defaultTheme` or `themeColor`? Build the script with the
45
45
 
46
46
  ### In a Vite app's index.html
47
47
 
48
- `zonThemeScript()` from `@zonsh/ui/vite` puts the script atop `<head>`, right after `<meta charset>`, in every page (options as `createThemeScript`).
48
+ `zonThemeScript()` from `@zonsh/ui/vite` puts the script atop `<head>`, right after `<meta charset>`, in every page (options as `createThemeScript`). In a build it also preloads the Licht faces nearly every page sets (Licht Light, Licht Sans Regular and Medium, Licht Mono Regular) by their built names, so the first paint is in Licht rather than a fallback; `preloadFonts` takes other cuts by file name (`["LichtSans-SemiBold"]`) or `false`.
49
49
 
50
50
  ```ts
51
51
  // vite.config.ts
@@ -340,7 +340,7 @@ export function Chooser() {
340
340
 
341
341
  **ThemeToggle** forwards `Button` props but `variant` and `children`; `size` `"default"` (36px) or `"sm"` (30px); `onClick` runs first.
342
342
 
343
- **zonThemeScript(options)** (from `@zonsh/ui/vite`) — the Vite plugin: `storageKey`, `defaultTheme` and `themeColor` as `createThemeScript`, and `preset`, whose stylesheet it writes into `index.html` for the first paint.
343
+ **zonThemeScript(options)** (from `@zonsh/ui/vite`) — the Vite plugin: `storageKey`, `defaultTheme` and `themeColor` as `createThemeScript`, `preset`, whose stylesheet it writes into `index.html` for the first paint, and `preloadFonts` (default `true`: the four common Licht cuts; a list of cut names, or `false`), preload links to the built font files.
344
344
 
345
345
  **themeScript** — the minified script for the defaults; **createThemeScript(options)** for others (options escaped, so `</script>` cannot break out). **THEME_STORAGE_KEY** is `"zon-theme"`; **PAGE_TONE** `{ light: "#f9f9f9", dark: "#141414" }`. The toggle's name is `messages.theme.toggle`.
346
346
 
@@ -12,9 +12,12 @@
12
12
  @source "../components/tooltip.js";
13
13
  @source "../lib/cn.js";
14
14
  @source "../lib/collapse-row.js";
15
+ @source "../lib/gesture.js";
15
16
  @source "../lib/icons.js";
16
17
  @source "../lib/logo-geometry.js";
17
18
  @source "../lib/merge-refs.js";
19
+ @source "../lib/motion.js";
18
20
  @source "../lib/platform.js";
19
21
  @source "../lib/portal-container.js";
22
+ @source "../lib/press.js";
20
23
  @source "../lib/room.js";
@@ -5,5 +5,6 @@
5
5
  @source "../lib/cn.js";
6
6
  @source "../lib/gesture.js";
7
7
  @source "../lib/glide.js";
8
+ @source "../lib/liquid-mark.js";
8
9
  @source "../lib/motion.js";
9
10
  @source "../lib/press.js";
@@ -4,6 +4,9 @@
4
4
  @source "../components/spinner.js";
5
5
  @source "../lib/cn.js";
6
6
  @source "../lib/collapse-row.js";
7
+ @source "../lib/gesture.js";
7
8
  @source "../lib/icons.js";
8
9
  @source "../lib/logo-geometry.js";
9
10
  @source "../lib/merge-refs.js";
11
+ @source "../lib/motion.js";
12
+ @source "../lib/press.js";
@@ -6,6 +6,9 @@
6
6
  @source "../components/spinner.js";
7
7
  @source "../lib/cn.js";
8
8
  @source "../lib/collapse-row.js";
9
+ @source "../lib/gesture.js";
9
10
  @source "../lib/icons.js";
10
11
  @source "../lib/logo-geometry.js";
11
12
  @source "../lib/merge-refs.js";
13
+ @source "../lib/motion.js";
14
+ @source "../lib/press.js";
@@ -8,6 +8,9 @@
8
8
  @source "../lib/code-highlight.js";
9
9
  @source "../lib/code-theme.js";
10
10
  @source "../lib/collapse-row.js";
11
+ @source "../lib/gesture.js";
11
12
  @source "../lib/icons.js";
12
13
  @source "../lib/logo-geometry.js";
13
14
  @source "../lib/merge-refs.js";
15
+ @source "../lib/motion.js";
16
+ @source "../lib/press.js";
@@ -5,6 +5,9 @@
5
5
  @source "../components/spinner.js";
6
6
  @source "../lib/cn.js";
7
7
  @source "../lib/collapse-row.js";
8
+ @source "../lib/gesture.js";
8
9
  @source "../lib/icons.js";
9
10
  @source "../lib/logo-geometry.js";
10
11
  @source "../lib/merge-refs.js";
12
+ @source "../lib/motion.js";
13
+ @source "../lib/press.js";
@@ -5,6 +5,9 @@
5
5
  @source "../components/spinner.js";
6
6
  @source "../lib/cn.js";
7
7
  @source "../lib/collapse-row.js";
8
+ @source "../lib/gesture.js";
8
9
  @source "../lib/icons.js";
9
10
  @source "../lib/logo-geometry.js";
10
11
  @source "../lib/merge-refs.js";
12
+ @source "../lib/motion.js";
13
+ @source "../lib/press.js";
@@ -16,12 +16,14 @@
16
16
  @source "../lib/cn.js";
17
17
  @source "../lib/collapse-row.js";
18
18
  @source "../lib/form-reset.js";
19
+ @source "../lib/gesture.js";
19
20
  @source "../lib/icons.js";
20
21
  @source "../lib/logo-geometry.js";
21
22
  @source "../lib/merge-refs.js";
22
23
  @source "../lib/motion.js";
23
24
  @source "../lib/platform.js";
24
25
  @source "../lib/portal-container.js";
26
+ @source "../lib/press.js";
25
27
  @source "../lib/room.js";
26
28
  @source "../lib/row-index.js";
27
29
  @source "../lib/table-fit.js";
@@ -9,7 +9,10 @@
9
9
  @source "../lib/cn.js";
10
10
  @source "../lib/collapse-row.js";
11
11
  @source "../lib/files.js";
12
+ @source "../lib/gesture.js";
12
13
  @source "../lib/icons.js";
13
14
  @source "../lib/logo-geometry.js";
14
15
  @source "../lib/merge-refs.js";
16
+ @source "../lib/motion.js";
15
17
  @source "../lib/platform.js";
18
+ @source "../lib/press.js";
@@ -20,6 +20,7 @@
20
20
  @source "../lib/collapse-row.js";
21
21
  @source "../lib/digit-roll.js";
22
22
  @source "../lib/form-reset.js";
23
+ @source "../lib/gesture.js";
23
24
  @source "../lib/icons.js";
24
25
  @source "../lib/logo-geometry.js";
25
26
  @source "../lib/merge-refs.js";
@@ -27,4 +28,5 @@
27
28
  @source "../lib/number-roll.js";
28
29
  @source "../lib/platform.js";
29
30
  @source "../lib/portal-container.js";
31
+ @source "../lib/press.js";
30
32
  @source "../lib/room.js";
@@ -24,10 +24,12 @@
24
24
  @source "../lib/code-theme.js";
25
25
  @source "../lib/collapse-row.js";
26
26
  @source "../lib/files.js";
27
+ @source "../lib/gesture.js";
27
28
  @source "../lib/icons.js";
28
29
  @source "../lib/logo-geometry.js";
29
30
  @source "../lib/merge-refs.js";
30
31
  @source "../lib/motion.js";
31
32
  @source "../lib/platform.js";
32
33
  @source "../lib/portal-container.js";
34
+ @source "../lib/press.js";
33
35
  @source "../lib/room.js";