feat(explorer): move filter state to url

.changeset/sixty-comics-love.md

@@ -0,0 +1,5 @@
+---
+"@latticexyz/explorer": patch
+---
+
+Added support for tracking table filtering, sorting, and additional parameters like selected tableId using type-safe URL search params. This ensures that state changes persist across sessions and can be shared with a URL.

packages/explorer/package.json

@@ -61,6 +61,7 @@
     "debug": "^4.3.4",
     "lucide-react": "^0.408.0",
     "next": "14.2.5",
+    "nuqs": "^1.19.2",
     "query-string": "^9.1.0",
     "react": "^18",
     "react-dom": "^18",

packages/explorer/src/app/(explorer)/[chainName]/worlds/[worldAddress]/explore/DataExplorer.tsx

@@ -1,13 +1,11 @@
 "use client";
 
 import { Loader } from "lucide-react";
-import { useSearchParams } from "next/navigation";
 import { useQuery } from "@tanstack/react-query";
 import { TableSelector } from "./TableSelector";
 import { TablesViewer } from "./TablesViewer";
 
 export function DataExplorer() {
-  const searchParams = useSearchParams();
   const { data: tables, isLoading } = useQuery({
     queryKey: ["tables"],
     queryFn: async () => {
@@ -16,24 +14,22 @@ export function DataExplorer() {
       if (!response.ok) {
         throw new Error(json.error);
       }
-
       return json;
     },
     select: (data) => data.tables.map((table: { name: string }) => table.name),
     refetchInterval: 15000,
     throwOnError: true,
     retry: false,
   });
-  const selectedTable = searchParams.get("tableId") || (tables?.length > 0 ? tables[0] : null);
 
   if (isLoading) {
     return <Loader className="animate-spin" />;
   }
 
   return (
     <>
-      <TableSelector value={selectedTable} options={tables} />
-      <TablesViewer table={selectedTable} />
+      <TableSelector tables={tables} />
+      <TablesViewer />
     </>
   );
 }

packages/explorer/src/app/(explorer)/[chainName]/worlds/[worldAddress]/explore/TableSelector.tsx

@@ -1,6 +1,8 @@
 import { Check, ChevronsUpDown, Lock } from "lucide-react";
 import { useParams } from "next/navigation";
-import { useState } from "react";
+import { useQueryState } from "nuqs";
+import { Hex } from "viem";
+import { useEffect, useState } from "react";
 import { internalTableNames } from "@latticexyz/store-sync/sqlite";
 import { Button } from "../../../../../../components/ui/Button";
 import {
@@ -15,20 +17,28 @@ import { Popover, PopoverContent, PopoverTrigger } from "../../../../../../compo
 import { cn } from "../../../../../../lib/utils";
 
 type Props = {
-  value: string | undefined;
-  options: string[];
+  tables: string[];
 };
 
-export function TableSelector({ value, options }: Props) {
+export function TableSelector({ tables }: Props) {
+  const [selectedTableId, setTableId] = useQueryState("tableId");
   const [open, setOpen] = useState(false);
   const { worldAddress } = useParams();
 
+  useEffect(() => {
+    if (!selectedTableId && tables.length > 0) {
+      setTableId(tables[0] as Hex);
+    }
+  }, [selectedTableId, setTableId, tables]);
+
   return (
     <div className="w-full py-4">
       <Popover open={open} onOpenChange={setOpen}>
         <PopoverTrigger asChild>
           <Button variant="outline" role="combobox" aria-expanded={open} className="w-full justify-between">
-            {value ? options.find((option) => option === value)?.replace(`${worldAddress}__`, "") : "Select table..."}
+            {selectedTableId
+              ? tables.find((tableId) => tableId === selectedTableId)?.replace(`${worldAddress}__`, "")
+              : "Select table..."}
             <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
           </Button>
         </PopoverTrigger>
@@ -39,26 +49,24 @@ export function TableSelector({ value, options }: Props) {
             <CommandList>
               <CommandEmpty>No framework found.</CommandEmpty>
               <CommandGroup>
-                {options.map((option) => {
+                {tables.map((tableId) => {
                   return (
                     <CommandItem
-                      key={option}
-                      value={option}
-                      onSelect={(currentValue) => {
-                        const url = new URL(window.location.href);
-                        const searchParams = new URLSearchParams(url.search);
-                        searchParams.set("tableId", currentValue);
-                        window.history.pushState({}, "", `${window.location.pathname}?${searchParams}`);
-
+                      key={tableId}
+                      value={tableId}
+                      onSelect={(newTableId) => {
+                        setTableId(newTableId as Hex);
                         setOpen(false);
                       }}
                       className="font-mono"
                     >
-                      <Check className={cn("mr-2 h-4 w-4", value === option ? "opacity-100" : "opacity-0")} />
-                      {(internalTableNames as string[]).includes(option) && (
+                      <Check
+                        className={cn("mr-2 h-4 w-4", selectedTableId === tableId ? "opacity-100" : "opacity-0")}
+                      />
+                      {(internalTableNames as string[]).includes(tableId) && (
                         <Lock className="mr-2 inline-block opacity-70" size={14} />
                       )}
-                      {option.replace(`${worldAddress}__`, "")}
+                      {tableId.replace(`${worldAddress}__`, "")}
                     </CommandItem>
                   );
                 })}

packages/explorer/src/app/(explorer)/[chainName]/worlds/[worldAddress]/explore/TablesViewer.tsx

@@ -1,12 +1,11 @@
 import { ArrowUpDown, Loader } from "lucide-react";
-import { useState } from "react";
+import { parseAsArrayOf, parseAsBoolean, parseAsJson, parseAsString, useQueryState } from "nuqs";
+import { useRef } from "react";
 import { internalTableNames } from "@latticexyz/store-sync/sqlite";
 import { useQuery } from "@tanstack/react-query";
 import {
   ColumnDef,
-  ColumnFiltersState,
-  SortingState,
-  VisibilityState,
+  ColumnSort,
   flexRender,
   getCoreRowModel,
   getFilteredRowModel,
@@ -21,22 +20,19 @@ import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from ".
 import { bufferToBigInt } from "../utils/bufferToBigInt";
 import { EditableTableCell } from "./EditableTableCell";
 
-type Props = {
-  table: string | undefined;
-};
-
-export function TablesViewer({ table: selectedTable }: Props) {
-  const [sorting, setSorting] = useState<SortingState>([]);
-  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
-  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({});
-  const [rowSelection, setRowSelection] = useState({});
-  const [globalFilter, setGlobalFilter] = useState("");
-  const [showAllColumns, setShowAllColumns] = useState(false);
+export function TablesViewer() {
+  const [selectedTableId] = useQueryState("tableId");
+  const [globalFilter, setGlobalFilter] = useQueryState("filter", parseAsString.withDefault(""));
+  const [showAllColumns, setShowAllColumns] = useQueryState("showAllColumns", parseAsBoolean.withDefault(false));
+  const [sorting, setSorting] = useQueryState(
+    "sort",
+    parseAsArrayOf(parseAsJson<ColumnSort>()).withDefault(useRef([]).current),
+  );
 
   const { data: schema } = useQuery({
-    queryKey: ["schema", { table: selectedTable }],
+    queryKey: ["schema", { table: selectedTableId }],
     queryFn: async () => {
-      const response = await fetch(`/api/schema?table=${selectedTable}`);
+      const response = await fetch(`/api/schema?table=${selectedTableId}`);
       return response.json();
     },
     select: (data) => {
@@ -50,9 +46,9 @@ export function TablesViewer({ table: selectedTable }: Props) {
   });
 
   const { data: rows } = useQuery({
-    queryKey: ["rows", { table: selectedTable }],
+    queryKey: ["rows", { table: selectedTableId }],
     queryFn: async () => {
-      const response = await fetch(`/api/rows?table=${selectedTable}`);
+      const response = await fetch(`/api/rows?table=${selectedTableId}`);
       return response.json();
     },
     select: (data) => {
@@ -67,14 +63,14 @@ export function TablesViewer({ table: selectedTable }: Props) {
         );
       });
     },
-    enabled: Boolean(selectedTable),
+    enabled: Boolean(selectedTableId),
     refetchInterval: 1000,
   });
 
   const { data: mudTableConfig } = useQuery({
-    queryKey: ["table", { selectedTable }],
+    queryKey: ["table", { selectedTableId }],
     queryFn: async () => {
-      const response = await fetch(`/api/table?table=${selectedTable}`);
+      const response = await fetch(`/api/table?table=${selectedTableId}`);
       return response.json();
     },
     select: (data) => {
@@ -84,7 +80,7 @@ export function TablesViewer({ table: selectedTable }: Props) {
         value_schema: JSON.parse(data.table.value_schema).json,
       };
     },
-    enabled: Boolean(selectedTable),
+    enabled: Boolean(selectedTableId),
   });
 
   const columns: ColumnDef<{}>[] = schema?.map(({ name, type }: { name: string; type: string }) => {
@@ -122,7 +118,10 @@ export function TablesViewer({ table: selectedTable }: Props) {
         const keysSchema = Object.keys(mudTableConfig?.key_schema || {});
         const keyTuple = keysSchema.map((key) => row.getValue(key));
         const value = row.getValue(name);
-        if ((selectedTable && (internalTableNames as string[]).includes(selectedTable)) || keysSchema.includes(name)) {
+        if (
+          (selectedTableId && (internalTableNames as string[]).includes(selectedTableId)) ||
+          keysSchema.includes(name)
+        ) {
           return value?.toString();
         }
 
@@ -140,20 +139,14 @@ export function TablesViewer({ table: selectedTable }: Props) {
       },
     },
     onSortingChange: setSorting,
-    onColumnFiltersChange: setColumnFilters,
     getCoreRowModel: getCoreRowModel(),
     getPaginationRowModel: getPaginationRowModel(),
     getSortedRowModel: getSortedRowModel(),
     getFilteredRowModel: getFilteredRowModel(),
-    onColumnVisibilityChange: setColumnVisibility,
-    onRowSelectionChange: setRowSelection,
     onGlobalFilterChange: setGlobalFilter,
     globalFilterFn: "includesString",
     state: {
       sorting,
-      columnFilters,
-      columnVisibility,
-      rowSelection,
       globalFilter,
     },
   });
@@ -171,7 +164,7 @@ export function TablesViewer({ table: selectedTable }: Props) {
       <div className="flex items-center justify-between gap-4 pb-4">
         <Input
           placeholder="Filter all columns..."
-          value={globalFilter ?? ""}
+          value={globalFilter}
           onChange={(event) => table.setGlobalFilter(event.target.value)}
           className="max-w-sm rounded border px-2 py-1"
         />