feat: replace useSettings with useUserPreferences

- extract sidebar collapsed state into separate `usePackageSidebarPreferences` composable
- add `preferences-sync.client.ts` plugin for early color mode + server sync init
- wrap theme select in `<ClientOnly>` to prevent SSR hydration mismatch
- show sync status indicator on settings page for authenticated users
- add `useColorModePreference` composable to sync color mode with `@nuxtjs/color-mode`

with '#' will be ignored, and an empty message aborts the commit. # #
On branch feat-484-persist-user-preferences # Changes to be committed:
app/components/Settings/AccentColorPicker.vue # modified:
app/components/Settings/BgThemePicker.vue # modified:
app/composables/useInstallCommand.ts # new file:
app/composables/usePackageSidebarPreferences.ts # deleted:
app/composables/useSettings.ts # new file:
app/composables/useUserPreferences.ts # new file:
app/composables/useUserPreferencesProvider.ts # modified:
app/pages/search.vue # modified:  app/pages/settings.vue # modified:
app/plugins/i18n-loader.client.ts # new file:
app/plugins/preferences-sync.client.ts # modified:
app/utils/prehydrate.ts # modified:  i18n/locales/en.json # modified:
lunaria/files/en-US.json # modified:
shared/schemas/userPreferences.ts # modified:
test/nuxt/components/DateTime.spec.ts # modified:
test/nuxt/components/compare/FacetRow.spec.ts # modified:
test/nuxt/composables/use-install-command.spec.ts # # Untracked files:

Author: gusa4grr

app/components/CollapsibleSection.vue

@@ -14,7 +14,7 @@ const props = withDefaults(defineProps<Props>(), {
   headingLevel: 'h2',
 })
 
-const appSettings = useSettings()
+const { sidebarPreferences } = usePackageSidebarPreferences()
 
 const buttonId = `${props.id}-collapsible-button`
 const contentId = `${props.id}-collapsible-content`
