uniweb 0.2.42 → 0.2.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.2.42",
+  "version": "0.2.43",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -37,9 +37,9 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.1.23",
-    "@uniweb/core": "0.1.10",
-    "@uniweb/kit": "0.1.5",
-    "@uniweb/runtime": "0.2.11"
+    "@uniweb/build": "0.1.24",
+    "@uniweb/kit": "0.1.6",
+    "@uniweb/runtime": "0.2.12",
+    "@uniweb/core": "0.1.11"
   }
 }

package/partials/agents-md.hbs

@@ -54,8 +54,9 @@ ls foundation/src/components/*/meta.js
 
 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.)
+   - `content` - What content it expects (title, paragraphs, links, items, etc.)
+   - `params` - Configurable parameters with types and defaults
+   - `presets` - Named combinations of param values
    - `hidden: true` - Component exists but isn't selectable from frontmatter
 
 2. **`index.jsx`** - The React implementation
@@ -156,33 +157,400 @@ index: getting-started                   # Or just name the index
 
 ### Props Interface
 
+The runtime provides **guarantees** for component props. No defensive null checks needed:
+
 ```jsx
-function MyComponent({ content, params, block, website }) {
-  const { title, pretitle } = content.main?.header || {}
-  const { paragraphs = [], links = [] } = content.main?.body || {}
-  const items = content.items || []
-  // ...
+function MyComponent({ content, params, block }) {
+  // Runtime guarantees these always exist:
+  const { title, pretitle, subtitle } = content.main.header
+  const { paragraphs, links, imgs } = content.main.body
+  const items = content.items  // Always an array (may be empty)
+
+  // params already has defaults from meta.js merged in:
+  const { theme, layout } = params
+
+  // Access website and page via block or useWebsite() hook:
+  const { website } = useWebsite()  // or use block.website, block.page
 }
 ```
 
+**Guaranteed content shape:**
+```js
+content = {
+  main: {
+    header: { title: '', pretitle: '', subtitle: '' },
+    body: { paragraphs: [], links: [], imgs: [], lists: [], icons: [] },
+  },
+  items: [],
+}
+```
+
+**Best practice:** Keep defaults in `meta.js`, not in component code. This ensures:
+- Documentation consistency (defaults defined once)
+- Cleaner, more readable component code
+- Easier maintenance (change defaults without touching JSX)
+
 ### Using @uniweb/kit
 
+The kit is split into two paths: primitives (no Tailwind dependency) and styled components.
+
+**Primitives** (`@uniweb/kit`):
 ```jsx
-import { H1, P, Link, Image, Section, cn } from '@uniweb/kit'
+import {
+  // Typography
+  H1, H2, H3, P, Span, Text,
+  // Navigation & Media
+  Link, Image, Icon, Media, Asset,
+  // Utilities
+  cn, FileLogo, MediaIcon, SocialIcon,
+  // Hooks
+  useScrolled, useMobileMenu, useAccordion, useActiveRoute,
+  useGridLayout, useTheme,
+} from '@uniweb/kit'
 ```
 
-- `H1, H2, H3, P, Span` - Typography (handles arrays, filters empty)
+**Pre-styled components** (`@uniweb/kit/styled`):
+```jsx
+import {
+  // Layout
+  SidebarLayout,
+  // Content rendering
+  Section, Render,
+  Code, Alert, Table, Details, Divider,
+  // UI
+  Disclaimer,
+  Media,   // styled version with play button facade
+  Asset,   // styled version with card preview
+} from '@uniweb/kit/styled'
+```
+
+Templates include an `@source` directive for kit components by default:
+
+```css
+/* foundation/src/styles.css */
+@import "tailwindcss";
+@source "./components/**/*.jsx";
+@source "../node_modules/@uniweb/kit/src/**/*.jsx";
+```
+
+**Primitives** (from `@uniweb/kit`):
+- `H1`-`H6`, `P`, `Span`, `Text` - Typography (handles arrays, filters empty)
 - `Link` - Smart routing
-- `Image` - Optimized images
-- `Section` - Layout wrapper
+- `Image` - Optimized images with size presets
+- `Icon` - SVG icon loader
+- `Media` - Video player (YouTube, Vimeo, local) - plain version
+- `Asset` - File download link - plain version
+- `FileLogo`, `MediaIcon` - File type icons
+- `SocialIcon` - SVG icons for 15+ social platforms
+
+**Styled components** (from `@uniweb/kit/styled`):
+- `SidebarLayout` - Layout with left/right sidebars (see Custom Layouts below)
+- `Section` - Rich content section with width/padding/columns
+- `Render` - ProseMirror content renderer
+- `Code`, `Alert`, `Table`, `Details`, `Divider` - Content block renderers
+- `Disclaimer` - Modal dialog for legal text
+- `Media` - Video with styled play button facade
+- `Asset` - File card with preview thumbnail and hover overlay
+
+**Hooks:**
+- `useScrolled(threshold)` - Scroll detection (returns boolean)
+- `useMobileMenu()` - Mobile menu state with auto-close on route change
+- `useAccordion({ multiple, defaultOpen })` - Expand/collapse state
+- `useActiveRoute()` - SSG-safe route detection for navigation highlighting
+- `useGridLayout(columns, { gap })` - Responsive grid classes
+- `useTheme(name, overrides)` - Standardized theme classes
+
+**Utilities:**
 - `cn()` - Tailwind class merging
+- `getSocialPlatform(url)` - Detect platform from URL
+- `isSocialLink(url)` - Check if URL is a social platform
+- `filterSocialLinks(links)` - Filter array to social links only
+- `getGridClasses()` / `getThemeClasses()` - Non-hook versions
+
+### Kit Hook Examples
+
+**Scroll-based header styling:**
+```jsx
+import { useScrolled, cn } from '@uniweb/kit'
+
+function Header() {
+  const scrolled = useScrolled(20) // threshold in pixels
+
+  return (
+    <header className={cn(
+      'fixed top-0 transition-all',
+      scrolled ? 'bg-white shadow-lg' : 'bg-transparent'
+    )}>
+      ...
+    </header>
+  )
+}
+```
+
+**Mobile menu with auto-close:**
+```jsx
+import { useMobileMenu } from '@uniweb/kit'
+
+function Header() {
+  const { isOpen, toggle, close } = useMobileMenu()
+
+  // Menu automatically closes on route change
+  return (
+    <>
+      <button onClick={toggle}>Menu</button>
+      {isOpen && (
+        <nav>
+          <Link href="/about" onClick={close}>About</Link>
+        </nav>
+      )}
+    </>
+  )
+}
+```
+
+**Active route highlighting:**
+```jsx
+import { useActiveRoute, cn } from '@uniweb/kit'
+
+function Navigation({ pages }) {
+  const { isActiveOrAncestor } = useActiveRoute()
+
+  return pages.map(page => (
+    <Link
+      key={page.route}
+      href={page.navigableRoute}
+      className={cn(
+        'nav-link',
+        isActiveOrAncestor(page) && 'text-primary font-bold'
+      )}
+    >
+      {page.label}
+    </Link>
+  ))
+}
+```
+
+**Accordion/FAQ:**
+```jsx
+import { useAccordion } from '@uniweb/kit'
+
+function FAQ({ items }) {
+  const { isOpen, toggle } = useAccordion({ expandFirst: true })
+
+  return items.map((item, i) => (
+    <div key={i}>
+      <button onClick={() => toggle(i)}>{item.question}</button>
+      {isOpen(i) && <p>{item.answer}</p>}
+    </div>
+  ))
+}
+```
+
+**Responsive grid:**
+```jsx
+import { useGridLayout } from '@uniweb/kit'
+
+function Features({ items, params }) {
+  const gridClass = useGridLayout(params.columns, { gap: 8 })
+  // Returns: "grid gap-8 sm:grid-cols-2 lg:grid-cols-3" (for columns=3)
+
+  return <div className={gridClass}>{items.map(...)}</div>
+}
+```
+
+**Social icons:**
+```jsx
+import { SocialIcon, filterSocialLinks, Link } from '@uniweb/kit'
+
+function Footer({ links }) {
+  const socialLinks = filterSocialLinks(links)
+
+  return (
+    <div className="flex gap-4">
+      {socialLinks.map((link, i) => (
+        <Link key={i} href={link.href}>
+          <SocialIcon url={link.href} className="w-5 h-5" />
+        </Link>
+      ))}
+    </div>
+  )
+}
+```
+
+**Why use kit hooks:**
+- Eliminates boilerplate (scroll handlers, route effects, state management)
+- Consistent behavior across components
+- SSG-safe (works during static generation)
+- Auto-close menus on navigation (better UX)
+
+### Custom Layouts
+
+Foundations can provide a custom site Layout component via `src/exports.js`. The kit includes `SidebarLayout` for common sidebar layouts:
+
+```jsx
+// foundation/src/exports.js
+import { SidebarLayout } from '@uniweb/kit/styled'
+
+export default {
+  Layout: SidebarLayout,
+}
+```
+
+**SidebarLayout features:**
+- Optional left and/or right sidebars (show whichever panels have content)
+- Desktop: sidebars appear inline at configurable breakpoints
+- Mobile: left panel in slide-out drawer with FAB, right panel hidden
+- Sticky header and sidebar options
+- Auto-close drawer on route change
+
+**Configuration props:**
+```jsx
+import { SidebarLayout } from '@uniweb/kit/styled'
+
+function CustomLayout(props) {
+  return (
+    <SidebarLayout
+      {...props}
+      leftWidth="w-64"         // Left sidebar width
+      rightWidth="w-64"        // Right sidebar width
+      drawerWidth="w-72"       // Mobile drawer width
+      leftBreakpoint="md"      // Show left at md+
+      rightBreakpoint="xl"     // Show right at xl+
+      stickyHeader={true}      // Sticky header
+      stickySidebar={true}     // Sticky sidebars
+      maxWidth="max-w-7xl"     // Content area max width
+    />
+  )
+}
+
+export default { Layout: CustomLayout }
+```
+
+**Layout receives pre-rendered areas:**
+- `header` - From `@header/` sections
+- `body` - Page content sections
+- `footer` - From `@footer/` sections
+- `left` / `leftPanel` - From `@left/` sections (navigation)
+- `right` / `rightPanel` - From `@right/` sections (TOC, contextual info)
+
+**When to use SidebarLayout vs custom:**
+- Use `SidebarLayout` for docs, dashboards, admin panels, or any sidebar site
+- Build custom Layout when you need complex responsive behavior or prose styling
+
+### Website and Page APIs
+
+Access `website` via `useWebsite()` hook or `block.website`. Access `page` via `block.page`:
+
+**Page hierarchy for navigation:**
+```jsx
+import { useWebsite, Link } from '@uniweb/kit'
+
+function Header({ content, params, block }) {
+  const { website } = useWebsite()
+
+  // Get pages for header navigation (respects hideInHeader)
+  const pages = website.getPageHierarchy({ for: 'header' })
+  // Returns: [{ route, navigableRoute, title, label, hasContent, children }]
+
+  return pages.map(page => (
+    <Link href={page.navigableRoute}>{page.label}</Link>
+  ))
+}
+
+function Footer({ content, params }) {
+  const { website } = useWebsite()
+
+  // Get pages for footer (respects hideInFooter)
+  const pages = website.getPageHierarchy({ for: 'footer' })
+}
+```
+
+**Key page info properties:**
+- `page.route` - The page's URL path
+- `page.navigableRoute` - URL to use for links (may differ if page has no content)
+- `page.label` - Short navigation label (falls back to title)
+- `page.hasContent` - Whether page has renderable sections
+- `page.children` - Nested child pages (if any)
+
+**Locale handling (for multilingual sites):**
+```jsx
+import { useWebsite } from '@uniweb/kit'
+
+function Header({ content, params }) {
+  const { website } = useWebsite()
+
+  if (website.hasMultipleLocales()) {
+    const locales = website.getLocales() // [{code, label, isDefault}]
+    const active = website.getActiveLocale() // 'en'
+
+    return locales.map(locale => (
+      <a
+        key={locale.code}
+        href={website.getLocaleUrl(locale.code)}
+        className={locale.code === active ? 'font-bold' : ''}
+      >
+        {locale.label}
+      </a>
+    ))
+  }
+}
+```
+
+**Active route detection (SSG-safe):**
+```jsx
+import { useActiveRoute } from '@uniweb/kit'
+
+function Navigation({ pages }) {
+  const { route, isActiveOrAncestor } = useActiveRoute()
+
+  // route: current normalized route (e.g., 'docs/getting-started')
+  // isActiveOrAncestor(page): true if page matches or is parent of current route
+}
+```
 
 ### 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`
