@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/app-rail/app-rail-item.d.ts

@@ -0,0 +1,30 @@
+import { type TemplateResult } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+/**
+ * `<lyra-app-rail-item>` — an explicit icon/label navigation item for
+ * `<lyra-app-rail>`. The rail sets its `icon-only` attribute as the viewport
+ * changes, keeping the label available to assistive technology while removing
+ * it from the visual layout.
+ *
+ * @customElement lyra-app-rail-item
+ * @slot - The visible navigation label.
+ * @slot icon - The leading icon.
+ * @csspart base - The link or button receiving focus and activation.
+ * @csspart icon - The icon wrapper.
+ * @csspart label - The label wrapper; visually clipped in icon-only mode.
+ */
+export declare class LyraAppRailItem extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** Optional destination. Without `href`, the item renders as a button. */
+    href: string;
+    /** Optional link target. */
+    target: string;
+    /** Prevents activation while retaining the item in the rail. */
+    disabled: boolean;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-app-rail-item': LyraAppRailItem;
+    }
+}

package/dist/components/app-rail/app-rail-item.js

@@ -0,0 +1,68 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { styles } from './app-rail-item.styles.js';
+/**
+ * `<lyra-app-rail-item>` — an explicit icon/label navigation item for
+ * `<lyra-app-rail>`. The rail sets its `icon-only` attribute as the viewport
+ * changes, keeping the label available to assistive technology while removing
+ * it from the visual layout.
+ *
+ * @customElement lyra-app-rail-item
+ * @slot - The visible navigation label.
+ * @slot icon - The leading icon.
+ * @csspart base - The link or button receiving focus and activation.
+ * @csspart icon - The icon wrapper.
+ * @csspart label - The label wrapper; visually clipped in icon-only mode.
+ */
+export class LyraAppRailItem extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** Optional destination. Without `href`, the item renders as a button. */
+        this.href = '';
+        /** Optional link target. */
+        this.target = '';
+        /** Prevents activation while retaining the item in the rail. */
+        this.disabled = false;
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    render() {
+        const label = this.getAttribute('aria-label');
+        const content = html `
+      <span part="icon" aria-hidden=${label ? 'true' : nothing}><slot name="icon"></slot></span>
+      <span part="label"><slot></slot></span>
+    `;
+        if (this.href && !this.disabled) {
+            return html `<a
+        part="base"
+        href=${this.href}
+        target=${this.target || nothing}
+        aria-label=${label || nothing}
+      >${content}</a>`;
+        }
+        return html `<button
+      part="base"
+      type="button"
+      ?disabled=${this.disabled}
+      aria-disabled=${this.disabled ? 'true' : nothing}
+      aria-label=${label || nothing}
+    >${content}</button>`;
+    }
+}
+__decorate([
+    property()
+], LyraAppRailItem.prototype, "href", void 0);
+__decorate([
+    property()
+], LyraAppRailItem.prototype, "target", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraAppRailItem.prototype, "disabled", void 0);
+defineElement('app-rail-item', LyraAppRailItem);

package/dist/components/app-rail/app-rail-item.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/app-rail/app-rail-item.styles.js

