@f-ewald/components 1.28.0 → 1.29.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/llms.txt CHANGED
@@ -982,6 +982,37 @@ Example:
982
982
  </frame-box>
983
983
  ```
984
984
 
985
+ ## <fullscreen-button>
986
+
987
+ Toggles fullscreen presentation of the page, or of a given `target` element.
988
+
989
+ The icon and accessible name track the *actual* fullscreen state rather than
990
+ this button's own clicks, because fullscreen can be left without touching it
991
+ — Escape, or the browser's own chrome — which would otherwise leave the
992
+ button showing the wrong affordance.
993
+
994
+ The control is styled as a square icon-sized `ui-button` `secondary` variant
995
+ (2rem, `--ui-radius-sm` corners, the `--ui-button-secondary-*` background and
996
+ border tokens, so a gradient theme carries over) layered over an opaque
997
+ `--ui-surface` base and an elevation shadow, since it normally floats above
998
+ the content it expands.
999
+
1000
+ Import: `import "@f-ewald/components/fullscreen-button.js";`
1001
+
1002
+ 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"
1003
+ Events: `fullscreen-change`
1004
+ 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`
1005
+
1006
+ Example:
1007
+ ```html
1008
+ <fullscreen-button></fullscreen-button>
1009
+ <script type="module">
1010
+ const button = document.querySelector('fullscreen-button');
1011
+ button.target = document.querySelector('#deck'); // omit for the whole page
1012
+ button.addEventListener('fullscreen-change', (e) => console.log(e.detail.active));
1013
+ </script>
1014
+ ```
1015
+
985
1016
  ## <gallery-item>
986
1017
 
987
1018
  Declarative image metadata consumed by a parent `photo-gallery`.
@@ -1861,6 +1892,44 @@ Example:
1861
1892
  <roman-numeral value="2004"></roman-numeral>
