@uniweb/runtime 0.2.11 → 0.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "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.11"
   },
   "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.)
   // 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) {
     // Simple PoC format - content was passed directly
     content = block.parsedContent.raw
+    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,98 @@
+/**
+ * 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 content structure exists
+ * Returns a content object with all standard paths guaranteed to exist
+ *
+ * @param {Object} parsedContent - Raw parsed content from semantic parser
+ * @returns {Object} Content with guaranteed structure
+ */
+export function guaranteeContentStructure(parsedContent) {
+  const content = parsedContent || {}
+
+  return {
+    // Main content section
+    main: {
+      header: {
+        title: content.main?.header?.title || '',
+        pretitle: content.main?.header?.pretitle || '',
+        subtitle: content.main?.header?.subtitle || '',
+      },
+      body: {
+        paragraphs: content.main?.body?.paragraphs || [],
+        links: content.main?.body?.links || [],
+        imgs: content.main?.body?.imgs || [],
+        lists: content.main?.body?.lists || [],
+        icons: content.main?.body?.icons || [],
+      },
+    },
+    // Content items (H3 sections)
+    items: content.items || [],
+    // Preserve any additional fields from parser
+    ...content,
+  }
+}
+
+/**
+ * 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) || {}
+}