@marvalt/wparser 0.1.25 → 0.1.27

package/dist/types.d.ts

@@ -48,6 +48,7 @@ export interface RenderContext {
     registry: ComponentRegistry;
     page?: WordPressPageMinimal;
     colorMapper?: ColorMapper;
+    spacingConfig?: SpacingConfig;
 }
 export interface BlockRendererProps {
     block: WordPressBlock;
@@ -68,6 +69,8 @@ export interface ComponentRegistry {
     fallback: BlockRenderer;
     /** Optional color mapper for converting WordPress theme colors to CSS classes */
     colorMapper?: ColorMapper;
+    /** Optional spacing configuration for customizing element spacing */
+    spacingConfig?: SpacingConfig;
 }
 /**
  * Pattern matching for blocks - allows matching blocks by name and attributes
@@ -109,4 +112,29 @@ export interface EnhancedRegistry extends ComponentRegistry {
     /** Find matching component mapping for a block */
     matchBlock: (block: WordPressBlock) => ComponentMapping | null;
 }
+/**
+ * Spacing configuration for customizing element and section spacing
+ * Allows applications to control spacing values while maintaining consistency
+ */
+export interface SpacingConfig {
+    /** Spacing for paragraph elements (e.g., 'my-4', 'my-6') */
+    paragraph?: string;
+    /** Spacing for heading elements by level */
+    heading?: {
+        /** H1 spacing (e.g., 'mt-8 mb-6') */
+        h1?: string;
+        /** H2 spacing (e.g., 'mt-6 mb-4') */
+        h2?: string;
+        /** H3 and below spacing (e.g., 'mt-4 mb-3') */
+        h3?: string;
+    };
+    /** Spacing for image elements (e.g., 'my-4', 'my-6') */
+    image?: string;
+    /** Spacing for list elements (e.g., 'my-4', 'my-6') */
+    list?: string;
+    /** Section-level padding (for groups with align: 'full' or 'wide') */
+    section?: string;
+    /** Content-level spacing (for groups without alignment) */
+    content?: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/COLOR_MAPPING.md

@@ -0,0 +1,82 @@
+# Color Mapping System
+
+## Overview
+
+The color mapping system allows WordPress theme colors to be converted to application-specific CSS classes. This maintains the separation where WordPress controls **which** color is used, while the app controls **what** it means.
+
+## Implementation
+
+### 1. Define Color Mapper
+
+```typescript
+import { type ColorMapper } from '@marvalt/wparser';
+
+const colorMapper: ColorMapper = (wpColorName) => {
+  const colorMap: Record<string, string> = {
+    'accent-5': 'bg-gray-100',           // Light gray background
+    'base': 'bg-white',                   // White background
+    'contrast': 'bg-gray-900 text-white', // Dark background with white text
+    'transparent': 'bg-transparent',      // Transparent
+    // Add more mappings as needed
+  };
+  
+  return wpColorName ? colorMap[wpColorName] || null : null;
+};
+```
+
+### 2. Pass to Registry
+
+```typescript
+import { createEnhancedRegistry } from '@marvalt/wparser';
+
+const registry = createEnhancedRegistry(mappings, undefined, colorMapper);
+```
+
+### 3. How It Works
+
+When a block has `backgroundColor: "accent-5"`:
+1. `extractBackgroundColor()` extracts `"accent-5"` from block attributes
+2. Your `colorMapper` function is called with `"accent-5"`
+3. Returns `"bg-gray-100"` (or your app's equivalent)
+4. Class is applied to the rendered element
+
+## WordPress Theme Colors
+
+Common WordPress theme color names:
+- `base` - Base/background color
+- `contrast` - Contrast/foreground color
+- `accent-1` through `accent-5` - Theme accent colors
+- `transparent` - Transparent background
+
+Check your WordPress theme's color palette for exact names.
+
+## Best Practices
+
+1. **Map All Used Colors**: Ensure all WordPress colors have mappings
+2. **Use Design Tokens**: Map to your app's design system tokens
+3. **Handle Missing Colors**: Return `null` for unmapped colors (no background applied)
+4. **Consider Text Colors**: Include text color classes when needed (e.g., `bg-gray-900 text-white`)
+
+## Example: Full Implementation
+
+```typescript
+// In your app's registry file
+import { createEnhancedRegistry, type ColorMapper } from '@marvalt/wparser';
+
+export function createAppRegistry() {
+  const colorMapper: ColorMapper = (wpColorName) => {
+    const colorMap: Record<string, string> = {
+      'accent-5': 'bg-gray-100',
+      'base': 'bg-white',
+      'contrast': 'bg-gray-900 text-white',
+      'transparent': 'bg-transparent',
+    };
+    return wpColorName ? colorMap[wpColorName] || null : null;
+  };
+  
+  const registry = createEnhancedRegistry(mappings, undefined, colorMapper);
+  // ... rest of registry setup
+  return registry;
+}
+```
+

package/docs/CUSTOMIZATION.md

@@ -0,0 +1,144 @@
+# Customization Guide
+
+## Overview
+
+The `@marvalt/wparser` package is designed to be highly customizable while maintaining a generic, reusable core. This guide covers how to customize block rendering, spacing, colors, and more.
+
+## Customizing Block Renderers
+
+### Override Default Renderers
+
+```typescript
+import { createDefaultRegistry } from '@marvalt/wparser';
+
+const registry = createDefaultRegistry();
+
+// Override paragraph renderer
+registry.renderers['core/paragraph'] = ({ block, context }) => {
+  const content = getBlockTextContent(block);
+  return <p className="my-6 text-lg text-gray-800">{content}</p>;
+};
+
+// Override heading renderer
+registry.renderers['core/heading'] = ({ block, children }) => {
+  const level = block.attributes?.level || 2;
+  const Tag = `h${level}` as keyof JSX.IntrinsicElements;
+  return (
+    <Tag className="font-bold text-4xl mb-6">
+      {children}
+    </Tag>
+  );
+};
+```
+
+### Using Enhanced Registry with Component Mappings
+
+```typescript
+import { createEnhancedRegistry, type ComponentMapping } from '@marvalt/wparser';
+import MyCustomHero from './components/MyCustomHero';
+
+const mappings: ComponentMapping[] = [
+  {
+    pattern: { name: 'core/cover' },
+    component: MyCustomHero,
+    extractProps: (block, context) => ({
+      backgroundImage: extractBackgroundImage(block, context.page),
+      title: extractTitleFromInnerBlocks(block),
+      // ... other props
+    }),
+  },
+];
+
+const registry = createEnhancedRegistry(mappings);
+```
+
+## Customizing Colors
+
+See [COLOR_MAPPING.md](./COLOR_MAPPING.md) for detailed color mapping documentation.
+
+## Customizing Spacing
+
+See [SPACING.md](./SPACING.md) for detailed spacing customization documentation.
+
+## Custom Shortcodes
+
+```typescript
+registry.shortcodes = {
+  'my_custom_shortcode': (attrs, content) => {
+    const id = attrs.id || '';
+    return <MyCustomComponent id={id}>{content}</MyCustomComponent>;
+  },
+};
+```
+
+## Best Practices
+
+1. **Keep Package Generic**: Don't hardcode app-specific styles in package code
+2. **Use App Overrides**: Customize through registry overrides in your app
+3. **Leverage Extractors**: Use provided extractor functions for consistent data extraction
+4. **Type Safety**: Use TypeScript types for all customizations
+5. **Documentation**: Document your app-specific customizations
+
+## Example: Complete Custom Registry
+
+```typescript
+import {
+  createEnhancedRegistry,
+  type ComponentMapping,
+  type ColorMapper,
+  type SpacingConfig,
+  extractBackgroundImage,
+  extractTitleFromInnerBlocks,
+} from '@marvalt/wparser';
+import MyHero from './components/MyHero';
+
+export function createAppRegistry() {
+  // Color mapping
+  const colorMapper: ColorMapper = (wpColorName) => {
+    const colorMap: Record<string, string> = {
+      'accent-5': 'bg-gray-100',
+      'base': 'bg-white',
+    };
+    return wpColorName ? colorMap[wpColorName] || null : null;
+  };
+
+  // Spacing configuration
+  const spacingConfig: SpacingConfig = {
+    paragraph: 'my-6',
+    heading: {
+      h1: 'mt-10 mb-8',
+      h2: 'mt-8 mb-6',
+      h3: 'mt-6 mb-4',
+    },
+  };
+
+  // Component mappings
+  const mappings: ComponentMapping[] = [
+    {
+      pattern: { name: 'core/cover' },
+      component: MyHero,
+      extractProps: (block, context) => ({
+        backgroundImage: extractBackgroundImage(block, context.page),
+        title: extractTitleFromInnerBlocks(block),
+      }),
+    },
+  ];
+
+  // Create registry
+  const registry = createEnhancedRegistry(mappings, undefined, colorMapper);
+
+  // Override specific renderers
+  registry.renderers['core/paragraph'] = ({ block, context }) => {
+    const content = getBlockTextContent(block);
+    return <p className="my-6 text-gray-700">{content}</p>;
+  };
+
+  // Add custom shortcodes
+  registry.shortcodes = {
+    'my_shortcode': (attrs) => <MyComponent {...attrs} />,
+  };
+
+  return registry;
+}
+```
+

package/docs/SPACING.md

@@ -0,0 +1,136 @@
+# Spacing System
+
+## Overview
+
+The package applies consistent spacing to block elements to ensure proper visual hierarchy and readability. Spacing is configurable at the application level through the `spacingConfig` parameter.
+
+## Default Spacing
+
+### Section-Level Spacing
+- **Groups with `align: "full"` or `"wide"`**: `py-16 md:py-24`
+  - These are treated as top-level sections
+  - Applied to the group container
+
+### Content-Level Spacing
+- **Groups without alignment**: `space-y-6`
+  - These are treated as content containers
+  - Uses flexbox gap for child spacing
+
+### Element-Level Spacing (Default Values)
+
+#### Headings
+- **H1**: `mt-10 mb-8` (larger top margin, larger bottom for main headings)
+- **H2**: `mt-8 mb-6` (medium top margin, medium bottom for section headings)
+- **H3+**: `mt-6 mb-4` (smaller margins for subsections)
+
+#### Paragraphs
+- **All paragraphs**: `my-6` (equal top and bottom margin for better readability)
+
+#### Images
+- **All images**: `my-6` (equal top and bottom margin for better separation)
+
+#### Lists
+- **All lists**: `my-6` (equal top and bottom margin for better separation)
+- **List items**: Internal spacing via `space-y-2` on parent
+
+### Shortcode Elements
+
+Shortcode elements (like `[leadership_cards]`) that render block-level content automatically receive spacing when rendered within paragraphs. The paragraph renderer detects block-level shortcode output and wraps it in a div with the configured paragraph spacing (`my-6` by default).
+
+## Customizing Spacing
+
+### Using SpacingConfig
+
+The package supports a `spacingConfig` object that allows apps to customize all spacing values:
+
+```typescript
+import { createDefaultRegistry, type SpacingConfig } from '@marvalt/wparser';
+
+const spacingConfig: SpacingConfig = {
+  // Element spacing
+  paragraph: 'my-8',        // Custom paragraph spacing (larger)
+  heading: {
+    h1: 'mt-12 mb-10',       // Custom H1 spacing (even larger)
+    h2: 'mt-10 mb-8',        // Custom H2 spacing
+    h3: 'mt-8 mb-6',         // Custom H3+ spacing
+  },
+  image: 'my-8',             // Custom image spacing
+  list: 'my-8',              // Custom list spacing
+  
+  // Section spacing
+  section: 'py-20 md:py-32', // Custom section padding
+  content: 'space-y-8',       // Custom content spacing
+};
+
+// Pass colorMapper (optional) and spacingConfig
+const registry = createDefaultRegistry(undefined, spacingConfig);
+```
+
+Or with `createEnhancedRegistry`:
+
+```typescript
+import { createEnhancedRegistry, type SpacingConfig } from '@marvalt/wparser';
+
+const spacingConfig: SpacingConfig = {
+  paragraph: 'my-8',
+  heading: {
+    h1: 'mt-12 mb-10',
+    h2: 'mt-10 mb-8',
+    h3: 'mt-8 mb-6',
+  },
+};
+
+// Pass mappings, baseRegistry (optional), colorMapper (optional), spacingConfig
+const registry = createEnhancedRegistry(mappings, undefined, colorMapper, spacingConfig);
+```
+
+### Override Default Spacing
+
+```typescript
+// In your app's registry override
+registry.renderers['core/paragraph'] = ({ block, context }) => {
+  const content = getBlockTextContent(block);
+  // Use your own spacing classes
+  return <p className="my-6 text-gray-700">{content}</p>;
+};
+```
+
+### Adjust Group Spacing
+
+```typescript
+registry.renderers['core/group'] = ({ block, children, context }) => {
+  // Extract background color
+  const backgroundColor = extractBackgroundColor(block, context);
+  
+  // Use custom spacing
+  const spacingClass = 'py-20 md:py-32'; // Larger spacing
+  
+  return (
+    <div className={buildClassName('container', spacingClass, backgroundColor)}>
+      {children}
+    </div>
+  );
+};
+```
+
+## Spacing Philosophy
+
+1. **Vertical Rhythm**: Consistent spacing creates visual flow
+2. **Responsive**: Spacing scales on larger screens (`md:` breakpoint)
+3. **Hierarchical**: Headings have more spacing than paragraphs
+4. **Contextual**: Section-level vs content-level spacing differs
+
+## WordPress Control
+
+WordPress doesn't directly control spacing values. Instead:
+- Content team uses group blocks with alignment to create sections
+- Package applies appropriate spacing based on block structure
+- Apps can customize spacing through `spacingConfig` or renderer overrides
+
+## Shortcode Elements
+
+Shortcode elements (like `[leadership_cards]`) should be wrapped in containers with appropriate spacing. The package doesn't automatically add spacing to shortcode outputs, so apps should:
+
+1. Ensure shortcode components have their own spacing
+2. Or wrap shortcodes in group blocks in WordPress for automatic spacing
+

package/docs/STYLING.md

@@ -0,0 +1,96 @@
+# Styling Control: WordPress vs Application
+
+## Overview
+
+The `@marvalt/wparser` package implements a **separation of concerns** model where:
+- **WordPress** controls **what** styling is applied (which colors, alignments, layouts)
+- **Application** controls **how** it's implemented (actual CSS classes, design tokens)
+
+This allows content teams to control styling from WordPress while developers maintain design system consistency.
+
+## Key Principles
+
+1. **WordPress = Content + Styling Intent**
+   - Content teams set background colors, alignments, spacing preferences
+   - WordPress stores theme color names (e.g., `"accent-5"`, `"base"`)
+
+2. **Application = Design System Implementation**
+   - Developers map WordPress colors to app-specific CSS classes
+   - Apps use their own design tokens (e.g., `bg-gray-100`, `bg-primary`)
+
+3. **Package = Generic Bridge**
+   - Package provides extraction utilities and generic renderers
+   - Package never hardcodes app-specific styles
+
+## How It Works
+
+### Background Colors
+
+**WordPress Side:**
+- Content team sets `backgroundColor: "accent-5"` on a group block
+- WordPress stores this as a theme color name
+
+**Package Side:**
+- `extractBackgroundColor()` extracts the color name from block attributes
+- Passes it to the app's `colorMapper` function
+
+**Application Side:**
+- `colorMapper` converts `"accent-5"` → `"bg-gray-100"` (or your app's equivalent)
+- CSS class is applied to the rendered element
+
+### Alignment & Layout
+
+**WordPress Side:**
+- Content team sets `align: "wide"` or `align: "full"` on blocks
+- Sets `layout.type: "constrained"` for container control
+
+**Package Side:**
+- Extracts alignment and layout attributes
+- Maps to generic container classes (`container`, `w-full`, `max-w-7xl`)
+
+**Application Side:**
+- Can override renderers to customize container behavior
+- Maintains consistent spacing and width constraints
+
+### Spacing
+
+**WordPress Side:**
+- Content team uses group blocks with alignment to create sections
+- WordPress doesn't directly control spacing (handled by block structure)
+
+**Package Side:**
+- Applies spacing based on block type and alignment:
+  - Section-level groups (`align: "full"` or `"wide"`): `py-16 md:py-24`
+  - Content-level groups: `space-y-6`
+  - Individual elements: Configurable via spacing utilities
+
+**Application Side:**
+- Can customize spacing through `spacingConfig` in registry creation
+- Can override spacing by customizing renderers
+- Can adjust spacing classes in `createDefaultRegistry()` or app overrides
+
+## Example: Complete Flow
+
+1. **WordPress**: Content team creates a group block with:
+   - `align: "wide"`
+   - `layout.type: "constrained"`
+   - `backgroundColor: "accent-5"`
+
+2. **Package**: `Group` renderer:
+   - Extracts `backgroundColor: "accent-5"`
+   - Calls `extractBackgroundColor(block, context)`
+   - Gets `"bg-gray-100"` from app's `colorMapper`
+   - Applies classes: `container py-16 md:py-24 bg-gray-100`
+
+3. **Application**: Renders with app's design system:
+   - Container width matches app's design tokens
+   - Background color matches app's color palette
+   - Spacing matches app's section spacing standards
+
+## Benefits
+
+✅ **Content Team Autonomy**: Can change colors and layouts without code changes  
+✅ **Design System Consistency**: App maintains control over actual CSS classes  
+✅ **Package Reusability**: Same package works for different apps with different styles  
+✅ **Type Safety**: TypeScript ensures correct usage of color mappers and extractors
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marvalt/wparser",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Static-only WordPress page parser and renderer (Gutenberg blocks → React) for Digivalt apps",
   "license": "GPL-3.0-or-later",
   "main": "dist/index.cjs",
@@ -16,7 +16,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs"
   ],
   "type": "module",
   "sideEffects": false,