@aquera/nile-elements 2.0.5 → 2.0.6

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

@@ -0,0 +1,100 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { NileAppShell } from './nile-app-shell';
+
+/** Events on the shell that change what a region component renders. */
+const SHELL_EVENTS = [
+  'nile-nav-toggle',
+  'nile-panel-toggle',
+  '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.
+ */
+export class AppShellController implements ReactiveController {
+  host: ReactiveControllerHost & HTMLElement;
+
+  /** Id of the shell to link to. Defaults to the nearest ancestor. */
+  shellId?: string;
+
+  private linked?: NileAppShell;
+  private observer?: MutationObserver;
+
+  constructor(host: ReactiveControllerHost & HTMLElement) {
+    (this.host = host).addController(this);
+  }
+
+  /** The linked shell, resolving it first if it has not been found yet. */
+  get shell(): NileAppShell | null {
+    if (!this.linked) this.link();
+    return this.linked ?? null;
+  }
+
+  hostConnected(): void {
+    // The shell can upgrade after its children; give it a microtask.
+    Promise.resolve().then(() => {
+      if (this.link()) this.host.requestUpdate();
+    });
+  }
+
+  hostDisconnected(): void {
+    this.unlink();
+  }
+
+  /** Resolve the shell and subscribe to it. Returns true when newly linked. */
+  private link(): boolean {
+    const found = this.find();
+    if (!found || found === this.linked) return false;
+    this.unlink();
+    this.linked = found;
+    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.
+     */
+    this.observer = new MutationObserver(this.handleShellChange);
+    this.observer.observe(found, { attributes: true });
+    return true;
+  }
+
+  private unlink(): void {
+    const shell = this.linked;
+    if (!shell) return;
+    SHELL_EVENTS.forEach(name =>
+      shell.removeEventListener(name, this.handleShellChange)
+    );
+    this.observer?.disconnect();
+    this.observer = undefined;
+    this.linked = undefined;
+  }
+
+  private find(): NileAppShell | null {
+    if (this.shellId) {
+      const root = this.host.getRootNode() as Document | ShadowRoot;
+      return root.querySelector<NileAppShell>(`nile-app-shell#${this.shellId}`);
+    }
+    return this.host.closest('nile-app-shell');
+  }
+
+  private handleShellChange = (): void => {
+    this.host.requestUpdate();
+  };
+}
+
+export default AppShellController;

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

@@ -0,0 +1,8 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export * from './nile-app-shell-main';

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

@@ -0,0 +1,29 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { css } from 'lit';
+
+export const styles = css`
+  :host {
+    box-sizing: border-box;
+    display: block;
+    width: 100%;
+    min-width: 0;
+    container-type: inline-size;
+    container-name: nile-content;
+  }
+
+  :host([no-container]) {
+    container-type: normal;
+  }
+
+  :host([hidden]) {
+    display: none;
+  }
+`;
+
+export default [styles];

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

@@ -0,0 +1,52 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { html, CSSResultArray, TemplateResult } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+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.
+ *
+ * @status stable
+ * @since 2.0
+ *
+ * @tag nile-app-shell-main
+ *
+ * @dependency nile-app-shell
+ *
+ * @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.
+ */
+@customElement('nile-app-shell-main')
+export class NileAppShellMain extends NileElement {
+  public static get styles(): CSSResultArray {
+    return [styles];
+  }
+
+  /** Drops the size query container. */
+  @property({ type: Boolean, reflect: true, attribute: 'no-container' })
+  noContainer: boolean = false;
+
+  public render(): TemplateResult {
+    return html`<slot></slot>`;
+  }
+}
+
+export default NileAppShellMain;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nile-app-shell-main': NileAppShellMain;
+  }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export * from './nile-app-shell-nav-toggle';

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

@@ -0,0 +1,44 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { css } from 'lit';
+
+/**
+ * AppShellNavToggle CSS. The button itself is the shared utility recipe; this
+ * file only handles the host box and the rule.
+ */
+export const styles = css`
+  :host {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--nile-spacing-lg, var(--ng-spacing-lg));
+  }
+
+  :host([hidden]) {
+    display: none;
+  }
+
+  .toggle {
+    margin-inline-start: var(--nile-app-shell-nav-toggle-offset, -7px);
+  }
+
+  .rule {
+    flex: 0 0 auto;
+    width: var(--nile-border-width-1, var(--ng-border-width-1));
+    height: 24px;
+    background: var(
+      --nile-colors-neutral-400,
+      var(--ng-colors-border-secondary)
+    );
+  }
+
+  :host(:not([with-rule])) .rule {
+    display: none;
+  }
+`;
+
+export default [styles];

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

