create-kywi-app 0.6.7 → 0.7.1

package/assets/agent-patterns.md

@@ -260,8 +260,8 @@ everywhere.
 | `name` | Purpose |
 |---|---|
 | `breadcrumbs` | Trail of ancestor links |
-| `navMenu` | A named menu (`menuSlug`) rendered to a depth |
-| `navigation` | Site navigation with a style variant and depth |
+| `navMenu` | A named menu (`menuSlug`) in a `variant`: horizontal / mega / vertical / footer |
+| `navigation` | Site navigation in the same four variants, to a depth |
 | `siteMap` | Nested list of the site tree |
 | `searchBox` | Compact search input posting to a results URL |
 | `search` | Full search form (method, label, results URL) |
@@ -328,6 +328,62 @@ page", "Case study" — so new pages start from a consistent skeleton. Hand-writ
 JSX stays fine for genuinely fixed chrome (a bespoke 404, legal boilerplate) —
 but if marketing will ever want to swap a headline, it's a layout page.
 
+### Navigation: menus vs. the site tree
+
+Two sources feed every nav module, and both resolve to the exact same
+render-ready shape — `navMenu`/`navigation` never know which one produced it:
+
+- **Menus** (Menus admin) — an owner-managed, named list of items. Each item
+  either links a content node (its href resolves live off that page — publish,
+  rename, or move the page and the menu link follows) or carries an external
+  URL, plus a label, an optional description (used by `mega` panels) and an
+  open-in-new-window flag. Reference one from a `navMenu` module's `menuSlug`
+  prop.
+- **The site tree** — every page with `isNav` checked (Site Tree admin), in
+  `sortOrder`. A page's nav label is its `menuTitle` when the editor set one,
+  else its `title` — so a long page title ("Plans and Pricing for Teams") can
+  show a short nav label ("Pricing") without a second, independently-maintained
+  copy of the link. `navigation` and `siteMap` modules render this tree, to
+  `depth` levels.
+
+**NEVER hardcode the site nav in chrome.** A hand-typed `<nav>` with pasted
+hrefs is exactly the failure mode this exists to close: a prior marketing
+build's hardcoded header had 7 of its 13 links quietly 404ing, because nothing
+checked them against the pages that actually existed. A menu item's href is
+derived from its linked page, so it cannot drift the way a pasted URL can; a
+site-tree nav module can't drift either, because it IS the tree. Build the
+header/footer from a `navMenu`/`navigation` module (or, in a scaffolded app's
+own chrome, from `scope.menus`/`scope.nav` directly — see below) and never from
+a list of `<a>` tags an agent typed out.
+
+`navMenu`'s `menuSlug` resolves server-side against a real, owner-managed menu.
+Both `navMenu` and `navigation` still accept hand-authored `items` JSON — as
+the fallback when a `menuSlug` names a menu that doesn't (yet) exist, or as a
+deliberate one-off override — but a named menu or the site tree is how a
+*maintained* nav gets built, not hand-typed JSON.
+
+**Variants** (`variant` prop, shared by `navMenu` and `navigation`):
+`horizontal` (dropdown panels — a top bar), `mega` (full-width multi-column
+panels with descriptions — reach for this when a top-level item has several
+children worth previewing), `vertical` (nested fly-outs — a sidebar), `footer`
+(grouped columns of links, no interactivity). Every variant is JS-off safe:
+links always render server-side, and below the mobile breakpoint the bar
+collapses behind a native `<details>` hamburger. The interactive variants carry
+`data-kywi-nav` + `data-kywi-nav-variant`; `@kywi-software/js` auto-boots
+hover-intent, keyboard and outside-click handling on any element with
+`data-kywi-nav` — nothing to wire up beyond loading `/kywi.js`.
+
+**A scaffolded app's own header/footer follow the same rule.**
+`app/(site)/layout.tsx` renders the `'main'` menu when the site has one,
+falling back to the `isNav` site tree — so a fresh install has a working header
+with zero manual wiring, and an owner who later builds a `'main'` menu in the
+admin overrides it with no code change. The footer renders a `'footer'` menu
+only when one exists (no tree fallback there — an unbuilt footer menu should be
+empty, not suddenly cluttered with the whole site tree). Both render through
+the same shared nav renderer as the `navigation` module, never hand-rolled
+markup, so the header and footer get the identical CSS and
+`@kywi-software/js` enhancement as any nav module placed in the page body.
+
 ## 6. Forms: always the Forms builder
 
 Never hand-code a `<form>`. Build forms in the Forms admin (fields, multi-step,

package/lib/templates.mjs

@@ -1087,10 +1087,58 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 `
 }
 
+/**
+ * Client-side wrapper around core's SHARED nav renderer — the same component the
+ * `navigation` module uses — so the site header and footer get identical markup,
+ * CSS (`.kywi-nav-*`) and @kywi-software/js enhancement to any nav placed in a
+ * page body. `items` is whatever app/(site)/layout.tsx resolved server-side (the
+ * owner-managed menu, or the site tree as fallback); nothing is decided here.
+ *
+ * WHY THIS FILE EXISTS — it is `'use client'` on purpose, and the layout that
+ * renders it is a Server Component. `BUILT_IN_MODULE_COMPONENTS` is exported
+ * from one of core's `'use client'` modules, so a Server Component that imports
+ * the map gets a client *reference*, not a real object:
+ * `BUILT_IN_MODULE_COMPONENTS.navigation` reads back `undefined` there and React
+ * throws "Element type is invalid… got: undefined" on every page (kywi-cms#112
+ * follow-up). Crossing the boundary here, in a client module, is what makes the
+ * lookup resolve to the real component — mirrors apps/reference/components/nav.tsx.
+ */
+function siteNavComponent() {
+  return `'use client'
+
+import React from 'react'
+import { BUILT_IN_MODULE_COMPONENTS } from '@kywi-software/core/layout'
+import type { NavMenuItem } from '@kywi-software/core/nav'
+
+// BUILT_IN_MODULE_COMPONENTS is a Record<string, …>, so a literal-key lookup is
+// typed as possibly-undefined under noUncheckedIndexedAccess; 'navigation' is
+// always present — it's one of core's own built-in modules, not user data.
+const NavRenderer = BUILT_IN_MODULE_COMPONENTS.navigation!
+
+export interface SiteNavProps {
+  items: NavMenuItem[]
+  /** \`horizontal\`/\`mega\`/\`vertical\` for the header bar, \`footer\` for the footer columns. */
+  variant: 'horizontal' | 'mega' | 'vertical' | 'footer'
+  ariaLabel: string
+  depth?: number
+}
+
+/** Renders one resolved menu (header or footer) through core's shared nav renderer. */
+export function SiteNav({ items, variant, ariaLabel, depth }: SiteNavProps) {
+  if (items.length === 0) return null
+  return (
+    <NavRenderer props={{ items, variant, ariaLabel, ...(depth ? { depth } : {}) }} />
+  )
+}
+`
+}
+
 /** @param {Answers} a — coupled public site shell. */
 function siteLayout(a) {
   return `import React from 'react'
+import { headers } from 'next/headers'
 import { themeTokenStyleBlock } from '@kywi-software/core/layout'
+import { navTreeToMenuItems, normalizePath } from '@kywi-software/core/nav'
 // Neutral, token-driven defaults for everything Kywi renders (prose, the layout
 // grid + modules, forms, the edit overlay). Restyle via theme tokens, not by
 // editing this — see README → "Theming".
@@ -1098,12 +1146,25 @@ import '@kywi-software/core/site/styles.css'
 // This app's OWN chrome (header / footer / page wrapper). Yours to edit freely.
 import './site.css'
 import config from '../../kywi.config'
+import { getKywi } from '../../lib/kywi'
+import { SiteNav } from '../../components/site-nav'
 
 /**
  * Public site shell. Header + footer carry this project's brand; edit them (and
  * site.css) freely — this is your app's own layer over the DB-backed content
  * that ${'app/(site)/[[...slug]]'} renders.
  *
+ * The header/footer nav is DATA-DRIVEN, never hand-typed: it renders the
+ * owner-managed \`'main'\` menu (Admin → Menus) when one exists, falling back to
+ * the published Site Tree (\`isNav\` pages) so a fresh site has working nav out
+ * of the box — and the footer renders a \`'footer'\` menu when one exists. NEVER
+ * hardcode this list: a menu item's href resolves from its linked page and
+ * can never drift the way a pasted URL can (see AGENTS.md → Navigation).
+ * Rendered through core's shared nav renderer via the generated
+ * \`components/site-nav.tsx\` (a \`'use client'\` wrapper — see that file for why)
+ * rather than bespoke markup, so it gets the same CSS and \`@kywi-software/js\`
+ * enhancement as a \`navigation\` module placed in the page body.
+ *
  * The active site's theme tokens (kywi.config.ts → themes[].tokens) are flattened
  * into a \`:root { --kywi-* }\` block by \`themeTokenStyleBlock\` and injected below,
  * so kywi.config.ts is the single source of truth for the palette and spacing and
@@ -1113,7 +1174,24 @@ const siteTheme =
   config.themes.find((t) => t.name === config.sites[0]?.theme) ?? config.themes[0]
 const themeVars = themeTokenStyleBlock(siteTheme?.tokens)
 
-export default function SiteLayout({ children }: { children: React.ReactNode }) {
+// Content edits (a renamed page, a reordered menu) must show up without a
+// restart — same reasoning as the page route.
+export const dynamic = 'force-dynamic'
+
+export default async function SiteLayout({ children }: { children: React.ReactNode }) {
+  const { scope, siteId } = await getKywi()
+
+  // The middleware forwards the full request URL as \`x-kywi-url\` (see
+  // middleware.ts) so this shared layout can resolve which page is current —
+  // without it, isActive/isAncestor on nav items would have nothing to match.
+  const h = await headers()
+  const url = h.get('x-kywi-url')
+  const currentPath = normalizePath(url ? new URL(url).pathname : '/')
+
+  const mainMenu = await scope.menus.getResolved(siteId, 'main', currentPath)
+  const headerItems = mainMenu ?? navTreeToMenuItems(await scope.nav.getTree(siteId, currentPath))
+  const footerItems = await scope.menus.getResolved(siteId, 'footer', currentPath)
+
   return (
     <div className="site-shell">
       {themeVars ? <style dangerouslySetInnerHTML={{ __html: themeVars }} /> : null}
@@ -1121,9 +1199,12 @@ export default function SiteLayout({ children }: { children: React.ReactNode })
       <header className="site-header">
         <div className="site-header__inner">
           <a className="site-brand" href="/">${escapeJsxText(a.projectName)}</a>
-          <nav className="site-nav" aria-label="Primary">
+          <div className="site-nav">
+            {headerItems.length > 0 && (
+              <SiteNav items={headerItems} variant="horizontal" ariaLabel="Primary" depth={2} />
+            )}
             <a className="site-nav__admin" href="/admin">Admin →</a>
-          </nav>
+          </div>
         </div>
       </header>
 
@@ -1131,7 +1212,10 @@ export default function SiteLayout({ children }: { children: React.ReactNode })
 
       <footer className="site-footer">
         <div className="site-footer__inner">
-          Powered by <a href="https://kywi.dev">Kywi CMS</a>
+          {footerItems && footerItems.length > 0 && (
+            <SiteNav items={footerItems} variant="footer" ariaLabel="Footer" />
+          )}
+          <p className="site-footer__credit">Powered by <a href="https://kywi.dev">Kywi CMS</a></p>
         </div>
       </footer>
     </div>
@@ -1183,6 +1267,14 @@ function siteStyles(a) {
   color: var(--kywi-color-heading, #0f172a);
   text-decoration: none;
 }
+/* Wraps the data-driven nav (rendered by core's shared nav renderer — see
+   app/(site)/layout.tsx) alongside the Admin link. The nav itself carries its
+   own .kywi-nav-* classes, styled by @kywi-software/core/site/styles.css. */
+.site-nav {
+  display: flex;
+  align-items: center;
+  gap: var(--kywi-spacing-md, 1rem);
+}
 .site-nav__admin {
   color: var(--kywi-color-primary, #2563eb);
   text-decoration: none;
@@ -1229,6 +1321,8 @@ function siteStyles(a) {
   font-size: 0.875rem;
 }
 .site-footer__inner a { color: var(--kywi-color-muted, #64748b); }
+/* Sits below the optional footer nav (a 'footer' menu, when one exists). */
+.site-footer__credit { margin: var(--kywi-spacing-md, 1rem) 0 0; }
 `
 }
 
@@ -1239,7 +1333,7 @@ import type { Metadata } from 'next'
 import { notFound } from 'next/navigation'
 import { cookies, headers } from 'next/headers'
 import { KywiBody, KywiEditableAttribute, KywiEditableRegion } from '@kywi-software/core/scope-client'
-import { KywiLayout, KywiRegion, AudienceMetaTags, hydrateLayoutFeeds, type LayoutDocument } from '@kywi-software/core/layout'
+import { KywiLayout, KywiRegion, AudienceMetaTags, hydrateLayoutFeeds, hydrateLayoutNav, type LayoutDocument } from '@kywi-software/core/layout'
 import { KywiJsonLd } from '@kywi-software/core/scope'
 import { ACCESS_COOKIE, canAccessContent, readSessionClaims } from '@kywi-software/core/host'
 import config from '../../../lib/config'
@@ -1400,7 +1494,15 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
     // hydrate feeds and resolve components on the layout THIS visitor sees.
     // variantContainer arms resolve at render time from \`personalization\`.
     const personalized = personalizeLayout(layout, perso.audienceId)
-    const hydrated = await hydrateLayoutFeeds(personalized, buildFeedResolver(runtime))
+    const feedsHydrated = await hydrateLayoutFeeds(personalized, buildFeedResolver(runtime))
+    // Resolve every navMenu/navigation/siteMap module placed in THIS layout
+    // (menuSlug → a real menu; the tree otherwise) — the same seam as feeds,
+    // so a nav module dropped into any region/section just works (#112).
+    const currentPath = String(node['path'] ?? '/')
+    const hydrated = await hydrateLayoutNav(
+      feedsHydrated,
+      runtime.scope.menus.createHydrationResolver(runtime.siteId, currentPath),
+    )
     const componentResolver = await buildComponentResolver(hydrated, runtime)
     const sectionComponentResolver = await buildSectionComponentResolver(hydrated, runtime)
     content = (
@@ -2236,7 +2338,7 @@ lib/config.ts                     single import path for kywi.config.ts
 app/api/v1/[...kywi]/route.ts     the versioned API (delegates to core)
 app/admin/[[...admin]]/page.tsx   mounts the FULL core admin (all surfaces) at /admin
 lib/modules.tsx                   custom (defineModule) module renderers (admin + public)
-app/{llms,robots,sitemap,…}       root AX routes (llms.txt, robots.txt, sitemap.xml, …)${a.mode === 'coupled' ? '\napp/(site)/layout.tsx              public shell: theme tokens + your header/footer\napp/(site)/site.css                your site chrome styles (edit freely)\napp/(site)/[[...slug]]/page.tsx    renders published pages (layout + SEO + JSON-LD + i18n)\nlib/site.ts                        public-render helpers: path/locale resolution, feeds, personalization\ncomponents/personalization-runtime.tsx  optional client runtime (self-ID widget, live re-eval)\napp/(site)/kywi-front-edit.tsx     front-of-site editor: browse toolbar + in-place Layout editor (?kywi-edit=1, lazy-loaded)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
+app/{llms,robots,sitemap,…}       root AX routes (llms.txt, robots.txt, sitemap.xml, …)${a.mode === 'coupled' ? '\napp/(site)/layout.tsx              public shell: theme tokens + your header/footer\napp/(site)/site.css                your site chrome styles (edit freely)\napp/(site)/[[...slug]]/page.tsx    renders published pages (layout + SEO + JSON-LD + i18n)\nlib/site.ts                        public-render helpers: path/locale resolution, feeds, personalization\ncomponents/site-nav.tsx            client wrapper around the shared nav renderer (header + footer)\ncomponents/personalization-runtime.tsx  optional client runtime (self-ID widget, live re-eval)\napp/(site)/kywi-front-edit.tsx     front-of-site editor: browse toolbar + in-place Layout editor (?kywi-edit=1, lazy-loaded)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
 \`\`\`
 `
 }
@@ -2620,6 +2722,11 @@ export function buildFileSet(answers) {
     // page at its slug. More-specific /admin and /api routes take precedence.
     files['app/(site)/layout.tsx'] = siteLayout(answers)
     files['app/(site)/site.css'] = siteStyles(answers)
+    // 'use client' wrapper around core's shared nav renderer — required because
+    // BUILT_IN_MODULE_COMPONENTS is exported from a 'use client' core module, so
+    // the (Server Component) site layout above must render it through here
+    // rather than looking it up directly (see siteNavComponent's doc comment).
+    files['components/site-nav.tsx'] = siteNavComponent()
     files['app/(site)/[[...slug]]/page.tsx'] = siteSlugPage()
     // Public-render helpers: path/locale resolution, feed + component resolvers,
     // personalization + experiments.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kywi-app",
-  "version": "0.6.7",
+  "version": "0.7.1",
   "description": "Scaffold a new Kywi CMS project — npx create-kywi-app my-site",
   "type": "module",
   "homepage": "https://github.com/Kywi-Software/kywi-cms#readme",