ngwr 10.2.1 → 11.1.0

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

@@ -0,0 +1,401 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+import { WrSegmentedSize } from 'ngwr/segmented';
+
+/**
+ * @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-segmented>` a harness query matches. */
+interface WrSegmentedHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the control's accessible name — a string is an exact match, a RegExp is
+     * tested. The component ships no label input, so this is whatever the consumer
+     * wired with `aria-label` / `aria-labelledby`, and it is the only thing that
+     * tells two segmented controls on one page apart.
+     */
+    readonly label?: string | RegExp;
+    /** Match only the rendered size — `'md'` matches a control carrying no size modifier. */
+    readonly size?: WrSegmentedSize;
+    /** Match only controls disabled as a whole (`true`) or the rest (`false`). */
+    readonly disabled?: boolean;
+}
+/** Narrows which segment of a `<wr-segmented>` a harness query matches. */
+interface WrSegmentedOptionHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the segment's accessible name — its visible label, or the `aria-label`
+     * standing in for an icon-only one. A string is an exact match, a RegExp is
+     * tested; a segment with no name at all matches neither.
+     *
+     * There is deliberately no `value` filter: the option's `value` never reaches the
+     * DOM — see `WrSegmentedHarness`.
+     */
+    readonly label?: string | RegExp;
+    /** Match only the pressed segment (`true`) or only the others (`false`). */
+    readonly selected?: boolean;
+    /** Match only enabled (`false`) or only disabled (`true`) segments. */
+    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 one segment of a `<wr-segmented>` — an option, not a control.
+ *
+ * A segment is a real `<button type="button">` carrying `aria-pressed`, so it is a
+ * TOGGLE BUTTON to a screen reader: it announces its own pressed state and its own
+ * name, and it is its own tab stop. That is why this exists as a harness of its own,
+ * and why the questions below are worth asking per segment rather than in bulk on
+ * `WrSegmentedHarness` — which is where the SELECTION lives.
+ *
+ * Three name-shaped methods, because a segment has three different names and only
+ * one of them is what a person hears:
+ *
+ * - {@link getText} — the visible label, `null` for an icon-only segment.
+ * - {@link getAccessibleName} — what is announced, `null` when nothing names it.
+ * - {@link getLabel} — the same, but it refuses to answer `null`, so a spec
+ *   addressing segments by label fails where the mistake is rather than three
+ *   lines later.
+ *
+ * @example
+ * ```ts
+ * const segmented = await loader.getHarness(WrSegmentedHarness);
+ * const [, week] = await segmented.getOptions();
+ *
+ * await week.select();
+ * expect(await week.isSelected()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSegmentedOptionHarness extends ComponentHarness {
+    /** The segment is a plain `<button>` — the BEM class is what identifies it. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSegmentedOptionHarnessFilters): HarnessPredicate<WrSegmentedOptionHarness>;
+    private readonly labelText;
+    private readonly icon;
+    /**
+     * The visible label, or `null` for an icon-only segment.
+     *
+     * `null` rather than `''`: the label element is only rendered when the option
+     * carries a `label`, and "no text at all" and "an empty label" are different
+     * mistakes to be looking at.
+     */
+    getText(): Promise<string | null>;
+    /**
+     * The name a screen reader announces for this segment, or `null` when nothing
+     * names it.
+     *
+     * The component's own fallback chain, read back off the page: a labelled segment
+     * is named by its text and carries no `aria-label`; an icon-only one is named by
+     * `aria-label`, which the template fills from the option's `ariaLabel` or — as a
+     * last resort — from its stringified `value`.
+     *
+     * `null` is a finding, not a detail: an icon-only segment whose option supplied
+     * neither an `ariaLabel` nor a stringifiable value is announced as a bare unnamed
+     * button.
+     */
+    getAccessibleName(): Promise<string | null>;
+    /**
+     * The segment's accessible name, for addressing it — and a targeted failure when
+     * it has none.
+     *
+     * {@link getAccessibleName} is the same answer without the refusal; use that one
+     * when `null` is what a spec is checking for.
+     */
+    getLabel(): Promise<string>;
+    /**
+     * Whether this segment is the control's current answer.
+     *
+     * From `aria-pressed`, in preference to the `wr-segmented__option--selected`
+     * class: both are public and they move together, but the class only recolours the
+     * label while the attribute is the entire state a screen reader is given.
+     */
+    isSelected(): Promise<boolean>;
+    /**
+     * Whether the segment refuses selection — for either reason.
+     *
+     * The native `disabled` PROPERTY, which is what actually blocks activation. The
+     * option's own `disabled` and the whole control's land on it identically, and from
+     * outside they are the same thing: this segment cannot be picked. Ask
+     * `WrSegmentedHarness.isDisabled()` for which of the two it was.
+     */
+    isDisabled(): Promise<boolean>;
+    /** Whether the segment renders an icon beside (or instead of) its label. */
+    hasIcon(): Promise<boolean>;
+    /**
+     * The name of the segment's icon, or `null` when it renders none.
+     *
+     * From `data-icon`, which `<wr-icon>` reflects. The glyph itself is markup the
+     * icon registry writes into the element, and an UNREGISTERED name leaves that
+     * empty — so the attribute is the only place the wiring survives, and it is the
+     * one that tells "no icon asked for" from "icon asked for, never registered".
+     */
+    getIconName(): Promise<string | null>;
+    /**
+     * Pick this segment.
+     *
+     * A click, and deliberately not a keypress: activating a `<button>` from the
+     * keyboard is the BROWSER's default action for Enter / Space — the component
+     * implements no key handling of its own — and jsdom implements none of it either,
+     * so there is nothing here for a key to drive. A no-arg CDK click needs no
+     * layout, which is the other half of why this is the drivable path.
+     *
+     * Nothing happens when the segment is already selected (a segmented control has no
+     * untoggle), and nothing happens when it is disabled — but not for the reason the
+     * `pointer-events: none` on a whole disabled control suggests, which is CSS a unit
+     * test never applies. The CDK's own `click()` reads the native `disabled` PROPERTY
+     * and dispatches the mouse sequence WITHOUT the final `click` event, so on a
+     * disabled segment the component's handler is never reached at all (measured: zero
+     * click events). Either way the value does not move and this resolves quietly, so
+     * assert the result rather than assume it, or reach for
+     * `WrSegmentedHarness.select()`, which says which of the two it was.
+     */
+    select(): Promise<void>;
+    /** Move keyboard focus to the segment. Each segment is its own tab stop. */
+    focus(): Promise<void>;
+    /** Take focus off the segment. */
+    blur(): Promise<void>;
+    isFocused(): Promise<boolean>;
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/**
+ * Test harness for `<wr-segmented>` — the root of a two-class family with
+ * {@link WrSegmentedOptionHarness}.
+ *
+ * **What the control actually is**, because it decides everything below: not a
+ * `radiogroup`, not a `tablist` and not native radios. The host is a plain
+ * `role="group"` and each segment is a `<button aria-pressed>` — a row of toggle
+ * buttons over one value. Three consequences a spec has to know about:
+ *
+ * - The selection is `aria-pressed`, on exactly one segment. There is no
+ *   `aria-checked`, no `aria-selected`, and no "2 of 3" position announced.
+ * - **There is no roving tab stop.** The component authors no `tabindex` and no
+ *   arrow-key handler, so every enabled segment is its OWN tab stop —
+ *   {@link getTabStopLabels} returns a list where a radiogroup or a tablist would
+ *   have one entry. Focus and selection are therefore independent here:
+ *   {@link getFocusedLabel} implies nothing about {@link getSelectedIndex}, and
+ *   arrowing along the strip moves neither.
+ * - Activation is the browser's own default action on a button, which jsdom does not
+ *   implement, so {@link select} clicks — see {@link WrSegmentedOptionHarness.select}.
+ *
+ * **There is deliberately no `getValue()` and no selection by value.** `options` is
+ * a bound array of `{ value, label, … }` and the value is a generic `T` the component
+ * writes nowhere — not on the host, not on a segment. The single exception is an
+ * accident rather than an addressing scheme: an icon-only option with no `ariaLabel`
+ * has its value stringified into the segment's `aria-label`, which for an object
+ * value reads `[object Object]`. So address segments by their label
+ * ({@link select}) or by position ({@link selectAt}), and assert the picked value on
+ * the host's own model — the only place it exists, and the assertion that would have
+ * caught the bug anyway.
+ *
+ * The sliding thumb is decoration (`aria-hidden`), and the four methods that mention
+ * it read what the component PUBLISHES for the stylesheet — two custom properties and
+ * two modifier classes — never painted geometry, which a DOM without layout does not
+ * have. {@link getThumbIndex} in particular is not the selection; it is the trap that
+ * method documents.
+ *
+ * @example
+ * ```ts
+ * const range = await loader.getHarness(WrSegmentedHarness.with({ label: 'Range' }));
+ *
+ * expect(await range.getOptionLabels()).toEqual(['Day', 'Week', 'Month']);
+ * await range.select({ label: 'Week' });
+ * expect(await range.getSelectedIndex()).toBe(1);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSegmentedHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSegmentedHarnessFilters): HarnessPredicate<WrSegmentedHarness>;
+    /**
+     * The role the host announces — `group`.
+     *
+     * Worth pinning precisely because it is the weaker of the shapes this component
+     * could have had: a `group` of toggle buttons tells a screen reader that the
+     * segments belong together, and nothing more. Were this to become a `radiogroup` or
+     * a `tablist`, the keyboard contract would change with it (one tab stop, arrow keys
+     * moving the selection), and every spec written against {@link getTabStopLabels}
+     * would need to change too.
+     */
+    getRole(): Promise<string | null>;
+    /**
+     * The control's accessible name, resolved the way a screen reader resolves it: the
+     * text of every element `aria-labelledby` points at, and `aria-label` only when
+     * that named nothing. `null` when the consumer wired neither.
+     *
+     * The order is not interchangeable — `aria-labelledby` WINS in the accessible-name
+     * computation — so a control carrying both is announced by the heading it points at,
+     * and reporting the `aria-label` would describe a name nobody hears.
+     *
+     * The component ships no label input on purpose (the question is the consumer's own
+     * heading), so this is the only way to check that wiring held, and a `null` on a
+     * group of three unrelated-sounding buttons is a real finding.
+     */
+    getAccessibleName(): Promise<string | null>;
+    /** This control's own segments, in DOM order. A sibling control's are not here. */
+    getOptions(filters?: WrSegmentedOptionHarnessFilters): Promise<WrSegmentedOptionHarness[]>;
+    /**
+     * The accessible name of every segment, in DOM order — the visible labels, with an
+     * icon-only segment answering with the `aria-label` that stands in for its text.
+     *
+     * Throws when a segment has no name at all, rather than leaving a hole in the list:
+     * see {@link WrSegmentedOptionHarness.getLabel}.
+     */
+    getOptionLabels(): Promise<string[]>;
+    /** The pressed segment, or `null` when nothing is selected. */
+    getSelectedOption(): Promise<WrSegmentedOptionHarness | null>;
+    /**
+     * The accessible name of the pressed segment, or `null` when nothing is selected.
+     *
+     * `null` is also the answer for a bound value that matches no option — the control
+     * holds it, no segment is pressed, and the page shows an unanswered control. See
+     * {@link getThumbIndex}, which does NOT answer `null` in that state.
+     */
+    getSelectedLabel(): Promise<string | null>;
+    /**
+     * The position of the pressed segment, or `-1` when nothing is selected.
+     *
+     * Derived from `aria-pressed`, which is the selection. The other index on the page —
+     * the thumb's — is not; it clamps at 0 (see {@link getThumbIndex}).
+     */
+    getSelectedIndex(): Promise<number>;
+    /**
+     * Pick the first segment matching the filters — this is how the control's value
+     * changes.
+     *
+     * Throws when nothing matches, naming the segments that do exist, and throws again
+     * when the segment is still unpressed afterwards. That second failure has exactly
+     * two causes and reports both, because a click that quietly did nothing surfaces as
+     * an unrelated assertion three lines later.
+     */
+    select(filters: WrSegmentedOptionHarnessFilters): Promise<void>;
+    /**
+     * Pick the segment at a position, counting from zero — the addressing route for an
+     * icon-only strip, or for one whose labels a spec would rather not hard-code.
+     *
+     * Throws on an index outside the control, saying how many segments there are: an
+     * off-by-one that resolved to nothing would otherwise read as "the click did not
+     * take".
+     */
+    selectAt(index: number): Promise<void>;
+    /**
+     * Whether the control was disabled AS A WHOLE, from the `wr-segmented--disabled`
+     * modifier.
+     *
+     * Deliberately not "every segment is disabled": a control whose options each carry
+     * their own `disabled` looks identical to a user, and the modifier is the only thing
+     * on the page that tells the two apart. What actually blocks a click is the native
+     * `disabled` each button gets either way — ask a segment
+     * ({@link WrSegmentedOptionHarness.isDisabled}) for that.
+     */
+    isDisabled(): Promise<boolean>;
+    /**
+     * The rendered control size.
+     *
+     * `md` is the component's own default and earns NO modifier class, so a bare host
+     * IS `md` — the absence is the answer rather than a missing one. Read from the
+     * class instead of the input, which is also why this reports what was rendered:
+     * unlike the form controls, `<wr-segmented>` does not resolve its size through
+     * `provideWrConfig()`, so an app-wide default set there does not reach it and this
+     * will say so.
+     */
+    getSize(): Promise<WrSegmentedSize>;
+    /**
+     * The accessible name of every segment a Tab press can reach, in tab order.
+     *
+     * A LIST, not one label, and that is the shape worth pinning: the component authors
+     * no roving `tabindex`, so each enabled segment is its own tab stop and reaching the
+     * third one takes three Tabs. An all-disabled control is skipped over entirely and
+     * answers `[]`.
+     *
+     * Unnamed segments are reported as `(unnamed)` rather than throwing — a tab order is
+     * still a fact worth reading on a page that has that bug in it.
+     */
+    getTabStopLabels(): Promise<string[]>;
+    /**
+     * The accessible name of the segment that currently holds focus, or `null` when
+     * focus is elsewhere.
+     *
+     * Independent of the selection here — see the note on the class. Reported as
+     * `(unnamed)` for a segment with no name, for the reason
+     * {@link getTabStopLabels} gives.
+     */
+    getFocusedLabel(): Promise<string | null>;
+    /**
+     * The index the component publishes for the thumb, from the
+     * `--wr-segmented-thumb-index` custom property it sets inline.
+     *
+     * **Not the selection, and this is the difference that bites.** The property is
+     * `Math.max(0, selectedIndex)`, so a control holding a value that matches no option
+     * publishes `0` — the thumb parks under the FIRST segment and is hidden by
+     * {@link isThumbVisible} instead of being moved out of the way. A harness that read
+     * this to answer "which segment is selected" would report segment one for a control
+     * with no selection at all. {@link getSelectedIndex} is the selection.
+     *
+     * It is also not where the thumb IS: the stylesheet turns this into a `translateX`,
+     * and no measurement of that survives a DOM without layout. This is the input to
+     * that, which is the part a unit test can honestly check.
+     */
+    getThumbIndex(): Promise<number>;
+    /**
+     * The segment count the component publishes for the thumb, from
+     * `--wr-segmented-thumb-count` — the divisor the stylesheet computes the thumb's
+     * width with.
+     *
+     * Should always equal the number of segments, and the reason to ask is that nothing
+     * else notices when it does not: a count that fell out of step with the options
+     * leaves the thumb the wrong width and sliding to the wrong place, while every ARIA
+     * state on the page stays correct. It is clamped to a minimum of `1`, so an empty
+     * control reports `1` rather than dividing by zero.
+     */
+    getThumbCount(): Promise<number>;
+    /**
+     * Whether the thumb is being shown at all.
+     *
+     * Read from the ABSENCE of the `wr-segmented--unselected` modifier, which is the
+     * hook the stylesheet zeroes the thumb's opacity through. The computed opacity is
+     * not the answer here — a unit test applies no stylesheet — so the public modifier
+     * is the contract, and it is what tells "parked under segment one" from "hidden
+     * because nothing is selected".
+     */
+    isThumbVisible(): Promise<boolean>;
+    /**
+     * Whether the thumb will animate its next move, from the `wr-segmented--mounted`
+     * modifier that gates the transition.
+     *
+     * Not "the thumb is animating now": nothing about a running animation is visible to
+     * a unit test. What this pins is the deliberate asymmetry — the class is added in
+     * `afterNextRender`, so the FIRST snap to the initial value is instant and every
+     * user-driven move after it slides. Deferred work like that only lands once the
+     * fixture is stable, which every harness read already waits for.
+     */
+    isThumbTransitionEnabled(): Promise<boolean>;
+    /** Click a segment and turn a click that did nothing into a failure that says why. */
+    private pick;
+    /** Segment names for an error message, which must not throw on its way out. */
+    private describeOptions;
+    private describe;
+    /** One of the thumb's inline custom properties, as a number. */
+    private thumbVar;
+}
+
+export { WrSegmentedHarness, WrSegmentedOptionHarness };
+export type { WrSegmentedHarnessFilters, WrSegmentedOptionHarnessFilters };

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

