@uniweb/semantic-parser 1.4.1 → 1.5.1

package/README.md

@@ -73,16 +73,22 @@ result = {
 
   // Body fields
   paragraphs: ["Get started today."],
-  links: [],                // All links (including buttons, documents)
+  links: [],                // All links (including buttons)
   images: [],
   videos: [],
+  documents: [],            // Files marked {role=pdf} — { url, name, mime, size?, alt,
+                            //   caption, preview?, … }
   icons: [],
   lists: [],
   quotes: [],
   insets: [],               // Inline @Component references — { refId }
+  media: [],                // Images, videos and insets on their own line, in the
+                            //   order written — each with its `kind`
   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 }
+  // math: [],              // Only when the content has one — { id, latex, mathml }
 
   // Additional content groups (from headings after content)
   // Each item has the SAME flat structure as the top level — title,

package/package.json

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

package/src/builders/doc.js

@@ -116,6 +116,18 @@ function imageBlock({ src, url, alt = '', caption = '', direction, role, width,
   return { type: 'ImageBlock', attrs }
 }
 
+// A document is STORED as the image row with `role: 'pdf'` — the node the
+// markdown reader writes and the parser reads as a `document` — so that is what
+// this emits. `url` (the parser's spelling) or `src` (this builder's) in.
+function documentNode({ url, src, alt = '', caption = '', preview, author, description }) {
+  const attrs = { src: url || src, alt, role: 'pdf' }
+  if (caption) attrs.caption = caption
+  if (preview) attrs.preview = preview
+  if (author) attrs.author = author
+  if (description) attrs.description = description
+  return { type: 'image', attrs }
+}
+
 function iconNode({ src, url, svg, library, name, size, color }) {
   // UniwebIcon supports multiple source types.
   //
@@ -293,6 +305,12 @@ function buildGroupNodes(group, titleLevel = 1, options = {}) {
     }
   }
 
+  if (group.documents) {
+    for (const doc of group.documents) {
+      nodes.push(documentNode(doc))
+    }
+  }
+
   if (group.lists) {
     for (const list of group.lists) {
       const node = bulletList(list)

package/src/index.js

@@ -2,6 +2,7 @@ import { processSequence, resolveAssetUrl, ASSET_SLOTS } from "./processors/sequ
 import { processGroups } from "./processors/groups.js";
 import { buildDoc } from "./builders/doc.js";
 import { lintContent } from "./lint.js";
+import { MIME_TYPES, mimeFor } from "./utils/mime.js";
 
 /**
  * Parse ProseMirror/TipTap content into semantic structure
@@ -54,4 +55,6 @@ function parseContent(doc, options = {}) {
 // `lintContent` diagnoses grouping near-misses (see src/lint.js). It never
 // affects a parse — parsing stays deterministic; the judgment lives here so
 // the CLI, the dev server, and an editor surface the same findings.
-export { parseContent, buildDoc, resolveAssetUrl, ASSET_SLOTS, lintContent };
+// `MIME_TYPES` / `mimeFor` are the one extension → media-type table: a document's
+// `mime` here, a file's in the build (src/utils/mime.js).
+export { parseContent, buildDoc, resolveAssetUrl, ASSET_SLOTS, lintContent, MIME_TYPES, mimeFor };

package/src/processors/groups.js

@@ -15,7 +15,9 @@ function flattenGroup(group) {
         icons: group.body.icons || [],
         lists: group.body.lists || [],
         videos: group.body.videos || [],
+        documents: group.body.documents || [],
         insets: group.body.insets || [],
+        media: group.body.media || [],
         snippets: group.body.snippets || [],
         data: group.body.data || {},
         quotes: group.body.quotes || [],
@@ -68,6 +70,7 @@ function processGroups(sequence, options = {}) {
             lists: [],
             videos: [],
             insets: [],
+            media: [],
             snippets: [],
             data: {},
             quotes: [],
@@ -112,6 +115,7 @@ function processGroups(sequence, options = {}) {
         lists: [],
         videos: [],
         insets: [],
+        media: [],
         data: {},
         quotes: [],
         headings: [],
@@ -303,7 +307,15 @@ function processGroupContent(elements, options = {}) {
         images: [],
         icons: [],
         videos: [],
+        documents: [],
         insets: [],
+        // ⭐ The group's visual media — each block-level image, video and inset, in the
+        // order written, tagged with its `kind`: what a media slot holds. `images`,
+        // `videos` and `insets` keep what they hold, and keep the author's order only
+        // within one kind; across kinds only this does (and `sequence`). An image
+        // inside a sentence belongs to the text, so it is not here — nor is a
+        // document, which is not visual media.
+        media: [],
         snippets: [],
         paragraphs: [],
         links: [],
@@ -380,11 +392,17 @@ function processGroupContent(elements, options = {}) {
                         body.icons.push(element.attrs);
                     } else {
                         body.images.push(preserveProps);
+                        body.media.push({ ...preserveProps, kind: "image" });
                     }
                     break;
 
                 case "video":
                     body.videos.push(preserveProps);
+                    body.media.push({ ...preserveProps, kind: "video" });
+                    break;
+
+                case "document":
+                    body.documents.push(preserveProps);
                     break;
 
                 case "link":
@@ -493,6 +511,7 @@ function processGroupContent(elements, options = {}) {
 
                 case "inset":
                     body.insets.push({ refId: element.refId });
+                    body.media.push({ refId: element.refId, kind: "inset" });
                     break;
 
                 case "form":
@@ -520,19 +539,6 @@ function processGroupContent(elements, options = {}) {
                     });
                     break;
 
-                case "document-group":
-                    // Map documents to links with role=document
-                    element.documents.forEach(doc => {
-                        body.links.push({
-                            href: doc.href || doc.downloadUrl || '',
-                            label: doc.title || '',
-                            role: 'document',
-                            download: true,
-                            preview: doc.coverImg,
-                            fileType: doc.fileType,
-                        });
-                    });
-                    break;
             }
         }
     }
@@ -588,6 +594,9 @@ function processInlineElements(children, body) {
             // `{role=video}` belongs in videos[] for the same reason a hoisted
             // one does.
             body.videos.push(item.attrs);
+        } else if (item.type === "document") {
+            // And an inline `{role=pdf}` in documents[].
+            body.documents.push(item.attrs);
         } else if (item.type === "link") {
             // Handle inline links extracted from paragraph text nodes
             body.links.push(item.attrs);

package/src/processors/sequence.js

@@ -1,3 +1,5 @@
+import { mimeFor, fileNameOf } from "../utils/mime.js";
+
 /**
  * HTML-attribute encoding for values placed inside double-quoted
  * attributes. Backslashes and braces (common in LaTeX) pass through
@@ -210,7 +212,19 @@ function createSequenceElement(node, options = {}) {
         case "image":
             // `role` decides which content array this lands in — the contract
             // published in docs/reference/content-structure.md ("Media Assets"):
-            // icon → icons, video → videos, everything else → images.
+            // icon → icons, video → videos, pdf → documents, everything else →
+            // images.
+            //
+            // A document is stored as this node, as a video is, and delivered as
+            // a kind of its own (`parseMarkdownDocument`). Until 2026-09-29 it
+            // landed in `images`, drawn as an image of the file, while the
+            // runtime had guaranteed an empty `content.documents` since January.
+            if (attrs?.role === "pdf") {
+                return {
+                    type: "document",
+                    attrs: parseMarkdownDocument(attrs, options),
+                };
+            }
             //
             // The video branch was missing until 2026-07-30: every
             // `{role=video}` node ran parseImgBlock, which does not carry
@@ -315,13 +329,16 @@ function createSequenceElement(node, options = {}) {
             };
 
         case "document-group":
-            return {
-                type: "document-group",
-                documents:
-                    node.content
-                        ?.filter((c) => c.type === "document")
-                        .map((doc) => parseDocumentBlock(doc.attrs)) || [],
-            };
+            // The editor's older container: one `document` element per document
+            // it holds, so a document is one kind of content whichever node
+            // wrote it (`documentFromEditorNode`). Until 2026-09-29 this was a
+            // `document-group` element whose documents became `content.links`.
+            return (node.content || [])
+                .filter((c) => c.type === "document")
+                .map((doc) => ({
+                    type: "document",
+                    attrs: documentFromEditorNode(doc.attrs),
+                }));
 
         // The editor renamed this node to `StructuredContent` (2026-07-31,
         // editor-internal). Both are accepted: the new name is what the editor
@@ -613,13 +630,15 @@ function processInlineElements(content, options = {}) {
             // image silently deleted. groups.js has carried the receiving
             // branch (and a comment describing exactly this failure) since it
             // was written, but nothing ever emitted the item it reads.
-            const isVideo = item.attrs?.role === "video";
-            items.push({
-                type: isVideo ? "video" : "image",
-                attrs: isVideo
-                    ? parseMarkdownVideo(item.attrs, options)
-                    : parseImgBlock(item.attrs || {}, options),
-            });
+            // The role partitions it as the block case does.
+            const role = item.attrs?.role;
+            if (role === "video") {
+                items.push({ type: "video", attrs: parseMarkdownVideo(item.attrs, options) });
+            } else if (role === "pdf") {
+                items.push({ type: "document", attrs: parseMarkdownDocument(item.attrs, options) });
+            } else {
+                items.push({ type: "image", attrs: parseImgBlock(item.attrs || {}, options) });
+            }
         } else if (item.type === "math-inline" || item.type === "math_inline") {
             items.push(item);
         } else if (item.type === "inset_placeholder") {
@@ -802,6 +821,76 @@ function parseCardBlock(itemAttrs) {
     };
 }
 
+// A document authored in markdown: `![Annual report](./report.pdf){role=pdf …}`.
+//
+// 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.
+function parseMarkdownDocument(itemAttrs, options) {
+    const { url, alt, caption, role, href, target, id, preview, author, description } =
+        parseImgBlock(itemAttrs || {}, options);
+    return {
+        url,
+        ...fileFacts(url, itemAttrs),
+        alt,
+        caption,
+        role,
+        ...(href && { href }),
+        ...(target && { target }),
+        ...(id && { id }),
+        ...(preview && { preview }),
+        ...(author && { author }),
+        ...(description && { description }),
+    };
+}
+
+/**
+ * A document's file, as a file record's value names it: `name` (the file's name) and
+ * `mime` from its address, and `size` — known only where the file is — when a
+ * producer stamped one. A stamped `name` or `mime` wins over the address: the build
+ * copies a local file under a hashed name, so it stamps the one the author gave it.
+ * ✅ The field names are a file record's [Diego, 2026-09-29], so one component can
+ * render a downloads list from either.
+ */
+function fileFacts(url, attrs = {}) {
+    const name = typeof attrs?.name === "string" && attrs.name ? attrs.name : fileNameOf(url);
+    const mime = typeof attrs?.mime === "string" && attrs.mime ? attrs.mime : name ? mimeFor(name) : "";
+    const size = Number.isFinite(attrs?.size) ? attrs.size : null;
+    return {
+        ...(name && { name }),
+        ...(mime && { mime }),
+        ...(size !== null && { size }),
+    };
+}
+
+// The editor's older `document` node — its `title`, `coverImg` and `src` (or
+// asset identifier) — read into the same shape a markdown document has.
+function documentFromEditorNode(itemAttrs) {
+    const {
+        href,
+        downloadUrl,
+        title = "",
+        alt = "",
+        coverImg,
+        author,
+        description,
+        fileType,
+    } = parseDocumentBlock(itemAttrs || {});
+    const url = href || downloadUrl || "";
+    return {
+        url,
+        ...fileFacts(url, itemAttrs),
+        alt: alt || title,
+        caption: title,
+        role: "pdf",
+        ...(coverImg && { preview: coverImg }),
+        ...(author && { author }),
+        ...(description && { description }),
+        ...(fileType && { fileType }),
+    };
+}
+
 function parseDocumentBlock(itemAttrs) {
     const { src, info = {}, coverImg = null, ...others } = itemAttrs;
 

package/src/utils/mime.js

@@ -0,0 +1,90 @@
+/**
+ * What a file is, by its extension — the one extension → media-type table.
+ *
+ * ⭐ ONE TABLE, HERE, because two producers need it and this is the package both can
+ * reach: the parser gives a document its `mime` from its address, and the build gives
+ * a file record — and a document file it copies — theirs (`@uniweb/build`'s
+ * `site/file-records.js` imports `mimeFor` from here, as it imports `ASSET_SLOTS`).
+ * The parser has no dependencies, so the table cannot live in the build and be
+ * reached from here. ⛔ Do not write a second.
+ *
+ * Anything not here is `application/octet-stream`.
+ */
+export const MIME_TYPES = {
+    pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ppt: "application/vnd.ms-powerpoint",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    odt: "application/vnd.oasis.opendocument.text",
+    ods: "application/vnd.oasis.opendocument.spreadsheet",
+    odp: "application/vnd.oasis.opendocument.presentation",
+    rtf: "application/rtf",
+    epub: "application/epub+zip",
+    zip: "application/zip",
+    gz: "application/gzip",
+    tar: "application/x-tar",
+    csv: "text/csv",
+    tsv: "text/tab-separated-values",
+    txt: "text/plain",
+    md: "text/markdown",
+    json: "application/json",
+    xml: "application/xml",
+    yml: "application/yaml",
+    yaml: "application/yaml",
+    html: "text/html",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    svg: "image/svg+xml",
+    webp: "image/webp",
+    avif: "image/avif",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+    m4a: "audio/mp4",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mov: "video/quicktime",
+};
+
+/**
+ * The extension of a file name or path, lower-cased, without its dot — `''` for none,
+ * and for a dotfile (`.env`), as Node's `extname` reads them.
+ */
+function extensionOf(name) {
+    const base = String(name || "").split(/[\\/]/).pop();
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
+}
+
+/**
+ * The media type of a file, by its extension.
+ *
+ * @param {string} name - a file name or path
+ * @returns {string}
+ */
+export function mimeFor(name) {
+    return MIME_TYPES[extensionOf(name)] || "application/octet-stream";
+}
+
+/**
+ * The file name an address ends in — `/files/Annual%20report.pdf?v=2` →
+ * `Annual report.pdf` — or `''` when it names none.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export function fileNameOf(url) {
+    const text = String(url || "");
+    if (/^data:/i.test(text)) return "";
+    const segment = text.split(/[?#]/)[0].split("/").pop() || "";
+    try {
+        return decodeURIComponent(segment);
+    } catch {
+        return segment;
+    }
+}