@koehler8/cms 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.1.0
+
+### Fixed
+
+- **A site-authored `pages/404.json` is no longer indexable.** The framework
+  flagged the not-found page via `selectPage`'s fallback branch only, which
+  runs when *no* page matches the requested path. But the authored page
+  necessarily carries `path: "/404"` so the plugin can pre-render it and copy
+  the output to `404.html` — which also makes it an ordinary route. A direct
+  hit on `/404` matched the path loop first and returned a page nothing
+  downstream recognized as a 404: `usePageMeta` emitted a canonical and skipped
+  the `noindex`, and `sitemapGenerator` listed the URL. Sites that followed the
+  documented advice to author a 404 for custom chrome got an indexable,
+  sitemapped `/404` for their trouble.
+
+  Detection now lives in `src/utils/notFound.js` and is shared by the runtime
+  and the build, so they cannot disagree. The page is matched by its reserved
+  `404` id *or* by resolving to `/404`, is flagged at every resolution point,
+  and is excluded from the sitemap. Authoring `pages/404.json` now does what
+  the docs always said it did: custom chrome *and* correct 404 semantics.
+
+- **The bundled `Header` has a mobile navigation menu.** `content.header.navItems[]`
+  was `display: none` below 720px with nothing to open it, so phone visitors
+  got no primary navigation at all — the header's own comment told sites to
+  override the nav slot, which means forking the component. The links now
+  collapse into a disclosure panel behind a 44×44 toggle: `aria-expanded` /
+  `aria-controls` wired up, ESC closes and restores focus to the toggle,
+  focus-out and outside clicks dismiss it, in-SPA navigation and crossing the
+  breakpoint close it. Overriding the nav slot still suppresses the bundled
+  toggle entirely, so sites with their own responsive header are unaffected.
+
 ## 1.0.0
 
 First stable release. The changes below are the three implementation batches

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",

package/src/components/Header.vue

@@ -8,7 +8,12 @@
       class="site-header__section ui-header__section"
       :class="{ 'ui-header__section--compact': isHeaderCompact }"
     >
-      <nav class="site-header__nav" aria-label="Primary">
+      <nav
+        class="site-header__nav"
+        aria-label="Primary"
+        @keydown.esc="closeNavMenu($event, 'escape')"
+        @focusout="onNavFocusOut"
+      >
         <div class="container">
           <div class="site-header__inner">
             <a href="/" ref="logoLinkRef" class="site-header__logo logo-flash-trigger" :aria-label="`${siteName || 'Home'} – home`">
@@ -33,18 +38,59 @@
             Nav slot. Defaults to a horizontal <ul> of links built from
             `content.header.navItems[]` (each entry: { text, href, target? }).
             No items, no nav.
+
+            Below 720px the row collapses into a disclosure menu behind the
+            toggle button below. Before this existed the list was simply
+            display:none on narrow viewports, which left phone visitors with
+            no primary navigation at all.
           -->
           <slot name="nav" :items="navItems">
-            <ul v-if="navItems.length" class="site-header__nav-list">
+            <ul
+              v-if="navItems.length"
+              id="site-header-nav-menu"
+              ref="navMenuRef"
+              class="site-header__nav-list"
+              :class="{ 'site-header__nav-list--open': isNavOpen }"
+            >
               <li v-for="(item, idx) in navItems" :key="`${item.href || item.text}-${idx}`">
                 <a
                   :href="item.href"
                   :target="item.target || null"
                   :rel="item.target === '_blank' ? 'noopener noreferrer' : null"
+                  @click="closeNavMenu(null, 'selection')"
                 >{{ item.text }}</a>
               </li>
             </ul>
           </slot>
