@hydrateless/react 0.7.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 +409 -206
  3. package/dist/index.js +820 -605
  4. package/package.json +4 -4
package/dist/index.d.ts CHANGED
@@ -1,62 +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, TooltipApi, EnhanceTabsOptions, EnhanceDropdownOptions, EnhanceMenuOptions, ToastApi, EnhanceComboboxOptions } from '@hydrateless/enhancers';
5
- export { AccordionApi, ComboboxApi, Disposer, DrawerApi, DropdownApi, EnhancerHandle, ModalApi, PopoverApi, TabsApi, ToastApi, 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 groups `[data-hl-disclosure]` elements for mutual exclusivity. */
46
- declare const useDisclosureGroup: <T extends HTMLElement = HTMLElement>(allowMultiple?: boolean) => {
47
- ref: react.RefObject<T | null>;
48
- api: react.RefObject<null>;
49
- };
50
- /** Ref hook that wires modal openers/closers + focus trap within a container. */
51
- declare const useModalGroup: <T extends HTMLElement = HTMLElement>(closeOnBackdrop?: boolean) => {
52
- ref: react.RefObject<T | null>;
53
- api: react.RefObject<_hydrateless_enhancers.DialogApi | null>;
54
- };
55
- /** Ref hook that builds a table of contents from the surrounding document. */
56
- declare const useTocEnhancer: <T extends HTMLElement = HTMLElement>(options?: EnhanceTocOptions) => {
57
- ref: react.RefObject<T | null>;
58
- api: react.RefObject<null>;
59
- };
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>;
60
26
 
61
27
  /** Props for {@link Accordion}. */
62
28
  interface AccordionProps extends HTMLAttributes<HTMLDivElement> {
@@ -71,33 +37,45 @@ interface AccordionProps extends HTMLAttributes<HTMLDivElement> {
71
37
  }
72
38
  /**
73
39
  * Accordion of native `<details>` items. Item values come from each
74
- * `<AccordionItem value>`, defaulting to the index. Open state works
75
- * 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
76
43
  * (`value` + `onValueChange`).
77
44
  */
78
- declare function Accordion({ allowMultiple, value, defaultValue, onValueChange, children, ...rest }: AccordionProps): react.JSX.Element;
45
+ declare const Accordion: react.ForwardRefExoticComponent<AccordionProps & react.RefAttributes<HTMLDivElement>>;
79
46
  /** Props for {@link AccordionItem}. */
80
47
  interface AccordionItemProps extends Omit<HTMLAttributes<HTMLDetailsElement>, 'title'> {
48
+ /** The always-visible header content. */
81
49
  summary: ReactNode;
82
50
  /** Stable value identifying this item; defaults to its index. */
83
51
  value?: string;
84
- defaultOpen?: boolean;
85
52
  }
86
53
  /** A single collapsible item within an {@link Accordion}, rendered as a native `<details>`. */
87
- declare function AccordionItem({ summary, value, defaultOpen, children, ...rest }: AccordionItemProps): react.JSX.Element;
54
+ declare const AccordionItem: react.ForwardRefExoticComponent<AccordionItemProps & react.RefAttributes<HTMLDetailsElement>>;
88
55
 
89
56
  /** Props for {@link Disclosure}. */
90
57
  interface DisclosureProps extends Omit<HTMLAttributes<HTMLDetailsElement>, 'title'> {
58
+ /** The always-visible header content. */
91
59
  summary: ReactNode;
60
+ /** Controlled open state (pair with `onOpenChange`). */
61
+ open?: boolean;
62
+ /** Open the disclosure initially for uncontrolled usage. */
92
63
  defaultOpen?: boolean;
64
+ /** Called after the disclosure opens or closes. */
65
+ onOpenChange?: (open: boolean) => void;
66
+ /**
67
+ * Group name. Disclosures sharing a `name` are exclusive: the browser closes
68
+ * the others when one opens, with no JavaScript.
69
+ */
70
+ name?: string;
93
71
  }
94
72
  /**
95
- * A single expandable section. Purely presentational: native `<details>`
96
- * handles open/close, so no enhancer is required for a lone disclosure. Use
97
- * `useEnhancer(enhanceDisclosure)` on a wrapper if you need a mutually
98
- * exclusive group.
73
+ * A single expandable section built on native `<details>`, which handles
74
+ * open/close (and exclusive groups, via the `name` attribute) on its own.
75
+ * Open state works uncontrolled (`defaultOpen`) or controlled (`open` +
76
+ * `onOpenChange`).
99
77
  */
100
- declare function Disclosure({ summary, defaultOpen, className, children, ...rest }: DisclosureProps): react.JSX.Element;
78
+ declare const Disclosure: react.ForwardRefExoticComponent<DisclosureProps & react.RefAttributes<HTMLDetailsElement>>;
101
79
 
102
80
  /** Props for {@link Tabs}. */
103
81
  interface TabsProps extends HTMLAttributes<HTMLDivElement> {
@@ -113,10 +91,11 @@ interface TabsProps extends HTMLAttributes<HTMLDivElement> {
113
91
  }
114
92
  /**
115
93
  * Tabbed interface root. Compose with `<TabList>`, `<Tab>`, and `<TabPanel>`.
116
- * The enhancer wires ARIA roles, roving tabindex, and arrow-key navigation
117
- * once the markup is mounted. Tab values come from each `<Tab value>`,
118
- * defaulting to the index; selection works uncontrolled (`defaultValue`) or
119
- * 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`).
120
99
  *
121
100
  * ```tsx
122
101
  * <Tabs value={tab} onValueChange={setTab}>
@@ -129,118 +108,183 @@ interface TabsProps extends HTMLAttributes<HTMLDivElement> {
129
108
  * </Tabs>
130
109
  * ```
131
110
  */
132
- declare function Tabs({ activation, orientation, value, defaultValue, onValueChange, children, ...rest }: TabsProps): react.JSX.Element;
111
+ declare const Tabs: react.ForwardRefExoticComponent<TabsProps & react.RefAttributes<HTMLDivElement>>;
133
112
  /** Props for {@link TabList}. */
134
113
  type TabListProps = HTMLAttributes<HTMLDivElement>;
135
114
  /** The row of tab triggers. Renders `role="tablist"`. */
136
- declare function TabList({ children, ...rest }: TabListProps): react.JSX.Element;
115
+ declare const TabList: react.ForwardRefExoticComponent<TabListProps & react.RefAttributes<HTMLDivElement>>;
137
116
  /** Props for {@link Tab}. */
138
117
  interface TabProps extends ButtonHTMLAttributes<HTMLButtonElement> {
139
118
  /** Stable value identifying this tab; defaults to its index. */
140
119
  value?: string;
141
120
  }
142
- /** A single tab trigger. Renders `role="tab"`. */
143
- 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>>;
144
123
  /** Props for {@link TabPanel}. */
145
124
  type TabPanelProps = HTMLAttributes<HTMLDivElement>;
146
- /** Content for the matching tab. Renders `role="tabpanel"`. */
147
- 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>>;
148
127
 
149
128
  /** Props for {@link Dropdown}. */
150
- 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`. */
151
131
  placement?: EnhanceDropdownOptions['placement'];
132
+ /** Close the menu after an item is activated. Defaults to `true`. */
133
+ closeOnSelect?: boolean;
152
134
  /** Controlled open state (pair with `onOpenChange`). */
153
135
  open?: boolean;
154
136
  /** Open the menu initially for uncontrolled usage. */
155
137
  defaultOpen?: boolean;
156
138
  /** Called after the menu opens or closes. */
157
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;
158
145
  }
159
146
  /**
160
147
  * Button-triggered menu following the WAI-ARIA menu-button pattern. Compose with
161
- * `<DropdownTrigger>`, `<DropdownMenu>`, `<DropdownItem>`, and
162
- * `<DropdownSeparator>`. The enhancer adds keyboard navigation, typeahead, and
163
- * `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.
164
153
  *
165
154
  * ```tsx
166
- * <Dropdown>
155
+ * <Dropdown onSelect={(value) => run(value)}>
167
156
  * <DropdownTrigger>Actions</DropdownTrigger>
168
157
  * <DropdownMenu>
169
- * <DropdownItem onSelect={edit}>Edit</DropdownItem>
158
+ * <DropdownItem value="edit">Edit</DropdownItem>
170
159
  * <DropdownSeparator />
171
- * <DropdownItem onSelect={remove}>Delete</DropdownItem>
160
+ * <DropdownItem value="delete">Delete</DropdownItem>
172
161
  * </DropdownMenu>
173
162
  * </Dropdown>
174
163
  * ```
175
164
  */
176
- declare function Dropdown({ placement, open, defaultOpen, onOpenChange, children, ...rest }: DropdownProps): react.JSX.Element;
165
+ declare const Dropdown: react.ForwardRefExoticComponent<DropdownProps & react.RefAttributes<HTMLDivElement>>;
177
166
  /** Props for {@link DropdownTrigger}. */
178
167
  type DropdownTriggerProps = ButtonHTMLAttributes<HTMLButtonElement>;
179
- /** The button that opens the menu. */
180
- 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>>;
181
170
  /** Props for {@link DropdownMenu}. */
182
171
  type DropdownMenuProps = HTMLAttributes<HTMLUListElement>;
183
- /** The menu surface; holds `<DropdownItem>` and `<DropdownSeparator>`. */
184
- 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>>;
185
174
  /** Props for {@link DropdownItem}. */
186
- interface DropdownItemProps extends ButtonHTMLAttributes<HTMLButtonElement> {
187
- /** Convenience handler fired on click; you can also pass `onClick`. */
188
- 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;
189
184
  }
190
- /** A selectable menu item (`role="menuitem"`). */
191
- declare function DropdownItem({ children, onSelect, onClick, type, ...rest }: DropdownItemProps): react.JSX.Element;
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;
191
+ }
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>>;
192
197
  /** Props for {@link DropdownSeparator}. */
193
198
  type DropdownSeparatorProps = Omit<LiHTMLAttributes<HTMLLIElement>, 'role'>;
194
199
  /** A visual divider between groups of items. */
195
- declare function DropdownSeparator(props: DropdownSeparatorProps): react.JSX.Element;
200
+ declare const DropdownSeparator: react.ForwardRefExoticComponent<DropdownSeparatorProps & react.RefAttributes<HTMLLIElement>>;
196
201
 
197
202
  /** Props for {@link Menu}. */
198
- interface MenuProps extends HTMLAttributes<HTMLUListElement> {
203
+ interface MenuProps extends Omit<HTMLAttributes<HTMLUListElement>, 'onSelect' | 'defaultValue'> {
204
+ /** Layout of the top-level items. Defaults to `horizontal` (a menubar). */
199
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;
210
+ /** Called with the open submenu's value (or `null`) after every change. */
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;
200
217
  }
201
218
  /**
202
- * Menubar / navigation menu with single-level submenus. Compose with
203
- * `<MenuItem>`; nest items by passing a `submenu`. The enhancer wires roving
204
- * tabindex, orientation-aware arrow navigation, and submenu toggling.
219
+ * Menubar / navigation menu with single-level submenus rendered in the top
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).
205
225
  *
206
226
  * ```tsx
207
227
  * <Menu orientation="horizontal">
208
228
  * <MenuItem href="/">Home</MenuItem>
209
- * <MenuItem submenu={<><MenuItem href="/docs">Docs</MenuItem></>}>Resources</MenuItem>
229
+ * <MenuSubmenu label="Resources" value="resources">
230
+ * <MenuItem href="/docs">Docs</MenuItem>
231
+ * </MenuSubmenu>
210
232
  * </Menu>
211
233
  * ```
212
234
  */
213
- declare function Menu({ orientation, children, ...rest }: MenuProps): react.JSX.Element;
235
+ declare const Menu: react.ForwardRefExoticComponent<MenuProps & react.RefAttributes<HTMLUListElement>>;
214
236
  /** Props for {@link MenuItem}. */
215
- interface MenuItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'href' | 'type'> {
237
+ interface MenuItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'href' | 'type' | 'value'> {
216
238
  /** Render as a link instead of a button. */
217
239
  href?: string;
218
- /** Convenience handler fired on activation. */
219
- onSelect?: () => void;
220
- /** Nested `<MenuItem>`s; renders a single-level submenu. */
221
- submenu?: ReactNode;
240
+ /** Value reported to `onSelect`; defaults to the item's text. */
241
+ value?: string;
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;
222
248
  /** Extra attributes for the `<a>` when `href` is set. */
223
249
  anchorProps?: AnchorHTMLAttributes<HTMLAnchorElement>;
224
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
+ }
225
264
  /**
226
- * A menu entry. Children are the label; pass `submenu` to nest a flyout. With
227
- * `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.
228
267
  */
229
- declare function MenuItem({ href, onSelect, onClick, submenu, anchorProps, children, ...rest }: MenuItemProps): react.JSX.Element;
268
+ declare const MenuSubmenu: react.ForwardRefExoticComponent<MenuSubmenuProps & react.RefAttributes<HTMLUListElement>>;
230
269
 
231
270
  /** Props for {@link Modal}. */
232
271
  interface ModalProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
233
- open: boolean;
272
+ /** Controlled open state (pair with `onOpenChange`). */
273
+ open?: boolean;
274
+ /** Open the dialog initially for uncontrolled usage. */
275
+ defaultOpen?: boolean;
234
276
  /** Called after the dialog opens or closes (Escape, backdrop, close buttons). */
235
277
  onOpenChange?: (open: boolean) => void;
278
+ /** Let Escape and backdrop clicks close the dialog. Defaults to `true`. */
236
279
  closeOnBackdrop?: boolean;
237
280
  }
238
281
  /**
239
- * Controlled dialog overlay. Driven by the `open` prop via the native
240
- * `<dialog>` element and the modal enhancer, which adds a focus trap, body
241
- * scroll-lock, and a background `inert` barrier. Compose with `<ModalHeader>`,
242
- * `<ModalBody>`, and `<ModalFooter>`. Wire `onOpenChange` so Escape and
243
- * backdrop clicks can update your state.
282
+ * Dialog overlay built on the native `<dialog>` element and the modal
283
+ * enhancer, which adds a focus trap, body scroll-lock, and a background
284
+ * `inert` barrier. Compose with `<ModalHeader>`, `<ModalBody>`, and
285
+ * `<ModalFooter>`. Open state works uncontrolled (`defaultOpen`, or a
286
+ * `command="show-modal"` invoker button) or controlled (`open` +
287
+ * `onOpenChange`).
244
288
  *
245
289
  * ```tsx
246
290
  * <Modal open={open} onOpenChange={setOpen}>
@@ -250,69 +294,98 @@ interface ModalProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
250
294
  * </Modal>
251
295
  * ```
252
296
  */
253
- declare function Modal({ open, onOpenChange, closeOnBackdrop, className, children, ...rest }: ModalProps): react.JSX.Element;
297
+ declare const Modal: react.ForwardRefExoticComponent<ModalProps & react.RefAttributes<HTMLDialogElement>>;
254
298
  /** Props shared by the {@link Modal} section components. */
255
299
  type ModalSectionProps = HTMLAttributes<HTMLDivElement>;
256
300
  /** Modal heading region; its content labels the dialog for assistive tech. */
257
- declare function ModalHeader({ className, ...rest }: ModalSectionProps): react.JSX.Element;
301
+ declare const ModalHeader: react.ForwardRefExoticComponent<ModalSectionProps & react.RefAttributes<HTMLDivElement>>;
258
302
  /** Modal main content region. */
259
- declare function ModalBody({ className, ...rest }: ModalSectionProps): react.JSX.Element;
303
+ declare const ModalBody: react.ForwardRefExoticComponent<ModalSectionProps & react.RefAttributes<HTMLDivElement>>;
260
304
  /** Modal actions region. */
261
- declare function ModalFooter({ className, ...rest }: ModalSectionProps): react.JSX.Element;
305
+ declare const ModalFooter: react.ForwardRefExoticComponent<ModalSectionProps & react.RefAttributes<HTMLDivElement>>;
262
306
 
263
307
  /** Props for {@link Drawer}. */
264
308
  interface DrawerProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
265
- open: boolean;
309
+ /** Controlled open state (pair with `onOpenChange`). */
310
+ open?: boolean;
311
+ /** Open the drawer initially for uncontrolled usage. */
312
+ defaultOpen?: boolean;
266
313
  /** Called after the drawer opens or closes (Escape, backdrop, close buttons). */
267
314
  onOpenChange?: (open: boolean) => void;
268
- 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`. */
269
318
  closeOnBackdrop?: boolean;
270
319
  }
271
320
  /**
272
- * Controlled off-canvas panel built on the native `<dialog>` element and the
273
- * drawer enhancer (focus trap, scroll-lock, background `inert`). Mirrors
321
+ * Off-canvas panel built on the native `<dialog>` element and the drawer
322
+ * enhancer (focus trap, scroll-lock, background `inert`). Mirrors
274
323
  * {@link Modal} but slides in from the chosen `side`. Compose with
275
- * `<DrawerHeader>`, `<DrawerBody>`, and `<DrawerFooter>`.
324
+ * `<DrawerHeader>`, `<DrawerBody>`, and `<DrawerFooter>`. Open state works
325
+ * uncontrolled (`defaultOpen`, or an invoker button) or controlled (`open` +
326
+ * `onOpenChange`).
276
327
  */
277
- declare function Drawer({ open, onOpenChange, side, closeOnBackdrop, className, children, ...rest }: DrawerProps): react.JSX.Element;
328
+ declare const Drawer: react.ForwardRefExoticComponent<DrawerProps & react.RefAttributes<HTMLDialogElement>>;
278
329
  /** Props shared by the {@link Drawer} section components. */
279
330
  type DrawerSectionProps = HTMLAttributes<HTMLDivElement>;
280
331
  /** Drawer heading region. */
281
- declare function DrawerHeader({ className, ...rest }: DrawerSectionProps): react.JSX.Element;
332
+ declare const DrawerHeader: react.ForwardRefExoticComponent<DrawerSectionProps & react.RefAttributes<HTMLDivElement>>;
282
333
  /** Drawer main content region. */
283
- declare function DrawerBody({ className, ...rest }: DrawerSectionProps): react.JSX.Element;
334
+ declare const DrawerBody: react.ForwardRefExoticComponent<DrawerSectionProps & react.RefAttributes<HTMLDivElement>>;
284
335
  /** Drawer actions region. */
285
- declare function DrawerFooter({ className, ...rest }: DrawerSectionProps): react.JSX.Element;
336
+ declare const DrawerFooter: react.ForwardRefExoticComponent<DrawerSectionProps & react.RefAttributes<HTMLDivElement>>;
286
337
 
287
338
  /** Props for {@link Popover}. */
288
339
  interface PopoverProps extends HTMLAttributes<HTMLDivElement> {
289
- open: boolean;
290
- /** Called when the browser's light-dismiss (Escape or outside click) closes it. */
340
+ /** Controlled open state (pair with `onOpenChange`). */
341
+ open?: boolean;
342
+ /** Show the popover initially for uncontrolled usage. */
343
+ defaultOpen?: boolean;
344
+ /** Called after the popover shows or hides (including the browser's light-dismiss). */
291
345
  onOpenChange?: (open: boolean) => void;
292
- 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;
293
350
  }
294
351
  /**
295
- * Controlled floating content built on the native Popover API. The surface
296
- * lives in the top layer with light-dismiss and Escape handled by the browser;
297
- * visibility follows the `open` prop and `onOpenChange` fires when the browser
298
- * dismisses it. Pair it with your own trigger button (toggling `open`) and
299
- * position it with the `hydrateless/popover.css` styles.
352
+ * Floating content built on the native Popover API. The surface lives in the
353
+ * top layer with light-dismiss and Escape handled by the browser; visibility
354
+ * works uncontrolled (`defaultOpen`, or a `popovertarget` trigger button) or
355
+ * controlled (`open` + `onOpenChange`). Position it with the
356
+ * `hydrateless/popover.css` styles.
300
357
  */
301
- declare function Popover({ open, onOpenChange, children, ...rest }: PopoverProps): react.JSX.Element;
358
+ declare const Popover: react.ForwardRefExoticComponent<PopoverProps & react.RefAttributes<HTMLDivElement>>;
302
359
 
303
360
  /** Props for {@link Tooltip}. */
304
- interface TooltipProps {
305
- /** The hint text shown on hover/focus. */
306
- label: ReactNode;
361
+ interface TooltipProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'content'> {
362
+ /** The hint shown on hover/focus. */
363
+ content: ReactNode;
307
364
  /** A single focusable element that triggers the tooltip. */
308
365
  children: ReactElement;
309
- 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;
310
376
  }
311
377
  /**
312
- * Adds an accessible tooltip to a focusable trigger. The enhancer toggles the
313
- * 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
+ * ```
314
387
  */
315
- declare function Tooltip({ label, children, id }: TooltipProps): react.JSX.Element;
388
+ declare const Tooltip: react.ForwardRefExoticComponent<TooltipProps & react.RefAttributes<HTMLSpanElement>>;
316
389
 
317
390
  /** Props for {@link Breadcrumb}. */
318
391
  type BreadcrumbProps = HTMLAttributes<HTMLElement>;
@@ -327,31 +400,38 @@ type BreadcrumbProps = HTMLAttributes<HTMLElement>;
327
400
  * </Breadcrumb>
328
401
  * ```
329
402
  */
330
- declare function Breadcrumb({ children, ...rest }: BreadcrumbProps): react.JSX.Element;
403
+ declare const Breadcrumb: react.ForwardRefExoticComponent<BreadcrumbProps & react.RefAttributes<HTMLElement>>;
331
404
  /** Props for {@link BreadcrumbItem}. */
332
405
  interface BreadcrumbItemProps extends Omit<LiHTMLAttributes<HTMLLIElement>, 'children'> {
333
406
  href?: string;
334
407
  /** Marks the current page; renders a non-link with `aria-current="page"`. */
335
408
  current?: boolean;
336
409
  children?: ReactNode;
410
+ /** Extra attributes for the `<a>` when `href` is set. */
337
411
  anchorProps?: AnchorHTMLAttributes<HTMLAnchorElement>;
338
412
  }
339
413
  /** A single crumb. Renders a link unless `current` (or no `href`) is set. */
340
- declare function BreadcrumbItem({ href, current, anchorProps, children, ...rest }: BreadcrumbItemProps): react.JSX.Element;
414
+ declare const BreadcrumbItem: react.ForwardRefExoticComponent<BreadcrumbItemProps & react.RefAttributes<HTMLLIElement>>;
341
415
 
342
416
  /** Props for {@link Switch}. */
343
417
  interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
344
418
  children?: ReactNode;
345
419
  }
346
- /** Toggle switch built on a native checkbox. CSS-only. */
347
- 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>>;
348
426
 
349
427
  /** Props for {@link SkipLink}. */
350
428
  type SkipLinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
351
429
  children?: ReactNode;
352
430
  };
353
431
  /** Accessibility skip-navigation link, visually hidden until focused. */
354
- 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>>;
355
435
 
356
436
  /** Props for {@link Toc}. */
357
437
  interface TocProps extends HTMLAttributes<HTMLElement> {
@@ -363,25 +443,39 @@ interface TocProps extends HTMLAttributes<HTMLElement> {
363
443
  scrollSpy?: boolean;
364
444
  }
365
445
  /** Auto-generated table of contents with optional scroll-spy. */
366
- declare function Toc({ contentSelector, headings, scrollSpy, ...rest }: TocProps): react.JSX.Element;
446
+ declare const Toc: react.ForwardRefExoticComponent<TocProps & react.RefAttributes<HTMLElement>>;
367
447
 
368
448
  /** Props for {@link ToastRegion}. */
369
- 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
+ }
370
455
  /**
371
456
  * The polite live region toasts render into. Render once near the root of
372
- * your app to control where toasts appear; if omitted, the first `show()`
373
- * 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>`.
374
460
  */
375
- declare function ToastRegion(props: ToastRegionProps): react.JSX.Element;
461
+ declare const ToastRegion: react.ForwardRefExoticComponent<ToastRegionProps & react.RefAttributes<HTMLDivElement>>;
376
462
  /**
377
- * Access the imperative toast API (`show`/`dismiss`). Works with or without a
378
- * 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
+ * ```
379
471
  */
380
472
  declare function useToast(): ToastApi;
381
473
 
382
474
  /** Props for {@link Combobox}. */
383
475
  interface ComboboxProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
476
+ /** Hide options that don't match the typed query. Defaults to `true`. */
384
477
  filter?: EnhanceComboboxOptions['filter'];
478
+ /** Highlight the first match while typing. Defaults to `true`. */
385
479
  autoHighlight?: EnhanceComboboxOptions['autoHighlight'];
386
480
  /** Controlled committed value (pair with `onValueChange`). */
387
481
  value?: string;
@@ -389,17 +483,22 @@ interface ComboboxProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>
389
483
  defaultValue?: string;
390
484
  /** Fires with the committed value when an option is selected. */
391
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;
392
492
  }
393
493
  /**
394
494
  * Editable combobox (input + listbox) implementing the APG pattern. Compose with
395
495
  * `<ComboboxInput>`, `<ComboboxList>`, and `<ComboboxOption>`. The enhancer adds
396
- * filtering, `aria-activedescendant` navigation, and selection; the committed
397
- * value works uncontrolled (`defaultValue`) or controlled (`value` +
398
- * `onValueChange`).
496
+ * filtering, `aria-activedescendant` navigation, and selection; both the
497
+ * committed value and the open state work uncontrolled or controlled.
399
498
  *
400
499
  * ```tsx
401
500
  * <Combobox value={fruit} onValueChange={setFruit}>
402
- * <ComboboxInput placeholder="Search…" />
501
+ * <ComboboxInput placeholder="Search..." />
403
502
  * <ComboboxList>
404
503
  * <ComboboxOption value="apple">Apple</ComboboxOption>
405
504
  * <ComboboxOption value="banana">Banana</ComboboxOption>
@@ -407,58 +506,74 @@ interface ComboboxProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>
407
506
  * </Combobox>
408
507
  * ```
409
508
  */
410
- declare function Combobox({ filter, autoHighlight, value, defaultValue, onValueChange, children, ...rest }: ComboboxProps): react.JSX.Element;
509
+ declare const Combobox: react.ForwardRefExoticComponent<ComboboxProps & react.RefAttributes<HTMLDivElement>>;
411
510
  /** Props for {@link ComboboxInput}. */
412
511
  interface ComboboxInputProps extends InputHTMLAttributes<HTMLInputElement> {
413
512
  /** Apply the `hl-input` style. Defaults to `true`. */
414
513
  styled?: boolean;
415
514
  }
416
- /** The combobox text field. */
417
- 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>>;
418
520
  /** Props for {@link ComboboxList}. */
419
521
  type ComboboxListProps = HTMLAttributes<HTMLUListElement>;
420
522
  /** The option popup (`role="listbox"`). */
421
- declare function ComboboxList({ children, ...rest }: ComboboxListProps): react.JSX.Element;
523
+ declare const ComboboxList: react.ForwardRefExoticComponent<ComboboxListProps & react.RefAttributes<HTMLUListElement>>;
422
524
  /** Props for {@link ComboboxOption}. */
423
525
  interface ComboboxOptionProps extends Omit<LiHTMLAttributes<HTMLLIElement>, 'value'> {
526
+ /** The value committed when this option is selected. */
424
527
  value: string;
528
+ /** Skip the option in keyboard navigation and refuse selection. */
529
+ disabled?: boolean;
425
530
  }
426
531
  /** A selectable option. The `value` is committed on selection. */
427
- declare function ComboboxOption({ value, children, ...rest }: ComboboxOptionProps): react.JSX.Element;
532
+ declare const ComboboxOption: react.ForwardRefExoticComponent<ComboboxOptionProps & react.RefAttributes<HTMLLIElement>>;
428
533
 
429
534
  /** Props for {@link Command}. */
430
- interface CommandProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
431
- /** 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. */
432
537
  hotkey?: string;
433
- /** Fires with the chosen item's value when a command runs. */
434
- 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;
435
546
  }
436
547
  /**
437
548
  * Command palette. Compose with `<CommandInput>`, `<CommandList>`,
438
549
  * `<CommandGroup>`, `<CommandItem>`, and `<CommandEmpty>`. The enhancer filters
439
550
  * items (text + keywords), provides arrow navigation and an empty state, and
440
- * 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`.
441
554
  */
442
- declare function Command({ hotkey, onSelect, children, ...rest }: CommandProps): react.JSX.Element;
555
+ declare const Command: react.ForwardRefExoticComponent<CommandProps & react.RefAttributes<HTMLDivElement>>;
443
556
  /** Props for {@link CommandInput}. */
444
557
  interface CommandInputProps extends InputHTMLAttributes<HTMLInputElement> {
558
+ /** Apply the `hl-input` style. Defaults to `true`. */
445
559
  styled?: boolean;
446
560
  }
447
561
  /** The palette search field. */
448
- declare function CommandInput({ styled, className, ...rest }: CommandInputProps): react.JSX.Element;
562
+ declare const CommandInput: react.ForwardRefExoticComponent<CommandInputProps & react.RefAttributes<HTMLInputElement>>;
449
563
  /** Props for {@link CommandList}. */
450
564
  type CommandListProps = HTMLAttributes<HTMLDivElement>;
451
565
  /** The scrollable list of commands (`role="listbox"`). */
452
- declare function CommandList({ children, ...rest }: CommandListProps): react.JSX.Element;
566
+ declare const CommandList: react.ForwardRefExoticComponent<CommandListProps & react.RefAttributes<HTMLDivElement>>;
453
567
  /** Props for {@link CommandGroup}. */
454
568
  interface CommandGroupProps extends HTMLAttributes<HTMLDivElement> {
455
569
  /** Optional heading shown above the grouped items. */
456
570
  label?: ReactNode;
457
571
  }
458
572
  /** A labelled group of commands. */
459
- declare function CommandGroup({ label, children, ...rest }: CommandGroupProps): react.JSX.Element;
573
+ declare const CommandGroup: react.ForwardRefExoticComponent<CommandGroupProps & react.RefAttributes<HTMLDivElement>>;
460
574
  /** Props for {@link CommandItem}. */
461
- interface CommandItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
575
+ interface CommandItemProps extends HTMLAttributes<HTMLDivElement> {
576
+ /** Value reported to `onCommand`. */
462
577
  value: string;
463
578
  /** Extra search terms for filtering. */
464
579
  keywords?: string;
@@ -466,25 +581,36 @@ interface CommandItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelec
466
581
  icon?: ReactNode;
467
582
  }
468
583
  /** A runnable command (`role="option"`). */
469
- declare function CommandItem({ value, keywords, icon, children, ...rest }: CommandItemProps): react.JSX.Element;
584
+ declare const CommandItem: react.ForwardRefExoticComponent<CommandItemProps & react.RefAttributes<HTMLDivElement>>;
470
585
  /** Props for {@link CommandEmpty}. */
471
586
  type CommandEmptyProps = HTMLAttributes<HTMLDivElement>;
472
587
  /** Shown when no commands match the query. */
473
- declare function CommandEmpty({ children, ...rest }: CommandEmptyProps): react.JSX.Element;
588
+ declare const CommandEmpty: react.ForwardRefExoticComponent<CommandEmptyProps & react.RefAttributes<HTMLDivElement>>;
474
589
 
475
590
  /** Props for {@link Input}. */
476
591
  interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
477
592
  size?: 'sm' | 'md' | 'lg';
593
+ /** Error state; also inherited from an enclosing {@link Field}. */
478
594
  invalid?: boolean;
479
595
  }
