@aceshooting/lyra-ui 2.0.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

@@ -1,5 +1,6 @@
 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. */
@@ -31,12 +32,10 @@ export declare function computeAppRailMode(iconOnlyMatches: boolean, mobileMatch
  * width the way a native OS shell's navigation does, not however much
  * horizontal space a particular layout happens to give it.
  *
- * This is its own standalone focus-trapped overlay implementation for the
- * `'mobile'` state (`role="dialog"`, Escape/backdrop-dismissible,
- * scroll-locking while open) rather than nesting a `<lyra-dialog>` in its
- * shadow template — see `<lyra-dialog>`'s own header comment for why a new
- * overlay-shaped component in this library duplicates that pattern locally
- * instead of composing the previous one. `[part="base"]` (the inline
+ * 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
@@ -49,15 +48,11 @@ export declare function computeAppRailMode(iconOnlyMatches: boolean, mobileMatch
  * on a generic element can be swapped for `role="dialog"` freely.
  *
  * @customElement lyra-app-rail
- * @slot - Nav items — generic slotted content (e.g. `<a>`/`<button>`
- *   elements) the consumer builds with its own icon+label structure; this
- *   component only lays them out and manages the responsive chrome around
- *   them. See the `@example` below for the accessible-name expectation this
- *   places on the slotted content in `'icon-only'` mode. While the mobile
- *   overlay is open, clicking anywhere inside this slot closes it (see
- *   `onNavItemClick`) — every slotted item is assumed to be a navigation
- *   trigger, not necessarily a real link, so this fires on any click rather
- *   than trying to detect one.
+ * @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
@@ -80,13 +75,13 @@ export declare function computeAppRailMode(iconOnlyMatches: boolean, mobileMatch
  *   for why it's the same element as `base`, never both at once.
  *
  * @example
- * In `'icon-only'` mode, slotted nav items lose their visible text label.
- * Give each one a real accessible name regardless — `aria-label`, visually
- * hidden text, or a `title` — since this component only lays out whatever is
- * slotted and has no way to inspect or fix up a consumer's own markup:
+ * Use the item contract so the visible label collapses while its accessible
+ * name remains available:
  * ```html
  * <lyra-app-rail>
- *   <a href="/inbox" aria-label="Inbox"><svg aria-hidden="true">...</svg><span>Inbox</span></a>
+ *   <lyra-app-rail-item href="/inbox" aria-label="Inbox">
+ *     <svg slot="icon" aria-hidden="true">...</svg>Inbox
+ *   </lyra-app-rail-item>
  * </lyra-app-rail>
  * ```
  */
@@ -126,8 +121,10 @@ export declare class LyraAppRail extends LyraElement {
     private overlayActive;
     private justOpened;
     private releaseScrollLock?;
-    private lastTrigger?;
+    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,
@@ -147,6 +144,8 @@ export declare class LyraAppRail extends LyraElement {
     protected updated(): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    private activateMobileOverlay;
+    private deactivateMobileOverlay;
     private setupMediaQueries;
     private teardownMediaQueries;
     private onIconOnlyChange;
@@ -159,9 +158,7 @@ export declare class LyraAppRail extends LyraElement {
     private onNavItemClick;
     private onHeaderSlotChange;
     private onFooterSlotChange;
-    private onDocKeyDown;
-    private getFocusableElements;
-    private getActiveElement;
+    private onNavSlotChange;
     render(): TemplateResult;
 }
 declare global {

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

@@ -7,42 +7,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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';
-const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
-// Shadow-piercing so a slotted custom element's real focusable target (e.g.
-// an <input> inside its own shadow root) is found even though the host tag
-// itself doesn't match FOCUSABLE_SELECTOR. Deliberately duplicated from
-// lyra-dialog's identical helper rather than imported/shared -- this
-// component is its own standalone overlay for the mobile state and must not
-// depend on lyra-dialog (see this file's class doc).
-function collectFocusable(el) {
-    const result = [];
-    if (el.matches(FOCUSABLE_SELECTOR)) {
-        result.push(el);
-    }
-    if (el instanceof HTMLSlotElement) {
-        for (const assigned of el.assignedElements({ flatten: true })) {
-            result.push(...collectFocusable(assigned));
-        }
-        return result;
-    }
-    const container = el.shadowRoot ?? el;
-    for (const child of Array.from(container.children)) {
-        result.push(...collectFocusable(child));
-    }
-    return result;
-}
-/** Whether `el` is actually laid out/paintable -- `checkVisibility()` (falling
- *  back to `getClientRects().length` where unsupported) correctly follows
- *  flattened-tree/slot assignment, unlike `offsetParent`. Mirrors
- *  lyra-dialog's/lyra-widget's identical helper. */
-function isRendered(el) {
-    return el.checkVisibility ? el.checkVisibility() : el.getClientRects().length > 0;
-}
+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
@@ -94,12 +65,10 @@ export function computeAppRailMode(iconOnlyMatches, mobileMatches) {
  * width the way a native OS shell's navigation does, not however much
  * horizontal space a particular layout happens to give it.
  *
- * This is its own standalone focus-trapped overlay implementation for the
- * `'mobile'` state (`role="dialog"`, Escape/backdrop-dismissible,
- * scroll-locking while open) rather than nesting a `<lyra-dialog>` in its
- * shadow template — see `<lyra-dialog>`'s own header comment for why a new
- * overlay-shaped component in this library duplicates that pattern locally
- * instead of composing the previous one. `[part="base"]` (the inline
+ * 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
@@ -112,15 +81,11 @@ export function computeAppRailMode(iconOnlyMatches, mobileMatches) {
  * on a generic element can be swapped for `role="dialog"` freely.
  *
  * @customElement lyra-app-rail
- * @slot - Nav items — generic slotted content (e.g. `<a>`/`<button>`
- *   elements) the consumer builds with its own icon+label structure; this
- *   component only lays them out and manages the responsive chrome around
- *   them. See the `@example` below for the accessible-name expectation this
- *   places on the slotted content in `'icon-only'` mode. While the mobile
- *   overlay is open, clicking anywhere inside this slot closes it (see
- *   `onNavItemClick`) — every slotted item is assumed to be a navigation
- *   trigger, not necessarily a real link, so this fires on any click rather
- *   than trying to detect one.
+ * @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
@@ -143,13 +108,13 @@ export function computeAppRailMode(iconOnlyMatches, mobileMatches) {
  *   for why it's the same element as `base`, never both at once.
  *
  * @example
- * In `'icon-only'` mode, slotted nav items lose their visible text label.
- * Give each one a real accessible name regardless — `aria-label`, visually
- * hidden text, or a `title` — since this component only lays out whatever is
- * slotted and has no way to inspect or fix up a consumer's own markup:
+ * Use the item contract so the visible label collapses while its accessible
+ * name remains available:
  * ```html
  * <lyra-app-rail>
- *   <a href="/inbox" aria-label="Inbox"><svg aria-hidden="true">...</svg><span>Inbox</span></a>
+ *   <lyra-app-rail-item href="/inbox" aria-label="Inbox">
+ *     <svg slot="icon" aria-hidden="true">...</svg>Inbox
+ *   </lyra-app-rail-item>
  * </lyra-app-rail>
  * ```
  */
@@ -204,11 +169,12 @@ export class LyraAppRail extends LyraElement {
                 this.applyComputedMode();
         };
         this.onToggleClick = (e) => {
-            this.lastTrigger = e.currentTarget;
+            if (!this.open)
+                this.explicitTrigger = e.currentTarget;
             this.setOpen(!this.open);
         };
         this.onBackdropClick = () => {
-            this.setOpen(false);
+            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
@@ -223,32 +189,8 @@ export class LyraAppRail extends LyraElement {
         this.onFooterSlotChange = (e) => {
             this.hasFooterSlot = e.target.assignedElements({ flatten: true }).length > 0;
         };
-        this.onDocKeyDown = (e) => {
-            if (!this.overlayActive)
-                return;
-            if (e.key === 'Escape') {
-                e.preventDefault();
-                this.setOpen(false);
-                return;
-            }
-            if (e.key !== 'Tab')
-                return;
-            const focusable = this.getFocusableElements();
-            if (focusable.length === 0) {
-                e.preventDefault();
-                return;
-            }
-            const first = focusable[0];
-            const last = focusable[focusable.length - 1];
-            const active = this.getActiveElement();
-            if (e.shiftKey && active === first) {
-                e.preventDefault();
-                last.focus();
-            }
-            else if (!e.shiftKey && active === last) {
-                e.preventDefault();
-                first.focus();
-            }
+        this.onNavSlotChange = () => {
+            this.syncSlottedItems();
         };
     }
     static { this.styles = [LyraElement.styles, styles]; }
@@ -262,6 +204,14 @@ export class LyraAppRail extends LyraElement {
     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,
@@ -306,13 +256,10 @@ export class LyraAppRail extends LyraElement {
                 this.overlayActive = next;
                 if (next) {
                     this.justOpened = true;
-                    this.releaseScrollLock = lockScroll();
-                    document.addEventListener('keydown', this.onDocKeyDown);
+                    this.activateMobileOverlay();
                 }
                 else {
-                    this.releaseScrollLock?.();
-                    this.releaseScrollLock = undefined;
-                    document.removeEventListener('keydown', this.onDocKeyDown);
+                    this.deactivateMobileOverlay();
                 }
             }
         }
@@ -322,15 +269,10 @@ export class LyraAppRail extends LyraElement {
     // rely on them -- mirrors lyra-dialog's/lyra-widget's identical ordering
     // rationale.
     updated() {
+        this.syncSlottedItems();
         if (this.justOpened) {
             this.justOpened = false;
-            const first = this.getFocusableElements()[0];
-            if (first) {
-                first.focus();
-            }
-            else {
-                this.shadowRoot?.querySelector('[part="panel"]')?.focus();
-            }
+            this.overlayHandle?.focusInitial();
         }
     }
     connectedCallback() {
@@ -339,11 +281,18 @@ export class LyraAppRail extends LyraElement {
         // 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 the scroll lock/trap it
-        // dropped. Mirrors lyra-dialog's/lyra-widget's identical reconnect handling.
-        if (this.hasUpdated && this.overlayActive && !this.releaseScrollLock) {
-            this.releaseScrollLock = lockScroll();
-            document.addEventListener('keydown', this.onDocKeyDown);
+        // 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() {
@@ -351,13 +300,31 @@ export class LyraAppRail extends LyraElement {
         this.teardownMediaQueries();
         this.releaseScrollLock?.();
         this.releaseScrollLock = undefined;
-        document.removeEventListener('keydown', this.onDocKeyDown);
+        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() {
-        if (typeof window === 'undefined' || !window.matchMedia)
+        const view = this.ownerDocument.defaultView;
+        if (!view?.matchMedia)
             return;
-        this.mqIconOnly = window.matchMedia(`(max-width: ${this.iconOnlyBreakpoint})`);
-        this.mqMobile = window.matchMedia(`(max-width: ${this.mobileBreakpoint})`);
+        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;
@@ -394,37 +361,6 @@ export class LyraAppRail extends LyraElement {
             return;
         this.open = next;
         this.emit('lyra-toggle', { open: next });
-        if (!next)
-            this.lastTrigger?.focus();
-    }
-    // Bounds Tab/Shift+Tab to the panel while the overlay is open. Order
-    // follows the header slot, then the nav (default) slot, then the footer
-    // slot -- the same order the flattened tree already tabs through. The
-    // toggle button itself is deliberately excluded, same as a dialog trigger
-    // living outside its own trap.
-    getFocusableElements() {
-        const root = this.shadowRoot;
-        if (!root)
-            return [];
-        const fromSlot = (selector) => {
-            const slot = root.querySelector(selector);
-            return slot ? slot.assignedElements({ flatten: true }).flatMap(collectFocusable) : [];
-        };
-        return [
-            ...fromSlot('slot[name="header"]'),
-            ...fromSlot('slot:not([name])'),
-            ...fromSlot('slot[name="footer"]'),
-        ].filter(isRendered);
-    }
-    getActiveElement() {
-        let active = document.activeElement;
-        while (active) {
-            const inner = active.shadowRoot?.activeElement ?? null;
-            if (!inner)
-                break;
-            active = inner;
-        }
-        return active;
     }
     render() {
         const mobile = this._mode === 'mobile';
@@ -453,7 +389,7 @@ export class LyraAppRail extends LyraElement {
           <slot name="header" @slotchange=${this.onHeaderSlotChange}></slot>
         </div>
         <div part="nav">
-          <slot @click=${this.onNavItemClick}></slot>
+          <slot @slotchange=${this.onNavSlotChange} @click=${this.onNavItemClick}></slot>
         </div>
         <div part="footer" ?hidden=${!this.hasFooterSlot}>
           <slot name="footer" @slotchange=${this.onFooterSlotChange}></slot>

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

@@ -39,7 +39,7 @@ export const styles = css `
   [part='backdrop'] {
     position: fixed;
     inset: 0;
-    z-index: 999;
+    z-index: var(--lyra-overlay-stack-index, 1000);
     background: var(--lyra-app-rail-overlay-color);
   }
 
@@ -68,7 +68,7 @@ export const styles = css `
     position: fixed;
     inset-block: 0;
     inset-inline-start: 0;
-    z-index: 1000;
+    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);
@@ -115,6 +115,9 @@ export const styles = css `
   :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'],