ngwr 10.2.0 → 11.0.0

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

@@ -0,0 +1,346 @@
+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-stepper>` a harness query matches. */
+interface WrStepperHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match a stepper that renders a step with this label — the readable way to tell
+     * two wizards on one page apart. A string is an exact match, a RegExp is tested.
+     */
+    readonly stepLabel?: string | RegExp;
+    /**
+     * Match the layout direction the stepper was ASKED for. A `responsive` horizontal
+     * stepper still matches `'horizontal'` while it lays itself out vertically — see
+     * `WrStepperHarness.getOrientation()`.
+     */
+    readonly orientation?: 'horizontal' | 'vertical';
+    /** Match only linear (`true`) or only freely navigable (`false`) steppers. */
+    readonly linear?: boolean;
+}
+/** Narrows which step of a `<wr-stepper>` a harness query matches. */
+interface WrStepHarnessFilters extends BaseHarnessFilters {
+    /** Match the step's label — a string is an exact match, a RegExp is tested. */
+    readonly label?: string | RegExp;
+    /** Match the step the wizard is showing — the one header announcing `aria-current="step"`. */
+    readonly active?: boolean;
+    /**
+     * Match steps shown as done. Completion is normally derived (everything before the
+     * active step), but a step's own `completed` input overrides it, so a step AFTER
+     * the active one can match too.
+     */
+    readonly completed?: boolean;
+    /**
+     * Match steps switched off by their own `disabled` input. A step merely locked by
+     * `linear` is not disabled — it is unreachable, which is `reachable: false`.
+     */
+    readonly disabled?: boolean;
+    /**
+     * Match steps whose header accepts a click right now, which is also exactly the
+     * set of headers a Tab press can reach.
+     */
+    readonly reachable?: boolean;
+    /** Match steps flagged `optional` in the header. */
+    readonly optional?: 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 step of a `<wr-stepper>` — the step as the HEADER STRIP
+ * publishes it: its label, its state, and the one control that navigates to it.
+ *
+ * A step is two pieces of DOM in two different places. The `<wr-step>` the consumer
+ * wrote is projected into the stepper's body region; the header this harness hosts on
+ * is generated next to it, in the `<ol>` above. Nothing links the two — no
+ * `aria-controls`, no id on the body — so `WrStepperHarness.getActiveStepText()` is
+ * where the body is read, and this answers what the wizard says about the step.
+ *
+ * Two states that look alike here are deliberately separate, because the component
+ * treats them separately: {@link isDisabled} is the step's own `disabled` input
+ * (switched off, whatever else happens), and {@link isReachable} is whether a click
+ * would land right now — which a `linear` stepper takes away from every step ahead of
+ * the gate without disabling any of them.
+ *
+ * @example
+ * ```ts
+ * const [review] = await stepper.getSteps({ label: 'Review' });
+ *
+ * expect(await review.isOptional()).toBe(true);
+ * expect(await review.isReachable()).toBe(false);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrStepHarness extends ComponentHarness {
+    /**
+     * The header `<li>`, which is the whole step as far as the strip is concerned.
+     *
+     * Not `.wr-stepper__header-button`: the state modifiers (`--active`, `--completed`,
+     * `--disabled`) land on the `<li>`, and the button is a child of it.
+     */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrStepHarnessFilters): HarnessPredicate<WrStepHarness>;
+    private readonly button;
+    /**
+     * The step's label, and only the label.
+     *
+     * The "optional" badge and the description are siblings of the label text inside
+     * the same span, so both are excluded — a step addressed by label should be
+     * addressable whether or not it also carries a description.
+     */
+    getLabel(): Promise<string>;
+    /** The secondary line under the label, or `null` when the step defines none. */
+    getDescription(): Promise<string | null>;
+    /** Whether the header flags the step as optional. */
+    isOptional(): Promise<boolean>;
+    /**
+     * What a screen reader announces for the header button.
+     *
+     * The indicator is excluded because it is `aria-hidden`: the step number and the
+     * completed tick are decoration, deliberately, since the label and
+     * `aria-current="step"` already carry what they would repeat. What IS announced is
+     * the label plus the "optional" badge and the description — so this is the method
+     * that notices when one of those stops being part of the name.
+     */
+    getAccessibleName(): Promise<string>;
+    /**
+     * Whether this is the step the wizard is showing.
+     *
+     * From `aria-current="step"` rather than the `--active` class, because that is the
+     * only place the wizard's position is published to a screen reader, and the two can
+     * only ever disagree by way of a bug.
+     */
+    isActive(): Promise<boolean>;
+    /**
+     * Whether the step is shown as done.
+     *
+     * Read from the `--completed` class, and there is no ARIA alternative to prefer:
+     * completion reaches the page as that class plus a tick glyph that is
+     * `aria-hidden`, so a screen-reader user hears the label and nothing else. The
+     * class is the whole of what exists.
+     *
+     * Completion is derived from the active index — every step before it — unless a
+     * step's own `completed` input overrides it, which is how a `linear` wizard opens
+     * its gate. So a step after the active one can be completed too.
+     */
+    isCompleted(): Promise<boolean>;
+    /**
+     * Whether the step is switched off by its own `disabled` input.
+     *
+     * The `--disabled` class is exactly that input, which is why it is read here rather
+     * than the button's `disabled`: the button is also disabled for a step that is
+     * merely behind a `linear` gate, and those are different facts about the wizard.
+     * See {@link isReachable} for the one about right now.
+     */
+    isDisabled(): Promise<boolean>;
+    /**
+     * Whether a click on this header would move the wizard here.
+     *
+     * Read from the button's `disabled` PROPERTY, because that is the enforcement and
+     * not the paint: the component disables the header for a step its own input
+     * switched off AND for one a `linear` gate has not opened yet. It is also what puts
+     * the header in or out of the tab order — a `disabled` button cannot be focused at
+     * all, so an unreachable step is off the keyboard entirely rather than focusable and
+     * inert the way `aria-disabled` would leave it.
+     */
+    isReachable(): Promise<boolean>;
+    /**
+     * Navigate to this step by clicking its header, the way a user does.
+     *
+     * A click, not a keypress: the header is a real `<button>`, so Enter and Space
+     * activate it through the browser's native activation — behaviour jsdom does not
+     * implement, leaving nothing for a key to drive. A no-arg CDK click needs no
+     * coordinate and no hit test, so the absent layout costs nothing here.
+     *
+     * Throws when the header refuses, rather than clicking and resolving quietly: the
+     * component's guard would drop the click and the wizard would still be showing the
+     * old step three assertions later. Reach for `WrStepperHarness.goTo()` when you
+     * want the failure to name WHICH earlier step is holding the gate shut.
+     */
+    select(): Promise<void>;
+    /** Move keyboard focus to the header. A header that is not reachable cannot take it. */
+    focus(): Promise<void>;
+    /** Whether the header currently has 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-stepper>` — the root of a two-part family with
+ * {@link WrStepHarness}, which is one step of it.
+ *
+ * Steps are addressed by their index or their LABEL, the two things a consumer can
+ * see; there is no key or id on a `<wr-step>` to address it by.
+ *
+ * Navigation here always goes through the HEADER STRIP, because that is the only
+ * control the component renders — a wizard's Next and Back buttons are the
+ * consumer's own, and they call `WrStepper.next()` / `prev()`. That distinction is
+ * not cosmetic: the imperative API does NOT consult `linear`, so it walks straight
+ * past a gate that refuses the equivalent header click. {@link next} and
+ * {@link goTo} therefore refuse exactly where a user would be refused, and a spec
+ * covering the wizard's own buttons should drive those buttons (through their own
+ * harness) instead of these.
+ *
+ * @example
+ * ```ts
+ * const wizard = await loader.getHarness(WrStepperHarness);
+ *
+ * expect(await wizard.getStepLabels()).toEqual(['Account', 'Address', 'Review']);
+ * expect(await wizard.canGoTo(2)).toBe(false);
+ * await wizard.goToLabel('Address');
+ * expect(await wizard.getActiveStepText()).toBe('Address body');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrStepperHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrStepperHarnessFilters): HarnessPredicate<WrStepperHarness>;
+    private readonly headerList;
+    /**
+     * The layout direction the stepper was ASKED for.
+     *
+     * Unusually for this library both values carry a class, so neither is read as the
+     * absence of the other. What the class cannot tell you is how the strip actually
+     * laid itself out: a `responsive` horizontal stepper drops to the vertical layout
+     * when its own box is too narrow, and that reflow is a container query — the class
+     * never changes. No unit test can see the difference in any case, jsdom having no
+     * layout at all; assert the opt-in with {@link isResponsive} instead.
+     */
+    getOrientation(): Promise<'horizontal' | 'vertical'>;
+    /** Whether the stepper locks the steps after the last completed one. */
+    isLinear(): Promise<boolean>;
+    /** Whether the stepper may reflow to the vertical layout in a narrow container. */
+    isResponsive(): Promise<boolean>;
+    /**
+     * The role the header strip announces — `list`.
+     *
+     * An `<ol>` is a list already, so the explicit role looks redundant and is not: the
+     * stylesheet removes the markers, and Safari drops list semantics from a list with
+     * `list-style: none`. Losing it costs the "list, 3 items" a VoiceOver user hears,
+     * which is how they learn how long the wizard is before starting it.
+     */
+    getListRole(): Promise<string | null>;
+    /** The wizard's steps, in order. */
+    getSteps(filters?: WrStepHarnessFilters): Promise<WrStepHarness[]>;
+    /** The label of every step, in order. */
+    getStepLabels(): Promise<string[]>;
+    /**
+     * The index of the step the wizard is showing, from the header announcing
+     * `aria-current="step"`.
+     *
+     * Throws when no header does, which is a state a stepper can genuinely be in: the
+     * `active` model is two-way, `WrStepper.goTo()` clamps an out-of-range index but a
+     * host writing `active` directly does not, and an index past the last step leaves
+     * every header un-current and every step body hidden. A `-1` here would be read as
+     * "the first step" by the next line of a spec.
+     */
+    getActiveIndex(): Promise<number>;
+    /** The label of the step the wizard is showing. Throws when there is no current step. */
+    getActiveLabel(): Promise<string>;
+    /** The labels of the steps shown as done, in order. Derived completion and overrides both. */
+    getCompletedLabels(): Promise<string[]>;
+    /**
+     * The labels of the headers a Tab press can reach, in order.
+     *
+     * A stepper does NOT rove focus: unlike a tab strip, the header list is not one tab
+     * stop with arrow keys inside it — every reachable header is its own stop, and the
+     * component authors no `tabindex` at all. So the question "which step is active" has
+     * two different answers, and this is the other one: the current step is not
+     * necessarily in this list. A step disabled by its own input keeps
+     * `aria-current="step"` while its button drops out of the tab order entirely, and a
+     * `linear` stepper takes every locked header off the keyboard the same way.
+     */
+    getTabStopLabels(): Promise<string[]>;
+    /** The label of the header that currently has focus, or `null` when focus is elsewhere. */
+    getFocusedLabel(): Promise<string | null>;
+    /**
+     * Whether the wizard would let a user navigate to this step right now — the question
+     * a `linear` stepper exists to answer `false` to.
+     *
+     * Throws for an index that is not a step, rather than answering `false`: "you cannot
+     * go there" and "there is no there" are different findings.
+     */
+    canGoTo(index: number): Promise<boolean>;
+    /**
+     * Navigate to the step at `index` by clicking its header.
+     *
+     * Throws when the wizard refuses, naming the cause — the step's own `disabled`, or
+     * the `linear` gate and which earlier step is holding it shut. Silence would be
+     * worse than a failure here: the component drops a click on a locked header without
+     * a sound, so a spec would go on to assert against the step it was already showing.
+     */
+    goTo(index: number): Promise<void>;
+    /**
+     * Navigate to the step with this label — a string matches exactly, a RegExp is
+     * tested. Throws naming the labels that do exist when nothing matches.
+     */
+    goToLabel(label: string | RegExp): Promise<void>;
+    /**
+     * Move to the next step through its header — subject to the same gate a user is.
+     *
+     * In a `linear` wizard that gate is shut until the CURRENT step reports itself
+     * complete (its own `completed` input; derived completion only ever covers steps
+     * before the active one), so this throws there. That is not the harness being
+     * strict: it is the header a user has, and the reason a linear wizard needs its own
+     * Next button, which calls `WrStepper.next()` and is not gated at all.
+     *
+     * Throws on the last step, where the component's own `next()` clamps in silence.
+     */
+    next(): Promise<void>;
+    /**
+     * Move to the previous step through its header. Throws on the first step, where
+     * `WrStepper.prev()` clamps in silence.
+     *
+     * Going back is normally allowed even in a `linear` wizard — every step at or before
+     * the active one is reachable — but a step its own input disabled stays out of
+     * reach in both directions.
+     */
+    previous(): Promise<void>;
+    /**
+     * The text of the step body the wizard is showing.
+     *
+     * Which body shows is CSS-only: every `<wr-step>` renders, and the stepper hides all
+     * but one with `display: none` through the `--active` class. So this reads the class,
+     * and in a unit test it has to — jsdom loads no stylesheet, which makes
+     * `fixture.nativeElement.textContent` the text of ALL the steps at once and any
+     * "is the body showing" assertion built on it meaningless.
+     */
+    getActiveStepText(): Promise<string>;
+    /**
+     * The text of EVERY step body, in order, showing or not.
+     *
+     * The list being complete is the point: a step is hidden by a class rather than
+     * dropped by an `@if`, so it mounts once and keeps its state — a half-filled form on
+     * step 1 is still filled after a trip to step 3. Anything that turned the body into
+     * a conditional block would keep every other assertion in a spec passing and quietly
+     * reset the wizard.
+     */
+    getStepTexts(): Promise<string[]>;
+    /** The step at `index`, or a failure that says how long the wizard is. */
+    private stepAt;
+    /** Why the header at `index` is refusing a click, in the component's own order of causes. */
+    private refusal;
+}
+
+export { WrStepHarness, WrStepperHarness };
+export type { WrStepHarnessFilters, WrStepperHarnessFilters };

