@uniweb/content-writer 0.2.7 → 0.2.8

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@uniweb/content-writer",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "ProseMirror document structure to Markdown converter",
   "type": "module",
   "main": "src/index.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./entities": "./src/entities.js"
   },
   "keywords": [
     "markdown",
@@ -19,7 +20,7 @@
   },
   "devDependencies": {
     "vitest": "^4.1.7",
-    "@uniweb/content-reader": "1.1.14"
+    "@uniweb/content-reader": "1.1.16"
   },
   "directories": {
     "test": "tests"

package/src/entities.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Undo the HTML escaping that ProseMirror text nodes carry.
+ *
+ * Text in a PM node is HTML, because the render path injects it as HTML
+ * (`kit`'s `SafeHtml` / `Text` use `dangerouslySetInnerHTML`). A literal `<`
+ * the author typed inside a code span therefore has to be *stored* escaped —
+ * `<code><x></code>` would have the browser swallow `<x>` as an unknown tag.
+ *
+ * `content-reader` encodes that asymmetry deliberately: it decodes `&amp;`,
+ * `&quot;` and `&#39;` back to plain characters and leaves `&lt;` / `&gt;`
+ * escaped. Verified against the parser (`parser/inline.js`) — raw HTML an
+ * author writes in prose is preserved verbatim through the `html` token, so
+ * only *machine-escaped* text carries entities on the way out.
+ *
+ * Two exports, because "leaving HTML-land" means different things depending
+ * on where the text is going:
+ *
+ * - `decodeMarkupEntities` — the markdown lane. Undoes only the pair the
+ *   reader left behind, so serializing is the reader's exact inverse.
+ * - `decodeTextEntities` — the plain-text lane. The target is not HTML at
+ *   all, so every entity resolves to the character a reader would see.
+ */
+
+/**
+ * Undo the escaping `content-reader` leaves in place (`&lt;` / `&gt;`).
+ *
+ * Deliberately narrow. `&amp;`, `&quot;` and `&#39;` are already decoded by
+ * the reader, so a PM node holding one of those means the author wrote the
+ * entity themselves — decoding it again would corrupt their source.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function decodeMarkupEntities(text) {
+  if (!text || !text.includes('&')) return text
+  return text.replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+}
+
+/**
+ * Escape a code span's text for storage in a ProseMirror text node.
+ *
+ * The exact inverse of {@link decodeMarkupEntities}, and the other half of the
+ * invariant: a code span's content is rendered by injecting it as HTML, so a
+ * literal `<` has to be stored escaped or `<code><x></code>` has the browser
+ * swallow `<x>` and the span renders empty.
+ *
+ * Exported for **producers other than content-reader**. Any tool that writes a
+ * ProseMirror code span — an editor, a converter — needs this rule, and the
+ * rule living in prose rather than in code is what let two producers diverge.
+ * Import it instead of reimplementing it.
+ *
+ * Only `<` and `>`: every other character is safe inside an HTML text node,
+ * and escaping `&` here would double-encode an entity the author typed.
+ *
+ * @param {string} text - Raw code span content, as the author typed it
+ * @returns {string} Text safe to store in a PM code-marked node
+ */
+export function encodeMarkupEntities(text) {
+  if (!text) return text
+  return text.replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+/**
+ * Resolve every entity to the character a reader would actually see.
+ *
+ * `&amp;` is decoded **last** so `&amp;lt;` yields `&lt;` rather than `<` —
+ * one decoding pass, not a cascade.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function decodeTextEntities(text) {
+  if (!text || !text.includes('&')) return text
+  return text
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#0*39;/g, "'")
+    .replace(/&apos;/g, "'")
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+}
+
+/**
+ * Drop raw inline HTML an author wrote in prose (`<br>`, `<span …>`).
+ *
+ * Only for the plain-text lane. Runs **before** entity decoding, so text the
+ * author escaped on purpose (`&lt;b&gt;`, meaning a literal `<b>`) survives
+ * as characters instead of being mistaken for a tag and stripped.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripInlineHtml(text) {
+  if (!text || !text.includes('<')) return text
+  return text.replace(/<\/?[a-zA-Z][^>]*>/g, '')
+}
+
+/**
+ * The plain-text cleanup, in the order the two steps have to run.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function toPlainCharacters(text) {
+  return decodeTextEntities(stripInlineHtml(text))
+}

package/src/index.js

@@ -8,7 +8,8 @@
 export { serializeDoc as proseMirrorToMarkdown } from './serializer.js'
 export { serializeInlineContent } from './marks.js'
 export { serializeFrontmatter } from './frontmatter.js'
-export { docToPlainText } from './plain-text.js'
+export { docToPlainText, docSummaryText } from './plain-text.js'
+export { encodeMarkupEntities, decodeMarkupEntities, decodeTextEntities } from './entities.js'
 export { normalizeDialect } from './normalize.js'
 export { setDiagnosticsReporter, resetDiagnostics } from './diagnostics.js'
 

package/src/marks.js

@@ -5,16 +5,17 @@
  */
 
 import { serializeAttributes } from './attributes.js'
+import { decodeMarkupEntities } from './entities.js'
 import { warnUnmappedMark, warnUnmappedNode } from './diagnostics.js'
 
 /**
  * Marks the markdown serializer can represent. Any other mark on an
  * inline node has its styling dropped (the text is still emitted) and is
  * reported by the no-silent-drop guard — e.g. editor-dialect `highlight`,
- * `textStyle` (colour), `strike`, `underline`, `uniqueID`, which need a
+ * `textStyle` (colour), `highlight`, `underline`, `uniqueID`, which need a
  * named-inline-style mapping decision.
  */
-const KNOWN_MARKS = new Set(['bold', 'italic', 'code', 'link', 'button', 'span'])
+const KNOWN_MARKS = new Set(['bold', 'italic', 'code', 'strike', 'link', 'button', 'span'])
 
 /** Report any inline mark we have no markdown form for (deduped per type). */
 function reportUnknownMarks(content) {
@@ -26,16 +27,6 @@ function reportUnknownMarks(content) {
   }
 }
 
-/**
- * Check if a node has a specific mark type.
- * @param {Object} node - ProseMirror inline node
- * @param {string} type - Mark type
- * @returns {Object|undefined} The mark object if found
- */
-function findMark(node, type) {
-  return node.marks?.find(m => m.type === type)
-}
-
 /**
  * Check if two marks are the same (same type and same attrs for link/button/span).
  */
@@ -115,15 +106,40 @@ export function serializeInsetRef(node) {
   return `${bang}[${label}](@${component})${attrStr}`
 }
 
+/**
+ * Icon library short codes, mirroring content-reader's `ICON_FAMILIES_SHORT`.
+ *
+ * The two spellings are not interchangeable on the way back in: the reader
+ * accepts `family:name` for ANY family but `family-name` only for a short
+ * code, deliberately, so a dash form stays unambiguous against an ordinary
+ * relative path. Emitting the dash form for a full family name produced
+ * `![](lucide-star)`, which reads back as a plain image with
+ * `src: "lucide-star"` — the icon destroyed, and stable in that state.
+ */
+const ICON_SHORT_CODES = new Set([
+  'lu', 'hi', 'hi2', 'pi', 'tb', 'fi', 'bs', 'md', 'ai',
+  'ri', 'si', 'io5', 'bi', 'vsc', 'wi', 'gi', 'fa', 'fa6',
+])
+
+/**
+ * Spell an icon reference so the reader parses it back as an icon.
+ * @param {string} library
+ * @param {string} name
+ * @returns {string}
+ */
+function iconRef(library, name) {
+  return ICON_SHORT_CODES.has(library) ? `${library}-${name}` : `${library}:${name}`
+}
+
 /**
  * Serialize an inline image node (icon within a paragraph).
  */
 function serializeInlineImage(node) {
   const { src, alt, caption, role, library, name, ...rest } = node.attrs || {}
 
-  // Icon with library+name → compact dash format
+  // Icon with library+name → dash for a short code, colon otherwise
   if (library && name) {
-    const iconSrc = `${library}-${name}`
+    const iconSrc = iconRef(library, name)
     const extraAttrs = { ...rest }
     // Remove icon-derived attrs from extra attrs
     delete extraAttrs.size
@@ -154,9 +170,9 @@ function serializeInlineImage(node) {
 export function serializeBlockImage(node) {
   const { src, alt, caption, role, library, name, ...rest } = node.attrs || {}
 
-  // Icon with library+name → compact dash format
+  // Icon with library+name → dash for a short code, colon otherwise
   if (library && name) {
-    const iconSrc = `${library}-${name}`
+    const iconSrc = iconRef(library, name)
     const extraAttrs = { ...rest }
     const attrStr = serializeAttributes(extraAttrs)
     const altPart = alt || ''
@@ -196,81 +212,115 @@ export function serializeInlineContent(content) {
   // No silent drops: flag any mark we can't represent before serializing.
   reportUnknownMarks(content)
 
-  // Pre-process: group nodes by wrapping marks (link, button, span)
-  const segments = groupByWrappingMarks(content)
-  return segments.map(seg => serializeSegment(seg)).join('')
+  return serializeRuns(content)
 }
 
 /**
- * Group consecutive nodes by shared wrapping marks (link, button, span).
- * Returns an array of segments, where each segment is either:
- * - { type: 'link'|'button'|'span', mark, nodes } — wrapped group
- * - { type: 'plain', nodes } — unwrapped nodes
+ * Serialize a run of inline nodes, honoring mark nesting.
+ *
+ * `node.marks` is **ordered, innermost first** — the reader records which mark
+ * the author wrapped around which. `**\`x\`**` gives `[code, bold]`;
+ * `[**x**](url)` gives `[bold, link]`; `**[x](url)**` gives `[link, bold]`.
+ * The semantic parser already reads that order (it renders
+ * `<strong><code>x</code></strong>`), and this serializer now does too.
+ *
+ * The algorithm is one rule applied recursively: take the OUTERMOST mark of
+ * the first node, absorb every following node that shares it, strip that one
+ * mark from the group, recurse, then wrap the result once.
+ *
+ * Absorbing the neighbours is what keeps a mark that spans several nodes from
+ * being re-emitted around each of them. `**Preview with \`pnpm dev\`.**` is
+ * three text nodes — `[bold]`, `[code, bold]`, `[bold]` — and wrapping each
+ * separately produced the invalid `**Preview with **\`pnpm dev\`**.**`.
+ *
+ * @param {Array} nodes - Inline nodes
+ * @returns {string} Markdown string
  */
-function groupByWrappingMarks(content) {
-  const segments = []
+function serializeRuns(nodes) {
+  const out = []
   let i = 0
 
-  while (i < content.length) {
-    const node = content[i]
-
-    // Check for wrapping marks: link, button, span
-    const linkMark = findMark(node, 'link')
-    const buttonMark = findMark(node, 'button')
-    const spanMark = findMark(node, 'span')
-    const wrappingMark = buttonMark || linkMark || spanMark
-
-    if (wrappingMark && node.type === 'text') {
-      // Collect consecutive nodes with the same wrapping mark
-      const group = [node]
-      let j = i + 1
-      while (j < content.length && content[j].type === 'text') {
-        const nextMark = findMark(content[j], wrappingMark.type)
-        if (nextMark && marksEqual(nextMark, wrappingMark)) {
-          group.push(content[j])
-          j++
-        } else {
-          break
-        }
-      }
-      segments.push({ type: wrappingMark.type, mark: wrappingMark, nodes: group })
-      i = j
-    } else {
-      // Plain node (no wrapping mark, or an image node)
-      segments.push({ type: 'plain', nodes: [node] })
+  while (i < nodes.length) {
+    const node = nodes[i]
+    const outer = node.type === 'text' ? outermostMark(node) : null
+
+    if (!outer) {
+      out.push(serializePlainNode(node))
       i++
+      continue
     }
+
+    // Absorb the consecutive text nodes wrapped by this same mark.
+    const group = []
+    let j = i
+    while (j < nodes.length && nodes[j].type === 'text') {
+      const candidate = outermostMark(nodes[j])
+      if (!candidate || !marksEqual(candidate, outer)) break
+      group.push(withoutOutermostMark(nodes[j]))
+      j++
+    }
+
+    out.push(applyMark(serializeRuns(group), outer))
+    i = j
   }
 
-  return segments
+  return out.join('')
 }
 
 /**
- * Serialize a segment (group of nodes with a common wrapping mark, or plain nodes).
+ * The mark an author wrapped outermost — the last entry, since marks are
+ * ordered innermost first.
+ *
+ * @param {Object} node
+ * @returns {Object|null}
  */
-function serializeSegment(segment) {
-  if (segment.type === 'plain') {
-    return segment.nodes.map(n => serializePlainNode(n)).join('')
-  }
+function outermostMark(node) {
+  const marks = node.marks || []
+  return marks.length ? marks[marks.length - 1] : null
+}
 
-  // Wrapped segment: serialize inner content (with the wrapping mark stripped)
-  const innerText = segment.nodes.map(node => {
-    // Strip the wrapping mark from this node's marks for inner serialization
-    const innerMarks = (node.marks || []).filter(m => !marksEqual(m, segment.mark))
-    return serializeTextWithMarks(node.text, innerMarks)
-  }).join('')
+/**
+ * The same node with its outermost mark peeled off.
+ * @param {Object} node
+ * @returns {Object}
+ */
+function withoutOutermostMark(node) {
+  return { ...node, marks: (node.marks || []).slice(0, -1) }
+}
 
-  if (segment.type === 'link') {
-    return `[${innerText}]${serializeLinkSuffix(segment.mark)}`
-  }
-  if (segment.type === 'button') {
-    return `[${innerText}]${serializeButtonSuffix(segment.mark)}`
-  }
-  if (segment.type === 'span') {
-    return `[${innerText}]${serializeSpanSuffix(segment.mark)}`
+/**
+ * Wrap already-serialized inner markdown in one mark.
+ *
+ * A mark with no markdown form leaves the text alone — the no-silent-drop
+ * guard has already reported it.
+ *
+ * @param {string} inner - Serialized inner content
+ * @param {Object} mark
+ * @returns {string}
+ */
+function applyMark(inner, mark) {
+  switch (mark.type) {
+    case 'code':
+      // Leaving HTML-land: a code span is the one place the reader leaves
+      // `&lt;`/`&gt;` escaped (see entities.js).
+      return serializeCodeSpan(decodeMarkupEntities(inner))
+    case 'bold':
+      return `**${inner}**`
+    case 'italic':
+      return `*${inner}*`
+    case 'strike':
+      // GFM. The editor's strike mark is author-reachable (input rule, paste
+      // rule, Mod-Shift-s) and had no markdown form, so it was dropped.
+      return `~~${inner}~~`
+    case 'link':
+      return `[${inner}]${serializeLinkSuffix(mark)}`
+    case 'button':
+      return `[${inner}]${serializeButtonSuffix(mark)}`
+    case 'span':
+      return `[${inner}]${serializeSpanSuffix(mark)}`
+    default:
+      return inner
   }
-
-  return innerText
 }
 
 /**
@@ -304,28 +354,40 @@ function serializePlainNode(node) {
 }
 
 /**
- * Serialize text with formatting marks (bold, italic, code).
+ * Wrap text in code-span backticks, picking a delimiter it can survive.
+ *
+ * A code span holding backticks needs a longer run to delimit it, and one
+ * that begins or ends with a backtick needs a padding space (the parser
+ * strips exactly one from each end). A single backtick emitted regardless
+ * mangles anything documenting markdown itself — `` ` ```math ` `` came back
+ * as ` ````math` `, which is a different, broken span.
+ *
+ * @param {string} text - Code span content
+ * @returns {string} The delimited span
  */
-function serializeTextWithMarks(text, marks) {
-  if (!marks || marks.length === 0) return text
+function serializeCodeSpan(text) {
+  const content = String(text)
+  const runs = (content.match(/`+/g) || []).map(run => run.length)
 
-  const hasCode = marks.some(m => m.type === 'code')
-  if (hasCode) {
-    return `\`${text}\``
-  }
+  // The shortest run length not already present, so the delimiter is
+  // unambiguous — CommonMark matches on equal-length runs.
+  let width = 1
+  while (runs.includes(width)) width++
+  const fence = '`'.repeat(width)
 
-  const hasBold = marks.some(m => m.type === 'bold')
-  const hasItalic = marks.some(m => m.type === 'italic')
+  // A leading or trailing backtick would fuse with the delimiter.
+  const pad = content.startsWith('`') || content.endsWith('`') ? ' ' : ''
 
-  if (hasBold && hasItalic) {
-    return `***${text}***`
-  }
-  if (hasBold) {
-    return `**${text}**`
-  }
-  if (hasItalic) {
-    return `*${text}*`
-  }
+  return `${fence}${pad}${content}${pad}${fence}`
+}
 
-  return text
+/**
+ * Serialize one text node's own marks, innermost first.
+ *
+ * Only reached for a lone node — `serializeRuns` handles anything that shares
+ * a mark with its neighbours.
+ */
+function serializeTextWithMarks(text, marks) {
+  if (!marks || marks.length === 0) return text
+  return marks.reduce((inner, mark) => applyMark(inner, mark), text)
 }