ngwr 11.0.0 → 11.2.0

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;

package/types/ngwr-border-glow-testing.d.ts

@@ -0,0 +1,219 @@
+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-border-glow>` a harness query matches. */
+interface WrBorderGlowHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the card's projected text — a string is an exact match, a RegExp is tested.
+     * The component names itself nothing, so the content it wraps is the only readable
+     * way to tell two cards on a page apart.
+     */
+    readonly text?: string | RegExp;
+    /**
+     * Match only cards that are mid mount-sweep (`true`) or only cards that are not
+     * (`false`) — see `WrBorderGlowHarness.isSweeping`, where the four-second window
+     * this is true for is explained.
+     */
+    readonly sweeping?: 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-border-glow>` — a card whose border lights up under the cursor.
+ *
+ * **Nearly all of this component is a bag of custom properties written onto the host,
+ * and that is what the harness reads.** The paint itself — the conic mask, the stacked
+ * `box-shadow` halo, the soft-light bloom — lives in the stylesheet, so a unit test can
+ * never see it. What it CAN see is the arithmetic that feeds it, and that is where the
+ * breakages are: the seven-step alpha ramp {@link getGlowAlphaRamp} derives from
+ * `glowIntensity`, the `[0,1,2,0,1,2,1]` palette mapping in {@link getGradientColors}
+ * with its clamp for short palettes, and the pointer maths behind
+ * {@link getPointerAngle} / {@link getEdgeProximity}.
+ *
+ * **Every custom-property getter reads the inline declaration** — see
+ * {@link parseInlineDeclarations} for why a computed read would be a different, and
+ * wrong, question.
+ *
+ * **A colour getter answering `null` means the component has never written that
+ * variable**, which is the contract when the input is unset: the stylesheet's per-theme
+ * default takes over. Note that it does not un-write them either — setting `[glowColor]`
+ * and then putting it back to `null` leaves the last value on the host — so `null` is
+ * "never set", not "not set now".
+ *
+ * There is deliberately no `getGlowOpacity()`, `isGlowVisible()` or `isHovered()`: the
+ * visible strength is a `calc()` in the stylesheet gated behind `:not(:hover)`, and
+ * jsdom loads no stylesheet and matches no `:hover`, so any number would be invented.
+ * There is no measured halo extent either — `.wr-border-glow__edge` is 0×0 in a test,
+ * and {@link getGlowRadius} reads what the component asked for instead. And there is no
+ * `getSweepProgress()` / `waitForSweep()`: the mount sweep is a four-second chain of
+ * `requestAnimationFrame` tweens, so awaiting it either hangs the spec or samples one
+ * frame and reports a value that was never settled. {@link isSweeping} answers the one
+ * durable fact — that the sweep started.
+ *
+ * @example
+ * ```ts
+ * const card = await loader.getHarness(WrBorderGlowHarness.with({ text: /Hover me/ }));
+ *
+ * expect(await card.getBorderRadius()).toBe(28);
+ * expect(await card.getPointerAngle()).toBeNull();   // nothing has pointed at it yet
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrBorderGlowHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrBorderGlowHarnessFilters): HarnessPredicate<WrBorderGlowHarness>;
+    private readonly edge;
+    /** The corner radius the stylesheet is told to round to, in pixels. */
+    getBorderRadius(): Promise<number>;
+    /** How far past the card edge the halo is told to reach, in pixels. */
+    getGlowRadius(): Promise<number>;
+    /**
+     * The width of the lit cone, as a share of the perimeter.
+     *
+     * Unitless by contract — the stylesheet multiplies it — so a `px` creeping in here is
+     * a real regression that leaves the mask with a length where it wants a number.
+     */
+    getConeSpread(): Promise<number>;
+    /** How sharply the halo fades as the cursor leaves an edge; lower is a wider falloff. */
+    getEdgeSensitivity(): Promise<number>;
+    /** Strength of the interior soft-light bloom, again unitless. */
+    getFillOpacity(): Promise<number>;
+    /**
+     * The card fill the author asked for, or `null` when they left it to the theme.
+     *
+     * The distinction is the whole point: an unset `[backgroundColor]` means the surface
+     * token decides, light or dark, and a card that starts declaring its own fill has
+     * stopped following the theme.
+     */
+    getBackgroundColor(): Promise<string | null>;
+    /**
+     * The halo colour at full strength, or `null` when the theme decides.
+     *
+     * Comes back as the `hsl(H deg S% L% / A%)` the component assembled from the bare
+     * `'H S L'` input, so this also pins that assembly. Be aware the parse is forgiving to
+     * a fault: anything that is not three bare numbers — a hex colour, `rgb(…)`, even
+     * `hsl(40deg 80% 80%)` with its units — silently becomes the default amber, so a
+     * plausible-looking value here does not mean the input was understood.
+     */
+    getGlowColor(): Promise<string | null>;
+    /**
+     * The seven halo alphas in percent, brightest first, or `null` when no glow colour
+     * was ever set.
+     *
+     * This is the whole of `[glowIntensity]`: the steps are `[100, 60, 50, 40, 30, 20,
+     * 10]` multiplied by the intensity and clamped at 100, so `0.5` gives
+     * `[50, 30, 25, 20, 15, 10, 5]` and anything above 1 saturates from the top down. The
+     * clamp is one-sided — a negative intensity produces negative percentages, which a
+     * browser drops as invalid declarations and the halo vanishes — so the numbers are
+     * returned as written rather than corrected, which is how a spec can see it.
+     */
+    getGlowAlphaRamp(): Promise<number[] | null>;
+    /**
+     * The seven mesh-gradient colours, in slot order, or `null` when no palette was set.
+     *
+     * The slots do not map one-to-one onto the palette: they take colours
+     * `[0, 1, 2, 0, 1, 2, 1]`, each index clamped to the last entry the palette actually
+     * has. So a two-colour palette repeats the second colour rather than reading past the
+     * end — which is the case worth a spec, since `undefined` in a `radial-gradient()`
+     * kills the whole declaration silently.
+     */
+    getGradientColors(): Promise<string[] | null>;
+    /**
+     * The flat colour behind the mesh, or `null` when no palette was set.
+     *
+     * Always the palette's FIRST entry. Worth its own method because the base slice is the
+     * one that shows where the gradients are transparent, and it drifting to the last
+     * colour changes the card's whole cast without touching a gradient.
+     */
+    getBaseGradientColor(): Promise<string | null>;
+    /**
+     * Where the cursor last sat, in degrees: `0` is straight up and the angle grows
+     * clockwise. `null` until something has pointed at the card.
+     *
+     * `null` is a state of its own rather than a stand-in for zero — the stylesheet's own
+     * default applies until the first pointer arrives, and dead centre legitimately
+     * reports `0`, so a harness that folded the two together could not tell an untouched
+     * card from one being pointed at from the middle.
+     */
+    getPointerAngle(): Promise<number | null>;
+    /**
+     * How close the cursor is to the perimeter: `0` at dead centre, `100` at the edge.
+     * `null` until something has pointed at the card.
+     *
+     * On a diagonal the NEARER axis wins rather than the two averaging, so a cursor level
+     * with the bottom edge reads 100 wherever it is along it.
+     */
+    getEdgeProximity(): Promise<number | null>;
+    /**
+     * Point at the card, in client coordinates.
+     *
+     * **Refuses on a card with no box, which in a unit test is every card.** The component
+     * measures the pointer against its own centre, and with a 0×0 rect that maths
+     * degenerates: the centre is the top-left corner, and `1 / Math.min(0, 0)` pins the
+     * proximity at 100 for every position on the page. Both would come back as confident
+     * numbers describing nothing. Give the host a box first, exactly as the component's own
+     * spec does:
+     *
+     * ```ts
+     * const card = fixture.nativeElement.querySelector('wr-border-glow');
+     * card.getBoundingClientRect = () => ({ left: 0, top: 0, width: 200, height: 100 }) as DOMRect;
+     * ```
+     *
+     * A `pointermove` is dispatched on the host itself, so it needs no hit test and cannot
+     * miss — the coordinates only ever reach the component's own arithmetic.
+     */
+    movePointerTo(clientX: number, clientY: number): Promise<void>;
+    /**
+     * Whether the one-shot mount sweep is running.
+     *
+     * The class is added synchronously when the sweep starts and removed when it ends
+     * about four seconds later, or when the component is torn down — so a spec asserts
+     * that it STARTED, and leaves the angle alone while it does. This is also the
+     * reduced-motion assertion: `[animated]="true"` for someone who asked for less motion
+     * must leave this `false`, and no angle written at all.
+     */
+    isSweeping(): Promise<boolean>;
+    /** Whether the halo layer is in the markup — the element the whole outer glow paints on. */
+    hasHaloLayer(): Promise<boolean>;
+    /**
+     * Whether the decoration stays out of the accessibility tree.
+     *
+     * The halo layer is the component's only decorative NODE — every other layer is a
+     * pseudo-element and so was never in the tree to begin with. It carries no text and no
+     * name, so losing its `aria-hidden` puts an anonymous element between the reader and
+     * the card's content.
+     */
+    isDecorationHiddenFromAssistiveTech(): Promise<boolean>;
+    /**
+     * The projected content's text, trimmed.
+     *
+     * Read from `.wr-border-glow__inner` rather than the host, which is the assertion:
+     * content that lands as a bare host child instead of inside the wrapper renders
+     * underneath the interior bloom, and reading the host would report the same string
+     * either way.
+     */
+    getContentText(): Promise<string>;
+    /** The host's inline declarations — the component's whole written output. */
+    private declarations;
+    /** One inline custom property, or `null` when the component has not written it. */
+    private readVar;
+    /** One inline custom property that is always written, as a number. */
+    private readNumberVar;
+}
+
+export { WrBorderGlowHarness };
+export type { WrBorderGlowHarnessFilters };

package/types/ngwr-calendar-heatmap-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-calendar-heatmap>` a harness query matches. */
+interface WrCalendarHeatmapHarnessFilters extends BaseHarnessFilters {
+    /** Match the grid's accessible name. */
+    readonly ariaLabel?: string | RegExp;
+}
+/** One day square, as its tooltip describes it. */
+interface WrCalendarHeatmapCell {
+    /** The ISO date the square stands for. */
+    readonly iso: string;
+    /** The value as printed in the tooltip. */
+    readonly value: string;
+    /** Which week column it sits in, one-based, as the grid places it. */
+    readonly week: number;
+    /** Which weekday row it sits in, one-based. */
+    readonly day: 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-calendar-heatmap>`.
+ *
+ * **Every square is `aria-hidden`, and that is the design.** The grid is one
+ * `role="img"` with a name; a year of individually announced days would be unusable
+ * with a screen reader. What each square carries instead is a `title` — its ISO date
+ * and value — which is the only text a spec can read, and what
+ * {@link getCells} parses.
+ *
+ * **Four of the seven weekday labels are blank on purpose**: seven do not fit beside
+ * a grid this dense. {@link getWeekdayLabels} returns them as they are, empties
+ * included, rather than filtering — a spec asserting seven entries with four blanks
+ * is pinning the real layout.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrCalendarHeatmapHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrCalendarHeatmapHarnessFilters): HarnessPredicate<WrCalendarHeatmapHarness>;
+    private readonly grid;
+    /** The role the grid announces — `img`, for the whole picture. */
+    getRole(): Promise<string | null>;
+    /** The grid's accessible name — the only name a reader gets. */
+    getAccessibleName(): Promise<string | null>;
+    /** How many day squares were drawn. */
+    getCellCount(): Promise<number>;
+    /**
+     * Every square, from its tooltip and its grid placement.
+     *
+     * The `title` is `"<iso>: <value>"`, which is the component's own format and the
+     * only text on a square — everything else about it is colour.
+     */
+    getCells(): Promise<WrCalendarHeatmapCell[]>;
+    /** The value a given ISO date's square reports, or `null` when that day is not drawn. */
+    getValueFor(iso: string): Promise<string | null>;
+    /** Whether the weekday and month labels are drawn (`showLabels`). */
+    hasLabels(): Promise<boolean>;
+    /** The weekday labels as drawn — seven entries, four of them deliberately empty. */
+    getWeekdayLabels(): Promise<string[]>;
+    /** The month labels along the top, in order. */
+    getMonthLabels(): Promise<string[]>;
+}
+
+export { WrCalendarHeatmapHarness };
+export type { WrCalendarHeatmapCell, WrCalendarHeatmapHarnessFilters };