@ignite-ember/ui-react 0.2.0 → 0.2.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 (127) hide show
  1. package/NOTICE +1 -1
  2. package/README.md +56 -13
  3. package/dist/CopySource.d.ts.map +1 -1
  4. package/dist/CopySource.js +16 -2
  5. package/dist/CopySource.js.map +1 -1
  6. package/dist/DataTable.d.ts +17 -1
  7. package/dist/DataTable.d.ts.map +1 -1
  8. package/dist/DataTable.js +17 -1
  9. package/dist/DataTable.js.map +1 -1
  10. package/dist/Dialog.d.ts +41 -0
  11. package/dist/Dialog.d.ts.map +1 -0
  12. package/dist/Dialog.js +94 -0
  13. package/dist/Dialog.js.map +1 -0
  14. package/dist/ErrorBoundary.d.ts +31 -2
  15. package/dist/ErrorBoundary.d.ts.map +1 -1
  16. package/dist/ErrorBoundary.js +38 -4
  17. package/dist/ErrorBoundary.js.map +1 -1
  18. package/dist/LiveRegion.d.ts +7 -1
  19. package/dist/LiveRegion.d.ts.map +1 -1
  20. package/dist/LiveRegion.js +7 -1
  21. package/dist/LiveRegion.js.map +1 -1
  22. package/dist/Markdown.d.ts +4 -0
  23. package/dist/Markdown.d.ts.map +1 -1
  24. package/dist/Markdown.js +4 -0
  25. package/dist/Markdown.js.map +1 -1
  26. package/dist/MarkdownInline.d.ts +13 -4
  27. package/dist/MarkdownInline.d.ts.map +1 -1
  28. package/dist/MarkdownInline.js +20 -5
  29. package/dist/MarkdownInline.js.map +1 -1
  30. package/dist/MenuIcon.d.ts +10 -4
  31. package/dist/MenuIcon.d.ts.map +1 -1
  32. package/dist/MenuIcon.js +8 -2
  33. package/dist/MenuIcon.js.map +1 -1
  34. package/dist/Mermaid.d.ts +2 -0
  35. package/dist/Mermaid.d.ts.map +1 -1
  36. package/dist/Mermaid.js +2 -0
  37. package/dist/Mermaid.js.map +1 -1
  38. package/dist/Monogram.d.ts +7 -3
  39. package/dist/Monogram.d.ts.map +1 -1
  40. package/dist/Monogram.js +14 -6
  41. package/dist/Monogram.js.map +1 -1
  42. package/dist/OverflowMenu.d.ts +6 -1
  43. package/dist/OverflowMenu.d.ts.map +1 -1
  44. package/dist/OverflowMenu.js +10 -2
  45. package/dist/OverflowMenu.js.map +1 -1
  46. package/dist/Shell.d.ts +13 -0
  47. package/dist/Shell.d.ts.map +1 -1
  48. package/dist/Shell.js +13 -0
  49. package/dist/Shell.js.map +1 -1
  50. package/dist/Skeleton.d.ts +30 -0
  51. package/dist/Skeleton.d.ts.map +1 -1
  52. package/dist/Skeleton.js +30 -0
  53. package/dist/Skeleton.js.map +1 -1
  54. package/dist/Split.d.ts +24 -5
  55. package/dist/Split.d.ts.map +1 -1
  56. package/dist/Split.js +27 -4
  57. package/dist/Split.js.map +1 -1
  58. package/dist/Tabs.d.ts +77 -0
  59. package/dist/Tabs.d.ts.map +1 -0
  60. package/dist/Tabs.js +91 -0
  61. package/dist/Tabs.js.map +1 -0
  62. package/dist/Toast.d.ts +12 -1
  63. package/dist/Toast.d.ts.map +1 -1
  64. package/dist/Toast.js +11 -0
  65. package/dist/Toast.js.map +1 -1
  66. package/dist/Tooltip.d.ts +12 -3
  67. package/dist/Tooltip.d.ts.map +1 -1
  68. package/dist/Tooltip.js +29 -7
  69. package/dist/Tooltip.js.map +1 -1
  70. package/dist/controls.d.ts +117 -0
  71. package/dist/controls.d.ts.map +1 -0
  72. package/dist/controls.js +59 -0
  73. package/dist/controls.js.map +1 -0
  74. package/dist/fenceInfo.d.ts +4 -1
  75. package/dist/fenceInfo.d.ts.map +1 -1
  76. package/dist/fenceInfo.js +4 -1
  77. package/dist/fenceInfo.js.map +1 -1
  78. package/dist/formControls.d.ts +143 -0
  79. package/dist/formControls.d.ts.map +1 -0
  80. package/dist/formControls.js +108 -0
  81. package/dist/formControls.js.map +1 -0
  82. package/dist/index.d.ts +5 -9
  83. package/dist/index.d.ts.map +1 -1
  84. package/dist/index.js +5 -9
  85. package/dist/index.js.map +1 -1
  86. package/dist/layout.d.ts +95 -0
  87. package/dist/layout.d.ts.map +1 -0
  88. package/dist/layout.js +93 -0
  89. package/dist/layout.js.map +1 -0
  90. package/dist/primitives.d.ts +10 -360
  91. package/dist/primitives.d.ts.map +1 -1
  92. package/dist/primitives.js +31 -338
  93. package/dist/primitives.js.map +1 -1
  94. package/dist/progress.d.ts +64 -0
  95. package/dist/progress.d.ts.map +1 -0
  96. package/dist/progress.js +51 -0
  97. package/dist/progress.js.map +1 -0
  98. package/dist/text.d.ts +63 -0
  99. package/dist/text.d.ts.map +1 -0
  100. package/dist/text.js +61 -0
  101. package/dist/text.js.map +1 -0
  102. package/package.json +4 -4
  103. package/src/CopySource.tsx +17 -2
  104. package/src/DataTable.tsx +17 -1
  105. package/src/Dialog.tsx +158 -0
  106. package/src/ErrorBoundary.tsx +39 -4
  107. package/src/LiveRegion.tsx +7 -1
  108. package/src/Markdown.tsx +4 -0
  109. package/src/MarkdownInline.tsx +20 -7
  110. package/src/MenuIcon.tsx +10 -4
  111. package/src/Mermaid.tsx +2 -0
  112. package/src/Monogram.tsx +14 -5
  113. package/src/OverflowMenu.tsx +9 -2
  114. package/src/Shell.tsx +13 -0
  115. package/src/Skeleton.tsx +30 -0
  116. package/src/Split.tsx +32 -7
  117. package/src/Tabs.tsx +194 -0
  118. package/src/Toast.tsx +12 -1
  119. package/src/Tooltip.tsx +33 -8
  120. package/src/controls.tsx +159 -0
  121. package/src/fenceInfo.ts +5 -2
  122. package/src/formControls.tsx +249 -0
  123. package/src/index.ts +5 -9
  124. package/src/layout.tsx +141 -0
  125. package/src/primitives.tsx +10 -864
  126. package/src/progress.tsx +129 -0
  127. package/src/text.tsx +99 -0
