@carlonicora/nextjs-jsonapi 6.32.2 → 6.33.0

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,
   };
 };

package/src/components/tables/index.ts

@@ -1,3 +1,5 @@
 export * from "./cells";
 export * from "./ContentListTable";
 export * from "./ContentTableSearch";
+export * from "./SortableHeader";
+export * from "./sorting";

package/src/components/tables/sorting.ts

@@ -0,0 +1,41 @@
+/** Direction of a column sort. */
+export type SortDirection = "asc" | "desc";
+
+/**
+ * The fields a column sorts by: its `meta.sortFields` when declared (a column
+ * built from several stored fields, or whose stored property differs from its
+ * id), otherwise its id.
+ */
+export function sortFieldsOf(column: { id?: string; columnDef: { meta?: unknown } }): string[] {
+  const meta = column.columnDef.meta as { sortFields?: unknown } | undefined;
+  if (Array.isArray(meta?.sortFields) && meta.sortFields.length > 0) {
+    return meta.sortFields.filter((field): field is string => typeof field === "string");
+  }
+  return column.id ? [column.id] : [];
+}
+
+/**
+ * The direction `sort` (JSON:API wire format) gives a column sorting by `fields`,
+ * or `undefined` when `sort` is about another column or absent.
+ */
+export function sortStateFor(sort: string | undefined, fields: string[]): SortDirection | undefined {
+  if (!sort || fields.length === 0) return undefined;
+  if (sort === fields.join(",")) return "asc";
+  if (sort === fields.map((field) => `-${field}`).join(",")) return "desc";
+  return undefined;
+}
+
+/**
+ * The sort a header click sets: none → ascending → descending → none.
+ * Returns `null` to clear the sort.
+ */
+export function nextSortValue(current: string | undefined, fields: string[]): string | null {
+  switch (sortStateFor(current, fields)) {
+    case undefined:
+      return fields.join(",");
+    case "asc":
+      return fields.map((field) => `-${field}`).join(",");
+    case "desc":
+      return null;
+  }
+}

package/src/features/billing/stripe-coupon/components/lists/CouponCodesList.tsx

@@ -25,6 +25,8 @@ export function CouponCodesList({ couponId }: CouponCodesListProps) {
     retriever: (params) => StripeCouponCodeService.listByCoupon({ ...params, couponId }),
     retrieverParams: {},
     module: Modules.StripeCouponCode,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "createdAt",
   });
 
   // Switching "Apply automatically" on one code clears it on the others in the

package/src/features/billing/stripe-coupon/components/lists/CouponsList.tsx

@@ -31,6 +31,8 @@ export function CouponsList({ fullWidth }: CouponsListProps = {}) {
     retriever: (params) => StripeCouponService.listCoupons(params),
     retrieverParams: {},
     module: Modules.StripeCoupon,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "-updatedAt",
   });
 
   // Renames and code changes happen on the detail page, so the list has to

package/src/features/billing/stripe-coupon/data/stripe-coupon-code.service.ts

