ngwr 10.2.0 → 11.0.0

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

@@ -0,0 +1,359 @@
+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 `[wrMention]` field a harness query matches. */
+interface WrMentionHarnessFilters extends BaseHarnessFilters {
+    /** Match the field's current text. A string is an exact match, a RegExp is tested. */
+    readonly value?: string | RegExp;
+    /**
+     * Match the field's placeholder — usually the only thing telling two mention
+     * fields apart in a fixture, since the host is a plain `<textarea>` / `<input>`
+     * with no label of its own. A string is an exact match, a RegExp is tested.
+     */
+    readonly placeholder?: string | RegExp;
+    /** Match only fields currently offering suggestions (`true`), or only those not (`false`). */
+    readonly open?: boolean;
+}
+/** Narrows which suggestion inside a mention panel a harness query matches. */
+interface WrMentionOptionHarnessFilters extends BaseHarnessFilters {
+    /** Match the suggestion's label — a string is an exact match, a RegExp is tested. */
+    readonly text?: string | RegExp;
+    /** Match only the active suggestion (`true`), or only the ones the cursor is not on (`false`). */
+    readonly active?: 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 one suggestion inside a `[wrMention]` panel.
+ *
+ * Reach these through {@link WrMentionHarness.getOptions}, never off the document:
+ * the panel is a portal in the shared overlay container, so a bare query answers
+ * with whichever mention field opened first.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrMentionOptionHarness extends ComponentHarness {
+    /** One `<li role="option">` in the panel's listbox. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrMentionOptionHarnessFilters): HarnessPredicate<WrMentionOptionHarness>;
+    /** The suggestion's label — whatever `displayWith` returned for the item. */
+    getText(): Promise<string>;
+    /**
+     * Whether the cursor is on this suggestion.
+     *
+     * Read from `aria-selected` rather than from the `--active` modifier class. The
+     * two are set from the same index, so they agree — but the ARIA state is what a
+     * screen reader is told, and the class is only what the highlight is painted
+     * with.
+     */
+    isActive(): Promise<boolean>;
+    /**
+     * The suggestion's id — the value the field names in `aria-activedescendant`.
+     *
+     * The only link between the two DOM trees: the panel is in the overlay
+     * container, not inside the field, so this id is how the reference reaches it
+     * at all.
+     */
+    getId(): Promise<string | null>;
+    /**
+     * Pick this suggestion with the mouse.
+     *
+     * Needs no layout, so it works here: the panel commits on `mousedown` —
+     * deliberately, so the field never loses focus and the caret stays put — and
+     * the CDK's no-arg click dispatches `mousedown` at the head of its sequence
+     * without any hit test.
+     */
+    click(): Promise<void>;
+    /**
+     * Move the pointer onto this suggestion, which makes it the active one.
+     *
+     * Hover and the arrow keys drive the same single cursor, so a spec can assert
+     * the mouse path through {@link WrMentionHarness.getActiveOptionLabel} exactly
+     * as it does the keyboard one.
+     */
+    hover(): Promise<void>;
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/**
+ * Test harness for `[wrMention]` — the field, and the suggestion panel it opens
+ * at the caret.
+ *
+ * The harness matches the FIELD, because that is the only part of a mention in the
+ * fixture: the panel is a `ComponentPortal` in the shared overlay container, a
+ * sibling of the whole app. Suggestions are read through the document root, scoped
+ * by the id the field publishes as `aria-controls` — which is what keeps two
+ * mention fields on one page from answering with each other's suggestions.
+ *
+ * **The field is not a combobox, and it has no `aria-expanded`.** Both are
+ * deliberate (the source spells out why: it holds prose, `role="combobox"` is
+ * disallowed on `<textarea>` and would drop `aria-multiline`, and `aria-expanded`
+ * is not a supported state of `role="textbox"`), and both shape this harness.
+ * `aria-controls` is STATIC — it names the listbox even while there is no listbox —
+ * so {@link isOpen} asks whether the listbox EXISTS instead of reading a state
+ * flag, and "a list appeared" reaches a screen reader through the live region that
+ * {@link getStatusMessage} reads.
+ *
+ * **The panel's POSITION is not testable in jsdom, so nothing here reports it.**
+ * `caret.ts` places the panel by measuring a mirror `<div>` with
+ * `getBoundingClientRect`, and jsdom has no layout: every rect is zeros, so the
+ * measurement collapses to the origin. The overlay still lands on finite numbers —
+ * `line-height` computes to `normal` there, so `caret.ts` falls back to
+ * `font-size * 1.2` and the pane is offset by that alone (a measured
+ * `margin-top: 23.2px`, `margin-left: 0px` on a default fixture) — which is
+ * precisely the problem: every one of them is an artefact of the environment
+ * rather than a fact about the component. Assert placement in a real browser.
+ *
+ * @example
+ * ```ts
+ * const mention = await loader.getHarness(WrMentionHarness);
+ *
+ * await mention.type('hey @al');
+ * expect(await mention.getOptionLabels()).toEqual(['Alan Turing', 'Linus Torvalds']);
+ *
+ * await mention.commit();
+ * expect(await mention.getValue()).toBe('hey @Alan Turing ');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrMentionHarness extends ComponentHarness {
+    /** The directive's host. Both tags, since the directive drives either one. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrMentionHarnessFilters): HarnessPredicate<WrMentionHarness>;
+    /** The field's whole text, mention fragments and prose alike. */
+    getValue(): Promise<string>;
+    /** The field's placeholder, or `''` when it has none. */
+    getPlaceholder(): Promise<string>;
+    /**
+     * Type into the field one keystroke at a time, APPENDING to whatever is there.
+     *
+     * The realistic path, and the one that exercises detection the way a person
+     * does: the directive re-reads the text before the caret on every `input`, so
+     * `type('hey @al')` opens the panel on the `@` and then narrows it twice.
+     *
+     * Focuses the field, which BLURS whatever was focused before — and a blurred
+     * mention field closes its own panel. Use {@link setValue} when a spec needs two
+     * fields suggesting at the same time.
+     */
+    type(text: string): Promise<void>;
+    /**
+     * Replace the field's whole text and let the directive detect once.
+     *
+     * The `input` event is dispatched by hand rather than through keystrokes so the
+     * field is never focused — which is the only way to get two mention panels open
+     * at once, since focusing one field blurs the other and blur closes its panel.
+     * The caret lands at the end of the new text, where detection looks.
+     */
+    setValue(text: string): Promise<void>;
+    /** Empty the field. The panel goes with it — there is no trigger char left to detect. */
+    clear(): Promise<void>;
+    /**
+     * Click the field.
+     *
+     * Re-opens the suggestions when the caret is still sitting inside a mention —
+     * the directive re-detects on click, which is how a user who pressed Escape (or
+     * clicked away and back) gets the panel again without retyping. Needs no layout:
+     * the CDK dispatches the event on the element rather than hit-testing a point.
+     */
+    click(): Promise<void>;
+    /**
+     * Whether the panel is offering suggestions.
+     *
+     * Asks whether this field's listbox exists, because the field publishes no
+     * open/closed state to read: `aria-expanded` is not a supported state of
+     * `role="textbox"` (axe rates it a critical violation), and `aria-controls` is
+     * static here, so its presence says nothing.
+     */
+    isOpen(): Promise<boolean>;
+    /**
+     * The field's `aria-autocomplete` — `'list'`, permanently.
+     *
+     * A capability, not a state: ARIA says authors should not toggle it to signal
+     * that suggestions are showing, and being static is what makes the feature
+     * discoverable on focus, before a trigger char is ever typed. {@link isOpen}
+     * answers the state.
+     */
+    getAutocomplete(): Promise<string | null>;
+    /**
+     * The role the field PROMISES its popup will announce, from `aria-haspopup` —
+     * `'listbox'`. Required alongside `aria-autocomplete="list"`, and it has to name
+     * the popup's real role, which {@link getListboxRole} reads back off the panel.
+     */
+    getPopupRole(): Promise<string | null>;
+    /** The role the open panel announces — `'listbox'`. Throws while the panel is closed. */
+    getListboxRole(): Promise<string | null>;
+    /**
+     * The panel's accessible name.
+     *
+     * ARIA requires a `role="listbox"` to have one, and a consumer never renders the
+     * panel themselves — so the directive supplies it from the i18n catalog
+     * (`mention.listbox`).
+     */
+    getListboxLabel(): Promise<string | null>;
+    /**
+     * The suggestions on offer, in DOM order.
+     *
+     * The whole list a user can reach, not a window onto a longer one: the directive
+     * slices the matches at `maxResults` (8 by default) before rendering, which is
+     * why this panel needs no virtualisation.
+     *
+     * Throws while the panel is closed — the options do not exist anywhere until the
+     * portal is attached, and an empty array reads like a panel that rendered
+     * nothing.
+     */
+    getOptions(filters?: WrMentionOptionHarnessFilters): Promise<WrMentionOptionHarness[]>;
+    /** The labels of the suggestions on offer, in DOM order. */
+    getOptionLabels(): Promise<string[]>;
+    /**
+     * The id the field names in `aria-activedescendant`, or `null` when it names
+     * nothing.
+     *
+     * The strict half of the field's two references. `aria-controls` is allowed to
+     * dangle (see {@link isOpen}); this one is not — naming an element that is not
+     * in the document is an author error no browser reports, it simply stops
+     * announcing options. So `null` is the CORRECT answer while the panel is closed,
+     * and worth asserting there.
+     */
+    getActiveOptionId(): Promise<string | null>;
+    /**
+     * The label a screen reader announces as the active suggestion.
+     *
+     * Resolved through `aria-activedescendant` the way an assistive technology
+     * would, rather than by hunting for the active class — which is why it throws on
+     * a reference that resolves to nothing instead of quietly reporting what the
+     * class says.
+     */
+    getActiveOptionLabel(): Promise<string>;
+    /**
+     * Where the active suggestion sits in {@link getOptions}, 0-based.
+     *
+     * Matched by id rather than counted by class, so the answer is the one
+     * `aria-activedescendant` actually points at.
+     */
+    getActiveOptionIndex(): Promise<number>;
+    /**
+     * Move the cursor down one suggestion, wrapping past the last back to the first.
+     *
+     * ArrowDown — and `aria-activedescendant` is the whole navigation model here,
+     * because the options are never focused: focus stays in the field so the user can
+     * keep typing the query.
+     *
+     * Throws while the panel is closed, where ArrowDown belongs to the field.
+     */
+    nextOption(): Promise<void>;
+    /** Move the cursor up one suggestion, wrapping past the first round to the last. */
+    previousOption(): Promise<void>;
+    /**
+     * Insert the active suggestion with Enter.
+     *
+     * The trigger char and the query are replaced by `valueWith(item, trigger)`
+     * (`@Label` by default) plus a trailing space, the caret lands after that space,
+     * the panel closes and `(wrMentionSelected)` fires with the item, the trigger
+     * char and the query.
+     *
+     * Throws while the panel is closed — Enter is the field's own key there (a
+     * newline in a `<textarea>`), and swallowing it would be the bug.
+     */
+    commit(): Promise<void>;
+    /**
+     * Insert the active suggestion with Tab instead.
+     *
+     * The same commit: the directive takes Tab as a second confirm key and
+     * `preventDefault`s it, so focus stays in the field rather than leaving for the
+     * next control.
+     */
+    commitWithTab(): Promise<void>;
+    /**
+     * Pick the first suggestion matching the filters, with the mouse.
+     *
+     * Opens nothing by itself — type a trigger char first. Names what the panel does
+     * offer when nothing matches, since a silent no-op here surfaces as an
+     * unexplained unchanged field further down the spec.
+     */
+    pick(filters: WrMentionOptionHarnessFilters): Promise<void>;
+    /**
+     * Dismiss the panel with Escape, leaving the typed text — trigger char and
+     * query included — exactly as it is. A closed panel is left alone.
+     *
+     * Sends the WHOLE keystroke, keydown and keyup, as a real Escape is. That
+     * matters here: the caret has not moved, so a keyup the directive re-detected on
+     * would reopen the panel this just closed, and a harness that dispatched only
+     * the keydown would report a dismissal the user never got.
+     */
+    dismiss(): Promise<void>;
+    /**
+     * Blur the field and wait for the panel to go.
+     *
+     * The close is deferred by 120ms so a `mousedown` on a suggestion lands first,
+     * and that is a real `setTimeout`: under zoneless change detection nothing
+     * flushes it for us, so this waits out REAL time. A spec on fake timers should
+     * drive its own clock and read {@link isOpen} instead of calling this.
+     */
+    blur(timeout?: number): Promise<void>;
+    /**
+     * What the live region currently says.
+     *
+     * This is the announcement channel the field has INSTEAD of ARIA state, and
+     * three things reach a screen reader only through it: how many suggestions
+     * appeared, that NOTHING matched — the panel closes in that case, so there is no
+     * DOM left to inspect and no state on the field to read — and what was inserted
+     * on commit.
+     *
+     * Throws when more than one mention field is mounted. The region is parked on
+     * `<body>` rather than in the panel (which is disposed on every keystroke that
+     * leaves a mention, and a live region has to pre-exist its own text to be
+     * announced at all), and it carries no id tying it to a field — so with two
+     * fields around, the harness genuinely cannot tell which region is this one's.
+     * Answering with whichever came first would be worse than refusing: assert
+     * announcements in a fixture holding a single mention field.
+     */
+    getStatusMessage(): Promise<string>;
+    /** Move keyboard focus to the field. Focusing alone opens nothing — the panel needs a trigger char. */
+    focus(): Promise<void>;
+    /** Whether the field holds keyboard focus. It keeps it while the panel is open, by design. */
+    isFocused(): Promise<boolean>;
+    /**
+     * A loader scoped to THIS field's listbox.
+     *
+     * Scoped by the id the field publishes as `aria-controls`, never by
+     * `.wr-mention-panel`: the overlay container is shared by every mention on the
+     * page, so a class query would answer with whichever field opened first.
+     */
+    private listboxLoader;
+    /** This field's listbox in the overlay. Throws when the panel is closed. */
+    private listbox;
+    /** This field's listbox, or `null` when the panel is closed. */
+    private listboxOrNull;
+    /** The id the field names in `aria-controls`, which its listbox carries. */
+    private listboxId;
+    /** The element `aria-activedescendant` points at, or a targeted failure. */
+    private activeOption;
+    /** The active option's id, or a targeted failure. */
+    private requireActiveOptionId;
+    /** Refuse a keystroke that would mean something else entirely with the panel closed. */
+    private requireOpen;
+}
+
+export { WrMentionHarness, WrMentionOptionHarness };
+export type { WrMentionHarnessFilters, WrMentionOptionHarnessFilters };

package/types/ngwr-meta.d.ts

@@ -54,8 +54,10 @@ interface WrMetaHandle {
  * Layers merge via shallow merge for scalars and a one-level deep merge
  * for `og` / `twitter` groups.
  *
- * The resolved metadata is applied diff-style — only changed tags are
- * touched in the DOM, so reads of `document.head` stay cheap.
+ * The title and the canonical link are diffed against the last applied
+ * snapshot and only rewritten when they actually change; the `<meta>` tags
+ * are re-resolved by selector on every apply, so an existing tag is updated
+ * in place rather than duplicated.
  *
  * @example
  * ```ts

package/types/ngwr-meter-group.d.ts

@@ -43,12 +43,22 @@ declare class WrMeterGroup {
     readonly max: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Show the labelled legend under the bar. @default true */
     readonly showLegend: _angular_core.InputSignalWithTransform<boolean, any>;
-    /** Show each segment's percent value in the legend. @default true */
+    /** Show each segment's value in the legend, next to its label. @default true */
     readonly showValues: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * A segment's contribution, floored at `0` and with anything non-finite read
+     * as `0`. One `NaN` used to poison the whole bar: the sum is `NaN` as soon as
+     * one value is, so the total fell back to `1` and every OTHER segment was
+     * asked for a width of `value * 100`%, while `aria-valuenow` announced `NaN`.
+     */
+    private static amount;
     protected readonly resolvedMax: _angular_core.Signal<number>;
     /**
      * Sum of the segments, for `aria-valuenow`. `role="progressbar"` without it
      * announces no value at all, so the bar was invisible to assistive tech.
+     *
+     * Capped at the total, because segments summing past an explicit `max` used
+     * to announce a value outside the range they were announced against.
      */
     protected readonly totalValue: _angular_core.Signal<number>;
     protected readonly slices: _angular_core.Signal<{

package/types/ngwr-overlay.d.ts

@@ -1,4 +1,4 @@
-import { OverlayRef, OverlayContainer, Overlay } from '@angular/cdk/overlay';
+import { ConnectedPosition, OverlayRef, OverlayContainer, Overlay } from '@angular/cdk/overlay';
 import { Observable } from 'rxjs';
 import * as i0 from '@angular/core';
 import { EnvironmentProviders, InjectionToken } from '@angular/core';
@@ -28,6 +28,37 @@ 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
+ */
+
+/**
+ * Mirror the horizontal offsets of a connected-position list for RTL.
+ *
+ * The CDK mirrors `originX` / `overlayX` under `dir="rtl"` — a `start` anchor
+ * resolves to the origin's right edge — but it does NOT mirror `offsetX`, which
+ * it adds to the final PHYSICAL x (`_getOffset` returns `position.offsetX`
+ * verbatim). So a position that meant "sit to the inline-start of the trigger,
+ * 8px clear of it" keeps its `-8` under RTL, where the panel is now on the
+ * right: the gap becomes an 8px OVERLAP, and the panel sits on top of the thing
+ * it is describing.
+ *
+ * Nothing in the CDK will do this for us, and the amount is per position, so
+ * every ngwr overlay that offsets along the inline axis passes its list through
+ * here. `offsetY` is untouched: the block axis does not flip.
+ *
+ * @example
+ * ```ts
+ * const dir = inject(Directionality, { optional: true });
+ *
+ * strategy.withPositions(wrMirrorOffsets(WR_POPOVER_POSITIONS[position], dir?.value === 'rtl'));
+ * ```
+ */
+declare function wrMirrorOffsets(positions: readonly ConnectedPosition[], isRtl: boolean): ConnectedPosition[];
+
 /**
  * @license
  *
@@ -253,4 +284,4 @@ 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, wrPresentAsSheet };
+export { WR_OVERLAY, WR_OVERLAY_CONTAINER, WR_RESPONSIVE_OVERLAYS, WrOutsideClick, WrOverlayContainer, provideWrOverlay, provideWrResponsiveOverlays, wrAppendOverlayClose, wrMirrorOffsets, wrPresentAsSheet };