ngwr 10.2.1 → 11.0.0

package/types/ngwr-date-picker-testing.d.ts

@@ -0,0 +1,518 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate, TestElement, HarnessLoader } 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-date-picker>` a harness query matches. */
+interface WrDatePickerHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the text the field is showing — the formatted value, or `''` when the
+     * picker is empty and the placeholder is up. A string is an exact match, a
+     * RegExp is tested.
+     */
+    readonly text?: string | RegExp;
+    /** Match the field's placeholder — a string is an exact match, a RegExp is tested. */
+    readonly placeholder?: string | RegExp;
+    /** Match one mode only. */
+    readonly mode?: 'date' | 'time' | 'datetime';
+    /** Match only enabled (`false`) or only disabled (`true`) pickers. */
+    readonly disabled?: boolean;
+    /** Match only pickers whose popup is up (`true`) or down (`false`). */
+    readonly open?: boolean;
+}
+/** Narrows which `<wr-date-range-picker>` a harness query matches. */
+interface WrDateRangePickerHarnessFilters extends BaseHarnessFilters {
+    /** Match the text in the START field. A string is an exact match, a RegExp is tested. */
+    readonly startText?: string | RegExp;
+    /** Match the text in the END field. A string is an exact match, a RegExp is tested. */
+    readonly endText?: string | RegExp;
+    /** Match one mode only. The range picker has no `time` mode. */
+    readonly mode?: 'date' | 'datetime';
+    /** Match only enabled (`false`) or only disabled (`true`) pickers. */
+    readonly disabled?: boolean;
+    /** Match only pickers whose popup is up (`true`) or down (`false`). */
+    readonly open?: boolean;
+}
+/** Narrows which day cell inside a picker's calendar a harness query matches. */
+interface WrDatePickerDayHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the cell's day number as rendered (`'1'` … `'31'`). A string is an
+     * exact match, a RegExp is tested — note the grid spills into the neighbouring
+     * months, so a number appears twice on most months.
+     */
+    readonly text?: string | RegExp;
+    /** Match only selected (`true`) or only unselected (`false`) cells. */
+    readonly selected?: boolean;
+    /** Match only enabled (`false`) or only disabled (`true`) cells. */
+    readonly disabled?: boolean;
+    /**
+     * Match cells strictly BETWEEN the two ends of a picked range — the ends
+     * themselves are `selected`, not `inRange`. Always `false` for
+     * `<wr-date-picker>`, whose calendar has a single value.
+     */
+    readonly inRange?: 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
+ */
+/**
+ * Which boxes of a time stepper to type into. Omitted fields are left alone, so
+ * `{ minutes: 45 }` changes the minutes and nothing else.
+ *
+ * Hours are given the way the stepper SHOWS them: 0-23 for a 24-hour panel,
+ * 1-12 for a 12-hour one (where AM/PM stays where it was — flip it with
+ * `toggleMeridiem()`).
+ */
+interface WrDatePickerTimeFields {
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+}
+
+/**
+ * @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 day cell of the calendar inside a date-picker popup.
+ *
+ * Reached through `WrDatePickerHarness.getDay()` / `getDays()` (or the range
+ * picker's), which scope it to ONE picker's panel — the cells are in the overlay
+ * container, so a bare query would answer with whichever picker opened first.
+ *
+ * State is read the way a screen reader reads it (`role`, `aria-selected`,
+ * `aria-disabled`) with the `.wr-calendar__day--*` modifiers filling in what
+ * ARIA has no word for: today, the spill days of the neighbouring months, and
+ * the interior of a picked range.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrDatePickerDayHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrDatePickerDayHarnessFilters): HarnessPredicate<WrDatePickerDayHarness>;
+    /** The day number as rendered. */
+    getText(): Promise<string>;
+    /** The day number as a number, for mapping a list of cells to dates. */
+    getDayOfMonth(): Promise<number>;
+    /** `'gridcell'` — the cell is a button, and the grid semantics are what a spec should assert. */
+    getRole(): Promise<string | null>;
+    /** Whether this day is (one end of) the current selection. */
+    isSelected(): Promise<boolean>;
+    /**
+     * Whether the day refuses selection — `min` / `max` or `dateFilter` ruled it
+     * out, or the whole calendar is disabled.
+     */
+    isDisabled(): Promise<boolean>;
+    /** Whether the cell is today's date. */
+    isToday(): Promise<boolean>;
+    /**
+     * Whether the cell belongs to a neighbouring month. The grid is always 6x7, so
+     * every month is padded with days that are selectable but not "in" the month —
+     * which is why {@link WrDatePickerHarness.getDay} skips them.
+     */
+    isOutOfMonth(): Promise<boolean>;
+    /** Whether the day lies strictly between the two ends of a picked range. */
+    isInRange(): Promise<boolean>;
+    /**
+     * Whether this is the roving cell — the grid's single tab stop, and where the
+     * arrow keys move from.
+     *
+     * At most ONE cell answers `true`, and it is not always one: the calendar's
+     * roving date does not follow `next()` / `previous()`, so a grid navigated away
+     * from that month has no active cell (and, deliberately or not, no tab stop)
+     * until a cell is clicked or the arrows move it.
+     */
+    isActive(): Promise<boolean>;
+    /** Click the cell. A disabled cell swallows the click — assert, do not assume. */
+    click(): 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
+ */
+
+/** Column order inside the stepper, which is also the order the boxes render in. */
+declare const UNITS: readonly ["hours", "minutes", "seconds"];
+/** One unit of a time stepper. */
+type Unit = (typeof UNITS)[number];
+/**
+ * The `<wr-time-picker>` stepper inside a date-picker popup.
+ *
+ * Deliberately NOT exported from the entry point: the component is `@internal`
+ * (`<wr-date-picker mode="time">` is how a consumer gets one), so the picker
+ * harnesses re-publish what it can do — `getTime()`, `setTime()`, `stepTime()`,
+ * `toggleMeridiem()` — rather than handing out this class. It exists so the
+ * range picker, which renders one stepper PER END, can address them
+ * independently instead of by CSS nth-of-type gymnastics.
+ *
+ * Units are addressed by position, not by the boxes' `aria-label`: every string
+ * in this panel is still hard-coded English (the box labels, the steppers'
+ * "Increment hours", the AM/PM text), so keying on them would make this harness
+ * the thing that breaks when they are moved into the i18n catalog. Column order
+ * is the layout contract.
+ *
+ * @internal
+ */
+declare class WrTimePanelHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** The stepper's value as `HH:MM`, plus `:SS` and ` AM`/` PM` when those columns exist. */
+    getTimeText(): Promise<string>;
+    /** `'AM'` / `'PM'`, or `null` when the stepper is in 24-hour mode. */
+    getMeridiem(): Promise<string | null>;
+    /**
+     * Type into the boxes named by `fields`, leaving the rest alone.
+     *
+     * Each box is cleared and retyped rather than assigned: the panel reads an
+     * emptied box as someone mid-retype and deliberately commits nothing for it, so
+     * a harness that only cleared would look like a no-op.
+     */
+    setFields(fields: WrDatePickerTimeFields): Promise<void>;
+    /** Click a unit's ▲ / ▼ button once. Minutes and seconds move by the picker's `step`. */
+    step(unit: Unit, direction: 1 | -1): Promise<void>;
+    /** Flip AM ↔ PM. Throws on a 24-hour stepper, which has no such control. */
+    toggleMeridiem(): Promise<void>;
+    /** A unit's rendered (zero-padded) value. */
+    private getValue;
+    /** Same, but `null` when the column is not rendered at all. */
+    private getOptionalValue;
+    private box;
+    /** The typable boxes, in column order — the AM/PM column is a `<span>`, not one of these. */
+    private boxes;
+}
+
+/**
+ * @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
+ */
+
+/**
+ * Everything `<wr-date-picker>` and `<wr-date-range-picker>` do identically: the
+ * trigger button, the popup it owns, and the `<wr-calendar>` inside it. Both
+ * components render the SAME trigger element (`.wr-date-picker__trigger` — the
+ * range picker reuses the class rather than minting its own) and both publish
+ * their popup's id through the trigger's `aria-controls`, so the scoping story is
+ * shared too.
+ *
+ * Not exported from the entry point — a consumer works with one of the two
+ * concrete harnesses.
+ *
+ * @internal
+ */
+declare abstract class WrDatePickerHarnessBase extends ComponentHarness {
+    /** Concrete class name, so errors read like the harness the caller reached for. */
+    protected abstract readonly harnessName: string;
+    /**
+     * Whether the popup is up.
+     *
+     * Read from the trigger's `aria-expanded` rather than from a host class: unlike
+     * `wr-select`, neither picker carries an `--open` modifier, and the ARIA state
+     * is the thing a consumer's users actually get told.
+     */
+    isOpen(): Promise<boolean>;
+    /** Open the popup from the trigger. An already-open picker is left alone. */
+    open(): Promise<void>;
+    /**
+     * Close the popup by clicking the trigger again. A closed picker is left alone.
+     *
+     * Deliberately not Escape: the CDK dispatches a keydown to the TOP-MOST overlay,
+     * so with two pickers open this would close whichever opened last rather than
+     * this one. The trigger only ever toggles its own popup.
+     */
+    close(): Promise<void>;
+    /** The popup's role — `'dialog'`, which is what the trigger's `aria-haspopup` promises. */
+    getPanelRole(): Promise<string | null>;
+    /**
+     * The popup's accessible name. Defaults to a catalog string chosen by `mode`
+     * ("Choose date", "Choose time", …) and is overridden by `[panelAriaLabel]`.
+     */
+    getPanelAriaLabel(): Promise<string | null>;
+    /**
+     * Which of the calendar's three views is showing. The header label zooms out
+     * (day → month → year); picking a month or a year zooms back in.
+     */
+    getView(): Promise<'day' | 'month' | 'year'>;
+    /**
+     * The calendar's header: `'January 2025'` in the day view, `'2025'` in the month
+     * view, `'2016 – 2027'` in the year view.
+     */
+    getPanelHeader(): Promise<string>;
+    /** The weekday strip, in display order — `role="columnheader"` cells of the grid's first row. */
+    getWeekdayLabels(): Promise<string[]>;
+    /**
+     * Step the calendar forwards. What one step MEANS follows the active view, as
+     * the button's own `aria-label` says: a month in the day view, a year in the
+     * month view, twelve years in the year view.
+     */
+    next(): Promise<void>;
+    /** Step the calendar backwards — see {@link next} for what one step covers. */
+    previous(): Promise<void>;
+    /**
+     * Zoom out one level by clicking the header, the way a user does: day → month,
+     * month → year. Throws at the year view, where the header is inert.
+     */
+    zoomOut(): Promise<void>;
+    /** Pick a month in the month view, by 0-based index or by the label the calendar renders. */
+    selectMonth(month: number | string): Promise<void>;
+    /** Pick a year in the year view. Only the twelve on show can be picked. */
+    selectYear(year: number): Promise<void>;
+    /**
+     * The day cells of the calendar in this picker's popup, in DOM order — 42 of
+     * them, since the grid is always six weeks and pads into the neighbouring
+     * months.
+     */
+    getDays(filters?: WrDatePickerDayHarnessFilters): Promise<WrDatePickerDayHarness[]>;
+    /**
+     * One day of the month on show. The padding days of the neighbouring months are
+     * skipped, so `getDay(1)` is the 1st of THIS month and never the 1st of the next.
+     */
+    getDay(dayOfMonth: number): Promise<WrDatePickerDayHarness>;
+    /** Click a day of the month on show. */
+    selectDay(dayOfMonth: number): Promise<void>;
+    /** The trigger button. Both components render it with the same class. */
+    protected trigger(): Promise<TestElement>;
+    /**
+     * The id of THIS picker's popup.
+     *
+     * The trigger publishes it as `aria-controls` only while the popup is up, which
+     * makes one lookup answer both questions — is it open, and which of the panes
+     * in the shared overlay container is ours.
+     */
+    protected panelId(): Promise<string>;
+    /** A loader scoped to THIS picker's popup, so a second open picker cannot answer for it. */
+    protected panelLoader(): Promise<HarnessLoader>;
+    /** One element inside THIS picker's popup, or `null`. */
+    protected inPanel(selector: string): Promise<TestElement | null>;
+    /** Every matching element inside THIS picker's popup, in DOM order. */
+    protected allInPanel(selector: string): Promise<TestElement[]>;
+    /**
+     * The time steppers in this popup, in DOM order — none in `date` mode, one for
+     * `time` / `datetime`, and two (start then end) for a datetime range.
+     */
+    protected timePanels(): Promise<WrTimePanelHarness[]>;
+    private navigate;
+    /** Fail early on the day-cell methods rather than answering with an empty list. */
+    private requireGrid;
+    private panel;
+    private noCalendar;
+}
+
+/**
+ * @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-date-picker>` — the `date`, `time` and `datetime` modes
+ * of the one component.
+ *
+ * The popup is NOT inside the picker: it is a pane in the overlay container, a
+ * sibling of the whole app. Everything inside it is therefore reached through the
+ * document root, scoped by the id the trigger publishes as `aria-controls` —
+ * which is what keeps two pickers on one page from reading each other's calendar.
+ *
+ * The value lives in a text field, so there are two ways in and the harness
+ * offers both: {@link setValueText} types a date, {@link selectDay} picks one out
+ * of the grid. There is deliberately no clear BUTTON on this component — an
+ * emptied field is what clears the value, and that is what {@link clear} does.
+ *
+ * @example
+ * ```ts
+ * const picker = await loader.getHarness(WrDatePickerHarness);
+ *
+ * await picker.open();
+ * expect(await picker.getPanelHeader()).toBe('January 2025');
+ * await picker.selectDay(14);
+ *
+ * expect(await picker.getValueText()).toBe('14.01.2025');
+ * expect(await (await picker.getDay(14)).isSelected()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrDatePickerHarness extends WrDatePickerHarnessBase {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrDatePickerHarnessFilters): HarnessPredicate<WrDatePickerHarness>;
+    protected readonly harnessName = "WrDatePickerHarness";
+    /** Which mode the picker is in, read from the `wr-date-picker--*` modifier. */
+    getMode(): Promise<'date' | 'time' | 'datetime'>;
+    /**
+     * What the field is showing: the value in the picker's `format`, or `''` when it
+     * is empty and the placeholder is up.
+     */
+    getValueText(): Promise<string>;
+    /** The field's placeholder. */
+    getPlaceholder(): Promise<string>;
+    /**
+     * Type a date into the field, replacing whatever is there.
+     *
+     * The field is cleared first, so the value passes through `null` on the way —
+     * exactly as it does for a user who selects all and types over it. The picker
+     * parses on every keystroke and commits only when the text parses in full, so a
+     * partial or out-of-bounds entry leaves the model on its last good value.
+     */
+    setValueText(text: string): Promise<void>;
+    /**
+     * Empty the field, which clears the value.
+     *
+     * There is no clear button to click: unlike `wr-select`, this component ships no
+     * `×` affordance, and an empty field is the documented way to get back to `null`.
+     */
+    clear(): Promise<void>;
+    /** Whether the picker refuses interaction. */
+    isDisabled(): Promise<boolean>;
+    /**
+     * Whether the field refuses typing. A read-only picker still OPENS its popup —
+     * documented behaviour, and the one place it parts company with the range picker.
+     */
+    isReadonly(): Promise<boolean>;
+    /** Move focus to the field. */
+    focus(): Promise<void>;
+    /**
+     * Blur the field, which is what reformats a value to canonical and emits `touch`
+     * so a bound `[formField]` can mark itself touched.
+     */
+    blur(): Promise<void>;
+    /** Whether the field currently has focus. */
+    isFocused(): Promise<boolean>;
+    /**
+     * The open time stepper's value as `HH:MM`, plus `:SS` when `showSeconds` is on
+     * and ` AM`/` PM` in 12-hour mode.
+     */
+    getTime(): Promise<string>;
+    /** Type into the open time stepper's boxes. Omitted fields are left alone. */
+    setTime(fields: WrDatePickerTimeFields): Promise<void>;
+    /** Click one of the stepper's ▲ / ▼ buttons. Minutes and seconds move by `step`. */
+    stepTime(unit: 'hours' | 'minutes' | 'seconds', direction: 1 | -1): Promise<void>;
+    /** Flip the stepper between AM and PM. Throws in 24-hour mode, which has no such control. */
+    toggleMeridiem(): Promise<void>;
+    private field;
+    /** The one stepper in the popup — `panelId()` has already refused a closed picker. */
+    private timePanel;
+}
+
+/**
+ * @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 end of the range a call applies to. */
+type End = 'start' | 'end';
+/**
+ * Test harness for `<wr-date-range-picker>` — two text fields over one range
+ * calendar.
+ *
+ * A separate harness rather than a mode of {@link WrDatePickerHarness}, because
+ * the DOM a spec has to reach is genuinely different: two fields with a separator
+ * between them, and in `datetime` mode two time steppers instead of one. Every
+ * call that could mean either field takes an explicit `'start'` / `'end'` — the
+ * component's own bugs were nearly all "which end did that belong to", and a
+ * harness that guessed would reproduce them.
+ *
+ * The popup, the calendar and the scoping work exactly as they do for the single
+ * picker: a pane in the overlay container, addressed by the id the trigger
+ * publishes as `aria-controls`.
+ *
+ * @example
+ * ```ts
+ * const period = await loader.getHarness(WrDateRangePickerHarness);
+ *
+ * await period.open();
+ * await period.selectDay(14);
+ * await period.selectDay(20);
+ *
+ * expect([await period.getStartText(), await period.getEndText()]).toEqual(['14.01.2025', '20.01.2025']);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrDateRangePickerHarness extends WrDatePickerHarnessBase {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrDateRangePickerHarnessFilters): HarnessPredicate<WrDateRangePickerHarness>;
+    protected readonly harnessName = "WrDateRangePickerHarness";
+    /** Which mode the picker is in, read from the `wr-date-range-picker--*` modifier. */
+    getMode(): Promise<'date' | 'datetime'>;
+    /** What the start field is showing — `''` while that end is unpicked. */
+    getStartText(): Promise<string>;
+    /** What the end field is showing — `''` while that end is unpicked. */
+    getEndText(): Promise<string>;
+    /** The glyph rendered between the two fields (`[separator]`, `'–'` by default). */
+    getSeparator(): Promise<string>;
+    /** The placeholder of one field. */
+    getPlaceholder(end: End): Promise<string>;
+    /**
+     * Type a date into the start field, replacing whatever is there.
+     *
+     * Ends typed out of order are NOT swapped here — the component settles the
+     * ordering when the interaction is over, so call {@link blur} (or close the
+     * popup) to see a normalised range.
+     */
+    setStartText(text: string): Promise<void>;
+    /** Type a date into the end field — see {@link setStartText} on ordering. */
+    setEndText(text: string): Promise<void>;
+    /** Empty both fields, which clears the range. Neither end has a clear button. */
+    clear(): Promise<void>;
+    /** Whether the picker refuses interaction. */
+    isDisabled(): Promise<boolean>;
+    /**
+     * Whether the fields refuse typing. Stricter than `<wr-date-picker>`: a
+     * read-only range picker also refuses to open, since two fields over one
+     * calendar leaves no reading of "untypeable" that still lets the grid rewrite
+     * both ends.
+     */
+    isReadonly(): Promise<boolean>;
+    /** Move focus to one field. */
+    focus(end: End): Promise<void>;
+    /**
+     * Blur one field. This is the moment an out-of-order range is put back in
+     * order, and — when focus leaves the control rather than hopping to the other
+     * end — the moment `touch` is emitted.
+     */
+    blur(end: End): Promise<void>;
+    /** Whether one field currently has focus. */
+    isFocused(end: End): Promise<boolean>;
+    /**
+     * One end's time stepper as `HH:MM`, plus `:SS` when `showSeconds` is on and
+     * ` AM`/` PM` in 12-hour mode. `datetime` mode only.
+     */
+    getTime(end: End): Promise<string>;
+    /** Type into one end's time stepper. Omitted fields are left alone. */
+    setTime(end: End, fields: WrDatePickerTimeFields): Promise<void>;
+    /** Click one of an end's ▲ / ▼ buttons. Minutes and seconds move by `step`. */
+    stepTime(end: End, unit: 'hours' | 'minutes' | 'seconds', direction: 1 | -1): Promise<void>;
+    /** Flip one end between AM and PM. Throws in 24-hour mode, which has no such control. */
+    toggleMeridiem(end: End): Promise<void>;
+    private type;
+    /** The two fields are addressed by position, which is the order they render in. */
+    private field;
+    /**
+     * One end's stepper. Both are mounted together in `datetime` mode, start first —
+     * the group labels are localized, so position is the addressable thing.
+     */
+    private timePanel;
+}
+
+export { WrDatePickerDayHarness, WrDatePickerHarness, WrDateRangePickerHarness };
+export type { WrDatePickerDayHarnessFilters, WrDatePickerHarnessFilters, WrDatePickerTimeFields, WrDateRangePickerHarnessFilters };

