@aceshooting/lyra-ui 2.0.0 → 2.1.0

package/dist/components/widget/widget.js

@@ -7,47 +7,12 @@ 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, collectFocusableElements, deepActiveElement, } 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 { chevronIcon, closeIcon, expandIcon } from '../../internal/icons.js';
 import { styles } from './widget.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.
-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 — used to drop e.g. a
- * `[collapsed]` body's slotted content from the fullscreen tab order.
- * `el.offsetParent !== null` is the usual shorthand for this, but it's
- * unreliable here: it resolves `null` for an element whose nearest
- * *positioned* ancestor (fullscreen's `[part="base"] { position: fixed }`)
- * lives across a slot-projection boundary from the element itself (true for
- * every element this scans, since they're all slotted content), even though
- * the element is genuinely rendered. `checkVisibility()` (falling back to
- * `getClientRects().length` on engines without it) correctly follows
- * flattened-tree/slot assignment instead.
- */
-function isRendered(el) {
-    return el.checkVisibility ? el.checkVisibility() : el.getClientRects().length > 0;
-}
 /**
  * `<lyra-widget>` — a titled panel shell with an optional collapse toggle and
  * an optional fullscreen-expand toggle. Fullscreen promotes the same host
@@ -99,48 +64,19 @@ export class LyraWidget extends LyraElement {
             this.emit('lyra-collapse-change', this.collapsed);
         };
         this.toggleFullscreen = (e) => {
-            this.lastTrigger = e.currentTarget;
+            if (!this.fullscreen)
+                this.explicitTrigger = e.currentTarget;
             this.fullscreen = !this.fullscreen;
             this.emit('lyra-fullscreen-change', this.fullscreen);
-            if (!this.fullscreen) {
-                this.lastTrigger?.focus();
-            }
         };
-        this.onDocKeyDown = (e) => {
-            if (!this.fullscreen)
-                return;
-            if (e.key === 'Escape') {
-                e.preventDefault();
-                this.fullscreen = false;
-                this.emit('lyra-fullscreen-change', false);
-                this.lastTrigger?.focus();
-                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.onBackdropClick = () => {
+        this.dismissFullscreen = () => {
             if (!this.fullscreen)
                 return;
             this.fullscreen = false;
             this.emit('lyra-fullscreen-change', false);
-            this.lastTrigger?.focus();
+        };
+        this.onBackdropClick = () => {
+            this.overlayHandle?.dismissBackdrop();
         };
     }
     static { this.styles = [LyraElement.styles, styles]; }
@@ -150,13 +86,10 @@ export class LyraWidget extends LyraElement {
         }
         if (changed.has('fullscreen')) {
             if (this.fullscreen) {
-                this.releaseScrollLock = lockScroll();
-                document.addEventListener('keydown', this.onDocKeyDown);
+                this.activateFullscreenOverlay();
             }
             else {
-                this.releaseScrollLock?.();
-                this.releaseScrollLock = undefined;
-                document.removeEventListener('keydown', this.onDocKeyDown);
+                this.deactivateFullscreenOverlay();
             }
         }
     }
@@ -167,14 +100,23 @@ export class LyraWidget extends LyraElement {
     // because a mouse click natively focuses the button that triggered it --
     // not true for a directly-set `fullscreen` property, and not guaranteed
     // for every input method/browser even in the click case.
+    //
+    // The `collapsed` branch covers the same modal-focus-trap requirement for
+    // a second case: collapsing the body while fullscreen hides (display:none)
+    // whatever was focused inside it, which the browser resolves by silently
+    // moving focus outside the panel. The shared manager then reclaims it while
+    // preserving focus that is still on one of the visible header controls.
     updated(changed) {
         if (changed.has('fullscreen') && this.fullscreen) {
-            const first = this.getFocusableElements()[0];
-            if (first) {
-                first.focus();
-            }
-            else {
-                this.shadowRoot?.querySelector('[part="base"]')?.focus();
+            this.overlayHandle?.focusInitial();
+        }
+        else if (changed.has('collapsed') && this.fullscreen) {
+            const panel = this.shadowRoot?.querySelector('[part="base"]');
+            const active = deepActiveElement(this.ownerDocument);
+            if (panel && !collectFocusableElements(panel).includes(active)) {
+                if (active && typeof active.blur === 'function')
+                    active.blur();
+                this.overlayHandle?.focusInitial();
             }
         }
     }
@@ -183,49 +125,42 @@ export class LyraWidget extends LyraElement {
         // A reconnect (e.g. a drag-and-drop reparent that keeps this same
         // element instance) fires disconnectedCallback then connectedCallback
         // synchronously with no update in between, so willUpdate never reruns
-        // to notice `fullscreen` is still true. Restore the scroll lock/trap it
-        // dropped. `hasUpdated` excludes the initial mount, where willUpdate's
-        // first pass already establishes them from the starting property value.
-        if (this.hasUpdated && this.fullscreen && !this.releaseScrollLock) {
-            this.releaseScrollLock = lockScroll();
-            document.addEventListener('keydown', this.onDocKeyDown);
+        // to notice `fullscreen` is still true. Restore the shared overlay
+        // registration and scroll lock it dropped.
+        if (this.hasUpdated && this.fullscreen) {
+            if (this.overlayHandle?.isActive()) {
+                this.overlayHandle.resume();
+            }
+            else {
+                this.activateFullscreenOverlay();
+            }
+            if (!this.releaseScrollLock)
+                this.releaseScrollLock = lockScroll(this.ownerDocument);
+            queueMicrotask(() => this.overlayHandle?.focusInitial());
         }
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.releaseScrollLock?.();
         this.releaseScrollLock = undefined;
-        document.removeEventListener('keydown', this.onDocKeyDown);
+        this.overlayHandle?.suspend();
     }
-    // Bounds Tab/Shift+Tab to the panel while fullscreen (a modal presentation)
-    // so keyboard focus can't escape to page content hidden behind the
-    // backdrop. Order follows the header's actions slot, then the collapse/
-    // fullscreen buttons, then the body 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) : [];
-        };
-        const shadowButtons = Array.from(root.querySelectorAll('[part="collapse-button"], [part="fullscreen-button"]'));
-        return [
-            ...fromSlot('slot[name="actions"]'),
-            ...shadowButtons,
-            ...fromSlot('[part="body"] slot:not([name])'),
-        ].filter(isRendered);
+    activateFullscreenOverlay() {
+        this.releaseScrollLock ??= lockScroll(this.ownerDocument);
+        this.overlayHandle = activateOverlay({
+            host: this,
+            panel: () => this.shadowRoot?.querySelector('[part="base"]') ?? null,
+            onEscape: this.dismissFullscreen,
+            onBackdrop: this.dismissFullscreen,
+            restoreFocusTo: this.explicitTrigger,
+        });
+        this.explicitTrigger = undefined;
     }
-    getActiveElement() {
-        let active = document.activeElement;
-        while (active) {
-            const inner = active.shadowRoot?.activeElement ?? null;
-            if (!inner)
-                break;
-            active = inner;
-        }
-        return active;
+    deactivateFullscreenOverlay() {
+        this.releaseScrollLock?.();
+        this.releaseScrollLock = undefined;
+        this.overlayHandle?.deactivate();
+        this.overlayHandle = undefined;
     }
     render() {
         const hasLabel = this.label.length > 0;
@@ -261,11 +196,10 @@ export class LyraWidget extends LyraElement {
                 aria-expanded=${this.collapsed ? 'false' : 'true'}
                 aria-label=${this.collapsed ? 'Expand panel' : 'Collapse panel'}
                 aria-controls=${this.bodyId}
+                style="transform:rotate(${this.collapsed ? '0deg' : '90deg'})"
                 @click=${this.toggleCollapsed}
               >
-                <span style="display:inline-flex;transform:rotate(${this.collapsed ? '0deg' : '90deg'})"
-                  >${chevronIcon()}</span
-                >
+                ${chevronIcon()}
               </button>`
             : nothing}
           ${this.expandable

package/dist/components/widget/widget.styles.js

@@ -29,6 +29,12 @@ export const styles = css `
     flex: 1 1 auto;
     min-inline-size: 0;
   }
+  [part='label'],
+  [part='sublabel'] {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
   [part='label'] {
     font-weight: 600;
   }
@@ -80,12 +86,12 @@ export const styles = css `
     position: fixed;
     inset: var(--lyra-widget-fullscreen-inset, 0);
     background: var(--lyra-widget-overlay-color);
-    z-index: 999;
+    z-index: var(--lyra-overlay-stack-index, 1000);
   }
   :host([fullscreen]) [part='base'] {
     position: fixed;
     inset: var(--lyra-widget-fullscreen-inset);
-    z-index: 1000;
+    z-index: calc(var(--lyra-overlay-stack-index, 1000) + 1);
     box-shadow: var(--lyra-shadow);
   }
   :host([fullscreen]) [part='body'] {

package/dist/components/word-cloud/word-cloud-layout.d.ts

@@ -52,6 +52,13 @@ export interface WordCloudLayoutResult {
 }
 /** DOM-node/compute-time safety cap — mirrors lyra-sparkline's `MAX_BARS`. */
 export declare const MAX_WORDS = 150;
+/** Largest accepted font size in CSS pixels. This keeps measurement and
+ *  placement geometry finite enough for an interactive render even when a
+ *  caller supplies an otherwise-valid but impractically large number. */
+export declare const MAX_FONT_SIZE_PX = 512;
+/** Maximum number of candidate positions tested for any one word. Together
+ *  with `MAX_WORDS`, this puts a hard upper bound on spiral-search work. */
+export declare const MAX_SPIRAL_ITERATIONS = 4096;
 /** Minimum gap enforced both between placed words and around the returned bounding box. */
 export declare const GAP = 3;
 /**

package/dist/components/word-cloud/word-cloud-layout.js

@@ -1,5 +1,12 @@
 /** DOM-node/compute-time safety cap — mirrors lyra-sparkline's `MAX_BARS`. */
 export const MAX_WORDS = 150;
+/** Largest accepted font size in CSS pixels. This keeps measurement and
+ *  placement geometry finite enough for an interactive render even when a
+ *  caller supplies an otherwise-valid but impractically large number. */
+export const MAX_FONT_SIZE_PX = 512;
+/** Maximum number of candidate positions tested for any one word. Together
+ *  with `MAX_WORDS`, this puts a hard upper bound on spiral-search work. */
+export const MAX_SPIRAL_ITERATIONS = 4096;
 /** Minimum gap enforced both between placed words and around the returned bounding box. */
 export const GAP = 3;
 const ROTATE_PROBABILITY = 0.25;
@@ -13,12 +20,17 @@ const MAX_RADIUS_AREA_FACTOR = 6;
  *  `minFontSize`/`maxFontSize` input. */
 const MIN_SANE_FONT_SIZE = 1;
 /** Normalizes possibly-invalid minFontSize/maxFontSize into a finite,
- *  positive, correctly-ordered pair — non-finite/negative inputs fall back
- *  to MIN_SANE_FONT_SIZE, and a reversed pair (max < min) is swapped rather
- *  than left to invert the weight-to-size mapping. */
+ *  positive, bounded, correctly-ordered pair — non-finite/negative inputs
+ *  fall back to MIN_SANE_FONT_SIZE, huge finite values are capped, and a
+ *  reversed pair (max < min) is swapped rather than left to invert the
+ *  weight-to-size mapping. */
 function resolveFontSizeBounds(minFontSize, maxFontSize) {
-    const min = Number.isFinite(minFontSize) && minFontSize > 0 ? minFontSize : MIN_SANE_FONT_SIZE;
-    const max = Number.isFinite(maxFontSize) && maxFontSize > 0 ? maxFontSize : MIN_SANE_FONT_SIZE;
+    const min = Number.isFinite(minFontSize) && minFontSize > 0
+        ? Math.min(minFontSize, MAX_FONT_SIZE_PX)
+        : MIN_SANE_FONT_SIZE;
+    const max = Number.isFinite(maxFontSize) && maxFontSize > 0
+        ? Math.min(maxFontSize, MAX_FONT_SIZE_PX)
+        : MIN_SANE_FONT_SIZE;
     return min <= max ? [min, max] : [max, min];
 }
 /** Clamps a (possibly negative/non-finite) input weight for scale math only —
@@ -89,7 +101,9 @@ export function layoutWordCloud(words, options) {
         let x = 0;
         let y = 0;
         let foundSpot = placed.length === 0;
-        while (!foundSpot && radius < maxRadius) {
+        let iterations = 0;
+        while (!foundSpot && radius < maxRadius && iterations < MAX_SPIRAL_ITERATIONS) {
+            iterations++;
             x = radius * Math.cos(theta);
             y = radius * Math.sin(theta);
             let collides = false;

package/dist/components/word-cloud/word-cloud.d.ts

@@ -16,12 +16,19 @@ export type { WordCloudWord };
  * Instead, like `lyra-heatmap`'s cells, the whole `[part="svg"]` is one tab
  * stop with roving arrow-key focus (Home/End jump to the first/last word,
  * Enter/Space activates the focused one), a drawn `[part="focus-ring"]`, and
- * a visually-hidden `aria-live="polite"` status announcement.
+ * a visually-hidden `aria-live="polite"` status announcement. The SVG focus
+ * target carries the group role and accessible name so the semantics follow
+ * the element a keyboard user actually focuses.
  *
  * @customElement lyra-word-cloud
  * @event lyra-word-click - Fired on click, or Enter/Space on the focused word.
  * `detail: { text, weight, group }`.
- * @csspart base, svg, word, focus-ring, live-region, empty
+ * @csspart base - The word-cloud wrapper.
+ * @csspart svg - The word-cloud SVG.
+ * @csspart word - A rendered word.
+ * @csspart focus-ring - The keyboard focus ring.
+ * @csspart live-region - The visually hidden announcement region.
+ * @csspart empty - The empty-state message.
  */
 export declare class LyraWordCloud extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -43,6 +50,19 @@ export declare class LyraWordCloud extends LyraElement {
     private focusedIndex;
     /** Text of the visually-hidden `aria-live="polite"` status announcement. */
     private liveText;
+    /**
+     * Whether `role`/`aria-label` were present on the host *before* this
+     * element's own code ever wrote to them -- snapshotted once, in the very
+     * first `willUpdate()` (guarded by `hasUpdated`, which Lit only flips to
+     * `true` after that first update commits). Re-checking `hasAttribute()` on
+     * every update instead would self-poison: once this element writes its own
+     * default `aria-label` on the first render, `hasAttribute('aria-label')` is
+     * permanently `true` afterwards, which would wrongly look like an
+     * author-supplied value and freeze the label instead of refreshing it as
+     * `words` changes on later updates.
+     */
+    private authorSuppliedRole;
+    private authorSuppliedAriaLabel;
     private measureText;
     private fontFamily;
     private paletteColors;

package/dist/components/word-cloud/word-cloud.js

@@ -53,12 +53,19 @@ function warnSkippedWords(count) {
  * Instead, like `lyra-heatmap`'s cells, the whole `[part="svg"]` is one tab
  * stop with roving arrow-key focus (Home/End jump to the first/last word,
  * Enter/Space activates the focused one), a drawn `[part="focus-ring"]`, and
- * a visually-hidden `aria-live="polite"` status announcement.
+ * a visually-hidden `aria-live="polite"` status announcement. The SVG focus
+ * target carries the group role and accessible name so the semantics follow
+ * the element a keyboard user actually focuses.
  *
  * @customElement lyra-word-cloud
  * @event lyra-word-click - Fired on click, or Enter/Space on the focused word.
  * `detail: { text, weight, group }`.
- * @csspart base, svg, word, focus-ring, live-region, empty
+ * @csspart base - The word-cloud wrapper.
+ * @csspart svg - The word-cloud SVG.
+ * @csspart word - A rendered word.
+ * @csspart focus-ring - The keyboard focus ring.
+ * @csspart live-region - The visually hidden announcement region.
+ * @csspart empty - The empty-state message.
  */
 export class LyraWordCloud extends LyraElement {
     constructor() {
@@ -78,6 +85,19 @@ export class LyraWordCloud extends LyraElement {
         this.focusedIndex = null;
         /** Text of the visually-hidden `aria-live="polite"` status announcement. */
         this.liveText = '';
+        /**
+         * Whether `role`/`aria-label` were present on the host *before* this
+         * element's own code ever wrote to them -- snapshotted once, in the very
+         * first `willUpdate()` (guarded by `hasUpdated`, which Lit only flips to
+         * `true` after that first update commits). Re-checking `hasAttribute()` on
+         * every update instead would self-poison: once this element writes its own
+         * default `aria-label` on the first render, `hasAttribute('aria-label')` is
+         * permanently `true` afterwards, which would wrongly look like an
+         * author-supplied value and freeze the label instead of refreshing it as
+         * `words` changes on later updates.
+         */
+        this.authorSuppliedRole = false;
+        this.authorSuppliedAriaLabel = false;
         this.measureText = (text, fontSize) => {
             const ctx = getScratchCtx();
             if (!ctx)
@@ -152,8 +172,19 @@ export class LyraWordCloud extends LyraElement {
             changed.has('orientations')) {
             this.relayout();
         }
-        this.setAttribute('role', 'group');
-        this.setAttribute('aria-label', `Word cloud of ${this.cachedLayout.placed.length} word${this.cachedLayout.placed.length === 1 ? '' : 's'}`);
+        if (!this.hasUpdated) {
+            this.authorSuppliedRole = this.hasAttribute('role');
+            this.authorSuppliedAriaLabel = this.hasAttribute('aria-label');
+        }
+        // Only default role/aria-label when the author hasn't already supplied
+        // one -- unconditionally overwriting them on every update (including
+        // ones triggered purely by a `words` re-layout) would silently clobber a
+        // host's own accessible name/role on the very next data refresh.
+        if (!this.authorSuppliedRole)
+            this.setAttribute('role', 'group');
+        if (!this.authorSuppliedAriaLabel) {
+            this.setAttribute('aria-label', `Word cloud of ${this.cachedLayout.placed.length} word${this.cachedLayout.placed.length === 1 ? '' : 's'}`);
+        }
     }
     relayout() {
         this.cachedLayout = layoutWordCloud(this.words, {
@@ -217,7 +248,15 @@ export class LyraWordCloud extends LyraElement {
         const ring = focused ? this.focusRingRect(focused) : undefined;
         return html `
       <div part="base">
-        <svg part="svg" tabindex="0" viewBox="0 0 ${layout.width} ${layout.height}" @keydown=${this.onKeyDown}>
+        <svg
+          part="svg"
+          role="group"
+          aria-label=${this.getAttribute('aria-label') ?? nothing}
+          aria-describedby="live-region"
+          tabindex="0"
+          viewBox="0 0 ${layout.width} ${layout.height}"
+          @keydown=${this.onKeyDown}
+        >
           ${layout.placed.map((w) => svg `<text
               part="word"
               x=${w.x}
@@ -231,7 +270,7 @@ export class LyraWordCloud extends LyraElement {
             ? svg `<rect part="focus-ring" x=${ring.x} y=${ring.y} width=${ring.width} height=${ring.height}></rect>`
             : ''}
         </svg>
-        <div part="live-region" class="sr-only" role="status" aria-live="polite">${this.liveText}</div>
+        <div id="live-region" part="live-region" class="sr-only" role="status" aria-live="polite">${this.liveText}</div>
       </div>
     `;
     }

package/dist/components/word-cloud/word-cloud.styles.js

@@ -16,6 +16,18 @@ export const styles = css `
     --lyra-word-cloud-color-7: #0a7d91;
     --lyra-word-cloud-color-8: #57606a;
   }
+  @media (prefers-color-scheme: dark) {
+    :host {
+      --lyra-word-cloud-color-1: var(--wa-color-brand-fill-loud, #4ea0f0);
+      --lyra-word-cloud-color-2: var(--wa-color-success-fill-loud, #3fb950);
+      --lyra-word-cloud-color-3: var(--wa-color-warning-fill-loud, #d29922);
+      --lyra-word-cloud-color-4: var(--wa-color-danger-fill-loud, #fa524a);
+      --lyra-word-cloud-color-5: #b083f5;
+      --lyra-word-cloud-color-6: #f470b8;
+      --lyra-word-cloud-color-7: #52d6e8;
+      --lyra-word-cloud-color-8: #c9d1d9;
+    }
+  }
   [part='base'] {
     display: flex;
     flex-direction: column;
@@ -46,7 +58,7 @@ export const styles = css `
   [part='focus-ring'] {
     fill: none;
     stroke: var(--lyra-focus-ring-color);
-    stroke-width: 2px;
+    stroke-width: var(--lyra-focus-ring-width);
     pointer-events: none;
   }
   [part='empty'] {

package/dist/internal/anchored-validity.d.ts

@@ -0,0 +1 @@
+export {};

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/form-associated.d.ts

@@ -8,9 +8,16 @@ export interface FormAssociatedInterface {
     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