@hydrateless/react 0.8.0 → 0.9.0

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