@aceshooting/lyra-ui 2.0.0 → 2.1.0

package/dist/components/responsive-panel/responsive-panel.js

@@ -7,43 +7,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
+import { activateOverlay, deepActiveElement } from '../../internal/overlay-manager.js';
 import { defineElement } from '../../internal/prefix.js';
 import { lockScroll } from '../../internal/scroll-lock.js';
 import { styles } from './responsive-panel.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 -- every
-// overlay-shaped component in this family (lyra-dialog, lyra-widget,
-// lyra-tool-result-dialog, lyra-tool-select-dialog) re-implements this
-// locally rather than nesting a previous overlay component inside its own
-// shadow DOM, because slot-forwarding would break the inner component's own
-// light-DOM scanning.
-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 identical helper. */
-function isRendered(el) {
-    return el.checkVisibility ? el.checkVisibility() : el.getClientRects().length > 0;
-}
+const HEADING_SELECTOR = 'h1, h2, h3, h4, h5, h6, [role="heading"]';
 /**
  * Pure resolution of the `mode` prop + current viewport into the actual
  * presentation. Kept separate from the `matchMedia` listener wiring below so
@@ -73,18 +41,26 @@ export function resolveEffectiveMode(mode, belowBreakpoint) {
  * attributes and backdrop element, differ), so lit-html's diffing keeps
  * `[part="body"]` and its `<slot>` as the same DOM node across the
  * transition -- scroll position and focus inside the slotted content survive
- * it for free, with no extra bookkeeping required. The one exception is
- * focus: crossing the breakpoint while already open does *not* forcibly
- * move focus into the panel (unlike an `open` transition, which does) --
- * doing so on a resize could yank focus away from an input the user is
- * actively typing into inside the now-newly-modal panel, which is worse UX
- * than a modal that's very briefly missing its initial focus placement.
+ * it for free. When an open inline panel becomes modal, focus already inside
+ * is preserved and outside focus moves to the first available target. Closing
+ * still returns to the opener captured by the original inline open.
+ *
+ * The overlay presentation uses the library's shared overlay coordinator for
+ * focus trapping, Escape/backdrop dismissal, inerting, and stack ordering,
+ * while retaining this component's own responsive rendering and close event.
  *
- * The overlay presentation duplicates lyra-dialog's `role="dialog"` +
- * focus-trap + Escape/backdrop-dismiss + scroll-lock mechanics locally
- * rather than nesting a `<lyra-dialog>` inside this component's shadow DOM,
- * per the established precedent for every overlay-shaped component in this
- * family (see lyra-dialog's own module doc).
+ * Accessible name (overlay presentation only -- the inline presentation has
+ * no dialog semantics to name): `label`, when set, is used verbatim. When
+ * `label` is empty, this falls back to the `header` slot's content -- a
+ * heading element (`h1`–`h6` or `[role="heading"]`) among the slotted header
+ * content wins if present, otherwise the header slot's full text content is
+ * used, mirroring lyra-dialog's `detectHeading()`/`headingText` fallback (see
+ * dialog.ts's module doc for why this uses `aria-label`, a copied string,
+ * rather than `aria-labelledby`: the header content is light DOM while
+ * `[part="panel"]` lives in this element's shadow tree, and an ID-reference
+ * attribute can't resolve across that boundary). A panel opened without
+ * either `label` or header content still renders `role="dialog"` with no
+ * accessible name -- set one of the two to avoid that.
  *
  * @customElement lyra-responsive-panel
  * @slot - The panel body.
@@ -126,7 +102,8 @@ export class LyraResponsivePanel extends LyraElement {
          *  height. */
         this.variant = 'fullscreen';
         /** Accessible name for the overlay presentation's `role="dialog"`. Unused in the inline
-         *  presentation, which has no dialog semantics to name. */
+         *  presentation, which has no dialog semantics to name. When empty, falls back to the `header`
+         *  slot's content -- see the class doc for the full fallback order. */
         this.label = '';
         /** CSS length passed to `matchMedia` as `(max-width: <this>)` to decide, in `mode="auto"`,
          *  whether the effective presentation is `'overlay'` (below/at this width) or `'inline'`
@@ -136,50 +113,25 @@ export class LyraResponsivePanel extends LyraElement {
         this.effectiveMode = 'inline';
         this.hasHeaderSlot = false;
         this.hasFooterSlot = false;
-        /** Whether the overlay-only mechanics (scroll-lock, document Escape/Tab trap) are currently
+        /** Whether the overlay-only mechanics (scroll-lock and shared overlay registration) are currently
          *  engaged -- derived from `effectiveMode === 'overlay' && open`, tracked separately from those
          *  two properties so willUpdate can diff "was engaged" vs "should be engaged now" regardless of
          *  which of the two changed. */
         this.overlayChromeActive = false;
