@danjelp/ngx-app-shell 1.0.0

package/types/danjelp-ngx-app-shell.d.ts

@@ -0,0 +1,1210 @@
+import * as _angular_core from '@angular/core';
+import { Signal, InjectionToken, EnvironmentProviders, ElementRef, TemplateRef } from '@angular/core';
+import * as _danjelp_ngx_app_shell from '@danjelp/ngx-app-shell';
+import { ActivatedRoute } from '@angular/router';
+
+/** Ordered size buckets. Order matters: `sizeRank()` relies on the index. */
+declare const SHELL_SIZES: readonly ["xs", "sm", "md", "lg", "xl"];
+type ShellSize = (typeof SHELL_SIZES)[number];
+/** Minimum *container* width (px) at which each bucket starts. */
+type ShellBreakpoints = Readonly<Record<ShellSize, number>>;
+/**
+ * `topbar-full`  – topbar spans the full width, sidebar starts below it.
+ * `sidebar-full` – sidebar spans the full height, topbar starts next to it.
+ * `stacked`      – topbar *and* footer span the full width, sidebar sits between.
+ * `inset`        – topbar, main and footer share one rounded card; the sidebar
+ *                  sits directly on the shell background.
+ */
+type ShellLayout = 'topbar-full' | 'sidebar-full' | 'stacked' | 'inset';
+/**
+ * `main` = app-like, only the content area scrolls.
+ * `page` = the document scrolls — or, in the `inset` layout, the card itself
+ * scrolls with the topbar sticky at its top.
+ */
+type ShellScrollMode = 'main' | 'page';
+/** What the sidebar currently *is*. Derived state, never set directly. */
+type SidebarMode = 'expanded' | 'collapsed' | 'overlay' | 'hidden';
+/**
+ * What the user *asked for* on a screen wide enough for a persistent sidebar.
+ * `auto` hands the decision back to the behaviour. The drawer's open/closed
+ * state is deliberately not an intent: it is transient and never persisted.
+ */
+type SidebarIntent = 'auto' | 'expanded' | 'collapsed' | 'hidden';
+/**
+ * When the topbar renders its built-in sidebar toggle.
+ * `auto` = only when the sidebar cannot be reached otherwise (drawer or hidden).
+ */
+type SidebarToggleVisibility = 'always' | 'auto' | 'never';
+/** Fully resolved sidebar state — the single source of truth for template + CSS. */
+interface SidebarState {
+    readonly mode: SidebarMode;
+    /** Is the panel visible at all (open drawer, or an in-flow rail/panel)? */
+    readonly open: boolean;
+    /** Does it trap focus and need a scrim? True for the open overlay drawer. */
+    readonly modal: boolean;
+    /** Should item labels / group headings render? False on an icon rail. */
+    readonly labels: boolean;
+    /** Collapsed rail temporarily widened by hover/focus peek. */
+    readonly peeked: boolean;
+    /** Width reserved in the shell grid. `0px` when the panel floats over content. */
+    readonly trackWidth: string;
+    /** Width of the panel element itself. */
+    readonly panelWidth: string;
+}
+/**
+ * Slot names the built-in regions render. Extra names are allowed — the
+ * `(string & {})` member keeps autocompletion for the known ones while letting
+ * you invent your own and render them with `<shell-slot-outlet>`.
+ */
+type ShellSlotName = 'topbar-start' | 'brand' | 'primary-nav' | 'title' | 'search' | 'actions' | 'account' | 'topbar-end' | 'sidebar-header' | 'sidebar-action' | 'sidebar-search' | 'sidebar-nav' | 'sidebar-secondary' | 'sidebar-footer' | 'breadcrumb' | 'subheader-start' | 'subheader-end' | 'footer-start' | 'footer' | 'footer-end' | (string & {});
+/** Imperative surface handed to slot templates and to `[shellSidebarToggle]`. */
+interface ShellApi {
+    readonly size: Signal<ShellSize>;
+    readonly sidebar: Signal<SidebarState>;
+    readonly sidebarIntent: Signal<SidebarIntent>;
+    toggleSidebar(): void;
+    openSidebar(): void;
+    closeSidebar(): void;
+    setSidebarIntent(intent: SidebarIntent): void;
+}
+/** `let-` context available inside every `<ng-template shellSlot="…">`. */
+interface ShellSlotContext {
+    /** `let-sidebar` / `let-x` — resolved sidebar state. */
+    readonly $implicit: SidebarState;
+    readonly sidebar: SidebarState;
+    /** Size bucket of the whole shell. */
+    readonly size: ShellSize;
+    /** Size bucket of the region rendering this slot (topbar, sidebar, footer…). */
+    readonly region: ShellSize;
+    /** True when rendered inside a ⋯ overflow menu (topbar or breadcrumb row). */
+    readonly overflow: boolean;
+    readonly shell: ShellApi;
+}
+
+/** Everything a behaviour is allowed to look at. Pure in, pure out. */
+interface SidebarContext {
+    /** Measured width of the shell in px, or `null` before the first measurement. */
+    readonly width: number | null;
+    /** Resolved size bucket of the shell container. */
+    readonly size: ShellSize;
+    /** The user's persistent preference for wide screens. */
+    readonly intent: SidebarIntent;
+    /** Transient open state, meaningful only when the behaviour resolves a drawer. */
+    readonly drawerOpen: boolean;
+    /** Pointer/focus is dwelling on the collapsed rail. */
+    readonly peeking: boolean;
+    readonly config: ShellConfig;
+}
+/**
+ * The collapse policy, isolated behind one interface so an app can change how
+ * the sidebar behaves without forking the layout. Swap it with
+ * `provideAppShell(config, { behavior })` or at runtime with
+ * `ShellStore.setBehavior()`.
+ *
+ * `resolve` must be a pure function of the context: it runs inside a `computed`.
+ * Build the returned state with `drawerState`, `railState`, `panelState` and
+ * `hiddenState` so every behaviour produces consistent widths and flags.
+ */
+interface SidebarBehavior {
+    resolve(context: SidebarContext): SidebarState;
+    /**
+     * Intent produced by activating a toggle while the sidebar is *not* a drawer
+     * (drawers simply open/close). Default: expanded ⇄ collapsed.
+     */
+    nextIntent?(context: SidebarContext): SidebarIntent;
+    /** Should this intent survive a reload? Default: yes. */
+    persistIntent?(intent: SidebarIntent, context: SidebarContext): boolean;
+}
+declare const SIDEBAR_BEHAVIOR: InjectionToken<SidebarBehavior>;
+
+/**
+ * Topbar look. `elevated` trades the border for a shadow; `blur` and
+ * `transparent` only show through when content scrolls under the bar
+ * (`scroll: 'page'`).
+ */
+type TopbarAppearance = 'solid' | 'elevated' | 'blur' | 'transparent';
+/** `floating` insets the panel as a rounded, shadowed card inside its track. */
+type SidebarAppearance = 'solid' | 'floating' | 'borderless';
+type FooterAppearance = 'solid' | 'minimal';
+/** How the active nav item is marked. `none` = accent text only. */
+type NavIndicator = 'pill' | 'bar' | 'none';
+type DrawerMotion = 'slide' | 'fade' | 'scale' | 'none';
+type MenuMotion = 'fade' | 'scale' | 'slide' | 'none';
+type ScrimMotion = 'fade' | 'none';
+/** `auto` = follow the page (see `ShellSubheaderConfig.enabled`); booleans force it. */
+type SubheaderVisibility = 'auto' | boolean;
+/** Breadcrumb row look. `transparent` blends into the page; `elevated` trades the rule for a shadow. */
+type SubheaderAppearance = 'solid' | 'transparent' | 'elevated';
+/** Glyph between breadcrumb levels. Always decorative: screen readers skip it. */
+type BreadcrumbSeparator = 'chevron' | 'slash' | 'dot';
+interface ShellSidebarConfig {
+    /** Width of the expanded panel. Any CSS length. */
+    readonly width: string;
+    /** Width of the icon rail. */
+    readonly collapsedWidth: string;
+    /** Width of the off-canvas drawer. */
+    readonly overlayWidth: string;
+    /** Starting intent. `auto` = let the behaviour decide from available space. */
+    readonly intent: SidebarIntent;
+    /** Below this bucket the panel collapses to a rail. */
+    readonly collapseBelow: ShellSize;
+    /** Below this bucket the panel becomes a modal drawer. */
+    readonly overlayBelow: ShellSize;
+    /** Widen the rail on hover/focus instead of showing flyouts. */
+    readonly peek: boolean;
+    /** Dwell time (ms) before a hover peeks the rail open. */
+    readonly peekDelay: number;
+    /** Close the drawer after a router navigation. */
+    readonly closeOnNavigate: boolean;
+    /** Let the user drag the expanded panel's edge to resize it. */
+    readonly resizable: boolean;
+    /** Resize bounds in px. */
+    readonly minWidth: number;
+    readonly maxWidth: number;
+    /**
+     * Key that toggles the sidebar together with Ctrl (Windows/Linux) or ⌘ (macOS),
+     * e.g. `'b'` for the VS Code style Ctrl+B. `null` disables the shortcut.
+     */
+    readonly toggleShortcut: string | null;
+    /** Remember the user's intent and custom width across reloads. */
+    readonly persist: boolean;
+    /** Prefix for persisted keys: `<storageKey>.intent`, `<storageKey>.width`. */
+    readonly storageKey: string;
+}
+interface ShellTopbarConfig {
+    readonly enabled: boolean;
+    readonly sidebarToggle: SidebarToggleVisibility;
+}
+interface ShellFooterConfig {
+    /** Render the footer even when no footer slot is filled. */
+    readonly enabled: boolean;
+}
+/**
+ * Look presets per part. Each preset only changes the *defaults* of that
+ * part's component tokens, so `--shell-topbar-bg` & co. always win.
+ */
+interface ShellAppearanceConfig {
+    readonly topbar: TopbarAppearance;
+    readonly sidebar: SidebarAppearance;
+    readonly footer: FooterAppearance;
+    readonly navIndicator: NavIndicator;
+    readonly subheader: SubheaderAppearance;
+}
+/**
+ * Which animations run and how. Timing per part lives in CSS
+ * (`--shell-drawer-duration`, `--shell-collapse-easing` …); this chooses the
+ * *kind*. `prefers-reduced-motion` is always respected on top.
+ */
+interface ShellMotionConfig {
+    /** Master switch. `false` makes every shell transition instant. */
+    readonly enabled: boolean;
+    /** Speed multiplier for every duration: 2 = twice as fast, 0.5 = half speed. */
+    readonly speed: number;
+    readonly drawer: DrawerMotion;
+    readonly overflowMenu: MenuMotion;
+    readonly scrim: ScrimMotion;
+    /** Animate rail ⇄ panel (grid track, panel width, peek). */
+    readonly collapse: boolean;
+    /** Animate nav sections opening and closing. */
+    readonly navExpand: boolean;
+}
+/** The breadcrumb row between the topbar and `main`. */
+interface ShellSubheaderConfig {
+    /**
+     * `'auto'`: shown when the trail is at least two levels deep or a subheader
+     * slot is filled; a route's `data: { subheader }` overrides. Booleans force it.
+     */
+    readonly enabled: SubheaderVisibility;
+    /** With `scroll: 'page'`, stick under the topbar instead of scrolling away. */
+    readonly sticky: boolean;
+    /** Slot names the row may push into its own ⋯ menu, in that order. */
+    readonly overflowSlots: readonly string[];
+}
+/** How `ShellBreadcrumbStore` builds the trail and `<shell-breadcrumb>` shows it. */
+interface ShellBreadcrumbsConfig {
+    /** Prepend a home crumb (unless the trail already starts there). */
+    readonly includeHome: boolean;
+    readonly homeLabel: string;
+    readonly homeUrl: string;
+    /** Show the current page as the last item (NN/g); `false` ends at the parent (GOV.UK). */
+    readonly includeCurrent: boolean;
+    /** Beyond this many items the middle levels fold into "…". Minimum 2. */
+    readonly maxItems: number;
+    /** Label levels without `data.breadcrumb` by their route `title`. */
+    readonly useRouteTitle: boolean;
+    /** Below this width (px, of the trail itself): first › … › parent › current. */
+    readonly compactBelow: number;
+    /** Below this width (px): a single "‹ Parent" link. */
+    readonly backBelow: number;
+    /** A pending label only shows its skeleton after this many ms. */
+    readonly skeletonDelay: number;
+    readonly separator: BreadcrumbSeparator;
+}
+interface ShellLabels {
+    readonly skipToContent: string;
+    readonly openNavigation: string;
+    readonly closeNavigation: string;
+    readonly expandSidebar: string;
+    readonly collapseSidebar: string;
+    readonly resizeSidebar: string;
+    readonly moreActions: string;
+    readonly primaryNavigation: string;
+    readonly breadcrumb: string;
+    readonly showPath: string;
+    readonly back: string;
+    readonly loading: string;
+}
+interface ShellConfig {
+    readonly layout: ShellLayout;
+    readonly scroll: ShellScrollMode;
+    /**
+     * With `scroll: 'main'` the router cannot restore scroll (the window never
+     * scrolls), so the shell scrolls `main` back to the top after navigation.
+     */
+    readonly scrollTopOnNavigate: boolean;
+    /** Bucket assumed before the first measurement (and on the server). */
+    readonly initialSize: ShellSize;
+    readonly breakpoints: ShellBreakpoints;
+    readonly sidebar: ShellSidebarConfig;
+    readonly topbar: ShellTopbarConfig;
+    readonly footer: ShellFooterConfig;
+    readonly appearance: ShellAppearanceConfig;
+    readonly motion: ShellMotionConfig;
+    readonly subheader: ShellSubheaderConfig;
+    readonly breadcrumbs: ShellBreadcrumbsConfig;
+    /** Slot names the topbar may push into its overflow menu, in that order. */
+    readonly overflowSlots: readonly string[];
+    readonly labels: ShellLabels;
+}
+declare const DEFAULT_SHELL_CONFIG: ShellConfig;
+/** Configuration as provided by the app (`provideAppShell`). */
+declare const SHELL_CONFIG: InjectionToken<ShellConfig>;
+/**
+ * Two levels deep is all the config tree needs — which keeps the merge honest
+ * and the type readable. Arrays and primitives are replaced wholesale; nested
+ * option objects are merged key by key.
+ */
+type ShellConfigInput = {
+    readonly [K in keyof ShellConfig]?: ShellConfig[K] extends readonly unknown[] ? ShellConfig[K] : ShellConfig[K] extends object ? Partial<ShellConfig[K]> : ShellConfig[K];
+};
+/** Merge `input` over `base` (the defaults unless given). Never mutates. */
+declare function mergeShellConfig(input?: ShellConfigInput, base?: ShellConfig): ShellConfig;
+/**
+ * Register the shell once, in `app.config.ts`:
+ *
+ * ```ts
+ * provideAppShell({ layout: 'sidebar-full', sidebar: { collapseBelow: 'xl' } })
+ * ```
+ *
+ * Pass `behavior` to replace the collapse policy wholesale. Both can also be
+ * changed at runtime through `ShellStore.configure()` / `setBehavior()`.
+ */
+declare function provideAppShell(config?: ShellConfigInput, options?: {
+    readonly behavior?: SidebarBehavior;
+}): EnvironmentProviders;
+
+/** Minimal persistence port so the shell never touches `localStorage` directly. */
+interface ShellStateStorage {
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+}
+declare function localShellStateStorage(): ShellStateStorage;
+declare const SHELL_STATE_STORAGE: InjectionToken<ShellStateStorage>;
+
+/**
+ * Stable element ids. The shell assumes one instance per application, which
+ * lets `aria-controls` work from a toggle rendered anywhere in the tree.
+ */
+declare const SHELL_SIDEBAR_ID = "shell-sidebar";
+declare const SHELL_MAIN_ID = "shell-main";
+
+/**
+ * Single source of truth for the shell.
+ *
+ * Root-provided on purpose: any component in the app — including lazily loaded
+ * pages and content projected into `<app-shell>` — can inject it and drive the
+ * sidebar without input/output plumbing. One shell per application.
+ *
+ * Everything is derived from four inputs: the measured shell width, the user's
+ * intent, the transient drawer/peek flags, and the (runtime-changeable)
+ * config + behaviour.
+ */
+declare class ShellStore implements ShellApi {
+    private readonly storage;
+    private readonly baseConfig;
+    private readonly behaviorState;
+    /** Measured shell width; `null` until the first ResizeObserver callback. */
+    private readonly width;
+    private readonly intent;
+    /** User-dragged panel width in px; `null` = use the configured width. */
+    private readonly customWidth;
+    private readonly peekRequested;
+    private readonly resizingState;
+    private peekTimer;
+    /** Size bucket of the shell container — not of the viewport. */
+    readonly size: Signal<ShellSize>;
+    /**
+     * Drawer open state. Transient by design: it is never persisted, and any
+     * change of size bucket closes it, so rotating a phone or resizing a window
+     * never leaves a modal drawer stranded open.
+     */
+    private readonly drawerOpen;
+    /** Effective configuration: app config, runtime patches and the user's width. */
+    readonly config: Signal<ShellConfig>;
+    readonly behavior: Signal<SidebarBehavior>;
+    readonly shellWidth: Signal<number | null>;
+    readonly sidebarIntent: Signal<SidebarIntent>;
+    readonly sidebarWidth: Signal<number | null>;
+    readonly resizing: Signal<boolean>;
+    readonly sidebar: Signal<SidebarState>;
+    /** Patch the configuration at runtime, e.g. from a settings screen. */
+    configure(patch: ShellConfigInput): void;
+    /** Swap the collapse policy at runtime. */
+    setBehavior(behavior: SidebarBehavior): void;
+    /** Called by `<app-shell>` with its measured width. */
+    setWidth(width: number | null): void;
+    setSidebarIntent(intent: SidebarIntent): void;
+    /**
+     * Overlay drawers toggle open/closed; persistent panels ask the behaviour
+     * for the next intent (by default: expanded ⇄ collapsed).
+     */
+    toggleSidebar(): void;
+    openSidebar(): void;
+    closeSidebar(): void;
+    /**
+     * Set the expanded panel width in px (clamped to `minWidth`/`maxWidth`), or
+     * `null` to return to the configured width. Pass `{ persist: false }` for
+     * intermediate values, e.g. while a drag is still in progress.
+     */
+    setSidebarWidth(width: number | null, options?: {
+        readonly persist?: boolean;
+    }): void;
+    /** Suspends layout transitions while a resize drag is in progress. */
+    setResizing(resizing: boolean): void;
+    /** Hover/focus peek on the collapsed rail, debounced by `sidebar.peekDelay`. */
+    requestPeek(peeking: boolean): void;
+    private context;
+    private persistIntent;
+    private write;
+    private read;
+    private restoreIntent;
+    private restoreWidth;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellStore, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ShellStore>;
+}
+
+/**
+ * Building blocks for `SidebarBehavior.resolve`. Each returns a complete,
+ * internally consistent state, so a custom behaviour only decides *which* mode
+ * applies — never how wide the track is or whether a scrim is needed.
+ */
+/** Off-canvas modal drawer. Reserves no grid track. */
+declare function drawerState(open: boolean, sidebar: ShellSidebarConfig): SidebarState;
+/** Icon rail. While peeking the panel floats wider but the track stays put. */
+declare function railState(peeking: boolean, sidebar: ShellSidebarConfig): SidebarState;
+/** Full in-flow panel with labels. */
+declare function panelState(sidebar: ShellSidebarConfig): SidebarState;
+/** Not rendered, zero-width track. */
+declare function hiddenState(): SidebarState;
+
+/**
+ * Default policy.
+ *
+ *   size < overlayBelow   → modal drawer, closed until opened
+ *   size < collapseBelow  → icon rail, widened while peeking
+ *   otherwise             → full panel
+ *
+ * An explicit intent (`expanded`, `collapsed`, `hidden`) wins over the
+ * automatic choice, except in drawer territory where there is no room for a
+ * persistent panel. Set the intent back to `auto` to follow breakpoints again.
+ */
+declare const responsiveSidebarBehavior: SidebarBehavior;
+
+/**
+ * The sidebar never collapses on its own. Whatever the user last chose is what
+ * they get at every desktop size (`auto` means expanded); only drawer
+ * territory overrides it.
+ *
+ * ```ts
+ * provideAppShell({}, { behavior: manualSidebarBehavior });
+ * ```
+ */
+declare const manualSidebarBehavior: SidebarBehavior;
+
+/**
+ * Content-first policy: the sidebar is always an off-canvas drawer, at every
+ * size. Suits editors, media players and dashboards that want the full width.
+ */
+declare const drawerSidebarBehavior: SidebarBehavior;
+
+/**
+ * Container-first breakpoints. Deliberately *not* device widths: they describe
+ * the space a region has, which is what layout decisions should react to.
+ */
+declare const DEFAULT_BREAKPOINTS: ShellBreakpoints;
+declare function sizeRank(size: ShellSize): number;
+/** Largest bucket whose minimum width is still <= `width`. */
+declare function resolveSize(width: number, breakpoints: ShellBreakpoints): ShellSize;
+/** `atLeast('md', 'sm')` → true */
+declare function atLeast(size: ShellSize, min: ShellSize): boolean;
+/** `atMost('md', 'lg')` → true */
+declare function atMost(size: ShellSize, max: ShellSize): boolean;
+/** Strictly narrower than `bound` — used for "collapse below md" style rules. */
+declare function isBelow(size: ShellSize, bound: ShellSize): boolean;
+
+type WidthTarget = ElementRef<HTMLElement> | Signal<ElementRef<HTMLElement> | undefined>;
+/**
+ * Tracks the inline size of an element as a signal.
+ *
+ * Accepts a plain `ElementRef` (host element) or a `viewChild` signal, in which
+ * case the observer follows the element as it appears, changes or is removed.
+ *
+ * Must be called from an injection context. SSR safe: with no `ResizeObserver`
+ * the signal simply stays `null`, which callers read as "not measured yet" and
+ * fall back to `config.initialSize` — so the server renders the desktop layout
+ * instead of flashing the mobile one.
+ */
+declare function observeWidth(target: WidthTarget): Signal<number | null>;
+
+interface MeasuredRegion {
+    /** Measured inline size in px, `null` until measured. */
+    readonly width: Signal<number | null>;
+    /** Bucket for that width under the shell's current breakpoints. */
+    readonly size: Signal<ShellSize>;
+}
+/**
+ * Measure an element and bucket its width with the shell's breakpoints.
+ * Before the first measurement (and on the server) the bucket is
+ * `config.initialSize`. Call from an injection context.
+ */
+declare function measureRegion(target: WidthTarget): MeasuredRegion;
+
+/**
+ * The size bucket of the nearest enclosing region (topbar, sidebar, drawer,
+ * main). Regions provide this so slot outlets and consumer templates react to
+ * *their own* available space rather than to the viewport.
+ */
+interface ShellRegion {
+    readonly regionName: string;
+    readonly regionSize: Signal<ShellSize>;
+    readonly regionWidth: Signal<number | null>;
+}
+declare const SHELL_REGION: InjectionToken<ShellRegion>;
+
+/**
+ * Turns any element into a measured container.
+ *
+ * ```html
+ * <div shellContainerSize #box="shellContainerSize">
+ *   @if (box.atLeast('md')) { <app-filters /> }
+ *   <span>{{ box.size() }}</span>
+ * </div>
+ * ```
+ *
+ * Also mirrors the bucket onto the host as `data-shell-size` and the raw width
+ * as `--shell-container-width`, and makes the host a CSS query container, so
+ * plain CSS can react without a media query:
+ *
+ * ```scss
+ * [data-shell-size='xs'] .toolbar__label { display: none; }
+ * ```
+ *
+ * Provides itself as the enclosing `SHELL_REGION`, so nested slot outlets pick
+ * the nearest measured ancestor.
+ */
+declare class ContainerSizeDirective implements ShellRegion {
+    /** Optional name, purely for debugging: `shellContainerSize="toolbar"`. */
+    readonly label: _angular_core.InputSignal<string>;
+    private readonly region;
+    readonly regionWidth: Signal<number | null>;
+    readonly size: Signal<ShellSize>;
+    readonly regionSize: Signal<ShellSize>;
+    protected readonly cssWidth: Signal<string | null>;
+    get regionName(): string;
+    atLeast(min: ShellSize): boolean;
+    atMost(max: ShellSize): boolean;
+    below(bound: ShellSize): boolean;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ContainerSizeDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ContainerSizeDirective, "[shellContainerSize]", ["shellContainerSize"], { "label": { "alias": "shellContainerSize"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Declares a piece of shell chrome.
+ *
+ * ```html
+ * <ng-template shellSlot="search" slotMinSize="md" slotOverflow>
+ *   <app-global-search />
+ * </ng-template>
+ * ```
+ *
+ * Templates register themselves with a root registry, so a slot can be
+ * contributed from anywhere — the app root, a routed page, a feature
+ * component — and it does not need to be a DOM child of `<app-shell>`.
+ * That is also what allows the same template to be rendered in the topbar on a
+ * wide screen and inside the overflow menu on a narrow one.
+ */
+declare class ShellSlotDirective {
+    /** Target slot. Unknown names are fine; render them with `<shell-slot-outlet>`. */
+    readonly name: _angular_core.InputSignal<ShellSlotName>;
+    /** Ascending render order within the slot. Contribute several templates freely. */
+    readonly order: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Render only when the *region* has at least this much room. */
+    readonly minSize: _angular_core.InputSignal<"xs" | "sm" | "md" | "lg" | "xl">;
+    /** Render only up to this region size — for narrow-only affordances. */
+    readonly maxSize: _angular_core.InputSignal<"xs" | "sm" | "md" | "lg" | "xl">;
+    /**
+     * When the region is too narrow, move the content into the overflow menu
+     * instead of dropping it. Off by default: dropping is the right answer for
+     * decorative chrome, moving is the right answer for actions. Only slots in
+     * `config.overflowSlots` have an overflow menu.
+     */
+    readonly overflow: _angular_core.InputSignalWithTransform<boolean, boolean | "">;
+    readonly template: TemplateRef<ShellSlotContext>;
+    private readonly registry;
+    constructor();
+    /** Type guard for `let-` context inference in the template. */
+    static ngTemplateContextGuard(_directive: ShellSlotDirective, _context: unknown): _context is ShellSlotContext;
+    /**
+     * `slotOverflow` on a slot the topbar never scans is silently ignored at
+     * runtime; say so during development. Inputs are only readable once bound,
+     * hence the effect. Config is read untracked so runtime `configure()` calls
+     * do not repeat the warning.
+     */
+    private warnOnUnsupportedOverflow;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellSlotDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ShellSlotDirective, "ng-template[shellSlot]", never, { "name": { "alias": "shellSlot"; "required": true; "isSignal": true; }; "order": { "alias": "slotOrder"; "required": false; "isSignal": true; }; "minSize": { "alias": "slotMinSize"; "required": false; "isSignal": true; }; "maxSize": { "alias": "slotMaxSize"; "required": false; "isSignal": true; }; "overflow": { "alias": "slotOverflow"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Reactive index of every registered slot template, keyed by name. */
+declare class ShellSlotRegistry {
+    private readonly slots;
+    private readonly byName;
+    register(slot: ShellSlotDirective): void;
+    unregister(slot: ShellSlotDirective): void;
+    /** All templates for a slot, ordered. Memoised per name. */
+    all(name: ShellSlotName): Signal<readonly ShellSlotDirective[]>;
+    /** Templates that fit the given region size. */
+    visible(name: ShellSlotName, size: ShellSize): readonly ShellSlotDirective[];
+    /** Templates that do not fit but asked to be kept via the overflow menu. */
+    overflowing(name: ShellSlotName, size: ShellSize): readonly ShellSlotDirective[];
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellSlotRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ShellSlotRegistry>;
+}
+
+/**
+ * Renders the templates registered for a slot.
+ *
+ * Size filtering uses the nearest measured region, falling back to the shell
+ * itself — which is why a topbar squeezed by a wide sidebar collapses its
+ * contents even though the window never changed.
+ */
+declare class ShellSlotOutletComponent {
+    readonly name: _angular_core.InputSignal<ShellSlotName>;
+    /** `visible` renders what fits; `overflow` renders what did not fit. */
+    readonly select: _angular_core.InputSignal<"visible" | "overflow">;
+    /** Overrides the measured region size. Mostly for tests. */
+    readonly size: _angular_core.InputSignal<"xs" | "sm" | "md" | "lg" | "xl" | null>;
+    private readonly registry;
+    private readonly store;
+    private readonly region;
+    private readonly effectiveSize;
+    readonly slots: Signal<readonly ShellSlotDirective[]>;
+    readonly context: Signal<ShellSlotContext>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellSlotOutletComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ShellSlotOutletComponent, "shell-slot-outlet", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; "select": { "alias": "select"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * `true` when at least one template is registered for a slot — lets a region
+ * skip its wrapper markup (and its padding) instead of rendering an empty box.
+ * Call from an injection context.
+ */
+declare function hasSlot(...names: readonly ShellSlotName[]): Signal<boolean>;
+
+/**
+ * The navigational shell: sidebar + topbar + breadcrumb row + main + footer.
+ *
+ * Layout is a CSS grid whose tracks come from custom properties, so a host app
+ * restyles it entirely from CSS. The only value TypeScript writes is the
+ * current sidebar track width, which is derived state, not layout maths.
+ */
+declare class AppShellComponent implements ShellRegion {
+    private readonly host;
+    private readonly document;
+    private readonly router;
+    private readonly breadcrumbs;
+    private readonly main;
+    private readonly frame;
+    protected readonly store: ShellStore;
+    protected readonly config: Signal<_danjelp_ngx_app_shell.ShellConfig>;
+    protected readonly mainId = "shell-main";
+    protected readonly sidebarId = "shell-sidebar";
+    /** Per-instance overrides. Leave unset to follow the (runtime) config. */
+    readonly layout: _angular_core.InputSignal<ShellLayout | undefined>;
+    readonly scroll: _angular_core.InputSignal<ShellScrollMode | undefined>;
+    readonly topbar: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
+    readonly subheader: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
+    readonly footer: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
+    readonly regionName = "shell";
+    readonly regionWidth: Signal<number | null>;
+    readonly regionSize: Signal<ShellSize>;
+    protected readonly size: Signal<"xs" | "sm" | "md" | "lg" | "xl">;
+    protected readonly sidebar: Signal<SidebarState>;
+    private readonly hasSubheaderSlots;
+    private readonly hasFooterSlots;
+    protected readonly resolvedLayout: Signal<ShellLayout>;
+    protected readonly resolvedScroll: Signal<ShellScrollMode>;
+    /** Topbar, main and footer share one rounded card; the sidebar sits on the shell. */
+    protected readonly inset: Signal<boolean>;
+    protected readonly showTopbar: Signal<boolean>;
+    protected readonly showFooter: Signal<boolean>;
+    /**
+     * The breadcrumb row. In `'auto'` it follows the page: a route's
+     * `data.subheader` wins; otherwise it shows when the trail is at least two
+     * levels deep (a flat trail is noise) or when a page fills a subheader slot.
+     * Decided per navigation, so it never appears or vanishes within a page.
+     */
+    protected readonly showSubheader: Signal<boolean>;
+    /**
+     * Factor every shell duration is multiplied by (see `duration()` in the
+     * token file): 0 turns motion off, 1 / speed scales it.
+     */
+    protected readonly motionScale: Signal<string>;
+    constructor();
+    /**
+     * The window does not scroll in these modes, so the router cannot restore
+     * scroll: `main` scrolls in `scroll: 'main'`, the card in `inset` + `page`.
+     */
+    private resetScroll;
+    /**
+     * A plain `href="#id"` would resolve against `<base href>` and trigger a
+     * router navigation, so the jump is done by moving focus instead.
+     */
+    protected skipToMain(event: Event): void;
+    /** Optional Ctrl/⌘ + key toggle, ignored while typing. */
+    protected onDocumentKeydown(event: KeyboardEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AppShellComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AppShellComponent, "app-shell", ["appShell"], { "layout": { "alias": "layout"; "required": false; "isSignal": true; }; "scroll": { "alias": "scroll"; "required": false; "isSignal": true; }; "topbar": { "alias": "topbar"; "required": false; "isSignal": true; }; "subheader": { "alias": "subheader"; "required": false; "isSignal": true; }; "footer": { "alias": "footer"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+/**
+ * Topbar with priority-based slot collapsing.
+ *
+ * The bar measures **itself**, not the window. That matters: expanding the
+ * sidebar from a rail to a full panel takes ~200px away from the topbar without
+ * the window ever resizing, and the bar has to respond to that the same way it
+ * responds to a phone.
+ *
+ * Slot order, start to end:
+ *
+ *   [toggle] [topbar-start] [brand] [primary-nav] [title] ····· [search] [actions] [⋯] [account] [topbar-end]
+ *
+ * Each slot template declares the room it needs (`slotMinSize` / `slotMaxSize`)
+ * and what happens when it does not get it (`slotOverflow` → move into the ⋯
+ * menu, otherwise drop).
+ */
+declare class ShellTopbarComponent implements ShellRegion {
+    private readonly registry;
+    private readonly region;
+    protected readonly store: ShellStore;
+    protected readonly config: Signal<_danjelp_ngx_app_shell.ShellConfig>;
+    readonly regionName = "topbar";
+    readonly regionWidth: Signal<number | null>;
+    readonly regionSize: Signal<ShellSize>;
+    protected readonly showToggle: Signal<boolean>;
+    protected readonly overflowSlots: Signal<readonly ShellSlotName[]>;
+    /** The ⋯ menu exists only while something is in it. */
+    protected readonly hasOverflow: Signal<boolean>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellTopbarComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ShellTopbarComponent, "shell-topbar", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Sidebar with four modes — `expanded`, `collapsed` (icon rail), `overlay`
+ * (modal drawer) and `hidden` — chosen by the injected `SidebarBehavior`
+ * rather than by this component. All this class does is render the resolved
+ * state and handle the mechanics each mode needs: peek timing, focus trapping,
+ * Escape, and drag-to-resize.
+ *
+ * Slot order, top to bottom:
+ *
+ *   sidebar-header      brand, workspace or account switcher
+ *   sidebar-action      one primary action ("New", "Compose")
+ *   sidebar-search      quick find / command palette launcher
+ *   sidebar-nav         the scrolling navigation (grows)
+ *   sidebar-secondary   settings, help, upgrade prompts
+ *   sidebar-footer      user card, storage meter — shares a row with the collapse control
+ */
+declare class ShellSidebarComponent implements ShellRegion {
+    private readonly host;
+    private readonly panel;
+    protected readonly store: ShellStore;
+    protected readonly config: Signal<_danjelp_ngx_app_shell.ShellConfig>;
+    /** Render the built-in expand/collapse control in the footer row. */
+    readonly collapseControl: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly regionName = "sidebar";
+    /**
+     * Measured on the *panel*, not the host: during a peek the panel is wider
+     * than the grid track it lives in. Exposed as `--shell-container-width`.
+     */
+    readonly regionWidth: Signal<number | null>;
+    /**
+     * The sidebar reports a *semantic* bucket rather than a measured one. Its
+     * panel is a few hundred pixels wide in every mode, so raw widths would put
+     * it permanently in `xs` and make `slotMinSize` useless. The contract is:
+     *
+     *   rail (icons only)          → `xs`
+     *   panel / drawer (labels on) → `md`
+     *
+     * so `slotMinSize="sm"` on a sidebar slot reads as "only when labels show".
+     */
+    readonly regionSize: Signal<ShellSize>;
+    protected readonly state: Signal<SidebarState>;
+    protected readonly hasHeader: Signal<boolean>;
+    protected readonly hasSecondary: Signal<boolean>;
+    private readonly hasFooterSlot;
+    /** The collapse control only makes sense for persistent panels. */
+    protected readonly showCollapse: Signal<boolean>;
+    protected readonly showFooter: Signal<boolean>;
+    protected readonly containerWidth: Signal<string | null>;
+    /** Peek only makes sense on a rail, and only when configured. */
+    private readonly peekable;
+    protected readonly resizable: Signal<boolean>;
+    /** Current panel width in px for `aria-valuenow` and keyboard steps. */
+    protected readonly resizeValue: Signal<number>;
+    constructor();
+    protected onPointerEnter(): void;
+    protected onPointerLeave(): void;
+    /** Keyboard users get the same peek: focus entering the rail widens it. */
+    protected onFocusIn(): void;
+    protected onFocusOut(event: FocusEvent): void;
+    protected onEscape(): void;
+    protected onResizeStart(event: PointerEvent): void;
+    protected onResizeMove(event: PointerEvent): void;
+    protected onResizeEnd(event: PointerEvent): void;
+    protected onResizeKey(event: KeyboardEvent): void;
+    /** Double-click the handle to return to the configured width. */
+    protected onResizeReset(): void;
+    private isRtl;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellSidebarComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ShellSidebarComponent, "shell-sidebar", never, { "collapseControl": { "alias": "collapseControl"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Footer strip. Three slots so the common "legal start, meta end" pattern
+ * needs no markup of its own, and so a status bar can occupy the middle.
+ * Measures itself, because its width depends on the layout and the sidebar.
+ */
+declare class ShellFooterComponent implements ShellRegion {
+    private readonly region;
+    protected readonly store: ShellStore;
+    readonly regionName = "footer";
+    readonly regionWidth: Signal<number | null>;
+    readonly regionSize: Signal<ShellSize>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellFooterComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ShellFooterComponent, "shell-footer", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * The breadcrumb row, between the topbar and `main`.
+ *
+ *   [breadcrumb | built-in trail] [subheader-start] ········ [subheader-end] [⋯]
+ *
+ * A measured region like the topbar: `subheader-end` templates use
+ * `slotMinSize` / `slotOverflow` against the row's own width and move into
+ * the row's ⋯ menu when they don't fit. Its minimum height is reserved, so
+ * labels and actions that arrive late never shift the page.
+ */
+declare class ShellSubheaderComponent implements ShellRegion {
+    private readonly region;
+    private readonly registry;
+    protected readonly config: Signal<_danjelp_ngx_app_shell.ShellConfig>;
+    readonly regionName = "subheader";
+    readonly regionWidth: Signal<number | null>;
+    readonly regionSize: Signal<ShellSize>;
+    /** An app-provided trail replaces the built-in one. */
+    protected readonly customTrail: Signal<boolean>;
+    protected readonly overflowSlots: Signal<readonly ShellSlotName[]>;
+    protected readonly hasOverflow: Signal<boolean>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellSubheaderComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ShellSubheaderComponent, "shell-subheader", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Route `data` key for a level's label: a string (static, or produced by a
+ * resolver under `resolve: { breadcrumb: … }`), or `false` to skip the level.
+ */
+declare const BREADCRUMB_DATA_KEY = "breadcrumb";
+/** Route `data` key that forces the breadcrumb row on (`true`) or off (`false`) for a page. */
+declare const SUBHEADER_DATA_KEY = "subheader";
+/** One level of the trail. */
+interface ShellCrumb {
+    /** `null` while the label is still loading: the crumb renders as a placeholder. */
+    readonly label: string | null;
+    readonly url: string;
+    /** The page the user is on: rendered as text with `aria-current="page"`, not as a link. */
+    readonly current: boolean;
+}
+/**
+ * How the trail is laid out:
+ * `full` — every level (the middle folds into "…" beyond `maxItems`);
+ * `compact` — first › … › parent › current;
+ * `back` — a single "‹ Parent" link.
+ */
+type ShellBreadcrumbDisplay = 'full' | 'compact' | 'back';
+/** Context of a custom `[itemTemplate]` on `<shell-breadcrumb>`. */
+interface ShellCrumbContext {
+    readonly $implicit: ShellCrumb;
+    readonly crumb: ShellCrumb;
+}
+type ShellCrumbTemplate = TemplateRef<ShellCrumbContext>;
+
+interface TrailView {
+    readonly head: readonly ShellCrumb[];
+    /** Levels folded into the "…" menu. */
+    readonly hidden: readonly ShellCrumb[];
+    readonly tail: readonly ShellCrumb[];
+}
+/**
+ * Breadcrumb trail, following the WAI-ARIA breadcrumb pattern:
+ * `<nav aria-label>` › `<ol>` › links, the current page as text with
+ * `aria-current="page"`, and CSS separators that screen readers skip.
+ *
+ * Renders the router-derived trail from `ShellBreadcrumbStore`, or `[items]`.
+ * It measures its own width and shortens itself instead of wrapping:
+ * full → middle levels folded into "…" → first › … › parent › current →
+ * a single "‹ Parent" back link.
+ */
+declare class ShellBreadcrumbComponent {
+    /** A manual trail. Leave unset to follow the router. */
+    readonly items: _angular_core.InputSignal<readonly ShellCrumb[] | null>;
+    /** Overrides `breadcrumbs.maxItems` for this instance. */
+    readonly maxItems: _angular_core.InputSignal<number | null>;
+    /** Force a layout instead of choosing one from the available width. */
+    readonly display: _angular_core.InputSignal<"auto" | ShellBreadcrumbDisplay>;
+    /** Custom crumb content; the link and `aria-current` stay the library's. */
+    readonly itemTemplate: _angular_core.InputSignal<ShellCrumbTemplate | null>;
+    private readonly store;
+    private readonly shell;
+    private readonly width;
+    private readonly options;
+    protected readonly separator: _angular_core.Signal<_danjelp_ngx_app_shell.BreadcrumbSeparator>;
+    protected readonly labels: _angular_core.Signal<_danjelp_ngx_app_shell.ShellLabels>;
+    protected readonly crumbs: _angular_core.Signal<readonly ShellCrumb[]>;
+    protected readonly mode: _angular_core.Signal<ShellBreadcrumbDisplay>;
+    protected readonly view: _angular_core.Signal<TrailView>;
+    /** Target of the "‹ Parent" link: the level just above the current page. */
+    protected readonly parent: _angular_core.Signal<ShellCrumb | null>;
+    protected readonly pending: _angular_core.Signal<boolean>;
+    /** Fast labels never flash a skeleton: it only shows after `skeletonDelay`. */
+    private readonly delayElapsed;
+    protected readonly skeletonShown: _angular_core.Signal<boolean>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellBreadcrumbComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ShellBreadcrumbComponent, "shell-breadcrumb", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "maxItems": { "alias": "maxItems"; "required": false; "isSignal": true; }; "display": { "alias": "display"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** A label, or a signal of one that is `undefined` while it loads. */
+type ShellBreadcrumbLabel = string | Signal<string | undefined>;
+/**
+ * The breadcrumb trail, derived from the router.
+ *
+ * On every `NavigationEnd` it walks the active (primary) route tree. Each
+ * route that consumes URL segments is one level, labelled by — in order — a
+ * page override, the route's own `data.breadcrumb` (static or resolved), or
+ * its own `title`. Only what a route declares *itself* counts: Angular copies
+ * `data` from componentless and empty-path parents into children, and a child
+ * must not borrow its parent's label.
+ */
+declare class ShellBreadcrumbStore {
+    private readonly router;
+    private readonly shell;
+    private readonly levels;
+    private readonly routeSubheader;
+    private readonly overrides;
+    /** Labelled levels of the current route, before the home/current options. */
+    private readonly trail;
+    /** The trail to render, with `breadcrumbs.includeHome` / `includeCurrent` applied. */
+    readonly crumbs: Signal<readonly ShellCrumb[]>;
+    /** Labelled levels in the current route; the home crumb is not counted. */
+    readonly depth: Signal<number>;
+    /** `data.subheader` of the deepest route that declares it, if any. */
+    readonly subheaderOverride: Signal<boolean | undefined>;
+    constructor();
+    /**
+     * Label one level from code — for names only the page knows, e.g. a record
+     * loaded without a resolver. `route` picks the level ending at that route's
+     * URL; `null` labels the current level. While a signal label is `undefined`
+     * the crumb renders as a placeholder. Returns a function that removes the
+     * label again; prefer `contributeBreadcrumbLabel()`, which does so for you.
+     */
+    setLabel(label: ShellBreadcrumbLabel, route?: ActivatedRoute | null): () => void;
+    /** The latest override for a level, `undefined` while pending, or `NO_OVERRIDE`. */
+    private overrideFor;
+    private refresh;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellBreadcrumbStore, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ShellBreadcrumbStore>;
+}
+/**
+ * Label the calling page's own level of the trail, for as long as the page
+ * lives. Call from a routed component's injection context:
+ *
+ * ```ts
+ * export class ProjectPage {
+ *   readonly name = signal<string | undefined>(undefined); // set when loaded
+ *   constructor() { contributeBreadcrumbLabel(this.name); }
+ * }
+ * ```
+ *
+ * While the signal is `undefined` the crumb is a placeholder; the breadcrumb
+ * row has reserved its height, so nothing shifts when the name arrives.
+ */
+declare function contributeBreadcrumbLabel(label: ShellBreadcrumbLabel): void;
+
+/**
+ * Drop-in toggle. Works anywhere in the app — header, page, command palette —
+ * because it talks to the root store rather than to a parent component.
+ *
+ * ```html
+ * <button shellSidebarToggle class="icon-button">☰</button>
+ * ```
+ *
+ * Sets `aria-expanded`, `aria-controls` and an accessible label that tracks the
+ * current mode, so the same button reads correctly as a hamburger on mobile and
+ * as a collapse control on desktop.
+ */
+declare class SidebarToggleDirective {
+    protected readonly store: ShellStore;
+    protected readonly sidebarId = "shell-sidebar";
+    /** True when the sidebar is showing its full, labelled panel. */
+    readonly expanded: _angular_core.Signal<boolean>;
+    readonly label: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SidebarToggleDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SidebarToggleDirective, "button[shellSidebarToggle]", ["shellSidebarToggle"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * One navigation entry. Data-driven on purpose: the same array can render in
+ * the sidebar, in the mobile drawer, in a command palette or in a breadcrumb
+ * without being duplicated as markup.
+ */
+interface ShellNavItem {
+    readonly id?: string;
+    readonly label: string;
+    /**
+     * Icon key handed to the icon template. Without an icon, a rail shows the
+     * label's first letter instead.
+     */
+    readonly icon?: string;
+    /** Router target. Takes precedence over `href`. Prefer absolute paths. */
+    readonly route?: string | readonly unknown[];
+    /** External or non-router target. */
+    readonly href?: string;
+    readonly target?: '_self' | '_blank';
+    /** Match the route exactly instead of by prefix. */
+    readonly exact?: boolean;
+    /** Short count or status text shown at the trailing edge. */
+    readonly badge?: string | number;
+    readonly disabled?: boolean;
+    /** Renders as an expandable section instead of a link. */
+    readonly children?: readonly ShellNavItem[];
+    /** Start expanded on first render. */
+    readonly expanded?: boolean;
+    /** Anything your own item template needs. */
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+/** A labelled cluster of items — the standard way to group sidebar navigation. */
+interface ShellNavGroup {
+    /** Required for `ShellNavRegistry` contributions to find the group. */
+    readonly id?: string;
+    /** Omit for an unlabelled first cluster (the usual "Home / Inbox" block). */
+    readonly label?: string;
+    readonly items: readonly ShellNavItem[];
+    readonly collapsible?: boolean;
+    readonly collapsed?: boolean;
+}
+/** Context of a custom `[itemTemplate]` on `<shell-nav>`. */
+interface ShellNavItemContext {
+    readonly $implicit: ShellNavItem;
+    readonly item: ShellNavItem;
+    /** Nesting level, 0 for top-level items. */
+    readonly depth: number;
+    /** False on an icon rail: render an icon only and keep the label for screen readers. */
+    readonly labels: boolean;
+    /** For sections: whether the children are showing. */
+    readonly expanded: boolean;
+}
+type ShellNavItemTemplate = TemplateRef<ShellNavItemContext>;
+interface ShellNavIconContext {
+    readonly $implicit: string;
+    readonly icon: string;
+    readonly item: ShellNavItem;
+}
+
+/**
+ * Renders grouped navigation. Data in, markup out — so the same array feeds
+ * the sidebar, the mobile drawer and anything else that needs the nav tree.
+ *
+ * ```html
+ * <ng-template shellSlot="sidebar-nav">
+ *   <shell-nav [groups]="navigation" [iconTemplate]="icon" />
+ * </ng-template>
+ * ```
+ *
+ * `labels` follows the sidebar by default, so a rail needs no configuration.
+ * Items contributed through `ShellNavRegistry` are merged into the groups with
+ * a matching `id`; groups that end up empty are not rendered.
+ */
+declare class ShellNavComponent {
+    /** Groups, or a flat item list which is wrapped in one unlabelled group. */
+    readonly groups: _angular_core.InputSignal<readonly ShellNavGroup[]>;
+    readonly items: _angular_core.InputSignal<readonly ShellNavItem[]>;
+    /** Override the sidebar's label state — useful when reusing `shell-nav`. */
+    readonly labels: _angular_core.InputSignal<boolean | null>;
+    /** Hide group headings even when labels show (a denser, Slack-like list). */
+    readonly headings: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Renders `ShellNavItem.icon` keys. Without it, the key is shown as text. */
+    readonly iconTemplate: _angular_core.InputSignal<TemplateRef<ShellNavIconContext> | null>;
+    /**
+     * Replaces the *content* of every row (icon, label, badge). The row element
+     * itself — link, section button, active state, children — stays the
+     * library's, so routing and accessibility keep working.
+     */
+    readonly itemTemplate: _angular_core.InputSignal<ShellNavItemTemplate | null>;
+    protected readonly store: ShellStore;
+    private readonly registry;
+    /** Per-group overrides on top of the data's own `collapsed` flag. */
+    private readonly groupOverrides;
+    protected readonly showLabels: _angular_core.Signal<boolean>;
+    protected readonly resolvedGroups: _angular_core.Signal<readonly ShellNavGroup[]>;
+    protected groupKey(group: ShellNavGroup, index: number): string;
+    protected isCollapsed(group: ShellNavGroup, index: number): boolean;
+    protected toggleGroup(group: ShellNavGroup, index: number): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellNavComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ShellNavComponent, "shell-nav", never, { "groups": { "alias": "groups"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; "headings": { "alias": "headings"; "required": false; "isSignal": true; }; "iconTemplate": { "alias": "iconTemplate"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * A single navigation entry: a link, or an expandable section when it has
+ * children.
+ *
+ * Renders `<a>` for anything navigable and `<button>` for a pure section
+ * header. Those are different semantics for assistive tech, and only one of
+ * them belongs in the tab order as a link. A section whose subtree contains the
+ * active route opens itself and is marked, so deep links never land in a
+ * collapsed tree.
+ */
+declare class ShellNavItemComponent {
+    readonly item: _angular_core.InputSignal<ShellNavItem>;
+    readonly depth: _angular_core.InputSignal<number>;
+    /** False on an icon rail: labels and badges give way to icons and tooltips. */
+    readonly labels: _angular_core.InputSignal<boolean>;
+    readonly iconTemplate: _angular_core.InputSignal<TemplateRef<ShellNavIconContext> | null>;
+    /** Replaces the row content; see `ShellNavComponent.itemTemplate`. */
+    readonly itemTemplate: _angular_core.InputSignal<ShellNavItemTemplate | null>;
+    private readonly router;
+    /** Current URL, so "contains the active route" re-evaluates on navigation. */
+    private readonly url;
+    protected readonly children: Signal<readonly ShellNavItem[]>;
+    protected readonly hasChildren: Signal<boolean>;
+    protected readonly isLink: Signal<boolean>;
+    protected readonly childActive: Signal<boolean>;
+    /**
+     * User-toggleable, but re-derives when the data or the active route changes —
+     * so a server-driven `expanded` flag or a deep link still wins, without
+     * clobbering a click the moment anything else re-renders.
+     */
+    private readonly expandedState;
+    protected readonly expanded: Signal<boolean>;
+    /** Tooltip only when the label is not rendered — otherwise it is noise. */
+    protected readonly title: Signal<string | null>;
+    /** Stand-in for a missing icon on a rail, so the row is never blank. */
+    protected readonly initial: Signal<string>;
+    protected readonly itemContext: Signal<ShellNavItemContext>;
+    protected toggle(): void;
+    /** `readonly unknown[]` is friendlier as an API than RouterLink's `any[]`. */
+    protected routerTarget(item: ShellNavItem): string | unknown[];
+    private containsActive;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellNavItemComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ShellNavItemComponent, "shell-nav-item", never, { "item": { "alias": "item"; "required": true; "isSignal": true; }; "depth": { "alias": "depth"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; "iconTemplate": { "alias": "iconTemplate"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Static items, or a signal of items (e.g. with live badge counts). */
+type ShellNavItemsSource = readonly ShellNavItem[] | Signal<readonly ShellNavItem[]>;
+interface ShellNavContributionOptions {
+    /**
+     * Ascending position among contributions to the same group. Contributions
+     * always follow the group's own items; ties keep registration order.
+     */
+    readonly order?: number;
+}
+/**
+ * Lets code other than the owner of the nav array add entries to it — a
+ * feature library adding "Roadmap" to the app's "Workspace" group, or a
+ * section adding context links while it is open.
+ *
+ * Contributions target a group by `ShellNavGroup.id` and are merged into every
+ * `<shell-nav>` that renders a group with that id. The app keeps control of
+ * structure and order: it declares the groups (an empty group is fine — empty
+ * groups are not rendered), features only fill them.
+ */
+declare class ShellNavRegistry {
+    private readonly contributions;
+    private sequence;
+    /**
+     * Add items to the group with this id. Returns a function that removes them
+     * again. Prefer `contributeNavItems()` / `provideShellNavItems()`, which
+     * remove them automatically.
+     */
+    contribute(groupId: string, items: ShellNavItemsSource, options?: ShellNavContributionOptions): () => void;
+    /** Items contributed to a group, in order. Reactive when read in a signal context. */
+    itemsFor(groupId: string): readonly ShellNavItem[];
+    /**
+     * `groups` with contributed items appended to the groups whose `id` matches.
+     * Returns the input untouched when there is nothing to add, so object
+     * identity stays stable for the common case. Reactive.
+     */
+    merge(groups: readonly ShellNavGroup[]): readonly ShellNavGroup[];
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ShellNavRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ShellNavRegistry>;
+}
+/**
+ * Contribute nav items for the lifetime of the calling component, directive or
+ * service. Call from an injection context.
+ *
+ * ```ts
+ * export class ProjectPage {
+ *   constructor() {
+ *     contributeNavItems('workspace', [{ label: 'Project settings', route: '/settings' }]);
+ *   }
+ * }
+ * ```
+ */
+declare function contributeNavItems(groupId: string, items: ShellNavItemsSource, options?: ShellNavContributionOptions): void;
+/**
+ * Contribute nav items for the lifetime of an environment injector. In the app
+ * config the entries exist from startup — the usual way for a feature to own
+ * its link:
+ *
+ * ```ts
+ * providers: [provideShellNavItems('workspace', [{ label: 'Roadmap', route: '/roadmap' }])]
+ * ```
+ *
+ * In a lazy route's `providers` they only appear once that route has loaded,
+ * so do not use that to add the link *to* the lazy route itself.
+ */
+declare function provideShellNavItems(groupId: string, items: ShellNavItemsSource, options?: ShellNavContributionOptions): EnvironmentProviders;
+
+/**
+ * Add to a component's `imports` to get the whole shell vocabulary:
+ *
+ * ```ts
+ * @Component({ imports: [APP_SHELL], … })
+ * ```
+ *
+ * Tree-shaking still applies per component, so unused pieces are dropped.
+ */
+declare const APP_SHELL: readonly [typeof AppShellComponent, typeof ShellSlotDirective, typeof ShellSlotOutletComponent, typeof ShellNavComponent, typeof ShellNavItemComponent, typeof ShellBreadcrumbComponent, typeof SidebarToggleDirective, typeof ContainerSizeDirective];
+
+export { APP_SHELL, AppShellComponent, BREADCRUMB_DATA_KEY, ContainerSizeDirective, DEFAULT_BREAKPOINTS, DEFAULT_SHELL_CONFIG, SHELL_CONFIG, SHELL_MAIN_ID, SHELL_REGION, SHELL_SIDEBAR_ID, SHELL_SIZES, SHELL_STATE_STORAGE, SIDEBAR_BEHAVIOR, SUBHEADER_DATA_KEY, ShellBreadcrumbComponent, ShellBreadcrumbStore, ShellFooterComponent, ShellNavComponent, ShellNavItemComponent, ShellNavRegistry, ShellSidebarComponent, ShellSlotDirective, ShellSlotOutletComponent, ShellSlotRegistry, ShellStore, ShellSubheaderComponent, ShellTopbarComponent, SidebarToggleDirective, atLeast, atMost, contributeBreadcrumbLabel, contributeNavItems, drawerSidebarBehavior, drawerState, hasSlot, hiddenState, isBelow, localShellStateStorage, manualSidebarBehavior, measureRegion, mergeShellConfig, observeWidth, panelState, provideAppShell, provideShellNavItems, railState, resolveSize, responsiveSidebarBehavior, sizeRank };
+export type { BreadcrumbSeparator, DrawerMotion, FooterAppearance, MeasuredRegion, MenuMotion, NavIndicator, ScrimMotion, ShellApi, ShellAppearanceConfig, ShellBreadcrumbDisplay, ShellBreadcrumbLabel, ShellBreadcrumbsConfig, ShellBreakpoints, ShellConfig, ShellConfigInput, ShellCrumb, ShellCrumbContext, ShellCrumbTemplate, ShellFooterConfig, ShellLabels, ShellLayout, ShellMotionConfig, ShellNavContributionOptions, ShellNavGroup, ShellNavIconContext, ShellNavItem, ShellNavItemContext, ShellNavItemTemplate, ShellNavItemsSource, ShellRegion, ShellScrollMode, ShellSidebarConfig, ShellSize, ShellSlotContext, ShellSlotName, ShellStateStorage, ShellSubheaderConfig, ShellTopbarConfig, SidebarAppearance, SidebarBehavior, SidebarContext, SidebarIntent, SidebarMode, SidebarState, SidebarToggleVisibility, SubheaderAppearance, SubheaderVisibility, TopbarAppearance, WidthTarget };