@koehler8/cms 1.0.0-beta.8 → 1.0.0

package/src/router/index.js

@@ -3,7 +3,21 @@ import { h } from 'vue';
 
 import Home from '../components/Home.vue';
 
-import { SUPPORTED_LOCALES } from '../constants/locales.js';
+import { availableLocales, baseLocale } from '../utils/loadConfig.js';
+import { readStoredLocale, writeStoredLocale } from '../utils/webStorage.js';
+
+// Test for `/{baseLocale}` or `/{baseLocale}/...` paths — these no longer
+// pre-render or match the locale layout (the canonical URL for the base
+// locale is unprefixed). Used by the router guard to redirect in-SPA
+// navigation so external clicks land on the canonical URL instead of the
+// SPA catch-all → 404 path.
+function stripBaseLocalePrefix(targetPath, base) {
+  if (!base || !targetPath) return null;
+  const root = `/${base}`;
+  if (targetPath === root) return '/';
+  if (targetPath.startsWith(`${root}/`)) return targetPath.slice(root.length) || '/';
+  return null;
+}
 
 const LocaleLayout = {
   name: 'LocaleLayout',
@@ -12,57 +26,96 @@ const LocaleLayout = {
   },
 };
 
-export const routes = [
-  {
+// Locales that should match the `/:locale/...` route — every available
+// locale on disk EXCEPT the base. The base locale is served at the
+// unprefixed path; emitting `/{baseLocale}/path` would be a duplicate URL.
+//
+// Read at module-load time. The vite-plugin's generated entry calls
+// setConfigLoader() synchronously before importing the app, so by the
+// time this module is evaluated (inside main.js), the singletons are
+// populated.
+function computeLocalePrefixes() {
+  if (!Array.isArray(availableLocales)) return [];
+  return availableLocales.filter((l) => typeof l === 'string' && l !== baseLocale);
+}
+
+export function buildRoutes(localePrefixes = computeLocalePrefixes()) {
+  const homeRoute = {
     path: '/',
     name: 'Home',
     component: Home,
     props: { pageId: 'home', pagePath: '/' },
-  },
-  {
-    path: `/:locale(${SUPPORTED_LOCALES.join('|')})`,
-    component: LocaleLayout,
-    children: [
-      {
-        path: '',
-        name: 'HomeLocale',
-        component: Home,
-        props: (route) => ({ pageId: 'home', pagePath: '/', locale: route.params.locale }),
-      },
-      {
-        path: ':pathMatch(.*)*',
-        name: 'LocaleDynamicPage',
-        component: Home,
-        props: (route) => {
-          const pathMatch = route.params.pathMatch;
-          const slugSegments = Array.isArray(pathMatch) ? pathMatch : [pathMatch || ''];
-          const rawSlug = `/${slugSegments.filter(Boolean).join('/')}`;
-          const normalizedSlug = rawSlug.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
-          return { pagePath: normalizedSlug, locale: route.params.locale };
-        },
-      },
-    ],
-  },
-  {
+  };
+
+  const catchAllRoute = {
     path: '/:pathMatch(.*)*',
     name: 'DynamicPage',
     component: Home,
     props: (route) => ({ pagePath: route.path || '/' }),
-  },
-];
+  };
+
+  if (!localePrefixes.length) {
+    // Single-locale site: don't register the locale-prefixed route at all.
+    // `/de/about` etc. fall into the catch-all → DynamicPage with a
+    // pagePath that won't match any page → home fallback.
+    return [homeRoute, catchAllRoute];
+  }
+
+  return [
+    homeRoute,
+    {
+      path: `/:locale(${localePrefixes.join('|')})`,
+      component: LocaleLayout,
+      children: [
+        {
+          path: '',
+          name: 'HomeLocale',
+          component: Home,
+          props: (route) => ({ pageId: 'home', pagePath: '/', locale: route.params.locale }),
+        },
+        {
+          path: ':pathMatch(.*)*',
+          name: 'LocaleDynamicPage',
+          component: Home,
+          props: (route) => {
+            const pathMatch = route.params.pathMatch;
+            const slugSegments = Array.isArray(pathMatch) ? pathMatch : [pathMatch || ''];
+            const rawSlug = `/${slugSegments.filter(Boolean).join('/')}`;
+            const normalizedSlug = rawSlug.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+            return { pagePath: normalizedSlug, locale: route.params.locale };
+          },
+        },
+      ],
+    },
+    catchAllRoute,
+  ];
+}
+
+export const routes = buildRoutes();
 
 function normalizeLocale(value = '') {
   return value.toLowerCase().split('-')[0];
 }
 