+        this.focusOverlayAfterUpdate = false;
         this.isFirstUpdate = true;
         this.onMediaChange = (e) => {
             this.handleBreakpointChange(e.matches);
         };
         this.onHeaderSlotChange = (e) => {
             this.hasHeaderSlot = e.target.assignedElements({ flatten: true }).length > 0;
+            this.headingText = this.detectHeadingText();
         };
         this.onFooterSlotChange = (e) => {
             this.hasFooterSlot = e.target.assignedElements({ flatten: true }).length > 0;
         };
         this.onBackdropClick = () => {
-            this.close('backdrop');
-        };
-        this.onDocKeyDown = (e) => {
-            if (!this.overlayChromeActive)
-                return;
-            if (e.key === 'Escape') {
-                e.preventDefault();
-                this.close('escape');
-                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.overlayHandle?.dismissBackdrop();
         };
     }
     static { this.styles = [LyraElement.styles, styles]; }
@@ -188,46 +140,69 @@ export class LyraResponsivePanel extends LyraElement {
         if (this.isFirstUpdate) {
             this.hasHeaderSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'header');
             this.hasFooterSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'footer');
+            this.headingText = this.detectHeadingText();
+        }
+        // Must run before the effectiveMode computation below reads
+        // belowBreakpoint: setupMediaQuery() -> handleBreakpointChange() mutates
+        // belowBreakpoint synchronously, and a runtime mobileBreakpoint change is
+        // otherwise the only kind of change in this method that doesn't itself
+        // touch mode/belowBreakpoint, so computing effectiveMode first would read
+        // the not-yet-updated belowBreakpoint and never get another chance to
+        // react -- a property write from inside willUpdate doesn't schedule a
+        // fresh update, it only folds into the one already in progress.
+        // mobileBreakpoint is present on the very first willUpdate too (Lit's
+        // changed-properties map includes every class-field default from
+        // construction), but connectedCallback() already called setupMediaQuery()
+        // once before this first update runs, so repeating it here would be
+        // redundant -- only a live post-mount change should re-run it.
+        if (!this.isFirstUpdate && changed.has('mobileBreakpoint') && this.isConnected) {
+            this.setupMediaQuery();
         }
         if (this.isFirstUpdate || changed.has('mode') || changed.has('belowBreakpoint')) {
             this.effectiveMode = resolveEffectiveMode(this.mode, this.belowBreakpoint);
         }
-        if (changed.has('mobileBreakpoint') && this.isConnected) {
-            this.setupMediaQuery();
+        // Captured on a genuine open transition only, independent of
+        // effectiveMode at that moment -- so it reflects whatever triggered the
+        // open even if a later breakpoint crossing (while still open) switches
+        // the presentation to overlay before close() runs. Deliberately not
+        // folded into the overlayOpen-engage branch below: that branch also
+        // fires when only effectiveMode (not open) changes, which would
+        // re-capture whatever currently has focus (e.g. something inside the
+        // panel) instead of the original external trigger.
+        if (changed.has('open') && this.open) {
+            const active = deepActiveElement(this.ownerDocument);
+            this.lastTrigger = active && typeof active.focus === 'function' ? active : undefined;
         }
         const overlayOpen = this.effectiveMode === 'overlay' && this.open;
         if (overlayOpen !== this.overlayChromeActive) {
             this.overlayChromeActive = overlayOpen;
             if (overlayOpen) {
-                const active = this.getActiveElement();
-                this.lastTrigger = active instanceof HTMLElement ? active : undefined;
-                this.releaseScrollLock = lockScroll();
-                document.addEventListener('keydown', this.onDocKeyDown);
+                this.activateOverlayChrome();
+                // Once the presentation becomes modal, focus cannot remain behind
+                // it. The manager preserves focus that is already inside the panel
+                // and otherwise moves it to the first composed focus target.
+                this.focusOverlayAfterUpdate = true;
             }
             else {
-                this.releaseScrollLock?.();
-                this.releaseScrollLock = undefined;
-                document.removeEventListener('keydown', this.onDocKeyDown);
+                // Removing modal chrome while the still-open panel becomes inline
+                // must preserve focus in that same panel. Only a real open -> closed
+                // transition restores the opener.
+                this.deactivateOverlayChrome(changed.has('open') && !this.open);
             }
         }
+        if (changed.has('open') && !this.open)
+            this.lastTrigger = undefined;
     }
     // Runs after render (not willUpdate) so [part="panel"] has already landed
     // in the DOM before the fallback .focus() call below can rely on it --
