feat: replace document status tabs with filter pills (#3145)

Swaps the tab row and dropdowns for faceted filter pills (status,
sender, period) with a shared reset, and moves URL param handling
to nuqs.

<img width="2198" height="1674" alt="image"
src="https://github.com/user-attachments/assets/6996431c-09c8-45c3-bc30-f0a1e503c941"
/>

apps/remix/app/routes/_authenticated+/t.$teamUrl+/documents._index.tsx

@@ -1,28 +1,20 @@
 import { useSessionStorage } from '@documenso/lib/client-only/hooks/use-session-storage';
-import { useCurrentOrganisation } from '@documenso/lib/client-only/providers/organisation';
-import { STATS_COUNT_CAP } from '@documenso/lib/constants/document';
 import { SKIP_QUERY_BATCH_META } from '@documenso/lib/constants/trpc';
 import { formatAvatarUrl } from '@documenso/lib/utils/avatars';
-import { parseToIntegerArray } from '@documenso/lib/utils/params';
 import { formatDocumentsPath } from '@documenso/lib/utils/teams';
 import { ExtendedDocumentStatus } from '@documenso/prisma/types/extended-document-status';
 import { trpc } from '@documenso/trpc/react';
 import type { TFindDocumentsInternalResponse } from '@documenso/trpc/server/document-router/find-documents-internal.types';
-import { ZFindDocumentsInternalRequestSchema } from '@documenso/trpc/server/document-router/find-documents-internal.types';
 import { Avatar, AvatarFallback, AvatarImage } from '@documenso/ui/primitives/avatar';
+import { Button } from '@documenso/ui/primitives/button';
 import type { RowSelectionState } from '@documenso/ui/primitives/data-table';
-import { Tabs, TabsList, TabsTrigger } from '@documenso/ui/primitives/tabs';
 import { msg } from '@lingui/core/macro';
 import { Trans } from '@lingui/react/macro';
-import {
-  EnvelopeType,
-  FolderType,
-  OrganisationType,
-  type DocumentStatus as PrismaDocumentStatus,
-} from '@prisma/client';
+import { EnvelopeType, FolderType, type DocumentStatus as PrismaDocumentStatus } from '@prisma/client';
+import { XIcon } from 'lucide-react';
+import { useQueryStates } from 'nuqs';
 import { useEffect, useMemo, useState } from 'react';
-import { Link, useNavigate, useParams, useSearchParams } from 'react-router';
-import { z } from 'zod';
+import { useNavigate, useParams } from 'react-router';
 
 import { EnvelopesBulkCancelDialog } from '~/components/dialogs/envelopes-bulk-cancel-dialog';
 import { EnvelopesBulkDeleteDialog } from '~/components/dialogs/envelopes-bulk-delete-dialog';
@@ -32,15 +24,16 @@ import {
 } from '~/components/dialogs/envelopes-bulk-download-dialog';
 import { EnvelopesBulkMoveDialog } from '~/components/dialogs/envelopes-bulk-move-dialog';
 import { DocumentSearch } from '~/components/general/document/document-search';
-import { DocumentStatus } from '~/components/general/document/document-status';
 import { EnvelopeDropZoneWrapper } from '~/components/general/envelope/envelope-drop-zone-wrapper';
 import { FolderGrid } from '~/components/general/folder/folder-grid';
-import { PeriodSelector } from '~/components/general/period-selector';
 import { DocumentsTable } from '~/components/tables/documents-table';
 import { DocumentsTableEmptyState } from '~/components/tables/documents-table-empty-state';
+import { DocumentsTablePeriodFilter } from '~/components/tables/documents-table-period-filter';
 import { DocumentsTableSenderFilter } from '~/components/tables/documents-table-sender-filter';
+import { DocumentsTableStatusFilter } from '~/components/tables/documents-table-status-filter';
 import { EnvelopesTableBulkActionBar } from '~/components/tables/envelopes-table-bulk-action-bar';
 import { useCurrentTeam } from '~/providers/team';
+import { documentsSearchParams } from '~/utils/documents-search-params';
 import { appMetaTags } from '~/utils/meta';
 
 export function meta() {
@@ -55,22 +48,10 @@ type EnvelopeMetaCache = Record<string, { title: string; status: PrismaDocumentS
 const EMPTY_ROW_SELECTION: RowSelectionState = {};
 const EMPTY_ENVELOPE_META_CACHE: EnvelopeMetaCache = {};
 
-const ZSearchParamsSchema = ZFindDocumentsInternalRequestSchema.pick({
-  status: true,
-  period: true,
-  page: true,
-  perPage: true,
-  query: true,
-}).extend({
-  senderIds: z.string().transform(parseToIntegerArray).optional().catch([]),
-});
-
 export default function DocumentsPage() {
-  const organisation = useCurrentOrganisation();
   const team = useCurrentTeam();
 
   const { folderId } = useParams();
-  const [searchParams] = useSearchParams();
   const navigate = useNavigate();
 
   const documentsPath = formatDocumentsPath(team.url);
@@ -107,14 +88,18 @@ export default function DocumentsPage() {
     [ExtendedDocumentStatus.ALL]: 0,
   });
 
-  const findDocumentSearchParams = useMemo(
-    () => ZSearchParamsSchema.safeParse(Object.fromEntries(searchParams.entries())).data || {},
-    [searchParams],
-  );
+  const [findDocumentSearchParams, setFindDocumentSearchParams] = useQueryStates(documentsSearchParams, {
+    history: 'push',
+  });
 
   const { data, isLoading, isLoadingError } = trpc.document.findDocumentsInternal.useQuery(
     {
-      ...findDocumentSearchParams,
+      status: findDocumentSearchParams.status ?? undefined,
+      period: findDocumentSearchParams.period ?? undefined,
+      senderIds: findDocumentSearchParams.senderIds ?? undefined,
+      page: findDocumentSearchParams.page ?? undefined,
+      perPage: findDocumentSearchParams.perPage ?? undefined,
+      query: findDocumentSearchParams.query ?? undefined,
       folderId,
     },
     {
@@ -167,34 +152,21 @@ export default function DocumentsPage() {
       .filter((item): item is EnvelopeBulkDownloadItem => item !== null);
   }, [selectedEnvelopeIds, envelopeMetaCache]);
 
-  const getTabHref = (value: keyof typeof ExtendedDocumentStatus) => {
-    const params = new URLSearchParams(searchParams);
+  const hasActiveFilters = useMemo(() => {
+    return Boolean(
+      (findDocumentSearchParams.status && findDocumentSearchParams.status !== ExtendedDocumentStatus.ALL) ||
+        findDocumentSearchParams.senderIds?.length ||
+        findDocumentSearchParams.period,
+    );
+  }, [findDocumentSearchParams]);
 
-    params.set('status', value);
-
-    if (value === ExtendedDocumentStatus.ALL) {
-      params.delete('status');
-    }
-
-    if (value === ExtendedDocumentStatus.INBOX && organisation.type === OrganisationType.PERSONAL) {
-      params.delete('status');
-    }
-
-    if (params.has('page')) {
-      params.delete('page');
-    }
-
-    let path = formatDocumentsPath(team.url);
-
-    if (folderId) {
-      path += `/f/${folderId}`;
-    }
-
-    if (params.toString()) {
-      path += `?${params.toString()}`;
-    }
-
-    return path;
+  const onResetFilters = () => {
+    void setFindDocumentSearchParams({
+      status: null,
+      senderIds: null,
+      period: null,
+      page: null,
+    });
   };
 
   useEffect(() => {
@@ -208,69 +180,40 @@ export default function DocumentsPage() {
       <div className="mx-auto w-full max-w-screen-xl px-4 md:px-8">
         <FolderGrid type={FolderType.DOCUMENT} parentId={folderId ?? null} />
 
-        <div className="mt-8 flex flex-wrap items-center justify-between gap-x-4 gap-y-8">
-          <div className="flex flex-row items-center">
-            <Avatar className="mr-3 h-12 w-12 border-2 border-white border-solid dark:border-border">
-              {team.avatarImageId && <AvatarImage src={formatAvatarUrl(team.avatarImageId)} />}
-              <AvatarFallback className="text-muted-foreground text-xs">{team.name.slice(0, 1)}</AvatarFallback>
-            </Avatar>
+        <div className="mt-8 flex flex-row items-center">
+          <Avatar className="mr-3 h-12 w-12 border-2 border-white border-solid dark:border-border">
+            {team.avatarImageId && <AvatarImage src={formatAvatarUrl(team.avatarImageId)} />}
+            <AvatarFallback className="text-muted-foreground text-xs">{team.name.slice(0, 1)}</AvatarFallback>
+          </Avatar>
 
-            <h2 className="font-semibold text-4xl">
-              <Trans>Documents</Trans>
-            </h2>
+          <h2 className="font-semibold text-4xl">
+            <Trans>Documents</Trans>
+          </h2>
+        </div>
+
+        <div className="mt-8 flex flex-wrap items-center gap-x-2 gap-y-4">
+          <div className="w-56">
+            <DocumentSearch />
           </div>
 
-          <div className="-m-1 flex flex-wrap gap-x-4 gap-y-6 overflow-hidden p-1">
-            <Tabs value={findDocumentSearchParams.status || 'ALL'} className="overflow-x-auto">
-              <TabsList>
-                {[
-                  ExtendedDocumentStatus.INBOX,
-                  ExtendedDocumentStatus.PENDING,
-                  ExtendedDocumentStatus.COMPLETED,
-                  ExtendedDocumentStatus.CANCELLED,
-                  ExtendedDocumentStatus.DRAFT,
-                  ExtendedDocumentStatus.REJECTED,
-                  ExtendedDocumentStatus.EXPIRED,
-                  ExtendedDocumentStatus.ALL,
-                ]
-                  .filter((value) => {
-                    if (organisation.type === OrganisationType.PERSONAL) {
-                      return value !== ExtendedDocumentStatus.INBOX;
-                    }
+          <DocumentsTableStatusFilter stats={stats} />
 
-                    return true;
-                  })
-                  .map((value) => (
-                    <TabsTrigger key={value} className="min-w-[60px] hover:text-foreground" value={value} asChild>
-                      <Link to={getTabHref(value)} preventScrollReset>
-                        <DocumentStatus status={value} />
+          {team && <DocumentsTableSenderFilter teamId={team.id} />}
 
-                        {value !== ExtendedDocumentStatus.ALL && (
-                          <span className="ml-1 inline-block opacity-50">
-                            {stats[value] >= STATS_COUNT_CAP ? `${STATS_COUNT_CAP.toLocaleString()}+` : stats[value]}
-                          </span>
-                        )}
-                      </Link>
-                    </TabsTrigger>
-                  ))}
-              </TabsList>
-            </Tabs>
+          <DocumentsTablePeriodFilter />
 
-            {team && <DocumentsTableSenderFilter teamId={team.id} />}
-
-            <div className="flex w-48 flex-wrap items-center justify-between gap-x-2 gap-y-4">
-              <PeriodSelector />
-            </div>
-            <div className="flex w-48 flex-wrap items-center justify-between gap-x-2 gap-y-4">
-              <DocumentSearch initialValue={findDocumentSearchParams.query} />
-            </div>
-          </div>
+          {hasActiveFilters && (
+            <Button variant="ghost" className="px-2 text-muted-foreground lg:px-3" onClick={onResetFilters}>
+              <Trans>Reset</Trans>
+              <XIcon className="ml-1 h-4 w-4" />
+            </Button>
+          )}
         </div>
 
         <div className="mt-8">
           <div>
             {data && data.count === 0 ? (
-              <DocumentsTableEmptyState status={findDocumentSearchParams.status || ExtendedDocumentStatus.ALL} />
+              <DocumentsTableEmptyState status={findDocumentSearchParams.status ?? ExtendedDocumentStatus.ALL} />
             ) : (
               <DocumentsTable
                 data={data}