@cdevhub/ngx-tw 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdevhub/ngx-tw",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Angular component library for Tailwind CSS v4 — accessible, signal-based, built on Angular CDK.",
   "keywords": [
     "angular",
@@ -193,6 +193,10 @@
       "types": "./types/cdevhub-ngx-tw-popover.d.ts",
       "default": "./fesm2022/cdevhub-ngx-tw-popover.mjs"
     },
+    "./popover/testing": {
+      "types": "./types/cdevhub-ngx-tw-popover-testing.d.ts",
+      "default": "./fesm2022/cdevhub-ngx-tw-popover-testing.mjs"
+    },
     "./progress-bar": {
       "types": "./types/cdevhub-ngx-tw-progress-bar.d.ts",
       "default": "./fesm2022/cdevhub-ngx-tw-progress-bar.mjs"
@@ -305,6 +309,10 @@
       "types": "./types/cdevhub-ngx-tw-tooltip.d.ts",
       "default": "./fesm2022/cdevhub-ngx-tw-tooltip.mjs"
     },
+    "./tooltip/testing": {
+      "types": "./types/cdevhub-ngx-tw-tooltip-testing.d.ts",
+      "default": "./fesm2022/cdevhub-ngx-tw-tooltip-testing.mjs"
+    },
     "./transfer": {
       "types": "./types/cdevhub-ngx-tw-transfer.d.ts",
       "default": "./fesm2022/cdevhub-ngx-tw-transfer.mjs"

package/types/cdevhub-ngx-tw-command-palette-testing.d.ts

@@ -80,8 +80,8 @@ declare class CommandPaletteHarness extends ComponentHarness {
      *
      * **The overlay is still attached when this resolves.** The component defers
      * the detach behind a leave animation, so a caller asserting on `isOpen()`
-     * immediately afterwards will still see `true`. Wait for the animation before
-     * asserting — with a plain timer, not by polling a harness method.
+     * immediately afterwards will still see `true`. Wait for the detach before
+     * asserting — by reading the document, never by polling a harness method.
      *
      * That caveat is deliberate rather than hidden behind a poll. An earlier
      * version looped on `isOpen()` until the panel detached, which reads better
@@ -92,11 +92,11 @@ declare class CommandPaletteHarness extends ComponentHarness {
      * failing it. A harness that can hang is worse than one that makes the caller
      * wait explicitly.
      *
-     * **This method is not covered by a spec.** A test driving it hung at the full
-     * 15000ms budget in roughly one run in three: the harness calls it makes
-     * around a leave animation route through `whenStable()`, which can wait on a
-     * re-scheduled timer and never resolve. Escape dismissal itself is covered in
-     * `command-palette.spec.ts`, directly against the component.
+     * Wait by polling the document for the panel to leave, under your own
+     * deadline — `document.querySelector('tw-command-palette-overlay') === null`
+     * needs no stabilization, so it can neither hang nor burn a fixed sleep. The
+     * `closes with Escape` case in `command-palette-harness.spec.ts` is the
+     * worked example, and is this method's coverage.
      */
     close(): Promise<void>;
     /** Moves the active descendant down one row. */

package/types/cdevhub-ngx-tw-popover-testing.d.ts

@@ -0,0 +1,89 @@
+import { ComponentHarness, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
+
+/** Filters accepted by `PopoverHarness.with`. */
+interface PopoverHarnessFilters extends BaseHarnessFilters {
+    /** Match by the text rendered in the trigger. */
+    triggerText?: string | RegExp;
+}
+/**
+ * Harness for a `[twPopover]` trigger and the panel it opens.
+ *
+ * ## Loading it
+ *
+ * The host is the trigger, which lives in the fixture, so the ordinary
+ * `TestbedHarnessEnvironment.loader(fixture)` is correct. The panel renders into
+ * the CDK overlay container outside the fixture, and this harness resolves it
+ * internally via `documentRootLocatorFactory()` — a consumer never needs
+ * `documentRootLoader`.
+ *
+ * The host selector is the directive's static `data-tw-popover-trigger` marker.
+ * `[twPopover]` cannot be used: it takes a required `TemplateRef` or component
+ * type, so it is always property-bound and Angular renders no attribute for a
+ * bound input. The marker also makes the match exact, so no disambiguation
+ * against `aria-haspopup="dialog"` — which the two date-picker triggers also
+ * carry — is needed.
+ *
+ * ## Waiting for the panel
+ *
+ * Every method stabilizes the fixture the way CDK harnesses always do, which
+ * covers change detection but **not** the component's own timers: `popover.ts`
+ * detaches the panel behind a hard-coded 120 ms leave window driven by a plain
+ * `setTimeout`, which Angular's `PendingTasks` does not track, so
+ * `whenStable()` does not wait for it. {@link close} therefore dispatches
+ * Escape and returns while the panel is still attached. Poll the DOM for its
+ * removal — `document.querySelector('tw-popover-overlay')` — and only then read
+ * through the harness.
+ *
+ * ## The panel is detached, not disposed
+ *
+ * Unlike `tw-select`, closing a popover **detaches** the portal and keeps the
+ * `OverlayRef` for reuse; it is only rebuilt when `twPopoverBackdrop` or
+ * `twPopoverScrollStrategy` changes. The panel element is therefore absent while
+ * closed and present again after a reopen, on the same overlay.
+ */
+declare class PopoverHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: PopoverHarnessFilters): HarnessPredicate<PopoverHarness>;
+    /** The text currently rendered in the trigger, trimmed. */
+    getTriggerText(): Promise<string>;
+    /** Whether the popover is open, read from the trigger's `aria-expanded`. */
+    isOpen(): Promise<boolean>;
+    /**
+     * Opens the popover by clicking the trigger. No-op when already open.
+     *
+     * This is the gesture for the default `twPopoverTriggerOn="click"`. A
+     * `'focus'`- or `'manual'`-triggered popover is opened through the directive's
+     * own `open()` (reachable via `exportAs: 'twPopover'`), not through a click.
+     */
+    open(): Promise<void>;
+    /**
+     * Closes the popover by sending Escape to the trigger — the one dismissal
+     * that works for click, focus and manual triggers alike. No-op when already
+     * closed, and deliberately inert when `twPopoverCloseOnEscape` is `false`.
+     *
+     * Returns as soon as the key is dispatched. The panel detaches only after the
+     * 120 ms leave window; poll the DOM for its removal before asserting.
+     */
+    close(): Promise<void>;
+    /**
+     * Text rendered inside the panel, trimmed, or `null` when the popover is
+     * closed and the panel is detached.
+     */
+    getText(): Promise<string | null>;
+    /**
+     * Whether the panel renders its directional arrow (`twPopoverArrow`). `false`
+     * while the popover is closed, because the panel does not exist then.
+     */
+    hasArrow(): Promise<boolean>;
+    /** The panel element, or `null` when the popover is closed. */
+    private getPanel;
+    /**
+     * The id of this trigger's own panel, or `null` when closed. Scoping by
+     * `aria-controls` keeps sibling popovers apart.
+     */
+    private getPanelId;
+}
+
+export { PopoverHarness };
+export type { PopoverHarnessFilters };

package/types/cdevhub-ngx-tw-tooltip-testing.d.ts

@@ -0,0 +1,83 @@
+import { ComponentHarness, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
+
+/** Filters accepted by `TooltipHarness.with`. */
+interface TooltipHarnessFilters extends BaseHarnessFilters {
+    /** Match by the text rendered in the trigger. */
+    triggerText?: string | RegExp;
+}
+/**
+ * Harness for a `[twTooltip]` trigger and the panel it shows.
+ *
+ * Deliberately narrow: a tooltip's whole observable surface is *whether it is
+ * showing and what it says*. Position, delays, color, size and arrow are
+ * configuration, not state, and a harness method for any of them would freeze an
+ * API that may still move — so none is offered.
+ *
+ * ## Loading it
+ *
+ * The host is the trigger, which lives in the fixture, so the ordinary
+ * `TestbedHarnessEnvironment.loader(fixture)` is correct. The panel renders into
+ * the CDK overlay container outside the fixture, and this harness resolves it
+ * internally via `documentRootLocatorFactory()` — a consumer never needs
+ * `documentRootLoader`.
+ *
+ * The host selector is the directive's static `data-tw-tooltip-trigger` marker,
+ * which matches both spellings of the input: `twTooltip="literal"` and the bound
+ * `[twTooltip]="expr()"`, for which Angular renders no attribute at all. A
+ * harness matching the directive's own selector would silently miss every bound
+ * trigger.
+ *
+ * Unlike `MenuHarness` and `PopoverHarness`, a tooltip trigger carries no
+ * `aria-controls` linking it to its panel (`aria-describedby` points at CDK
+ * `AriaDescriber`'s shared hidden message element for string content), so the
+ * panel is resolved as "the tooltip showing in the document". That is exact for
+ * the hover/focus model, where only one tooltip is visible at a time, but a test
+ * that forces two open at once cannot tell them apart.
+ *
+ * ## Waiting for the panel
+ *
+ * Every method stabilizes the fixture the way CDK harnesses always do, which
+ * covers change detection but **not** the component's own timers: show and hide
+ * are driven by plain `setTimeout`s behind `twTooltipShowDelay` (200 ms by
+ * default) and `twTooltipHideDelay` (150 ms), which Angular's `PendingTasks`
+ * does not track, so `whenStable()` does not wait for them — not even at a delay
+ * of `0`. {@link show} and {@link hide} therefore dispatch the interaction and
+ * return before anything has attached or detached. Set both delays to `0` in the
+ * fixture, poll the DOM for the panel —
+ * `document.querySelector('tw-tooltip-overlay')` — and only then read through
+ * the harness.
+ */
+declare class TooltipHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Resolves the tooltip panel, which lives outside this harness's host. */
+    private readonly panel;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: TooltipHarnessFilters): HarnessPredicate<TooltipHarness>;
+    /** The text currently rendered in the trigger, trimmed. */
+    getTriggerText(): Promise<string>;
+    /** Whether a tooltip panel is currently showing. */
+    isOpen(): Promise<boolean>;
+    /**
+     * The tooltip's message, trimmed, or `null` when nothing is showing. Works
+     * for string and `TemplateRef` content alike.
+     */
+    getTooltipText(): Promise<string | null>;
+    /** Hovers the trigger. The panel appears once `twTooltipShowDelay` elapses. */
+    show(): Promise<void>;
+    /** Moves the pointer off the trigger. The panel detaches once `twTooltipHideDelay` elapses. */
+    hide(): Promise<void>;
+    /**
+     * Focuses the trigger — the keyboard equivalent of {@link show}, and the path
+     * WCAG 2.1 SC 1.4.13 requires to work.
+     *
+     * Moves real DOM focus *and* dispatches `focusin`, because a programmatic
+     * `focus()` does not reliably raise `focusin` in every test DOM. The directive
+     * treats a repeated show as a no-op, so the belt-and-braces pair is safe.
+     */
+    focusTrigger(): Promise<void>;
+    /** Blurs the trigger — the keyboard equivalent of {@link hide}. */
+    blurTrigger(): Promise<void>;
+}
+
+export { TooltipHarness };
+export type { TooltipHarnessFilters };