@f-ewald/components 1.33.1 → 1.35.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.
@@ -193,42 +193,87 @@ backbone, and `app-sidebar`, `action-bar`, `page-header`, `pagination-nav`, and
193
193
 
194
194
  ### Shell grid and metrics
195
195
 
196
- - `app-shell` owns a CSS grid with `sidebar`, `topbar`, `main` (default slot),
197
- `detail`, and `footer` areas plus the responsive behavior. It is the only
198
- component that coordinates the sidebar rail and the detail overlay.
196
+ - `app-shell` owns a CSS grid with `topbar`, `sidebar`, `main` (default
197
+ slot), `detail`, and `footer` areas. The top bar always spans the shell's
198
+ full width, in every sidebar state — its grid row spans all three columns,
199
+ while `sidebar`/`main`/`detail` share the row beneath it.
200
+ - The sidebar's three properties are independent: `sidebar-open` (visible or
201
+ not, closed by default), `sidebar-width` (`full` 16rem vs. `icon` 3.5rem
202
+ rail), and `sidebar-mode` (`overlay`, the default, vs. `push`). `overlay`
203
+ positions the sidebar with `position: absolute` against `.shell` (not the
204
+ viewport, so the component stays correct when embedded well short of the
205
+ full viewport) at a z-index above the top bar's corner, and its reserved
206
+ grid column width (`--_sidebar-w`) stays `0px` — opening it never resizes
207
+ or reflows `main`/`footer`, it visually covers whatever is underneath.
208
+ `push` instead sets `--_sidebar-w` to the current `sidebar-width` value, so
209
+ the sidebar becomes a real, in-flow grid item and `main`/`footer` reflow
210
+ around it, same as the top bar always doing so above it.
211
+ - Below the shared `48rem` breakpoint, `sidebar-mode`/`sidebar-width` are
212
+ ignored entirely — the sidebar is always a full-screen, modal,
213
+ scrim/Escape-dismissible drawer, same as the detail column's mobile
214
+ overlay. Those two properties only affect the desktop presentation.
199
215
  - Layout dimensions are documented literal rems, not `--ui-*` tokens (widths and
200
216
  spacing are constants in this system). A few are exposed as overridable
201
- `--component-*` custom properties for per-instance tuning, mirroring
202
- `--component-layer-z`:
203
- - sidebar expanded `--component-sidebar-width` = `16rem`;
204
- - sidebar rail `--component-sidebar-rail-width` = `3.5rem`;
217
+ `--component-*` custom properties for per-instance tuning:
218
+ - sidebar full width `--component-sidebar-width` = `16rem` (also full
219
+ screen width below the `48rem` breakpoint, regardless of `sidebar-width`);
220
+ - sidebar icon rail width `--component-sidebar-rail-width` = `3.5rem`;
205
221
  - top bar `--component-topbar-height` = `3rem`;
206
222
  - detail column reuses the `20rem` / `25rem` panel widths (the `detail-width`
207
223
  `compact` / `comfortable` attribute);
208
224
  - main content is white (`--component-main-background`, default `--ui-surface`)
209
225
  and fluid; constrain reading or form pages with a `max-width` on your own
210
226
  wrapper (roughly `40rem`–`48rem`).
211
- - The shared `48rem` breakpoint remains the only responsive breakpoint. At or
212
- below it the sidebar becomes an off-canvas drawer and the detail an overlay,
213
- both raised with `--component-layer-z` and dismissed by a scrim or Escape.
227
+ - `push` mode's width change is an instant snap, not an animated slide —
228
+ `--_sidebar-w` is a plain (unregistered) custom property feeding a grid
229
+ track, and those don't transition smoothly without `@property` syntax
230
+ registration. `overlay` mode's slide is a genuine `transform` transition
231
+ and animates normally.
232
+ - Z-index tiering keeps the shell's own chrome under the shared overlay
233
+ stack: `.nav-group` (the built-in toggle) is `41`, `.sidebar`/`.detail` are
234
+ `40`, `.scrim` is `39` — all fixed literals, not `--component-layer-z`,
235
+ since `app-shell` never calls `activateLayer`/`deactivateLayer` from
236
+ `utils/layer-stack.ts`. Any real `modal-dialog`/`confirm-dialog`/
237
+ `popover-panel`/`slide-panel` (all ≥100) must always paint above the
238
+ shell's own chrome. `.topbar` itself deliberately carries no z-index — an
239
+ explicit z-index on a CSS grid item creates a stacking context, which would
240
+ trap the toggle below the sidebar it opens; giving the z-index to the
241
+ toggle's own wrapper (`.nav-group`) instead avoids that trap. Relatedly,
242
+ `.sidebar` itself only gets `grid-area: sidebar` in `push` mode — an
243
+ absolutely-positioned grid item's inset properties resolve against its own
244
+ grid area's box rather than the whole grid container once `grid-area` is
245
+ set, even with explicit (non-`auto`) insets, which would anchor `overlay`
246
+ mode below the top bar's row instead of overlapping it.
214
247
 
