improvement(url-state): migrate ee settings sections to nuqs deep-linkable view-state

- audit-logs: types/time-range/start-date/end-date filters move to a co-located
  search-params.ts (reusing the logs kebab-token time-range parser); search binds
  to the shared settings ?search= via useSettingsSearch, replacing a hand-rolled
  debounce effect
- access-control: group detail deep-links via ?group-id (push/replace-on-close);
  search via useSettingsSearch
- custom-blocks: block detail deep-links via ?custom-block-id; create flow stays
  local; search via useSettingsSearch
- data-drains + forks: search via useSettingsSearch; forks close now replaces
  history like the mcp reference pattern
- polish: nullable-reason comment on logs startDate/endDate, stale debounce
  TSDoc now references useDebouncedSearchSetter

Author: waleedlatif1

apps/sim/app/(landing)/integrations/search-params.ts

@@ -6,8 +6,8 @@ import { createSearchParamsCache, parseAsString } from 'nuqs/server'
  * so the filtered view is server-rendered for shareable, crawlable `?category=`/`?q=`
  * URLs — the same SSR pattern the blog index uses.
  *
- * - `q` is the search filter; its URL write is debounced on the setter, never
- *   written per keystroke.
+ * - `q` is the search filter; its URL write is debounced via
+ *   `useDebouncedSearchSetter`, never written per keystroke.
  * - `category` filters by integration type (`''` = all).
  */
 export const integrationsParsers = {

apps/sim/app/(landing)/models/search-params.ts

@@ -6,8 +6,8 @@ import { createSearchParamsCache, parseAsString } from 'nuqs/server'
  * so the filtered view is server-rendered for shareable, crawlable `?provider=`/`?q=`
  * URLs — the same SSR pattern the blog index uses.
  *
- * - `q` is the search filter; its URL write is debounced on the setter, never
- *   written per keystroke.
+ * - `q` is the search filter; its URL write is debounced via
+ *   `useDebouncedSearchSetter`, never written per keystroke.
  * - `provider` filters by provider id (`''` = all).
  */
 export const modelsParsers = {

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

@@ -15,8 +15,8 @@ export const CONNECTED_LABEL = 'Connected'
  *   pseudo-categories and are derived from the data set, so a plain string is
  *   used; the `All` default clears from the URL.
  * - `search` is the integration search term. The input is controlled directly by
- *   the nuqs value; only its URL write is debounced via `limitUrlUpdates`
- *   (`debounce`) on the setter — never written on every keystroke.
+ *   the nuqs value; only its URL write is debounced via
+ *   `useDebouncedSearchSetter` — never written on every keystroke.
  */
 export const integrationsParsers = {
   category: parseAsString.withDefault(ALL_CATEGORY),

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

@@ -27,8 +27,8 @@ export const knowledgeSortParams = createSortParams(KNOWLEDGE_SORT_COLUMNS, {
  *
  * - `search` is the knowledge base name/description filter. The input is
  *   controlled directly by the instant nuqs value; only its URL write is
- *   debounced via `limitUrlUpdates` (`debounce`) on the setter — never written
- *   on every keystroke.
+ *   debounced via `useDebouncedSearchSetter` — never written on every
+ *   keystroke.
  * - `connector` filters by connector presence; `content` filters by document
  *   presence; `owner` filters by creator id. All are multi-select arrays.
  *

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

@@ -104,6 +104,8 @@ export const parseAsTriggers = createParser<TriggerType[]>({
  */
 export const logFilterParsers = {
   timeRange: parseAsTimeRange.withDefault(DEFAULT_TIME_RANGE),
+  // Deliberately nullable: only populated when timeRange is "Custom range";
+  // every preset range derives its window from the label instead.
   startDate: parseAsString,
   endDate: parseAsString,
   level: parseAsLogLevel.withDefault('all'),

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

@@ -49,6 +49,37 @@ export const forkViewUrlKeys = {
   clearOnDefault: true,
 } as const
 
+/**
+ * `group-id` deep-links the Access Control settings tab to a specific
+ * permission group's detail sub-view (mirrors `mcpServerId` on the MCP tab).
+ */
+export const groupIdParam = {
+  key: 'group-id',
+  parser: parseAsString,
+} as const
+
+/** Opening a group's detail is a destination → push to history; clear on close. */
+export const groupIdUrlKeys = {
+  history: 'push',
+  clearOnDefault: true,
+} as const
+
+/**
+ * `custom-block-id` deep-links the Custom Blocks settings tab to a specific
+ * block's detail sub-view. The "create new" flow stays in local state — only
+ * existing entities are deep-linkable.
+ */
+export const customBlockIdParam = {
+  key: 'custom-block-id',
+  parser: parseAsString,
+} as const
+
+/** Opening a block's detail is a destination → push to history; clear on close. */
+export const customBlockIdUrlKeys = {
+  history: 'push',
+  clearOnDefault: true,
+} as const
+
 /**
  * `fork-direction` is the sync direction (push/pull) on the parent fork's detail
  * page — shareable view state, so a copied link opens the same side of the sync.

apps/sim/app/workspace/[workspaceId]/settings/components/inbox/search-params.ts

@@ -18,7 +18,7 @@ export type InboxStatusFilter = (typeof INBOX_STATUS_FILTERS)[number]
  * - `status` is the active status filter (feeds the tasks query key).
  * - `search` is the subject/sender/body name filter. The input is controlled
  *   directly by the nuqs value; only its URL write is debounced via
- *   `limitUrlUpdates` (`debounce`) on the setter — never written per keystroke.
+ *   `useDebouncedSearchSetter` — never written per keystroke.
  */
 export const inboxTaskParsers = {
   status: parseAsStringLiteral(INBOX_STATUS_FILTERS).withDefault('all'),

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

@@ -23,8 +23,7 @@ export const skillIdUrlKeys = {
 /**
  * `search` filters the skills list by name/description. The input is controlled
  * directly by the instant nuqs value; only its URL write is debounced via
- * `limitUrlUpdates` (`debounce`) on the setter — never written on every
- * keystroke.
+ * `useDebouncedSearchSetter` — never written on every keystroke.
  */
 export const skillSearchParam = {
   key: 'search',

apps/sim/ee/access-control/components/access-control.tsx

@@ -16,11 +16,17 @@ import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
 import { ArrowRight, Plus } from 'lucide-react'
 import { useParams } from 'next/navigation'
+import { useQueryState } from 'nuqs'
 import { isEnterprise } from '@/lib/billing/plan-helpers'
 import { getEnv, isTruthy } from '@/lib/core/config/env'
+import {
+  groupIdParam,
+  groupIdUrlKeys,
+} from '@/app/workspace/[workspaceId]/settings/[section]/search-params'
 import { SettingsEmptyState } from '@/app/workspace/[workspaceId]/settings/components/settings-empty-state'
 import { SettingsPanel } from '@/app/workspace/[workspaceId]/settings/components/settings-panel'
 import { SettingsSection } from '@/app/workspace/[workspaceId]/settings/components/settings-section/settings-section'
+import { useSettingsSearch } from '@/app/workspace/[workspaceId]/settings/components/use-settings-search'
 import { GroupDetail } from '@/ee/access-control/components/group-detail'
 import { WorkspaceSelect } from '@/ee/access-control/components/workspace-select'
 import {
@@ -74,8 +80,11 @@ export function AccessControl({ isOrganizationAdmin, organizationId }: AccessCon
 
   const createPermissionGroup = useCreatePermissionGroup()
 
-  const [searchTerm, setSearchTerm] = useState('')
-  const [selectedGroupId, setSelectedGroupId] = useState<string | null>(null)
+  const [searchTerm, setSearchTerm] = useSettingsSearch()
+  const [selectedGroupId, setSelectedGroupId] = useQueryState(groupIdParam.key, {
+    ...groupIdParam.parser,
+    ...groupIdUrlKeys,
+  })
   const [showCreateModal, setShowCreateModal] = useState(false)
   const [newGroupName, setNewGroupName] = useState('')
   const [newGroupDescription, setNewGroupDescription] = useState('')
@@ -160,8 +169,8 @@ export function AccessControl({ isOrganizationAdmin, organizationId }: AccessCon
         workspaceOptions={workspaceOptions}
         organizationWorkspaces={organizationWorkspaces}
         workspacesLoading={workspacesLoading}
-        onBack={() => setSelectedGroupId(null)}
-        onDeleted={() => setSelectedGroupId(null)}
+        onBack={() => void setSelectedGroupId(null, { history: 'replace' })}
+        onDeleted={() => void setSelectedGroupId(null, { history: 'replace' })}
       />
     )
   }
@@ -198,7 +207,7 @@ export function AccessControl({ isOrganizationAdmin, organizationId }: AccessCon
                 <button
                   key={group.id}
                   type='button'
-                  onClick={() => setSelectedGroupId(group.id)}
+                  onClick={() => void setSelectedGroupId(group.id)}
                   className='flex items-center gap-2.5 rounded-lg p-2 text-left transition-colors hover-hover:bg-[var(--surface-active)]'
                 >
                   <div className='flex min-w-0 flex-1 flex-col'>

apps/sim/ee/audit-logs/components/audit-logs.tsx

@@ -20,7 +20,9 @@ import {
 import { createLogger } from '@sim/logger'
 import { formatDateTime } from '@sim/utils/formatting'
 import { isRecordLike } from '@sim/utils/object'
+import { useQueryStates } from 'nuqs'
 import { getEndDateFromTimeRange, getStartDateFromTimeRange } from '@/lib/logs/filters'
+import { SEARCH_DEBOUNCE_MS } from '@/lib/url-state'
 import type { EnterpriseAuditLogEntry } from '@/app/api/v1/audit-logs/format'
 import { formatDateShort } from '@/app/workspace/[workspaceId]/logs/utils'
 import {
@@ -29,8 +31,11 @@ import {
 } from '@/app/workspace/[workspaceId]/settings/components/activity-log'
 import { SettingsEmptyState } from '@/app/workspace/[workspaceId]/settings/components/settings-empty-state'
 import { SettingsPanel } from '@/app/workspace/[workspaceId]/settings/components/settings-panel'
+import { useSettingsSearch } from '@/app/workspace/[workspaceId]/settings/components/use-settings-search'
 import { RESOURCE_TYPE_OPTIONS } from '@/ee/audit-logs/constants'
 import { type AuditLogFilters, useAuditLogs } from '@/ee/audit-logs/hooks/audit-logs'
+import { auditLogFilterParsers, auditLogFilterUrlKeys } from '@/ee/audit-logs/search-params'
+import { useDebounce } from '@/hooks/use-debounce'
 import type { TimeRange } from '@/stores/logs/filters/types'
 
 const logger = createLogger('AuditLogs')
@@ -228,31 +233,19 @@ interface AuditLogsProps {
 }
 
 export function AuditLogs({ organizationId }: AuditLogsProps) {
-  const [selectedTypes, setSelectedTypes] = useState<string[]>([])
-  const [timeRange, setTimeRange] = useState<TimeRange>('Past 30 days')
-  const [customStartDate, setCustomStartDate] = useState('')
-  const [customEndDate, setCustomEndDate] = useState('')
+  const [urlFilters, setUrlFilters] = useQueryStates(auditLogFilterParsers, auditLogFilterUrlKeys)
+  const { types: selectedTypes, timeRange } = urlFilters
+  const customStartDate = urlFilters.startDate ?? ''
+  const customEndDate = urlFilters.endDate ?? ''
   const [datePickerOpen, setDatePickerOpen] = useState(false)
-  const previousTimeRangeRef = useRef<TimeRange>('Past 30 days')
+  const previousTimeRangeRef = useRef<TimeRange>(timeRange)
   const dateRangeAppliedRef = useRef(false)
-  const [searchTerm, setSearchTerm] = useState('')
-  const [debouncedSearch, setDebouncedSearch] = useState('')
-  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const [searchTerm, setSearchTerm] = useSettingsSearch()
+  const debouncedSearch = useDebounce(searchTerm, SEARCH_DEBOUNCE_MS).trim()
   const [isVisuallyRefreshing, setIsVisuallyRefreshing] = useState(false)
   const refreshTimersRef = useRef(new Set<number>())
   const [isExporting, setIsExporting] = useState(false)
 
-  useEffect(() => {
-    const trimmed = searchTerm.trim()
-    if (trimmed === debouncedSearch) return
-    debounceRef.current = setTimeout(() => {
-      setDebouncedSearch(trimmed)
-    }, 300)
-    return () => {
-      if (debounceRef.current) clearTimeout(debounceRef.current)
-    }
-  }, [searchTerm, debouncedSearch])
-
   useEffect(() => {
     const timers = refreshTimersRef.current
     return () => {
@@ -301,23 +294,19 @@ export function AuditLogs({ organizationId }: AuditLogsProps) {
       previousTimeRangeRef.current = timeRange
       setDatePickerOpen(true)
     } else {
-      setCustomStartDate('')
-      setCustomEndDate('')
-      setTimeRange(value as TimeRange)
+      void setUrlFilters({ timeRange: value as TimeRange, startDate: null, endDate: null })
     }
   }
 
   const handleDateRangeApply = (start: string, end: string) => {
     dateRangeAppliedRef.current = true
-    setCustomStartDate(start)
-    setCustomEndDate(end)
-    setTimeRange('Custom range')
+    void setUrlFilters({ timeRange: 'Custom range', startDate: start, endDate: end })
     setDatePickerOpen(false)
   }
 
   const handleDatePickerCancel = () => {
     if (timeRange === 'Custom range' && !customStartDate) {
-      setTimeRange(previousTimeRangeRef.current)
+      void setUrlFilters({ timeRange: previousTimeRangeRef.current })
     }
     setDatePickerOpen(false)
   }
@@ -399,7 +388,7 @@ export function AuditLogs({ organizationId }: AuditLogsProps) {
           options={RESOURCE_TYPE_OPTIONS}
           multiSelect
           multiSelectValues={selectedTypes}
-          onMultiSelectChange={setSelectedTypes}
+          onMultiSelectChange={(values) => void setUrlFilters({ types: values })}
           placeholder='All types'
           displayLabel={typeDisplayLabel}
           searchable