@uniweb/content-writer 0.2.7 → 0.2.9

package/tests/entities.test.js

@@ -0,0 +1,175 @@
+/**
+ * Entity handling on the way out of ProseMirror.
+ *
+ * The invariant these tests pin down (verified against `content-reader`'s
+ * `parser/inline.js`): a PM text node holds HTML. The reader decodes `&`,
+ * `"` and `'` and leaves `<`/`>` escaped, because the render
+ * path injects the string as HTML. Serializing has to undo exactly that, and
+ * exactly there — decoding more, or decoding in prose, corrupts source.
+ */
+
+import { markdownToProseMirror } from '@uniweb/content-reader'
+import { proseMirrorToMarkdown, docSummaryText, docToPlainText } from '../src/index.js'
+import { encodeMarkupEntities, decodeMarkupEntities, decodeTextEntities } from '../src/entities.js'
+
+const md = s => proseMirrorToMarkdown(markdownToProseMirror(s)).trim()
+
+describe('decodeMarkupEntities', () => {
+  test('undoes the pair the reader leaves escaped', () => {
+    expect(decodeMarkupEntities('/data/&lt;name&gt;.json')).toBe('/data/<name>.json')
+  })
+
+  test('leaves entities the reader already decoded alone', () => {
+    // A PM node holding these means the author typed them.
+    expect(decodeMarkupEntities('a &amp; b')).toBe('a &amp; b')
+    expect(decodeMarkupEntities('say &quot;hi&quot;')).toBe('say &quot;hi&quot;')
+  })
+
+  test('is a no-op on text with no entities', () => {
+    expect(decodeMarkupEntities('plain text')).toBe('plain text')
+  })
+})
+
+describe('decodeTextEntities', () => {
+  test('resolves every entity to the character a reader sees', () => {
+    expect(decodeTextEntities('&lt;b&gt; &amp; &quot;q&quot; &#39;a&#39;')).toBe(`<b> & "q" 'a'`)
+  })
+
+  test('decodes &amp; last, so &amp;lt; yields &lt; and not <', () => {
+    expect(decodeTextEntities('&amp;lt;')).toBe('&lt;')
+  })
+})
+
+describe('D1 — code spans round-trip a literal < >', () => {
+  test('the reported defect', () => {
+    expect(md('Read `/data/<name>.json` for the cascade.')).toBe(
+      'Read `/data/<name>.json` for the cascade.'
+    )
+  })
+
+  test('inside a heading', () => {
+    expect(md('# The `<slug>` folder')).toBe('# The `<slug>` folder')
+  })
+
+  test('inside a table cell', () => {
+    expect(md('| Col |\n| --- |\n| `<x>` |')).toContain('`<x>`')
+  })
+
+  test('inside a link', () => {
+    expect(md('[the `<x>` doc](/a)')).toBe('[the `<x>` doc](/a)')
+  })
+})
+
+describe('D1 — what the fix must NOT touch', () => {
+  test('prose entities stay escaped (decoding them would render as a tag)', () => {
+    expect(md('Literal &lt;name&gt; in prose.')).toBe('Literal &lt;name&gt; in prose.')
+  })
+
+  test('raw inline HTML in prose is preserved verbatim', () => {
+    expect(md('A <name> tag in prose.')).toBe('A <name> tag in prose.')
+  })
+
+  test('an authored &amp; inside a code span survives', () => {
+    expect(md('Code `a &amp; b` here.')).toBe('Code `a &amp; b` here.')
+  })
+
+  test('code blocks are raw text and are left alone', () => {
+    const source = '```js\nconst x = a < b && c > d;\n```'
+    expect(md(source)).toBe(source)
+  })
+
+  test('quotes and apostrophes in code spans are untouched', () => {
+    expect(md(`Code \`say "hi" it's\` here.`)).toBe(`Code \`say "hi" it's\` here.`)
+  })
+})
+
+describe('docSummaryText', () => {
+  const summary = (source, opts) => docSummaryText(markdownToProseMirror(source), opts)
+
+  test('skips the H1 and reads the first paragraph', () => {
+    expect(summary('# Quickstart\n\nCreate your first Uniweb site in 5 minutes.')).toBe(
+      'Create your first Uniweb site in 5 minutes.'
+    )
+  })
+
+  test('returns plain text — no anchors, no mark tags', () => {
+    expect(summary('# T\n\nSee **the [docs](/docs)** for *more*.')).toBe(
+      'See the docs for more.'
+    )
+  })
+
+  test('resolves entities and drops raw inline HTML', () => {
+    expect(summary('# T\n\nUse `<name>` and &lt;slug&gt; and <br> here.')).toBe(
+      'Use <name> and <slug> and here.'
+    )
+  })
+
+  test('truncates at a sentence boundary', () => {
+    const text = 'One sentence here. Two sentence here. Three sentence here.'
+    expect(summary(`# T\n\n${text}`, { maxChars: 40 })).toBe('One sentence here. Two sentence here.')
+  })
+
+  test('falls back to a word boundary with an ellipsis', () => {
+    const text = 'Collections let you manage repeating content across many files'
+    expect(summary(`# T\n\n${text}`, { maxChars: 40 })).toBe(
+      'Collections let you manage repeating…'
+    )
+  })
+
+  test('a dot inside a filename does not end a sentence', () => {
+    expect(summary('# T\n\nEdit site.yml then run the build now please.', { maxChars: 20 }))
+      .toBe('Edit site.yml then…')
+  })
+
+  test('returns empty string when there is no paragraph', () => {
+    expect(summary('# Only a heading')).toBe('')
+    expect(docSummaryText(null)).toBe('')
+  })
+
+  test('collapses newlines into one line', () => {
+    expect(summary('# T\n\nA line\nand another.')).toBe('A line and another.')
+  })
+})
+
+describe('docToPlainText also yields plain characters', () => {
+  test('strips tags and resolves entities', () => {
+    // Note the doubled space where <br> was: this primitive does not
+    // normalize whitespace, and its consumers (word counts, search tokens)
+    // do not care. `docSummaryText` is the one that promises a single line.
+    expect(docToPlainText(markdownToProseMirror('Use &lt;x&gt; and <br> here.'))).toBe(
+      'Use <x> and  here.'
+    )
+  })
+})
+
+describe('encodeMarkupEntities — the producer-side half', () => {
+  test('is the exact inverse of decodeMarkupEntities', () => {
+    const raw = '/data/<name>.json'
+    expect(encodeMarkupEntities(raw)).toBe('/data/&lt;name&gt;.json')
+    expect(decodeMarkupEntities(encodeMarkupEntities(raw))).toBe(raw)
+  })
+
+  test('does not touch &, so an authored entity is not double-encoded', () => {
+    expect(encodeMarkupEntities('a & b')).toBe('a & b')
+    expect(encodeMarkupEntities('&amp;')).toBe('&amp;')
+  })
+
+  test('round-trips what an author types in a code span', () => {
+    for (const raw of ['<div>', 'a < b && c > d', 'a & b', 'plain']) {
+      expect(decodeMarkupEntities(encodeMarkupEntities(raw))).toBe(raw)
+    }
+  })
+
+  test('the one input it does NOT round-trip: literal entity text', () => {
+    // `<div>` and `&lt;div&gt;` both store as `&lt;div&gt;`, so the pair
+    // cannot tell them apart and resolves to the decoded form.
+    //
+    // Accepted deliberately, because the loss happened earlier and elsewhere:
+    // a code span is rendered by injecting its text as HTML, so an author who
+    // typed `&lt;div&gt;` already sees `<div>` on the page. Decoding makes the
+    // file agree with the page rather than destroying something a reader could
+    // otherwise see. Escaping `&` as well would make the pair lossless, at the
+    // cost of changing what every existing code span stores.
+    expect(decodeMarkupEntities(encodeMarkupEntities('&lt;div&gt;'))).toBe('<div>')
+  })
+})

