@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.
- package/README.md +125 -40
- package/dist/index.d.ts +2340 -1007
- package/dist/index.js +1297 -1451
- 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
|
-
|
|
5
|
-
enhancers
|
|
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
|
-
|
|
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
|
-
|
|
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 {
|
|
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
|
|
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
|
|
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)
|