ngwr 10.2.0 → 11.0.0

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

@@ -0,0 +1,379 @@
+import { BaseHarnessFilters, ContentContainerComponentHarness, HarnessPredicate, HarnessLoader } 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
+ */
+/**
+ * Where a visible message came from, as far as the DOM can tell.
+ *
+ * - `projected` — a `<wr-form-error key="…">` the consumer wrote. It is its own
+ *   element, so this one IS distinguishable.
+ * - `resolved` — the field rendered it from the copy chain
+ *   (`provideWrFormErrors()` → the `ngwr/i18n` `validation.*` catalog → the
+ *   built-in English sentence). All three links render the same `<div>`, so the
+ *   DOM cannot say which of them answered — compare the TEXT if you need to know.
+ */
+type WrFormFieldErrorSource = 'projected' | 'resolved';
+/** One message a `<wr-form-field>` is currently showing. */
+interface WrFormFieldError {
+    /**
+     * Validator key the message answers, read from `data-key`. `null` for a keyless
+     * `<wr-form-error>`, which always renders.
+     */
+    readonly key: string | null;
+    /** The rendered text. */
+    readonly text: string;
+    /** Whether the consumer wrote this message or the field resolved it. */
+    readonly source: WrFormFieldErrorSource;
+}
+
+/**
+ * @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-form-field>` a harness query matches. */
+interface WrFormFieldHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the label text, with the `*` / `(optional)` markers left out of it — a
+     * string is an exact match, a RegExp is tested. `null` matches a field that
+     * renders no label at all.
+     */
+    readonly label?: string | RegExp | null;
+    /**
+     * Match the hint text. A field showing an error has NO hint in the DOM — the
+     * error block takes its place — so this never matches an invalid field.
+     */
+    readonly hint?: string | RegExp;
+    /** Match only fields marked required (`true`) or not (`false`). */
+    readonly required?: boolean;
+    /** Match only fields currently showing an error (`true`) or not (`false`). */
+    readonly invalid?: boolean;
+    /**
+     * Match a field one of whose VISIBLE messages is this text — a string is an
+     * exact match, a RegExp is tested. Suppressed messages (a projected
+     * `<wr-form-error key>` whose key is not failing) are not considered.
+     */
+    readonly errorText?: string | RegExp;
+}
+/** Narrows which `<wr-form-item>` a harness query matches. */
+interface WrFormItemHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the text of the item's own `<label>` child — a string is an exact
+     * match, a RegExp is tested. The label is the consumer's, not the item's.
+     */
+    readonly label?: string | RegExp;
+    /** Match only items the consumer put in the error state (`true`) or not (`false`). */
+    readonly invalid?: boolean;
+    /** Match an item one of whose `<wr-form-error>` messages is this text. */
+    readonly errorText?: string | RegExp;
+}
+
+/**
+ * @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-form-field>` — the label + control + hint + validation
+ * copy block.
+ *
+ * The field's real job is the COPY CONTRACT, and this harness is built around it.
+ * A message reaches the DOM one of two ways, and they are distinguishable there:
+ *
+ * - a `<wr-form-error key="…">` the consumer wrote, which renders only while that
+ *   key is failing — the others stay in the DOM carrying
+ *   `wr-form-field__error--hidden`, which is why {@link getErrors} filters and
+ *   {@link getSuppressedErrorKeys} exists. A raw `.wr-form-error` query answers
+ *   with the held-back copy too, and reads green on the wrong sentence.
+ * - a message the field RESOLVED for an error no markup claimed:
+ *   `provideWrFormErrors()`, then the `ngwr/i18n` `validation.*` catalog, then a
+ *   built-in English sentence. All three render the identical `<div>`, so
+ *   `source` is `'resolved'` for every one of them — the DOM genuinely cannot say
+ *   which link answered, and this harness does not pretend otherwise.
+ *
+ * Nothing renders at all until the projected control is touched or dirty, so a
+ * spec has to reach that gate first: {@link blurControl} is the shortest way
+ * (blur is what marks a bound control touched), and typing through the control's
+ * own harness is the other.
+ *
+ * The field publishes no `aria-label` anywhere. Its `<label for>` pointing at the
+ * projected control IS the naming story, and a control that does not adopt the
+ * id leaves the field silently unlabelled — {@link isLabelLinkedToControl} is
+ * what catches that. The other half is the reverse wiring: the control reads back
+ * `aria-describedby` and `aria-invalid`, which is the only reason a screen reader
+ * hears the message ({@link getAnnouncedDescription}).
+ *
+ * Harnesses loaded through this one resolve INSIDE the control slot, so the
+ * control's own harness composes without a selector:
+ *
+ * @example
+ * ```ts
+ * const email = await loader.getHarness(WrFormFieldHarness.with({ label: 'Email' }));
+ *
+ * await (await email.getHarness(WrInputHarness)).setValue('nope');
+ * await email.blurControl();
+ *
+ * expect(await email.getErrorTexts()).toEqual(["That isn't a valid email."]);
+ * expect(await email.getAnnouncedDescription()).toBe("That isn't a valid email.");
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrFormFieldHarness extends ContentContainerComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrFormFieldHarnessFilters): HarnessPredicate<WrFormFieldHarness>;
+    /**
+     * The label text, or `null` when the field renders no label.
+     *
+     * The `*` and `(optional)` markers ride INSIDE the `<label>`, so they are
+     * excluded here — otherwise this answers `'Email *'` and every equality
+     * assertion has to know which marker the field happens to carry.
+     *
+     * `null` is not "the consumer forgot": `label=""` renders no `<label>` element
+     * at all, which also means there is nothing naming the control.
+     */
+    getLabel(): Promise<string | null>;
+    /**
+     * Whether the field is marked required.
+     *
+     * Read from the host's `wr-form-field--required` modifier, not from the `*`:
+     * that marker is `aria-hidden="true"` decoration, and it is only rendered when
+     * there is a label to hang it on — the modifier is set either way. Note what
+     * this does NOT mean: the field forwards nothing to the projected control, so
+     * `required` here is the field's own visual state. What announces the constraint
+     * is the forms layer — a `required` rule writes the native `required` attribute
+     * onto the control — and the two are set independently, so a field can carry the
+     * `*` with no validator behind it.
+     */
+    isRequired(): Promise<boolean>;
+    /**
+     * Whether the label carries the `(optional)` marker.
+     *
+     * Read from the marker itself, because — unlike `required` — `optional` sets no
+     * host modifier. It is also the marker a screen reader actually reads: this one
+     * is not `aria-hidden`. `required` wins when both inputs are set, so a required
+     * field is never optional here however it was bound.
+     */
+    isOptional(): Promise<boolean>;
+    /**
+     * The hint text, or `null` when none is showing.
+     *
+     * `null` does not mean the consumer set no hint: the error block takes the
+     * hint's slot outright, so a field with a visible message has no hint in the DOM
+     * at all. Note also that the hint carries no id and is NOT referenced by the
+     * control's `aria-describedby` — see {@link getAnnouncedDescription}.
+     */
+    getHint(): Promise<string | null>;
+    /**
+     * Whether the field is painting the error state.
+     *
+     * The host's `wr-form-field--invalid` modifier — what the user sees. The
+     * screen-reader half lives on the control as `aria-invalid`, and the two are
+     * separate elements rather than two readings of one: {@link isControlInvalid}.
+     */
+    isInvalid(): Promise<boolean>;
+    /**
+     * Every message the field is SHOWING, in DOM order — the consumer's markup
+     * first, then whatever the field resolved for the keys that markup left over.
+     *
+     * Only THIS field's own error block is read — its direct child, holding its
+     * direct children — so a `<wr-form-field>` nested in another one's control slot
+     * contributes nothing to the outer field's answer. Without that anchoring the
+     * outer field reports the inner one's copy as its own, which is the same class
+     * of break as reading a sibling field's messages.
+     */
+    getErrors(): Promise<WrFormFieldError[]>;
+    /** The visible messages as text, in DOM order. */
+    getErrorTexts(): Promise<string[]>;
+    /**
+     * The visible message for one validator key.
+     *
+     * Throws rather than answering `null` when that key has no visible message: the
+     * two reasons are worth failing on and the message names both — the key is not
+     * in error at all, or its copy resolved to nothing.
+     */
+    getErrorText(key: string): Promise<string>;
+    /**
+     * The keys of the projected messages the field is holding BACK — copy that is in
+     * the DOM but hidden because its key is not among the failing ones.
+     *
+     * This is the gating contract seen from outside, and the reason a spec must not
+     * query `.wr-form-error` itself: the suppressed sentences sit right next to the
+     * live one.
+     */
+    getSuppressedErrorKeys(): Promise<string[]>;
+    /**
+     * Whether the field is announcing an error it has no words for: invalid, with an
+     * error block that renders nothing.
+     *
+     * Worth a named check because it is invisible in review — the field still goes
+     * red, and `aria-describedby` still points at the block, so a screen reader is
+     * sent to an empty element. It happens when no link in the copy chain answers
+     * the key (`[autoErrors]="false"` with no markup, or a key nothing has copy for
+     * — Signal Forms reports `minLength`, while the chain only knows Angular's
+     * lowercase `minlength`).
+     */
+    hasEmptyErrorBlock(): Promise<boolean>;
+    /** The id the `<label for>` points at, or `null` when there is no label. */
+    getLabelFor(): Promise<string | null>;
+    /** The `id` the projected control actually answers to, or `null` when it has none. */
+    getControlId(): Promise<string | null>;
+    /**
+     * Whether the `<label for>` resolves to an element inside THIS field's control
+     * slot — the only thing that makes the field nameable.
+     *
+     * Scoped to the slot on purpose: ids are document-global, so a check that went
+     * through `getElementById` would also pass for a label pointing at a DIFFERENT
+     * field's control, and for a control that has been moved out of the field
+     * entirely. The failure this catches is quiet — a projected control that does
+     * not adopt the field's `controlId` (a bare `<input>` with no `[wrInput]`, say)
+     * leaves a `for` naming nothing, the field renders exactly as it always did, and
+     * nothing is labelled.
+     */
+    isLabelLinkedToControl(): Promise<boolean>;
+    /**
+     * The ids the projected control names in `aria-describedby`, in order.
+     *
+     * The field points this at the error block and nothing else — the hint has no
+     * id — so an empty list while a hint is showing is correct rather than a bug.
+     * That is not an oversight to fix from a harness either: `[wrInput]` derives
+     * `aria-invalid` from the same signal, so describing the hint would announce
+     * every hinted field as invalid.
+     */
+    getDescribedByIds(): Promise<string[]>;
+    /**
+     * What a screen reader reads as the control's description: the text of the
+     * elements `aria-describedby` names, joined by a space. `null` when the control
+     * describes nothing.
+     *
+     * `''` is a real answer and the interesting one — the reference resolves to an
+     * element with no text in it, which is {@link hasEmptyErrorBlock}. Ids naming
+     * something outside this field are skipped (a consumer's own description is out
+     * of a field harness's reach); an id naming nothing anywhere throws, because a
+     * dangling reference is the bug this method exists to surface.
+     *
+     * Suppressed copy is excluded explicitly rather than left to CSS: a browser drops
+     * `display: none` subtrees from the accessibility tree, but a unit test loads no
+     * stylesheet at all, so the referenced block's raw `textContent` runs every
+     * held-back sentence together with the live one and this would answer with copy
+     * nobody can read.
+     */
+    getAnnouncedDescription(): Promise<string | null>;
+    /**
+     * Whether the control announces itself invalid.
+     *
+     * `aria-invalid` on the projected control, which is what assistive technology
+     * is told — the field's own red styling is {@link isInvalid}. Both are here
+     * because they live on different elements and travel in opposite directions: the
+     * field renders the message, the control reads back that there is one. A field
+     * that paints red while the control says nothing is a real (and silent) break.
+     */
+    isControlInvalid(): Promise<boolean>;
+    /** Move focus to the projected control. */
+    focusControl(): Promise<void>;
+    /**
+     * Blur the projected control, which is usually how a spec gets any message to
+     * appear at all: a bound control marks itself touched on blur, and the field
+     * renders nothing while the control is untouched AND pristine.
+     */
+    blurControl(): Promise<void>;
+    /** The rendered `<label>`, or `null` when `label` is empty. */
+    private labelElement;
+    /**
+     * The control this field wraps.
+     *
+     * The element the label points at, when that resolves inside the slot — which
+     * covers a control nested inside a component (`<wr-input-number>`'s own
+     * `<input>` adopts the field's id, so the label names it, not the component
+     * element). Otherwise the first native control in the slot, so a field with no
+     * label still answers.
+     */
+    private control;
+    /**
+     * The content loader every `HarnessLoader` method on this class runs through,
+     * scoped to the control slot.
+     *
+     * So `field.getHarness(WrInputHarness)` finds the control this field wraps and
+     * not a sibling field's — the loader is per-instance by construction, which is
+     * what a document-wide query for the same selector would lose.
+     */
+    protected getRootHarnessLoader(): Promise<HarnessLoader>;
+}
+
+/**
+ * @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-form-item>` — the layout-only field row.
+ *
+ * Deliberately a much smaller surface than {@link WrFormFieldHarness}, because
+ * the component is a much smaller thing: it discovers no control, generates no
+ * id, wires no `for` and no `aria-describedby`, and reads no validity. It paints
+ * the error state it is TOLD to paint, via `[hasError]`, and everything else in
+ * it belongs to the consumer — including the `<label>`, which is named here
+ * rather than linked (nothing wires it; the consumer's own `for` is the only
+ * thing that can).
+ *
+ * The one behavioural trap it is worth a harness for: a `<wr-form-error>` inside
+ * a form-item renders UNCONDITIONALLY. `key` has no effect at all — the gating
+ * lives in the surrounding `<wr-form-field>`, and with no field to ask, every
+ * message decides it is the one to show. Markup moved from a field into an item
+ * therefore starts printing every sentence at once, and {@link getErrorTexts}
+ * is what says so.
+ *
+ * @example
+ * ```ts
+ * const item = await loader.getHarness(WrFormItemHarness.with({ label: 'Email' }));
+ *
+ * expect(await item.isInvalid()).toBe(true);
+ * expect(await item.getErrorTexts()).toEqual(['Invalid email']);
+ * await (await item.getHarness(WrInputHarness)).setValue('ada@example.test');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrFormItemHarness extends ContentContainerComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrFormItemHarnessFilters): HarnessPredicate<WrFormItemHarness>;
+    /**
+     * The text of the item's own `<label>` child, or `null` when it has none.
+     *
+     * Direct child only — that is what the item styles (`> label` is what turns red
+     * in the error state), so a label nested deeper is the consumer's own business
+     * and answering with it would describe something the item never touches.
+     */
+    getLabel(): Promise<string | null>;
+    /**
+     * Whether the item is painting the error state.
+     *
+     * The `wr-form-item--error` modifier, which is driven entirely by the
+     * consumer's `[hasError]` — the item runs no validity check of its own, so this
+     * answers what it was told, not what the control thinks.
+     */
+    isInvalid(): Promise<boolean>;
+    /**
+     * Every `<wr-form-error>` in the item, as text, in DOM order.
+     *
+     * All of them: nothing is gated here, `key` or no `key`. Nothing is ever
+     * hidden either, so there is no suppressed-message counterpart to this — see
+     * the class docs.
+     */
+    getErrorTexts(): Promise<string[]>;
+}
+
+export { WrFormFieldHarness, WrFormItemHarness };
+export type { WrFormFieldError, WrFormFieldErrorSource, WrFormFieldHarnessFilters, WrFormItemHarnessFilters };

