@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.
Files changed (65) hide show
  1. package/README.md +104 -2
  2. package/custom-elements.json +12890 -0
  3. package/dist/index.d.ts +3192 -0
  4. package/dist/index.js +20807 -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/typography.css +41 -0
  10. package/dist/styles/typography.json +858 -0
  11. package/dist/styles/vars.css +1225 -0
  12. package/package.json +46 -4
  13. package/readmes/lof-accordion/README.md +140 -0
  14. package/readmes/lof-alert/README.md +142 -0
  15. package/readmes/lof-autocomplete/README.md +209 -0
  16. package/readmes/lof-avatar/README.md +228 -0
  17. package/readmes/lof-badge/README.md +102 -0
  18. package/readmes/lof-breadcrumb/README.md +97 -0
  19. package/readmes/lof-button/README.md +189 -0
  20. package/readmes/lof-calendar/README.md +111 -0
  21. package/readmes/lof-card/README.md +105 -0
  22. package/readmes/lof-cardmedia/README.md +100 -0
  23. package/readmes/lof-carousel/README.md +187 -0
  24. package/readmes/lof-checkbox/README.md +159 -0
  25. package/readmes/lof-chip/README.md +153 -0
  26. package/readmes/lof-container/README.md +107 -0
  27. package/readmes/lof-date-picker/README.md +221 -0
  28. package/readmes/lof-divider/README.md +88 -0
  29. package/readmes/lof-drawer/README.md +188 -0
  30. package/readmes/lof-empty-state/README.md +78 -0
  31. package/readmes/lof-image-input/README.md +75 -0
  32. package/readmes/lof-kbd/README.md +188 -0
  33. package/readmes/lof-layout/README.md +122 -0
  34. package/readmes/lof-link/README.md +67 -0
  35. package/readmes/lof-menu/README.md +187 -0
  36. package/readmes/lof-menubar/README.md +218 -0
  37. package/readmes/lof-nav/README.md +90 -0
  38. package/readmes/lof-otp/README.md +167 -0
  39. package/readmes/lof-page-header/README.md +71 -0
  40. package/readmes/lof-pagination/README.md +141 -0
  41. package/readmes/lof-popover/README.md +220 -0
  42. package/readmes/lof-progress/README.md +88 -0
  43. package/readmes/lof-radio/README.md +142 -0
  44. package/readmes/lof-range-picker/README.md +194 -0
  45. package/readmes/lof-rating/README.md +90 -0
  46. package/readmes/lof-resizable/README.md +220 -0
  47. package/readmes/lof-segmented-button/README.md +158 -0
  48. package/readmes/lof-select/README.md +193 -0
  49. package/readmes/lof-sheet/README.md +170 -0
  50. package/readmes/lof-signature-pad/README.md +161 -0
  51. package/readmes/lof-skeleton/README.md +104 -0
  52. package/readmes/lof-slider/README.md +140 -0
  53. package/readmes/lof-snackbar/README.md +170 -0
  54. package/readmes/lof-split-button/README.md +129 -0
  55. package/readmes/lof-stat/README.md +73 -0
  56. package/readmes/lof-stepper/README.md +171 -0
  57. package/readmes/lof-switch/README.md +122 -0
  58. package/readmes/lof-tab/README.md +188 -0
  59. package/readmes/lof-table/README.md +114 -0
  60. package/readmes/lof-textfield/README.md +206 -0
  61. package/readmes/lof-time-picker/README.md +188 -0
  62. package/readmes/lof-toast/README.md +174 -0
  63. package/readmes/lof-tooltip/README.md +120 -0
  64. package/readmes/lof-tree/README.md +157 -0
  65. package/readmes/lof-upload/README.md +223 -0
