@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,193 @@
1
+ # lof-select
2
+
3
+ `<lof-select>` is the combobox-style dropdown from the Figma "Dropdown" component: a text-field-styled trigger button that opens a custom listbox (never a native `<select>`, so it is fully themeable in light and dark mode). It supports single- and multi-select, an optional in-panel search field, a Select-all row in multi mode, and width-adaptive selection chips that collapse into a "+N" chip instead of wrapping. Use it to pick one or several values from a known list. For free text use `lof-textfield`; for type-ahead against a large or remote list use `lof-autocomplete`; for two or three mutually exclusive options `lof-radio` is usually clearer.
4
+
5
+ ## Usage
6
+
7
+ ```html
8
+ <!-- Single select -->
9
+ <lof-select id="country" label="Country" placeholder="Select a country"></lof-select>
10
+ <script>
11
+ const country = document.getElementById("country");
12
+ country.options = ["USA", "Canada", "Mexico"];
13
+ country.addEventListener("lof-change", (e) => console.log(e.detail.value)); // "Canada"
14
+ </script>
15
+
16
+ <!-- Object options: value / label / icon / supportingText (a second line under the label, in single and multi rows) -->
17
+ <script>
18
+ country.options = [
19
+ { value: "email", label: "Email", icon: "email" },
20
+ { value: "chat", label: "Chat", icon: "chat", supportingText: "Replies within an hour" },
21
+ ];
22
+ </script>
23
+
24
+ <!-- Preselected value, helper text, icons -->
25
+ <lof-select label="Email preference" selected="weekly" supporting-text="How often we email you" left-icon="email"></lof-select>
26
+ <lof-select label="Custom chevron" right-icon="chevron-down"></lof-select>
27
+
28
+ <!-- Sizes, corners, label styles -->
29
+ <lof-select label="Small" size="small"></lof-select>
30
+ <lof-select label="Large" size="large"></lof-select>
31
+ <lof-select label="Sharp corners" border="sharp"></lof-select>
32
+ <lof-select label="Floating label" label-style="floating"></lof-select>
33
+ <lof-select label-style="none" placeholder="Filter by status" field-aria-label="Filter by status"></lof-select>
34
+
35
+ <!-- States -->
36
+ <lof-select label="Region" state="error" supporting-text="Pick a region to continue"></lof-select>
37
+ <lof-select label="Locked" state="disabled" selected="USA"></lof-select>
38
+
39
+ <!-- Short list without a search field (Figma "Single Option" dropdown) -->
40
+ <lof-select label="Priority" no-search></lof-select>
41
+
42
+ <!-- Multi-select with chips, Select-all and a search placeholder -->
43
+ <lof-select
44
+ id="tags"
45
+ label="Tags"
46
+ multiple
47
+ selected-values='["urgent","fragile"]'
48
+ select-all-label="Select all tags"
49
+ search-placeholder="Search tags"
50
+ max-visible-chips="3">
51
+ </lof-select>
52
+ <script>
53
+ const tags = document.getElementById("tags");
54
+ tags.options = ["urgent", "fragile", "hazmat", "oversize", "refrigerated"];
55
+ tags.addEventListener("lof-change", (e) => console.log(e.detail.value)); // ["urgent", "fragile", ...]
56
+ </script>
57
+ ```
58
+
59
+ <!-- readme-gen:start -->
60
+
61
+ <!-- Generated from lof-select.ts — do not edit; run readme-generate.mjs -->
62
+
63
+ ## API
64
+
65
+ ### Attributes / Properties
66
+
67
+ | Property | Attribute | Type | Default | Description |
68
+ | --- | --- | --- | --- | --- |
69
+ | `label` | `label` | `string` | `""` | Visible label. Rendered above the trigger (`labelStyle="default"`) or floating inside it; omitted under `labelStyle="none"`. |
70
+ | `labelStyle` | `label-style` | `"default" \| "floating" \| "none"` | `"default"` | Label presentation: `default` static label above the trigger; `floating` label rests in the value area and floats onto the border when focused, open or filled; `none` renders no label (supply `fieldAriaLabel` / `fieldAriaLabelledby`). Reflected. |
71
+ | `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the trigger. Required when `labelStyle="none"`, since no `<label>` renders and a placeholder is not a valid naming mechanism. |
72
+ | `fieldAriaLabelledby` | `field-aria-labelledby` | `string` | `undefined` | IDREF list of external element(s) naming the trigger. Wins over `fieldAriaLabel`. |
73
+ | `options` | `options` | `(string \| SelectOptionObject)[]` | `[]` | Options to list. Each entry is a plain string (used as both value and label) or `{ value, label?, supportingText?, icon? }`; `icon` is a `lof-icon` name rendered before the label, `supportingText` renders as a second line in both single- and multi-select rows. NOTE — the panel's search matches the LABEL ONLY. `supportingText` is displayed but not searched, so an option is not findable by its second line here. This differs deliberately from `lof-autocomplete`, whose filter matches the supporting line as well: there the second line carries identifying data (a DOT or MC number) that a user types to find the row, whereas a select's is descriptive ("Read-only", "Can edit, not delete") and matching it would return rows whose visible label has nothing to do with the query. |
74
+ | `multiple` | `multiple` | `boolean` | `false` | Enables multi-select: selected values render as removable chips, options as checkboxes, and a Select-all row appears in the panel. |
75
+ | `selected` | `selected` | `string` | `""` | Selected option value in single-select mode. Ignored when `multiple` is set. |
76
+ | `selectedValues` | `selected-values` | `string[]` | `[]` | Selected option values in multi-select mode. Reset to `[]` when `multiple` is turned off. |
77
+ | `state` | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Visual / interaction state. `error` colours the border and supporting text and clears itself on the next selection; `disabled` blocks interaction and dims the whole field. |
78
+ | `supportingText` | `supporting-text` | `string` | `""` | Helper line below the trigger; coloured as an error while `state="error"`. |
79
+ | `supportingIcon` | `supporting-icon` | `string` | `""` | `lof-icon` name shown before the supporting text (16px, 14px at `small`). Optional: the design pairs the helper line with an icon, but existing fields without one keep their current single-line look. |
80
+ | `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Field height — `small` 32px, `medium` 40px, `large` 48px. The whole component rides this one axis: label and supporting type, trigger padding, icons (20 / 18 / 16), selection chips, and the panel's rows, search field and checkboxes all scale with it. Reflected. |
81
+ | `border` | `border` | `"rounded" \| "sharp"` | `"rounded"` | Trigger corners: `rounded` applies the corner radius, `sharp` renders square corners. |
82
+ | `leftIcon` | `left-icon` | `string` | `""` | `lof-icon` name rendered at the left edge of the trigger. |
83
+ | `rightIcon` | `right-icon` | `string` | `""` | `lof-icon` name replacing the default chevron at the right edge of the trigger. A custom icon does not rotate when the panel opens. |
84
+ | `placeholder` | `placeholder` | `string` | `"Select option"` | Text shown in the trigger while nothing is selected. |
85
+ | `searchPlaceholder` | `search-placeholder` | `string` | `"Search option"` | Placeholder of the in-panel search field (the field is hidden when `noSearch` is set). |
86
+ | `selectAllLabel` | `select-all-label` | `string` | `"Select all"` | Label of the Select-all row shown at the top of the panel in multi-select mode. |
87
+ | `maxVisibleChips` | `max-visible-chips` | `number` | `Infinity` | Optional hard cap on visible chips. By default (no cap) the visible count adapts to the trigger's width: chips collapse into the "+N" badge one by one instead of wrapping to a second line. |
88
+ | `noSearch` | `no-search` | `boolean` | `false` | Hides the in-panel search field. The search row shows in single- and multi-select panels alike unless this is set; use it for short lists that don't need searching (Figma's "Single Option" dropdown has no search bar). |
89
+
90
+ ## Events
91
+
92
+ | Event | Detail | Bubbles / composed | Description |
93
+ | --- | --- | --- | --- |
94
+ | `changed` | `{ value: this.multiple ? this.selectedValues : this.selected }` | bubbles / composed | Fired after any selection change (pick, checkbox toggle, Select-all, chip removal). Detail: `{ value }` — the selected value string in single mode, or the array of selected values when `multiple`. Legacy name, kept indefinitely: it fires together with `lof-change`, same detail, same moment. |
95
+ | `lof-change` | `{ value: this.multiple ? this.selectedValues : this.selected }` | bubbles / composed | Prefixed alias of `changed`, fired on the same action with the same detail (added in 1.4.9). The name the rest of the library uses — prefer it in new code. |
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 above the trigger (default label style) |
108
+ | `trigger` | The button that opens the panel; styled like a text field |
109
+ | `value` | The value area: the selected label or placeholder inside the trigger. In multi-select with chips (since 1.5.0) it is the chip overlay, a sibling laid over the trigger's value area rather than a child of it |
110
+ | `helper` | The supporting / error text below the trigger |
111
+ | `panel` | The dropdown panel (a `role="group"` holding the search, Select-all and the options listbox; same node as `list`) |
112
+ | `list` | Alias of `panel` |
113
+ | `input` | The search input inside the panel |
114
+ | `option` | A single-select option row |
115
+ | `option-label` | A single-select row's first line (the option label) |
116
+ | `option-supporting-text` | A single-select row's optional second line; rendered only when the option supplies `supportingText` |
117
+
118
+ ## Tokens / CSS Variables
119
+
120
+ ### Component hooks
121
+
122
+ Set these on the host (or an ancestor) to customise the element without touching design tokens.
123
+
124
+ | Custom property | Default | Description |
125
+ | --- | --- | --- |
126
+ | `--lof-field-label-reserve` | `calc(var(--lof-body-md-regular-line-height) + var(--lof-spacing-2xs))` | Height held for the label row whenever no label renders above the trigger — `labelStyle="none"`, and `labelStyle="floating"` where the label sits inside the trigger — so the trigger still lines up with labelled siblings in a form row. Defaults to that size's label line-height plus the wrapper gap (24px at `small`, 26px at `medium` and `large`). Set to `0` to collapse the row entirely (toolbars, table cells). |
127
+ | `--lof-overlay-fallback-z` | `1001` | z-index of the panel on the **no-Popover-API fallback path only**. Wherever the browser top layer is available the panel is promoted into it and this value is inert, because top-layer elements are not in the page stacking order at all. Shared with the other overlays (select, autocomplete, the three pickers) so the whole family can be moved from one place. |
128
+ | `--lof-select-bg` | `var(--lof-bg-neutral)` | Background of the trigger, the panel and its sticky header. No longer paints behind the floating label — see `--lof-select-surface`. |
129
+ | `--lof-select-bg-disabled` | `var(--lof-bg-neutral-elevated-2)` | Trigger background when `state="disabled"` |
130
+ | `--lof-select-border-default` | `var(--lof-border-default)` | Trigger border colour at rest |
131
+ | `--lof-select-border-disabled` | `var(--lof-border-accent)` | Trigger border colour when `state="disabled"` |
132
+ | `--lof-select-border-error` | `var(--lof-border-danger)` | Trigger border colour when `state="error"` |
133
+ | `--lof-select-border-focus` | `var(--lof-border-strong)` | Trigger border colour on hover, while focused (where it also thickens to 2px) and while the panel is open |
134
+ | `--lof-select-divider` | `var(--lof-border-subtle)` | Hairline under the search field, the Select-all row and every option row |
135
+ | `--lof-select-icon-color` | `var(--lof-text-default)` | Colour of the trigger icons, the search icon and option prefix icons |
136
+ | `--lof-select-label-color` | `var(--lof-text-label)` | Colour of the static label and of the floated label |
137
+ | `--lof-select-menu-border` | `var(--lof-border-subtle)` | Panel border colour. The panel is borderless by design and only draws this on dark surfaces, where its shadow alone can't separate it from the page. |
138
+ | `--lof-select-menu-radius` | `var(--lof-border-radius-sm)` | Panel corner radius |
139
+ | `--lof-select-menu-shadow` | `var(--lof-shadows-md)` | Panel box-shadow |
140
+ | `--lof-select-option-hover` | `var(--lof-action-overlay-hover)` | Background of the hovered / keyboard-highlighted / selected option and Select-all row |
141
+ | `--lof-select-option-pressed` | `var(--lof-action-overlay-pressed)` | Background of an option row while it is being pressed |
142
+ | `--lof-select-panel-min-width` | `0px` | Smallest width of the dropdown panel. The panel is as wide as the trigger; set this when the trigger is narrower than its options need (a scrollbar included), and the panel grows past the trigger's right edge instead of squeezing them. Unset by default, so the panel matches the trigger. New in 1.5.0. |
143
+ | `--lof-select-placeholder-color` | `var(--lof-text-placeholder)` | Placeholder colour (trigger, resting floating label, search field, empty-list message) |
144
+ | `--lof-select-placeholder-disabled-color` | `var(--lof-text-caption)` | Placeholder colour when disabled |
145
+ | `--lof-select-radius` | `var(--lof-border-radius-xs)` | Trigger corner radius when `border="rounded"` |
146
+ | `--lof-select-search-border` | `var(--lof-border-default)` | Border colour of the search field inside the panel |
147
+ | `--lof-select-supporting-color` | `var(--lof-text-body)` | Supporting text colour (non-error) |
148
+ | `--lof-select-surface` | `var(--lof-select-bg, var(--lof-bg-neutral))` | Colour of the strip the floating label lays over the trigger's top border and focus ring, so the label appears to sit in a notch. It overshoots the band by 2px on the page side, so it must match the surface the field sits on. Defaults to `--lof-select-bg`. Set it when the field sits on a surface that is not the trigger's own fill, otherwise the strip shows as a short dash of the wrong colour. Mirrors `--lof-textfield-surface`. |
149
+ | `--lof-select-surface-disabled` | `var(--lof-select-bg-disabled, var(--lof-bg-neutral-elevated-2))` | The same strip while `state="disabled"`, where the trigger fill changes. Defaults to `--lof-select-bg-disabled`. |
150
+ | `--lof-select-value-color` | `var(--lof-text-default)` | Colour of the selected value, the search text, option labels and the check mark |
151
+
152
+ <!-- readme-gen:end -->
153
+
154
+ ## Accessibility
155
+
156
+ - The trigger is a native `<button role="combobox">` with `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls` (the listbox id) and `aria-invalid` (true in the error state). Its accessible name is composed as `"{label}, {selected label}"` in single mode and `"{label}, a, b, c, plus N more"` in multi mode (first three labels), so the current selection is always announced with the name. `field-aria-labelledby` replaces that computed name entirely.
157
+ - The static label (`label-style="default"`) is a `<label for>` linked to the trigger. The floating label is a visual `<span>`; the trigger's `aria-label` still carries the name. With `label-style="none"` the name comes from `field-aria-label` and a console warning is logged once if neither `field-aria-label` nor `field-aria-labelledby` is set.
158
+ - The panel (part `panel`) is a `role="group"` named after the field (or "Options"): it holds the search combobox and the Select-all row, which a listbox may not contain. The `role="listbox"` (same name, `aria-multiselectable` in multi mode, and the id the trigger and search `aria-controls` point at) is the options container inside it; the Select-all row joins it through `aria-owns`. With no matches the listbox holds one disabled option with the "No matches found" / "No options available" text. Every row is `role="option"` with `aria-selected`; multi-select rows and the Select-all row carry an explicit `aria-label` and contain an `inert`, `aria-hidden` `lof-checkbox` used purely as the visual.
159
+ - The in-panel search input is itself a `role="combobox"` with `aria-expanded`, `aria-controls` and `aria-activedescendant` tracking the highlighted row. With `no-search` the trigger keeps focus while open and carries `aria-activedescendant` instead.
160
+ - Screen-reader announcements via the shared `announce()` helper: `"{label} selected"` / `"{label} deselected"` on a checkbox toggle, `"All options selected"` / `"All options deselected"`, `"{label} removed"` when a chip is removed, and `"N options available"` / `"No matches found"` / `"No options available"` while typing in the search field.
161
+ - Focus: opening the panel moves focus to the search input (with `preventScroll`) unless `no-search`; closing always returns focus to the trigger.
162
+ - With `no-search`, the open list is reached with the arrow keys through the combobox (focus stays on the trigger and `aria-activedescendant` follows the highlight), not with Tab. The scrolling panel itself is not a Tab stop, so axe reports `scrollable-region-focusable` for it; that is expected for this pattern (decision 2026-10-28).
163
+ - Multi-select chips (changed in 1.5.0): the chips are no longer inside the trigger `<button>` (interactive content in a button is invalid HTML), and their bodies and the "+N" chip are no longer Tab stops that did nothing. They sit in an overlay over the trigger's value area: a click on a chip label or on "+N" opens the panel like any click on the field. The Tab order is the trigger, then each visible chip's remove button ("Remove {label}", at least 24 × 24px). Removing a chip from the keyboard moves focus to the next chip's remove button, else the previous one, else the trigger. Backspace / Delete on the trigger (or Backspace in an empty search field) still removes the most recent selection. The "+N" chip is hidden from assistive technology, because the trigger's name already ends "plus N more". Before 1.5.0 this README said the remove buttons were not Tab stops; they were, alongside the dead stops.
164
+
165
+ | Key | Action |
166
+ |-----|--------|
167
+ | `ArrowDown` / `ArrowUp` / `Enter` / `Space` (closed) | Open the panel |
168
+ | `Backspace` / `Delete` (closed, `multiple`) | Remove the most recently selected chip |
169
+ | `ArrowDown` / `ArrowUp` (open) | Move the highlight; in multi mode the Select-all row is a virtual first row above the options |
170
+ | `Home` / `End` (open) | Jump to the first / last filtered option |
171
+ | `Enter` (open) | Select the highlighted option (single), toggle it (multi) or toggle Select-all |
172
+ | `Space` (open, `no-search` only) | Same as Enter; with a search field Space types into it |
173
+ | `Escape` (open) | Close the panel and return focus to the trigger |
174
+ | `Tab` (open) | Close the panel, then focus moves on normally |
175
+ | `Backspace` in an empty search field (`multiple`) | Remove the most recently selected chip |
176
+ | Typing (search field) | Filters options by case-insensitive substring; the first match is highlighted |
177
+ | Printable keys (`no-search`) | APG type-ahead: keys accumulate for 500 ms and jump to the next option whose label starts with the buffer |
178
+
179
+ ## Notes / Edge Cases
180
+
181
+ - **Two events fire for one selection — listen to ONE of them or your handler runs twice.** `lof-change` (added in 1.4.9, matching the rest of the library) and the legacy `changed` fire together with the same detail; `detail.value` is a string in single mode and an array of strings when `multiple`. Existing `changed` listeners keep working.
182
+ - Opening the panel does not pre-highlight any row; the highlight appears on the first hover or arrow key so nothing reads as an unintended default.
183
+ - Since 1.5.0 the multi-select chip overlay is positioned from the field's own size (border, inline padding, icon size), not from the trigger's computed padding. Custom CSS that changes the inline padding through `::part(trigger)` therefore no longer moves the chips with it. Style `::part(value)` to adjust them as well. `::part(trigger)` is still the same button with the same box, and the chips are still `lof-chip` elements.
184
+ - `state="error"` clears itself to `"default"` on the next selection, toggle, Select-all or chip removal. `state="disabled"` dims the whole field to 50% opacity, makes chips non-removable and blocks pointer events on them.
185
+ - Turning `multiple` off resets `selectedValues` to `[]`. `selected` is ignored in multi mode and `selectedValues` in single mode.
186
+ - Chips never wrap: the number shown adapts to the trigger width (measured through a hidden copy of every chip and a `ResizeObserver`), with the remainder collapsed into a trailing "+N" chip. At least one chip always stays visible; `max-visible-chips` is an extra hard cap. A selected value with no matching option is shown as its raw value.
187
+ - Option `icon` and `supportingText` render in both single and multi rows. Both lines truncate to one line with an ellipsis in either mode (nothing wraps or hyphenates), and a row that carries a second line gets a native `title` with its full text so hovering reveals what was cut. An unknown icon name logs a `lof-icon` warning and renders nothing (no reserved space).
188
+ - A custom `right-icon` replaces the chevron and does not rotate when the panel opens; the default chevron rotates 180°.
189
+ - The search field uses the small field sizing for both `small` and `medium` selects; only `large` bumps it to medium. Empty results show "No matches found" (or "No options available" when `options` is empty).
190
+ - The `helper` part exists only while `supporting-text` is non-empty.
191
+ - The open listbox is promoted to the browser top layer (native Popover API, `popover="manual"`) so it renders correctly inside transformed or `overflow: hidden` containers such as a centered `lof-modal` or a `lof-drawer`; engines without the Popover API fall back to `position: fixed` with a measure-and-cancel correction. The panel matches the trigger width, flips above the trigger when there is not enough room below, is capped at 360px with internal scrolling, and closes on any outside pointerdown. On an outside scroll (since 1.5.0) it **stays open and moves with the field while the field is still visible**, and closes once the field scrolls out of the viewport or its scroll container, or under a sticky header — so the top-layer panel never paints over page furniture (the reason 1.4.9 closed it on every scroll). Only the window and the field's own scroll containers count, including ones inside shadow roots such as `lof-modal`'s body; scrolls of unrelated elements and of the panel itself are ignored, and a wheel or swipe over the panel never scrolls the page (`overscroll-behavior: contain`).
192
+ - `--lof-field-label-reserve` (see Component hooks) keeps a `label-style="none"` select bottom-aligned with labelled siblings; set it to `0` in toolbars or table cells.
193
+ - The trigger heights (32 / 40 / 48px) match `lof-textfield` and the date / time / range picker triggers so mixed form rows line up.
@@ -0,0 +1,170 @@
1
+ # lof-modal
2
+
3
+ `<lof-modal>` is the design system's modal dialog and implements the Figma **Modal Sheet** component (8171:3412): a panel anchored to the bottom, top or centre of the viewport over a scrim, with a title/description header, a scrollable body, an optional right-aligned footer and a built-in loading state. It lives in the `lof-sheet` folder and is exported as the `LofModal` class — there is no separate sheet element; the "sheet" is the `side="bottom"` / `side="top"` presentation of this one element. Use it for confirmations, short forms and messages that must interrupt the page. For edge-anchored panels that hold navigation or longer editing flows use `<lof-drawer>`; for lightweight contextual content anchored to a trigger use `<lof-popover>`.
4
+
5
+ ## Usage
6
+
7
+ ```html
8
+ <!-- Bottom sheet (default) with header, body and footer actions -->
9
+ <lof-button id="open-delete">Delete project</lof-button>
10
+
11
+ <lof-modal id="delete-modal" title="Delete project?" description="This action cannot be undone.">
12
+ <p>All files and history for <strong>Acme Rollout</strong> will be removed.</p>
13
+ <lof-button slot="footer" variant="secondary" id="cancel">Cancel</lof-button>
14
+ <lof-button slot="footer" tone="destructive" id="confirm">Delete</lof-button>
15
+ </lof-modal>
16
+
17
+ <script>
18
+ const modal = document.getElementById('delete-modal');
19
+ document.getElementById('open-delete').addEventListener('click', () => { modal.open = true; });
20
+ document.getElementById('cancel').addEventListener('click', () => { modal.open = false; });
21
+ modal.addEventListener('lof-open-change', (e) => {
22
+ console.log('open =', e.detail); // true | false
23
+ });
24
+ </script>
25
+
26
+ <!-- Centred dialog, small width -->
27
+ <lof-modal side="center" size="small" title="Session expired" description="Sign in again to continue.">
28
+ <lof-button slot="footer" variant="primary" tone="brand">Sign in</lof-button>
29
+ </lof-modal>
30
+
31
+ <!-- Top-anchored sheet with extra header content -->
32
+ <lof-modal side="top" size="large" title="New release">
33
+ <lof-tab slot="header" size="small">
34
+ <lof-tab-item slot="items" label="Summary"></lof-tab-item>
35
+ <lof-tab-item slot="items" label="Details"></lof-tab-item>
36
+ </lof-tab>
37
+ <p>Release notes go here.</p>
38
+ </lof-modal>
39
+
40
+ <!-- Message-only body (Figma "Text" slot) -->
41
+ <lof-modal variant="text" side="center" title="Saved" open>
42
+ <p>Your changes were saved.</p>
43
+ <p>You can close this window.</p>
44
+ </lof-modal>
45
+
46
+ <!-- Fullscreen, fixed desktop layout at every viewport width -->
47
+ <lof-modal size="fullscreen" breakpoint="web" title="Editor">
48
+ <p>Edge-to-edge content.</p>
49
+ </lof-modal>
50
+
51
+ <!-- Loading and locked states -->
52
+ <lof-modal title="Publishing…" loading open>
53
+ <p>Please wait.</p>
54
+ </lof-modal>
55
+ <lof-modal title="Processing" disabled open>
56
+ <p>Closing is blocked until the job finishes.</p>
57
+ <lof-button slot="footer">Done</lof-button>
58
+ </lof-modal>
59
+
60
+ <!-- Non-dismissible: no close button, backdrop and Escape ignored -->
61
+ <lof-modal id="locked" title="Accept terms">
62
+ <p>You must accept to continue.</p>
63
+ <lof-button slot="footer" variant="primary" tone="brand">Accept</lof-button>
64
+ </lof-modal>
65
+ <script>
66
+ // Boolean props that default to true can only be switched off from JS —
67
+ // an absent attribute leaves the default in place.
68
+ document.getElementById('locked').dismissible = false;
69
+ </script>
70
+ ```
71
+
72
+ <!-- readme-gen:start -->
73
+
74
+ <!-- Generated from lof-sheet.ts — do not edit; run readme-generate.mjs -->
75
+
76
+ ## API
77
+
78
+ ### Attributes / Properties
79
+
80
+ | Property | Attribute | Type | Default | Description |
81
+ | --- | --- | --- | --- | --- |
82
+ | `open` | `open` | `boolean` | `false` | Whether the modal is shown. Toggle it to open/close; every change fires `lof-open-change`. Reflected. |
83
+ | `side` | `side` | `"top" \| "bottom" \| "center"` | `"bottom"` | Where the panel is anchored: `bottom` (48px above the bottom edge, slides up), `top` (48px below the top edge, slides down) or `center` (fades and scales in). Below 480px with `breakpoint="responsive"` every side collapses to a full-width bottom sheet. |
84
+ | `title` | `title` | `string` | `""` | Heading text (rendered as an `<h2>`, linked via `aria-labelledby`). The `title` attribute is stripped from the host after it is read so no native tooltip appears. |
85
+ | `description` | `description` | `string` | `""` | Supporting text under the title (linked via `aria-describedby`). |
86
+ | `subtitle` | `subtitle` | `string` | `""` | Alias for `description`; rendered only when `description` is empty. |
87
+ | `dismissible` | `dismissible` | `boolean` | `true` | Coarse dismissal switch. When false the close button is hidden and backdrop clicks / Escape are ignored regardless of the granular `close-on-*` / `show-close-button` props. |
88
+ | `modal` | `modal` | `boolean` | `true` | Modal mode: renders the scrim, sets `role="dialog"` + `aria-modal`, traps Tab inside the panel and moves focus in on open. When false the panel is a `region` with no scrim and no focus trap. |
89
+ | `size` | `size` | `"small" \| "medium" \| "large" \| "extra-large" \| "fullscreen" \| "sm" \| "md" \| "lg" \| "xl"` | `"medium"` | Panel width scale. `medium` (default) matches the Figma Modal Sheet width; `fullscreen` covers the viewport. `sm` / `md` / `lg` / `xl` are alternative spellings of `small` / `medium` / `large` / `extra-large` and stay supported — they are normalised to the full words, not deprecated. Reflected. |
90
+ | `variant` | `variant` | `"default" \| "text"` | `"default"` | Body treatment — see `ModalVariant`. `"text"` styles the default slot as the Figma "Text" message slot; the header (and its divider) render as usual above it. Default rendering is unchanged. Reflected. |
91
+ | `closeOnBackdropClick` | `close-on-backdrop-click` | `boolean` | `true` | Close when the scrim is clicked. Only effective while `dismissible` is true; ignored while `disabled` or `loading`. |
92
+ | `closeOnEscape` | `close-on-escape` | `boolean` | `true` | Close on the Escape key. Only effective while `dismissible` is true; ignored while `disabled`. |
93
+ | `showCloseButton` | `show-close-button` | `boolean` | `true` | Render the "X" close button in the header. Only effective while `dismissible` is true. |
94
+ | `autoFocus` | `auto-focus` | `boolean` | `true` | Move focus into the panel when opened (modal mode only). |
95
+ | `restoreFocus` | `restore-focus` | `boolean` | `true` | Return focus to the opener when closed. |
96
+ | `scrollable` | `scrollable` | `boolean` | `true` | When false, the body no longer scrolls internally — tall content clips at the panel's max height. |
97
+ | `loading` | `loading` | `boolean` | `false` | Shows a spinner overlay and blocks all interaction inside the panel. Reflected. |
98
+ | `disabled` | `disabled` | `boolean` | `false` | Blocks user-initiated closes (X / backdrop / Escape) and footer actions. Reflected. |
99
+ | `zIndex` | `z-index` | `number` | `1000` | Stacking order of the whole modal (backdrop + panel). |
100
+ | `breakpoint` | `breakpoint` | `"responsive" \| "web"` | `"responsive"` | Figma "Breakpoint" axis. responsive (default) collapses to a full-width bottom sheet below 480px; web keeps the fixed desktop panel at every size. Reflected. |
101
+
102
+ ## Events
103
+
104
+ | Event | Detail | Bubbles / composed | Description |
105
+ | --- | --- | --- | --- |
106
+ | `lof-open-change` | `true / false` | bubbles / composed | Fired whenever `open` changes, from any cause (prop set, close button, backdrop, Escape). Detail: the new `open` boolean. |
107
+
108
+ ## Slots
109
+
110
+ | Slot | Description |
111
+ | --- | --- |
112
+ | (default) | Body content of the modal |
113
+ | `header` | Extra header content rendered under the title/description (e.g. a stepper or tabs) |
114
+ | `footer` | Actions row (right-aligned, 8px gap); the footer only renders when this slot has content |
115
+
116
+ ## CSS Parts
117
+
118
+ | Part | Description |
119
+ | --- | --- |
120
+ | `overlay` | The full-viewport scrim behind the panel |
121
+ | `panel` | The dialog panel (role="dialog") |
122
+ | `header` | Header row holding title, description, header slot and close button |
123
+ | `close-button` | The "X" close button |
124
+ | `content` | Scrollable body wrapper around the default slot |
125
+ | `footer` | Footer wrapper around the `footer` slot |
126
+ | `loading` | Spinner overlay shown while `loading` is set |
127
+
128
+ ## Tokens / CSS Variables
129
+
130
+ ### Component hooks
131
+
132
+ Set these on the host (or an ancestor) to customise the element without touching design tokens.
133
+
134
+ | Custom property | Default | Description |
135
+ | --- | --- | --- |
136
+ | `--lof-modal-transition-duration` | `var(--modal-transition-duration)` | Open/close animation duration; default `0.3s` |
137
+ | `--lof-modal-transition-timing` | `var(--modal-transition-timing)` | Open/close animation easing; default `cubic-bezier(0.32, 0.72, 0, 1)` |
138
+ | `--lof-modal-width` | `var(--modal-width)` | Panel width; overrides the `size` scale (md default `clamp(360px, 49vw, 708px)`, sm `min(400px, 100vw - 32px)`, lg `min(900px, 100vw - 48px)`, xl `min(1140px, 100vw - 48px)`). Ignored by `fullscreen` and by the responsive collapse below 480px |
139
+
140
+ <!-- readme-gen:end -->
141
+
142
+ ## Accessibility
143
+
144
+ - The panel is `role="dialog"` with `aria-modal="true"` while `modal` is on; with `modal` off it becomes a `role="region"` without scrim or focus trap.
145
+ - `aria-labelledby` points at the rendered `<h2>` when `title` is set, otherwise the panel carries `aria-label="Dialog"`; `aria-describedby` points at the description paragraph when `description` (or `subtitle`) is set.
146
+ - While `loading` the panel has `aria-busy="true"` and the header, body and footer are made `inert`; while `disabled` only the footer is `inert` and the close button is disabled.
147
+ - The close button is a real `<button>` with `aria-label="Close"`.
148
+ - A body that overflows (and `scrollable` is on) becomes a Tab stop so the keyboard can scroll it: `tabindex="0"`, `role="region"`, named by the title (`aria-label="Dialog content"` without one), with the 2px focus ring inside its edge. It is never the initial focus, and the attributes go away again when the body stops overflowing, when `scrollable` is off, or while `loading` makes it inert.
149
+ - Focus: on open (modal + `auto-focus`) focus moves to the first focusable element inside the panel, or to the panel itself (`tabindex="-1"`). On close (`restore-focus`) focus returns to the element that was active before opening — resolved through shadow roots, so a `<lof-button>` opener gets focus back.
150
+ - Body scroll is locked while open; the scrollbar width is added as body padding so the page does not shift.
151
+ - `prefers-reduced-motion: reduce` removes the slide/fade transitions and hides the closed panel outright.
152
+
153
+ | Key | Action |
154
+ | --- | --- |
155
+ | `Escape` | Closes the modal when `dismissible` and `close-on-escape` are on and the modal is not `disabled`. |
156
+ | `Tab` / `Shift+Tab` | Cycles focus inside the panel while `modal` is on (focus trap); wraps at either end. |
157
+
158
+ ## Notes / Edge Cases
159
+
160
+ - `title` is also HTML's global tooltip attribute. The component reads the attribute into the property and then removes it from the host, so no native tooltip appears over the modal or its scrim.
161
+ - `subtitle` is an alias for `description` and is only rendered when `description` is empty.
162
+ - The footer is only rendered when the `footer` slot has content; the host gains a `has-footer` attribute while it does.
163
+ - The header always has a bottom border. The footer's top divider shows only while the body scrolls (the host gains `body-scrolls`); short content has no footer divider. Scrolling is re-measured when the body or any slotted child resizes, so content added after opening, children growing in place (including in a `fullscreen` modal, whose body never changes size itself), images loading and window resizes all update it.
164
+ - `dismissible` is the coarse switch and is ANDed with `close-on-backdrop-click`, `close-on-escape` and `show-close-button`; turning it off locks all three regardless of their own values.
165
+ - `loading` blocks backdrop clicks and the close button but does **not** block `Escape`; set `disabled` (or `close-on-escape` = false) if Escape must be blocked as well.
166
+ - Boolean props default to `true` (`dismissible`, `modal`, `close-on-*`, `show-close-button`, `auto-focus`, `restore-focus`, `scrollable`); an absent attribute keeps the default, so switch them off from JavaScript (`modal.closeOnEscape = false`).
167
+ - `size` picks the panel width; `--lof-modal-width` overrides it for every size except `fullscreen`. Below 480px with `breakpoint="responsive"` every side and size (except `fullscreen`) collapses to a full-width bottom sheet, ignoring the width hook.
168
+ - `z-index` is applied to the whole fixed container (scrim + panel); use it when the modal must sit above other stacked UI such as a toast region.
169
+ - Legacy hook aliases still honoured: `--modal-transition-duration`, `--modal-transition-timing` and `--modal-width` are read as fallbacks of the `--lof-modal-*` hooks. Note `--modal-width` is also set internally per `size`, so only the canonical `--lof-modal-width` reliably overrides the width from outside.
170
+ - The old `<lof-sheet>` / `<lof-sheet-*>` element family described in earlier docs was never shipped; this element is the only export of the folder.
@@ -0,0 +1,161 @@
1
+ # lof-signature-pad
2
+
3
+ <!-- @unreleased-component 1.5.0 -->
4
+
5
+ A field that captures a handwritten signature. The user signs with a mouse, pen or finger on a 160px pad that fills its container's width. Like `lof-textfield`, the field has a label, helper text, and error, disabled and read-only states. Undo and Clear sit in the helper row. Undo removes the last stroke, and it also brings back a signature that Clear removed, so Clear asks no confirmation. `value` is the signature as a trimmed PNG data URL; `strokes` keeps the vector record, and `toSVG()` exports it.
6
+
7
+ A "Type your name instead" link beside the label switches to type mode: the user types their name and it renders on the baseline in Poppins italic. The value is the same kind of PNG. Type mode is the keyboard and screen-reader alternative to drawing (WCAG 2.2 SC 2.5.7, Dragging Movements), and it is offered to everyone.
8
+
9
+ ## Usage
10
+
11
+ ```html
12
+ <lof-signature-pad id="sig" label="Customer signature" required></lof-signature-pad>
13
+ <script>
14
+ const sig = document.getElementById('sig');
15
+ sig.addEventListener('lof-change', (e) => {
16
+ console.log(e.detail.value); // "data:image/png;base64,…", or "" once cleared
17
+ console.log(e.detail.strokes); // [{ points: [[x, y, t, pressure], …], pointerType }, …]
18
+ console.log(e.detail.signedAt); // ISO 8601 time of the first stroke
19
+ });
20
+ </script>
21
+
22
+ <!-- An error message replaces the helper text -->
23
+ <lof-signature-pad label="Customer signature" required error
24
+ error-message="A signature is required to confirm handoff"></lof-signature-pad>
25
+
26
+ <!-- Show a stored signature without letting it change -->
27
+ <lof-signature-pad label="Customer signature" readonly value="data:image/png;base64,…"></lof-signature-pad>
28
+
29
+ <!-- Start in type mode, with a name filled in -->
30
+ <lof-signature-pad label="Signature" mode="type" typed-name="Ada Lovelace"></lof-signature-pad>
31
+
32
+ <!-- A taller pad -->
33
+ <lof-signature-pad label="Signature" style="--lof-signature-pad-height: 200px"></lof-signature-pad>
34
+ ```
35
+
36
+ Once there is ink, the helper row shows "Signed" with the date, time and a short time zone (for example "Signed 18/10/2026, 2:14 PM GMT+5"), formatted for the nearest `lang` attribute. `signedAt` holds the same moment as an ISO string. It is set by the first stroke and cleared by Clear.
37
+
38
+ The exported PNG and SVG always use black ink on a transparent background, so a signature captured in dark mode still prints. On screen the ink follows the theme (`--lof-text-default`), and a stored `value` is recoloured to match. The PNG is trimmed to the ink plus 8px and drawn at 2×.
39
+
40
+ `strokes` coordinates are CSS pixels of the pad at the moment the signature began. If the pad later gets narrower, the signature is drawn scaled down to fit and the coordinates do not change. Assigning `strokes` redraws a stored record that can still be added to; assigning `value` shows a stored image that Undo cannot take apart. Both start a new Undo history.
41
+
42
+ Each mode keeps its own content when the user switches, and only the active mode makes the `value`. In type mode, Clear empties the name and Undo brings it back; while focus is in the name input, Ctrl/Cmd+Z is the input's own undo. `signedAt` in type mode is when the name was first typed. The value updates as the user types, and `lof-change` fires when the name is committed (on blur or Enter) and when the mode switch changes the value.
43
+
44
+ `lof-change` reports what the user did: a stroke, Undo, Clear, a committed name or a mode switch. It does not fire when your code sets `value`, `strokes`, `typed-name` or `mode`, or calls `undo()` or `clear()`. Read the new state from the element after those calls.
45
+
46
+ ## Forms
47
+
48
+ The pad is a form control (decision 0006). Inside a `<form>` it submits its `value`, the PNG data URL, under its `name`; an empty pad submits `""`. The data URL is typically 5–30 KB, so post the form (`method="post"`) and check your server's request-size limit.
49
+
50
+ ```html
51
+ <form method="post" action="/handoffs/42/confirm">
52
+ <lof-signature-pad name="signature" label="Customer signature" required></lof-signature-pad>
53
+ <button>Confirm handoff</button>
54
+ </form>
55
+ ```
56
+
57
+ - **Validation:** a `required` pad is invalid while empty (`valueMissing`), so the form will not submit and the browser focuses the pad, or the name input in type mode. The field does not turn red by itself. Listen for `invalid` and set `error` and `error-message`, as with the other fields. A `readonly` pad is not validated.
58
+ - **Reset:** a form reset empties both modes and the Undo history, without firing `lof-change`.
59
+ - **Restore:** when the browser restores a form (back and forward navigation), the strokes, the stored image or the typed name come back.
60
+ - **Labels and fieldsets:** an outer `<label for>` (or a wrapping one) names the pad and focuses it when clicked. A `<fieldset disabled>` disables the pad, and a disabled pad is left out of the form data.
61
+
62
+ <!-- readme-gen:start -->
63
+
64
+ <!-- Generated from lof-signature-pad.ts — do not edit; run readme-generate.mjs -->
65
+
66
+ ## API
67
+
68
+ ### Attributes / Properties
69
+
70
+ | Property | Attribute | Type | Default | Description |
71
+ | --- | --- | --- | --- | --- |
72
+ | `label` | `label` | `string` | `undefined` | Visible label above the pad. A `required` asterisk is appended. |
73
+ | `required` | `required` | `boolean` | `false` | Marks the signature as required: the label gets an asterisk. Reflected. |
74
+ | `helperText` | `helper-text` | `string` | `undefined` | Helper line below the pad. Defaults to "Use a mouse, pen or finger to sign"; once signed, the line shows "Signed {date and time}" instead. |
75
+ | `disabledText` | `disabled-text` | `string` | `undefined` | Text in the helper line while disabled (default "Signing is unavailable"). |
76
+ | `error` | `error` | `boolean` | `false` | Puts the field in the error state: danger border, and `error-message` replacing the helper text. Reflected. |
77
+ | `errorMessage` | `error-message` | `string` | `undefined` | Text shown below the pad, with an alert icon, instead of the helper text while `error` is set. |
78
+ | `disabled` | `disabled` | `boolean` | `false` | Disables the field: no drawing, Undo and Clear disabled, the pad leaves the Tab order, and the helper line shows `disabled-text`. Reflected. |
79
+ | `readonly` | `readonly` | `boolean` | `false` | Shows the signature and its timestamp without letting it change: a subtle border, no Undo or Clear buttons, no drawing. Reflected. |
80
+ | `placeholder` | `placeholder` | `string` | `"Sign here"` | Text in the empty pad (default "Sign here"). It hides on the first ink; the baseline stays. |
81
+ | `name` | `name` | `string` | `undefined` | Name of the field in a form. Reflected. |
82
+ | `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name of the pad when there is no visible `label`. |
83
+ | `value` | `value` | `string` | `""` | The signature as a PNG data URL, trimmed to the ink at 2×, with black ink on a transparent background in every theme; `""` when empty. Set it to show a stored signature: it is drawn in the theme's ink colour and replaces the strokes, so Undo cannot take it apart stroke by stroke (Clear removes it, and Undo brings it back). Setting `""` empties the pad. |
84
+ | `strokes` | — | `SignatureStroke[]` | `[]` | The vector record of the signature, one entry per stroke: `{ points: [x, y, t, pressure][], pointerType? }`. Coordinates are CSS pixels of the pad when the first stroke was drawn (a narrower pad later shows the signature scaled down to fit, and the coordinates do not change); `t` is epoch milliseconds. Set it to redraw a stored signature that can be added to; that starts a new Undo history. Property only. |
85
+ | `mode` | `mode` | `"draw" \| "type"` | `"draw"` | `draw` (default) captures the signature with a pointer; `type` takes a typed name and renders it in Poppins italic. The user switches with the link beside the label. Each mode keeps its own content; only the active mode makes the `value`. Reflected. |
86
+ | `typedName` | `typed-name` | `string` | `""` | The name typed in type mode. The `value` in type mode is this name rendered as a PNG, black, in Poppins italic. |
87
+
88
+ ### Public fields / accessors
89
+
90
+ | Name | Type | Description |
91
+ | --- | --- | --- |
92
+ | `signedAt` | `string` | When the signature was started, as an ISO 8601 string; `""` while empty. Set by the first stroke and cleared by Clear. Read-only. |
93
+
94
+ ### Methods
95
+
96
+ | Method | Signature | Description |
97
+ | --- | --- | --- |
98
+ | `isEmpty` | `isEmpty(): boolean` | True when the active mode has no signature: no strokes and no stored signature in draw mode, a blank name in type mode. |
99
+ | `undo` | `undo(): void` | Removes the last stroke, or restores what Clear removed (in type mode, the cleared name). Does not fire `lof-change`. |
100
+ | `clear` | `clear(): void` | Removes the whole signature of the active mode; Undo brings it back. Does not fire `lof-change`. |
101
+ | `toDataURL` | `toDataURL(type = "image/png"): string` | The signature as a data URL of the given type (default `"image/png"`), trimmed to the ink at 2× with black ink; `"image/svg+xml"` returns `toSVG()` as a data URL, and `"image/jpeg"` gets a white background. `""` when empty. |
102
+ | `toSVG` | `toSVG(): string` | The signature as an SVG document string, in black and trimmed. Draw mode gives smoothed paths in the `strokes` coordinate space (a stored signature from `value` is embedded as an image); type mode gives the name as `<text>` in Poppins italic. `""` when empty. |
103
+
104
+ ## Events
105
+
106
+ | Event | Detail | Bubbles / composed | Description |
107
+ | --- | --- | --- | --- |
108
+ | `lof-begin` | `{}` | bubbles / composed | The user put the pointer down to start a stroke. Detail: `{}`. |
109
+ | `lof-change` | `{ value, strokes, signedAt, mode }` | bubbles / composed | The signature changed through the user: a finished stroke, Undo, Clear, a committed typed name (on blur or Enter) or a switch of mode. Detail: `{ value, strokes, signedAt, mode }`. Not fired for property changes or the `undo()` / `clear()` methods. |
110
+ | `lof-end` | `{}` | bubbles / composed | The user finished a stroke. Detail: `{}`. |
111
+
112
+ ## Slots
113
+
114
+ | Slot | Description |
115
+ | --- | --- |
116
+ | — | This element has no slots. |
117
+
118
+ ## CSS Parts
119
+
120
+ | Part | Description |
121
+ | --- | --- |
122
+ | `label` | The label above the pad. |
123
+ | `mode-toggle` | The link-style `lof-button` beside the label that switches between drawing ("Type your name instead") and typing ("Draw instead"). Hidden while `readonly`. |
124
+ | `pad` | The bordered drawing area. In draw mode it is a focusable `role="img"` named by the label and the signature's state; in type mode it holds the name input. |
125
+ | `canvas` | The `<canvas>` the ink is drawn on. |
126
+ | `placeholder` | The "Sign here" text ("Type your full name" in type mode), shown while the pad is empty. |
127
+ | `baseline` | The line near the bottom of the pad. |
128
+ | `typed-input` | The text input of type mode, drawn on the baseline in Poppins italic. |
129
+ | `helper` | The helper, error or "Signed …" text below the pad. |
130
+ | `actions` | The row that holds the Undo and Clear buttons. |
131
+ | `undo` | The Undo `lof-button` (ghost, small). |
132
+ | `clear` | The Clear `lof-button` (secondary, small). |
133
+
134
+ ## Tokens / CSS Variables
135
+
136
+ ### Component hooks
137
+
138
+ Set these on the host (or an ancestor) to customise the element without touching design tokens.
139
+
140
+ | Custom property | Default | Description |
141
+ | --- | --- | --- |
142
+ | `--lof-signature-pad-height` | `160px` | Height of the pad, border included (default 160px). |
143
+
144
+ <!-- readme-gen:end -->
145
+
146
+ ## Accessibility
147
+
148
+ - The "Type your name instead" / "Draw instead" link comes before the pad in the Tab order, so keyboard users reach the typed alternative first. Switching moves focus to the name input or to the pad. The input is named "{label}, type your full name", carries `aria-required` and `aria-invalid`, and is described by the helper or error text.
149
+ - In draw mode the pad is a focusable `role="img"`. Its name is the label (or `field-aria-label`) plus its state: "Customer signature, required, signature pad, empty", or "Customer signature, required, signed 18/10/2026, 2:14 PM GMT+5". It is described by the helper or error text.
150
+ - Undo and Clear are real buttons, named "Undo last stroke" ("Undo clear" in type mode) and "Clear signature". When a button disables itself (Clear, or the last Undo), focus moves to the pad.
151
+ - Changes are announced politely: "Signature captured" on the first stroke, then "Last stroke removed", "Signature cleared" and "Signature restored".
152
+ - The pad has the field border (`--lof-border-default`, 3:1 or more). Focus, and drawing, draw a 2px `--lof-border-strong` border inside the pad edge; the error state draws it in `--lof-border-danger` at rest, and focus in error adds a 2px danger ring outside, so focus stays visible. Both stay visible in forced-colours mode, where the ink is drawn in `CanvasText`.
153
+ - Only the canvas sets `touch-action: none`. The page still scrolls from the label, the helper row and a read-only or disabled pad.
154
+
155
+ ### Keyboard
156
+
157
+ | Key | Action |
158
+ | --- | --- |
159
+ | Tab / Shift+Tab | Moves between the mode link, the pad (or the name input in type mode), Undo and Clear. The pad leaves the Tab order while disabled. |
160
+ | Ctrl+Z / Cmd+Z | Undoes the last stroke, or a Clear, while focus is in the field (in the name input it is the input's own undo) |
161
+ | Enter / Space | Activates the mode link, Undo or Clear |