creo-edit 0.1.0

package/dist/createEditor.d.ts

@@ -0,0 +1,252 @@
+import type { PublicView, Store } from "creo";
+import { type SetBlockTypePayload } from "./commands/structuralCommands";
+import { emptyDoc } from "./model/doc";
+import type { Anchor, BlockId, BlockSpec, DistOmit, DocState, Mark, Selection } from "./model/types";
+/**
+ * Input shape for `appendBlocks` / `prependBlocks` — same as `BlockSpec`
+ * but with `id` optional. The editor generates an id when missing so most
+ * callers can stay terse:
+ *
+ *   editor.appendBlocks([{ type: "p", runs: [] }]);
+ */
+export type BlockInsertInput = DistOmit<BlockSpec, "id"> & {
+    id?: BlockId;
+};
+import { Registry } from "./plugin/registry";
+import type { EditorPlugin } from "./plugin/types";
+export type SerializedRun = {
+    text: string;
+    marks?: string[];
+};
+/**
+ * SerializedBlock — wire shape the editor reads from `setDoc()` and emits
+ * from `toJSON()`. Built-in block types are listed exhaustively here so the
+ * compiler still catches typos in user code. Plugins that introduce new
+ * block types extend the runtime serialize codec registry without changing
+ * this type — their entries appear as the catch-all `Record<string, unknown>`
+ * branch.
+ */
+export type SerializedBlock = {
+    id?: string;
+    type: "p";
+    runs: SerializedRun[];
+} | {
+    id?: string;
+    type: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+    runs: SerializedRun[];
+} | {
+    id?: string;
+    type: "li";
+    ordered: boolean;
+    depth?: 0 | 1 | 2 | 3;
+    runs: SerializedRun[];
+} | {
+    id?: string;
+    type: "code";
+    runs: SerializedRun[];
+    lang?: string;
+} | {
+    id?: string;
+    type: "img";
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+} | {
+    id?: string;
+    type: "table";
+    rows: number;
+    cols: number;
+    cells: SerializedRun[][][];
+} | {
+    id?: string;
+    type: "columns";
+    cols: number;
+    cells: SerializedRun[][];
+} | {
+    id?: string;
+    type: "calendar";
+    date: string;
+    days: number;
+} | {
+    id?: string;
+    type: "date-marker";
+    date: string;
+};
+/**
+ * Catch-all shape for plugin-introduced block types. Plugins serializing
+ * outside the built-in union should cast through this when constructing
+ * `SerializedDoc.blocks` — the runtime serialize codec registry handles
+ * dispatch by `type` and ignores extra fields.
+ */
+export type ExternalSerializedBlock = {
+    id?: string;
+    type: string;
+    [k: string]: unknown;
+};
+export type SerializedDoc = {
+    blocks: SerializedBlock[];
+};
+export type EditorViewProps = {
+    class?: string;
+};
+/**
+ * Built-in command shape. Plugin commands dispatch through the same
+ * `dispatch()` entry point using the `{ t: string; payload?: unknown }`
+ * fallback shape — see `Editor.dispatch` below.
+ */
+export type Command = {
+    t: "noop";
+} | {
+    t: "insertText";
+    text: string;
+} | {
+    t: "deleteBackward";
+} | {
+    t: "deleteForward";
+} | {
+    t: "splitBlock";
+} | {
+    t: "mergeBackward";
+} | {
+    t: "mergeForward";
+} | {
+    t: "setBlockType";
+    payload: SetBlockTypePayload;
+} | {
+    t: "toggleMark";
+    mark: Mark;
+} | {
+    t: "toggleList";
+    ordered: boolean;
+} | {
+    t: "indentList";
+} | {
+    t: "outdentList";
+} | {
+    t: "insertImage";
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+} | {
+    t: "insertTable";
+    rows: number;
+    cols: number;
+} | {
+    t: "insertColumns";
+    cols: number;
+} | {
+    t: "tableInsertRow";
+    where: "above" | "below";
+} | {
+    t: "tableInsertCol";
+    where: "before" | "after";
+} | {
+    t: "tableRemoveRow";
+} | {
+    t: "tableRemoveCol";
+} | {
+    t: "moveCursor";
+    to: Anchor;
+    extend?: boolean;
+};
+/** Anything dispatchable — the typed `Command` union for built-ins, plus the
+ *  open `{ t: string; payload?: unknown }` shape for plugin commands. */
+export type DispatchableCommand = Command | {
+    t: string;
+    payload?: unknown;
+};
+/**
+ * Editing mode.
+ *
+ *  - `"wysiwyg"`: rich-text editor with all blocks rendered visually.
+ *  - `"md"`: raw markdown source view (the doc is serialized to markdown
+ *    and edited as plain text); markdown-shortcut input rules also active
+ *    when the user re-enters wysiwyg via mdShortcutsPlugin.
+ *
+ * Replaces the older `"regular" | "mono"` cosmetic flag — host apps that
+ * want a monospaced editor should add their own CSS class.
+ */
+export type EditorMode = "wysiwyg" | "md";
+export type EditorOptions = {
+    initial?: SerializedDoc;
+    uploadImage?: (f: File) => Promise<string>;
+    /**
+     * Enable virtualized rendering — only blocks intersecting the viewport
+     * are mounted. Recommended for documents with > ~500 blocks. The host
+     * page must put a scroll container around the editor for this to work.
+     */
+    virtualized?: boolean;
+    /** Estimated block height (px) when virtualized — default 32. */
+    virtualEstimatedHeight?: number;
+    /**
+     * Initial editing mode — see `EditorMode`. Defaults to `"wysiwyg"`.
+     * Toggle at runtime via `editor.setMode(...)`.
+     */
+    mode?: EditorMode;
+    /**
+     * Plugins to install in addition to the default set (paragraph, heading,
+     * list, code-block, image, cells). Registered AFTER built-ins so plugin
+     * codecs can override built-in HTML matchers by registering more specific
+     * tag matchers.
+     */
+    plugins?: EditorPlugin[];
+};
+export type Editor = {
+    docStore: Store<DocState>;
+    selStore: Store<Selection>;
+    /** Dispatch any registered command — typed built-ins or plugin commands. */
+    dispatch: (cmd: DispatchableCommand) => void;
+    undo: () => void;
+    redo: () => void;
+    EditorView: PublicView<EditorViewProps, void>;
+    setDocFromHTML: (html: string) => void;
+    /**
+     * Replace the entire document with a SerializedDoc. Resets selection to
+     * the end and clears history — used for swapping content on top of a
+     * long-lived editor instance (e.g. routing between different docs in a
+     * docs site without reallocating the input pipeline & DOM listeners).
+     */
+    setDoc: (doc: SerializedDoc) => void;
+    toJSON: () => SerializedDoc;
+    /**
+     * Append `specs` to the end of the doc. Preserves all existing block
+     * identities (no full rebuild) so existing renders stay; the renderer's
+     * identity-based shouldUpdate skips them. Returns the assigned block ids.
+     * Specs may omit `id`; an id is generated when missing. Selection is left
+     * untouched — callers move the caret separately if they want it on a new
+     * block.
+     */
+    appendBlocks: (specs: BlockInsertInput[]) => BlockId[];
+    /**
+     * Prepend `specs` to the start of the doc. Same identity-preserving
+     * mutation as `appendBlocks`. NOTE: prepending grows the doc upward; the
+     * viewport will jump unless the host re-anchors scrollTop. The
+     * `infiniteScrollPlugin` does this anchoring automatically; manual
+     * callers can capture `scrollHeight` + `scrollTop` before the call and
+     * adjust after the next animation frame.
+     */
+    prependBlocks: (specs: BlockInsertInput[]) => BlockId[];
+    focus: () => void;
+    blur: () => void;
+    /** Read or change the editing mode (wysiwyg ↔ md). */
+    getMode: () => EditorMode;
+    setMode: (mode: EditorMode) => void;
+    /** Plugin registry for this editor instance — exposed for advanced
+     *  consumers (devtools, the M3 trigger manager, etc.). */
+    registry: Registry;
+    /**
+     * Scroll a block into view by id. Works for both virtualized and
+     * non-virtualized editors — for virtualized off-screen blocks, jumps
+     * the scroll container to the height-index-resolved Y. Used by the
+     * search plugin's jump-to-match; safe for any host code that wants
+     * to focus a specific block (e.g. permalink navigation).
+     */
+    scrollToBlock: (blockId: BlockId, opts?: {
+        block?: "start" | "center" | "end" | "nearest";
+        behavior?: ScrollBehavior;
+    }) => void;
+};
+export declare function createEditor(opts?: EditorOptions): Editor;
+export { emptyDoc };

