kmcom-nuxt-layers 1.0.1

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

@@ -0,0 +1,109 @@
+// composables/useLoading.ts
+
+interface LoadingState {
+  isLoading: Ref<boolean>
+  progress: Ref<number>
+}
+
+// Shared state across all calls (singleton pattern)
+const state: LoadingState = {
+  isLoading: ref(true), // Start as true for initial app load
+  progress: ref(0),
+}
+
+let progressInterval: ReturnType<typeof setInterval> | null = null
+let progressTimeout: ReturnType<typeof setTimeout> | null = null
+
+/**
+ * Loading state composable for app initialization and async operations
+ *
+ * Features:
+ * - Simulated progress (0-90% auto, then waits)
+ * - Shared state across all component instances
+ * - Can be disabled via app.config
+ * - Works without UI component (headless)
+ *
+ * @param id - Optional scoped loading ID (for future multi-loading support)
+ * @returns Loading state and control methods
+ */
+export function useLoading() {
+  /**
+   * Start loading with simulated progress
+   * Progress will automatically increment from 0 to ~90
+   */
+  function startLoading(): void {
+    state.isLoading.value = true
+    state.progress.value = 0
+
+    // Clear any existing intervals
+    if (progressInterval) clearInterval(progressInterval)
+    if (progressTimeout) clearTimeout(progressTimeout)
+
+    // Simulate progress: increment randomly to 90%, then wait
+    progressInterval = setInterval(() => {
+      if (state.progress.value < 90) {
+        // Random increment between 3-8%
+        const increment = Math.random() * 5 + 3
+        state.progress.value = Math.min(state.progress.value + increment, 90)
+      } else {
+        // Stop at 90, wait for manual completion
+        if (progressInterval) {
+          clearInterval(progressInterval)
+          progressInterval = null
+        }
+      }
+    }, 150) // Update every 150ms
+  }
+
+  /**
+   * Stop loading and jump to 100%
+   */
+  function stopLoading(): void {
+    // Clear any running intervals
+    if (progressInterval) {
+      clearInterval(progressInterval)
+      progressInterval = null
+    }
+
+    // Jump to 100%
+    state.progress.value = 100
+
+    // Mark as not loading after a brief delay (allows 100% to be visible)
+    progressTimeout = setTimeout(() => {
+      state.isLoading.value = false
+    }, 100)
+  }
+
+  /**
+   * Manually update progress (0-100)
+   * @param value - Progress percentage (0-100)
+   */
+  function updateProgress(value: number): void {
+    state.progress.value = Math.min(Math.max(value, 0), 100)
+  }
+
+  /**
+   * Execute async function with loading state
+   * @param fn - Async function to execute
+   */
+  async function withLoading(fn: () => Promise<void>): Promise<void> {
+    startLoading()
+    try {
+      await fn()
+    } finally {
+      stopLoading()
+    }
+  }
+
+  return {
+    // State (reactive refs)
+    isLoading: readonly(state.isLoading),
+    progress: readonly(state.progress),
+
+    // Actions
+    startLoading,
+    stopLoading,
+    updateProgress,
+    withLoading,
+  }
+}

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

@@ -0,0 +1,83 @@
+// composables/useNetworkInfo.ts
+import { useNetwork } from '@vueuse/core'
+
+/**
+ * Network information composable
+ *
+ * Wraps VueUse's useNetwork with additional helper computed values
+ * for adaptive loading patterns.
+ *
+ * @returns Network state and connection information
+ */
+export function useNetworkInfo() {
+  const { isOnline, offlineAt, downlink, downlinkMax, effectiveType, saveData, type } = useNetwork()
+
+  /**
+   * Connection is slow (2G or slower)
+   */
+  const isSlow = computed(() => {
+    return (
+      effectiveType.value === 'slow-2g' ||
+      effectiveType.value === '2g' ||
+      (downlink.value !== undefined && downlink.value < 1.5)
+    )
+  })
+
+  /**
+   * Connection is fast (4G or better)
+   */
+  const isFast = computed(() => {
+    return effectiveType.value === '4g' || (downlink.value !== undefined && downlink.value > 5)
+  })
+
+  /**
+   * Connection type is cellular (mobile data)
+   */
+  const isCellular = computed(() => {
+    return type.value === 'cellular'
+  })
+
+  /**
+   * Connection type is WiFi
+   */
+  const isWiFi = computed(() => {
+    return type.value === 'wifi'
+  })
+
+  /**
+   * Should limit bandwidth usage
+   * (slow connection, data saver mode, or cellular)
+   */
+  const shouldLimitBandwidth = computed(() => {
+    return isSlow.value || saveData.value || isCellular.value
+  })
+
+  /**
+   * Connection quality description
+   */
+  const connectionQuality = computed<'excellent' | 'good' | 'poor' | 'offline'>(() => {
+    if (!isOnline.value) return 'offline'
+    if (isFast.value) return 'excellent'
+    if (isSlow.value) return 'poor'
+    return 'good'
+  })
+
+  return {
+    // Raw network state (from VueUse)
+    isOnline,
+    offlineAt,
+    downlink,
+    downlinkMax,
+    effectiveType,
+    saveData,
+    type,
+
+    // Computed helpers
+    isSlow,
+    isFast,
+    isCellular,
+    isWiFi,
+    shouldLimitBandwidth,
+    connectionQuality,
+  }
+}

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