@@ -0,0 +1,175 @@
+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-select>` a harness query matches. */
+interface WrSelectHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the trigger's visible text — the selected label, the chip labels
+     * joined by `', '`, or the placeholder when nothing is selected. A string is
+     * an exact match, a RegExp is tested.
+     */
+    readonly text?: string | RegExp;
+    /** Match only enabled (`false`) or only disabled (`true`) selects. */
+    readonly disabled?: boolean;
+    /** Match only open (`true`) or only closed (`false`) selects. */
+    readonly open?: boolean;
+}
+/** Narrows which option inside a select's panel a harness query matches. */
+interface WrOptionHarnessFilters extends BaseHarnessFilters {
+    /** Match the option's label — a string is an exact match, a RegExp is tested. */
+    readonly text?: string | RegExp;
+    /** Match only selected (`true`) or only unselected (`false`) options. */
+    readonly selected?: boolean;
+    /** Match only enabled (`false`) or only disabled (`true`) options. */
+    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 one option inside a `<wr-select>` panel.
+ *
+ * The selector is the CLASS, not the `wr-option` element: a select rendering a
+ * virtualized list emits plain `<div role="option" class="wr-option">` rows
+ * instead of components, and a spec should not have to care which one it got.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrOptionHarness extends ComponentHarness {
+    /** The projected component and the virtualized row both carry this class. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrOptionHarnessFilters): HarnessPredicate<WrOptionHarness>;
+    /** The option's label, trimmed. */
+    getText(): Promise<string>;
+    /** Whether the option is currently selected. */
+    isSelected(): Promise<boolean>;
+    /** Whether the option refuses selection. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the option is the keyboard cursor target. */
+    isActive(): Promise<boolean>;
+    /**
+     * Whether a search query has filtered this option out.
+     *
+     * Filtered options stay in the DOM — registration order has to survive a
+     * query — and collapse via CSS, so a spec that counts options while a search
+     * is active gets them back unless it asks. `getOptions()` on the select
+     * harness already drops them.
+     */
+    isHidden(): Promise<boolean>;
+    /** Click the option. */
+    click(): Promise<void>;
+}
+
+/**
+ * @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-select>` — single, multi, tag and search modes.
+ *
+ * The panel is NOT inside the select: it is a template portal in the overlay
+ * container, a sibling of the whole app. So the options are reached through the
+ * document root, scoped by the `aria-controls` id the trigger already publishes
+ * — which is what keeps two selects on one page from reading each other's
+ * options.
+ *
+ * @example
+ * ```ts
+ * const select = await loader.getHarness(WrSelectHarness);
+ *
+ * await select.open();
+ * await select.selectOption({ text: 'Medium' });
+ *
+ * expect(await select.getValueText()).toBe('Medium');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSelectHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrSelectHarnessFilters): HarnessPredicate<WrSelectHarness>;
+    /** Whether the panel is showing. */
+    isOpen(): Promise<boolean>;
+    /** Whether the select refuses interaction. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the select takes more than one value (multi or tag mode). */
+    isMultiple(): Promise<boolean>;
+    /**
+     * What the trigger currently shows as the selection: the chip labels joined by
+     * `', '` in multi and tag modes, the label in single mode, the input's text in
+     * search mode, and `''` when nothing is selected (the placeholder is showing).
+     */
+    getValueText(): Promise<string>;
+    /** The placeholder, or `null` when a selection is hiding it. */
+    getPlaceholder(): Promise<string | null>;
+    /** The visible chip labels, in order. The `+N more` overflow chip is not one. */
+    getChipLabels(): Promise<string[]>;
+    /**
+     * Open the panel.
+     *
+     * Throws rather than resolving quietly when the panel does not appear, because
+     * the two reasons it would not are both worth failing on: a tag-mode select
+     * has no panel at all, and a searchable one with `minChars` opens on the query
+     * rather than on focus.
+     */
+    open(): Promise<void>;
+    /** Close the panel. A closed select is left alone. */
+    close(): Promise<void>;
+    /**
+     * The options currently offered, in DOM order.
+     *
+     * Filtered-out options are dropped: a client-side search leaves them in the
+     * DOM (registration order has to survive a query) and collapses them with CSS,
+     * so counting raw elements would answer with the unfiltered list.
+     */
+    getOptions(filters?: WrOptionHarnessFilters): Promise<WrOptionHarness[]>;
+    /** The labels of the options currently offered, in DOM order. */
+    getOptionLabels(): Promise<string[]>;
+    /** Open the panel if needed, then click the first option matching the filters. */
+    selectOption(filters: WrOptionHarnessFilters): Promise<void>;
+    /** Type into a search or tag select's input, replacing whatever is there. */
+    typeSearch(query: string): Promise<void>;
+    /** Click the clear (×) control. It only exists on a `clearable` select with a selection. */
+    clear(): Promise<void>;
+    /** Remove one chip by its label. */
+    removeChip(label: string): Promise<void>;
+    /** The "no results" message, or `null` when the panel is showing options. */
+    getNoResultsText(): Promise<string | null>;
+    /** Whether the panel is showing its async loading row. */
+    isLoading(): Promise<boolean>;
+    /** Move keyboard focus to the select. */
+    focus(): Promise<void>;
+    /** The text input of a search or tag select, or `null` for the button trigger. */
+    private searchInput;
+    /** One element inside THIS select's panel, or `null`. */
+    private inPanel;
+    /**
+     * A loader scoped to THIS select's panel.
+     *
+     * Scoped by the `aria-controls` id rather than by `.wr-select-panel`: the
+     * overlay container is shared, so a bare class query would happily return the
+     * options of a different select that happens to be open.
+     */
+    private panelLoader;
+    /** The id the trigger publishes as `aria-controls`, which the panel carries. */
+    private panelId;
+}
+
+export { WrOptionHarness, WrSelectHarness };
+export type { WrOptionHarnessFilters, WrSelectHarnessFilters };

package/types/ngwr-select.d.ts

@@ -57,6 +57,14 @@ interface WrSelectOptionRegistration {
      * read it at call time once Angular has settled the projected content.
      */
     readonly getLabel: () => string;
+    /**
+     * The option's own element, when it has one. The keyboard cursor walks the
+     * registry, and registration order is CREATION order — projected children are
+     * created before the panel renders its own `[options]` rows — so without this
+     * the cursor moved in a different order from the one on screen. Optional: a
+     * registration that cannot supply an element simply keeps its place.
+     */
+    readonly host?: HTMLElement;
 }
 /**
  * Contract a `<wr-option>` uses to talk to its parent `<wr-select>`.
@@ -193,10 +201,24 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
      * @default false
      */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
-    /** Pill-shaped corners on the trigger. @default false */
-    readonly rounded: _angular_core.InputSignalWithTransform<boolean, any>;
-    /** Control size — shares the `--wr-control-*` contract. @default 'md' */
-    readonly size: _angular_core.InputSignal<WrSelectSize>;
+    /**
+     * Pill-shaped corners on the trigger. Unset falls back to the `select.rounded`
+     * app default from `provideWrConfig()`; `[rounded]="false"` turns a configured
+     * `true` back off. @default false
+     */
+    readonly rounded: _angular_core.InputSignalWithTransform<boolean | null, BooleanInput>;
+    /**
+     * Control size — shares the `--wr-control-*` contract. Unset falls back to the
+     * `select.size` app default from `provideWrConfig()`. @default 'md'
+     */
+    readonly size: _angular_core.InputSignal<WrSelectSize | null>;
+    /** `rounded`, then the app config, then `false`. @internal */
+    protected readonly resolvedRounded: _angular_core.Signal<boolean>;
+    /**
+     * `size`, then the app config, then `md`. Read by the trigger's host classes AND
+     * by the overlay panel, which builds its size modifier separately.
+     */
+    protected readonly resolvedSize: _angular_core.Signal<"sm" | "md" | "lg">;
     /**
      * Present the option panel as a full-width bottom-sheet on small
      * viewports instead of an anchored dropdown. `undefined` follows the
@@ -406,6 +428,17 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     protected readonly listboxId: string;
     /** Registered options (insertion order). Internal — distinct from the public `[options]` input. */
     private readonly registry;
+    /**
+     * The registry in DOM order — the list the keyboard cursor walks.
+     *
+     * `registry` is CREATION order, and projected `<wr-option>` children are created
+     * before the panel renders its own `[options]` rows, so with both in play the
+     * cursor moved in an order the eye could not follow: opening highlighted the
+     * third row on screen and ArrowDown went to the last. Value lookups keep reading
+     * `registry` — they do not care about order — and a registration with no element
+     * keeps its place, since the sort is stable.
+     */
+    protected readonly orderedRegistry: _angular_core.Signal<readonly WrSelectOptionRegistration[]>;
     /** Keyboard cursor index into `options`. -1 = none. */
     protected readonly activeIndex: _angular_core.WritableSignal<number>;
     /** Id of the active option (for `aria-activedescendant`). */
@@ -478,6 +511,14 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
      * Hides the noResults state when the panel has at least one visible row.
      */
     protected readonly visibleCount: _angular_core.Signal<number>;
+    /**
+     * Whether the panel may be open at all. `minChars` is documented as the
+     * "minimum query length before the panel OPENS", and nothing gated the open —
+     * so a picker with `[minChars]="3"` popped a panel on focus and showed an empty
+     * bordered box for the first two keystrokes (with the "no results" row itself
+     * gated on the same threshold, there was nothing in it to explain the box).
+     */
+    protected readonly meetsMinChars: _angular_core.Signal<boolean>;
     /** Search mode: show "no results" when the panel has nothing to offer. */
     protected readonly hasNoResults: _angular_core.Signal<boolean>;
     /** Search mode: is this option hidden by the current query? @internal */