@uniweb/build 0.1.2 → 0.1.5

package/src/docs.js

@@ -0,0 +1,217 @@
+/**
+ * Documentation Generator
+ *
+ * Generates markdown documentation from foundation schema.json
+ * or directly from component meta files.
+ */
+
+import { readFile, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { buildSchema } from './schema.js'
+
+/**
+ * Generate markdown documentation for a single component
+ *
+ * @param {string} name - Component name
+ * @param {Object} meta - Component metadata
+ * @returns {string} Markdown content
+ */
+function generateComponentDocs(name, meta) {
+  const lines = []
+
+  // Component header
+  lines.push(`## ${name}`)
+  lines.push('')
+
+  // Description
+  if (meta.description) {
+    lines.push(meta.description)
+    lines.push('')
+  }
+
+  // Category badge
+  if (meta.category) {
+    lines.push(`**Category:** ${meta.category}`)
+    lines.push('')
+  }
+
+  // Content Elements
+  if (meta.elements && Object.keys(meta.elements).length > 0) {
+    lines.push('### Content Elements')
+    lines.push('')
+    lines.push('| Element | Label | Required | Description |')
+    lines.push('|---------|-------|----------|-------------|')
+
+    for (const [key, element] of Object.entries(meta.elements)) {
+      const label = element.label || key
+      const required = element.required ? 'Yes' : ''
+      const description = element.description || ''
+      lines.push(`| \`${key}\` | ${label} | ${required} | ${description} |`)
+    }
+    lines.push('')
+  }
+
+  // Parameters/Properties
+  if (meta.properties && Object.keys(meta.properties).length > 0) {
+    lines.push('### Parameters')
+    lines.push('')
+    lines.push('| Parameter | Type | Default | Description |')
+    lines.push('|-----------|------|---------|-------------|')
+
+    for (const [key, prop] of Object.entries(meta.properties)) {
+      const type = prop.type || 'string'
+      const defaultVal = prop.default !== undefined ? `\`${prop.default}\`` : ''
+      let description = prop.label || ''
+
+      // Add options for select type
+      if (prop.type === 'select' && prop.options) {
+        const optionValues = prop.options.map(o =>
+          typeof o === 'object' ? o.value : o
+        ).join(', ')
+        description += description ? ` (${optionValues})` : optionValues
+      }
+
+      lines.push(`| \`${key}\` | ${type} | ${defaultVal} | ${description} |`)
+    }
+    lines.push('')
+  }
+
+  // Presets
+  if (meta.presets && meta.presets.length > 0) {
+    lines.push('### Presets')
+    lines.push('')
+
+    for (const preset of meta.presets) {
+      const settings = preset.settings
+        ? Object.entries(preset.settings)
+            .map(([k, v]) => `${k}: ${v}`)
+            .join(', ')
+        : ''
+      lines.push(`- **${preset.name}** - ${preset.label || ''} ${settings ? `(${settings})` : ''}`)
+    }
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate full markdown documentation for a foundation
+ *
+ * @param {Object} schema - Foundation schema object
+ * @param {Object} options - Generation options
+ * @param {string} [options.title] - Document title
+ * @returns {string} Complete markdown documentation
+ */
+export function generateDocsFromSchema(schema, options = {}) {
+  const { title = 'Foundation Components' } = options
+  const lines = []
+
+  // Header
+  lines.push(`# ${title}`)
+  lines.push('')
+
+  // Foundation info
+  const foundationMeta = schema._self
+  if (foundationMeta) {
+    if (foundationMeta.name) {
+      lines.push(`**${foundationMeta.name}**`)
+      lines.push('')
+    }
+    if (foundationMeta.description) {
+      lines.push(foundationMeta.description)
+      lines.push('')
+    }
+  }
+
+  lines.push('---')
+  lines.push('')
+
+  // Table of contents
+  const componentNames = Object.keys(schema).filter(k => k !== '_self')
+
+  if (componentNames.length > 0) {
+    lines.push('## Components')
+    lines.push('')
+    for (const name of componentNames) {
+      const meta = schema[name]
+      const title = meta.title || name
+      lines.push(`- [${title}](#${name.toLowerCase()}) - ${meta.description || ''}`)
+    }
+    lines.push('')
+    lines.push('---')
+    lines.push('')
+  }
+
+  // Component documentation
+  for (const name of componentNames) {
+    const meta = schema[name]
+    lines.push(generateComponentDocs(name, meta))
+    lines.push('---')
+    lines.push('')
+  }
+
+  // Footer
+  lines.push('*Generated from foundation schema*')
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate documentation for a foundation directory
+ *
+ * Can read from existing schema.json or build schema from source.
+ *
+ * @param {string} foundationDir - Path to foundation directory
+ * @param {Object} options - Options
+ * @param {string} [options.output] - Output file path (default: COMPONENTS.md)
+ * @param {boolean} [options.fromSource] - Build schema from source instead of dist
+ * @returns {Promise<{outputPath: string, componentCount: number}>}
+ */
+export async function generateDocs(foundationDir, options = {}) {
+  const {
+    output = 'COMPONENTS.md',
+    fromSource = false,
+  } = options
+
+  let schema
+
+  // Try to load schema.json from dist
+  const schemaPath = join(foundationDir, 'dist', 'schema.json')
+
+  if (!fromSource && existsSync(schemaPath)) {
+    // Load from existing schema.json
+    const schemaContent = await readFile(schemaPath, 'utf-8')
+    schema = JSON.parse(schemaContent)
+  } else {
+    // Build schema from source
+    const srcDir = join(foundationDir, 'src')
+    if (!existsSync(srcDir)) {
+      throw new Error(`Source directory not found: ${srcDir}`)
+    }
+    schema = await buildSchema(srcDir)
+  }
+
+  // Get foundation name for title
+  const pkgPath = join(foundationDir, 'package.json')
+  let title = 'Foundation Components'
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
+    if (pkg.name) {
+      title = `${pkg.name} Components`
+    }
+  }
+
+  // Generate markdown
+  const markdown = generateDocsFromSchema(schema, { title })
+
+  // Write output
+  const outputPath = join(foundationDir, output)
+  await writeFile(outputPath, markdown)
+
+  // Count components
+  const componentCount = Object.keys(schema).filter(k => k !== '_self').length
+
+  return { outputPath, componentCount }
+}

package/src/images.js

@@ -2,6 +2,8 @@
  * Image Processing Utilities
  *
  * Handles preview image discovery, conversion to webp, and metadata extraction.
+ * Preview images are editor metadata (for preset visualization) and are output
+ * to dist/meta/previews/ to keep them separate from runtime assets.
  */
 
 import { readdir, mkdir, copyFile } from 'node:fs/promises'
@@ -71,8 +73,8 @@ export async function processComponentPreviews(componentDir, componentName, outp
     return previews
   }
 
-  // Create output directory
-  const componentOutputDir = join(outputDir, 'assets', componentName)
+  // Create output directory for preview images (editor metadata)
+  const componentOutputDir = join(outputDir, 'meta', 'previews', componentName)
   await mkdir(componentOutputDir, { recursive: true })
 
   // Get all image files
@@ -115,7 +117,7 @@ export async function processComponentPreviews(componentDir, componentName, outp
     }
 
     previews[presetName] = {
-      path: `assets/${componentName}/${outputFilename}`,
+      path: `meta/previews/${componentName}/${outputFilename}`,
       width: metadata.width,
       height: metadata.height,
       type: finalFormat,

package/src/index.js

@@ -35,5 +35,16 @@ export {
   foundationDevPlugin,
 } from './vite-foundation-plugin.js'
 
+// SSG Prerendering
+export {
+  prerenderSite,
+} from './prerender.js'
+
+// Documentation generation
+export {
+  generateDocs,
+  generateDocsFromSchema,
+} from './docs.js'
+
 // Default export is the combined Vite plugin
 export { default } from './vite-foundation-plugin.js'

package/src/prerender.js

@@ -0,0 +1,310 @@
+/**
+ * SSG Prerendering for Uniweb Sites
+ *
+ * Renders each page to static HTML at build time.
+ * The output includes full HTML with hydration support.
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// Lazily loaded dependencies (ESM with React)
+let React, renderToString, createUniweb
+
+/**
+ * Load dependencies dynamically
+ * These are ESM modules that may not be available at import time
+ */
+async function loadDependencies() {
+  if (React) return // Already loaded
+
+  const [reactMod, serverMod, coreMod] = await Promise.all([
+    import('react'),
+    import('react-dom/server'),
+    import('@uniweb/core')
+  ])
+
+  React = reactMod.default || reactMod
+  renderToString = serverMod.renderToString
+  createUniweb = coreMod.createUniweb
+}
+
+/**
+ * Pre-render all pages in a built site to static HTML
+ *
+ * @param {string} siteDir - Path to the site directory
+ * @param {Object} options
+ * @param {string} options.foundationDir - Path to foundation directory (default: ../foundation)
+ * @param {function} options.onProgress - Progress callback
+ * @returns {Promise<{pages: number, files: string[]}>}
+ */
+export async function prerenderSite(siteDir, options = {}) {
+  const {
+    foundationDir = join(siteDir, '..', 'foundation'),
+    onProgress = () => {}
+  } = options
+
+  const distDir = join(siteDir, 'dist')
+
+  // Verify build exists
+  if (!existsSync(distDir)) {
+    throw new Error(`Site must be built first. No dist directory found at: ${distDir}`)
+  }
+
+  // Load dependencies
+  onProgress('Loading dependencies...')
+  await loadDependencies()
+
+  // Load site content
+  onProgress('Loading site content...')
+  const contentPath = join(distDir, 'site-content.json')
+  if (!existsSync(contentPath)) {
+    throw new Error(`site-content.json not found at: ${contentPath}`)
+  }
+  const siteContent = JSON.parse(await readFile(contentPath, 'utf8'))
+
+  // Load the HTML shell
+  onProgress('Loading HTML shell...')
+  const shellPath = join(distDir, 'index.html')
+  if (!existsSync(shellPath)) {
+    throw new Error(`index.html not found at: ${shellPath}`)
+  }
+  const htmlShell = await readFile(shellPath, 'utf8')
+
+  // Load the foundation module
+  onProgress('Loading foundation...')
+  const foundationPath = join(foundationDir, 'dist', 'foundation.js')
+  if (!existsSync(foundationPath)) {
+    throw new Error(`Foundation not found at: ${foundationPath}. Build foundation first.`)
+  }
+  const foundationUrl = pathToFileURL(foundationPath).href
+  const foundation = await import(foundationUrl)
+
+  // Initialize the Uniweb runtime (this sets globalThis.uniweb)
+  onProgress('Initializing runtime...')
+  const uniweb = createUniweb(siteContent)
+  uniweb.setFoundation(foundation)
+
+  if (foundation.config || foundation.site) {
+    uniweb.setFoundationConfig(foundation.config || foundation.site)
+  }
+
+  // Pre-render each page
+  const renderedFiles = []
+  const pages = uniweb.activeWebsite.pages
+
+  for (const page of pages) {
+    const route = page.route
+    onProgress(`Rendering ${route}...`)
+
+    // Set this as the active page
+    uniweb.activeWebsite.setActivePage(route)
+
+    // Create the page element
+    // Note: We don't need StaticRouter for SSG since we're just rendering
+    // components to strings. The routing context isn't needed for static HTML.
+    const element = React.createElement(PageRenderer, { page, foundation })
+
+    // Render to HTML string
+    let renderedContent
+    try {
+      renderedContent = renderToString(element)
+    } catch (err) {
+      console.warn(`Warning: Failed to render ${route}: ${err.message}`)
+      if (process.env.DEBUG) {
+        console.error(err.stack)
+      }
+      continue
+    }
+
+    // Inject into shell
+    const html = injectContent(htmlShell, renderedContent, page, siteContent)
+
+    // Determine output path
+    const outputPath = getOutputPath(distDir, route)
+    await mkdir(dirname(outputPath), { recursive: true })
+    await writeFile(outputPath, html)
+
+    renderedFiles.push(outputPath)
+    onProgress(`  → ${outputPath.replace(distDir, 'dist')}`)
+  }
+
+  onProgress(`Pre-rendered ${renderedFiles.length} pages`)
+
+  return {
+    pages: renderedFiles.length,
+    files: renderedFiles
+  }
+}
+
+/**
+ * Minimal page renderer for SSG
+ * Renders blocks using foundation components
+ */
+function PageRenderer({ page, foundation }) {
+  const blocks = page.getPageBlocks()
+
+  return React.createElement(
+    'main',
+    null,
+    blocks.map((block, index) =>
+      React.createElement(BlockRenderer, {
+        key: block.id || index,
+        block,
+        foundation
+      })
+    )
+  )
+}
+
+/**
+ * Block renderer - maps block to foundation component
+ */
+function BlockRenderer({ block, foundation }) {
+  // Get component from foundation
+  const componentName = block.component
+  let Component = null
+
+  if (typeof foundation.getComponent === 'function') {
+    Component = foundation.getComponent(componentName)
+  } else if (foundation[componentName]) {
+    Component = foundation[componentName]
+  }
+
+  if (!Component) {
+    // Return placeholder for unknown components
+    return React.createElement(
+      'div',
+      {
+        className: 'block-placeholder',
+        'data-component': componentName,
+        style: { display: 'none' }
+      },
+      `Component: ${componentName}`
+    )
+  }
+
+  // Build content object (same as runtime's BlockRenderer)
+  let content
+  if (block.parsedContent?.raw) {
+    content = block.parsedContent.raw
+  } else {
+    content = {
+      ...block.parsedContent,
+      ...block.properties,
+      _prosemirror: block.parsedContent
+    }
+  }
+
+  // Build wrapper props
+  const theme = block.themeName
+  const className = theme || ''
+  const wrapperProps = {
+    id: `Section${block.id}`,
+    className
+  }
+
+  // Component props
+  const componentProps = {
+    content,
+    params: block.properties,
+    block,
+    page: globalThis.uniweb?.activeWebsite?.activePage,
+    website: globalThis.uniweb?.activeWebsite,
+    input: block.input
+  }
+
+  return React.createElement(
+    'div',
+    wrapperProps,
+    React.createElement(Component, componentProps)
+  )
+}
+
+/**
+ * Inject rendered content into HTML shell
+ */
+function injectContent(shell, renderedContent, page, siteContent) {
+  let html = shell
+
+  // Replace the empty root div with pre-rendered content
+  // Handle various formats of root div
+  html = html.replace(
+    /<div id="root">[\s\S]*?<\/div>/,
+    `<div id="root">${renderedContent}</div>`
+  )
+
+  // Update page title
+  if (page.title) {
+    html = html.replace(
+      /<title>.*?<\/title>/,
+      `<title>${escapeHtml(page.title)}</title>`
+    )
+  }
+
+  // Add meta description if available
+  if (page.description) {
+    const metaDesc = `<meta name="description" content="${escapeHtml(page.description)}">`
+    if (html.includes('<meta name="description"')) {
+      html = html.replace(
+        /<meta name="description"[^>]*>/,
+        metaDesc
+      )
+    } else {
+      html = html.replace(
+        '</head>',
+        `  ${metaDesc}\n  </head>`
+      )
+    }
+  }
+
+  // Inject site content as JSON for hydration
+  // This allows the client-side React to hydrate with the same data
+  const contentScript = `<script id="__SITE_CONTENT__" type="application/json">${JSON.stringify(siteContent)}</script>`
+  if (!html.includes('__SITE_CONTENT__')) {
+    html = html.replace(
+      '</head>',
+      `  ${contentScript}\n  </head>`
+    )
+  }
+
+  return html
+}
+
+/**
+ * Get output path for a route
+ */
+function getOutputPath(distDir, route) {
+  // Normalize route
+  let normalizedRoute = route
+
+  // Handle root route
+  if (normalizedRoute === '/' || normalizedRoute === '') {
+    return join(distDir, 'index.html')
+  }
+
+  // Remove leading slash
+  if (normalizedRoute.startsWith('/')) {
+    normalizedRoute = normalizedRoute.slice(1)
+  }
+
+  // Create directory structure: /about -> /about/index.html
+  return join(distDir, normalizedRoute, 'index.html')
+}
+
+/**
+ * Escape HTML special characters
+ */
+function escapeHtml(str) {
+  if (!str) return ''
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+export default prerenderSite