ngwr 11.0.0 → 11.2.0

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;

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

@@ -0,0 +1,174 @@
+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-splitter>` a harness query matches. */
+interface WrSplitterHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the splitter's own axis — `horizontal` for panes side by side. Note that
+     * this is the COMPONENT's word, which is the opposite of what the divider
+     * announces; see `WrSplitterHarness.getOrientation`.
+     */
+    readonly orientation?: 'horizontal' | 'vertical';
+    /** Match the divider's accessible name, an exact string or a RegExp. */
+    readonly dividerLabel?: string | RegExp;
+    /** Match only enabled (`false`) or only disabled (`true`) splitters. */
+    readonly disabled?: boolean;
+}
+/** The share of the splitter each pane is asking for, in percent. */
+interface WrSplitterPaneSizes {
+    /** The start pane's `flex-basis` — the same number as the divider's position. */
+    readonly start: number;
+    /** The end pane's `flex-basis` — the remainder. */
+    readonly end: 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
+ */
+
+/** The four arrow keys, by the direction a user would say out loud. */
+type Arrow = 'left' | 'right' | 'up' | 'down';
+/**
+ * Test harness for `<wr-splitter>` — two panes and the divider between them.
+ *
+ * **Everything here is the keyboard, and that is not a workaround.** The divider is
+ * dragged with a pointer in a browser, but the drag reads
+ * `getBoundingClientRect()` and turns a client coordinate into a percentage; jsdom
+ * lays nothing out, so every rect is 0×0 and a synthetic drag writes `NaN` into the
+ * position. The arrow keys reach the same state, are the accessible path anyway, and
+ * are what the WAI-ARIA separator pattern is judged on.
+ *
+ * **Two words for the axis, and they are opposites.** The component's
+ * `orientation="horizontal"` means the panes sit side by side, which needs a
+ * VERTICAL divider — so that is what `aria-orientation` says. {@link getOrientation}
+ * answers the component's word and {@link getDividerOrientation} the divider's; both
+ * are here because a spec that conflated them would look right and assert nothing.
+ *
+ * **Arrows follow the VISUAL axis.** Under `dir="rtl"` the start pane is the one on
+ * the right, so ArrowRight SHRINKS the position. {@link pressArrow} takes the key a
+ * user presses rather than a semantic direction, which is the only way a spec can
+ * pin that mirroring; {@link setPosition} walks with whichever key currently grows
+ * the number, and reports where it landed.
+ *
+ * @example
+ * ```ts
+ * const splitter = await loader.getHarness(WrSplitterHarness);
+ *
+ * expect(await splitter.getPosition()).toBe(50);
+ * await splitter.setPosition(70);
+ * expect(await splitter.getPaneSizes()).toEqual({ start: 70, end: 30 });
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSplitterHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSplitterHarnessFilters): HarnessPredicate<WrSplitterHarness>;
+    private readonly divider;
+    /**
+     * The splitter's own axis: `horizontal` when the panes sit side by side.
+     *
+     * Read from the host modifier rather than from `aria-orientation`, which says the
+     * opposite thing about the same layout — see {@link getDividerOrientation}.
+     */
+    getOrientation(): Promise<'horizontal' | 'vertical'>;
+    /**
+     * What the divider announces — the INVERSE of {@link getOrientation}, and correct:
+     * a separator's orientation is the line it draws, not the axis it travels along.
+     */
+    getDividerOrientation(): Promise<string | null>;
+    /** The divider's position as a percentage, from `aria-valuenow`. */
+    getPosition(): Promise<number>;
+    /** The lowest position the divider will accept, from `aria-valuemin`. */
+    getMinPosition(): Promise<number>;
+    /** The highest position the divider will accept, from `aria-valuemax`. */
+    getMaxPosition(): Promise<number>;
+    /**
+     * What each pane is asking for, in percent, from the `flex-basis` the component
+     * writes inline.
+     *
+     * This is the only evidence a spec without layout has that the panes followed the
+     * divider — a measured width is zero for both. They should always sum to 100:
+     * the end pane is `100 - position`, so a pair that does not is a component bug
+     * rather than a rounding artefact.
+     */
+    getPaneSizes(): Promise<WrSplitterPaneSizes>;
+    /** The start pane's projected text, trimmed. */
+    getStartText(): Promise<string>;
+    /** The end pane's projected text, trimmed. */
+    getEndText(): Promise<string>;
+    /** The divider's accessible name — a focusable separator is a widget and needs one. */
+    getDividerLabel(): Promise<string | null>;
+    /**
+     * Whether the splitter refuses to resize.
+     *
+     * From the divider's `aria-disabled`, which is the half a screen reader acts on.
+     * The component also drops the divider out of the tab order and paints a modifier
+     * on the host, and {@link isDividerFocusable} answers the first of those — worth
+     * asking separately, because a divider that is announced as disabled and still a
+     * tab stop is a control the keyboard can reach and not use.
+     */
+    isDisabled(): Promise<boolean>;
+    /** Whether the divider is a tab stop (`tabindex="0"`). */
+    isDividerFocusable(): Promise<boolean>;
+    /** Move keyboard focus to the divider. */
+    focusDivider(): Promise<void>;
+    /** Whether the divider currently holds focus. */
+    isDividerFocused(): Promise<boolean>;
+    /**
+     * Press one arrow key on the divider.
+     *
+     * The key rather than a direction, deliberately: which way the position moves is a
+     * function of the key AND the reading direction, and a `grow()` / `shrink()` pair
+     * would hide exactly the behaviour worth asserting. An arrow off the splitter's own
+     * axis does nothing at all — the horizontal splitter ignores Up and Down.
+     *
+     * `shift` is the coarse step: 10 instead of 1.
+     */
+    pressArrow(arrow: Arrow, options?: {
+        shift?: boolean;
+    }): Promise<void>;
+    /** Press Home — jumping to `minPosition`, whatever the reading direction. */
+    pressHome(): Promise<void>;
+    /** Press End — jumping to `maxPosition`. Semantic, so it never mirrors under RTL. */
+    pressEnd(): Promise<void>;
+    /**
+     * Walk the divider to a position with the keyboard, and assert it landed there.
+     *
+     * Ten-unit hops first, then single steps — the same two strides a user has. It
+     * walks rather than assigning, because assigning would prove the harness can write
+     * a signal and nothing about the component: the clamp, the min / max and the
+     * mirroring all live on this path.
+     *
+     * Throws rather than half-arriving. A target outside `[min, max]` is unreachable by
+     * construction, and so is any target the walk cannot hit exactly — the position is a
+     * float that a previous drag may have left mid-step, and whole-unit keys cannot get
+     * off a fractional offset. Both say so, with where it actually stopped.
+     */
+    setPosition(target: number): Promise<void>;
+    /**
+     * Whether ArrowRight is currently the key that GROWS the position — true in LTR,
+     * false in RTL, where the start pane is the one on the right.
+     *
+     * Probed rather than read off `Directionality`, which a harness has no access to:
+     * press, look, and put it back. At the top of the range a growing press is clamped
+     * and would prove nothing, so the probe presses the other way there instead. The
+     * undo is conditional — a press that moved nothing has nothing to undo, and undoing
+     * it anyway would move the divider by one in the direction the probe was testing.
+     */
+    private growsWithRight;
+    private numeric;
+}
+
+export { WrSplitterHarness };
+export type { WrSplitterHarnessFilters, WrSplitterPaneSizes };