ngwr 14.0.0 → 14.0.1

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.0.1";
 
 /**
  * @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%);
-}