@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,111 @@
|
|
|
1
|
+
# lof-calendar
|
|
2
|
+
|
|
3
|
+
`<lof-calendar>` is the inline, always-visible month calendar of the Lofid Design System (Figma "Calendar"). It renders one month as a 7-column grid with previous/next navigation, a today ring, dimmed weekends and adjacent-month days, `min`/`max` bounds and a custom disabled-day predicate, and lets the user select a single date. Use it when the calendar itself is the interface — a scheduling sidebar, an inline availability view. For a form field that opens a calendar in a popover use `<lof-date-picker>`; for a from/to range use `<lof-range-picker>`.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Default: today's month, nothing selected -->
|
|
9
|
+
<lof-calendar></lof-calendar>
|
|
10
|
+
|
|
11
|
+
<!-- Preselected date (ISO YYYY-MM-DD); the grid opens on that month -->
|
|
12
|
+
<lof-calendar value="2026-01-16"></lof-calendar>
|
|
13
|
+
|
|
14
|
+
<!-- Bounded: days outside min/max render disabled -->
|
|
15
|
+
<lof-calendar min="2026-01-01" max="2026-12-31"></lof-calendar>
|
|
16
|
+
|
|
17
|
+
<!-- Monday-first week with German month and weekday names -->
|
|
18
|
+
<lof-calendar week-start="mon" locale="de-DE"></lof-calendar>
|
|
19
|
+
|
|
20
|
+
<!-- Disabled: every cell and both navigation buttons are inert -->
|
|
21
|
+
<lof-calendar value="2026-01-16" disabled></lof-calendar>
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
```js
|
|
25
|
+
const calendar = document.querySelector("lof-calendar");
|
|
26
|
+
|
|
27
|
+
// Disable individual days on top of min/max (property only — there is no attribute)
|
|
28
|
+
calendar.isDateDisabled = (date) => date.getDay() === 0 || date.getDay() === 6;
|
|
29
|
+
|
|
30
|
+
calendar.addEventListener("lof-change", (e) => {
|
|
31
|
+
e.detail.value; // "2026-01-16"
|
|
32
|
+
e.detail.date; // Date at local midnight
|
|
33
|
+
});
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
<!-- readme-gen:start -->
|
|
37
|
+
|
|
38
|
+
<!-- Generated from lof-calendar.ts — do not edit; run readme-generate.mjs -->
|
|
39
|
+
|
|
40
|
+
## API
|
|
41
|
+
|
|
42
|
+
### Attributes / Properties
|
|
43
|
+
|
|
44
|
+
| Property | Attribute | Type | Default | Description |
|
|
45
|
+
| --- | --- | --- | --- | --- |
|
|
46
|
+
| `value` | `value` | `string \| null` | `null` | Selected date as an ISO `YYYY-MM-DD` string, or `null` for no selection; setting it also moves the visible month. Reflected. |
|
|
47
|
+
| `min` | `min` | `string \| null` | `null` | Earliest selectable date (ISO `YYYY-MM-DD`); earlier days render disabled. |
|
|
48
|
+
| `max` | `max` | `string \| null` | `null` | Latest selectable date (ISO `YYYY-MM-DD`); later days render disabled. |
|
|
49
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables every day cell and the month navigation; the host dims to 40% opacity (Figma State=Disabled). Reflected. |
|
|
50
|
+
| `weekStart` | `week-start` | `"sun" \| "mon"` | `"sun"` | First column of the week grid: `"sun"` (default) or `"mon"`. |
|
|
51
|
+
| `locale` | `locale` | `string` | `"en-US"` | BCP 47 locale for the month name, weekday headers and day cell labels (via `Intl.DateTimeFormat`). |
|
|
52
|
+
|
|
53
|
+
### Public fields / accessors
|
|
54
|
+
|
|
55
|
+
| Name | Type | Description |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| `isDateDisabled` | `(date: Date) => boolean` | Custom predicate that disables individual days (return `true` to disable); applied on top of `min`/`max`. Property only — assign it from JavaScript. |
|
|
58
|
+
|
|
59
|
+
## Events
|
|
60
|
+
|
|
61
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
62
|
+
| --- | --- | --- | --- |
|
|
63
|
+
| `lof-change` | `{ value: newValue, date: new Date(day.date), }` | bubbles / composed | Fired when the user selects a day. Detail: `{ value: string, date: Date }` — the ISO `YYYY-MM-DD` string and a local-midnight Date. |
|
|
64
|
+
|
|
65
|
+
## Slots
|
|
66
|
+
|
|
67
|
+
| Slot | Description |
|
|
68
|
+
| --- | --- |
|
|
69
|
+
| — | This element has no slots. |
|
|
70
|
+
|
|
71
|
+
## CSS Parts
|
|
72
|
+
|
|
73
|
+
| Part | Description |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| `header` | Month navigation row (previous button, month/year label, next button) |
|
|
76
|
+
| `action` | The previous-month and next-month buttons |
|
|
77
|
+
| `label` | The month/year heading and each weekday column header |
|
|
78
|
+
| `list` | The weekday-header row and the day grid |
|
|
79
|
+
| `item` | Each day cell button (unavailable days also carry `unavailable`) |
|
|
80
|
+
| `unavailable` | Day cells that cannot be picked (outside `min` / `max`, or blocked by `isDateDisabled`), alongside `item`. They are `aria-disabled` and stay focusable, so `::part(item):disabled` does not match them; style them with `::part(unavailable)` |
|
|
81
|
+
|
|
82
|
+
<!-- readme-gen:end -->
|
|
83
|
+
|
|
84
|
+
## Accessibility
|
|
85
|
+
|
|
86
|
+
- The day area is a `role="grid"` named "<Month> <Year>" (e.g. "January 2026"); the weekday header row and each week are `role="row"`, weekday names are `role="columnheader"`.
|
|
87
|
+
- Every day is a native `<button role="gridcell">` whose `aria-label` is the full long date in `locale` ("Friday, January 16, 2026"), with `aria-selected` for the selected day and `aria-current="date"` on today. Days outside `min`/`max` or rejected by `isDateDisabled` are `aria-disabled="true"`, not natively disabled: they stay focusable so the arrow keys can land on them (rather than getting stuck in front of one), and Enter, Space and click do nothing there. When the host is `disabled`, every day button is also natively disabled, so the grid leaves the tab order.
|
|
88
|
+
- The navigation buttons are labelled "Previous month" / "Next month".
|
|
89
|
+
- Roving tabindex: 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 of the month — so Tab can always re-enter the grid, and Shift+Tab then Tab returns to the day you left. The day last interacted with keeps the Tab stop after a chevron click as long as it is still on screen as a leading/trailing cell.
|
|
90
|
+
- The key map is shared with `<lof-date-picker>` and `<lof-range-picker>` (`dayGridTarget` in `lof-date-picker/period-page.ts`). Keys move by date, so crossing a month edge lands on the right day (Sun 27 Sep + ArrowDown → Sun 4 Oct) and the view follows.
|
|
91
|
+
- After every month or year change (buttons, PageUp/PageDown, or arrowing past the edge of the month) the new "<Month> <Year>" is read to screen readers through the shared `announce()` live region (`utils/announce.ts`).
|
|
92
|
+
|
|
93
|
+
| Key | Action |
|
|
94
|
+
| --- | --- |
|
|
95
|
+
| ArrowLeft / ArrowRight | Focus the previous / next day (crossing into the adjacent month switches the view) |
|
|
96
|
+
| ArrowUp / ArrowDown | Focus the same weekday one week earlier / later |
|
|
97
|
+
| Home / End | Focus the first / last day of the week (honours `week-start`; may cross into the adjacent month) |
|
|
98
|
+
| PageUp / PageDown | Focus the same day in the previous / next month, clamped to that month's last day (31 Jan → 28 Feb) |
|
|
99
|
+
| Shift + PageUp / Shift + PageDown | Focus the same day in the previous / next year (29 Feb → 28 Feb) |
|
|
100
|
+
| Enter / Space | Select the focused day (fires `lof-change`); does nothing on an unavailable day |
|
|
101
|
+
|
|
102
|
+
## Notes / Edge Cases
|
|
103
|
+
|
|
104
|
+
- `value`, `min` and `max` must be `YYYY-MM-DD`; any other string is ignored (no selection, view unchanged). Setting `value` moves the visible month; clearing it to `null` leaves the view where it is.
|
|
105
|
+
- The grid always renders six weeks (42 cells). The leading/trailing cells belong to the adjacent months and, unlike in `lof-date-picker`, they are selectable (subject to `min`/`max`/`isDateDisabled`); picking one fires `lof-change`, the view jumps to that month and focus moves with the picked day.
|
|
106
|
+
- Comparisons happen at local midnight: the `Date` passed to `isDateDisabled` and returned in `lof-change` is `new Date(y, m, d)`, so read it with local getters, not `toISOString()`.
|
|
107
|
+
- `disabled` makes every day fail the disabled check and natively disables every day button and both navigation buttons, so nothing in the calendar is in the tab order; pointer events stay on the host so the `not-allowed` cursor shows.
|
|
108
|
+
- Each cell follows Figma ".Date Days": a 36 px full-rounded halo around a 28 px disc. The halo carries hover (`action/overlay/hover`), the focus ring and the selected day's `elevated-1` backing; the disc carries today's 1 px brand ring and the selected day's `inverse-2` fill with an inverse semibold label.
|
|
109
|
+
- Figma treats the cell tone as one axis, so exactly one applies per day: today beats weekend beats adjacent-month. Adjacent-month and weekend labels use the caption colour (`--lof-text-caption`; changed in 1.5.0, they used to fade to 40% / 70% opacity) — on the label only, so a *selected* weekend or adjacent-month day still reads at full contrast on the dark disc. A disabled day switches to the disabled text colour, with no extra fade when it is also a weekend or adjacent-month day (changed in 1.5.0; those used to fade further), and today keeps its brand ring even when it is unavailable or the calendar is disabled (changed in 1.5.0; it used to switch to a neutral ring).
|
|
110
|
+
- The month-navigation buttons are hand-rolled ghost buttons that bind the same action tokens as `<lof-button variant="ghost">` (audit 8b) — they are intentionally not `<lof-button>` instances.
|
|
111
|
+
- The host has a fixed `max-width: 320px`, its own radius, shadow and padding and no border (Figma draws the card with `shadow/xl`, approximated here by `--lof-shadows-shadow-400`, the nearest shipped step); wrap it or override on the host if you need a different footprint.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# lof-card
|
|
2
|
+
|
|
3
|
+
`<lof-card>` is an elevated, padded surface that groups related content — the Figma "Card" component. `type="custom"` (the default) pads whatever you slot in and applies the Figma card typography to slotted headings and paragraphs; `type="media"` adds a flush media region above the body, meant for a `<lof-card-media>` image header. Use it for dashboard tiles, summary blocks and list items that pair a title with body copy. It is a static container with no interaction of its own — for transient content use `lof-modal` or `lof-drawer` instead, and for a surface with its own tone/elevation variants use `lof-container`.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Default type: padded body -->
|
|
9
|
+
<lof-card>
|
|
10
|
+
<h3>Project 4821</h3>
|
|
11
|
+
<p>Kicked off in Dallas · Due Thursday 14:00</p>
|
|
12
|
+
</lof-card>
|
|
13
|
+
|
|
14
|
+
<!-- Media type: flush image header via <lof-card-media> in the "media" slot -->
|
|
15
|
+
<lof-card type="media">
|
|
16
|
+
<lof-card-media slot="media" image-src="/img/warehouse.jpg" image-alt="Office floor"></lof-card-media>
|
|
17
|
+
<h3>Dallas office</h3>
|
|
18
|
+
<p>12 meeting rooms · 24/7 operations</p>
|
|
19
|
+
</lof-card>
|
|
20
|
+
|
|
21
|
+
<!-- Cards in a grid -->
|
|
22
|
+
<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px;">
|
|
23
|
+
<lof-card><h4>On time</h4><p>98.2%</p></lof-card>
|
|
24
|
+
<lof-card><h4>Damage-free</h4><p>99.7%</p></lof-card>
|
|
25
|
+
<lof-card><h4>Claims</h4><p>3 open</p></lof-card>
|
|
26
|
+
</div>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
<!-- readme-gen:start -->
|
|
30
|
+
|
|
31
|
+
<!-- Generated from lof-card.ts — do not edit; run readme-generate.mjs -->
|
|
32
|
+
|
|
33
|
+
## API
|
|
34
|
+
|
|
35
|
+
### Attributes / Properties
|
|
36
|
+
|
|
37
|
+
| Property | Attribute | Type | Default | Description |
|
|
38
|
+
| --- | --- | --- | --- | --- |
|
|
39
|
+
| `type` | `type` | `"custom" \| "media"` | `"custom"` | Figma "Type" axis: custom (default) renders slotted content with card padding; media adds a flush media region (slot name="media") above the content — pair it with <lof-card-media>. Reflected. |
|
|
40
|
+
|
|
41
|
+
## Events
|
|
42
|
+
|
|
43
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
44
|
+
| --- | --- | --- | --- |
|
|
45
|
+
| — | — | — | This element emits no custom events. |
|
|
46
|
+
|
|
47
|
+
## Slots
|
|
48
|
+
|
|
49
|
+
| Slot | Description |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| (default) | Card body; slotted headings and paragraphs receive the Figma card typography |
|
|
52
|
+
| `media` | Flush media region above the body; rendered only when `type="media"` |
|
|
53
|
+
|
|
54
|
+
## CSS Parts
|
|
55
|
+
|
|
56
|
+
| Part | Description |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| `base` | The outer elevated card surface |
|
|
59
|
+
| `header` | The media region wrapper (present only when `type="media"`) |
|
|
60
|
+
| `content` | The padded body that wraps the default slot |
|
|
61
|
+
|
|
62
|
+
<!-- readme-gen:end -->
|
|
63
|
+
|
|
64
|
+
## Accessibility
|
|
65
|
+
|
|
66
|
+
- The card sets no ARIA role — it is a generic container (`display: block`), so the accessible structure comes entirely from the slotted content. Use real headings (`<h2>`–`<h4>`) and paragraphs inside it; they also pick up the card typography.
|
|
67
|
+
- The host is not focusable and has no keyboard handling. Interactive children (links, `lof-button`) keep their own focus order and must be keyboard-reachable on their own.
|
|
68
|
+
- A `<lof-card-media>` in the `media` slot carries the image's alt text via its `image-alt` attribute; leave it empty only for purely decorative imagery.
|
|
69
|
+
|
|
70
|
+
## Notes / Edge Cases
|
|
71
|
+
|
|
72
|
+
- `type="media"` removes the card's own padding and clips overflow so the media sits flush against the rounded border; the body (`content` part) keeps the standard padding. Content placed in the `media` slot without `type="media"` is not rendered, because the slot only exists in that mode.
|
|
73
|
+
- The `header` part exists only while `type="media"`; `::part(header)` matches nothing otherwise.
|
|
74
|
+
- Slotted `h1`–`h4` and `p` elements get the Figma card roles (heading md / body lg) with their default margins reset; wrap other content in your own elements to style it.
|
|
75
|
+
- The card is elevated with Figma's `shadow/sm` and draws no border, in both light and dark themes. There is no hover lift or transition.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# lof-card-media
|
|
2
|
+
|
|
3
|
+
Media card (element `<lof-card-media>`, folder `lof-cardmedia`): a bordered surface with an optional full-width image on top, then a title (`<h3>`), a subtitle and a slotted body inside a padded content area. Use it for previews that lead with an image — articles, products, gallery tiles. Use `lof-card` when you need a free-form layout or no image section.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Image, title, subtitle -->
|
|
9
|
+
<lof-card-media
|
|
10
|
+
image-src="/images/lake.jpg"
|
|
11
|
+
image-alt="A mountain lake at sunrise"
|
|
12
|
+
title="Alpine lakes"
|
|
13
|
+
subtitle="12 photos"
|
|
14
|
+
></lof-card-media>
|
|
15
|
+
|
|
16
|
+
<!-- With slotted body content -->
|
|
17
|
+
<lof-card-media
|
|
18
|
+
image-src="/images/headphones.jpg"
|
|
19
|
+
image-alt="Over-ear headphones"
|
|
20
|
+
title="Studio headphones"
|
|
21
|
+
subtitle="$99.99"
|
|
22
|
+
>
|
|
23
|
+
<p>Closed-back, 40 mm drivers, detachable cable.</p>
|
|
24
|
+
<lof-button variant="primary" tone="brand" size="small">Add to cart</lof-button>
|
|
25
|
+
</lof-card-media>
|
|
26
|
+
|
|
27
|
+
<!-- No image: just the content area -->
|
|
28
|
+
<lof-card-media title="Text-only card" subtitle="No image provided">
|
|
29
|
+
<p>Body copy goes in the default slot.</p>
|
|
30
|
+
</lof-card-media>
|
|
31
|
+
|
|
32
|
+
<!-- Gallery grid -->
|
|
33
|
+
<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px;">
|
|
34
|
+
<lof-card-media image-src="/images/1.jpg" image-alt="" title="Item 1"></lof-card-media>
|
|
35
|
+
<lof-card-media image-src="/images/2.jpg" image-alt="" title="Item 2"></lof-card-media>
|
|
36
|
+
<lof-card-media image-src="/images/3.jpg" image-alt="" title="Item 3"></lof-card-media>
|
|
37
|
+
</div>
|
|
38
|
+
|
|
39
|
+
<!-- Restyle through parts -->
|
|
40
|
+
<style>
|
|
41
|
+
.flat::part(base) {
|
|
42
|
+
border: none;
|
|
43
|
+
}
|
|
44
|
+
.flat::part(content) {
|
|
45
|
+
padding: 24px;
|
|
46
|
+
}
|
|
47
|
+
</style>
|
|
48
|
+
<lof-card-media class="flat" title="Flat card"></lof-card-media>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
<!-- readme-gen:start -->
|
|
52
|
+
|
|
53
|
+
<!-- Generated from lof-cardmedia.ts — do not edit; run readme-generate.mjs -->
|
|
54
|
+
|
|
55
|
+
## API
|
|
56
|
+
|
|
57
|
+
### Attributes / Properties
|
|
58
|
+
|
|
59
|
+
| Property | Attribute | Type | Default | Description |
|
|
60
|
+
| --- | --- | --- | --- | --- |
|
|
61
|
+
| `imageSrc` | `image-src` | `string` | `""` | URL of the hero image shown full-width at the top of the card. Empty (the default) omits the image section entirely. |
|
|
62
|
+
| `imageAlt` | `image-alt` | `string` | `"Card image"` | Alternative text for the hero image. Replace the generic default with a real description, or an empty string for purely decorative images. |
|
|
63
|
+
| `title` | `title` | `string` | `""` | Heading rendered as an `<h3>` above the subtitle; empty omits it. Note this is also the native `title` attribute, so a value shows as a browser tooltip on hover. |
|
|
64
|
+
| `subtitle` | `subtitle` | `string` | `""` | Secondary line rendered as a paragraph under the title; empty omits it. |
|
|
65
|
+
|
|
66
|
+
## Events
|
|
67
|
+
|
|
68
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
69
|
+
| --- | --- | --- | --- |
|
|
70
|
+
| — | — | — | This element emits no custom events. |
|
|
71
|
+
|
|
72
|
+
## Slots
|
|
73
|
+
|
|
74
|
+
| Slot | Description |
|
|
75
|
+
| --- | --- |
|
|
76
|
+
| (default) | Body content rendered inside the padded content area below the title and subtitle. |
|
|
77
|
+
|
|
78
|
+
## CSS Parts
|
|
79
|
+
|
|
80
|
+
| Part | Description |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| `base` | The outer bordered card surface (background, border, radius, overflow clip). |
|
|
83
|
+
| `icon` | The image wrapper above the content, rendered only when `image-src` is set. |
|
|
84
|
+
| `content` | The padded area holding the title, subtitle and slotted body. |
|
|
85
|
+
|
|
86
|
+
<!-- readme-gen:end -->
|
|
87
|
+
|
|
88
|
+
## Accessibility
|
|
89
|
+
|
|
90
|
+
- The image renders as an `<img>` whose `alt` is `image-alt`; the default "Card image" is a placeholder — supply a real description, or an empty `image-alt=""` when the picture is decorative.
|
|
91
|
+
- The title is a real `<h3>`; make sure that fits the page's heading outline (there is no way to change the level).
|
|
92
|
+
- The card itself is a non-focusable container with no keyboard handling. Slotted controls (buttons, links) keep their own focus and keyboard behaviour.
|
|
93
|
+
|
|
94
|
+
## Notes / Edge Cases
|
|
95
|
+
|
|
96
|
+
- **Attribute spellings are kebab-case**: `image-src` and `image-alt`. Setting `imageSrc="…"` as an HTML attribute does nothing; use the property in code (`el.imageSrc = …`).
|
|
97
|
+
- **`title` is also the native tooltip attribute.** Because the property maps to the global `title` attribute, hovering the card shows the title text as a browser tooltip.
|
|
98
|
+
- The image section (`icon` part) is omitted entirely when `image-src` is empty; the title and subtitle are likewise omitted when empty, so the content area may hold only slotted children.
|
|
99
|
+
- The image is `width: 100%; height: auto; object-fit: cover` and the card clips overflow, so the top corners follow the card radius.
|
|
100
|
+
- The card is static: no hover lift, shadow or transition is applied.
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# lof-carousel
|
|
2
|
+
|
|
3
|
+
A slide carousel implementing the Figma "Carousel" component and its three axes — `Type` (Default, Only Indicators, Side Arrows, Bottom Arrows), `Orientation` (Horizontal, Vertical) and `Multi Panels` — plus the `Show Dots` property. It shows one or more slotted slides at a time in a horizontal or vertical viewport and moves between them with arrows, dot indicators, pointer drag / swipe, the keyboard, or autoplay. Use it for a small, ordered set of equally important panels (hero images, onboarding cards, testimonials); do not use it as a substitute for tabs or for content the user must read in full — hidden slides are not reachable by page search or by screen readers until they are shown.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- Default type: slides only — swipe, drag or use the arrow keys -->
|
|
9
|
+
<lof-carousel label="Product photos">
|
|
10
|
+
<img src="/photos/front.jpg" alt="Front view">
|
|
11
|
+
<img src="/photos/side.jpg" alt="Side view">
|
|
12
|
+
<img src="/photos/back.jpg" alt="Back view">
|
|
13
|
+
</lof-carousel>
|
|
14
|
+
|
|
15
|
+
<!-- Figma Type axis: overlaid arrows + dots -->
|
|
16
|
+
<lof-carousel type="side-arrows" label="Highlights">
|
|
17
|
+
<div><h3>Fast setup</h3><p>Up and running in minutes.</p></div>
|
|
18
|
+
<div><h3>Secure by default</h3><p>Encrypted at rest and in transit.</p></div>
|
|
19
|
+
<div><h3>Works everywhere</h3><p>One component, every framework.</p></div>
|
|
20
|
+
</lof-carousel>
|
|
21
|
+
|
|
22
|
+
<!-- Dots flanked by arrows under the slide -->
|
|
23
|
+
<lof-carousel type="bottom-arrows" label="Testimonials">
|
|
24
|
+
<blockquote>"Saved us a week." — Ada</blockquote>
|
|
25
|
+
<blockquote>"Zero regressions." — Grace</blockquote>
|
|
26
|
+
</lof-carousel>
|
|
27
|
+
|
|
28
|
+
<!-- Dots only -->
|
|
29
|
+
<lof-carousel type="only-indicators" label="Tips">
|
|
30
|
+
<p>Tip 1</p>
|
|
31
|
+
<p>Tip 2</p>
|
|
32
|
+
<p>Tip 3</p>
|
|
33
|
+
</lof-carousel>
|
|
34
|
+
|
|
35
|
+
<!-- Arrows on their own: show-dots="false" suppresses the dots the type implies -->
|
|
36
|
+
<lof-carousel type="side-arrows" show-dots="false" label="Highlights">
|
|
37
|
+
<div>Fast setup</div>
|
|
38
|
+
<div>Secure by default</div>
|
|
39
|
+
</lof-carousel>
|
|
40
|
+
|
|
41
|
+
<!-- Loop and autoplay (3 s), 16px between slides, start on the second slide -->
|
|
42
|
+
<lof-carousel type="side-arrows" loop autoplay interval="3000" gap="16" value="1" label="Promotions">
|
|
43
|
+
<div>Spring sale</div>
|
|
44
|
+
<div>Free shipping</div>
|
|
45
|
+
<div>New arrivals</div>
|
|
46
|
+
</lof-carousel>
|
|
47
|
+
|
|
48
|
+
<!-- Figma Multi Panels: 1.5 panels leaves the next slide peeking in -->
|
|
49
|
+
<lof-carousel type="side-arrows" panels="1.5" label="Related products">
|
|
50
|
+
<div>Product A</div>
|
|
51
|
+
<div>Product B</div>
|
|
52
|
+
<div>Product C</div>
|
|
53
|
+
<div>Product D</div>
|
|
54
|
+
</lof-carousel>
|
|
55
|
+
|
|
56
|
+
<!-- Two whole panels at a time, no peek -->
|
|
57
|
+
<lof-carousel type="only-indicators" panels="2" label="Case studies">
|
|
58
|
+
<div>Case A</div>
|
|
59
|
+
<div>Case B</div>
|
|
60
|
+
<div>Case C</div>
|
|
61
|
+
<div>Case D</div>
|
|
62
|
+
</lof-carousel>
|
|
63
|
+
|
|
64
|
+
<!-- Vertical: the viewport height comes from --lof-carousel-height -->
|
|
65
|
+
<lof-carousel orientation="vertical" type="side-arrows" label="Timeline" style="--lof-carousel-height: 240px">
|
|
66
|
+
<div>2024</div>
|
|
67
|
+
<div>2025</div>
|
|
68
|
+
<div>2026</div>
|
|
69
|
+
</lof-carousel>
|
|
70
|
+
|
|
71
|
+
<!-- Programmatic control -->
|
|
72
|
+
<lof-carousel id="gallery" type="bottom-arrows" label="Gallery">
|
|
73
|
+
<div>A</div>
|
|
74
|
+
<div>B</div>
|
|
75
|
+
<div>C</div>
|
|
76
|
+
</lof-carousel>
|
|
77
|
+
<script>
|
|
78
|
+
const gallery = document.getElementById('gallery');
|
|
79
|
+
gallery.value = 2; // jump to the third slide
|
|
80
|
+
gallery.pauseOnHover = false; // default-true booleans are switched off via the property
|
|
81
|
+
gallery.addEventListener('lof-change', (e) => {
|
|
82
|
+
console.log('Current slide:', e.detail.value);
|
|
83
|
+
});
|
|
84
|
+
</script>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
<!-- readme-gen:start -->
|
|
88
|
+
|
|
89
|
+
<!-- Generated from lof-carousel.ts — do not edit; run readme-generate.mjs -->
|
|
90
|
+
|
|
91
|
+
## API
|
|
92
|
+
|
|
93
|
+
### Attributes / Properties
|
|
94
|
+
|
|
95
|
+
| Property | Attribute | Type | Default | Description |
|
|
96
|
+
| --- | --- | --- | --- | --- |
|
|
97
|
+
| `value` | `value` | `number` | `0` | Index of the current slide (0-based). Set it to jump; it is clamped to the slide count and reflected as an attribute. Reflected. |
|
|
98
|
+
| `loop` | `loop` | `boolean` | `false` | Wrap from the last slide to the first (and back) with a seamless clone transition instead of stopping at the ends. |
|
|
99
|
+
| `autoplay` | `autoplay` | `boolean` | `false` | Advance automatically every `interval` ms; implies looping and pauses while hovered (see `pause-on-hover`) or while focus is inside the carousel. |
|
|
100
|
+
| `interval` | `interval` | `number` | `5000` | Autoplay delay between slides, in milliseconds (default 5000). |
|
|
101
|
+
| `pauseOnHover` | `pause-on-hover` | `boolean` | `true` | Pause autoplay while the pointer is over the carousel or while dragging (default true; switch off with `pause-on-hover="false"` or `el.pauseOnHover = false`). |
|
|
102
|
+
| `showButtons` | `show-buttons` | `boolean` | `false` | Legacy toggle for the overlaid previous / next arrows; ignored whenever `type` is set. |
|
|
103
|
+
| `showDots` | `show-dots` | `boolean` | `undefined` | Figma "Show Dots" property. Tri-state: left off it defers to `type` (dots for every type except `default`, and nothing at all when `type` is unset too); `show-dots` turns them on; `show-dots="false"` turns them off even when `type` would have shown them. |
|
|
104
|
+
| `type` | `type` | `"default" \| "only-indicators" \| "side-arrows" \| "bottom-arrows"` | `undefined` | Figma "Type" axis. When set it drives which controls render: default = content only · only-indicators = dots · side-arrows = overlaid arrows + dots · bottom-arrows = dots flanked by arrows below the slide. When unset, the legacy show-buttons boolean applies unchanged. The dots a type implies can always be overridden by an explicit `show-dots`. Reflected. |
|
|
105
|
+
| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Slide axis: `horizontal` (default) translates the track left / right; `vertical` stacks slides in a fixed-height viewport (`--lof-carousel-height`) and translates up / down. Reflected. |
|
|
106
|
+
| `label` | `label` | `string` | `"Carousel"` | Accessible name of the carousel region (`aria-label` on the viewport); default "Carousel". |
|
|
107
|
+
| `gap` | `gap` | `number` | `8` | Space between consecutive slides in pixels (applied as the track `gap` and added to each slide step); default 8 (Figma `spacing/xs`), 0 = slides touch. |
|
|
108
|
+
| `panels` | `panels` | `number` | `1` | Figma "Multi Panels" axis, as a count: how many slides are visible at once (default 1). Fractions are allowed and produce a peek of the next slide — `panels="1.5"` reproduces the Figma Multi Panels=True variant. Navigation still advances one slide at a time. |
|
|
109
|
+
| `disabled` | `disabled` | `boolean` | `false` | Disables arrows, dots, drag and keyboard navigation, stops autoplay and renders the carousel at 60% opacity. Reflected. |
|
|
110
|
+
|
|
111
|
+
## Events
|
|
112
|
+
|
|
113
|
+
| Event | Detail | Bubbles / composed | Description |
|
|
114
|
+
| --- | --- | --- | --- |
|
|
115
|
+
| `lof-change` | `{ value: this.value }` | bubbles / composed | Fired whenever the current slide changes (arrows, dots, drag, keyboard, autoplay or a loop wrap). Detail: `{ value: number }` — the new 0-based slide index. |
|
|
116
|
+
|
|
117
|
+
## Slots
|
|
118
|
+
|
|
119
|
+
| Slot | Description |
|
|
120
|
+
| --- | --- |
|
|
121
|
+
| (default) | The slides: one light-DOM element per slide (each is sized to one panel and given `role="group"` / `aria-roledescription="slide"`). |
|
|
122
|
+
|
|
123
|
+
## CSS Parts
|
|
124
|
+
|
|
125
|
+
| Part | Description |
|
|
126
|
+
| --- | --- |
|
|
127
|
+
| `${direction}-button` | The two arrow buttons, exposed as `prev-button` and `next-button` (`type="side-arrows"` overlays them on the viewport; `type="bottom-arrows"` inlines them in the dots row). |
|
|
128
|
+
| `viewport` | The focusable `role="region"` box that clips the track (also the keyboard target). |
|
|
129
|
+
| `track` | The flex row / column that translates to reveal the current slide. |
|
|
130
|
+
| `dots` | The indicator row under the viewport (also hosts the arrows for `type="bottom-arrows"`). |
|
|
131
|
+
| `dot-group` | The row of dots inside `dots` (for `type="bottom-arrows"` it is the middle child, between the two arrows). |
|
|
132
|
+
| `dot` | One indicator button per reachable position (per slide at `panels="1"`); the active one carries the `active` class and `aria-current="true"`. Since 1.5.0 the button is a transparent target cell of at least 24 × 24px and the visible dot is its `::before` (style it with `::part(dot)::before`). |
|
|
133
|
+
|
|
134
|
+
## Tokens / CSS Variables
|
|
135
|
+
|
|
136
|
+
### Component hooks
|
|
137
|
+
|
|
138
|
+
Set these on the host (or an ancestor) to customise the element without touching design tokens.
|
|
139
|
+
|
|
140
|
+
| Custom property | Default | Description |
|
|
141
|
+
| --- | --- | --- |
|
|
142
|
+
| `--lof-carousel-dot-size` | `8px` | Diameter of an inactive dot (default 8px); its target cell is at least 24px. |
|
|
143
|
+
| `--lof-carousel-dot-size-active` | `16px` | Width of the active (brand-coloured, pill-shaped) dot (default 16px); its target cell is at least 24px. |
|
|
144
|
+
| `--lof-carousel-height` | `320px` | Viewport height in `orientation="vertical"` (default 320px); the horizontal viewport takes the height of its tallest slide. |
|
|
145
|
+
| `--lof-carousel-nav-size` | `32px` | Width / height of the arrow buttons (default 32px, matching Figma; applies to both side and bottom arrows). |
|
|
146
|
+
| `--lof-carousel-slide-bg` | `var(--lof-bg-neutral)` | — |
|
|
147
|
+
| `--lof-carousel-slide-display` | `flex` | `display` given to each slide in `orientation="vertical"` only, which is what centres the slide's content in the fixed-height viewport as Figma draws it. Set it to `block` to opt out if forcing flex reflows your slide's own children. Horizontal slides are never touched. |
|
|
148
|
+
| `--lof-carousel-slide-height` | `100%` | Written by the component on its own host to the computed panel height (used for vertical slides); not meant to be set by consumers. |
|
|
149
|
+
| `--lof-carousel-slide-radius` | `var(--lof-border-radius-sm)` | — |
|
|
150
|
+
| `--lof-carousel-slide-width` | `100%` | Written by the component on its own host to the computed panel width (viewport width for `panels="1"`, a fraction of it above that); not meant to be set by consumers (an inline value is overwritten on resize). |
|
|
151
|
+
|
|
152
|
+
<!-- readme-gen:end -->
|
|
153
|
+
|
|
154
|
+
## Accessibility
|
|
155
|
+
|
|
156
|
+
- The viewport renders with `role="region"`, `aria-roledescription="carousel"` and `aria-label` set from the `label` prop (default "Carousel"); give every carousel a meaningful `label`.
|
|
157
|
+
- Each slotted slide is decorated with `role="group"`, `aria-roledescription="slide"` and `aria-label="n of N"`; the clone slides used for looping are `aria-hidden="true"`.
|
|
158
|
+
- The arrow buttons are labelled "Previous slide" / "Next slide" and their chevrons are `aria-hidden`; each dot is labelled "Go to slide n" and the active dot carries `aria-current="true"`.
|
|
159
|
+
- The viewport is a single Tab stop (`tabindex="0"`); the arrows and dots that are rendered are ordinary buttons and follow it in the Tab order.
|
|
160
|
+
- Every user-initiated slide change is announced through the shared live region as "Slide n of N"; autoplay ticks are deliberately silent.
|
|
161
|
+
- Autoplay pauses while the pointer is over the carousel (`pause-on-hover`, default on) and while keyboard focus is anywhere inside it (WCAG 2.2.2 Pause, Stop, Hide); it resumes when focus leaves.
|
|
162
|
+
- Track transitions are disabled under `prefers-reduced-motion: reduce`; drag still snaps to the nearest slide, just without animation.
|
|
163
|
+
|
|
164
|
+
| Key | Action |
|
|
165
|
+
| --- | --- |
|
|
166
|
+
| `ArrowLeft` / `ArrowUp` | Previous slide (wraps when `loop` or `autoplay` is set) |
|
|
167
|
+
| `ArrowRight` / `ArrowDown` | Next slide (wraps when `loop` or `autoplay` is set) |
|
|
168
|
+
| `Home` | First slide |
|
|
169
|
+
| `End` | Last slide |
|
|
170
|
+
| `Tab` | Move between the viewport, the arrows and the dots |
|
|
171
|
+
|
|
172
|
+
Keys are handled on the viewport (and anything focused inside it) and are ignored while `disabled`.
|
|
173
|
+
|
|
174
|
+
## Notes / Edge Cases
|
|
175
|
+
|
|
176
|
+
- `type` is the canonical control switch. When it is unset the legacy `show-buttons` boolean still decides whether arrows render; when it is set `show-buttons` is ignored (`type="default"` hides the arrows).
|
|
177
|
+
- `show-dots` is deliberately tri-state, because Figma's `Show Dots` is a property rather than part of the `Type` axis. Omit it and `type` decides, exactly as before; write `show-dots` to force the dots on; write `show-dots="false"` to force them off even for a `type` that would have shown them. Omitting it is what every pre-existing carousel does, so none of them change.
|
|
178
|
+
- `panels` implements the Figma `Multi Panels` axis. Each panel measures `(viewport − gap × (ceil(panels) − 1)) / panels` along the scroll axis — a viewport showing `n` panels contains `ceil(n) − 1` whole gaps, so at the Figma frame width of 350px with the default 8px gap, `panels="1.5"` yields exactly the 228px slide the design specifies.
|
|
179
|
+
- Navigation always advances one slide per step, never one page. Without `loop`, the track stops once the last slide is flush with the trailing edge instead of scrolling into empty space, so at `panels="1.5"` with three slides the reachable indices are `0` and `1`. The dot row follows that: one dot per reachable position, which is one per slide at `panels="1"` and whenever `loop` is on.
|
|
180
|
+
- Slides are sized by the component: every slotted element gets `width: var(--lof-carousel-slide-width)` (or the height equivalent in `orientation="vertical"`) with `!important`, where the variable is written on the host to the computed panel size. Style the inside of a slide freely, but do not rely on a slide's own `width` / `height`.
|
|
181
|
+
- `loop` and `autoplay` clone the edge slides into the shadow DOM so the wrap looks continuous — `ceil(panels)` of them at each end, since a viewport showing more than one panel would otherwise run out of slides mid-transition. `lof-change` still reports the real index (`0` … `N-1`) after the silent jump.
|
|
182
|
+
- Drag / swipe uses a 20% threshold of the panel size; shorter drags snap back. Dragging pauses autoplay (when `pause-on-hover` is on) and resumes it on release.
|
|
183
|
+
- `value` is clamped to the highest reachable index whenever the slot content changes; setting it out of range moves to the nearest valid slide.
|
|
184
|
+
- Arrows are 32px circles with a 16px chevron, matching Figma. Side arrows (`type="side-arrows"`) overlay the viewport at the vertical centre, inset 8px from the edge; bottom arrows (`type="bottom-arrows"`) sit inside the indicator row, 20px from the dots. Both are hand-rolled ghost-style buttons, not `<lof-button>`, and both are sized by `--lof-carousel-nav-size`. Per the published Figma set the arrows stay on the left and right edges in `orientation="vertical"` too.
|
|
185
|
+
- The active dot is a 16 × 8 fully-rounded brand pill and an inactive dot an 8px circle; `--lof-carousel-dot-size-active` and `--lof-carousel-dot-size` override them. Since 1.5.0 each dot sits in a target cell of at least 24 × 24px (WCAG 2.5.8 target size), so the indicator row is 24px tall (it was 8px). The cells touch, with no gap between them, so the visible dots sit 16px apart (three dots make a 72px row). The cell is transparent: `::part(dot)` styles the cell (and carries the focus ring), `::part(dot)::before` the visible dot. Also since 1.5.0, an inactive dot is filled with `--lof-bg-neutral-elevated-3` (it was `--lof-bg-neutral-elevated-2`), and the active pill keeps `--lof-bg-surface-brand` with a 1px inside edge in `--lof-text-default`. In forced-colours mode the dots paint in system colours (inactive `CanvasText`, active `Highlight` with a `CanvasText` edge) instead of disappearing.
|
|
186
|
+
- The horizontal viewport takes the height of its tallest slide; the vertical viewport is a fixed `--lof-carousel-height` (320px) — set it to fit your content.
|
|
187
|
+
- Arrow buttons are exposed as `::part(prev-button)` and `::part(next-button)`; the indicator row is `::part(dots)`, the dots inside it `::part(dot-group)` and `::part(dot)`.
|