215
248
  ### Sidebar
216
249
 
217
- - Collapsing is a two-mode design: on desktop the sidebar condenses to an icon
218
- rail (labels hide, icons stay) via `app-shell`'s `sidebar-collapsed`, which
219
- propagates `collapsed` to the slotted `app-sidebar`; below `48rem` it is a
220
- drawer with labels shown.
221
- - The built-in top-bar toggle and the `[` keyboard shortcut (ignored while a
222
- text field is focused or a modifier is held) both drive `sidebar-collapsed`.
223
- The shortcut is surfaced in the toggle's hover/focus tooltip, not as permanent
224
- chrome — reveal shortcuts on interaction rather than displaying them inline.
250
+ - Visibility, width, and layout mode are three independent `app-shell`
251
+ properties — not a two-mode rail/drawer split. `sidebar-open` (closed by
252
+ default at every breakpoint) is toggled by the built-in top-bar button or
253
+ the `[` keyboard shortcut (ignored while a text field is focused or a
254
+ modifier is held); the shortcut is surfaced in the toggle's hover/focus
255
+ tooltip, not as permanent chrome. `sidebar-width` and `sidebar-mode` have
256
+ no built-in toggle — a consumer sets them directly (e.g. from their own
257
+ settings UI), same as `detail-width`.
258
+ - Below `48rem` the open sidebar is always full width and modal — a scrim
259
+ dims the rest of the page and Escape dismisses it, same as the detail
260
+ overlay — regardless of `sidebar-width`/`sidebar-mode`. At or above `48rem`,
261
+ an `overlay`-mode sidebar is non-modal — no scrim, no Escape-dismiss, since
262
+ it reads as an ordinary always-interactive panel, not a blocking dialog;
263
+ only the toggle (or `[`) closes it. A `push`-mode sidebar is even more
264
+ clearly non-modal, since it never covers anything.
265
+ - `sidebar-width="icon"` drives the slotted `app-sidebar`'s own `collapsed`
266
+ (rail) attribute to match, in both `overlay` and `push` mode — `app-shell`
267
+ re-syncs it on every `sidebar-width` change and on `slotchange`. Outside of
268
+ that, `app-shell` doesn't otherwise manage `collapsed`; a caller can still
269
+ set it directly on a standalone `app-sidebar`.
225
270
  - Nav items are the consumer's `<a>`/`<button>` elements with an icon and a
226
271
  label; mark the active one with `aria-current="page"`. Each label reads the
227
- inherited `--app-sidebar-label` custom property so rail mode can hide it while
228
- its `aria-label` keeps the accessible name.
229
- - The `header` slot holds the brand: a small logo plus a name. Wrap the name in
230
- a `--app-sidebar-label` element so rail mode shows only the logo, centered in
231
- line with the nav icons.
272
+ inherited `--app-sidebar-label` custom property so rail mode can hide it
273
+ while its `aria-label` keeps the accessible name.
274
+ - The `header` slot holds the brand: a small logo plus a name. Wrap the name
275
+ in a `--app-sidebar-label` element so rail mode shows only the logo,
276
+ centered in line with the nav icons.
232
277
 
233
278
  ### Forms and actions
234
279
 
@@ -10,7 +10,9 @@ want an inline detail pane, use the list + detail template instead.
10
10
  ## Shell slots
11
11
 
12
12
  - `sidebar` → `app-sidebar` with the app's navigation.
13
- - `topbar` → `page-header` with the collection title (and optional actions).
13
+ - `topbar` → `page-header` with the collection title and, optionally, its
14
+ `actions` slot holding a dismissible `popover-panel` and/or a fullscreen
15
+ `modal-dialog` trigger.
14
16
  - default (`main`) → an `action-bar` above a `data-table`.
15
17
  - `footer` → `pagination-nav`.
16
18
 
@@ -20,7 +22,26 @@ want an inline detail pane, use the list + detail template instead.
20
22
  <app-shell style="height: 100vh">
