@f-ewald/components 1.28.0 → 1.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +4 -0
  2. package/custom-elements.json +1817 -84
  3. package/dist/countdown-timer.d.ts +31 -0
  4. package/dist/countdown-timer.d.ts.map +1 -0
  5. package/dist/countdown-timer.js +74 -0
  6. package/dist/countdown-timer.js.map +1 -0
  7. package/dist/cron-schedule.d.ts +55 -0
  8. package/dist/cron-schedule.d.ts.map +1 -0
  9. package/dist/cron-schedule.js +768 -0
  10. package/dist/cron-schedule.js.map +1 -0
  11. package/dist/fullscreen-button.d.ts +43 -0
  12. package/dist/fullscreen-button.d.ts.map +1 -0
  13. package/dist/fullscreen-button.js +172 -0
  14. package/dist/fullscreen-button.js.map +1 -0
  15. package/dist/index.d.ts +6 -1
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +5 -0
  18. package/dist/index.js.map +1 -1
  19. package/dist/scroll-dots.d.ts +54 -0
  20. package/dist/scroll-dots.d.ts.map +1 -0
  21. package/dist/scroll-dots.js +178 -0
  22. package/dist/scroll-dots.js.map +1 -0
  23. package/dist/timeline-container.d.ts +21 -5
  24. package/dist/timeline-container.d.ts.map +1 -1
  25. package/dist/timeline-container.js +35 -7
  26. package/dist/timeline-container.js.map +1 -1
  27. package/dist/timeline-entry.d.ts +32 -0
  28. package/dist/timeline-entry.d.ts.map +1 -1
  29. package/dist/timeline-entry.js +130 -3
  30. package/dist/timeline-entry.js.map +1 -1
  31. package/dist/utils/cron.d.ts +83 -0
  32. package/dist/utils/cron.d.ts.map +1 -0
  33. package/dist/utils/cron.js +409 -0
  34. package/dist/utils/cron.js.map +1 -0
  35. package/docs/countdown-timer.md +40 -0
  36. package/docs/cron-schedule.md +82 -0
  37. package/docs/fullscreen-button.md +70 -0
  38. package/docs/scroll-dots.md +65 -0
  39. package/docs/timeline-container.md +30 -6
  40. package/docs/timeline-entry.md +18 -0
  41. package/llms.txt +171 -8
  42. package/package.json +1 -1