@@ -23,8 +23,8 @@ const headingId = `${props.id}-heading`
 const isOpen = shallowRef(true)
 
 onPrehydrate(() => {
-  const settings = JSON.parse(localStorage.getItem('npmx-settings') || '{}')
-  const collapsed: string[] = settings?.sidebar?.collapsed || []
+  const sidebar = JSON.parse(localStorage.getItem('npmx-sidebar-preferences') || '{}')
+  const collapsed: string[] = sidebar?.collapsed || []
   for (const id of collapsed) {
     if (!document.documentElement.dataset.collapsed?.includes(id)) {
       document.documentElement.dataset.collapsed = (
@@ -45,17 +45,16 @@ onMounted(() => {
 function toggle() {
   isOpen.value = !isOpen.value
 
-  const removed = appSettings.settings.value.sidebar.collapsed.filter(c => c !== props.id)
+  const removed = sidebarPreferences.value.collapsed.filter(c => c !== props.id)
 
   if (isOpen.value) {
-    appSettings.settings.value.sidebar.collapsed = removed
+    sidebarPreferences.value.collapsed = removed
   } else {
     removed.push(props.id)
-    appSettings.settings.value.sidebar.collapsed = removed
+    sidebarPreferences.value.collapsed = removed
   }
 
-  document.documentElement.dataset.collapsed =
-    appSettings.settings.value.sidebar.collapsed.join(' ')
+  document.documentElement.dataset.collapsed = sidebarPreferences.value.collapsed.join(' ')
 }
 
 const ariaLabel = computed(() => {

app/components/Settings/AccentColorPicker.vue

@@ -1,11 +1,11 @@
 <script setup lang="ts">
-import { useAccentColor } from '~/composables/useSettings'
+import { useAccentColor } from '~/composables/useUserPreferences'
 
 const { accentColors, selectedAccentColor, setAccentColor } = useAccentColor()
 
 onPrehydrate(el => {
-  const settings = JSON.parse(localStorage.getItem('npmx-settings') || '{}')
-  const id = settings.accentColorId
+  const preferences = JSON.parse(localStorage.getItem('npmx-user-preferences') || '{}')
+  const id = preferences.accentColorId
   if (id) {
     const input = el.querySelector<HTMLInputElement>(`input[value="${id}"]`)
     if (input) {

app/components/Settings/BgThemePicker.vue

@@ -2,8 +2,8 @@
 const { backgroundThemes, selectedBackgroundTheme, setBackgroundTheme } = useBackgroundTheme()
 
 onPrehydrate(el => {
-  const settings = JSON.parse(localStorage.getItem('npmx-settings') || '{}')
-  const id = settings.preferredBackgroundTheme
+  const preferences = JSON.parse(localStorage.getItem('npmx-user-preferences') || '{}')
+  const id = preferences.preferredBackgroundTheme
   if (id) {
     const input = el.querySelector<HTMLInputElement>(`input[value="${id}"]`)
     if (input) {

app/composables/useInstallCommand.ts

@@ -11,11 +11,11 @@ export function useInstallCommand(
   typesPackageName: MaybeRefOrGetter<string | null>,
 ) {
   const selectedPM = useSelectedPackageManager()
-  const { settings } = useSettings()
+  const { preferences } = useUserPreferences()
 
   // Check if we should show @types in install command
   const showTypesInInstall = computed(() => {
-    return settings.value.includeTypesInInstall && !!toValue(typesPackageName)
+    return preferences.value.includeTypesInInstall && !!toValue(typesPackageName)
   })
 
   const installCommandParts = computed(() => {

app/composables/usePackageSidebarPreferences.ts

@@ -0,0 +1,24 @@
+interface SidebarPreferences {
+  collapsed: string[]
+}
+
+const STORAGE_KEY = 'npmx-sidebar-preferences'
+const DEFAULT_SIDEBAR_PREFERENCES: SidebarPreferences = { collapsed: [] }
+
+let sidebarRef: Ref<SidebarPreferences> | null = null
+
+/**
+ * Composable for managing sidebar section collapsed state.
+ * This is local-only and uses its own LS key.
+ */
+export function usePackageSidebarPreferences() {
+  if (!sidebarRef) {
+    sidebarRef = useLocalStorage<SidebarPreferences>(STORAGE_KEY, DEFAULT_SIDEBAR_PREFERENCES, {
+      mergeDefaults: true,
+    })
+  }
+
+  return {
+    sidebarPreferences: sidebarRef,
+  }
+}

app/composables/useSettings.ts

@@ -0,0 +1,133 @@
+import { ACCENT_COLORS, BACKGROUND_THEMES } from '#shared/utils/constants'
+import {
+  DEFAULT_USER_PREFERENCES,
+  type AccentColorId,
+  type BackgroundThemeId,
+  type ColorModePreference,
+  type UserPreferences,
+} from '#shared/schemas/userPreferences'
+
+/**
+ * Main composable for user preferences.
+ * Uses `npmx-user-preferences` localStorage key and syncs to the server
+ * for authenticated users via `useUserPreferencesProvider`.
+ */
+export function useUserPreferences() {
+  const provider = useUserPreferencesProvider<UserPreferences>(DEFAULT_USER_PREFERENCES)
+
+  return {
+    preferences: provider.data,
+    isAuthenticated: provider.isAuthenticated,
+    isSyncing: provider.isSyncing,
+    isSynced: provider.isSynced,
+    hasError: provider.hasError,
+    syncError: provider.syncError,
+    lastSyncedAt: provider.lastSyncedAt,
+    initSync: provider.initSync,
+  }
+}
+
+export function useRelativeDates() {
+  const { preferences } = useUserPreferences()
+  return computed(() => preferences.value.relativeDates)
+}
+
+export function useAccentColor() {
+  const { preferences } = useUserPreferences()
+  const colorMode = useColorMode()
+
+  const accentColors = computed(() => {
+    const isDark = colorMode.value === 'dark'
+    const colors = isDark ? ACCENT_COLORS.dark : ACCENT_COLORS.light
+
+    return Object.entries(colors).map(([id, value]) => ({
+      id: id as AccentColorId,
+      name: id,
+      value,
+    }))
+  })
+
+  function setAccentColor(id: AccentColorId | null) {
+    if (id) {
+      document.documentElement.style.setProperty('--accent-color', `var(--swatch-${id})`)
+    } else {
+      document.documentElement.style.removeProperty('--accent-color')
+    }
+    preferences.value.accentColorId = id
+  }
+
+  return {
+    accentColors,
+    selectedAccentColor: computed(() => preferences.value.accentColorId),
+    setAccentColor,
+  }
+}
+
+export function useBackgroundTheme() {
+  const backgroundThemes = Object.entries(BACKGROUND_THEMES).map(([id, value]) => ({
+    id: id as BackgroundThemeId,
+    name: id,
+    value,
+  }))
+
+  const { preferences } = useUserPreferences()
+
+  function setBackgroundTheme(id: BackgroundThemeId | null) {
+    if (id) {
+      document.documentElement.dataset.bgTheme = id
+    } else {
+      document.documentElement.removeAttribute('data-bg-theme')
+    }
+    preferences.value.preferredBackgroundTheme = id
+  }
+
+  return {
+    backgroundThemes,
+    selectedBackgroundTheme: computed(() => preferences.value.preferredBackgroundTheme),
+    setBackgroundTheme,
+  }
+}
+
+/**
+ * Composable for syncing color mode preference.
+ * Keeps the user preference in sync with @nuxtjs/color-mode's own LS key (`npmx-color-mode`)
+ * so that the color-mode module picks up the correct value on page load.
+ */
+export function useColorModePreference() {
+  const { preferences } = useUserPreferences()
+  const colorMode = useColorMode()
+
+  /**
+   * Set color mode preference and sync to both user preferences and the
+   * `npmx-color-mode` LS key used by @nuxtjs/color-mode.
+   */
+  function setColorMode(mode: ColorModePreference) {
+    preferences.value.colorModePreference = mode
+    colorMode.preference = mode
+  }
+
+  /**
+   * On init, if the user has a stored preference, apply it to @nuxtjs/color-mode.
+   * This handles the case where preferences were synced from the server.
+   */
+  function applyStoredColorMode() {
+    const stored = preferences.value.colorModePreference
+    if (stored) {
+      colorMode.preference = stored
+    } else {
+      // No user preference stored yet — seed it from the current color-mode LS value
+      const currentPreference = colorMode.preference as ColorModePreference
+      if (currentPreference && currentPreference !== 'system') {
+        preferences.value.colorModePreference = currentPreference
+      }
+    }
+  }
+
+  return {
+    colorModePreference: computed(
+      () => preferences.value.colorModePreference ?? colorMode.preference,
+    ),
+    setColorMode,
+    applyStoredColorMode,
+  }
+}