@scrider/formatter 1.2.0 → 1.3.0

package/README.md

@@ -8,7 +8,7 @@ Schema, conversion and block handlers for rich-text content. HTML, Markdown, san
 
 ## Key Features
 
-- **Schema** — extensible format registry (31 built-in formats: inline, block, embed)
+- **Schema** — extensible format registry (32 built-in formats: inline, block, embed — including `softBreak` for Shift+Enter line breaks)
 - **HTML conversion** — `deltaToHtml()` / `htmlToDelta()` with DOM adapters (browser + Node.js)
 - **Markdown conversion** — `deltaToMarkdown()` / `markdownToDelta()` (GFM, math, footnotes)
 - **Block handlers** — tables, footnotes, alerts, columns, inline-box
@@ -65,7 +65,7 @@ const delta = htmlToDelta(html, { registry });
 ```typescript
 import { Registry, createDefaultRegistry, BlockHandlerRegistry } from '@scrider/formatter';
 
-const registry = createDefaultRegistry();  // 31 built-in formats
+const registry = createDefaultRegistry();  // 32 built-in formats
 ```
 
 ### HTML Conversion
@@ -86,6 +86,35 @@ deltaToMarkdown(delta, options?)           // Delta → Markdown string
 await markdownToDelta(markdown, options?)  // Markdown string → Delta (async)
 ```
 
+### Soft Line Break (`softBreak` embed)
+
+A `Shift+Enter` style line break that does **not** split the containing block. Stored in Delta as `{ insert: { softBreak: true } }` and round-tripped consistently across all three layers:
+
+| Direction | Encoding |
+|-----------|----------|
+| HTML      | `<br data-scrider-embed>` (the marker disambiguates it from the `<br>` placeholder inside an empty paragraph) |
+| Markdown  | `"  \n"` by default — GFM hard break; switch to inline `<br>` via `deltaToMarkdown(delta, { softBreakStyle: 'html' })` |
+
+`htmlToDelta` also recognises bare `<br>` between content (e.g. `<p>foo<br>bar</p>`) as a soft break, while keeping the leading / placeholder shapes (`<p><br></p>`, `<p><br>foo</p>`) as regular newlines for backward compatibility.
+
+```typescript
+import { Delta, deltaToHtml, deltaToMarkdown } from '@scrider/formatter';
+
+const doc = new Delta()
+  .insert('hello')
+  .insert({ softBreak: true })
+  .insert('world\n');
+
+deltaToHtml(doc);
+// → '<p>hello<br data-scrider-embed>world</p>'
+
+deltaToMarkdown(doc);
+// → 'hello  \nworld'
+
+deltaToMarkdown(doc, { softBreakStyle: 'html' });
+// → 'hello<br>world'
+```
+
 ### Sanitization
 
 ```typescript

package/dist/index.cjs

