ngwr 15.3.0 → 15.4.0

package/package.json

@@ -1234,5 +1234,5 @@
       "sass": "./styles/_typography.scss"
     }
   },
-  "version": "15.3.0"
+  "version": "15.4.0"
 }

package/schematics/use/symbol-map.json

@@ -157,6 +157,7 @@
   "WrPagination": "ngwr/pagination",
   "WrBytes": "ngwr/pipes",
   "WrDate": "ngwr/pipes",
+  "WrDuration": "ngwr/pipes",
   "WrMark": "ngwr/pipes",
   "WrNumber": "ngwr/pipes",
   "WrPlural": "ngwr/pipes",

package/skills/ngwr/SKILL.md

@@ -111,7 +111,9 @@ guess gets backwards.
   through `ngwr/i18n`; every component takes overridable `*Label` inputs.
 - **Prefer the library over hand-rolling.** `ngwr/utils` (coercion, dom,
   keyboard, id, css-size, math), `ngwr/pipes` (`wrDate`, `wrBytes`,
-  `wrTruncate`, `wrNumber`, `wrMark`, `wrPlural`, `wrRange`) and
+  `wrTruncate`, `wrNumber`, `wrMark`, `wrPlural`, `wrRange`, `wrDuration`,
+  and for a string built in TypeScript `wrFormatDate`, `wrFormatBytes`,
+  `wrFormatNumber`, `wrFormatPlural` and `wrFormatDuration`) and
   `ngwr/validators` already exist.
 
 ## Setting a component up

package/types/ngwr-bits-aurora.d.ts

@@ -11,6 +11,13 @@ import * as i0 from "@angular/core";
  * box on the palette's own ground, which is what forced text and marks are chosen
  * against. The loop also stops off screen and with no box to draw on.
  *
