@aquera/nile-elements 2.0.10 → 2.0.12

package/dist/src/nile-app-shell/nile-app-shell.js

@@ -13,9 +13,7 @@ import { renderGlyph } from '../internal/glyph';
 import NileElement from '../internal/nile-element';
 import '../nile-button/nile-button';
 /**
- * @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
@@ -27,29 +25,22 @@ import '../nile-button/nile-button';
  *
  * @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 before the page title whenever this slot has content, 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-click - Emitted when the header's back control is pressed, or `goBackHeader()` is called. `detail: { value: 'back' }`. Emitted on the shell itself, so check `event.target === shell` as well as the value: a `nile-click` from page content bubbles through the shell too.
+ * @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.
@@ -57,12 +48,15 @@ import '../nile-button/nile-button';
  * @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 ask-rule - The vertical rule before the Ask button, drawn when `top-bar-actions` has content.
+ * @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: back control, app icon, 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 back - The header back control, shown by `headerBack`.
+ * @csspart app-icon - The block holding the `app-icon` slot, shown when the slot has content and 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.
@@ -71,42 +65,32 @@ import '../nile-button/nile-button';
  * @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 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.
  *
@@ -116,24 +100,27 @@ import '../nile-button/nile-button';
  * @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-click` with `{ value: 'back' }`, as the header's back control does.
+ * @method goBackPanel() - Emit `nile-panel-back`, as the panel's back control does.
+ * @method goBack() - Deprecated alias of `goBackPanel()`.
  */
 let NileAppShell = class NileAppShell extends NileElement {
     constructor() {
         super(...arguments);
-        /**
-         * 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`. */
         this.navCollapsed = false;
         /** Whether the AI panel is open. */
         this.panelOpen = 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. */
         this.noPanel = false;
         /** The default panel heading. Ignored when `panel-header` is slotted. */
         this.panelLabel = 'Ask Aquera';
+        /** 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. */
+        this.headingLevel = 1;
+        /** Shows the back arrow before the page title; pressing it emits `nile-click` with `{ value: 'back' }`. Independent of the `app-icon` slot. */
+        this.headerBack = false;
+        /** Accessible name of the header back control. Never rendered as visible text. */
+        this.headerBackLabel = 'Back';
         /** Hides the built-in nav toggle. Mount `nile-app-shell-nav-toggle` yourself. */
         this.noNavToggle = false;
         /** Drops the Cmd/Ctrl+J and Escape panel shortcuts. */
@@ -146,48 +133,27 @@ let NileAppShell = class NileAppShell extends NileElement {
         this.topBarPlacement = 'content';
         /** `centered` caps the page body at `--nile-app-shell-centered-width`. */
         this.contentAlign = '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. */
         this.contentContainer = false;
         /** Drops the container's card chrome for a full-bleed page. */
         this.flat = false;
         /** Removes the container's inner padding. */
         this.noPadding = 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. */
         this.askLabel = 'Ask';
         /** Drops the built-in Ask button, for a bar that renders its own. */
         this.noAsk = false;
+        /** Shows a back control at the start of the panel header for a panel sub-view; emits `nile-panel-back`. */
+        this.panelBack = false;
+        /** Accessible name of the panel's back control. */
+        this.panelBackLabel = 'Back';
+        /** Hides the tab strip for this route even when the `tabs` slot is filled. */
+        this.noTabs = false;
         /** Sizes the shell to the viewport instead of its parent. */
         this.fullHeight = 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. */
         this.overlayBreakpoint = 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. */
         this.dockedRailBreakpoint = 1440;
         /** The panel's current mode. Derived from the shell's width. */
         this._panelMode = 'docked';
@@ -198,14 +164,10 @@ let NileAppShell = class NileAppShell extends NileElement {
         this._hasTopBar = false;
         this._hasTopBarActions = false;
         this._hasTabs = false;
+        this._hasAppIcon = false;
         this._hasPanel = false;
         this._hasPanelFooter = 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. */
         this._panelOwnsChrome = false;
         this._hasAside = false;
         this._width = 0;
@@ -247,6 +209,10 @@ let NileAppShell = class NileAppShell extends NileElement {
     get panelAvailable() {
         return this._hasPanel && !this.noPanel;
     }
+    /** Whether the tab strip is rendered: something slotted, and not switched off. */
+    get tabsVisible() {
+        return this._hasTabs && !this.noTabs;
+    }
     /** Whether the built-in Ask button is rendered. */
     get askVisible() {
         return this.panelAvailable && !this.noAsk;
@@ -276,8 +242,7 @@ let NileAppShell = 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.has('_hasAside') ||
             changed.has('_hasSideNav')) {
             this._recompute();
@@ -290,10 +255,15 @@ let NileAppShell = class NileAppShell extends NileElement {
         this.toggleAttribute('nav-locked', this._navLocked);
         this.toggleAttribute('has-banner', this._hasBanner);
         this.toggleAttribute('has-side-nav', this._hasSideNav);
-        this.toggleAttribute('has-top-bar', this._hasTopBar || (!this.noNavToggle && this._hasSideNav));
+        this.toggleAttribute('has-top-bar', 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-app-icon', this._hasAppIcon);
         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);
@@ -311,11 +281,7 @@ let NileAppShell = class NileAppShell extends NileElement {
     closePanel() {
         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. */
     togglePanel(force) {
         const next = force ?? !this.panelOpen;
         if (next)
@@ -323,6 +289,19 @@ let NileAppShell = class NileAppShell extends NileElement {
         else
             this.closePanel();
     }
+    /** Emit `nile-click` with `{ value: 'back' }`, as the header's back control does; the page owns the history. */
+    goBackHeader() {
+        const detail = { value: 'back' };
+        this.emit('nile-click', detail);
+    }
+    /** Emit `nile-panel-back`, as the panel's back control does; the page owns the view stack. */
+    goBackPanel() {
+        this.emit('nile-panel-back');
+    }
+    /** @deprecated Use `goBackPanel()`; kept as an alias that emits `nile-panel-back`. */
+    goBack() {
+        this.goBackPanel();
+    }
     /** Expand the side nav. */
     expandNav() {
         this._setNavCollapsed(false);
@@ -371,11 +350,7 @@ let NileAppShell = class NileAppShell extends NileElement {
                 this.openPanel();
         }
     }
-    /**
-     * 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. */
     _geometry() {
         const style = getComputedStyle(this);
         const px = (name, fallback) => {
@@ -383,46 +358,30 @@ let NileAppShell = 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. */
     _dockRequirement(geo, track) {
         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;
     }
     _recompute() {
         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 = 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));
         const squeezed = !overlay &&
             this.panelOpen &&
@@ -503,6 +462,9 @@ let NileAppShell = class NileAppShell extends NileElement {
             case 'tabs':
                 this._hasTabs = filled;
                 break;
+            case 'app-icon':
+                this._hasAppIcon = filled;
+                break;
             case 'aside':
                 this._hasAside = filled;
                 break;
@@ -526,7 +488,7 @@ let NileAppShell = 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
@@ -541,9 +503,91 @@ let NileAppShell = class NileAppShell extends NileElement {
           aria-label=${expanded ? 'Collapse navigation' : 'Expand navigation'}
           @click=${() => this.toggleNav()}
         >
-          ${renderGlyph(expanded ? 'ng-panel-left-close' : 'ng-panel-left-open', 24, 'currentColor')}
+          ${renderGlyph(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: a title, the back arrow or a slotted app icon mounts it. */
+    get _hasTitleBlock() {
+        return !!this.pageTitle || this.headerBack || this._hasAppIcon;
+    }
+    /** `headingLevel` as a safe `aria-level`: a whole number clamped to 1–6, and 1 for anything non-numeric. */
+    get _headingLevel() {
+        const level = Math.trunc(Number(this.headingLevel));
+        return Number.isFinite(level) ? Math.min(6, Math.max(1, level)) : 1;
+    }
+    _renderBack() {
+        if (!this.headerBack)
+            return '';
+        return html `
+      <span class="back-line">
+        <button
+          class="back"
+          part="back"
+          type="button"
+          aria-label=${this.headerBackLabel}
+          title=${this.headerBackLabel}
+          @click=${() => this.goBackHeader()}
+        >
+          ${renderGlyph('ng-arrow-narrow-left', 20, 'currentColor')}
+        </button>
+      </span>
+    `;
+    }
+    _renderAppIconSlot() {
+        return html `<slot
+      name="app-icon"
+      @slotchange=${(e) => this._onSlotChange('app-icon', e)}
+    ></slot>`;
+    }
+    /* The app-icon slot has to exist whenever the stack does not, or a slotted icon could never mount it: park it, hidden. */
+    _renderAppIconProbe() {
+        return html `<span class="app-icon-probe" hidden
+      >${this._renderAppIconSlot()}</span
+    >`;
+    }
+    _renderTitleBlock() {
+        if (!this._hasTitleBlock)
+            return this._renderAppIconProbe();
+        /* The stack is the title and/or the app icon; a back arrow on its own brings no empty stack. */
+        if (!this.pageTitle && !this._hasAppIcon) {
+            return html `
+        <div class="title-area" part="title-area">
+          ${this._renderBack()} ${this._renderAppIconProbe()}
+        </div>
+      `;
+        }
+        /* The back arrow sits beside the stack; the app icon starts the stack's first row, so the description lines up under the icon when there is one and under the title when not. */
+        return html `
+      <div class="title-area" part="title-area">
+        ${this._renderBack()}
+        <div class="title-stack">
+          <div class="title-row">
+            <span class="app-icon" part="app-icon"
+              >${this._renderAppIconSlot()}</span
+            >
+            ${this.pageTitle
+            ? html `<div
+                  class="page-title"
+                  part="page-title"
+                  role="heading"
+                  aria-level=${this._headingLevel}
+                >${this.pageTitle}</div>`
+            : ''}
+            ${this.pageTitle && this.badge
+            ? html `<span class="badge" part="badge">${this.badge}</span>`
+            : ''}
+          </div>
+          ${this.pageTitle && this.description
+            ? html `<p class="description" part="description">
+                ${this.description}
+              </p>`
+            : ''}
+        </div>
       </div>
     `;
     }
@@ -555,6 +599,7 @@ let NileAppShell = class NileAppShell extends NileElement {
       >
         ${this._renderNavToggle()}
         <div class="top-bar-content">
+          ${this._renderTitleBlock()}
           <slot
             name="top-bar"
             @slotchange=${(e) => this._onSlotChange('top-bar', e)}
@@ -565,13 +610,16 @@ let NileAppShell = class NileAppShell extends NileElement {
             name="top-bar-actions"
             @slotchange=${(e) => this._onSlotChange('top-bar-actions', e)}
           ></slot>
+          ${this.askVisible && this._hasTopBarActions
+            ? html `<span class="rule ask-rule" part="ask-rule"></span>`
+            : ''}
           ${this.askVisible
             ? html `
                 <nile-button
                   class="ask"
                   part="ask"
                   exportparts="base: ask__base, label: ask__label"
-                  variant="primary"
+                  variant="secondary"
                   @click=${() => this.openPanel()}
                 >
                   <span slot="prefix" class="ask-mark">
@@ -652,6 +700,19 @@ let NileAppShell = 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">
@@ -665,7 +726,7 @@ let NileAppShell = 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
@@ -673,7 +734,7 @@ let NileAppShell = 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>
@@ -707,6 +768,24 @@ __decorate([
 __decorate([
     property({ type: String, attribute: 'panel-label' })
 ], NileAppShell.prototype, "panelLabel", void 0);
+__decorate([
+    property({ type: String, attribute: true, reflect: true })
+], NileAppShell.prototype, "pageTitle", void 0);
+__decorate([
+    property({ type: Number, attribute: true, reflect: true })
+], NileAppShell.prototype, "headingLevel", void 0);
+__decorate([
+    property({ type: String, attribute: true, reflect: true })
+], NileAppShell.prototype, "description", void 0);
+__decorate([
+    property({ type: String, attribute: true, reflect: true })
+], NileAppShell.prototype, "badge", void 0);
+__decorate([
+    property({ type: Boolean, attribute: true, reflect: true })
+], NileAppShell.prototype, "headerBack", void 0);
+__decorate([
+    property({ type: String, attribute: true, reflect: true })
+], NileAppShell.prototype, "headerBackLabel", void 0);
 __decorate([
     property({ type: Boolean, reflect: true, attribute: 'no-nav-toggle' })
 ], NileAppShell.prototype, "noNavToggle", void 0);
@@ -740,6 +819,15 @@ __decorate([
 __decorate([
     property({ type: Boolean, reflect: true, attribute: 'no-ask' })
 ], NileAppShell.prototype, "noAsk", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], NileAppShell.prototype, "panelBack", void 0);
+__decorate([
+    property({ type: String })
+], NileAppShell.prototype, "panelBackLabel", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], NileAppShell.prototype, "noTabs", void 0);
 __decorate([
     property({ type: Boolean, reflect: true, attribute: 'full-height' })
 ], NileAppShell.prototype, "fullHeight", void 0);
@@ -773,6 +861,9 @@ __decorate([
 __decorate([
     state()
 ], NileAppShell.prototype, "_hasTabs", void 0);
+__decorate([
+    state()
+], NileAppShell.prototype, "_hasAppIcon", void 0);
 __decorate([
     state()
 ], NileAppShell.prototype, "_hasPanel", void 0);