@@ -0,0 +1,40 @@
1
+ # `<countdown-timer>`
2
+
3
+ Per-second ticking count-down timer, e.g. a live "Retrying in 3 seconds"
4
+ indicator while waiting to retry a failed request. Renders nothing while
5
+ `until` is unset or unparseable. Remaining time is clamped to zero — it
6
+ never goes negative once the target instant has passed.
7
+
8
+ ## Install
9
+
10
+ ```js
11
+ import "@f-ewald/components/countdown-timer.js";
12
+ ```
13
+
14
+ ## Usage
15
+
16
+ ```html
17
+ <countdown-timer until="2026-07-19T12:00:10Z" prefix="Retrying in "></countdown-timer>
18
+ <countdown-timer until="2026-07-19T12:00:10Z" format="compact" prefix="retrying in "></countdown-timer>
19
+ ```
20
+
21
+ ## Attributes / properties
22
+
23
+ | Property | Attribute | Type | Default | Description |
24
+ | --- | --- | --- | --- | --- |
25
+ | `until` | `until` | `string | null` | `null` | ISO-8601 target instant; remaining time is measured until here. |
26
+ | `format` | `format` | `DurationFormat` | `"seconds"` | `"seconds"` -> "1 second", "12 seconds"; `"compact"` -> "12s", "3m 12s", "1h 03m 12s". |
27
+ | `prefix` | `prefix` | `string` | `""` | Text rendered before the formatted value. |
28
+ | `suffix` | `suffix` | `string` | `""` | Text rendered after the formatted value. |
29
+
30
+ ## Events
31
+
32
+ _None._
33
+
34
+ ## Slots
35
+
36
+ _None._
37
+
38
+ ## CSS custom properties
39
+
40
+ _None._
@@ -0,0 +1,82 @@
1
+ # `<cron-schedule>`
2
+
3
+ Repeat-schedule picker that reads and writes a standard 5-field cron
4
+ expression. The collapsed trigger shows a compact English description of
5
+ the current schedule ("Every hour", "10:17 every Monday"); clicking it
6
+ opens an anchored panel with the schedule form.
7
+
8
+ The panel offers frequency presets (every N minutes, hourly, daily, weekly,
9
+ monthly, yearly) plus an `Advanced` mode that edits each cron field as a
10
+ list of terms, so any valid expression — including compound fields that mix
11
+ ranges, steps, and single values — is reachable. Edits apply immediately:
12
+ each change updates `value` and fires `change`; closing the panel only
13
+ dismisses it.
14
+
15
+ An unparseable `value` (e.g. `@reboot`, which has no five-field form) is
16
+ preserved verbatim and shown as-is on the trigger; the panel then starts
17
+ from the default hourly schedule.
18
+
19
+ The host is `display: block` with a full-width trigger, matching the other
20
+ value-entry fields. To shrink an instance to its content, constrain the
21
+ host: `cron-schedule { display: inline-block; }`.
22
+
23
+ ## Install
24
+
25
+ ```js
26
+ import "@f-ewald/components/cron-schedule.js";
27
+ ```
28
+
29
+ ## Usage
30
+
31
+ ```html
32
+ <cron-schedule label="Backup schedule" value="0 * * * *"></cron-schedule>
33
+
34
+ <script type="module">
35
+ const schedule = document.querySelector("cron-schedule");
36
+ schedule.addEventListener("change", (e) => {
37
+ console.log(e.detail.value, schedule.description);
38
+ });
39
+ </script>
40
+ ```
41
+
42
+ ## Attributes / properties
43
+
44
+ | Property | Attribute | Type | Default | Description |
45
+ | --- | --- | --- | --- | --- |
46
+ | `value` | `value` | `string` | `"0 * * * *"` | The cron expression, e.g. `"0 * * * *"`. |
47
+ | `label` | `label` | `string` | `""` | Accessible label for the trigger. |
48
+ | `disabled` | `disabled` | `boolean` | `false` | Whether the picker is disabled. |
49
+ | `open` | `open` | `boolean` | `false` | Whether the schedule panel is open. |
50
+ | `description` | _(JS property only)_ | `string` | `—` | The compact English description of the current expression. _(read-only)_ |
51
+
52
+ ## Events
53
+
54
+ | Event | Description |
55
+ | --- | --- |
56
+ | `change` | Fired with `{ value: string }` whenever the expression changes. |
57
+
58
+ ## Slots
59
+
60
+ _None._
61
+
62
+ ## CSS custom properties
63
+
64
+ | Custom property |
65
+ | --- |
66
+ | `--ui-border` |
67
+ | `--ui-focus-ring` |
68
+ | `--ui-font` |
69
+ | `--ui-font-mono` |
70
+ | `--ui-font-size-sm` |
71
+ | `--ui-font-size-xs` |
72
+ | `--ui-font-weight-medium` |
73
+ | `--ui-line-height-tight` |
74
+ | `--ui-primary` |
75
+ | `--ui-radius` |
76
+ | `--ui-radius-sm` |
77
+ | `--ui-shadow-lg` |
78
+ | `--ui-surface` |
79
+ | `--ui-surface-muted` |
80
+ | `--ui-text` |
81
+ | `--ui-text-muted` |
82
+ | `--ui-tracking-wide` |
@@ -0,0 +1,70 @@
1
+ # `<fullscreen-button>`
2
+
3
+ Toggles fullscreen presentation of the page, or of a given `target` element.
4
+
5
+ The icon and accessible name track the *actual* fullscreen state rather than
6
+ this button's own clicks, because fullscreen can be left without touching it
7
+ — Escape, or the browser's own chrome — which would otherwise leave the
8
+ button showing the wrong affordance.
9
+
10
+ The control is styled as a square icon-sized `ui-button` `secondary` variant
11
+ (2rem, `--ui-radius-sm` corners, the `--ui-button-secondary-*` background and
12
+ border tokens, so a gradient theme carries over) layered over an opaque
13
+ `--ui-surface` base and an elevation shadow, since it normally floats above
14
+ the content it expands.
15
+
16
+ ## Install
17
+
18
+ ```js
19
+ import "@f-ewald/components/fullscreen-button.js";
20
+ ```
21
+
22
+ ## Usage
23
+
24
+ ```html
25
+ <fullscreen-button></fullscreen-button>
26
+ <script type="module">
27
+ const button = document.querySelector('fullscreen-button');
28
+ button.target = document.querySelector('#deck'); // omit for the whole page
29
+ button.addEventListener('fullscreen-change', (e) => console.log(e.detail.active));
30
+ </script>
31
+ ```
32
+
33
+ ## Attributes / properties
34
+
35
+ | Property | Attribute | Type | Default | Description |
36
+ | --- | --- | --- | --- | --- |
37
+ | `target` | _(JS property only)_ | `HTMLElement | null` | `null` | Element to present fullscreen; `null` (default) presents the whole page. |
38
+ | `enterLabel` | `enter-label` | `string` | `"Enter full screen"` | Accessible name while not fullscreen. |
39
+ | `exitLabel` | `exit-label` | `string` | `"Exit full screen"` | Accessible name while fullscreen. |
40
+
41
+ ## Events
42
+
43
+ | Event | Description |
44
+ | --- | --- |
45
+ | `fullscreen-change` | The fullscreen state changed, from this button or otherwise (`detail: { active }`). |
46
+
47
+ ## Slots
48
+
49
+ _None._
50
+
51
+ ## CSS custom properties
52
+
53
+ | Custom property |
54
+ | --- |
55
+ | `--ui-border` |
56
+ | `--ui-button-highlight` |
57
+ | `--ui-button-secondary-` |
58
+ | `--ui-button-secondary-background` |
59
+ | `--ui-button-secondary-background-active` |
60
+ | `--ui-button-secondary-background-hover` |
61
+ | `--ui-button-secondary-border` |
62
+ | `--ui-button-secondary-border-hover` |
63
+ | `--ui-focus-ring` |
64
+ | `--ui-line-height-glyph` |
65
+ | `--ui-radius-sm` |
66
+ | `--ui-shadow` |
67
+ | `--ui-surface` |
68
+ | `--ui-surface-muted` |
69
+ | `--ui-text` |
70
+ | `--ui-text-muted` |
@@ -0,0 +1,65 @@
1
+ # `<scroll-dots>`
2
+
3
+ Vertical section navigator for a long scrolled page or a slide deck: one dot
4
+ per section, the active one drawn as an elongated rounded bar rather than a
5
+ dot, which is the only cue needed to read position at a glance.
6
+
7
+ Controlled, like `pagination-nav`: it owns no scroll behavior and never
8
+ reads the scroll position. The consumer sets `active` and moves the page in
9
+ response to `dot-select` — what counts as the active section differs too much
10
+ between a snapped deck and an ordinary long page to bake in.
11
+
12
+ Positioning is also the consumer's, since a rail is normally fixed into a
13
+ reserved gutter that only the page knows the width of.
14
+
15
+ The dots use the same lighter-on-top gradient as `map-circle`/`map-pin`,
16
+ derived from a single base `color` — a rail beside a map reads as the same
17
+ family of marks as the pins on it.
18
+
19
+ ## Install
20
+
21
+ ```js
22
+ import "@f-ewald/components/scroll-dots.js";
23
+ ```
24
+
25
+ ## Usage
26
+
27
+ ```html
28
+ <scroll-dots label="Journey stops"></scroll-dots>
29
+ <script type="module">
30
+ const rail = document.querySelector('scroll-dots');
31
+ rail.items = ['Intro', 'Freiburg', 'Berkeley', { label: 'Credits', muted: true }];
32
+ rail.active = 0;
33
+ rail.addEventListener('dot-select', (e) => {
34
+ rail.active = e.detail.index;
35
+ sections[e.detail.index].scrollIntoView({ behavior: 'smooth', block: 'start' });
36
+ });
37
+ </script>
38
+ ```
39
+
40
+ ## Attributes / properties
41
+
42
+ | Property | Attribute | Type | Default | Description |
43
+ | --- | --- | --- | --- | --- |
44
+ | `items` | _(JS property only)_ | `ScrollDotsItem[]` | `[]` | Dots to render, in document order. A bare string is shorthand for `{ label }`. |
45
+ | `active` | `active` | `number` | `0` | 0-based index of the active dot. Out-of-range values simply match no dot. |
46
+ | `color` | `color` | `string` | `""` | Base color the dot gradient is derived from. Empty uses `--ui-primary`. |
47
+ | `label` | `label` | `string` | `""` | Accessible name for the rail, e.g. "Journey stops". |
48
+
49
+ ## Events
50
+
51
+ | Event | Description |
52
+ | --- | --- |
53
+ | `dot-select` | The user picked a dot (`detail: { index }`). |
54
+
55
+ ## Slots
56
+
57
+ _None._
58
+
59
+ ## CSS custom properties
60
+
61
+ | Custom property |
62
+ | --- |
63
+ | `--ui-focus-ring` |
64
+ | `--ui-primary` |
65
+ | `--ui-text-muted` |
@@ -1,10 +1,20 @@
1
1
  # `<timeline-container>`