+ * With no WebGL2 context, or a shader the driver refuses, nothing is thrown and
+ * the canvas stays empty. A context the browser takes away is rebuilt if it offers
+ * one back. A destroyed host hands its GPU resources back at once. Browsers keep a
+ * small number of live contexts and kill the oldest: Chromium frees the slot at that
+ * point, while WebKit frees it only when the context is collected and offers an
+ * evicted one no restore, so there a host that is not drawing can stay empty for good.
+ *
  * @example
  * ```html
  * <div style="position: relative; min-height: 24rem; overflow: hidden">
@@ -42,11 +49,11 @@ export declare class WrAurora {
   private readonly platform;
   private readonly isBrowser;
   private gl;
-  private uniforms;
+  private gpu;
   private rafId;
   /** The shader time last drawn, so a resize can repaint the frame it just cleared. */
   private time;
-  /** Flips once `boot()` has a context and a program — the loop waits for it. */
+  /** Flips once a program is built, and back when the context goes — everything that draws waits for it. */
   private readonly booted;
   /** Whether the host is in the viewport; stays `true` without an observer. */
   private readonly onScreen;
@@ -57,6 +64,21 @@ export declare class WrAurora {
   private readonly hasBox;
   constructor();
   private boot;
+  /**
+   * Compile, link and upload what one context needs, and make it current. Returns
+   * `null` when it cannot: on a lost context, where every call answers no and
+   * nothing is wrong with the shader, it says nothing.
+   */
+  private build;
+  private compile;
+  /**
+   * Give the GPU resources back at once rather than to the garbage collector:
+   * browsers keep a small number of live contexts and kill the oldest, so a
+   * navigating single-page app would lose the context of a page still on screen.
+   * Chromium frees the slot here too. WebKit holds it until the context is collected,
+   * and no API frees it sooner, so a still or parked host can still be evicted there.
+   */
+  private release;
   private pushUniforms;
   /**
    * Stop `index` as shader channels. Explicit input wins; otherwise the theme's

package/types/ngwr-bits-border-glow-testing.d.ts

@@ -32,10 +32,13 @@ interface WrBorderGlowHarnessFilters extends BaseHarnessFilters {
  * {@link parseInlineDeclarations} for why a computed read would be a different, and
  * wrong, question.
  *
- * **A colour getter answering `null` means that variable is not on the host now**, which
- * is the contract when the input is unset or its value was refused: the stylesheet's
- * per-theme default takes over. An input set and then put back to `null` comes off the
- * host, so `null` says nothing about whether it was ever set.
+ * **A colour getter answering `null` means the input is not on the host now**, which is
+ * the contract when it is unset or its value was refused: the stylesheet's per-theme
+ * default takes over. An input set and then put back to `null` comes off the host, so
+ * `null` says nothing about whether it was ever set. Each colour input writes its own
+ * `--wr-border-glow-input-*` twin, and that twin is what these read — never the hook it
+ * stands in for (`--wr-border-glow-bg`, `-color`, `-gradient-*`), which stays the
+ * author's, so a value an author put there is not what a getter reports.
  *
  * There is deliberately no `getGlowOpacity()`, `isGlowVisible()` or `isHovered()`: the
  * visible strength is a `calc()` in the stylesheet gated behind `:not(:hover)`, and
@@ -81,7 +84,8 @@ export declare class WrBorderGlowHarness extends ComponentHarness {
   /** Strength of the interior soft-light bloom, again unitless. */
   getFillOpacity(): Promise<number>;
   /**
-   * The card fill the author asked for, or `null` when they left it to the theme.
+   * The card fill `[backgroundColor]` asked for, or `null` when it left the fill to the
+   * `--wr-border-glow-bg` hook, and so to the theme.
    *
    * The distinction is the whole point: an unset `[backgroundColor]` means the surface
    * token decides, light or dark, and a card that starts declaring its own fill has

package/types/ngwr-bits-border-glow.d.ts

@@ -24,9 +24,11 @@ import * as i0 from "@angular/core";
  */
 export declare class WrBorderGlow {
   /**
-   * Card background fill. When unset, uses the theme surface token. A hook set inline on
-   * the same element is replaced by this input and does not come back when it is unset,
-   * so set it from a stylesheet rule. The same goes for `glowColor` and `colors`.
+   * Card background fill. When unset, `--wr-border-glow-bg` decides, which defaults to
+   * the theme surface. Written to `--wr-border-glow-input-bg` rather than to the hook,
+   * so a `--wr-border-glow-bg` an author set on the element — inline or from a rule —
+   * stays there under this input and is read again when it is unset. The same goes
+   * for `glowColor` and `colors`.
    */
   readonly backgroundColor: import("@angular/core").InputSignal<string | null>;
   /** Corner radius in pixels. @default 28 */
@@ -80,7 +82,11 @@ export declare class WrBorderGlow {
   private readonly isBrowser;
   /** Whether a pointer is over the card — the loop holds still while it drives. */
   private pointerInside;
-  /** Inline CSS variable bag — recomputed when colour / radius / sensitivity inputs change. */
+  /**
+   * Inline CSS variable bag — the colour inputs, recomputed when one changes. Every
+   * name in it is an `--wr-border-glow-input-*` twin that is there only while its
+   * input is set; the geometry, which is always set, is bound in `host`.
+   */
   protected readonly cssVars: import("@angular/core").Signal<Record<string, string>>;
   constructor();
   protected onPointerEnter(): void;

package/types/ngwr-bits-fuzzy-text.d.ts

@@ -4,7 +4,8 @@ type WrFuzzyTextDirection = 'horizontal' | 'vertical' | 'both';
  * Canvas-rendered "fuzzy" text — each row/column of glyphs is offset by
  * a random amount per frame, giving the text a TV-static or motion-blur
  * appearance. Intensity ramps up on hover, click, and during periodic
- * glitch bursts (configurable).
+ * glitch bursts (configurable). Off screen, or drawn at no size, the loop
+ * stops asking for frames and resumes where it left off.
  *
  * @example
  * ```html

package/types/ngwr-bits-ripple-grid.d.ts

@@ -28,8 +28,8 @@ import * as i0 from "@angular/core";
  *
  * Decorative: the canvas is `aria-hidden`, the host has no role and nothing in
  * it takes focus. The frame loop runs only while a ring is alive, and never
- * while the host is off screen; an idle ring comes due only while frames run,
- * so a hidden tab does not queue them up.
+ * while the host is off screen or has no box to draw on; an idle ring comes due
+ * only while frames run, so a hidden tab does not queue them up.
  *
  * Under `prefers-reduced-motion` one still grid is drawn, in the line colour,
  * with no ripples, no idle rings and no pointer listeners; it is drawn again
@@ -158,6 +158,11 @@ export declare class WrRippleGrid {
   private armIdle;
   /** Flips once `boot()` has a context and a box — everything after waits for it. */
   private readonly booted;
+  /**
+   * Whether the box has an area. The intersection observer calls a zero-area host
+   * intersecting and sends no entry when it gains a size, so this reads the box instead.
+   */
+  private readonly hasBox;
   constructor();
   private boot;
   /** Follow the pointer, keep the idle timer and draw on demand; returns what stops all three. */

package/types/ngwr-bits-splash-cursor.d.ts

@@ -6,7 +6,8 @@ import * as i0 from "@angular/core";
  * everywhere) and it tears down with the component.
  *
  * Renders nothing under `prefers-reduced-motion` or when WebGL is