21
23
  <app-sidebar slot="sidebar"><!-- nav items --></app-sidebar>
22
24
 
23
- <page-header slot="topbar" heading="Members"></page-header>
25
+ <page-header slot="topbar" heading="Members">
26
+ <div slot="actions" style="display: flex; align-items: center; gap: 0.5rem;">
27
+ <ui-button id="fullscreen-report-open" size="sm" variant="secondary">Full report</ui-button>
28
+ <modal-dialog id="fullscreen-report" heading="Members — full report" size="fullscreen">
29
+ <div style="padding: 1rem;">
30
+ <data-table style="display: block;"></data-table>
31
+ </div>
32
+ </modal-dialog>
33
+
34
+ <div style="position: relative; display: inline-block;">
35
+ <icon-button id="quick-actions-trigger" label="Quick actions"></icon-button>
36
+ <popover-panel id="quick-actions-popover" heading="Quick actions">
37
+ <div style="display: flex; flex-direction: column; gap: 0.5rem; padding: 0.75rem;">
38
+ <ui-button size="sm" variant="secondary">Export CSV</ui-button>
39
+ <ui-button size="sm" variant="secondary">Import CSV</ui-button>
40
+ </div>
41
+ </popover-panel>
42
+ </div>
43
+ </div>
44
+ </page-header>
24
45
 
25
46
  <div>
26
47
  <action-bar>
@@ -44,7 +65,18 @@ want an inline detail pane, use the list + detail template instead.
44
65
  rows to you.
45
66
  - Put search and filters in the action bar's `start` slot and record actions
46
67
  (create, delete) in `end`.
68
+ - The `popover-panel` trigger needs a `position: relative` wrapper around both
69
+ the trigger and the panel — the panel anchors to that ancestor, not to
70
+ `page-header` itself. Toggle `.open` on click and set it back to `false` on
71
+ the panel's `panel-close` event (fired on outside click, Escape, or its own
72
+ close button) — `popover-panel` never closes itself.
73
+ - For a full-viewport overlay, use `modal-dialog` with `size="fullscreen"`
74
+ instead of growing `popover-panel` — `popover-panel`'s `centered` mode tops
75
+ out at a 25rem card, and `modal-dialog` already owns the fullscreen/lg/default
76
+ sizing plus the same focus-trap/Escape/layer-stack behavior. It needs no
77
+ positioning wrapper (it's a fixed, viewport-relative overlay) and is wired
78
+ the same way: toggle `.open` on click, reset it to `false` on `panel-close`.
47
79
 
48
80
  **Live demo:** `demo/layouts/list-only.html`
49
81
 
50
- **Components:** app-shell, app-sidebar, page-header, action-bar, data-table, pagination-nav
82
+ **Components:** app-shell, app-sidebar, page-header, action-bar, data-table, pagination-nav, icon-button, popover-panel, modal-dialog
@@ -14,6 +14,15 @@ circle, info → information circle, warning → exclamation triangle). Each toa
14
14
  auto-dismisses after `duration` ms and can also be dismissed via its ✕
15
15
  button. Appears/disappears instantly — no slide/fade transitions.
16
16
 
17
+ A toast with `duration > 0` replaces its ✕ button with a countdown: a
18
+ number of seconds remaining inside a ring that fills in clockwise over
19
+ `duration`. Hovering or keyboard-focusing the toast swaps the countdown
20
+ back for the ✕ and pauses the countdown (both the visual ring/number and
21
+ the underlying auto-dismiss timer) — the toast won't disappear while
22
+ someone's reading it or has tabbed to its close button — resuming from
23
+ where it left off once the pointer/focus leaves. A `duration: 0` toast has
24
+ no countdown to show, so its ✕ is always visible, exactly as before.
25
+
17
26
  Each variant's background reads a dedicated `--ui-toast-*-background` hook
18
27
  (`success`/`error`/`info`/`warning`), which defaults to the flat
19
28
  `--ui-success`/`--ui-danger`/`--ui-info`/`--ui-warning` tokens unchanged —
@@ -67,6 +76,7 @@ _None._
67
76
  | `--ui-font` |
68
77
  | `--ui-font-size` |
69
78
  | `--ui-font-size-sm` |
79
+ | `--ui-font-size-xs` |
70
80
  | `--ui-font-weight-regular` |
71
81
  | `--ui-font-weight-semibold` |
72
82
  | `--ui-hover-overlay` |
package/llms.txt CHANGED
@@ -161,29 +161,50 @@ Example:
161
161
  ## <app-shell>