-    // mirrors lyra-dialog's identical ordering rationale. Only a genuine `open`
-    // transition steals focus (see the class doc for why a breakpoint-crossing
-    // while already open deliberately does not).
+    // mirrors lyra-dialog's identical ordering rationale.
     updated(changed) {
         if (!this.isFirstUpdate && changed.has('effectiveMode')) {
             this.emit('lyra-mode-change', { mode: this.effectiveMode });
         }
-        if (changed.has('open') && this.open && this.effectiveMode === 'overlay') {
-            const first = this.getFocusableElements()[0];
-            if (first) {
-                first.focus();
-            }
-            else {
-                this.shadowRoot?.querySelector('[part="panel"]')?.focus();
-            }
+        if (this.focusOverlayAfterUpdate) {
+            this.focusOverlayAfterUpdate = false;
+            this.overlayHandle?.focusInitial();
         }
     }
     connectedCallback() {
@@ -237,10 +212,17 @@ export class LyraResponsivePanel extends LyraElement {
         // instance) fires disconnectedCallback then connectedCallback
         // synchronously with no update in between, so willUpdate never reruns to
         // notice overlay chrome is still supposed to be active -- restore it.
-        // Mirrors lyra-dialog's identical reconnect handling.
-        if (this.hasUpdated && this.overlayChromeActive && !this.releaseScrollLock) {
-            this.releaseScrollLock = lockScroll();
-            document.addEventListener('keydown', this.onDocKeyDown);
+        const overlayOpen = resolveEffectiveMode(this.mode, this.belowBreakpoint) === 'overlay' && this.open;
+        if (this.hasUpdated && overlayOpen) {
+            if (this.overlayHandle?.isActive()) {
+                this.overlayHandle.resume();
+            }
+            else {
+                this.activateOverlayChrome();
+            }
+            if (!this.releaseScrollLock)
+                this.releaseScrollLock = lockScroll(this.ownerDocument);
+            queueMicrotask(() => this.overlayHandle?.focusInitial());
         }
     }
     disconnectedCallback() {
@@ -249,11 +231,32 @@ export class LyraResponsivePanel extends LyraElement {
         this.mediaQuery = undefined;
         this.releaseScrollLock?.();
         this.releaseScrollLock = undefined;
-        document.removeEventListener('keydown', this.onDocKeyDown);
+        this.overlayHandle?.suspend();
+    }
+    activateOverlayChrome() {
+        this.releaseScrollLock ??= lockScroll(this.ownerDocument);
+        this.overlayHandle = activateOverlay({
+            host: this,
+            panel: () => this.shadowRoot?.querySelector('[part="panel"]') ?? null,
+            onEscape: () => this.close('escape'),
+            onBackdrop: () => this.close('backdrop'),
+            restoreFocusTo: this.lastTrigger ?? null,
+        });
+    }
+    deactivateOverlayChrome(restoreFocus = true) {
+        this.releaseScrollLock?.();
+        this.releaseScrollLock = undefined;
+        this.overlayHandle?.deactivate({ restoreFocus });
+        this.overlayHandle = undefined;
     }
     setupMediaQuery() {
         this.mediaQuery?.removeEventListener('change', this.onMediaChange);
-        this.mediaQuery = window.matchMedia(`(max-width: ${this.mobileBreakpoint})`);
+        const view = this.ownerDocument.defaultView;
+        if (!view?.matchMedia) {
+            this.mediaQuery = undefined;
+            return;
+        }
+        this.mediaQuery = view.matchMedia(`(max-width: ${this.mobileBreakpoint})`);
         this.mediaQuery.addEventListener('change', this.onMediaChange);
         this.handleBreakpointChange(this.mediaQuery.matches);
     }
@@ -263,6 +266,27 @@ export class LyraResponsivePanel extends LyraElement {
     handleBreakpointChange(matches) {
         this.belowBreakpoint = matches;
     }
+    // Only direct children slotted into `header` are scanned -- same depth
+    // limit lyra-dialog's own detectHeading() applies to its direct children.
+    // A heading tag among them wins (its own text only, so a header slot mixing
+    // a heading with e.g. a trailing icon button doesn't pull the button's
+    // label into the accessible name); otherwise the header slot's combined
+    // text stands in for it, since this component (unlike lyra-dialog) has a
+    // dedicated header slot that's already the conventional place a heading
+    // would go. Recomputed only on slot assignment changes, not on every
+    // render -- same rationale as lyra-dialog's detectHeading().
+    detectHeadingText() {
+        const headerChildren = Array.from(this.children).filter((el) => el.getAttribute('slot') === 'header');
+        if (headerChildren.length === 0)
+            return undefined;
+        const heading = headerChildren.find((el) => el.matches(HEADING_SELECTOR));
+        if (heading)
+            return heading.textContent?.trim() || undefined;
+        return (headerChildren
+            .map((el) => el.textContent?.trim())
+            .filter(Boolean)
+            .join(' ') || undefined);
+    }
     /**
      * Close the panel. `reason` is forwarded as the `lyra-close` detail --
      * built-in overlay triggers pass `'escape'`/`'backdrop'`; a consumer's own
@@ -278,39 +302,10 @@ export class LyraResponsivePanel extends LyraElement {
             return;
         this.open = false;
         this.emit('lyra-close', reason);
-        if (this.effectiveMode === 'overlay') {
-            this.lastTrigger?.focus();
-        }
-    }
-    // Bounds Tab/Shift+Tab to the panel while overlay chrome is active. Order
-    // follows the header slot, then the body slot, then the footer slot -- the
-    // same order the flattened tree already tabs through.
-    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 overlay = this.effectiveMode === 'overlay';
+        const accessibleName = this.label || this.headingText;
         return html `
       <div part="base" class=${overlay ? 'overlay' : 'inline'}>
         ${overlay ? html `<div part="backdrop" @click=${this.onBackdropClick}></div>` : nothing}
@@ -318,7 +313,7 @@ export class LyraResponsivePanel extends LyraElement {
           part="panel"
           role=${overlay ? 'dialog' : nothing}
           aria-modal=${overlay ? 'true' : nothing}
-          aria-label=${overlay && this.label ? this.label : nothing}
+          aria-label=${overlay && accessibleName ? accessibleName : nothing}
           tabindex=${overlay ? '-1' : nothing}
         >
           <div part="header" ?hidden=${!this.hasHeaderSlot}>
@@ -362,4 +357,7 @@ __decorate([
 __decorate([
     state()
 ], LyraResponsivePanel.prototype, "hasFooterSlot", void 0);
+__decorate([
+    state()
+], LyraResponsivePanel.prototype, "headingText", void 0);
 defineElement('responsive-panel', LyraResponsivePanel);

package/dist/components/responsive-panel/responsive-panel.styles.js

@@ -24,7 +24,7 @@ export const styles = css `
     display: flex;
     position: fixed;
     inset: 0;
-    z-index: 1000;
+    z-index: var(--lyra-overlay-stack-index, 1000);
   }
   /* Bottom-sheet anchors its panel to the block-end edge instead of
      stretching it full-height like fullscreen does. */

package/dist/components/result-card/result-card.d.ts

@@ -22,7 +22,10 @@ import { LyraElement } from '../../internal/lyra-element.js';
  * `actions` is still observed) but `hidden` whenever there is no `title`
  * and no `actions` content — an untitled, action-less card has no visible
  * header bar at all.
- * @csspart title - The title text.
+ * @csspart title - The title text. Truncates with an ellipsis when it
+ * overflows; carries its own native `title` attribute (the full string) so
+ * hovering the truncated text reveals it via the browser's default tooltip,
+ * scoped to just this element rather than the whole card.
  * @csspart actions - The wrapper around the `actions` slot. `hidden`
  * whenever the slot has no assigned content.
  * @csspart body - The wrapper around the default slot.
@@ -30,7 +33,10 @@ import { LyraElement } from '../../internal/lyra-element.js';
 export declare class LyraResultCard extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
     /** Small heading for the card. Leave unset for an untitled card (e.g. a
-     *  bare block of `<lyra-result-field>` rows with no natural heading). */
+     *  bare block of `<lyra-result-field>` rows with no natural heading).
+     *  Rendered into the truncating `[part="title"]` span, which also carries
+     *  this value as its own `title` attribute so the disclosure tooltip is
+     *  scoped to that element rather than the whole host. */
     title: string;
     private hasActionsSlot;
     protected willUpdate(): void;

package/dist/components/result-card/result-card.js

@@ -31,7 +31,10 @@ import { styles } from './result-card.styles.js';
  * `actions` is still observed) but `hidden` whenever there is no `title`
  * and no `actions` content — an untitled, action-less card has no visible
  * header bar at all.
- * @csspart title - The title text.
+ * @csspart title - The title text. Truncates with an ellipsis when it
+ * overflows; carries its own native `title` attribute (the full string) so
+ * hovering the truncated text reveals it via the browser's default tooltip,
+ * scoped to just this element rather than the whole card.
  * @csspart actions - The wrapper around the `actions` slot. `hidden`
  * whenever the slot has no assigned content.
  * @csspart body - The wrapper around the default slot.
@@ -40,7 +43,10 @@ export class LyraResultCard extends LyraElement {
     constructor() {
         super(...arguments);
         /** Small heading for the card. Leave unset for an untitled card (e.g. a
-         *  bare block of `<lyra-result-field>` rows with no natural heading). */
+         *  bare block of `<lyra-result-field>` rows with no natural heading).
+         *  Rendered into the truncating `[part="title"]` span, which also carries
+         *  this value as its own `title` attribute so the disclosure tooltip is
+         *  scoped to that element rather than the whole host. */
         this.title = '';
         // See `<lyra-widget>`'s identical `hasActionsSlot` -- a `[part]` wrapper
         // always contains a literal `<slot>` child regardless of assigned
@@ -64,7 +70,7 @@ export class LyraResultCard extends LyraElement {
         return html `
       <div part="base">
         <div part="header" ?hidden=${!hasHeader}>
-          ${hasTitle ? html `<span part="title">${this.title}</span>` : nothing}
+          ${hasTitle ? html `<span part="title" title=${this.title}>${this.title}</span>` : nothing}
           <div part="actions" ?hidden=${!this.hasActionsSlot}>
             <slot name="actions" @slotchange=${this.onActionsSlotChange}></slot>
           </div>

package/dist/components/result-card/result-card.styles.js

@@ -27,7 +27,6 @@ export const styles = css `
     min-inline-size: 0;
     color: var(--lyra-color-text);
     font-weight: 600;
-    font-size: 0.8125rem;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;

package/dist/components/select/select.d.ts

@@ -21,16 +21,21 @@ export type LyraSelectSize = 'xs' | 's' | 'm' | 'l' | 'xl';
  * "active" row is conveyed via `aria-activedescendant`, never actual focus),
  * matching the WAI-ARIA "select-only combobox" pattern.
  *
- * When exactly one option is enabled (regardless of how many disabled ones
- * exist alongside it), the popup never opens at all: a click, Enter, Space,
- * ArrowDown, or ArrowUp on the trigger commits that sole option directly,
- * and the trigger renders as a plain `role="button"` with no chevron/
- * `aria-haspopup`/`aria-expanded` rather than a combobox with a permanently
- * inert popup state — opening a one-row list to pick the only available
- * choice is pure friction with no real decision behind it. This never
- * changes `value`/validity defaults on its own — an unselected single-option
- * select stays unselected (and a `required` one stays invalid) exactly like
- * the multi-option case, until the trigger is actually activated.
+ * When `autoCommitSingleOption` is set and exactly one option is enabled
+ * (regardless of how many disabled ones exist alongside it), the popup never
+ * opens at all: a click, Enter, Space, ArrowDown, or ArrowUp on the trigger
+ * commits that sole option directly, and the trigger renders as a plain
+ * `role="button"` with no chevron/`aria-haspopup`/`aria-expanded` rather than
+ * a combobox with a permanently inert popup state — opening a one-row list to
+ * pick the only available choice is pure friction with no real decision
+ * behind it. This never changes `value`/validity defaults on its own — an
+ * unselected single-option select stays unselected (and a `required` one
+ * stays invalid) exactly like the multi-option case, until the trigger is
+ * actually activated. `autoCommitSingleOption` defaults to `false`: by
+ * default a select always renders the normal combobox/listbox/chevron
+ * trigger no matter how many options are enabled, matching pre-1.3.0
+ * behavior — opt in explicitly if a narrowing-to-one option list should
+ * auto-commit.
  *
  * @customElement lyra-select
  * @slot - `<lyra-option>` elements.
@@ -58,6 +63,16 @@ export declare class LyraSelect extends LyraElement {
     static formAssociated: boolean;
     static styles: import("lit").CSSResultGroup[];
     static properties: {
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+        required: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            noAccessor: boolean;
+        };
         value: {
             noAccessor: boolean;
         };
@@ -67,14 +82,22 @@ export declare class LyraSelect extends LyraElement {
         };
     };
     placeholder: string;
-    disabled: boolean;
-    required: boolean;
     label: string;
     hint: string;
     errorText: string;
     open: boolean;
     /** Visual size — same `xs`–`xl` scale as `lyra-toast-item`'s `size`. */
     size: LyraSelectSize;
+    /**
+     * Opt-in: when `true` and exactly one `<lyra-option>` is enabled, the
+     * trigger commits that option directly (click/Enter/Space/ArrowDown/
+     * ArrowUp) instead of opening the listbox, and renders as a plain
+     * `role="button"` with no chevron. Defaults to `false`, which always
+     * renders the normal combobox/listbox/chevron trigger regardless of how
+     * many options are enabled — the pre-1.3.0 behavior. See the class doc
+     * above and `onlyOption` below for the full rationale.
+     */
+    autoCommitSingleOption: boolean;
     private activeIndex;
     private options;
     private touched;
@@ -82,22 +105,35 @@ export declare class LyraSelect extends LyraElement {
     private hasErrorSlot;
     private hasLabelSlot;
     private internals;
+    private validityController;
     private _fieldsetDisabled;
     private listId;
     private triggerId;
     private cleanup?;
     private _isFirstUpdate;
     private _selected;
+    private _disabled;
+    private _required;
     private _defaultSelected;
     private _defaultCaptured;
+    private _restoredStateActive;
     private typeAheadBuffer;
     private typeAheadTimer?;
     private _name;
     constructor();
+    get form(): HTMLFormElement | null;
+    get labels(): NodeList;
+    get validity(): ValidityState;
+    get validationMessage(): string;
+    get willValidate(): boolean;
     connectedCallback(): void;
     protected willUpdate(): void;
     get name(): string;
     set name(next: string);
+    get disabled(): boolean;
+    set disabled(next: boolean);
+    get required(): boolean;
+    set required(next: boolean);
     /** The selected value: a single string (empty when nothing is selected). */
     get value(): string;
     set value(next: string);
@@ -108,6 +144,7 @@ export declare class LyraSelect extends LyraElement {
      *  own `disabled` IDL property/attribute is never mutated by a fieldset. */
     get effectiveDisabled(): boolean;
     formResetCallback(): void;
+    formStateRestoreCallback(state: string | File | FormData | null, _mode?: 'restore' | 'autocomplete'): void;
     /**
      * Called by the browser when an ancestor `<fieldset disabled>` toggles.
      * Tracked separately from the consumer's own `disabled` (see
@@ -121,14 +158,16 @@ export declare class LyraSelect extends LyraElement {
     private collectOptions;
     private reflectSelected;
     /**
-     * The sole navigable (non-disabled) option, when there's exactly one. Opening a one-row
-     * popup to pick the only available choice is pure friction with no real decision behind
-     * it, so a single-option select skips the popup entirely -- see `onTriggerClick`/`onKeyDown`,
-     * which commit this option directly on activation instead of opening the listbox, and
-     * `render()`, which drops the popup-trigger ARIA semantics (`role="combobox"`,
-     * `aria-haspopup`, `aria-expanded`, the chevron) in favor of a plain button's, since no
-     * popup can ever appear while this getter returns a value. Does not affect `value`/
-     * validity defaults in any way -- an unselected single-option select stays unselected
+     * The sole navigable (non-disabled) option, when `autoCommitSingleOption` is set and
+     * there's exactly one. Opening a one-row popup to pick the only available choice is pure
+     * friction with no real decision behind it, so an opted-in single-option select skips the
+     * popup entirely -- see `onTriggerClick`/`onKeyDown`, which commit this option directly on
+     * activation instead of opening the listbox, and `render()`, which drops the popup-trigger
+     * ARIA semantics (`role="combobox"`, `aria-haspopup`, `aria-expanded`, the chevron) in favor
+     * of a plain button's, since no popup can ever appear while this getter returns a value.
+     * Returns `undefined` whenever `autoCommitSingleOption` is `false` (the default), regardless
+     * of option count, so the normal combobox trigger renders unconditionally. Does not affect
+     * `value`/validity defaults in any way -- an unselected single-option select stays unselected
      * until the trigger is actually activated, exactly like the multi-option case.
      */
     private get onlyOption();