@cdevhub/ngx-tw 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdevhub/ngx-tw",
-  "version": "0.7.0",
+  "version": "0.8.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-popover-testing.d.ts

@@ -0,0 +1,138 @@
+import { ComponentHarness, HarnessLoader, 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.
+ *
+ * ## Nothing here awaits application stabilization, and that is load-bearing
+ *
+ * `TestbedHarnessEnvironment` routes every `TestElement` operation through
+ * `forceStabilize()` — `fixture.detectChanges()` then
+ * `await fixture.whenStable()` — and that await resolves only when Angular's
+ * `PendingTasks` set is empty. Under full-suite contention it was observed
+ * **not to resolve at all**, and everything built on it hung for the whole test
+ * budget instead of failing. This harness was withdrawn twice for that.
+ *
+ * Every method body therefore runs inside CDK's `manualChangeDetection()`,
+ * which sets the flag `forceStabilize()` early-returns on, and so does
+ * acquisition, via {@link load} / {@link loadAll}. The spec beside this file
+ * adds the third piece: it never awaits `fixture.whenStable()` either, not even
+ * in `beforeEach`. All three were needed — each of the two CI failures during
+ * this restoration was traced to one of them, and the second landed on
+ * `tooltip` rather than here, which is how it became clear the fault belongs to
+ * whichever harness spec lands in the unlucky worker slot rather than to any
+ * one component. `grep -c whenStable` over this file and its spec returns zero,
+ * which is the whole claim and is checkable in one command rather than by
+ * counting green runs. The spec pins the rest with tests that hold a real
+ * `PendingTasks` entry open across acquisition and every method.
+ *
+ * Why the application stops stabilizing is **not** known; this removes the
+ * dependency rather than curing it.
+ *
+ * The cost is that change detection is not forced on your behalf. Instead every
+ * method spends one macrotask on the scheduler (see {@link afterSchedulerTick}),
+ * which covers everything already scheduled — including the panel's first
+ * render. What it does not cover is state behind the component's own timers:
+ * {@link close} dispatches Escape and returns, and the panel detaches only after
+ * the 120 ms leave window in `popover.ts`. Wait for that by polling the DOM —
+ * `document.querySelector` needs no stabilization and so can neither hang nor
+ * burn a fixed interval — and only then read through the harness.
+ *
+ * ## 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.
+ *
+ * ## 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;
+    /**
+     * Acquires one harness without waiting for the application to stabilize —
+     * the counterpart to the guarantee the methods below make.
+     *
+     * `loader.getHarness(...)` is CDK's own acquisition path and it stabilizes:
+     * `getAllRawElements` calls `forceStabilize()`, and `HarnessPredicate`
+     * filtering routes through `parallel()`, which asks *every* active fixture in
+     * the worker to settle. Both await `fixture.whenStable()`, which is the one
+     * thing this harness exists to avoid — and the failure that withdrew it was
+     * observed there, at acquisition, before any method had run.
+     *
+     * So acquisition is wrapped too, and `manualChangeDetection()` nests: the
+     * inner `parallel()` sees the flag already set and skips the stabilization
+     * entirely. **Render the fixture first** (`fixture.detectChanges()`), because
+     * nothing here will do it for you; an unrendered fixture fails loudly with
+     * CDK's "failed to find element" rather than returning something wrong.
+     *
+     * Plain `loader.getHarness(PopoverHarness)` still works and is still supported.
+     * This is the path to use when a suite must not be able to hang.
+     */
+    static load(loader: HarnessLoader, options?: PopoverHarnessFilters): Promise<PopoverHarness>;
+    /** {@link load} for every matching trigger rather than the first. */
+    static loadAll(loader: HarnessLoader, options?: PopoverHarnessFilters): Promise<PopoverHarness[]>;
+    /** 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. Callers are already
+     * inside `manualChangeDetection`.
+     */
+    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,131 @@
+import { ComponentHarness, HarnessLoader, 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.
+ *
+ * ## Nothing here awaits application stabilization, and that is load-bearing
+ *
+ * `TestbedHarnessEnvironment` routes every `TestElement` operation through
+ * `forceStabilize()` — `fixture.detectChanges()` then
+ * `await fixture.whenStable()` — and that await resolves only when Angular's
+ * `PendingTasks` set is empty. Under full-suite contention it was observed
+ * **not to resolve at all**, and everything built on it hung for the whole test
+ * budget instead of failing. This harness was withdrawn once for that, on five
+ * green local runs followed by one red CI run.
+ *
+ * Every method body therefore runs inside CDK's `manualChangeDetection()`,
+ * which sets the flag `forceStabilize()` early-returns on, and so does
+ * acquisition, via {@link load} / {@link loadAll}. The spec beside this file
+ * adds the third piece: it never awaits `fixture.whenStable()` either, not even
+ * in `beforeEach`. All three were needed — each of the two CI failures during
+ * this restoration was traced to one of them, and the second landed on
+ * `popover` rather than here, which is how it became clear the fault belongs to
+ * whichever harness spec lands in the unlucky worker slot rather than to any
+ * one component. `grep -c whenStable` over this file and its spec returns zero,
+ * which is the whole claim and is checkable in one command rather than by
+ * counting green runs. The spec pins the rest with tests that hold a real
+ * `PendingTasks` entry open across acquisition and every method.
+ *
+ * Why the application stops stabilizing is **not** known; this removes the
+ * dependency rather than curing it.
+ *
+ * The cost is that change detection is not forced on your behalf. Instead every
+ * method spends one macrotask on the scheduler (see {@link afterSchedulerTick}),
+ * which covers everything already scheduled — including the panel's first
+ * render, which is why {@link getTooltipText} does not come back empty on a
+ * tooltip that has only just attached. What it does not cover is state behind
+ * the component's own timers: {@link show} and {@link hide} dispatch the
+ * interaction and return, and the panel appears or detaches only once
+ * `twTooltipShowDelay` (200 ms by default) or `twTooltipHideDelay` (150 ms)
+ * elapses. Set both to `0` in a fixture, poll the DOM for the panel —
+ * `document.querySelector` needs no stabilization and so can neither hang nor
+ * burn a fixed interval — and only then read through the harness.
+ *
+ * ## 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.
+ */
+declare class TooltipHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Resolves the tooltip panel, which lives outside this harness's host. */
+    private readonly panel;
+    /**
+     * Acquires one harness without waiting for the application to stabilize —
+     * the counterpart to the guarantee the methods below make.
+     *
+     * `loader.getHarness(...)` is CDK's own acquisition path and it stabilizes:
+     * `getAllRawElements` calls `forceStabilize()`, and `HarnessPredicate`
+     * filtering routes through `parallel()`, which asks *every* active fixture in
+     * the worker to settle. Both await `fixture.whenStable()`, which is the one
+     * thing this harness exists to avoid — and the failure that withdrew it was
+     * observed there, at acquisition, before any method had run.
+     *
+     * So acquisition is wrapped too, and `manualChangeDetection()` nests: the
+     * inner `parallel()` sees the flag already set and skips the stabilization
+     * entirely. **Render the fixture first** (`fixture.detectChanges()`), because
+     * nothing here will do it for you; an unrendered fixture fails loudly with
+     * CDK's "failed to find element" rather than returning something wrong.
+     *
+     * Plain `loader.getHarness(TooltipHarness)` still works and is still supported.
+     * This is the path to use when a suite must not be able to hang.
+     */
+    static load(loader: HarnessLoader, options?: TooltipHarnessFilters): Promise<TooltipHarness>;
+    /** {@link load} for every matching trigger rather than the first. */
+    static loadAll(loader: HarnessLoader, options?: TooltipHarnessFilters): Promise<TooltipHarness[]>;
+    /** 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 };