@carlonicora/nextjs-jsonapi 6.32.1 → 6.33.0

package/src/features/email-automation/components/lists/EmailAutomationsList.tsx

@@ -31,6 +31,8 @@ export function EmailAutomationsList({ fullWidth }: EmailAutomationsListProps =
     retriever: (params) => EmailAutomationService.findMany(params),
     retrieverParams: {},
     module: Modules.EmailAutomation,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "-updatedAt",
   });
 
   // The trigger column shows the label the app declares, not the stored key.

package/src/features/email-automation/data/EmailAutomationService.ts

@@ -8,7 +8,9 @@ import { EmailAutomationInput, EmailAutomationInterface } from "./EmailAutomatio
 import { EmailAutomationTriggerInterface } from "./EmailAutomationTriggerInterface";
 
 export class EmailAutomationService extends AbstractService {
-  static async findMany(params: { next?: NextRef; previous?: PreviousRef } = {}): Promise<EmailAutomationInterface[]> {
+  static async findMany(
+    params: { next?: NextRef; previous?: PreviousRef; sort?: string } = {},
+  ): Promise<EmailAutomationInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.EmailAutomation });
 
     if (Modules.EmailAutomation.inclusions?.lists?.fields)
@@ -16,6 +18,8 @@ export class EmailAutomationService extends AbstractService {
     if (Modules.EmailAutomation.inclusions?.lists?.types)
       endpoint.limitToType(Modules.EmailAutomation.inclusions.lists.types);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi<EmailAutomationInterface[]>({
       type: Modules.EmailAutomation,
       method: HttpMethod.GET,
@@ -90,6 +94,8 @@ export class EmailAutomationService extends AbstractService {
     status?: string;
     next?: NextRef;
     previous?: PreviousRef;
+    /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+    sort?: string;
   }): Promise<EmailAutomationEnrollmentInterface[]> {
     const endpoint = new EndpointCreator({
       endpoint: Modules.EmailAutomation,
@@ -99,6 +105,8 @@ export class EmailAutomationService extends AbstractService {
 
     if (params.status) endpoint.addAdditionalParam("status", params.status);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi<EmailAutomationEnrollmentInterface[]>({
       type: Modules.EmailAutomationEnrollment,
       method: HttpMethod.GET,

package/src/features/email-automation/hooks/__tests__/useEmailAutomationEnrollmentTableStructure.sort.spec.tsx

@@ -0,0 +1,21 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { EmailAutomationEnrollmentFields } from "../../data/email-automation-enrollment.fields";
+import { useEmailAutomationEnrollmentTableStructure } from "../useEmailAutomationEnrollmentTableStructure";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key, useLocale: () => "en" }));
+
+/** Spec row A4: email, name, status, nextSendAt; the computed step and sent count are not sortable. Only an explicit `enableSorting: true` opts a column in (call C3). */
+describe("useEmailAutomationEnrollmentTableStructure sorting", () => {
+  it("opts in exactly the row's sortable columns", () => {
+    const { result } = renderHook(() =>
+      useEmailAutomationEnrollmentTableStructure({
+        data: [],
+        fields: Object.values(EmailAutomationEnrollmentFields) 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(["email", "name", "nextSendAt", "status"]);
+  });
+});

package/src/features/email-automation/hooks/__tests__/useEmailAutomationTableStructure.sort.spec.tsx

@@ -0,0 +1,29 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { EmailAutomationFields } from "../../data/email-automation.fields";
+import { useEmailAutomationTableStructure } from "../useEmailAutomationTableStructure";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key, useLocale: () => "en" }));
+
+/** Spec row A5: name, purpose, trigger, status (isActive); the counts stay unsortable. Only an explicit `enableSorting: true` opts a column in (call C3). */
+describe("useEmailAutomationTableStructure sorting", () => {
+  it("opts in exactly the row's sortable columns", () => {
+    const { result } = renderHook(() =>
+      useEmailAutomationTableStructure({ data: [], fields: Object.values(EmailAutomationFields) 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(["name", "purpose", "status", "trigger"]);
+  });
+
+  it("maps the columns whose key differs from the stored property (call C4)", () => {
+    const { result } = renderHook(() =>
+      useEmailAutomationTableStructure({ data: [], fields: Object.values(EmailAutomationFields) 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({ status: ["isActive"] });
+  });
+});

package/src/features/email-automation/hooks/useEmailAutomationEnrollmentTableStructure.tsx

@@ -47,7 +47,7 @@ export const useEmailAutomationEnrollmentTableStructure: UseTableStructureHook<
         const enrollment: EmailAutomationEnrollmentInterface = row.original.jsonApiData;
         return <span className="text-sm">{enrollment.email}</span>;
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailAutomationEnrollmentFields.name]: () => ({
@@ -58,7 +58,7 @@ export const useEmailAutomationEnrollmentTableStructure: UseTableStructureHook<
         const enrollment: EmailAutomationEnrollmentInterface = row.original.jsonApiData;
         return enrollment.name ? <span className="text-sm">{enrollment.name}</span> : empty;
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailAutomationEnrollmentFields.status]: () => ({
@@ -76,7 +76,7 @@ export const useEmailAutomationEnrollmentTableStructure: UseTableStructureHook<
           </Badge>
         );
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailAutomationEnrollmentFields.currentStep]: () => ({
@@ -103,7 +103,7 @@ export const useEmailAutomationEnrollmentTableStructure: UseTableStructureHook<
           </span>
         );
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailAutomationEnrollmentFields.sentCount]: () => ({

package/src/features/email-automation/hooks/useEmailAutomationTableStructure.tsx

@@ -59,7 +59,7 @@ export const useEmailAutomationTableStructure: UseTableStructureHook<
         const automation: EmailAutomationInterface = row.original.jsonApiData;
         return <Link href={generateUrl({ page: Modules.EmailAutomation, id: automation.id })}>{automation.name}</Link>;
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailAutomationFields.purpose]: () => ({
@@ -78,7 +78,7 @@ export const useEmailAutomationTableStructure: UseTableStructureHook<
           </Badge>
         );
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailAutomationFields.trigger]: () => ({
@@ -90,7 +90,7 @@ export const useEmailAutomationTableStructure: UseTableStructureHook<
         if (!automation.trigger) return <span className="text-muted-foreground text-xs">—</span>;
         return <span className="text-sm">{triggerLabels[automation.trigger] ?? automation.trigger}</span>;
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailAutomationFields.status]: () => ({
@@ -105,7 +105,8 @@ export const useEmailAutomationTableStructure: UseTableStructureHook<
           <Badge variant="softGray">{t("emailAutomations.list.status.off")}</Badge>
         );
       },
-      enableSorting: false,
+      meta: { sortFields: ["isActive"] },
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailAutomationFields.steps]: () =>

package/src/features/email-blast/components/lists/EmailBlastsList.tsx

@@ -32,6 +32,8 @@ export function EmailBlastsList({ fullWidth }: EmailBlastsListProps = {}) {
     retriever: (params) => EmailBlastService.findMany(params),
     retrieverParams: {},
     module: Modules.EmailBlast,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "-updatedAt",
   });
 
   const functions: ReactNode[] = [<EmailBlastEditor key="create-email-blast" />];

package/src/features/email-blast/data/EmailBlastService.ts

@@ -4,13 +4,17 @@ import { EmailBlastAudienceInterface } from "./EmailBlastAudienceInterface";
 import { EmailBlastInput, EmailBlastInterface } from "./EmailBlastInterface";
 
 export class EmailBlastService extends AbstractService {
-  static async findMany(params: { next?: NextRef; previous?: PreviousRef } = {}): Promise<EmailBlastInterface[]> {
+  static async findMany(
+    params: { next?: NextRef; previous?: PreviousRef; sort?: string } = {},
+  ): Promise<EmailBlastInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.EmailBlast });
 
     if (Modules.EmailBlast.inclusions?.lists?.fields)
       endpoint.limitToFields(Modules.EmailBlast.inclusions.lists.fields);
     if (Modules.EmailBlast.inclusions?.lists?.types) endpoint.limitToType(Modules.EmailBlast.inclusions.lists.types);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi<EmailBlastInterface[]>({
       type: Modules.EmailBlast,
       method: HttpMethod.GET,

package/src/features/email-blast/hooks/__tests__/useEmailBlastTableStructure.sort.spec.tsx

@@ -0,0 +1,29 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { EmailBlastFields } from "../../data/email-blast.fields";
+import { useEmailBlastTableStructure } from "../useEmailBlastTableStructure";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key, useLocale: () => "en" }));
+
+/** Spec row A17: every column, the counts mapped to their stored property. Only an explicit `enableSorting: true` opts a column in (call C3). */
+describe("useEmailBlastTableStructure sorting", () => {
+  it("opts in exactly the row's sortable columns", () => {
+    const { result } = renderHook(() =>
+      useEmailBlastTableStructure({ data: [], fields: Object.values(EmailBlastFields) 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(["failed", "purpose", "sent", "sentAt", "status", "subject", "unsubscribed"]);
+  });
+
+  it("maps the columns whose key differs from the stored property (call C4)", () => {
+    const { result } = renderHook(() =>
+      useEmailBlastTableStructure({ data: [], fields: Object.values(EmailBlastFields) 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({ sent: ["sentCount"], failed: ["failedCount"], unsubscribed: ["unsubscribedCount"] });
+  });
+});

package/src/features/email-blast/hooks/useEmailBlastTableStructure.tsx

@@ -33,7 +33,13 @@ export const useEmailBlastTableStructure: UseTableStructureHook<EmailBlastInterf
 
   // Typography role 15 (numeric): tabular-nums, end-aligned. NEVER
   // font-mono — no monospace font is loaded in these apps.
-  const numericColumn = (field: EmailBlastFields, header: string, read: (b: EmailBlastInterface) => number) => ({
+  // `sortField` is the stored count the column shows (its id differs from the property).
+  const numericColumn = (
+    field: EmailBlastFields,
+    header: string,
+    read: (b: EmailBlastInterface) => number,
+    sortField: string,
+  ) => ({
     id: field,
     accessorKey: field,
     header: header,
@@ -41,7 +47,8 @@ export const useEmailBlastTableStructure: UseTableStructureHook<EmailBlastInterf
       const blast: EmailBlastInterface = row.original.jsonApiData;
       return <span className="block text-xs tabular-nums text-end">{read(blast) ?? 0}</span>;
     },
-    enableSorting: false,
+    meta: { sortFields: [sortField] },
+    enableSorting: true,
     enableHiding: false,
   });
 
@@ -54,7 +61,7 @@ export const useEmailBlastTableStructure: UseTableStructureHook<EmailBlastInterf
         const blast: EmailBlastInterface = row.original.jsonApiData;
         return <Link href={generateUrl({ page: Modules.EmailBlast, id: blast.id })}>{blast.subject}</Link>;
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailBlastFields.purpose]: () => ({
@@ -69,7 +76,7 @@ export const useEmailBlastTableStructure: UseTableStructureHook<EmailBlastInterf
           <Badge variant="softGray">{t("emailPurpose.marketing")}</Badge>
         );
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailBlastFields.status]: () => ({
@@ -80,7 +87,7 @@ export const useEmailBlastTableStructure: UseTableStructureHook<EmailBlastInterf
         const blast: EmailBlastInterface = row.original.jsonApiData;
         return <Badge variant={STATUS_VARIANTS[blast.status]}>{t(`emailBlasts.list.status.${blast.status}`)}</Badge>;
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailBlastFields.sentAt]: () => ({
@@ -92,18 +99,19 @@ export const useEmailBlastTableStructure: UseTableStructureHook<EmailBlastInterf
         if (!blast.sentAt) return <span className="text-muted-foreground text-xs">—</span>;
         return <span className="text-sm">{dates.format(blast.sentAt, "date")}</span>;
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [EmailBlastFields.sent]: () =>
-      numericColumn(EmailBlastFields.sent, t("emailBlasts.list.columns.sent"), (b) => b.sentCount),
+      numericColumn(EmailBlastFields.sent, t("emailBlasts.list.columns.sent"), (b) => b.sentCount, "sentCount"),
     [EmailBlastFields.failed]: () =>
-      numericColumn(EmailBlastFields.failed, t("emailBlasts.list.columns.failed"), (b) => b.failedCount),
+      numericColumn(EmailBlastFields.failed, t("emailBlasts.list.columns.failed"), (b) => b.failedCount, "failedCount"),
     [EmailBlastFields.unsubscribed]: () =>
       numericColumn(
         EmailBlastFields.unsubscribed,
         t("emailBlasts.list.columns.unsubscribed"),
         (b) => b.unsubscribedCount,
+        "unsubscribedCount",
       ),
   };
 

package/src/features/how-to/components/lists/HowToList.tsx

@@ -25,6 +25,8 @@ export default function HowToList({ fullWidth, extraFunctions }: HowToListProps)
     module: Modules.HowTo,
     retriever: (params) => HowToService.findMany(params),
     retrieverParams: {},
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "-updatedAt",
   });
 
   const functions: ReactNode[] = [

package/src/features/how-to/data/HowToService.ts

@@ -16,6 +16,8 @@ export class HowToService extends AbstractService {
       fetchAll?: boolean;
       next?: NextRef;
       prev?: PreviousRef;
+      /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+      sort?: string;
     } = {},
   ): Promise<HowToInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.HowTo });
@@ -25,6 +27,8 @@ export class HowToService extends AbstractService {
     if (Modules.HowTo.inclusions?.lists?.fields) endpoint.limitToFields(Modules.HowTo.inclusions.lists.fields);
     if (Modules.HowTo.inclusions?.lists?.types) endpoint.limitToType(Modules.HowTo.inclusions.lists.types);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi({
       type: Modules.HowTo,
       method: HttpMethod.GET,

package/src/features/how-to/hooks/__tests__/useHowToTableStructure.sort.spec.tsx

@@ -0,0 +1,18 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { HowToFields } from "../../data/HowToFields";
+import { useHowToTableStructure } from "../useHowToTableStructure";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key, useLocale: () => "en" }));
+
+/** Spec row A19: name. Only an explicit `enableSorting: true` opts a column in (call C3). */
+describe("useHowToTableStructure sorting", () => {
+  it("opts in exactly the row's sortable columns", () => {
+    const { result } = renderHook(() =>
+      useHowToTableStructure({ data: [], fields: Object.values(HowToFields) 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(["name"]);
+  });
+});

package/src/features/how-to/hooks/useHowToTableStructure.tsx

@@ -43,7 +43,7 @@ export const useHowToTableStructure: UseTableStructureHook<HowToInterface, HowTo
         const howTo: HowToInterface = row.original.jsonApiData;
         return <Link href={generateUrl({ page: Modules.HowTo, id: howTo.id })}>{howTo.name}</Link>;
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [HowToFields.description]: () => ({

package/src/features/notification/components/lists/NotificationsList.tsx

@@ -29,6 +29,8 @@ export function NotificationsList({ archived, headerControl, fullWidth }: Notifi
     module: Modules.Notification,
     retriever: (params) => NotificationService.findMany(params),
     retrieverParams: { isArchived: archived },
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "-createdAt",
   });
 
   /* Mark read what this list ACTUALLY SHOWS, on every page. Reading the shared

package/src/features/notification/data/notification.service.ts

@@ -6,11 +6,15 @@ export class NotificationService extends AbstractService {
     isArchived?: boolean;
     next?: NextRef;
     suppressGlobalError?: boolean;
+    /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+    sort?: string;
   }): Promise<NotificationInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.Notification });
 
     if (params.isArchived) endpoint.addAdditionalParam("isArchived", "true");
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi<NotificationInterface[]>({
       type: Modules.Notification,
       method: HttpMethod.GET,

package/src/features/notification/hooks/__tests__/useNotificationTableStructure.sort.spec.tsx

@@ -0,0 +1,19 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { NotificationFields } from "../../data/notification.fields";
+import { useNotificationTableStructure } from "../useNotificationTableStructure";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key, useLocale: () => "en" }));
+vi.mock("../../contexts/NotificationContext", () => ({ useNotificationContext: () => ({}) }));
+
+/** Spec row A6: createdAt. Only an explicit `enableSorting: true` opts a column in (call C3). */
+describe("useNotificationTableStructure sorting", () => {
+  it("opts in exactly the row's sortable columns", () => {
+    const { result } = renderHook(() =>
+      useNotificationTableStructure({ data: [], fields: Object.values(NotificationFields) 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(["createdAt"]);
+  });
+});

package/src/features/notification/hooks/useNotificationTableStructure.tsx

@@ -130,7 +130,7 @@ export const useNotificationTableStructure: UseTableStructureHook<NotificationIn
           </span>
         );
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [NotificationFields.actions]: () => ({

package/src/features/referral/components/containers/ReferralsAdminContainer.tsx

@@ -103,9 +103,11 @@ export function ReferralsAdminContainer() {
 
   const referrals: DataListRetriever<ReferralAdminReferralInterface> = useDataListRetriever({
     module: Modules.ReferralAdminReferral,
-    retriever: (params: { period: ReferralAdminPeriod }) =>
-      ReferralAdminService.getReferrals({ period: params.period }),
+    retriever: (params: { period: ReferralAdminPeriod; sort?: string }) =>
+      ReferralAdminService.getReferrals({ period: params.period, sort: params.sort }),
     retrieverParams: { period },
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "-referredAt",
   });
 
   useRefetchOnChange(referrers as DataListRetriever<unknown>, "period", period);

package/src/features/referral/data/ReferralAdminService.ts

@@ -38,10 +38,15 @@ export class ReferralAdminService extends AbstractService {
   }
 
   /** Every referral in the period, newest first. */
-  static async getReferrals(params: { period: ReferralAdminPeriod }): Promise<ReferralAdminReferralInterface[]> {
+  static async getReferrals(params: {
+    period: ReferralAdminPeriod;
+    sort?: string;
+  }): Promise<ReferralAdminReferralInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.ReferralAdminReferral });
     endpoint.addAdditionalParam("period", params.period);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi<ReferralAdminReferralInterface[]>({
       type: Modules.ReferralAdminReferral,
       method: HttpMethod.GET,

package/src/features/referral/hooks/__tests__/useReferralAdminReferralTableStructure.sort.spec.tsx

@@ -0,0 +1,35 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+// Loads the core barrel first, as the app does: the hook reaches it through the components barrel,
+// which on its own resolves a model module before its base class (circular import).
+import "../../../../core";
+import "../../../../components";
+import {
+  ReferralAdminReferralFields,
+  useReferralAdminReferralTableStructure,
+} from "../useReferralAdminReferralTableStructure";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key, useLocale: () => "en" }));
+
+/** Spec row A3 (Referrals): source, status, referredAt, tokensAwarded. Only an explicit `enableSorting: true` opts a column in (call C3). */
+describe("useReferralAdminReferralTableStructure sorting", () => {
+  it("opts in exactly the row's sortable columns", () => {
+    const { result } = renderHook(() =>
+      useReferralAdminReferralTableStructure({ data: [], fields: Object.values(ReferralAdminReferralFields) 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(["credits", "date", "source", "status"]);
+  });
+
+  it("maps the columns whose key differs from the stored property (call C4)", () => {
+    const { result } = renderHook(() =>
+      useReferralAdminReferralTableStructure({ data: [], fields: Object.values(ReferralAdminReferralFields) 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({ date: ["referredAt"], credits: ["tokensAwarded"] });
+  });
+});

package/src/features/referral/hooks/useReferralAdminReferralTableStructure.tsx

@@ -81,11 +81,16 @@ export const useReferralAdminReferralTableStructure: UseTableStructureHook<
         // A referral written before the source was recorded: unknown, not guessed.
         return <span className="text-muted-foreground text-xs">—</span>;
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [ReferralAdminReferralFields.date]: () =>
-      cellDate({ name: ReferralAdminReferralFields.date, title: t("referral.admin.referrals.columns.date") }),
+      cellDate({
+        name: ReferralAdminReferralFields.date,
+        title: t("referral.admin.referrals.columns.date"),
+        sortable: true,
+        sortFields: ["referredAt"],
+      }),
     [ReferralAdminReferralFields.status]: () => ({
       id: ReferralAdminReferralFields.status,
       header: t("referral.admin.referrals.columns.status"),
@@ -95,7 +100,7 @@ export const useReferralAdminReferralTableStructure: UseTableStructureHook<
         ) : (
           <Badge variant="softYellow">{t("referral.admin.status.pending")}</Badge>
         ),
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [ReferralAdminReferralFields.credits]: () => ({
@@ -109,8 +114,8 @@ export const useReferralAdminReferralTableStructure: UseTableStructureHook<
         const award = decimal(entry.tokensAwarded, 0);
         return <span className="block text-xs tabular-nums text-end">{`${award} + ${award}`}</span>;
       },
-      meta: { className: "text-end" },
-      enableSorting: false,
+      meta: { className: "text-end", sortFields: ["tokensAwarded"] },
+      enableSorting: true,
       enableHiding: false,
     }),
   };

package/src/features/role/components/lists/RolesList.tsx

@@ -15,6 +15,8 @@ export function RolesList() {
     retriever: (params) => RoleService.findAllRoles(params),
     retrieverParams: {},
     module: Modules.Role,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "name",
   });
 
   return (

package/src/features/role/components/lists/UserRolesList.tsx

@@ -19,6 +19,8 @@ export function UserRolesList({ user }: UserRolesListProps) {
     retriever: (params) => RoleService.findAllRolesByUser(params),
     retrieverParams: { userId: user.id },
     module: Modules.Role,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "name",
   });
 
   return (

package/src/features/role/data/role.service.ts

@@ -10,11 +10,13 @@ export class RoleService extends AbstractService {
     });
   }
 
-  static async findAllRoles(params: { search?: string; next?: NextRef }): Promise<RoleInterface[]> {
+  static async findAllRoles(params: { search?: string; next?: NextRef; sort?: string }): Promise<RoleInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.Role });
 
     if (params.search) endpoint.addAdditionalParam("search", params.search);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi({
       type: Modules.Role,
       method: HttpMethod.GET,
@@ -28,11 +30,15 @@ export class RoleService extends AbstractService {
     search?: string;
     next?: NextRef;
     prev?: PreviousRef;
+    /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+    sort?: string;
   }): Promise<RoleInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.User, id: params.userId, childEndpoint: Modules.Role });
 
     if (params.search) endpoint.addAdditionalParam("search", params.search);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi({
       type: Modules.Role,
       method: HttpMethod.GET,

package/src/features/role/hooks/__tests__/useRoleTableStructure.sort.spec.tsx

@@ -0,0 +1,16 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { RoleFields } from "../../data";
+import { useRoleTableStructure } from "../useRoleTableStructure";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key, useLocale: () => "en" }));
+
+/** Spec rows A25, A26: name, description. Only an explicit `enableSorting: true` opts a column in (call C3). */
+describe("useRoleTableStructure sorting", () => {
+  it("opts in exactly the row's sortable columns", () => {
+    const { result } = renderHook(() => useRoleTableStructure({ data: [], fields: Object.values(RoleFields) 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(["description", "name"]);
+  });
+});

package/src/features/role/hooks/useRoleTableStructure.tsx

@@ -42,7 +42,7 @@ export const useRoleTableStructure: UseTableStructureHook<RoleInterface, RoleFie
         const role = row.original.jsonApiData as RoleInterface;
         return <Link href={generateUrl({ page: Modules.Role, id: role.id })}>{row.getValue("name")}</Link>;
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [RoleFields.description]: () => ({
@@ -50,7 +50,7 @@ export const useRoleTableStructure: UseTableStructureHook<RoleInterface, RoleFie
       accessorKey: "description",
       header: t(`role.fields.description.label`),
       cell: ({ row }: { row: Row<TableContent<RoleInterface>> }) => <>{row.getValue("description")}</>,
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [RoleFields.createdAt]: () =>

package/src/features/user/components/lists/AdminUsersList.tsx

@@ -21,6 +21,8 @@ function AdminUsersListInternal({ company }: AdminUsersListProps) {
     retriever: (params) => UserService.findManyForAmin(params),
     retrieverParams: { companyId: company.id },
     module: Modules.User,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "name",
   });
 
   return (

package/src/features/user/components/lists/CompanyUsersList.tsx

@@ -24,6 +24,10 @@ export function CompanyUsersList({ isDeleted, fullWidth }: CompanyUsersListProps
     retriever: (params) => UserService.findAllUsers(params),
     retrieverParams: { companyId: company?.id, isDeleted: isDeleted },
     module: Modules.User,
+    // The active and deleted lists can share a page (AllUsersListContainer tabs): each keeps its own sort.
+    sortKey: isDeleted ? `${Modules.User.name}-deleted` : undefined,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "name",
   }) as DataListRetriever<UserInterface>;
 
   useEffect(() => {