@uniweb/runtime 0.2.11 → 0.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -29,7 +29,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "0.1.8"
+    "@uniweb/core": "0.1.12"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/components/BlockRenderer.jsx

@@ -2,10 +2,11 @@
  * BlockRenderer
  *
  * Bridges Block data to foundation components.
- * Handles theming and wrapper props.
+ * Handles theming, wrapper props, and runtime guarantees.
  */
 
 import React from 'react'
+import { prepareProps, getComponentMeta } from '../prepare-props.js'
 
 /**
  * Convert hex color to rgba
@@ -82,34 +83,40 @@ export default function BlockRenderer({ block, pure = false, extra = {} }) {
     )
   }
 
-  // Build content for component
-  // Components expect content as a simple object with all data
+  // Build content and params with runtime guarantees
   // Sources:
-  // 1. parsedContent.raw - simple PoC format (hardcoded content)
-  // 2. parsedContent - semantic parser output (main.header, main.body, items, etc.)
+  // 1. parsedContent._isPoc - simple PoC format (hardcoded content)
+  // 2. parsedContent - semantic parser output (flat: title, paragraphs, links, etc.)
   // 3. block.properties - params from frontmatter (theme, alignment, etc.)
-  let content
+  // 4. meta - defaults from component meta.js
+  let content, params
 
-  if (block.parsedContent?.raw) {
+  if (block.parsedContent?._isPoc) {
     // Simple PoC format - content was passed directly
-    content = block.parsedContent.raw
+    content = block.parsedContent._pocContent
+    params = block.properties
   } else {
-    // Collected content - merge parsed content with frontmatter params
-    // Parsed content goes first so components can access content.main.header, etc.
-    // Frontmatter params overlay for things like content.title from YAML
+    // Get runtime metadata for this component (has defaults, data binding, etc.)
+    const meta = getComponentMeta(block.type)
+
+    // Prepare props with runtime guarantees:
+    // - Apply param defaults from meta.js
+    // - Guarantee content structure exists
+    const prepared = prepareProps(block, meta)
+    params = prepared.params
+
+    // Merge prepared content with raw access for components that need it
     content = {
-      ...block.parsedContent,  // Semantic parser output (main, items, etc.)
-      ...block.properties,     // Frontmatter params overlay
+      ...prepared.content,
+      ...block.properties,     // Frontmatter params overlay (legacy support)
       _prosemirror: block.parsedContent  // Keep original for components that need raw access
     }
   }
 
   const componentProps = {
     content,
-    params: block.properties,
+    params,
     block,
-    page: globalThis.uniweb?.activeWebsite?.activePage,
-    website: globalThis.uniweb?.activeWebsite,
     input: block.input
   }
 

package/src/prepare-props.js

@@ -0,0 +1,137 @@
+/**
+ * Props Preparation for Runtime Guarantees
+ *
+ * Prepares props for foundation components with:
+ * - Param defaults from runtime schema
+ * - Guaranteed content structure (no null checks needed)
+ *
+ * This enables simpler component code by ensuring predictable prop shapes.
+ */
+
+/**
+ * Guarantee item has flat content structure
+ *
+ * @param {Object} item - Raw item from parser
+ * @returns {Object} Item with guaranteed flat structure
+ */
+function guaranteeItemStructure(item) {
+  return {
+    title: item.title || '',
+    pretitle: item.pretitle || '',
+    subtitle: item.subtitle || '',
+    paragraphs: item.paragraphs || [],
+    links: item.links || [],
+    imgs: item.imgs || [],
+    lists: item.lists || [],
+    icons: item.icons || [],
+    videos: item.videos || [],
+    buttons: item.buttons || [],
+    properties: item.properties || {},
+    cards: item.cards || [],
+    documents: item.documents || [],
+    forms: item.forms || [],
+    quotes: item.quotes || [],
+    headings: item.headings || [],
+  }
+}
+
+/**
+ * Guarantee content structure exists
+ * Returns a flat content object with all standard fields guaranteed to exist
+ *
+ * @param {Object} parsedContent - Raw parsed content from semantic parser (flat structure)
+ * @returns {Object} Content with guaranteed flat structure
+ */
+export function guaranteeContentStructure(parsedContent) {
+  const content = parsedContent || {}
+
+  return {
+    // Flat header fields
+    title: content.title || '',
+    pretitle: content.pretitle || '',
+    subtitle: content.subtitle || '',
+    subtitle2: content.subtitle2 || '',
+    alignment: content.alignment || null,
+
+    // Flat body fields
+    paragraphs: content.paragraphs || [],
+    links: content.links || [],
+    imgs: content.imgs || [],
+    lists: content.lists || [],
+    icons: content.icons || [],
+    videos: content.videos || [],
+    buttons: content.buttons || [],
+    properties: content.properties || {},
+    propertyBlocks: content.propertyBlocks || [],
+    cards: content.cards || [],
+    documents: content.documents || [],
+    forms: content.forms || [],
+    quotes: content.quotes || [],
+    headings: content.headings || [],
+
+    // Items with guaranteed structure
+    items: (content.items || []).map(guaranteeItemStructure),
+
+    // Sequence for ordered rendering
+    sequence: content.sequence || [],
+
+    // Preserve raw content if present
+    raw: content.raw,
+  }
+}
+
+/**
+ * Apply param defaults from runtime schema
+ *
+ * @param {Object} params - Params from frontmatter
+ * @param {Object} defaults - Default values from runtime schema
+ * @returns {Object} Merged params with defaults applied
+ */
+export function applyDefaults(params, defaults) {
+  if (!defaults || Object.keys(defaults).length === 0) {
+    return params || {}
+  }
+
+  return {
+    ...defaults,
+    ...(params || {}),
+  }
+}
+
+/**
+ * Prepare props for a component with runtime guarantees
+ *
+ * @param {Object} block - The block instance
+ * @param {Object} meta - Runtime metadata for the component (from meta[componentName])
+ * @returns {Object} Prepared props: { content, params }
+ */
+export function prepareProps(block, meta) {
+  // Apply param defaults
+  const defaults = meta?.defaults || {}
+  const params = applyDefaults(block.properties, defaults)
+
+  // Guarantee content structure
+  const content = guaranteeContentStructure(block.parsedContent)
+
+  return { content, params }
+}
+
+/**
+ * Get runtime metadata for a component from the global uniweb instance
+ *
+ * @param {string} componentName
+ * @returns {Object|null}
+ */
+export function getComponentMeta(componentName) {
+  return globalThis.uniweb?.getComponentMeta?.(componentName) || null
+}
+
+/**
+ * Get default param values for a component
+ *
+ * @param {string} componentName
+ * @returns {Object}
+ */
+export function getComponentDefaults(componentName) {
+  return globalThis.uniweb?.getComponentDefaults?.(componentName) || {}
+}