1862
1893
  ```
1863
1894
 
1895
+ ## <scroll-dots>
1896
+
1897
+ Vertical section navigator for a long scrolled page or a slide deck: one dot
1898
+ per section, the active one drawn as an elongated rounded bar rather than a
1899
+ dot, which is the only cue needed to read position at a glance.
1900
+
1901
+ Controlled, like `pagination-nav`: it owns no scroll behavior and never
1902
+ reads the scroll position. The consumer sets `active` and moves the page in
1903
+ response to `dot-select` — what counts as the active section differs too much
1904
+ between a snapped deck and an ordinary long page to bake in.
1905
+
1906
+ Positioning is also the consumer's, since a rail is normally fixed into a
1907
+ reserved gutter that only the page knows the width of.
1908
+
1909
+ The dots use the same lighter-on-top gradient as `map-circle`/`map-pin`,
1910
+ derived from a single base `color` — a rail beside a map reads as the same
1911
+ family of marks as the pins on it.
1912
+
1913
+ Import: `import "@f-ewald/components/scroll-dots.js";`
1914
+
1915
+ Properties: `items` (JS property only) : ScrollDotsItem[], default []; `active` (attribute `active`) : number, default 0; `color` (attribute `color`) : string, default ""; `label` (attribute `label`) : string, default ""
1916
+ Events: `dot-select`
1917
+ CSS custom properties: `--ui-focus-ring`, `--ui-primary`, `--ui-text-muted`
1918
+
1919
+ Example:
1920
+ ```html
1921
+ <scroll-dots label="Journey stops"></scroll-dots>
1922
+ <script type="module">
1923
+ const rail = document.querySelector('scroll-dots');
1924
+ rail.items = ['Intro', 'Freiburg', 'Berkeley', { label: 'Credits', muted: true }];
1925
+ rail.active = 0;
1926
+ rail.addEventListener('dot-select', (e) => {
1927
+ rail.active = e.detail.index;
1928
+ sections[e.detail.index].scrollIntoView({ behavior: 'smooth', block: 'start' });
1929
+ });
1930
+ </script>
1931
+ ```
1932
+
1864
1933
  ## <scroll-to-bottom>
1865
1934
 
1866
1935
  Overlay button that appears once the page (or a given `target` container)
@@ -2157,15 +2226,25 @@ Example:
2157
2226
 
2158
2227
  ## <timeline-container>
2159
2228
 
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.
2229
+ Vertical timeline: a connecting line runs down the entries and each slotted
2230
+ `timeline-entry` places a dot on it. This is a thin layout and semantics
2231
+ wrapper — the entries draw the line segments and dots themselves, so the
2232
+ container adds no gap between them (a gap would break the line). Exposed to
2233
+ assistive technology as a list of events.
2234
+
2235
+ `layout` chooses where the line runs. `left` (the default) puts it down the
2236
+ left edge with each entry's label inline beside its headline. `alternating`
2237
+ centers it and gives each entry three columns — label, line, body — with the
2238
+ two sides swapping on every second entry, for a presentation timeline rather
2239
+ than an event log.
2240
+
2241
+ The layout is pushed onto each entry rather than read from here, because a
2242
+ shadow-DOM child cannot style itself against an ancestor portably —
2243
+ `:host-context()` is Chromium-only.
2165
2244
 
2166
2245
  Import: `import "@f-ewald/components/timeline-container.js";`
2167
2246
 
2168
- Properties: none
2247
+ Properties: `layout` (attribute `layout`) : TimelineLayout, default "left"
2169
2248
  Events: none
2170
2249
  CSS custom properties: none
2171
2250
 
@@ -2185,6 +2264,18 @@ Example:
2185
2264
  <chat-message role="user" author="Freddy">Ship it.</chat-message>
2186
2265
  </timeline-entry>
2187
2266
  </timeline-container>
2267
+
2268
+ <!-- A presentation timeline: centered line, label and body swapping sides. -->
2269
+ <timeline-container layout="alternating">
2270
+ <timeline-entry label="1987">
2271
+ <span slot="headline">Where it started</span>
2272
+ A first stop, with the label on the left.
2273
+ </timeline-entry>
2274
+ <timeline-entry label="2004">
2275
+ <span slot="headline">The question</span>
2276
+ The second entry mirrors the first.
2277
+ </timeline-entry>
2278
+ </timeline-container>
2188
2279
  ```
2189
2280
 
2190
2281
  ## <timeline-entry>
@@ -2200,6 +2291,19 @@ exactly at the first and last dots. Only meaningful inside a
2200
2291
  timestamp prop (e.g. `chat-message`'s `timestamp`) should leave it unset —
2201
2292
  setting both renders the same time twice.
2202
2293
 
2294
+ `label` is a free-text alternative for a timeline whose axis is not a wall
2295
+ clock — a year, an era, a phase. It wins over `datetime` when both are set.
2296
+ Slot `label` instead when it needs its own styling, since a property is
2297
+ rendered inside this component's shadow DOM and cannot be reached from
2298
+ outside.
2299
+
2300
+ `alternating` is set by `timeline-container` and should not be set by hand:
2301
+ it switches the entry to three columns — label, line, body — with the sides
2302
+ swapping on every second entry. The entry fills whatever height it is given,
2303
+ so the line spans it rather than only its content — do not override the
2304
+ host's `display` from outside, since a light-DOM rule beats the `:host`
2305
+ declaration this relies on.
2306
+
2203
2307
  The dot's `color` types the entry using the shared status-pill palette —
2204
2308
  `primary` by default, plus `neutral`, `info`, `success`, `warning`, and
2205
2309
  `danger`.
@@ -2213,9 +2317,9 @@ effect while `running` is set.
2213
2317
 
2214
2318
  Import: `import "@f-ewald/components/timeline-entry.js";`
2215
2319
 
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
2320
+ 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
2321
  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`
2322
+ 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
2323
 
2220
2324
  Example:
2221
2325
  ```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.29.0",
5
5
  "description": "A collection of universally usable web components for various tasks.",
6
6
  "type": "module",
7
7
  "main": "dist/index.js",