ngwr 6.1.1 → 7.0.0

package/types/ngwr-utils.d.ts

@@ -0,0 +1,447 @@
+import { Observable } from 'rxjs';
+
+/**
+ * @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
+ */
+/**
+ * Represents a value that may be absent.
+ *
+ * Preferred over inline `T | null | undefined` unions for consistency
+ * across the codebase and to reduce repetition in public API signatures.
+ *
+ * @example
+ * ```ts
+ * function findUser(id: string): Maybe<User> {
+ *   return db.get(id) ?? null;
+ * }
+ *
+ * const user: Maybe<User> = findUser('42');
+ *
+ * if (isDefined(user)) {
+ *   // user is User
+ * }
+ * ```
+ *
+ * @see {@link isDefined} — type guard that narrows `Maybe<T>` to `T`.
+ */
+type Maybe<T> = T | null | undefined;
+
+/**
+ * @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
+ */
+/**
+ * Explicitly untyped value.
+ *
+ * Use in places where `any` is intentional and unavoidable,
+ * such as generic wrappers around third-party APIs that do not
+ * expose precise types.
+ *
+ * Prefer narrowing to a concrete type whenever possible.
+ *
+ * @example
+ * ```ts
+ * function wrapThirdPartyCallback(fn: (...args: SafeAny[]) => SafeAny): void {
+ *   // ...
+ * }
+ * ```
+ */
+type SafeAny = any;
+
+/**
+ * @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
+ */
+
+/**
+ * Type guard that checks if a value is neither `null` nor `undefined`.
+ *
+ * @example
+ * ```ts
+ * const maybeValue: Maybe<number> = getValue();
+ *
+ * if (isDefined(maybeValue)) {
+ *   // here maybeValue is number
+ *   console.log(maybeValue.toFixed(2));
+ * }
+ * ```
+ *
+ * @see {@link Maybe}
+ */
+declare function isDefined<T>(value: Maybe<T>): value is T;
+
+/**
+ * @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
+ */
+
+/**
+ * Type guard that checks if a value is an array with at least one element.
+ *
+ * @example
+ * ```ts
+ * const items: Maybe<string[]> = getItems();
+ *
+ * if (isNonEmptyArray(items)) {
+ *   // items is string[]
+ *   console.log(items[0]);
+ * }
+ * ```
+ */
+declare function isNonEmptyArray<T>(value: Maybe<T[]>): value is [T, ...T[]];
+
+/**
+ * @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
+ */
+
+/**
+ * Type guard that checks whether a value looks like an RxJS `Observable`.
+ *
+ * Uses duck-typing: verifies that the object has a `subscribe` function.
+ * Does not require an actual `Observable` instance.
+ *
+ * @example
+ * ```ts
+ * if (isObservable(stream)) {
+ *   stream.subscribe(value => console.log(value));
+ * }
+ * ```
+ */
+declare function isObservable<T = unknown>(value: unknown): value is Observable<T>;
+
+/**
+ * Clamps `value` into the inclusive `[min, max]` range.
+ *
+ * @example
+ * ```ts
+ * clamp(140, 0, 100); // 100
+ * clamp(-3, 0, 100);  // 0
+ * clamp(42, 0, 100);  // 42
+ * ```
+ */
+declare function clamp(value: number, min: number, max: number): number;
+
+/**
+ * Rounds `value` to `decimals` fraction digits, compensating the usual
+ * floating point drift (`0.1 + 0.2` rounds to `0.3`, not `0.30000000000000004`).
+ *
+ * @example
+ * ```ts
+ * round(0.1 + 0.2, 2); // 0.3
+ * round(1.005, 2);     // 1.01
+ * round(7.4);          // 7
+ * ```
+ */
+declare function round(value: number, decimals?: number): number;
+
+/**
+ * Input-transform factory: coerces any bound value to a number, falling
+ * back to `fallback` for `null` / `undefined` / unparsable input. The
+ * standard transform for numeric `input()`s across ngwr.
+ *
+ * @example
+ * ```ts
+ * readonly speed = input(4, { transform: numAttr(4) });
+ * ```
+ */
+declare const numAttr: (fallback: number) => (value: unknown) => number;
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+/**
+ * Options for {@link resolveCssSize}.
+ */
+interface ResolveCssSizeOptions {
+    /**
+     * Fallback value used when the raw input is `null` or `undefined`.
+     *
+     * Accepts the same formats as the `raw` parameter:
+     * numbers, pixel strings, rem strings, percentages, etc.
+     */
+    defaultValue?: unknown;
+}
+
+/**
+ * @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
+ */
+/**
+ * Result of resolving a CSS size value via {@link resolveCssSize}.
+ */
+interface ResolvedCssSize {
+    /**
+     * Value suitable for use in CSS styles (e.g. `"48px"`, `"3rem"`, `"80%"`).
+     */
+    cssValue: string;
+    /**
+     * Equivalent value in pixels, when computable.
+     *
+     * `null` for percentage-based or unknown units where a pixel
+     * equivalent cannot be determined.
+     */
+    pxValue: number | null;
+}
+
+/**
+ * @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
+ */
+
+/**
+ * Resolves a raw size value into a CSS string and an optional pixel equivalent.
+ *
+ * Supported formats:
+ * - `number`   → pixels        (`48`    → `"48px"`)
+ * - `"12px"`   → pixels        (`"12px"` → `"12px"`)
+ * - `"3rem"`   → rems via root (`"3rem"` → `"3rem"`, pxValue = 3 × root font size)
+ * - `"80%"`    → percentage    (`"80%"`  → `"80%"`,  pxValue = null)
+ * - `"15"`     → pixels        (`"15"`   → `"15px"`)
+ * - anything else → passed through as-is, pxValue = null
+ *
+ * @example
+ * ```ts
+ * const size = resolveCssSize('3rem', { defaultValue: '6rem' });
+ * // size.cssValue === '3rem'
+ * // size.pxValue  === 3 * getRootFontSize()
+ * ```
+ *
+ * @param raw - Value to resolve. Accepts numbers, pixel/rem/percent strings, or `null`/`undefined`.
+ * @param options - Optional configuration.
+ * @returns Resolved CSS value and its pixel equivalent when computable.
+ *
+ * @see {@link ResolvedCssSize}
+ * @see {@link ResolveCssSizeOptions}
+ */
+declare function resolveCssSize(raw: unknown, options?: ResolveCssSizeOptions): ResolvedCssSize;
+
+/**
+ * @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
+ */
+/**
+ * Reads the root font size (in pixels) from
+ * `getComputedStyle(document.documentElement).fontSize`.
+ *
+ * Typical use case: converting `rem` values to pixels for layout calculations.
+ *
+ * Falls back to the provided value when:
+ * - DOM is not available (SSR);
+ * - `getComputedStyle` fails or returns an unparseable value.
+ *
+ * @example
+ * ```ts
+ * const rootFontSize = getRootFontSize();      // e.g. 16
+ * const customFallback = getRootFontSize(14);  // uses 14 if DOM is unavailable
+ * ```
+ *
+ * @param fallback - Value in pixels when DOM is unavailable. Defaults to `16`.
+ * @returns Root font size in pixels.
+ */
+declare function getRootFontSize(fallback?: number): number;
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+/** Return every focusable descendant of `root` in DOM order. */
+declare function getFocusableElements(root: HTMLElement): readonly HTMLElement[];
+/**
+ * Trap Tab navigation inside `root` for a keyboard event — call from a
+ * `keydown` handler. Cycles focus from first ↔ last focusable element.
+ * Returns `true` when focus was redirected (event was handled).
+ */
+declare function trapFocus(root: HTMLElement, event: KeyboardEvent): boolean;
+
+/**
+ * @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
+ */
+/**
+ * Generates a pseudo-random, DOM-safe identifier.
+ *
+ * Produced ids:
+ * - are prefixed to avoid collisions with host-application ids;
+ * - contain only `[a-z0-9-]` characters;
+ * - use `crypto.getRandomValues` when available, falling back to `Math.random`.
+ *
+ * **Not suitable for cryptographic or security-sensitive purposes** —
+ * intended only for UI element identifiers (`id`, `for`, `aria-*`, etc.).
+ *
+ * @example
+ * ```ts
+ * randomId();
+ * // → "wr-a8f2bx1k9q4z"
+ *
+ * randomId('ng', 8);
+ * // → "ng-k2f9mbeo"
+ *
+ * randomId('wr', 24);
+ * // → "wr-a8f2bx1k9q4zmneo73wplr"
+ * ```
+ *
+ * @param prefix - Namespace prefix prepended before the random segment. Defaults to `'wr'`.
+ * @param length - Length of the random segment. Clamped to `[4, 64]`. Defaults to `12`.
+ * @param random - Custom random byte source `(byteLength) => Uint8Array`.
+ *   When omitted, uses `crypto.getRandomValues` with a `Math.random` fallback.
+ * @returns A pseudo-random id string matching `/^[a-z]+-[a-z0-9]+$/`.
+ */
+declare function randomId(prefix?: string, length?: number, random?: (byteLength: number) => Uint8Array): string;
+
+/**
+ * @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
+ */
+/**
+ * A function that does nothing.
+ *
+ * Useful as a default callback, placeholder event handler,
+ * or to explicitly signal intentional no-ops.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class MyComponent {
+ *   onTouched: () => void = noop;
+ * }
+ * ```
+ */
+declare const noop: () => void;
+
+/**
+ * @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
+ */
+/** A debounced function — same signature as the original plus `cancel`. */
+type WrDebouncedFn<TArgs extends readonly unknown[]> = ((...args: TArgs) => void) & {
+    readonly cancel: () => void;
+};
+/**
+ * Wrap `fn` so it only fires `waitMs` after the last invocation.
+ * Useful for resize / scroll / input handlers.
+ *
+ * @example
+ * ```ts
+ * const onResize = debounce(() => recalcLayout(), 150);
+ * window.addEventListener('resize', onResize);
+ * ```
+ */
+declare function debounce<TArgs extends readonly unknown[]>(fn: (...args: TArgs) => void, waitMs: number): WrDebouncedFn<TArgs>;
+
+/**
+ * @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
+ */
+/** A throttled function — same signature as the original plus `cancel`. */
+type WrThrottledFn<TArgs extends readonly unknown[]> = ((...args: TArgs) => void) & {
+    readonly cancel: () => void;
+};
+/**
+ * Wrap `fn` so it fires at most once every `waitMs`. Leading-edge call
+ * fires immediately; trailing-edge call fires once at the end of the window
+ * if there were further invocations.
+ */
+declare function throttle<TArgs extends readonly unknown[]>(fn: (...args: TArgs) => void, waitMs: number): WrThrottledFn<TArgs>;
+
+/**
+ * @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
+ */
+/**
+ * Canonical `KeyboardEvent.key` values used across ngwr components.
+ * Use these constants instead of magic strings so refactors are searchable.
+ */
+declare const KEYS: {
+    readonly ENTER: "Enter";
+    readonly ESCAPE: "Escape";
+    readonly TAB: "Tab";
+    readonly SPACE: " ";
+    readonly BACKSPACE: "Backspace";
+    readonly DELETE: "Delete";
+    readonly ARROW_UP: "ArrowUp";
+    readonly ARROW_DOWN: "ArrowDown";
+    readonly ARROW_LEFT: "ArrowLeft";
+    readonly ARROW_RIGHT: "ArrowRight";
+    readonly HOME: "Home";
+    readonly END: "End";
+    readonly PAGE_UP: "PageUp";
+    readonly PAGE_DOWN: "PageDown";
+};
+type WrKey = (typeof KEYS)[keyof typeof KEYS];
+
+/**
+ * @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
+ */
+/** True when any modifier key (Ctrl / Cmd / Alt / Shift / Meta) is held. */
+declare function hasModifier(event: KeyboardEvent): boolean;
+/**
+ * True when the key is a single printable character (letters, digits,
+ * punctuation, etc.). Skips function keys, arrows, modifiers, and named
+ * keys like `Backspace` or `Tab`.
+ */
+declare function isPrintableKey(event: KeyboardEvent): boolean;
+
+/**
+ * @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
+ */
+/**
+ * Logs a coloured pill to the browser console followed by a payload.
+ *
+ * Useful when you need to scan a noisy console for a specific subsystem's
+ * messages. The pill is rendered with the CSS `%c` console formatting trick.
+ *
+ * @example
+ * ```ts
+ * badgeLog('icons', '#3969e2', { name: 'plus', registered: true });
+ * // → [icons] { name: 'plus', registered: true }
+ * ```
+ *
+ * @param badgeText Short label shown inside the pill.
+ * @param color    CSS colour applied to the pill border and text.
+ * @param message  Anything you'd pass to `console.log` as the second argument.
+ *
+ * @internal
+ */
+declare function badgeLog(badgeText: string, color: string, message: unknown): void;
+
+export { KEYS, badgeLog, clamp, debounce, getFocusableElements, getRootFontSize, hasModifier, isDefined, isNonEmptyArray, isObservable, isPrintableKey, noop, numAttr, randomId, resolveCssSize, round, throttle, trapFocus };
+export type { Maybe, ResolveCssSizeOptions, ResolvedCssSize, SafeAny, WrDebouncedFn, WrKey, WrThrottledFn };

