@aquera/nile-elements 2.0.5 → 2.0.7

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

@@ -0,0 +1,292 @@
+/**
+ * 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 { CSSResultArray, TemplateResult, PropertyValues } from 'lit';
+import NileElement from '../internal/nile-element';
+import '../nile-button/nile-button';
+/** The mode the AI panel is currently in. */
+export type NileAppShellPanelMode = 'docked' | 'overlay';
+/** Where the top bar is mounted. */
+export type NileAppShellTopBarPlacement = 'content' | 'shell';
+/** How the main region lays its content out. */
+export type NileAppShellContentAlign = 'fluid' | 'centered';
+/**
+ * @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.
+ *
+ * @status stable
+ * @since 2.0
+ *
+ * @tag nile-app-shell
+ *
+ * @dependency nile-button
+ * @dependency nile-glyph
+ *
+ * @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-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 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-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.
+ *
+ * @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 }`.
+ *
+ * @csspart skip-link - The skip-to-content link.
+ * @csspart banner - The banner region.
+ * @csspart shell-top-bar - The top bar when it spans the shell.
+ * @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 - 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 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.
+ * @csspart container - The content container.
+ * @csspart main - The scrolling page body.
+ * @csspart aside - The aside region.
+ * @csspart panel - The AI panel.
+ * @csspart panel-header - The panel's header bar.
+ * @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-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-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-duration=250ms] - Track and panel motion.
+ * @cssproperty [--nile-app-shell-ease] - Easing for moves and resizes.
+ *
+ * @method openPanel() - Open the AI panel. No-op when the panel is unavailable.
+ * @method closePanel() - Close the AI panel.
+ * @method togglePanel(force?) - Toggle, or force a specific open state.
+ * @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.
+ */
+export declare class NileAppShell extends NileElement {
+    static get styles(): CSSResultArray;
+    /**
+     * The user's nav preference. The nav can still render as a rail while this is
+     * false — see `navLocked`.
+     */
+    navCollapsed: boolean;
+    /** Whether the AI panel is open. */
+    panelOpen: boolean;
+    /**
+     * Unmounts the AI panel for this route even when the `panel` slot is filled.
+     * `openPanel()` becomes a no-op.
+     */
+    noPanel: boolean;
+    /** The default panel heading. Ignored when `panel-header` is slotted. */
+    panelLabel: 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. */
+    noPanelShortcut: boolean;
+    /** Hides the skip-to-content link. */
+    noSkipLink: boolean;
+    /** Label for the skip-to-content link. */
+    skipLinkLabel: string;
+    /** Where the top bar is mounted: inside the container, or spanning the shell. */
+    topBarPlacement: NileAppShellTopBarPlacement;
+    /** `centered` caps the page body at `--nile-app-shell-centered-width`. */
+    contentAlign: NileAppShellContentAlign;
+    /**
+     * 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.
+     */
+    contentContainer: boolean;
+    /** Drops the container's card chrome for a full-bleed page. */
+    flat: boolean;
+    /** Removes the container's inner padding. */
+    noPadding: boolean;
+    /**
+     * 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.
+     */
+    askLabel: string;
+    /** Drops the built-in Ask button, for a bar that renders its own. */
+    noAsk: boolean;
+    /** Sizes the shell to the viewport instead of its parent. */
+    fullHeight: boolean;
+    /**
+     * 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.
+     */
+    overlayBreakpoint: number;
+    /**
+     * 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.
+     */
+    dockedRailBreakpoint: number;
+    /**
+     * Persists the nav preference and the docked panel state under this key.
+     * Overlay panel state is never persisted — a reload opens closed.
+     */
+    persistKey?: string;
+    /** The panel's current mode. Derived from the shell's width. */
+    private _panelMode;
+    /** Whether the nav is held at a rail by the shell's width. */
+    private _navLocked;
+    private _hasBanner;
+    private _hasSideNav;
+    private _hasTopBar;
+    private _hasTopBarActions;
+    private _hasTabs;
+    private _hasPanel;
+    private _hasPanelFooter;
+    /**
+     * 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`.
+     */
+    private _panelOwnsChrome;
+    private _hasAside;
+    private _main?;
+    private _width;
+    private _resizeObserver?;
+    private _restoredPanelOpen;
+    /** The panel's current mode: `docked` or `overlay`. */
+    get panelMode(): NileAppShellPanelMode;
+    /** Whether the shell is holding the nav at a rail. The toggle is disabled. */
+    get navLocked(): boolean;
+    /** Whether a panel is mounted for this route. */
+    get panelAvailable(): boolean;
+    /** Whether the built-in Ask button is rendered. */
+    get askVisible(): boolean;
+    /** Whether the nav renders as a rail right now, preference or lock. */
+    get rail(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    protected updated(changed: PropertyValues<this>): void;
+    /** Open the AI panel. No-op when no panel is mounted for this route. */
+    openPanel(): void;
+    /** Close the AI panel. */
+    closePanel(): void;
+    /**
+     * 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.
+     */
+    togglePanel(force?: boolean): void;
+    /** Expand the side nav. */
+    expandNav(): void;
+    /** Collapse the side nav to a rail. */
+    collapseNav(): void;
+    /** Toggle the side nav, or force a collapsed state. */
+    toggleNav(force?: boolean): void;
+    /** Move focus to the page body. */
+    focusMain(): void;
+    private _setPanelOpen;
+    private _setNavCollapsed;
+    /** Records the shell's width and re-derives everything that depends on it. */
+    private _measure;
+    /**
+     * 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.
+     */
+    private _geometry;
+    /**
+     * 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.
+     */
+    private _dockRequirement;
+    private _recompute;
+    /** Mirrors the effective rail state onto a slotted `nile-side-bar`. */
+    private _syncSideNav;
+    /** A slotted sidebar's own expand button is the same toggle. */
+    private _onSideNavToggle;
+    private _onKeyDown;
+    private _storageKey;
+    private _restore;
+    private _persist;
+    private _onSlotChange;
+    private _renderNavToggle;
+    private _renderTopBar;
+    render(): TemplateResult;
+}
+export default NileAppShell;
+declare global {
+    interface HTMLElementTagNameMap {
+        'nile-app-shell': NileAppShell;
+    }
+}