@uniweb/semantic-parser 1.1.8 → 1.1.10

package/AGENTS.md

@@ -95,12 +95,15 @@ The `data` object holds all structured content:
 data: {
   "nav-links": [...],     // From ```yaml:nav-links
   "config": {...},        // From ```yaml:config
-  "form": {...},          // From FormBlock editor widget or ```yaml:form
+  "stats": [...],         // From FormBlock (activeSchemaId='stats') or ```yaml:stats
   "person": [...],        // From card-group with cardType="person"
   "event": [...]          // From card-group with cardType="event"
 }
 ```
 
+FormBlock data is routed to `data[activeSchemaId]`. A legacy
+FormBlock without a `schemaId` still lands at `data.form`.
+
 ### Main Content Identification
 
 The `identifyMainContent()` function (src/processors/groups.js:282) determines if the first group should be treated as main content:
@@ -121,7 +124,7 @@ The sequence processor identifies several special element types by inspecting pa
 
 Editor-specific nodes are mapped to standard entities:
 - `button` node → `links[]` with `role: "button"` and `variant` attribute
-- `FormBlock` → `data.form`
+- `FormBlock` → `data[activeSchemaId]` (fallback: `data.form` when no schemaId)
 - `card-group` → `data[cardType]` arrays (e.g., `data.person`, `data.event`)
 - `document-group` → `links[]` with `role: "document"` and `download: true`
 

package/README.md

@@ -77,13 +77,18 @@ result = {
   icons: [],
   lists: [],
   quotes: [],
+  insets: [],               // Inline @Component references — { refId }
+  snippets: [],             // Fenced code blocks — { language, code }
   data: {},                 // Structured data (tagged data blocks, forms, cards)
   headings: [],             // Headings after subtitle, in document order
 
   // Additional content groups (from headings after content)
+  // Each item has the SAME flat structure as the top level — title,
+  // pretitle, subtitle, paragraphs, links, images, icons, lists,
+  // snippets, data, etc. Use this for cards, features, FAQ entries.
   items: [
-    { title: "Feature 1", paragraphs: [...], links: [...] },
-    { title: "Feature 2", paragraphs: [...], links: [...] }
+    { title: "Feature 1", paragraphs: [...], links: [...], /* ...full shape */ },
+    { title: "Feature 2", paragraphs: [...], links: [...], /* ...full shape */ }
   ],
 
   // Ordered sequence for document-order rendering
@@ -144,28 +149,53 @@ sequence.forEach(element => {
 
 ## Content Grouping
 
-The parser supports two grouping modes:
+The parser interprets heading levels **relatively**, not absolutely. There is no requirement that a section start with H1 — what matters is the relationship *between* headings (which is more important, which is deeper, which comes after body content). Starting at H1 is natural and recommended, but the same structure works starting at H2 or H3 — every rule below is about relative levels.
 
-### Heading-Based Grouping (Default)
+### How groups are formed
 
-Groups are created based on heading patterns. A new group starts when:
-- A heading follows content
-- Multiple H1s appear (no main content created)
-- The heading level indicates a new section
+A new group is started whenever a heading appears after non-heading content (paragraphs, images, links, lists, etc.). A horizontal rule (`---`) explicitly closes the current group.
 
-**Heading group formation:** Consecutive headings are consumed as a single semantic unit only when each subsequent heading is _exactly one level deeper_ than the previous (e.g., H1→H2→H3). Skipping levels (H1→H3) breaks the group — the deeper heading starts a new group instead of becoming a subtitle. This reflects natural document structure: a large level gap signals items, not a title-subtitle pair.
+When a group begins with one or more headings, the parser consumes a contiguous **heading block** following these rules:
 
-**Pretitle Detection:** Any heading followed by a more important heading is automatically detected as a pretitle:
-- H3 before H1 → pretitle ✅
-- H2 before H1 → pretitle ✅
-- H6 before H5 → pretitle ✅
-- H4 before H2 → pretitle ✅
+1. **Adjacent deeper** — the next heading is exactly one level deeper (e.g., H1→H2, H2→H3). It becomes the `subtitle`. Skipping levels (H1→H3) breaks the block; the deeper heading starts a new group as an item.
+2. **Pretitle promotion** — if the very first heading is followed by a *more important* (lower-numbered) heading, the first one becomes `pretitle` and the next becomes `title`. This only applies at the start of the block.
+3. **Same-level continuation** — consecutive headings at the same level merge into an array (multi-line title or subtitle). This stops once a deeper level has been reached: after going deeper, a same-level heading starts a new group instead of merging.
 
-No configuration needed - it just works naturally!
+Anything else (going back up after going deeper, or any other gap) breaks the block.
 
-### Divider-Based Grouping
+### Main content vs items
 
-When any horizontal rule (`---`) is present, the entire document uses divider-based grouping. Groups are split explicitly by dividers.
+Once groups are split, the parser decides whether the first group is the section's main content or whether *all* groups should be treated as items. The first group becomes main content when **either**:
+
+- It has no heading at all (body content appearing before the first heading), **or**
+- Its heading level is more important (lower-numbered) than the second group's heading level.
+
+Otherwise, every group becomes an item and the top-level header fields stay empty. For example, a document that starts with `## Card A` followed by `## Card B` produces two items and no main title — because the first group is not more important than the second. The same is true for two H1s in a row, or two H3s; the rule is about *relative* importance, not a specific level.
+
+This is the mechanism that creates repeating content groups (cards, features, FAQ entries) without any extra configuration.
+
+### Pretitle detection
+
+A heading followed by a more important heading at the start of a group is detected as `pretitle`:
+
+- H3 before H1 → pretitle
+- H2 before H1 → pretitle
+- H6 before H5 → pretitle
+- H4 before H2 → pretitle
+
+Pretitle is detected only between the first two headings of a heading block (before the title is set).
+
+### Banner image
+
+If a section's very first element is an image (or an image followed immediately by a heading), the parser keeps the image and the following heading in the same group rather than splitting them. This lets a leading image act as a banner for the section's title without becoming an unrelated item.
+
+### Divider-based grouping
+
+A horizontal rule (`---`) explicitly closes the current group and starts a new one. Dividers compose with the heading rules above — they don't replace them — and are useful in three situations:
+
+- **Resolving ambiguity.** When the heading rules would group content one way but you want it grouped another way. Most common case: forcing items without a subtitle. Without a divider, `# Our Stats` followed by `## 15,000+` makes `## 15,000+` the subtitle (one level deeper). Adding `---` between them closes the title group so `## 15,000+` becomes `items[0].title` instead.
+- **Forcing splits within same-level runs.** Same-level headings that would otherwise merge into a multi-line title/subtitle become separate groups when separated by a divider.
+- **Personal preference.** Even when the heading rules would already produce the desired structure, authors can use `---` as an explicit visual separator between groups. It never changes a structure that's already correct — it just makes the boundary obvious in the markdown source.
 
 ## Text Formatting
 