+3. Rebuild: `cd foundation && pnpm build`
+
+### Component Organization
+
+By default, exposed components (those with `meta.js`) live in `src/components/`:
+
+```
+foundation/src/
+├── components/          # Exposed components (auto-discovered)
+│   ├── Hero/
+│   │   ├── index.jsx
+│   │   └── meta.js      # Makes this component available to content
+│   └── Features/
+│       ├── index.jsx
+│       └── meta.js
+├── shared/              # Internal components (no meta.js)
+│   ├── Button/
+│   └── Card/
+└── styles.css
+```
+
+**Discovery rule:** A component is exposed if it has a `meta.js` file. Components without `meta.js` are internal helpers.
+
+**For complex projects**, you can organize exposed components in subdirectories:
+
+```js
+// vite.config.js
+import { defineFoundationConfig } from '@uniweb/build'
+
+export default defineFoundationConfig({
+  components: [
+    'components',           // src/components/*/meta.js
+    'components/marketing', // src/components/marketing/*/meta.js
+    'components/docs',      // src/components/docs/*/meta.js
+  ]
+})
+```
+
+This allows organizing exposed components by category while keeping internal components separate.
 
 ### meta.js Structure
 
@@ -190,26 +558,150 @@ import { H1, P, Link, Image, Section, cn } from '@uniweb/kit'
 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' },
