ngwr 10.2.1 → 11.1.0

package/types/ngwr-file-upload-testing.d.ts

@@ -0,0 +1,194 @@
+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-file-upload>` a harness query matches. */
+interface WrFileUploadHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the drop zone's accessible name — a string is an exact match, a RegExp
+     * is tested. This is `dropZoneLabel`, not the visible CTA: the zone carries an
+     * `aria-label`, so the copy inside it is not what identifies the control.
+     */
+    readonly label?: string | RegExp;
+    /** Match only single-file (`false`) or only multi-file (`true`) uploads. */
+    readonly multiple?: boolean;
+    /** Match only enabled (`false`) or only disabled (`true`) uploads. */
+    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-file-upload>`.
+ *
+ * The control a user operates is the `.wr-file-upload__zone` — a `role="button"`
+ * div that is the single tab stop; the `<input type="file">` behind it is
+ * `aria-hidden` and `tabindex="-1"`, and exists only so a click can be forwarded
+ * to it. So focus, drag and disabled state are all read off the zone, plus the
+ * `wr-file-upload--*` host modifiers and the rendered file list. The picker is
+ * touched only where it is the one that carries the state — `accept` and
+ * `multiple` land on it, and {@link selectFiles} has to hand it the files.
+ *
+ * What this component does NOT have, so this harness does not either:
+ * - **no per-file progress or status.** `<wr-file-upload>` picks files; uploading
+ *   them is the app's job, and there is no bar or state to read.
+ * - **no rendered error.** A file refused for its type, its size or the file count
+ *   leaves NOTHING in the DOM — no `aria-invalid`, no message, and a list that
+ *   simply did not grow. The `(rejected)` output is the only channel, so a spec
+ *   asserts on the host's handler. See {@link selectFiles}.
+ * - **no `maxSize` / `maxFiles` readback.** Neither reaches the DOM (unlike
+ *   `accept` and `multiple`, which land on the picker), so they can only be
+ *   observed by offering a file that breaks them.
+ *
+ * Two traps worth knowing before writing assertions. The bound value's SHAPE
+ * follows `multiple` — a bare `File` (or `null`) in single mode, a `File[]` in
+ * multi — and `[showList]="false"` renders no list at all, so {@link getFileNames}
+ * answers `[]` for a component that is holding files. Assert the bound value in
+ * that case.
+ *
+ * @example
+ * ```ts
+ * const upload = await loader.getHarness(WrFileUploadHarness.with({ label: 'Avatar' }));
+ * await upload.selectFiles(new File(['…'], 'me.png', { type: 'image/png' }));
+ *
+ * expect(await upload.getFileNames()).toEqual(['me.png']);
+ * await upload.removeFileNamed('me.png');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrFileUploadHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrFileUploadHarnessFilters): HarnessPredicate<WrFileUploadHarness>;
+    private readonly zone;
+    private readonly picker;
+    private readonly items;
+    private readonly names;
+    private readonly sizes;
+    private readonly removeButtons;
+    /**
+     * The accessible name of the trigger — what a screen-reader user is told this
+     * control is.
+     *
+     * Read from the zone's `aria-label` (the `dropZoneLabel` input) rather than from
+     * the copy inside it, because that label OVERRIDES the copy: the visible "Click
+     * to browse" is not the accessible name, and a harness that returned it would
+     * describe a control nobody is announced.
+     */
+    getLabel(): Promise<string>;
+    /** The visible call-to-action line — the `pickLabel` input. */
+    getPickText(): Promise<string>;
+    /** The visible instruction below the CTA — the `dropLabel` input. */
+    getDropText(): Promise<string>;
+    /** The optional `helperText` line, or `null` when the component was given none. */
+    getHelperText(): Promise<string | null>;
+    /** The `accept` list the picker advertises, or `null` when it accepts anything. */
+    getAccept(): Promise<string | null>;
+    /**
+     * Whether more than one file can be held.
+     *
+     * Read as the DOM PROPERTY: the template writes the attribute as an empty string
+     * (`[attr.multiple]="multiple() ? '' : null"`), and `''` is falsy — an attribute
+     * read would report a multi-file upload as single.
+     */
+    isMultiple(): Promise<boolean>;
+    /**
+     * Whether the control refuses interaction.
+     *
+     * Read from the zone's `aria-disabled`. The host also carries
+     * `wr-file-upload--disabled` and the picker its own `disabled`, but the zone is
+     * a `role="button"` div — `aria-disabled` is the only one of the three that
+     * tells a screen-reader user the trigger is inert.
+     */
+    isDisabled(): Promise<boolean>;
+    /**
+     * Whether the zone is armed for a drop.
+     *
+     * The `wr-file-upload--dragging` host modifier is the whole signal — a drop
+     * target has no ARIA state, so there is nothing better to read here.
+     */
+    isDragging(): Promise<boolean>;
+    /** How many files the list is RENDERING. Zero with `[showList]="false"`, always. */
+    getFileCount(): Promise<number>;
+    /** The file names in the rendered list, in order. */
+    getFileNames(): Promise<string[]>;
+    /**
+     * The file sizes in the rendered list, as SHOWN — `'4.9 KB'`, not `5000`.
+     *
+     * The component formats bytes for display and the byte count never reaches the
+     * DOM, so this is the string a user reads. Assert the `File` itself if the exact
+     * size matters.
+     */
+    getFileSizes(): Promise<string[]>;
+    /**
+     * Hand files to the picker, the way choosing them in the browser dialog does.
+     *
+     * This is the one method that reaches past `TestElement` to the native
+     * `<input type="file">`, and it has to: `TestElement` has no file API, and it
+     * cannot grow one portably, because a `FileList` is not constructible and a
+     * remote WebDriver session cannot be handed a `File` object at all. Everything
+     * else on this harness is environment-agnostic; this needs a DOM behind it
+     * (`TestbedHarnessEnvironment`), and says so with an error when it does not have
+     * one. The input is found through this harness's own locator rather than a
+     * `document` query, so it is still THIS component's picker that gets the files.
+     *
+     * Rejected files are silent: nothing appears in the DOM, so pair this with the
+     * host's `(rejected)` handler when a file is meant to be refused. In single mode
+     * the LAST accepted file wins, which is also how a drop of several files onto a
+     * single-file zone behaves.
+     *
+     * @throws if called with no files, on a disabled upload, or outside a DOM
+     *   environment.
+     */
+    selectFiles(...files: File[]): Promise<void>;
+    /**
+     * Drag files over the zone and drop them.
+     *
+     * Driven by dispatching the drag sequence AT the zone rather than by coordinates:
+     * nothing has layout in a unit test — `getBoundingClientRect` is all zeros — so a
+     * pointer-driven drag would land nowhere. From the component's side it is the
+     * same event either way; it reads `dataTransfer.files` and never a position.
+     *
+     * A disabled upload refuses the drop itself, so this stays a no-op there rather
+     * than throwing the way {@link selectFiles} does — that refusal is the
+     * component's own, and worth asserting.
+     */
+    dropFiles(...files: File[]): Promise<void>;
+    /** Drag over the zone without letting go — arms {@link isDragging}. */
+    dragOver(): Promise<void>;
+    /**
+     * Drag back out of the zone, disarming {@link isDragging}.
+     *
+     * Dispatched at the zone itself on purpose: the component ignores a `dragleave`
+     * whose target is one of the zone's children, because crossing the icon or the
+     * hint text is not leaving the zone.
+     */
+    dragLeave(): Promise<void>;
+    /**
+     * Remove the file at `index` from the rendered list.
+     *
+     * On a disabled upload the remove buttons are disabled too, so this is a no-op
+     * there — assert the result rather than assuming it.
+     */
+    removeFile(index: number): Promise<void>;
+    /** Remove the file with this name. Names come from {@link getFileNames}. */
+    removeFileNamed(name: string): Promise<void>;
+    /** Move keyboard focus to the zone — the control's only tab stop. */
+    focus(): Promise<void>;
+    /** Whether the zone has focus. */
+    isFocused(): Promise<boolean>;
+}
+
+export { WrFileUploadHarness };
+export type { WrFileUploadHarnessFilters };

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-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;