@carlonicora/nextjs-jsonapi 6.32.1 → 6.33.0

package/src/components/tables/ContentListTable.tsx

@@ -1,18 +1,34 @@
 "use client";
 import "../../client";
 
-import { ExpandedState, flexRender, getCoreRowModel, getExpandedRowModel, useReactTable } from "@tanstack/react-table";
+import {
+  ExpandedState,
+  flexRender,
+  getCoreRowModel,
+  getExpandedRowModel,
+  getSortedRowModel,
+  SortingState,
+  TableState,
+  useReactTable,
+} from "@tanstack/react-table";
 
 import { cn } from "@/index";
 import { ChevronLeft, ChevronRight, Loader2 } from "lucide-react";
 import { useTranslations } from "next-intl";
 import React, { ReactNode, memo, useMemo, useState } from "react";
-import { DataListRetriever, TableContent, useTableGenerator } from "../../hooks";
+import { DataListRetriever, TableContent, useListSortParam, useTableGenerator } from "../../hooks";
 import { ModuleWithPermissions } from "../../permissions";
 import { Button, Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow } from "../../shadcnui";
 import { useIsMobile } from "../../utils/use-mobile";
 import { MicroLabel } from "../typography";
 import { ContentTableSearch } from "./ContentTableSearch";
+import { SortableHeader } from "./SortableHeader";
+import { nextSortValue, sortFieldsOf, sortStateFor } from "./sorting";
+
+/** Column `meta` read by the table: cell classes and, for a sortable column, the fields it sorts by. */
+type ColumnMeta = { className?: string; sortFields?: string[] };
+
+const ARIA_SORT = { asc: "ascending", desc: "descending" } as const;
 
 const EMPTY_ARRAY: any[] = [];
 
@@ -76,6 +92,20 @@ type ContentListTableProps = {
    * toggles it via `row.getToggleExpandedHandler()`.
    */
   renderExpandedRow?: (rowData: any) => ReactNode;
+  /**
+   * Where a sortable column (`enableSorting: true`) sorts. `"server"` (default): a
+   * header click sets the retriever's sort and the API orders the whole list.
+   * `"client"`: for small, fully loaded tables only; the loaded rows are sorted in
+   * the browser and the sort is kept in the page address under `sortKey`.
+   */
+  sortMode?: "server" | "client";
+  /** Address key of the sort in `sortMode="client"` (`sort[<sortKey>]`). Required in client mode. */
+  sortKey?: string;
+  /**
+   * Client mode only: sorts the loaded items itself (grouped tables that sort inside
+   * their groups). Without it, rows are sorted by the column's accessor.
+   */
+  clientSort?: <T>(rows: T[], sort: string | undefined) => T[];
 };
 
 type CellRenderer = (context: unknown) => ReactNode;
@@ -123,8 +153,19 @@ export const ContentListTable = memo(function ContentListTable(props: ContentLis
     if (data.isLoaded) setPendingDirection(null);
   }, [data.isLoaded]);
 
