@uniweb/build 0.1.32 → 0.2.0

package/src/site/content-collector.js

@@ -28,6 +28,7 @@ import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { collectSectionAssets, mergeAssetCollections } from './assets.js'
 import { parseFetchConfig, singularize } from './data-fetcher.js'
+import { buildTheme, extractFoundationVars } from '../theme/index.js'
 
 // Try to import content-reader, fall back to simplified parser
 let markdownToProseMirror
@@ -66,6 +67,90 @@ function extractRouteParam(folderName) {
   return match ? match[1] : null
 }
 
+// ─────────────────────────────────────────────────────────────────
+// Version Detection
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Check if a folder name represents a version (e.g., v1, v2, v1.0, v2.1)
+ * @param {string} folderName - The folder name to check
+ * @returns {boolean}
+ */
+function isVersionFolder(folderName) {
+  return /^v\d+(\.\d+)?$/.test(folderName)
+}
+
+/**
+ * Parse version info from folder name
+ * @param {string} folderName - The folder name (e.g., "v1", "v2.1")
+ * @returns {Object} Version info { id, major, minor, sortKey }
+ */
+function parseVersionInfo(folderName) {
+  const match = folderName.match(/^v(\d+)(?:\.(\d+))?$/)
+  if (!match) return null
+
+  const major = parseInt(match[1], 10)
+  const minor = match[2] ? parseInt(match[2], 10) : 0
+
+  return {
+    id: folderName,
+    major,
+    minor,
+    sortKey: major * 1000 + minor // For sorting: v2.1 > v2.0 > v1.9
+  }
+}
+
+/**
+ * Detect if a set of folders contains version folders
+ * @param {Array<string>} folderNames - List of folder names
+ * @returns {Array<Object>|null} Sorted version infos (highest first) or null if not versioned
+ */
+function detectVersions(folderNames) {
+  const versions = folderNames
+    .filter(isVersionFolder)
+    .map(parseVersionInfo)
+    .filter(Boolean)
+
+  if (versions.length === 0) return null
+
+  // Sort by version (highest first)
+  versions.sort((a, b) => b.sortKey - a.sortKey)
+
+  return versions
+}
+
+/**
+ * Build version metadata from detected versions and page.yml config
+ * @param {Array<Object>} detectedVersions - Detected version infos
+ * @param {Object} pageConfig - page.yml configuration
+ * @returns {Object} Version metadata { versions, latestId, scope }
+ */
+function buildVersionMetadata(detectedVersions, pageConfig = {}) {
+  const configVersions = pageConfig.versions || {}
+
+  // Build version list with metadata
+  const versions = detectedVersions.map((v, index) => {
+    const config = configVersions[v.id] || {}
+    const isLatest = config.latest === true || (index === 0 && !Object.values(configVersions).some(c => c.latest))
+
+    return {
+      id: v.id,
+      label: config.label || v.id,
+      latest: isLatest,
+      deprecated: config.deprecated || false,
+      sortKey: v.sortKey
+    }
+  })
+
+  // Find the latest version
+  const latestVersion = versions.find(v => v.latest) || versions[0]
+
+  return {
+    versions,
+    latestId: latestVersion?.id || null
+  }
+}
+
 /**
  * Parse YAML string using js-yaml
  */
