uniweb 0.2.15 → 0.2.19

package/README.md

@@ -31,13 +31,19 @@ my-project/
 │   │       └── 1-hero.md     # Section content
 │   ├── locales/              # i18n (mirrors pages/)
 │   │   └── es/
+│   ├── src/
+│   │   └── main.jsx          # 1-line entry point
+│   ├── vite.config.js        # 3-line config
 │   └── public/               # Static assets
 │
 └── foundation/               # Your components
-    └── src/
-        └── components/
-            └── Hero/
-                └── index.jsx
+    ├── src/
+    │   └── components/
+    │       └── Hero/
+    │           ├── index.jsx
+    │           └── meta.js
+    ├── vite.config.js        # 3-line config
+    └── dist/                 # Built output
 ```
 
 **Pages are folders.** Create `pages/about/` with markdown files inside → visit `/about`. That's the whole routing model.
@@ -98,7 +104,24 @@ export function Hero({ content, params }) {
 
 Standard React. Standard Tailwind. The `{ content, params }` interface is only for *exposed* components—the ones content creators select in markdown frontmatter. Internal components (the majority of your codebase) use regular React props.
 
-No framework to learn. Foundations are purpose-built component systems designed for a specific domain (marketing, documentation, learning, etc.). Sites are Vite apps that load content from markdown files. The CLI handles the wiring.
+No framework to learn. Foundations are purpose-built component systems designed for a specific domain (marketing, documentation, learning, etc.). Sites are Vite apps that load content from markdown files. Configuration is minimal—both site and foundation use 3-line Vite configs:
+
+```javascript
+// site/vite.config.js
+import { defineSiteConfig } from '@uniweb/build/site'
+export default defineSiteConfig()
+
+// foundation/vite.config.js
+import { defineFoundationConfig } from '@uniweb/build'
+export default defineFoundationConfig()
+```
+
+The site entry point is equally minimal:
+
+```javascript
+// site/src/main.jsx
+import 'virtual:uniweb-site-entry'
+```
 
 ## The Bigger Picture
 
@@ -122,6 +145,12 @@ npx uniweb@latest <command>
 npm install -g uniweb
 ```
 
+**Requirements:**
+- Node.js 20.19 or later
+- pnpm 9+ (recommended) or npm 10+
+
+Projects use Vite 7 and Tailwind CSS v4 by default.
+
 ## Commands
 
 ### `create`
@@ -214,37 +243,35 @@ A minimal workspace with a site and foundation as sibling packages. This is the
 
 ```
 my-project/
-├── package.json              # Workspace root (includes workspaces field for npm)
+├── package.json              # Workspace root (npm + pnpm compatible)
 ├── pnpm-workspace.yaml       # Pre-configured for evolution (see below)
+├── CLAUDE.md                 # AI assistant instructions
 │
 ├── site/                     # Site package (content + entry)
 │   ├── package.json
-│   ├── vite.config.js
+│   ├── vite.config.js        # 3-line config using defineSiteConfig()
 │   ├── index.html
-│   ├── site.yml
+│   ├── site.yml              # Site configuration (foundation, title, i18n)
 │   ├── src/
-│   │   └── main.jsx          # Thin entry point
-│   ├── pages/                # Content structure
+│   │   └── main.jsx          # 1-line entry: import 'virtual:uniweb-site-entry'
+│   ├── pages/                # Content pages (file-based routing)
 │   │   └── home/
 │   │       ├── page.yml
 │   │       └── 1-hero.md
-│   ├── locales/              # i18n (mirrors pages/)
-│   │   └── es/
-│   │       └── home/
 │   └── public/               # Static assets
 │
 └── foundation/               # Foundation package (components)
     ├── package.json
-    ├── vite.config.js
-    ├── src/
-    │   ├── index.js          # Component registry
-    │   ├── styles.css        # Tailwind
-    │   ├── meta.js           # Foundation metadata
-    │   └── components/
-    │       └── Hero/
-    │           ├── index.jsx
-    │           └── meta.js
-    └── ...
+    ├── vite.config.js        # 3-line config using defineFoundationConfig()
+    └── src/
+        ├── index.js          # Component exports
+        ├── entry-runtime.js  # Runtime entry (imports styles + index)
+        ├── styles.css        # Tailwind CSS v4
+        ├── meta.js           # Foundation metadata
+        └── components/
+            └── Section/
+                ├── index.jsx
+                └── meta.js
 ```
 
 **Key characteristics:**
