@orvain/utils 0.0.0-stage → 0.1.1

package/dist/kanbanDnd.d.cts

@@ -0,0 +1,71 @@
+/**
+ * Framework-free drag and drop for KanbanBoard (React + Vue).
+ *
+ * Pointer events only (mouse, pen and touch; no HTML5 DnD, no library), plus
+ * the keyboard alternative of the "accessible drag and drop" pattern:
+ * Space picks a card up, arrow keys move it (up/down within a column,
+ * left/right between columns), Space (or Enter) drops it and Escape cancels.
+ * Every step is announced through the board's live region.
+ *
+ * The board stays controlled: nothing in the DOM is moved here. On a drop the
+ * controller calls `onMove({ cardId, fromColumn, toColumn, index })`, the app
+ * updates its data and re-renders, and the controller puts focus back on the
+ * moved card (keyboard drops).
+ *
+ * DOM contract (set by the components):
+ *   [data-kanban-column="<id>"][data-kanban-column-label="<title>"]  column
+ *   [data-kanban-card="<id>"][data-kanban-card-label="<title>"]      card
+ *   [data-kanban-handle]                                              the card's focus target
+ * State the controller writes (styled by the CSS module):
+ *   board  [data-kanban-dragging="pointer|keyboard"]
+ *   card   [data-kanban-lifted="pointer|keyboard"] (pointer: the card stays as a
+ *          dimmed placeholder; a clone with [data-kanban-lifted="preview"]
+ *          follows the pointer in a position:fixed layer on <body>, so the
+ *          board's scroll box never clips it)
+ *   handle tabindex: roving, one Tab stop per column (Up/Down between cards,
+ *          Left/Right to the same position in the next column)
+ *   column [data-kanban-drop-target]
+ *   li     [data-kanban-drop="before|after"]
+ */
+export interface KanbanCardMove {
+    cardId: string;
+    fromColumn: string;
+    toColumn: string;
+    /** Index in `toColumn` after the move (the card removed from its old place first). */
+    index: number;
+    /** Index the card had in `fromColumn`. */
+    fromIndex: number;
+}
+export interface KanbanDndPosition {
+    /** Card title. */
+    card: string;
+    /** Column title the card is over. */
+    column: string;
+    /** 1-based position in that column. */
+    position: number;
+    /** Positions in that column. */
+    total: number;
+    /** Column title the card was picked up from. */
+    fromColumn: string;
+    fromPosition: number;
+    fromTotal: number;
+}
+export interface KanbanDndAnnouncements {
+    pickedUp: (p: KanbanDndPosition) => string;
+    moved: (p: KanbanDndPosition) => string;
+    dropped: (p: KanbanDndPosition) => string;
+    cancelled: (p: KanbanDndPosition) => string;
+}
+export declare const defaultKanbanAnnouncements: KanbanDndAnnouncements;
+export declare const defaultKanbanInstructions: string;
+export interface KanbanDndOptions {
+    onMove: (move: KanbanCardMove) => void;
+    /** Writes into the board's aria-live region. */
+    announce: (text: string) => void;
+    announcements?: Partial<KanbanDndAnnouncements> | undefined;
+}
+export interface KanbanDndController {
+    update: (options: KanbanDndOptions) => void;
+    destroy: () => void;
+}
+export declare function createKanbanDnd(board: HTMLElement, initial: KanbanDndOptions): KanbanDndController;

