@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/internal/anchored-validity.js

@@ -0,0 +1,86 @@
+/** @internal */
+export const VALIDITY_ANCHOR = Symbol('lyra-validity-anchor');
+/** @internal */
+export const SET_ANCHORED_VALIDITY = Symbol('lyra-set-anchored-validity');
+/** @internal */
+export function resolveValidityAnchor(provider) {
+    if (!provider || (typeof provider !== 'object' && typeof provider !== 'function'))
+        return undefined;
+    const resolver = provider[VALIDITY_ANCHOR];
+    if (typeof resolver !== 'function')
+        return undefined;
+    return resolver.call(provider) ?? undefined;
+}
+/**
+ * Keeps ElementInternals validity synchronous while refreshing its focus
+ * anchor after every render. The refresh is required because validity can be
+ * computed before the first shadow render and because conditional templates
+ * can replace a previously registered anchor.
+ *
+ * @internal
+ */
+export class AnchoredValidityController {
+    constructor(host, internals, getAnchor) {
+        this.host = host;
+        this.internals = internals;
+        this.getAnchor = getAnchor;
+        this.flags = {};
+        this.message = '';
+        this.revision = 0;
+        this.refreshToken = 0;
+        host.addController(this);
+    }
+    setValidity(flags = {}, message = '') {
+        this.flags = { ...flags };
+        this.message = message;
+        this.revision += 1;
+        this.apply();
+    }
+    refreshAnchor() {
+        if (this.isInvalid())
+            this.apply();
+    }
+    hostUpdated() {
+        if (!this.isInvalid())
+            return;
+        const revision = this.revision;
+        const token = ++this.refreshToken;
+        // Rebind just after the host's update so focus side effects from an
+        // already-visible validation UI cannot schedule a new Lit update from
+        // inside hostUpdated(). This microtask runs before updateComplete settles.
+        queueMicrotask(() => {
+            if (token !== this.refreshToken || revision !== this.revision)
+                return;
+            if (this.apply())
+                return;
+            // Nested custom controls may render one microtask after their parent.
+            // Retry once so an outer form can anchor inside that nested shadow tree.
+            queueMicrotask(() => {
+                if (token === this.refreshToken && revision === this.revision)
+                    this.apply();
+            });
+        });
+    }
+    isInvalid() {
+        return Object.values(this.flags).some(Boolean);
+    }
+    /** Returns true when an invalid state was installed with a real anchor. */
+    apply() {
+        const anchor = this.isInvalid() ? this.getAnchor() : undefined;
+        if (anchor?.isConnected) {
+            try {
+                this.internals.setValidity(this.flags, this.message, anchor);
+                return true;
+            }
+            catch (error) {
+                // A stale or incorrectly provided non-descendant anchor must not
+                // break the host's update. Preserve validity and fall back to the
+                // host until the next fresh render resolves a legal descendant.
+                if (!(error instanceof DOMException) || error.name !== 'NotFoundError')
+                    throw error;
+            }
+        }
+        this.internals.setValidity(this.flags, this.message);
+        return false;
+    }
+}

package/dist/internal/announcer.d.ts