@@ -0,0 +1,188 @@
1
+ # lof-time-picker
2
+
3
+ Time selection field implementing the Figma "Time Picker" component (Lofid DS V1.0, node 8301:3771): an editable text field with a clock icon that opens a panel of Hour / Minute (/ Second / AM-PM) columns and a Now / Cancel / OK footer. Column picks are held as a draft until OK; the field also accepts free-form typed times ("930", "9:30 pm", "n" for now). The committed `value` is always 24-hour `"HH:mm"` (or `"HH:mm:ss"` with `seconds`) regardless of the display `format`. Use it for a single time of day; use `lof-date-picker` for dates and `lof-range-picker` for date ranges.
4
+
5
+ ## Usage
6
+
7
+ ```html
8
+ <!-- Basic (12-hour display, 5-minute steps) -->
9
+ <lof-time-picker></lof-time-picker>
10
+
11
+ <!-- Value is always 24-hour HH:mm; the field shows it per `format` -->
12
+ <lof-time-picker value="09:30" label="Start time"></lof-time-picker>
13
+ <lof-time-picker value="17:05" format="24h"></lof-time-picker>
14
+
15
+ <!-- Seconds column; value becomes HH:mm:ss -->
16
+ <lof-time-picker seconds value="17:05:30" format="24h"></lof-time-picker>
17
+
18
+ <!-- Minute granularity of the column (typed entry still accepts any minute) -->
19
+ <lof-time-picker minute-step="15"></lof-time-picker>
20
+ <lof-time-picker minute-step="1"></lof-time-picker>
21
+
22
+ <!-- Constrain to business hours (inclusive, HH:mm) -->
23
+ <lof-time-picker min-time="09:00" max-time="17:30" placeholder="Business hours only"></lof-time-picker>
24
+
25
+ <!-- Clear button, helper / error text, required -->
26
+ <lof-time-picker value="09:30" clearable></lof-time-picker>
27
+ <lof-time-picker label="Start time" helper-text="Local timezone"></lof-time-picker>
28
+ <lof-time-picker label="Start time" error error-message="Select a valid time"></lof-time-picker>
29
+ <lof-time-picker label="Start time" required></lof-time-picker>
30
+
31
+ <!-- States -->
32
+ <lof-time-picker value="09:30" disabled></lof-time-picker>
33
+ <lof-time-picker value="09:30" readonly></lof-time-picker>
34
+
35
+ <!-- Sizes (field 28 / 34 / 40px, panel 220 / 250 / 280px) and layout -->
36
+ <lof-time-picker size="small"></lof-time-picker>
37
+ <lof-time-picker size="medium"></lof-time-picker>
38
+ <lof-time-picker size="large"></lof-time-picker>
39
+ <lof-time-picker full-width label="Full width"></lof-time-picker>
40
+
41
+ <!-- Form integration: `name` renders a hidden input carrying the value -->
42
+ <form>
43
+ <lof-time-picker name="startTime" label="Start time" required></lof-time-picker>
44
+ </form>
45
+
46
+ <!-- Programmatic control -->
47
+ <lof-time-picker id="tp" clearable></lof-time-picker>
48
+ <script>
49
+ const picker = document.getElementById('tp');
50
+ picker.value = '14:30'; // always 24h
51
+ picker.open = true; // opens the panel and focuses the selected hour
52
+
53
+ picker.addEventListener('lof-change', (e) => {
54
+ console.log('time:', e.detail.value); // "14:30" | "14:30:00" | null (cleared)
55
+ });
56
+ picker.addEventListener('lof-open-change', (e) => {
57
+ console.log('open:', e.detail.open);
58
+ });
59
+ </script>
60
+ ```
61
+
62
+ ### Typed entry
63
+
64
+ Typing into the field and pressing `Enter` (or leaving the field) commits the text. Accepted forms are case- and whitespace-insensitive: `9` → 09:00, `930` / `0930` / `9:30` / `9.30` / `9 30` → 09:30, `093015` / `9:30:15` → 09:30:15, `9 pm` / `9:30p` → 21:00 / 21:30, `12am` → 00:00, `12 pm` → 12:00, and `n` / `now` → the current time. Unparseable text shows "Invalid time", a time outside `min-time` / `max-time` shows "Time out of range"; in both cases the text stays in the field for correction and the committed `value` is untouched.
65
+
66
+ ### Deprecated aliases
67
+
68
+ ```html
69
+ <!-- fullwidth → full-width (since 1.5.0; still works, logs a one-time console notice, removed in 3.0) -->
70
+ <lof-time-picker fullwidth label="Old spelling"></lof-time-picker>
71
+ <lof-time-picker full-width label="Canonical"></lof-time-picker>
72
+ ```
73
+
74
+ <!-- readme-gen:start -->
75
+
76
+ <!-- Generated from lof-time-picker.ts — do not edit; run readme-generate.mjs -->
77
+
78
+ ## API
79
+
80
+ ### Attributes / Properties
81
+
82
+ | Property | Attribute | Type | Default | Description |
83
+ | --- | --- | --- | --- | --- |
84
+ | `value` | `value` | `string \| null` | `null` | Committed time, 24-hour "HH:mm" or "HH:mm:ss" (e.g. "09:30", "17:05:30"). Reflected. |
85
+ | `placeholder` | `placeholder` | `string` | `"Select time"` | Placeholder shown in the field while no value is committed and nothing is typed. |
86
+ | `label` | `label` | `string \| null` | `null` | Field label rendered above the trigger; also the input's accessible name (unset → "Select time"). |
87
+ | `disabled` | `disabled` | `boolean` | `false` | Disables the field (no pointer events) and the panel cannot open. The field looks exactly like a disabled `lof-textfield`: the whole field at 0.65 opacity, an elevated-2 box with the accent border, the label in `--lof-text-label` and the value and placeholder in `--lof-text-caption` (changed in 1.5.0: they were `--lof-text-disabled` under the 0.65, which left them barely readable). Reflected. |
88
+ | `required` | `required` | `boolean` | `false` | Renders the `*` mark after the label and sets `aria-required`; not enforced by the component. |
89
+ | `readonly` | `readonly` | `boolean` | `false` | Shows the value but blocks typing and opening the panel. Reflected. |
90
+ | `format` | `format` | `"12h" \| "24h"` | `"12h"` | Display format of the trigger text and hour column. Value stays 24-hour. |
91
+ | `seconds` | `seconds` | `boolean` | `false` | Shows the seconds column; committed value becomes "HH:mm:ss". Reflected. |
92
+ | `minuteStep` | `minute-step` | `number` | `5` | Minute granularity of the minutes column (1, 5, 10, 15, 30, …). |
93
+ | `minTime` | `min-time` | `string \| null` | `null` | Earliest selectable time, "HH:mm" (inclusive). |
94
+ | `maxTime` | `max-time` | `string \| null` | `null` | Latest selectable time, "HH:mm" (inclusive). |
95
+ | `open` | `open` | `boolean` | `false` | Whether the panel is open. Settable from outside; opening resets the draft from `value` (programmatic changes do not fire `lof-open-change`). Reflected. |
96
+ | `clearable` | `clearable` | `boolean` | `false` | Shows a clear (×) button inside the field while a value is set; clearing commits `null`. |
97
+ | `error` | `error` | `boolean` | `false` | Error styling (danger border, `aria-invalid`) and shows `errorMessage` below the field. |
98
+ | `invalid` | `invalid` | `boolean` | `false` | Alias for `error` (requested-API compat); either flag applies error styling. |
99
+ | `errorMessage` | `error-message` | `string` | `undefined` | Text shown below the field while `error` / `invalid` is set (falls back to the typed-entry parse error, then `helperText`). |
100
+ | `helperText` | `helper-text` | `string` | `undefined` | Assistive text shown below the field when not in error. |
101
+ | `name` | `name` | `string` | `undefined` | When set, renders a hidden `<input name="…">` carrying `value` for native form submission. |
102
+ | `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Trigger height on the shared field scale — small 32 / medium 40 / large 48px border-box; also sets the panel width (220 / 250 / 280px) and option row height (32 / 36 / 40px). Small lowers the trigger min-width from 160 to 128px. |
103
+ | `variant` | `variant` | `"outlined"` | `"outlined"` | Visual style; only `"outlined"` exists today. Reflected. |
104
+ | `fullWidth` | `full-width` | `boolean` | `false` | Fills the parent width (the host is inline-block with intrinsic width otherwise). The attribute is `full-width`. Reflected (as `fullwidth` in 1.x). The `fullwidth` attribute spelling is deprecated (still works; removal targeted for 3.0). |
105
+
106
+ ## Events
107
+
108
+ | Event | Detail | Bubbles / composed | Description |
109
+ | --- | --- | --- | --- |
110
+ | `lof-blur` | — | bubbles / composed | Fired when the text input loses focus (before any typed text is committed). No detail. |
111
+ | `lof-change` | `{ value: newValue } / { value: null }` | bubbles / composed | Fired when a time is committed (OK, Enter / blur on typed text, the Now shortcut) or cleared. Detail: `{ value: string \| null }` — 24-hour "HH:mm" / "HH:mm:ss", or `null` after a clear. |
112
+ | `lof-focus` | — | bubbles / composed | Fired when the text input receives focus. No detail. |
113
+ | `lof-open-change` | `{ open: this.open } / { open: false }` | bubbles / composed | Fired whenever the panel opens or closes through user interaction. Detail: `{ open: boolean }`. |
114
+
115
+ ## Slots
116
+
117
+ | Slot | Description |
118
+ | --- | --- |
119
+ | — | This element has no slots. |
120
+
121
+ ## CSS Parts
122
+
123
+ | Part | Description |
124
+ | --- | --- |
125
+ | `base` | Outer wrapper; carries the size / error / readonly classes |
126
+ | `label` | The field label above the trigger |
127
+ | `trigger` | The field box that anchors the panel (wraps the text input and the icons) |
128
+ | `value` | The editable text input showing the formatted time |
129
+ | `icon` | The trailing clock icon |
130
+ | `panel` | The popover panel (`role="dialog"`) |
131
+ | `shortcuts` | The typed-shortcut chip row at the top of the panel (N → Now) |
132
+ | `option` | Each hour / minute / second / AM-PM entry button |
133
+ | `footer` | The Now / Cancel / OK row |
134
+ | `helper` | The helper / error text live region under the field |
135
+
136
+ ## Tokens / CSS Variables
137
+
138
+ ### Component hooks
139
+
140
+ Set these on the host (or an ancestor) to customise the element without touching design tokens.
141
+
142
+ | Custom property | Default | Description |
143
+ | --- | --- | --- |
144
+ | `--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. |
145
+
146
+ <!-- readme-gen:end -->
147
+
148
+
149
+ ## CSS Custom Properties
150
+
151
+ | Custom property | Default | Description |
152
+ | --- | --- | --- |
153
+ | `--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. |
154
+ ## Accessibility
155
+
156
+ - The editable field is an `<input type="text" role="combobox">` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel, `aria-required` (from `required`), `aria-invalid` (from `error` / `invalid` / a typed-entry error) and `aria-describedby` pointing at the helper / error text. Its accessible name is the `label` (via `aria-labelledby`), falling back to `aria-label="Select time"`.
157
+ - The clock icon is a button labelled "Open time panel" with its own `aria-expanded`; the optional clear button is labelled "Clear time". The required mark `*` is `aria-hidden`.
158
+ - The panel is `role="dialog"` `aria-label="Choose time"`, promoted to the browser top layer (`popover="manual"`) so a modal / drawer ancestor cannot clip it. Each column is a `role="listbox"` named "Hours", "Minutes", "Seconds" or "AM or PM"; entries are `role="option"` buttons with `aria-selected`, and out-of-range entries are native `disabled`. Each column uses a roving `tabindex` (the selected entry, else the first).
159
+ - The helper / error text (part `helper`) is a persistent `aria-live="polite"` region, so error messages and typed-entry errors are announced as they appear.
160
+ - Focus: opening with the clock icon, `ArrowDown`, `Enter` or by setting `open` moves focus to the selected (or first enabled) hour without scrolling the page; opening by clicking into the field keeps focus in the input so typing continues to work. Cancel, `Escape` and OK return focus to the field; an outside click closes without refocusing.
161
+ - Screen-reader announcement (shared `announce()` utility): "{formatted time} selected" when OK commits the draft.
162
+
163
+ | Key | Where | Action |
164
+ | --- | --- | --- |
165
+ | Typing | Field | Edits the free-form text (see Typed entry); clears any previous parse error |
166
+ | `Enter` | Field | Commit the typed text; if nothing was typed, open the panel (closed) or apply the draft (open) |
167
+ | `ArrowDown` | Field | Open the panel, or move focus into the columns when already open |
168
+ | `Escape` | Field | Revert uncommitted typed text; also closes the panel discarding the draft |
169
+ | Blur | Field | Commit the typed text when focus leaves the component (moving into the panel does not commit) |
170
+ | `ArrowUp` / `ArrowDown` | Column | Move to and select the previous / next enabled entry |
171
+ | `ArrowLeft` / `ArrowRight` | Column | Jump to the previous / next column (Hour → Minute → Second → AM/PM) |
172
+ | `Home` / `End` | Column | Select the first / last enabled entry |
173
+ | `Enter` | Column | Select the entry and apply (OK) |
174
+ | `N` | Panel | Commit the current time immediately (same as the "N → Now" chip) and close |
175
+ | `Escape` | Anywhere | Discard the draft and close |
176
+
177
+ ## Notes / Edge Cases
178
+
179
+ - `value` is always 24-hour `"HH:mm"`, or `"HH:mm:ss"` when `seconds` is set; the `format` prop only changes the field text and the hour column (`12h` shows 01–12 plus an AM/PM column, `24h` shows 00–23). An unparseable `value` renders as empty.
180
+ - `min-time` / `max-time` are `"HH:mm"` (inclusive) and are compared at minute precision even with `seconds`. Hours with no in-range step minute and AM/PM periods with no enabled hour are disabled; picking an hour snaps the draft minute to the nearest in-range step.
181
+ - Draft model: column clicks only update the draft; **OK** commits and fires `lof-change`; **Cancel**, `Escape` or an outside click discard it (and fire `lof-open-change` with `open: false`). The OK button is disabled until an hour is chosen; picking an hour with no minute defaults the minute to `00`; picking a minute or second first defaults the hour to the first enabled one.
182
+ - Two "now" behaviours: the footer **Now** link sets the draft to the current time snapped to `minute-step` (and to the nearest enabled hour) — you still press OK; the `N` shortcut / typed `n` / the "N → Now" chip commit the current time immediately, clamped into `min-time` / `max-time`.
183
+ - Typed entry is not limited to `minute-step`: `9:07` commits `09:07` even with `minute-step="15"`. Typing an empty string and committing behaves like the clear button (`lof-change` with `value: null`).
184
+ - `minute-step` outside 1–60 falls back to 1; the seconds column is always step 1.
185
+ - `invalid` is a non-deprecated alias of `error`; either flag applies error styling. The text below the field is `error-message`, else the typed-entry error, else `helper-text`.
186
+ - Panel widths are fixed per `size` (220 / 250 / 280px, border-box) and capped to the viewport; it flips above the field when there is no room below and shrinks (columns scroll) rather than covering the field. 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`); that includes the hour / minute / period columns. Footer buttons are always small per the Figma spec; OK is narrowed to 60px min-width.
187
+ - Setting `open` programmatically opens the panel and resets the draft from `value`; it does not fire `lof-open-change` (only user interaction does).
188
+ - `fullWidth` (attribute `full-width`) still reflects as the lowercase `fullwidth` attribute in 1.x; the host is `inline-block` with intrinsic width otherwise.
@@ -0,0 +1,174 @@
1
+ # lof-toast
2
+
3
+ `<lof-toast>` is the transient notification of the Lofid Design System: a card anchored to one of six viewport positions (bottom centre by default) that shows a short message, an optional action button ("Undo", "Retry") and a dismiss button, then hides itself after `duration` milliseconds. It has four tones — `neutral` (default), `info`, `success` and `destructive`; the three filled ones use the same fill and text tokens as `<lof-alert appearance="solid">` — and is driven by the `show` property (or `open()` / `close()`). Use it for brief confirmations that need no reply; use `<lof-snackbar>` when you need a warning tone, a stacked layout or your own positioning, and `<lof-alert>` for messages that must stay on the page.
4
+
5
+ ## Usage
6
+
7
+ ```html
8
+ <!-- Hidden until `show` is set (or open() is called) -->
9
+ <lof-toast id="saved" message="File saved"></lof-toast>
10
+
11
+ <!-- Initially visible; auto-hides after the default 4000 ms -->
12
+ <lof-toast show message="Welcome back"></lof-toast>
13
+
14
+ <!-- Destructive tone: danger fill, announced assertively -->
15
+ <lof-toast id="failed" tone="destructive" message="Upload failed"></lof-toast>
16
+
17
+ <!-- Success and info tones: success / info fill (same tokens as a solid lof-alert), announced politely -->
18
+ <lof-toast id="done" tone="success" message="Changes saved"></lof-toast>
19
+ <lof-toast id="note" tone="info" message="A new version is available"></lof-toast>
20
+
21
+ <!-- Action button -->
22
+ <lof-toast id="deleted" message="Item deleted" action-label="Undo"></lof-toast>
23
+
24
+ <!-- Longer and persistent toasts -->
25
+ <lof-toast id="slow" message="Download complete" duration="7000"></lof-toast>
26
+ <lof-toast id="sticky" message="Reconnecting…" duration="0"></lof-toast>
27
+ ```
28
+
29
+ ```js
30
+ const saved = document.getElementById("saved");
31
+ saved.open(); // same as saved.show = true — starts the auto-dismiss timer
32
+ saved.addEventListener("dismissed", () => {
33
+ saved.show; // false — fired by close(), the ✕ button, the action button and the timer
34
+ });
35
+
36
+ const deleted = document.getElementById("deleted");
37
+ deleted.addEventListener("action", () => {
38
+ // undo the deletion… the toast closes itself right after (a `dismissed` event follows)
39
+ });
40
+ deleted.open();
41
+
42
+ const sticky = document.getElementById("sticky");
43
+ sticky.open();
44
+ sticky.close(); // the only way to hide a duration="0" toast from script
45
+ ```
46
+
47
+ ```css
48
+ /* Lift the toast above an open modal / drawer layer */
49
+ lof-toast { --lof-toast-z: 10000; }
50
+ ```
51
+
52
+ ### Deprecated aliases
53
+
54
+ ```html
55
+ <!-- type= is the deprecated alias of tone= (tone wins when both are set). Logs once per page:
56
+ [lof-toast] "type" is deprecated and will be removed in 3.0 — use "tone" instead. Note: tone="destructive" replaces type="error". -->
57
+ <lof-toast type="error" message="Upload failed"></lof-toast>
58
+
59
+ <!-- tone="error" | "danger" | "critical" are deprecated spellings of tone="destructive". Logs once per spelling:
60
+ [lof-toast] "tone="error"" is deprecated and will be removed in 3.0 — use "tone="destructive"" instead. -->
61
+ <lof-toast tone="error" message="Upload failed"></lof-toast>
62
+ <lof-toast tone="danger" message="Upload failed"></lof-toast>
63
+
64
+ <!-- actionlabel → action-label (since 1.5.0; still works, logs a one-time console notice, removed in 3.0) -->
65
+ <lof-toast message="Item deleted" actionlabel="Undo"></lof-toast>
66
+ <lof-toast message="Item deleted" action-label="Undo"></lof-toast>
67
+ ```
68
+
69
+ ```css
70
+ /* --lof-z-toast is the deprecated alias of --lof-toast-z; it is still read as the fallback (no console notice). */
71
+ lof-toast { --lof-z-toast: 10000; }
72
+ ```
73
+
74
+ <!-- readme-gen:start -->
75
+
76
+ <!-- Generated from lof-toast.ts — do not edit; run readme-generate.mjs -->
77
+
78
+ ## API
79
+
80
+ ### Attributes / Properties
81
+
82
+ | Property | Attribute | Type | Default | Description |
83
+ | --- | --- | --- | --- | --- |
84
+ | `message` | `message` | `string` | `""` | Text of the toast. It is also announced to screen readers through the shared live-region announcer each time `show` becomes true. |
85
+ | `tone` | `tone` | `"neutral" \| "info" \| "success" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | `undefined` | Semantic tone (Figma "Tone"): `"neutral"` (default: neutral surface) \| `"info"` (info fill) \| `"success"` (success fill) \| `"destructive"` (danger fill, announced assertively). The three filled tones use the same fill and text tokens as lof-alert's solid style, so a toast matches an alert of the same tone; info and success are announced politely. The three filled tones show a 20px leading icon (`error`, `check-circle`, `info`; part `icon`, hidden from assistive technology); the neutral tone has none (new in 1.5.0). Figma's Toast has all four tones. An unknown value renders as `"neutral"`. `"default"` is a deprecated alias of `"neutral"`; `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"`; each logs a one-time console notice. Takes precedence over the deprecated `type` prop. |
86
+ | `actionLabel` | `action-label` | `string` | `undefined` | Label of the optional action button rendered between the message and the dismiss button; the button is omitted when unset. Clicking it fires `action` and then closes the toast. The `actionlabel` attribute spelling is deprecated (still works; removal targeted for 3.0). |
87
+ | `duration` | `duration` | `number` | `4000` | Auto-dismiss delay in milliseconds, started each time `show` becomes true. `0` (or a negative value) disables auto-dismiss so the toast stays until `close()` or the dismiss button. Changing it while the toast is visible does not restart the running timer. |
88
+ | `show` | `show` | `boolean` | `false` | Whether the toast is visible. Set it to true (or call `open()`) to show the toast and start the auto-dismiss timer; it is set back to false by `close()`, the dismiss button, the action button and the timer. Reflected. |
89
+ | `dismissible` | `dismissible` | `boolean` | `true` | Shows the trailing dismiss button (Figma "Show Close Button"). Defaults to true; `dismissible="false"` (or the property set to `false`) hides the button. |
90
+ | `position` | `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-center"` | Where the toast is anchored: `bottom-center` (default, unchanged from before this prop existed), `bottom-left`, `bottom-right`, `top-left`, `top-center` or `top-right`. Top anchors also animate in from the top edge rather than upward from the bottom. Figma's Toast has axes Content / Show Button / Show Close Button / Tone and no position, so this axis is ours. Reflected. |
91
+ | `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Toast scale: `small`, `medium` (default, unchanged) or `large`. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Scales the padding, the inner gap, the message type role and the close icon. Figma has no Size axis on Toast. Reflected. |
92
+ | `maxVisible` | `max-visible` | `number` | `3` | How many toasts may be on screen at once AT THIS POSITION. Further ones wait their turn rather than being dropped — a notification the user never saw is worse than a late one — and each toast's `duration` only starts once it actually becomes visible, so a queued message cannot expire unseen. Default 3; unbounded stacking just fills the viewport. |
93
+
94
+ #### Deprecated (still supported — removal targeted for 3.0)
95
+
96
+ | Property | Attribute | Type | Use instead |
97
+ | --- | --- | --- | --- |
98
+ | `type` | `type` | `"neutral" \| "info" \| "success" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"` and `type="default"` to `tone="neutral"`. Ignored when `tone` is set. Logs a one-time console notice. |
99
+
100
+ ### Public fields / accessors
101
+
102
+ | Name | Type | Description |
103
+ | --- | --- | --- |
104
+ | `resolvedTone` | `ToastTone` | Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"neutral"` / `"destructive"`, and an unknown value to `"neutral"`. |
105
+
106
+ ### Methods
107
+
108
+ | Method | Signature | Description |
109
+ | --- | --- | --- |
110
+ | `open` | `open()` | Shows the toast: sets `show = true`, which starts the auto-dismiss timer and announces `message`. |
111
+ | `close` | `close()` | Hides the toast, clears the auto-dismiss timer and fires `dismissed`. It fires `dismissed` even when the toast was already hidden. |
112
+
113
+ ## Events
114
+
115
+ | Event | Detail | Bubbles / composed | Description |
116
+ | --- | --- | --- | --- |
117
+ | `action` | — | bubbles / composed | Fired when the action button is clicked, before the toast closes itself (a `dismissed` event follows). No detail. |
118
+ | `dismissed` | — | bubbles / composed | Fired whenever the toast is closed — by `close()`, the dismiss button, the action button or the auto-dismiss timer. No detail. |
119
+
120
+ ## Slots
121
+
122
+ | Slot | Description |
123
+ | --- | --- |
124
+ | — | This element has no slots. |
125
+
126
+ ## CSS Parts
127
+
128
+ | Part | Description |
129
+ | --- | --- |
130
+ | `base` | The `role="status"` toast container that carries the tone class |
131
+ | `icon` | The 20px leading icon of a filled tone (`error` on destructive, `check-circle` on success, `info` on info); a neutral toast has none. New in 1.5.0 |
132
+ | `label` | The message text span |
133
+ | `action` | The action button; rendered only when `action-label` is set |
134
+ | `close-button` | The dismiss button; rendered while `dismissible` is true |
135
+
136
+ ## Tokens / CSS Variables
137
+
138
+ ### Component hooks
139
+
140
+ Set these on the host (or an ancestor) to customise the element without touching design tokens.
141
+
142
+ | Custom property | Default | Description |
143
+ | --- | --- | --- |
144
+ | `--lof-toast-z` | `var(--lof-z-toast, 9000)` | `z-index` of the fixed host (default `9000`); raise it when a modal or drawer layer covers the toast |
145
+
146
+ <!-- readme-gen:end -->
147
+
148
+ ## Accessibility
149
+
150
+ - The toast container (part `base`) is always in the shadow DOM with `role="status"`, `aria-live="polite"` and `aria-atomic="true"`; it is hidden with `display: none` while `show` is false. Because toggling `display` is not reliably announced, the component also pushes `message` into the shared off-screen live-region announcer (`utils/announce`) every time `show` becomes true — politely for `neutral`, `info` and `success`, assertively for `destructive`. Focus is never moved.
151
+ - Two native `<button>`s: the optional action button (labelled by `action-label`) and the dismiss button with `aria-label="Dismiss"`. Both are in the Tab order; the component registers no key handlers (there is no Escape-to-close):
152
+
153
+ | Key | Action |
154
+ | --- | --- |
155
+ | Tab / Shift + Tab | Move between the action button (if any) and the dismiss button; the toast sits in the Tab order at its DOM position, not at the end of the page |
156
+ | Enter / Space | Activate the focused button: action fires `action` then `dismissed`; dismiss fires `dismissed` |
157
+
158
+ - Keyboard focus on either button is a 2px `--lof-text-static-light` outline with 2px offset and `--lof-border-radius-xs` corners (`:focus-visible` only).
159
+ - The 0.25s fade-in-up animation is disabled under `prefers-reduced-motion: reduce`.
160
+ - A toast that auto-dismisses while a button inside it has focus drops focus to `<body>`; give important actions a `duration="0"` toast or a persistent control elsewhere.
161
+
162
+ ## Notes / Edge Cases
163
+
164
+ - `show` is a boolean **property**, not a method: `toast.show()` throws. Use `toast.show = true` or `toast.open()`; the old README's `show()` call was wrong.
165
+ - The host is a full-width `position: fixed` bar (`left: 0; right: 0`) pinned to the edge named by `position`, with `pointer-events: none` (the pill itself restores `pointer-events: all`), so it never blocks clicks around it. The corner positions add a 24px side inset so the toast does not sit flush against the viewport edge; the centred ones keep the full width to centre in, which is why `bottom-center` is unchanged from before the axis existed.
166
+ - Top-anchored toasts animate in from the top edge (`fadeInDown`) rather than sliding upward, which would have read as the toast escaping its own anchor.
167
+ - **Toasts at the same `position` stack automatically.** No wrapper element and no change to your markup: each `lof-toast` registers itself, and up to `max-visible` (default 3) show at once with the newest against the anchor edge. Dismissing one closes the gap for the rest, animated. The six positions are independent stacks, and a toast whose `position` changes while it is showing leaves one and joins the other.
168
+ - **Overflow waits; it is never dropped.** Beyond `max-visible`, further toasts queue in arrival order and appear as earlier ones dismiss. A toast's `duration` does not begin until it is actually on screen, so a queued message cannot expire before anyone has seen it. *Behaviour change*: five toasts at one position used to render on top of each other — now three show and two wait.
169
+ - A single toast is unaffected by any of this: the stack only writes a transform from the second card onward, so a lone toast renders exactly as it did before stacking existed.
170
+ - The auto-dismiss timer starts only when `show` changes to true; changing `duration` on a visible toast does not restart it. Re-showing a visible toast (setting `show = true` again) is a no-op because the value did not change — `close()` it first.
171
+ - `close()` always fires `dismissed`, even when the toast was already hidden.
172
+ - The action button's hover state swaps to `--lof-bg-neutral` / `--lof-text-default` at 75% opacity.
173
+ - Layering: the host's `z-index` is `--lof-toast-z` (default 9000; the pre-rename `--lof-z-toast` still works as its fallback). Raise it on the element or an ancestor if an overlay with a higher `z-index` covers the toast; anything rendered in the browser top layer (native `<dialog>` / Popover API content) always paints above it regardless of `z-index`.
174
+ - `resolvedTone` is the tone actually rendered after alias resolution; use it (not `tone` / `type`) if you branch on tone in script.
@@ -0,0 +1,120 @@
1
+ # lof-tooltip
2
+
3
+ Hover/focus tooltip implementing the Figma "Tooltip" component: wraps a trigger element and fades in a short inverse-coloured text bubble (body-sm medium, sliding 4px toward its side) above, below, left or right of it — after a 200ms hover delay, or immediately on keyboard focus — in the Figma `single-line` or `multi-line` **Type**, optionally with a pointing tail. Use it for brief supplementary hints on icon buttons and truncated labels. Do not put critical or interactive content in it — it is not reachable on touch, cannot be focused, and disappears on hover-out.
4
+
5
+ ## Usage
6
+
7
+ ```html
8
+ <!-- Default: above the trigger -->
9
+ <lof-tooltip text="Save your changes">
10
+ <lof-button variant="primary" tone="brand">Save</lof-button>
11
+ </lof-tooltip>
12
+
13
+ <!-- Positions -->
14
+ <lof-tooltip text="Appears below" position="below">
15
+ <lof-button variant="secondary">Below</lof-button>
16
+ </lof-tooltip>
17
+ <lof-tooltip text="Appears on the left" position="left">
18
+ <lof-button variant="secondary">Left</lof-button>
19
+ </lof-tooltip>
20
+ <lof-tooltip text="Appears on the right" position="right">
21
+ <lof-button variant="secondary">Right</lof-button>
22
+ </lof-tooltip>
23
+
24
+ <!-- With the pointing tail -->
25
+ <lof-tooltip text="Edit" show-tail>
26
+ <lof-button variant="ghost" icon-only aria-label="Edit">
27
+ <lof-icon name="pencil"></lof-icon>
28
+ </lof-button>
29
+ </lof-tooltip>
30
+
31
+ <!-- Multi-line: wraps inside a 220px bubble -->
32
+ <lof-tooltip
33
+ type="multi-line"
34
+ position="below"
35
+ show-tail
36
+ text="Exports the current view as CSV. Filters and sorting are preserved."
37
+ >
38
+ <lof-button variant="secondary">Export</lof-button>
39
+ </lof-tooltip>
40
+
41
+ <!-- Restyle the bubble through its part -->
42
+ <style>
43
+ .wide::part(panel) {
44
+ max-width: 320px;
45
+ }
46
+ </style>
47
+ <lof-tooltip class="wide" type="multi-line" text="A longer explanation that needs more room than the default bubble.">
48
+ <lof-button variant="ghost">Details</lof-button>
49
+ </lof-tooltip>
50
+ ```
51
+
52
+ <!-- readme-gen:start -->
53
+
54
+ <!-- Generated from lof-tooltip.ts — do not edit; run readme-generate.mjs -->
55
+
56
+ ## API
57
+
58
+ ### Attributes / Properties
59
+
60
+ | Property | Attribute | Type | Default | Description |
61
+ | --- | --- | --- | --- | --- |
62
+ | `text` | `text` | `string` | `""` | Plain-text content of the bubble. Empty text still renders an (empty) bubble on hover, so always set it. |
63
+ | `position` | `position` | `"above" \| "below" \| "left" \| "right"` | `"above"` | Side of the trigger the bubble appears on, centred and 6px away (9px when `show-tail` is set, so the tail clears the trigger; override with `--lof-tooltip-offset`): `above`, `below`, `left` or `right`. No collision detection — pick a side with room in the viewport. |
64
+ | `showTail` | `show-tail` | `boolean` | `false` | Renders the triangular tail (`indicator` part) on the bubble's edge facing the trigger. |
65
+ | `type` | `type` | `"single-line" \| "multi-line"` | `"single-line"` | Figma "Type": `single-line` keeps the text on one line and sizes to content; `multi-line` wraps inside a 200px max-width bubble. Reflected. |
66
+ | `tone` | `tone` | `"inverse" \| "neutral"` | `"inverse"` | Bubble appearance: `inverse` (default) is the original inverse-surface bubble, unchanged; `neutral` is a light surface — `--lof-bg-neutral` with `--lof-text-default` and a 1px `--lof-border-default`, tail included. Figma has no such variant; this is a deliberate addition. Reflected. |
67
+
68
+ ## Events
69
+
70
+ | Event | Detail | Bubbles / composed | Description |
71
+ | --- | --- | --- | --- |
72
+ | — | — | — | This element emits no custom events. |
73
+
74
+ ## Slots
75
+
76
+ | Slot | Description |
77
+ | --- | --- |
78
+ | (default) | The trigger element (one focusable element such as a button or icon button). The control that takes focus — the slotted element itself, or the focusable control inside a lof-* trigger such as lof-button — receives `text` as its `aria-description`, so screen readers announce it. |
79
+
80
+ ## CSS Parts
81
+
82
+ | Part | Description |
83
+ | --- | --- |
84
+ | `panel` | The tooltip bubble (`role="tooltip"`): background, padding, radius, shadow and max-width. |
85
+ | `indicator` | The triangular tail pointing at the trigger, rendered only when `show-tail` is set. |
86
+
87
+ ## Tokens / CSS Variables
88
+
89
+ ### Component hooks
90
+
91
+ Set these on the host (or an ancestor) to customise the element without touching design tokens.
92
+
93
+ | Custom property | Default | Description |
94
+ | --- | --- | --- |
95
+ | `--lof-tooltip-offset` | `6px` | Gap between the trigger and the bubble; defaults to `6px`, or `13px` when `show-tail` is set so the tail clears the trigger. |
96
+
97
+ <!-- readme-gen:end -->
98
+
99
+ ## Accessibility
100
+
101
+ - Screen readers read `text` as the trigger's **description**: it is set as `aria-description` on the control that takes focus — the first slotted element, or, when that is a lof-* component such as `<lof-button>`, the focusable control inside its shadow root. It is re-linked on `slotchange` and updated when `text` changes, and a swapped-out trigger loses the description it was given. (Up to 1.4.9 the trigger got `aria-describedby` pointing at the bubble's id inside this component's shadow root, a reference that cannot cross the shadow boundary, so nothing was announced.)
102
+ - The bubble keeps `role="tooltip"` but is `aria-hidden`: it stays in the DOM while hidden (opacity), so it would otherwise be read a second time as stray text.
103
+ - The bubble is shown while the host is hovered **or** has focus within (`:focus-within`), so keyboard users see it when the slotted trigger is focused. The trigger therefore must be focusable — wrap a button or link, not plain text.
104
+ - The bubble never takes focus and has `pointer-events: none`.
105
+
106
+ | Key | Action |
107
+ | --- | --- |
108
+ | `Tab` | Focus the slotted trigger; the tooltip appears |
109
+ | `Escape` | Dismiss the tooltip (APG pattern). The key is not swallowed, so an enclosing dialog may also react to it |
110
+
111
+ After `Escape` the tooltip stays hidden until the pointer leaves and returns or focus leaves and returns (`mouseleave` / `focusout` clear the dismissed state).
112
+
113
+ ## Notes / Edge Cases
114
+
115
+ - **Attribute spelling is `show-tail`** (kebab-case). `showTail="…"` as an HTML attribute does nothing; set the property in code.
116
+ - **Positioning is static.** The bubble is `position: absolute` relative to the host (which is `display: inline-block; position: relative`), 6px from the trigger, centred on it, with `z-index: 1000`. There is no flipping or viewport collision detection, and ancestors with `overflow: hidden` or their own stacking context will clip it — for popover-style panels use `lof-popover`.
117
+ - `single-line` bubbles use `white-space: nowrap` and grow with the text; `multi-line` wraps at a 220px `max-width` (override it via `::part(panel)`).
118
+ - The bubble's shadow is applied with `filter: drop-shadow` so the tail (`indicator` part) casts the same shadow as the panel.
119
+ - Colours use the inverse neutral tokens, so the tooltip flips automatically (dark bubble on light themes, light bubble under `data-theme="dark"` / `.dark`).
120
+ - The hint is read from `text` only; slotted content is the trigger, not the tooltip body.