ngwr 10.2.0 → 11.0.0

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

@@ -0,0 +1,290 @@
+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-collapse>` a harness query matches. */
+interface WrCollapseHarnessFilters extends BaseHarnessFilters {
+    /** Match the panel's header text — a string is an exact match, a RegExp is tested. */
+    readonly title?: string | RegExp;
+    /**
+     * Match only open (`true`) or only closed (`false`) panels, as the HEADER announces
+     * it — see `WrCollapseHarness.isOpen`, which is where the animated height is
+     * explained away.
+     */
+    readonly open?: boolean;
+    /** Match only enabled (`false`) or only disabled (`true`) panels. */
+    readonly disabled?: boolean;
+}
+/** Narrows which `<wr-collapse-group>` / `<wr-accordion>` a harness query matches. */
+interface WrCollapseGroupHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match a group holding a panel with this header text — the readable way to tell two
+     * groups on one page apart, a group having no name of its own. A string is an exact
+     * match, a RegExp is tested.
+     */
+    readonly panelTitle?: string | RegExp;
+    /**
+     * Match a group whose OPEN panel has this header text; a group with everything closed
+     * matches nothing. In accordion mode there is at most one open panel, which is what
+     * makes this a way to address a group rather than a coin toss.
+     */
+    readonly openPanelTitle?: 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 one `<wr-collapse>` — a disclosure: a header button, and the region
+ * it opens. {@link WrCollapseGroupHarness} is the container several of them sit in.
+ *
+ * Open and closed are read from the header's `aria-expanded`, never from the panel's
+ * size, and that is not merely a jsdom workaround. The body animates through
+ * `grid-template-rows: 0fr → 1fr`, so a measured box answers with whatever frame the
+ * transition happens to be on; a unit test has no layout at all, which makes every box
+ * 0×0 and every such answer wrong in the same direction. The attribute is also the only
+ * thing a screen-reader user gets — a panel that slides open without flipping it is
+ * closed as far as they are concerned.
+ *
+ * The body stays in the DOM while the panel is closed. It has to: there would be no
+ * height to animate otherwise. So its text is READABLE from a spec long before it is
+ * visible on screen, which is why {@link getContentText} refuses to answer for a closed
+ * panel instead of handing back invisible text, and why {@link isContentHidden} exists
+ * to assert that a closed panel really is out of reach.
+ *
+ * The region itself is a plain `<div>` — the component gives it no `role="region"` — so
+ * `aria-expanded` plus `aria-controls` is the whole of the wiring, and
+ * {@link isRegionBound} is how a spec checks it still points at this panel's own body.
+ *
+ * @example
+ * ```ts
+ * const loader = TestbedHarnessEnvironment.loader(fixture);
+ * const shipping = await loader.getHarness(WrCollapseHarness.with({ title: 'Shipping' }));
+ *
+ * await shipping.open();
+ * expect(await shipping.getContentText()).toContain('Ships Monday');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrCollapseHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrCollapseHarnessFilters): HarnessPredicate<WrCollapseHarness>;
+    private readonly header;
+    private readonly body;
+    /**
+     * The header text, trimmed.
+     *
+     * Read from `.wr-collapse__title` rather than from the header button. Reading the
+     * button would return the same string today — the chevron beside the title is an
+     * `<svg>`, and an `<svg>` contributes no text — but the title element is the thing that
+     * holds the name, so an icon that ever grows a `<text>` node or a label, or a badge
+     * added next to the title, cannot leak into it.
+     */
+    getTitle(): Promise<string>;
+    /**
+     * Whether the panel is open, from the header's `aria-expanded`.
+     *
+     * The `wr-collapse--open` modifier on the host is equally public and says the same
+     * thing today, but the attribute is the one a screen reader acts on: a panel that
+     * looks open while announcing `false` is the bug worth catching, and reading the class
+     * would agree with the animation and miss it.
+     */
+    isOpen(): Promise<boolean>;
+    /**
+     * Whether the panel refuses interaction.
+     *
+     * From the header's own `disabled` property — the thing that actually turns a click
+     * away, and what the CDK consults before dispatching one — rather than from the
+     * `wr-collapse--disabled` modifier the host also carries. Both are public, but the
+     * class is styling: a panel could lose it and still refuse every click, and what a
+     * spec wants to know is whether the control is inert.
+     */
+    isDisabled(): Promise<boolean>;
+    /**
+     * The id the header's `aria-controls` names, or `null` when it names nothing.
+     *
+     * Per-instance and generated, so a spec cannot predict it — what it can do is check
+     * that two panels do not share one, and {@link isRegionBound} does the rest.
+     */
+    getRegionId(): Promise<string | null>;
+    /**
+     * Whether the header points at THIS panel's body, and at nothing else on the page.
+     *
+     * Both halves matter, and neither is provable from the header alone. The id is
+     * resolved inside the host first, so a header naming a SIBLING panel's body — which
+     * resolves perfectly well from the document and would look correctly wired — fails
+     * here. Then it is counted across the document, because two bodies answering to one
+     * id hand every reference to whichever comes first, and the second panel's region
+     * becomes unreachable to anything that follows the reference.
+     */
+    isRegionBound(): Promise<boolean>;
+    /**
+     * Whether the region is hidden from assistive tech AND from the keyboard.
+     *
+     * Two attributes, because a closed panel needs both and they cover different people:
+     * `aria-hidden` keeps the content out of the screen reader's document, `inert` keeps
+     * Tab from landing on a link inside a panel nobody can see. The body is never removed
+     * from the DOM — the height animation needs it — so these are the only thing standing
+     * between a collapsed panel and a keyboard user, and losing either is invisible on
+     * screen.
+     *
+     * They are asserted together on purpose: this answers "is the closed content actually
+     * out of reach", and half of it is not.
+     */
+    isContentHidden(): Promise<boolean>;
+    /**
+     * The text of an OPEN panel's region, trimmed.
+     *
+     * Throws while the panel is closed rather than answering, because the body is still in
+     * the DOM and the text would come back exactly as it does when open — a spec asserting
+     * it would be pinning content the user cannot see, and would keep passing if the panel
+     * stopped opening at all.
+     */
+    getContentText(): Promise<string>;
+    /** Open the panel. An already-open one is left alone; a disabled one throws. */
+    open(): Promise<void>;
+    /** Close the panel. An already-closed one is left alone; a disabled one throws. */
+    close(): Promise<void>;
+    /**
+     * Click the header — the panel's entire interactive surface.
+     *
+     * A click rather than Enter / Space, and nothing is lost by it: the header is a native
+     * `<button>`, so a real keyboard activation is the BROWSER synthesising a click from
+     * the key press, and jsdom synthesises none. The click is dispatched onto the header
+     * itself, so it needs no coordinate and cannot miss in a test that has no layout.
+     *
+     * A disabled panel ignores this and stays as it was, twice over: the CDK withholds the
+     * `click` from an element carrying `disabled`, and the component checks `disabled`
+     * again inside its own toggle. Assert rather than assume, or reach for {@link open} /
+     * {@link close}, which say so.
+     */
+    toggle(): Promise<void>;
+    /**
+     * Move keyboard focus to the header — the only focusable element the component itself
+     * renders. Projected content can of course hold its own (which is why a closed panel is
+     * `inert`), but that belongs to the consumer, not to this harness.
+     */
+    focus(): Promise<void>;
+    /** Whether the header 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-collapse-group>` and `<wr-accordion>` — the container a set of
+ * {@link WrCollapseHarness} panels sits in, matched in both of its element shapes.
+ *
+ * There is deliberately no `isAccordion()`, and the reason is worth knowing before a
+ * spec goes looking for one: single-open behaviour is not written down anywhere on the
+ * page. `<wr-accordion>` carries the marker class `wr-collapse-group--accordion`, but
+ * `<wr-collapse-group [accordion]="true">` enforces exactly the same rule and carries
+ * nothing — a bound input reaches the component without touching the DOM, and even the
+ * literal `accordion` attribute survives only because Angular leaves a static attribute
+ * alone. So the class answers "which element did the template use", not "does this group
+ * close siblings", and a harness reporting it would call the group form false. Assert the
+ * BEHAVIOUR instead: open two panels and read {@link getOpenTitles} — the assertion that
+ * would catch a broken accordion anyway.
+ *
+ * A collapse group is also not a composite widget. Every header is a native `<button>`
+ * in the normal tab order, with no roving `tabindex` and no arrow-key navigation (the
+ * APG lists both as optional for an accordion), so there is no "active" panel to tell
+ * apart from the open one — {@link getFocusedTitle} is the only cursor there is.
+ *
+ * @example
+ * ```ts
+ * const settings = await loader.getHarness(WrCollapseGroupHarness.with({ panelTitle: 'Profile' }));
+ *
+ * await settings.openPanel({ title: 'Security' });
+ * expect(await settings.getOpenTitles()).toEqual(['Security']);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrCollapseGroupHarness extends ComponentHarness {
+    /** Both shapes the container ships in: the plain group, and the always-accordion one. */
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrCollapseGroupHarnessFilters): HarnessPredicate<WrCollapseGroupHarness>;
+    /**
+     * The group's panels, in DOM order.
+     *
+     * Every `<wr-collapse>` inside the host, which includes one nested in another panel's
+     * content and every panel of a nested group — the group scopes no more tightly than
+     * the DOM does, and a nested accordion's children are still descendants of this one.
+     */
+    getPanels(filters?: WrCollapseHarnessFilters): Promise<WrCollapseHarness[]>;
+    /** The header text of every panel, in DOM order. */
+    getPanelTitles(): Promise<string[]>;
+    /** The first panel matching the filters, or a failure naming the panels that exist. */
+    getPanel(filters: WrCollapseHarnessFilters): Promise<WrCollapseHarness>;
+    /**
+     * The panel at a 0-based position in DOM order — the other half of "by text or by
+     * index", and the only way to address a panel whose title is not unique.
+     *
+     * Throws for an index past the end rather than resolving to nothing, and says how many
+     * panels there are: an out-of-range index is a mistake in the spec, and a `undefined`
+     * handed back would surface three lines later as a failure about something else.
+     */
+    getPanelAt(index: number): Promise<WrCollapseHarness>;
+    /** The panels that are open, in DOM order. In accordion mode there is at most one. */
+    getOpenPanels(): Promise<WrCollapseHarness[]>;
+    /**
+     * The header text of every open panel, in DOM order.
+     *
+     * The assertion an accordion is worth pinning with: opening a second panel has to leave
+     * this a list of ONE, and it reads the state from each header's `aria-expanded`, so a
+     * sibling that collapsed on screen while still announcing itself open fails here.
+     */
+    getOpenTitles(): Promise<string[]>;
+    /**
+     * Open the first panel matching the filters.
+     *
+     * In accordion mode this is also what CLOSES the siblings — the group is told by the
+     * panel that opened, not by the click — so a spec that opens two panels in a row is
+     * asserting the mode, and {@link getOpenTitles} is where the answer shows up. Throws
+     * when nothing matched, and again when the panel refused to open (it is disabled).
+     */
+    openPanel(filters: WrCollapseHarnessFilters): Promise<void>;
+    /** Close the first panel matching the filters. */
+    closePanel(filters: WrCollapseHarnessFilters): Promise<void>;
+    /**
+     * Close every open panel.
+     *
+     * The open panels are resolved first and then closed one at a time. Every click a
+     * harness makes already awaits its own change detection, so closing them concurrently
+     * would work too — this reads in the order a user would click, and keeps each failure
+     * attributable to the panel that caused it. A disabled panel that was opened through
+     * `[open]` cannot be closed from the page and throws — the same failure
+     * {@link WrCollapseHarness.close} reports, for the same reason.
+     */
+    closeAll(): Promise<void>;
+    /**
+     * The header text of the panel whose header holds focus, or `null` when focus is
+     * elsewhere.
+     *
+     * Every header is its own tab stop here, so this reports where focus actually IS
+     * rather than where the group would send it — there is no roving tab stop to diverge
+     * from.
+     */
+    getFocusedTitle(): Promise<string | null>;
+}
+
+export { WrCollapseGroupHarness, WrCollapseHarness };
+export type { WrCollapseGroupHarnessFilters, WrCollapseHarnessFilters };

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

