ngwr 14.7.0 → 14.9.0

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

@@ -0,0 +1,378 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate, TestKey, ModifierKeys } from '@angular/cdk/testing';
+import { WrButtonHarness } from 'ngwr/button/testing';
+import { WrPopoverHarness } from 'ngwr/popover/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
+ */
+
+/** Narrows which `<wr-editor>` a harness query matches. */
+interface WrEditorHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the text surface's accessible name — its `ariaLabel`, the surrounding
+     * `<wr-form-field>`'s label, or the catalog default, in that order. A string is an
+     * exact match, a RegExp is tested.
+     */
+    readonly label?: string | RegExp;
+    /**
+     * Match the text the surface DRAWS — see `WrEditorHarness.getText`, which is where
+     * the blocks are joined and the task-item words left out. A string is an exact
+     * match, a RegExp is tested.
+     */
+    readonly text?: string | RegExp;
+    /** Match only enabled (`false`) or only disabled (`true`) editors. */
+    readonly disabled?: boolean;
+    /** Match only writable (`false`) or only read-only (`true`) editors. */
+    readonly readonly?: 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 `<wr-editor>` — a ProseMirror text surface, the formatting
+ * toolbar above it, and the link panel one of its buttons opens.
+ *
+ * **The value is not read here, and that is the first thing to know.** The model
+ * holds an HTML string, a markdown string or a JSON tree depending on `format`, and
+ * all three are written by the editor's codec, never by the DOM. What the surface
+ * draws is ProseMirror's rendering of the document — a trailing `<br>` in an empty
+ * paragraph, a presentational box beside a task item — so a string derived from it
+ * would be a fourth format agreeing with none of the three. A spec reads the value
+ * from what it bound (`form.body().value()`, the `[(value)]` signal); this harness
+ * answers the other question, what is DRAWN ({@link getText}), and a spec on an
+ * editor should usually ask both.
+ *
+ * Four more things are refused, each because jsdom cannot answer it and a method
+ * would answer it anyway:
+ *
+ * - **Typing, character by character.** `sendKeys` dispatches key events and nothing
+ *   else. In a browser the BROWSER inserts the character into the contenteditable and
+ *   ProseMirror reads the mutation; jsdom inserts nothing, so a typed string would
+ *   vanish while the call resolved. {@link setText} writes the surface the way the
+ *   CDK defines writing a contenteditable, which ProseMirror reads as a real DOM
+ *   change; {@link paste} inserts at the selection; {@link pressKey} refuses a
+ *   printable character without a modifier rather than dropping it.
+ * - **A caret or a selected range.** Placing either needs a DOM selection inside a
+ *   text node, which no `TestElement` call can create. {@link selectAll} is the one
+ *   selection a keyboard makes without a coordinate, and it is the one offered.
+ * - **Anything measured** — the height between `--wr-editor-min-height` and
+ *   `-max-height`, a scroll, how the toolbar wraps, where a tooltip lands. Every box
+ *   is 0×0 without layout.
+ * - **Whether the placeholder is visible.** It is CSS `content` drawn from a data
+ *   attribute, which no DOM query sees; {@link getPlaceholder} reads what is
+ *   ANNOUNCED, and that is only there while the document is empty.
+ *
+ * Toolbar buttons are addressed by the name a screen reader reads — `Bold`,
+ * `Heading 2`, `Insert link` in English, the catalog's words otherwise — because the
+ * DOM carries nothing else to tell them apart, and that name is the contract anyway.
+ * {@link getTool} hands back a `WrButtonHarness`; what that harness does not read
+ * (`aria-pressed`, `aria-keyshortcuts`, the roving tab stop) is answered here.
+ *
+ * Every method reads the MOUNTED surface. ProseMirror takes it over in
+ * `afterNextRender`, which the harness's own stabilising lets run; under a server
+ * `PLATFORM_ID` it never does, and the static preview the server renders is not
+ * something this harness pretends to be the editor.
+ *
+ * **A spec under jsdom installs one stub first.** After an edit made while the
+ * surface has focus, ProseMirror scrolls the selection into view, which measures a
+ * `Range` — and jsdom's `Range` has no `getClientRects()`. The throw comes AFTER the
+ * document changed but before the model hears of it, from inside a DOM listener, so
+ * the model keeps the old value and the error surfaces only as an unhandled one. Empty
+ * boxes are the whole stub; nothing here measures anything, so nothing is lost:
+ *
+ * ```ts
+ * beforeEach(() => {
+ *   Range.prototype.getClientRects = () => [] as unknown as DOMRectList;
+ *   Range.prototype.getBoundingClientRect = () => new DOMRect();
+ *   document.elementFromPoint = () => null;
+ * });
+ * // …and delete all three again in afterEach, so no other file inherits them.
+ * ```
+ *
+ * @example
+ * ```ts
+ * const loader = TestbedHarnessEnvironment.loader(fixture);
+ * const body = await loader.getHarness(WrEditorHarness.with({ label: 'Body' }));
+ *
+ * await body.setText('Release notes');
+ * await body.selectAll();
+ * await (await body.getTool('Bold')).click();
+ *
+ * expect(await body.isToolPressed('Bold')).toBe(true);
+ * expect(host.value()).toBe('<p><strong>Release notes</strong></p>');
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrEditorHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrEditorHarnessFilters): HarnessPredicate<WrEditorHarness>;
+    private readonly surface;
+    /**
+     * Whether ProseMirror owns the surface yet — read from the `contenteditable` it
+     * writes there, which nothing else does.
+     *
+     * `true` in any browser-platform spec by the time a harness method runs. `false`
+     * under a server `PLATFORM_ID`, where the editor is the static preview for good —
+     * and every other method here throws, rather than answer about a preview as if it
+     * were the editor.
+     */
+    isMounted(): Promise<boolean>;
+    /**
+     * The text the surface DRAWS: every textblock (paragraph, heading, code block) in
+     * document order, each trimmed, joined with a newline.
+     *
+     * Joined per textblock rather than read in one go, because a single text read of the
+     * surface glues two paragraphs into one word — `Hello` and `world` would come back
+     * as `Helloworld`. A list item, a quote and a table cell draw their text in
+     * paragraphs too, so a two-item list reads `One\nTwo`. Left out, deliberately: a task
+     * item's `Done:` / `To do:` — screen-reader text beside the paragraph, not in it —
+     * and a hard break, which is a `<br>` and has no text. An empty document is `''`.
+     *
+     * This is the drawn half of the two questions an editor answers; the class docs say
+     * why the other half, the value, is read from the model instead.
+     */
+    getText(): Promise<string>;
+    /**
+     * The surface's accessible name — `ariaLabel` when one is bound, else the
+     * surrounding `<wr-form-field>`'s label, else the catalog's `editor.label`.
+     *
+     * A field's label reaches the surface through `aria-labelledby`, never `<label for>`:
+     * a contenteditable is not labelable. So the reference is resolved the way assistive
+     * technology resolves it — each id's element, its text — and a reference to an
+     * element that is not on the page contributes nothing, which is the failure worth
+     * catching.
+     */
+    getLabel(): Promise<string | null>;
+    /**
+     * The placeholder as announced — `aria-placeholder` — or `null` when there is none
+     * to announce.
+     *
+     * That is `null` whenever the document holds anything, not only when no
+     * `placeholder` is bound: the component publishes it only while the document is
+     * empty, the moment it is also drawn. A document holding an empty heading still
+     * counts as empty.
+     */
+    getPlaceholder(): Promise<string | null>;
+    /**
+     * Whether the editor is disabled — the surface's `aria-disabled`.
+     *
+     * Read from the surface rather than the `wr-editor--disabled` host class, because a
+     * contenteditable has no `disabled` property: the attribute is what a screen reader
+     * is told, and ProseMirror's own `contenteditable="false"` is what turns the
+     * keyboard away. The component sets both.
+     */
+    isDisabled(): Promise<boolean>;
+    /**
+     * Whether the editor shows its document and refuses edits — the surface's
+     * `aria-readonly`, which `role="textbox"` allows. Read-only keeps the tab stop, so
+     * {@link focus} still lands; disabled does not.
+     */
+    isReadonly(): Promise<boolean>;
+    /**
+     * Whether the surface is announced invalid — the `aria-invalid` the surrounding
+     * `<wr-form-field>` hands it when a bound field fails validation and has been
+     * touched. An editor outside a field is never invalid.
+     */
+    isInvalid(): Promise<boolean>;
+    /**
+     * Replace the whole document with `text`, as one paragraph of plain text.
+     *
+     * Written through `TestElement.setContenteditableValue` — the CDK's own definition of
+     * writing a contenteditable — which ProseMirror observes as a DOM change and parses
+     * back through the schema, exactly as it does the mutation a browser makes for a
+     * keystroke. So the write reaches the model through the editor's own path, filters
+     * and all. A line break in `text` becomes a hard break inside that one paragraph,
+     * the way Shift+Enter makes one; more paragraphs, lists and headings come from the
+     * toolbar, {@link pressKey} or {@link pasteHtml}.
+     *
+     * An empty `text` empties the document, which writes `''` (`null` in `json` format).
+     *
+     * Throws on a disabled or read-only editor, where no user could change a word — the
+     * surface is not contenteditable then, and a write the DOM accepted anyway would be
+     * a green spec for something that cannot happen.
+     */
+    setText(text: string): Promise<void>;
+    /**
+     * Paste `text` as plain text at the selection, replacing whatever is selected — a
+     * `paste` event carrying `text/plain`, handled by ProseMirror's own paste path.
+     *
+     * On a READ-ONLY editor the event is still delivered, because a browser delivers it:
+     * the refusal is the editor's to make, and asserting the value did not change is how
+     * a spec proves it did. Throws on a disabled one, whose surface cannot hold focus for
+     * a paste to arrive at.
+     */
+    paste(text: string): Promise<void>;
+    /**
+     * Paste `html` at the selection, the way content copied from a web page arrives —
+     * `text/html` with `text` as its `text/plain` twin.
+     *
+     * This is the path to exercise what the editor strips from untrusted markup: the
+     * pasted HTML is parsed without executing anything and rebuilt from the schema,
+     * exactly as a bound HTML value is, so `onclick`, a `javascript:` link or an
+     * `<iframe>` never reaches the document. Read-only and disabled behave as in
+     * {@link paste}.
+     */
+    pasteHtml(html: string, text?: string): Promise<void>;
+    /**
+     * Select the whole document with the platform's select-all chord, as ProseMirror's
+     * keymap reads it.
+     *
+     * Throws on a read-only or disabled editor: ProseMirror hands the keyboard back to
+     * the browser once the surface is not editable, and the browser's native select-all
+     * is exactly what jsdom does not have, so the chord would select nothing and say so
+     * to no one.
+     */
+    selectAll(): Promise<void>;
+    /**
+     * Press one key on the surface, with modifiers — Enter, Backspace, an arrow, or a
+     * shortcut such as `pressKey('b', { control: true })`.
+     *
+     * The keys reach ProseMirror's keymap, which is where the shortcuts, the list
+     * behaviour of Enter and history live. Under jsdom, ProseMirror reads `Mod` as
+     * Control; {@link getToolShortcuts} names the chord each tool answers to.
+     *
+     * A printable character WITHOUT a Control, Meta or Alt modifier throws: inserting it
+     * is the browser's job, not the key event's (see the class docs), so it would be
+     * dropped while the call resolved — use {@link setText} or {@link paste}. Throws on a
+     * disabled editor, whose surface is out of the tab order. A read-only one takes the
+     * key and refuses whatever it would have changed, as it does in a browser.
+     */
+    pressKey(key: TestKey | string, modifiers?: ModifierKeys): Promise<void>;
+    /**
+     * Move focus to the text surface. A read-only editor keeps its tab stop and takes
+     * it.
+     *
+     * Throws on a disabled one rather than focusing it. In a browser its surface cannot
+     * take focus — no `tabindex`, and `contenteditable="false"` — but jsdom counts ANY
+     * `contenteditable` attribute as focusable, `false` included, so the focus would
+     * land in the spec and never in the app.
+     */
+    focus(): Promise<void>;
+    /**
+     * Take focus away from the surface — the whole control losing focus, which is what
+     * emits `touch` and lets a bound field show its error. Focus moving to the editor's
+     * own toolbar or link panel is not a blur of the control, and does not emit it.
+     */
+    blur(): Promise<void>;
+    /** Whether the text surface holds focus. A toolbar button holding it is not the surface. */
+    isFocused(): Promise<boolean>;
+    /** Whether a toolbar is drawn — gone with `toolbar="false"`, and with a list holding no tool. */
+    hasToolbar(): Promise<boolean>;
+    /** The toolbar's accessible name — the catalog's `editor.toolbar`. Throws when there is no toolbar. */
+    getToolbarLabel(): Promise<string | null>;
+    /**
+     * The names of the drawn tools, in order, separators left out.
+     *
+     * What is DRAWN, which is not always what was bound: `underline` is dropped in
+     * `markdown` format, which cannot store it, and a duplicate or a stray separator is
+     * dropped too.
+     */
+    getToolLabels(): Promise<string[]>;
+    /**
+     * The toolbar button named `label`, as a `WrButtonHarness` — click it, focus it, ask
+     * whether it is disabled.
+     *
+     * A tool the current selection cannot use is NATIVELY disabled, so its click never
+     * fires; that is the answer to "can bold apply here", read with `isDisabled()`. Its
+     * tooltip — the name plus the shortcut — is a `[wrPopover]` in tooltip mode, which
+     * `WrPopoverHarness` reads when a spec cares about the wording.
+     */
+    getTool(label: string | RegExp): Promise<WrButtonHarness>;
+    /**
+     * Whether a toggle tool is pressed — its `aria-pressed` — at the current selection.
+     *
+     * The marks answer for the selection (or, at a caret, for what typing would carry);
+     * the block types answer for every textblock the selection touches, so a select-all
+     * over a heading and a paragraph presses neither.
+     *
+     * Throws for a tool that is not a toggle: the link button opens a panel, and undo,
+     * redo and the horizontal rule are actions, so none carries `aria-pressed` and a
+     * `false` would claim a state they do not have. Whether the selection sits in a link
+     * is what the link panel's remove button answers — see {@link removeLink}.
+     */
+    isToolPressed(label: string | RegExp): Promise<boolean>;
+    /**
+     * The chords a tool answers to, as its `aria-keyshortcuts` states them
+     * (`Control+B`, `Control+Shift+Z Control+Y`), or `null` for a tool with none — the
+     * horizontal rule.
+     *
+     * ARIA key names, never localised; `Meta` replaces `Control` where the user agent is
+     * Apple's.
+     */
+    getToolShortcuts(label: string | RegExp): Promise<string | null>;
+    /**
+     * The name of the one tool in the tab order, or `null` when there is none.
+     *
+     * The toolbar is a single tab stop that the arrow keys rove. The stop follows the
+     * user, and moves off a tool that stopped applying — so after a click that disables
+     * undo, it lands on the first tool that still applies. `null` only when nothing does
+     * (read-only, disabled), where there is nothing for the keyboard to reach.
+     */
+    getToolbarTabStop(): Promise<string | null>;
+    /** Whether the link panel is open, from the link tool's `aria-expanded`. `false` when there is no link tool. */
+    isLinkPanelOpen(): Promise<boolean>;
+    /**
+     * Open the link panel from its toolbar button and hand back the popover — a
+     * content container, so `panel.getHarness(WrInputHarness)` reaches the address
+     * field without the spec touching the overlay. An open panel is returned as it is.
+     *
+     * The panel is a portal in the overlay container, reached through the id the
+     * button publishes as `aria-controls`, never by its class: two editors can each have
+     * one. Mod-K on the surface opens the same panel — `pressKey('k', { control: true })`.
+     *
+     * Throws when the toolbar draws no link tool, or when the tool is unavailable (a
+     * read-only or disabled editor).
+     */
+    openLinkPanel(): Promise<WrPopoverHarness>;
+    /**
+     * Link the selection to `url` through the panel: open it, write the address, apply.
+     *
+     * With text selected, the selection becomes the link; with the caret inside a link,
+     * that link's address changes; with nothing selected at all, the address is inserted
+     * as its own linked text. An emptied address on an existing link removes it.
+     *
+     * Resolves whether or not the address was accepted. One the URL policy refuses — a
+     * `javascript:` or `data:` scheme — leaves the panel OPEN with its error showing and
+     * the document untouched, which is the behaviour a spec most wants to pin; read it
+     * with {@link getLinkError} and {@link isLinkPanelOpen}.
+     */
+    setLink(url: string): Promise<void>;
+    /**
+     * Remove the link the selection sits in or covers, through the panel's remove button.
+     *
+     * Throws when the selection is in no link: the panel draws the button only then, so
+     * its absence IS the answer to "is there a link here".
+     */
+    removeLink(): Promise<void>;
+    /**
+     * The message the open panel shows for a refused address, or `null` when it shows
+     * none. It is a `role="alert"`, and the address field names it with
+     * `aria-describedby` — so the text a screen reader hears is the text read here.
+     *
+     * Throws while the panel is closed: the message only exists inside it, and a `null`
+     * would read as "the address was accepted".
+     */
+    getLinkError(): Promise<string | null>;
+    /** The surface, or a sentence saying the editor is still the server's static preview. */
+    private mountedSurface;
+    /** The surface, when a user could still reach it with the keyboard. */
+    private focusableSurface;
+    /** The surface, when a user could change its text. */
+    private writableSurface;
+    private dispatchPaste;
+    private toolbar;
+    private linkPopover;
+}
+
+export { WrEditorHarness };
+export type { WrEditorHarnessFilters };