@koehler8/cms 1.0.0-beta.10

package/src/utils/assetResolver.js

@@ -0,0 +1,162 @@
+/**
+ * Normalize a module key from import.meta.glob into a lookup-friendly format.
+ *
+ * Strips everything up to and including the 'assets/' segment, producing a
+ * relative path like 'img/foo.png'.
+ */
+function normalizeAssetKey(key = '') {
+  const assetsIdx = key.indexOf('assets/');
+  if (assetsIdx !== -1) {
+    return key.slice(assetsIdx + 'assets/'.length);
+  }
+  // Fallback for prefixed patterns like @cms-assets/
+  const lastSlash = key.lastIndexOf('/');
+  return lastSlash >= 0 ? key.slice(lastSlash + 1) : key;
+}
+
+export function createAssetResolver(sharedAssetModules, siteAssetModules) {
+  const assetUrlMap = {};
+
+  // Register shared (framework) assets
+  for (const [key, url] of Object.entries(sharedAssetModules)) {
+    const normalizedKey = normalizeAssetKey(key);
+    if (normalizedKey) {
+      assetUrlMap[normalizedKey] = url;
+    }
+  }
+
+  // Register site assets
+  for (const [key, url] of Object.entries(siteAssetModules)) {
+    const normalizedKey = normalizeAssetKey(key);
+    if (normalizedKey) {
+      assetUrlMap[normalizedKey] = url;
+    }
+  }
+
+  function resolveAssetUrl(path = '') {
+    if (!path || typeof path !== 'string') {
+      return '';
+    }
+    const normalizedPath = path.replace(/^\/+/, '');
+    return assetUrlMap[normalizedPath] || '';
+  }
+
+  function resolveAsset(relativePath = '', options = {}) {
+    if (!relativePath || typeof relativePath !== 'string') {
+      return '';
+    }
+
+    const normalizedPath = relativePath.replace(/^\/+/, '');
+    const extraCandidates = Array.isArray(options.fallbacks) ? options.fallbacks : [];
+    const candidates = new Set();
+
+    const addCandidate = (value) => {
+      if (!value || typeof value !== 'string') return;
+      const candidate = value.replace(/^\/+/, '');
+      if (candidate) {
+        candidates.add(candidate);
+      }
+    };
+
+    const withoutLeadingImg = normalizedPath.startsWith('img/')
+      ? normalizedPath.slice(4)
+      : normalizedPath;
+
+    if (!normalizedPath.startsWith('img/')) {
+      addCandidate(`img/${normalizedPath}`);
+    }
+    if (withoutLeadingImg !== normalizedPath) {
+      addCandidate(`img/${withoutLeadingImg}`);
+    }
+
+    addCandidate(normalizedPath);
+    if (withoutLeadingImg !== normalizedPath) {
+      addCandidate(withoutLeadingImg);
+    }
+
+    extraCandidates.forEach((candidate) => {
+      addCandidate(candidate);
+    });
+
+    for (const candidate of candidates) {
+      if (assetUrlMap[candidate]) {
+        return assetUrlMap[candidate];
+      }
+    }
+
+    return '';
+  }
+
+  function resolveMedia(src = '') {
+    const value = typeof src === 'string' ? src.trim() : '';
+    if (!value) return '';
+    if (/^https?:\/\//i.test(value) || value.startsWith('data:') || value.startsWith('/')) {
+      return value;
+    }
+
+    const normalized = value.replace(/^\/+/, '');
+    const segments = normalized.split('/');
+
+    const mediaCandidates = [normalized];
+    if (segments.length > 1) {
+      const [, ...restSegments] = segments;
+      if (restSegments.length) {
+        mediaCandidates.push(restSegments.join('/'));
+      }
+    }
+    mediaCandidates.push(`img/${normalized}`);
+    mediaCandidates.push(`logos/${normalized}`);
+
+    const uniqueCandidates = Array.from(new Set(mediaCandidates));
+    for (const candidate of uniqueCandidates) {
+      const resolved = resolveAsset(candidate);
+      if (resolved) {
+        return resolved;
+      }
+    }
+
+    return value;
+  }
+
+  return { resolveAssetUrl, resolveAsset, resolveMedia, assetUrlMap };
+}
+
+// ---- Runtime singleton ----
+// Components import resolver functions directly from this module. The Vite
+// plugin's generated entry file calls `setAssetResolver()` with the configured
+// instance (built from the virtual module's globs) at startup, before any
+// component code runs.
+
+const emptyWarning = (name) => () => {
+  if (typeof console !== 'undefined') {
+    console.warn(`[@koehler8/cms] ${name}() called before asset resolver was initialized`);
+  }
+  return '';
+};
+
+let _resolveAssetUrl = emptyWarning('resolveAssetUrl');
+let _resolveAsset = emptyWarning('resolveAsset');
+let _resolveMedia = emptyWarning('resolveMedia');
+let _assetUrlMap = {};
+
+export function setAssetResolver(instance) {
+  if (!instance) return;
+  _resolveAssetUrl = instance.resolveAssetUrl;
+  _resolveAsset = instance.resolveAsset;
+  _resolveMedia = instance.resolveMedia;
+  _assetUrlMap = instance.assetUrlMap || {};
+}
+
+export const resolveAssetUrl = (...args) => _resolveAssetUrl(...args);
+export const resolveAsset = (...args) => _resolveAsset(...args);
+export const resolveMedia = (src) => _resolveMedia(src);
+export const assetUrlMap = new Proxy({}, {
+  get: (_, key) => _assetUrlMap[key],
+  has: (_, key) => key in _assetUrlMap,
+  ownKeys: () => Object.keys(_assetUrlMap),
+  getOwnPropertyDescriptor: (_, key) => {
+    if (key in _assetUrlMap) {
+      return { value: _assetUrlMap[key], enumerable: true, configurable: true };
+    }
+  },
+});

