uniweb 0.2.34 → 0.2.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.2.34",
+  "version": "0.2.36",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "src",
-    "templates"
+    "templates",
+    "partials"
   ],
   "keywords": [
     "uniweb",
@@ -37,8 +38,8 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/build": "0.1.19",
+    "@uniweb/runtime": "0.2.10",
     "@uniweb/core": "0.1.8",
-    "@uniweb/kit": "0.1.4",
-    "@uniweb/runtime": "0.2.10"
+    "@uniweb/kit": "0.1.4"
   }
 }

package/partials/adding-pages.hbs

@@ -0,0 +1,29 @@
+### Adding a New Page
+
+1. Create a folder: `site/pages/my-page/`
+2. Add `page.yml`:
+   ```yaml
+   title: My Page
+   ```
+3. Add section files: `1-hero.md`, `2-content.md`, etc.
+
+### Section Ordering
+
+By default, sections are discovered from `.md` files and sorted by numeric prefix (`1-`, `2-`, `2.5-`).
+
+For more control, use the `sections` property in `page.yml`:
+
+```yaml
+title: My Page
+sections:
+  - hero
+  - features
+  - pricing
+```
+
+This approach makes reordering easy (just move lines) and allows temporarily removing sections by commenting them out.
+
+**Options:**
+- `sections: *` or omit — auto-discover and sort `.md` files (default)
+- `sections: [hero, features]` — explicit ordering, no numeric prefixes needed
+- `sections: []` or no `.md` files — pure route with no content sections

package/partials/ai-assistance.hbs

@@ -0,0 +1,3 @@
+## AI Assistance
+
+See [CLAUDE.md](./CLAUDE.md) for detailed instructions that AI assistants can use.

package/partials/claude-md.hbs

@@ -0,0 +1,226 @@
+# CLAUDE.md
+
+This file provides guidance for AI assistants working with this Uniweb project.
+
+## Project Structure
+
+Uniweb projects have two structures. A single project can be converted to multi-site:
+
+**Single (one foundation, one site):**
+```
+project/
+├── foundation/     # Purpose-built component library (React)
+├── site/           # Content (markdown pages)
+└── pnpm-workspace.yaml
+```
+
+**Multi-site (multiple foundations and sites):**
+```
+project/
+├── foundations/        # Purpose-built component libraries
+│   └── marketing/
+├── sites/              # Content sites
+│   └── my-org/
+└── pnpm-workspace.yaml
+```
+
+- **Foundation**: React components. Components with `meta.js` are *exposed* to content authors.
+- **Site**: Markdown content. Each section references a component via `type:` in frontmatter.
+
+## Commands
+
+```bash
+pnpm install    # Install dependencies
+pnpm dev        # Start dev server (runs default/main site)
+pnpm build      # Build for production
+```
+
+Multi-site also supports:
+```bash
+pnpm dev:all    # Start all sites in parallel
+pnpm build:all  # Build all sites
+```
+
+## Discovering Components
+
+Exposed components live in `foundation/src/components/` (or `foundations/*/src/components/`).
+
+```bash
+# List exposed components (those with meta.js)
+ls foundation/src/components/*/meta.js
+```
+
+**Understanding a component:**
+
+1. **`meta.js`** - Defines the component's interface:
+   - `title`, `description` - What the component does
+   - `elements` - What content it expects (title, paragraphs, links, items, etc.)
+   - `properties` - Configurable parameters (theme, layout, etc.)
+   - `hidden: true` - Component exists but isn't selectable from frontmatter
+
+2. **`index.jsx`** - The React implementation
+
+3. **Existing content** - See how the component is used in `site/pages/`
+
+**Note:** Components without `meta.js` are internal helpers used by other components.
+
+## Content Authoring
+
+### Section Format
+
+Each section is a markdown file with YAML frontmatter:
+
+```markdown
+---
+type: ComponentName   # Must match an exposed component
+theme: dark           # Parameter from meta.js properties
+---
+
+### Eyebrow Text      # H3 before H1 → pretitle
+
+# Main Headline       # H1 → title
+
+## Subtitle           # H2 after H1 → subtitle
+
+Description paragraph.
+
+[Call to Action](#link)
+
+![Image](image.jpg)
+```
+
+### Content Structure
+
+The semantic parser extracts markdown into:
+
+- **`content.main.header`** - title, pretitle, subtitle
+- **`content.main.body`** - paragraphs, links, imgs, lists
+- **`content.items`** - Groups created by H3 headings (each with its own header/body)
+
+### Page Organization
+
+```
+site/pages/                    # or sites/*/pages/
+├── @header/                   # Rendered on all pages
+├── @footer/                   # Rendered on all pages
+└── [page-name]/
+    ├── page.yml               # title, description, order
+    └── 1-section.md           # Numbered for ordering
+```
+
+**page.yml options:**
+```yaml
+title: About Us
+description: Learn about our company
+order: 2                 # Sort order in navigation
+
+# Section ordering (optional)
+sections:
+  - hero
+  - features
+  - pricing
+```
+
+**Section ordering:**
+- Default: `.md` files discovered and sorted by numeric prefix (`1-`, `2-`, `2.5-`)
+- Explicit: Use `sections: [hero, features]` — no prefixes needed, easy reordering
+- Empty: `sections: []` or no `.md` files — pure route with no content
+- Wildcard: `sections: *` — explicitly use default behavior
+
+## Component Development
+
+### Props Interface
+
+```jsx
+function MyComponent({ content, params, block, website }) {
+  const { title, pretitle } = content.main?.header || {}
+  const { paragraphs = [], links = [] } = content.main?.body || {}
+  const items = content.items || []
+  // ...
+}
+```
+
+### Using @uniweb/kit
+
+```jsx
+import { H1, P, Link, Image, Section, cn } from '@uniweb/kit'
+```
+
+- `H1, H2, H3, P, Span` - Typography (handles arrays, filters empty)
+- `Link` - Smart routing
+- `Image` - Optimized images
+- `Section` - Layout wrapper
+- `cn()` - Tailwind class merging
+
+### Creating a New Component
+
+1. Create `foundation/src/components/NewComponent/index.jsx`
+2. Create `foundation/src/components/NewComponent/meta.js`
+3. Export from `foundation/src/index.js`
+4. Rebuild: `cd foundation && pnpm build`
+
+### meta.js Structure
+
+```javascript
+export default {
+  title: 'Component Name',
+  description: 'What it does',
+  // hidden: true,  // Uncomment to hide from content authors
+  elements: {
+    title: { label: 'Headline', required: true },
+    paragraphs: { label: 'Description' },
+    links: { label: 'Call to Action' },
+  },
+  properties: {
+    theme: {
+      type: 'select',
+      label: 'Theme',
+      options: [
+        { value: 'light', label: 'Light' },
+        { value: 'dark', label: 'Dark' },
+      ],
+      default: 'light',
+    },
+  },
+}
+```
+
+### Parameter Philosophy
+
+Design parameters that describe **intent**, not implementation:
+
+| Good | Bad |
+|------|-----|
+| `theme: "dark"` | `backgroundColor: "#1a1a1a"` |
+| `layout: "split"` | `gridTemplateColumns: "1fr 1fr"` |
+| `size: "large"` | `fontSize: "2rem"` |
+
+## Tailwind CSS v4
+
+Theme is defined in `foundation/src/styles.css`:
+
+```css
+@import "tailwindcss";
+@source "./components/**/*.{js,jsx}";
+
+@theme {
+  --color-primary: #3b82f6;
+}
+```
+
+Use with: `bg-primary`, `text-primary`, `bg-primary/10` (10% opacity)
+
+## Troubleshooting
+
+**"Could not load foundation"**
+- Single: Check `site/package.json` has `"foundation": "file:../foundation"`
+- Multi: Check `sites/*/package.json` has `"default": "file:../../foundations/default"`
+
+**Component not appearing**
+1. Verify `meta.js` exists and doesn't have `hidden: true`
+2. Check it's exported from `foundation/src/index.js`
+3. Rebuild: `cd foundation && pnpm build`
+
+**Styles not applying**
+1. Verify `@source` in styles.css includes your component path
+2. Check custom color names match `@theme` definitions

