@unframed/cli 0.5.0 → 0.6.1

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.5.0 components
1
+ # Unframed 0.6.1 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
 
@@ -639,265 +824,313 @@ Type a date in the page language's format, or open the calendar. The value is al
639
824
  |---|---|
640
825
  | `--uf-calendar-day-size` | Width and height of a day. |
641
826
 
642
- ## Checkbox
827
+ ## Dialog
643
828
 
644
- A checkbox with its label as content.
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.
645
832
 
646
- 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).
833
+ Tags: `<uf-dialog>`. Import: `import '@unframed/core/dialog';` (or `npx @unframed/cli add dialog` to copy the source).
647
834
 
648
- ### States
835
+ ### Confirmation
836
+
837
+ Escape, the close button and any element with `data-dialog="close"` close it.
649
838
 
650
839
  ```html
651
- <uf-checkbox checked hint="One email a month.">Subscribe to the newsletter</uf-checkbox>
652
- <uf-checkbox indeterminate>Select all</uf-checkbox>
653
- <uf-checkbox disabled>Disabled</uf-checkbox>
654
- ```
655
-
656
- ### Select all
657
-
658
- ```html
659
- <uf-checkbox-group label="Toppings">
660
- <uf-checkbox select-all>All toppings</uf-checkbox>
661
- <uf-checkbox name="topping" value="cheese">Cheese</uf-checkbox>
662
- <uf-checkbox name="topping" value="olives" checked>Olives</uf-checkbox>
663
- <uf-checkbox name="topping" value="basil">Basil</uf-checkbox>
664
- </uf-checkbox-group>
665
- ```
666
-
667
- ### Binding the indeterminate state
668
-
669
- ```html
670
- <uf-checkbox indeterminate>Notify me</uf-checkbox>
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>
671
846
  ```
672
847
 
673
- ### `<uf-checkbox>` API
848
+ ### `<uf-dialog>` API
674
849
 
675
850
  #### Attributes and properties
676
851
 
677
852
  | Attribute | Property | Type | Default | Description |
678
853
  |---|---|---|---|---|
679
- | `indeterminate` | | `boolean` | `false` | Shows a dash instead of a check, for "some selected". Cleared when the user clicks. |
680
- | `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. |
681
- | `hint` | | `string \| undefined` | | Help text below the label. |
682
- | `checked` | `defaultChecked` | `boolean` | `false` | Initial state, restored on form reset. Set with the `checked` attribute. |
683
- | `value` | | `string` | `'on'` | Value submitted with the form when checked. |
684
- | `name` | | `string` | `''` | Name submitted with the form. |
685
- | `disabled` | | `boolean` | `false` | Disables the control. |
686
- | `required` | | `boolean` | `false` | Makes the control required for form submission. |
687
-
688
- #### Properties only
689
-
690
- | Property | Type | Description |
691
- |---|---|---|
692
- | `checked` | `boolean` | Whether the control is on. |
693
- | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
694
- | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
695
- | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
696
- | `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. |
697
858
 
698
859
  #### Methods
699
860
 
700
861
  | Method | Description |
701
862
  |---|---|
702
- | `toggle()` | Toggles the control, as if the user clicked it. |
703
- | `checkValidity()` | Returns whether the value is valid, without showing an error. |
704
- | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
705
- | `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. |
706
866
 
707
867
  #### Events
708
868
 
709
869
  | Event | Type | Description |
710
870
  |---|---|---|
711
- | `input` | | Fired when the checked state changes. |
712
- | `change` | `Event` | Fired when the checked 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. |
713
874
 
714
875
  #### Slots
715
876
 
716
877
  | Slot | Description |
717
878
  |---|---|
718
- | (default) | The label. |
719
- | `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. |
720
883
 
721
884
  #### CSS parts
722
885
 
723
886
  | Part | Description |
724
887
  |---|---|
725
- | `base` | The `<label>` wrapping control and label. |
726
- | `control` | The box. |
727
- | `checkmark` | The check or dash icon. |
728
- | `label` | The label text. |
729
- | `hint` | The hint text. |
730
- | `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. |
731
894
 
732
895
  #### CSS custom properties
733
896
 
734
897
  | Property | Description |
735
898
  |---|---|
736
- | `--uf-checkbox-size` | Size of the box. |
737
- | `--uf-checkbox-radius` | Corner radius of the box. |
738
- | `--uf-checkbox-checked-bg` | Background when checked. |
739
- | `--uf-checkbox-indeterminate-bg` | Background when indeterminate. Defaults to the checked background. |
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. |
740
904
 
741
- ### `<uf-checkbox-group>` API
905
+ ## Dropdown menu
906
+
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.
910
+
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).
912
+
913
+ ### Menu button
914
+
915
+ Arrow keys move, typing a letter jumps to an item, Escape closes.
916
+
917
+ ```html
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>
927
+ ```
928
+
929
+ ### `<uf-dropdown>` API
742
930
 
743
931
  #### Attributes and properties
744
932
 
745
933
  | Attribute | Property | Type | Default | Description |
746
934
  |---|---|---|---|---|
747
- | `label` | | `string \| undefined` | | Visible group label. |
748
- | `hint` | | `string \| undefined` | | Help text below the checkboxes. |
749
- | `orientation` | | `'vertical' \| 'horizontal'` | `'vertical'` | Lays the checkboxes out in a column or a row. |
750
-
751
- #### Properties only
752
-
753
- | Property | Type | Description |
754
- |---|---|---|
755
- | `value` | `string[]` | The values of the checked checkboxes (other than "select all"). |
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. |
756
939
 
757
940
  #### Methods
758
941
 
759
942
  | Method | Description |
760
943
  |---|---|
761
- | `sync()` | Updates "select all" to match the other checkboxes. Called automatically on user changes; call it after changing `checked` on a checkbox from code. |
944
+ | `show()` | Opens the popover. |
945
+ | `hide()` | Closes the popover. |
946
+ | `toggle()` | Opens the popover if closed, closes it if open. |
762
947
 
763
948
  #### Events
764
949
 
765
950
  | Event | Type | Description |
766
951
  |---|---|---|
767
- | `change` | | A checkbox in the group changed (including through "select all"). |
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. |
768
955
 
769
956
  #### Slots
770
957
 
771
958
  | Slot | Description |
772
959
  |---|---|
773
- | (default) | `<uf-checkbox>` elements. |
774
- | `label` | The group label, when you need markup. Overrides `label`. |
775
- | `hint` | Help text below the checkboxes. Overrides `hint`. |
960
+ | `trigger` | The button that opens the menu. |
961
+ | (default) | A `<uf-menu>`. |
776
962
 
777
963
  #### CSS parts
778
964
 
779
965
  | Part | Description |
780
966
  |---|---|
781
- | `base` | The element with `role="group"`. |
782
- | `form-label` | The group label. |
783
- | `options` | The wrapper around the checkboxes. |
784
- | `hint` | The hint text. |
967
+ | `panel` | The floating panel around the menu. |
785
968
 
786
969
  #### CSS custom properties
787
970
 
788
971
  | Property | Description |
789
972
  |---|---|
790
- | `--uf-checkbox-group-indent` | Indent of the checkboxes under a "select all". |
791
-
792
- ## Switch
793
-
794
- An on/off switch with its label as content. Use it for settings that apply
795
- immediately; use a checkbox for choices submitted later with a form.
796
-
797
- Tags: `<uf-switch>`. Import: `import '@unframed/core/switch';` (or `npx @unframed/cli add switch` to copy the source).
798
-
799
- ### Settings that apply immediately
800
-
801
- ```html
802
- <uf-switch checked>Notifications</uf-switch>
803
- ```
973
+ | `--uf-popover-padding` | Padding of the panel. |
974
+ | `--uf-popover-width` | Width of the panel. Defaults to its content. |
804
975
 
805
- ### `<uf-switch>` API
976
+ ### `<uf-menu>` API
806
977
 
807
978
  #### Attributes and properties
808
979
 
809
980
  | Attribute | Property | Type | Default | Description |
810
981
  |---|---|---|---|---|
811
- | `hint` | | `string \| undefined` | | Help text below the label. |
812
- | `checked` | `defaultChecked` | `boolean` | `false` | Initial state, restored on form reset. Set with the `checked` attribute. |
813
- | `value` | | `string` | `'on'` | Value submitted with the form when checked. |
814
- | `name` | | `string` | `''` | Name submitted with the form. |
815
- | `disabled` | | `boolean` | `false` | Disables the control. |
816
- | `required` | | `boolean` | `false` | Makes the control required for form submission. |
982
+ | `label` | | `string \| undefined` | | Accessible name of the menu. |
817
983
 
818
984
  #### Properties only
819
985
 
820
986
  | Property | Type | Description |
821
987
  |---|---|---|
822
- | `checked` | `boolean` | Whether the control is on. |
823
- | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
824
- | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
825
- | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
826
- | `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
988
+ | `items` | `UfMenuItem[]` | Read-only. Enabled items that belong to this menu (not to a nested one). |
827
989
 
828
990
  #### Methods
829
991
 
830
992
  | Method | Description |
831
993
  |---|---|
832
- | `toggle()` | Toggles the control, as if the user clicked it. |
833
- | `checkValidity()` | Returns whether the value is valid, without showing an error. |
834
- | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
835
- | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
994
+ | `focusFirst()` | Focuses the first enabled item. |
995
+ | `focusLast()` | Focuses the last enabled item. |
836
996
 