package/src/utils/componentRegistry.js

@@ -0,0 +1,146 @@
+// 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) {
+  return entry && typeof entry === 'object' && 'default' in entry ? entry.default : entry;
+}
+
+function resolveComponentName(filePath) {
+  const normalized = filePath.replace(/^\.{2}\//, '').replace(/\.vue$/i, '');
+  const parts = normalized.split('/');
+  return parts.length ? parts[parts.length - 1] : normalized;
+}
+
+export function createRegistry(modules) {
+  const registry = Object.entries(modules).reduce((acc, [file, module]) => {
+    const component = normalizeComponentEntry(module);
+    if (!component) return acc;
+
+    const componentName = resolveComponentName(file);
+
+    if (!acc[componentName]) {
+      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;
+
+      const existing = acc.__spacerFallback;
+      if (!existing || score < existing.score) {
+        acc.__spacerFallback = { component, score };
+      }
+    }
+
+    return acc;
+  }, {});
+
+  if (!registry.Spacer && registry.__spacerFallback && registry.__spacerFallback.component) {
+    registry.Spacer = registry.__spacerFallback.component;
+  }
+  delete registry.__spacerFallback;
+
+  return registry;
+}
+
+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 };
+}
+
+/**
+ * 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];
+
+  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(', ')}.`,
+      );
+    }
+  }
+}
+
+/**
+ * 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];
+}
+
+/**
+ * Read-only snapshot of the registered site components. Mainly for tests and
+ * tooling; runtime resolution should use getSiteComponent.
+ */
+export function getSiteRegistry() {
+  return { ...siteRegistry };
+}

package/src/utils/contentRequirements.js

@@ -0,0 +1,67 @@
+function hasUsableValue(value) {
+  if (value === null || value === undefined) {
+    return false;
+  }
+  if (typeof value === 'string') {
+    return value.trim().length > 0;
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0;
+  }
+  if (typeof value === 'object') {
+    return Object.keys(value).length > 0;
+  }
+  return true;
+}
+
+function satisfiesSegments(target, segments) {
+  if (!segments.length) {
+    return hasUsableValue(target);
+  }
+  if (target === null || target === undefined) return false;
+
+  const [rawSegment, ...rest] = segments;
+  const isArraySegment = rawSegment.endsWith('[]');
+  const key = isArraySegment ? rawSegment.slice(0, -2) : rawSegment;
+  const nextValue = key ? target?.[key] : target;
+
+  if (isArraySegment) {
+    if (!Array.isArray(nextValue) || nextValue.length === 0) {
+      return false;
+    }
+    if (!rest.length) {
+      return nextValue.some((item) => hasUsableValue(item));
+    }
+    return nextValue.some((item) => satisfiesSegments(item, rest));
+  }
+
+  if (!rest.length) {
+    return hasUsableValue(nextValue);
+  }
+
+  return satisfiesSegments(nextValue, rest);
+}
+
+export function validateRequiredContentPaths(content, requiredPaths = []) {
+  if (!Array.isArray(requiredPaths) || requiredPaths.length === 0) {
+    return { isValid: true, missing: [] };
+  }
+  const missing = [];
+
+  for (const rawPath of requiredPaths) {
+    if (typeof rawPath !== 'string' || !rawPath.trim()) {
+      continue;
+    }
+    const segments = rawPath.split('.').map((segment) => segment.trim()).filter(Boolean);
+    if (!segments.length) continue;
+    const satisfied = satisfiesSegments(content, segments);
+    if (!satisfied) {
+      missing.push(rawPath);
+    }
+  }
+
+  return {
+    isValid: missing.length === 0,
+    missing,
+  };
+}