480
- /** 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
+ */
481
600
  declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
482
601
 
483
602
  /** Props for {@link Textarea}. */
484
603
  interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
604
+ /** Error state; also inherited from an enclosing {@link Field}. */
485
605
  invalid?: boolean;
606
+ /** Grow with the content (`field-sizing: content` where supported). */
607
+ autosize?: boolean;
486
608
  }
487
- /** 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
+ */
488
614
  declare const Textarea: react.ForwardRefExoticComponent<TextareaProps & react.RefAttributes<HTMLTextAreaElement>>;
489
615
 
490
616
  /** A single option in a {@link Select}. */
@@ -496,6 +622,7 @@ interface SelectOption {
496
622
  /** Props for {@link Select}. */
497
623
  interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'> {
498
624
  size?: 'sm' | 'md' | 'lg';
625
+ /** Error state; also inherited from an enclosing {@link Field}. */
499
626
  invalid?: boolean;
500
627
  /** Convenience for simple option lists; or pass `children` directly. */
501
628
  options?: SelectOption[];
@@ -503,7 +630,8 @@ interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'siz
503
630
  /**
504
631
  * Native `<select>` styled with the `hl-select` primitive, wrapped so a custom
505
632
  * caret can be drawn purely in CSS. Native selects keep full mobile/keyboard
506
- * behavior for free.
633
+ * behavior for free. Inside a {@link Field} it picks up `id`,
634
+ * `aria-describedby`, `aria-invalid`, and `required`.
507
635
  */
508
636
  declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLSelectElement>>;
509
637
 
@@ -511,11 +639,15 @@ declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAtt
511
639
  interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
512
640
  children?: ReactNode;
513
641
  }