837
997
  #### Events
838
998
 
839
999
  | Event | Type | Description |
840
1000
  |---|---|---|
841
- | `input` | | Fired when the state changes. |
842
- | `change` | `Event` | Fired when the state changes. |
1001
+ | `uf-select` | `CustomEvent<MenuSelectDetail>` | An item was chosen. Cancel it to keep a dropdown open. |
1002
+
1003
+ #### Slots
1004
+
1005
+ | Slot | Description |
1006
+ |---|---|
1007
+ | (default) | `<uf-menu-item>` elements and `<hr>` separators. |
1008
+
1009
+ ### `<uf-menu-item>` API
1010
+
1011
+ #### Attributes and properties
1012
+
1013
+ | Attribute | Property | Type | Default | Description |
1014
+ |---|---|---|---|---|
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. |
843
1019
 
844
1020
  #### Slots
845
1021
 
846
1022
  | Slot | Description |
847
1023
  |---|---|
848
1024
  | (default) | The label. |
849
- | `hint` | Help text below the label. Overrides `hint`. |
1025
+ | `prefix` | An icon before the label. |
1026
+ | `suffix` | Trailing content, e.g. a keyboard shortcut. |
850
1027
 
851
1028
  #### CSS parts
852
1029
 
853
1030
  | Part | Description |
854
1031
  |---|---|
855
- | `base` | The `<label>` wrapping control and label. |
856
- | `control` | The track. |
857
- | `thumb` | The moving knob. |
858
- | `label` | The label text. |
859
- | `hint` | The hint text. |
860
- | `error` | The validation message. |
1032
+ | `checkmark` | The check shown for checked checkbox items. |
1033
+ | `label` | The label wrapper. |
861
1034
 
862
- #### CSS custom properties
1035
+ ## Icon
863
1036
 
864
- | Property | Description |
865
- |---|---|
866
- | `--uf-switch-width` | Width of the track. |
867
- | `--uf-switch-height` | Height of the track. |
868
- | `--uf-switch-checked-bg` | Track color when on. |
869
- | `--uf-switch-radius` | Corner radius of track and thumb. Use `999px` for a pill. |
1037
+ An icon from the built-in set, or one added with `registerIcons()`.
1038
+ Icons are decorative unless you give them a `label`.
870
1039
 
871
- ## Radio group
1040
+ Tags: `<uf-icon>`. Import: `import '@unframed/core/icon';` (or `npx @unframed/cli add icon` to copy the source).
872
1041
 
873
- A group of `<uf-radio>` options with one selected value. Arrow keys move
874
- the selection, and only the selected option is in the tab order.
1042
+ ### Built-in set
875
1043
 
876
- 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).
1044
+ Icons are decorative unless you give them a `label`. Add your own with `registerIcons()`.
877
1045
 
878
- ### Pick one
1046
+ ```html
1047
+ <uf-icon name="check-circle" label="Done"></uf-icon>
1048
+ ```
879
1049
 
880
- Arrow keys move the selection; only the selected radio is in the tab order.
1050
+ ### Your own icons
881
1051
 
882
1052
  ```html
883
- <uf-radio-group label="Plan" value="pro" orientation="horizontal">
884
- <uf-radio value="free">Free</uf-radio>
885
- <uf-radio value="pro">Pro</uf-radio>
886
- <uf-radio value="team">Team</uf-radio>
887
- <uf-radio value="enterprise" disabled>Enterprise</uf-radio>
888
- </uf-radio-group>
889
- ```
1053
+ <script type="module">
1054
+ import { registerIcons } from '@unframed/core/icon';
890
1055
 
891
- ### `<uf-radio-group>` API
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>
892
1061
 
893
- #### Attributes and properties
1062
+ <uf-icon name="heart" label="Favorite"></uf-icon>
1063
+ <uf-button><uf-icon slot="prefix" name="heart"></uf-icon>Save</uf-button>
1064
+ ```
894
1065
 
895
- | Attribute | Property | Type | Default | Description |
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
1073
+
1074
+ #### Attributes and properties
1075
+
1076
+ | Attribute | Property | Type | Default | Description |
896
1077
  |---|---|---|---|---|
897
- | `value` | `defaultValue` | `string` | `''` | Initially selected value, restored on form reset. Set with the `value` attribute. |
898
- | `label` | | `string \| undefined` | | Visible group label. |
899
- | `hint` | | `string \| undefined` | | Help text below the options. |
900
- | `orientation` | | `'vertical' \| 'horizontal'` | `'vertical'` | Lays the options out in a column or a row. |
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. |
1080
+
1081
+ #### CSS parts
1082
+
1083
+ | Part | Description |
1084
+ |---|---|
1085
+ | `svg` | The `<svg>` element. |
1086
+
1087
+ #### CSS custom properties
1088
+
1089
+ | Property | Description |
1090
+ |---|---|
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. |
1093
+
1094
+ ## Input
1095
+
1096
+ A single-line text field with a built-in label, hint and validation message.
1097
+
1098
+ Tags: `<uf-input>`. Import: `import '@unframed/core/input';` (or `npx @unframed/cli add input` to copy the source).
1099
+
1100
+ ### With label, hint and validation
1101
+
1102
+ Errors appear after the user edits the field or tries to submit.
1103
+
1104
+ ```html
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>
1111
+ ```
1112
+
1113
+ ### `<uf-input>` API
1114
+
1115
+ #### Attributes and properties
1116
+
1117
+ | Attribute | Property | Type | Default | Description |
1118
+ |---|---|---|---|---|
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. |
901
1134
  | `name` | | `string` | `''` | Name submitted with the form. |
902
1135
  | `disabled` | | `boolean` | `false` | Disables the control. |
903
1136
  | `required` | | `boolean` | `false` | Makes the control required for form submission. |
@@ -906,7 +1139,7 @@ Arrow keys move the selection; only the selected radio is in the tab order.
906
1139
 
907
1140
  | Property | Type | Description |
908
1141
  |---|---|---|
909
- | `value` | `string` | The selected radio's value, or an empty string. |
1142
+ | `value` | `string` | Current value. |
910
1143
  | `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
911
1144
  | `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
912
1145
  | `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
@@ -916,7 +1149,7 @@ Arrow keys move the selection; only the selected radio is in the tab order.
916
1149
 
917
1150
  | Method | Description |
918
1151
  |---|---|
919
- | `focus(options: FocusOptions)` | Moves focus to the selected radio, or the first enabled one. |
1152
+ | `select()` | Selects all text in the field. |
920
1153
  | `checkValidity()` | Returns whether the value is valid, without showing an error. |
921
1154
  | `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
922
1155
  | `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
@@ -925,1084 +1158,851 @@ Arrow keys move the selection; only the selected radio is in the tab order.
925
1158
 
926
1159
  | Event | Type | Description |
927
1160
  |---|---|---|
928
- | `input` | `Event` | Fired when the selection changes. |
929
- | `change` | `Event` | Fired when the selection changes. |
1161
+ | `input` | | Fired on every keystroke. |
1162
+ | `change` | `Event` | Fired when the value is committed (blur or Enter). |
930
1163
 
931
1164
  #### Slots
932
1165
 
933
1166
  | Slot | Description |
934
1167
  |---|---|
935
- | (default) | `<uf-radio>` elements. |
936
- | `label` | The group label, when you need markup. Overrides `label`. |
937
- | `hint` | Help text below the options. Overrides `hint`. |
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. |
938
1172
 
939
1173
  #### CSS parts
940
1174
 
941
1175
  | Part | Description |
942
1176
  |---|---|
943
- | `base` | The element with `role="radiogroup"`. |
944
- | `form-label` | The group label. |
945
- | `options` | The wrapper around the radios. |
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>`. |
946
1181
  | `hint` | The hint text. |
947
1182
  | `error` | The validation message. |
948
1183
 
949
- ### `<uf-radio>` API
1184
+ #### CSS custom properties
1185
+
1186
+ | Property | Description |
1187
+ |---|---|
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. |
1191
+
1192
+ ## Pagination
1193
+
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.
1196
+
1197
+ It's a navigation landmark: when a page has more than one, give each a
1198
+ different `label`.
1199
+
1200
+ Tags: `<uf-pagination>`. Import: `import '@unframed/core/pagination';` (or `npx @unframed/cli add pagination` to copy the source).
1201
+
1202
+ ### Pages
1203
+
1204
+ Long ranges collapse around the current page; the number of buttons stays the same from page to page.
1205
+
1206
+ ```html
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>
1214
+ ```
1215
+
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
950
1226
 
951
1227
  #### Attributes and properties
952
1228
 
953
1229
  | Attribute | Property | Type | Default | Description |
954
1230
  |---|---|---|---|---|
955
- | `value` | | `string` | `''` | Value the group takes when this radio is selected. |
956
- | `checked` | | `boolean` | `false` | Whether this radio is selected. Set by the group. |
957
- | `disabled` | | `boolean` | `false` | Disables this option. |
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`. |
958
1236
 
959
- #### Slots
1237
+ #### Events
960
1238
 
