ngwr 14.4.0 → 14.5.1

package/types/ngwr-drawer.d.ts

@@ -168,8 +168,28 @@ declare class WrDrawer {
     private readonly overlay;
     private readonly vcr;
     private readonly destroyRef;
+    private readonly injector;
     private readonly focusTrapFactory;
     private readonly isBrowser;
+    /**
+     * The reading direction the open drawer has to keep up with, resolved off the
+     * ENVIRONMENT injector rather than this component's.
+     *
+     * That is where the CDK read it: `createOverlayRef` takes `Directionality`
+     * from the `Overlay`'s own injector, which `provideWrOverlay()` parents to
+     * the application's, so a node-level CDK `[dir]` is never in the chain. A
+     * panel is not IN that island either — it is appended to the overlay
+     * container on `<body>` — so following the node injector would not follow the
+     * ref at all: it would rewrite a correctly-stamped panel to the island's
+     * direction one pass after it opened, and `WrDrawerManager`, a root service
+     * with no island to read, could never do the same. Two halves of one
+     * component, same panel classes, same stylesheet, two answers.
+     *
+     * `null` never happens in an app — `Directionality` is root-provided — but a
+     * bare `TestBed` should still get a drawer that opens, with nothing ambient
+     * to follow.
+     */
+    private readonly dir;
     private overlayRef;
     private focusTrap;
     private previouslyFocused;
@@ -297,6 +317,14 @@ declare class WrDrawerManager {
     private readonly isBrowser;
     private readonly i18n;
     private readonly location;
+    /**
+     * The application's reading direction — the instance the CDK itself read when
+     * it stamped the overlay. A root service has no node injector above it, so a
+     * plain `inject()` here already resolves the environment one; `<wr-drawer>`,
+     * which does, spells that out and says why. The two halves of one component
+     * must not answer differently about the same panel.
+     */
+    private readonly dir;
     open<C, R = unknown, D = unknown>(component: ComponentType<C>, options?: WrDrawerOptions<D>): WrDrawerRef<C, R>;
     /**
      * Tie the drawer's lifetime to the URL it was opened on — the same treatment

package/types/ngwr-dropdown.d.ts

@@ -73,10 +73,19 @@ declare class WrDropdown {
     readonly closed: _angular_core.OutputEmitterRef<void>;
     private readonly host;
     private readonly overlay;
+    /**
+     * The reading direction the open menu has to keep up with.
+     *
+     * Optional inject: `Directionality` is root-provided, so this is never null in
+     * an app — but a bare `TestBed` that provides nothing should still get a menu
+     * that opens, with simply nothing ambient to follow.
+     */
+    private readonly dir;
     private readonly outsideClick;
     private readonly responsiveConfig;
     private readonly vcr;
     private readonly scrollStrategies;
+    private readonly injector;
     private readonly destroyRef;
     /** @internal Public so host bindings can read it. */
     readonly isOpen: _angular_core.WritableSignal<boolean>;

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

@@ -0,0 +1,190 @@
+import { BaseHarnessFilters, ComponentHarness, ComponentHarnessConstructor, HarnessPredicate } from '@angular/cdk/testing';
+
+/**
+ * @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
+ */
+
+/** Narrows which `<wr-graph>` a harness query matches. */
+interface WrGraphHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the viewport's accessible name — `ariaLabel`, or the catalog's `graph.label`
+     * when none is bound. A string is an exact match, a RegExp is tested.
+     */
+    readonly ariaLabel?: string | RegExp;
+    /**
+     * Match a graph that draws a node with this text (see `WrGraphNodeHarness.getText`) —
+     * the way to tell two graphs apart when neither was given a name of its own. A node
+     * of a graph nested inside one of this graph's node templates does not count, for a
+     * RegExp as much as for a string: the node text it is tested against leaves the
+     * nested graph out.
+     */
+    readonly nodeLabel?: string | RegExp;
+}
+/** Narrows which node of a `<wr-graph>` a harness query matches. */
+interface WrGraphNodeHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the node's DRAWN text, as `WrGraphNodeHarness.getText` reads it: the label on
+     * the default card, and everything a `wrGraphNode` template drew otherwise — so a
+     * RegExp is how to match one part of a template. A string is an exact match. A
+     * `<wr-graph>` the template nests inside the node is not part of that text.
+     */
+    readonly label?: string | RegExp;
+}
+
+/**
+ * @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
+ */
+
+/**
+ * Test harness for one node of a `<wr-graph>` — a `role="listitem"` block.
+ *
+ * A node answers two questions, and they are kept apart on purpose. {@link getText} is
+ * what is DRAWN: the default card, or whatever a `wrGraphNode` template rendered.
+ * {@link getRelationText} is what is ANNOUNCED about its place in the graph: the
+ * lines are `aria-hidden`, so the visually hidden sentence naming the parents and the
+ * children is the only form the structure takes for a screen reader. A spec that read
+ * the node's whole text would get both glued together, and would keep passing on a
+ * graph whose relation sentences named the wrong neighbours.
+ *
+ * There is no `getId()`. The component writes a node's id nowhere in the DOM — only
+ * an edge carries ids, on its `data-from` / `data-to` — so a node is addressed by what
+ * it draws, and {@link WrGraphHarness.getEdges} is where ids are read.
+ *
+ * @example
+ * ```ts
+ * const birch = await graph.getNode({ label: 'Birch' });
+ *
+ * expect(await birch.getText()).toBe('Birch');
+ * expect(await birch.getRelationText()).toBe('Parents: Atlas. Children: Dune.');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrGraphNodeHarness extends ComponentHarness {
+    static hostSelector: string;
+    /**
+     * Build a predicate that narrows the query.
+     *
+     * Typed on `this`, so the predicate is built for whichever node harness it is called
+     * on — {@link WrGraphHarness.getNodes} narrows its own, direct-child query through
+     * the same options.
+     */
+    static with<T extends WrGraphNodeHarness>(this: ComponentHarnessConstructor<T>, options?: WrGraphNodeHarnessFilters): HarnessPredicate<T>;
+    /**
+     * The text the node DRAWS, trimmed, with the relation sentence left out.
+     *
+     * The sentence is a real text node inside the block — visually hidden, not removed —
+     * so a plain text read would end in `Parents: Atlas. Children: Dune.`. It is excluded
+     * rather than subtracted.
+     *
+     * A `<wr-graph>` a template nests inside the node is left out whole, cards and
+     * sentences alike: it is a graph of its own, and its nodes answer to its own harness.
+     * So a node drawing `Harbor` above an inner graph of `Kestrel` and `Lark` reads
+     * `Harbor`, and a `/Lark/` label does not match it.
+     */
+    getText(): Promise<string>;
+    /**
+     * The sentence a screen reader hears about the node's place in the graph — its
+     * parents, then its children, as the catalog words them — or `null` for a node with
+     * no edges, which the graph gives no sentence at all.
+     *
+     * `null` rather than `''`: the component never writes an empty sentence, so an empty
+     * string could only mean the element exists and says nothing, which is a different
+     * failure from a node that has nothing to say.
+     */
+    getRelationText(): Promise<string | 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
+ */
+
+/**
+ * Test harness for `<wr-graph>` — blocks joined by parent-child lines, laid out in
+ * layers, display only.
+ *
+ * The graph is read the way assistive technology reads it: the viewport's name, the
+ * nodes as a list in READING order (layer, then inline position — which is DOM order),
+ * each node's drawn text and its relation sentence, and the edges as the `from` / `to`
+ * ids the component writes on each line. Those are what break when the data wiring
+ * does.
+ *
+ * Three methods are deliberately absent, and each would answer the same for a working
+ * graph and a broken one:
+ *
+ * - **No edge path `d`.** A path is a rendering detail: rounded to two decimals, mirrored
+ *   under RTL, and moved by every node size and gap. The same rule as
+ *   `WrLineChartHarness`.
+ * - **No node positions.** jsdom lays nothing out, so every measured box is 0×0. The
+ *   inline `transform` IS the component's own write and would be readable, but its
+ *   numbers belong to a layout that is internal in this release — a harness method
+ *   returning them would make every layout improvement a breaking change to consumer
+ *   specs. Coordinates are pinned in the layout's own pure spec, where the arithmetic is.
+ * - **No "is scrollable".** Overflow is layout: in jsdom `scrollWidth` and `clientWidth`
+ *   are both 0 for a graph that fits and for one ten times wider. The viewport's
+ *   `tabindex` is no proxy either — it is always `0`, precisely so the tab stop never
+ *   depends on a measurement.
+ *
+ * An empty graph and a graph whose layout drew nothing render the same DOM, so the
+ * harness cannot tell them apart. {@link getNodes} answers `[]` for both, which is the
+ * honest way to assert emptiness; {@link getEdges} refuses instead, because "no edges"
+ * would be vacuously true of a graph that drew nothing at all.
+ *
+ * @example
+ * ```ts
+ * const graph = await loader.getHarness(WrGraphHarness.with({ ariaLabel: 'Team structure' }));
+ *
+ * expect(await graph.getEdges()).toEqual([{ from: 'atlas', to: 'birch' }]);
+ * const birch = await graph.getNode({ label: 'Birch' });
+ * expect(await birch.getRelationText()).toBe('Parents: Atlas.');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrGraphHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrGraphHarnessFilters): HarnessPredicate<WrGraphHarness>;
+    /**
+     * The viewport's accessible name — the scroller is the graph's one tab stop and the
+     * element that carries it, never the host.
+     */
+    getAccessibleName(): Promise<string | null>;
+    /**
+     * This graph's nodes, in reading order, narrowed by the filters.
+     *
+     * Only the graph's own: a graph drawn inside one of its node templates has nodes of
+     * its own, and they are not this graph's. `[]` for a graph that draws no node — see
+     * the class note for why that answer cannot tell empty data from a layout that drew
+     * nothing.
+     */
+    getNodes(filters?: WrGraphNodeHarnessFilters): Promise<WrGraphNodeHarness[]>;
+    /** The first node matching the filters, or a failure that says what the graph draws. */
+    getNode(filters: WrGraphNodeHarnessFilters): Promise<WrGraphNodeHarness>;
+    /**
+     * One `{ from, to }` per line drawn, read off the path's `data-from` / `data-to` —
+     * node ids, the only place the DOM writes one — in the order the edges were given,
+     * with the edges the graph skipped left out. Parallel edges each appear, since each is
+     * its own line.
+     *
+     * Throws on a graph that draws no nodes, rather than answering `[]`: that answer would
+     * be the same for empty data and for a layout that drew nothing, and a spec asserting
+     * "no edges" would pass on both.
+     */
+    getEdges(): Promise<{
+        from: string;
+        to: string;
+    }[]>;
+}
+
+export { WrGraphHarness, WrGraphNodeHarness };
+export type { WrGraphHarnessFilters, WrGraphNodeHarnessFilters };

