@aceshooting/lyra-ui 26.0.0 → 28.0.0

package/llms/shared/testing-and-utilities.md

@@ -10,6 +10,70 @@ that need form-value or validity behavior: it supplies
 `form`/`labels`/`validity`/`validationMessage`/`willValidate`. The shim is a no-op where the
 platform already provides internals, so it is safe in a shared setup file.
 
+`installHappyDomShims()` installs that shim plus two more Happy DOM gap fixes, each a no-op where
+the engine already behaves (feature-detected, so safe in a shared setup file and never part of a
+production bundle): `installHappyDomShadowFocusShim()` makes `ShadowRoot.activeElement` return
+`null` for a sibling or detached shadow root instead of throwing a `TypeError` (own-root and
+nested-root focus are unchanged; it returns a function that restores the original descriptor), and `installHappyDomAriaControlsShim()` adds `Element.ariaControlsElements` only
+when absent. Setting it stores the references and writes an empty `aria-controls`; reading returns
+only targets in the element's own or an ancestor shadow scope (sibling and descendant shadow
+targets are dropped); `null` clears it and removes the attribute; a changed `aria-controls`
+attribute resolves ids in the element's own root instead.
+
+`installHappyDomShims()` also calls `installHappyDomCascadeLayerShim()`. Happy DOM 20 drops every
+rule inside an `@layer` block from its CSSOM, while `CSS.supports('at-rule(@layer)')` still reports
+support. Lyra's stylesheets declare their probe properties (`--_lr-style-resolver`, the
+`--_lr-*-installed` markers, the token-layer sentinel) inside cascade layers, so under Happy DOM
+`theme.css` looked absent: `setLyraStyle()` warned that a stylesheet was missing and took its
+no-stylesheet fallback. The shim passes the text that `CSSStyleSheet.replaceSync()`/`replace()`
+parse (the path used by `<style>`, `<link rel="stylesheet">` and constructed sheets) through the
+exported `flattenCascadeLayers(css)`. That function drops `@layer a, b;` statements and unwraps
+each layer block in place, leaving comments, strings, `url(...)` and `@import … layer(x)` as they
+are. The probes then resolve as they do in a browser. Layer precedence is not modelled: the
+unwrapped rules cascade in source order, so assert behaviour, not values that depend on which layer
+wins. `insertRule()` is unchanged. The shim detects the defect by parsing a layered rule, so it is
+a no-op in every browser and without a `CSSStyleSheet` global; it installs once and returns a
+function that restores the original methods. Install it before any stylesheet is parsed (in the
+same `setupFiles` entry): a sheet parsed earlier keeps the rules it dropped.
+
+### jsdom: `installJsdomShims()`
+
+jsdom implements no `adoptedStyleSheets`, so Lit renders one `<style>` element per component
+shadow root. jsdom registers each of those sheets on the document, not the shadow root, and every
+`getComputedStyle()` call then matches the element against every rule of every sheet. With a few
+hundred Lyra elements on the page a single computed-style read can take over 100 ms, and Lyra
+reads computed style to decide which slotted text is visible, so whole tests slow to a crawl.
+
+`installJsdomShims()` installs the two jsdom shims. `installJsdomAdoptedStyleSheetsShim()` adds an inert
+`adoptedStyleSheets` to `Document` and `ShadowRoot`, so Lit adopts each component's constructed
+stylesheet instead of appending `<style>` elements. Adopted sheets are stored and read back (the
+same array until reassigned, so `push()` persists) but never applied; jsdom could not cascade them
+per shadow root anyway. `getComputedStyle()` then sees only the document's own sheets and inline
+styles, so assert behaviour and DOM rather than component styling. A jsdom release without
+`CSSStyleSheet.prototype.replace()`/`replaceSync()`, which Lit also requires, gets inert versions
+that record the text. The shim installs only when `navigator.userAgent` carries jsdom's
+`jsdom/<version>` signature and `adoptedStyleSheets` is missing, so it is a no-op in browsers,
+under Happy DOM and in plain Node projects. It installs once and returns a function that removes
+what it added.
+
+jsdom's `ElementInternals` has no form association, so every Lyra form control (`lr-button`,
+`lr-input`, `lr-checkbox`, …) throws in its constructor there. `installJsdomFormAssociatedShim()`
+adds, only where missing, an inert `setFormValue()`, a `setValidity()` that `validity`,
+`validationMessage`, `checkValidity()` and `reportValidity()` reflect, `willValidate`, `form` (the
+host's closest `<form>`) and a `Set` for `states`. Nothing is submitted and no `invalid` event
+fires. It has the same jsdom detection, install-once and restore behaviour.
+
+Lit decides whether it can adopt stylesheets when its module is first evaluated, so call the shim
+in a `setupFiles` entry before anything imports Lit or a Lyra component. Importing
+`@aceshooting/lyra-ui/testing` does not load Lit:
+
+```ts
+// vitest.setup.ts (environment: 'jsdom')
+import { installJsdomShims } from '@aceshooting/lyra-ui/testing';
+
+installJsdomShims();
+```
+
 ## Constructing a validated test event: `createLyraEvent()`
 
 `@aceshooting/lyra-ui/testing` also exports
@@ -42,8 +106,9 @@ semantics of their own that this factory does not model.
 
 ## Driving a component's real activation path: interaction drivers
 
-For the exact gap `createLyraEvent()` leaves open — choosing an option, submitting a confirm
-decision, toggling a switch, activating a step — `@aceshooting/lyra-ui/testing` exports a small
+For the exact gap `createLyraEvent()` leaves open — choosing an option, a swatch or a currency,
+submitting a confirm decision, toggling a switch, activating a step, opening and closing a
+popover — `@aceshooting/lyra-ui/testing` exports a small
 set of typed interaction drivers, one per interaction, that go through the real component's own
 activation path (its own shadow-part lookup and `.click()`, the same as its own tests) instead of
 a downstream suite reverse-engineering internal detail shapes or shadow-part selectors itself:
@@ -51,17 +116,43 @@ a downstream suite reverse-engineering internal detail shapes or shadow-part sel
 ```ts
 import {
   chooseOption,
+  chooseSwatch,
+  chooseCurrency,
+  openPopover,
+  closePopover,
   submitConfirmDecision,
   toggleSwitch,
   activateStep,
 } from '@aceshooting/lyra-ui/testing';
 
 await chooseOption(combobox, 'banana'); // opens the listbox, clicks the matching [part="option"] row
+await chooseSwatch(swatchPicker, 'ruby'); // clicks the matching swatch radio
+await chooseCurrency(currencyPicker, 'EUR'); // opens the composed listbox, clicks the EUR option
+await openPopover(popover); // clicks the slotted (or `for`) trigger, waits for lr-after-show
+await closePopover(popover); // presses Escape, waits for lr-after-hide; { via: 'trigger' } clicks instead
 await submitConfirmDecision(confirmBar, 'approved'); // clicks [part="approve-button"]
 await toggleSwitch(switchEl); // calls switchEl.click(), lr-switch's own activation path
 await activateStep(stepper, 'review'); // clicks the [part="step"] button for that stepId (or pass an index)
 ```
 
+`chooseSwatch(picker, value)` clicks the `<lr-swatch-picker>` radio whose value matches (the first
+enabled one when values repeat). When it resolves, `lr-change` (only if the selection moved) and
+`lr-activate` have fired. `chooseCurrency(picker, code)` drives the select, or the lazily loaded
+combobox of a `searchable` picker, that `<lr-currency-picker>` composes. The code must match the
+catalog exactly (`"EUR"`). When it resolves, the picker has emitted `input`, `lr-input`, `change`
+and `lr-change` once if the value changed.
+
+`openPopover(popover, { timeoutMs? })` clicks the `<lr-popover>` interaction trigger (the slotted
+`trigger` element, else its `for` target) and resolves after `lr-show` and `lr-after-show`. A
+`hover`/`focus` popover opens and pins, as for a user's click. `closePopover(popover, { via?,
+timeoutMs? })` presses Escape on the focused element by default, which closes the topmost overlay,
+or clicks the trigger again with `via: 'trigger'`. It resolves after `lr-hide` and `lr-after-hide`,
+with focus back on the trigger. Both resolve at once when the popover is already in the requested
+state. They throw when the interaction is refused: an `lr-show`/`lr-hide` veto, a disabled popover
+or trigger, `trigger="manual"`, no trigger, or Escape going to a newer overlay. Use `show()`/`hide()`
+for manual and `showAt()` popovers. A missing `lr-after-*` event rejects after `timeoutMs`
+(default 2000).
+
 `chooseOption()` accepts any of `<lr-combobox>`, `<lr-select>`, `<lr-model-select>`,
 `<lr-locale-picker>` and `<lr-voice-picker>` — every component that independently implements the
 same `[part="option"]` row plus `data-value` delegated-click pattern for its own listbox/popup.
@@ -77,13 +168,14 @@ immediately after it see the render reached by that interaction. Host-driven asy
 still need their own completion check. Each driver also throws a plain `Error` — never a
 silent no-op — when the requested interaction cannot actually happen: the target is disabled, the
 option owner/stepper is read-only or has no matching row/step currently rendered, or the confirm
-bar is already decided. That is the exact failure mode a hand-rolled event misses (for example
+bar is already decided, or a popover's lifecycle event was vetoed. That is the exact failure mode a hand-rolled event misses (for example
 dispatching a confirm event without `cancelable`, which makes a `preventDefault()`-based
 pending-state handler a silent no-op that still looks tested) — these drivers exercise the
 component for real, so a precondition that blocks the interaction is surfaced as a thrown error
 instead of quietly doing nothing.
 
-Pure DOM operations only (`Element.click()`, shadow-part queries, public properties) — no
+Pure DOM operations only (`Element.click()`, an Escape `KeyboardEvent`, shadow-part queries,
+public properties) — no
 `@web/test-runner`/CDP-only helper, so they also run under a downstream suite's own
 happy-dom/jsdom environment, not only a real browser.
 
@@ -136,47 +228,28 @@ a local island around the call site.
 
 ## happy-dom's custom-property resolver and host-to-part token forwarding
 
-In 16.0.0, seven built-in controls that each compose a real
-`<lr-icon-button>` for their icon-only action — `<lr-copy-button>`, `<lr-dialog>` (whose close
-button is inherited by `<lr-drawer>`), `<lr-reorder-item>`, `<lr-message-actions>`,
-`<lr-attachment-trigger>`, `<lr-code-block>` (shared by `<lr-code-block-core>`), and `<lr-callout>`
-— captured the composed control's public `--lr-icon-button-*` tokens on their own `:host` and
-forwarded that private token back onto the SAME public token name on the `[part]` rendering the
-composed control, so that an ancestor theme override still reached the composed child instead of
-being shadowed by the component's own default. That was legal under the CSS Custom Properties spec
-— `:host` and `[part]` resolve on different elements, so a real browser resolves the host
-declaration to a concrete value first and the part substitutes that, and per-element cycle detection
-never fired — but **happy-dom does not model that element boundary**. Its `CSSComputedStyle` merges
-ancestor and own-element custom properties into a single flat map with no notion of which element
-declared what, and (at least through 20.14.5, the newest release at time of writing)
-`CSSVariableFormatter.resolveVariables` substitutes into that map recursively with no visited set
-and no depth cap — so the capture-and-forward pair resolved into each other forever, throwing an
-unhandled `RangeError: Maximum call stack size exceeded` from `CSSVariableFormatter.resolveVariables`
-on every render of any of the seven components. Every test still reported as passing — there was no
-failing assertion to point at — but the runner counted the unhandled errors and exited non-zero
-anyway, which read as unrelated flakiness rather than a CSS issue.
-
-**Current versions are unaffected.** `<lr-icon-button>` now carries a private
-`--_lr-icon-button-<token>-default` fallback tier for every paint token (background, color, border,
-and their hover/active variants — the same shape its corner radius already used via
-`--_lr-icon-button-radius-default`), and each composing component sets its own default directly on
-that private tier rather than re-declaring the public token name. `<lr-icon-button>`'s own
-stylesheet still checks the public token first, so an ancestor override reaches a composed control
-exactly as before, but no descendant declares a public `--lr-icon-button-*` token from a private
-token that was itself derived from that same public token — so no resolver, scoped or flattened,
-ever sees a cycle. A project still hitting the `RangeError` above should upgrade
-`@aceshooting/lyra-ui`; the workarounds that version range needed (patching or upgrading the DOM
-implementation to cycle-aware/depth-limited custom-property resolution, or running the affected
-suites against a real browser engine) are no longer necessary once it does.
+happy-dom merges ancestor and own-element custom properties into one flat map and resolves
+`var()` recursively with no visited set or depth cap, so a `:host` token captured from a public
+token and forwarded back onto that same public name on a `[part]` recurses forever
+(`RangeError: Maximum call stack size exceeded` from `CSSVariableFormatter.resolveVariables`).
+Real browsers resolve host and part on separate elements and never cycle. Tests can pass while
+the unhandled errors still make the runner exit non-zero.
+
+Current versions are unaffected: composing components set their defaults on
+`<lr-icon-button>`'s private `--_lr-icon-button-<token>-default` tier, and `<lr-icon-button>` still
+checks the public token first, so an ancestor override reaches a composed control. A project
+still hitting the `RangeError` should upgrade `@aceshooting/lyra-ui`; no resolver patch or
+real-browser fallback is needed.
 
 ## Editor and tooling integration
 
-The published package ships machine-readable metadata for editors:
-`custom-elements.json` (Custom Elements Manifest), `web-types.json` (JetBrains, zero-config), and
-`vscode-html-data.json` / `vscode-css-data.json` (point `html.customData` / `css.customData` at them
-in `.vscode/settings.json`). For an agent, `llms/components/<tag>.md` is the cheaper source; these
+The companion package `@aceshooting/lyra-ide` (not `@aceshooting/lyra-ui`) ships machine-readable
+metadata for editors: `custom-elements.json` (Custom Elements Manifest), `web-types.json`
+(JetBrains, zero-config), and `vscode-html-data.json` / `vscode-css-data.json` (point
+`html.customData` / `css.customData` at `./node_modules/@aceshooting/lyra-ide/...` in
+`.vscode/settings.json`). For an agent, `llms/components/<tag>.md` is the cheaper source; these
 files matter when scaffolding a project's editor configuration. Build tools can import the manifest
-through the explicit `@aceshooting/lyra-ui/custom-elements.json` package export; native Node ESM
+through the explicit `@aceshooting/lyra-ide/custom-elements.json` package export; native Node ESM
 uses `with { type: 'json' }` on that import.
 
 **Inherited members in `custom-elements.json`.** A subclass declaration's `cssParts` array is
@@ -413,10 +486,11 @@ arrowPadding?: number; hoverBridge?: HTMLElement; onPlaced?: (result: PlacementR
   `FormValueAdapter<T>` has readonly `empty`, required `toFormValue(value)`, and optional
   `toFormState(value)`, `isEmpty(value)`, `fromAttribute(attribute)`, `toAttribute(value)`, and
   `fromFormState(state)`. `FormAssociatedInterface<T>` exposes `internals`; the `name` getter/setter
-  (`next`); `value`; `defaultValue`; `customError`; `disabled`; `required`; readonly
+  (`next`); the `value` getter/setter (`next`); `defaultValue`; `customError`; `disabled`; `required`; readonly
   `effectiveDisabled`; the `form` getter/setter (`owner`); readonly `labels`, `validity`,
   `validationMessage`, and `willValidate`; `setFormValue(next)`; `getForm()`; `checkValidity()`;
-  `reportValidity()`; `setCustomValidity(message)`; `resetValidity()`; `formResetCallback()`; and
+  `reportValidity()`; `setCustomValidity(message)`; `resetValidity()`; `formResetCallback()`;
+  `formDisabledCallback(disabled)`; and
   `formStateRestoreCallback(state, reason)`.
   Writing `null` to `defaultValue` removes its markup value and resets the default to the adapter's
   empty value; reading it still returns `TValue`. This does not overwrite a dirty live value.
@@ -432,18 +506,25 @@ toFormValue(value: TValue): FormSubmissionValue; toFormState?(value: TValue):
 FormSubmissionValue; isEmpty?(value: TValue): boolean; fromAttribute?(attribute: string): TValue;
 toAttribute?(value: TValue): string | null; fromFormState?(state: FormSubmissionValue): TValue }`
   and `FormAssociatedInterface<TValue> { internals: ElementInternals; get name(): string; set
-name(next: string | null); value: TValue; get defaultValue(): TValue;
+name(next: string | null); get value(): TValue; set value(next: TValue | null); get defaultValue(): TValue;
 set defaultValue(next: TValue | null); customError: string | null;
 disabled: boolean; required: boolean; readonly effectiveDisabled: boolean; get form():
 HTMLFormElement | null; set form(owner: FormOwnerValue); readonly labels: NodeList; readonly
 validity: ValidityState; readonly validationMessage: string; readonly willValidate: boolean;
 setFormValue(next: TValue): void; getForm(): HTMLFormElement | null; checkValidity(): boolean;
 reportValidity(): boolean; setCustomValidity(message: string): void; resetValidity(): void;
-formResetCallback(): void; formStateRestoreCallback(state: FormSubmissionValue, reason:
+formResetCallback(): void; formDisabledCallback(disabled: boolean): void;
+formStateRestoreCallback(state: FormSubmissionValue, reason:
 'autocomplete' | 'restore'): void }`. The exported subclass seam is
   `FormAssociatedSubclassInterface<TValue> { protected captureLiveValueCheckpoint(): { readonly
 value: TValue; readonly dirty: boolean }; protected restoreLiveValueCheckpoint(checkpoint: {
-readonly value: TValue; readonly dirty: boolean }): void }`.
+readonly value: TValue; readonly dirty: boolean }): void; protected commitFormValue(value: TValue):
+void; protected isMissingValue(): boolean }`.
+  `CheckedFormAssociated(Base)` is the checkbox-, switch- and radio-shaped variant of that mixin: the
+  string `value` (default `'on'`) is submitted only while `checked`, `checked` has native
+  dirty/default semantics, reset and state restore round-trip it, and `required` means "must be
+  checked". It adds `CheckedFormAssociatedInterface { checked: boolean; get defaultChecked():
+boolean; set defaultChecked(next: boolean) }`.
 - **`group-by-recency` → `groupByRecency(items, options?)`** — buckets dated items into
   Today / Yesterday / Previous 7 Days / Older, on **local calendar-day boundaries** ("yesterday" is
   the previous calendar date, not 24–48 hours ago). Plain data in, plain data out — no DOM.
@@ -625,7 +706,10 @@ animationName: string, options?: LyraGetAnimationOptions): LyraResolvedElementAn
   `lockScroll`.
   `OverlayActivationOptions` exposes `host`, `panel`, optional `modalRoot`, `auxiliaryRoots`, `modal`, `lockScroll`,
   `suspendWhenUnrendered`, `onEscape`, `onBackdrop`, `preferredInitialFocus`,
-  `beforeInitialFocus`, `restoreFocusTo`, `trapFocus`, and `onTab`. `OverlayHandle` exposes
+  `beforeInitialFocus`, `restoreFocusTo`, `trapFocus`, `onTab`, and `deferredReturn` (resolved after
+  the synchronous focus return of a restoring close: a deferred pass for a target the host only
+  re-shows afterward, or `undefined` to skip it; every activation and deactivation abandons a pass
+  still pending for the host). `OverlayHandle` exposes
   `focusInitial()`, `focusAutofocus()`, `updateRestoreFocusTo(target)`,
   `deactivate({ restoreFocus?, deferScrollLockRelease? }?)`, `suspend()`, `resume()`, `isTopmost()`,
   `isActive()`, and `dismissBackdrop()`; the deactivate argument is the exported
@@ -640,7 +724,8 @@ animationName: string, options?: LyraGetAnimationOptions): LyraResolvedElementAn
 null; modalRoot?: () => HTMLElement | null; auxiliaryRoots?: () => readonly HTMLElement[]; onEscape: () => void; onBackdrop?: () => void;
 preferredInitialFocus?: () => HTMLElement | null; beforeInitialFocus?: () => boolean;
 restoreFocusTo?: OverlayRestoreFocusTarget; modal?: boolean; trapFocus?: boolean; onTab?: () =>
-void; suspendWhenUnrendered?: boolean; lockScroll?: boolean }`, `OverlayDeactivateOptions {
+void; suspendWhenUnrendered?: boolean; lockScroll?: boolean; deferredReturn?: () =>
+DeferredFocusReturnPass | undefined }`, `OverlayDeactivateOptions {
 restoreFocus?: boolean; deferScrollLockRelease?: boolean }`, and `OverlayHandle { focusInitial():
 void; focusAutofocus(): boolean; updateRestoreFocusTo(target: OverlayRestoreFocusTarget): void;
 deactivate(options?: OverlayDeactivateOptions): (() => void) | undefined; suspend(): void;
@@ -708,7 +793,7 @@ number; clearTimeout(handle: number): void }`.
 
   ```ts
   import { bridgeLyraLocale, setLyraLocale } from "@aceshooting/lyra-ui/localization.js";
-  import "@aceshooting/lyra-ui/translations/ar.js";
+  import "@aceshooting/lyra-translations/ar.js";
 
   const stop = bridgeLyraLocale(); // mirrors onto <html>
   setLyraLocale("ar"); // <html lang="ar" dir="rtl">