961
- | Slot | Description |
962
- |---|---|
963
- | (default) | The label. |
1239
+ | Event | Type | Description |
1240
+ |---|---|---|
1241
+ | `uf-page-change` | `CustomEvent<PageChangeDetail>` | The user chose another page. |
964
1242
 
965
1243
  #### CSS parts
966
1244
 
967
1245
  | Part | Description |
968
1246
  |---|---|
969
- | `control` | The circle. |
970
- | `label` | The label text. |
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. |
971
1254
 
972
1255
  #### CSS custom properties
973
1256
 
974
1257
  | Property | Description |
975
1258
  |---|---|
976
- | `--uf-radio-size` | Size of the circle. |
977
- | `--uf-radio-checked-color` | Color of the circle when checked. |
1259
+ | `--uf-pagination-gap` | Space between the buttons. |
978
1260
 
979
- ## Tabs
1261
+ ## Popover
980
1262
 
981
- Tabs that switch between panels. Arrow keys move between tabs, Home and End
982
- jump to the ends, and only the selected tab is in the tab order.
1263
+ A panel anchored to a trigger, built on the Popover API: it renders in the
1264
+ top layer and closes on Escape or a click outside. Use it for menus of
1265
+ actions, filters or small forms; use a dialog for anything that blocks the page.
983
1266
 
984
- Tags: `<uf-tabs>`, `<uf-tab>`, `<uf-tab-panel>`. Import: `import '@unframed/core/tabs';` (or `npx @unframed/cli add tabs` to copy the source).
1267
+ Tags: `<uf-popover>`. Import: `import '@unframed/core/popover';` (or `npx @unframed/cli add popover` to copy the source).
985
1268
 
986
- ### Tabs and panels
1269
+ ### Floating panel
987
1270
 
988
1271
  ```html
989
- <uf-tabs label="Project settings">
990
- <uf-tab panel="general">General</uf-tab>
991
- <uf-tab panel="members">Members</uf-tab>
992
- <uf-tab-panel name="general">General settings for the project.</uf-tab-panel>
993
- <uf-tab-panel name="members">Invite people and manage roles.</uf-tab-panel>
994
- </uf-tabs>
1272
+ <uf-popover>
1273
+ <uf-button slot="trigger" variant="outline">Filters</uf-button>
1274
+ <uf-checkbox checked>Open issues</uf-checkbox>
1275
+ <uf-checkbox>Closed issues</uf-checkbox>
1276
+ </uf-popover>
995
1277
  ```
996
1278
 
997
- ### `<uf-tabs>` API
1279
+ ### `<uf-popover>` API
998
1280
 
999
1281
  #### Attributes and properties
1000
1282
 
1001
1283
  | Attribute | Property | Type | Default | Description |
1002
1284
  |---|---|---|---|---|
1003
- | `active` | | `string` | `''` | Name of the selected panel. Defaults to the first enabled tab. |
1004
- | `activation` | | `'auto' \| 'manual'` | `'auto'` | `auto` selects a tab as soon as it gets focus; `manual` waits for Enter or Space. |
1005
- | `orientation` | | `'horizontal' \| 'vertical'` | `'horizontal'` | Lays the tab list out horizontally or vertically. |
1006
- | `label` | | `string \| undefined` | | Accessible name for the tab list. |
1285
+ | `open` | | `boolean` | `false` | Whether the popover is open. |
1286
+ | `placement` | | `Placement` | `'bottom-start'` | Preferred side. Flips when there is no room. |
1287
+ | `distance` | | `number` | `6` | Gap between trigger and panel, in pixels. |
1288
+ | `label` | | `string \| undefined` | | Accessible name of the panel. Defaults to the trigger's text. |
1007
1289
 
1008
1290
  #### Methods
1009
1291
 
1010
1292
  | Method | Description |
1011
1293
  |---|---|
1012
- | `select(name: string)` | Selects the tab for the given panel name. |
1294
+ | `show()` | Opens the popover. |
1295
+ | `hide()` | Closes the popover. |
1296
+ | `toggle()` | Opens the popover if closed, closes it if open. |
1013
1297
 
1014
1298
  #### Events
1015
1299
 
1016
1300
  | Event | Type | Description |
1017
1301
  |---|---|---|
1018
- | `uf-tab-change` | `CustomEvent<TabChangeDetail>` | The selected tab changed. |
1302
+ | `uf-show` | `Event` | The popover opened. |
1303
+ | `uf-hide` | | The popover closed. |
1019
1304
 
1020
1305
  #### Slots
1021
1306
 
1022
1307
  | Slot | Description |
1023
1308
  |---|---|
1024
- | (default) | `<uf-tab>` and `<uf-tab-panel>` elements. Tabs are moved into the tab list automatically. |
1025
- | `nav` | The tab list. You don't need to set this yourself. |
1309
+ | `trigger` | The element that toggles the popover, usually a button. |
1310
+ | (default) | The popover content. |
1026
1311
 
1027
1312
  #### CSS parts
1028
1313
 
1029
1314
  | Part | Description |
1030
1315
  |---|---|
1031
- | `tablist` | The element with `role="tablist"`. |
1032
- | `panels` | The wrapper around the panels. |
1316
+ | `panel` | The floating panel. |
1033
1317
 
1034
1318
  #### CSS custom properties
1035
1319
 
1036
1320
  | Property | Description |
1037
1321
  |---|---|
1038
- | `--uf-tabs-indicator-color` | Color of the selected tab's underline. |
1039
-
1040
- ### `<uf-tab>` API
1322
+ | `--uf-popover-padding` | Padding of the panel. |
1323
+ | `--uf-popover-width` | Width of the panel. Defaults to its content. |
1041
1324
 
1042
- #### Attributes and properties
1325
+ ## Radio group
1043
1326
 
1044
- | Attribute | Property | Type | Default | Description |
1045
- |---|---|---|---|---|
1046
- | `panel` | | `string` | `''` | Name of the `<uf-tab-panel>` this tab shows. |
1047
- | `disabled` | | `boolean` | `false` | Disables the tab. |
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.
1048
1329
 
1049
- #### Slots
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).
1050
1331
 
1051
- | Slot | Description |
1052
- |---|---|
1053
- | (default) | The tab label. |
1332
+ ### Pick one
1054
1333
 
1055
- #### CSS parts
1334
+ Arrow keys move the selection; only the selected radio is in the tab order.
1056
1335
 
1057
- | Part | Description |
1058
- |---|---|
1059
- | `base` | The tab's inner wrapper. |
1336
+ ```html
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>
1343
+ ```
1060
1344
 
1061
- ### `<uf-tab-panel>` API
1345
+ ### `<uf-radio-group>` API
1062
1346
 
1063
1347
  #### Attributes and properties
1064
1348
 
1065
1349
  | Attribute | Property | Type | Default | Description |
1066
1350
  |---|---|---|---|---|
1067
- | `name` | | `string` | `''` | Name the matching tab refers to with `panel`. |
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. |
1068
1358
 
1069
- #### Slots
1359
+ #### Properties only
1070
1360
 
1071
- | Slot | Description |
1072
- |---|---|
1073
- | (default) | The panel content. |
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. |
1074
1368
 
1075
- #### CSS custom properties
1369
+ #### Methods
1076
1370
 
1077
- | Property | Description |
1371
+ | Method | Description |
1078
1372
  |---|---|
1079
- | `--uf-tab-panel-padding` | Padding around the content. |
1080
-
1081
- ## Accordion
1082
-
1083
- Groups `<uf-accordion-item>`s. By default opening one item closes the
1084
- others; set `multiple` to let several stay open. Up and Down arrows move
1085
- between headers, Home and End jump to the first and last.
1086
-
1087
- Tags: `<uf-accordion>`, `<uf-accordion-item>`. Import: `import '@unframed/core/accordion';` (or `npx @unframed/cli add accordion` to copy the source).
1088
-
1089
- ### One open at a time
1090
-
1091
- Add `multiple` to let several items stay open.
1092
-
1093
- ```html
1094
- <uf-accordion>
1095
- <uf-accordion-item summary="What is Unframed?" open>
1096
- A library of web components that work in any framework, or none.
1097
- </uf-accordion-item>
1098
- <uf-accordion-item summary="Can I edit the components?">…</uf-accordion-item>
1099
- </uf-accordion>
1100
- ```
1101
-
1102
- ### `<uf-accordion>` API
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. |
1103
1377
 
1104
- #### Attributes and properties
1378
+ #### Events
1105
1379
 
1106
- | Attribute | Property | Type | Default | Description |
1107
- |---|---|---|---|---|
1108
- | `multiple` | | `boolean` | `false` | Allows several items to be open at once. |
1380
+ | Event | Type | Description |
1381
+ |---|---|---|
1382
+ | `input` | `Event` | Fired when the selection changes. |
1383
+ | `change` | `Event` | Fired when the selection changes. |
1109
1384
 
1110
1385
  #### Slots
1111
1386
 
1112
1387
  | Slot | Description |
1113
1388
  |---|---|
