@uniweb/semantic-parser 1.1.5 → 1.1.6

package/AGENTS.md

@@ -61,7 +61,6 @@ 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: [],       // All link-like entities (including buttons, documents)
   images: [],
@@ -71,7 +70,7 @@ The parser returns a flat content structure:
   quotes: [],
   snippets: [],    // Fenced code — [{ language, code }]
   data: {},        // Structured data (tagged data blocks, forms, cards)
-  headings: [],    // Overflow headings after title/subtitle/subtitle2
+  headings: [],    // Headings after subtitle, in document order
   items: [],       // Child content groups (same structure recursively)
 }
 ```
@@ -126,8 +125,6 @@ Editor-specific nodes are mapped to standard entities:
 - `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 Data Blocks
 
 Data blocks with tags route parsed data to the `data` object:
@@ -165,14 +162,14 @@ Lists maintain hierarchy through nested structure. The `processListItems()` func
 
 ## Content Writing Conventions
 
-The parser implements the semantic conventions documented in `docs/guide.md`. Key patterns:
+Key patterns:
 
 - **Pretitle Pattern**: Any heading followed by a more important heading (e.g., H3→H1, H2→H1, H6→H5, etc.)
 - **Banner Pattern**: Image (with banner role or followed by heading) at start of first group
 - **Divider Mode**: Presence of any `horizontalRule` switches entire document to divider-based grouping
 - **Heading Groups**: Consecutive headings with increasing levels are consumed together
 - **Main Content**: First group is main if it's the only group OR has lower heading level than second group
-- **Body Headings**: Headings that overflow the header slots (title, subtitle, subtitle2) are automatically collected in `body.headings`
+- **Body Headings**: Headings after the title and subtitle slots are collected in `body.headings` in document order
 
 ## Testing Structure
 
@@ -188,6 +185,5 @@ Tests are organized by processor:
 
 - The parser never modifies the original ProseMirror document
 - Text content can include inline HTML for formatting (bold → `<strong>`, italic → `<em>`, links → `<a>`)
-- The `processors_old/` directory contains legacy implementations - do not modify
 - Context information in byType includes position, previous/next elements, and nearest heading
 - Group splitting logic differs significantly between heading mode and divider mode

package/README.md

