ngwr 11.1.0 → 12.0.0

package/types/ngwr-shiny-text-testing.d.ts

@@ -0,0 +1,165 @@
+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
+ */
+
+/**
+ * Which way the bright stripe travels. Mirrors the component's `direction` input, which
+ * declares the union inline and exports no name for it.
+ */
+type WrShinyTextSweepDirection = 'left' | 'right';
+/** Narrows which `<wr-shiny-text>` a harness query matches. */
+interface WrShinyTextHarnessFilters extends BaseHarnessFilters {
+    /** Match the rendered text — a string is an exact match, a RegExp is tested. */
+    readonly text?: string | RegExp;
+    /**
+     * Match only the stopped (`true`) or only the running (`false`) instances. Named for the
+     * DOM contract rather than for the input: `[disabled]` writes `wr-shiny-text--paused`.
+     */
+    readonly paused?: boolean;
+    /** Match the sweep direction — `'left'` is the absence of the reverse modifier. */
+    readonly direction?: WrShinyTextSweepDirection;
+}
+
+/**
+ * @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-shiny-text>`.
+ *
+ * **The duration is the assertion that matters.** The pause between sweeps is not
+ * `animation-delay` and not a second animation — it is folded INTO `animation-duration`,
+ * because the keyframe finishes at 50% and holds there. So `[speed]="2"` with
+ * `[delay]="3"` has to read 5 seconds, and anyone reimplementing the pause the obvious
+ * way passes every other check here and fails {@link getCycleDurationSeconds}.
+ *
+ * **The stripe is five stops and only one of them is the shine.** The base colour fills
+ * 0%, 35%, 65% and 100%; the highlight sits alone at 50%. {@link getBaseColor} and
+ * {@link getShineColor} are offered as a pair because swapping the two inputs is
+ * otherwise undetectable — the gradient stays well-formed, the angle is unchanged, and
+ * the text simply stops shimmering.
+ *
+ * **Both gradient reads come off the inline `style` attribute**, not through computed
+ * style. Unset colours fall through to the literal `var(--wr-shiny-text-base)` /
+ * `var(--wr-shiny-text-shine)` tokens, which is exactly what makes the dark-theme
+ * override work — and a computed read resolves those tokens in a real browser while
+ * handing them back verbatim in a unit test. Reading what the component wrote gives the
+ * same answer in both places.
+ *
+ * The colours still pass through the CSSOM on their way back out, and it has its own
+ * spelling: a hex literal is re-serialised, so `[color]="'#444'"` reads
+ * `rgb(68, 68, 68)`. Functional notations and `var()` tokens survive untouched. Assert
+ * the form the CSSOM returns, not the one the template passed in.
+ *
+ * There is no inner element to query: the template is the bare interpolation, so the text
+ * is a node on the host. A locator copied from the gradient-text harness finds nothing.
+ *
+ * **What the harness deliberately does not offer**, and why. There is no `isAnimating()`
+ * / `getBackgroundPosition()`: the sweep is a stylesheet keyframe over
+ * `background-position`, and a unit test neither loads the sheet nor runs the animation.
+ * There is no `getAnimationName()` / `getIterationCount()` / `getPlayState()`: every
+ * animation property except the duration lives in the stylesheet, so those reads answer
+ * the same empty string for a working component and a deleted one. {@link isPaused} and
+ * {@link pausesOnHover} claim the CLASSES and not the pauses — `:hover` is a selector and
+ * `animation-play-state` is a stylesheet rule, so what they honestly pin is that the
+ * input arrived. There is no `respectsReducedMotion()`: the handling is a `@media` block
+ * with no TypeScript counterpart. And there is nothing reporting the painted text colour,
+ * because `-webkit-text-fill-color: transparent` is a stylesheet declaration and a read
+ * would report the inherited colour as if the text were solid.
+ *
+ * The `[wrShimmer]` directive shipped from the same entry point has no harness: it adds
+ * one static class and nothing else, so a harness could only restate its own selector.
+ *
+ * @example
+ * ```ts
+ * const shiny = await loader.getHarness(WrShinyTextHarness);
+ *
+ * expect(await shiny.getCycleDurationSeconds()).toBe(5);
+ * expect(await shiny.getShineColor()).toBe('var(--wr-shiny-text-shine)');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrShinyTextHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrShinyTextHarnessFilters): HarnessPredicate<WrShinyTextHarness>;
+    /** The rendered text, trimmed. It is a text node on the host — there is no inner span. */
+    getText(): Promise<string>;
+    /**
+     * The whole stripe gradient the component computed, as written.
+     *
+     * Unresolved on purpose. With no `[color]` / `[shineColor]` given this string contains
+     * the theme's own custom-property tokens rather than colours, and that is the working
+     * state, not a gap — resolving them would need the stylesheet, and the resolved answer
+     * would differ between a unit test and a browser.
+     */
+    getGradient(): Promise<string>;
+    /**
+     * The gradient's angle in degrees, from `[spread]`.
+     *
+     * The only observable effect that input has, `numAttr` coercion included. Note the name
+     * is inherited vocabulary and describes the ANGLE, not the width of the bright stripe:
+     * the stop positions are hard-coded, so no input narrows the shine.
+     */
+    getSpreadDegrees(): Promise<number>;
+    /**
+     * The colour outside the bright stripe — the 0% stop.
+     *
+     * The same colour fills 35%, 65% and 100%; only the 50% stop differs. Assert it next to
+     * {@link getShineColor}: a `[color]` that lands in the shine slot instead leaves a
+     * perfectly valid gradient that no longer shimmers.
+     */
+    getBaseColor(): Promise<string>;
+    /** The highlight colour — the lone 50% stop the stripe is made of. */
+    getShineColor(): Promise<string>;
+    /**
+     * One full cycle in seconds — the sweep AND the pause after it.
+     *
+     * `[delay]` is not `animation-delay` and not a second animation: the keyframe reaches
+     * its end at 50% and holds, so the wait is bought by making the animation twice as long.
+     * That is why this reads `speed + delay` and why the method is named for the cycle
+     * rather than for the sweep.
+     *
+     * Read from the inline declaration rather than from computed style, so a missing binding
+     * is reported as missing instead of being answered from the stylesheet.
+     */
+    getCycleDurationSeconds(): Promise<number>;
+    /**
+     * Whether the animation is stopped (`disabled`).
+     *
+     * Three names for one thing, which is why this method exists rather than a spec reading
+     * the class: the input is `disabled`, its JSDoc says "pause", and the DOM contract is
+     * `wr-shiny-text--paused`. Only the last of those is public API.
+     */
+    isPaused(): Promise<boolean>;
+    /** Whether the opt-in reached the class the `:hover` rule needs. */
+    pausesOnHover(): Promise<boolean>;
+    /**
+     * Whether the stripe bounces instead of restarting (`yoyo`).
+     *
+     * Defaults to `false` here — the opposite of the same-named input on `wr-gradient-text`,
+     * which is worth pinning in a spec that uses both. Together with {@link getDirection}
+     * this is the whole four-way matrix the stylesheet derives `animation-direction` from.
+     */
+    isYoyo(): Promise<boolean>;
+    /** Which way the stripe travels — `'left'` is the absence of the reverse modifier. */
+    getDirection(): Promise<WrShinyTextSweepDirection>;
+    /** The five stops of the stripe, positions attached, in gradient order. */
+    private gradientStops;
+    /** The gradient's arguments — the angle first, then the stops. */
+    private gradientArguments;
+    /** One of the host's two inline declarations, or a failure that says which one is missing. */
+    private require;
+}
+
+export { WrShinyTextHarness };
+export type { WrShinyTextHarnessFilters, WrShinyTextSweepDirection };

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

