ngwr 11.1.0 → 11.2.0

package/skills/ngwr/references/setup.md

@@ -0,0 +1,73 @@
+# Setting up ngwr
+
+## Install
+
+```bash
+ng add ngwr
+```
+
+Prompts for styles, date adapter, density and theme, installs the peers, and
+prints a bootstrap snippet tailored to the answers.
+
+## Bootstrap
+
+```ts
+import { provideWrTheme } from 'ngwr/theme';
+import { provideWrOverlay } from 'ngwr/overlay';
+import { provideWrIcons } from 'ngwr/icon';
+import { lucideIcons } from 'ngwr/icon/adapters/lucide';
+
+bootstrapApplication(App, {
+  providers: [
+    provideZonelessChangeDetection(),
+    provideWrTheme(),
+    provideWrOverlay(),
+    provideWrIcons(lucideIcons({ check, chevronDown })),
+  ],
+});
+```
+
+`provideWrOverlay()` gives ngwr its OWN CDK overlay container, which is what
+keeps it from colliding with Material or NG-ZORRO in the same app. It also
+installs `WrVisualViewport`, which publishes `--wr-keyboard-inset`.
+
+## Styles
+
+```scss
+@use 'ngwr';          // everything
+@use 'ngwr/button';   // or one entry point at a time
+```
+
+Resolved through the `sass` condition in the package's `exports` map. Entry
+points that ship no stylesheet (the `/testing` harnesses, `ngwr/utils`) have no
+`@use` target — importing one fails the build.
+
+## Providers with no default
+
+### `provideWrOverlay() // from 'ngwr/overlay'`
+
+Overlays render into an ngwr-owned container; without it they never appear. Needed by `WrDialog`, `WrDrawer`, `WrToast`, `WrPopover`, `WrPopconfirm`, `WrContextMenu`, `WrSelect`, `WrDropdown`, `WrCommandPalette`, `WrCascader`, `WrMention`, `WrDatePicker`, `WrTour`, `WrLightbox`.
+
+### `provideWrIcons(lucideIcons({ … })) // from 'ngwr/icon' + 'ngwr/icon/adapters/lucide'`
+
+Icons resolve by name from a registry you populate. Needed by `WrIcon`.
+
+### `provideWrDateAdapter(wrDateFnsAdapter) // from 'ngwr/date-adapter-fns'`
+
+Every date mode goes through an adapter; there is no built-in default. Needed by `WrDatePicker`, `WrCalendar`, `WrEventCalendar`.
+
+### `provideWrI18n() + provideWrI18nStaticLoader({ en: wrEn }) // from 'ngwr/i18n'`
+
+The pipe and directive read from a catalog you provide. Needed by `WrT`, `WrI18n`.
+
+## Optional, app-wide
+
+- `provideWrConfig({ button: { size: 'sm' } })` — component defaults. A bound
+  value always wins, including a bound `false` over a configured `true`.
+- `provideWrDensity('sm' | 'md' | 'lg' | 'touch')` — one control size for the
+  whole app; `touch` enlarges every hit area at once.
+- `provideWrResponsiveOverlays()` — overlays present as bottom sheets under the
+  breakpoint (640px by default). Per-component opt-out with `[responsive]="false"`.
+- `provideWrFormErrors({ … })` — one place for validation copy; `<wr-form-field>`
+  resolves a message per error key through it, then the i18n catalog, then a
+  built-in fallback.

package/types/ngwr-action-sheet-testing.d.ts

