@heyramzi/ui 2.11.1 → 2.11.2

package/dist/editor/block-id.js

@@ -1,62 +1,63 @@
 import { Extension } from "@tiptap/core";
 import { Plugin, PluginKey } from "@tiptap/pm/state";
+// WHY: Top-level block types that need stable IDs for agentic read/write ops.
+// Inline nodes (text, hardBreak) and list items are not top-level in ProseMirror
+// doc structure, so they are excluded.
 const TOP_LEVEL_BLOCK_TYPES = new Set([
-    "paragraph",
-    "heading",
-    "bulletList",
-    "orderedList",
-    "blockquote",
-    "codeBlock",
-    "horizontalRule"
+	"paragraph",
+	"heading",
+	"bulletList",
+	"orderedList",
+	"blockquote",
+	"codeBlock",
+	"horizontalRule"
 ]);
+/** Generate a stable unique ID for a block. Uses crypto.randomUUID() which is
+* available in Cloudflare Workers, Node 24+, and all modern browsers. */
 export function generateBlockId() {
-    return crypto.randomUUID();
+	return crypto.randomUUID();
 }
 function isTopLevelBlock(node) {
-    return TOP_LEVEL_BLOCK_TYPES.has(node.type.name);
+	return TOP_LEVEL_BLOCK_TYPES.has(node.type.name);
 }
 const blockIdPluginKey = new PluginKey("blockId");
+/**
+* TipTap extension that stamps a stable unique `id` on every top-level block,
+* set on creation and kept on update. Opt in via the `blockIds` prop.
+*/
 export const BlockIdExtension = Extension.create({
-    name: "blockId",
-    addGlobalAttributes () {
-        return [
-            {
-                types: Array.from(TOP_LEVEL_BLOCK_TYPES),
-                attributes: {
-                    id: {
-                        default: null,
-                        parseHTML: (element)=>element.getAttribute("data-block-id") || null,
-                        renderHTML: (attributes)=>{
-                            if (!attributes.id) return {};
-                            return {
-                                "data-block-id": attributes.id
-                            };
-                        }
-                    }
-                }
-            }
-        ];
-    },
-    addProseMirrorPlugins () {
-        return [
-            new Plugin({
-                key: blockIdPluginKey,
-                appendTransaction (_transactions, _oldState, newState) {
-                    const { tr, doc } = newState;
-                    let changed = false;
-                    doc.forEach((node, offset)=>{
-                        if (!isTopLevelBlock(node)) return;
-                        if (node.attrs.id) return;
-                        const id = generateBlockId();
-                        tr.setNodeMarkup(offset, undefined, {
-                            ...node.attrs,
-                            id
-                        });
-                        changed = true;
-                    });
-                    return changed ? tr : null;
-                }
-            })
-        ];
-    }
+	name: "blockId",
+	addGlobalAttributes() {
+		return [{
+			types: Array.from(TOP_LEVEL_BLOCK_TYPES),
+			attributes: { id: {
+				default: null,
+				parseHTML: (element) => element.getAttribute("data-block-id") || null,
+				renderHTML: (attributes) => {
+					if (!attributes.id) return {};
+					return { "data-block-id": attributes.id };
+				}
+			} }
+		}];
+	},
+	addProseMirrorPlugins() {
+		return [new Plugin({
+			key: blockIdPluginKey,
+			appendTransaction(_transactions, _oldState, newState) {
+				const { tr, doc } = newState;
+				let changed = false;
+				doc.forEach((node, offset) => {
+					if (!isTopLevelBlock(node)) return;
+					if (node.attrs.id) return;
+					const id = generateBlockId();
+					tr.setNodeMarkup(offset, undefined, {
+						...node.attrs,
+						id
+					});
+					changed = true;
+				});
+				return changed ? tr : null;
+			}
+		})];
+	}
 });

package/dist/editor/block-ops.js

@@ -1,105 +1,133 @@
+// WHY: pure, server-safe block edits. No DB, HTTP or DOM, and every op returns
+// a new doc without touching the input.
+// Top-level blocks must carry `id` attrs. An unknown id throws.
 import { markdownToTiptap } from "./markdown.js";