@@ -52,8 +52,10 @@ declare class WrShinyText {
  * Gradient sweep over text. Applies a `background-clip: text` gradient
  * with a moving highlight — gives any text a subtle shimmer.
  *
- * The directive only adds the `wr-shimmer` host class. Pair with the
- * styles in `ngwr/animations` (which include the `wr-shimmer` keyframes).
+ * The directive only adds the `wr-shimmer` host class. Pair with the styles
+ * in `ngwr/shiny-text` (`@use 'ngwr/shiny-text'`), which carry the
+ * `.wr-shimmer` rule and its keyframes; the umbrella `@use 'ngwr'` forwards
+ * the same sheet.
  *
  * @example
  * ```html

package/types/ngwr-sidebar.d.ts

@@ -75,17 +75,26 @@ declare class WrSidebar {
     private readonly uid;
     private readonly router;
     private readonly currentUrl;
-    /** Last URL we auto-expanded — prevents re-opening a group the user collapsed. */
+    /**
+     * Last URL we resolved to a group — prevents re-opening one the user collapsed.
+     * A URL no entry claims is deliberately NOT recorded: see the effect below.
+     */
     private lastAutoUrl;
     constructor();
     protected isOpen(title: string): boolean;
     /**
      * Stable id for the group body, referenced by the toggle's `aria-controls`.
-     * Scoped to this sidebar and stripped of anything that is not id-safe: a title
-     * like `Data & charts` used to produce `wr-sidebar-group-data-&-charts`, which
-     * no selector can address.
+     *
+     * Keyed by POSITION, not by the title. Slugging the title kept the id readable
+     * but was not injective: it lowercases and collapses every non-`[a-z0-9]` run,
+     * so `Data & charts` and `Data / charts` produced the same string, and a title
+     * with no ASCII alphanumerics at all — `Компоненты`, `数据` — produced the empty
+     * one. A whole Russian or Chinese sidebar therefore emitted N identical ids and
+     * every toggle's `aria-controls` resolved to the FIRST group's body. The toggle
+     * and its body read `$index` from the same `@for` iteration, so the two always
+     * name each other — reordering `entries` renumbers both together.
      */
-    protected groupBodyId(title: string): string;
+    protected groupBodyId(index: number): string;
     protected toggleGroup(title: string): void;
     protected asItem(entry: WrSidebarEntry): WrSidebarItem;
     protected asGroup(entry: WrSidebarEntry): WrSidebarGroup;

package/types/ngwr-slider.d.ts

@@ -69,6 +69,63 @@ declare class WrSlider implements FormValueControl<WrSliderValue> {
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
     /** Render the current value below the track. @default true */
     readonly showLabel: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Accessible name of the thumb — the single one, or the LOWER one in range
+     * mode. Falls back to `slider.label` / `slider.lower`.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /** Accessible name of the upper thumb in range mode. Falls back to `slider.upper`. */
+    readonly upperLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * A thumb projects no text, so these ARE the accessible names — and they were
+     * hard-coded English with no key behind them, so every slider on a page
+     * announced the same untranslated "Value" whatever it controlled.
+     *
+     * Range mode reads `ariaLabel` as the LOWER end rather than as the whole
+     * control: a name given once must land on something, and naming both thumbs
+     * the same thing would read two different values under one name.
+     */
+    private readonly singleLabel;
+    private readonly lowerLabel;
+    protected readonly resolvedUpperLabel: _angular_core.Signal<string>;
+    protected readonly resolvedLowLabel: _angular_core.Signal<string>;
+    private readonly field;
+    /**
+     * Id the surrounding `<wr-form-field>`'s `<label for>` points at, put on the
+     * single thumb — the LOWER one in range mode, the same end `ariaLabel` names.
+     *
+     * The field renders its label before it can see what was projected into it, so
+     * the id travels the other way and the control adopts it, exactly as
+     * `[wrInput]` does. Without this the `for` named an element that was nowhere
+     * in the document: clicking the label did nothing, and the field's own text
+     * reached the thumb through no path at all.
+     *
+     * It lands on the THUMB rather than on the host because only a labelable
+     * element can be a label's target, and `<wr-slider>` is not one — a `for`
+     * pointing at the host would resolve and still name nothing. The thumb is a
+     * real `<button>`, so it is.
+     *
+     * What this does NOT change is the thumb's name: an `aria-label` outranks a
+     * `<label>` in the accname order, and the thumb keeps its own because the
+     * field cannot promise it has one to give — `<wr-form-field>` renders a label
+     * only when `label` is set, and a slider that traded a generic name for no
+     * name would be the worse bug. Set `[ariaLabel]` to the field's label where
+     * the two should read alike.
+     */
+    protected readonly thumbId: _angular_core.Signal<string | null>;
+    /**
+     * The field's error message, wired to the thumb the same way `wrInput` wires it
+     * to its native element.
+     *
+     * Without this the messages `<wr-form-field>` renders are visible and nothing
+     * else: a screen reader on the thumb never learns the field is invalid, nor
+     * what the message says. `aria-invalid` is keyed on the message EXISTING rather
+     * than on `errorKeys()`, because the field only publishes an id once it is
+     * showing something — announcing "invalid" while pointing at nothing is worse
+     * than staying quiet.
+     */
+    protected readonly describedBy: _angular_core.Signal<string | null>;
+    protected readonly ariaInvalid: _angular_core.Signal<"true" | null>;
     /**
      * Current value. Bound by `[formField]`, or two-way via `[(value)]`. Shape
      * follows `range`: a plain `number`, or `[low, high]` in range mode.
@@ -77,7 +134,22 @@ declare class WrSlider implements FormValueControl<WrSliderValue> {
     /** Emitted on blur so a bound field can mark itself touched. */
     readonly touch: _angular_core.OutputEmitterRef<void>;
     protected readonly low: _angular_core.WritableSignal<number>;
+    /**
+     * The high thumb's cell. Its literal default stands in for `maxValue()`,
+     * which cannot be read at field-initialisation time — see `highSeeded` and
+     * the constructor effect.
+     */
     protected readonly high: _angular_core.WritableSignal<number>;
+    /**
+     * Whether `high` has ever been told a real value by the model.
+     *
+     * `<wr-slider range [min]="200" [max]="300" />` binds no value, so the model
+     * holds its own scalar default and the tuple branch below never runs: `high`
+     * kept the literal 100, which is not inside every `[min, max]`. The thumb
+     * rendered off the track and the first interaction committed `[low, 100]` —
+     * a value the slider itself calls out of range.
+     */
+    private highSeeded;
     protected readonly track: _angular_core.Signal<ElementRef<HTMLElement>>;
     /**
      * Ambient reading direction. Optional so a bare `TestBed` — or any consumer
@@ -101,6 +173,17 @@ declare class WrSlider implements FormValueControl<WrSliderValue> {
     protected onPointerDown(event: PointerEvent, thumb: 'low' | 'high'): void;
     protected onTrackPointerDown(event: PointerEvent): void;
     protected onKey(event: KeyboardEvent, thumb: 'low' | 'high'): void;
+    /**
+     * A bound field learns it may show its validation copy from `touch`, and
+     * pointer-up plus a value-changing keypress cannot be the only sources: a
+     * slider tabbed into and out of without an arrow press left the field
+     * untouched forever — which is exactly the case `touched` exists for, and
+     * what this output has always documented itself as doing. `wr-knob` and
+     * `wr-rating` bind `(blur)` on the one element they own; this component has
+     * two thumbs, so it listens for the bubbling `focusout` on its host instead
+     * — and ignores the one that only moves focus from one thumb to the other.
+     */
+    protected onFocusOut(event: FocusEvent): void;
     private isRtl;
     /**
      * The value under a pointer, measured along the track's INLINE axis.
@@ -127,7 +210,7 @@ declare class WrSlider implements FormValueControl<WrSliderValue> {
     private percentOf;
     private emitChange;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrSlider, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrSlider, "wr-slider", never, { "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "range": { "alias": "range"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "showLabel": { "alias": "showLabel"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrSlider, "wr-slider", never, { "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "range": { "alias": "range"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "showLabel": { "alias": "showLabel"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "upperLabel": { "alias": "upperLabel"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
 }
 
 export { WrSlider };

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

@@ -0,0 +1,69 @@
+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-sparkline>` a harness query matches. */
+interface WrSparklineHarnessFilters extends BaseHarnessFilters {
+    /** Match the sparkline's accessible name — `null` for the decorative ones. */
+    readonly ariaLabel?: 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 `<wr-sparkline>`.
+ *
+ * **The interesting assertion here is the ARIA one.** A sparkline is a trend line
+ * with no axes and no labels, so it is either given an `ariaLabel` — in which case it
+ * announces itself as an image — or it is decoration, and must be `aria-hidden` so a
+ * screen reader does not stop on a nameless graphic. The component switches between
+ * those two states on one input, and {@link isDecorative} is how a spec pins which
+ * one it is in.
+ *
+ * The line itself is an SVG path, and a path's `d` is not something a spec should
+ * assert: it is a rendering detail that changes with the viewBox, the stroke width
+ * and the smoothing. What IS worth asserting is whether the parts are there —
+ * {@link hasLine}, {@link hasArea}, {@link hasTip} — since each is an input the
+ * consumer set, and an empty dataset draws none of them.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSparklineHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSparklineHarnessFilters): HarnessPredicate<WrSparklineHarness>;
+    private readonly svg;
+    /** The name the chart announces, or `null` when it is decoration. */
+    getAccessibleName(): Promise<string | null>;
+    /** The role the chart claims — `img` when it is named, `null` when it is not. */
+    getRole(): Promise<string | null>;
+    /**
+     * Whether the chart is hidden from assistive tech.
+     *
+     * The other half of {@link getAccessibleName}, and the pairing worth asserting
+     * together: a named sparkline must NOT be hidden, and an unnamed one must be, or a
+     * screen reader announces a graphic with nothing to say about it.
+     */
+    isDecorative(): Promise<boolean>;
+    /** Whether a trend line was drawn — `false` for an empty or single-point dataset. */
+    hasLine(): Promise<boolean>;
+    /** Whether the area under the line is filled (`showArea`). */
+    hasArea(): Promise<boolean>;
+    /** Whether the last point is marked with a dot (`showTip`). */
+    hasTip(): Promise<boolean>;
+    /** The stroke colour as the component passed it through — a CSS value, not a resolved one. */
+    getColor(): Promise<string | null>;
+}
+
+export { WrSparklineHarness };
+export type { WrSparklineHarnessFilters };

