@unframed/cli 0.4.0 → 0.6.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.
@@ -1,4 +1,237 @@
1
- # Unframed 0.4.0 components
1
+ # Unframed 0.6.0 components
2
+
3
+ ## Accordion
4
+
5
+ Groups `<uf-accordion-item>`s. By default opening one item closes the
6
+ others; set `multiple` to let several stay open. Up and Down arrows move
7
+ between headers, Home and End jump to the first and last.
8
+
9
+ Tags: `<uf-accordion>`, `<uf-accordion-item>`. Import: `import '@unframed/core/accordion';` (or `npx @unframed/cli add accordion` to copy the source).
10
+
11
+ ### One open at a time
12
+
13
+ Add `multiple` to let several items stay open.
14
+
15
+ ```html
16
+ <uf-accordion>
17
+ <uf-accordion-item summary="What is Unframed?" open>
18
+ A library of web components that work in any framework, or none.
19
+ </uf-accordion-item>
20
+ <uf-accordion-item summary="Can I edit the components?">…</uf-accordion-item>
21
+ </uf-accordion>
22
+ ```
23
+
24
+ ### `<uf-accordion>` API
25
+
26
+ #### Attributes and properties
27
+
28
+ | Attribute | Property | Type | Default | Description |
29
+ |---|---|---|---|---|
30
+ | `multiple` | | `boolean` | `false` | Allows several items to be open at once. |
31
+
32
+ #### Slots
33
+
34
+ | Slot | Description |
35
+ |---|---|
36
+ | (default) | `<uf-accordion-item>` elements. |
37
+
38
+ #### CSS parts
39
+
40
+ | Part | Description |
41
+ |---|---|
42
+ | `base` | The wrapper around the items. |
43
+
44
+ ### `<uf-accordion-item>` API
45
+
46
+ #### Attributes and properties
47
+
48
+ | Attribute | Property | Type | Default | Description |
49
+ |---|---|---|---|---|
50
+ | `open` | | `boolean` | `false` | Whether the item is expanded. |
51
+ | `summary` | | `string \| undefined` | | Header text. |
52
+ | `disabled` | | `boolean` | `false` | Prevents the user from toggling the item. |
53
+
54
+ #### Properties only
55
+
56
+ | Property | Type | Description |
57
+ |---|---|---|
58
+ | `header` | `HTMLElement \| null` | Read-only. The header element, for keyboard navigation between items. |
59
+
60
+ #### Methods
61
+
62
+ | Method | Description |
63
+ |---|---|
64
+ | `show()` | Expands the item. |
65
+ | `hide()` | Collapses the item. |
66
+ | `focus(options: FocusOptions)` | Focuses the header. |
67
+
68
+ #### Events
69
+
70
+ | Event | Type | Description |
71
+ |---|---|---|
72
+ | `uf-show` | | The item opened. |
73
+ | `uf-hide` | | The item closed. |
74
+
75
+ #### Slots
76
+
77
+ | Slot | Description |
78
+ |---|---|
79
+ | (default) | The content. |
80
+ | `summary` | The header, when you need markup. Overrides `summary`. |
81
+
82
+ #### CSS parts
83
+
84
+ | Part | Description |
85
+ |---|---|
86
+ | `base` | The native `<details>`. |
87
+ | `header` | The clickable header (`<summary>`). |
88
+ | `chevron` | The arrow icon. |
89
+ | `content` | The content wrapper. |
90
+
91
+ #### CSS custom properties
92
+
93
+ | Property | Description |
94
+ |---|---|
95
+ | `--uf-accordion-padding` | Horizontal padding of header and content. |
96
+
97
+ ## Avatar
98
+
99
+ A picture of a person or an entity. Shows the image when it loads, the
100
+ initials of `name` when there's no image or it fails, and a generic icon
101
+ when there's neither.
102
+
103
+ `name` is also the accessible name. When the name is already written next
104
+ to the avatar, set `decorative` so screen readers don't read it twice.
105
+
106
+ Tags: `<uf-avatar>`. Import: `import '@unframed/core/avatar';` (or `npx @unframed/cli add avatar` to copy the source).
107
+
108
+ ### Image, initials or icon
109
+
110
+ The image when it loads, the initials of `name` when it doesn't, a generic icon when there's neither.
111
+
112
+ ```html
113
+ <uf-avatar name="John Smith" src="/photos/john.jpg"></uf-avatar>
114
+ <uf-avatar name="John Smith"></uf-avatar>
115
+ <uf-avatar></uf-avatar>
116
+ ```
117
+
118
+ ### Sizes and shapes
119
+
120
+ ```html
121
+ <uf-avatar size="sm" name="John Smith"></uf-avatar>
122
+ <uf-avatar size="xl" name="John Smith"></uf-avatar>
123
+ <uf-avatar size="xl" shape="square" name="Unframed" initials="U"></uf-avatar>
124
+ ```
125
+
126
+ ### Next to a name
127
+
128
+ ```html
129
+ <uf-avatar name="John Smith" decorative></uf-avatar>
130
+ <strong>John Smith</strong>
131
+ ```
132
+
133
+ - `name` is the accessible name. When the name is written next to the avatar, add `decorative` so screen readers don't read it twice.
134
+
135
+ ### `<uf-avatar>` API
136
+
137
+ #### Attributes and properties
138
+
139
+ | Attribute | Property | Type | Default | Description |
140
+ |---|---|---|---|---|
141
+ | `src` | | `string \| undefined` | | Image URL. |
142
+ | `name` | | `string \| undefined` | | The person's or entity's name: the accessible name, and the source of the initials. |
143
+ | `initials` | | `string \| undefined` | | Initials to show instead of the ones taken from `name`. |
144
+ | `size` | | `AvatarSize` | `'md'` | Size: `sm`, `md`, `lg` or `xl`. |
145
+ | `shape` | | `AvatarShape` | `'circle'` | `circle` or `square` (rounded corners). |
146
+ | `decorative` | | `boolean` | `false` | Hides the avatar from assistive tech, when the name is already shown next to it. |
147
+ | `loading` | | `'eager' \| 'lazy'` | `'eager'` | The image's `loading` attribute: `lazy` waits until it's near the viewport. |
148
+
149
+ #### Slots
150
+
151
+ | Slot | Description |
152
+ |---|---|
153
+ | (default) | Custom content instead of the initials or icon, e.g. an `<uf-icon>`. |
154
+
155
+ #### CSS parts
156
+
157
+ | Part | Description |
158
+ |---|---|
159
+ | `base` | The avatar. |
160
+ | `image` | The `<img>`. |
161
+ | `initials` | The initials. |
162
+ | `icon` | The fallback icon. |
163
+
164
+ #### CSS custom properties
165
+
166
+ | Property | Description |
167
+ |---|---|
168
+ | `--uf-avatar-size` | Width and height. Overrides `size`. |
169
+ | `--uf-avatar-bg` | Background behind initials and icon. |
170
+ | `--uf-avatar-color` | Color of the initials and icon. |
171
+ | `--uf-avatar-radius` | Corner radius. Overrides `shape`. |
172
+
173
+ ## Badge
174
+
175
+ A short label for a status, a category or a count. It's plain text for
176
+ assistive tech: write text that makes sense out of context ("3 unread", not
177
+ just "3"), or describe it in the surrounding element's label.
178
+
179
+ Tags: `<uf-badge>`. Import: `import '@unframed/core/badge';` (or `npx @unframed/cli add badge` to copy the source).
180
+
181
+ ### Variants
182
+
183
+ Six colors by meaning, in three appearances: `soft` (the default), `solid` and `outline`.
184
+
185
+ ```html
186
+ <uf-badge>Draft</uf-badge>
187
+ <uf-badge variant="success">Paid</uf-badge>
188
+ <uf-badge variant="warning" appearance="solid">Expiring</uf-badge>
189
+ <uf-badge variant="info" appearance="outline">Beta</uf-badge>
190
+ ```
191
+
192
+ ### Dot, icon and size
193
+
194
+ ```html
195
+ <uf-badge dot variant="success">Online</uf-badge>
196
+ <uf-badge variant="success"><uf-icon slot="prefix" name="check-circle"></uf-icon>Verified</uf-badge>
197
+ <uf-badge size="sm" variant="accent">New</uf-badge>
198
+ ```
199
+
200
+ - Badges are read as plain text: write "3 unread" rather than "3", so the badge makes sense on its own.
201
+
202
+ ### `<uf-badge>` API
203
+
204
+ #### Attributes and properties
205
+
206
+ | Attribute | Property | Type | Default | Description |
207
+ |---|---|---|---|---|
208
+ | `variant` | | `BadgeVariant` | `'neutral'` | Color, by meaning: `neutral`, `accent`, `info`, `success`, `warning` or `danger`. |
209
+ | `appearance` | | `BadgeAppearance` | `'soft'` | `soft` (tinted background), `solid` (bold background) or `outline` (border only). |
210
+ | `size` | | `BadgeSize` | `'md'` | Size: `sm` or `md`. |
211
+ | `dot` | | `boolean` | `false` | Shows a status dot before the text. |
212
+
213
+ #### Slots
214
+
215
+ | Slot | Description |
216
+ |---|---|
217
+ | (default) | The badge text. |
218
+ | `prefix` | An icon before the text. |
219
+
220
+ #### CSS parts
221
+
222
+ | Part | Description |
223
+ |---|---|
224
+ | `base` | The badge. |
225
+ | `dot` | The status dot, when `dot` is set. |
226
+
227
+ #### CSS custom properties
228
+
229
+ | Property | Description |
230
+ |---|---|
231
+ | `--uf-badge-bg` | Background color. |
232
+ | `--uf-badge-color` | Text color. |
233
+ | `--uf-badge-border-color` | Border color. |
234
+ | `--uf-badge-radius` | Corner radius. Use `999px` for a pill. |
2
235
 
3
236
  ## Button
4
237
 
@@ -87,133 +320,126 @@ Icon-only buttons need a `label` for screen readers.
87
320
  | `--uf-button-font-family` | Font family. |
88
321
  | `--uf-button-font-weight` | Font weight. |
89
322
 
90
- ## Input
323
+ ## Card
91
324
 
92
- A single-line text field with a built-in label, hint and validation message.
325
+ A container that groups related content: an optional image, a header, the
326
+ content and actions. Empty sections take no space.
93
327
 
94
- Tags: `<uf-input>`. Import: `import '@unframed/core/input';` (or `npx @unframed/cli add input` to copy the source).
328
+ A card is a plain container for assistive tech. To make a whole card a link,
329
+ put a link in the header and let it cover the card with CSS, so the card's
330
+ buttons stay usable.
95
331
 
96
- ### With label, hint and validation
332
+ Tags: `<uf-card>`. Import: `import '@unframed/core/card';` (or `npx @unframed/cli add card` to copy the source).
97
333
 
98
- Errors appear after the user edits the field or tries to submit.
334
+ ### Media, header, content and footer
99
335
 
100
- ```html
101
- <form>
102
- <uf-input name="email" type="email" label="Email" hint="We never share it." required>
103
- <uf-icon slot="prefix" name="info"></uf-icon>
104
- </uf-input>
105
- <uf-button type="submit">Subscribe</uf-button>
106
- </form>
107
- ```
336
+ Every section is optional; empty ones take no space.
108
337
 
109
- ### `<uf-input>` API
110
-
111
- #### Attributes and properties
112
-
113
- | Attribute | Property | Type | Default | Description |
114
- |---|---|---|---|---|
115
- | `type` | | `InputType` | `'text'` | Input type. |
116
- | `value` | `defaultValue` | `string` | `''` | Initial value, restored on form reset. Set with the `value` attribute. |
117
- | `label` | | `string \| undefined` | | Visible label. |
118
- | `hint` | | `string \| undefined` | | Help text below the field. |
119
- | `placeholder` | | `string \| undefined` | | Placeholder text. |
120
- | `size` | | `FieldSize` | `'md'` | Size of the field. |
121
- | `readonly` | | `boolean` | `false` | Makes the field read-only. |
122
- | `autocomplete` | | `AutoFill \| undefined` | | Native `autocomplete` hint. |
123
- | `inputmode` | | `string \| undefined` | | Native `inputmode` hint for virtual keyboards. |
124
- | `pattern` | | `string \| undefined` | | Regex the value must match. |
125
- | `min` | | `string \| undefined` | | Minimum value, for number and date types. |
126
- | `max` | | `string \| undefined` | | Maximum value, for number and date types. |
127
- | `step` | | `string \| undefined` | | Step, for number and date types. |
128
- | `minlength` | | `number \| undefined` | | Minimum length. |
129
- | `maxlength` | | `number \| undefined` | | Maximum length. |
130
- | `name` | | `string` | `''` | Name submitted with the form. |
131
- | `disabled` | | `boolean` | `false` | Disables the control. |
132
- | `required` | | `boolean` | `false` | Makes the control required for form submission. |
133
-
134
- #### Properties only
338
+ ```html
339
+ <uf-card>
340
+ <img slot="media" src="/cover.png" alt="The Unframed logo" />
341
+ <div slot="header">
342
+ <h3>Unframed 0.2</h3>
343
+ <small>Released this week</small>
344
+ </div>
345
+ A link button variant, new colors and smaller Angular bundles.
346
+ <uf-button slot="footer">Read more</uf-button>
347
+ <uf-button slot="footer" variant="ghost">Dismiss</uf-button>
348
+ </uf-card>
349
+ ```
135
350
 
136
- | Property | Type | Description |
137
- |---|---|---|
138
- | `value` | `string` | Current value. |
139
- | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
140
- | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
141
- | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
142
- | `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
351
+ ### Variants and orientation
143
352
 
144
- #### Methods
353
+ ```html
354
+ <uf-card variant="elevated">…</uf-card>
355
+ <uf-card variant="filled">…</uf-card>
356
+ <uf-card orientation="horizontal">
357
+ <img slot="media" src="/cover.png" alt="" />
358
+ Media beside the content.
359
+ </uf-card>
360
+ ```
145
361
 
146
- | Method | Description |
147
- |---|---|
148
- | `select()` | Selects all text in the field. |
149
- | `checkValidity()` | Returns whether the value is valid, without showing an error. |
150
- | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
151
- | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
362
+ ### `<uf-card>` API
152
363
 
153
- #### Events
364
+ #### Attributes and properties
154
365
 
155
- | Event | Type | Description |
156
- |---|---|---|
157
- | `input` | | Fired on every keystroke. |
158
- | `change` | `Event` | Fired when the value is committed (blur or Enter). |
366
+ | Attribute | Property | Type | Default | Description |
367
+ |---|---|---|---|---|
368
+ | `variant` | | `CardVariant` | `'outline'` | `outline` (a border), `elevated` (a shadow, or an accent glow in dark mode) or `filled` (a tinted background). |
369
+ | `orientation` | | `CardOrientation` | `'vertical'` | `vertical`, or `horizontal` to put the media beside the content. |
159
370
 
160
371
  #### Slots
161
372
 
162
373
  | Slot | Description |
163
374
  |---|---|
164
- | `label` | The label, when you need markup. Overrides `label`. |
165
- | `hint` | Help text below the field. Overrides `hint`. |
166
- | `prefix` | An icon or text before the input. |
167
- | `suffix` | An icon or text after the input. |
375
+ | (default) | The main content. |
376
+ | `media` | An image or video, edge to edge at the top (or the start, when horizontal). |
377
+ | `header` | The title area, e.g. a heading and a subtitle. |
378
+ | `footer` | Actions or details at the bottom. |
168
379
 
169
380
  #### CSS parts
170
381
 
171
382
  | Part | Description |
172
383
  |---|---|
173
- | `field` | The wrapper around label, control, hint and error. |
174
- | `form-label` | The label. |
175
- | `box` | The bordered box around the input. |
176
- | `input` | The native `<input>`. |
177
- | `hint` | The hint text. |
178
- | `error` | The validation message. |
384
+ | `base` | The card. |
385
+ | `media` | The media wrapper. |
386
+ | `header` | The header wrapper. |
387
+ | `body` | The main content wrapper. |
388
+ | `footer` | The footer wrapper. |
179
389
 
180
390
  #### CSS custom properties
181
391
 
182
392
  | Property | Description |
183
393
  |---|---|
184
- | `--uf-field-bg` | Background of the box. |
185
- | `--uf-field-border-color` | Border color of the box. |
186
- | `--uf-field-radius` | Corner radius of the box. |
394
+ | `--uf-card-padding` | Padding of header, body and footer. |
395
+ | `--uf-card-bg` | Background color. |
396
+ | `--uf-card-border-color` | Border color. |
397
+ | `--uf-card-radius` | Corner radius. |
398
+ | `--uf-card-shadow` | Shadow of an elevated card. Defaults to a soft shadow in light mode and an accent glow in dark mode. |
399
+ | `--uf-card-media-width` | Width of the media in a horizontal card. Defaults to 40%. |
187
400
 
188
- ## Textarea
401
+ ## Checkbox
189
402
 
190
- A multi-line text field with a built-in label, hint and validation message.
403
+ A checkbox with its label as content.
191
404
 
192
- Tags: `<uf-textarea>`. Import: `import '@unframed/core/textarea';` (or `npx @unframed/cli add textarea` to copy the source).
405
+ Tags: `<uf-checkbox>`, `<uf-checkbox-group>`. Import: `import '@unframed/core/checkbox';`, `import '@unframed/core/checkbox-group';` (or `npx @unframed/cli add checkbox checkbox-group` to copy the source).
193
406
 
194
- ### Grows with its content
407
+ ### States
195
408
 
196
409
  ```html