@@ -0,0 +1,104 @@
+/**
+ * PWA composable for managing Progressive Web App functionality
+ *
+ * Features:
+ * - Install prompt handling
+ * - Installation state detection
+ *
+ * Note: Full PWA features (service worker) are only available in production.
+ * In development, this composable provides install prompt handling only.
+ *
+ * @example
+ * ```typescript
+ * const {
+ *   isInstalled,        // Is PWA installed?
+ *   canInstall,         // Can show install prompt?
+ *   install,            // Trigger install prompt
+ * } = usePWAInfo()
+ * ```
+ */
+export function usePWAInfo() {
+  // Install prompt event
+  const deferredPrompt = ref<BeforeInstallPromptEvent | null>(null)
+
+  // Track if PWA is installed
+  const isInstalled = ref(false)
+
+  // Service worker state - only meaningful in production with PWA module
+  const needRefresh = ref(false)
+
+  // Can show install prompt
+  const canInstall = computed(() => {
+    return !isInstalled.value && deferredPrompt.value !== null
+  })
+
+  // Update service worker - no-op, handled by PWA module in production
+  const updateServiceWorker = async () => {
+    // Service worker updates are handled automatically by @vite-pwa/nuxt in production
+    // This is a no-op placeholder for API consistency
+  }
+
+  // Initialize PWA detection (client-side only)
+  onMounted(() => {
+    if (!import.meta.client) return
+
+    // Listen for beforeinstallprompt event
+    window.addEventListener('beforeinstallprompt', (e) => {
+      e.preventDefault()
+      deferredPrompt.value = e as BeforeInstallPromptEvent
+    })
+
+    // Listen for app installed event
+    window.addEventListener('appinstalled', () => {
+      isInstalled.value = true
+      deferredPrompt.value = null
+    })
+
+    // Check if already installed (standalone mode)
+    if (window.matchMedia('(display-mode: standalone)').matches) {
+      isInstalled.value = true
+    }
+
+    // Check for iOS standalone mode
+    if ((window.navigator as Navigator & { standalone?: boolean }).standalone) {
+      isInstalled.value = true
+    }
+  })
+
+  /**
+   * Trigger the install prompt
+   */
+  const install = async () => {
+    if (!deferredPrompt.value) {
+      return false
+    }
+
+    deferredPrompt.value.prompt()
+    const { outcome } = await deferredPrompt.value.userChoice
+    deferredPrompt.value = null
+
+    return outcome === 'accepted'
+  }
+
+  return {
+    // Installation state
+    isInstalled: readonly(isInstalled),
+    canInstall: readonly(canInstall),
+    install,
+
+    // Service worker updates (production only via PWA module)
+    needRefresh: readonly(needRefresh),
+    updateServiceWorker,
+  }
+}
+
+/**
+ * Type definition for beforeinstallprompt event
+ */
+interface BeforeInstallPromptEvent extends Event {
+  prompt(): Promise<void>
+  userChoice: Promise<{
+    outcome: 'accepted' | 'dismissed'
+    platform: string
+  }>
+}

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

