ngwr 14.10.0 → 14.12.0

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

@@ -1,34 +1,18 @@
-import { BaseHarnessFilters, ContentContainerComponentHarness, HarnessPredicate, HarnessLoader } from '@angular/cdk/testing';
-import { WrPopoverPosition } from 'ngwr/popover';
-
-/**
- * @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
- */
-
+import { BaseHarnessFilters, ContentContainerComponentHarness, HarnessLoader, HarnessPredicate } from "@angular/cdk/testing";
+import { WrPopoverPosition } from "ngwr/popover";
 /** Narrows which `[wrPopover]` trigger a harness query matches. */
 interface WrPopoverHarnessFilters extends BaseHarnessFilters {
-    /**
-     * Match the trigger's own visible text — the label of the button (or link, or
-     * whatever the directive sits on), not the panel's content. A string is an
-     * exact match, a RegExp is tested.
-     */
-    readonly triggerText?: string | RegExp;
-    /** Match only popovers (`'popover'`) or only tooltips (`'tooltip'`). */
-    readonly mode?: 'popover' | 'tooltip';
-    /** Match only showing (`true`) or only hidden (`false`) panels. */
-    readonly open?: boolean;
+  /**
+   * Match the trigger's own visible text — the label of the button (or link, or
+   * whatever the directive sits on), not the panel's content. A string is an
+   * exact match, a RegExp is tested.
+   */
+  readonly triggerText?: string | RegExp;
+  /** Match only popovers (`'popover'`) or only tooltips (`'tooltip'`). */
+  readonly mode?: 'popover' | 'tooltip';
+  /** Match only showing (`true`) or only hidden (`false`) panels. */
+  readonly open?: boolean;
 }
-
-/**
- * @license
- *
- * Use of this source code is governed by an MIT-style license that can be
- * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
- */
-
 /**
  * Test harness for `[wrPopover]` — both shapes the one directive ships:
  *
@@ -67,177 +51,175 @@ interface WrPopoverHarnessFilters extends BaseHarnessFilters {
  *
  * @see https://ngwr.dev/guides/testing
  */
