ngwr 11.0.0 → 11.2.0

package/types/ngwr-toast.d.ts

@@ -105,12 +105,21 @@ interface WrToastConfig {
      * @default 5
      */
     readonly maxStack: number;
-    /** Labels rendered in the UI. Keep short — meant to be overridden for i18n. */
+    /**
+     * Labels rendered in the UI. Keep short.
+     *
+     * `null` — the default for every one of them — means "resolve it from the
+     * `ngwr/i18n` catalog", which is what makes a Russian app announce a Russian
+     * close button without configuring the toast at all. They were English
+     * literals here until v11, so the four `toast.*` keys in the shipped catalogs
+     * were never read by anything. A string set here still WINS over the catalog:
+     * this is the consumer's explicit override, not a default.
+     */
     readonly labels: {
-        readonly close: string;
-        readonly copy: string;
-        readonly copied: string;
-        readonly closeAll: string;
+        readonly close: string | null;
+        readonly copy: string | null;
+        readonly copied: string | null;
+        readonly closeAll: string | null;
     };
 }
 

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

@@ -0,0 +1,143 @@
+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 tour popup a harness query matches. */
+interface WrTourHarnessFilters extends BaseHarnessFilters {
+    /** Match the step's heading — a string is an exact match, a RegExp is tested. */
+    readonly title?: string | RegExp;
+    /** Match the step's body copy. */
+    readonly content?: string | RegExp;
+}
+/** Which step of how many, as the popup prints it. */
+interface WrTourProgress {
+    /** One-based, the way the card counts. */
+    readonly current: number;
+    /** How many steps the tour was STARTED with — not how many it will show. */
+    readonly total: 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 the card `WrTour` shows beside the spotlit element.
+ *
+ * `WrTour` is a service with no element of its own, so there is nothing in your
+ * fixture to load: the popup is a portal in the NGWR overlay container, and this
+ * comes from `TestbedHarnessEnvironment.documentRootLoader()`. **One card exists at
+ * a time** — the service tears the whole step down before opening the next — so a
+ * harness held across {@link next} is pointed at a detached element, and a fresh one
+ * has to be fetched per step.
+ *
+ * **The card is rebuilt per step, and that is what makes `getHarnessOrNull` the way
+ * to ask whether a tour is running.** There is no "closed" state to read: the popup,
+ * the overlay and the spotlight all go away together.
+ *
+ * **What "last" means here is not `current === total`.** A step whose target is not
+ * on the page is skipped, so a tour of three steps can show two, and the service
+ * looks AHEAD for a reachable one to decide what the primary button says.
+ * {@link getProgress} reports the printed count, {@link getPrimaryLabel} what the
+ * button actually reads — asserting the second is what catches a card that says
+ * "Next" and then ends the tour.
+ *
+ * @example
+ * ```ts
+ * const rootLoader = TestbedHarnessEnvironment.documentRootLoader(fixture);
+ * tour.start(steps);
+ * await fixture.whenStable();
+ *
+ * const card = await rootLoader.getHarness(WrTourHarness);
+ * expect(await card.getTitle()).toBe('Search');
+ * await card.next();
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrTourHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrTourHarnessFilters): HarnessPredicate<WrTourHarness>;
+    /**
+     * Whether this card is still on the page.
+     *
+     * For a harness you are already HOLDING: moving to another step disposes the
+     * overlay, so this flips to `false` where a fresh `getHarnessOrNull()` answers
+     * with the NEW card rather than with nothing.
+     */
+    isShowing(): Promise<boolean>;
+    /** The step's heading, or `null` for a step given no `title`. */
+    getTitle(): Promise<string | null>;
+    /** The step's body copy. */
+    getContent(): Promise<string>;
+    /** The progress line as printed, e.g. `Step 2 of 4`. */
+    getProgressText(): Promise<string>;
+    /**
+     * The two numbers out of the progress line, or `null` when it does not hold two.
+     *
+     * Parsed from the rendered string rather than asked of the service, because the
+     * service is not something a harness can reach — and the string is what the user
+     * actually gets. A catalog that spells the numbers as words, or reverses them,
+     * makes this `null` instead of a wrong answer; assert {@link getProgressText} in
+     * that case.
+     *
+     * `total` is how many steps the tour was STARTED with, not how many it will show:
+     * a step whose target is missing is skipped and still counted here, which is the
+     * component's own choice and worth knowing before writing an assertion on it.
+     */
+    getProgress(): Promise<WrTourProgress | null>;
+    /**
+     * The name the card announces — its title and the progress line, or just the
+     * progress line for an untitled step.
+     *
+     * The card is an `aria-modal` dialog, so it needs a name; the progress line is
+     * what an untitled step has instead of one.
+     */
+    getAccessibleName(): Promise<string | null>;
+    /** Whether the card announces itself as a modal dialog. */
+    isModal(): Promise<boolean>;
+    /**
+     * Whether the card offers a Back button — which is the same question as "is this
+     * the first step", since the button is only rendered past it.
+     */
+    hasBack(): Promise<boolean>;
+    /**
+     * What the primary button READS — the "next" label, or the "done" one on the last
+     * step the user will see.
+     *
+     * The assertion worth writing, and not derivable from the count: the service looks
+     * ahead for a step whose target is still on the page, so a tour whose last step is
+     * hidden ends one card early and this is the only place that shows.
+     */
+    getPrimaryLabel(): Promise<string>;
+    /** The Skip button's label. */
+    getSkipLabel(): Promise<string>;
+    /** The Back button's label. Throws on the first step, where there is none. */
+    getBackLabel(): Promise<string>;
+    /**
+     * Press the primary button — the next step, or the end of the tour.
+     *
+     * Composed through {@link WrButtonHarness} rather than clicking an element: these
+     * are `wr-btn`s, and that harness already knows how one reports being off.
+     */
+    next(): Promise<void>;
+    /** Press Back. Throws on the first step, where the button is not rendered. */
+    back(): Promise<void>;
+    /** Press Skip — ending the tour without finishing it. */
+    skipTour(): Promise<void>;
+    private primary;
+    private skip;
+    private backButton;
+}
+
+export { WrTourHarness };
+export type { WrTourHarnessFilters, WrTourProgress };

package/types/ngwr-tree.d.ts

@@ -93,6 +93,13 @@ declare class WrTree<TId = string> implements FormValueControl<unknown> {
     readonly openOn: _angular_core.InputSignal<"inline" | "overlay">;
     /** Placeholder shown on the trigger when no node is selected. */
     readonly placeholder: _angular_core.InputSignal<string>;
+    /**
+     * The same fall-through `wr-select` has had all along: an unset placeholder
+     * takes the catalog's `tree.placeholder`, so an overlay trigger with nothing
+     * selected reads "Select…" in the app's language instead of rendering an
+     * empty span. The key shipped in both catalogs and nothing read it.
+     */
+    protected readonly resolvedPlaceholder: _angular_core.Signal<string>;
     /**
      * Accessible name of the overlay trigger. Falls back to the placeholder, then
      * to `select.label` — a `role="combobox"` with nothing selected and no

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

@@ -0,0 +1,201 @@
+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-typewriter>` a harness query matches. */
+interface WrTypewriterHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match what the machine has typed SO FAR — a prefix while it is still going, the
+     * whole sentence once it settles, and the empty string before the first tick. A
+     * string is an exact match, a RegExp is tested.
+     *
+     * There is nothing steadier to match on: the component holds no copy of the phrase
+     * it is working towards, so a filter cannot address a typewriter by what it is
+     * going to say. Pin the clock first — `vi.useFakeTimers` and an explicit advance —
+     * or match a RegExp loose enough to survive whichever frame the query lands on.
+     */
+    readonly text?: string | RegExp;
+    /**
+     * Match typewriters showing a caret (`true`) or none at all (`false`).
+     *
+     * The cursor is REMOVED from the DOM rather than hidden, so this changes mid-run on
+     * anything with `hideCursorWhileTyping` — see `WrTypewriterHarness.hasCursor`. On a
+     * default typewriter it is stable, and it is the one way to tell two otherwise
+     * identical machines apart.
+     */
+    readonly hasCursor?: 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-typewriter>`.
+ *
+ * **The typed string is the entire component, and it is a moving target.**
+ * {@link getText} reads the one text node the machine writes into, which mid-run holds
+ * a FRAGMENT — `'Hell'` on the way to `'Hello'` — and between sentences holds whatever
+ * is left of the previous one. That is not a limitation to work around; it is what the
+ * component renders, and pinning it tick by tick is what proves the machine types one
+ * character at a time, deletes one at a time, pauses, cycles, and stops when told not to
+ * loop. Install fake timers for `setTimeout` / `clearTimeout` only and advance the clock
+ * yourself before every read — awaiting a harness method flushes microtasks, never
+ * timers, so an unadvanced read answers with the previous frame.
+ *
+ * **What is typed is also what is announced, and no second copy exists.** There is
+ * deliberately no `getAccessibleText()` here: the component renders one plain text node
+ * and nothing else, so a screen reader landing mid-word hears the fragment. (Its sibling
+ * `wr-rotating-text` carries a visually-hidden copy of the whole phrase; this one does
+ * not, and inventing a method that implied otherwise would report an accessible layer
+ * that is not there.) The single a11y decision the component does make is the caret, and
+ * {@link isCursorDecorative} is how a spec holds it: without `aria-hidden` every phrase
+ * is announced as `Hello pipe`, and nothing else in the DOM would change.
+ *
+ * **The methods that are missing are missing on purpose.** There is no `isTyping()` or
+ * `getPhase()` — the phase is a private signal that never reaches the document, and its
+ * only proxy, the caret vanishing, exists solely when `hideCursorWhileTyping` is set, so
+ * the method would report "not typing" for the DEFAULT configuration while the machine
+ * types. No `isComplete()` / `isFinished()`: a machine stopped on its last sentence and
+ * one pausing between sentences render the identical string and the identical caret, so
+ * assert the `sentenceComplete` output instead. No `isCursorBlinking()` /
+ * `getCursorOpacity()`: the blink is a `@keyframes` rule from a stylesheet a unit test
+ * never loads, and a mid-animation opacity is a number that means nothing.
+ * No `isVisible()` / `waitForVisible()`: `startOnVisible` hangs off an
+ * `IntersectionObserver` jsdom does not implement, so any answer would be the spec's own
+ * stub echoing back. And no `getTypingSpeed()` / `getDeletingSpeed()` /
+ * `getPauseDuration()` / `getInitialDelay()`: none of them is ever written to the DOM, so
+ * reading them would mean reading the component instance rather than the rendered
+ * control. They are observable exactly once — as the cadence of {@link getText}.
+ *
+ * What DOES survive a test with no layout, besides the string: the caret's presence,
+ * glyph and `aria-hidden`, and the two values the host writes inline —
+ * {@link getColor} and {@link getCursorBlinkDuration}.
+ *
+ * ```ts
+ * // jsdom implements no IntersectionObserver, so `[startOnVisible]` throws on boot.
+ * vi.stubGlobal('IntersectionObserver', StubObserver);
+ * // Fake these two and no more: faking the microtask queue deadlocks `whenStable`,
+ * // which is where the machine boots and where every harness read stabilizes.
+ * vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ * ```
+ *
+ * @example
+ * ```ts
+ * const typewriter = await loader.getHarness(WrTypewriterHarness);
+ *
+ * vi.advanceTimersByTime(0);            // the first tick is scheduled at `initialDelay`
+ * expect(await typewriter.getText()).toBe('H');
+ *
+ * vi.advanceTimersByTime(50);
+ * expect(await typewriter.getText()).toBe('He');
+ * expect(await typewriter.isCursorDecorative()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrTypewriterHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrTypewriterHarnessFilters): HarnessPredicate<WrTypewriterHarness>;
+    private readonly content;
+    private readonly cursor;
+    /**
+     * What has been typed so far — a FRAGMENT while the machine is running.
+     *
+     * This is the whole state machine in one string, and every timing input is observable
+     * only through it: one character per `typingSpeed`, one fewer per `deletingSpeed`, the
+     * `pauseDuration` gap, the swap to the next entry in `[texts]`, and the stop that
+     * `[loop]="false"` puts on the last sentence. `reverseMode` shows up here too, and
+     * `[...await getText()].length` is what proves the reversal counted CODE POINTS: a
+     * `split('')` reversal turns one emoji into two lone surrogates, which is a pair of
+     * broken glyphs on screen and the same character count as a correct answer.
+     *
+     * Untrimmed, because the fragment is what it is: a phrase typed as far as `'Hello '`
+     * genuinely has a trailing space, and trimming would make that frame indistinguishable
+     * from the one before it.
+     *
+     * The empty string is a real state, not a failure — nothing has been typed until the
+     * first tick fires, and a deletion run passes back through it on its way to the next
+     * sentence.
+     */
+    getText(): Promise<string>;
+    /**
+     * Whether a caret is in the document at all.
+     *
+     * The component removes the element rather than hiding it, which makes this two
+     * questions at once. Statically it answers `showCursor`. While the machine runs it
+     * also answers `hideCursorWhileTyping` — and the caret going away is the ONLY evidence
+     * anywhere in the DOM that the component considers itself mid-phase, since the phase
+     * signal is private. Do not read that as `isTyping()`, though: with
+     * `hideCursorWhileTyping` off, which is the default, the caret stays put from the first
+     * character to the last.
+     */
+    hasCursor(): Promise<boolean>;
+    /**
+     * The caret glyph, or `null` when there is no caret.
+     *
+     * `null` rather than `''` on purpose: "no cursor element" and "a cursor element
+     * rendering nothing" are different failures, and an interpolated glyph that stopped
+     * arriving is exactly the second one. Untrimmed, since a caret can legitimately be a
+     * space-padded glyph and `TestElement.text()` would erase it.
+     */
+    getCursorCharacter(): Promise<string | null>;
+    /**
+     * Whether the caret is kept out of the accessibility tree.
+     *
+     * The component's one deliberate a11y decision, and a silent one to lose: drop the
+     * attribute and nothing on screen changes while every phrase starts being announced as
+     * `Hello pipe`.
+     *
+     * Throws when there is no caret. `false` would read as "the caret is announced", which
+     * is the opposite of what an absent caret means — and it is the answer a component that
+     * stopped rendering its cursor entirely would also give. Ask {@link hasCursor} first
+     * when the caret's presence is itself in question.
+     */
+    isCursorDecorative(): Promise<boolean>;
+    /**
+     * The caret's blink half-cycle in seconds, from the custom property the host writes.
+     *
+     * The blink itself is a CSS keyframe and unobservable, so this custom property is the
+     * only channel `[cursorBlinkDuration]` has into it — a binding that quietly stopped
+     * writing it would leave the blink stuck at the stylesheet's default with no other
+     * symptom anywhere.
+     *
+     * Throws rather than answering when the property is missing or unparseable, and says
+     * which it was. The stylesheet's own `0.5s` fallback is never applied in a test that
+     * loads no stylesheets, so an absent property reads as the empty string here — and
+     * `0.5` returned from a `parseFloat('')` would be indistinguishable from the component
+     * writing the default correctly.
+     */
+    getCursorBlinkDuration(): Promise<number>;
+    /**
+     * The colour the host paints the phrase in, exactly as it is written inline.
+     *
+     * `[textColors]` cycles per SENTENCE, so this is how a spec pins that the colour index
+     * follows the sentence index rather than drifting; and with no colours given the
+     * component writes the literal `inherit`, which is a value worth asserting rather than
+     * an absence.
+     *
+     * Read off the `style` ATTRIBUTE rather than through `getCssValue`, which would answer
+     * from a computed style. jsdom hands `inherit` straight back, so `getCssValue` would
+     * agree here and lie in a real browser, where the keyword resolves to whatever rgb
+     * triple the parent happens to carry.
+     *
+     * Throws when the host carries no `color` declaration: the component writes one on
+     * every render, so its absence means the binding is gone, and any string returned in
+     * its place would be a guess at what the page inherits.
+     */
+    getColor(): Promise<string>;
+}
+
+export { WrTypewriterHarness };
+export type { WrTypewriterHarnessFilters };

