ngwr 8.0.0 → 9.0.0

package/types/ngwr-toast.d.ts

@@ -137,7 +137,7 @@ declare class WrToastRef {
  * toast.show({ message: 'Permalink copied', position: 'bottom', showCopy: true });
  * ```
  *
- * @see https://ngwr.dev/components/toast
+ * @see https://ngwr.dev/reference/components/toast
  */
 declare class WrToast {
     private readonly overlay;

package/types/ngwr-toolbar.d.ts

@@ -20,7 +20,7 @@ import * as i0 from '@angular/core';
  * </wr-toolbar>
  * ```
  *
- * @see https://ngwr.dev/components/toolbar
+ * @see https://ngwr.dev/reference/components/toolbar
  */
 declare class WrToolbar {
     /**

package/types/ngwr-tree.d.ts

@@ -1,7 +1,7 @@
 import * as ngwr_i18n from 'ngwr/i18n';
 import * as _angular_core from '@angular/core';
 import { TemplateRef } from '@angular/core';
-import { ControlValueAccessor } from '@angular/forms';
+import { FormValueControl } from '@angular/forms/signals';
 
 /**
  * @license
@@ -23,6 +23,12 @@ interface FlatNode<TId> {
     readonly node: WrTreeNode<TId>;
     readonly depth: number;
     readonly hasChildren: boolean;
+    /** Absolute position in the flattened visible list. */
+    readonly index: number;
+    /** 1-based position within its sibling group (ARIA `aria-posinset`). */
+    readonly posinset: number;
+    /** Sibling count at this level (ARIA `aria-setsize`). */
+    readonly setsize: number;
 }
 interface SelectedChip<TId> {
     readonly id: TId;
@@ -38,9 +44,11 @@ interface SelectedChip<TId> {
  * - `'inline'` (default) — renders the tree list in-place. Use as a display
  *   widget or form-less hierarchical picker.
  * - `'overlay'` — renders a `<wr-select>`-style trigger button (with chips
- *   in multi mode) that opens a popover containing the tree. Acts as a
- *   `ControlValueAccessor` — bind via `[(ngModel)]`, `[formControl]`, or
- *   `formControlName`. Replaces the standalone `<wr-tree-select>`.
+ *   in multi mode) that opens a popover containing the tree. A signal-forms
+ *   native control: it implements `FormValueControl<unknown>`, so `[formField]`
+ *   binds straight to its `value` model — no `ControlValueAccessor` in between.
+ *   `[(value)]` and classic `[(ngModel)]` / reactive forms all keep working via
+ *   Angular's bridge. Replaces the standalone `<wr-tree-select>`.
  *
  * Value type in `overlay` mode: `TId | null` in single mode,
  * `readonly TId[]` in multi mode.
@@ -50,19 +58,22 @@ interface SelectedChip<TId> {
  * <!-- Inline tree (display widget) -->
  * <wr-tree [nodes]="folders" [(selected)]="picked" [(expanded)]="open" />
  *
- * <!-- Form-bound combobox -->
+ * <!-- Form-bound combobox (signal forms) -->
  * <wr-tree
  *   openOn="overlay"
  *   [nodes]="folders"
  *   selectionMode="single"
- *   [(ngModel)]="picked"
+ *   [formField]="form.folder"
  *   placeholder="Pick a folder"
  * />
+ *
+ * <!-- standalone two-way binding -->
+ * <wr-tree openOn="overlay" [nodes]="folders" [(value)]="picked" placeholder="Pick a folder" />
  * ```
  *
- * @see https://ngwr.dev/components/tree
+ * @see https://ngwr.dev/reference/components/tree
  */
-declare class WrTree<TId = string> implements ControlValueAccessor {
+declare class WrTree<TId = string> implements FormValueControl<unknown> {
     /** Tree data. */
     readonly nodes: _angular_core.InputSignal<readonly WrTreeNode<TId>[]>;
     /** Selected node ids (two-way bindable). */
@@ -71,7 +82,12 @@ declare class WrTree<TId = string> implements ControlValueAccessor {
     readonly expanded: _angular_core.ModelSignal<readonly TId[]>;
     /** Selection behavior. @default 'single' */
     readonly selectionMode: _angular_core.InputSignal<WrTreeSelectionMode>;
-    /** Disable the whole tree. @default false */
+    /**
+     * Disable the whole tree. Bound automatically from the field's disabled
+     * state when used with `[formField]`.
+     *
+     * @default false
+     */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
     /** Render shape. @default 'inline' */
     readonly openOn: _angular_core.InputSignal<"inline" | "overlay">;
@@ -87,11 +103,45 @@ declare class WrTree<TId = string> implements ControlValueAccessor {
     readonly maxTagCount: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Auto-expand every node that has children on first open of the overlay. @default false */
     readonly defaultExpandAll: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Window the visible-node list so a large tree keeps only ~one viewport of
+     * rows in the DOM. Opt-in and OFF by default — a tree without it renders
+     * byte-identically to today. Works in both `inline` and `overlay` shapes;
+     * while on, keyboard navigation switches to the `aria-activedescendant`
+     * pattern so Arrow / Home / End / Enter keep working across un-rendered rows.
+     * @default false
+     */
+    readonly virtualScroll: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Uniform row height in px used to map scroll offset to node index. `0`
+     * (default) measures the first rendered row once and reuses it, so it adapts
+     * to the active density / touch target automatically. Read only when
+     * `virtualScroll` is on. @default 0
+     */
+    readonly rowHeight: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Height of the scroll viewport when `virtualScroll` is on — a number (px) or
+     * any CSS length (`'60vh'`). A numeric px value lets the server prerender the
+     * exact first window. @default 288
+     */
+    readonly viewportHeight: _angular_core.InputSignal<string | number>;
+    /** Extra rows kept rendered above and below the viewport as scroll headroom. @default 6 */
+    readonly overscan: _angular_core.InputSignalWithTransform<number, 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.
+     */
+    readonly value: _angular_core.ModelSignal<unknown>;
+    /** Emitted on blur so a bound field can mark itself touched. */
+    readonly touch: _angular_core.OutputEmitterRef<void>;
     private readonly host;
     private readonly overlay;
     private readonly vcr;
     private readonly scrollStrategies;
     private readonly destroyRef;
+    private readonly platformId;
     /** Currently focused row's index in the flattened visible list. */
     protected readonly focusedIndex: _angular_core.WritableSignal<number>;
     /** Resolved ARIA labels — pick up live locale changes via re-render. */
@@ -116,23 +166,54 @@ declare class WrTree<TId = string> implements ControlValueAccessor {
     protected readonly open: _angular_core.WritableSignal<boolean>;
     /** Trigger / panel id for `aria-controls`. */
     protected readonly panelId: string;
-    private readonly disabledFromCva;
-    protected readonly isDisabled: _angular_core.Signal<boolean>;
     protected readonly classes: _angular_core.Signal<string>;
     protected readonly panelTpl: _angular_core.Signal<TemplateRef<any> | undefined>;
     private overlayRef;
-    private onChange;
-    /** @internal exposed so the trigger can fire on blur. */
-    protected onTouched: () => void;
+    private static readonly FALLBACK_ROW_PX;
+    private static readonly FALLBACK_VIEWPORT_PX;
+    /** Live vertical scroll offset (px); 0 on the server / before first scroll. */
+    private readonly scrollTop;
+    /** Measured viewport clientHeight (px); 0 until the browser observer fires. */
+    private readonly viewportPx;
+    /** Measured first-row height (px) when `rowHeight` is auto; 0 until measured. */
+    private readonly measuredRowPx;
+    /** Virtualization active (opt-in and there is anything to window). */
+    protected readonly virtualized: _angular_core.Signal<boolean>;
+    /** Effective uniform row height (px). */
+    protected readonly effRowH: _angular_core.Signal<number>;
+    /** Deterministic viewport px for SSR + first paint (numeric height, else fallback). */
+    private readonly fallbackViewportPx;
+    /** `viewportHeight` as a CSS length for the inline max-height (bare number → px). */
+    protected readonly resolvedViewportHeight: _angular_core.Signal<string>;
+    /** Rendered window [start,end) + spacer pads (px). Pure math from `scrollTop`. */
+    protected readonly virtualWindow: _angular_core.Signal<{
+        start: number;
+        end: number;
+        padTop: number;
+        padBottom: number;
+    }>;
+    /** Nodes placed in the list. SAME array instance as `flat()` when off → byte-identical DOM. */
+    protected readonly windowRows: _angular_core.Signal<readonly FlatNode<TId>[]>;
+    /** Stable id for a row at flat index `i` — the `aria-activedescendant` target. */
+    protected rowId(i: number): string;
+    /**
+     * Active-descendant id when virtualized (focus stays on the list container),
+     * else `null`. Returns `null` while the focused row is outside the rendered
+     * window (e.g. mouse-wheeled away) so `aria-activedescendant` never dangles at
+     * a removed element — the next arrow key scrolls it back and re-establishes it.
+     */
+    protected readonly activeRowId: _angular_core.Signal<string | null>;
+    /** The scrollable `<ul>` — inside the overlay panel in overlay mode, else in the host. */
+    private get listElement();
+    /** Scroll flat index `i` just into view (sets the `scrollTop` signal synchronously). */
+    private ensureVisible;
     constructor();
-    writeValue(value: unknown): void;
-    registerOnChange(fn: (value: TId | readonly TId[] | null) => void): void;
-    registerOnTouched(fn: () => void): void;
-    setDisabledState(isDisabled: boolean): void;
     protected onRowClick(flat: FlatNode<TId>, event: MouseEvent): void;
     protected onToggleClick(node: WrTreeNode<TId>, event: MouseEvent): void;
     protected onKeydown(event: KeyboardEvent): void;
     protected onTriggerClick(): void;
+    /** Trigger blur — mark the bound field touched. */
+    protected onBlur(): void;
     protected removeChip(id: TId, event: Event): void;
     protected clearSelection(event: Event): void;
     private toggleExpanded;
@@ -143,7 +224,7 @@ declare class WrTree<TId = string> implements ControlValueAccessor {
     private openOverlay;
     private closeOverlay;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrTree<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrTree<any>, "wr-tree", never, { "nodes": { "alias": "nodes"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "openOn": { "alias": "openOn"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "maxTagCount": { "alias": "maxTagCount"; "required": false; "isSignal": true; }; "defaultExpandAll": { "alias": "defaultExpandAll"; "required": false; "isSignal": true; }; }, { "selected": "selectedChange"; "expanded": "expandedChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrTree<any>, "wr-tree", never, { "nodes": { "alias": "nodes"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "openOn": { "alias": "openOn"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "maxTagCount": { "alias": "maxTagCount"; "required": false; "isSignal": true; }; "defaultExpandAll": { "alias": "defaultExpandAll"; "required": false; "isSignal": true; }; "virtualScroll": { "alias": "virtualScroll"; "required": false; "isSignal": true; }; "rowHeight": { "alias": "rowHeight"; "required": false; "isSignal": true; }; "viewportHeight": { "alias": "viewportHeight"; "required": false; "isSignal": true; }; "overscan": { "alias": "overscan"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "selected": "selectedChange"; "expanded": "expandedChange"; "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
 }
 
 export { WrTree };

package/types/ngwr-typography.d.ts

@@ -31,7 +31,7 @@ type WrTypographyTone = 'dark' | 'medium' | 'primary' | 'success' | 'warning' |
  * <code wrTypography variant="code">inject(WrTheme)</code>
  * ```
  *
- * @see https://ngwr.dev/typography/overview
+ * @see https://ngwr.dev/guides/typography/overview
  */
 declare class WrTypography {
     /** Visual variant. @default 'body' */

package/types/ngwr-validators.d.ts

@@ -30,7 +30,7 @@ import { AbstractControl, ValidationErrors, ValidatorFn } from '@angular/forms';
  * Anything Angular already ships (`required`, `email`, `min`, `max`,
  * `pattern`, …) is deliberately NOT duplicated here.
  *
- * @see https://ngwr.dev/validators
+ * @see https://ngwr.dev/reference/validators
  */
 declare const WrValidators: {
     /** No whitespace anywhere in the value. */

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. `'21.2.13'`), not ngwr's.
  */
-declare const NGWR_VERSION = "8.0.0";
+declare const NGWR_VERSION = "9.0.0";
 
 /**
  * @license

package/types/ngwr-virtual-scroll.d.ts

@@ -18,7 +18,7 @@ import { CdkVirtualScrollViewport } from '@angular/cdk/scrolling';
  * </wr-virtual-scroll>
  * ```
  *
- * @see https://ngwr.dev/components/virtual-scroll
+ * @see https://ngwr.dev/reference/components/virtual-scroll
  */
 declare class WrVirtualScroll<T = unknown> {
     /** Items to render. */

package/types/ngwr-window.d.ts

@@ -418,7 +418,7 @@ declare class WrWindowManager {
  * <wr-window-taskbar position="top" />
  * ```
  *
- * @see https://ngwr.dev/components/window
+ * @see https://ngwr.dev/reference/components/window
  */
 declare class WrWindowTaskbar {
     /** Edge the taskbar pins itself to. @default 'bottom' */

package/typography/styles/_index.scss

@@ -3,7 +3,7 @@
 .wr-typography {
   // Inherit the host element's native display (block for h1/p, inline for span).
   margin: 0;
-  color: var(--wr-color-dark);
+  color: var(--wr-color-on-surface);
   font-family: var(--wr-font-family-base);
 
   &--display {
@@ -56,7 +56,7 @@
     font-size: var(--wr-text-xl);
     font-weight: var(--wr-font-weight-regular);
     line-height: var(--wr-leading-relaxed);
-    color: var(--wr-color-medium);
+    color: var(--wr-color-on-surface-muted);
   }
 
   &--body {
@@ -73,7 +73,7 @@
   &--caption {
     font-size: var(--wr-text-xs);
     line-height: var(--wr-leading-normal);
-    color: var(--wr-color-medium);
+    color: var(--wr-color-on-surface-muted);
   }
 
   &--overline {
@@ -81,12 +81,12 @@
     font-weight: var(--wr-font-weight-semibold);
     text-transform: uppercase;
     letter-spacing: var(--wr-tracking-widest);
-    color: var(--wr-color-medium);
+    color: var(--wr-color-on-surface-muted);
   }
 
   &--code {
     padding: 0.0625rem 0.375rem;
-    background: rgba(var(--wr-color-light-rgb), 0.6);
+    background: rgba(var(--wr-color-outline-rgb), 0.6);
     border-radius: var(--wr-border-radius-sm);
     font-size: 0.875em;
   }
@@ -99,7 +99,7 @@
     padding: 0;
     font-size: var(--wr-text-base);
     line-height: var(--wr-leading-normal);
-    color: var(--wr-color-medium);
+    color: var(--wr-color-on-surface-muted);
 
     > li + li,
     > li > ul,
@@ -133,19 +133,19 @@
 
     dl#{&}--list dt {
       margin-bottom: 0.25rem;
-      color: var(--wr-color-medium);
+      color: var(--wr-color-on-surface-muted);
     }
 
     dl#{&}--list dd {
       font-size: var(--wr-text-lg);
       font-weight: var(--wr-font-weight-medium);
-      color: var(--wr-color-dark);
+      color: var(--wr-color-on-surface);
     }
 
     dl#{&}--list dd + dt {
       margin-top: 0.75rem;
       padding-top: 0.75rem;
-      border-top: 1px solid var(--wr-color-light);
+      border-top: 1px solid var(--wr-color-outline);
     }
   }
 
@@ -165,10 +165,10 @@
 
   // Tones
   &--tone-dark {
-    color: var(--wr-color-dark);
+    color: var(--wr-color-on-surface);
   }
   &--tone-medium {
-    color: var(--wr-color-medium);
+    color: var(--wr-color-on-surface-muted);
   }
   &--tone-primary {
     color: var(--wr-color-primary);

package/virtual-scroll/styles/_index.scss

@@ -20,7 +20,7 @@
       height: 0.5rem;
     }
     &::-webkit-scrollbar-thumb {
-      background: rgba(var(--wr-color-dark-rgb), 0.2);
+      background: rgba(var(--wr-color-on-surface-rgb), 0.2);
       border-radius: 999px;
     }
   }

package/waves/styles/_index.scss

@@ -3,7 +3,7 @@
 // `--wr-waves-line-color` unless `[lineColor]` overrides it.
 
 .wr-waves {
-  --wr-waves-line-color: rgba(var(--wr-color-dark-rgb), 0.12);
+  --wr-waves-line-color: rgba(var(--wr-color-on-surface-rgb), 0.12);
 
   position: absolute;
   inset: 0;

package/window/styles/_index.scss

@@ -1,10 +1,10 @@
 @use '../../theme/styles' as theme;
 
 .wr-window {
-  --wr-window-bg: var(--wr-color-white);
-  --wr-window-border: var(--wr-color-light);
+  --wr-window-bg: var(--wr-color-surface);
+  --wr-window-border: var(--wr-color-outline);
   --wr-window-chrome-bg: var(--wr-color-hover);
-  --wr-window-chrome-color: var(--wr-color-dark);
+  --wr-window-chrome-color: var(--wr-color-on-surface);
   --wr-window-radius: var(--wr-border-radius-base);
   --wr-window-handle-size: 8px;
   --wr-window-chrome-height: 2.25rem;
@@ -20,7 +20,7 @@
   @include theme.smooth-br(var(--wr-window-radius));
   box-shadow: var(--wr-shadow-modal);
   font-family: var(--wr-font-family-base);
-  color: var(--wr-color-dark);
+  color: var(--wr-color-on-surface);
   overflow: hidden;
   user-select: none;
   // Enter animation — popover-style fade + scale-up. Disabled by
@@ -118,7 +118,7 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    color: var(--wr-color-medium);
+    color: var(--wr-color-on-surface-muted);
     cursor: pointer;
     border-radius: var(--wr-border-radius-sm);
     transition:
@@ -126,12 +126,12 @@
       background var(--wr-transition-base);
 
     &:hover {
-      color: var(--wr-color-dark);
-      background: rgba(var(--wr-color-light-rgb), 0.6);
+      color: var(--wr-color-on-surface);
+      background: rgba(var(--wr-color-outline-rgb), 0.6);
     }
 
     &--close:hover {
-      color: var(--wr-color-white);
+      color: var(--wr-color-surface);
       background: var(--wr-color-danger);
     }
   }
@@ -222,9 +222,9 @@
     gap: 0.5rem;
     padding: 0.25rem 0.75rem;
     border-top: 1px solid var(--wr-window-border);
-    background: rgba(var(--wr-color-light-rgb), 0.25);
+    background: rgba(var(--wr-color-outline-rgb), 0.25);
     font-size: var(--wr-text-xs);
-    color: var(--wr-color-medium);
+    color: var(--wr-color-on-surface-muted);
 
     &:empty {
       display: none;
@@ -345,10 +345,10 @@
   font-family: var(--wr-font-family-base);
 
   &--bottom {
-    bottom: 0.75rem;
+    bottom: calc(0.75rem + env(safe-area-inset-bottom));
   }
   &--top {
-    top: 0.75rem;
+    top: calc(0.75rem + env(safe-area-inset-top));
   }
 
   &__rail {
@@ -356,8 +356,8 @@
     align-items: center;
     gap: 0.25rem;
     padding: 0.25rem;
-    background: var(--wr-color-white);
-    border: 1px solid var(--wr-color-light);
+    background: var(--wr-color-surface);
+    border: 1px solid var(--wr-color-outline);
     @include theme.smooth-br(var(--wr-border-radius-base));
     box-shadow: var(--wr-shadow-overlay);
     pointer-events: auto;
@@ -372,7 +372,7 @@
     gap: 0.375rem;
     padding: 0.25rem 0.5rem 0.25rem 0.75rem;
     border-radius: var(--wr-border-radius-sm);
-    color: var(--wr-color-dark);
+    color: var(--wr-color-on-surface);
     font-family: inherit;
     font-size: var(--wr-text-sm);
     line-height: 1.25rem;
@@ -383,7 +383,7 @@
       color var(--wr-transition-base);
 
     &:hover {
-      background: rgba(var(--wr-color-light-rgb), 0.6);
+      background: rgba(var(--wr-color-outline-rgb), 0.6);
     }
 
     &:focus-visible {
@@ -408,11 +408,11 @@
     align-items: center;
     justify-content: center;
     border-radius: var(--wr-border-radius-sm);
-    color: var(--wr-color-medium);
+    color: var(--wr-color-on-surface-muted);
     cursor: pointer;
 
     &:hover {
-      color: var(--wr-color-white);
+      color: var(--wr-color-surface);
       background: var(--wr-color-danger);
     }
   }