package/types/ngwr-validators.d.ts

@@ -0,0 +1,70 @@
+import { AbstractControl, ValidationErrors, ValidatorFn } from '@angular/forms';
+
+/**
+ * @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
+ */
+
+/**
+ * Bundled `ValidatorFn`s — pure functions, no DOM, no DI. Mirrors the
+ * API shape of Angular's built-in `Validators` so it composes cleanly:
+ *
+ * ```ts
+ * import { Validators } from '@angular/forms';
+ * import { WrValidators } from 'ngwr/validators';
+ *
+ * new FormControl('', [
+ *   Validators.required,
+ *   WrValidators.cardNumber,
+ *   WrValidators.cvc(3),
+ *   WrValidators.match('password'),
+ *   WrValidators.oneOf(['xs', 'sm', 'md', 'lg', 'xl']),
+ * ]);
+ * ```
+ *
+ * Each error is keyed under the validator name (e.g. `cardNumber`,
+ * `cvc`, `iban`) so consumers can branch in templates.
+ *
+ * Anything Angular already ships (`required`, `email`, `min`, `max`,
+ * `pattern`, …) is deliberately NOT duplicated here.
+ *
+ * @see https://ngwr.dev/validators
+ */
+declare const WrValidators: {
+    /** No whitespace anywhere in the value. */
+    noWhitespace: (control: AbstractControl) => ValidationErrors | null;
+    /** 3, 4, 6, or 8-digit hex colour (`#abc`, `#1a2b3c`, `#1a2b3c4d`). */
+    hexColor: (control: AbstractControl) => ValidationErrors | null;
+    /**
+     * Valid URL. Accepts any scheme by default; pass `{ protocols: ['https'] }`
+     * to restrict.
+     */
+    url: (options?: {
+        readonly protocols?: readonly string[];
+    }) => ValidatorFn;
+    /** Credit card number — Luhn check + 13-19 digit length. Spaces and dashes are stripped first. */
+    cardNumber: (control: AbstractControl) => ValidationErrors | null;
+    /** CVC / CVV — N digits (default 3). Common: 3 for Visa/MC, 4 for Amex. */
+    cvc: (length?: number) => ValidatorFn;
+    /**
+     * IBAN — basic structure (CC + 2 digits + up to 30 alphanumerics) +
+     * the mod-97 check. Country-length tables not enforced.
+     */
+    iban: (control: AbstractControl) => ValidationErrors | null;
+    /**
+     * Value must equal a sibling control's value (e.g. confirm-password).
+     * The target lookup uses `control.parent.get(name)`, so it works
+     * inside `FormGroup` and nested groups.
+     */
+    match: (targetName: string) => ValidatorFn;
+    /** Value must be one of the allowed entries (strict equality). */
+    oneOf: <T>(allowed: readonly T[]) => ValidatorFn;
+    /** Value (Date | parseable) must be ≥ `min`. */
+    minDate: (min: Date | string | number) => ValidatorFn;
+    /** Value (Date | parseable) must be ≤ `max`. */
+    maxDate: (max: Date | string | number) => ValidatorFn;
+};
+
+export { WrValidators };

