@carlonicora/nextjs-jsonapi 6.32.1 → 6.33.0

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

@@ -30,6 +30,8 @@ export function PlatformUsersList({ includeDeleted, fullWidth }: PlatformUsersLi
     retriever: (params) => UserService.findMany(params),
     retrieverParams: { includeDeleted: includeDeleted },
     module: Modules.User,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "name",
   }) as DataListRetriever<UserInterface>;
 
   return (

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

@@ -19,6 +19,8 @@ export function RoleUsersList({ role }: RoleUsersListProps) {
     retriever: (params) => UserService.findAllUsersByRole(params),
     retrieverParams: { roleId: role.id },
     module: Modules.User,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "name",
   }) as DataListRetriever<UserInterface>;
 
   return (

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

@@ -18,6 +18,8 @@ export function UsersListByContentIds({ contentIds }: UsersListByContentIdsProps
     module: Modules.User,
     retriever: (params) => UserService.findManyByContentIds(params),
     retrieverParams: { contentIds: contentIds },
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "name",
   });
 
   return (

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

@@ -33,6 +33,8 @@ export class UserService extends AbstractService {
     includeDeleted?: boolean;
     next?: NextRef;
     prev?: PreviousRef;
+    /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+    sort?: string;
   }): Promise<UserInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.User });
 
@@ -42,6 +44,8 @@ export class UserService extends AbstractService {
     if (params.fetchAll) endpoint.addAdditionalParam("fetchAll", "true");
     if (params.search) endpoint.addAdditionalParam("search", params.search);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi({
       type: Modules.User,
       method: HttpMethod.GET,
@@ -55,6 +59,8 @@ export class UserService extends AbstractService {
     search?: string;
     next?: NextRef;
     prev?: PreviousRef;
+    /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+    sort?: string;
   }): Promise<UserInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.User });
 