2
2
 
3
- Vertical timeline: a single connecting line runs down the left edge and each
4
- slotted `timeline-entry` places a dot on it. This is a thin layout and
5
- semantics wrapper — the entries draw the line segments and dots themselves,
6
- so the container adds no gap between them (a gap would break the line).
7
- Exposed to assistive technology as a list of events.
3
+ Vertical timeline: a connecting line runs down the entries and each slotted
4
+ `timeline-entry` places a dot on it. This is a thin layout and semantics
5
+ wrapper — the entries draw the line segments and dots themselves, so the
6
+ container adds no gap between them (a gap would break the line). Exposed to
7
+ assistive technology as a list of events.
8
+
9
+ `layout` chooses where the line runs. `left` (the default) puts it down the
10
+ left edge with each entry's label inline beside its headline. `alternating`
11
+ centers it and gives each entry three columns — label, line, body — with the
12
+ two sides swapping on every second entry, for a presentation timeline rather
13
+ than an event log.
14
+
15
+ The layout is pushed onto each entry rather than read from here, because a
16
+ shadow-DOM child cannot style itself against an ancestor portably —
17
+ `:host-context()` is Chromium-only.
8
18
 
9
19
  ## Install
10
20
 
@@ -29,11 +39,25 @@ import "@f-ewald/components/timeline-container.js";
29
39
  <chat-message role="user" author="Freddy">Ship it.</chat-message>