1114
- | (default) | `<uf-accordion-item>` elements. |
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`. |
1115
1392
 
1116
1393
  #### CSS parts
1117
1394
 
1118
1395
  | Part | Description |
1119
1396
  |---|---|
1120
- | `base` | The wrapper around the items. |
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. |
1121
1402
 
1122
- ### `<uf-accordion-item>` API
1403
+ ### `<uf-radio>` API
1123
1404
 
1124
1405
  #### Attributes and properties
1125
1406
 
1126
1407
  | Attribute | Property | Type | Default | Description |
1127
1408
  |---|---|---|---|---|
1128
- | `open` | | `boolean` | `false` | Whether the item is expanded. |
1129
- | `summary` | | `string \| undefined` | | Header text. |
1130
- | `disabled` | | `boolean` | `false` | Prevents the user from toggling the item. |
1131
-
1132
- #### Properties only
1133
-
1134
- | Property | Type | Description |
1135
- |---|---|---|
1136
- | `header` | `HTMLElement \| null` | Read-only. The header element, for keyboard navigation between items. |
1137
-
1138
- #### Methods
1139
-
1140
- | Method | Description |
1141
- |---|---|
1142
- | `show()` | Expands the item. |
1143
- | `hide()` | Collapses the item. |
1144
- | `focus(options: FocusOptions)` | Focuses the header. |
1145
-
1146
- #### Events
1147
-
1148
- | Event | Type | Description |
1149
- |---|---|---|
1150
- | `uf-show` | | The item opened. |
1151
- | `uf-hide` | | The item closed. |
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. |
1152
1412
 
1153
1413
  #### Slots
1154
1414
 
1155
1415
  | Slot | Description |
1156
1416
  |---|---|
1157
- | (default) | The content. |
1158
- | `summary` | The header, when you need markup. Overrides `summary`. |
1417
+ | (default) | The label. |
1159
1418
 
1160
1419
  #### CSS parts
1161
1420
 
1162
1421
  | Part | Description |
1163
1422
  |---|---|
1164
- | `base` | The native `<details>`. |
1165
- | `header` | The clickable header (`<summary>`). |
1166
- | `chevron` | The arrow icon. |
1167
- | `content` | The content wrapper. |
1423
+ | `control` | The circle. |
1424
+ | `label` | The label text. |
1168
1425
 
1169
1426
  #### CSS custom properties
1170
1427
 
1171
1428
  | Property | Description |
1172
1429
  |---|---|
1173
- | `--uf-accordion-padding` | Horizontal padding of header and content. |
1430
+ | `--uf-radio-size` | Size of the circle. |
1431
+ | `--uf-radio-checked-color` | Color of the circle when checked. |
1174
1432
 
1175
- ## Dialog
1433
+ ## Select
1176
1434
 
1177
- A modal dialog built on the native `<dialog>`: it renders in the top layer,
1178
- traps focus, makes the page inert, and returns focus to the opener on close.
1179
- Any element inside with `data-dialog="close"` closes it.
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.
1180
1438
 
1181
- Tags: `<uf-dialog>`. Import: `import '@unframed/core/dialog';` (or `npx @unframed/cli add dialog` to copy the source).
1439
+ Tags: `<uf-select>`. Import: `import '@unframed/core/select';` (or `npx @unframed/cli add select` to copy the source).
1182
1440
 
1183
- ### Confirmation
1441
+ ### Native options
1184
1442
 
1185
- Escape, the close button and any element with `data-dialog="close"` close it.
1443
+ Built on the native `<select>`: write plain `<option>` and `<optgroup>` children.
1186
1444
 
1187
1445
  ```html
1188
- <uf-button variant="danger" onclick="this.nextElementSibling.show()">Delete project…</uf-button>
1189
- <uf-dialog label="Delete project?" light-dismiss>
1190
- <p>This permanently deletes the project and its 128 issues.</p>
1191
- <uf-button slot="footer" variant="ghost" data-dialog="close">Cancel</uf-button>
1192
- <uf-button slot="footer" variant="danger">Delete</uf-button>
1193
- </uf-dialog>
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>
1194
1454
  ```
1195
1455
 
1196
- ### `<uf-dialog>` API
1456
+ ### `<uf-select>` API
1197
1457
 
1198
1458
  #### Attributes and properties
1199
1459
 
1200
1460
  | Attribute | Property | Type | Default | Description |
1201
1461
  |---|---|---|---|---|
1202
- | `open` | | `boolean` | `false` | Whether the dialog is open. |
1203
- | `label` | | `string \| undefined` | | Title of the dialog, also its accessible name. |
1204
- | `light-dismiss` | `lightDismiss` | `boolean` | `false` | Closes the dialog when the backdrop is clicked. |
1205
- | `without-header` | `withoutHeader` | `boolean` | `false` | Hides the header. Set `label` anyway, so the dialog keeps an accessible name. |
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. |
1471
+
1472
+ #### Properties only
1473
+
1474
+ | Property | Type | Description |
1475
+ |---|---|---|
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. |
1206
1481
 
1207
1482
  #### Methods
1208
1483
 
1209
1484
  | Method | Description |
1210
1485
  |---|---|
1211
- | `show()` | Opens the dialog. |
1212
- | `hide()` | Closes the dialog, without firing `uf-request-close`. |
1213
- | `requestClose(source?: DialogCloseSource)` | Asks to close, as a user action would. Listeners can cancel it. |
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. |
1214
1489
 
1215
1490
  #### Events
1216
1491
 
1217
1492
  | Event | Type | Description |
1218
1493
  |---|---|---|
1219
- | `uf-show` | `Event` | The dialog opened. |
1220
- | `uf-hide` | `Event` | The dialog closed. |
1221
- | `uf-request-close` | `CustomEvent<DialogRequestCloseDetail>` | The user tried to close the dialog. Call `preventDefault()` to keep it open. |
1494
+ | `input` | | Fired when the selection changes. |
1495
+ | `change` | `Event` | Fired when the selection changes. |
1222
1496
 
1223
1497
  #### Slots
1224
1498
 
1225
1499
  | Slot | Description |
1226
1500
  |---|---|
1227
- | (default) | The dialog content. |
1228
- | `label` | The title, when you need markup. Overrides `label`. |
1229
- | `header-actions` | Extra buttons next to the close button. |
1230
- | `footer` | Actions at the bottom, usually buttons. |
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. |
1231
1505
 
1232
1506
  #### CSS parts
1233
1507
 
1234
1508
  | Part | Description |
1235
1509
  |---|---|
1236
- | `dialog` | The native `<dialog>`. |
1237
- | `header` | The header with title and close button. |
1238
- | `title` | The title. |
1239
- | `close-button` | The close button. |
1240
- | `body` | The content area. |
1241
- | `footer` | The footer. |
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. |
1242
1517
 
1243
1518
  #### CSS custom properties
1244
1519
 
1245
1520
  | Property | Description |
1246
1521
  |---|---|
1247
- | `--uf-dialog-bg` | Background of the dialog. |
1248
- | `--uf-dialog-width` | Width of the dialog. Defaults to `32rem`. |
1249
- | `--uf-dialog-padding` | Padding of header, body and footer. |
1250
- | `--uf-dialog-radius` | Corner radius. |
1251
- | `--uf-dialog-backdrop` | Backdrop color. |
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. |
1252
1525
 
1253
- ## Popover
1526
+ ## Switch
1254
1527
 
1255
- A panel anchored to a trigger, built on the Popover API: it renders in the
1256
- top layer and closes on Escape or a click outside. Use it for menus of
1257
- actions, filters or small forms; use a dialog for anything that blocks the page.
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.
1258
1530
 
1259
- Tags: `<uf-popover>`. Import: `import '@unframed/core/popover';` (or `npx @unframed/cli add popover` to copy the source).
1531
+ Tags: `<uf-switch>`. Import: `import '@unframed/core/switch';` (or `npx @unframed/cli add switch` to copy the source).
1260
1532
 
1261
- ### Floating panel
1533
+ ### Settings that apply immediately
1262
1534
 
1263
1535
  ```html