514
- /** 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
+ */
515
647
  declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
516
648
 
517
649
  /** Props for {@link Radio}. */
518
- interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
650
+ interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'value'> {
519
651
  children?: ReactNode;
520
652
  value: string;
521
653
  }
@@ -523,52 +655,91 @@ interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>
523
655
  declare const Radio: react.ForwardRefExoticComponent<RadioProps & react.RefAttributes<HTMLInputElement>>;
524
656
  /** Props for {@link RadioGroup}. */
525
657
  interface RadioGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
658
+ /** Shared `name` for the radios; generated when omitted. */
526
659
  name?: string;
660
+ /** Controlled selected value (pair with `onValueChange`). */
527
661
  value?: string;
662
+ /** Initially selected value for uncontrolled usage. */
663
+ defaultValue?: string;
664
+ /** Called with the newly selected value. */
528
665
  onValueChange?: (value: string) => void;
666
+ /** Layout direction; sets `data-hl-orientation` and `aria-orientation`. */
667
+ orientation?: 'horizontal' | 'vertical';
529
668
  }
530
669
  /**
531
670
  * Groups radios under a `role="radiogroup"`, sharing a name and managing the
532
- * selected value. Pass `<Radio value="…">` children.
671
+ * selected value (uncontrolled via `defaultValue` or controlled via `value`).
672
+ * Pass `<Radio value="...">` children.
533
673
  */
