uniweb 0.8.12 → 0.8.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,11 +41,11 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.8.11",
-    "@uniweb/core": "0.5.8",
+    "@uniweb/build": "0.8.13",
     "@uniweb/content-reader": "1.1.4",
-    "@uniweb/kit": "0.7.8",
-    "@uniweb/runtime": "0.6.8",
-    "@uniweb/semantic-parser": "1.1.5"
+    "@uniweb/kit": "0.7.10",
+    "@uniweb/runtime": "0.6.10",
+    "@uniweb/core": "0.5.10",
+    "@uniweb/semantic-parser": "1.1.6"
   }
 }

package/partials/agents.md

@@ -172,7 +172,6 @@ content = {
   title: '',        // Main heading (string or string[] for multi-line)
   pretitle: '',     // Heading before main title (auto-detected)
   subtitle: '',     // Heading after title (string or string[] for multi-line)
-  subtitle2: '',    // Third-level heading
   paragraphs: [],   // Text blocks
   links: [],        // { href, label, role } — standalone links become buttons
   images: [],       // { src, alt, role, href }
@@ -183,7 +182,7 @@ content = {
   quotes: [],       // Blockquotes
   snippets: [],     // Fenced code — [{ language, code }]
   data: {},         // From tagged data blocks (```yaml:tagname, ```json:tagname)
-  headings: [],     // Overflow headings after subtitle2
+  headings: [],     // Headings after subtitle, in document order
   items: [],        // Each has the same flat structure — from headings after body content
   sequence: [],     // All elements in document order
 }
@@ -431,6 +430,13 @@ Does the content author write content *inside* the nested element? **Yes** → c
 
 Inset components declare `inset: true` in meta.js. Don't use `hidden: true` on insets — `hidden` means "don't export this component at all" (for internal helpers), while `inset: true` means "available for `@Component` references in markdown."
 
+**What inset components receive:** Insets are full section types — they get `{ content, params, block }` like any other section. The alt text becomes `content.title`, and attributes become `params`:
+
+```markdown
+![npm create uniweb](@CommandBlock){note="Ready to go"}
+```
+→ CommandBlock receives `content.title = "npm create uniweb"` and `params.note = "Ready to go"`.
+
 **SSG:** Insets, `<ChildBlocks>`, and `<Visual>` all render correctly during prerender. Inset components that use React hooks internally (useState, useEffect) will trigger prerender warnings — this is expected and harmless; the page renders correctly client-side.
 
 ### Section Nesting Details
@@ -601,21 +607,27 @@ Components use **semantic CSS tokens** instead of hardcoded colors. The runtime
 <h2 className="text-heading">...</h2>
 ```
 
-**Core tokens** (available as Tailwind classes):
+**Semantic tokens** (available as Tailwind classes — `text-*`, `bg-*`, `border-*`):
 
 | Token | Purpose |
 |-------|---------|
-| `text-heading` | Headings |
-| `text-body` | Body text |
-| `text-subtle` | Secondary/de-emphasized text |
-| `bg-section` | Section background |
-| `bg-card` | Card/panel background |
-| `bg-muted` | Hover states, zebra rows |
-| `border-border` | Borders |
-| `text-link` | Link color |
-| `bg-primary` / `text-primary-foreground` / `hover:bg-primary-hover` | Primary actions |
-| `bg-secondary` / `text-secondary-foreground` / `hover:bg-secondary-hover` | Secondary actions |
-| `text-success` / `text-error` / `text-warning` / `text-info` | Status colors |
+| `heading` | Heading text |
+| `body` | Body text |
+| `subtle` | Secondary/de-emphasized text |
+| `section` | Section background |
+| `card` | Card/panel/well background |
+| `muted` | Hover states, zebra rows |
+| `border` | Lines, dividers |
+| `ring` | Focus indicators |
+| `link` / `link-hover` | Link colors |
+| `primary` / `primary-foreground` / `primary-hover` / `primary-border` | Primary actions |
+| `secondary` / `secondary-foreground` / `secondary-hover` / `secondary-border` | Secondary actions |
+| `success` / `warning` / `error` / `info` | Status colors |
+| `success-subtle` / `warning-subtle` / `error-subtle` / `info-subtle` | Status backgrounds (alerts) |
+
+Use with any Tailwind prefix: `text-heading`, `bg-section`, `border-border`, `bg-primary`, `text-primary-foreground`, `hover:bg-primary-hover`, `bg-error-subtle`, etc.
+
+**Palette shades** are also available: `text-primary-600`, `bg-neutral-100`, `border-accent-300` — 11 shades (50–950) for each palette color (primary, secondary, accent, neutral). See `theme-tokens.css` for the complete mapping.
 
 **Content authors control context** in frontmatter:
 
@@ -787,14 +799,16 @@ Content fields are **HTML strings** — they contain `<strong>`, `<em>`, `<a>` f
 **Extracted fields** (most common — custom layout with content from markdown):
 
 ```jsx
-import { H1, H2, P, Span } from '@uniweb/kit'
+import { H1, H2, H3, P, Span } from '@uniweb/kit'
 
 <H1 text={content.title} className="text-heading text-5xl font-bold" />
+<H2 text={content.subtitle} className="text-heading text-2xl" />
+<H3 text={item.title} className="text-heading text-lg font-semibold" />
 <P text={content.paragraphs} className="text-body" />
 <Span text={listItem.paragraphs[0]} className="text-subtle" />
 ```
 
-These render their own HTML tag — don't wrap: `<H2 text={...} />` not `<h2><H2 text={...} /></h2>`.
+Kit provides `H1` through `H6` — use the appropriate level for semantic hierarchy. These render their own HTML tag — don't wrap: `<H2 text={...} />` not `<h2><H2 text={...} /></h2>`.
 
 **Full content rendering** (article/docs sections where the author controls the flow):
 
@@ -823,18 +837,46 @@ import { Visual } from '@uniweb/kit'
 
 **Navigation and routing:** `Link` (`to`/`href`, `to="page:about"` for page ID resolution, auto `target="_blank"` for external, `reload` for full page reload), `useActiveRoute()`, `useWebsite()`, `useRouting()`
 
-**Header and layout:** `useScrolled(threshold)`, `useMobileMenu()`, `useAppearance()` (light/dark mode)
+**Header and layout:** `useScrolled(threshold)`, `useMobileMenu()`, `useAppearance()`
 
 **Layout helpers:** `useGridLayout(columns, { gap })`, `useAccordion({ multiple, defaultOpen })`, `useTheme(name)`
 
 **Data and theming:** `useThemeData()` (programmatic color access), `useColorContext(block)`
 
-**Utilities:** `cn()` (Tailwind class merge), `Link`, `Image`, `Asset`, `SafeHtml`, `SocialIcon`, `filterSocialLinks(links)`, `getSocialPlatform(url)`
+**Utilities:** `cn()` (Tailwind class merge — `cn('px-4', condition && 'bg-primary')` resolves conflicts), `Link`, `Image`, `Asset`, `SafeHtml`, `SocialIcon`, `filterSocialLinks(links)`, `getSocialPlatform(url)`
 
 **Other styled:** `SidebarLayout`, `Prose`, `Article`, `Code`, `Alert`, `Table`, `Details`, `Divider`, `Disclaimer`
 
+### Hook Signatures
+
+```js
+useActiveRoute()    → { route, rootSegment, isActive(pageOrRoute), isActiveOrAncestor(pageOrRoute) }
+useMobileMenu()     → { isOpen, open, close, toggle }  // auto-closes on route change
+useScrolled(threshold?) → boolean                       // true when scrolled past threshold (px)
+useAppearance()     → { scheme, setScheme, toggle, canToggle, schemes }
+useWebsite()        → { website }                       // the Website object
+useThemeData()      → Theme                             // programmatic color access
+useColorContext(block) → 'light' | 'medium' | 'dark'   // current section context
+```
+
+`isActive` and `isActiveOrAncestor` accept a Page object or a route string. `useAppearance` reads `appearance:` from `theme.yml` — `scheme` is `'light'`|`'dark'`, `canToggle` reflects `allowToggle` config. Stores preference in localStorage, respects system preference.
+
+### Icon Component
+
+The `<Icon>` renders icons from content or explicit props. The simplest usage — spread an icon object from content:
+
+```jsx
+{content.icons.map((icon, i) => <Icon key={i} {...icon} />)}
+```
+
+Props: `library` + `name` (from content), `svg` (direct SVG string), `url` (fetch from URL), `size` (default `'24'`), `className`. The legacy `icon` prop accepts shorthand strings (`"lu-house"`) or objects.
+
+Built-in icons (no library needed): `check`, `close`, `menu`, `chevronDown`, `chevronRight`, `externalLink`, `download`, `play`, and a few others.
+
 ### Content Patterns for Header and Footer
 
+Layout sections (`header.md`, `footer.md`) are regular section types — they support the full content shape including tagged data blocks, lists, links, icons, and items. The only difference is they render on every page instead of one.
+
 Header and Footer combine several content categories. Use different parts of the content shape for each role:
 
 **Header** — title for logo, list for nav, standalone link for CTA:

package/src/commands/build.js

@@ -225,7 +225,7 @@ async function loadI18nConfig(projectDir, siteConfig = null) {
 
   // Resolve locales (undefined/'*' → all available, array → specific)
   const { resolveLocales } = await import('@uniweb/build/i18n')
-  const locales = await resolveLocales(config.i18n?.locales, localesPath)
+  const locales = await resolveLocales(config.languages, localesPath)
 
   if (locales.length === 0) return null
 

package/src/commands/docs.js

@@ -80,7 +80,7 @@ ${colors.bright}Page Ordering:${colors.reset}
                     Rest are auto-discovered
 
 ${colors.bright}Internationalization:${colors.reset}
-  ${colors.cyan}i18n.locales${colors.reset}      Locales to build (array or "*" for all)
+  ${colors.cyan}languages${colors.reset}         Languages to build (array or "*" for all)
                     Example: [es, fr, de]
   ${colors.cyan}i18n.localesDir${colors.reset}   Translation files directory (default: "locales")
 

package/src/commands/i18n.js

@@ -213,7 +213,7 @@ async function loadSiteConfig(siteRoot) {
 
   // Resolve locales (undefined/'*' → all available, array → specific)
   const { resolveLocales } = await import('@uniweb/build/i18n')
-  const locales = await resolveLocales(config.i18n?.locales, localesPath)
+  const locales = await resolveLocales(config.languages, localesPath)
 
   return {
     defaultLocale: config.defaultLanguage || 'en',
@@ -376,7 +376,7 @@ async function runInit(siteRoot, config, args) {
   if (!targetLocales || targetLocales.length === 0) {
     error('No target locales specified.')
     log(`${colors.dim}Specify locales as arguments (e.g., "uniweb i18n generate es fr")`)
-    log(`or configure them in site.yml under i18n.locales.${colors.reset}`)
+    log(`or configure them in site.yml under languages.${colors.reset}`)
     process.exit(1)
   }
 
@@ -1454,10 +1454,10 @@ ${colors.bright}Options:${colors.reset}
 ${colors.bright}Configuration:${colors.reset}
   Optional site.yml settings:
 
+    languages: [es, fr]           # Languages to build (default: all available)
+
     i18n:
-      locales: [es, fr]          # Specific locales only (default: all available)
-      locales: '*'               # Explicitly all available locales
-      localesDir: locales        # Directory for translation files (default: locales)
+      localesDir: locales          # Directory for translation files (default: locales)
 
   By default, all *.json files in locales/ are treated as translation targets.
 

package/src/commands/inspect.js

@@ -174,7 +174,6 @@ function guaranteeContentStructure(parsedContent) {
     title: content.title || '',
     pretitle: content.pretitle || '',
     subtitle: content.subtitle || '',
-    subtitle2: content.subtitle2 || '',
     alignment: content.alignment || null,
     paragraphs: content.paragraphs || [],
     links: content.links || [],

package/src/index.js

@@ -411,7 +411,7 @@ async function main() {
       type: projectName ? null : 'text',
       name: 'projectName',
       message: 'Project name:',
-      initial: 'my-uniweb-project',
+      initial: 'website',
       validate: (value) => {
         if (!value) return 'Project name is required'
         if (!/^[a-z0-9-]+$/.test(value)) {

package/src/templates/processor.js

@@ -177,7 +177,7 @@ async function processFile(sourcePath, targetPath, data, options = {}) {
  * @param {Function} options.onProgress - Progress callback
  */
 export async function copyTemplateDirectory(sourcePath, targetPath, data, options = {}) {
-  const { onWarning, onProgress } = options
+  const { onWarning, onProgress, skip } = options
 
   await fs.mkdir(targetPath, { recursive: true })
   const entries = await fs.readdir(sourcePath, { withFileTypes: true })
@@ -194,13 +194,19 @@ export async function copyTemplateDirectory(sourcePath, targetPath, data, option
         : sourceName
       const targetFullPath = path.join(targetPath, targetName)
 
-      await copyTemplateDirectory(sourceFullPath, targetFullPath, data, { onWarning, onProgress })
+      await copyTemplateDirectory(sourceFullPath, targetFullPath, data, { onWarning, onProgress, skip })
     } else {
       // Skip template.json as it's metadata for the template, not for the output
       if (sourceName === 'template.json') {
         continue
       }
 
+      // Determine the output filename (strip .hbs extension) for skip check
+      const outputName = sourceName.endsWith('.hbs') ? sourceName.slice(0, -4) : sourceName
+      if (skip?.includes(outputName)) {
+        continue
+      }
+
       // Remove .hbs extension for target filename
       const targetName = sourceName.endsWith('.hbs')
         ? sourceName.slice(0, -4)

package/src/utils/scaffold.js

@@ -30,10 +30,17 @@ const STARTER_DIR = join(__dirname, '..', '..', 'starter')
 export async function scaffoldWorkspace(targetDir, context, options = {}) {
   registerVersions(getVersionsForTemplates())
 
+  // Skip pnpm-workspace.yaml for blank workspaces (no packages yet).
+  // The `add` command creates it on demand via addWorkspaceGlob().
+  // Without this, pnpm fails with ERR_PNPM_NO_IMPORTER_MANIFEST_FOUND
+  // because an empty packages: [] makes pnpm search parent directories.
+  const skip = context.workspaceGlobs?.length ? [] : ['pnpm-workspace.yaml']
+
   const templatePath = join(TEMPLATES_DIR, 'workspace')
   await copyTemplateDirectory(templatePath, targetDir, context, {
     onProgress: options.onProgress,
     onWarning: options.onWarning,
+    skip,
   })
 }