197
- <uf-textarea label="Bio" resize="auto" rows="2" maxlength="280" hint="Up to 280 characters."></uf-textarea>
410
+ <uf-checkbox checked hint="One email a month.">Subscribe to the newsletter</uf-checkbox>
411
+ <uf-checkbox indeterminate>Select all</uf-checkbox>
412
+ <uf-checkbox disabled>Disabled</uf-checkbox>
198
413
  ```
199
414
 
200
- ### `<uf-textarea>` API
415
+ ### Select all
416
+
417
+ ```html
418
+ <uf-checkbox-group label="Toppings">
419
+ <uf-checkbox select-all>All toppings</uf-checkbox>
420
+ <uf-checkbox name="topping" value="cheese">Cheese</uf-checkbox>
421
+ <uf-checkbox name="topping" value="olives" checked>Olives</uf-checkbox>
422
+ <uf-checkbox name="topping" value="basil">Basil</uf-checkbox>
423
+ </uf-checkbox-group>
424
+ ```
425
+
426
+ ### Binding the indeterminate state
427
+
428
+ ```html
429
+ <uf-checkbox indeterminate>Notify me</uf-checkbox>
430
+ ```
431
+
432
+ ### `<uf-checkbox>` API
201
433
 
202
434
  #### Attributes and properties
203
435
 
204
436
  | Attribute | Property | Type | Default | Description |
205
437
  |---|---|---|---|---|
206
- | `value` | `defaultValue` | `string` | `''` | Initial value, restored on form reset. Set with the `value` attribute. |
207
- | `label` | | `string \| undefined` | | Visible label. |
208
- | `hint` | | `string \| undefined` | | Help text below the field. |
209
- | `placeholder` | | `string \| undefined` | | Placeholder text. |
210
- | `rows` | | `number` | `4` | Visible number of lines. |
211
- | `resize` | | `TextareaResize` | `'vertical'` | How the user can resize the field. `auto` grows with the content. |
212
- | `size` | | `FieldSize` | `'md'` | Size of the field. |
213
- | `readonly` | | `boolean` | `false` | Makes the field read-only. |
214
- | `autocomplete` | | `AutoFill \| undefined` | | Native `autocomplete` hint. |
215
- | `minlength` | | `number \| undefined` | | Minimum length. |
216
- | `maxlength` | | `number \| undefined` | | Maximum length. |
438
+ | `indeterminate` | | `boolean` | `false` | Shows a dash instead of a check, for "some selected". Cleared when the user clicks. |
439
+ | `select-all` | `selectAll` | `boolean` | `false` | Inside `<uf-checkbox-group>`: checks or unchecks every other checkbox in the group, and shows checked, unchecked or indeterminate to match them. |
440
+ | `hint` | | `string \| undefined` | | Help text below the label. |
441
+ | `checked` | `defaultChecked` | `boolean` | `false` | Initial state, restored on form reset. Set with the `checked` attribute. |
442
+ | `value` | | `string` | `'on'` | Value submitted with the form when checked. |
217
443
  | `name` | | `string` | `''` | Name submitted with the form. |
218
444
  | `disabled` | | `boolean` | `false` | Disables the control. |
219
445
  | `required` | | `boolean` | `false` | Makes the control required for form submission. |
@@ -222,7 +448,7 @@ Tags: `<uf-textarea>`. Import: `import '@unframed/core/textarea';` (or `npx @unf
222
448
 
223
449
  | Property | Type | Description |
224
450
  |---|---|---|
225
- | `value` | `string` | Current value. |
451
+ | `checked` | `boolean` | Whether the control is on. |
226
452
  | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
227
453
  | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
228
454
  | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