30
40
  </timeline-entry>
31
41
  </timeline-container>
42
+
43
+ <!-- A presentation timeline: centered line, label and body swapping sides. -->
44
+ <timeline-container layout="alternating">
45
+ <timeline-entry label="1987">
46
+ <span slot="headline">Where it started</span>
47
+ A first stop, with the label on the left.
48
+ </timeline-entry>
49
+ <timeline-entry label="2004">
50
+ <span slot="headline">The question</span>
51
+ The second entry mirrors the first.
52
+ </timeline-entry>
53
+ </timeline-container>
32
54
  ```
33
55
 
34
56
  ## Attributes / properties
35
57
 
36
- _None._
58
+ | Property | Attribute | Type | Default | Description |
59
+ | --- | --- | --- | --- | --- |
60
+ | `layout` | `layout` | `TimelineLayout` | `"left"` | Arrangement of the entries: a left-edge line, or a centered alternating one. |
37
61
 
38
62
  ## Events
39
63
 
@@ -11,6 +11,19 @@ exactly at the first and last dots. Only meaningful inside a
11
11
  timestamp prop (e.g. `chat-message`'s `timestamp`) should leave it unset —
12
12
  setting both renders the same time twice.
13
13
 
14
+ `label` is a free-text alternative for a timeline whose axis is not a wall
15
+ clock — a year, an era, a phase. It wins over `datetime` when both are set.
16
+ Slot `label` instead when it needs its own styling, since a property is
17
+ rendered inside this component's shadow DOM and cannot be reached from
18
+ outside.
19
+
20
+ `alternating` is set by `timeline-container` and should not be set by hand:
21
+ it switches the entry to three columns — label, line, body — with the sides
22
+ swapping on every second entry. The entry fills whatever height it is given,
23
+ so the line spans it rather than only its content — do not override the
24
+ host's `display` from outside, since a light-DOM rule beats the `:host`
25
+ declaration this relies on.
26
+
14
27
  The dot's `color` types the entry using the shared status-pill palette —
15
28
  `primary` by default, plus `neutral`, `info`, `success`, `warning`, and
16
29
  `danger`.
@@ -42,6 +55,8 @@ import "@f-ewald/components/timeline-entry.js";
42
55
  | Property | Attribute | Type | Default | Description |
43
56
  | --- | --- | --- | --- | --- |
44
57
  | `datetime` | `datetime` | `string | null` | `null` | ISO 8601 or SQLite datetime string, rendered as a relative time. |
58
+ | `label` | `label` | `string | null` | `null` | Free-text label shown in place of the relative time; wins over `datetime`. |
59
+ | `alternating` | `alternating` | `boolean` | `false` | Three-column alternating presentation. Set by `timeline-container` from its own `layout`; setting it directly is not supported. |
45
60
  | `color` | `color` | `StatusPillColor` | `"primary"` | Visual type of the entry's dot, from the shared status-pill palette: `primary` (default), `neutral`, `info`, `success`, `warning`, or `danger`. |
46
61
  | `compact` | `compact` | `boolean` | `false` | Dense, one-line presentation for system-status entries: tighter vertical spacing and smaller, muted content. |
47
62
  | `running` | `running` | `boolean` | `false` | Shows an animated ring spinner in place of the dot, indicating the entry represents in-progress work. Overrides `color` while set — the spinner always uses the muted/gray palette. |
@@ -62,7 +77,9 @@ _None._
62
77
  | `--ui-danger` |
63
78
  | `--ui-font` |
64
79
  | `--ui-font-size` |
80
+ | `--ui-font-size-lg` |
65
81
  | `--ui-font-size-sm` |
82
+ | `--ui-font-weight-medium` |
66
83
  | `--ui-font-weight-semibold` |
67
84
  | `--ui-info` |
68
85
  | `--ui-line-height-normal` |
@@ -72,4 +89,5 @@ _None._
72
89
  | `--ui-surface` |
73
90
  | `--ui-text` |
74
91
  | `--ui-text-muted` |
92
+ | `--ui-tracking-wide` |
75
93
  | `--ui-warning` |
package/llms.txt CHANGED
@@ -704,6 +704,65 @@ Example:
704
704
  <copy-link-button value="https://example.com/listing/42" label="Copy listing link"></copy-link-button>
705
705
  ```