@@ -18,6 +18,8 @@ export class StripeCouponCodeService extends AbstractService {
     couponId: string;
     next?: NextRef;
     prev?: PreviousRef;
+    /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+    sort?: string;
   }): Promise<StripeCouponCodeInterface[]> {
     const endpoint = new EndpointCreator({
       endpoint: Modules.StripeCoupon,
@@ -25,6 +27,8 @@ export class StripeCouponCodeService extends AbstractService {
       childEndpoint: Modules.StripeCouponCode,
     });
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi({
       type: Modules.StripeCouponCode,
       method: HttpMethod.GET,

package/src/features/billing/stripe-coupon/data/stripe-coupon.service.ts

@@ -10,11 +10,17 @@ export class StripeCouponService extends AbstractService {
   /**
    * List all coupons with their codes (admin)
    */
-  static async listCoupons(params?: { next?: NextRef; prev?: PreviousRef }): Promise<StripeCouponInterface[]> {
+  static async listCoupons(params?: {
+    next?: NextRef;
+    prev?: PreviousRef;
+    sort?: string;
+  }): Promise<StripeCouponInterface[]> {
     const endpoint = new EndpointCreator({
       endpoint: Modules.StripeCoupon,
     });
 
+    if (params?.sort) endpoint.addAdditionalParam("sort", params?.sort);
+
     return this.callApi({
       type: Modules.StripeCoupon,
       method: HttpMethod.GET,

package/src/features/billing/stripe-coupon/hooks/__tests__/useStripeCouponCodeTableStructure.sort.spec.tsx

@@ -0,0 +1,30 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { StripeCouponCodeFields } from "../../data/stripe-coupon-code.fields";
+import { useStripeCouponCodeTableStructure } from "../useStripeCouponCodeTableStructure";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key, useLocale: () => "en" }));
+vi.mock("../../../contexts/CouponContext", () => ({ useCouponContext: () => ({}) }));
+
+/** Spec row A21: code, expiresAt, automatic, places (timesRedeemed); status is derived. Only an explicit `enableSorting: true` opts a column in (call C3). */
+describe("useStripeCouponCodeTableStructure sorting", () => {
+  it("opts in exactly the row's sortable columns", () => {
+    const { result } = renderHook(() =>
+      useStripeCouponCodeTableStructure({ data: [], fields: Object.values(StripeCouponCodeFields) as any }),
+    );
+    const columns = result.current.columns as any[];
+    const sortable = columns.filter((column) => column.enableSorting === true).map((column) => column.id);
+    expect(sortable.sort()).toEqual(["automatic", "code", "expiresAt", "places"]);
+  });
+
+  it("maps the columns whose key differs from the stored property (call C4)", () => {
+    const { result } = renderHook(() =>
+      useStripeCouponCodeTableStructure({ data: [], fields: Object.values(StripeCouponCodeFields) as any }),
+    );
+    const columns = result.current.columns as any[];
+    const sortFields = Object.fromEntries(
+      columns.filter((column) => column.meta?.sortFields).map((column) => [column.id, column.meta.sortFields]),
+    );
+    expect(sortFields).toEqual({ places: ["timesRedeemed"] });
+  });
+});

package/src/features/billing/stripe-coupon/hooks/__tests__/useStripeCouponTableStructure.sort.spec.tsx

@@ -0,0 +1,33 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { StripeCouponFields } from "../../data/stripe-coupon.fields";
+import { useStripeCouponTableStructure } from "../useStripeCouponTableStructure";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key, useLocale: () => "en" }));
+
+/** Spec row A20: name, status (valid), places, discount; codes (a count) is not sortable. Only an explicit `enableSorting: true` opts a column in (call C3). */
+describe("useStripeCouponTableStructure sorting", () => {
+  it("opts in exactly the row's sortable columns", () => {
+    const { result } = renderHook(() =>
+      useStripeCouponTableStructure({ data: [], fields: Object.values(StripeCouponFields) as any }),
+    );
+    const columns = result.current.columns as any[];
+    const sortable = columns.filter((column) => column.enableSorting === true).map((column) => column.id);
+    expect(sortable.sort()).toEqual(["discount", "name", "places", "status"]);
+  });
+
+  it("maps the columns whose key differs from the stored property (call C4)", () => {
+    const { result } = renderHook(() =>
+      useStripeCouponTableStructure({ data: [], fields: Object.values(StripeCouponFields) as any }),
+    );
+    const columns = result.current.columns as any[];
+    const sortFields = Object.fromEntries(
+      columns.filter((column) => column.meta?.sortFields).map((column) => [column.id, column.meta.sortFields]),
+    );
+    expect(sortFields).toEqual({
+      discount: ["discountType", "percentOff", "amountOff"],
+      places: ["timesRedeemed", "maxRedemptions"],
+      status: ["valid"],
+    });
+  });
+});