@reiwuzen/blocky 1.3.4 → 1.4.1

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   applyMarkdownTransform: () => applyMarkdownTransform,
+  areBlocksSame: () => areBlocksSame,
   canRedo: () => canRedo,
   canUndo: () => canUndo,
   changeBlockType: () => changeBlockType,
@@ -619,18 +620,15 @@ function buildMetaForTarget(targetType) {
     case "number":
     case "todo":
       return { depth: 0 };
-    case "heading1":
-    case "heading2":
-    case "heading3":
-    case "paragraph":
-    case "code":
-    case "equation":
+    default:
       return {};
   }
 }
+function isList(type) {
+  return type === "bullet" || type === "todo" || type === "number";
+}
 function deriveMeta(block, targetType) {
-  if (isList(block.type) && isList(targetType))
-    return block.meta;
+  if (isList(block.type) && isList(targetType)) return block.meta;
   return buildMetaForTarget(targetType);
 }
 function toggleTodo(block) {
@@ -645,9 +643,6 @@ var MAX_DEPTH = 6;
 function isIndentable(block) {
   return block.type === "bullet" || block.type === "number" || block.type === "todo";
 }
-function isList(type) {
-  return type === "bullet" || type === "todo" || type === "number";
-}
 function indentBlock(block) {
   if (!isIndentable(block))
     return import_result4.Result.Err(
@@ -671,6 +666,31 @@ function outdentBlock(block) {
     meta: { ...block.meta, depth: block.meta.depth - 1 }
   });
 }
+function areBlocksSame(blocks, withBlocks) {
+  if (blocks.length !== withBlocks.length) return false;
+  return blocks.every((a, i) => {
+    const b = withBlocks[i];
+    if (a.type !== b.type) return false;
+    if (JSON.stringify(a.meta) !== JSON.stringify(b.meta)) return false;
+    if (a.content.length !== b.content.length) return false;
+    return a.content.every((an, j) => {
+      const bn = b.content[j];
+      if (an.type !== bn.type) return false;
+      switch (an.type) {
+        case "code":
+          return an.text === bn.text;
+        case "equation":
+          return an.latex === bn.latex;
+        case "text": {
+          const bt = bn;
+          return an.text === bt.text && an.bold === bt.bold && an.italic === bt.italic && an.underline === bt.underline && an.strikethrough === bt.strikethrough && an.highlighted === bt.highlighted && an.color === bt.color && an.link === bt.link;
+        }
+        default:
+          return false;
+      }
+    });
+  });
+}
 
 // src/engine/serializer.ts
 var import_result5 = require("@reiwuzen/result");
@@ -769,6 +789,7 @@ function nodesToMarkdown(nodes) {
   return nodes.map((n) => {
     if (n.type === "code") return `\`${n.text}\``;
     if (n.type === "equation") return `$${n.latex}$`;
+    if (n.type === "ref") return `[${n.label}](${n.href})`;
     let text = n.text;
     if (n.bold) text = `**${text}**`;
     if (n.italic) text = `*${text}*`;
@@ -857,6 +878,7 @@ var currentBlocks = (history) => history.present.blocks;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   applyMarkdownTransform,
+  areBlocksSame,
   canRedo,
   canUndo,
   changeBlockType,

package/dist/index.d.cts

@@ -5,12 +5,16 @@ type Node = {
     type: "text";
     text: string;
     highlighted?: "yellow" | "green";
-    color?: "red" | 'blue' | 'green';
+    color?: "red" | "blue" | "green";
     bold?: true;
     italic?: true;
     underline?: true;
     strikethrough?: true;
     link?: string;
+} | {
+    type: "ref";
+    href: string;
+    label: string;
 } | {
     type: "code";
     text: string;
@@ -111,47 +115,98 @@ declare const removeLink: (nodes: Node[], sel: NodeSelection) => Result<Node[],
 
 type TransformResult = {
     block: AnyBlock;
+    /** true if the block type was actually changed, false if no trigger matched */
     converted: boolean;
 };
 /**
- * Call this when a space is typed.
+ * Attempt to convert a paragraph block into another type based on a
+ * Markdown-style prefix typed by the user.
+ *
+ * Call this when a **space** is typed inside a paragraph block.
+ *
+ * Supported triggers (must appear at position 0, immediately before the space):
+ *
+ * | Typed    | Converts to |
+ * |----------|-------------|
+ * | `-`      | bullet      |
+ * | `1.`     | number      |
+ * | `[]`     | todo        |
+ * | `#`      | heading1    |
+ * | `##`     | heading2    |
+ * | `###`    | heading3    |
  *
- * Guards (returns converted=false if any fail):
- *   1. block.type must be "paragraph"
- *   2. cursorOffset must be ≤ trigger.length + 1
- *      — ensures the space was typed right after the trigger at position 0
- *      — blocks mid-text spaces like "hello - " from converting
- *   3. text must start with a known trigger prefix
+ * Guards — returns `converted: false` without mutating if any fail:
+ *   1. `block.type` must be `"paragraph"`
+ *   2. The text must start with a known trigger prefix
+ *   3. `cursorOffset` must be ≥ `trigger.length + 1` — ensures the space
+ *      was typed right after the trigger (blocks mid-text triggers like
+ *      `"hello - "` from accidentally converting)
+ *
+ * On success the returned block has the trigger prefix stripped from its
+ * content and a freshly built `meta` for the target type.
  */
 declare function applyMarkdownTransform(block: AnyBlock, cursorOffset: number): Result<TransformResult>;
 /**
- * Convert a block to a new type while preserving content as much as possible.
+ * Convert a block to a new type, preserving content and meta where possible.
+ *
+ * Content conversion rules:
  *
- * rich → rich         keep content as-is, update type + meta
- * rich → code         strip all formatting, concat all text → [CodeNode]
- * rich → equation     strip all formatting, concat all text → [EquationNode]
- * code → rich         single TextNode with code.text
- * equation → rich     single TextNode with equation.latex
- * code → equation     [EquationNode] with code.text as latex
- * equation → code     [CodeNode] with equation.latex as text
+ * | From        | To          | Content result                         |
+ * |-------------|-------------|----------------------------------------|
+ * | rich        | rich        | kept as-is                             |
+ * | rich        | code        | all text concatenated → `[CodeNode]`   |
+ * | rich        | equation    | all text concatenated → `[EquationNode]`|
+ * | code        | rich        | `code.text` → single `TextNode`        |
+ * | equation    | rich        | `equation.latex` → single `TextNode`   |
+ * | code        | equation    | `code.text` as `latex`                 |
+ * | equation    | code        | `equation.latex` as `text`             |
+ *
+ * Meta conversion rules:
+ * - list → list  : `meta` (including `depth`) is preserved
+ * - anything else: fresh default `meta` is built for the target type
  */
 declare function changeBlockType<T extends BlockType>(block: AnyBlock, targetType: T): Result<Block<T>>;
 /**
  * Toggle the checked state of a todo block.
- * checked: undefined → checked: true → checked: undefined (cycle)
+ *
+ * Cycle: `undefined → true → undefined`
+ *
+ * Returns `Err` if the block is not of type `"todo"`.
  */
 declare function toggleTodo(block: AnyBlock): Result<Block<"todo">>;
 type IndentableBlock = Block<"bullet"> | Block<"number"> | Block<"todo">;
 /**
- * Increase the depth of a bullet, number, or todo block by 1.
- * Max depth is 6. Returns Err if block type is not indentable.
+ * Increase the indentation depth of a list block (`bullet`, `number`, `todo`) by 1.
+ *
+ * - Maximum depth is `6`.
+ * - Returns `Err` if the block type is not indentable or is already at max depth.
  */
 declare function indentBlock(block: AnyBlock): Result<IndentableBlock>;
 /**
- * Decrease the depth of a bullet, number, or todo block by 1.
- * Min depth is 0. Returns Err if block type is not indentable or already at 0.
+ * Decrease the indentation depth of a list block (`bullet`, `number`, `todo`) by 1.
+ *
+ * - Minimum depth is `0`.
+ * - Returns `Err` if the block type is not indentable or is already at depth 0.
  */
 declare function outdentBlock(block: AnyBlock): Result<IndentableBlock>;
+/**
+ * Deep-equality check between two block arrays.
+ *
+ * Two arrays are considered the same when:
+ *   - They have the same length
+ *   - Every block at the same index has the same `id`, `type`, `meta`, and `content`
+ *
+ * Content nodes are compared field-by-field. Unknown extra fields on nodes are
+ * ignored so the check stays stable across schema additions.
+ *
+ * Useful for preventing redundant saves or snapshot writes:
+ * ```ts
+ * if (!areBlocksSame(current, saved)) {
+ *   await createSnapshot(current);
+ * }
+ * ```
+ */
+declare function areBlocksSame(blocks: AnyBlock[], withBlocks: AnyBlock[]): boolean;
 
 /**
  * Serialize an array of blocks to a JSON string.
@@ -267,4 +322,4 @@ declare function duplicateBlockAfter(blocks: AnyBlock[], id: string, newId?: str
  */
 declare function moveBlock(blocks: AnyBlock[], id: string, direction: "up" | "down"): Result<AnyBlock[], string>;
 
-export { type AnyBlock, type Block, type BlockContent, type BlockMeta, type BlockType, type History, type HistoryEntry, type Node, type NodeSelection, applyMarkdownTransform, canRedo, canUndo, changeBlockType, createBlock, createBlockAfter, createHistory, currentBlocks, deleteBlock, deleteLastChar, deleteRange, deserialize, deserializeNodes, duplicateBlock, duplicateBlockAfter, formatNodes, generateId, indentBlock, insertAt, insertBlockAfter, mergeAdjacentNodes, mergeBlocks, moveBlock, outdentBlock, push, redo, removeLink, replaceRange, serialize, serializeNodes, setLink, splitBlock, toMarkdown, toPlainText, toggleBold, toggleColor, toggleHighlight, toggleItalic, toggleStrikethrough, toggleTodo, toggleUnderline, undo };
+export { type AnyBlock, type Block, type BlockContent, type BlockMeta, type BlockType, type History, type HistoryEntry, type Node, type NodeSelection, applyMarkdownTransform, areBlocksSame, canRedo, canUndo, changeBlockType, createBlock, createBlockAfter, createHistory, currentBlocks, deleteBlock, deleteLastChar, deleteRange, deserialize, deserializeNodes, duplicateBlock, duplicateBlockAfter, formatNodes, generateId, indentBlock, insertAt, insertBlockAfter, mergeAdjacentNodes, mergeBlocks, moveBlock, outdentBlock, push, redo, removeLink, replaceRange, serialize, serializeNodes, setLink, splitBlock, toMarkdown, toPlainText, toggleBold, toggleColor, toggleHighlight, toggleItalic, toggleStrikethrough, toggleTodo, toggleUnderline, undo };

package/dist/index.d.ts

@@ -5,12 +5,16 @@ type Node = {
     type: "text";
     text: string;
     highlighted?: "yellow" | "green";
-    color?: "red" | 'blue' | 'green';
+    color?: "red" | "blue" | "green";
     bold?: true;
     italic?: true;
     underline?: true;
     strikethrough?: true;
     link?: string;
+} | {
+    type: "ref";
+    href: string;
+    label: string;
 } | {
     type: "code";
     text: string;
@@ -111,47 +115,98 @@ declare const removeLink: (nodes: Node[], sel: NodeSelection) => Result<Node[],
 
 type TransformResult = {
     block: AnyBlock;
+    /** true if the block type was actually changed, false if no trigger matched */
     converted: boolean;
 };
 /**
- * Call this when a space is typed.
+ * Attempt to convert a paragraph block into another type based on a
+ * Markdown-style prefix typed by the user.
+ *
+ * Call this when a **space** is typed inside a paragraph block.
+ *
+ * Supported triggers (must appear at position 0, immediately before the space):
+ *
+ * | Typed    | Converts to |
+ * |----------|-------------|
+ * | `-`      | bullet      |
+ * | `1.`     | number      |
+ * | `[]`     | todo        |
+ * | `#`      | heading1    |
+ * | `##`     | heading2    |
+ * | `###`    | heading3    |
  *
- * Guards (returns converted=false if any fail):
- *   1. block.type must be "paragraph"
- *   2. cursorOffset must be ≤ trigger.length + 1
- *      — ensures the space was typed right after the trigger at position 0
- *      — blocks mid-text spaces like "hello - " from converting
- *   3. text must start with a known trigger prefix
+ * Guards — returns `converted: false` without mutating if any fail:
+ *   1. `block.type` must be `"paragraph"`
+ *   2. The text must start with a known trigger prefix
+ *   3. `cursorOffset` must be ≥ `trigger.length + 1` — ensures the space
+ *      was typed right after the trigger (blocks mid-text triggers like
+ *      `"hello - "` from accidentally converting)
+ *
+ * On success the returned block has the trigger prefix stripped from its
+ * content and a freshly built `meta` for the target type.
  */
 declare function applyMarkdownTransform(block: AnyBlock, cursorOffset: number): Result<TransformResult>;
 /**
- * Convert a block to a new type while preserving content as much as possible.
+ * Convert a block to a new type, preserving content and meta where possible.
+ *
+ * Content conversion rules:
  *
- * rich → rich         keep content as-is, update type + meta
- * rich → code         strip all formatting, concat all text → [CodeNode]
- * rich → equation     strip all formatting, concat all text → [EquationNode]
- * code → rich         single TextNode with code.text
- * equation → rich     single TextNode with equation.latex
- * code → equation     [EquationNode] with code.text as latex
- * equation → code     [CodeNode] with equation.latex as text
+ * | From        | To          | Content result                         |
+ * |-------------|-------------|----------------------------------------|
+ * | rich        | rich        | kept as-is                             |
+ * | rich        | code        | all text concatenated → `[CodeNode]`   |
+ * | rich        | equation    | all text concatenated → `[EquationNode]`|
+ * | code        | rich        | `code.text` → single `TextNode`        |
+ * | equation    | rich        | `equation.latex` → single `TextNode`   |
+ * | code        | equation    | `code.text` as `latex`                 |
+ * | equation    | code        | `equation.latex` as `text`             |
+ *
+ * Meta conversion rules:
+ * - list → list  : `meta` (including `depth`) is preserved
+ * - anything else: fresh default `meta` is built for the target type
  */
 declare function changeBlockType<T extends BlockType>(block: AnyBlock, targetType: T): Result<Block<T>>;
 /**
  * Toggle the checked state of a todo block.
- * checked: undefined → checked: true → checked: undefined (cycle)
+ *
+ * Cycle: `undefined → true → undefined`
+ *
+ * Returns `Err` if the block is not of type `"todo"`.
  */
 declare function toggleTodo(block: AnyBlock): Result<Block<"todo">>;
 type IndentableBlock = Block<"bullet"> | Block<"number"> | Block<"todo">;
 /**
- * Increase the depth of a bullet, number, or todo block by 1.
- * Max depth is 6. Returns Err if block type is not indentable.
+ * Increase the indentation depth of a list block (`bullet`, `number`, `todo`) by 1.
+ *
+ * - Maximum depth is `6`.
+ * - Returns `Err` if the block type is not indentable or is already at max depth.
  */
 declare function indentBlock(block: AnyBlock): Result<IndentableBlock>;
 /**
- * Decrease the depth of a bullet, number, or todo block by 1.
- * Min depth is 0. Returns Err if block type is not indentable or already at 0.
+ * Decrease the indentation depth of a list block (`bullet`, `number`, `todo`) by 1.
+ *
+ * - Minimum depth is `0`.
+ * - Returns `Err` if the block type is not indentable or is already at depth 0.
  */
 declare function outdentBlock(block: AnyBlock): Result<IndentableBlock>;
+/**
+ * Deep-equality check between two block arrays.
+ *
+ * Two arrays are considered the same when:
+ *   - They have the same length
+ *   - Every block at the same index has the same `id`, `type`, `meta`, and `content`
+ *
+ * Content nodes are compared field-by-field. Unknown extra fields on nodes are
+ * ignored so the check stays stable across schema additions.
+ *
+ * Useful for preventing redundant saves or snapshot writes:
+ * ```ts
+ * if (!areBlocksSame(current, saved)) {
+ *   await createSnapshot(current);
+ * }
+ * ```
+ */
+declare function areBlocksSame(blocks: AnyBlock[], withBlocks: AnyBlock[]): boolean;
 
 /**
  * Serialize an array of blocks to a JSON string.
@@ -267,4 +322,4 @@ declare function duplicateBlockAfter(blocks: AnyBlock[], id: string, newId?: str
  */
 declare function moveBlock(blocks: AnyBlock[], id: string, direction: "up" | "down"): Result<AnyBlock[], string>;
 
-export { type AnyBlock, type Block, type BlockContent, type BlockMeta, type BlockType, type History, type HistoryEntry, type Node, type NodeSelection, applyMarkdownTransform, canRedo, canUndo, changeBlockType, createBlock, createBlockAfter, createHistory, currentBlocks, deleteBlock, deleteLastChar, deleteRange, deserialize, deserializeNodes, duplicateBlock, duplicateBlockAfter, formatNodes, generateId, indentBlock, insertAt, insertBlockAfter, mergeAdjacentNodes, mergeBlocks, moveBlock, outdentBlock, push, redo, removeLink, replaceRange, serialize, serializeNodes, setLink, splitBlock, toMarkdown, toPlainText, toggleBold, toggleColor, toggleHighlight, toggleItalic, toggleStrikethrough, toggleTodo, toggleUnderline, undo };
+export { type AnyBlock, type Block, type BlockContent, type BlockMeta, type BlockType, type History, type HistoryEntry, type Node, type NodeSelection, applyMarkdownTransform, areBlocksSame, canRedo, canUndo, changeBlockType, createBlock, createBlockAfter, createHistory, currentBlocks, deleteBlock, deleteLastChar, deleteRange, deserialize, deserializeNodes, duplicateBlock, duplicateBlockAfter, formatNodes, generateId, indentBlock, insertAt, insertBlockAfter, mergeAdjacentNodes, mergeBlocks, moveBlock, outdentBlock, push, redo, removeLink, replaceRange, serialize, serializeNodes, setLink, splitBlock, toMarkdown, toPlainText, toggleBold, toggleColor, toggleHighlight, toggleItalic, toggleStrikethrough, toggleTodo, toggleUnderline, undo };

package/dist/index.js

@@ -552,18 +552,15 @@ function buildMetaForTarget(targetType) {
     case "number":
     case "todo":
       return { depth: 0 };
-    case "heading1":
-    case "heading2":
-    case "heading3":
-    case "paragraph":
-    case "code":
-    case "equation":
+    default:
       return {};
   }
 }
+function isList(type) {
+  return type === "bullet" || type === "todo" || type === "number";
+}
 function deriveMeta(block, targetType) {
-  if (isList(block.type) && isList(targetType))
-    return block.meta;
+  if (isList(block.type) && isList(targetType)) return block.meta;
   return buildMetaForTarget(targetType);
 }
 function toggleTodo(block) {
@@ -578,9 +575,6 @@ var MAX_DEPTH = 6;
 function isIndentable(block) {
   return block.type === "bullet" || block.type === "number" || block.type === "todo";
 }
-function isList(type) {
-  return type === "bullet" || type === "todo" || type === "number";
-}
 function indentBlock(block) {
   if (!isIndentable(block))
     return Result4.Err(
@@ -604,6 +598,31 @@ function outdentBlock(block) {
     meta: { ...block.meta, depth: block.meta.depth - 1 }
   });
 }
+function areBlocksSame(blocks, withBlocks) {
+  if (blocks.length !== withBlocks.length) return false;
+  return blocks.every((a, i) => {
+    const b = withBlocks[i];
+    if (a.type !== b.type) return false;
+    if (JSON.stringify(a.meta) !== JSON.stringify(b.meta)) return false;
+    if (a.content.length !== b.content.length) return false;
+    return a.content.every((an, j) => {
+      const bn = b.content[j];
+      if (an.type !== bn.type) return false;
+      switch (an.type) {
+        case "code":
+          return an.text === bn.text;
+        case "equation":
+          return an.latex === bn.latex;
+        case "text": {
+          const bt = bn;
+          return an.text === bt.text && an.bold === bt.bold && an.italic === bt.italic && an.underline === bt.underline && an.strikethrough === bt.strikethrough && an.highlighted === bt.highlighted && an.color === bt.color && an.link === bt.link;
+        }
+        default:
+          return false;
+      }
+    });
+  });
+}
 
 // src/engine/serializer.ts
 import { Result as Result5 } from "@reiwuzen/result";
@@ -702,6 +721,7 @@ function nodesToMarkdown(nodes) {
   return nodes.map((n) => {
     if (n.type === "code") return `\`${n.text}\``;
     if (n.type === "equation") return `$${n.latex}$`;
+    if (n.type === "ref") return `[${n.label}](${n.href})`;
     let text = n.text;
     if (n.bold) text = `**${text}**`;
     if (n.italic) text = `*${text}*`;
@@ -789,6 +809,7 @@ var canRedo = (history) => history.future.length > 0;
 var currentBlocks = (history) => history.present.blocks;
 export {
   applyMarkdownTransform,
+  areBlocksSame,
   canRedo,
   canUndo,
   changeBlockType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reiwuzen/blocky",
-  "version": "1.3.4",
+  "version": "1.4.1",
   "description": "Pure TypeScript block editor engine. Headless, framework-agnostic — content mutation, formatting, transforms, serialization, and history.",
   "author": "Rei WuZen",
   "license": "ISC",