162
162
 
163
163
  The dashboard page shell: a slot-based CSS-grid backbone that arranges a
164
- full-height sidebar, a top bar, the main content, an optional right-hand
165
- detail column, and an optional footer. It owns the responsive behavior so
166
- consumers don't re-implement it — above the shared 48rem breakpoint the
167
- sidebar collapses to an icon rail and the detail region is an inline column;
168
- at or below it the sidebar becomes an off-canvas drawer and the detail region
169
- an overlay, both dismissed by a scrim or Escape.
164
+ top bar, the main content, an optional right-hand detail column, an
165
+ optional footer, and a sidebar. The top bar always spans the shell's full
166
+ width, in every sidebar state.
167
+
168
+ The sidebar's visibility, width, and layout mode are three independent
169
+ properties:
170
+ - `sidebar-open` (default closed) — whether it's shown at all.
171
+ - `sidebar-width`: `"full"` (16rem, icons + labels, the default) or
172
+ `"icon"` (3.5rem rail, icons only — drives the slotted `app-sidebar`'s
173
+ own `collapsed` attribute).
174
+ - `sidebar-mode`: `"overlay"` (the default) floats the sidebar above the
175
+ shell's own content with a higher z-index, covering part of the top
176
+ bar's corner and whatever content sits beneath it, without ever
177
+ resizing or reflowing `main`/`footer`. `"push"` instead reserves a real
178
+ grid column beside `main`/`footer` (which resize to make room) — the
179
+ top bar still spans full width above it either way.
180
+
181
+ Below the shared 48rem breakpoint the sidebar always behaves as a
182
+ full-width, modal, scrim/Escape-dismissible drawer regardless of
183
+ `sidebar-mode`/`sidebar-width` — those two properties only affect the
184
+ desktop presentation. Above 48rem, an `overlay`-mode sidebar is a
185
+ non-modal panel (no dimming scrim, no Escape-dismiss, since it reads as
186
+ an ordinary always-interactive panel rather than a blocking dialog); a
187
+ `push`-mode sidebar is even more clearly non-modal, since it never
188
+ covers anything.
189
+
190
+ The right-hand detail column is unaffected by any of the above: it still
191
+ reserves an inline grid column on desktop and becomes a dismissible
192
+ overlay (scrim/Escape) on mobile.
170
193
 
171
194
  Widths are tunable per instance via `--component-sidebar-width` (16rem),
172
195
  `--component-sidebar-rail-width` (3.5rem), and `--component-topbar-height`
173
196
  (3rem); the detail column reuses the 20rem/25rem panel widths. The main
174
197
  content area is white by default — override it with
175
- `--component-main-background`. Give the shell a height (e.g. `height: 100vh`)
176
- so the sidebar and main can size and scroll.
198
+ `--component-main-background`. Give the shell a height (e.g. `height:
199
+ 100vh`) so the sidebar and main can size and scroll.
177
200
 
178
- The built-in top-bar button toggles the sidebar, and so does pressing `[`
179
- anywhere on the page (ignored while typing in a text field or with a
180
- modifier held). Hovering or keyboard-focusing the toggle reveals a tooltip
181
- naming the action and its `[` shortcut — the shortcut is not shown as
182
- permanent chrome.
201
+ Hovering or keyboard-focusing the toggle reveals a tooltip naming the
202
+ action and its `[` shortcut — the shortcut is not shown as permanent
203
+ chrome.
183
204
 
184
205
  Import: `import "@f-ewald/components/app-shell.js";`
185
206
 
186
- Properties: `sidebarCollapsed` (attribute `sidebar-collapsed`) : boolean, default false; `detailOpen` (attribute `detail-open`) : boolean, default false; `detailWidth` (attribute `detail-width`) : "compact" | "comfortable", default "compact"
207
+ Properties: `sidebarOpen` (attribute `sidebar-open`) : boolean, default false; `sidebarMode` (attribute `sidebar-mode`) : "overlay" | "push", default "overlay"; `sidebarWidth` (attribute `sidebar-width`) : "full" | "icon", default "full"; `detailOpen` (attribute `detail-open`) : boolean, default false; `detailWidth` (attribute `detail-width`) : "compact" | "comfortable", default "compact"
187
208
  Events: `sidebar-toggle`, `detail-close`
