@f-ewald/components 1.33.1 → 1.34.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/docs/app-shell.md CHANGED
@@ -1,25 +1,46 @@
1
1
  # `<app-shell>`
2
2
 
3
3
  The dashboard page shell: a slot-based CSS-grid backbone that arranges a
4
- full-height sidebar, a top bar, the main content, an optional right-hand
5
- detail column, and an optional footer. It owns the responsive behavior so
6
- consumers don't re-implement it — above the shared 48rem breakpoint the
7
- sidebar collapses to an icon rail and the detail region is an inline column;
8
- at or below it the sidebar becomes an off-canvas drawer and the detail region
9
- an overlay, both dismissed by a scrim or Escape.
4
+ top bar, the main content, an optional right-hand detail column, an
5
+ optional footer, and a sidebar. The top bar always spans the shell's full
6
+ width, in every sidebar state.
7
+
8
+ The sidebar's visibility, width, and layout mode are three independent
9
+ properties:
10
+ - `sidebar-open` (default closed) — whether it's shown at all.
11
+ - `sidebar-width`: `"full"` (16rem, icons + labels, the default) or
12
+ `"icon"` (3.5rem rail, icons only — drives the slotted `app-sidebar`'s
13
+ own `collapsed` attribute).
14
+ - `sidebar-mode`: `"overlay"` (the default) floats the sidebar above the
15
+ shell's own content with a higher z-index, covering part of the top
16
+ bar's corner and whatever content sits beneath it, without ever
17
+ resizing or reflowing `main`/`footer`. `"push"` instead reserves a real
18
+ grid column beside `main`/`footer` (which resize to make room) — the
19
+ top bar still spans full width above it either way.
20
+
21
+ Below the shared 48rem breakpoint the sidebar always behaves as a
22
+ full-width, modal, scrim/Escape-dismissible drawer regardless of
23
+ `sidebar-mode`/`sidebar-width` — those two properties only affect the
24
+ desktop presentation. Above 48rem, an `overlay`-mode sidebar is a
25
+ non-modal panel (no dimming scrim, no Escape-dismiss, since it reads as
26
+ an ordinary always-interactive panel rather than a blocking dialog); a
27
+ `push`-mode sidebar is even more clearly non-modal, since it never
28
+ covers anything.
29
+
30
+ The right-hand detail column is unaffected by any of the above: it still
31
+ reserves an inline grid column on desktop and becomes a dismissible
32
+ overlay (scrim/Escape) on mobile.
10
33
 
11
34
  Widths are tunable per instance via `--component-sidebar-width` (16rem),
12
35
  `--component-sidebar-rail-width` (3.5rem), and `--component-topbar-height`
13
36
  (3rem); the detail column reuses the 20rem/25rem panel widths. The main
14
37
  content area is white by default — override it with
15
- `--component-main-background`. Give the shell a height (e.g. `height: 100vh`)
16
- so the sidebar and main can size and scroll.
38
+ `--component-main-background`. Give the shell a height (e.g. `height:
39
+ 100vh`) so the sidebar and main can size and scroll.
17
40
 
18
- The built-in top-bar button toggles the sidebar, and so does pressing `[`
19
- anywhere on the page (ignored while typing in a text field or with a
20
- modifier held). Hovering or keyboard-focusing the toggle reveals a tooltip
21
- naming the action and its `[` shortcut — the shortcut is not shown as
22
- permanent chrome.
41
+ Hovering or keyboard-focusing the toggle reveals a tooltip naming the
42
+ action and its `[` shortcut — the shortcut is not shown as permanent
43
+ chrome.
23
44
 
24
45
  ## Install
25
46
 
@@ -51,7 +72,9 @@ import "@f-ewald/components/app-shell.js";
51
72
 
52
73
  | Property | Attribute | Type | Default | Description |
53
74
  | --- | --- | --- | --- | --- |
54
- | `sidebarCollapsed` | `sidebar-collapsed` | `boolean` | `false` | Collapses the sidebar to an icon rail on desktop. |
75
+ | `sidebarOpen` | `sidebar-open` | `boolean` | `false` | Whether the sidebar is open. Closed by default at every breakpoint. |
76
+ | `sidebarMode` | `sidebar-mode` | `"overlay" | "push"` | `"overlay"` | `"overlay"` (default) floats the sidebar above content; `"push"` reserves a grid column instead. |
77
+ | `sidebarWidth` | `sidebar-width` | `"full" | "icon"` | `"full"` | Sidebar width when open: `"full"` (16rem, icons + labels) or `"icon"` (3.5rem rail, icons only). |
55
78
  | `detailOpen` | `detail-open` | `boolean` | `false` | Shows the right-hand detail region (inline column, or overlay on mobile). |
56
79
  | `detailWidth` | `detail-width` | `"compact" | "comfortable"` | `"compact"` | Detail width: `compact` (20rem) or `comfortable` (25rem). |
57
80
 
@@ -7,9 +7,10 @@ label), optional `<p>` group headings, and marks the active item with
7
7
  `aria-current="page"`. The sidebar styles them, tracks hover/active/focus,
8
8
  and — in collapsed "rail" mode — centers the icons and hides the labels.
9
9
 
10
- Rail mode is driven by the `collapsed` attribute (the parent `app-shell`
11
- toggles it). Labels are hidden by the inherited `--app-sidebar-label` custom
12
- property, so each label element should read it, e.g.
10
+ Rail mode is driven by the `collapsed` attribute, which callers set
11
+ directly — `app-shell` no longer auto-manages it (its own sidebar is a
12
+ pure overlay, not a rail). Labels are hidden by the inherited
13
+ `--app-sidebar-label` custom property, so each label element should read it, e.g.
13
14
  `<span style="display: var(--app-sidebar-label, inline)">Reports</span>`;
14
15
  keep an `aria-label` on the item so its accessible name survives collapse.
15
16
  The sidebar fills the width and height of its container — `app-shell` owns
@@ -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
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
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.34.0",
5
5
  "description": "A collection of universally usable web components for various tasks.",
6
6
  "type": "module",
7
7
  "main": "dist/index.js",