@unframed/cli 0.12.0 → 0.13.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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.13.1: 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
|
|
|
@@ -49,14 +49,17 @@ Unframed 0.12.0: accessible UI components as standard custom elements (Lit). Eve
|
|
|
49
49
|
| Divider: Separates groups of content with a line. | `<uf-divider>` | `@unframed/core/divider` |
|
|
50
50
|
| Drawer: A panel that slides in from an edge of the screen. | `<uf-drawer>` | `@unframed/core/drawer` |
|
|
51
51
|
| Dropdown menu: Opens a menu of actions from a button. | `<uf-dropdown>` `<uf-menu>` `<uf-menu-item>` | `@unframed/core/dropdown` `@unframed/core/menu` |
|
|
52
|
+
| Empty state: Fills an empty list or page with a message and what to do next. | `<uf-empty-state>` | `@unframed/core/empty-state` |
|
|
52
53
|
| File upload: Lets users choose files to upload. | `<uf-file-upload>` | `@unframed/core/file-upload` |
|
|
53
54
|
| Icon: Shows a small symbol. | `<uf-icon>` | `@unframed/core/icon` |
|
|
54
55
|
| Input: Lets users enter a single line of text. | `<uf-input>` | `@unframed/core/input` |
|
|
56
|
+
| Multi-select: Lets users search a list and pick several options. | `<uf-multi-select>` | `@unframed/core/multi-select` |
|
|
55
57
|
| Number input: Lets users enter a number, or step it with buttons. | `<uf-number-input>` | `@unframed/core/number-input` |
|
|
56
58
|
| Pagination: Moves between the pages of a long list. | `<uf-pagination>` | `@unframed/core/pagination` |
|
|
57
59
|
| Popover: Shows floating content next to a trigger. | `<uf-popover>` | `@unframed/core/popover` |
|
|
58
60
|
| Progress: Shows how far a task has got. | `<uf-progress>` | `@unframed/core/progress` |
|
|
59
61
|
| Radio group: Lets users pick exactly one option from a list. | `<uf-radio-group>` `<uf-radio>` | `@unframed/core/radio-group` `@unframed/core/radio` |
|
|
62
|
+
| Segmented control: Picks one of a few options, side by side. | `<uf-segmented-control>` | `@unframed/core/segmented-control` |
|
|
60
63
|
| Select: Lets users pick one option from a dropdown list. | `<uf-select>` | `@unframed/core/select` |
|
|
61
64
|
| Skeleton: Holds the place of content while it loads. | `<uf-skeleton>` | `@unframed/core/skeleton` |
|
|
62
65
|
| Slider: Lets users pick a number in a range. | `<uf-slider>` | `@unframed/core/slider` |
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Unframed 0.
|
|
1
|
+
# Unframed 0.13.1 components
|
|
2
2
|
|
|
3
3
|
## Accordion
|
|
4
4
|
|
|
@@ -1572,6 +1572,75 @@ Arrow keys move, typing a letter jumps to an item, Escape closes.
|
|
|
1572
1572
|
| `checkmark` | The check shown for checked checkbox items. |
|
|
1573
1573
|
| `label` | The label wrapper. |
|
|
1574
1574
|
|
|
1575
|
+
## Empty state
|
|
1576
|
+
|
|
1577
|
+
What to show where content would be: an empty list, no search results, a
|
|
1578
|
+
first visit. An icon, a heading, a short explanation and what to do next.
|
|
1579
|
+
|
|
1580
|
+
The `heading` attribute is bold text. For a real heading in the page's
|
|
1581
|
+
outline, put an `<h2>` or `<h3>` in the `heading` slot.
|
|
1582
|
+
|
|
1583
|
+
Tags: `<uf-empty-state>`. Import: `import '@unframed/core/empty-state';` (or `npx @unframed/cli add empty-state` to copy the source).
|
|
1584
|
+
|
|
1585
|
+
### Basic
|
|
1586
|
+
|
|
1587
|
+
An icon, a heading, a short explanation and what to do next.
|
|
1588
|
+
|
|
1589
|
+
```html
|
|
1590
|
+
<uf-empty-state heading="No projects yet">
|
|
1591
|
+
Projects keep your files and your team together.
|
|
1592
|
+
<uf-button slot="actions">New project</uf-button>
|
|
1593
|
+
</uf-empty-state>
|
|
1594
|
+
```
|
|
1595
|
+
|
|
1596
|
+
### No search results
|
|
1597
|
+
|
|
1598
|
+
Another `icon`, and a real heading in the `heading` slot when it belongs in the page outline.
|
|
1599
|
+
|
|
1600
|
+
```html
|
|
1601
|
+
<uf-empty-state icon="search">
|
|
1602
|
+
<h3 slot="heading">No results for “invoice 2019”</h3>
|
|
1603
|
+
Check the spelling, or try a shorter search.
|
|
1604
|
+
<uf-button slot="actions" variant="outline">Clear search</uf-button>
|
|
1605
|
+
</uf-empty-state>
|
|
1606
|
+
```
|
|
1607
|
+
|
|
1608
|
+
### `<uf-empty-state>` API
|
|
1609
|
+
|
|
1610
|
+
#### Attributes and properties
|
|
1611
|
+
|
|
1612
|
+
| Attribute | Property | Type | Default | Description |
|
|
1613
|
+
|---|---|---|---|---|
|
|
1614
|
+
| `heading` | | `string \| undefined` | | Bold text above the explanation. |
|
|
1615
|
+
| `icon` | | `string` | `'inbox'` | A built-in or registered icon name. An empty string hides the icon. |
|
|
1616
|
+
|
|
1617
|
+
#### Slots
|
|
1618
|
+
|
|
1619
|
+
| Slot | Description |
|
|
1620
|
+
|---|---|
|
|
1621
|
+
| (default) | The explanation. |
|
|
1622
|
+
| `heading` | The heading, when you need markup or a heading level. Overrides `heading`. |
|
|
1623
|
+
| `icon` | Replaces the icon. |
|
|
1624
|
+
| `actions` | Buttons or links, like "Create a project". |
|
|
1625
|
+
|
|
1626
|
+
#### CSS parts
|
|
1627
|
+
|
|
1628
|
+
| Part | Description |
|
|
1629
|
+
|---|---|
|
|
1630
|
+
| `base` | The empty state. |
|
|
1631
|
+
| `icon` | The icon. |
|
|
1632
|
+
| `heading` | The heading. |
|
|
1633
|
+
| `description` | The explanation. |
|
|
1634
|
+
| `actions` | The wrapper around the actions. |
|
|
1635
|
+
|
|
1636
|
+
#### CSS custom properties
|
|
1637
|
+
|
|
1638
|
+
| Property | Description |
|
|
1639
|
+
|---|---|
|
|
1640
|
+
| `--uf-empty-state-icon-size` | Size of the icon. |
|
|
1641
|
+
| `--uf-empty-state-icon-color` | Color of the icon. |
|
|
1642
|
+
| `--uf-empty-state-padding` | Space around the content. |
|
|
1643
|
+
|
|
1575
1644
|
## File upload
|
|
1576
1645
|
|
|
1577
1646
|
Picks files to send with a form: from a button, or by dragging them onto the
|
|
@@ -1833,6 +1902,130 @@ Errors appear after the user edits the field or tries to submit.
|
|
|
1833
1902
|
| `--uf-field-border-color` | Border color of the box. |
|
|
1834
1903
|
| `--uf-field-radius` | Corner radius of the box. |
|
|
1835
1904
|
|
|
1905
|
+
## Multi-select
|
|
1906
|
+
|
|
1907
|
+
A field to pick several options from a list you can search. The picked ones
|
|
1908
|
+
show as chips in the field, each with a remove button. Write options as plain
|
|
1909
|
+
`<option>` and `<optgroup>` children; `selected` ones start picked.
|
|
1910
|
+
|
|
1911
|
+
It follows the WAI-ARIA combobox pattern with a multi-select listbox: typing
|
|
1912
|
+
filters the list, arrow keys move through it, Enter picks or unpicks an
|
|
1913
|
+
option and keeps the list open, and Backspace in an empty field removes the
|
|
1914
|
+
last chip. With a `name`, every picked value is submitted with the form.
|
|
1915
|
+
|
|
1916
|
+
Tags: `<uf-multi-select>`. Import: `import '@unframed/core/multi-select';` (or `npx @unframed/cli add multi-select` to copy the source).
|
|
1917
|
+
|
|
1918
|
+
### Basic
|
|
1919
|
+
|
|
1920
|
+
Type to filter, Enter or a click to pick, and the list stays open for the next one. Backspace removes the last chip. The value is an array, in the order of the options.
|
|
1921
|
+
|
|
1922
|
+
```html
|
|
1923
|
+
<uf-multi-select name="toppings" label="Toppings" placeholder="Pick toppings">
|
|
1924
|
+
<option value="cheese" selected>Cheese</option>
|
|
1925
|
+
<option value="olives">Olives</option>
|
|
1926
|
+
<option value="basil">Basil</option>
|
|
1927
|
+
<option value="ham" disabled>Ham (sold out)</option>
|
|
1928
|
+
</uf-multi-select>
|
|
1929
|
+
```
|
|
1930
|
+
|
|
1931
|
+
- With a `name`, every picked value is submitted under that name, like a native `<select multiple>`: read them with `formData.getAll(name)`.
|
|
1932
|
+
|
|
1933
|
+
### Groups and validation
|
|
1934
|
+
|
|
1935
|
+
```html
|
|
1936
|
+
<uf-multi-select name="languages" label="Languages" hint="Pick at least one." required>
|
|
1937
|
+
<optgroup label="Europe">
|
|
1938
|
+
<option>English</option>
|
|
1939
|
+
<option>Italian</option>
|
|
1940
|
+
</optgroup>
|
|
1941
|
+
<optgroup label="Asia">
|
|
1942
|
+
<option>Japanese</option>
|
|
1943
|
+
</optgroup>
|
|
1944
|
+
</uf-multi-select>
|
|
1945
|
+
```
|
|
1946
|
+
|
|
1947
|
+
### `<uf-multi-select>` API
|
|
1948
|
+
|
|
1949
|
+
#### Attributes and properties
|
|
1950
|
+
|
|
1951
|
+
| Attribute | Property | Type | Default | Description |
|
|
1952
|
+
|---|---|---|---|---|
|
|
1953
|
+
| `label` | | `string \| undefined` | | Visible label. |
|
|
1954
|
+
| `hint` | | `string \| undefined` | | Help text below the field. |
|
|
1955
|
+
| `placeholder` | | `string \| undefined` | | Placeholder text in the field, while nothing is picked. |
|
|
1956
|
+
| `size` | | `FieldSize` | `'md'` | Size of the field. |
|
|
1957
|
+
| `open` | | `boolean` | `false` | Whether the list is showing. |
|
|
1958
|
+
| `name` | | `string` | `''` | Name submitted with the form. |
|
|
1959
|
+
| `disabled` | | `boolean` | `false` | Disables the control. |
|
|
1960
|
+
| `required` | | `boolean` | `false` | Makes the control required for form submission. |
|
|
1961
|
+
|
|
1962
|
+
#### Properties only
|
|
1963
|
+
|
|
1964
|
+
| Property | Type | Description |
|
|
1965
|
+
|---|---|---|
|
|
1966
|
+
| `value` | `string[]` | The picked options' values, in the order of the options. |
|
|
1967
|
+
| `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
|
|
1968
|
+
| `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
|
|
1969
|
+
| `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
|
|
1970
|
+
| `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
|
|
1971
|
+
|
|
1972
|
+
#### Methods
|
|
1973
|
+
|
|
1974
|
+
| Method | Description |
|
|
1975
|
+
|---|---|
|
|
1976
|
+
| `show()` | Opens the list. |
|
|
1977
|
+
| `hide()` | Closes the list. |
|
|
1978
|
+
| `checkValidity()` | Returns whether the value is valid, without showing an error. |
|
|
1979
|
+
| `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
|
|
1980
|
+
| `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
|
|
1981
|
+
|
|
1982
|
+
#### Events
|
|
1983
|
+
|
|
1984
|
+
| Event | Type | Description |
|
|
1985
|
+
|---|---|---|
|
|
1986
|
+
| `uf-show` | `Event` | The list opened. |
|
|
1987
|
+
| `uf-hide` | `Event` | The list closed. |
|
|
1988
|
+
| `input` | | Fired as the user types in the field (the search text, not the value). |
|
|
1989
|
+
| `change` | `Event` | Fired when an option is picked or removed. |
|
|
1990
|
+
|
|
1991
|
+
#### Slots
|
|
1992
|
+
|
|
1993
|
+
| Slot | Description |
|
|
1994
|
+
|---|---|
|
|
1995
|
+
| (default) | `<option>` and `<optgroup>` elements. They are read, not rendered. |
|
|
1996
|
+
| `label` | The label, when you need markup. Overrides `label`. |
|
|
1997
|
+
| `hint` | Help text below the field. Overrides `hint`. |
|
|
1998
|
+
|
|
1999
|
+
#### CSS parts
|
|
2000
|
+
|
|
2001
|
+
| Part | Description |
|
|
2002
|
+
|---|---|
|
|
2003
|
+
| `field` | The wrapper around label, control, hint and error. |
|
|
2004
|
+
| `form-label` | The label. |
|
|
2005
|
+
| `box` | The bordered box with the chips and the input. |
|
|
2006
|
+
| `chips` | The list of picked options. |
|
|
2007
|
+
| `chip` | A picked option. |
|
|
2008
|
+
| `chip-remove` | A chip's remove button. |
|
|
2009
|
+
| `input` | The native `<input>`. |
|
|
2010
|
+
| `toggle` | The button that opens the list. |
|
|
2011
|
+
| `listbox` | The floating list. |
|
|
2012
|
+
| `option` | Each option. |
|
|
2013
|
+
| `group-label` | Each group heading. |
|
|
2014
|
+
| `empty` | The "no results" message. |
|
|
2015
|
+
| `hint` | The hint text. |
|
|
2016
|
+
| `error` | The validation message. |
|
|
2017
|
+
|
|
2018
|
+
#### CSS custom properties
|
|
2019
|
+
|
|
2020
|
+
| Property | Description |
|
|
2021
|
+
|---|---|
|
|
2022
|
+
| `--uf-multi-select-max-height` | Maximum height of the list before it scrolls. |
|
|
2023
|
+
| `--uf-multi-select-chip-bg` | Background of the chips. |
|
|
2024
|
+
| `--uf-multi-select-chip-color` | Text color of the chips. |
|
|
2025
|
+
| `--uf-field-bg` | Background of the box. |
|
|
2026
|
+
| `--uf-field-border-color` | Border color of the box. |
|
|
2027
|
+
| `--uf-field-radius` | Corner radius of the box. |
|
|
2028
|
+
|
|
1836
2029
|
## Number input
|
|
1837
2030
|
|
|
1838
2031
|
A field for a number, with buttons to step it down and up. The value is a
|
|
@@ -2250,6 +2443,109 @@ Arrow keys move the selection; only the selected radio is in the tab order.
|
|
|
2250
2443
|
| `--uf-radio-size` | Size of the circle. |
|
|
2251
2444
|
| `--uf-radio-checked-bg` | Color of the circle when checked. |
|
|
2252
2445
|
|
|
2446
|
+
## Segmented control
|
|
2447
|
+
|
|
2448
|
+
A row of buttons for one choice among a few, like "List / Grid" or "Day /
|
|
2449
|
+
Week / Month". The choices are plain `<option>` children. One is always
|
|
2450
|
+
selected: the `value` attribute, an option marked `selected`, or the first.
|
|
2451
|
+
|
|
2452
|
+
It's a radio group for assistive tech: arrow keys move and select, Home and
|
|
2453
|
+
End jump to the ends, and it submits its value with a form.
|
|
2454
|
+
|
|
2455
|
+
Tags: `<uf-segmented-control>`. Import: `import '@unframed/core/segmented-control';` (or `npx @unframed/cli add segmented-control` to copy the source).
|
|
2456
|
+
|
|
2457
|
+
### Basic
|
|
2458
|
+
|
|
2459
|
+
One choice among a few, always with one picked: the `value` attribute, a `selected` option, or the first. Arrow keys move and pick.
|
|
2460
|
+
|
|
2461
|
+
```html
|
|
2462
|
+
<uf-segmented-control name="view" label="View" value="week">
|
|
2463
|
+
<option value="day">Day</option>
|
|
2464
|
+
<option value="week">Week</option>
|
|
2465
|
+
<option value="month">Month</option>
|
|
2466
|
+
<option value="year" disabled>Year</option>
|
|
2467
|
+
</uf-segmented-control>
|
|
2468
|
+
```
|
|
2469
|
+
|
|
2470
|
+
- For more than five or six options, or long labels, use a select or a radio group instead.
|
|
2471
|
+
|
|
2472
|
+
### Sizes
|
|
2473
|
+
|
|
2474
|
+
```html
|
|
2475
|
+
<uf-segmented-control size="sm" label="Layout">
|
|
2476
|
+
<option>List</option>
|
|
2477
|
+
<option>Grid</option>
|
|
2478
|
+
</uf-segmented-control>
|
|
2479
|
+
```
|
|
2480
|
+
|
|
2481
|
+
### `<uf-segmented-control>` API
|
|
2482
|
+
|
|
2483
|
+
#### Attributes and properties
|
|
2484
|
+
|
|
2485
|
+
| Attribute | Property | Type | Default | Description |
|
|
2486
|
+
|---|---|---|---|---|
|
|
2487
|
+
| `value` | `defaultValue` | `string \| undefined` | | Initially selected value, restored on form reset. Set with the `value` attribute. |
|
|
2488
|
+
| `label` | | `string \| undefined` | | Visible label, also the group's accessible name. |
|
|
2489
|
+
| `hint` | | `string \| undefined` | | Help text below the options. |
|
|
2490
|
+
| `size` | | `FieldSize` | `'md'` | Size of the buttons. |
|
|
2491
|
+
| `name` | | `string` | `''` | Name submitted with the form. |
|
|
2492
|
+
| `disabled` | | `boolean` | `false` | Disables the control. |
|
|
2493
|
+
| `required` | | `boolean` | `false` | Makes the control required for form submission. |
|
|
2494
|
+
|
|
2495
|
+
#### Properties only
|
|
2496
|
+
|
|
2497
|
+
| Property | Type | Description |
|
|
2498
|
+
|---|---|---|
|
|
2499
|
+
| `value` | `string` | The selected option's value. |
|
|
2500
|
+
| `form` | `HTMLFormElement \| null` | Read-only. The form this control belongs to, if any. |
|
|
2501
|
+
| `validity` | `ValidityState` | Read-only. The control's validity state, like a native input's. |
|
|
2502
|
+
| `validationMessage` | `string` | Read-only. The error message shown when the value is invalid. |
|
|
2503
|
+
| `willValidate` | `boolean` | Read-only. Whether the control takes part in form validation. |
|
|
2504
|
+
|
|
2505
|
+
#### Methods
|
|
2506
|
+
|
|
2507
|
+
| Method | Description |
|
|
2508
|
+
|---|---|
|
|
2509
|
+
| `focus(options: FocusOptions)` | Moves focus to the selected option. |
|
|
2510
|
+
| `checkValidity()` | Returns whether the value is valid, without showing an error. |
|
|
2511
|
+
| `reportValidity()` | Returns whether the value is valid, and shows the error if not. |
|
|
2512
|
+
| `setCustomValidity(message: string)` | Sets a custom error message. Pass an empty string to clear it. |
|
|
2513
|
+
|
|
2514
|
+
#### Events
|
|
2515
|
+
|
|
2516
|
+
| Event | Type | Description |
|
|
2517
|
+
|---|---|---|
|
|
2518
|
+
| `input` | `Event` | The user picked another option. |
|
|
2519
|
+
| `change` | `Event` | The user picked another option. |
|
|
2520
|
+
|
|
2521
|
+
#### Slots
|
|
2522
|
+
|
|
2523
|
+
| Slot | Description |
|
|
2524
|
+
|---|---|
|
|
2525
|
+
| (default) | `<option>` elements. `disabled` options can't be picked. |
|
|
2526
|
+
| `label` | The label, when you need markup. Overrides `label`. |
|
|
2527
|
+
| `hint` | Help text below the options. Overrides `hint`. |
|
|
2528
|
+
|
|
2529
|
+
#### CSS parts
|
|
2530
|
+
|
|
2531
|
+
| Part | Description |
|
|
2532
|
+
|---|---|
|
|
2533
|
+
| `base` | The element with `role="radiogroup"`. |
|
|
2534
|
+
| `form-label` | The label. |
|
|
2535
|
+
| `options` | The row of buttons. |
|
|
2536
|
+
| `option` | One button. The selected one also has the part `selected`. |
|
|
2537
|
+
| `selected` | The selected button. |
|
|
2538
|
+
| `hint` | The hint text. |
|
|
2539
|
+
|
|
2540
|
+
#### CSS custom properties
|
|
2541
|
+
|
|
2542
|
+
| Property | Description |
|
|
2543
|
+
|---|---|
|
|
2544
|
+
| `--uf-segmented-control-bg` | Background behind the buttons. |
|
|
2545
|
+
| `--uf-segmented-control-selected-bg` | Background of the selected button. |
|
|
2546
|
+
| `--uf-segmented-control-selected-color` | Text color of the selected button. |
|
|
2547
|
+
| `--uf-segmented-control-radius` | Corner radius of the row. |
|
|
2548
|
+
|
|
2253
2549
|
## Select
|
|
2254
2550
|
|
|
2255
2551
|
A dropdown built on the native `<select>`, so it gets the platform's
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Using Unframed 0.
|
|
1
|
+
# Using Unframed 0.13.1 in each framework
|
|
2
2
|
|
|
3
3
|
## HTML & JavaScript
|
|
4
4
|
|
|
@@ -68,8 +68,8 @@ dialog.addEventListener('uf-hide', () => toast('Welcome aboard!', { variant: 'su
|
|
|
68
68
|
<!doctype html>
|
|
69
69
|
<html lang="en">
|
|
70
70
|
<head>
|
|
71
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@unframed/tokens@0.
|
|
72
|
-
<script type="module" src="https://cdn.jsdelivr.net/npm/@unframed/core@0.
|
|
71
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@unframed/tokens@0.13/dist/tokens.css" />
|
|
72
|
+
<script type="module" src="https://cdn.jsdelivr.net/npm/@unframed/core@0.13/+esm"></script>
|
|
73
73
|
</head>
|
|
74
74
|
<body>
|
|
75
75
|
<uf-button variant="primary">It works</uf-button>
|