ngwr 11.1.0 → 12.0.0

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

@@ -0,0 +1,154 @@
+import { BaseHarnessFilters, ComponentHarness, 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-lightbox>` a harness query matches. */
+interface WrLightboxHarnessFilters extends BaseHarnessFilters {
+    /** Match the image's alt text — a string is an exact match, a RegExp is tested. */
+    readonly alt?: string | RegExp;
+    /** Match the caption shown under the full image. */
+    readonly caption?: string | RegExp;
+    /** Match only open (`true`) or only closed (`false`) lightboxes. */
+    readonly open?: 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
+ */
+
+/**
+ * Test harness for `<wr-lightbox>` — the thumbnail, and the full-size viewer it
+ * opens.
+ *
+ * The thumbnail is an element in your fixture and the viewer is a portal in the NGWR
+ * overlay container, so this is loaded from the normal fixture loader and reaches
+ * across for you — scoped by the id the trigger publishes as `aria-controls`, never
+ * by `.wr-lightbox-viewer`, which would answer with whichever lightbox opened first.
+ *
+ * **A closed lightbox has no viewer at all**, unlike the collapse or the speed dial:
+ * the overlay is created on open and disposed on close, so every viewer read here
+ * throws while it is shut rather than answering about a stale element.
+ *
+ * **`disablePreview` removes the button, not just its behaviour.** The thumbnail is
+ * then a bare `<img>` with nothing to click and nothing in the tab order, which is
+ * why {@link isInteractive} exists and why {@link open} explains itself rather than
+ * timing out on a missing element.
+ *
+ * @example
+ * ```ts
+ * const lightbox = await loader.getHarness(WrLightboxHarness.with({ alt: 'Mountain' }));
+ *
+ * await lightbox.open();
+ * expect(await lightbox.getFullSrc()).toBe('/photo.jpg');
+ *
+ * await lightbox.sendEscape();
+ * expect(await lightbox.isOpen()).toBe(false);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrLightboxHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrLightboxHarnessFilters): HarnessPredicate<WrLightboxHarness>;
+    private readonly thumb;
+    private readonly trigger;
+    /**
+     * Whether the viewer is open, from the host's own modifier.
+     *
+     * The class rather than the overlay, because it is the answer that holds for a
+     * harness you are HOLDING: the viewer is disposed on close, and a query for it
+     * cannot tell "shut" apart from "never opened".
+     */
+    isOpen(): Promise<boolean>;
+    /**
+     * Whether the thumbnail has settled — loaded OR failed.
+     *
+     * A failure counts on purpose: the loading state animates a shimmer and hides the
+     * image, so a broken `src` with no error path would shimmer for ever instead of
+     * falling back to its alt text. The two cases are deliberately not separated here,
+     * because the DOM does not separate them either.
+     */
+    isLoading(): Promise<boolean>;
+    /** The thumbnail's alt text — the same string the viewer takes its name from. */
+    getAlt(): Promise<string>;
+    /**
+     * What the THUMBNAIL is showing: `preview` when one was given, `src` otherwise.
+     *
+     * Worth its own method because the two images are different files by design — a
+     * grid of thumbnails should not pull full-size originals — and because the
+     * thumbnail never swaps to `src` later. Compare with {@link getFullSrc}.
+     */
+    getThumbSrc(): Promise<string>;
+    /** Whether the thumbnail can be clicked open at all (`disablePreview` off). */
+    isInteractive(): Promise<boolean>;
+    /** The trigger's accessible name — falls back to the alt text, then to the catalog. */
+    getOpenLabel(): Promise<string | null>;
+    /** Open the viewer. An already-open one is left alone; a non-interactive one throws. */
+    open(): Promise<void>;
+    /** Close the viewer through its ✕ button. An already-closed one is left alone. */
+    close(): Promise<void>;
+    /**
+     * Click the full image — which closes the viewer.
+     *
+     * It looks like decoration and is not: the image is styled `cursor: zoom-out`, and
+     * that is a promise. It is deliberately NOT in the tab order, since the ✕ button,
+     * Escape, the backdrop and a swipe all do the same thing and all reach a keyboard —
+     * so this is a mouse affordance, and the only way to assert it still works.
+     */
+    clickImage(): Promise<void>;
+    /**
+     * Press Escape.
+     *
+     * Sent to the viewer, though it would arrive from anywhere: the overlay is fed by
+     * the CDK's keyboard dispatcher, which keeps one document listener and routes to
+     * the top-most overlay.
+     */
+    sendEscape(): Promise<void>;
+    /** The full-size image's `src`. Throws while the viewer is closed. */
+    getFullSrc(): Promise<string>;
+    /** The caption under the full image, or `null` when there is none. Throws while closed. */
+    getCaption(): Promise<string | null>;
+    /** The name the viewer dialog announces — its alt text, or the catalog's fallback. */
+    getViewerLabel(): Promise<string | null>;
+    /** The ✕ button's accessible name. Throws while the viewer is closed. */
+    getCloseLabel(): Promise<string | null>;
+    /** Whether the viewer announces itself as a modal dialog. */
+    isModal(): Promise<boolean>;
+    /**
+     * Whether focus is inside the viewer, where the trap should be holding it.
+     *
+     * `role="dialog"` with `aria-modal` promises the page behind is out of reach, and a
+     * missing trap makes that a lie — Tab walks straight through the backdrop. Note
+     * that in a unit test the trap needs elements with a box to find anything tabbable,
+     * so a spec asserting this has to hand the DOM some dimensions first.
+     */
+    isFocusTrapped(): Promise<boolean>;
+    /**
+     * Whether the trigger's `aria-controls` names THIS lightbox's viewer, and nothing
+     * else on the page.
+     *
+     * The reference only exists while the viewer does — an id naming an element that is
+     * not in the document is not a pairing, it is a dangling reference — so this is
+     * `false` for a closed lightbox by construction. Counted across the document too,
+     * because two viewers answering to one id hand every reference to the first.
+     */
+    isViewerBound(): Promise<boolean>;
+    /** The caption without the open check — for filters, which must not throw. */
+    private readCaption;
+    /** The id the trigger currently points at, or `null` while the viewer is closed. */
+    private viewerId;
+    private requireViewer;
+    private viewerPart;
+}
+
+export { WrLightboxHarness };
+export type { WrLightboxHarnessFilters };