1264
- <uf-popover>
1265
- <uf-button slot="trigger" variant="outline">Filters</uf-button>
1266
- <uf-checkbox checked>Open issues</uf-checkbox>
1267
- <uf-checkbox>Closed issues</uf-checkbox>
1268
- </uf-popover>
1536
+ <uf-switch checked>Notifications</uf-switch>
1269
1537
  ```
1270
1538
 
1271
- ### `<uf-popover>` API
1539
+ ### `<uf-switch>` API
1272
1540
 
1273
1541
  #### Attributes and properties
1274
1542
 
1275
1543
  | Attribute | Property | Type | Default | Description |
1276
1544
  |---|---|---|---|---|
1277
- | `open` | | `boolean` | `false` | Whether the popover is open. |
1278
- | `placement` | | `Placement` | `'bottom-start'` | Preferred side. Flips when there is no room. |
1279
- | `distance` | | `number` | `6` | Gap between trigger and panel, in pixels. |
1280
- | `label` | | `string \| undefined` | | Accessible name of the panel. Defaults to the trigger's text. |
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. |
1281
1561
 
1282
1562
  #### Methods
1283
1563
 
1284
1564
  | Method | Description |
1285
1565
  |---|---|
1286
- | `show()` | Opens the popover. |
1287
- | `hide()` | Closes the popover. |
1288
- | `toggle()` | Opens the popover if closed, closes it if open. |
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. |
1289
1570
 
1290
1571
  #### Events
1291
1572
 
1292
1573
  | Event | Type | Description |
1293
1574
  |---|---|---|
1294
- | `uf-show` | `Event` | The popover opened. |
1295
- | `uf-hide` | | The popover closed. |
1575
+ | `input` | | Fired when the state changes. |
1576
+ | `change` | `Event` | Fired when the state changes. |
1296
1577
 
1297
1578
  #### Slots
1298
1579
 
1299
1580
  | Slot | Description |
1300
1581
  |---|---|
1301
- | `trigger` | The element that toggles the popover, usually a button. |
1302
- | (default) | The popover content. |
1582
+ | (default) | The label. |
1583
+ | `hint` | Help text below the label. Overrides `hint`. |
1303
1584
 
1304
1585
  #### CSS parts
1305
1586
 
1306
1587
  | Part | Description |
1307
1588
  |---|---|
1308
- | `panel` | The floating panel. |
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. |
1309
1595
 
1310
1596
  #### CSS custom properties
1311
1597
 
1312
1598
  | Property | Description |
1313
1599
  |---|---|
1314
- | `--uf-popover-padding` | Padding of the panel. |
1315
- | `--uf-popover-width` | Width of the panel. Defaults to its content. |
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. |
1316
1604
 
1317
- ## Dropdown menu
1605
+ ## Table
1318
1606
 
1319
- A button that opens a `<uf-menu>`, following the WAI-ARIA menu button
1320
- pattern: Enter, Space or Down open it on the first item, Up on the last;
1321
- choosing an item or pressing Escape closes it and returns focus to the button.
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.
1322
1610
 
1323
- 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).
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.
1324
1615
 
1325
- ### Menu button
1616
+ Tags: `<uf-table>`. Import: `import '@unframed/core/table';` (or `npx @unframed/cli add table` to copy the source).
1326
1617
 
1327
- Arrow keys move, typing a letter jumps to an item, Escape closes.
1618
+ ### Columns, rows and sorting
1619
+
1620
+ Describe the columns and pass the rows. Columns marked `sortable` sort on click.
1328
1621
 
1329
1622
  ```html
1330
- <uf-dropdown>
1331
- <uf-button slot="trigger" variant="secondary">Actions</uf-button>
1332
- <uf-menu label="Project actions">
1333
- <uf-menu-item value="edit">Edit<span slot="suffix">⌘E</span></uf-menu-item>
1334
- <uf-menu-item value="duplicate">Duplicate</uf-menu-item>
1335
- <hr />
1336
- <uf-menu-item value="pin" type="checkbox" checked>Pinned</uf-menu-item>
1337
- </uf-menu>
1338
- </uf-dropdown>
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>
1339
1631
  ```
1340
1632
 
1341
- ### `<uf-dropdown>` API
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.
1639
+
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
+
1644
+ <script type="module">
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);
1659
+ </script>
1660
+ ```
1661
+
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
1342
1666
 
1343
1667
  #### Attributes and properties
1344
1668
 
1345
1669
  | Attribute | Property | Type | Default | Description |
1346
1670
  |---|---|---|---|---|
1347
- | `open` | | `boolean` | `false` | Whether the popover is open. |
1348
- | `placement` | | `Placement` | `'bottom-start'` | Preferred side. Flips when there is no room. |
1349
- | `distance` | | `number` | `6` | Gap between trigger and panel, in pixels. |
1350
- | `label` | | `string \| undefined` | | Accessible name of the panel. Defaults to the trigger's text. |
1351
-
1352
- #### Methods
1353
-
1354
- | Method | Description |
1355
- |---|---|
1356
- | `show()` | Opens the popover. |
1357
- | `hide()` | Closes the popover. |
1358
- | `toggle()` | Opens the popover if closed, closes it if open. |
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`. |
1359
1680
 
1360
1681
  #### Events
1361
1682
 
1362
1683
  | Event | Type | Description |
1363
1684
  |---|---|---|
1364
- | `uf-select` | `CustomEvent<MenuSelectDetail>` | An item was chosen (bubbles up from the menu). |
1365
- | `uf-show` | `Event` | The menu opened. |
1366
- | `uf-hide` | | The menu closed. |
1685
+ | `uf-sort` | `CustomEvent<TableSortDetail>` | The user sorted by a column. |
1367
1686
 
1368
1687
  #### Slots
1369
1688
 
1370
1689
  | Slot | Description |
1371
1690
  |---|---|
1372
- | `trigger` | The button that opens the menu. |
1373
- | (default) | A `<uf-menu>`. |
1691
+ | `empty` | Shown when there are no rows. Defaults to "No data", or its translation. |
1374
1692
 
1375
1693
  #### CSS parts
1376
1694
 
1377
1695
  | Part | Description |
1378
1696
  |---|---|
1379
- | `panel` | The floating panel around the menu. |
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. |
1380
1704
 
1381
1705
  #### CSS custom properties
1382
1706
 
1383
1707
  | Property | Description |
1384
1708
  |---|---|
1385
- | `--uf-popover-padding` | Padding of the panel. |
1386
- | `--uf-popover-width` | Width of the panel. Defaults to its content. |
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. |
1387
1714
 
1388
- ### `<uf-menu>` API
1715
+ ## Tabs
1716
+
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.
1719
+
1720
+ Tags: `<uf-tabs>`, `<uf-tab>`, `<uf-tab-panel>`. Import: `import '@unframed/core/tabs';` (or `npx @unframed/cli add tabs` to copy the source).
1721
+
1722
+ ### Tabs and panels
1723
+
1724
+ ```html
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>
1731
+ ```
1732
+
1733
+ ### `<uf-tabs>` API
1389
1734
 
1390
1735
  #### Attributes and properties
1391
1736
 
1392
1737
  | Attribute | Property | Type | Default | Description |
1393
1738
  |---|---|---|---|---|
1394
- | `label` | | `string \| undefined` | | Accessible name of the menu. |
1395
-
1396
- #### Properties only
1397
-
1398
- | Property | Type | Description |
1399
- |---|---|---|
1400
- | `items` | `UfMenuItem[]` | Read-only. Enabled items that belong to this menu (not to a nested one). |
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. |
1401
1743
 
1402
1744
  #### Methods
1403
1745
 
1404
1746
  | Method | Description |
1405
1747
  |---|---|
1406
- | `focusFirst()` | Focuses the first enabled item. |
1407
- | `focusLast()` | Focuses the last enabled item. |
1748
+ | `select(name: string)` | Selects the tab for the given panel name. |
1408
1749
 
1409
1750
  #### Events
1410
1751
 
1411
1752
  | Event | Type | Description |
1412
1753
  |---|---|---|
1413
- | `uf-select` | `CustomEvent<MenuSelectDetail>` | An item was chosen. Cancel it to keep a dropdown open. |
1754
+ | `uf-tab-change` | `CustomEvent<TabChangeDetail>` | The selected tab changed. |
1414
1755
 
1415
1756
  #### Slots
1416
1757
 
1417
1758
  | Slot | Description |
1418
1759
  |---|---|
1419
- | (default) | `<uf-menu-item>` elements and `<hr>` separators. |
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. |
1420
1762
 
1421
- ### `<uf-menu-item>` API
1763
+ #### CSS parts
1764
+
1765
+ | Part | Description |
1766
+ |---|---|
1767
+ | `tablist` | The element with `role="tablist"`. |
1768
+ | `panels` | The wrapper around the panels. |
1769
+
1770
+ #### CSS custom properties
1771
+
1772
+ | Property | Description |
1773
+ |---|---|
1774
+ | `--uf-tabs-indicator-color` | Color of the selected tab's underline. |
1775
+
1776
+ ### `<uf-tab>` API
1422
1777
 
1423
1778
  #### Attributes and properties
1424
1779
 
1425
1780
  | Attribute | Property | Type | Default | Description |
1426
1781
  |---|---|---|---|---|
1427
- | `value` | | `string` | `''` | Identifies the item in the menu's `uf-select` event. |
1428
- | `type` | | `'normal' \| 'checkbox'` | `'normal'` | `checkbox` items toggle `checked` when selected. |
1429
- | `checked` | | `boolean` | `false` | Whether a checkbox item is on. |
1430
- | `disabled` | | `boolean` | `false` | Disables the item. |
1782
+ | `panel` | | `string` | `''` | Name of the `<uf-tab-panel>` this tab shows. |
1783
+ | `disabled` | | `boolean` | `false` | Disables the tab. |
1431
1784
 
1432
1785
  #### Slots
1433
1786
 
1434
1787
  | Slot | Description |
1435
1788
  |---|---|
1436
- | (default) | The label. |
1437
- | `prefix` | An icon before the label. |
1438
- | `suffix` | Trailing content, e.g. a keyboard shortcut. |
1789
+ | (default) | The tab label. |
1439
1790
 
1440
1791
  #### CSS parts
1441
1792
 
1442
1793
  | Part | Description |
1443
1794
  |---|---|
1444
- | `checkmark` | The check shown for checked checkbox items. |
1445
- | `label` | The label wrapper. |
1446
-
1447
- ## Tooltip
1448
-
1449
- A short label that appears on hover and keyboard focus. Wrap the element it
1450
- describes. The text is also set as the trigger's `aria-description` (unless it
1451
- repeats the trigger's own label), so screen reader users get it too. Don't put
1452
- interactive content in a tooltip.
1453
-
1454
- Tags: `<uf-tooltip>`. Import: `import '@unframed/core/tooltip';` (or `npx @unframed/cli add tooltip` to copy the source).
1455
-
1456
- ### On hover and focus
1457
-
1458
- ```html
1459
- <uf-tooltip content="Saves without publishing">
1460
- <uf-button variant="outline">Save draft</uf-button>
1461
- </uf-tooltip>
1462
- ```
1795
+ | `base` | The tab's inner wrapper. |
1463
1796
 
1464
- ### `<uf-tooltip>` API
1797
+ ### `<uf-tab-panel>` API
1465
1798
 
1466
1799
  #### Attributes and properties
1467
1800
 
1468
1801
  | Attribute | Property | Type | Default | Description |
1469
1802
  |---|---|---|---|---|
1470
- | `content` | | `string` | `''` | The tooltip text. |
1471
- | `placement` | | `Placement` | `'top'` | Preferred side. Flips when there is no room. |
1472
- | `disabled` | | `boolean` | `false` | Turns the tooltip off. |
1473
- | `delay` | | `number` | `300` | Milliseconds to wait on hover before showing. Focus shows it immediately. |
1474
- | `open` | | `boolean` | `false` | Whether the tooltip is showing. |
1475
-
1476
- #### Methods
1477
-
1478
- | Method | Description |
1479
- |---|---|
1480
- | `show()` | Shows the tooltip, unless it's disabled. |
1481
- | `hide()` | Hides the tooltip. |
1803
+ | `name` | | `string` | `''` | Name the matching tab refers to with `panel`. |
1482
1804
 
1483
1805
  #### Slots
1484
1806
 
1485
1807
  | Slot | Description |
1486
1808
  |---|---|
1487
- | (default) | The element the tooltip describes. |
1488
-
1489
- #### CSS parts
1490
-
1491
- | Part | Description |
1492
- |---|---|
1493
- | `body` | The tooltip bubble. |
1809
+ | (default) | The panel content. |
1494
1810
 
1495
1811
  #### CSS custom properties
1496
1812
 
1497
1813
  | Property | Description |
1498
1814
  |---|---|
1499
- | `--uf-tooltip-bg` | Background color. |
1500
- | `--uf-tooltip-color` | Text color. |
1501
- | `--uf-tooltip-max-width` | Maximum width. |
1502
-
1503
- ## Toast
1815
+ | `--uf-tab-panel-padding` | Padding around the content. |
1504
1816
 
1505
- The region that shows toasts. You rarely need to add it yourself: `toast()`
1506
- creates one on first use. Add it to choose a placement, or to hold
1507
- toasts in a specific place in the DOM.
1817
+ ## Textarea
1508
1818
 
1509
- Tags: `<uf-toaster>`. Import: `import '@unframed/core/toast';` (or `npx @unframed/cli add toast` to copy the source).
1819
+ A multi-line text field with a built-in label, hint and validation message.
1510
1820
 
1511
- ### Variants
1821
+ Tags: `<uf-textarea>`. Import: `import '@unframed/core/textarea';` (or `npx @unframed/cli add textarea` to copy the source).
1512
1822
 
1513
- Call `toast()` from anywhere; the toaster is created on first use.
1823
+ ### Grows with its content
1514
1824
 
1515
1825
  ```html
