docs(url-state): convert inline comments to TSDoc

Author: waleedlatif1

apps/sim/app/workspace/[workspaceId]/home/home.tsx

@@ -69,25 +69,30 @@ export function Home({ chatId, userName, userId }: HomeProps) {
   useOAuthReturnRouter()
   const { workspaceId } = useParams<{ workspaceId: string }>()
   const router = useRouter()
-  // URL is the single source of truth for the selected resource. `Home` renders
-  // client-side, so nuqs reads `?resource=` from the URL on mount — the same
-  // value the page previously threaded through `initialResourceId` — and writes
-  // it back with `history: 'replace'`, the previous behavior, minus the banned
-  // `window.history.replaceState` param-mutation effect. The page wraps `Home`
-  // in Suspense for the `useSearchParams` requirement.
+  /**
+   * URL is the single source of truth for the selected resource. `Home` renders
+   * client-side, so nuqs reads `?resource=` from the URL on mount — the same
+   * value the page previously threaded through `initialResourceId` — and writes
+   * it back with `history: 'replace'`, the previous behavior, minus the banned
+   * `window.history.replaceState` param-mutation effect. The page wraps `Home`
+   * in Suspense for the `useSearchParams` requirement.
+   */
   const [activeResourceParam, setResourceParam] = useQueryState(resourceParam.key, {
     ...resourceParam.parser,
     ...resourceUrlKeys,
   })
-  // Strips any leftover URL fragment on selection change, preserving the old
-  // effect's `url.hash = ''` (the only hash usage on this surface) without a
-  // separate effect-sync mirror. This rewrites the fragment only — it never
-  // mutates a query param via the History API.
+  /**
+   * Strips any leftover URL fragment on selection change, preserving the old
+   * effect's `url.hash = ''` (the only hash usage on this surface) without a
+   * separate effect-sync mirror. This rewrites the fragment only — it never
+   * mutates a query param via the History API.
+   *
+   * Order matters: the fragment is stripped synchronously BEFORE the nuqs write,
+   * because nuqs re-appends `location.hash` on its (deferred) flush — clearing the
+   * hash first ensures the param write doesn't carry the stale fragment back.
+   */
   const setActiveResourceUrl = useCallback<Dispatch<SetStateAction<string | null>>>(
     (action) => {
-      // Order matters: strip the fragment synchronously BEFORE the nuqs write.
-      // nuqs re-appends `location.hash` on its (deferred) flush, so clearing the
-      // hash first ensures the param write doesn't carry the stale fragment back.
       if (typeof window !== 'undefined' && window.location.hash) {
         const { pathname, search } = window.location
         window.history.replaceState(window.history.state, '', `${pathname}${search}`)
@@ -96,8 +101,10 @@ export function Home({ chatId, userName, userId }: HomeProps) {
     },
     [setResourceParam]
   )
-  // Controlled binding handed to `useChat` so the URL is the sole owner of the
-  // selection with no dual source.
+  /**
+   * Controlled binding handed to `useChat` so the URL is the sole owner of the
+   * selection with no dual source.
+   */
   const activeResourceState = useMemo<[string | null, Dispatch<SetStateAction<string | null>>]>(
     () => [activeResourceParam, setActiveResourceUrl],
     [activeResourceParam, setActiveResourceUrl]

apps/sim/app/workspace/[workspaceId]/home/hooks/use-chat.ts

@@ -1070,9 +1070,11 @@ export function useChat(
   const internalActiveResourceState = useState<string | null>(
     options?.initialActiveResourceId ?? null
   )
-  // Prefer a caller-supplied controlled binding (URL-backed nuqs on the home/Chat
-  // surface) so the URL is the single source of truth; fall back to internal state
-  // for the workflow editor copilot, which keeps resource selection out of the URL.
+  /**
+   * Prefer a caller-supplied controlled binding (URL-backed nuqs on the home/Chat
+   * surface) so the URL is the single source of truth; fall back to internal state
+   * for the workflow editor copilot, which keeps resource selection out of the URL.
+   */
   const [activeResourceId, setActiveResourceId] =
     options?.activeResourceState ?? internalActiveResourceState
   const [genericResourceData, setGenericResourceData] = useState<GenericResourceData | null>(null)

apps/sim/app/workspace/[workspaceId]/integrations/integrations.tsx

@@ -141,9 +141,11 @@ export function Integrations() {
   const [{ category: selectedCategory, search: urlSearchTerm }, setIntegrationFilters] =
     useQueryStates(integrationsParsers, integrationsUrlKeys)
 
-  // The input is controlled directly by the instant nuqs value; only the URL
-  // write is debounced. Filtering below is cheap in-memory over a static list,
-  // so it reads the instant value too.
+  /**
+   * The input is controlled directly by the instant nuqs value; only the URL
+   * write is debounced. Filtering below is cheap in-memory over a static list,
+   * so it reads the instant value too.
+   */
   const setSearchTerm = useCallback(
     (value: string) => {
       const trimmed = value.trim()

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

@@ -188,13 +188,15 @@ export function Document({
 
   const [selectedChunks, setSelectedChunks] = useState<Set<string>>(() => new Set())
 
-  // Inline editor state. The open chunk is sourced directly from the URL `chunk`
-  // param (single source of truth) so back/forward, deep links, and external
-  // navigation drive the editor; opening/closing a chunk writes the param.
+  /**
+   * Inline editor state. The open chunk is sourced directly from the URL `chunk`
+   * param (single source of truth) so back/forward, deep links, and external
+   * navigation drive the editor; opening/closing a chunk writes the param.
+   */
   const selectedChunkId = chunkFromURL
+  /** Opening a chunk is a destination (back closes it); clearing replaces. */
   const setSelectedChunkId = useCallback(
     (chunkId: string | null) => {
-      // Opening a chunk is a destination (back closes it); clearing replaces.
       void setDocumentParams({ chunk: chunkId }, chunkId !== null ? { history: 'push' } : undefined)
     },
     [setDocumentParams]

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

@@ -293,9 +293,11 @@ export function KnowledgeBase({
     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.
+  /**
+   * 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 trimmed = newQuery.trim()
@@ -898,8 +900,10 @@ export function KnowledgeBase({
         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.
+      /**
+       * Clearing writes the defaults back (stripped by clearOnDefault), so the
+       * sort menu reads "no active sort" again and the URL stays clean.
+       */
       onClear: () => {
         setDocumentFilters({ sort: DEFAULT_KB_SORT_COLUMN, dir: DEFAULT_KB_SORT_DIRECTION })
         setCurrentPage(1)

apps/sim/app/workspace/[workspaceId]/logs/components/log-details/log-details.tsx

@@ -278,8 +278,11 @@ export function LogDetailsContent({ log, onActiveTabChange }: LogDetailsContentP
   const { config: permissionConfig } = usePermissionConfig()
 
   const isInitialTabMountRef = useRef(true)
+  /**
+   * Honors a deep-linked tab on first mount; resets to overview only when
+   * switching to a different log.
+   */
   useEffect(() => {
-    // Honor a deep-linked tab on first mount; reset to overview only when switching to a different log.
     if (isInitialTabMountRef.current) {
       isInitialTabMountRef.current = false
     } else {

apps/sim/app/workspace/[workspaceId]/logs/hooks/use-log-filters.ts

@@ -115,13 +115,15 @@ export function useLogFilters(): UseLogFilters {
     [setFilters]
   )
 
+  /**
+   * Debounces only the search param's URL write; the returned `filters.search`
+   * value still updates instantly so the controlled input stays responsive.
+   * Clearing flushes immediately so the param drops out without lingering.
+   */
   const setSearchQuery = useCallback(
     (query: string) => {
       const trimmed = query.trim()
       const next = trimmed.length > 0 ? trimmed : null
-      // Debounce only the search param's URL write; the returned `filters.search`
-      // value still updates instantly so the controlled input stays responsive.
-      // Clearing flushes immediately so the param drops out without lingering.
       setFilters(
         { search: next },
         next === null ? undefined : { limitUrlUpdates: debounce(SEARCH_DEBOUNCE_MS) }

apps/sim/app/workspace/[workspaceId]/logs/logs.tsx

@@ -237,17 +237,21 @@ export default function Logs() {
   const [executionId] = useQueryState(executionIdParam.key, executionIdParam.parser)
   const [pendingExecutionId, setPendingExecutionId] = useState<string | null>(() => executionId)
 
-  // The log-details `tab` param is owned/written by the details panel, but the
-  // orchestrator must clear it when the panel closes so a lingering `?tab=trace`
-  // never carries over to the next log opened from the list.
+  /**
+   * The log-details `tab` param is owned/written by the details panel, but the
+   * orchestrator must clear it when the panel closes so a lingering `?tab=trace`
+   * never carries over to the next log opened from the list.
+   */
   const [, setLogDetailsTab] = useQueryState(logDetailsTabParam.key, {
     ...logDetailsTabParam.parser,
     ...logDetailsTabUrlKeys,
   })
 
-  // `urlSearchQuery` is the instant nuqs value (its URL write is debounced inside
-  // `useLogFilters`); the query/filtering still debounce off it to avoid per-keystroke
-  // fetches.
+  /**
+   * `urlSearchQuery` is the instant nuqs value (its URL write is debounced inside
+   * `useLogFilters`); the query/filtering still debounce off it to avoid
+   * per-keystroke fetches.
+   */
   const debouncedSearchQuery = useDebounce(urlSearchQuery, 300)
 
   const isLive = true
@@ -487,9 +491,11 @@ export default function Logs() {
     }
   }, [contextMenuLog, workflowIds, setWorkflowIds])
 
+  /**
+   * `resetFilters()` already clears `search` (sets it to null), so no separate
+   * search reset is needed here.
+   */
   const handleClearAllFilters = useCallback(() => {
-    // `resetFilters()` already clears `search` (sets it to null), so no separate
-    // search reset is needed here.
     resetFilters()
   }, [resetFilters])
 

apps/sim/app/workspace/[workspaceId]/settings/components/recently-deleted/recently-deleted.tsx

@@ -157,9 +157,11 @@ export function RecentlyDeleted() {
     setRecentlyDeletedFilters,
   ] = useQueryStates(recentlyDeletedParsers, recentlyDeletedUrlKeys)
 
-  // The input is controlled directly by the instant nuqs value; only the URL
-  // write is debounced. Filtering below is cheap in-memory over a small list, so
-  // it reads the instant value too.
+  /**
+   * The input is controlled directly by the instant nuqs value; only the URL
+   * write is debounced. Filtering below is cheap in-memory over a small list, so
+   * it reads the instant value too.
+   */
   const setSearchTerm = useCallback(
     (value: string) => {
       const trimmed = value.trim()

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/table.tsx

@@ -504,8 +504,10 @@ export function Table({
       options: columnOptions,
       active: sortColumn ? { column: sortColumn, direction: sortDirection } : null,
       onSort: (column, direction) => setSortParams({ sort: column, dir: direction }),
-      // Clearing writes the default direction (stripped by clearOnDefault) and
-      // drops the column, leaving a clean URL with no active sort.
+      /**
+       * Clearing writes the default direction (stripped by clearOnDefault) and
+       * drops the column, leaving a clean URL with no active sort.
+       */
       onClear: () => setSortParams({ sort: null, dir: DEFAULT_TABLE_DETAIL_SORT_DIRECTION }),
     }),
     [columnOptions, sortColumn, sortDirection, setSortParams]