@x12i/editor 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,184 +1,220 @@
-import { ChartSpec } from '@x12i/charts';
-import { SavedView } from '@x12i/data';
-import { DiagramDocument } from '@x12i/diagrams';
+import { E as EditorDocument, B as Block, I as Inline } from './outline-Drc3E0C1.js';
+export { A as AiCommand, a as AiProvider, b as BLOCK_ID_NODES, c as BLOCK_TYPES, d as BlockBase, e as BlockType, C as CALLOUT_VARIANTS, f as CalloutVariant, g as CollaborationProvider, h as ConversionWarning, i as ConversionWarningCode, j as ConvertOptions, D as DOCUMENT_VERSION, k as InlineNode, L as ListItem, M as MARK_TYPES, l as Mark, O as OutlineItem, m as OutlineNode, n as OutlineOptions, T as TIPTAP_MARKS, o as TIPTAP_NODES, p as TableCell, q as TaskItem, r as TiptapDoc, s as TiptapMark, t as TiptapNode, u as TiptapNodeName, v as buildOutlineTree, w as createEmptyDocument, x as createParagraph, y as documentToTiptap, z as getOutline, F as isKnownBlockType, G as normalizeDocument, H as normalizeInline, J as slugifyHeading, K as tiptapToDocument } from './outline-Drc3E0C1.js';
+import '@x12i/charts';
+import '@x12i/data';
+import '@x12i/diagrams';
 
 /**
- * The stored document (spec section 11): versioned JSON owned by the kit, with
- * converters to and from the engine's format planned. That keeps the editor
- * engine (Tiptap by default) replaceable.
+ * Block ids. Every block, list item and task item carries a stable id so a
+ * diff, a comment anchor or a collaboration layer can refer to it.
  */
 