- * unavailable.
+ * unavailable. Off screen, or with no box to draw on, the solver stops asking
+ * for frames and resumes where it left off.
  *
  * @example
  * ```html

package/types/ngwr-pipes.d.ts

@@ -1,6 +1,6 @@
 import * as i0 from "@angular/core";
 import { PipeTransform } from "@angular/core";
-import { WrDateFormat } from "ngwr/date";
+import { WrDateAdapter, WrDateFormat } from "ngwr/date";
 import { SafeHtml } from "@angular/platform-browser";
 /**
  * Humanise a byte count using binary (1024-based) units, in the reader's locale.
@@ -36,34 +36,56 @@ import { SafeHtml } from "@angular/platform-browser";
  * which are public catalog keys a consumer may have overridden, so it renders
  * `KB` where this pipe renders `kB`. Retiring those keys would silently break
  * every override that had been translating them, which is a major-version move.
+ *
+ * {@link wrFormatBytes} is the same output as a function.
  */
 export declare class WrBytes implements PipeTransform {
   private readonly locale;
   transform(value: number | string | null | undefined, decimals?: number): string;
-  /**
-   * `Intl`'s NARROW unit, with one space put back between it and the number.
-   *
-   * Neither display mode is right on its own. `short` spells the smallest unit
-   * as a word — "512 byte", "0 byte" in English, "0 Byte" in German — which is
-   * both worse copy than the `B` this pipe has always rendered and a bigger
-   * change than the fix is worth. `narrow` gives `B` / `Б` / `o` correctly and
-   * then closes the gap: "1.2kB".
-   *
-   * So the parts are reassembled rather than the string. Going through
-   * `formatToParts` is what keeps the ORDER the locale's own — Hebrew puts the
-   * unit first, and hand-joining `${n} ${unit}` would silently straighten every
-   * such locale into English order.
-   */
-  private format;
   static ɵfac: i0.ɵɵFactoryDeclaration<WrBytes, never>;
   static ɵpipe: i0.ɵɵPipeDeclaration<WrBytes, "wrBytes", true>;
 }
+/**
+ * A byte count in binary (1024-based) units, in the given locale: the same
+ * output as the `wrBytes` pipe, for a string built in TypeScript. `null`,
+ * `undefined` and an empty string give an empty string; zero, a negative
+ * number and a value that is not a number give `0 B`.
+ *
+ * @example
+ * ```ts
+ * wrFormatBytes(1234, 'en-US');       // "1.2 kB"
+ * wrFormatBytes(1234567, 'fr-FR', 0); // "1 Mo"
+ * ```
+ */
+export declare function wrFormatBytes(value: number | string | null | undefined, locale: string, decimals?: number): string;
+/**
+ * A date through a `WrDateAdapter`: the same output as the `wrDate` pipe, for a
+ * string built in TypeScript. A date-only string (`'2026-01-01'`) is that day in
+ * the local zone, as `DatePipe` reads it. `null`, `undefined`, an empty string
+ * and a date the engine refuses give an empty string.
+ *
+ * The adapter stands where `wrFormatNumber` takes a locale, because the output
+ * is the adapter's: the native one formats in `WR_DATE_LOCALE`, and an app's own
+ * adapter formats however it formats. Neither can be rebuilt from a locale
+ * string, so the caller passes `inject(WrDateAdapter)` once.
+ *
+ * @example
+ * ```ts
+ * private readonly dates = inject(WrDateAdapter);
+ *
+ * wrFormatDate(row.createdAt, this.dates);                   // shortDate
+ * wrFormatDate(row.createdAt, this.dates, 'mediumDateTime'); // named key
+ * wrFormatDate(row.createdAt, this.dates, 'dd.MM.yyyy');     // raw token string
+ * ```
+ */
+export declare function wrFormatDate(value: Date | string | number | null | undefined, adapter: WrDateAdapter<Date>, format?: WrDateFormat | (string & {})): string;
 /**
  * Locale-aware date formatting. Delegates to `WrDateAdapter` — the native one
  * unless the app provides its own — so both the named format keys
  * (`'shortDate'`, `'longDate'`, …) and raw token strings work with nothing to
  * set up. A date-only string (`'2026-01-01'`) is that day in the local zone,
- * as `DatePipe` reads it, not UTC midnight.
+ * as `DatePipe` reads it, not UTC midnight. {@link wrFormatDate} is the same
+ * output as a function.
  *
  * @example
  * ```html