@@ -0,0 +1,138 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { html, CSSResultArray, TemplateResult } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { styles } from './nile-app-shell-nav-toggle.css';
+import { renderGlyph } from '../internal/glyph';
+import '../nile-button/nile-button';
+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.
+ *
+ * @status stable
+ * @since 2.0
+ *
+ * @tag nile-app-shell-nav-toggle
+ *
+ * @dependency nile-app-shell
+ * @dependency nile-glyph
+ *
+ * @csspart button - The toggle button.
+ * @csspart rule - The trailing vertical rule.
+ *
+ * @cssproperty [--nile-app-shell-nav-toggle-offset=-4px] - Optical start offset.
+ */
+@customElement('nile-app-shell-nav-toggle')
+export class NileAppShellNavToggle extends NileElement {
+  public static get styles(): CSSResultArray {
+    return [styles];
+  }
+
+  /** Draws the vertical rule the shell's own bar puts after the toggle. */
+  @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.
+   */
+  @property({ type: String })
+  shell?: string;
+
+  @state() private _rail: boolean = false;
+  @state() private _locked: boolean = false;
+
+  private _observed?: NileAppShell;
+
+  public connectedCallback(): void {
+    super.connectedCallback();
+    // The shell may upgrade after this element does, so read it on a microtask.
+    Promise.resolve().then(() => this._attach());
+  }
+
+  public disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this._observed?.removeEventListener('nile-nav-toggle', this._onShellToggle);
+    this._observed = undefined;
+  }
+
+  /** The shell this toggle drives, if it found one. */
+  public get appShell(): NileAppShell | null {
+    if (this.shell) {
+      const root = this.getRootNode() as Document | ShadowRoot;
+      return (root.querySelector(`#${this.shell}`) as NileAppShell) ?? null;
+    }
+    return this.closest('nile-app-shell') ?? null;
+  }
+
+  private _attach(): void {
+    const shell = this.appShell;
+    if (!shell || shell === this._observed) return;
+    this._observed?.removeEventListener('nile-nav-toggle', this._onShellToggle);
+    this._observed = shell;
+    shell.addEventListener('nile-nav-toggle', this._onShellToggle);
+    this._sync();
+  }
+
+  private _onShellToggle = (): void => {
+    this._sync();
+  };
+
+  private _sync(): void {
+    const shell = this._observed;
+    if (!shell) return;
+    this._rail = shell.rail;
+    this._locked = shell.navLocked;
+  }
+
+  public render(): TemplateResult {
+    const expanded = !this._rail;
+    return html`
+      <nile-button
+        class="toggle"
+        part="button"
+        variant="ghost"
+        circle
+        aria-expanded=${expanded ? 'true' : 'false'}
+        ?disabled=${this._locked}
+        title=${this._locked
+          ? 'The navigation stays collapsed at this window width'
+          : expanded
+          ? 'Collapse navigation'
+          : 'Expand navigation'}
+        aria-label=${expanded ? 'Collapse navigation' : 'Expand navigation'}
+        @click=${this._onClick}
+      >
+        ${renderGlyph(
+          expanded ? 'ng-panel-left-close' : 'ng-panel-left-open',
+          24,
+          'currentColor'
+        )}
+      </nile-button>
+      <span class="rule" part="rule"></span>
+    `;
+  }
+
+  private _onClick = (): void => {
+    this._attach();
+    this._observed?.toggleNav();
+    this._sync();
+  };
+}
+
+export default NileAppShellNavToggle;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nile-app-shell-nav-toggle': NileAppShellNavToggle;
+  }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export * from './nile-app-shell-panel';

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

@@ -0,0 +1,114 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { css } from 'lit';
+
+export const styles = css`
+  :host {
+    box-sizing: border-box;
+    /* A flex item of the shell's panel region, filling it. */
+    flex: 1 1 auto;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    height: 100%;
+    overflow: hidden;
+  }
+
+  :host([hidden]) {
+    display: none;
+  }
+
+  .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));
+    border-bottom: var(--nile-border-width-1, var(--ng-border-width-1)) solid
+      var(--nile-colors-neutral-400, var(--ng-colors-border-secondary));
+  }
+
+  :host([no-header]) .header {
+    display: none;
+  }
+
+  .heading {
+    display: flex;
+    align-items: center;
+    gap: var(--nile-spacing-md, var(--ng-spacing-md));
+    min-width: 0;
+  }
+
+  .mark {
+    display: inline-flex;
+    color: var(
+      --nile-colors-primary-600,
+      var(--ng-colors-fg-brand-primary-600)
+    );
+  }
+
+  .mark nile-glyph {
+    --nile-svg-fill: currentColor;
+    --nile-svg-stroke-width: var(--ng-svg-stroke-width);
+    width: 20px;
+    height: 20px;
+  }
+
+  .title {
+    margin: 0;
+    font-size: var(--nile-type-scale-3, var(--ng-font-size-text-sm));
+    font-weight: var(
+      --nile-font-weight-semi-bold,
+      var(--ng-font-weight-semibold)
+    );
+    color: var(--nile-colors-dark-900, var(--ng-colors-text-primary-900));
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .actions {
+    display: flex;
+    align-items: center;
+    gap: var(--nile-spacing-xs, var(--ng-spacing-xs));
+    margin-inline-start: auto;
+  }
+
+  :host([no-close]) .close {
+    display: none;
+  }
+
+  .body {
+    flex: 1 1 auto;
+    min-height: 0;
+    overflow-y: auto;
+    display: flex;
+    flex-direction: column;
+    gap: var(--nile-spacing-xl, var(--ng-spacing-xl));
+    padding: var(--nile-spacing-xl, var(--ng-spacing-xl));
+  }
+
+  :host([no-padding]) .body {
+    padding: 0;
+  }
+
+  .footer {
+    flex: 0 0 auto;
+    padding: var(--nile-spacing-xl, var(--ng-spacing-xl));
+    border-top: var(--nile-border-width-1, var(--ng-border-width-1)) solid
+      var(--nile-colors-neutral-400, var(--ng-colors-border-secondary));
+  }
+
+  :host(:not([has-footer])) .footer {
+    display: none;
+  }
+`;
+
+export default [styles];

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

