@danjelp/ngx-app-shell 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danjel Peqini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,559 @@
+# @danjelp/ngx-app-shell
+
+[![npm](https://img.shields.io/npm/v/@danjelp/ngx-app-shell)](https://www.npmjs.com/package/@danjelp/ngx-app-shell)
+[![license](https://img.shields.io/npm/l/@danjelp/ngx-app-shell)](https://github.com/dpeqini/ngx-app-shell/blob/main/LICENSE)
+
+A reusable Angular navigational shell: **sidebar + topbar + main + footer**.
+
+- Layout comes from CSS custom properties.
+- Chrome comes from named slots that react to the space *they* have, not the window.
+- The sidebar's collapse policy is a swappable strategy that can change at runtime.
+
+```
+projects/app-shell/
+├── styles/_tokens.scss                 public Sass entry (@forward)
+└── src/
+    ├── public-api.ts                   the only import surface
+    └── lib/
+        ├── app-shell.imports.ts        APP_SHELL convenience array
+        ├── core/
+        │   ├── shell.types.ts          SidebarState, ShellSlotName, ShellApi …
+        │   ├── shell.config.ts         ShellConfig, provideAppShell(), mergeShellConfig()
+        │   ├── shell.store.ts          the one source of truth (root, signals)
+        │   ├── shell-state-storage.ts  persistence port (localStorage by default)
+        │   └── shell.ids.ts
+        ├── sidebar/
+        │   ├── sidebar-behavior.ts     SidebarBehavior interface + DI token
+        │   ├── sidebar-states.ts       drawerState / railState / panelState / hiddenState
+        │   ├── responsive-sidebar-behavior.ts   default policy
+        │   ├── manual-sidebar-behavior.ts       user decides, never auto-collapses
+        │   └── drawer-sidebar-behavior.ts       always an off-canvas drawer
+        ├── responsive/
+        │   ├── shell-size.ts           buckets, resolveSize, atLeast/atMost/isBelow
+        │   ├── observe-width.ts        ResizeObserver → signal
+        │   ├── measure-region.ts       width + bucket for any element
+        │   ├── shell-region.ts         SHELL_REGION: "the space I actually have"
+        │   └── container-size.directive.ts   [shellContainerSize] for your own UI
+        ├── slots/                      shellSlot directive, registry, outlet, hasSlot()
+        ├── layout/                     app-shell, topbar, sidebar, subheader, footer, overflow menu
+        ├── nav/                        shell-nav, shell-nav-item, ShellNavRegistry, types
+        ├── breadcrumbs/                ShellBreadcrumbStore, shell-breadcrumb, types
+        ├── directives/sidebar-toggle.directive.ts
+        ├── a11y/focus-trap.ts
+        └── styles/_tokens.scss         the token map (single source of truth)
+```
+
+## Install
+
+```bash
+npm install @danjelp/ngx-app-shell
+```
+
+The peer dependencies are `@angular/core`, `@angular/common` and `@angular/router` (19–22), plus
+`rxjs` 7.
+
+## Quick start
+
+```ts
+// app.config.ts
+providers: [
+  provideRouter(routes),
+  provideAppShell({
+    layout: 'topbar-full',
+    sidebar: { collapseBelow: 'lg', overlayBelow: 'md', resizable: true, toggleShortcut: 'b' },
+  }),
+];
+```
+
+```scss
+// styles.scss — optional: every token has an inline fallback
+@use '@danjelp/ngx-app-shell/styles/tokens' as shell;
+@include shell.tokens;
+@include shell.dark-tokens(':root[data-theme="dark"]');
+
+:root {
+  --shell-topbar-height: 64px;
+  --shell-sidebar-width: 250px;
+  --shell-main-padding: 24px;
+}
+```
+
+```html
+<!-- app.html -->
+<app-shell>
+  <ng-template shellSlot="brand"><a routerLink="/">Acme</a></ng-template>
+  <ng-template shellSlot="sidebar-nav">
+    <shell-nav [groups]="navigation" [iconTemplate]="icon" />
+  </ng-template>
+  <ng-template #icon let-name><my-icon [name]="name" /></ng-template>
+
+  <router-outlet />
+</app-shell>
+```
+
+```ts
+@Component({ imports: [APP_SHELL, RouterOutlet, RouterLink], … })
+```
+
+### Mapping of the original layout variables
+
+| original                   | shell                                                                  |
+| -------------------------- | ---------------------------------------------------------------------- |
+| `--topbar-height`          | `--shell-topbar-height`                                                |
+| `--sidebar-width`          | `--shell-sidebar-width`                                                |
+| `--sidebar-top-offset`     | derived from the layout (`--shell-sidebar-top-offset`, read-only)      |
+| `--topbar-left-offset`     | derived from the layout — the topbar is its own grid area             |
+| `--main-container-padding` | `--shell-main-padding`, no topbar compensation — `main` is its own row |
+
+## 1. Layout: a grid driven by custom properties
+
+There are three named grid areas and one runtime value. Switching arrangement swaps only
+`grid-template-areas`, so no component needs to know where it sits.
+
+```
+topbar-full             sidebar-full            stacked
+┌───────────────┐       ┌────┬──────────┐       ┌───────────────┐
+│    topbar     │       │ s  │  topbar  │       │    topbar     │
+├────┬──────────┤       │ i  ├──────────┤       ├────┬──────────┤
+│ sb │   main   │       │ d  │   main   │       │ sb │   main   │
+├────┼──────────┤       │ e  ├──────────┤       ├────┴──────────┤
+│ sb │  footer  │       │ b  │  footer  │       │    footer     │
+└────┴──────────┘       └────┴──────────┘       └───────────────┘
+```
+
+`inset` puts the topbar, content and footer together in one rounded card (the *frame*). The
+sidebar sits directly on the shell background, with no surface, border or shadow; the drawer
+keeps its own.
+
+```
+inset
+┌────┬───────────────────┐
+│    │╭─────────────────╮│
+│ sb ││     topbar      ││
+│    ││      main       ││
+│    ││     footer      ││
+│    │╰─────────────────╯│
+└────┴───────────────────┘
+```
+
+Inside the card, `scroll` chooses what moves:
+- `'main'`: only the content scrolls, between a pinned topbar and footer.
+- `'page'`: the card itself scrolls. The topbar sticks to the top of the card, and the footer
+  follows the content.
+
+The card never leaves the screen and the sidebar never moves. Style the card with the `frame-*`
+tokens, and the area around it with `--shell-bg`.
+
+The only layout value TypeScript writes is `--shell-sidebar-track`, bound from the resolved
+sidebar state. With `scroll: 'main'` only `main` scrolls, and the shell scrolls it back to the
+top after each navigation (`scrollTopOnNavigate`). With `scroll: 'page'` the document scrolls,
+and the topbar and sidebar stick.
+
+## 2. Adding items: slots and nav data
+
+There are two mechanisms, for two kinds of content.
+
+### Slots — templates that register themselves
+
+`<ng-content select>` can't move content between places, and a shell needs exactly that:
+search collapses to an icon, and actions move into an overflow menu. So each slot is an
+`ng-template` that registers with a root `ShellSlotRegistry` when it is created and unregisters
+when it is destroyed. Each region renders the slots it owns with `<shell-slot-outlet>`.
+
+```html
+<ng-template shellSlot="actions" slotOrder="1" slotMinSize="md" slotOverflow let-overflow="overflow">
+  <button [class]="overflow ? 'menu-row' : 'icon-btn'">Notifications</button>
+</ng-template>
+```
+
+| input          | meaning                                                                  |
+| -------------- | ------------------------------------------------------------------------ |
+| `shellSlot`    | target slot name                                                         |
+| `slotOrder`    | ascending order within the slot (several templates per slot is fine)     |
+| `slotMinSize`  | render only when the *region* is at least this size                      |
+| `slotMaxSize`  | render only up to this size (narrow-only affordances)                    |
+| `slotOverflow` | when it doesn't fit, move it to the ⋯ menu instead of dropping it (only slots in `config.overflowSlots`; dev mode warns otherwise) |
+
+Template context: `let-sidebar` (resolved `SidebarState`), `let-size` (shell size),
+`let-region` (this region's size), `let-overflow` (true in the ⋯ menu) and `let-shell`
+(`ShellApi`).
+
+Because registration is a service call rather than content projection, a **routed page can
+contribute chrome** — its own actions or title — and it disappears when the page is destroyed.
+
+### Navigation — data in, markup out
+
+`<shell-nav>` renders `ShellNavGroup[]` (or a flat `ShellNavItem[]`) and handles:
+- rail labels: hidden, but still read by screen readers and shown as tooltips
+- badges turning into dots on the rail
+- nested sections that open themselves when they contain the active route
+- collapsible groups and `aria-current`
+
+The same array can feed a command palette.
+
+| input            | purpose                                                                     |
+| ---------------- | --------------------------------------------------------------------------- |
+| `groups`/`items` | the data                                                                    |
+| `iconTemplate`   | turns `item.icon` keys into icons (`let-name`)                              |
+| `itemTemplate`   | replaces the **content** of each row. The row element — link, section button, active state, children — stays the library's. Context: `item`, `depth`, `labels`, `expanded` |
+| `labels`         | overrides the sidebar's label state                                         |
+| `headings`       | `false` for a dense list without group headings                             |
+
+On the rail, an item without an icon shows the first letter of its label, so no row is ever
+blank.
+
+### Feature-contributed nav items — `ShellNavRegistry`
+
+The app declares the groups, and features fill them by group `id`. A group with no items and no
+contributions isn't rendered, so an app can reserve an empty group for plugins.
+
+```ts
+// app-lifetime: feature-owned link, registered at startup
+providers: [provideShellNavItems('workspace', [{ label: 'Roadmap', route: '/roadmap' }], { order: 10 })];
+
+// component-lifetime: context links while a page is open
+contributeNavItems('workspace', computed(() => [{ label: 'Inbox', route: '/inbox', badge: unread() }]));
+
+// merged tree for your own consumers (palette, breadcrumbs)
+inject(ShellNavRegistry).merge(groups);
+```
+
+## 3. Regions measure themselves, not the window
+
+Every region measures its own width and provides `SHELL_REGION` with it. **Expanding the sidebar
+from a rail to a full panel takes ~200px away from the topbar without the window resizing.** The
+topbar notices, drops to a smaller size, and collapses its slots exactly as it would on a phone.
+
+The sizes are based on container width, not device width: `xs 0` · `sm 520` · `md 768` · `lg 1080` · `xl 1440`.
+Every region also exposes `data-shell-size` and a named CSS container (`shell-topbar`,
+`shell-main`, `shell-footer`), so plain CSS can react too:
+
+```scss
+@container shell-topbar (max-width: 820px) { .search__kbd { display: none; } }
+```
+
+`[shellContainerSize]` gives your own components the same trick. The sidebar is the deliberate
+exception: it reports a size based on what it shows — `xs` on a rail, `md` when labels show —
+so `slotMinSize="sm"` in the sidebar means "only when labels show".
+
+## 4. The sidebar's behaviour is a strategy
+
+The state is computed from four inputs: the shell size, the user's **intent** (`auto`,
+`expanded`, `collapsed` or `hidden`; persisted), a temporary **drawer-open** flag (never
+persisted, and reset whenever the size changes), and the peek flag.
+
+```ts
+export const railFirst: SidebarBehavior = {
+  resolve({ size, intent, drawerOpen, peeking, config: { sidebar } }) {
+    if (isBelow(size, sidebar.overlayBelow)) return drawerState(drawerOpen, sidebar);
+    if (intent === 'hidden') return hiddenState();
+    return intent === 'expanded' ? panelState(sidebar) : railState(peeking, sidebar);
+  },
+};
+
+provideAppShell({}, { behavior: railFirst });   // at startup
+inject(ShellStore).setBehavior(railFirst);      // or at runtime
+```
+
+Shipped policies: `responsiveSidebarBehavior` (default), `manualSidebarBehavior` and
+`drawerSidebarBehavior`.
+
+A drawer toggles open and closed. A persistent panel asks `nextIntent`, which defaults to
+expanded ⇄ collapsed.
+
+| mode        | open | modal | labels  | notes                                          |
+| ----------- | ---- | ----- | ------- | ---------------------------------------------- |
+| `expanded`  | ✓    |       | ✓       | in-flow panel, optional drag-to-resize         |
+| `collapsed` | ✓    |       | on peek | icon rail; peek widens it over the content     |
+| `overlay`   | ✗/✓  | ✓     | ✓       | drawer, scrim, focus trap, Escape              |
+| `hidden`    | ✗    |       |         | not displayed, zero-width track                |
+
+`trackWidth` and `panelWidth` are separate so that peek doesn't reflow the page under the
+pointer.
+
+`<button shellSidebarToggle>` works anywhere and keeps `aria-expanded`, `aria-controls` and its
+label in sync with the mode.
+
+## 5. The breadcrumb row
+
+A row between the topbar and `main`, holding the trail on the start side and page-level actions
+on the end side:
+
+```
+Projects › Mobile app v3 › Settings   [subheader-start]  ········  Updated 2m ago · Share · [New issue] ⋯
+```
+
+**The trail comes from your routes.** Each route that consumes URL segments is one level. Its
+label comes from, in order:
+1. a page override
+2. the route's own `data.breadcrumb` (a string, or produced by `resolve: { breadcrumb }`)
+3. the route's own `title`
+
+`data: { breadcrumb: false }` skips a level, and empty-path routes never add one. Only what a
+route declares itself counts; values Angular passes down from a parent don't.
+
+```ts
+{ path: 'projects', data: { breadcrumb: 'Projects' }, children: [
+  { path: '', component: ProjectsPage },
+  { path: ':id', component: ProjectPage, children: [
+    { path: 'settings', title: 'Settings', component: ProjectSettings },
+  ]},
+]}
+```
+
+**The placeholder.** For names only the page knows, call `contributeBreadcrumbLabel(nameSignal)`
+in a routed component. It labels *that component's* level, including while a child tab is
+current.
+- While the signal is `undefined`, the crumb is a skeleton and the list is `aria-busy`.
+- The skeleton appears only after `skeletonDelay` (400ms), so fast labels never flash.
+- The row's height is reserved, so nothing moves when the name arrives.
+- Labels from resolvers are ready before the page renders and never need a placeholder.
+
+**When the row shows** (`subheader.enabled: 'auto'`):
+- when the page is at least two levels deep, or a page fills a subheader slot
+- `data: { subheader: true | false }` on a route forces it
+- the decision is made per navigation, so the row never appears or disappears within a page
+
+**The end side.**
+- `subheader-start` sits right after the trail; `subheader-end` holds actions.
+- `slotOverflow` on `subheader-end` moves actions into the row's own ⋯ menu.
+- Keep to one primary action and up to three secondary ones, and only actions that apply to the
+  whole page.
+
+**Narrow widths.** The trail measures its own width:
+1. the full trail; beyond `maxItems`, the middle levels fold into a "…" menu
+2. below `compactBelow`: first › … › parent › current
+3. below `backBelow`: a single "‹ Parent" link
+
+**Scrolling.**
+- With `scroll: 'main'` the row is pinned.
+- With `scroll: 'page'` it sticks under the topbar, unless `subheader.sticky` is `false`.
+- In `inset` it sits inside the card.
+
+`<shell-breadcrumb>` also works on its own, for example inside a page: `[items]`, `[display]`,
+`[maxItems]`, `[itemTemplate]`.
+
+## Slot map
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ ☰ topbar-start brand primary-nav title ··· search actions ⋯ account topbar-end│
+├──────────────────┬───────────────────────────────────────────────────────────┤
+│ sidebar-header   │ breadcrumb · subheader-start ·······  subheader-end  ⋯    │
+│ sidebar-action   ├───────────────────────────────────────────────────────────┤
+│ sidebar-search   │                    main  (<ng-content>)                   │
+│ sidebar-nav    ↕ │                                                           │
+│ sidebar-secondary│                                                           │
+│ sidebar-footer ‹ │                                                           │
+├──────────────────┴───────────────────────────────────────────────────────────┤
+│ footer-start                      footer                          footer-end │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+The sidebar slots follow what Linear, GitHub, Slack, Notion, Vercel, VS Code, Gmail, Jira and
+Shopify agree on:
+1. identity or workspace switcher
+2. one primary action
+3. quick find (usually a command-palette launcher)
+4. grouped, scrollable navigation — the only part that scrolls
+5. secondary links (settings, help, upgrade)
+6. the user card, sharing its row with the collapse control
+
+## Tokens
+
+The tokens are defined once as a Sass map. They're emitted as CSS custom properties (`@include shell.tokens`) **and**
+inlined as `var()` fallbacks, so the shell renders without any global stylesheet. You can override
+them anywhere in the cascade. `shell.dark-tokens($selector)` emits a dark palette.
+
+| group     | tokens |
+| --------- | ------ |
+| structure | `topbar-height` `topbar-padding-inline` `topbar-gap` `sidebar-width` `sidebar-collapsed-width` `sidebar-overlay-width` `sidebar-padding` `sidebar-gap` `footer-min-height` `main-padding` `main-max-width` |
+| colour    | `color-scheme` `surface` `surface-raised` `sidebar-surface` `topbar-surface` `fg` `fg-muted` `border` `hover-surface` `active-surface` `accent` `accent-fg` `accent-surface` `focus-ring` `scrim` `shadow-panel` |
+| shape     | `radius` `radius-sm` `nav-item-height` `nav-item-gap` `nav-icon-size` `font-family` `font-size` `font-size-sm` |
+| motion    | `transition-duration` `transition-easing` |
+| stacking  | `z-main` `z-topbar` `z-scrim` `z-sidebar` `z-flyout` `z-skip-link` |
+
+## Theming each part
+
+There are three layers, and each one overrides the layer below it:
+
+1. **Global tokens** — `--shell-surface`, `--shell-accent` and the rest of the table above.
+2. **Component tokens** — `--shell-<part>-<property>`. Each defaults to a global token, so you
+   only set what's different:
+
+   | part          | tokens |
+   | ------------- | ------ |
+   | shell         | `bg` (the container behind every part — shows around inset or transparent parts) |
+   | topbar        | `topbar-bg` `topbar-fg` `topbar-border-width` `topbar-border-style` `topbar-border-color` `topbar-radius` `topbar-shadow` `topbar-blur` |
+   | sidebar       | `sidebar-bg` `sidebar-fg` `sidebar-border-color` `sidebar-shadow` `sidebar-radius` `sidebar-inset` `sidebar-peek-shadow` |
+   | drawer        | `drawer-bg` `drawer-shadow` `drawer-radius` `drawer-scrim` `drawer-scrim-blur` |
+   | nav           | `nav-item-fg` `nav-item-hover-bg` `nav-item-active-bg` `nav-item-active-fg` `nav-item-radius` `nav-indicator-color` `nav-indicator-size` `nav-heading-fg` `nav-heading-size` |
+   | ⋯ menu        | `menu-bg` `menu-border-color` `menu-shadow` `menu-radius` |
+   | main          | `main-bg` `main-fg` `main-border-width` `main-border-style` `main-border-color` `main-radius` `main-shadow` `main-margin` |
+   | footer        | `footer-bg` `footer-fg` `footer-border-color` `footer-shadow` `footer-font-size` |
+   | frame (`inset` card) | `frame-bg` `frame-border-width` `frame-border-style` `frame-border-color` `frame-radius` `frame-shadow` `frame-inset` |
+   | subheader (breadcrumb row) | `subheader-height` (a minimum) `subheader-bg` `subheader-fg` `subheader-border-width` `subheader-border-style` `subheader-border-color` `subheader-radius` `subheader-margin` `subheader-padding-inline` `subheader-shadow` `subheader-font-size` |
+   | breadcrumb    | `breadcrumb-fg` `breadcrumb-hover-fg` `breadcrumb-hover-bg` `breadcrumb-current-fg` `breadcrumb-current-weight` `breadcrumb-separator-color` `breadcrumb-gap` `breadcrumb-font-size` `breadcrumb-label-max` `breadcrumb-skeleton-bg` |
+
+   ```scss
+   :root {
+     --shell-topbar-bg: #0b1020;
+     --shell-topbar-fg: #f5f6fa;
+     --shell-sidebar-shadow: 0 10px 30px -12px rgb(0 0 0 / 30%);
+     --shell-drawer-duration: 260ms;
+
+     /* Border tokens take the CSS shorthand: 1–4 values, top right bottom left. */
+     --shell-topbar-border-width: 0 0 2px;   /* bottom only (the default is 0 0 1px) */
+     --shell-topbar-border-color: #6366f1;
+     --shell-main-border-width: 1px;         /* all four sides */
+     --shell-main-border-color: #e4e4e7;
+     --shell-main-radius: 12px;
+     --shell-main-margin: 0 8px 8px 0;       /* inset "card" look */
+     --shell-topbar-radius: 0 0 12px 12px;   /* bottom corners only */
+     --shell-bg: #eef0f4;                    /* behind everything, shows around the card */
+
+     /* Breadcrumb row as an inset pill, with a bolder current page. */
+     --shell-subheader-margin: 8px 8px 0;
+     --shell-subheader-radius: 10px;
+     --shell-subheader-border-width: 1px;
+     --shell-breadcrumb-current-fg: #4f46e5;
+     --shell-breadcrumb-current-weight: 700;
+   }
+   ```
+
+   Give them concrete values. Don't alias them on `:root`, as in
+   `--shell-topbar-bg: var(--shell-surface)`. An alias is resolved where it's declared, so it
+   would stop following theme changes made lower in the page. The shell keeps its own fallbacks
+   inside each component for exactly this reason.
+3. **Presets** — the `appearance` config picks a look for each part. Presets only change the
+   tokens' *defaults*, so a component token always wins.
+
+### Motion per part
+
+- **Timing:** `--shell-<scope>-duration` and `--shell-<scope>-easing`. Each falls back to
+  `--shell-transition-duration` / `-easing`. The scopes are:
+  - `topbar`, `sidebar`, `footer`
+  - `collapse` (rail ⇄ panel)
+  - `drawer` (drawer and scrim)
+  - `nav` and `nav-expand`
+  - `menu`
+  - `subheader` (breadcrumb row and trail)
+- **Kind and on/off:** the `motion` config.
+- **One multiplier:** every duration is multiplied by `--shell-motion-scale`. That's `1 / speed`,
+  or 0 when `motion.enabled` is false, so the switch also covers durations you set yourself.
+  `prefers-reduced-motion` still wins.
+
+```ts
+provideAppShell({
+  appearance: { topbar: 'elevated', sidebar: 'floating', navIndicator: 'bar' },
+  motion: { drawer: 'fade', overflowMenu: 'scale', speed: 1.5, navExpand: false },
+});
+```
+
+The scrim and the ⋯ menu stay in the page and toggle `data-open`, so they animate out as well as
+in. This is plain CSS, with no animation library.
+
+## Configuration
+
+`provideAppShell(config, { behavior })` at startup; `ShellStore.configure(patch)` at runtime.
+
+| key                        | default                            | notes                                          |
+| -------------------------- | ---------------------------------- | ---------------------------------------------- |
+| `layout`                   | `topbar-full`                      | `sidebar-full`, `stacked`, `inset` (card)      |
+| `scroll`                   | `main`                             | `page` makes the document scroll               |
+| `scrollTopOnNavigate`      | `true`                             | resets `main` scroll after navigation          |
+| `initialSize`              | `lg`                               | assumed before the first measurement and on SSR |
+| `breakpoints`              | see above                          | container widths                               |
+| `topbar.enabled`           | `true`                             |                                                |
+| `topbar.sidebarToggle`     | `always`                           | `auto` = only for drawer/hidden, `never`       |
+| `footer.enabled`           | `false`                            | the footer also shows when a footer slot is filled |
+| `sidebar.collapseBelow`    | `lg`                               | rail below this size                           |
+| `sidebar.overlayBelow`     | `md`                               | drawer below this size                         |
+| `sidebar.peek`/`peekDelay` | `true` / `180`                     | hover/focus widens the rail                    |
+| `sidebar.closeOnNavigate`  | `true`                             | drawer closes on `NavigationEnd`               |
+| `sidebar.resizable`        | `false`                            | drag or keyboard; `minWidth`/`maxWidth`; double-click resets |
+| `sidebar.toggleShortcut`   | `null`                             | e.g. `'b'` → Ctrl/⌘+B, ignored while typing    |
+| `sidebar.persist`          | `true`                             | intent + width under `<storageKey>.intent/.width` |
+| `appearance.topbar`        | `solid`                            | `elevated`, `blur`, `transparent` (blur/transparent need `scroll: 'page'`) |
+| `appearance.sidebar`       | `solid`                            | `floating`, `borderless`                       |
+| `appearance.footer`        | `solid`                            | `minimal`                                      |
+| `appearance.navIndicator`  | `pill`                             | `bar`, `none`                                  |
+| `appearance.subheader`     | `solid`                            | `transparent` (blends into the page), `elevated` (shadow instead of the rule) |
+| `motion.enabled` / `speed` | `true` / `1`                       | master switch; 2 = twice as fast               |
+| `motion.drawer`            | `slide`                            | `fade`, `scale`, `none`                        |
+| `motion.overflowMenu`      | `fade`                             | `scale`, `slide`, `none`                       |
+| `motion.scrim`             | `fade`                             | `none`                                         |
+| `motion.collapse`          | `true`                             | animate rail ⇄ panel                           |
+| `motion.navExpand`         | `true`                             | animate nav sections                           |
+| `subheader.enabled`        | `'auto'`                           | `true` / `false` force it; auto = at least two levels deep, or a filled subheader slot |
+| `subheader.sticky`         | `true`                             | stick under the topbar with `scroll: 'page'`   |
+| `subheader.overflowSlots`  | `subheader-end`                    | slots the row's ⋯ menu serves                  |
+| `breadcrumbs.includeHome` / `homeLabel` / `homeUrl` | `false` / `Home` / `/` | prepend a home crumb               |
+| `breadcrumbs.includeCurrent` | `true`                           | `false` ends the trail at the parent           |
+| `breadcrumbs.maxItems`     | `4`                                | beyond it, the middle folds into "…"           |
+| `breadcrumbs.separator`    | `chevron`                          | `slash`, `dot` — always skipped by screen readers |
+| `breadcrumbs.compactBelow` / `backBelow` | `480` / `280`        | px of the trail's own width                    |
+| `breadcrumbs.useRouteTitle` / `skeletonDelay` | `true` / `400`  | title fallback; placeholder delay in ms        |
+| `overflowSlots`            | `primary-nav`, `search`, `actions` | slots the topbar's ⋯ menu serves               |
+| `labels.*`                 | English                            | every string the shell renders                 |
+
+Per-instance overrides: `<app-shell layout="sidebar-full" scroll="page" footer>`.
+
+## `ShellStore` (root, inject anywhere)
+
+`size()`, `shellWidth()`, `sidebar()`, `sidebarIntent()`, `sidebarWidth()`, `config()`,
+`behavior()` · `toggleSidebar()`, `openSidebar()`, `closeSidebar()`, `setSidebarIntent()`,
+`setSidebarWidth(px | null)`, `configure(patch)`, `setBehavior(behavior)`.
+
+## Accessibility
+
+- A skip link focuses `main`; it doesn't navigate, so it can't trigger the router.
+- Landmarks: `role="banner"` on the topbar, `<nav aria-label>` in the sidebar, `main`, and
+  `role="contentinfo"` on the footer.
+- The drawer is `role="dialog" aria-modal="true"`. It traps focus, restores focus on close, and
+  closes on Escape, a scrim click or navigation. The page behind it can't scroll.
+- A closed drawer and collapsed nav children are `inert`.
+- Rail items keep a visually hidden label and a tooltip.
+- The breadcrumb follows the WAI-ARIA pattern:
+  - a `<nav aria-label="Breadcrumb">` containing an ordered list
+  - the current page is text with `aria-current="page"`
+  - the separators are CSS, so screen readers don't read them
+  - the row sits before `main`, so the skip link jumps past it
+- The resize handle is a `role="separator"` with arrow keys, Home and End.
+- `prefers-reduced-motion` is respected, and the layout supports RTL via logical properties.
+- SSR-safe: `localStorage` sits behind a swappable port, and unmeasured regions render at
+  `initialSize`.
+
+## Limits
+
+- **One shell per application.** The store, the registries and the element ids are app-wide
+  singletons.
+- **Topbar fitting uses the sizes you declare; it doesn't measure content.** The topbar doesn't
+  measure each item's width, so unexpectedly long content (translations, many links) can clip.
+  There's no "fit as many as possible" algorithm.
+- **Overflow moves whole templates.** For per-link overflow, use one template per link. The
+  template must style its own overflow version (`let-overflow`). The ⋯ panel is a simple
+  show/hide panel, not an ARIA menu with arrow-key navigation.
+- **Contributions add, they never replace.** A page can't hide the app's contribution to the same
+  slot. `slotOrder` numbers are global, so features must agree on them.
+- **Components in a slot template resolve dependencies from where the template is written, not
+  where it's rendered.** `inject(SHELL_REGION)` inside a slot template doesn't return the topbar.
+  Use `let-region`.
+- **Nav contributions only land in groups with a matching `id`.** Lazy-route providers only run
+  after the route has loaded. With `itemTemplate`, the template handles the rail case (`labels`
+  false).
+- **Group and section open state isn't persisted.** Active-section detection treats string routes
+  as absolute paths.
+- **Breadcrumbs follow the primary router outlet only.** Call `contributeBreadcrumbLabel()` from
+  a routed component: it labels that component's route level.
+- **Server-side rendering can shift the layout.** Regions render at `initialSize` until the
+  browser measures them.
+
+## Requirements
+
+Angular ≥ 19 (`linkedSignal`, `@let`, signal inputs, `provideEnvironmentInitializer`). The
+router is a peer dependency, injected optionally.
+
+## License
+
+MIT © Danjel Peqini