@uniweb/content-writer 0.2.6 → 0.2.8

package/tests/fixtures/roundtrip/defect-loose-list.md

@@ -0,0 +1,5 @@
+- one
+
+- two
+
+- three

package/tests/fixtures/roundtrip/fences.md

@@ -0,0 +1,9 @@
+# Fences
+
+````markdown
+```js
+const x = 1
+```
+````
+
+A ` ```math ` fence, and ` `` ` for nested spans.

package/tests/fixtures/roundtrip/list-blocks.md

@@ -0,0 +1,18 @@
+# Blocks inside list items
+
+- Use the hook:
+  ```jsx
+  const { data } = useEntityDetail(article)
+  ```
+- A quoted aside:
+  > Worth knowing.
+- A nested list:
+  - child
+  - sibling
+- Plain item
+
+1. Step one
+   ```sh
+   pnpm install
+   ```
+2. Step two

package/tests/fixtures/roundtrip/lists.md

@@ -0,0 +1,13 @@
+# Lists
+
+- one
+- two
+- three
+
+1. first
+2. second
+
+- parent
+  - child
+  - sibling
+- next

package/tests/fixtures/roundtrip/media.md

@@ -0,0 +1,7 @@
+# Media
+
+![](lu-house)
+
+![A network diagram](@NetworkDiagram){variant=compact}
+
+![Hero image](./hero.jpg)

package/tests/fixtures/roundtrip/prose.md

@@ -0,0 +1,12 @@
+# Working with Collections
+
+Collections let you manage repeating content as a set of files.
+
+## Declaring a collection
+
+Each collection is declared in `site.yml`, and every item compiles into
+`/data/<name>.json`. See the [collections guide](/docs/authoring/collections)
+for the full story.
+
+Text can be **bold**, *italic*, or ***both***. A literal &lt;name&gt; stays
+escaped in prose, and `a &amp; b` keeps its entity inside code.

package/tests/fixtures/roundtrip/structure.md

@@ -0,0 +1,16 @@
+# Structure
+
+> A quoted line.
+
+---
+
+A paragraph with math $x^2$ inline.
+
+$$E = mc^2$$
+
+```math
+\begin{aligned}
+a &= b + c \\
+d &= e + f
+\end{aligned}
+```

package/tests/fixtures/roundtrip/tables-escaped.md

@@ -0,0 +1,6 @@
+# Escaped pipes
+
+| Option | Values | Notes |
+| --- | --- | --- |
+| `mode` | `"a"` \| `"b"` \| `"c"` | A pipe inside a cell must stay escaped |
+| `flag` | `true` | Ordinary cell |

package/tests/fixtures/roundtrip/tables.md

@@ -0,0 +1,6 @@
+# Tables
+
+| Field | Meaning |
+| --- | --- |
+| `path` | A local file path |
+| `url` | A remote URL |

package/tests/marks.test.js

@@ -44,7 +44,12 @@ describe('Inline Content Serialization', () => {
         marks: [{ type: 'italic' }, { type: 'bold' }],
       },
     ]
-    expect(serializeInlineContent(content)).toBe('**bold *****then italic***')
+    // Bold spans both nodes and italic sits inside it, so bold is emitted once
+    // around the pair. This used to assert `**bold *****then italic***` — two
+    // bold spans butted together — which does not survive a reparse: the run
+    // of five asterisks reads back as the literal text `**bold **` with no
+    // marks at all, destroying the bold it was meant to carry.
+    expect(serializeInlineContent(content)).toBe('**bold *then italic***')
   })
 
   test('serializes inline code', () => {

package/tests/normalize.test.js

@@ -156,8 +156,12 @@ describe('no-silent-drop guard: unmappable nodes are reported, not lost', () =>
         })
       )
     )
-    expect(md).toBe('important') // text preserved, styling dropped
-    expect(warnings.some((m) => m.includes('highlight'))).toBe(true)
+    // `highlight` used to have no markdown form and was reported as an
+    // unmapped mark. It is now a named inline style — the editor stores a
+    // theme token rather than a colour — so it maps onto the span mark and
+    // nothing is dropped or reported.
+    expect(md).toBe('[important]{highlight}')
+    expect(warnings).toEqual([])
   })
 
   test('a known framework document produces no warnings', () => {
@@ -195,4 +199,126 @@ describe('no-silent-drop guard: unmappable nodes are reported, not lost', () =>
     expect(md).toBe('before  after')
     expect(warnings.some((m) => m.includes('FancyInlineWidget'))).toBe(true)
   })
+
+  test('a standalone "\\n" text node is a soft break, not a hard one', () => {
+    // content-reader emits a lone "\n" node for a SOFT break whenever the
+    // spans on both sides are marked. This used to be healed into a hard
+    // break, on the assumption it could only be the legacy spelling of one —
+    // which turned a wrapped line into a visible <br> one round trip later.
+    const md = proseMirrorToMarkdown(
+      doc(
+        para(
+          { type: 'text', text: 'line one' },
+          { type: 'text', text: '\n' },
+          { type: 'text', text: 'line two' }
+        )
+      )
+    )
+    expect(md.trim()).toBe('line one\nline two')
+    expect(warnings).toEqual([])
+  })
+
+  test('a hard break is the hardBreak node, and still serializes as one', () => {
+    const md = proseMirrorToMarkdown(
+      doc(para({ type: 'text', text: 'line one' }, { type: 'hardBreak' }, { type: 'text', text: 'line two' }))
+    )
+    expect(md.trim()).toBe('line one\\\nline two')
+  })
+
+  test('a newline INSIDE a text node is a soft break and must not be converted', () => {
+    // The narrow rule matters: this is an ordinary wrapped paragraph, which is
+    // a space. Converting it would inject a break into every wrapped paragraph.
+    const md = proseMirrorToMarkdown(
+      doc(para({ type: 'text', text: 'wrapped\nparagraph' }))
+    )
+    expect(md.trim()).toBe('wrapped\nparagraph')
+  })
+})
+
+describe('editor named inline styles map onto the span mark', () => {
+  let warnings
+
+  beforeEach(() => {
+    warnings = []
+    resetDiagnostics()
+    setDiagnosticsReporter(m => warnings.push(m))
+  })
+
+  const styled = marks => proseMirrorToMarkdown(doc(para({ type: 'text', text: 'x', marks }))).trim()
+
+  test('a textStyle token becomes a named inline style', () => {
+    // The editor's picker offers a closed set of theme tokens, not colours —
+    // the attribute is only *named* `color`. So they round-trip through the
+    // span mark the framework already has, and nothing is lost.
+    expect(styled([{ type: 'textStyle', attrs: { color: 'accent' } }])).toBe('[x]{accent}')
+    expect(styled([{ type: 'textStyle', attrs: { color: 'muted' } }])).toBe('[x]{muted}')
+    expect(styled([{ type: 'textStyle', attrs: { color: 'callout' } }])).toBe('[x]{callout}')
+  })
+
+  test('highlight is effectively boolean and maps the same way', () => {
+    expect(styled([{ type: 'highlight' }])).toBe('[x]{highlight}')
+  })
+
+  test('the "Normal" option carries no styling', () => {
+    expect(styled([{ type: 'textStyle', attrs: { color: '' } }])).toBe('x')
+    expect(warnings).toEqual([])
+  })
+
+  test('a raw colour is NOT mapped — it is reported, not written into markdown', () => {
+    // Reachable today via a paste carrying inline style; the editor is gating
+    // its parseHTML. A hex in markdown would contradict the theming model and
+    // would not survive a change of brand, so it must not be invented here.
+    expect(styled([{ type: 'textStyle', attrs: { color: '#ff0000' } }])).toBe('x')
+    expect(warnings.some(m => m.includes('textStyle'))).toBe(true)
+  })
+
+  test('a mapped style round-trips back through the reader', () => {
+    expect(styled([{ type: 'textStyle', attrs: { color: 'accent' } }])).toBe('[x]{accent}')
+  })
+})
+
+describe('editor icons and emoji', () => {
+  const inline = n => proseMirrorToMarkdown(doc(para(n))).trim()
+
+  test('the insert path stores a colon-joined family:id name', () => {
+    // What the editor actually emits: one `name`, no `library`. Requiring
+    // both attrs dropped every icon the editor produces.
+    expect(inline({ type: 'UniwebIcon', attrs: { name: 'lucide:star', svg: '<svg/>' } }))
+      .toBe('![](lucide:star)')
+  })
+
+  test('a short-code family uses the compact dash spelling', () => {
+    expect(inline({ type: 'UniwebIcon', attrs: { name: 'lu:star' } })).toBe('![](lu-star)')
+  })
+
+  test('the separate library+name form still maps', () => {
+    expect(inline({ type: 'UniwebIcon', attrs: { library: 'lu', name: 'star' } })).toBe('![](lu-star)')
+  })
+
+  test('the inlined svg blob is never written into markdown', () => {
+    const md = inline({ type: 'UniwebIcon', attrs: { name: 'lucide:star', svg: '<svg viewBox="0 0 24 24"/>' } })
+    expect(md).not.toContain('<svg')
+    expect(md).not.toContain('viewBox')
+  })
+
+  test('emoji carries its character', () => {
+    expect(inline({ type: 'emoji', attrs: { name: 'star', emoji: '⭐' } })).toBe('⭐')
+  })
+
+  test('an emoji with no character is not invented', () => {
+    expect(inline({ type: 'emoji', attrs: { name: 'star' } })).toBe('')
+  })
+})
+
+describe('icon spelling round-trips', () => {
+  test('a full family name keeps the colon form', () => {
+    // `![](lucide-star)` reads back as a plain image with src "lucide-star" —
+    // the dash spelling is short-codes-only, by design in the reader, so that
+    // the form stays unambiguous against a relative path.
+    for (const md of ['![](lucide:star)', '![](heroicons2:arrow-right)', '![](lu-star)']) {
+      const out = proseMirrorToMarkdown(markdownToProseMirror(md)).trim()
+      const attrs = markdownToProseMirror(out).content[0].content[0].attrs
+      expect(attrs.role).toBe('icon')
+    }
+  })
 })

package/tests/roundtrip-source.test.js

@@ -0,0 +1,244 @@
+/**
+ * Source-fidelity round trip: does `source.md` survive reader → writer as the
+ * *same text*, not merely as the same ProseMirror structure?
+ *
+ * `roundtrip.test.js` already asserts the structural fixed point (reparse the
+ * output, compare documents). That test cannot catch a whole class of defect:
+ * the file-lane bug where the second pass is stable but the *first* pass has
+ * already rewritten the author's source. D1 was exactly that shape — a code
+ * span holding `<name>` re-serialized as `&lt;name&gt;`, which reparses to
+ * the same document forever after.
+ *
+ * That matters beyond tidiness. `content-writer` is what the editor uses to
+ * sync ProseMirror back to markdown files, so anything this test tolerates is
+ * something the editor will eventually write into a developer's repository.
+ * The app lane has no source file to diff against, so this is the only place
+ * the codec can be checked at all.
+ *
+ * Known defects are an explicit allowlist below. They assert the *current*
+ * wrong output, so fixing one fails this test and forces the entry to be
+ * removed — the allowlist can only shrink.
+ */
+
+import { readFileSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { markdownToProseMirror } from '@uniweb/content-reader'
+import { proseMirrorToMarkdown } from '../src/index.js'
+
+const FIXTURE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'fixtures', 'roundtrip')
+
+/**
+ * Cosmetic normalization applied to BOTH sides before comparing.
+ *
+ * Declared, not incidental — each entry is a difference we have decided is
+ * not a defect. Keep this list short; anything added here is fidelity given
+ * up permanently.
+ */
+function normalize(markdown) {
+  return (
+    markdown
+      // Table cell padding and delimiter width. Markdown tables are
+      // whitespace-insensitive between pipes, so `|---|---|` and
+      // `| --- | --- |` are the same table — as are `| |` and `|  |`.
+      .replace(/^\|.*\|$/gm, normalizeTableRow)
+      // Hard breaks have two spellings. Two trailing spaces is the classic
+      // one; the serializer deliberately emits a backslash instead, because it
+      // survives editors and pre-commit hooks that strip trailing whitespace.
+      // Fold both to the backslash so a real hard break is not read as a diff
+      // — and so stripping trailing space below cannot silently delete one.
+      .replace(/[ \t]{2,}$/gm, '\\')
+      // Remaining trailing whitespace, and the final newline.
+      .replace(/[ \t]+$/gm, '')
+      .trim()
+  )
+}
+
+/**
+ * Canonicalize one table row: trim every cell, collapse delimiter runs.
+ * @param {string} line
+ * @returns {string}
+ */
+function normalizeTableRow(line) {
+  const cells = line.slice(1, -1).split('|').map(cell => {
+    const trimmed = cell.trim()
+    return /^:?-{2,}:?$/.test(trimmed) ? trimmed.replace(/-+/, '---') : trimmed
+  })
+  return `| ${cells.join(' | ')} |`
+}
+
+/**
+ * Intentional canonicalizations: the projection differs from the source and
+ * that is the designed behavior, not a bug. Separate from the defect list
+ * below because these never "get fixed" — they are the serializer's chosen
+ * spelling, and the entry exists so the choice stays deliberate.
+ */
+const CANONICAL_FORMS = {
+  'canonical-math.md': {
+    reason: 'single-line display math canonicalizes to the compact $$…$$ spelling',
+    // `serializeMathDisplay` documents this: compact for one line, fenced
+    // ```math for multi-line. Both read back as the same node.
+    current: '$$E = mc^2$$'
+  },
+}
+
+/**
+ * Defects known to corrupt source today, each with the output it currently
+ * produces. Fixing one makes its assertion fail, which is the point: the entry
+ * then has to come out, so this list can only shrink.
+ */
+const KNOWN_DEFECTS = {
+  // Empty, and that is the point of the mechanism rather than a claim of
+  // perfection. Four entries lived here and each left by being fixed:
+  //
+  //   D1 — a code span's `<name>` written back as `&lt;name&gt;`
+  //   D2 — bold mishandled around a code span (and dropped outright when it
+  //        wrapped only one)
+  //   D5 — a bold link re-nested to [**x**](url)
+  //   D4 — a tagged data block's YAML rewritten as JSON
+  //   D3 — a loose list re-serialized tight
+  //
+  // D2 and D5 turned out to be one bug (the serializer ignoring `node.marks`
+  // order); D1, D3 and D4 were all the same shape as each other — the reader
+  // dropping something the writer then had to guess at.
+  //
+  // Add an entry when you find a defect you are not fixing today, with the
+  // wrong output it currently produces. Fixing it will break the entry, which
+  // is what forces the removal: this list can only shrink.
+}
+
+const fixtures = readdirSync(FIXTURE_DIR).filter(f => f.endsWith('.md')).sort()
+
+describe('source-fidelity round trip', () => {
+  test('the fixture corpus is not empty', () => {
+    expect(fixtures.length).toBeGreaterThan(0)
+  })
+
+  for (const name of fixtures) {
+    const source = readFileSync(join(FIXTURE_DIR, name), 'utf8')
+    const canonical = CANONICAL_FORMS[name]
+    const known = KNOWN_DEFECTS[name]
+
+    if (canonical) {
+      test(`${name} — canonicalized: ${canonical.reason}`, () => {
+        const projected = proseMirrorToMarkdown(markdownToProseMirror(source))
+        expect(normalize(projected)).toBe(normalize(canonical.current))
+      })
+      continue
+    }
+
+    if (known) {
+      test(`${name} — known defect: ${known.defect}`, () => {
+        const projected = proseMirrorToMarkdown(markdownToProseMirror(source))
+        expect(normalize(projected)).toBe(normalize(known.current))
+        // Guard the guard: if this ever equals the source, the defect is
+        // fixed and the allowlist entry must be deleted.
+        expect(normalize(projected)).not.toBe(normalize(source))
+      })
+      continue
+    }
+
+    test(`${name} round-trips to its source`, () => {
+      const projected = proseMirrorToMarkdown(markdownToProseMirror(source))
+      expect(normalize(projected)).toBe(normalize(source))
+    })
+  }
+
+  test('every allowlist entry names a real fixture', () => {
+    for (const name of [...Object.keys(KNOWN_DEFECTS), ...Object.keys(CANONICAL_FORMS)]) {
+      expect(fixtures).toContain(name)
+    }
+  })
+})
+
+describe('structural fixed point holds for every fixture', () => {
+  // Even a fixture with a known source-level defect must be stable on the
+  // second pass — otherwise the defect compounds on each sync.
+  for (const name of fixtures) {
+    test(`${name} is stable on re-serialization`, () => {
+      const source = readFileSync(join(FIXTURE_DIR, name), 'utf8')
+      const once = proseMirrorToMarkdown(markdownToProseMirror(source))
+      const twice = proseMirrorToMarkdown(markdownToProseMirror(once))
+      expect(twice).toBe(once)
+    })
+  }
+})
+
+describe('list looseness', () => {
+  const rt = md => proseMirrorToMarkdown(markdownToProseMirror(md)).trim()
+
+  test('a tight list stays tight', () => {
+    expect(rt('- one\n- two')).toBe('- one\n- two')
+  })
+
+  test('a loose list keeps its blank lines', () => {
+    expect(rt('- one\n\n- two')).toBe('- one\n\n- two')
+  })
+
+  test('looseness applies inside an item too, not just between items', () => {
+    const source = '- parent\n\n  - child\n  - sibling\n\n- next'
+    expect(rt(source)).toBe(source)
+  })
+
+  test('ordered lists carry looseness alongside start', () => {
+    expect(rt('1. a\n\n2. b')).toBe('1. a\n\n2. b')
+  })
+
+  test('a nested list is loose independently of its parent', () => {
+    expect(rt('- parent\n  - child\n  - sibling\n- next')).toBe('- parent\n  - child\n  - sibling\n- next')
+  })
+
+  test('a list node with no loose flag serializes tight', () => {
+    // Documents written before the reader recorded looseness.
+    const doc = {
+      type: 'doc',
+      content: [{
+        type: 'bulletList',
+        content: ['one', 'two'].map(t => ({
+          type: 'listItem',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: t }] }]
+        }))
+      }]
+    }
+    expect(proseMirrorToMarkdown(doc).trim()).toBe('- one\n- two')
+  })
+})
+
+describe('blocks inside list items', () => {
+  const rt = md => proseMirrorToMarkdown(markdownToProseMirror(md)).trim()
+  const itemChildren = md => markdownToProseMirror(md).content[0].content[0].content.map(n => n.type)
+
+  test('a fenced block under a bullet stays a code block', () => {
+    // It used to be lexed as inline and folded into the item's paragraph,
+    // losing the fence, the language and the line breaks — in the rendered
+    // page, not only on a round trip.
+    expect(itemChildren('- Use it:\n  ```jsx\n  const x = 1\n  ```')).toEqual(['paragraph', 'codeBlock'])
+  })
+
+  test('a blockquote under a bullet stays a blockquote', () => {
+    expect(itemChildren('- Item\n  > quoted')).toEqual(['paragraph', 'blockquote'])
+  })
+
+  test('a nested list is still a nested list', () => {
+    expect(itemChildren('- parent\n  - child')).toEqual(['paragraph', 'bulletList'])
+  })
+
+  test('multiple paragraphs in one item survive', () => {
+    expect(itemChildren('- First\n\n  Second\n\n- Next')).toEqual(['paragraph', 'paragraph'])
+  })
+
+  test('a code block round-trips inside a tight list', () => {
+    const source = '- Use the hook:\n  ```jsx\n  const x = 1\n  ```\n- Next item'
+    expect(rt(source)).toBe(source)
+  })
+
+  test('a code block round-trips inside a loose list', () => {
+    const source = '- Use the hook:\n\n  ```jsx\n  const x = 1\n  ```\n\n- Next item'
+    expect(rt(source)).toBe(source)
+  })
+
+  test('an ordered item indents its block to the wider bullet', () => {
+    const source = '1. Step one\n   ```sh\n   run it\n   ```\n2. Step two'
+    expect(rt(source)).toBe(source)
+  })
+})