@@ -0,0 +1,161 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { html, CSSResultArray, TemplateResult } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { styles } from './nile-app-shell-panel.css';
+import { renderGlyph } from '../internal/glyph';
+import { AppShellController } from '../nile-app-shell/shell-controller';
+import '../nile-button/nile-button';
+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.
+ *
+ * @status stable
+ * @since 2.0
+ *
+ * @tag nile-app-shell-panel
+ *
+ * @dependency 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 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.
+ *
+ * @csspart header - The header bar.
+ * @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.
+ */
+@customElement('nile-app-shell-panel')
+export class NileAppShellPanel extends NileElement {
+  public static get styles(): CSSResultArray {
+    return [styles];
+  }
+
+  private shellLink = new AppShellController(this);
+
+  /** The heading, and the accessible name of the region. */
+  @property({ type: String })
+  label: string = 'Ask Aquera';
+
+  /** Drops the header bar entirely. */
+  @property({ type: Boolean, reflect: true, attribute: 'no-header' })
+  noHeader: boolean = false;
+
+  /** Drops the close button — for a panel the page closes its own way. */
+  @property({ type: Boolean, reflect: true, attribute: 'no-close' })
+  noClose: boolean = false;
+
+  /** Removes the body's padding, for a full-bleed transcript. */
+  @property({ type: Boolean, reflect: true, attribute: 'no-padding' })
+  noPadding: boolean = false;
+
+  /** Id of the shell to follow. Defaults to the nearest ancestor. */
+  @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']`).
+   */
+  @property({ type: String, reflect: true })
+  mode: NileAppShellPanelMode = 'docked';
+
+  @state() private _hasFooter: boolean = false;
+
+  public connectedCallback(): void {
+    super.connectedCallback();
+    // Claim the shell's right region unless the author placed it elsewhere.
+    if (!this.hasAttribute('slot')) this.setAttribute('slot', 'panel');
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'complementary');
+  }
+
+  protected willUpdate(): void {
+    this.shellLink.shellId = this.shell;
+    const shell = this.shellLink.shell;
+    if (shell) this.mode = shell.panelMode;
+  }
+
+  protected updated(): void {
+    this.toggleAttribute('has-footer', this._hasFooter);
+    this.setAttribute('aria-label', this.label);
+  }
+
+  /** Close the panel through the shell. */
+  public close(): void {
+    this.shellLink.shell?.closePanel();
+    this.emit('nile-close');
+  }
+
+  private handleFooterSlotChange(event: Event): void {
+    this._hasFooter = (event.target as HTMLSlotElement)
+      .assignedNodes({ flatten: true })
+      .some(
+        node =>
+          node.nodeType === Node.ELEMENT_NODE ||
+          (node.textContent ?? '').trim() !== ''
+      );
+  }
+
+  public render(): TemplateResult {
+    return html`
+      <header class="header" part="header">
+        <slot name="header">
+          <span class="heading">
+            <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"
+            part="close"
+            variant="ghost"
+            circle
+            title="Close ${this.label}"
+            aria-label="Close ${this.label}"
+            @click=${() => this.close()}
+          >
+            ${renderGlyph('ng-x-close', 24, 'currentColor')}
+          </nile-button>
+        </div>
+      </header>
+
+      <div class="body" part="body"><slot></slot></div>
+
+      <div class="footer" part="footer">
+        <slot
+          name="footer"
+          @slotchange=${(e: Event) => this.handleFooterSlotChange(e)}
+        ></slot>
+      </div>
+    `;
+  }
+}
+
+export default NileAppShellPanel;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nile-app-shell-panel': NileAppShellPanel;
+  }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export * from './nile-app-shell-side-nav';