@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,218 @@
1
+ # lof-menubar
2
+
3
+ `<lof-menubar>` is a horizontal application menubar (`role="menubar"`) in the style of a desktop app's File / Edit / View strip. Each child `<lof-menubar-menu label="…">` becomes a trigger button, and that menu's light-DOM children — `data-item` buttons, `data-separator` rules, `data-submenu` groups, `data-checkbox` labels and `data-radio-group` blocks — are read by the menubar and rendered into a fixed-position dropdown panel with full arrow-key navigation, optional bound keyboard shortcuts and `lof-menubar-select` / `lof-menubar-change` events. Use it for dense, command-style navigation in tools and admin surfaces. For one dropdown hanging off a single button use `lof-menu`; for site navigation with links use the Navbar recipe (`/docs/recipes/navbar`).
4
+
5
+ ## Usage
6
+
7
+ ```html
8
+ <lof-menubar>
9
+ <lof-menubar-menu label="File">
10
+ <button data-item data-shortcut="Ctrl+N">New Tab</button>
11
+ <button data-item data-shortcut="Ctrl+Shift+N">New Window</button>
12
+ <div data-separator></div>
13
+ <button data-item disabled>Close</button>
14
+ </lof-menubar-menu>
15
+
16
+ <lof-menubar-menu label="Edit">
17
+ <button data-item data-shortcut="Ctrl+Z">Undo</button>
18
+ <button data-item data-shortcut="Ctrl+Y">Redo</button>
19
+ <div data-separator></div>
20
+ <button data-item data-shortcut="Ctrl+X">Cut</button>
21
+ <button data-item data-shortcut="Ctrl+C">Copy</button>
22
+ <button data-item data-shortcut="Ctrl+V">Paste</button>
23
+ </lof-menubar-menu>
24
+ </lof-menubar>
25
+ ```
26
+
27
+ ### Width mode and disabled menus
28
+
29
+ ```html
30
+ <!-- type="fit" (default) hugs its triggers; type="fixed" spans its container -->
31
+ <lof-menubar type="fixed">
32
+ <lof-menubar-menu label="File">
33
+ <button data-item>New Tab</button>
34
+ </lof-menubar-menu>
35
+ <lof-menubar-menu label="Edit">
36
+ <button data-item>Undo</button>
37
+ </lof-menubar-menu>
38
+ <!-- a disabled menu keeps its trigger visible and focusable but never opens -->
39
+ <lof-menubar-menu label="View" disabled>
40
+ <button data-item>Zoom In</button>
41
+ </lof-menubar-menu>
42
+ </lof-menubar>
43
+ ```
44
+
45
+ ### Submenus, checkbox items and radio groups
46
+
47
+ ```html
48
+ <lof-menubar>
49
+ <lof-menubar-menu label="File">
50
+ <button data-item>New Tab</button>
51
+ <div data-separator></div>
52
+ <div data-submenu label="Share">
53
+ <button data-item value="email">Email link</button>
54
+ <button data-item value="messages">Messages</button>
55
+ <button data-item value="notes">Notes</button>
56
+ </div>
57
+ </lof-menubar-menu>
58
+
59
+ <lof-menubar-menu label="View">
60
+ <label data-checkbox>
61
+ <input type="checkbox" />
62
+ Always Show Bookmarks Bar
63
+ </label>
64
+ <label data-checkbox>
65
+ <input type="checkbox" checked />
66
+ Always Show Full URLs
67
+ </label>
68
+ <div data-separator></div>
69
+ <div data-radio-group name="profile" value="andy">
70
+ <button data-radio value="andy">Andy</button>
71
+ <button data-radio value="benoit">Benoit</button>
72
+ <button data-radio value="luis">Luis</button>
73
+ </div>
74
+ </lof-menubar-menu>
75
+ </lof-menubar>
76
+ ```
77
+
78
+ ### Bound shortcuts and events
79
+
80
+ ```html
81
+ <lof-menubar id="app-menubar" bind-shortcuts>
82
+ <lof-menubar-menu label="Edit">
83
+ <button data-item value="undo" data-shortcut="Mod+Z">Undo</button>
84
+ <button data-item value="redo" data-shortcut="Mod+Shift+Z">Redo</button>
85
+ </lof-menubar-menu>
86
+ </lof-menubar>
87
+
88
+ <script>
89
+ const bar = document.getElementById('app-menubar');
90
+ // { label: "Undo", value: "undo", shortcut: "Mod+Z" }
91
+ bar.addEventListener('lof-menubar-select', (e) => console.log('select', e.detail));
92
+ // { type: "checkbox", label, checked } | { type: "radio", name, value }
93
+ bar.addEventListener('lof-menubar-change', (e) => console.log('change', e.detail));
94
+ </script>
95
+ ```
96
+
97
+ ### Authoring items
98
+
99
+ Items are plain HTML placed inside a `<lof-menubar-menu>`; the menubar recognises them by data attribute and renders its own copy in the panel.
100
+
101
+ | Attribute | Put it on | What it becomes |
102
+ | --- | --- | --- |
103
+ | `data-item` | `<button>` | A `role="menuitem"` row. Its text content is the label; `value` (optional) and `data-shortcut` are echoed in `lof-menubar-select`. A native `disabled` attribute renders the row `aria-disabled` and skips it for clicks and bound shortcuts. |
104
+ | `data-shortcut` | a `data-item` button | Shortcut text shown right-aligned in the row, exactly as written. With `bind-shortcuts` it is also matched against keydowns: `+`-joined tokens, case-insensitive, `Mod` = Cmd on Apple / Ctrl elsewhere, plus `Ctrl`, `Alt`, `Shift`, `Meta`. |
105
+ | `data-separator` | `<div>` | A `role="separator"` rule. |
106
+ | `data-submenu` + `label` | `<div>` wrapping `data-item` buttons | A submenu trigger row (`aria-haspopup="menu"`) that opens a nested panel to the right on hover, click, Enter or ArrowRight. |
107
+ | `data-checkbox` | `<label>` containing `<input type="checkbox">` | A `lof-checkbox` row. The label text is the element's own text nodes (or a `label` attribute); state lives on the wrapped `<input>`. |
108
+ | `data-radio-group` + `name` + `value` | `<div>` wrapping `data-radio` buttons | A `lof-radio` group. `value` on the wrapper is the current selection and is rewritten on change; the chosen `data-radio` also gets `data-checked="true"`. |
109
+ | `data-radio` + `value` | `<button>` inside a `data-radio-group` | One option; text content is its label. |
110
+
111
+ <!-- readme-gen:start -->
112
+
113
+ <!-- Generated from lof-menubar.ts, lof-menubar-menu.ts — do not edit; run readme-generate.mjs -->
114
+
115
+ ## Elements
116
+
117
+ | Element | Class | Source |
118
+ | --- | --- | --- |
119
+ | `<lof-menubar>` | `LofMenubar` | `lof-menubar.ts` |
120
+ | `<lof-menubar-menu>` | `LofMenubarMenu` | `lof-menubar-menu.ts` |
121
+
122
+ ## API
123
+
124
+ ### `<lof-menubar>`
125
+
126
+ #### Attributes / Properties
127
+
128
+ | Property | Attribute | Type | Default | Description |
129
+ | --- | --- | --- | --- | --- |
130
+ | `bindShortcuts` | `bind-shortcuts` | `boolean` | `false` | Opt-in: actually bind the keys declared via `data-shortcut` on items (e.g. `data-shortcut="Ctrl+Z"`) instead of only displaying them; a "Mod" token means Cmd on Apple platforms and Ctrl elsewhere, and keystrokes that originate in inputs, textareas or contenteditable regions are ignored. |
131
+ | `type` | `type` | `"fixed" \| "fit"` | `"fit"` | Width mode (Figma "Menu Bar" Type, 8699:4): `fit` sizes the bar to its triggers, `fixed` stretches it across its container (override the stretched width with `--lof-menubar-width`). The default stays `fit`, which is how the bar has always rendered. Reflected. |
132
+
133
+ ### Events
134
+
135
+ | Event | Detail | Bubbles / composed | Description |
136
+ | --- | --- | --- | --- |
137
+ | `lof-menubar-change` | `detail` | bubbles / composed | Fired when a `data-checkbox` item is toggled or a `data-radio` option is picked. Detail: `{ type: "checkbox", label, checked }` or `{ type: "radio", name, value }`. |
138
+ | `lof-menubar-select` | `{ label: item.textContent?.trim() ?? "", value: item.getAttribute("value") ?? undefined, shortcut: item.getAttribute("data-shortcut") ?? undefined, }` | bubbles / composed | Fired when a regular `data-item` (in a panel or a submenu) is activated by click, Enter/Space or a bound shortcut. Detail: `{ label: string, value?: string, shortcut?: string }` taken from the item's text, `value` and `data-shortcut` attributes. |
139
+
140
+ ### Slots
141
+
142
+ | Slot | Description |
143
+ | --- | --- |
144
+ | — | This element has no slots. |
145
+
146
+ ### CSS Parts
147
+
148
+ | Part | Description |
149
+ | --- | --- |
150
+ | — | None exposed. |
151
+
152
+ ### `<lof-menubar-menu>`
153
+
154
+ #### Attributes / Properties
155
+
156
+ | Property | Attribute | Type | Default | Description |
157
+ | --- | --- | --- | --- | --- |
158
+ | `label` | `label` | `string` | `""` | Text of the trigger button the parent menubar renders for this menu. |
159
+ | `disabled` | `disabled` | `boolean` | `false` | Renders this menu's trigger in the Figma State=Disabled style and stops it opening by pointer, keyboard or hover-switch. The trigger stays in the tab order and reachable with the arrow keys (`aria-disabled`, not the native `disabled` attribute), matching how disabled `data-item` rows behave. Reflected. |
160
+
161
+ ### Events
162
+
163
+ | Event | Detail | Bubbles / composed | Description |
164
+ | --- | --- | --- | --- |
165
+ | — | — | — | This element emits no custom events. |
166
+
167
+ ### Slots
168
+
169
+ | Slot | Description |
170
+ | --- | --- |
171
+ | — | This element has no slots. |
172
+
173
+ ### CSS Parts
174
+
175
+ | Part | Description |
176
+ | --- | --- |
177
+ | — | None exposed. |
178
+
179
+ <!-- readme-gen:end -->
180
+
181
+ ## Accessibility
182
+
183
+ - Roles follow the APG menubar pattern: the strip is `role="menubar"`; each trigger is a `<button role="menuitem" aria-haspopup="menu" aria-expanded="true|false">`; each dropdown is a `role="menu"` panel with `tabindex="-1"`; rows are `role="menuitem"` (disabled ones add `aria-disabled="true"`), separators are `role="separator"`, and a submenu trigger row carries `aria-haspopup="menu"` / `aria-expanded` with its own nested `role="menu"` panel.
184
+ - Focus model: the triggers are real buttons in the tab order. When a menu opens from the keyboard, DOM focus moves to the panel itself and the highlighted row is exposed through `aria-activedescendant` (row ids are generated per menubar instance), so arrow keys move a virtual focus rather than DOM focus. `Escape` closes everything and returns DOM focus to the trigger that owned the menu.
185
+ - Checkbox items render as `lof-checkbox` and radio groups as `lof-radio` inside the panel, so those rows carry the native checkbox / radiogroup semantics of those components.
186
+ - There is no type-ahead and no wrap-around: arrow keys stop at the first / last trigger or row.
187
+ - Bound shortcuts (`bind-shortcuts`) listen on `document`, skip events whose `defaultPrevented` is already set, skip keystrokes that start in an input, textarea, select or contenteditable, and call `preventDefault()` on a match.
188
+
189
+ | Key | Where | Action |
190
+ | --- | --- | --- |
191
+ | `Tab` / `Shift+Tab` | anywhere | Native focus movement between the trigger buttons (and out of the menubar). |
192
+ | `ArrowRight` / `ArrowLeft` | trigger | Move focus to the next / previous trigger (does not open it). |
193
+ | `Enter` / `Space` / `ArrowDown` | trigger | Open that menu, focus the panel and highlight the first item. |
194
+ | `Enter` / `Space` / `ArrowDown` | trigger of a `disabled` menu | Nothing — the trigger is reachable but never opens. |
195
+ | `Escape` | trigger (menu open) | Close all menus and keep focus on the trigger. |
196
+ | `ArrowDown` / `ArrowUp` | open panel | Highlight the next / previous item (clamped, no wrap). |
197
+ | `Home` / `End` | open panel | Highlight the first / last item. |
198
+ | `ArrowRight` | open panel, on a submenu row | Open the submenu and highlight its first item. |
199
+ | `Enter` / `Space` | open panel | Activate the highlighted row: fire `lof-menubar-select` and close, toggle a checkbox, pick a radio option, or open a submenu. |
200
+ | `Escape` | open panel | Close all menus and return focus to the trigger. |
201
+ | `ArrowDown` / `ArrowUp` / `Home` / `End` | open submenu | Move the highlight inside the submenu. |
202
+ | `ArrowLeft` / `Escape` | open submenu | Close only the submenu; the parent panel stays open and focused. |
203
+ | `Enter` / `Space` | open submenu | Activate the highlighted sub-item: fire `lof-menubar-select`, close everything, refocus the trigger. |
204
+
205
+ ## Notes / Edge Cases
206
+
207
+ - Both elements render into **light DOM** (`createRenderRoot()` returns the host): there are no slots, no `::part` hooks and no style encapsulation. The menubar injects its own `<style>` block; the `.menubar-trigger` / `.menubar-panel` / `.menu-item` class names are implementation details, not a styling contract.
208
+ - `<lof-menubar-menu>` is a hidden data holder (`display: none`) — it never renders its children itself. The menubar discovers menus once, when it connects; menus added or removed later are not picked up until the menubar is re-attached. Item lists inside a menu are re-read on each render, so item changes show up the next time a panel opens.
209
+ - Item content is flattened: a `data-item` row renders the button's `textContent` only, so markup inside the button (icons, `<lof-kbd>` chips) is not reproduced. Use `data-shortcut` for the shortcut hint — it is displayed verbatim, so `Mod+Z` is shown literally as "Mod+Z"; write `Ctrl+Z` if you want that text and only need Ctrl.
210
+ - Panels are `position: fixed` (z-index 1000, submenus 1001), placed flush under the trigger / against the right edge of the submenu row, and repositioned on scroll. They are not moved into the top layer, so a `lof-modal` or other top-layer surface can cover them.
211
+ - Panels are a fixed 300px wide, matching the Figma Menu component the bar is paired with; override with `--lof-menubar-panel-width`. There is no viewport clamping, so a panel opened near the right edge can overflow.
212
+ - The bar follows Figma's Menu Bar geometry: 40px tall triggers (`spacing/xs` × `spacing/md` padding on a `body/lg` label) on a `bg/fill/neutral/default` surface with `border-radius/sm` and no border. The trigger whose menu is open takes the hover overlay plus a medium-weight label, which widens it by a pixel or two — that weight shift is in the Figma spec, not an artefact.
213
+ - A `disabled` `<lof-menubar-menu>` renders its trigger in the disabled tone and refuses to open by click, hover-switch, Enter/Space/ArrowDown or a bound shortcut. It uses `aria-disabled`, not the native `disabled` attribute, so the trigger stays in the tab order — the same model the disabled `data-item` rows use.
214
+ - With a menu already open the bar is in hover-switch mode: moving the pointer onto another trigger opens that menu, so a *click* on it arrives when it is already open and toggles it shut. Switch menus by hovering, or click twice.
215
+ - Hover-switching between menus is armed only after a click has opened one; hovering triggers on a closed menubar does nothing. Clicking outside (checked via `composedPath`, so it works inside shadow roots) closes everything.
216
+ - Disabled `data-item` buttons ignore pointer clicks and bound shortcuts but are still reachable with the arrow keys.
217
+ - `lof-menubar-select` fires only for regular `data-item` rows (panel or submenu); checkbox and radio rows fire `lof-menubar-change` instead. Both events bubble and are composed.
218
+ - Only one submenu can be open at a time, and submenus nest one level deep (a `data-submenu` inside a `data-submenu` is not rendered).
@@ -0,0 +1,167 @@
1
+ # lof-otp
2
+
3
+ A one-time-password input implementing the Figma "OTP Input" cell: one single-character `<input>` per position, with auto-advance, smart backspace, paste distribution, mobile OTP autofill and optional group separators. The cells accept digits only (`input-mode="numeric"`, the default) or digits plus ASCII letters (`input-mode="alphanumeric"`), and can be masked password-style. Use it for SMS / authenticator verification codes and PINs; for free-form text use `lof-textfield`.
4
+
5
+ ## Usage
6
+
7
+ ```html
8
+ <!-- 6-digit numeric code in two groups of three -->
9
+ <lof-otp length="6" group-size="3"></lof-otp>
10
+
11
+ <!-- Alphanumeric, masked, four per group, custom accessible name -->
12
+ <lof-otp
13
+ length="8"
14
+ input-mode="alphanumeric"
15
+ mask
16
+ group-size="4"
17
+ aria-label="Enter 8-character code">
18
+ </lof-otp>
19
+
20
+ <!-- Sizes: small 32px / medium 40px (default) / large 48px cells -->
21
+ <lof-otp size="small" length="4"></lof-otp>
22
+ <lof-otp size="medium" length="6"></lof-otp>
23
+ <lof-otp size="large" length="6"></lof-otp>
24
+
25
+ <!-- Form integration: `name` renders a hidden input carrying the value -->
26
+ <form id="verify-form">
27
+ <lof-otp id="otp-form" name="verification_code" length="6" required></lof-otp>
28
+ <button type="submit">Verify</button>
29
+ </form>
30
+ <script>
31
+ const form = document.getElementById('verify-form');
32
+ const otp = document.getElementById('otp-form');
33
+
34
+ form.addEventListener('submit', (e) => {
35
+ e.preventDefault();
36
+ console.log('OTP:', new FormData(form).get('verification_code'));
37
+ });
38
+
39
+ otp.addEventListener('lof-change', (e) => {
40
+ console.log('Value:', e.detail.value, 'Complete:', e.detail.complete);
41
+ otp.invalid = false;
42
+ });
43
+
44
+ otp.addEventListener('lof-complete', async (e) => {
45
+ otp.disabled = true;
46
+ const ok = await verifyOtp(e.detail.value);
47
+ otp.disabled = false;
48
+ if (!ok) {
49
+ otp.invalid = true; // danger border + aria-invalid
50
+ otp.value = ''; // clear for retry
51
+ }
52
+ });
53
+ </script>
54
+
55
+ <!-- No separators ("false" switches a default-true boolean off, since 1.5.0) -->
56
+ <lof-otp length="6" show-separator="false"></lof-otp>
57
+
58
+ <!-- States -->
59
+ <lof-otp value="123456" readonly></lof-otp>
60
+ <lof-otp value="12" disabled></lof-otp>
61
+ <lof-otp invalid length="6"></lof-otp>
62
+ ```
63
+
64
+ ### Deprecated aliases
65
+
66
+ ```html
67
+ <!-- type= is a deprecated alias of input-mode; input-mode wins when both are set.
68
+ Logs once per page:
69
+ [lof-otp] "type" is deprecated and will be removed in 3.0 — use "input-mode" instead. It describes the accepted characters, not a semantic input type. -->
70
+ <lof-otp type="alphanumeric" length="8"></lof-otp>
71
+
72
+ <!-- sm / md / lg are deprecated aliases of size="small" / "medium" / "large" (no console notice) -->
73
+ <lof-otp size="lg" length="6"></lof-otp>
74
+ ```
75
+
76
+ <!-- readme-gen:start -->
77
+
78
+ <!-- Generated from lof-otp.ts — do not edit; run readme-generate.mjs -->
79
+
80
+ ## API
81
+
82
+ ### Attributes / Properties
83
+
84
+ | Property | Attribute | Type | Default | Description |
85
+ | --- | --- | --- | --- | --- |
86
+ | `value` | `value` | `string` | `""` | The concatenated code (all cells joined). Set it to fill the cells programmatically; it never exceeds `length` characters. Reflected. |
87
+ | `length` | `length` | `number` | `6` | Total number of cells (characters in the code). |
88
+ | `groupSize` | `group-size` | `number` | `3` | Cells per visual group; a separator renders between groups. Grouping applies only when `length` divides evenly by this — otherwise the row renders ungrouped, because a ragged final group would put a separator before a lone cell. So the default `length="6"` is 3–3, `length="4"` is one ungrouped row of four, and `group-size="2"` with `length="4"` is 2–2. `0` (or `show-separator` off) also renders one ungrouped row. |
89
+ | `placeholder` | `placeholder` | `string` | `""` | Placeholder character shown in every empty cell. |
90
+ | `inputMode` | `input-mode` | `"numeric" \| "alphanumeric" \| ""` | `""` | Accepted character set (Trello 5). Describes what the field ACCEPTS, not a semantic input type — hence the name. Explicitly set it wins over the deprecated `type`; unset (`""`, like the native `inputMode` accessor it shadows on the host), `type` (default `"numeric"`) applies. Note the lowercase `inputmode` prop is a different thing: the raw native keyboard hint forwarded to each cell. |
91
+ | `mask` | `mask` | `boolean` | `false` | Renders the cells as `type="password"` so entered characters are masked. |
92
+ | `disabled` | `disabled` | `boolean` | `false` | Disables every cell and dims the control to 0.4 opacity (cell fill and border unchanged, as Figma specifies). Reflected. |
93
+ | `readonly` | `readonly` | `boolean` | `false` | Makes every cell read-only: the value is shown but typing, paste and keyboard editing are ignored. Reflected. |
94
+ | `required` | `required` | `boolean` | `false` | Marks the first cell `required` for native form validation. |
95
+ | `name` | `name` | `string \| null` | `null` | When set, renders a hidden `<input name="…">` (part `hidden-input`) carrying `value` for native form submission. |
96
+ | `autocomplete` | `autocomplete` | `string` | `"one-time-code"` | Reserved autocomplete hint. Currently every cell always renders `autocomplete="one-time-code"` regardless of this value. |
97
+ | `inputmode` | `inputmode` | `"numeric" \| "text" \| null` | `null` | Raw native `inputmode` keyboard hint forwarded to every cell. Unset, it follows the accepted character set: `numeric` for numeric, `text` for alphanumeric. |
98
+ | `pattern` | `pattern` | `string \| null` | `null` | Native `pattern` attribute forwarded to every cell (per-character regex for form validation). |
99
+ | `ariaLabel` | `aria-label` | `string \| null` | `null` | Accessible name of the whole group; defaults to "One-time password input". Each cell is additionally labelled "Digit/Character N of M". |
100
+ | `invalid` | `invalid` | `boolean` | `false` | Error styling (danger border on every cell) and `aria-invalid="true"`. Reflected. |
101
+ | `showSeparator` | `show-separator` | `boolean` | `true` | Renders the dash separator between groups. Presence or `""` means true; `show-separator="false"` (or the property set to `false`) hides them. Even when on, separators appear only if `length` divides evenly by `group-size`; see `groupSize`. |
102
+ | `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Cell size on the shared field scale (square, border-box): `small` 32px, `medium` 40px, `large` 48px (the Figma OTP Input cell). `sm` / `md` / `lg` are deprecated aliases of the full words. Reflected. |
103
+
104
+ #### Deprecated (still supported — removal targeted for 3.0)
105
+
106
+ | Property | Attribute | Type | Use instead |
107
+ | --- | --- | --- | --- |
108
+ | `type` | `type` | `"numeric" \| "alphanumeric"` | Deprecated alias of `inputMode` (attribute `input-mode`); use `input-mode` instead. Kept working in 1.x and logs a one-time console notice. |
109
+
110
+ ## Events
111
+
112
+ | Event | Detail | Bubbles / composed | Description |
113
+ | --- | --- | --- | --- |
114
+ | `lof-change` | `{ value: newValue, complete }` | bubbles / composed | Fired on every value change (typing, backspace, delete, paste). Detail: `{ value: string, complete: boolean }` — `complete` is true when all cells hold a valid character. |
115
+ | `lof-complete` | `{ value: newValue }` | bubbles / composed | Fired after `lof-change` once every cell holds a valid character. Detail: `{ value: string }` (the full code). |
116
+
117
+ ## Slots
118
+
119
+ | Slot | Description |
120
+ | --- | --- |
121
+ | — | This element has no slots. |
122
+
123
+ ## CSS Parts
124
+
125
+ | Part | Description |
126
+ | --- | --- |
127
+ | `base` | The `role="group"` root container (same element as `root`) |
128
+ | `root` | Alias of `base`, kept for existing `::part(root)` selectors |
129
+ | `input` | Each single-character cell input (same element as `cell`) |
130
+ | `cell` | Alias of `input`, kept for existing `::part(cell)` selectors |
131
+ | `separator` | The dash rendered between cell groups |
132
+ | `hidden-input` | The hidden form input rendered when `name` is set |
133
+
134
+ <!-- readme-gen:end -->
135
+
136
+ ## Accessibility
137
+
138
+ - The root renders `role="group"` with `aria-label` from the `aria-label` attribute (default "One-time password input").
139
+ - Every cell is a native `<input maxlength="1">` labelled "Digit N of M" (numeric) or "Character N of M" (alphanumeric), so screen readers announce the position while focus auto-advances.
140
+ - `invalid` sets `aria-invalid="true"` on every cell; `disabled`, `readonly` and `required` (first cell only) are the native attributes.
141
+ - The native `inputmode` hint on each cell follows the accepted character set — `numeric` for `input-mode="numeric"`, `text` for `alphanumeric` — unless the raw `inputmode` prop overrides it. Every cell carries `autocomplete="one-time-code"` so iOS / Android can inject an SMS code; a multi-character injection into any cell is distributed like a paste.
142
+ - Focus management: focusing a cell selects its content (replace-on-type); a pointer-down on a cell beyond the first empty one is redirected to that empty cell so the code cannot be entered out of order; after paste focus lands on the next empty cell (or the last cell when full).
143
+ - Live-region announcements (via the shared `announce()` utility): "Code complete" when every cell holds a valid character, and "N digits/characters entered" after a paste that does not fill the code.
144
+
145
+ | Key | Action |
146
+ | --- | --- |
147
+ | `0-9` (numeric) / `0-9` `A-Z` `a-z` (alphanumeric) | Enter the character and advance to the next cell; other characters are rejected |
148
+ | `Backspace` | Clear the current cell; if it is already empty, move to the previous cell and clear it |
149
+ | `Delete` | Clear the current cell and stay |
150
+ | `ArrowLeft` / `ArrowRight` | Move to the previous / next cell |
151
+ | `Home` / `End` | Jump to the first / last cell |
152
+ | `ArrowUp` / `ArrowDown` | Ignored (prevented so the page does not scroll) |
153
+ | `Ctrl/Cmd+V` | Paste: valid characters are distributed from the current cell onward, overflow past `length` is dropped |
154
+ | `Tab` / `Shift+Tab` | Move focus between cells (each cell is a tab stop) |
155
+
156
+ ## Notes / Edge Cases
157
+
158
+ - `value` is truncated to `length` characters when synced into the cells; changing `length` re-initialises the cells from `value`.
159
+ - `lof-change` fires on every edit; `lof-complete` fires right after it when all cells hold a valid character for the current mode — validate the code server-side, the component only checks the character set.
160
+ - `input-mode` unset (`""`) falls back to the deprecated `type` prop (default `"numeric"`); set `input-mode` explicitly and it always wins.
161
+ - The lowercase `inputmode` prop is the raw native keyboard hint, not the accepted character set — normally leave it unset.
162
+ - `show-separator="false"` hides the separators (since 1.5.0; before that any value enabled them), as do `el.showSeparator = false` and `group-size="0"`.
163
+ - **Separators require an even split.** Grouping applies only when `length` divides evenly by `group-size`; otherwise the cells render as one ungrouped row. A separator marks a boundary between two equal groups, so a length that does not divide would put one before a lone trailing cell — `length="4"` with the default `group-size="3"` used to draw `3 – 1`. Affected lengths at the default group size are 4, 5, 7 and 8; each now renders ungrouped. To group a length of 4, set `group-size="2"` for `2 – 2`.
164
+ - `required` is applied to the first cell only, so native form validation blocks submission when the code is empty but not when it is partial — check `e.detail.complete` yourself.
165
+ - The `autocomplete` prop currently has no effect: every cell always renders `autocomplete="one-time-code"`.
166
+ - `disabled` and `readonly` also suppress paste and keyboard handling; the value stays visible.
167
+ - Style cells via `::part(cell)` (alias `::part(input)`) and the root via `::part(base)` (alias `::part(root)`); the two names in each pair target the same element.
@@ -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.