706
706
 
707
+ ## <countdown-timer>
708
+
709
+ Per-second ticking count-down timer, e.g. a live "Retrying in 3 seconds"
710
+ indicator while waiting to retry a failed request. Renders nothing while
711
+ `until` is unset or unparseable. Remaining time is clamped to zero — it
712
+ never goes negative once the target instant has passed.
713
+
714
+ Import: `import "@f-ewald/components/countdown-timer.js";`
715
+
716
+ Properties: `until` (attribute `until`) : string | null, default null; `format` (attribute `format`) : DurationFormat, default "seconds"; `prefix` (attribute `prefix`) : string, default ""; `suffix` (attribute `suffix`) : string, default ""
717
+ Events: none
718
+ CSS custom properties: none
719
+
720
+ Example:
721
+ ```html
722
+ <countdown-timer until="2026-07-19T12:00:10Z" prefix="Retrying in "></countdown-timer>
723
+ <countdown-timer until="2026-07-19T12:00:10Z" format="compact" prefix="retrying in "></countdown-timer>
724
+ ```
725
+
726
+ ## <cron-schedule>
727
+
728
+ Repeat-schedule picker that reads and writes a standard 5-field cron
729
+ expression. The collapsed trigger shows a compact English description of
730
+ the current schedule ("Every hour", "10:17 every Monday"); clicking it
731
+ opens an anchored panel with the schedule form.
732
+
733
+ The panel offers frequency presets (every N minutes, hourly, daily, weekly,
734
+ monthly, yearly) plus an `Advanced` mode that edits each cron field as a
735
+ list of terms, so any valid expression — including compound fields that mix
736
+ ranges, steps, and single values — is reachable. Edits apply immediately:
737
+ each change updates `value` and fires `change`; closing the panel only
738
+ dismisses it.
739
+
740
+ An unparseable `value` (e.g. `@reboot`, which has no five-field form) is
741
+ preserved verbatim and shown as-is on the trigger; the panel then starts
742
+ from the default hourly schedule.
743
+
744
+ The host is `display: block` with a full-width trigger, matching the other
745
+ value-entry fields. To shrink an instance to its content, constrain the
746
+ host: `cron-schedule { display: inline-block; }`.
747
+
748
+ Import: `import "@f-ewald/components/cron-schedule.js";`
749
+
750
+ Properties: `value` (attribute `value`) : string, default "0 * * * *"; `label` (attribute `label`) : string, default ""; `disabled` (attribute `disabled`) : boolean, default false; `open` (attribute `open`) : boolean, default false; `description` (JS property only) : string, default —
751
+ Events: `change`
752
+ CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-mono`, `--ui-font-size-sm`, `--ui-font-size-xs`, `--ui-font-weight-medium`, `--ui-line-height-tight`, `--ui-primary`, `--ui-radius`, `--ui-radius-sm`, `--ui-shadow-lg`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`, `--ui-tracking-wide`
753
+
754
+ Example:
755
+ ```html
756
+ <cron-schedule label="Backup schedule" value="0 * * * *"></cron-schedule>
757
+
758
+ <script type="module">
759
+ const schedule = document.querySelector("cron-schedule");
760
+ schedule.addEventListener("change", (e) => {
761
+ console.log(e.detail.value, schedule.description);
762
+ });
763
+ </script>
764
+ ```
765
+
707
766
  ## <data-table>
