@cdevhub/ngx-tw 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdevhub/ngx-tw",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Angular component library for Tailwind CSS v4 — accessible, signal-based, built on Angular CDK.",
   "keywords": [
     "angular",

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

@@ -1,4 +1,4 @@
-import { ComponentHarness, HarnessLoader, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
+import { ComponentHarness, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
 
 /** Filters accepted by `PopoverHarness.with`. */
 interface PopoverHarnessFilters extends BaseHarnessFilters {
@@ -8,40 +8,6 @@ interface PopoverHarnessFilters extends BaseHarnessFilters {
 /**
  * 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
@@ -57,6 +23,17 @@ interface PopoverHarnessFilters extends BaseHarnessFilters {
  * 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
@@ -66,29 +43,6 @@ interface PopoverHarnessFilters extends BaseHarnessFilters {
  */
 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. */
@@ -122,10 +76,7 @@ declare class PopoverHarness extends ComponentHarness {
      * 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`.
-     */
+    /** 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

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

@@ -1,4 +1,4 @@
-import { ComponentHarness, HarnessLoader, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
+import { ComponentHarness, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
 
 /** Filters accepted by `TooltipHarness.with`. */
 interface TooltipHarnessFilters extends BaseHarnessFilters {
@@ -13,44 +13,6 @@ interface TooltipHarnessFilters extends BaseHarnessFilters {
  * 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
@@ -71,34 +33,24 @@ interface TooltipHarnessFilters extends BaseHarnessFilters {
  * 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;
-    /**
-     * 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. */