@aceshooting/lyra-ui 2.0.0 → 2.1.0

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,
@@ -15,13 +16,13 @@ export function FormAssociated(Base) {
         static { this.properties = {
             name: { reflect: true, noAccessor: true },
             value: { noAccessor: true },
-            disabled: { type: Boolean, reflect: true },
+            disabled: { type: Boolean, reflect: true, noAccessor: true },
             required: { type: Boolean, reflect: true, noAccessor: true },
         }; }
         constructor(...args) {
             super(...args);
-            this.disabled = 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
@@ -42,11 +43,35 @@ export function FormAssociated(Base) {
             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;
         }
@@ -71,6 +96,17 @@ 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;
         }
@@ -107,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() {
@@ -124,6 +160,9 @@ export function FormAssociated(Base) {
             // semantics) — previously this unconditionally blanked the field.
             this.value = this._defaultValue;
         }
+        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

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;