improvement(billing): move credit usage period filter into the URL

waleedlatif1 · waleedlatif1 · commit 73679b175688 · 2026-07-03T13:13:26.000-07:00
/cleanup pass (nuqs rule, react-query-best-practices, emcn review):
- period was a plain useState, but it's exactly the kind of shareable
  list filter sim-url-state.md calls out for nuqs &mdash; migrated to
  billingParsers/useQueryStates so the selection deep-links, survives
  reload, and matches every sibling settings section (recently-deleted,
  inbox, teammates). Derives its literal values from
  usageLogPeriodSchema instead of a fourth copy of the same union.
- Removed an unjustified showSelectedCheck={false} on the period
  ChipDropdown &mdash; the one other usage in the codebase is a one-shot
  action menu with no persistent selection; this is a real filter and
  should show the check like the default intends.
- Added placeholderData: keepPreviousData to useUsageLogs &mdash; period is
  a variable query key, so without it switching periods flashed the
  loading empty-state instead of smoothly transitioning.

Verified live: deep-link with ?period=7d pre-selects and loads
correctly, switching periods updates the URL, and the selection
survives a hard reload.
diff --git a/apps/sim/app/workspace/[workspaceId]/settings/components/billing/components/credit-usage-section/credit-usage-section.tsx b/apps/sim/app/workspace/[workspaceId]/settings/components/billing/components/credit-usage-section/credit-usage-section.tsx
@@ -1,10 +1,14 @@
 'use client'
 
-import { useState } from 'react'
 import { Badge, ChipDropdown, type ChipDropdownOption, chipVariants, cn } from '@sim/emcn'
 import { formatDateTime } from '@sim/utils/formatting'
+import { useQueryStates } from 'nuqs'
 import type { UsageLogEntry, UsageLogPeriod, UsageLogSource } from '@/lib/api/contracts/user'
 import { formatCreditsLabel } from '@/lib/billing/credits/conversion'
+import {
+  billingParsers,
+  billingUrlKeys,
+} from '@/app/workspace/[workspaceId]/settings/components/billing/search-params'
 import { SettingsEmptyState } from '@/app/workspace/[workspaceId]/settings/components/settings-empty-state'
 import { SettingsSection } from '@/app/workspace/[workspaceId]/settings/components/settings-section/settings-section'
 import { useUsageLogs } from '@/hooks/queries/usage-logs'
@@ -62,7 +66,7 @@ function UsageLogRow({ log }: UsageLogRowProps) {
  * so builders can see exactly where their credits went.
  */
 export function CreditUsageSection() {
-  const [period, setPeriod] = useState<UsageLogPeriod>('30d')
+  const [{ period }, setFilters] = useQueryStates(billingParsers, billingUrlKeys)
 
   const { data, isLoading, isError, hasNextPage, isFetchingNextPage, fetchNextPage } = useUsageLogs(
     { period }
@@ -78,8 +82,7 @@ export function CreditUsageSection() {
         <ChipDropdown
           options={PERIOD_OPTIONS}
           value={period}
-          onChange={(value) => setPeriod(value as UsageLogPeriod)}
-          showSelectedCheck={false}
+          onChange={(value) => setFilters({ period: value as UsageLogPeriod })}
         />
       }
     >
diff --git a/apps/sim/app/workspace/[workspaceId]/settings/components/billing/search-params.ts b/apps/sim/app/workspace/[workspaceId]/settings/components/billing/search-params.ts
@@ -0,0 +1,21 @@
+import { parseAsStringLiteral } from 'nuqs/server'
+import { usageLogPeriodSchema } from '@/lib/api/contracts/user'
+
+/**
+ * Co-located, typed URL query-param definitions for the Billing settings
+ * view.
+ *
+ * - `period` is the Credit usage section's time-window filter, sharing its
+ *   literal values with {@link usageLogPeriodSchema} so the URL parser can
+ *   never drift from the API contract it filters.
+ */
+export const billingParsers = {
+  period: parseAsStringLiteral(usageLogPeriodSchema.options).withDefault('30d'),
+} as const
+
+/** Filter view-state: clean URLs, no back-stack churn. */
+export const billingUrlKeys = {
+  history: 'replace',
+  shallow: true,
+  clearOnDefault: true,
+} as const
diff --git a/apps/sim/hooks/queries/usage-logs.ts b/apps/sim/hooks/queries/usage-logs.ts
@@ -1,6 +1,6 @@
 'use client'
 
-import { useInfiniteQuery } from '@tanstack/react-query'
+import { keepPreviousData, useInfiniteQuery } from '@tanstack/react-query'
 import { requestJson } from '@/lib/api/client/request'
 import {
   getUsageLogsContract,
@@ -30,7 +30,8 @@ interface UseUsageLogsOptions {
 /**
  * Infinite-scrolls the authenticated user's credit-consuming usage events for
  * the Billing settings "Credit usage" section, keyset-paginated by the
- * backend's opaque `nextCursor`.
+ * backend's opaque `nextCursor`. Keeps the prior period's rows on screen
+ * while a newly selected period loads, since `period` is a variable key.
  */
 export function useUsageLogs({ period, enabled = true }: UseUsageLogsOptions) {
   return useInfiniteQuery({
@@ -41,5 +42,6 @@ export function useUsageLogs({ period, enabled = true }: UseUsageLogsOptions) {
       lastPage.pagination.hasMore ? lastPage.pagination.nextCursor : undefined,
     enabled,
     staleTime: 30 * 1000,
+    placeholderData: keepPreviousData,
   })
 }