package/tests/fixtures/roundtrip/bare-autolink.md

@@ -0,0 +1,7 @@
+Open http://localhost:5173 in your browser.
+
+Email me at a@b.com when it works.
+
+A labelled link to [the docs](https://example.com) stays labelled.
+
+A link whose label happens to be a URL, [https://example.com](https://example.com "titled"), keeps its explicit form.

package/tests/fixtures/roundtrip/canonical-math.md

@@ -0,0 +1,3 @@
+$$
+E = mc^2
+$$

package/tests/fixtures/roundtrip/code.md

@@ -0,0 +1,11 @@
+# Code
+
+Install it first:
+
+```bash
+pnpm add @uniweb/kit
+```
+
+```js
+const site = { name: 'docs' }
+```

package/tests/fixtures/roundtrip/containers.md

@@ -0,0 +1,22 @@
+# Containers
+
+```@Details
+A summary with **marks**
+
+Body content, [links](/x), the lot.
+```
+
+```@Alert{type=warning}
+Be careful with this.
+
+- one
+- two
+```
+
+````@Alert{type=info}
+Do not do this:
+
+```js
+const x = 1
+```
+````

package/tests/fixtures/roundtrip/defect-bold-code.md

@@ -0,0 +1,3 @@
+- **Preview with `pnpm dev`.**
+
+Use **`npm install`** first.

package/tests/fixtures/roundtrip/defect-bold-link.md

@@ -0,0 +1 @@
+- **[Predicates](./predicates.md)** — filtering with `where:` clauses

package/tests/fixtures/roundtrip/defect-data-block.md

@@ -0,0 +1,6 @@
+# Navigation
+
+```yaml:nav
+- label: Docs
+  href: /docs
+```

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/nested-list-indent.md

@@ -0,0 +1,18 @@
+1. Push your repo to the host
+2. Configure:
+   - Base directory: `site`
+   - Build command: `pnpm build`
+3. Deploy
+
+## A two-digit marker is wider
+
+8. eight
+9. nine
+10. ten
+    - nested under a two-digit marker
+
+## A bullet parent stays at two
+
+- a
+  - b
+    - c

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', () => {
@@ -197,7 +202,7 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'highlighted text',
-        marks: [{ type: 'span', attrs: { class: 'highlight' } }],
+        marks: [{ type: 'span', attrs: { '.highlight': true } }],
       },
       { type: 'text', text: ' in a sentence.' },
     ]