+  const isClientSort = props.sortMode === "client";
+  const clientSortParam = useListSortParam({ sortKey: props.sortKey ?? "" });
+  const activeSort = isClientSort ? clientSortParam.sort : data.sort;
+  const { clientSort } = props;
+
+  const sourceData = data?.data ?? EMPTY_ARRAY;
+  const rowsToRender = useMemo(
+    () => (isClientSort && clientSort ? clientSort(sourceData, activeSort) : sourceData),
+    [isClientSort, clientSort, sourceData, activeSort],
+  );
+
   const { data: tableData, columns: tableColumns } = useTableGenerator(props.tableGeneratorType, {
-    data: data?.data ?? EMPTY_ARRAY,
+    data: rowsToRender,
     fields: fields,
     checkedIds: checkedIds,
     toggleId: toggleId,
@@ -144,10 +185,33 @@ export const ContentListTable = memo(function ContentListTable(props: ContentLis
     [fields],
   );
 
+  // Client mode without `clientSort`: TanStack sorts the loaded rows by the column the
+  // address sort names. Server mode never sorts rows: the retriever owns the order.
+  const clientSorting = useMemo((): SortingState | undefined => {
+    if (!isClientSort || clientSort || !activeSort) return undefined;
+    for (const column of tableColumns as Array<{ id?: string; accessorKey?: string; meta?: unknown }>) {
+      const id = column.id ?? column.accessorKey;
+      if (!id) continue;
+      const direction = sortStateFor(activeSort, sortFieldsOf({ id, columnDef: { meta: column.meta } }));
+      if (direction) return [{ id, desc: direction === "desc" }];
+    }
+    return undefined;
+  }, [isClientSort, clientSort, activeSort, tableColumns]);
+
+  const expansionEnabled = !!props.renderExpandedRow || !!props.expandable;
+  const tableState: Partial<TableState> | undefined =
+    expansionEnabled || isClientSort
+      ? {
+          ...(expansionEnabled && { expanded }),
+          ...(isClientSort && { sorting: clientSorting ?? [] }),
+        }
+      : undefined;
+
   const table = useReactTable({
     data: tableData,
     columns: tableColumns,
     getCoreRowModel: getCoreRowModel(),
+    ...(isClientSort ? { getSortedRowModel: getSortedRowModel(), manualSorting: false } : { manualSorting: true }),
     // Pagination is server-side (the data retriever), never TanStack's. Left on,
     // every core-row-model rebuild queues resetPageIndex -> setState -> re-render,
     // and the table generators rebuild their columns on every render, so it never
@@ -160,14 +224,13 @@ export const ContentListTable = memo(function ContentListTable(props: ContentLis
       getRowId: (row: TableContent<any>, index: number) => row.jsonApiData?.id ?? String(index),
       getRowCanExpand: () => true,
       onExpandedChange: setExpanded,
-      state: { expanded },
     }),
     ...(props.expandable && {
       getExpandedRowModel: getExpandedRowModel(),
       getSubRows: props.getSubRows,
       onExpandedChange: setExpanded,
-      state: { expanded },
     }),
+    ...(tableState && { state: tableState }),
     initialState: {
       columnVisibility,
     },
@@ -291,10 +354,45 @@ export const ContentListTable = memo(function ContentListTable(props: ContentLis
               table.getHeaderGroups().map((headerGroup) => (
                 <TableRow key={headerGroup.id}>
                   {headerGroup.headers.map((header) => {
-                    const meta = header.column.columnDef.meta as { className?: string } | undefined;
+                    const meta = header.column.columnDef.meta as ColumnMeta | undefined;
+                    const label = header.isPlaceholder
+                      ? null
+                      : flexRender(header.column.columnDef.header, header.getContext());
+                    // Only an explicit `true` opts a column in: TanStack defaults a missing key to sortable.
+                    // A server-mode retriever without `setSort` (hand-built) cannot sort: plain header.
+                    if (
+                      header.isPlaceholder ||
+                      header.column.columnDef.enableSorting !== true ||
+                      (!isClientSort && !data.setSort)
+                    ) {
+                      return (
+                        <TableHead key={header.id} className={meta?.className}>
+                          {label}
+                        </TableHead>
+                      );
+                    }
+                    const sortFields = sortFieldsOf(header.column);
+                    const direction = sortStateFor(activeSort, sortFields);
+                    const defaultDirection =
+                      !isClientSort && !activeSort ? sortStateFor(data.defaultSort, sortFields) : undefined;
+                    const onToggle = () => {
+                      const next = nextSortValue(activeSort, sortFields);
+                      if (isClientSort) clientSortParam.setSort(next);
+                      else data.setSort?.(next);
+                    };
                     return (
-                      <TableHead key={header.id} className={meta?.className}>
-                        {header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext())}
+                      <TableHead
+                        key={header.id}
+                        className={meta?.className}
+                        aria-sort={direction ? ARIA_SORT[direction] : "none"}
+                      >
+                        <SortableHeader
+                          columnId={header.column.id}
+                          label={label}
+                          direction={direction}
+                          defaultDirection={defaultDirection}
+                          onToggle={onToggle}
+                        />
                       </TableHead>
                     );
                   })}
@@ -318,7 +416,7 @@ export const ContentListTable = memo(function ContentListTable(props: ContentLis
                           className={`group ${onRowClick ? "hover:bg-muted/50 cursor-pointer" : ""}`}
                         >
                           {row.getVisibleCells().map((cell) => {
-                            const meta = cell.column.columnDef.meta as { className?: string } | undefined;
+                            const meta = cell.column.columnDef.meta as ColumnMeta | undefined;
                             return (
                               <TableCell key={cell.id} className={meta?.className}>
                                 {renderCell(cell.column.columnDef.cell, cell.getContext())}
@@ -345,7 +443,7 @@ export const ContentListTable = memo(function ContentListTable(props: ContentLis
                       className={`group ${onRowClick ? "hover:bg-muted/50 cursor-pointer" : ""}`}
                     >
                       {row.getVisibleCells().map((cell) => {
-                        const meta = cell.column.columnDef.meta as { className?: string } | undefined;
+                        const meta = cell.column.columnDef.meta as ColumnMeta | undefined;
                         return (
                           <TableCell key={cell.id} className={meta?.className}>
                             {renderCell(cell.column.columnDef.cell, cell.getContext())}

package/src/components/tables/SortableHeader.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { ArrowDown, ArrowUp, ArrowUpDown } from "lucide-react";
+import { ReactNode } from "react";
+import { Button } from "../../shadcnui";
+import { SortDirection } from "./sorting";
+
+/**
+ * The label of a sortable column header: a button that toggles the column's sort.
+ *
+ * `direction` is the sort the user chose (primary colour). `defaultDirection` is
+ * the list's display-only default order, shown as a muted arrow while no sort is
+ * chosen. The enclosing `<TableHead>` carries `aria-sort`.
+ */
+export function SortableHeader(props: {
+  columnId: string;
+  label: ReactNode;
+  direction?: SortDirection;
+  defaultDirection?: SortDirection;
+  onToggle: () => void;
+}) {
+  const shown = props.direction ?? props.defaultDirection;
+  const Icon = shown === "asc" ? ArrowUp : shown === "desc" ? ArrowDown : ArrowUpDown;
+
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="xs"
+      className={props.direction ? "text-primary" : "text-muted-foreground"}
+      data-testid={`list-sort-header-${props.columnId}`}
+      onClick={props.onToggle}
+    >
+      {props.label}
+      <Icon
+        data-testid="list-sort-icon"
+        data-direction={shown ?? "none"}
+        className={props.direction ? undefined : "text-muted-foreground"}
+        aria-hidden="true"
+      />
+    </Button>
+  );
+}

package/src/components/tables/__tests__/ContentListTable.rendering.spec.tsx

@@ -52,6 +52,7 @@ function createMockDataRetriever(overrides: Partial<DataListRetriever<any>> = {}
     removeAdditionalParameter: vi.fn(),
     setRefreshedElement: vi.fn(),
     removeElement: vi.fn(),
+    setSort: vi.fn(),
     isSearch: false,
     ...overrides,
   };

package/src/components/tables/__tests__/ContentListTable.sort.spec.tsx

@@ -0,0 +1,273 @@
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ContentListTable } from "../ContentListTable";
+
+// The columns the mocked table generator returns. Each test sets them; the
+// generator maps every data item to a row that also carries `jsonApiData`, as
+// the sibling ContentListTable specs do.
+const mockColumns = vi.hoisted(() => ({ columns: [] as any[] }));
+
+vi.mock("../../../hooks", async () => {
+  const actual = await vi.importActual("../../../hooks");
+  return {
+    ...actual,
+    useTableGenerator: vi.fn((_type: any, params: any) => ({
+      data: params.data.map((item: any) => ({ ...item, jsonApiData: item })),
+      columns: mockColumns.columns,
+    })),
+  };
+});
+
+vi.mock("../ContentTableSearch", () => ({
+  ContentTableSearch: () => <div data-testid="content-table-search">Search</div>,
+}));
+
+const nameColumn = (enableSorting?: boolean) => ({
+  id: "name",
+  header: "Name",
+  accessorKey: "name",
+  cell: ({ row }: any) => row.original.name,
+  ...(enableSorting !== undefined && { enableSorting }),
+});
+
+const updatedAtColumn = {
+  id: "updatedAt",
+  header: "Updated",
+  accessorKey: "updatedAt",
+  cell: ({ row }: any) => row.original.updatedAt,
+  enableSorting: true,
+};
+
+const rows = [
+  { id: "1", name: "Bravo", updatedAt: "2" },
+  { id: "2", name: "Alpha", updatedAt: "3" },
+  { id: "3", name: "Charlie", updatedAt: "1" },
+];
+
+const retriever = (overrides: Record<string, any> = {}) =>
+  ({
+    data: rows,
+    isLoaded: true,
+    ready: true,
+    next: undefined,
+    previous: undefined,
+    refresh: vi.fn(),
+    addAdditionalParameter: vi.fn(),
+    removeAdditionalParameter: vi.fn(),
+    setRefreshedElement: vi.fn(),
+    removeElement: vi.fn(),
+    search: vi.fn(),
+    setReady: vi.fn(),
+    setSort: vi.fn(),
+    isSearch: false,
+    ...overrides,
+  }) as any;
+
+const mockModule = { name: "things", icon: undefined } as any;
+
+const renderedNames = () =>
+  screen
+    .getAllByRole("row")
+    .slice(1)
+    .map((row) => row.textContent);
+
+const headCell = (columnId: string) => screen.getByTestId(`list-sort-header-${columnId}`).closest("th")!;
+
+describe("ContentListTable sortable headers", () => {
+  beforeEach(() => {
+    window.history.replaceState(null, "", "/things");
+  });
+
+  afterEach(() => {
+    window.history.replaceState(null, "", "/");
+    vi.restoreAllMocks();
+    mockColumns.columns = [];
+  });
+
+  it("renders a sort button only for a column with enableSorting: true", () => {
+    mockColumns.columns = [nameColumn(true)];
+    render(<ContentListTable data={retriever()} fields={["name"]} tableGeneratorType={mockModule} />);
+    expect(screen.getByTestId("list-sort-header-name")).toBeInTheDocument();
+  });
+
+  it("renders no sort button when the column omits enableSorting", () => {
+    mockColumns.columns = [nameColumn()];
+    render(<ContentListTable data={retriever()} fields={["name"]} tableGeneratorType={mockModule} />);
+    expect(screen.queryByTestId("list-sort-header-name")).toBeNull();
+    expect(screen.getByText("Name").closest("th")).not.toHaveAttribute("aria-sort");
+  });
+
+  it("renders a plain header in server mode when a hand-built retriever has no setSort", () => {
+    mockColumns.columns = [nameColumn(true)];
+    render(
+      <ContentListTable data={retriever({ setSort: undefined })} fields={["name"]} tableGeneratorType={mockModule} />,
+    );
+    expect(screen.queryByTestId("list-sort-header-name")).toBeNull();
+    expect(screen.getByText("Name").closest("th")).not.toHaveAttribute("aria-sort");
+  });
+
+  it("still sorts in client mode when the retriever has no setSort", () => {
+    mockColumns.columns = [nameColumn(true)];
+    render(
+      <ContentListTable
+        data={retriever({ setSort: undefined })}
+        fields={["name"]}
+        tableGeneratorType={mockModule}
+        sortMode="client"
+        sortKey="things"
+      />,
+    );
+    fireEvent.click(screen.getByTestId("list-sort-header-name"));
+    expect(renderedNames()).toEqual(["Alpha", "Bravo", "Charlie"]);
+  });
+
+  it("renders no sort button when enableSorting is false", () => {
+    mockColumns.columns = [nameColumn(false)];
+    render(<ContentListTable data={retriever()} fields={["name"]} tableGeneratorType={mockModule} />);
+    expect(screen.queryByTestId("list-sort-header-name")).toBeNull();
+  });
+
+  it("cycles none -> asc -> desc -> none through data.setSort, with aria-sort following", () => {
+    mockColumns.columns = [nameColumn(true)];
+    const setSort = vi.fn();
+
+    const { rerender } = render(
+      <ContentListTable data={retriever({ setSort })} fields={["name"]} tableGeneratorType={mockModule} />,
+    );
+    expect(headCell("name")).toHaveAttribute("aria-sort", "none");
+    fireEvent.click(screen.getByTestId("list-sort-header-name"));
+    expect(setSort).toHaveBeenLastCalledWith("name");
+
+    rerender(
+      <ContentListTable
+        data={retriever({ setSort, sort: "name" })}
+        fields={["name"]}
+        tableGeneratorType={mockModule}
+      />,
+    );
+    expect(headCell("name")).toHaveAttribute("aria-sort", "ascending");
+    fireEvent.click(screen.getByTestId("list-sort-header-name"));
+    expect(setSort).toHaveBeenLastCalledWith("-name");
+
+    rerender(
+      <ContentListTable
+        data={retriever({ setSort, sort: "-name" })}
+        fields={["name"]}
+        tableGeneratorType={mockModule}
+      />,
+    );
+    expect(headCell("name")).toHaveAttribute("aria-sort", "descending");
+    fireEvent.click(screen.getByTestId("list-sort-header-name"));
+    expect(setSort).toHaveBeenLastCalledWith(null);
+    expect(setSort).toHaveBeenCalledTimes(3);
+  });
+
+  it("does not reorder rows in server mode", () => {
+    mockColumns.columns = [nameColumn(true)];
+    render(<ContentListTable data={retriever({ sort: "name" })} fields={["name"]} tableGeneratorType={mockModule} />);
+    expect(renderedNames()).toEqual(["Bravo", "Alpha", "Charlie"]);
+  });
+
+  it("shows the defaultSort column with a muted arrow and aria-sort none", () => {
+    mockColumns.columns = [nameColumn(true), updatedAtColumn];
+    render(
+      <ContentListTable
+        data={retriever({ defaultSort: "-updatedAt" })}
+        fields={["name", "updatedAt"]}
+        tableGeneratorType={mockModule}
+      />,
+    );
+
+    expect(headCell("updatedAt")).toHaveAttribute("aria-sort", "none");
+    const icon = within(screen.getByTestId("list-sort-header-updatedAt")).getByTestId("list-sort-icon");
+    expect(icon).toHaveAttribute("data-direction", "desc");
+    expect(icon.getAttribute("class")).toContain("text-muted-foreground");
+    expect(screen.getByTestId("list-sort-header-updatedAt").className).toContain("text-muted-foreground");
+
+    expect(within(screen.getByTestId("list-sort-header-name")).getByTestId("list-sort-icon")).toHaveAttribute(
+      "data-direction",
+      "none",
+    );
+  });
+
+  it("drops the muted default arrow once a sort is chosen", () => {
+    mockColumns.columns = [nameColumn(true), updatedAtColumn];
+    render(
+      <ContentListTable
+        data={retriever({ defaultSort: "-updatedAt", sort: "name" })}
+        fields={["name", "updatedAt"]}
+        tableGeneratorType={mockModule}
+      />,
+    );
+
+    expect(within(screen.getByTestId("list-sort-header-updatedAt")).getByTestId("list-sort-icon")).toHaveAttribute(
+      "data-direction",
+      "none",
+    );
+    expect(screen.getByTestId("list-sort-header-name").className).toContain("text-primary");
+  });
+
+  it("sorts the loaded rows in the browser in client mode, without calling setSort", () => {
+    mockColumns.columns = [nameColumn(true)];
+    const setSort = vi.fn();
+    render(
+      <ContentListTable
+        data={retriever({ setSort })}
+        fields={["name"]}
+        tableGeneratorType={mockModule}
+        sortMode="client"
+        sortKey="things"
+      />,
+    );
+    expect(renderedNames()).toEqual(["Bravo", "Alpha", "Charlie"]);
+
+    fireEvent.click(screen.getByTestId("list-sort-header-name"));
+    expect(renderedNames()).toEqual(["Alpha", "Bravo", "Charlie"]);
+    expect(headCell("name")).toHaveAttribute("aria-sort", "ascending");
+    expect(new URLSearchParams(window.location.search).get("sort[things]")).toBe("name");
+
+    fireEvent.click(screen.getByTestId("list-sort-header-name"));
+    expect(renderedNames()).toEqual(["Charlie", "Bravo", "Alpha"]);
+    expect(headCell("name")).toHaveAttribute("aria-sort", "descending");
+
+    fireEvent.click(screen.getByTestId("list-sort-header-name"));
+    expect(renderedNames()).toEqual(["Bravo", "Alpha", "Charlie"]);
+    expect(headCell("name")).toHaveAttribute("aria-sort", "none");
+
+    expect(setSort).not.toHaveBeenCalled();
+  });
+
+  it("restores a client sort from the address on mount", () => {
+    window.history.replaceState(null, "", "/things?sort%5Bthings%5D=-name");
+    mockColumns.columns = [nameColumn(true)];
+    render(
+      <ContentListTable
+        data={retriever()}
+        fields={["name"]}
+        tableGeneratorType={mockModule}
+        sortMode="client"
+        sortKey="things"
+      />,
+    );
+    expect(renderedNames()).toEqual(["Charlie", "Bravo", "Alpha"]);
+  });
+
+  it("renders the order clientSort returns, called with (rows, sort)", () => {
+    window.history.replaceState(null, "", "/things?sort%5Bthings%5D=name");
+    mockColumns.columns = [nameColumn(true)];
+    const clientSort = vi.fn((items: any[]) => [items[2], items[0], items[1]]);
+    render(
+      <ContentListTable
+        data={retriever()}
+        fields={["name"]}
+        tableGeneratorType={mockModule}
+        sortMode="client"
+        sortKey="things"
+        clientSort={clientSort}
+      />,
+    );
+
+    expect(clientSort).toHaveBeenLastCalledWith(rows, "name");
+    expect(renderedNames()).toEqual(["Charlie", "Bravo", "Alpha"]);
+  });
+});

package/src/components/tables/__tests__/sorting.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { nextSortValue, sortFieldsOf, sortStateFor } from "../sorting";
+
+describe("nextSortValue", () => {
+  it("starts ascending when the column is not sorted", () => {
+    expect(nextSortValue(undefined, ["name"])).toBe("name");
+  });
+
+  it("goes from ascending to descending", () => {
+    expect(nextSortValue("name", ["name"])).toBe("-name");
+  });
+
+  it("clears the sort after descending", () => {
+    expect(nextSortValue("-name", ["name"])).toBeNull();
+  });
+
+  it("starts ascending when another column holds the sort", () => {
+    expect(nextSortValue("-createdAt", ["name"])).toBe("name");
+  });
+
+  it("writes every field of a composite column", () => {
+    expect(nextSortValue(undefined, ["lastName", "firstName"])).toBe("lastName,firstName");
+    expect(nextSortValue("lastName,firstName", ["lastName", "firstName"])).toBe("-lastName,-firstName");
+    expect(nextSortValue("-lastName,-firstName", ["lastName", "firstName"])).toBeNull();
+  });
+});
+
+describe("sortFieldsOf", () => {
+  it("uses meta.sortFields when the column declares them", () => {
+    expect(sortFieldsOf({ id: "name", columnDef: { meta: { sortFields: ["lastName", "firstName"] } } })).toEqual([
+      "lastName",
+      "firstName",
+    ]);
+  });
+
+  it("falls back to the column id", () => {
+    expect(sortFieldsOf({ id: "name", columnDef: { meta: { className: "w-10" } } })).toEqual(["name"]);
+    expect(sortFieldsOf({ id: "name", columnDef: {} })).toEqual(["name"]);
+  });
+
+  it("returns no field for a column without id or sortFields", () => {
+    expect(sortFieldsOf({ columnDef: {} })).toEqual([]);
+  });
+});
+
+describe("sortStateFor", () => {
+  it("reads a descending composite sort", () => {
+    expect(sortStateFor("-lastName,-firstName", ["lastName", "firstName"])).toBe("desc");
+  });
+
+  it("reads an ascending sort", () => {
+    expect(sortStateFor("name", ["name"])).toBe("asc");
+  });
+
+  it("returns undefined when the sort belongs to another column or is absent", () => {
+    expect(sortStateFor("-createdAt", ["name"])).toBeUndefined();
+    expect(sortStateFor(undefined, ["name"])).toBeUndefined();
+    expect(sortStateFor("lastName", ["lastName", "firstName"])).toBeUndefined();
+    expect(sortStateFor("name", [])).toBeUndefined();
+  });
+});

package/src/components/tables/cells/cell.date.tsx

@@ -6,7 +6,14 @@ function DateCell({ date }: { date: Date }) {
   return <span className="text-muted-foreground text-xs">{format(date, "dateMedium")}</span>;
 }
 
-export const cellDate = (params: { name: string; title: string }): ColumnDef<any> => {
+export const cellDate = (params: {
+  name: string;
+  title: string;
+  /** Opt-in: the header sorts the list by this column. */
+  sortable?: boolean;
+  /** Stored fields the column sorts by, when they differ from `name`. */
+  sortFields?: string[];
+}): ColumnDef<any> => {
   return {
     id: params.name,
     accessorKey: params.name,
@@ -16,7 +23,8 @@ export const cellDate = (params: { name: string; title: string }): ColumnDef<any
       if (!date) return null;
       return <DateCell date={date} />;
     },
-    enableSorting: false,
+    enableSorting: params.sortable === true,
+    ...(params.sortFields && { meta: { sortFields: params.sortFields } }),
     enableHiding: false,
   };
 };

package/src/components/tables/cells/cell.dateTime.tsx

@@ -6,7 +6,14 @@ function DateTimeCell({ date }: { date: Date }) {
   return <span className="text-muted-foreground text-xs">{format(date, "dateTimeMedium")}</span>;
 }
 
-export const cellDateTime = (params: { name: string; title: string }): ColumnDef<any> => {
+export const cellDateTime = (params: {
+  name: string;
+  title: string;
+  /** Opt-in: the header sorts the list by this column. */
+  sortable?: boolean;
+  /** Stored fields the column sorts by, when they differ from `name`. */
+  sortFields?: string[];
+}): ColumnDef<any> => {
   return {
     id: params.name,
     accessorKey: params.name,
@@ -16,7 +23,8 @@ export const cellDateTime = (params: { name: string; title: string }): ColumnDef
       if (!date) return null;
       return <DateTimeCell date={date} />;
     },
-    enableSorting: false,
+    enableSorting: params.sortable === true,
+    ...(params.sortFields && { meta: { sortFields: params.sortFields } }),
     enableHiding: false,
   };
 };

package/src/components/tables/cells/cell.link.tsx

@@ -6,13 +6,18 @@ export const cellLink = <T,>(params: {
   name: string;
   title: string;
   generateUrl: (id: string) => string;
+  /** Opt-in: the header sorts the list by this column. */
+  sortable?: boolean;
+  /** Stored fields the column sorts by, when they differ from `name`. */
+  sortFields?: string[];
 }): ColumnDef<T> => {
   return {
     id: params.name,
     accessorKey: params.name,
     header: params.title,
     cell: ({ row }) => <Link href={params.generateUrl(row.getValue(params.id))}>{row.getValue(params.name)}</Link>,
-    enableSorting: false,
+    enableSorting: params.sortable === true,
+    ...(params.sortFields && { meta: { sortFields: params.sortFields } }),
     enableHiding: false,
   };
 };

package/src/components/tables/cells/cell.text.tsx

@@ -1,12 +1,21 @@
 import { ColumnDef } from "@tanstack/react-table";
 
-export const cellText = (params: { id: string; name: string; title: string }): ColumnDef<any> => {
+export const cellText = (params: {
+  id: string;
+  name: string;
+  title: string;
+  /** Opt-in: the header sorts the list by this column. */
+  sortable?: boolean;
+  /** Stored fields the column sorts by, when they differ from `name`. */
+  sortFields?: string[];
+}): ColumnDef<any> => {
   return {
     id: params.name,
     accessorKey: params.name,
     header: params.title,
     cell: ({ row }) => row.getValue(params.name),
-    enableSorting: false,
+    enableSorting: params.sortable === true,
+    ...(params.sortFields && { meta: { sortFields: params.sortFields } }),
     enableHiding: false,
   };
 };