kmcom-nuxt-layers 1.0.1

package/layers/core/app/composables/useCache.ts

@@ -0,0 +1,138 @@
+/* eslint-disable no-console */
+// composables/useCache.ts
+import { useOnline } from '@vueuse/core'
+
+/**
+ * Cache management composable for PWA
+ *
+ * Provides utilities for managing service worker cache,
+ * checking offline readiness, and clearing cached data.
+ *
+ * @returns Cache state and management functions
+ *
+ * @example
+ * ```typescript
+ * const { isOnline, offlineReady, clearCache } = useCache()
+ *
+ * if (!isOnline && offlineReady) {
+ *   // App works offline
+ * }
+ * ```
+ */
+export function useCache() {
+  const isOnline = useOnline()
+  const offlineReady = ref(false)
+
+  /**
+   * Check if a specific URL is cached
+   * @param url - URL to check
+   */
+  async function isCached(url: string): Promise<boolean> {
+    if (!import.meta.client || !('caches' in window)) return false
+
+    try {
+      const cache = await caches.open('workbox-precache-v2')
+      const response = await cache.match(url)
+      return !!response
+    } catch (error) {
+      console.warn('[useCache] Failed to check cache:', error)
+      return false
+    }
+  }
+
+  /**
+   * Get total cache size in bytes
+   */
+  async function getCacheSize(): Promise<number> {
+    if (!import.meta.client || !('caches' in window)) return 0
+
+    try {
+      const cacheNames = await caches.keys()
+      let totalSize = 0
+
+      for (const cacheName of cacheNames) {
+        const cache = await caches.open(cacheName)
+        const requests = await cache.keys()
+
+        for (const request of requests) {
+          const response = await cache.match(request)
+          if (response) {
+            const blob = await response.blob()
+            totalSize += blob.size
+          }
+        }
+      }
+
+      return totalSize
+    } catch (error) {
+      console.warn('[useCache] Failed to get cache size:', error)
+      return 0
+    }
+  }
+
+  /**
+   * Clear all caches
+   */
+  async function clearCache(): Promise<void> {
+    if (!import.meta.client || !('caches' in window)) return
+
+    try {
+      const cacheNames = await caches.keys()
+      await Promise.all(cacheNames.map((name) => caches.delete(name)))
+
+      console.log('[useCache] All caches cleared')
+    } catch (error) {
+      console.error('[useCache] Failed to clear cache:', error)
+    }
+  }
+
+  /**
+   * Get formatted cache size (human-readable)
+   */
+  async function getFormattedCacheSize(): Promise<string> {
+    const bytes = await getCacheSize()
+
+    if (bytes === 0) return '0 B'
+
+    const units = ['B', 'KB', 'MB', 'GB']
+    const k = 1024
+    const i = Math.floor(Math.log(bytes) / Math.log(k))
+
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${units[i]}`
+  }
+
+  /**
+   * Check if service worker has cached essential resources
+   */
+  async function checkOfflineReady(): Promise<boolean> {
+    if (!import.meta.client || !('caches' in window)) return false
+
+    try {
+      const cacheNames = await caches.keys()
+      // If we have any caches, consider offline ready
+      offlineReady.value = cacheNames.length > 0
+      return offlineReady.value
+    } catch (error) {
+      console.warn('[useCache] Failed to check offline readiness:', error)
+      return false
+    }
+  }
+
+  // Check offline readiness on mount
+  if (import.meta.client) {
+    checkOfflineReady()
+  }
+
+  return {
+    // State
+    isOnline,
+    offlineReady: computed(() => offlineReady.value),
+
+    // Actions
+    isCached,
+    clearCache,
+    getCacheSize,
+    getFormattedCacheSize,
+    checkOfflineReady,
+  }
+}

package/layers/core/app/composables/useDevice.ts

@@ -0,0 +1,36 @@
+// composables/useDevice.ts
+// Device detection composable for Nuxt layers
+// Wraps @nuxtjs/device (if available) and provides SSR/client fallback
+
+/**
+ * Device detection composable
+ *
+ * Returns booleans for isMobile, isTablet, isDesktop
+ * Uses @nuxtjs/device if available, otherwise falls back to user agent sniffing (client only)
+ */
+export function useDevice() {
+  const nuxtApp = useNuxtApp()
+  // @nuxtjs/device injects $device into Nuxt app context
+  const device = nuxtApp.$device
+
+  // If @nuxtjs/device is present, use it
+  if (device) {
+    return {
+      isMobile: computed(() => device.isMobile),
+      isTablet: computed(() => device.isTablet),
+      isDesktop: computed(() => device.isDesktop),
+    }
+  }
+
+  // Fallback: basic user agent detection (client only)
+  const ua = typeof navigator !== 'undefined' ? navigator.userAgent : ''
+  const isMobile = /Mobi|Android|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(ua)
+  const isTablet = /Tablet|iPad/i.test(ua)
+  const isDesktop = !isMobile && !isTablet
+
+  return {
+    isMobile: computed(() => isMobile),
+    isTablet: computed(() => isTablet),
+    isDesktop: computed(() => isDesktop),
+  }
+}

package/layers/core/app/composables/useEnv.ts

@@ -0,0 +1,23 @@
+// composables/useEnv.ts
+
+/**
+ * Type-safe environment variable access
+ *
+ * Provides typed access to Nuxt runtime config with proper
+ * separation between public (client-accessible) and private
+ * (server-only) values.
+ *
+ * @returns Runtime configuration object
+ *
+ * @example
+ * ```typescript
+ * const env = useEnv()
+ * const apiUrl = env.public.apiUrl // Client-accessible
+ * const secretKey = env.secretKey // Server-only
+ * ```
+ */
+export function useEnv() {
+  const config = useRuntimeConfig()
+
+  return config
+}

package/layers/core/app/composables/useErrorLog.ts

@@ -0,0 +1,158 @@
+/**
+ * Error logging composable for tracking and reporting errors
+ *
+ * Features:
+ * - Console logging in development
+ * - Optional external service integration (Sentry, LogRocket, etc.)
+ * - Type-safe error context
+ * - Client-side only (no SSR logging to external services)
+ * - Configurable via app.config
+ *
+ * @example
+ * ```ts
+ * const { logError } = useErrorLog()
+ *
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   logError(error, { context: 'riskyOperation', userId: '123' })
+ * }
+ * ```
+ */
+
+export interface ErrorContext {
+  /** Component name where error occurred */
+  component?: string
+  /** Additional context information */
+  info?: string
+  /** User ID (if available) */
+  userId?: string
+  /** Route path where error occurred */
+  route?: string
+  /** Custom metadata */
+  [key: string]: unknown
+}
+
+export interface ErrorLogConfig {
+  /** Enable console logging in development */
+  logToConsole?: boolean
+  /** Enable external error service logging */
+  logToExternal?: boolean
+  /** External error service URL */
+  externalUrl?: string
+  /** External error service token/key */
+  externalToken?: string
+}
+
+export function useErrorLog() {
+  const appConfig = useAppConfig()
+  const route = useRoute()
+
+  // Get error log configuration from app.config
+  const config = computed(() => {
+    const coreLayer = appConfig.coreLayer as { errors?: ErrorLogConfig } | undefined
+    return {
+      logToConsole: coreLayer?.errors?.logToConsole ?? true,
+      logToExternal: coreLayer?.errors?.logToExternal ?? false,
+      externalUrl: coreLayer?.errors?.externalUrl,
+      externalToken: coreLayer?.errors?.externalToken,
+    }
+  })
+
+  /**
+   * Log an error with optional context
+   */
+  const logError = (error: unknown, context?: ErrorContext) => {
+    // Normalize error to Error object
+    const errorObj = error instanceof Error ? error : new Error(String(error))
+
+    // Build full context
+    const fullContext: ErrorContext = {
+      route: route.path,
+      timestamp: new Date().toISOString(),
+      userAgent: import.meta.client ? navigator.userAgent : 'SSR',
+      ...context,
+    }
+
+    // Console logging (development only by default)
+    if (config.value.logToConsole && import.meta.dev) {
+      // eslint-disable-next-line no-console
+      console.group('🔴 Error Logged')
+      // eslint-disable-next-line no-console
+      console.error('Error:', errorObj)
+      // eslint-disable-next-line no-console
+      console.log('Context:', fullContext)
+      // eslint-disable-next-line no-console
+      console.groupEnd()
+    }
+
+    // External logging (client-side only, production)
+    if (config.value.logToExternal && import.meta.client) {
+      sendToExternalService(errorObj, fullContext)
+    }
+  }
+
+  /**
+   * Send error to external error tracking service
+   */
+  const sendToExternalService = async (error: Error, context: ErrorContext) => {
+    const { externalUrl, externalToken } = config.value
+
+    if (!externalUrl) {
+      // eslint-disable-next-line no-console
+      console.warn('Error logging enabled but no externalUrl configured')
+      return
+    }
+
+    try {
+      await $fetch(externalUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(externalToken ? { Authorization: `Bearer ${externalToken}` } : {}),
+        },
+        body: {
+          error: {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+          },
+          context,
+        },
+      })
+    } catch (loggingError) {
+      // Don't let logging errors crash the app
+      if (import.meta.dev) {
+        // eslint-disable-next-line no-console
+        console.error('Failed to send error to external service:', loggingError)
+      }
+    }
+  }
+
+  /**
+   * Log a warning (non-critical error)
+   */
+  const logWarning = (message: string, context?: ErrorContext) => {
+    if (config.value.logToConsole && import.meta.dev) {
+      // eslint-disable-next-line no-console
+      console.warn('⚠️  Warning:', message, context)
+    }
+  }
+
+  /**
+   * Log info (for debugging)
+   */
+  const logInfo = (message: string, data?: unknown) => {
+    if (config.value.logToConsole && import.meta.dev) {
+      // eslint-disable-next-line no-console
+      console.log('ℹ️  Info:', message, data)
+    }
+  }
+
+  return {
+    logError,
+    logWarning,
+    logInfo,
+    config: readonly(config),
+  }
+}

package/layers/core/app/composables/useFeatures.ts

@@ -0,0 +1,269 @@
+// composables/useFeatures.ts
+import {
+  usePreferredContrast,
+  usePreferredDark,
+  usePreferredReducedMotion,
+  useSessionStorage,
+} from '@vueuse/core'
+import type { FeatureDetection } from '#layers/core/app/types/detection'
+
+/**
+ * Check if CSS feature is supported
+ */
+function checkCSSSupport(property: string, value?: string): boolean {
+  if (!import.meta.client || !window.CSS?.supports) return false
+  if (value === undefined) {
+    // Single-argument form (e.g., "display: flex")
+    return window.CSS.supports(property)
+  }
+  return window.CSS.supports(property, value)
+}
+
+/**
+ * Check if :has() selector is supported
+ * CSS.supports() doesn't reliably detect selector support, so we test directly
+ */
+function checkHasSupport(): boolean {
+  if (!import.meta.client) return false
+  try {
+    document.querySelector(':has(*)')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check if JS API is available
+ */
+function checkAPI(api: string): boolean {
+  if (!import.meta.client) return false
+  return api in window
+}
+
+/**
+ * Get default/empty feature detection object
+ */
+function getDefaultFeatures(): FeatureDetection {
+  return {
+    // CSS Features
+    grid: false,
+    subgrid: false,
+    containerQueries: false,
+    has: false,
+    aspectRatio: false,
+    logicalProperties: false,
+    backdropFilter: false,
+
+    // JS APIs
+    intersectionObserver: false,
+    resizeObserver: false,
+    serviceWorker: false,
+    webGL: false,
+
+    // User Preferences
+    darkMode: false,
+    reducedMotion: false,
+    highContrast: false,
+
+    // Image Formats
+    webp: false,
+    avif: false,
+  }
+}
+
+/**
+ * Detect all features (client-side only)
+ */
+function detectFeatures(): FeatureDetection {
+  // Return defaults if not on client
+  if (!import.meta.client) {
+    return getDefaultFeatures()
+  }
+
+  // Detect features
+  const features: FeatureDetection = {
+    // CSS Features
+    grid: checkCSSSupport('display', 'grid'),
+    subgrid: checkCSSSupport('grid-template-columns', 'subgrid'),
+    containerQueries: checkCSSSupport('container-type', 'inline-size'),
+    has: checkHasSupport(),
+    aspectRatio: checkCSSSupport('aspect-ratio', '1/1'),
+    logicalProperties: checkCSSSupport('margin-inline-start', '1px'),
+    backdropFilter: checkCSSSupport('backdrop-filter', 'blur(1px)'),
+
+    // JS APIs
+    intersectionObserver: checkAPI('IntersectionObserver'),
+    resizeObserver: checkAPI('ResizeObserver'),
+    serviceWorker: 'serviceWorker' in navigator,
+    webGL: !!(
+      document.createElement('canvas').getContext('webgl') ||
+      document.createElement('canvas').getContext('experimental-webgl')
+    ),
+
+    // User Preferences (will be set reactively)
+    darkMode: false,
+    reducedMotion: false,
+    highContrast: false,
+
+    // Image Formats (will be checked async)
+    webp: false,
+    avif: false,
+  }
+
+  return features
+}
+
+/**
+ * Check if image format is supported
+ */
+async function checkImageFormat(format: 'webp' | 'avif'): Promise<boolean> {
+  if (!import.meta.client) return false
+
+  const testImages = {
+    webp: 'data:image/webp;base64,UklGRiQAAABXRUJQVlA4IBgAAAAwAQCdASoBAAEAAwA0JaQAA3AA/vuUAAA=',
+    avif: 'data:image/avif;base64,AAAAIGZ0eXBhdmlmAAAAAGF2aWZtaWYxbWlhZk1BMUIAAADybWV0YQAAAAAAAAAoaGRscgAAAAAAAAAAcGljdAAAAAAAAAAAAAAAAGxpYmF2aWYAAAAADnBpdG0AAAAAAAEAAAAeaWxvYwAAAABEAAABAAEAAAABAAABGgAAAB0AAAAoaWluZgAAAAAAAQAAABppbmZlAgAAAAABAABhdjAxQ29sb3IAAAAAamlwcnAAAABLaXBjbwAAABRpc3BlAAAAAAAAAAIAAAACAAAAEHBpeGkAAAAAAwgICAAAAAxhdjFDgQ0MAAAAABNjb2xybmNseAACAAIAAYAAAAAXaXBtYQAAAAAAAAABAAEEAQKDBAAAACVtZGF0EgAKCBgANogQEAwgMg8f8D///8WfhwB8+ErK42A=',
+  }
+
+  return new Promise((resolve) => {
+    const img = new Image()
+    img.onload = () => resolve(img.width > 0 && img.height > 0)
+    img.onerror = () => resolve(false)
+    img.src = testImages[format]
+  })
+}
+
+/**
+ * Add feature classes to <html> element
+ */
+function applyFeatureClasses(features: FeatureDetection) {
+  if (!import.meta.client || !document.documentElement) return
+
+  // Remove old classes first
+  const htmlClasses = document.documentElement.classList
+  const classesToRemove = Array.from(htmlClasses).filter(
+    (cls) => cls.startsWith('supports-') || cls.startsWith('no-') || cls.startsWith('has-')
+  )
+  htmlClasses.remove(...classesToRemove)
+
+  const classes: string[] = []
+
+  // CSS features
+  classes.push(features.grid ? 'supports-grid' : 'no-grid')
+  classes.push(features.subgrid ? 'supports-subgrid' : 'no-subgrid')
+  classes.push(features.containerQueries ? 'supports-container-queries' : 'no-container-queries')
+  classes.push(features.has ? 'supports-has' : 'no-has')
+  classes.push(features.aspectRatio ? 'supports-aspect-ratio' : 'no-aspect-ratio')
+  classes.push(features.backdropFilter ? 'supports-backdrop-filter' : 'no-backdrop-filter')
+
+  // JS APIs
+  if (features.intersectionObserver) classes.push('has-intersection-observer')
+  if (features.resizeObserver) classes.push('has-resize-observer')
+  if (features.serviceWorker) classes.push('has-service-worker')
+  if (features.webGL) classes.push('has-webgl')
+
+  // Image formats
+  if (features.webp) classes.push('supports-webp')
+  if (features.avif) classes.push('supports-avif')
+
+  htmlClasses.add(...classes)
+}
+
+/**
+ * Feature detection composable
+ *
+ * Detects CSS features, JS APIs, user preferences, and image format support.
+ * Results are cached in sessionStorage (reactive via VueUse) and CSS classes are added to <html>.
+ *
+ * @returns Feature detection state
+ *
+ * @example
+ * ```typescript
+ * const { grid, subgrid, webp, darkMode } = useFeatures()
+ *
+ * if (!subgrid) {
+ *   // Use fallback layout
+ * }
+ * ```
+ */
+export function useFeatures() {
+  // Use VueUse's reactive sessionStorage with lazy initialization
+  const features = useSessionStorage<FeatureDetection>(
+    'core-layer:features',
+    getDefaultFeatures(), // Start with defaults
+    {
+      mergeDefaults: true,
+    }
+  )
+
+  // User preferences (reactive via VueUse)
+  const prefersDark = usePreferredDark()
+  const prefersReducedMotion = usePreferredReducedMotion()
+  const prefersContrast = usePreferredContrast()
+
+  // Only run detection on client
+  if (import.meta.client) {
+    // Detect features immediately on client
+    const detected = detectFeatures()
+    features.value = detected
+
+    // Apply initial classes
+    applyFeatureClasses(features.value)
+
+    // Watch for changes and reapply classes
+    watch(
+      features,
+      (newFeatures) => {
+        applyFeatureClasses(newFeatures)
+      },
+      { deep: true }
+    )
+
+    // Detect image formats asynchronously
+    Promise.all([checkImageFormat('webp'), checkImageFormat('avif')]).then(([webp, avif]) => {
+      features.value.webp = webp
+      features.value.avif = avif
+    })
+  }
+
+  // Update user preference flags reactively
+  watch(
+    [prefersDark, prefersReducedMotion, prefersContrast],
+    () => {
+      features.value.darkMode = prefersDark.value
+      features.value.reducedMotion = prefersReducedMotion.value === 'reduce'
+      features.value.highContrast = prefersContrast.value === 'more'
+    },
+    { immediate: true }
+  )
+
+  // Return individual feature flags as computed refs
+  return {
+    // CSS Features
+    grid: computed(() => features.value.grid),
+    subgrid: computed(() => features.value.subgrid),
+    containerQueries: computed(() => features.value.containerQueries),
+    has: computed(() => features.value.has),
+    aspectRatio: computed(() => features.value.aspectRatio),
+    logicalProperties: computed(() => features.value.logicalProperties),
+    backdropFilter: computed(() => features.value.backdropFilter),
+
+    // JS APIs
+    intersectionObserver: computed(() => features.value.intersectionObserver),
+    resizeObserver: computed(() => features.value.resizeObserver),
+    serviceWorker: computed(() => features.value.serviceWorker),
+    webGL: computed(() => features.value.webGL),
+
+    // User Preferences (reactive)
+    darkMode: prefersDark,
+    reducedMotion: computed(() => prefersReducedMotion.value === 'reduce'),
+    highContrast: computed(() => prefersContrast.value === 'more'),
+
+    // Image Formats
+    webp: computed(() => features.value.webp),
+    avif: computed(() => features.value.avif),
+
+    // Expose the reactive storage for advanced use (e.g., clearing cache)
+    _storage: features,
+  }
+}