@@ -211,7 +216,7 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'important note',
-        marks: [{ type: 'span', attrs: { class: 'callout bold' } }],
+        marks: [{ type: 'span', attrs: { '.callout': true, '.bold': true } }],
       },
     ]
     expect(serializeInlineContent(content)).toBe('[important note]{.callout .bold}')
@@ -222,7 +227,7 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'key term',
-        marks: [{ type: 'span', attrs: { class: 'highlight', id: 'glossary-term' } }],
+        marks: [{ type: 'span', attrs: { '.highlight': true, id: 'glossary-term' } }],
       },
     ]
     expect(serializeInlineContent(content)).toBe('[key term]{.highlight #glossary-term}')
@@ -233,7 +238,7 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'tooltip text',
-        marks: [{ type: 'span', attrs: { class: 'info', 'data-tooltip': 'More info' } }],
+        marks: [{ type: 'span', attrs: { '.info': true, 'data-tooltip': 'More info' } }],
       },
     ]
     expect(serializeInlineContent(content)).toBe('[tooltip text]{.info data-tooltip="More info"}')
@@ -269,13 +274,13 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'first',
-        marks: [{ type: 'span', attrs: { class: 'highlight' } }],
+        marks: [{ type: 'span', attrs: { '.highlight': true } }],
       },
       { type: 'text', text: ' normal ' },
       {
         type: 'text',
         text: 'second',
-        marks: [{ type: 'span', attrs: { class: 'muted' } }],
+        marks: [{ type: 'span', attrs: { '.muted': true } }],
       },
     ]
     expect(serializeInlineContent(content)).toBe('[first]{.highlight} normal [second]{.muted}')
@@ -292,7 +297,7 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'span',
-        marks: [{ type: 'span', attrs: { class: 'highlight' } }],
+        marks: [{ type: 'span', attrs: { '.highlight': true } }],
       },
     ]
     expect(serializeInlineContent(content)).toBe(

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', () => {
@@ -196,7 +200,11 @@ describe('no-silent-drop guard: unmappable nodes are reported, not lost', () =>
     expect(warnings.some((m) => m.includes('FancyInlineWidget'))).toBe(true)
   })
 
-  test('a legacy standalone "\\n" text node self-heals to a hard break', () => {
+  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(
@@ -206,8 +214,15 @@ describe('no-silent-drop guard: unmappable nodes are reported, not lost', () =>
         )
       )
     )
+    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')
-    expect(warnings).toEqual([]) // healed, not reported as unmapped
   })
 
   test('a newline INSIDE a text node is a soft break and must not be converted', () => {
@@ -219,3 +234,91 @@ describe('no-silent-drop guard: unmappable nodes are reported, not lost', () =>
     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')
+    }
+  })
+})