@aquera/nile-elements 2.0.11 → 2.0.12

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

@@ -13,8 +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';
+/** The `detail` of the `nile-click` the header back control emits. */
+export interface NileAppShellClickDetail {
+    value: 'back';
+}
 /**
  * @summary The application frame every route inherits: a side nav, a content container, an optional aside and an AI assistant panel.
  *
@@ -31,7 +33,7 @@ export type NileAppShellLeading = 'none' | 'back' | 'app-icon';
  * @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.
- * @slot app-icon - The mark shown when `leading="app-icon"`, clipped to the shell's box.
+ * @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 empty the panel is unmounted and `openPanel()` is a no-op.
@@ -42,7 +44,7 @@ export type NileAppShellLeading = 'none' | 'back' | 'app-icon';
  * @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-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.
@@ -51,15 +53,15 @@ export type NileAppShellLeading = 'none' | 'back' | 'app-icon';
  * @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 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.
- * @csspart title-area - The header's own title block: leading, title, badge and description.
+ * @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 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 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.
@@ -91,7 +93,7 @@ export type NileAppShellLeading = 'none' | 'back' | 'app-icon';
  * @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-app-icon-size=20px] - The leading app icon's box.
+ * @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.
@@ -103,9 +105,8 @@ export type NileAppShellLeading = 'none' | 'back' | 'app-icon';
  * @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 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 goBackPage() - Deprecated alias of `goBackHeader()`.
  * @method goBack() - Deprecated alias of `goBackPanel()`.
  */
 export declare class NileAppShell extends NileElement {
@@ -126,10 +127,10 @@ export declare class NileAppShell extends NileElement {
     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;
+    /** Shows the back arrow before the page title; pressing it emits `nile-click` with `{ value: 'back' }`. Independent of the `app-icon` slot. */
+    headerBack: boolean;
+    /** Accessible name of the header back control. Never rendered as visible text. */
+    headerBackLabel: 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. */
@@ -175,6 +176,7 @@ export declare class NileAppShell extends NileElement {
     private _hasTopBar;
     private _hasTopBarActions;
     private _hasTabs;
+    private _hasAppIcon;
     private _hasPanel;
     private _hasPanelFooter;
     /** True when a `nile-app-shell-panel` is slotted, owning the panel's own chrome so the shell renders a bare region. */
@@ -206,12 +208,10 @@ export declare class NileAppShell extends NileElement {
     closePanel(): void;
     /** 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. */
+    /** Emit `nile-click` with `{ value: '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. */
@@ -241,13 +241,13 @@ 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. */
+    /** Whether the header has a title block of its own to draw: a title, the back arrow or a slotted app icon 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 _renderBack;
+    private _renderAppIconSlot;
+    private _renderAppIconProbe;
     private _renderTitleBlock;
     private _renderTopBar;
     render(): TemplateResult;

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

@@ -28,7 +28,7 @@ import '../nile-button/nile-button';
  * @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.
- * @slot app-icon - The mark shown when `leading="app-icon"`, clipped to the shell's box.
+ * @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 empty the panel is unmounted and `openPanel()` is a no-op.
@@ -39,7 +39,7 @@ import '../nile-button/nile-button';
  * @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-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.
@@ -48,15 +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 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.
- * @csspart title-area - The header's own title block: leading, title, badge and description.
+ * @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 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 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.
@@ -88,7 +88,7 @@ import '../nile-button/nile-button';
  * @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-app-icon-size=20px] - The leading app icon's box.
+ * @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.
@@ -100,9 +100,8 @@ 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-header-back`, as the header's back control does.
+ * @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 goBackPage() - Deprecated alias of `goBackHeader()`.
  * @method goBack() - Deprecated alias of `goBackPanel()`.
  */
 let NileAppShell = class NileAppShell extends NileElement {
@@ -118,10 +117,10 @@ let NileAppShell = class NileAppShell extends NileElement {
         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;
-        /** 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. */
-        this.leading = 'none';
-        /** The previous-page label drawn by `leading="back"`. */
-        this.backLabel = 'Back';
+        /** 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. */
@@ -165,6 +164,7 @@ 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, owning the panel's own chrome so the shell renders a bare region. */
@@ -261,6 +261,7 @@ let NileAppShell = class NileAppShell extends NileElement {
         // 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.tabsVisible);
         this.toggleAttribute('has-aside', this._hasAside);
@@ -288,18 +289,15 @@ let NileAppShell = class NileAppShell extends NileElement {
         else
             this.closePanel();
     }
-    /** Emit `nile-header-back`, as the header's back control does; the page owns the history. */
+    /** Emit `nile-click` with `{ value: 'back' }`, as the header's back control does; the page owns the history. */
     goBackHeader() {
-        this.emit('nile-header-back');
+        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 `goBackHeader()`; kept as an alias that emits `nile-header-back`. */
-    goBackPage() {
-        this.goBackHeader();
-    }
     /** @deprecated Use `goBackPanel()`; kept as an alias that emits `nile-panel-back`. */
     goBack() {
         this.goBackPanel();
@@ -464,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;
@@ -510,80 +511,83 @@ let NileAppShell = class NileAppShell extends NileElement {
       </div>
     `;
     }
-    /** Whether the header has a title block of its own to draw: only a title or a leading control mounts it. */
+    /** 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._hasLeading;
-    }
-    /** Whether `leading` names a control that renders; an empty or unknown value draws nothing, like `none`. */
-    get _hasLeading() {
-        return this.leading === 'back' || this.leading === 'app-icon';
+        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;
     }
-    _renderLeading() {
-        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 `
+    _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-chevron-left', 20, 'currentColor')}
-          <span>${this.backLabel}</span>
+          ${renderGlyph('ng-arrow-narrow-left', 20, 'currentColor')}
         </button>
-        ${this.pageTitle
-                ? html `<span class="crumb-divider" aria-hidden="true">
-              ${renderGlyph('ng-slash', 16, 'currentColor')}
-            </span>`
-                : ''}
-      `;
-        }
-        return '';
+      </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 '';
-        /* 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 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._hasLeading
-            ? html `<span class="leading" part="leading"
-              >${this._renderLeading()}</span
-            >`
+        ${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
-            ? 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>
-            `
+            ${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>
     `;
     }
@@ -606,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">
@@ -774,11 +781,11 @@ __decorate([
     property({ type: String, attribute: true, reflect: true })
 ], NileAppShell.prototype, "badge", void 0);
 __decorate([
-    property({ type: String, attribute: true, reflect: true })
-], NileAppShell.prototype, "leading", void 0);
+    property({ type: Boolean, attribute: true, reflect: true })
+], NileAppShell.prototype, "headerBack", void 0);
 __decorate([
     property({ type: String, attribute: true, reflect: true })
-], NileAppShell.prototype, "backLabel", void 0);
+], NileAppShell.prototype, "headerBackLabel", void 0);
 __decorate([
     property({ type: Boolean, reflect: true, attribute: 'no-nav-toggle' })
 ], NileAppShell.prototype, "noNavToggle", void 0);
@@ -854,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);