@@ -232,7 +458,7 @@ Tags: `<uf-textarea>`. Import: `import '@unframed/core/textarea';` (or `npx @unf
232
458
 
233
459
  | Method | Description |
234
460
  |---|---|
235
- | `select()` | Selects all text in the field. |
461
+ | `toggle()` | Toggles the control, as if the user clicked it. |
236
462
  | `checkValidity()` | Returns whether the value is valid, without showing an error. |
237
463
  | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
238
464
  | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
@@ -241,24 +467,24 @@ Tags: `<uf-textarea>`. Import: `import '@unframed/core/textarea';` (or `npx @unf
241
467
 
242
468
  | Event | Type | Description |
243
469
  |---|---|---|
244
- | `input` | | Fired on every keystroke. |
245
- | `change` | `Event` | Fired when the value is committed (blur). |
470
+ | `input` | | Fired when the checked state changes. |
471
+ | `change` | `Event` | Fired when the checked state changes. |
246
472
 
247
473
  #### Slots
248
474
 
249
475
  | Slot | Description |
250
476
  |---|---|
251
- | `label` | The label, when you need markup. Overrides `label`. |
252
- | `hint` | Help text below the field. Overrides `hint`. |
477
+ | (default) | The label. |
478
+ | `hint` | Help text below the label. Overrides `hint`. |
253
479
 
254
480
  #### CSS parts
255
481
 
256
482
  | Part | Description |
257
483
  |---|---|
258
- | `field` | The wrapper around label, control, hint and error. |
259
- | `form-label` | The label. |
260
- | `box` | The bordered box around the textarea. |
261
- | `textarea` | The native `<textarea>`. |
484
+ | `base` | The `<label>` wrapping control and label. |
485
+ | `control` | The box. |
486
+ | `checkmark` | The check or dash icon. |
487
+ | `label` | The label text. |
262
488
  | `hint` | The hint text. |
263
489
  | `error` | The validation message. |
264
490
 
@@ -266,102 +492,61 @@ Tags: `<uf-textarea>`. Import: `import '@unframed/core/textarea';` (or `npx @unf
266
492
 
267
493
  | Property | Description |
268
494
  |---|---|
269
- | `--uf-field-bg` | Background of the box. |
270
- | `--uf-field-border-color` | Border color of the box. |
271
- | `--uf-field-radius` | Corner radius of the box. |
272
-
273
- ## Select
274
-
275
- A dropdown built on the native `<select>`, so it gets the platform's
276
- keyboard support, screen reader support and mobile pickers for free.
277
- Write options as plain `<option>` and `<optgroup>` children.
278
-
279
- Tags: `<uf-select>`. Import: `import '@unframed/core/select';` (or `npx @unframed/cli add select` to copy the source).
280
-
281
- ### Native options
282
-
283
- Built on the native `<select>`: write plain `<option>` and `<optgroup>` children.
284
-
285
- ```html
286
- <uf-select label="Country" placeholder="Choose a country">
287
- <option value="it">Italy</option>
288
- <option value="fr">France</option>
289
- <optgroup label="Elsewhere">
290
- <option value="jp">Japan</option>
291
- <option value="us">United States</option>
292
- </optgroup>
293
- </uf-select>
294
- ```
495
+ | `--uf-checkbox-size` | Size of the box. |
496
+ | `--uf-checkbox-radius` | Corner radius of the box. |
497
+ | `--uf-checkbox-checked-bg` | Background when checked. |
498
+ | `--uf-checkbox-indeterminate-bg` | Background when indeterminate. Defaults to the checked background. |
295
499
 
296
- ### `<uf-select>` API
500
+ ### `<uf-checkbox-group>` API
297
501
 
298
502
  #### Attributes and properties
299
503
 
300
504
  | Attribute | Property | Type | Default | Description |
301
505
  |---|---|---|---|---|
302
- | `value` | `defaultValue` | `string \| undefined` | | Initially selected value, restored on form reset. Set with the `value` attribute. |
303
- | `label` | | `string \| undefined` | | Visible label. |
304
- | `hint` | | `string \| undefined` | | Help text below the field. |
305
- | `placeholder` | | `string \| undefined` | | Text shown while nothing is selected. |
306
- | `size` | | `FieldSize` | `'md'` | Size of the field. |
307
- | `autocomplete` | | `AutoFill \| undefined` | | Native `autocomplete` hint. |
308
- | `name` | | `string` | `''` | Name submitted with the form. |
309
- | `disabled` | | `boolean` | `false` | Disables the control. |
310
- | `required` | | `boolean` | `false` | Makes the control required for form submission. |
506
+ | `label` | | `string \| undefined` | | Visible group label. |
507
+ | `hint` | | `string \| undefined` | | Help text below the checkboxes. |
508
+ | `orientation` | | `'vertical' \| 'horizontal'` | `'vertical'` | Lays the checkboxes out in a column or a row. |
311
509
 
312
510
  #### Properties only
313
511
 
314
512
  | Property | Type | Description |
315
513
  |---|---|---|
316
- | `value` | `string` | The selected option's value. |
317
- | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
318
- | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
319
- | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
320
- | `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
514
+ | `value` | `string[]` | The values of the checked checkboxes (other than "select all"). |
321
515
 
322
516
  #### Methods
323
517
 
324
518
  | Method | Description |
325
519
  |---|---|
326
- | `checkValidity()` | Returns whether the value is valid, without showing an error. |
327
- | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
328
- | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
520
+ | `sync()` | Updates "select all" to match the other checkboxes. Called automatically on user changes; call it after changing `checked` on a checkbox from code. |
329
521
 
330
522
  #### Events
331
523
 
332
524
  | Event | Type | Description |
333
525
  |---|---|---|
334
- | `input` | | Fired when the selection changes. |
335
- | `change` | `Event` | Fired when the selection changes. |
526
+ | `change` | | A checkbox in the group changed (including through "select all"). |
336
527
 
337
528
  #### Slots
338
529
 
339
530
  | Slot | Description |
340
531
  |---|---|
341
- | (default) | `<option>` and `<optgroup>` elements. They are mirrored into the native select. |
342
- | `label` | The label, when you need markup. Overrides `label`. |
343
- | `hint` | Help text below the field. Overrides `hint`. |
344
- | `prefix` | An icon before the selected value. |
532
+ | (default) | `<uf-checkbox>` elements. |
533
+ | `label` | The group label, when you need markup. Overrides `label`. |
534
+ | `hint` | Help text below the checkboxes. Overrides `hint`. |
345
535
 
346
536
  #### CSS parts
347
537
 
348
538
  | Part | Description |
349
539
  |---|---|
350
- | `field` | The wrapper around label, control, hint and error. |
351
- | `form-label` | The label. |
352
- | `box` | The bordered box. |
353
- | `select` | The native `<select>`. |
354
- | `chevron` | The dropdown arrow. |
540
+ | `base` | The element with `role="group"`. |
541
+ | `form-label` | The group label. |
542
+ | `options` | The wrapper around the checkboxes. |
355
543
  | `hint` | The hint text. |
356
- | `error` | The validation message. |
357
544
 
358
545
  #### CSS custom properties
359
546
 
360
547
  | Property | Description |
361
548
  |---|---|
362
- | `--uf-field-bg` | Background of the box. |
363
- | `--uf-field-border-color` | Border color of the box. |
364
- | `--uf-field-radius` | Corner radius of the box. |
549
+ | `--uf-checkbox-group-indent` | Indent of the checkboxes under a "select all". |
365
550
 
366
551
  ## Combobox
367
552
 
@@ -462,48 +647,71 @@ Type to filter, arrow keys to move, Enter to pick.
462
647
  |---|---|
463
648
  | `--uf-combobox-max-height` | Maximum height of the list before it scrolls. |
464
649
 
465
- ## Checkbox
650
+ ## Date picker
466
651
 
467
- A checkbox with its label as content.
652
+ A date field: type a date in the page language's format, or pick one from a
653
+ calendar. The value is always `YYYY-MM-DD`, like `<input type="date">`, so
654
+ it's the same in every language and submits with the form.
468
655
 
469
- Tags: `<uf-checkbox>`, `<uf-checkbox-group>`. Import: `import '@unframed/core/checkbox';`, `import '@unframed/core/checkbox-group';` (or `npx @unframed/cli add checkbox checkbox-group` to copy the source).
656
+ Alt + Down Arrow opens the calendar; Escape closes it.
470
657
 
471
- ### States
658
+ Tags: `<uf-date-picker>`, `<uf-calendar>`. Import: `import '@unframed/core/date-picker';`, `import '@unframed/core/calendar';` (or `npx @unframed/cli add date-picker calendar` to copy the source).
659
+
660
+ ### Type or pick a date
661
+
662
+ Type a date in the page language's format, or open the calendar. The value is always `YYYY-MM-DD`.
472
663
 
473
664
  ```html
474
- <uf-checkbox checked hint="One email a month.">Subscribe to the newsletter</uf-checkbox>
475
- <uf-checkbox indeterminate>Select all</uf-checkbox>
476
- <uf-checkbox disabled>Disabled</uf-checkbox>
665
+ <uf-date-picker label="Check-in" hint="From 3 pm" name="checkin" min="2026-10-14" required></uf-date-picker>
477
666
  ```
478
667
 
479
- ### Select all
668
+ - Arrow keys move by day and week, Page Up and Page Down by month (with Shift, by year). Alt + Down Arrow opens the calendar, Escape closes it.
669
+ - The format, month names and first day of the week follow the nearest `lang` attribute: `14/10/2026` in Italian, `10/14/2026` in US English.
670
+ - Typed text that isn't a date stays in the field with an error, so the user can fix it.
671
+
672
+ ### Disabled dates
673
+
674
+ `min` and `max` limit the range; `isDateDisabled` rules out single dates, like weekends.
480
675
 
481
676
  ```html
482
- <uf-checkbox-group label="Toppings">
483
- <uf-checkbox select-all>All toppings</uf-checkbox>
484
- <uf-checkbox name="topping" value="cheese">Cheese</uf-checkbox>
485
- <uf-checkbox name="topping" value="olives" checked>Olives</uf-checkbox>
486
- <uf-checkbox name="topping" value="basil">Basil</uf-checkbox>
487
- </uf-checkbox-group>
677
+ <uf-date-picker id="delivery" label="Delivery day" hint="Weekdays only"></uf-date-picker>
678
+
679
+ <script type="module">
680
+ // A property, not an attribute: it's a function.
681
+ document.querySelector('#delivery').isDateDisabled = (date) =>
682
+ [0, 6].includes(new Date(date).getUTCDay());
683
+ </script>
488
684
  ```
489
685
 
490
- ### Binding the indeterminate state
686
+ ### Calendar on its own
687
+
688
+ `<uf-calendar>` is the grid inside the picker. Use it inline, e.g. on a booking page.
491
689
 
492
690
  ```html
493
- <uf-checkbox indeterminate>Notify me</uf-checkbox>
691
+ <uf-calendar value="2026-10-14"></uf-calendar>
692
+
693
+ <script type="module">
694
+ document.querySelector('uf-calendar').addEventListener('change', (event) => {
695
+ console.log(event.target.value); // "2026-10-21"
696
+ });
697
+ </script>
494
698
  ```
495
699
 
496
- ### `<uf-checkbox>` API
700
+ ### `<uf-date-picker>` API
497
701
 
498
702
  #### Attributes and properties
499
703
 
500
704
  | Attribute | Property | Type | Default | Description |
501
705
  |---|---|---|---|---|
502
- | `indeterminate` | | `boolean` | `false` | Shows a dash instead of a check, for "some selected". Cleared when the user clicks. |
503
- | `select-all` | `selectAll` | `boolean` | `false` | Inside `<uf-checkbox-group>`: checks or unchecks every other checkbox in the group, and shows checked, unchecked or indeterminate to match them. |
504
- | `hint` | | `string \| undefined` | | Help text below the label. |
505
- | `checked` | `defaultChecked` | `boolean` | `false` | Initial state, restored on form reset. Set with the `checked` attribute. |
506
- | `value` | | `string` | `'on'` | Value submitted with the form when checked. |
706
+ | `value` | `defaultValue` | `string` | `''` | Initial date, restored on form reset. Set with the `value` attribute, as `YYYY-MM-DD`. |
707
+ | `label` | | `string \| undefined` | | The field's label, also its accessible name. |
708
+ | `hint` | | `string \| undefined` | | Help text below the field. |
709
+ | `placeholder` | | `string \| undefined` | | Shown when empty. Defaults to the date format, e.g. dd/mm/yyyy. |
710
+ | `size` | | `FieldSize` | `'md'` | Size: `sm`, `md` or `lg`. |
711
+ | `min` | | `string \| undefined` | | The earliest allowed date, as `YYYY-MM-DD`. |
712
+ | `max` | | `string \| undefined` | | The latest allowed date, as `YYYY-MM-DD`. |
713
+ | `readonly` | | `boolean` | `false` | Lets the user select the text but not change the date. |
714
+ | `open` | | `boolean` | `false` | Whether the calendar is open. |
507
715
  | `name` | | `string` | `''` | Name submitted with the form. |
508
716
  | `disabled` | | `boolean` | `false` | Disables the control. |
509
717
  | `required` | | `boolean` | `false` | Makes the control required for form submission. |
@@ -512,7 +720,8 @@ Tags: `<uf-checkbox>`, `<uf-checkbox-group>`. Import: `import '@unframed/core/ch
512
720
 
513
721
  | Property | Type | Description |
514
722
  |---|---|---|
515
- | `checked` | `boolean` | Whether the control is on. |
723
+ | `value` | `string` | The date, as `YYYY-MM-DD`, or an empty string. |
724
+ | `isDateDisabled` | `((date: string) => boolean) \| undefined` | Rules out dates, e.g. weekends: called with each date as `YYYY-MM-DD`, returns true to disable it. |
516
725
  | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
517
726
  | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
518
727
  | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
@@ -522,7 +731,8 @@ Tags: `<uf-checkbox>`, `<uf-checkbox-group>`. Import: `import '@unframed/core/ch
522
731
 
523
732
  | Method | Description |
524
733
  |---|---|
525
- | `toggle()` | Toggles the control, as if the user clicked it. |
734
+ | `show()` | Opens the calendar. |
735
+ | `hide()` | Closes the calendar. |
526
736
  | `checkValidity()` | Returns whether the value is valid, without showing an error. |
527
737
  | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
528
738
  | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
@@ -531,24 +741,29 @@ Tags: `<uf-checkbox>`, `<uf-checkbox-group>`. Import: `import '@unframed/core/ch
531
741
 
532
742
  | Event | Type | Description |
533
743
  |---|---|---|
534
- | `input` | | Fired when the checked state changes. |
535
- | `change` | `Event` | Fired when the checked state changes. |
744
+ | `input` | `Event` | The value changed (a date was typed and committed, or picked). |
745
+ | `change` | `Event` | The value changed (a date was typed and committed, or picked). |
746
+ | `uf-show` | | The calendar opened. |
747
+ | `uf-hide` | | The calendar closed. |
536
748
 
537
749
  #### Slots
538
750
 
539
751
  | Slot | Description |
540
752
  |---|---|
541
- | (default) | The label. |
542
- | `hint` | Help text below the label. Overrides `hint`. |
753
+ | `label` | The label, when you need markup. Overrides `label`. |
754
+ | `hint` | Help text below the field. Overrides `hint`. |
543
755
 
544
756
  #### CSS parts
545
757
 
546
758
  | Part | Description |
547
759
  |---|---|
548
- | `base` | The `<label>` wrapping control and label. |
549
- | `control` | The box. |
550
- | `checkmark` | The check or dash icon. |
551
- | `label` | The label text. |
760
+ | `field` | The wrapper around label, control, hint and error. |
761
+ | `form-label` | The label. |
762
+ | `box` | The bordered box around the input. |
763
+ | `input` | The text input. |
764
+ | `toggle` | The calendar button. |
765
+ | `popup` | The floating panel around the calendar. |
766
+ | `calendar` | The `<uf-calendar>`. |
552
767
  | `hint` | The hint text. |
553
768
  | `error` | The validation message. |
554
769
 
@@ -556,522 +771,492 @@ Tags: `<uf-checkbox>`, `<uf-checkbox-group>`. Import: `import '@unframed/core/ch
556
771
 
557
772
  | Property | Description |
558
773
  |---|---|
559
- | `--uf-checkbox-size` | Size of the box. |
560
- | `--uf-checkbox-radius` | Corner radius of the box. |
561
- | `--uf-checkbox-checked-bg` | Background when checked. |
562
- | `--uf-checkbox-indeterminate-bg` | Background when indeterminate. Defaults to the checked background. |
774
+ | `--uf-field-bg` | Background of the box. |
775
+ | `--uf-field-border-color` | Border color of the box. |
776
+ | `--uf-field-radius` | Corner radius of the box. |
563
777
 
564
- ### `<uf-checkbox-group>` API
778
+ ### `<uf-calendar>` API
565
779
 
566
780
  #### Attributes and properties
567
781
 
568
782
  | Attribute | Property | Type | Default | Description |
569
783
  |---|---|---|---|---|
570
- | `label` | | `string \| undefined` | | Visible group label. |
571
- | `hint` | | `string \| undefined` | | Help text below the checkboxes. |
572
- | `orientation` | | `'vertical' \| 'horizontal'` | `'vertical'` | Lays the checkboxes out in a column or a row. |
784
+ | `value` | | `string` | `''` | The selected date, as `YYYY-MM-DD`, or an empty string. |
785
+ | `min` | | `string \| undefined` | | The earliest date that can be picked, as `YYYY-MM-DD`. |
786
+ | `max` | | `string \| undefined` | | The latest date that can be picked, as `YYYY-MM-DD`. |
787
+ | `first-day-of-week` | `firstDayOfWeek` | `number \| undefined` | | First day of the week: 0 Sunday … 6 Saturday. Defaults to the language's. |
573
788
 
574
789
  #### Properties only
575
790
 
576
791
  | Property | Type | Description |
577
792
  |---|---|---|
578
- | `value` | `string[]` | The values of the checked checkboxes (other than "select all"). |
793
+ | `isDateDisabled` | `((date: string) => boolean) \| undefined` | Rules out dates, e.g. weekends: called with each date as `YYYY-MM-DD`, returns true to disable it. |
579
794
 
580
795
  #### Methods
581
796
 
582
797
  | Method | Description |
583
798
  |---|---|
584
- | `sync()` | Updates "select all" to match the other checkboxes. Called automatically on user changes; call it after changing `checked` on a checkbox from code. |
799
+ | `focus(options: FocusOptions)` | Moves keyboard focus to the selected day, or today. |
585
800
 
586
801
  #### Events
587
802
 
588
803
  | Event | Type | Description |
589
804
  |---|---|---|
590
- | `change` | | A checkbox in the group changed (including through "select all"). |
591
-
592
- #### Slots
593
-
594
- | Slot | Description |
595
- |---|---|
596
- | (default) | `<uf-checkbox>` elements. |
597
- | `label` | The group label, when you need markup. Overrides `label`. |
598
- | `hint` | Help text below the checkboxes. Overrides `hint`. |
805
+ | `change` | `Event` | The user picked a date. Read it from `value`. |
599
806
 
600
807
  #### CSS parts
601
808
 
602
809
  | Part | Description |
603
810
  |---|---|
604
- | `base` | The element with `role="group"`. |
605
- | `form-label` | The group label. |
606
- | `options` | The wrapper around the checkboxes. |
607
- | `hint` | The hint text. |
811
+ | `base` | The calendar. |
812
+ | `header` | The month title and the previous and next buttons. |
813
+ | `title` | The month and year. |
814
+ | `nav-button` | The previous and next month buttons. |
815
+ | `grid` | The `<table>` of days. |
816
+ | `weekday` | A weekday heading. |
817
+ | `day` | Every day. |
818
+ | `selected` | The selected day. |
819
+ | `today` | Today. |
608
820
 
609
821
  #### CSS custom properties
610
822
 
611
823
  | Property | Description |
612
824
  |---|---|
613
- | `--uf-checkbox-group-indent` | Indent of the checkboxes under a "select all". |
825
+ | `--uf-calendar-day-size` | Width and height of a day. |
614
826
 
615
- ## Switch
827
+ ## Dialog
616
828
 
617
- An on/off switch with its label as content. Use it for settings that apply
618
- immediately; use a checkbox for choices submitted later with a form.
829
+ A modal dialog built on the native `<dialog>`: it renders in the top layer,
830
+ traps focus, makes the page inert, and returns focus to the opener on close.
831
+ Any element inside with `data-dialog="close"` closes it.
619
832
 
620
- Tags: `<uf-switch>`. Import: `import '@unframed/core/switch';` (or `npx @unframed/cli add switch` to copy the source).
833
+ Tags: `<uf-dialog>`. Import: `import '@unframed/core/dialog';` (or `npx @unframed/cli add dialog` to copy the source).
621
834
 
622
- ### Settings that apply immediately
835
+ ### Confirmation
836
+
837
+ Escape, the close button and any element with `data-dialog="close"` close it.
623
838
 
624
839
  ```html
625
- <uf-switch checked>Notifications</uf-switch>
840
+ <uf-button variant="danger" onclick="this.nextElementSibling.show()">Delete project…</uf-button>
841
+ <uf-dialog label="Delete project?" light-dismiss>
842
+ <p>This permanently deletes the project and its 128 issues.</p>
843
+ <uf-button slot="footer" variant="ghost" data-dialog="close">Cancel</uf-button>
844
+ <uf-button slot="footer" variant="danger">Delete</uf-button>
845
+ </uf-dialog>
626
846
  ```
627
847
 
628
- ### `<uf-switch>` API
848
+ ### `<uf-dialog>` API
629
849
 
630
850
  #### Attributes and properties
631
851
 
632
852
  | Attribute | Property | Type | Default | Description |
633
853
  |---|---|---|---|---|
634
- | `hint` | | `string \| undefined` | | Help text below the label. |
635
- | `checked` | `defaultChecked` | `boolean` | `false` | Initial state, restored on form reset. Set with the `checked` attribute. |
636
- | `value` | | `string` | `'on'` | Value submitted with the form when checked. |
637
- | `name` | | `string` | `''` | Name submitted with the form. |
638
- | `disabled` | | `boolean` | `false` | Disables the control. |
639
- | `required` | | `boolean` | `false` | Makes the control required for form submission. |
640
-
641
- #### Properties only
642
-
643
- | Property | Type | Description |
644
- |---|---|---|
645
- | `checked` | `boolean` | Whether the control is on. |
646
- | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
647
- | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
648
- | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
649
- | `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
854
+ | `open` | | `boolean` | `false` | Whether the dialog is open. |
855
+ | `label` | | `string \| undefined` | | Title of the dialog, also its accessible name. |
856
+ | `light-dismiss` | `lightDismiss` | `boolean` | `false` | Closes the dialog when the backdrop is clicked. |
857
+ | `without-header` | `withoutHeader` | `boolean` | `false` | Hides the header. Set `label` anyway, so the dialog keeps an accessible name. |
650
858
 
651
859
  #### Methods
652
860
 
653
861
  | Method | Description |
654
862
  |---|---|
655
- | `toggle()` | Toggles the control, as if the user clicked it. |
656
- | `checkValidity()` | Returns whether the value is valid, without showing an error. |
657
- | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
658
- | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
863
+ | `show()` | Opens the dialog. |
864
+ | `hide()` | Closes the dialog, without firing `uf-request-close`. |
865
+ | `requestClose(source?: DialogCloseSource)` | Asks to close, as a user action would. Listeners can cancel it. |
659
866
 
660
867
  #### Events
661
868
 
662
869
  | Event | Type | Description |
663
870
  |---|---|---|
664
- | `input` | | Fired when the state changes. |
665
- | `change` | `Event` | Fired when the state changes. |
871
+ | `uf-show` | `Event` | The dialog opened. |
872
+ | `uf-hide` | `Event` | The dialog closed. |
873
+ | `uf-request-close` | `CustomEvent<DialogRequestCloseDetail>` | The user tried to close the dialog. Call `preventDefault()` to keep it open. |
666
874
 
667
875
  #### Slots
668
876
 
669
877
  | Slot | Description |
670
878
  |---|---|
671
- | (default) | The label. |
672
- | `hint` | Help text below the label. Overrides `hint`. |
879
+ | (default) | The dialog content. |
880
+ | `label` | The title, when you need markup. Overrides `label`. |
881
+ | `header-actions` | Extra buttons next to the close button. |
882
+ | `footer` | Actions at the bottom, usually buttons. |
673
883
 
674
884
  #### CSS parts
675
885
 
676
886
  | Part | Description |
677
887
  |---|---|
678
- | `base` | The `<label>` wrapping control and label. |
679
- | `control` | The track. |
680
- | `thumb` | The moving knob. |
681
- | `label` | The label text. |
682
- | `hint` | The hint text. |
683
- | `error` | The validation message. |
888
+ | `dialog` | The native `<dialog>`. |
889
+ | `header` | The header with title and close button. |
890
+ | `title` | The title. |
891
+ | `close-button` | The close button. |
892
+ | `body` | The content area. |
893
+ | `footer` | The footer. |
684
894
 
685
895
  #### CSS custom properties
686
896
 
687
897
  | Property | Description |
688
898
  |---|---|
689
- | `--uf-switch-width` | Width of the track. |
690
- | `--uf-switch-height` | Height of the track. |
691
- | `--uf-switch-checked-bg` | Track color when on. |
692
- | `--uf-switch-radius` | Corner radius of track and thumb. Use `999px` for a pill. |
899
+ | `--uf-dialog-bg` | Background of the dialog. |
900
+ | `--uf-dialog-width` | Width of the dialog. Defaults to `32rem`. |
901
+ | `--uf-dialog-padding` | Padding of header, body and footer. |
902
+ | `--uf-dialog-radius` | Corner radius. |
903
+ | `--uf-dialog-backdrop` | Backdrop color. |
693
904
 
694
- ## Radio group
905
+ ## Dropdown menu
695
906
 
696
- A group of `<uf-radio>` options with one selected value. Arrow keys move
697
- the selection, and only the selected option is in the tab order.
907
+ A button that opens a `<uf-menu>`, following the WAI-ARIA menu button
908
+ pattern: Enter, Space or Down open it on the first item, Up on the last;
909
+ choosing an item or pressing Escape closes it and returns focus to the button.
698
910
 
699
- Tags: `<uf-radio-group>`, `<uf-radio>`. Import: `import '@unframed/core/radio-group';`, `import '@unframed/core/radio';` (or `npx @unframed/cli add radio-group radio` to copy the source).
911
+ Tags: `<uf-dropdown>`, `<uf-menu>`, `<uf-menu-item>`. Import: `import '@unframed/core/dropdown';`, `import '@unframed/core/menu';` (or `npx @unframed/cli add dropdown menu` to copy the source).
700
912
 
701
- ### Pick one
913
+ ### Menu button
702
914
 
703
- Arrow keys move the selection; only the selected radio is in the tab order.
915
+ Arrow keys move, typing a letter jumps to an item, Escape closes.
704
916
 
705
917
  ```html
706
- <uf-radio-group label="Plan" value="pro" orientation="horizontal">
707
- <uf-radio value="free">Free</uf-radio>
708
- <uf-radio value="pro">Pro</uf-radio>
709
- <uf-radio value="team">Team</uf-radio>
710
- <uf-radio value="enterprise" disabled>Enterprise</uf-radio>
711
- </uf-radio-group>
918
+ <uf-dropdown>
919
+ <uf-button slot="trigger" variant="secondary">Actions</uf-button>
920
+ <uf-menu label="Project actions">
921
+ <uf-menu-item value="edit">Edit<span slot="suffix">⌘E</span></uf-menu-item>
922
+ <uf-menu-item value="duplicate">Duplicate</uf-menu-item>
923
+ <hr />
924
+ <uf-menu-item value="pin" type="checkbox" checked>Pinned</uf-menu-item>
925
+ </uf-menu>
926
+ </uf-dropdown>
712
927
  ```
713
928
 
714
- ### `<uf-radio-group>` API
929
+ ### `<uf-dropdown>` API
715
930
 
716
931
  #### Attributes and properties
717
932
 
718
933
  | Attribute | Property | Type | Default | Description |
719
934
  |---|---|---|---|---|
720
- | `value` | `defaultValue` | `string` | `''` | Initially selected value, restored on form reset. Set with the `value` attribute. |
721
- | `label` | | `string \| undefined` | | Visible group label. |
722
- | `hint` | | `string \| undefined` | | Help text below the options. |
723
- | `orientation` | | `'vertical' \| 'horizontal'` | `'vertical'` | Lays the options out in a column or a row. |
724
- | `name` | | `string` | `''` | Name submitted with the form. |
725
- | `disabled` | | `boolean` | `false` | Disables the control. |
726
- | `required` | | `boolean` | `false` | Makes the control required for form submission. |
727
-
728
- #### Properties only
729
-
730
- | Property | Type | Description |
731
- |---|---|---|
732
- | `value` | `string` | The selected radio's value, or an empty string. |
733
- | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
734
- | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
735
- | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
736
- | `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
935
+ | `open` | | `boolean` | `false` | Whether the popover is open. |
936
+ | `placement` | | `Placement` | `'bottom-start'` | Preferred side. Flips when there is no room. |
937
+ | `distance` | | `number` | `6` | Gap between trigger and panel, in pixels. |
938
+ | `label` | | `string \| undefined` | | Accessible name of the panel. Defaults to the trigger's text. |
737
939
 
738
940
  #### Methods
739
941
 
740
942
  | Method | Description |
741
943
  |---|---|
742
- | `focus(options: FocusOptions)` | Moves focus to the selected radio, or the first enabled one. |
743
- | `checkValidity()` | Returns whether the value is valid, without showing an error. |
744
- | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
745
- | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
944
+ | `show()` | Opens the popover. |
945
+ | `hide()` | Closes the popover. |
946
+ | `toggle()` | Opens the popover if closed, closes it if open. |
746
947
 
747
948
  #### Events
748
949
 
749
950
  | Event | Type | Description |
750
951
  |---|---|---|
751
- | `input` | `Event` | Fired when the selection changes. |
752
- | `change` | `Event` | Fired when the selection changes. |
952
+ | `uf-select` | `CustomEvent<MenuSelectDetail>` | An item was chosen (bubbles up from the menu). |
953
+ | `uf-show` | `Event` | The menu opened. |
954
+ | `uf-hide` | | The menu closed. |
753
955
 
754
956
  #### Slots
755
957
 
756
958
  | Slot | Description |
757
959
  |---|---|
758
- | (default) | `<uf-radio>` elements. |
759
- | `label` | The group label, when you need markup. Overrides `label`. |
760
- | `hint` | Help text below the options. Overrides `hint`. |
960
+ | `trigger` | The button that opens the menu. |
961
+ | (default) | A `<uf-menu>`. |
761
962
 
762
963
  #### CSS parts
763
964
 
764
965
  | Part | Description |
765
966
  |---|---|
766
- | `base` | The element with `role="radiogroup"`. |
767
- | `form-label` | The group label. |
768
- | `options` | The wrapper around the radios. |
769
- | `hint` | The hint text. |
770
- | `error` | The validation message. |
967
+ | `panel` | The floating panel around the menu. |
771
968
 
772
- ### `<uf-radio>` API
969
+ #### CSS custom properties
970
+
971
+ | Property | Description |
972
+ |---|---|
973
+ | `--uf-popover-padding` | Padding of the panel. |
974
+ | `--uf-popover-width` | Width of the panel. Defaults to its content. |
975
+
976
+ ### `<uf-menu>` API
773
977
 
774
978
  #### Attributes and properties
775
979
 
776
980
  | Attribute | Property | Type | Default | Description |
777
981
  |---|---|---|---|---|
778
- | `value` | | `string` | `''` | Value the group takes when this radio is selected. |
779
- | `checked` | | `boolean` | `false` | Whether this radio is selected. Set by the group. |
780
- | `disabled` | | `boolean` | `false` | Disables this option. |
982
+ | `label` | | `string \| undefined` | | Accessible name of the menu. |
781
983
 
782
- #### Slots
984
+ #### Properties only
783
985
 
784
- | Slot | Description |
785
- |---|---|
786
- | (default) | The label. |
986
+ | Property | Type | Description |
987
+ |---|---|---|
988
+ | `items` | `UfMenuItem[]` | Read-only. Enabled items that belong to this menu (not to a nested one). |
787
989
 
788
- #### CSS parts
990
+ #### Methods
789
991
 
790
- | Part | Description |
992
+ | Method | Description |
791
993
  |---|---|
792
- | `control` | The circle. |
793
- | `label` | The label text. |
994
+ | `focusFirst()` | Focuses the first enabled item. |
995
+ | `focusLast()` | Focuses the last enabled item. |
794
996
 
795
- #### CSS custom properties
997
+ #### Events
796
998
 
797
- | Property | Description |
798
- |---|---|
799
- | `--uf-radio-size` | Size of the circle. |
800
- | `--uf-radio-checked-color` | Color of the circle when checked. |
999
+ | Event | Type | Description |
1000
+ |---|---|---|
1001
+ | `uf-select` | `CustomEvent<MenuSelectDetail>` | An item was chosen. Cancel it to keep a dropdown open. |
801
1002
 
802
- ## Tabs
803
-
804
- Tabs that switch between panels. Arrow keys move between tabs, Home and End
805
- jump to the ends, and only the selected tab is in the tab order.
806
-
807
- Tags: `<uf-tabs>`, `<uf-tab>`, `<uf-tab-panel>`. Import: `import '@unframed/core/tabs';` (or `npx @unframed/cli add tabs` to copy the source).
808
-
809
- ### Tabs and panels
1003
+ #### Slots
810
1004
 
811
- ```html
812
- <uf-tabs label="Project settings">
813
- <uf-tab panel="general">General</uf-tab>
814
- <uf-tab panel="members">Members</uf-tab>
815
- <uf-tab-panel name="general">General settings for the project.</uf-tab-panel>
816
- <uf-tab-panel name="members">Invite people and manage roles.</uf-tab-panel>
817
- </uf-tabs>
818
- ```
1005
+ | Slot | Description |
1006
+ |---|---|
1007
+ | (default) | `<uf-menu-item>` elements and `<hr>` separators. |
819
1008
 
820
- ### `<uf-tabs>` API
1009
+ ### `<uf-menu-item>` API
821
1010
 
822
1011
  #### Attributes and properties
823
1012
 
824
1013
  | Attribute | Property | Type | Default | Description |
825
1014
  |---|---|---|---|---|
826
- | `active` | | `string` | `''` | Name of the selected panel. Defaults to the first enabled tab. |
827
- | `activation` | | `'auto' \| 'manual'` | `'auto'` | `auto` selects a tab as soon as it gets focus; `manual` waits for Enter or Space. |
828
- | `orientation` | | `'horizontal' \| 'vertical'` | `'horizontal'` | Lays the tab list out horizontally or vertically. |
829
- | `label` | | `string \| undefined` | | Accessible name for the tab list. |
830
-
831
- #### Methods
832
-
833
- | Method | Description |
834
- |---|---|
835
- | `select(name: string)` | Selects the tab for the given panel name. |
836
-
837
- #### Events
838
-
839
- | Event | Type | Description |
840
- |---|---|---|
841
- | `uf-tab-change` | `CustomEvent<TabChangeDetail>` | The selected tab changed. |
1015
+ | `value` | | `string` | `''` | Identifies the item in the menu's `uf-select` event. |
1016
+ | `type` | | `'normal' \| 'checkbox'` | `'normal'` | `checkbox` items toggle `checked` when selected. |
1017
+ | `checked` | | `boolean` | `false` | Whether a checkbox item is on. |
1018
+ | `disabled` | | `boolean` | `false` | Disables the item. |
842
1019
 
843
1020
  #### Slots
844
1021
 
845
1022
  | Slot | Description |
846
1023
  |---|---|
847
- | (default) | `<uf-tab>` and `<uf-tab-panel>` elements. Tabs are moved into the tab list automatically. |
848
- | `nav` | The tab list. You don't need to set this yourself. |
1024
+ | (default) | The label. |
1025
+ | `prefix` | An icon before the label. |
1026
+ | `suffix` | Trailing content, e.g. a keyboard shortcut. |
849
1027
 
850
1028
  #### CSS parts
851
1029
 
852
1030
  | Part | Description |
853
1031
  |---|---|
854
- | `tablist` | The element with `role="tablist"`. |
855
- | `panels` | The wrapper around the panels. |
1032
+ | `checkmark` | The check shown for checked checkbox items. |
1033
+ | `label` | The label wrapper. |
856
1034
 
857
- #### CSS custom properties
1035
+ ## Icon
858
1036
 
859
- | Property | Description |
860
- |---|---|
861
- | `--uf-tabs-indicator-color` | Color of the selected tab's underline. |
1037
+ An icon from the built-in set, or one added with `registerIcons()`.
1038
+ Icons are decorative unless you give them a `label`.
862
1039
 
863
- ### `<uf-tab>` API
1040
+ Tags: `<uf-icon>`. Import: `import '@unframed/core/icon';` (or `npx @unframed/cli add icon` to copy the source).
864
1041
 
865
- #### Attributes and properties
1042
+ ### Built-in set
866
1043
 
867
- | Attribute | Property | Type | Default | Description |
868
- |---|---|---|---|---|
869
- | `panel` | | `string` | `''` | Name of the `<uf-tab-panel>` this tab shows. |
870
- | `disabled` | | `boolean` | `false` | Disables the tab. |
1044
+ Icons are decorative unless you give them a `label`. Add your own with `registerIcons()`.
871
1045
 
872
- #### Slots
1046
+ ```html
1047
+ <uf-icon name="check-circle" label="Done"></uf-icon>
1048
+ ```
873
1049
 
874
- | Slot | Description |
875
- |---|---|
876
- | (default) | The tab label. |
1050
+ ### Your own icons
877
1051
 
878
- #### CSS parts
1052
+ ```html
1053
+ <script type="module">
1054
+ import { registerIcons } from '@unframed/core/icon';
879
1055
 
880
- | Part | Description |
881
- |---|---|
882
- | `base` | The tab's inner wrapper. |
1056
+ registerIcons({
1057
+ heart: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>',
1058
+ star: '<svg viewBox="0 0 24 24" fill="currentColor">…</svg>',
1059
+ });
1060
+ </script>
883
1061
 
884
- ### `<uf-tab-panel>` API
1062
+ <uf-icon name="heart" label="Favorite"></uf-icon>
1063
+ <uf-button><uf-icon slot="prefix" name="heart"></uf-icon>Save</uf-button>
1064
+ ```
1065
+
1066
+ - Use `currentColor` for strokes and fills, so the icon takes the text color around it (set `color` to change it).
1067
+ - Keep a `viewBox` and leave out `width`/`height`: the icon is `1em` square, so it follows the font size. Change it with `--uf-icon-size`.
1068
+ - Registering a built-in name (e.g. `x`) replaces that icon everywhere, including inside components like the dialog's close button.
1069
+ - Icons already on the page update when you register their name, so registration order doesn't matter.
1070
+ - The markup is inserted as-is: only register SVG from your own code or files, never from user input.
1071
+
1072
+ ### `<uf-icon>` API
885
1073
 
886
1074
  #### Attributes and properties
887
1075
 
888
1076
  | Attribute | Property | Type | Default | Description |
889
1077
  |---|---|---|---|---|
890
- | `name` | | `string` | `''` | Name the matching tab refers to with `panel`. |
1078
+ | `name` | | `BuiltInIconName \| (string & {})` | `''` | Icon name: a built-in icon or one added with `registerIcons()`. |
1079
+ | `label` | | `string \| undefined` | | Accessible label. Without it the icon is hidden from assistive tech. |
891
1080
 
892
- #### Slots
1081
+ #### CSS parts
893
1082
 
894
- | Slot | Description |
1083
+ | Part | Description |
895
1084
  |---|---|
896
- | (default) | The panel content. |
1085
+ | `svg` | The `<svg>` element. |
897
1086
 
898
1087
  #### CSS custom properties
899
1088
 
900
1089
  | Property | Description |
901
1090
  |---|---|
902
- | `--uf-tab-panel-padding` | Padding around the content. |
1091
+ | `--uf-icon-size` | Width and height. Defaults to `1em`, so it follows the font size. |
1092
+ | `--uf-icon-stroke-width` | Stroke width of built-in icons. |
903
1093
 
904
- ## Accordion
1094
+ ## Input
905
1095
 
906
- Groups `<uf-accordion-item>`s. By default opening one item closes the
907
- others; set `multiple` to let several stay open. Up and Down arrows move
908
- between headers, Home and End jump to the first and last.
1096
+ A single-line text field with a built-in label, hint and validation message.
909
1097
 
910
- Tags: `<uf-accordion>`, `<uf-accordion-item>`. Import: `import '@unframed/core/accordion';` (or `npx @unframed/cli add accordion` to copy the source).
1098
+ Tags: `<uf-input>`. Import: `import '@unframed/core/input';` (or `npx @unframed/cli add input` to copy the source).
911
1099
 
912
- ### One open at a time
1100
+ ### With label, hint and validation
913
1101
 
914
- Add `multiple` to let several items stay open.
1102
+ Errors appear after the user edits the field or tries to submit.
915
1103
 
916
1104
  ```html
917
- <uf-accordion>
918
- <uf-accordion-item summary="What is Unframed?" open>
919
- A library of web components that work in any framework, or none.
920
- </uf-accordion-item>
921
- <uf-accordion-item summary="Can I edit the components?">…</uf-accordion-item>
922
- </uf-accordion>
1105
+ <form>
1106
+ <uf-input name="email" type="email" label="Email" hint="We never share it." required>
1107
+ <uf-icon slot="prefix" name="info"></uf-icon>
1108
+ </uf-input>
1109
+ <uf-button type="submit">Subscribe</uf-button>
1110
+ </form>
923
1111
  ```
924
1112
 
925
- ### `<uf-accordion>` API
926
-
927
- #### Attributes and properties
928
-
929
- | Attribute | Property | Type | Default | Description |
930
- |---|---|---|---|---|
931
- | `multiple` | | `boolean` | `false` | Allows several items to be open at once. |
932
-
933
- #### Slots
934
-
935
- | Slot | Description |
936
- |---|---|
937
- | (default) | `<uf-accordion-item>` elements. |
938
-
939
- #### CSS parts
940
-
941
- | Part | Description |
942
- |---|---|
943
- | `base` | The wrapper around the items. |
944
-
945
- ### `<uf-accordion-item>` API
1113
+ ### `<uf-input>` API
946
1114
 
947
1115
  #### Attributes and properties
948
1116
 
949
1117
  | Attribute | Property | Type | Default | Description |
950
1118
  |---|---|---|---|---|
951
- | `open` | | `boolean` | `false` | Whether the item is expanded. |
952
- | `summary` | | `string \| undefined` | | Header text. |
953
- | `disabled` | | `boolean` | `false` | Prevents the user from toggling the item. |
1119
+ | `type` | | `InputType` | `'text'` | Input type. |
1120
+ | `value` | `defaultValue` | `string` | `''` | Initial value, restored on form reset. Set with the `value` attribute. |
1121
+ | `label` | | `string \| undefined` | | Visible label. |
1122
+ | `hint` | | `string \| undefined` | | Help text below the field. |
1123
+ | `placeholder` | | `string \| undefined` | | Placeholder text. |
1124
+ | `size` | | `FieldSize` | `'md'` | Size of the field. |
1125
+ | `readonly` | | `boolean` | `false` | Makes the field read-only. |
1126
+ | `autocomplete` | | `AutoFill \| undefined` | | Native `autocomplete` hint. |
1127
+ | `inputmode` | | `string \| undefined` | | Native `inputmode` hint for virtual keyboards. |
1128
+ | `pattern` | | `string \| undefined` | | Regex the value must match. |
1129
+ | `min` | | `string \| undefined` | | Minimum value, for number and date types. |
1130
+ | `max` | | `string \| undefined` | | Maximum value, for number and date types. |
1131
+ | `step` | | `string \| undefined` | | Step, for number and date types. |
1132
+ | `minlength` | | `number \| undefined` | | Minimum length. |
1133
+ | `maxlength` | | `number \| undefined` | | Maximum length. |
1134
+ | `name` | | `string` | `''` | Name submitted with the form. |
1135
+ | `disabled` | | `boolean` | `false` | Disables the control. |
1136
+ | `required` | | `boolean` | `false` | Makes the control required for form submission. |
954
1137
 
955
1138
  #### Properties only
956
1139
 
957
1140
  | Property | Type | Description |
958
1141
  |---|---|---|
959
- | `header` | `HTMLElement \| null` | Read-only. The header element, for keyboard navigation between items. |
1142
+ | `value` | `string` | Current value. |
1143
+ | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
1144
+ | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
1145
+ | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
1146
+ | `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
960
1147
 
961
1148
  #### Methods
962
1149
 
963
1150
  | Method | Description |
964
1151
  |---|---|
965
- | `show()` | Expands the item. |
966
- | `hide()` | Collapses the item. |
967
- | `focus(options: FocusOptions)` | Focuses the header. |
1152
+ | `select()` | Selects all text in the field. |
1153
+ | `checkValidity()` | Returns whether the value is valid, without showing an error. |
1154
+ | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
1155
+ | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
968
1156
 
969
1157
  #### Events
970
1158
 
971
1159
  | Event | Type | Description |
972
1160
  |---|---|---|
973
- | `uf-show` | | The item opened. |
974
- | `uf-hide` | | The item closed. |
1161
+ | `input` | | Fired on every keystroke. |
1162
+ | `change` | `Event` | Fired when the value is committed (blur or Enter). |
975
1163
 
976
1164
  #### Slots
977
1165
 
978
1166
  | Slot | Description |
979
1167
  |---|---|
980
- | (default) | The content. |
981
- | `summary` | The header, when you need markup. Overrides `summary`. |
1168
+ | `label` | The label, when you need markup. Overrides `label`. |
1169
+ | `hint` | Help text below the field. Overrides `hint`. |
1170
+ | `prefix` | An icon or text before the input. |
1171
+ | `suffix` | An icon or text after the input. |
982
1172
 
983
1173
  #### CSS parts
984
1174
 
985
1175
  | Part | Description |
986
1176
  |---|---|
987
- | `base` | The native `<details>`. |
988
- | `header` | The clickable header (`<summary>`). |
989
- | `chevron` | The arrow icon. |
990
- | `content` | The content wrapper. |
1177
+ | `field` | The wrapper around label, control, hint and error. |
1178
+ | `form-label` | The label. |
1179
+ | `box` | The bordered box around the input. |
1180
+ | `input` | The native `<input>`. |
1181
+ | `hint` | The hint text. |
1182
+ | `error` | The validation message. |
991
1183
 
992
1184
  #### CSS custom properties
993
1185
 
994
1186
  | Property | Description |
995
1187
  |---|---|
996
- | `--uf-accordion-padding` | Horizontal padding of header and content. |
1188
+ | `--uf-field-bg` | Background of the box. |
1189
+ | `--uf-field-border-color` | Border color of the box. |
1190
+ | `--uf-field-radius` | Corner radius of the box. |
997
1191
 
998
- ## Dialog
1192
+ ## Pagination
999
1193
 
1000
- A modal dialog built on the native `<dialog>`: it renders in the top layer,
1001
- traps focus, makes the page inert, and returns focus to the opener on close.
1002
- Any element inside with `data-dialog="close"` closes it.
1194
+ Navigation between the pages of a list or table. Set `pages` and `page`; the
1195
+ user changes `page`, and `uf-page-change` tells you which page to show.
1003
1196
 
1004
- Tags: `<uf-dialog>`. Import: `import '@unframed/core/dialog';` (or `npx @unframed/cli add dialog` to copy the source).
1197
+ It's a navigation landmark: when a page has more than one, give each a
1198
+ different `label`.
1005
1199
 
1006
- ### Confirmation
1200
+ Tags: `<uf-pagination>`. Import: `import '@unframed/core/pagination';` (or `npx @unframed/cli add pagination` to copy the source).
1007
1201
 
1008
- Escape, the close button and any element with `data-dialog="close"` close it.
1202
+ ### Pages
1203
+
1204
+ Long ranges collapse around the current page; the number of buttons stays the same from page to page.
1009
1205
 
1010
1206
  ```html
1011
- <uf-button variant="danger" onclick="this.nextElementSibling.show()">Delete project…</uf-button>
1012
- <uf-dialog label="Delete project?" light-dismiss>
1013
- <p>This permanently deletes the project and its 128 issues.</p>
1014
- <uf-button slot="footer" variant="ghost" data-dialog="close">Cancel</uf-button>
1015
- <uf-button slot="footer" variant="danger">Delete</uf-button>
1016
- </uf-dialog>
1207
+ <uf-pagination pages="20" page="6"></uf-pagination>
1208
+
1209
+ <script type="module">
1210
+ document.querySelector('uf-pagination').addEventListener('uf-page-change', (event) => {
1211
+ loadPage(event.detail.page);
1212
+ });
1213
+ </script>
1017
1214
  ```
1018
1215
 
1019
- ### `<uf-dialog>` API
1216
+ ### Siblings and size
1217
+
1218
+ ```html
1219
+ <uf-pagination pages="30" page="15" siblings="2"></uf-pagination>
1220
+ <uf-pagination pages="30" page="15" size="sm"></uf-pagination>
1221
+ ```
1222
+
1223
+ - Each pagination is a navigation landmark: when a page has more than one, give each a different `label`.
1224
+
1225
+ ### `<uf-pagination>` API
1020
1226
 
1021
1227
  #### Attributes and properties
1022
1228
 
1023
1229
  | Attribute | Property | Type | Default | Description |
1024
1230
  |---|---|---|---|---|
1025
- | `open` | | `boolean` | `false` | Whether the dialog is open. |
1026
- | `label` | | `string \| undefined` | | Title of the dialog, also its accessible name. |
1027
- | `light-dismiss` | `lightDismiss` | `boolean` | `false` | Closes the dialog when the backdrop is clicked. |
1028
- | `without-header` | `withoutHeader` | `boolean` | `false` | Hides the header. Set `label` anyway, so the dialog keeps an accessible name. |
1029
-
1030
- #### Methods
1031
-
1032
- | Method | Description |
1033
- |---|---|
1034
- | `show()` | Opens the dialog. |
1035
- | `hide()` | Closes the dialog, without firing `uf-request-close`. |
1036
- | `requestClose(source?: DialogCloseSource)` | Asks to close, as a user action would. Listeners can cancel it. |
1231
+ | `page` | | `number` | `1` | The current page, from 1. |
1232
+ | `pages` | | `number` | `1` | How many pages there are. |
1233
+ | `siblings` | | `number` | `1` | How many pages to show on each side of the current one. |
1234
+ | `label` | | `string \| undefined` | | Accessible name of the navigation, e.g. "Search results pages". Defaults to "Pagination", or its translation. |
1235
+ | `size` | | `PaginationSize` | `'md'` | Size: `sm` or `md`. |
1037
1236
 
1038
1237
  #### Events
1039
1238
 
1040
1239
  | Event | Type | Description |
1041
1240
  |---|---|---|
1042
- | `uf-show` | `Event` | The dialog opened. |
1043
- | `uf-hide` | `Event` | The dialog closed. |
1044
- | `uf-request-close` | `CustomEvent<DialogRequestCloseDetail>` | The user tried to close the dialog. Call `preventDefault()` to keep it open. |
1045
-
1046
- #### Slots
1047
-
1048
- | Slot | Description |
1049
- |---|---|
1050
- | (default) | The dialog content. |
1051
- | `label` | The title, when you need markup. Overrides `label`. |
1052
- | `header-actions` | Extra buttons next to the close button. |
1053
- | `footer` | Actions at the bottom, usually buttons. |
1241
+ | `uf-page-change` | `CustomEvent<PageChangeDetail>` | The user chose another page. |
1054
1242
 
1055
1243
  #### CSS parts
1056
1244
 
1057
1245
  | Part | Description |
1058
1246
  |---|---|
1059
- | `dialog` | The native `<dialog>`. |
1060
- | `header` | The header with title and close button. |
1061
- | `title` | The title. |
1062
- | `close-button` | The close button. |
1063
- | `body` | The content area. |
1064
- | `footer` | The footer. |
1247
+ | `base` | The `<nav>`. |
1248
+ | `list` | The list of buttons. |
1249
+ | `button` | Every button: pages, previous and next. |
1250
+ | `current` | The current page's button. |
1251
+ | `previous` | The previous button. |
1252
+ | `next` | The next button. |
1253
+ | `ellipsis` | The "…" between pages. |
1065
1254
 
1066
1255
  #### CSS custom properties
1067
1256
 
1068
1257
  | Property | Description |
1069
1258
  |---|---|
1070
- | `--uf-dialog-bg` | Background of the dialog. |
1071
- | `--uf-dialog-width` | Width of the dialog. Defaults to `32rem`. |
1072
- | `--uf-dialog-padding` | Padding of header, body and footer. |
1073
- | `--uf-dialog-radius` | Corner radius. |
1074
- | `--uf-dialog-backdrop` | Backdrop color. |
1259
+ | `--uf-pagination-gap` | Space between the buttons. |
1075
1260
 
1076
1261
  ## Popover
1077
1262
 
@@ -1137,694 +1322,687 @@ Tags: `<uf-popover>`. Import: `import '@unframed/core/popover';` (or `npx @unfra
1137
1322
  | `--uf-popover-padding` | Padding of the panel. |
1138
1323
  | `--uf-popover-width` | Width of the panel. Defaults to its content. |
1139
1324
 
1140
- ## Dropdown menu
1325
+ ## Radio group
1141
1326
 
1142
- A button that opens a `<uf-menu>`, following the WAI-ARIA menu button
1143
- pattern: Enter, Space or Down open it on the first item, Up on the last;
1144
- choosing an item or pressing Escape closes it and returns focus to the button.
1327
+ A group of `<uf-radio>` options with one selected value. Arrow keys move
1328
+ the selection, and only the selected option is in the tab order.
1145
1329
 
1146
- Tags: `<uf-dropdown>`, `<uf-menu>`, `<uf-menu-item>`. Import: `import '@unframed/core/dropdown';`, `import '@unframed/core/menu';` (or `npx @unframed/cli add dropdown menu` to copy the source).
1330
+ Tags: `<uf-radio-group>`, `<uf-radio>`. Import: `import '@unframed/core/radio-group';`, `import '@unframed/core/radio';` (or `npx @unframed/cli add radio-group radio` to copy the source).
1147
1331
 
1148
- ### Menu button
1332
+ ### Pick one
1149
1333
 
1150
- Arrow keys move, typing a letter jumps to an item, Escape closes.
1334
+ Arrow keys move the selection; only the selected radio is in the tab order.
1151
1335
 
1152
1336
  ```html
1153
- <uf-dropdown>
1154
- <uf-button slot="trigger" variant="secondary">Actions</uf-button>
1155
- <uf-menu label="Project actions">
1156
- <uf-menu-item value="edit">Edit<span slot="suffix">⌘E</span></uf-menu-item>
1157
- <uf-menu-item value="duplicate">Duplicate</uf-menu-item>
1158
- <hr />
1159
- <uf-menu-item value="pin" type="checkbox" checked>Pinned</uf-menu-item>
1160
- </uf-menu>
1161
- </uf-dropdown>
1337
+ <uf-radio-group label="Plan" value="pro" orientation="horizontal">
1338
+ <uf-radio value="free">Free</uf-radio>
1339
+ <uf-radio value="pro">Pro</uf-radio>
1340
+ <uf-radio value="team">Team</uf-radio>
1341
+ <uf-radio value="enterprise" disabled>Enterprise</uf-radio>
1342
+ </uf-radio-group>
1162
1343
  ```
1163
1344
 
1164
- ### `<uf-dropdown>` API
1345
+ ### `<uf-radio-group>` API
1165
1346
 
1166
1347
  #### Attributes and properties
1167
1348
 
1168
1349
  | Attribute | Property | Type | Default | Description |
1169
1350
  |---|---|---|---|---|
1170
- | `open` | | `boolean` | `false` | Whether the popover is open. |
1171
- | `placement` | | `Placement` | `'bottom-start'` | Preferred side. Flips when there is no room. |
1172
- | `distance` | | `number` | `6` | Gap between trigger and panel, in pixels. |
1173
- | `label` | | `string \| undefined` | | Accessible name of the panel. Defaults to the trigger's text. |
1351
+ | `value` | `defaultValue` | `string` | `''` | Initially selected value, restored on form reset. Set with the `value` attribute. |
1352
+ | `label` | | `string \| undefined` | | Visible group label. |
1353
+ | `hint` | | `string \| undefined` | | Help text below the options. |
1354
+ | `orientation` | | `'vertical' \| 'horizontal'` | `'vertical'` | Lays the options out in a column or a row. |
1355
+ | `name` | | `string` | `''` | Name submitted with the form. |
1356
+ | `disabled` | | `boolean` | `false` | Disables the control. |
1357
+ | `required` | | `boolean` | `false` | Makes the control required for form submission. |
1358
+
1359
+ #### Properties only
1360
+
1361
+ | Property | Type | Description |
1362
+ |---|---|---|
1363
+ | `value` | `string` | The selected radio's value, or an empty string. |
1364
+ | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
1365
+ | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
1366
+ | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
1367
+ | `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
1174
1368
 
1175
1369
  #### Methods
1176
1370
 
1177
1371
  | Method | Description |
1178
1372
  |---|---|
1179
- | `show()` | Opens the popover. |
1180
- | `hide()` | Closes the popover. |
1181
- | `toggle()` | Opens the popover if closed, closes it if open. |
1373
+ | `focus(options: FocusOptions)` | Moves focus to the selected radio, or the first enabled one. |
1374
+ | `checkValidity()` | Returns whether the value is valid, without showing an error. |
1375
+ | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
1376
+ | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
1182
1377
 
1183
1378
  #### Events
1184
1379
 
1185
1380
  | Event | Type | Description |
1186
1381
  |---|---|---|
1187
- | `uf-select` | `CustomEvent<MenuSelectDetail>` | An item was chosen (bubbles up from the menu). |
1188
- | `uf-show` | `Event` | The menu opened. |
1189
- | `uf-hide` | | The menu closed. |
1382
+ | `input` | `Event` | Fired when the selection changes. |
1383
+ | `change` | `Event` | Fired when the selection changes. |
1190
1384
 
1191
1385
  #### Slots
1192
1386
 
1193
1387
  | Slot | Description |
1194
1388
  |---|---|
1195
- | `trigger` | The button that opens the menu. |
1196
- | (default) | A `<uf-menu>`. |
1389
+ | (default) | `<uf-radio>` elements. |
1390
+ | `label` | The group label, when you need markup. Overrides `label`. |
1391
+ | `hint` | Help text below the options. Overrides `hint`. |
1197
1392
 
1198
1393
  #### CSS parts
1199
1394
 
1200
1395
  | Part | Description |
1201
1396
  |---|---|
1202
- | `panel` | The floating panel around the menu. |
1397
+ | `base` | The element with `role="radiogroup"`. |
1398
+ | `form-label` | The group label. |
1399
+ | `options` | The wrapper around the radios. |
1400
+ | `hint` | The hint text. |
1401
+ | `error` | The validation message. |
1402
+
1403
+ ### `<uf-radio>` API
1404
+
1405
+ #### Attributes and properties
1406
+
1407
+ | Attribute | Property | Type | Default | Description |
1408
+ |---|---|---|---|---|
1409
+ | `value` | | `string` | `''` | Value the group takes when this radio is selected. |
1410
+ | `checked` | | `boolean` | `false` | Whether this radio is selected. Set by the group. |
1411
+ | `disabled` | | `boolean` | `false` | Disables this option. |
1412
+
1413
+ #### Slots
1414
+
1415
+ | Slot | Description |
1416
+ |---|---|
1417
+ | (default) | The label. |
1418
+
1419
+ #### CSS parts
1420
+
1421
+ | Part | Description |
1422
+ |---|---|
1423
+ | `control` | The circle. |
1424
+ | `label` | The label text. |
1203
1425
 
1204
1426
  #### CSS custom properties
1205
1427
 
1206
1428
  | Property | Description |
1207
1429
  |---|---|
1208
- | `--uf-popover-padding` | Padding of the panel. |
1209
- | `--uf-popover-width` | Width of the panel. Defaults to its content. |
1430
+ | `--uf-radio-size` | Size of the circle. |
1431
+ | `--uf-radio-checked-color` | Color of the circle when checked. |
1210
1432
 
1211
- ### `<uf-menu>` API
1433
+ ## Select
1434
+
1435
+ A dropdown built on the native `<select>`, so it gets the platform's
1436
+ keyboard support, screen reader support and mobile pickers for free.
1437
+ Write options as plain `<option>` and `<optgroup>` children.
1438
+
1439
+ Tags: `<uf-select>`. Import: `import '@unframed/core/select';` (or `npx @unframed/cli add select` to copy the source).
1440
+
1441
+ ### Native options
1442
+
1443
+ Built on the native `<select>`: write plain `<option>` and `<optgroup>` children.
1444
+
1445
+ ```html
1446
+ <uf-select label="Country" placeholder="Choose a country">
1447
+ <option value="it">Italy</option>
1448
+ <option value="fr">France</option>
1449
+ <optgroup label="Elsewhere">
1450
+ <option value="jp">Japan</option>
1451
+ <option value="us">United States</option>
1452
+ </optgroup>
1453
+ </uf-select>
1454
+ ```
1455
+
1456
+ ### `<uf-select>` API
1212
1457
 
1213
1458
  #### Attributes and properties
1214
1459
 
1215
1460
  | Attribute | Property | Type | Default | Description |
1216
1461
  |---|---|---|---|---|
1217
- | `label` | | `string \| undefined` | | Accessible name of the menu. |
1462
+ | `value` | `defaultValue` | `string \| undefined` | | Initially selected value, restored on form reset. Set with the `value` attribute. |
1463
+ | `label` | | `string \| undefined` | | Visible label. |
1464
+ | `hint` | | `string \| undefined` | | Help text below the field. |
1465
+ | `placeholder` | | `string \| undefined` | | Text shown while nothing is selected. |
1466
+ | `size` | | `FieldSize` | `'md'` | Size of the field. |
1467
+ | `autocomplete` | | `AutoFill \| undefined` | | Native `autocomplete` hint. |
1468
+ | `name` | | `string` | `''` | Name submitted with the form. |
1469
+ | `disabled` | | `boolean` | `false` | Disables the control. |
1470
+ | `required` | | `boolean` | `false` | Makes the control required for form submission. |
1218
1471
 
1219
1472
  #### Properties only
1220
1473
 
1221
1474
  | Property | Type | Description |
1222
1475
  |---|---|---|
1223
- | `items` | `UfMenuItem[]` | Read-only. Enabled items that belong to this menu (not to a nested one). |
1476
+ | `value` | `string` | The selected option's value. |
1477
+ | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
1478
+ | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
1479
+ | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
1480
+ | `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
1224
1481
 
1225
1482
  #### Methods
1226
1483
 
1227
1484
  | Method | Description |
1228
1485
  |---|---|
1229
- | `focusFirst()` | Focuses the first enabled item. |
1230
- | `focusLast()` | Focuses the last enabled item. |
1486
+ | `checkValidity()` | Returns whether the value is valid, without showing an error. |
1487
+ | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
1488
+ | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
1231
1489
 
1232
1490
  #### Events
1233
1491
 
1234
1492
  | Event | Type | Description |
1235
1493
  |---|---|---|
1236
- | `uf-select` | `CustomEvent<MenuSelectDetail>` | An item was chosen. Cancel it to keep a dropdown open. |
1494
+ | `input` | | Fired when the selection changes. |
1495
+ | `change` | `Event` | Fired when the selection changes. |
1237
1496
 
1238
1497
  #### Slots
1239
1498
 
1240
1499
  | Slot | Description |
1241
1500
  |---|---|
1242
- | (default) | `<uf-menu-item>` elements and `<hr>` separators. |
1243
-
1244
- ### `<uf-menu-item>` API
1245
-
1246
- #### Attributes and properties
1247
-
1248
- | Attribute | Property | Type | Default | Description |
1249
- |---|---|---|---|---|
1250
- | `value` | | `string` | `''` | Identifies the item in the menu's `uf-select` event. |
1251
- | `type` | | `'normal' \| 'checkbox'` | `'normal'` | `checkbox` items toggle `checked` when selected. |
1252
- | `checked` | | `boolean` | `false` | Whether a checkbox item is on. |
1253
- | `disabled` | | `boolean` | `false` | Disables the item. |
1501
+ | (default) | `<option>` and `<optgroup>` elements. They are mirrored into the native select. |
1502
+ | `label` | The label, when you need markup. Overrides `label`. |
1503
+ | `hint` | Help text below the field. Overrides `hint`. |
1504
+ | `prefix` | An icon before the selected value. |
1254
1505
 
1255
- #### Slots
1506
+ #### CSS parts
1256
1507
 
1257
- | Slot | Description |
1508
+ | Part | Description |
1258
1509
  |---|---|
1259
- | (default) | The label. |
1260
- | `prefix` | An icon before the label. |
1261
- | `suffix` | Trailing content, e.g. a keyboard shortcut. |
1510
+ | `field` | The wrapper around label, control, hint and error. |
1511
+ | `form-label` | The label. |
1512
+ | `box` | The bordered box. |
1513
+ | `select` | The native `<select>`. |
1514
+ | `chevron` | The dropdown arrow. |
1515
+ | `hint` | The hint text. |
1516
+ | `error` | The validation message. |
1262
1517
 
1263
- #### CSS parts
1518
+ #### CSS custom properties
1264
1519
 
1265
- | Part | Description |
1520
+ | Property | Description |
1266
1521
  |---|---|
1267
- | `checkmark` | The check shown for checked checkbox items. |
1268
- | `label` | The label wrapper. |
1522
+ | `--uf-field-bg` | Background of the box. |
1523
+ | `--uf-field-border-color` | Border color of the box. |
1524
+ | `--uf-field-radius` | Corner radius of the box. |
1269
1525
 
1270
- ## Tooltip
1526
+ ## Switch
1271
1527
 
1272
- A short label that appears on hover and keyboard focus. Wrap the element it
1273
- describes. The text is also set as the trigger's `aria-description` (unless it
1274
- repeats the trigger's own label), so screen reader users get it too. Don't put
1275
- interactive content in a tooltip.
1528
+ An on/off switch with its label as content. Use it for settings that apply
1529
+ immediately; use a checkbox for choices submitted later with a form.
1276
1530
 
1277
- Tags: `<uf-tooltip>`. Import: `import '@unframed/core/tooltip';` (or `npx @unframed/cli add tooltip` to copy the source).
1531
+ Tags: `<uf-switch>`. Import: `import '@unframed/core/switch';` (or `npx @unframed/cli add switch` to copy the source).
1278
1532
 
1279
- ### On hover and focus
1533
+ ### Settings that apply immediately
1280
1534
 
1281
1535
  ```html
1282
- <uf-tooltip content="Saves without publishing">
1283
- <uf-button variant="outline">Save draft</uf-button>
1284
- </uf-tooltip>
1536
+ <uf-switch checked>Notifications</uf-switch>
1285
1537
  ```
1286
1538
 
1287
- ### `<uf-tooltip>` API
1539
+ ### `<uf-switch>` API
1288
1540
 
1289
1541
  #### Attributes and properties
1290
1542
 
1291
1543
  | Attribute | Property | Type | Default | Description |
1292
1544
  |---|---|---|---|---|
1293
- | `content` | | `string` | `''` | The tooltip text. |
1294
- | `placement` | | `Placement` | `'top'` | Preferred side. Flips when there is no room. |
1295
- | `disabled` | | `boolean` | `false` | Turns the tooltip off. |
1296
- | `delay` | | `number` | `300` | Milliseconds to wait on hover before showing. Focus shows it immediately. |
1297
- | `open` | | `boolean` | `false` | Whether the tooltip is showing. |
1545
+ | `hint` | | `string \| undefined` | | Help text below the label. |
1546
+ | `checked` | `defaultChecked` | `boolean` | `false` | Initial state, restored on form reset. Set with the `checked` attribute. |
1547
+ | `value` | | `string` | `'on'` | Value submitted with the form when checked. |
1548
+ | `name` | | `string` | `''` | Name submitted with the form. |
1549
+ | `disabled` | | `boolean` | `false` | Disables the control. |
1550
+ | `required` | | `boolean` | `false` | Makes the control required for form submission. |
1551
+
1552
+ #### Properties only
1553
+
1554
+ | Property | Type | Description |
1555
+ |---|---|---|
1556
+ | `checked` | `boolean` | Whether the control is on. |
1557
+ | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
1558
+ | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
1559
+ | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
1560
+ | `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
1298
1561
 
1299
1562
  #### Methods
1300
1563
 
1301
1564
  | Method | Description |
1302
1565
  |---|---|
1303
- | `show()` | Shows the tooltip, unless it's disabled. |
1304
- | `hide()` | Hides the tooltip. |
1566
+ | `toggle()` | Toggles the control, as if the user clicked it. |
1567
+ | `checkValidity()` | Returns whether the value is valid, without showing an error. |
1568
+ | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
1569
+ | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
1570
+
1571
+ #### Events
1572
+
1573
+ | Event | Type | Description |
1574
+ |---|---|---|
1575
+ | `input` | | Fired when the state changes. |
1576
+ | `change` | `Event` | Fired when the state changes. |
1305
1577
 
1306
1578
  #### Slots
1307
1579
 
1308
1580
  | Slot | Description |
1309
1581
  |---|---|
1310
- | (default) | The element the tooltip describes. |
1582
+ | (default) | The label. |
1583
+ | `hint` | Help text below the label. Overrides `hint`. |
1311
1584
 
1312
1585
  #### CSS parts
1313
1586
 
1314
1587
  | Part | Description |
1315
1588
  |---|---|
1316
- | `body` | The tooltip bubble. |
1589
+ | `base` | The `<label>` wrapping control and label. |
1590
+ | `control` | The track. |
1591
+ | `thumb` | The moving knob. |
1592
+ | `label` | The label text. |
1593
+ | `hint` | The hint text. |
1594
+ | `error` | The validation message. |
1317
1595
 
1318
1596
  #### CSS custom properties
1319
1597
 
1320
1598
  | Property | Description |
1321
1599
  |---|---|
1322
- | `--uf-tooltip-bg` | Background color. |
1323
- | `--uf-tooltip-color` | Text color. |
1324
- | `--uf-tooltip-max-width` | Maximum width. |
1600
+ | `--uf-switch-width` | Width of the track. |
1601
+ | `--uf-switch-height` | Height of the track. |
1602
+ | `--uf-switch-checked-bg` | Track color when on. |
1603
+ | `--uf-switch-radius` | Corner radius of track and thumb. Use `999px` for a pill. |
1325
1604
 
1326
- ## Toast
1605
+ ## Table
1327
1606
 
1328
- The region that shows toasts. You rarely need to add it yourself: `toast()`
1329
- creates one on first use. Add it to choose a placement, or to hold
1330
- toasts in a specific place in the DOM.
1607
+ A table of data, from `columns` and `rows`. Users can sort by the columns
1608
+ marked `sortable`. Rendered as a native `<table>`, so assistive tech reads
1609
+ headers and cells as usual.
1331
1610
 
1332
- Tags: `<uf-toaster>`. Import: `import '@unframed/core/toast';` (or `npx @unframed/cli add toast` to copy the source).
1611
+ Set `columns` and `rows` as properties, or as JSON attributes in plain HTML.
1612
+ The table sorts `rows` itself; with `manual-sort` it only shows the order
1613
+ and tells you, so you can sort on the server. Combine it with
1614
+ `<uf-pagination>` for long lists.
1333
1615
 
1334
- ### Variants
1616
+ Tags: `<uf-table>`. Import: `import '@unframed/core/table';` (or `npx @unframed/cli add table` to copy the source).
1335
1617
 
1336
- Call `toast()` from anywhere; the toaster is created on first use.
1618
+ ### Columns, rows and sorting
1619
+
1620
+ Describe the columns and pass the rows. Columns marked `sortable` sort on click.
1621
+
1622
+ ```html
1623
+ <uf-table
1624
+ label="Team"
1625
+ columns='[{"key": "name", "label": "Name", "sortable": true},
1626
+ {"key": "role", "label": "Role"},
1627
+ {"key": "commits", "label": "Commits", "sortable": true, "align": "end"}]'
1628
+ rows='[{"name": "John Smith", "role": "Product designer", "commits": 412},
1629
+ {"name": "Jane Doe", "role": "Engineer", "commits": 1290}]'
1630
+ ></uf-table>
1631
+ ```
1632
+
1633
+ - In plain HTML, `columns` and `rows` can be JSON attributes. From JavaScript, set them as properties.
1634
+ - Give the table a `label`: it names the table for screen readers.
1635
+
1636
+ ### Formatting, and pages
1637
+
1638
+ `format` turns a value into text or a DOM node, like a badge. Sorting still uses the raw values.
1337
1639
 
1338
1640
  ```html
