@aquera/nile-elements 2.0.10 → 2.0.11

package/dist/src/nile-app-shell/nile-app-shell.d.ts

@@ -13,10 +13,10 @@ export type NileAppShellPanelMode = 'docked' | 'overlay';
 export type NileAppShellTopBarPlacement = 'content' | 'shell';
 /** How the main region lays its content out. */
 export type NileAppShellContentAlign = 'fluid' | 'centered';
+/** What sits before the page title in the top bar. */
+export type NileAppShellLeading = 'none' | 'back' | 'app-icon';
 /**
- * @summary The application frame every route inherits: a side nav, a content
- * container, an optional aside and an AI assistant panel. It holds anything —
- * the shell owns the boxes, the page owns what goes in them.
+ * @summary The application frame every route inherits: a side nav, a content container, an optional aside and an AI assistant panel.
  *
  * @status stable
  * @since 2.0
@@ -28,29 +28,22 @@ export type NileAppShellContentAlign = 'fluid' | 'centered';
  *
  * @slot - The page body, inside the content container.
  * @slot banner - A full-width strip above every other region.
- * @slot top-bar - The page-title bar. Mounted inside the container by default,
- *   or spanning the shell when `top-bar-placement="shell"`. The nav toggle is
- *   rendered before whatever is slotted here.
+ * @slot top-bar - The page-title bar, mounted inside the container by default or spanning the shell when `top-bar-placement="shell"`.
  * @slot top-bar-actions - Controls pinned to the end of the top bar.
- * @slot tabs - A hoisted second-level tab strip, flush under the top bar and
- *   outside `<main>`'s scroller, so it never scrolls away. The region carries
- *   the strip's height, padding and rule, so slot a `<nile-tab-group>` or the
- *   tab controls themselves.
+ * @slot tabs - A hoisted second-level tab strip, flush under the top bar and outside `<main>`'s scroller.
+ * @slot app-icon - The mark shown when `leading="app-icon"`, clipped to the shell's box.
  * @slot side-nav - The navigation track. Works best with `<nile-side-bar>`.
  * @slot aside - A secondary column between the content container and the panel.
- * @slot panel - The AI panel's body. When nothing is slotted here the panel is
- *   unmounted and `openPanel()` is a no-op.
+ * @slot panel - The AI panel's body. When empty the panel is unmounted and `openPanel()` is a no-op.
  * @slot panel-header - Replaces the default panel heading (mark plus title).
  * @slot panel-actions - Controls added before the panel's close button.
- * @slot panel-footer - A bar docked below the panel's scroll region, for a
- *   composer.
+ * @slot panel-footer - A bar docked below the panel's scroll region, for a composer.
  *
- * @event nile-nav-toggle - Emitted after the nav's collapsed state or its
- *   forced-rail lock changes. `detail: { collapsed, locked }`.
- * @event nile-panel-toggle - Emitted after the panel opens or closes.
- *   `detail: { open, mode }`.
- * @event nile-panel-mode-change - Emitted when the panel flips between docked
- *   and overlay. `detail: { mode }`.
+ * @event nile-nav-toggle - Emitted after the nav's collapsed state or forced-rail lock changes. `detail: { collapsed, locked }`.
+ * @event nile-panel-toggle - Emitted after the panel opens or closes. `detail: { open, mode }`.
+ * @event nile-panel-mode-change - Emitted when the panel flips between docked and overlay. `detail: { mode }`.
+ * @event nile-header-back - Emitted when the header's back control is pressed.
+ * @event nile-panel-back - Emitted when the panel's back control is pressed, whether the shell's built-in panel chrome or a slotted `nile-app-shell-panel` draws it.
  *
  * @csspart skip-link - The skip-to-content link.
  * @csspart banner - The banner region.
@@ -58,12 +51,15 @@ export type NileAppShellContentAlign = 'fluid' | 'centered';
  * @csspart top-bar - The top bar, in either placement.
  * @csspart nav-toggle - The built-in nav toggle button.
  * @csspart rule - The vertical rule after the nav toggle.
- * @csspart top-bar-actions - The end-aligned top bar action group. Unmounted
- *   when it holds neither slotted actions nor the Ask button, so it reserves
- *   no gap.
+ * @csspart top-bar-actions - The end-aligned top bar action group.
  * @csspart ask - The built-in Ask button, the shell's single door to the panel.
- *   A `<nile-button>`; its inner surface and label are exported as
- *   `ask__base` and `ask__label`.
+ * @csspart title-area - The header's own title block: leading, title, badge and description.
+ * @csspart page-title - The title text, exposed as a heading whose level `headingLevel` sets.
+ * @csspart description - The second line under the title.
+ * @csspart badge - The pill after the title.
+ * @csspart leading - The line box holding the leading control.
+ * @csspart back - The back control shown by `leading="back"`.
+ * @csspart app-icon - The block shown by `leading="app-icon"`, sized by `--nile-app-shell-app-icon-size`.
  * @csspart tabs - The hoisted tab-strip region, under the top bar.
  * @csspart side-nav - The navigation track.
  * @csspart content-section - The flex row holding container, aside and panel.
@@ -72,42 +68,32 @@ export type NileAppShellContentAlign = 'fluid' | 'centered';
  * @csspart aside - The aside region.
  * @csspart panel - The AI panel.
  * @csspart panel-header - The panel's header bar.
+ * @csspart panel-back - The panel's back control, shown by `panelBack`.
  * @csspart panel-title - The panel's title text.
  * @csspart panel-actions - The panel's header action group.
  * @csspart panel-close - The panel's close button.
  * @csspart panel-body - The panel's scroll region.
  * @csspart panel-footer - The panel's footer.
  *
- * @cssproperty [--nile-app-shell-side-nav-width=260px] - Expanded nav track.
- * @cssproperty [--nile-app-shell-side-nav-rail-width=64px] - Collapsed track.
- * @cssproperty [--nile-app-shell-side-nav-bg=transparent] - Surface behind a
- *   slotted side nav. Transparent by default: the nav and the page share one
- *   surface.
- * @cssproperty [--nile-app-shell-side-nav-border=0] - Edge on a slotted side
- *   nav.
- * @cssproperty [--nile-app-shell-gutter=8px] - Content-section padding, and the
- *   gap between container, aside and panel.
- * @cssproperty [--nile-app-shell-content-padding=24px] - Container inner
- *   padding. The origin every top bar starts at.
- * @cssproperty [--nile-app-shell-top-bar-height=56px] - Top bar and panel
- *   header height. Drops to 48px under 600px of viewport height.
- * @cssproperty [--nile-app-shell-tabs-height=48px] - Tab strip height.
- * @cssproperty [--nile-app-shell-panel-width=480px] - Docked panel width, and
- *   the `min()` ceiling for the overlay drawer.
- * @cssproperty [--nile-app-shell-panel-min-width=360px] - How far a docked
- *   panel shrinks to keep pushing rather than covering the page.
+ * @cssproperty [--nile-app-shell-side-nav-width=240px] - Expanded nav track.
+ * @cssproperty [--nile-app-shell-side-nav-rail-width=70px] - Collapsed track.
+ * @cssproperty [--nile-app-shell-side-nav-bg=transparent] - Surface behind a slotted side nav.
+ * @cssproperty [--nile-app-shell-side-nav-border=0] - Edge on a slotted side nav.
+ * @cssproperty [--nile-app-shell-gutter=4px] - Content-section padding, and the gap between container, aside and panel.
+ * @cssproperty [--nile-app-shell-content-padding=24px] - Container inner padding.
+ * @cssproperty [--nile-app-shell-top-bar-height=68px] - Top bar height.
+ * @cssproperty [--nile-app-shell-panel-header-height=56px] - The panel header's own height.
+ * @cssproperty [--nile-app-shell-tabs-height=33px] - Tab strip height.
+ * @cssproperty [--nile-app-shell-panel-width=480px] - Docked panel width, and the `min()` ceiling for the overlay drawer.
+ * @cssproperty [--nile-app-shell-panel-min-width=360px] - How far a docked panel shrinks to keep pushing rather than covering the page.
  * @cssproperty [--nile-app-shell-aside-width=320px] - Aside width.
- * @cssproperty [--nile-app-shell-aside-min-width=240px] - How far the aside
- *   shrinks before the page is asked for room.
+ * @cssproperty [--nile-app-shell-aside-min-width=240px] - How far the aside shrinks before the page is asked for room.
  * @cssproperty [--nile-app-shell-content-min-width=640px] - Container floor.
- * @cssproperty [--nile-app-shell-min-width=768px] - Below this the window
- *   scrolls rather than the shell compressing.
- * @cssproperty [--nile-app-shell-centered-width=824px] - Column width under
- *   `content-align="centered"`.
- * @cssproperty [--nile-app-shell-utility-size=32px] - Height of the Ask
- *   button. The toggle and close controls are nile-buttons and size themselves.
- * @cssproperty [--nile-app-shell-radius=16px] - Container, aside and panel
- *   radius.
+ * @cssproperty [--nile-app-shell-min-width=768px] - Below this the window scrolls rather than the shell compressing.
+ * @cssproperty [--nile-app-shell-centered-width=824px] - Column width under `content-align="centered"`.
+ * @cssproperty [--nile-app-shell-app-icon-size=20px] - The leading app icon's box.
+ * @cssproperty [--nile-app-shell-utility-size=32px] - Box the shell's own icon controls sit in.
+ * @cssproperty [--nile-app-shell-radius=16px] - Container, aside and panel radius.
  * @cssproperty [--nile-app-shell-duration=250ms] - Track and panel motion.
  * @cssproperty [--nile-app-shell-ease] - Easing for moves and resizes.
  *
@@ -117,23 +103,33 @@ export type NileAppShellContentAlign = 'fluid' | 'centered';
  * @method expandNav() - Expand the side nav.
  * @method collapseNav() - Collapse the side nav to a rail.
  * @method toggleNav(force?) - Toggle, or force a specific collapsed state.
+ * @method goBackHeader() - Emit `nile-header-back`, as the header's back control does.
+ * @method goBackPanel() - Emit `nile-panel-back`, as the panel's back control does.
+ * @method goBackPage() - Deprecated alias of `goBackHeader()`.
+ * @method goBack() - Deprecated alias of `goBackPanel()`.
  */
 export declare class NileAppShell extends NileElement {
     static get styles(): CSSResultArray;
-    /**
-     * The user's nav preference. The nav can still render as a rail while this is
-     * false — see `navLocked`.
-     */
+    /** The user's nav preference. The nav can still render as a rail while this is false — see `navLocked`. */
     navCollapsed: boolean;
     /** Whether the AI panel is open. */
     panelOpen: boolean;
-    /**
-     * Unmounts the AI panel for this route even when the `panel` slot is filled.
-     * `openPanel()` becomes a no-op.
-     */
+    /** Unmounts the AI panel for this route even when the `panel` slot is filled; `openPanel()` becomes a no-op. */
     noPanel: boolean;
     /** The default panel heading. Ignored when `panel-header` is slotted. */
     panelLabel: string;
+    /** The page title, rendered as the top bar's own heading (`role="heading"`, level from `headingLevel`) before anything slotted into `top-bar`; leave unset and no title block renders. */
+    pageTitle?: string;
+    /** The `aria-level` of the `pageTitle` heading, 1–6, so the title can fit the page's own heading outline; e.g. 2 when the page body or banner already has its h1. Out-of-range values clamp to 1–6 and non-numbers fall back to 1. */
+    headingLevel: number;
+    /** A second line under the page title; a modifier on `pageTitle` that renders nothing with no title, and takes the bar to 76px. */
+    description?: string;
+    /** A pill after the page title; a modifier on `pageTitle` like `description`, so with no title there is no badge. */
+    badge?: string;
+    /** What sits before the page title: `back` draws a breadcrumb and emits `nile-header-back`; `app-icon` draws a 20px block for the `app-icon` slot. */
+    leading: NileAppShellLeading;
+    /** The previous-page label drawn by `leading="back"`. */
+    backLabel: string;
     /** Hides the built-in nav toggle. Mount `nile-app-shell-nav-toggle` yourself. */
     noNavToggle: boolean;
     /** Drops the Cmd/Ctrl+J and Escape panel shortcuts. */
@@ -146,53 +142,29 @@ export declare class NileAppShell extends NileElement {
     topBarPlacement: NileAppShellTopBarPlacement;
     /** `centered` caps the page body at `--nile-app-shell-centered-width`. */
     contentAlign: NileAppShellContentAlign;
-    /**
-     * Makes the slotted page root a size query container, so page CSS can size
-     * against the content container instead of the viewport. Query it unnamed —
-     * `@container (min-width: 720px)` — because a container name declared inside
-     * the shell's shadow tree is not visible to page CSS. Opt-in, because it
-     * also applies layout containment to that element.
-     */
+    /** Makes the slotted page root a size query container, so page CSS can size against the content container instead of the viewport. */
     contentContainer: boolean;
     /** Drops the container's card chrome for a full-bleed page. */
     flat: boolean;
     /** Removes the container's inner padding. */
     noPadding: boolean;
-    /**
-     * The label on the built-in Ask button.
-     *
-     * The button is the shell's, not the app's: it is the one control that has
-     * to know whether a panel is mounted for this route and how to open it, and
-     * slotted content can see neither. Everything else in the bar — the
-     * breadcrumb, the page actions, the tab strip — is slotted markup.
-     */
+    /** The label on the built-in Ask button. */
     askLabel: string;
     /** Drops the built-in Ask button, for a bar that renders its own. */
     noAsk: boolean;
+    /** Shows a back control at the start of the panel header for a panel sub-view; emits `nile-panel-back`. */
+    panelBack: boolean;
+    /** Accessible name of the panel's back control. */
+    panelBackLabel: string;
+    /** Hides the tab strip for this route even when the `tabs` slot is filled. */
+    noTabs: boolean;
     /** Sizes the shell to the viewport instead of its parent. */
     fullHeight: boolean;
-    /**
-     * Below this shell width the panel overlays the content instead of pushing
-     * it, and the nav is forced to a rail.
-     *
-     * Zero — the default — means never: the panel is furniture that squeezes the
-     * page, at every width. It earns its room from the nav rail first and from
-     * its own width next (see `--nile-app-shell-panel-min-width`), so it does
-     * not have to cover the page to fit. Set a width here to opt back into an
-     * overlay drawer below it.
-     */
+    /** Below this shell width the panel overlays the content instead of pushing it, and the nav is forced to a rail; zero (default) means never. */
     overlayBreakpoint: number;
-    /**
-     * Below this shell width an open docked panel forces the nav to a rail.
-     * A floor, not the whole rule: the nav also rails as soon as the expanded
-     * track is what stops the row from fitting. This is the first thing the
-     * panel takes room from, so it can push rather than cover.
-     */
+    /** Below this shell width an open docked panel forces the nav to a rail. */
     dockedRailBreakpoint: number;
-    /**
-     * Persists the nav preference and the docked panel state under this key.
-     * Overlay panel state is never persisted — a reload opens closed.
-     */
+    /** Persists the nav preference and docked panel state under this key. Overlay panel state is never persisted. */
     persistKey?: string;
     /** The panel's current mode. Derived from the shell's width. */
     private _panelMode;
@@ -205,12 +177,7 @@ export declare class NileAppShell extends NileElement {
     private _hasTabs;
     private _hasPanel;
     private _hasPanelFooter;
-    /**
-     * True when a `nile-app-shell-panel` is slotted. That component owns the
-     * panel's heading, actions, close button and footer, so the shell renders a
-     * bare region and keeps only the geometry and the open state — the same
-     * hand-off as `no-nav-toggle` plus `nile-app-shell-nav-toggle`.
-     */
+    /** True when a `nile-app-shell-panel` is slotted, owning the panel's own chrome so the shell renders a bare region. */
     private _panelOwnsChrome;
     private _hasAside;
     private _main?;
@@ -223,6 +190,8 @@ export declare class NileAppShell extends NileElement {
     get navLocked(): boolean;
     /** Whether a panel is mounted for this route. */
     get panelAvailable(): boolean;
+    /** Whether the tab strip is rendered: something slotted, and not switched off. */
+    get tabsVisible(): boolean;
     /** Whether the built-in Ask button is rendered. */
     get askVisible(): boolean;
     /** Whether the nav renders as a rail right now, preference or lock. */
@@ -235,12 +204,16 @@ export declare class NileAppShell extends NileElement {
     openPanel(): void;
     /** Close the AI panel. */
     closePanel(): void;
-    /**
-     * Toggle the panel, or force a state. Call `openPanel()` from a page action —
-     * a page action that toggles closes the panel for a user who already had it
-     * open.
-     */
+    /** Toggle the panel, or force a state. */
     togglePanel(force?: boolean): void;
+    /** Emit `nile-header-back`, as the header's back control does; the page owns the history. */
+    goBackHeader(): void;
+    /** Emit `nile-panel-back`, as the panel's back control does; the page owns the view stack. */
+    goBackPanel(): void;
+    /** @deprecated Use `goBackHeader()`; kept as an alias that emits `nile-header-back`. */
+    goBackPage(): void;
+    /** @deprecated Use `goBackPanel()`; kept as an alias that emits `nile-panel-back`. */
+    goBack(): void;
     /** Expand the side nav. */
     expandNav(): void;
     /** Collapse the side nav to a rail. */
@@ -253,22 +226,9 @@ export declare class NileAppShell extends NileElement {
     private _setNavCollapsed;
     /** Records the shell's width and re-derives everything that depends on it. */
     private _measure;
-    /**
-     * The shell's geometry, read off its own custom properties so a consumer's
-     * overrides are part of the sum. Falls back to the stylesheet's defaults
-     * before the element has a computed style.
-     */
+    /** The shell's geometry, read off its own custom properties, falling back to defaults before a computed style exists. */
     private _geometry;
-    /**
-     * The shell width a docked panel needs to sit beside the content floor, over
-     * a side-nav `track` wide.
-     *
-     * A fixed breakpoint cannot answer this: what shares the row changes per
-     * route. An aside alone adds 328px, so a shell wide enough to hold the
-     * expanded nav beside a docked panel on one route is 328px short on the
-     * next. Summing what is actually mounted rails the nav exactly when the
-     * track is what the row cannot afford.
-     */
+    /** The shell width a docked panel needs to sit beside the content floor, over a side-nav `track` wide. */
     private _dockRequirement;
     private _recompute;
     /** Mirrors the effective rail state onto a slotted `nile-side-bar`. */
@@ -281,6 +241,14 @@ export declare class NileAppShell extends NileElement {
     private _persist;
     private _onSlotChange;
     private _renderNavToggle;
+    /** Whether the header has a title block of its own to draw: only a title or a leading control mounts it. */
+    private get _hasTitleBlock();
+    /** Whether `leading` names a control that renders; an empty or unknown value draws nothing, like `none`. */
+    private get _hasLeading();
+    /** `headingLevel` as a safe `aria-level`: a whole number clamped to 1–6, and 1 for anything non-numeric. */
+    private get _headingLevel();
+    private _renderLeading;
+    private _renderTitleBlock;
     private _renderTopBar;
     render(): TemplateResult;
 }