@@ -96,6 +96,7 @@ __export(index_exports, {
   sizeFormat: () => sizeFormat,
   slugify: () => slugify,
   slugifyWithDedup: () => slugifyWithDedup,
+  softBreakFormat: () => softBreakFormat,
   strikeFormat: () => strikeFormat,
   subscriptFormat: () => subscriptFormat,
   superscriptFormat: () => superscriptFormat,
@@ -2020,7 +2021,13 @@ var EMBED_RENDERERS = {
     const id = typeof value === "string" ? value : String(value);
     return `<sup class="footnote-ref"><a href="#fn-${escapeHtml(id)}" id="fnref-${escapeHtml(id)}">[${escapeHtml(id)}]</a></sup>`;
   },
-  divider: () => "<hr>"
+  divider: () => "<hr>",
+  // Soft line break (Shift+Enter equivalent). Emitted with an explicit
+  // `data-scrider-embed` marker so that html-to-delta can distinguish this
+  // embed from the placeholder `<br>` that appears inside an empty
+  // paragraph (`<p><br></p>`) without relying solely on positional
+  // heuristics. See `soft-break.ts` for the format definition.
+  softBreak: () => "<br data-scrider-embed>"
 };
 var TAG_TO_INLINE_FORMAT = {
   strong: { format: "bold", value: true },
@@ -2258,6 +2265,33 @@ var imageFormat = {
   }
 };
 
+// src/schema/formats/embed/soft-break.ts
+var softBreakFormat = {
+  name: "softBreak",
+  scope: "embed",
+  normalize(value) {
+    return !!value;
+  },
+  validate(value) {
+    return value === true;
+  },
+  render() {
+    return "<br data-scrider-embed>";
+  },
+  match(element) {
+    if (element.tagName.toLowerCase() !== "br") return null;
+    if (!element.hasAttribute("data-scrider-embed")) return null;
+    return { value: true };
+  }
+  // NB: Markdown rendering is intentionally NOT implemented on the format
+  // itself. The choice between `"  \n"` (GFM spaces) and inline `<br>`
+  // depends on the caller-provided `softBreakStyle` option on
+  // `deltaToMarkdown`, so the converter handles it as a built-in special
+  // case instead of going through `Format.toMarkdown`. The Markdown side
+  // of the round-trip is symmetric: `markdownToDelta` recognises both
+  // `break` AST nodes and inline `<br>` HTML and emits this embed.
+};
+
 // src/schema/formats/embed/video.ts
 var videoFormat = {
   name: "video",
@@ -2360,6 +2394,7 @@ var defaultEmbedFormats = [
   videoFormat,
   formulaFormat,
   dividerFormat,
+  softBreakFormat,
   blockFormat,
   footnoteRefFormat
 ];
@@ -3190,7 +3225,12 @@ function htmlToDelta(html, options = {}) {
       return;
     }
     if (tagName === "br") {
-      context.pushNewline();
+      const hasMarker = node.hasAttribute("data-scrider-embed");
+      if (hasMarker || hasMeaningfulPrevSibling(node)) {
+        context.pushEmbed({ softBreak: true });
+      } else {
+        context.pushNewline();
+      }
       return;
     }
     processChildren(node);
@@ -3624,6 +3664,23 @@ function normalizeText(text, pendingText, atLineStart) {
   }
   return text;
 }
+function hasMeaningfulPrevSibling(brNode) {
+  const parent = brNode.parentNode;
+  if (!parent) return false;
+  const children = parent.childNodes;
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    if (!child) continue;
+    if (child === brNode) return false;
+    if (child.nodeType === NODE_TYPE.TEXT_NODE) {
+      const text = child.textContent ?? "";
+      if (text.trim().length > 0) return true;
+    } else if (isElement(child)) {
+      return true;
+    }
+  }
+  return false;
+}
 function findTagHandler(handlers, element, tagName) {
   const className = element.getAttribute("class");
   if (className) {
@@ -3760,6 +3817,7 @@ function deltaToMarkdown(delta, options = {}) {
     blockHandlers,
     prettyHtml = false,
     registry,
+    softBreakStyle = "spaces",
     trimTrailingNewlines = false
   } = options;
   const useLatexDelimiters = mathSyntax === "latex";
@@ -3776,7 +3834,9 @@ function deltaToMarkdown(delta, options = {}) {
     const isBlockquote = !!attrs.blockquote;
     if (typeof attrs["table-row"] === "number" && typeof attrs["table-col"] === "number") {
       const tableLines = collectTableLines2(lines, i);
-      result.push(renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters, registry));
+      result.push(
+        renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters, registry, softBreakStyle)
+      );
       result.push("");
       i += tableLines.length - 1;
       lastListType = null;
@@ -3792,7 +3852,16 @@ function deltaToMarkdown(delta, options = {}) {
       const codeLines = collectCodeBlock(lines, i);
       const language = getCodeBlockLanguage2(attrs);
       const code = codeLines.map(
-        (l) => renderLineContent2(l.ops, embedRenderers, true, false, blockHandlers, false, registry)
+        (l) => renderLineContent2(
+          l.ops,
+          embedRenderers,
+          true,
+          false,
+          blockHandlers,
+          false,
+          registry,
+          softBreakStyle
+        )
       ).join("\n");
       if (language === "math") {
         if (mathBlock === false) {
@@ -3842,7 +3911,8 @@ ${code}
       useLatexDelimiters,
       blockHandlers,
       prettyHtml,
-      registry
+      registry,
+      softBreakStyle
     );
     if (!content && !hasBlockFormat(attrs)) {
       result.push(preserveEmptyLines ? "<br>" : "");
@@ -3944,7 +4014,7 @@ function collectTableLines2(lines, startIndex) {
   }
   return result;
 }
-function renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters = false, registry) {
+function renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters = false, registry, softBreakStyle = "spaces") {
   const rows = /* @__PURE__ */ new Map();
   for (const line of tableLines) {
     const attrs = line.attributes;
@@ -3981,7 +4051,9 @@ function renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters = fa
   const mdLines = [];
   if (headerRows.length > 0) {
     for (const [, row] of headerRows) {
-      mdLines.push(renderMdRow(row.cells, maxCol, embedRenderers, useLatexDelimiters, registry));
+      mdLines.push(
+        renderMdRow(row.cells, maxCol, embedRenderers, useLatexDelimiters, registry, softBreakStyle)
+      );
     }
     mdLines.push(renderMdSeparator(maxCol, colAligns));
   } else {
@@ -3989,15 +4061,19 @@ function renderMarkdownTable(tableLines, embedRenderers, useLatexDelimiters = fa
     for (let col = 0; col <= maxCol; col++) {
       emptyRow.set(col, { ops: [] });
     }
-    mdLines.push(renderMdRow(emptyRow, maxCol, embedRenderers, useLatexDelimiters, registry));
+    mdLines.push(
+      renderMdRow(emptyRow, maxCol, embedRenderers, useLatexDelimiters, registry, softBreakStyle)
+    );
     mdLines.push(renderMdSeparator(maxCol, colAligns));
   }
   for (const [, row] of bodyRows) {
-    mdLines.push(renderMdRow(row.cells, maxCol, embedRenderers, useLatexDelimiters, registry));
+    mdLines.push(
+      renderMdRow(row.cells, maxCol, embedRenderers, useLatexDelimiters, registry, softBreakStyle)
+    );
   }
   return mdLines.join("\n");
 }
-function renderMdRow(cells, maxCol, embedRenderers, useLatexDelimiters = false, registry) {
+function renderMdRow(cells, maxCol, embedRenderers, useLatexDelimiters = false, registry, softBreakStyle = "spaces") {
   const parts = [];
   for (let col = 0; col <= maxCol; col++) {
     const cell = cells.get(col);
@@ -4008,7 +4084,10 @@ function renderMdRow(cells, maxCol, embedRenderers, useLatexDelimiters = false,
       useLatexDelimiters,
       void 0,
       false,
-      registry
+      registry,
+      softBreakStyle,
+      true
+      // inTableCell — softBreak must use <br>, never "  \n"
     ) : "";
     parts.push(content.replace(/\|/g, "\\|"));
   }
@@ -4037,7 +4116,7 @@ function getCodeBlockLanguage2(attributes) {
   }
   return void 0;
 }
-function renderLineContent2(ops, embedRenderers, inCodeBlock, useLatexDelimiters = false, blockHandlers, prettyHtml = false, registry) {
+function renderLineContent2(ops, embedRenderers, inCodeBlock, useLatexDelimiters = false, blockHandlers, prettyHtml = false, registry, softBreakStyle = "spaces", inTableCell = false) {
   let result = "";
   for (const op of ops) {
     const attrs = op.attributes;
@@ -4057,7 +4136,9 @@ function renderLineContent2(ops, embedRenderers, inCodeBlock, useLatexDelimiters
         useLatexDelimiters,
         blockHandlers,
         prettyHtml,
-        registry
+        registry,
+        softBreakStyle,
+        inTableCell
       );
     }
   }
@@ -4091,13 +4172,17 @@ function renderInlineText2(text, attributes) {
   }
   return result;
 }
-function renderEmbed2(embed, attributes, customRenderers, useLatexDelimiters = false, blockHandlers, prettyHtml = false, registry) {
+function renderEmbed2(embed, attributes, customRenderers, useLatexDelimiters = false, blockHandlers, prettyHtml = false, registry, softBreakStyle = "spaces", inTableCell = false) {
   const entries = Object.entries(embed);
   if (entries.length === 0) return "";
   const firstEntry = entries[0];
   if (!firstEntry) return "";
   const embedType = firstEntry[0];
   const embedValue = firstEntry[1];
+  if (embedType === "softBreak") {
+    if (inTableCell) return "<br>";
+    return softBreakStyle === "html" ? "<br>" : "  \n";
+  }
   if (embedType === "block" && blockHandlers) {
     const blockData = embedValue;
     if (blockData && typeof blockData.type === "string") {
@@ -4586,7 +4671,7 @@ function astToDelta(tree, customHandlers, mathBlock, mermaidBlock, plantumlBlock
         footnoteDefinitions.set(node.identifier ?? "", node);
         break;
       case "break":
-        context.pushNewline();
+        context.pushEmbed({ softBreak: true });
         break;
       case "html": {
         const htmlContent = node.value ?? "";
@@ -4892,8 +4977,8 @@ function astToDelta(tree, customHandlers, mathBlock, mermaidBlock, plantumlBlock
       context.pushNewline();
       return;
     }
-    if (/^<br\s*\/?>$/i.test(html)) {
-      context.pushNewline();
+    if (/^<br\b[^>]*\/?>$/i.test(html)) {
+      context.pushEmbed({ softBreak: true });
       return;
     }
   }
@@ -5044,6 +5129,7 @@ function extractTableRegion(ops, hintOpIdx) {
   sizeFormat,
   slugify,
   slugifyWithDedup,
+  softBreakFormat,
   strikeFormat,
   subscriptFormat,
   superscriptFormat,