@uniweb/semantic-parser 1.0.0

package/src/mappers/accessor.js

@@ -0,0 +1,312 @@
+/**
+ * Path-based accessor for extracting values from parsed content
+ */
+
+import { applyType, validateType } from './types.js';
+
+/**
+ * Parse a path string into segments, handling array indices
+ * @param {string} path - Path string (e.g., 'groups.main.body.imgs[0].url')
+ * @returns {Array} Array of path segments
+ */
+function parsePath(path) {
+    const segments = [];
+    const parts = path.split('.');
+
+    for (const part of parts) {
+        // Check for array index notation: key[0]
+        const match = part.match(/^(.+?)\[(\d+)\]$/);
+        if (match) {
+            segments.push({ key: match[1], type: 'object' });
+            segments.push({ index: parseInt(match[2], 10), type: 'array' });
+        } else {
+            segments.push({ key: part, type: 'object' });
+        }
+    }
+
+    return segments;
+}
+
+/**
+ * Get value at path from parsed content
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @param {string} path - Path to value (e.g., 'groups.main.header.title')
+ * @param {Object} options - Options for extraction
+ * @param {*} options.defaultValue - Default value if path doesn't exist
+ * @param {Function} options.transform - Transformation function to apply to value
+ * @param {boolean} options.required - Throw error if value is missing
+ * @param {string} options.type - Field type for automatic transformation
+ * @param {boolean} options.treatEmptyAsDefault - Treat empty strings as missing
+ * @returns {*} Value at path
+ */
+function getByPath(parsed, path, options = {}) {
+    const {
+        defaultValue,
+        transform,
+        required = false,
+        type,
+        treatEmptyAsDefault = false,
+        ...typeOptions
+    } = options;
+
+    if (!parsed || !path) {
+        if (required) {
+            throw new Error('Path is required');
+        }
+        return defaultValue;
+    }
+
+    const segments = parsePath(path);
+    let current = parsed;
+
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+
+        if (current === null || current === undefined) {
+            if (required) {
+                throw new Error(`Required field missing at path: ${path}`);
+            }
+            return defaultValue;
+        }
+
+        if (segment.type === 'array') {
+            if (!Array.isArray(current)) {
+                if (required) {
+                    throw new Error(`Expected array at path segment ${i} in: ${path}`);
+                }
+                return defaultValue;
+            }
+            current = current[segment.index];
+        } else {
+            current = current[segment.key];
+        }
+    }
+
+    let value = current !== undefined ? current : defaultValue;
+
+    // Treat empty strings as missing if requested
+    if (treatEmptyAsDefault && value === '') {
+        value = defaultValue;
+    }
+
+    if (required && (value === undefined || value === null || value === '')) {
+        throw new Error(`Required field missing at path: ${path}`);
+    }
+
+    // Apply type transformation if specified
+    if (type && value !== undefined && value !== null) {
+        value = applyType(value, type, typeOptions);
+    }
+
+    // Apply custom transform after type transformation
+    return transform ? transform(value) : value;
+}
+
+/**
+ * Extract multiple values using a schema
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @param {Object} schema - Schema defining paths and transformations
+ * @param {Object} options - Extraction options
+ * @param {string} options.mode - Execution mode ('visual-editor' or 'build')
+ * @returns {Object} Extracted values
+ *
+ * @example
+ * const schema = {
+ *   title: {
+ *     path: 'groups.main.header.title',
+ *     type: 'plaintext',
+ *     maxLength: 60
+ *   },
+ *   image: {
+ *     path: 'groups.main.body.imgs[0].url',
+ *     type: 'image',
+ *     defaultValue: '/placeholder.jpg'
+ *   },
+ *   description: {
+ *     path: 'groups.main.body.paragraphs',
+ *     type: 'excerpt',
+ *     maxLength: 150
+ *   }
+ * };
+ * const data = extractBySchema(parsed, schema, { mode: 'visual-editor' });
+ */
+function extractBySchema(parsed, schema, options = {}) {
+    const { mode = 'visual-editor' } = options;
+    const result = {};
+    const validationResults = [];
+
+    for (const [key, config] of Object.entries(schema)) {
+        // Allow shorthand: key: 'path.to.value'
+        if (typeof config === 'string') {
+            result[key] = getByPath(parsed, config);
+        } else {
+            // Full config: { path, type, defaultValue, transform, required, ... }
+            const { path, type, ...fieldOptions } = config;
+
+            // Extract value
+            result[key] = getByPath(parsed, path, { type, ...fieldOptions });
+
+            // Validate if type specified and in build mode
+            if (type && mode === 'build') {
+                const rawValue = getByPath(parsed, path, {
+                    defaultValue: fieldOptions.defaultValue
+                });
+                const errors = validateType(rawValue, type, {
+                    ...fieldOptions,
+                    fieldName: key
+                }, mode);
+                validationResults.push(...errors);
+            }
+        }
+    }
+
+    // In build mode, log validation results
+    if (mode === 'build' && validationResults.length > 0) {
+        const errors = validationResults.filter(v => v.severity === 'error');
+        const warnings = validationResults.filter(v => v.severity === 'warning');
+
+        if (warnings.length > 0) {
+            console.warn('Content validation warnings:');
+            warnings.forEach(w => {
+                console.warn(`  [${w.field}] ${w.message}${w.autoFix ? ' (auto-fixed)' : ''}`);
+            });
+        }
+
+        if (errors.length > 0) {
+            console.error('Content validation errors:');
+            errors.forEach(e => {
+                console.error(`  [${e.field}] ${e.message}`);
+            });
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Check if a path exists in parsed content
+ * @param {Object} parsed - Parsed content
+ * @param {string} path - Path to check
+ * @returns {boolean} True if path exists and has a non-null/undefined value
+ */
+function hasPath(parsed, path) {
+    try {
+        const value = getByPath(parsed, path);
+        return value !== null && value !== undefined;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Get multiple paths, return first that exists
+ * @param {Object} parsed - Parsed content
+ * @param {Array<string>} paths - Array of paths to try
+ * @param {*} defaultValue - Default if none exist
+ * @returns {*} First existing value or default
+ */
+function getFirstExisting(parsed, paths, defaultValue = null) {
+    for (const path of paths) {
+        if (hasPath(parsed, path)) {
+            return getByPath(parsed, path);
+        }
+    }
+    return defaultValue;
+}
+
+/**
+ * Extract values from array of items using same path
+ * @param {Object} parsed - Parsed content
+ * @param {string} arrayPath - Path to array
+ * @param {string|Object} itemConfig - Path or config for each item
+ * @returns {Array} Extracted values
+ *
+ * @example
+ * // Get all item titles
+ * mapArray(parsed, 'groups.items', 'header.title')
+ *
+ * // Get objects from each item
+ * mapArray(parsed, 'groups.items', {
+ *   title: 'header.title',
+ *   text: { path: 'body.paragraphs', transform: p => p.join(' ') }
+ * })
+ */
+function mapArray(parsed, arrayPath, itemConfig) {
+    const array = getByPath(parsed, arrayPath, { defaultValue: [] });
+
+    if (!Array.isArray(array)) {
+        return [];
+    }
+
+    return array.map(item => {
+        if (typeof itemConfig === 'string') {
+            return getByPath({ item }, `item.${itemConfig}`);
+        } else {
+            return extractBySchema({ item },
+                Object.entries(itemConfig).reduce((acc, [key, config]) => {
+                    if (typeof config === 'string') {
+                        acc[key] = `item.${config}`;
+                    } else {
+                        acc[key] = { ...config, path: `item.${config.path}` };
+                    }
+                    return acc;
+                }, {})
+            );
+        }
+    });
+}
+
+/**
+ * Validate content against schema without extracting
+ * Useful for providing UI hints in visual editor
+ * @param {Object} parsed - Parsed content
+ * @param {Object} schema - Schema to validate against
+ * @param {Object} options - Validation options
+ * @param {string} options.mode - Execution mode ('visual-editor' or 'build')
+ * @returns {Object} Validation results by field
+ *
+ * @example
+ * const hints = validateSchema(parsed, schema);
+ * // {
+ * //   title: [{ type: 'max_length', severity: 'info', message: '...' }],
+ * //   image: [{ type: 'required', severity: 'error', message: '...' }]
+ * // }
+ */
+function validateSchema(parsed, schema, options = {}) {
+    const { mode = 'visual-editor' } = options;
+    const results = {};
+
+    for (const [key, config] of Object.entries(schema)) {
+        if (typeof config === 'string') {
+            continue; // No validation for shorthand
+        }
+
+        const { path, type, ...fieldOptions } = config;
+
+        if (type) {
+            const rawValue = getByPath(parsed, path, {
+                defaultValue: fieldOptions.defaultValue
+            });
+
+            const errors = validateType(rawValue, type, {
+                ...fieldOptions,
+                fieldName: key
+            }, mode);
+
+            if (errors.length > 0) {
+                results[key] = errors;
+            }
+        }
+    }
+
+    return results;
+}
+
+export {
+    getByPath,
+    extractBySchema,
+    validateSchema,
+    hasPath,
+    getFirstExisting,
+    mapArray
+};

package/src/mappers/extractors.js

@@ -0,0 +1,397 @@
+/**
+ * Pre-built extractors for common component patterns
+ */
+
+import { first, joinParagraphs } from "./helpers.js";
+
+/**
+ * Extract hero component data
+ * Common pattern: Large header with title, subtitle, image, and CTA
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @returns {Object} Hero component data
+ */
+function hero(parsed) {
+    const main = parsed.groups?.main;
+
+    return {
+        title: main?.header?.title || null,
+        subtitle: main?.header?.subtitle || null,
+        kicker: main?.header?.pretitle || null,
+        description: main?.body?.paragraphs || [],
+        image: first(main?.body?.imgs)?.url || null,
+        imageAlt: first(main?.body?.imgs)?.alt || null,
+        banner: main?.banner?.url || null,
+        cta: first(main?.body?.links) || null,
+        button: first(main?.body?.buttons) || null,
+    };
+}
+
+/**
+ * Extract card component data
+ * Common pattern: Title, description, image, and link
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @param {Object} options - Extraction options
+ * @param {boolean} options.useItems - Extract from items instead of main
+ * @param {number} options.itemIndex - Specific item index to extract from
+ * @returns {Object|Array} Card data or array of cards if useItems=true
+ */
+function card(parsed, options = {}) {
+    const { useItems = false, itemIndex } = options;
+
+    const extractCard = (group) => {
+        if (!group) return null;
+
+        return {
+            title: group.header?.title || null,
+            subtitle: group.header?.subtitle || null,
+            description: group.body?.paragraphs || [],
+            image: first(group.body?.imgs)?.url || null,
+            imageAlt: first(group.body?.imgs)?.alt || null,
+            icon: first(group.body?.icons) || null,
+            link: first(group.body?.links) || null,
+            button: first(group.body?.buttons) || null,
+        };
+    };
+
+    if (useItems) {
+        const items = parsed.groups?.items || [];
+        if (itemIndex !== undefined) {
+            return extractCard(items[itemIndex]);
+        }
+        return items.map(extractCard).filter(Boolean);
+    }
+
+    return extractCard(parsed.groups?.main);
+}
+
+/**
+ * Extract article/blog content
+ * Common pattern: Title, author info, content blocks, images
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @returns {Object} Article data
+ */
+function article(parsed) {
+    const main = parsed.groups?.main;
+
+    return {
+        title: main?.header?.title || null,
+        subtitle: main?.header?.subtitle || null,
+        kicker: main?.header?.pretitle || null,
+        author: main?.metadata?.author || null,
+        date: main?.metadata?.date || null,
+        banner: main?.banner?.url || null,
+        content: main?.body?.paragraphs || [],
+        images: main?.body?.imgs || [],
+        videos: main?.body?.videos || [],
+        links: main?.body?.links || [],
+    };
+}
+
+/**
+ * Extract statistics/metrics data
+ * Common pattern: Numeric value with label
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @returns {Array} Array of stat objects
+ */
+function stats(parsed) {
+    const items = parsed.groups?.items || [];
+
+    return items
+        .map((item) => ({
+            value: item.header?.title || null,
+            label:
+                item.header?.subtitle || first(item.body?.paragraphs) || null,
+            description: item.body?.paragraphs || [],
+        }))
+        .filter((stat) => stat.value);
+}
+
+/**
+ * Extract navigation menu structure
+ * Common pattern: Hierarchical menu with labels, links, and optional children
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @returns {Array} Navigation items
+ */
+function navigation(parsed) {
+    const items = parsed.groups?.items || [];
+
+    return items
+        .map((item) => {
+            const navItem = {
+                label: item.header?.title || null,
+                href: first(item.body?.links)?.href || null,
+            };
+
+            // Extract children from nested lists
+            const firstList = first(item.body?.lists);
+            if (firstList && firstList.length > 0) {
+                navItem.children = firstList
+                    .map((listItem) => ({
+                        label: joinParagraphs(listItem.paragraphs) || null,
+                        href: first(listItem.links)?.href || null,
+                        icon: first(listItem.icons) || null,
+                    }))
+                    .filter((child) => child.label);
+            }
+
+            return navItem;
+        })
+        .filter((item) => item.label);
+}
+
+/**
+ * Extract feature list
+ * Common pattern: Icon/image, title, description
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @returns {Array} Feature items
+ */
+function features(parsed) {
+    const items = parsed.groups?.items || [];
+
+    return items
+        .map((item) => ({
+            title: item.header?.title || null,
+            subtitle: item.header?.subtitle || null,
+            description: item.body?.paragraphs || [],
+            icon: first(item.body?.icons) || null,
+            image: first(item.body?.imgs)?.url || null,
+            link: first(item.body?.links) || null,
+        }))
+        .filter((feature) => feature.title);
+}
+
+/**
+ * Extract testimonial data
+ * Common pattern: Quote, author name, role, image
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @param {Object} options - Extraction options
+ * @param {boolean} options.useItems - Extract from items instead of main
+ * @returns {Object|Array} Testimonial data
+ */
+function testimonial(parsed, options = {}) {
+    const { useItems = false } = options;
+
+    const extractTestimonial = (group) => {
+        if (!group) return null;
+
+        return {
+            quote: group.body?.paragraphs || [],
+            author: group.header?.title || null,
+            role: group.header?.subtitle || null,
+            company: group.header?.pretitle || null,
+            image: first(group.body?.imgs)?.url || null,
+            imageAlt: first(group.body?.imgs)?.alt || null,
+        };
+    };
+
+    if (useItems) {
+        const items = parsed.groups?.items || [];
+        return items.map(extractTestimonial).filter(Boolean);
+    }
+
+    return extractTestimonial(parsed.groups?.main);
+}
+
+/**
+ * Extract FAQ (question and answer pairs)
+ * Common pattern: Question as title, answer as content
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @returns {Array} FAQ items
+ */
+function faq(parsed) {
+    const items = parsed.groups?.items || [];
+
+    return items
+        .map((item) => ({
+            question: item.header?.title || null,
+            answer: item.body?.paragraphs || [],
+            links: item.body?.links || [],
+        }))
+        .filter((item) => item.question);
+}
+
+/**
+ * Extract pricing tier data
+ * Common pattern: Plan name, price, features list, CTA
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @returns {Array} Pricing tiers
+ */
+function pricing(parsed) {
+    const items = parsed.groups?.items || [];
+
+    return items
+        .map((item) => {
+            const firstList = first(item.body?.lists);
+
+            return {
+                name: item.header?.title || null,
+                price: item.header?.subtitle || null,
+                description: first(item.body?.paragraphs) || null,
+                features: firstList
+                    ? firstList
+                          .map((listItem) =>
+                              joinParagraphs(listItem.paragraphs)
+                          )
+                          .filter(Boolean)
+                    : [],
+                cta:
+                    first(item.body?.links) ||
+                    first(item.body?.buttons) ||
+                    null,
+                highlighted:
+                    item.header?.pretitle?.toLowerCase().includes("popular") ||
+                    false,
+            };
+        })
+        .filter((tier) => tier.name);
+}
+
+/**
+ * Extract team member data
+ * Common pattern: Name, role, bio, image, social links
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @returns {Array} Team members
+ */
+function team(parsed) {
+    const items = parsed.groups?.items || [];
+
+    return items
+        .map((item) => ({
+            name: item.header?.title || null,
+            role: item.header?.subtitle || null,
+            department: item.header?.pretitle || null,
+            bio: item.body?.paragraphs || [],
+            image: first(item.body?.imgs)?.url || null,
+            imageAlt: first(item.body?.imgs)?.alt || null,
+            links: item.body?.links || [],
+        }))
+        .filter((member) => member.name);
+}
+
+/**
+ * Extract gallery images
+ * Common pattern: Collection of images with captions
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @param {Object} options - Extraction options
+ * @param {string} options.source - Source to extract from: 'main', 'items', 'all'
+ * @returns {Array} Gallery images
+ */
+function gallery(parsed, options = {}) {
+    const { source = "all" } = options;
+    const images = [];
+
+    if (source === "main" || source === "all") {
+        const mainImages = parsed.groups?.main?.body?.imgs || [];
+        images.push(...mainImages);
+    }
+
+    if (source === "items" || source === "all") {
+        const items = parsed.groups?.items || [];
+        items.forEach((item) => {
+            const itemImages = item.body?.imgs || [];
+            images.push(...itemImages);
+        });
+    }
+
+    return images.map((img) => ({
+        url: img.url,
+        alt: img.alt || null,
+        caption: img.caption || null,
+    }));
+}
+
+/**
+ * Extract content in legacy Article class format
+ * Used for backward compatibility with existing components
+ *
+ * This extractor transforms the new parser output into the exact format
+ * used by the legacy Article class, enabling drop-in replacement without
+ * breaking existing components.
+ *
+ * @param {Object} parsed - Parsed content from parseContent()
+ * @returns {Object} Legacy format { main, items }
+ *
+ * @example
+ * const { parseContent, mappers } = require('@uniwebcms/semantic-parser');
+ * const parsed = parseContent(doc, { pretitleLevel: 2, parseCodeAsJson: true });
+ * const legacy = mappers.extractors.legacy(parsed);
+ * // Returns: { main: {...}, items: [...] }
+ */
+function legacy(parsed) {
+    const groups = parsed.groups || {};
+
+    const transformGroup = (group) => {
+        if (!group) return null;
+
+        let imgs = group.body?.imgs || [];
+        let banner = imgs.filter((item) => {
+            return (item.role = "banner");
+        })?.[0];
+
+        if (!banner) banner = imgs[0];
+
+        return {
+            header: {
+                title: group.header?.title || "",
+                subtitle: group.header?.subtitle || "",
+                subtitle2: group.header?.subtitle2 || "",
+                pretitle: group.header?.pretitle || "",
+                // Auto-fill description (legacy behavior)
+                description:
+                    group.header?.subtitle2 ||
+                    first(group.body?.paragraphs) ||
+                    "",
+                alignment: group.header?.alignment || "",
+            },
+            banner,
+            body: {
+                paragraphs: group.body?.paragraphs || [],
+                headings: group.body?.headings || [],
+                imgs,
+                videos: group.body?.videos || [],
+                lists: group.body?.lists || [],
+                links: group.body?.links || [],
+                icons: group.body?.icons || [],
+                buttons: group.body?.buttons || [],
+                cards: group.body?.cards || [],
+                documents: group.body?.documents || [],
+                forms: group.body?.forms || [],
+                form: first(group.body?.forms) || null,
+                quotes: group.body?.quotes || [],
+                properties: group.body?.properties || {},
+                propertyBlocks: group.body?.propertyBlocks || [],
+            },
+        };
+    };
+
+    return {
+        main: transformGroup(groups.main),
+        items: (groups.items || []).map(transformGroup),
+    };
+}
+
+export {
+    hero,
+    card,
+    article,
+    stats,
+    navigation,
+    features,
+    testimonial,
+    faq,
+    pricing,
+    team,
+    gallery,
+    legacy,
+};