ngwr 14.0.0 → 14.1.0

package/types/ngwr-form.d.ts

@@ -66,6 +66,20 @@ interface WrFormFieldContext {
     readonly errorKeys: Signal<readonly string[]>;
     /** Id of the element listing the visible messages, or `null` when there are none. */
     readonly describedBy: Signal<string | null>;
+    /**
+     * Id of the field's hint, or `null` when it is showing none — including while
+     * an error has replaced it, since the two never render together and an
+     * `aria-describedby` naming an absent element is an author error.
+     *
+     * Separate from {@link describedBy} rather than folded into it because the two
+     * carry different weight: a control keyed `aria-invalid` on "the field is
+     * describing me" would announce itself invalid for a plain hint. Compose the
+     * pair with `useFormFieldAria()` instead of reading either one directly.
+     *
+     * Optional so an app that provides its own `WR_FORM_FIELD` keeps compiling; a
+     * field without it simply describes nothing but its errors.
+     */
+    readonly hintId?: Signal<string | null>;
 }
 /** Present only inside a `<wr-form-field>`; inject with `{ optional: true }`. */
 declare const WR_FORM_FIELD: InjectionToken<WrFormFieldContext>;
@@ -187,6 +201,20 @@ declare class WrFormField implements WrFormFieldContext {
     readonly errorKeys: _angular_core.Signal<readonly string[]>;
     /** @internal Read by the projected control so a screen reader is pointed at the message. */
     readonly describedBy: _angular_core.Signal<string | null>;
+    /**
+     * @internal Read by the projected control so the hint is announced with the field.
+     *
+     * The hint used to carry no id at all, so the only thing `aria-describedby`
+     * could ever name was the error block: the sentence explaining what to type was
+     * on screen and reached a screen-reader user through no path whatsoever, and
+     * the one gate that could have said so does not exist — axe has no rule that
+     * visible help text must be programmatically associated.
+     *
+     * `null` while an error is showing, because the template swaps the hint out for
+     * the message; publishing the id anyway would point every control at an element
+     * that had just left the document.
+     */
+    readonly hintId: _angular_core.Signal<string | null>;
     /**
      * Render a catalog message for any error the markup does not already answer.
      *
@@ -223,24 +251,31 @@ declare class WrFormField implements WrFormFieldContext {
 
 /** What {@link useFormFieldAria} hands a control to bind on its own element. */
 interface WrFormFieldAria {
-    /** Id of the field's message block, or `null` when it is showing none. */
+    /**
+     * Id of the field's message block while it is showing one, of its hint
+     * otherwise, and `null` when it is showing neither.
+     */
     readonly describedBy: Signal<string | null>;
-    /** `'true'` while the field is showing a message, `null` otherwise. */
+    /** `'true'` while the field has a validation error, `null` otherwise. */
     readonly ariaInvalid: Signal<'true' | null>;
 }
 /**
- * The two attributes that make a `<wr-form-field>`'s visible error reach a
- * screen reader — bind both on whichever element carries the control's role.
+ * The two attributes that make a `<wr-form-field>`'s visible text — its error
+ * message, or its hint — reach a screen reader. Bind both on whichever element
+ * carries the control's role.
  *
- * Without them the messages the field renders are visible and nothing else: the
- * control announces itself as valid, and the message is associated with nothing.
- * No automated gate catches that — axe has no rule that a visible error must be
- * programmatically associated with its control — so this helper exists to make
- * the wiring one line per control rather than three, and the specs are the gate.
+ * Without them the copy the field renders is visible and nothing else: the
+ * control announces itself as valid, and the text is associated with nothing.
+ * No automated gate catches that — axe has no rule that a visible error or hint
+ * must be programmatically associated with its control — so this helper exists
+ * to make the wiring one line per control rather than three, and the specs are
+ * the gate.
  *
- * `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.
+ * The field renders an error OR a hint, never both, so `describedBy` names
+ * whichever is on screen and `aria-invalid` is keyed SEPARATELY, on the field's
+ * `errorKeys()`. Deriving it from `describedBy` instead — which is what every
+ * control did while a hint had no id to name — makes a field with a plain hint
+ * announce its control as invalid the moment the hint becomes describable.
  *
  * Must be called from an injection context (a field initialiser or a
  * constructor). Returns inert signals outside a `<wr-form-field>`.

package/types/ngwr-input.d.ts

@@ -66,8 +66,9 @@ declare class WrInput {
      * invisible to a screen reader, which never learns the field is invalid or
      * what the message says.
      */
-    protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
+    private readonly fieldAria;
     protected readonly describedBy: _angular_core.Signal<string | null>;
+    protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
     /**
      * Control size. Unset, it falls back to
      * `provideWrConfig({ input: { size } })`. @default 'md'

package/types/ngwr-rating.d.ts

@@ -4,8 +4,13 @@ import { FormValueControl } from '@angular/forms/signals';
 
 /**
  * Star rating input. Click or hover to set a value; supports half-star
- * increments via `step="0.5"`. Value is `number | null` (clamped to
- * `[0, count]`).
+ * increments via `step="0.5"`. Value is `number | null`.
+ *
+ * `[0, count]` bounds what this control's OWN edits produce — a click, an arrow
+ * key, `End`. A value written from outside is displayed and announced clamped
+ * (a slider cannot report an `aria-valuenow` past its own `aria-valuemax`) and
+ * left in the model as it stands, the same rule `wr-slider` and
+ * `wr-input-number` follow.
  *
  * A signal-forms native control: it implements `FormValueControl<number | null>`,
  * so `[formField]` binds straight to its `value` model — no
@@ -68,8 +73,25 @@ declare class WrRating implements FormValueControl<number | null> {
      * an error message on an element nobody could focus.
      */
     protected readonly focusable: _angular_core.Signal<boolean>;
-    /** What we actually render — hover wins while hovering. */
+    /**
+     * What we actually render — hover wins while hovering.
+     *
+     * Clamped, because there is no such thing as drawing six stars in a row of
+     * five, and the same number is what `aria-valuenow` reports: a `role="slider"`
+     * whose value sits outside its own min / max is an invalid slider whatever the
+     * model holds. The MODEL is left alone — see the note above `fillFor` for why
+     * the clamp is not written back.
+     */
     protected readonly displayValue: _angular_core.Signal<number>;
+    /**
+     * What the slider REPORTS, and where the arrows start from.
+     *
+     * Deliberately not `displayValue`: a hover preview is a pointer affordance and
+     * must not be announced as the current value, and an arrow press after a hover
+     * has to step from the committed number rather than from wherever the mouse
+     * happened to rest.
+     */
+    protected readonly announcedValue: _angular_core.Signal<number>;
     protected readonly slots: _angular_core.Signal<number[]>;
     /**
      * Reading direction, for the two places it changes the answer: the arrows and
@@ -84,7 +106,6 @@ declare class WrRating implements FormValueControl<number | null> {
     /** The surrounding `<wr-form-field>`'s error state. @internal */
     protected readonly fieldAria: ngwr_form.WrFormFieldAria;
     protected readonly classes: _angular_core.Signal<string>;
-    constructor();
     /** Fill ratio for slot `i` in `[0, 1]` — drives the CSS clip width. */
     protected fillFor(i: number): number;
     protected onSlotMove(event: MouseEvent, index: number): void;

package/types/ngwr-segmented.d.ts

@@ -141,6 +141,7 @@ declare class WrSegmented<T = unknown> implements FormValueControl<T | null> {
      * because the field only publishes an id once it is showing something — announcing
      * "invalid" while pointing at nothing is worse than staying quiet.
      */
+    private readonly fieldAria;
     protected readonly describedBy: _angular_core.Signal<string | null>;
     protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
     /** Index of the selected option, or `-1` when nothing is selected. */

package/types/ngwr-select.d.ts

@@ -227,15 +227,17 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
      */
     protected readonly controlId: _angular_core.Signal<string | null>;
     /**
-     * The field's error message, wired to the same element.
+     * The field's error message — or, failing that, its hint — wired to the same
+     * element, plus the invalid flag.
      *
-     * 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.
-     */
+     * Without it the copy `<wr-form-field>` renders is visible and nothing else: a
+     * screen reader on the trigger never learns the field is invalid, nor what the
+     * message says. Composed by `useFormFieldAria()` rather than read off the field
+     * here, so the trigger picks up the hint the same way the other value controls
+     * do and `aria-invalid` stays keyed on the error rather than on "is anything
+     * describing me".
+     */
+    private readonly fieldAria;
     protected readonly describedBy: _angular_core.Signal<string | null>;
     protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
     /**
@@ -605,8 +607,41 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     protected virtualRowId(i: number): string;
     /** The virtual scroll container inside the overlay panel, if attached. */
     private get vlistElement();
-    /** Scroll filtered index `i` just into view (sets the `scrollTop` signal synchronously). */
+    /** The scrolling listbox inside the overlay panel, if attached. */
+    private get panelElement();
+    /**
+     * Scroll the ordered index `i` just into view. Two implementations, because the
+     * two panels scroll different elements and know the row geometry in different
+     * ways — the virtual list is index maths against a measured row height, the
+     * projected list has to read the row it is moving to.
+     *
+     * The non-virtual half is not an optimisation, it is the whole keyboard
+     * contract: `activeIndex` drives `aria-activedescendant`, and NOTHING else
+     * moves a projected panel, because the rows never take DOM focus. Without it
+     * End on a 250-option `mode="search"` panel announced Zimbabwe while the panel
+     * sat at `scrollTop` 0 with the cursor 9 218 px below the fold, and Enter then
+     * committed a row the user could not see.
+     */
     private ensureVisible;
+    /**
+     * Scroll the projected row at ordered index `i` just into view.
+     *
+     * Geometry is READ rather than computed: projected `<wr-option>` rows are
+     * consumer content, so they are not a uniform height the way a virtual row is
+     * — a row with a description, an icon or a wrapped label is taller than its
+     * neighbours, and index maths would land the panel next to the cursor instead
+     * of on it. The offset is taken relative to the panel's own scroll content
+     * (`rect.top` difference plus the current `scrollTop`) rather than from
+     * `offsetTop`, which is measured against whichever ancestor happens to be
+     * positioned.
+     *
+     * `scrollTop` is written directly instead of `scrollTo`, so the write is
+     * observable in a spec — jsdom implements the property and does not implement
+     * the method. It still reads as a no-op there, since every jsdom rect is 0×0:
+     * a spec asserting a scroll has to stub `getBoundingClientRect` and
+     * `clientHeight` on the panel and the row, which `select.spec.ts` does.
+     */
+    private ensureRowVisible;
     /**
      * Count of registered options that pass the current search filter.
      * Hides the noResults state when the panel has at least one visible row.
@@ -674,6 +709,7 @@ declare class WrSelect implements FormValueControl<unknown>, WrSelectContext {
     private readonly scrollStrategies;
     private readonly destroyRef;
     private readonly platformId;
+    private readonly injector;
     private overlayRef;
     constructor();
     isSelected(value: unknown): boolean;

package/types/ngwr-slider.d.ts

@@ -137,6 +137,7 @@ declare class WrSlider implements FormValueControl<WrSliderValue> {
      * showing something — announcing "invalid" while pointing at nothing is worse
      * than staying quiet.
      */
+    private readonly fieldAria;
     protected readonly describedBy: _angular_core.Signal<string | null>;
     protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
     /**

package/types/ngwr-storage.d.ts

@@ -14,6 +14,9 @@ import * as ngwr_storage from 'ngwr/storage';
  *   lazily on the next `get` / `watch` read.
  * - **Reactive watch** — `watch(key)` returns a `Signal` that updates on
  *   local writes and cross-tab `storage` events.
+ * - **On-disk format** — values are wrapped in a {@link WrStorageEnvelope}
+ *   (`{"v":…,"e":…}`) while `json` is on. Anything reading the same key from
+ *   outside Angular has to unwrap it.
  *
  * SSR-safe: the default engine factory returns an in-memory shim when
  * `localStorage` is unavailable, so reads always work.
@@ -60,6 +63,11 @@ declare class WrStorage {
     /**
      * Write `value` at `key`. Per-call `ttl` (ms) overrides the config
      * default. JSON-serializable values only when `json` is on (the default).
+     *
+     * What lands in the engine is a {@link WrStorageEnvelope} —
+     * `{"v":<value>}`, plus `"e"` when a TTL applies — not the bare value. Code
+     * outside Angular that reads the same key has to unwrap it; see the envelope's
+     * own docs for the exact format.
      */
     set<T = unknown>(key: string, value: T, opts?: {
         ttl?: number;
@@ -118,6 +126,36 @@ interface WrStorageConfig {
 }
 /** Fully-resolved config (all defaults filled). @internal */
 type WrStorageConfigResolved = Required<WrStorageConfig>;
+/**
+ * The **on-disk format** `WrStorage` writes while `json` is on (the default).
+ *
+ * Public because it is a wire format, not an implementation detail: the value in
+ * `localStorage` is `JSON.stringify(envelope)`, so anything reading the same key
+ * from outside Angular — a pre-paint theme script in `index.html`, a service
+ * worker, a native shell, another framework on the same origin — has to know
+ * that a stored `'dark'` is spelled `{"v":"dark"}` and not `"dark"`. Left
+ * undocumented, the only way to learn that was to read the bundle.
+ *
+ * `e` is an absolute expiry in epoch milliseconds, written only when a TTL
+ * applies; a value past it reads as absent and is removed on the next `get`.
+ * A key holding anything else — a bare JSON value, or a string that is not JSON
+ * at all — is returned as it stands, so keys written by non-ngwr code keep
+ * working.
+ *
+ * @example
+ * ```jsonc
+ * // localStorage['wr-theme']
+ * { "v": "dark" }
+ * // localStorage['cart'], written with { ttl: 60_000 }
+ * { "v": [{ "sku": "a1" }], "e": 1767225600000 }
+ * ```
+ */
+interface WrStorageEnvelope<T = unknown> {
+    /** The stored value, as handed to `set()`. */
+    readonly v: T;
+    /** Absolute expiry, epoch ms. Absent when the write carried no TTL. */
+    readonly e?: number;
+}
 
 declare const DEFAULT_WR_STORAGE_CONFIG: WrStorageConfigResolved;
 declare const WR_STORAGE_CONFIG: InjectionToken<Required<ngwr_storage.WrStorageConfig>>;
@@ -185,4 +223,4 @@ interface ProvideWrStorageOptions extends WrStorageConfig {
 declare function provideWrStorage(options?: ProvideWrStorageOptions): EnvironmentProviders;
 
 export { DEFAULT_WR_STORAGE_CONFIG, WR_STORAGE_CONFIG, WR_STORAGE_ENGINE, WrStorage, createMemoryStorage, provideWrStorage };
-export type { ProvideWrStorageOptions, WrStorageConfig, WrStorageConfigResolved, WrStorageEngine };
+export type { ProvideWrStorageOptions, WrStorageConfig, WrStorageConfigResolved, WrStorageEngine, WrStorageEnvelope };

package/types/ngwr-textarea.d.ts

@@ -71,6 +71,26 @@ declare class WrTextarea implements FormValueControl<string> {
     protected readonly effectiveResize: _angular_core.Signal<WrTextareaResize>;
     /** The surrounding `<wr-form-field>`'s error state. @internal */
     protected readonly fieldAria: ngwr_form.WrFormFieldAria;
+    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-select` do. Without it the `for` named an element that
+     * was nowhere in the document: clicking the label did nothing, and the field
+     * was, to a screen reader, an unlabelled block.
+     *
+     * It lands on the native `<textarea>` rather than on the host, because only a
+     * labelable element can be a label's target and `<wr-textarea>` is not one.
+     *
+     * What it does NOT change is the NAME: `aria-label` outranks a `<label>` in
+     * the accname order and `resolvedAriaLabel()` still wins, the same call
+     * `wr-select` and `wr-slider` make — the field renders a label only when its
+     * `label` input is set, so it cannot promise a name to fall back on. Set
+     * `[ariaLabel]` to the field's label where the two should read alike.
+     */
+    protected readonly controlId: _angular_core.Signal<string | null>;
     protected readonly classes: _angular_core.Signal<string>;
     /** Show the corner grip (hidden when direction is 'none' / autosize / disabled). */
     protected readonly showHandle: _angular_core.Signal<boolean>;

package/types/ngwr-theme.d.ts

@@ -164,6 +164,15 @@ declare const WR_THEME_CONFIG: InjectionToken<WrThemeConfig>;
  * `@use 'ngwr' with ($theme-attribute: '...')`. In dev mode the service compares
  * the two and warns when they disagree.
  *
+ * **Under SSR or prerendering this service cannot prevent a flash of the wrong
+ * theme, and nothing inside the application can.** The server has no
+ * `localStorage` and no `prefers-color-scheme`, so every rendered page ships the
+ * same attribute (`light` under the default config); by the time the client
+ * bundle boots and the effect below corrects it, the browser has already
+ * painted. Closing that window takes a script that runs before first paint —
+ * {@link wrThemePrePaintScript} emits one that reads the persisted mode exactly
+ * the way this service does.
+ *
  * @example
  * ```ts
  * const theme = inject(WrTheme);
@@ -237,5 +246,86 @@ declare class WrTheme {
  */
 declare function provideWrTheme(config?: Partial<WrThemeConfig>): EnvironmentProviders;
 
-export { DEFAULT_WR_THEME_CONFIG, WR_COLORS, WR_THEME_CONFIG, WrTheme, provideWrTheme, wrContrastFor, wrIntentTokens, wrThemeTokens };
-export type { WrColor, WrResolvedTheme, WrThemeConfig, WrThemeMode };
+/**
+ * @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
+ */
+
+/** Options for {@link wrThemePrePaintScript}. All optional — defaults mirror the services. */
+interface WrThemePrePaintOptions {
+    /**
+     * The key {@link WrTheme} persists the mode under — `provideWrTheme({ storageKey })`.
+     * @default 'wr-theme'
+     */
+    readonly storageKey?: string;
+    /**
+     * The attribute written on `<html>` — `provideWrTheme({ attribute })`, which
+     * has to agree with `@use 'ngwr' with ($theme-attribute: '…')`.
+     * @default 'data-theme'
+     */
+    readonly attribute?: string;
+    /**
+     * What to resolve when nothing is persisted — `provideWrTheme({ defaultMode })`.
+     * @default 'auto'
+     */
+    readonly defaultMode?: WrThemeMode;
+    /**
+     * `WrStorage`'s key prefix — `provideWrStorage({ prefix })`. The script reads
+     * the raw key, so a prefixed app has to pass the same string here.
+     * @default ''
+     */
+    readonly storagePrefix?: string;
+    /**
+     * Whether `WrStorage` wraps values in its JSON envelope —
+     * `provideWrStorage({ json })`. The emitted reader accepts both shapes either
+     * way; this only decides which one it tries first, and is here so the option
+     * cannot be silently forgotten when an app turns the envelope off.
+     * @default true
+     */
+    readonly json?: boolean;
+}
+/**
+ * Source of the blocking script that resolves the theme BEFORE first paint.
+ *
+ * A server has no `localStorage` and no `prefers-color-scheme`, so every
+ * server-rendered or prerendered page ships the same attribute — `light` under
+ * the default config — and a dark-mode visitor sees a white page until the
+ * client bundle boots and {@link WrTheme}'s effect corrects it. That window is
+ * milliseconds on localhost and seconds on a slow connection, and it is not
+ * something the service can close from inside the application: by the time
+ * Angular runs, the paint has happened.
+ *
+ * The only fix is a script that runs before the first paint, and the only thing
+ * it needs to know is how {@link WrTheme} and `WrStorage` agree to spell the
+ * persisted mode. That agreement — the key, the prefix, the JSON envelope
+ * `{ v, e }`, the expiry, the `auto` fallback — is what this function writes
+ * out, so an app never has to re-derive it from the bundle and never has to keep
+ * a hand-copied version in step with a library upgrade.
+ *
+ * Returns the JS source WITHOUT a `<script>` wrapper, so it can be inlined into
+ * `index.html`, emitted from an SSR template, or hashed for a CSP
+ * `script-src 'sha256-…'`. It is plain ES5 with no dependency on the app bundle,
+ * and every step is wrapped so a blocked `localStorage` (private mode, a
+ * sandboxed iframe) leaves the prerendered default in place rather than throwing
+ * before anything has rendered.
+ *
+ * Pass the same values given to `provideWrTheme()` / `provideWrStorage()`; the
+ * defaults here are the defaults there.
+ *
+ * @example
+ * ```ts
+ * // Build step / SSR template:
+ * const html = template.replace('<!--theme-->', `<script>${wrThemePrePaintScript()}</script>`);
+ *
+ * // Or paste the output straight into <head>, above every stylesheet:
+ * // <script>(function(){ … })();</script>
+ * ```
+ *
+ * @see https://ngwr.dev/reference/services/theme
+ */
+declare function wrThemePrePaintScript(options?: WrThemePrePaintOptions): string;
+
+export { DEFAULT_WR_THEME_CONFIG, WR_COLORS, WR_THEME_CONFIG, WrTheme, provideWrTheme, wrContrastFor, wrIntentTokens, wrThemePrePaintScript, wrThemeTokens };
+export type { WrColor, WrResolvedTheme, WrThemeConfig, WrThemeMode, WrThemePrePaintOptions };

package/types/ngwr-toast.d.ts

@@ -166,6 +166,8 @@ declare class WrToast {
     private readonly config;
     private overlayRef;
     private hostRef;
+    /** Watches the overlay container for overlays opened after the host. */
+    private containerObserver;
     private currentPosition;
     private currentMode;
     private nextId;
@@ -187,6 +189,49 @@ declare class WrToast {
     private startTimer;
     private pauseTimer;
     private ensureHost;
+    /**
+     * Put the host back on top of the browser's top layer.
+     *
+     * The stacking rule here is not a z-index and cannot be fixed with one. CDK 22
+     * promotes every overlay by calling `showPopover()` on its host element, and
+     * the top layer is ordered by the MOMENT of promotion — a popover shown later
+     * paints over one shown earlier no matter what either element's z-index, DOM
+     * order or containing block says. The toast host is created once and kept
+     * alive until the last toast leaves, so its place in that order is frozen at
+     * whenever the first toast of the run appeared. Every dialog and drawer opened
+     * after that sits above it.
+     *
+     * The symptom was as bad as the mechanism is quiet: a toast raised from inside
+     * an open dialog rendered UNDER the dialog's backdrop, dimmed by it and
+     * hit-tested as it — so the close button was unreachable and clicking where it
+     * appeared closed the dialog instead. Nothing threw, and a toast with
+     * `duration: 0` never went away on its own.
+     *
+     * Hiding and re-showing moves the host to the end of the top layer. Both calls
+     * happen in one task, so there is no frame in which the host is `display:
+     * none` and nothing re-runs a toast's enter animation.
+     *
+     * Skipped while focus is inside the host: Chromium keeps focus across this
+     * pair, but the hide-popover algorithm is specified to restore focus to the
+     * previously focused element, and a host the user is already tabbing through
+     * is by definition reachable. In practice the two never coincide — a modal
+     * traps focus, so focus inside the host means nothing is above it to escape.
+     */
+    private raiseHost;
+    /**
+     * Re-raise the host whenever another overlay joins the container.
+     *
+     * `show()` covers the reported order (toast raised while a dialog is up). This
+     * covers the mirror image, which is the same defect seen from the other side:
+     * a toast already on screen when the dialog opens is left under it, unclickable
+     * for the rest of its duration, and no further `show()` is coming to fix it.
+     *
+     * Observing the host's own parent rather than a container resolved from the
+     * injector keeps this correct whether or not `provideWrOverlay()` is installed
+     * — the host is in whichever container it was actually appended to. Re-showing
+     * a popover moves nothing in the DOM, so this cannot re-trigger itself.
+     */
+    private watchForNewerOverlays;
     /** Fill any free stack slots from the queue (FIFO), starting each promoted
      * toast's auto-dismiss timer only as it becomes visible. */
     private promoteFromQueue;
@@ -222,6 +267,14 @@ declare class WrToast {
  *   ],
  * });
  * ```
+ *
+ * **Bootstrap only, and the three ngwr providers differ here.** {@link WrToast}
+ * is root-provided, so it reads this token once from the ROOT injector — a
+ * `provideWrToastConfig()` in a route's `providers` is never seen, and used to
+ * be ignored in silence. It now warns in dev mode instead. By contrast
+ * `provideWrConfig()` IS read per route, because components resolve it from
+ * their own injector, and `provideWrIcons()` works at any level and chains, so
+ * a route may add icons to the set its parent registered.
  */
 declare function provideWrToastConfig(config: Partial<Omit<WrToastConfig, 'labels'>> & {
     readonly labels?: Partial<WrToastConfig['labels']>;

package/types/ngwr-tree.d.ts

@@ -165,8 +165,9 @@ declare class WrTree<TId = string> implements FormValueControl<unknown> {
     /**
      * Form value — the current selection as seen by a bound field. Bound by
      * `[formField]`, or two-way via `[(value)]`. Shape follows `selectionMode`:
-     * `TId | null` in single mode, `readonly TId[]` in multi mode. Meaningful in
-     * `overlay` mode; inline mode drives selection via `[(selected)]` instead.
+     * `TId | null` in single mode, `readonly TId[]` in multi mode. Works in both
+     * `openOn` modes; `[(selected)]` stays the inline-native API and always
+     * carries an array, whatever the selection mode.
      */
     readonly value: _angular_core.ModelSignal<unknown>;
     /** Emitted on blur so a bound field can mark itself touched. */

package/types/ngwr-version.d.ts

@@ -16,7 +16,7 @@ import { InjectionToken } from '@angular/core';
  * Distinct from `Version` exported by `@angular/core`, which reports the
  * loaded Angular runtime version (e.g. `'22.0.0'`), not ngwr's.
  */
-declare const NGWR_VERSION = "14.0.0";
+declare const NGWR_VERSION = "14.1.0";
 
 /**
  * @license

package/waves/styles/_dark.scss

@@ -0,0 +1,19 @@
+// Dark theme.
+//
+// Keyed on `theme.dark-selector()`, never on a literal `[data-theme='dark']`.
+// The attribute is renameable — `@use 'ngwr' with ($theme-attribute: '…')`
+// alongside `provideWrTheme({ attribute: '…' })` — and a hand-written literal
+// misses the rename in both directions: this block stops firing under the
+// configured name, and it keeps firing under `data-theme`, which is the
+// attribute a foreign design system owns and the rename exists to escape.
+//
+// It lives outside the `styleUrl` closure for the same reason. A component
+// stylesheet is compiled when the LIBRARY is built, where `$theme-attribute` can
+// only ever be the default, and Angular appends that copy after the app's linked
+// sheet — so an inlined literal would not merely be dead, it would outrank the
+// correctly-named rule beside it.
+@use '../../theme/styles' as theme;
+
+#{theme.dark-selector()} .wr-waves {
+  --wr-waves-line-color: rgb(255 255 255 / 14%);
+}

package/waves/styles/_index.scss

@@ -11,5 +11,10 @@
 // box-sizing reset into the compiled component styles, which ng-packagr then
 // embeds in the FESM bundle as a string. `waves.scss` forwards `_rules`
 // instead, so it carries this component's own CSS and nothing else.
+//
+// `_dark` is loaded from HERE for a second reason: its selector is built out of
+// `$theme-attribute`, which only a stylesheet compiled by the consuming app can
+// configure, so a copy inside the bundle could only ever carry the default name.
 @use '../../theme/styles';
 @forward 'rules';
+@forward 'dark';

package/waves/styles/_rules.scss

@@ -40,6 +40,3 @@
   }
 }
 
-[data-theme='dark'] .wr-waves {
-  --wr-waves-line-color: rgb(255 255 255 / 14%);
-}