ngwr 11.1.0 → 12.0.0

package/types/ngwr-meter-group-testing.d.ts

@@ -0,0 +1,77 @@
+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-meter-group>` a harness query matches. */
+interface WrMeterGroupHarnessFilters extends BaseHarnessFilters {
+    /** Match the bar's accessible name. */
+    readonly ariaLabel?: string | RegExp;
+    /** Match a group whose legend holds this label. */
+    readonly sliceLabel?: string | RegExp;
+}
+/** One band of the bar, as it is drawn and titled. */
+interface WrMeterGroupSlice {
+    /** The band's `title` — its only text, since the bar itself is one `progressbar`. */
+    readonly label: string | null;
+    /** The share of the bar it takes, in percent. */
+    readonly percent: number;
+}
+
+/**
+ * @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-meter-group>` — one bar divided into labelled bands.
+ *
+ * **The bar is a single `progressbar`, and its value is the TOTAL.** The bands
+ * themselves announce nothing: they carry a `title` for a mouse and their share as an
+ * inline width, and the legend is where their labels and values are readable. So a
+ * spec that wants "how much of each" reads {@link getSlices} for the shares or
+ * {@link getLegendLabels} / {@link getLegendValues} for what is printed, and one that
+ * wants "how full" reads {@link getValue}.
+ *
+ * **A band's share is read off the `style` ATTRIBUTE, not through `getCssValue()`**,
+ * and the difference is not cosmetic: `getCssValue()` is `getComputedStyle()`, and
+ * `width` resolves to the USED value — so the declared `30%` comes straight back in
+ * jsdom and arrives as `180px` on a 600px bar in a real browser, and the same harness
+ * answered 30 here and 180 under a browser runner with nothing to say which one you
+ * got.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrMeterGroupHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrMeterGroupHarnessFilters): HarnessPredicate<WrMeterGroupHarness>;
+    private readonly bar;
+    /** The role the bar announces — `progressbar`, for the total. */
+    getRole(): Promise<string | null>;
+    /** The bar's accessible name. */
+    getAccessibleName(): Promise<string | null>;
+    /** The total the bands add up to, from `aria-valuenow`. */
+    getValue(): Promise<number>;
+    /** The full capacity, from `aria-valuemax` — given, or the sum of the bands. */
+    getMax(): Promise<number>;
+    /** The bands, in order, with the share of the bar each takes. */
+    getSlices(): Promise<WrMeterGroupSlice[]>;
+    /** Parse one band's declared share. See the class note on why this is not `getCssValue()`. */
+    private static percentOf;
+    /** Whether the legend is rendered (`showLegend`, and at least one band). */
+    hasLegend(): Promise<boolean>;
+    /** The legend's labels, in order. */
+    getLegendLabels(): Promise<string[]>;
+    /** The legend's values, in order — empty when `showValues` is off. */
+    getLegendValues(): Promise<string[]>;
+}
+
+export { WrMeterGroupHarness };
+export type { WrMeterGroupHarnessFilters, WrMeterGroupSlice };

package/types/ngwr-overlay.d.ts