package/types/ngwr-form.d.ts

@@ -51,6 +51,14 @@ declare class WrFormItem {
 interface WrFormFieldContext {
     /** Id the field's `<label for>` points at. */
     readonly controlId: Signal<string>;
+    /**
+     * The reverse direction, for the one case the paragraph above does not cover: a
+     * projected control that already carries its own `id` keeps it, and the label has
+     * to follow, or `for` names an element that does not exist and the field ends up
+     * with no label at all. Called during the control's construction, so the label's
+     * binding still resolves in the same render pass.
+     */
+    adoptControlId(id: string): void;
     /**
      * Validator keys currently in error, once the control is touched or dirty.
      * Empty when the field is valid or has not been interacted with.
@@ -133,6 +141,15 @@ declare class WrFormField implements WrFormFieldContext {
      * already carries an `id` of its own.
      */
     readonly controlId: _angular_core.InputSignal<string>;
+    private readonly adoptedId;
+    /**
+     * Id the `<label for>` renders. A control that came with its own `id` keeps it, so
+     * the label follows that instead of the generated one — otherwise `for` points at
+     * an element that is not in the document and the field is unlabelled.
+     */
+    protected readonly labelFor: _angular_core.Signal<string>;
+    /** @internal `WrFormFieldContext` — see the token's docs. */
+    adoptControlId(id: string): void;
     /**
      * Projected `NgControl` — used to read touched / dirty / errors.
      *

package/types/ngwr-gauge.d.ts

@@ -16,7 +16,12 @@ declare class WrGauge {
     /** Accessible name — the role needs one. Falls back to `gauge.label`. */
     readonly ariaLabel: _angular_core.InputSignal<string | null>;
     protected readonly resolvedAriaLabel: _angular_core.Signal<string>;
-    readonly value: _angular_core.InputSignal<number>;
+    /**
+     * The reading. Coerced like every other numeric input here — it was the only one
+     * without it, so a NaN reached the arc's `d` as the literal text `NaN`, which is
+     * invalid path geometry and drops the arc.
+     */
+    readonly value: _angular_core.InputSignalWithTransform<number, unknown>;
     readonly min: _angular_core.InputSignalWithTransform<number, unknown>;
     readonly max: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Diameter in CSS pixels. @default 160 */
@@ -31,6 +36,13 @@ declare class WrGauge {
     protected readonly cx = 50;
     protected readonly cy = 50;
     protected readonly radius: _angular_core.Signal<number>;
+    /**
+     * The reading as it can actually be shown. Only `ratio` used to be clamped, so an
+     * over-range value drew a full bar while `aria-valuenow` announced the raw number
+     * against `aria-valuemax` — an invalid state for `role="meter"` — and the printed
+     * text disagreed with the bar as well.
+     */
+    protected readonly displayValue: _angular_core.Signal<number>;
     protected readonly ratio: _angular_core.Signal<number>;
     protected readonly trackPath: _angular_core.Signal<string>;
     protected readonly valuePath: _angular_core.Signal<string>;

package/types/ngwr-hotkey.d.ts

@@ -68,9 +68,11 @@ declare class WrHotkey {
     private readonly doc;
     private readonly zone;
     private readonly platform;
+    private readonly destroyRef;
     private readonly isMac;
     /** Bindings grouped by listener target. */
     private readonly registries;
+    constructor();
     /** Register a binding. */
     bind(spec: WrHotkeySpec, handler: (event: KeyboardEvent) => void, options?: WrHotkeyOptions): WrHotkeyHandle;
     private readonly listeners;

package/types/ngwr-image-cropper.d.ts

@@ -85,6 +85,16 @@ declare class WrImageCropper {
     /** Resolved crop rect in natural (source) pixel coordinates. */
     readonly cropRect: _angular_core.Signal<WrCropRect>;
     constructor();
+    /**
+     * Back to "nothing measured yet", which is also what an absent `src` means.
+     *
+     * `display` is the field that gates everything downstream — the crop UI renders on
+     * `display().w > 0` and `cropRect` returns zeros without it — so it is the only one
+     * a test can observe. The other two are reset for coherence: anything that learns to
+     * set `display` from elsewhere (a resize observer is the obvious candidate for this
+     * component) would otherwise resurrect a crop measured against the previous image.
+     */
+    private resetGeometry;
     protected onImageLoad(): void;
     /** Compute a sensible initial crop — centered, respecting aspectRatio. */
     private initialCrop;