ngwr 8.0.0 → 9.0.0

package/types/ngwr-pagination.d.ts

@@ -54,7 +54,7 @@ type PageEntry = number | typeof ELLIPSIS;
  * />
  * ```
  *
- * @see https://ngwr.dev/components/pagination
+ * @see https://ngwr.dev/reference/components/pagination
  */
 declare class WrPagination {
     /** Currently displayed page (1-based). Two-way bindable. */

package/types/ngwr-platform.d.ts

@@ -20,7 +20,7 @@ import { Signal } from '@angular/core';
  * protected readonly dark = this.platform.prefersDark;
  * ```
  *
- * @see https://ngwr.dev/services/platform
+ * @see https://ngwr.dev/reference/services/platform
  */
 declare class WrPlatform {
     private readonly destroyRef;
@@ -35,4 +35,95 @@ declare class WrPlatform {
     static ɵprov: i0.ɵɵInjectableDeclaration<WrPlatform>;
 }
 
-export { WrPlatform };
+/**
+ * SSR-safe view onto `window.visualViewport` — the part of the layout viewport
+ * actually visible once the on-screen keyboard (or other browser chrome) is
+ * accounted for.
+ *
+ * - `bottomInset` — px hidden at the bottom of the layout viewport (the
+ *   keyboard height); `0` when nothing covers it, on the server, or in browsers
+ *   without the API.
+ * - `offsetTop` — how far the visual viewport is pushed/scrolled down.
+ *
+ * While active it also mirrors `bottomInset` onto `--wr-keyboard-inset` on the
+ * document root, so purely presentational surfaces (the responsive overlay
+ * sheet, the command-palette sheet) can lift above the keyboard with CSS alone.
+ *
+ * @see https://ngwr.dev/reference/services/platform
+ */
+declare class WrVisualViewport {
+    private readonly destroyRef;
+    private readonly doc;
+    private readonly isBrowser;
+    private readonly _bottomInset;
+    private readonly _offsetTop;
+    /** Height (px) the keyboard / browser chrome hides at the viewport bottom. */
+    readonly bottomInset: Signal<number>;
+    /** The visual viewport's top offset (px). */
+    readonly offsetTop: Signal<number>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<WrVisualViewport, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WrVisualViewport>;
+}
+
+/** Impact weight for {@link WrHaptics.impact}. */
+type WrHapticImpact = 'light' | 'medium' | 'heavy';
+/**
+ * SSR-safe wrapper around the Vibration API for tactile feedback on touch
+ * devices. Semantic presets (`impact`, `selection`, `success`, `warning`,
+ * `error`) map to sensible vibration patterns so call sites stay readable.
+ *
+ * Every method is a no-op — returning `false` — when there is no support:
+ * on the server, in browsers without `navigator.vibrate`, and notably on
+ * **iOS Safari**, which does not expose the Vibration API at all (its
+ * haptics are native-only). Check {@link supported} to branch UI on it.
+ *
+ * Haptics are best paired with a real user gesture (tap) — some browsers
+ * ignore `vibrate()` calls that aren't triggered by one. This service does
+ * not gate on `prefers-reduced-motion`; read {@link WrPlatform.prefersReducedMotion}
+ * at the call site if you want to suppress feedback for those users.
+ *
+ * @example
+ * ```ts
+ * private readonly haptics = inject(WrHaptics);
+ *
+ * onDelete(): void {
+ *   this.haptics.warning();       // buzz before a destructive confirm
+ * }
+ *
+ * onToggle(): void {
+ *   this.haptics.selection();     // subtle tick on a switch / segmented change
+ * }
+ * ```
+ *
+ * @see https://ngwr.dev/reference/services/platform
+ */
+declare class WrHaptics {
+    private readonly isBrowser;
+    private readonly nav;
+    /** Whether the Vibration API is available (browser + `navigator.vibrate`). */
+    readonly supported: boolean;
+    /**
+     * Fire a raw vibration pattern — a single duration in ms, or an alternating
+     * `[buzz, pause, buzz, …]` array. Returns whether it was dispatched; passing
+     * `0` / `[]` cancels any ongoing vibration.
+     */
+    vibrate(pattern: number | readonly number[]): boolean;
+    /** A physical "tap" — `light`, `medium` (default), or `heavy`. */
+    impact(strength?: WrHapticImpact): boolean;
+    /** A subtle tick for a discrete change (switch, segmented, stepper). */
+    selection(): boolean;
+    /** A confirming pulse for a completed action. */
+    success(): boolean;
+    /** A cautioning pulse before a risky or destructive action. */
+    warning(): boolean;
+    /** A buzzing pulse for a failure or rejected action. */
+    error(): boolean;
+    /** Cancel any in-progress vibration. */
+    stop(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WrHaptics, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WrHaptics>;
+}
+
+export { WrHaptics, WrPlatform, WrVisualViewport };
+export type { WrHapticImpact };

package/types/ngwr-popconfirm.d.ts

@@ -24,7 +24,7 @@ type WrPopconfirmPosition = 'top' | 'bottom' | 'left' | 'right';
  * >Delete</wr-btn>
  * ```
  *
- * @see https://ngwr.dev/components/popconfirm
+ * @see https://ngwr.dev/reference/components/popconfirm
  */
 declare class WrPopconfirm {
     /** Confirmation message. */
@@ -36,7 +36,7 @@ declare class WrPopconfirm {
     /** Label for the cancel button. @default 'Cancel' */
     readonly cancelText: _angular_core.InputSignal<string>;
     /** Color of the confirm button. @default 'primary' */
-    readonly confirmColor: _angular_core.InputSignal<"primary" | "secondary" | "success" | "warning" | "danger" | "light" | "medium" | "dark">;
+    readonly confirmColor: _angular_core.InputSignal<"primary" | "secondary" | "success" | "warning" | "danger" | "info" | "light" | "medium" | "dark">;
     /** Fires when the user clicks confirm. */
     readonly confirmed: _angular_core.OutputEmitterRef<void>;
     /** Fires when the user clicks cancel or dismisses the overlay. */
@@ -68,7 +68,7 @@ declare class WrPopconfirmPanel {
     readonly message: _angular_core.InputSignal<string>;
     readonly confirmText: _angular_core.InputSignal<string>;
     readonly cancelText: _angular_core.InputSignal<string>;
-    readonly confirmColor: _angular_core.InputSignal<"primary" | "secondary" | "success" | "warning" | "danger" | "light" | "medium" | "dark">;
+    readonly confirmColor: _angular_core.InputSignal<"primary" | "secondary" | "success" | "warning" | "danger" | "info" | "light" | "medium" | "dark">;
     readonly confirmed: _angular_core.OutputEmitterRef<void>;
     readonly cancelled: _angular_core.OutputEmitterRef<void>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrPopconfirmPanel, never>;

package/types/ngwr-progress.d.ts

@@ -9,7 +9,7 @@ import * as _angular_core from '@angular/core';
  * <wr-progress color="success" [value]="80" />
  * ```
  *
- * @see https://ngwr.dev/components/progress
+ * @see https://ngwr.dev/reference/components/progress
  */
 declare class WrProgress {
     /**
@@ -17,7 +17,7 @@ declare class WrProgress {
      *
      * @default 'primary'
      */
-    readonly color: _angular_core.InputSignal<"primary" | "secondary" | "success" | "warning" | "danger" | "light" | "medium" | "dark">;
+    readonly color: _angular_core.InputSignal<"primary" | "secondary" | "success" | "warning" | "danger" | "info" | "light" | "medium" | "dark">;
     /**
      * Progress value, clamped to `[0, 100]`.
      *

package/types/ngwr-pull-to-refresh.d.ts

@@ -0,0 +1,69 @@
+import * as _angular_core from '@angular/core';
+
+/**
+ * Pull-to-refresh wrapper. Make its own content scrollable (give it a height /
+ * `max-height`), and when the user drags down from the very top past
+ * `threshold` and lets go, `refresh` fires.
+ *
+ * It is a **controlled** spinner: bind `refreshing` — set it `true` in your
+ * `refresh` handler and `false` once the async work settles, and the indicator
+ * holds open until then. Setting `refreshing` `true` yourself (without a pull)
+ * shows the spinner too, so it doubles as a programmatic "reloading" state.
+ *
+ * Touch-only by design (the gesture is meaningless with a mouse); it lives
+ * beside native scrolling — a pull only starts at `scrollTop === 0`, otherwise
+ * the list scrolls as usual. Fires a light {@link WrHaptics} tap when the pull
+ * arms. `overscroll-behavior` stops the browser's own pull-to-refresh from
+ * fighting it.
+ *
+ * @example
+ * ```html
+ * <wr-pull-to-refresh style="height: 20rem" [refreshing]="loading()" (refresh)="reload()">
+ *   @for (item of items(); track item.id) {
+ *     <div class="row">{{ item.label }}</div>
+ *   }
+ * </wr-pull-to-refresh>
+ * ```
+ * ```ts
+ * reload(): void {
+ *   this.loading.set(true);
+ *   this.api.fetch().subscribe((rows) => {
+ *     this.items.set(rows);
+ *     this.loading.set(false);   // closes the indicator
+ *   });
+ * }
+ * ```
+ *
+ * @see https://ngwr.dev/reference/components/pull-to-refresh
+ */
+declare class WrPullToRefresh {
+    private readonly el;
+    private readonly haptics;
+    /**
+     * Whether the refresh is in flight — drives the spinner. Set `true` in your
+     * `refresh` handler and `false` when the work resolves. @default false
+     */
+    readonly refreshing: _angular_core.InputSignalWithTransform<boolean, any>;
+    /** Disable the gesture entirely. @default false */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
+    /** Distance (px) the pull must reach for a release to trigger `refresh`. @default 64 */
+    readonly threshold: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Fires once each time the user pulls past `threshold` and releases. */
+    readonly refresh: _angular_core.OutputEmitterRef<void>;
+    protected readonly distance: _angular_core.WritableSignal<number>;
+    protected readonly dragging: _angular_core.WritableSignal<boolean>;
+    protected readonly thresholdPx: _angular_core.Signal<number>;
+    protected readonly armed: _angular_core.Signal<boolean>;
+    protected readonly progress: _angular_core.Signal<number>;
+    protected readonly contentTransform: _angular_core.Signal<string | null>;
+    private startY;
+    private canPull;
+    constructor();
+    protected onTouchStart(event: TouchEvent): void;
+    protected onTouchMove(event: TouchEvent): void;
+    protected onTouchEnd(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrPullToRefresh, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrPullToRefresh, "wr-pull-to-refresh", never, { "refreshing": { "alias": "refreshing"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "threshold": { "alias": "threshold"; "required": false; "isSignal": true; }; }, { "refresh": "refresh"; }, never, ["*"], true, never>;
+}
+
+export { WrPullToRefresh };

package/types/ngwr-qr.d.ts

@@ -26,7 +26,7 @@ type WrQrErrorLevel = 'L' | 'M' | 'Q' | 'H';
  * <wr-qr value="..." iconUrl="/logo.png" [iconSize]="48" level="H" />
  * ```
  *
- * @see https://ngwr.dev/components/qrcode
+ * @see https://ngwr.dev/reference/components/qrcode
  */
 declare class WrQr {
     /** Text or URL to encode. Required. */

package/types/ngwr-radio.d.ts

@@ -1,6 +1,6 @@
 import * as _angular_core from '@angular/core';
 import { InjectionToken, Signal } from '@angular/core';
-import { ControlValueAccessor } from '@angular/forms';
+import { FormValueControl } from '@angular/forms/signals';
 
 /**
  * Single-choice option. Must be a child of `<wr-radio-group>`.
@@ -14,7 +14,7 @@ import { ControlValueAccessor } from '@angular/forms';
  * </wr-radio-group>
  * ```
  *
- * @see https://ngwr.dev/components/radio
+ * @see https://ngwr.dev/reference/components/radio
  */
 type WrRadioSize = 'sm' | 'md' | 'lg';
 declare class WrRadio {
@@ -70,8 +70,12 @@ interface WrRadioGroupContext {
     readonly isDisabled: Signal<boolean>;
     /** Select the given value. */
     select(value: unknown): void;
-    /** Mark the group as touched (called on blur from any child). */
-    touch(): void;
+    /**
+     * Mark the group as touched (called on blur from any child). Named
+     * `markTouched` rather than `touch` so it doesn't clash with the
+     * `FormUiControl.touch` output the group now exposes for signal forms.
+     */
+    markTouched(): void;
 }
 /**
  * Token a `<wr-radio>` injects to participate in its parent `<wr-radio-group>`
@@ -85,46 +89,45 @@ declare const WR_RADIO_GROUP: InjectionToken<WrRadioGroupContext>;
 /**
  * Hosts a group of `<wr-radio>` children as a single-value selection.
  *
- * Implements `ControlValueAccessor` — the group's `value` is the
- * currently selected radio's `value`.
+ * A signal-forms native control: it implements `FormValueControl<unknown>`, so
+ * `[formField]` binds to its `value` model — the currently selected radio's
+ * `value`. `[(value)]` works standalone. Classic `[(ngModel)]` / reactive forms
+ * keep working through Angular's bridge.
  *
  * @example
  * ```html
- * <wr-radio-group [(ngModel)]="size">
+ * <wr-radio-group [formField]="form.size">
  *   <wr-radio value="sm">Small</wr-radio>
  *   <wr-radio value="md">Medium</wr-radio>
  *   <wr-radio value="lg">Large</wr-radio>
  * </wr-radio-group>
  * ```
  *
- * @see https://ngwr.dev/components/radio
+ * @see https://ngwr.dev/reference/components/radio
  */
-declare class WrRadioGroup implements ControlValueAccessor, WrRadioGroupContext {
+declare class WrRadioGroup implements FormValueControl<unknown>, WrRadioGroupContext {
     /**
      * Shared `name` attribute. Defaults to a random id so multiple groups
-     * on the same page don't collide.
+     * on the same page don't collide. (Also the `FormUiControl.name` slot.)
      */
     readonly name: _angular_core.InputSignal<string>;
     /**
-     * Disable the whole group. Also set by Angular forms via `setDisabledState`.
+     * Disable the whole group. Bound automatically from the field's disabled
+     * state when used with `[formField]`.
      *
      * @default false
      */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
-    readonly value: _angular_core.WritableSignal<unknown>;
-    private readonly disabledFromCva;
-    /** Effective disabled state — true if either source disables. */
+    /** The selected radio's value. Bound by `[formField]`, or two-way via `[(value)]`. */
+    readonly value: _angular_core.ModelSignal<unknown>;
+    /** Emitted on blur from any child so a bound field can mark itself touched. */
+    readonly touch: _angular_core.OutputEmitterRef<void>;
+    /** Effective disabled state (WrRadioGroupContext). */
     readonly isDisabled: _angular_core.Signal<boolean>;
-    private onChange;
-    private onTouched;
     select(value: unknown): void;
-    touch(): void;
-    writeValue(value: unknown): void;
-    registerOnChange(fn: (value: unknown) => void): void;
-    registerOnTouched(fn: () => void): void;
-    setDisabledState(isDisabled: boolean): void;
+    markTouched(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrRadioGroup, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrRadioGroup, "wr-radio-group", never, { "name": { "alias": "name"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrRadioGroup, "wr-radio-group", never, { "name": { "alias": "name"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, ["*"], true, never>;
 }
 
 export { WR_RADIO_GROUP, WrRadio, WrRadioGroup };

package/types/ngwr-rating.d.ts

@@ -1,65 +1,73 @@
 import * as _angular_core from '@angular/core';
-import { ControlValueAccessor } from '@angular/forms';
+import { FormValueControl } from '@angular/forms/signals';
 
 /**
  * Star rating input. Click or hover to set a value; supports half-star
- * increments via `step="0.5"`. Implements `ControlValueAccessor` — value
- * is `number | null` (clamped to `[0, count]`).
+ * increments via `step="0.5"`. Value is `number | null` (clamped to
+ * `[0, count]`).
+ *
+ * A signal-forms native control: it implements `FormValueControl<number | null>`,
+ * so `[formField]` binds straight to its `value` model — no
+ * `ControlValueAccessor` in between. `[(value)]` works standalone.
  *
  * Keyboard: `←` / `→` bump by `step`, `Home` / `End` jump to 0 / max.
  * Clicking the current value clears it (toggle off).
  *
  * @example
  * ```html
- * <wr-rating [(ngModel)]="score" />
- * <wr-rating [(ngModel)]="score" [count]="10" step="0.5" />
- * <wr-rating [ngModel]="4.5" [readonly]="true" />
+ * <!-- signal forms -->
+ * <wr-rating [formField]="form.score" />
+ *
+ * <!-- standalone two-way binding -->
+ * <wr-rating [(value)]="score" [count]="10" step="0.5" />
+ * <wr-rating [value]="4.5" [readonly]="true" />
  * ```
  *
- * @see https://ngwr.dev/components/rating
+ * @see https://ngwr.dev/reference/components/rating
  */
 type WrRatingSize = 'sm' | 'md' | 'lg';
-declare class WrRating implements ControlValueAccessor {
+declare class WrRating implements FormValueControl<number | null> {
     /** Total number of slots. @default 5 */
     readonly count: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Step granularity — `1` for whole stars, `0.5` for halves. @default 1 */
     readonly step: _angular_core.InputSignalWithTransform<1 | 0.5, unknown>;
     /** Read-only — value is displayed but not interactive. @default false */
     readonly readonly: _angular_core.InputSignalWithTransform<boolean, any>;
-    /** Disable interaction. @default false */
+    /**
+     * Disable interaction. Bound automatically from the field's disabled state
+     * when used with `[formField]`.
+     *
+     * @default false
+     */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
     /** Control size — scales the icons + gaps. @default 'md' */
     readonly size: _angular_core.InputSignal<WrRatingSize>;
     /** Accessible label. @default 'Rating' */
     readonly ariaLabel: _angular_core.InputSignal<string>;
-    /** Last committed value (mirrored from the CVA). */
-    protected readonly value: _angular_core.WritableSignal<number | null>;
+    /** The rating. Bound by `[formField]`, or two-way via `[(value)]`. */
+    readonly value: _angular_core.ModelSignal<number | null>;
+    /** Emitted on blur so a bound field can mark itself touched. */
+    readonly touch: _angular_core.OutputEmitterRef<void>;
     /** Transient hover preview — overrides `value` for display when set. */
     protected readonly hoverValue: _angular_core.WritableSignal<number | null>;
-    private readonly disabledFromCva;
-    protected readonly effectiveDisabled: _angular_core.Signal<boolean>;
     protected readonly interactive: _angular_core.Signal<boolean>;
     /** What we actually render — hover wins while hovering. */
     protected readonly displayValue: _angular_core.Signal<number>;
     protected readonly slots: _angular_core.Signal<number[]>;
     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;
-    private onChange;
-    private onTouched;
-    writeValue(value: number | null): void;
-    registerOnChange(fn: (value: number | null) => void): void;
-    registerOnTouched(fn: () => void): void;
-    setDisabledState(isDisabled: boolean): void;
     protected onSlotMove(event: MouseEvent, index: number): void;
     protected onLeave(): void;
     protected onSlotClick(event: MouseEvent, index: number): void;
     protected onKeydown(event: KeyboardEvent): void;
+    protected onBlur(): void;
     /** Convert a mouse position over slot `index` to a snapped value. */
     private computeValue;
     private commit;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrRating, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrRating, "wr-rating", never, { "count": { "alias": "count"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrRating, "wr-rating", never, { "count": { "alias": "count"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
 }
 
 export { WrRating };

package/types/ngwr-result.d.ts

@@ -18,7 +18,7 @@ type WrResultStatus = 'success' | 'warning' | 'error' | 'info' | 'empty';
  * </wr-result>
  * ```
  *
- * @see https://ngwr.dev/components/result
+ * @see https://ngwr.dev/reference/components/result
  */
 declare class WrResult {
     readonly title: _angular_core.InputSignal<string>;

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

@@ -55,6 +55,7 @@ declare class WrRotatingText {
     private readonly platform;
     private timerId;
     private isAnimating;
+    private destroyed;
     constructor();
     next(): void;
     previous(): void;

package/types/ngwr-scroll.d.ts

@@ -43,7 +43,7 @@ interface WrScrollOptions {
  * scroll.intoView(myEl, { offset: 64 });
  * ```
  *
- * @see https://ngwr.dev/services/scroll
+ * @see https://ngwr.dev/reference/services/scroll
  */
 declare class WrScroll {
     private readonly doc;

package/types/ngwr-segmented.d.ts

@@ -37,7 +37,7 @@ interface WrSegmentedOption<T = unknown> {
  * />
  * ```
  *
- * @see https://ngwr.dev/components/segmented
+ * @see https://ngwr.dev/reference/components/segmented
  */
 type WrSegmentedSize = 'sm' | 'md' | 'lg';
 declare class WrSegmented<T = unknown> {