@@ -78,6 +100,74 @@ export declare class WrDate implements PipeTransform {
   static ɵfac: i0.ɵɵFactoryDeclaration<WrDate, never>;
   static ɵpipe: i0.ɵɵPipeDeclaration<WrDate, "wrDate", true>;
 }
+/** Word forms keyed by CLDR plural category. Only `other` is required. */
+type WrPluralForms = Partial<Record<Intl.LDMLPluralRule, string>> & {
+  readonly other: string;
+};
+interface WrPluralOptions {
+  /** Prefix the formatted count before the word. @default true */
+  readonly includeValue?: boolean;
+  /** Locale override; defaults to Angular's `LOCALE_ID`. */
+  readonly locale?: string;
+}
+/** Built-in style shortcuts — pick a sensible `Intl.NumberFormat` preset by name. */
+type WrNumberStyle = 'decimal' | 'percent' | 'currency';
+/** How `wrDuration` writes a span: digits and colons (`1:30:00`), or units (`1 hr 30 min`). */
+type WrDurationStyle = 'clock' | 'units';
+/** The units a span of milliseconds splits into, largest first. */
+type WrDurationUnit = 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
+/**
+ * Split a span of milliseconds into the units asked for. A unit left out is
+ * carried into the next larger one that is kept, so `['hour', 'minute',
+ * 'second']` over three days and an hour reads 73 hours; the smallest unit kept
+ * floors whatever remains. Shared with `wr-statistic-countdown`, whose format
+ * tokens pick the units.
+ *
+ * @internal
+ */
+export declare function wrSplitDuration(ms: number, units: ReadonlySet<WrDurationUnit>): Readonly<Partial<Record<WrDurationUnit, number>>>;
+/**
+ * A span of milliseconds as text, in the given locale.
+ *
+ * Two styles. `'clock'` is digits and colons: `1:30:00`, and `5:07` under an
+ * hour; days are carried into the hours, since a clock has no day digit, so two
+ * days read `48:00:00`. `'units'` is every non-zero unit as a word the locale
+ * writes, `1 hr 30 min` in English and `1 h 30 min` in French, through
+ * `Intl.NumberFormat`'s unit style and `Intl.ListFormat` — `Intl.DurationFormat`
+ * is above the browser floor. The digits are the locale's own in both styles.
+ *
+ * Whole seconds: a fraction of a second is floored in both styles. Zero reads
+ * `0:00` and `0 sec`. A negative span is its absolute value with the locale's
+ * minus sign in front, `-5:07`. `null`, `undefined`, an empty string and a value
+ * that is not a finite number give an empty string, as `wrFormatNumber` does.
+ *
+ * The same output as the `wrDuration` pipe, for a string built in TypeScript.
+ *
+ * @example
+ * ```ts
+ * wrFormatDuration(5_400_000, 'en-US');           // "1:30:00"
+ * wrFormatDuration(5_400_000, 'en-US', 'units');  // "1 hr 30 min"
+ * wrFormatDuration(307_000, 'fr-FR', 'units');    // "5 min 7 s"
+ * ```
+ */
+export declare function wrFormatDuration(value: number | string | null | undefined, locale: string, style?: WrDurationStyle): string;
+/**
+ * A span of milliseconds as clock digits or as units, in Angular's `LOCALE_ID`.
+ * See {@link wrFormatDuration} for the two styles and the edge cases.
+ *
+ * @example
+ * ```html
+ * {{ 5400000 | wrDuration }}            <!-- "1:30:00"      -->
+ * {{ 5400000 | wrDuration: 'units' }}   <!-- "1 hr 30 min"  -->
+ * {{ 307000 | wrDuration }}             <!-- "5:07"         -->
+ * ```
+ */
+export declare class WrDuration implements PipeTransform {
+  private readonly locale;
+  transform(value: number | string | null | undefined, style?: WrDurationStyle): string;
+  static ɵfac: i0.ɵɵFactoryDeclaration<WrDuration, never>;
+  static ɵpipe: i0.ɵɵPipeDeclaration<WrDuration, "wrDuration", true>;
+}
 /**
  * Wrap every occurrence of `query` in `<mark>` tags. Useful for highlighting
  * search-term matches in autocomplete results, lists, and table cells.
@@ -104,24 +194,29 @@ export declare class WrMark implements PipeTransform {
   static ɵfac: i0.ɵɵFactoryDeclaration<WrMark, never>;
   static ɵpipe: i0.ɵɵPipeDeclaration<WrMark, "wrMark", true>;
 }
-/** Word forms keyed by CLDR plural category. Only `other` is required. */
-type WrPluralForms = Partial<Record<Intl.LDMLPluralRule, string>> & {
-  readonly other: string;
-};
-interface WrPluralOptions {
-  /** Prefix the formatted count before the word. @default true */
-  readonly includeValue?: boolean;
-  /** Locale override; defaults to Angular's `LOCALE_ID`. */
-  readonly locale?: string;
-}
-/** Built-in style shortcuts — pick a sensible `Intl.NumberFormat` preset by name. */
-type WrNumberStyle = 'decimal' | 'percent' | 'currency';
+/**
+ * A number through `Intl.NumberFormat`, in the given locale: the same output as
+ * the `wrNumber` pipe, for a string built in TypeScript. Takes a style shortcut
+ * (with an optional currency code) or a full `Intl.NumberFormatOptions` object.
+ * `null`, `undefined`, an empty string and a value that is not a finite number
+ * give an empty string.
+ *
+ * @example
+ * ```ts
+ * wrFormatNumber(1234.5, 'en-US');                      // "1,234.5"
+ * wrFormatNumber(0.875, 'en-US', 'percent');            // "87.5%"
+ * wrFormatNumber(19.99, 'de-DE', 'currency', 'EUR');    // "19,99 €"
+ * wrFormatNumber(19.99, 'en-US', { minimumFractionDigits: 2 });
+ * ```
+ */
+export declare function wrFormatNumber(value: number | string | null | undefined, locale: string, styleOrOptions?: WrNumberStyle | Intl.NumberFormatOptions, currency?: string): string;
 /**
  * Locale-aware number formatting via `Intl.NumberFormat`. Uses Angular's
  * `LOCALE_ID` as the default locale.
  *
  * Accepts either a style shortcut (with optional currency code) or a full
  * `Intl.NumberFormatOptions` object for fine-grained control.
+ * {@link wrFormatNumber} is the same output as a function.
  *
  * @example
  * ```html
@@ -134,17 +229,32 @@ type WrNumberStyle = 'decimal' | 'percent' | 'currency';
 export declare class WrNumber implements PipeTransform {
   private readonly locale;
   transform(value: number | string | null | undefined, styleOrOptions?: WrNumberStyle | Intl.NumberFormatOptions, currency?: string): string;
-  private toOptions;
   static ɵfac: i0.ɵɵFactoryDeclaration<WrNumber, never>;
   static ɵpipe: i0.ɵɵPipeDeclaration<WrNumber, "wrNumber", true>;
 }
+/**
+ * A count and its word form through `Intl.PluralRules`, in the given locale:
+ * the same output as the `wrPlural` pipe, for a string built in TypeScript.
+ * `options.locale` still wins over `locale`, as it wins over `LOCALE_ID` in the
+ * pipe. `null`, `undefined` and a value that is not a finite number give an
+ * empty string.
+ *
+ * @example
+ * ```ts
+ * wrFormatPlural(1, 'en', { one: 'comment', other: 'comments' });     // "1 comment"
+ * wrFormatPlural(5, 'ru', { one: 'файл', few: 'файла', other: 'файлов' }); // "5 файлов"
+ * wrFormatPlural(5, 'en', forms, { includeValue: false });            // "comments"
+ * ```
+ */
+export declare function wrFormatPlural(value: number | null | undefined, locale: string, forms: WrPluralForms, options?: WrPluralOptions): string;
 /**
  * Locale-aware pluralization via `Intl.PluralRules`. Picks the right word
  * form for the count — including languages with more than two forms
  * (Russian, Polish, Arabic, …) — without hand-rolled `n % 10` rules.
  *
  * Categories follow CLDR: `zero` / `one` / `two` / `few` / `many` /
- * `other`. Missing categories fall back to `other`.
+ * `other`. Missing categories fall back to `other`. {@link wrFormatPlural} is
+ * the same output as a function.
  *
  * @example
  * ```html
@@ -198,4 +308,4 @@ export declare class WrTruncate implements PipeTransform {
   static ɵfac: i0.ɵɵFactoryDeclaration<WrTruncate, never>;
   static ɵpipe: i0.ɵɵPipeDeclaration<WrTruncate, "wrTruncate", true>;
 }
-export type { WrNumberStyle, WrPluralForms, WrPluralOptions };
+export type { WrDurationStyle, WrDurationUnit, WrNumberStyle, WrPluralForms, WrPluralOptions };

package/types/ngwr-version.d.ts

@@ -15,7 +15,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.
  */
-export declare const NGWR_VERSION = "15.3.0";
+export declare const NGWR_VERSION = "15.4.0";
 /**
  * Injection token holding the ngwr library version string.
  *