188
209
  CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font-size-sm`, `--ui-line-height-tight`, `--ui-on-accent`, `--ui-overlay`, `--ui-radius-sm`, `--ui-shadow`, `--ui-shadow-lg`, `--ui-surface`, `--ui-surface-muted`, `--ui-text-muted`, `--ui-tooltip`
189
210
 
@@ -215,9 +236,10 @@ label), optional `<p>` group headings, and marks the active item with
215
236
  `aria-current="page"`. The sidebar styles them, tracks hover/active/focus,
216
237
  and — in collapsed "rail" mode — centers the icons and hides the labels.
217
238
 
218
- Rail mode is driven by the `collapsed` attribute (the parent `app-shell`
219
- toggles it). Labels are hidden by the inherited `--app-sidebar-label` custom
220
- property, so each label element should read it, e.g.
239
+ Rail mode is driven by the `collapsed` attribute, which callers set
240
+ directly — `app-shell` no longer auto-manages it (its own sidebar is a
241
+ pure overlay, not a rail). Labels are hidden by the inherited
242
+ `--app-sidebar-label` custom property, so each label element should read it, e.g.
221
243
  `<span style="display: var(--app-sidebar-label, inline)">Reports</span>`;
222
244
  keep an `aria-label` on the item so its accessible name survives collapse.
223
245
  The sidebar fills the width and height of its container — `app-shell` owns
@@ -2463,6 +2485,15 @@ circle, info → information circle, warning → exclamation triangle). Each toa
2463
2485
  auto-dismisses after `duration` ms and can also be dismissed via its ✕
2464
2486
  button. Appears/disappears instantly — no slide/fade transitions.
2465
2487
 
2488
+ A toast with `duration > 0` replaces its ✕ button with a countdown: a
2489
+ number of seconds remaining inside a ring that fills in clockwise over
2490
+ `duration`. Hovering or keyboard-focusing the toast swaps the countdown
2491
+ back for the ✕ and pauses the countdown (both the visual ring/number and
2492
+ the underlying auto-dismiss timer) — the toast won't disappear while
2493
+ someone's reading it or has tabbed to its close button — resuming from
2494
+ where it left off once the pointer/focus leaves. A `duration: 0` toast has
2495
+ no countdown to show, so its ✕ is always visible, exactly as before.
2496
+
2466
2497
  Each variant's background reads a dedicated `--ui-toast-*-background` hook
2467
2498
  (`success`/`error`/`info`/`warning`), which defaults to the flat
2468
2499
  `--ui-success`/`--ui-danger`/`--ui-info`/`--ui-warning` tokens unchanged —
@@ -2481,7 +2512,7 @@ Import: `import "@f-ewald/components/toast-notification.js";`
2481
2512
 
2482
2513
  Properties: none
2483
2514
  Events: none
2484
- CSS custom properties: `--ui-button-highlight`, `--ui-button-text-shadow`, `--ui-danger`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size`, `--ui-font-size-sm`, `--ui-font-weight-regular`, `--ui-font-weight-semibold`, `--ui-hover-overlay`, `--ui-info`, `--ui-line-height-glyph`, `--ui-line-height-normal`, `--ui-on-accent`, `--ui-radius`, `--ui-radius-sm`, `--ui-shadow-lg`, `--ui-success`, `--ui-text`, `--ui-toast-`, `--ui-toast-error-background`, `--ui-toast-highlight`, `--ui-toast-info-background`, `--ui-toast-success-background`, `--ui-toast-text-shadow`, `--ui-toast-warning-background`, `--ui-warning`
2515
+ CSS custom properties: `--ui-button-highlight`, `--ui-button-text-shadow`, `--ui-danger`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size`, `--ui-font-size-sm`, `--ui-font-size-xs`, `--ui-font-weight-regular`, `--ui-font-weight-semibold`, `--ui-hover-overlay`, `--ui-info`, `--ui-line-height-glyph`, `--ui-line-height-normal`, `--ui-on-accent`, `--ui-radius`, `--ui-radius-sm`, `--ui-shadow-lg`, `--ui-success`, `--ui-text`, `--ui-toast-`, `--ui-toast-error-background`, `--ui-toast-highlight`, `--ui-toast-info-background`, `--ui-toast-success-background`, `--ui-toast-text-shadow`, `--ui-toast-warning-background`, `--ui-warning`
2485
2516
 
2486
2517
  Example:
2487
2518
  ```html
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@f-ewald/components",
3
3
  "private": false,
4
- "version": "1.33.1",
4
+ "version": "1.35.0",
5
5
  "description": "A collection of universally usable web components for various tasks.",
6
6
  "type": "module",
7
7
  "main": "dist/index.js",