uniweb 0.8.9 → 0.8.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.9",
+  "version": "0.8.10",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.8.8",
+    "@uniweb/build": "0.8.9",
     "@uniweb/content-reader": "1.1.4",
     "@uniweb/kit": "0.7.6",
     "@uniweb/core": "0.5.6",

package/partials/agents.md

@@ -50,10 +50,10 @@ This project was created with [Uniweb CLI](https://github.com/uniweb/cli). Full
 | Component metadata (meta.js) | `reference/component-metadata.md` |
 | Migrating existing designs | `development/converting-existing.md` |
 
-> **npm registry:** Use `https://registry.npmjs.org/uniweb` for package metadata — the npmjs.com website blocks automated requests.
-
 ## Project Structure
 
+Most projects start as a workspace with two packages:
+
 ```
 project/
 ├── foundation/     # Component developer's domain
@@ -61,23 +61,24 @@ project/
 └── pnpm-workspace.yaml
 ```
 
-Multi-site variant uses `foundations/` and `sites/` (plural) folders.
+- **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.
+- **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.
 
-- **Foundation** (developer): React components. Those with `meta.js` are *section types* — selectable by content authors via `type:` in frontmatter. Everything else is ordinary React.
-- **Site** (content author): Markdown content + configuration. Each section file references a section type. Authors work here without touching foundation code.
+> Multi-site projects use sub-folders with site/foundation pairs in them, or segregate foundations and sites into separate folders (`foundations/`, `sites/`).
 
 ## Project Setup
 
 Always use the CLI to scaffold projects — never write `package.json`, `vite.config.js`, `main.js`, or `index.html` manually. The CLI resolves correct versions and structure.
 
+**npm or pnpm.** Projects include both `pnpm-workspace.yaml` and npm workspaces. Replace `pnpm` with `npm` in any command below.
+
 ### New workspace
 
 ```bash
-pnpm create uniweb my-project
+pnpm create uniweb my-project --template <n>
 cd my-project && pnpm install
 ```
-
-This creates a workspace with foundation + site + starter content — two commands to a dev server. Use `--template <n>` for an official template (`marketing`, `docs`, `academic`, etc.), `--template none` for foundation + site with no content, or `--blank` for an empty workspace.
+Use `--template <n>` for an official template (`none`, `starter`, `marketing`, `docs`, `academic`, etc.), `--template none` for foundation + site with no content, or `--blank` for an empty workspace.
 
 ### Adding a co-located project
 
@@ -129,8 +130,6 @@ pnpm build      # Build for production
 pnpm preview    # Preview production build (SSG + SPA)
 ```
 
-> **npm works too.** Projects include both `pnpm-workspace.yaml` and npm workspaces. Replace `pnpm` with `npm` in any command above.
-
 ---
 
 ## Content Authoring
@@ -360,7 +359,9 @@ submitLabel: Send
 
 Access: `content.data?.form` → `{ fields: [...], submitLabel: "Send" }`
 
-**Untagged code blocks** (plain ``` js) are only visible to sequential-rendering components. If a component needs to access code blocks by name, tag them (`jsx:before`, `jsx:after` → `content.data?.before`, `content.data?.after`).
+> **FIXME:** The claim below is wrong. I think tagged blocks an only be YAML/JSON. We could add regular code blocks to the parsed content as an array of code blocks or "pre" elements.
+
+**Untagged code blocks** are only visible to sequential-rendering components. If a component needs to access code blocks by name, tag them (`jsx:before`, `jsx:after` → `content.data?.before`, `content.data?.after`).
 
 ### Composition: Nesting and Embedding
 