package/dist/kanbanDnd.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Framework-free drag and drop for KanbanBoard (React + Vue).
+ *
+ * Pointer events only (mouse, pen and touch; no HTML5 DnD, no library), plus
+ * the keyboard alternative of the "accessible drag and drop" pattern:
+ * Space picks a card up, arrow keys move it (up/down within a column,
+ * left/right between columns), Space (or Enter) drops it and Escape cancels.
+ * Every step is announced through the board's live region.
+ *
+ * The board stays controlled: nothing in the DOM is moved here. On a drop the
+ * controller calls `onMove({ cardId, fromColumn, toColumn, index })`, the app
+ * updates its data and re-renders, and the controller puts focus back on the
+ * moved card (keyboard drops).
+ *
+ * DOM contract (set by the components):
+ *   [data-kanban-column="<id>"][data-kanban-column-label="<title>"]  column
+ *   [data-kanban-card="<id>"][data-kanban-card-label="<title>"]      card
+ *   [data-kanban-handle]                                              the card's focus target
+ * State the controller writes (styled by the CSS module):
+ *   board  [data-kanban-dragging="pointer|keyboard"]
+ *   card   [data-kanban-lifted="pointer|keyboard"] (pointer: the card stays as a
+ *          dimmed placeholder; a clone with [data-kanban-lifted="preview"]
+ *          follows the pointer in a position:fixed layer on <body>, so the
+ *          board's scroll box never clips it)
+ *   handle tabindex: roving, one Tab stop per column (Up/Down between cards,
+ *          Left/Right to the same position in the next column)
+ *   column [data-kanban-drop-target]
+ *   li     [data-kanban-drop="before|after"]
+ */
+export interface KanbanCardMove {
+    cardId: string;
+    fromColumn: string;
+    toColumn: string;
+    /** Index in `toColumn` after the move (the card removed from its old place first). */
+    index: number;
+    /** Index the card had in `fromColumn`. */
+    fromIndex: number;
+}
+export interface KanbanDndPosition {
+    /** Card title. */
+    card: string;
+    /** Column title the card is over. */
+    column: string;
+    /** 1-based position in that column. */
+    position: number;
+    /** Positions in that column. */
+    total: number;
+    /** Column title the card was picked up from. */
+    fromColumn: string;
+    fromPosition: number;
+    fromTotal: number;
+}
+export interface KanbanDndAnnouncements {
+    pickedUp: (p: KanbanDndPosition) => string;
+    moved: (p: KanbanDndPosition) => string;
+    dropped: (p: KanbanDndPosition) => string;
+    cancelled: (p: KanbanDndPosition) => string;
+}
+export declare const defaultKanbanAnnouncements: KanbanDndAnnouncements;
+export declare const defaultKanbanInstructions: string;
+export interface KanbanDndOptions {
+    onMove: (move: KanbanCardMove) => void;
+    /** Writes into the board's aria-live region. */
+    announce: (text: string) => void;
+    announcements?: Partial<KanbanDndAnnouncements> | undefined;
+}
+export interface KanbanDndController {
+    update: (options: KanbanDndOptions) => void;
+    destroy: () => void;
+}
+export declare function createKanbanDnd(board: HTMLElement, initial: KanbanDndOptions): KanbanDndController;
+//# sourceMappingURL=kanbanDnd.d.ts.map

package/dist/listNavigation.d.cts

@@ -0,0 +1,36 @@
+/**
+ * Index arithmetic behind the WAI-ARIA APG listbox / menu / toolbar keyboard
+ * model, shared by React `useListNavigation` and its Vue twin. Items are
+ * addressed by index; disabled items are skipped.
+ */
+export type ListOrientation = 'vertical' | 'horizontal' | 'both';
+export type ListMove = 'next' | 'prev' | 'first' | 'last';
+/** First enabled index from `from` in `step` direction (inclusive), or -1. */
+export declare function findEnabledIndex(count: number, isDisabled: (index: number) => boolean, from: number, step: 1 | -1, loop: boolean): number;
+/**
+ * Index `move` lands on from `current` (-1 = nothing active). With nothing
+ * active, next starts at the first item and prev at the last. Without `loop`
+ * the ends hold.
+ */
+export declare function moveIndex(move: ListMove, current: number, count: number, isDisabled: (index: number) => boolean, loop: boolean): number;
+/** The move a key requests for an orientation, or null when the key isn't navigation. */
+export declare function keyToMove(key: string, orientation: ListOrientation, rtl?: boolean, homeEnd?: boolean): ListMove | null;
+/** Typed characters are joined while keys arrive less than this far apart (APG). */
+export declare const TYPEAHEAD_TIMEOUT_MS = 500;
+export interface Typeahead {
+    /**
+     * Feeds one key. Returns the index to activate, -1 when nothing matches,
+     * or null when the key isn't part of typeahead (not printable, or a space
+     * that doesn't continue a search).
+     */
+    handle(key: string, current: number, count: number, getLabel: (index: number) => string, isDisabled: (index: number) => boolean, now?: number): number | null;
+    /** True while a search is in progress, so Space joins it instead of selecting. */
+    active(now?: number): boolean;
+    reset(): void;
+}
+/**
+ * APG typeahead: the typed string matches the start of an enabled item's
+ * label (case-insensitive), searching from the item after the active one.
+ * Repeating one letter cycles through the items that start with it.
+ */
+export declare function createTypeahead(timeout?: number): Typeahead;

package/dist/listNavigation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Index arithmetic behind the WAI-ARIA APG listbox / menu / toolbar keyboard
+ * model, shared by React `useListNavigation` and its Vue twin. Items are
+ * addressed by index; disabled items are skipped.
+ */
+export type ListOrientation = 'vertical' | 'horizontal' | 'both';
+export type ListMove = 'next' | 'prev' | 'first' | 'last';
+/** First enabled index from `from` in `step` direction (inclusive), or -1. */
+export declare function findEnabledIndex(count: number, isDisabled: (index: number) => boolean, from: number, step: 1 | -1, loop: boolean): number;
+/**
+ * Index `move` lands on from `current` (-1 = nothing active). With nothing
+ * active, next starts at the first item and prev at the last. Without `loop`
+ * the ends hold.
+ */
+export declare function moveIndex(move: ListMove, current: number, count: number, isDisabled: (index: number) => boolean, loop: boolean): number;
+/** The move a key requests for an orientation, or null when the key isn't navigation. */
+export declare function keyToMove(key: string, orientation: ListOrientation, rtl?: boolean, homeEnd?: boolean): ListMove | null;
+/** Typed characters are joined while keys arrive less than this far apart (APG). */
+export declare const TYPEAHEAD_TIMEOUT_MS = 500;
+export interface Typeahead {
+    /**
+     * Feeds one key. Returns the index to activate, -1 when nothing matches,
+     * or null when the key isn't part of typeahead (not printable, or a space
+     * that doesn't continue a search).
+     */
+    handle(key: string, current: number, count: number, getLabel: (index: number) => string, isDisabled: (index: number) => boolean, now?: number): number | null;
+    /** True while a search is in progress, so Space joins it instead of selecting. */
+    active(now?: number): boolean;
+    reset(): void;
+}
+/**
+ * APG typeahead: the typed string matches the start of an enabled item's
+ * label (case-insensitive), searching from the item after the active one.
+ * Repeating one letter cycles through the items that start with it.
+ */
+export declare function createTypeahead(timeout?: number): Typeahead;
+//# sourceMappingURL=listNavigation.d.ts.map

package/dist/richText/blockquote.d.cts

@@ -0,0 +1,11 @@
+/**
+ * Block quotes in editors built on the browser's own editing commands
+ * (`RichEditor`). `TextAreaWithToolbar` keeps quotes in its document model instead.
+ */
+/** The `<blockquote>` inside `root` that holds the selection's start, if any. */
+export declare function blockquoteAtSelection(root: Element): HTMLQuoteElement | null;
+/**
+ * Quotes the selected paragraphs, or unquotes them when the selection is
+ * already in a quote. Returns whether the selection ends up quoted.
+ */
+export declare function toggleBlockquote(root: Element): boolean;

package/dist/richText/blockquote.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Block quotes in editors built on the browser's own editing commands
+ * (`RichEditor`). `TextAreaWithToolbar` keeps quotes in its document model instead.
+ */
+/** The `<blockquote>` inside `root` that holds the selection's start, if any. */
+export declare function blockquoteAtSelection(root: Element): HTMLQuoteElement | null;
+/**
+ * Quotes the selected paragraphs, or unquotes them when the selection is
+ * already in a quote. Returns whether the selection ends up quoted.
+ */
+export declare function toggleBlockquote(root: Element): boolean;
+//# sourceMappingURL=blockquote.d.ts.map

package/dist/richText/editor.d.cts

@@ -0,0 +1,117 @@
+/**
+ * The behaviour of a `contenteditable` rich-text field, shared by the React
+ * and Vue `TextAreaWithToolbar` so both behave identically. No `document.execCommand`:
+ * formatting is applied to the document model (./model.ts) and the editor
+ * re-renders from it, so the output is always the sanitized allow-list.
+ *
+ * Plain typing inside one paragraph stays native (spell-check, autocorrect,
+ * IME); everything that would let the browser invent markup (line breaks,
+ * joining paragraphs, deleting across them, paste, drop, its own format
+ * commands) goes through the model. Native undo cannot see model edits, so
+ * the editor keeps its own history and answers Ctrl/Cmd+Z, Ctrl+Y and
+ * Ctrl/Cmd+Shift+Z (plus the browser's Undo / Redo menu items).
+ *
+ * Quote and indent are paragraph formats: Ctrl/Cmd+] indents, Ctrl/Cmd+[
+ * outdents and Ctrl/Cmd+Shift+9 toggles the quote (when `blockShortcuts`
+ * allows), and Backspace at the start of an indented or quoted paragraph
+ * removes the indent, then the quote, before it joins the paragraph above.
+ * Tab is never captured: it keeps moving focus, as in any form field.
+ */
+import { type RichTextAlign, type RichTextFormat, type RichTextMark, type RichTextMarkPatch, type RichTextStyle } from './model.cjs';
+export interface RichTextEditorOptions {
+    /** Fires when the sanitized value changes through editing (not through `setValue`). */
+    onChange?: (value: string, text: string) => void;
+    /** Fires when the format at the selection changes (drives the toolbar). */
+    onFormatChange?: (format: RichTextFormat) => void;
+    /** Formatting for text typed before the caret is first moved (e.g. start in bold). */
+    defaultMarks?: RichTextMarkPatch | null | undefined;
+    /** Whether the quote / indent shortcuts are on (e.g. only while their buttons are shown). */
+    blockShortcuts?: () => boolean;
+}
+export interface RichTextCommandOptions {
+    /** Move focus back into the editor afterwards (pointer use of a toolbar button). */
+    focus?: boolean;
+}
+export declare class RichTextEditor {
+    readonly root: HTMLElement;
+    private readonly options;
+    private doc;
+    private items;
+    private value;
+    private lastSelection;
+    private pending;
+    /** Caret the pending marks belong to; `null` until the caret is first placed. */
+    private pendingAt;
+    private history;
+    private historyIndex;
+    private lastEdit;
+    private composing;
+    private compositionStart;
+    private dragRange;
+    /** The DOM was re-rendered while focus was elsewhere, so its selection is gone. */
+    private selectionStale;
+    private formatKey;
+    private readonly cleanup;
+    constructor(root: HTMLElement, options?: RichTextEditorOptions);
+    destroy(): void;
+    /** The sanitized HTML value (`''` when empty). */
+    getValue(): string;
+    getText(): string;
+    getFormat(): RichTextFormat;
+    /** Replaces the content from outside (a controlled value). Does not fire `onChange`. */
+    setValue(html: string): void;
+    /** Bold / italic / underline: toggles the selection, or the typing format at a caret. */
+    toggleMark(mark: RichTextMark, options?: RichTextCommandOptions): void;
+    /** Colour, font family or size for the selection (or the typing format); `null` clears it. */
+    applyStyle(style: RichTextStyle, value: string | null, options?: RichTextCommandOptions): void;
+    /** Aligns every paragraph the selection touches (the caret's paragraph when collapsed). */
+    setAlign(align: RichTextAlign, options?: RichTextCommandOptions): void;
+    /** Quotes (or unquotes) every paragraph the selection touches. */
+    setQuote(on: boolean, options?: RichTextCommandOptions): void;
+    /** Sets the indent level (0 = none) of every paragraph the selection touches. */
+    setIndent(level: number | ((current: number) => number), options?: RichTextCommandOptions): void;
+    focus(): void;
+    undo(): void;
+    redo(): void;
+    private applyPatch;
+    private replace;
+    private insertText;
+    private afterModelEdit;
+    /** Publishes a changed value and records it in the history. */
+    private commit;
+    private record;
+    private stepHistory;
+    private emitFormat;
+    private render;
+    /** Re-reads the DOM after native editing; rewrites it if the browser left non-canonical markup. */
+    private syncFromDom;
+    private isFocused;
+    private endSelection;
+    /**
+     * The live selection while the editor has focus, else the last one it had
+     * (focus on a toolbar button leaves the document selection behind).
+     */
+    private currentSelection;
+    private domSelection;
+    private globalAt;
+    private posAt;
+    /** A DOM point for a model position; at a format boundary it stays with the text before it. */
+    private domPoint;
+    private restoreSelection;
+    private focusAt;
+    private pendingApplies;
+    private listen;
+    private onFocus;
+    private onSelectionChange;
+    private onKeyDown;
+    private onBeforeInput;
+    private onInput;
+    private onCompositionStart;
+    private onCompositionEnd;
+    private fragmentFrom;
+    private onPaste;
+    private writeClipboard;
+    private onCopy;
+    private onDragStart;
+    private onDrop;
+}

package/dist/richText/editor.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The behaviour of a `contenteditable` rich-text field, shared by the React
+ * and Vue `TextAreaWithToolbar` so both behave identically. No `document.execCommand`:
+ * formatting is applied to the document model (./model.ts) and the editor
+ * re-renders from it, so the output is always the sanitized allow-list.
+ *
+ * Plain typing inside one paragraph stays native (spell-check, autocorrect,
+ * IME); everything that would let the browser invent markup (line breaks,
+ * joining paragraphs, deleting across them, paste, drop, its own format
+ * commands) goes through the model. Native undo cannot see model edits, so
+ * the editor keeps its own history and answers Ctrl/Cmd+Z, Ctrl+Y and
+ * Ctrl/Cmd+Shift+Z (plus the browser's Undo / Redo menu items).
+ *
+ * Quote and indent are paragraph formats: Ctrl/Cmd+] indents, Ctrl/Cmd+[
+ * outdents and Ctrl/Cmd+Shift+9 toggles the quote (when `blockShortcuts`
+ * allows), and Backspace at the start of an indented or quoted paragraph
+ * removes the indent, then the quote, before it joins the paragraph above.
+ * Tab is never captured: it keeps moving focus, as in any form field.
+ */
+import { type RichTextAlign, type RichTextFormat, type RichTextMark, type RichTextMarkPatch, type RichTextStyle } from './model.js';
+export interface RichTextEditorOptions {
+    /** Fires when the sanitized value changes through editing (not through `setValue`). */
+    onChange?: (value: string, text: string) => void;
+    /** Fires when the format at the selection changes (drives the toolbar). */
+    onFormatChange?: (format: RichTextFormat) => void;
+    /** Formatting for text typed before the caret is first moved (e.g. start in bold). */
+    defaultMarks?: RichTextMarkPatch | null | undefined;
+    /** Whether the quote / indent shortcuts are on (e.g. only while their buttons are shown). */
+    blockShortcuts?: () => boolean;
+}
+export interface RichTextCommandOptions {
+    /** Move focus back into the editor afterwards (pointer use of a toolbar button). */
+    focus?: boolean;
+}
+export declare class RichTextEditor {
+    readonly root: HTMLElement;
+    private readonly options;
+    private doc;
+    private items;
+    private value;
+    private lastSelection;
+    private pending;
+    /** Caret the pending marks belong to; `null` until the caret is first placed. */
+    private pendingAt;
+    private history;
+    private historyIndex;
+    private lastEdit;
+    private composing;
+    private compositionStart;
+    private dragRange;
+    /** The DOM was re-rendered while focus was elsewhere, so its selection is gone. */
+    private selectionStale;
+    private formatKey;
+    private readonly cleanup;
+    constructor(root: HTMLElement, options?: RichTextEditorOptions);
+    destroy(): void;
+    /** The sanitized HTML value (`''` when empty). */
+    getValue(): string;
+    getText(): string;
+    getFormat(): RichTextFormat;
+    /** Replaces the content from outside (a controlled value). Does not fire `onChange`. */
+    setValue(html: string): void;
+    /** Bold / italic / underline: toggles the selection, or the typing format at a caret. */
+    toggleMark(mark: RichTextMark, options?: RichTextCommandOptions): void;
+    /** Colour, font family or size for the selection (or the typing format); `null` clears it. */
+    applyStyle(style: RichTextStyle, value: string | null, options?: RichTextCommandOptions): void;
+    /** Aligns every paragraph the selection touches (the caret's paragraph when collapsed). */
+    setAlign(align: RichTextAlign, options?: RichTextCommandOptions): void;
+    /** Quotes (or unquotes) every paragraph the selection touches. */
+    setQuote(on: boolean, options?: RichTextCommandOptions): void;
+    /** Sets the indent level (0 = none) of every paragraph the selection touches. */
+    setIndent(level: number | ((current: number) => number), options?: RichTextCommandOptions): void;
+    focus(): void;
+    undo(): void;
+    redo(): void;
+    private applyPatch;
+    private replace;
+    private insertText;
+    private afterModelEdit;
+    /** Publishes a changed value and records it in the history. */
+    private commit;
+    private record;
+    private stepHistory;
+    private emitFormat;
+    private render;
+    /** Re-reads the DOM after native editing; rewrites it if the browser left non-canonical markup. */
+    private syncFromDom;
+    private isFocused;
+    private endSelection;
+    /**
+     * The live selection while the editor has focus, else the last one it had
+     * (focus on a toolbar button leaves the document selection behind).
+     */
+    private currentSelection;
+    private domSelection;
+    private globalAt;
+    private posAt;
+    /** A DOM point for a model position; at a format boundary it stays with the text before it. */
+    private domPoint;
+    private restoreSelection;
+    private focusAt;
+    private pendingApplies;
+    private listen;
+    private onFocus;
+    private onSelectionChange;
+    private onKeyDown;
+    private onBeforeInput;
+    private onInput;
+    private onCompositionStart;
+    private onCompositionEnd;
+    private fragmentFrom;
+    private onPaste;
+    private writeClipboard;
+    private onCopy;
+    private onDragStart;
+    private onDrop;
+}
+//# sourceMappingURL=editor.d.ts.map

package/dist/richText/index.d.cts

@@ -0,0 +1,3 @@
+export * from './model.cjs';
+export * from './editor.cjs';
+export * from './blockquote.cjs';

package/dist/richText/index.d.ts

@@ -0,0 +1,4 @@
+export * from './model.js';
+export * from './editor.js';
+export * from './blockquote.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/richText/model.d.cts

@@ -0,0 +1,161 @@
+/**
+ * Rich-text document model shared by the React and Vue `TextAreaWithToolbar`.
+ *
+ * Every HTML string that enters the editor (a `value`, a paste, a drop, the
+ * live DOM after native typing) is read into this model and written back out
+ * by `serializeRichText`. Output is only ever produced from the model, so the
+ * allow-list is structural: text is escaped, and the only markup that can come
+ * out is `<blockquote>` around quoted paragraphs, `<p>` (optional `text-align`
+ * and a 24px `margin-left` indent), `<br>`, `<strong>`, `<em>`, `<u>` and
+ * `<span>` with validated `color` / `font-family` / `font-size`. Scripts,
+ * event handlers, URLs and every other tag or style are dropped on the way in.
+ */
+export type RichTextMark = 'bold' | 'italic' | 'underline';
+export type RichTextStyle = 'color' | 'fontFamily' | 'fontSize';
+export type RichTextAlign = 'left' | 'center' | 'right';
+/** Formatting carried by a run of text. Absent = off / inherited default. */
+export interface RichTextMarks {
+    bold?: true;
+    italic?: true;
+    underline?: true;
+    color?: string;
+    fontFamily?: string;
+    fontSize?: string;
+}
+/** A change to marks: `false` / `null` removes a mark or style. */
+export interface RichTextMarkPatch {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string | null;
+    fontFamily?: string | null;
+    fontSize?: string | null;
+}
+export interface RichTextRun {
+    /** Text; `\n` is a line break (`<br>`). */
+    text: string;
+    marks: RichTextMarks;
+}
+export interface RichTextBlock {
+    align: RichTextAlign;
+    runs: RichTextRun[];
+    /** Inside a block quote. Absent = not quoted. */
+    quote?: true;
+    /** Indent steps of {@link RICH_TEXT_INDENT_STEP}px (0 to {@link RICH_TEXT_MAX_INDENT}). Absent = 0. */
+    indent?: number;
+}
+/** One indent step, in px (`spacing.24`). */
+export declare const RICH_TEXT_INDENT_STEP = 24;
+/** Deepest indent the editor produces; the model keeps a number so more levels can follow. */
+export declare const RICH_TEXT_MAX_INDENT = 1;
+export type RichTextDoc = RichTextBlock[];
+/** A caret position: block index + character offset inside the block. */
+export interface RichTextPos {
+    block: number;
+    offset: number;
+}
+/** What the toolbar shows for the current selection. */
+export interface RichTextFormat {
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    align: RichTextAlign;
+    /** Every paragraph the selection touches is quoted. */
+    quote: boolean;
+    /** The smallest indent among the paragraphs the selection touches. */
+    indent: number;
+    /** `undefined` when the selection has no explicit value or mixes several. */
+    color: string | undefined;
+    fontFamily: string | undefined;
+    fontSize: string | undefined;
+}
+/** A CSS colour from the allow-list (hex, rgb[a](), a bare keyword), normalised, or `undefined`. */
+export declare function cleanRichTextColor(value: string): string | undefined;
+/** A font-family list made only of names, quotes, commas and hyphens, or `undefined`. */
+export declare function cleanRichTextFontFamily(value: string): string | undefined;
+/** A font size with a unit (px, pt, em, rem, %) inside sane bounds, or `undefined`. */
+export declare function cleanRichTextFontSize(value: string): string | undefined;
+export declare function applyMarkPatch(marks: RichTextMarks, patch: RichTextMarkPatch): RichTextMarks;
+export interface RichTextReadOptions {
+    /**
+     * Clipboard / drag-and-drop content from elsewhere: keep only bold, italic,
+     * underline and paragraphs (foreign colours, fonts and sizes are dropped)
+     * and collapse source-code whitespace the way a browser renders it.
+     */
+    foreign?: boolean;
+}
+/** Where a DOM node landed in the model; used to map selections. */
+export interface RichTextDomItem<N> {
+    node: N;
+    kind: 'text' | 'br' | 'placeholder' | 'block';
+    block: number;
+    start: number;
+    length: number;
+}
+/** Merges equal neighbouring runs and drops empty ones. */
+export declare function normalizeDoc(doc: RichTextDoc): RichTextDoc;
+/** Reads an HTML string (a value, or clipboard HTML with `foreign`) into the model. */
+export declare function parseRichText(html: string, options?: RichTextReadOptions): RichTextDoc;
+/** Reads the live editor DOM into the model, with where each node landed. */
+export declare function readRichTextDom(root: Node): {
+    doc: RichTextDoc;
+    items: RichTextDomItem<Node>[];
+};
+/** Builds output nodes of any kind (an HTML string, framework vnodes) from the model. */
+export interface RichTextRenderer<T> {
+    element(tag: RichTextTag, style: string | undefined, children: T[]): T;
+    text(text: string): T;
+}
+export type RichTextTag = 'blockquote' | 'p' | 'br' | 'strong' | 'em' | 'u' | 'span';
+/**
+ * The editor's paragraphs as renderer nodes: always at least one (empty)
+ * paragraph. An empty line needs a <br> to have height; so does a paragraph
+ * ending in a line break. Neighbouring quoted paragraphs share one
+ * `<blockquote>`.
+ */
+export declare function renderRichText<T>(doc: RichTextDoc, r: RichTextRenderer<T>): T[];
+/** The markup the editor renders: always at least one (empty) paragraph. */
+export declare function serializeRichText(doc: RichTextDoc): string;
+/** The public value: the serialized document, or `''` when there is no content. */
+export declare function richTextValue(doc: RichTextDoc): string;
+export declare function isRichTextEmpty(doc: RichTextDoc): boolean;
+/** Sanitizes an HTML string to the editor's allow-list. */
+export declare function sanitizeRichText(html: string, options?: RichTextReadOptions): string;
+/** Plain text of an HTML value: one line per paragraph, `<br>` as a newline. */
+export declare function richTextToPlainText(html: string): string;
+export declare function richTextDocText(doc: RichTextDoc): string;
+export declare const emptyBlock: (align?: RichTextAlign) => RichTextBlock;
+export declare function blockText(b: RichTextBlock): string;
+export declare function blockLength(b: RichTextBlock | undefined): number;
+/** Positions as one number: block boundaries count as one character. */
+export declare function toGlobal(doc: RichTextDoc, pos: RichTextPos): number;
+export declare function fromGlobal(doc: RichTextDoc, g: number): RichTextPos;
+export declare function docLength(doc: RichTextDoc): number;
+/** The content between two global positions, as a document fragment. */
+export declare function sliceDoc(doc: RichTextDoc, from: number, to: number): RichTextDoc;
+/**
+ * Replaces the range with a fragment. A one-block fragment goes inline; more
+ * blocks split the paragraph. Returns the new document and the caret after
+ * the inserted content.
+ */
+export declare function replaceRange(doc: RichTextDoc, from: number, to: number, fragment: RichTextDoc): {
+    doc: RichTextDoc;
+    caret: number;
+};
+/** Applies `change` to the marks of every character in the range. */
+export declare function formatRange(doc: RichTextDoc, from: number, to: number, change: (marks: RichTextMarks) => RichTextMarks): RichTextDoc;
+/** Sets the alignment of every block the range touches. */
+export declare function alignRange(doc: RichTextDoc, from: number, to: number, align: RichTextAlign): RichTextDoc;
+/** Quotes (or unquotes) every block the range touches. */
+export declare function quoteRange(doc: RichTextDoc, from: number, to: number, on: boolean): RichTextDoc;
+/**
+ * Sets the indent of every block the range touches, to `level` or to what
+ * `level(current)` returns; clamped to 0…{@link RICH_TEXT_MAX_INDENT}.
+ */
+export declare function indentRange(doc: RichTextDoc, from: number, to: number, level: number | ((current: number) => number)): RichTextDoc;
+/** Marks typed text would take at a caret: the character before it, else the first one. */
+export declare function marksAt(doc: RichTextDoc, g: number): RichTextMarks;
+/** The format of a selection: a mark is on only if every selected character has it. */
+export declare function formatOf(doc: RichTextDoc, anchor: number, focus: number, pending?: RichTextMarkPatch | null): RichTextFormat;
+/** The toolbar format for a value before the editor is mounted: the caret at the end. */
+export declare function richTextFormat(html: string, pending?: RichTextMarkPatch | null): RichTextFormat;