feat: add server-synced user preferences infrastructure (#484)

- introduce the foundational layer for persisting user preferences
to the server
- add UserPreferencesSchema and shared types for user preferences
- add client-only sync composable with debounced saves, route guard flush, and sendBeacon fallback
- integrate server sync into useSettings and migrate to shared UserPreferences type
- extract generic localStorage helpers, migrate consumers, remove usePreferencesProvider

Author: gusa4grr

app/composables/useLocalStorageHashProvider.ts

@@ -0,0 +1,34 @@
+import { createLocalStorageProvider } from '~/utils/storage'
+
+export function useLocalStorageHashProvider<T extends object>(key: string, defaultValue: T) {
+  const provider = createLocalStorageProvider<T>(key)
+  const data = ref<T>(defaultValue)
+
+  onMounted(() => {
+    const stored = provider.get()
+    if (stored) {
+      data.value = { ...defaultValue, ...stored }
+    }
+  })
+
+  function save() {
+    provider.set(data.value)
+  }
+
+  function reset() {
+    data.value = { ...defaultValue }
+    provider.remove()
+  }
+
+  function update<K extends keyof T>(key: K, value: T[K]) {
+    data.value[key] = value
+    save()
+  }
+
+  return {
+    data,
+    save,
+    reset,
+    update,
+  }
+}

app/composables/usePackageListPreferences.ts

@@ -11,18 +11,18 @@ import type {
 } from '#shared/types/preferences'
 import { DEFAULT_COLUMNS, DEFAULT_PREFERENCES } from '#shared/types/preferences'
 
+const STORAGE_KEY = 'npmx-list-prefs'
+
 /**
  * Composable for managing package list display preferences
  * Persists to localStorage and provides reactive state
- *
  */
 export function usePackageListPreferences() {
   const {
     data: preferences,
-    isHydrated,
     save,
     reset,
-  } = usePreferencesProvider<PackageListPreferences>(DEFAULT_PREFERENCES)
+  } = useLocalStorageHashProvider<PackageListPreferences>(STORAGE_KEY, DEFAULT_PREFERENCES)
 
   // Computed accessors for common properties
   const viewMode = computed({
@@ -90,7 +90,6 @@ export function usePackageListPreferences() {
   return {
     // Raw preferences
     preferences,
-    isHydrated,
 
     // Individual properties with setters
     viewMode,

app/composables/usePreferencesProvider.ts

@@ -1,58 +1,23 @@
 import type { RemovableRef } from '@vueuse/core'
 import { useLocalStorage } from '@vueuse/core'
 import { ACCENT_COLORS } from '#shared/utils/constants'
-import type { LocaleObject } from '@nuxtjs/i18n'
 import { BACKGROUND_THEMES } from '#shared/utils/constants'
-
-type BackgroundThemeId = keyof typeof BACKGROUND_THEMES
-
-type AccentColorId = keyof typeof ACCENT_COLORS.light
-
-/**
- * Application settings stored in localStorage
- */
-export interface AppSettings {
-  /** Display dates as relative (e.g., "3 days ago") instead of absolute */
-  relativeDates: boolean
-  /** Include @types/* package in install command for packages without built-in types */
-  includeTypesInInstall: boolean
-  /** Accent color theme */
-  accentColorId: AccentColorId | null
-  /** Preferred background shade */
-  preferredBackgroundTheme: BackgroundThemeId | null
-  /** Hide platform-specific packages (e.g., @scope/pkg-linux-x64) from search results */
-  hidePlatformPackages: boolean
-  /** User-selected locale */
-  selectedLocale: LocaleObject['code'] | null
-  sidebar: {
-    collapsed: string[]
-  }
-}
-
-const DEFAULT_SETTINGS: AppSettings = {
-  relativeDates: false,
-  includeTypesInInstall: true,
-  accentColorId: null,
-  hidePlatformPackages: true,
-  selectedLocale: null,
-  preferredBackgroundTheme: null,
-  sidebar: {
-    collapsed: [],
-  },
-}
+import {
+  DEFAULT_USER_PREFERENCES,
+  type AccentColorId,
+  type BackgroundThemeId,
+  type UserPreferences,
+} from '#shared/schemas/userPreferences'
 
 const STORAGE_KEY = 'npmx-settings'
 
-// Shared settings instance (singleton per app)
-let settingsRef: RemovableRef<AppSettings> | null = null
+let settingsRef: RemovableRef<UserPreferences> | null = null
+let syncInitialized = false
 
-/**
- * Composable for managing application settings with localStorage persistence.
- * Settings are shared across all components that use this composable.
- */
+// TODO: After discussion with the team, this will be replaced with a proper persistent solution (LS + server sync)
 export function useSettings() {
   if (!settingsRef) {
-    settingsRef = useLocalStorage<AppSettings>(STORAGE_KEY, DEFAULT_SETTINGS, {
+    settingsRef = useLocalStorage<UserPreferences>(STORAGE_KEY, DEFAULT_USER_PREFERENCES, {
       mergeDefaults: true,
     })
   }
@@ -62,18 +27,72 @@ export function useSettings() {
   }
 }
 
-/**
- * Composable for accessing just the relative dates setting.
- * Useful for components that only need to read this specific setting.
- */
+// TODO: Name to be changed
+export function useSettingsSync() {
+  const { settings } = useSettings()
+  const {
+    isAuthenticated,
+    status,
+    lastSyncedAt,
+    error,
+    loadFromServer,
+    scheduleSync,
+    setupRouteGuard,
+    setupBeforeUnload,
+  } = useUserPreferencesSync()
+
+  const isSyncing = computed(() => status.value === 'syncing')
+  const isSynced = computed(() => status.value === 'synced')
+  const hasError = computed(() => status.value === 'error')
+
+  async function initializeSync(): Promise<void> {
+    if (syncInitialized || import.meta.server) return
+
+    setupRouteGuard(() => settings.value)
+    setupBeforeUnload(() => settings.value)
+
+    if (isAuthenticated.value) {
+      const serverPrefs = await loadFromServer()
+      Object.assign(settings.value, serverPrefs)
+    }
+
+    watch(
+      settings,
+      newSettings => {
+        if (isAuthenticated.value) {
+          scheduleSync(newSettings)
+        }
+      },
+      { deep: true },
+    )
+
+    watch(isAuthenticated, async newIsAuth => {
+      if (newIsAuth) {
+        const serverPrefs = await loadFromServer()
+        Object.assign(settings.value, serverPrefs)
+      }
+    })
+
+    syncInitialized = true
+  }
+
+  return {
+    settings,
+    isAuthenticated,
+    isSyncing,
+    isSynced,
+    hasError,
+    syncError: error,
+    lastSyncedAt,
+    initializeSync,
+  }
+}
+
 export function useRelativeDates() {
   const { settings } = useSettings()
   return computed(() => settings.value.relativeDates)
 }
 
-/**
- * Composable for managing accent color.
- */
 export function useAccentColor() {
   const { settings } = useSettings()
   const colorMode = useColorMode()