package/partials/components-docs.hbs

@@ -0,0 +1,15 @@
+## Component Documentation
+
+Generate up-to-date documentation for all foundation components:
+
+```bash
+# From within the foundation directory
+pnpm docs
+```
+
+This creates `COMPONENTS.md` with full details on each component's:
+- Content elements (title, paragraphs, links, images, items)
+- Parameters (theme, layout, columns, etc.)
+- Presets (pre-configured parameter combinations)
+
+The documentation is generated from component `meta.js` files, so it's always current.

package/partials/deployment.hbs

@@ -0,0 +1,13 @@
+## Deployment
+
+Build and deploy the `site/dist` folder:
+
+```bash
+pnpm build
+```
+
+**Supported platforms:**
+- **Vercel**: `cd site && vercel`
+- **Netlify**: Build command `pnpm build`, publish `site/dist`
+- **GitHub Pages**: Use GitHub Actions
+- **Cloudflare Pages**: Connect repo, set `pnpm build` and `site/dist`

package/partials/exports-js.hbs

@@ -0,0 +1,14 @@
+/**
+ * Foundation Exports
+ *
+ * Optional file to export foundation-level capabilities to the runtime:
+ * - Layout: Custom page layout component (receives header, body, footer, sidebars)
+ * - props: Foundation-wide props accessible via website.foundationProps
+ *
+ * The Layout component receives pre-rendered page areas as props:
+ * - page, website: Runtime context
+ * - header, body, footer: Core page regions (pre-rendered React elements)
+ * - left/leftPanel, right/rightPanel: Sidebar panels
+ *
+ * If this file is not provided, the runtime uses a default layout (header -> body -> footer).
+ */

package/partials/learn-more.hbs

@@ -0,0 +1,5 @@
+## Learn More
+
+- [Uniweb Documentation](https://github.com/uniweb/cli)
+- [@uniweb/kit Components](https://www.npmjs.com/package/@uniweb/kit)
+- [Tailwind CSS v4](https://tailwindcss.com)

package/partials/quick-start.hbs

@@ -0,0 +1,8 @@
+## Quick Start
+
+```bash
+pnpm install    # Install dependencies
+pnpm dev        # Start development server
+```
+
+Visit `http://localhost:5173` to see your site.

package/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')
+```