+// =========================
+// HELPERS
+// =========================
 function extractText(nodes) {
-    if (!nodes?.length) return "";
-    return nodes.map((n)=>{
-        if (n.type === "text") return n.text ?? "";
-        if (n.type === "hardBreak") return " ";
-        return extractText(n.content);
-    }).join("");
+	if (!nodes?.length) return "";
+	return nodes.map((n) => {
+		if (n.type === "text") return n.text ?? "";
+		if (n.type === "hardBreak") return " ";
+		return extractText(n.content);
+	}).join("");
 }
 function blockText(node) {
-    const raw = extractText(node.content).trim();
-    return raw.length > 120 ? raw.slice(0, 117) + "..." : raw;
+	// For list nodes, join item texts separated by spaces.
+	const raw = extractText(node.content).trim();
+	// Truncate for preview.
+	return raw.length > 120 ? raw.slice(0, 117) + "..." : raw;
 }
 function getId(node) {
-    const id = node.attrs?.id;
-    return typeof id === "string" && id.length > 0 ? id : null;
+	const id = node.attrs?.id;
+	return typeof id === "string" && id.length > 0 ? id : null;
 }
 function requireDoc(doc) {
-    const d = doc;
-    if (!d || d.type !== "doc" || !Array.isArray(d.content)) {
-        throw new Error("Invalid doc: expected { type: 'doc', content: [...] }");
-    }
-    return d;
+	const d = doc;
+	if (!d || d.type !== "doc" || !Array.isArray(d.content)) {
+		throw new Error("Invalid doc: expected { type: 'doc', content: [...] }");
+	}
+	return d;
 }
 function requireBlockById(doc, id) {
-    const idx = doc.content.findIndex((n)=>getId(n) === id);
-    if (idx === -1) {
-        throw new Error(`Block id "${id}" not found in doc`);
-    }
-    return idx;
+	const idx = doc.content.findIndex((n) => getId(n) === id);
+	if (idx === -1) {
+		throw new Error(`Block id "${id}" not found in doc`);
+	}
+	return idx;
 }
 function newBlocksFromMd(markdown) {
-    const parsed = markdownToTiptap(markdown);
-    return parsed.content;
+	const parsed = markdownToTiptap(markdown);
+	return parsed.content;
 }
+// =========================
+// PUBLIC OPS
+// =========================
+/**
+* Return a flat list of top-level blocks with id, type, and plain-text preview.
+*/
 export function listBlocks(doc) {
-    const d = requireDoc(doc);
-    return d.content.map((node)=>({
-            id: getId(node) ?? "",
-            type: node.type,
-            text: blockText(node)
-        }));
+	const d = requireDoc(doc);
+	return d.content.map((node) => ({
+		id: getId(node) ?? "",
+		type: node.type,
+		text: blockText(node)
+	}));
 }
+/**
+* Append blocks parsed from `markdown` after the last block.
+* Returns a new doc.
+*/
 export function appendBlocks(doc, markdown) {
-    const d = requireDoc(doc);
-    const added = newBlocksFromMd(markdown);
-    return {
-        type: "doc",
-        content: [
-            ...d.content,
-            ...added
-        ]
-    };
+	const d = requireDoc(doc);
+	const added = newBlocksFromMd(markdown);
+	return {
+		type: "doc",
+		content: [...d.content, ...added]
+	};
 }
+/**
+* Prepend blocks parsed from `markdown` before the first block.
+* Returns a new doc.
+*/
 export function prependBlocks(doc, markdown) {
-    const d = requireDoc(doc);
-    const added = newBlocksFromMd(markdown);
-    return {
-        type: "doc",
-        content: [
-            ...added,
-            ...d.content
-        ]
-    };
+	const d = requireDoc(doc);
+	const added = newBlocksFromMd(markdown);
+	return {
+		type: "doc",
+		content: [...added, ...d.content]
+	};
 }
+/**
+* Insert blocks parsed from `markdown` immediately after the block with `afterId`.
+* Throws if `afterId` does not exist.
+* Returns a new doc.
+*/
 export function insertBlocksAfter(doc, afterId, markdown) {
-    const d = requireDoc(doc);
-    const idx = requireBlockById(d, afterId);
-    const added = newBlocksFromMd(markdown);
-    const content = [
-        ...d.content.slice(0, idx + 1),
-        ...added,
-        ...d.content.slice(idx + 1)
-    ];
-    return {
-        type: "doc",
-        content
-    };
+	const d = requireDoc(doc);
+	const idx = requireBlockById(d, afterId);
+	const added = newBlocksFromMd(markdown);
+	const content = [
+		...d.content.slice(0, idx + 1),
+		...added,
+		...d.content.slice(idx + 1)
+	];
+	return {
+		type: "doc",
+		content
+	};
 }
+/**
+* Replace the block with `id` with blocks parsed from `markdown`.
+* Throws if `id` does not exist.
+* Returns a new doc.
+*/
 export function replaceBlock(doc, id, markdown) {
-    const d = requireDoc(doc);
-    const idx = requireBlockById(d, id);
-    const added = newBlocksFromMd(markdown);
-    const content = [
-        ...d.content.slice(0, idx),
-        ...added,
-        ...d.content.slice(idx + 1)
-    ];
-    return {
-        type: "doc",
-        content
-    };
+	const d = requireDoc(doc);
+	const idx = requireBlockById(d, id);
+	const added = newBlocksFromMd(markdown);
+	const content = [
+		...d.content.slice(0, idx),
+		...added,
+		...d.content.slice(idx + 1)
+	];
+	return {
+		type: "doc",
+		content
+	};
 }
+/**
+* Delete the block with `id`.
+* Throws if `id` does not exist.
+* Returns a new doc.
+*/
 export function deleteBlock(doc, id) {
-    const d = requireDoc(doc);
-    const idx = requireBlockById(d, id);
-    const content = [
-        ...d.content.slice(0, idx),
-        ...d.content.slice(idx + 1)
-    ];
-    return {
-        type: "doc",
-        content
-    };
+	const d = requireDoc(doc);
+	const idx = requireBlockById(d, id);
+	const content = [...d.content.slice(0, idx), ...d.content.slice(idx + 1)];
+	return {
+		type: "doc",
+		content
+	};
 }