1641
+ <uf-table id="invoices" label="Invoices" row-key="id"></uf-table>
1642
+ <uf-pagination id="pages" label="Invoice pages"></uf-pagination>
1643
+
1339
1644
  <script type="module">
1340
- import { toast } from '@unframed/core/toast';
1341
- toast('Changes published.', { variant: 'success' });
1645
+ const table = document.querySelector('#invoices');
1646
+ const pages = document.querySelector('#pages');
1647
+ const pageSize = 8;
1648
+
1649
+ table.columns = [
1650
+ { key: 'customer', label: 'Customer', sortable: true },
1651
+ { key: 'amount', label: 'Amount', sortable: true, align: 'end',
1652
+ format: (value) => euro.format(value) },
1653
+ ];
1654
+ pages.pages = Math.ceil(invoices.length / pageSize);
1655
+
1656
+ const show = (page) => (table.rows = invoices.slice((page - 1) * pageSize, page * pageSize));
1657
+ pages.addEventListener('uf-page-change', (event) => show(event.detail.page));
1658
+ show(1);
1342
1659
  </script>
1343
1660
  ```
1344
1661
 
1345
- ### `<uf-toaster>` API
1662
+ - To sort on the server, add `manual-sort`: the table shows the sort and fires `uf-sort`, and you load the rows in that order.
1663
+ - Set `--uf-table-max-height` to scroll long tables under a sticky header.
1664
+
1665
+ ### `<uf-table>` API
1346
1666
 
1347
1667
  #### Attributes and properties
1348
1668
 
1349
1669
  | Attribute | Property | Type | Default | Description |
1350
1670
  |---|---|---|---|---|
1351
- | `placement` | | `ToasterPlacement` | `'bottom-end'` | Corner or edge of the viewport where toasts appear. |
1352
- | `label` | | `string \| undefined` | | Accessible name of the notification region. Defaults to "Notifications", or its translation. |
1671
+ | `columns` | | `TableColumn[]` | `[]` | The columns, in order. As an attribute, JSON: `[{"key": "name", "label": "Name"}]`. |
1672
+ | `rows` | | `TableRow[]` | `[]` | The data, one object per row. As an attribute, JSON: `[{"name": "John"}]`. |
1673
+ | `label` | | `string \| undefined` | | Accessible name of the table, e.g. "Invoices". |
1674
+ | `sort-key` | `sortKey` | `string \| undefined` | | Key of the column the rows are sorted by. |
1675
+ | `sort-direction` | `sortDirection` | `SortDirection` | `'ascending'` | Sort order: `ascending` or `descending`. |
1676
+ | `manual-sort` | `manualSort` | `boolean` | `false` | Doesn't sort the rows: only shows the sort and fires `uf-sort`, for sorting on the server. |
1677
+ | `row-key` | `rowKey` | `string \| undefined` | | Row property that identifies each row, so rows keep their DOM when the data changes. Defaults to the index. |
1678
+ | `striped` | | `boolean` | `false` | Shades every other row. |
1679
+ | `density` | | `TableDensity` | `'comfortable'` | Row spacing: `comfortable` or `compact`. |
1353
1680
 
1354
- #### Methods
1681
+ #### Events
1355
1682
 
1356
- | Method | Description |
1683
+ | Event | Type | Description |
1684
+ |---|---|---|
1685
+ | `uf-sort` | `CustomEvent<TableSortDetail>` | The user sorted by a column. |
1686
+
1687
+ #### Slots
1688
+
1689
+ | Slot | Description |
1357
1690
  |---|---|
1358
- | `add(message: string, options?: ToastOptions)` | Shows a toast in this region. Prefer the `toast()` function. |
1359
- | `dismiss(id: number)` | Hides a toast by id. |
1691
+ | `empty` | Shown when there are no rows. Defaults to "No data", or its translation. |
1360
1692
 
1361
1693
  #### CSS parts
1362
1694
 
1363
1695
  | Part | Description |
1364
1696
  |---|---|
1365
- | `region` | The list holding the toasts. |
1366
- | `toast` | Each toast. |
1367
- | `title` | A toast's title. |
1368
- | `message` | A toast's message. |
1369
- | `close-button` | A toast's dismiss button. |
1697
+ | `base` | The scroll container around the table. |
1698
+ | `table` | The `<table>`. |
1699
+ | `header-cell` | Every header cell (`<th>`). |
1700
+ | `sort-button` | The button in a sortable header. |
1701
+ | `row` | Every body row. |
1702
+ | `cell` | Every body cell. |
1703
+ | `empty` | The cell shown when there are no rows. |
1370
1704
 
1371
1705
  #### CSS custom properties
1372
1706
 
1373
1707
  | Property | Description |
1374
1708
  |---|---|
1375
- | `--uf-toast-width` | Width of each toast. |
1376
- | `--uf-toaster-offset` | Distance from the viewport edges. |
1377
-
1378
- ## Icon
1709
+ | `--uf-table-max-height` | Height after which the body scrolls under a sticky header. |
1710
+ | `--uf-table-border-color` | Border color between rows. |
1711
+ | `--uf-table-header-bg` | Background of the header row. |
1712
+ | `--uf-table-stripe-bg` | Background of every other row, with `striped`. |
1713
+ | `--uf-table-hover-bg` | Background of the row under the pointer. |
1379
1714
 
1380
- An icon from the built-in set, or one added with `registerIcons()`.
1381
- Icons are decorative unless you give them a `label`.
1715
+ ## Tabs
1382
1716
 
1383
- Tags: `<uf-icon>`. Import: `import '@unframed/core/icon';` (or `npx @unframed/cli add icon` to copy the source).
1717
+ Tabs that switch between panels. Arrow keys move between tabs, Home and End
1718
+ jump to the ends, and only the selected tab is in the tab order.
1384
1719
 
1385
- ### Built-in set
1720
+ Tags: `<uf-tabs>`, `<uf-tab>`, `<uf-tab-panel>`. Import: `import '@unframed/core/tabs';` (or `npx @unframed/cli add tabs` to copy the source).
1386
1721
 
1387
- Icons are decorative unless you give them a `label`. Add your own with `registerIcons()`.
1722
+ ### Tabs and panels
1388
1723
 
1389
1724
  ```html
