ngwr 10.2.0 → 11.0.0

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

@@ -0,0 +1,392 @@
+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-cascader>` a harness query matches. */
+interface WrCascaderHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the trigger's displayed value — the selected labels joined by the
+     * `separator`, e.g. `'Europe / Germany / Berlin'`. A string is an exact match,
+     * a RegExp is tested. A cascader with nothing selected shows its placeholder
+     * and matches `''`.
+     */
+    readonly text?: string | RegExp;
+    /** Match the placeholder, which only shows while nothing is selected. */
+    readonly placeholder?: string | RegExp;
+    /** Match only enabled (`false`) or only disabled (`true`) cascaders. */
+    readonly disabled?: boolean;
+    /** Match only open (`true`) or only closed (`false`) cascaders. */
+    readonly open?: boolean;
+}
+/** Narrows which column of an open cascader panel a harness query matches. */
+interface WrCascaderColumnHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match a column that offers an option with this label — the way to ask for
+     * "the level Germany lives in" without counting columns. A string is an exact
+     * match, a RegExp is tested.
+     */
+    readonly optionText?: string | RegExp;
+}
+/** Narrows which option inside a cascader column a harness query matches. */
+interface WrCascaderOptionHarnessFilters extends BaseHarnessFilters {
+    /** Match the option's label — a string is an exact match, a RegExp is tested. */
+    readonly text?: string | RegExp;
+    /** Match only enabled (`false`) or only disabled (`true`) options. */
+    readonly disabled?: boolean;
+    /** Match only the expanded option of its column (`true`), or only the rest (`false`). */
+    readonly active?: boolean;
+    /** Match only branches (`true`) or only leaves (`false`). */
+    readonly hasChildren?: 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 option inside a `<wr-cascader>` column.
+ *
+ * An option is either a BRANCH (it has children, so clicking it opens the next
+ * column) or a LEAF (clicking it commits the whole path and closes the panel).
+ * {@link hasChildren} is the only way to tell them apart, and it reads the
+ * chevron the template draws for branches — the option carries no
+ * `aria-haspopup` / `aria-expanded`, so a screen-reader user is told nothing
+ * about a branch either. Reported here rather than papered over.
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrCascaderOptionHarness extends ComponentHarness {
+    /** The `<li role="menuitem">` a column renders per option. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrCascaderOptionHarnessFilters): HarnessPredicate<WrCascaderOptionHarness>;
+    /** The option's label, trimmed. The branch chevron contributes no text. */
+    getText(): Promise<string>;
+    /** The role the option announces — `menuitem`. */
+    getRole(): Promise<string | null>;
+    /** Whether the option refuses selection, from the state a screen reader is given. */
+    isDisabled(): Promise<boolean>;
+    /**
+     * Whether this is the option its column is currently drilled into — the one
+     * whose children the column to the right is showing, or the committed segment
+     * at this level.
+     *
+     * Read from the `--active` modifier because nothing else says it: the option
+     * has no `aria-selected` and no `aria-expanded`, so the class is both the
+     * whole visual answer and the only one available.
+     */
+    isActive(): Promise<boolean>;
+    /** Whether the option opens a deeper level rather than ending the path. */
+    hasChildren(): Promise<boolean>;
+    /**
+     * The option's tab index — `0` for every enabled option, `-1` for a disabled
+     * one.
+     *
+     * Worth asking: a cascader column is NOT a roving-cursor listbox. Every
+     * enabled option is its own tab stop, in every column, which is the documented
+     * reason virtual scrolling is deferred for this component — there is no
+     * container-owned arrow-nav model to hang a window off.
+     *
+     * Read as the element's `tabIndex` PROPERTY rather than the attribute, so an
+     * option that carried no `tabindex` at all answers `-1` — what the DOM says of a
+     * bare `<li>` — instead of a made-up `0` that would report an unfocusable option
+     * as a tab stop if this component ever moved to a roving cursor.
+     */
+    getTabIndex(): Promise<number>;
+    /**
+     * Click the option: a branch opens its children to the right, a leaf commits
+     * the path and closes the panel.
+     *
+     * A disabled option is clickable here on purpose — the component refuses it in
+     * its own handler rather than through `pointer-events`, so the click a spec
+     * dispatches is exactly as ineffective as one in a browser.
+     */
+    click(): Promise<void>;
+    /**
+     * Activate the option from the keyboard (Enter; Space is bound to the same
+     * handler).
+     *
+     * This is the component's entire keyboard model — the columns bind
+     * `keydown.enter` / `keydown.space` per option and nothing else, so there are
+     * no arrow keys to walk levels with. A keyboard user reaches the option they
+     * want with Tab and presses Enter — and Tab is a long way round: the panel is a
+     * portal in the overlay container at the end of the document, and nothing moves
+     * focus into it on open, so the first option is not the next stop after the
+     * trigger.
+     */
+    selectByKeyboard(): Promise<void>;
+    /**
+     * Move the pointer onto the option.
+     *
+     * Deliberately does NOT expand a branch: this cascader drills down on CLICK
+     * only, unlike the hover-to-expand cascaders elsewhere. Kept because a spec
+     * may want to pin that, and because the option's hover tint is styled.
+     */
+    hover(): Promise<void>;
+    /** Move keyboard focus to the option. */
+    focus(): Promise<void>;
+    /** Whether the option holds keyboard 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 one COLUMN of an open `<wr-cascader>` panel.
+ *
+ * A column is a level of the tree: column 0 holds the root options, and each
+ * further column holds the children of the active option in the column before
+ * it. Which columns exist is therefore a function of what is expanded — the
+ * relationship this harness exists to let a spec assert. Column 0 is always
+ * there; a column only appears once there are children to put in it, so a leaf
+ * adds none.
+ *
+ * @example
+ * ```ts
+ * const [countries, cities] = await cascader.getColumns();
+ *
+ * expect(await countries.getActiveOptionText()).toBe('Germany');
+ * expect(await cities.getOptionLabels()).toEqual(['Berlin']);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrCascaderColumnHarness extends ComponentHarness {
+    /** The `<ul role="menu">` the panel renders per level. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrCascaderColumnHarnessFilters): HarnessPredicate<WrCascaderColumnHarness>;
+    /** The role the column announces — `menu`. */
+    getRole(): Promise<string | null>;
+    /** The options this level offers, in order. */
+    getOptions(filters?: WrCascaderOptionHarnessFilters): Promise<WrCascaderOptionHarness[]>;
+    /** The labels this level offers, in order. */
+    getOptionLabels(): Promise<string[]>;
+    /**
+     * The first option matching the filters.
+     *
+     * Throws rather than answering `null`, and names what the column does offer:
+     * a missing option here almost always means the level is not the one the spec
+     * thought it was, and that is far easier to see with the alternatives listed.
+     */
+    getOption(filters: WrCascaderOptionHarnessFilters): Promise<WrCascaderOptionHarness>;
+    /** The option this level is drilled into, or `null` when nothing here is expanded. */
+    getActiveOption(): Promise<WrCascaderOptionHarness | null>;
+    /** The label of the option this level is drilled into, or `null`. */
+    getActiveOptionText(): Promise<string | null>;
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/**
+ * Test harness for `<wr-cascader>` — the trigger, and the panel of COLUMNS it
+ * opens. Root of a small family: {@link WrCascaderColumnHarness} for one level,
+ * `WrCascaderOptionHarness` for one option in it.
+ *
+ * A cascader is not a select with extra steps. Its value is the whole PATH from
+ * root to leaf (`['eu', 'de', 'ber']`, not `'ber'`), and the panel shows one
+ * column per level, so which columns exist depends on what is expanded — column
+ * 0 is the roots, and every further column holds the children of the active
+ * option in the column to its left. That relationship is the component, so it is
+ * what {@link getColumns} and {@link getColumnLabels} are for.
+ *
+ * The panel is NOT inside the cascader: it is a template portal in the overlay
+ * container, a sibling of the whole app. Every read of it goes through the
+ * document root scoped by the `aria-controls` id the trigger publishes, so two
+ * cascaders on one page can never answer with each other's columns.
+ *
+ * @example
+ * ```ts
+ * const cascader = await loader.getHarness(WrCascaderHarness);
+ *
+ * await cascader.selectPath(['Europe', 'Germany', 'Berlin']);
+ *
+ * expect(await cascader.getValueText()).toBe('Europe / Germany / Berlin');
+ * expect(await cascader.isOpen()).toBe(false);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrCascaderHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query. */
+    static with(options?: WrCascaderHarnessFilters): HarnessPredicate<WrCascaderHarness>;
+    private readonly trigger;
+    /**
+     * Whether the panel is showing.
+     *
+     * From the trigger's `aria-expanded` rather than the host's `--open` class:
+     * both exist, and the ARIA state is the one a screen-reader user is told.
+     */
+    isOpen(): Promise<boolean>;
+    /**
+     * Whether the cascader refuses interaction.
+     *
+     * From the trigger's native `disabled`, which is what actually stops a pointer
+     * and what assistive tech reports; the host's `--disabled` class only mirrors
+     * it for styling.
+     */
+    isDisabled(): Promise<boolean>;
+    /**
+     * What the trigger displays as the selection: the labels of the whole path
+     * joined by the `separator` (`'Europe / Germany / Berlin'` by default), or `''`
+     * while nothing is selected and the placeholder is showing.
+     *
+     * The joined string is all the DOM has — the separator is not published
+     * anywhere on its own, so the harness will not pretend it can split the path
+     * back apart. Assert against the bound value, or against
+     * {@link getActiveTrail} while the panel is open, when the segments matter.
+     */
+    getValueText(): Promise<string>;
+    /**
+     * The placeholder, or `null` when a selection is hiding it.
+     *
+     * `''` is a real answer, not an absence: a cascader with no `placeholder` still
+     * renders the element while unselected.
+     */
+    getPlaceholder(): Promise<string | null>;
+    /**
+     * The trigger's accessible name — the `ariaLabel` input, falling back to the
+     * placeholder and then to the i18n catalog, because a `role="combobox"` with
+     * nothing selected and no placeholder would otherwise have no name at all.
+     */
+    getAccessibleName(): Promise<string | null>;
+    /** The kind of popup the trigger promises via `aria-haspopup` — `menu`. */
+    getPopupRole(): Promise<string | null>;
+    /** The role the panel announces — `menu`, matching what the trigger promised. */
+    getPanelRole(): Promise<string | null>;
+    /**
+     * The id the trigger publishes as `aria-controls`.
+     *
+     * Published unconditionally, open or closed — so while the panel is closed this
+     * id resolves to nothing in the document. Exposed so a spec can pin that
+     * (dangling or not) rather than have the harness quietly decide for it; every
+     * panel read goes through the same id but refuses to run while closed.
+     */
+    getPanelId(): Promise<string | null>;
+    /**
+     * Whether the panel now in the overlay is the one this trigger claims to
+     * control — `aria-controls` resolving to a real element that carries that id.
+     *
+     * With several cascaders on a page it is also the check that the reference lands
+     * on THIS instance's panel rather than a neighbour's: the overlay container is
+     * shared, so panels sit side by side in it with nothing but their ids to tell
+     * them apart.
+     */
+    isPanelWiredToTrigger(): Promise<boolean>;
+    /**
+     * Open the panel.
+     *
+     * Clicks the trigger, because that is the only gesture the component binds. The
+     * trigger is a native `<button>`, so a browser turns Enter / Space on it into
+     * the same click — there is no separate keyboard route to model here, and jsdom
+     * does not synthesise button activation from a key, so an `openByKeyboard()`
+     * would only be able to lie.
+     */
+    open(): Promise<void>;
+    /**
+     * Close the panel with Escape. A closed cascader is left alone.
+     *
+     * Escape reaches the panel through the CDK's keyboard dispatcher rather than
+     * through the DOM tree, which is why sending it to the trigger works even
+     * though the panel is somewhere else entirely.
+     */
+    close(): Promise<void>;
+    /** Click the trigger once, whatever that does — opens a closed panel, closes an open one. */
+    clickTrigger(): Promise<void>;
+    /**
+     * The columns of the open panel, left to right: column 0 is the root options,
+     * and each further one holds the children of its neighbour's active option.
+     *
+     * Throws while the panel is closed. The columns do not exist anywhere until the
+     * portal is attached, and an empty array reads like a panel that rendered
+     * nothing — a confusing failure three lines later instead of here.
+     */
+    getColumns(filters?: WrCascaderColumnHarnessFilters): Promise<WrCascaderColumnHarness[]>;
+    /** How many levels the panel is currently showing. */
+    getColumnCount(): Promise<number>;
+    /**
+     * One column by its 0-based level. Throws when the level is not showing, which
+     * is the interesting failure: it means the option before it has no children, or
+     * has not been expanded yet.
+     */
+    getColumn(index: number): Promise<WrCascaderColumnHarness>;
+    /** The labels offered by every column, outer array left to right. */
+    getColumnLabels(): Promise<string[][]>;
+    /**
+     * The expanded trail — the label of the active option in each column, root
+     * first.
+     *
+     * This is the panel's own idea of where the user is, which is NOT always the
+     * committed value: drilling into a branch moves the trail without committing
+     * anything unless `changeOnSelect` is on. Once a leaf is picked the two agree,
+     * and this is the only place the path's segments exist separately in the DOM.
+     */
+    getActiveTrail(): Promise<string[]>;
+    /**
+     * The first option matching the filters, anywhere in the panel. Throws when
+     * nothing matches, naming what is on offer.
+     *
+     * Use {@link getColumn} when the level matters — the same label can legitimately
+     * appear at more than one level.
+     */
+    getOption(filters: WrCascaderOptionHarnessFilters): Promise<WrCascaderOptionHarness>;
+    /**
+     * Walk a path by label, opening the panel first if needed: each label is
+     * clicked in the column it belongs to, so `['Europe', 'Germany', 'Berlin']`
+     * drills two levels and commits the third.
+     *
+     * Clicking is the only way down — this cascader does not expand on hover, so
+     * neither does the harness. A path that ends on a BRANCH just leaves that
+     * branch expanded: the component commits nothing on the way down unless
+     * `changeOnSelect` is on, and only a leaf closes the panel.
+     */
+    selectPath(labels: readonly string[]): Promise<void>;
+    /**
+     * Click the clear (×) control on the trigger.
+     *
+     * Throws when there is none, and both reasons are worth failing on: the
+     * cascader is not `clearable`, or nothing is selected — the control is not
+     * rendered at all in either case (nor while disabled).
+     */
+    clear(): Promise<void>;
+    /** Move keyboard focus to the trigger. */
+    focus(): Promise<void>;
+    /** Take focus off the trigger, which is what makes a bound form field touched. */
+    blur(): Promise<void>;
+    /** Whether the trigger holds keyboard focus. */
+    isFocused(): Promise<boolean>;
+    /** This cascader's panel element in the overlay — the single-element scoped read. */
+    private panel;
+    /**
+     * A loader scoped to THIS cascader's panel — the list scoped read.
+     *
+     * Scoped by the published id rather than by `.wr-cascader-panel`: the overlay
+     * container is shared with every other overlay in the app, so a bare class
+     * query would answer with whichever panel happened to be open.
+     */
+    private panelLoader;
+    /** The panel id, refusing to hand it out while there is no panel to find. */
+    private panelId;
+}
+
+export { WrCascaderColumnHarness, WrCascaderHarness, WrCascaderOptionHarness };
+export type { WrCascaderColumnHarnessFilters, WrCascaderHarnessFilters, WrCascaderOptionHarnessFilters };

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