@@ -0,0 +1,65 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: block;
+    inline-size: 100%;
+  }
+  [part='base'] {
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    gap: var(--lyra-space-s);
+    inline-size: 100%;
+    min-block-size: var(--lyra-icon-button-size);
+    padding: var(--lyra-space-s);
+    border: 0;
+    border-radius: var(--lyra-radius);
+    background: transparent;
+    color: var(--lyra-color-text);
+    font: inherit;
+    text-align: start;
+    text-decoration: none;
+    cursor: pointer;
+  }
+  [part='base']:hover {
+    background: var(--lyra-color-brand-quiet);
+    color: var(--lyra-color-brand);
+  }
+  [part='base']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+  [part='base'][aria-disabled='true'] {
+    opacity: var(--lyra-opacity-disabled);
+    cursor: not-allowed;
+  }
+  [part='icon'] {
+    display: inline-flex;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--lyra-icon-button-size);
+    min-inline-size: var(--lyra-icon-button-size);
+  }
+  [part='label'] {
+    min-inline-size: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  :host([icon-only]) [part='label'] {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+  :host([icon-only]) [part='base'] {
+    justify-content: center;
+    padding-inline: 0;
+  }
+`;

package/dist/components/app-rail/app-rail.d.ts

@@ -0,0 +1,168 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import './app-rail-item.js';
+/** The rail's effective presentation -- see the class doc for what each renders. */
+export type AppRailMode = 'full' | 'icon-only' | 'mobile';
+/** What can be *assigned* to `mode` -- `'auto'` is a write-only sentinel; see the `mode` accessor doc. */
+export type AppRailModeInput = AppRailMode | 'auto';
+export interface AppRailModeChangeDetail {
+    mode: AppRailMode;
+}
+export interface AppRailToggleDetail {
+    open: boolean;
+}
+/**
+ * Pure breakpoint-to-mode resolver, kept separate from the `matchMedia`
+ * wiring below so it's directly unit-testable without resizing a real
+ * browser window. `mobileMatches` wins over `iconOnlyMatches` when both are
+ * true (the viewport is narrower than both breakpoints at once).
+ */
+export declare function computeAppRailMode(iconOnlyMatches: boolean, mobileMatches: boolean): AppRailMode;
+/**
+ * `<lyra-app-rail>` — a responsive navigation rail that adapts across three
+ * presentations as the *viewport* narrows (not this element's own inline
+ * size — see the `mode` accessor doc for why): `'full'` (nav items show
+ * icon + label, inline), `'icon-only'` (a narrower inline rail, icons only),
+ * and `'mobile'` (hidden behind a toggle button; opening it shows a
+ * focus-trapped floating overlay over the page).
+ *
+ * Breakpoints are viewport-width `matchMedia()` queries against
+ * `icon-only-breakpoint`/`mobile-breakpoint`, not a `ResizeObserver` on this
+ * element — a nav rail's presentation should track the actual device/window
+ * width the way a native OS shell's navigation does, not however much
+ * horizontal space a particular layout happens to give it.
+ *
+ * The `'mobile'` state participates in the library's shared overlay stack,
+ * which supplies focus trapping, Escape/backdrop dismissal, inerting, and
+ * focus restoration without nesting a `<lyra-dialog>` in this component's
+ * shadow template. `[part="base"]` (the inline
+ * `'full'`/`'icon-only'` presentation) and `[part="panel"]` (the mobile
+ * overlay) are the *same* element promoted in place across modes (mirrors
+ * `<lyra-widget>`'s fullscreen mode) — never both at once, and never two
+ * separate copies of the slotted content, which slot projection can't
+ * produce anyway (a light-DOM node is only ever assigned to one `<slot>`).
+ * It's a plain `<div>` with an explicit `role="navigation"` rather than a
+ * literal `<nav>` tag: a `<nav>`'s implicit role can't be overridden to
+ * `role="dialog"` while the overlay is modal without an `aria-allowed-role`
+ * violation (verified against axe), whereas an explicit `role="navigation"`
+ * on a generic element can be swapped for `role="dialog"` freely.
+ *
+ * @customElement lyra-app-rail
+ * @slot - Nav items. Use `<lyra-app-rail-item>` for the explicit icon/label
+ *   contract that automatically hides labels in `'icon-only'` mode. Generic
+ *   links and buttons remain supported, but their compact presentation is the
+ *   consumer's responsibility. While the mobile overlay is open, clicking
+ *   anywhere inside this slot closes it.
+ * @slot header - Logo/brand content, shown above the nav items in every mode.
+ * @slot footer - A trailing user/settings trigger, shown below the nav items.
+ * @event lyra-mode-change - The effective mode changed, whether from a
+ *   breakpoint crossing or an explicit `mode` assignment. Not fired for a
+ *   redundant reassignment to the mode already in effect.
+ *   `detail: AppRailModeChangeDetail`.
+ * @event lyra-toggle - The mobile overlay opened or closed — via the
+ *   built-in toggle button, Escape, a backdrop click, a nav-item click while
+ *   open, or a breakpoint/forced mode change leaving `'mobile'` while open.
+ *   Not fired when a consumer sets `open` directly (mirrors `<lyra-dialog>`'s
+ *   `open`/`close()` split). `detail: AppRailToggleDetail`.
+ * @csspart base - The rail root while inline (`'full'`/`'icon-only'` modes).
+ * @csspart header - The wrapper around the `header` slot.
+ * @csspart nav - The wrapper around the default (nav items) slot.
+ * @csspart footer - The wrapper around the `footer` slot.
+ * @csspart toggle - The mobile hamburger/close toggle button. Hidden via
+ *   CSS outside `'mobile'` mode.
+ * @csspart backdrop - The mobile overlay's scrim. Only rendered while open.
+ * @csspart panel - The mobile overlay's floating panel — see the class doc
+ *   for why it's the same element as `base`, never both at once.
+ *
+ * @example
+ * Use the item contract so the visible label collapses while its accessible
+ * name remains available:
+ * ```html
+ * <lyra-app-rail>
+ *   <lyra-app-rail-item href="/inbox" aria-label="Inbox">
+ *     <svg slot="icon" aria-hidden="true">...</svg>Inbox
+ *   </lyra-app-rail-item>
+ * </lyra-app-rail>
+ * ```
+ */
+export declare class LyraAppRail extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    static properties: {
+        mode: {
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+    };
+    /** Below this viewport width, the rail switches from `'full'` to
+     *  `'icon-only'`. Any valid CSS length, used directly in a `max-width`
+     *  media query. */
+    iconOnlyBreakpoint: string;
+    /** Below this viewport width, the rail switches from `'icon-only'` to
+     *  `'mobile'`. Should be smaller than `iconOnlyBreakpoint` to produce all
+     *  three states as the viewport narrows. */
+    mobileBreakpoint: string;
+    /** Whether the mobile floating overlay is shown. Only meaningful while
+     *  `mode` is `'mobile'` — the value is preserved (not reset) while another
+     *  mode is active, but no overlay chrome renders until `mode` is
+     *  `'mobile'` again. Set this directly, or use the built-in toggle button
+     *  — there is no separate `show()`/`hide()` pair. */
+    open: boolean;
+    /** Accessible name for the rail's navigation landmark, and for its dialog
+     *  role while the mobile overlay is open. */
+    label: string;
+    private hasHeaderSlot;
+    private hasFooterSlot;
+    private _mode;
+    private forced;
+    private iconOnlyMatches;
+    private mobileMatches;
+    private mqIconOnly?;
+    private mqMobile?;
+    private overlayActive;
+    private justOpened;
+    private releaseScrollLock?;
+    private overlayHandle?;
+    private explicitTrigger?;
+    private readonly navId;
+    private syncSlottedItems;
+    /**
+     * The rail's current effective presentation. Always one of the three real
+     * modes — never `'auto'` — reflecting either the live breakpoint match or,
+     * once forced, whatever was last assigned.
+     *
+     * Assigning `'full'`/`'icon-only'`/`'mobile'` forces that mode and stops
+     * this element from responding to `icon-only-breakpoint`/
+     * `mobile-breakpoint` matches. Assigning the sentinel `'auto'` releases
+     * the force and immediately re-syncs to the current viewport width,
+     * resuming automatic tracking. `'auto'` is a write-only instruction, not a
+     * value this getter ever returns — there is no way to observe "currently
+     * forced" from the property itself.
+     */
+    get mode(): AppRailMode;
+    set mode(next: AppRailModeInput);
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private activateMobileOverlay;
+    private deactivateMobileOverlay;
+    private setupMediaQueries;
+    private teardownMediaQueries;
+    private onIconOnlyChange;
+    private onMobileChange;
+    private applyComputedMode;
+    private setEffectiveMode;
+    private setOpen;
+    private onToggleClick;
+    private onBackdropClick;
+    private onNavItemClick;
+    private onHeaderSlotChange;
+    private onFooterSlotChange;
+    private onNavSlotChange;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-app-rail': LyraAppRail;
+    }
+}