@@ -156,12 +156,16 @@ declare function toHex(rgb: WrRgb, withAlpha?: boolean): string;
  * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
  */
 /**
- * Output format produced by `<wr-color-picker>` when emitting through its
- * `ControlValueAccessor`:
+ * Output format produced by `<wr-color-picker>` when it writes its `value`
+ * model. Each format has an opaque and a translucent spelling, picked by the
+ * picker's `alpha` input:
  *
- * - `hex`  — `#3969e2` or `#3969e2ff` when alpha is enabled
- * - `rgba` — `rgba(57, 105, 226, 0.5)`
- * - `hsla` — `hsla(220, 73%, 56%, 0.5)`
+ * - `hex`  — `#3969e2`, or `#3969e2ff` with alpha
+ * - `rgba` — `rgb(57, 105, 226)`, or `rgba(57, 105, 226, 0.5)` with alpha
+ * - `hsla` — `hsl(220, 73%, 56%)`, or `hsla(220, 73%, 56%, 0.5)` with alpha
+ *
+ * All three are also ACCEPTED on the way in, whichever one is set, so a
+ * `[(value)]` binding round-trips its own output.
  */
 type WrColorFormat = 'hex' | 'rgba' | 'hsla';
 
@@ -192,7 +196,10 @@ declare class WrColorPicker implements FormValueControl<string> {
     readonly alpha: _angular_core.InputSignalWithTransform<boolean, any>;
     /** Disable interaction. @default false */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
-    /** Output format produced by the control. @default 'hex' */
+    /**
+     * Format the control writes into `value`. See {@link WrColorFormat} — all
+     * three are accepted on the way in whichever one is set. @default 'hex'
+     */
     readonly format: _angular_core.InputSignal<WrColorFormat>;
     /** Preset hex colours rendered as a clickable row beneath the inputs. Empty = no row. @default [] */
     readonly swatches: _angular_core.InputSignal<readonly string[]>;
@@ -206,8 +213,10 @@ declare class WrColorPicker implements FormValueControl<string> {
     protected readonly a: _angular_core.WritableSignal<number>;
     /** RGB view of the current colour, computed lazily. */
     protected readonly rgb: _angular_core.Signal<WrRgb>;
-    /** Canonical hex (used by the input field and by drag emits). */
+    /** Canonical hex — what the HEX field shows, whatever `format` emits. */
     protected readonly hex: _angular_core.Signal<string>;
+    /** The colour as the consumer asked for it; this is what `value` receives. */
+    protected readonly formatted: _angular_core.Signal<string>;
     /** SV canvas background colour (full-saturation hue). */
     protected readonly hueCss: _angular_core.Signal<string>;
     /** RGB string used for the alpha-slider gradient. */
@@ -227,8 +236,8 @@ declare class WrColorPicker implements FormValueControl<string> {
     protected readonly alphaPercent: _angular_core.Signal<number>;
     protected readonly tabOptions: readonly WrSegmentedOption<Tab>[];
     protected readonly classes: _angular_core.Signal<string>;
-    /** Last hex we pushed into `value`; lets the sync effect ignore our own writes. */
-    private lastEmittedHex;
+    /** Last string we pushed into `value`; lets the sync effect ignore our own writes. */
+    private lastEmitted;
     constructor();
     protected onPointerDown(event: PointerEvent, surface: Edges): void;
     private updateFromEvent;
@@ -241,7 +250,7 @@ declare class WrColorPicker implements FormValueControl<string> {
     protected onHslChannel(channel: 'h' | 's' | 'l', event: Event): void;
     protected onAlphaPercent(event: Event): void;
     protected onSwatchClick(hex: string): void;
-    /** Push an RGB triple into the HSV source of truth (preserving the current alpha if the swap removes it). */
+    /** Push an RGB triple into the HSV source of truth. */
     private applyRgb;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrColorPicker, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrColorPicker, "wr-color-picker", never, { "alpha": { "alias": "alpha"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "swatches": { "alias": "swatches"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
@@ -290,7 +299,7 @@ declare class WrColorPickerTrigger {
     private readonly vcr;
     private readonly scrollStrategies;
     private readonly destroyRef;
-    private readonly isOpen;
+    protected readonly isOpen: _angular_core.WritableSignal<boolean>;
     private overlayRef;
     constructor();
     /** Toggle the picker. Open if closed, close if open. */