package/types/ngwr-date-picker.d.ts

@@ -135,6 +135,10 @@ declare class WrDatePicker implements FormValueControl<Date | null> {
     /** Live calendar ref while the date popover is open — lets the panel track
      * the typed value in real time (not just on reopen). */
     private readonly dateRef;
+    private readonly timeRef;
+    private readonly dateTimeRef;
+    /** The last value an open panel handed us, so the live push never echoes it back. */
+    private lastFromPanel;
     /** Last value we pushed into the model ourselves — lets the sync effect
      * skip the echo of our own edits (so a live keystroke's raw text is never
      * reformatted mid-type). */

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

@@ -0,0 +1,79 @@
+import { BaseHarnessFilters, ContentContainerComponentHarness, 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 open dialog a harness query matches. */
+interface WrDialogHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the dialog's `[wrDialogTitle]` text — a string is an exact match, a
+     * RegExp is tested. A dialog with no title never matches.
+     */
+    readonly title?: 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 a dialog opened with `WrDialog.open()`.
+ *
+ * A dialog is never inside the fixture — `WrDialog` attaches it to the overlay
+ * container — so load this from `TestbedHarnessEnvironment.documentRootLoader()`
+ * rather than from `loader()`. The harness is a CONTENT CONTAINER, which is what
+ * makes the interesting assertions possible: the buttons and fields it holds are
+ * the consumer's own components, so `dialog.getHarness(WrButtonHarness…)` reads
+ * them without the spec ever touching the overlay.
+ *
+ * @example
+ * ```ts
+ * const rootLoader = TestbedHarnessEnvironment.documentRootLoader(fixture);
+ * const dialog = await rootLoader.getHarness(WrDialogHarness);
+ *
+ * expect(await dialog.getTitleText()).toBe('Delete this item?');
+ * await (await dialog.getHarness(WrButtonHarness.with({ text: 'Delete' }))).click();
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrDialogHarness extends ContentContainerComponentHarness {
+    /** The overlay panel `WrDialog` creates. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — useful when two dialogs are stacked. */
+    static with(options?: WrDialogHarnessFilters): HarnessPredicate<WrDialogHarness>;
+    /** The `[wrDialogTitle]` text, or `null` when the dialog has no title. */
+    getTitleText(): Promise<string | null>;
+    /** The `[wrDialogContent]` text, or `null` when the dialog projects no content region. */
+    getContentText(): Promise<string | null>;
+    /**
+     * The role and modality the dialog announces.
+     *
+     * Worth asserting rather than assuming: `WrDialog` sets these on the OVERLAY
+     * element, not on the component it renders, so a consumer looking for them on
+     * their own host would not find them.
+     */
+    getRole(): Promise<string | null>;
+    /** Whether the dialog is marked `aria-modal`. */
+    isModal(): Promise<boolean>;
+    /** Whether the built-in dismiss button is present (`closable`, the default). */
+    isClosable(): Promise<boolean>;
+    /** The dismiss button's accessible name — the string a screen reader reads out. */
+    getCloseLabel(): Promise<string | null>;
+    /** Click the built-in dismiss button. Throws when the dialog was opened `closable: false`. */
+    close(): Promise<void>;
+    /** Press Escape. A dialog opened `closeOnEscape: false` ignores it — assert, do not assume. */
+    sendEscape(): Promise<void>;
+    /** Whether focus is currently somewhere inside the dialog, where the trap should keep it. */
+    isFocusTrapped(): Promise<boolean>;
+}
+
+export { WrDialogHarness };
+export type { WrDialogHarnessFilters };

package/types/ngwr-directives.d.ts

@@ -85,7 +85,16 @@ declare class WrCopyToClipboard {
     private readonly doc;
     /** @internal */
     protected onClick(): Promise<void>;
-    /** Legacy clipboard write — hidden textarea + execCommand('copy'). */
+    /**
+     * Legacy clipboard write — hidden textarea + `execCommand('copy')`.
+     *
+     * Two things this has to get right beyond writing the text. `execCommand`
+     * REPORTS refusal rather than throwing it: a document without focus hands back
+     * `false` and copies nothing, so ignoring the return value shows a "Copied!"
+     * toast over an unchanged clipboard. And selecting the textarea moves focus
+     * into it, so removing the node afterwards drops focus on `<body>` — the user's
+     * next Tab restarts from the top of the page, on every copy.
+     */
     private fallback;
     static ɵfac: i0.ɵɵFactoryDeclaration<WrCopyToClipboard, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<WrCopyToClipboard, "[wrCopyToClipboard]", never, { "wrCopyToClipboard": { "alias": "wrCopyToClipboard"; "required": true; "isSignal": true; }; }, { "copied": "copied"; "copyFailed": "copyFailed"; }, never, never, true, never>;

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

@@ -22,6 +22,13 @@ interface WrDonutSegment {
  */
 declare class WrDonutChart {
     readonly segments: _angular_core.InputSignal<readonly WrDonutSegment[]>;
+    /**
+     * Accessible name of the chart. The ring is `aria-hidden` and the legend is optional,
+     * so with `showLegend: false` this is the only thing a screen reader gets. Falls back
+     * to `donutChart.label`.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly resolvedAriaLabel: _angular_core.Signal<string>;
     /** Diameter in CSS pixels. @default 200 */
     readonly size: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Inner-ring thickness as a percent of radius (0–100). `0` = solid pie. @default 30 */
@@ -46,7 +53,7 @@ declare class WrDonutChart {
     /** SVG path for one donut slice using outer and inner arcs. */
     private arcPath;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrDonutChart, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrDonutChart, "wr-donut-chart", never, { "segments": { "alias": "segments"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "thickness": { "alias": "thickness"; "required": false; "isSignal": true; }; "showLegend": { "alias": "showLegend"; "required": false; "isSignal": true; }; "centerValue": { "alias": "centerValue"; "required": false; "isSignal": true; }; "centerLabel": { "alias": "centerLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrDonutChart, "wr-donut-chart", never, { "segments": { "alias": "segments"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "thickness": { "alias": "thickness"; "required": false; "isSignal": true; }; "showLegend": { "alias": "showLegend"; "required": false; "isSignal": true; }; "centerValue": { "alias": "centerValue"; "required": false; "isSignal": true; }; "centerLabel": { "alias": "centerLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { WrDonutChart };