@input/pen-markdown 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Input B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# `@input/pen-markdown`
+
+`@input/pen-markdown` is not a package to install alone. Install `@input/pen-interop` and import `markdownExporter` from `@input/pen-interop/markdown`, which is the host-facing markdown exporter and runs URL admission on the serialized output.
+
+This package owns the shared markdown serializer used by that exporter and by a few other Pen packages. It does not create an editor, apply ops, or admit URLs.
+
+## Install
+
+This package has no peer dependencies. Hosts should install `@input/pen-interop` instead of depending on this package directly.
+
+```bash
+pnpm add @input/pen @input/pen-markdown
+```
+
+`engines.node` is `>=22`.
+
+## Usage
+
+```ts
+import { createEditor } from "@input/pen";
+import { exportMarkdownForBlocks } from "@input/pen-markdown";
+
+const editor = createEditor();
+const markdown = exportMarkdownForBlocks(
+  editor,
+  editor.documentState.allBlocks(),
+);
+```
+
+`exportMarkdownRange(editor, range)` serializes a start/end block-id span. Omit `range`, or pass a range with no ids, to serialize every block. Hosts that need the admitted URL form should call `markdownExporter` from `@input/pen-interop/markdown` instead.
+
+## Options
+
+| Option     | Default | Effect                                     |
+| ---------- | ------- | ------------------------------------------ |
+| `viewMode` | `"raw"` | `"resolved"` drops delete-suggestion spans |
+
+`MarkdownExportRange.startBlockId` and `endBlockId` default to the first and last block when omitted.
+
+## Documentation
+
+The docs site (the `@input/pen-docs` package) covers this area on the Import and export page (`#/import-export`).
+
+The public signatures of record are in `api-report.md` next to this package's source in the Pen repository. The docs site does not host a generated browsable reference.
+
+## License
+
+MIT © Input B.V. See [`LICENSE.md`](./LICENSE.md).

package/dist/index.cjs