+  category: 'marketing',         // For grouping in editors
+  // hidden: true,               // Uncomment to hide from content authors
+
+  // Document expected content (for editors/validation)
+  content: {
+    pretitle: 'Eyebrow text',
+    title: 'Headline',
+    paragraphs: 'Description [1-2]',
+    links: 'CTA buttons [1-2]',
   },
-  properties: {
+
+  // Configurable parameters with defaults
+  params: {
     theme: {
       type: 'select',
       label: 'Theme',
-      options: [
-        { value: 'light', label: 'Light' },
-        { value: 'dark', label: 'Dark' },
-      ],
-      default: 'light',
+      options: ['light', 'dark', 'gradient'],
+      default: 'light',           // Runtime applies this if not set
     },
+    columns: {
+      type: 'number',
+      label: 'Columns',
+      default: 3,
+    },
+    showIcon: {
+      type: 'boolean',
+      label: 'Show Icon',
+      default: true,
+    },
+  },
+
+  // Named presets (combinations of params)
+  presets: {
+    default: { label: 'Standard', params: { theme: 'light', columns: 3 } },
+    dark: { label: 'Dark Mode', params: { theme: 'dark', columns: 3 } },
+    compact: { label: 'Compact', params: { theme: 'light', columns: 4 } },
   },
+
+  // Static capabilities for cross-block coordination (optional)
+  context: {
+    allowTranslucentTop: true,   // Header can overlay this section
+  },
+
+  // Initial values for mutable block state (optional)
+  initialState: {
+    expanded: false,
+  },
+}
+```
+
+**Key principle:** All defaults belong in `meta.js`. Component code should never have inline defaults like `theme || 'light'` or `columns ?? 3`.
+
+### Cross-Block Communication
+
+Components can read information from neighboring blocks via `block.getNextBlockInfo()` or `block.page.getFirstBodyBlockInfo()`. This enables adaptive behavior like headers that become translucent over hero sections.
+
+**Block info structure:**
+```js
+{
+  type: 'Hero',           // Component type
+  theme: 'dark',          // Theme setting
+  state: { ... },         // Dynamic state (mutable at runtime)
+  context: { ... },       // Static context (from meta.js, immutable)
+}
+```
+
+**Key distinction:**
+- **`context`** — Static capabilities per component type. Defined in meta.js. "All Hero components support translucent navbar overlay."
+- **`state`** — Dynamic values per block instance. Can change via `useBlockState`. "This accordion has item 2 open."
+
+**Example: Header adapting to first section:**
+```jsx
+function Header({ content, params, block }) {
+  const firstBodyInfo = block.page.getFirstBodyBlockInfo()
+
+  // Use context (static) to check capability
+  const allowTranslucentTop = firstBodyInfo?.context?.allowTranslucentTop || false
+
+  // Use theme (from params) for color adaptation
+  const isDarkTheme = firstBodyInfo?.theme === 'dark'
+
+  return (
+    <header className={cn(
+      allowTranslucentTop ? 'absolute bg-transparent' : 'relative bg-white',
+      isDarkTheme ? 'text-white' : 'text-gray-900'
+    )}>
+      ...
+    </header>
+  )
+}
+```
+
+**Hero declaring its context:**
+```javascript
+// Hero/meta.js
+export default {
+  title: 'Hero Banner',
+  context: {
+    allowTranslucentTop: true,  // Header can overlay this section
+  },
+  params: { ... },
 }
 ```
 
+### Block State
+
+Block state persists across renders and SPA page navigations. Use for UI state like accordion open/closed, tabs, form input.
+
+```jsx
+import { useState } from 'react'
+
+function Accordion({ content, params, block }) {
+  // Bridge pattern: pass useState to block
+  const [state, setState] = block.useBlockState(useState)
+
+  const toggle = (index) => {
+    setState({ ...state, openItem: state.openItem === index ? null : index })
+  }
+
+  return content.items.map((item, i) => (
+    <div key={i}>
+      <button onClick={() => toggle(i)}>{item.header.title}</button>
+      {state.openItem === i && <p>{item.body.paragraphs[0]}</p>}
+    </div>
+  ))
+}
+```
+
+**Initial state in meta.js:**
+```javascript
+// Accordion/meta.js
+export default {
+  title: 'Accordion',
+  initialState: {
+    openItem: null,
+  },
+  params: { ... },
+}
+```
+
+**When to use block state vs React state:**
+- **Block state** — UI state that should persist across SPA navigation (accordion position, form input)
+- **React state** — Temporary state that should reset on navigation (hover effects, animations)
+
 ### Parameter Philosophy
 
 Design parameters that describe **intent**, not implementation: