@hydrateless/react 0.8.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +128 -19
- package/dist/index.d.ts +363 -184
- package/dist/index.js +800 -621
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# @hydrateless/react
|
|
2
2
|
|
|
3
3
|
React bindings for [Hydrateless](https://github.com/hydrateless/hydrateless). Thin
|
|
4
|
-
|
|
5
|
-
|
|
4
|
+
components that render semantic HTML and wire the framework-agnostic enhancers,
|
|
5
|
+
with automatic cleanup on unmount.
|
|
6
6
|
|
|
7
7
|
## Install
|
|
8
8
|
|
|
@@ -37,14 +37,24 @@ function Example() {
|
|
|
37
37
|
}
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
|
|
41
|
-
|
|
40
|
+
Every component forwards `ref`, `className`, `id`, and any other attributes to
|
|
41
|
+
its root element. Interactive components work uncontrolled (`defaultValue` /
|
|
42
|
+
`defaultOpen`) or fully controlled (`value` + `onValueChange`, `open` +
|
|
43
|
+
`onOpenChange`). Tabs render `aria-selected`, `hidden`, and `tabindex` from the
|
|
44
|
+
value during render, so server output is correct before hydration.
|
|
42
45
|
|
|
43
|
-
###
|
|
46
|
+
### Server Components
|
|
44
47
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
+
The package is a client bundle: `'use client'` is embedded at the top of the
|
|
49
|
+
built module, so you can import any component from a React Server Components
|
|
50
|
+
app (Next.js App Router, for example) without wrapping it yourself.
|
|
51
|
+
|
|
52
|
+
### Dialogs
|
|
53
|
+
|
|
54
|
+
`Modal` and `Drawer` are built on the native `<dialog>` element plus the modal
|
|
55
|
+
enhancer (focus trap, scroll-lock, background `inert`). Escape and backdrop
|
|
56
|
+
clicks report back through `onOpenChange`. `Drawer` takes `side="start" | "end"`
|
|
57
|
+
(default `end`), which follows the writing direction.
|
|
48
58
|
|
|
49
59
|
```tsx
|
|
50
60
|
const [open, setOpen] = useState(false);
|
|
@@ -57,29 +67,131 @@ const [open, setOpen] = useState(false);
|
|
|
57
67
|
</Modal>;
|
|
58
68
|
```
|
|
59
69
|
|
|
70
|
+
### Dropdown
|
|
71
|
+
|
|
72
|
+
The menu renders as a native `popover` and the trigger carries `popovertarget`,
|
|
73
|
+
so the menu opens before hydration. Items can be plain, checkable, or radio,
|
|
74
|
+
and `onSelect` receives the value, the element, and (for checkable items) the
|
|
75
|
+
new checked state. Pass `closeOnSelect={false}` for menus that stay open while
|
|
76
|
+
several items are toggled.
|
|
77
|
+
|
|
78
|
+
```tsx
|
|
79
|
+
<Dropdown closeOnSelect={false} onSelect={(value, _item, checked) => toggle(value, checked)}>
|
|
80
|
+
<DropdownTrigger>View</DropdownTrigger>
|
|
81
|
+
<DropdownMenu>
|
|
82
|
+
<DropdownItem value="reload">Reload</DropdownItem>
|
|
83
|
+
<DropdownSeparator />
|
|
84
|
+
<DropdownGroup label="Panels">
|
|
85
|
+
<DropdownItem role="menuitemcheckbox" value="sidebar" checked={sidebar}>
|
|
86
|
+
Sidebar
|
|
87
|
+
</DropdownItem>
|
|
88
|
+
<DropdownItem role="menuitemcheckbox" value="minimap" checked={minimap} disabled>
|
|
89
|
+
Minimap
|
|
90
|
+
</DropdownItem>
|
|
91
|
+
</DropdownGroup>
|
|
92
|
+
</DropdownMenu>
|
|
93
|
+
</Dropdown>
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Menu
|
|
97
|
+
|
|
98
|
+
`Menu` is a menubar (or vertical menu) whose value is the open submenu. Use
|
|
99
|
+
`MenuItem` for leaf items and `MenuSubmenu` for items that open a flyout;
|
|
100
|
+
control it with `value` / `defaultValue` / `onValueChange` (`null` means every
|
|
101
|
+
submenu is closed) and listen for activations with `onSelect`.
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
<Menu value={openSubmenu} onValueChange={setOpenSubmenu} onSelect={navigate}>
|
|
105
|
+
<MenuItem href="/">Home</MenuItem>
|
|
106
|
+
<MenuSubmenu label="Resources" value="resources">
|
|
107
|
+
<MenuItem href="/docs">Docs</MenuItem>
|
|
108
|
+
<MenuItem href="/blog">Blog</MenuItem>
|
|
109
|
+
</MenuSubmenu>
|
|
110
|
+
</Menu>
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Command palette
|
|
114
|
+
|
|
115
|
+
`Command` exposes the filter query as `query` / `defaultQuery` / `onQueryChange`
|
|
116
|
+
and reports the chosen item through `onCommand(value, item)`. Inside a
|
|
117
|
+
`<dialog>`, `hotkey="k"` opens it with Cmd/Ctrl+K.
|
|
118
|
+
|
|
119
|
+
### Forms
|
|
120
|
+
|
|
121
|
+
`Field` wires a label, help text, and error message to its control. The
|
|
122
|
+
built-in controls (`Input`, `Textarea`, `Select`, `Checkbox`, `Switch`,
|
|
123
|
+
`Slider`, `ComboboxInput`) read the field automatically and pick up `id`,
|
|
124
|
+
`aria-describedby`, `aria-invalid`, and `required`; they also work on their
|
|
125
|
+
own outside a Field.
|
|
126
|
+
|
|
127
|
+
```tsx
|
|
128
|
+
<Field label="Email" description="We never share it." error={errors.email} required>
|
|
129
|
+
<Input type="email" />
|
|
130
|
+
</Field>
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
For a custom control, `useField()` returns
|
|
134
|
+
`{ id, describedBy, invalid, required }`, or `null` outside a Field:
|
|
135
|
+
|
|
136
|
+
```tsx
|
|
137
|
+
function ColorPicker() {
|
|
138
|
+
const field = useField();
|
|
139
|
+
return (
|
|
140
|
+
<input
|
|
141
|
+
type="color"
|
|
142
|
+
id={field?.id}
|
|
143
|
+
aria-describedby={field?.describedBy}
|
|
144
|
+
aria-invalid={field?.invalid || undefined}
|
|
145
|
+
required={field?.required}
|
|
146
|
+
/>
|
|
147
|
+
);
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
60
151
|
### Toasts
|
|
61
152
|
|
|
62
|
-
`useToast()` works anywhere, no provider required.
|
|
63
|
-
|
|
153
|
+
`useToast()` works anywhere, no provider required. It returns
|
|
154
|
+
`show(message, { duration, intent })` (which returns the toast element) and
|
|
155
|
+
`dismiss(toast)`. `intent` is one of `info`, `success`, `warning`, or `danger`
|
|
156
|
+
and is rendered as `data-hl-intent`; `danger` toasts are announced assertively.
|
|
157
|
+
Render `<ToastRegion />` once if you want to control where toasts appear; it
|
|
158
|
+
enhances on mount.
|
|
64
159
|
|
|
65
160
|
```tsx
|
|
66
161
|
function Save() {
|
|
67
162
|
const toast = useToast();
|
|
68
|
-
return <button onClick={() => toast.show('Saved', {
|
|
163
|
+
return <button onClick={() => toast.show('Saved', { intent: 'success' })}>Save</button>;
|
|
69
164
|
}
|
|
70
165
|
```
|
|
71
166
|
|
|
72
|
-
|
|
167
|
+
### Other changes worth knowing
|
|
73
168
|
|
|
74
|
-
|
|
75
|
-
|
|
169
|
+
- `Skeleton` takes `shape="text" | "circle" | "rect"` (rendered as
|
|
170
|
+
`data-hl-shape`); `width` and `height` map to the logical `inline-size` and
|
|
171
|
+
`block-size`.
|
|
172
|
+
- `Tooltip` takes `content` plus `placement`, `showDelay`, `hideDelay`, and
|
|
173
|
+
`open` / `onOpenChange`.
|
|
174
|
+
- `SegmentedControl` selects the first option when uncontrolled and no
|
|
175
|
+
`defaultValue` is given.
|
|
176
|
+
- `Table` renders `<table class="hl-table">` with `striped`, `hover`,
|
|
177
|
+
`align="start" | "center" | "end"`, and `size` modifiers.
|
|
178
|
+
|
|
179
|
+
## Escape hatch: `useEnhancer`
|
|
180
|
+
|
|
181
|
+
For your own markup, attach any enhancer with `useEnhancer(ref, enhancer,
|
|
182
|
+
options, deps)`. It returns a ref to the enhancer's imperative API, destroys
|
|
183
|
+
the instance on unmount, and re-creates it when `deps` change. Callback options
|
|
184
|
+
always call the handler from the latest render, so they never need to be
|
|
185
|
+
listed in `deps`.
|
|
76
186
|
|
|
77
187
|
```tsx
|
|
188
|
+
import { useRef } from 'react';
|
|
78
189
|
import { useEnhancer } from '@hydrateless/react';
|
|
79
|
-
import { enhanceTabs
|
|
190
|
+
import { enhanceTabs } from '@hydrateless/enhancers';
|
|
80
191
|
|
|
81
192
|
function CustomTabs() {
|
|
82
|
-
const
|
|
193
|
+
const ref = useRef<HTMLDivElement>(null);
|
|
194
|
+
const api = useEnhancer(ref, enhanceTabs, { activation: 'automatic', onValueChange: log });
|
|
83
195
|
// api.current?.setValue('install')
|
|
84
196
|
return (
|
|
85
197
|
<div data-hl-tabs ref={ref}>
|
|
@@ -89,9 +201,6 @@ function CustomTabs() {
|
|
|
89
201
|
}
|
|
90
202
|
```
|
|
91
203
|
|
|
92
|
-
Convenience hooks: `useTabs`, `useDropdown`, `useTooltip`, `useAccordion`,
|
|
93
|
-
`useModalGroup`, `useTocEnhancer`.
|
|
94
|
-
|
|
95
204
|
## License
|
|
96
205
|
|
|
97
206
|
[MIT](../../LICENSE)
|