@hydrateless/react 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,46 +1,87 @@
1
1
  import * as react from 'react';
2
- import { DependencyList, RefObject, HTMLAttributes, ReactNode, ReactElement, InputHTMLAttributes, AnchorHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, LabelHTMLAttributes, ButtonHTMLAttributes, ProgressHTMLAttributes } from 'react';
3
- import { Disposer, EnhanceTocOptions, ToastApi } from '@hydrateless/enhancers';
4
- export { Disposer } from '@hydrateless/enhancers';
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';
5
6
 
6
7
  /**
7
8
  * Attach any Hydrateless enhancer to a DOM node for the lifetime of a
8
- * component. Returns a ref to spread onto the element you want enhanced; the
9
- * enhancer's disposer is called automatically on unmount (and before re-running
10
- * when `deps` change), so there are no leaked listeners across renders.
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.
11
13
  *
12
14
  * ```tsx
13
- * const ref = useEnhancer<HTMLDivElement>(enhanceTabs);
15
+ * const { ref, api } = useEnhancer<HTMLDivElement, TabsApi>((el) => enhanceTabs(el));
16
+ * // api.current?.setValue('two');
14
17
  * return <div data-hl-tabs ref={ref}>…</div>;
15
18
  * ```
16
19
  */
17
- declare function useEnhancer<T extends HTMLElement = HTMLElement>(enhance: (container: HTMLElement) => Disposer, deps?: DependencyList): RefObject<T | null>;
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
+ };
18
24
 
19
25
  /** Ref hook that wires tabs ARIA + keyboard navigation onto a container. */
20
- declare const useTabs: <T extends HTMLElement = HTMLDivElement>() => react.RefObject<T | null>;
26
+ declare const useTabs: <T extends HTMLElement = HTMLDivElement>() => {
27
+ ref: react.RefObject<T | null>;
28
+ api: react.RefObject<TabsApi | null>;
29
+ };
21
30
  /** Ref hook that wires a dropdown menu onto a container. */
22
- declare const useDropdown: <T extends HTMLElement = HTMLDivElement>() => react.RefObject<T | null>;
31
+ declare const useDropdown: <T extends HTMLElement = HTMLDivElement>() => {
32
+ ref: react.RefObject<T | null>;
33
+ api: react.RefObject<DropdownApi | null>;
34
+ };
23
35
  /** Ref hook that wires tooltips onto all `[data-hl-tooltip]` triggers inside. */
24
- declare const useTooltip: <T extends HTMLElement = HTMLElement>() => react.RefObject<T | null>;
36
+ declare const useTooltip: <T extends HTMLElement = HTMLElement>() => {
37
+ ref: react.RefObject<T | null>;
38
+ api: react.RefObject<TooltipApi | null>;
39
+ };
25
40
  /** Ref hook that enforces single-open accordion behavior on a container. */
26
- declare const useAccordion: <T extends HTMLElement = HTMLDivElement>(allowMultiple?: boolean) => react.RefObject<T | null>;
41
+ declare const useAccordion: <T extends HTMLElement = HTMLDivElement>(allowMultiple?: boolean) => {
42
+ ref: react.RefObject<T | null>;
43
+ api: react.RefObject<AccordionApi | null>;
44
+ };
27
45
  /** Ref hook that groups `[data-hl-disclosure]` elements for mutual exclusivity. */
28
- declare const useDisclosureGroup: <T extends HTMLElement = HTMLElement>(allowMultiple?: boolean) => react.RefObject<T | null>;
46
+ declare const useDisclosureGroup: <T extends HTMLElement = HTMLElement>(allowMultiple?: boolean) => {
47
+ ref: react.RefObject<T | null>;
48
+ api: react.RefObject<null>;
49
+ };
29
50
  /** Ref hook that wires modal openers/closers + focus trap within a container. */
30
- declare const useModalGroup: <T extends HTMLElement = HTMLElement>(closeOnBackdrop?: boolean) => react.RefObject<T | null>;
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
+ };
31
55
  /** Ref hook that builds a table of contents from the surrounding document. */
32
- declare const useTocEnhancer: <T extends HTMLElement = HTMLElement>(options?: EnhanceTocOptions) => react.RefObject<T | null>;
56
+ declare const useTocEnhancer: <T extends HTMLElement = HTMLElement>(options?: EnhanceTocOptions) => {
57
+ ref: react.RefObject<T | null>;
58
+ api: react.RefObject<null>;
59
+ };
33
60
 
