@uniweb/semantic-parser 1.6.0 → 1.8.0

package/README.md

@@ -74,8 +74,8 @@ result = {
   // Body fields
   paragraphs: ["Get started today."],
   links: [],                // All links (including buttons)
-  images: [],
-  videos: [],
+  images: [],               // { url, alt, caption, role, placement?, author?, … }
+  videos: [],               // { src, poster?, caption, placement?, … }
   documents: [],            // Files marked {role=pdf} — { url, name, mime, size?, alt,
                             //   caption, preview?, … }
   icons: [],
@@ -87,7 +87,8 @@ result = {
   snippets: [],             // Fenced code blocks — { language, code }
   data: {},                 // Structured data (tagged data blocks, forms, cards)
   headings: [],             // Only from nested content (quote/list bodies)
-  // tables: [],            // Only when the content has one — { rows, attrs }
+  // tables: [],            // Only when the content has one — { rows, attrs } — attrs:
+                            //   caption, id, placement, from its caption line
   // math: [],              // Only when the content has one — { id, latex, mathml }
 
   // Additional content groups (from headings after content)
@@ -116,7 +117,7 @@ const content = parseContent(doc);
 
 const title = content.title;
 const description = content.paragraphs.join(" ");
-const image = content.images[0]?.src;
+const image = content.images[0]?.url;
 ```
 
 ### Processing Content Sections

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/semantic-parser",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Semantic parser for ProseMirror/TipTap content structures",
   "type": "module",
   "main": "./src/index.js",

package/src/builders/doc.js

@@ -1,5 +1,6 @@
 /**
- * Reverse conversion: content structure → TipTap document.
+ * Reverse conversion: content structure → a ProseMirror document in the
+ * rich-text vocabulary (`@uniweb/content-reader`'s schema).
  *
  * Mirrors the forward parser (processors/sequence.js + processors/groups.js)
  * so that parseContent(buildDoc(content)) roundtrips cleanly.
@@ -7,6 +8,16 @@
  * Starter content uses plain strings (no HTML marks), so the conversion
  * is straightforward — no need to reverse inline HTML formatting.
  *
+ * ## ⭐ IT WRITES THE VOCABULARY, IN THE SHAPES MARKDOWN READS TO
+ *
+ * Every node is one content-reader writes for the same markdown: a picture, a
+ * video and a document are an `image` with its `role`, an icon an `image` with
+ * `role: 'icon'` inside a paragraph, a divider a `divider`. What this returns is
+ * stored as it is and opened like any stored document, so it holds what every
+ * reader of a stored document reads — never one editor's own node names.
+ * ⛔ Until 2026-10-15 it wrote an editor's TipTap nodes (`ImageBlock`,
+ * `UniwebIcon`, `Video`, `DividerBlock`), which the vocabulary does not hold.
+ *
  * ## ⭐ IT ACCEPTS THE PARSER'S OWN VOCABULARY TOO — and that is a contract
  *
  * This builder was written with its own spelling for several concepts, and
@@ -20,7 +31,7 @@
  * most naturally reach for:
  *
  *   { links:  [{ label, href }] }        → buildDoc returns **null** outright
- *   { images: [{ url, alt }] }           → an ImageBlock with NO url attr
+ *   { images: [{ url, alt }] }           → an image node with NO address
  *   { videos: [{ coverImg: '/p.jpg' }] } → the cover parses back as ""
  *   { lists:  parsed.lists }             → a text node whose `text` is an
  *                                          OBJECT — an invalid document
@@ -36,7 +47,7 @@
  * differs from the parser's needs the same treatment, or it joins this list.
  */
 
-// --- TipTap node builders ---
+// --- Node builders ---
 
 function textNode(text) {
   return { type: 'text', text }
@@ -103,17 +114,23 @@ function linkParagraph({ text, label, href, target }) {
   }
 }
 
-function imageBlock({ src, url, alt = '', caption = '', direction, role, width, height }) {
-  // The node attr is `url` and so is the parsed field; `src` is this builder's
-  // original spelling. Either one in, `url` out.
-  const attrs = { url: src || url, alt }
+/** The attributes an image may hold beside its address, copied when they hold a value. */
+const IMAGE_EXTRAS = ['href', 'target', 'author', 'id', 'fit', 'position', 'loading']
+
+function imageNode(image) {
+  const { src, url, alt = '', caption = '', placement, role, width, height } = image
+  // The node's attr is `src`, this builder's original spelling; the parsed
+  // field is `url`. Either one in, `src` out.
+  const attrs = { src: src || url, alt, role: role || 'image' }
   if (caption) attrs.caption = caption
-  if (direction) attrs.direction = direction
-  if (role) attrs.role = role
-  if (width && height) {
-    attrs.aspect_ratio = { width, height, ratio: (height / width) * 100 }
-  }
-  return { type: 'ImageBlock', attrs }
+  // The picture's own size. Its proportions are these two, so nothing else
+  // carries them — ⛔ until 2026-10-15 this wrote an `aspect_ratio` computed
+  // from them, which the vocabulary does not hold.
+  if (width) attrs.width = width
+  if (height) attrs.height = height
+  if (placement) attrs.placement = placement
+  for (const key of IMAGE_EXTRAS) if (image[key]) attrs[key] = image[key]
+  return { type: 'image', attrs }
 }
 
 // A document is STORED as the image row with `role: 'pdf'` — the node the
@@ -128,46 +145,58 @@ function documentNode({ url, src, alt = '', caption = '', preview, author, descr
   return { type: 'image', attrs }
 }
 
-function iconNode({ src, url, svg, library, name, size, color }) {
-  // UniwebIcon supports multiple source types.
-  //
-  // The family rides INSIDE `name` as `family:id`. The editor's node declares
-  // `{ name, svg, url, size, color, preserveColors, info }` and no `library`,
-  // and ProseMirror silently drops undeclared attrs on `fromJSON` — so emitting
-  // a separate `library` lost the family without a trace, on the path that
-  // builds starter content for every new section.
-  //
-  // `svg` is MARKUP and `url` is a URL — on both sides. A file-sourced icon
-  // arrives here as `src` and belongs in `url`, not in the markup slot; putting
-  // a path where a consumer expects `<svg …>` renders nothing. (Fixed
-  // 2026-07-30; `url` is declared on the editor's node, so it crosses intact.)
-  const attrs = {}
-  if (svg) attrs.svg = svg
-  // Either spelling in, one spelling out — `parseUniwebIcon` now emits `url`
-  // for a file-sourced icon, and this builder's documented invariant is that
-  // parseContent(buildDoc(x)) round-trips.
-  if (url || src) attrs.url = url || src
-  if (name) attrs.name = library ? `${library}:${name}` : name
+/**
+ * An icon, as markdown's `![](lu-house)` reads: an `image` with `role: 'icon'`
+ * inside a paragraph — from a library by `library` and `name`, or from a file
+ * by its address.
+ *
+ * `svg` is MARKUP, and a stored document holds none (the vocabulary has no
+ * attribute for it), so an icon given only as markup is left out: the builder
+ * returns null rather than a node that names no picture. A file-sourced icon
+ * arrives as `url` (what the parser emits) or `src`.
+ */
+function iconNode({ src, url, library, name, size, color }) {
+  const attrs = { role: 'icon' }
+  if (src || url) {
+    attrs.src = src || url
+  } else if (name) {
+    // A parsed editor node may carry the family inside the name, `family:id`.
+    // The vocabulary holds the two apart, as `![](lu-house)` reads.
+    if (!library && typeof name === 'string' && name.includes(':')) {
+      const [family, ...id] = name.split(':')
+      library = family
+      name = id.join(':')
+    }
+    if (library) attrs.library = library
+    attrs.name = name
+  } else {
+    return null
+  }
   if (size) attrs.size = size
   if (color) attrs.color = color
-  return { type: 'UniwebIcon', attrs }
+  return { type: 'paragraph', content: [{ type: 'image', attrs }] }
 }
 
-function videoNode({ src, url, caption, direction, coverImg }) {
-  const attrs = { src: src || url }
+const PLAYBACK_FLAGS = ['autoplay', 'muted', 'loop', 'controls']
+
+function videoNode(video) {
+  const { src, url, alt, caption, placement, poster, coverImg } = video
+  const attrs = { src: src || url, role: 'video' }
+  if (alt) attrs.alt = alt
   if (caption) attrs.caption = caption
-  if (direction) attrs.direction = direction
-  // ⛔ The editor's `Video` node holds `coverImg` as an OBJECT — the reader is
-  // `makeAssetUrl`, which looks for `.src` / `.url` / `.identifier`. A bare
-  // string passed straight through parses back as "": `info?.src` on a string
-  // is undefined. Normalize here so a caller may write either.
-  const cover = typeof coverImg === 'string' ? { src: coverImg } : coverImg
-  if (cover && (cover.src || cover.url || cover.identifier)) attrs.coverImg = cover
-  return { type: 'Video', attrs }
+  // The cover is `poster`, what the parser emits for a video and what a
+  // component reads. `coverImg` is an editor's spelling — a string, or an
+  // object whose `src` or `url` is the address; an `identifier` alone names
+  // no address, so it gives none.
+  const cover = poster || (typeof coverImg === 'string' ? coverImg : coverImg?.src || coverImg?.url)
+  if (cover) attrs.poster = cover
+  if (placement) attrs.placement = placement
+  for (const flag of PLAYBACK_FLAGS) if (typeof video[flag] === 'boolean') attrs[flag] = video[flag]
+  return { type: 'image', attrs }
 }
 
-function dividerBlock() {
-  return { type: 'DividerBlock' }
+function dividerNode() {
+  return { type: 'divider' }
 }
 
 /**
@@ -242,11 +271,11 @@ function listItemText(item) {
 // --- Group builder ---
 
 /**
- * Build TipTap nodes from a content group (main or item).
+ * Build the nodes of a content group (main or item).
  *
  * @param {Object} group - Content structure: { pretitle, title, subtitle, paragraphs, images, ... }
  * @param {number} titleLevel - Heading level for title (1 for main, 2 for items)
- * @returns {Array} Array of TipTap nodes
+ * @returns {Array} the group's nodes, in the vocabulary
  */
 function buildGroupNodes(group, titleLevel = 1, options = {}) {
   const nodes = []
@@ -282,7 +311,7 @@ function buildGroupNodes(group, titleLevel = 1, options = {}) {
 
   if (group.images) {
     for (const img of group.images) {
-      nodes.push(imageBlock(img))
+      nodes.push(imageNode(img))
     }
   }
 
@@ -295,7 +324,8 @@ function buildGroupNodes(group, titleLevel = 1, options = {}) {
 
   if (group.icons) {
     for (const icon of group.icons) {
-      nodes.push(iconNode(icon))
+      const node = iconNode(icon)
+      if (node) nodes.push(node)
     }
   }
 
@@ -347,10 +377,10 @@ function buildGroupNodes(group, titleLevel = 1, options = {}) {
 // --- Main export ---
 
 /**
- * Build a TipTap document from a content structure.
+ * Build a document in the vocabulary from a content structure.
  *
  * This is the reverse of parseContent(): given a flat content object
- * (title, paragraphs, items, etc.), produce a TipTap document that
+ * (title, paragraphs, items, etc.), produce a ProseMirror document that
  * roundtrips through parseContent() to yield the same structure.
  *
  * @param {Object} content - Content structure (same shape as parseContent output / starter)
@@ -358,7 +388,7 @@ function buildGroupNodes(group, titleLevel = 1, options = {}) {
  * @param {string} [options.dataLanguage='yaml'] - the fence a tagged data block
  *   is written as. It is recorded on the node because content-writer reads it
  *   back to choose the fence, and a parsed value cannot say which one it was.
- * @returns {Object|null} TipTap document { type: 'doc', content: [...] }, or null if empty
+ * @returns {Object|null} a document { type: 'doc', content: [...] }, or null if empty
  */
 function buildDoc(content, options = {}) {
   if (!content) return null
@@ -368,10 +398,10 @@ function buildDoc(content, options = {}) {
   // Main group content (title level 1)
   nodes.push(...buildGroupNodes(content, 1, options))
 
-  // Items: separated by DividerBlock (mirrors divider-based grouping in groups.js)
+  // Items: separated by a divider (mirrors divider-based grouping in groups.js)
   if (content.items && content.items.length > 0) {
     for (const item of content.items) {
-      nodes.push(dividerBlock())
+      nodes.push(dividerNode())
       // Item headings use level 2 (one below main H1)
       nodes.push(...buildGroupNodes(item, 2, options))
     }

package/src/processors/sequence.js

@@ -861,8 +861,8 @@ function parseCardBlock(itemAttrs) {
 //
 // Read through `parseImgBlock`, which resolves the address and the preview's the
 // way every image's are, and then narrowed to what a document IS: where the file
-// is, what it is called, and the resource's own metadata. The image layout keys
-// (direction, size, credit) describe a picture, not a file, and are left out.
+// is, what it is called, and the resource's own metadata. Where a picture sits
+// in a flow (`placement`) is not a file's, and is left out.
 function parseMarkdownDocument(itemAttrs, options) {
     const { url, alt, caption, role, href, target, id, preview, author, description } =
         parseImgBlock(itemAttrs || {}, options);
@@ -1016,47 +1016,47 @@ function parseImgBlock(itemAttrs, options) {
         info: imgInfo,
         targetId,
         caption = "",
-        direction,
-        filter,
         alt = "",
         src,
         url,
         href = "",
         target = "",
-        theme,
         role,
-        credit = "",
+        credit, // the editor's word for `author` — delivered as `author`
         id, // {#fig-id} cross-reference label — preserved so Press
             // adapters can emit \label{id} (LaTeX) / <id> (Typst).
         // ── Markdown-authored attributes ────────────────────────────────
         // This function was written for the EDITOR's `ImageBlock` node and
         // later reused for the markdown `image` node (see `case "image"`), so
-        // its vocabulary is the editor's: contentType, direction, filter,
-        // theme, credit. Everything markdown declares and the editor does not
-        // was therefore tokenized, declared, and then dropped one layer before
-        // delivery — the published "Image Attributes" table
-        // (docs/reference/content-structure.md) reached no component, and
-        // neither did the `role=pdf` set added 2026-07-29 for the editor's
-        // `document` fold-in. Carried 2026-07-30.
+        // its vocabulary was the editor's. Everything markdown declares and
+        // the editor does not was therefore tokenized, declared, and then
+        // dropped one layer before delivery — the published "Image
+        // Attributes" table (docs/reference/content-structure.md) reached no
+        // component, and neither did the `role=pdf` set added 2026-07-29 for
+        // the editor's `document` fold-in. Carried 2026-07-30.
+        //
+        // ⭐ An element now holds the vocabulary's words, whichever node it
+        // came from. ⛔ Until 2026-10-15 it also held the editor's `direction`
+        // and two things derived from it — `imgPos` (left/right) and a
+        // layout `size` (basic/lg/full, `basic` for every image without one) —
+        // plus `filter` and `theme`, none of which a stored document holds. A
+        // component handing the element to kit's <Image> passed that `size` as
+        // Image's avatar preset, so a "wide" image drew as a 96px square.
         width,
         height,
         loading,
         fit,
         position,
+        placement,   // where it sits in a flow: left, right, wide, full
         preview,     // role=pdf — the preview image
-        author,      // role=pdf — resource metadata, rendered beside the preview
+        author,      // the image's attribution; for role=pdf, the resource's
         description, // role=pdf — describes the RESOURCE, not the image (≠ alt)
     } = itemAttrs;
 
     let { contentType, viewType, contentId, identifier } = imgInfo || {};
 
-    const sizes = {
-        center: "basic",
-        wide: "lg",
-        fill: "full",
-    };
-
     caption = stripTags(caption);
+    const attribution = author || credit;
 
     // Reference precedence. Standard ProseMirror `image` nodes use `src`; the
     // custom `ImageBlock` node uses `url`. Honor either so callers don't have to
@@ -1088,19 +1088,9 @@ function parseImgBlock(itemAttrs, options) {
         value: identifier || "",
         alt: alt || caption,
         caption,
-        direction,
-        filter,
-        imgPos: direction === "left" || direction === "right" ? direction : "",
-        // NOTE: `size` here is the direction-derived LAYOUT size
-        // (basic/lg/full), not the author's `{size=…}` — that attribute is
-        // icon-only and is read by parseUniwebIcon. Do not wire `{size=…}`
-        // through here; the two meanings collide on one key.
-        size: sizes[direction] || "basic",
         href,
         target,
-        theme,
         role,
-        credit,
         id: id || undefined,
         // Omitted when absent, so an existing consumer sees no new empty keys.
         ...(width !== undefined && width !== null && { width }),
@@ -1108,12 +1098,13 @@ function parseImgBlock(itemAttrs, options) {
         ...(loading && { loading }),
         ...(fit && { fit }),
         ...(position && { position }),
+        ...(placement && { placement }),
         ...((() => {
             // Same rule for a document's preview image.
             const p = secondaryAssetUrl(itemAttrs, options, "preview");
             return p ? { preview: p } : {};
         })()),
-        ...(author && { author }),
+        ...(attribution && { author: attribution }),
         ...(description && { description }),
     };
 }
@@ -1142,6 +1133,7 @@ function parseMarkdownVideo(itemAttrs, options) {
         target = "",
         role,
         id, // {#fig-id} cross-reference label, same as parseImgBlock
+        placement, // where it sits in a flow, same as parseImgBlock
     } = itemAttrs || {};
 
     // Reference precedence, now genuinely identical to parseImgBlock: a
@@ -1175,6 +1167,7 @@ function parseMarkdownVideo(itemAttrs, options) {
     if (loop !== undefined) video.loop = loop;
     if (controls !== undefined) video.controls = controls;
     if (id) video.id = id;
+    if (placement) video.placement = placement;
 
     return video;
 }
@@ -1183,12 +1176,12 @@ function parseVideoBlock(itemAttrs, options) {
     let {
         src,
         caption = "",
-        direction,
         info = {},
         coverImg = {},
         alt,
         href = "",
         target = "",
+        placement, // where it sits in a flow; the editor's `direction` is not read
     } = itemAttrs;
 
     // Same precedence as parseImgBlock / parseMarkdownVideo: a resolvable
@@ -1198,11 +1191,11 @@ function parseVideoBlock(itemAttrs, options) {
     return {
         src: video,
         caption,
-        direction,
         coverImg: makeAssetUrl(coverImg),
         alt,
         href,
         target,
+        ...(placement && { placement }),
     };
 }