1390
- <uf-icon name="check-circle" label="Done"></uf-icon>
1725
+ <uf-tabs label="Project settings">
1726
+ <uf-tab panel="general">General</uf-tab>
1727
+ <uf-tab panel="members">Members</uf-tab>
1728
+ <uf-tab-panel name="general">General settings for the project.</uf-tab-panel>
1729
+ <uf-tab-panel name="members">Invite people and manage roles.</uf-tab-panel>
1730
+ </uf-tabs>
1391
1731
  ```
1392
1732
 
1393
- ### Your own icons
1733
+ ### `<uf-tabs>` API
1394
1734
 
1395
- ```html
1396
- <script type="module">
1397
- import { registerIcons } from '@unframed/core/icon';
1735
+ #### Attributes and properties
1398
1736
 
1399
- registerIcons({
1400
- heart: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>',
1401
- star: '<svg viewBox="0 0 24 24" fill="currentColor">…</svg>',
1402
- });
1403
- </script>
1737
+ | Attribute | Property | Type | Default | Description |
1738
+ |---|---|---|---|---|
1739
+ | `active` | | `string` | `''` | Name of the selected panel. Defaults to the first enabled tab. |
1740
+ | `activation` | | `'auto' \| 'manual'` | `'auto'` | `auto` selects a tab as soon as it gets focus; `manual` waits for Enter or Space. |
1741
+ | `orientation` | | `'horizontal' \| 'vertical'` | `'horizontal'` | Lays the tab list out horizontally or vertically. |
1742
+ | `label` | | `string \| undefined` | | Accessible name for the tab list. |
1404
1743
 