package/types/ngwr-speed-dial-testing.d.ts

@@ -0,0 +1,199 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+import { WrSpeedDialDirection } from 'ngwr/speed-dial';
+
+/**
+ * @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-speed-dial>` a harness query matches. */
+interface WrSpeedDialHarnessFilters extends BaseHarnessFilters {
+    /** Match the trigger's accessible name — a string is an exact match, a RegExp is tested. */
+    readonly triggerLabel?: string | RegExp;
+    /** Match the direction the actions fan out. */
+    readonly direction?: WrSpeedDialDirection;
+    /** Match only open (`true`) or only closed (`false`) dials. */
+    readonly open?: boolean;
+    /** Match only enabled (`false`) or only disabled (`true`) dials. */
+    readonly disabled?: boolean;
+}
+/** Narrows which action inside a speed dial a harness query matches. */
+interface WrSpeedDialActionHarnessFilters extends BaseHarnessFilters {
+    /** Match the action's accessible name — a string is an exact match, a RegExp is tested. */
+    readonly label?: string | RegExp;
+    /** Match only enabled (`false`) or only disabled (`true`) actions. */
+    readonly disabled?: 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 action inside a {@link WrSpeedDialHarness}.
+ *
+ * The label is read from `aria-label` rather than from the button's text, and that
+ * is the whole point of the control: an action renders an ICON, or — with no icon —
+ * the first glyph of its label. Its visible text is therefore `"S"` for "Share", or
+ * nothing at all. {@link getInitial} answers what is drawn; {@link getLabel} answers
+ * what it is.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSpeedDialActionHarness extends ComponentHarness {
+    /** The action button. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSpeedDialActionHarnessFilters): HarnessPredicate<WrSpeedDialActionHarness>;
+    /** The action's accessible name — what a screen reader reads, and what `title` shows. */
+    getLabel(): Promise<string | null>;
+    /** Whether the action draws an icon rather than a letter. */
+    hasIcon(): Promise<boolean>;
+    /** The icon's registered name, from `wr-icon`'s reflected `data-icon`, or `null`. */
+    getIconName(): Promise<string | null>;
+    /**
+     * The single glyph drawn in place of a missing icon, or `null` when there is one.
+     *
+     * A GLYPH, not a character: the component splits the label by code point, so an
+     * emoji label draws the whole emoji rather than the broken half of a surrogate pair.
+     */
+    getInitial(): Promise<string | null>;
+    /**
+     * Whether the action refuses interaction.
+     *
+     * Every action follows the DIAL's `disabled` — there is no per-action flag — so
+     * this is really "is the dial disabled", asked at the action. Worth having anyway:
+     * it is what the DOM and the CDK consult before delivering a click.
+     */
+    isDisabled(): Promise<boolean>;
+    /** Pick this action — emitting `pick` and closing the dial. */
+    click(): Promise<void>;
+    /** Move keyboard focus to the action. */
+    focus(): Promise<void>;
+    /** Whether the action currently holds focus. */
+    isFocused(): 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-speed-dial>` — the floating trigger and the actions that fan
+ * out of it.
+ *
+ * **The actions never leave the DOM.** They are hidden with `visibility`, which is
+ * what actually takes them out of the tab order and the accessibility tree —
+ * `opacity: 0` alone would leave them focusable — and CSS is exactly what a unit
+ * test does not have. So a closed dial's buttons are queryable, clickable and
+ * readable from a spec while being unreachable in a browser. {@link getActions} and
+ * {@link pick} therefore REFUSE while the dial is closed rather than answering with
+ * elements nobody can see; open it first, which is what a user has to do too.
+ *
+ * @example
+ * ```ts
+ * const dial = await loader.getHarness(WrSpeedDialHarness);
+ *
+ * await dial.open();
+ * expect(await dial.getActionLabels()).toEqual(['Share', 'Copy link']);
+ *
+ * await dial.pick({ label: 'Share' });
+ * expect(await dial.isOpen()).toBe(false);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrSpeedDialHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrSpeedDialHarnessFilters): HarnessPredicate<WrSpeedDialHarness>;
+    private readonly trigger;
+    private readonly menu;
+    /** Whether the dial is fanned out, from the trigger's `aria-expanded`. */
+    isOpen(): Promise<boolean>;
+    /** The direction the actions travel, from the host modifier. */
+    getDirection(): Promise<WrSpeedDialDirection>;
+    /**
+     * The trigger's accessible name.
+     *
+     * The trigger is icon-only, so this is its ONLY name — there is no text to fall
+     * back on, and a dial that loses it is announced as an unnamed button.
+     */
+    getTriggerLabel(): Promise<string | null>;
+    /** The trigger icon's registered name, from `wr-icon`'s reflected `data-icon`. */
+    getTriggerIcon(): Promise<string | null>;
+    /** Whether the dial refuses interaction, from the trigger's own `disabled` property. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the host is padded for the device's safe area (`safeArea`). */
+    hasSafeArea(): Promise<boolean>;
+    /**
+     * The role the action list announces — `list`.
+     *
+     * Worth asking despite being a plain `<ul>`: the list is styled `list-style: none`,
+     * which drops the implicit list semantics in Safari, so the role is written out. It
+     * is deliberately NOT `menu` — that role promises arrows, Home/End and a single tab
+     * stop, none of which this component has.
+     */
+    getMenuRole(): Promise<string | null>;
+    /**
+     * Whether the trigger's `aria-controls` names THIS dial's action list, and nothing
+     * else on the page.
+     *
+     * Both halves matter. The id is resolved inside the host first, so a trigger
+     * pointing at a SIBLING dial's list — which resolves perfectly well from the
+     * document — fails here. Then it is counted across the document, because two lists
+     * answering to one id hand every reference to whichever comes first.
+     */
+    isMenuBound(): Promise<boolean>;
+    /**
+     * The actions, in DOM order.
+     *
+     * Throws while the dial is closed. The buttons are still in the DOM then — they
+     * have to be, for the fan-out to animate — and jsdom applies no `visibility`, so
+     * they would come back looking perfectly reachable when a real user cannot tab to
+     * one. A spec that read them closed would pass on a dial that never opens.
+     */
+    getActions(filters?: WrSpeedDialActionHarnessFilters): Promise<WrSpeedDialActionHarness[]>;
+    /** The accessible names of the actions, in DOM order. Throws while closed. */
+    getActionLabels(): Promise<(string | null)[]>;
+    /** How many actions the dial holds — readable while closed, since it is not a reach. */
+    getActionCount(): Promise<number>;
+    /** Open the dial. An already-open one is left alone; a disabled one throws. */
+    open(): Promise<void>;
+    /** Close the dial. An already-closed one is left alone. */
+    close(): Promise<void>;
+    /** Click the trigger once, whichever way that takes it. */
+    toggle(): Promise<void>;
+    /**
+     * Pick the first action matching the filters — emitting `pick` and closing the dial.
+     *
+     * Opens first if it has to, the way `WrDropdownHarness.clickItem` does: a spec that
+     * says "pick Share" means the whole gesture. Throws when nothing matches, naming
+     * what the dial does offer.
+     */
+    pick(filters: WrSpeedDialActionHarnessFilters): Promise<void>;
+    /**
+     * Press Escape — closing the dial and putting focus back on the trigger.
+     *
+     * Sent to the host, which is where the component listens. The focus return is the
+     * half worth asserting: the actions are ordinary tab stops, so without it a keyboard
+     * user has to walk through every action to leave.
+     */
+    sendEscape(): Promise<void>;
+    /** Move keyboard focus to the trigger. */
+    focusTrigger(): Promise<void>;
+    /** Whether the trigger currently holds focus. */
+    isTriggerFocused(): Promise<boolean>;
+    private requireOpen;
+}
+
+export { WrSpeedDialActionHarness, WrSpeedDialHarness };
+export type { WrSpeedDialActionHarnessFilters, WrSpeedDialHarnessFilters };

