@uniweb/content-writer 0.2.9 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/content-writer",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "ProseMirror document structure to Markdown converter",
   "type": "module",
   "main": "src/index.js",
@@ -20,7 +20,7 @@
   },
   "devDependencies": {
     "vitest": "^4.1.7",
-    "@uniweb/content-reader": "1.1.17"
+    "@uniweb/content-reader": "1.2.0"
   },
   "directories": {
     "test": "tests"

package/src/nodes.js

@@ -126,6 +126,42 @@ export function serializeInsetBlock(node) {
   return `${fence}@${component}${attrStr}\n${body}\n${fence}`
 }
 
+/**
+ * Serialize a concept block back to its ```md:<tag> fence.
+ *
+ * The inverse of content-reader's concept-block branch. The body is real block
+ * content, so it serializes through the ordinary node path — a concept block is
+ * the section pipeline one level down, and its body is markdown at both ends.
+ *
+ * The fence widens past any backtick run in the body, for the same reason a
+ * container's does: an answer that shows a code sample is ordinary
+ * documentation, and a three-backtick fence would close on the sample's own
+ * fence and spill the remainder into the page as prose.
+ *
+ * A missing serializer here is not a cosmetic gap. `serializeNode` omits an
+ * unmapped node, so the whole block — the author's prose with it — would
+ * vanish from the file on the next write-back and from the per-page markdown
+ * projection. That is why the round-trip test asserts the BODY rather than
+ * just the fence line.
+ *
+ * @param {Object} node - concept_block node with attrs.tag + block content
+ * @returns {string} Fenced concept block
+ */
+export function serializeConceptBlock(node) {
+  const { tag } = node.attrs || {}
+  if (!tag) return ''
+
+  const { serializeNode } = await_serializer()
+  const body = (node.content || [])
+    .map(child => serializeNode(child))
+    .filter(Boolean)
+    .join('\n\n')
+
+  const fence = '`'.repeat(fenceWidthFor(body))
+
+  return `${fence}md:${tag}\n${body}\n${fence}`
+}
+
 /**
  * Serialize a data block node.
  *
@@ -317,9 +353,21 @@ function indentBlock(text, firstPrefix, pad) {
 
 /**
  * Serialize a divider node.
- * @returns {string} Markdown horizontal rule
+ *
+ * Emits the attribute spelling only when `type` carries a non-default value, so
+ * an ordinary rule stays `---` and no existing document is rewritten. `style` and
+ * `size` are deliberately NOT emitted: they are dead attrs (nothing reads them,
+ * no spelling sets them) and writing them would put vocabulary into every
+ * author's file that the framework is trying to retire.
+ *
+ * @param {Object} [node] - Divider node
+ * @returns {string} Markdown thematic break, with `{type=…}` when meaningful
  */
-export function serializeDivider() {
+export function serializeDivider(node) {
+  const type = node?.attrs?.type
+  if (typeof type === 'string' && type && type !== 'hr') {
+    return `---{type=${type}}`
+  }
   return '---'
 }
 

package/src/normalize.js

@@ -193,14 +193,8 @@ function mapEditorNode(node) {
     case 'Icon':
       return mapUniwebIcon(node)
     case 'WarningBlock':
-    case 'details': {
-      const attrs = EDITOR_CONTAINERS[node.type](node)
-      return {
-        type: 'inset_block',
-        attrs,
-        content: node.type === 'details' ? detailsBody(node) : asBlocks(node.content),
-      }
-    }
+    case 'details':
+      return EDITOR_CONTAINERS[node.type](node)
     case 'emoji':
       // The node carries the character alongside a name; the character is the
       // whole markdown form. Guarded rather than assumed to be populated.
@@ -256,8 +250,25 @@ const NAMED_INLINE_STYLES = new Set(['accent', 'highlight', 'callout', 'muted'])
  * missing entry here is a visible gap rather than a silent assumption.
  */
 const EDITOR_CONTAINERS = {
-  WarningBlock: node => ({ component: 'Alert', type: node.attrs?.type || 'info' }),
-  details: () => ({ component: 'Details' }),
+  // A callout's SEVERITY is the concept, not a parameter on one — a warning and
+  // a note are different kinds of thing, so they are different tags. This is
+  // where the editor's `type` attribute goes.
+  WarningBlock: node => ({
+    type: 'concept_block',
+    attrs: { tag: node.attrs?.type || 'info' },
+    content: asBlocks(node.content),
+  }),
+  // The summary becomes the leading HEADING rather than a paragraph, which is
+  // what makes the mapping lossless in both directions: a concept block's items
+  // come from its headings, so the summary recovers as that item's title and
+  // the body as its paragraphs. Flattening it to a paragraph — what this did
+  // while the target was an inset — made the two indistinguishable on the way
+  // back.
+  details: node => ({
+    type: 'concept_block',
+    attrs: { tag: 'details' },
+    content: detailsBody(node),
+  }),
 }
 
 /** Inline node types, for deciding whether a container's body needs wrapping. */
@@ -289,11 +300,18 @@ function asBlocks(content) {
 }
 
 /**
- * Flatten the editor's `details` › `detailsSummary` + `detailsContent` into the
- * container's body, summary first.
+ * Flatten the editor's `details` › `detailsSummary` + `detailsContent` into a
+ * concept block's body, summary first — as a HEADING.
  *
- * The summary leads rather than riding on an attribute: `detailsSummary` can
- * carry marks, and `summary="…"` would flatten emphasis and links.
+ * The heading is what makes the mapping lossless. A concept block's items come
+ * from its headings, so a summary written as `# …` recovers as that item's
+ * title and the body as its paragraphs; written as a paragraph (which is what
+ * this did while the target was an inset) the two become indistinguishable on
+ * the way back, and a disclosure loses which half was its label.
+ *
+ * The summary stays inline content rather than moving to an attribute for the
+ * original reason: `detailsSummary` can carry marks, and `summary="…"` would
+ * flatten emphasis and links.
  *
  * @param {Object} node
  * @returns {Array}
@@ -301,8 +319,11 @@ function asBlocks(content) {
 function detailsBody(node) {
   const body = []
   for (const child of node.content || []) {
-    if (child.type === 'detailsSummary') body.push(...asBlocks(child.content))
-    else if (child.type === 'detailsContent') body.push(...(child.content || []))
+    if (child.type === 'detailsSummary') {
+      if (child.content?.length) {
+        body.push({ type: 'heading', attrs: { level: 1 }, content: child.content })
+      }
+    } else if (child.type === 'detailsContent') body.push(...(child.content || []))
     else body.push(child)
   }
   return body

package/src/serializer.js

@@ -10,6 +10,7 @@ import {
   serializeImage,
   serializeInsetRef,
   serializeInsetBlock,
+  serializeConceptBlock,
   serializeCodeBlock,
   serializeDataBlock,
   serializeBlockquote,
@@ -29,6 +30,7 @@ const NODE_SERIALIZERS = {
   image: serializeImage,
   inset_ref: serializeInsetRef,
   inset_block: serializeInsetBlock,
+  concept_block: serializeConceptBlock,
   codeBlock: serializeCodeBlock,
   dataBlock: serializeDataBlock,
   blockquote: serializeBlockquote,

package/tests/roundtrip-source.test.js

@@ -263,22 +263,34 @@ describe('containers — the block form of an inset', () => {
     expect(rt(source)).toBe(source)
   })
 
-  test('the editor container shapes normalize onto it', () => {
+  test('the editor containers normalize onto CONCEPT blocks, not insets', () => {
+    // Changed 2026-07-31. These used to become `@Alert` and `@Details` — an
+    // inset naming the component that renders it, which is a rendering
+    // decision living in content. A concept block names what the content IS
+    // and leaves rendering to the foundation.
     const text = t => ({ type: 'text', text: t })
     const doc = node => proseMirrorToMarkdown({ type: 'doc', content: [node] }).trim()
 
-    // WarningBlock ↔ @Alert, defaulting to info, NOT warning — a name-derived
-    // mapping drops exactly this.
+    // The editor's `type` becomes the TAG: a warning and a note are different
+    // kinds of thing, not one kind with a parameter. `info` is still the
+    // default, and still not `warning` — a name-derived mapping drops that.
     expect(doc({ type: 'WarningBlock', attrs: {}, content: [text('Careful.')] }))
-      .toBe('```@Alert{type=info}\nCareful.\n```')
-
-    // The summary is the first block and keeps its marks.
+      .toBe('```md:info\nCareful.\n```')
+    expect(doc({ type: 'WarningBlock', attrs: { type: 'warning' }, content: [text('Careful.')] }))
+      .toBe('```md:warning\nCareful.\n```')
+
+    // The summary becomes the leading HEADING, which is what makes this
+    // lossless: a concept block's items come from its headings, so the summary
+    // recovers as the item's title and the body as its paragraphs. As a
+    // paragraph — what this produced while the target was an inset — the two
+    // were indistinguishable coming back.
     expect(doc({
       type: 'details',
       content: [
         { type: 'detailsSummary', content: [text('Breaking '), { type: 'text', text: 'changes', marks: [{ type: 'bold' }] }] },
         { type: 'detailsContent', content: [{ type: 'paragraph', content: [text('Body.')] }] },
       ],
-    })).toBe('```@Details\nBreaking **changes**\n\nBody.\n```')
+    })).toBe('```md:details\n# Breaking **changes**\n\nBody.\n```')
   })
+
 })

package/tests/roundtrip.test.js

@@ -389,3 +389,71 @@ describe('Round-trip: Hard breaks', () => {
     expect(proseMirrorToMarkdown(parsed).trim()).toBe('wrapped\nparagraph')
   })
 })
+
+describe('Round-trip: Concept blocks', () => {
+  testRoundTrip(
+    '```md:faq\n# A question\nAn answer.\n\n# Another\nAlso answered.\n```',
+    'concept block with two pairs'
+  )
+
+  testRoundTrip(
+    '```md:warning\nBack up your database **first**.\n\n- Not reversible\n```',
+    'headingless concept block (a callout)'
+  )
+
+  testRoundTrip(
+    '```md:faq\n# Q\nAn answer with **bold** and a [link](/x).\n```',
+    'concept block whose body carries marks and links'
+  )
+
+  test('the BODY survives, not just the fence line', () => {
+    // A missing NODE_SERIALIZERS entry omits the whole node, so a test that
+    // only checks the fence and tag came back would pass on an empty block —
+    // and on a serializer that mangles the prose while the first line looks
+    // right. Assert the content.
+    const md = '```md:faq\n# What plans do you have?\nWe have three.\n```'
+    const out = proseMirrorToMarkdown(markdownToProseMirror(md))
+
+    expect(out).toContain('md:faq')
+    expect(out).toContain('# What plans do you have?')
+    expect(out).toContain('We have three.')
+  })
+
+  test('serialization is a FIXED POINT, which is the bar — not byte equality', () => {
+    // pass1 may differ from the author's original: the serializer normalizes
+    // spacing, so `# Q` immediately followed by its answer comes back with a
+    // blank line between them. Nothing is lost. Asserting byte-equality
+    // against the original would fail on content that is behaving correctly,
+    // and someone would "fix" the serializer to make it pass.
+    const original = '```md:faq\n# Q1\nA1\n# Q2\nA2\n```'
+    const pass1 = proseMirrorToMarkdown(markdownToProseMirror(original))
+    const pass2 = proseMirrorToMarkdown(markdownToProseMirror(pass1))
+
+    // Guard the guard: a fixed point on NOTHING is trivially true. Verified by
+    // canary — unregister the serializer and every other test in this block
+    // fails while `'' === ''` sails through. So pin the content first.
+    expect(pass1).toContain('# Q1')
+    expect(pass1).toContain('A2')
+    expect(pass2).toBe(pass1)
+  })
+
+  test('a code sample inside a concept block widens the outer fence', () => {
+    // Without fenceWidthFor the outer fence closes on the sample's own fence
+    // and the remainder spills into the page as prose. An FAQ answer that
+    // shows code is ordinary documentation, so this is the common case, not
+    // an edge one.
+    const md = '````md:faq\n# How do I start?\nRun this:\n\n```sh\nnpm i\n```\n````'
+    const out = proseMirrorToMarkdown(markdownToProseMirror(md))
+
+    expect(out.startsWith('````md:faq')).toBe(true)
+    expect(out).toContain('```sh')
+    expect(markdownToProseMirror(out)).toEqual(markdownToProseMirror(md))
+  })
+
+  test('an unmapped node would be dropped — so this one must stay mapped', () => {
+    // The failure mode this suite exists to catch: serializeNode omits a node
+    // it has no serializer for, taking the author's prose with it.
+    const doc = markdownToProseMirror('```md:faq\n# Q\nA\n```')
+    expect(proseMirrorToMarkdown(doc).trim()).not.toBe('')
+  })
+})