@aquera/nile-elements 2.0.10 → 2.0.12

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 {

package/src/nile-app-shell-nav-toggle/nile-app-shell-nav-toggle.css.ts

@@ -6,11 +6,9 @@
  */
 
 import { css } from 'lit';
+import { utilityControlStyles } from '../internal/app-shell-utility-control-styles';
 
-/**
- * AppShellNavToggle CSS. The button itself is the shared utility recipe; this
- * file only handles the host box and the rule.
- */
+/** AppShellNavToggle CSS: the host box, the rule, and the utility-control recipe, since this element also mounts outside a shell. */
 export const styles = css`
   :host {
     display: inline-flex;
@@ -22,10 +20,14 @@ export const styles = css`
     display: none;
   }
 
+  /* Lands the 20px glyph box, not the 32px utility circle, on the 24px origin: (32 - 20) / 2 = 6. */
   .toggle {
-    margin-inline-start: var(--nile-app-shell-nav-toggle-offset, -7px);
+    margin-inline-start: var(--nile-app-shell-nav-toggle-offset, -6px);
   }
 
+  /* The toggle itself: the shared utility-control recipe. */
+  ${utilityControlStyles}
+
   .rule {
     flex: 0 0 auto;
     width: var(--nile-border-width-1, var(--ng-border-width-1));

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

@@ -14,9 +14,7 @@ import NileElement from '../internal/nile-element';
 import type { NileAppShell } from '../nile-app-shell/nile-app-shell';
 
 /**
- * @summary The side-nav toggle, as a standalone control. `nile-app-shell`
- * renders one in its own top bar; mount this in a header you build yourself, or
- * a route has no way to expand the rail.
+ * @summary The side-nav toggle as a standalone control, for a header you build yourself.
  *
  * @status stable
  * @since 2.0
@@ -29,7 +27,8 @@ import type { NileAppShell } from '../nile-app-shell/nile-app-shell';
  * @csspart button - The toggle button.
  * @csspart rule - The trailing vertical rule.
  *
- * @cssproperty [--nile-app-shell-nav-toggle-offset=-4px] - Optical start offset.
+ * @cssproperty [--nile-app-shell-nav-toggle-offset=-6px] - Optical start offset, so the glyph lands on the bar's text origin.
+ * @cssproperty [--nile-app-shell-utility-size=32px] - Box the toggle sits in; the hit area and hover surface, not a visible chip.
  */
 @customElement('nile-app-shell-nav-toggle')
 export class NileAppShellNavToggle extends NileElement {
@@ -41,10 +40,7 @@ export class NileAppShellNavToggle extends NileElement {
   @property({ type: Boolean, reflect: true, attribute: 'with-rule' })
   withRule: boolean = false;
 
-  /**
-   * The shell to drive. Defaults to the nearest `nile-app-shell` ancestor, or
-   * the element with this id.
-   */
+  /** The shell to drive. Defaults to the nearest `nile-app-shell` ancestor, or the element with this id. */
   @property({ type: String })
   shell?: string;
 
@@ -98,7 +94,7 @@ export class NileAppShellNavToggle extends NileElement {
     const expanded = !this._rail;
     return html`
       <nile-button
-        class="toggle"
+        class="toggle utility-control"
         part="button"
         variant="ghost"
         circle
@@ -113,8 +109,8 @@ export class NileAppShellNavToggle extends NileElement {
         @click=${this._onClick}
       >
         ${renderGlyph(
-          expanded ? 'ng-panel-left-close' : 'ng-panel-left-open',
-          24,
+          expanded ? 'ng-panel-left' : 'ng-panel-right',
+          20,
           'currentColor'
         )}
       </nile-button>

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

@@ -6,6 +6,7 @@
  */
 
 import { css } from 'lit';
+import { utilityControlStyles } from '../internal/app-shell-utility-control-styles';
 
 export const styles = css`
   :host {
@@ -23,14 +24,15 @@ export const styles = css`
     display: none;
   }
 
+  /* The panel header keeps its own height, never the page header's; the literal is the floor for a panel mounted outside a shell. */
   .header {
     box-sizing: border-box;
     flex: 0 0 auto;
     display: flex;
     align-items: center;
-    gap: var(--nile-spacing-lg, var(--ng-spacing-lg));
-    height: var(--nile-app-shell-top-bar-height, 56px);
-    padding-inline: var(--nile-spacing-xl, var(--ng-spacing-xl));
+    gap: var(--nile-spacing-md, var(--ng-spacing-md));
+    height: var(--nile-app-shell-panel-header-height, 56px);
+    padding-inline: var(--nile-spacing-3xl, var(--ng-spacing-3xl));
     border-bottom: var(--nile-border-width-1, var(--ng-border-width-1)) solid
       var(--nile-colors-neutral-400, var(--ng-colors-border-secondary));
   }
@@ -39,6 +41,21 @@ export const styles = css`
     display: none;
   }
 
+  /* The back control for a sub-view; stands where the brand mark does in the root view. */
+  .back {
+    flex: 0 0 auto;
+    margin-inline-start: -6px;
+  }
+
+  /* Mirrors the back control's offset on the end edge: the 20px glyph, not the 32px circle, lands on the padding line. */
+  .close {
+    margin-inline-end: -6px;
+  }
+
+  :host([back]) .mark {
+    display: none;
+  }
+
   .heading {
     display: flex;
     align-items: center;
@@ -63,7 +80,9 @@ export const styles = css`
 
   .title {
     margin: 0;
-    font-size: var(--nile-type-scale-3, var(--ng-font-size-text-sm));
+    /* Figma's Assistant Title: Text lg/Semibold, 18/28 on NxtGen. Enterprise keeps --nile-type-scale-3, and it defines no --ng-* tokens, so the line-height declaration is invalid there and the title inherits its line height exactly as before. */
+    font-size: var(--nile-type-scale-3, var(--ng-font-size-text-lg));
+    line-height: var(--ng-line-height-text-lg);
     font-weight: var(
       --nile-font-weight-semi-bold,
       var(--ng-font-weight-semibold)
@@ -85,6 +104,11 @@ export const styles = css`
     display: none;
   }
 
+  /* ------------------------------------------------------- utility controls */
+
+  /* The header's own icon controls (back and close): the shared utility-control recipe. */
+  ${utilityControlStyles}
+
   .body {
     flex: 1 1 auto;
     min-height: 0;
@@ -92,7 +116,8 @@ export const styles = css`
     display: flex;
     flex-direction: column;
     gap: var(--nile-spacing-xl, var(--ng-spacing-xl));
-    padding: var(--nile-spacing-xl, var(--ng-spacing-xl));
+    /* 16 under the header, 24 on the sides and bottom. */
+    padding: var(--nile-spacing-xl, var(--ng-spacing-xl)) var(--nile-spacing-3xl, var(--ng-spacing-3xl)) var(--nile-spacing-3xl, var(--ng-spacing-3xl));
   }
 
   :host([no-padding]) .body {
@@ -101,7 +126,7 @@ export const styles = css`
 
   .footer {
     flex: 0 0 auto;
-    padding: var(--nile-spacing-xl, var(--ng-spacing-xl));
+    padding: var(--nile-spacing-xl, var(--ng-spacing-xl)) var(--nile-spacing-3xl, var(--ng-spacing-3xl)) var(--nile-spacing-3xl, var(--ng-spacing-3xl));
     border-top: var(--nile-border-width-1, var(--ng-border-width-1)) solid
       var(--nile-colors-neutral-400, var(--ng-colors-border-secondary));
   }

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

@@ -15,10 +15,7 @@ import NileElement from '../internal/nile-element';
 import type { NileAppShellPanelMode } from '../nile-app-shell/nile-app-shell';
 
 /**
- * @summary The shell's right region — the AI assistant panel. Assigns itself to
- * the shell's `panel` slot and takes over the panel chrome: heading, actions,
- * close button, scroll region and composer footer. The shell keeps the geometry
- * — 480px docked, an overlay drawer when narrow — and the open/closed state.
+ * @summary The shell's right region — the AI assistant panel; takes over the panel chrome while the shell keeps the geometry and open state.
  *
  * @status stable
  * @since 2.0
@@ -29,20 +26,25 @@ import type { NileAppShellPanelMode } from '../nile-app-shell/nile-app-shell';
  * @dependency nile-glyph
  *
  * @slot - The panel body. Scrolls.
- * @slot header - Replaces the default heading (mark plus label).
- * @slot actions - Controls added before the close button.
+ * @slot header - Replaces the default heading (mark plus label); the back control renders before it.
+ * @slot actions - Controls added before the close button; size and clear their `base` part from page CSS to match the header's bare glyphs.
  * @slot footer - A composer, docked below the scroll region.
  *
- * @event nile-close - Emitted when the close button is pressed, after the shell
- *   has been told to close. Cancelable is not honoured; listen to it to react,
- *   and use `no-close` to own the control yourself.
+ * @event nile-close - Emitted when the close button is pressed, after the shell has been told to close.
+ * @event nile-back - Emitted when the back control is pressed; the page swaps its own content back.
+ * @event nile-panel-back - Emitted right after `nile-back` for the same press, matching the shell's built-in panel chrome, so a page listening on the shell keeps working when it slots this component. Listen for one of the two, not both, or one press is handled twice.
  *
  * @csspart header - The header bar.
+ * @csspart back - The back control, shown by `back`.
  * @csspart title - The default heading text.
  * @csspart actions - The header action group.
  * @csspart close - The close button.
  * @csspart body - The scrolling body.
  * @csspart footer - The footer.
+ *
+ * @cssproperty [--nile-app-shell-utility-size=32px] - Box the header's back and close controls sit in.
+ *
+ * @method goBack() - Emit `nile-back` then `nile-panel-back`, as the back control does.
  */
 @customElement('nile-app-shell-panel')
 export class NileAppShellPanel extends NileElement {
@@ -60,6 +62,14 @@ export class NileAppShellPanel extends NileElement {
   @property({ type: Boolean, reflect: true, attribute: 'no-header' })
   noHeader: boolean = false;
 
+  /** Shows a back control at the start of the header for a sub-view; the panel keeps no view stack and only emits `nile-back`. */
+  @property({ type: Boolean, reflect: true })
+  back: boolean = false;
+
+  /** Accessible name of the back control. */
+  @property({ type: String })
+  backLabel: string = 'Back';
+
   /** Drops the close button — for a panel the page closes its own way. */
   @property({ type: Boolean, reflect: true, attribute: 'no-close' })
   noClose: boolean = false;
@@ -72,10 +82,7 @@ export class NileAppShellPanel extends NileElement {
   @property({ type: String })
   shell?: string;
 
-  /**
-   * Mirrors the shell's panel mode. Set by the shell; treat it as read-only and
-   * style against it (`nile-app-shell-panel[mode='overlay']`).
-   */
+  /** Mirrors the shell's panel mode. Set by the shell; treat it as read-only and style against it (`nile-app-shell-panel[mode='overlay']`). */
   @property({ type: String, reflect: true })
   mode: NileAppShellPanelMode = 'docked';
 
@@ -99,6 +106,12 @@ export class NileAppShellPanel extends NileElement {
     this.setAttribute('aria-label', this.label);
   }
 
+  /** Announce that the back control was pressed, as the page owns which view it goes back to: `nile-back`, then `nile-panel-back` for pages written against the shell's built-in panel chrome. */
+  public goBack(): void {
+    this.emit('nile-back');
+    this.emit('nile-panel-back');
+  }
+
   /** Close the panel through the shell. */
   public close(): void {
     this.shellLink.shell?.closePanel();
@@ -118,16 +131,31 @@ export class NileAppShellPanel extends NileElement {
   public render(): TemplateResult {
     return html`
       <header class="header" part="header">
+        ${this.back
+          ? html`<nile-button
+              class="back utility-control"
+              part="back"
+              variant="ghost"
+              circle
+              title=${this.backLabel}
+              aria-label=${this.backLabel}
+              @click=${() => this.goBack()}
+            >
+              ${renderGlyph('ng-arrow-left', 20, 'currentColor')}
+            </nile-button>`
+          : ''}
         <slot name="header">
           <span class="heading">
-            <span class="mark">${renderGlyph('ng-sparkles', 20, 'currentColor')}</span>
+            <span class="mark"
+              >${renderGlyph('ng-sparkles', 20, 'currentColor')}</span
+            >
             <h2 class="title" part="title">${this.label}</h2>
           </span>
         </slot>
         <div class="actions" part="actions">
           <slot name="actions"></slot>
           <nile-button
-            class="close"
+            class="close utility-control"
             part="close"
             variant="ghost"
             circle
@@ -135,7 +163,7 @@ export class NileAppShellPanel extends NileElement {
             aria-label="Close ${this.label}"
             @click=${() => this.close()}
           >
-            ${renderGlyph('ng-x-close', 24, 'currentColor')}
+            ${renderGlyph('ng-x-close', 20, 'currentColor')}
           </nile-button>
         </div>
       </header>

package/src/nile-app-shell-side-nav/nile-app-shell-side-nav.css.ts

@@ -7,10 +7,7 @@
 
 import { css } from 'lit';
 
-/**
- * AppShellSideNav CSS. The shell owns the track width; this owns what happens
- * inside it — a pinned header, a scrolling body, a pinned footer.
- */
+/** AppShellSideNav CSS: the shell owns the track width, this owns what happens inside it — a pinned header, a scrolling body, a pinned footer. */
 export const styles = css`
   :host {
     box-sizing: border-box;

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

@@ -12,9 +12,7 @@ import { AppShellController } from '../nile-app-shell/shell-controller';
 import NileElement from '../internal/nile-element';
 
 /**
- * @summary The shell's left region — the navigation track. Assigns itself to the
- * shell's `side-nav` slot and mirrors the shell's rail state, so nav content can
- * style against it.
+ * @summary The shell's left region — the navigation track; mirrors the shell's rail state so nav content can style against it.
  *
  * @status stable
  * @since 2.0
@@ -31,10 +29,8 @@ import NileElement from '../internal/nile-element';
  * @csspart body - The scrolling nav body.
  * @csspart footer - The pinned footer.
  *
- * @cssproperty [--nile-app-shell-side-nav-padding=12px] - Body inset. 12 + 40 +
- *   12 is what makes a 64px rail.
- * @cssproperty [--nile-app-shell-side-nav-bg=transparent] - Surface behind the
- *   nav. Transparent by default: the nav and the page share one.
+ * @cssproperty [--nile-app-shell-side-nav-padding=12px] - Body inset.
+ * @cssproperty [--nile-app-shell-side-nav-bg=transparent] - Surface behind the nav; transparent so the nav and page share one.
  */
 @customElement('nile-app-shell-side-nav')
 export class NileAppShellSideNav extends NileElement {
@@ -44,11 +40,7 @@ export class NileAppShellSideNav extends NileElement {
 
   private shellLink = new AppShellController(this);
 
-  /**
-   * Mirrors the shell's effective rail state — the user's preference, or a rail
-   * forced by the shell's width. Set by the shell; treat it as read-only and
-   * style against it (`nile-app-shell-side-nav[collapsed] .label`).
-   */
+  /** Mirrors the shell's effective rail state. Set by the shell; treat it as read-only and style against it (`nile-app-shell-side-nav[collapsed] .label`). */
   @property({ type: Boolean, reflect: true })
   collapsed: boolean = false;