package/types/ngwr-lightbox.d.ts

@@ -50,6 +50,12 @@ declare class WrLightbox {
     readonly aspectRatio: _angular_core.InputSignal<string | number | null>;
     protected readonly open: _angular_core.WritableSignal<boolean>;
     protected readonly loaded: _angular_core.WritableSignal<boolean>;
+    /**
+     * Id the trigger's `aria-controls` points at while the viewer is open.
+     *
+     * @internal Public so the host bindings can read it.
+     */
+    protected readonly viewerId: string;
     protected readonly classes: _angular_core.Signal<string>;
     protected readonly panelTpl: _angular_core.Signal<TemplateRef<unknown>>;
     private readonly overlay;

package/types/ngwr-line-chart-testing.d.ts

@@ -0,0 +1,93 @@
+import { BaseHarnessFilters, ComponentHarness, 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-line-chart>` a harness query matches. */
+interface WrLineChartHarnessFilters extends BaseHarnessFilters {
+    /** Match the plot's accessible name. */
+    readonly ariaLabel?: string | RegExp;
+    /** Match a chart whose legend holds this series. */
+    readonly seriesLabel?: string | RegExp;
+}
+/** One row of the hover tooltip — a series and its value at the hovered index. */
+interface WrLineChartTooltipRow {
+    readonly label: string;
+    readonly value: 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
+ */
+
+/**
+ * Test harness for `<wr-line-chart>`.
+ *
+ * **The lines are paths and the paths are not assertable.** A `d` attribute is a
+ * rendering detail — it moves with the viewBox, the padding and the value range — so
+ * this harness counts the lines and reads everything TEXTUAL instead: the legend, the
+ * axis ticks, the x labels and the tooltip. Those are what a reader gets, and they
+ * are what breaks when the data wiring does.
+ *
+ * **The tooltip cannot be opened from a spec, and the reason is worth knowing.** It
+ * follows a `pointermove` over the plot, and the component turns the cursor's x into
+ * an index by measuring the plot's box — which jsdom reports as 0×0, so every
+ * synthetic move resolves to the same index or to none at all. There is deliberately
+ * no `hoverAt()`; {@link getTooltipRows} reads the tooltip when something else has
+ * opened it, which in practice means a browser-run harness.
+ *
+ * @example
+ * ```ts
+ * const chart = await loader.getHarness(WrLineChartHarness);
+ *
+ * expect(await chart.getSeriesLabels()).toEqual(['Revenue', 'Costs']);
+ * expect(await chart.getLineCount()).toBe(2);
+ * expect(await chart.getXLabels()).toEqual(['Jan', 'Feb', 'Mar']);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrLineChartHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrLineChartHarnessFilters): HarnessPredicate<WrLineChartHarness>;
+    /** The plot's accessible name — the only name the drawing has. */
+    getAccessibleName(): Promise<string | null>;
+    /** Whether the legend is rendered (`showLegend`, and at least one series). */
+    hasLegend(): Promise<boolean>;
+    /** The series names from the legend, in order. */
+    getSeriesLabels(): Promise<string[]>;
+    /**
+     * How many lines were drawn.
+     *
+     * Worth comparing with {@link getSeriesLabels}: the legend and the paths come from
+     * the same list, so a mismatch is a series that got filtered out of one of them.
+     */
+    getLineCount(): Promise<number>;
+    /** How many point dots were drawn across every series (`showDots`). */
+    getDotCount(): Promise<number>;
+    /** Whether the horizontal grid lines are drawn (`showGrid`). */
+    hasGrid(): Promise<boolean>;
+    /** The y-axis tick labels, top to bottom as drawn. */
+    getYTicks(): Promise<string[]>;
+    /** The x-axis labels under the plot, in order. */
+    getXLabels(): Promise<string[]>;
+    /** Whether the hover tooltip is showing. */
+    hasTooltip(): Promise<boolean>;
+    /** The tooltip's heading — the x label of the hovered point — or `null` while it is closed. */
+    getTooltipLabel(): Promise<string | null>;
+    /** The tooltip's rows, one per series, or `[]` while it is closed. */
+    getTooltipRows(): Promise<WrLineChartTooltipRow[]>;
+    /** The plot's height in pixels, as the component writes it inline. */
+    getPlotHeight(): Promise<number>;
+}
+
+export { WrLineChartHarness };
+export type { WrLineChartHarnessFilters, WrLineChartTooltipRow };

