@aceshooting/lyra-ui 1.2.0 → 2.1.0

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

@@ -0,0 +1,419 @@
+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, svg } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { activateOverlay } from '../../internal/overlay-manager.js';
+import { defineElement } from '../../internal/prefix.js';
+import { lockScroll } from '../../internal/scroll-lock.js';
+import { nextId } from '../../internal/a11y.js';
+import { closeIcon } from '../../internal/icons.js';
+import { styles } from './app-rail.styles.js';
+import './app-rail-item.js';
+// icons.ts has no hamburger/menu glyph and this component must not modify
+// that shared module -- inlined here instead, matching its 24x24
+// viewBox/stroke-width/currentColor convention so it reads as part of the
+// same icon set.
+function menuIcon() {
+    return svg `
+    <svg
+      width="1em"
+      height="1em"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="1.75"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <line x1="4" y1="7" x2="20" y2="7"></line>
+      <line x1="4" y1="12" x2="20" y2="12"></line>
+      <line x1="4" y1="17" x2="20" y2="17"></line>
+    </svg>
+  `;
+}
+/**
+ * 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 function computeAppRailMode(iconOnlyMatches, mobileMatches) {
+    if (mobileMatches)
+        return 'mobile';
+    if (iconOnlyMatches)
+        return 'icon-only';
+    return 'full';
+}
+/**
+ * `<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 class LyraAppRail extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** Below this viewport width, the rail switches from `'full'` to
+         *  `'icon-only'`. Any valid CSS length, used directly in a `max-width`
+         *  media query. */
+        this.iconOnlyBreakpoint = '960px';
+        /** 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. */
+        this.mobileBreakpoint = '600px';
+        /** 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. */
+        this.open = false;
+        /** Accessible name for the rail's navigation landmark, and for its dialog
+         *  role while the mobile overlay is open. */
+        this.label = 'Navigation';
+        this.hasHeaderSlot = false;
+        this.hasFooterSlot = false;
+        this._mode = 'full';
+        // Whether matchMedia changes are currently ignored because a consumer
+        // forced a specific mode -- see the `mode` accessor doc.
+        this.forced = false;
+        this.iconOnlyMatches = false;
+        this.mobileMatches = false;
+        // Derived from mode === 'mobile' && open -- tracked as its own field
+        // (rather than recomputed inline everywhere) so willUpdate can detect the
+        // specific false->true/true->false transition regardless of which of the
+        // two source properties changed.
+        this.overlayActive = false;
+        this.justOpened = false;
+        this.navId = nextId('app-rail-nav');
+        // Split into two single-query listeners (rather than one shared handler
+        // reading both live MediaQueryLists) specifically so a test can invoke
+        // either directly with a fabricated { matches } event -- exercising the
+        // full breakpoint-response wiring without needing to actually resize the
+        // browser window a test runs in.
+        this.onIconOnlyChange = (e) => {
+            this.iconOnlyMatches = e.matches;
+            if (!this.forced)
+                this.applyComputedMode();
+        };
+        this.onMobileChange = (e) => {
+            this.mobileMatches = e.matches;
+            if (!this.forced)
+                this.applyComputedMode();
+        };
+        this.onToggleClick = (e) => {
+            if (!this.open)
+                this.explicitTrigger = e.currentTarget;
+            this.setOpen(!this.open);
+        };
+        this.onBackdropClick = () => {
+            this.overlayHandle?.dismissBackdrop();
+        };
+        // See the default-slot @slot doc -- any click inside the nav items while
+        // the overlay is open closes it, without trying to distinguish a real
+        // navigation trigger from incidental slotted content.
+        this.onNavItemClick = () => {
+            if (this.overlayActive)
+                this.setOpen(false);
+        };
+        this.onHeaderSlotChange = (e) => {
+            this.hasHeaderSlot = e.target.assignedElements({ flatten: true }).length > 0;
+        };
+        this.onFooterSlotChange = (e) => {
+            this.hasFooterSlot = e.target.assignedElements({ flatten: true }).length > 0;
+        };
+        this.onNavSlotChange = () => {
+            this.syncSlottedItems();
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    // `mode` needs a custom accessor (force/auto semantics below) rather than
+    // the usual @property()-generated one -- registered here, alongside the
+    // decorator-declared properties below, the same way lyra-model-select's
+    // form-associated `value` accessor is. `reflect: true` still applies:
+    // LitElement's update loop reflects any `reflect`-flagged property to its
+    // attribute generically by reading `this[name]` after render, regardless
+    // of whether that property has a custom or auto-generated accessor.
+    static { this.properties = {
+        mode: { reflect: true, noAccessor: true },
+    }; }
+    syncSlottedItems() {
+        const slot = this.shadowRoot?.querySelector('[part="nav"] > slot');
+        for (const item of slot?.assignedElements({ flatten: true }) ?? []) {
+            if (item.localName === 'lyra-app-rail-item') {
+                item.toggleAttribute('icon-only', this._mode === 'icon-only');
+            }
+        }
+    }
+    /**
+     * 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() {
+        return this._mode;
+    }
+    set mode(next) {
+        if (next === 'auto') {
+            if (!this.forced)
+                return;
+            this.forced = false;
+            this.applyComputedMode();
+            return;
+        }
+        if (next !== 'full' && next !== 'icon-only' && next !== 'mobile')
+            return;
+        this.forced = true;
+        this.setEffectiveMode(next);
+    }
+    willUpdate(changed) {
+        if (!this.hasUpdated) {
+            this.hasHeaderSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'header');
+            this.hasFooterSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'footer');
+        }
+        if (this.hasUpdated && (changed.has('iconOnlyBreakpoint') || changed.has('mobileBreakpoint'))) {
+            this.teardownMediaQueries();
+            this.setupMediaQueries();
+        }
+        if (changed.has('open') || changed.has('mode')) {
+            const next = this._mode === 'mobile' && this.open;
+            if (next !== this.overlayActive) {
+                this.overlayActive = next;
+                if (next) {
+                    this.justOpened = true;
+                    this.activateMobileOverlay();
+                }
+                else {
+                    this.deactivateMobileOverlay();
+                }
+            }
+        }
+    }
+    // Runs after render (not willUpdate) so [part="panel"] and its slotted
+    // content have already landed in the DOM before the focus call below can
+    // rely on them -- mirrors lyra-dialog's/lyra-widget's identical ordering
+    // rationale.
+    updated() {
+        this.syncSlottedItems();
+        if (this.justOpened) {
+            this.justOpened = false;
+            this.overlayHandle?.focusInitial();
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.setupMediaQueries();
+        // A reconnect (e.g. a drag-and-drop reparent keeping this same element
+        // instance) fires disconnectedCallback then connectedCallback
+        // synchronously with no update in between, so willUpdate never reruns to
+        // notice the overlay is still active -- restore its shared registration
+        // and scroll lock.
+        if (this.hasUpdated && this._mode === 'mobile' && this.open) {
+            if (this.overlayHandle?.isActive()) {
+                this.overlayHandle.resume();
+            }
+            else {
+                this.activateMobileOverlay();
+            }
+            if (!this.releaseScrollLock)
+                this.releaseScrollLock = lockScroll(this.ownerDocument);
+            queueMicrotask(() => this.overlayHandle?.focusInitial());
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.teardownMediaQueries();
+        this.releaseScrollLock?.();
+        this.releaseScrollLock = undefined;
+        this.overlayHandle?.suspend();
+    }
+    activateMobileOverlay() {
+        this.releaseScrollLock ??= lockScroll(this.ownerDocument);
+        this.overlayHandle = activateOverlay({
+            host: this,
+            panel: () => this.shadowRoot?.querySelector('[part="panel"]') ?? null,
+            onEscape: () => this.setOpen(false),
+            onBackdrop: () => this.setOpen(false),
+            restoreFocusTo: this.explicitTrigger,
+        });
+        this.explicitTrigger = undefined;
+    }
+    deactivateMobileOverlay() {
+        this.releaseScrollLock?.();
+        this.releaseScrollLock = undefined;
+        this.overlayHandle?.deactivate();
+        this.overlayHandle = undefined;
+    }
+    setupMediaQueries() {
+        const view = this.ownerDocument.defaultView;
+        if (!view?.matchMedia)
+            return;
+        this.mqIconOnly = view.matchMedia(`(max-width: ${this.iconOnlyBreakpoint})`);
+        this.mqMobile = view.matchMedia(`(max-width: ${this.mobileBreakpoint})`);
+        this.mqIconOnly.addEventListener('change', this.onIconOnlyChange);
+        this.mqMobile.addEventListener('change', this.onMobileChange);
+        this.iconOnlyMatches = this.mqIconOnly.matches;
+        this.mobileMatches = this.mqMobile.matches;
+        if (!this.forced)
+            this.applyComputedMode();
+    }
+    teardownMediaQueries() {
+        this.mqIconOnly?.removeEventListener('change', this.onIconOnlyChange);
+        this.mqMobile?.removeEventListener('change', this.onMobileChange);
+        this.mqIconOnly = undefined;
+        this.mqMobile = undefined;
+    }
+    applyComputedMode() {
+        this.setEffectiveMode(computeAppRailMode(this.iconOnlyMatches, this.mobileMatches));
+    }
+    setEffectiveMode(next) {
+        if (this._mode === next)
+            return;
+        const old = this._mode;
+        this._mode = next;
+        this.requestUpdate('mode', old);
+        this.emit('lyra-mode-change', { mode: next });
+        // 'open' is only meaningful in 'mobile' mode -- leaving it while open
+        // closes the overlay as a side effect (through setOpen, so it still
+        // emits lyra-toggle and releases the scroll lock/focus trap normally)
+        // rather than leaving a now-invisible overlay primed to reappear the
+        // next time mode returns to 'mobile'.
+        if (next !== 'mobile' && this.open)
+            this.setOpen(false);
+    }
+    setOpen(next) {
+        if (this.open === next)
+            return;
+        this.open = next;
+        this.emit('lyra-toggle', { open: next });
+    }
+    render() {
+        const mobile = this._mode === 'mobile';
+        return html `
+      <button
+        part="toggle"
+        type="button"
+        aria-expanded=${this.open ? 'true' : 'false'}
+        aria-controls=${this.navId}
+        aria-label=${this.open ? 'Close navigation' : 'Open navigation'}
+        @click=${this.onToggleClick}
+      >
+        ${this.open ? closeIcon() : menuIcon()}
+      </button>
+      ${mobile && this.open ? html `<div part="backdrop" @click=${this.onBackdropClick}></div>` : nothing}
+      <div
+        id=${this.navId}
+        part=${mobile ? 'panel' : 'base'}
+        aria-label=${this.label}
+        role=${this.overlayActive ? 'dialog' : 'navigation'}
+        aria-modal=${this.overlayActive ? 'true' : nothing}
+        tabindex=${this.overlayActive ? '-1' : nothing}
+        ?inert=${mobile && !this.open}
+      >
+        <div part="header" ?hidden=${!this.hasHeaderSlot}>
+          <slot name="header" @slotchange=${this.onHeaderSlotChange}></slot>
+        </div>
+        <div part="nav">
+          <slot @slotchange=${this.onNavSlotChange} @click=${this.onNavItemClick}></slot>
+        </div>
+        <div part="footer" ?hidden=${!this.hasFooterSlot}>
+          <slot name="footer" @slotchange=${this.onFooterSlotChange}></slot>
+        </div>
+      </div>
+    `;
+    }
+}
+__decorate([
+    property({ attribute: 'icon-only-breakpoint' })
+], LyraAppRail.prototype, "iconOnlyBreakpoint", void 0);
+__decorate([
+    property({ attribute: 'mobile-breakpoint' })
+], LyraAppRail.prototype, "mobileBreakpoint", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraAppRail.prototype, "open", void 0);
+__decorate([
+    property()
+], LyraAppRail.prototype, "label", void 0);
+__decorate([
+    state()
+], LyraAppRail.prototype, "hasHeaderSlot", void 0);
+__decorate([
+    state()
+], LyraAppRail.prototype, "hasFooterSlot", void 0);
+defineElement('app-rail', LyraAppRail);

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

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

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

@@ -0,0 +1,128 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: block;
+    /* Component-specific sizing -- not shared design tokens, so a consumer
+       can retheme any of them without a raw literal leaking into the public
+       API (same rationale as lyra-dialog's --lyra-dialog-overlay-color and
+       lyra-widget's --lyra-widget-overlay-color). */
+    --lyra-app-rail-width: 15rem;
+    --lyra-app-rail-icon-width: 4rem;
+    --lyra-app-rail-mobile-width: 18rem;
+    --lyra-app-rail-overlay-color: rgb(0 0 0 / 0.5);
+  }
+
+  [part='toggle'] {
+    display: none;
+    align-items: center;
+    justify-content: center;
+    min-inline-size: var(--lyra-icon-button-size);
+    min-block-size: var(--lyra-icon-button-size);
+    border: 1px solid var(--lyra-color-border);
+    border-radius: var(--lyra-radius);
+    background: var(--lyra-color-surface);
+    color: var(--lyra-color-text);
+    cursor: pointer;
+  }
+  :host([mode='mobile']) [part='toggle'] {
+    display: inline-flex;
+  }
+  [part='toggle']:hover {
+    background: var(--lyra-color-brand-quiet);
+    color: var(--lyra-color-brand);
+  }
+  [part='toggle']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+
+  [part='backdrop'] {
+    position: fixed;
+    inset: 0;
+    z-index: var(--lyra-overlay-stack-index, 1000);
+    background: var(--lyra-app-rail-overlay-color);
+  }
+
+  /* [part="base"]/[part="panel"] are the SAME element -- this
+     component promotes it in place for the mobile overlay (mirrors
+     lyra-widget's fullscreen mode) rather than duplicating the slotted nav
+     content into a second element, which slot projection can't do anyway
+     (a light-DOM node can only be assigned to one <slot> at a time). Its
+     part attribute switches between the two names per render, so the two
+     rulesets below are always mutually exclusive on it. */
+  [part='base'] {
+    display: flex;
+    flex-direction: column;
+    inline-size: var(--lyra-app-rail-width);
+    block-size: 100%;
+    border-inline-end: 1px solid var(--lyra-color-border);
+    background: var(--lyra-color-surface);
+    overflow-y: auto;
+    transition: inline-size var(--lyra-transition-base);
+  }
+  :host([mode='icon-only']) [part='base'] {
+    inline-size: var(--lyra-app-rail-icon-width);
+  }
+
+  [part='panel'] {
+    position: fixed;
+    inset-block: 0;
+    inset-inline-start: 0;
+    z-index: calc(var(--lyra-overlay-stack-index, 1000) + 1);
+    display: flex;
+    flex-direction: column;
+    inline-size: min(var(--lyra-app-rail-mobile-width), 85vw);
+    background: var(--lyra-color-surface);
+    box-shadow: var(--lyra-shadow);
+    overflow-y: auto;
+    transform: translateX(-100%);
+    transition: transform var(--lyra-transition-base);
+  }
+  /* translateX is a physical transform -- CSS logical properties don't cover
+     it -- so the offscreen direction is flipped explicitly for RTL via
+     :dir() rather than needing internal/rtl.ts's JS helper (that helper is
+     for pointer/keyboard math that can't be expressed in CSS at all; this
+     can). */
+  :host(:dir(rtl)) [part='panel'] {
+    transform: translateX(100%);
+  }
+  :host([mode='mobile'][open]) [part='panel'] {
+    transform: translateX(0);
+  }
+
+  [part='header'] {
+    padding: var(--lyra-space-m);
+    border-block-end: 1px solid var(--lyra-color-border);
+  }
+  [part='header'][hidden] {
+    display: none;
+  }
+  [part='footer'] {
+    padding: var(--lyra-space-m);
+    border-block-start: 1px solid var(--lyra-color-border);
+  }
+  [part='footer'][hidden] {
+    display: none;
+  }
+  [part='nav'] {
+    flex: 1 1 auto;
+    overflow-y: auto;
+    padding: var(--lyra-space-s);
+    display: flex;
+    flex-direction: column;
+    gap: var(--lyra-space-xs);
+  }
+  :host([mode='icon-only']) [part='nav'] {
+    align-items: center;
+  }
+  :host([mode='icon-only']) ::slotted(lyra-app-rail-item) {
+    max-inline-size: var(--lyra-app-rail-icon-width);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [part='base'],
+    [part='panel'] {
+      transition: none !important;
+    }
+  }
+`;