1516
- <script type="module">
1517
- import { toast } from '@unframed/core/toast';
1518
- toast('Changes published.', { variant: 'success' });
1519
- </script>
1826
+ <uf-textarea label="Bio" resize="auto" rows="2" maxlength="280" hint="Up to 280 characters."></uf-textarea>
1520
1827
  ```
1521
1828
 
1522
- ### `<uf-toaster>` API
1829
+ ### `<uf-textarea>` API
1523
1830
 
1524
1831
  #### Attributes and properties
1525
1832
 
1526
1833
  | Attribute | Property | Type | Default | Description |
1527
1834
  |---|---|---|---|---|
1528
- | `placement` | | `ToasterPlacement` | `'bottom-end'` | Corner or edge of the viewport where toasts appear. |
1529
- | `label` | | `string \| undefined` | | Accessible name of the notification region. Defaults to "Notifications", or its translation. |
1530
-
1531
- #### Methods
1532
-
1533
- | Method | Description |
1534
- |---|---|
1535
- | `add(message: string, options?: ToastOptions)` | Shows a toast in this region. Prefer the `toast()` function. |
1536
- | `dismiss(id: number)` | Hides a toast by id. |
1537
-
1538
- #### CSS parts
1539
-
1540
- | Part | Description |
1541
- |---|---|
1542
- | `region` | The list holding the toasts. |
1543
- | `toast` | Each toast. |
1544
- | `title` | A toast's title. |
1545
- | `message` | A toast's message. |
1546
- | `close-button` | A toast's dismiss button. |
1547
-
1548
- #### CSS custom properties
1549
-
1550
- | Property | Description |
1551
- |---|---|
1552
- | `--uf-toast-width` | Width of each toast. |
1553
- | `--uf-toaster-offset` | Distance from the viewport edges. |
1554
-
1555
- ## Icon
1556
-
1557
- An icon from the built-in set, or one added with `registerIcons()`.
1558
- Icons are decorative unless you give them a `label`.
1559
-
1560
- Tags: `<uf-icon>`. Import: `import '@unframed/core/icon';` (or `npx @unframed/cli add icon` to copy the source).
1561
-
1562
- ### Built-in set
1563
-
1564
- Icons are decorative unless you give them a `label`. Add your own with `registerIcons()`.
1565
-
1566
- ```html
1567
- <uf-icon name="check-circle" label="Done"></uf-icon>
1568
- ```
1569
-
1570
- ### Your own icons
1571
-
1572
- ```html
1573
- <script type="module">
1574
- import { registerIcons } from '@unframed/core/icon';
1575
-
1576
- registerIcons({
1577
- heart: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>',
1578
- star: '<svg viewBox="0 0 24 24" fill="currentColor">…</svg>',
1579
- });
1580
- </script>
1581
-
1582
- <uf-icon name="heart" label="Favorite"></uf-icon>
1583
- <uf-button><uf-icon slot="prefix" name="heart"></uf-icon>Save</uf-button>
1584
- ```
1585
-
1586
- - Use `currentColor` for strokes and fills, so the icon takes the text color around it (set `color` to change it).
1587
- - 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`.
1588
- - Registering a built-in name (e.g. `x`) replaces that icon everywhere, including inside components like the dialog's close button.
1589
- - Icons already on the page update when you register their name, so registration order doesn't matter.
1590
- - The markup is inserted as-is: only register SVG from your own code or files, never from user input.
1591
-
1592
- ### `<uf-icon>` API
1593
-
1594
- #### Attributes and properties
1595
-
1596
- | Attribute | Property | Type | Default | Description |
1597
- |---|---|---|---|---|
1598
- | `name` | | `BuiltInIconName \| (string & {})` | `''` | Icon name: a built-in icon or one added with `registerIcons()`. |
1599
- | `label` | | `string \| undefined` | | Accessible label. Without it the icon is hidden from assistive tech. |
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. |
1600
1849
 
1601
- #### CSS parts
1850
+ #### Properties only
1602
1851
 
1603
- | Part | Description |
1604
- |---|---|
1605
- | `svg` | The `<svg>` element. |
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. |
1606
1859
 
1607
- #### CSS custom properties
1860
+ #### Methods
1608
1861
 
1609
- | Property | Description |
1862
+ | Method | Description |
1610
1863
  |---|---|
1611
- | `--uf-icon-size` | Width and height. Defaults to `1em`, so it follows the font size. |
1612
- | `--uf-icon-stroke-width` | Stroke width of built-in icons. |
1613
-
1614
- ## Badge
1615
-
1616
- A short label for a status, a category or a count. It's plain text for
1617
- assistive tech: write text that makes sense out of context ("3 unread", not
1618
- just "3"), or describe it in the surrounding element's label.
1619
-
1620
- Tags: `<uf-badge>`. Import: `import '@unframed/core/badge';` (or `npx @unframed/cli add badge` to copy the source).
1621
-
1622
- ### Variants
1623
-
1624
- Six colors by meaning, in three appearances: `soft` (the default), `solid` and `outline`.
1625
-
1626
- ```html
1627
- <uf-badge>Draft</uf-badge>
1628
- <uf-badge variant="success">Paid</uf-badge>
1629
- <uf-badge variant="warning" appearance="solid">Expiring</uf-badge>
1630
- <uf-badge variant="info" appearance="outline">Beta</uf-badge>
1631
- ```
1632
-
1633
- ### Dot, icon and size
1634
-
1635
- ```html
1636
- <uf-badge dot variant="success">Online</uf-badge>
1637
- <uf-badge variant="success"><uf-icon slot="prefix" name="check-circle"></uf-icon>Verified</uf-badge>
1638
- <uf-badge size="sm" variant="accent">New</uf-badge>
1639
- ```
1640
-
1641
- - Badges are read as plain text: write "3 unread" rather than "3", so the badge makes sense on its own.
1642
-
1643
- ### `<uf-badge>` 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. |
1644
1868
 
1645
- #### Attributes and properties
1869
+ #### Events
1646
1870
 