@@ -260,23 +287,24 @@ A monorepo for multi-site or multi-foundation development.
 
 ```
 my-workspace/
-├── package.json              # Workspace root (includes workspaces field for npm)
+├── package.json              # Workspace root (npm + pnpm compatible)
 ├── pnpm-workspace.yaml       # Same config as single template
+├── CLAUDE.md                 # AI assistant instructions
 │
 ├── sites/
 │   ├── marketing/            # Main marketing site
 │   │   ├── package.json
+│   │   ├── vite.config.js    # 3-line config
 │   │   ├── site.yml
-│   │   ├── src/
-│   │   ├── pages/
-│   │   └── ...
+│   │   ├── src/main.jsx      # 1-line entry
+│   │   └── pages/
 │   └── docs/                 # Documentation site
 │
 └── foundations/
     ├── marketing/            # Marketing foundation
     │   ├── package.json
-    │   ├── src/components/
-    │   └── ...
+    │   ├── vite.config.js    # 3-line config
+    │   └── src/components/
     └── documentation/        # Documentation foundation
 ```
 
@@ -298,15 +326,39 @@ A complete marketing site with landing page components:
 uniweb create my-site --template marketing
 ```
 
-**Includes:**
-- **Hero** — Gradient/light/dark banner with CTAs
-- **Features** — Grid layout with icons
-- **Pricing** — Tiered pricing tables
-- **Testimonials** — Customer quotes
-- **CTA** — Call-to-action sections
+**Includes:** Hero, Features, Pricing, Testimonials, CTA, FAQ, Stats, LogoCloud, Video, Gallery, Team
 
 Perfect for product launches, SaaS websites, and business landing pages.
 
+**Tailwind v3 variant:**
+```bash
+uniweb create my-site --template marketing --variant tailwind3
+```
+
+#### Academic
+
+A professional academic site for researchers, labs, and departments:
+
+```bash
+uniweb create my-site --template academic
+```
+
+**Includes:** ProfileHero, PublicationList, ResearchAreas, TeamGrid, Timeline, ContactCard, Navbar, Footer
+
+Perfect for researcher portfolios, lab websites, and academic department sites.
+
+#### Docs
+
+A documentation site with navigation levels:
+
+```bash
+uniweb create my-site --template docs
+```
+
+**Includes:** Header, LeftPanel, DocSection, CodeBlock, Footer
+
+Perfect for technical documentation, guides, and API references.
+
 ### External Templates
 
 You can use templates from npm or GitHub:
@@ -347,6 +399,52 @@ cd foundation && pnpm add embla-carousel
 # No path gymnastics needed
 ```
 
+## Configuration
+
+### Site Configuration
+
+The `defineSiteConfig()` function handles all Vite configuration for sites:
+
+```javascript
+import { defineSiteConfig } from '@uniweb/build/site'
+
+export default defineSiteConfig({
+  // All options are optional
+  tailwind: true,        // Enable Tailwind CSS v4 (default: true)
+  plugins: [],           // Additional Vite plugins
+  // ...any other Vite config options
+})
+```
+
+### Foundation Configuration
+
+The `defineFoundationConfig()` function handles all Vite configuration for foundations:
+
+```javascript
+import { defineFoundationConfig } from '@uniweb/build'
+
+export default defineFoundationConfig({
+  // All options are optional
+  entry: 'src/entry-runtime.js',     // Entry point path
+  fileName: 'foundation',             // Output file name
+  externals: [],                      // Additional packages to externalize
+  includeDefaultExternals: true,      // Include react, @uniweb/core, etc.
+  tailwind: true,                     // Enable Tailwind CSS v4 Vite plugin
+  sourcemap: true,                    // Generate sourcemaps
+  plugins: [],                        // Additional Vite plugins
+  build: {},                          // Additional Vite build options
+  // ...any other Vite config options
+})
+```
+
+For Tailwind CSS v3 projects, set `tailwind: false` and use PostCSS:
+
+```javascript
+export default defineFoundationConfig({
+  tailwind: false  // Uses PostCSS instead of Vite plugin
+})
+```
+
 ## Foundation Build Process
 
 When you run `uniweb build` on a foundation:

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "uniweb",
-  "version": "0.2.15",
+  "version": "0.2.19",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
     "uniweb": "src/index.js"
   },
   "files": [
-    "src"
+    "src",
+    "templates"
   ],
   "keywords": [
     "uniweb",
@@ -35,6 +36,6 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.1.8"
+    "@uniweb/build": "0.1.9"
   }
 }

package/src/partials/search-docs.hbs

