@uniweb/semantic-parser 1.0.0

package/reference/README.md

@@ -0,0 +1,195 @@
+# Reference Implementations
+
+This folder contains production-ready reference implementations for common patterns when working with the semantic parser. These are **not** part of the published npm package but are provided for you to copy and adapt to your project.
+
+## Available Components
+
+### Text.js
+
+A complete, production-ready React component for rendering content extracted by the semantic parser.
+
+**Features:**
+- Handles single strings or arrays of paragraphs
+- Smart semantic defaults (headings, paragraphs, divs)
+- Automatic empty content filtering
+- Semantic wrapper components (H1-H6, P, PlainText, Div)
+- Support for color marks and rich formatting
+- **Trusts engine-sanitized data** - No component-level sanitization
+- Simple and lightweight - no performance overhead
+
+**Security Model:**
+This component assumes content is **already sanitized by your engine**. It does NOT sanitize HTML itself. See the [Sanitization](#sanitization) section below.
+
+**Installation:**
+
+1. **Copy the file to your project:**
+   ```bash
+   cp reference/Text.js src/components/Text.js
+   ```
+
+2. **No additional dependencies needed** - Just React
+
+3. **Sanitize at engine level** (see [Sanitization](#sanitization))
+
+4. **Use in your components:**
+   ```jsx
+   import Text, { H1, P } from './components/Text';
+   import { parseContent, mappers } from '@uniwebcms/semantic-parser';
+
+   function MyComponent({ document }) {
+     const parsed = parseContent(document);
+     const hero = mappers.extractors.hero(parsed);
+
+     return (
+       <>
+         <H1 text={hero.title} />
+         <P text={hero.description} />
+       </>
+     );
+   }
+   ```
+
+**TypeScript Support:**
+
+If using TypeScript, add this type definition file:
+
+```typescript
+// Text.d.ts
+import { ReactElement } from 'react';
+
+interface TextProps {
+  text: string | string[];
+  as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'div' | 'span';
+  html?: boolean;
+  className?: string;
+  lineAs?: string;
+}
+
+declare const Text: React.FC<TextProps>;
+export default Text;
+
+export const H1: React.FC<Omit<TextProps, 'as'>>;
+export const H2: React.FC<Omit<TextProps, 'as'>>;
+export const H3: React.FC<Omit<TextProps, 'as'>>;
+export const H4: React.FC<Omit<TextProps, 'as'>>;
+export const H5: React.FC<Omit<TextProps, 'as'>>;
+export const H6: React.FC<Omit<TextProps, 'as'>>;
+export const P: React.FC<Omit<TextProps, 'as'>>;
+export const PlainText: React.FC<Omit<TextProps, 'html'>>;
+export const Div: React.FC<Omit<TextProps, 'as'>>;
+```
+
+## Sanitization
+
+**IMPORTANT:** This component does NOT sanitize HTML. Sanitization happens at the **engine level**.
+
+### Why Engine-Level Sanitization?
+
+1. **Performance** - Sanitize once during data preparation, not on every render
+2. **Context-aware** - Engine knows if content is from trusted TipTap or external sources
+3. **Cacheable** - Sanitized content can be memoized
+4. **Clear responsibility** - Engine owns the data pipeline
+
+### How to Sanitize
+
+Use the parser's built-in utilities in your engine:
+
+```javascript
+import { sanitizeHtml } from '@uniwebcms/semantic-parser/mappers/types';
+import { parseContent, mappers } from '@uniwebcms/semantic-parser';
+
+// In your engine (NOT in the component)
+function prepareHeroData(document) {
+  const parsed = parseContent(document);
+  const hero = mappers.extractors.hero(parsed);
+
+  // Sanitize here, before passing to component
+  return {
+    ...hero,
+    title: sanitizeHtml(hero.title, {
+      allowedTags: ['strong', 'em', 'mark', 'span'],
+      allowedAttr: ['class', 'data-variant']
+    }),
+    description: hero.description.map(p => sanitizeHtml(p))
+  };
+}
+
+// Component receives clean data
+const heroData = prepareHeroData(doc);
+<H1 text={heroData.title} />  {/* Already sanitized */}
+```
+
+### When to Sanitize
+
+- **Always**: External content, user-generated content
+- **Optional**: Trusted TipTap editor with locked schema
+- **Never needed**: Hard-coded content in your app
+
+See [docs/text-component-reference.md](../docs/text-component-reference.md#sanitization-tools) for detailed sanitization guidance.
+
+## Customization
+
+These reference implementations are designed to be copied and customized for your needs:
+
+### Add Custom Styling Props
+
+```jsx
+// Add a spacing prop
+const Text = React.memo(({ text, as = 'p', className, spacing = 'normal', ... }) => {
+  const spacingClass = spacing !== 'normal' ? `spacing-${spacing}` : '';
+  const combinedClass = [className, spacingClass].filter(Boolean).join(' ');
+
+  // Use combinedClass in rendering
+});
+
+// Usage
+<P text={paragraphs} spacing="comfortable" />
+```
+
+### Remove Features You Don't Need
+
+If you don't need certain features, simplify the component:
+
+- Remove sanitization if you sanitize at engine level
+- Remove wrapper components if you don't use them
+- Remove HTML support if you only render plain text
+- Remove array support if you always use strings
+
+## Why Reference Implementations?
+
+The semantic parser is a **data transformation library**, not a UI component library. It focuses on parsing and structuring content.
+
+However, rendering that content requires common patterns that most projects need. Rather than forcing specific implementations, we provide battle-tested reference code that you can:
+
+1. **Copy as-is** - Use immediately without modification
+2. **Customize** - Adapt to your specific needs
+3. **Learn from** - Understand best practices
+4. **Replace** - Use your own implementations
+
+This approach:
+- ✅ Keeps the parser lightweight and focused
+- ✅ Gives you full control over rendering
+- ✅ Avoids forcing UI framework choices
+- ✅ Provides working code, not just documentation
+
+## Documentation
+
+For detailed usage guides, see:
+- [Text Component Reference](../docs/text-component-reference.md) - Complete documentation
+- [Mapping Patterns Guide](../docs/mapping-patterns.md) - Integration examples
+- [API Reference](../docs/api.md) - Parser API documentation
+
+## Contributing
+
+If you develop improved versions or new reference implementations, consider contributing them back to help other users.
+
+Common additions that would be valuable:
+- Vue.js version of Text component
+- Svelte version of Text component
+- Image component for handling image data
+- Link component for handling link objects
+- Video component for media handling
+
+## License
+
+These reference implementations are provided under the same license as the semantic parser (GPL-3.0-or-later) and can be freely used in your projects.

package/reference/Text.js

@@ -0,0 +1,188 @@
+import React from 'react';
+
+/**
+ * Text - A smart typography component for rendering content from semantic-parser
+ *
+ * Features:
+ * - Handles single strings or arrays of paragraphs
+ * - Smart semantic defaults for different content types
+ * - Automatic filtering of empty content
+ *
+ * Security Model:
+ * - Assumes content is ALREADY SANITIZED at the engine level
+ * - Does NOT sanitize HTML (that's the engine's responsibility)
+ * - Trusts the data it receives and renders it as-is
+ *
+ * @param {Object} props
+ * @param {string|string[]} props.text - The content to render. Can be a string or an array of strings.
+ * @param {string} [props.as='p'] - The tag to use for the wrapper or primary semantic element (e.g. 'h1', 'p', 'div').
+ * @param {boolean} [props.html=true] - If true, renders content as HTML. If false, renders as plain text.
+ * @param {string} [props.className] - Optional className to apply to the outer wrapper or individual elements.
+ * @param {string} [props.lineAs] - For array inputs: tag to wrap each line. Defaults to 'div' for headings, 'p' for others.
+ *
+ * @example
+ * // Simple paragraph (semantic default)
+ * <Text text="Hello World" />
+ *
+ * // Explicit heading
+ * <Text text="Hello World" as="h1" />
+ *
+ * // Multi-line heading
+ * <Text text={["Welcome to", "Our Platform"]} as="h1" />
+ *
+ * // Multiple paragraphs (clean semantic output)
+ * <Text text={["First paragraph", "Second paragraph"]} />
+ *
+ * // Rich HTML content (assumes already sanitized by engine)
+ * <Text text={["Safe <strong>bold</strong> text", "With <em>emphasis</em>"]} />
+ *
+ * // Plain text when HTML is disabled
+ * <Text text="No <strong>formatting</strong> here" html={false} />
+ *
+ * // Explicit div wrapper when needed
+ * <Text text={["Item 1", "Item 2"]} as="div" lineAs="span" />
+ */
+function Text({ text, as = 'p', html = true, className, lineAs }) {
+  const isArray = Array.isArray(text);
+  const Tag = as;
+  const isHeading = as === 'h1' || as === 'h2' || as === 'h3' || as === 'h4' || as === 'h5' || as === 'h6';
+
+  // Single string input
+  if (!isArray) {
+    if (!text || text.trim() === '') return null;
+
+    if (html) {
+      return (
+        <Tag
+          className={className}
+          dangerouslySetInnerHTML={{ __html: text }}
+        />
+      );
+    }
+    return <Tag className={className}>{text}</Tag>;
+  }
+
+  // Array input - filter empty content first
+  const filteredText = text.filter(
+    (item) => typeof item === 'string' && item.trim() !== ''
+  );
+
+  if (filteredText.length === 0) {
+    return null; // Don't render anything for empty arrays
+  }
+
+  // Determine the line wrapper tag with smart defaults
+  const LineTag = lineAs || (isHeading ? 'div' : 'p');
+
+  // Multi-line heading: wrap all lines in a single heading tag
+  if (isHeading) {
+    return (
+      <Tag className={className}>
+        {filteredText.map((line, i) => {
+          if (html) {
+            return (
+              <LineTag
+                key={i}
+                dangerouslySetInnerHTML={{ __html: line }}
+              />
+            );
+          }
+          return <LineTag key={i}>{line}</LineTag>;
+        })}
+      </Tag>
+    );
+  }
+
+  // Non-heading arrays: render each line as separate element
+  return (
+    <>
+      {filteredText.map((line, i) => {
+        if (html) {
+          return (
+            <LineTag
+              key={i}
+              className={className}
+              dangerouslySetInnerHTML={{ __html: line }}
+            />
+          );
+        }
+        return (
+          <LineTag key={i} className={className}>
+            {line}
+          </LineTag>
+        );
+      })}
+    </>
+  );
+}
+
+// ============================================================================
+// Semantic Wrapper Components - Thin wrappers around Text for common use cases
+// ============================================================================
+
+/**
+ * H1 - Heading level 1 component
+ * @param {Object} props - All Text props except 'as' (automatically set to 'h1')
+ * @example
+ * <H1 text="Main Title" />
+ * <H1 text={["Multi-line", "Main Title"]} />
+ */
+export const H1 = (props) => <Text {...props} as="h1" />;
+
+/**
+ * H2 - Heading level 2 component
+ * @param {Object} props - All Text props except 'as' (automatically set to 'h2')
+ */
+export const H2 = (props) => <Text {...props} as="h2" />;
+
+/**
+ * H3 - Heading level 3 component
+ * @param {Object} props - All Text props except 'as' (automatically set to 'h3')
+ */
+export const H3 = (props) => <Text {...props} as="h3" />;
+
+/**
+ * H4 - Heading level 4 component
+ * @param {Object} props - All Text props except 'as' (automatically set to 'h4')
+ */
+export const H4 = (props) => <Text {...props} as="h4" />;
+
+/**
+ * H5 - Heading level 5 component
+ * @param {Object} props - All Text props except 'as' (automatically set to 'h5')
+ */
+export const H5 = (props) => <Text {...props} as="h5" />;
+
+/**
+ * H6 - Heading level 6 component
+ * @param {Object} props - All Text props except 'as' (automatically set to 'h6')
+ */
+export const H6 = (props) => <Text {...props} as="h6" />;
+
+/**
+ * P - Paragraph component (explicitly semantic)
+ * @param {Object} props - All Text props except 'as' (automatically set to 'p')
+ * @example
+ * <P text="A paragraph of content" />
+ * <P text={["First paragraph", "Second paragraph"]} />
+ */
+export const P = (props) => <Text {...props} as="p" />;
+
+/**
+ * PlainText - Text component with HTML processing disabled
+ * @param {Object} props - All Text props except 'html' (automatically set to false)
+ * @example
+ * <PlainText text="Display <strong>tags</strong> as literal text" />
+ */
+export const PlainText = (props) => <Text {...props} html={false} />;
+
+/**
+ * Div - Explicit div wrapper component
+ * @param {Object} props - All Text props except 'as' (automatically set to 'div')
+ * @example
+ * <Div text={["Item 1", "Item 2"]} lineAs="span" />
+ */
+export const Div = (props) => <Text {...props} as="div" />;
+
+// Export all components
+export default Text;

package/src/index.js

@@ -0,0 +1,35 @@
+import { processSequence } from "./processors/sequence.js";
+import { processGroups } from "./processors/groups.js";
+import { processByType } from "./processors/byType.js";
+import * as mappers from "./mappers/index.js";
+
+/**
+ * Parse ProseMirror/TipTap content into semantic structure
+ * @param {Object} doc - ProseMirror document
+ * @param {Object} options - Parsing options
+ * @param {boolean} options.parseCodeAsJson - Parse code blocks as JSON. Default: false
+ * @returns {Object} Parsed content structure
+ */
+function parseContent(doc, options = {}) {
+    // Default options
+    const opts = {
+        parseCodeAsJson: false,
+        ...options,
+    };
+
+    // Process content in different ways
+    const sequence = processSequence(doc, opts);
+
+    const groups = processGroups(sequence, opts);
+
+    const byType = processByType(sequence);
+
+    return {
+        raw: doc,
+        sequence,
+        groups,
+        byType,
+    };
+}
+
+export { parseContent, mappers };