34
61
  interface AccordionProps extends HTMLAttributes<HTMLDivElement> {
35
62
  /** Allow more than one panel to stay open at a time. */
36
63
  allowMultiple?: boolean;
64
+ /** Controlled list of open item values (pair with `onValueChange`). */
65
+ value?: string[];
66
+ /** Initially open item values for uncontrolled usage. */
67
+ defaultValue?: string[];
68
+ /** Called with the open item values after every change. */
69
+ onValueChange?: (value: string[]) => void;
37
70
  }
38
- declare function Accordion({ allowMultiple, children, ...rest }: AccordionProps): react.JSX.Element;
71
+ /**
72
+ * Accordion of native `<details>` items. Item values come from each
73
+ * `<AccordionItem value>`, defaulting to the index. Open state works
74
+ * uncontrolled (`defaultValue`, or `defaultOpen` on items) or controlled
75
+ * (`value` + `onValueChange`).
76
+ */
77
+ declare function Accordion({ allowMultiple, value, defaultValue, onValueChange, children, ...rest }: AccordionProps): react.JSX.Element;
39
78
  interface AccordionItemProps extends Omit<HTMLAttributes<HTMLDetailsElement>, 'title'> {
40
79
  summary: ReactNode;
80
+ /** Stable value identifying this item; defaults to its index. */
81
+ value?: string;
41
82
  defaultOpen?: boolean;
42
83
  }
43
- declare function AccordionItem({ summary, defaultOpen, children, ...rest }: AccordionItemProps): react.JSX.Element;
84
+ declare function AccordionItem({ summary, value, defaultOpen, children, ...rest }: AccordionItemProps): react.JSX.Element;
44
85
 
