@uniweb/build 0.4.10 → 0.5.0

package/README.md

@@ -15,7 +15,7 @@ npm install @uniweb/build --save-dev
 ## Features
 
 **For Foundations:**
-- **Component Discovery** - Automatically discovers components from `src/components/*/meta.js`
+- **Component Discovery** - Discovers section types from `src/sections/` (implicit at root) and `src/components/` (requires `meta.js`)
 - **Entry Generation** - Generates the foundation entry point with all exports
 - **Schema Building** - Creates `schema.json` with full component metadata for editors
 - **Image Processing** - Converts preview images to WebP format
@@ -263,7 +263,7 @@ src/
 ### Component Meta File
 
 ```js
-// src/components/Hero/meta.js
+// src/sections/Hero/meta.js
 export default {
   title: 'Hero Banner',
   description: 'A prominent header section',
@@ -367,7 +367,7 @@ Identity fields (`name`, `version`, `description`) come from the foundation's `p
 
 | Function | Description |
 |----------|-------------|
-| `discoverComponents(srcDir)` | Discover all exposed components |
+| `discoverComponents(srcDir)` | Discover all section types (folders with meta.js) |
 | `loadComponentMeta(componentDir)` | Load meta file for a component |
 | `loadPackageJson(srcDir)` | Load identity from package.json |
 | `loadFoundationConfig(srcDir)` | Load foundation.js configuration |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.4.10",
+  "version": "0.5.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {

package/src/foundation/config.js