708
767
 
709
768
  A generic, presentational table shell: renders a `<thead>` from `columns`
@@ -982,6 +1041,37 @@ Example:
982
1041
  </frame-box>
983
1042
  ```
984
1043
 
1044
+ ## <fullscreen-button>
1045
+
1046
+ Toggles fullscreen presentation of the page, or of a given `target` element.
1047
+
1048
+ The icon and accessible name track the *actual* fullscreen state rather than
1049
+ this button's own clicks, because fullscreen can be left without touching it
1050
+ — Escape, or the browser's own chrome — which would otherwise leave the
1051
+ button showing the wrong affordance.
1052
+
1053
+ The control is styled as a square icon-sized `ui-button` `secondary` variant
1054
+ (2rem, `--ui-radius-sm` corners, the `--ui-button-secondary-*` background and
1055
+ border tokens, so a gradient theme carries over) layered over an opaque
1056
+ `--ui-surface` base and an elevation shadow, since it normally floats above
1057
+ the content it expands.
1058
+
1059
+ Import: `import "@f-ewald/components/fullscreen-button.js";`
1060
+
1061
+ Properties: `target` (JS property only) : HTMLElement | null, default null; `enterLabel` (attribute `enter-label`) : string, default "Enter full screen"; `exitLabel` (attribute `exit-label`) : string, default "Exit full screen"
1062
+ Events: `fullscreen-change`
1063
+ CSS custom properties: `--ui-border`, `--ui-button-highlight`, `--ui-button-secondary-`, `--ui-button-secondary-background`, `--ui-button-secondary-background-active`, `--ui-button-secondary-background-hover`, `--ui-button-secondary-border`, `--ui-button-secondary-border-hover`, `--ui-focus-ring`, `--ui-line-height-glyph`, `--ui-radius-sm`, `--ui-shadow`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`
1064
+
1065
+ Example:
1066
+ ```html
1067
+ <fullscreen-button></fullscreen-button>
1068
+ <script type="module">
1069
+ const button = document.querySelector('fullscreen-button');
1070
+ button.target = document.querySelector('#deck'); // omit for the whole page
1071
+ button.addEventListener('fullscreen-change', (e) => console.log(e.detail.active));
1072
+ </script>
1073
+ ```
1074
+
985
1075
  ## <gallery-item>
