@thomasfosterau/prosekit-utilities 0.0.0 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,203 @@
+import { a as DocumentViolation, c as checkAllowList, d as MarkJSON, f as NodeJSON, i as AllowList, l as defineAllowList, n as DocumentShape, o as allowListFilter, r as defineDocumentShape, s as allowListViolation, t as DocumentGrammarGuard, u as DocumentJSON } from "./document-shape-CrKjPIEf.js";
+/**
+ * Extracts plain text from a document, joining the `text` leaves with
+ * `options.separator` (default `' '`).
+ *
+ * Tolerant by design: `null`, `undefined`, a document with no `content`, a
+ * stray string or `null` inside `content`, and a `text`-typed node whose
+ * `text` is not a string all contribute nothing rather than throwing. The
+ * callers are database columns and queue payloads, where a malformed row
+ * must degrade to empty text rather than fail a batch.
+ */
+export declare function extractDocumentText(doc: NodeJSON | DocumentJSON | null | undefined, options?: {
+  readonly separator?: string | undefined;
+}): string;
+/**
+ * Extracts plain text from an inline document, joining the `text` leaves
+ * with nothing at all.
+ *
+ * This is the form a title or other flat field wants: `extractDocumentText`
+ * would turn `Rosa` + `canina` (two runs, one styled) into `Rosa canina`
+ * with a space that is already in the first run, or into `Rosacanina` with
+ * one missing — the `''` join keeps whatever whitespace the author wrote.
+ * Recurses into any node that carries `content`, so a wrapping inline node
+ * (a sidenote, a mention) still contributes its text.
+ */
+export declare function inlineDocumentText(doc: NodeJSON | DocumentJSON): string;
+/**
+ * Rewrites a document's root `type` to `doc`, ready for a ProseMirror
+ * schema.
+ *
+ * Anything that is not already `doc` is treated as an envelope name — the
+ * remap does not need to know which one, which is what lets one component
+ * serve every shape an application declares.
+ */
+export declare const toEditorDocument: <N extends string>(doc: DocumentJSON<N> | NodeJSON) => NodeJSON;
+/**
+ * Rewrites an editor document's root `type` back to the envelope `name`,
+ * ready to persist.
+ *
+ * Curried on the name so a component can bind it once
+ * (`const toStored = fromEditorDocument(shape.name)`). A document with no
+ * `content` at all becomes an empty one rather than an envelope missing its
+ * required field.
+ */
+export declare const fromEditorDocument: <N extends string>(name: N) => (doc: NodeJSON) => DocumentJSON<N>;
+/**
+ * What a node serialiser is handed alongside its node: the two recursive
+ * passes and the escaping function, so an application's serialiser renders
+ * its children exactly as the stock ones do.
+ */
+interface MarkdownContext {
+  /** Serialise a run of inline nodes (text with marks, hard breaks, atoms). */
+  readonly serialiseInline: (nodes: ReadonlyArray<NodeJSON>) => string;
+  /** Serialise a run of block nodes, grouping consecutive list siblings. */
+  readonly serialiseBlocks: (nodes: ReadonlyArray<NodeJSON>) => string;
+  /** Backslash-escape CommonMark metacharacters in literal text. */
+  readonly escape: (text: string) => string;
+}
+/** Renders one block node. Returns `''` to drop the block entirely. */
+type BlockSerialiser = (node: NodeJSON, context: MarkdownContext) => string;
+/** Renders one non-text inline node. Returns `''` to contribute nothing. */
+type InlineSerialiser = (node: NodeJSON, context: MarkdownContext) => string;
+/** Wraps already-rendered text in one mark's Markdown syntax. */
+type MarkSerialiser = (text: string, mark: MarkJSON) => string;
+/** A configured serialiser: one entry point per document shape. */
+interface MarkdownSerialiser {
+  /** A block document → multi-line Markdown, trimmed. */
+  readonly document: (doc: NodeJSON | DocumentJSON) => string;
+  /** An inline document → a single line of Markdown, trimmed. */
+  readonly inline: (doc: NodeJSON | DocumentJSON) => string;
+}
+/**
+ * Builds a Markdown serialiser.
+ *
+ * The stock cases — paragraph, heading, blockquote, code block, horizontal
+ * rule, image, table, hard break and the five marks with a Markdown form —
+ * are built in, along with the flat-list run model and the fallback that
+ * emits an unknown node's inline text rather than dropping it. `blocks`,
+ * `inlines` and `marks` are merged **over** the stock maps, so an
+ * application adds its own nodes (and may replace a stock one) without
+ * restating any of this:
+ *
+ * ```ts
+ * const toMarkdown = createMarkdownSerialiser({
+ *   inlines: { mention: mentionMarkdown },
+ *   blocks: { figure: figureMarkdown },
+ * });
+ * ```
+ *
+ * `list` is the one type a `blocks` entry cannot override: consecutive
+ * `list` siblings are one list, so the run — not the node — is the unit of
+ * serialisation, and that grouping lives here.
+ */
+export declare function createMarkdownSerialiser(options?: {
+  readonly blocks?: Record<string, BlockSerialiser> | undefined;
+  readonly inlines?: Record<string, InlineSerialiser> | undefined;
+  readonly marks?: Record<string, MarkSerialiser> | undefined;
+}): MarkdownSerialiser;
+/**
+ * CommonMark escaping for literal text.
+ *
+ * @module
+ */
+/**
+ * Backslash-escapes the CommonMark inline metacharacters in literal text, so
+ * an author's `*` stays an asterisk instead of opening emphasis.
+ *
+ * Exported because an application's own node serialiser emits literal text
+ * too — a mention's `@label`, a caption — and must escape it the same way
+ * the stock serialisers do.
+ */
+export declare function escapeMarkdown(text: string): string;
+/**
+ * A mention as its `@label`, escaped.
+ *
+ * The referenced account's id has no Markdown form and is dropped: a
+ * mention is a link to something only the application can resolve, so the
+ * text is all that survives. The label is escaped like any other literal
+ * text, so a display name containing `*` cannot open emphasis.
+ */
+export declare const mentionMarkdown: InlineSerialiser;
+/**
+ * A figure as its image line followed by the caption as an italic
+ * paragraph — Markdown has no figure element, and this is the form a reader
+ * renders closest to one.
+ *
+ * A figure whose image is dropped (an unsafe `src`) still emits its caption;
+ * a figure with no caption emits the image line alone.
+ */
+export declare const figureMarkdown: BlockSerialiser;
+/**
+ * A sidenote as a Pandoc inline footnote (`^[note]`).
+ *
+ * This is the established Markdown form for a reference aside with no
+ * separate definition block: it keeps the note where it sits in the prose
+ * and renders as a footnote in Pandoc-flavoured pipelines, the closest
+ * faithful analogue to a margin note. `^[…]` is a Pandoc extension, not core
+ * CommonMark; a plain CommonMark reader shows the bracketed content inline,
+ * which still reads as a parenthetical aside.
+ *
+ * The note holds rich inline content, so its children go through the same
+ * inline pass body prose does — `^[…]` legitimately contains inline Markdown
+ * (`[t](u)`, `*em*`, `` `code` ``), and literal `[` / `]` in a text run is
+ * already backslash-escaped so it cannot close the note early. Any newline
+ * (a hard break renders as `\␤`) is collapsed to a space afterwards: a
+ * literal newline would terminate the inline footnote and split the
+ * surrounding paragraph.
+ *
+ * A nested sidenote is flattened to its body first. A grammar restricting a
+ * sidenote to `(text | hardBreak)*` rules one out, but a persistence guard
+ * checks the node registry rather than content expressions, so a
+ * hand-crafted or migrated document can still carry one — and `^[…^[…]…]`
+ * has no valid Pandoc rendering, since the inner `]` closes the outer note.
+ */
+export declare const sidenoteMarkdown: InlineSerialiser;
+/**
+ * The default serialiser: the shared base grammar and nothing else.
+ *
+ * An application whose grammar includes an opt-in node builds its own with
+ * `createMarkdownSerialiser` rather than reaching for this one, because a
+ * node with no serialiser falls back to its inline text — readable, but not
+ * a faithful rendering of a figure or a sidenote.
+ */
+export declare const toMarkdown: MarkdownSerialiser;
+/**
+ * The safe-URL allow-list shared by every serialiser in this package.
+ *
+ * Link `href`s and image `src`s are passed through this allow-list before
+ * being embedded, so a serialiser never emits a `javascript:` / `data:` /
+ * `vbscript:` URI. Single-sourced here so the Markdown serialiser, the HTML
+ * serialiser (the ProseKit entry point) and the allow-list write-seam check can never
+ * drift apart — the SEC-XSS-001 defence-in-depth both apps this package was
+ * extracted from rely on.
+ *
+ * @module
+ */
+/**
+ * The schemes {@link isSafeHref} accepts when the caller names none.
+ *
+ * Deliberately short: these are the three a rich-text document has a reason
+ * to link to. An application that needs `tel:` or a custom scheme passes it
+ * in rather than widening the default for everyone.
+ */
+export declare const DEFAULT_SAFE_SCHEMES: ReadonlyArray<string>;
+/**
+ * Returns true when `href` is safe to embed as a link target or image
+ * source.
+ *
+ * Allowed: any of `options.schemes` (default `http`, `https`, `mailto`),
+ * root-relative paths (`/foo`, but not `//evil.example` or `/\evil.example`,
+ * both of which resolve off-origin), and fragment links (`#bar`).
+ *
+ * The scheme is read off `new URL()` rather than compared as a string
+ * prefix, which is what makes the obfuscated forms fail: the WHATWG parser
+ * lowercases the scheme and strips leading and inner ASCII whitespace and
+ * control characters before reporting it, so `JaVaScRiPt:`, `  javascript:`
+ * and `java\tscript:` all normalise to `javascript:` and are rejected. A
+ * `startsWith('javascript:')` test would pass all three.
+ */
+export declare function isSafeHref(href: unknown, options?: {
+  readonly schemes?: ReadonlyArray<string> | undefined;
+}): href is string;
+export { type AllowList, type BlockSerialiser, type DocumentGrammarGuard, type DocumentJSON, type DocumentShape, DocumentViolation, type InlineSerialiser, type MarkJSON, type MarkSerialiser, type MarkdownContext, type MarkdownSerialiser, type NodeJSON, allowListFilter, allowListViolation, checkAllowList, defineAllowList, defineDocumentShape };