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