986
1076
 
987
1077
  Declarative image metadata consumed by a parent `photo-gallery`.
@@ -1861,6 +1951,44 @@ Example:
1861
1951
  <roman-numeral value="2004"></roman-numeral>
1862
1952
  ```
1863
1953
 
1954
+ ## <scroll-dots>
1955
+
1956
+ Vertical section navigator for a long scrolled page or a slide deck: one dot
1957
+ per section, the active one drawn as an elongated rounded bar rather than a
1958
+ dot, which is the only cue needed to read position at a glance.
1959
+
1960
+ Controlled, like `pagination-nav`: it owns no scroll behavior and never
1961
+ reads the scroll position. The consumer sets `active` and moves the page in
1962
+ response to `dot-select` — what counts as the active section differs too much
1963
+ between a snapped deck and an ordinary long page to bake in.
1964
+
1965
+ Positioning is also the consumer's, since a rail is normally fixed into a
1966
+ reserved gutter that only the page knows the width of.
1967
+
1968
+ The dots use the same lighter-on-top gradient as `map-circle`/`map-pin`,
1969
+ derived from a single base `color` — a rail beside a map reads as the same
1970
+ family of marks as the pins on it.
1971
+
1972
+ Import: `import "@f-ewald/components/scroll-dots.js";`
1973
+
1974
+ Properties: `items` (JS property only) : ScrollDotsItem[], default []; `active` (attribute `active`) : number, default 0; `color` (attribute `color`) : string, default ""; `label` (attribute `label`) : string, default ""
1975
+ Events: `dot-select`
1976
+ CSS custom properties: `--ui-focus-ring`, `--ui-primary`, `--ui-text-muted`
1977
+
1978
+ Example:
1979
+ ```html
1980
+ <scroll-dots label="Journey stops"></scroll-dots>
1981
+ <script type="module">
1982
+ const rail = document.querySelector('scroll-dots');
1983
+ rail.items = ['Intro', 'Freiburg', 'Berkeley', { label: 'Credits', muted: true }];
1984
+ rail.active = 0;
1985
+ rail.addEventListener('dot-select', (e) => {
1986
+ rail.active = e.detail.index;
1987
+ sections[e.detail.index].scrollIntoView({ behavior: 'smooth', block: 'start' });
1988
+ });
1989
+ </script>
1990
+ ```
1991
+
1864
1992
  ## <scroll-to-bottom>
1865
1993
 
1866
1994
  Overlay button that appears once the page (or a given `target` container)
@@ -2157,15 +2285,25 @@ Example:
2157
2285
 
2158
2286
  ## <timeline-container>
2159
2287
 
2160
- Vertical timeline: a single connecting line runs down the left edge and each
2161
- slotted `timeline-entry` places a dot on it. This is a thin layout and
2162
- semantics wrapper — the entries draw the line segments and dots themselves,
2163
- so the container adds no gap between them (a gap would break the line).
2164
- Exposed to assistive technology as a list of events.
2288
+ Vertical timeline: a connecting line runs down the entries and each slotted
2289
+ `timeline-entry` places a dot on it. This is a thin layout and semantics
2290
+ wrapper — the entries draw the line segments and dots themselves, so the
2291
+ container adds no gap between them (a gap would break the line). Exposed to
2292
+ assistive technology as a list of events.
2293
+
2294
+ `layout` chooses where the line runs. `left` (the default) puts it down the
2295
+ left edge with each entry's label inline beside its headline. `alternating`
2296
+ centers it and gives each entry three columns — label, line, body — with the
2297
+ two sides swapping on every second entry, for a presentation timeline rather
2298
+ than an event log.
2299
+
2300
+ The layout is pushed onto each entry rather than read from here, because a
2301
+ shadow-DOM child cannot style itself against an ancestor portably —
2302
+ `:host-context()` is Chromium-only.
2165
2303
 
2166
2304
  Import: `import "@f-ewald/components/timeline-container.js";`
2167
2305
 
2168
- Properties: none
2306
+ Properties: `layout` (attribute `layout`) : TimelineLayout, default "left"
2169
2307
  Events: none
2170
2308
  CSS custom properties: none
2171
2309
 
@@ -2185,6 +2323,18 @@ Example:
2185
2323
  <chat-message role="user" author="Freddy">Ship it.</chat-message>
2186
2324
  </timeline-entry>
2187
2325
  </timeline-container>
2326
+
2327
+ <!-- A presentation timeline: centered line, label and body swapping sides. -->
2328
+ <timeline-container layout="alternating">
2329
+ <timeline-entry label="1987">
2330
+ <span slot="headline">Where it started</span>
2331
+ A first stop, with the label on the left.
2332
+ </timeline-entry>
2333
+ <timeline-entry label="2004">
2334
+ <span slot="headline">The question</span>
2335
+ The second entry mirrors the first.
2336
+ </timeline-entry>
2337
+ </timeline-container>
2188
2338
  ```
