@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.
Files changed (4) hide show
  1. package/README.md +128 -19
  2. package/dist/index.d.ts +367 -183
  3. package/dist/index.js +821 -620
  4. 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
- hooks and components that render semantic HTML and wire the framework-agnostic
5
- enhancers, with automatic cleanup on unmount.
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
- Interactive components work uncontrolled (`defaultValue` / `defaultOpen`) or
41
- fully controlled (`value` + `onValueChange`, `open` + `onOpenChange`).
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
- ### Controlled dialogs
46
+ ### Server Components
44
47
 
45
- `Modal` and `Drawer` are controlled via the `open` prop and built on the native
46
- `<dialog>` element plus the modal enhancer (focus trap, scroll-lock, background
47
- `inert`). Escape and backdrop clicks report back through `onOpenChange`:
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. Render `<ToastRegion />`
63
- once if you want to control where toasts appear:
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', { variant: 'success' })}>Save</button>;
163
+ return <button onClick={() => toast.show('Saved', { intent: 'success' })}>Save</button>;
69
164
  }
70
165
  ```
71
166
 
72
- ## Hooks
167
+ ### Other changes worth knowing
73
168
 
74
- For your own markup, attach any enhancer with a ref. You get the enhancer's
75
- imperative API back, and the instance is destroyed automatically on unmount:
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, type TabsApi } from '@hydrateless/enhancers';
190
+ import { enhanceTabs } from '@hydrateless/enhancers';
80
191
 
81
192
  function CustomTabs() {
82
- const { ref, api } = useEnhancer<HTMLDivElement, TabsApi>((el) => enhanceTabs(el));
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)