ngwr 11.1.0 → 11.2.0

package/types/ngwr-speed-dial-testing.d.ts

@@ -0,0 +1,195 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+import { WrSpeedDialDirection } from 'ngwr/speed-dial';
+
+/**
+ * @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-speed-dial>` a harness query matches. */
+interface WrSpeedDialHarnessFilters extends BaseHarnessFilters {
+    /** Match the trigger's accessible name — a string is an exact match, a RegExp is tested. */
+    readonly triggerLabel?: string | RegExp;
+    /** Match the direction the actions fan out. */
+    readonly direction?: WrSpeedDialDirection;
+    /** Match only open (`true`) or only closed (`false`) dials. */
+    readonly open?: boolean;
+    /** Match only enabled (`false`) or only disabled (`true`) dials. */
+    readonly disabled?: boolean;
+}
+/** Narrows which action inside a speed dial a harness query matches. */
+interface WrSpeedDialActionHarnessFilters extends BaseHarnessFilters {
+    /** Match the action's accessible name — a string is an exact match, a RegExp is tested. */
+    readonly label?: string | RegExp;
+    /** Match only enabled (`false`) or only disabled (`true`) actions. */
+    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 action inside a {@link WrSpeedDialHarness}.
+ *
+ * The label is read from `aria-label` rather than from the button's text, and that
+ * is the whole point of the control: an action renders an ICON, or — with no icon —
+ * the first glyph of its label. Its visible text is therefore `"S"` for "Share", or
+ * nothing at all. {@link getInitial} answers what is drawn; {@link getLabel} answers
+ * what it is.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSpeedDialActionHarness extends ComponentHarness {
+    /** The action button. `role="menuitem"` sits on this element too. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSpeedDialActionHarnessFilters): HarnessPredicate<WrSpeedDialActionHarness>;
+    /** The action's accessible name — what a screen reader reads, and what `title` shows. */
+    getLabel(): Promise<string | null>;
+    /** The role the action announces — `menuitem`. */
+    getRole(): Promise<string | null>;
+    /** Whether the action draws an icon rather than a letter. */
+    hasIcon(): Promise<boolean>;
+    /** The icon's registered name, from `wr-icon`'s reflected `data-icon`, or `null`. */
+    getIconName(): Promise<string | null>;
+    /**
+     * The single glyph drawn in place of a missing icon, or `null` when there is one.
+     *
+     * A GLYPH, not a character: the component splits the label by code point, so an
+     * emoji label draws the whole emoji rather than the broken half of a surrogate pair.
+     */
+    getInitial(): Promise<string | null>;
+    /**
+     * Whether the action refuses interaction.
+     *
+     * Every action follows the DIAL's `disabled` — there is no per-action flag — so
+     * this is really "is the dial disabled", asked at the action. Worth having anyway:
+     * it is what the DOM and the CDK consult before delivering a click.
+     */
+    isDisabled(): Promise<boolean>;
+    /** Pick this action — emitting `pick` and closing the dial. */
+    click(): Promise<void>;
+    /** Move keyboard focus to the action. */
+    focus(): Promise<void>;
+    /** Whether the action 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 `<wr-speed-dial>` — the floating trigger and the actions that fan
+ * out of it.
+ *
+ * **The actions never leave the DOM.** They are hidden with `visibility`, which is
+ * what actually takes them out of the tab order and the accessibility tree —
+ * `opacity: 0` alone would leave them focusable — and CSS is exactly what a unit
+ * test does not have. So a closed dial's buttons are queryable, clickable and
+ * readable from a spec while being unreachable in a browser. {@link getActions} and
+ * {@link pick} therefore REFUSE while the dial is closed rather than answering with
+ * elements nobody can see; open it first, which is what a user has to do too.
+ *
+ * @example
+ * ```ts
+ * const dial = await loader.getHarness(WrSpeedDialHarness);
+ *
+ * await dial.open();
+ * expect(await dial.getActionLabels()).toEqual(['Share', 'Copy link']);
+ *
+ * await dial.pick({ label: 'Share' });
+ * expect(await dial.isOpen()).toBe(false);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSpeedDialHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSpeedDialHarnessFilters): HarnessPredicate<WrSpeedDialHarness>;
+    private readonly trigger;
+    private readonly menu;
+    /** Whether the dial is fanned out, from the trigger's `aria-expanded`. */
+    isOpen(): Promise<boolean>;
+    /** The direction the actions travel, from the host modifier. */
+    getDirection(): Promise<WrSpeedDialDirection>;
+    /**
+     * The trigger's accessible name.
+     *
+     * The trigger is icon-only, so this is its ONLY name — there is no text to fall
+     * back on, and a dial that loses it is announced as an unnamed button.
+     */
+    getTriggerLabel(): Promise<string | null>;
+    /** The trigger icon's registered name, from `wr-icon`'s reflected `data-icon`. */
+    getTriggerIcon(): Promise<string | null>;
+    /** Whether the dial refuses interaction, from the trigger's own `disabled` property. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the host is padded for the device's safe area (`safeArea`). */
+    hasSafeArea(): Promise<boolean>;
+    /** The role the action list announces — `menu`. */
+    getMenuRole(): Promise<string | null>;
+    /**
+     * Whether the trigger's `aria-controls` names THIS dial's menu, and nothing else on
+     * the page.
+     *
+     * Both halves matter. The id is resolved inside the host first, so a trigger
+     * pointing at a SIBLING dial's menu — which resolves perfectly well from the
+     * document — fails here. Then it is counted across the document, because two menus
+     * answering to one id hand every reference to whichever comes first.
+     */
+    isMenuBound(): Promise<boolean>;
+    /**
+     * The actions, in DOM order.
+     *
+     * Throws while the dial is closed. The buttons are still in the DOM then — they
+     * have to be, for the fan-out to animate — and jsdom applies no `visibility`, so
+     * they would come back looking perfectly reachable when a real user cannot tab to
+     * one. A spec that read them closed would pass on a dial that never opens.
+     */
+    getActions(filters?: WrSpeedDialActionHarnessFilters): Promise<WrSpeedDialActionHarness[]>;
+    /** The accessible names of the actions, in DOM order. Throws while closed. */
+    getActionLabels(): Promise<(string | null)[]>;
+    /** How many actions the dial holds — readable while closed, since it is not a reach. */
+    getActionCount(): Promise<number>;
+    /** Open the dial. An already-open one is left alone; a disabled one throws. */
+    open(): Promise<void>;
+    /** Close the dial. An already-closed one is left alone. */
+    close(): Promise<void>;
+    /** Click the trigger once, whichever way that takes it. */
+    toggle(): Promise<void>;
+    /**
+     * Pick the first action matching the filters — emitting `pick` and closing the dial.
+     *
+     * Opens first if it has to, the way `WrDropdownHarness.clickItem` does: a spec that
+     * says "pick Share" means the whole gesture. Throws when nothing matches, naming
+     * what the dial does offer.
+     */
+    pick(filters: WrSpeedDialActionHarnessFilters): Promise<void>;
+    /**
+     * Press Escape — closing the dial and putting focus back on the trigger.
+     *
+     * Sent to the host, which is where the component listens. The focus return is the
+     * half worth asserting: `role="menu"` promises a way out, and the actions are
+     * ordinary tab stops, so without it a keyboard user has to walk through every
+     * action to leave.
+     */
+    sendEscape(): Promise<void>;
+    /** Move keyboard focus to the trigger. */
+    focusTrigger(): Promise<void>;
+    /** Whether the trigger currently holds focus. */
+    isTriggerFocused(): Promise<boolean>;
+    private requireOpen;
+}
+
+export { WrSpeedDialActionHarness, WrSpeedDialHarness };
+export type { WrSpeedDialActionHarnessFilters, WrSpeedDialHarnessFilters };

package/types/ngwr-splash-cursor-testing.d.ts

@@ -0,0 +1,95 @@
+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-splash-cursor>` a harness query matches. */
+interface WrSplashCursorHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match only the page-wide overlay (`true`) or only a box-contained effect (`false`).
+     * The component has no name and no content, so its layout mode is the only thing that
+     * distinguishes two of them — see `WrSplashCursorHarness.isFullscreen`.
+     */
+    readonly fullscreen?: 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-splash-cursor>` — a WebGL fluid that splashes dye under the
+ * pointer.
+ *
+ * **This is a deliberately small surface, and the reason is the component.** The
+ * simulation is GL programs and framebuffers driven by `window` pointer listeners; the
+ * layout is `position: fixed`, `inset: 0`, `z-index: 50` and a `100dvh` canvas, all of
+ * it in the stylesheet. A unit test gets no WebGL context — the simulation is never
+ * constructed — and loads no stylesheet, so asking `getCssValue('position')` would
+ * answer `static` about a component whose whole layout contract is `fixed`. Three
+ * questions survive that, and they are the three below.
+ *
+ * There is no `isSimulating()`, `getSplatCount()` or `splat()`: the simulation returns
+ * `null` the moment the context is refused, so every one of those would report on
+ * something that was never built. No `moveMouse()` either — the listeners live on
+ * `window` and are only attached once a context exists, so a dispatched move reaches
+ * nothing. And no `isReducedMotion()` or `hasWebGL()`: the component renders
+ * byte-identical DOM whether it is running, standing down for reduced motion, or on a
+ * machine with no WebGL at all, so any answer would be the same for a working component
+ * and a broken one.
+ *
+ * @example
+ * ```ts
+ * const splash = await loader.getHarness(WrSplashCursorHarness);
+ *
+ * expect(await splash.isFullscreen()).toBe(true);
+ * expect(await splash.isDecorative()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSplashCursorHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSplashCursorHarnessFilters): HarnessPredicate<WrSplashCursorHarness>;
+    /**
+     * Whether the effect covers the whole viewport, rather than filling the nearest
+     * positioned ancestor.
+     *
+     * The component's one behavioural switch: fullscreen is a fixed, click-through
+     * overlay above the page, contained is an absolutely positioned box whose walls the
+     * dye collides with. Note what is being read — there is no `--fullscreen` class, only
+     * a `--contained` one written from a NEGATED binding, so this method answers the
+     * absence of a class. That inversion is exactly the kind that gets flipped in a
+     * refactor and looks fine on a page where the effect is full-viewport anyway, which
+     * is the whole reason the method exists.
+     */
+    isFullscreen(): Promise<boolean>;
+    /**
+     * Whether the effect is hidden from assistive tech.
+     *
+     * It has no text and nothing to say, and at full size it sits in front of the entire
+     * page — so losing this puts a nameless graphic over everything a screen reader is
+     * trying to get through.
+     */
+    isDecorative(): Promise<boolean>;
+    /**
+     * Whether the drawing surface is in the markup.
+     *
+     * It is there in all three states where nothing is ever drawn on it — prerendered on
+     * the server, WebGL refused, or reduced motion — because the documented contract is
+     * that the component renders nothing VISIBLE and stops, never that it renders no
+     * element and never that it throws on a null context.
+     */
+    hasCanvas(): Promise<boolean>;
+}
+
+export { WrSplashCursorHarness };
+export type { WrSplashCursorHarnessFilters };

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

@@ -0,0 +1,209 @@
+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
+ */
+
+/**
+ * The alignments `<wr-split-text>` takes.
+ *
+ * Restated here because the component declares the union inline on its `textAlign`
+ * input and exports no name for it — a filter typed `string` would take a value the
+ * component cannot produce and then quietly match nothing.
+ */
+type WrSplitTextHarnessAlign = 'left' | 'center' | 'right' | 'justify';
+/** Narrows which `<wr-split-text>` a harness query matches. */
+interface WrSplitTextHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the string the component announces — the readable copy, not the pieces.
+     * A string is an exact match, a RegExp is tested.
+     *
+     * Against the accessible copy rather than the host's own text, which holds the
+     * string twice: once readably and once as a span per character.
+     */
+    readonly text?: string | RegExp;
+    /**
+     * Match on how many animated pieces the split produced — one per character, or one
+     * per word. The only number about the animation that reaches the DOM.
+     */
+    readonly pieceCount?: number;
+    /**
+     * Match on the alignment the host was given.
+     *
+     * The most useful of the three in practice: a page usually carries several of these
+     * and alignment is what tells a centred hero from a left-aligned caption, whereas
+     * their text is the thing a spec is usually trying not to hard-code.
+     */
+    readonly textAlign?: WrSplitTextHarnessAlign;
+}
+
+/**
+ * @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-split-text>`.
+ *
+ * **The tween is unreadable from a test, and the absent methods are absent for that
+ * reason.** Each piece is animated from a `from` motion state to a `to` one through the
+ * Web Animations API, started by an `IntersectionObserver`. A unit test has no layout,
+ * no compositor and no WAAPI, so there is no `getOpacity()` and no `getTransform()`:
+ * both would report the frozen staged value in jsdom and a value the compositor is not
+ * painting in a browser. There is no `getFromState()` / `getToState()` either — those
+ * objects only reach the DOM as staged inline styles, on the one path that throws here,
+ * so reporting them would mean re-deriving an input from a string the component may
+ * never have written. No `isAnimating()`, no `whenAnimationComplete()`: nothing in the
+ * document says a tween is running, and completion is the `animationComplete` OUTPUT,
+ * which the host binds. No `enterViewport()` / `trigger()`, because an observer is not
+ * reachable from a `TestElement` — and observation here is additionally gated behind
+ * `document.fonts.ready`, which jsdom does not have, so a `waitForFonts()` would resolve
+ * instantly and prove nothing about the gating it claimed to test. Nothing measures
+ * either: `getLineCount()` / `didItWrap()` would need layout (and `lines` is not a split
+ * this port supports), and the `overflow: hidden` mask with its descender compensation
+ * is a stylesheet, which a test runs none of.
+ *
+ * **What is real is the split, the accessible layer and the alignment.** The string is
+ * carried once in a visually-hidden span and every drawn piece is `aria-hidden`, so
+ * {@link getAccessibleText} is what is heard while {@link getPieces} is what is drawn —
+ * two questions, and a spec asserting only the second would pass on a component that
+ * spells the text out letter by letter. {@link getRenderedText} closes the loop by
+ * putting the pieces and the spaces back together: the split has to be lossless, and
+ * that comparison is what catches a dropped space or a halved surrogate pair. Whether
+ * the hidden copy is genuinely off-screen is CSS, so nothing here claims to know.
+ *
+ * **{@link getTextAlign} is the one input this component reflects**, written straight
+ * onto the host as an inline style — an honest read with no layout involved, unlike
+ * anything else about how the text is arranged. And {@link hasStagedMotion} is the one
+ * fact about the tween worth pinning: that the pieces were taken over, not that anything
+ * is moving.
+ *
+ * Driving the reveal is the spec's job — jsdom supplies neither half of it, and the font
+ * gate defers observation by a microtask:
+ *
+ * ```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 }));
+ * // …and always settle before tearing down: observation is queued off a promise, and
+ * // landing after destroy() registers a teardown on a dead DestroyRef (NG0911).
+ * await fixture.whenStable();
+ * ```
+ *
+ * @example
+ * ```ts
+ * const hero = await loader.getHarness(WrSplitTextHarness.with({ textAlign: 'center' }));
+ *
+ * expect(await hero.getPieces()).toEqual(['H', 'e', 'l', 'l', 'o']);
+ * expect(await hero.getRenderedText()).toBe(await hero.getAccessibleText());
+ * expect(await hero.isTextHidden()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSplitTextHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSplitTextHarnessFilters): HarnessPredicate<WrSplitTextHarness>;
+    private readonly pieces;
+    private readonly spaces;
+    /**
+     * The whole string, as the one readable copy holds it.
+     *
+     * All 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, and {@link getRenderedText} is meant to compare equal to this. A trimmed read
+     * on one side of that comparison would forgive the case it exists to catch.
+     */
+    getAccessibleText(): Promise<string>;
+    /**
+     * The animated pieces, in document order — one per character, or one per word.
+     *
+     * The split the stagger runs over: `['H', 'i']` at the default `splitType="chars"`
+     * against `['Hi', 'there']` for `"words"`, and `['a', '🚀']` for a surrogate pair the
+     * code-point split kept whole instead of halving into two broken glyphs. Whitespace is
+     * not here — it is drawn separately and never staggered, so see {@link getSpaceCount}.
+     */
+    getPieces(): Promise<string[]>;
+    /**
+     * How many pieces the stagger runs over.
+     *
+     * `delay` × this is the real length of the effect, and the only number about the
+     * animation present in the document.
+     */
+    getPieceCount(): Promise<number>;
+    /**
+     * How many whitespace runs sit between the pieces.
+     *
+     * Its own method because whitespace is deliberately excluded from the animated set:
+     * reclassifying 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 intact 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
+     * `H. e. l. l. o.`, and one piece missing `aria-hidden` brings it back — so this is
+     * all-or-nothing, across both element kinds: a 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 also what a
+     * component that stopped rendering its pieces would report.
+     */
+    isTextHidden(): Promise<boolean>;
+    /**
+     * The alignment the host was given, as the component wrote it.
+     *
+     * Off the inline `style` attribute rather than through `getCssValue`, and the
+     * difference is not pedantry: computed style answers for an element nobody wrote to —
+     * with the inherited or user-agent value — so a host that stopped reflecting the input
+     * altogether would keep reporting a plausible `left` or `start`. The attribute is the
+     * fact being asserted.
+     *
+     * `null` means the host carries no alignment at all, which the component never does:
+     * the binding is unconditional and the input defaults to `'center'`.
+     */
+    getTextAlign(): Promise<string | null>;
+    /**
+     * 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` once the reveal has finished: 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, 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 with
+     * text parked at `from.opacity: 0` by a tween 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 glyph invisible, which is a real failure — and one jsdom reproduces every time
+     * `Element.prototype.animate` is missing.
+     */
+    hasStagedMotion(): Promise<boolean>;
+}
+
+export { WrSplitTextHarness };
+export type { WrSplitTextHarnessAlign, WrSplitTextHarnessFilters };

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

@@ -72,6 +72,18 @@ declare class WrSplitText {
     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;