@hydrateless/react 0.10.0 → 0.11.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.
@@ -0,0 +1,760 @@
1
+ import * as react from 'react';
2
+ import { RefObject, DependencyList, HTMLAttributes, ReactNode, ButtonHTMLAttributes, LiHTMLAttributes, AnchorHTMLAttributes, ReactElement, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, LabelHTMLAttributes } from 'react';
3
+ import { EnhancerHandle, EnhanceTabsOptions, EnhanceDropdownOptions, EnhanceMenuOptions, EnhancePopoverOptions, EnhanceTooltipOptions, ToastApi, EnhanceComboboxOptions } from '@hydrateless/enhancers';
4
+ export { AccordionApi, ComboboxApi, CommandApi, DisclosureApi, Disposer, DrawerApi, DropdownApi, EnhancerHandle, MenuApi, ModalApi, PopoverApi, TabsApi, ToastApi, ToastIntent, ToastOptions, TocApi, TooltipApi } from '@hydrateless/enhancers';
5
+
6
+ /**
7
+ * Attach any Hydrateless enhancer to the element in `ref` for the lifetime of a
8
+ * component. Returns a ref holding the enhancer's imperative API (for example
9
+ * `setValue`/`setOpen`), or `null` while nothing is enhanced. The instance is
10
+ * attached once on mount and destroyed on unmount; when `deps` change, options
11
+ * are updated in place via `handle.update()` so open overlays and active state
12
+ * are preserved instead of torn down. If the element isn't rendered on mount,
13
+ * the enhancer attaches on the first `deps` change after it appears.
14
+ *
15
+ * Function-valued options (`onValueChange`, `onOpenChange`, ...) always call
16
+ * the handler from the latest render, so they never need to appear in `deps`.
17
+ * List non-function options that should update the enhancer in `deps`.
18
+ *
19
+ * ```tsx
20
+ * const ref = useRef<HTMLDivElement>(null);
21
+ * const api = useEnhancer(ref, enhanceTabs, { onValueChange: setTab });
22
+ * // api.current?.setValue('install');
23
+ * return <div className="hl-tabs" data-hl-tabs ref={ref}>...</div>;
24
+ * ```
25
+ */
26
+ declare function useEnhancer<Options extends object, Api>(ref: RefObject<HTMLElement | null>, enhancer: (container: HTMLElement, options?: Partial<Options>) => EnhancerHandle<Api, Options>, options?: Partial<Options>, deps?: DependencyList): RefObject<Api | null>;
27
+
28
+ /** Props for {@link Accordion}. */
29
+ interface AccordionProps extends HTMLAttributes<HTMLDivElement> {
30
+ /** Allow more than one panel to stay open at a time. */
31
+ allowMultiple?: boolean;
32
+ /** Controlled list of open item values (pair with `onValueChange`). */
33
+ value?: string[];
34
+ /** Initially open item values for uncontrolled usage. */
35
+ defaultValue?: string[];
36
+ /** Called with the open item values after every change. */
37
+ onValueChange?: (value: string[]) => void;
38
+ }
39
+ /**
40
+ * Accordion of native `<details>` items. Item values come from each
41
+ * `<AccordionItem value>`, defaulting to the index, and each item's `open`
42
+ * attribute is rendered from the value so server output already shows the
43
+ * right panels. Open state works uncontrolled (`defaultValue`) or controlled
44
+ * (`value` + `onValueChange`).
45
+ */
46
+ declare const Accordion: react.ForwardRefExoticComponent<AccordionProps & react.RefAttributes<HTMLDivElement>>;
47
+ /** Props for {@link AccordionItem}. */
48
+ interface AccordionItemProps extends Omit<HTMLAttributes<HTMLDetailsElement>, 'title'> {
49
+ /** The always-visible header content. */
50
+ summary: ReactNode;
51
+ /** Stable value identifying this item; defaults to its index. */
52
+ value?: string;
53
+ }
54
+ /** A single collapsible item within an {@link Accordion}, rendered as a native `<details>`. */
55
+ declare const AccordionItem: react.ForwardRefExoticComponent<AccordionItemProps & react.RefAttributes<HTMLDetailsElement>>;
56
+
57
+ /** Props for {@link Disclosure}. */
58
+ interface DisclosureProps extends Omit<HTMLAttributes<HTMLDetailsElement>, 'title'> {
59
+ /** The always-visible header content. */
60
+ summary: ReactNode;
61
+ /** Controlled open state (pair with `onOpenChange`). */
62
+ open?: boolean;
63
+ /** Open the disclosure initially for uncontrolled usage. */
64
+ defaultOpen?: boolean;
65
+ /** Called after the disclosure opens or closes. */
66
+ onOpenChange?: (open: boolean) => void;
67
+ /**
68
+ * Group name. Disclosures sharing a `name` are exclusive: the browser closes
69
+ * the others when one opens, with no JavaScript.
70
+ */
71
+ name?: string;
72
+ }
73
+ /**
74
+ * A single expandable section built on native `<details>`, which handles
75
+ * open/close (and exclusive groups, via the `name` attribute) on its own.
76
+ * Open state works uncontrolled (`defaultOpen`) or controlled (`open` +
77
+ * `onOpenChange`).
78
+ */
79
+ declare const Disclosure: react.ForwardRefExoticComponent<DisclosureProps & react.RefAttributes<HTMLDetailsElement>>;
80
+
81
+ /** Props for {@link Tabs}. */
82
+ interface TabsProps extends HTMLAttributes<HTMLDivElement> {
83
+ /** `manual` (default): arrows move focus, Enter/Space activates. `automatic`: arrows activate immediately. */
84
+ activation?: EnhanceTabsOptions['activation'];
85
+ orientation?: EnhanceTabsOptions['orientation'];
86
+ /** Controlled value of the selected tab (pair with `onValueChange`). */
87
+ value?: string;
88
+ /** Initial value for uncontrolled usage. */
89
+ defaultValue?: string;
90
+ /** Called with the new tab value after every selection change. */
91
+ onValueChange?: (value: string) => void;
92
+ }
93
+ /**
94
+ * Tabbed interface root. Compose with `<TabList>`, `<Tab>`, and `<TabPanel>`.
95
+ * The role-based markup, `aria-selected`, `hidden`, and roving `tabindex` are
96
+ * all rendered from the value, so server output is correct before the
97
+ * enhancer adds keyboard navigation. Tab values come from each `<Tab value>`,
98
+ * defaulting to the index; panels match tabs by position. Selection works
99
+ * uncontrolled (`defaultValue`) or controlled (`value` + `onValueChange`).
100
+ *
101
+ * ```tsx
102
+ * <Tabs value={tab} onValueChange={setTab}>
103
+ * <TabList>
104
+ * <Tab value="overview">Overview</Tab>
105
+ * <Tab value="install">Install</Tab>
106
+ * </TabList>
107
+ * <TabPanel>Zero runtime by default.</TabPanel>
108
+ * <TabPanel>npm install hydrateless</TabPanel>
109
+ * </Tabs>
110
+ * ```
111
+ */
112
+ declare const Tabs: react.ForwardRefExoticComponent<TabsProps & react.RefAttributes<HTMLDivElement>>;
113
+ /** Props for {@link TabList}. */
114
+ type TabListProps = HTMLAttributes<HTMLDivElement>;
115
+ /** The row of tab triggers. Renders `role="tablist"`. */
116
+ declare const TabList: react.ForwardRefExoticComponent<TabListProps & react.RefAttributes<HTMLDivElement>>;
117
+ /** Props for {@link Tab}. */
118
+ interface TabProps extends ButtonHTMLAttributes<HTMLButtonElement> {
119
+ /** Stable value identifying this tab; defaults to its index. */
120
+ value?: string;
121
+ }
122
+ /** A single tab trigger. Renders `role="tab"` with `aria-selected` from the Tabs value. */
123
+ declare const Tab: react.ForwardRefExoticComponent<TabProps & react.RefAttributes<HTMLButtonElement>>;
124
+ /** Props for {@link TabPanel}. */
125
+ type TabPanelProps = HTMLAttributes<HTMLDivElement>;
126
+ /** Content for the tab at the same position. Renders `role="tabpanel"`, hidden unless selected. */
127
+ declare const TabPanel: react.ForwardRefExoticComponent<TabPanelProps & react.RefAttributes<HTMLDivElement>>;
128
+
129
+ /** Props for {@link Dropdown}. */
130
+ interface DropdownProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
131
+ /** Placement used by the JS positioning fallback. Defaults to `bottom-start`. */
132
+ placement?: EnhanceDropdownOptions['placement'];
133
+ /** Close the menu after an item is activated. Defaults to `true`. */
134
+ closeOnSelect?: boolean;
135
+ /** Controlled open state (pair with `onOpenChange`). */
136
+ open?: boolean;
137
+ /** Open the menu initially for uncontrolled usage. */
138
+ defaultOpen?: boolean;
139
+ /** Called after the menu opens or closes. */
140
+ onOpenChange?: (open: boolean) => void;
141
+ /**
142
+ * Called with the item's value when a menu item is activated. For
143
+ * `menuitemcheckbox`/`menuitemradio` items, `checked` is the new state.
144
+ */
145
+ onSelect?: (value: string, item: HTMLElement, checked?: boolean) => void;
146
+ }
147
+ /**
148
+ * Button-triggered menu following the WAI-ARIA menu-button pattern. Compose with
149
+ * `<DropdownTrigger>`, `<DropdownMenu>`, `<DropdownItem>`, `<DropdownGroup>`,
150
+ * and `<DropdownSeparator>`. The menu renders as a native `popover` the
151
+ * trigger opens through `popovertarget`, so it works before hydration; the
152
+ * enhancer adds keyboard navigation, typeahead, checkable items, and focus
153
+ * return. Open state works uncontrolled or controlled.
154
+ *
155
+ * ```tsx
156
+ * <Dropdown onSelect={(value) => run(value)}>
157
+ * <DropdownTrigger>Actions</DropdownTrigger>
158
+ * <DropdownMenu>
159
+ * <DropdownItem value="edit">Edit</DropdownItem>
160
+ * <DropdownSeparator />
161
+ * <DropdownItem value="delete">Delete</DropdownItem>
162
+ * </DropdownMenu>
163
+ * </Dropdown>
164
+ * ```
165
+ */
166
+ declare const Dropdown: react.ForwardRefExoticComponent<DropdownProps & react.RefAttributes<HTMLDivElement>>;
167
+ /** Props for {@link DropdownTrigger}. */
168
+ type DropdownTriggerProps = ButtonHTMLAttributes<HTMLButtonElement>;
169
+ /** The button that opens the menu; carries `popovertarget` so it works pre-hydration. */
170
+ declare const DropdownTrigger: react.ForwardRefExoticComponent<DropdownTriggerProps & react.RefAttributes<HTMLButtonElement>>;
171
+ /** Props for {@link DropdownMenu}. */
172
+ type DropdownMenuProps = HTMLAttributes<HTMLUListElement>;
173
+ /** The menu surface (a native `popover`); holds items, groups, and separators. */
174
+ declare const DropdownMenu: react.ForwardRefExoticComponent<DropdownMenuProps & react.RefAttributes<HTMLUListElement>>;
175
+ /** Props for {@link DropdownItem}. */
176
+ interface DropdownItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'value'> {
177
+ /** Value reported to `onSelect`; defaults to the item's text. */
178
+ value?: string;
179
+ /** `menuitemcheckbox` toggles; `menuitemradio` is exclusive within its group. Defaults to `menuitem`. */
180
+ role?: 'menuitem' | 'menuitemcheckbox' | 'menuitemradio';
181
+ /** Checked state for checkable roles (rendered as `aria-checked`). */
182
+ checked?: boolean;
183
+ /** Skip the item in keyboard navigation and ignore activation. */
184
+ disabled?: boolean;
185
+ }
186
+ /** A menu item. Renders `<li><button role="menuitem">`. */
187
+ declare const DropdownItem: react.ForwardRefExoticComponent<DropdownItemProps & react.RefAttributes<HTMLButtonElement>>;
188
+ /** Props for {@link DropdownGroup}. */
189
+ interface DropdownGroupProps extends HTMLAttributes<HTMLUListElement> {
190
+ /** Accessible name of the group. */
191
+ label?: string;
192
+ }
193
+ /**
194
+ * A labelled `role="group"` of items; `menuitemradio` items inside it are
195
+ * exclusive with each other.
196
+ */
197
+ declare const DropdownGroup: react.ForwardRefExoticComponent<DropdownGroupProps & react.RefAttributes<HTMLUListElement>>;
198
+ /** Props for {@link DropdownSeparator}. */
199
+ type DropdownSeparatorProps = Omit<LiHTMLAttributes<HTMLLIElement>, 'role'>;
200
+ /** A visual divider between groups of items. */
201
+ declare const DropdownSeparator: react.ForwardRefExoticComponent<DropdownSeparatorProps & react.RefAttributes<HTMLLIElement>>;
202
+
203
+ /** Props for {@link Menu}. */
204
+ interface MenuProps extends Omit<HTMLAttributes<HTMLUListElement>, 'onSelect' | 'defaultValue'> {
205
+ /** Layout of the top-level items. Defaults to `horizontal` (a menubar). */
206
+ orientation?: EnhanceMenuOptions['orientation'];
207
+ /** Controlled value of the open submenu, or `null` when all are closed (pair with `onValueChange`). */
208
+ value?: string | null;
209
+ /** Submenu to open initially for uncontrolled usage. */
210
+ defaultValue?: string | null;
211
+ /** Called with the open submenu's value (or `null`) after every change. */
212
+ onValueChange?: (value: string | null) => void;
213
+ /**
214
+ * Called with the item's value when a leaf item is activated. For
215
+ * `menuitemcheckbox`/`menuitemradio` items, `checked` is the new state.
216
+ */
217
+ onSelect?: (value: string, item: HTMLElement, checked?: boolean) => void;
218
+ }
219
+ /**
220
+ * Menubar / navigation menu with single-level submenus rendered in the top
221
+ * layer. Compose with `<MenuItem>` for leaf items and `<MenuSubmenu>` for
222
+ * items that open a flyout. The enhancer wires roving tabindex,
223
+ * orientation-aware arrow navigation, typeahead, and submenu toggling; the
224
+ * open submenu is the component's value (from `<MenuSubmenu value>`,
225
+ * defaulting to the index).
226
+ *
227
+ * ```tsx
228
+ * <Menu orientation="horizontal">
229
+ * <MenuItem href="/">Home</MenuItem>
230
+ * <MenuSubmenu label="Resources" value="resources">
231
+ * <MenuItem href="/docs">Docs</MenuItem>
232
+ * </MenuSubmenu>
233
+ * </Menu>
234
+ * ```
235
+ */
236
+ declare const Menu: react.ForwardRefExoticComponent<MenuProps & react.RefAttributes<HTMLUListElement>>;
237
+ /** Props for {@link MenuItem}. */
238
+ interface MenuItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'href' | 'type' | 'value'> {
239
+ /** Render as a link instead of a button. */
240
+ href?: string;
241
+ /** Value reported to `onSelect`; defaults to the item's text. */
242
+ value?: string;
243
+ /** `menuitemcheckbox` toggles; `menuitemradio` is exclusive within its menu. Defaults to `menuitem`. */
244
+ role?: 'menuitem' | 'menuitemcheckbox' | 'menuitemradio';
245
+ /** Checked state for checkable roles (rendered as `aria-checked`). */
246
+ checked?: boolean;
247
+ /** Skip the item in keyboard navigation and ignore activation. */
248
+ disabled?: boolean;
249
+ /** Extra attributes for the `<a>` when `href` is set. */
250
+ anchorProps?: AnchorHTMLAttributes<HTMLAnchorElement>;
251
+ }
252
+ /** A leaf menu entry. With `href` it renders an anchor, otherwise a button. */
253
+ declare const MenuItem: react.ForwardRefExoticComponent<MenuItemProps & react.RefAttributes<HTMLElement>>;
254
+ /** Props for {@link MenuSubmenu}. */
255
+ interface MenuSubmenuProps extends Omit<HTMLAttributes<HTMLUListElement>, 'value'> {
256
+ /** Content of the top-level trigger. */
257
+ label: ReactNode;
258
+ /** Stable value identifying this submenu; defaults to its index among top-level items. */
259
+ value?: string;
260
+ /** Skip the trigger in keyboard navigation and keep the submenu closed. */
261
+ disabled?: boolean;
262
+ /** Extra attributes for the trigger button. */
263
+ triggerProps?: ButtonHTMLAttributes<HTMLButtonElement>;
264
+ }
265
+ /**
266
+ * A top-level menu entry that opens a flyout of `<MenuItem>`s. Rest props go
267
+ * to the submenu list (`role="menu"`); use `triggerProps` for the button.
268
+ */
269
+ declare const MenuSubmenu: react.ForwardRefExoticComponent<MenuSubmenuProps & react.RefAttributes<HTMLUListElement>>;
270
+
271
+ /** Props for {@link Modal}. */
272
+ interface ModalProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
273
+ /** Controlled open state (pair with `onOpenChange`). */
274
+ open?: boolean;
275
+ /** Open the dialog initially for uncontrolled usage. */
276
+ defaultOpen?: boolean;
277
+ /** Called after the dialog opens or closes (Escape, backdrop, close buttons). */
278
+ onOpenChange?: (open: boolean) => void;
279
+ /** Let Escape and backdrop clicks close the dialog. Defaults to `true`. */
280
+ closeOnBackdrop?: boolean;
281
+ }
282
+ /**
283
+ * Dialog overlay built on the native `<dialog>` element and the modal
284
+ * enhancer, which adds a focus trap, body scroll-lock, and a background
285
+ * `inert` barrier. Compose with `<ModalTrigger>`, `<ModalHeader>`,
286
+ * `<ModalBody>`, and `<ModalFooter>`. Open state works uncontrolled
287
+ * (`defaultOpen`, or a `<ModalTrigger>` invoker button) or controlled
288
+ * (`open` + `onOpenChange`).
289
+ */
290
+ declare const Modal: react.ForwardRefExoticComponent<ModalProps & react.RefAttributes<HTMLDialogElement>>;
291
+
292
+ /** Props for {@link Drawer}. */
293
+ interface DrawerProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
294
+ /** Controlled open state (pair with `onOpenChange`). */
295
+ open?: boolean;
296
+ /** Open the drawer initially for uncontrolled usage. */
297
+ defaultOpen?: boolean;
298
+ /** Called after the drawer opens or closes (Escape, backdrop, close buttons). */
299
+ onOpenChange?: (open: boolean) => void;
300
+ /** Logical edge the panel slides in from (`end` follows the writing direction). Defaults to `end`. */
301
+ side?: 'start' | 'end';
302
+ /** Let Escape and backdrop clicks close the drawer. Defaults to `true`. */
303
+ closeOnBackdrop?: boolean;
304
+ }
305
+ /**
306
+ * Off-canvas panel built on the native `<dialog>` element and the drawer
307
+ * enhancer (focus trap, scroll-lock, background `inert`). Mirrors
308
+ * {@link Modal} but slides in from the chosen `side`. Compose with
309
+ * `<DrawerTrigger>`, `<DrawerHeader>`, `<DrawerBody>`, and `<DrawerFooter>`.
310
+ * Open state works uncontrolled (`defaultOpen`, or a `<DrawerTrigger>` invoker
311
+ * button) or controlled (`open` + `onOpenChange`).
312
+ */
313
+ declare const Drawer: react.ForwardRefExoticComponent<DrawerProps & react.RefAttributes<HTMLDialogElement>>;
314
+
315
+ /** Props for {@link Popover}. */
316
+ interface PopoverProps extends HTMLAttributes<HTMLDivElement> {
317
+ /** Controlled open state (pair with `onOpenChange`). */
318
+ open?: boolean;
319
+ /** Show the popover initially for uncontrolled usage. */
320
+ defaultOpen?: boolean;
321
+ /** Called after the popover shows or hides (including the browser's light-dismiss). */
322
+ onOpenChange?: (open: boolean) => void;
323
+ /** Placement used by the JS positioning fallback. Defaults to `bottom`. */
324
+ placement?: EnhancePopoverOptions['placement'];
325
+ /** Open on pointer hover and focus instead of click. */
326
+ hover?: boolean;
327
+ }
328
+ /**
329
+ * Floating content built on the native Popover API. The surface lives in the
330
+ * top layer with light-dismiss and Escape handled by the browser; visibility
331
+ * works uncontrolled (`defaultOpen`, or a `<PopoverTrigger>` button) or
332
+ * controlled (`open` + `onOpenChange`). Position it with the
333
+ * `hydrateless/popover.css` styles.
334
+ */
335
+ declare const Popover: react.ForwardRefExoticComponent<PopoverProps & react.RefAttributes<HTMLDivElement>>;
336
+
337
+ /** Props for {@link Tooltip}. */
338
+ interface TooltipProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'content'> {
339
+ /** The hint shown on hover/focus. */
340
+ content: ReactNode;
341
+ /** A single focusable element that triggers the tooltip. */
342
+ children: ReactElement;
343
+ /** Preferred placement relative to the trigger. Defaults to `top`. */
344
+ placement?: EnhanceTooltipOptions['placement'];
345
+ /** Delay in ms before showing on hover. */
346
+ showDelay?: number;
347
+ /** Grace period in ms before hiding. */
348
+ hideDelay?: number;
349
+ /** Controlled visibility (pair with `onOpenChange`). */
350
+ open?: boolean;
351
+ /** Called after the tooltip shows or hides. */
352
+ onOpenChange?: (open: boolean) => void;
353
+ }
354
+ /**
355
+ * Adds an accessible tooltip to a focusable trigger. The trigger is linked to
356
+ * the tip with `aria-describedby`; the enhancer shows it on hover/focus with
357
+ * delays, promotes it to the top layer, and dismisses it on Escape.
358
+ *
359
+ * ```tsx
360
+ * <Tooltip content="Save (Cmd+S)">
361
+ * <Button icon aria-label="Save">...</Button>
362
+ * </Tooltip>
363
+ * ```
364
+ */
365
+ declare const Tooltip: react.ForwardRefExoticComponent<TooltipProps & react.RefAttributes<HTMLSpanElement>>;
366
+
367
+ /** Props for {@link Switch}. */
368
+ interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
369
+ children?: ReactNode;
370
+ }
371
+ /**
372
+ * Toggle switch built on a native checkbox with `role="switch"`. CSS-only.
373
+ * Inside a {@link Field} it picks up `id`, `aria-describedby`, `aria-invalid`,
374
+ * and `required`.
375
+ */
376
+ declare const Switch: react.ForwardRefExoticComponent<SwitchProps & react.RefAttributes<HTMLInputElement>>;
377
+
378
+ /** Props for {@link Toc}. */
379
+ interface TocProps extends HTMLAttributes<HTMLElement> {
380
+ /** CSS selector for the content root to scan for headings. */
381
+ contentSelector?: string;
382
+ /** Comma-separated heading selector, e.g. `"h2,h3"`. */
383
+ headings?: string;
384
+ /** Highlight the current section while scrolling. */
385
+ scrollSpy?: boolean;
386
+ }
387
+ /** Auto-generated table of contents with optional scroll-spy. */
388
+ declare const Toc: react.ForwardRefExoticComponent<TocProps & react.RefAttributes<HTMLElement>>;
389
+
390
+ /** Props for {@link ToastRegion}. */
391
+ interface ToastRegionProps extends HTMLAttributes<HTMLDivElement> {
392
+ /** Default auto-dismiss duration in ms for toasts shown without one. */
393
+ duration?: number;
394
+ /** Called after a toast appears (`open: true`) or is dismissed (`open: false`). */
395
+ onOpenChange?: (open: boolean, toast: HTMLElement) => void;
396
+ }
397
+ /**
398
+ * The polite live region toasts render into. Render once near the root of
399
+ * your app to control where toasts appear; it enhances on mount and adopts
400
+ * declarative `data-hl-toast-trigger` buttons anywhere in the document. If
401
+ * omitted, the first `show()` call creates a region at the end of `<body>`.
402
+ */
403
+ declare const ToastRegion: react.ForwardRefExoticComponent<ToastRegionProps & react.RefAttributes<HTMLDivElement>>;
404
+ /**
405
+ * Access the imperative toast API: `show(message, { duration, intent })`
406
+ * returns the toast element, `dismiss(toast)` removes it. Works with or
407
+ * without a mounted {@link ToastRegion}.
408
+ *
409
+ * ```tsx
410
+ * const toast = useToast();
411
+ * toast.show('Saved', { intent: 'success' });
412
+ * ```
413
+ */
414
+ declare function useToast(): ToastApi;
415
+
416
+ /** Props for {@link Combobox}. */
417
+ interface ComboboxProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
418
+ /** Hide options that don't match the typed query. Defaults to `true`. */
419
+ filter?: EnhanceComboboxOptions['filter'];
420
+ /** Highlight the first match while typing. Defaults to `true`. */
421
+ autoHighlight?: EnhanceComboboxOptions['autoHighlight'];
422
+ /** Controlled committed value (pair with `onValueChange`). */
423
+ value?: string;
424
+ /** Initial committed value for uncontrolled usage. */
425
+ defaultValue?: string;
426
+ /** Fires with the committed value when an option is selected. */
427
+ onValueChange?: (value: string) => void;
428
+ /** Controlled listbox visibility (pair with `onOpenChange`). */
429
+ open?: boolean;
430
+ /** Show the listbox initially for uncontrolled usage. */
431
+ defaultOpen?: boolean;
432
+ /** Called when the listbox expands or collapses. */
433
+ onOpenChange?: (open: boolean) => void;
434
+ }
435
+ /**
436
+ * Editable combobox (input + listbox) implementing the APG pattern. Compose with
437
+ * `<ComboboxInput>`, `<ComboboxList>`, and `<ComboboxOption>`. The enhancer adds
438
+ * filtering, `aria-activedescendant` navigation, and selection; both the
439
+ * committed value and the open state work uncontrolled or controlled.
440
+ *
441
+ * ```tsx
442
+ * <Combobox value={fruit} onValueChange={setFruit}>
443
+ * <ComboboxInput placeholder="Search..." />
444
+ * <ComboboxList>
445
+ * <ComboboxOption value="apple">Apple</ComboboxOption>
446
+ * <ComboboxOption value="banana">Banana</ComboboxOption>
447
+ * </ComboboxList>
448
+ * </Combobox>
449
+ * ```
450
+ */
451
+ declare const Combobox: react.ForwardRefExoticComponent<ComboboxProps & react.RefAttributes<HTMLDivElement>>;
452
+ /** Props for {@link ComboboxInput}. */
453
+ interface ComboboxInputProps extends InputHTMLAttributes<HTMLInputElement> {
454
+ /** Apply the `hl-input` style. Defaults to `true`. */
455
+ styled?: boolean;
456
+ }
457
+ /**
458
+ * The combobox text field. Inside a {@link Field} it picks up `id`,
459
+ * `aria-describedby`, `aria-invalid`, and `required`.
460
+ */
461
+ declare const ComboboxInput: react.ForwardRefExoticComponent<ComboboxInputProps & react.RefAttributes<HTMLInputElement>>;
462
+ /** Props for {@link ComboboxList}. */
463
+ type ComboboxListProps = HTMLAttributes<HTMLUListElement>;
464
+ /** The option popup (`role="listbox"`). */
465
+ declare const ComboboxList: react.ForwardRefExoticComponent<ComboboxListProps & react.RefAttributes<HTMLUListElement>>;
466
+ /** Props for {@link ComboboxOption}. */
467
+ interface ComboboxOptionProps extends Omit<LiHTMLAttributes<HTMLLIElement>, 'value'> {
468
+ /** The value committed when this option is selected. */
469
+ value: string;
470
+ /** Skip the option in keyboard navigation and refuse selection. */
471
+ disabled?: boolean;
472
+ }
473
+ /** A selectable option. The `value` is committed on selection. */
474
+ declare const ComboboxOption: react.ForwardRefExoticComponent<ComboboxOptionProps & react.RefAttributes<HTMLLIElement>>;
475
+
476
+ /** Props for {@link Command}. */
477
+ interface CommandProps extends HTMLAttributes<HTMLDivElement> {
478
+ /** Lowercased key that opens the palette's hosting `<dialog>` with Cmd/Ctrl. */
479
+ hotkey?: string;
480
+ /** Controlled filter query (pair with `onQueryChange`). */
481
+ query?: string;
482
+ /** Initial filter query for uncontrolled usage. */
483
+ defaultQuery?: string;
484
+ /** Called with the filter query after every change. */
485
+ onQueryChange?: (query: string) => void;
486
+ /** Fires with the chosen item's value and element when a command runs. */
487
+ onCommand?: (value: string, item: HTMLElement) => void;
488
+ }
489
+ /**
490
+ * Command palette. Compose with `<CommandInput>`, `<CommandList>`,
491
+ * `<CommandGroup>`, `<CommandItem>`, and `<CommandEmpty>`. The enhancer filters
492
+ * items (text + keywords), provides arrow navigation and an empty state, and
493
+ * runs the active item on Enter. The query works uncontrolled (`defaultQuery`)
494
+ * or controlled (`query` + `onQueryChange`). Place inside a `<dialog>` to use
495
+ * `hotkey`.
496
+ */
497
+ declare const Command: react.ForwardRefExoticComponent<CommandProps & react.RefAttributes<HTMLDivElement>>;
498
+ /** Props for {@link CommandInput}. */
499
+ interface CommandInputProps extends InputHTMLAttributes<HTMLInputElement> {
500
+ /** Apply the `hl-command-input` style. Defaults to `true`. */
501
+ styled?: boolean;
502
+ }
503
+ /** The palette search field. */
504
+ declare const CommandInput: react.ForwardRefExoticComponent<CommandInputProps & react.RefAttributes<HTMLInputElement>>;
505
+ /** Props for {@link CommandList}. */
506
+ type CommandListProps = HTMLAttributes<HTMLDivElement>;
507
+ /** The scrollable list of commands (`role="listbox"`). */
508
+ declare const CommandList: react.ForwardRefExoticComponent<CommandListProps & react.RefAttributes<HTMLDivElement>>;
509
+ /** Props for {@link CommandGroup}. */
510
+ interface CommandGroupProps extends HTMLAttributes<HTMLDivElement> {
511
+ /** Optional heading shown above the grouped items. */
512
+ label?: ReactNode;
513
+ }
514
+ /** A labelled group of commands. */
515
+ declare const CommandGroup: react.ForwardRefExoticComponent<CommandGroupProps & react.RefAttributes<HTMLDivElement>>;
516
+ /** Props for {@link CommandItem}. */
517
+ interface CommandItemProps extends HTMLAttributes<HTMLDivElement> {
518
+ /** Value reported to `onCommand`. */
519
+ value: string;
520
+ /** Extra search terms for filtering. */
521
+ keywords?: string;
522
+ /** Leading icon node. */
523
+ icon?: ReactNode;
524
+ }
525
+ /** A runnable command (`role="option"`). */
526
+ declare const CommandItem: react.ForwardRefExoticComponent<CommandItemProps & react.RefAttributes<HTMLDivElement>>;
527
+ /** Props for {@link CommandEmpty}. */
528
+ type CommandEmptyProps = HTMLAttributes<HTMLDivElement>;
529
+ /** Shown when no commands match the query. */
530
+ declare const CommandEmpty: react.ForwardRefExoticComponent<CommandEmptyProps & react.RefAttributes<HTMLDivElement>>;
531
+
532
+ /** Props for {@link Input}. */
533
+ interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
534
+ size?: 'sm' | 'md' | 'lg';
535
+ /** Error state; also inherited from an enclosing {@link Field}. */
536
+ invalid?: boolean;
537
+ }
538
+ /**
539
+ * Text input styled with the `hl-input` primitive. Inside a {@link Field} it
540
+ * picks up `id`, `aria-describedby`, `aria-invalid`, and `required`.
541
+ */
542
+ declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
543
+
544
+ /** Props for {@link Textarea}. */
545
+ interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
546
+ /** Error state; also inherited from an enclosing {@link Field}. */
547
+ invalid?: boolean;
548
+ /** Grow with the content (`field-sizing: content` where supported). */
549
+ autosize?: boolean;
550
+ }
551
+ /**
552
+ * Multi-line text input styled with the `hl-textarea` primitive. Inside a
553
+ * {@link Field} it picks up `id`, `aria-describedby`, `aria-invalid`, and
554
+ * `required`.
555
+ */
556
+ declare const Textarea: react.ForwardRefExoticComponent<TextareaProps & react.RefAttributes<HTMLTextAreaElement>>;
557
+
558
+ /** A single option in a {@link Select}. */
559
+ interface SelectOption {
560
+ label: ReactNode;
561
+ value: string;
562
+ disabled?: boolean;
563
+ }
564
+ /** Props for {@link Select}. */
565
+ interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'> {
566
+ size?: 'sm' | 'md' | 'lg';
567
+ /** Error state; also inherited from an enclosing {@link Field}. */
568
+ invalid?: boolean;
569
+ /** Convenience for simple option lists; or pass `children` directly. */
570
+ options?: SelectOption[];
571
+ }
572
+ /**
573
+ * Native `<select>` styled with the `hl-select` primitive, wrapped so a custom
574
+ * caret can be drawn purely in CSS. Native selects keep full mobile/keyboard
575
+ * behavior for free. Inside a {@link Field} it picks up `id`,
576
+ * `aria-describedby`, `aria-invalid`, and `required`.
577
+ */
578
+ declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLSelectElement>>;
579
+
580
+ /** Props for {@link Checkbox}. */
581
+ interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
582
+ children?: ReactNode;
583
+ }
584
+ /**
585
+ * Checkbox built on a native `<input type="checkbox">`, label-wrapped. Inside
586
+ * a {@link Field} it picks up `id`, `aria-describedby`, `aria-invalid`, and
587
+ * `required`.
588
+ */
589
+ declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
590
+
591
+ /** Props for {@link Radio}. */
592
+ interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'value'> {
593
+ children?: ReactNode;
594
+ value: string;
595
+ }
596
+ /** A single radio built on a native `<input type="radio">`, label-wrapped. */
597
+ declare const Radio: react.ForwardRefExoticComponent<RadioProps & react.RefAttributes<HTMLInputElement>>;
598
+ /** Props for {@link RadioGroup}. */
599
+ interface RadioGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
600
+ /** Shared `name` for the radios; generated when omitted. */
601
+ name?: string;
602
+ /** Controlled selected value (pair with `onValueChange`). */
603
+ value?: string;
604
+ /** Initially selected value for uncontrolled usage. */
605
+ defaultValue?: string;
606
+ /** Called with the newly selected value. */
607
+ onValueChange?: (value: string) => void;
608
+ /** Layout direction; sets `data-hl-orientation` and `aria-orientation`. */
609
+ orientation?: 'horizontal' | 'vertical';
610
+ }
611
+ /**
612
+ * Groups radios under a `role="radiogroup"`, sharing a name and managing the
613
+ * selected value (uncontrolled via `defaultValue` or controlled via `value`).
614
+ * Pass `<Radio value="...">` children.
615
+ */
616
+ declare const RadioGroup: react.ForwardRefExoticComponent<RadioGroupProps & react.RefAttributes<HTMLDivElement>>;
617
+
618
+ /** What {@link useField} hands to a custom control inside a {@link Field}. */
619
+ interface FieldControl {
620
+ /** The id the field's label points at; put it on the control. */
621
+ id: string;
622
+ /** Space-separated ids for `aria-describedby`, or `undefined` when there's nothing to reference. */
623
+ describedBy: string | undefined;
624
+ /** Whether the field is currently in an error state. */
625
+ invalid: boolean;
626
+ /** Whether the field is required. */
627
+ required: boolean;
628
+ }
629
+ /**
630
+ * Read the enclosing {@link Field}'s wiring for a custom control, or `null`
631
+ * outside a Field. The built-in controls (Input, Textarea, Select, Checkbox,
632
+ * Switch, Slider, ComboboxInput) call this themselves.
633
+ *
634
+ * ```tsx
635
+ * const field = useField();
636
+ * <input id={field?.id} aria-describedby={field?.describedBy} aria-invalid={field?.invalid || undefined} />
637
+ * ```
638
+ */
639
+ declare function useField(): FieldControl | null;
640
+ /** Props for {@link Field}. */
641
+ interface FieldProps extends HTMLAttributes<HTMLDivElement> {
642
+ /**
643
+ * Id given to the control inside the Field (the label's `htmlFor` target).
644
+ * Generated when omitted. Help and error text derive their ids from it.
645
+ */
646
+ id?: string;
647
+ /** Label text; renders a {@link FieldLabel} before the control. */
648
+ label?: ReactNode;
649
+ /** Help text; renders a {@link FieldHelp} after the control. */
650
+ description?: ReactNode;
651
+ /** Validation message; renders a {@link FieldError} and marks the field invalid. */
652
+ error?: ReactNode;
653
+ /** Force the error state without a message. */
654
+ invalid?: boolean;
655
+ required?: boolean;
656
+ }
657
+ /**
658
+ * Layout + accessibility wrapper for a form control. Provides a shared id so
659
+ * the label, help text, and error message wire up `htmlFor` and
660
+ * `aria-describedby` automatically, and the built-in controls pick up `id`,
661
+ * `aria-describedby`, `aria-invalid`, and `required` from it with no extra
662
+ * props. Pass `label`/`description`/`error` for the common layout, or compose
663
+ * `<FieldLabel>`, `<FieldHelp>`, and `<FieldError>` yourself.
664
+ *
665
+ * ```tsx
666
+ * <Field label="Email" description="We never share it." error={errors.email}>
667
+ * <Input type="email" />
668
+ * </Field>
669
+ * ```
670
+ */
671
+ declare const Field: react.ForwardRefExoticComponent<FieldProps & react.RefAttributes<HTMLDivElement>>;
672
+ /** Props for {@link FieldLabel}. */
673
+ type FieldLabelProps = LabelHTMLAttributes<HTMLLabelElement>;
674
+ /** Label bound to the enclosing field's control via `htmlFor`. */
675
+ declare const FieldLabel: react.ForwardRefExoticComponent<FieldLabelProps & react.RefAttributes<HTMLLabelElement>>;
676
+ /** Props for {@link FieldHelp}. */
677
+ type FieldHelpProps = HTMLAttributes<HTMLParagraphElement>;
678
+ /** Supplementary help text, referenced by the control's `aria-describedby`. */
679
+ declare const FieldHelp: react.ForwardRefExoticComponent<FieldHelpProps & react.RefAttributes<HTMLParagraphElement>>;
680
+ /** Props for {@link FieldError}. */
681
+ type FieldErrorProps = HTMLAttributes<HTMLParagraphElement>;
682
+ /** Validation message; renders nothing unless given content. */
683
+ declare const FieldError: react.ForwardRefExoticComponent<FieldErrorProps & react.RefAttributes<HTMLParagraphElement>>;
684
+ /** Props for {@link Fieldset}. */
685
+ interface FieldsetProps extends HTMLAttributes<HTMLFieldSetElement> {
686
+ legend?: ReactNode;
687
+ }
688
+ /** Grouped fields with an optional legend. */
689
+ declare const Fieldset: react.ForwardRefExoticComponent<FieldsetProps & react.RefAttributes<HTMLFieldSetElement>>;
690
+
691
+ /** A single option in a {@link SegmentedControl}. */
692
+ interface SegmentedOption {
693
+ label: ReactNode;
694
+ value: string;
695
+ disabled?: boolean;
696
+ }
697
+ /** Props for {@link SegmentedControl}. */
698
+ interface SegmentedControlProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
699
+ options: SegmentedOption[];
700
+ /** Controlled selected value (pair with `onValueChange`). */
701
+ value?: string;
702
+ /** Initially selected value for uncontrolled usage; defaults to the first option. */
703
+ defaultValue?: string;
704
+ /** Called with the newly selected value. */
705
+ onValueChange?: (value: string) => void;
706
+ /** Shared `name` for the underlying radios; generated when omitted. */
707
+ name?: string;
708
+ size?: 'sm' | 'md' | 'lg';
709
+ }
710
+ /**
711
+ * Segmented control: an `hl-segmented` radiogroup built on native radios, so
712
+ * keyboard navigation comes for free. Uncontrolled (`defaultValue`, falling
713
+ * back to the first option) or controlled (`value` + `onValueChange`).
714
+ */
715
+ declare const SegmentedControl: react.ForwardRefExoticComponent<SegmentedControlProps & react.RefAttributes<HTMLDivElement>>;
716
+
717
+ /** Props for {@link Slider}. */
718
+ type SliderProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>;
719
+ /**
720
+ * Range slider primitive: `<input type="range" class="hl-slider">`. Inside a
721
+ * {@link Field} it picks up `id`, `aria-describedby`, `aria-invalid`, and
722
+ * `required`.
723
+ */
724
+ declare const Slider: react.ForwardRefExoticComponent<SliderProps & react.RefAttributes<HTMLInputElement>>;
725
+
726
+ /** Props for {@link Avatar}. */
727
+ interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
728
+ src?: string;
729
+ alt?: string;
730
+ /** Shown when there is no `src` or the image fails to load. */
731
+ fallback?: ReactNode;
732
+ size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
733
+ shape?: 'circle' | 'square';
734
+ }
735
+ /** Avatar primitive: `hl-avatar` with image + graceful fallback. */
736
+ declare const Avatar: react.ForwardRefExoticComponent<AvatarProps & react.RefAttributes<HTMLSpanElement>>;
737
+ /** Props for {@link AvatarGroup}. */
738
+ type AvatarGroupProps = HTMLAttributes<HTMLDivElement>;
739
+ /** Overlapping stack of avatars. */
740
+ declare const AvatarGroup: react.ForwardRefExoticComponent<AvatarGroupProps & react.RefAttributes<HTMLDivElement>>;
741
+
742
+ /** Props for {@link Pagination}. */
743
+ interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
744
+ /** The current 1-based page. */
745
+ page: number;
746
+ /** Total number of pages. */
747
+ count: number;
748
+ /** Called with the requested page. */
749
+ onPageChange?: (page: number) => void;
750
+ /** Pages to show on each side of the current page. Defaults to 1. */
751
+ siblingCount?: number;
752
+ /** Render Previous/Next controls. Defaults to true. */
753
+ showControls?: boolean;
754
+ prevLabel?: ReactNode;
755
+ nextLabel?: ReactNode;
756
+ }
757
+ /** Pagination primitive: `hl-pagination` with smart ellipsis truncation. */
758
+ declare const Pagination: react.ForwardRefExoticComponent<PaginationProps & react.RefAttributes<HTMLElement>>;
759
+
760
+ export { Accordion, AccordionItem, type AccordionItemProps, type AccordionProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, Checkbox, type CheckboxProps, Combobox, ComboboxInput, type ComboboxInputProps, ComboboxList, type ComboboxListProps, ComboboxOption, type ComboboxOptionProps, type ComboboxProps, Command, CommandEmpty, type CommandEmptyProps, CommandGroup, type CommandGroupProps, CommandInput, type CommandInputProps, CommandItem, type CommandItemProps, CommandList, type CommandListProps, type CommandProps, Disclosure, type DisclosureProps, Drawer, type DrawerProps, Dropdown, DropdownGroup, type DropdownGroupProps, DropdownItem, type DropdownItemProps, DropdownMenu, type DropdownMenuProps, type DropdownProps, DropdownSeparator, type DropdownSeparatorProps, DropdownTrigger, type DropdownTriggerProps, Field, type FieldControl, FieldError, type FieldErrorProps, FieldHelp, type FieldHelpProps, FieldLabel, type FieldLabelProps, type FieldProps, Fieldset, type FieldsetProps, Input, type InputProps, Menu, MenuItem, type MenuItemProps, type MenuProps, MenuSubmenu, type MenuSubmenuProps, Modal, type ModalProps, Pagination, type PaginationProps, Popover, type PopoverProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectOption, type SelectProps, Slider, type SliderProps, Switch, type SwitchProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Textarea, type TextareaProps, ToastRegion, type ToastRegionProps, Toc, type TocProps, Tooltip, type TooltipProps, useEnhancer, useField, useToast };