package/types/ngwr-version.d.ts

@@ -16,7 +16,7 @@ import { InjectionToken } from '@angular/core';
  * Distinct from `Version` exported by `@angular/core`, which reports the
  * loaded Angular runtime version (e.g. `'22.0.0'`), not ngwr's.
  */
-declare const NGWR_VERSION = "11.0.0";
+declare const NGWR_VERSION = "11.2.0";
 
 /**
  * @license

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

@@ -0,0 +1,121 @@
+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-waves>` a harness query matches. */
+interface WrWavesHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match only fields whose canvas has drawn (`true`) or only fields still showing the
+     * stand-in grid (`false`). A wave field has no name of its own, so this is the one
+     * state that tells two of them apart — see `WrWavesHarness.isPainted`, which explains
+     * why the answer is always `false` in a unit test.
+     */
+    readonly painted?: 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-waves>` — a field of lines drifting on perlin noise.
+ *
+ * **The lines themselves are unreadable and always will be.** They are strokes on a 2D
+ * canvas, seeded from the host's measured box and redrawn every frame; a unit test has
+ * no box and no drawing context, so there is nothing to count and nothing to compare.
+ * What the component publishes to the DOM is small, deliberate and worth pinning: the
+ * handover flag {@link isPainted}, the pitch {@link getLineGapPx} that the CSS stand-in
+ * grid draws at before the canvas takes over, and the surface itself.
+ *
+ * Two style reads, taken two different ways, and the difference is the point.
+ * {@link getBackgroundColor} is computed, because nothing but the component declares
+ * that property and the resolved value is what gets painted. {@link getLineGapPx} is
+ * read from the inline declaration, because the stylesheet declares
+ * `--wr-waves-x-gap` too — as the stand-in's own 10px fallback — so a computed read
+ * would answer `10px` on a component that had stopped publishing anything, which is
+ * precisely the break the method exists to catch.
+ *
+ * There is no `getLineCount()`, `getPoints()` or `getCanvasSize()`: the grid is seeded
+ * from `getBoundingClientRect()`, which is 0×0 here, and the numbers that fall out of
+ * that describe nothing. No `getLineColor()` either — it is a canvas `strokeStyle`
+ * resolved from a themed custom property that only a stylesheet can supply. No
+ * `moveMouse()`: the pointer listeners are on `window` and are only installed once a
+ * context exists. And no `isReducedMotion()`, which is the sharpest of them — the
+ * reduced-motion path draws one static grid through the same code and sets the same
+ * flag, so the DOM is identical either way and any answer would be a guess.
+ *
+ * @example
+ * ```ts
+ * const waves = await loader.getHarness(WrWavesHarness);
+ *
+ * expect(await waves.hasCanvas()).toBe(true);
+ * expect(await waves.isDecorative()).toBe(true);
+ * expect(await waves.getLineGapPx()).toBe(10);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrWavesHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrWavesHarnessFilters): HarnessPredicate<WrWavesHarness>;
+    private readonly canvas;
+    /**
+     * Whether the canvas has drawn a frame and retired the CSS stand-in grid.
+     *
+     * **In a unit test this is always `false`, and asserting exactly that is the point.**
+     * jsdom hands back no 2D context, so the component must leave the stand-in up rather
+     * than declare itself painted over a blank box — the flag is set inside the draw for
+     * that reason, not at the end of the boot. A spec that waits for this to turn `true`
+     * waits forever.
+     */
+    isPainted(): Promise<boolean>;
+    /**
+     * The horizontal gap between lines, in pixels, as the component publishes it.
+     *
+     * `[xGap]` feeds the canvas maths, which is invisible here — but it is also published
+     * to the stand-in grid, and that is the half a spec can hold: a field whose stand-in
+     * draws at 10px and whose canvas then arrives at 40px changes pitch under the reader
+     * on hydration, a visible pop that nothing else can catch.
+     */
+    getLineGapPx(): Promise<number>;
+    /**
+     * The fill behind the lines, resolved.
+     *
+     * Comes back as the browser reports it rather than as it was authored — the default
+     * `'transparent'` reads as `'rgba(0, 0, 0, 0)'` and `'#5227ff'` as
+     * `'rgb(82, 39, 255)'` — which is true in jsdom and in a real browser alike, so an
+     * assertion written against it travels. Worth pinning because the alternative
+     * implementation is to fill the canvas instead, and a canvas fill is invisible to
+     * everything until it has painted: the background has to be a real declaration on the
+     * host so the field is the right colour from the prerendered HTML onwards.
+     */
+    getBackgroundColor(): Promise<string>;
+    /**
+     * Whether the field is hidden from assistive tech.
+     *
+     * A background canvas has nothing to announce, so losing this leaves a screen reader
+     * stopping on a nameless graphic in front of the section's actual content.
+     */
+    isDecorative(): Promise<boolean>;
+    /**
+     * Whether the drawing surface is in the markup.
+     *
+     * It is there in every state, including the ones where nothing is ever drawn on it —
+     * prerendered, no 2D context, reduced motion. That is the contract: the element goes
+     * up and the component stops, so the stand-in grid has something to sit behind and
+     * {@link isPainted} has something to answer about.
+     */
+    hasCanvas(): Promise<boolean>;
+}
+
+export { WrWavesHarness };
+export type { WrWavesHarnessFilters };