+          <button
+            v-if="navItems.length && !hasNavSlot"
+            ref="navToggleRef"
+            class="site-header__nav-toggle"
+            type="button"
+            aria-controls="site-header-nav-menu"
+            :aria-expanded="isNavOpen ? 'true' : 'false'"
+            :aria-label="isNavOpen ? 'Close menu' : 'Open menu'"
+            @click="toggleNavMenu"
+          >
+            <svg viewBox="0 0 24 24" aria-hidden="true" width="22" height="22">
+              <path
+                v-if="isNavOpen"
+                d="M6 6l12 12M18 6L6 18"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="1.8"
+                stroke-linecap="round"
+              />
+              <path
+                v-else
+                d="M4 7h16M4 12h16M4 17h16"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="1.8"
+                stroke-linecap="round"
+              />
+            </svg>
+          </button>
           <div v-if="hasHeaderActions || showLocaleLinks || hasActionsSlot" class="site-header__actions">
             <!-- Site-provided extra actions, rendered before the locale dropdown. -->
             <slot name="actions" />
@@ -125,8 +171,12 @@ import { readStoredLocale, writeStoredLocale } from '../utils/webStorage.js';
 
   const slots = useSlots();
   const hasActionsSlot = computed(() => Boolean(slots.actions));
+  // A site overriding the nav slot owns its own responsive behaviour, so the
+  // bundled toggle must not render alongside it.
+  const hasNavSlot = computed(() => Boolean(slots.nav));
 
 const isLangOpen = ref(false);
+const isNavOpen = ref(false);
 const isHeaderCompact = ref(false);
 const currentLocale = ref('');
 const availableLocales = computed(() => siteLocales.map((code) => code.trim()).filter(Boolean));
@@ -189,6 +239,8 @@ const localeEmojis = {
 };
   const langButtonRef = ref(null);
   const langMenuRef = ref(null);
+  const navToggleRef = ref(null);
+  const navMenuRef = ref(null);
   const localeWrapperRef = ref(null);
   const localeMenuStyle = ref({ animationDuration: '500ms' });
   const logoLinkRef = ref(null);
@@ -228,9 +280,21 @@ const updateLocaleMenuPosition = () => {
     if (isLangOpen.value) {
       updateLocaleMenuPosition();
     }
+    // Above the breakpoint the toggle is display:none. Leaving isNavOpen true
+    // would strand aria-expanded="true" on a button no longer in the a11y tree.
+    if (isNavOpen.value && typeof window !== 'undefined' && window.innerWidth >= 720) {
+      isNavOpen.value = false;
+    }
   };
 
   const onDocumentClick = (e) => {
+    const navBtn = navToggleRef.value;
+    const navMenu = navMenuRef.value;
+    if (isNavOpen.value && !navBtn?.contains(e.target) && !navMenu?.contains(e.target)) {
+      isNavOpen.value = false;
+      trackEvent('header_nav_menu_toggle', { state: 'close', trigger: 'outside_click' });
+    }
+
     const btn = langButtonRef.value;
     const menu = langMenuRef.value;
     if (btn && btn.contains(e.target)) return; // toggle handled by button
@@ -266,6 +330,41 @@ const updateLocaleMenuPosition = () => {
     }
   };
 
+  const toggleNavMenu = () => {
+    isNavOpen.value = !isNavOpen.value;
+    trackEvent('header_nav_menu_toggle', {
+      state: isNavOpen.value ? 'open' : 'close',
+      trigger: 'click',
+    });
+  };
+
+  // Mirrors closeLocaleMenu: ESC restores focus to the toggle so keyboard
+  // dismissal doesn't strand focus inside a hidden menu (WCAG 2.4.3, 1.4.13).
+  const closeNavMenu = (event, trigger = 'escape') => {
+    if (!isNavOpen.value) return;
+    if (event) {
+      event.preventDefault?.();
+      event.stopPropagation?.();
+    }
+    isNavOpen.value = false;
+    trackEvent('header_nav_menu_toggle', { state: 'close', trigger });
+    if (trigger === 'escape') {
+      nextTick(() => navToggleRef.value?.focus());
+    }
+  };
+
+  // Closes the menu when focus leaves both the menu and its toggle. Scoped to
+  // those two elements rather than the whole <nav> so tabbing from a menu link
+  // to the locale button (also inside <nav>) still dismisses it.
+  const onNavFocusOut = (event) => {
+    if (!isNavOpen.value) return;
+    const next = event.relatedTarget;
+    if (!next) return;
+    if (navMenuRef.value?.contains(next)) return;
+    if (navToggleRef.value?.contains(next)) return;
+    closeNavMenu(null, 'focusout');
+  };
+
   // Closes the menu when keyboard focus leaves the wrapper entirely.
   // Without this, Tab would walk past the dropdown but leave it visible
   // and clickable — also fails 1.4.13's "dismissable" requirement.
