@lofid/web 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +104 -2
- package/custom-elements.json +12890 -0
- package/dist/index.d.ts +3192 -0
- package/dist/index.js +20807 -0
- package/dist/index.js.map +1 -0
- package/dist/styles/ag-grid.css +145 -0
- package/dist/styles/motion.css +32 -0
- package/dist/styles/motion.tokens.json +38 -0
- package/dist/styles/typography.css +41 -0
- package/dist/styles/typography.json +858 -0
- package/dist/styles/vars.css +1225 -0
- package/package.json +46 -4
- package/readmes/lof-accordion/README.md +140 -0
- package/readmes/lof-alert/README.md +142 -0
- package/readmes/lof-autocomplete/README.md +209 -0
- package/readmes/lof-avatar/README.md +228 -0
- package/readmes/lof-badge/README.md +102 -0
- package/readmes/lof-breadcrumb/README.md +97 -0
- package/readmes/lof-button/README.md +189 -0
- package/readmes/lof-calendar/README.md +111 -0
- package/readmes/lof-card/README.md +105 -0
- package/readmes/lof-cardmedia/README.md +100 -0
- package/readmes/lof-carousel/README.md +187 -0
- package/readmes/lof-checkbox/README.md +159 -0
- package/readmes/lof-chip/README.md +153 -0
- package/readmes/lof-container/README.md +107 -0
- package/readmes/lof-date-picker/README.md +221 -0
- package/readmes/lof-divider/README.md +88 -0
- package/readmes/lof-drawer/README.md +188 -0
- package/readmes/lof-empty-state/README.md +78 -0
- package/readmes/lof-image-input/README.md +75 -0
- package/readmes/lof-kbd/README.md +188 -0
- package/readmes/lof-layout/README.md +122 -0
- package/readmes/lof-link/README.md +67 -0
- package/readmes/lof-menu/README.md +187 -0
- package/readmes/lof-menubar/README.md +218 -0
- package/readmes/lof-nav/README.md +90 -0
- package/readmes/lof-otp/README.md +167 -0
- package/readmes/lof-page-header/README.md +71 -0
- package/readmes/lof-pagination/README.md +141 -0
- package/readmes/lof-popover/README.md +220 -0
- package/readmes/lof-progress/README.md +88 -0
- package/readmes/lof-radio/README.md +142 -0
- package/readmes/lof-range-picker/README.md +194 -0
- package/readmes/lof-rating/README.md +90 -0
- package/readmes/lof-resizable/README.md +220 -0
- package/readmes/lof-segmented-button/README.md +158 -0
- package/readmes/lof-select/README.md +193 -0
- package/readmes/lof-sheet/README.md +170 -0
- package/readmes/lof-signature-pad/README.md +161 -0
- package/readmes/lof-skeleton/README.md +104 -0
- package/readmes/lof-slider/README.md +140 -0
- package/readmes/lof-snackbar/README.md +170 -0
- package/readmes/lof-split-button/README.md +129 -0
- package/readmes/lof-stat/README.md +73 -0
- package/readmes/lof-stepper/README.md +171 -0
- package/readmes/lof-switch/README.md +122 -0
- package/readmes/lof-tab/README.md +188 -0
- package/readmes/lof-table/README.md +114 -0
- package/readmes/lof-textfield/README.md +206 -0
- package/readmes/lof-time-picker/README.md +188 -0
- package/readmes/lof-toast/README.md +174 -0
- package/readmes/lof-tooltip/README.md +120 -0
- package/readmes/lof-tree/README.md +157 -0
- package/readmes/lof-upload/README.md +223 -0
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
# lof-segmented-button
|
|
2
|
+
|
|
3
|
+
A single-select segmented button group: a row of buttons on a 2px-inset track where exactly one segment is active at a time. Each entry in `options` renders as a native `<button role="radio">` inside a `role="radiogroup"`, so the group behaves like a compact radio group (one Tab stop, arrow keys move the selection). Use it for mutually exclusive view or mode switches with two to five short options (list / grid, day / week / month, sort order); do not use it for navigation between pages (use `lof-tab`) or for actions (use `lof-button`).
|
|
4
|
+
|
|
5
|
+
The control comes in three sizes that match the text field ramp — `small` 32px, `medium` 40px, `large` 48px — and each option can carry a leading `icon`.
|
|
6
|
+
|
|
7
|
+
## Usage
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<!-- Basic: options are set as a property, `active` holds the selected value -->
|
|
11
|
+
<lof-segmented-button id="view-mode" active="grid" field-aria-label="View mode"></lof-segmented-button>
|
|
12
|
+
<script>
|
|
13
|
+
document.getElementById('view-mode').options = [
|
|
14
|
+
{ label: 'List', value: 'list' },
|
|
15
|
+
{ label: 'Grid', value: 'grid' },
|
|
16
|
+
{ label: 'Table', value: 'table' }
|
|
17
|
+
];
|
|
18
|
+
</script>
|
|
19
|
+
|
|
20
|
+
<!-- Options as a JSON attribute, small size -->
|
|
21
|
+
<lof-segmented-button
|
|
22
|
+
size="small"
|
|
23
|
+
active="week"
|
|
24
|
+
field-aria-label="Calendar range"
|
|
25
|
+
options='[{"label":"Day","value":"day"},{"label":"Week","value":"week"},{"label":"Month","value":"month"}]'>
|
|
26
|
+
</lof-segmented-button>
|
|
27
|
+
|
|
28
|
+
<!-- Large size (40px), matching a large text field -->
|
|
29
|
+
<lof-segmented-button
|
|
30
|
+
size="large"
|
|
31
|
+
active="grid"
|
|
32
|
+
field-aria-label="View mode"
|
|
33
|
+
options='[{"label":"List","value":"list"},{"label":"Grid","value":"grid"}]'>
|
|
34
|
+
</lof-segmented-button>
|
|
35
|
+
|
|
36
|
+
<!-- Leading icons: `icon` names a lof-icon, sized 16 / 18 / 20 with the control -->
|
|
37
|
+
<lof-segmented-button
|
|
38
|
+
active="list"
|
|
39
|
+
field-aria-label="View mode"
|
|
40
|
+
options='[{"label":"List","value":"list","icon":"bullet-list"},{"label":"Grid","value":"grid","icon":"dashboard"}]'>
|
|
41
|
+
</lof-segmented-button>
|
|
42
|
+
|
|
43
|
+
<!-- Disabled option: rendered but not selectable or focusable -->
|
|
44
|
+
<lof-segmented-button id="plan" active="free" field-aria-label="Plan"></lof-segmented-button>
|
|
45
|
+
<script>
|
|
46
|
+
document.getElementById('plan').options = [
|
|
47
|
+
{ label: 'Free', value: 'free' },
|
|
48
|
+
{ label: 'Pro', value: 'pro' },
|
|
49
|
+
{ label: 'Enterprise', value: 'enterprise', disabled: true }
|
|
50
|
+
];
|
|
51
|
+
</script>
|
|
52
|
+
|
|
53
|
+
<!-- Alignment inside a wider host (align only matters when the host is stretched) -->
|
|
54
|
+
<lof-segmented-button
|
|
55
|
+
style="display: block; width: 100%"
|
|
56
|
+
align="middle"
|
|
57
|
+
active="asc"
|
|
58
|
+
field-aria-label="Sort direction"
|
|
59
|
+
options='[{"label":"Ascending","value":"asc"},{"label":"Descending","value":"desc"}]'>
|
|
60
|
+
</lof-segmented-button>
|
|
61
|
+
|
|
62
|
+
<!-- Listen for changes -->
|
|
63
|
+
<lof-segmented-button id="sort-order" active="newest" field-aria-label="Sort order"></lof-segmented-button>
|
|
64
|
+
<script>
|
|
65
|
+
const sortOrder = document.getElementById('sort-order');
|
|
66
|
+
sortOrder.options = [
|
|
67
|
+
{ label: 'Newest', value: 'newest' },
|
|
68
|
+
{ label: 'Oldest', value: 'oldest' },
|
|
69
|
+
{ label: 'Popular', value: 'popular' }
|
|
70
|
+
];
|
|
71
|
+
sortOrder.addEventListener('lof-change', (e) => {
|
|
72
|
+
console.log('Selected:', e.detail.value);
|
|
73
|
+
});
|
|
74
|
+
</script>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The `SegmentOption` interface and the `SegmentSize` / `SegmentAlign` unions are exported from the package:
|
|
78
|
+
|
|
79
|
+
```typescript
|
|
80
|
+
import type { SegmentOption } from '@lofid/web';
|
|
81
|
+
|
|
82
|
+
const options: SegmentOption[] = [
|
|
83
|
+
{ label: 'List', value: 'list' }, // label = visible text, value = what `active` / the event carry
|
|
84
|
+
{ label: 'Grid', value: 'grid', icon: 'dashboard' }, // icon = a lof-icon name, drawn before the label
|
|
85
|
+
{ label: 'Archive', value: 'archive', disabled: true } // rendered at 50% opacity, skipped by the arrow keys
|
|
86
|
+
];
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
<!-- readme-gen:start -->
|
|
90
|
+
|
|
91
|
+
<!-- Generated from lof-segmented-button.ts — do not edit; run readme-generate.mjs -->
|
|
92
|
+
|
|
93
|
+
## API
|
|
94
|
+
|
|
95
|
+
### Attributes / Properties
|
|
96
|
+
|
|
97
|
+
| Property | Attribute | Type | Default | Description |
|
|
98
|
+
| --- | --- | --- | --- | --- |
|
|
99
|
+
| `options` | `options` | `SegmentOption[]` | `[]` | The segments in order, each `{ label: string; value: string; disabled?: boolean; icon?: string; badge?: number \| string \| boolean }`. Set as a property (or a JSON array attribute); a disabled entry is rendered but cannot be selected, and `icon` names a `lof-icon` drawn before the label. |
|
|
100
|
+
| `active` | `active` | `string` | `""` | `value` of the currently selected segment. Updated by the component on click / arrow keys; set it to pre-select a segment (an unknown value selects nothing). |
|
|
101
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables the whole group (click and keyboard) without changing individual `options[].disabled` settings. Angular `control.disable()` uses it. New in 1.5.0. Reflected. |
|
|
102
|
+
| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Control height, matching the TextField ramp: `small` (32px — 28px segments, `action-md` 12px text, 16px icons), `medium` (default, 40px — 36px segments, `action-lg` 14px text, 18px icons) or `large` (48px — 44px segments, `action-xl` 16px text, 20px icons). |
|
|
103
|
+
| `align` | `align` | `"left" \| "middle" \| "right"` | `"left"` | `justify-content` of the group's inline-flex container: `left` (default), `middle` or `right`. Only visible when the host is made wider than its content. |
|
|
104
|
+
| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the radiogroup (it renders no visible group label). |
|
|
105
|
+
|
|
106
|
+
## Events
|
|
107
|
+
|
|
108
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
109
|
+
| --- | --- | --- | --- |
|
|
110
|
+
| `changed` | `{ value: option.value }` | bubbles / composed | Legacy alias of `lof-change`, fired with the same detail at the same time. Kept indefinitely so existing listeners keep working; new code should use `lof-change`. |
|
|
111
|
+
| `lof-change` | `{ value: option.value }` | bubbles / composed | Fired after a non-disabled segment is selected by click or arrow / Home / End key (also when it was already the active one). Detail: `{ value: string }`. The canonical name — prefer it over the legacy `changed`, which fires alongside it with the same detail. |
|
|
112
|
+
|
|
113
|
+
## Slots
|
|
114
|
+
|
|
115
|
+
| Slot | Description |
|
|
116
|
+
| --- | --- |
|
|
117
|
+
| — | This element has no slots. |
|
|
118
|
+
|
|
119
|
+
## CSS Parts
|
|
120
|
+
|
|
121
|
+
| Part | Description |
|
|
122
|
+
| --- | --- |
|
|
123
|
+
| `option` | Each segment's native `<button role="radio">`; the active one carries the `active` class and `aria-checked="true"`. |
|
|
124
|
+
| `icon` | A segment's optional leading `lof-icon` element. |
|
|
125
|
+
| `label` | The wrapper around a segment's label text. |
|
|
126
|
+
| `badge` | A segment's optional trailing `lof-badge`; rendered only when the option sets `badge`. |
|
|
127
|
+
| `base` | The `role="radiogroup"` track that lays out the segments. |
|
|
128
|
+
|
|
129
|
+
<!-- readme-gen:end -->
|
|
130
|
+
|
|
131
|
+
## Accessibility
|
|
132
|
+
|
|
133
|
+
- The container is a `role="radiogroup"`; give it a name with `field-aria-label` — the component renders no visible group label, so without it screen readers announce an unnamed group.
|
|
134
|
+
- Every segment is a native `<button role="radio">` with `aria-checked="true"` on the active one and `aria-checked="false"` on the rest. Disabled options get the native `disabled` attribute, so they are not focusable and do not fire `click`.
|
|
135
|
+
- Roving tabindex (APG radio-group pattern): the whole group is a single Tab stop. The active segment carries `tabindex="0"`; if `active` matches no enabled option, the first enabled segment takes the Tab stop instead (without becoming selected). All other segments are `tabindex="-1"`.
|
|
136
|
+
- Arrow keys both move focus and select, so they emit the change event immediately. Focus is moved to the newly active segment after the re-render.
|
|
137
|
+
- Focus ring: a 2px `border-focus` outline drawn inside the segment (`outline-offset: -2px`) and raised with `z-index: 1` so it stays above the neighbouring segment.
|
|
138
|
+
- Nothing is announced beyond the native `aria-checked` change.
|
|
139
|
+
|
|
140
|
+
| Key | Action |
|
|
141
|
+
| --- | --- |
|
|
142
|
+
| `Tab` / `Shift+Tab` | Move focus into / out of the group (one stop, on the active segment) |
|
|
143
|
+
| `ArrowRight` / `ArrowDown` | Select and focus the next enabled segment (wraps to the first) |
|
|
144
|
+
| `ArrowLeft` / `ArrowUp` | Select and focus the previous enabled segment (wraps to the last) |
|
|
145
|
+
| `Home` / `End` | Select and focus the first / last enabled segment |
|
|
146
|
+
| `Enter` / `Space` | Native button activation: selects the focused segment |
|
|
147
|
+
|
|
148
|
+
## Notes / Edge Cases
|
|
149
|
+
|
|
150
|
+
- **Two events fire for one selection — listen to ONE of them or your handler runs twice.** The change event is `lof-change`, matching the rest of the library. The legacy un-prefixed `changed` fires alongside it with the same detail and is kept so existing listeners keep working — listen to one, not both. Both bubble and are composed, so either can be caught on any ancestor, and both fire when the already-active segment is clicked again.
|
|
151
|
+
- `active` is a plain string compared against `option.value`; setting it to a value that is not in `options` (or to a disabled option's value) renders no active segment.
|
|
152
|
+
- `options` is compared by reference: mutate-in-place changes are not picked up — assign a new array.
|
|
153
|
+
- The host is `display: inline-block` and the group `inline-flex`, so it sizes to its content; `align` has no visible effect until the host is stretched (e.g. `style="display: block; width: 100%"`). Every segment has `min-width: 80px`, so a group is never narrower than 80px per segment.
|
|
154
|
+
- Sizing (2026-11 refresh): a joined, outlined group — 1px `--lof-border-default` edge, 6px outer corners, hairline seams between segments — 28 / 34 / 40px tall like the buttons. The selected segment takes the muted fill (`--lof-bg-muted`) and Medium weight; hover shows a lighter wash.
|
|
155
|
+
- Per size: padding `spacing-3xs spacing-sm` / `spacing-2xs spacing-md` / `spacing-xs spacing-lg`, text `action-md` (12px) / `action-lg` (14px) / `action-xl` (16px), and leading icons at 16 / 18 / 20px with an `spacing-xs` (8px) gap.
|
|
156
|
+
- Colours: the active segment uses `action-neutral-fill` with inverse text (and `action-neutral-fill-hover` on hover); a non-active segment is transparent so the `action-overlay-hover` alpha composites over the track; disabled segments are drawn at 50% opacity with `bg-neutral-elevated-1` and a `not-allowed` cursor. Background and colour transitions are 0.2s.
|
|
157
|
+
- A per-option `icon` renders a `lof-icon` before the label. Its size rides `--lof-icon-size` set directly on the `lof-icon` element — not on a wrapper, since `lof-icon` reflects `size="md"` and its own `:host([size])` rule would otherwise win.
|
|
158
|
+
- No design-token overrides or `--lof-segmented-button-*` hooks are exposed; style through the `base` / `option` / `icon` / `label` parts.
|
|
@@ -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-field-label-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 (28 / 34 / 40px) 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.
|