2189
2339
 
2190
2340
  ## <timeline-entry>
@@ -2200,6 +2350,19 @@ exactly at the first and last dots. Only meaningful inside a
2200
2350
  timestamp prop (e.g. `chat-message`'s `timestamp`) should leave it unset —
2201
2351
  setting both renders the same time twice.
2202
2352
 
2353
+ `label` is a free-text alternative for a timeline whose axis is not a wall
2354
+ clock — a year, an era, a phase. It wins over `datetime` when both are set.
2355
+ Slot `label` instead when it needs its own styling, since a property is
2356
+ rendered inside this component's shadow DOM and cannot be reached from
2357
+ outside.
2358
+
2359
+ `alternating` is set by `timeline-container` and should not be set by hand:
2360
+ it switches the entry to three columns — label, line, body — with the sides
2361
+ swapping on every second entry. The entry fills whatever height it is given,
2362
+ so the line spans it rather than only its content — do not override the
2363
+ host's `display` from outside, since a light-DOM rule beats the `:host`
2364
+ declaration this relies on.
2365
+
2203
2366
  The dot's `color` types the entry using the shared status-pill palette —
2204
2367
  `primary` by default, plus `neutral`, `info`, `success`, `warning`, and
2205
2368
  `danger`.
@@ -2213,9 +2376,9 @@ effect while `running` is set.
2213
2376
 
2214
2377
  Import: `import "@f-ewald/components/timeline-entry.js";`
2215
2378
 
2216
- Properties: `datetime` (attribute `datetime`) : string | null, default null; `color` (attribute `color`) : StatusPillColor, default "primary"; `compact` (attribute `compact`) : boolean, default false; `running` (attribute `running`) : boolean, default false
2379
+ Properties: `datetime` (attribute `datetime`) : string | null, default null; `label` (attribute `label`) : string | null, default null; `alternating` (attribute `alternating`) : boolean, default false; `color` (attribute `color`) : StatusPillColor, default "primary"; `compact` (attribute `compact`) : boolean, default false; `running` (attribute `running`) : boolean, default false
2217
2380
  Events: none
2218
- CSS custom properties: `--ui-border`, `--ui-danger`, `--ui-font`, `--ui-font-size`, `--ui-font-size-sm`, `--ui-font-weight-semibold`, `--ui-info`, `--ui-line-height-normal`, `--ui-line-height-tight`, `--ui-primary`, `--ui-success`, `--ui-surface`, `--ui-text`, `--ui-text-muted`, `--ui-warning`
2381
+ CSS custom properties: `--ui-border`, `--ui-danger`, `--ui-font`, `--ui-font-size`, `--ui-font-size-lg`, `--ui-font-size-sm`, `--ui-font-weight-medium`, `--ui-font-weight-semibold`, `--ui-info`, `--ui-line-height-normal`, `--ui-line-height-tight`, `--ui-primary`, `--ui-success`, `--ui-surface`, `--ui-text`, `--ui-text-muted`, `--ui-tracking-wide`, `--ui-warning`
2219
2382
 
2220
2383
  Example:
2221
2384
  ```html
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@f-ewald/components",
3
3
  "private": false,
4
- "version": "1.28.0",
4
+ "version": "1.30.0",
5
5
  "description": "A collection of universally usable web components for various tasks.",
6
6
  "type": "module",
7
7
  "main": "dist/index.js",