-declare class WrPopoverHarness extends ContentContainerComponentHarness {
-    /**
-     * The directive's host — whatever element the consumer put `[wrPopover]` on.
-     *
-     * Matched by the marker class, not by `[wrPopover]`: popover-mode content is a
-     * `TemplateRef` and so is always BOUND (`[wrPopover]="tpl"`), which leaves no
-     * attribute in the DOM at all, and a CLOSED tooltip publishes no ARIA either.
-     * (A tooltip written with the static string form, `wrPopover="Save changes"`,
-     * does keep the attribute — but only that one shape would be findable by it.)
-     * Same shape as `.wr-dropdown-trigger`.
-     */
-    static hostSelector: string;
-    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
-    static with(options?: WrPopoverHarnessFilters): HarnessPredicate<WrPopoverHarness>;
-    /**
-     * Which shape this trigger carries.
-     *
-     * Read from the ARIA contract, not from the `mode` input: a bound `[mode]`
-     * never reaches the DOM, while `aria-haspopup="dialog"` is on every popover
-     * trigger and on no tooltip trigger — a tooltip is a description of the
-     * control, not a popup it owns.
-     */
-    getMode(): Promise<'popover' | 'tooltip'>;
-    /** The trigger's own visible text. The panel's content is `getContentText()`. */
-    getTriggerText(): Promise<string>;
-    /**
-     * Whether the panel is showing.
-     *
-     * Two different signals because the two modes advertise different things: a
-     * popover flips `aria-expanded` on its trigger, a tooltip has none at all and
-     * links its description instead. So a tooltip's answer is only as good as the
-     * directive's claim on `aria-describedby` — put the tooltip on a control that
-     * is ALSO described by something else (a `<wr-form-field>` hint, say) and the
-     * two bindings fight over one attribute.
-     */
-    isOpen(): Promise<boolean>;
-    /**
-     * Open the panel with the gesture this trigger actually answers to, and wait
-     * until it is showing.
-     *
-     * `trigger` is an input, so the DOM does not say which gesture this popover
-     * wants — the harness moves the pointer on first and falls back to a click.
-     * Hover leads because a click is an outside pointer event for every OTHER open
-     * panel, so leading with it would dismiss someone else's popover on the way to
-     * opening this one; a click-driven popover ignores the hover outright. A
-     * tooltip is never clicked at all, and hover is the only one of its two
-     * gestures a harness can perform — the other is a keyboard focus, which is
-     * `FocusMonitor`'s to grant (see {@link focus}).
-     *
-     * Throws when nothing appears: a tooltip with an empty string never opens, and
-     * a spec on fake timers has to advance the clock itself.
-     */
-    open(timeout?: number): Promise<void>;
-    /**
-     * Dismiss the panel and wait until it is gone.
-     *
-     * Escape, because it is the one gesture both modes honour immediately: a
-     * popover is closed by the overlay's keyboard dispatcher, a tooltip by the
-     * directive's own binding — no delay in either. To exercise the delayed
-     * pointer path instead, call `mouseAway()` and then `waitUntilClosed()`.
-     */
-    close(timeout?: number): Promise<void>;
-    /** Click the trigger. Opens a click-driven popover, toggles it shut again, and does nothing else. */
-    click(): Promise<void>;
-    /** Move the pointer onto the trigger — opens a hover popover at once, a tooltip after `showDelay`. */
-    hover(): Promise<void>;
-    /** Move the pointer off the trigger. The panel goes after the grace period, not instantly. */
-    mouseAway(): Promise<void>;
-    /**
-     * Focus the trigger PROGRAMMATICALLY — and note that this does not open a
-     * tooltip.
-     *
-     * `TestElement.focus()` is a `.focus()` call, which is the one kind of focus a
-     * tooltip deliberately ignores: it shows for a KEYBOARD focus only, because
-     * every overlay in the catalog hands focus back to the trigger it was opened
-     * from, and a tooltip that answered those appeared with no pointer to leave and
-     * no focus to lose. So this method is the way to assert that NOTHING happens.
-     *
-     * There is no keyboard-origin twin, and it cannot be written honestly here:
-     * origin is `FocusMonitor`'s answer, this class has no injector, and the Tab
-     * that would earn it moves focus in a browser and not in jsdom. A spec that
-     * needs the opening gesture drives `FocusMonitor.focusVia(el, 'keyboard')`
-     * itself, the way `popover.spec.ts` does — or uses `hover()`.
-     */
-    focus(): Promise<void>;
-    /** Blur the trigger, which hides a tooltip after `hideDelay`. */
-    blur(): Promise<void>;
-    /** Press Escape on the trigger. Both modes dismiss on it, and neither moves focus. */
-    sendEscape(): Promise<void>;
-    /** Wait out a pending show. Resolves at once when the panel is already up. */
-    waitUntilOpen(timeout?: number): Promise<void>;
-    /** Wait out a pending hide. Resolves at once when the panel is already gone. */
-    waitUntilClosed(timeout?: number): Promise<void>;
-    /**
-     * The panel's text.
-     *
-     * In tooltip mode that is the string itself, rendered into the small text
-     * panel; in popover mode it is everything the projected template renders.
-     */
-    getContentText(): Promise<string>;
-    /**
-     * The role the open panel announces: `'dialog'` for a popover, `'tooltip'` for
-     * a tooltip.
-     *
-     * Worth asserting rather than assuming, twice over: the directive sets it on
-     * the OVERLAY PANE, not on the content a consumer wrote, and in tooltip mode
-     * the pane is deliberately the only element carrying it — the text panel
-     * inside has none, or the description would nest a tooltip in a tooltip.
-     */
-    getRole(): Promise<string | null>;
-    /**
-     * The panel's accessible name — `null` in tooltip mode.
-     *
-     * A popover is a named `role="dialog"`: the `ariaLabel` input, or the i18n
-     * catalog's `popover.label` when the consumer says nothing, because an unnamed
-     * dialog announces as "dialog" and nothing else. A tooltip has no name of its
-     * own; it IS the trigger's description, which is `getDescriptionText()`.
-     */
-    getLabel(): Promise<string | null>;
-    /**
-     * Whether the panel claims modality.
-     *
-     * `false`, deliberately, and worth pinning: the popover sets
-     * `aria-modal="false"` because focus is NOT trapped and the panel dismisses on
-     * outside click / Escape rather than blocking the page.
-     */
-    isModal(): Promise<boolean>;
-    /**
-     * Where the panel sits relative to the trigger, or `null` when it is presented
-     * as a sheet and has no anchor.
-     *
-     * The APPLIED position, not the requested one: CDK flips a placement that does
-     * not fit to the next in its fallback chain and swaps the modifier class with
-     * it. Under a unit test that is always the requested placement — jsdom measures
-     * every box as 0×0, so the first candidate always "fits" — but in a browser the
-     * two can differ, and this answers what is on screen. The directive defaults
-     * the request per mode (`bottom` for a popover, `top` for a tooltip).
-     *
-     * The arrow itself is a `::after` pseudo-element, so it exists for no DOM query
-     * at all; this class is the placement, and it is what the arrow's own CSS keys
-     * off.
-     */
-    getPosition(): Promise<WrPopoverPosition | null>;
-    /** Whether the popover is presented as a full-width bottom sheet instead of an anchored panel. */
-    isSheet(): Promise<boolean>;
-    /**
-     * The text a screen reader reads as the TRIGGER'S DESCRIPTION, or `null` when
-     * it describes nothing.
-     *
-     * This resolves `aria-describedby` the way an assistive technology would, so
-     * it answers the whole of tooltip mode's naming contract in one call. Always
-     * `null` for a popover, open or shut — a popover is a thing the trigger owns
-     * (`aria-haspopup` / `aria-expanded`), never a description of it.
-     */
-    getDescriptionText(): Promise<string | null>;
-    /**
-     * Harnesses for the consumer's own components are resolved inside THIS
-     * instance's panel.
-     *
-     * Scoped by the published id rather than by `.wr-popover-overlay`: the overlay
-     * container is shared, so a class query would answer with whichever popover
-     * opened first.
-     */
-    protected getRootHarnessLoader(): Promise<HarnessLoader>;
-    /** Poll until `isOpen()` reports `open`, and say whether it did. */
-    private settled;
-    /** This instance's overlay pane. */
-    private panel;
-    /** The id the trigger publishes for its panel, which only exists while the panel does. */
-    private panelId;
+export declare class WrPopoverHarness extends ContentContainerComponentHarness {
+  /**
+   * The directive's host — whatever element the consumer put `[wrPopover]` on.
+   *
+   * Matched by the marker class, not by `[wrPopover]`: popover-mode content is a
+   * `TemplateRef` and so is always BOUND (`[wrPopover]="tpl"`), which leaves no
+   * attribute in the DOM at all, and a CLOSED tooltip publishes no ARIA either.
+   * (A tooltip written with the static string form, `wrPopover="Save changes"`,
+   * does keep the attribute — but only that one shape would be findable by it.)
+   * Same shape as `.wr-dropdown-trigger`.
+   */
+  static hostSelector: string;
+  /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+  static with(options?: WrPopoverHarnessFilters): HarnessPredicate<WrPopoverHarness>;
+  /**
+   * Which shape this trigger carries.
+   *
+   * Read from the ARIA contract, not from the `mode` input: a bound `[mode]`
+   * never reaches the DOM, while `aria-haspopup="dialog"` is on every popover
+   * trigger and on no tooltip trigger — a tooltip is a description of the
+   * control, not a popup it owns.
+   */
+  getMode(): Promise<'popover' | 'tooltip'>;
+  /** The trigger's own visible text. The panel's content is `getContentText()`. */
+  getTriggerText(): Promise<string>;
+  /**
+   * Whether the panel is showing.
+   *
+   * Two different signals because the two modes advertise different things: a
+   * popover flips `aria-expanded` on its trigger, a tooltip has none at all and
+   * links its description instead. So a tooltip's answer is only as good as the
+   * directive's claim on `aria-describedby` — put the tooltip on a control that
+   * is ALSO described by something else (a `<wr-form-field>` hint, say) and the
+   * two bindings fight over one attribute.
+   */
+  isOpen(): Promise<boolean>;
+  /**
+   * Open the panel with the gesture this trigger actually answers to, and wait
+   * until it is showing.
+   *
+   * `trigger` is an input, so the DOM does not say which gesture this popover
+   * wants — the harness moves the pointer on first and falls back to a click.
+   * Hover leads because a click is an outside pointer event for every OTHER open
+   * panel, so leading with it would dismiss someone else's popover on the way to
+   * opening this one; a click-driven popover ignores the hover outright. A
+   * tooltip is never clicked at all, and hover is the only one of its two
+   * gestures a harness can perform — the other is a keyboard focus, which is
+   * `FocusMonitor`'s to grant (see {@link focus}).
+   *
+   * Throws when nothing appears: a tooltip with an empty string never opens, and
+   * a spec on fake timers has to advance the clock itself.
+   */
+  open(timeout?: number): Promise<void>;
+  /**
+   * Dismiss the panel and wait until it is gone.
+   *
+   * Escape, because it is the one gesture both modes honour immediately: a
+   * popover is closed by the overlay's keyboard dispatcher, a tooltip by the
+   * directive's own binding — no delay in either. To exercise the delayed
+   * pointer path instead, call `mouseAway()` and then `waitUntilClosed()`.
+   */
+  close(timeout?: number): Promise<void>;
+  /** Click the trigger. Opens a click-driven popover, toggles it shut again, and does nothing else. */
+  click(): Promise<void>;
+  /** Move the pointer onto the trigger — opens a hover popover at once, a tooltip after `showDelay`. */
+  hover(): Promise<void>;
+  /** Move the pointer off the trigger. The panel goes after the grace period, not instantly. */
+  mouseAway(): Promise<void>;
+  /**
+   * Focus the trigger PROGRAMMATICALLY — and note that this does not open a
+   * tooltip.
+   *
+   * `TestElement.focus()` is a `.focus()` call, which is the one kind of focus a
+   * tooltip deliberately ignores: it shows for a KEYBOARD focus only, because
+   * every overlay in the catalog hands focus back to the trigger it was opened
+   * from, and a tooltip that answered those appeared with no pointer to leave and
+   * no focus to lose. So this method is the way to assert that NOTHING happens.
+   *
+   * There is no keyboard-origin twin, and it cannot be written honestly here:
+   * origin is `FocusMonitor`'s answer, this class has no injector, and the Tab
+   * that would earn it moves focus in a browser and not in jsdom. A spec that
+   * needs the opening gesture drives `FocusMonitor.focusVia(el, 'keyboard')`
+   * itself, the way `popover.spec.ts` does — or uses `hover()`.
+   */
+  focus(): Promise<void>;
+  /** Blur the trigger, which hides a tooltip after `hideDelay`. */
+  blur(): Promise<void>;
+  /** Press Escape on the trigger. Both modes dismiss on it, and neither moves focus. */
+  sendEscape(): Promise<void>;
+  /** Wait out a pending show. Resolves at once when the panel is already up. */
+  waitUntilOpen(timeout?: number): Promise<void>;
+  /** Wait out a pending hide. Resolves at once when the panel is already gone. */
+  waitUntilClosed(timeout?: number): Promise<void>;
+  /**
+   * The panel's text.
+   *
+   * In tooltip mode that is the string itself, rendered into the small text
+   * panel; in popover mode it is everything the projected template renders.
+   */
+  getContentText(): Promise<string>;
+  /**
+   * The role the open panel announces: `'dialog'` for a popover, `'tooltip'` for
+   * a tooltip.
+   *
+   * Worth asserting rather than assuming, twice over: the directive sets it on
+   * the OVERLAY PANE, not on the content a consumer wrote, and in tooltip mode
+   * the pane is deliberately the only element carrying it — the text panel
+   * inside has none, or the description would nest a tooltip in a tooltip.
+   */
+  getRole(): Promise<string | null>;
+  /**
+   * The panel's accessible name — `null` in tooltip mode.
+   *
+   * A popover is a named `role="dialog"`: the `ariaLabel` input, or the i18n
+   * catalog's `popover.label` when the consumer says nothing, because an unnamed
+   * dialog announces as "dialog" and nothing else. A tooltip has no name of its
+   * own; it IS the trigger's description, which is `getDescriptionText()`.
+   */
+  getLabel(): Promise<string | null>;
+  /**
+   * Whether the panel claims modality.
+   *
+   * `false`, deliberately, and worth pinning: the popover sets
+   * `aria-modal="false"` because focus is NOT trapped and the panel dismisses on
+   * outside click / Escape rather than blocking the page.
+   */
+  isModal(): Promise<boolean>;
+  /**
+   * Where the panel sits relative to the trigger, or `null` when it is presented
+   * as a sheet and has no anchor.
+   *
+   * The APPLIED position, not the requested one: CDK flips a placement that does
+   * not fit to the next in its fallback chain and swaps the modifier class with
+   * it. Under a unit test that is always the requested placement — jsdom measures
+   * every box as 0×0, so the first candidate always "fits" — but in a browser the
+   * two can differ, and this answers what is on screen. The directive defaults
+   * the request per mode (`bottom` for a popover, `top` for a tooltip).
+   *
+   * The arrow itself is a `::after` pseudo-element, so it exists for no DOM query
+   * at all; this class is the placement, and it is what the arrow's own CSS keys
+   * off.
+   */
+  getPosition(): Promise<WrPopoverPosition | null>;
+  /** Whether the popover is presented as a full-width bottom sheet instead of an anchored panel. */
+  isSheet(): Promise<boolean>;
+  /**
+   * The text a screen reader reads as the TRIGGER'S DESCRIPTION, or `null` when
+   * it describes nothing.
+   *
+   * This resolves `aria-describedby` the way an assistive technology would, so
+   * it answers the whole of tooltip mode's naming contract in one call. Always
+   * `null` for a popover, open or shut — a popover is a thing the trigger owns
+   * (`aria-haspopup` / `aria-expanded`), never a description of it.
+   */
+  getDescriptionText(): Promise<string | null>;
+  /**
+   * Harnesses for the consumer's own components are resolved inside THIS
+   * instance's panel.
+   *
+   * Scoped by the published id rather than by `.wr-popover-overlay`: the overlay
+   * container is shared, so a class query would answer with whichever popover
+   * opened first.
+   */
+  protected getRootHarnessLoader(): Promise<HarnessLoader>;
+  /** Poll until `isOpen()` reports `open`, and say whether it did. */
+  private settled;
+  /** This instance's overlay pane. */
+  private panel;
+  /** The id the trigger publishes for its panel, which only exists while the panel does. */
+  private panelId;
 }
-
-export { WrPopoverHarness };
-export type { WrPopoverHarnessFilters };
+export type { WrPopoverHarnessFilters };