create-kywi-app 0.6.6 → 0.7.0

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

@@ -1090,7 +1090,9 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 /** @param {Answers} a — coupled public site shell. */
 function siteLayout(a) {
   return `import React from 'react'
-import { themeTokenStyleBlock } from '@kywi-software/core/layout'
+import { headers } from 'next/headers'
+import { themeTokenStyleBlock, BUILT_IN_MODULE_COMPONENTS } 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 +1100,23 @@ 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'
 
 /**
  * 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 (\`BUILT_IN_MODULE_COMPONENTS\`)
+ * 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 +1126,26 @@ 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 }) {
+const NavRenderer = BUILT_IN_MODULE_COMPONENTS.navigation
+
+// 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 +1153,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 && (
+              <NavRenderer props={{ items: headerItems, variant: 'horizontal', ariaLabel: 'Primary', depth: 2 }} />
+            )}
             <a className="site-nav__admin" href="/admin">Admin →</a>
-          </nav>
+          </div>
         </div>
       </header>
 
@@ -1131,7 +1166,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 && (
+            <NavRenderer props={{ 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 +1221,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 +1275,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 +1287,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 +1448,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 = (

package/package.json

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