feat(nuqs): migrate table-detail sort, KB document filters, and calendar view to URL state

- Table detail: sort+dir to nuqs; Filter stays in useState (recursive/nested, too large for URL)
- Knowledge base: search (debounced), enabled filter, sort+dir to nuqs; tagFilterEntries stays in useState (rich rule objects)
- Scheduled-tasks calendar: scope + date-only anchor (parseAsIsoDate, nullable, derive-today) to nuqs
- Add Suspense boundaries to table-detail and scheduled-tasks pages
- Document parseAsIsoDate / nullable-dynamic-default pattern in sim-url-state.md

Author: waleedlatif1

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

@@ -164,6 +164,10 @@ export const thingsParsers = {
 
 Both carry the shared filter options (`{ history: 'replace', clearOnDefault: true }`). The defaults must match the list's existing default sort exactly. If a UI exposes "no active sort" as `null`, derive that in the component (`sort === DEFAULT && dir === DEFAULT ? null : { column, direction }`) — the URL still holds the resolved values. "Clear sort" writes the defaults back (which `clearOnDefault` strips from the URL); never write `null`/garbage columns.
 
+## Dates in the URL (`parseAsIsoDate`)
+
+A date-only param (a calendar anchor, a date filter) uses the built-in `parseAsIsoDate` (`yyyy-MM-dd`) — never serialize a full `Date`/timestamp when only the day matters. When the default is **dynamic** (e.g. "today"), make the param **nullable** (omit `.withDefault`) and derive the fallback in the hook (`const anchor = param ?? today`), so a clean URL means the dynamic default and navigating back to it writes `null` (clears the param). See `scheduled-tasks/search-params.ts` + `hooks/use-calendar.ts`.
+
 ## Selected-entity deep-link (store the id, derive the object)
 
 To deep-link a row/modal/drawer to one entity, store **only its id** and look the object up in the already-loaded list — never serialize the object into the URL:

apps/sim/app/workspace/[workspaceId]/knowledge/[id]/base.tsx

@@ -7,7 +7,7 @@ import { generateId } from '@sim/utils/id'
 import { format } from 'date-fns'
 import { AlertCircle, Pencil, Plus, Tag, X } from 'lucide-react'
 import { useParams, useRouter } from 'next/navigation'
-import { useQueryState } from 'nuqs'
+import { debounce, useQueryState, useQueryStates } from 'nuqs'
 import { usePostHog } from 'posthog-js/react'
 import {
   Badge,
@@ -60,6 +60,11 @@ import {
 } from '@/app/workspace/[workspaceId]/knowledge/[id]/components'
 import {
   addConnectorParam,
+  DEFAULT_KB_SORT_COLUMN,
+  DEFAULT_KB_SORT_DIRECTION,
+  documentFiltersParsers,
+  documentFiltersUrlKeys,
+  type KbSortColumn,
   pageParam,
   pageUrlKeys,
 } from '@/app/workspace/[workspaceId]/knowledge/[id]/search-params'
@@ -85,6 +90,7 @@ import {
   useUpdateDocument,
   useUpdateKnowledgeBase,
 } from '@/hooks/queries/kb/knowledge'
+import { useDebounce } from '@/hooks/use-debounce'
 import { useInlineRename } from '@/hooks/use-inline-rename'
 import { useOAuthReturnForKBConnectors } from '@/hooks/use-oauth-return'
 
@@ -242,9 +248,7 @@ export function KnowledgeBase({
   })
   const { mutate: bulkDocumentMutation, isPending: isBulkOperating } = useBulkDocumentOperation()
 
-  const [searchQuery, setSearchQuery] = useState('')
   const [showTagsModal, setShowTagsModal] = useState(false)
-  const [enabledFilter, setEnabledFilter] = useState<'all' | 'enabled' | 'disabled'>('all')
   const [tagFilterEntries, setTagFilterEntries] = useState<
     {
       id: string
@@ -271,11 +275,6 @@ export function KnowledgeBase({
     [tagFilterEntries]
   )
 
-  const handleSearchChange = useCallback((newQuery: string) => {
-    setSearchQuery(newQuery)
-    setCurrentPage(1)
-  }, [])
-
   const [selectedDocuments, setSelectedDocuments] = useState<Set<string>>(() => new Set())
   const [isSelectAllMode, setIsSelectAllMode] = useState(false)
   const [showDeleteDialog, setShowDeleteDialog] = useState(false)
@@ -288,10 +287,48 @@ export function KnowledgeBase({
     ...pageParam.parser,
     ...pageUrlKeys,
   })
-  const [activeSort, setActiveSort] = useState<{
-    column: string
-    direction: 'asc' | 'desc'
-  } | null>(null)
+
+  const [
+    { q: searchQuery, enabled: enabledFilter, sort: sortColumn, dir: sortDirection },
+    setDocumentFilters,
+  ] = useQueryStates(documentFiltersParsers, documentFiltersUrlKeys)
+
+  // The input is controlled directly by the instant nuqs value; only the URL
+  // write is debounced. The document query below reads a debounced value so it
+  // doesn't refetch on every keystroke. Changing the search resets pagination.
+  const handleSearchChange = useCallback(
+    (newQuery: string) => {
+      const next = newQuery.length > 0 ? newQuery : null
+      setDocumentFilters(
+        { q: next },
+        next === null ? undefined : { limitUrlUpdates: debounce(300) }
+      )
+      setCurrentPage(1)
+    },
+    [setDocumentFilters, setCurrentPage]
+  )
+  const debouncedSearchQuery = useDebounce(searchQuery, 300)
+
+  /**
+   * The resolved sort is exposed to the sort menu only when it differs from the
+   * default, mirroring the prior `null`-means-default semantics.
+   */
+  const activeSort = useMemo(
+    () =>
+      sortColumn === DEFAULT_KB_SORT_COLUMN && sortDirection === DEFAULT_KB_SORT_DIRECTION
+        ? null
+        : { column: sortColumn, direction: sortDirection },
+    [sortColumn, sortDirection]
+  )
+
+  const setEnabledFilter = useCallback(
+    (value: 'all' | 'enabled' | 'disabled') => {
+      setDocumentFilters({ enabled: value })
+      setCurrentPage(1)
+    },
+    [setDocumentFilters, setCurrentPage]
+  )
+
   const [contextMenuDocument, setContextMenuDocument] = useState<DocumentData | null>(null)
   const [showRenameModal, setShowRenameModal] = useState(false)
   const [documentToRename, setDocumentToRename] = useState<DocumentData | null>(null)
@@ -335,11 +372,11 @@ export function KnowledgeBase({
     updateDocument,
     refreshDocuments,
   } = useKnowledgeBaseDocuments(id, {
-    search: searchQuery || undefined,
+    search: debouncedSearchQuery || undefined,
     limit: DOCUMENTS_PER_PAGE,
     offset: (currentPage - 1) * DOCUMENTS_PER_PAGE,
-    sortBy: (activeSort?.column ?? 'uploadedAt') as DocumentSortField,
-    sortOrder: (activeSort?.direction ?? 'desc') as SortOrder,
+    sortBy: sortColumn as DocumentSortField,
+    sortOrder: sortDirection as SortOrder,
     refetchInterval: (data) => {
       if (isDeleting) return false
       const hasPending = data?.documents?.some(
@@ -857,15 +894,17 @@ export function KnowledgeBase({
       ],
       active: activeSort,
       onSort: (column, direction) => {
-        setActiveSort({ column, direction })
+        setDocumentFilters({ sort: column as KbSortColumn, dir: direction })
         setCurrentPage(1)
       },
+      // Clearing writes the defaults back (stripped by clearOnDefault), so the
+      // sort menu reads "no active sort" again and the URL stays clean.
       onClear: () => {
-        setActiveSort(null)
+        setDocumentFilters({ sort: DEFAULT_KB_SORT_COLUMN, dir: DEFAULT_KB_SORT_DIRECTION })
         setCurrentPage(1)
       },
     }),
-    [activeSort]
+    [activeSort, setDocumentFilters, setCurrentPage]
   )
 
   const filterContent = useMemo(
@@ -879,7 +918,6 @@ export function KnowledgeBase({
                 variant='ghost'
                 onClick={() => {
                   setEnabledFilter('all')
-                  setCurrentPage(1)
                   setSelectedDocuments(new Set())
                   setIsSelectAllMode(false)
                 }}
@@ -895,7 +933,6 @@ export function KnowledgeBase({
             onChange={(value) => {
               if (value !== 'all' && value !== 'enabled' && value !== 'disabled') return
               setEnabledFilter(value)
-              setCurrentPage(1)
               setSelectedDocuments(new Set())
               setIsSelectAllMode(false)
             }}
@@ -968,7 +1005,6 @@ export function KnowledgeBase({
               label: `Status: ${enabledFilter === 'enabled' ? 'Enabled' : 'Disabled'}`,
               onRemove: () => {
                 setEnabledFilter('all')
-                setCurrentPage(1)
                 setSelectedDocuments(new Set())
                 setIsSelectAllMode(false)
               },

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

@@ -1,4 +1,4 @@
-import { parseAsInteger, parseAsString } from 'nuqs/server'
+import { parseAsInteger, parseAsString, parseAsStringLiteral } from 'nuqs/server'
 import { ADD_CONNECTOR_SEARCH_PARAM } from '@/lib/credentials/client-state'
 
 /**
@@ -30,3 +30,53 @@ export const pageUrlKeys = {
   history: 'replace',
   clearOnDefault: true,
 } as const
+
+/** Document `enabled` filter buckets, matching the status filter dropdown. */
+const ENABLED_FILTERS = ['all', 'enabled', 'disabled'] as const
+
+/** Sortable document columns, matching the `Resource` sort menu / `DocumentSortField`. */
+export const KB_SORT_COLUMNS = [
+  'filename',
+  'fileSize',
+  'tokenCount',
+  'chunkCount',
+  'uploadedAt',
+  'enabled',
+] as const
+
+export type KbSortColumn = (typeof KB_SORT_COLUMNS)[number]
+
+const SORT_DIRECTIONS = ['asc', 'desc'] as const
+
+/** Default sort: most-recently-uploaded first (matches the document query default). */
+export const DEFAULT_KB_SORT_COLUMN = 'uploadedAt'
+export const DEFAULT_KB_SORT_DIRECTION = 'desc'
+
+/**
+ * Grouped filter/search/sort URL state for the document list.
+ *
+ * - `q` is the document name search. The input is controlled directly by the
+ *   instant nuqs value; only its URL write is debounced via `limitUrlUpdates`
+ *   on the setter — never written on every keystroke.
+ * - `enabled` filters by processing/enabled status (`all` clears from the URL).
+ * - `sort` / `dir` follow the shared `sort`+`dir` convention. The defaults match
+ *   the document query's default order; "no active sort" is derived in the
+ *   component as `sort === DEFAULT && dir === DEFAULT`.
+ *
+ * `tagFilterEntries` is intentionally NOT represented here: it is an array of
+ * rich filter-rule objects (slot, field type, operator, value, value-to per
+ * row), too large/structured for the URL per the URL-state doctrine. It stays
+ * in local `useState`.
+ */
+export const documentFiltersParsers = {
+  q: parseAsString.withDefault(''),
+  enabled: parseAsStringLiteral(ENABLED_FILTERS).withDefault('all'),
+  sort: parseAsStringLiteral(KB_SORT_COLUMNS).withDefault(DEFAULT_KB_SORT_COLUMN),
+  dir: parseAsStringLiteral(SORT_DIRECTIONS).withDefault(DEFAULT_KB_SORT_DIRECTION),
+} as const
+
+/** Filter/search/sort view-state: clean URLs, no back-stack churn. */
+export const documentFiltersUrlKeys = {
+  history: 'replace',
+  clearOnDefault: true,
+} as const

apps/sim/app/workspace/[workspaceId]/scheduled-tasks/hooks/use-calendar.ts

@@ -2,7 +2,12 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { isSameDay } from 'date-fns'
+import { useQueryStates } from 'nuqs'
 import { zonedClockDate } from '@/lib/core/utils/timezone'
+import {
+  calendarParsers,
+  calendarUrlKeys,
+} from '@/app/workspace/[workspaceId]/scheduled-tasks/search-params'
 import {
   advanceAnchor,
   type CalendarScope,
@@ -40,43 +45,74 @@ export interface UseCalendarReturn {
 }
 
 /**
- * Owns the calendar's ephemeral view state (scope, anchor, selected slot, and
- * create-modal open state). Pure UI state — `useState`, not a store. Opens on
- * the `week` scope. "Now" (the today highlight, the anchor's initial day) is
- * resolved in `timezone` — the viewer's effective zone — so the calendar's date
- * frame matches the zone tasks are scheduled in. `today` is polled so the today
- * highlight and current-time column survive midnight without a remount; the poll
- * only re-renders when the day actually changes (the interval is resilient to
- * device sleep, unlike a one-shot timeout aimed at midnight).
+ * Owns the calendar's view state. `scope` and `anchor` live in the URL (nuqs) so
+ * the current view is shareable and survives reload / back-forward; the create
+ * modal and selected slot stay local (ephemeral UI). Opens on the `week` scope.
+ * "Now" (the today highlight, the default anchor) is resolved in `timezone` — the
+ * viewer's effective zone — so the calendar's date frame matches the zone tasks
+ * are scheduled in. The `anchor` param is date-only and nullable: a clean URL
+ * means "today", derived per-timezone here, so navigating to today clears the
+ * param. `today` is polled so the today highlight and current-time column survive
+ * midnight without a remount; the poll only re-renders when the day actually
+ * changes (the interval is resilient to device sleep, unlike a one-shot timeout
+ * aimed at midnight).
  */
 export function useCalendar(timezone: string): UseCalendarReturn {
   const timezoneRef = useRef(timezone)
   const [today, setToday] = useState<Date>(() => zonedClockDate(new Date(), timezone))
-  const [scope, setScope] = useState<CalendarScope>('week')
-  const [anchor, setAnchor] = useState<Date>(() => zonedClockDate(new Date(), timezone))
+  const [{ scope, anchor: anchorParam }, setCalendarState] = useQueryStates(
+    calendarParsers,
+    calendarUrlKeys
+  )
   const [selectedSlot, setSelectedSlot] = useState<CalendarSlot | null>(null)
   const [isCreateOpen, setIsCreateOpen] = useState(false)
   const todayRef = useRef(today)
 
+  /** A clean URL (no `anchor` param) means "today", resolved in the effective zone. */
+  const anchor = anchorParam ?? today
+  const anchorRef = useRef(anchor)
+
   useEffect(() => {
     todayRef.current = today
   }, [today])
+  useEffect(() => {
+    anchorRef.current = anchor
+  }, [anchor])
+
+  const setScope = useCallback(
+    (next: CalendarScope) => {
+      void setCalendarState({ scope: next })
+    },
+    [setCalendarState]
+  )
 
   /**
-   * Re-sync to the effective zone's current day when `timezone` actually
-   * changes — e.g. when `useTimezone()` resolves from the browser fallback to
-   * the saved account zone after mount. The focused day follows only while it is
-   * still on "today", so an in-progress navigation is preserved. Owning
-   * `timezoneRef` here (instead of a separate sync effect) keeps the guard
-   * honest: the ref still reflects the previous zone when this runs.
+   * Set the focused day. Writing `today` (the default anchor) as `null` keeps the
+   * URL clean and preserves the "clean URL = today" invariant.
+   */
+  const setAnchorDate = useCallback(
+    (date: Date) => {
+      void setCalendarState({ anchor: isSameDay(date, todayRef.current) ? null : date })
+    },
+    [setCalendarState]
+  )
+
+  /**
+   * Re-sync `today` to the effective zone's current day when `timezone` actually
+   * changes — e.g. when `useTimezone()` resolves from the browser fallback to the
+   * saved account zone after mount. When the URL holds an explicit anchor that
+   * was on the previous "today", drop it so the view follows to the new today;
+   * an in-progress navigation (anchor on another day) is preserved.
    */
   useEffect(() => {
     if (timezoneRef.current === timezone) return
     timezoneRef.current = timezone
     const now = zonedClockDate(new Date(), timezone)
-    setAnchor((current) => (isSameDay(current, todayRef.current) ? now : current))
+    if (anchorRef.current && isSameDay(anchorRef.current, todayRef.current)) {
+      void setCalendarState({ anchor: null })
+    }
     setToday(now)
-  }, [timezone])
+  }, [timezone, setCalendarState])
 
   useEffect(() => {
     const id = setInterval(() => {
@@ -86,15 +122,29 @@ export function useCalendar(timezone: string): UseCalendarReturn {
     return () => clearInterval(id)
   }, [])
 
-  const next = useCallback(() => setAnchor((current) => advanceAnchor(current, scope, 1)), [scope])
-  const prev = useCallback(() => setAnchor((current) => advanceAnchor(current, scope, -1)), [scope])
-  const goToday = useCallback(() => setAnchor(zonedClockDate(new Date(), timezoneRef.current)), [])
-  const goToDate = useCallback((date: Date) => setAnchor(date), [])
+  const next = useCallback(
+    () => setAnchorDate(advanceAnchor(anchorRef.current, scope, 1)),
+    [scope, setAnchorDate]
+  )
+  const prev = useCallback(
+    () => setAnchorDate(advanceAnchor(anchorRef.current, scope, -1)),
+    [scope, setAnchorDate]
+  )
+  const goToday = useCallback(
+    () => setAnchorDate(zonedClockDate(new Date(), timezoneRef.current)),
+    [setAnchorDate]
+  )
+  const goToDate = useCallback((date: Date) => setAnchorDate(date), [setAnchorDate])
 
-  const openDay = useCallback((date: Date) => {
-    setAnchor(date)
-    setScope('day')
-  }, [])
+  const openDay = useCallback(
+    (date: Date) => {
+      void setCalendarState({
+        anchor: isSameDay(date, todayRef.current) ? null : date,
+        scope: 'day',
+      })
+    },
+    [setCalendarState]
+  )
 
   const selectSlot = useCallback((date: Date, time?: string) => {
     setSelectedSlot({ date, time })