ngwr 10.2.1 → 11.0.0

package/fesm2022/ngwr-collapse-testing.mjs

@@ -0,0 +1,368 @@
+import { 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
+ */
+/**
+ * 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
+ */
+class WrCollapseHarness extends ComponentHarness {
+    static hostSelector = 'wr-collapse';
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options = {}) {
+        return new HarnessPredicate(WrCollapseHarness, options)
+            .addOption('title', options.title, (harness, title) => HarnessPredicate.stringMatches(harness.getTitle(), title))
+            .addOption('open', options.open, async (harness, open) => (await harness.isOpen()) === open)
+            .addOption('disabled', options.disabled, async (harness, disabled) => (await harness.isDisabled()) === disabled);
+    }
+    header = this.locatorFor('button.wr-collapse__header');
+    body = this.locatorFor('.wr-collapse__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.
+     */
+    async getTitle() {
+        return (await this.locatorFor('.wr-collapse__title')()).text();
+    }
+    /**
+     * 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.
+     */
+    async isOpen() {
+        return (await (await this.header()).getAttribute('aria-expanded')) === 'true';
+    }
+    /**
+     * 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.
+     */
+    async isDisabled() {
+        return (await this.header()).getProperty('disabled');
+    }
+    /**
+     * 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.
+     */
+    async getRegionId() {
+        return (await this.header()).getAttribute('aria-controls');
+    }
+    /**
+     * 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.
+     */
+    async isRegionBound() {
+        const id = await this.getRegionId();
+        if (id === null)
+            return false;
+        const own = await this.locatorForOptional(`.wr-collapse__body#${id}`)();
+        if (!own)
+            return false;
+        const everywhere = await this.documentRootLocatorFactory().locatorForAll(`#${id}`)();
+        return everywhere.length === 1;
+    }
+    /**
+     * 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.
+     */
+    async isContentHidden() {
+        const body = await this.body();
+        const hiddenFromAt = (await body.getAttribute('aria-hidden')) === 'true';
+        const inert = (await body.getAttribute('inert')) !== null;
+        return hiddenFromAt && inert;
+    }
+    /**
+     * 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.
+     */
+    async getContentText() {
+        if (!(await this.isOpen())) {
+            throw new Error(`WrCollapseHarness.getContentText(): "${await this.getTitle()}" is closed. Its content stays in the ` +
+                'DOM while collapsed — the body has to be there for the height to animate — so reading it now would ' +
+                'assert text nobody can see. Open the panel first, or ask isContentHidden().');
+        }
+        return (await this.locatorFor('.wr-collapse__inner')()).text();
+    }
+    /** Open the panel. An already-open one is left alone; a disabled one throws. */
+    async open() {
+        if (await this.isOpen())
+            return;
+        await this.toggle();
+        if (!(await this.isOpen())) {
+            throw new Error(`WrCollapseHarness.open(): "${await this.getTitle()}" did not open. A disabled panel refuses its own ` +
+                'header — the button carries `disabled`, and the component checks it again before toggling.');
+        }
+    }
+    /** Close the panel. An already-closed one is left alone; a disabled one throws. */
+    async close() {
+        if (!(await this.isOpen()))
+            return;
+        await this.toggle();
+        if (await this.isOpen()) {
+            throw new Error(`WrCollapseHarness.close(): "${await this.getTitle()}" did not close. A disabled panel that was opened ` +
+                'through `[open]` cannot be closed from the page at all: the toggle refuses while `disabled` is set, ' +
+                'whichever direction the click would have gone.');
+        }
+    }
+    /**
+     * 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.
+     */
+    async toggle() {
+        return (await this.header()).click();
+    }
+    /**
+     * 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.
+     */
+    async focus() {
+        return (await this.header()).focus();
+    }
+    /** Whether the header currently holds focus. */
+    async isFocused() {
+        return (await this.header()).isFocused();
+    }
+}
+
+/**
+ * @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
+ */
+class WrCollapseGroupHarness extends ComponentHarness {
+    /** Both shapes the container ships in: the plain group, and the always-accordion one. */
+    static hostSelector = 'wr-collapse-group, wr-accordion';
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options = {}) {
+        return new HarnessPredicate(WrCollapseGroupHarness, options)
+            .addOption('panelTitle', options.panelTitle, async (harness, title) => {
+            for (const panel of await harness.getPanelTitles()) {
+                if (await HarnessPredicate.stringMatches(panel, title))
+                    return true;
+            }
+            return false;
+        })
+            .addOption('openPanelTitle', options.openPanelTitle, async (harness, title) => {
+            for (const open of await harness.getOpenTitles()) {
+                if (await HarnessPredicate.stringMatches(open, title))
+                    return true;
+            }
+            return false;
+        });
+    }
+    /**
+     * 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.
+     */
+    async getPanels(filters = {}) {
+        return this.locatorForAll(WrCollapseHarness.with(filters))();
+    }
+    /** The header text of every panel, in DOM order. */
+    async getPanelTitles() {
+        const panels = await this.getPanels();
+        return Promise.all(panels.map(panel => panel.getTitle()));
+    }
+    /** The first panel matching the filters, or a failure naming the panels that exist. */
+    async getPanel(filters) {
+        const [panel] = await this.getPanels(filters);
+        if (!panel) {
+            throw new Error(`WrCollapseGroupHarness.getPanel(): no panel matched ${JSON.stringify(filters)}. This group holds: ` +
+                `${(await this.getPanelTitles()).join(', ')}.`);
+        }
+        return panel;
+    }
+    /**
+     * 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.
+     */
+    async getPanelAt(index) {
+        const panels = await this.getPanels();
+        const panel = panels[index];
+        if (!panel) {
+            throw new Error(`WrCollapseGroupHarness.getPanelAt(): index ${index} is out of range — this group holds ` +
+                `${panels.length} panel(s), so the last index is ${panels.length - 1}.`);
+        }
+        return panel;
+    }
+    /** The panels that are open, in DOM order. In accordion mode there is at most one. */
+    async getOpenPanels() {
+        return this.getPanels({ open: true });
+    }
+    /**
+     * 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.
+     */
+    async getOpenTitles() {
+        const open = await this.getOpenPanels();
+        return Promise.all(open.map(panel => panel.getTitle()));
+    }
+    /**
+     * 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).
+     */
+    async openPanel(filters) {
+        await (await this.getPanel(filters)).open();
+    }
+    /** Close the first panel matching the filters. */
+    async closePanel(filters) {
+        await (await this.getPanel(filters)).close();
+    }
+    /**
+     * 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.
+     */
+    async closeAll() {
+        for (const panel of await this.getOpenPanels()) {
+            await panel.close();
+        }
+    }
+    /**
+     * 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.
+     */
+    async getFocusedTitle() {
+        for (const panel of await this.getPanels()) {
+            if (await panel.isFocused())
+                return panel.getTitle();
+        }
+        return null;
+    }
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { WrCollapseGroupHarness, WrCollapseHarness };
+//# sourceMappingURL=ngwr-collapse-testing.mjs.map

package/fesm2022/ngwr-collapse-testing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ngwr-collapse-testing.mjs","sources":["../../../projects/lib/collapse/testing/wr-collapse-harness.ts","../../../projects/lib/collapse/testing/wr-collapse-group-harness.ts","../../../projects/lib/collapse/testing/ngwr-collapse-testing.ts"],"sourcesContent":["/**\n * @license\n *\n * Use of this source code is governed by an MIT-style license that can be\n * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE\n */\n\nimport { ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';\n\nimport type { WrCollapseHarnessFilters } from './interfaces';\n\n/**\n * Test harness for one `<wr-collapse>` — a disclosure: a header button, and the region\n * it opens. {@link WrCollapseGroupHarness} is the container several of them sit in.\n *\n * Open and closed are read from the header's `aria-expanded`, never from the panel's\n * size, and that is not merely a jsdom workaround. The body animates through\n * `grid-template-rows: 0fr → 1fr`, so a measured box answers with whatever frame the\n * transition happens to be on; a unit test has no layout at all, which makes every box\n * 0×0 and every such answer wrong in the same direction. The attribute is also the only\n * thing a screen-reader user gets — a panel that slides open without flipping it is\n * closed as far as they are concerned.\n *\n * The body stays in the DOM while the panel is closed. It has to: there would be no\n * height to animate otherwise. So its text is READABLE from a spec long before it is\n * visible on screen, which is why {@link getContentText} refuses to answer for a closed\n * panel instead of handing back invisible text, and why {@link isContentHidden} exists\n * to assert that a closed panel really is out of reach.\n *\n * The region itself is a plain `<div>` — the component gives it no `role=\"region\"` — so\n * `aria-expanded` plus `aria-controls` is the whole of the wiring, and\n * {@link isRegionBound} is how a spec checks it still points at this panel's own body.\n *\n * @example\n * ```ts\n * const loader = TestbedHarnessEnvironment.loader(fixture);\n * const shipping = await loader.getHarness(WrCollapseHarness.with({ title: 'Shipping' }));\n *\n * await shipping.open();\n * expect(await shipping.getContentText()).toContain('Ships Monday');\n * ```\n *\n * @see https://ngwr.dev/guides/testing\n */\nexport class WrCollapseHarness extends ComponentHarness {\n  static hostSelector = 'wr-collapse';\n\n  /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */\n  static with(options: WrCollapseHarnessFilters = {}): HarnessPredicate<WrCollapseHarness> {\n    return new HarnessPredicate(WrCollapseHarness, options)\n      .addOption('title', options.title, (harness, title) => HarnessPredicate.stringMatches(harness.getTitle(), title))\n      .addOption('open', options.open, async (harness, open) => (await harness.isOpen()) === open)\n      .addOption('disabled', options.disabled, async (harness, disabled) => (await harness.isDisabled()) === disabled);\n  }\n\n  private readonly header = this.locatorFor('button.wr-collapse__header');\n  private readonly body = this.locatorFor('.wr-collapse__body');\n\n  /**\n   * The header text, trimmed.\n   *\n   * Read from `.wr-collapse__title` rather than from the header button. Reading the\n   * button would return the same string today — the chevron beside the title is an\n   * `<svg>`, and an `<svg>` contributes no text — but the title element is the thing that\n   * holds the name, so an icon that ever grows a `<text>` node or a label, or a badge\n   * added next to the title, cannot leak into it.\n   */\n  async getTitle(): Promise<string> {\n    return (await this.locatorFor('.wr-collapse__title')()).text();\n  }\n\n  /**\n   * Whether the panel is open, from the header's `aria-expanded`.\n   *\n   * The `wr-collapse--open` modifier on the host is equally public and says the same\n   * thing today, but the attribute is the one a screen reader acts on: a panel that\n   * looks open while announcing `false` is the bug worth catching, and reading the class\n   * would agree with the animation and miss it.\n   */\n  async isOpen(): Promise<boolean> {\n    return (await (await this.header()).getAttribute('aria-expanded')) === 'true';\n  }\n\n  /**\n   * Whether the panel refuses interaction.\n   *\n   * From the header's own `disabled` property — the thing that actually turns a click\n   * away, and what the CDK consults before dispatching one — rather than from the\n   * `wr-collapse--disabled` modifier the host also carries. Both are public, but the\n   * class is styling: a panel could lose it and still refuse every click, and what a\n   * spec wants to know is whether the control is inert.\n   */\n  async isDisabled(): Promise<boolean> {\n    return (await this.header()).getProperty<boolean>('disabled');\n  }\n\n  /**\n   * The id the header's `aria-controls` names, or `null` when it names nothing.\n   *\n   * Per-instance and generated, so a spec cannot predict it — what it can do is check\n   * that two panels do not share one, and {@link isRegionBound} does the rest.\n   */\n  async getRegionId(): Promise<string | null> {\n    return (await this.header()).getAttribute('aria-controls');\n  }\n\n  /**\n   * Whether the header points at THIS panel's body, and at nothing else on the page.\n   *\n   * Both halves matter, and neither is provable from the header alone. The id is\n   * resolved inside the host first, so a header naming a SIBLING panel's body — which\n   * resolves perfectly well from the document and would look correctly wired — fails\n   * here. Then it is counted across the document, because two bodies answering to one\n   * id hand every reference to whichever comes first, and the second panel's region\n   * becomes unreachable to anything that follows the reference.\n   */\n  async isRegionBound(): Promise<boolean> {\n    const id = await this.getRegionId();\n    if (id === null) return false;\n\n    const own = await this.locatorForOptional(`.wr-collapse__body#${id}`)();\n    if (!own) return false;\n\n    const everywhere = await this.documentRootLocatorFactory().locatorForAll(`#${id}`)();\n    return everywhere.length === 1;\n  }\n\n  /**\n   * Whether the region is hidden from assistive tech AND from the keyboard.\n   *\n   * Two attributes, because a closed panel needs both and they cover different people:\n   * `aria-hidden` keeps the content out of the screen reader's document, `inert` keeps\n   * Tab from landing on a link inside a panel nobody can see. The body is never removed\n   * from the DOM — the height animation needs it — so these are the only thing standing\n   * between a collapsed panel and a keyboard user, and losing either is invisible on\n   * screen.\n   *\n   * They are asserted together on purpose: this answers \"is the closed content actually\n   * out of reach\", and half of it is not.\n   */\n  async isContentHidden(): Promise<boolean> {\n    const body = await this.body();\n    const hiddenFromAt = (await body.getAttribute('aria-hidden')) === 'true';\n    const inert = (await body.getAttribute('inert')) !== null;\n    return hiddenFromAt && inert;\n  }\n\n  /**\n   * The text of an OPEN panel's region, trimmed.\n   *\n   * Throws while the panel is closed rather than answering, because the body is still in\n   * the DOM and the text would come back exactly as it does when open — a spec asserting\n   * it would be pinning content the user cannot see, and would keep passing if the panel\n   * stopped opening at all.\n   */\n  async getContentText(): Promise<string> {\n    if (!(await this.isOpen())) {\n      throw new Error(\n        `WrCollapseHarness.getContentText(): \"${await this.getTitle()}\" is closed. Its content stays in the ` +\n          'DOM while collapsed — the body has to be there for the height to animate — so reading it now would ' +\n          'assert text nobody can see. Open the panel first, or ask isContentHidden().'\n      );\n    }\n    return (await this.locatorFor('.wr-collapse__inner')()).text();\n  }\n\n  /** Open the panel. An already-open one is left alone; a disabled one throws. */\n  async open(): Promise<void> {\n    if (await this.isOpen()) return;\n    await this.toggle();\n\n    if (!(await this.isOpen())) {\n      throw new Error(\n        `WrCollapseHarness.open(): \"${await this.getTitle()}\" did not open. A disabled panel refuses its own ` +\n          'header — the button carries `disabled`, and the component checks it again before toggling.'\n      );\n    }\n  }\n\n  /** Close the panel. An already-closed one is left alone; a disabled one throws. */\n  async close(): Promise<void> {\n    if (!(await this.isOpen())) return;\n    await this.toggle();\n\n    if (await this.isOpen()) {\n      throw new Error(\n        `WrCollapseHarness.close(): \"${await this.getTitle()}\" did not close. A disabled panel that was opened ` +\n          'through `[open]` cannot be closed from the page at all: the toggle refuses while `disabled` is set, ' +\n          'whichever direction the click would have gone.'\n      );\n    }\n  }\n\n  /**\n   * Click the header — the panel's entire interactive surface.\n   *\n   * A click rather than Enter / Space, and nothing is lost by it: the header is a native\n   * `<button>`, so a real keyboard activation is the BROWSER synthesising a click from\n   * the key press, and jsdom synthesises none. The click is dispatched onto the header\n   * itself, so it needs no coordinate and cannot miss in a test that has no layout.\n   *\n   * A disabled panel ignores this and stays as it was, twice over: the CDK withholds the\n   * `click` from an element carrying `disabled`, and the component checks `disabled`\n   * again inside its own toggle. Assert rather than assume, or reach for {@link open} /\n   * {@link close}, which say so.\n   */\n  async toggle(): Promise<void> {\n    return (await this.header()).click();\n  }\n\n  /**\n   * Move keyboard focus to the header — the only focusable element the component itself\n   * renders. Projected content can of course hold its own (which is why a closed panel is\n   * `inert`), but that belongs to the consumer, not to this harness.\n   */\n  async focus(): Promise<void> {\n    return (await this.header()).focus();\n  }\n\n  /** Whether the header currently holds focus. */\n  async isFocused(): Promise<boolean> {\n    return (await this.header()).isFocused();\n  }\n}\n","/**\n * @license\n *\n * Use of this source code is governed by an MIT-style license that can be\n * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE\n */\n\nimport { ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';\n\nimport type { WrCollapseGroupHarnessFilters, WrCollapseHarnessFilters } from './interfaces';\nimport { WrCollapseHarness } from './wr-collapse-harness';\n\n/**\n * Test harness for `<wr-collapse-group>` and `<wr-accordion>` — the container a set of\n * {@link WrCollapseHarness} panels sits in, matched in both of its element shapes.\n *\n * There is deliberately no `isAccordion()`, and the reason is worth knowing before a\n * spec goes looking for one: single-open behaviour is not written down anywhere on the\n * page. `<wr-accordion>` carries the marker class `wr-collapse-group--accordion`, but\n * `<wr-collapse-group [accordion]=\"true\">` enforces exactly the same rule and carries\n * nothing — a bound input reaches the component without touching the DOM, and even the\n * literal `accordion` attribute survives only because Angular leaves a static attribute\n * alone. So the class answers \"which element did the template use\", not \"does this group\n * close siblings\", and a harness reporting it would call the group form false. Assert the\n * BEHAVIOUR instead: open two panels and read {@link getOpenTitles} — the assertion that\n * would catch a broken accordion anyway.\n *\n * A collapse group is also not a composite widget. Every header is a native `<button>`\n * in the normal tab order, with no roving `tabindex` and no arrow-key navigation (the\n * APG lists both as optional for an accordion), so there is no \"active\" panel to tell\n * apart from the open one — {@link getFocusedTitle} is the only cursor there is.\n *\n * @example\n * ```ts\n * const settings = await loader.getHarness(WrCollapseGroupHarness.with({ panelTitle: 'Profile' }));\n *\n * await settings.openPanel({ title: 'Security' });\n * expect(await settings.getOpenTitles()).toEqual(['Security']);\n * ```\n *\n * @see https://ngwr.dev/guides/testing\n */\nexport class WrCollapseGroupHarness extends ComponentHarness {\n  /** Both shapes the container ships in: the plain group, and the always-accordion one. */\n  static hostSelector = 'wr-collapse-group, wr-accordion';\n\n  /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */\n  static with(options: WrCollapseGroupHarnessFilters = {}): HarnessPredicate<WrCollapseGroupHarness> {\n    return new HarnessPredicate(WrCollapseGroupHarness, options)\n      .addOption('panelTitle', options.panelTitle, async (harness, title) => {\n        for (const panel of await harness.getPanelTitles()) {\n          if (await HarnessPredicate.stringMatches(panel, title)) return true;\n        }\n        return false;\n      })\n      .addOption('openPanelTitle', options.openPanelTitle, async (harness, title) => {\n        for (const open of await harness.getOpenTitles()) {\n          if (await HarnessPredicate.stringMatches(open, title)) return true;\n        }\n        return false;\n      });\n  }\n\n  /**\n   * The group's panels, in DOM order.\n   *\n   * Every `<wr-collapse>` inside the host, which includes one nested in another panel's\n   * content and every panel of a nested group — the group scopes no more tightly than\n   * the DOM does, and a nested accordion's children are still descendants of this one.\n   */\n  async getPanels(filters: WrCollapseHarnessFilters = {}): Promise<WrCollapseHarness[]> {\n    return this.locatorForAll(WrCollapseHarness.with(filters))();\n  }\n\n  /** The header text of every panel, in DOM order. */\n  async getPanelTitles(): Promise<string[]> {\n    const panels = await this.getPanels();\n    return Promise.all(panels.map(panel => panel.getTitle()));\n  }\n\n  /** The first panel matching the filters, or a failure naming the panels that exist. */\n  async getPanel(filters: WrCollapseHarnessFilters): Promise<WrCollapseHarness> {\n    const [panel] = await this.getPanels(filters);\n    if (!panel) {\n      throw new Error(\n        `WrCollapseGroupHarness.getPanel(): no panel matched ${JSON.stringify(filters)}. This group holds: ` +\n          `${(await this.getPanelTitles()).join(', ')}.`\n      );\n    }\n    return panel;\n  }\n\n  /**\n   * The panel at a 0-based position in DOM order — the other half of \"by text or by\n   * index\", and the only way to address a panel whose title is not unique.\n   *\n   * Throws for an index past the end rather than resolving to nothing, and says how many\n   * panels there are: an out-of-range index is a mistake in the spec, and a `undefined`\n   * handed back would surface three lines later as a failure about something else.\n   */\n  async getPanelAt(index: number): Promise<WrCollapseHarness> {\n    const panels = await this.getPanels();\n    const panel = panels[index];\n    if (!panel) {\n      throw new Error(\n        `WrCollapseGroupHarness.getPanelAt(): index ${index} is out of range — this group holds ` +\n          `${panels.length} panel(s), so the last index is ${panels.length - 1}.`\n      );\n    }\n    return panel;\n  }\n\n  /** The panels that are open, in DOM order. In accordion mode there is at most one. */\n  async getOpenPanels(): Promise<WrCollapseHarness[]> {\n    return this.getPanels({ open: true });\n  }\n\n  /**\n   * The header text of every open panel, in DOM order.\n   *\n   * The assertion an accordion is worth pinning with: opening a second panel has to leave\n   * this a list of ONE, and it reads the state from each header's `aria-expanded`, so a\n   * sibling that collapsed on screen while still announcing itself open fails here.\n   */\n  async getOpenTitles(): Promise<string[]> {\n    const open = await this.getOpenPanels();\n    return Promise.all(open.map(panel => panel.getTitle()));\n  }\n\n  /**\n   * Open the first panel matching the filters.\n   *\n   * In accordion mode this is also what CLOSES the siblings — the group is told by the\n   * panel that opened, not by the click — so a spec that opens two panels in a row is\n   * asserting the mode, and {@link getOpenTitles} is where the answer shows up. Throws\n   * when nothing matched, and again when the panel refused to open (it is disabled).\n   */\n  async openPanel(filters: WrCollapseHarnessFilters): Promise<void> {\n    await (await this.getPanel(filters)).open();\n  }\n\n  /** Close the first panel matching the filters. */\n  async closePanel(filters: WrCollapseHarnessFilters): Promise<void> {\n    await (await this.getPanel(filters)).close();\n  }\n\n  /**\n   * Close every open panel.\n   *\n   * The open panels are resolved first and then closed one at a time. Every click a\n   * harness makes already awaits its own change detection, so closing them concurrently\n   * would work too — this reads in the order a user would click, and keeps each failure\n   * attributable to the panel that caused it. A disabled panel that was opened through\n   * `[open]` cannot be closed from the page and throws — the same failure\n   * {@link WrCollapseHarness.close} reports, for the same reason.\n   */\n  async closeAll(): Promise<void> {\n    for (const panel of await this.getOpenPanels()) {\n      await panel.close();\n    }\n  }\n\n  /**\n   * The header text of the panel whose header holds focus, or `null` when focus is\n   * elsewhere.\n   *\n   * Every header is its own tab stop here, so this reports where focus actually IS\n   * rather than where the group would send it — there is no roving tab stop to diverge\n   * from.\n   */\n  async getFocusedTitle(): Promise<string | null> {\n    for (const panel of await this.getPanels()) {\n      if (await panel.isFocused()) return panel.getTitle();\n    }\n    return null;\n  }\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":";;AAAA;;;;;AAKG;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCG;AACG,MAAO,iBAAkB,SAAQ,gBAAgB,CAAA;AACrD,IAAA,OAAO,YAAY,GAAG,aAAa;;AAGnC,IAAA,OAAO,IAAI,CAAC,OAAA,GAAoC,EAAE,EAAA;AAChD,QAAA,OAAO,IAAI,gBAAgB,CAAC,iBAAiB,EAAE,OAAO;aACnD,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,KAAK,KAAK,gBAAgB,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC;aAC/G,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,OAAO,EAAE,IAAI,KAAK,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,MAAM,IAAI;aAC1F,SAAS,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC,MAAM,OAAO,CAAC,UAAU,EAAE,MAAM,QAAQ,CAAC;IACpH;AAEiB,IAAA,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,4BAA4B,CAAC;AACtD,IAAA,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,oBAAoB,CAAC;AAE7D;;;;;;;;AAQG;AACH,IAAA,MAAM,QAAQ,GAAA;AACZ,QAAA,OAAO,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,qBAAqB,CAAC,EAAE,EAAE,IAAI,EAAE;IAChE;AAEA;;;;;;;AAOG;AACH,IAAA,MAAM,MAAM,GAAA;AACV,QAAA,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,EAAE,YAAY,CAAC,eAAe,CAAC,MAAM,MAAM;IAC/E;AAEA;;;;;;;;AAQG;AACH,IAAA,MAAM,UAAU,GAAA;AACd,QAAA,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,EAAE,WAAW,CAAU,UAAU,CAAC;IAC/D;AAEA;;;;;AAKG;AACH,IAAA,MAAM,WAAW,GAAA;AACf,QAAA,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,EAAE,YAAY,CAAC,eAAe,CAAC;IAC5D;AAEA;;;;;;;;;AASG;AACH,IAAA,MAAM,aAAa,GAAA;AACjB,QAAA,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE;QACnC,IAAI,EAAE,KAAK,IAAI;AAAE,YAAA,OAAO,KAAK;AAE7B,QAAA,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,CAAA,mBAAA,EAAsB,EAAE,CAAA,CAAE,CAAC,EAAE;AACvE,QAAA,IAAI,CAAC,GAAG;AAAE,YAAA,OAAO,KAAK;AAEtB,QAAA,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,0BAA0B,EAAE,CAAC,aAAa,CAAC,CAAA,CAAA,EAAI,EAAE,CAAA,CAAE,CAAC,EAAE;AACpF,QAAA,OAAO,UAAU,CAAC,MAAM,KAAK,CAAC;IAChC;AAEA;;;;;;;;;;;;AAYG;AACH,IAAA,MAAM,eAAe,GAAA;AACnB,QAAA,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE;AAC9B,QAAA,MAAM,YAAY,GAAG,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC,MAAM,MAAM;AACxE,QAAA,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,IAAI;QACzD,OAAO,YAAY,IAAI,KAAK;IAC9B;AAEA;;;;;;;AAOG;AACH,IAAA,MAAM,cAAc,GAAA;QAClB,IAAI,EAAE,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE;YAC1B,MAAM,IAAI,KAAK,CACb,CAAA,qCAAA,EAAwC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAA,sCAAA,CAAwC;gBACnG,qGAAqG;AACrG,gBAAA,6EAA6E,CAChF;QACH;AACA,QAAA,OAAO,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,qBAAqB,CAAC,EAAE,EAAE,IAAI,EAAE;IAChE;;AAGA,IAAA,MAAM,IAAI,GAAA;AACR,QAAA,IAAI,MAAM,IAAI,CAAC,MAAM,EAAE;YAAE;AACzB,QAAA,MAAM,IAAI,CAAC,MAAM,EAAE;QAEnB,IAAI,EAAE,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE;YAC1B,MAAM,IAAI,KAAK,CACb,CAAA,2BAAA,EAA8B,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAA,iDAAA,CAAmD;AACpG,gBAAA,4FAA4F,CAC/F;QACH;IACF;;AAGA,IAAA,MAAM,KAAK,GAAA;AACT,QAAA,IAAI,EAAE,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YAAE;AAC5B,QAAA,MAAM,IAAI,CAAC,MAAM,EAAE;AAEnB,QAAA,IAAI,MAAM,IAAI,CAAC,MAAM,EAAE,EAAE;YACvB,MAAM,IAAI,KAAK,CACb,CAAA,4BAAA,EAA+B,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAA,kDAAA,CAAoD;gBACtG,sGAAsG;AACtG,gBAAA,gDAAgD,CACnD;QACH;IACF;AAEA;;;;;;;;;;;;AAYG;AACH,IAAA,MAAM,MAAM,GAAA;QACV,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE;IACtC;AAEA;;;;AAIG;AACH,IAAA,MAAM,KAAK,GAAA;QACT,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE;IACtC;;AAGA,IAAA,MAAM,SAAS,GAAA;QACb,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE;IAC1C;;;AC9NF;;;;;AAKG;AAOH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BG;AACG,MAAO,sBAAuB,SAAQ,gBAAgB,CAAA;;AAE1D,IAAA,OAAO,YAAY,GAAG,iCAAiC;;AAGvD,IAAA,OAAO,IAAI,CAAC,OAAA,GAAyC,EAAE,EAAA;AACrD,QAAA,OAAO,IAAI,gBAAgB,CAAC,sBAAsB,EAAE,OAAO;AACxD,aAAA,SAAS,CAAC,YAAY,EAAE,OAAO,CAAC,UAAU,EAAE,OAAO,OAAO,EAAE,KAAK,KAAI;YACpE,KAAK,MAAM,KAAK,IAAI,MAAM,OAAO,CAAC,cAAc,EAAE,EAAE;gBAClD,IAAI,MAAM,gBAAgB,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC;AAAE,oBAAA,OAAO,IAAI;YACrE;AACA,YAAA,OAAO,KAAK;AACd,QAAA,CAAC;AACA,aAAA,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC,cAAc,EAAE,OAAO,OAAO,EAAE,KAAK,KAAI;YAC5E,KAAK,MAAM,IAAI,IAAI,MAAM,OAAO,CAAC,aAAa,EAAE,EAAE;gBAChD,IAAI,MAAM,gBAAgB,CAAC,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC;AAAE,oBAAA,OAAO,IAAI;YACpE;AACA,YAAA,OAAO,KAAK;AACd,QAAA,CAAC,CAAC;IACN;AAEA;;;;;;AAMG;AACH,IAAA,MAAM,SAAS,CAAC,OAAA,GAAoC,EAAE,EAAA;AACpD,QAAA,OAAO,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE;IAC9D;;AAGA,IAAA,MAAM,cAAc,GAAA;AAClB,QAAA,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE;AACrC,QAAA,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC3D;;IAGA,MAAM,QAAQ,CAAC,OAAiC,EAAA;QAC9C,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QAC7C,IAAI,CAAC,KAAK,EAAE;YACV,MAAM,IAAI,KAAK,CACb,CAAA,oDAAA,EAAuD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA,oBAAA,CAAsB;AAClG,gBAAA,CAAA,EAAG,CAAC,MAAM,IAAI,CAAC,cAAc,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA,CAAA,CAAG,CACjD;QACH;AACA,QAAA,OAAO,KAAK;IACd;AAEA;;;;;;;AAOG;IACH,MAAM,UAAU,CAAC,KAAa,EAAA;AAC5B,QAAA,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE;AACrC,QAAA,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,KAAK,EAAE;AACV,YAAA,MAAM,IAAI,KAAK,CACb,CAAA,2CAAA,EAA8C,KAAK,CAAA,oCAAA,CAAsC;gBACvF,CAAA,EAAG,MAAM,CAAC,MAAM,CAAA,gCAAA,EAAmC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAA,CAAA,CAAG,CAC1E;QACH;AACA,QAAA,OAAO,KAAK;IACd;;AAGA,IAAA,MAAM,aAAa,GAAA;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACvC;AAEA;;;;;;AAMG;AACH,IAAA,MAAM,aAAa,GAAA;AACjB,QAAA,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,aAAa,EAAE;AACvC,QAAA,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IACzD;AAEA;;;;;;;AAOG;IACH,MAAM,SAAS,CAAC,OAAiC,EAAA;AAC/C,QAAA,MAAM,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE;IAC7C;;IAGA,MAAM,UAAU,CAAC,OAAiC,EAAA;AAChD,QAAA,MAAM,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE;IAC9C;AAEA;;;;;;;;;AASG;AACH,IAAA,MAAM,QAAQ,GAAA;QACZ,KAAK,MAAM,KAAK,IAAI,MAAM,IAAI,CAAC,aAAa,EAAE,EAAE;AAC9C,YAAA,MAAM,KAAK,CAAC,KAAK,EAAE;QACrB;IACF;AAEA;;;;;;;AAOG;AACH,IAAA,MAAM,eAAe,GAAA;QACnB,KAAK,MAAM,KAAK,IAAI,MAAM,IAAI,CAAC,SAAS,EAAE,EAAE;AAC1C,YAAA,IAAI,MAAM,KAAK,CAAC,SAAS,EAAE;AAAE,gBAAA,OAAO,KAAK,CAAC,QAAQ,EAAE;QACtD;AACA,QAAA,OAAO,IAAI;IACb;;;AC/KF;;AAEG;;;;"}

package/fesm2022/ngwr-color-picker.mjs

@@ -251,6 +251,102 @@ function toHex(rgb, withAlpha = false) {
  * 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
  */
+/**
+ * `rgb(…)` / `rgba(…)`, comma- or space-separated, with an optional `/ alpha`.
+ * Signs are accepted so an out-of-range channel CLAMPS the way CSS clamps it,
+ * rather than failing to parse and reading as black.
+ */
+const RGB_RE = /^rgba?\(\s*(-?[\d.]+)\s*[,\s]\s*(-?[\d.]+)\s*[,\s]\s*(-?[\d.]+)\s*(?:[,/]\s*(-?[\d.]+%?)\s*)?\)$/i;
+/** `hsl(…)` / `hsla(…)`, with `%` optional on saturation and lightness. */
+const HSL_RE = /^hsla?\(\s*(-?[\d.]+)(?:deg)?\s*[,\s]\s*(-?[\d.]+)%?\s*[,\s]\s*(-?[\d.]+)%?\s*(?:[,/]\s*(-?[\d.]+%?)\s*)?\)$/i;
+/** `0.5` and `50%` are the same alpha; anything absent is fully opaque. */
+function alphaOf(raw) {
+    if (raw === undefined)
+        return 1;
+    const value = raw.endsWith('%') ? Number(raw.slice(0, -1)) / 100 : Number(raw);
+    return Number.isFinite(value) ? clamp(value, 0, 1) : 1;
+}
+function channel(raw) {
+    return clamp(Math.round(Number(raw)), 0, 255);
+}
+/**
+ * Read a colour written in any format `<wr-color-picker>` can emit — hex,
+ * `rgb()` / `rgba()`, `hsl()` / `hsla()` — or `null` when it is none of them.
+ *
+ * The picker emits in whichever format it was given, so a `[(value)]` binding
+ * hands its own output straight back on the next external write. Accepting only
+ * hex there (which is what it used to do) turned every non-hex value into black.
+ *
+ * `null` rather than a throw or a black fallback: the caller is often a text
+ * field mid-typing, where "not valid yet" is the normal state.
+ */
+function parseColor(input) {
+    const value = input.trim();
+    if (value === '')
+        return null;
+    const hex = parseHex(value);
+    if (hex)
+        return hex;
+    const rgb = RGB_RE.exec(value);
+    if (rgb) {
+        return { r: channel(rgb[1]), g: channel(rgb[2]), b: channel(rgb[3]), a: alphaOf(rgb[4]) };
+    }
+    const hsl = HSL_RE.exec(value);
+    if (hsl) {
+        return hslToRgb({
+            // Normalised here rather than trusted downstream: `hslToRgb` happens to
+            // absorb one negative turn inside `hueToChannel`, which is an internal
+            // detail this function should not be leaning on.
+            h: ((Number(hsl[1]) % 360) + 360) % 360,
+            s: clamp(Number(hsl[2]) / 100, 0, 1),
+            l: clamp(Number(hsl[3]) / 100, 0, 1),
+            a: alphaOf(hsl[4]),
+        });
+    }
+    return 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
+ */
+/** Alpha with at most two decimals, and no trailing zeroes: `0.5`, not `0.50`. */
+function alphaText(a) {
+    return String(Math.round(a * 100) / 100);
+}
+/**
+ * Render a colour in the format a `<wr-color-picker>` was asked for.
+ *
+ * `withAlpha` follows the picker's own `alpha` input, so each format has an
+ * opaque and a translucent spelling — `#3969e2` / `#3969e2ff`,
+ * `rgb(…)` / `rgba(…)`, `hsl(…)` / `hsla(…)` — and a picker with the alpha
+ * slider turned off never emits a channel the caller cannot see or edit.
+ */
+function formatColor(rgb, format, withAlpha) {
+    if (format === 'hex')
+        return toHex(rgb, withAlpha);
+    if (format === 'rgba') {
+        const { r, g, b } = rgb;
+        return withAlpha ? `rgba(${r}, ${g}, ${b}, ${alphaText(rgb.a)})` : `rgb(${r}, ${g}, ${b})`;
+    }
+    const { h, s, l } = rgbToHsl(rgb);
+    const parts = `${Math.round(h)}, ${Math.round(s * 100)}%, ${Math.round(l * 100)}%`;
+    return withAlpha ? `hsla(${parts}, ${alphaText(rgb.a)})` : `hsl(${parts})`;
+}
+
+/**
+ * @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
+ */
+/** Whether a hex string carries its own alpha (`#rgba` or `#rrggbbaa`). */
+function hasAlphaDigits(hex) {
+    const digits = hex.trim().replace(/^#/, '').length;
+    return digits === 4 || digits === 8;
+}
 /**
  * Inline colour picker — HSV canvas, hue slider, optional alpha slider, HEX
  * input.
@@ -276,7 +372,10 @@ class WrColorPicker {
     alpha = input(true, { ...(ngDevMode ? { debugName: "alpha" } : /* istanbul ignore next */ {}), transform: coerceBooleanProperty });
     /** Disable interaction. @default false */
     disabled = input(false, { ...(ngDevMode ? { debugName: "disabled" } : /* istanbul ignore next */ {}), transform: coerceBooleanProperty });
-    /** 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'
+     */
     format = input('hex', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "format" }] : /* istanbul ignore next */ []));
     /** Preset hex colours rendered as a clickable row beneath the inputs. Empty = no row. @default [] */