534
- declare function RadioGroup({ name, value, onValueChange, className, children, ...rest }: RadioGroupProps): react.JSX.Element;
674
+ declare const RadioGroup: react.ForwardRefExoticComponent<RadioGroupProps & react.RefAttributes<HTMLDivElement>>;
535
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;
536
698
  /** Props for {@link Field}. */
537
699
  interface FieldProps extends HTMLAttributes<HTMLDivElement> {
538
- 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. */
539
707
  invalid?: boolean;
540
708
  required?: boolean;
541
709
  }
542
710
  /**
543
711
  * Layout + accessibility wrapper for a form control. Provides a shared id so
544
- * `<FieldLabel>`, `<FieldHelp>`, and `<FieldError>` wire up
545
- * `htmlFor`/`aria-describedby` automatically; spread {@link useField}'s result
546
- * onto your control.
547
- */
548
- declare function Field({ id, invalid, required, className, children, ...rest }: FieldProps): react.JSX.Element;
549
- /**
550
- * Props to spread onto the field's control (`id`, `aria-describedby`,
551
- * `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
+ * ```
552
723
  */
553
- declare function useField(): {
554
- id: string;
555
- 'aria-describedby': string | undefined;
556
- 'aria-invalid': true | undefined;
557
- };
724
+ declare const Field: react.ForwardRefExoticComponent<FieldProps & react.RefAttributes<HTMLDivElement>>;
558
725
  /** Props for {@link FieldLabel}. */
