@uniweb/semantic-parser 1.0.10 → 1.0.11

package/AGENTS.md

@@ -61,17 +61,43 @@ The parser returns a flat content structure:
   title: '',       // Main heading
   pretitle: '',    // Heading before main title
   subtitle: '',    // Heading after main title
+  subtitle2: '',   // Third heading level
   paragraphs: [],
-  links: [],
+  links: [],       // All link-like entities (including buttons, documents)
   imgs: [],
   icons: [],
   videos: [],
   lists: [],
-  buttons: [],
-  data: {},        // Tagged code blocks (keyed by tag name)
-  cards: [],
-  headings: [],
-  items: [],       // Child content groups
+  quotes: [],
+  data: {},        // Structured data (tagged code blocks, forms, cards)
+  headings: [],    // Overflow headings after title/subtitle/subtitle2
+  items: [],       // Child content groups (same structure recursively)
+}
+```
+
+### Link Roles
+
+Links include buttons and documents, distinguished by `role`:
+
+```js
+links: [
+  { href: "/page", label: "Learn More", role: "link" },
+  { href: "/action", label: "Get Started", role: "button", variant: "primary" },
+  { href: "/file.pdf", label: "Download", role: "document", download: true },
+]
+```
+
+### Structured Data
+
+The `data` object holds all structured content:
+
+```js
+data: {
+  "nav-links": [...],     // From ```json:nav-links or ```yaml:nav-links
+  "config": {...},        // From ```yaml:config
+  "form": {...},          // From FormBlock editor widget
+  "person": [...],        // From card-group with cardType="person"
+  "event": [...]          // From card-group with cardType="event"
 }
 ```
 
@@ -88,10 +114,18 @@ The sequence processor identifies several special element types by inspecting pa
 - **Links**: Paragraphs containing only a single link mark
 - **Images**: Paragraphs with single image (role: 'image' or 'banner')
 - **Icons**: Paragraphs with single image (role: 'icon')
-- **Buttons**: Paragraphs with single text node having button mark
+- **Buttons**: Editor `button` nodes → mapped to links with `role: "button"`
 - **Videos**: Paragraphs with single image (role: 'video')
 
-These are extracted into dedicated element types for easier downstream processing.
+### Editor Node Mappings
+
+Editor-specific nodes are mapped to standard entities:
+- `button` node → `links[]` with `role: "button"` and `variant` attribute
+- `FormBlock` → `data.form`
+- `card-group` → `data[cardType]` arrays (e.g., `data.person`, `data.event`)
+- `document-group` → `links[]` with `role: "document"` and `download: true`
+
+See `docs/entity-consolidation.md` for complete mapping documentation.
 
 ### Tagged Code Blocks
 

package/README.md

@@ -64,19 +64,22 @@ Main content fields are at the top level. The `items` array contains additional
 
 ```js
 result = {
-  // Main content fields
+  // Header fields (from headings)
   pretitle: "",             // Heading before main title
   title: "Welcome",         // Main heading
   subtitle: "",             // Heading after main title
+  subtitle2: "",            // Third heading level
+
+  // Body fields
   paragraphs: ["Get started today."],
+  links: [],                // All links (including buttons, documents)
   imgs: [],
   videos: [],
-  links: [],
-  lists: [],
   icons: [],
-  buttons: [],
-  banner: null,             // Optional banner image
-  // ... more content types
+  lists: [],
+  quotes: [],
+  data: {},                 // Structured data (tagged code blocks, forms, cards)
+  headings: [],             // Overflow headings after title/subtitle/subtitle2
 
   // Additional content groups (from headings after content)
   items: [

package/docs/entity-consolidation.md

@@ -0,0 +1,467 @@
+# Semantic Parser Entity Consolidation
+
+This document defines the standard semantic entities output by the parser and how editor-specific node types map to them.
+
+## Design Principle
+
+**Editor nodes are authoring conveniences → Parser outputs standardized semantic entities**
+
+The semantic parser accepts ProseMirror/TipTap documents from two sources:
+1. **File-based markdown** via `@uniweb/content-reader`
+2. **Visual editor** via TipTap with custom node types
+
+Both sources must produce the same standardized output. Editor-specific node types (like `card-group`, `FormBlock`, `button` node) are conveniences that map to standard entities.
+
+---
+
+## Standard Entity Set
+
+After consolidation, the parser outputs this flat structure:
+
+```js
+{
+    // Header fields (from headings)
+    title: '',
+    pretitle: '',
+    subtitle: '',
+    subtitle2: '',
+
+    // Body fields
+    paragraphs: [],    // Text blocks with inline HTML formatting
+    links: [],         // All link-like entities (buttons, documents, nav links)
+    imgs: [],          // All images (with role distinguishing purpose)
+    videos: [],        // Video embeds
+    icons: [],         // Standalone icons
+    lists: [],         // Bullet/ordered lists (recursive structure)
+    quotes: [],        // Blockquotes (recursive structure)
+    data: {},          // Structured data (tagged code blocks, forms, cards)
+    headings: [],      // Overflow headings after title/subtitle/subtitle2
+
+    items: [],         // Semantic groups (same structure recursively)
+}
+```
+
+### Removed Fields
+
+| Field | Status | Reason |
+|-------|--------|--------|
+| `alignment` | **Deprecated** | Editor-only concept, not expressible in markdown |
+| `buttons` | **Merged into `links`** | Buttons are styled links |
+| `cards` | **Merged into `data`** | Structured data with schema tag |
+| `documents` | **Merged into `links`** | Documents are downloadable links |
+| `forms` | **Merged into `data`** | Structured data with `form` tag |
+
+---
+
+## Entity Specifications
+
+### Links
+
+All link-like content merges into the `links` array. The `role` attribute distinguishes behavior.
+
+```js
+{
+    href: "/contact",
+    label: "Contact Us",
+
+    // Role distinguishes link type
+    role: "link",           // Default: standard hyperlink
+         | "button"         // Call-to-action button
+         | "button-primary" // Primary CTA
+         | "button-outline" // Outline style button
+         | "nav-link"       // Navigation link
+         | "footer-link"    // Footer navigation
+         | "document"       // Downloadable file
+
+    // Button-specific attributes (when role is button-*)
+    variant: "primary" | "secondary" | "outline" | "ghost",
+    size: "sm" | "md" | "lg",
+    icon: "icon-name",
+
+    // Link behavior
+    target: "_blank" | "_self",
+    rel: "noopener noreferrer",
+    download: true | "filename.pdf",
+}
+```
+
+**Markdown syntax:**
+```markdown
+[Standard link](/page)
+[Button link](button:/action){variant=primary}
+[Download](report.pdf){download}
+```
+
+### Images
+
+All image content uses the `imgs` array. The `role` attribute distinguishes purpose.
+
+```js
+{
+    url: "/images/hero.jpg",
+    alt: "Hero image",
+    caption: "Optional caption",
+
+    // Role distinguishes image purpose
+    role: "image",      // Default: content image
+         | "icon"       // Small icon/logo
+         | "background" // Section background
+         | "gallery"    // Gallery item
+         | "banner"     // Hero/banner image
+
+    // Layout attributes
+    direction: "left" | "right" | "center",
+    size: "basic" | "lg" | "full",
+
+    // Styling
+    filter: "grayscale" | "blur",
+    theme: "light" | "dark",
+
+    // Link wrapper (clickable image)
+    href: "/link-target",
+}
+```
+
+### Data (Structured Content)
+
+The `data` object holds all structured content from tagged code blocks and editor widgets.
+
+```js
+{
+    // From tagged code blocks
+    "form": { fields: [...], submitLabel: "Send" },
+    "nav-links": [{ label: "Home", href: "/" }],
+    "config": { theme: "dark" },
+
+    // From editor card widgets (mapped by type)
+    "person": [
+        { name: "John", title: "CEO", ... },
+        { name: "Jane", title: "CTO", ... },
+    ],
+    "event": [
+        { title: "Launch Party", date: "2024-01-15", location: "NYC", ... },
+    ],
+}
+```
+
+**Markdown syntax for structured data:**
+```markdown
+```yaml:form
+fields:
+  - name: email
+    type: email
+    required: true
+submitLabel: Subscribe
+```
+
+```json:nav-links
+[{ "label": "Home", "href": "/" }]
+```
+```
+
+---
+
+## Editor Node Mappings
+
+This section documents how TipTap/editor-specific nodes map to standard entities.
+
+### `button` Node → `links[]`
+
+**Editor input:**
+```js
+{
+    type: "button",
+    content: [{ type: "text", text: "Click me" }],
+    attrs: {
+        href: "/action",
+        variant: "primary",
+        size: "lg",
+        icon: "arrow-right"
+    }
+}
+```
+
+**Standard output:**
+```js
+links: [{
+    href: "/action",
+    label: "Click me",
+    role: "button",
+    variant: "primary",
+    size: "lg",
+    icon: "arrow-right"
+}]
+```
+
+### `FormBlock` Node → `data.form`
+
+**Editor input:**
+```js
+{
+    type: "FormBlock",
+    attrs: {
+        data: {
+            fields: [{ name: "email", type: "email" }],
+            submitLabel: "Subscribe"
+        }
+    }
+}
+```
+
+**Standard output:**
+```js
+data: {
+    form: {
+        fields: [{ name: "email", type: "email" }],
+        submitLabel: "Subscribe"
+    }
+}
+```
+
+### `card-group` Node → `data[cardType]`
+
+Cards are editor widgets for structured entities like people, events, addresses. Each card type becomes a key in `data`, with an array of all cards of that type. This follows the same pattern as tagged code blocks.
+
+**Editor input:**
+```js
+{
+    type: "card-group",
+    content: [
+        {
+            type: "card",
+            attrs: {
+                cardType: "person",
+                title: "Jane Doe",
+                subtitle: "CEO",
+                coverImg: { src: "/jane.jpg" },
+                address: '{"city": "NYC"}',
+                icon: { svg: "..." }
+            }
+        },
+        {
+            type: "card",
+            attrs: {
+                cardType: "person",
+                title: "John Smith",
+                subtitle: "CTO",
+                coverImg: { src: "/john.jpg" }
+            }
+        },
+        {
+            type: "card",
+            attrs: {
+                cardType: "event",
+                title: "Launch Party",
+                date: "2024-03-15",
+                location: "San Francisco"
+            }
+        }
+    ]
+}
+```
+
+**Standard output:**
+```js
+data: {
+    person: [
+        {
+            title: "Jane Doe",
+            subtitle: "CEO",
+            coverImg: "/jane.jpg",
+            address: { city: "NYC" },
+            icon: { svg: "..." }
+        },
+        {
+            title: "John Smith",
+            subtitle: "CTO",
+            coverImg: "/john.jpg"
+        }
+    ],
+    event: [
+        {
+            title: "Launch Party",
+            date: "2024-03-15",
+            location: "San Francisco"
+        }
+    ]
+}
+```
+
+**Accessing cards by type:**
+```js
+// Get all person cards
+const people = content.data.person || [];
+
+// Get all event cards
+const events = content.data.event || [];
+```
+
+**Card schemas:**
+| Schema | Common Fields |
+|--------|---------------|
+| `person` | title (name), subtitle (role), coverImg (photo), address |
+| `event` | title, date, location, description |
+| `address` | street, city, state, country, postal |
+| `document` | title, href, coverImg (preview), fileType |
+
+### `document-group` Node → `links[]`
+
+Documents are downloadable files. They map to links with `role: "document"`.
+
+**Editor input:**
+```js
+{
+    type: "document-group",
+    content: [
+        {
+            type: "document",
+            attrs: {
+                title: "Annual Report",
+                src: "/reports/annual-2024.pdf",
+                coverImg: { src: "/preview.jpg" }
+            }
+        }
+    ]
+}
+```
+
+**Standard output:**
+```js
+links: [{
+    href: "/reports/annual-2024.pdf",
+    label: "Annual Report",
+    role: "document",
+    download: true,
+    preview: "/preview.jpg"
+}]
+```
+
+---
+
+## Deprecation: `alignment`
+
+The `alignment` field was extracted from heading's `textAlign` attribute in the editor. This is an editor-specific styling concern that:
+- Cannot be expressed in file-based markdown
+- Is a presentation concern, not semantic content
+- Should be handled by component styling, not content structure
+
+**Migration:** Components relying on `content.alignment` should:
+1. Use CSS/Tailwind for text alignment
+2. Or accept alignment as a component `param` in frontmatter
+
+---
+
+## Migration Path
+
+### Phase 1: Add Mappings (Non-Breaking)
+
+1. Continue outputting legacy fields (`buttons`, `cards`, `documents`, `forms`, `alignment`)
+2. Also populate new locations (`links` for buttons/documents, `data` for cards/forms)
+3. Components can migrate gradually
+
+### Phase 2: Deprecation Warnings
+
+1. Log warnings when legacy fields are accessed
+2. Document migration for each field
+3. Provide codemod or migration script
+
+### Phase 3: Remove Legacy Fields
+
+1. Remove `buttons`, `cards`, `documents`, `forms`, `alignment` from output
+2. Update all components to use new structure
+3. Update documentation
+
+---
+
+## Backwards Compatibility
+
+During migration, the parser can provide a compatibility layer:
+
+```js
+// Parser option
+const content = parse(doc, {
+    legacyFields: true  // Include deprecated fields
+});
+
+// Or via getter that warns
+Object.defineProperty(content, 'buttons', {
+    get() {
+        console.warn('content.buttons is deprecated, use content.links with role="button"');
+        return content.links.filter(l => l.role?.startsWith('button'));
+    }
+});
+```
+
+---
+
+## Component Migration Examples
+
+### Before: Using `buttons`
+
+```jsx
+function CTA({ content }) {
+    const { links, buttons } = content;
+    return (
+        <div>
+            {links.map(link => <a href={link.href}>{link.label}</a>)}
+            {buttons.map(btn => <button>{btn.content}</button>)}
+        </div>
+    );
+}
+```
+
+### After: Unified `links`
+
+```jsx
+function CTA({ content }) {
+    const { links } = content;
+    const buttons = links.filter(l => l.role?.startsWith('button'));
+    const plainLinks = links.filter(l => !l.role?.startsWith('button'));
+
+    return (
+        <div>
+            {plainLinks.map(link => <a href={link.href}>{link.label}</a>)}
+            {buttons.map(btn => (
+                <a href={btn.href} className={`btn btn-${btn.variant}`}>
+                    {btn.label}
+                </a>
+            ))}
+        </div>
+    );
+}
+```
+
+### Or: Role-based rendering
+
+```jsx
+function CTA({ content }) {
+    return (
+        <div>
+            {content.links.map(link => {
+                if (link.role?.startsWith('button')) {
+                    return <Button variant={link.variant}>{link.label}</Button>;
+                }
+                if (link.role === 'document') {
+                    return <DownloadLink href={link.href}>{link.label}</DownloadLink>;
+                }
+                return <a href={link.href}>{link.label}</a>;
+            })}
+        </div>
+    );
+}
+```
+
+---
+
+## Implementation Checklist
+
+- [ ] Update `processGroupContent` in `groups.js` to map button → links
+- [ ] Update `processGroupContent` to map card-group → data.cards
+- [ ] Update `processGroupContent` to map document-group → links
+- [ ] Update `processGroupContent` to map FormBlock → data.form
+- [ ] Remove `alignment` from header extraction
+- [ ] Add `legacyFields` option for backwards compatibility
+- [ ] Update `flattenGroup` to use new structure
+- [ ] Update tests for new entity structure
+- [ ] Update AGENTS.md and README.md
+- [ ] Create migration guide for components

package/package.json

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

package/src/mappers/extractors.js

@@ -16,6 +16,10 @@ import { first, joinParagraphs } from "./helpers.js";
  * @returns {Object} Hero component data
  */
 function hero(parsed) {
+    const links = parsed?.links || [];
+    const buttonLink = links.find(l => l.role?.startsWith('button'));
+    const plainLink = links.find(l => !l.role?.startsWith('button'));
+
     return {
         title: parsed?.title || null,
         subtitle: parsed?.subtitle || null,
@@ -24,8 +28,7 @@ function hero(parsed) {
         image: first(parsed?.imgs)?.url || null,
         imageAlt: first(parsed?.imgs)?.alt || null,
         banner: null, // Banner detection would need to be added separately
-        cta: first(parsed?.links) || null,
-        button: first(parsed?.buttons) || null,
+        cta: buttonLink || plainLink || null,
     };
 }
 
@@ -45,6 +48,10 @@ function card(parsed, options = {}) {
     const extractCard = (content) => {
         if (!content) return null;
 
+        const links = content.links || [];
+        const buttonLink = links.find(l => l.role?.startsWith('button'));
+        const plainLink = links.find(l => !l.role?.startsWith('button'));
+
         return {
             title: content.title || null,
             subtitle: content.subtitle || null,
@@ -52,8 +59,8 @@ function card(parsed, options = {}) {
             image: first(content.imgs)?.url || null,
             imageAlt: first(content.imgs)?.alt || null,
             icon: first(content.icons) || null,
-            link: first(content.links) || null,
-            button: first(content.buttons) || null,
+            link: plainLink || null,
+            cta: buttonLink || plainLink || null,
         };
     };
 
@@ -230,6 +237,8 @@ function pricing(parsed) {
     return items
         .map((item) => {
             const firstList = first(item.lists);
+            const links = item.links || [];
+            const buttonLink = links.find(l => l.role?.startsWith('button'));
 
             return {
                 name: item.title || null,
@@ -242,7 +251,7 @@ function pricing(parsed) {
                           )
                           .filter(Boolean)
                     : [],
-                cta: first(item.links) || first(item.buttons) || null,
+                cta: buttonLink || first(links) || null,
                 highlighted:
                     item.pretitle?.toLowerCase().includes("popular") || false,
             };
@@ -314,6 +323,9 @@ function gallery(parsed, options = {}) {
  * used by the legacy Article class, enabling drop-in replacement without
  * breaking existing components.
  *
+ * NOTE: Reconstructs deprecated fields (buttons, cards, documents, forms, alignment)
+ * from the new consolidated structure for backwards compatibility.
+ *
  * @param {Object} parsed - Parsed content from parseContent() (flat structure)
  * @returns {Object} Legacy format { main, items } with nested header/body structure
  *
@@ -334,6 +346,20 @@ function legacy(parsed) {
 
         if (!banner) banner = imgs[0];
 
+        // Reconstruct deprecated fields from new structure
+        const links = content.links || [];
+        const buttons = links
+            .filter(l => l.role?.startsWith('button'))
+            .map(l => ({ attrs: l, content: l.label }));
+        const documents = links
+            .filter(l => l.role === 'document')
+            .map(l => ({ title: l.label, href: l.href, coverImg: l.preview }));
+        const plainLinks = links.filter(l => !l.role?.startsWith('button') && l.role !== 'document');
+
+        const cards = content.data?.cards || [];
+        const form = content.data?.form || null;
+        const forms = form ? [form] : [];
+
         return {
             header: {
                 title: content.title || "",
@@ -345,7 +371,7 @@ function legacy(parsed) {
                     content.subtitle2 ||
                     first(content.paragraphs) ||
                     "",
-                alignment: content.alignment || "",
+                alignment: "", // Deprecated: always empty
             },
             banner,
             body: {
@@ -354,16 +380,16 @@ function legacy(parsed) {
                 imgs,
                 videos: content.videos || [],
                 lists: content.lists || [],
-                links: content.links || [],
+                links: plainLinks,
                 icons: content.icons || [],
-                buttons: content.buttons || [],
-                cards: content.cards || [],
-                documents: content.documents || [],
-                forms: content.forms || [],
-                form: first(content.forms) || null,
+                buttons,
+                cards,
+                documents,
+                forms,
+                form,
                 quotes: content.quotes || [],
-                properties: content.properties || {},
-                propertyBlocks: content.propertyBlocks || [],
+                properties: content.data || {},
+                propertyBlocks: [],
             },
         };
     };

package/src/processors/groups.js

@@ -10,18 +10,13 @@ function flattenGroup(group) {
         pretitle: group.header.pretitle || '',
         subtitle: group.header.subtitle || '',
         subtitle2: group.header.subtitle2 || '',
-        alignment: group.header.alignment || null,
         paragraphs: group.body.paragraphs || [],
         links: group.body.links || [],
         imgs: group.body.imgs || [],
         icons: group.body.icons || [],
         lists: group.body.lists || [],
         videos: group.body.videos || [],
-        buttons: group.body.buttons || [],
         data: group.body.data || {},
-        cards: group.body.cards || [],
-        documents: group.body.documents || [],
-        forms: group.body.forms || [],
         quotes: group.body.quotes || [],
         headings: group.body.headings || [],
     };
@@ -41,18 +36,13 @@ function processGroups(sequence, options = {}) {
             pretitle: '',
             subtitle: '',
             subtitle2: '',
-            alignment: null,
             paragraphs: [],
             links: [],
             imgs: [],
             icons: [],
             lists: [],
             videos: [],
-            buttons: [],
             data: {},
-            cards: [],
-            documents: [],
-            forms: [],
             quotes: [],
             headings: [],
             items: [],
@@ -82,18 +72,13 @@ function processGroups(sequence, options = {}) {
         pretitle: '',
         subtitle: '',
         subtitle2: '',
-        alignment: null,
         paragraphs: [],
         links: [],
         imgs: [],
         icons: [],
         lists: [],
         videos: [],
-        buttons: [],
         data: {},
-        cards: [],
-        documents: [],
-        forms: [],
         quotes: [],
         headings: [],
     };
@@ -225,7 +210,6 @@ function processGroupContent(elements) {
         title: "",
         subtitle: "",
         subtitle2: "",
-        alignment: null,
     };
 
     const body = {
@@ -235,11 +219,7 @@ function processGroupContent(elements) {
         paragraphs: [],
         links: [],
         lists: [],
-        buttons: [],
         data: {},
-        cards: [],
-        documents: [],
-        forms: [],
         quotes: [],
         headings: [],
     };
@@ -272,10 +252,6 @@ function processGroupContent(elements) {
             //We shuold set the group level to the highest one instead of the first one.
             metadata.level ??= element.level;
 
-            // Extract alignment from first heading
-            if (!header.alignment && element.attrs?.textAlign) {
-                header.alignment = element.attrs.textAlign;
-            }
             // h3 h2 h1 h1
             // Assign to header fields
             // h3 h2 h3 h4
@@ -329,9 +305,16 @@ function processGroupContent(elements) {
                     break;
 
                 case "button":
-                    body.buttons.push({
-                        attrs: element.attrs,
-                        content: element.text,
+                    // Map button to link with role
+                    body.links.push({
+                        href: element.attrs?.href || '',
+                        label: element.text || '',
+                        role: element.attrs?.variant ? `button-${element.attrs.variant}` : 'button',
+                        variant: element.attrs?.variant || 'primary',
+                        size: element.attrs?.size,
+                        icon: element.attrs?.icon,
+                        target: element.attrs?.target,
+                        class: element.attrs?.class,
                     });
                     break;
 
@@ -356,15 +339,34 @@ function processGroupContent(elements) {
                     break;
 
                 case "form":
-                    body.forms.push(element.data || element.attrs);
+                    // Map FormBlock to data.form
+                    body.data.form = element.data || element.attrs;
                     break;
 
                 case "card-group":
-                    body.cards.push(...element.cards);
+                    // Map cards to data by type: data.person = [...], data.event = [...]
+                    // Each card type becomes a key, with an array of cards of that type
+                    (element.cards || []).forEach(card => {
+                        const cardType = card.cardType || 'card';
+                        if (!body.data[cardType]) body.data[cardType] = [];
+                        // Remove cardType from the card object since it's now the key
+                        const { cardType: _, ...cardData } = card;
+                        body.data[cardType].push(cardData);
+                    });
                     break;
 
                 case "document-group":
-                    body.documents.push(...element.documents);
+                    // 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;
             }
         }