package/src/utils/cookieConsent.js

@@ -0,0 +1,281 @@
+/**
+ * Cookie Consent Management Utility
+ * Handles storing and retrieving user consent for analytics tracking
+ */
+
+const CONSENT_KEY = 'cookie_consent';
+const CONSENT_TIMESTAMP_KEY = 'cookie_consent_timestamp';
+const TRUTHY_ENV_VALUES = new Set(['1', 'true', 'yes', 'on']);
+
+export const ConsentStatus = {
+  ACCEPTED: 'accepted',
+  DECLINED: 'declined',
+  PENDING: 'pending'
+};
+
+function parseEnvFlag(rawValue) {
+  if (rawValue === undefined || rawValue === null) {
+    return false;
+  }
+
+  if (typeof rawValue === 'boolean') {
+    return rawValue;
+  }
+
+  const normalized = String(rawValue).trim().toLowerCase();
+  if (normalized === '') {
+    return false;
+  }
+
+  return TRUTHY_ENV_VALUES.has(normalized);
+}
+
+export function isCookieBannerEnabled() {
+  return parseEnvFlag(import.meta.env.VITE_SHOW_COOKIE_BANNER);
+}
+
+/**
+ * Get the current consent status
+ * @returns {string} One of ConsentStatus values
+ */
+export function getConsentStatus() {
+  try {
+    const consent = localStorage.getItem(CONSENT_KEY);
+    if (consent === ConsentStatus.ACCEPTED || consent === ConsentStatus.DECLINED) {
+      return consent;
+    }
+    return ConsentStatus.PENDING;
+  } catch (error) {
+    console.warn('Unable to access localStorage for consent:', error);
+    return ConsentStatus.PENDING;
+  }
+}
+
+/**
+ * Set the user's consent status
+ * @param {string} status - One of ConsentStatus values
+ */
+export function setConsentStatus(status) {
+  try {
+    localStorage.setItem(CONSENT_KEY, status);
+    localStorage.setItem(CONSENT_TIMESTAMP_KEY, new Date().toISOString());
+    
+    // Trigger custom event for other parts of the app to react
+    window.dispatchEvent(new CustomEvent('consentChanged', { detail: { status } }));
+  } catch (error) {
+    console.error('Unable to save consent status:', error);
+  }
+}
+
+/**
+ * Accept cookies and analytics tracking
+ */
+export function acceptConsent() {
+  setConsentStatus(ConsentStatus.ACCEPTED);
+}
+
+/**
+ * Decline cookies and analytics tracking
+ */
+export function declineConsent() {
+  setConsentStatus(ConsentStatus.DECLINED);
+}
+
+/**
+ * Revoke previously given consent (records as declined)
+ */
+export function revokeConsent() {
+  declineConsent();
+}
+
+/**
+ * Check if user has accepted consent
+ * @returns {boolean}
+ */
+export function hasAcceptedConsent() {
+  return getConsentStatus() === ConsentStatus.ACCEPTED;
+}
+
+/**
+ * Check if user has declined consent
+ * @returns {boolean}
+ */
+export function hasDeclinedConsent() {
+  return getConsentStatus() === ConsentStatus.DECLINED;
+}
+
+/**
+ * Check if consent is still pending
+ * @returns {boolean}
+ */
+export function isConsentPending() {
+  return getConsentStatus() === ConsentStatus.PENDING;
+}
+
+/**
+ * Determine if analytics should be active.
+ * Pending consent defaults to enabled so tracking starts immediately.
+ *
+ * NOTE: In EU/EEA jurisdictions, GDPR and the ePrivacy Directive require
+ * affirmative consent before setting non-essential cookies or loading
+ * tracking scripts. If the site targets EU users, consider changing the
+ * PENDING case to return false so analytics remain disabled until the
+ * user explicitly accepts.
+ *
+ * @returns {boolean}
+ */
+export function shouldEnableAnalytics() {
+  const status = getConsentStatus();
+  return status === ConsentStatus.ACCEPTED || status === ConsentStatus.PENDING;
+}
+
+let analyticsLoadPromise;
+
+function appendAnalyticsScript(googleId) {
+  if (!googleId) return;
+  if (window.gtag) return;
+
+  const script = document.createElement('script');
+  script.async = true;
+  script.src = `https://www.googletagmanager.com/gtag/js?id=${googleId}`;
+  document.head.appendChild(script);
+
+  window.dataLayer = window.dataLayer || [];
+  function gtag() {
+    window.dataLayer.push(arguments);
+  }
+  window.gtag = gtag;
+  gtag('js', new Date());
+  gtag('config', googleId);
+}
+
+/**
+ * Load Google Analytics if consent is granted
+ */
+export function loadGoogleAnalytics(googleId) {
+  if (!googleId || typeof window === 'undefined') {
+    return;
+  }
+
+  if (!shouldEnableAnalytics()) {
+    return;
+  }
+
+  appendAnalyticsScript(googleId);
+}
+
+function whenHeroIsVisible(selector, callback, timeout = 4000) {
+  if (typeof window === 'undefined') {
+    callback();
+    return;
+  }
+
+  const targets = Array.from(document.querySelectorAll(selector)).filter(Boolean);
+  if (!targets.length || !('IntersectionObserver' in window)) {
+    callback();
+    return;
+  }
+
+  let resolved = false;
+  const resolve = () => {
+    if (resolved) return;
+    resolved = true;
+    observer.disconnect();
+    callback();
+  };
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) {
+        resolve();
+      }
+    },
+    {
+      rootMargin: '0px',
+      threshold: 0.1,
+    }
+  );
+
+  targets.forEach((target) => observer.observe(target));
+
+  window.setTimeout(resolve, timeout);
+}
+
+function deferUntilIdle(callback, timeout = 2000) {
+  if (typeof window === 'undefined') {
+    callback();
+    return;
+  }
+
+  const run = () => {
+    try {
+      callback();
+    } catch (error) {
+      console.error('Deferred analytics load failed:', error);
+    }
+  };
+
+  if ('requestIdleCallback' in window) {
+    window.requestIdleCallback(run, { timeout });
+  } else {
+    window.setTimeout(run, timeout);
+  }
+}
+
+/**
+ * Defer analytics loading until the main content is visible (or idle timeout).
+ * @param {string} googleId
+ * @param {object} [options]
+ * @param {string} [options.selector='#promo, main']
+ * @param {number} [options.visibilityTimeout=4000]
+ * @param {number} [options.idleTimeout=2000]
+ * @returns {Promise<void>}
+ */
+export function scheduleAnalyticsLoad(googleId, options = {}) {
+  if (!googleId || typeof window === 'undefined') {
+    return Promise.resolve();
+  }
+
+  if (!shouldEnableAnalytics()) {
+    return Promise.resolve();
+  }
+
+  if (window.gtag) {
+    return Promise.resolve();
+  }
+
+  if (analyticsLoadPromise) {
+    return analyticsLoadPromise;
+  }
+
+  const {
+    selector = '#promo, main',
+    visibilityTimeout = 4000,
+    idleTimeout = 2000,
+  } = options;
+
+  analyticsLoadPromise = new Promise((resolve) => {
+    const triggerLoad = () => {
+      if (window.gtag) {
+        resolve();
+        return;
+      }
+      appendAnalyticsScript(googleId);
+      resolve();
+    };
+
+    const startObservation = () => {
+      whenHeroIsVisible(selector, () => {
+        deferUntilIdle(triggerLoad, idleTimeout);
+      }, visibilityTimeout);
+    };
+
+    if (document.readyState === 'complete') {
+      startObservation();
+    } else {
+      window.addEventListener('load', startObservation, { once: true });
+    }
+  });
+
+  return analyticsLoadPromise;
+}