1647
- | Attribute | Property | Type | Default | Description |
1648
- |---|---|---|---|---|
1649
- | `variant` | | `BadgeVariant` | `'neutral'` | Color, by meaning: `neutral`, `accent`, `info`, `success`, `warning` or `danger`. |
1650
- | `appearance` | | `BadgeAppearance` | `'soft'` | `soft` (tinted background), `solid` (bold background) or `outline` (border only). |
1651
- | `size` | | `BadgeSize` | `'md'` | Size: `sm` or `md`. |
1652
- | `dot` | | `boolean` | `false` | Shows a status dot before the text. |
1871
+ | Event | Type | Description |
1872
+ |---|---|---|
1873
+ | `input` | | Fired on every keystroke. |
1874
+ | `change` | `Event` | Fired when the value is committed (blur). |
1653
1875
 
1654
1876
  #### Slots
1655
1877
 
1656
1878
  | Slot | Description |
1657
1879
  |---|---|
1658
- | (default) | The badge text. |
1659
- | `prefix` | An icon before the text. |
1880
+ | `label` | The label, when you need markup. Overrides `label`. |
1881
+ | `hint` | Help text below the field. Overrides `hint`. |
1660
1882
 
1661
1883
  #### CSS parts
1662
1884
 
1663
1885
  | Part | Description |
1664
1886
  |---|---|
1665
- | `base` | The badge. |
1666
- | `dot` | The status dot, when `dot` is set. |
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. |
1667
1893
 
1668
1894
  #### CSS custom properties
1669
1895
 
1670
1896
  | Property | Description |
1671
1897
  |---|---|
1672
- | `--uf-badge-bg` | Background color. |
1673
- | `--uf-badge-color` | Text color. |
1674
- | `--uf-badge-border-color` | Border color. |
1675
- | `--uf-badge-radius` | Corner radius. Use `999px` for a pill. |
1676
-
1677
- ## Avatar
1678
-
1679
- A picture of a person or an entity. Shows the image when it loads, the
1680
- initials of `name` when there's no image or it fails, and a generic icon
1681
- when there's neither.
1682
-
1683
- `name` is also the accessible name. When the name is already written next
1684
- to the avatar, set `decorative` so screen readers don't read it twice.
1685
-
1686
- Tags: `<uf-avatar>`. Import: `import '@unframed/core/avatar';` (or `npx @unframed/cli add avatar` to copy the source).
1687
-
1688
- ### Image, initials or icon
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. |
1689
1901
 
1690
- The image when it loads, the initials of `name` when it doesn't, a generic icon when there's neither.
1902
+ ## Toast
1691
1903
 
1692
- ```html
1693
- <uf-avatar name="John Smith" src="/photos/john.jpg"></uf-avatar>
1694
- <uf-avatar name="John Smith"></uf-avatar>
1695
- <uf-avatar></uf-avatar>
1696
- ```
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.
1697
1907
 
1698
- ### Sizes and shapes
1908
+ Tags: `<uf-toaster>`. Import: `import '@unframed/core/toast';` (or `npx @unframed/cli add toast` to copy the source).
1699
1909
 
1700
- ```html
1701
- <uf-avatar size="sm" name="John Smith"></uf-avatar>
1702
- <uf-avatar size="xl" name="John Smith"></uf-avatar>
1703
- <uf-avatar size="xl" shape="square" name="Unframed" initials="U"></uf-avatar>
1704
- ```
1910
+ ### Variants
1705
1911
 
1706
- ### Next to a name
1912
+ Call `toast()` from anywhere; the toaster is created on first use.
1707
1913
 
1708
1914
  ```html
1709
- <uf-avatar name="John Smith" decorative></uf-avatar>
1710
- <strong>John Smith</strong>
1915
+ <script type="module">
1916
+ import { toast } from '@unframed/core/toast';
1917
+ toast('Changes published.', { variant: 'success' });
1918
+ </script>
1711
1919
  ```
1712
1920
 
1713
- - `name` is the accessible name. When the name is written next to the avatar, add `decorative` so screen readers don't read it twice.
1714
-
1715
- ### `<uf-avatar>` API
1921
+ ### `<uf-toaster>` API
1716
1922
 
1717
1923
  #### Attributes and properties
1718
1924
 
1719
1925
  | Attribute | Property | Type | Default | Description |
1720
1926
  |---|---|---|---|---|
1721
- | `src` | | `string \| undefined` | | Image URL. |
1722
- | `name` | | `string \| undefined` | | The person's or entity's name: the accessible name, and the source of the initials. |
1723
- | `initials` | | `string \| undefined` | | Initials to show instead of the ones taken from `name`. |
1724
- | `size` | | `AvatarSize` | `'md'` | Size: `sm`, `md`, `lg` or `xl`. |
1725
- | `shape` | | `AvatarShape` | `'circle'` | `circle` or `square` (rounded corners). |
1726
- | `decorative` | | `boolean` | `false` | Hides the avatar from assistive tech, when the name is already shown next to it. |
1727
- | `loading` | | `'eager' \| 'lazy'` | `'eager'` | The image's `loading` attribute: `lazy` waits until it's near the viewport. |
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. |
1728
1929
 
1729
- #### Slots
1930
+ #### Methods
1730
1931
 
1731
- | Slot | Description |
1932
+ | Method | Description |
1732
1933
  |---|---|
1733
- | (default) | Custom content instead of the initials or icon, e.g. an `<uf-icon>`. |
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. |
1734
1936
 
1735
1937
  #### CSS parts
1736
1938
 
1737
1939
  | Part | Description |
1738
1940
  |---|---|
1739
- | `base` | The avatar. |
1740
- | `image` | The `<img>`. |
1741
- | `initials` | The initials. |
1742
- | `icon` | The fallback icon. |
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. |
1743
1946
 
1744
1947
  #### CSS custom properties
1745
1948
 
1746
1949
  | Property | Description |
1747
1950
  |---|---|
1748
- | `--uf-avatar-size` | Width and height. Overrides `size`. |
1749
- | `--uf-avatar-bg` | Background behind initials and icon. |
1750
- | `--uf-avatar-color` | Color of the initials and icon. |
1751
- | `--uf-avatar-radius` | Corner radius. Overrides `shape`. |
1752
-
1753
- ## Card
1754
-
1755
- A container that groups related content: an optional image, a header, the
1756
- content and actions. Empty sections take no space.
1757
-
1758
- A card is a plain container for assistive tech. To make a whole card a link,
1759
- put a link in the header and let it cover the card with CSS, so the card's
1760
- buttons stay usable.
1761
-
1762
- Tags: `<uf-card>`. Import: `import '@unframed/core/card';` (or `npx @unframed/cli add card` to copy the source).
1951
+ | `--uf-toast-width` | Width of each toast. |
1952
+ | `--uf-toaster-offset` | Distance from the viewport edges. |
1763
1953
 
1764
- ### Media, header, content and footer
1954
+ ## Tooltip
1765
1955
 
1766
- Every section is optional; empty ones take no space.
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.
1767
1960
 
1768
- ```html
1769
- <uf-card>
1770
- <img slot="media" src="/cover.png" alt="The Unframed logo" />
1771
- <div slot="header">
1772
- <h3>Unframed 0.2</h3>
1773
- <small>Released this week</small>
1774
- </div>
1775
- A link button variant, new colors and smaller Angular bundles.
1776
- <uf-button slot="footer">Read more</uf-button>
1777
- <uf-button slot="footer" variant="ghost">Dismiss</uf-button>
1778
- </uf-card>
1779
- ```
1961
+ Tags: `<uf-tooltip>`. Import: `import '@unframed/core/tooltip';` (or `npx @unframed/cli add tooltip` to copy the source).
1780
1962
 
1781
- ### Variants and orientation
1963
+ ### On hover and focus
1782
1964
 
1783
1965
  ```html
1784
- <uf-card variant="elevated">…</uf-card>
1785
- <uf-card variant="filled">…</uf-card>
1786
- <uf-card orientation="horizontal">
1787
- <img slot="media" src="/cover.png" alt="" />
1788
- Media beside the content.
1789
- </uf-card>
1966
+ <uf-tooltip content="Saves without publishing">
1967
+ <uf-button variant="outline">Save draft</uf-button>
1968
+ </uf-tooltip>
1790
1969
  ```
1791
1970
 
1792
- ### `<uf-card>` API
1971
+ ### `<uf-tooltip>` API
1793
1972
 
1794
1973
  #### Attributes and properties
1795
1974
 
1796
1975
  | Attribute | Property | Type | Default | Description |
1797
1976
  |---|---|---|---|---|
1798
- | `variant` | | `CardVariant` | `'outline'` | `outline` (a border), `elevated` (a shadow, or an accent glow in dark mode) or `filled` (a tinted background). |
1799
- | `orientation` | | `CardOrientation` | `'vertical'` | `vertical`, or `horizontal` to put the media beside the content. |
1800
-
1801
- #### Slots
1802
-
1803
- | Slot | Description |
1804
- |---|---|
1805
- | (default) | The main content. |
1806
- | `media` | An image or video, edge to edge at the top (or the start, when horizontal). |
1807
- | `header` | The title area, e.g. a heading and a subtitle. |
1808
- | `footer` | Actions or details at the bottom. |
1809
-
1810
- #### CSS parts
1811
-
1812
- | Part | Description |
1813
- |---|---|
1814
- | `base` | The card. |
1815
- | `media` | The media wrapper. |
1816
- | `header` | The header wrapper. |
1817
- | `body` | The main content wrapper. |
1818
- | `footer` | The footer wrapper. |
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. |
1819
1982
 