package/package.json

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

package/src/processors/groups.js

@@ -364,17 +364,10 @@ function processGroupContent(elements) {
                     break;
 
                 case "codeBlock":
-                    const tag = element.attrs?.tag;
-                    if (tag) {
-                        // Tagged block where parsing failed at build time — store as data
-                        body.data[tag] = element.text;
-                    } else {
-                        // Untagged code block — collect as a snippet
-                        body.snippets.push({
-                            language: element.attrs?.language || '',
-                            code: typeof element.text === 'string' ? element.text : '',
-                        });
-                    }
+                    body.snippets.push({
+                        language: element.attrs?.language || '',
+                        code: typeof element.text === 'string' ? element.text : '',
+                    });
                     break;
 
                 case "inset":
@@ -382,8 +375,16 @@ function processGroupContent(elements) {
                     break;
 
                 case "form":
-                    // Map FormBlock to data.form
-                    body.data.form = element.data || element.attrs;
+                    // Route FormBlock data by the schema id it targets, so it
+                    // shares a namespace with tagged markdown data blocks
+                    // (```yaml:<id>``` also lands at data[<id>]). When no
+                    // schemaId is present (legacy content), fall back to the
+                    // literal key "form" — eventual deprecation.
+                    {
+                        const payload = element.data || element.attrs;
+                        const key = element.schemaId || "form";
+                        body.data[key] = payload;
+                    }
                     break;
 
                 case "card-group":

package/src/processors/sequence.js

@@ -145,13 +145,22 @@ function createSequenceElement(node, options = {}) {
                 tag: attrs.tag,
             };
 
-        case "codeBlock":
+        case "codeBlock": {
             const codeText = getTextContent(content, options);
+            // Tagged code blocks are semantically data blocks, not code
+            if (attrs?.tag) {
+                return {
+                    type: "dataBlock",
+                    tag: attrs.tag,
+                    data: getCodeBlockData(codeText, attrs),
+                };
+            }
             return {
                 type: "codeBlock",
-                text: getCodeBlockData(codeText, attrs),
+                text: codeText,
                 attrs,
             };
+        }
 
         case "inset_placeholder":
             return {
@@ -232,6 +241,7 @@ function createSequenceElement(node, options = {}) {
 
             return {
                 type: "form",
+                schemaId: attrs?.activeSchemaId || null,
                 data: formData,
                 attrs,
             };