@hussmartinez/ui 0.3.0 → 0.5.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.
package/dist/ui.d.ts ADDED
@@ -0,0 +1,1432 @@
1
+ /**
2
+ * Accessible React components of the `@hussmartinez` design system.
3
+ *
4
+ * @remarks
5
+ * A client entry: it starts with `"use client"`, which the build keeps
6
+ * (ADR 0007). React and React DOM 18.3 or later are optional peer
7
+ * dependencies.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+
12
+ import { ButtonHTMLAttributes } from 'react';
13
+ import { DialogHTMLAttributes } from 'react';
14
+ import { ForwardRefExoticComponent } from 'react';
15
+ import { HTMLAttributes } from 'react';
16
+ import { InputHTMLAttributes } from 'react';
17
+ import { Messages } from '@hussmartinez/sdk-core';
18
+ import { Platform } from '@hussmartinez/sdk-core';
19
+ import { ProgressHTMLAttributes } from 'react';
20
+ import { ReactElement } from 'react';
21
+ import { ReactNode } from 'react';
22
+ import { Ref } from 'react';
23
+ import { RefAttributes } from 'react';
24
+ import { RefObject } from 'react';
25
+ import type { SVGProps } from 'react';
26
+
27
+ /**
28
+ * The `add` icon: Lucide's `plus`.
29
+ *
30
+ * @public
31
+ */
32
+ export declare function AddIcon(props: IconProps): ReactElement;
33
+
34
+ /**
35
+ * Announces a message to screen readers, such as "Saved 1.3 MB" (ADR 0014).
36
+ * The message is plain text from your message catalogue.
37
+ *
38
+ * @public
39
+ */
40
+ export declare type Announce = (message: string, options?: {
41
+ politeness?: Politeness;
42
+ }) => void;
43
+
44
+ /**
45
+ * Renders a polite and an assertive `aria-live` region, visually hidden, and
46
+ * lets everything inside announce through {@link useAnnounce}. The regions are
47
+ * in the server-rendered page from the start, as screen readers only announce
48
+ * changes to regions that already exist. Render it once, near the root of an
49
+ * editor or application.
50
+ *
51
+ * @public
52
+ */
53
+ export declare function AnnouncerProvider({ children }: AnnouncerProviderProps): ReactElement;
54
+
55
+ /**
56
+ * Props of {@link AnnouncerProvider}.
57
+ *
58
+ * @public
59
+ */
60
+ export declare interface AnnouncerProviderProps {
61
+ readonly children?: ReactNode;
62
+ }
63
+
64
+ /**
65
+ * A button: a native `<button>`, `type="button"` unless you say otherwise.
66
+ *
67
+ * @example
68
+ * ```tsx
69
+ * <Button variant="primary" startIcon={<DownloadIcon />} onClick={save}>
70
+ * {messages.t("toolbar.download")}
71
+ * </Button>
72
+ * ```
73
+ *
74
+ * @public
75
+ */
76
+ export declare const Button: ForwardRefExoticComponent<ButtonProps & RefAttributes<HTMLButtonElement>>;
77
+
78
+ /**
79
+ * The parts of a button that `classNames` can target.
80
+ *
81
+ * @public
82
+ */
83
+ export declare type ButtonPart = "root" | "icon" | "label";
84
+
85
+ /**
86
+ * Props of {@link Button}. Native button props are passed through.
87
+ *
88
+ * @public
89
+ */
90
+ export declare interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "className">, StyleProps<ButtonPart> {
91
+ /** Defaults to `secondary`. */
92
+ readonly variant?: ButtonVariant | undefined;
93
+ /** Defaults to `medium`. */
94
+ readonly size?: ButtonSize | undefined;
95
+ /** Makes it a toggle button, on or off, exposed as `aria-pressed`. */
96
+ readonly pressed?: boolean | undefined;
97
+ /** An icon before the label. It's decorative, and draws with `currentColor`. */
98
+ readonly startIcon?: ReactNode;
99
+ /** An icon after the label. */
100
+ readonly endIcon?: ReactNode;
101
+ /**
102
+ * Keeps a disabled button focusable, with `aria-disabled` instead of the
103
+ * `disabled` attribute, so it stays in a toolbar's keyboard order and
104
+ * screen readers can find it. Clicks are ignored.
105
+ */
106
+ readonly focusableWhenDisabled?: boolean | undefined;
107
+ }
108
+
109
+ /**
110
+ * Button sizes. Both meet the 24 px target size, and 44 px on coarse
111
+ * pointers (ADR 0014).
112
+ *
113
+ * @public
114
+ */
115
+ export declare type ButtonSize = "medium" | "small";
116
+
117
+ /**
118
+ * How prominent a button is: `primary` for the main action, `secondary`
119
+ * (the default) for others, `quiet` for toolbars and dense places, `danger`
120
+ * for destructive actions.
121
+ *
122
+ * @public
123
+ */
124
+ export declare type ButtonVariant = "primary" | "secondary" | "quiet" | "danger";
125
+
126
+ /**
127
+ * The `check` icon: Lucide's `check`.
128
+ *
129
+ * @public
130
+ */
131
+ export declare function CheckIcon(props: IconProps): ReactElement;
132
+
133
+ /**
134
+ * The `chevron-down` icon: Lucide's `chevron-down`.
135
+ *
136
+ * @public
137
+ */
138
+ export declare function ChevronDownIcon(props: IconProps): ReactElement;
139
+
140
+ /**
141
+ * The `chevron-left` icon: Lucide's `chevron-left`.
142
+ *
143
+ * @public
144
+ */
145
+ export declare function ChevronLeftIcon(props: IconProps): ReactElement;
146
+
147
+ /**
148
+ * The `chevron-right` icon: Lucide's `chevron-right`.
149
+ *
150
+ * @public
151
+ */
152
+ export declare function ChevronRightIcon(props: IconProps): ReactElement;
153
+
154
+ /**
155
+ * Extra classes for a component's named parts.
156
+ *
157
+ * @public
158
+ */
159
+ export declare type ClassNames<Part extends string> = {
160
+ readonly [Name in Part]?: string;
161
+ };
162
+
163
+ /**
164
+ * The `close` icon: Lucide's `x`.
165
+ *
166
+ * @public
167
+ */
168
+ export declare function CloseIcon(props: IconProps): ReactElement;
169
+
170
+ /**
171
+ * How a subtree picks between light and dark: one of them, or whichever the
172
+ * operating system prefers (`prefers-color-scheme`).
173
+ *
174
+ * @public
175
+ */
176
+ export declare type ColorMode = "light" | "dark" | "system";
177
+
178
+ /**
179
+ * The `crop` icon: Lucide's `crop`.
180
+ *
181
+ * @public
182
+ */
183
+ export declare function CropIcon(props: IconProps): ReactElement;
184
+
185
+ /**
186
+ * The `delete` icon: Lucide's `trash`.
187
+ *
188
+ * @public
189
+ */
190
+ export declare function DeleteIcon(props: IconProps): ReactElement;
191
+
192
+ /**
193
+ * How tightly controls are packed. Set it with `data-hm-density` or the
194
+ * `density` prop.
195
+ *
196
+ * @public
197
+ */
198
+ export declare type Density = "comfortable" | "compact";
199
+
200
+ /**
201
+ * A modal dialog on the native `<dialog>` element with `showModal()` (ADR
202
+ * 0014): it traps focus, makes the page behind it inert, and sits in the top
203
+ * layer, which host z-indexes and overflow can't break.
204
+ *
205
+ * - **Controlled:** `open` decides, and `onOpenChange(false)` asks to close,
206
+ * on Escape or the close button.
207
+ * - **Focus:** moves into the dialog when it opens, to `initialFocus` or the
208
+ * first focusable element, and back to what was focused before when it
209
+ * closes.
210
+ * - **Server rendering:** renders closed, and opens after hydration.
211
+ *
212
+ * @example
213
+ * ```tsx
214
+ * <Dialog
215
+ * open={open}
216
+ * onOpenChange={setOpen}
217
+ * title={messages.t("export.title")}
218
+ * footer={<Button variant="primary" onClick={exportFile}>{messages.t("export.confirm")}</Button>}
219
+ * >
220
+ * {options}
221
+ * </Dialog>
222
+ * ```
223
+ *
224
+ * @public
225
+ */
226
+ export declare const Dialog: ForwardRefExoticComponent<DialogProps & RefAttributes<HTMLDialogElement>>;
227
+
228
+ /**
229
+ * The parts of a dialog that `classNames` can target.
230
+ *
231
+ * @public
232
+ */
233
+ export declare type DialogPart = "root" | "header" | "title" | "description" | "body" | "footer" | "close";
234
+
235
+ /**
236
+ * Props of {@link Dialog}.
237
+ *
238
+ * @public
239
+ */
240
+ export declare interface DialogProps extends Omit<DialogHTMLAttributes<HTMLDialogElement>, "className" | "title" | "open">, StyleProps<DialogPart> {
241
+ /** Whether the dialog is open. The dialog is always controlled. */
242
+ readonly open: boolean;
243
+ /**
244
+ * Called with `false` when the user asks to close: Escape, or the close
245
+ * button. Keep `open` true to refuse, for example while saving.
246
+ */
247
+ readonly onOpenChange: (open: boolean) => void;
248
+ /** The heading, and the dialog's accessible name. */
249
+ readonly title: ReactNode;
250
+ /** A short description under the title, read when the dialog opens. */
251
+ readonly description?: ReactNode;
252
+ /** Actions at the bottom, such as Cancel and Save buttons. */
253
+ readonly footer?: ReactNode;
254
+ /** The close button's accessible name. Defaults to `dialog.close` from the messages. */
255
+ readonly closeLabel?: string | undefined;
256
+ /** Replaces the close icon. It draws with `currentColor`. */
257
+ readonly closeIcon?: ReactNode;
258
+ /** The element to focus when the dialog opens. Defaults to the first focusable one. */
259
+ readonly initialFocus?: RefObject<HTMLElement | null> | undefined;
260
+ /** Defaults to `medium`. */
261
+ readonly size?: "small" | "medium" | "large" | undefined;
262
+ }
263
+
264
+ /**
265
+ * The `download` icon: Lucide's `download`.
266
+ *
267
+ * @public
268
+ */
269
+ export declare function DownloadIcon(props: IconProps): ReactElement;
270
+
271
+ /**
272
+ * The `fade-in` icon: Lucide's `chart-no-axes-column-increasing`.
273
+ *
274
+ * @public
275
+ */
276
+ export declare function FadeInIcon(props: IconProps): ReactElement;
277
+
278
+ /**
279
+ * The `fade-out` icon: Lucide's `chart-no-axes-column-decreasing`.
280
+ *
281
+ * @public
282
+ */
283
+ export declare function FadeOutIcon(props: IconProps): ReactElement;
284
+
285
+ /**
286
+ * A label, an optional description and an optional error, wired to one
287
+ * control: the label names it, and the description and error describe it.
288
+ *
289
+ * The control must be labelable, such as an `<input>`, `<select>`,
290
+ * `<textarea>` or `ui`'s `Slider`. For a group of controls, such as
291
+ * `SegmentedControl`, use the group's own `label`.
292
+ *
293
+ * An error that appears after the user acts, such as on submit, isn't
294
+ * announced on its own: move focus to the field, or announce it with
295
+ * `useAnnounce`.
296
+ *
297
+ * @example
298
+ * ```tsx
299
+ * <Field label={t("export.dpi")} description={t("export.dpiHelp")} error={dpiError}>
300
+ * <Slider min={72} max={600} value={dpi} onValueChange={setDpi} />
301
+ * </Field>
302
+ *
303
+ * <Field label={t("export.name")}>
304
+ * {(control) => <input {...control} value={name} onChange={onNameChange} />}
305
+ * </Field>
306
+ * ```
307
+ *
308
+ * @public
309
+ */
310
+ export declare const Field: ForwardRefExoticComponent<FieldProps & RefAttributes<HTMLDivElement>>;
311
+
312
+ /**
313
+ * The props a {@link Field} gives its control, so the label, description
314
+ * and error reach assistive technology.
315
+ *
316
+ * @public
317
+ */
318
+ export declare interface FieldControlProps {
319
+ /** The control's `id`, which the label points at. */
320
+ readonly id: string;
321
+ /** The ids of the description and the error, when there are any. */
322
+ readonly "aria-describedby": string | undefined;
323
+ /** `true` while the field shows an error. */
324
+ readonly "aria-invalid": true | undefined;
325
+ }
326
+
327
+ /**
328
+ * The parts of a field that `classNames` can target.
329
+ *
330
+ * @public
331
+ */
332
+ export declare type FieldPart = "root" | "label" | "description" | "error";
333
+
334
+ /**
335
+ * Props of {@link Field}. Native `div` props are passed through to the root.
336
+ *
337
+ * @public
338
+ */
339
+ export declare interface FieldProps extends Omit<HTMLAttributes<HTMLDivElement>, "className" | "children">, StyleProps<FieldPart> {
340
+ /** The visible label. Use text from your message catalogue. */
341
+ readonly label: ReactNode;
342
+ /** Help shown under the label, such as "Between −24 and 24 dB". */
343
+ readonly description?: ReactNode;
344
+ /**
345
+ * What's wrong with the value, such as "Enter a number". While it's set,
346
+ * the control is marked invalid and the text is read with it.
347
+ */
348
+ readonly error?: ReactNode;
349
+ /** The control's `id`. Defaults to a generated one. */
350
+ readonly controlId?: string | undefined;
351
+ /**
352
+ * The control. `ui` controls, such as `Slider` and `NumberField`, connect
353
+ * themselves. For any other control, pass a function and spread the
354
+ * props it receives onto the control.
355
+ */
356
+ readonly children: ReactNode | ((control: FieldControlProps) => ReactNode);
357
+ }
358
+
359
+ /**
360
+ * Where people choose or drop files, such as a document to open. The button
361
+ * opens the system's file picker: it's the keyboard and screen reader path.
362
+ * The zone around it takes dropped files, a shortcut for pointer users, so it
363
+ * isn't focusable itself. While files are dragged over it, it has the
364
+ * `data-hm-dragging` attribute.
365
+ *
366
+ * The zone checks names, types and counts against `accept` and `multiple`,
367
+ * and turns away folders, then calls `onFiles`. It never reads a file and
368
+ * never shows a file's name. Treat files as untrusted: check their contents
369
+ * before using them, and show their names as text.
370
+ *
371
+ * While a zone is on the page, files dropped elsewhere on the page are
372
+ * turned away, so a near miss doesn't navigate away from it. Hosts that
373
+ * handle that themselves turn it off with `preventStrayDrops={false}`.
374
+ *
375
+ * @example
376
+ * ```tsx
377
+ * <FileDropZone accept=".pdf,application/pdf" onFiles={([file]) => open(file)}>
378
+ * <p>{messages.t("editor.start.title")}</p>
379
+ * </FileDropZone>
380
+ * ```
381
+ *
382
+ * @public
383
+ */
384
+ export declare const FileDropZone: ForwardRefExoticComponent<FileDropZoneProps & RefAttributes<HTMLDivElement>>;
385
+
386
+ /**
387
+ * The parts of a file drop zone that `classNames` can target.
388
+ *
389
+ * @public
390
+ */
391
+ export declare type FileDropZonePart = "root" | "button" | "hint";
392
+
393
+ /**
394
+ * Props of {@link FileDropZone}. Native `div` props are passed through to the
395
+ * zone.
396
+ *
397
+ * @public
398
+ */
399
+ export declare interface FileDropZoneProps extends Omit<HTMLAttributes<HTMLDivElement>, "className" | "onDrop" | "onDragEnter" | "onDragOver" | "onDragLeave">, StyleProps<FileDropZonePart> {
400
+ /**
401
+ * Called with the files that passed the zone's checks, chosen or dropped,
402
+ * in order. The checks only look at names, types and counts: validate each
403
+ * file's contents before using it.
404
+ */
405
+ readonly onFiles: (files: File[]) => void;
406
+ /** Called with the files the zone turned away, and why. */
407
+ readonly onFilesRejected?: ((rejections: FileRejection[]) => void) | undefined;
408
+ /**
409
+ * The file types to offer and take, as in `<input accept>`: extensions
410
+ * such as `.pdf`, MIME types such as `application/pdf`, or `audio/*`.
411
+ * A hint for the picker and a first filter, not a security check: a
412
+ * file's name and type are whatever its sender chose.
413
+ */
414
+ readonly accept?: string | undefined;
415
+ /** Takes several files at once. Defaults to `false`. */
416
+ readonly multiple?: boolean | undefined;
417
+ /**
418
+ * Turns away files dropped anywhere else on the page while the zone is
419
+ * mounted, so a near miss doesn't open the file in place of the page.
420
+ * Defaults to `true`. Turn it off when the host handles stray drops
421
+ * itself, or embeds the zone in a page whose drag and drop it doesn't own.
422
+ */
423
+ readonly preventStrayDrops?: boolean | undefined;
424
+ /** Turns the button off, and ignores drops. */
425
+ readonly disabled?: boolean | undefined;
426
+ /**
427
+ * The button's text. Defaults to `fileDropZone.choose` from the messages
428
+ * ("Choose a file"), or `fileDropZone.chooseMultiple` with `multiple`.
429
+ */
430
+ readonly buttonLabel?: ReactNode;
431
+ /** Defaults to `primary`. */
432
+ readonly buttonVariant?: ButtonVariant | undefined;
433
+ /** A ref to the button, for moving focus to it. */
434
+ readonly buttonRef?: Ref<HTMLButtonElement> | undefined;
435
+ /**
436
+ * Text under the button, which also describes it. Defaults to
437
+ * `fileDropZone.hint` ("or drop it here"), or `fileDropZone.hintMultiple`.
438
+ */
439
+ readonly hint?: ReactNode;
440
+ /** Content above the button, such as a title or the reason the last file failed. */
441
+ readonly children?: ReactNode;
442
+ }
443
+
444
+ /**
445
+ * A file that {@link FileDropZone} turned away, and why: `type` when it
446
+ * doesn't match `accept`, `count` when several came and `multiple` is off,
447
+ * `directory` for a dropped folder.
448
+ *
449
+ * @public
450
+ */
451
+ export declare interface FileRejection {
452
+ readonly file: File;
453
+ readonly reason: "type" | "count" | "directory";
454
+ }
455
+
456
+ /**
457
+ * The `fit` icon: Lucide's `scan`.
458
+ *
459
+ * @public
460
+ */
461
+ export declare function FitIcon(props: IconProps): ReactElement;
462
+
463
+ /**
464
+ * The `flip-horizontal` icon: Lucide's `triangles-centerline-dashed-vertical`.
465
+ *
466
+ * @public
467
+ */
468
+ export declare function FlipHorizontalIcon(props: IconProps): ReactElement;
469
+
470
+ /**
471
+ * The `flip-vertical` icon: Lucide's `triangles-centerline-dashed-horizontal`.
472
+ *
473
+ * @public
474
+ */
475
+ export declare function FlipVerticalIcon(props: IconProps): ReactElement;
476
+
477
+ /**
478
+ * The `highlighter` icon: Lucide's `highlighter`.
479
+ *
480
+ * @public
481
+ */
482
+ export declare function HighlighterIcon(props: IconProps): ReactElement;
483
+
484
+ /**
485
+ * A square button with only an icon. `label` is its accessible name, so it
486
+ * can't be left out.
487
+ *
488
+ * @example
489
+ * ```tsx
490
+ * <IconButton label={messages.t("toolbar.rotate")} icon={<RotateIcon />} onClick={rotate} />
491
+ * ```
492
+ *
493
+ * @public
494
+ */
495
+ export declare const IconButton: ForwardRefExoticComponent<IconButtonProps & RefAttributes<HTMLButtonElement>>;
496
+
497
+ /**
498
+ * Props of {@link IconButton}.
499
+ *
500
+ * @public
501
+ */
502
+ export declare interface IconButtonProps extends Omit<ButtonProps, "startIcon" | "endIcon" | "children" | "classNames"> {
503
+ /** The accessible name. Required, because the button shows no text. */
504
+ readonly label: string;
505
+ /** The icon. It draws with `currentColor`. */
506
+ readonly icon: ReactNode;
507
+ /** Extra classes on the root and the icon. */
508
+ readonly classNames?: ClassNames<"root" | "icon"> | undefined;
509
+ }
510
+
511
+ /**
512
+ * An icon from ui's set, such as `UndoIcon`.
513
+ *
514
+ * @public
515
+ */
516
+ export declare type IconComponent = (props: IconProps) => ReactElement;
517
+
518
+ /**
519
+ * The name of an icon in ui's set, such as `rotate-left`. Tools refer to
520
+ * icons by name (sdk-core ADR 0030), and the SDK maps the names it uses to
521
+ * their components.
522
+ *
523
+ * @public
524
+ */
525
+ export declare type IconName = "add" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "close" | "crop" | "delete" | "download" | "fade-in" | "fade-out" | "fit" | "flip-horizontal" | "flip-vertical" | "highlighter" | "info" | "loop" | "menu" | "more" | "muted" | "open" | "page-grid" | "page-single" | "pan" | "pause" | "pen" | "play" | "redo" | "remove" | "rotate-left" | "rotate-right" | "search" | "select" | "skip-back" | "skip-forward" | "snap" | "split" | "stop" | "trim-end" | "trim-start" | "undo" | "upload" | "volume" | "warning" | "zoom-in" | "zoom-out";
526
+
527
+ /**
528
+ * Props of every icon. SVG attributes are passed through.
529
+ *
530
+ * @public
531
+ */
532
+ export declare interface IconProps extends Omit<SVGProps<SVGSVGElement>, "children" | "dangerouslySetInnerHTML" | "ref"> {
533
+ /**
534
+ * The accessible name, for an icon that means something on its own.
535
+ * Without it, the icon is decorative and hidden from assistive
536
+ * technology, as it should be inside a labelled button.
537
+ */
538
+ readonly label?: string | undefined;
539
+ }
540
+
541
+ /**
542
+ * The `info` icon: Lucide's `info`.
543
+ *
544
+ * @public
545
+ */
546
+ export declare function InfoIcon(props: IconProps): ReactElement;
547
+
548
+ /**
549
+ * The `loop` icon: Lucide's `repeat`.
550
+ *
551
+ * @public
552
+ */
553
+ export declare function LoopIcon(props: IconProps): ReactElement;
554
+
555
+ /**
556
+ * The `menu` icon: Lucide's `menu`.
557
+ *
558
+ * @public
559
+ */
560
+ export declare function MenuIcon(props: IconProps): ReactElement;
561
+
562
+ /**
563
+ * The `more` icon: Lucide's `ellipsis`.
564
+ *
565
+ * @public
566
+ */
567
+ export declare function MoreIcon(props: IconProps): ReactElement;
568
+
569
+ /**
570
+ * The `muted` icon: Lucide's `volume-x`.
571
+ *
572
+ * @public
573
+ */
574
+ export declare function MutedIcon(props: IconProps): ReactElement;
575
+
576
+ /**
577
+ * A number input: a text field exposed as a spin button, with locale-aware
578
+ * parsing and formatting.
579
+ *
580
+ * Typing never changes the value: the text is committed on blur or Enter,
581
+ * then kept within `min` and `max`. Text that isn't a number, or no text,
582
+ * goes back to the last value, so the value is never `NaN`. Escape throws
583
+ * the typing away. Arrow Up and Arrow Down move by `step`, Page Up and Page
584
+ * Down by `largeStep`, from the typed number when there is one.
585
+ *
586
+ * Other notations are a `parse` and `format` away: a timecode field is a
587
+ * `NumberField` of seconds. With `name`, forms receive the number, not the
588
+ * formatted text.
589
+ *
590
+ * @example
591
+ * ```tsx
592
+ * <Field label={messages.t("view.zoom")}>
593
+ * <NumberField
594
+ * min={10}
595
+ * max={400}
596
+ * step={10}
597
+ * value={zoom}
598
+ * onValueChange={setZoom}
599
+ * format={(percent) => `${percent}%`}
600
+ * parse={(text) => parseFloat(text)}
601
+ * />
602
+ * </Field>
603
+ * ```
604
+ *
605
+ * @public
606
+ */
607
+ export declare const NumberField: ForwardRefExoticComponent<NumberFieldProps & RefAttributes<HTMLInputElement>>;
608
+
609
+ /**
610
+ * Props of {@link NumberField}. Native input props are passed through.
611
+ *
612
+ * @public
613
+ */
614
+ export declare interface NumberFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "className" | "type" | "value" | "defaultValue" | "min" | "max" | "step" | "onChange" | "role" | "aria-valuenow" | "aria-valuemin" | "aria-valuemax" | "aria-valuetext">, StyleProps<"root"> {
615
+ /** The value, when you control it. Leave it out to let the field keep its own. */
616
+ readonly value?: number | undefined;
617
+ /** The starting value, when the field keeps its own. Defaults to 0, kept within `min` and `max`. */
618
+ readonly defaultValue?: number | undefined;
619
+ /**
620
+ * Called with the new value when it's committed: on blur, on Enter, or
621
+ * with the arrow and Page keys. Never with `NaN`, and never while typing.
622
+ */
623
+ readonly onValueChange?: ((value: number) => void) | undefined;
624
+ /** The smallest value. Values below it are raised to it. */
625
+ readonly min?: number | undefined;
626
+ /** The largest value. Values above it are lowered to it. */
627
+ readonly max?: number | undefined;
628
+ /** The Arrow Up and Arrow Down step. Defaults to 1. Typed values aren't snapped to it. */
629
+ readonly step?: number | undefined;
630
+ /** The Page Up and Page Down step. Defaults to ten steps. */
631
+ readonly largeStep?: number | undefined;
632
+ /**
633
+ * The locale for the default `parse` and `format`, such as `"de"`.
634
+ * Defaults to the locale of `UiMessagesProvider`, or `"en"`.
635
+ */
636
+ readonly locale?: string | undefined;
637
+ /**
638
+ * Reads typed text as a number, or returns `undefined` when it isn't one.
639
+ * Defaults to the locale's digits, decimal and group separators, and minus
640
+ * sign. Replace it for other notations, such as a timecode.
641
+ */
642
+ readonly parse?: ((text: string) => number | undefined) | undefined;
643
+ /**
644
+ * Writes a value as text: the field shows it, and screen readers read it.
645
+ * Defaults to the locale's number format.
646
+ */
647
+ readonly format?: ((value: number) => string) | undefined;
648
+ /**
649
+ * The accessible name, such as "Zoom". Leave it out inside a `Field`, or
650
+ * when a visible `<label>` points at the field's `id`, or
651
+ * `aria-labelledby` names it.
652
+ */
653
+ readonly label?: string | undefined;
654
+ }
655
+
656
+ /**
657
+ * The `open` icon: Lucide's `folder-open`.
658
+ *
659
+ * @public
660
+ */
661
+ export declare function OpenIcon(props: IconProps): ReactElement;
662
+
663
+ /**
664
+ * The `page-grid` icon: Lucide's `grid-2x2`.
665
+ *
666
+ * @public
667
+ */
668
+ export declare function PageGridIcon(props: IconProps): ReactElement;
669
+
670
+ /**
671
+ * The `page-single` icon: Lucide's `file`.
672
+ *
673
+ * @public
674
+ */
675
+ export declare function PageSingleIcon(props: IconProps): ReactElement;
676
+
677
+ /**
678
+ * The `pan` icon: Lucide's `hand`.
679
+ *
680
+ * @public
681
+ */
682
+ export declare function PanIcon(props: IconProps): ReactElement;
683
+
684
+ /**
685
+ * The `pause` icon: Lucide's `pause`.
686
+ *
687
+ * @public
688
+ */
689
+ export declare function PauseIcon(props: IconProps): ReactElement;
690
+
691
+ /**
692
+ * The `pen` icon: Lucide's `pen`.
693
+ *
694
+ * @public
695
+ */
696
+ export declare function PenIcon(props: IconProps): ReactElement;
697
+
698
+ /**
699
+ * The `play` icon: Lucide's `play`.
700
+ *
701
+ * @public
702
+ */
703
+ export declare function PlayIcon(props: IconProps): ReactElement;
704
+
705
+ /**
706
+ * How urgently a message interrupts: `polite` waits for the screen reader to
707
+ * finish, `assertive` interrupts. Use `assertive` only for errors the user
708
+ * must act on.
709
+ *
710
+ * @public
711
+ */
712
+ export declare type Politeness = "polite" | "assertive";
713
+
714
+ /**
715
+ * Shows how much of a task is done, on the native `<progress>` element: no
716
+ * inline styles, so it renders correctly under a strict Content Security
717
+ * Policy, before hydration too. Without `value`, it's indeterminate and
718
+ * pulses, or stays still under reduced motion.
719
+ *
720
+ * @example
721
+ * ```tsx
722
+ * <ProgressBar value={done} max={total} label={messages.t("export.progress")} />
723
+ * ```
724
+ *
725
+ * @public
726
+ */
727
+ export declare const ProgressBar: ForwardRefExoticComponent<ProgressBarProps & RefAttributes<HTMLProgressElement>>;
728
+
729
+ /**
730
+ * Props of {@link ProgressBar}.
731
+ *
732
+ * @public
733
+ */
734
+ export declare interface ProgressBarProps extends Omit<ProgressHTMLAttributes<HTMLProgressElement>, "className" | "value" | "max">, StyleProps<"root"> {
735
+ /** How much is done, from 0 to `max`. Leave it out while the amount is unknown. */
736
+ readonly value?: number | undefined;
737
+ /** Defaults to 100. */
738
+ readonly max?: number | undefined;
739
+ /** What's in progress. Defaults to `progress.label` from the messages ("Progress"). */
740
+ readonly label?: string | undefined;
741
+ /** The value as words, such as "Page 3 of 12", read instead of a percentage. */
742
+ readonly valueText?: string | undefined;
743
+ }
744
+
745
+ /**
746
+ * The `redo` icon: Lucide's `redo-2`, mirrored in right-to-left text.
747
+ *
748
+ * @public
749
+ */
750
+ export declare function RedoIcon(props: IconProps): ReactElement;
751
+
752
+ /**
753
+ * The `remove` icon: Lucide's `minus`.
754
+ *
755
+ * @public
756
+ */
757
+ export declare function RemoveIcon(props: IconProps): ReactElement;
758
+
759
+ /**
760
+ * The `rotate-left` icon: Lucide's `rotate-ccw`.
761
+ *
762
+ * @public
763
+ */
764
+ export declare function RotateLeftIcon(props: IconProps): ReactElement;
765
+
766
+ /**
767
+ * The `rotate-right` icon: Lucide's `rotate-cw`.
768
+ *
769
+ * @public
770
+ */
771
+ export declare function RotateRightIcon(props: IconProps): ReactElement;
772
+
773
+ /**
774
+ * The `search` icon: Lucide's `search`.
775
+ *
776
+ * @public
777
+ */
778
+ export declare function SearchIcon(props: IconProps): ReactElement;
779
+
780
+ /**
781
+ * A small set of mutually exclusive choices shown side by side, such as a
782
+ * view mode. It's a WAI-ARIA radio group: arrow keys move and select. Inside a
783
+ * {@link Toolbar}, it joins the toolbar's arrow-key navigation instead, and
784
+ * Space or Enter selects.
785
+ *
786
+ * @example
787
+ * ```tsx
788
+ * <SegmentedControl
789
+ * label={messages.t("view.label")}
790
+ * value={view}
791
+ * onValueChange={setView}
792
+ * options={[
793
+ * { value: "single", label: messages.t("view.single") },
794
+ * { value: "grid", label: messages.t("view.grid"), icon: <GridIcon />, hideLabel: true },
795
+ * ]}
796
+ * />
797
+ * ```
798
+ *
799
+ * @public
800
+ */
801
+ export declare const SegmentedControl: <Value extends string>(props: SegmentedControlProps<Value> & RefAttributes<HTMLDivElement>) => ReactElement;
802
+
803
+ /**
804
+ * One choice in a {@link SegmentedControl}.
805
+ *
806
+ * @public
807
+ */
808
+ export declare interface SegmentedControlOption<Value extends string> {
809
+ readonly value: Value;
810
+ /** The option's text, and its accessible name when `hideLabel` is set. */
811
+ readonly label: string;
812
+ /** An icon before the label. It draws with `currentColor`. */
813
+ readonly icon?: ReactNode;
814
+ /** Shows only the icon; `label` stays the accessible name. */
815
+ readonly hideLabel?: boolean;
816
+ readonly disabled?: boolean;
817
+ }
818
+
819
+ /**
820
+ * The parts of a segmented control that `classNames` can target.
821
+ *
822
+ * @public
823
+ */
824
+ export declare type SegmentedControlPart = "root" | "option" | "icon" | "label";
825
+
826
+ /**
827
+ * Props of {@link SegmentedControl}.
828
+ *
829
+ * @public
830
+ */
831
+ export declare interface SegmentedControlProps<Value extends string> extends Omit<HTMLAttributes<HTMLDivElement>, "className" | "role" | "onChange">, StyleProps<SegmentedControlPart> {
832
+ /** The group's accessible name, such as "View". Required. */
833
+ readonly label: string;
834
+ /** The selected option's value. The control is always controlled. */
835
+ readonly value: Value;
836
+ readonly onValueChange: (value: Value) => void;
837
+ readonly options: readonly SegmentedControlOption<Value>[];
838
+ /** Defaults to `medium`. */
839
+ readonly size?: "medium" | "small" | undefined;
840
+ }
841
+
842
+ /**
843
+ * The `select` icon: Lucide's `mouse-pointer-2`.
844
+ *
845
+ * @public
846
+ */
847
+ export declare function SelectIcon(props: IconProps): ReactElement;
848
+
849
+ /**
850
+ * The `skip-back` icon: Lucide's `skip-back`.
851
+ *
852
+ * @public
853
+ */
854
+ export declare function SkipBackIcon(props: IconProps): ReactElement;
855
+
856
+ /**
857
+ * The `skip-forward` icon: Lucide's `skip-forward`.
858
+ *
859
+ * @public
860
+ */
861
+ export declare function SkipForwardIcon(props: IconProps): ReactElement;
862
+
863
+ /**
864
+ * A slider for a value in a range, such as volume or zoom, on the native
865
+ * `<input type="range">`.
866
+ *
867
+ * Arrow keys move by `step`, Page Up and Page Down by `largeStep`, and Home
868
+ * and End to the ends. In right-to-left text, the slider is mirrored and the
869
+ * left and right arrows follow it, in every browser. `formatValue` gives
870
+ * screen readers the value as text.
871
+ *
872
+ * Inside a `Toolbar`, the slider keeps the arrow keys, Home and End, so
873
+ * they can't move focus past it: put it last in the toolbar. Tab still
874
+ * leaves the toolbar.
875
+ *
876
+ * It has no filled part of the track, because one would need an inline
877
+ * style, which a strict Content Security Policy blocks.
878
+ *
879
+ * @example
880
+ * ```tsx
881
+ * <Slider
882
+ * label={messages.t("player.volume")}
883
+ * min={-60}
884
+ * max={0}
885
+ * value={gain}
886
+ * onValueChange={setGain}
887
+ * formatValue={(db) => messages.t("player.decibels", { db })}
888
+ * />
889
+ * ```
890
+ *
891
+ * @public
892
+ */
893
+ export declare const Slider: ForwardRefExoticComponent<SliderProps & RefAttributes<HTMLInputElement>>;
894
+
895
+ /**
896
+ * Props of {@link Slider}. Native input props are passed through.
897
+ *
898
+ * @public
899
+ */
900
+ export declare interface SliderProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "className" | "type" | "value" | "defaultValue" | "min" | "max" | "step" | "onChange" | "aria-valuetext">, StyleProps<"root"> {
901
+ /** The value, when you control it. Leave it out to let the slider keep its own. */
902
+ readonly value?: number | undefined;
903
+ /** The starting value, when the slider keeps its own. Defaults to `min`. */
904
+ readonly defaultValue?: number | undefined;
905
+ /** Called with the new value as it changes, by pointer or keyboard. */
906
+ readonly onValueChange?: ((value: number) => void) | undefined;
907
+ /** Defaults to 0. */
908
+ readonly min?: number | undefined;
909
+ /** Defaults to 100. */
910
+ readonly max?: number | undefined;
911
+ /** The arrow keys' step, and the values the slider snaps to. Defaults to 1. */
912
+ readonly step?: number | undefined;
913
+ /**
914
+ * The Page Up and Page Down step. Defaults to a tenth of the range, rounded
915
+ * to a whole number of steps.
916
+ */
917
+ readonly largeStep?: number | undefined;
918
+ /**
919
+ * Writes the value as text for screen readers, such as "−6 dB" or "1:05",
920
+ * exposed as `aria-valuetext`. Without it, they read the number. Format
921
+ * for the user's locale, as `Intl.NumberFormat` does.
922
+ */
923
+ readonly formatValue?: ((value: number) => string) | undefined;
924
+ /**
925
+ * The accessible name, such as "Volume". Leave it out inside a `Field`,
926
+ * or when a visible `<label>` points at the slider's `id`, or
927
+ * `aria-labelledby` names it.
928
+ */
929
+ readonly label?: string | undefined;
930
+ }
931
+
932
+ /**
933
+ * The `snap` icon: Lucide's `magnet`.
934
+ *
935
+ * @public
936
+ */
937
+ export declare function SnapIcon(props: IconProps): ReactElement;
938
+
939
+ /**
940
+ * Shows that something is loading, for an unknown time. It's an
941
+ * indeterminate progress bar to assistive technology, named by `label`.
942
+ * Under reduced motion it pulses slowly instead of turning. Its size follows
943
+ * `--hm-spinner-size`.
944
+ *
945
+ * @example
946
+ * ```tsx
947
+ * <Spinner label={messages.t("pages.loading")} />
948
+ * ```
949
+ *
950
+ * @public
951
+ */
952
+ export declare const Spinner: ForwardRefExoticComponent<SpinnerProps & RefAttributes<HTMLSpanElement>>;
953
+
954
+ /**
955
+ * Props of {@link Spinner}.
956
+ *
957
+ * @public
958
+ */
959
+ export declare interface SpinnerProps extends Omit<HTMLAttributes<HTMLSpanElement>, "className" | "role" | "children">, StyleProps<"root"> {
960
+ /** What's loading. Defaults to `spinner.label` from the messages ("Loading"). */
961
+ readonly label?: string | undefined;
962
+ }
963
+
964
+ /**
965
+ * The `split` icon: Lucide's `scissors`.
966
+ *
967
+ * @public
968
+ */
969
+ export declare function SplitIcon(props: IconProps): ReactElement;
970
+
971
+ /**
972
+ * The `stop` icon: Lucide's `square`.
973
+ *
974
+ * @public
975
+ */
976
+ export declare function StopIcon(props: IconProps): ReactElement;
977
+
978
+ /**
979
+ * Styling props every component takes (STANDARDS: React API).
980
+ *
981
+ * @public
982
+ */
983
+ export declare interface StyleProps<Part extends string> {
984
+ /** Extra classes on the root element. */
985
+ readonly className?: string | undefined;
986
+ /** Extra classes on each named part. */
987
+ readonly classNames?: ClassNames<Part> | undefined;
988
+ /**
989
+ * Drops the visual styles (colours, borders, typography, motion) and keeps
990
+ * layout, focus indication and target sizes, so the component stays
991
+ * accessible while you style it yourself.
992
+ */
993
+ readonly unstyled?: boolean | undefined;
994
+ }
995
+
996
+ /**
997
+ * A validated theme. Create it with `createTheme`; its values are
998
+ * frozen and safe to write into CSS.
999
+ *
1000
+ * @public
1001
+ */
1002
+ export declare interface Theme {
1003
+ readonly colorScheme: "light" | "dark";
1004
+ /** Every token value, by name without the `--hm-` prefix. Density tokens hold comfortable values. */
1005
+ readonly tokens: Readonly<Record<string, string>>;
1006
+ /** Density token values for compact density. */
1007
+ readonly compact: Readonly<Record<string, string>>;
1008
+ /** Density token values for coarse pointers. */
1009
+ readonly coarsePointer: Readonly<Record<string, string>>;
1010
+ }
1011
+
1012
+ /**
1013
+ * A light and a dark theme used together, so `system` mode can follow the
1014
+ * operating system. Density values come from `light`.
1015
+ *
1016
+ * @public
1017
+ */
1018
+ export declare interface ThemePair {
1019
+ readonly light: Theme;
1020
+ readonly dark: Theme;
1021
+ }
1022
+
1023
+ /**
1024
+ * Applies a theme, colour mode and density to everything inside it, with CSS
1025
+ * custom properties only: no runtime styling library and no context reads in
1026
+ * components (ADR 0006).
1027
+ *
1028
+ * It renders a wrapper with `display: contents`, so it doesn't affect layout.
1029
+ * A custom theme is written as a `<style>` element, rendered on the server
1030
+ * with the rest of the page, and `system` mode is pure CSS, so nothing
1031
+ * flashes before hydration (ADR 0007). Pass a stable theme object, such as
1032
+ * one created at module level, so its CSS is generated once.
1033
+ *
1034
+ * Under a Content Security Policy, a custom theme needs a `style-src` nonce
1035
+ * source and the `nonce` prop. Without a nonce, use `themeToCss` at build
1036
+ * time instead. The built-in themes need no inline styles.
1037
+ *
1038
+ * @example
1039
+ * ```tsx
1040
+ * <ThemeProvider theme={{ light: brandLight, dark: brandDark }} mode="system" density="compact">
1041
+ * <App />
1042
+ * </ThemeProvider>
1043
+ * ```
1044
+ *
1045
+ * @public
1046
+ */
1047
+ export declare function ThemeProvider(props: ThemeProviderProps): ReactElement;
1048
+
1049
+ /**
1050
+ * Props of {@link ThemeProvider} shared by every form.
1051
+ *
1052
+ * @public
1053
+ */
1054
+ export declare interface ThemeProviderBaseProps {
1055
+ /** Density of everything inside. Inherited from above when omitted. */
1056
+ readonly density?: Density;
1057
+ /**
1058
+ * The nonce of a Content Security Policy whose `style-src` allows it.
1059
+ * Only needed with a custom theme, which renders a `<style>` element.
1060
+ */
1061
+ readonly nonce?: string;
1062
+ readonly children?: ReactNode;
1063
+ }
1064
+
1065
+ /**
1066
+ * The built-in themes, or a custom light and dark pair, with a colour mode.
1067
+ *
1068
+ * @public
1069
+ */
1070
+ export declare interface ThemeProviderModeProps extends ThemeProviderBaseProps {
1071
+ /** A custom `{ light, dark }` pair. The built-in themes when omitted. */
1072
+ readonly theme?: ThemePair;
1073
+ /** Light, dark, or follow the operating system. Defaults to `"system"`. */
1074
+ readonly mode?: ColorMode;
1075
+ }
1076
+
1077
+ /**
1078
+ * Props of {@link ThemeProvider}.
1079
+ *
1080
+ * @public
1081
+ */
1082
+ export declare type ThemeProviderProps = ThemeProviderModeProps | ThemeProviderSingleProps;
1083
+
1084
+ /**
1085
+ * A single custom theme, which has one colour scheme, so there's no mode.
1086
+ *
1087
+ * @public
1088
+ */
1089
+ export declare interface ThemeProviderSingleProps extends ThemeProviderBaseProps {
1090
+ readonly theme: Theme;
1091
+ readonly mode?: undefined;
1092
+ }
1093
+
1094
+ /**
1095
+ * A button that turns something on or off, such as loop playback or the
1096
+ * active tool, exposed as `aria-pressed`. Controlled with `pressed` and
1097
+ * `onPressedChange`, or keeping its own state from `defaultPressed`.
1098
+ *
1099
+ * Its label names what it turns on and never changes with the state: screen
1100
+ * readers announce the state. For a button whose label changes, such as
1101
+ * play and pause, use `IconButton` or `Button` and swap the label instead.
1102
+ *
1103
+ * Inside a `Toolbar`, it's a toolbar item like any button: arrow keys reach
1104
+ * it, and Space or Enter toggles it.
1105
+ *
1106
+ * @example
1107
+ * ```tsx
1108
+ * <ToggleButton
1109
+ * label={messages.t("player.loop")}
1110
+ * icon={<LoopIcon />}
1111
+ * pressed={loop}
1112
+ * onPressedChange={setLoop}
1113
+ * />
1114
+ * ```
1115
+ *
1116
+ * @public
1117
+ */
1118
+ export declare const ToggleButton: ForwardRefExoticComponent<ToggleButtonProps & RefAttributes<HTMLButtonElement>>;
1119
+
1120
+ /**
1121
+ * Props every {@link ToggleButton} takes, with or without visible text.
1122
+ *
1123
+ * @public
1124
+ */
1125
+ export declare interface ToggleButtonBaseProps extends Omit<ButtonProps, "variant" | "pressed" | "aria-pressed" | "children" | "startIcon" | "endIcon" | "classNames"> {
1126
+ /** Defaults to `secondary`. */
1127
+ readonly variant?: ToggleButtonVariant | undefined;
1128
+ /** Whether it's on, when you control it. Leave it out to let the button keep its own state. */
1129
+ readonly pressed?: boolean | undefined;
1130
+ /** Whether it starts on, when it keeps its own state. Defaults to `false`. */
1131
+ readonly defaultPressed?: boolean | undefined;
1132
+ /**
1133
+ * Called with the new state when the button is activated. Calling
1134
+ * `event.preventDefault()` in `onClick` stops the change.
1135
+ */
1136
+ readonly onPressedChange?: ((pressed: boolean) => void) | undefined;
1137
+ }
1138
+
1139
+ /**
1140
+ * A square toggle button with only an icon.
1141
+ *
1142
+ * @public
1143
+ */
1144
+ export declare interface ToggleButtonIconProps extends ToggleButtonBaseProps {
1145
+ /** The icon. It draws with `currentColor`. */
1146
+ readonly icon: ReactNode;
1147
+ /** The accessible name. Required, because the button shows no text. It stays the same in both states. */
1148
+ readonly label: string;
1149
+ /** Extra classes on the root and the icon. */
1150
+ readonly classNames?: ClassNames<"root" | "icon"> | undefined;
1151
+ readonly children?: undefined;
1152
+ readonly startIcon?: undefined;
1153
+ readonly endIcon?: undefined;
1154
+ }
1155
+
1156
+ /**
1157
+ * Props of {@link ToggleButton}: visible text, or an icon with a `label`.
1158
+ *
1159
+ * @public
1160
+ */
1161
+ export declare type ToggleButtonProps = ToggleButtonTextProps | ToggleButtonIconProps;
1162
+
1163
+ /**
1164
+ * A toggle button with visible text, and optional icons beside it.
1165
+ *
1166
+ * @public
1167
+ */
1168
+ export declare interface ToggleButtonTextProps extends ToggleButtonBaseProps {
1169
+ /** The label. It must say what the button turns on, and stay the same in both states. */
1170
+ readonly children: ReactNode;
1171
+ /** An icon before the label. It's decorative, and draws with `currentColor`. */
1172
+ readonly startIcon?: ReactNode;
1173
+ /** An icon after the label. */
1174
+ readonly endIcon?: ReactNode;
1175
+ /** Extra classes per part. */
1176
+ readonly classNames?: ClassNames<ButtonPart> | undefined;
1177
+ readonly icon?: undefined;
1178
+ readonly label?: undefined;
1179
+ }
1180
+
1181
+ /**
1182
+ * How prominent a toggle button is: `secondary` (the default), or `quiet` for
1183
+ * toolbars. There's no `primary` or `danger`: their solid fill would make a
1184
+ * toggle that's off look more active than one that's on.
1185
+ *
1186
+ * @public
1187
+ */
1188
+ export declare type ToggleButtonVariant = Extract<ButtonVariant, "secondary" | "quiet">;
1189
+
1190
+ /**
1191
+ * A toolbar (WAI-ARIA `toolbar`): one Tab stop, arrow keys between its items,
1192
+ * Home and End to the ends. Items are any focusable descendants, such as
1193
+ * `Button`, `IconButton` and `SegmentedControl`. Disabled items that should
1194
+ * stay discoverable use `focusableWhenDisabled`.
1195
+ *
1196
+ * @example
1197
+ * ```tsx
1198
+ * <Toolbar label={messages.t("toolbar.label")}>
1199
+ * <ToolbarGroup label={messages.t("toolbar.history")}>
1200
+ * <IconButton label={messages.t("toolbar.undo")} icon={<UndoIcon />} />
1201
+ * </ToolbarGroup>
1202
+ * <ToolbarSeparator />
1203
+ * </Toolbar>
1204
+ * ```
1205
+ *
1206
+ * @public
1207
+ */
1208
+ export declare const Toolbar: ForwardRefExoticComponent<ToolbarProps & RefAttributes<HTMLDivElement>>;
1209
+
1210
+ /**
1211
+ * Related items in a toolbar, announced together as a named group. Arrow keys
1212
+ * move across groups as if they weren't there.
1213
+ *
1214
+ * @public
1215
+ */
1216
+ export declare const ToolbarGroup: ForwardRefExoticComponent<ToolbarGroupProps & RefAttributes<HTMLDivElement>>;
1217
+
1218
+ /**
1219
+ * Props of {@link ToolbarGroup}.
1220
+ *
1221
+ * @public
1222
+ */
1223
+ export declare interface ToolbarGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, "role"> {
1224
+ /** The group's accessible name, such as "Zoom". Required. */
1225
+ readonly label: string;
1226
+ }
1227
+
1228
+ /**
1229
+ * Props of {@link Toolbar}.
1230
+ *
1231
+ * @public
1232
+ */
1233
+ export declare interface ToolbarProps extends Omit<HTMLAttributes<HTMLDivElement>, "className" | "role">, StyleProps<"root"> {
1234
+ /** The toolbar's accessible name, such as "Page tools". Required. */
1235
+ readonly label: string;
1236
+ /** Defaults to `horizontal`. Arrow keys follow it. */
1237
+ readonly orientation?: "horizontal" | "vertical" | undefined;
1238
+ }
1239
+
1240
+ /**
1241
+ * A line between toolbar items: a native `<hr>`, so it's a separator to
1242
+ * assistive technology. It isn't focusable, and is oriented across the
1243
+ * toolbar.
1244
+ *
1245
+ * @public
1246
+ */
1247
+ export declare const ToolbarSeparator: ForwardRefExoticComponent<ToolbarSeparatorProps & RefAttributes<HTMLHRElement>>;
1248
+
1249
+ /**
1250
+ * Props of {@link ToolbarSeparator}.
1251
+ *
1252
+ * @public
1253
+ */
1254
+ export declare type ToolbarSeparatorProps = Omit<HTMLAttributes<HTMLHRElement>, "children">;
1255
+
1256
+ /**
1257
+ * The `trim-end` icon: Lucide's `arrow-left-from-line`.
1258
+ *
1259
+ * @public
1260
+ */
1261
+ export declare function TrimEndIcon(props: IconProps): ReactElement;
1262
+
1263
+ /**
1264
+ * The `trim-start` icon: Lucide's `arrow-right-from-line`.
1265
+ *
1266
+ * @public
1267
+ */
1268
+ export declare function TrimStartIcon(props: IconProps): ReactElement;
1269
+
1270
+ /**
1271
+ * Messages that include `ui`'s text: any sdk-core `Messages` object whose
1272
+ * catalogue spreads `uiMessages`.
1273
+ *
1274
+ * @public
1275
+ */
1276
+ export declare type UiMessages = Messages<typeof uiMessages>;
1277
+
1278
+ /**
1279
+ * English text for `@hussmartinez/ui`'s error codes. Applications and SDKs
1280
+ * spread it into their catalogue, next to `sdkCoreMessages`, so
1281
+ * `messages.error()` can describe a `UiError`. Components add their
1282
+ * text here as they arrive.
1283
+ *
1284
+ * @example
1285
+ * ```ts
1286
+ * export const en = defineMessages({ ...sdkCoreMessages, ...uiMessages });
1287
+ * ```
1288
+ *
1289
+ * @public
1290
+ */
1291
+ export declare const uiMessages: {
1292
+ readonly "dialog.close": "Close";
1293
+ readonly "fileDropZone.choose": "Choose a file";
1294
+ readonly "fileDropZone.chooseMultiple": "Choose files";
1295
+ readonly "fileDropZone.hint": "or drop it here";
1296
+ readonly "fileDropZone.hintMultiple": "or drop them here";
1297
+ readonly "progress.label": "Progress";
1298
+ readonly "spinner.label": "Loading";
1299
+ readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
1300
+ readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
1301
+ };
1302
+
1303
+ /**
1304
+ * Gives `ui`'s components their text (ADR 0014). SDKs and applications pass
1305
+ * their message catalogue once, here; a component's own text props still win.
1306
+ * Without a provider, components use English.
1307
+ *
1308
+ * @example
1309
+ * ```tsx
1310
+ * const messages = createMessages({ ...sdkCoreMessages, ...uiMessages, ...en }, { locale });
1311
+ * <UiMessagesProvider messages={messages}>{editor}</UiMessagesProvider>
1312
+ * ```
1313
+ *
1314
+ * @public
1315
+ */
1316
+ export declare function UiMessagesProvider({ messages, children }: UiMessagesProviderProps): ReactElement;
1317
+
1318
+ /**
1319
+ * Props of {@link UiMessagesProvider}.
1320
+ *
1321
+ * @public
1322
+ */
1323
+ export declare interface UiMessagesProviderProps {
1324
+ /** Your catalogue's messages, created with sdk-core's `createMessages`. */
1325
+ readonly messages: UiMessages;
1326
+ readonly children?: ReactNode;
1327
+ }
1328
+
1329
+ /**
1330
+ * The `undo` icon: Lucide's `undo-2`, mirrored in right-to-left text.
1331
+ *
1332
+ * @public
1333
+ */
1334
+ export declare function UndoIcon(props: IconProps): ReactElement;
1335
+
1336
+ /**
1337
+ * The `upload` icon: Lucide's `upload`.
1338
+ *
1339
+ * @public
1340
+ */
1341
+ export declare function UploadIcon(props: IconProps): ReactElement;
1342
+
1343
+ /**
1344
+ * The `announce` function of the closest {@link AnnouncerProvider}. Without
1345
+ * one, announcing does nothing and warns in development.
1346
+ *
1347
+ * @example
1348
+ * ```tsx
1349
+ * const announce = useAnnounce();
1350
+ * announce(messages.t("result.saved", { size }));
1351
+ * ```
1352
+ *
1353
+ * @public
1354
+ */
1355
+ export declare function useAnnounce(): Announce;
1356
+
1357
+ /**
1358
+ * The platform whose keyboard conventions apply, for shortcut labels and for
1359
+ * sdk-core's `createShortcutRegistry({ platform })`: `"apple"` on macOS, iOS
1360
+ * and iPadOS, where `Mod` is `Meta` (⌘), and `"other"` elsewhere, where it's
1361
+ * `Control`.
1362
+ *
1363
+ * A server can't know the platform, so the server render and hydration both
1364
+ * use `"other"`, and Apple devices switch to their keys in the render right
1365
+ * after hydration. That keeps hydration free of mismatches. Never read
1366
+ * `navigator` during render for this.
1367
+ *
1368
+ * @example
1369
+ * ```tsx
1370
+ * const platform = usePlatform();
1371
+ * const shortcuts = useMemo(() => createShortcutRegistry({ platform, tools }), [platform, tools]);
1372
+ * ```
1373
+ *
1374
+ * @public
1375
+ */
1376
+ export declare function usePlatform(): Platform;
1377
+
1378
+ /**
1379
+ * The messages from the closest {@link UiMessagesProvider}, or English.
1380
+ *
1381
+ * @public
1382
+ */
1383
+ export declare function useUiMessages(): UiMessages;
1384
+
1385
+ /**
1386
+ * Content for assistive technology only: hidden on screen, but read out and
1387
+ * part of the accessible name of its parent. It has no `unstyled` prop,
1388
+ * because hiding is its whole purpose.
1389
+ *
1390
+ * @public
1391
+ */
1392
+ export declare const VisuallyHidden: ForwardRefExoticComponent<VisuallyHiddenProps & RefAttributes<HTMLElement>>;
1393
+
1394
+ /**
1395
+ * Props of {@link VisuallyHidden}.
1396
+ *
1397
+ * @public
1398
+ */
1399
+ export declare interface VisuallyHiddenProps extends HTMLAttributes<HTMLElement> {
1400
+ /** The element to render. Defaults to `span`. */
1401
+ readonly as?: "span" | "div";
1402
+ }
1403
+
1404
+ /**
1405
+ * The `volume` icon: Lucide's `volume-2`.
1406
+ *
1407
+ * @public
1408
+ */
1409
+ export declare function VolumeIcon(props: IconProps): ReactElement;
1410
+
1411
+ /**
1412
+ * The `warning` icon: Lucide's `triangle-exclamation-point`.
1413
+ *
1414
+ * @public
1415
+ */
1416
+ export declare function WarningIcon(props: IconProps): ReactElement;
1417
+
1418
+ /**
1419
+ * The `zoom-in` icon: Lucide's `zoom-in`.
1420
+ *
1421
+ * @public
1422
+ */
1423
+ export declare function ZoomInIcon(props: IconProps): ReactElement;
1424
+
1425
+ /**
1426
+ * The `zoom-out` icon: Lucide's `zoom-out`.
1427
+ *
1428
+ * @public
1429
+ */
1430
+ export declare function ZoomOutIcon(props: IconProps): ReactElement;
1431
+
1432
+ export { }