package/tests/roundtrip.test.js

@@ -358,3 +358,34 @@ describe('Round-trip: Mixed Content', () => {
     expect(reparsed).toEqual(parsed)
   })
 })
+
+describe('Round-trip: Hard breaks', () => {
+  // A hard break used to become a "\n" text node, which re-parsed as a SOFT
+  // break — so the break was silently downgraded on every round trip. It is a
+  // `hardBreak` node now, and both markdown spellings converge on the
+  // backslash form.
+  testRoundTrip('line one\\\nline two', 'backslash hard break')
+  testRoundTrip('a\\\nb\\\nc', 'consecutive hard breaks')
+  testRoundTrip('**bold**\\\nplain', 'hard break after a mark')
+
+  test('two-space spelling normalizes to backslash and keeps the break', () => {
+    const parsed = markdownToProseMirror('line one  \nline two')
+    expect(parsed.content[0].content).toEqual([
+      { type: 'text', text: 'line one' },
+      { type: 'hardBreak' },
+      { type: 'text', text: 'line two' }
+    ])
+    // One-time source normalization; the break itself survives.
+    const serialized = proseMirrorToMarkdown(parsed).trim()
+    expect(serialized).toBe('line one\\\nline two')
+    expect(markdownToProseMirror(serialized)).toEqual(parsed)
+  })
+
+  test('a soft break stays soft — it is a space, not a break', () => {
+    const parsed = markdownToProseMirror('wrapped\nparagraph')
+    expect(parsed.content[0].content).toEqual([
+      { type: 'text', text: 'wrapped\nparagraph' }
+    ])
+    expect(proseMirrorToMarkdown(parsed).trim()).toBe('wrapped\nparagraph')
+  })
+})

