@lofid/web 0.0.0-stage → 1.1.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/README.md +104 -2
- package/custom-elements.json +12890 -0
- package/dist/index.d.ts +3192 -0
- package/dist/index.js +20807 -0
- package/dist/index.js.map +1 -0
- package/dist/styles/ag-grid.css +145 -0
- package/dist/styles/motion.css +32 -0
- package/dist/styles/motion.tokens.json +38 -0
- package/dist/styles/typography.css +41 -0
- package/dist/styles/typography.json +858 -0
- package/dist/styles/vars.css +1225 -0
- package/package.json +46 -4
- package/readmes/lof-accordion/README.md +140 -0
- package/readmes/lof-alert/README.md +142 -0
- package/readmes/lof-autocomplete/README.md +209 -0
- package/readmes/lof-avatar/README.md +228 -0
- package/readmes/lof-badge/README.md +102 -0
- package/readmes/lof-breadcrumb/README.md +97 -0
- package/readmes/lof-button/README.md +189 -0
- package/readmes/lof-calendar/README.md +111 -0
- package/readmes/lof-card/README.md +105 -0
- package/readmes/lof-cardmedia/README.md +100 -0
- package/readmes/lof-carousel/README.md +187 -0
- package/readmes/lof-checkbox/README.md +159 -0
- package/readmes/lof-chip/README.md +153 -0
- package/readmes/lof-container/README.md +107 -0
- package/readmes/lof-date-picker/README.md +221 -0
- package/readmes/lof-divider/README.md +88 -0
- package/readmes/lof-drawer/README.md +188 -0
- package/readmes/lof-empty-state/README.md +78 -0
- package/readmes/lof-image-input/README.md +75 -0
- package/readmes/lof-kbd/README.md +188 -0
- package/readmes/lof-layout/README.md +122 -0
- package/readmes/lof-link/README.md +67 -0
- package/readmes/lof-menu/README.md +187 -0
- package/readmes/lof-menubar/README.md +218 -0
- package/readmes/lof-nav/README.md +90 -0
- package/readmes/lof-otp/README.md +167 -0
- package/readmes/lof-page-header/README.md +71 -0
- package/readmes/lof-pagination/README.md +141 -0
- package/readmes/lof-popover/README.md +220 -0
- package/readmes/lof-progress/README.md +88 -0
- package/readmes/lof-radio/README.md +142 -0
- package/readmes/lof-range-picker/README.md +194 -0
- package/readmes/lof-rating/README.md +90 -0
- package/readmes/lof-resizable/README.md +220 -0
- package/readmes/lof-segmented-button/README.md +158 -0
- package/readmes/lof-select/README.md +193 -0
- package/readmes/lof-sheet/README.md +170 -0
- package/readmes/lof-signature-pad/README.md +161 -0
- package/readmes/lof-skeleton/README.md +104 -0
- package/readmes/lof-slider/README.md +140 -0
- package/readmes/lof-snackbar/README.md +170 -0
- package/readmes/lof-split-button/README.md +129 -0
- package/readmes/lof-stat/README.md +73 -0
- package/readmes/lof-stepper/README.md +171 -0
- package/readmes/lof-switch/README.md +122 -0
- package/readmes/lof-tab/README.md +188 -0
- package/readmes/lof-table/README.md +114 -0
- package/readmes/lof-textfield/README.md +206 -0
- package/readmes/lof-time-picker/README.md +188 -0
- package/readmes/lof-toast/README.md +174 -0
- package/readmes/lof-tooltip/README.md +120 -0
- package/readmes/lof-tree/README.md +157 -0
- package/readmes/lof-upload/README.md +223 -0
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# lof-pagination
|
|
2
|
+
|
|
3
|
+
Page navigation implementing the Figma "Pagination" component in its three **Type** layouts: `extended` (prev/next ghost buttons around numbered page chips, with a windowed ellipsis for long ranges), `compact` (prev/next around a "Page X of Y" readout) and `count-text` (a "1–10 of 50" item range with the nav on the right). Use it under tables, lists and search results that load one page at a time. It never fetches data or reads the URL: listen for `lof-change` and load the requested page yourself.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Extended (default): numbered pages, uncontrolled -->
|
|
9
|
+
<lof-pagination total-pages="12" default-page="3"></lof-pagination>
|
|
10
|
+
|
|
11
|
+
<!-- Extended with the "Viewing page X of Y" caption -->
|
|
12
|
+
<lof-pagination total-pages="20" show-label></lof-pagination>
|
|
13
|
+
|
|
14
|
+
<!-- Compact: prev / "Page X of Y" / next -->
|
|
15
|
+
<lof-pagination type="compact" total-pages="8"></lof-pagination>
|
|
16
|
+
|
|
17
|
+
<!-- Count-text: item range computed from total-items and per-page -->
|
|
18
|
+
<lof-pagination type="count-text" total-items="137" per-page="25"></lof-pagination>
|
|
19
|
+
|
|
20
|
+
<!-- Controlled: the parent owns the page -->
|
|
21
|
+
<lof-pagination id="results" page="1" total-pages="40" ariaLabel="Search results pagination"></lof-pagination>
|
|
22
|
+
<script>
|
|
23
|
+
const pager = document.getElementById('results');
|
|
24
|
+
pager.addEventListener('lof-change', (e) => {
|
|
25
|
+
loadResults(e.detail.page).then(() => {
|
|
26
|
+
pager.page = e.detail.page; // commit once the data is in
|
|
27
|
+
});
|
|
28
|
+
});
|
|
29
|
+
</script>
|
|
30
|
+
|
|
31
|
+
<!-- Disabled while loading -->
|
|
32
|
+
<lof-pagination total-pages="12" disabled></lof-pagination>
|
|
33
|
+
|
|
34
|
+
<!-- New in 1.5.0. Page select: prev / "Page [dropdown] of Y" / next; the dropdown jumps to any page -->
|
|
35
|
+
<lof-pagination type="page-select" total-pages="40"></lof-pagination>
|
|
36
|
+
|
|
37
|
+
<!-- New in 1.5.0. A rows-per-page selector after the navigation (Figma "Extended with Rows").
|
|
38
|
+
Works with every type; choosing a value updates per-page and returns to page 1. -->
|
|
39
|
+
<lof-pagination total-items="137" per-page="20" show-rows-per-page></lof-pagination>
|
|
40
|
+
<lof-pagination type="count-text" total-items="137" per-page="25"
|
|
41
|
+
show-rows-per-page rows-per-page-options="[25, 50, 100]"></lof-pagination>
|
|
42
|
+
<script>
|
|
43
|
+
document.querySelector('lof-pagination[show-rows-per-page]')
|
|
44
|
+
.addEventListener('lof-per-page-change', (e) => reload({ perPage: e.detail.perPage, page: 1 }));
|
|
45
|
+
</script>
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Without `show-rows-per-page` there is no rows-per-page selector, and every type except `page-select` has no jump-to-page control: those are the defaults, so existing markup renders exactly as before.
|
|
49
|
+
|
|
50
|
+
### Deprecated aliases
|
|
51
|
+
|
|
52
|
+
```html
|
|
53
|
+
<!-- Lowercase-joined attribute spellings → kebab-case (since 1.5.0; still work, log a one-time
|
|
54
|
+
console notice, removed in 3.0). camelCase markup (totalPages="12") lands on these too. -->
|
|
55
|
+
<lof-pagination totalpages="12" defaultpage="3" showlabel></lof-pagination>
|
|
56
|
+
<lof-pagination type="count-text" totalitems="137" perpage="25" hreftemplate="?page={page}"></lof-pagination>
|
|
57
|
+
<!-- canonical -->
|
|
58
|
+
<lof-pagination total-pages="12" default-page="3" show-label></lof-pagination>
|
|
59
|
+
<lof-pagination type="count-text" total-items="137" per-page="25" href-template="?page={page}"></lof-pagination>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
<!-- readme-gen:start -->
|
|
63
|
+
|
|
64
|
+
<!-- Generated from lof-pagination.ts — do not edit; run readme-generate.mjs -->
|
|
65
|
+
|
|
66
|
+
## API
|
|
67
|
+
|
|
68
|
+
### Attributes / Properties
|
|
69
|
+
|
|
70
|
+
| Property | Attribute | Type | Default | Description |
|
|
71
|
+
| --- | --- | --- | --- | --- |
|
|
72
|
+
| `type` | `type` | `"extended" \| "compact" \| "count-text" \| "page-select"` | `"extended"` | Figma "Type": `extended` = prev/next + numbered page buttons (auto-collapses to compact under 480px container width), `compact` = prev/next + "Page X of Y", `count-text` = "start–end of total" item range + prev/next around the current page number, `page-select` = prev/next around "Page [select] of Y", a dropdown that jumps to any page (new in 1.5.0). Every type except `page-select` has no jump-to-page control. Reflected. |
|
|
73
|
+
| `page` | `page` | `number` | `undefined` | Controlled current page (1-based). When set, the element only emits `lof-change` and waits for the parent to update `page`; leave unset for uncontrolled behaviour. |
|
|
74
|
+
| `defaultPage` | `default-page` | `number` | `1` | Starting page for uncontrolled use (ignored when `page` is set). The `defaultpage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
75
|
+
| `totalPages` | `total-pages` | `number` | `0` | Total number of pages. `0` (the default) lets `totalItems` / `perPage` compute the page count instead. The `totalpages` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
76
|
+
| `totalItems` | `total-items` | `number` | `0` | Total item count; with `perPage` it computes the page count when `totalPages` is `0` and is the "of N" figure in the count-text readout. The `totalitems` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
77
|
+
| `perPage` | `per-page` | `number` | `10` | Items per page, used to compute the page count from `totalItems` and the "start–end" range in the count-text readout. The `perpage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
78
|
+
| `showLabel` | `show-label` | `boolean` | `false` | Shows a "Viewing page X of Y" caption under the extended layout (ignored by the other types). Off by default. The `showlabel` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
79
|
+
| `disabled` | `disabled` | `boolean` | `false` | Dims the whole control to 40% opacity, shows a `not-allowed` cursor and ignores every page change. Reflected. |
|
|
80
|
+
| `hrefTemplate` | `href-template` | `string` | `""` | Reserved for link-mode pagination. Currently accepted but not rendered: every page control is a `<button>`, so navigate in your `lof-change` handler instead. The `hreftemplate` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
81
|
+
| `ariaLabel` | `arialabel` | `string` | `"Pagination"` | Accessible name of the `role="navigation"` landmark (attribute `ariaLabel`). Set it when a page contains more than one pagination control. |
|
|
82
|
+
| `showRowsPerPage` | `show-rows-per-page` | `boolean` | `false` | New in 1.5.0. Adds a rows-per-page selector after the navigation, with any `type` (Figma "Extended with Rows" is `type="extended"` with this set). Choosing a value sets `perPage`, fires `lof-per-page-change` and returns to page 1. Off by default: no rows-per-page selector. |
|
|
83
|
+
| `rowsPerPageOptions` | `rows-per-page-options` | `number[]` | `[10, 20, 50, 100]` | New in 1.5.0. The values the rows-per-page selector offers (a number array, or a JSON array in the attribute). The current `perPage` is added to the list when it is not in it. |
|
|
84
|
+
| `rowsPerPageLabel` | `rows-per-page-label` | `string` | `"Results per Page"` | New in 1.5.0. Text before the rows-per-page selector, also its accessible name. |
|
|
85
|
+
|
|
86
|
+
## Events
|
|
87
|
+
|
|
88
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
89
|
+
| --- | --- | --- | --- |
|
|
90
|
+
| `lof-change` | `{ page: newPage }` | bubbles / composed | Fired when the user picks another page (prev/next or a page number). Detail: `{ page: number }` (1-based). In controlled mode the parent must then set `page`. |
|
|
91
|
+
| `lof-per-page-change` | `{ perPage }` | bubbles / composed | New in 1.5.0. Fired when the user picks a value in the rows-per-page selector (`show-rows-per-page`). Detail: `{ perPage: number }`. `perPage` is already updated; the element then returns to page 1 (in controlled mode it fires `lof-change` with `{ page: 1 }` for the parent to commit). |
|
|
92
|
+
|
|
93
|
+
## Slots
|
|
94
|
+
|
|
95
|
+
| Slot | Description |
|
|
96
|
+
| --- | --- |
|
|
97
|
+
| — | This element has no slots. |
|
|
98
|
+
|
|
99
|
+
## CSS Parts
|
|
100
|
+
|
|
101
|
+
| Part | Description |
|
|
102
|
+
| --- | --- |
|
|
103
|
+
| `base` | The `role="navigation"` root of the extended layout (page buttons plus the optional "Viewing page" label). |
|
|
104
|
+
| `label` | The `role="navigation"` root row of the count-text layout (item-range text plus prev/next nav). |
|
|
105
|
+
| `page-select` | The `lof-select` of the `page-select` layout (the jump-to-page dropdown). New in 1.5.0. |
|
|
106
|
+
| `rows-per-page` | The rows-per-page block (its text plus the `lof-select`), rendered with `show-rows-per-page`. New in 1.5.0. |
|
|
107
|
+
|
|
108
|
+
<!-- readme-gen:end -->
|
|
109
|
+
|
|
110
|
+
## Accessibility
|
|
111
|
+
|
|
112
|
+
- The control is a `role="navigation"` landmark named by `ariaLabel` (default "Pagination"); give each pager on a page a distinct name.
|
|
113
|
+
- Prev/next are native buttons labelled "Previous page" / "Next page"; they are disabled (not hidden) on the first / last page.
|
|
114
|
+
- Each page chip is a native button labelled "Page N" with `aria-current="page"` on the current one. Abbreviated first/last chips (e.g. "368k") keep the exact number in their `title`.
|
|
115
|
+
- Every page change is announced to screen readers as "Page N of M" via the shared live region.
|
|
116
|
+
- If a prev/next button becomes disabled while it has focus (you reached the first/last page), focus moves to the other nav button instead of being lost.
|
|
117
|
+
- `type="page-select"` (new in 1.5.0): the dropdown is a `lof-select` combobox named "Page (of N)", so it is read as, for example, "Page (of 40), 3". The visible "Page" and "of N" texts are hidden from assistive technology because the name already carries them. It sits inside the navigation landmark, and picking a page is announced like any other page change.
|
|
118
|
+
- `show-rows-per-page` (new in 1.5.0): the rows-per-page dropdown is a `lof-select` combobox named by `rows-per-page-label` (default "Results per Page"), placed after the navigation landmark rather than inside it. Its visible text is hidden from assistive technology for the same reason.
|
|
119
|
+
- `disabled` also disables both dropdowns.
|
|
120
|
+
|
|
121
|
+
| Key | Action |
|
|
122
|
+
| --- | --- |
|
|
123
|
+
| `Tab` / `Shift+Tab` | Move between the prev button, page chips (or the page dropdown) and next button, then the rows-per-page dropdown |
|
|
124
|
+
| `Enter` / `Space` | Activate the focused button (native behaviour); on a dropdown, open it |
|
|
125
|
+
| `ArrowDown` / `ArrowUp`, `Enter`, `Escape` (dropdown open) | Move the highlight, pick the highlighted value, close without picking (lof-select's keyboard model) |
|
|
126
|
+
| Typing (page dropdown open) | Moves the highlight to the next page that starts with the digits typed within half a second (2 then 5 for page 25); Enter picks it |
|
|
127
|
+
|
|
128
|
+
The page chips and nav buttons have no arrow-key navigation; they are regular tab stops.
|
|
129
|
+
|
|
130
|
+
## Notes / Edge Cases
|
|
131
|
+
|
|
132
|
+
- **Attribute names.** Multi-word attributes are kebab-case: `total-pages`, `default-page`, `total-items`, `per-page`, `show-label`, `href-template`. They are observed like any other attribute, so later changes apply. The older lowercase spellings (which camelCase markup also produces, since HTML attribute names are case-insensitive) still work since 1.5.0 but log a one-time console notice and are removed in 3.0; see Deprecated aliases. `ariaLabel` keeps its `arialabel` attribute.
|
|
133
|
+
- **Page count.** `totalPages` wins when greater than `0`; otherwise the count is `ceil(totalItems / perPage)`. With neither set the element renders no page chips and both nav buttons disabled.
|
|
134
|
+
- **Controlled vs uncontrolled.** With `page` unset the element tracks the current page itself starting at `defaultPage`. Once `page` is set it stays on that page until the parent changes it — clicking only emits `lof-change`.
|
|
135
|
+
- **Ellipsis window.** Up to 7 pages render in full. Beyond that: the first 5 + last near the start, first + last 5 near the end, otherwise first, current ±1 and last, with `…` between. Far first/last chips abbreviate large numbers (`10000` → `10k`, `2500000` → `2.5M`); chips inside the window are never abbreviated.
|
|
136
|
+
- **Responsive.** `extended` uses a container query on the host: between 480px and 768px only first, last and current ±1 stay visible, with `…` wherever that hides two or more pages (a single hidden page stays visible instead); under 480px the whole control swaps to the compact layout (media-query fallback for browsers without container queries). The `label` part belongs to the `count-text` layout, not to the "Viewing page" caption.
|
|
137
|
+
- **`hrefTemplate`** is accepted but currently unused — chips are always buttons, not links. Perform navigation in the `lof-change` handler.
|
|
138
|
+
- **`lof-change` is not fired** for the current page, out-of-range pages, or while `disabled`.
|
|
139
|
+
- **Page select.** The dropdown lists every page. Above 1,000 pages it lists a window of 1,000 around the current page plus the first and last, so the list stays fast. In controlled mode the dropdown snaps back to `page` until the parent commits the new one.
|
|
140
|
+
- **Rows per page.** `rows-per-page-options` defaults to `[10, 20, 50, 100]`; the current `per-page` is added when it is not in the list. A pick sets `perPage`, fires `lof-per-page-change` (`{ perPage }`), then returns to page 1: uncontrolled, the element moves and fires `lof-change` with `{ page: 1 }`; controlled, it only fires `lof-change` with `{ page: 1 }`. When it is already on page 1, no `lof-change` fires. The inner dropdowns' own `changed` / `lof-change` events stop at the dropdown, so a listener on the pagination only ever sees `{ page }`.
|
|
141
|
+
- **Narrow containers.** With `show-rows-per-page` the navigation and the rows-per-page block share one row, 16px apart, and wrap onto two rows when they do not fit.
|
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
# lof-popover
|
|
2
|
+
|
|
3
|
+
A click-to-open floating panel anchored to a trigger, implementing the Figma "Popover" component (including its opt-in chevron). The folder registers two elements: `<lof-popover>` is the controller — its first child is the trigger, its `content` slot is the panel — and `<lof-popover-content>` is the optional styled surface (neutral background, radius, shadow, S/M/L padding; no border) you drop into that slot. The panel is promoted to the browser top layer and positioned in viewport coordinates, so it renders correctly even inside a centred `<lof-modal>`. Use it for rich, interactive content that needs an explicit click — small forms, filters, menus, detail cards. For a short hover label use `<lof-tooltip>`; for a task that must be completed before continuing use `<lof-modal>`.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Basic: first child = trigger, slot="content" = panel -->
|
|
9
|
+
<lof-popover>
|
|
10
|
+
<lof-button>Open</lof-button>
|
|
11
|
+
<lof-popover-content aria-label="About popovers">
|
|
12
|
+
<h3>Popover title</h3>
|
|
13
|
+
<p>Any HTML can go here.</p>
|
|
14
|
+
</lof-popover-content>
|
|
15
|
+
</lof-popover>
|
|
16
|
+
|
|
17
|
+
<!-- Panel padding (Figma Size S / M / L = 12 / 16 / 20px) -->
|
|
18
|
+
<lof-popover>
|
|
19
|
+
<lof-button variant="secondary">Compact</lof-button>
|
|
20
|
+
<lof-popover-content size="small" aria-label="Compact panel"><p>12px padding</p></lof-popover-content>
|
|
21
|
+
</lof-popover>
|
|
22
|
+
<lof-popover>
|
|
23
|
+
<lof-button variant="secondary">Roomy</lof-button>
|
|
24
|
+
<lof-popover-content size="large" aria-label="Roomy panel"><p>20px padding</p></lof-popover-content>
|
|
25
|
+
</lof-popover>
|
|
26
|
+
|
|
27
|
+
<!-- Positioning: side, alignment and pixel offsets -->
|
|
28
|
+
<lof-popover side="top" align="start">
|
|
29
|
+
<lof-button>Top / start</lof-button>
|
|
30
|
+
<lof-popover-content aria-label="Top start"><p>Above the trigger, left edges aligned.</p></lof-popover-content>
|
|
31
|
+
</lof-popover>
|
|
32
|
+
<lof-popover side="right" side-offset="16" align-offset="8">
|
|
33
|
+
<lof-button>Right, 16px away</lof-button>
|
|
34
|
+
<lof-popover-content aria-label="Right offset"><p>16px gap, shifted 8px down.</p></lof-popover-content>
|
|
35
|
+
</lof-popover>
|
|
36
|
+
|
|
37
|
+
<!-- Chevron pointing at the trigger -->
|
|
38
|
+
<lof-popover side="bottom" arrow>
|
|
39
|
+
<lof-button>With arrow</lof-button>
|
|
40
|
+
<lof-popover-content aria-label="Arrow demo"><p>The chevron follows the trigger centre.</p></lof-popover-content>
|
|
41
|
+
</lof-popover>
|
|
42
|
+
|
|
43
|
+
<!-- Any element can be the trigger or the panel -->
|
|
44
|
+
<lof-popover>
|
|
45
|
+
<span>Plain text trigger (made focusable automatically)</span>
|
|
46
|
+
<div slot="content" style="padding: 12px; background: var(--lof-bg-neutral); border: 1px solid var(--lof-border-default); border-radius: 8px;">
|
|
47
|
+
Unstyled custom panel
|
|
48
|
+
</div>
|
|
49
|
+
</lof-popover>
|
|
50
|
+
|
|
51
|
+
<!-- Form with focus trap: Tab cycles inside the panel until it closes -->
|
|
52
|
+
<lof-popover trap-focus>
|
|
53
|
+
<lof-button>Edit profile</lof-button>
|
|
54
|
+
<lof-popover-content aria-label="Edit profile">
|
|
55
|
+
<h3>Edit profile</h3>
|
|
56
|
+
<form>
|
|
57
|
+
<lof-textfield label="Name" value="Ada Lovelace"></lof-textfield>
|
|
58
|
+
<lof-textfield label="Email" type="email" value="ada@example.com"></lof-textfield>
|
|
59
|
+
<lof-button>Save</lof-button>
|
|
60
|
+
</form>
|
|
61
|
+
</lof-popover-content>
|
|
62
|
+
</lof-popover>
|
|
63
|
+
|
|
64
|
+
<!-- Controlled: you own `open` and apply every requested change -->
|
|
65
|
+
<lof-popover id="controlled" open>
|
|
66
|
+
<lof-button>Controlled trigger</lof-button>
|
|
67
|
+
<lof-popover-content aria-label="Controlled panel">
|
|
68
|
+
<p>State lives outside the component.</p>
|
|
69
|
+
<lof-button id="done" variant="secondary">Done</lof-button>
|
|
70
|
+
</lof-popover-content>
|
|
71
|
+
</lof-popover>
|
|
72
|
+
<script>
|
|
73
|
+
const popover = document.getElementById('controlled');
|
|
74
|
+
popover.addEventListener('lof-open-change', (e) => {
|
|
75
|
+
popover.open = e.detail.open; // nothing happens until you apply it
|
|
76
|
+
});
|
|
77
|
+
document.getElementById('done').addEventListener('click', () => {
|
|
78
|
+
popover.open = false;
|
|
79
|
+
});
|
|
80
|
+
// Uncontrolled instances: never set `open`; start open with `default-open` instead.
|
|
81
|
+
// Default-true booleans are switched off via the property:
|
|
82
|
+
popover.closeOnOutsideClick = false;
|
|
83
|
+
popover.closeOnEscape = false;
|
|
84
|
+
</script>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Deprecated aliases
|
|
88
|
+
|
|
89
|
+
```html
|
|
90
|
+
<!-- Lowercase-joined attribute spellings → kebab-case (since 1.5.0; still work, log a one-time
|
|
91
|
+
console notice, removed in 3.0) -->
|
|
92
|
+
<lof-popover defaultopen sideoffset="16" alignoffset="8" trapfocus closeonescape="false" closeonoutsideclick="false">…</lof-popover>
|
|
93
|
+
<!-- canonical -->
|
|
94
|
+
<lof-popover default-open side-offset="16" align-offset="8" trap-focus close-on-escape="false" close-on-outside-click="false">…</lof-popover>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
<!-- readme-gen:start -->
|
|
98
|
+
|
|
99
|
+
<!-- Generated from lof-popover.ts, lof-popover-content.ts — do not edit; run readme-generate.mjs -->
|
|
100
|
+
|
|
101
|
+
## Elements
|
|
102
|
+
|
|
103
|
+
| Element | Class | Source |
|
|
104
|
+
| --- | --- | --- |
|
|
105
|
+
| `<lof-popover>` | `LofPopover` | `lof-popover.ts` |
|
|
106
|
+
| `<lof-popover-content>` | `LofPopoverContent` | `lof-popover-content.ts` |
|
|
107
|
+
|
|
108
|
+
## API
|
|
109
|
+
|
|
110
|
+
### `<lof-popover>`
|
|
111
|
+
|
|
112
|
+
#### Attributes / Properties
|
|
113
|
+
|
|
114
|
+
| Property | Attribute | Type | Default | Description |
|
|
115
|
+
| --- | --- | --- | --- | --- |
|
|
116
|
+
| `open` | `open` | `boolean` | `undefined` | Controlled open state. Leave unset for uncontrolled mode; once set (true or false) the component only emits `lof-open-change` and you must update `open` yourself. Reflected. |
|
|
117
|
+
| `defaultOpen` | `default-open` | `boolean` | `false` | Initial state in uncontrolled mode (attribute `default-open`); ignored when `open` is set. The `defaultopen` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
118
|
+
| `disabled` | `disabled` | `boolean` | `false` | Blocks trigger interaction and dims the host to 60% opacity; does not close an already-open panel. Reflected. |
|
|
119
|
+
| `side` | `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Which side of the trigger the panel opens on: `top`, `right`, `bottom` (default) or `left`. The panel is clamped 8px inside the viewport but never flips to another side. Reflected. |
|
|
120
|
+
| `align` | `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the cross axis: `start` (left / top edge of the trigger), `center` (default) or `end` (right / bottom edge). Reflected. |
|
|
121
|
+
| `sideOffset` | `side-offset` | `number` | `8` | Gap between trigger and panel in pixels (attribute `side-offset`, default 8). With `arrow` the effective gap is at least 13px. The `sideoffset` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
122
|
+
| `alignOffset` | `align-offset` | `number` | `0` | Extra shift along the alignment axis in pixels (attribute `align-offset`, default 0); positive moves right / down. The `alignoffset` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
123
|
+
| `trapFocus` | `trap-focus` | `boolean` | `false` | Keep Tab / Shift+Tab cycling inside the panel while open (attribute `trap-focus`); use for forms. The `trapfocus` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
124
|
+
| `closeOnEscape` | `close-on-escape` | `boolean` | `true` | Close on Escape (attribute `close-on-escape`, default true; switch off with `close-on-escape="false"` or `el.closeOnEscape = false`). The `closeonescape` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
125
|
+
| `closeOnOutsideClick` | `close-on-outside-click` | `boolean` | `true` | Close on a pointer-down outside the trigger and panel (attribute `close-on-outside-click`, default true; switch off with `close-on-outside-click="false"` or the property). Also lets another popover's opening dismiss this one. The `closeonoutsideclick` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
126
|
+
| `arrow` | `arrow` | `boolean` | `false` | Opt-in pointer (audit 23a): a 14×11 triangle on the panel edge that faces the trigger — the Figma Popover "Chevron" — following `side` and tracking the trigger's centre along the cross axis (clamped inside the panel). It is drawn with the panel's tokens (`--lof-popover-arrow-bg` / `--lof-popover-arrow-border`, defaulting to lof-popover-content's background and border). With the arrow on, the panel keeps at least the arrow's height plus 2px away from the trigger so the tip never overlaps it; larger `sideOffset` values still apply. Default off — existing popovers render exactly as before. Reflected. |
|
|
127
|
+
| `hasPopup` | `has-popup` | `"dialog" \| "menu" \| "listbox" \| "tree" \| "grid" \| "true"` | `"dialog"` | New in 1.5.0. Value written to the trigger's `aria-haspopup` (attribute `has-popup`): `dialog` (default) for a panel of content, or `menu`, `listbox`, `tree`, `grid` or `true` when the panel holds that widget. A panel holding a `lof-menu` takes `menu`. |
|
|
128
|
+
|
|
129
|
+
### Events
|
|
130
|
+
|
|
131
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
132
|
+
| --- | --- | --- | --- |
|
|
133
|
+
| `lof-open-change` | `{ open: next }` | bubbles / composed | Fired whenever the trigger, Escape, an outside click or another popover requests a state change. Detail: `{ open: boolean }` — the requested state; in controlled mode apply it to `open` yourself. |
|
|
134
|
+
|
|
135
|
+
### Slots
|
|
136
|
+
|
|
137
|
+
| Slot | Description |
|
|
138
|
+
| --- | --- |
|
|
139
|
+
| (default) | The trigger: the first slotted element toggles the panel on pointer down / Enter / Space and receives `aria-haspopup` (from `has-popup`), `aria-expanded` and `aria-controls` (a bare `<div>` / `<span>` also gets `tabindex="0"` and `role="button"`). |
|
|
140
|
+
| `content` | The panel body, usually a `<lof-popover-content>`; rendered inside the fixed, top-layer wrapper only while open. |
|
|
141
|
+
|
|
142
|
+
### CSS Parts
|
|
143
|
+
|
|
144
|
+
| Part | Description |
|
|
145
|
+
| --- | --- |
|
|
146
|
+
| `arrow` | The 14×14 chevron box rendered on the panel edge facing the trigger when `arrow` is set (absent otherwise). |
|
|
147
|
+
|
|
148
|
+
### Tokens / CSS Variables
|
|
149
|
+
|
|
150
|
+
#### Component hooks
|
|
151
|
+
|
|
152
|
+
Set these on the host (or an ancestor) to customise the element without touching design tokens.
|
|
153
|
+
|
|
154
|
+
| Custom property | Default | Description |
|
|
155
|
+
| --- | --- | --- |
|
|
156
|
+
| `--lof-popover-arrow-bg` | `var(--lof-bg-neutral)` | Fill of the `arrow` chevron (default `--lof-bg-neutral`, matching `<lof-popover-content>`). |
|
|
157
|
+
| `--lof-popover-arrow-border` | `transparent` | **Deprecated.** Stroke of the `arrow` chevron's two slanted edges. The panel no longer draws a border — overlapping surfaces are separated by shadow — so this defaults to `transparent` and the chevron has no edge. Set it to restore a stroke. |
|
|
158
|
+
|
|
159
|
+
### `<lof-popover-content>`
|
|
160
|
+
|
|
161
|
+
#### Attributes / Properties
|
|
162
|
+
|
|
163
|
+
| Property | Attribute | Type | Default | Description |
|
|
164
|
+
| --- | --- | --- | --- | --- |
|
|
165
|
+
| `ariaLabel` | `aria-label` | `string` | `""` | Accessible name applied to the inner `role="dialog"` box (attribute `aria-label`); describe what the panel is for. |
|
|
166
|
+
| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Figma Size axis: panel padding 12px (`small`), 16px (`medium`, default) or 20px (`large`). `sm` / `md` / `lg` are alternative spellings and stay supported — they are normalised to the full words, not deprecated. Reflected. |
|
|
167
|
+
|
|
168
|
+
#### Methods
|
|
169
|
+
|
|
170
|
+
| Method | Signature | Description |
|
|
171
|
+
| --- | --- | --- |
|
|
172
|
+
| `focus` | `focus(options?: FocusOptions)` | Focuses the `role="dialog"` box rather than the host (which is not focusable). lof-popover lands focus here when the panel has nothing focusable, so a screen reader announces the dialog by its `aria-label`. |
|
|
173
|
+
|
|
174
|
+
### Events
|
|
175
|
+
|
|
176
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
177
|
+
| --- | --- | --- | --- |
|
|
178
|
+
| — | — | — | This element emits no custom events. |
|
|
179
|
+
|
|
180
|
+
### Slots
|
|
181
|
+
|
|
182
|
+
| Slot | Description |
|
|
183
|
+
| --- | --- |
|
|
184
|
+
| (default) | The panel content (headings, paragraphs, form controls, buttons). |
|
|
185
|
+
|
|
186
|
+
### CSS Parts
|
|
187
|
+
|
|
188
|
+
| Part | Description |
|
|
189
|
+
| --- | --- |
|
|
190
|
+
| `content` | The padded `role="dialog"` box that carries the surface, shadow and size padding. |
|
|
191
|
+
|
|
192
|
+
<!-- readme-gen:end -->
|
|
193
|
+
|
|
194
|
+
## Accessibility
|
|
195
|
+
|
|
196
|
+
- The trigger (first slotted element) is decorated with `aria-haspopup="dialog"`, `aria-expanded` (kept in sync with the open state) and `aria-controls` pointing at the panel wrapper. A trigger that is not natively focusable and contains nothing focusable (a bare `<div>` / `<span>`) also gets `tabindex="0"` and `role="button"`; native buttons and `<lof-button>` are left alone so they do not get a second Tab stop.
|
|
197
|
+
- `<lof-popover-content>` renders its box with `role="dialog"`; pass `aria-label` so the dialog has a name. A custom panel element should carry its own role and label.
|
|
198
|
+
- On open, focus moves to the first focusable element inside the panel — found through slots and nested shadow roots, so a `<lof-button>` inside `<lof-popover-content>` counts. When there is none, the panel itself takes focus so it is announced: `<lof-popover-content>` focuses its `role="dialog"` box (named by its `aria-label`), and any other panel element falls back to the panel wrapper. On close, focus that was inside the popover returns to the trigger's own control (a `<lof-button>`'s inner `<button>`); a close while focus is elsewhere on the page leaves it there.
|
|
199
|
+
- With `trap-focus`, Tab from the last focusable element wraps to the first and Shift+Tab from the first wraps to the last, so keyboard focus cannot leave the panel while it is open. Without it, Tab leaves the panel normally and the panel stays open until an outside click or Escape.
|
|
200
|
+
- There are no screen-reader announcements beyond the `aria-expanded` change; put the important content first in the panel so it is read when focus lands.
|
|
201
|
+
|
|
202
|
+
| Key | Action |
|
|
203
|
+
| --- | --- |
|
|
204
|
+
| `Enter` / `Space` (on the trigger) | Toggle the panel |
|
|
205
|
+
| `Escape` (anywhere, while open) | Close (unless `closeOnEscape` is switched off) |
|
|
206
|
+
| `Tab` / `Shift+Tab` | Move through the panel's focusable elements; with `trap-focus` the order wraps at both ends |
|
|
207
|
+
|
|
208
|
+
## Notes / Edge Cases
|
|
209
|
+
|
|
210
|
+
- **Slots.** The trigger is the *default* slot's first element; the panel goes in `slot="content"`. There is no `trigger` slot. Only one element should be in the default slot — extra default-slot children render next to the trigger but never toggle the panel.
|
|
211
|
+
- **Top layer / inside a modal.** The panel wrapper is a native `popover="manual"` element shown with `showPopover()`, so a transformed or `overflow: hidden` ancestor (for example `<lof-modal>`'s centred panel) cannot clip it or break its `position: fixed` coordinates. Where the Popover API is unavailable it falls back to `position: fixed; z-index: 1001` and re-measures once to cancel any containing-block offset.
|
|
212
|
+
- **No collision flipping.** The panel always opens on the requested `side`; it is only clamped to stay 8px inside the viewport. Pick the side yourself for edge-of-screen triggers.
|
|
213
|
+
- **One open at a time.** Opening a popover light-dismisses every other open popover that honours `closeOnOutsideClick`, whether it was opened by pointer, keyboard or code. A popover nested inside another's panel keeps its parent open.
|
|
214
|
+
- **Controlled vs uncontrolled.** `open` is `undefined` until you set it; setting it (to `true` *or* `false`) switches the instance to controlled mode permanently, after which the component only emits `lof-open-change` and never changes its own state. Use `default-open` for an uncontrolled popover that starts open.
|
|
215
|
+
- **Default-true booleans** (`closeOnEscape`, `closeOnOutsideClick`): since 1.5.0 the attribute value `"false"` turns them off (`close-on-escape="false"`), as does setting the property. A bare attribute or `=""` still means true.
|
|
216
|
+
- **Positioning updates** run on window resize and on scroll (capture phase). They do not run when the panel's own content changes size; toggle `open` or trigger a resize if you swap content while open.
|
|
217
|
+
- **Arrow.** `arrow` draws a 14×11 chevron on the panel edge facing the trigger, centred on the trigger and clamped 15px in from the panel corners; the trigger gap becomes `max(side-offset, 13px)`. Colour it with `--lof-popover-arrow-bg` / `--lof-popover-arrow-border` (defaults match `<lof-popover-content>`); if you use a custom panel with a different surface, set both so the chevron blends in.
|
|
218
|
+
- **`<lof-popover-content>`** is `display: block; width: 100%; max-width: 400px`; override `max-width` on the element for wider panels. Slotted `h1`–`h6` get heading-sm type and `p` gets placeholder-tone body text with a bottom margin (none on the last paragraph).
|
|
219
|
+
- **`disabled`** blocks the trigger and dims the host but does not close a panel that is already open — set `open = false` first if needed.
|
|
220
|
+
- The `size` values on `<lof-popover-content>` are `small` / `medium` / `large`. The short spellings `sm` / `md` / `lg` are alternative spellings and keep working — they are normalised to the full words before the attribute reflects, so `lof-popover-content[size="medium"]` matches whichever spelling was written.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# lof-progress
|
|
2
|
+
|
|
3
|
+
`<lof-progress>` is the Figma "Progress" indicator in its two shapes and two behaviours: a full-width 4px linear bar or a 36px circular ring, each either determinate (fills to `value`, 0–100) or indeterminate (loops an animation while you wait). Use `linear-determinate` / `circular-determinate` for uploads, imports and multi-step flows where progress is known, and the `*-indeterminate` modes as a loading signal while a request is in flight. It is a passive `role="progressbar"` element — it does not block interaction (use `lof-modal` with `loading` for that) and does not announce completion on its own.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Linear, determinate -->
|
|
9
|
+
<lof-progress mode="linear-determinate" value="45"></lof-progress>
|
|
10
|
+
<lof-progress mode="linear-determinate" value="100"></lof-progress>
|
|
11
|
+
|
|
12
|
+
<!-- Linear, indeterminate (loading) -->
|
|
13
|
+
<lof-progress mode="linear-indeterminate"></lof-progress>
|
|
14
|
+
|
|
15
|
+
<!-- Circular, determinate -->
|
|
16
|
+
<lof-progress mode="circular-determinate" value="75"></lof-progress>
|
|
17
|
+
|
|
18
|
+
<!-- Circular, indeterminate (spinner) -->
|
|
19
|
+
<lof-progress mode="circular-indeterminate"></lof-progress>
|
|
20
|
+
|
|
21
|
+
<!-- Accessible name -->
|
|
22
|
+
<lof-progress mode="linear-determinate" value="30" label="Uploading invoices"></lof-progress>
|
|
23
|
+
<lof-progress mode="circular-indeterminate" label="Loading projects"></lof-progress>
|
|
24
|
+
|
|
25
|
+
<!-- Driving the value from script -->
|
|
26
|
+
<lof-progress id="uploadProgress" mode="linear-determinate" value="0" label="Upload"></lof-progress>
|
|
27
|
+
<script>
|
|
28
|
+
const progress = document.getElementById('uploadProgress');
|
|
29
|
+
let value = 0;
|
|
30
|
+
const interval = setInterval(() => {
|
|
31
|
+
value += 10;
|
|
32
|
+
progress.value = value;
|
|
33
|
+
if (value >= 100) clearInterval(interval);
|
|
34
|
+
}, 500);
|
|
35
|
+
</script>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
<!-- readme-gen:start -->
|
|
39
|
+
|
|
40
|
+
<!-- Generated from lof-progress.ts — do not edit; run readme-generate.mjs -->
|
|
41
|
+
|
|
42
|
+
## API
|
|
43
|
+
|
|
44
|
+
### Attributes / Properties
|
|
45
|
+
|
|
46
|
+
| Property | Attribute | Type | Default | Description |
|
|
47
|
+
| --- | --- | --- | --- | --- |
|
|
48
|
+
| `mode` | `mode` | `"linear-determinate" \| "linear-indeterminate" \| "circular-determinate" \| "circular-indeterminate"` | `"linear-determinate"` | Shape and behaviour: `linear-*` is a full-width 2px bar, `circular-*` a 36px ring; `*-determinate` fills to `value`, `*-indeterminate` loops an animation and ignores `value`. Reflected. |
|
|
49
|
+
| `value` | `value` | `number` | `0` | Completion percentage 0–100 for the determinate modes; out-of-range values are clamped before rendering and before `aria-valuenow`. |
|
|
50
|
+
| `label` | `label` | `string` | `""` | Accessible name of the progressbar (not rendered visually); defaults to "Progress" for determinate and "Loading" for indeterminate modes. |
|
|
51
|
+
|
|
52
|
+
## Events
|
|
53
|
+
|
|
54
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
55
|
+
| --- | --- | --- | --- |
|
|
56
|
+
| — | — | — | This element emits no custom events. |
|
|
57
|
+
|
|
58
|
+
## Slots
|
|
59
|
+
|
|
60
|
+
| Slot | Description |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| — | This element has no slots. |
|
|
63
|
+
|
|
64
|
+
## CSS Parts
|
|
65
|
+
|
|
66
|
+
| Part | Description |
|
|
67
|
+
| --- | --- |
|
|
68
|
+
| `track` | The linear track `<div>` that carries `role="progressbar"` (linear modes only) |
|
|
69
|
+
| `indicator` | The filled / sliding bar inside the linear track (linear modes only) |
|
|
70
|
+
|
|
71
|
+
<!-- readme-gen:end -->
|
|
72
|
+
|
|
73
|
+
## Accessibility
|
|
74
|
+
|
|
75
|
+
- Every mode renders one element with `role="progressbar"` and an `aria-label` taken from `label`; when `label` is empty the name is "Progress" for determinate modes and "Loading" for indeterminate ones. Give it a specific `label` ("Uploading invoices") when more than one indicator can be on screen.
|
|
76
|
+
- Determinate modes also set `aria-valuenow` (the clamped `value`), `aria-valuemin="0"` and `aria-valuemax="100"`. Indeterminate modes omit the value attributes, which is what tells assistive technology the progress is unknown.
|
|
77
|
+
- The element is not focusable and handles no keys.
|
|
78
|
+
- It does not announce anything by itself: neither the start of loading nor reaching 100% is spoken. Announce those from the surrounding UI (for example with a status message) when they matter.
|
|
79
|
+
- `prefers-reduced-motion: reduce` is respected: the determinate transitions are removed, the linear indeterminate bar becomes a static full-width bar at 50% opacity, and the circular spinner stops rotating and shows a static partial arc.
|
|
80
|
+
|
|
81
|
+
## Notes / Edge Cases
|
|
82
|
+
|
|
83
|
+
- `value` is clamped to 0–100 before rendering and before `aria-valuenow`; the indeterminate modes ignore it entirely.
|
|
84
|
+
- The `track` and `indicator` parts exist only in the two linear modes. The circular modes render an inline `<svg>` with no parts, so `::part(track)` matches nothing there.
|
|
85
|
+
- Linear bars are 4px tall (`--lof-progress-height`) with fully rounded ends and stretch to the host's width (host is `display: block`); circular rings use round caps. Circular rings are fixed at 36px and the host switches to `display: inline-block`, so they sit inline with text.
|
|
86
|
+
- The linear determinate width animates over 0.3s and the circular arc over 0.35s; a value that jumps from 0 to 100 therefore takes a moment to catch up visually.
|
|
87
|
+
- Circular strokes are 3px (determinate) and 4px (indeterminate) with a flat (`butt`) line cap; the determinate ring starts at 12 o'clock via a −90° rotation.
|
|
88
|
+
- The indeterminate linear bar is a 30%-wide segment that sweeps left to right on a 1.5s loop; the spinner rotates on a 2s loop with a 1.5s dash animation.
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# lof-radio
|
|
2
|
+
|
|
3
|
+
`<lof-radio>` is the single-select radio group of the Lofid Design System (Figma "Radio"). One element is one group: it renders a native radio input for every entry in `options`, with optional supporting text and an icon or avatar prefix, in the Figma Size (S/M/L), Density (compact / comfortable) and Layout (leading / trailing) variants, plus error and disabled states. Use it when the user must pick exactly one of a few visible choices (2–7). For long lists use `<lof-select>`, for independent on/off choices use `<lof-checkbox>` or `<lof-switch>`.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Basic group; options as a JSON attribute, preselected via selected-value -->
|
|
9
|
+
<lof-radio
|
|
10
|
+
name="color"
|
|
11
|
+
field-aria-label="Colour"
|
|
12
|
+
options='[{"value":"red","label":"Red"},{"value":"blue","label":"Blue"},{"value":"green","label":"Green"}]'
|
|
13
|
+
selected-value="blue"
|
|
14
|
+
></lof-radio>
|
|
15
|
+
|
|
16
|
+
<!-- Two independent groups on one page: give each its own name -->
|
|
17
|
+
<lof-radio id="plan" name="plan" field-aria-label="Plan"></lof-radio>
|
|
18
|
+
<lof-radio id="billing" name="billing" field-aria-label="Billing cycle" orientation="horizontal"></lof-radio>
|
|
19
|
+
|
|
20
|
+
<!-- Sizes (16 / 18 / 20px controls, the same frames as lof-checkbox) -->
|
|
21
|
+
<lof-radio id="small" name="size-small" size="small"></lof-radio>
|
|
22
|
+
<lof-radio id="medium" name="size-medium" size="medium"></lof-radio>
|
|
23
|
+
<lof-radio id="large" name="size-large" size="large"></lof-radio>
|
|
24
|
+
|
|
25
|
+
<!-- Supporting text beside the control instead of on its own line -->
|
|
26
|
+
<lof-radio id="comfortable" name="tier" density="comfortable"></lof-radio>
|
|
27
|
+
|
|
28
|
+
<!-- Control on the far edge of each row (always comfortable density) -->
|
|
29
|
+
<lof-radio id="trailing" name="notify" alignment="trailing"></lof-radio>
|
|
30
|
+
|
|
31
|
+
<!-- Error state with a message; disabled group -->
|
|
32
|
+
<lof-radio id="consent" name="consent" error error-message="Choose one option to continue"></lof-radio>
|
|
33
|
+
<lof-radio id="locked" name="locked" disabled></lof-radio>
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
```js
|
|
37
|
+
const plan = document.getElementById("plan");
|
|
38
|
+
plan.options = [
|
|
39
|
+
{ value: "basic", label: "Basic", supportingText: "$9.99 / month" },
|
|
40
|
+
{ value: "pro", label: "Pro", supportingText: "$19.99 / month", icon: "settings" },
|
|
41
|
+
{ value: "team", label: "Team", avatar: "TM" },
|
|
42
|
+
{ value: "enterprise", label: "Enterprise", supportingText: "Contact sales", disabled: true },
|
|
43
|
+
];
|
|
44
|
+
plan.selectedValue = "basic";
|
|
45
|
+
|
|
46
|
+
plan.addEventListener("lof-change", (e) => {
|
|
47
|
+
e.detail.value; // "pro" — the selected option's value
|
|
48
|
+
e.detail.checked; // always true
|
|
49
|
+
plan.selectedValue === e.detail.value; // already updated
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Deprecated aliases
|
|
54
|
+
|
|
55
|
+
```html
|
|
56
|
+
<!-- selectedvalue / errormessage → selected-value / error-message (since 1.5.0; still work, log a
|
|
57
|
+
one-time console notice, removed in 3.0). selectedValue still reflects as selectedvalue in 1.x. -->
|
|
58
|
+
<lof-radio name="old" selectedvalue="blue" error errormessage="Pick one"></lof-radio>
|
|
59
|
+
<lof-radio name="new" selected-value="blue" error error-message="Pick one"></lof-radio>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
<!-- readme-gen:start -->
|
|
63
|
+
|
|
64
|
+
<!-- Generated from lof-radio.ts — do not edit; run readme-generate.mjs -->
|
|
65
|
+
|
|
66
|
+
## API
|
|
67
|
+
|
|
68
|
+
### Attributes / Properties
|
|
69
|
+
|
|
70
|
+
| Property | Attribute | Type | Default | Description |
|
|
71
|
+
| --- | --- | --- | --- | --- |
|
|
72
|
+
| `options` | `options` | `RadioOption[]` | `[]` | The options to render, in order. Each entry is a `RadioOption` (`value`, `label`, optional `supportingText`, `disabled`, `icon` or `avatar`). Set as a property (`.options=`) or as a JSON attribute. |
|
|
73
|
+
| `name` | `name` | `string` | `"radio-group"` | `name` given to every native radio input inside this element. It scopes native radio-group behaviour (arrow-key movement, mutual exclusion) to this group, so give each group on a page a distinct name. |
|
|
74
|
+
| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Layout axis of the option list. `"vertical"` (default) stacks options in a column; `"horizontal"` lays them out in a wrapping row. Reflected. |
|
|
75
|
+
| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Control scale. Since the 2026-11 refresh the radio pairs with `lof-checkbox`: `"small"` draws a 16px control with body-sm labels, `"medium"` (default) 18px with body-md, and `"large"` 20px with body-lg. Supporting text sits one body step below the label at every size (10 / 12 / 14px). `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. (Before the refresh, Small and Medium shared a 20px control and Large was 24px, following the Figma file.) Reflected. |
|
|
76
|
+
| `density` | `density` | `"compact" \| "comfortable"` | `"compact"` | Supporting-text layout (Figma Density). `"compact"` (default) puts the supporting text on its own line under the row, indented past the control; `"comfortable"` stacks label + supporting text beside the control. Reflected. |
|
|
77
|
+
| `alignment` | `alignment` | `"leading" \| "trailing"` | `"leading"` | Control position (Figma Layout). `"leading"` (default) renders the control before the label; `"trailing"` pushes it to the far edge of the row. Trailing has no compact layout in the spec, so it always renders with comfortable density. Meant for vertical orientation — trailing options stretch to the group's full width. Reflected. |
|
|
78
|
+
| `selectedValue` | `selected-value` | `string \| null` | `null` | `value` of the currently selected option, or `null` when nothing is selected. Set it to preselect an option; it is updated on every user selection. Reflected (as `selectedvalue` in 1.x). The `selectedvalue` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
79
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables every option (Figma State=Disabled: the whole group at 40% opacity). Individual options can also be disabled via `RadioOption.disabled`. An ancestor `<fieldset disabled>` disables the group the same way, without changing this property. |
|
|
80
|
+
| `error` | `error` | `boolean` | `false` | Error state (Figma State=Error): rings, dots and supporting text turn danger. Applies to every option while nothing is selected, and only to the selected option once a choice is made. Selection is still allowed. |
|
|
81
|
+
| `errorMessage` | `error-message` | `string` | `""` | Message rendered under the group (live region) while `error` is set; hidden when `error` is false or the text is empty. The `errormessage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
82
|
+
| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the radiogroup (it renders no visible group label). Unset, an outer `<label>` (wrapping the group, or `for=`) names it instead. |
|
|
83
|
+
| `value` | `value` | `string` | `""` | Value reported to the Angular forms bridge (`registerOnChange` callback) on each change and compared by `writeValue`. Not used for rendering; read `selectedValue` or the `lof-change` detail for the selected option. |
|
|
84
|
+
|
|
85
|
+
### Public fields / accessors
|
|
86
|
+
|
|
87
|
+
| Name | Type | Description |
|
|
88
|
+
| --- | --- | --- |
|
|
89
|
+
| `checked` | `boolean` | Set by the Angular forms bridge (`writeValue`) to whether the written form value equals `value`. Not used for rendering — read `selectedValue` for the selection. |
|
|
90
|
+
|
|
91
|
+
## Events
|
|
92
|
+
|
|
93
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
94
|
+
| --- | --- | --- | --- |
|
|
95
|
+
| `lof-change` | `{ value, checked: true }` | bubbles / composed | Fired when the user selects an option (after `selectedValue` is updated). Detail: `{ value: string, checked: true }` — `value` is the selected option's value. |
|
|
96
|
+
|
|
97
|
+
## Slots
|
|
98
|
+
|
|
99
|
+
| Slot | Description |
|
|
100
|
+
| --- | --- |
|
|
101
|
+
| — | This element has no slots. |
|
|
102
|
+
|
|
103
|
+
## CSS Parts
|
|
104
|
+
|
|
105
|
+
| Part | Description |
|
|
106
|
+
| --- | --- |
|
|
107
|
+
| `label` | The visible label text of each option |
|
|
108
|
+
| `base` | The `role="radiogroup"` container that lays out the options |
|
|
109
|
+
|
|
110
|
+
<!-- readme-gen:end -->
|
|
111
|
+
|
|
112
|
+
## Accessibility
|
|
113
|
+
|
|
114
|
+
- The option container (part `base`) is a `role="radiogroup"` with `aria-orientation` = `orientation`, `aria-label` = `field-aria-label` (the group renders no visible legend, so name it with this or an outer `<label>`) and `aria-describedby` pointing at the error line.
|
|
115
|
+
- An outer `<label>` (`<label for="plan">Plan</label><lof-radio id="plan">`, or wrapped around the group) names the GROUP: the element is form-associated, and the label's text is copied into the radiogroup's `aria-label` when `field-aria-label` is unset. Clicking the label does not select anything. It moves focus onto the selected option, or the first enabled one when nothing is selected (where Tab would land), with no `lof-change`; then the arrow keys choose. A disabled group ignores the click. Clicking an option inside a wrapping label behaves as it always has.
|
|
116
|
+
- Every option is a native `<input type="radio">` inside a `<label>`, so the whole row (control, label, supporting text) is the click target and the input's accessible name is the option label. The input is visually hidden (`opacity: 0`, absolutely positioned over the row) but stays in the Tab order; the drawn ring / dot mirror its `:checked` state.
|
|
117
|
+
- Disabled options get the native `disabled` attribute (skipped by Tab and arrow keys) and render at 40% opacity; `disabled` on the host disables all of them.
|
|
118
|
+
- The error message is a persistent `aria-live="polite"` region under the group, so a message that appears after submission is read out.
|
|
119
|
+
- Avatar chips are `aria-hidden`; a prefix icon is a `<lof-icon>` and decorative.
|
|
120
|
+
- Keyboard focus is shown as a 2px `--lof-border-focus` outline, flush (no offset), around the focused option; it appears only for `:focus-visible` (keyboard) focus.
|
|
121
|
+
- In forced-colors mode (Windows High Contrast) the ring is drawn as a 1px `CanvasText` border and the selected dot is painted `CanvasText`, because the normal ring (an inset box-shadow) and the dot's background are not painted there.
|
|
122
|
+
- Keyboard behaviour is the browser's native radio behaviour — the component adds no key handlers of its own:
|
|
123
|
+
|
|
124
|
+
| Key | Action |
|
|
125
|
+
| --- | --- |
|
|
126
|
+
| Tab / Shift + Tab | Enter the group (on the checked option, else the first enabled one) or leave it |
|
|
127
|
+
| ArrowDown / ArrowRight | Move to the next enabled option and select it (fires `lof-change`) |
|
|
128
|
+
| ArrowUp / ArrowLeft | Move to the previous enabled option and select it (fires `lof-change`) |
|
|
129
|
+
| Space | Select the focused option if it is not yet selected |
|
|
130
|
+
|
|
131
|
+
## Notes / Edge Cases
|
|
132
|
+
|
|
133
|
+
- `RadioOption` shape: `{ value: string; label: string; supportingText?: string; disabled?: boolean; icon?: string; avatar?: string }`. `icon` is a `lof-icon` name rendered before the label (Figma Has Icon/Avatar, Type=Icon); `avatar` is 1–2 initials rendered as a circular chip and is ignored when `icon` is also set.
|
|
134
|
+
- `lof-change` fires only on user selection. Setting `selectedValue` from code (or via the `selected-value` attribute) updates the UI silently.
|
|
135
|
+
- Grouping by `name`: the native inputs of one `<lof-radio>` share `name`, which is what gives arrow-key movement and mutual exclusion; they live in the element's shadow root, so they are not submitted with a surrounding `<form>`. The element itself is form-associated (for the outer `<label>`) but sets no form value, so that does not change; it does now appear in `form.elements`. Read `selectedValue` or listen to `lof-change` to collect the value. Give every group on a page its own `name` so the intent is unambiguous.
|
|
136
|
+
- Error rules: while nothing is selected, every option shows the danger ring; once an option is selected only that option does. Labels keep their default colour; rings, dots and supporting text turn `--lof-text-danger`. Error never blocks selection.
|
|
137
|
+
- `alignment="trailing"` always renders comfortable density. Combining it with `density="compact"` logs `[lof-radio] density="compact" has no trailing layout; rendering comfortable density.` (a `console.warn`, every time either prop changes).
|
|
138
|
+
- Compact supporting text is indented past the control box: 28px (S/M) and 32px (L). Comfortable density widens the control-to-label gap from 8px to 12px.
|
|
139
|
+
- Hover shifts the ring and dot from `--lof-text-default` to `--lof-text-body`, and the label and prefix icon to `--lof-text-label`, on enabled, non-error options.
|
|
140
|
+
- `value` and `checked` exist for the Angular forms bridge (`registerOnChange` / `registerOnTouched` / `writeValue`, which are internal API). The bridge callback receives the `value` property, not the selected option — plain DOM consumers should ignore both and use `selectedValue` / `lof-change`.
|
|
141
|
+
- `<lof-menu type="select-option">` renders an `inert`, `aria-hidden` `<lof-radio>` inside each row purely as a visual control; that usage does not fire `lof-change`.
|
|
142
|
+
- The hidden native input is absolutely positioned inside a `position: relative` row on purpose — without that containing block, tabbing to it scrolls the wrong ancestor and jumps the page (shared fix with `lof-checkbox`).
|