-declare const DOCUMENT_VERSION = 1;
-type Mark = {
-    type: "bold";
-} | {
-    type: "italic";
-} | {
-    type: "underline";
-} | {
-    type: "strike";
-} | {
-    type: "code";
-} | {
-    type: "link";
-    href: string;
-} | {
-    type: "color";
-    token: string;
-} | {
-    type: "highlight";
-    token: string;
-};
-type InlineNode = {
-    type: "text";
-    text: string;
-    marks?: Mark[];
-} | {
-    type: "mention";
-    kind: "person" | "page" | "date";
-    id: string;
-    label: string;
-} | {
-    type: "emoji";
-    shortcode: string;
-};
-type Inline = InlineNode[];
-interface BlockBase {
-    id: string;
+/**
+ * A new random block id: 12 lowercase base-36 characters. Uses the Web Crypto
+ * API when it exists (browsers, Node 20+, edge runtimes) and falls back to
+ * `Math.random`, so it works on the server too.
+ */
+declare function generateBlockId(): string;
+/** A small seeded PRNG (mulberry32). Deterministic across platforms. */
+declare function createSeededRandom(seed: number): () => number;
+/**
+ * A deterministic id generator for tests and fixtures: `b1`, `b2`, ... with
+ * your own prefix. Never use it for real documents.
+ */
+declare function createSequentialIdGenerator(prefix?: string, start?: number): () => string;
+/** Calls `visit` for every block, including blocks nested in toggles, columns and AI results. */
+declare function walkBlocks(blocks: readonly Block[], visit: (block: Block, parent: Block | null) => void, parent?: Block | null): void;
+/** Every id in the document: blocks (nested too), list items and task items, in document order. */
+declare function collectIds(doc: EditorDocument): string[];
+/** Ids that occur more than once. A healthy document returns an empty array. */
+declare function findDuplicateIds(doc: EditorDocument): string[];
+
+/**
+ * URL safety. Links and media in a stored document come from users, so every
+ * renderer runs them through here: http, https, mailto, tel and relative URLs
+ * pass; `javascript:`, `vbscript:`, `file:` and `data:` do not, except
+ * `data:image/*` for image sources.
+ */
+interface SanitizeUrlOptions {
+    /** Allow `data:image/*` URLs. Only set this for image sources, never for links. */
+    allowDataImage?: boolean;
+    /** Schemes (without the colon) that pass, in lower case. Defaults to http, https, mailto, tel. */
+    allowedProtocols?: readonly string[];
 }
-type CalloutVariant = "info" | "success" | "warning" | "danger" | "neutral";
-interface TaskItem {
-    id: string;
-    content: Inline;
-    checked: boolean;
-    children?: TaskItem[];
+/**
+ * Returns the trimmed URL when it is safe to render, or `null` when it is not.
+ * Relative URLs (`/a`, `./a`, `../a`, `a/b`, `#id`, `?q=1`) are safe.
+ */
+declare function sanitizeUrl(input: unknown, options?: SanitizeUrlOptions): string | null;
+/** True when `sanitizeUrl` accepts the value. */
+declare function isSafeUrl(input: unknown, options?: SanitizeUrlOptions): boolean;
+/** Sanitizer for image, video and audio sources: also lets `data:image/*` through. */
+declare function sanitizeMediaUrl(input: unknown): string | null;
+/**
+ * Turns what a person typed in a link field into a URL: bare domains get
+ * `https://`, bare email addresses get `mailto:`. Anything else is returned
+ * trimmed. Run the result through `sanitizeUrl` before storing it.
+ */
+declare function normalizeUrlInput(input: string): string;
+
+/** Text colors. Foreground tokens are chosen to keep 4.5:1 on the surface in every theme. */
+declare const TEXT_COLOR_TOKENS: readonly ["color.text.secondary", "color.text.link", "color.accent.default", "color.status.success.foreground", "color.status.warning.foreground", "color.status.danger.foreground", "color.status.info.foreground", "color.chart.categorical.4"];
+/** Highlight (background) colors. Text keeps the primary text color on top of them. */
+declare const HIGHLIGHT_TOKENS: readonly ["color.highlight", "color.accent.subtle", "color.status.success.background", "color.status.warning.background", "color.status.danger.background", "color.status.info.background"];
+type TextColorToken = (typeof TEXT_COLOR_TOKENS)[number];
+type HighlightToken = (typeof HIGHLIGHT_TOKENS)[number];
+declare function isTextColorToken(token: unknown): token is TextColorToken;
+declare function isHighlightToken(token: unknown): token is HighlightToken;
+/** The CSS custom property for a token path, for example `--kit-color-text-link`. */
+declare function tokenToCssVarName(token: string): string;
+/** `var(--kit-...)` for an allowed text color token, or `null` when the token is not on the list. */
+declare function textColorToCss(token: unknown): string | null;
+/** `var(--kit-...)` for an allowed highlight token, or `null` when the token is not on the list. */
+declare function highlightToCss(token: unknown): string | null;
+
+/** Plain text of an inline run: marks dropped, mentions as `@label`, emoji as characters. */
+declare function inlineToPlainText(inline: Inline | undefined): string;
+interface PlainTextOptions {
+    /** Text between blocks. Defaults to a blank line. */
+    blockSeparator?: string;
+    /** Prefix list items with `-`, `1.` and `[x]`. Defaults to true. Counting turns it off. */
+    markers?: boolean;
 }
-interface ListItem {
-    id: string;
-    content: Inline;
-    children?: ListItem[];
+/**
+ * The document as plain text. Blocks are separated by a blank line, lists keep
+ * their markers and tables become tab-separated rows. Blocks with no text
+ * (dividers, page breaks) are skipped. Columns read in order.
+ */
+declare function documentToPlainText(doc: EditorDocument, options?: PlainTextOptions): string;
+/**
+ * Counts words. Uses `Intl.Segmenter` when available, so Hebrew, Arabic and
+ * CJK text count correctly; otherwise it splits on whitespace.
+ */
+declare function countWords(text: string, locale?: string): number;
+/** Counts characters as the reader sees them (grapheme clusters), not UTF-16 units. */
+declare function countCharacters(text: string, options?: {
+    includeSpaces?: boolean;
+}): number;
+interface DocumentStats {
+    words: number;
+    characters: number;
+    charactersNoSpaces: number;
+    /** Top-level blocks. */
+    blocks: number;
+    /** Reading time at 200 words per minute, rounded up, at least 1 when there is any text. */
+    readingMinutes: number;
 }
-interface TableCell {
-    content: Inline;
-    colSpan?: number;
-    rowSpan?: number;
-    header?: boolean;
+/** Word, character and block counts for a document. */
+declare function getDocumentStats(doc: EditorDocument, options?: {
+    locale?: string;
+}): DocumentStats;
+
+/** English labels for the few strings an export needs. Pass `labels` to translate them. */
+interface ExportLabels {
+    tableOfContents: string;
+    chart: string;
+    diagram: string;
+    dataView: string;
+    ai: string;
+    file: string;
 }
-type Block = BlockBase & ({
-    type: "paragraph";
-    content: Inline;
-} | {
-    type: "heading";
-    level: 1 | 2 | 3 | 4;
-    content: Inline;
-} | {
-    type: "quote";
-    content: Inline;
-} | {
-    type: "callout";
-    variant: CalloutVariant;
-    content: Inline;
-} | {
-    type: "toggle";
-    summary: Inline;
-    children: Block[];
-} | {
-    type: "divider";
-} | {
-    type: "bulleted-list";
-    items: ListItem[];
-} | {
-    type: "numbered-list";
-    items: ListItem[];
-} | {
-    type: "task-list";
-    items: TaskItem[];
-} | {
-    type: "code";
-    language?: string;
-    code: string;
-} | {
-    type: "equation";
-    latex: string;
-} | {
-    type: "table";
-    headerRow?: boolean;
-    headerColumn?: boolean;
-    rows: TableCell[][];
-} | {
-    type: "image";
-    src: string;
-    alt: string;
-    caption?: Inline;
-    align?: "start" | "center" | "end";
-    width?: number;
-} | {
-    type: "video" | "audio";
-    src: string;
-    caption?: Inline;
-} | {
-    type: "file";
-    src: string;
-    name: string;
-    size?: number;
-} | {
-    type: "bookmark";
-    url: string;
-    title?: string;
-    description?: string;
-} | {
-    type: "columns";
-    columns: Block[][];
-} | {
-    type: "page-break";
-} | {
-    type: "table-of-contents";
-} | {
-    type: "chart";
-    spec: ChartSpec;
-} | {
-    type: "diagram";
-    engine: "mermaid" | "canvas" | "excalidraw";
-    diagram?: DiagramDocument;
-    source?: string;
-} | {
-    type: "data-view";
-    dataset: string;
-    view: SavedView;
-} | {
-    type: "ai";
-    prompt: string;
-    result?: Block[];
-});
-type BlockType = Block["type"];
-interface EditorDocument {
-    version: typeof DOCUMENT_VERSION;
+declare const defaultExportLabels: ExportLabels;
+interface HtmlOptions {
+    /** Prefix for generated element ids (headings, task labels). Defaults to `kit-`. */
+    idPrefix?: string;
+    /** Wrap the output in `<div data-kit="editor-view">`. Defaults to false. */
+    wrap?: boolean;
+    labels?: Partial<ExportLabels>;
+    /** Locale for number formatting (file sizes). */
+    locale?: string;
+}
+/** Escapes text for use in HTML content or a quoted attribute. */
+declare function escapeHtml(value: string): string;
+/**
+ * Renders the document as safe HTML (see the note at the top of this file).
+ * Block ids become `data-block-id`; headings get an `id` so a table of
+ * contents block can link to them.
+ */
+declare function documentToHtml(doc: EditorDocument, options?: HtmlOptions): string;
+
+interface MarkdownOptions {
+    /** Keep marks Markdown has no syntax for (underline, color, highlight) as inline HTML. Defaults to true. */
+    inlineHtml?: boolean;
+}
+/** Escapes characters that would start Markdown syntax inside running text. */
+declare function escapeMarkdown(text: string): string;
+/**
+ * Renders the document as Markdown. A level 1 `title` is not added; the
+ * document's `title` field is metadata, not content.
+ */
+declare function documentToMarkdown(doc: EditorDocument, options?: MarkdownOptions): string;
+
+interface MarkdownImportOptions {
+    /** Creates block ids. Defaults to `generateBlockId`. */
+    generateId?: () => string;
+    /** Document title to set. */
     title?: string;
-    blocks: Block[];
 }
-/** An empty document with one empty paragraph. */
-declare function createEmptyDocument(id?: string): EditorDocument;
-/** Shared document model behind a provider interface (Yjs and Hocuspocus planned). */
-interface CollaborationProvider {
-    connect(documentId: string): Promise<void>;
-    disconnect(): void;
-    onPresence(listener: (users: Array<{
-        id: string;
-        name: string;
-        color: string;
-    }>) => void): () => void;
+/** Parses inline Markdown into schema inline content (canonical form). */
+declare function markdownToInline(markdown: string): Inline;
+/**
+ * Parses Markdown into a document. Block ids are generated; Markdown has no
+ * ids. Line endings of any kind are accepted.
+ */
+declare function markdownToDocument(markdown: string, options?: MarkdownImportOptions): EditorDocument;
+
+interface DocumentDiff {
+    /** Ids present only in the newer document. */
+    added: string[];
+    /** Ids present only in the older document. */
+    removed: string[];
+    /** Ids in both whose own content differs (children of containers are compared by their own ids). */
+    changed: string[];
+    /** Ids in both, with the same content, that sit in a different order or place. */
+    moved: string[];
+    /** Ids in both with no difference. */
+    unchanged: string[];
+}
+/** Compares two documents by block id (nested blocks included). */
+declare function diffDocuments(previous: EditorDocument, next: EditorDocument): DocumentDiff;
+
+type ValidationCode = "invalid-document" | "unsupported-version" | "invalid-block" | "unknown-block-type" | "missing-id" | "duplicate-id" | "invalid-field" | "invalid-inline" | "unsafe-url" | "unknown-token";
+interface ValidationIssue {
+    code: ValidationCode;
+    /** `error` means the document cannot be rendered as is; `warning` means a renderer will neutralize it. */
+    severity: "error" | "warning";
+    /** A path such as `blocks[2].items[0].content[1]`. */
+    path: string;
+    message: string;
 }
-type AiCommand = "continue" | "summarize" | "rewrite" | "fix-grammar";
-/** Provider-agnostic hook. The kit calls no model by itself. */
-interface AiProvider {
-    run(input: {
-        command: AiCommand;
-        selection: string;
-        /** For `rewrite`, for example "formal". */
-        tone?: string;
-        signal?: AbortSignal;
-    }): AsyncIterable<string>;
+interface ValidationResult {
+    /** True when there are no errors. Warnings do not make a document invalid. */
+    valid: boolean;
+    issues: ValidationIssue[];
 }
+/** Checks an unknown value against the document schema and reports every problem found. */
+declare function validateDocument(value: unknown): ValidationResult;
+/** Type guard: the value has no structural errors (warnings are allowed). */
+declare function isEditorDocument(value: unknown): value is EditorDocument;
+/**
+ * Returns a copy of the document that is safe to render: links with unsafe
+ * URLs lose the link mark, media with unsafe sources get an empty source,
+ * and color marks outside the token allow-list are dropped. Structure and
+ * ids are kept. Renderers already neutralize these values; sanitize when
+ * you store or forward a document you do not control.
+ */
+declare function sanitizeDocument(doc: EditorDocument): EditorDocument;
+
+/**
+ * A small shortcode table for the `emoji` inline node, so exports and the
+ * editor can show a character without an emoji dependency. Unknown shortcodes
+ * render as `:shortcode:`, which is also what Markdown uses.
+ */
+declare const EMOJI_SHORTCODES: Readonly<Record<string, string>>;
+/** The character for a shortcode (with or without colons), or `null` when it is not in the table. */
+declare function emojiForShortcode(shortcode: string): string | null;
+/** The character when known, otherwise `:shortcode:`. */
+declare function emojiToText(shortcode: string): string;
 
-export { DOCUMENT_VERSION, createEmptyDocument };
-export type { AiCommand, AiProvider, Block, BlockBase, BlockType, CalloutVariant, CollaborationProvider, EditorDocument, Inline, InlineNode, ListItem, Mark, TableCell, TaskItem };
+export { Block, EMOJI_SHORTCODES, EditorDocument, HIGHLIGHT_TOKENS, Inline, TEXT_COLOR_TOKENS, collectIds, countCharacters, countWords, createSeededRandom, createSequentialIdGenerator, defaultExportLabels, diffDocuments, documentToHtml, documentToMarkdown, documentToPlainText, emojiForShortcode, emojiToText, escapeHtml, escapeMarkdown, findDuplicateIds, generateBlockId, getDocumentStats, highlightToCss, inlineToPlainText, isEditorDocument, isHighlightToken, isSafeUrl, isTextColorToken, markdownToDocument, markdownToInline, normalizeUrlInput, sanitizeDocument, sanitizeMediaUrl, sanitizeUrl, textColorToCss, tokenToCssVarName, validateDocument, walkBlocks };
+export type { DocumentDiff, DocumentStats, ExportLabels, HighlightToken, HtmlOptions, MarkdownImportOptions, MarkdownOptions, PlainTextOptions, SanitizeUrlOptions, TextColorToken, ValidationCode, ValidationIssue, ValidationResult };