@@ -0,0 +1,247 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  exportMarkdownForBlocks: () => exportMarkdownForBlocks,
+  exportMarkdownRange: () => exportMarkdownRange
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/markdownSerialization.ts
+var import_pen_core = require("@input/pen-core");
+
+// src/listGrouper.ts
+function groupListItems(lines) {
+  const result = [];
+  let index = 0;
+  while (index < lines.length) {
+    const line = lines[index];
+    if (isListLine(line)) {
+      const group = [line];
+      index++;
+      while (index < lines.length && isListLine(lines[index])) {
+        group.push(lines[index]);
+        index++;
+      }
+      result.push(group.join("\n"));
+      continue;
+    }
+    result.push(line);
+    index++;
+  }
+  return result;
+}
+var LIST_PREFIX = /^\s*(?:[-*+]|\d+\.)\s/;
+function isListLine(line) {
+  return LIST_PREFIX.test(line);
+}
+
+// src/markdownSerialization.ts
+var DELETE_SUGGESTION_ACTION = "delete";
+function exportMarkdownRange(editor, range, config) {
+  return exportMarkdownForBlocks(editor, resolveBlockRange(editor, range), config);
+}
+function exportMarkdownForBlocks(editor, handles, config) {
+  const viewMode = config?.viewMode ?? "raw";
+  const lines = [];
+  for (const handle of handles) {
+    lines.push(serializeBlockHandleToMarkdown(handle, editor, viewMode));
+  }
+  return groupListItems(lines).join("\n\n");
+}
+function resolveBlockRange(editor, range) {
+  const blocks = listAllBlockHandles(editor);
+  const startBlockId = range?.startBlockId ?? null;
+  const endBlockId = range?.endBlockId ?? null;
+  if (!startBlockId && !endBlockId) {
+    return blocks;
+  }
+  const startIndex = startBlockId ? blocks.findIndex((block) => block.id === startBlockId) : 0;
+  const endIndex = endBlockId ? blocks.findIndex((block) => block.id === endBlockId) : blocks.length - 1;
+  if (startIndex === -1 || endIndex === -1) {
+    return blocks;
+  }
+  const rangeStart = Math.min(startIndex, endIndex);
+  const rangeEnd = Math.max(startIndex, endIndex) + 1;
+  return blocks.slice(rangeStart, rangeEnd);
+}
+function serializeBlockHandleToMarkdown(handle, editor, viewMode) {
+  const schema = editor.schema.resolve(handle.type);
+  if (!schema?.serialize?.toMarkdown) {
+    return readResolvedText(handle, viewMode);
+  }
+  const props = handle.type === "numberedListItem" ? {
+    ...handle.props,
+    start: (0, import_pen_core.getNumberedListItemValue)(handle) ?? 1
+  } : handle.props;
+  if (handle.type === "table") {
+    return renderTableMarkdown(handle, editor, viewMode);
+  }
+  const block = {
+    id: handle.id,
+    type: handle.type,
+    props,
+    content: serializeInlineContent(handle, editor, viewMode),
+    children: (0, import_pen_core.buildTableChildren)(handle)
+  };
+  return schema.serialize.toMarkdown(block);
+}
+function serializeInlineContent(handle, editor, viewMode) {
+  const deltas = handle.textDeltas();
+  if (!deltas || deltas.length === 0) {
+    return readResolvedText(handle, viewMode);
+  }
+  const stored = deltas.map((delta) => typeof delta.insert === "string" ? delta.insert : "").join("");
+  if (stored === "") {
+    return "";
+  }
+  let result = "";
+  for (const delta of deltas) {
+    let text = typeof delta.insert === "string" ? delta.insert : "";
+    if (!text) continue;
+    const suggestion = delta.attributes?.suggestion;
+    if (viewMode === "resolved" && suggestion?.action === DELETE_SUGGESTION_ACTION) {
+      continue;
+    }
+    if (delta.attributes) {
+      const ordered = (0, import_pen_core.sortDeltaAttributes)(delta.attributes, editor.schema);
+      for (const [mark, props] of Object.entries(ordered)) {
+        const inlineSchema = editor.schema.resolveInline(mark);
+        if (!inlineSchema?.serialize?.toMarkdown) continue;
+        text = inlineSchema.serialize.toMarkdown(
+          text,
+          typeof props === "object" ? props : {}
+        );
+      }
+    }
+    result += text;
+  }
+  return result;
+}
+function renderTableMarkdown(handle, editor, viewMode) {
+  const rows = readTableRows(
+    handle,
+    (cell) => serializeTableCellMarkdown(cell, editor, viewMode)
+  );
+  if (rows.length === 0) {
+    return "";
+  }
+  const hasHeaderRow = handle.props.hasHeaderRow !== false;
+  if (!hasHeaderRow) {
+    return renderHtmlTableFallback(rows);
+  }
+  const colCount = Math.max(...rows.map((row) => row.length), 1);
+  const lines = [];
+  const headerRow = rows[0] ?? [];
+  const headerCells = Array.from(
+    { length: colCount },
+    (_, index) => escapeMarkdownPipe(headerRow[index] ?? "")
+  );
+  lines.push(`| ${headerCells.join(" | ")} |`);
+  lines.push(`| ${Array.from({ length: colCount }, () => "---").join(" | ")} |`);
+  for (let rowIndex = 1; rowIndex < rows.length; rowIndex++) {
+    const rowCells = Array.from(
+      { length: colCount },
+      (_, index) => escapeMarkdownPipe(rows[rowIndex]?.[index] ?? "")
+    );
+    lines.push(`| ${rowCells.join(" | ")} |`);
+  }
+  return lines.join("\n");
+}
+function readTableRows(handle, serializeCell) {
+  const rows = [];
+  const table = handle.as("table");
+  const rowCount = table?.tableRowCount() ?? 0;
+  const colCount = table?.tableColumnCount() ?? 0;
+  for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+    const row = [];
+    for (let columnIndex = 0; columnIndex < colCount; columnIndex++) {
+      row.push(serializeCell(table?.tableCell(rowIndex, columnIndex) ?? null));
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+function serializeTableCellMarkdown(cell, editor, viewMode) {
+  if (!cell) {
+    return "";
+  }
+  const deltas = [...cell.textDeltas()];
+  const stored = deltas.map((delta) => delta.insert).join("");
+  if (stored === "") {
+    return "";
+  }
+  let result = "";
+  for (const delta of deltas) {
+    let text = delta.insert;
+    if (!text) {
+      continue;
+    }
+    const suggestion = delta.attributes?.suggestion;
+    if (viewMode === "resolved" && suggestion?.action === DELETE_SUGGESTION_ACTION) {
+      continue;
+    }
+    if (delta.attributes) {
+      const ordered = (0, import_pen_core.sortDeltaAttributes)(delta.attributes, editor.schema);
+      for (const [mark, props] of Object.entries(ordered)) {
+        const inlineSchema = editor.schema.resolveInline(mark);
+        if (!inlineSchema?.serialize?.toMarkdown) {
+          continue;
+        }
+        text = inlineSchema.serialize.toMarkdown(
+          text,
+          typeof props === "object" ? props : {}
+        );
+      }
+    }
+    result += text;
+  }
+  return result;
+}
+function renderHtmlTableFallback(rows) {
+  const parts = ["<table><tbody>"];
+  for (const row of rows) {
+    parts.push("<tr>");
+    for (const cell of row) {
+      parts.push(`<td>${escapeHTML(cell)}</td>`);
+    }
+    parts.push("</tr>");
+  }
+  parts.push("</tbody></table>");
+  return parts.join("");
+}
+function escapeMarkdownPipe(text) {
+  return text.replaceAll("\\", "\\\\").replaceAll("|", "\\|");
+}
+function escapeHTML(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function listAllBlockHandles(editor) {
+  return Array.from(editor.documentState.allBlocks());
+}
+function readResolvedText(handle, viewMode) {
+  return viewMode === "resolved" ? handle.textContent({ resolved: true }) : handle.textContent();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  exportMarkdownForBlocks,
+  exportMarkdownRange
+});

package/dist/index.d.cts

@@ -0,0 +1,14 @@
+import { Editor, BlockHandle } from '@input/pen-types';
+
+interface MarkdownExportRange {
+    startBlockId?: string | null;
+    endBlockId?: string | null;
+}
+type MarkdownExportViewMode = "resolved" | "raw";
+interface MarkdownExportConfig {
+    viewMode?: MarkdownExportViewMode;
+}
+declare function exportMarkdownRange(editor: Editor, range?: MarkdownExportRange | null, config?: MarkdownExportConfig): string;
+declare function exportMarkdownForBlocks(editor: Editor, handles: Iterable<BlockHandle>, config?: MarkdownExportConfig): string;
+
+export { type MarkdownExportConfig, type MarkdownExportRange, type MarkdownExportViewMode, exportMarkdownForBlocks, exportMarkdownRange };

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { Editor, BlockHandle } from '@input/pen-types';
+
+interface MarkdownExportRange {
+    startBlockId?: string | null;
+    endBlockId?: string | null;
+}
+type MarkdownExportViewMode = "resolved" | "raw";
+interface MarkdownExportConfig {
+    viewMode?: MarkdownExportViewMode;
+}
+declare function exportMarkdownRange(editor: Editor, range?: MarkdownExportRange | null, config?: MarkdownExportConfig): string;
+declare function exportMarkdownForBlocks(editor: Editor, handles: Iterable<BlockHandle>, config?: MarkdownExportConfig): string;
+
+export { type MarkdownExportConfig, type MarkdownExportRange, type MarkdownExportViewMode, exportMarkdownForBlocks, exportMarkdownRange };

package/dist/index.mjs

@@ -0,0 +1,223 @@
+// src/markdownSerialization.ts
+import {
+  buildTableChildren,
+  getNumberedListItemValue,
+  sortDeltaAttributes
+} from "@input/pen-core";
+
+// src/listGrouper.ts
+function groupListItems(lines) {
+  const result = [];
+  let index = 0;
+  while (index < lines.length) {
+    const line = lines[index];
+    if (isListLine(line)) {
+      const group = [line];
+      index++;
+      while (index < lines.length && isListLine(lines[index])) {
+        group.push(lines[index]);
+        index++;
+      }
+      result.push(group.join("\n"));
+      continue;
+    }
+    result.push(line);
+    index++;
+  }
+  return result;
+}
+var LIST_PREFIX = /^\s*(?:[-*+]|\d+\.)\s/;
+function isListLine(line) {
+  return LIST_PREFIX.test(line);
+}
+
+// src/markdownSerialization.ts
+var DELETE_SUGGESTION_ACTION = "delete";
+function exportMarkdownRange(editor, range, config) {
+  return exportMarkdownForBlocks(editor, resolveBlockRange(editor, range), config);
+}
+function exportMarkdownForBlocks(editor, handles, config) {
+  const viewMode = config?.viewMode ?? "raw";
+  const lines = [];
+  for (const handle of handles) {
+    lines.push(serializeBlockHandleToMarkdown(handle, editor, viewMode));
+  }
+  return groupListItems(lines).join("\n\n");
+}
+function resolveBlockRange(editor, range) {
+  const blocks = listAllBlockHandles(editor);
+  const startBlockId = range?.startBlockId ?? null;
+  const endBlockId = range?.endBlockId ?? null;
+  if (!startBlockId && !endBlockId) {
+    return blocks;
+  }
+  const startIndex = startBlockId ? blocks.findIndex((block) => block.id === startBlockId) : 0;
+  const endIndex = endBlockId ? blocks.findIndex((block) => block.id === endBlockId) : blocks.length - 1;
+  if (startIndex === -1 || endIndex === -1) {
+    return blocks;
+  }
+  const rangeStart = Math.min(startIndex, endIndex);
+  const rangeEnd = Math.max(startIndex, endIndex) + 1;
+  return blocks.slice(rangeStart, rangeEnd);
+}
+function serializeBlockHandleToMarkdown(handle, editor, viewMode) {
+  const schema = editor.schema.resolve(handle.type);
+  if (!schema?.serialize?.toMarkdown) {
+    return readResolvedText(handle, viewMode);
+  }
+  const props = handle.type === "numberedListItem" ? {
+    ...handle.props,
+    start: getNumberedListItemValue(handle) ?? 1
+  } : handle.props;
+  if (handle.type === "table") {
+    return renderTableMarkdown(handle, editor, viewMode);
+  }
+  const block = {
+    id: handle.id,
+    type: handle.type,
+    props,
+    content: serializeInlineContent(handle, editor, viewMode),
+    children: buildTableChildren(handle)
+  };
+  return schema.serialize.toMarkdown(block);
+}
+function serializeInlineContent(handle, editor, viewMode) {
+  const deltas = handle.textDeltas();
+  if (!deltas || deltas.length === 0) {
+    return readResolvedText(handle, viewMode);
+  }
+  const stored = deltas.map((delta) => typeof delta.insert === "string" ? delta.insert : "").join("");
+  if (stored === "") {
+    return "";
+  }
+  let result = "";
+  for (const delta of deltas) {
+    let text = typeof delta.insert === "string" ? delta.insert : "";
+    if (!text) continue;
+    const suggestion = delta.attributes?.suggestion;
+    if (viewMode === "resolved" && suggestion?.action === DELETE_SUGGESTION_ACTION) {
+      continue;
+    }
+    if (delta.attributes) {
+      const ordered = sortDeltaAttributes(delta.attributes, editor.schema);
+      for (const [mark, props] of Object.entries(ordered)) {
+        const inlineSchema = editor.schema.resolveInline(mark);
+        if (!inlineSchema?.serialize?.toMarkdown) continue;
+        text = inlineSchema.serialize.toMarkdown(
+          text,
+          typeof props === "object" ? props : {}
+        );
+      }
+    }
+    result += text;
+  }
+  return result;
+}
+function renderTableMarkdown(handle, editor, viewMode) {
+  const rows = readTableRows(
+    handle,
+    (cell) => serializeTableCellMarkdown(cell, editor, viewMode)
+  );
+  if (rows.length === 0) {
+    return "";
+  }
+  const hasHeaderRow = handle.props.hasHeaderRow !== false;
+  if (!hasHeaderRow) {
+    return renderHtmlTableFallback(rows);
+  }
+  const colCount = Math.max(...rows.map((row) => row.length), 1);
+  const lines = [];
+  const headerRow = rows[0] ?? [];
+  const headerCells = Array.from(
+    { length: colCount },
+    (_, index) => escapeMarkdownPipe(headerRow[index] ?? "")
+  );
+  lines.push(`| ${headerCells.join(" | ")} |`);
+  lines.push(`| ${Array.from({ length: colCount }, () => "---").join(" | ")} |`);
+  for (let rowIndex = 1; rowIndex < rows.length; rowIndex++) {
+    const rowCells = Array.from(
+      { length: colCount },
+      (_, index) => escapeMarkdownPipe(rows[rowIndex]?.[index] ?? "")
+    );
+    lines.push(`| ${rowCells.join(" | ")} |`);
+  }
+  return lines.join("\n");
+}
+function readTableRows(handle, serializeCell) {
+  const rows = [];
+  const table = handle.as("table");
+  const rowCount = table?.tableRowCount() ?? 0;
+  const colCount = table?.tableColumnCount() ?? 0;
+  for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+    const row = [];
+    for (let columnIndex = 0; columnIndex < colCount; columnIndex++) {
+      row.push(serializeCell(table?.tableCell(rowIndex, columnIndex) ?? null));
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+function serializeTableCellMarkdown(cell, editor, viewMode) {
+  if (!cell) {
+    return "";
+  }
+  const deltas = [...cell.textDeltas()];
+  const stored = deltas.map((delta) => delta.insert).join("");
+  if (stored === "") {
+    return "";
+  }
+  let result = "";
+  for (const delta of deltas) {
+    let text = delta.insert;
+    if (!text) {
+      continue;
+    }
+    const suggestion = delta.attributes?.suggestion;
+    if (viewMode === "resolved" && suggestion?.action === DELETE_SUGGESTION_ACTION) {
+      continue;
+    }
+    if (delta.attributes) {
+      const ordered = sortDeltaAttributes(delta.attributes, editor.schema);
+      for (const [mark, props] of Object.entries(ordered)) {
+        const inlineSchema = editor.schema.resolveInline(mark);
+        if (!inlineSchema?.serialize?.toMarkdown) {
+          continue;
+        }
+        text = inlineSchema.serialize.toMarkdown(
+          text,
+          typeof props === "object" ? props : {}
+        );
+      }
+    }
+    result += text;
+  }
+  return result;
+}
+function renderHtmlTableFallback(rows) {
+  const parts = ["<table><tbody>"];
+  for (const row of rows) {
+    parts.push("<tr>");
+    for (const cell of row) {
+      parts.push(`<td>${escapeHTML(cell)}</td>`);
+    }
+    parts.push("</tr>");
+  }
+  parts.push("</tbody></table>");
+  return parts.join("");
+}
+function escapeMarkdownPipe(text) {
+  return text.replaceAll("\\", "\\\\").replaceAll("|", "\\|");
+}
+function escapeHTML(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function listAllBlockHandles(editor) {
+  return Array.from(editor.documentState.allBlocks());
+}
+function readResolvedText(handle, viewMode) {
+  return viewMode === "resolved" ? handle.textContent({ resolved: true }) : handle.textContent();
+}
+export {
+  exportMarkdownForBlocks,
+  exportMarkdownRange
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@input/pen-markdown",
+  "version": "0.1.0",
+  "description": "Shared markdown serialization helpers for Pen",
+  "license": "MIT",
+  "homepage": "https://github.com/input-systems/pen#readme",
+  "bugs": {
+    "url": "https://github.com/input-systems/pen/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/input-systems/pen.git",
+    "directory": "packages/shared/markdown"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@input/pen-types": "^0.1.0",
+    "@input/pen-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.7"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}