fix(resources): honor explicit default list params

Author: j15z

.claude/rules/sim-url-state.md

@@ -53,8 +53,9 @@ Files, Tables, and Knowledge may persist their last-used filter/sort snapshot th
 
 - nuqs remains authoritative while the module is open.
 - Zustand is consulted once on a clean module entry, after persisted state hydrates.
-- Effective URL filter/sort state wins as one complete snapshot and becomes the remembered value;
-  omitted fields use URL defaults rather than merging with storage.
+- An explicit URL filter/sort parameter wins even when it resolves to the module default. The
+  complete resolved URL snapshot becomes the remembered value; omitted fields use URL defaults
+  rather than merging with storage.
 - Explicit filter/sort gestures commit the same complete snapshot to nuqs and Zustand together.
 - Never mirror subsequent URL changes with a synchronization effect or `popstate` listener.
 - Search and folder navigation remain URL-only and are excluded from the persisted snapshot.

apps/sim/app/workspace/[workspaceId]/files/search-params.ts

@@ -83,10 +83,13 @@ export const filesSortParams = createSortParams(FILE_SORT_COLUMNS, {
   direction: 'desc',
 })
 
+const filesFilterUrlKeyMap = { uploadedBy: 'uploaded-by' } as const
+
 export const filesListPreferenceConfig = {
   module: 'files',
   sortColumns: FILE_SORT_COLUMNS,
   filterKeys: ['type', 'size', 'uploadedBy'],
+  preferenceUrlKeys: filesFilterUrlKeyMap,
   defaultPreference: {
     sort: filesSortParams.default,
     filters: { type: [], size: [], uploadedBy: [] },
@@ -98,5 +101,5 @@ export const filesFilterUrlKeys = {
   history: 'replace',
   shallow: true,
   clearOnDefault: true,
-  urlKeys: { uploadedBy: 'uploaded-by' },
+  urlKeys: filesFilterUrlKeyMap,
 } as const

apps/sim/hooks/use-resource-list-preferences.test.tsx

@@ -2,6 +2,7 @@
  * @vitest-environment jsdom
  */
 import { act } from 'react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { createRoot, type Root } from 'react-dom/client'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { filesListPreferenceConfig } from '@/app/workspace/[workspaceId]/files/search-params'
@@ -30,12 +31,13 @@ interface HookProps {
 
 const mountedRoots: Root[] = []
 
-function renderPreferenceHook(props: HookProps) {
+function renderPreferenceHook(props: HookProps, searchParams = '') {
   ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
   const root = createRoot(document.createElement('div'))
   mountedRoots.push(root)
   let result: ReturnType<typeof useResourceListPreferences>
   let currentProps = props
+  let currentSearchParams = searchParams
 
   function Probe() {
     result = useResourceListPreferences({
@@ -46,14 +48,21 @@ function renderPreferenceHook(props: HookProps) {
     return null
   }
 
-  act(() => root.render(<Probe />))
+  const renderProbe = () => (
+    <NuqsTestingAdapter hasMemory searchParams={currentSearchParams}>
+      <Probe />
+    </NuqsTestingAdapter>
+  )
+
+  act(() => root.render(renderProbe()))
   return {
     get current() {
       return result
     },
-    rerender(nextProps: HookProps) {
+    rerender(nextProps: HookProps, nextSearchParams = currentSearchParams) {
       currentProps = nextProps
-      act(() => root.render(<Probe />))
+      currentSearchParams = nextSearchParams
+      act(() => root.render(renderProbe()))
     },
   }
 }
@@ -112,6 +121,23 @@ describe('useResourceListPreferences', () => {
     expect(applyPreference).not.toHaveBeenCalled()
   })
 
+  it.each(['sort=updated&dir=desc', 'uploaded-by='])(
+    'honors explicitly default-valued URL state instead of restoring a saved preference (%s)',
+    async (searchParams) => {
+      seedPreference(filteredPreference)
+      const applyPreference = vi.fn()
+      const result = renderPreferenceHook(
+        { preference: defaultPreference, applyPreference },
+        searchParams
+      )
+
+      expect(result.current.isReady).toBe(true)
+      await flushEffects()
+      expect(applyPreference).not.toHaveBeenCalled()
+      expect(useResourceListPreferencesStore.getState().preferences).toEqual({})
+    }
+  )
+
   it('starts restoring a saved preference once on a clean visit', async () => {
     seedPreference(filteredPreference)
     const applyPreference = vi.fn()
@@ -140,6 +166,23 @@ describe('useResourceListPreferences', () => {
     expect(applyPreference).toHaveBeenCalledOnce()
   })
 
+  it('lets an explicit URL change cancel a pending saved-preference restoration', async () => {
+    seedPreference(filteredPreference)
+    const applyPreference = vi.fn()
+    const result = renderPreferenceHook({ preference: defaultPreference, applyPreference })
+
+    await flushEffects()
+    expect(result.current.isReady).toBe(false)
+    expect(applyPreference).toHaveBeenCalledWith(filteredPreference)
+
+    result.rerender({ preference: defaultPreference, applyPreference }, 'sort=updated&dir=desc')
+    await flushEffects()
+
+    expect(result.current.isReady).toBe(true)
+    expect(applyPreference).toHaveBeenCalledOnce()
+    expect(useResourceListPreferencesStore.getState().preferences).toEqual({})
+  })
+
   it('stays unready while a clean entry waits for hydration', () => {
     vi.spyOn(useResourceListPreferencesStore.persist, 'rehydrate').mockImplementation(
       () => new Promise(() => undefined)
@@ -308,4 +351,8 @@ describe('module list preference configs', () => {
       filters: Object.fromEntries(keys.map((key) => [key, []])),
     })
   })
+
+  it('reuses the Files filter URL alias when detecting explicit preferences', () => {
+    expect(filesListPreferenceConfig.preferenceUrlKeys).toEqual({ uploadedBy: 'uploaded-by' })
+  })
 })

apps/sim/hooks/use-resource-list-preferences.ts

@@ -1,6 +1,7 @@
 'use client'
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { parseAsString, useQueryStates } from 'nuqs'
 import type {
   ResourceListPreference,
   ResourceListPreferenceConfig,
@@ -86,6 +87,12 @@ export function useResourceListPreferences({
   )
   const setPreference = useResourceListPreferencesStore((state) => state.setPreference)
   const removePreference = useResourceListPreferencesStore((state) => state.removePreference)
+  const preferenceQueryParsers = Object.fromEntries(
+    ['sort', 'dir', ...config.filterKeys].map((queryKey) => [queryKey, parseAsString])
+  )
+  const [preferenceQuery] = useQueryStates(preferenceQueryParsers, {
+    urlKeys: config.preferenceUrlKeys,
+  })
 
   const defaultPreference = useMemo(
     () => normalizePreference(config.defaultPreference, config),
@@ -100,6 +107,8 @@ export function useResourceListPreferences({
       defaultPreference &&
       !resourceListPreferencesEqual(currentPreference, defaultPreference)
   )
+  const hasExplicitUrlPreference = Object.values(preferenceQuery).some((value) => value !== null)
+  const hasUrlPreference = hasExplicitUrlPreference || hasEffectiveUrlPreference
 
   const rememberPreference = useCallback(
     (normalizedPreference: ResourceListPreference) => {
@@ -129,6 +138,10 @@ export function useResourceListPreferences({
       ) {
         setPendingRestoration(null)
         setReadyKey(key)
+      } else if (currentPreference && hasExplicitUrlPreference) {
+        setPendingRestoration(null)
+        rememberPreference(currentPreference)
+        setReadyKey(key)
       }
       return
     }
@@ -142,7 +155,7 @@ export function useResourceListPreferences({
       return
     }
 
-    if (!resourceListPreferencesEqual(currentPreference, defaultPreference)) {
+    if (hasUrlPreference) {
       rememberPreference(currentPreference)
       setReadyKey(key)
       return
@@ -163,7 +176,9 @@ export function useResourceListPreferences({
     currentPreference,
     defaultPreference,
     enabled,
+    hasExplicitUrlPreference,
     hasHydrated,
+    hasUrlPreference,
     key,
     pendingRestoration,
     rememberPreference,
@@ -215,10 +230,7 @@ export function useResourceListPreferences({
   }, [commitPreference, currentPreference, defaultPreference])
 
   return {
-    isReady:
-      !enabled ||
-      (pendingRestoration?.key !== key && hasEffectiveUrlPreference) ||
-      readyKey === key,
+    isReady: !enabled || (pendingRestoration?.key !== key && hasUrlPreference) || readyKey === key,
     commitPreference,
     setFilter,
     clearFilters,

apps/sim/stores/resource-list-preferences/types.ts

@@ -21,6 +21,7 @@ export interface ResourceListPreferenceConfig {
   module: ResourceListModule
   sortColumns: readonly string[]
   filterKeys: readonly string[]
+  preferenceUrlKeys?: Readonly<Record<string, string>>
   defaultPreference: ResourceListPreference
 }