@@ -0,0 +1,57 @@
+/** Options for a single `Announcer.announce()` call. */
+export interface AnnounceOptions {
+    /** Bypass any in-progress throttle window and flush this text immediately. */
+    force?: boolean;
+}
+export interface AnnouncerOptions {
+    /** Throttle window in ms. Repeated `announce()` calls arriving within this
+     *  window of the first call in a burst collapse to one trailing-edge flush
+     *  of the latest text. Defaults to 500. */
+    throttleMs?: number;
+    /** Invoked with the coalesced text whenever a burst flushes (on the
+     *  trailing edge, or immediately for a `{ force: true }` call). */
+    onFlush: (text: string) => void;
+}
+/**
+ * Trailing-edge debounce/coalesce for screen-reader announcements.
+ *
+ * Streaming UIs (token-by-token chat responses, progress ticks, etc.)
+ * naturally produce far more candidate announcements than a screen-reader
+ * user can usefully absorb — reading every incremental chunk aloud is spam,
+ * not information. `Announcer` collapses a burst of `announce()` calls
+ * arriving within `throttleMs` of the *first* call in that burst down to a
+ * single flush of the latest text: superseded intermediate text is dropped
+ * outright, never queued or concatenated. Passing `{ force: true }` always
+ * flushes immediately regardless of any window in progress, so a final or
+ * terminal message (e.g. "response complete") is never swallowed mid-burst.
+ *
+ * This is pure timing/state logic with no DOM dependency — it knows nothing
+ * about ARIA, elements, or Lit. `<lyra-live-region>`
+ * (`../components/live-region/live-region.js`) is the DOM-facing wrapper
+ * that composes one of these with an actual live-region element. Other
+ * components that need throttled announcements (a stream-status indicator,
+ * a tool-call chip's status transitions, a chat message's streaming state)
+ * should reuse that wrapper rather than instantiating `Announcer` directly.
+ */
+export declare class Announcer {
+    /** Throttle window in ms. Safe to change between bursts; a flush already
+     *  scheduled keeps the deadline it was scheduled with. */
+    throttleMs: number;
+    private readonly onFlush;
+    private timer?;
+    private pending?;
+    constructor(options: AnnouncerOptions);
+    /** The latest text awaiting flush, if a burst is currently in progress. */
+    get pendingText(): string | undefined;
+    /** Whether a flush is currently scheduled (a burst is in progress). */
+    get isPending(): boolean;
+    /**
+     * Queue `text` for announcement. Within a single throttle window, only the
+     * latest text queued survives — this call always overwrites whatever an
+     * earlier call in the same burst queued.
+     */
+    announce(text: string, options?: AnnounceOptions): void;
+    /** Cancel any pending (not yet flushed) announcement without flushing it. */
+    cancel(): void;
+    private flush;
+}

package/dist/internal/announcer.js

@@ -0,0 +1,71 @@
+const DEFAULT_THROTTLE_MS = 500;
+/**
+ * Trailing-edge debounce/coalesce for screen-reader announcements.
+ *
+ * Streaming UIs (token-by-token chat responses, progress ticks, etc.)
+ * naturally produce far more candidate announcements than a screen-reader
+ * user can usefully absorb — reading every incremental chunk aloud is spam,
+ * not information. `Announcer` collapses a burst of `announce()` calls
+ * arriving within `throttleMs` of the *first* call in that burst down to a
+ * single flush of the latest text: superseded intermediate text is dropped
+ * outright, never queued or concatenated. Passing `{ force: true }` always
+ * flushes immediately regardless of any window in progress, so a final or
+ * terminal message (e.g. "response complete") is never swallowed mid-burst.
+ *
+ * This is pure timing/state logic with no DOM dependency — it knows nothing
+ * about ARIA, elements, or Lit. `<lyra-live-region>`
+ * (`../components/live-region/live-region.js`) is the DOM-facing wrapper
+ * that composes one of these with an actual live-region element. Other
+ * components that need throttled announcements (a stream-status indicator,
+ * a tool-call chip's status transitions, a chat message's streaming state)
+ * should reuse that wrapper rather than instantiating `Announcer` directly.
+ */
+export class Announcer {
+    constructor(options) {
+        this.throttleMs = options.throttleMs ?? DEFAULT_THROTTLE_MS;
+        this.onFlush = options.onFlush;
+    }
+    /** The latest text awaiting flush, if a burst is currently in progress. */
+    get pendingText() {
+        return this.pending;
+    }
+    /** Whether a flush is currently scheduled (a burst is in progress). */
+    get isPending() {
+        return this.timer !== undefined;
+    }
+    /**
+     * Queue `text` for announcement. Within a single throttle window, only the
+     * latest text queued survives — this call always overwrites whatever an
+     * earlier call in the same burst queued.
+     */
+    announce(text, options = {}) {
+        this.pending = text;
+        if (options.force) {
+            this.flush();
+            return;
+        }
+        // Only the first call of a burst schedules the timer; later calls inside
+        // the same window just overwrite `pending` above, so the flush deadline
+        // stays anchored to the first call (trailing-edge debounce) instead of
+        // being pushed back on every subsequent call.
+        this.timer ??= setTimeout(() => this.flush(), this.throttleMs);
+    }
+    /** Cancel any pending (not yet flushed) announcement without flushing it. */
+    cancel() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.pending = undefined;
+    }
+    flush() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        const text = this.pending;
+        this.pending = undefined;
+        if (text !== undefined)
+            this.onFlush(text);
+    }
+}