@@ -475,6 +574,17 @@ const updateLocaleMenuPosition = () => {
       currentLocale.value = normalized;
     }
   );
+
+  // In-SPA navigation must dismiss the mobile menu. The link click handler
+  // covers taps on the menu's own links; this covers everything else that
+  // changes the route while it's open (back button, a link elsewhere on the
+  // page, a programmatic push).
+  watch(
+    () => route.path,
+    () => {
+      isNavOpen.value = false;
+    }
+  );
 </script>
 
 <style scoped>
@@ -542,8 +652,13 @@ const updateLocaleMenuPosition = () => {
 }
 
 /* Nav menu rendered from content.header.navItems[]. Sits between the logo
-   and the actions cluster. Hidden on narrow viewports — sites that need
-   responsive nav should override the slot. */
+   and the actions cluster.
+
+   Below 720px it becomes a disclosure panel dropped beneath the header bar,
+   opened by .site-header__nav-toggle. (It used to be plain display:none here,
+   with no toggle — phone visitors got no primary navigation at all.) Sites
+   that want something else still override the nav slot, which also suppresses
+   the bundled toggle. */
 .site-header__nav-list {
   display: none;
   list-style: none;
@@ -552,10 +667,76 @@ const updateLocaleMenuPosition = () => {
   gap: clamp(0.75rem, 2vw, 1.75rem);
   align-items: center;
 }
+.site-header__nav-list--open {
+  /* Containing block is .site-header (position: sticky), so this drops the
+     panel flush under the full-width bar rather than under the inner column. */
+  display: flex;
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 0;
+  padding: 0.5rem 0;
+  background: var(--brand-header-bg, #020409);
+  border-top: 1px solid var(--ui-header-divider, rgba(255, 255, 255, 0.12));
+  box-shadow: var(--site-header-shadow, 0 18px 45px rgba(0, 0, 0, 0.35));
+  max-height: calc(100dvh - 100%);
+  overflow-y: auto;
+}
+.site-header__nav-list--open a {
+  display: block;
+  /* Comfortably past the 24x24 minimum for pointer targets (WCAG 2.5.8). */
+  padding: 0.85rem clamp(1rem, 5vw, 2rem);
+}
+
+/* Toggle is mobile-only; the row speaks for itself at 720px and up. */
+.site-header__nav-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  /* 44px square — the comfortable touch target, well past WCAG 2.5.8's 24px. */
+  width: 44px;
+  height: 44px;
+  margin-left: auto;
+  padding: 0;
+  border: 0;
+  border-radius: 8px;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+.site-header__nav-toggle:hover {
+  background: var(--ui-header-hover, rgba(255, 255, 255, 0.08));
+}
+
 @media (min-width: 720px) {
   .site-header__nav-list {
     display: flex;
   }
+  /* Neutralize the open state above the breakpoint: resizing past it while the
+     menu is open must not leave a dropped panel on a desktop layout. */
+  .site-header__nav-list--open {
+    position: static;
+    flex-direction: row;
+    align-items: center;
+    gap: clamp(0.75rem, 2vw, 1.75rem);
+    padding: 0;
+    background: none;
+    border-top: 0;
+    box-shadow: none;
+    max-height: none;
+    overflow-y: visible;
+  }
+  .site-header__nav-list--open a {
+    display: inline;
+    padding: 0;
+  }
+  .site-header__nav-toggle {
+    display: none;
+  }
 }
 .site-header__nav-list a {
   color: var(--brand-header-text, var(--brand-fg-100, inherit));

package/src/composables/usePageConfig.js

@@ -1,6 +1,7 @@
 import { onServerPrefetch, ref, watch } from 'vue';
 import { loadConfigData, mergeConfigTrees, peekConfigSync } from '../utils/loadConfig.js';
 import { readStoredLocale } from '../utils/webStorage.js';
+import { isNotFoundPage, NOT_FOUND_PAGE_ID } from '../utils/notFound.js';
 
 function normalizePath(value) {
   if (!value || typeof value !== 'string') return '/';
@@ -44,7 +45,7 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
     const resolveById = (id) => {
       const data = pages[id];
       if (!data) return null;
-      return {
+      const resolved = {
         id,
         path: data.path ?? '/',
         components: Array.isArray(data.components) ? [...data.components] : [],
@@ -53,6 +54,13 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
         draft: data.draft,
         jsonld: data.jsonld,
       };
+      // A site-authored pages/404.json resolves like any other route (it has a
+      // real path so the plugin can pre-render it), so the flag has to be set
+      // here rather than only on the not-found fallback below. Otherwise a
+      // direct hit on /404 yields a page usePageMeta treats as ordinary —
+      // canonical emitted, noindex omitted — and sitemapGenerator lists it.
+      if (isNotFoundPage(id, resolved.path)) resolved.isNotFound = true;
+      return resolved;
     };
 
     const currentPageId = typeof pageId === 'function' ? pageId() : pageId;
@@ -67,15 +75,7 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
       const requestedPath = normalizePath(currentPagePath);
       for (const [id, data] of entries) {
         if (normalizePath(data.path) === requestedPath) {
-          return {
-            id,
-            path: data.path ?? '/',
-            components: Array.isArray(data.components) ? [...data.components] : [],
-            content: data.content || {},
-            meta: data.meta || {},
-            draft: data.draft,
-            jsonld: data.jsonld,
-          };
+          return resolveById(id);
         }
       }
 
@@ -88,8 +88,10 @@ export function usePageConfig({ pageId, pagePath, locale, onPageLoaded } = {}) {
       // with their own components[]; otherwise the synthesized sentinel
       // renders the bundled NotFound component.
       if (requestedPath !== '/') {
-        const customNotFound = resolveById('404');
+        const customNotFound = resolveById(NOT_FOUND_PAGE_ID);
         if (customNotFound) {
+          // resolveById already flags this; kept explicit so the guarantee is
+          // visible at the call site that depends on it.
           return { ...customNotFound, isNotFound: true };
         }
         return {

package/src/utils/notFound.js

@@ -0,0 +1,52 @@
+/**
+ * Single source of truth for "is this page the not-found page".
+ *
+ * A site can author `pages/404.json` to give the 404 its own chrome and copy.
+ * That page necessarily carries `path: "/404"` so the plugin pre-renders it and
+ * can copy `dist/404/index.html` → `dist/404.html`. The consequence is that it
+ * is also an ordinary route: resolving by id or by path matches it directly,
+ * before `selectPage`'s not-found fallback ever runs.
+ *
+ * Without a shared check, those direct resolutions produce a page that looks
+ * ordinary to everything downstream — `usePageMeta` emits a canonical and skips
+ * the `noindex`, `sitemapGenerator` lists it, and breadcrumbs are derived for
+ * it. The result is an indexable, sitemapped /404, which is the opposite of what
+ * authoring the page was supposed to achieve.
+ *
+ * Both the runtime (usePageConfig → usePageMeta) and the build (sitemapGenerator)
+ * import from here so they cannot disagree about what counts.
+ */
+
+/** Page id the framework reserves for a site-authored not-found page. */
+export const NOT_FOUND_PAGE_ID = '404';
+
+/** Route the not-found page is pre-rendered at. */
+export const NOT_FOUND_PATH = '/404';
+
+/**
+ * Normalize a page path for comparison: leading slash, no duplicate slashes,
+ * no trailing slash. Mirrors the normalization in usePageConfig so `/404/`,
+ * `404`, and `/404` all compare equal.
+ */
+export function normalizeNotFoundPath(value) {
+  if (!value || typeof value !== 'string') return '/';
+  const trimmed = value.trim();
+  if (!trimmed) return '/';
+  let normalized = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  normalized = normalized.replace(/\/+/g, '/');
+  normalized = normalized.replace(/\/+$/, '');
+  return normalized || '/';
+}
+
+/**
+ * True when a page is the not-found page — either by its reserved id or by
+ * being routed at /404. Either alone is enough: a site may name the file
+ * something else but point it at /404, or vice versa.
+ *
+ * @param {string} [id] page id (the content filename without extension)
+ * @param {string} [path] the page's `path` value
+ */
+export function isNotFoundPage(id, path) {
+  if (id === NOT_FOUND_PAGE_ID) return true;
+  return normalizeNotFoundPath(path) === NOT_FOUND_PATH;
+}

package/src/utils/sitemapGenerator.js

@@ -2,7 +2,10 @@
  * Build sitemap.xml from the inflated site config.
  *
  * Pages where isPathDraft() is true are skipped — drafts must not be in the
- * sitemap. Returns '' when site.url is missing (the sitemap protocol requires
+ * sitemap. The not-found page is skipped for the same reason: it is a real
+ * pre-rendered route (so the plugin can copy it to 404.html) but it carries
+ * noindex, and listing a noindex URL is a Search Console warning.
+ * Returns '' when site.url is missing (the sitemap protocol requires
  * absolute URLs); the plugin treats empty output as "do not write the file."
  *
  * Single-locale sites emit only <loc> per page. Multi-locale sites emit one
@@ -15,6 +18,7 @@
 
 import { isPathDraft, normalizeDraftPath } from './draftMode.js';
 import { buildCanonicalUrl } from './canonicalUrl.js';
+import { isNotFoundPage } from './notFound.js';
 
 function escapeXml(value) {
   return String(value).replace(/[<>&'"]/g, (c) => ({
@@ -48,10 +52,13 @@ export function buildSitemap(siteConfig, options = {}) {
   const entries = [];
   const seenPaths = new Set();
 
-  for (const [, pageData] of Object.entries(pages)) {
+  for (const [pageId, pageData] of Object.entries(pages)) {
     if (!pageData || typeof pageData !== 'object') continue;
     const pagePath = normalizeDraftPath(pageData.path) || '/';
     if (isPathDraft(siteConfig, pagePath, pageData)) continue;
+    // The not-found page is pre-rendered as a real route so the plugin can copy
+    // it to 404.html, but it carries noindex and must never be advertised.
+    if (isNotFoundPage(pageId, pagePath)) continue;
     if (seenPaths.has(pagePath)) continue;
     seenPaths.add(pagePath);
 

package/vite-plugin.js

@@ -783,10 +783,11 @@ export default function cmsPlugin(options = {}) {
           // not the bound; see SSG-MEMORY-PLAN.md for the durable fix.
           concurrency: 8,
           // After vite-ssg pre-renders every route, copy the rendered
-          // dist/404/index.html to dist/404.html. AWS Amplify (and most
-          // static hosts) auto-serve a top-level 404.html for any
-          // unmatched URL with HTTP status 404, so this gives sites a
-          // proper not-found response without per-site config.
+          // dist/404/index.html to dist/404.html — the not-found target
+          // hosts point their catch-all at. (GitHub-Pages-style hosts
+          // auto-serve it at HTTP 404; AWS Amplify does NOT — it needs the
+          // fleet's customRule `/<*>` → `/404.html` @ `404`, which Amplify
+          // implements as a 302 redirect. Measured 2026-08-16.)
           onFinished() {
             const distDir = path.join(siteRoot, process.env.CMS_SSG_OUTDIR || 'dist');
             const nestedNotFound = path.join(distDir, '404', 'index.html');
@@ -802,8 +803,11 @@ export default function cmsPlugin(options = {}) {
           includedRoutes(paths) {
             // /404 is the not-found landing page (rendered via the
             // catch-all + NotFound component). onFinished above copies
-            // dist/404/index.html to dist/404.html so AWS Amplify serves
-            // it for unmatched URLs with HTTP 404.
+            // dist/404/index.html to dist/404.html; the host's catch-all
+            // rule sends unmatched URLs there. (On AWS Amplify that rule is
+            // a 302 redirect — its `404` rule type redirects rather than
+            // rewriting, and it has no native 404.html fallback. Measured
+            // 2026-08-16; the page's noindex meta covers the SEO side.)
             const staticRoutes = new Set(['/404']);
             pagePaths.forEach((routePath) => staticRoutes.add(routePath));