@@ -143,11 +228,12 @@ function compareFilenames(a, b) {
  * Process a markdown file into a section
  *
  * @param {string} filePath - Path to markdown file
- * @param {string} id - Section ID
+ * @param {string} id - Section ID (numeric/positional)
  * @param {string} siteRoot - Site root directory for asset resolution
+ * @param {string} defaultStableId - Default stable ID from filename (can be overridden in frontmatter)
  * @returns {Object} Section data with assets manifest
  */
-async function processMarkdownFile(filePath, id, siteRoot) {
+async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = null) {
   const content = await readFile(filePath, 'utf8')
   let frontMatter = {}
   let markdown = content
@@ -161,19 +247,33 @@ async function processMarkdownFile(filePath, id, siteRoot) {
     }
   }
 
-  const { type, component, preset, input, props, fetch, ...params } = frontMatter
+  const { type, component, preset, input, props, fetch, data, id: frontmatterId, ...params } = frontMatter
 
   // Convert markdown to ProseMirror
   const proseMirrorContent = markdownToProseMirror(markdown)
 
+  // Support 'data:' shorthand for collection fetch
+  // data: team → fetch: { collection: team }
+  // data: [team, articles] → fetch: { collection: team } (first item, others via inheritData)
+  let resolvedFetch = fetch
+  if (!fetch && data) {
+    const collectionName = Array.isArray(data) ? data[0] : data
+    resolvedFetch = { collection: collectionName }
+  }
+
+  // Stable ID for scroll targeting: frontmatter id > filename-derived > null
+  // This ID is stable across reordering (unlike the positional id)
+  const stableId = frontmatterId || defaultStableId || null
+
   const section = {
     id,
+    stableId,
     component: type || component || 'Section',
     preset,
     input,
     params: { ...params, ...props },
     content: proseMirrorContent,
-    fetch: parseFetchConfig(fetch),
+    fetch: parseFetchConfig(resolvedFetch),
     subsections: []
   }
 
@@ -280,7 +380,8 @@ async function processExplicitSections(sectionsConfig, pagePath, siteRoot, paren
     }
 
     // Process the section
-    const { section, assetCollection: sectionAssets } = await processMarkdownFile(filePath, id, siteRoot)
+    // Use sectionName as stable ID for scroll targeting (e.g., "hero", "features")
+    const { section, assetCollection: sectionAssets } = await processMarkdownFile(filePath, id, siteRoot, sectionName)
     assetCollection = mergeAssetCollections(assetCollection, sectionAssets)
 
     // Track last modified
@@ -316,9 +417,10 @@ async function processExplicitSections(sectionsConfig, pagePath, siteRoot, paren
  * @param {boolean} options.isIndex - Whether this page is the index for its parent route
  * @param {string} options.parentRoute - The parent route (e.g., '/' or '/docs')
  * @param {Object} options.parentFetch - Parent page's fetch config (for dynamic routes)
+ * @param {Object} options.versionContext - Version context from parent { version, versionMeta, scope }
  * @returns {Object} Page data with assets manifest
  */
-async function processPage(pagePath, pageName, siteRoot, { isIndex = false, parentRoute = '/', parentFetch = null } = {}) {
+async function processPage(pagePath, pageName, siteRoot, { isIndex = false, parentRoute = '/', parentFetch = null, versionContext = null } = {}) {
   const pageConfig = await readYamlFile(join(pagePath, 'page.yml'))
 
   // Note: We no longer skip hidden pages here - they still exist as valid pages,
@@ -344,10 +446,13 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
     const sections = []
     for (const file of mdFiles) {
       const { name } = parse(file)
-      const { prefix } = parseNumericPrefix(name)
+      const { prefix, name: stableName } = parseNumericPrefix(name)
       const id = prefix || name
+      // Use the name part (after prefix) as stable ID for scroll targeting
+      // e.g., "1-intro.md" → stableId: "intro", "2-features.md" → stableId: "features"
+      const stableId = stableName || name
 
-      const { section, assetCollection } = await processMarkdownFile(join(pagePath, file), id, siteRoot)
+      const { section, assetCollection } = await processMarkdownFile(join(pagePath, file), id, siteRoot, stableId)
       sections.push(section)
       pageAssetCollection = mergeAssetCollections(pageAssetCollection, assetCollection)
 
@@ -405,6 +510,7 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
   return {
     page: {
       route,
+      id: pageConfig.id || null, // Stable page ID for page: links (survives reorganization)
       isIndex, // Marks this page as the index for its parent route (accessible at parentRoute)
       title: pageConfig.title || pageName,
       description: pageConfig.description || '',
@@ -417,6 +523,11 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
       paramName, // e.g., "slug" from [slug]
       parentSchema, // e.g., "articles" - the data array to iterate over
 
+      // Version metadata (if within a versioned section)
+      version: versionContext?.version || null,
+      versionMeta: versionContext?.versionMeta || null,
+      versionScope: versionContext?.scope || null,
+
       // Navigation options
       hidden: pageConfig.hidden || false, // Hide from all navigation
       hideInHeader: pageConfig.hideInHeader || false, // Hide from header nav
@@ -438,7 +549,13 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
       },
 
       // Data fetching
-      fetch: parseFetchConfig(pageConfig.fetch),
+      // Support 'data:' shorthand at page level
+      // data: team → fetch: { collection: team }
+      fetch: parseFetchConfig(
+        pageConfig.fetch || (pageConfig.data
+          ? { collection: Array.isArray(pageConfig.data) ? pageConfig.data[0] : pageConfig.data }
+          : undefined)
+      ),
 
       sections: hierarchicalSections
     },
@@ -488,9 +605,10 @@ function determineIndexPage(orderConfig, availableFolders) {
  * @param {string} siteRoot - Site root directory for asset resolution
  * @param {Object} orderConfig - { pages: [...], index: 'name' } from parent's config
  * @param {Object} parentFetch - Parent page's fetch config (for dynamic child routes)
- * @returns {Promise<Object>} { pages, assetCollection, header, footer, left, right, notFound }
+ * @param {Object} versionContext - Version context from parent { version, versionMeta }
+ * @returns {Promise<Object>} { pages, assetCollection, header, footer, left, right, notFound, versionedScopes }
  */
-async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null) {
+async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, versionContext = null) {
   const entries = await readdir(dirPath)
   const pages = []
   let assetCollection = {
@@ -503,6 +621,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
   let left = null
   let right = null
   let notFound = null
+  const versionedScopes = new Map() // scope route → versionMeta
 
   // First pass: discover all page folders and read their order values
   const pageFolders = []
@@ -517,6 +636,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
       name: entry,
       path: entryPath,
       order: pageConfig.order,
+      pageConfig,
       childOrderConfig: {
         pages: pageConfig.pages,
         index: pageConfig.index
@@ -524,6 +644,72 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     })
   }
 
+  // Check if this directory contains version folders (versioned section)
+  const folderNames = pageFolders.map(f => f.name)
+  const detectedVersions = detectVersions(folderNames)
+
+  // If versioned section, handle version folders specially
+  if (detectedVersions && !versionContext) {
+    // Read parent page.yml for version metadata
+    const parentConfig = await readYamlFile(join(dirPath, 'page.yml'))
+    const versionMeta = buildVersionMetadata(detectedVersions, parentConfig)
+
+    // Record this versioned scope
+    versionedScopes.set(parentRoute, versionMeta)
+
+    // Process version folders
+    for (const folder of pageFolders) {
+      const { name: entry, path: entryPath, childOrderConfig, pageConfig } = folder
+
+      if (isVersionFolder(entry)) {
+        // This is a version folder
+        const versionInfo = versionMeta.versions.find(v => v.id === entry)
+        const isLatest = versionInfo?.latest || false
+
+        // For latest version, use parent route directly
+        // For other versions, add version prefix to route
+        const versionRoute = isLatest ? parentRoute : `${parentRoute}/${entry}`
+
+        // Recurse into version folder with version context
+        const subResult = await collectPagesRecursive(
+          entryPath,
+          versionRoute,
+          siteRoot,
+          childOrderConfig,
+          parentFetch,
+          {
+            version: versionInfo,
+            versionMeta,
+            scope: parentRoute // The route where versioning is scoped
+          }
+        )
+
+        pages.push(...subResult.pages)
+        assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
+        // Merge any nested versioned scopes (shouldn't happen often, but possible)
+        for (const [scope, meta] of subResult.versionedScopes) {
+          versionedScopes.set(scope, meta)
+        }
+      } else if (!entry.startsWith('@')) {
+        // Non-version, non-special folders in a versioned section
+        // These could be shared across versions - process normally
+        const result = await processPage(entryPath, entry, siteRoot, {
+          isIndex: false,
+          parentRoute,
+          parentFetch
+        })
+
+        if (result) {
+          pages.push(result.page)
+          assetCollection = mergeAssetCollections(assetCollection, result.assetCollection)
+        }
+      }
+    }
+
+    // Return early - we've handled all children
+    return { pages, assetCollection, header, footer, left, right, notFound, versionedScopes }
+  }
+
   // Determine which page is the index for this level
   const regularFolders = pageFolders.filter(f => !f.name.startsWith('@'))
   const indexPageName = determineIndexPage(orderConfig, regularFolders)
@@ -539,7 +725,8 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     const result = await processPage(entryPath, entry, siteRoot, {
       isIndex: isIndex && !isSpecial,
       parentRoute,
-      parentFetch
+      parentFetch,
+      versionContext
     })
 
     if (result) {
@@ -571,34 +758,84 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
         const childParentRoute = isIndex ? parentRoute : page.route
         // Pass this page's fetch config to children (for dynamic routes that inherit parent data)
         const childFetch = page.fetch || parentFetch
-        const subResult = await collectPagesRecursive(entryPath, childParentRoute, siteRoot, childOrderConfig, childFetch)
+        // Pass version context to children (maintains version scope)
+        const subResult = await collectPagesRecursive(entryPath, childParentRoute, siteRoot, childOrderConfig, childFetch, versionContext)
         pages.push(...subResult.pages)
         assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
+        // Merge any versioned scopes from children
+        for (const [scope, meta] of subResult.versionedScopes) {
+          versionedScopes.set(scope, meta)
+        }
       }
     }
   }
 
-  return { pages, assetCollection, header, footer, left, right, notFound }
+  return { pages, assetCollection, header, footer, left, right, notFound, versionedScopes }
+}
+
+/**
+ * Load foundation variables from schema.json
+ *
+ * @param {string} foundationPath - Path to foundation directory
+ * @returns {Promise<Object>} Foundation variables or empty object
+ */
+async function loadFoundationVars(foundationPath) {
+  if (!foundationPath) return {}
+
+  // Try dist/meta/schema.json first (built foundation), then root schema.json
+  const distSchemaPath = join(foundationPath, 'dist', 'meta', 'schema.json')
+  const rootSchemaPath = join(foundationPath, 'schema.json')
+
+  const schemaPath = existsSync(distSchemaPath) ? distSchemaPath : rootSchemaPath
+
+  if (!existsSync(schemaPath)) {
+    return {}
+  }
+
+  try {
+    const schemaContent = await readFile(schemaPath, 'utf8')
+    const schema = JSON.parse(schemaContent)
+    // Foundation config is in _self, support both 'vars' (new) and 'themeVars' (legacy)
+    return schema._self?.vars || schema._self?.themeVars || schema.themeVars || {}
+  } catch (err) {
+    console.warn('[content-collector] Failed to load foundation schema:', err.message)
+    return {}
+  }
 }
 
 /**
  * Collect all site content
  *
  * @param {string} sitePath - Path to site directory
+ * @param {Object} options - Collection options
+ * @param {string} options.foundationPath - Path to foundation directory (for theme vars)
  * @returns {Promise<Object>} Site content object with assets manifest
  */
-export async function collectSiteContent(sitePath) {
+export async function collectSiteContent(sitePath, options = {}) {
+  const { foundationPath } = options
   const pagesPath = join(sitePath, 'pages')
 
-  // Read site config
+  // Read site config and raw theme config
   const siteConfig = await readYamlFile(join(sitePath, 'site.yml'))
-  const themeConfig = await readYamlFile(join(sitePath, 'theme.yml'))
+  const rawThemeConfig = await readYamlFile(join(sitePath, 'theme.yml'))
+
+  // Load foundation vars and process theme
+  const foundationVars = await loadFoundationVars(foundationPath)
+  const { config: processedTheme, css: themeCSS, warnings } = buildTheme(rawThemeConfig, { foundationVars })
+
+  // Log theme warnings
+  if (warnings?.length > 0) {
+    warnings.forEach(w => console.warn(`[theme] ${w}`))
+  }
 
   // Check if pages directory exists
   if (!existsSync(pagesPath)) {
     return {
       config: siteConfig,
-      theme: themeConfig,
+      theme: {
+        ...processedTheme,
+        css: themeCSS
+      },
       pages: [],
       assets: {}
     }
@@ -611,7 +848,7 @@ export async function collectSiteContent(sitePath) {
   }
 
   // Recursively collect all pages
-  const { pages, assetCollection, header, footer, left, right, notFound } =
+  const { pages, assetCollection, header, footer, left, right, notFound, versionedScopes } =
     await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig)
 
   // Sort pages by order
@@ -624,18 +861,26 @@ export async function collectSiteContent(sitePath) {
     console.log(`[content-collector] Found ${assetCount} asset references${explicitCount > 0 ? ` (${explicitCount} with explicit poster/preview)` : ''}`)
   }
 
+  // Convert versionedScopes Map to plain object for JSON serialization
+  const versionedScopesObj = Object.fromEntries(versionedScopes)
+
   return {
     config: {
       ...siteConfig,
       fetch: parseFetchConfig(siteConfig.fetch),
     },
-    theme: themeConfig,
+    theme: {
+      ...processedTheme,
+      css: themeCSS
+    },
     pages,
     header,
     footer,
     left,
     right,
     notFound,
+    // Versioned scopes: route → { versions, latestId }
+    versionedScopes: versionedScopesObj,
     assets: assetCollection.assets,
     hasExplicitPoster: assetCollection.hasExplicitPoster,
     hasExplicitPreview: assetCollection.hasExplicitPreview

package/src/site/plugin.js

@@ -305,6 +305,7 @@ function escapeHtml(str) {
  * @param {Object} [options.search] - Search index configuration
  * @param {boolean} [options.search.enabled=true] - Generate search index (uses site.yml config by default)
  * @param {string} [options.search.filename='search-index.json'] - Search index filename
+ * @param {string} [options.foundationPath] - Path to foundation directory (for loading theme vars)
  */
 export function siteContentPlugin(options = {}) {
   const {
@@ -316,7 +317,8 @@ export function siteContentPlugin(options = {}) {
     watch: shouldWatch = true,
     seo = {},
     assets: assetsConfig = {},
-    search: searchPluginConfig = {}
+    search: searchPluginConfig = {},
+    foundationPath
   } = options
 
   // Extract asset processing options
@@ -416,7 +418,7 @@ export function siteContentPlugin(options = {}) {
       if (!isProduction) {
         try {
           // Do an early content collection to get the collections config
-          const earlyContent = await collectSiteContent(resolvedSitePath)
+          const earlyContent = await collectSiteContent(resolvedSitePath, { foundationPath })
           collectionsConfig = earlyContent.config?.collections
 
           if (collectionsConfig) {
@@ -433,7 +435,7 @@ export function siteContentPlugin(options = {}) {
     async buildStart() {
       // Collect content at build start
       try {
-        siteContent = await collectSiteContent(resolvedSitePath)
+        siteContent = await collectSiteContent(resolvedSitePath, { foundationPath })
         console.log(`[site-content] Collected ${siteContent.pages?.length || 0} pages`)
 
         // Process content collections if defined in site.yml
@@ -480,7 +482,7 @@ export function siteContentPlugin(options = {}) {
           rebuildTimeout = setTimeout(async () => {
             console.log('[site-content] Content changed, rebuilding...')
             try {
-              siteContent = await collectSiteContent(resolvedSitePath)
+              siteContent = await collectSiteContent(resolvedSitePath, { foundationPath })
               // Execute fetches for the updated content
               await executeDevFetches(siteContent, resolvedSitePath)
               console.log(`[site-content] Rebuilt ${siteContent.pages?.length || 0} pages`)
@@ -685,6 +687,11 @@ export function siteContentPlugin(options = {}) {
 
       let headInjection = ''
 
+      // Inject theme CSS
+      if (contentToInject.theme?.css) {
+        headInjection += `    <style id="uniweb-theme">\n${contentToInject.theme.css}\n    </style>\n`
+      }
+
       // Inject SEO meta tags
       if (seoEnabled) {
         const metaTags = generateMetaTags(contentToInject, seoOptions)
@@ -791,6 +798,9 @@ export function siteContentPlugin(options = {}) {
       delete finalContent.hasExplicitPoster
       delete finalContent.hasExplicitPreview
 
+      // Note: theme.css is kept here so prerender can inject it into HTML
+      // Prerender will strip it from the JSON it injects into each page
+
       // Emit content as JSON file in production build
       this.emitFile({
         type: 'asset',