@@ -68,7 +68,6 @@ result = {
   pretitle: "",             // Heading before main title
   title: "Welcome",         // Main heading
   subtitle: "",             // Heading after main title
-  subtitle2: "",            // Third heading level
 
   // Body fields
   paragraphs: ["Get started today."],
@@ -78,8 +77,8 @@ result = {
   icons: [],
   lists: [],
   quotes: [],
-  data: {},                 // Structured data (tagged code blocks, forms, cards)
-  headings: [],             // Overflow headings after title/subtitle/subtitle2
+  data: {},                 // Structured data (tagged data blocks, forms, cards)
+  headings: [],             // Headings after subtitle, in document order
 
   // Additional content groups (from headings after content)
   items: [
@@ -143,154 +142,6 @@ sequence.forEach(element => {
 });
 ```
 
-## Content Mapping Utilities
-
-The parser includes optional mapping utilities to transform parsed content into component-specific formats. Perfect for visual editors and component-based systems.
-
-### Type System (Recommended)
-
-Automatically transform content based on field types with context-aware behavior:
-
-```js
-const schema = {
-  title: {
-    path: "title",
-    type: "plaintext",  // Auto-strips <strong>, <em>, etc.
-    maxLength: 60       // Auto-truncates intelligently
-  },
-  excerpt: {
-    path: "paragraphs",
-    type: "excerpt",    // Auto-creates excerpt from paragraphs
-    maxLength: 150
-  },
-  image: {
-    path: "images[0].url",
-    type: "image",
-    defaultValue: "/placeholder.jpg"
-  }
-};
-
-// Visual editor mode (default) - silent, graceful cleanup
-const data = mappers.extractBySchema(parsed, schema);
-
-// Build mode - validates and warns
-const data = mappers.extractBySchema(parsed, schema, { mode: 'build' });
-```
-
-**Field Types:** `plaintext`, `richtext`, `excerpt`, `number`, `image`, `link`
-
-### Using Pre-Built Extractors
-
-```js
-import { parseContent, mappers } from "@uniweb/semantic-parser";
-
-const parsed = parseContent(doc);
-
-// Extract hero component data
-const heroData = mappers.extractors.hero(parsed);
-// { title, subtitle, kicker, description, image, cta, ... }
-
-// Extract card data
-const cards = mappers.extractors.card(parsed, { useItems: true });
-
-// Extract statistics
-const stats = mappers.extractors.stats(parsed);
-// [{ value: "12", label: "Partner Labs" }, ...]
-
-// Extract navigation menu
-const nav = mappers.extractors.navigation(parsed);
-
-// Extract features list
-const features = mappers.extractors.features(parsed);
-```
-
-### Schema-Based Mapping
-
-Define custom mappings using schemas:
-
-```js
-const schema = {
-  brand: "pretitle",
-  title: "title",
-  subtitle: "subtitle",
-  image: {
-    path: "images[0].url",
-    defaultValue: "/placeholder.jpg"
-  },
-  actions: {
-    path: "links",
-    transform: links => links.map(l => ({ label: l.label, type: "primary" }))
-  }
-};
-
-const componentData = mappers.accessor.extractBySchema(parsed, schema);
-```
-
-### Available Extractors
-
-- `hero` - Hero/banner sections
-- `card` - Card components
-- `article` - Article/blog content
-- `stats` - Statistics/metrics
-- `navigation` - Navigation menus
-- `features` - Feature lists
-- `testimonial` - Testimonials
-- `faq` - FAQ sections
-- `pricing` - Pricing tiers
-- `team` - Team members
-- `gallery` - Image galleries
-
-See **[Mapping Patterns Guide](./docs/mapping-patterns.md)** for complete documentation.
-
-## Rendering Content
-
-After extracting content, render it using a Text component that handles paragraph arrays, rich HTML, and formatting marks.
-
-### Text Component Pattern
-
-```jsx
-import { parseContent, mappers } from '@uniweb/semantic-parser';
-import { H1, P } from './components/Text';
-
-const parsed = parseContent(doc);
-const hero = mappers.extractors.hero(parsed);
-
-// Render extracted content
-<>
-  <H1 text={hero.title} />
-  <P text={hero.description} />  {/* Handles arrays automatically */}
-</>
-```
-
-The Text component:
-- **Handles arrays** - Renders `["Para 1", "Para 2"]` as separate paragraphs
-- **Supports rich HTML** - Preserves formatting marks
-- **Multi-line headings** - Wraps multiple lines in semantic heading tags
-- **Color marks** - Supports `<mark>` and `<span>` for visual emphasis
-
-See **[Text Component Reference](./docs/text-component-reference.md)** for implementation guide.
-
-### Sanitization
-
-Sanitize content at the engine level (during data preparation), not in components:
-
-```javascript
-import { parseContent, mappers } from '@uniweb/semantic-parser';
-
-function prepareData(parsed) {
-  const hero = mappers.extractors.hero(parsed);
-  return {
-    ...hero,
-    title: mappers.types.sanitizeHtml(hero.title, {
-      allowedTags: ['strong', 'em', 'mark', 'span'],
-      allowedAttr: ['class', 'data-variant']
-    })
-  };
-}
-```
-
-The parser provides sanitization utilities but doesn't enforce their use. Your engine decides when to sanitize based on security requirements.
-
 ## Content Grouping
 
 The parser supports two grouping modes:
@@ -346,14 +197,6 @@ Bracketed spans (`[text]{.class}`) are converted to `<span>` elements with their
 
 Spans can have classes, IDs, and custom attributes. They combine with other marks—a span with bold becomes `<strong><span class="...">text</span></strong>`.
 
-## Documentation
-
-- **[Content Writing Guide](./docs/guide.md)**: Learn how to structure content for optimal parsing
-- **[API Reference](./docs/api.md)**: Complete API documentation with all element types
-- **[Mapping Patterns Guide](./docs/mapping-patterns.md)**: Transform content to component-specific formats
-- **[Text Component Reference](./docs/text-component-reference.md)**: Reference implementation for rendering parsed content
-- **[File Structure](./docs/file-structure.md)**: Codebase organization
-
 ## Use Cases
 
 - **Component-based websites**: Extract structured data for React/Vue components

package/package.json

@@ -1,13 +1,11 @@
 {
   "name": "@uniweb/semantic-parser",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Semantic parser for ProseMirror/TipTap content structures",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
-    ".": "./src/index.js",
-    "./mappers": "./src/mappers/index.js",
-    "./mappers/*": "./src/mappers/*.js"
+    ".": "./src/index.js"
   },
   "keywords": [
     "prosemirror",
@@ -30,7 +28,6 @@
   },
   "homepage": "https://github.com/uniweb/semantic-parser#readme",
   "directories": {
-    "doc": "docs",
     "test": "tests"
   },
   "dependencies": {

package/src/index.js

@@ -1,6 +1,5 @@
 import { processSequence } from "./processors/sequence.js";
 import { processGroups } from "./processors/groups.js";
-import * as mappers from "./mappers/index.js";
 
 /**
  * Parse ProseMirror/TipTap content into semantic structure
@@ -30,4 +29,4 @@ function parseContent(doc, options = {}) {
     };
 }
 
-export { parseContent, mappers };
+export { parseContent };

package/src/processors/groups.js

@@ -9,7 +9,6 @@ function flattenGroup(group) {
         title: group.header.title || '',
         pretitle: group.header.pretitle || '',
         subtitle: group.header.subtitle || '',
-        subtitle2: group.header.subtitle2 || '',
         paragraphs: group.body.paragraphs || [],
         links: group.body.links || [],
         images: group.body.images || [],
@@ -37,7 +36,6 @@ function processGroups(sequence, options = {}) {
             title: '',
             pretitle: '',
             subtitle: '',
-            subtitle2: '',
             paragraphs: [],
             links: [],
             images: [],
@@ -75,7 +73,6 @@ function processGroups(sequence, options = {}) {
         title: '',
         pretitle: '',
         subtitle: '',
-        subtitle2: '',
         paragraphs: [],
         links: [],
         images: [],
@@ -227,7 +224,6 @@ function processGroupContent(elements) {
         pretitle: "",
         title: "",
         subtitle: "",
-        subtitle2: "",
     };
 
     const body = {
@@ -290,11 +286,8 @@ function processGroupContent(elements) {
             } else if (!header.subtitle) {
                 header.subtitle = element.text;
                 lastSlot = 'subtitle';
-            } else if (!header.subtitle2) {
-                header.subtitle2 = element.text;
-                lastSlot = 'subtitle2';
             } else {
-                // After subtitle2, we're in body - collect heading
+                // After subtitle, remaining headings go to body
                 body.headings.push(element.text);
                 lastSlot = null;
             }

package/docs/api.md

@@ -1,350 +0,0 @@
-# API Reference
-
-## parseContent(doc, options)
-
-Parses a ProseMirror/TipTap document into three semantic views.
-
-### Import
-
-```js
-import { parseContent } from '@uniweb/semantic-parser';
-```
-
-### Parameters
-
-- `doc` (Object): A ProseMirror/TipTap document object with `type: "doc"` and `content` array
-- `options` (Object, optional): Parsing options
-  - `parseCodeAsJson` (boolean): Parse code blocks as JSON for properties. Default: false
-
-**Note:** Body headings are always collected automatically - no configuration needed.
-
-### Returns
-
-An object with four properties providing different views of the content:
-
-```js
-{
-  raw: Object,      // Original ProseMirror document
-  sequence: Array,  // Flat sequence of elements
-  groups: Object,   // Semantic content groups
-  byType: Object    // Elements organized by type
-}
-```
-
-## Return Value Structure
-
-### `raw`
-
-The original ProseMirror document passed as input, unchanged.
-
-### `sequence`
-
-A flat array of semantic elements extracted from the document tree.
-
-**Element Types:**
-
-```js
-// Heading
-{
-  type: "heading",
-  level: 1,              // 1-6
-  content: "Text content with <strong>HTML</strong> formatting"
-}
-
-// Paragraph
-{
-  type: "paragraph",
-  content: "Text with <em>inline</em> <a href=\"...\">formatting</a>"
-}
-
-// List
-{
-  type: "list",
-  style: "bullet" | "ordered",
-  items: [
-    {
-      content: [/* array of elements */],
-      items: [/* nested list items */]
-    }
-  ]
-}
-
-// Image
-{
-  type: "image",
-  src: "path/to/image.jpg",
-  alt: "Alt text",
-  caption: "Caption text",
-  role: "background" | "content" | "banner" | "icon"
-}
-
-// Icon (SVG)
-{
-  type: "icon",
-  svg: "<svg>...</svg>"
-}
-
-// Video
-{
-  type: "video",
-  src: "path/to/video.mp4",
-  alt: "Alt text",
-  caption: "Caption text"
-}
-
-// Link (paragraph containing only a link)
-{
-  type: "link",
-  content: {
-    href: "https://example.com",
-    label: "Link text"
-  }
-}
-
-// Button
-{
-  type: "button",
-  content: "Button text",
-  attrs: {
-    // Button-specific attributes
-  }
-}
-
-// Divider (horizontal rule)
-{
-  type: "divider"
-}
-```
-
-### `groups`
-
-Content organized into semantic groups with identified main content and items. The structure is flat - header and body fields are merged at the top level.
-
-```js
-{
-  main: {
-    // Header fields (flat)
-    pretitle: "PRETITLE TEXT",    // H3 before main title
-    title: "Main Title",           // First heading in group
-    subtitle: "Subtitle",          // Second heading in group
-
-    // Body fields (flat)
-    paragraphs: ["paragraph text", ...],
-    images: [
-      { url: "...", caption: "...", alt: "..." }
-    ],
-    icons: ["<svg>...</svg>", ...],
-    videos: [
-      { src: "...", caption: "...", alt: "..." }
-    ],
-    links: [
-      { href: "...", label: "..." }
-    ],
-    lists: [
-      [/* processed list items */]
-    ],
-    buttons: [
-      { content: "...", attrs: {...} }
-    ],
-    properties: [],       // Code block content
-    propertyBlocks: [],   // Array of code blocks
-    cards: [],            // Not yet implemented
-    headings: [],         // Used in list items
-
-    // Banner (flat)
-    banner: {
-      url: "path/to/banner.jpg",
-      caption: "Banner caption",
-      alt: "Banner alt text"
-    } | null
-  },
-  items: [
-    // Array of groups with same flat structure as main
-    // { title, pretitle, subtitle, paragraphs, images, ... }
-  ],
-  metadata: {
-    dividerMode: false,     // Whether dividers were used for grouping
-    groups: 0               // Total number of groups
-  }
-}
-```
-
-**Grouping Modes:**
-
-1. **Heading-based grouping** (default): Groups start with heading patterns
-2. **Divider-based grouping**: When any `horizontalRule` is present, groups are split by dividers
-
-**Main Content Identification:**
-
-- Single group → always main content
-- Multiple groups → first group is main if it has lower heading level than second group
-- Divider mode starting with divider → no main content, all items
-
-### `byType`
-
-Elements organized by type with positional context.
-
-```js
-{
-  headings: [
-    {
-      type: "heading",
-      level: 1,
-      content: "Title",
-      context: {
-        position: 0,
-        previousElement: null,
-        nextElement: { type: "paragraph", ... },
-        nearestHeading: null
-      }
-    }
-  ],
-  paragraphs: [
-    {
-      type: "paragraph",
-      content: "Text",
-      context: { ... }
-    }
-  ],
-  images: {
-    background: [/* images with role="background" */],
-    content: [/* images with role="content" */],
-    gallery: [/* images with role="gallery" */],
-    icon: [/* images with role="icon" */]
-  },
-  lists: [/* list elements with context */],
-  dividers: [/* divider elements with context */],
-  metadata: {
-    totalElements: 10,
-    dominantType: "paragraph",
-    hasMedia: true
-  },
-
-  // Helper methods
-  getHeadingsByLevel(level),
-  getElementsByHeadingContext(headingFilter)
-}
-```
-
-**Helper Methods:**
-
-```js
-// Get all H1 headings
-byType.getHeadingsByLevel(1)
-
-// Get all elements under headings matching a filter
-byType.getElementsByHeadingContext((heading) => heading.level === 2)
-```
-
-## Usage Examples
-
-### Basic Usage
-
-```js
-import { parseContent } from "@uniweb/semantic-parser";
-
-const doc = {
-  type: "doc",
-  content: [
-    {
-      type: "heading",
-      attrs: { level: 1 },
-      content: [{ type: "text", text: "Welcome" }]
-    },
-    {
-      type: "paragraph",
-      content: [{ type: "text", text: "Get started today." }]
-    }
-  ]
-};
-
-const result = parseContent(doc);
-```
-
-### Working with Groups
-
-```js
-const { groups } = parseContent(doc);
-
-// Access main content (flat structure)
-console.log(groups.main.title);
-console.log(groups.main.paragraphs);
-
-// Iterate through content items
-groups.items.forEach(item => {
-  console.log(item.title);
-  console.log(item.paragraphs);
-});
-```
-
-### Working with byType
-
-```js
-const { byType } = parseContent(doc);
-
-// Get all images
-const allImages = Object.values(byType.images).flat();
-
-// Get all H2 headings
-const h2Headings = byType.getHeadingsByLevel(2);
-
-// Get content under specific headings
-const featuresContent = byType.getElementsByHeadingContext(
-  h => h.content.includes("Features")
-);
-```
-
-### Working with Sequence
-
-```js
-const { sequence } = parseContent(doc);
-
-// Process elements in order
-sequence.forEach(element => {
-  switch(element.type) {
-    case 'heading':
-      console.log(`H${element.level}: ${element.content}`);
-      break;
-    case 'paragraph':
-      console.log(`P: ${element.content}`);
-      break;
-  }
-});
-```
-
-## Text Formatting
-
-The parser preserves inline formatting as HTML tags within text content:
-
-- **Bold**: `<strong>text</strong>`
-- **Italic**: `<em>text</em>`
-- **Links**: `<a href="url">text</a>`
-
-```js
-// Input
-{
-  type: "paragraph",
-  content: [
-    { type: "text", text: "Normal " },
-    { type: "text", marks: [{ type: "bold" }], text: "bold" }
-  ]
-}
-
-// Output
-{
-  type: "paragraph",
-  content: "Normal <strong>bold</strong>"
-}
-```
-
-## Special Element Detection
-
-The parser detects special patterns and extracts them as dedicated element types:
-
-- **Paragraph with only a link** → `type: "link"`
-- **Paragraph with only an image** (role: image/banner) → `type: "image"`
-- **Paragraph with only an icon** (role: icon) → `type: "icon"`
-- **Paragraph with only a button mark** → `type: "button"`
-- **Paragraph with only a video** (role: video) → `type: "video"`
-
-This makes it easier to identify and handle these special cases in downstream processing.