ngwr 11.0.0 → 11.2.0

package/types/ngwr-marquee-testing.d.ts

@@ -0,0 +1,280 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/** Narrows which `<wr-marquee>` a harness query matches. */
+interface WrMarqueeHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the region's accessible name — the only thing telling two strips on one page
+     * apart. A string is an exact match, a RegExp is tested.
+     *
+     * Every marquee has one: with no `[ariaLabel]` and no catalog it is the literal
+     * `'Marquee'`, so this never matches on absence.
+     */
+    readonly ariaLabel?: string | RegExp;
+}
+/** Narrows which `.wr-marquee__item` a harness query matches. */
+interface WrMarqueeItemHarnessFilters extends BaseHarnessFilters {
+    /** Match what the entry announces — see `WrMarqueeItemHarness.getAccessibleName()`. */
+    readonly name?: string | RegExp;
+    /** Match only linked (`true`) or only plain (`false`) entries. */
+    readonly link?: boolean;
+}
+/** One linked entry of the strip, as it announces itself and as it navigates. */
+interface WrMarqueeLink {
+    /** The `href` exactly as the item declared it, unresolved. */
+    readonly href: string | null;
+    /**
+     * The link's accessible name. Never `null` in practice — an entry with nothing to call
+     * itself falls back to the catalog's `marquee.link`, because a bare "link" was what a
+     * screen reader used to announce for every unlabelled logo in the strip.
+     */
+    readonly name: string | null;
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/**
+ * Test harness for one entry of a `<wr-marquee>`.
+ *
+ * **Reach these through `WrMarqueeHarness.getItems()`, which scopes them to the first
+ * copy.** The strip duplicates its whole sequence to make the loop seamless, so asking
+ * the document loader for all of these returns one per entry per copy — at least twice
+ * everything, and a count assertion that quietly multiplies. The parent harness is the
+ * only place that knows which copy is the original.
+ *
+ * An entry is built from an image or from a projected template, and it may or may not be
+ * a link. That is the reason to ask a harness rather than the DOM: the same question —
+ * what does this announce, is it decoration — is answered from a different attribute in
+ * each of those shapes, and {@link getAccessibleName} and {@link isDecorative} pick the
+ * right one.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrMarqueeItemHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrMarqueeItemHarnessFilters): HarnessPredicate<WrMarqueeItemHarness>;
+    private readonly link;
+    private readonly image;
+    private readonly node;
+    /**
+     * What this entry announces, without the caller needing to know how it was built.
+     *
+     * A linked entry answers with the link's own name, which is the end of a four-step
+     * ladder — the item's `ariaLabel`, then its `title`, then an image's `alt`, then the
+     * catalog's `marquee.link`. An unlinked image answers with its `alt`, where `''` means
+     * the logo is decoration and announces nothing. Anything else answers with its text.
+     */
+    getAccessibleName(): Promise<string | null>;
+    /** Whether this entry became a link — `[items]` carries `href` per entry, optionally. */
+    isLink(): Promise<boolean>;
+    /** The `href` exactly as the entry declared it, unresolved, or `null` when it is not a link. */
+    getHref(): Promise<string | null>;
+    /**
+     * Whether the link opens in a new tab AND says so safely: `target="_blank"` with both
+     * `noreferrer` and `noopener` in `rel`.
+     *
+     * One question rather than two, because half of it is a reverse-tabnabbing hole that
+     * nothing visual would ever show. The library hard-codes the safe pair, so this is a
+     * regression check on the template rather than on the caller's data.
+     *
+     * Throws for an entry that is not a link, where a `false` would read as "it opens in
+     * this tab" — an answer about safety that is not true of anything.
+     */
+    opensInNewTab(): Promise<boolean>;
+    /**
+     * Whether this entry's content is kept out of the accessible tree, leaving whatever
+     * wraps it to do the announcing.
+     *
+     * The marker depends on how the entry was built, which is the whole reason to ask here:
+     * a projected template inside a named link carries `aria-hidden`, so the link's own name
+     * is not read twice, while an image says the same thing with `alt=""`. It describes the
+     * CONTENT — a decorative logo inside a link is still announced, by the link, and that
+     * name is {@link getAccessibleName}.
+     *
+     * Throws for an entry that rendered neither, which should not happen — every entry of
+     * `[items]` is one or the other.
+     */
+    isDecorative(): Promise<boolean>;
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/**
+ * Test harness for `<wr-marquee>`.
+ *
+ * **Almost everything worth asserting about a marquee is structural, not animated.** The
+ * strip duplicates its sequence so the loop has no seam, and only the first copy is left
+ * in the accessible tree — {@link getAnnouncedCopyCount} is the assertion that catches
+ * the regression that matters, because a duplicate leaking in makes a screen reader read
+ * the whole logo strip twice and changes nothing on screen. The other half is the naming
+ * ladder on linked entries, which is real logic with a real bug in its history: the
+ * fallback used to be the hard-coded English word "link".
+ *
+ * **Every list query is scoped to the first copy**, and that is the reason to use
+ * {@link getItems} rather than a raw `.wr-marquee__item` query, which returns at least
+ * twice as many elements as there are entries.
+ *
+ * Nothing about the motion is offered. The track's `translate3d` is written only when the
+ * measured sequence is wider than zero, so it never appears in a test at all, and in a
+ * browser it is one frame of a loop that is already stale by the time an assertion reads
+ * it. `[speed]` and `[direction]` reach the DOM in no form. Neither does the hover state:
+ * pausing flips a private signal with no class, attribute or property behind it, so a
+ * `hover()` here would fire events that provably change nothing readable. And the
+ * reduced-motion freeze is a CSS `!important` rule with no counterpart in TypeScript,
+ * which means the DOM is identical either way — see `getGap` for what a harness can
+ * honestly read off a stylesheet-driven component, and why it reads it where it does.
+ *
+ * @example
+ * ```ts
+ * const loader = TestbedHarnessEnvironment.loader(fixture);
+ * const strip = await loader.getHarness(WrMarqueeHarness);
+ *
+ * expect(await strip.getAnnouncedCopyCount()).toBe(1);
+ * expect(await strip.getItemCount()).toBe(logos.length);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrMarqueeHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrMarqueeHarnessFilters): HarnessPredicate<WrMarqueeHarness>;
+    private readonly copies;
+    /**
+     * The name the region announces.
+     *
+     * Pins the i18n ladder end to end: `'Marquee'` with no catalog loaded, the consumer's
+     * `[ariaLabel]` when one is given, the localized string under a catalog. A landmark
+     * with no name is an axe failure, so this is what keeps the `region` legitimate rather
+     * than a decoration a screen-reader user is invited to jump to and finds unnamed.
+     */
+    getAccessibleName(): Promise<string | null>;
+    /**
+     * The landmark role the strip claims.
+     *
+     * Static in the template and one attribute away from being dropped in a refactor, which
+     * is exactly why a consumer asserting their page's landmark structure should be able to
+     * see it from here.
+     */
+    getRole(): Promise<string | null>;
+    /**
+     * How many copies of the sequence are rendered.
+     *
+     * The seamless loop is built by repeating the whole list until it covers the container,
+     * so the count is decided by measurement — which means it stays at the floor of 2 in a
+     * test with no layout, whatever the container would really be. Assert `>= 2`; the
+     * growth needs a browser.
+     */
+    getCopyCount(): Promise<number>;
+    /**
+     * How many copies are left in the accessible tree. Must be exactly 1.
+     *
+     * The one assertion here that catches a silent regression: every copy after the first
+     * carries `aria-hidden="true"`, and losing that makes a screen reader read the whole
+     * strip once per copy while the page looks unchanged.
+     *
+     * Note the first copy carries the literal `aria-hidden="false"` rather than no
+     * attribute at all, so this compares against the string `'true'` — testing the
+     * attribute for presence would count nothing at all as announced.
+     */
+    getAnnouncedCopyCount(): Promise<number>;
+    /** The entries of the first copy, in order — one per entry of `[items]`. */
+    getItems(): Promise<WrMarqueeItemHarness[]>;
+    /**
+     * How many entries the strip drew, counting the first copy only.
+     *
+     * One per entry of `[items]` — the mapping a consumer's own data pipeline is really
+     * being tested for.
+     */
+    getItemCount(): Promise<number>;
+    /**
+     * The `alt` of each image in the first copy, in order.
+     *
+     * `null` in this list is the thing to look for: it means the attribute is MISSING, which
+     * is a serious axe violation and announces the file name. An empty string is the
+     * opposite — a deliberately decorative logo — and the template's `alt || ''` is what
+     * keeps the two apart. A method typed `string[]` would have had to flatten them.
+     */
+    getImageAlts(): Promise<(string | null)[]>;
+    /**
+     * Every linked entry of the first copy: where it goes and what it announces.
+     *
+     * The name is the interesting half. It walks a ladder ending in the catalog's
+     * `marquee.link`, so an unlabelled logo announces a localized word rather than nothing
+     * — real component logic rather than an echo of the input.
+     */
+    getLinks(): Promise<WrMarqueeLink[]>;
+    /**
+     * Whether the edge fades are on.
+     *
+     * The fades themselves are `::before` / `::after` gradients, which no unit environment
+     * can see — so the modifier class is the observable, and it is public API a consumer
+     * may be styling against in any case.
+     */
+    hasFade(): Promise<boolean>;
+    /**
+     * The fade colour as the component passed it through — a CSS value such as
+     * `'var(--wr-color-success)'`, not a resolved colour — or `null` when none was given.
+     *
+     * Worth asserting next to {@link hasFade}: a colour with no fade modifier renders
+     * nothing at all, which is a consumer mistake this pairing makes visible.
+     */
+    getFadeColor(): Promise<string | null>;
+    /**
+     * Whether entries scale up under the pointer.
+     *
+     * A `:hover` transform, so again the modifier is the only honest read — and it earns
+     * its place by doing more than the name suggests: it also changes the strip's vertical
+     * padding, so a lost class shifts the layout as well as the hover.
+     */
+    hasScaleOnHover(): Promise<boolean>;
+    /** The gap between entries in pixels — the seam width the stylesheet reads. */
+    getGap(): Promise<number>;
+    /**
+     * The entry height in pixels.
+     *
+     * It drives the image height AND the entry font size, so a binding that stops arriving
+     * collapses the whole strip rather than merely resizing it.
+     */
+    getItemHeight(): Promise<number>;
+    /**
+     * Read a custom property off the host's inline `style`, rather than through
+     * `getCssValue()`.
+     *
+     * Not a jsdom workaround — the opposite. The stylesheet declares its own
+     * `--wr-marquee-gap: 32px` and `--wr-marquee-height: 28px` on `.wr-marquee`, so a
+     * computed read in a real browser answers with the stylesheet's default when the host
+     * binding is the very thing that broke. The inline value is what the component wrote,
+     * and nothing else can forge it.
+     */
+    private hostStyle;
+    /**
+     * Parse a `<n>px` custom property, refusing anything that lost its unit.
+     *
+     * The refusal is the point. `[gap]` and `[itemHeight]` are numbers that the host binding
+     * turns into lengths, and the stylesheet uses them raw — a bare `32` is an invalid
+     * declaration, so the property falls back to the stylesheet default and the strip looks
+     * merely a little different. A `parseFloat` would report 32 either way and hide it.
+     */
+    private pixels;
+}
+
+export { WrMarqueeHarness, WrMarqueeItemHarness };
+export type { WrMarqueeHarnessFilters, WrMarqueeItemHarnessFilters, WrMarqueeLink };