@@ -17,871 +17,17 @@
17
17
  * `Dialog` is the exception and says so at its own definition — a
18
18
  * dialog is behaviour, not just a box.
19
19
  *
20
+ * This module is the one name the primitives are imported by. Each
21
+ * group lives in its own file, re-exported here in reading order.
22
+ *
20
23
  * **Under the compatibility floor.** A prop here is a promise; see
21
24
  * EXTENSIBILITY.md §8.
22
25
  */
23
26
 
24
- import type {
25
- ButtonHTMLAttributes,
26
- HTMLAttributes,
27
- InputHTMLAttributes,
28
- ReactElement,
29
- ReactNode,
30
- SelectHTMLAttributes,
31
- TextareaHTMLAttributes,
32
- } from "react";
33
- import {
34
- cloneElement,
35
- isValidElement,
36
- useCallback,
37
- useEffect,
38
- useId,
39
- useRef,
40
- } from "react";
41
-
42
- /** Joins class names, skipping anything falsy. */
43
- function cx(...parts: (string | false | null | undefined)[]): string {
44
- return parts.filter(Boolean).join(" ");
45
- }
46
-
47
- // ── Controls ────────────────────────────────────────────────────────
48
-
49
- /**
50
- * How a button reads.
51
- *
52
- * `default` is a plain button, `primary` is the one action on the
53
- * panel, `danger` is the one that destroys something, `warn` says the
54
- * action is not what it sounds like, and `quiet` is a button that
55
- * should not be the first thing the eye lands on.
56
- */
57
- export type ButtonVariant = "default" | "primary" | "danger" | "warn" | "quiet";
58
-
59
- /** `md` unless the row is dense, in which case `sm` or `xs`. */
60
- export type ButtonSize = "md" | "sm" | "xs";
61
-
62
- /** What a {@link Button} takes. */
63
- export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
64
- /** How it reads. */
65
- variant?: ButtonVariant;
66
- /** Its size. */
67
- size?: ButtonSize;
68
- }
69
-
70
- /**
71
- * A button.
72
- *
73
- * The variant is a prop rather than a class name you spell:
74
- * `btn-primery` is a typo that renders as a plain button and looks
75
- * like nothing at all, which is exactly why the name is one the
76
- * compiler checks.
77
- */
78
- export function Button({
79
- variant = "default",
80
- size = "md",
81
- className,
82
- ...rest
83
- }: ButtonProps) {
84
- return (
85
- <button
86
- type="button"
87
- {...rest}
88
- className={cx(
89
- "btn",
90
- variant !== "default" && `btn-${variant}`,
91
- size !== "md" && `btn-${size}`,
92
- className,
93
- )}
94
- />
95
- );
96
- }
97
-
98
- /** What an {@link Input} takes. */
99
- export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {}
100
-
101
- /** A single-line text field. */
102
- export function Input({ className, ...rest }: InputProps) {
103
- return <input {...rest} className={cx("panel-input", className)} />;
104
- }
105
-
106
- /**
107
- * How loud a status is.
108
- *
109
- * `neutral` for a state nothing is wrong with, and the three that
110
- * mean something.
111
- */
112
- export type Tone = "neutral" | "success" | "warning" | "danger";
113
-
114
- /**
115
- * A tag the reader can scan past.
116
- *
117
- * Bordered, pill-shaped, muted, `--text-sm`. Use it for a filter, a
118
- * label, a piece of metadata — something that describes the row it
119
- * sits on.
120
- *
121
- * `Chip` and `Badge` take the same props and are not
122
- * interchangeable. If the thing you are showing is a *state* that
123
- * changes — ready, failed, three unread — it is a {@link Badge},
124
- * which is filled by tone and bold so it is noticed. If it is a fact
125
- * about the thing, it is a `Chip`.
126
- */
127
- export interface ChipProps extends HTMLAttributes<HTMLSpanElement> {
128
- /** How loud it is. */
129
- tone?: Tone;
130
- }
131
-
132
- /**
133
- * A tag the reader can scan past. See {@link ChipProps} for when to
134
- * reach for a chip and when for a badge.
135
- */
136
- export function Chip({ tone = "neutral", className, ...rest }: ChipProps) {
137
- return <span {...rest} data-tone={tone} className={cx("chip", className)} />;
138
- }
139
-
140
- /**
141
- * A state the reader is meant to notice.
142
- *
143
- * Filled by tone, bold, `--text-xs`, no border. See {@link ChipProps}
144
- * for which of the two to reach for.
145
- *
146
- * The tone is colour, and colour alone is not a message: put the
147
- * state in the text too. "Failed" in a danger badge survives being
148
- * read aloud and being looked at by somebody who cannot tell it from
149
- * the success one; an empty red badge does not.
150
- */
151
- export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
152
- /** How loud it is. */
153
- tone?: Tone;
154
- }
155
-
156
- /**
157
- * A state the reader is meant to notice. See {@link BadgeProps} for
158
- * what the tone does and does not say.
159
- */
160
- export function Badge({ tone = "neutral", className, ...rest }: BadgeProps) {
161
- return (
162
- <span {...rest} data-tone={tone} className={cx("ui-badge", className)} />
163
- );
164
- }
165
-
166
- // ── Layout ──────────────────────────────────────────────────────────
167
-
168
- /** A horizontal run of things, vertically centred. */
169
- export function Row({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
170
- return <div {...rest} className={cx("ui-row", className)} />;
171
- }
172
-
173
- /** A horizontal run of buttons. Separate from `Row` because it is
174
- * what a reader looks for at the foot of a panel. */
175
- export function Actions({
176
- className,
177
- ...rest
178
- }: HTMLAttributes<HTMLDivElement>) {
179
- return <div {...rest} className={cx("ui-actions", className)} />;
180
- }
181
-
182
- /** A vertical stack. */
183
- export function List({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
184
- return <div {...rest} className={cx("ui-list", className)} />;
185
- }
186
-
187
- /**
188
- * A row of controls at the top of a panel: what the panel is, and what
189
- * you can do to it.
190
- */
191
- export function Toolbar({
192
- className,
193
- ...rest
194
- }: HTMLAttributes<HTMLDivElement>) {
195
- return <div {...rest} className={cx("ui-toolbar", className)} />;
196
- }
197
-
198
- // ── Containers ──────────────────────────────────────────────────────
199
-
200
- /** A surface: background, border, radius, padding. */
201
- export function Card({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
202
- return <div {...rest} className={cx("ui-card", className)} />;
203
- }
204
-
205
- /** One selectable row inside a list. Renders a button, because
206
- * something clickable that is not a button is a keyboard trap. */
207
- export function Item({
208
- className,
209
- ...rest
210
- }: ButtonHTMLAttributes<HTMLButtonElement>) {
211
- return (
212
- <button type="button" {...rest} className={cx("ui-item", className)} />
213
- );
214
- }
215
-
216
- /**
217
- * A table.
218
- *
219
- * The class only; the head, the rows and the cells are yours, because
220
- * a table that decides its own columns is a table you cannot use for
221
- * anything the app has not already seen.
222
- */
223
- export function Table({
224
- className,
225
- ...rest
226
- }: HTMLAttributes<HTMLTableElement>) {
227
- return <table {...rest} className={cx("ui-table", className)} />;
228
- }
229
-
230
- /**
231
- * What to show where there is nothing.
232
- *
233
- * Its own component rather than a paragraph with a class, because an
234
- * empty state that says only "nothing here" is the commonest way a
235
- * panel wastes the one moment it had the reader's attention. The
236
- * `action` slot is a nudge to say what to do next.
237
- */
238
- export interface EmptyProps extends HTMLAttributes<HTMLDivElement> {
239
- /** A button, usually: the one thing to do about being empty. */
240
- action?: ReactNode;
241
- }
242
-
243
- /**
244
- * What to show where there is nothing.
245
- *
246
- * See {@link EmptyProps} for why the `action` slot exists.
247
- */
248
- export function Empty({ children, action, className, ...rest }: EmptyProps) {
249
- return (
250
- <div {...rest} className={cx("ui-empty", className)}>
251
- {children}
252
- {action}
253
- </div>
254
- );
255
- }
256
-
257
- // ── Dialog ──────────────────────────────────────────────────────────
258
-
259
- /** What a {@link Dialog} takes. */
260
- export interface DialogProps extends Omit<
261
- HTMLAttributes<HTMLDivElement>,
262
- "title"
263
- > {
264
- /** Its title. Also the accessible name of the dialog. */
265
- title: ReactNode;
266
- /** Shown under the title. A sentence, not a paragraph. */
267
- sub?: ReactNode;
268
- /** The body. */
269
- children?: ReactNode;
270
- /** The buttons. Rendered in an `Actions` row at the foot. */
271
- actions?: ReactNode;
272
- /** Escape, or a click on the backdrop. */
273
- onClose: () => void;
274
- }
275
-
276
- /**
277
- * The one primitive here that is behaviour rather than a box.
278
- *
279
- * A dialog has to trap focus, close on Escape, restore focus to
280
- * whatever opened it, and not let a click inside the panel count as a
281
- * click on the backdrop. Every extension that built its own would get
282
- * some of that wrong, and the ones they get wrong are the ones only
283
- * keyboard and screen-reader users notice.
284
- */
285
- export function Dialog({
286
- title,
287
- sub,
288
- children,
289
- actions,
290
- onClose,
291
- className,
292
- ...rest
293
- }: DialogProps) {
294
- const panel = useRef<HTMLDivElement | null>(null);
295
- const opener = useRef<Element | null>(null);
296
- const titleId = useId();
297
-
298
- useEffect(() => {
299
- opener.current = document.activeElement;
300
- // Focus the panel itself rather than the first control: reading
301
- // the title before the buttons is the point of having one.
302
- panel.current?.focus();
303
- return () => {
304
- // Only if it is still in the document: an opener that has
305
- // unmounted drops focus to <body> silently, which is worse than
306
- // leaving it where the closing action put it.
307
- const back = opener.current;
308
- if (back instanceof HTMLElement && back.isConnected) back.focus();
309
- };
310
- }, []);
311
-
312
- const onKeyDown = useCallback(
313
- (event: React.KeyboardEvent) => {
314
- if (event.key === "Escape") {
315
- event.stopPropagation();
316
- onClose();
317
- return;
318
- }
319
- if (event.key !== "Tab") return;
320
- // `:not([disabled])` matters more than it looks: a modal whose
321
- // confirm button is disabled until a field is typed is the
322
- // commonest pattern there is, and without this the wrap targets
323
- // a disabled element, preventDefault fires, focus() is a no-op
324
- // and Tab appears dead. Dead Tab is worse than escaping Tab.
325
- // `iframe` is here because an extension *is* one.
326
- const focusable = panel.current?.querySelectorAll<HTMLElement>(
327
- [
328
- "button:not([disabled])",
329
- "a[href]",
330
- "input:not([disabled]):not([type=hidden])",
331
- "select:not([disabled])",
332
- "textarea:not([disabled])",
333
- "iframe",
334
- "summary",
335
- "[contenteditable]",
336
- '[tabindex]:not([tabindex="-1"])',
337
- ].join(", "),
338
- );
339
- if (!focusable || focusable.length === 0) {
340
- // Nothing to move to, so hold the focus here rather than let
341
- // Tab walk into the page behind a modal with no way back.
342
- event.preventDefault();
343
- return;
344
- }
345
- const first = focusable[0];
346
- const last = focusable[focusable.length - 1];
347
- if (event.shiftKey && document.activeElement === first) {
348
- event.preventDefault();
349
- last.focus();
350
- } else if (!event.shiftKey && document.activeElement === last) {
351
- event.preventDefault();
352
- first.focus();
353
- }
354
- },
355
- [onClose],
356
- );
357
-
358
- return (
359
- <div
360
- className="overlay"
361
- onMouseDown={(e) => {
362
- // Primary button only, and only on the backdrop itself. A
363
- // right-click raising a context menu used to dismiss the
364
- // modal underneath it.
365
- if (e.button === 0 && e.target === e.currentTarget) onClose();
366
- }}
367
- >
368
- <div
369
- {...rest}
370
- ref={panel}
371
- className={cx("dialog", className)}
372
- role="dialog"
373
- aria-modal="true"
374
- // Without this a screen reader announces "dialog" and nothing
375
- // else. The app's own hand-rolled dialogs got this right while
376
- // the published one did not.
377
- aria-labelledby={titleId}
378
- tabIndex={-1}
379
- onKeyDown={onKeyDown}
380
- // Without this a drag that starts inside and ends outside
381
- // closes the dialog, which eats a selection.
382
- onMouseDown={(e) => e.stopPropagation()}
383
- >
384
- <h2 className="dialog-title" id={titleId}>
385
- {title}
386
- </h2>
387
- {sub ? <p className="dialog-sub">{sub}</p> : null}
388
- {children}
389
- {actions ? (
390
- <Actions className="dialog-actions">{actions}</Actions>
391
- ) : null}
392
- </div>
393
- </div>
394
- );
395
- }
396
-
397
- // ── Form controls ───────────────────────────────────────────────────
398
-
399
- /** What a {@link Select} takes. */
400
- export interface SelectProps extends SelectHTMLAttributes<HTMLSelectElement> {}
401
-
402
- /** A drop-down. */
403
- export function Select({ className, ...rest }: SelectProps) {
404
- return <select {...rest} className={cx("ui-select", className)} />;
405
- }
406
-
407
- /** What a {@link Textarea} takes. */
408
- export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {}
409
-
410
- /** A multi-line text field. */
411
- export function Textarea({ className, ...rest }: TextareaProps) {
412
- return <textarea {...rest} className={cx("ui-textarea", className)} />;
413
- }
414
-
415
- /** What a {@link Checkbox} takes. */
416
- export interface CheckboxProps extends InputHTMLAttributes<HTMLInputElement> {
417
- /** The text beside the box. It is the accessible name too. */
418
- label: ReactNode;
419
- }
420
-
421
- /**
422
- * A native checkbox, wrapped in its own label.
423
- *
424
- * Wrapped rather than associated by `id`, because an `id` an
425
- * extension forgets to make unique is a label that checks somebody
426
- * else's box — and nothing about the page looks wrong when it does.
427
- */
428
- export function Checkbox({ label, className, ...rest }: CheckboxProps) {
429
- return (
430
- <label className={cx("ui-check", className)}>
431
- <input type="checkbox" {...rest} />
432
- <span>{label}</span>
433
- </label>
434
- );
435
- }
436
-
437
- /** What a {@link Radio} takes. */
438
- export interface RadioProps extends InputHTMLAttributes<HTMLInputElement> {
439
- /** The text beside the box. It is the accessible name too. */
440
- label: ReactNode;
441
- }
442
-
443
- /**
444
- * A native radio, wrapped in its own label.
445
- *
446
- * Wrapped for the same reason a {@link Checkbox} is: an `id` an
447
- * extension forgets to make unique is a label that picks somebody
448
- * else's radio.
449
- */
450
- export function Radio({ label, className, ...rest }: RadioProps) {
451
- return (
452
- <label className={cx("ui-check", className)}>
453
- <input type="radio" {...rest} />
454
- <span>{label}</span>
455
- </label>
456
- );
457
- }
458
-
459
- /** What a {@link Switch} takes. */
460
- export interface SwitchProps extends Omit<
461
- ButtonHTMLAttributes<HTMLButtonElement>,
462
- "onChange"
463
- > {
464
- /** Whether it is on. */
465
- checked: boolean;
466
- /** Called with the next value. It takes effect at once. */
467
- onChange: (next: boolean) => void;
468
- /**
469
- * Shown beside the switch, and used as its accessible name.
470
- *
471
- * Visible, like `Checkbox.label` and `Radio.label`. It was an
472
- * `aria-label` and nothing else, so one prop name meant opposite
473
- * things on two components in the same package and a sighted user
474
- * got a bare toggle.
475
- */
476
- label: ReactNode;
477
- }
478
-
479
- /**
480
- * A switch, which is a button rather than a checkbox.
481
- *
482
- * The difference is not cosmetic. A checkbox is a value you submit; a
483
- * switch takes effect the moment it moves. `role="switch"` is what
484
- * tells a screen reader which of those it is looking at.
485
- */
486
- export function Switch({
487
- checked,
488
- onChange,
489
- label,
490
- className,
491
- ...rest
492
- }: SwitchProps) {
493
- const id = useId();
494
- return (
495
- <span className="ui-check">
496
- <button
497
- // `rest` goes first so a caller cannot clobber the parts that
498
- // make this a switch. It used to spread last, and a caller's
499
- // own onClick silently replaced the toggle — the control
500
- // looked fine and did nothing.
501
- {...rest}
502
- type="button"
503
- role="switch"
504
- aria-checked={checked}
505
- aria-labelledby={id}
506
- onClick={() => onChange(!checked)}
507
- className={cx("ui-switch", className)}
508
- />
509
- <span id={id}>{label}</span>
510
- </span>
511
- );
512
- }
513
-
514
- /**
515
- * A label, a control, and room for the reason it is wrong.
516
- *
517
- * The error slot is the part that gets left out, and a form that
518
- * rejects input without saying why is the one people abandon. When
519
- * `error` is set it is wired to the control through
520
- * `aria-describedby`, so it is announced rather than merely shown.
521
- */
522
- export interface FieldProps extends HTMLAttributes<HTMLDivElement> {
523
- /** The label. It is visible, not a placeholder. */
524
- label: ReactNode;
525
- /** A sentence under the control, for when nothing is wrong. */
526
- hint?: ReactNode;
527
- /** Why the control is wrong. It replaces the hint while it is set. */
528
- error?: ReactNode;
529
- /** The id of the control, so the label points at it. */
530
- htmlFor?: string;
531
- }
532
-
533
- /**
534
- * A label, a control, and room for the reason it is wrong.
535
- *
536
- * See {@link FieldProps}. The error slot is the part that gets left
537
- * out, and a form that rejects input without saying why is the one
538
- * people abandon.
539
- */
540
- export function Field({
541
- label,
542
- hint,
543
- error,
544
- htmlFor,
545
- children,
546
- className,
547
- ...rest
548
- }: FieldProps) {
549
- const describedBy = htmlFor ? `${htmlFor}-note` : undefined;
550
- // Cloned, not merely rendered beside. The first version put the id
551
- // on the note and stopped, while the docstring claimed the control
552
- // was wired to it — a claim its own test did not check, because the
553
- // test asserted the id existed and never that anything referenced
554
- // it. Nothing was announced. A Field cannot set an attribute on an
555
- // opaque child without doing this.
556
- const control =
557
- isValidElement(children) && describedBy && (error || hint)
558
- ? cloneElement(children as ReactElement<Record<string, unknown>>, {
559
- "aria-describedby": describedBy,
560
- ...(error ? { "aria-invalid": true } : {}),
561
- })
562
- : children;
563
- return (
564
- <div {...rest} className={cx("ui-field", className)}>
565
- <label className="ui-label" htmlFor={htmlFor}>
566
- {label}
567
- </label>
568
- {control}
569
- {error ? (
570
- <span className="ui-error" id={describedBy} role="alert">
571
- {error}
572
- </span>
573
- ) : hint ? (
574
- <span className="ui-hint" id={describedBy}>
575
- {hint}
576
- </span>
577
- ) : null}
578
- </div>
579
- );
580
- }
581
-
582
- // ── Feedback ────────────────────────────────────────────────────────
583
-
584
- /**
585
- * Work whose duration is unknown. `Skeleton` is for known shapes.
586
- *
587
- * `label` is required for the same reason `Progress.label` is. This
588
- * was `role="status"` on an empty span: a live region with nothing
589
- * to say, so a screen reader got silence while a sighted user
590
- * watched something spin.
591
- */
592
- export interface SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
593
- /** Required: a spinner with no name is a live region with nothing in it. */
594
- label: string;
595
- }
596
-
597
- /**
598
- * Work whose duration is unknown.
599
- *
600
- * See {@link SpinnerProps} for why `label` is required.
601
- */
602
- export function Spinner({ label, className, ...rest }: SpinnerProps) {
603
- return (
604
- <span
605
- {...rest}
606
- role="status"
607
- aria-live="polite"
608
- className={cx("ui-spinner", className)}
609
- >
610
- <span className="ui-visually-hidden">{label}</span>
611
- </span>
612
- );
613
- }
614
-
615
- /** What a {@link Progress} takes. */
616
- export interface ProgressProps extends HTMLAttributes<HTMLDivElement> {
617
- /**
618
- * How far along, against `max`. Omit for indeterminate, which
619
- * slides rather than sits.
620
- *
621
- * This was 0–1 while the ARIA attributes beside it were 0–100, so
622
- * `value={50}` meant 5000% and was silently clamped — the clamp hid
623
- * the mistake instead of surfacing it. Every other progress API,
624
- * `<progress>` included, takes a value against a max.
625
- */
626
- value?: number;
627
- /** Defaults to 100. */
628
- max?: number;
629
- /** Its name, for a screen reader. */
630
- label: string;
631
- }
632
-
633
- /**
634
- * A bar that fills.
635
- *
636
- * See {@link ProgressProps}. Without a `value` it slides, because a
637
- * bar that sits still while unknown work is happening is a bar that
638
- * looks broken.
639
- */
640
- export function Progress({
641
- value,
642
- max = 100,
643
- label,
644
- className,
645
- ...rest
646
- }: ProgressProps) {
647
- const determinate = typeof value === "number";
648
- const clamped = determinate
649
- ? Math.max(0, Math.min(max, value as number))
650
- : undefined;
651
- const pct = determinate ? ((clamped as number) / max) * 100 : undefined;
652
- return (
653
- <div
654
- {...rest}
655
- className={cx("ui-progress", className)}
656
- role="progressbar"
657
- aria-label={label}
658
- aria-valuenow={clamped}
659
- aria-valuemin={0}
660
- aria-valuemax={max}
661
- aria-valuetext={determinate ? `${Math.round(pct as number)}%` : undefined}
662
- data-indeterminate={!determinate}
663
- >
664
- <div
665
- className="ui-progress-fill"
666
- style={determinate ? { width: `${pct}%` } : undefined}
667
- />
668
- </div>
669
- );
670
- }
671
-
672
- // ── Tabs ────────────────────────────────────────────────────────────
673
-
674
- /** What a {@link Tabs} takes. */
675
- export interface TabsProps extends Omit<
676
- HTMLAttributes<HTMLDivElement>,
677
- "onChange"
678
- > {
679
- /** The tabs. The `id` is what {@link TabPanel}s match on. */
680
- tabs: { id: string; label: ReactNode }[];
681
- /** Which tab is showing. */
682
- active: string;
683
- /** Called with the id of the tab the reader chose. */
684
- onChange: (id: string) => void;
685
- /** The strip's name, for a screen reader. */
686
- label: string;
687
- /**
688
- * The id prefix shared with this strip's {@link TabPanel}s.
689
- *
690
- * Optional, and generated when it is absent — but a `TabPanel`
691
- * *requires* one, and for as long as this did not accept it there
692
- * was no way for a caller to learn what was generated. The two were
693
- * published as a pair that could not be used as a pair, and nothing
694
- * noticed because each is unit-tested on its own and neither had a
695
- * consumer. Found by building a second extension against them.
696
- */
697
- base?: string;
698
- }
699
-
700
- /**
701
- * Tabs with the arrow keys wired, because a tab strip that only
702
- * responds to clicks is a tab strip half the people cannot use.
703
- */
704
- export function Tabs({
705
- tabs,
706
- active,
707
- onChange,
708
- label,
709
- base: givenBase,
710
- className,
711
- ...rest
712
- }: TabsProps) {
713
- // Hooks run unconditionally; the generated id is simply unused
714
- // when a caller supplied one.
715
- const generated = useId();
716
- const base = givenBase ?? generated;
717
- const strip = useRef<HTMLDivElement | null>(null);
718
-
719
- // Focus follows selection, which the ARIA practices require and
720
- // this did not do. Without it the focus ring sits on a tab that is
721
- // now tabIndex={-1} while a different one is selected, and the next
722
- // Tab leaves the strip from somewhere the reader cannot see.
723
- useEffect(() => {
724
- const el = strip.current?.querySelector<HTMLElement>(
725
- '[aria-selected="true"]',
726
- );
727
- if (el && strip.current?.contains(document.activeElement)) el.focus();
728
- }, [active]);
729
-
730
- const onKeyDown = (event: React.KeyboardEvent) => {
731
- if (tabs.length === 0) return;
732
- const i = tabs.findIndex((t) => t.id === active);
733
- let next: number | null = null;
734
- if (event.key === "ArrowRight") next = (Math.max(i, 0) + 1) % tabs.length;
735
- else if (event.key === "ArrowLeft")
736
- next = (Math.max(i, 0) - 1 + tabs.length) % tabs.length;
737
- else if (event.key === "Home") next = 0;
738
- else if (event.key === "End") next = tabs.length - 1;
739
- if (next === null) return;
740
- event.preventDefault();
741
- onChange(tabs[next].id);
742
- };
743
-
744
- return (
745
- <div
746
- {...rest}
747
- ref={strip}
748
- role="tablist"
749
- aria-label={label}
750
- aria-orientation="horizontal"
751
- className={cx("ui-tabs", className)}
752
- onKeyDown={onKeyDown}
753
- >
754
- {tabs.map((tab) => (
755
- <button
756
- key={tab.id}
757
- // Real DOM ids, so a panel can point back with
758
- // aria-labelledby and this one can point at it. Without
759
- // them a screen reader announces "tab, 1 of 2" controlling
760
- // nothing.
761
- id={`${base}-${tab.id}`}
762
- aria-controls={`${base}-${tab.id}-panel`}
763
- type="button"
764
- role="tab"
765
- aria-selected={tab.id === active}
766
- tabIndex={tab.id === active ? 0 : -1}
767
- className="ui-tab"
768
- onClick={() => onChange(tab.id)}
769
- >
770
- {tab.label}
771
- </button>
772
- ))}
773
- </div>
774
- );
775
- }
776
-
777
- /**
778
- * The panel a tab controls. Needs the same `base` the strip used.
779
- *
780
- * Published because `Tabs` without it is half the ARIA pattern: the
781
- * strip announced that it controlled something and there was nothing
782
- * for it to control.
783
- */
784
- export interface TabPanelProps extends HTMLAttributes<HTMLDivElement> {
785
- /** The id prefix shared with its {@link Tabs}, so the two agree. */
786
- base: string;
787
- /** Which tab this panel belongs to. */
788
- id: string;
789
- /** Which tab is showing. The panel renders only when they match. */
790
- active: string;
791
- }
792
-
793
- /**
794
- * The panel a tab controls.
795
- *
796
- * See {@link TabPanelProps}. It renders nothing at all when its tab is
797
- * not the active one, so the content of a panel that is not showing
798
- * is not in the page.
799
- */
800
- export function TabPanel({
801
- base,
802
- id,
803
- active,
804
- children,
805
- className,
806
- ...rest
807
- }: TabPanelProps) {
808
- if (id !== active) return null;
809
- return (
810
- <div
811
- {...rest}
812
- id={`${base}-${id}-panel`}
813
- role="tabpanel"
814
- aria-labelledby={`${base}-${id}`}
815
- tabIndex={0}
816
- className={className}
817
- >
818
- {children}
819
- </div>
820
- );
821
- }
822
-
823
- // ── Text ────────────────────────────────────────────────────────────
824
-
825
- /** A horizontal rule. */
826
- export function Divider({ className, ...rest }: HTMLAttributes<HTMLHRElement>) {
827
- return <hr {...rest} className={cx("ui-divider", className)} />;
828
- }
829
-
830
- /** What a {@link Heading} takes. */
831
- export interface HeadingProps extends HTMLAttributes<HTMLHeadingElement> {
832
- /** The outline level. Also picks the size, so they cannot disagree. */
833
- level?: 1 | 2 | 3 | 4;
834
- }
835
-
836
- const HEADING_SIZE = {
837
- 1: "var(--text-2xl)",
838
- 2: "var(--text-xl)",
839
- 3: "var(--text-lg)",
840
- 4: "var(--text-sm)",
841
- } as const;
842
-
843
- /**
844
- * A heading, at the level you say.
845
- *
846
- * The size follows the level, so the outline and the type cannot
847
- * disagree — which is the whole reason there is no `Title`.
848
- */
849
- export function Heading({
850
- level = 2,
851
- className,
852
- style,
853
- ...rest
854
- }: HeadingProps) {
855
- const Tag = `h${level}` as "h1" | "h2" | "h3" | "h4";
856
- return (
857
- <Tag
858
- {...rest}
859
- className={cx("ui-heading", className)}
860
- style={{ fontSize: HEADING_SIZE[level], ...style }}
861
- />
862
- );
863
- }
864
-
865
- /** How loud. Not {@link Tone}: this is emphasis, not status. */
866
- export type TextTone = "default" | "muted" | "faint";
867
-
868
- /** What a {@link Text} takes. */
869
- export interface TextProps extends HTMLAttributes<HTMLParagraphElement> {
870
- /** How loud it is. */
871
- tone?: TextTone;
872
- }
873
-
874
- /**
875
- * A paragraph.
876
- *
877
- * {@link TextTone} says how loud it is — emphasis, not status. A
878
- * status is a {@link Badge}.
879
- */
880
- export function Text({ tone = "default", className, ...rest }: TextProps) {
881
- return <p {...rest} data-tone={tone} className={cx("ui-text", className)} />;
882
- }
883
-
884
- /** Inline code: a name, a path, a flag. */
885
- export function Code({ className, ...rest }: HTMLAttributes<HTMLElement>) {
886
- return <code {...rest} className={cx("ui-code", className)} />;
887
- }
27
+ export * from "./controls.js";
28
+ export * from "./layout.js";
29
+ export * from "./Dialog.js";
30
+ export * from "./formControls.js";
31
+ export * from "./progress.js";
32
+ export * from "./Tabs.js";
33
+ export * from "./text.js";