1405
- <uf-icon name="heart" label="Favorite"></uf-icon>
1406
- <uf-button><uf-icon slot="prefix" name="heart"></uf-icon>Save</uf-button>
1407
- ```
1744
+ #### Methods
1408
1745
 
1409
- - Use `currentColor` for strokes and fills, so the icon takes the text color around it (set `color` to change it).
1410
- - Keep a `viewBox` and leave out `width`/`height`: the icon is `1em` square, so it follows the font size. Change it with `--uf-icon-size`.
1411
- - Registering a built-in name (e.g. `x`) replaces that icon everywhere, including inside components like the dialog's close button.
1412
- - Icons already on the page update when you register their name, so registration order doesn't matter.
1413
- - The markup is inserted as-is: only register SVG from your own code or files, never from user input.
1746
+ | Method | Description |
1747
+ |---|---|
1748
+ | `select(name: string)` | Selects the tab for the given panel name. |
1414
1749
 
1415
- ### `<uf-icon>` API
1750
+ #### Events
1416
1751
 
1417
- #### Attributes and properties
1752
+ | Event | Type | Description |
1753
+ |---|---|---|
1754
+ | `uf-tab-change` | `CustomEvent<TabChangeDetail>` | The selected tab changed. |
1418
1755
 
1419
- | Attribute | Property | Type | Default | Description |
1420
- |---|---|---|---|---|
1421
- | `name` | | `BuiltInIconName \| (string & {})` | `''` | Icon name: a built-in icon or one added with `registerIcons()`. |
1422
- | `label` | | `string \| undefined` | | Accessible label. Without it the icon is hidden from assistive tech. |
1756
+ #### Slots
1757
+
1758
+ | Slot | Description |
1759
+ |---|---|
1760
+ | (default) | `<uf-tab>` and `<uf-tab-panel>` elements. Tabs are moved into the tab list automatically. |
1761
+ | `nav` | The tab list. You don't need to set this yourself. |
1423
1762
 
1424
1763
  #### CSS parts
1425
1764
 
1426
1765
  | Part | Description |
1427
1766
  |---|---|
1428
- | `svg` | The `<svg>` element. |
1767
+ | `tablist` | The element with `role="tablist"`. |
1768
+ | `panels` | The wrapper around the panels. |
1429
1769
 
1430
1770
  #### CSS custom properties
1431
1771
 
1432
1772
  | Property | Description |
1433
1773
  |---|---|
1434
- | `--uf-icon-size` | Width and height. Defaults to `1em`, so it follows the font size. |
1435
- | `--uf-icon-stroke-width` | Stroke width of built-in icons. |
1774
+ | `--uf-tabs-indicator-color` | Color of the selected tab's underline. |
1436
1775
 
1437
- ## Badge
1776
+ ### `<uf-tab>` API
1438
1777
 
1439
- A short label for a status, a category or a count. It's plain text for
1440
- assistive tech: write text that makes sense out of context ("3 unread", not
1441
- just "3"), or describe it in the surrounding element's label.
1778
+ #### Attributes and properties
1442
1779
 
1443
- Tags: `<uf-badge>`. Import: `import '@unframed/core/badge';` (or `npx @unframed/cli add badge` to copy the source).
1780
+ | Attribute | Property | Type | Default | Description |
1781
+ |---|---|---|---|---|
1782
+ | `panel` | | `string` | `''` | Name of the `<uf-tab-panel>` this tab shows. |
1783
+ | `disabled` | | `boolean` | `false` | Disables the tab. |
1444
1784
 
1445
- ### Variants
1785
+ #### Slots
1446
1786
 
1447
- Six colors by meaning, in three appearances: `soft` (the default), `solid` and `outline`.
1787
+ | Slot | Description |
1788
+ |---|---|
1789
+ | (default) | The tab label. |
1448
1790
 
1449
- ```html
1450
- <uf-badge>Draft</uf-badge>
1451
- <uf-badge variant="success">Paid</uf-badge>
1452
- <uf-badge variant="warning" appearance="solid">Expiring</uf-badge>
1453
- <uf-badge variant="info" appearance="outline">Beta</uf-badge>
1454
- ```
1791
+ #### CSS parts
1455
1792
 
1456
- ### Dot, icon and size
1793
+ | Part | Description |
1794
+ |---|---|
1795
+ | `base` | The tab's inner wrapper. |
1457
1796
 
1458
- ```html
1459
- <uf-badge dot variant="success">Online</uf-badge>
1460
- <uf-badge variant="success"><uf-icon slot="prefix" name="check-circle"></uf-icon>Verified</uf-badge>
1461
- <uf-badge size="sm" variant="accent">New</uf-badge>
1462
- ```
1463
-
1464
- - Badges are read as plain text: write "3 unread" rather than "3", so the badge makes sense on its own.
1465
-
1466
- ### `<uf-badge>` API
1797
+ ### `<uf-tab-panel>` API
1467
1798
 
1468
1799
  #### Attributes and properties
1469
1800
 
1470
1801
  | Attribute | Property | Type | Default | Description |
1471
1802
  |---|---|---|---|---|
1472
- | `variant` | | `BadgeVariant` | `'neutral'` | Color, by meaning: `neutral`, `accent`, `info`, `success`, `warning` or `danger`. |
1473
- | `appearance` | | `BadgeAppearance` | `'soft'` | `soft` (tinted background), `solid` (bold background) or `outline` (border only). |
1474
- | `size` | | `BadgeSize` | `'md'` | Size: `sm` or `md`. |
1475
- | `dot` | | `boolean` | `false` | Shows a status dot before the text. |
1803
+ | `name` | | `string` | `''` | Name the matching tab refers to with `panel`. |
1476
1804
 
1477
1805
  #### Slots
1478
1806
 
1479
1807
  | Slot | Description |
1480
1808
  |---|---|
1481
- | (default) | The badge text. |
1482
- | `prefix` | An icon before the text. |
1483
-
1484
- #### CSS parts
1485
-
1486
- | Part | Description |
1487
- |---|---|
1488
- | `base` | The badge. |
1489
- | `dot` | The status dot, when `dot` is set. |
1809
+ | (default) | The panel content. |
1490
1810
 
1491
1811
  #### CSS custom properties
1492
1812
 
1493
1813
  | Property | Description |
1494
1814
  |---|---|
1495
- | `--uf-badge-bg` | Background color. |
1496
- | `--uf-badge-color` | Text color. |
1497
- | `--uf-badge-border-color` | Border color. |
1498
- | `--uf-badge-radius` | Corner radius. Use `999px` for a pill. |
1499
-
1500
- ## Avatar
1501
-
1502
- A picture of a person or an entity. Shows the image when it loads, the
1503
- initials of `name` when there's no image or it fails, and a generic icon
1504
- when there's neither.
1505
-
1506
- `name` is also the accessible name. When the name is already written next
1507
- to the avatar, set `decorative` so screen readers don't read it twice.
1508
-
1509
- Tags: `<uf-avatar>`. Import: `import '@unframed/core/avatar';` (or `npx @unframed/cli add avatar` to copy the source).
1510
-
1511
- ### Image, initials or icon
1512
-
1513
- The image when it loads, the initials of `name` when it doesn't, a generic icon when there's neither.
1815
+ | `--uf-tab-panel-padding` | Padding around the content. |
1514
1816
 
1515
- ```html
1516
- <uf-avatar name="John Smith" src="/photos/john.jpg"></uf-avatar>
1517
- <uf-avatar name="John Smith"></uf-avatar>
1518
- <uf-avatar></uf-avatar>
1519
- ```
1817
+ ## Textarea
1520
1818
 
1521
- ### Sizes and shapes
1819
+ A multi-line text field with a built-in label, hint and validation message.
1522
1820
 
1523
- ```html
1524
- <uf-avatar size="sm" name="John Smith"></uf-avatar>
1525
- <uf-avatar size="xl" name="John Smith"></uf-avatar>
1526
- <uf-avatar size="xl" shape="square" name="Unframed" initials="U"></uf-avatar>
1527
- ```
1821
+ Tags: `<uf-textarea>`. Import: `import '@unframed/core/textarea';` (or `npx @unframed/cli add textarea` to copy the source).
1528
1822
 
1529
- ### Next to a name
1823
+ ### Grows with its content
1530
1824
 
1531
1825
  ```html
