ngwr 13.0.1 → 14.0.0

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

@@ -67,6 +67,14 @@ declare class WrBlurText {
      * watching the same host and all of them able to fire `animate()`.
      */
     private observer;
+    /**
+     * The effect below reaches `startObserver()` through a `queueMicrotask`, so
+     * the component can be destroyed between the two. The destroy hook runs first
+     * and disconnects whatever exists at that moment — then the continuation
+     * builds a FRESH observer on a host Angular has already detached, and nothing
+     * is left to disconnect it. Same hazard, and same flag, as `wr-split-text`.
+     */
+    private destroyed;
     constructor();
     private startObserver;
     private animate;

package/types/ngwr-button.d.ts

@@ -117,7 +117,7 @@ declare class WrButton {
      *
      * @default true
      */
-    readonly isDisabledWhenLoading: _angular_core.InputSignalWithTransform<boolean, any>;
+    readonly disabledWhenLoading: _angular_core.InputSignalWithTransform<boolean, any>;
     private readonly group;
     /** The size, or the app-wide default, or `md`. @see useConfigValue */
     protected readonly resolvedSize: _angular_core.Signal<WrButtonSize>;
@@ -164,7 +164,7 @@ declare class WrButton {
     protected onHostKeydown(event: KeyboardEvent): void;
     protected readonly classes: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrButton, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrButton, "wr-btn, button[wr-btn], a[wr-btn]", never, { "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "shape": { "alias": "shape"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconPosition": { "alias": "iconPosition"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "outlined": { "alias": "outlined"; "required": false; "isSignal": true; }; "block": { "alias": "block"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "isDisabledWhenLoading": { "alias": "isDisabledWhenLoading"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrButton, "wr-btn, button[wr-btn], a[wr-btn]", never, { "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "shape": { "alias": "shape"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconPosition": { "alias": "iconPosition"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "outlined": { "alias": "outlined"; "required": false; "isSignal": true; }; "block": { "alias": "block"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "disabledWhenLoading": { "alias": "disabledWhenLoading"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
 /**

package/types/ngwr-calendar-testing.d.ts

@@ -8,6 +8,12 @@ import { WrCalendarMode } from 'ngwr/calendar';
  * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
  */
 
+/**
+ * An arrow key, by the direction a user would say out loud — the parameter type
+ * of `WrCalendarHarness.pressArrow`, exported so a consumer's own test helper can
+ * name what it forwards.
+ */
+type WrCalendarArrowKey = 'left' | 'right' | 'up' | 'down';
 /** Which of the three sub-views the calendar is showing. */
 type WrCalendarView = 'day' | 'month' | 'year';
 /** One month or year chip, as the picker views render them. */
@@ -82,6 +88,19 @@ declare class WrCalendarDayHarness extends ComponentHarness {
     getText(): Promise<string>;
     /** The day number as a number, for mapping a list of cells to dates. */
     getDayOfMonth(): Promise<number>;
+    /**
+     * What a screen reader announces for this cell — "Thursday, January 15, 2026".
+     *
+     * A SECOND question from {@link getText}, and the reason this method exists:
+     * until v14 the cell had no name at all, so the two answers were "15" and
+     * nothing. A spec that reads only the drawn number passes on a grid that
+     * announces bare integers with no month, year or weekday anywhere in it.
+     *
+     * The string is `calendar.dayLabel` interpolated with the adapter's
+     * `longDate`, so it moves with the locale AND with the adapter — assert
+     * against the pair your spec provides, not against an English literal.
+     */
+    getAccessibleName(): Promise<string | null>;
     /** `'gridcell'` — the cell is a button, and the grid semantics are what a spec should assert. */
     getRole(): Promise<string | null>;
     /** Whether this day is (one end of) the current selection. */
@@ -122,8 +141,6 @@ declare class WrCalendarDayHarness extends ComponentHarness {
  * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
  */
 
-/** The arrow keys, by the direction a user would say out loud. */
-type Arrow = 'left' | 'right' | 'up' | 'down';
 /**
  * Test harness for `<wr-calendar>` — the standalone month grid, and the one
  * `<wr-date-picker>` puts in an overlay.
@@ -244,7 +261,7 @@ declare class WrCalendarHarness extends ComponentHarness {
      * having managed to focus a cell. Under `dir="rtl"` the horizontal pair mirrors:
      * ArrowRight goes back a day, because the grid itself is mirrored.
      */
-    pressArrow(arrow: Arrow): Promise<void>;
+    pressArrow(arrow: WrCalendarArrowKey): Promise<void>;
     /** Press Home — the first day of the roving cell's week, not of the month. */
     pressHome(): Promise<void>;
     /** Press End — the last day of the roving cell's week. */
@@ -274,4 +291,4 @@ declare class WrCalendarHarness extends ComponentHarness {
 }
 
 export { WrCalendarDayHarness, WrCalendarHarness };
-export type { WrCalendarChip, WrCalendarDayHarnessFilters, WrCalendarHarnessFilters, WrCalendarView };
+export type { WrCalendarArrowKey, WrCalendarChip, WrCalendarDayHarnessFilters, WrCalendarHarnessFilters, WrCalendarView };

package/types/ngwr-calendar.d.ts

@@ -104,7 +104,44 @@ declare class WrCalendar {
     protected readonly monthsView: _angular_core.Signal<readonly string[]>;
     /** 12-year window centered on the floor-aligned decade containing `viewDate`. */
     protected readonly yearsView: _angular_core.Signal<readonly number[]>;
+    /**
+     * The header above the grid.
+     *
+     * Both templated strings used to be assembled here: `${month} ${year}` and
+     * `${first} – ${last}`. That is English word order with an English separator
+     * baked into TypeScript, and no catalog could move either — ja-JP writes
+     * 2026年3月, which is not a translation of any word in `March 2026` but a
+     * different arrangement of the same two values. So the arrangement is the
+     * translatable unit, and `calendar.header` / `calendar.yearRange` are it.
+     */
     protected readonly headerLabel: _angular_core.Signal<string>;
+    private readonly headerText;
+    private readonly yearRangeText;
+    private readonly dayLabelText;
+    /**
+     * Long weekday names for the cell names.
+     *
+     * `getDayOfWeekNames` returns them in COLUMN order — index 0 is
+     * `getFirstDayOfWeek()`, not Sunday — which is what the header strip wants and
+     * what a `getDayOfWeek()` result (0 = Sunday) must be rotated into. Indexing
+     * it directly reads Monday's name for a Sunday in every locale that starts its
+     * week on Monday, which is most of them.
+     */
+    private readonly longWeekdays;
+    /**
+     * A day cell's accessible name — "Sunday, March 15, 2026".
+     *
+     * The cell had none. Its only content is the day NUMBER, and `role="gridcell"`
+     * does not inherit a name from the grid's header or from the column header
+     * above it, so every date in the month announced as a bare number: the month,
+     * the year and the weekday were all on screen and none of them reachable.
+     *
+     * `{{date}}` is the adapter's `longDate`, so its field order, its separators
+     * and its digits are `Intl`'s — the catalog decides only where the weekday
+     * goes. Building it from `getMonthNames('long')` instead would have hard-coded
+     * the nominative month, which Russian and Finnish inflect inside a date.
+     */
+    protected dayLabel(date: Date): string;
     /** 6×7 day grid covering the current month plus spillover. */
     protected readonly weeks: _angular_core.Signal<readonly (readonly Date[])[]>;
     /**

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

@@ -33,6 +33,15 @@ declare class WrCircularText {
     private readonly platform;
     private rotation;
     private hovered;
+    /**
+     * The effect below reaches `startOrSwap()` through a `queueMicrotask`, so the
+     * ring can be destroyed between the two. Without this flag the continuation
+     * then starts an infinite Web Animation on a host Angular has already
+     * detached — and an animation keeps its target alive, so the whole `#spin`
+     * subtree is retained for the life of the page. Same hazard, and same flag, as
+     * `wr-split-text` and `wr-fuzzy-text`.
+     */
+    private destroyed;
     /** Active spin duration in seconds — base, or hover-modified. */
     private effectiveDuration;
     constructor();

package/types/ngwr-collapse.d.ts

@@ -54,6 +54,21 @@ declare class WrCollapse {
  * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
  */
 
+/**
+ * What a `<wr-collapse>` hands its parent group when it registers.
+ *
+ * A named export rather than the structural type it used to be spelled as. Both
+ * group components declared their OWN local `interface Member`, so d.ts
+ * flattening had two of one name to resolve and published the second as
+ * `Member$1` — a bundler-assigned identifier in the signature of a public method,
+ * which no consumer could import and nobody had authored.
+ */
+interface WrCollapseGroupMember {
+    /** Close this collapse — the group calls it on siblings in accordion mode. */
+    close(): void;
+    /** Identity of the registering collapse, used as the map key and by `notifyOpened`. */
+    readonly id: object;
+}
 /**
  * Contract a collapse uses to talk to its parent `<wr-collapse-group>`.
  *
@@ -65,10 +80,7 @@ interface WrCollapseGroupContext {
     /** Called by a child when it opens — closes siblings in accordion mode. */
     notifyOpened(opener: object): void;
     /** Register a child so the group can call `closeAll()` etc. */
-    register(member: {
-        close(): void;
-        readonly id: object;
-    }): void;
+    register(member: WrCollapseGroupMember): void;
     /** Unregister on destroy. */
     unregister(memberId: object): void;
 }
@@ -81,10 +93,6 @@ interface WrCollapseGroupContext {
  */
 declare const WR_COLLAPSE_GROUP: InjectionToken<WrCollapseGroupContext>;
 
-interface Member$1 {
-    close(): void;
-    readonly id: object;
-}
 /**
  * Visual + behavioral grouping of `<wr-collapse>` children. When
  * `accordion` is true, opening one child closes the others.
@@ -95,17 +103,13 @@ declare class WrCollapseGroup implements WrCollapseGroupContext {
     /** When true, only one child may be open at a time. @default false */
     readonly accordion: _angular_core.InputSignalWithTransform<boolean, any>;
     private readonly members;
-    register(member: Member$1): void;
+    register(member: WrCollapseGroupMember): void;
     unregister(memberId: object): void;
     notifyOpened(opener: object): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrCollapseGroup, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCollapseGroup, "wr-collapse-group", never, { "accordion": { "alias": "accordion"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
-interface Member {
-    close(): void;
-    readonly id: object;
-}
 /**
  * Accordion — a `<wr-collapse>` container that enforces single-open
  * behavior: opening a child closes its siblings.
@@ -128,7 +132,7 @@ declare class WrAccordion implements WrCollapseGroupContext {
     /** Always behaves as an accordion. Provided for context-interface symmetry. */
     readonly accordion: _angular_core.Signal<boolean>;
     private readonly members;
-    register(member: Member): void;
+    register(member: WrCollapseGroupMember): void;
     unregister(memberId: object): void;
     notifyOpened(opener: object): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrAccordion, never>;
@@ -136,4 +140,4 @@ declare class WrAccordion implements WrCollapseGroupContext {
 }
 
 export { WR_COLLAPSE_GROUP, WrAccordion, WrCollapse, WrCollapseGroup };
-export type { WrCollapseGroupContext };
+export type { WrCollapseGroupContext, WrCollapseGroupMember };

package/types/ngwr-color-picker-testing.d.ts

@@ -193,10 +193,16 @@ declare class WrColorPickerHarness extends ComponentHarness {
     /**
      * Where the three thumbs sit, in percent along their surfaces.
      *
-     * The component writes these as inline `left` / `top` percentages, so they are
-     * readable with no layout at all — which makes them the only evidence a spec has
-     * that the surfaces followed a colour set through the fields. A measured position
-     * would be zero for all three.
+     * The component writes these as inline percentages, so they are readable with no
+     * layout at all — which makes them the only evidence a spec has that the surfaces
+     * followed a colour set through the fields. A measured position would be zero for
+     * all three.
+     *
+     * The number is always "along the surface from its own start", so it is direction
+     * free: the SV canvas reports a physical `left` because it does not mirror, and
+     * the two tracks report `inset-inline-start` because they do. An RTL spec reads
+     * the same value as an LTR one, which is the point — what mirrors is where that
+     * fraction lands on screen, not the fraction.
      *
      * Read off the `style` ATTRIBUTE rather than through `getCssValue()`, and the
      * difference is not cosmetic: `getCssValue()` is `getComputedStyle()`, and `left` /

package/types/ngwr-color-picker.d.ts

@@ -239,6 +239,18 @@ declare class WrColorPicker implements FormValueControl<string> {
     protected readonly hueCss: _angular_core.Signal<string>;
     /** RGB string used for the alpha-slider gradient. */
     protected readonly rgbCss: _angular_core.Signal<string>;
+    /**
+     * Ambient reading direction, for the two SLIDERS only — see `updateFromEvent`
+     * for why the SV canvas is not in that set.
+     *
+     * Optional so a bare `TestBed` — or any consumer that never set a direction —
+     * needs no provider; `Directionality` is root-provided, so `null` only ever
+     * means "nobody asked", which is LTR. Read inside the handlers rather than
+     * cached: the thumbs are placed with `inset-inline-start`, so the tracks mirror
+     * from CSS alone and a runtime flip needs no subscription to
+     * `Directionality.change`.
+     */
+    private readonly dir;
     /** Thumb positions in % for each surface. */
     protected readonly svThumbX: _angular_core.Signal<number>;
     protected readonly svThumbY: _angular_core.Signal<number>;
@@ -259,7 +271,33 @@ declare class WrColorPicker implements FormValueControl<string> {
     protected readonly resolvedAreaLabel: _angular_core.Signal<string>;
     protected readonly resolvedHueLabel: _angular_core.Signal<string>;
     protected readonly resolvedAlphaLabel: _angular_core.Signal<string>;
-    protected readonly tabOptions: readonly WrSegmentedOption<Tab>[];
+    /**
+     * Every visible word in this component that is not a slider name.
+     *
+     * The format strip and the nine channel captions were literals — three in
+     * TypeScript, the rest in the template — beside a `colorPicker` catalog
+     * section that already existed and held the slider names. So the section was
+     * there and these had simply not been put in it, which is why a fully Russian
+     * picker still read `HEX RGB HSL` over `R G B`. Each caption is one string
+     * INCLUDING its `%`, because a locale that spaces the sign differently has to
+     * move the letter and the sign together.
+     *
+     * Signals, not strings: they follow a locale switch, and a catalog that lands
+     * a microtask after the first change-detection pass.
+     */
+    protected readonly channelHexLabel: _angular_core.Signal<string>;
+    protected readonly channelRedLabel: _angular_core.Signal<string>;
+    protected readonly channelGreenLabel: _angular_core.Signal<string>;
+    protected readonly channelBlueLabel: _angular_core.Signal<string>;
+    protected readonly channelHueLabel: _angular_core.Signal<string>;
+    protected readonly channelSaturationLabel: _angular_core.Signal<string>;
+    protected readonly channelLightnessLabel: _angular_core.Signal<string>;
+    protected readonly channelAlphaLabel: _angular_core.Signal<string>;
+    private readonly formatHexLabel;
+    private readonly formatRgbLabel;
+    private readonly formatHslLabel;
+    /** A `computed`, because `WrSegmentedOption.label` is a plain string. */
+    protected readonly tabOptions: _angular_core.Signal<readonly WrSegmentedOption<Tab>[]>;
     protected readonly classes: _angular_core.Signal<string>;
     /**
      * The one write we just made, held only until the sync effect has seen it.
@@ -278,16 +316,46 @@ declare class WrColorPicker implements FormValueControl<string> {
     /**
      * Hue and alpha are real one-value sliders, so they take the APG slider keys —
      * the same set `wr-knob` and `wr-slider` implement, including Home / End.
+     *
+     * The horizontal arrows name a SIDE of the track and so follow the reading
+     * direction, exactly as `wr-slider`'s do; the vertical pair names a value's
+     * direction and never mirrors.
      */
     protected onSliderKeydown(event: KeyboardEvent, surface: 'hue' | 'alpha'): void;
     /**
      * The SV canvas is two axes at once, so the keys follow the picture: left and
      * right run along saturation, up and down along brightness — the directions
      * the thumb visibly moves. Shift takes ten percent at a time.
+     *
+     * Not mirrored under `dir="rtl"`, unlike the two sliders above, and for the
+     * reason given on `fraction()`: the canvas is a picture rather than a track, so
+     * its gradient does not flip and neither may the keys that walk it.
      */
     protected onAreaKeydown(event: KeyboardEvent): void;
     /** Leaving a surface is what "touched" means, the same as leaving the hex field. */
     protected onSurfaceBlur(): void;
+    /**
+     * The pointer's position along a surface, as a 0–1 fraction.
+     *
+     * Measured from whichever edge the surface STARTS at, and the two surfaces do
+     * not agree on what that means — deliberately.
+     *
+     * The hue and alpha bars are one-value tracks with `role="slider"`, the same
+     * widget `wr-slider` is, so they mirror: their thumbs are placed with
+     * `inset-inline-start` and their gradients are flipped by a `[dir='rtl']` rule,
+     * which makes the reader's start the physical right edge under `dir="rtl"`.
+     * Opacity 100% used to sit at the physical right in both directions, i.e. at
+     * the reader's START in RTL, while the format strip in the same panel mirrored
+     * correctly.
+     *
+     * The SV canvas does NOT mirror, and stays measured from `rect.left`. It is a
+     * two-axis colour FIELD, not a track — the component says so itself by giving
+     * it `role="group"` rather than `role="slider"`, because it carries two values
+     * and a slider has one. A picture with no start and no end has nothing to
+     * mirror, and flipping it would only move white to the other side of an image
+     * every colour picker in the world draws the same way.
+     */
+    private fraction;
     private updateFromEvent;
     protected onHexInput(event: Event): void;
     protected onHexBlur(): void;
@@ -360,7 +428,7 @@ declare class WrColorPickerTrigger {
     close(): void;
     private dispose;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrColorPickerTrigger, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WrColorPickerTrigger, "[wrColorPickerTrigger]", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "alpha": { "alias": "alpha"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "swatches": { "alias": "swatches"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "opened": "opened"; "closed": "closed"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WrColorPickerTrigger, "[wrColorPickerTrigger]", ["wrColorPickerTrigger"], { "value": { "alias": "value"; "required": false; "isSignal": true; }; "alpha": { "alias": "alpha"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "swatches": { "alias": "swatches"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "opened": "opened"; "closed": "closed"; }, never, never, true, never>;
 }
 
 export { WrColorPicker, WrColorPickerTrigger, hslToRgb, hsvToRgb, parseHex, rgbToHsl, rgbToHsv, toHex };

package/types/ngwr-command-palette.d.ts

@@ -71,6 +71,12 @@ declare class WrCommandPalette {
     readonly emptyText: _angular_core.InputSignal<string | null>;
     protected readonly resolvedPlaceholder: _angular_core.Signal<string>;
     protected readonly resolvedEmpty: _angular_core.Signal<string>;
+    /**
+     * The key-cap chip beside the search field. It was the literal `esc` in the
+     * template — the one string on this component no catalog could reach, so a
+     * fully Russian palette still hinted in English.
+     */
+    protected readonly resolvedEscHint: _angular_core.Signal<string>;
     /** Auto-close on `(picked)`. Set false to keep open. @default true */
     readonly closeOnPick: _angular_core.InputSignalWithTransform<boolean, any>;
     /**
@@ -110,6 +116,14 @@ declare class WrCommandPalette {
     private bindingHandle;
     private focusTrap;
     private previouslyFocused;
+    /**
+     * The open branch below builds the trap inside a `queueMicrotask`, so a
+     * palette destroyed while open — in the same task that opened it — runs its
+     * destroy hook first and then constructs a fresh trap nothing will ever
+     * destroy. A `ConfigurableFocusTrap` plants two anchor elements in the panel
+     * and holds it, so that is retained DOM, not just a stray object.
+     */
+    private destroyed;
     /** Grouped view — what the template renders. */
     protected readonly buckets: _angular_core.Signal<readonly Bucket[]>;
     /**

package/types/ngwr-context-menu.d.ts

@@ -182,7 +182,7 @@ declare class WrContextMenu {
     private cancelLeaveTimer;
     private scheduleLeave;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrContextMenu, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WrContextMenu, "[wrContextMenu]", never, { "menu": { "alias": "wrContextMenu"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WrContextMenu, "[wrContextMenu]", ["wrContextMenuTrigger"], { "menu": { "alias": "wrContextMenu"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**

package/types/ngwr-date-adapters-fns.d.ts

@@ -1,6 +1,7 @@
 import { WrDateAdapter, WrDateFormat } from 'ngwr/date';
 import * as i0 from '@angular/core';
-import { EnvironmentProviders } from '@angular/core';
+import { EnvironmentProviders, InjectionToken } from '@angular/core';
+import { Locale } from 'date-fns';
 
 /**
  * {@link WrDateAdapter} backed by `date-fns`. Same `Date` value type as the
@@ -8,32 +9,28 @@ import { EnvironmentProviders } from '@angular/core';
  * pick this when you want its long patterns (`P`, `PP`, `PPP`, `p`) without
  * writing them by hand.
  *
- * **{@link WR_DATE_LOCALE} does not reach `format` or `parse`, and that is not
- * an oversight.** date-fns resolves those patterns against a date-fns `Locale`
- * OBJECT rather than a BCP 47 tag, and the objects are separate modules —
- * mapping a tag onto one would mean importing all of them, which defeats the
- * tree-shaking that is the reason this is an opt-in entry point. So the named
- * formats render AND read in en-US whatever the tag says, while
- * `getFirstDayOfWeek`, `getDayOfWeekNames` and `getMonthNames` go through `Intl`
- * and do honour it: a calendar heads its columns `пн вт ср` beside a trigger
- * reading `08/11/2025`. Reading is the sharper edge — `11/08/2025` typed by a
- * user in a dd/MM locale parses as 8 November, valid and wrong.
- *
- * The lever is date-fns's own module default, and the adapter passing no locale
- * is precisely what keeps it working. Set it once at bootstrap, or take
- * `provideWrLuxonAdapter()`, which forwards the tag itself:
+ * **Localising it takes TWO settings, and that is a property of date-fns rather
+ * than a wart here.** `WR_DATE_LOCALE` is a BCP 47 tag; date-fns resolves its
+ * patterns against a `Locale` OBJECT, and the objects are separate modules, so
+ * mapping a tag onto one would mean importing all of them and defeating the
+ * tree-shaking that is the reason this is an opt-in entry point. Pass the object
+ * as `dateFnsLocale` and it reaches `format` and `parse`; leave it out and they
+ * stay on date-fns's own module default, which is what keeps
+ * `setDefaultOptions({ locale })` working for apps that already use it.
  *
- * ```ts
- * import { setDefaultOptions } from 'date-fns';
- * import { ru } from 'date-fns/locale';
- *
- * setDefaultOptions({ locale: ru });
- * ```
+ * Half-localising is the failure mode this is designed to make loud: with only a
+ * tag, `getFirstDayOfWeek`, `getDayOfWeekNames` and `getMonthNames` go through
+ * `Intl` and answer in the locale while the trigger beside them reads
+ * `08/11/2025`, and READING is the sharper edge — `11/08/2025` typed by a user in
+ * a dd/MM locale parses as 8 November, valid and wrong. A non-English tag with no
+ * object warns once in dev mode for exactly that reason.
  *
  * @example
  * ```ts
+ * import { ru } from 'date-fns/locale/ru';
+ *
  * bootstrapApplication(AppComponent, {
- *   providers: [provideWrDateFnsAdapter()],
+ *   providers: [provideWrDateFnsAdapter({ locale: 'ru-RU', dateFnsLocale: ru })],
  * });
  * ```
  *
@@ -41,6 +38,10 @@ import { EnvironmentProviders } from '@angular/core';
  */
 declare class WrDateFnsAdapter extends WrDateAdapter<Date> {
     private readonly locale;
+    private readonly dateFnsLocale;
+    constructor();
+    /** What date-fns is handed. `{}` leaves its module default in charge. */
+    private get options();
     today(): Date;
     clone(date: Date): Date;
     createDate(year: number, month: number, day: number): Date;
@@ -80,21 +81,62 @@ declare class WrDateFnsAdapter extends WrDateAdapter<Date> {
  * Register the {@link WrDateFnsAdapter} so date-pickers / calendars in this
  * app use `date-fns` for all math and formatting.
  *
- * `locale` sets {@link WR_DATE_LOCALE}, which this adapter reads for the first
- * day of the week and nothing else — its `format` and `parse` do not pass a
- * locale to date-fns. For localized month names and patterns, set date-fns's own
- * module default with `setDefaultOptions`, or use the luxon adapter, which does
- * thread the tag through everything.
+ * Two locale settings, because date-fns needs a `Locale` OBJECT where the rest of the
+ * library needs a BCP 47 TAG:
+ *
+ * - `dateFnsLocale` — the imported object. It reaches `format` and `parse`, which is
+ *   where the field's own text comes from, and it also decides the first day of the
+ *   week. Leave it out and date-fns stays on its module default, so an existing
+ *   `setDefaultOptions({ locale })` keeps working.
+ * - `locale` — the tag {@link WR_DATE_LOCALE} carries, read through `Intl` for the month
+ *   and weekday NAMES. Omit it and the object's own `code` supplies it, so one import is
+ *   enough for a fully localized picker.
+ *
+ * Passing only `locale` localizes the calendar headings and not the field, which is the
+ * shape of a real defect rather than a preference — the adapter warns about it once in
+ * dev mode.
  *
  * @example
  * ```ts
+ * import { ru } from 'date-fns/locale/ru';
+ *
  * bootstrapApplication(AppComponent, {
- *   providers: [provideWrDateFnsAdapter()],
+ *   providers: [provideWrDateFnsAdapter({ dateFnsLocale: ru })],
  * });
  * ```
  */
 declare function provideWrDateFnsAdapter(options?: {
     readonly locale?: string;
+    readonly dateFnsLocale?: Locale;
 }): EnvironmentProviders;
 
-export { WrDateFnsAdapter, provideWrDateFnsAdapter };
+/**
+ * @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 date-fns `Locale` OBJECT {@link WrDateFnsAdapter} formats and parses with.
+ *
+ * `WR_DATE_LOCALE` is a BCP 47 TAG, and date-fns cannot resolve a tag: its locales are
+ * separate modules, so mapping `'ru-RU'` onto one would mean importing all of them and
+ * defeating the tree-shaking that makes this an opt-in entry point. The consumer imports
+ * the one they need and hands it over — which is what
+ * {@link provideWrDateFnsAdapter}'s `dateFnsLocale` option sets.
+ *
+ * `null` (the default) passes nothing to date-fns, which leaves that library's own
+ * module-level default in charge — so `setDefaultOptions({ locale })` keeps working for
+ * apps that already use it.
+ *
+ * @example
+ * ```ts
+ * import { ru } from 'date-fns/locale/ru';
+ *
+ * provideWrDateFnsAdapter({ locale: 'ru-RU', dateFnsLocale: ru });
+ * ```
+ */
+declare const WR_DATE_FNS_LOCALE: InjectionToken<Locale | null>;
+
+export { WR_DATE_FNS_LOCALE, WrDateFnsAdapter, provideWrDateFnsAdapter };