@aceshooting/lyra-ui 27.0.0 → 28.0.0

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

@@ -20,6 +20,60 @@ only targets in the element's own or an ancestor shadow scope (sibling and desce
 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
@@ -52,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:
@@ -61,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.
@@ -87,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.
 
@@ -407,7 +489,8 @@ arrowPadding?: number; hoverBridge?: HTMLElement; onPlaced?: (result: PlacementR
   (`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.
@@ -430,7 +513,8 @@ HTMLFormElement | null; set form(owner: FormOwnerValue); readonly labels: NodeLi
 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: {