1532
- <uf-avatar name="John Smith" decorative></uf-avatar>
1533
- <strong>John Smith</strong>
1826
+ <uf-textarea label="Bio" resize="auto" rows="2" maxlength="280" hint="Up to 280 characters."></uf-textarea>
1534
1827
  ```
1535
1828
 
1536
- - `name` is the accessible name. When the name is written next to the avatar, add `decorative` so screen readers don't read it twice.
1537
-
1538
- ### `<uf-avatar>` API
1829
+ ### `<uf-textarea>` API
1539
1830
 
1540
1831
  #### Attributes and properties
1541
1832
 
1542
1833
  | Attribute | Property | Type | Default | Description |
1543
1834
  |---|---|---|---|---|
1544
- | `src` | | `string \| undefined` | | Image URL. |
1545
- | `name` | | `string \| undefined` | | The person's or entity's name: the accessible name, and the source of the initials. |
1546
- | `initials` | | `string \| undefined` | | Initials to show instead of the ones taken from `name`. |
1547
- | `size` | | `AvatarSize` | `'md'` | Size: `sm`, `md`, `lg` or `xl`. |
1548
- | `shape` | | `AvatarShape` | `'circle'` | `circle` or `square` (rounded corners). |
1549
- | `decorative` | | `boolean` | `false` | Hides the avatar from assistive tech, when the name is already shown next to it. |
1550
- | `loading` | | `'eager' \| 'lazy'` | `'eager'` | The image's `loading` attribute: `lazy` waits until it's near the viewport. |
1551
-
1552
- #### Slots
1553
-
1554
- | Slot | Description |
1555
- |---|---|
1556
- | (default) | Custom content instead of the initials or icon, e.g. an `<uf-icon>`. |
1835
+ | `value` | `defaultValue` | `string` | `''` | Initial value, restored on form reset. Set with the `value` attribute. |
1836
+ | `label` | | `string \| undefined` | | Visible label. |
1837
+ | `hint` | | `string \| undefined` | | Help text below the field. |
1838
+ | `placeholder` | | `string \| undefined` | | Placeholder text. |
1839
+ | `rows` | | `number` | `4` | Visible number of lines. |
1840
+ | `resize` | | `TextareaResize` | `'vertical'` | How the user can resize the field. `auto` grows with the content. |
1841
+ | `size` | | `FieldSize` | `'md'` | Size of the field. |
1842
+ | `readonly` | | `boolean` | `false` | Makes the field read-only. |
1843
+ | `autocomplete` | | `AutoFill \| undefined` | | Native `autocomplete` hint. |
1844
+ | `minlength` | | `number \| undefined` | | Minimum length. |
1845
+ | `maxlength` | | `number \| undefined` | | Maximum length. |
1846
+ | `name` | | `string` | `''` | Name submitted with the form. |
1847
+ | `disabled` | | `boolean` | `false` | Disables the control. |
1848
+ | `required` | | `boolean` | `false` | Makes the control required for form submission. |
1557
1849
 
1558
- #### CSS parts
1850
+ #### Properties only
1559
1851
 
1560
- | Part | Description |
1561
- |---|---|
1562
- | `base` | The avatar. |
1563
- | `image` | The `<img>`. |
1564
- | `initials` | The initials. |
1565
- | `icon` | The fallback icon. |
1852
+ | Property | Type | Description |
1853
+ |---|---|---|
1854
+ | `value` | `string` | Current value. |
1855
+ | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
1856
+ | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
1857
+ | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
1858
+ | `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
1566
1859
 
1567
- #### CSS custom properties
1860
+ #### Methods
1568
1861
 
1569
- | Property | Description |
1862
+ | Method | Description |
1570
1863
  |---|---|
