ngwr 10.2.1 → 11.1.0

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

@@ -0,0 +1,291 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+import { WrRatingSize } from 'ngwr/rating';
+
+/**
+ * @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-rating>` a harness query matches. */
+interface WrRatingHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the rating's accessible name — the readable way to tell two ratings on
+     * one page apart, since a rating projects no text of its own. A string is an
+     * exact match, a RegExp is tested.
+     */
+    readonly label?: string | RegExp;
+    /**
+     * Match the value the slider announces. A cleared rating announces `0`, so
+     * `{ value: 0 }` matches both "zero stars" and "no rating yet".
+     */
+    readonly value?: number;
+    /** Match only read-only (`true`) or only editable (`false`) ratings. */
+    readonly readonly?: boolean;
+    /** Match only disabled (`true`) or only enabled (`false`) ratings. */
+    readonly disabled?: boolean;
+}
+/** Narrows which star a harness query matches. */
+interface WrRatingItemHarnessFilters extends BaseHarnessFilters {
+    /** Match the star's fill ratio exactly — `1` for full, `0.5` for a half, `0` for empty. */
+    readonly fill?: number;
+    /** Match only stars that accept the pointer (`true`) — a readonly or disabled rating has none. */
+    readonly interactive?: 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 star of a `<wr-rating>`.
+ *
+ * A star is invisible to a screen reader — the row above it is the `slider` and
+ * owns the whole accessible story — but it carries the state the eye reads: how
+ * far it is filled, whether it is still a click target, and, while the pointer is
+ * over the row, the PREVIEW rather than the committed value. That is the reason
+ * this exists as a harness of its own.
+ *
+ * The fill is read from `--wr-rating-fill`, the per-star custom property the
+ * component sets and the stylesheet clips the filled glyph with — a public token,
+ * and the only place a half star exists in the DOM.
+ *
+ * @example
+ * ```ts
+ * const rating = await loader.getHarness(WrRatingHarness.with({ label: 'Overall' }));
+ * const [, , third] = await rating.getItems();
+ *
+ * expect(await third.isPartiallyFilled()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrRatingItemHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrRatingItemHarnessFilters): HarnessPredicate<WrRatingItemHarness>;
+    /**
+     * How much of this star is painted, `0` to `1`.
+     *
+     * While the pointer is over the rating this is the PREVIEW — the component
+     * paints `hoverValue ?? value`, so a hovered star reads full before anything is
+     * committed. `WrRatingHarness.getValue()` is the committed one.
+     */
+    getFill(): Promise<number>;
+    /** Whether the star is painted whole. */
+    isFilled(): Promise<boolean>;
+    /**
+     * Whether the star is painted part-way — a half star.
+     *
+     * Any fractional value paints one, not only `step="0.5"`: the step governs the
+     * keyboard and the pointer, but a fraction written straight into `value` is only
+     * clamped to `[0, count]`, never snapped — so `[value]="3.5"` half-fills star four
+     * on a whole-star rating.
+     */
+    isPartiallyFilled(): Promise<boolean>;
+    /** Whether the star still takes the pointer — a readonly or disabled rating drops the modifier. */
+    isInteractive(): Promise<boolean>;
+    /**
+     * Click this star, picking it whole — star three sets the value to `3`.
+     *
+     * Clicking the value the rating ALREADY holds clears it instead; that is the
+     * component's toggle-off, not an accident of this harness.
+     *
+     * Needs real layout: the component snaps the value from where the pointer sits
+     * inside the star, so this aims at the star's inline-END edge. In jsdom every
+     * element is 0×0 and a pointer position over one cannot mean anything — this
+     * throws rather than committing the `NaN` such a click computes. Reach for
+     * `WrRatingHarness.setValue()` there, which drives the keyboard.
+     */
+    click(): Promise<void>;
+    /**
+     * Click the leading half of this star — `2.5` on star three.
+     *
+     * On a whole-star rating this is the same as {@link click}: the component snaps
+     * UP to its `step`, so half of star three is still three stars. Carries the same
+     * layout requirement.
+     */
+    clickHalf(): Promise<void>;
+    /**
+     * Move the pointer onto this star, previewing it whole.
+     *
+     * Sends `mousemove` rather than the `TestElement.hover()` pair: the rating
+     * tracks the pointer's x across a star to decide whether it is over the half or
+     * the whole, so `mouseenter` alone tells it nothing and leaves the preview
+     * unchanged. `WrRatingHarness.unhover()` ends it. Carries the same layout
+     * requirement as {@link click}.
+     */
+    hover(): Promise<void>;
+    /**
+     * The x, relative to the star's own box, that lands on its inline-END edge —
+     * the far side of the star, where the rating reads a whole one.
+     *
+     * The component measures the pointer from the star's inline-START edge, which
+     * is the right one once `dir="rtl"` mirrors the row; aiming at the physical
+     * right edge there reads ratio 0 and picks one star FEWER. So the side is asked
+     * for rather than assumed: `direction` is a computed style, which the harness
+     * can read in every environment — jsdom included, where it inherits from an
+     * ancestor `dir` attribute like any other browser.
+     */
+    private inlineEndX;
+    /** The star's box, or a failure that names the reason it has none. */
+    private box;
+}
+
+/**
+ * @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-rating>` — the root of a two-class family, since a star
+ * carries state of its own: {@link WrRatingItemHarness}.
+ *
+ * The stars are decoration. Everything a screen reader is told lives on the
+ * `.wr-rating__row` inside them, which is the `slider`: `aria-valuenow` is the
+ * committed value, `aria-valuemax` the top of the range, and the row — not the
+ * host — is the tab stop. So this harness reads the row and, for writes, drives
+ * its KEYBOARD: arrows step by the rating's own `step`, `Home` / `End` jump to
+ * the ends, `Delete` clears. That is the accessible path, and it is the only one a
+ * unit test can take unaided, because the pointer path snaps the value from where
+ * the cursor sits inside a star — which needs layout jsdom does not have, so a
+ * spec that wants it has to stub the star's box (see
+ * {@link WrRatingItemHarness.click}).
+ *
+ * @example
+ * ```ts
+ * const rating = await loader.getHarness(WrRatingHarness.with({ label: 'Overall' }));
+ *
+ * await rating.setValue(4);
+ * expect(await rating.getValue()).toBe(4);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrRatingHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrRatingHarnessFilters): HarnessPredicate<WrRatingHarness>;
+    private readonly row;
+    /**
+     * What the control announces itself as — `slider`.
+     *
+     * Not a `radiogroup`: the value is a number on a continuum with a `step`, the
+     * arrows move it and `Home` / `End` bound it, and that is a slider's contract
+     * rather than a group of one-of-N choices.
+     */
+    getRole(): Promise<string | null>;
+    /**
+     * The rating's accessible name, from `ariaLabel` or the i18n catalogue.
+     *
+     * A rating projects no text, so this is the only name it has — and it sits on
+     * the row, not on the host, because the row is what carries the role.
+     */
+    getLabel(): Promise<string | null>;
+    /**
+     * The committed value, from `aria-valuenow` — what a screen reader is told, not
+     * what is painted, which during a hover is the preview instead.
+     *
+     * A CLEARED rating is announced as `0`, exactly like a rating of zero stars:
+     * `value` is `number | null` and ARIA has no null. So `0` here means "zero or
+     * nothing" — assert the bound model when the difference matters, and see
+     * {@link clear}.
+     */
+    getValue(): Promise<number>;
+    /** The top of the range, from `aria-valuemax` — the `count` of stars. */
+    getMax(): Promise<number>;
+    /** How many stars are painted. Should always agree with {@link getMax}. */
+    getCount(): Promise<number>;
+    /** The stars, left to right. */
+    getItems(filters?: WrRatingItemHarnessFilters): Promise<WrRatingItemHarness[]>;
+    /**
+     * Each star's fill ratio, left to right — `[1, 1, 0.5, 0, 0]` for two and a
+     * half stars out of five.
+     *
+     * This is what the eye sees, so it follows the hover preview while there is one;
+     * {@link getValue} stays on the committed value throughout.
+     */
+    getFills(): Promise<number[]>;
+    /** The control size. `'md'` is the default and paints no modifier of its own. */
+    getSize(): Promise<WrRatingSize>;
+    /**
+     * Whether the rating displays a value it will not let you change.
+     *
+     * Read from `aria-readonly` rather than from the `wr-rating--readonly` class:
+     * both are public, but the attribute is the one a screen reader acts on, and a
+     * rating that looks read-only without saying so is the bug worth catching.
+     */
+    isReadonly(): Promise<boolean>;
+    /** Whether the rating refuses interaction — `aria-disabled`, for the same reason. */
+    isDisabled(): Promise<boolean>;
+    /**
+     * Whether the rating is in the tab order.
+     *
+     * A rating that takes no input takes itself out of it (`tabindex="-1"`), so this
+     * is `false` while readonly or disabled.
+     */
+    isFocusable(): Promise<boolean>;
+    /**
+     * Set the rating, from the keyboard.
+     *
+     * `Home` first, then one `ArrowUp` per step — the step is not in the DOM, so
+     * the only honest way to reach a value is to walk to it and watch where the
+     * rating lands. (The top of the range takes `End` instead of walking there.) A
+     * host counting value changes therefore sees the intermediate ones, which is what
+     * a keyboard user produces too.
+     *
+     * The BLOCK-axis arrow, deliberately: the stars lie on the inline axis, so
+     * `ArrowRight` raises the value in LTR and lowers it under `dir="rtl"`, where
+     * the arrows follow visual order. `ArrowUp` means "more" in both, so a spec
+     * written against this harness reads the same either way.
+     *
+     * Throws rather than settling for a near miss: on a value outside `[0, max]`, on
+     * one the step cannot land on (`2.5` on a whole-star rating), and on a rating
+     * that took no input at all because it is readonly or disabled.
+     *
+     * `setValue(0)` commits ZERO. It is {@link clear} that returns the model to
+     * `null`, and the two are indistinguishable from the DOM.
+     */
+    setValue(value: number): Promise<void>;
+    /**
+     * Clear the rating, the way `Delete` does — the bound value becomes `null`, not
+     * `0`.
+     *
+     * The slider then announces `aria-valuenow="0"` and every star empties, so
+     * {@link getValue} cannot tell you this happened. Assert the model.
+     */
+    clear(): Promise<void>;
+    /**
+     * Bump the rating up by one step — one `ArrowUp`, the arrow that means "more"
+     * in both reading directions (see {@link setValue}).
+     *
+     * The step is the rating's, not this harness's, so this is also how a spec finds
+     * out what it is: clear the rating, step up once, read the value.
+     * Already at the top, this does nothing; the value clamps rather than wrapping.
+     */
+    stepUp(): Promise<void>;
+    /** Bump the rating down by one step — one `ArrowDown`. Clamps at `0`. */
+    stepDown(): Promise<void>;
+    /**
+     * End a hover preview, dropping the stars back to the committed value.
+     *
+     * It lives here rather than on the star because the component listens for
+     * `mouseleave` on the ROW: leaving one star for the next is not leaving the
+     * rating.
+     */
+    unhover(): Promise<void>;
+    /** Move keyboard focus to the rating — onto the row, which is the tab stop. */
+    focus(): Promise<void>;
+    /** Blur the rating. This is what emits `touch`, so a bound field marks itself touched. */
+    blur(): Promise<void>;
+    isFocused(): Promise<boolean>;
+}
+
+export { WrRatingHarness, WrRatingItemHarness };
+export type { WrRatingHarnessFilters, WrRatingItemHarnessFilters };

package/types/ngwr-rating.d.ts

@@ -13,6 +13,10 @@ import { FormValueControl } from '@angular/forms/signals';
  * Keyboard: `←` / `→` bump by `step`, `Home` / `End` jump to 0 / max.
  * Clicking the current value clears it (toggle off).
  *
+ * The stars sit on the inline axis, so under `dir="rtl"` the row is mirrored and
+ * both halves of the input mirror with it: `→` walks toward the low end, and a
+ * click is measured from the star's inline-start (right) edge.
+ *
  * @example
  * ```html
  * <!-- signal forms -->
