@hydrateless/vue 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.
Files changed (4) hide show
  1. package/README.md +125 -40
  2. package/dist/index.d.ts +2340 -1007
  3. package/dist/index.js +1297 -1451
  4. package/package.json +5 -5
package/README.md CHANGED
@@ -1,8 +1,12 @@
1
1
  # @hydrateless/vue
2
2
 
3
3
  Vue 3 bindings for [Hydrateless](https://github.com/hydrateless/hydrateless):
4
- directives, composables, and a plugin that wire the framework-agnostic
5
- enhancers, with automatic cleanup when components unmount.
4
+ first-class components that render the library's HTML and attach the
5
+ framework-agnostic enhancers on mount, plus three composables (`useEnhancer`,
6
+ `useField`, `useToast`) for anything the components don't cover.
7
+
8
+ Requires Vue 3.5 or later (the package uses `useId()` for every generated id,
9
+ so server and client markup always agree).
6
10
 
7
11
  ## Install
8
12
 
@@ -16,39 +20,15 @@ Import the CSS once (e.g., in your entry):
16
20
  import 'hydrateless/hydrateless.css';
17
21
  ```
18
22
 
19
- ## Plugin (global directives)
20
-
21
- ```ts
22
- import { createApp } from 'vue';
23
- import { HydratelessPlugin } from '@hydrateless/vue';
24
- import App from './App.vue';
25
-
26
- createApp(App).use(HydratelessPlugin).mount('#app');
27
- ```
28
-
29
- Then use the directives in any template:
30
-
31
- ```vue
32
- <template>
33
- <div v-hl-tabs data-hl-tabs>
34
- <div role="tablist">
35
- <button role="tab">Overview</button>
36
- <button role="tab">Install</button>
37
- </div>
38
- <div role="tabpanel">Zero runtime by default.</div>
39
- <div role="tabpanel"><code>npm i hydrateless</code></div>
40
- </div>
41
- </template>
42
- ```
43
-
44
- Available directives: `v-hl-accordion`, `v-hl-disclosure`, `v-hl-tabs`,
45
- `v-hl-dropdown`, `v-hl-modal`, `v-hl-drawer`, `v-hl-popover`, `v-hl-tooltip`,
46
- `v-hl-toc`. You can also import individual directives (e.g., `vHlTabs`) and
47
- register them locally.
48
-
49
23
  ## Components
50
24
 
51
- Interactive components support `v-model` on their state:
25
+ Every component forwards `class`, `id`, and other attributes to its root
26
+ element and exports a `XProps` type (`TabsProps`, `DropdownItemProps`, and so
27
+ on). Stateful components work uncontrolled out of the box and accept `v-model`
28
+ for their primary value: `modelValue`/`defaultValue` for values, and
29
+ `open`/`defaultOpen` (`v-model:open`) for open state. Selection state is
30
+ rendered on the server (`aria-selected`, `hidden`, `popover`, `popovertarget`),
31
+ so nothing flashes before hydration.
52
32
 
53
33
  ```vue
54
34
  <script setup lang="ts">
@@ -76,25 +56,130 @@ const open = ref(false);
76
56
  </template>
77
57
  ```
78
58
 
79
- ## Composables
59
+ ### Prop and event contracts
60
+
61
+ | Component | State | Events | Notes |
62
+ | ------------------ | ------------------------------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------- |
63
+ | `Tabs` | `v-model` (`modelValue`/`defaultValue`) | `update:modelValue` | `orientation`, `activation` |
64
+ | `Accordion` | `v-model` (`string[]`) | `update:modelValue` | `allowMultiple`; `AccordionItem` takes `value` and `title` or a summary slot |
65
+ | `Disclosure` | `v-model:open` | `update:open` | |
66
+ | `Dropdown` | `v-model:open` | `update:open`, `select` | `closeOnSelect`, `placement`; `select` gets `(value, item, checked?)` |
67
+ | `Menu` | `v-model` (open submenu value or `null`) | `update:modelValue`, `select` | `orientation`; no `open` prop |
68
+ | `Command` | `v-model:query` (`query`/`defaultQuery`) | `update:query`, `command` | `hotkey`; `command` gets `(value, item)` |
69
+ | `Combobox` | `v-model` and `v-model:open` | `update:modelValue`, `update:open` | `filter`, `autoHighlight`; `ComboboxOption` takes `disabled` |
70
+ | `Modal`, `Drawer` | `v-model:open` | `update:open` | `closeOnBackdrop`; `Drawer` takes `side: 'start' \| 'end'` (default `end`) |
71
+ | `Popover` | `v-model:open` | `update:open` | `placement`, `hover` |
72
+ | `Tooltip` | `v-model:open` | `update:open` | `content`, `placement`, `showDelay`, `hideDelay` |
73
+ | `SegmentedControl` | `v-model`; uncontrolled default is the first `options` | `update:modelValue` | `options`, `size` |
74
+ | `Pagination` | `v-model:page` | `update:page` | `count`, `siblingCount` |
75
+
76
+ `DropdownItem` takes `value`, `disabled`, `role` (`menuitem`, `menuitemcheckbox`,
77
+ or `menuitemradio`), and `checked`, and emits both `click` and `select`.
78
+ `DropdownGroup` wraps items in a labelled `role="group"` (radio items check one
79
+ per group), and `DropdownSeparator` draws a divider. `MenuSubmenu` opens a
80
+ flyout of `MenuItem`s from a top-level `Menu`.
81
+
82
+ Primitives: `Alert`, `Avatar`, `AvatarGroup`, `Badge`, `Breadcrumb`, `Button`,
83
+ `Card` (with `CardHeader`, `CardBody`, `CardFooter`, `CardTitle`,
84
+ `CardDescription`), `Kbd`, `Progress`, `Separator`, `Skeleton` (`shape`,
85
+ `width`, `height`), `SkipLink`, `Spinner`, `Table` (`striped`, `hover`,
86
+ `align`, `size`), and `Toc`.
87
+
88
+ ## Forms and `useField()`
89
+
90
+ `<Field>` gives its control an id and describes it with the help and error
91
+ text. Pass `label`, `description`, `error`, and `required` as props, or compose
92
+ `<FieldLabel>`, `<FieldHelp>`, and `<FieldError>` yourself. Every Hydrateless
93
+ control (`Input`, `Textarea`, `Select`, `Checkbox`, `Switch`, `Slider`,
94
+ `ComboboxInput`) reads the field automatically: `id`, `aria-describedby`,
95
+ `aria-invalid`, and `required` are wired for you, and the controls work
96
+ unchanged outside a field.
97
+
98
+ ```vue
99
+ <Field label="Email" description="We never share it." :error="error" required>
100
+ <Input v-model="email" type="email" />
101
+ </Field>
102
+ ```
103
+
104
+ For a custom control, call `useField()`. It returns `{ id, describedBy,
105
+ invalid, required }` (reactive) inside a `<Field>` and `null` outside one.
80
106
 
81
107
  ```vue
82
108
  <script setup lang="ts">
83
- import { useEnhancer, useToast } from '@hydrateless/vue';
109
+ import { useField } from '@hydrateless/vue';
110
+ const field = useField();
111
+ </script>
112
+
113
+ <template>
114
+ <div
115
+ role="textbox"
116
+ :id="field?.id"
117
+ :aria-describedby="field?.describedBy"
118
+ :aria-invalid="field?.invalid || undefined"
119
+ />
120
+ </template>
121
+ ```
122
+
123
+ ## Toasts
124
+
125
+ Mount `<ToastRegion>` once near the app root; it enhances itself on mount. Then
126
+ call `useToast()` anywhere. No provider is required.
127
+
128
+ ```vue
129
+ <script setup lang="ts">
130
+ import { ToastRegion, useToast } from '@hydrateless/vue';
131
+
132
+ const toast = useToast();
133
+ const save = () => toast.show('Saved', { intent: 'success', duration: 4000 });
134
+ </script>
135
+
136
+ <template>
137
+ <button @click="save">Save</button>
138
+ <ToastRegion />
139
+ </template>
140
+ ```
141
+
142
+ `show(message, { duration, intent })` returns the toast element, which you can
143
+ pass to `dismiss()`. Intents are `info`, `success`, `warning`, and `danger`
144
+ (`danger` toasts are announced assertively).
145
+
146
+ ## `useEnhancer()`
147
+
148
+ The one low-level escape hatch. Pass a template ref, an enhancer from
149
+ `@hydrateless/enhancers`, and its options; the enhancer attaches on mount, is
150
+ destroyed on unmount, and its imperative API is returned as a shallow ref.
151
+
152
+ ```vue
153
+ <script setup lang="ts">
154
+ import { useTemplateRef } from 'vue';
155
+ import { useEnhancer } from '@hydrateless/vue';
84
156
  import { enhanceDropdown } from '@hydrateless/enhancers';
85
157
 
86
- const { host, api } = useEnhancer((el) => enhanceDropdown(el));
158
+ const host = useTemplateRef('host');
159
+ const api = useEnhancer(host, enhanceDropdown, { placement: 'bottom-end' });
87
160
  // api.value?.setOpen(true)
88
-
89
- const toast = useToast(); // no provider required
90
161
  </script>
91
162
 
92
163
  <template>
93
- <div ref="host" data-hl-dropdown>…</div>
94
- <button @click="toast.show('Saved')">Save</button>
164
+ <div ref="host" data-hl-dropdown>...</div>
95
165
  </template>
96
166
  ```
97
167
 
168
+ Pass a getter for `options` and a fourth `deps` watch source to re-attach when
169
+ an option changes.
170
+
171
+ ## Breaking changes in this release
172
+
173
+ - The `v-hl-*` directives and `HydratelessPlugin` are gone; use the components
174
+ or `useEnhancer`.
175
+ - `useFieldBindings()` is now `useField()` and returns `{ id, describedBy,
176
+ invalid, required } | null` instead of attribute names.
177
+ - `Menu` is controlled through `v-model` (the open submenu's value) instead of
178
+ `v-model:open`.
179
+ - `Command` uses `v-model:query` and emits `command` (was `select`).
180
+ - `Drawer` `side` is `'start' | 'end'`; `Skeleton` `variant` is `shape`;
181
+ `Tooltip` `label` is `content`; toast `variant` is `intent`.
182
+
98
183
  ## License
99
184
 
100
185
  [MIT](../../LICENSE)