@@ -48,9 +48,9 @@ const DEFAULT_EXTERNALS = [
  * @param {Object} [options={}] - Configuration options
  * @param {string} [options.entry] - Entry point path (default: 'src/_entry.generated.js')
  * @param {string} [options.fileName] - Output file name (default: 'foundation')
- * @param {string[]} [options.components] - Paths to search for components (relative to src/).
- *                                          Default: ['components']
- *                                          Example: ['components', 'components/sections']
+ * @param {string[]} [options.components] - Paths to scan for content interfaces (relative to src/).
+ *                                          Default: ['sections', 'components']
+ *                                          Example: ['sections', 'sections/marketing']
  * @param {string[]} [options.externals] - Additional packages to externalize
  * @param {boolean} [options.includeDefaultExternals] - Include default externals (default: true)
  * @param {Array} [options.plugins] - Additional Vite plugins

package/src/generate-entry.js

@@ -112,10 +112,10 @@ function generateEntrySource(components, options = {}) {
     lines.push(`import capabilities from '${foundationExports.path}'`)
   }
 
-  // Component imports (use component's path and detected extension)
+  // Component imports
   for (const name of componentNames) {
-    const { path, ext = 'js' } = components[name]
-    lines.push(`import ${name} from './${path}/index.${ext}'`)
+    const { path, entryFile = `index.js` } = components[name]
+    lines.push(`import ${name} from './${path}/${entryFile}'`)
   }
 
   lines.push('')
@@ -153,19 +153,33 @@ function generateEntrySource(components, options = {}) {
 }
 
 /**
- * Detect the index file extension for a component
+ * Detect the entry file for a component
+ *
+ * Supports two conventions:
+ * - index.jsx (default)
+ * - ComponentName.jsx (named file matching the directory name)
+ *
+ * Named files are checked first so that Hero/Hero.jsx takes precedence
+ * over Hero/index.jsx when both exist (the named file is more intentional).
  *
  * @param {string} srcDir - Source directory
  * @param {string} componentPath - Relative path to component (e.g., 'components/Hero')
+ * @param {string} componentName - Component name (e.g., 'Hero')
+ * @returns {{ file: string, ext: string }} Entry file name and extension
  */
-function detectComponentExtension(srcDir, componentPath) {
+function detectComponentEntry(srcDir, componentPath, componentName) {
   const basePath = join(srcDir, componentPath)
   for (const ext of ['jsx', 'tsx', 'js', 'ts']) {
+    // Check named file first: Hero/Hero.jsx
+    if (existsSync(join(basePath, `${componentName}.${ext}`))) {
+      return { file: `${componentName}.${ext}`, ext }
+    }
+    // Then index file: Hero/index.jsx
     if (existsSync(join(basePath, `index.${ext}`))) {
-      return ext
+      return { file: `index.${ext}`, ext }
     }
   }
-  return 'js' // default
+  return { file: 'index.js', ext: 'js' } // default
 }
 
 /**
@@ -184,13 +198,18 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
   const componentNames = Object.keys(components).sort()
 
   if (componentNames.length === 0) {
-    console.warn('Warning: No exposed components found')
+    console.warn('Warning: No section types found')
   }
 
-  // Detect extensions for each component and add to component info
+  // Detect entry files for each component
+  // Bare files discovered in sections/ already have entryFile set — skip detection for those
   for (const name of componentNames) {
     const component = components[name]
-    component.ext = detectComponentExtension(srcDir, component.path)
+    if (!component.entryFile) {
+      const entry = detectComponentEntry(srcDir, component.path, component.name)
+      component.ext = entry.ext
+      component.entryFile = entry.file
+    }
   }
 
   // Check for CSS file

package/src/schema.js

@@ -3,12 +3,18 @@
  *
  * Discovers component meta files and loads them for schema.json generation.
  * Schema data is for editor-time only, not runtime.
+ *
+ * Discovery rules:
+ * - sections/ root: bare files and folders are addressable by default (implicit empty meta)
+ * - sections/ nested: meta.js required for addressability
+ * - components/ (and other paths): meta.js required (backward compatibility)
  */
 
 import { readdir, readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { join, dirname, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { inferTitle } from './utils/infer-title.js'
 
 // Component meta file name
 const META_FILE_NAME = 'meta.js'
@@ -16,8 +22,15 @@ const META_FILE_NAME = 'meta.js'
 // Foundation config file name
 const FOUNDATION_FILE_NAME = 'foundation.js'
 
-// Default component paths (relative to srcDir)
-const DEFAULT_COMPONENT_PATHS = ['components']
+// Default paths to scan for content interfaces (relative to srcDir)
+// sections/ is the primary convention; components/ supported for backward compatibility
+const DEFAULT_COMPONENT_PATHS = ['sections', 'components']
+
+// Extensions recognized as component entry files
+const COMPONENT_EXTENSIONS = new Set(['.jsx', '.tsx', '.js', '.ts'])
+
+// The primary sections path where relaxed discovery applies
+const SECTIONS_PATH = 'sections'
 
 /**
  * Load a meta.js file via dynamic import
@@ -113,12 +126,173 @@ export async function loadFoundationMeta(srcDir) {
 }
 
 /**
- * Discover components in a single path
+ * Check if a filename looks like a PascalCase component (starts with uppercase)
+ */
+function isComponentFileName(name) {
+  return /^[A-Z]/.test(name)
+}
+
+/**
+ * Check if a directory has a valid entry file (Name.ext or index.ext)
+ */
+function hasEntryFile(dirPath, dirName) {
+  for (const ext of ['.jsx', '.tsx', '.js', '.ts']) {
+    if (existsSync(join(dirPath, `${dirName}${ext}`))) return true
+    if (existsSync(join(dirPath, `index${ext}`))) return true
+  }
+  return false
+}
+
+/**
+ * Create an implicit empty meta for a section type discovered without meta.js
+ */
+function createImplicitMeta(name) {
+  return { title: inferTitle(name) }
+}
+
+/**
+ * Build a component entry with title inference applied
+ */
+function buildComponentEntry(name, relativePath, meta) {
+  const entry = {
+    name,
+    path: relativePath,
+    ...meta,
+  }
+  // Apply title inference if meta has no explicit title
+  if (!entry.title) {
+    entry.title = inferTitle(name)
+  }
+  return entry
+}
+
+/**
+ * Discover section types in sections/ with relaxed rules
+ *
+ * Root level: bare files and folders are addressable by default.
+ * Nested levels: meta.js required for addressability.
+ *
  * @param {string} srcDir - Source directory (e.g., 'src')
- * @param {string} relativePath - Path relative to srcDir (e.g., 'components' or 'components/sections')
+ * @param {string} sectionsRelPath - Relative path to sections dir (e.g., 'sections')
+ */
+async function discoverSectionsInPath(srcDir, sectionsRelPath) {
+  const fullPath = join(srcDir, sectionsRelPath)
+
+  if (!existsSync(fullPath)) {
+    return {}
+  }
+
+  const entries = await readdir(fullPath, { withFileTypes: true })
+  const components = {}
+
+  // Collect names from both files and directories to detect collisions
+  const fileNames = new Set()
+  const dirNames = new Set()
+
+  for (const entry of entries) {
+    const ext = extname(entry.name)
+    if (entry.isFile() && COMPONENT_EXTENSIONS.has(ext)) {
+      const name = basename(entry.name, ext)
+      if (isComponentFileName(name)) {
+        fileNames.add(name)
+      }
+    } else if (entry.isDirectory()) {
+      dirNames.add(entry.name)
+    }
+  }
+
+  // Check for name collisions (e.g., Hero.jsx AND Hero/)
+  for (const name of fileNames) {
+    if (dirNames.has(name)) {
+      throw new Error(
+        `Name collision in ${sectionsRelPath}/: both "${name}.jsx" (or similar) and "${name}/" exist. ` +
+        `Use one or the other, not both.`
+      )
+    }
+  }
+
+  // Discover bare files at root
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const ext = extname(entry.name)
+    if (!COMPONENT_EXTENSIONS.has(ext)) continue
+    const name = basename(entry.name, ext)
+    if (!isComponentFileName(name)) continue
+
+    const meta = createImplicitMeta(name)
+    components[name] = {
+      ...buildComponentEntry(name, sectionsRelPath, meta),
+      // Bare file: the entry file IS the file itself (not inside a subdirectory)
+      entryFile: entry.name,
+    }
+  }
+
+  // Discover directories at root
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    if (!isComponentFileName(entry.name)) continue
+
+    const dirPath = join(fullPath, entry.name)
+    const relativePath = join(sectionsRelPath, entry.name)
+    const result = await loadComponentMeta(dirPath)
+
+    if (result && result.meta) {
+      // Has meta.js — use explicit meta
+      if (result.meta.exposed === false) continue
+      components[entry.name] = buildComponentEntry(entry.name, relativePath, result.meta)
+    } else if (hasEntryFile(dirPath, entry.name)) {
+      // No meta.js but has entry file — implicit section type at root
+      components[entry.name] = buildComponentEntry(entry.name, relativePath, createImplicitMeta(entry.name))
+    }
+
+    // Recurse into subdirectories for nested section types (meta.js required)
+    await discoverNestedSections(srcDir, dirPath, relativePath, components)
+  }
+
+  return components
+}
+
+/**
+ * Recursively discover nested section types that have meta.js
+ *
+ * @param {string} srcDir - Source directory
+ * @param {string} parentFullPath - Absolute path to parent directory
+ * @param {string} parentRelPath - Relative path from srcDir to parent
+ * @param {Object} components - Accumulator for discovered components
+ */
+async function discoverNestedSections(srcDir, parentFullPath, parentRelPath, components) {
+  let entries
+  try {
+    entries = await readdir(parentFullPath, { withFileTypes: true })
+  } catch {
+    return
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+
+    const dirPath = join(parentFullPath, entry.name)
+    const relativePath = join(parentRelPath, entry.name)
+    const result = await loadComponentMeta(dirPath)
+
+    if (result && result.meta) {
+      if (result.meta.exposed === false) continue
+      components[entry.name] = buildComponentEntry(entry.name, relativePath, result.meta)
+    }
+
+    // Continue recursing regardless — deeper levels may have meta.js
+    await discoverNestedSections(srcDir, dirPath, relativePath, components)
+  }
+}
+
+/**
+ * Discover components in a non-sections path (meta.js required)
+ *
+ * @param {string} srcDir - Source directory (e.g., 'src')
+ * @param {string} relativePath - Path relative to srcDir (e.g., 'components')
  * @returns {Object} Map of componentName -> { name, path, ...meta }
  */
-async function discoverComponentsInPath(srcDir, relativePath) {
+async function discoverExplicitComponentsInPath(srcDir, relativePath) {
   const fullPath = join(srcDir, relativePath)
 
   if (!existsSync(fullPath)) {
@@ -135,16 +309,12 @@ async function discoverComponentsInPath(srcDir, relativePath) {
     const result = await loadComponentMeta(componentDir)
 
     if (result && result.meta) {
-      // Check if explicitly not exposed
+      // Check if explicitly hidden from discovery
       if (result.meta.exposed === false) {
         continue
       }
 
-      components[entry.name] = {
-        name: entry.name,
-        path: join(relativePath, entry.name), // e.g., 'components/Hero' or 'components/sections/Hero'
-        ...result.meta,
-      }
+      components[entry.name] = buildComponentEntry(entry.name, join(relativePath, entry.name), result.meta)
     }
   }
 
@@ -152,18 +322,25 @@ async function discoverComponentsInPath(srcDir, relativePath) {
 }
 
 /**
- * Discover all exposed components in a foundation
+ * Discover all section types in a foundation
+ *
+ * For the 'sections' path: relaxed discovery (bare files and folders at root,
+ * meta.js required for nested levels).
+ * For other paths: strict discovery (meta.js required).
  *
  * @param {string} srcDir - Source directory (e.g., 'src')
- * @param {string[]} [componentPaths] - Paths to search for components (relative to srcDir)
- *                                      Default: ['components']
- * @returns {Object} Map of componentName -> { name, path, ...meta }
+ * @param {string[]} [componentPaths] - Paths to scan for section types (relative to srcDir).
+ *                                      Default: ['sections', 'components']
+ * @returns {Object} Map of sectionTypeName -> { name, path, ...meta }
  */
 export async function discoverComponents(srcDir, componentPaths = DEFAULT_COMPONENT_PATHS) {
   const components = {}
 
   for (const relativePath of componentPaths) {
-    const found = await discoverComponentsInPath(srcDir, relativePath)
+    // Use relaxed discovery for the primary sections path
+    const found = relativePath === SECTIONS_PATH
+      ? await discoverSectionsInPath(srcDir, relativePath)
+      : await discoverExplicitComponentsInPath(srcDir, relativePath)
 
     for (const [name, meta] of Object.entries(found)) {
       if (components[name]) {
@@ -210,10 +387,10 @@ export async function buildSchema(srcDir, componentPaths) {
 }
 
 /**
- * Get list of exposed component names
+ * Get list of section type names
  *
  * @param {string} srcDir - Source directory
- * @param {string[]} [componentPaths] - Paths to search for components
+ * @param {string[]} [componentPaths] - Paths to scan for section types
  */
 export async function getExposedComponents(srcDir, componentPaths) {
   const components = await discoverComponents(srcDir, componentPaths)

package/src/utils/infer-title.js

@@ -0,0 +1,16 @@
+/**
+ * Infer display title from PascalCase component name.
+ *
+ * TeamRoster → "Team Roster"
+ * CTA → "CTA"
+ * FAQSection → "FAQ Section"
+ * Hero → "Hero"
+ *
+ * @param {string} name - PascalCase component name
+ * @returns {string} Human-readable title
+ */
+export function inferTitle(name) {
+  return name
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+}

package/src/vite-foundation-plugin.js

@@ -120,21 +120,33 @@ export function foundationDevPlugin(options = {}) {
     },
 
     async handleHotUpdate({ file, server }) {
+      const entryPath = join(resolvedSrcDir, entryFileName)
+
       // Regenerate entry when meta.js files change
-      // Check if file is a meta.js in the src directory
       if (file.startsWith(resolvedSrcDir) && file.endsWith('/meta.js')) {
         console.log('Component meta.js changed, regenerating entry...')
-        const entryPath = join(resolvedSrcDir, entryFileName)
         await generateEntryPoint(resolvedSrcDir, entryPath, { componentPaths })
-
-        // Trigger full reload since entry changed
         server.ws.send({ type: 'full-reload' })
+        return
+      }
+
+      // Regenerate when component files are added/removed in sections/ root
+      // (bare file discovery means any .jsx/.tsx/.js/.ts at sections root is a section type)
+      const sectionsDir = join(resolvedSrcDir, 'sections')
+      if (file.startsWith(sectionsDir)) {
+        const relative = file.slice(sectionsDir.length + 1)
+        // Direct child of sections/ (no further slashes) — could be a new/removed bare file
+        if (!relative.includes('/') && /\.(jsx|tsx|js|ts)$/.test(relative)) {
+          console.log('Section file changed, regenerating entry...')
+          await generateEntryPoint(resolvedSrcDir, entryPath, { componentPaths })
+          server.ws.send({ type: 'full-reload' })
+          return
+        }
       }
 
       // Also regenerate if exports.js changes
       if (file.endsWith('/exports.js') || file.endsWith('/exports.jsx')) {
         console.log('Foundation exports changed, regenerating entry...')
-        const entryPath = join(resolvedSrcDir, entryFileName)
         await generateEntryPoint(resolvedSrcDir, entryPath, { componentPaths })
         server.ws.send({ type: 'full-reload' })
       }