@@ -0,0 +1,97 @@
+// composables/useRendering.ts
+
+type RenderMode = 'ssr' | 'ssg' | 'csr' | 'hybrid'
+
+/**
+ * Rendering mode detection composable
+ *
+ * Detects the current rendering mode and provides helpers
+ * for server/client-specific logic and hydration state.
+ *
+ * Note: This DETECTS the mode, it does NOT choose it.
+ * The mode is chosen by Nuxt via routeRules in nuxt.config.ts.
+ *
+ * @returns Rendering state and mode information
+ *
+ * @example
+ * ```typescript
+ * const { mode, isClient, isHydrated } = useRendering()
+ *
+ * // Wait for hydration before interactive elements
+ * <button :disabled="!isHydrated">Click me</button>
+ * ```
+ */
+export function useRendering() {
+  const nuxtApp = useNuxtApp()
+
+  /**
+   * Is code running on the server (Node.js)?
+   */
+  const isServer = computed(() => import.meta.server)
+
+  /**
+   * Is code running in the browser?
+   */
+  const isClient = computed(() => import.meta.client)
+
+  /**
+   * Is Vue currently taking control of the server-rendered HTML?
+   */
+  const isHydrating = computed(() => nuxtApp.isHydrating)
+
+  /**
+   * Has hydration completed? Is the page fully interactive?
+   */
+  const isHydrated = computed(() => {
+    // On server, never hydrated
+    if (import.meta.server) return false
+
+    // On client, check if hydration is complete
+    return !nuxtApp.isHydrating
+  })
+
+  /**
+   * Detect the current rendering mode
+   *
+   * - SSR: Server-Side Rendering (HTML generated per request)
+   * - SSG: Static Site Generation (HTML pre-built at build time)
+   * - CSR: Client-Side Rendering (SPA, no server HTML)
+   * - Hybrid: Mix of above per route
+   */
+  const mode = computed<RenderMode>(() => {
+    // Check if we have SSR/SSG by looking at payload
+    const payload = nuxtApp.payload
+
+    // If running on server, it's SSR or SSG
+    if (import.meta.server) {
+      // Check if prerendering (SSG)
+      if (nuxtApp.ssrContext?.event?.context?.prerender) {
+        return 'ssg'
+      }
+      return 'ssr'
+    }
+
+    // On client, check if we have server-rendered content
+    if (payload.serverRendered) {
+      // Could be SSR or SSG - check if we have build-time data
+      // SSG typically has static payload, SSR has fresh data
+      return payload.prerendered ? 'ssg' : 'ssr'
+    }
+
+    // No server rendering = CSR
+    return 'csr'
+  })
+
+  return {
+    // Mode detection
+    mode,
+
+    // Environment flags
+    isServer,
+    isClient,
+
+    // Hydration state
+    isHydrating,
+    isHydrated,
+  }
+}

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

@@ -0,0 +1,95 @@
+// composables/useScreen.ts
+import { breakpointsTailwind, useBreakpoints, useScreenOrientation } from '@vueuse/core'
+
+/**
+ * Screen size and orientation composable
+ *
+ * Wraps VueUse's useBreakpoints (Tailwind) and useScreenOrientation
+ * with additional helper computed values.
+ *
+ * Tailwind breakpoints:
+ * - sm: 640px
+ * - md: 768px
+ * - lg: 1024px
+ * - xl: 1280px
+ * - 2xl: 1536px
+ *
+ * @returns Screen state and breakpoint information
+ */
+export function useScreen() {
+  const breakpoints = useBreakpoints(breakpointsTailwind)
+  const { orientation, angle, isSupported } = useScreenOrientation()
+
+  // Breakpoint helpers
+  const isMobile = breakpoints.smaller('md') // < 768px
+  const isTablet = breakpoints.between('md', 'lg') // 768px - 1023px
+  const isDesktop = breakpoints.greaterOrEqual('lg') // >= 1024px
+  const isLargeDesktop = breakpoints.greaterOrEqual('xl') // >= 1280px
+  const isExtraLargeDesktop = breakpoints.greaterOrEqual('2xl') // >= 1536px
+
+  // Current breakpoint name
+  const breakpoint = computed<'mobile' | 'tablet' | 'desktop' | 'xl' | '2xl'>(() => {
+    if (isExtraLargeDesktop.value) return '2xl'
+    if (isLargeDesktop.value) return 'xl'
+    if (isDesktop.value) return 'desktop'
+    if (isTablet.value) return 'tablet'
+    return 'mobile'
+  })
+
+  // Orientation helpers
+  const isPortrait = computed(() => orientation.value === 'portrait-primary')
+  const isLandscape = computed(() => orientation.value === 'landscape-primary')
+
+  // Device pixel ratio (retina detection)
+  const pixelRatio = computed(() => {
+    if (import.meta.client) {
+      return window.devicePixelRatio || 1
+    }
+    return 1
+  })
+
+  const isRetina = computed(() => pixelRatio.value >= 2)
+
+  // Screen dimensions (client-only)
+  const width = computed(() => {
+    if (import.meta.client) {
+      return window.innerWidth
+    }
+    return 0
+  })
+
+  const height = computed(() => {
+    if (import.meta.client) {
+      return window.innerHeight
+    }
+    return 0
+  })
+
+  return {
+    // Breakpoint state
+    breakpoint,
+    isMobile,
+    isTablet,
+    isDesktop,
+    isLargeDesktop,
+    isExtraLargeDesktop,
+
+    // Orientation state
+    orientation,
+    angle,
+    isPortrait,
+    isLandscape,
+    isOrientationSupported: isSupported,
+
+    // Display quality
+    pixelRatio,
+    isRetina,
+
+    // Dimensions
+    width,
+    height,
+
+    // Raw breakpoints instance (for advanced usage)
+    breakpoints,
+  }
+}