1571
- | `--uf-avatar-size` | Width and height. Overrides `size`. |
1572
- | `--uf-avatar-bg` | Background behind initials and icon. |
1573
- | `--uf-avatar-color` | Color of the initials and icon. |
1574
- | `--uf-avatar-radius` | Corner radius. Overrides `shape`. |
1575
-
1576
- ## Card
1577
-
1578
- A container that groups related content: an optional image, a header, the
1579
- content and actions. Empty sections take no space.
1580
-
1581
- A card is a plain container for assistive tech. To make a whole card a link,
1582
- put a link in the header and let it cover the card with CSS, so the card's
1583
- buttons stay usable.
1584
-
1585
- Tags: `<uf-card>`. Import: `import '@unframed/core/card';` (or `npx @unframed/cli add card` to copy the source).
1586
-
1587
- ### Media, header, content and footer
1588
-
1589
- Every section is optional; empty ones take no space.
1590
-
1591
- ```html
1592
- <uf-card>
1593
- <img slot="media" src="/cover.png" alt="The Unframed logo" />
1594
- <div slot="header">
1595
- <h3>Unframed 0.2</h3>
1596
- <small>Released this week</small>
1597
- </div>
1598
- A link button variant, new colors and smaller Angular bundles.
1599
- <uf-button slot="footer">Read more</uf-button>
1600
- <uf-button slot="footer" variant="ghost">Dismiss</uf-button>
1601
- </uf-card>
1602
- ```
1603
-
1604
- ### Variants and orientation
1605
-
1606
- ```html
1607
- <uf-card variant="elevated">…</uf-card>
1608
- <uf-card variant="filled">…</uf-card>
1609
- <uf-card orientation="horizontal">
1610
- <img slot="media" src="/cover.png" alt="" />
1611
- Media beside the content.
1612
- </uf-card>
1613
- ```
1614
-
1615
- ### `<uf-card>` API
1864
+ | `select()` | Selects all text in the field. |
1865
+ | `checkValidity()` | Returns whether the value is valid, without showing an error. |
1866
+ | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
1867
+ | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
1616
1868
 
1617
- #### Attributes and properties
1869
+ #### Events
1618
1870
 
1619
- | Attribute | Property | Type | Default | Description |
1620
- |---|---|---|---|---|
1621
- | `variant` | | `CardVariant` | `'outline'` | `outline` (a border), `elevated` (a shadow) or `filled` (a tinted background). |
1622
- | `orientation` | | `CardOrientation` | `'vertical'` | `vertical`, or `horizontal` to put the media beside the content. |
1871
+ | Event | Type | Description |
1872
+ |---|---|---|
1873
+ | `input` | | Fired on every keystroke. |
1874
+ | `change` | `Event` | Fired when the value is committed (blur). |
1623
1875
 
1624
1876
  #### Slots
1625
1877
 
1626
1878
  | Slot | Description |
1627
1879
  |---|---|
1628
- | (default) | The main content. |
1629
- | `media` | An image or video, edge to edge at the top (or the start, when horizontal). |
1630
- | `header` | The title area, e.g. a heading and a subtitle. |
1631
- | `footer` | Actions or details at the bottom. |
1880
+ | `label` | The label, when you need markup. Overrides `label`. |
1881
+ | `hint` | Help text below the field. Overrides `hint`. |
1632
1882
 
1633
1883
  #### CSS parts
1634
1884
 
1635
1885
  | Part | Description |
1636
1886
  |---|---|
1637
- | `base` | The card. |
1638
- | `media` | The media wrapper. |
1639
- | `header` | The header wrapper. |
1640
- | `body` | The main content wrapper. |
1641
- | `footer` | The footer wrapper. |
1887
+ | `field` | The wrapper around label, control, hint and error. |
1888
+ | `form-label` | The label. |
1889
+ | `box` | The bordered box around the textarea. |
1890
+ | `textarea` | The native `<textarea>`. |
1891
+ | `hint` | The hint text. |
1892
+ | `error` | The validation message. |
1642
1893
 
1643
1894
  #### CSS custom properties
1644
1895
 
1645
1896
  | Property | Description |
1646
1897
  |---|---|
1647
- | `--uf-card-padding` | Padding of header, body and footer. |
1648
- | `--uf-card-bg` | Background color. |
1649
- | `--uf-card-border-color` | Border color. |
1650
- | `--uf-card-radius` | Corner radius. |
1651
- | `--uf-card-media-width` | Width of the media in a horizontal card. Defaults to 40%. |
1652
-
1653
- ## Table
1654
-
1655
- A table of data, from `columns` and `rows`. Users can sort by the columns
1656
- marked `sortable`. Rendered as a native `<table>`, so assistive tech reads
1657
- headers and cells as usual.
1658
-
1659
- Set `columns` and `rows` as properties, or as JSON attributes in plain HTML.
1660
- The table sorts `rows` itself; with `manual-sort` it only shows the order
1661
- and tells you, so you can sort on the server. Combine it with
1662
- `<uf-pagination>` for long lists.
1663
-
1664
- Tags: `<uf-table>`. Import: `import '@unframed/core/table';` (or `npx @unframed/cli add table` to copy the source).
1665
-
1666
- ### Columns, rows and sorting
1898
+ | `--uf-field-bg` | Background of the box. |
1899
+ | `--uf-field-border-color` | Border color of the box. |
1900
+ | `--uf-field-radius` | Corner radius of the box. |
1667
1901
 
1668
- Describe the columns and pass the rows. Columns marked `sortable` sort on click.
1902
+ ## Toast
1669
1903
 
1670
- ```html
1671
- <uf-table
1672
- label="Team"
1673
- columns='[{"key": "name", "label": "Name", "sortable": true},
1674
- {"key": "role", "label": "Role"},
1675
- {"key": "commits", "label": "Commits", "sortable": true, "align": "end"}]'
1676
- rows='[{"name": "John Smith", "role": "Product designer", "commits": 412},
1677
- {"name": "Jane Doe", "role": "Engineer", "commits": 1290}]'
1678
- ></uf-table>
1679
- ```
1904
+ The region that shows toasts. You rarely need to add it yourself: `toast()`
1905
+ creates one on first use. Add it to choose a placement, or to hold
1906
+ toasts in a specific place in the DOM.
1680
1907
 
1681
- - In plain HTML, `columns` and `rows` can be JSON attributes. From JavaScript, set them as properties.
1682
- - Give the table a `label`: it names the table for screen readers.
1908
+ Tags: `<uf-toaster>`. Import: `import '@unframed/core/toast';` (or `npx @unframed/cli add toast` to copy the source).
1683
1909
 
1684
- ### Formatting, and pages
1910
+ ### Variants
1685
1911
 
1686
- `format` turns a value into text or a DOM node, like a badge. Sorting still uses the raw values.
1912
+ Call `toast()` from anywhere; the toaster is created on first use.
1687
1913
 
1688
1914
  ```html
1689
- <uf-table id="invoices" label="Invoices" row-key="id"></uf-table>
1690
- <uf-pagination id="pages" label="Invoice pages"></uf-pagination>
1691
-
1692
1915
  <script type="module">
1693
- const table = document.querySelector('#invoices');
1694
- const pages = document.querySelector('#pages');
1695
- const pageSize = 8;
1696
-
1697
- table.columns = [
1698
- { key: 'customer', label: 'Customer', sortable: true },
1699
- { key: 'amount', label: 'Amount', sortable: true, align: 'end',
1700
- format: (value) => euro.format(value) },
1701
- ];
1702
- pages.pages = Math.ceil(invoices.length / pageSize);
1703
-
1704
- const show = (page) => (table.rows = invoices.slice((page - 1) * pageSize, page * pageSize));
1705
- pages.addEventListener('uf-page-change', (event) => show(event.detail.page));
1706
- show(1);
1916
+ import { toast } from '@unframed/core/toast';
1917
+ toast('Changes published.', { variant: 'success' });
1707
1918
  </script>
1708
1919
  ```
1709
1920
 
1710
- - To sort on the server, add `manual-sort`: the table shows the sort and fires `uf-sort`, and you load the rows in that order.
1711
- - Set `--uf-table-max-height` to scroll long tables under a sticky header.
1712
-
1713
- ### `<uf-table>` API
1921
+ ### `<uf-toaster>` API
1714
1922
 
1715
1923
  #### Attributes and properties
1716
1924
 
1717
1925
  | Attribute | Property | Type | Default | Description |
1718
1926
  |---|---|---|---|---|
1719
- | `columns` | | `TableColumn[]` | `[]` | The columns, in order. As an attribute, JSON: `[{"key": "name", "label": "Name"}]`. |
1720
- | `rows` | | `TableRow[]` | `[]` | The data, one object per row. As an attribute, JSON: `[{"name": "John"}]`. |
1721
- | `label` | | `string \| undefined` | | Accessible name of the table, e.g. "Invoices". |
1722
- | `sort-key` | `sortKey` | `string \| undefined` | | Key of the column the rows are sorted by. |
1723
- | `sort-direction` | `sortDirection` | `SortDirection` | `'ascending'` | Sort order: `ascending` or `descending`. |
1724
- | `manual-sort` | `manualSort` | `boolean` | `false` | Doesn't sort the rows: only shows the sort and fires `uf-sort`, for sorting on the server. |
1725
- | `row-key` | `rowKey` | `string \| undefined` | | Row property that identifies each row, so rows keep their DOM when the data changes. Defaults to the index. |
1726
- | `striped` | | `boolean` | `false` | Shades every other row. |
1727
- | `density` | | `TableDensity` | `'comfortable'` | Row spacing: `comfortable` or `compact`. |
1728
-
1729
- #### Events
1730
-
1731
- | Event | Type | Description |
1732
- |---|---|---|
1733
- | `uf-sort` | `CustomEvent<TableSortDetail>` | The user sorted by a column. |
1927
+ | `placement` | | `ToasterPlacement` | `'bottom-end'` | Corner or edge of the viewport where toasts appear. |
1928
+ | `label` | | `string \| undefined` | | Accessible name of the notification region. Defaults to "Notifications", or its translation. |
1734
1929
 
1735
- #### Slots
1930
+ #### Methods
1736
1931
 
1737
- | Slot | Description |
1932
+ | Method | Description |
1738
1933
  |---|---|
1739
- | `empty` | Shown when there are no rows. Defaults to "No data", or its translation. |
1934
+ | `add(message: string, options?: ToastOptions)` | Shows a toast in this region. Prefer the `toast()` function. |
1935
+ | `dismiss(id: number)` | Hides a toast by id. |
1740
1936
 
1741
1937
  #### CSS parts
1742
1938
 
1743
1939
  | Part | Description |
1744
1940
  |---|---|
1745
- | `base` | The scroll container around the table. |
1746
- | `table` | The `<table>`. |
1747
- | `header-cell` | Every header cell (`<th>`). |
1748
- | `sort-button` | The button in a sortable header. |
1749
- | `row` | Every body row. |
1750
- | `cell` | Every body cell. |
1751
- | `empty` | The cell shown when there are no rows. |
1941
+ | `region` | The list holding the toasts. |
1942
+ | `toast` | Each toast. |
1943
+ | `title` | A toast's title. |
1944
+ | `message` | A toast's message. |
1945
+ | `close-button` | A toast's dismiss button. |
1752
1946
 
1753
1947
  #### CSS custom properties
1754
1948
 
1755
1949
  | Property | Description |
1756
1950
  |---|---|
1757
- | `--uf-table-max-height` | Height after which the body scrolls under a sticky header. |
1758
- | `--uf-table-border-color` | Border color between rows. |
1759
- | `--uf-table-header-bg` | Background of the header row. |
1760
- | `--uf-table-stripe-bg` | Background of every other row, with `striped`. |
1761
- | `--uf-table-hover-bg` | Background of the row under the pointer. |
1762
-
1763
- ## Pagination
1764
-
1765
- Navigation between the pages of a list or table. Set `pages` and `page`; the
1766
- user changes `page`, and `uf-page-change` tells you which page to show.
1767
-
1768
- It's a navigation landmark: when a page has more than one, give each a
1769
- different `label`.
1770
-
1771
- Tags: `<uf-pagination>`. Import: `import '@unframed/core/pagination';` (or `npx @unframed/cli add pagination` to copy the source).
1772
-
1773
- ### Pages
1951
+ | `--uf-toast-width` | Width of each toast. |
1952
+ | `--uf-toaster-offset` | Distance from the viewport edges. |
1774
1953
 
1775
- Long ranges collapse around the current page; the number of buttons stays the same from page to page.
1954
+ ## Tooltip
1776
1955
 
1777
- ```html
1778
- <uf-pagination pages="20" page="6"></uf-pagination>
1956
+ A short label that appears on hover and keyboard focus. Wrap the element it
1957
+ describes. The text is also set as the trigger's `aria-description` (unless it
1958
+ repeats the trigger's own label), so screen reader users get it too. Don't put
1959
+ interactive content in a tooltip.
1779
1960
 
1780
- <script type="module">
1781
- document.querySelector('uf-pagination').addEventListener('uf-page-change', (event) => {
1782
- loadPage(event.detail.page);
1783
- });
1784
- </script>
1785
- ```
1961
+ Tags: `<uf-tooltip>`. Import: `import '@unframed/core/tooltip';` (or `npx @unframed/cli add tooltip` to copy the source).
1786
1962
 
1787
- ### Siblings and size
1963
+ ### On hover and focus
1788
1964
 
1789
1965
  ```html
1790
- <uf-pagination pages="30" page="15" siblings="2"></uf-pagination>
1791
- <uf-pagination pages="30" page="15" size="sm"></uf-pagination>
1966
+ <uf-tooltip content="Saves without publishing">
1967
+ <uf-button variant="outline">Save draft</uf-button>
1968
+ </uf-tooltip>
1792
1969
  ```
1793
1970
 
1794
- - Each pagination is a navigation landmark: when a page has more than one, give each a different `label`.
1795
-
1796
- ### `<uf-pagination>` API
1971
+ ### `<uf-tooltip>` API
1797
1972
 
1798
1973
  #### Attributes and properties
1799
1974
 
1800
1975
  | Attribute | Property | Type | Default | Description |
1801
1976
  |---|---|---|---|---|
1802
- | `page` | | `number` | `1` | The current page, from 1. |
1803
- | `pages` | | `number` | `1` | How many pages there are. |
1804
- | `siblings` | | `number` | `1` | How many pages to show on each side of the current one. |
1805
- | `label` | | `string \| undefined` | | Accessible name of the navigation, e.g. "Search results pages". Defaults to "Pagination", or its translation. |
1806
- | `size` | | `PaginationSize` | `'md'` | Size: `sm` or `md`. |
1977
+ | `content` | | `string` | `''` | The tooltip text. |
1978
+ | `placement` | | `Placement` | `'top'` | Preferred side. Flips when there is no room. |
1979
+ | `disabled` | | `boolean` | `false` | Turns the tooltip off. |
1980
+ | `delay` | | `number` | `300` | Milliseconds to wait on hover before showing. Focus shows it immediately. |
1981
+ | `open` | | `boolean` | `false` | Whether the tooltip is showing. |
1807
1982
 
1808
- #### Events
1983
+ #### Methods
1809
1984
 
1810
- | Event | Type | Description |
1811
- |---|---|---|
1812
- | `uf-page-change` | `CustomEvent<PageChangeDetail>` | The user chose another page. |
1985
+ | Method | Description |
1986
+ |---|---|
1987
+ | `show()` | Shows the tooltip, unless it's disabled. |
1988
+ | `hide()` | Hides the tooltip. |
1989
+
1990
+ #### Slots
1991
+
1992
+ | Slot | Description |
1993
+ |---|---|
1994
+ | (default) | The element the tooltip describes. |
1813
1995
 
1814
1996
  #### CSS parts
1815
1997
 
1816
1998
  | Part | Description |
1817
1999
  |---|---|
1818
- | `base` | The `<nav>`. |
1819
- | `list` | The list of buttons. |
1820
- | `button` | Every button: pages, previous and next. |
1821
- | `current` | The current page's button. |
1822
- | `previous` | The previous button. |
1823
- | `next` | The next button. |
1824
- | `ellipsis` | The "…" between pages. |
2000
+ | `body` | The tooltip bubble. |
1825
2001
 
1826
2002
  #### CSS custom properties
1827
2003
 
1828
2004
  | Property | Description |
1829
2005
  |---|---|
1830
- | `--uf-pagination-gap` | Space between the buttons. |
2006
+ | `--uf-tooltip-bg` | Background color. |
2007
+ | `--uf-tooltip-color` | Text color. |
2008
+ | `--uf-tooltip-max-width` | Maximum width. |