@koehler8/cms 1.0.0-beta.5

package/src/utils/analytics.js

@@ -0,0 +1,100 @@
+/**
+ * Lightweight Google Analytics helper that respects consent settings.
+ */
+import { shouldEnableAnalytics } from './cookieConsent.js';
+import { getAnalyticsContext } from './trackingContext.js';
+
+const SENSITIVE_KEYS = new Set(['wallet_address', 'account_address', 'private_key', 'seed_phrase']);
+
+function sanitizeParams(params = {}) {
+  if (!params || typeof params !== 'object') return {};
+  return Object.entries(params).reduce((acc, [key, value]) => {
+    const lowered = key.toLowerCase();
+    if (SENSITIVE_KEYS.has(lowered)) {
+      return acc;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      acc[key] = sanitizeParams(value);
+      return acc;
+    }
+    acc[key] = value;
+    return acc;
+  }, {});
+}
+
+function canTrack() {
+  if (typeof window === 'undefined') return false;
+  if (!shouldEnableAnalytics()) return false;
+  if (typeof window.gtag !== 'function') return false;
+  return true;
+}
+
+/**
+ * Send a GA4 event if analytics is ready.
+ * @param {string} name - GA4 event name.
+ * @param {Record<string, any>} [params] - Additional event parameters.
+ * @returns {boolean} True when the call was sent to gtag.
+ */
+export function trackEvent(name, params = {}) {
+  if (!name || typeof name !== 'string') {
+    if (import.meta.env.DEV) {
+      console.warn('[analytics] trackEvent requires a string name.');
+    }
+    return false;
+  }
+
+  if (!canTrack()) return false;
+
+  try {
+    const payload = sanitizeParams(params);
+    window.gtag('event', name, payload);
+    return true;
+  } catch (error) {
+    if (import.meta.env.DEV) {
+      console.warn('[analytics] Failed to send event', name, error);
+    }
+    return false;
+  }
+}
+
+/**
+ * Set GA4 user properties.
+ * @param {Record<string, any>} properties
+ * @returns {boolean}
+ */
+export function setUserProperties(properties = {}) {
+  if (!properties || typeof properties !== 'object') return false;
+  if (!canTrack()) return false;
+  try {
+    window.gtag('set', 'user_properties', properties);
+    return true;
+  } catch (error) {
+    if (import.meta.env.DEV) {
+      console.warn('[analytics] Failed to set user_properties', error);
+    }
+    return false;
+  }
+}
+
+/**
+ * Public helper to surface readiness in components if needed.
+ * @returns {boolean}
+ */
+export function isAnalyticsReady() {
+  return canTrack();
+}
+
+/**
+ * Alias kept for ergonomic imports in components.
+ */
+export function trackEventIfReady(name, params) {
+  return trackEvent(name, params);
+}
+
+export function trackFunnelEvent(name, params = {}) {
+  const payload = {
+    ...getAnalyticsContext(),
+    ...sanitizeParams(params),
+  };
+  return trackEvent(name, payload);
+}

package/src/utils/appInfo.js

@@ -0,0 +1,9 @@
+import packageJsonRaw from '../../package.json?raw';
+
+const packageJson = JSON.parse(packageJsonRaw);
+
+const envVersion = import.meta?.env?.VITE_APP_VERSION;
+
+export const APP_VERSION = (typeof envVersion === 'string' && envVersion.trim())
+  ? envVersion.trim()
+  : packageJson?.version || '0.0.0';

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,46 @@
+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);

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;
+}