1820
- #### CSS custom properties
1983
+ #### Methods
1821
1984
 
1822
- | Property | Description |
1985
+ | Method | Description |
1823
1986
  |---|---|
1824
- | `--uf-card-padding` | Padding of header, body and footer. |
1825
- | `--uf-card-bg` | Background color. |
1826
- | `--uf-card-border-color` | Border color. |
1827
- | `--uf-card-radius` | Corner radius. |
1828
- | `--uf-card-shadow` | Shadow of an elevated card. Defaults to a soft shadow in light mode and an accent glow in dark mode. |
1829
- | `--uf-card-media-width` | Width of the media in a horizontal card. Defaults to 40%. |
1830
-
1831
- ## Table
1832
-
1833
- A table of data, from `columns` and `rows`. Users can sort by the columns
1834
- marked `sortable`. Rendered as a native `<table>`, so assistive tech reads
1835
- headers and cells as usual.
1836
-
1837
- Set `columns` and `rows` as properties, or as JSON attributes in plain HTML.
1838
- The table sorts `rows` itself; with `manual-sort` it only shows the order
1839
- and tells you, so you can sort on the server. Combine it with
1840
- `<uf-pagination>` for long lists.
1841
-
1842
- Tags: `<uf-table>`. Import: `import '@unframed/core/table';` (or `npx @unframed/cli add table` to copy the source).
1843
-
1844
- ### Columns, rows and sorting
1845
-
1846
- Describe the columns and pass the rows. Columns marked `sortable` sort on click.
1847
-
1848
- ```html
1849
- <uf-table
1850
- label="Team"
1851
- columns='[{"key": "name", "label": "Name", "sortable": true},
1852
- {"key": "role", "label": "Role"},
1853
- {"key": "commits", "label": "Commits", "sortable": true, "align": "end"}]'
1854
- rows='[{"name": "John Smith", "role": "Product designer", "commits": 412},
1855
- {"name": "Jane Doe", "role": "Engineer", "commits": 1290}]'
1856
- ></uf-table>
1857
- ```
1858
-
1859
- - In plain HTML, `columns` and `rows` can be JSON attributes. From JavaScript, set them as properties.
1860
- - Give the table a `label`: it names the table for screen readers.
1861
-
1862
- ### Formatting, and pages
1863
-
1864
- `format` turns a value into text or a DOM node, like a badge. Sorting still uses the raw values.
1865
-
1866
- ```html
1867
- <uf-table id="invoices" label="Invoices" row-key="id"></uf-table>
1868
- <uf-pagination id="pages" label="Invoice pages"></uf-pagination>
1869
-
1870
- <script type="module">
1871
- const table = document.querySelector('#invoices');
1872
- const pages = document.querySelector('#pages');
1873
- const pageSize = 8;
1874
-
1875
- table.columns = [
1876
- { key: 'customer', label: 'Customer', sortable: true },
1877
- { key: 'amount', label: 'Amount', sortable: true, align: 'end',
1878
- format: (value) => euro.format(value) },
1879
- ];
1880
- pages.pages = Math.ceil(invoices.length / pageSize);
1881
-
1882
- const show = (page) => (table.rows = invoices.slice((page - 1) * pageSize, page * pageSize));
1883
- pages.addEventListener('uf-page-change', (event) => show(event.detail.page));
1884
- show(1);
1885
- </script>
1886
- ```
1887
-
1888
- - 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.
1889
- - Set `--uf-table-max-height` to scroll long tables under a sticky header.
1890
-
1891
- ### `<uf-table>` API
1892
-
1893
- #### Attributes and properties
1894
-
1895
- | Attribute | Property | Type | Default | Description |
1896
- |---|---|---|---|---|
1897
- | `columns` | | `TableColumn[]` | `[]` | The columns, in order. As an attribute, JSON: `[{"key": "name", "label": "Name"}]`. |
1898
- | `rows` | | `TableRow[]` | `[]` | The data, one object per row. As an attribute, JSON: `[{"name": "John"}]`. |
1899
- | `label` | | `string \| undefined` | | Accessible name of the table, e.g. "Invoices". |
1900
- | `sort-key` | `sortKey` | `string \| undefined` | | Key of the column the rows are sorted by. |
1901
- | `sort-direction` | `sortDirection` | `SortDirection` | `'ascending'` | Sort order: `ascending` or `descending`. |
1902
- | `manual-sort` | `manualSort` | `boolean` | `false` | Doesn't sort the rows: only shows the sort and fires `uf-sort`, for sorting on the server. |
1903
- | `row-key` | `rowKey` | `string \| undefined` | | Row property that identifies each row, so rows keep their DOM when the data changes. Defaults to the index. |
1904
- | `striped` | | `boolean` | `false` | Shades every other row. |
1905
- | `density` | | `TableDensity` | `'comfortable'` | Row spacing: `comfortable` or `compact`. |
1906
-
1907
- #### Events
1908
-
1909
- | Event | Type | Description |
1910
- |---|---|---|
1911
- | `uf-sort` | `CustomEvent<TableSortDetail>` | The user sorted by a column. |
1987
+ | `show()` | Shows the tooltip, unless it's disabled. |
1988
+ | `hide()` | Hides the tooltip. |
1912
1989
 
1913
1990
  #### Slots
1914
1991
 
1915
1992
  | Slot | Description |
1916
1993
  |---|---|
1917
- | `empty` | Shown when there are no rows. Defaults to "No data", or its translation. |
1918
-
1919
- #### CSS parts
1920
-
1921
- | Part | Description |
1922
- |---|---|
1923
- | `base` | The scroll container around the table. |
1924
- | `table` | The `<table>`. |
1925
- | `header-cell` | Every header cell (`<th>`). |
1926
- | `sort-button` | The button in a sortable header. |
1927
- | `row` | Every body row. |
1928
- | `cell` | Every body cell. |
1929
- | `empty` | The cell shown when there are no rows. |
1930
-
1931
- #### CSS custom properties
1932
-
1933
- | Property | Description |
1934
- |---|---|
1935
- | `--uf-table-max-height` | Height after which the body scrolls under a sticky header. |
1936
- | `--uf-table-border-color` | Border color between rows. |
1937
- | `--uf-table-header-bg` | Background of the header row. |
1938
- | `--uf-table-stripe-bg` | Background of every other row, with `striped`. |
1939
- | `--uf-table-hover-bg` | Background of the row under the pointer. |
1940
-
1941
- ## Pagination
1942
-
1943
- Navigation between the pages of a list or table. Set `pages` and `page`; the
1944
- user changes `page`, and `uf-page-change` tells you which page to show.
1945
-
1946
- It's a navigation landmark: when a page has more than one, give each a
1947
- different `label`.
1948
-
1949
- Tags: `<uf-pagination>`. Import: `import '@unframed/core/pagination';` (or `npx @unframed/cli add pagination` to copy the source).
1950
-
1951
- ### Pages
1952
-
1953
- Long ranges collapse around the current page; the number of buttons stays the same from page to page.
1954
-
1955
- ```html
1956
- <uf-pagination pages="20" page="6"></uf-pagination>
1957
-
1958
- <script type="module">
1959
- document.querySelector('uf-pagination').addEventListener('uf-page-change', (event) => {
1960
- loadPage(event.detail.page);
1961
- });
1962
- </script>
1963
- ```
1964
-
1965
- ### Siblings and size
1966
-
1967
- ```html
1968
- <uf-pagination pages="30" page="15" siblings="2"></uf-pagination>
1969
- <uf-pagination pages="30" page="15" size="sm"></uf-pagination>
1970
- ```
1971
-
1972
- - Each pagination is a navigation landmark: when a page has more than one, give each a different `label`.
1973
-
1974
- ### `<uf-pagination>` API
1975
-
1976
- #### Attributes and properties
1977
-
1978
- | Attribute | Property | Type | Default | Description |
1979
- |---|---|---|---|---|
1980
- | `page` | | `number` | `1` | The current page, from 1. |
1981
- | `pages` | | `number` | `1` | How many pages there are. |
1982
- | `siblings` | | `number` | `1` | How many pages to show on each side of the current one. |
1983
- | `label` | | `string \| undefined` | | Accessible name of the navigation, e.g. "Search results pages". Defaults to "Pagination", or its translation. |
1984
- | `size` | | `PaginationSize` | `'md'` | Size: `sm` or `md`. |
1985
-
1986
- #### Events
1987
-
1988
- | Event | Type | Description |
1989
- |---|---|---|
1990
- | `uf-page-change` | `CustomEvent<PageChangeDetail>` | The user chose another page. |
1994
+ | (default) | The element the tooltip describes. |
1991
1995
 
1992
1996
  #### CSS parts
1993
1997
 
1994
1998
  | Part | Description |
1995
1999
  |---|---|
1996
- | `base` | The `<nav>`. |
1997
- | `list` | The list of buttons. |
1998
- | `button` | Every button: pages, previous and next. |
1999
- | `current` | The current page's button. |
2000
- | `previous` | The previous button. |
2001
- | `next` | The next button. |
2002
- | `ellipsis` | The "…" between pages. |
2000
+ | `body` | The tooltip bubble. |
2003
2001
 
2004
2002
  #### CSS custom properties
2005
2003
 
2006
2004
  | Property | Description |
2007
2005
  |---|---|
2008
- | `--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. |