package/types/ngwr-version.d.ts

@@ -0,0 +1,44 @@
+import { InjectionToken } from '@angular/core';
+
+/**
+ * @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
+ */
+/**
+ * The ngwr library version string, kept in sync with
+ * `projects/lib/package.json` by `scripts/release-prepare.ts`.
+ *
+ * Prefer this over reading `package.json` at runtime — that requires a JSON
+ * import or `require`, neither of which tree-shakes well in Angular builds.
+ *
+ * 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 = "7.0.0";
+
+/**
+ * @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
+ */
+
+/**
+ * Injection token holding the ngwr library version string.
+ *
+ * Default factory returns {@link NGWR_VERSION}. Override it in tests or in
+ * apps that want to surface a custom build identifier.
+ *
+ * @example
+ * ```ts
+ * @Component({...})
+ * export class FooterComponent {
+ *   readonly version = inject(NGWR_VERSION_TOKEN);
+ * }
+ * ```
+ */
+declare const NGWR_VERSION_TOKEN: InjectionToken<string>;
+
+export { NGWR_VERSION, NGWR_VERSION_TOKEN };

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

@@ -0,0 +1,64 @@
+import * as _angular_core from '@angular/core';
+import { TrackByFunction, TemplateRef } from '@angular/core';
+import { CdkVirtualScrollViewport } from '@angular/cdk/scrolling';
+
+/**
+ * Fixed-size virtual scroll viewport.
+ *
+ * Thin wrapper around CDK's `cdk-virtual-scroll-viewport` with ngwr
+ * theming and sensible buffer defaults. Project a single template — it's
+ * called per item with `let-item let-index="index"`.
+ *
+ * @example
+ * ```html
+ * <wr-virtual-scroll [items]="rows" [itemSize]="32" [height]="320">
+ *   <ng-template let-row let-i="index">
+ *     <div class="row">{{ i }}. {{ row.name }}</div>
+ *   </ng-template>
+ * </wr-virtual-scroll>
+ * ```
+ *
+ * @see https://ngwr.dev/components/virtual-scroll
+ */
+declare class WrVirtualScroll<T = unknown> {
+    /** Items to render. */
+    readonly items: _angular_core.InputSignal<readonly T[]>;
+    /** Per-item pixel height. All rows must be the same height. @default 32 */
+    readonly itemSize: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Viewport height. Pass a number (`px`) or any CSS length string
+     * (`'80vh'`, `'40rem'`). @default 256
+     */
+    readonly height: _angular_core.InputSignal<string | number>;
+    /**
+     * Pixels of rendered content kept above + below the viewport. CDK
+     * keeps adding rows until at least this many pixels are buffered.
+     * @default itemSize * 4
+     */
+    readonly minBufferPx: _angular_core.InputSignal<number | undefined>;
+    /**
+     * Maximum pixels of buffered content before CDK starts recycling rows.
+     * Must be ≥ `minBufferPx`. @default itemSize * 8
+     */
+    readonly maxBufferPx: _angular_core.InputSignal<number | undefined>;
+    /**
+     * `trackBy` function for the inner `*cdkVirtualFor`. Defaults to
+     * identity (recreates rows when the item reference changes).
+     */
+    readonly trackBy: _angular_core.InputSignal<TrackByFunction<T>>;
+    protected readonly rowTemplate: _angular_core.Signal<TemplateRef<any>>;
+    protected readonly viewport: _angular_core.Signal<CdkVirtualScrollViewport>;
+    protected readonly resolvedHeight: _angular_core.Signal<string>;
+    protected readonly resolvedMinBuffer: _angular_core.Signal<number>;
+    protected readonly resolvedMaxBuffer: _angular_core.Signal<number>;
+    /** Scroll a specific index into view. Mirrors the CDK API. */
+    scrollToIndex(index: number, behavior?: ScrollBehavior): void;
+    /** Scroll to a pixel offset. */
+    scrollToOffset(offset: number, behavior?: ScrollBehavior): void;
+    /** Manually trigger size recheck (e.g. after host resize outside ResizeObserver). */
+    checkViewportSize(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrVirtualScroll<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrVirtualScroll<any>, "wr-virtual-scroll", never, { "items": { "alias": "items"; "required": true; "isSignal": true; }; "itemSize": { "alias": "itemSize"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "minBufferPx": { "alias": "minBufferPx"; "required": false; "isSignal": true; }; "maxBufferPx": { "alias": "maxBufferPx"; "required": false; "isSignal": true; }; "trackBy": { "alias": "trackBy"; "required": false; "isSignal": true; }; }, {}, ["rowTemplate"], never, true, never>;
+}
+
+export { WrVirtualScroll };

package/types/ngwr-waves.d.ts

@@ -0,0 +1,71 @@
+import * as _angular_core from '@angular/core';
+
+/**
+ * Wave-field background — a grid of lines drifting on perlin noise,
+ * nudged by the pointer. Fills its nearest positioned ancestor; put it
+ * behind hero copy or section content.
+ *
+ * Colours are theme-aware by default: a soft dark line on light surfaces,
+ * a faint white line on dark — override with `[lineColor]`.
+ *
+ * @example
+ * ```html
+ * <section style="position: relative">
+ *   <wr-waves />
+ *   <h1>Hero copy above the waves</h1>
+ * </section>
+ * ```
+ *
+ * @see https://ngwr.dev/animations/waves
+ */
+declare class WrWaves {
+    /** Line stroke colour. When unset, the theme decides. */
+    readonly lineColor: _angular_core.InputSignal<string | null>;
+    /** Background fill behind the lines. @default 'transparent' */
+    readonly backgroundColor: _angular_core.InputSignal<string>;
+    /** Horizontal noise drift per ms. @default 0.0125 */
+    readonly waveSpeedX: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Vertical noise drift per ms. @default 0.005 */
+    readonly waveSpeedY: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Horizontal wave amplitude in px. @default 32 */
+    readonly waveAmpX: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Vertical wave amplitude in px. @default 16 */
+    readonly waveAmpY: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Horizontal gap between lines in px. @default 10 */
+    readonly xGap: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Vertical gap between points on a line in px. @default 32 */
+    readonly yGap: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Velocity damping of the cursor spring, 0..1. @default 0.925 */
+    readonly friction: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Pull-back strength of the cursor spring. @default 0.005 */
+    readonly tension: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Max px a point can be dragged from rest. @default 100 */
+    readonly maxCursorMove: _angular_core.InputSignalWithTransform<number, unknown>;
+    private readonly canvasRef;
+    private readonly host;
+    private readonly zone;
+    private readonly destroyRef;
+    private readonly platform;
+    private readonly isBrowser;
+    private ctx;
+    private readonly noise;
+    private lines;
+    private bounding;
+    private readonly mouse;
+    private rafId;
+    constructor();
+    private boot;
+    private setSize;
+    private setLines;
+    private tick;
+    private movePoints;
+    private moved;
+    private drawLines;
+    /** Explicit input wins; otherwise the theme's `--wr-waves-line-color`. */
+    private resolveLineColor;
+    private updateMouse;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrWaves, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrWaves, "wr-waves", never, { "lineColor": { "alias": "lineColor"; "required": false; "isSignal": true; }; "backgroundColor": { "alias": "backgroundColor"; "required": false; "isSignal": true; }; "waveSpeedX": { "alias": "waveSpeedX"; "required": false; "isSignal": true; }; "waveSpeedY": { "alias": "waveSpeedY"; "required": false; "isSignal": true; }; "waveAmpX": { "alias": "waveAmpX"; "required": false; "isSignal": true; }; "waveAmpY": { "alias": "waveAmpY"; "required": false; "isSignal": true; }; "xGap": { "alias": "xGap"; "required": false; "isSignal": true; }; "yGap": { "alias": "yGap"; "required": false; "isSignal": true; }; "friction": { "alias": "friction"; "required": false; "isSignal": true; }; "tension": { "alias": "tension"; "required": false; "isSignal": true; }; "maxCursorMove": { "alias": "maxCursorMove"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { WrWaves };