ngwr 10.2.1 → 11.0.0

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

@@ -0,0 +1,462 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/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
+ */
+/**
+ * What these types are, and why they keep `Harness` in their names.
+ *
+ * `ngwr/markdown` already exports a node tree — `WrMarkdownBlock`,
+ * `WrMarkdownListItem`, `WrMarkdownCell` — which is what the PARSER produced. The
+ * types here are what the DOM says afterwards, and a spec imports both entry
+ * points, so a second `WrMarkdownListItem` in scope would be one import line away
+ * from an assertion about the wrong half of the pipeline. They are deliberately
+ * flat snapshots rather than harnesses: rendered prose is inert, there is nothing
+ * to drive, and a `toEqual` over one object says more than six awaited reads.
+ */
+/**
+ * How a table column is aligned, as the delimiter row asked for it.
+ *
+ * Logical values, never `left` / `right`: the alignment mirrors under `dir="rtl"`
+ * on its own, and a harness reporting the physical edge would make an RTL
+ * regression look like the intended behaviour. `null` is a column the delimiter
+ * row said nothing about.
+ */
+type WrMarkdownHarnessAlign = 'start' | 'center' | 'end' | null;
+/** One rendered heading. */
+interface WrMarkdownHarnessHeading {
+    /**
+     * The heading level, 1–6, read from the ELEMENT the renderer chose.
+     *
+     * Not from an `aria-level` or a class: `<wr-markdown>` renders a real `<h1>` …
+     * `<h6>`, which is what carries the level to assistive technology and to every
+     * stylesheet, and a `<div role="heading">` regression has to show up here.
+     */
+    readonly level: number;
+    /** The heading's text, whitespace collapsed. */
+    readonly text: string;
+    /**
+     * The slug the document can be linked into, or `null` when `headingIds` is off.
+     *
+     * `null` is the whole reason this is reported rather than assumed: an anchor
+     * that silently stops being generated breaks every deep link into the page and
+     * changes nothing on screen.
+     */
+    readonly id: string | null;
+}
+/** One rendered link. */
+interface WrMarkdownHarnessLink {
+    /** The link's visible text. */
+    readonly text: string;
+    /** The `href` attribute as written, unresolved — a relative path stays relative. */
+    readonly href: string | null;
+    /** The link's `title`, or `null` when the source gave none. */
+    readonly title: string | null;
+    /** Where the link opens, or `null` when `linkTarget` is off. */
+    readonly target: string | null;
+    /**
+     * The `rel`, which is not decoration: a `target="_blank"` without
+     * `noopener noreferrer` hands `window.opener` to a page whose URL came out of
+     * the document being rendered — untrusted input, by construction. Assert the
+     * pair together.
+     */
+    readonly rel: string | null;
+}
+/** One rendered image. */
+interface WrMarkdownHarnessImage {
+    /** The `src` attribute as written. A refused URL renders no image at all. */
+    readonly src: string | null;
+    /** The alt text — also what a refused `src` leaves behind as plain text. */
+    readonly alt: string | null;
+    /** The image's `title`, or `null` when the source gave none. */
+    readonly title: string | null;
+}
+/** One rendered task-list item. */
+interface WrMarkdownHarnessTaskItem {
+    /**
+     * The item's visible text, with the hidden state label left out — so this is
+     * `'ship it'` and not `'Done: ship it'`.
+     */
+    readonly text: string;
+    /** Whether the box is ticked (`- [x]`). */
+    readonly checked: boolean;
+    /**
+     * The state as assistive technology hears it, or `null` when nothing announces
+     * it.
+     *
+     * The tick is a presentational `<span aria-hidden>` — a real
+     * `<input type="checkbox">` would be an unlabelled form control, and making it
+     * operable would promise an interaction a renderer cannot honour — so this
+     * hidden text is the ONLY thing that carries the state to a screen reader. It
+     * comes from `taskDoneLabel` / `taskTodoLabel`, so it is localized, and `null`
+     * here is a checked box nobody is told about.
+     */
+    readonly stateLabel: string | null;
+}
+/** One rendered GFM table, as a snapshot. */
+interface WrMarkdownHarnessTable {
+    /** The header cells, in column order. */
+    readonly headers: string[];
+    /**
+     * The body rows, one array of cell text per row.
+     *
+     * Every row is as wide as the header — the renderer pads a short row and
+     * truncates a long one — so this is a rectangle, which is what makes it
+     * assertable in one `toEqual`.
+     */
+    readonly rows: string[][];
+    /** One entry per column, in the same order as {@link headers}. */
+    readonly align: WrMarkdownHarnessAlign[];
+}
+
+/**
+ * @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-markdown>` a harness query matches. */
+interface WrMarkdownHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the document's rendered text — whitespace collapsed, the hidden
+     * task-state labels left out, the way `getText()` reads it.
+     *
+     * A string is an exact match against the WHOLE document, which is almost never
+     * what a spec means for anything longer than a line; a RegExp is tested, which
+     * is.
+     */
+    readonly text?: string | RegExp;
+    /**
+     * Match a document that renders a heading with this text, at any level.
+     *
+     * The heading rather than the first line: a document's title is the one piece
+     * of it a spec can name without restating its contents.
+     */
+    readonly headingText?: string | RegExp;
+    /**
+     * Match a document that renders a fenced block in this language.
+     *
+     * The language is the info string's first word, lowercased — what the renderer
+     * puts in `data-language`. A BARE fence claims none, so no filter value finds
+     * one: `<wr-markdown>` cannot report a language nobody wrote.
+     */
+    readonly codeLanguage?: string | RegExp;
+    /**
+     * Match only streaming (`true`) or only settled (`false`) documents.
+     *
+     * Read from the host modifier the caret is painted with, so this is the
+     * document's rendered state and not the input that asked for it.
+     */
+    readonly streaming?: boolean;
+}
+/** Narrows which fenced code block of a document a harness query matches. */
+interface WrMarkdownCodeBlockHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the block's language — a string is an exact match, a RegExp is tested.
+     *
+     * A bare fence has no language and matches neither form.
+     */
+    readonly language?: string | RegExp;
+    /**
+     * Match the block's code.
+     *
+     * A string is an exact match against the whole snippet, newlines and
+     * indentation included — that is the point of the block, and it is also why a
+     * RegExp is usually the form worth writing here.
+     */
+    readonly code?: string | RegExp;
+}
+
+/**
+ * @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 one fenced code block of a `<wr-markdown>` document.
+ *
+ * A block of its own rather than a field on the document harness, because it is
+ * the one piece of rendered markdown that has BEHAVIOUR: it carries a language, it
+ * may or may not be coloured yet, and it may offer a copy button — three states
+ * that belong to the block and not to the page it is on.
+ *
+ * Its host is the `.wr-markdown__code-block` wrapper, which is what holds the
+ * `<pre>` and the copy button together. Blocks nested inside a quote or a list item
+ * are blocks too, and this harness finds them: `<wr-markdown>` renders them the
+ * same way, and the copy affordance is theirs as well.
+ *
+ * @example
+ * ```ts
+ * const block = await (await loader.getHarness(WrMarkdownHarness)).getCodeBlock({ language: 'ts' });
+ *
+ * expect(await block.getCode()).toBe('const a = 1;');
+ * await block.copy();
+ * ```
+ *
+ * @see https://ngwr.dev/reference/components/markdown
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrMarkdownCodeBlockHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrMarkdownCodeBlockHarnessFilters): HarnessPredicate<WrMarkdownCodeBlockHarness>;
+    private readonly pre;
+    private readonly code;
+    private readonly copyButton;
+    /**
+     * The block's language — the info string's first word, lowercased — or `null` for
+     * a bare fence.
+     *
+     * Read from `data-language`, which is the only place it reaches the DOM, and the
+     * reason it is there at all: a highlighter picks a grammar by it, and the
+     * showcase's markdown export needs it to re-fence the block. `null` is a real
+     * answer, not a gap: a bare fence names no grammar, so nothing is ever asked to
+     * colour it.
+     */
+    getLanguage(): Promise<string | null>;
+    /**
+     * The block's code, EXACTLY — every space, every blank line, every newline.
+     *
+     * Nothing is collapsed here, unlike every prose read on the document harness,
+     * and it is read off the `<pre>` rather than off the host so the copy button is
+     * not part of the answer. Two failures live in this one string. Angular strips
+     * whitespace-only text nodes from templates, so the code has to arrive as an
+     * interpolation — a template that types it instead loses the indentation. And a
+     * HIGHLIGHTED block is not one text node but a span per token: what separates its
+     * lines is a real `\n` interpolated between them, so a spec that only ever
+     * asserts the unhighlighted case would not notice a highlighted block copying out
+     * as one run-together line.
+     */
+    getCode(): Promise<string>;
+    /**
+     * Whether the block is coloured right now.
+     *
+     * A block is plain text until a highlighter answers for it, and that is the
+     * intended order rather than a compromise: a grammar engine loads WASM, and
+     * blocking on it would leave the reader with an empty box instead of their code.
+     * So this is `false` with no `WR_MARKDOWN_HIGHLIGHTER` provided, `false` for a
+     * language the highlighter declined or threw on, `false` under SSR — a
+     * highlighter resolving after prerender cannot contribute to the HTML — and
+     * `false` for the first render of an async one.
+     */
+    isHighlighted(): Promise<boolean>;
+    /**
+     * Whether this block offers a copy button.
+     *
+     * Two conditions, and both are the component's policy rather than an accident:
+     * `copyable` has to be on (bound, or defaulted through
+     * `provideWrConfig({ markdown: { copyable: true } })`), and the fence has to be
+     * CLOSED. Mid-stream a block's code is not all there, and a button that copies
+     * half a snippet is worse than no button.
+     */
+    canCopy(): Promise<boolean>;
+    /**
+     * The copy button's accessible name, or `null` when there is no button.
+     *
+     * Worth reading rather than assuming, because it is the whole of the copy
+     * feedback: the button swaps its label — and its icon — for the "copied" one for
+     * two seconds after a successful write, and both strings come from the i18n
+     * catalog (`markdown.copy` / `markdown.copied`) or the matching inputs. Which is
+     * also why this harness reports the name instead of a `isCopied()` boolean: only
+     * the consuming app knows which of its own two strings means which.
+     */
+    getCopyLabel(): Promise<string | null>;
+    /**
+     * Copy the block, the way a pointer does.
+     *
+     * Throws when there is no button, naming both reasons — a silent no-op here
+     * surfaces as an empty clipboard assertion several lines later. Note what a
+     * successful click needs from the environment: the directive behind the button
+     * writes through `navigator.clipboard`, which jsdom does not implement at all, so
+     * a unit test has to stand one in before the write can succeed and the label can
+     * swap.
+     */
+    copy(): Promise<void>;
+}
+
+/**
+ * @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-markdown>`, with {@link WrMarkdownCodeBlockHarness} for one
+ * fenced code block.
+ *
+ * What a consumer of a markdown renderer actually asserts is that a piece of
+ * SOURCE became the right DOM, so everything here reads rendered elements: the
+ * heading levels, the `href` / `target` / `rel` triple on a link, the tick state of
+ * a task item, a table as a rectangle of text. The parse tree is not exposed on
+ * purpose — `parseMarkdown()` is a pure function with its own spec, and a harness
+ * that reported its nodes would pass straight through the half that breaks people,
+ * which is the template between the tree and the page.
+ *
+ * Three things worth knowing before writing expectations:
+ *
+ * - **Prose reads are whitespace-collapsed, code is not.** A soft line break inside
+ *   a paragraph is a real `\n` in the DOM (CommonMark says CSS collapses it), so
+ *   every text answer here is normalized to the line a reader sees.
+ *   {@link WrMarkdownCodeBlockHarness.getCode} is the exception and reads its
+ *   snippet exactly.
+ * - **The hidden task-state labels are left out of prose.** They are announced text,
+ *   not visible text; {@link getTaskItems} reports them as a field.
+ * - **Everything is flat and in document order.** Markdown nests — a quote holds
+ *   blocks, a list item holds blocks — and these readers do not re-derive that
+ *   hierarchy: {@link getCodeBlocks} finds a block inside a quote, and a nested
+ *   list item's text is part of its parent's, because that is what the DOM says.
+ *
+ * @example
+ * ```ts
+ * const md = await loader.getHarness(WrMarkdownHarness);
+ *
+ * expect(await md.getHeadings()).toEqual([{ level: 1, text: 'Release notes', id: 'release-notes' }]);
+ * expect(await md.getLinks()).toEqual([
+ *   { text: 'the docs', href: 'https://ngwr.dev', title: null, target: '_blank', rel: 'noopener noreferrer' },
+ * ]);
+ * ```
+ *
+ * @see https://ngwr.dev/reference/components/markdown
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrMarkdownHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrMarkdownHarnessFilters): HarnessPredicate<WrMarkdownHarness>;
+    /**
+     * The whole document as text — whitespace collapsed, the hidden task-state labels
+     * left out.
+     *
+     * The coarse read, and the useful one for the security cases: raw HTML in the
+     * source is ESCAPED rather than rendered, so `<img onerror=…>` shows up here as
+     * characters, and a refused `javascript:` URL leaves its label behind as text with
+     * no anchor around it. A code block's newlines are collapsed like everything else
+     * — {@link getCodeBlocks} is where a snippet stays exact.
+     *
+     * It is `textContent`, which means sibling BLOCKS are not separated: a document of
+     * `<h1>Title</h1><p>Body</p>` reads as `'TitleBody'`, because the renderer emits
+     * no whitespace between them and none is invented here. Assert a fragment with
+     * `toContain`, or read the blocks themselves — {@link getHeadings},
+     * {@link getParagraphs} — when the boundary matters.
+     */
+    getText(): Promise<string>;
+    /**
+     * Whether the component rendered nothing at all.
+     *
+     * True for an empty `value`, and for one that parses to nothing — a lone `<!--`
+     * or whitespace. Distinct from `getText() === ''`, which a document made only of
+     * a thematic break or an image would also answer.
+     */
+    isEmpty(): Promise<boolean>;
+    /**
+     * Whether the document is being streamed.
+     *
+     * Read from the `--streaming` host modifier rather than from the input, because
+     * the modifier is the whole public API of the feature on the styling side: it is
+     * what paints the caret after the last block. What it does NOT say is that
+     * partial-safe parsing is on — the same input drives both, but only this reaches
+     * the DOM.
+     */
+    isStreaming(): Promise<boolean>;
+    /** Every heading, in document order. */
+    getHeadings(): Promise<WrMarkdownHarnessHeading[]>;
+    /**
+     * The text of every paragraph, in document order.
+     *
+     * Including the ones inside a LOOSE list item — CommonMark drops the `<p>` in a
+     * tight list and keeps it in a loose one, which is what stops a one-line list from
+     * rendering double-spaced, so an empty answer for `- a\n- b` is the correct one
+     * rather than a missed paragraph.
+     */
+    getParagraphs(): Promise<string[]>;
+    /**
+     * Every link, in document order, with the attributes that make it safe.
+     *
+     * A URL the renderer refused is NOT here — it renders as plain text instead of as
+     * a live anchor that announces as a link and does nothing — so an empty answer
+     * where a link was expected is the sanitizer speaking, and {@link getText} still
+     * has the label.
+     */
+    getLinks(): Promise<WrMarkdownHarnessLink[]>;
+    /**
+     * Every image, in document order.
+     *
+     * A refused source renders no image at all and leaves the alt text as prose,
+     * which is the information the author actually wrote — so assert this together
+     * with {@link getText} when the point is the refusal.
+     */
+    getImages(): Promise<WrMarkdownHarnessImage[]>;
+    /**
+     * The text of every inline code span, in document order.
+     *
+     * A different element from a fenced block (`<code>` on its own, not inside a
+     * `<pre>`), and never one of {@link getCodeBlocks}. Read exactly rather than
+     * collapsed, for the same reason a block is: this is code, and the spacing in it
+     * is content.
+     */
+    getInlineCode(): Promise<string[]>;
+    /**
+     * The fenced code blocks, in document order — nested ones included.
+     *
+     * A block inside a quote or a list item is a block: it renders the same way and it
+     * gets the same copy affordance, so leaving it out would report a document as
+     * having no code because its snippet is indented under a bullet.
+     */
+    getCodeBlocks(filters?: WrMarkdownCodeBlockHarnessFilters): Promise<WrMarkdownCodeBlockHarness[]>;
+    /**
+     * The first code block matching the filters.
+     *
+     * Throws when nothing matches, naming the languages the document does offer —
+     * a `getCodeBlocks(…)[0]` that quietly resolves to `undefined` fails several lines
+     * later, on an unrelated line, with `Cannot read properties of undefined`.
+     */
+    getCodeBlock(filters?: WrMarkdownCodeBlockHarnessFilters): Promise<WrMarkdownCodeBlockHarness>;
+    /**
+     * The text of every list item, in document order.
+     *
+     * Bullets, numbers and task items alike — a task item's tick state is in
+     * {@link getTaskItems} instead. NESTING is not re-derived: a nested list lives
+     * INSIDE its parent `<li>` (which is what makes the list's accessibility tree
+     * valid), so a parent's text contains its children's, and each child is also an
+     * entry of its own.
+     */
+    getListItems(): Promise<string[]>;
+    /**
+     * Every task-list item (`- [x]` / `- [ ]`), in document order.
+     *
+     * Ordinary items are not here, so the count is the number of checkboxes in the
+     * document. Both halves of each entry are worth asserting: the `checked` flag is
+     * what a reader sees, and `stateLabel` is the only thing a screen reader gets —
+     * the tick itself is `aria-hidden`.
+     */
+    getTaskItems(): Promise<WrMarkdownHarnessTaskItem[]>;
+    /** Every table, in document order, each as a rectangle of text plus its alignment. */
+    getTables(): Promise<WrMarkdownHarnessTable[]>;
+    /**
+     * The text of every blockquote, in document order.
+     *
+     * A quote holds BLOCKS, so this is everything inside it collapsed to one line —
+     * its paragraphs are also in {@link getParagraphs} and a snippet inside it is
+     * also one of {@link getCodeBlocks}.
+     */
+    getQuotes(): Promise<string[]>;
+    /**
+     * How many thematic breaks the document rendered.
+     *
+     * A count rather than a list because an `<hr>` has no content — and it is worth
+     * counting: `---` is the one construct this renderer resolves differently from
+     * some others (it is always a break here, never a setext heading underline), so a
+     * document that lost a rule gained a heading somewhere.
+     */
+    getRuleCount(): Promise<number>;
+}
+
+export { WrMarkdownCodeBlockHarness, WrMarkdownHarness };
+export type { WrMarkdownCodeBlockHarnessFilters, WrMarkdownHarnessAlign, WrMarkdownHarnessFilters, WrMarkdownHarnessHeading, WrMarkdownHarnessImage, WrMarkdownHarnessLink, WrMarkdownHarnessTable, WrMarkdownHarnessTaskItem };