package/dist/dom/anchorMap.d.ts

@@ -0,0 +1,27 @@
+import type { Anchor, BlockId } from "../model/types";
+export type BlockKind = "p" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "li" | "code" | "img" | "table" | "columns";
+/**
+ * Find the OUTER block element with the given block id, scoped under `root`.
+ *
+ * Required filter: both `data-block-id` and `data-block-kind` — the latter
+ * disambiguates the block container from inner cells (table cells / column
+ * cells share the owning block's `data-block-id`).
+ */
+export declare function findBlockElementById(root: HTMLElement, blockId: BlockId): HTMLElement | null;
+/**
+ * Convert a (DOM node, offset) selection point into an editor Anchor.
+ *
+ * Returns null when the node is outside any block element (e.g. user clicked
+ * editor chrome). Coarse but never crashes.
+ */
+export declare function domToAnchor(node: Node, offset: number, root: HTMLElement): Anchor | null;
+export type DomPoint = {
+    node: Node;
+    offset: number;
+};
+/**
+ * Convert an editor Anchor into a (DOM node, offset) pair suitable for
+ * `Range.setStart` / `Selection.collapse`. Returns null when the block can't
+ * be found in the DOM (not yet rendered, virtualized off-screen, etc.).
+ */
+export declare function anchorToDom(anchor: Anchor, root: HTMLElement): DomPoint | null;

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+export { createEditor } from "./createEditor";
+export type { Editor, EditorOptions, EditorViewProps, Command, DispatchableCommand, BlockInsertInput, SerializedBlock, SerializedDoc, SerializedRun, EditorMode, } from "./createEditor";
+export { DocView } from "./render/DocView";
+export { ParagraphView } from "./render/blocks/ParagraphView";
+export { HeadingView } from "./render/blocks/HeadingView";
+export { ListItemView } from "./render/blocks/ListItemView";
+export { CodeBlockView } from "./render/blocks/CodeBlockView";
+export { TableViewPlugin as TableView } from "./plugins/cells/views";
+export { ColumnsViewPlugin as ColumnsView } from "./plugins/cells/views";
+export { ImageView } from "./render/blocks/ImageView";
+export { InlineRunsView } from "./render/InlineRunsView";
+export { isCoarsePointer } from "./input/mobile";
+export { domToAnchor, anchorToDom, findBlockElementById, } from "./dom/anchorMap";
+export { VirtualDoc } from "./virtual/VirtualDoc";
+export { HeightIndex } from "./virtual/heightIndex";
+export type { Block, BlockId, BlockSpec, BlockType, CodeBlock, ColumnsBlock, DistOmit, DocState, FracIndex, HeadingBlock, HeadingLevel, ImageBlock, InlineRun, ListItemBlock, Mark, ParagraphBlock, TableBlock, Anchor, Selection, } from "./model/types";
+export { emptyDoc, docFromBlocks, insertAt, insertAfter, insertWithIndex, insertManyAt, updateBlock, removeBlock, findInsertionPos, findPos, blockAt, getBlock, iterBlocks, newBlockId, maybeRebalance, } from "./model/doc";
+export { generateBetween, generateN, needsRebalance, rebalance, REBALANCE_THRESHOLD, } from "./model/fractional";
+export type { EditorPlugin, BlockDef, CommandDef, KeymapDef, TriggerDef, TriggerCtx, TriggerController, DecorationDef, AnchorCodec, HtmlBlockCodec, HtmlParseCtx, SerializeCodec, RunsCtx, CommandCtx, DomPoint, } from "./plugin/types";
+export { Registry } from "./plugin/registry";
+export { defaultPlugins, paragraphPlugin, headingPlugin, listPlugin, codeBlockPlugin, imagePlugin, cellsPlugin, } from "./plugin/builtin";
+export { runsAt, runsLengthAt } from "./plugin/runsAt";
+export { atomicCodec, defaultTextCodec, codeBlockCodec, imageCodec, } from "./plugin/anchorCodec";
+export { isAtomicBlockType, registerAtomic } from "./plugin/atomic";
+export { TriggerManager } from "./plugin/triggers";
+export { DecorationManager } from "./plugin/decorations";
+export { slashCommandsPlugin, defaultSlashItems, defaultFilter as defaultSlashFilter, mountSlashMenu, type SlashItem, type MenuHandle as SlashMenuHandle, type MenuOptions as SlashMenuOptions, } from "./plugins/slash";
+export { dragHandlePlugin, type DragHandleOptions } from "./plugins/drag-handle";
+export { addBlockPlugin, type AddBlockOptions } from "./plugins/add-block";
+export { mdShortcutsPlugin } from "./plugins/md-shortcuts";
+export { calendarPlugin, calendarSlashItem, CalendarView, DateMarkerView, calendarHelpers, } from "./plugins/calendar";
+export { infiniteScrollPlugin, type InfiniteScrollEditor, type InfiniteScrollOptions, } from "./plugins/infinite-scroll";
+export { searchPlugin, type SearchOptions, type SearchController, type SearchSource, type SearchState, type SearchToggle, type SearchMatch, type SearchOpts, } from "./plugins/search";
+export { docToMarkdown } from "./markdown/serialize";