45
86
  interface DisclosureProps extends Omit<HTMLAttributes<HTMLDetailsElement>, 'title'> {
46
87
  summary: ReactNode;
@@ -52,75 +93,191 @@ interface DisclosureProps extends Omit<HTMLAttributes<HTMLDetailsElement>, 'titl
52
93
  * `useEnhancer(enhanceDisclosure)` on a wrapper if you need a mutually
53
94
  * exclusive group.
54
95
  */
55
- declare function Disclosure({ summary, defaultOpen, children, ...rest }: DisclosureProps): react.JSX.Element;
96
+ declare function Disclosure({ summary, defaultOpen, className, children, ...rest }: DisclosureProps): react.JSX.Element;
56
97
 
57
- interface TabItem {
58
- label: ReactNode;
59
- content: ReactNode;
60
- }
61
98
  interface TabsProps extends HTMLAttributes<HTMLDivElement> {
62
- items: TabItem[];
99
+ /** `manual` (default): arrows move focus, Enter/Space activates. `automatic`: arrows activate immediately. */
100
+ activation?: EnhanceTabsOptions['activation'];
101
+ orientation?: EnhanceTabsOptions['orientation'];
102
+ /** Controlled value of the selected tab (pair with `onValueChange`). */
103
+ value?: string;
104
+ /** Initial value for uncontrolled usage. */
105
+ defaultValue?: string;
106
+ /** Called with the new tab value after every selection change. */
107
+ onValueChange?: (value: string) => void;
63
108
  }
64
109
  /**
65
- * Tabbed interface. The enhancer wires ARIA roles, roving tabindex, and arrow
66
- * key navigation once the markup is rendered.
110
+ * Tabbed interface root. Compose with `<TabList>`, `<Tab>`, and `<TabPanel>`.
111
+ * The enhancer wires ARIA roles, roving tabindex, and arrow-key navigation
112
+ * once the markup is mounted. Tab values come from each `<Tab value>`,
113
+ * defaulting to the index; selection works uncontrolled (`defaultValue`) or
114
+ * controlled (`value` + `onValueChange`).
115
+ *
116
+ * ```tsx
117
+ * <Tabs value={tab} onValueChange={setTab}>
118
+ * <TabList>
119
+ * <Tab value="overview">Overview</Tab>
120
+ * <Tab value="install">Install</Tab>
121
+ * </TabList>
122
+ * <TabPanel>Zero runtime by default.</TabPanel>
123
+ * <TabPanel>npm install hydrateless</TabPanel>
124
+ * </Tabs>
125
+ * ```
67
126
  */
68
- declare function Tabs({ items, ...rest }: TabsProps): react.JSX.Element;
127
+ declare function Tabs({ activation, orientation, value, defaultValue, onValueChange, children, ...rest }: TabsProps): react.JSX.Element;
128
+ type TabListProps = HTMLAttributes<HTMLDivElement>;
129
+ /** The row of tab triggers. Renders `role="tablist"`. */
130
+ declare function TabList({ children, ...rest }: TabListProps): react.JSX.Element;
131
+ interface TabProps extends ButtonHTMLAttributes<HTMLButtonElement> {
132
+ /** Stable value identifying this tab; defaults to its index. */
133
+ value?: string;
134
+ }
135
+ /** A single tab trigger. Renders `role="tab"`. */
136
+ declare function Tab({ children, type, value, ...rest }: TabProps): react.JSX.Element;
137
+ type TabPanelProps = HTMLAttributes<HTMLDivElement>;
138
+ /** Content for the matching tab. Renders `role="tabpanel"`. */
139
+ declare function TabPanel({ children, ...rest }: TabPanelProps): react.JSX.Element;
69
140
 
70
- interface DropdownItem {
71
- label: ReactNode;
141
+ interface DropdownProps extends HTMLAttributes<HTMLDivElement> {
142
+ placement?: EnhanceDropdownOptions['placement'];
143
+ /** Controlled open state (pair with `onOpenChange`). */
144
+ open?: boolean;
145
+ /** Open the menu initially for uncontrolled usage. */
146
+ defaultOpen?: boolean;
147
+ /** Called after the menu opens or closes. */
148
+ onOpenChange?: (open: boolean) => void;
149
+ }
150
+ /**
151
+ * Button-triggered menu following the WAI-ARIA menu-button pattern. Compose with
152
+ * `<DropdownTrigger>`, `<DropdownMenu>`, `<DropdownItem>`, and
153
+ * `<DropdownSeparator>`. The enhancer adds keyboard navigation, typeahead, and
154
+ * `aria-expanded`/`role` wiring; open state works uncontrolled or controlled.
155
+ *
156
+ * ```tsx
157
+ * <Dropdown>
158
+ * <DropdownTrigger>Actions</DropdownTrigger>
159
+ * <DropdownMenu>
160
+ * <DropdownItem onSelect={edit}>Edit</DropdownItem>
161
+ * <DropdownSeparator />
162
+ * <DropdownItem onSelect={remove}>Delete</DropdownItem>
163
+ * </DropdownMenu>
164
+ * </Dropdown>
165
+ * ```
166
+ */
167
+ declare function Dropdown({ placement, open, defaultOpen, onOpenChange, children, ...rest }: DropdownProps): react.JSX.Element;
168
+ type DropdownTriggerProps = ButtonHTMLAttributes<HTMLButtonElement>;
169
+ /** The button that opens the menu. */
170
+ declare function DropdownTrigger({ children, type, ...rest }: DropdownTriggerProps): react.JSX.Element;
171
+ type DropdownMenuProps = HTMLAttributes<HTMLUListElement>;
172
+ /** The menu surface; holds `<DropdownItem>` and `<DropdownSeparator>`. */
173
+ declare function DropdownMenu({ children, ...rest }: DropdownMenuProps): react.JSX.Element;
174
+ interface DropdownItemProps extends ButtonHTMLAttributes<HTMLButtonElement> {
175
+ /** Convenience handler fired on click; you can also pass `onClick`. */
72
176
  onSelect?: () => void;
73
- separator?: boolean;
74
- disabled?: boolean;
75
177
  }
76
- interface DropdownProps extends HTMLAttributes<HTMLDivElement> {
77
- trigger: ReactNode;
78
- items: DropdownItem[];
178
+ /** A selectable menu item (`role="menuitem"`). */
179
+ declare function DropdownItem({ children, onSelect, onClick, type, ...rest }: DropdownItemProps): react.JSX.Element;
180
+ type DropdownSeparatorProps = Omit<LiHTMLAttributes<HTMLLIElement>, 'role'>;
181
+ /** A visual divider between groups of items. */
182
+ declare function DropdownSeparator(props: DropdownSeparatorProps): react.JSX.Element;
183
+
184
+ interface MenuProps extends HTMLAttributes<HTMLUListElement> {
185
+ orientation?: EnhanceMenuOptions['orientation'];
79
186
  }
80
187
  /**
81
- * Button-triggered menu following the WAI-ARIA menu pattern. The enhancer adds
82
- * keyboard navigation, typeahead, and `aria-expanded`/`role` wiring.
188
+ * Menubar / navigation menu with single-level submenus. Compose with
189
+ * `<MenuItem>`; nest items by passing a `submenu`. The enhancer wires roving
190
+ * tabindex, orientation-aware arrow navigation, and submenu toggling.
191
+ *
192
+ * ```tsx
193
+ * <Menu orientation="horizontal">
194
+ * <MenuItem href="/">Home</MenuItem>
195
+ * <MenuItem submenu={<><MenuItem href="/docs">Docs</MenuItem></>}>Resources</MenuItem>
196
+ * </Menu>
197
+ * ```
83
198
  */
84
- declare function Dropdown({ trigger, items, ...rest }: DropdownProps): react.JSX.Element;
199
+ declare function Menu({ orientation, children, ...rest }: MenuProps): react.JSX.Element;
200
+ interface MenuItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'href' | 'type'> {
201
+ /** Render as a link instead of a button. */
202
+ href?: string;
203
+ /** Convenience handler fired on activation. */
204
+ onSelect?: () => void;
205
+ /** Nested `<MenuItem>`s; renders a single-level submenu. */
206
+ submenu?: ReactNode;
207
+ /** Extra attributes for the `<a>` when `href` is set. */
208
+ anchorProps?: AnchorHTMLAttributes<HTMLAnchorElement>;
209
+ }
210
+ /**
211
+ * A menu entry. Children are the label; pass `submenu` to nest a flyout. With
212
+ * `href` it renders an anchor, otherwise a button.
213
+ */
214
+ declare function MenuItem({ href, onSelect, onClick, submenu, anchorProps, children, ...rest }: MenuItemProps): react.JSX.Element;
85
215
 
86
- interface ModalProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title' | 'onClick'> {
216
+ interface ModalProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
87
217
  open: boolean;
88
- onClose?: () => void;
89
- title?: ReactNode;
90
- footer?: ReactNode;
218
+ /** Called after the dialog opens or closes (Escape, backdrop, close buttons). */
219
+ onOpenChange?: (open: boolean) => void;
91
220
  closeOnBackdrop?: boolean;
92
221
  }
93
222
  /**
94
223
  * Controlled dialog overlay. Driven by the `open` prop via the native
95
- * `<dialog>` element, which provides focus containment in the top layer. Wire
96
- * `onClose` so Escape and backdrop clicks can update your state.
224
+ * `<dialog>` element and the modal enhancer, which adds a focus trap, body
225
+ * scroll-lock, and a background `inert` barrier. Compose with `<ModalHeader>`,
226
+ * `<ModalBody>`, and `<ModalFooter>`. Wire `onOpenChange` so Escape and
227
+ * backdrop clicks can update your state.
228
+ *
229
+ * ```tsx
230
+ * <Modal open={open} onOpenChange={setOpen}>
231
+ * <ModalHeader>Confirm</ModalHeader>
232
+ * <ModalBody>Are you sure?</ModalBody>
233
+ * <ModalFooter><Button onClick={() => setOpen(false)}>Close</Button></ModalFooter>
234
+ * </Modal>
235
+ * ```
97
236
  */
98
- declare function Modal({ open, onClose, title, footer, closeOnBackdrop, className, children, ...rest }: ModalProps): react.JSX.Element;
99
-
100
- interface DrawerProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title' | 'onClick'> {
237
+ declare function Modal({ open, onOpenChange, closeOnBackdrop, className, children, ...rest }: ModalProps): react.JSX.Element;
238
+ type ModalSectionProps = HTMLAttributes<HTMLDivElement>;
239
+ /** Modal heading region; its content labels the dialog for assistive tech. */
240
+ declare function ModalHeader({ className, ...rest }: ModalSectionProps): react.JSX.Element;
241
+ /** Modal main content region. */
242
+ declare function ModalBody({ className, ...rest }: ModalSectionProps): react.JSX.Element;
243
+ /** Modal actions region. */
244
+ declare function ModalFooter({ className, ...rest }: ModalSectionProps): react.JSX.Element;
245
+
246
+ interface DrawerProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
101
247
  open: boolean;
102
- onClose?: () => void;
248
+ /** Called after the drawer opens or closes (Escape, backdrop, close buttons). */
249
+ onOpenChange?: (open: boolean) => void;
103
250
  side?: 'left' | 'right';
104
- title?: ReactNode;
105
- footer?: ReactNode;
106
251
  closeOnBackdrop?: boolean;
107
252
  }
108
253
  /**
109
- * Controlled off-canvas panel built on the native `<dialog>` element. Mirrors
110
- * {@link Modal} but slides in from the chosen `side`.
254
+ * Controlled off-canvas panel built on the native `<dialog>` element and the
255
+ * drawer enhancer (focus trap, scroll-lock, background `inert`). Mirrors
256
+ * {@link Modal} but slides in from the chosen `side`. Compose with
257
+ * `<DrawerHeader>`, `<DrawerBody>`, and `<DrawerFooter>`.
111
258
  */
112
- declare function Drawer({ open, onClose, side, title, footer, closeOnBackdrop, className, children, ...rest }: DrawerProps): react.JSX.Element;
259
+ declare function Drawer({ open, onOpenChange, side, closeOnBackdrop, className, children, ...rest }: DrawerProps): react.JSX.Element;
260
+ type DrawerSectionProps = HTMLAttributes<HTMLDivElement>;
261
+ /** Drawer heading region. */
262
+ declare function DrawerHeader({ className, ...rest }: DrawerSectionProps): react.JSX.Element;
263
+ /** Drawer main content region. */
264
+ declare function DrawerBody({ className, ...rest }: DrawerSectionProps): react.JSX.Element;
265
+ /** Drawer actions region. */
266
+ declare function DrawerFooter({ className, ...rest }: DrawerSectionProps): react.JSX.Element;
113
267
 
114
268
  interface PopoverProps extends HTMLAttributes<HTMLDivElement> {
115
269
  open: boolean;
270
+ /** Called when Escape or an outside click requests dismissal. */
271
+ onOpenChange?: (open: boolean) => void;
116
272
  children?: ReactNode;
117
273
  }
118
274
  /**
119
- * Controlled floating content. Visibility follows the `open` prop. Pair it with
120
- * your own trigger button (toggling `open`) and position it with the
275
+ * Controlled floating content. Visibility follows the `open` prop; wire
276
+ * `onOpenChange` to let Escape and outside clicks request dismissal. Pair it
277
+ * with your own trigger button (toggling `open`) and position it with the
121
278
  * `hydrateless/popover.css` styles.
122
279
  */
123
- declare function Popover({ open, children, ...rest }: PopoverProps): react.JSX.Element;
280
+ declare function Popover({ open, onOpenChange, children, ...rest }: PopoverProps): react.JSX.Element;
124
281
 
125
282
  interface TooltipProps {
126
283
  /** The hint text shown on hover/focus. */
@@ -135,16 +292,28 @@ interface TooltipProps {
135
292
  */
136
293
  declare function Tooltip({ label, children, id }: TooltipProps): react.JSX.Element;
137
294
 
138
- interface BreadcrumbItem {
139
- label: ReactNode;
295
+ type BreadcrumbProps = HTMLAttributes<HTMLElement>;
296
+ /**
297
+ * Semantic breadcrumb navigation (`<nav> > <ol>`). CSS-only, no enhancer.
298
+ * Compose with `<BreadcrumbItem>`.
299
+ *
300
+ * ```tsx
301
+ * <Breadcrumb>
302
+ * <BreadcrumbItem href="/">Home</BreadcrumbItem>
303
+ * <BreadcrumbItem current>Components</BreadcrumbItem>
304
+ * </Breadcrumb>
305
+ * ```
306
+ */
307
+ declare function Breadcrumb({ children, ...rest }: BreadcrumbProps): react.JSX.Element;
308
+ interface BreadcrumbItemProps extends Omit<LiHTMLAttributes<HTMLLIElement>, 'children'> {
140
309
  href?: string;
310
+ /** Marks the current page; renders a non-link with `aria-current="page"`. */
141
311
  current?: boolean;
312
+ children?: ReactNode;
313
+ anchorProps?: AnchorHTMLAttributes<HTMLAnchorElement>;
142
314
  }
143
- interface BreadcrumbProps extends HTMLAttributes<HTMLElement> {
144
- items: BreadcrumbItem[];
145
- }
146
- /** Semantic breadcrumb navigation (`<nav> > <ol>`). CSS-only, no enhancer. */
147
- declare function Breadcrumb({ items, ...rest }: BreadcrumbProps): react.JSX.Element;
315
+ /** A single crumb. Renders a link unless `current` (or no `href`) is set. */
316
+ declare function BreadcrumbItem({ href, current, anchorProps, children, ...rest }: BreadcrumbItemProps): react.JSX.Element;
148
317
 
149
318
  interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
150
319
  children?: ReactNode;
@@ -169,76 +338,101 @@ interface TocProps extends HTMLAttributes<HTMLElement> {
169
338
  /** Auto-generated table of contents with optional scroll-spy. */
170
339
  declare function Toc({ contentSelector, headings, scrollSpy, ...rest }: TocProps): react.JSX.Element;
171
340
 
172
- interface ToastProviderProps {
173
- children?: ReactNode;
174
- }
341
+ type ToastRegionProps = HTMLAttributes<HTMLDivElement>;
175
342
  /**
176
- * Provides a toast region and exposes the imperative toast API via
177
- * {@link useToast}. Render once near the root of your app.
343
+ * The polite live region toasts render into. Render once near the root of
344
+ * your app to control where toasts appear; if omitted, the first `show()`
345
+ * call creates a region at the end of `<body>`.
178
346
  */
179
- declare function ToastProvider({ children }: ToastProviderProps): react.JSX.Element;
180
- /** Access the toast API. Must be called within a {@link ToastProvider}. */
181
- declare function useToast(): ToastApi;
182
-
183
- interface MenuItemDef {
184
- label: ReactNode;
185
- href?: string;
186
- onSelect?: () => void;
187
- disabled?: boolean;
188
- items?: MenuItemDef[];
189
- }
190
- interface MenuProps extends HTMLAttributes<HTMLUListElement> {
191
- items: MenuItemDef[];
192
- orientation?: 'horizontal' | 'vertical';
193
- }
347
+ declare function ToastRegion(props: ToastRegionProps): react.JSX.Element;
194
348
  /**
195
- * Menubar / navigation menu. The enhancer wires roving tabindex, arrow
196
- * navigation, and single-level submenu toggling per the WAI-ARIA menubar
197
- * pattern.
349
+ * Access the imperative toast API (`show`/`dismiss`). Works with or without a
350
+ * mounted {@link ToastRegion}.
198
351
  */
199
- declare function Menu({ items, orientation, ...rest }: MenuProps): react.JSX.Element;
352
+ declare function useToast(): ToastApi;
200
353
 
201
- interface ComboboxOption {
202
- value: string;
203
- label?: ReactNode;
204
- }
205
354
  interface ComboboxProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
206
- options: ComboboxOption[];
355
+ filter?: EnhanceComboboxOptions['filter'];
356
+ autoHighlight?: EnhanceComboboxOptions['autoHighlight'];
357
+ /** Controlled committed value (pair with `onValueChange`). */
358
+ value?: string;
359
+ /** Initial committed value for uncontrolled usage. */
207
360
  defaultValue?: string;
208
- placeholder?: string;
361
+ /** Fires with the committed value when an option is selected. */
209
362
  onValueChange?: (value: string) => void;
210
- inputProps?: Omit<InputHTMLAttributes<HTMLInputElement>, 'role'>;
211
363
  }
212
364
  /**
213
- * Editable combobox (input + listbox). The enhancer adds filtering,
214
- * `aria-activedescendant` navigation, and selection; `onValueChange` fires when
215
- * an option is committed.
365
+ * Editable combobox (input + listbox) implementing the APG pattern. Compose with
366
+ * `<ComboboxInput>`, `<ComboboxList>`, and `<ComboboxOption>`. The enhancer adds
367
+ * filtering, `aria-activedescendant` navigation, and selection; the committed
368
+ * value works uncontrolled (`defaultValue`) or controlled (`value` +
369
+ * `onValueChange`).
370
+ *
371
+ * ```tsx
372
+ * <Combobox value={fruit} onValueChange={setFruit}>
373
+ * <ComboboxInput placeholder="Search…" />
374
+ * <ComboboxList>
375
+ * <ComboboxOption value="apple">Apple</ComboboxOption>
376
+ * <ComboboxOption value="banana">Banana</ComboboxOption>
377
+ * </ComboboxList>
378
+ * </Combobox>
379
+ * ```
216
380
  */
217
- declare function Combobox({ options, defaultValue, placeholder, onValueChange, inputProps, ...rest }: ComboboxProps): react.JSX.Element;
218
-
219
- interface CommandItemDef {
381
+ declare function Combobox({ filter, autoHighlight, value, defaultValue, onValueChange, children, ...rest }: ComboboxProps): react.JSX.Element;
382
+ interface ComboboxInputProps extends InputHTMLAttributes<HTMLInputElement> {
383
+ /** Apply the `hl-input` style. Defaults to `true`. */
384
+ styled?: boolean;
385
+ }
386
+ /** The combobox text field. */
387
+ declare function ComboboxInput({ styled, className, ...rest }: ComboboxInputProps): react.JSX.Element;
388
+ type ComboboxListProps = HTMLAttributes<HTMLUListElement>;
389
+ /** The option popup (`role="listbox"`). */
390
+ declare function ComboboxList({ children, ...rest }: ComboboxListProps): react.JSX.Element;
391
+ interface ComboboxOptionProps extends Omit<LiHTMLAttributes<HTMLLIElement>, 'value'> {
220
392
  value: string;
221
- label: ReactNode;
222
- keywords?: string;
223
- group?: string;
224
- icon?: ReactNode;
225
- href?: string;
226
- onSelect?: () => void;
227
393
  }
394
+ /** A selectable option. The `value` is committed on selection. */
395
+ declare function ComboboxOption({ value, children, ...rest }: ComboboxOptionProps): react.JSX.Element;
396
+
228
397
  interface CommandProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
229
- items: CommandItemDef[];
230
- placeholder?: string;
231
- emptyLabel?: ReactNode;
232
398
  /** Lowercased key that opens the palette's dialog with Cmd/Ctrl. */
233
399
  hotkey?: string;
400
+ /** Fires with the chosen item's value when a command runs. */
234
401
  onSelect?: (value: string) => void;
235
402
  }
236
403
  /**
237
- * Command palette. The enhancer filters items (text + keywords), provides arrow
238
- * navigation and an empty state, and runs the active item on Enter; `onSelect`
239
- * receives the chosen item's value. Place inside a `<dialog>` to use `hotkey`.
404
+ * Command palette. Compose with `<CommandInput>`, `<CommandList>`,
405
+ * `<CommandGroup>`, `<CommandItem>`, and `<CommandEmpty>`. The enhancer filters
406
+ * items (text + keywords), provides arrow navigation and an empty state, and
407
+ * runs the active item on Enter. Place inside a `<dialog>` to use `hotkey`.
240
408
  */
241
- declare function Command({ items, placeholder, emptyLabel, hotkey, onSelect, ...rest }: CommandProps): react.JSX.Element;
409
+ declare function Command({ hotkey, onSelect, children, ...rest }: CommandProps): react.JSX.Element;
410
+ interface CommandInputProps extends InputHTMLAttributes<HTMLInputElement> {
411
+ styled?: boolean;
412
+ }
413
+ /** The palette search field. */
414
+ declare function CommandInput({ styled, className, ...rest }: CommandInputProps): react.JSX.Element;
415
+ type CommandListProps = HTMLAttributes<HTMLDivElement>;
416
+ /** The scrollable list of commands (`role="listbox"`). */
417
+ declare function CommandList({ children, ...rest }: CommandListProps): react.JSX.Element;
418
+ interface CommandGroupProps extends HTMLAttributes<HTMLDivElement> {
419
+ /** Optional heading shown above the grouped items. */
420
+ label?: ReactNode;
421
+ }
422
+ /** A labelled group of commands. */
423
+ declare function CommandGroup({ label, children, ...rest }: CommandGroupProps): react.JSX.Element;
424
+ interface CommandItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
425
+ value: string;
426
+ /** Extra search terms for filtering. */
427
+ keywords?: string;
428
+ /** Leading icon node. */
429
+ icon?: ReactNode;
430
+ }
431
+ /** A runnable command (`role="option"`). */
432
+ declare function CommandItem({ value, keywords, icon, children, ...rest }: CommandItemProps): react.JSX.Element;
433
+ type CommandEmptyProps = HTMLAttributes<HTMLDivElement>;
434
+ /** Shown when no commands match the query. */
435
+ declare function CommandEmpty({ children, ...rest }: CommandEmptyProps): react.JSX.Element;
242
436
 
243
437
  interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
244
438
  size?: 'sm' | 'md' | 'lg';
@@ -301,8 +495,9 @@ interface FieldProps extends HTMLAttributes<HTMLDivElement> {
301
495
  }
302
496
  /**
303
497
  * Layout + accessibility wrapper for a form control. Provides a shared id so
304
- * `<Label>`, `<Help>`, and `<Error>` wire up `htmlFor`/`aria-describedby`
305
- * automatically; spread {@link useField}'s result onto your control.
498
+ * `<FieldLabel>`, `<FieldHelp>`, and `<FieldError>` wire up
499
+ * `htmlFor`/`aria-describedby` automatically; spread {@link useField}'s result
500
+ * onto your control.
306
501
  */
307
502
  declare function Field({ id, invalid, required, className, children, ...rest }: FieldProps): react.JSX.Element;
308
503
  /**
@@ -314,11 +509,11 @@ declare function useField(): {
314
509
  'aria-describedby': string | undefined;
315
510
  'aria-invalid': true | undefined;
316
511
  };
317
- type LabelProps = LabelHTMLAttributes<HTMLLabelElement>;
512
+ type FieldLabelProps = LabelHTMLAttributes<HTMLLabelElement>;
318
513
  /** Label bound to the enclosing field's control via `htmlFor`. */
319
- declare function Label({ className, children, ...rest }: LabelProps): react.JSX.Element;
514
+ declare function FieldLabel({ className, children, ...rest }: FieldLabelProps): react.JSX.Element;
320
515
  /** Supplementary help text, referenced by the control's `aria-describedby`. */
321
- declare function Help({ className, children, ...rest }: HTMLAttributes<HTMLParagraphElement>): react.JSX.Element;
516
+ declare function FieldHelp({ className, children, ...rest }: HTMLAttributes<HTMLParagraphElement>): react.JSX.Element;
322
517
  /** Validation message; renders nothing unless given content. */
323
518
  declare function FieldError({ className, children, ...rest }: HTMLAttributes<HTMLParagraphElement>): react.JSX.Element | null;
324
519
  interface FieldsetProps extends HTMLAttributes<HTMLFieldSetElement> {
@@ -461,4 +656,7 @@ interface SeparatorProps extends HTMLAttributes<HTMLHRElement> {
461
656
  /** Separator primitive — `<hr class="hl-separator">`. */
462
657
  declare const Separator: react.ForwardRefExoticComponent<SeparatorProps & react.RefAttributes<HTMLHRElement>>;
463
658
 
464
- export { Accordion, AccordionItem, type AccordionItemProps, type AccordionProps, Alert, type AlertProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, Badge, type BadgeProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, CardBody, CardDescription, CardFooter, CardHeader, type CardProps, type CardSectionProps, CardTitle, Checkbox, type CheckboxProps, Combobox, type ComboboxOption, type ComboboxProps, Command, type CommandItemDef, type CommandProps, Disclosure, type DisclosureProps, Drawer, type DrawerProps, Dropdown, type DropdownItem, type DropdownProps, Field, FieldError, type FieldProps, Fieldset, type FieldsetProps, Help, Input, type InputProps, Kbd, type KbdProps, Label, type LabelProps, Menu, type MenuItemDef, type MenuProps, Modal, type ModalProps, 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, type TabItem, Tabs, type TabsProps, Textarea, type TextareaProps, ToastProvider, type ToastProviderProps, Toc, type TocProps, Tooltip, type TooltipProps, useAccordion, useDisclosureGroup, useDropdown, useEnhancer, useField, useModalGroup, useTabs, useToast, useTocEnhancer, useTooltip };
659
+ /** Join truthy class names into a single string. */
660
+ declare function cx(...classes: Array<string | false | null | undefined>): string;
661
+
662
+ 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 };