package/types/ngwr-storage.d.ts

@@ -37,7 +37,16 @@ declare class WrStorage {
     private readonly engine;
     private readonly config;
     private readonly isBrowser;
-    /** Per-key watchers. Shared so multiple `watch(k)` calls reuse one signal. */
+    /**
+     * Per-key watchers. Shared so multiple `watch(k)` calls reuse one signal.
+     *
+     * The fallback is kept alongside the signal because every refresh has to read
+     * the key the same way `watch` first did. Refreshing without it made `get` and
+     * `watch` disagree about what an ABSENT key means: after a `remove()` the
+     * signal went to `null` while `get(key, fallback)` still answered with the
+     * default, so a consumer watching `'theme'` with a `'light'` fallback got no
+     * theme at all rather than the light one.
+     */
     private readonly watchers;
     private listenerInstalled;
     /** Is `key` present (regardless of value / expiry)? */

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

@@ -0,0 +1,66 @@
+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-switch>` a harness query matches. */
+interface WrSwitchHarnessFilters extends BaseHarnessFilters {
+    /** Match the projected label — a string is an exact match, a RegExp is tested. */
+    readonly label?: string | RegExp;
+    /** Match only switches that are on (`true`) or off (`false`). */
+    readonly on?: boolean;
+    /** Match only enabled (`false`) or only disabled (`true`) switches. */
+    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 `<wr-switch>`.
+ *
+ * The track and thumb are painted `<span>`s; the state lives on a real
+ * `<input type="checkbox" role="switch">` inside the label, and that is what this
+ * reads and clicks. The role is why a switch is not a checkbox to a screen reader,
+ * and {@link isOn} is named after it rather than after `checked` for the same
+ * reason — a spec that reads "the switch is on" says what the user sees.
+ *
+ * @example
+ * ```ts
+ * const dark = await loader.getHarness(WrSwitchHarness.with({ label: 'Dark mode' }));
+ * await dark.turnOn();
+ * expect(await dark.isOn()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSwitchHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSwitchHarnessFilters): HarnessPredicate<WrSwitchHarness>;
+    private readonly input;
+    /** The projected label text, trimmed. */
+    getLabel(): Promise<string>;
+    /** Whether the switch is on. */
+    isOn(): Promise<boolean>;
+    isDisabled(): Promise<boolean>;
+    /** What a screen reader is told this control is — `switch`, not `checkbox`. */
+    getRole(): Promise<string | null>;
+    /** Flip the switch. A disabled switch does not move; assert rather than assume. */
+    toggle(): Promise<void>;
+    turnOn(): Promise<void>;
+    turnOff(): Promise<void>;
+    focus(): Promise<void>;
+    isFocused(): Promise<boolean>;
+}
+
+export { WrSwitchHarness };
+export type { WrSwitchHarnessFilters };

package/types/ngwr-switch.d.ts

@@ -36,8 +36,13 @@ declare class WrSwitch implements FormCheckboxControl {
      * @default false
      */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
-    /** Control size — shares the `--wr-control-*` contract. @default 'md' */
-    readonly size: _angular_core.InputSignal<WrSwitchSize>;
+    /**
+     * Control size — shares the `--wr-control-*` contract. Unset falls back to the
+     * `switch.size` app default from `provideWrConfig()`. @default 'md'
+     */
+    readonly size: _angular_core.InputSignal<WrSwitchSize | null>;
+    /** `size`, then the app config, then `md`. @internal */
+    protected readonly resolvedSize: _angular_core.Signal<"sm" | "md" | "lg">;
     /** On / off state. Bound by `[formField]`, or two-way via `[(checked)]`. */
     readonly checked: _angular_core.ModelSignal<boolean>;
     /** Emitted on blur so a bound field can mark itself touched. */