ngwr 14.8.0 → 14.9.0

package/types/ngwr-editor.d.ts

@@ -0,0 +1,449 @@
+import * as ngwr_form from 'ngwr/form';
+import { WrFormFieldContext } from 'ngwr/form';
+import * as _angular_core from '@angular/core';
+import { Signal } from '@angular/core';
+import { FormValueControl } from '@angular/forms/signals';
+
+/**
+ * @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 `<wr-editor>` reads from and writes into its `value` model.
+ *
+ * - `html` — an HTML string, parsed without executing anything and rebuilt from
+ *   the editor's own schema on the way out, so only what the schema allows comes
+ *   back. `''` for an empty document.
+ * - `markdown` — the dialect `ngwr/markdown` reads and `<wr-markdown>` renders,
+ *   written back by `serializeMarkdown`. Markdown has no underline, so the
+ *   underline tool and its shortcut are absent in this format. `''` for an empty
+ *   document.
+ * - `json` — the document as a {@link WrEditorJson} tree. `null` for an empty
+ *   document.
+ */
+type WrEditorFormat = 'html' | 'markdown' | 'json';
+
+/**
+ * @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
+ */
+/**
+ * One mark on a {@link WrEditorJson} node — `strong`, `em`, `underline`,
+ * `strike`, `code`, or `link` with `{ href, title }`.
+ */
+interface WrEditorMarkJson {
+    readonly type: string;
+    readonly attrs?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The editor's document as plain data — the shape ProseMirror's `toJSON()`
+ * writes, declared here so no ProseMirror type reaches the public API.
+ *
+ * Nodes: `doc`, `paragraph`, `heading` (`level` 1–3), `blockquote`,
+ * `code_block` (`language`), `horizontal_rule`, `bullet_list` (`tight`),
+ * `ordered_list` (`order`, `tight`), `list_item` (`checked`: `true`, `false`
+ * or `null` for an ordinary item), `hard_break`, `image` (`src`, `alt`,
+ * `title`), `table`, `table_row`, `table_header` / `table_cell` (`align`) and
+ * `text`.
+ *
+ * A value bound in `json` format is VALIDATED, not trusted: an unknown node or
+ * mark, an attribute outside its allowed set, a content rule broken, or a link
+ * or image whose URL `safeMarkdownUrl` refuses, and the whole value is refused —
+ * the editor keeps what it had and warns in dev mode.
+ */
+interface WrEditorJson {
+    readonly type: string;
+    readonly attrs?: Readonly<Record<string, unknown>>;
+    readonly content?: readonly WrEditorJson[];
+    readonly marks?: readonly WrEditorMarkJson[];
+    readonly text?: string;
+}
+
+/**
+ * @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
+ */
+/**
+ * One entry of `<wr-editor>`'s `toolbar` input.
+ *
+ * - Marks: `bold`, `italic`, `underline` (absent in `markdown` format, which
+ *   cannot express it), `strike`, `code`.
+ * - Blocks: `paragraph`, `heading1`, `heading2`, `heading3`, `bulletList`,
+ *   `orderedList`, `blockquote`, `codeBlock`.
+ * - Inserts: `link` (opens the link panel), `horizontalRule`.
+ * - History: `undo`, `redo`.
+ * - `'|'` draws a separator between two groups.
+ */
+type WrEditorTool = 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'bulletList' | 'orderedList' | 'blockquote' | 'codeBlock' | 'link' | 'horizontalRule' | 'undo' | 'redo' | '|';
+
+/**
+ * @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
+ */
+
+/**
+ * The `value` model of `<wr-editor>`: a string in `html` and `markdown` format,
+ * a {@link WrEditorJson} tree in `json` format.
+ *
+ * An empty document is written as `''` in the two string formats and as `null`
+ * in `json`, so a Signal Forms `required()` rule reports an empty editor as
+ * empty — `'<p></p>'` would be a non-empty string. `null` and `''` are both
+ * read as an empty document in every format.
+ */
+type WrEditorValue = string | WrEditorJson | null;
+
+/**
+ * @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
+ */
+
+/** Every tool but the separator. */
+type WrEditorCommandTool = Exclude<WrEditorTool, '|'>;
+
+/**
+ * The field the link panel's URL input belongs to — provided as `WR_FORM_FIELD`
+ * for the editor's whole subtree.
+ *
+ * It does two jobs at once. It is the SHIELD every composite control needs: the
+ * editor is the control a `<wr-form-field>` wraps, and without a nearer provider
+ * the `[wrInput]` in its link panel would adopt the outer field's id, take over
+ * its label and announce its error as its own. And it is the input's own field:
+ * `[wrInput]` binds `id`, `aria-invalid` and `aria-describedby` from whatever
+ * field it finds, so answering here is how a refused URL reaches a screen reader
+ * without binding attributes the directive already owns.
+ *
+ * @internal
+ */
+declare class WrEditorLinkField implements WrFormFieldContext {
+    private readonly id;
+    /** The URL just submitted was refused by the link policy. */
+    readonly invalid: _angular_core.WritableSignal<boolean>;
+    readonly controlId: _angular_core.Signal<string>;
+    readonly errorId: string;
+    readonly panelId: string;
+    readonly errorKeys: _angular_core.Signal<readonly string[]>;
+    readonly describedBy: _angular_core.Signal<string | null>;
+    readonly labelId: _angular_core.Signal<string | null>;
+    adoptControlId(): void;
+}
+
+/** One toolbar button's state at the current selection. */
+interface WrToolState {
+    readonly tool: WrEditorCommandTool;
+    readonly active: boolean;
+    readonly available: boolean;
+}
+/**
+ * Rich-text editor on ProseMirror, with a toolbar, a link panel, keyboard
+ * shortcuts and markdown-style block shortcuts (`# `, `> `, `- `, `1. `,
+ * ` ``` `).
+ *
+ * A signal-forms native control: it implements `FormValueControl<WrEditorValue>`,
+ * so `[formField]` binds straight to its `value` model — no
+ * `ControlValueAccessor` in between. `[(value)]` works standalone.
+ *
+ * The value is an HTML string, a markdown string or the document as JSON, chosen
+ * by `format`. Whatever arrives is treated as untrusted and rebuilt from the
+ * editor's schema, so only what the schema allows survives, and links and images
+ * go through `safeMarkdownUrl` in all three. A value the editor cannot read is
+ * refused — the document it already shows is kept, a warning names the reason in
+ * dev mode, and nothing is written back. Until a value it CAN read arrives the
+ * editor is read-only and carries `wr-editor--refused`: the model still holds the
+ * refused value, and an edit would write the document on screen over it.
+ *
+ * Headings stop at three levels: an h4–h6 read from HTML or markdown becomes an
+ * h3 rather than a paragraph. Underline exists in `html` and `json` only —
+ * markdown cannot spell it, so in that format the tool, the shortcut and the mark
+ * itself are absent.
+ *
+ * ProseMirror is an OPTIONAL peer dependency: only an app that imports
+ * `ngwr/editor` installs `prosemirror-model`, `-state`, `-view`, `-commands`,
+ * `-keymap`, `-history`, `-schema-list` and `-inputrules`.
+ *
+ * @example
+ * ```html
+ * <!-- signal forms -->
+ * <wr-editor format="markdown" placeholder="Describe the change" [formField]="form.body" />
+ *
+ * <!-- standalone two-way binding -->
+ * <wr-editor [(value)]="html" />
+ * ```
+ *
+ * @see https://ngwr.dev/reference/components/editor
+ */
+declare class WrEditor implements FormValueControl<WrEditorValue> {
+    /**
+     * The document. A string in `html` and `markdown` format, a
+     * {@link WrEditorJson} tree in `json`; `''` / `null` when nothing is written.
+     * Bound by `[formField]`, or two-way via `[(value)]`.
+     */
+    readonly value: _angular_core.ModelSignal<WrEditorValue>;
+    /** Emitted on blur so a bound field can mark itself touched. */
+    readonly touch: _angular_core.OutputEmitterRef<void>;
+    /**
+     * Disable the editor and its toolbar. Bound automatically from the field's
+     * disabled state when used with `[formField]`.
+     *
+     * @default false
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Refuse edits while the text stays focusable, selectable and announced.
+     * Bound automatically from the field's readonly state when used with
+     * `[formField]`.
+     *
+     * The surface keeps its tab stop and reports `aria-readonly`; typing, paste,
+     * drop, the shortcuts and every toolbar command are refused. The toolbar goes
+     * inert, since none of its tools can apply.
+     *
+     * @default false
+     */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, any>;
+    /**
+     * Hint shown while the document is empty, and exposed as `aria-placeholder`.
+     *
+     * @default ''
+     */
+    readonly placeholder: _angular_core.InputSignal<string>;
+    /**
+     * Accessible name of the text surface. Falls back to the surrounding
+     * `<wr-form-field>`'s label, then to `editor.label`.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * What `value` holds — see {@link WrEditorFormat}. Unset, it falls back to
+     * `provideWrConfig({ editor: { format } })`. Changing it re-reads `value` in
+     * the new format.
+     *
+     * @default 'html'
+     */
+    readonly format: _angular_core.InputSignal<WrEditorFormat | null>;
+    protected readonly resolvedFormat: Signal<"html" | "markdown" | "json">;
+    /**
+     * The toolbar's tools, in order, with `'|'` between groups; `false` hides it.
+     * `underline` is left out in `markdown` format, which cannot store it.
+     *
+     * @default WR_EDITOR_TOOLBAR
+     */
+    readonly toolbar: _angular_core.InputSignal<false | readonly WrEditorTool[]>;
+    private readonly document;
+    private readonly injector;
+    private readonly destroyRef;
+    private readonly host;
+    private readonly platform;
+    private readonly isBrowser;
+    /**
+     * Ambient reading direction, read by the toolbar's arrow keys. Optional so a
+     * bare `TestBed` needs no provider; `null` means LTR.
+     */
+    private readonly dir;
+    /** @internal */
+    protected readonly linkField: WrEditorLinkField;
+    /** The surrounding `<wr-form-field>`'s error state, read past the editor's own shield. @internal */
+    protected readonly fieldAria: ngwr_form.WrFormFieldAria;
+    protected readonly resolvedAriaLabel: Signal<string>;
+    /**
+     * The field's label names the surface, when there is one — a
+     * `contenteditable` is not labelable, so the field's `<label for>` cannot
+     * reach it. An explicit `ariaLabel` still wins over both.
+     */
+    protected readonly labelledBy: Signal<string | null>;
+    /** `null` while the field's label carries the name. */
+    protected readonly accessibleName: Signal<string | null>;
+    protected readonly surfaceId: string;
+    /** ProseMirror owns the surface from here on; until then the preview stands in. */
+    protected readonly mounted: _angular_core.WritableSignal<boolean>;
+    protected readonly focused: _angular_core.WritableSignal<boolean>;
+    private readonly editorState;
+    /**
+     * Whether `value` holds something the editor could not read, so the document
+     * on screen is not the one the model holds — empty at mount, or the previous
+     * record after a write. Edits are refused until a readable value arrives:
+     * the first keystroke would otherwise replace the stored value with whatever
+     * is on screen, and the only sign of it was a dev-mode warning.
+     */
+    private readonly refused;
+    /** Read-only by the input, or because the value was refused. @internal */
+    protected readonly locked: Signal<boolean>;
+    /** Apple keyboards name the modifier ⌘. Read in the browser only — see `mount()`. */
+    private readonly apple;
+    private readonly surface;
+    private readonly toolButtons;
+    private readonly linkPopover;
+    private view;
+    /** The format the live document was read in, which is the format it is written in. */
+    private viewFormat;
+    /**
+     * The value the live document was last read from or written as. A write from
+     * outside that equals it is the document already on screen — an echo of the
+     * editor's own emit, or a consumer writing back what it was handed — and must
+     * neither re-parse nor reset the selection.
+     */
+    private lastSerialized;
+    private linkToSurface;
+    protected readonly toolbarLabel: Signal<string>;
+    protected readonly linkUrlLabel: Signal<string>;
+    protected readonly linkApplyLabel: Signal<string>;
+    protected readonly linkRemoveLabel: Signal<string>;
+    protected readonly linkInvalidLabel: Signal<string>;
+    protected readonly taskDoneLabel: Signal<string>;
+    protected readonly taskTodoLabel: Signal<string>;
+    private readonly keyCtrl;
+    private readonly keyShift;
+    private readonly keyAlt;
+    private readonly headingLabel;
+    private readonly shortcutLabel;
+    private readonly toolLabels;
+    /**
+     * The bound tools as drawn: underline dropped where the format cannot store
+     * it, and separators only BETWEEN two groups — a leading, trailing or doubled
+     * one would be left behind by that filter or by a hand-built list.
+     */
+    protected readonly tools: Signal<readonly WrEditorTool[]>;
+    /** The tools that are buttons, in order — what the roving tab stop moves over. */
+    private readonly buttons;
+    /** Each drawn entry's index among the buttons, `-1` for a separator. @internal */
+    protected readonly buttonIndex: Signal<number[]>;
+    private readonly commands;
+    /** Every button's pressed and available state at the current selection. @internal */
+    protected readonly toolStates: Signal<ReadonlyMap<WrEditorCommandTool, WrToolState>>;
+    private readonly rovingIndex;
+    /**
+     * The one button in the tab order. It follows the user, and moves off a tool
+     * that stopped applying so the toolbar never loses its tab stop — unless NO
+     * tool applies (read-only, disabled), where it stays put, because there is
+     * nothing to reach.
+     */
+    private readonly tabStop;
+    /** Whether the live document is empty — pre-mount, whether the value is. */
+    private readonly empty;
+    /** The task-item words, handed to ProseMirror through its node views. */
+    private readonly nodeViews;
+    protected readonly ariaPlaceholder: Signal<string | null>;
+    protected readonly linkDraft: _angular_core.WritableSignal<string>;
+    /** Whether the selection is in a link — what the panel's remove button needs. */
+    protected readonly linkActive: Signal<boolean>;
+    /**
+     * The value rendered by Angular until ProseMirror takes over: on the server,
+     * and for the first browser frame. Read from the doc JSON, so it shows exactly
+     * what the schema kept — the same sanitised document the editor will mount.
+     */
+    protected readonly preview: Signal<WrEditorJson | null>;
+    protected readonly classes: Signal<string>;
+    constructor();
+    /** Focus the text surface — what Signal Forms calls to focus this control. */
+    focus(options?: FocusOptions): void;
+    protected label(tool: WrEditorCommandTool): string;
+    protected icon(tool: WrEditorCommandTool): readonly string[];
+    protected isToggle(tool: WrEditorCommandTool): boolean;
+    /** The tooltip: the label, with the shortcut when the tool has one. */
+    protected tooltip(tool: WrEditorCommandTool): string;
+    /** `aria-keyshortcuts` — key names from the ARIA spec, never localised. */
+    protected keyShortcuts(tool: WrEditorCommandTool): string | null;
+    protected state(tool: WrEditorCommandTool): WrToolState | undefined;
+    /**
+     * A toolbar button was activated.
+     *
+     * By pointer, focus never left the text (`mousedown` is cancelled), so the
+     * caret is put back where the command left it. By keyboard, focus stays on the
+     * button, as the toolbar pattern asks — unless the tool no longer applies,
+     * which disables it: a disabled button drops its focus on `<body>`, so the text
+     * takes it first.
+     */
+    protected onToolClick(tool: WrEditorCommandTool, event: MouseEvent): void;
+    protected onToolFocus(index: number): void;
+    /** The APG toolbar keys: the arrows rove and wrap, Home and End jump. */
+    protected onToolbarKeydown(event: KeyboardEvent): void;
+    /** `touch` once focus leaves the whole control — not when it moves between its own parts. */
+    protected onFocusOut(event: FocusEvent): void;
+    protected onLinkOpened(): void;
+    protected onLinkClosed(): void;
+    protected onLinkInput(event: Event): void;
+    protected applyLink(event: Event): void;
+    protected removeLink(): void;
+    protected nodesOf(raw: unknown): readonly WrEditorJson[];
+    protected nodeOf(raw: unknown): WrEditorJson;
+    protected markAt(node: WrEditorJson, depth: number): WrEditorMarkJson | null;
+    protected attr(node: WrEditorJson | WrEditorMarkJson, name: string): unknown;
+    protected text(node: WrEditorJson | WrEditorMarkJson, name: string): string | null;
+    protected textOf(node: WrEditorJson): string;
+    /** Whether an edit may happen at all — not while read-only, disabled or refused. */
+    private canEdit;
+    private mount;
+    private createState;
+    private dispatch;
+    private emit;
+    /**
+     * Bring an outside write into the view.
+     *
+     * Compared as DOCUMENTS, never as strings: `<b>` comes back as `<strong>`, so a
+     * normalised string differs from what the consumer wrote while the documents
+     * are equal — and an equal document is left alone, selection and history
+     * included. A different one replaces the state wholesale, history with it,
+     * which is right for a form reset or a server load: undo back into content the
+     * app replaced would be wrong. The normalised form is never written back —
+     * that would mark the field dirty on load. A write that arrives mid-composition
+     * (IME) replaces the composition too: the model is the source of truth.
+     */
+    private sync;
+    /**
+     * A new format whose value could not be read: keep the document, moved into
+     * the new format's schema — markdown's lacks underline, so that mark is
+     * dropped on the way. What is written from here on is in the new format.
+     */
+    private switchFormat;
+    private replaceState;
+    private placeholderDecorations;
+    /**
+     * Mod-K opens the link panel. Its propagation stops here: `<wr-command-palette>`
+     * binds the same chord on the document, and `WrHotkey` deliberately does not
+     * skip an event another listener already handled.
+     */
+    private onSurfaceKeydown;
+    private focusLinkInput;
+    /**
+     * Focus left the link panel for somewhere outside the control — Tab, Shift+Tab,
+     * a click elsewhere. The panel is not a focus trap, and left open it stays
+     * anchored to a control the user has left, whose next close would then pull
+     * focus back into the text. Closed with focus left where it went.
+     */
+    private leaveLinkPanel;
+    /** Whether a node is part of this control: the host, or its link panel. */
+    private withinControl;
+    private inLinkPanel;
+    private warnRefused;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrEditor, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WrEditor, "wr-editor", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "toolbar": { "alias": "toolbar"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "touch": "touch"; }, never, never, true, never>;
+}
+
+/**
+ * @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
+ */
+
+/**
+ * The toolbar `<wr-editor>` draws when `toolbar` is not bound — every tool, in
+ * five groups. Exported so a toolbar can be built from it rather than retyped:
+ *
+ * ```ts
+ * readonly tools = WR_EDITOR_TOOLBAR.filter(tool => tool !== 'code');
+ * ```
+ *
+ * `underline` is dropped in `markdown` format whether it is listed or not.
+ */
+declare const WR_EDITOR_TOOLBAR: readonly WrEditorTool[];
+
+export { WR_EDITOR_TOOLBAR, WrEditor };
+export type { WrEditorFormat, WrEditorJson, WrEditorMarkJson, WrEditorTool, WrEditorValue };

package/types/ngwr-markdown.d.ts

@@ -475,7 +475,11 @@ declare function parseMarkdown(source: string, options?: WrMarkdownParseOptions)
  *
  * Whitespace and control characters are stripped before the scheme is read,
  * because `java\nscript:` and `java script:` are the same URL to a browser and
- * different strings to a naive check.
+ * different strings to a naive check. So are character references:
+ * `javascript:` has no scheme to this check, but a CommonMark renderer
+ * decodes it in a destination, so any markdown the URL is written into — an
+ * editor's output, say — hands a browser `javascript:`. The scheme is read from
+ * the decoded form; what comes back is still the URL as written.
  */
 declare function safeMarkdownUrl(raw: string, kind: 'link' | 'image'): string | null;
 /** Inline markdown to nodes. */
@@ -483,6 +487,61 @@ declare function parseInlines(source: string, options?: WrMarkdownParseOptions):
 /** Text content of an inline tree — for `alt` and for heading slugs. */
 declare function plainText(inlines: readonly WrMarkdownInline[]): string;
 
+/**
+ * @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
+ */
+
+/**
+ * A block tree back to markdown — the inverse of {@link parseMarkdown}.
+ *
+ * **Written against this library's parser, not against CommonMark.** The two
+ * disagree in places (no setext headings, no indented code, no entities, a
+ * simplified reading of emphasis), and a serializer that escapes for the wrong
+ * dialect writes text that comes back as something else. So every escape here is
+ * derived from a question `parseMarkdown` actually asks — several of them by
+ * calling the parser's own predicates — and the spec holds the pair to one
+ * property: `parseMarkdown(serializeMarkdown(tree))` returns `tree`.
+ *
+ * **What markdown cannot say is normalised, never guessed at.** The output is the
+ * nearest document this dialect can express, and reading it back gives a tree
+ * that serializes to the same string. The losses, all of them structural:
+ *
+ * - Whitespace at the edges of a paragraph, heading or cell is dropped, and so is
+ *   whitespace just inside `**` / `*` / `~~` — a delimiter next to a space is not
+ *   a delimiter. A soft line break inside a text node becomes a space, and a hard
+ *   break at the very end of a block (a trailing `\` stays literal) is dropped;
+ *   inside a heading or a table cell every hard break becomes a space.
+ * - An empty paragraph, an empty list and a table with no header cell vanish.
+ * - Two adjacent lists of the same kind merge on the way back — there is no
+ *   raw-HTML comment to put between them. A single-item list with one block
+ *   cannot be loose, and a loose list nested in a tight one loosens it. Nesting
+ *   deeper than the parser's twelve levels reads back as text.
+ * - Inline marks are rewritten in one canonical nesting — link outside strong
+ *   outside strikethrough outside emphasis — which is also how a mark SET, the
+ *   shape an editor holds, becomes a tree. An image carries no emphasis (none of
+ *   it paints on an image); where an emphasis run touches a strong one and
+ *   neither can switch to `_`, the emphasis is dropped rather than written as
+ *   markup that reads back as literal asterisks.
+ * - A link or image whose URL `safeMarkdownUrl` refuses is written as its text,
+ *   exactly as the renderer would show it. A destination is percent-encoded
+ *   where this parser cannot carry a character (`<`, `>`, an unbalanced
+ *   parenthesis, a `\` it would read as an escape — and `[`, `]`, a backtick for
+ *   an image inside a link label), loses a tab or line break the way a browser's
+ *   URL parser does, a title that cannot be delimited is dropped, and a link
+ *   whose label is too long for the parser's label cap is written as plain text.
+ * - A fence's info string keeps its first word, lowercased, and `closed` is not
+ *   written: a serialized fence is always closed. A tab that indents a line reads
+ *   back as four spaces, as the parser expands it. Heading ids are the parser's,
+ *   recomputed on the way back.
+ *
+ * @param blocks a block tree, typically from {@link parseMarkdown} or an editor
+ * @returns markdown, with no trailing newline; `''` for an empty tree
+ */
+declare function serializeMarkdown(blocks: readonly WrMarkdownBlock[]): string;
+
 /**
  * @license
  *
@@ -541,5 +600,5 @@ declare function provideWrMarkdownHighlighter(highlighter: WrMarkdownHighlighter
  */
 declare const WR_MARKDOWN_HIGHLIGHTER: InjectionToken<WrMarkdownHighlighter | null>;
 
-export { WR_MARKDOWN_HIGHLIGHTER, WrMarkdown, WrMarkdownHighlight, parseInlines, parseMarkdown, plainText, provideWrMarkdownHighlighter, safeMarkdownUrl };
+export { WR_MARKDOWN_HIGHLIGHTER, WrMarkdown, WrMarkdownHighlight, parseInlines, parseMarkdown, plainText, provideWrMarkdownHighlighter, safeMarkdownUrl, serializeMarkdown };
 export type { WrHighlightLine, WrHighlightSpan, WrMarkdownAlign, WrMarkdownBlock, WrMarkdownCell, WrMarkdownHighlighter, WrMarkdownInline, WrMarkdownListItem, WrMarkdownParseOptions };

package/types/ngwr-typography.d.ts

@@ -39,6 +39,10 @@ declare class WrTypography {
     /**
      * Color tone. `null` (default) keeps the variant's own color — the base
      * dark for headings/body, medium for lead/caption, primary for links.
+     * Emphasis only: a tone never carries a state on its own. Six of the nine
+     * intents share one lightness, and `success` against `danger` is 1.05:1 as
+     * text, so the words have to name the state (`500 Server Error`, not a red
+     * `Request`) — or reach for `<wr-alert>`, which draws a glyph per type.
      */
     readonly tone: _angular_core.InputSignal<WrTypographyTone | null>;
     /** Horizontal alignment. */

package/types/ngwr-version.d.ts

@@ -16,7 +16,7 @@ import { InjectionToken } from '@angular/core';
  * Distinct from `Version` exported by `@angular/core`, which reports the
  * loaded Angular runtime version (e.g. `'22.0.0'`), not ngwr's.
  */
-declare const NGWR_VERSION = "14.8.0";
+declare const NGWR_VERSION = "14.9.0";
 
 /**
  * @license

package/typography/styles/_index.scss

@@ -186,21 +186,37 @@
   }
 
   // Tones
+  // color-ok: a text ROLE, not a state — body copy. Like every tone it is
+  // emphasis only, and the words carry whatever state there is.
   &--tone-dark {
     color: var(--wr-color-on-surface);
   }
+  // color-ok: a text ROLE, not a state — muted prose rather than body copy.
+  // Like every tone it is emphasis only.
   &--tone-medium {
     color: var(--wr-color-on-surface-muted);
   }
+  // color-ok: emphasis only, never the sole carrier of a state — the words
+  // carry it, as "500 Server Error" does, because `success` against `danger` is
+  // 1.05:1 as text in light.
   &--tone-primary {
     color: var(--wr-color-primary-ink);
   }
+  // color-ok: emphasis only, never the sole carrier of a state — the words
+  // carry it, as "500 Server Error" does, because `success` against `danger` is
+  // 1.05:1 as text in light.
   &--tone-success {
     color: var(--wr-color-success-ink);
   }
+  // color-ok: emphasis only, never the sole carrier of a state — the words
+  // carry it, as "500 Server Error" does, because `success` against `danger` is
+  // 1.05:1 as text in light.
   &--tone-warning {
     color: var(--wr-color-warning-ink);
   }
+  // color-ok: emphasis only, never the sole carrier of a state — the words
+  // carry it, as "500 Server Error" does, because `success` against `danger` is
+  // 1.05:1 as text in light.
   &--tone-danger {
     color: var(--wr-color-danger-ink);
   }