@@ -55,6 +59,16 @@ declare class WrRating implements FormValueControl<number | null> {
     /** What we actually render — hover wins while hovering. */
     protected readonly displayValue: _angular_core.Signal<number>;
     protected readonly slots: _angular_core.Signal<number[]>;
+    /**
+     * Reading direction, for the two places it changes the answer: the arrows and
+     * the pointer ratio inside a star.
+     *
+     * `optional` because a consumer who never set a direction should not have to
+     * provide anything — `Directionality` is root-provided, so this only resolves
+     * to `null` in a bare `TestBed`, where LTR is the right assumption. Read per
+     * interaction rather than cached, so a runtime flip needs no subscription.
+     */
+    private readonly directionality;
     protected readonly classes: _angular_core.Signal<string>;
     constructor();
     /** Fill ratio for slot `i` in `[0, 1]` — drives the CSS clip width. */
@@ -64,6 +78,15 @@ declare class WrRating implements FormValueControl<number | null> {
     protected onSlotClick(event: MouseEvent, index: number): void;
     protected onKeydown(event: KeyboardEvent): void;
     protected onBlur(): void;
+    /** Whether the row reads right-to-left. */
+    private isRtl;
+    /**
+     * How far into the star the pointer sits, `0` to `1`, measured from its
+     * INLINE-start edge — the left one in LTR, the right one in RTL, where the row
+     * is mirrored. Taken from `rect.left` alone it reads 1 exactly where an RTL
+     * user sees the start of the star, which inverts every half step.
+     */
+    private inlineRatio;
     /** Convert a mouse position over slot `index` to a snapped value. */
     private computeValue;
     private commit;