ngwr 10.2.0 → 11.0.0

package/types/ngwr-affix.d.ts

@@ -2,7 +2,7 @@ import * as _angular_core from '@angular/core';
 
 /**
  * Stick-on-scroll directive. Combines native CSS `position: sticky` with
- * an `IntersectionObserver`-driven `--affixed` state class, so consumers
+ * an `IntersectionObserver`-driven `wr-affix--active` state class, so consumers
  * can style the element differently while it's pinned (e.g. add a
  * shadow, change the background, shrink the height).
  *
@@ -35,6 +35,12 @@ declare class WrAffix {
     private readonly host;
     private readonly destroyRef;
     private readonly isBrowser;
+    /**
+     * `afterNextRender`'s callback is not an injection context, and the observer
+     * cannot exist before the sentinel it watches — so the effect that rebuilds it
+     * is handed the injector explicitly.
+     */
+    private readonly injector;
     constructor();
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrAffix, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WrAffix, "[wrAffix]", never, { "offsetTop": { "alias": "wrAffixOffsetTop"; "required": false; "isSignal": true; }; }, { "affixChange": "wrAffixChange"; }, never, never, true, never>;

package/types/ngwr-anchor.d.ts

@@ -32,6 +32,13 @@ interface WrAnchorLink {
  */
 declare class WrAnchor {
     readonly links: _angular_core.InputSignal<readonly WrAnchorLink[]>;
+    /**
+     * Accessible name for the navigation landmark. Falls back to `anchor.label`,
+     * then `'Table of contents'` — it used to be that English string, hard-coded
+     * on the host, in a landmark a screen reader reads out on every page.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly resolvedAriaLabel: _angular_core.Signal<string>;
     /** Pixel offset subtracted on scroll — for sticky headers. @default 0 */
     readonly offset: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Highlight an item when its target's top is within this many px of the offset line. @default 80 */
@@ -46,7 +53,7 @@ declare class WrAnchor {
     constructor();
     protected onClick(id: string, event: MouseEvent): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrAnchor, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrAnchor, "wr-anchor", never, { "links": { "alias": "links"; "required": false; "isSignal": true; }; "offset": { "alias": "offset"; "required": false; "isSignal": true; }; "hitArea": { "alias": "hitArea"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrAnchor, "wr-anchor", never, { "links": { "alias": "links"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "offset": { "alias": "offset"; "required": false; "isSignal": true; }; "hitArea": { "alias": "hitArea"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { WrAnchor };

package/types/ngwr-avatar.d.ts

@@ -58,11 +58,13 @@ declare class WrAvatar {
      */
     readonly url: _angular_core.InputSignal<string | null>;
     /**
-     * Alt text for the image.
+     * Alt text for the image. Falls back to `avatar.alt`, then `'Avatar'` — pass
+     * the person's name where you have it, since that is what a reader wants.
      *
-     * @default 'Avatar'
+     * @default null
      */
-    readonly alt: _angular_core.InputSignal<string>;
+    readonly alt: _angular_core.InputSignal<string | null>;
+    protected readonly resolvedAlt: _angular_core.Signal<string>;
     /**
      * Corner treatment. `rounded` (default) is a soft rounded square,
      * `circle` is the classic profile avatar, `squircle` is the iOS look.
@@ -77,11 +79,19 @@ declare class WrAvatar {
      */
     readonly size: _angular_core.InputSignal<WrAvatarSize>;
     protected readonly loaded: _angular_core.WritableSignal<boolean>;
+    /**
+     * Whether the image failed. Without this the spinner spun forever on a broken
+     * URL — the one state where an avatar is guaranteed to have projected initials
+     * worth showing instead.
+     */
+    protected readonly failed: _angular_core.WritableSignal<boolean>;
+    constructor();
     protected readonly resolved: _angular_core.Signal<ResolvedCssSize>;
     protected readonly cssSize: _angular_core.Signal<string>;
     protected readonly pxSize: _angular_core.Signal<number | null>;
     protected readonly classes: _angular_core.Signal<string>;
     protected onImageLoad(): void;
+    protected onImageError(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrAvatar, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrAvatar, "wr-avatar", never, { "url": { "alias": "url"; "required": false; "isSignal": true; }; "alt": { "alias": "alt"; "required": false; "isSignal": true; }; "shape": { "alias": "shape"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }

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

@@ -32,12 +32,28 @@ declare class WrBarChart {
     readonly height: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Explicit max value. `0` = auto. @default 0 */
     readonly max: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * A datum's value, with anything non-finite read as `0`.
+     *
+     * One `NaN` used to take out the whole chart rather than its own bar:
+     * `Math.max(...values)` is `NaN` as soon as one value is, so the scale fell
+     * back to `1` and every OTHER bar was asked for a height of `value * 100`%.
+     * The bad bar also printed the literal text `NaN` above itself.
+     */
+    private static value;
     protected readonly resolvedMax: _angular_core.Signal<number>;
     protected readonly bars: _angular_core.Signal<{
         label: string;
         value: number;
         color: string;
         heightPercent: number;
+        /**
+         * The bar's accessible name. The label and the value sit in separate
+         * rows, so a screen reader read every number and then every label with
+         * nothing tying the two together — and with `showValues` off the
+         * numbers were not in the accessible tree at all.
+         */
+        name: string;
     }[]>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrBarChart, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrBarChart, "wr-bar-chart", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "showValues": { "alias": "showValues"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;

package/types/ngwr-burger.d.ts

@@ -20,8 +20,12 @@ import * as _angular_core from '@angular/core';
 declare class WrBurger {
     /** Two-way bindable open state. Drives the hamburger ↔ close morph. @default false */
     readonly open: _angular_core.ModelSignal<boolean>;
-    /** Accessible label for the toggle button. @default 'Toggle menu' */
-    readonly label: _angular_core.InputSignal<string>;
+    /**
+     * Accessible name for the toggle button. Falls back to `burger.label`, then
+     * `'Toggle menu'`.
+     */
+    readonly label: _angular_core.InputSignal<string | null>;
+    protected readonly resolvedLabel: _angular_core.Signal<string>;
     /** Disable the toggle. @default false */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
     protected readonly classes: _angular_core.Signal<{

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

@@ -0,0 +1,85 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+import { WrColor } from 'ngwr/theme';
+
+/**
+ * @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-btn>` a harness query matches. */
+interface WrButtonHarnessFilters extends BaseHarnessFilters {
+    /** Match the button's visible label — a string is an exact match, a RegExp is tested. */
+    readonly text?: string | RegExp;
+    /** Match only enabled (`false`) or only disabled (`true`) buttons. */
+    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 `<wr-btn>` — drive a button from a consumer's spec without
+ * knowing how it is built.
+ *
+ * Everything this reads is public API: the `wr-btn` selector, the
+ * `.wr-btn__label` element, the `wr-btn--*` modifiers and the disabled attributes.
+ * `<wr-btn>` is deliberately NOT always a native `<button>` — the element form
+ * exists so a link or a custom host can be one — which is why the disabled state
+ * is answered from the ATTRIBUTES rather than from `el.disabled`, a property half
+ * of those shapes do not have.
+ *
+ * @example
+ * ```ts
+ * const loader = TestbedHarnessEnvironment.loader(fixture);
+ * const save = await loader.getHarness(WrButtonHarness.with({ text: 'Save' }));
+ *
+ * expect(await save.isDisabled()).toBe(false);
+ * await save.click();
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrButtonHarness extends ComponentHarness {
+    /** Every shape the button ships in: the element, and the two attribute forms. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrButtonHarnessFilters): HarnessPredicate<WrButtonHarness>;
+    /** The button's visible label, trimmed. Icons and the spinner are not part of it. */
+    getText(): Promise<string>;
+    /**
+     * Whether the button refuses interaction.
+     *
+     * Both signals are read, because the component sets them for different reasons:
+     * `disabled` lands on every shape (it is inert on a custom element, which is
+     * exactly why `aria-disabled` exists as well, but it is the attribute that is
+     * always there). A button that is merely LOADING also answers `true` here, and
+     * that is not a quirk — by default a loading button refuses clicks.
+     */
+    isDisabled(): Promise<boolean>;
+    /** Whether the button is showing its loading spinner. */
+    isLoading(): Promise<boolean>;
+    /**
+     * The intent colour, or `null` when the button carries none.
+     *
+     * Matched against `WR_COLORS` rather than "the first `wr-btn--*` class": the
+     * modifier list also carries the size, the shape, `outlined`, `block`, `loading`
+     * and the icon position, so a pattern match answers `icon` as readily as
+     * `primary`.
+     */
+    getColor(): Promise<WrColor | null>;
+    /** Click the button. A disabled button is still clicked — assert, do not assume. */
+    click(): Promise<void>;
+    /** Move keyboard focus to the button. */
+    focus(): Promise<void>;
+    /** Whether the button currently has focus. */
+    isFocused(): Promise<boolean>;
+}
+
+export { WrButtonHarness };
+export type { WrButtonHarnessFilters };

package/types/ngwr-button.d.ts

@@ -68,13 +68,26 @@ type WrButtonIconPosition = 'start' | 'end';
  * @see https://ngwr.dev/reference/components/button
  */
 declare class WrButton {
-    /** Color variant. Omit for the neutral default style. @default null */
+    /**
+     * Color variant. Omit for the neutral default style.
+     *
+     * Deliberately NOT configurable app-wide: the library's own chrome binds
+     * `[color]="isCurrent ? 'primary' : null"`, where `null` means neutral, and a
+     * configured intent would repaint every one of those buttons. See `WrConfig`.
+     *
+     * @default null
+     */
     readonly color: _angular_core.InputSignal<"primary" | "secondary" | "success" | "warning" | "danger" | "info" | "light" | "medium" | "dark" | null>;
-    /** Size variant. @default 'md' */
-    readonly size: _angular_core.InputSignal<WrButtonSize>;
     /**
-     * Corner treatment — `rounded` or `pill`. `null` (default) falls back
-     * to `rounded`. Inside a `<wr-btn-group shape="…">`, the group's shape
+     * Size variant. Unset, it resolves through
+     * `provideWrConfig({ button: { size } })` and then to `md`.
+     *
+     * @default 'md'
+     */
+    readonly size: _angular_core.InputSignal<WrButtonSize | null>;
+    /**
+     * Corner treatment — `rounded`, `pill` or `squircle`. `null` (default) falls
+     * back to `rounded`. Inside a `<wr-btn-group shape="…">`, the group's shape
      * ALWAYS wins over this input — the group enforces a consistent corner
      * treatment across its members.
      *
@@ -106,14 +119,49 @@ declare class WrButton {
      */
     readonly isDisabledWhenLoading: _angular_core.InputSignalWithTransform<boolean, any>;
     private readonly group;
+    /** The size, or the app-wide default, or `md`. @see useConfigValue */
+    protected readonly resolvedSize: _angular_core.Signal<WrButtonSize>;
+    /**
+     * Resolved shape. Inside a `<wr-btn-group>`, the group ALWAYS wins — child
+     * `[shape]` is ignored entirely so the group reads as one coherent control.
+     * Outside a group, the button's own `[shape]` is used, falling back to
+     * `rounded`. Not config-resolved: see `WrConfig` for why a boolean cannot
+     * express this three-valued input.
+     */
+    protected readonly resolvedShape: _angular_core.Signal<WrButtonShape>;
+    private readonly hostEl;
     /**
-     * Resolved shape. Inside a `<wr-btn-group>`, the group ALWAYS wins —
-     * child `[shape]` is ignored entirely so the group reads as one
-     * coherent control. Outside a group, the button's own `[shape]` is
-     * used, falling back to `rounded`.
+     * Whether this instance is the `<wr-btn>` ELEMENT rather than the attribute
+     * form on a native `<button>` / `<a>`.
+     *
+     * The element form is documented as first-class and is what the pagination,
+     * event-calendar and popconfirm chrome use — but a custom element has no
+     * button semantics of its own. It was rendering with no `role`, no
+     * `tabindex` and no keyboard activation, so it was invisible to assistive
+     * tech and unreachable by Tab. Measured in Chromium against the built site:
+     * the whole `wr-pagination` subtree, 26 elements, contained ZERO focusable
+     * nodes and sixty Tab presses never entered it. axe cannot see this — an
+     * unknown element with no role simply is not an interactive control to it,
+     * which is the same blind spot that lets `disabled` pass unnoticed on a
+     * custom element.
      */
-    protected readonly effectiveShape: _angular_core.Signal<WrButtonShape>;
+    private readonly isCustomHost;
+    private readonly isOff;
     protected readonly nativeDisabled: _angular_core.Signal<"" | null>;
+    protected readonly hostRole: _angular_core.Signal<"button" | null>;
+    /** Out of the tab order while off — `disabled` is inert on a custom element. */
+    protected readonly hostTabIndex: _angular_core.Signal<"0" | null>;
+    protected readonly hostAriaDisabled: _angular_core.Signal<"true" | null>;
+    /**
+     * Enter and Space activate a button. A native one does this for free; a
+     * custom element does not, so without this the element form could be focused
+     * (once it had a tabindex) and still not be operable.
+     *
+     * `preventDefault` on Space is not optional — it scrolls the page otherwise.
+     * The pointer path needs no guard here: `.wr-btn[disabled]` already sets
+     * `pointer-events: none`.
+     */
+    protected onHostKeydown(event: KeyboardEvent): void;
     protected readonly classes: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrButton, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrButton, "wr-btn, button[wr-btn], a[wr-btn]", never, { "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "shape": { "alias": "shape"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconPosition": { "alias": "iconPosition"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "outlined": { "alias": "outlined"; "required": false; "isSignal": true; }; "block": { "alias": "block"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "isDisabledWhenLoading": { "alias": "isDisabledWhenLoading"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;

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

@@ -27,6 +27,13 @@ interface Cell {
  */
 declare class WrCalendarHeatmap {
     readonly data: _angular_core.InputSignal<readonly WrHeatmapDatum[]>;
+    /**
+     * Accessible name of the whole grid. Its cells are bare spans whose `title` a screen
+     * reader on a role-less element does not read, so the map used to be several hundred
+     * anonymous nodes with no name. Falls back to `calendarHeatmap.label`.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly resolvedAriaLabel: _angular_core.Signal<string>;
     /** Last day to render. @default today */
     readonly endDate: _angular_core.InputSignal<string | Date | null>;
     /** Number of weeks (columns) to render. @default 53 */
@@ -41,7 +48,14 @@ declare class WrCalendarHeatmap {
     readonly emptyColor: _angular_core.InputSignal<string>;
     /** Show the weekday + month labels around the grid. @default true */
     readonly showLabels: _angular_core.InputSignalWithTransform<boolean, any>;
-    protected readonly weekdayLabels: string[];
+    private readonly locale;
+    /**
+     * Weekday names from the locale rather than a hard-coded English list — the row order is
+     * Sunday-first, matching the grid's own alignment, so 7 Jan 2024 (a Sunday) is the
+     * reference. Rows without a label stay blank on purpose: seven labels do not fit.
+     */
+    protected readonly weekdayLabels: _angular_core.Signal<readonly string[]>;
+    private readonly monthNames;
     protected readonly cells: _angular_core.Signal<readonly Cell[]>;
     protected readonly monthLabels: _angular_core.Signal<{
         label: string;
@@ -51,7 +65,7 @@ declare class WrCalendarHeatmap {
     protected colorFor(intensity: number): string;
     protected opacityFor(intensity: number): number;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrCalendarHeatmap, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCalendarHeatmap, "wr-calendar-heatmap", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "endDate": { "alias": "endDate"; "required": false; "isSignal": true; }; "weeks": { "alias": "weeks"; "required": false; "isSignal": true; }; "cellSize": { "alias": "cellSize"; "required": false; "isSignal": true; }; "cellGap": { "alias": "cellGap"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "emptyColor": { "alias": "emptyColor"; "required": false; "isSignal": true; }; "showLabels": { "alias": "showLabels"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCalendarHeatmap, "wr-calendar-heatmap", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "endDate": { "alias": "endDate"; "required": false; "isSignal": true; }; "weeks": { "alias": "weeks"; "required": false; "isSignal": true; }; "cellSize": { "alias": "cellSize"; "required": false; "isSignal": true; }; "cellGap": { "alias": "cellGap"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "emptyColor": { "alias": "emptyColor"; "required": false; "isSignal": true; }; "showLabels": { "alias": "showLabels"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { WrCalendarHeatmap };

package/types/ngwr-calendar.d.ts

@@ -56,10 +56,21 @@ declare class WrCalendar {
     readonly max: _angular_core.InputSignal<Date | null>;
     /** Predicate — return `false` to disable specific dates (e.g. weekends only). */
     readonly dateFilter: _angular_core.InputSignal<((date: Date) => boolean) | null>;
+    /**
+     * Move real focus onto the roving cell as soon as the grid is on screen.
+     *
+     * Off by default: a standalone `<wr-calendar>` sitting in a page must not
+     * steal focus on load. `wr-date-picker` turns it on for the popup it opens
+     * from its trigger, where the user asked to be taken to the calendar.
+     * @default false
+     */
+    readonly autoFocus: _angular_core.InputSignalWithTransform<boolean, any>;
     /** Disable interaction entirely. @default false */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
     private readonly adapter;
+    private readonly dir;
     private readonly host;
+    private readonly injector;
     /** Currently displayed month (any date inside it). */
     protected readonly viewDate: _angular_core.WritableSignal<Date>;
     /** Date currently focused by keyboard (single roving tabindex). */
@@ -105,11 +116,36 @@ declare class WrCalendar {
     protected onCellLeave(): void;
     private applyRangeClick;
     protected onKeyDown(event: KeyboardEvent): void;
+    /**
+     * The first selectable day at or after `candidate`, else the first before it,
+     * else `candidate` unchanged when everything nearby is closed off. Bounded at
+     * a year each way so a pathological `dateFilter` cannot spin.
+     */
+    private nearestEnabled;
+    /**
+     * The first selectable day at `candidate` or beyond it in `step`'s direction,
+     * else null when that whole direction is closed off — which is the answer for
+     * an ArrowLeft that would cross `min`: stay put.
+     *
+     * Direction matters. Reusing `nearestEnabled`, which probes forward first,
+     * would send an ArrowLeft over a disabled weekend straight back to the day it
+     * started from, so the ring could never cross the hole.
+     */
+    private nearestEnabledToward;
     private focusActiveCell;
     /** Used by the template's `track` expression. */
     protected trackByTime(_: number, date: Date): number;
+    /**
+     * The key as the GRID sees it.
+     *
+     * Arrow keys follow visual order, and a calendar grid mirrors under
+     * `dir="rtl"`: the day to the visual right of today is yesterday. Only the
+     * inline pair swaps — Up/Down step a week either way, and PageUp/PageDown and
+     * Home/End are semantic rather than physical.
+     */
+    private inlineKey;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrCalendar, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCalendar, "wr-calendar", never, { "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "date": { "alias": "date"; "required": false; "isSignal": true; }; "range": { "alias": "range"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "dateFilter": { "alias": "dateFilter"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "date": "dateChange"; "range": "rangeChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrCalendar, "wr-calendar", never, { "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "date": { "alias": "date"; "required": false; "isSignal": true; }; "range": { "alias": "range"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "dateFilter": { "alias": "dateFilter"; "required": false; "isSignal": true; }; "autoFocus": { "alias": "autoFocus"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "date": "dateChange"; "range": "rangeChange"; }, never, never, true, never>;
 }
 
 export { WrCalendar };