package/types/ngwr-speed-dial.d.ts

@@ -11,6 +11,24 @@ interface WrSpeedDialAction {
 /** Direction the action buttons fan out. */
 type WrSpeedDialDirection = 'up' | 'down' | 'left' | 'right';
 
+/**
+ * Floating action button that expands into a fan of secondary actions on click.
+ * Place inside a positioned container or near `position: fixed` — the component
+ * itself doesn't pin to the viewport.
+ *
+ * @example
+ * ```html
+ * <wr-speed-dial
+ *   [actions]="[
+ *     { id: 'new', label: 'New', icon: 'add' },
+ *     { id: 'edit', label: 'Edit', icon: 'cog' }
+ *   ]"
+ *   (pick)="onPick($event)"
+ * />
+ * ```
+ *
+ * @see https://ngwr.dev/reference/components/speed-dial
+ */
 declare class WrSpeedDial {
     readonly actions: _angular_core.InputSignal<readonly WrSpeedDialAction[]>;
     /**
@@ -38,14 +56,15 @@ declare class WrSpeedDial {
     /** Id the trigger's `aria-controls` points at. */
     protected readonly menuId: string;
     protected readonly triggerEl: _angular_core.Signal<ElementRef<HTMLButtonElement> | undefined>;
+    private readonly host;
     constructor();
     protected readonly classes: _angular_core.Signal<string>;
     protected onTrigger(): void;
     protected onPick(action: WrSpeedDialAction): void;
     /**
-     * `role="menu"` promises a way out, and the actions are ordinary buttons in the tab
-     * order — without this a keyboard user who opened the dial had to tab through every
-     * action to leave it.
+     * Escape closes the dial and hands the caret back. The actions are ordinary buttons
+     * in the tab order, so without this a keyboard user who opened the dial had to tab
+     * through every action to leave it.
      */
     protected onKeydown(event: KeyboardEvent): void;
     /**