package/types/ngwr-meter-group-testing.d.ts

@@ -0,0 +1,67 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/** Narrows which `<wr-meter-group>` a harness query matches. */
+interface WrMeterGroupHarnessFilters extends BaseHarnessFilters {
+    /** Match the bar's accessible name. */
+    readonly ariaLabel?: string | RegExp;
+    /** Match a group whose legend holds this label. */
+    readonly sliceLabel?: string | RegExp;
+}
+/** One band of the bar, as it is drawn and titled. */
+interface WrMeterGroupSlice {
+    /** The band's `title` — its only text, since the bar itself is one `progressbar`. */
+    readonly label: string | null;
+    /** The share of the bar it takes, in percent. */
+    readonly percent: number;
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/**
+ * Test harness for `<wr-meter-group>` — one bar divided into labelled bands.
+ *
+ * **The bar is a single `progressbar`, and its value is the TOTAL.** The bands
+ * themselves announce nothing: they carry a `title` for a mouse and their share as an
+ * inline width, and the legend is where their labels and values are readable. So a
+ * spec that wants "how much of each" reads {@link getLegend} or {@link getSlices},
+ * and one that wants "how full" reads {@link getValue}.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrMeterGroupHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrMeterGroupHarnessFilters): HarnessPredicate<WrMeterGroupHarness>;
+    private readonly bar;
+    /** The role the bar announces — `progressbar`, for the total. */
+    getRole(): Promise<string | null>;
+    /** The bar's accessible name. */
+    getAccessibleName(): Promise<string | null>;
+    /** The total the bands add up to, from `aria-valuenow`. */
+    getValue(): Promise<number>;
+    /** The full capacity, from `aria-valuemax` — given, or the sum of the bands. */
+    getMax(): Promise<number>;
+    /** The bands, in order, with the share of the bar each takes. */
+    getSlices(): Promise<WrMeterGroupSlice[]>;
+    /** Whether the legend is rendered (`showLegend`, and at least one band). */
+    hasLegend(): Promise<boolean>;
+    /** The legend's labels, in order. */
+    getLegendLabels(): Promise<string[]>;
+    /** The legend's values, in order — empty when `showValues` is off. */
+    getLegendValues(): Promise<string[]>;
+}
+
+export { WrMeterGroupHarness };
+export type { WrMeterGroupHarnessFilters, WrMeterGroupSlice };