@@ -0,0 +1,260 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+import { WrActionSheetAction } from 'ngwr/action-sheet';
+
+/**
+ * @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 open `<wr-action-sheet>` a harness query matches. */
+interface WrActionSheetHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the sheet's VISIBLE heading — a string is an exact match, a RegExp is
+     * tested. A sheet with no `title` has none and matches nothing here; filter on
+     * `accessibleName` to reach one by the name it announces instead.
+     */
+    readonly title?: string | RegExp;
+    /** Match the muted sub-heading under the title. */
+    readonly message?: string | RegExp;
+    /**
+     * Match the name the dialog announces — the visible title when there is one, and
+     * otherwise the screen-reader-only fallback, which is the only name an untitled
+     * sheet has.
+     */
+    readonly accessibleName?: string | RegExp;
+}
+/** Narrows which row inside an action sheet a harness query matches. */
+interface WrActionSheetActionHarnessFilters extends BaseHarnessFilters {
+    /** Match the row's label — a string is an exact match, a RegExp is tested. */
+    readonly label?: string | RegExp;
+    /**
+     * Match the row's visual role. `default` covers every row the caller left
+     * unroled, which is what the component itself does with the value.
+     */
+    readonly role?: NonNullable<WrActionSheetAction['role']>;
+    /** Match only enabled (`false`) or only disabled (`true`) rows. */
+    readonly disabled?: 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 one row inside a {@link WrActionSheetHarness}.
+ *
+ * A row is a real `<button>`, not an ARIA-decorated div, so `disabled` is the
+ * property rather than an attribute and the CDK refuses to click it — which is the
+ * behaviour a spec wants asserted, since the component ALSO checks `disabled`
+ * inside its own handler. Either guard alone would keep a disabled row inert; both
+ * being there means removing one is invisible until the other is removed too, and
+ * {@link click} is where that shows up.
+ *
+ * **Clicking a row closes the sheet.** The component emits `action` and clears
+ * `open` in the same call, so a harness held across a {@link click} is pointed at a
+ * detached element the moment it returns — read what you need first, and get a
+ * fresh harness afterwards if the sheet was reopened.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrActionSheetActionHarness extends ComponentHarness {
+    /** The class every row carries, cancel rows included. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrActionSheetActionHarnessFilters): HarnessPredicate<WrActionSheetActionHarness>;
+    /**
+     * The row's label, trimmed.
+     *
+     * Read from `.wr-action-sheet__label` rather than from the button, so a leading
+     * icon can never join it. The icon contributes no text today — it is an `<svg>` —
+     * but an icon set that ships a `<title>` for its own accessibility would, and the
+     * label element is the thing that actually holds the string.
+     */
+    getLabel(): Promise<string>;
+    /**
+     * The row's visual role, as the component painted it.
+     *
+     * `default` is returned for a row the caller left unroled, which is what the
+     * component does with the value: only `destructive` and `cancel` change anything,
+     * and everything else falls through to the plain row. The two modifiers are
+     * mutually exclusive by construction — `cancel` rows are filtered into their own
+     * group before the destructive class is ever considered — so reading them in
+     * either order gives the same answer.
+     */
+    getRole(): Promise<NonNullable<WrActionSheetAction['role']>>;
+    /**
+     * Whether the row refuses interaction, from the button's own `disabled` property
+     * — the thing the CDK consults before dispatching a click, and the DOM before
+     * delivering one.
+     *
+     * There is no `aria-disabled` to fall back to here, and none is wanted: the row is
+     * a native button, where the property already carries the state to assistive tech.
+     */
+    isDisabled(): Promise<boolean>;
+    /** Whether the row draws a leading icon. */
+    hasIcon(): Promise<boolean>;
+    /**
+     * The icon's registered name, or `null` on a row without one.
+     *
+     * From `wr-icon`'s reflected `data-icon`, which is the only place the name reaches
+     * the DOM — the rendered `<svg>` carries no trace of which entry of the set it
+     * came from.
+     */
+    getIconName(): Promise<string | null>;
+    /**
+     * Pick this row — emitting `action` and closing the sheet.
+     *
+     * Throws on a disabled row instead of quietly doing nothing. The click would not
+     * land anyway (the DOM swallows it), so the alternative is a spec that reads as
+     * "picked the row" and asserts a sheet that never moved.
+     */
+    click(): Promise<void>;
+    /** Move keyboard focus to the row. */
+    focus(): Promise<void>;
+    /** Whether the row currently holds focus. */
+    isFocused(): 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 an open `<wr-action-sheet>` — the iOS-style bottom sheet of
+ * choices.
+ *
+ * The sheet renders through `<wr-drawer>`, so its rows are in the NGWR overlay
+ * container rather than in the fixture: load this from
+ * `TestbedHarnessEnvironment.documentRootLoader()`. A fixture-scoped loader finds
+ * nothing at all — the `<wr-action-sheet>` host element itself holds no content and
+ * the drawer it wraps is `display: none`.
+ *
+ * The anchor is `.wr-action-sheet`, the sheet's own root inside the drawer panel,
+ * which makes each instance self-scoping: two sheets open at once are two hosts, and
+ * every query here descends from one of them. That is worth stating because it is
+ * NOT how the drawer harness underneath has to work — a drawer publishes no link to
+ * the overlay it opened, so `WrDrawerHarness` anchors on the shared pane and scopes
+ * by id.
+ *
+ * **What belongs to the drawer, not here.** Dismissal by backdrop click or by the ✕
+ * button, the modal role, the focus trap and the panel's position are all the
+ * drawer's surface, and `WrDrawerHarness` from the same root loader answers them.
+ * {@link sendEscape} is the one exception, kept because dismissing without choosing
+ * is a documented behaviour of the sheet itself: it closes and emits NOTHING, which
+ * is the assertion most specs are actually after.
+ *
+ * @example
+ * ```ts
+ * const rootLoader = TestbedHarnessEnvironment.documentRootLoader(fixture);
+ * const sheet = await rootLoader.getHarness(WrActionSheetHarness);
+ *
+ * expect(await sheet.getActionLabels()).toEqual(['Take Photo', 'Delete', 'Cancel']);
+ * await sheet.select({ label: 'Delete' });
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrActionSheetHarness extends ComponentHarness {
+    /** The sheet's root inside the drawer panel. A closed sheet renders none. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — sheets can be stacked. */
+    static with(options?: WrActionSheetHarnessFilters): HarnessPredicate<WrActionSheetHarness>;
+    /**
+     * Whether this sheet is still open.
+     *
+     * A harness can only be obtained while the sheet is open — closing disposes the
+     * overlay and everything in it — so this is the answer for a harness you are
+     * already HOLDING: it flips to `false` after a pick or a dismissal, where a fresh
+     * `getHarnessOrNull()` comes back `null`.
+     *
+     * Attachment is the test rather than a class, because disposal removes the element
+     * without changing anything on it.
+     */
+    isOpen(): Promise<boolean>;
+    /** The visible heading, or `null` when the sheet was opened without a `title`. */
+    getTitle(): Promise<string | null>;
+    /** The muted sub-heading, or `null` when the sheet has no `message`. */
+    getMessage(): Promise<string | null>;
+    /**
+     * The name the dialog announces.
+     *
+     * The sheet always publishes one, and for an untitled sheet it is INVISIBLE: the
+     * component renders a screen-reader-only `[wrDrawerTitle]` carrying
+     * `actionSheet.label` (English default `Actions`), because a bottom sheet is an
+     * `aria-modal` dialog and an unnamed one is announced as nothing at all. Nothing
+     * on screen changes when that string is wrong or missing, which is exactly why it
+     * is worth an assertion.
+     *
+     * Read from `.wr-drawer__title` — the class the title directive applies — so the
+     * one query answers for both shapes: the visible heading carries it too.
+     */
+    getAccessibleName(): Promise<string>;
+    /** Whether the announced name comes from a visible heading rather than the fallback. */
+    isTitleVisible(): Promise<boolean>;
+    /**
+     * Whether the dialog is actually WIRED to that name — the drawer panel's
+     * `aria-labelledby` resolving to this sheet's own title element, and to nothing
+     * else on the page.
+     *
+     * {@link getAccessibleName} only proves a string exists in the markup; a screen
+     * reader reads it only if the reference points at it. The two are separate
+     * failures and the second is silent: the title renders, the sheet looks right, and
+     * the dialog is announced as unnamed. Worth its own assertion because the drawer
+     * resolves the reference AFTER attaching the panel rather than while rendering it,
+     * so a title that arrives late is named late or not at all.
+     *
+     * Counted across the document as well, because two panels answering to one id hand
+     * every reference to whichever comes first — which is how a second sheet ends up
+     * announcing the first one's title.
+     */
+    isNamed(): Promise<boolean>;
+    /** The rows this sheet offers, in DOM order — cancel rows last, in their own group. */
+    getActions(filters?: WrActionSheetActionHarnessFilters): Promise<WrActionSheetActionHarness[]>;
+    /** The labels of every row, in DOM order. */
+    getActionLabels(): Promise<string[]>;
+    /**
+     * The labels grouped the way the sheet lays them out: the main group first, then
+     * the cancel group when there is one.
+     *
+     * The grouping is the component's whole visual contract — a `cancel` row is pulled
+     * out of the list and pinned to the bottom with a gap above it — and it is
+     * invisible to {@link getActionLabels}, which flattens the two. A cancel row that
+     * stopped being separated would still come last in DOM order, so the flat list
+     * cannot catch it.
+     */
+    getActionGroups(): Promise<string[][]>;
+    /**
+     * Whether the sheet drew a separate bottom group — true exactly when at least one
+     * row was given `role: 'cancel'`, since the component omits the group entirely
+     * rather than rendering an empty one.
+     */
+    hasCancelGroup(): Promise<boolean>;
+    /**
+     * Pick the first row matching the filters.
+     *
+     * Throws when nothing matches, naming what the sheet does offer — the alternative
+     * is a silent no-op followed by an assertion about a sheet that never moved. A
+     * disabled match throws too, from the row harness.
+     */
+    select(filters: WrActionSheetActionHarnessFilters): Promise<void>;
+    /**
+     * Press Escape — dismissing the sheet WITHOUT emitting `action`.
+     *
+     * The key never needs to reach the sheet itself: the drawer underneath listens
+     * through the CDK's keyboard dispatcher, which keeps one document listener and
+     * hands the event to the top-most overlay. So with sheets stacked this dismisses
+     * the top one whichever harness it is called on.
+     */
+    sendEscape(): Promise<void>;
+}
+
+export { WrActionSheetActionHarness, WrActionSheetHarness };
+export type { WrActionSheetActionHarnessFilters, WrActionSheetHarnessFilters };

package/types/ngwr-bar-chart-testing.d.ts

@@ -0,0 +1,77 @@
+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-bar-chart>` a harness query matches. */
+interface WrBarChartHarnessFilters extends BaseHarnessFilters {
+    /** Match a chart holding a bar with this label. */
+    readonly barLabel?: string | RegExp;
+}
+/** One column, as the chart draws and announces it. */
+interface WrBarChartBar {
+    /** The label printed under the column — decoration, and `aria-hidden`. */
+    readonly label: string;
+    /** The value printed above it, or `null` when `showValues` is off. */
+    readonly value: string | null;
+    /** What the column announces: the label and the value in one string. */
+    readonly name: string | null;
+    /** The bar's height as a percentage of the chart's maximum. */
+    readonly heightPercent: 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-bar-chart>`.
+ *
+ * **The bars are read as PERCENTAGES, not as pixels.** Each column's height is
+ * written inline as a share of the chart's maximum, which is the one number that
+ * survives a test with no layout — and it is also the component's whole job, since
+ * the maximum is either given or derived from the data.
+ *
+ * **The visible label row is decoration.** Every column carries `role="img"` with
+ * the label AND the value in its name, and the printed labels underneath are
+ * `aria-hidden` — so {@link WrBarChartBar.name} is what a screen reader gets and
+ * {@link WrBarChartBar.label} is what is drawn. Asserting only the second would pass
+ * on a chart that announces nothing.
+ *
+ * @example
+ * ```ts
+ * const chart = await loader.getHarness(WrBarChartHarness);
+ *
+ * expect(await chart.getLabels()).toEqual(['Mon', 'Tue', 'Wed']);
+ * expect((await chart.getBars())[1].heightPercent).toBe(100);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrBarChartHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrBarChartHarnessFilters): HarnessPredicate<WrBarChartHarness>;
+    /** Every column, in data order. */
+    getBars(): Promise<WrBarChartBar[]>;
+    /** The labels printed under the columns, in order. */
+    getLabels(): Promise<string[]>;
+    /** What each column announces — the label and the value together. */
+    getAccessibleNames(): Promise<(string | null)[]>;
+    /** How many columns the chart drew. */
+    getBarCount(): Promise<number>;
+    /** Whether the values are printed above the bars (`showValues`). */
+    hasValues(): Promise<boolean>;
+    /** The plot's height in pixels, as the component writes it inline. */
+    getPlotHeight(): Promise<number>;
+}
+
+export { WrBarChartHarness };
+export type { WrBarChartBar, WrBarChartHarnessFilters };

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

@@ -0,0 +1,180 @@
+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-blur-text>` a harness query matches. */
+interface WrBlurTextHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the string the component announces — the readable copy, not the pieces.
+     * A string is an exact match, a RegExp is tested.
+     *
+     * Matching on the accessible copy rather than on the host's text is deliberate:
+     * the host also holds a span per character, so its text reads back as the string
+     * twice over, and a filter written against that would depend on the split.
+     */
+    readonly text?: string | RegExp;
+    /**
+     * Match on how many animated pieces the split produced — one per word, or one per
+     * character. The blunt way to tell two otherwise identical reveals apart, and the
+     * only number about the animation that is present in the DOM at all.
+     */
+    readonly pieceCount?: 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-blur-text>`.
+ *
+ * **Most of what this component does cannot be read from a test, and the methods that
+ * are missing are missing on purpose.** The reveal is a Web Animations tween per piece
+ * — blur, vertical offset and opacity, staggered — started by an `IntersectionObserver`.
+ * A unit test has no layout, no compositor and no WAAPI, so there is no
+ * `getOpacity()`, no `getBlurRadius()` and no `getOffset()`: each would report the
+ * staged from-state forever in jsdom, and in a real browser it would report the inline
+ * value while the compositor paints a different one. There is no `isAnimating()` and no
+ * `whenAnimationComplete()` either — nothing in the DOM says a tween is running, and
+ * completion is the `animationComplete` OUTPUT, which the host binds. Nor is there an
+ * `enterViewport()` / `scrollIntoView()`: the trigger is an observer, which a
+ * `TestElement` cannot reach, and a method that pretended to scroll would do nothing in
+ * jsdom and something untimed in a browser. The inputs that shape the tween —
+ * `direction`, `delay`, `stepDuration`, `easing` — never reach the DOM at all; they live
+ * in a keyframe array and an effect timing, and neither is a document.
+ *
+ * **What is real is the split and the accessible layer, and they are two questions.**
+ * The string is carried once in a visually-hidden span, and every animated piece is
+ * `aria-hidden` so a screen reader does not spell the text out letter by letter — so
+ * {@link getAccessibleText} is what is heard and {@link getPieces} is what is drawn, and
+ * a spec that only asserted the second would pass on a component that announces
+ * `W. e. l. c. o. m. e.` {@link getRenderedText} closes the loop: the split has to be
+ * lossless, and comparing it against the accessible copy is what catches a dropped space
+ * or a halved surrogate pair. (Whether the hidden copy is really off-screen is CSS —
+ * `clip-path` and a 1px box — and a test running no stylesheets cannot tell a correctly
+ * hidden span from one printing the string twice, so nothing here claims to.)
+ *
+ * **{@link hasStagedMotion} is the one thing about the tween worth pinning**, and it
+ * reports that the pieces were taken over rather than that anything is moving. Under
+ * reduced motion the component returns before touching them, which is the promise: a
+ * reader who asked for less motion must never be left with text staged at `opacity: 0`
+ * by an animation that then never runs.
+ *
+ * Driving the reveal is the spec's job, since jsdom supplies neither half of it:
+ *
+ * ```ts
+ * // Before TestBed.createComponent — keep the callbacks so the spec can fire them.
+ * vi.stubGlobal('IntersectionObserver', StubObserver);
+ * // Otherwise `el.animate(...)` throws mid-stagger and leaves the DOM half-staged.
+ * Reflect.set(Element.prototype, 'animate', () => ({ cancel: () => undefined, onfinish: null }));
+ * ```
+ *
+ * @example
+ * ```ts
+ * const text = await loader.getHarness(WrBlurTextHarness.with({ text: 'Welcome to ngwr' }));
+ *
+ * expect(await text.getPieces()).toEqual(['Welcome', 'to', 'ngwr']);
+ * expect(await text.getRenderedText()).toBe(await text.getAccessibleText());
+ * expect(await text.isTextHidden()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrBlurTextHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrBlurTextHarnessFilters): HarnessPredicate<WrBlurTextHarness>;
+    private readonly pieces;
+    private readonly spaces;
+    /**
+     * The whole string, as the one readable copy holds it.
+     *
+     * The only thing a screen reader gets, since every drawn piece is out of the tree —
+     * lose this span and the component becomes a nameless pile of hidden spans with no
+     * other symptom anywhere in the DOM.
+     *
+     * Untrimmed, deliberately. Leading and trailing whitespace is content the split has to
+     * carry through, and {@link getRenderedText} is meant to compare equal to this; a
+     * trimmed read on one side of that comparison would quietly forgive the case it exists
+     * to catch.
+     */
+    getAccessibleText(): Promise<string>;
+    /**
+     * The animated pieces, in document order — one per word or one per character.
+     *
+     * This is the split the stagger runs over: `['Hi', 'there']` for `animateBy="words"`
+     * against `['H', 'i', 't', 'h', 'e', 'r', 'e']` for `"chars"`, and `['a', '🚀']` for a
+     * surrogate pair the code-point split kept whole rather than halved into two broken
+     * glyphs. Whitespace is not here — it is rendered separately and never staggered, so
+     * see {@link getSpaceCount}.
+     */
+    getPieces(): Promise<string[]>;
+    /**
+     * How many pieces the stagger runs over.
+     *
+     * `delay` × this is the whole length of the effect, and it is the only number about
+     * the animation that exists in the document.
+     */
+    getPieceCount(): Promise<number>;
+    /**
+     * How many whitespace runs sit between the pieces.
+     *
+     * Worth a method of its own because whitespace is deliberately NOT a staggered piece:
+     * a regression that reclassified spaces as pieces would leave {@link getRenderedText}
+     * identical, change the stagger count and the rhythm of the reveal, and show up
+     * nowhere else.
+     */
+    getSpaceCount(): Promise<number>;
+    /**
+     * Everything the component drew, pieces and spaces together, in document order.
+     *
+     * The assertion this exists for is `getRenderedText() === getAccessibleText()`: the
+     * split must be lossless. A swallowed space, a re-split that dropped a character, or a
+     * surrogate pair cut in half all leave the accessible copy untouched and are invisible
+     * from anywhere else.
+     */
+    getRenderedText(): Promise<string>;
+    /**
+     * Whether every drawn piece is out of the accessibility tree.
+     *
+     * The defect this component exists to avoid is a screen reader reading
+     * `W. e. l. c. o. m. e.`, and one piece missing `aria-hidden` is enough to bring it
+     * back — so this is all-or-nothing, and across both element kinds: a stray readable
+     * space is heard as a pause in the middle of a word.
+     *
+     * Throws when the split produced nothing at all. An empty run of elements satisfies
+     * "every one of them is hidden" without anything being hidden, which is the answer a
+     * component that stopped rendering its pieces would also give.
+     */
+    isTextHidden(): Promise<boolean>;
+    /**
+     * Whether the reveal has taken the pieces over — NOT whether anything is animating.
+     *
+     * Read off the inline `style` attribute the component writes itself, so it stays
+     * `true` after the reveal finishes: the tween commits its end state back to the same
+     * inline properties on `onfinish`. Anyone reaching for `isAnimating()` wants a frame,
+     * and there are no frames here.
+     *
+     * `false` is the answer worth asserting. It means no piece was written to at all,
+     * which is both the pre-trigger state and the reduced-motion promise — the component
+     * returns before staging anything, so a reader who asked for less motion cannot be
+     * left staring at text parked at `opacity: 0` by an animation that never runs.
+     *
+     * ANY piece counts, not all of them, and that is the conservative reading rather than
+     * a loose one: a stagger that stages the first piece and then throws leaves exactly one
+     * piece invisible, which is a real failure and one jsdom reproduces whenever
+     * `Element.prototype.animate` is missing.
+     */
+    hasStagedMotion(): Promise<boolean>;
+}
+
+export { WrBlurTextHarness };
+export type { WrBlurTextHarnessFilters };

package/types/ngwr-blur-text.d.ts

@@ -52,6 +52,18 @@ declare class WrBlurText {
     private readonly isBrowser;
     private readonly platform;
     private hasAnimated;
+    /**
+     * The ONE observer, replaced rather than stacked.
+     *
+     * `startObserver()` used to `new IntersectionObserver(…)` and register its own
+     * `destroyRef.onDestroy` every time, and the effect below calls it on every
+     * `text` change after setting `hasAnimated = false` — so the guard at the top
+     * of `startObserver` never blocked that path. An off-screen element (the only
+     * case where the observer does not immediately disconnect itself) therefore
+     * leaked one live observer AND one destroy callback per change, all of them
+     * watching the same host and all of them able to fire `animate()`.
+     */
+    private observer;
     constructor();
     private startObserver;
     private animate;