@@ -90,6 +90,7 @@ declare function wrMirrorOffsets(positions: readonly ConnectedPosition[], isRtl:
  *
  * Registration is per subscription: the document listeners go up with the first
  * watcher and come down with the last, so an app with no open overlay has none.
+ * That sentence was aspirational until v11 — see {@link outsidePointerEvents}.
  */
 declare class WrOutsideClick {
     private readonly doc;
@@ -100,7 +101,24 @@ declare class WrOutsideClick {
     private pressOrigin;
     /**
      * Emits every `click` / `auxclick` / `contextmenu` that lands outside the
-     * given overlay's pane, for as long as the returned observable is subscribed.
+     * given overlay's pane, for as long as the overlay is attached.
+     *
+     * **It completes when the overlay detaches, and that is load-bearing.** Every
+     * one of the ten call sites subscribes inside its own `openOverlay()` and
+     * pipes `takeUntilDestroyed(destroyRef)` — a DIRECTIVE lifetime, not an
+     * overlay one — and none of them unsubscribes on close, because the natural
+     * reading of that idiom is "this ends with the component". Without the
+     * completion below the teardown never ran: one watcher accumulated per OPEN
+     * for the life of the page, each pinning a disposed `OverlayRef` (and through
+     * it a detached pane, its portal outlet and their injectors), the four
+     * capture-phase document listeners could never come down because
+     * `watchers.length` never reached zero, and every click on the page walked a
+     * list that only grew. A `mode="tooltip"` popover made it unbounded — one
+     * permanent watcher per hover.
+     *
+     * Completing here rather than fixing ten call sites is deliberate: the next
+     * component to open an overlay would have made the same reasonable mistake.
+     * It is also what CDK's own `OverlayRef.outsidePointerEvents()` does.
      */
     outsidePointerEvents(overlayRef: OverlayRef): Observable<MouseEvent>;
     private readonly onPointerDown;
@@ -285,3 +303,4 @@ declare const WR_OVERLAY: InjectionToken<Overlay>;
 declare const WR_OVERLAY_CONTAINER: InjectionToken<OverlayContainer>;
 
 export { WR_OVERLAY, WR_OVERLAY_CONTAINER, WR_RESPONSIVE_OVERLAYS, WrOutsideClick, WrOverlayContainer, provideWrOverlay, provideWrResponsiveOverlays, wrAppendOverlayClose, wrMirrorOffsets, wrPresentAsSheet };
+export type { WrResponsiveOverlaysConfig };

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

@@ -179,10 +179,10 @@ declare class WrPaginationHarness extends ComponentHarness {
      * The page the pager announces as current, from `aria-current="page"`.
      *
      * Throws when no cell claims it. The window always keeps the current page on the
-     * strip, so getting here means `currentPage` is not one of the pages at all — it
-     * is below 1, or not a whole number. The component clamps a page ABOVE the last
-     * one and nothing else, and either survivor leaves every cell looking equally
-     * inactive to an assistive tech user.
+     * strip, so getting here means `currentPage` is not one of the pages at all. The
+     * component clamps a host write into `1..totalPages`, which leaves one survivor:
+     * a fractional page, which is in range and matches no cell — and which leaves
+     * every cell looking equally inactive to an assistive tech user.
      */
     getCurrentPage(): Promise<number>;
     /**

package/types/ngwr-pipes.d.ts

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
 import { PipeTransform } from '@angular/core';
-import { WrDateFormat } from 'ngwr/date-adapter';
+import { WrDateFormat } from 'ngwr/date';
 import { SafeHtml } from '@angular/platform-browser';
 
 /**

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

@@ -181,8 +181,13 @@ declare class WrPopoverHarness extends ContentContainerComponentHarness {
      * Where the panel sits relative to the trigger, or `null` when it is presented
      * as a sheet and has no anchor.
      *
-     * The resolved position — the directive defaults it per mode (`bottom` for a
-     * popover, `top` for a tooltip) — read off the pane's public modifier class.
+     * The APPLIED position, not the requested one: CDK flips a placement that does
+     * not fit to the next in its fallback chain and swaps the modifier class with
+     * it. Under a unit test that is always the requested placement — jsdom measures
+     * every box as 0×0, so the first candidate always "fits" — but in a browser the
+     * two can differ, and this answers what is on screen. The directive defaults
+     * the request per mode (`bottom` for a popover, `top` for a tooltip).
+     *
      * The arrow itself is a `::after` pseudo-element, so it exists for no DOM query
      * at all; this class is the placement, and it is what the arrow's own CSS keys
      * off.

package/types/ngwr-popover.d.ts

@@ -73,6 +73,7 @@ declare class WrPopover {
     private readonly resolvedAriaLabel;
     private readonly resolvedPosition;
     private overlayRef;
+    private textPanelRef;
     private hoverCloseTimer;
     private showTimer;
     private hideTimer;

package/types/ngwr-result.d.ts

@@ -40,6 +40,8 @@ declare class WrResult {
  * ```
  */
 declare class WrResult404 {
+    /** Bound by the shared template; not an input — a preset IS its status. */
+    protected readonly status: WrResultStatus;
     readonly title: _angular_core.InputSignal<string>;
     /** Body text. Falls back to `result.notFound` from WrI18n. */
     readonly description: _angular_core.InputSignal<string | null>;
@@ -49,6 +51,8 @@ declare class WrResult404 {
 }
 /** Pre-set 403 result — forbidden / no access. */
 declare class WrResult403 {
+    /** Bound by the shared template; not an input — a preset IS its status. */
+    protected readonly status: WrResultStatus;
     readonly title: _angular_core.InputSignal<string>;
     /** Body text. Falls back to `result.forbidden` from WrI18n. */
     readonly description: _angular_core.InputSignal<string | null>;
@@ -58,6 +62,8 @@ declare class WrResult403 {
 }
 /** Pre-set 500 result — internal server error. */
 declare class WrResult500 {
+    /** Bound by the shared template; not an input — a preset IS its status. */
+    protected readonly status: WrResultStatus;
     readonly title: _angular_core.InputSignal<string>;
     /** Body text. Falls back to `result.serverError` from WrI18n. */
     readonly description: _angular_core.InputSignal<string | null>;

package/types/ngwr-rotating-text-testing.d.ts

@@ -0,0 +1,191 @@
+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-rotating-text>` a harness query matches. */
+interface WrRotatingTextHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the string showing right now — the readable copy, not the animated pieces.
+     * A string is an exact match, a RegExp is tested.
+     *
+     * It matches a MOMENT, not a rotator: the component cycles, so a filter that hits today
+     * misses two seconds later. Use it to address the one that is currently showing a known
+     * word, and prefer `selector` for a rotator you need to hold on to.
+     */
+    readonly text?: string | RegExp;
+    /**
+     * Match on how many word groups the split produced. Word boundaries survive every
+     * granularity — three words stay three groups even when each is exploded into
+     * characters — so this is stable across the split, unlike the piece count.
+     */
+    readonly wordCount?: number;
+}
+
+/**
+ * @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-rotating-text>`.
+ *
+ * **What is announced and what is drawn are two questions, and this component is worth a
+ * harness mostly because it answers them separately.** The string showing now is carried
+ * verbatim in a visually-hidden span; the animated layer beside it is one span per
+ * grapheme, word or line and is `aria-hidden` as a whole, so a screen reader hears `one`
+ * rather than `o. n. e.` {@link getAccessibleText} is the first, {@link getRenderedText}
+ * and {@link getPieces} the second, and {@link isAnimatedLayerHidden} together with
+ * {@link hasAccessibleCopy} is the pairing that regresses silently when someone
+ * restructures the template — pieces hidden AND no readable copy is an element with no
+ * accessible text at all, which reads as a pass on either check alone.
+ *
+ * **The sr-only span is deliberately not a live region, and no method here implies
+ * otherwise.** `auto` advances every two seconds by default, and the APG's answer for
+ * self-advancing content is silence, not an announcement on a timer. What the harness
+ * pins is that the announced copy TRACKS the current word — nothing about it being
+ * spoken.
+ *
+ * **There is no `getIndex()`, and no `next()` / `previous()` / `jumpTo()` / `reset()`.**
+ * The index appears nowhere in the DOM — no attribute, no data hook — so deriving it
+ * would mean matching the shown string against a list the harness was never given, and
+ * guessing between duplicates. And the component renders no controls at all: rotation is
+ * a timer or a method call on the instance, so a harness "click" would have nothing to
+ * click and reaching into the component would make this a wrapper around the class rather
+ * than a reader of the DOM. Drive it from the spec — through the instance, or by
+ * advancing the interval — and assert the `nextChange` output for the index.
+ *
+ * **Nothing here reports the tween.** `duration`, `easing`, `staggerDuration` and
+ * `staggerFrom` are passed straight into Web Animation options and never written to the
+ * document; `delayFor()` is arithmetic with no rendered trace. So no `getDuration()`, no
+ * `getStagger()`, no `isAnimating()`. The pieces do carry inline `opacity` and
+ * `transform`, but on the animated path those are the FIRST keyframe — `opacity: 0` on
+ * text the user can see perfectly well — which is why the only reading offered is
+ * {@link isSettled}, and why it is spelled as a commitment rather than as a state of
+ * motion. The host's `overflow: hidden` clipping is layout, and every rect in a unit test
+ * is 0×0, so there is no `isClipped()` either.
+ *
+ * jsdom implements no Web Animations API, so the animated path throws on the first
+ * `el.animate` — before any assertion runs. Every spec supplies one half or the other:
+ *
+ * ```ts
+ * // Either: mount under reduced motion, where each swap is instant and nothing tweens.
+ * // (jsdom has no matchMedia, so WrPlatform must be provided as a value.)
+ * TestBed.configureTestingModule({ providers: [{ provide: WrPlatform, useValue: reducedMotion }] });
+ *
+ * // Or: stub the API — and remember a stub that never fires `onfinish` never resolves
+ * // the exit step, so the rotator stops after one swap.
+ * Reflect.set(Element.prototype, 'animate', () => ({ cancel: () => undefined, onfinish: null }));
+ * ```
+ *
+ * @example
+ * ```ts
+ * const rotator = await loader.getHarness(WrRotatingTextHarness);
+ *
+ * expect(await rotator.getAccessibleText()).toBe('design');
+ * expect(await rotator.getPieces()).toEqual(['d', 'e', 's', 'i', 'g', 'n']);
+ * expect(await rotator.isAnimatedLayerHidden()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrRotatingTextHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrRotatingTextHarnessFilters): HarnessPredicate<WrRotatingTextHarness>;
+    private readonly chars;
+    /**
+     * The string showing right now, as the one readable copy holds it.
+     *
+     * Literally what a screen reader gets, the animated layer being out of the tree — and
+     * the thing to assert a rotation against, since it is where `next()`, `previous()`, a
+     * clamped `jumpTo()`, `reset()`, the wrap at either end, the stop when `loop` is off and
+     * the shrinking-list clamp all become visible.
+     *
+     * Throws when the copy is missing rather than answering with the pieces' text: an empty
+     * string is what a rotator holding an empty list correctly reports, so a plausible
+     * nothing here is indistinguishable from the component having lost its accessible name
+     * entirely. Ask {@link hasAccessibleCopy} when presence is the question.
+     */
+    getAccessibleText(): Promise<string>;
+    /**
+     * Everything the animated layer draws, in document order, as one string.
+     *
+     * A different fact from {@link getAccessibleText}, and the comparison between them is
+     * the point: a split that drops its spacer renders `hellothere` while the readable copy
+     * stays perfect, and nothing else in the DOM says so.
+     *
+     * The spacer between words is a non-breaking space (`&nbsp;`), which is a rendering
+     * choice rather than a contract, so it is normalized to a plain space here — otherwise
+     * every round-trip assertion would have to spell U+00A0 out to pass against a working
+     * component. Note that `splitBy="lines"` genuinely does not round-trip: the newline the
+     * readable copy carries is drawn as that same spacer.
+     */
+    getRenderedText(): Promise<string>;
+    /**
+     * The animated pieces, in document order.
+     *
+     * The granularity actually applied: one piece per grapheme for `splitBy="characters"`,
+     * one per word for `"words"`, one per line for `"lines"`. It is also where the grapheme
+     * contract shows — `a🚀b` must come back as three pieces, not four with two broken
+     * halves of a surrogate pair.
+     */
+    getPieces(): Promise<string[]>;
+    /**
+     * How many word groups the split produced.
+     *
+     * Word boundaries survive every granularity: three words stay three groups even when
+     * each is exploded into characters, which is what keeps the line wrapping sane. A
+     * splitter that flattened the grouping would leave {@link getPieces} correct and break
+     * only this.
+     */
+    getWordCount(): Promise<number>;
+    /**
+     * Whether the animated layer is out of the accessibility tree.
+     *
+     * ONE attribute answers it — `aria-hidden` sits on the `__inner` wrapper, so the pieces
+     * inherit it and none carries it itself, which keeps the attribute off the nodes the
+     * tween writes to. Asserting it per piece would fail on a component that is behaving.
+     *
+     * If it regresses, every rotation is spelled out letter by letter beside the copy that
+     * was already read, and nothing changes on screen — so no other check catches it.
+     */
+    isAnimatedLayerHidden(): Promise<boolean>;
+    /**
+     * Whether the readable copy is rendered at all.
+     *
+     * The other half of {@link isAnimatedLayerHidden}, and it exists as a separate question
+     * because the failure the two catch together is invisible to each alone: a layer
+     * correctly hidden with no readable copy beside it is a control with no accessible text
+     * whatsoever, and `isAnimatedLayerHidden() === true` is exactly what it reports.
+     */
+    hasAccessibleCopy(): Promise<boolean>;
+    /**
+     * Whether the enter step committed its end state on every piece — NOT whether an
+     * animation finished.
+     *
+     * The component writes `opacity: 1` inline on each piece when the swap settles: instantly
+     * under reduced motion, and from the tween's `onfinish` otherwise. So this answers "the
+     * new word was actually taken over", which is the bug the deferred enter exists to
+     * prevent — a swap that animates the OLD spans leaves the new ones staged at `opacity: 0`
+     * and the text invisible, while the readable copy reports the new word correctly.
+     *
+     * It is all-or-nothing: one piece left staged is one invisible glyph in the middle of a
+     * word. On the animated path it stays `false` until each tween finishes, which in a unit
+     * test means forever, since a stubbed `Element.animate` never fires anything — that is
+     * an honest answer about a swap that never landed, not a limitation to work around.
+     *
+     * Throws when there are no pieces: "every piece is settled" is true of none of them,
+     * and that is also what a component that stopped rendering its text would report.
+     */
+    isSettled(): Promise<boolean>;
+}
+
+export { WrRotatingTextHarness };
+export type { WrRotatingTextHarnessFilters };

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

@@ -393,6 +393,15 @@ declare class WrSegmentedHarness extends ComponentHarness {
     /** Segment names for an error message, which must not throw on its way out. */
     private describeOptions;
     private describe;
+    /**
+     * One custom property off the host's `style` ATTRIBUTE.
+     *
+     * Not `getCssValue()`, which is `getComputedStyle`: with the entry point's own
+     * stylesheet loaded that resolves the sheet's declaration, so the method
+     * answers plausibly at exactly the moment the host binding — the thing under
+     * test — is what broke. The attribute holds only what the component wrote.
+     */
+    private inlineVar;
     /** One of the thumb's inline custom properties, as a number. */
     private thumbVar;
 }

package/types/ngwr-segmented.d.ts

@@ -61,7 +61,27 @@ declare class WrSegmented<T = unknown> {
     private readonly mounted;
     constructor();
     protected readonly classes: _angular_core.Signal<string>;
-    /** Inline CSS vars driving the sliding thumb position. */
+    private readonly dir;
+    /**
+     * Reading direction of the strip. `Directionality` is root-provided, so this
+     * always resolves — `optional` only guards a consumer who has deliberately
+     * torn the provider out. A subtree that overrides the direction does it with
+     * the CDK's `Dir` directive, which writes `valueSignal`, so `thumbStyle`
+     * re-renders instead of leaving the thumb parked on the old segment.
+     */
+    private readonly isRtl;
+    /**
+     * Inline CSS vars driving the sliding thumb position.
+     *
+     * `--wr-segmented-thumb-index` is the SLOT the thumb parks in, counted from the
+     * physical left, which is the selected index only in LTR. The stylesheet anchors
+     * the thumb with a physical `left` and slides it with `translateX` — neither has
+     * a logical form — while the options are a grid that mirrors, so under `dir="rtl"`
+     * the segment at logical index `i` occupies slot `count - 1 - i`. Left unsigned,
+     * the pill sat under a different label than the one it marks (the whole strip's
+     * worth of offset at the far end), which is the carousel's `trackStyle` problem
+     * one component over.
+     */
     protected readonly thumbStyle: _angular_core.Signal<Record<string, string>>;
     protected isSelected(option: WrSegmentedOption<T>): boolean;
     protected select(option: WrSegmentedOption<T>): void;

package/types/ngwr-select.d.ts

@@ -194,6 +194,48 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     protected readonly resolvedAriaLabel: _angular_core.Signal<string>;
     /** Per-chip ARIA label — interpolates `{{label}}`. @internal */
     protected readonly chipRemoveLabel: (params?: ngwr_i18n.WrI18nParams) => string;
+    /**
+     * The overflow chip past `maxTagCount` — interpolates `{{count}}`. Through the
+     * catalog, like every other string here: printed as a bare `+{{ extra }} more`
+     * it stayed English in a fully localized app, beside an event-calendar cell
+     * reading "ещё 3" from the same string. @internal
+     */
+    protected readonly moreLabel: (params?: ngwr_i18n.WrI18nParams) => string;
+    private readonly field;
+    /**
+     * Id the surrounding `<wr-form-field>`'s `<label for>` points at.
+     *
+     * The field renders its label before it can see what was projected into it, so
+     * the id travels the other way and the control adopts it, exactly as `[wrInput]`
+     * and `wr-slider` do. Without this the `for` named an element that was nowhere in
+     * the document: clicking the label did nothing, and the field's own text reached
+     * the control through no path at all.
+     *
+     * It lands on the ONE focusable element each trigger shape has — the button, the
+     * search input, or the tag input — never on the host, because only a labelable
+     * element can be a label's target and `<wr-select>` is not one.
+     *
+     * What this does NOT change is that element's NAME: `aria-label` outranks a
+     * `<label>` in the accname order, and the trigger keeps `resolvedAriaLabel()`
+     * because the field cannot promise it has a name to give — `<wr-form-field>`
+     * renders a label only when its `label` input is set, and a combobox that traded
+     * a generic name for no name would be the worse bug. `WrFormFieldContext`
+     * publishes no "do I have a visible label" signal to key that on. Until it does,
+     * set `[ariaLabel]` to the field's label where the two should read alike.
+     */
+    protected readonly controlId: _angular_core.Signal<string | null>;
+    /**
+     * The field's error message, wired to the same element.
+     *
+     * Without it the messages `<wr-form-field>` renders are visible and nothing else:
+     * a screen reader on the trigger never learns the field is invalid, nor what the
+     * message says. `aria-invalid` is keyed on the message EXISTING rather than on
+     * `errorKeys()`, because the field only publishes an id once it is showing
+     * something — announcing "invalid" while pointing at nothing is worse than
+     * staying quiet.
+     */
+    protected readonly describedBy: _angular_core.Signal<string | null>;
+    protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
     /**
      * Disable the select. Bound automatically from the field's disabled state
      * when used with `[formField]`.
@@ -465,7 +507,17 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     protected readonly dynamicOptions: _angular_core.Signal<readonly unknown[]>;
     private static readonly FALLBACK_ROW_PX;
     private static readonly FALLBACK_VIEWPORT_PX;
-    /** Consumer-projected `<wr-option>` children only (NOT the `@for`-rendered ones). */
+    /**
+     * Consumer-projected `<wr-option>` children only (NOT the `@for`-rendered ones
+     * — those live in the panel's own view, which a content query never sees).
+     *
+     * `descendants: true` because a projected option is as often wrapped in a
+     * `<wr-option-group>` as it is a direct child, and the signal default is
+     * `false`. A grouped list therefore read as NO projected options: `virtualActive`
+     * engaged over the (empty) data array, so the panel rendered the group's rows
+     * with a virtual window beside them that owned the keyboard — no
+     * `aria-activedescendant`, no active row, and Enter committing nothing.
+     */
     private readonly projectedOptions;
     /**
      * `dynamicOptions()` narrowed to the current search query. `dynamicOptions()`
@@ -475,9 +527,18 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
      */
     protected readonly filteredDynamicOptions: _angular_core.Signal<readonly unknown[]>;
     /**
-     * Virtualization engaged: opt-in, search mode, a non-empty filtered array, and
-     * NO projected `<wr-option>` children (those keep the full-render registry path
-     * so their DOM-derived labels / selection still work).
+     * Virtualization engaged: opt-in, search mode, and NO projected `<wr-option>`
+     * children — grouped ones included (those keep the full-render registry path so
+     * their DOM-derived labels / selection still work).
+     *
+     * NOT gated on there being matches. It used to also require
+     * `filteredDynamicOptions().length > 0`, which meant a query matching nothing
+     * fell back to the full-render path and mounted the ENTIRE unfiltered array —
+     * 2000 `<wr-option>` hosts, every one of them `--hidden`, behind a "No
+     * results" line — and then tore all of them down again on the next keystroke
+     * that matched. The empty window is handled where it belongs: `virtualWindow`
+     * already short-circuits on `total === 0`, and `firstEnabled` / `lastEnabled`
+     * already answer -1.
      */
     protected readonly virtualActive: _angular_core.Signal<boolean>;
     private readonly scrollTop;
@@ -537,6 +598,7 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     protected onChipsBlur(): void;
     protected onSearchInput(event: Event): void;
     protected onSearchFocus(): void;
+    protected onSearchBlur(): void;
     protected onSearchKey(event: KeyboardEvent): void;
     /**
      * Display text for the search input. Shows the selected option's
@@ -544,6 +606,15 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
      * @internal
      */
     protected readonly searchDisplay: _angular_core.Signal<string>;
+    /**
+     * Whether the search field holds focus.
+     *
+     * Read by `searchDisplay`, so it has to be a signal — and it is also what
+     * lets the panel-close effect tell "the user walked away" (reset the query)
+     * from "the query dropped under `minChars` and they are still typing" (keep
+     * it).
+     */
+    private readonly searchHasFocus;
     private readonly host;
     private readonly overlay;
     private readonly outsideClick;
@@ -557,8 +628,18 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     isSelected(value: unknown): boolean;
     selectOption(value: unknown): void;
     registerOption(reg: WrSelectOptionRegistration): () => void;
-    /** Remove one selection (chip × button). Works for multi and tag modes. */
-    protected removeChip(value: unknown, event: Event): void;
+    /**
+     * Remove one selection (chip × button) BY POSITION. Works for multi and tag
+     * modes.
+     *
+     * Positional, not by value: under `allowDuplicates` two chips carry the same
+     * string, and a filter on equality deleted every copy at once — one click on
+     * the second "red" took both reds with it. `visibleChips()` slices the HEAD
+     * of `selectedChips()`, which maps the value array one for one, so the
+     * `$index` a chip was rendered with indexes the value array directly. The
+     * multi-mode toggle in `selectOption` was already positional.
+     */
+    protected removeChip(index: number, event: Event): void;
     /** Clear every selection (× button). Multi/tag → empty array; search → null. */
     protected clearAll(event: Event): void;
     /** Capacity check used by tag mode to refuse the next add. */
@@ -573,6 +654,19 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     protected onTriggerKey(event: KeyboardEvent): void;
     private seedActiveIndex;
     private moveActive;
+    /**
+     * Both scan `orderedRegistry`, and that is not interchangeable with
+     * `registry`.
+     *
+     * They RETURN an index, and every reader of `activeIndex` — `activeOptionId`,
+     * `moveActive`, `seedActiveIndex`, the Enter branch of `onTriggerKey` —
+     * resolves it against DOM order. Scanning creation order here produced an
+     * index into the other list: with projected `<wr-option>` children next to
+     * `[options]` rows the two differ, so opening or searching left the cursor on
+     * a row the user was not looking at, and Enter committed whatever happened to
+     * sit at that position in DOM order — a filter-hidden option, which commits
+     * nothing at all.
+     */
     private firstEnabled;
     private lastEnabled;
     /** Coerce the multi-mode value into an array (tolerates a scalar or null write). */