uniweb 0.8.28 → 0.8.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.28",
+  "version": "0.8.30",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,12 +41,12 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "0.5.17",
-    "@uniweb/kit": "0.7.18",
-    "@uniweb/runtime": "0.6.23"
+    "@uniweb/core": "0.5.18",
+    "@uniweb/runtime": "0.6.25",
+    "@uniweb/kit": "0.7.19"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.8.27",
+    "@uniweb/build": "0.8.29",
     "@uniweb/content-reader": "1.1.4",
     "@uniweb/semantic-parser": "1.1.8"
   },

package/partials/agents.md

@@ -61,9 +61,11 @@ project/
 └── pnpm-workspace.yaml
 ```
 
-- **Foundation** (developer): React components. Those in `src/sections` and `src/layouts` are *section types* — selectable by content authors via `type:` in frontmatter, or used for site-level layout areas (header, footer, panel). Most have an a `meta.js` with metadata in them. Everything in `src/components` (or elsewhere) is ordinary React.
+- **Foundation** (developer): React components. Those in `src/sections` and `src/layouts` are *section types* — selectable by content authors via `type:` in frontmatter, or used for site-level layout areas (header, footer, panel). Most have a `meta.js` with metadata in them. Everything in `src/components` (or elsewhere) is ordinary React — the developer's workbench for helper components that section types import and compose internally.
 - **Site** (content author): Markdown content + configuration. Each section file references a section type. Authors work here without touching foundation code. It may also contain collections of structured content and/or references to external data sources.
 
+**The composition boundary:** Authors compose pages from finished section types — choosing types, writing content, setting params. Developers compose section types from building blocks — importing helpers from `src/components/`, using libraries, writing JSX. These are two different levels of composition. The section type is the boundary between them. Don't expose building-block composition to authors; build complete, self-contained section types that handle their own internal structure.
+
 > Multi-site projects use sub-folders with site/foundation pairs in them, or segregate foundations and sites into separate folders (`foundations/`, `sites/`).
 
 ## Project Setup
@@ -553,7 +555,6 @@ description: Learn about our company
 id: about                   # Stable identity (for page: links, survives moves)
 order: 2                    # Navigation sort position
 pages: [team, history, ...] # Child page order (... = rest). Without ... = strict (hides unlisted)
-index: getting-started      # Which child page is the index
 redirect: academic          # Redirect to child page (relative or absolute path, or URL)
 ```
 
@@ -564,6 +565,10 @@ pages: [home, about, ...]           # Order pages (... = rest, first = homepage)
 pages: [home, about]                # Strict: only listed pages in nav
 ```
 
+**Route mapping:** Folder structure maps 1:1 to routes. Every folder keeps its natural route — `pages:` controls **order only**, not which child "becomes" the parent. The only exception is the site root: `index:` (or first in `pages:`) in site.yml sets the homepage at `/`.
+
+**Content-less containers:** Folders with `page.yml` but no markdown are structural groups. They appear in `getPageHierarchy()` with `hasContent: false` and their own title/label. When visited directly, the runtime auto-redirects to the first descendant with content. This supports hierarchical navigation (courses → modules → lessons) at any depth.
+
 ### Lists as Navigation Menus
 
 Markdown lists model nav, menus, and grouped links. Each list item is a full content object with `paragraphs`, `links`, `icons`, and nested `lists`.
@@ -708,7 +713,7 @@ inline:
     font-weight: '600'
 
 vars:
-  header-height: 5rem
+  radius: 0.75rem
 ```
 
 Each color generates 11 OKLCH shades (50–950). `neutral` uses a named preset rather than hex. Shade 500 = your exact input color. Context override keys match token names: `section:` not `bg:`, `primary:` not `btn-primary-bg:`.
@@ -734,19 +739,35 @@ contexts:
 
 ### Foundation variables
 
-Foundations declare customizable layout values in `foundation.js`:
+Most customization is handled by component params. Both section components and layout components declare their own params in `meta.js` — layouts are full components with params, not just structural wrappers. A header height, for example, is typically a layout param, not a foundation var.
+
+Foundation-level CSS variables are for values that must stay consistent **across** multiple components — shared radii, spacing scales, or additional font roles beyond the three the theming system already provides (body, heading, mono). Don't reach for foundation vars when a component or layout param would do.
+
+If you need them, declare vars in two places:
+
+**`foundation.js`** — metadata for the editor and schema:
 
 ```js
 export const vars = {
-  'header-height': { default: '4rem', description: 'Fixed header height' },
-  'max-content-width': { default: '80rem', description: 'Maximum content width' },
+  'radius': { default: '0.5rem', description: 'Default border radius for cards and buttons' },
+  'radius-lg': { default: '1rem', description: 'Large border radius' },
   'section-padding-y': { default: 'clamp(4rem, 6vw, 7rem)', description: 'Vertical section padding' },
 }
 ```
 
-Sites override in `theme.yml` under `vars:`. Components use: `py-[var(--section-padding-y)]`, `h-[var(--header-height)]`.
+**`styles.css`** — the actual CSS that ships with the foundation:
 
