ngwr 11.1.0 → 12.0.0

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

@@ -0,0 +1,173 @@
+import { BaseHarnessFilters, TestKey, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+import { WrCropHandle } from 'ngwr/image-cropper';
+
+/**
+ * @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-image-cropper>` a harness query matches. */
+interface WrImageCropperHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match croppers holding an image (`false`) or showing the empty state (`true`).
+     * A cropper with a `src` it has not measured yet is NOT empty — see
+     * `WrImageCropperHarness.isReady`.
+     */
+    readonly empty?: 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
+ */
+
+declare const ARROWS: {
+    readonly left: TestKey.LEFT_ARROW;
+    readonly right: TestKey.RIGHT_ARROW;
+    readonly up: TestKey.UP_ARROW;
+    readonly down: TestKey.DOWN_ARROW;
+};
+/** The four directions the crop window's keyboard model understands. */
+type WrCropArrow = keyof typeof ARROWS;
+/** Where the crop window sits over the DISPLAYED image, in CSS pixels. */
+interface WrCropWindowBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Test harness for `<wr-image-cropper>`.
+ *
+ * **This is the smallest honest surface of any harness here, and the reason is worth
+ * reading before you reach for a method that is not on it.** Almost everything the
+ * cropper does is measured: it reads the `<img>`'s rendered box and its
+ * `naturalWidth`, converts between display and source pixels, and moves the crop
+ * window with pointer deltas. jsdom measures nothing — every rect is 0×0 and
+ * `naturalWidth` is 0 — so an image never "loads", the crop UI never renders, and a
+ * synthetic drag divides by zero. There is deliberately no drag method: it would
+ * write `NaN` and report success.
+ *
+ * What a spec CAN do is give the image a box and a natural size itself, then call
+ * {@link dispatchImageLoad} — the two numbers `onImageLoad` reads are the whole
+ * stub, and from there {@link getCropBox} and {@link getHandles} are real answers,
+ * because the component writes the crop window's geometry as inline pixels. The
+ * KEYBOARD path needs the same stub to get the crop UI up, but nothing beyond it:
+ * its step is a constant rather than a pointer delta, so {@link pressArrow} lands
+ * on a number a spec can name.
+ *
+ * ```ts
+ * // In your spec, before dispatching the load:
+ * const img = fixture.nativeElement.querySelector('.wr-image-cropper__image');
+ * img.getBoundingClientRect = () => ({ width: 400, height: 400, x: 0, y: 0 }) as DOMRect;
+ * Object.defineProperty(img, 'naturalWidth', { value: 800 });
+ * Object.defineProperty(img, 'naturalHeight', { value: 800 });
+ * ```
+ *
+ * **There is nothing to click.** The cropper renders no buttons: the result
+ * arrives on the `(cropped)` output, which emits a `Blob` after each drag end or
+ * each run of arrow keys, and a consumer who wants a one-off read calls `toBlob()` /
+ * `toDataUrl()` — or `cropRect()` for the geometry — on the component through a
+ * `viewChild`. An output and three instance members: component API rather than DOM,
+ * so all of it is outside what a harness can reach at all, which is worth knowing
+ * rather than discovering.
+ *
+ * @example
+ * ```ts
+ * const cropper = await loader.getHarness(WrImageCropperHarness);
+ *
+ * expect(await cropper.isEmpty()).toBe(false);
+ * expect(await cropper.isReady()).toBe(false);   // nothing measured yet
+ *
+ * await cropper.dispatchImageLoad();
+ * expect(await cropper.getCropBox()).toEqual({ x: 80, y: 80, width: 240, height: 240 });
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrImageCropperHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrImageCropperHarnessFilters): HarnessPredicate<WrImageCropperHarness>;
+    private readonly image;
+    private readonly cropWindow;
+    /** Whether the cropper has no source at all, and is showing its placeholder. */
+    isEmpty(): Promise<boolean>;
+    /** The placeholder's text, or `null` when there is an image. Comes from the catalog. */
+    getEmptyText(): Promise<string | null>;
+    /**
+     * Whether the crop UI is up.
+     *
+     * Not the same question as {@link isEmpty}: a cropper with a perfectly good `src`
+     * shows nothing but the image until it has been MEASURED, because the window's size
+     * is a fraction of the rendered box. In a browser that happens on load; in a unit
+     * test it happens when the spec stubs the box and calls
+     * {@link dispatchImageLoad}.
+     */
+    isReady(): Promise<boolean>;
+    /**
+     * What the `<img>` is pointing at.
+     *
+     * A `File` or `Blob` source becomes an object URL, so this is `blob:…` for those
+     * and the plain string for a string `src`. Comparing the two is not useful; asking
+     * whether it CHANGED is.
+     */
+    getImageSrc(): Promise<string | null>;
+    /**
+     * Fire the image's `load` event.
+     *
+     * The event, not a real load: jsdom fetches nothing, and the handler reads
+     * `getBoundingClientRect()` and `naturalWidth` off the element. Stub those first —
+     * see this class's docs — or the crop window will still not render and
+     * {@link isReady} will stay `false`, which is exactly what a real cropper does with
+     * a zero-sized image.
+     */
+    dispatchImageLoad(): Promise<void>;
+    /**
+     * Where the crop window sits over the displayed image, in CSS pixels.
+     *
+     * From the inline styles the component writes — a measured box would be 0×0 — and
+     * in DISPLAY pixels, which is not what a consumer receives: `cropRect()` converts
+     * to the image's natural pixels, and that conversion is the component's own contract
+     * rather than something the DOM shows.
+     */
+    getCropBox(): Promise<WrCropWindowBox>;
+    /** The eight resize handles, by their compass suffix. Throws before the crop UI is up. */
+    getHandles(): Promise<WrCropHandle[]>;
+    /** Whether the dimming backdrop with the cut-out is drawn. */
+    hasBackdrop(): Promise<boolean>;
+    /**
+     * Press an arrow key on the crop window — one display pixel, or ten with
+     * `shift`; `alt` resizes from the east / south edge instead of moving.
+     *
+     * Sent to the crop window, where the component listens, so it does not depend on
+     * jsdom having managed to focus anything. `sendKeys` fires keyup as well as
+     * keydown, which is what makes `(cropped)` emit — the component treats a run of
+     * arrows as one gesture, the way a drag is one.
+     */
+    pressArrow(arrow: WrCropArrow, modifiers?: {
+        alt?: boolean;
+        shift?: boolean;
+    }): Promise<void>;
+    /** The crop window's accessible name. Comes from the catalog. */
+    getCropWindowLabel(): Promise<string | null>;
+    /**
+     * The last thing the live region announced — the crop rect in SOURCE pixels,
+     * as `x, y, width × height`.
+     *
+     * Empty until a key has moved the crop: a pointer drag deliberately says nothing
+     * (it would flood the region and the sighted user can see it), and the initial
+     * crop is not news. Two questions, not one — {@link getCropBox} reads the window's
+     * DISPLAY geometry, and a component that moved the box without announcing it
+     * would still pass that one.
+     */
+    getAnnouncement(): Promise<string>;
+    private requireReady;
+}
+
+export { WrImageCropperHarness };
+export type { WrCropArrow, WrCropWindowBox, WrImageCropperHarnessFilters };

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

@@ -30,8 +30,12 @@ interface RectPx {
  * the crop window or any of its eight handles. Optionally lock the crop
  * to a fixed `[aspectRatio]`.
  *
- * `(cropped)` fires after each drag end with a freshly-rendered `Blob`
- * of the cropped region. For one-off reads use `toBlob()` / `toDataUrl()`.
+ * The crop window is also the one tab stop: arrow keys move it, Alt with an
+ * arrow key resizes it, and Shift makes either step ten pixels instead of one.
+ *
+ * `(cropped)` fires after each drag end — or each run of arrow keys — with a
+ * freshly-rendered `Blob` of the cropped region. For one-off reads use
+ * `toBlob()` / `toDataUrl()`.
  *
  * @example
  * ```html
@@ -61,6 +65,16 @@ declare class WrImageCropper {
     readonly cropped: _angular_core.OutputEmitterRef<Blob>;
     protected readonly imgEl: _angular_core.Signal<ElementRef<HTMLImageElement>>;
     /** Resolved object URL for `src` (so File / Blob render in `<img>`). */
+    protected readonly emptyText: _angular_core.Signal<string>;
+    /** Accessible name of the crop window — the component's only tab stop. */
+    protected readonly resolvedWindowLabel: _angular_core.Signal<string>;
+    /** The key model, referenced by the window's `aria-describedby`. */
+    protected readonly resolvedKeyHelp: _angular_core.Signal<string>;
+    /** Id linking the crop window to the help text. Random rather than counted:
+     *  the crop UI only exists after a real image load, so it never prerenders. */
+    protected readonly helpId: string;
+    /** Live-region text — written by the keyboard path only (see `onWindowKeydown`). */
+    protected readonly announcement: _angular_core.WritableSignal<string>;
     protected readonly objectUrl: _angular_core.WritableSignal<string | null>;
     /** Previous object URL we created — kept off-signal so the resolve
      *  effect doesn't depend on its own writes (which would loop). */
@@ -77,6 +91,8 @@ declare class WrImageCropper {
     }>;
     /** Crop rect in display coordinates. */
     protected readonly cropDisplay: _angular_core.WritableSignal<RectPx>;
+    /** Watches the rendered image box — see `watchResize`. */
+    private resizeObserver;
     /** Currently active drag handle. */
     private active;
     private startPointer;
@@ -90,18 +106,68 @@ declare class WrImageCropper {
      *
      * `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.
+     * a test can observe. The other two are reset for coherence: the resize observer
+     * below also writes `display`, and left alone they would resurrect a crop measured
+     * against the previous image (which is why `onResize` refuses to run on a zeroed
+     * `display` — see there).
      */
     private resetGeometry;
     protected onImageLoad(): void;
+    /**
+     * Keep `display` on the box the image is actually rendered at.
+     *
+     * The stylesheet sizes the image responsively — `max-width: 100%`,
+     * `max-height: 70dvh`, `height: auto` — so the single measurement taken in the
+     * `(load)` handler stops being true as soon as the container or the viewport
+     * changes. Everything the user sees and touches is in DISPLAY pixels: the crop
+     * window's inline `left` / `top` / `width` / `height`, the backdrop cut-out, and
+     * the bounds `applyMove` / `applyResize` clamp against. Measured once, a narrowed
+     * window leaves the crop painted past the edge of the image and draggable off it.
+     *
+     * Re-observed per load rather than once, because a new `src` may mount a new
+     * `<img>`; the old observation would then be on a detached element.
+     */
+    private watchResize;
+    /**
+     * Rescale the crop by however much the image did, so the user keeps the region
+     * they picked instead of having it re-centred: `cropRect()` — the source-pixel
+     * value a consumer acts on — comes out the same across the resize.
+     */
+    private onResize;
     /** Compute a sensible initial crop — centered, respecting aspectRatio. */
     private initialCrop;
     protected readonly handles: readonly WrCropHandle[];
     protected onPointerDown(handle: WrCropHandle, event: PointerEvent): void;
     protected onPointerMove(event: PointerEvent): void;
     protected onPointerUp(event: PointerEvent): void;
+    /** Whether a key has moved the crop since the last `keyup`. */
+    private keyboardDirty;
+    /**
+     * The component's only keyboard path. Arrow keys move the crop window; Alt
+     * with an arrow key resizes it from the east / south edge; Shift makes either
+     * one ten display pixels instead of one — the coarse modifier `wr-slider`,
+     * `wr-knob` and `wr-splitter` all use, which is why Alt and not Shift carries
+     * the mode switch here.
+     *
+     * Nothing mirrors under `dir="rtl"`: the image is not flipped and the window
+     * is placed with a physical `left`, so ArrowLeft moves the crop visually left
+     * in both directions.
+     *
+     * Both branches go through `applyMove` / `applyResize`, so the `aspectRatio`
+     * lock, the `minWidth` / `minHeight` floors and the canvas bounds hold for a
+     * keystroke exactly as they do for a drag. Those two measure from `startRect`
+     * rather than from the live rect, so it is re-seeded per keystroke — a 1px
+     * delta against the rect from the first press would make a held arrow stall
+     * after one pixel instead of accumulating.
+     */
+    protected onWindowKeydown(event: KeyboardEvent): void;
+    /**
+     * Emit once per gesture, not once per keystroke. A held arrow repeats its
+     * keydown many times a second and each `emitCropped` renders a canvas and
+     * encodes a Blob; `keyup` fires once when the run ends, which is the keyboard's
+     * equivalent of the `pointerup` the drag path emits on.
+     */
+    protected onWindowKeyup(): void;
     private applyMove;
     private applyResize;
     /** Render the current crop as a Blob. */

package/types/ngwr-input-number-testing.d.ts

@@ -173,13 +173,17 @@ declare class WrInputNumberHarness extends ComponentHarness {
     /** The field's placeholder. */
     getPlaceholder(): Promise<string>;
     /**
-     * The field's accessible name, or `null` when it has none of its own.
+     * The field's `aria-label`, or `null` when it carries none.
      *
      * Read from the native input, not from the host: an `aria-label` on a component
      * element does not reach the control inside it, which is why the component
-     * takes an `ariaLabel` input and forwards it here (falling back to the
-     * placeholder). Inside a `<wr-form-field>` the name comes from the label's
-     * `for`, and `null` here is then correct rather than a missing name.
+     * takes an `ariaLabel` input and forwards it here.
+     *
+     * NOT the accessible name — `null` is the usual answer and usually correct.
+     * Nothing is forwarded unless `[ariaLabel]` is bound: inside a
+     * `<wr-form-field>` the name comes from the label's `for`, and standalone it
+     * comes from the `placeholder` (see {@link getPlaceholder}), neither of which
+     * is an attribute on this element.
      */
     getAriaLabel(): Promise<string | null>;
     /**
@@ -212,12 +216,13 @@ declare class WrInputNumberHarness extends ComponentHarness {
     /**
      * One of the two stepper buttons, BY POSITION — ▲ first, ▼ second.
      *
-     * Not by `aria-label`: those strings ("Increment" / "Decrement") are still
-     * hard-coded English, so keying on them would make this harness the thing that
-     * breaks when they move into the i18n catalog — the same call
-     * `WrTimePanelHarness` makes about its own columns. Order is the layout
-     * contract, and the spec pins it by asserting which way each button moves the
-     * value.
+     * Not by `aria-label`: those strings resolve through the i18n catalog
+     * (`inputNumber.increment` / `.decrement`) and an `[incrementLabel]` /
+     * `[decrementLabel]` binding overrides them, so keying on them would make this
+     * harness answer in whatever locale the app under test is configured for — the
+     * same call `WrTimePanelHarness` makes about its own columns. Order is the
+     * layout contract, and the spec pins it by asserting which way each button
+     * moves the value.
      */
     private stepButton;
 }

package/types/ngwr-input-number.d.ts

@@ -14,7 +14,7 @@ import { WrInputSize } from 'ngwr/input';
  * re-formats with grouping + fixed decimals on blur.
  *
  * Locale comes from Angular's `LOCALE_ID` — input-number intentionally does
- * NOT depend on `ngwr/date-adapter` so it can be used in date-free apps.
+ * NOT depend on `ngwr/date` so it can be used in date-free apps.
  *
  * @example
  * ```html
@@ -73,12 +73,30 @@ declare class WrInputNumber implements FormValueControl<number | null> {
     /** Placeholder shown when the input is empty. */
     readonly placeholder: _angular_core.InputSignal<string>;
     /**
-     * Accessible name for the field. Falls back to the placeholder — inside a
-     * `<wr-form-field>` the projected `wrInput` picks up the label's id and needs
-     * neither, but standalone the text field has no name at all.
+     * Accessible name for the field. Unset, the field is named by whatever labels
+     * it — there is deliberately no fallback here.
+     *
+     * It used to mirror the `placeholder`, and an `aria-label` OUTRANKS a
+     * `<label>` in the accname order: inside a `<wr-form-field label="Quantity">`
+     * the very input that adopts the field's id announced the placeholder ("0")
+     * instead, and a placeholder disappears as soon as the user types. Standalone
+     * nothing was lost by dropping it — an input with no other name already falls
+     * back to its own `placeholder` attribute, which is the name axe's `label`
+     * rule accepts too.
      */
     readonly ariaLabel: _angular_core.InputSignal<string | null>;
     protected readonly resolvedAriaLabel: _angular_core.Signal<string | null>;
+    /** Increment button aria-label. Falls back to `inputNumber.increment`. */
+    readonly incrementLabel: _angular_core.InputSignal<string | null>;
+    /** Decrement button aria-label. Falls back to `inputNumber.decrement`. */
+    readonly decrementLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * The steppers are icon-only buttons, so these ARE their accessible names.
+     * They were hard-coded English while the catalog carried the keys for them
+     * unread — a Russian app announced "Increment".
+     */
+    protected readonly resolvedIncrement: _angular_core.Signal<string>;
+    protected readonly resolvedDecrement: _angular_core.Signal<string>;
     /** Disable interaction. @default false */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
     /** Read-only — values cannot be changed (steppers + typing disabled). @default false */
@@ -97,6 +115,27 @@ declare class WrInputNumber implements FormValueControl<number | null> {
     protected readonly atMin: _angular_core.Signal<boolean>;
     protected readonly atMax: _angular_core.Signal<boolean>;
     protected readonly classes: _angular_core.Signal<string>;
+    /**
+     * Fraction digits the stepper rounds its arithmetic to when `decimals` says
+     * nothing. High enough to leave a real value alone, low enough to erase the
+     * binary-float tail that repeated stepping accumulates.
+     */
+    private static readonly STEP_PRECISION;
+    /**
+     * Above this, the anti-drift round is skipped — it would MANUFACTURE drift.
+     *
+     * `round(v, 10)` is `Math.round((v + EPSILON) * 1e10) / 1e10`, and the scale
+     * factor is only exact while `v * 1e10` stays inside 2^53, i.e. |v| under
+     * about 900,720. In practice the round-trip still recovers up to ~9.2e8 and
+     * then breaks: `round(1000000001, 10)` is `1000000000.9999999`, and since
+     * `format` prints up to 20 fraction digits that tail reaches the screen —
+     * and compounds, because the next press starts from it. Integer stepping at
+     * that magnitude is exact in IEEE754 and needed no help; the only thing this
+     * rounding exists to defend is `0.1 + 0.1 + 0.1`.
+     */
+    private static readonly SAFE_ROUND_MAGNITUDE;
+    /** Steps finer than this would be rounded away by {@link STEP_PRECISION}. */
+    private static readonly SAFE_ROUND_STEP;
     constructor();
     protected onInput(event: Event): void;
     protected onFocus(): void;
@@ -112,7 +151,7 @@ declare class WrInputNumber implements FormValueControl<number | null> {
     /** Format a value using `Intl.NumberFormat` for the active locale. */
     private format;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrInputNumber, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrInputNumber, "wr-input-number", never, { "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "decimals": { "alias": "decimals"; "required": false; "isSignal": true; }; "showSteppers": { "alias": "showSteppers"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "prefix": { "alias": "prefix"; "required": false; "isSignal": true; }; "suffix": { "alias": "suffix"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrInputNumber, "wr-input-number", never, { "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "decimals": { "alias": "decimals"; "required": false; "isSignal": true; }; "showSteppers": { "alias": "showSteppers"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "prefix": { "alias": "prefix"; "required": false; "isSignal": true; }; "suffix": { "alias": "suffix"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "incrementLabel": { "alias": "incrementLabel"; "required": false; "isSignal": true; }; "decrementLabel": { "alias": "decrementLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
 }
 
 export { WrInputNumber };

package/types/ngwr-input-otp-testing.d.ts

@@ -54,11 +54,11 @@ interface WrInputOtpHarnessFilters extends BaseHarnessFilters {
  * single character.
  *
  * A box is more than the string it shows: it carries its own accessible name
- * (`Digit 3`), its own emptiness, its own masking, and it is the thing that
- * either has focus or does not. The root harness answers the control's
- * questions (the assembled code, which index is focused); this one answers the
- * box's, so a spec can hold on to "the box that has focus" instead of zipping
- * four parallel arrays by index.
+ * (`Digit 3` on a numeric strip, `Character 3` on the others), its own
+ * emptiness, its own masking, and it is the thing that either has focus or does
+ * not. The root harness answers the control's questions (the assembled code,
+ * which index is focused); this one answers the box's, so a spec can hold on to
+ * "the box that has focus" instead of zipping four parallel arrays by index.
  *
  * @example
  * ```ts
@@ -93,11 +93,17 @@ declare class WrInputOtpBoxHarness extends ComponentHarness {
     /** Whether the box is still waiting for a character. */
     isEmpty(): Promise<boolean>;
     /**
-     * The box's accessible name — `Digit 1`, `Digit 2`, …
+     * The box's accessible name — `Digit 1`, `Digit 2`, … on a numeric strip.
      *
      * This is the whole of a box's identity for a screen-reader user: the boxes
      * carry no visible label and no position in an `aria-*` set, so the name is
      * how someone knows which one they are in.
+     *
+     * The word depends on `mode`, so an assertion has to follow it: the
+     * `alphanumeric` and `text` modes accept letters, and the component names
+     * their boxes `Character 1`, `Character 2`, … rather than call an `A` a digit.
+     * Both come from the `inputOtp.digit` / `inputOtp.character` catalog entries,
+     * so a localized app answers here in its own language.
      */
     getLabel(): Promise<string | null>;
     /** Whether the box hides what was typed, like a password field. */

package/types/ngwr-input-otp.d.ts

@@ -42,6 +42,9 @@ type WrInputOtpSize = 'sm' | 'md' | 'lg';
  */
 declare class WrInputOtp implements FormValueControl<string> {
     private readonly dir;
+    /** Accessible name of the whole strip. Falls back to `inputOtp.label`. */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly resolvedAriaLabel: _angular_core.Signal<string>;
     /** Number of cells to render. Clamped to `[1, 20]`. @default 6 */
     readonly length: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Character set per cell. @default 'numeric' */
@@ -81,6 +84,8 @@ declare class WrInputOtp implements FormValueControl<string> {
     protected readonly classes: _angular_core.Signal<string>;
     protected readonly cellType: _angular_core.Signal<"text" | "password">;
     protected readonly cellInputMode: _angular_core.Signal<"numeric" | "text">;
+    private readonly digitLabel;
+    private readonly characterLabel;
     protected readonly cellRefs: _angular_core.Signal<readonly ElementRef<HTMLInputElement>[]>;
     constructor();
     protected onInput(event: Event, index: number): void;
@@ -88,6 +93,15 @@ declare class WrInputOtp implements FormValueControl<string> {
     protected onPaste(event: ClipboardEvent): void;
     protected onBlur(): void;
     protected trackIndex(index: number): number;
+    /**
+     * A box's accessible name. It projects no text and carries no label of its own,
+     * so this string IS the name a screen reader reads for it.
+     *
+     * Keyed off `mode`, not fixed: `sanitiseChar` passes any letter through in
+     * `alphanumeric` and `text`, so the old literal announced "Digit 3" over a box
+     * holding `A` — wrong in a way translating it would not have fixed.
+     */
+    protected cellLabel(index: number): string;
     private update;
     private emitChange;
     private focusCell;
@@ -102,7 +116,7 @@ declare class WrInputOtp implements FormValueControl<string> {
      */
     private inlineKey;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrInputOtp, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrInputOtp, "wr-input-otp", never, { "length": { "alias": "length"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "mask": { "alias": "mask"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "completed": "completed"; "touch": "touch"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrInputOtp, "wr-input-otp", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "length": { "alias": "length"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "mask": { "alias": "mask"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "completed": "completed"; "touch": "touch"; }, never, never, true, never>;
 }
 
 export { WrInputOtp };

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

@@ -0,0 +1,150 @@
+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-knob>` a harness query matches. */
+interface WrKnobHarnessFilters extends BaseHarnessFilters {
+    /** Match the dial's accessible name — a string is an exact match, a RegExp is tested. */
+    readonly label?: string | RegExp;
+    /** Match the current value, as `aria-valuenow` reports it. */
+    readonly value?: number;
+    /** Match only enabled (`false`) or only disabled (`true`) dials. */
+    readonly disabled?: boolean;
+    /** Match only writable (`false`) or only read-only (`true`) dials. */
+    readonly readonly?: 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
+ */
+
+/** The two arrow keys that raise the value, and the two that lower it. */
+type Arrow = 'left' | 'right' | 'up' | 'down';
+/**
+ * Test harness for `<wr-knob>` — the radial dial.
+ *
+ * **Driven by the keyboard, and the drag is not merely unsupported.** Turning the
+ * dial with a pointer takes `getBoundingClientRect()`, measures the angle from the
+ * centre to the cursor, and maps it onto a 270° arc. jsdom lays nothing out, so the
+ * centre is `(0, 0)` and every synthetic gesture writes the same corner of the arc
+ * whatever coordinates it is given — a `turnTo()` built on one would pass while
+ * proving nothing. The arrows reach every value on the grid and are the accessible
+ * path anyway.
+ *
+ * **Two questions about the value, not one.** {@link getValue} is the number
+ * `aria-valuenow` carries; {@link getDisplayValue} is the string in the middle of the
+ * dial, which the `suffix` input can make `"50%"` while the announced value stays
+ * `50`. They are separate methods because they can disagree, and because
+ * `showValue` can remove the text entirely without touching the value.
+ *
+ * @example
+ * ```ts
+ * const knob = await loader.getHarness(WrKnobHarness);
+ *
+ * await knob.setValue(60);
+ * expect(await knob.getValue()).toBe(60);
+ * expect(await knob.getDisplayValue()).toBe('60%');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrKnobHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrKnobHarnessFilters): HarnessPredicate<WrKnobHarness>;
+    private readonly surface;
+    /** The value the dial announces, from `aria-valuenow`. */
+    getValue(): Promise<number>;
+    /** The bottom of the range, from `aria-valuemin`. */
+    getMin(): Promise<number>;
+    /** The top of the range, from `aria-valuemax`. */
+    getMax(): Promise<number>;
+    /**
+     * The text printed in the middle of the dial, suffix included, or `null` when the
+     * knob was built with `[showValue]="false"`.
+     *
+     * Not the same question as {@link getValue}: with a `suffix` the two disagree by
+     * design, and a screen reader is told the bare number — the component publishes no
+     * `aria-valuetext`, so `50` is what gets announced for a dial that reads `50%`.
+     */
+    getDisplayValue(): Promise<string | null>;
+    /** The suffix alone, or `null` when there is none (or no value text at all). */
+    getSuffix(): Promise<string | null>;
+    /** The dial's accessible name — `role="slider"` needs one. */
+    getLabel(): Promise<string | null>;
+    /** Whether the dial is disabled, from `aria-disabled`. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the dial is read-only, from `aria-readonly`. */
+    isReadonly(): Promise<boolean>;
+    /**
+     * Whether the dial is a tab stop.
+     *
+     * The component drops it out of the tab order for BOTH disabled and read-only,
+     * which is worth knowing: a read-only slider that a keyboard user cannot reach is
+     * also one they cannot read, and this is the method that says so.
+     */
+    isFocusable(): Promise<boolean>;
+    /** Move keyboard focus to the dial. */
+    focus(): Promise<void>;
+    /** Whether the dial currently holds focus. */
+    isFocused(): Promise<boolean>;
+    /** Blur the dial — which is what emits `touch` for a knob moved with the keyboard. */
+    blur(): Promise<void>;
+    /**
+     * Press one arrow key.
+     *
+     * Right and Up raise the value, Left and Down lower it — all four are live on this
+     * component, which has one axis and no mirroring to do. `shift` multiplies the step
+     * by ten.
+     */
+    pressArrow(arrow: Arrow, options?: {
+        shift?: boolean;
+    }): Promise<void>;
+    /** Press Home — the bottom of the range. */
+    pressHome(): Promise<void>;
+    /**
+     * Press End — the top of the range, or the last value ON the grid below it: a range
+     * that is not a whole number of steps cannot reach its own maximum.
+     */
+    pressEnd(): Promise<void>;
+    /**
+     * Walk the dial to a value with the arrow keys, and assert it landed there.
+     *
+     * It measures the step as it goes rather than being told it — `step` is an input
+     * with no DOM presence, and the value can arrive off the grid, since an external
+     * write is clamped but never snapped. So the first press may move by less than a
+     * step (it snaps onto the grid) and the walk adapts, which also means the ten-step
+     * hops only start once a real step has been seen.
+     *
+     * Throws rather than half-arriving, and the two reasons read differently: a target
+     * outside `[min, max]` is refused before anything moves, while a target BETWEEN two
+     * grid points is only discovered by overshooting it, and says where it landed. A
+     * dial that will not move at all — disabled, read-only — is the third.
+     */
+    setValue(target: number): Promise<void>;
+    /**
+     * Where the handle dot sits, in the SVG's own 100×100 viewBox units.
+     *
+     * The dial's whole visual state is an arc path and this dot, and neither can be
+     * measured in a unit test — but the dot's centre is written as plain `cx` / `cy`
+     * attributes, so it reads with no layout at all. That makes it the evidence that
+     * the drawing followed the value: at `min` the handle is at the 7 o'clock end of
+     * the arc, at `max` the 5 o'clock end.
+     */
+    getHandlePosition(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    private numeric;
+}
+
+export { WrKnobHarness };
+export type { WrKnobHarnessFilters };