package/types/ngwr-line-chart.d.ts

@@ -55,7 +55,7 @@ declare class WrLineChart {
     protected readonly hoveredIndex: _angular_core.WritableSignal<number | null>;
     protected readonly resolvedSeries: _angular_core.Signal<{
         label: string;
-        data: number[];
+        data: (number | null)[];
         color: string;
     }[]>;
     protected readonly bounds: _angular_core.Signal<{
@@ -70,12 +70,29 @@ declare class WrLineChart {
     }[]>;
     protected readonly plotWidth: () => number;
     protected readonly plotHeight: () => number;
-    /** Get the SVG path for a series. */
+    /**
+     * The SVG path for a series — one subpath per unbroken run, so a hole in the data
+     * leaves a hole in the line rather than a straight segment across it.
+     */
     protected pathFor(series: {
-        data: readonly number[];
+        data: readonly (number | null)[];
     }): string;
     protected pointX(index: number): number;
     protected pointY(value: number): number;
+    /**
+     * A point's x as a percentage of the host's width. The x-label strip and the SVG share
+     * that width — the drawing stretches to it — so this is the same space the tooltip and
+     * the labels are placed in, at any size.
+     */
+    protected xPercent(index: number): number;
+    /**
+     * How wide an x label may be, as a percentage of the host's width: its own slot — half
+     * the distance to a neighbour on each side — cut back to what is left between its point
+     * and the end of the strip. Centring a label on its point says nothing about its WIDTH,
+     * and with no bound at all twelve month names printed over each other and the last one
+     * hung outside the chart. Past this the stylesheet ellipsises.
+     */
+    protected xMaxPercent(index: number): number;
     protected readonly hoverPoints: _angular_core.Signal<{
         label: string;
         value: number;

package/types/ngwr-markdown.d.ts

@@ -387,6 +387,17 @@ declare class WrMarkdownHighlight {
     private fill;
     /** `Map` iterates in insertion order, and `linesFor` re-inserts on read. */
     private evict;
+    /**
+     * The same bound, one dimension out. `request` re-inserts a bucket it already
+     * holds, so the outer map iterates least-recently-REQUESTED first — and the
+     * component's effect asks for every code block in the document it is showing,
+     * so a language that stops being requested is one nothing renders any more.
+     *
+     * Read is deliberately NOT a touch here, unlike {@link linesFor} for the inner
+     * map: with the effect re-asking for every block, request order already tracks
+     * what is rendered, and nothing has needed the finer signal.
+     */
+    private evictLanguage;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrMarkdownHighlight, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<WrMarkdownHighlight>;
 }

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

@@ -0,0 +1,280 @@
+import { BaseHarnessFilters, ComponentHarness, 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-marquee>` a harness query matches. */
+interface WrMarqueeHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the region's accessible name — the only thing telling two strips on one page
+     * apart. A string is an exact match, a RegExp is tested.
+     *
+     * Every marquee has one: with no `[ariaLabel]` and no catalog it is the literal
+     * `'Marquee'`, so this never matches on absence.
+     */
+    readonly ariaLabel?: string | RegExp;
+}
+/** Narrows which `.wr-marquee__item` a harness query matches. */
+interface WrMarqueeItemHarnessFilters extends BaseHarnessFilters {
+    /** Match what the entry announces — see `WrMarqueeItemHarness.getAccessibleName()`. */
+    readonly name?: string | RegExp;
+    /** Match only linked (`true`) or only plain (`false`) entries. */
+    readonly link?: boolean;
+}
+/** One linked entry of the strip, as it announces itself and as it navigates. */
+interface WrMarqueeLink {
+    /** The `href` exactly as the item declared it, unresolved. */
+    readonly href: string | null;
+    /**
+     * The link's accessible name. Never `null` in practice — an entry with nothing to call
+     * itself falls back to the catalog's `marquee.link`, because a bare "link" was what a
+     * screen reader used to announce for every unlabelled logo in the strip.
+     */
+    readonly name: 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 one entry of a `<wr-marquee>`.
+ *
+ * **Reach these through `WrMarqueeHarness.getItems()`, which scopes them to the first
+ * copy.** The strip duplicates its whole sequence to make the loop seamless, so asking
+ * the document loader for all of these returns one per entry per copy — at least twice
+ * everything, and a count assertion that quietly multiplies. The parent harness is the
+ * only place that knows which copy is the original.
+ *
+ * An entry is built from an image or from a projected template, and it may or may not be
+ * a link. That is the reason to ask a harness rather than the DOM: the same question —
+ * what does this announce, is it decoration — is answered from a different attribute in
+ * each of those shapes, and {@link getAccessibleName} and {@link isDecorative} pick the
+ * right one.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrMarqueeItemHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrMarqueeItemHarnessFilters): HarnessPredicate<WrMarqueeItemHarness>;
+    private readonly link;
+    private readonly image;
+    private readonly node;
+    /**
+     * What this entry announces, without the caller needing to know how it was built.
+     *
+     * A linked entry answers with the link's own name, which is the end of a four-step
+     * ladder — the item's `ariaLabel`, then its `title`, then an image's `alt`, then the
+     * catalog's `marquee.link`. An unlinked image answers with its `alt`, where `''` means
+     * the logo is decoration and announces nothing. Anything else answers with its text.
+     */
+    getAccessibleName(): Promise<string | null>;
+    /** Whether this entry became a link — `[items]` carries `href` per entry, optionally. */
+    isLink(): Promise<boolean>;
+    /** The `href` exactly as the entry declared it, unresolved, or `null` when it is not a link. */
+    getHref(): Promise<string | null>;
+    /**
+     * Whether the link opens in a new tab AND says so safely: `target="_blank"` with both
+     * `noreferrer` and `noopener` in `rel`.
+     *
+     * One question rather than two, because half of it is a reverse-tabnabbing hole that
+     * nothing visual would ever show. The library hard-codes the safe pair, so this is a
+     * regression check on the template rather than on the caller's data.
+     *
+     * Throws for an entry that is not a link, where a `false` would read as "it opens in
+     * this tab" — an answer about safety that is not true of anything.
+     */
+    opensInNewTab(): Promise<boolean>;
+    /**
+     * Whether this entry's content is kept out of the accessible tree, leaving whatever
+     * wraps it to do the announcing.
+     *
+     * The marker depends on how the entry was built, which is the whole reason to ask here:
+     * a projected template inside a named link carries `aria-hidden`, so the link's own name
+     * is not read twice, while an image says the same thing with `alt=""`. It describes the
+     * CONTENT — a decorative logo inside a link is still announced, by the link, and that
+     * name is {@link getAccessibleName}.
+     *
+     * Throws for an entry that rendered neither, which should not happen — every entry of
+     * `[items]` is one or the other.
+     */
+    isDecorative(): Promise<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
+ */
+
+/**
+ * Test harness for `<wr-marquee>`.
+ *
+ * **Almost everything worth asserting about a marquee is structural, not animated.** The
+ * strip duplicates its sequence so the loop has no seam, and only the first copy is left
+ * in the accessible tree — {@link getAnnouncedCopyCount} is the assertion that catches
+ * the regression that matters, because a duplicate leaking in makes a screen reader read
+ * the whole logo strip twice and changes nothing on screen. The other half is the naming
+ * ladder on linked entries, which is real logic with a real bug in its history: the
+ * fallback used to be the hard-coded English word "link".
+ *
+ * **Every list query is scoped to the first copy**, and that is the reason to use
+ * {@link getItems} rather than a raw `.wr-marquee__item` query, which returns at least
+ * twice as many elements as there are entries.
+ *
+ * Nothing about the motion is offered. The track's `translate3d` is written only when the
+ * measured sequence is wider than zero, so it never appears in a test at all, and in a
+ * browser it is one frame of a loop that is already stale by the time an assertion reads
+ * it. `[speed]` and `[direction]` reach the DOM in no form. Neither does the hover state:
+ * pausing flips a private signal with no class, attribute or property behind it, so a
+ * `hover()` here would fire events that provably change nothing readable. And the
+ * reduced-motion freeze is a CSS `!important` rule with no counterpart in TypeScript,
+ * which means the DOM is identical either way — see `getGap` for what a harness can
+ * honestly read off a stylesheet-driven component, and why it reads it where it does.
+ *
+ * @example
+ * ```ts
+ * const loader = TestbedHarnessEnvironment.loader(fixture);
+ * const strip = await loader.getHarness(WrMarqueeHarness);
+ *
+ * expect(await strip.getAnnouncedCopyCount()).toBe(1);
+ * expect(await strip.getItemCount()).toBe(logos.length);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrMarqueeHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrMarqueeHarnessFilters): HarnessPredicate<WrMarqueeHarness>;
+    private readonly copies;
+    /**
+     * The name the region announces.
+     *
+     * Pins the i18n ladder end to end: `'Marquee'` with no catalog loaded, the consumer's
+     * `[ariaLabel]` when one is given, the localized string under a catalog. A landmark
+     * with no name is an axe failure, so this is what keeps the `region` legitimate rather
+     * than a decoration a screen-reader user is invited to jump to and finds unnamed.
+     */
+    getAccessibleName(): Promise<string | null>;
+    /**
+     * The landmark role the strip claims.
+     *
+     * Static in the template and one attribute away from being dropped in a refactor, which
+     * is exactly why a consumer asserting their page's landmark structure should be able to
+     * see it from here.
+     */
+    getRole(): Promise<string | null>;
+    /**
+     * How many copies of the sequence are rendered.
+     *
+     * The seamless loop is built by repeating the whole list until it covers the container,
+     * so the count is decided by measurement — which means it stays at the floor of 2 in a
+     * test with no layout, whatever the container would really be. Assert `>= 2`; the
+     * growth needs a browser.
+     */
+    getCopyCount(): Promise<number>;
+    /**
+     * How many copies are left in the accessible tree. Must be exactly 1.
+     *
+     * The one assertion here that catches a silent regression: every copy after the first
+     * carries `aria-hidden="true"`, and losing that makes a screen reader read the whole
+     * strip once per copy while the page looks unchanged.
+     *
+     * Note the first copy carries the literal `aria-hidden="false"` rather than no
+     * attribute at all, so this compares against the string `'true'` — testing the
+     * attribute for presence would count nothing at all as announced.
+     */
+    getAnnouncedCopyCount(): Promise<number>;
+    /** The entries of the first copy, in order — one per entry of `[items]`. */
+    getItems(): Promise<WrMarqueeItemHarness[]>;
+    /**
+     * How many entries the strip drew, counting the first copy only.
+     *
+     * One per entry of `[items]` — the mapping a consumer's own data pipeline is really
+     * being tested for.
+     */
+    getItemCount(): Promise<number>;
+    /**
+     * The `alt` of each image in the first copy, in order.
+     *
+     * `null` in this list is the thing to look for: it means the attribute is MISSING, which
+     * is a serious axe violation and announces the file name. An empty string is the
+     * opposite — a deliberately decorative logo — and the template's `alt || ''` is what
+     * keeps the two apart. A method typed `string[]` would have had to flatten them.
+     */
+    getImageAlts(): Promise<(string | null)[]>;
+    /**
+     * Every linked entry of the first copy: where it goes and what it announces.
+     *
+     * The name is the interesting half. It walks a ladder ending in the catalog's
+     * `marquee.link`, so an unlabelled logo announces a localized word rather than nothing
+     * — real component logic rather than an echo of the input.
+     */
+    getLinks(): Promise<WrMarqueeLink[]>;
+    /**
+     * Whether the edge fades are on.
+     *
+     * The fades themselves are `::before` / `::after` gradients, which no unit environment
+     * can see — so the modifier class is the observable, and it is public API a consumer
+     * may be styling against in any case.
+     */
+    hasFade(): Promise<boolean>;
+    /**
+     * The fade colour as the component passed it through — a CSS value such as
+     * `'var(--wr-color-success)'`, not a resolved colour — or `null` when none was given.
+     *
+     * Worth asserting next to {@link hasFade}: a colour with no fade modifier renders
+     * nothing at all, which is a consumer mistake this pairing makes visible.
+     */
+    getFadeColor(): Promise<string | null>;
+    /**
+     * Whether entries scale up under the pointer.
+     *
+     * A `:hover` transform, so again the modifier is the only honest read — and it earns
+     * its place by doing more than the name suggests: it also changes the strip's vertical
+     * padding, so a lost class shifts the layout as well as the hover.
+     */
+    hasScaleOnHover(): Promise<boolean>;
+    /** The gap between entries in pixels — the seam width the stylesheet reads. */
+    getGap(): Promise<number>;
+    /**
+     * The entry height in pixels.
+     *
+     * It drives the image height AND the entry font size, so a binding that stops arriving
+     * collapses the whole strip rather than merely resizing it.
+     */
+    getItemHeight(): Promise<number>;
+    /**
+     * Read a custom property off the host's inline `style`, rather than through
+     * `getCssValue()`.
+     *
+     * Not a jsdom workaround — the opposite. The stylesheet declares its own
+     * `--wr-marquee-gap: 32px` and `--wr-marquee-height: 28px` on `.wr-marquee`, so a
+     * computed read in a real browser answers with the stylesheet's default when the host
+     * binding is the very thing that broke. The inline value is what the component wrote,
+     * and nothing else can forge it.
+     */
+    private hostStyle;
+    /**
+     * Parse a `<n>px` custom property, refusing anything that lost its unit.
+     *
+     * The refusal is the point. `[gap]` and `[itemHeight]` are numbers that the host binding
+     * turns into lengths, and the stylesheet uses them raw — a bare `32` is an invalid
+     * declaration, so the property falls back to the stylesheet default and the strip looks
+     * merely a little different. A `parseFloat` would report 32 either way and hide it.
+     */
+    private pixels;
+}
+
+export { WrMarqueeHarness, WrMarqueeItemHarness };
+export type { WrMarqueeHarnessFilters, WrMarqueeItemHarnessFilters, WrMarqueeLink };

package/types/ngwr-mention.d.ts

@@ -65,6 +65,12 @@ declare class WrMention<T extends WrMentionItem = WrMentionItem> {
     private readonly isBrowser;
     private overlayRef;
     private panelRef;
+    /**
+     * Where the caret sits INSIDE the field — its offset from the field's
+     * top-left corner, plus the height of the line it is on. Mutated in place by
+     * `open()`, never replaced: `caretAnchor()` closes over this object.
+     */
+    private readonly caretOffset;
     private state;
     private readonly activeIndex;
     private readonly filteredItems;
@@ -113,6 +119,27 @@ declare class WrMention<T extends WrMentionItem = WrMentionItem> {
     private activate;
     private filter;
     private setActive;
+    /**
+     * The overlay's anchor: the caret's line box, grown by the gap the panel
+     * keeps from the text, as a zero-WIDTH virtual origin in viewport
+     * coordinates. Inflating the rect rather than passing `offsetY` is what keeps
+     * `withPush` honest — CDK applies a position offset as a `transform` AFTER it
+     * has clamped, so a pushed panel would land the offset off the screen edge.
+     *
+     * Live getters, not a snapshot, and that is the whole of the scroll fix.
+     * `getCaretCoordinates` answers in viewport coordinates, which a
+     * `GlobalPositionStrategy` froze at the instant of the keystroke: the panel
+     * then stayed pinned to the screen while the page scrolled out from under it
+     * (150px of scroll, 150px of drift, ending up over unrelated content). CDK
+     * re-reads a virtual origin on every `apply()`, so pinning it to the FIELD's
+     * live rect is what turns `reposition()` into a real re-anchor.
+     *
+     * Only the caret's offset inside the field is captured up front. Measuring it
+     * runs the mirror-div pass in `caret.ts` — a full layout read, far too
+     * expensive to repeat per scroll event — and it cannot change without a
+     * keystroke, which re-enters `open()` anyway.
+     */
+    private caretAnchor;
     private open;
     private close;
     private commit;
@@ -123,6 +150,11 @@ declare class WrMention<T extends WrMentionItem = WrMentionItem> {
 /**
  * Overlay panel rendered by {@link WrMention}. Not intended for
  * direct use — the directive instantiates it via a ComponentPortal.
+ *
+ * @internal — the same tag its twin `WrPopconfirmPanel` already carried. It says
+ * the intent; it does not by itself keep the class out of the generated API
+ * tables, because `WrTableFilter` and `WrTableSort` are tagged AND documented —
+ * see `EXPORTED_BUT_INTERNAL` in `scripts/lib/extract-api.ts`.
  */
 declare class WrMentionPanel {
     readonly items: _angular_core.InputSignal<readonly WrMentionItem[]>;