@unframed/cli 0.3.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/skill/unframed/SKILL.md
CHANGED
|
@@ -5,7 +5,7 @@ description: Builds UI with Unframed web components (@unframed/core, @unframed/r
|
|
|
5
5
|
|
|
6
6
|
# Unframed UI
|
|
7
7
|
|
|
8
|
-
Unframed 0.
|
|
8
|
+
Unframed 0.5.0: accessible UI components as standard custom elements (Lit). Every tag starts with `uf-`. They work in plain HTML and every framework; React, Vue and Angular have wrapper packages for typed props, events and form bindings.
|
|
9
9
|
|
|
10
10
|
## Before writing code
|
|
11
11
|
|
|
@@ -26,6 +26,7 @@ Unframed 0.3.0: accessible UI components as standard custom elements (Lit). Ever
|
|
|
26
26
|
- **Dialogs.** Open with `open` or `.show()`; any child with `data-dialog="close"` closes it; cancel a close in `uf-request-close` with `preventDefault()`.
|
|
27
27
|
- **Toasts.** `import { toast } from '@unframed/core'` and call `toast('Saved', { variant: 'success' })`; no element needed.
|
|
28
28
|
- **Theming.** Change colors and shapes with `--uf-*` custom properties (global tokens, then per-component ones like `--uf-button-radius`), then `::part()`. Don't style internals any other way, and don't re-implement a component that exists. See [references/theming.md](references/theming.md).
|
|
29
|
+
- **Translations.** Built-in texts (dialog close button, "No results", pagination labels, a few error messages) are English. Translate them with `setTranslations({ close: 'Chiudi', page: 'Pagina {page}' }, 'it')` from `@unframed/core`, once at startup; components follow the nearest `lang` attribute. Don't add `aria-label`s to override them.
|
|
29
30
|
- **Dark mode** follows the OS; force it with `data-uf-theme="dark"` (or `"light"`) on any element.
|
|
30
31
|
|
|
31
32
|
## Components
|
|
@@ -37,6 +38,7 @@ Unframed 0.3.0: accessible UI components as standard custom elements (Lit). Ever
|
|
|
37
38
|
| Textarea: Lets users enter multiple lines of text. | `<uf-textarea>` | `@unframed/core/textarea` |
|
|
38
39
|
| Select: Lets users pick one option from a dropdown list. | `<uf-select>` | `@unframed/core/select` |
|
|
39
40
|
| Combobox: Lets users search a list and pick one option. | `<uf-combobox>` | `@unframed/core/combobox` |
|
|
41
|
+
| Date picker: Lets users type or pick a date. | `<uf-date-picker>` `<uf-calendar>` | `@unframed/core/date-picker` `@unframed/core/calendar` |
|
|
40
42
|
| Checkbox: Lets users turn an option on or off, or pick several options. | `<uf-checkbox>` `<uf-checkbox-group>` | `@unframed/core/checkbox` `@unframed/core/checkbox-group` |
|
|
41
43
|
| Switch: Turns a setting on or off. | `<uf-switch>` | `@unframed/core/switch` |
|
|
42
44
|
| Radio group: Lets users pick exactly one option from a list. | `<uf-radio-group>` `<uf-radio>` | `@unframed/core/radio-group` `@unframed/core/radio` |
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Unframed 0.
|
|
1
|
+
# Unframed 0.5.0 components
|
|
2
2
|
|
|
3
3
|
## Button
|
|
4
4
|
|
|
@@ -462,6 +462,183 @@ Type to filter, arrow keys to move, Enter to pick.
|
|
|
462
462
|
|---|---|
|
|
463
463
|
| `--uf-combobox-max-height` | Maximum height of the list before it scrolls. |
|
|
464
464
|
|
|
465
|
+
## Date picker
|
|
466
|
+
|
|
467
|
+
A date field: type a date in the page language's format, or pick one from a
|
|
468
|
+
calendar. The value is always `YYYY-MM-DD`, like `<input type="date">`, so
|
|
469
|
+
it's the same in every language and submits with the form.
|
|
470
|
+
|
|
471
|
+
Alt + Down Arrow opens the calendar; Escape closes it.
|
|
472
|
+
|
|
473
|
+
Tags: `<uf-date-picker>`, `<uf-calendar>`. Import: `import '@unframed/core/date-picker';`, `import '@unframed/core/calendar';` (or `npx @unframed/cli add date-picker calendar` to copy the source).
|
|
474
|
+
|
|
475
|
+
### Type or pick a date
|
|
476
|
+
|
|
477
|
+
Type a date in the page language's format, or open the calendar. The value is always `YYYY-MM-DD`.
|
|
478
|
+
|
|
479
|
+
```html
|
|
480
|
+
<uf-date-picker label="Check-in" hint="From 3 pm" name="checkin" min="2026-10-14" required></uf-date-picker>
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
- Arrow keys move by day and week, Page Up and Page Down by month (with Shift, by year). Alt + Down Arrow opens the calendar, Escape closes it.
|
|
484
|
+
- The format, month names and first day of the week follow the nearest `lang` attribute: `14/10/2026` in Italian, `10/14/2026` in US English.
|
|
485
|
+
- Typed text that isn't a date stays in the field with an error, so the user can fix it.
|
|
486
|
+
|
|
487
|
+
### Disabled dates
|
|
488
|
+
|
|
489
|
+
`min` and `max` limit the range; `isDateDisabled` rules out single dates, like weekends.
|
|
490
|
+
|
|
491
|
+
```html
|
|
492
|
+
<uf-date-picker id="delivery" label="Delivery day" hint="Weekdays only"></uf-date-picker>
|
|
493
|
+
|
|
494
|
+
<script type="module">
|
|
495
|
+
// A property, not an attribute: it's a function.
|
|
496
|
+
document.querySelector('#delivery').isDateDisabled = (date) =>
|
|
497
|
+
[0, 6].includes(new Date(date).getUTCDay());
|
|
498
|
+
</script>
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
### Calendar on its own
|
|
502
|
+
|
|
503
|
+
`<uf-calendar>` is the grid inside the picker. Use it inline, e.g. on a booking page.
|
|
504
|
+
|
|
505
|
+
```html
|
|
506
|
+
<uf-calendar value="2026-10-14"></uf-calendar>
|
|
507
|
+
|
|
508
|
+
<script type="module">
|
|
509
|
+
document.querySelector('uf-calendar').addEventListener('change', (event) => {
|
|
510
|
+
console.log(event.target.value); // "2026-10-21"
|
|
511
|
+
});
|
|
512
|
+
</script>
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
### `<uf-date-picker>` API
|
|
516
|
+
|
|
517
|
+
#### Attributes and properties
|
|
518
|
+
|
|
519
|
+
| Attribute | Property | Type | Default | Description |
|
|
520
|
+
|---|---|---|---|---|
|
|
521
|
+
| `value` | `defaultValue` | `string` | `''` | Initial date, restored on form reset. Set with the `value` attribute, as `YYYY-MM-DD`. |
|
|
522
|
+
| `label` | | `string \| undefined` | | The field's label, also its accessible name. |
|
|
523
|
+
| `hint` | | `string \| undefined` | | Help text below the field. |
|
|
524
|
+
| `placeholder` | | `string \| undefined` | | Shown when empty. Defaults to the date format, e.g. dd/mm/yyyy. |
|
|
525
|
+
| `size` | | `FieldSize` | `'md'` | Size: `sm`, `md` or `lg`. |
|
|
526
|
+
| `min` | | `string \| undefined` | | The earliest allowed date, as `YYYY-MM-DD`. |
|
|
527
|
+
| `max` | | `string \| undefined` | | The latest allowed date, as `YYYY-MM-DD`. |
|
|
528
|
+
| `readonly` | | `boolean` | `false` | Lets the user select the text but not change the date. |
|
|
529
|
+
| `open` | | `boolean` | `false` | Whether the calendar is open. |
|
|
530
|
+
| `name` | | `string` | `''` | Name submitted with the form. |
|
|
531
|
+
| `disabled` | | `boolean` | `false` | Disables the control. |
|
|
532
|
+
| `required` | | `boolean` | `false` | Makes the control required for form submission. |
|
|
533
|
+
|
|
534
|
+
#### Properties only
|
|
535
|
+
|
|
536
|
+
| Property | Type | Description |
|
|
537
|
+
|---|---|---|
|
|
538
|
+
| `value` | `string` | The date, as `YYYY-MM-DD`, or an empty string. |
|
|
539
|
+
| `isDateDisabled` | `((date: string) => boolean) \| undefined` | Rules out dates, e.g. weekends: called with each date as `YYYY-MM-DD`, returns true to disable it. |
|
|
540
|
+
| `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
|
|
541
|
+
| `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
|
|
542
|
+
| `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
|
|
543
|
+
| `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
|
|
544
|
+
|
|
545
|
+
#### Methods
|
|
546
|
+
|
|
547
|
+
| Method | Description |
|
|
548
|
+
|---|---|
|
|
549
|
+
| `show()` | Opens the calendar. |
|
|
550
|
+
| `hide()` | Closes the calendar. |
|
|
551
|
+
| `checkValidity()` | Returns whether the value is valid, without showing an error. |
|
|
552
|
+
| `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
|
|
553
|
+
| `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
|
|
554
|
+
|
|
555
|
+
#### Events
|
|
556
|
+
|
|
557
|
+
| Event | Type | Description |
|
|
558
|
+
|---|---|---|
|
|
559
|
+
| `input` | `Event` | The value changed (a date was typed and committed, or picked). |
|
|
560
|
+
| `change` | `Event` | The value changed (a date was typed and committed, or picked). |
|
|
561
|
+
| `uf-show` | | The calendar opened. |
|
|
562
|
+
| `uf-hide` | | The calendar closed. |
|
|
563
|
+
|
|
564
|
+
#### Slots
|
|
565
|
+
|
|
566
|
+
| Slot | Description |
|
|
567
|
+
|---|---|
|
|
568
|
+
| `label` | The label, when you need markup. Overrides `label`. |
|
|
569
|
+
| `hint` | Help text below the field. Overrides `hint`. |
|
|
570
|
+
|
|
571
|
+
#### CSS parts
|
|
572
|
+
|
|
573
|
+
| Part | Description |
|
|
574
|
+
|---|---|
|
|
575
|
+
| `field` | The wrapper around label, control, hint and error. |
|
|
576
|
+
| `form-label` | The label. |
|
|
577
|
+
| `box` | The bordered box around the input. |
|
|
578
|
+
| `input` | The text input. |
|
|
579
|
+
| `toggle` | The calendar button. |
|
|
580
|
+
| `popup` | The floating panel around the calendar. |
|
|
581
|
+
| `calendar` | The `<uf-calendar>`. |
|
|
582
|
+
| `hint` | The hint text. |
|
|
583
|
+
| `error` | The validation message. |
|
|
584
|
+
|
|
585
|
+
#### CSS custom properties
|
|
586
|
+
|
|
587
|
+
| Property | Description |
|
|
588
|
+
|---|---|
|
|
589
|
+
| `--uf-field-bg` | Background of the box. |
|
|
590
|
+
| `--uf-field-border-color` | Border color of the box. |
|
|
591
|
+
| `--uf-field-radius` | Corner radius of the box. |
|
|
592
|
+
|
|
593
|
+
### `<uf-calendar>` API
|
|
594
|
+
|
|
595
|
+
#### Attributes and properties
|
|
596
|
+
|
|
597
|
+
| Attribute | Property | Type | Default | Description |
|
|
598
|
+
|---|---|---|---|---|
|
|
599
|
+
| `value` | | `string` | `''` | The selected date, as `YYYY-MM-DD`, or an empty string. |
|
|
600
|
+
| `min` | | `string \| undefined` | | The earliest date that can be picked, as `YYYY-MM-DD`. |
|
|
601
|
+
| `max` | | `string \| undefined` | | The latest date that can be picked, as `YYYY-MM-DD`. |
|
|
602
|
+
| `first-day-of-week` | `firstDayOfWeek` | `number \| undefined` | | First day of the week: 0 Sunday … 6 Saturday. Defaults to the language's. |
|
|
603
|
+
|
|
604
|
+
#### Properties only
|
|
605
|
+
|
|
606
|
+
| Property | Type | Description |
|
|
607
|
+
|---|---|---|
|
|
608
|
+
| `isDateDisabled` | `((date: string) => boolean) \| undefined` | Rules out dates, e.g. weekends: called with each date as `YYYY-MM-DD`, returns true to disable it. |
|
|
609
|
+
|
|
610
|
+
#### Methods
|
|
611
|
+
|
|
612
|
+
| Method | Description |
|
|
613
|
+
|---|---|
|
|
614
|
+
| `focus(options: FocusOptions)` | Moves keyboard focus to the selected day, or today. |
|
|
615
|
+
|
|
616
|
+
#### Events
|
|
617
|
+
|
|
618
|
+
| Event | Type | Description |
|
|
619
|
+
|---|---|---|
|
|
620
|
+
| `change` | `Event` | The user picked a date. Read it from `value`. |
|
|
621
|
+
|
|
622
|
+
#### CSS parts
|
|
623
|
+
|
|
624
|
+
| Part | Description |
|
|
625
|
+
|---|---|
|
|
626
|
+
| `base` | The calendar. |
|
|
627
|
+
| `header` | The month title and the previous and next buttons. |
|
|
628
|
+
| `title` | The month and year. |
|
|
629
|
+
| `nav-button` | The previous and next month buttons. |
|
|
630
|
+
| `grid` | The `<table>` of days. |
|
|
631
|
+
| `weekday` | A weekday heading. |
|
|
632
|
+
| `day` | Every day. |
|
|
633
|
+
| `selected` | The selected day. |
|
|
634
|
+
| `today` | Today. |
|
|
635
|
+
|
|
636
|
+
#### CSS custom properties
|
|
637
|
+
|
|
638
|
+
| Property | Description |
|
|
639
|
+
|---|---|
|
|
640
|
+
| `--uf-calendar-day-size` | Width and height of a day. |
|
|
641
|
+
|
|
465
642
|
## Checkbox
|
|
466
643
|
|
|
467
644
|
A checkbox with its label as content.
|
|
@@ -1349,7 +1526,7 @@ Call `toast()` from anywhere; the toaster is created on first use.
|
|
|
1349
1526
|
| Attribute | Property | Type | Default | Description |
|
|
1350
1527
|
|---|---|---|---|---|
|
|
1351
1528
|
| `placement` | | `ToasterPlacement` | `'bottom-end'` | Corner or edge of the viewport where toasts appear. |
|
|
1352
|
-
| `label` | | `string
|
|
1529
|
+
| `label` | | `string \| undefined` | | Accessible name of the notification region. Defaults to "Notifications", or its translation. |
|
|
1353
1530
|
|
|
1354
1531
|
#### Methods
|
|
1355
1532
|
|
|
@@ -1618,7 +1795,7 @@ Every section is optional; empty ones take no space.
|
|
|
1618
1795
|
|
|
1619
1796
|
| Attribute | Property | Type | Default | Description |
|
|
1620
1797
|
|---|---|---|---|---|
|
|
1621
|
-
| `variant` | | `CardVariant` | `'outline'` | `outline` (a border), `elevated` (a shadow) or `filled` (a tinted background). |
|
|
1798
|
+
| `variant` | | `CardVariant` | `'outline'` | `outline` (a border), `elevated` (a shadow, or an accent glow in dark mode) or `filled` (a tinted background). |
|
|
1622
1799
|
| `orientation` | | `CardOrientation` | `'vertical'` | `vertical`, or `horizontal` to put the media beside the content. |
|
|
1623
1800
|
|
|
1624
1801
|
#### Slots
|
|
@@ -1648,6 +1825,7 @@ Every section is optional; empty ones take no space.
|
|
|
1648
1825
|
| `--uf-card-bg` | Background color. |
|
|
1649
1826
|
| `--uf-card-border-color` | Border color. |
|
|
1650
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. |
|
|
1651
1829
|
| `--uf-card-media-width` | Width of the media in a horizontal card. Defaults to 40%. |
|
|
1652
1830
|
|
|
1653
1831
|
## Table
|
|
@@ -1736,7 +1914,7 @@ Describe the columns and pass the rows. Columns marked `sortable` sort on click.
|
|
|
1736
1914
|
|
|
1737
1915
|
| Slot | Description |
|
|
1738
1916
|
|---|---|
|
|
1739
|
-
| `empty` | Shown when there are no rows. Defaults to "No data". |
|
|
1917
|
+
| `empty` | Shown when there are no rows. Defaults to "No data", or its translation. |
|
|
1740
1918
|
|
|
1741
1919
|
#### CSS parts
|
|
1742
1920
|
|
|
@@ -1802,7 +1980,7 @@ Long ranges collapse around the current page; the number of buttons stays the sa
|
|
|
1802
1980
|
| `page` | | `number` | `1` | The current page, from 1. |
|
|
1803
1981
|
| `pages` | | `number` | `1` | How many pages there are. |
|
|
1804
1982
|
| `siblings` | | `number` | `1` | How many pages to show on each side of the current one. |
|
|
1805
|
-
| `label` | | `string
|
|
1983
|
+
| `label` | | `string \| undefined` | | Accessible name of the navigation, e.g. "Search results pages". Defaults to "Pagination", or its translation. |
|
|
1806
1984
|
| `size` | | `PaginationSize` | `'md'` | Size: `sm` or `md`. |
|
|
1807
1985
|
|
|
1808
1986
|
#### Events
|