@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,221 @@
|
|
|
1
|
+
# lof-date-picker
|
|
2
|
+
|
|
3
|
+
`<lof-date-picker>` is the single-date form field of the Lofid Design System (Figma "Date Picker"). It is a text field you can type a date into, with a popover calendar whose header pills drill into month and year grids, above Today / Tomorrow / Yesterday shortcut chips. The committed `value` is always an ISO `YYYY-MM-DD` string; the visible text follows `locale`, `display-format` or a `formatDate` callback. Use it wherever a form needs one date. For a from/to range use `<lof-range-picker>`, for an always-visible grid use `<lof-calendar>`, for a time of day use `<lof-time-picker>`.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Basic labelled field -->
|
|
9
|
+
<lof-date-picker label="Start date"></lof-date-picker>
|
|
10
|
+
|
|
11
|
+
<!-- Preselected, clearable, required (adds * to the label and aria-required) -->
|
|
12
|
+
<lof-date-picker label="Appointment" value="2026-01-16" clearable required></lof-date-picker>
|
|
13
|
+
|
|
14
|
+
<!-- Bounded to 2026, Monday-first grid -->
|
|
15
|
+
<lof-date-picker label="Handoff" min-date="2026-01-01" max-date="2026-12-31" week-start="mon"></lof-date-picker>
|
|
16
|
+
|
|
17
|
+
<!-- Field heights 32 / 40 / 48; full-width fills the parent -->
|
|
18
|
+
<lof-date-picker size="small" label="Small"></lof-date-picker>
|
|
19
|
+
<lof-date-picker size="medium" label="Medium" variant="outlined"></lof-date-picker>
|
|
20
|
+
<lof-date-picker size="large" label="Large" full-width></lof-date-picker>
|
|
21
|
+
|
|
22
|
+
<!-- Hide the Today / Tomorrow / Yesterday chip row (on by default) -->
|
|
23
|
+
<lof-date-picker label="Due" show-shortcuts="false"></lof-date-picker>
|
|
24
|
+
|
|
25
|
+
<!-- Helper and error text below the field -->
|
|
26
|
+
<lof-date-picker label="Due" helper-text="Defaults to the next business day"></lof-date-picker>
|
|
27
|
+
<lof-date-picker label="Due" error error-message="Pick a date after today"></lof-date-picker>
|
|
28
|
+
|
|
29
|
+
<!-- Fixed display format and locale (value stays ISO) -->
|
|
30
|
+
<lof-date-picker value="2026-07-21" display-format="DD/MM/YYYY"></lof-date-picker>
|
|
31
|
+
<lof-date-picker value="2026-07-21" locale="es-ES"></lof-date-picker>
|
|
32
|
+
|
|
33
|
+
<!-- Read-only, disabled, and native form submission via a hidden input -->
|
|
34
|
+
<lof-date-picker label="Created" value="2026-01-16" readonly></lof-date-picker>
|
|
35
|
+
<lof-date-picker label="Archived" value="2026-01-16" disabled></lof-date-picker>
|
|
36
|
+
<lof-date-picker name="start" label="Start" placeholder="YYYY-MM-DD"></lof-date-picker>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```js
|
|
40
|
+
const picker = document.querySelector("lof-date-picker");
|
|
41
|
+
|
|
42
|
+
// Disable individual days on top of min-date/max-date (property only)
|
|
43
|
+
picker.isDateDisabled = (date) => date.getDay() === 0 || date.getDay() === 6;
|
|
44
|
+
|
|
45
|
+
// Full control of the visible text; wins over display-format
|
|
46
|
+
picker.formatDate = (date) => `Q${Math.floor(date.getMonth() / 3) + 1} ${date.getFullYear()}`;
|
|
47
|
+
|
|
48
|
+
// Keep the popover open after a pick (same as close-on-select="false" in markup)
|
|
49
|
+
picker.closeOnSelect = false;
|
|
50
|
+
|
|
51
|
+
picker.addEventListener("lof-change", (e) => {
|
|
52
|
+
e.detail.value; // "2026-01-16" or null when cleared
|
|
53
|
+
e.detail.date; // Date at local midnight, or null
|
|
54
|
+
});
|
|
55
|
+
picker.addEventListener("lof-open-change", (e) => e.detail.open);
|
|
56
|
+
picker.addEventListener("lof-blur", () => {/* run validation */});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Typed entry
|
|
60
|
+
|
|
61
|
+
The field is editable. Typed text is committed on Enter or when focus leaves the component; the parser (`date-parse.ts`) accepts ISO `2026-07-21`, numeric `21/7/2026` / `7/21/26`, month names `21 Jul 2026` / `July 21, 2026`, partial `21/7` (current year) or `21` (current month), and `20260721`. Two-digit years map to `20YY`. When day/month order is ambiguous (`3/4`), the order in `display-format` decides, else the locale's default numeric order. Shortcuts `t` / `today`, `t+7`, `t-3` resolve relative to today. Unparseable text shows "Invalid date", a date outside `min-date`/`max-date`/`isDateDisabled` shows "Date not available" — in both cases the text stays for correction and `value` is untouched; Escape reverts the text. Committing an empty field clears the value like the clear button does.
|
|
62
|
+
|
|
63
|
+
### Display format
|
|
64
|
+
|
|
65
|
+
Without `display-format` or `formatDate` the field shows the locale long date (`July 21, 2026`, `21 de julio de 2026` for `es-ES`). `display-format` tokens (`date-format.ts`), matched longest-first with other characters passed through and literal text in `[ ]`: `YYYY` 2026 · `YY` 26 · `MMMM` July · `MMM` Jul · `MM` 07 · `M` 7 · `DD` 21 · `D` 21. Named-month tokens follow `locale`.
|
|
66
|
+
|
|
67
|
+
### Deprecated aliases
|
|
68
|
+
|
|
69
|
+
```html
|
|
70
|
+
<!-- min / max → min-date / max-date. Both still work; min-date/max-date win when both are set. No console notice is logged. -->
|
|
71
|
+
<lof-date-picker min="2026-01-01" max="2026-12-31"></lof-date-picker>
|
|
72
|
+
<!-- canonical -->
|
|
73
|
+
<lof-date-picker min-date="2026-01-01" max-date="2026-12-31"></lof-date-picker>
|
|
74
|
+
|
|
75
|
+
<!-- fullwidth → full-width (since 1.5.0; still works, logs a one-time console notice, removed in 3.0) -->
|
|
76
|
+
<lof-date-picker label="Old spelling" fullwidth></lof-date-picker>
|
|
77
|
+
<lof-date-picker label="Canonical" full-width></lof-date-picker>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
<!-- readme-gen:start -->
|
|
81
|
+
|
|
82
|
+
<!-- Generated from lof-date-picker.ts — do not edit; run readme-generate.mjs -->
|
|
83
|
+
|
|
84
|
+
## API
|
|
85
|
+
|
|
86
|
+
### Attributes / Properties
|
|
87
|
+
|
|
88
|
+
| Property | Attribute | Type | Default | Description |
|
|
89
|
+
| --- | --- | --- | --- | --- |
|
|
90
|
+
| `value` | `value` | `string \| null` | `null` | Selected date as an ISO `YYYY-MM-DD` string, or `null` when empty; setting it also moves the popover to that month. Reflected. |
|
|
91
|
+
| `placeholder` | `placeholder` | `string` | `"Select date"` | Placeholder text shown while the field is empty (visual only; the accessible name comes from `label`, or "Select date" when unset). |
|
|
92
|
+
| `label` | `label` | `string \| null` | `null` | Visible label rendered above the field and wired to the input via `aria-labelledby`; `null` renders no label. |
|
|
93
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables the field, the icons and the popover. 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. |
|
|
94
|
+
| `required` | `required` | `boolean` | `false` | Appends a `*` to the label and sets `aria-required`; no validation is performed. |
|
|
95
|
+
| `readonly` | `readonly` | `boolean` | `false` | Makes the input read-only and stops the field, icon, Enter and ArrowDown from opening the popover. Reflected. |
|
|
96
|
+
| `minDate` | `min-date` | `string \| null` | `null` | Earliest selectable date (ISO `YYYY-MM-DD`); earlier days are disabled and typed dates before it are rejected. Wins over the deprecated `min`. |
|
|
97
|
+
| `maxDate` | `max-date` | `string \| null` | `null` | Latest selectable date (ISO `YYYY-MM-DD`); later days are disabled and typed dates after it are rejected. Wins over the deprecated `max`. |
|
|
98
|
+
| `weekStart` | `week-start` | `"sun" \| "mon"` | `"sun"` | First column of the calendar grid: `"sun"` (default) or `"mon"`. |
|
|
99
|
+
| `locale` | `locale` | `string` | `"en-US"` | BCP 47 locale for weekday/month names, the default long-date display, and day/month order when parsing ambiguous typed input. |
|
|
100
|
+
| `displayFormat` | `display-format` | `string \| null` | `null` | Token pattern for the displayed value (`YYYY`, `YY`, `MMMM`, `MMM`, `MM`, `M`, `DD`, `D`; literal text in `[ ]`), e.g. `DD/MM/YYYY`. Unset → the locale long date. Affects only the visible text, never `value`. |
|
|
101
|
+
| `formatDate` | — | `(date: Date) => string` | `undefined` | Callback with full control over the displayed value; wins over `displayFormat`. Assign it from JavaScript; it stays reactive so setting it after render re-renders the field. The Date it receives is at local midnight. Property only. |
|
|
102
|
+
| `open` | `open` | `boolean` | `false` | Whether the calendar popover is open; set it directly to open/close programmatically (focus then moves into the grid). Reflected. |
|
|
103
|
+
| `closeOnSelect` | `close-on-select` | `boolean` | `true` | Closes the popover after a day is picked in the grid (default `true`). |
|
|
104
|
+
| `clearable` | `clearable` | `boolean` | `false` | Shows a clear (×) icon while a value is set; clearing fires `lof-change` with `value: null`. |
|
|
105
|
+
| `showShortcuts` | `show-shortcuts` | `boolean` | `true` | Figma ".Date Picker Calendar" Show Shortcuts: renders the Today / Tomorrow / Yesterday chip row and its divider at the top of the popover. On by default — write `show-shortcuts="false"` to hide both (a plain boolean attribute could not express a default of `true`). The typed `T` / `T±N` shortcuts and the in-panel `T` key keep working either way. |
|
|
106
|
+
| `error` | `error` | `boolean` | `false` | Forces the error style (danger border, `aria-invalid`) and shows `errorMessage` below the field. Typed-entry parse errors set the same style on their own. |
|
|
107
|
+
| `errorMessage` | `error-message` | `string` | `undefined` | Text shown below the field while `error` is set (or a typed date failed to parse); falls back to `helperText`. |
|
|
108
|
+
| `helperText` | `helper-text` | `string` | `undefined` | Supporting text shown below the field when there is no error. |
|
|
109
|
+
| `name` | `name` | `string` | `undefined` | When set, renders a hidden `<input name>` carrying the ISO value so the picker submits with a native form. |
|
|
110
|
+
| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Field height scale shared with lof-textfield / lof-select: `small` 32px, `medium` 40px (default), `large` 48px. |
|
|
111
|
+
| `variant` | `variant` | `"outlined"` | `"outlined"` | Visual style of the field; `outlined` is the only variant today. Reflected. |
|
|
112
|
+
| `fullWidth` | `full-width` | `boolean` | `false` | Stretches the host to fill its parent's width (attribute `full-width`); off by default so the field keeps its intrinsic inline width. Reflected (as `fullwidth` in 1.x). The `fullwidth` attribute spelling is deprecated (still works; removal targeted for 3.0). |
|
|
113
|
+
|
|
114
|
+
#### Deprecated (still supported — removal targeted for 3.0)
|
|
115
|
+
|
|
116
|
+
| Property | Attribute | Type | Use instead |
|
|
117
|
+
| --- | --- | --- | --- |
|
|
118
|
+
| `min` | `min` | `string \| null` | use minDate |
|
|
119
|
+
| `max` | `max` | `string \| null` | use maxDate |
|
|
120
|
+
|
|
121
|
+
### Public fields / accessors
|
|
122
|
+
|
|
123
|
+
| Name | Type | Description |
|
|
124
|
+
| --- | --- | --- |
|
|
125
|
+
| `isDateDisabled` | `(date: Date) => boolean` | Custom predicate that disables individual days (return `true` to disable); applied on top of `minDate`/`maxDate` and also rejects typed input. Property only — assign it from JavaScript. |
|
|
126
|
+
|
|
127
|
+
## Events
|
|
128
|
+
|
|
129
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
130
|
+
| --- | --- | --- | --- |
|
|
131
|
+
| `lof-blur` | — | bubbles / composed | Fired when the text input loses focus (before any typed text is committed). No detail. |
|
|
132
|
+
| `lof-change` | `{ value: newValue, date: new Date(date), } / { value: null, date: null, } / { value: null, date: null }` | bubbles / composed | Fired when the value changes — grid pick, typed entry, shortcut, or clear. Detail: `{ value: string \| null, date: Date \| null }` (ISO `YYYY-MM-DD` and a local-midnight Date; both `null` when cleared). |
|
|
133
|
+
| `lof-open-change` | `{ open: this.open } / { open: false }` | bubbles / composed | Fired when the calendar popover opens or closes. Detail: `{ open: boolean }`. |
|
|
134
|
+
|
|
135
|
+
## Slots
|
|
136
|
+
|
|
137
|
+
| Slot | Description |
|
|
138
|
+
| --- | --- |
|
|
139
|
+
| — | This element has no slots. |
|
|
140
|
+
|
|
141
|
+
## CSS Parts
|
|
142
|
+
|
|
143
|
+
| Part | Description |
|
|
144
|
+
| --- | --- |
|
|
145
|
+
| `unavailable` | Day cells that cannot be picked (outside `min-date` / `max-date`, or blocked by `isDateDisabled`). They are `aria-disabled` and stay focusable, so `:disabled` does not match them; style them with `::part(unavailable)` |
|
|
146
|
+
| `base` | Outer wrapper carrying the size class (`small` / `medium` / `large`) |
|
|
147
|
+
| `label` | The visible field label (rendered only when `label` is set) |
|
|
148
|
+
| `trigger` | The field box that wraps the text input and the clear/calendar icons |
|
|
149
|
+
| `value` | The editable text input inside the trigger |
|
|
150
|
+
| `shortcuts` | The Today / Tomorrow / Yesterday chip row at the top of the popover |
|
|
151
|
+
|
|
152
|
+
## Tokens / CSS Variables
|
|
153
|
+
|
|
154
|
+
### Component hooks
|
|
155
|
+
|
|
156
|
+
Set these on the host (or an ancestor) to customise the element without touching design tokens.
|
|
157
|
+
|
|
158
|
+
| Custom property | Default | Description |
|
|
159
|
+
| --- | --- | --- |
|
|
160
|
+
| `--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. |
|
|
161
|
+
|
|
162
|
+
<!-- readme-gen:end -->
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
## CSS Custom Properties
|
|
166
|
+
|
|
167
|
+
| Custom property | Default | Description |
|
|
168
|
+
| --- | --- | --- |
|
|
169
|
+
| `--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. |
|
|
170
|
+
## Accessibility
|
|
171
|
+
|
|
172
|
+
- The text input is a `role="combobox"` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel, `aria-required` from `required`, `aria-invalid` when `error` is set or typed text failed to parse, and `aria-describedby` pointing at the helper/error line. Its name is the `label` (via `aria-labelledby`) or the fixed string "Select date" when no label is set; the required `*` is `aria-hidden`.
|
|
173
|
+
- The icons are real buttons: "Clear date" (only while `clearable` and a value is set) and "Open calendar" (carries `aria-expanded`).
|
|
174
|
+
- The popover is a `role="dialog"` named "Choose date". While it is open, Tab and Shift+Tab are trapped inside it (`trapTabKey`), and Escape closes it from anywhere in the document.
|
|
175
|
+
- The month and year pills are buttons carrying `aria-expanded`; pressing one swaps the panel body for a `role="grid"` of `role="gridcell"` cells ("Select month" / "Select year") with `aria-selected` on the current value. Every view is 252 px tall, so the panel never resizes as the user drills in.
|
|
176
|
+
- The day grid is `role="grid"` named "<Month> <Year>"; weeks are `role="row"`; each day is a `<button role="gridcell">` with the full long date as `aria-label`, `aria-selected`, `aria-current="date"` on today and `aria-disabled="true"` for unavailable days (changed, unreleased — they used to be native `disabled`, which could not take focus). Exactly one cell is a Tab stop: the day last interacted with (arrowed to, clicked or tabbed onto), else the selected day, else today, else the first enabled day — so Shift+Tab then Tab returns to the day you left. The arrow keys move by date, not by grid position, so they stay on the right day when the view flips month (unreleased fix: Sep 27 + ArrowDown used to land on Nov 1 instead of Oct 4). The key map is shared with `lof-range-picker`.
|
|
177
|
+
- Focus: opening from the calendar icon, Enter, ArrowDown or by setting `open` moves focus into the grid (onto that Tab-stop cell) after 100 ms; opening by clicking into the text keeps focus in the input so typing keeps working. Closing via Escape, a pick or a shortcut returns focus to the input; an outside click closes without refocusing.
|
|
178
|
+
- Screen readers hear "<Month> <Year>" through the shared `announce()` region (`utils/announce.ts`) on every month/year change (chevrons, a month or year cell, PageUp/PageDown, arrowing across a month boundary), and the first and last year of the page (e.g. "2020 to 2031") when the years page changes. The helper/error line is a persistent `aria-live="polite"` region, so parse errors are read as they appear.
|
|
179
|
+
|
|
180
|
+
| Key (in the field) | Action |
|
|
181
|
+
| --- | --- |
|
|
182
|
+
| Enter | Nothing typed: open the popover. Text typed: commit it |
|
|
183
|
+
| ArrowDown | Open the popover; if already open, move focus into the grid |
|
|
184
|
+
| Escape | Revert uncommitted text and close the popover |
|
|
185
|
+
| Tab (popover open) | Cycle through the popover's controls |
|
|
186
|
+
|
|
187
|
+
| Key (in the grid) | Action |
|
|
188
|
+
| --- | --- |
|
|
189
|
+
| ArrowLeft / ArrowRight | Previous / next day (switches month at the edge) |
|
|
190
|
+
| ArrowUp / ArrowDown | Same weekday one week earlier / later |
|
|
191
|
+
| Home / End | First / last day of the week, honouring `week-start` (switches month if that day is in the adjacent month) |
|
|
192
|
+
| PageUp / PageDown | Same day previous / next month (clamped to the month's last day, e.g. 31 Jan → 28 Feb) |
|
|
193
|
+
| Shift + PageUp / Shift + PageDown | Same day previous / next year |
|
|
194
|
+
| Enter / Space | Select the day; closes the popover unless `closeOnSelect` is false. Does nothing on an unavailable day — the arrows land on those days rather than skipping them |
|
|
195
|
+
| T (anywhere in the popover, no modifier) | Select today |
|
|
196
|
+
| Escape | Close and return focus to the input |
|
|
197
|
+
|
|
198
|
+
| Key (month / year grid) | Action |
|
|
199
|
+
| --- | --- |
|
|
200
|
+
| Enter / Space on a pill | Open that grid; press the same pill again to return to the days |
|
|
201
|
+
| ArrowLeft / ArrowRight | Previous / next cell |
|
|
202
|
+
| ArrowUp / ArrowDown | Same column, one row up / down |
|
|
203
|
+
| Home / End | First / last cell of the grid |
|
|
204
|
+
| Enter / Space | Choose the cell — a year drills into the months, a month returns to the days |
|
|
205
|
+
| Escape | Back to the days grid, keeping the popover open |
|
|
206
|
+
|
|
207
|
+
## Notes / Edge Cases
|
|
208
|
+
|
|
209
|
+
- `value` is always ISO `YYYY-MM-DD`; `display-format` and `formatDate` change only the visible text. The `Date` given to `formatDate`, `isDateDisabled` and `lof-change` is at local midnight — read it with `getFullYear()`/`getMonth()`/`getDate()`, never `toISOString()` (which can shift the day by the UTC offset). For a plain ISO display use `display-format="YYYY-MM-DD"`.
|
|
210
|
+
- `min`/`max` are deprecated aliases of `min-date`/`max-date`; when both spellings are present the canonical one wins. No runtime notice is logged.
|
|
211
|
+
- Leading and trailing cells of adjacent months are interactive, as in `lof-calendar` (changed, unreleased — they used to be disabled): they hover, focus and select like any other day, and `min-date` / `max-date` / `isDateDisabled` disable them exactly as they would an in-month day. Their label, like a weekend's, uses the caption colour (`--lof-text-caption`) unless selected (1.5.0; it used to fade to 40%, weekends to 70%). Picking one with `closeOnSelect = false` moves the view to that day's month and focus to the new selection.
|
|
212
|
+
- The years grid shows one 12-year page at a time, anchored so the year in view sits in the seventh cell; the chevrons page by 12. In the months grid the chevrons step a year, and in the days grid a month. A month or year cell is disabled only when *every* day it covers falls outside `min-date`/`max-date`.
|
|
213
|
+
- The panel always reopens on the days grid, whichever view was showing when it closed.
|
|
214
|
+
- The field is Figma's TextField instance: `border-radius: xs` (4 px), 12 px inline padding at `medium`, a 4 px label gap and an 18 px suffix icon — the same geometry `lof-textfield` uses, so the two line up in a shared form row. Icon and inline padding step with `size` (16/18/20 px and 8/12/16 px).
|
|
215
|
+
- The panel is promoted to the browser top layer (`popover="manual"`), so it renders above `lof-modal` / `lof-drawer` and transformed or `overflow: hidden` ancestors. It repositions on resize. 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`). It flips above the trigger when there is no room below, stays 8 px inside the viewport, is capped at 600 px tall (scrolls) and never wider than the viewport.
|
|
216
|
+
- Below-field text resolves as `errorMessage ?? typed-entry error ?? helperText` while in error, else `helperText`. A typed-entry error styles the field like `error` without setting the property.
|
|
217
|
+
- `readonly` and `disabled` both stop the popover from opening (field click, icon, Enter, ArrowDown); `disabled` also blocks all pointer events.
|
|
218
|
+
- `closeOnSelect` defaults to true; turn it off with `close-on-select="false"` (since 1.5.0) or `picker.closeOnSelect = false`. It affects grid picks only — typed entry and shortcuts always close the popover.
|
|
219
|
+
- The `name` hidden input submits an empty string while `value` is null.
|
|
220
|
+
- `size` is applied as a class on part `base` (not reflected); `variant` currently has the single value `outlined`.
|
|
221
|
+
- The host is `inline-block` with an intrinsic width (min 200 px) by default; `full-width` switches it to a block that fills the parent.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# lof-divider
|
|
2
|
+
|
|
3
|
+
A thin separator rule, horizontal or vertical, drawn with the neutral elevated background token at the small stroke width and padded by the medium spacing token. Use it to visually split sections, list groups or toolbar clusters. Do not use it purely as a spacer — use layout gaps for that.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Horizontal (default): full width, vertical margin -->
|
|
9
|
+
<section>
|
|
10
|
+
<h2>Section A</h2>
|
|
11
|
+
<p>Content A</p>
|
|
12
|
+
</section>
|
|
13
|
+
<lof-divider></lof-divider>
|
|
14
|
+
<section>
|
|
15
|
+
<h2>Section B</h2>
|
|
16
|
+
<p>Content B</p>
|
|
17
|
+
</section>
|
|
18
|
+
|
|
19
|
+
<!-- Vertical: give the parent a height or use a flex row -->
|
|
20
|
+
<div style="display: flex; align-items: center; height: 40px;">
|
|
21
|
+
<lof-button variant="ghost">Cut</lof-button>
|
|
22
|
+
<lof-divider orientation="vertical"></lof-divider>
|
|
23
|
+
<lof-button variant="ghost">Copy</lof-button>
|
|
24
|
+
<lof-divider orientation="vertical"></lof-divider>
|
|
25
|
+
<lof-button variant="ghost">Paste</lof-button>
|
|
26
|
+
</div>
|
|
27
|
+
|
|
28
|
+
<!-- Restyle through the part -->
|
|
29
|
+
<style>
|
|
30
|
+
.thick::part(base) {
|
|
31
|
+
height: 2px;
|
|
32
|
+
margin: 24px 0;
|
|
33
|
+
}
|
|
34
|
+
</style>
|
|
35
|
+
<lof-divider class="thick"></lof-divider>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
<!-- readme-gen:start -->
|
|
39
|
+
|
|
40
|
+
<!-- Generated from lof-divider.ts — do not edit; run readme-generate.mjs -->
|
|
41
|
+
|
|
42
|
+
## API
|
|
43
|
+
|
|
44
|
+
### Attributes / Properties
|
|
45
|
+
|
|
46
|
+
| Property | Attribute | Type | Default | Description |
|
|
47
|
+
| --- | --- | --- | --- | --- |
|
|
48
|
+
| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Axis of the rule: `horizontal` spans the full width with vertical margin; `vertical` is a full-height line with horizontal margin (the parent needs a defined height or a flex row). Mirrored to `aria-orientation` on the host. |
|
|
49
|
+
|
|
50
|
+
## Events
|
|
51
|
+
|
|
52
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
53
|
+
| --- | --- | --- | --- |
|
|
54
|
+
| — | — | — | This element emits no custom events. |
|
|
55
|
+
|
|
56
|
+
## Slots
|
|
57
|
+
|
|
58
|
+
| Slot | Description |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| — | This element has no slots. |
|
|
61
|
+
|
|
62
|
+
## CSS Parts
|
|
63
|
+
|
|
64
|
+
| Part | Description |
|
|
65
|
+
| --- | --- |
|
|
66
|
+
| `base` | The rendered rule — restyle thickness, colour or margin here. |
|
|
67
|
+
|
|
68
|
+
## Tokens / CSS Variables
|
|
69
|
+
|
|
70
|
+
### Component hooks
|
|
71
|
+
|
|
72
|
+
Set these on the host (or an ancestor) to customise the element without touching design tokens.
|
|
73
|
+
|
|
74
|
+
| Custom property | Default | Description |
|
|
75
|
+
| --- | --- | --- |
|
|
76
|
+
| `--lof-divider-spacing` | `var(--lof-spacing-md)` | Cross-axis margin around the rule; default 16px. Figma specifies none, so set it to `0` for strict parity — the default is kept for back-compat and is planned to become `0` in 3.0. |
|
|
77
|
+
|
|
78
|
+
<!-- readme-gen:end -->
|
|
79
|
+
|
|
80
|
+
## Accessibility
|
|
81
|
+
|
|
82
|
+
- The host receives `role="separator"` when connected and `aria-orientation` (`horizontal` or `vertical`) on every update, so screen readers announce it as a separator in the right axis. The inner rule also carries `role="separator"`.
|
|
83
|
+
- Not focusable; no keyboard interaction.
|
|
84
|
+
|
|
85
|
+
## Notes / Edge Cases
|
|
86
|
+
|
|
87
|
+
- **Vertical dividers need a height.** The vertical rule is `height: 100%` with `align-self: stretch`; inside a flex row it stretches to the row, otherwise the parent must have a definite height or the rule collapses to 0px.
|
|
88
|
+
- The host is `display: block` with a transparent background; the visible line is the inner `base` part. Override thickness, colour or margin via `::part(base)` rather than on the host.
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# lof-drawer
|
|
2
|
+
|
|
3
|
+
`<lof-drawer>` implements the Figma **Drawer** component (5699:6844): a panel that slides in from the bottom, left or right edge over a scrim, with an optional drag-to-close handle on bottom drawers, a title/description header, a scrollable body and a footer. The folder also registers `<lof-drawer-footer>`, the right-aligned actions row the drawer uses for its `footer` slot, which can be reused standalone. Use a drawer for side navigation, filter panels and secondary editing flows that should stay attached to a viewport edge; use `<lof-modal>` for confirmations and short dialogs, and `<lof-popover>` for small contextual content anchored to a trigger.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Bottom drawer (default) with header, body and footer actions -->
|
|
9
|
+
<lof-button id="open-filters">Filters</lof-button>
|
|
10
|
+
|
|
11
|
+
<lof-drawer id="filters" title="Filters" description="Narrow down the results.">
|
|
12
|
+
<p>Filter controls go here.</p>
|
|
13
|
+
<lof-button slot="footer" variant="secondary" id="reset">Reset</lof-button>
|
|
14
|
+
<lof-button slot="footer" variant="primary" tone="brand" id="apply">Apply</lof-button>
|
|
15
|
+
</lof-drawer>
|
|
16
|
+
|
|
17
|
+
<script>
|
|
18
|
+
const drawer = document.getElementById('filters');
|
|
19
|
+
document.getElementById('open-filters').addEventListener('click', () => { drawer.open = true; });
|
|
20
|
+
document.getElementById('apply').addEventListener('click', () => { drawer.open = false; });
|
|
21
|
+
drawer.addEventListener('lof-open-change', (e) => {
|
|
22
|
+
console.log('open =', e.detail.open);
|
|
23
|
+
});
|
|
24
|
+
</script>
|
|
25
|
+
|
|
26
|
+
<!-- Right side panel with an explicit width -->
|
|
27
|
+
<lof-drawer side="right" width="360px" title="Settings">
|
|
28
|
+
<p>Account settings.</p>
|
|
29
|
+
</lof-drawer>
|
|
30
|
+
|
|
31
|
+
<!-- Left navigation drawer -->
|
|
32
|
+
<lof-drawer side="left" title="Menu">
|
|
33
|
+
<nav>
|
|
34
|
+
<a href="/home">Home</a>
|
|
35
|
+
<a href="/reports">Reports</a>
|
|
36
|
+
</nav>
|
|
37
|
+
</lof-drawer>
|
|
38
|
+
|
|
39
|
+
<!-- Bottom drawer that closes after a longer drag -->
|
|
40
|
+
<lof-drawer snap-threshold="0.5" title="Share">
|
|
41
|
+
<p>Drag the handle down past half the panel to close.</p>
|
|
42
|
+
</lof-drawer>
|
|
43
|
+
|
|
44
|
+
<!-- Non-modal, persistent side panel (no scrim, no focus trap, not dismissible) -->
|
|
45
|
+
<lof-drawer id="sidebar" side="left" open>
|
|
46
|
+
<p>Always-on sidebar content.</p>
|
|
47
|
+
</lof-drawer>
|
|
48
|
+
<script>
|
|
49
|
+
// Boolean props that default to true can only be switched off from JS —
|
|
50
|
+
// an absent attribute leaves the default in place.
|
|
51
|
+
const sidebar = document.getElementById('sidebar');
|
|
52
|
+
sidebar.modal = false;
|
|
53
|
+
sidebar.dismissible = false;
|
|
54
|
+
</script>
|
|
55
|
+
|
|
56
|
+
<!-- Standalone actions row using the same layout as the drawer footer -->
|
|
57
|
+
<lof-drawer-footer>
|
|
58
|
+
<lof-button variant="secondary">Cancel</lof-button>
|
|
59
|
+
<lof-button variant="primary" tone="brand">Save</lof-button>
|
|
60
|
+
</lof-drawer-footer>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
<!-- readme-gen:start -->
|
|
64
|
+
|
|
65
|
+
<!-- Generated from lof-drawer.ts, lof-drawer-footer.ts — do not edit; run readme-generate.mjs -->
|
|
66
|
+
|
|
67
|
+
## Elements
|
|
68
|
+
|
|
69
|
+
| Element | Class | Source |
|
|
70
|
+
| --- | --- | --- |
|
|
71
|
+
| `<lof-drawer>` | `LofDrawer` | `lof-drawer.ts` |
|
|
72
|
+
| `<lof-drawer-footer>` | `LofDrawerFooter` | `lof-drawer-footer.ts` |
|
|
73
|
+
|
|
74
|
+
## API
|
|
75
|
+
|
|
76
|
+
### `<lof-drawer>`
|
|
77
|
+
|
|
78
|
+
#### Attributes / Properties
|
|
79
|
+
|
|
80
|
+
| Property | Attribute | Type | Default | Description |
|
|
81
|
+
| --- | --- | --- | --- | --- |
|
|
82
|
+
| `open` | `open` | `boolean` | `false` | Whether the drawer is shown. Toggle it to open/close; every change fires `lof-open-change`. Reflected. |
|
|
83
|
+
| `side` | `side` | `"bottom" \| "left" \| "right"` | `"bottom"` | Edge the panel slides in from. `bottom` is centred horizontally and supports the drag handle; `left`/`right` are full-height side panels. |
|
|
84
|
+
| `dismissible` | `dismissible` | `boolean` | `true` | When false the close button is hidden and backdrop clicks / Escape are ignored (drag-to-close still works). |
|
|
85
|
+
| `modal` | `modal` | `boolean` | `true` | Modal mode: renders the scrim, sets `role="dialog"` + `aria-modal`, traps Tab inside the panel and moves focus in on open. When false the panel is a `region` with no scrim and no focus trap. |
|
|
86
|
+
| `closeOnBackdrop` | `close-on-backdrop` | `boolean` | `true` | Close when the scrim is clicked. Only effective while `dismissible` is true. |
|
|
87
|
+
| `closeOnEscape` | `close-on-escape` | `boolean` | `true` | Close on the Escape key. Only effective while `dismissible` is true. |
|
|
88
|
+
| `showHandle` | `show-handle` | `boolean` | `true` | Show the grab bar above the header. Only rendered when `side="bottom"` and `draggable` is true. |
|
|
89
|
+
| `draggable` | `draggable` | `boolean` | `true` | Enable drag-to-close on the handle (pointer or touch). Bottom drawers only. |
|
|
90
|
+
| `snapThreshold` | `snap-threshold` | `number` | `0.25` | Fraction (0–1) of the panel height the user must drag down before release closes the drawer; shorter drags snap back. |
|
|
91
|
+
| `maxHeight` | `max-height` | `string` | `"80vh"` | Written to the panel as the `--drawer-max-height` custom property (any CSS length). No built-in rule reads it yet; use `--lof-drawer-height` to size a bottom drawer. |
|
|
92
|
+
| `width` | `width` | `string` | `""` | Explicit panel width (any CSS length). Empty by default, which uses the per-side `--lof-drawer-width` default. |
|
|
93
|
+
| `title` | `title` | `string` | `""` | Heading text (rendered as an `<h2>`, linked via `aria-labelledby`). |
|
|
94
|
+
| `description` | `description` | `string` | `""` | Supporting text under the title (linked via `aria-describedby`). |
|
|
95
|
+
|
|
96
|
+
### Events
|
|
97
|
+
|
|
98
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
99
|
+
| --- | --- | --- | --- |
|
|
100
|
+
| `lof-open-change` | `{ open: true } / { open: false }` | bubbles / composed | Fired whenever `open` changes, from any cause (prop set, close button, backdrop, Escape, drag). Detail: `{ open: boolean }`. |
|
|
101
|
+
|
|
102
|
+
### Slots
|
|
103
|
+
|
|
104
|
+
| Slot | Description |
|
|
105
|
+
| --- | --- |
|
|
106
|
+
| (default) | Body content of the drawer |
|
|
107
|
+
| `footer` | Actions row; rendered inside a `<lof-drawer-footer>` (right-aligned, 8px gap). The footer only renders when this slot has content; its top divider shows only while the body scrolls |
|
|
108
|
+
|
|
109
|
+
### CSS Parts
|
|
110
|
+
|
|
111
|
+
| Part | Description |
|
|
112
|
+
| --- | --- |
|
|
113
|
+
| `overlay` | The full-viewport scrim behind the panel |
|
|
114
|
+
| `panel` | The sliding panel (role="dialog") |
|
|
115
|
+
| `handle` | The drag-to-close grab bar (bottom drawers only) |
|
|
116
|
+
| `header` | Header block holding title, description and close button |
|
|
117
|
+
| `close-button` | The "X" close button |
|
|
118
|
+
| `content` | Scrollable body wrapper around the default slot |
|
|
119
|
+
| `footer` | Footer wrapper around the `footer` slot |
|
|
120
|
+
|
|
121
|
+
### Tokens / CSS Variables
|
|
122
|
+
|
|
123
|
+
#### Component hooks
|
|
124
|
+
|
|
125
|
+
Set these on the host (or an ancestor) to customise the element without touching design tokens.
|
|
126
|
+
|
|
127
|
+
| Custom property | Default | Description |
|
|
128
|
+
| --- | --- | --- |
|
|
129
|
+
| `--lof-drawer-height` | `var(--drawer-height, clamp(360px, 49vh, 600px))` | Panel height for `side="bottom"`; default `clamp(360px, 49vh, 600px)`. Left/right drawers are always full height |
|
|
130
|
+
| `--lof-drawer-scrim-opacity` | `1` | Opacity of the scrim while open; default `1` |
|
|
131
|
+
| `--lof-drawer-transition-duration` | `var(--drawer-transition-duration)` | Slide/scrim animation duration; default `0.3s` |
|
|
132
|
+
| `--lof-drawer-transition-timing` | `var(--drawer-transition-timing)` | Slide/scrim animation easing; default `cubic-bezier(0.32, 0.72, 0, 1)` |
|
|
133
|
+
| `--lof-drawer-width` | `var(--drawer-width, clamp(640px, 66vw, 952px))` | Panel width. Default `clamp(640px, 66vw, 952px)` for `side="bottom"`, `clamp(280px, 24vw, 420px)` for left/right. The `width` prop sets this on the panel and wins over a host value |
|
|
134
|
+
|
|
135
|
+
### `<lof-drawer-footer>`
|
|
136
|
+
|
|
137
|
+
#### Attributes / Properties
|
|
138
|
+
|
|
139
|
+
| Property | Attribute | Type | Default | Description |
|
|
140
|
+
| --- | --- | --- | --- | --- |
|
|
141
|
+
| — | — | — | — | No public properties. |
|
|
142
|
+
|
|
143
|
+
### Events
|
|
144
|
+
|
|
145
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
146
|
+
| --- | --- | --- | --- |
|
|
147
|
+
| — | — | — | This element emits no custom events. |
|
|
148
|
+
|
|
149
|
+
### Slots
|
|
150
|
+
|
|
151
|
+
| Slot | Description |
|
|
152
|
+
| --- | --- |
|
|
153
|
+
| (default) | Footer actions (typically `<lof-button>`s) |
|
|
154
|
+
|
|
155
|
+
### CSS Parts
|
|
156
|
+
|
|
157
|
+
| Part | Description |
|
|
158
|
+
| --- | --- |
|
|
159
|
+
| — | None exposed. |
|
|
160
|
+
|
|
161
|
+
<!-- readme-gen:end -->
|
|
162
|
+
|
|
163
|
+
## Accessibility
|
|
164
|
+
|
|
165
|
+
- The panel is `role="dialog"` with `aria-modal="true"` while `modal` is on; with `modal` off it becomes a `role="region"` without scrim or focus trap.
|
|
166
|
+
- `aria-labelledby` points at the rendered `<h2>` when `title` is set, otherwise the panel carries `aria-label="Drawer"`; `aria-describedby` points at the description paragraph when `description` is set.
|
|
167
|
+
- The close button is a real `<button>` with `aria-label="Close"`. It is rendered whenever `dismissible` is on.
|
|
168
|
+
- A body that overflows becomes a Tab stop so the keyboard can scroll it: `tabindex="0"`, `role="region"`, named by the title (`aria-label="Drawer content"` without one), with the 2px focus ring inside its edge. It is never the initial focus, and the attributes go away again when the body stops overflowing.
|
|
169
|
+
- Focus: on open in modal mode focus moves to the first focusable element inside the panel, or to the panel itself (`tabindex="-1"`). On close focus always returns to the element that was active before opening — resolved through shadow roots, so a `<lof-button>` opener gets focus back.
|
|
170
|
+
- Body scroll is locked while open; the scrollbar width is added as body padding so the page does not shift.
|
|
171
|
+
- The drag handle is pointer-only (`touch-action: none`); keyboard users close with `Escape` or the close button.
|
|
172
|
+
- `prefers-reduced-motion: reduce` removes the slide/fade transitions and hides the closed panel outright.
|
|
173
|
+
|
|
174
|
+
| Key | Action |
|
|
175
|
+
| --- | --- |
|
|
176
|
+
| `Escape` | Closes the drawer when `dismissible` and `close-on-escape` are on. |
|
|
177
|
+
| `Tab` / `Shift+Tab` | Cycles focus inside the panel while `modal` is on (focus trap); wraps at either end. |
|
|
178
|
+
|
|
179
|
+
## Notes / Edge Cases
|
|
180
|
+
|
|
181
|
+
- Drag-to-close only exists for `side="bottom"` and only when `draggable` is on; the handle is additionally hidden when `show-handle` is off. Dragging is one-directional (down); release past `snap-threshold` × panel height closes, shorter drags snap back. The scrim fades in proportion to the drag. Drag still closes the drawer when `dismissible` is off.
|
|
182
|
+
- `lof-open-change` is the only event; it fires for every `open` change including programmatic ones. The exported `DrawerCloseReason` type is used internally only — the event detail does not carry a reason.
|
|
183
|
+
- Boolean props default to `true` (`dismissible`, `modal`, `close-on-backdrop`, `close-on-escape`, `show-handle`, `draggable`); an absent attribute keeps the default, so switch them off from JavaScript (`drawer.modal = false`).
|
|
184
|
+
- `width` is written to the panel as an inline `--lof-drawer-width`, so it wins over a `--lof-drawer-width` set on the host. Leave it empty to use the per-side defaults.
|
|
185
|
+
- `max-height` is written to the panel as `--drawer-max-height` but no rule reads it yet; size bottom drawers with `--lof-drawer-height` instead.
|
|
186
|
+
- After a left/right drawer finishes sliding in, its `transform` is dropped so `position: fixed` descendants (select menus, popovers, tooltips, date pickers) are no longer clipped to the panel. Bottom drawers keep their transform because it centres them.
|
|
187
|
+
- The header always has a bottom border. The footer wrapper only renders when the `footer` slot has content (the host gains a `has-footer` attribute while it does), so a drawer without actions has no empty footer band. Its top divider shows only while the body scrolls (the host gains `body-scrolls`); short content has no footer divider. Scrolling is re-measured when the body or any slotted child resizes, so content added after opening, children growing in place, images loading and window resizes all update it.
|
|
188
|
+
- Legacy hook aliases still honoured: `--drawer-width`, `--drawer-height`, `--drawer-transition-duration` and `--drawer-transition-timing` are read as fallbacks of the `--lof-drawer-*` hooks. `--lof-drawer-scrim-opacity` has no legacy alias.
|