@lofid/web 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -2
- package/custom-elements.json +11166 -0
- package/dist/index.d.ts +2784 -0
- package/dist/index.js +18710 -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/vars.css +870 -0
- package/package.json +44 -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 +190 -0
- package/readmes/lof-calendar/README.md +111 -0
- package/readmes/lof-card/README.md +75 -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 +141 -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-kbd/README.md +188 -0
- package/readmes/lof-layout/README.md +122 -0
- package/readmes/lof-menu/README.md +187 -0
- package/readmes/lof-menubar/README.md +218 -0
- package/readmes/lof-otp/README.md +167 -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-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-stepper/README.md +171 -0
- package/readmes/lof-switch/README.md +122 -0
- package/readmes/lof-tab/README.md +184 -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,206 @@
|
|
|
1
|
+
# lof-textfield
|
|
2
|
+
|
|
3
|
+
`<lof-textfield>` is the single-line and multi-line text input from the Figma "Text Field" component: a labelled control with three chromes (`default` outlined, `underline`, `legend` notched outline), three heights (32 / 40 / 48px), prefix and suffix blocks (icon, short text or slotted content), error / helper text and full-width or inline layout. Use it for free-text entry — names, emails, passwords, numbers, notes (`multiline`). For picking from a fixed list use `lof-select`; for type-ahead against a list use `lof-autocomplete`; for dates and times use the picker components, which reuse this field's chrome.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Basic field -->
|
|
9
|
+
<lof-textfield label="Email" placeholder="you@example.com" type="email"></lof-textfield>
|
|
10
|
+
|
|
11
|
+
<!-- Sizes and chromes -->
|
|
12
|
+
<lof-textfield label="Small" size="small"></lof-textfield>
|
|
13
|
+
<lof-textfield label="Large" size="large"></lof-textfield>
|
|
14
|
+
<lof-textfield label="Underline" variant="underline"></lof-textfield>
|
|
15
|
+
<lof-textfield label="Legend" variant="legend"></lof-textfield>
|
|
16
|
+
|
|
17
|
+
<!-- Label styles -->
|
|
18
|
+
<lof-textfield label="Floating label" label-style="floating"></lof-textfield>
|
|
19
|
+
<lof-textfield label-style="none" placeholder="Search orders" field-aria-label="Search orders"></lof-textfield>
|
|
20
|
+
|
|
21
|
+
<!-- Leading icon, helper text, required -->
|
|
22
|
+
<lof-textfield label="Search" prefix-icon="search" helper-text="Type at least 3 characters" required></lof-textfield>
|
|
23
|
+
|
|
24
|
+
<!-- Prefix / suffix text (Figma .Preffix / .Suffix) -->
|
|
25
|
+
<lof-textfield label="Website" prefix-text="https://" prefix-style="fill"></lof-textfield>
|
|
26
|
+
<lof-textfield label="Weight" suffix-text="kg" suffix-divider></lof-textfield>
|
|
27
|
+
|
|
28
|
+
<!-- Slotted prefix / suffix content -->
|
|
29
|
+
<lof-textfield label="Amount">
|
|
30
|
+
<span slot="prefix">$</span>
|
|
31
|
+
<lof-button slot="suffix" variant="ghost" size="small">Max</lof-button>
|
|
32
|
+
</lof-textfield>
|
|
33
|
+
|
|
34
|
+
<!-- Clickable trailing icon (e.g. password toggle) -->
|
|
35
|
+
<lof-textfield
|
|
36
|
+
id="pw"
|
|
37
|
+
label="Password"
|
|
38
|
+
type="password"
|
|
39
|
+
right-icon="visibility-on"
|
|
40
|
+
clickable-right-icon
|
|
41
|
+
right-icon-aria-label="Show password">
|
|
42
|
+
</lof-textfield>
|
|
43
|
+
<script>
|
|
44
|
+
const pw = document.getElementById("pw");
|
|
45
|
+
pw.addEventListener("lof-right-icon-click", () => {
|
|
46
|
+
pw.type = pw.type === "password" ? "text" : "password";
|
|
47
|
+
});
|
|
48
|
+
pw.addEventListener("lof-change", (e) => console.log("typed:", e.detail));
|
|
49
|
+
</script>
|
|
50
|
+
|
|
51
|
+
<!-- Error state -->
|
|
52
|
+
<lof-textfield label="Username" value="a" error error-message="Must be at least 3 characters"></lof-textfield>
|
|
53
|
+
|
|
54
|
+
<!-- Multiline (textarea) -->
|
|
55
|
+
<lof-textfield label="Notes" multiline rows="5" maxlength="500"></lof-textfield>
|
|
56
|
+
|
|
57
|
+
<!-- Read-only, disabled, inline width -->
|
|
58
|
+
<lof-textfield label="Order ID" value="SO-4821" readonly></lof-textfield>
|
|
59
|
+
<lof-textfield label="Disabled" disabled></lof-textfield>
|
|
60
|
+
<lof-textfield id="qty" label="Quantity" type="number"></lof-textfield>
|
|
61
|
+
<script>
|
|
62
|
+
// fullWidth defaults to true; full-width="false" in markup does the same as this
|
|
63
|
+
document.getElementById("qty").fullWidth = false;
|
|
64
|
+
</script>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Deprecated aliases
|
|
68
|
+
|
|
69
|
+
```html
|
|
70
|
+
<!-- floatingLabel → label-style="floating" (kept permanently as an alias; no console notice) -->
|
|
71
|
+
<lof-textfield label="Old spelling" floatinglabel></lof-textfield>
|
|
72
|
+
<lof-textfield label="Canonical" label-style="floating"></lof-textfield>
|
|
73
|
+
|
|
74
|
+
<!-- Lowercase-joined attribute spellings → kebab-case (since 1.5.0; the old ones still work,
|
|
75
|
+
log a one-time console notice, and are removed in 3.0) -->
|
|
76
|
+
<lof-textfield label="Old spelling" prefixicon="search" lefticon="search" righticon="visibility-on" prefixiconarialabel="Search"
|
|
77
|
+
helpertext="Helper" errormessage="Error" fullwidth></lof-textfield>
|
|
78
|
+
<lof-textfield label="Canonical" prefix-icon="search" left-icon="search" right-icon="visibility-on" prefix-icon-aria-label="Search"
|
|
79
|
+
helper-text="Helper" error-message="Error" full-width></lof-textfield>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
<!-- readme-gen:start -->
|
|
83
|
+
|
|
84
|
+
<!-- Generated from lof-textfield.ts — do not edit; run readme-generate.mjs -->
|
|
85
|
+
|
|
86
|
+
## API
|
|
87
|
+
|
|
88
|
+
### Attributes / Properties
|
|
89
|
+
|
|
90
|
+
| Property | Attribute | Type | Default | Description |
|
|
91
|
+
| --- | --- | --- | --- | --- |
|
|
92
|
+
| `label` | `label` | `string` | `undefined` | Visible label text. Rendered above the control (default), inside it as a floating label (`labelStyle="floating"`) or as the notch of the `legend` variant; omitted entirely under `labelStyle="none"`. |
|
|
93
|
+
| `placeholder` | `placeholder` | `string` | `""` | Placeholder shown while the field is empty. Under the floating label style it stays hidden until the field is focused. |
|
|
94
|
+
| `type` | `type` | `string` | `"text"` | Native input `type` (`text`, `email`, `password`, `number`, …). Ignored when `multiline` is set. |
|
|
95
|
+
| `value` | `value` | `string` | `""` | Current text. Updated on every keystroke; set it to control the field programmatically. |
|
|
96
|
+
| `leftIcon` | `left-icon` | `string` | `undefined` | Legacy name for the leading icon (a `lof-icon` name). `prefixIcon` wins when both are set. The `lefticon` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
97
|
+
| `rightIcon` | `right-icon` | `string` | `undefined` | Trailing `lof-icon` name rendered in the suffix block. Decorative unless `clickableRightIcon` is set. The `righticon` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
98
|
+
| `clickableRightIcon` | `clickable-right-icon` | `boolean` | `false` | Makes the trailing icon interactive (pointer + focusable) and emits `lof-right-icon-click` — e.g. a password show/hide toggle or clear button. |
|
|
99
|
+
| `rightIconAriaLabel` | `right-icon-aria-label` | `string` | `undefined` | Accessible label for the trailing icon when it is clickable. |
|
|
100
|
+
| `prefixText` | `prefix-text` | `string` | `undefined` | Short text rendered before the input, e.g. `"http://"` or `"$"`. Sits in the same prefix block as `prefixIcon` and is styled by `prefixStyle`. |
|
|
101
|
+
| `prefixStyle` | `prefix-style` | `"clear" \| "divider" \| "fill"` | `"clear"` | Visual treatment of the prefix block — applies to the prefix icon, text and slotted `prefix` content alike. See `TextFieldPrefixStyle`. |
|
|
102
|
+
| `suffixText` | `suffix-text` | `string` | `undefined` | Short text rendered after the input, e.g. `"kg"` or `".00"`. Shares the suffix block with `rightIcon` and slotted `suffix` content. |
|
|
103
|
+
| `suffixDivider` | `suffix-divider` | `boolean` | `false` | Draws a hairline between the input and the suffix block. |
|
|
104
|
+
| `supportingText` | `supportingtext` | `string` | `undefined` | Legacy name for the helper line below the control. `helperText` wins when both are set. |
|
|
105
|
+
| `state` | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Legacy visual state. `"error"` / `"disabled"` behave like the `error` / `disabled` booleans, which are preferred and take precedence. Typing into a `state="error"` field resets it to `"default"` until the value is emptied again. |
|
|
106
|
+
| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Control height — `small` 32px, `medium` 40px, `large` 48px — which also scales the text and the affix icons. |
|
|
107
|
+
| `labelStyle` | `label-style` | `"default" \| "floating" \| "none"` | `undefined` | Label presentation. Left `undefined` the deprecated `floatingLabel` boolean decides, so existing markup keeps working; set explicitly and it wins. Declares `attribute` because Lit would otherwise only listen for the all-lowercase `labelstyle`. Reflected. |
|
|
108
|
+
| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the input. Required when `labelStyle="none"`, since no `<label>` renders and a placeholder is not a valid naming mechanism. |
|
|
109
|
+
| `fieldAriaLabelledby` | `field-aria-labelledby` | `string` | `undefined` | IDREF list of external element(s) naming the input. Wins over `fieldAriaLabel`. |
|
|
110
|
+
| `variant` | `variant` | `"default" \| "underline" \| "legend"` | `"default"` | Field chrome: `default` outlined box, `underline` bottom border only, `legend` notched outline with the label sitting in the top border (native fieldset/legend). Reflected. |
|
|
111
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables the input (not focusable, not editable) and dims the control. |
|
|
112
|
+
| `required` | `required` | `boolean` | `false` | Marks the input required: sets native `required` / `aria-required` and appends an asterisk to the label. |
|
|
113
|
+
| `multiline` | `multiline` | `boolean` | `false` | Renders a textarea instead of a single-line input (see `rows`). Prefix/suffix blocks and `type` are ignored in this mode. Reflected. |
|
|
114
|
+
| `rows` | `rows` | `number` | `3` | Visible text rows of the textarea when `multiline` is set. |
|
|
115
|
+
| `prefixIcon` | `prefix-icon` | `string` | `undefined` | Leading `lof-icon` name rendered in the prefix block (preferred over the legacy `leftIcon`). The `prefixicon` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
116
|
+
| `prefixIconAriaLabel` | `prefix-icon-aria-label` | `string` | `undefined` | Accessible label for the leading icon. Without it the icon is `aria-hidden` (decorative). The `prefixiconarialabel` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
117
|
+
| `error` | `error` | `boolean` | `false` | Puts the field in the error state: danger border, `aria-invalid`, and `errorMessage` replacing the helper text. |
|
|
118
|
+
| `errorMessage` | `error-message` | `string` | `undefined` | Text shown below the control instead of `helperText` while the field is in the error state. The `errormessage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
119
|
+
| `helperText` | `helper-text` | `string` | `undefined` | Helper line below the control (preferred over the legacy `supportingText`); linked to the input via `aria-describedby`. The `helpertext` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
120
|
+
| `helperIcon` | `helper-icon` | `string` | `undefined` | Icon name from the generated icon dictionary, rendered before the helper line (Figma "Supporting Icon"). Sized 16px, or 14px at `size="small"`, and it takes the helper's colour — so it turns `--lof-text-danger` in the error state. Decorative: it is hidden from screen readers, since the helper text it sits beside is already announced. |
|
|
121
|
+
| `readonly` | `readonly` | `boolean` | `false` | Makes the input read-only: focusable and selectable but not editable. |
|
|
122
|
+
| `maxLength` | `maxlength` | `number` | `undefined` | Maximum number of characters (native `maxlength`). |
|
|
123
|
+
| `name` | `name` | `string` | `undefined` | Form field name forwarded to the native input, for form submission and autofill. |
|
|
124
|
+
| `fullWidth` | `full-width` | `boolean` | `true` | Fills the parent width as a block element (default). Unset it to render inline at the content's natural width. Reflected (as `fullwidth` in 1.x). The `fullwidth` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
125
|
+
|
|
126
|
+
#### Deprecated (still supported — removal targeted for 3.0)
|
|
127
|
+
|
|
128
|
+
| Property | Attribute | Type | Use instead |
|
|
129
|
+
| --- | --- | --- | --- |
|
|
130
|
+
| `floatingLabel` | `floatinglabel` | `boolean` | Use `labelStyle="floating"`. Kept permanently as an alias. |
|
|
131
|
+
|
|
132
|
+
### Methods
|
|
133
|
+
|
|
134
|
+
| Method | Signature | Description |
|
|
135
|
+
| --- | --- | --- |
|
|
136
|
+
| `focus` | `focus(options?: FocusOptions)` | Focuses the inner input/textarea (the host itself is not focusable). |
|
|
137
|
+
|
|
138
|
+
## Events
|
|
139
|
+
|
|
140
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
141
|
+
| --- | --- | --- | --- |
|
|
142
|
+
| `lof-change` | `value` | bubbles / composed | Fired on every keystroke. Detail: the current text (`value`). |
|
|
143
|
+
| `lof-right-icon-click` | — | bubbles / composed | Fired when the trailing icon is clicked or activated with Enter / Space while `clickableRightIcon` is set. No detail. |
|
|
144
|
+
|
|
145
|
+
## Slots
|
|
146
|
+
|
|
147
|
+
| Slot | Description |
|
|
148
|
+
| --- | --- |
|
|
149
|
+
| `prefix` | Custom content at the far left of the control (e.g. a unit dropdown); shares the prefix block with `prefixIcon` / `prefixText`. Hidden when `multiline` is set. |
|
|
150
|
+
| `suffix` | Custom content at the far right of the control (e.g. an action button); shares the suffix block with `rightIcon` / `suffixText`. Hidden when `multiline` is set. |
|
|
151
|
+
|
|
152
|
+
## CSS Parts
|
|
153
|
+
|
|
154
|
+
| Part | Description |
|
|
155
|
+
| --- | --- |
|
|
156
|
+
| `label` | The visible label element (default and floating label styles) |
|
|
157
|
+
| `input` | The native input / textarea |
|
|
158
|
+
| `right-icon` | The trailing `lof-icon` |
|
|
159
|
+
| `prefix` | The prefix block (leading icon, prefix text and the `prefix` slot) |
|
|
160
|
+
| `suffix` | The suffix block (suffix text, trailing icon and the `suffix` slot) |
|
|
161
|
+
| `helper` | The helper / error text line below the control |
|
|
162
|
+
| `helper-icon` | The leading `lof-icon` in the helper line; rendered only when `helper-icon` is set and there is helper text |
|
|
163
|
+
| `control` | The bordered control box. **Changed in 1.4.9:** in `variant="legend"` this is now the same `div` as every other variant, not the `fieldset` — the fieldset was demoted to a decorative outline layer behind the content so the control sits on the 32/40/48 size ladder and centres its value like the other variants. `::part(control)` still matches; only rules that depended on it being a fieldset do not. |
|
|
164
|
+
|
|
165
|
+
## Tokens / CSS Variables
|
|
166
|
+
|
|
167
|
+
### Component hooks
|
|
168
|
+
|
|
169
|
+
Set these on the host (or an ancestor) to customise the element without touching design tokens.
|
|
170
|
+
|
|
171
|
+
| Custom property | Default | Description |
|
|
172
|
+
| --- | --- | --- |
|
|
173
|
+
| `--lof-field-label-reserve` | `calc(var(--lof-body-md-regular-line-height) + var(--lof-spacing-2xs))` | Height held for the label row whenever no label renders above the control — `labelStyle="none"`, and `labelStyle="floating"` where the label sits inside the control — so the control 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). |
|
|
174
|
+
| `--lof-textfield-surface` | `var(--lof-bg-neutral)` | Colour of the strip the floating label lays over the control'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 the control's own fill (`--lof-bg-neutral`). Set it on a tinted or elevated surface, otherwise the strip shows as a light dash across the border. |
|
|
175
|
+
|
|
176
|
+
<!-- readme-gen:end -->
|
|
177
|
+
|
|
178
|
+
## Accessibility
|
|
179
|
+
|
|
180
|
+
- The visible `<label>` is linked to the native input via `for`/`id` (the host `id`, or a generated one). In the `legend` variant the input is instead named through `aria-labelledby` pointing at the `<legend>`.
|
|
181
|
+
- With `label-style="none"` no label renders: `field-aria-labelledby` (wins) or `field-aria-label` must supply the accessible name. The component logs a console warning once when neither is set, because a placeholder is not a valid naming mechanism.
|
|
182
|
+
- The input carries `aria-required`, `aria-invalid` (true in the error state) and `aria-describedby` pointing at the helper line. That line is always rendered with `aria-live="polite"`, so a change from helper text to `errorMessage` is announced.
|
|
183
|
+
- The leading icon is `aria-hidden` unless `prefixIconAriaLabel` is set, in which case it becomes `role="img"` with that label. The trailing icon is `aria-hidden` unless `clickable-right-icon` is set, in which case it is `role="button"`, `tabindex="0"` and named by `right-icon-aria-label`.
|
|
184
|
+
- No screen-reader announcements are made via `announce()`; the live helper region is the only announcement path.
|
|
185
|
+
|
|
186
|
+
| Key | Action |
|
|
187
|
+
|-----|--------|
|
|
188
|
+
| `Tab` | Focus the input; with `clickable-right-icon` the trailing icon is the next Tab stop |
|
|
189
|
+
| `Enter` / `Space` (on the trailing icon) | Fires `lof-right-icon-click` (default prevented) |
|
|
190
|
+
|
|
191
|
+
Focus behaviour: `focus()` on the host focuses the inner input / textarea (the host itself is not focusable). A mousedown anywhere on the control — border, legend notch, prefix / suffix padding — focuses the input like clicking a label would; presses on the input, a clickable icon or slotted content keep their native behaviour. The focused control shows a `--lof-border-strong` border plus a 1px ring; the `legend` variant recolours the border and legend only (a ring would strike through the notch).
|
|
192
|
+
|
|
193
|
+
## Notes / Edge Cases
|
|
194
|
+
|
|
195
|
+
- Attribute spellings: every multi-word attribute is kebab-case (`label-style`, `prefix-text`, `prefix-icon`, `left-icon`, `right-icon`, `prefix-icon-aria-label`, `helper-text`, `error-message`, `full-width`, …), the same spelling `lof-autocomplete` and `lof-select` use — see the Attribute column above. The older all-lowercase spellings still work since 1.5.0 but log a one-time console notice and are removed in 3.0 (see Deprecated aliases); when both spellings are present the kebab one wins. `maxlength` keeps the native HTML spelling, and the deprecated `supportingText` / `floatingLabel` props keep their old attributes. In a Lit template a property binding (`.prefixIcon=${…}`) sidesteps spelling entirely.
|
|
196
|
+
- Legacy names still work but the canonical ones win when both are set: `leftIcon` → `prefixIcon`, `supportingText` → `helperText`, `state="error"` → `error`, `state="disabled"` → `disabled`.
|
|
197
|
+
- `errorMessage` replaces the helper line only while the field is in the error state **and** the message is set; otherwise the helper text stays visible. There is no built-in validation — set `error` from your form layer.
|
|
198
|
+
- `state="error"` (legacy) auto-clears to `"default"` as soon as the user types a non-empty value and comes back once the value is emptied again; the `error` boolean never auto-clears.
|
|
199
|
+
- `multiline` renders a `<textarea>` (`rows`, vertical resize, 80px minimum height). `type`, the prefix / suffix blocks and their slots are ignored in this mode (the slots stay mounted but hidden).
|
|
200
|
+
- `fullWidth` defaults to `true`; without it the host becomes `inline-block` at its content width. Turn it off with `full-width="false"` (since 1.5.0) or the property (`.fullWidth=${false}`). In 1.x it still reflects as the `fullwidth` attribute, so `lof-textfield[fullwidth]` selectors keep matching.
|
|
201
|
+
- `label-style="floating"`: the placeholder is hidden until the field is focused; the label floats onto the border when focused or filled. Internally the deprecated `floatingLabel` boolean is kept in sync with `labelStyle` and its reflected `floatinglabel` attribute is the styling hook, so both spellings render identically. With a `prefix-style="clear"` prefix the floated label slides back over the control's left edge (Figma "Floating Label"); `divider` / `fill` prefixes keep it after the block.
|
|
202
|
+
- `variant="legend"` + `label-style="none"` drops the `<legend>` entirely so the top border runs continuous; a `fill` prefix is squared off in this variant because it cannot reach the notched top border.
|
|
203
|
+
- `--lof-field-label-reserve` (see Component hooks) keeps a `label-style="none"` field bottom-aligned with labelled siblings; set it to `0` in toolbars or table cells.
|
|
204
|
+
- Inside the prefix block the order is slotted content → icon → text (nearest the input); in the suffix block it is text → icon → slotted content. Clicking a non-interactive part of either block focuses the input.
|
|
205
|
+
- The control height (32 / 40 / 48px) is explicit so the field lines up with `lof-select` and the date / time / range picker triggers; the textarea keeps the padding model and grows with `rows`.
|
|
206
|
+
- In Figma, the `error` state's border has no focus ring; that matches the code (`box-shadow: none` in error).
|
|
@@ -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 32 / 40 / 48px, 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.
|