package/types/ngwr-graph.d.ts

@@ -0,0 +1,203 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef } 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
+ */
+/**
+ * A parent-child link: `from` is the parent, `to` the child. The line is drawn
+ * with its arrow at the child.
+ *
+ * Several edges between one pair and edges that close a cycle are both legal.
+ * An edge naming a node that does not exist is skipped (dev mode warns).
+ */
+interface WrGraphEdge {
+    /** Id of the parent node. */
+    readonly from: string;
+    /** Id of the child node. */
+    readonly to: 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
+ */
+/**
+ * One block in a `wr-graph`.
+ *
+ * The component knows nothing about what a node stands for — anything the
+ * picture needs beyond `label` travels in `data` and is drawn by the consumer's
+ * `ng-template[wrGraphNode]`.
+ */
+interface WrGraphNode<TData = unknown> {
+    /** Unique within the graph. A repeated id is skipped after its first occurrence (dev mode warns). */
+    readonly id: string;
+    /**
+     * The node's name. The default card shows it, and every neighbour's relation
+     * text reads it out — so a custom template should render it too, or a screen
+     * reader hears a name no node announces.
+     */
+    readonly label: string;
+    /** Width in pixels. Falls back to the graph's `nodeWidth` when absent, non-finite or not positive. */
+    readonly width?: number;
+    /** Height in pixels. Falls back to the graph's `nodeHeight` when absent, non-finite or not positive. */
+    readonly height?: number;
+    /** Anything the node template needs. Never read by the component or the layout. */
+    readonly data?: TData;
+}
+/** The context an `ng-template[wrGraphNode]` receives: the node as `let-node`. */
+interface WrGraphNodeContext<TData = unknown> {
+    readonly $implicit: WrGraphNode<TData>;
+}
+
+/**
+ * @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
+ */
+
+/**
+ * Replace the default card. The node is the implicit context; its box — the
+ * size the layout reserved, its position and the relation text read to a screen
+ * reader — stays with the graph, so a template cannot break the geometry.
+ *
+ * Render `node.label` somewhere in it: the relation text of every neighbour
+ * names this node by its label.
+ *
+ * @example
+ * ```html
+ * <wr-graph [nodes]="nodes" [edges]="edges">
+ *   <ng-template wrGraphNode let-node>
+ *     <strong>{{ node.label }}</strong> {{ node.data.role }}
+ *   </ng-template>
+ * </wr-graph>
+ * ```
+ */
+declare class WrGraphNodeTemplate {
+    readonly template: TemplateRef<WrGraphNodeContext<unknown>>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrGraphNodeTemplate, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WrGraphNodeTemplate, "ng-template[wrGraphNode]", never, {}, {}, never, never, true, never>;
+}
+
+interface DrawnNode<TData> {
+    readonly node: WrGraphNode<TData>;
+    readonly width: number;
+    readonly height: number;
+    readonly transform: string;
+}
+interface DrawnEdge {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    readonly d: string;
+}
+/** What the template binds: physical pixels, already mirrored for RTL. */
+interface GraphView<TData> {
+    readonly width: number;
+    readonly height: number;
+    readonly nodes: readonly DrawnNode<TData>[];
+    readonly edges: readonly DrawnEdge[];
+}
+/**
+ * A graph of blocks joined by parent-child links, laid out in layers from top to
+ * bottom. Display only: nothing is selectable, and the graph scrolls inside its
+ * own viewport rather than the page.
+ *
+ * The layout runs in a `computed` with no DOM and no measuring, so the sizes are
+ * the consumer's: `nodeWidth` / `nodeHeight` for every node, or `width` /
+ * `height` on one. A prerender therefore ships the finished picture.
+ *
+ * What the lines show is also written out: every node carries visually hidden
+ * text naming its parents and children, and the lines themselves are hidden
+ * from assistive technology.
+ *
+ * @example
+ * ```html
+ * <wr-graph [nodes]="nodes" [edges]="edges" ariaLabel="Team structure" />
+ * ```
+ *
+ * @see https://ngwr.dev/reference/components/graph
+ */
+declare class WrGraph<TData = unknown> {
+    /**
+     * The nodes, in any order. Input order breaks layout ties, so the same arrays
+     * always produce the same picture. Never mutated.
+     *
+     * @default []
+     */
+    readonly nodes: _angular_core.InputSignal<readonly WrGraphNode<TData>[]>;
+    /**
+     * Parent-child links, `from` the parent and `to` the child. Never mutated.
+     *
+     * @default []
+     */
+    readonly edges: _angular_core.InputSignal<readonly WrGraphEdge[]>;
+    /**
+     * Width in pixels of a node that sets none of its own.
+     *
+     * @default 160
+     */
+    readonly nodeWidth: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Height in pixels of a node that sets none of its own.
+     *
+     * @default 48
+     */
+    readonly nodeHeight: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Accessible name of the scrolling viewport. Falls back to `graph.label`, then `'Graph'`. */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly label: _angular_core.Signal<string>;
+    private readonly parentsText;
+    private readonly childrenText;
+    protected readonly nodeTemplate: _angular_core.Signal<WrGraphNodeTemplate | undefined>;
+    /** `url(#…)` for every edge's `marker-end`. */
+    protected readonly markerId: string;
+    protected readonly markerUrl: string;
+    protected readonly arrowSize = 6;
+    private readonly engine;
+    private readonly dir;
+    private readonly i18n;
+    private readonly localeId;
+    private readonly isRtl;
+    private readonly locale;
+    /**
+     * The size of a node that sets none of its own. Each dimension falls back on its
+     * own, and the dev warning reads this same value, so it cannot name a size the
+     * layout did not use.
+     */
+    private readonly defaultSize;
+    private readonly prepared;
+    /** The engine's answer, as returned. A fresh signal per run: nothing aborts a synchronous layout. */
+    private readonly raw;
+    /**
+     * The drawable result. An asynchronous layout is declared by the interface and
+     * not supported by this release: a thenable draws nothing, and dev mode says so.
+     */
+    private readonly result;
+    /** Layout joined to the nodes and edges, direction-free, nodes in reading order. */
+    private readonly placed;
+    /**
+     * Physical pixels. Mirrored here rather than in CSS so nodes and lines get the
+     * same numbers and cannot drift apart — and kept apart from the layout so a
+     * direction change does not lay the graph out again.
+     */
+    protected readonly view: _angular_core.Signal<GraphView<TData>>;
+    /**
+     * The visually hidden sentence per node id: its parents, then its children, as
+     * name lists. Never a count — the catalogs have no plural forms. A neighbour
+     * linked by several edges is named once, and names follow reading order.
+     */
+    protected readonly relations: _angular_core.Signal<Map<string, string>>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrGraph<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrGraph<any>, "wr-graph", never, { "nodes": { "alias": "nodes"; "required": false; "isSignal": true; }; "edges": { "alias": "edges"; "required": false; "isSignal": true; }; "nodeWidth": { "alias": "nodeWidth"; "required": false; "isSignal": true; }; "nodeHeight": { "alias": "nodeHeight"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, ["nodeTemplate"], never, true, never>;
+}
+
+export { WrGraph, WrGraphNodeTemplate };
+export type { WrGraphEdge, WrGraphNode, WrGraphNodeContext };

package/types/ngwr-i18n-en.d.ts

@@ -1,16 +1,27 @@
 import { WrI18nCatalog } from 'ngwr/i18n';
 
 /**
- * Base English catalog for ngwr built-in component strings. Spread this
- * into your root catalog or pass it to `provideWrI18nStaticLoader`.
+ * Base English catalog for ngwr built-in component strings. Register it with
+ * `provideWrI18nBaseCatalogs` and keep only your own keys in the loader.
+ *
+ * Do not spread it into your own catalog. A spread is shallow, so any namespace
+ * you share with ngwr, e.g. `common`, `validation`, `table`, keeps only the keys
+ * of the side spread last, and the other side's keys stop resolving with nothing
+ * logged: ngwr's components fall back to their English defaults, and a `wrT`
+ * read of a lost key renders the raw key under the default missing handler. A
+ * base catalog is looked up key by key underneath yours, so both halves of a
+ * shared namespace resolve.
  *
  * @example
  * ```ts
+ * import { provideWrI18n, provideWrI18nBaseCatalogs, provideWrI18nStaticLoader } from 'ngwr/i18n';
  * import { wrEn } from 'ngwr/i18n/en';
  *
- * provideWrI18nStaticLoader({
- *   en: { ...wrEn, app: { title: 'My app' } },
- * });
+ * providers: [
+ *   provideWrI18n(),
+ *   provideWrI18nBaseCatalogs({ en: wrEn }),
+ *   provideWrI18nStaticLoader({ en: { app: { title: 'My app' } } }),
+ * ]
  * ```
  */
 declare const wrEn: WrI18nCatalog;

package/types/ngwr-i18n.d.ts

@@ -403,6 +403,15 @@ declare function provideWrI18n(options?: ProvideWrI18nOptions): EnvironmentProvi
 /**
  * Provide a static loader — catalogs already in memory.
  *
+ * A loader serves only the catalog you pass it, and ngwr registers none of its
+ * own. Pass only your own keys here and register ngwr's catalogs with
+ * {@link provideWrI18nBaseCatalogs} — not `{ ...wrRu, ...yours }`. A spread is
+ * shallow, so any namespace you share with ngwr, e.g. `common`, `validation`,
+ * `table`, keeps only the keys of the side spread last, and the other side's
+ * keys stop resolving with nothing logged: ngwr's components fall back to their
+ * English defaults, and a `wrT` read of a lost key renders the raw key under the
+ * default missing handler.
+ *
  * @param catalogs Root catalogs keyed by locale.
  * @param scopes Optional per-scope catalogs served to `registerScope(name)`.
  */
@@ -428,6 +437,10 @@ declare function provideWrI18nStaticLoader(catalogs: WrI18nStaticCatalogs, scope
  *
  * Pass only the locales you ship — the ones you leave out stay out of the
  * bundle. Your own keys always win; this is a floor, not an override.
+ *
+ * Use it instead of spreading `wrRu` into your own catalog, too: the lookup
+ * walks these key by key after the loader's catalog misses, so a namespace both
+ * define keeps both halves, where a shallow spread keeps only one.
  */
 declare function provideWrI18nBaseCatalogs(catalogs: WrI18nBaseCatalogs): Provider;
 /** Provide an HTTP loader — catalogs fetched from URLs. Requires `provideHttpClient`. */

package/types/ngwr-lightbox.d.ts

@@ -61,7 +61,22 @@ declare class WrLightbox {
     private readonly overlay;
     private readonly vcr;
     private readonly destroyRef;
+    private readonly injector;
     private readonly focusTrapFactory;
+    /**
+     * The reading direction the open viewer has to keep up with, resolved off the
+     * ENVIRONMENT injector rather than this component's — the same instance the
+     * CDK read when it stamped the overlay, since `createOverlayRef` takes
+     * `Directionality` from the `Overlay`'s injector and no node-level `[dir]` is
+     * in that chain. The viewer is appended to the overlay container on `<body>`,
+     * not into whatever region the thumbnail sits in, so reading the node
+     * injector would rewrite a correctly-stamped panel to an island's direction
+     * one pass after it opened rather than follow the application at all.
+     *
+     * `null` never happens in an app — `Directionality` is root-provided — but a
+     * bare `TestBed` should still get a viewer that opens.
+     */
+    private readonly dir;
     private focusTrap;
     private previouslyFocused;
     private overlayRef;

package/types/ngwr-mention.d.ts

@@ -60,8 +60,15 @@ declare class WrMention<T extends WrMentionItem = WrMentionItem> {
     readonly wrMentionSelected: _angular_core.OutputEmitterRef<WrMentionCommit<T>>;
     private readonly host;
     private readonly overlay;
+    /**
+     * Optional inject: `Directionality` is root-provided, so this is never null in
+     * an app — but a bare `TestBed` that provides nothing should still get a
+     * directive that works, and defaulting to LTR is the honest fallback.
+     */
+    private readonly dir;
     private readonly scrollStrategies;
     private readonly destroyRef;
+    private readonly injector;
     private readonly isBrowser;
     private overlayRef;
     private panelRef;

package/types/ngwr-overlay.d.ts

@@ -1,7 +1,8 @@
-import { ConnectedPosition, OverlayRef, OverlayContainer, Overlay } from '@angular/cdk/overlay';
-import { Observable } from 'rxjs';
+import { Directionality, Direction } from '@angular/cdk/bidi';
+import { OverlayRef, ConnectedPosition, OverlayContainer, Overlay } from '@angular/cdk/overlay';
 import * as i0 from '@angular/core';
-import { EnvironmentProviders, InjectionToken } from '@angular/core';
+import { Injector, EnvironmentProviders, InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
 
 /**
  * @license
@@ -28,6 +29,63 @@ import { EnvironmentProviders, InjectionToken } from '@angular/core';
  */
 declare function wrAppendOverlayClose(host: HTMLElement, className: string, label: string, onClose: () => void): HTMLButtonElement;
 
+/**
+ * @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
+ */
+
+/**
+ * Keep an OPEN overlay on the application's reading direction.
+ *
+ * The CDK reads the direction ONCE, as a string, when the overlay is created
+ * (`overlayConfig.direction ||= directionality.value`), writes it as the host's
+ * `dir` on attach, and never looks at it again — `updatePosition()` does not
+ * touch it and `setDirection()` is the only thing that does. So an application
+ * that flips direction while a panel is open mirrors the page and leaves the
+ * panel behind, still `ltr`, still resolving `start` to the left. This site's
+ * own LTR/RTL switch is the demonstration: it lives inside a `wr-dropdown`, and
+ * the `wr-segmented` it is built from reads `Directionality` live — so the thumb
+ * slides to the other slot while the pane around it still renders `ltr`, and
+ * parks under the wrong label.
+ *
+ * Call it once per `OverlayRef`, right after `overlay.create(...)`. The follower
+ * ends itself when that overlay detaches or is disposed, so a reopen — which is
+ * always a NEW ref in this library — needs a new call, and the returned teardown
+ * is only for stopping early.
+ *
+ * `onDirectionChange` is for the sites whose position LIST is itself
+ * direction-dependent (the four that pass their table through
+ * {@link wrMirrorOffsets}): it runs with the new direction already on the ref
+ * and before the overlay repositions, so the strategy is carrying the mirrored
+ * offsets by the time the CDK re-resolves them.
+ *
+ * SSR-safe: it touches no browser global of its own, and the CDK's position
+ * strategies no-op off the browser, so a flip on the server only rewrites the
+ * attribute.
+ *
+ * @param overlayRef The overlay to keep in step, freshly created.
+ * @param dir The `Directionality` the caller injected. `null` — an optional
+ *   inject with no provider, i.e. a bare `TestBed` — means there is nothing
+ *   ambient to follow and this does nothing at all.
+ * @param injector Owns the `valueSignal` watch; the caller's own is right.
+ * @param onDirectionChange Re-applies direction-dependent state, e.g.
+ *   `strategy.withPositions(wrMirrorOffsets(TABLE, direction === 'rtl'))`.
+ * @returns Stops following. Idempotent, and unnecessary in the normal case.
+ *
+ * @example
+ * ```ts
+ * this.overlayRef = this.overlay.create({ positionStrategy, ... });
+ * wrFollowDirection(this.overlayRef, this.dir, this.injector, direction =>
+ *   positionStrategy.withPositions(
+ *     wrMirrorOffsets(WR_POPCONFIRM_POSITIONS[this.position()], direction === 'rtl')
+ *   )
+ * );
+ * ```
+ */
+declare function wrFollowDirection(overlayRef: OverlayRef, dir: Directionality | null, injector: Injector, onDirectionChange?: (direction: Direction) => void): () => void;
+
 /**
  * @license
  *
@@ -302,5 +360,5 @@ declare const WR_OVERLAY: InjectionToken<Overlay>;
  */
 declare const WR_OVERLAY_CONTAINER: InjectionToken<OverlayContainer>;
 
-export { WR_OVERLAY, WR_OVERLAY_CONTAINER, WR_RESPONSIVE_OVERLAYS, WrOutsideClick, WrOverlayContainer, provideWrOverlay, provideWrResponsiveOverlays, wrAppendOverlayClose, wrMirrorOffsets, wrPresentAsSheet };
+export { WR_OVERLAY, WR_OVERLAY_CONTAINER, WR_RESPONSIVE_OVERLAYS, WrOutsideClick, WrOverlayContainer, provideWrOverlay, provideWrResponsiveOverlays, wrAppendOverlayClose, wrFollowDirection, wrMirrorOffsets, wrPresentAsSheet };
 export type { WrResponsiveOverlaysConfig };

package/types/ngwr-popconfirm.d.ts

@@ -40,6 +40,7 @@ declare class WrPopconfirm {
     private readonly outsideClick;
     private readonly vcr;
     private readonly scrollStrategies;
+    private readonly injector;
     private readonly destroyRef;
     /** @internal Public so the host bindings can read it. */
     readonly isOpen: _angular_core.WritableSignal<boolean>;