@unframed/cli 0.2.0 → 0.4.0

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