@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.
@@ -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.3.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.
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.3.0 components
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` | `'Notifications'` | Accessible name of the notification region. |
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` | `'Pagination'` | Accessible name of the navigation, e.g. "Search results pages". |
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
@@ -1,4 +1,4 @@
1
- # Using Unframed 0.3.0 in each framework
1
+ # Using Unframed 0.5.0 in each framework
2
2
 
3
3
  ## HTML & JavaScript
4
4