@aquera/nile-elements 2.0.9 → 2.0.11

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

@@ -22,6 +22,9 @@ 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';
+
 /** The shell's own track and region widths, in px. */
 interface ShellGeometry {
   nav: number;
@@ -33,9 +36,7 @@ interface ShellGeometry {
 }
 
 /**
- * @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
@@ -47,29 +48,22 @@ interface ShellGeometry {
  *
  * @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.
@@ -77,12 +71,15 @@ interface ShellGeometry {
  * @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.
@@ -91,42 +88,32 @@ interface ShellGeometry {
  * @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.
  *
@@ -136,6 +123,10 @@ interface ShellGeometry {
  * @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()`.
  */
 @customElement('nile-app-shell')
 export class NileAppShell extends NileElement {
@@ -143,10 +134,7 @@ export class NileAppShell extends NileElement {
     return [styles];
   }
 
-  /**
-   * 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`. */
   @property({ type: Boolean, reflect: true, attribute: 'nav-collapsed' })
   navCollapsed: boolean = false;
 
@@ -154,10 +142,7 @@ export class NileAppShell extends NileElement {
   @property({ type: Boolean, reflect: true, attribute: 'panel-open' })
   panelOpen: boolean = false;
 
-  /**
-   * 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. */
   @property({ type: Boolean, reflect: true, attribute: 'no-panel' })
   noPanel: boolean = false;
 
@@ -165,6 +150,30 @@ export class NileAppShell extends NileElement {
   @property({ type: String, attribute: 'panel-label' })
   panelLabel: string = 'Ask Aquera';
 
+  /** 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. */
+  @property({ type: String, attribute: true, reflect: true })
+  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. */
+  @property({ type: Number, attribute: true, reflect: true })
+  headingLevel: number = 1;
+
+  /** A second line under the page title; a modifier on `pageTitle` that renders nothing with no title, and takes the bar to 76px. */
+  @property({ type: String, attribute: true, reflect: true })
+  description?: string;
+
+  /** A pill after the page title; a modifier on `pageTitle` like `description`, so with no title there is no badge. */
+  @property({ type: String, attribute: true, reflect: true })
+  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. */
+  @property({ type: String, attribute: true, reflect: true })
+  leading: NileAppShellLeading = 'none';
+
+  /** The previous-page label drawn by `leading="back"`. */
+  @property({ type: String, attribute: true, reflect: true })
+  backLabel: string = 'Back';
+
   /** Hides the built-in nav toggle. Mount `nile-app-shell-nav-toggle` yourself. */
   @property({ type: Boolean, reflect: true, attribute: 'no-nav-toggle' })
   noNavToggle: boolean = false;
@@ -189,13 +198,7 @@ export class NileAppShell extends NileElement {
   @property({ type: String, reflect: true, attribute: 'content-align' })
   contentAlign: NileAppShellContentAlign = 'fluid';
 
-  /**
-   * 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. */
   @property({ type: Boolean, reflect: true, attribute: 'content-container' })
   contentContainer: boolean = false;
 
@@ -207,14 +210,7 @@ export class NileAppShell extends NileElement {
   @property({ type: Boolean, reflect: true, attribute: 'no-padding' })
   noPadding: boolean = false;
 
-  /**
-   * 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. */
   @property({ type: String, attribute: 'ask-label' })
   askLabel: string = 'Ask';
 
@@ -222,36 +218,31 @@ export class NileAppShell extends NileElement {
   @property({ type: Boolean, reflect: true, attribute: 'no-ask' })
   noAsk: boolean = false;
 
+  /** Shows a back control at the start of the panel header for a panel sub-view; emits `nile-panel-back`. */
+  @property({ type: Boolean, reflect: true })
+  panelBack: boolean = false;
+
+  /** Accessible name of the panel's back control. */
+  @property({ type: String })
+  panelBackLabel: string = 'Back';
+
+  /** Hides the tab strip for this route even when the `tabs` slot is filled. */
+  @property({ type: Boolean, reflect: true })
+  noTabs: boolean = false;
+
   /** Sizes the shell to the viewport instead of its parent. */
   @property({ type: Boolean, reflect: true, attribute: 'full-height' })
   fullHeight: boolean = false;
 
-  /**
-   * 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. */
   @property({ type: Number, attribute: 'overlay-breakpoint' })
   overlayBreakpoint: number = 0;
 
-  /**
-   * 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. */
   @property({ type: Number, attribute: 'docked-rail-breakpoint' })
   dockedRailBreakpoint: number = 1440;
 
-  /**
-   * 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. */
   @property({ type: String, attribute: 'persist-key' })
   persistKey?: string;
 
@@ -269,12 +260,7 @@ export class NileAppShell extends NileElement {
   @state() private _hasPanel: boolean = false;
   @state() private _hasPanelFooter: boolean = false;
 
-  /**
-   * 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. */
   @state() private _panelOwnsChrome: boolean = false;
   @state() private _hasAside: boolean = false;
 
@@ -299,6 +285,11 @@ export class NileAppShell extends NileElement {
     return this._hasPanel && !this.noPanel;
   }
 
+  /** Whether the tab strip is rendered: something slotted, and not switched off. */
+  public get tabsVisible(): boolean {
+    return this._hasTabs && !this.noTabs;
+  }
+
   /** Whether the built-in Ask button is rendered. */
   public get askVisible(): boolean {
     return this.panelAvailable && !this.noAsk;
@@ -333,8 +324,7 @@ export class NileAppShell extends NileElement {
       changed.has('noPanel') ||
       changed.has('overlayBreakpoint') ||
       changed.has('dockedRailBreakpoint') ||
-      // Mounting an aside changes what a docked panel has to fit beside.
-      // Private state is outside `keyof this`, so ask the map directly.
+      // Aside/side-nav mounting changes what a docked panel fits beside; ask the map since private state is outside `keyof this`.
       (changed as Map<string, unknown>).has('_hasAside') ||
       (changed as Map<string, unknown>).has('_hasSideNav')
     ) {
@@ -352,11 +342,18 @@ export class NileAppShell extends NileElement {
     this.toggleAttribute('has-side-nav', this._hasSideNav);
     this.toggleAttribute(
       'has-top-bar',
-      this._hasTopBar || (!this.noNavToggle && this._hasSideNav)
+      this._hasTopBar ||
+        this._hasTitleBlock ||
+        (!this.noNavToggle && this._hasSideNav)
+    );
+    // Only with a title to sit under: see _hasTitleBlock.
+    this.toggleAttribute(
+      'has-description',
+      !!this.description && !!this.pageTitle
     );
     this.toggleAttribute('has-top-bar-actions', this._hasTopBarActions);
     this.toggleAttribute('has-ask', this.askVisible);
-    this.toggleAttribute('has-tabs', this._hasTabs);
+    this.toggleAttribute('has-tabs', this.tabsVisible);
     this.toggleAttribute('has-aside', this._hasAside);
     this.toggleAttribute('has-panel', this.panelAvailable);
     this.toggleAttribute('has-panel-footer', this._hasPanelFooter);
@@ -380,17 +377,33 @@ export class NileAppShell extends NileElement {
     this._setPanelOpen(false);
   }
 
-  /**
-   * 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. */
   public togglePanel(force?: boolean): void {
     const next = force ?? !this.panelOpen;
     if (next) this.openPanel();
     else this.closePanel();
   }
 
+  /** Emit `nile-header-back`, as the header's back control does; the page owns the history. */
+  public goBackHeader(): void {
+    this.emit('nile-header-back');
+  }
+
+  /** Emit `nile-panel-back`, as the panel's back control does; the page owns the view stack. */
+  public goBackPanel(): void {
+    this.emit('nile-panel-back');
+  }
+
+  /** @deprecated Use `goBackHeader()`; kept as an alias that emits `nile-header-back`. */
+  public goBackPage(): void {
+    this.goBackHeader();
+  }
+
+  /** @deprecated Use `goBackPanel()`; kept as an alias that emits `nile-panel-back`. */
+  public goBack(): void {
+    this.goBackPanel();
+  }
+
   /** Expand the side nav. */
   public expandNav(): void {
     this._setNavCollapsed(false);
@@ -443,11 +456,7 @@ export class NileAppShell extends NileElement {
     }
   }
 
-  /**
-   * 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(): ShellGeometry {
     const style = getComputedStyle(this);
     const px = (name: string, fallback: number): number => {
@@ -455,51 +464,35 @@ export class NileAppShell extends NileElement {
       return Number.isFinite(value) ? value : fallback;
     };
     return {
-      nav: px('--nile-app-shell-side-nav-width', 260),
-      rail: px('--nile-app-shell-side-nav-rail-width', 64),
-      gutter: px('--nile-app-shell-gutter', 8),
+      // Read the substituted value so they follow the active theme; the literals are the enterprise fallback.
+      nav: px('--nile-app-shell-side-nav-width', 240),
+      rail: px('--nile-app-shell-side-nav-rail-width', 70),
+      gutter: px('--nile-app-shell-gutter', 4),
       content: px('--nile-app-shell-content-min-width', 640),
       aside: px('--nile-app-shell-aside-width', 320),
       panel: px('--nile-app-shell-panel-width', 480),
     };
   }
 
-  /**
-   * 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(geo: ShellGeometry, track: number): number {
     const nav = this._hasSideNav ? track : 0;
     const aside = this._hasAside ? geo.aside + geo.gutter : 0;
-    // Two gutters of padding on the content column, one between container and
-    // panel; the aside carries its own gutter above.
-    return nav + geo.content + aside + geo.panel + geo.gutter * 3;
+    /* The content row's chrome is end-edge padding plus one flex gap between container and panel (an aside carries its own gap above), and start-edge padding too when no nav track is there to sit flush against. */
+    const gutters = this._hasSideNav ? 2 : 3;
+    return nav + geo.content + aside + geo.panel + geo.gutter * gutters;
   }
 
   private _recompute(): void {
     const width = this._width;
     const geo = this._geometry();
 
-    /*
-     * Overlay is opt-in and nothing derives it: a panel that covers the page
-     * hides the thing the user is asking about. Running out of room is not a
-     * reason to switch — the rail and the panel's own min width absorb that —
-     * so the shell only overlays below a width the author names.
-     */
+    /* Overlay is opt-in: the shell only overlays below a width the author names, never from running out of room. */
     const overlay =
       this.overlayBreakpoint > 0 && width > 0 && width < this.overlayBreakpoint;
     const mode: NileAppShellPanelMode = overlay ? 'overlay' : 'docked';
 
-    // A docked panel squeezes the container, so a narrow shell trades the
-    // expanded nav for content width before the page gives any up. Measured
-    // against the expanded track: the nav rails exactly when it is the track
-    // that stops the row from fitting.
+    // A docked panel squeezes the container, so a narrow shell trades the expanded nav for content width, measured against the expanded track.
     const railAt = Math.max(
       this.dockedRailBreakpoint,
       this._dockRequirement(geo, geo.nav)
@@ -646,7 +639,7 @@ export class NileAppShell extends NileElement {
     return html`
       <div class="nav-toggle-group">
         <nile-button
-          class="nav-toggle"
+          class="nav-toggle utility-control"
           part="nav-toggle"
           variant="ghost"
           circle
@@ -662,12 +655,98 @@ export class NileAppShell extends NileElement {
           @click=${() => this.toggleNav()}
         >
           ${renderGlyph(
-            expanded ? 'ng-panel-left-close' : 'ng-panel-left-open',
-            24,
+            expanded ? 'ng-panel-left' : 'ng-panel-right',
+            20,
             'currentColor'
           )}
         </nile-button>
-        ${this._hasTopBar ? html`<span class="rule" part="rule"></span>` : ''}
+        ${this._hasTopBar || this._hasTitleBlock
+          ? html`<span class="rule" part="rule"></span>`
+          : ''}
+      </div>
+    `;
+  }
+
+  /** Whether the header has a title block of its own to draw: only a title or a leading control mounts it. */
+  private get _hasTitleBlock(): boolean {
+    return !!this.pageTitle || this._hasLeading;
+  }
+
+  /** Whether `leading` names a control that renders; an empty or unknown value draws nothing, like `none`. */
+  private get _hasLeading(): boolean {
+    return this.leading === 'back' || this.leading === 'app-icon';
+  }
+
+  /** `headingLevel` as a safe `aria-level`: a whole number clamped to 1–6, and 1 for anything non-numeric. */
+  private get _headingLevel(): number {
+    const level = Math.trunc(Number(this.headingLevel));
+    return Number.isFinite(level) ? Math.min(6, Math.max(1, level)) : 1;
+  }
+
+  private _renderLeading(): TemplateResult | string {
+    if (this.leading === 'app-icon') {
+      return html`
+        <span class="app-icon" part="app-icon">
+          <slot name="app-icon"></slot>
+        </span>
+      `;
+    }
+
+    if (this.leading === 'back') {
+      return html`
+        <button
+          class="back"
+          part="back"
+          type="button"
+          @click=${() => this.goBackHeader()}
+        >
+          ${renderGlyph('ng-chevron-left', 20, 'currentColor')}
+          <span>${this.backLabel}</span>
+        </button>
+        ${this.pageTitle
+          ? html`<span class="crumb-divider" aria-hidden="true">
+              ${renderGlyph('ng-slash', 16, 'currentColor')}
+            </span>`
+          : ''}
+      `;
+    }
+
+    return '';
+  }
+
+  private _renderTitleBlock(): TemplateResult | string {
+    if (!this._hasTitleBlock) return '';
+
+    /* Both leading modes render beside the title stack, never inside the title row, so the description stays under the page title in every leading mode. */
+    return html`
+      <div class="title-area" part="title-area">
+        ${this._hasLeading
+          ? html`<span class="leading" part="leading"
+              >${this._renderLeading()}</span
+            >`
+          : ''}
+        ${this.pageTitle
+          ? html`
+              <div class="title-stack">
+                <div class="title-row">
+                  <div
+                    class="page-title"
+                    part="page-title"
+                    role="heading"
+                    aria-level=${this._headingLevel}
+                  >${this.pageTitle}</div>
+                  ${this.badge
+                    ? html`<span class="badge" part="badge">${this.badge}</span>`
+                    : ''}
+                </div>
+                ${this.description
+                  ? html`<p class="description" part="description">
+                      ${this.description}
+                    </p>`
+                  : ''}
+              </div>
+            `
+          : ''}
       </div>
     `;
   }
@@ -682,6 +761,7 @@ export class NileAppShell extends NileElement {
       >
         ${this._renderNavToggle()}
         <div class="top-bar-content">
+          ${this._renderTitleBlock()}
           <slot
             name="top-bar"
             @slotchange=${(e: Event) => this._onSlotChange('top-bar', e)}
@@ -784,6 +864,19 @@ export class NileAppShell extends NileElement {
               ></slot>`
             : html`
                 <header class="panel-header" part="panel-header">
+                  ${this.panelBack
+                    ? html`<nile-button
+                        class="panel-back utility-control"
+                        part="panel-back"
+                        variant="ghost"
+                        circle
+                        title=${this.panelBackLabel}
+                        aria-label=${this.panelBackLabel}
+                        @click=${() => this.goBackPanel()}
+                      >
+                        ${renderGlyph('ng-arrow-left', 20, 'currentColor')}
+                      </nile-button>`
+                    : ''}
                   <slot name="panel-header">
                     <span class="panel-heading">
                       <span class="panel-mark">
@@ -797,7 +890,7 @@ export class NileAppShell extends NileElement {
                   <div class="panel-actions" part="panel-actions">
                     <slot name="panel-actions"></slot>
                     <nile-button
-                      class="panel-close"
+                      class="panel-close utility-control"
                       part="panel-close"
                       variant="ghost"
                       circle
@@ -805,7 +898,7 @@ export class NileAppShell extends NileElement {
                       aria-label="Close ${this.panelLabel}"
                       @click=${() => this.closePanel()}
                     >
-                      ${renderGlyph('ng-x-close', 24, 'currentColor')}
+                      ${renderGlyph('ng-x-close', 20, 'currentColor')}
                     </nile-button>
                   </div>
                 </header>

package/src/nile-app-shell/shell-controller.ts

@@ -15,14 +15,7 @@ const SHELL_EVENTS = [
   'nile-panel-mode-change',
 ];
 
-/**
- * A reactive controller that links a region component to its shell.
- *
- * Region components sit in the shell's light DOM, so the shell is just an
- * ancestor — `closest()` finds it. The shell may upgrade after its children do,
- * so the lookup is deferred to a microtask and retried on demand. While linked,
- * the host re-renders whenever the shell's nav or panel state changes.
- */
+/** A reactive controller that links a region component to its shell, re-rendering the host when the shell's nav or panel state changes. */
 export class AppShellController implements ReactiveController {
   host: ReactiveControllerHost & HTMLElement;
 
@@ -62,12 +55,7 @@ export class AppShellController implements ReactiveController {
     SHELL_EVENTS.forEach(name =>
       found.addEventListener(name, this.handleShellChange)
     );
-    /*
-     * Not every state a region renders from has an event. Panel availability
-     * flips when the panel slot fills, which emits nothing — a header would
-     * render its Ask button hidden and never re-render. The shell reflects that
-     * state onto itself, so watching its attributes covers the whole surface.
-     */
+    /* Not every state a region renders from has an event, so watch the shell's reflected attributes to cover the whole surface. */
     this.observer = new MutationObserver(this.handleShellChange);
     this.observer.observe(found, { attributes: true });
     return true;

package/src/nile-app-shell-main/nile-app-shell-main.ts

@@ -11,9 +11,7 @@ import { styles } from './nile-app-shell-main.css';
 import NileElement from '../internal/nile-element';
 
 /**
- * @summary The shell's centre region — the page body. Goes in the shell's
- * default slot and declares the size query container that page CSS sizes
- * against, which the shell itself cannot do across its shadow boundary.
+ * @summary The shell's centre region — the page body; declares the size query container that page CSS sizes against.
  *
  * @status stable
  * @since 2.0
@@ -24,9 +22,7 @@ import NileElement from '../internal/nile-element';
  *
  * @slot - The page body.
  *
- * @attr no-container - Drops the query container. Size containment makes this a
- *   containing block for absolutely and fixed-positioned descendants; set this
- *   when page content needs to escape to the viewport instead.
+ * @attr no-container - Drops the query container, so page content can escape to the viewport.
  */
 @customElement('nile-app-shell-main')
 export class NileAppShellMain extends NileElement {