@@ -0,0 +1,110 @@
+## Search Functionality
+
+Uniweb sites support full-text search out of the box. Search indexes are generated automatically at build time.
+
+### Enabling Search in Your Foundation
+
+To add search to your site, your foundation needs the **Fuse.js** library:
+
+```bash
+cd foundation
+pnpm add fuse.js
+```
+
+Then use the search helpers from `@uniweb/kit`:
+
+```jsx
+import { useSearch } from '@uniweb/kit/search'
+
+function SearchComponent({ website }) {
+  const { query, results, isLoading, clear } = useSearch(website)
+
+  return (
+    <div>
+      <input
+        type="search"
+        placeholder="Search..."
+        onChange={e => query(e.target.value)}
+      />
+      {isLoading && <span>Searching...</span>}
+      <ul>
+        {results.map(result => (
+          <li key={result.id}>
+            <a href={result.href}>{result.title}</a>
+            <p dangerouslySetInnerHTML=\{{ __html: result.snippetHtml }} />
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+### Search Configuration
+
+Search is enabled by default. To customize, add to `site/site.yml`:
+
+```yaml
+search:
+  enabled: true
+  exclude:
+    routes: [/admin, /private]    # Don't index these routes
+    components: [Debug]            # Don't index these component types
+```
+
+### How It Works
+
+1. **Build time**: Uniweb extracts text from all pages and sections
+2. **Output**: A `search-index.json` file is generated in `dist/`
+3. **Runtime**: Components fetch and search the index client-side
+4. **Multi-locale**: Each locale gets its own search index
+
+### Search API
+
+The `website` object provides these methods:
+
+```javascript
+// Check if search is available
+website.isSearchEnabled()      // Returns boolean
+
+// Get the URL for the search index
+website.getSearchIndexUrl()    // "/search-index.json" or "/es/search-index.json"
+
+// Get full search configuration
+website.getSearchConfig()      // { enabled, indexUrl, locale, include, exclude }
+```
+
+### Search Result Format
+
+Results from `useSearch()` include:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique result identifier |
+| `type` | `"page"` or `"section"` |
+| `route` | Page route |
+| `href` | Full link including anchor |
+| `title` | Result title |
+| `pageTitle` | Parent page title (for sections) |
+| `snippetHtml` | Excerpt with `<mark>` highlighted matches |
+| `snippetText` | Plain text excerpt |
+
+### Without @uniweb/kit
+
+If you prefer not to use the kit helpers, you can fetch the index directly:
+
+```javascript
+// Fetch the search index
+const response = await fetch(website.getSearchIndexUrl())
+const index = await response.json()
+
+// Use with Fuse.js directly
+import Fuse from 'fuse.js'
+const fuse = new Fuse(index.entries, {
+  keys: ['title', 'content'],
+  threshold: 0.35,
+  includeMatches: true
+})
+
+const results = fuse.search('your query')
+```

package/src/templates/processor.js

@@ -3,13 +3,19 @@
  */
 
 import fs from 'node:fs/promises'
-import { existsSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import Handlebars from 'handlebars'
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
 // Cache for compiled templates
 const templateCache = new Map()
 
+// Track if partials have been registered
+let partialsRegistered = false
+
 // Store for version data (set by registerVersions)
 let versionData = {}
 
@@ -45,6 +51,40 @@ export function clearMissingVersions() {
   missingVersions.clear()
 }
 
+/**
+ * Register Handlebars partials from the partials directory
+ * Partials are available as {{> partial-name}} in templates
+ */
+function registerPartials() {
+  if (partialsRegistered) return
+
+  const partialsDir = path.join(__dirname, '..', 'partials')
+
+  if (!existsSync(partialsDir)) {
+    partialsRegistered = true
+    return
+  }
+
+  try {
+    const files = readdirSync(partialsDir)
+
+    for (const file of files) {
+      if (file.endsWith('.hbs') || file.endsWith('.md')) {
+        const partialName = file.replace(/\.(hbs|md)$/, '')
+        const partialPath = path.join(partialsDir, file)
+        const partialContent = readFileSync(partialPath, 'utf8')
+
+        Handlebars.registerPartial(partialName, partialContent)
+      }
+    }
+
+    partialsRegistered = true
+  } catch (err) {
+    console.warn('Warning: Could not register partials:', err.message)
+    partialsRegistered = true
+  }
+}
+
 /**
  * Handlebars helper to get a package version
  * Usage: {{version "@uniweb/build"}} or {{version "build"}}
@@ -99,6 +139,9 @@ function findUnresolvedPlaceholders(content) {
  * Load and compile a Handlebars template with caching
  */
 async function loadTemplate(templatePath) {
+  // Ensure partials are registered before first template load
+  registerPartials()
+
   if (templateCache.has(templatePath)) {
     return templateCache.get(templatePath)
   }

package/templates/_shared/CLAUDE.md.hbs

@@ -0,0 +1,146 @@
+# CLAUDE.md - AI Assistant Instructions
+
+This file provides guidance for AI assistants working with this Uniweb project.
+
+## Project Overview
+
+This is a **Uniweb** project - a component web platform that separates content from code.
+
+```
+{{projectName}}/
+├── foundation/     # React component library (code)
+├── site/           # Content and pages (markdown)
+├── package.json    # Root workspace config
+└── pnpm-workspace.yaml
+```
+
+## Quick Commands
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server (site with foundation)
+pnpm dev
+
+# Build foundation (generates dist/foundation.js and schema.json)
+cd foundation && pnpm build
+
+# Build site for production (outputs to site/dist/)
+cd site && pnpm build
+```
+
+## Key Files
+
+**Site:**
+- `site/vite.config.js` - 3-line config using `defineSiteConfig()` from `@uniweb/build/site`
+- `site/src/main.jsx` - 1-line entry: `import 'virtual:uniweb-site-entry'`
+- `site/site.yml` - Site configuration (foundation path, title, i18n)
+- `site/pages/` - Content pages (file-based routing)
+
+**Foundation:**
+- `foundation/vite.config.js` - 3-line config using `defineFoundationConfig()` from `@uniweb/build`
+- `foundation/src/entry-runtime.js` - Runtime entry point (imports styles + components)
+- `foundation/src/index.js` - Component exports
+- `foundation/src/styles.css` - Tailwind CSS v4 theme
+- `foundation/src/components/*/meta.js` - Component metadata and schema
+
+## Architecture
+
+### Foundation Package (`/foundation`)
+
+The **foundation** is a React component library. Each component:
+
+1. Receives structured content parsed from markdown
+2. Has configurable parameters (theme, layout, etc.)
+3. Renders the content according to its design
+
+**Key directories:**
+- `src/components/*/` - Component implementations
+- `src/components/*/meta.js` - Component metadata and schema
+- `src/styles.css` - Global Tailwind styles
+
+### Site Package (`/site`)
+
+The **site** contains content written in markdown. The runtime loads the foundation and renders content based on component selections.
+
+**Key directories:**
+- `pages/` - Content pages organized in folders
+- `pages/[page-name]/page.yml` - Page metadata
+- `pages/[page-name]/*.md` - Content sections
+
+## Content Authoring
+
+### Section File Format
+
+```markdown
+---
+type: ComponentName
+theme: dark
+layout: center
+---
+
+# Main Headline
+
+Description paragraph.
+
+[Call to Action](#link)
+```
+
+### Content Structure
+
+The semantic parser extracts content into:
+
+- **`content.main.header`**: title, pretitle, subtitle
+- **`content.main.body`**: paragraphs, links, imgs, lists
+- **`content.items`**: Content groups from H3 headings
+
+## Component Development
+
+### Component Interface
+
+```jsx
+function MyComponent({ content, params, block, website }) {
+  const { title } = content.main?.header || {}
+  const { paragraphs = [] } = content.main?.body || {}
+  // ...
+}
+```
+
+### Using @uniweb/kit
+
+```jsx
+import { H1, P, Link, cn } from '@uniweb/kit'
+```
+
+### Component Metadata (`meta.js`)
+
+```javascript
+export default {
+  title: 'Component Name',
+  description: 'What the component does',
+  category: 'Content',
+  elements: { /* content elements */ },
+  properties: { /* configurable params */ },
+}
+```
+
+## Tailwind CSS v4
+
+This project uses Tailwind CSS v4 with the Vite plugin.
+
+**Theme customization** (`foundation/src/styles.css`):
+
+```css
+@import "tailwindcss";
+@source "./components/**/*.{js,jsx}";
+@theme {
+  --color-primary: #3b82f6;
+}
+```
+
+## Resources
+
+- [Uniweb Documentation](https://github.com/uniweb/uniweb)
+- [@uniweb/kit Documentation](https://www.npmjs.com/package/@uniweb/kit)
+- [Tailwind CSS v4](https://tailwindcss.com/docs)

package/templates/_shared/package.json.hbs

@@ -0,0 +1,23 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pnpm --filter site dev",
+    "build": "pnpm --filter foundation build && pnpm --filter site build",
+    "preview": "pnpm --filter site preview"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "workspaces": [
+    "site",
+    "foundation",
+    "sites/*",
+    "foundations/*"
+  ],
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild", "sharp"]
+  }
+}

package/templates/_shared/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+packages:
+  - foundation
+  - site
+  - foundations/*
+  - sites/*