ngwr 11.0.0 → 11.2.0

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

@@ -0,0 +1,79 @@
+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-donut-chart>` a harness query matches. */
+interface WrDonutChartHarnessFilters extends BaseHarnessFilters {
+    /** Match the chart's accessible name. */
+    readonly ariaLabel?: string | RegExp;
+    /** Match a chart whose legend holds this label. */
+    readonly sliceLabel?: string | RegExp;
+}
+/** One legend row — the only place a slice's label and value are readable. */
+interface WrDonutChartLegendEntry {
+    readonly label: string;
+    readonly value: string;
+}
+
+/**
+ * @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-donut-chart>`.
+ *
+ * **The ring itself is unreadable, and that is by design.** The slices are SVG
+ * paths inside an `aria-hidden` drawing: a screen reader is given the chart's
+ * `aria-label` and nothing else, and a spec cannot get a label or a value off a
+ * path's `d`. {@link getLegend} is where the numbers are — which is also the
+ * argument for keeping `showLegend` on, since with it off the chart's data has no
+ * textual form at all.
+ *
+ * {@link getSliceCount} is therefore the one thing the ring answers: how many
+ * wedges were drawn. Compare it with the legend's length to catch a slice that was
+ * filtered out of one and not the other.
+ *
+ * @example
+ * ```ts
+ * const chart = await loader.getHarness(WrDonutChartHarness);
+ *
+ * expect(await chart.getSliceCount()).toBe(3);
+ * expect(await chart.getLegend()).toEqual([
+ *   { label: 'Direct', value: '48' },
+ *   { label: 'Search', value: '32' },
+ *   { label: 'Social', value: '20' },
+ * ]);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrDonutChartHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrDonutChartHarnessFilters): HarnessPredicate<WrDonutChartHarness>;
+    /** The name the ring announces — the whole chart's, since the slices announce nothing. */
+    getAccessibleName(): Promise<string | null>;
+    /** How many wedges were drawn. */
+    getSliceCount(): Promise<number>;
+    /** Whether the legend is rendered (`showLegend`, and at least one slice). */
+    hasLegend(): Promise<boolean>;
+    /** The legend rows in order — the only textual form the data has. */
+    getLegend(): Promise<WrDonutChartLegendEntry[]>;
+    /** The big number in the middle, or `null` when the chart has none. */
+    getCenterValue(): Promise<string | null>;
+    /** The caption under the centre value, or `null`. */
+    getCenterLabel(): Promise<string | null>;
+    /** The ring's diameter in pixels, as the component writes it inline. */
+    getSize(): Promise<number>;
+}
+
+export { WrDonutChartHarness };
+export type { WrDonutChartHarnessFilters, WrDonutChartLegendEntry };

package/types/ngwr-drawer.d.ts

@@ -143,6 +143,18 @@ declare class WrDrawer {
     private focusTrap;
     private previouslyFocused;
     constructor();
+    /**
+     * Point the panel's `aria-labelledby` at the CURRENT `[wrDrawerTitle]`.
+     *
+     * Re-resolved after every render rather than once when the drawer opens,
+     * because the title element is projected content and can come and go while
+     * the drawer stays open — an `@if` around it, or a heading that only exists
+     * once the data arrives. A one-shot lookup leaves the attribute naming an
+     * element that has been removed or replaced, and a dangling reference is not
+     * a name: the dialog is announced as unnamed, with nothing on screen to say
+     * so. A missing title clears the attribute for the same reason.
+     */
+    private syncLabel;
     private openOverlay;
     private closeOverlay;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrDrawer, never>;

package/types/ngwr-dropdown.d.ts

@@ -97,6 +97,15 @@ declare class WrDropdown {
     /** Toggle the menu. */
     toggle(): void;
     /** @internal */
+    /**
+     * Whether the pointer, rather than the keyboard, opened the current menu.
+     *
+     * A hover-opened menu must not take focus — the APG shows a menu on hover and
+     * leaves the caret where it was — while a keyboard-opened one must. The
+     * trigger MODE cannot answer that on its own: a `trigger="hover"` menu is
+     * still openable with Enter, and that open should focus the first item.
+     */
+    private openedByPointer;
     protected onClick(event: MouseEvent): void;
     /** @internal */
     protected onMouseEnter(): void;

package/types/ngwr-event-calendar-testing.d.ts

@@ -0,0 +1,301 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+import { WrCalendarView } from 'ngwr/event-calendar';
+
+/**
+ * @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-event-calendar>` a harness query matches. */
+interface WrEventCalendarHarnessFilters extends BaseHarnessFilters {
+    /** Match the header title as printed — a string is an exact match, a RegExp is tested. */
+    readonly title?: string | RegExp;
+    /** Match the view the calendar is showing. */
+    readonly view?: WrCalendarView;
+}
+/** Narrows which event chip a harness query matches. */
+interface WrEventCalendarChipHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the chip's accessible name, which is the time and the title together —
+     * the visible text is `aria-hidden`, so this is what a screen reader gets.
+     */
+    readonly label?: string | RegExp;
+    /** Match the chip's title text as printed. */
+    readonly title?: string | RegExp;
+    /** Match day-spanning bands (`true`) or timed chips (`false`). */
+    readonly band?: 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
+ */
+
+/** The arrow keys, by the direction a user would say out loud. */
+type Arrow$1 = 'left' | 'right' | 'up' | 'down';
+/**
+ * Test harness for one event chip inside a {@link WrEventCalendarHarness}.
+ *
+ * **The visible text is `aria-hidden`; the name is on the button.** A chip prints a
+ * time and a title for the eye, and publishes both as one `aria-label` for a screen
+ * reader — so {@link getLabel} is what the control announces and {@link getTitle} is
+ * what is drawn. They are separate because a consumer's `[wrCalendarEvent]` template
+ * replaces the drawn half and not the announced one.
+ *
+ * **Moving and resizing are on the keyboard here, and not because of jsdom.** The
+ * pointer drag is real, but the same two operations are bound to the arrows —
+ * `Alt` to move, `Alt` + `Shift` to resize — precisely so the calendar is usable
+ * without one. That is the path this harness drives; a synthetic drag would divide
+ * by a rect that measures 0×0 anyway.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrEventCalendarChipHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrEventCalendarChipHarnessFilters): HarnessPredicate<WrEventCalendarChipHarness>;
+    /** What the chip announces — its time and title in one string. */
+    getLabel(): Promise<string | null>;
+    /**
+     * The title as drawn, or `null` when a consumer template replaced it.
+     *
+     * The default chip prints its own `.wr-event-calendar__chip-title`; a
+     * `[wrCalendarEvent]` template renders whatever the consumer wrote instead, and
+     * there is no title element to find. {@link getText} is the fallback that always
+     * answers.
+     */
+    getTitle(): Promise<string | null>;
+    /** The chip's whole rendered text, whoever drew it. */
+    getText(): Promise<string>;
+    /** The time as printed on a timed chip, or `null` on a band, which prints none. */
+    getTime(): Promise<string | null>;
+    /**
+     * Whether this is a day-spanning BAND rather than a timed chip.
+     *
+     * One shape covers two places — a month cell and the all-day row — and the other
+     * is the block in a time grid. They size themselves completely differently (a
+     * `calc()` width across columns versus a percentage height down one), which is why
+     * the two are worth telling apart.
+     */
+    isBand(): Promise<boolean>;
+    /** Whether the event started before this cell — the chip is drawn cut off at the leading edge. */
+    continuesBefore(): Promise<boolean>;
+    /** Whether the event runs past this cell. */
+    continuesAfter(): Promise<boolean>;
+    /** Whether the chip is mid-drag. */
+    isDragging(): Promise<boolean>;
+    /**
+     * Whether the chip offers a resize grab area.
+     *
+     * It is `aria-hidden` and not focusable on purpose — the same resize is `Alt` +
+     * `Shift` + arrows on the chip itself, so a second tab stop here would lead
+     * nowhere. Its
+     * presence is still the mouse affordance, and it is dropped on a chip whose event
+     * continues past this cell.
+     */
+    hasResizeHandle(): Promise<boolean>;
+    /**
+     * Click the chip — which emits `eventClick` and does NOT bubble to the cell
+     * underneath.
+     *
+     * On an editable calendar this needs `document.elementFromPoint` to exist: the CDK
+     * dispatches a whole pointer sequence, and the chip's `pointerdown` hit-tests for
+     * the cell under the cursor. jsdom implements no such method, so stub it in your
+     * spec — `() => null` is the honest answer where nothing has a box — or the click
+     * throws out of the listener.
+     */
+    click(): Promise<void>;
+    /** Move keyboard focus to the chip. */
+    focus(): Promise<void>;
+    /** Whether the chip currently holds focus. */
+    isFocused(): Promise<boolean>;
+    /**
+     * Move the event — `Alt` + an arrow, a day sideways or a slot vertically.
+     *
+     * The calendar never mutates `events`: this emits `eventChange` and the host is
+     * expected to apply it. A spec whose host ignores the output is asserting a
+     * CANCELLED move, which is the contract and the most common surprise here. A
+     * calendar without `editable` ignores the keys entirely — the same gate the pointer
+     * path uses.
+     */
+    move(arrow: Arrow$1): Promise<void>;
+    /**
+     * Resize the event — `Alt` + `Shift` + an arrow, which moves the END alone.
+     *
+     * A resize that would end at or before the start emits nothing rather than
+     * inverting the event, which is the pointer path's rule too.
+     */
+    resize(arrow: Arrow$1): Promise<void>;
+    /** Press a bare arrow — which the chip ignores, letting the grid's own navigation run. */
+    pressArrow(arrow: Arrow$1): Promise<void>;
+    /** Press Escape — handing focus back to the cell the chip sits in. */
+    sendEscape(): Promise<void>;
+}
+
+/**
+ * @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
+ */
+
+/** The arrow keys, by the direction a user would say out loud. */
+type Arrow = 'left' | 'right' | 'up' | 'down';
+/**
+ * Test harness for `<wr-event-calendar>` — month, week and day in one component.
+ *
+ * **Every chip lives inside the `role="gridcell"` where its event STARTS**, and
+ * reaches out from there with a `calc()` width or a percentage height. That is a
+ * deliberate structural choice — a floating events layer would leave `role="row"`
+ * owning something other than cells — and it is why {@link getChips} can be scoped
+ * to a cell at all.
+ *
+ * **The view is read from the DOM, not from the input.** A month renders one grid
+ * shape and week / day another, and those two are told apart by how many day columns
+ * they draw. That is the honest answer for a harness: `view` is a model a consumer
+ * can write, and the grid is what the user sees.
+ *
+ * **Nothing here mutates the events.** A move or a resize emits `eventChange` and
+ * the host applies it — so a spec whose host ignores the output is asserting a
+ * CANCELLED gesture, which is the contract rather than a bug.
+ *
+ * @example
+ * ```ts
+ * const calendar = await loader.getHarness(WrEventCalendarHarness);
+ *
+ * expect(await calendar.getView()).toBe('month');
+ * const [standup] = await calendar.getChips({ title: 'Standup' });
+ * await standup.move('right');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrEventCalendarHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrEventCalendarHarnessFilters): HarnessPredicate<WrEventCalendarHarness>;
+    private readonly grid;
+    /**
+     * Which view is on screen.
+     *
+     * `month` has its own grid modifier; `week` and `day` share the time grid and are
+     * told apart by the column count the component publishes on it. Reading the DOM
+     * rather than the `view` model is the point — that model is an input a consumer can
+     * set to anything, and this is what got rendered.
+     */
+    getView(): Promise<WrCalendarView>;
+    /** The header title — the month, the week's range, or the day. */
+    getTitle(): Promise<string>;
+    /** Whether the header is rendered at all (`hideHeader`). */
+    hasHeader(): Promise<boolean>;
+    /** The grid's accessible name. */
+    getAccessibleName(): Promise<string | null>;
+    /** Step back one month, week or day, depending on the view. */
+    previous(): Promise<void>;
+    /** Step forward one month, week or day. */
+    next(): Promise<void>;
+    /** Press the Today button — jumping to the period containing today. */
+    goToday(): Promise<void>;
+    /** The back arrow's accessible name — the two steps are icon-only. */
+    getPreviousLabel(): Promise<string | null>;
+    /** The forward arrow's accessible name. */
+    getNextLabel(): Promise<string | null>;
+    /** The Today button's label. */
+    getTodayLabel(): Promise<string>;
+    /**
+     * The view switcher's labels, in order — empty when the calendar was given a single
+     * view, which drops the switcher entirely.
+     */
+    getViewLabels(): Promise<string[]>;
+    /** The label of the view currently pressed, or `null` when there is no switcher. */
+    getActiveViewLabel(): Promise<string | null>;
+    /**
+     * Switch view by the label the switcher prints.
+     *
+     * By label rather than by the `WrCalendarView` value, because the label is what the
+     * DOM has — the value never reaches it, and a spec that passed one would be naming
+     * something only the component can see. {@link getViewLabels} lists them.
+     */
+    setView(label: string): Promise<void>;
+    /** The weekday column headers of the month view. */
+    getWeekdayNames(): Promise<string[]>;
+    /** The day numbers of the month grid, in order — 42 of them, spill days included. */
+    getDayNumbers(): Promise<string[]>;
+    /** The time-gutter labels down the left of a week or day view. */
+    getSlotLabels(): Promise<string[]>;
+    /** Whether the time views drew an all-day band, which they only do when something needs it. */
+    hasAllDayRow(): Promise<boolean>;
+    /**
+     * Every chip on screen, in DOM order.
+     *
+     * A multi-day event has ONE chip, in the cell where it starts — the band reaches
+     * across the rest — so this counts events-in-view rather than event-days.
+     */
+    getChips(filters?: WrEventCalendarChipHarnessFilters): Promise<WrEventCalendarChipHarness[]>;
+    /** The chips' announced names, in DOM order. */
+    getChipLabels(): Promise<(string | null)[]>;
+    /**
+     * The "+N more" overflow buttons of the month view, by the text they print.
+     *
+     * A month cell shows `maxLanes` chips and hides the rest behind one of these, which
+     * opens the day view — so its presence is the only sign that a cell has more than
+     * it is showing.
+     */
+    getOverflowLabels(): Promise<string[]>;
+    /** Click the first "+N more" button, which drops to the day view for that date. */
+    openOverflow(): Promise<void>;
+    /**
+     * Click an empty part of a cell — which emits `slotClick` with its date and minutes.
+     *
+     * A cell is addressed by its DAY and, in a time view, the minutes from midnight of
+     * its row (`-1` means a month cell or the all-day band). Both come off the two data
+     * attributes every cell publishes for the drag's own hit-testing, which makes them
+     * the one stable way to name a cell from outside — a row index would mean something
+     * different in each view.
+     */
+    clickCell(day: Date, minutes?: number): Promise<void>;
+    /** A cell's accessible name — the date, and the time for a slot. */
+    getCellLabel(day: Date, minutes?: number): Promise<string | null>;
+    /** The chips inside ONE cell, which is where a chip's event starts. */
+    getCellChips(day: Date, minutes?: number): Promise<WrEventCalendarChipHarness[]>;
+    /**
+     * The grid's single tab stop, as `"<day>:<minutes>"`.
+     *
+     * The cursor roves rather than every cell being tabbable, and it is RAW — it
+     * survives a view switch, so the same pair means a different cell in a month grid
+     * and a week one.
+     */
+    getCursor(): Promise<string | null>;
+    /** Move keyboard focus to a cell, which is also what moves the roving cursor onto it. */
+    focusCell(day: Date, minutes?: number): Promise<void>;
+    /**
+     * Press an arrow on the cell that currently holds the cursor.
+     *
+     * Sent to that cell rather than to the grid, because the component listens per cell
+     * — the element carrying the keyboard should be the one that holds focus — and
+     * anything originating inside a chip is deliberately let through untouched.
+     */
+    pressArrow(arrow: Arrow): Promise<void>;
+    /** Press Home on the cursor cell — the first day of its week. */
+    pressHome(): Promise<void>;
+    /** Press End on the cursor cell — the last day of its week. */
+    pressEnd(): Promise<void>;
+    private step;
+    private stepElement;
+    private headerButton;
+    /**
+     * The stamp a cell publishes for a day — local midnight, which is what the
+     * component's own `startOfDay` produces. Taking a `Date` and normalising here keeps
+     * the timestamp out of every spec.
+     */
+    private stamp;
+    private requireCell;
+    private cursorCell;
+}
+
+export { WrEventCalendarChipHarness, WrEventCalendarHarness };
+export type { WrEventCalendarChipHarnessFilters, WrEventCalendarHarnessFilters };