@@ -63,6 +69,8 @@ export class UserService extends AbstractService {
     endpoint.addAdditionalParam("fetchAll", "true");
     if (params.search) endpoint.addAdditionalParam("search", params.search);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi({
       type: Modules.User,
       method: HttpMethod.GET,
@@ -71,7 +79,12 @@ export class UserService extends AbstractService {
     });
   }
 
-  static async findRelevant(params: { id: string; next?: NextRef; prev?: PreviousRef }): Promise<UserInterface[]> {
+  static async findRelevant(params: {
+    id: string;
+    next?: NextRef;
+    prev?: PreviousRef;
+    sort?: string;
+  }): Promise<UserInterface[]> {
     const endpoint: EndpointCreator = new EndpointCreator({
       endpoint: Modules.Content,
       id: params.id,
@@ -81,6 +94,8 @@ export class UserService extends AbstractService {
     if (Modules.User.inclusions?.lists?.fields) endpoint.limitToFields(Modules.User.inclusions.lists.fields);
     if (Modules.User.inclusions?.lists?.types) endpoint.limitToType(Modules.User.inclusions.lists.types);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi<UserInterface[]>({
       type: Modules.User,
       method: HttpMethod.GET,
@@ -94,6 +109,8 @@ export class UserService extends AbstractService {
     search?: string;
     next?: NextRef;
     prev?: PreviousRef;
+    /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+    sort?: string;
   }): Promise<UserInterface[]> {
     if (!params.companyId) return [];
 
@@ -105,6 +122,8 @@ export class UserService extends AbstractService {
 
     if (params.search) endpoint.addAdditionalParam("search", params.search);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi({
       type: Modules.User,
       method: HttpMethod.GET,
@@ -121,6 +140,8 @@ export class UserService extends AbstractService {
     isDeleted?: boolean;
     next?: NextRef;
     prev?: PreviousRef;
+    /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+    sort?: string;
   }): Promise<UserInterface[]> {
     const endpoint = new EndpointCreator({
       endpoint: Modules.Company,
@@ -133,6 +154,8 @@ export class UserService extends AbstractService {
     if (params.limitToRoles && params.limitToRoles.length > 0)
       endpoint.addAdditionalParam("limitToRoles", params.limitToRoles.join(","));
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi({
       type: Modules.User,
       method: HttpMethod.GET,
@@ -146,11 +169,15 @@ export class UserService extends AbstractService {
     search?: string;
     next?: NextRef;
     prev?: PreviousRef;
+    /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+    sort?: string;
   }): Promise<UserInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.Role, id: params.roleId, childEndpoint: Modules.User });
 
     if (params.search) endpoint.addAdditionalParam("search", params.search);
 
+    if (params.sort) endpoint.addAdditionalParam("sort", params.sort);
+
     return this.callApi({
       type: Modules.User,
       method: HttpMethod.GET,

package/src/features/user/hooks/__tests__/useUserTableStructure.sort.spec.tsx

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

package/src/features/user/hooks/useUserTableStructure.tsx

@@ -57,7 +57,7 @@ export const useUserTableStructure: UseTableStructureHook<UserInterface, UserFie
           </Link>
         );
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [UserFields.email]: () => ({
@@ -65,7 +65,7 @@ export const useUserTableStructure: UseTableStructureHook<UserInterface, UserFie
       accessorKey: "email",
       header: t(`common.fields.email.label`),
       cell: ({ row }: { row: Row<TableContent<UserInterface>> }) => <>{row.getValue("email")}</>,
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     // Only meaningful on a platform-wide list (PlatformUsersList), where users

package/src/features/waitlist/components/lists/WaitlistList.tsx

@@ -32,6 +32,8 @@ export function WaitlistList({ fullWidth }: WaitlistListProps = {}) {
     retriever: (params) => WaitlistService.findMany(params),
     retrieverParams: {},
     module: Modules.Waitlist,
+    // Display only (call C8): the server's own order when no sort is chosen.
+    defaultSort: "-createdAt",
   });
 
   const loadStats = useCallback(async () => {

package/src/features/waitlist/data/WaitlistService.ts

@@ -43,6 +43,8 @@ export class WaitlistService extends AbstractService {
     fetchAll?: boolean;
     next?: NextRef;
     previous?: PreviousRef;
+    /** JSON:API `sort` (`name`, `-name`), forwarded to the API. */
+    sort?: string;
   }): Promise<WaitlistInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: Modules.Waitlist });
 
@@ -50,6 +52,8 @@ export class WaitlistService extends AbstractService {
     if (params?.search) endpoint.addAdditionalParam("search", params.search);
     if (params?.fetchAll) endpoint.addAdditionalParam("fetchAll", "true");
 
+    if (params?.sort) endpoint.addAdditionalParam("sort", params?.sort);
+
     return this.callApi<WaitlistInterface[]>({
       type: Modules.Waitlist,
       method: HttpMethod.GET,

package/src/features/waitlist/hooks/__tests__/useWaitlistTableStructure.sort.spec.tsx

@@ -0,0 +1,17 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { WaitlistFields } from "../../data/waitlist.fields";
+import { useWaitlistTableStructure } from "../useWaitlistTableStructure";
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key, useLocale: () => "en" }));
+
+/** Spec row A1: exactly email, status and createdAt are sortable (call C3: an explicit `true`). */
+describe("useWaitlistTableStructure sorting", () => {
+  it("opts in exactly the row's sortable columns", () => {
+    const { result } = renderHook(() =>
+      useWaitlistTableStructure({ data: [], fields: Object.values(WaitlistFields) as WaitlistFields[] }),
+    );
+    const sortable = result.current.columns.filter((c) => c.enableSorting === true).map((c) => c.id);
+    expect(sortable.sort()).toEqual(["createdAt", "email", "status"]);
+  });
+});

package/src/features/waitlist/hooks/useWaitlistTableStructure.tsx

@@ -53,7 +53,7 @@ export const useWaitlistTableStructure: UseTableStructureHook<WaitlistInterface,
       cell: ({ row }: { row: TableContent<WaitlistInterface> }) => (
         <span className="font-medium">{row.original.jsonApiData.email}</span>
       ),
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [WaitlistFields.status]: () => ({
@@ -61,7 +61,7 @@ export const useWaitlistTableStructure: UseTableStructureHook<WaitlistInterface,
       accessorKey: "status",
       header: t("waitlist.admin.columns.status"),
       cell: ({ row }: { row: TableContent<WaitlistInterface> }) => getStatusBadge(row.original.jsonApiData.status),
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [WaitlistFields.createdAt]: () => ({
@@ -73,7 +73,7 @@ export const useWaitlistTableStructure: UseTableStructureHook<WaitlistInterface,
         if (!entry.createdAt) return "-";
         return dates.format(entry.createdAt, "date");
       },
-      enableSorting: false,
+      enableSorting: true,
       enableHiding: false,
     }),
     [WaitlistFields.source]: () => ({

package/src/hooks/__tests__/useDataListRetriever.sort.spec.tsx

@@ -0,0 +1,114 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createMockModule } from "../../testing";
+import { useDataListRetriever } from "../useDataListRetriever";
+
+describe("useDataListRetriever sort", () => {
+  const mockModule = createMockModule({ name: "accounts" });
+
+  beforeEach(() => {
+    window.history.replaceState(null, "", "/accounts?sort%5Baccounts%5D=-name");
+  });
+
+  afterEach(() => {
+    window.history.replaceState(null, "", "/");
+    vi.restoreAllMocks();
+  });
+
+  it("reads the sort from the address and fetches once with it", async () => {
+    const retriever = vi.fn().mockResolvedValue([]);
+    const { result } = renderHook(() => useDataListRetriever({ retriever, module: mockModule }));
+
+    await waitFor(() => expect(result.current.isLoaded).toBe(true));
+
+    expect(retriever).toHaveBeenCalledTimes(1);
+    expect(retriever.mock.calls[0][0].sort).toBe("-name");
+    expect(result.current.sort).toBe("-name");
+  });
+
+  it("refetches once with the new sort and the current search term", async () => {
+    const retriever = vi.fn().mockResolvedValue([]);
+    const { result } = renderHook(() => useDataListRetriever({ retriever, module: mockModule }));
+    await waitFor(() => expect(result.current.isLoaded).toBe(true));
+
+    await act(async () => {
+      await result.current.search("rossi");
+    });
+    await waitFor(() => expect(result.current.isLoaded).toBe(true));
+    retriever.mockClear();
+
+    await act(async () => {
+      result.current.setSort("name");
+    });
+    await waitFor(() => expect(result.current.isLoaded).toBe(true));
+
+    expect(retriever).toHaveBeenCalledTimes(1);
+    expect(retriever.mock.calls[0][0].sort).toBe("name");
+    expect(retriever.mock.calls[0][0].search).toBe("rossi");
+    expect(result.current.sort).toBe("name");
+    expect(new URLSearchParams(window.location.search).get("sort[accounts]")).toBe("name");
+  });
+
+  it("returns to page 1 when the sort changes", async () => {
+    const retriever = vi.fn().mockImplementation(async (params: { next?: { next?: string } }) => {
+      if (params.next) params.next.next = "accounts?page[offset]=25";
+      return [];
+    });
+    const { result } = renderHook(() => useDataListRetriever({ retriever, module: mockModule }));
+    await waitFor(() => expect(result.current.isLoaded).toBe(true));
+    await waitFor(() => expect(result.current.next).toBeDefined());
+
+    retriever.mockClear();
+    retriever.mockResolvedValue([]);
+    await act(async () => {
+      result.current.setSort("name");
+    });
+    await waitFor(() => expect(result.current.isLoaded).toBe(true));
+
+    // The refetch goes through the list's own retriever (page 1), never the stored next-page link.
+    expect(retriever).toHaveBeenCalledTimes(1);
+    expect(retriever.mock.calls[0][0].sort).toBe("name");
+    expect(result.current.next).toBeUndefined();
+    expect(result.current.previous).toBeUndefined();
+  });
+
+  it("sends no sort after it is cleared", async () => {
+    const retriever = vi.fn().mockResolvedValue([]);
+    const { result } = renderHook(() => useDataListRetriever({ retriever, module: mockModule }));
+    await waitFor(() => expect(result.current.isLoaded).toBe(true));
+    retriever.mockClear();
+
+    await act(async () => {
+      result.current.setSort(null);
+    });
+    await waitFor(() => expect(result.current.isLoaded).toBe(true));
+
+    expect(retriever).toHaveBeenCalledTimes(1);
+    expect(retriever.mock.calls[0][0].sort).toBeUndefined();
+    expect(result.current.sort).toBeUndefined();
+  });
+
+  it("uses sortKey over the module name", async () => {
+    window.history.replaceState(null, "", "/accounts?sort%5Bclients%5D=name&sort%5Baccounts%5D=-name");
+    const retriever = vi.fn().mockResolvedValue([]);
+    const { result } = renderHook(() => useDataListRetriever({ retriever, module: mockModule, sortKey: "clients" }));
+    await waitFor(() => expect(result.current.isLoaded).toBe(true));
+
+    expect(retriever).toHaveBeenCalledTimes(1);
+    expect(retriever.mock.calls[0][0].sort).toBe("name");
+  });
+
+  it("exposes defaultSort and never sends it", async () => {
+    window.history.replaceState(null, "", "/accounts");
+    const retriever = vi.fn().mockResolvedValue([]);
+    const { result } = renderHook(() =>
+      useDataListRetriever({ retriever, module: mockModule, defaultSort: "-updatedAt" }),
+    );
+    await waitFor(() => expect(result.current.isLoaded).toBe(true));
+
+    expect(result.current.defaultSort).toBe("-updatedAt");
+    expect(result.current.sort).toBeUndefined();
+    expect(retriever).toHaveBeenCalledTimes(1);
+    expect(retriever.mock.calls[0][0].sort).toBeUndefined();
+  });
+});

package/src/hooks/__tests__/useListSortParam.spec.tsx

@@ -0,0 +1,91 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useListSortParam } from "../useListSortParam";
+
+describe("useListSortParam", () => {
+  beforeEach(() => {
+    window.history.replaceState(null, "", "/accounts?search=x");
+  });
+
+  afterEach(() => {
+    window.history.replaceState(null, "", "/");
+    vi.restoreAllMocks();
+  });
+
+  it("is not ready on the first render and ready after mount", () => {
+    const renders: boolean[] = [];
+    const { result } = renderHook(() => {
+      const state = useListSortParam({ sortKey: "accounts" });
+      renders.push(state.ready);
+      return state;
+    });
+
+    expect(renders[0]).toBe(false);
+    expect(result.current.ready).toBe(true);
+  });
+
+  it("reads its key from the address", () => {
+    window.history.replaceState(null, "", "/accounts?sort%5Baccounts%5D=-name");
+    const { result } = renderHook(() => useListSortParam({ sortKey: "accounts" }));
+
+    expect(result.current.sort).toBe("-name");
+  });
+
+  it("is undefined when the address has no value for its key", () => {
+    const { result } = renderHook(() => useListSortParam({ sortKey: "accounts" }));
+
+    expect(result.current.ready).toBe(true);
+    expect(result.current.sort).toBeUndefined();
+  });
+
+  it("writes its key with replaceState, keeping the path and the other params", () => {
+    const replaceState = vi.spyOn(window.history, "replaceState");
+    const { result } = renderHook(() => useListSortParam({ sortKey: "accounts" }));
+
+    act(() => result.current.setSort("name"));
+
+    expect(replaceState).toHaveBeenCalledTimes(1);
+    expect(replaceState).toHaveBeenCalledWith(null, "", "/accounts?search=x&sort%5Baccounts%5D=name");
+    expect(result.current.sort).toBe("name");
+  });
+
+  it("keeps two keys on one address independent", () => {
+    window.history.replaceState(null, "", "/accounts?sort%5Bcontacts%5D=-lastName");
+    const accounts = renderHook(() => useListSortParam({ sortKey: "accounts" }));
+    const contacts = renderHook(() => useListSortParam({ sortKey: "contacts" }));
+
+    expect(accounts.result.current.sort).toBeUndefined();
+    expect(contacts.result.current.sort).toBe("-lastName");
+
+    act(() => accounts.result.current.setSort("name"));
+
+    const params = new URLSearchParams(window.location.search);
+    expect(params.get("sort[accounts]")).toBe("name");
+    expect(params.get("sort[contacts]")).toBe("-lastName");
+    expect(contacts.result.current.sort).toBe("-lastName");
+  });
+
+  it("removes only its own key on null", () => {
+    window.history.replaceState(null, "", "/accounts?search=x&sort%5Baccounts%5D=name&sort%5Bcontacts%5D=-lastName");
+    const { result } = renderHook(() => useListSortParam({ sortKey: "accounts" }));
+
+    act(() => result.current.setSort(null));
+
+    const params = new URLSearchParams(window.location.search);
+    expect(params.has("sort[accounts]")).toBe(false);
+    expect(params.get("sort[contacts]")).toBe("-lastName");
+    expect(params.get("search")).toBe("x");
+    expect(window.location.pathname).toBe("/accounts");
+    expect(result.current.sort).toBeUndefined();
+  });
+
+  it("keeps the hash", () => {
+    window.history.replaceState(null, "", "/accounts#top");
+    const replaceState = vi.spyOn(window.history, "replaceState");
+    const { result } = renderHook(() => useListSortParam({ sortKey: "accounts" }));
+
+    act(() => result.current.setSort("-name"));
+
+    expect(replaceState).toHaveBeenCalledWith(null, "", "/accounts?sort%5Baccounts%5D=-name#top");
+  });
+});

package/src/hooks/index.ts

@@ -9,6 +9,7 @@ export type {
 export { useUrlRewriter } from "./url.rewriter";
 export { useDataListRetriever, type DataListRetriever } from "./useDataListRetriever";
 export { useDebounce } from "./useDebounce";
+export { useListSortParam } from "./useListSortParam";
 export { usePageUrlGenerator } from "./usePageUrlGenerator";
 export { registerTableGenerator, useTableGenerator } from "./useTableGenerator";
 

package/src/hooks/useDataListRetriever.ts

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { ClientAbstractService } from "../core/abstracts/ClientAbstractService";
 import { getLastApiMeta, getLastApiTotal } from "../core/abstracts/AbstractService";
+import { useListSortParam } from "./useListSortParam";
 
 export type PageInfo = {
   startItem: number;
@@ -27,6 +28,15 @@ export type DataListRetriever<T> = {
   removeElement: (element: T) => void;
   isSearch: boolean;
   pageInfo?: PageInfo;
+  /** The chosen sort in JSON:API wire format (`name`, `-name`), kept in the page address. */
+  sort?: string;
+  /** The list's display-only default order (e.g. `-updatedAt`). Never sent to the API. */
+  defaultSort?: string;
+  /**
+   * Sets (or, with `null`, clears) the sort: writes the address and refetches from page 1, keeping the search term.
+   * Optional so hand-built retrievers keep compiling; without it a server-mode table renders plain headers.
+   */
+  setSort?: (value: string | null) => void;
 };
 
 export function useDataListRetriever<T>(params: {
@@ -37,6 +47,10 @@ export function useDataListRetriever<T>(params: {
   addAdditionalParameter?: (key: string, value: any | null) => void;
   requiresSearch?: boolean;
   module: any;
+  /** Address key of this list's sort (`sort[<sortKey>]`). Defaults to `module.name`. */
+  sortKey?: string;
+  /** Display-only default order, exposed for the table header and never passed to the retriever. */
+  defaultSort?: string;
 }): DataListRetriever<T> {
   const [data, setData] = useState<T[] | undefined>(undefined);
   const [total, setTotal] = useState<number | undefined>(undefined);
@@ -52,6 +66,15 @@ export function useDataListRetriever<T>(params: {
   const isFetchingRef = useRef(false);
   const isPaginatingRef = useRef(false);
 
+  // The sort lives in the page address. The first fetch waits until the address has been
+  // read, so a restored sort is fetched once instead of unsorted first and sorted after.
+  const sortParam = useListSortParam({ sortKey: params.sortKey ?? params.module?.name ?? "" });
+  const sortReady = sortParam.ready;
+  const sortRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    sortRef.current = sortParam.sort;
+  }, [sortParam.sort]);
+
   const resolvedType = params.module;
   const resolvedService = ClientAbstractService; // We'll just use ClientAbstractService directly for pagination
 
@@ -129,7 +152,7 @@ export function useDataListRetriever<T>(params: {
       /** Re-fetch even though a single-page list is already loaded. */
       force?: boolean;
     }) => {
-      if (ready === false) return;
+      if (ready === false || !sortReady) return;
 
       // Prevent concurrent pagination calls
       if ((fetchParams?.callNext || fetchParams?.callPrevious) && isPaginatingRef.current) {
@@ -213,6 +236,7 @@ export function useDataListRetriever<T>(params: {
           // An explicit `search` passed through addAdditionalParameter wins: overwriting it
           // with the internal term (only ever set by `search()`) silently dropped it.
           if (additionalParamsRef.current.search === undefined) retrieverParams.search = currentSearchTerm;
+          if (sortRef.current !== undefined) retrieverParams.sort = sortRef.current;
           retrieverParams.next = nextRef;
           retrieverParams.previous = previousRef;
           retrieverParams.self = selfRef;
@@ -254,7 +278,7 @@ export function useDataListRetriever<T>(params: {
         }
       }
     },
-    [stableParams, ready, params.search],
+    [stableParams, ready, sortReady, params.search],
   );
 
   const setRefreshedElement = useCallback(
@@ -297,10 +321,10 @@ export function useDataListRetriever<T>(params: {
   // and ready effect fired simultaneously on initial render
   useEffect(() => {
     // Only fetch if ready and haven't loaded yet
-    if (ready && !isLoaded) {
+    if (ready && sortReady && !isLoaded) {
       fetchData({ isRefresh: true });
     }
-  }, [ready, fetchData]);
+  }, [ready, sortReady, fetchData]);
 
   // Cache Components keeps a visited route alive in a hidden <Activity>: leaving it cleans up
   // its effects, coming back re-runs them with the old state intact. A loaded list would then
@@ -377,6 +401,19 @@ export function useDataListRetriever<T>(params: {
     [fetchData],
   );
 
+  const writeSortParam = sortParam.setSort;
+  const setSort = useCallback(
+    (value: string | null) => {
+      writeSortParam(value);
+      sortRef.current = value ? value : undefined;
+      setNextPage(undefined);
+      setPreviousPage(undefined);
+      // `force`: a new order must be fetched even when the loaded list fits on one page.
+      fetchData({ isRefine: true, isRefresh: true, force: true });
+    },
+    [fetchData, writeSortParam],
+  );
+
   const isSearch = !!searchTermRef.current;
 
   const refresh = useCallback(async () => {
@@ -412,5 +449,8 @@ export function useDataListRetriever<T>(params: {
     isSearch: isSearch,
     removeElement: removeElement,
     pageInfo: pageInfo,
+    sort: sortParam.sort,
+    defaultSort: params.defaultSort,
+    setSort: setSort,
   };
 }

package/src/hooks/useListSortParam.ts

@@ -0,0 +1,53 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+/**
+ * The sort of one list, kept in the page address as `sort[<sortKey>]=<value>`
+ * (JSON:API wire format: `name`, `-name`, `lastName,firstName`).
+ *
+ * The address is read from `window.location` once on mount, so this hook is not a
+ * Next search-params hook consumer and needs no `<Suspense>` boundary. `ready` is false
+ * until that read has happened; a loader holds its first fetch until then, so a
+ * restored sort costs one request, not two.
+ *
+ * `setSort` replaces only the query string of the current path with
+ * `history.replaceState`, keeping every other search param and the hash: no
+ * navigation, no scroll, no locale handling. `null` removes this list's key only.
+ *
+ * @param params.sortKey the list's address key; two lists on one page need two keys.
+ */
+export function useListSortParam(params: { sortKey: string }): {
+  sort: string | undefined;
+  ready: boolean;
+  setSort: (value: string | null) => void;
+} {
+  const { sortKey } = params;
+  const [sort, setSortState] = useState<string | undefined>(undefined);
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    const value = new URLSearchParams(window.location.search).get(`sort[${sortKey}]`);
+    setSortState(value ? value : undefined);
+    setReady(true);
+  }, [sortKey]);
+
+  const setSort = useCallback(
+    (value: string | null) => {
+      const search = new URLSearchParams(window.location.search);
+      if (value) search.set(`sort[${sortKey}]`, value);
+      else search.delete(`sort[${sortKey}]`);
+
+      const next = search.toString();
+      window.history.replaceState(
+        null,
+        "",
+        `${window.location.pathname}${next ? `?${next}` : ""}${window.location.hash}`,
+      );
+      setSortState(value ? value : undefined);
+    },
+    [sortKey],
+  );
+
+  return { sort, ready, setSort };
+}