@@ -300,9 +399,12 @@ class WrColorPicker {
     /** RGB view of the current colour, computed lazily. */
     rgb = computed(() => hsvToRgb({ h: this.h(), s: this.s(), v: this.v(), a: this.a() }), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "rgb" }] : /* istanbul ignore next */ []));
-    /** Canonical hex (used by the input field and by drag emits). */
+    /** Canonical hex — what the HEX field shows, whatever `format` emits. */
     hex = computed(() => toHex(this.rgb(), this.alpha()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "hex" }] : /* istanbul ignore next */ []));
+    /** The colour as the consumer asked for it; this is what `value` receives. */
+    formatted = computed(() => formatColor(this.rgb(), this.format(), this.alpha()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "formatted" }] : /* istanbul ignore next */ []));
     /** SV canvas background colour (full-saturation hue). */
     hueCss = computed(() => `hsl(${this.h()}, 100%, 50%)`, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "hueCss" }] : /* istanbul ignore next */ []));
@@ -347,17 +449,17 @@ class WrColorPicker {
         return parts.join(' ');
     }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "classes" }] : /* istanbul ignore next */ []));
-    /** Last hex we pushed into `value`; lets the sync effect ignore our own writes. */
-    lastEmittedHex = null;
+    /** Last string we pushed into `value`; lets the sync effect ignore our own writes. */
+    lastEmitted = null;
     constructor() {
         // External writes (via `[formField]` / `[(value)]`) flow the incoming hex
         // string back into the HSV source of truth. Our own emits are skipped via
-        // `lastEmittedHex` so dragging keeps its continuous (unquantised) values.
+        // `lastEmitted` so dragging keeps its continuous (unquantised) values.
         effect(() => {
             const value = this.value();
-            if (value === this.lastEmittedHex)
+            if (value === this.lastEmitted)
                 return;
-            const rgb = parseHex(value) ?? { r: 0, g: 0, b: 0, a: 1 };
+            const rgb = parseColor(value) ?? { r: 0, g: 0, b: 0, a: 1 };
             const hsv = rgbToHsv(rgb);
             this.h.set(hsv.h);
             this.s.set(hsv.s);
@@ -370,6 +472,10 @@ class WrColorPicker {
     onPointerDown(event, surface) {
         if (this.disabled())
             return;
+        // Primary button, primary pointer: a right-click used to open the context
+        // menu AND start a drag, and a second finger used to fight the first one.
+        if (event.button !== 0 || !event.isPrimary)
+            return;
         event.preventDefault();
         const target = event.currentTarget;
         target.setPointerCapture(event.pointerId);
@@ -378,10 +484,15 @@ class WrColorPicker {
             target.releasePointerCapture(e.pointerId);
             target.removeEventListener('pointermove', update);
             target.removeEventListener('pointerup', cleanup);
+            target.removeEventListener('pointercancel', cleanup);
             this.touch.emit();
         };
         target.addEventListener('pointermove', update);
         target.addEventListener('pointerup', cleanup);
+        // `pointercancel` never sends a `pointerup` after it, so without this the
+        // move listener outlived the drag: a cancelled gesture left the surface
+        // repainting the colour under a pointer that was only hovering.
+        target.addEventListener('pointercancel', cleanup);
         this.updateFromEvent(event, target, surface);
     }
     updateFromEvent(event, target, surface) {
@@ -425,9 +536,9 @@ class WrColorPicker {
         this.hexInput.set(this.hex());
     }
     emitWithoutHexSync() {
-        const hex = this.hex();
-        this.lastEmittedHex = hex;
-        this.value.set(hex);
+        const next = this.formatted();
+        this.lastEmitted = next;
+        this.value.set(next);
     }
     // Tab + channel handlers
     onTabChange(tab) {
@@ -463,9 +574,12 @@ class WrColorPicker {
         const rgb = parseHex(hex);
         if (!rgb)
             return;
-        this.applyRgb(rgb);
+        // A 6-digit swatch says nothing about alpha, and `parseHex` reports the
+        // absence as `1` — so picking a preset used to silently snap a translucent
+        // colour back to fully opaque.
+        this.applyRgb(hasAlphaDigits(hex) ? rgb : { ...rgb, a: this.a() });
     }
-    /** 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. */
     applyRgb(rgb) {
         const hsv = rgbToHsv(rgb);
         this.h.set(hsv.h);
@@ -621,13 +735,19 @@ class WrColorPickerTrigger {
         }
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.1", ngImport: i0, type: WrColorPickerTrigger, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.1.1", type: WrColorPickerTrigger, isStandalone: true, selector: "[wrColorPickerTrigger]", inputs: { value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null }, alpha: { classPropertyName: "alpha", publicName: "alpha", isSignal: true, isRequired: false, transformFunction: null }, format: { classPropertyName: "format", publicName: "format", isSignal: true, isRequired: false, transformFunction: null }, swatches: { classPropertyName: "swatches", publicName: "swatches", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { value: "valueChange", opened: "opened", closed: "closed" }, host: { listeners: { "click": "toggle()" } }, ngImport: i0 });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.1.1", type: WrColorPickerTrigger, isStandalone: true, selector: "[wrColorPickerTrigger]", inputs: { value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null }, alpha: { classPropertyName: "alpha", publicName: "alpha", isSignal: true, isRequired: false, transformFunction: null }, format: { classPropertyName: "format", publicName: "format", isSignal: true, isRequired: false, transformFunction: null }, swatches: { classPropertyName: "swatches", publicName: "swatches", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { value: "valueChange", opened: "opened", closed: "closed" }, host: { listeners: { "click": "toggle()" }, properties: { "attr.aria-haspopup": "\"dialog\"", "attr.aria-expanded": "isOpen()" } }, ngImport: i0 });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.1", ngImport: i0, type: WrColorPickerTrigger, decorators: [{
             type: Directive,
             args: [{
                     selector: '[wrColorPickerTrigger]',
-                    host: { '(click)': 'toggle()' },
+                    host: {
+                        '(click)': 'toggle()',
+                        // The same two attributes `<wr-popover>`'s trigger carries: without them the
+                        // button gave no hint that it opens anything, and never said it was open.
+                        '[attr.aria-haspopup]': '"dialog"',
+                        '[attr.aria-expanded]': 'isOpen()',
+                    },
                 }]
         }], ctorParameters: () => [], propDecorators: { value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: false }] }, { type: i0.Output, args: ["valueChange"] }], alpha: [{ type: i0.Input, args: [{ isSignal: true, alias: "alpha", required: false }] }], format: [{ type: i0.Input, args: [{ isSignal: true, alias: "format", required: false }] }], swatches: [{ type: i0.Input, args: [{ isSignal: true, alias: "swatches", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], opened: [{ type: i0.Output, args: ["opened"] }], closed: [{ type: i0.Output, args: ["closed"] }] } });