package/types/ngwr-event-calendar.d.ts

@@ -220,13 +220,16 @@ declare class WrEventCalendar {
     private readonly document;
     private readonly dir;
     private readonly chipTpl;
-    protected readonly todayLabel: string;
-    protected readonly previousLabel: string;
-    protected readonly nextLabel: string;
-    protected readonly allDayLabel: string;
-    protected readonly timeLabel: string;
+    protected readonly todayLabel: _angular_core.Signal<string>;
+    protected readonly previousLabel: _angular_core.Signal<string>;
+    protected readonly nextLabel: _angular_core.Signal<string>;
+    protected readonly allDayLabel: _angular_core.Signal<string>;
+    protected readonly timeLabel: _angular_core.Signal<string>;
     protected readonly moreLabel: (params?: ngwr_i18n.WrI18nParams) => string;
-    protected readonly viewLabels: Record<WrCalendarView, string>;
+    private readonly monthLabel;
+    private readonly weekLabel;
+    private readonly dayLabel;
+    protected readonly viewLabels: _angular_core.Signal<Record<WrCalendarView, string>>;
     /** Accessible name of the grid; overridable for a page with several. */
     readonly ariaLabel: _angular_core.InputSignal<string | null>;
     protected readonly resolvedAriaLabel: _angular_core.Signal<string>;

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

@@ -0,0 +1,186 @@
+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-falling-text>` a harness query matches. */
+interface WrFallingTextHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the rendered sentence — the only thing that tells two of these apart, the
+     * component having no name, id or role of its own. A string is an exact match, a
+     * RegExp is tested.
+     *
+     * Compared against `WrFallingTextHarness.getText()`, so the non-breaking spaces the
+     * component types between the words are already back to plain ones: pass the sentence
+     * as it was written.
+     */
+    readonly text?: string | RegExp;
+}
+
+/**
+ * @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-falling-text>`.
+ *
+ * **The assertion that matters here is that the animation did not eat the text.** The
+ * component cuts the sentence into one span per word so a physics loop can throw them
+ * around, and {@link getText} is the check that a screen reader still gets prose out of
+ * the other end. It normalises whitespace on the way, because the separators are real
+ * `&nbsp;` characters rather than plain spaces — so `textContent` is never byte-identical
+ * to the `[text]` input, and a spec comparing the two raw would fail on a component that
+ * works perfectly.
+ *
+ * The rest of the readable surface is the split itself: {@link getWords} pins the rule
+ * (split on spaces, empty tokens dropped) and {@link getHighlightedWords} pins the
+ * prefix match, which is genuine logic — `grav` highlights `gravity`, and a whole-word
+ * implementation would satisfy every naive test but not this one.
+ *
+ * **Nothing positional is offered, and that is not a jsdom concession.** The words'
+ * `transform` values are one frame of a loop that never stops, seeded by `Math.random()`,
+ * so they are not reproducible even in a real browser; there is no rest state to call
+ * settled; the drag path needs `setPointerCapture` and AABB hit-testing over boxes that
+ * a unit test measures as 0×0 at the origin, where every word contains every point. Nor
+ * is `[gravity]` or `[trigger]` readable — neither reaches the DOM, and answering them
+ * would mean reaching into the component instance. There is no `isReducedMotion()`
+ * either: under reduced motion the component simply returns before touching anything, so
+ * the only honest proxy is {@link hasReleased}, which reports what it did rather than
+ * what it was told.
+ *
+ * **{@link hasReleased} and {@link release} have a precondition, and without it they are
+ * worthless.** The simulator measures the host and each word before it starts, and bails
+ * on a zero-sized box — which is every box in a test with no layout. So the spec has to
+ * give them one, and it has to do it BEFORE the trigger fires: the component marks itself
+ * started on the way past that guard, and the trigger listener is `{ once: true }`, so a
+ * failed first attempt is permanent.
+ *
+ * ```ts
+ * // In your spec, on a fixture mounted with trigger="click", before calling release():
+ * const box = { width: 300, height: 120, left: 0, top: 0, right: 300, bottom: 120 } as DOMRect;
+ * for (const el of fixture.nativeElement.querySelectorAll('wr-falling-text, .wr-falling-text__word')) {
+ *   el.getBoundingClientRect = () => box;
+ * }
+ * ```
+ *
+ * Assert `hasReleased()` is `true` in that control case before you assert it is `false`
+ * anywhere else, or a spec proves only that the guard fired.
+ *
+ * @example
+ * ```ts
+ * const loader = TestbedHarnessEnvironment.loader(fixture);
+ * const text = await loader.getHarness(WrFallingTextHarness);
+ *
+ * expect(await text.getText()).toBe('gravity pulls every word down');
+ * expect(await text.getHighlightedWords()).toEqual(['gravity']);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrFallingTextHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrFallingTextHarnessFilters): HarnessPredicate<WrFallingTextHarness>;
+    private readonly wordEls;
+    /**
+     * The whole sentence, as a screen reader reads it: whitespace collapsed and trimmed.
+     *
+     * The one assertion worth making about a component that dismantles a paragraph. The
+     * words are separated by `.wr-falling-text__space` spans holding U+00A0, so this
+     * collapses them back to ordinary spaces — losing those spans would be invisible to
+     * every other check here while turning the announcement into one run-on word.
+     *
+     * DOM order never changes once the physics starts. The words are absolutely positioned
+     * and scattered on screen, but they are still read in the order they were typeset, so
+     * this answers the same before and after {@link release}.
+     */
+    getText(): Promise<string>;
+    /**
+     * Each word, in DOM order.
+     *
+     * Pins the split rule: on a literal space, with empty tokens dropped. Each of these is
+     * also one body in the simulator, so the length is the body count — which is why there
+     * is no separate `getWordCount()`, a method that would invite asserting how many
+     * without asserting which.
+     */
+    getWords(): Promise<string[]>;
+    /**
+     * The words carrying the highlight, in DOM order.
+     *
+     * `[highlightWords]` is matched as a PREFIX and case-sensitively, so `['grav']` picks
+     * up `gravity` and `['Grav']` picks up nothing. The highlight is colour alone with no
+     * non-visual counterpart, which is acceptable only because it adds no meaning the
+     * sentence does not already carry.
+     */
+    getHighlightedWords(): Promise<string[]>;
+    /**
+     * Whether one word is highlighted — for asserting a keyword without depending on the
+     * order or the completeness of the whole list.
+     *
+     * Takes the word as it is rendered, not the keyword that matched it: ask for `gravity`,
+     * not for `grav`. Throws for a word the sentence does not contain, since `false` there
+     * would read as "present and not highlighted" and quietly survive a typo. A word that
+     * appears twice is answered once, which is safe — matching is on the text alone, so
+     * both copies always agree.
+     */
+    isHighlighted(word: string): Promise<boolean>;
+    /**
+     * The font size as the consumer wrote it — `'2rem'`, not `'32px'`.
+     *
+     * Read off the inline `style` attribute rather than through `getCssValue()`. The two
+     * agree here and would part company in a real browser, which resolves `font-size` to
+     * pixels; `[fontSize]` takes a CSS length and handing back a different unit than the
+     * one that went in is the sort of green unit test that hides a broken assertion.
+     *
+     * Throws when nothing is written, which takes an empty `[fontSize]` — the component
+     * writes this on every render otherwise, default included.
+     */
+    getFontSize(): Promise<string>;
+    /**
+     * Whether the simulator has taken the words over.
+     *
+     * Reads the `position: absolute` the component writes onto every word before its first
+     * frame — a value it wrote itself, not a measurement, and the only difference in the
+     * DOM between "the physics is running" and "the words are still in normal flow". That
+     * makes it the way to observe the trigger contract and the reduced-motion escape, since
+     * neither leaves anything else behind.
+     *
+     * **It is `false` by default in a test, for a reason that has nothing to do with the
+     * component.** Without layout every box measures 0×0 and the simulator refuses to start
+     * — see this class's docs for the stub, and assert a `true` before you trust a `false`.
+     *
+     * Throws for a component rendering no words at all, where the question does not apply.
+     */
+    hasReleased(): Promise<boolean>;
+    /**
+     * Fire the events a `click` or `hover` trigger is waiting for.
+     *
+     * Both, because the harness cannot tell which one it is: `[trigger]` never reaches the
+     * DOM. The component consumes at most one — its listener is registered `{ once: true }`
+     * and the simulator refuses to start twice — so this is safe to call whatever the
+     * trigger is, and safe to call again.
+     *
+     * It does nothing for `auto`, which released on mount, and nothing for `scroll`, which
+     * waits on an `IntersectionObserver`: jsdom has none, so a spec has to stub the global
+     * and fire the callback itself. Same precondition as {@link hasReleased} — stub the
+     * boxes BEFORE calling this, because a start that bails on a zero-sized host still
+     * burns the trigger.
+     *
+     * Both are dispatched as bare events rather than through the harness's `click()` and
+     * `hover()` helpers, which would bring a whole pointer sequence with them. Released
+     * words listen for `pointerdown` so they can be picked up and thrown, and that handler
+     * calls `setPointerCapture` — which a unit environment does not implement, so the
+     * realistic version of this method would throw the moment the simulator was running.
+     */
+    release(): Promise<void>;
+}
+
+export { WrFallingTextHarness };
+export type { WrFallingTextHarnessFilters };