-export function applyRouterGuards(router) {
+export function applyRouterGuards(router, localePrefixes = computeLocalePrefixes()) {
   router.beforeEach((to) => {
+    // SPA-side redirect for stale base-locale-prefixed URLs. When a user
+    // navigates inside the app to `/en/about` (and `en` is base), the URL
+    // doesn't pre-render and the catch-all renders the 404 page. Rewrite
+    // to the canonical unprefixed equivalent. Direct external hits to
+    // these URLs still need an Amplify customRule on the host side — see
+    // CLAUDE.md "URL hygiene".
+    const stripped = stripBaseLocalePrefix(to.path, baseLocale);
+    if (stripped !== null && stripped !== to.path) {
+      return { path: stripped, replace: true };
+    }
+
     const rawLocale = (to.params.locale || '').toString().trim();
 
     if (rawLocale) {
       const normalized = normalizeLocale(rawLocale);
 
-      if (!SUPPORTED_LOCALES.includes(normalized)) {
+      if (!localePrefixes.includes(normalized)) {
         return { path: '/', replace: true };
       }
 
@@ -75,19 +128,27 @@ export function applyRouterGuards(router) {
         try {
           document.documentElement.lang = normalized;
         } catch {}
-        try {
-          localStorage.setItem('locale', normalized);
-        } catch {}
+        writeStoredLocale(normalized);
       }
 
       return;
     }
 
     if (!import.meta.env.SSR) {
+      // Browser-language auto-redirect on first visit only. If the user
+      // already has a stored locale preference (set by either an explicit
+      // dropdown click or a previous visit to a locale-prefixed URL),
+      // respect that — don't second-guess them with browser-language
+      // detection. This prevents the bug where clicking "EN" on /de
+      // navigates to / and the auto-detect bounces back to /de because
+      // the browser is set to German.
+      const storedPreference = (readStoredLocale() || '').toString().toLowerCase();
+      if (storedPreference) return;
+
       const navLang = (navigator.language || navigator.userLanguage || '').toString();
       const shortLang = normalizeLocale(navLang || '');
 
-      if (to.path === '/' && SUPPORTED_LOCALES.includes(shortLang)) {
+      if (to.path === '/' && localePrefixes.includes(shortLang)) {
         return { path: `/${shortLang}`, replace: true };
       }
     }

package/src/styles/base.css

@@ -643,7 +643,9 @@ a:focus-visible {
 }
 
 .ui-form-control::placeholder {
-  color: var(--ui-form-placeholder, var(--brand-input-placeholder, rgba(84, 98, 123, 0.64)));
+  /* Solid fallback (#54627b = 5.66:1 on white). Avoid alpha — composited
+     placeholder colors slip below 4.5:1 quickly. */
+  color: var(--ui-form-placeholder, var(--brand-input-placeholder, #54627b));
 }
 
 .ui-form-control:focus {
@@ -692,7 +694,9 @@ a:focus-visible {
 }
 
 .ui-input-group__input::placeholder {
-  color: var(--ui-form-placeholder, var(--brand-input-placeholder, rgba(84, 98, 123, 0.64)));
+  /* Solid fallback (#54627b = 5.66:1 on white). Avoid alpha — composited
+     placeholder colors slip below 4.5:1 quickly. */
+  color: var(--ui-form-placeholder, var(--brand-input-placeholder, #54627b));
 }
 
 .ui-input-group__input:focus {
@@ -852,6 +856,11 @@ a:focus-visible {
   transform: translate3d(0, 0, 0);
 }
 
+.ui-backtotop:focus-visible {
+  outline: 2px solid #ffffff;
+  outline-offset: 3px;
+}
+
 .ui-backtotop__icon {
   font-size: 1rem;
   line-height: 1;

package/src/themes/buildCssVarMap.js

@@ -68,6 +68,12 @@ export function buildCssVarMap(manifest) {
   const radii = tokens.radii || {};
   const elevation = tokens.elevation || {};
   const utility = tokens.utility || {};
+  // Section-chrome blocks for surfaces that pair text with non-default
+  // backgrounds. Components read these to avoid the fallback-chain trap
+  // (e.g. dark hero surface + light --ui-text-primary fallback = invisible).
+  const hero = tokens.hero || {};
+  const footer = tokens.footer || {};
+  const plan = tokens.plan || {};
 
   assignPrefixed(
     vars,
@@ -195,6 +201,15 @@ export function buildCssVarMap(manifest) {
   setVar(vars, '--ui-field-value', text.primary);
   setVar(vars, '--ui-status-heading-color', text.accent || palette.primary);
 
+  // Standalone-page tokens consumed by DraftGate and NotFound, which render
+  // outside any themed section. Every manifest theme feeds these; the two
+  // components keep neutral literal fallbacks for the unthemed case.
+  setVar(vars, '--brand-text', text.primary);
+  setVar(vars, '--brand-text-muted', text.muted);
+  setVar(vars, '--brand-surface', surfaces.base);
+  setVar(vars, '--brand-surface-elevated', surfaces.card || surfaces.raised);
+  setVar(vars, '--brand-border', surfaces.border);
+
   setVar(vars, '--brand-countdown-digit', palette.primary);
   setVar(vars, '--brand-countdown-label', text.muted);
 
@@ -231,6 +246,25 @@ export function buildCssVarMap(manifest) {
   setVar(vars, '--status-price-value-color', palette.accent || palette.primary || text.primary);
   setVar(vars, '--status-price-value-shadow', elevation.raised);
 
+  // Hero text — paired with the hero surface to keep contrast intact when
+  // a consumer overrides the hero bg. textOnDark is the fallback when no
+  // hero.text is set.
+  setVar(vars, '--brand-hero-text', hero.text || text.primary);
+  setVar(vars, '--brand-hero-text-on-dark', hero.textOnDark || text.onDark || text.inverse);
+  setVar(vars, '--brand-hero-eyebrow', hero.eyebrow || palette.primary);
+
+  // Footer chrome — FooterMinimal's default bg is dark, so it reads
+  // these instead of falling through --ui-text-primary (a light-on-light trap).
+  setVar(vars, '--brand-footer-text', footer.text || text.onDark || text.inverse);
+  setVar(vars, '--brand-footer-text-muted', footer.textMuted || text.onDarkMuted);
+  setVar(vars, '--brand-footer-link-color', footer.linkColor || footer.text || text.onDark || text.inverse);
+  setVar(vars, '--brand-footer-link-hover', footer.linkHover || '#ffffff');
+
+  // Plan card chrome — same dark-surface pairing.
+  setVar(vars, '--brand-plan-card-text', plan.cardText || text.inverse);
+  setVar(vars, '--brand-plan-card-muted-text', plan.cardMutedText || text.onDarkMuted);
+  setVar(vars, '--brand-plan-step-ring', plan.stepRing);
+
   return vars;
 }
 

package/src/utils/appInfo.js

@@ -1,9 +1,12 @@
-import packageJsonRaw from '../../package.json?raw';
-
-const packageJson = JSON.parse(packageJsonRaw);
-
+// Framework version as seen by the runtime (used by useComponentResolver's
+// minAppVersion checks and available to extensions).
+//
+// The Vite plugin defines import.meta.env.VITE_APP_VERSION at build time
+// (framework package.json version, overridable by a real VITE_APP_VERSION
+// env var), so no package.json bytes ship in the bundle. Outside the plugin
+// (bare unit tests) the fallback is '0.0.0'.
 const envVersion = import.meta?.env?.VITE_APP_VERSION;
 
 export const APP_VERSION = (typeof envVersion === 'string' && envVersion.trim())
   ? envVersion.trim()
-  : packageJson?.version || '0.0.0';
+  : '0.0.0';

package/src/utils/breadcrumbs.js

@@ -0,0 +1,121 @@
+/**
+ * Build a JSON-LD `BreadcrumbList` for the current page from URL path
+ * segments and the inflated pages map. Drives Google's breadcrumb display
+ * in search results without authors having to hand-author the schema.
+ *
+ * Returns `null` when breadcrumbs aren't applicable (home, draft, 404,
+ * single-segment path with no resolvable hierarchy, missing site.url, or
+ * per-page opt-out via `currentPage.meta.breadcrumbs === false`).
+ *
+ * Label resolution priority for each path prefix `/seg1/seg2/...`:
+ *   1. A page in the inflated config whose `path` matches → its
+ *      `meta.title`, falling back to a slug-derived title-case label.
+ *   2. Otherwise → the last segment formatted (`my-post-title` →
+ *      `My Post Title`).
+ *
+ * The first entry is always `Home` linked at the canonical home URL. The
+ * last entry is the current page; its `item` URL is included (Google
+ * accepts both forms; including is more interoperable).
+ */
+
+import { buildCanonicalUrl } from './canonicalUrl.js';
+
+function normalizePath(value) {
+  if (typeof value !== 'string') return '/';
+  const trimmed = value.trim();
+  if (!trimmed) return '/';
+  let p = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  p = p.replace(/\/+/g, '/').replace(/\/+$/, '');
+  return p || '/';
+}
+
+function titleCaseSlug(slug) {
+  if (typeof slug !== 'string') return '';
+  return slug
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function findPageByPath(pages, targetPath) {
+  if (!pages || typeof pages !== 'object') return null;
+  const norm = normalizePath(targetPath);
+  for (const data of Object.values(pages)) {
+    if (!data || typeof data !== 'object') continue;
+    if (normalizePath(data.path) === norm) return data;
+  }
+  return null;
+}
+
+function resolveLabel(pages, prefixPath, lastSegment) {
+  const page = findPageByPath(pages, prefixPath);
+  const explicitTitle = page?.meta?.title;
+  if (typeof explicitTitle === 'string' && explicitTitle.trim()) {
+    return explicitTitle.trim();
+  }
+  return titleCaseSlug(lastSegment) || lastSegment || '';
+}
+
+export function buildBreadcrumbList({
+  siteUrl,
+  currentPage,
+  pages,
+  baseLocale,
+  locale,
+  trailingSlash = false,
+} = {}) {
+  if (!currentPage || typeof currentPage !== 'object') return null;
+  if (currentPage.isNotFound) return null;
+  if (currentPage.draft === true) return null;
+  if (currentPage.meta && currentPage.meta.breadcrumbs === false) return null;
+
+  const host = (typeof siteUrl === 'string' ? siteUrl : '').trim().replace(/\/+$/, '');
+  if (!host) return null;
+
+  const targetPath = normalizePath(currentPage.path);
+  if (targetPath === '/' || targetPath === '') return null;
+
+  const segments = targetPath.split('/').filter(Boolean);
+  if (segments.length === 0) return null;
+
+  const homeHref = buildCanonicalUrl({
+    siteUrl: host,
+    locale,
+    baseLocale,
+    path: '/',
+    trailingSlash,
+  });
+
+  const items = [
+    {
+      '@type': 'ListItem',
+      position: 1,
+      name: 'Home',
+      item: homeHref,
+    },
+  ];
+
+  for (let i = 0; i < segments.length; i++) {
+    const prefixPath = `/${segments.slice(0, i + 1).join('/')}`;
+    const href = buildCanonicalUrl({
+      siteUrl: host,
+      locale,
+      baseLocale,
+      path: prefixPath,
+      trailingSlash,
+    });
+    items.push({
+      '@type': 'ListItem',
+      position: items.length + 1,
+      name: resolveLabel(pages, prefixPath, segments[i]),
+      item: href,
+    });
+  }
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items,
+  };
+}

package/src/utils/canonicalUrl.js

@@ -0,0 +1,53 @@
+/**
+ * Single source of truth for the canonical URL formula.
+ *
+ * Used by:
+ *   - usePageMeta.js (emits <link rel="canonical"> + <link rel="alternate" hreflang>)
+ *   - sitemapGenerator.js (emits <loc> + <xhtml:link rel="alternate" hreflang>)
+ *
+ * URL space rule (matches Google / Stripe / GitHub conventions):
+ *   - Base locale → ${siteUrl}${path}     e.g. https://example.com/about
+ *   - Non-base    → ${siteUrl}/${locale}${path}   e.g. https://example.com/de/about
+ *
+ * When `trailingSlash` is true, every non-root URL gets a trailing slash
+ * (`/about/`, `/de/`, `/de/about/`) — the root (`/`) is unchanged. This aligns
+ * the canonical with how a static host serving nested `dirStyle` output
+ * (`/about/index.html`) actually serves the page (`/about/`, with `/about`
+ * 301-redirecting to it), so the canonical names the URL that returns 200
+ * instead of one that redirects. Opt in per-site via `site.trailingSlash`;
+ * default (false) is byte-identical to the no-slash scheme.
+ *
+ * Returns '' when siteUrl is missing — sitemaps require absolute URLs and
+ * canonical links without a host are useless. Callers treat '' as "skip".
+ */
+
+function normalizePath(value) {
+  if (typeof value !== 'string') return '/';
+  const trimmed = value.trim();
+  if (!trimmed) return '/';
+  let p = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  p = p.replace(/\/+/g, '/').replace(/\/+$/, '');
+  return p || '/';
+}
+
+function normalizeLocale(value) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim().toLowerCase();
+  return trimmed;
+}
+
+export function buildCanonicalUrl({ siteUrl, locale, baseLocale, path, trailingSlash = false } = {}) {
+  const host = typeof siteUrl === 'string' ? siteUrl.trim().replace(/\/+$/, '') : '';
+  if (!host) return '';
+
+  const normalizedPath = normalizePath(path);
+  const loc = normalizeLocale(locale);
+  const base = normalizeLocale(baseLocale);
+  const slash = trailingSlash ? '/' : '';
+
+  if (!loc || loc === base) {
+    return normalizedPath === '/' ? `${host}/` : `${host}${normalizedPath}${slash}`;
+  }
+
+  return normalizedPath === '/' ? `${host}/${loc}${slash}` : `${host}/${loc}${normalizedPath}${slash}`;
+}

package/src/utils/componentRegistry.js

@@ -1,3 +1,11 @@
+// Bundled CMS components — discovered at module-eval time via the
+// framework's own glob. Site-local components from `site/components/`
+// are added separately at runtime via `setSiteComponents()` (called by
+// the generated entry from a Vite virtual module — see vite-plugin.js
+// VIRTUAL_SITE_COMPONENTS). Site components are checked BEFORE bundled
+// components during resolution (most-specific wins), with a console
+// warning when a site component shadows a bundled component.
+
 const rawModules = import.meta.glob(['../components/**/*.vue', '!../components/Home.vue'], { eager: true });
 
 function normalizeComponentEntry(entry) {
@@ -11,7 +19,7 @@ function resolveComponentName(filePath) {
 }
 
 export function createRegistry(modules) {
-  const registry = Object.entries(modules).reduce((acc, [file, module]) => {
+  return Object.entries(modules).reduce((acc, [file, module]) => {
     const component = normalizeComponentEntry(module);
     if (!component) return acc;
 
@@ -21,26 +29,100 @@ export function createRegistry(modules) {
       acc[componentName] = component;
     }
 
-    if (componentName.startsWith('Spacer') && componentName.length > 'Spacer'.length) {
-      const suffix = componentName.slice('Spacer'.length);
-      const parsed = Number.parseInt(suffix, 10);
-      const score = Number.isFinite(parsed) ? parsed : Number.POSITIVE_INFINITY;
+    return acc;
+  }, {});
+}
 
-      const existing = acc.__spacerFallback;
-      if (!existing || score < existing.score) {
-        acc.__spacerFallback = { component, score };
-      }
+export const registry = createRegistry(rawModules);
+
+// ----------------------------------------------------------------------------
+// Site-local component registry
+//
+// Sites can drop Vue files into `site/components/**/*.vue` and reference them
+// from `pages/{pageId}.json` `components[]` by name — same as bundled or
+// extension components. The vite plugin globs these eagerly into a virtual
+// module that the generated entry imports and hands to `setSiteComponents`.
+//
+// Resolution priority (in useComponentResolver): site → extension → bundled.
+// Source-qualified `site:Name` always resolves to the site-local component;
+// `slug:Name` continues to target a specific extension.
+
+const siteRegistry = {};
+const siteShadows = {};
+
+function buildSiteRegistry(modules) {
+  const next = {};
+  const collisions = {};
+  for (const [file, module] of Object.entries(modules || {})) {
+    const component = normalizeComponentEntry(module);
+    if (!component) continue;
+    const name = resolveComponentName(file);
+    if (!name) continue;
+    if (next[name]) {
+      // Same basename in two different files under site/components/ — keep
+      // the first and warn so the user can rename.
+      (collisions[name] = collisions[name] || []).push(file);
+      continue;
     }
+    next[name] = component;
+  }
+  return { entries: next, duplicates: collisions };
+}
 
-    return acc;
-  }, {});
+/**
+ * Register components found under `site/components/`. Called once during app
+ * initialization by the generated entry. Also accepts the result of an
+ * `import.meta.glob('@cms-site/components/**\/*.vue', { eager: true })` call.
+ */
+export function setSiteComponents(modules) {
+  // Reset prior state so HMR re-registrations don't accumulate stale entries.
+  for (const key of Object.keys(siteRegistry)) delete siteRegistry[key];
+  for (const key of Object.keys(siteShadows)) delete siteShadows[key];
 
-  if (!registry.Spacer && registry.__spacerFallback && registry.__spacerFallback.component) {
-    registry.Spacer = registry.__spacerFallback.component;
+  const source = modules && typeof modules === 'object'
+    ? (modules.default && typeof modules.default === 'object' ? modules.default : modules)
+    : {};
+
+  const { entries, duplicates } = buildSiteRegistry(source);
+  Object.assign(siteRegistry, entries);
+
+  // Emit a single concise warning per site-component name that:
+  //   - shadows a bundled CMS component (overrides are powerful and easy
+  //     to do by accident — flag them so they're explicit), or
+  //   - has duplicate basenames across subdirectories (only the first
+  //     wins; rename or restructure to fix).
+  if (typeof console !== 'undefined' && import.meta.env?.DEV) {
+    for (const name of Object.keys(entries)) {
+      if (registry[name] && registry[name] !== entries[name]) {
+        siteShadows[name] = true;
+        console.warn(
+          `[site-components] "${name}" overrides a bundled CMS component. ` +
+          `Use "site:${name}" in pages/*.json to make this explicit, or rename if accidental.`,
+        );
+      }
+    }
+    for (const [name, files] of Object.entries(duplicates)) {
+      console.warn(
+        `[site-components] Multiple files named "${name}.vue" in site/components/; ` +
+        `keeping the first registration. Duplicates: ${files.join(', ')}.`,
+      );
+    }
   }
-  delete registry.__spacerFallback;
+}
 
-  return registry;
+/**
+ * Lookup helper used by useComponentResolver. Returns the site-local component
+ * for `name` or `undefined`.
+ */
+export function getSiteComponent(name) {
+  if (!name) return undefined;
+  return siteRegistry[name];
 }
 
-export const registry = createRegistry(rawModules);
+/**
+ * Read-only snapshot of the registered site components. Mainly for tests and
+ * tooling; runtime resolution should use getSiteComponent.
+ */
+export function getSiteRegistry() {
+  return { ...siteRegistry };
+}