-Tailwind v4 also supports a shorthand: `py-(--section-padding-y)`. This requires registering the variable in `styles.css` via `@theme inline { --section-padding-y: <default>; }`. Use the shorthand for vars referenced across many components; otherwise the bracket syntax works without registration.
+```css
+@theme inline {
+  --radius: 0.5rem;
+  --radius-lg: 1rem;
+  --section-padding-y: clamp(4rem, 6vw, 7rem);
+}
+```
+
+The `styles.css` declaration ensures defaults are present in the foundation's CSS output and enables Tailwind shorthand (`rounded-(--radius)` instead of `rounded-[var(--radius)]`). The `foundation.js` declaration provides descriptions and types for the visual editor. Sites override values in `theme.yml` under `vars:` — the site's theme CSS takes priority over the foundation defaults.
+
+**Common mistake:** Using foundation vars for values that belong to a specific component. A header height is a layout param, not a foundation var — the layout component owns it. A sidebar width is a layout param too. Foundation vars are for values that multiple unrelated components share — radii, spacing, shadows.
 
 ### Design richness beyond tokens
 
@@ -1083,6 +1104,33 @@ export default function Hero({ content, block, params }) {
 
 This is the system-building pattern at its clearest: **section types are the public interface** to your content system (author-friendly names, documented in `meta.js`). **Helper components are the implementation** (developer-friendly APIs, ordinary React props). The section type is the thin translation layer that connects the two worlds.
 
+### Section components are composites
+
+A section component is rarely a single flat render. It imports helper components from `src/components/` to build a complex UI while presenting a single `type:` to the content author. The `src/components/` directory is the developer's workbench — ordinary React components with ordinary props, not selectable by authors, not auto-discovered.
+
+```jsx
+// src/sections/Lesson/index.jsx
+import LessonHeader from '../../components/LessonHeader'
+import LessonContent from '../../components/LessonContent'
+import LessonNav from '../../components/LessonNav'
+
+export default function Lesson({ content, params, block }) {
+  return (
+    <>
+      <LessonHeader block={block} />
+      <LessonContent content={content} params={params} />
+      <LessonNav block={block} />
+    </>
+  )
+}
+```
+
+The content author writes `type: Lesson` in one markdown file. The section component handles the structural chrome — a header derived from the page hierarchy, the rendered content, a prev/next footer. The three helpers live in `src/components/` and receive whatever props make sense for their job.
+
+**When to reach for this pattern:** When a page type has consistent structural elements (header bars, navigation footers, contextual sidebars) that the content author shouldn't need to add as separate sections. If the author would have to add the same boilerplate sections to every page of a certain type, the section component should compose them internally.
+
+**Common mistake:** Solving structural repetition at the layout level. If only some page types need a content header (lessons do, the homepage doesn't), it's a section concern, not a layout concern. The layout owns the page-wide chrome (header area, sidebar area). The section owns its own internal structure.
+
 ### Foundation Organization
 
 ```
@@ -1111,9 +1159,26 @@ foundation/src/
 const { website } = useWebsite()
 const page = website.activePage
 
-// Navigation
-website.getPageHierarchy({ for: 'header' })
-// → [{ route, navigableRoute, label, hasContent, children }]
+// Navigation — getPageHierarchy(options)
+// Returns [{ id, route, navigableRoute, translatedRoute, title, label, description, hasContent, version, children }]
+//
+// Options:
+//   for: 'header' | 'footer'  — filter by nav type (respects hideInHeader/hideInFooter)
+//   nested: true (default)    — nested hierarchy with children; false = flat list
+//   includeHidden: false       — include hidden pages
+//   filter: (page) => bool    — custom filter function
+//   sort: (a, b) => number    — custom sort function
+//
+// Convenience methods:
+//   website.getHeaderPages()  — same as getPageHierarchy({ for: 'header' })
+//   website.getFooterPages()  — same as getPageHierarchy({ for: 'footer' })
+//   website.getAllPages()     — flat list: getPageHierarchy({ nested: false })
+//
+// Common patterns:
+website.getPageHierarchy({ for: 'header' })           // Header nav (excludes hideInHeader pages)
+website.getPageHierarchy()                             // Full nested hierarchy (no nav filtering)
+website.getPageHierarchy({ nested: false })            // Flat list of all visible pages
+website.getPageHierarchy({ nested: false, includeHidden: true })  // Everything including hidden
 
 // Core properties
 website.name              // Site name from site.yml
@@ -1132,9 +1197,17 @@ const { isActive, isActiveOrAncestor } = useActiveRoute()
 const { scheme, toggle, canToggle } = useAppearance()
 
 // Page properties
-page.title, page.label, page.route
+page.title, page.label, page.route, page.description
 page.isHidden(), page.showInHeader(), page.showInFooter()
-page.hasChildren(), page.children
+page.hasContent()                   // True if page has its own content (not just a folder)
+page.hasChildren(), page.children   // Direct child Page instances
+page.parent                         // Parent Page instance (null for root pages)
+page.getNavigableRoute()            // First descendant route with content (for linking)
+
+// Hierarchical navigation — content-less containers are group nodes:
+// { route: '/courses/intro', title: 'Introduction', hasContent: false,
+//   navigableRoute: '/courses/intro/lesson-1', children: [...] }
+// Use navigableRoute for links, title for display, hasContent to style differently.
 ```
 
 ### Cross-Block Communication