package/dist/internal/form-associated.d.ts

@@ -7,9 +7,17 @@ export interface FormAssociatedInterface {
     value: string;
     disabled: boolean;
     required: boolean;
+    readonly effectiveDisabled: boolean;
+    readonly form: HTMLFormElement | null;
+    readonly labels: NodeList;
+    readonly validity: ValidityState;
+    readonly validationMessage: string;
+    readonly willValidate: boolean;
     setFormValue(next: string): void;
     checkValidity(): boolean;
     reportValidity(): boolean;
+    formResetCallback(): void;
+    formStateRestoreCallback(state: string | File | FormData | null, mode?: 'restore' | 'autocomplete'): void;
 }
 /**
  * Mixin that turns a Lit component into a form-associated custom element via

package/dist/internal/form-associated.js

@@ -1,3 +1,4 @@
+import { AnchoredValidityController, SET_ANCHORED_VALIDITY, VALIDITY_ANCHOR, } from './anchored-validity.js';
 /**
  * Mixin that turns a Lit component into a form-associated custom element via
  * `ElementInternals`, so it participates in native `<form>` submission,
@@ -13,16 +14,22 @@ export function FormAssociated(Base) {
     class FormAssociatedElement extends Base {
         static { this.formAssociated = true; }
         static { this.properties = {
-            name: {},
+            name: { reflect: true, noAccessor: true },
             value: { noAccessor: true },
-            disabled: { type: Boolean, reflect: true },
-            required: { type: Boolean, reflect: true },
+            disabled: { type: Boolean, reflect: true, noAccessor: true },
+            required: { type: Boolean, reflect: true, noAccessor: true },
         }; }
         constructor(...args) {
             super(...args);
-            this.name = '';
-            this.disabled = false;
-            this.required = false;
+            this._fieldsetDisabled = false;
+            this._disabled = false;
+            // Hand-written accessor (mirrors `value`/`required` below): native form
+            // submission for a form-associated custom element keys its `FormData`
+            // entry off the `name` *content attribute*, read synchronously at
+            // submission time — an async (Lit-scheduled) reflection would leave a
+            // property-only assignment like `el.name = 'foo'` invisible to a
+            // same-tick `new FormData(form)`/submit.
+            this._name = '';
             this._value = '';
             // What native `defaultValue`/`form.reset()` restores to. Mirrors the
             // `value` *content attribute* only (see `attributeChangedCallback`
@@ -34,7 +41,50 @@ export function FormAssociated(Base) {
             // first" would wrongly let a user's first-ever edit become permanent
             // (a required field could never be reset back to blank again).
             this._defaultValue = '';
+            this._required = false;
             this.internals = this.attachInternals();
+            this.validityController = new AnchoredValidityController(this, this.internals, () => this[VALIDITY_ANCHOR]());
+            // Native <input> always has a submission value ("") from construction —
+            // without this, a control whose `value` is never touched is entirely
+            // absent from FormData instead of present as "".
+            this.internals.setFormValue('');
+        }
+        get form() {
+            return this.internals.form;
+        }
+        get labels() {
+            return this.internals.labels;
+        }
+        get validity() {
+            return this.internals.validity;
+        }
+        get validationMessage() {
+            return this.internals.validationMessage;
+        }
+        get willValidate() {
+            return this.internals.willValidate;
+        }
+        /** @internal */
+        [VALIDITY_ANCHOR]() {
+            return this.renderRoot?.querySelector("input:not([type='hidden']), textarea, select, button, [tabindex]:not([tabindex='-1'])") ?? null;
+        }
+        /** @internal */
+        [SET_ANCHORED_VALIDITY](flags, message = '') {
+            this.validityController.setValidity(flags, message);
+        }
+        get name() {
+            return this._name;
+        }
+        set name(next) {
+            const old = this._name;
+            this._name = next ?? '';
+            if (this._name) {
+                this.setAttribute('name', this._name);
+            }
+            else {
+                this.removeAttribute('name');
+            }
+            this.requestUpdate('name', old);
         }
         get value() {
             return this._value;
@@ -46,6 +96,33 @@ export function FormAssociated(Base) {
             this.updateValidity();
             this.requestUpdate('value', old);
         }
+        get disabled() {
+            return this._disabled;
+        }
+        set disabled(next) {
+            const old = this._disabled;
+            this._disabled = Boolean(next);
+            // FACE omission and barred validation are driven by the live host
+            // attribute, so reflection must happen before same-tick form APIs run.
+            this.toggleAttribute('disabled', this._disabled);
+            this.requestUpdate('disabled', old);
+        }
+        get required() {
+            return this._required;
+        }
+        set required(next) {
+            const old = this._required;
+            this._required = next;
+            this.toggleAttribute('required', next);
+            this.updateValidity();
+            this.requestUpdate('required', old);
+        }
+        /** Effective disabled state: this element's own `disabled` OR an ancestor
+         *  `<fieldset disabled>`'s inherited state — mirrors native `<input>`, whose
+         *  own `disabled` IDL property/attribute is never mutated by a fieldset. */
+        get effectiveDisabled() {
+            return this.disabled || this._fieldsetDisabled;
+        }
         attributeChangedCallback(name, old, value) {
             super.attributeChangedCallback(name, old, value);
             if (name === 'value') {
@@ -66,10 +143,10 @@ export function FormAssociated(Base) {
          */
         updateValidity() {
             if (this.required && this._value === '') {
-                this.internals.setValidity({ valueMissing: true }, 'Please fill out this field.');
+                this[SET_ANCHORED_VALIDITY]({ valueMissing: true }, 'Please fill out this field.');
             }
             else {
-                this.internals.setValidity({});
+                this[SET_ANCHORED_VALIDITY]({});
             }
         }
         checkValidity() {
@@ -83,8 +160,19 @@ export function FormAssociated(Base) {
             // semantics) — previously this unconditionally blanked the field.
             this.value = this._defaultValue;
         }
-        formDisabledCallback(disabled) {
-            this.disabled = disabled;
+        formStateRestoreCallback(state, _mode) {
+            this.value = typeof state === 'string' ? state : '';
+        }
+        /**
+         * Called by the browser when an ancestor `<fieldset disabled>` toggles.
+         * Tracked separately from the consumer's own `disabled` (see
+         * `effectiveDisabled`) — a native `<input>`'s own `disabled` IDL
+         * property/attribute is never mutated by fieldset cascading, so a
+         * consumer's explicit `disabled` must survive the fieldset re-enabling.
+         */
+        formDisabledCallback(fieldsetDisabled) {
+            this._fieldsetDisabled = fieldsetDisabled;
+            this.requestUpdate();
         }
         connectedCallback() {
             super.connectedCallback();
@@ -93,11 +181,6 @@ export function FormAssociated(Base) {
             // `value` write.
             this.updateValidity();
         }
-        updated(changed) {
-            super.updated(changed);
-            if (changed.has('required'))
-                this.updateValidity();
-        }
     }
     return FormAssociatedElement;
 }

package/dist/internal/group-by-recency.d.ts

@@ -0,0 +1,50 @@
+/** Per-bucket English defaults, overridable the same "no i18n, but
+ *  overridable via an options object" way `<lyra-date-picker>`/
+ *  `<lyra-source-list>`'s `label-plural` already establish. */
+export interface RecencyLabels {
+    today?: string;
+    yesterday?: string;
+    previousWeek?: string;
+    older?: string;
+}
+export interface GroupByRecencyOptions<T> {
+    /** Extracts the timestamp to bucket `item` by. Defaults to assuming `item`
+     *  itself *is* a `Date` — the simplest possible default for the common
+     *  case of grouping a plain array of dates. A returned `number` is treated
+     *  as a standard JS epoch-milliseconds value (`Date.prototype.getTime()`'s
+     *  own unit) — not GreyCat's micros `time` type; a caller bridging from
+     *  GreyCat data converts in its own `getTimestamp` callback. */
+    getTimestamp?: (item: T) => Date | number | string;
+    /** The "current" instant bucket boundaries are computed relative to.
+     *  Defaults to `new Date()`. Overridable for deterministic tests (and for
+     *  a caller that wants to bucket relative to something other than the
+     *  actual current instant, e.g. a fixed "as of" report time). */
+    now?: Date;
+    /** Overrides for one or more of the four bucket labels. Any label left
+     *  unset keeps its English default. */
+    labels?: RecencyLabels;
+}
+export interface RecencyBucket<T> {
+    label: string;
+    items: T[];
+}
+/**
+ * Buckets `items` into Today / Yesterday / Previous 7 Days / Older, using
+ * calendar-day boundaries in the local timezone — "yesterday" means the
+ * previous calendar date, not "24-48 hours ago". Mirrors the bucketing a
+ * chat sidebar's conversation-history list commonly groups by (this
+ * library's own `<lyra-conversation-item>` is the intended consumer, though
+ * this function is deliberately DOM/component-free — plain data in, plain
+ * data out).
+ *
+ * Only buckets that end up with at least one item are included in the
+ * returned array, in Today/Yesterday/Previous-7-Days/Older order; each
+ * bucket's items keep their original relative order from `items` (never
+ * re-sorted). Two edge cases with no dedicated bucket of their own: a
+ * timestamp dated in the future relative to `now` lands in `Today` — the
+ * most-recent bucket available, since there's no "upcoming" bucket to put it
+ * in instead. A timestamp that fails to parse lands in `Older` instead — it
+ * carries no "this is recent" signal at all, so the oldest/catch-all bucket
+ * is the more honest home for it than the newest one.
+ */
+export declare function groupByRecency<T>(items: T[], options?: GroupByRecencyOptions<T>): RecencyBucket<T>[];

package/dist/internal/group-by-recency.js

@@ -0,0 +1,80 @@
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const DEFAULT_LABELS = {
+    today: 'Today',
+    yesterday: 'Yesterday',
+    previousWeek: 'Previous 7 Days',
+    older: 'Older',
+};
+/** Midnight (start of the local calendar day) for `d`, as epoch millis —
+ *  built from `d`'s own local-timezone Y/M/D fields, so this is a calendar-
+ *  day boundary, not a rolling 24-hour offset from `d` itself. */
+function startOfLocalDay(d) {
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+}
+/**
+ * Buckets `items` into Today / Yesterday / Previous 7 Days / Older, using
+ * calendar-day boundaries in the local timezone — "yesterday" means the
+ * previous calendar date, not "24-48 hours ago". Mirrors the bucketing a
+ * chat sidebar's conversation-history list commonly groups by (this
+ * library's own `<lyra-conversation-item>` is the intended consumer, though
+ * this function is deliberately DOM/component-free — plain data in, plain
+ * data out).
+ *
+ * Only buckets that end up with at least one item are included in the
+ * returned array, in Today/Yesterday/Previous-7-Days/Older order; each
+ * bucket's items keep their original relative order from `items` (never
+ * re-sorted). Two edge cases with no dedicated bucket of their own: a
+ * timestamp dated in the future relative to `now` lands in `Today` — the
+ * most-recent bucket available, since there's no "upcoming" bucket to put it
+ * in instead. A timestamp that fails to parse lands in `Older` instead — it
+ * carries no "this is recent" signal at all, so the oldest/catch-all bucket
+ * is the more honest home for it than the newest one.
+ */
+export function groupByRecency(items, options = {}) {
+    const getTimestamp = options.getTimestamp ?? ((item) => item);
+    const now = options.now ?? new Date();
+    const labels = { ...DEFAULT_LABELS, ...options.labels };
+    const todayStart = startOfLocalDay(now);
+    const today = [];
+    const yesterday = [];
+    const previousWeek = [];
+    const older = [];
+    for (const item of items) {
+        const raw = getTimestamp(item);
+        const date = raw instanceof Date ? raw : new Date(raw);
+        const time = date.getTime();
+        // No meaningful "how recent" signal at all -- the catch-all bucket
+        // surfaces it (so it's never silently dropped) without inventing a
+        // "day 0" that a genuinely-invalid timestamp doesn't deserve.
+        if (Number.isNaN(time)) {
+            older.push(item);
+            continue;
+        }
+        const dayDiff = Math.round((todayStart - startOfLocalDay(date)) / MS_PER_DAY);
+        if (dayDiff <= 0) {
+            // <= 0 (not === 0) also covers a timestamp dated in the future
+            // relative to `now` -- there's no "upcoming" bucket, so it reads as
+            // the most-recent bucket available rather than being dropped.
+            today.push(item);
+        }
+        else if (dayDiff === 1) {
+            yesterday.push(item);
+        }
+        else if (dayDiff <= 7) {
+            previousWeek.push(item);
+        }
+        else {
+            older.push(item);
+        }
+    }
+    const buckets = [];
+    if (today.length)
+        buckets.push({ label: labels.today, items: today });
+    if (yesterday.length)
+        buckets.push({ label: labels.yesterday, items: yesterday });
+    if (previousWeek.length)
+        buckets.push({ label: labels.previousWeek, items: previousWeek });
+    if (older.length)
+        buckets.push({ label: labels.older, items: older });
+    return buckets;
+}

package/dist/internal/numbers.d.ts

@@ -0,0 +1,12 @@
+/** The largest delay browsers can represent reliably with setTimeout. */
+export declare const MAX_TIMEOUT_MS = 2147483647;
+/** Returns a finite number or the supplied finite fallback. */
+export declare function finiteNumber(value: number, fallback: number): number;
+/** Returns a finite value clamped to the requested range. */
+export declare function finiteRange(value: number, fallback: number, min?: number, max?: number): number;
+/** Returns a finite integer, truncating fractional input and clamping it. */
+export declare function finiteInteger(value: number, fallback: number, min?: number, max?: number): number;
+/** Returns a finite, non-negative integer suitable for a count or index. */
+export declare function finiteCount(value: number, fallback?: number, max?: number): number;
+/** Returns a finite timer duration, capped at the browser timer ceiling. */
+export declare function finiteDuration(value: number, fallback: number, min?: number, max?: number): number;

package/dist/internal/numbers.js

@@ -0,0 +1,26 @@
+/** The largest delay browsers can represent reliably with setTimeout. */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+/** Returns a finite number or the supplied finite fallback. */
+export function finiteNumber(value, fallback) {
+    return Number.isFinite(value) ? value : Number.isFinite(fallback) ? fallback : 0;
+}
+/** Returns a finite value clamped to the requested range. */
+export function finiteRange(value, fallback, min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY) {
+    const safeFallback = finiteNumber(fallback, 0);
+    const safeMin = Number.isFinite(min) ? min : Number.NEGATIVE_INFINITY;
+    const safeMax = Number.isFinite(max) ? max : Number.POSITIVE_INFINITY;
+    const safeValue = finiteNumber(value, safeFallback);
+    return Math.min(safeMax, Math.max(safeMin, safeValue));
+}
+/** Returns a finite integer, truncating fractional input and clamping it. */
+export function finiteInteger(value, fallback, min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
+    return Math.trunc(finiteRange(value, fallback, min, max));
+}
+/** Returns a finite, non-negative integer suitable for a count or index. */
+export function finiteCount(value, fallback = 0, max = Number.MAX_SAFE_INTEGER) {
+    return finiteInteger(value, Math.max(0, fallback), 0, max);
+}
+/** Returns a finite timer duration, capped at the browser timer ceiling. */
+export function finiteDuration(value, fallback, min = 0, max = MAX_TIMEOUT_MS) {
+    return finiteRange(value, fallback, min, Math.min(max, MAX_TIMEOUT_MS));
+}

package/dist/internal/overlay-manager.d.ts

@@ -0,0 +1,51 @@
+export interface OverlayActivationOptions {
+    /** The custom-element host that owns this overlay. */
+    host: HTMLElement;
+    /** Resolves the current dialog/panel element after each render. */
+    panel: () => HTMLElement | null;
+    /** Dismisses the overlay with its component-specific Escape reason/event. */
+    onEscape: () => void;
+    /** Dismisses the overlay with its component-specific backdrop reason/event. */
+    onBackdrop?: () => void;
+    /** Optional component-specific initial target, such as an intentionally safe default action. */
+    preferredInitialFocus?: () => HTMLElement | null;
+    /** Override the focus-return target captured when the overlay activates. */
+    restoreFocusTo?: HTMLElement | null;
+    /** Defaults to true. Nonmodal popups share ordering without inerting the page. */
+    modal?: boolean;
+    /** Defaults to true. Set false for popups that allow native Tab to leave. */
+    trapFocus?: boolean;
+    /** Optional non-trapping Tab lifecycle, called without preventing the event. */
+    onTab?: () => void;
+}
+export interface OverlayDeactivateOptions {
+    /** Defaults to true. Explicit outside-pointer paths can suppress restoration. */
+    restoreFocus?: boolean;
+}
+export interface OverlayHandle {
+    /** Moves focus inside unless focus is already within the current panel. */
+    focusInitial(): void;
+    /** Removes the overlay permanently. Safe to call repeatedly. */
+    deactivate(options?: OverlayDeactivateOptions): void;
+    /** Temporarily unregisters during disconnect, preserving the original return target. */
+    suspend(): void;
+    /** Re-registers a suspended overlay in its current `ownerDocument`. */
+    resume(): void;
+    /** Whether this overlay currently owns Escape, Tab, and backdrop dismissal. */
+    isTopmost(): boolean;
+    /** Whether this handle still represents an active or temporarily suspended overlay. */
+    isActive(): boolean;
+    /** Runs the backdrop callback only when this overlay is topmost. */
+    dismissBackdrop(): boolean;
+}
+/** Returns the deepest focused descendant across open shadow roots. */
+export declare function deepActiveElement(doc?: Document): Element | null;
+export declare function composedContains(container: Element, candidate: Element | null): boolean;
+/** Collects rendered focus targets through slots and nested open shadow roots in browser tab order. */
+export declare function collectFocusableElements(root: Element | ShadowRoot): HTMLElement[];
+/**
+ * Adds an overlay to a stack scoped to its own `ownerDocument`. One document
+ * listener routes Escape and Tab only to the top entry, while modal inerting,
+ * visual stack depth, and focus return are recomputed as entries move.
+ */
+export declare function activateOverlay(options: OverlayActivationOptions): OverlayHandle;