package/types/ngwr-overlay.d.ts

@@ -90,6 +90,7 @@ declare function wrMirrorOffsets(positions: readonly ConnectedPosition[], isRtl:
  *
  * Registration is per subscription: the document listeners go up with the first
  * watcher and come down with the last, so an app with no open overlay has none.
+ * That sentence was aspirational until v11 — see {@link outsidePointerEvents}.
  */
 declare class WrOutsideClick {
     private readonly doc;
@@ -100,7 +101,24 @@ declare class WrOutsideClick {
     private pressOrigin;
     /**
      * Emits every `click` / `auxclick` / `contextmenu` that lands outside the
-     * given overlay's pane, for as long as the returned observable is subscribed.
+     * given overlay's pane, for as long as the overlay is attached.
+     *
+     * **It completes when the overlay detaches, and that is load-bearing.** Every
+     * one of the ten call sites subscribes inside its own `openOverlay()` and
+     * pipes `takeUntilDestroyed(destroyRef)` — a DIRECTIVE lifetime, not an
+     * overlay one — and none of them unsubscribes on close, because the natural
+     * reading of that idiom is "this ends with the component". Without the
+     * completion below the teardown never ran: one watcher accumulated per OPEN
+     * for the life of the page, each pinning a disposed `OverlayRef` (and through
+     * it a detached pane, its portal outlet and their injectors), the four
+     * capture-phase document listeners could never come down because
+     * `watchers.length` never reached zero, and every click on the page walked a
+     * list that only grew. A `mode="tooltip"` popover made it unbounded — one
+     * permanent watcher per hover.
+     *
+     * Completing here rather than fixing ten call sites is deliberate: the next
+     * component to open an overlay would have made the same reasonable mistake.
+     * It is also what CDK's own `OverlayRef.outsidePointerEvents()` does.
      */
     outsidePointerEvents(overlayRef: OverlayRef): Observable<MouseEvent>;
     private readonly onPointerDown;

package/types/ngwr-rotating-text-testing.d.ts

@@ -0,0 +1,191 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/** Narrows which `<wr-rotating-text>` a harness query matches. */
+interface WrRotatingTextHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the string showing right now — the readable copy, not the animated pieces.
+     * A string is an exact match, a RegExp is tested.
+     *
+     * It matches a MOMENT, not a rotator: the component cycles, so a filter that hits today
+     * misses two seconds later. Use it to address the one that is currently showing a known
+     * word, and prefer `selector` for a rotator you need to hold on to.
+     */
+    readonly text?: string | RegExp;
+    /**
+     * Match on how many word groups the split produced. Word boundaries survive every
+     * granularity — three words stay three groups even when each is exploded into
+     * characters — so this is stable across the split, unlike the piece count.
+     */
+    readonly wordCount?: number;
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/**
+ * Test harness for `<wr-rotating-text>`.
+ *
+ * **What is announced and what is drawn are two questions, and this component is worth a
+ * harness mostly because it answers them separately.** The string showing now is carried
+ * verbatim in a visually-hidden span; the animated layer beside it is one span per
+ * grapheme, word or line and is `aria-hidden` as a whole, so a screen reader hears `one`
+ * rather than `o. n. e.` {@link getAccessibleText} is the first, {@link getRenderedText}
+ * and {@link getPieces} the second, and {@link isAnimatedLayerHidden} together with
+ * {@link hasAccessibleCopy} is the pairing that regresses silently when someone
+ * restructures the template — pieces hidden AND no readable copy is an element with no
+ * accessible text at all, which reads as a pass on either check alone.
+ *
+ * **The sr-only span is deliberately not a live region, and no method here implies
+ * otherwise.** `auto` advances every two seconds by default, and the APG's answer for
+ * self-advancing content is silence, not an announcement on a timer. What the harness
+ * pins is that the announced copy TRACKS the current word — nothing about it being
+ * spoken.
+ *
+ * **There is no `getIndex()`, and no `next()` / `previous()` / `jumpTo()` / `reset()`.**
+ * The index appears nowhere in the DOM — no attribute, no data hook — so deriving it
+ * would mean matching the shown string against a list the harness was never given, and
+ * guessing between duplicates. And the component renders no controls at all: rotation is
+ * a timer or a method call on the instance, so a harness "click" would have nothing to
+ * click and reaching into the component would make this a wrapper around the class rather
+ * than a reader of the DOM. Drive it from the spec — through the instance, or by
+ * advancing the interval — and assert the `nextChange` output for the index.
+ *
+ * **Nothing here reports the tween.** `duration`, `easing`, `staggerDuration` and
+ * `staggerFrom` are passed straight into Web Animation options and never written to the
+ * document; `delayFor()` is arithmetic with no rendered trace. So no `getDuration()`, no
+ * `getStagger()`, no `isAnimating()`. The pieces do carry inline `opacity` and
+ * `transform`, but on the animated path those are the FIRST keyframe — `opacity: 0` on
+ * text the user can see perfectly well — which is why the only reading offered is
+ * {@link isSettled}, and why it is spelled as a commitment rather than as a state of
+ * motion. The host's `overflow: hidden` clipping is layout, and every rect in a unit test
+ * is 0×0, so there is no `isClipped()` either.
+ *
+ * jsdom implements no Web Animations API, so the animated path throws on the first
+ * `el.animate` — before any assertion runs. Every spec supplies one half or the other:
+ *
+ * ```ts
+ * // Either: mount under reduced motion, where each swap is instant and nothing tweens.
+ * // (jsdom has no matchMedia, so WrPlatform must be provided as a value.)
+ * TestBed.configureTestingModule({ providers: [{ provide: WrPlatform, useValue: reducedMotion }] });
+ *
+ * // Or: stub the API — and remember a stub that never fires `onfinish` never resolves
+ * // the exit step, so the rotator stops after one swap.
+ * Reflect.set(Element.prototype, 'animate', () => ({ cancel: () => undefined, onfinish: null }));
+ * ```
+ *
+ * @example
+ * ```ts
+ * const rotator = await loader.getHarness(WrRotatingTextHarness);
+ *
+ * expect(await rotator.getAccessibleText()).toBe('design');
+ * expect(await rotator.getPieces()).toEqual(['d', 'e', 's', 'i', 'g', 'n']);
+ * expect(await rotator.isAnimatedLayerHidden()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrRotatingTextHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrRotatingTextHarnessFilters): HarnessPredicate<WrRotatingTextHarness>;
+    private readonly chars;
+    /**
+     * The string showing right now, as the one readable copy holds it.
+     *
+     * Literally what a screen reader gets, the animated layer being out of the tree — and
+     * the thing to assert a rotation against, since it is where `next()`, `previous()`, a
+     * clamped `jumpTo()`, `reset()`, the wrap at either end, the stop when `loop` is off and
+     * the shrinking-list clamp all become visible.
+     *
+     * Throws when the copy is missing rather than answering with the pieces' text: an empty
+     * string is what a rotator holding an empty list correctly reports, so a plausible
+     * nothing here is indistinguishable from the component having lost its accessible name
+     * entirely. Ask {@link hasAccessibleCopy} when presence is the question.
+     */
+    getAccessibleText(): Promise<string>;
+    /**
+     * Everything the animated layer draws, in document order, as one string.
+     *
+     * A different fact from {@link getAccessibleText}, and the comparison between them is
+     * the point: a split that drops its spacer renders `hellothere` while the readable copy
+     * stays perfect, and nothing else in the DOM says so.
+     *
+     * The spacer between words is a non-breaking space (`&nbsp;`), which is a rendering
+     * choice rather than a contract, so it is normalized to a plain space here — otherwise
+     * every round-trip assertion would have to spell U+00A0 out to pass against a working
+     * component. Note that `splitBy="lines"` genuinely does not round-trip: the newline the
+     * readable copy carries is drawn as that same spacer.
+     */
+    getRenderedText(): Promise<string>;
+    /**
+     * The animated pieces, in document order.
+     *
+     * The granularity actually applied: one piece per grapheme for `splitBy="characters"`,
+     * one per word for `"words"`, one per line for `"lines"`. It is also where the grapheme
+     * contract shows — `a🚀b` must come back as three pieces, not four with two broken
+     * halves of a surrogate pair.
+     */
+    getPieces(): Promise<string[]>;
+    /**
+     * How many word groups the split produced.
+     *
+     * Word boundaries survive every granularity: three words stay three groups even when
+     * each is exploded into characters, which is what keeps the line wrapping sane. A
+     * splitter that flattened the grouping would leave {@link getPieces} correct and break
+     * only this.
+     */
+    getWordCount(): Promise<number>;
+    /**
+     * Whether the animated layer is out of the accessibility tree.
+     *
+     * ONE attribute answers it — `aria-hidden` sits on the `__inner` wrapper, so the pieces
+     * inherit it and none carries it itself, which keeps the attribute off the nodes the
+     * tween writes to. Asserting it per piece would fail on a component that is behaving.
+     *
+     * If it regresses, every rotation is spelled out letter by letter beside the copy that
+     * was already read, and nothing changes on screen — so no other check catches it.
+     */
+    isAnimatedLayerHidden(): Promise<boolean>;
+    /**
+     * Whether the readable copy is rendered at all.
+     *
+     * The other half of {@link isAnimatedLayerHidden}, and it exists as a separate question
+     * because the failure the two catch together is invisible to each alone: a layer
+     * correctly hidden with no readable copy beside it is a control with no accessible text
+     * whatsoever, and `isAnimatedLayerHidden() === true` is exactly what it reports.
+     */
+    hasAccessibleCopy(): Promise<boolean>;
+    /**
+     * Whether the enter step committed its end state on every piece — NOT whether an
+     * animation finished.
+     *
+     * The component writes `opacity: 1` inline on each piece when the swap settles: instantly
+     * under reduced motion, and from the tween's `onfinish` otherwise. So this answers "the
+     * new word was actually taken over", which is the bug the deferred enter exists to
+     * prevent — a swap that animates the OLD spans leaves the new ones staged at `opacity: 0`
+     * and the text invisible, while the readable copy reports the new word correctly.
+     *
+     * It is all-or-nothing: one piece left staged is one invisible glyph in the middle of a
+     * word. On the animated path it stays `false` until each tween finishes, which in a unit
+     * test means forever, since a stubbed `Element.animate` never fires anything — that is
+     * an honest answer about a swap that never landed, not a limitation to work around.
+     *
+     * Throws when there are no pieces: "every piece is settled" is true of none of them,
+     * and that is also what a component that stopped rendering its text would report.
+     */
+    isSettled(): Promise<boolean>;
+}
+
+export { WrRotatingTextHarness };
+export type { WrRotatingTextHarnessFilters };

package/types/ngwr-select.d.ts

@@ -478,6 +478,15 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
      * Virtualization engaged: opt-in, search mode, a non-empty filtered array, and
      * NO projected `<wr-option>` children (those keep the full-render registry path
      * so their DOM-derived labels / selection still work).
+     *
+     * NOT gated on there being matches. It used to also require
+     * `filteredDynamicOptions().length > 0`, which meant a query matching nothing
+     * fell back to the full-render path and mounted the ENTIRE unfiltered array —
+     * 2000 `<wr-option>` hosts, every one of them `--hidden`, behind a "No
+     * results" line — and then tore all of them down again on the next keystroke
+     * that matched. The empty window is handled where it belongs: `virtualWindow`
+     * already short-circuits on `total === 0`, and `firstEnabled` / `lastEnabled`
+     * already answer -1.
      */
     protected readonly virtualActive: _angular_core.Signal<boolean>;
     private readonly scrollTop;
@@ -537,6 +546,7 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     protected onChipsBlur(): void;
     protected onSearchInput(event: Event): void;
     protected onSearchFocus(): void;
+    protected onSearchBlur(): void;
     protected onSearchKey(event: KeyboardEvent): void;
     /**
      * Display text for the search input. Shows the selected option's
@@ -544,6 +554,15 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
      * @internal
      */
     protected readonly searchDisplay: _angular_core.Signal<string>;
+    /**
+     * Whether the search field holds focus.
+     *
+     * Read by `searchDisplay`, so it has to be a signal — and it is also what
+     * lets the panel-close effect tell "the user walked away" (reset the query)
+     * from "the query dropped under `minChars` and they are still typing" (keep
+     * it).
+     */
+    private readonly searchHasFocus;
     private readonly host;
     private readonly overlay;
     private readonly outsideClick;
@@ -573,6 +592,19 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     protected onTriggerKey(event: KeyboardEvent): void;
     private seedActiveIndex;
     private moveActive;
+    /**
+     * Both scan `orderedRegistry`, and that is not interchangeable with
+     * `registry`.
+     *
+     * They RETURN an index, and every reader of `activeIndex` — `activeOptionId`,
+     * `moveActive`, `seedActiveIndex`, the Enter branch of `onTriggerKey` —
+     * resolves it against DOM order. Scanning creation order here produced an
+     * index into the other list: with projected `<wr-option>` children next to
+     * `[options]` rows the two differ, so opening or searching left the cursor on
+     * a row the user was not looking at, and Enter committed whatever happened to
+     * sit at that position in DOM order — a filter-hidden option, which commits
+     * nothing at all.
+     */
     private firstEnabled;
     private lastEnabled;
     /** Coerce the multi-mode value into an array (tolerates a scalar or null write). */