@@ -461,6 +462,8 @@ export default function Grid({ block, params }) {
 
 Set `background` in frontmatter — the runtime renders it automatically:
 
+> **FIXME:** var(--primary-900) should be primary-900, right?
+
 ```yaml
 background: /images/hero.jpg                             # Image
 background: /videos/hero.mp4                             # Video
@@ -916,8 +919,20 @@ export default {
     compact: { label: 'Compact', params: { columns: 4 } },
   },
 
+  // context and initialState: keys are developer-defined, not framework fields.
+  // Design your own names for your foundation's cross-block communication.
+
+  // Static — neighbors read via getNextBlockInfo().context
   context: {
-    allowTranslucentTop: true,
+    // Example: a Hero might declare this so a Header knows it can float.
+    // allowTranslucentTop: true,
+  },
+
+  // Dynamic — neighbors read via getNextBlockInfo().state
+  // Component can update with useBlockState()
+  initialState: {
+    // Example: Hero starts translucent-ready, but component logic may disable it.
+    // allowTranslucentTop: true,
   },
 }
 ```
@@ -928,46 +943,52 @@ All defaults belong in `meta.js`, not inline in component code.
 
 Section types naturally use params to adjust their own rendering — `variant: flipped` reverses a flex direction, `columns: 3` sets a grid. That's not a pattern, that's the baseline.
 
-The **Front Desk pattern** is when a section type does virtually no rendering itself. It reads the author's params, picks the right helper component from `src/components/`, and translates author-friendly vocabulary into developer-oriented props. The section type is a front desk — it greets the request and routes it to the right specialist:
+The **Front Desk pattern** is when a section type does virtually no rendering itself. It reads the author's params, picks the right helper component, and translates author-friendly vocabulary into developer-oriented props. The section type is a front desk — it greets the request and routes it to the right specialist.
+
+The workers behind the front desk don't need to share the same interface. A `Hero` might delegate to a `SliderHero` that renders an image carousel and a `ContactHero` that renders a quote request form. They expect different content and different props — that's fine. The front desk declares the **union** of all content its workers might need. Some content won't be used for a given variant, and that's perfectly normal in CCA — params change behavior, and that includes not rendering some content:
+
+```js
+// meta.js — the union of all variants' needs
+export default {
+  params: {
+    variant: { type: 'select', options: ['slider', 'contact'], default: 'slider' },
+    slideInterval: { type: 'number', default: 5 },
+    density: { type: 'select', options: ['default', 'compact'], default: 'default' },
+    style: { type: 'select', options: ['default', 'dramatic'], default: 'default' },
+  }
+}
+```
 
 ```jsx
-// sections/Features/index.jsx — the front desk
-import { CardGrid } from '../../components/CardGrid'
-import { CardList } from '../../components/CardList'
-import { ComparisonTable } from '../../components/ComparisonTable'
+// sections/Hero/index.jsx — the front desk
+import { SliderHero } from '../../components/SliderHero'
+import { ContactHero } from '../../components/ContactHero'
 
-const variants = { grid: CardGrid, list: CardList, comparison: ComparisonTable }
+const variants = { slider: SliderHero, contact: ContactHero }
 
-export default function Features({ content, block, params }) {
-  const Layout = variants[params.variant] || CardGrid
+export default function Hero({ content, block, params }) {
+  const Variant = variants[params.variant] || SliderHero
 
   return (
-    <Layout
+    <Variant
+      // Shared — every variant gets these
       title={content.title}
       subtitle={content.paragraphs[0]}
-      items={content.items}
+      links={content.links}
       block={block}
-      columns={params.columns}
-      showIcons={params.showIcon !== false}
+      // Content that only some variants use
+      images={content.imgs}
+      formData={content.data?.quote}
+      // Translated params — author vocabulary → developer props
+      interval={params.slideInterval}
       compact={params.density === 'compact'}
+      transition={params.style === 'dramatic' ? 'zoom' : 'fade'}
     />
   )
 }
 ```
 
-```js
-// meta.js — author-friendly language
-export default {
-  params: {
-    variant: { type: 'select', options: ['grid', 'list', 'comparison'], default: 'grid' },
-    columns: { type: 'number', default: 3 },
-    showIcon: { type: 'boolean', default: true },
-    density: { type: 'select', options: ['default', 'compact'], default: 'default' },
-  }
-}
-```
-
-The content author writes `variant: comparison` — they don't know or care about `ComparisonTable`. The section type translates `density: compact` into a `compact={true}` prop. `CardGrid`, `CardList`, `ComparisonTable` live in `src/components/` — ordinary React, reusable across multiple section types, testable independently.
+`SliderHero` uses `images`, `interval`, and `transition`; it ignores `formData` and `compact`. `ContactHero` uses `formData` and `compact`; it ignores `images` and `interval`. Each worker takes what it needs. Some params only matter for certain variants (`slideInterval` for slider, `density` for contact). Some are high-level names that the front desk translates into developer-oriented values (`style: dramatic` → `transition="zoom"`). The content author writes `variant: contact` — they don't know or care about `ContactHero`.
 
 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.
 
@@ -1027,11 +1048,65 @@ page.hasChildren(), page.children
 
 ### Cross-Block Communication
 
+Section types sometimes need to coordinate. The typical case: a Header needs to know whether the section below it supports a floating translucent overlay — a Hero with a full-bleed background does, a plain text section doesn't. The section that **owns the capability declares it**; the section that **needs to adapt reads it**.
+
+`getBlockInfo()` exposes two channels:
+
+- **`context`** — Static capabilities from `meta.js`. Never changes. The declaring section type always has this capability.
+- **`state`** — Dynamic runtime state via `useBlockState()`. Can change based on component logic. Initial value comes from `initialState` in `meta.js`.
+
+```jsx
+// Header reads the next section's info to decide how to render
+const nextBlockInfo = block.getNextBlockInfo()
+// nextBlockInfo.context  → static (meta.js)
+// nextBlockInfo.state    → dynamic (useBlockState)
+```
+
+**Static context** — Hero declares a permanent capability, Header reads it:
+
+```js
+// Hero/meta.js — "I always support a translucent header over me"
+export default {
+  context: { allowTranslucentTop: true },
+}
+```
+
+```jsx
+// Header/index.jsx — adapts based on what's below
+const nextBlockInfo = block.getNextBlockInfo()
+const isFloating = nextBlockInfo?.context?.allowTranslucentTop || false
+```
+
+**Dynamic state** — Hero declares an initial value but can change it at runtime:
+
+```js
+// Hero/meta.js — starts as true, but component logic may change it
+export default {
+  initialState: { allowTranslucentTop: true },
+}
+```
+
 ```jsx
-const firstBody = block.page.getFirstBodyBlockInfo()
-// → { type, theme, context: { allowTranslucentTop }, state }
+// Hero/index.jsx — conditionally updates
+function Hero({ content, block }) {
+  const [state, setState] = block.useBlockState(useState)
+  // state.allowTranslucentTop is true initially (from meta.js)
+  // Component logic can change it: setState({ allowTranslucentTop: false })
+}
 ```
 
+```jsx
+// Header/index.jsx — reads dynamic state, falls back to static context
+const nextBlockInfo = block.getNextBlockInfo()
+const isFloating = nextBlockInfo?.state?.allowTranslucentTop
+  ?? nextBlockInfo?.context?.allowTranslucentTop
+  ?? false
+```
+
+The key names (`allowTranslucentTop`, `expanded`, etc.) are yours to design — they're not framework fields. Define whatever protocol your foundation's sections need.
+
+Other navigation methods: `block.getPrevBlockInfo()`, `block.page.getFirstBodyBlockInfo()`.
+
 ### Custom Layouts
 
 Layouts live in `foundation/src/layouts/` and are auto-discovered:
@@ -1154,9 +1229,9 @@ Semantic tokens come from `theme-tokens.css` (populated from `theme.yml`). Use `
 
 **Content not appearing as expected?**
 ```bash
-uniweb inspect pages/home/hero.md         # Single section
-uniweb inspect pages/home/                 # Whole page
-uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
+pnpm uniweb inspect pages/home/hero.md         # Single section
+pnpm uniweb inspect pages/home/                 # Whole page
+pnpm uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
 ```
 
 ## Learning from Official Templates
@@ -1164,7 +1239,7 @@ uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
 When you're unsure how to implement a pattern — data fetching, i18n, layouts, insets, theming — install an official template as a reference project in your workspace:
 
 ```bash
-uniweb add project marketing --from marketing
+pnpm uniweb add project marketing --from marketing
 pnpm install
 ```