@@ -0,0 +1,77 @@
+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-checkbox>` a harness query matches. */
+interface WrCheckboxHarnessFilters extends BaseHarnessFilters {
+    /** Match the projected label — a string is an exact match, a RegExp is tested. */
+    readonly label?: string | RegExp;
+    /** Match only ticked (`true`) or only unticked (`false`) boxes. */
+    readonly checked?: boolean;
+    /** Match only enabled (`false`) or only disabled (`true`) boxes. */
+    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-checkbox>`.
+ *
+ * The visible box is a `<span>` the stylesheet paints; the state lives on a real
+ * `<input type="checkbox">` inside the label, and that is what this harness reads
+ * and clicks. Toggling through the input rather than the painted box is what makes
+ * `check()` behave the way a user does — the label is what a click lands on.
+ *
+ * Note `checkboxValue` versus `value`: a checkbox's group identity is
+ * `checkboxValue`, because `FormCheckboxControl` reserves `value` for the form
+ * value. {@link getCheckboxValue} reads the identity.
+ *
+ * @example
+ * ```ts
+ * const terms = await loader.getHarness(WrCheckboxHarness.with({ label: 'I agree' }));
+ * await terms.check();
+ * expect(await terms.isChecked()).toBe(true);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrCheckboxHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrCheckboxHarnessFilters): HarnessPredicate<WrCheckboxHarness>;
+    private readonly input;
+    /** The projected label text, trimmed. */
+    getLabel(): Promise<string>;
+    isChecked(): Promise<boolean>;
+    /**
+     * Whether the box is in its third state.
+     *
+     * `indeterminate` is a DOM PROPERTY, not an attribute — reading the attribute
+     * would report `null` for a box that is visibly dashed.
+     */
+    isIndeterminate(): Promise<boolean>;
+    isDisabled(): Promise<boolean>;
+    /** The group identity — `checkboxValue`, not the form value. */
+    getCheckboxValue(): Promise<string | null>;
+    /** Flip the box. A disabled checkbox does not move; assert rather than assume. */
+    toggle(): Promise<void>;
+    /** Tick the box if it is not already ticked. */
+    check(): Promise<void>;
+    /** Untick the box if it is ticked. */
+    uncheck(): Promise<void>;
+    focus(): Promise<void>;
+    isFocused(): Promise<boolean>;
+}
+
+export { WrCheckboxHarness };
+export type { WrCheckboxHarnessFilters };

package/types/ngwr-checkbox.d.ts

@@ -70,8 +70,13 @@ declare class WrCheckbox implements FormCheckboxControl {
      * @default false
      */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
-    /** Control size — shares the `--wr-control-*` contract. @default 'md' */
-    readonly size: _angular_core.InputSignal<WrCheckboxSize>;
+    /**
+     * Control size — shares the `--wr-control-*` contract. Unset falls back to the
+     * `checkbox.size` app default from `provideWrConfig()`. @default 'md'
+     */
+    readonly size: _angular_core.InputSignal<WrCheckboxSize | null>;
+    /** `size`, then the app config, then `md`. @internal */
+    protected readonly resolvedSize: _angular_core.Signal<"sm" | "md" | "lg">;
     /**
      * Optional icon name rendered inside the box when checked, in place of the
      * default checkmark. Use any registered NGWR icon.

package/types/ngwr-clipboard.d.ts

@@ -54,7 +54,14 @@ declare class WrClipboard {
      * return `'unsupported'` when the capability genuinely isn't there.
      */
     permission(name: 'read' | 'write'): Promise<WrClipboardPermission>;
-    /** Hidden-textarea + `execCommand('copy')` write. Synchronous, no permissions. */
+    /**
+     * Hidden-textarea + `execCommand('copy')` write. Synchronous, no permissions.
+     *
+     * `select()` takes focus, and the textarea is removed a moment later — so
+     * without putting focus back, every copy on a non-secure origin (plain
+     * `http://`, which is exactly where the async clipboard is missing) leaves
+     * focus on `<body>` and the user's next Tab restarts from the top of the page.
+     */
     private legacyWrite;
     static ɵfac: i0.ɵɵFactoryDeclaration<WrClipboard, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<WrClipboard>;