@lofid/web 0.0.0-stage → 1.0.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.
Files changed (55) hide show
  1. package/README.md +85 -2
  2. package/custom-elements.json +11166 -0
  3. package/dist/index.d.ts +2784 -0
  4. package/dist/index.js +18710 -0
  5. package/dist/index.js.map +1 -0
  6. package/dist/styles/ag-grid.css +145 -0
  7. package/dist/styles/motion.css +32 -0
  8. package/dist/styles/motion.tokens.json +38 -0
  9. package/dist/styles/vars.css +870 -0
  10. package/package.json +44 -4
  11. package/readmes/lof-accordion/README.md +140 -0
  12. package/readmes/lof-alert/README.md +142 -0
  13. package/readmes/lof-autocomplete/README.md +209 -0
  14. package/readmes/lof-avatar/README.md +228 -0
  15. package/readmes/lof-badge/README.md +102 -0
  16. package/readmes/lof-breadcrumb/README.md +97 -0
  17. package/readmes/lof-button/README.md +190 -0
  18. package/readmes/lof-calendar/README.md +111 -0
  19. package/readmes/lof-card/README.md +75 -0
  20. package/readmes/lof-cardmedia/README.md +100 -0
  21. package/readmes/lof-carousel/README.md +187 -0
  22. package/readmes/lof-checkbox/README.md +159 -0
  23. package/readmes/lof-chip/README.md +141 -0
  24. package/readmes/lof-container/README.md +107 -0
  25. package/readmes/lof-date-picker/README.md +221 -0
  26. package/readmes/lof-divider/README.md +88 -0
  27. package/readmes/lof-drawer/README.md +188 -0
  28. package/readmes/lof-kbd/README.md +188 -0
  29. package/readmes/lof-layout/README.md +122 -0
  30. package/readmes/lof-menu/README.md +187 -0
  31. package/readmes/lof-menubar/README.md +218 -0
  32. package/readmes/lof-otp/README.md +167 -0
  33. package/readmes/lof-pagination/README.md +141 -0
  34. package/readmes/lof-popover/README.md +220 -0
  35. package/readmes/lof-progress/README.md +88 -0
  36. package/readmes/lof-radio/README.md +142 -0
  37. package/readmes/lof-range-picker/README.md +194 -0
  38. package/readmes/lof-resizable/README.md +220 -0
  39. package/readmes/lof-segmented-button/README.md +158 -0
  40. package/readmes/lof-select/README.md +193 -0
  41. package/readmes/lof-sheet/README.md +170 -0
  42. package/readmes/lof-signature-pad/README.md +161 -0
  43. package/readmes/lof-skeleton/README.md +104 -0
  44. package/readmes/lof-slider/README.md +140 -0
  45. package/readmes/lof-snackbar/README.md +170 -0
  46. package/readmes/lof-split-button/README.md +129 -0
  47. package/readmes/lof-stepper/README.md +171 -0
  48. package/readmes/lof-switch/README.md +122 -0
  49. package/readmes/lof-tab/README.md +184 -0
  50. package/readmes/lof-textfield/README.md +206 -0
  51. package/readmes/lof-time-picker/README.md +188 -0
  52. package/readmes/lof-toast/README.md +174 -0
  53. package/readmes/lof-tooltip/README.md +120 -0
  54. package/readmes/lof-tree/README.md +157 -0
  55. package/readmes/lof-upload/README.md +223 -0
@@ -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 2px 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 2px tall with a 4px radius and stretch to the host's width (host is `display: block`). 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 (S and M share the 20px control; L is 24px) -->
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, matching Figma's Size axis. `"small"` and `"medium"` (default) both draw a 20px control — they differ by TYPE, body-md labels against body-lg — and `"large"` steps the control to 24px with body-xl labels. Supporting text sits one body step below the label at every size (body-sm / md / lg, i.e. 12 / 14 / 16px). `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Small and Medium sharing a control is Figma's design, not an oversight: verified against the live Published DS file on 2026-09-25, `.Radio Control` measures 20x20 in all 15 Small variants and all 15 Medium ones. v1.4.8 briefly gave Small its own 16px control on the mistaken premise that the ramp was 16/20/24; 1.4.9 reverts that. 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`).