559
726
  type FieldLabelProps = LabelHTMLAttributes<HTMLLabelElement>;
560
727
  /** Label bound to the enclosing field's control via `htmlFor`. */
561
- 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>;
562
731
  /** Supplementary help text, referenced by the control's `aria-describedby`. */
563
- 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>;
564
735
  /** Validation message; renders nothing unless given content. */
565
- declare function FieldError({ className, children, ...rest }: HTMLAttributes<HTMLParagraphElement>): react.JSX.Element | null;
736
+ declare const FieldError: react.ForwardRefExoticComponent<FieldErrorProps & react.RefAttributes<HTMLParagraphElement>>;
566
737
  /** Props for {@link Fieldset}. */
567
738
  interface FieldsetProps extends HTMLAttributes<HTMLFieldSetElement> {
568
739
  legend?: ReactNode;
569
740
  }
570
741
  /** Grouped fields with an optional legend. */
571
- declare function Fieldset({ legend, className, children, ...rest }: FieldsetProps): react.JSX.Element;
742
+ declare const Fieldset: react.ForwardRefExoticComponent<FieldsetProps & react.RefAttributes<HTMLFieldSetElement>>;
572
743
 
573
744
  /** A single option in a {@link SegmentedControl}. */
574
745
  interface SegmentedOption {
@@ -579,22 +750,30 @@ interface SegmentedOption {
579
750
  /** Props for {@link SegmentedControl}. */
580
751
  interface SegmentedControlProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
581
752
  options: SegmentedOption[];
753
+ /** Controlled selected value (pair with `onValueChange`). */
582
754
  value?: string;
755
+ /** Initially selected value for uncontrolled usage; defaults to the first option. */
583
756
  defaultValue?: string;
757
+ /** Called with the newly selected value. */
584
758
  onValueChange?: (value: string) => void;
759
+ /** Shared `name` for the underlying radios; generated when omitted. */
585
760
  name?: string;
586
761
  size?: 'sm' | 'md' | 'lg';
587
762
  }
588
763
  /**
589
- * Segmented control: `hl-segmented` radiogroup. Controlled via `value` or
590
- * uncontrolled via `defaultValue`. Built on native radios for free keyboard
591
- * 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`).
592
767
  */
593
- 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>>;
594
769
 
595
770
  /** Props for {@link Slider}. */
596
771
  type SliderProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>;
597
- /** 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
+ */
598
777
  declare const Slider: react.ForwardRefExoticComponent<SliderProps & react.RefAttributes<HTMLInputElement>>;
599
778
 
600
779
  /** Props for {@link Button}. */
@@ -689,17 +868,23 @@ declare const Spinner: react.ForwardRefExoticComponent<SpinnerProps & react.RefA
689
868
 
690
869
  /** Props for {@link Skeleton}. */
691
870
  interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
692
- 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`). */
693
874
  width?: string | number;
875
+ /** Block size (maps to the logical `block-size`). */
694
876
  height?: string | number;
695
877
  }
696
- /** Skeleton placeholder primitive: `hl-skeleton`. */
878
+ /** Skeleton placeholder primitive: `hl-skeleton`. Hidden from assistive tech. */
697
879
  declare const Skeleton: react.ForwardRefExoticComponent<SkeletonProps & react.RefAttributes<HTMLSpanElement>>;
698
880
 
699
881
  /** Props for {@link Pagination}. */
700
882
  interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
883
+ /** The current 1-based page. */
701
884
  page: number;
885
+ /** Total number of pages. */
702
886
  count: number;
887
+ /** Called with the requested page. */
703
888
  onPageChange?: (page: number) => void;
704
889
  /** Pages to show on each side of the current page. Defaults to 1. */
705
890
  siblingCount?: number;
@@ -709,7 +894,7 @@ interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'>
709
894
  nextLabel?: ReactNode;
710
895
  }
711
896
  /** Pagination primitive: `hl-pagination` with smart ellipsis truncation. */
712
- 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>>;
713
898
 
714
899
  /** Props for {@link Kbd}. */
715
900
  type KbdProps = HTMLAttributes<HTMLElement>;
@@ -725,7 +910,25 @@ interface SeparatorProps extends HTMLAttributes<HTMLHRElement> {
725
910
  /** Separator primitive: `<hr class="hl-separator">`. */
726
911
  declare const Separator: react.ForwardRefExoticComponent<SeparatorProps & react.RefAttributes<HTMLHRElement>>;
727
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
+
728
931
  /** Join truthy class names into a single string. */
729
932
  declare function cx(...classes: Array<string | false | null | undefined>): string;
730
933
 
731
- 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, useDisclosureGroup, 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 };