package/tests/serializer.test.js

@@ -349,18 +349,28 @@ describe('Code Blocks', () => {
     expect(serializeDoc(doc)).toBe('```\nline 1\n\nline 2\n```')
   })
 
-  test('serializes data block', () => {
-    const doc = {
-      type: 'doc',
-      content: [
-        {
-          type: 'dataBlock',
-          attrs: { tag: 'nav-links', data: [{ label: 'Home' }] },
-        },
-      ],
-    }
-    const expected = '```json:nav-links\n[\n  {\n    "label": "Home"\n  }\n]\n```'
-    expect(serializeDoc(doc)).toBe(expected)
+  const dataBlockDoc = attrs => ({ type: 'doc', content: [{ type: 'dataBlock', attrs }] })
+
+  test('serializes a data block as JSON when that is what the author wrote', () => {
+    const doc = dataBlockDoc({ tag: 'nav-links', language: 'json', data: [{ label: 'Home' }] })
+    expect(serializeDoc(doc)).toBe('```json:nav-links\n[\n  {\n    "label": "Home"\n  }\n]\n```')
+  })
+
+  test('serializes a data block as YAML when that is what the author wrote', () => {
+    const doc = dataBlockDoc({ tag: 'nav-links', language: 'yaml', data: [{ label: 'Home' }] })
+    expect(serializeDoc(doc)).toBe('```yaml:nav-links\n- label: Home\n```')
+  })
+
+  test('echoes back the `yml` spelling rather than normalizing it', () => {
+    const doc = dataBlockDoc({ tag: 'cfg', language: 'yml', data: { key: 'value' } })
+    expect(serializeDoc(doc)).toBe('```yml:cfg\nkey: value\n```')
+  })
+
+  test('falls back to YAML when no language was recorded', () => {
+    // A node from before the reader recorded `language`. This used to emit
+    // JSON unconditionally, which rewrote every YAML block an author wrote.
+    const doc = dataBlockDoc({ tag: 'nav-links', data: [{ label: 'Home' }] })
+    expect(serializeDoc(doc)).toBe('```yaml:nav-links\n- label: Home\n```')
   })
 })