From b1f1e16af1994084e8597930540318aee480da9b Mon Sep 17 00:00:00 2001
From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Date: Fri, 31 Jul 2026 17:26:29 +0800
Subject: [PATCH 1/2] feat(components,grid,list): a column-header sort orders
 the whole list, not the page you can see (#3106)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clicking a column header under server pagination sorted the CURRENT PAGE. The
user saw "sorted by this column" and got "these fifty rows are in order; page 2
starts over". The sort was real — its scope was not the one the screen implied
— and it had no way out of `data-table` at all: it lived in two `useState`s
with no callback, so the layer that issues the request could not see it even in
principle.

DataTable gains `manualSorting` + a controlled `sort` + `onSortChange`. In that
mode it sorts nothing, reports what a header click asks for, and renders `sort`
as the indicator — holding NO sort state of its own, because a private copy
beside a controlled prop is the shape the defect had. `manualSorting` is
independent of `manualPagination`: what matters is whether `data` is a window,
not who owns the pager.

ObjectGrid turns that into a `$orderby` in both of its server modes (its own
fetch and a parent-driven one) and returns to page 1, since a new ordering
makes the old page index a different set of rows. ListView lands it in
`currentSort` — the same state the toolbar's sort builder writes. One sort with
two controls onto it is what makes "does a header sort outrank the saved view's
sort?" a non-question rather than a precedence rule someone has to remember.

Three decisions worth naming:

- A header click REPLACES the order rather than appending, so the column under
  the cursor is the one the list is sorted by. Multi-key orders still come from
  the sort builder, and the headers render them numbered.
- It cannot ask for "no sort". The third click clears in client mode, which is
  meaningful there (rows return to the order they arrived in); across a
  server-paged collection there is no such order (objectstack#4363), so a header
  offering it would hand the user a worse lie than the one being fixed.
- Relational columns render no sort affordance under server sorting: a `lookup`
  column shows a related record's name while `$orderby` can only order by the
  stored id (objectstack#4256) — the same reason #3096 removed them from the
  toolbar's picker. Client-side sorting keys off the rendered label, so those
  headers stay live there.

The header context menu's Sort Ascending/Descending items now route through the
same write path; they wrote internal state directly, which under `manualSorting`
would have been a menu item that highlights, closes, and changes nothing.

Client-side tables are untouched: same three-state cycle, same local sort.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .changeset/server-side-column-header-sort.md  |  44 ++++
 .../data-table-manual-sorting.test.tsx        | 207 +++++++++++++++++
 .../src/renderers/complex/data-table.tsx      | 103 +++++++--
 packages/plugin-grid/src/ObjectGrid.tsx       | 144 ++++++++++--
 .../src/__tests__/serverSorting.test.tsx      | 212 ++++++++++++++++++
 packages/plugin-list/src/ListView.tsx         |  34 +++
 .../__tests__/ListView.headerSort.test.tsx    | 188 ++++++++++++++++
 packages/types/src/data-display.ts            |  58 +++++
 packages/types/src/index.ts                   |   1 +
 9 files changed, 953 insertions(+), 38 deletions(-)
 create mode 100644 .changeset/server-side-column-header-sort.md
 create mode 100644 packages/components/src/__tests__/data-table-manual-sorting.test.tsx
 create mode 100644 packages/plugin-grid/src/__tests__/serverSorting.test.tsx
 create mode 100644 packages/plugin-list/src/__tests__/ListView.headerSort.test.tsx

diff --git a/.changeset/server-side-column-header-sort.md b/.changeset/server-side-column-header-sort.md
new file mode 100644
index 000000000..e8e82222f
--- /dev/null
+++ b/.changeset/server-side-column-header-sort.md
@@ -0,0 +1,44 @@
+---
+"@object-ui/types": minor
+"@object-ui/components": minor
+"@object-ui/plugin-grid": minor
+"@object-ui/plugin-list": minor
+---
+
+feat(components,grid,list): a column-header sort orders the whole list, not the page you can see — #3106
+
+Clicking a column header under server pagination sorted **the current page**.
+The user saw "sorted by this column" and got "these fifty rows are in order;
+page 2 starts over". The sort was real — its scope was not the one the screen
+implied — and it had no way out of `data-table` at all: the sort lived in two
+`useState`s with no callback, so the layer that issues the request could not
+see it even in principle.
+
+`DataTable` gains `manualSorting` + a controlled `sort` + `onSortChange`. In
+that mode it sorts nothing, reports what a header click asks for, and renders
+`sort` as the indicator — keeping **no** sort state of its own, because a
+private copy beside a controlled prop is the shape the defect had.
+
+`ObjectGrid` turns that into a `$orderby` in both of its server modes (its own
+fetch, and a parent-driven one), and `ListView` lands it in `currentSort` — the
+same state the toolbar's sort builder writes. One sort, two controls: that is
+what makes "does a header sort outrank the saved view's sort?" a non-question
+rather than a precedence rule someone has to remember.
+
+Three details that are decisions, not incidentals:
+
+- **A header click replaces the order** instead of appending to it, so the
+  column under the cursor is the one the list is sorted by. Multi-key orders
+  still come from the sort builder, and the headers render them numbered.
+- **It cannot ask for "no sort".** In client mode the third click clears, and
+  that is meaningful there — the rows return to the order they arrived in.
+  Across a server-paged collection there is no such order (objectstack#4363), so
+  a header offering it would hand the user a worse lie than the one being fixed.
+  Clearing stays with the sort builder, which can restore the view's default.
+- **Relational columns render no sort affordance** under server sorting. A
+  `lookup` column shows a related record's name while `$orderby` can only order
+  by the stored id (objectstack#4256) — the same reason #3096 removed them from
+  the toolbar's sort picker. Client-side sorting keys off the rendered label, so
+  those headers stay live there.
+
+Client-side tables are untouched: same three-state cycle, same local sort.
diff --git a/packages/components/src/__tests__/data-table-manual-sorting.test.tsx b/packages/components/src/__tests__/data-table-manual-sorting.test.tsx
new file mode 100644
index 000000000..9e45bfc27
--- /dev/null
+++ b/packages/components/src/__tests__/data-table-manual-sorting.test.tsx
@@ -0,0 +1,207 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Server-side ("manual") sorting for DataTable (objectui#3106).
+ *
+ * The defect: a column-header click sorted whatever rows the table was holding.
+ * Under server pagination that is ONE PAGE, so the header said "sorted by this
+ * column" about fifty rows and nothing about the list they came from — and the
+ * sort had no way out of the component to reach the layer that fetches.
+ *
+ * In manual mode the table sorts nothing, reports the requested sort through
+ * `onSortChange`, and renders `sort` as the indicator. It keeps **no** sort
+ * state of its own: a private copy alongside a controlled prop is the shape the
+ * bug had, so these tests assert the rows are untouched and that the indicator
+ * follows the prop rather than the click.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { renderComponent } from './test-utils';
+// Registers the renderers at module scope, NOT inside a `beforeAll` — there the
+// cold transform is billed to `hookTimeout` (objectui#3010/#3021).
+import '../renderers';
+
+/** Deliberately NOT in `status` order — a local sort would visibly reorder it. */
+const pageData = [
+  { id: 'r1', name: 'Alpha', status: 'open' },
+  { id: 'r2', name: 'Bravo', status: 'done' },
+  { id: 'r3', name: 'Charlie', status: 'hold' },
+];
+
+const columns = [
+  { header: 'Name', accessorKey: 'name' },
+  { header: 'Status', accessorKey: 'status' },
+];
+
+const baseSchema = {
+  type: 'data-table' as const,
+  columns,
+  data: pageData,
+  manualSorting: true,
+  sort: [],
+} as any;
+
+const rowOrder = (container: HTMLElement) =>
+  Array.from(container.querySelectorAll('tbody tr')).map(
+    (tr) => tr.querySelector('td')?.textContent?.trim(),
+  );
+
+const headerCell = (container: HTMLElement, label: string) =>
+  Array.from(container.querySelectorAll('thead th')).find((th) =>
+    th.textContent?.includes(label),
+  ) as HTMLElement;
+
+describe('data-table — manual (server-side) sorting', () => {
+  it('does not reorder the rows it was handed', () => {
+    const { container } = renderComponent({
+      ...baseSchema,
+      sort: [{ field: 'status', order: 'asc' }],
+      onSortChange: vi.fn(),
+    });
+    // `status` ascending would be done, hold, open. The rows arrive in the
+    // server's order and stay in it — sorting this window is the whole defect.
+    expect(rowOrder(container)).toEqual(['Alpha', 'Bravo', 'Charlie']);
+  });
+
+  it('reports a header click instead of sorting locally', () => {
+    const onSortChange = vi.fn();
+    const { container } = renderComponent({ ...baseSchema, onSortChange });
+
+    fireEvent.click(headerCell(container, 'Status'));
+
+    expect(onSortChange).toHaveBeenCalledWith([{ field: 'status', order: 'asc' }]);
+    expect(rowOrder(container)).toEqual(['Alpha', 'Bravo', 'Charlie']);
+  });
+
+  it('toggles the direction of the column already sorted', () => {
+    const onSortChange = vi.fn();
+    const { container } = renderComponent({
+      ...baseSchema,
+      sort: [{ field: 'status', order: 'asc' }],
+      onSortChange,
+    });
+
+    fireEvent.click(headerCell(container, 'Status'));
+    expect(onSortChange).toHaveBeenCalledWith([{ field: 'status', order: 'desc' }]);
+  });
+
+  it('never asks for "no sort" — the third click returns to ascending', () => {
+    // Client mode cycles asc → desc → none, and none is meaningful there (the
+    // rows return to the order they arrived in). Across a server-paged
+    // collection there is no such order: an unsorted paged read is arbitrary
+    // per page (objectstack#4363), so a header must not be able to request it.
+    const onSortChange = vi.fn();
+    const { container } = renderComponent({
+      ...baseSchema,
+      sort: [{ field: 'status', order: 'desc' }],
+      onSortChange,
+    });
+
+    fireEvent.click(headerCell(container, 'Status'));
+    expect(onSortChange).toHaveBeenCalledWith([{ field: 'status', order: 'asc' }]);
+    // Not `[]`, and not a call with an empty array anywhere.
+    for (const call of onSortChange.mock.calls) expect(call[0]).not.toHaveLength(0);
+  });
+
+  it('REPLACES the order when a different column is clicked', () => {
+    // The column under the cursor becomes the one the list is sorted by. A
+    // header that appended would grow an invisible sort stack — the arrow says
+    // "Name" while the rows are ordered by Status first.
+    const onSortChange = vi.fn();
+    const { container } = renderComponent({
+      ...baseSchema,
+      sort: [{ field: 'status', order: 'asc' }],
+      onSortChange,
+    });
+
+    fireEvent.click(headerCell(container, 'Name'));
+    expect(onSortChange).toHaveBeenCalledWith([{ field: 'name', order: 'asc' }]);
+  });
+
+  it('holds no sort state of its own — the indicator follows the prop, not the click', () => {
+    // The controlled value never changes, so nothing may appear to have been
+    // sorted. A table keeping a private copy would light up its own arrow here,
+    // which is exactly how a sort ends up somewhere the fetching layer cannot
+    // see it.
+    const { container } = renderComponent({ ...baseSchema, onSortChange: vi.fn() });
+    const before = headerCell(container, 'Status').innerHTML;
+
+    fireEvent.click(headerCell(container, 'Status'));
+
+    expect(headerCell(container, 'Status').innerHTML).toBe(before);
+  });
+
+  it('renders every key of a multi-key sort, numbered', () => {
+    // Multi-key orders come from a host's sort builder. Marking only the first
+    // column would say "sorted by Status" about a list ordered by Status then
+    // Name.
+    const { container } = renderComponent({
+      ...baseSchema,
+      sort: [{ field: 'status', order: 'asc' }, { field: 'name', order: 'desc' }],
+      onSortChange: vi.fn(),
+    });
+
+    expect(headerCell(container, 'Status').textContent).toContain('1');
+    expect(headerCell(container, 'Name').textContent).toContain('2');
+  });
+
+  it('renders no rank badge for an ordinary single-column sort', () => {
+    const { container } = renderComponent({
+      ...baseSchema,
+      sort: [{ field: 'status', order: 'asc' }],
+      onSortChange: vi.fn(),
+    });
+    expect(headerCell(container, 'Status').textContent?.trim()).toBe('Status');
+  });
+
+  it('renders inert headers when no onSortChange was supplied', () => {
+    // A manual-sorting table with nowhere to report a click must not look
+    // clickable: a dead affordance is the same class of lie as a sort that
+    // silently covers one page.
+    const { container } = renderComponent(baseSchema);
+    const status = headerCell(container, 'Status');
+    expect(status.className).not.toContain('cursor-pointer');
+    // No sort chevron. (Other header chrome — the column drag grip — stays.)
+    expect(status.querySelector('[class*="chevron"]')).toBeNull();
+  });
+
+  it('honours a column that opts out of sorting', () => {
+    // How a relational column is withheld: its label is a related record's
+    // name, but a server `$orderby` can only order by the stored id (#3096).
+    const onSortChange = vi.fn();
+    const { container } = renderComponent({
+      ...baseSchema,
+      columns: [columns[0], { ...columns[1], sortable: false }],
+      onSortChange,
+    });
+
+    fireEvent.click(headerCell(container, 'Status'));
+    expect(onSortChange).not.toHaveBeenCalled();
+  });
+
+  it('leaves client-side sorting exactly as it was', () => {
+    // No `manualSorting`: the table owns the rows, so it sorts them and keeps
+    // its three-state cycle. This mode is untouched by #3106.
+    const { container } = renderComponent({
+      type: 'data-table',
+      columns,
+      data: pageData,
+    } as any);
+
+    fireEvent.click(headerCell(container, 'Status'));
+    expect(rowOrder(container)).toEqual(['Bravo', 'Charlie', 'Alpha']); // done, hold, open
+
+    fireEvent.click(headerCell(container, 'Status'));
+    expect(rowOrder(container)).toEqual(['Alpha', 'Charlie', 'Bravo']); // open, hold, done
+
+    fireEvent.click(headerCell(container, 'Status'));
+    expect(rowOrder(container)).toEqual(['Alpha', 'Bravo', 'Charlie']); // cleared
+  });
+});
diff --git a/packages/components/src/renderers/complex/data-table.tsx b/packages/components/src/renderers/complex/data-table.tsx
index 3a48786e6..6d58566cc 100644
--- a/packages/components/src/renderers/complex/data-table.tsx
+++ b/packages/components/src/renderers/complex/data-table.tsx
@@ -12,7 +12,7 @@ import { cn } from '../../lib/utils';
 import { resolveIcon } from '../action/resolve-icon';
 import { useGridFieldAuthoring } from '../../context/gridFieldAuthoring';
 import { ComponentRegistry, compareSortValues, getSortValue } from '@object-ui/core';
-import type { DataTableSchema } from '@object-ui/types';
+import type { DataTableSchema, TableSortItem } from '@object-ui/types';
 import { useRowPredicate } from '@object-ui/react';
 import { createSafeTranslation } from '@object-ui/i18n';
 import { 
@@ -361,6 +361,9 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
     page: controlledPage,
     onPageChange,
     onPageSizeChange,
+    manualSorting = false,
+    sort: controlledSort,
+    onSortChange,
     searchable = true,
     selectable: selectableProp = false,
     showSelectionCount = true,
@@ -601,6 +604,12 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
 
   // Sorting — client-side, over the rows this table was handed.
   //
+  // Under `manualSorting` there is nothing to do: `data` arrived in the order
+  // the server produced, for the whole collection rather than this window.
+  // Re-sorting it here would order the CURRENT PAGE — the defect objectui#3106
+  // reports, where "sorted by this column" is true of fifty rows and false of
+  // the list they came from.
+  //
   // Sort keys go through `getSortValue` so a relational column orders by the
   // label its cell shows, not by the `$expand`-ed record object (objectui#3096).
   // The old `aValue < bValue` was always false for two objects, so a lookup
@@ -610,6 +619,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
   // Decorate → sort → undecorate: the key is resolved ONCE per row rather than
   // on every one of the O(n log n) comparisons.
   const sortedData = useMemo(() => {
+    if (manualSorting) return filteredData;
     if (!sortColumn || !sortDirection) return filteredData;
 
     const keyed = filteredData.map((row) => ({ row, key: getSortValue(row[sortColumn]) }));
@@ -619,7 +629,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
       return sortDirection === 'asc' ? comparison : -comparison;
     });
     return keyed.map((entry) => entry.row);
-  }, [filteredData, sortColumn, sortDirection]);
+  }, [filteredData, sortColumn, sortDirection, manualSorting]);
 
   // Pagination. Under manual (server-side) pagination the parent controls the
   // page and supplies the grand total via `rowCount`; `data` already IS the
@@ -678,10 +688,54 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
     return row.id !== undefined ? row.id : `row-${index}`;
   };
 
+  // The sort the headers display and cycle.
+  //
+  // Under `manualSorting` this is the caller's prop and nothing else — the two
+  // `useState`s below are not read, not written, and not mirrored. Keeping a
+  // private copy in sync with a controlled prop is precisely how objectui#3106
+  // happened: the table held the user's sort somewhere the layer that fetches
+  // the rows could not see it.
+  const activeSort: TableSortItem[] = manualSorting
+    ? (controlledSort ?? [])
+    : (sortColumn && sortDirection ? [{ field: sortColumn, order: sortDirection }] : []);
+
+  // A manual-sorting table with nowhere to report a click renders inert headers
+  // rather than clickable ones that do nothing — a dead affordance is the same
+  // class of lie as a sort that only covers the current page.
+  const sortingEnabled = sortable && (!manualSorting || !!onSortChange);
+
+  /**
+   * Sort by one column in a given direction — the single write path, so the
+   * column-header cycle and the header context menu cannot diverge about where
+   * a sort goes. The menu used to call `setSortColumn`/`setSortDirection`
+   * directly, which under `manualSorting` would have written to state nothing
+   * reads: a menu item that highlights, closes, and changes nothing.
+   */
+  const applySort = (columnKey: string, order: 'asc' | 'desc') => {
+    if (manualSorting) {
+      onSortChange?.([{ field: columnKey, order }]);
+      return;
+    }
+    setSortColumn(columnKey);
+    setSortDirection(order);
+  };
+
   // Handlers
   const handleSort = (columnKey: string) => {
-    if (!sortable) return;
-    
+    if (!sortingEnabled) return;
+
+    if (manualSorting) {
+      // Two states, not three. A header click REPLACES the order — the column
+      // under the cursor becomes the one the list is sorted by — and it never
+      // produces "no sort": across a server-paged collection that is an
+      // arbitrary order per page (objectstack#4363), so it is not a state a
+      // header should be able to ask for. Clearing a sort belongs to the host's
+      // sort builder, which can also restore the view's configured default.
+      const current = activeSort.find((s) => s.field === columnKey);
+      applySort(columnKey, current?.order === 'asc' ? 'desc' : 'asc');
+      return;
+    }
+
     if (sortColumn === columnKey) {
       if (sortDirection === 'asc') {
         setSortDirection('desc');
@@ -773,14 +827,31 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
     window.URL.revokeObjectURL(url);
   };
 
+  /**
+   * The indicator for one column, read from {@link activeSort}.
+   *
+   * Every participating key is marked, not just the first: a multi-key sort
+   * arrives from the host's sort builder, and showing only its primary column
+   * would say "sorted by Status" about a list actually ordered by Status then
+   * Rank. The rank badge appears only when there is more than one key, so the
+   * ordinary single-column case renders exactly as it always has.
+   */
   const getSortIcon = (columnKey: string) => {
-    if (sortColumn !== columnKey) {
+    const index = activeSort.findIndex((s) => s.field === columnKey);
+    if (index === -1) {
       return <ChevronsUpDown className="h-3 w-3 ml-0.5 opacity-0 group-hover:opacity-50 transition-opacity" />;
     }
-    if (sortDirection === 'asc') {
-      return <ChevronUp className="h-3 w-3 ml-0.5 text-primary" />;
-    }
-    return <ChevronDown className="h-3 w-3 ml-0.5 text-primary" />;
+    const Arrow = activeSort[index].order === 'asc' ? ChevronUp : ChevronDown;
+    return (
+      <span className="inline-flex items-center shrink-0">
+        <Arrow className="h-3 w-3 ml-0.5 text-primary" />
+        {activeSort.length > 1 && (
+          <span className="text-[10px] font-medium text-primary tabular-nums leading-none">
+            {index + 1}
+          </span>
+        )}
+      </span>
+    );
   };
 
   // Column resizing handlers
@@ -1374,7 +1445,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
                     key={col.accessorKey}
                     className={cn(
                       col.className,
-                      sortable && col.sortable !== false && 'cursor-pointer select-none',
+                      sortingEnabled && col.sortable !== false && 'cursor-pointer select-none',
                       isDragging && 'opacity-50',
                       isDragOver && 'border-l-2 border-primary',
                       col.align === 'right' && 'text-right',
@@ -1401,7 +1472,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
                     onDragOver={(e) => handleColumnDragOver(e, index)}
                     onDrop={(e) => handleColumnDrop(e, index)}
                     onDragEnd={handleColumnDragEnd}
-                    onClick={() => sortable && col.sortable !== false && handleSort(col.accessorKey)}
+                    onClick={() => sortingEnabled && col.sortable !== false && handleSort(col.accessorKey)}
                     onContextMenu={(e) => handleColumnContextMenu(e, col.accessorKey)}
                   >
                     <div className={cn(
@@ -1416,7 +1487,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
                           <span className="text-muted-foreground shrink-0">{col.headerIcon}</span>
                         )}
                         <span className="text-xs font-medium text-muted-foreground whitespace-nowrap truncate">{col.header}</span>
-                        {sortable && col.sortable !== false && getSortIcon(col.accessorKey)}
+                        {sortingEnabled && col.sortable !== false && getSortIcon(col.accessorKey)}
                         {editColumnEnabled && (
                           <button
                             type="button"
@@ -2019,14 +2090,13 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
           data-testid="column-context-menu"
           onClick={(e) => e.stopPropagation()}
         >
-          {sortable && (
+          {sortingEnabled && (
             <>
               <button
                 type="button"
                 className="flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-sm hover:bg-accent hover:text-accent-foreground cursor-pointer"
                 onClick={() => {
-                  setSortColumn(contextMenu.columnKey);
-                  setSortDirection('asc');
+                  applySort(contextMenu.columnKey, 'asc');
                   setContextMenu(null);
                 }}
               >
@@ -2037,8 +2107,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
                 type="button"
                 className="flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-sm hover:bg-accent hover:text-accent-foreground cursor-pointer"
                 onClick={() => {
-                  setSortColumn(contextMenu.columnKey);
-                  setSortDirection('desc');
+                  applySort(contextMenu.columnKey, 'desc');
                   setContextMenu(null);
                 }}
               >
diff --git a/packages/plugin-grid/src/ObjectGrid.tsx b/packages/plugin-grid/src/ObjectGrid.tsx
index 98b7ae534..298808244 100644
--- a/packages/plugin-grid/src/ObjectGrid.tsx
+++ b/packages/plugin-grid/src/ObjectGrid.tsx
@@ -22,7 +22,7 @@
  */
 
 import React, { useEffect, useState, useCallback, useMemo } from 'react';
-import type { ObjectGridSchema, DataSource, ListColumn, ViewData } from '@object-ui/types';
+import type { ObjectGridSchema, DataSource, ListColumn, ViewData, TableSortItem } from '@object-ui/types';
 import { isSystemManagedField } from '@object-ui/types';
 import type { I18nLabel } from '@objectstack/spec/ui';
 import { SchemaRenderer, useDataScope, useNavigationOverlay, useAction, useSafeFieldLabel, usePredicateScope } from '@object-ui/react';
@@ -36,7 +36,7 @@ import {
   RefreshIndicator,
 } from '@object-ui/components';
 import { usePullToRefresh } from '@object-ui/mobile';
-import { resolveConditionalFormatting, buildExpandFields, buildExportFileName } from '@object-ui/core';
+import { resolveConditionalFormatting, buildExpandFields, buildExportFileName, isExpandableFieldType } from '@object-ui/core';
 import { usePermissions } from '@object-ui/permissions';
 import { ChevronRight, ChevronDown, ChevronLeft, ChevronsLeft, ChevronsRight, Download, Rows2, Rows3, Rows4, AlignJustify, Type, Hash, Calendar, CheckSquare, User, Tag, Clock, Loader2 } from 'lucide-react';
 import { useRowColor } from './useRowColor';
@@ -53,6 +53,33 @@ import { BulkActionDialog } from './components/BulkActionDialog';
 import type { BulkResult } from './hooks/useBulkExecutor';
 import type { BulkActionDef } from '@object-ui/types';
 
+/**
+ * A view's declared `sort` → the shape the table's header indicators read.
+ *
+ * `@objectstack/spec` allows `"name desc"`, `["name desc", …]` and
+ * `[{ field, order }, …]`, and this grid's own fetch path already reads all
+ * three. The headers have to agree with it: a view that arrives sorted by
+ * `created_at desc` should show that arrow before anyone clicks anything —
+ * otherwise the first click on that column produces `asc` while the list was
+ * already `desc`, and the arrow tells the truth only from the second click on.
+ *
+ * Exported for the test that pins it against the fetch path's own reading.
+ */
+export function parseSchemaSort(sort: unknown): TableSortItem[] {
+  const entries = typeof sort === 'string' ? [sort] : Array.isArray(sort) ? sort : [];
+  const items: TableSortItem[] = [];
+  for (const entry of entries) {
+    if (typeof entry === 'string') {
+      const [field, order] = entry.trim().split(/\s+/);
+      if (field) items.push({ field, order: order?.toLowerCase() === 'desc' ? 'desc' : 'asc' });
+    } else if (entry && typeof entry === 'object' && typeof (entry as any).field === 'string') {
+      const { field, order } = entry as { field: string; order?: string };
+      items.push({ field, order: String(order).toLowerCase() === 'desc' ? 'desc' : 'asc' });
+    }
+  }
+  return items;
+}
+
 // Clickable text cell that can safely contain other interactive content
 // (e.g., EmailCellRenderer's copy button). Using <button> here would
 // produce an invalid <button> > <button> nesting (hydration error +
@@ -416,6 +443,15 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
     (schema.pagination as any)?.pageSize ?? schema.pageSize ?? 50,
   );
 
+  // Column-header sort, when this grid fetches its own rows (objectui#3106).
+  // `null` means "nobody has clicked a header" and the view's declared
+  // `schema.sort` is in force; once set it REPLACES that sort for the whole
+  // collection, not for the window on screen.
+  const [headerSort, setHeaderSort] = useState<TableSortItem[] | null>(null);
+  // A view whose declared sort changes underneath us (view switch, saved-view
+  // edit) invalidates a header sort taken against the previous one.
+  useEffect(() => { setHeaderSort(null); }, [JSON.stringify(schema.sort ?? null)]);
+
   // --- Inline data effect (synchronous, no fetch needed) ---
   useEffect(() => {
     if (hasInlineData && dataConfig?.provider === 'value') {
@@ -532,8 +568,15 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
             params.$filter = schema.defaultFilters;
           }
 
-          // Support new sort format
-          if (schemaSort) {
+          // Sort. A column-header click (objectui#3106) replaces the view's
+          // declared sort for the whole collection — which is what makes the
+          // arrow in the header true of the list rather than of this page.
+          // The `SortNode[]` form goes out rather than the `"field order"`
+          // string: it is the shape the server names in its own error messages,
+          // and it survives a field name containing a space.
+          if (headerSort && headerSort.length > 0) {
+            params.$orderby = headerSort.map((s) => ({ field: s.field, order: s.order }));
+          } else if (schemaSort) {
             if (typeof schemaSort === 'string') {
               params.$orderby = schemaSort;
             } else if (Array.isArray(schemaSort)) {
@@ -580,7 +623,7 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
     return () => {
       cancelled = true;
     };
-  }, [objectName, schemaFields, schemaColumns, schemaFilter, schemaSort, schemaPagination, schemaPageSize, serverPage, serverPageSize, dataSource, hasInlineData, dataConfig, refreshKey]);
+  }, [objectName, schemaFields, schemaColumns, schemaFilter, schemaSort, headerSort, schemaPagination, schemaPageSize, serverPage, serverPageSize, dataSource, hasInlineData, dataConfig, refreshKey]);
 
   // Reset to page 1 whenever the query itself changes (object / filter / sort),
   // so we never request a page index that no longer exists for the new result
@@ -588,7 +631,7 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
   React.useEffect(() => {
     setServerPage(1);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [objectName, schemaFilter, schemaSort]);
+  }, [objectName, schemaFilter, schemaSort, headerSort]);
 
   // --- NavigationConfig support ---
   // Must be called before any early returns to satisfy React hooks rules
@@ -1602,17 +1645,64 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
     cellClassName: [rowHeightCellClass, col.cellClassName].filter(Boolean).join(' '),
   });
 
+  // Server-side pagination applies to the flat, server-fetched list only.
+  // Inline/static data and the grouped view paginate in-memory (grouped mode
+  // keeps whole groups together via its own groupedPage state), so they stay
+  // on DataTable's default client-side slicing.
+  //
+  // Declared here rather than beside the rest of the manual-mode wiring below
+  // because `orderedColumns` needs it: which columns may be sorted at all
+  // depends on whether the sort is the server's.
+  const useServerPagination = !hasInlineData && !isGrouped;
+
+  // Either we own the server fetch (useServerPagination) or a parent does
+  // (externalManualPagination). Grouped mode always keeps in-memory slicing so
+  // whole groups stay together. Both server modes feed DataTable a manual pager
+  // backed by the real match total.
+  const manualPaginationOn = (useServerPagination || externalManualPagination) && !isGrouped;
+
+  // Server-side sorting, in either of the two server modes (objectui#3106).
+  //
+  // Tied to who owns the ROWS, not to who owns the pager: whenever `data` is
+  // one window of a larger collection, sorting it in the browser orders that
+  // window and nothing else. Grouped mode holds every row it groups, so it
+  // keeps DataTable's own client-side sort.
+  const manualSortingOn = manualPaginationOn;
+
+  /**
+   * Withhold the sort affordance from a relational column when the sort is the
+   * server's (objectui#3096 + #3106).
+   *
+   * A `lookup` / `master_detail` / `user` / `tree` column stores a foreign-key
+   * id and shows the related record's name. A server `$orderby` can only order
+   * by the stored id — objectstack#4256 settled that no relation join is coming
+   * — so the column of names would come back in an order with no relation to
+   * the names. The ListView toolbar's sort picker already withholds these for
+   * exactly this reason; a clickable header would have been the same illusion
+   * through a different control.
+   *
+   * Only under manual sorting. A client-side sort keys off the label the cell
+   * renders (`getSortValue`, #3096), which is honest, so those headers stay.
+   */
+  const withSortability = (col: any) => {
+    if (!manualSortingOn || col.sortable === false) return col;
+    const fieldDef = (objectSchema as any)?.fields?.[col.accessorKey];
+    return isExpandableFieldType(fieldDef) ? { ...col, sortable: false } : col;
+  };
+
+  const applyColumnChrome = (col: any) => withSortability(applyDensity(col));
+
   const orderedColumns = hasPinnedColumns
     ? [
-        ...pinnedLeftCols.map(applyDensity),
-        ...unpinnedCols.map(applyDensity),
+        ...pinnedLeftCols.map(applyColumnChrome),
+        ...unpinnedCols.map(applyColumnChrome),
         ...pinnedRightCols.map((col: any) => ({
-          ...applyDensity(col),
+          ...applyColumnChrome(col),
           className: ['px-3', col.className, rightPinnedClasses].filter(Boolean).join(' '),
           cellClassName: [rowHeightCellClass, col.cellClassName, rightPinnedClasses].filter(Boolean).join(' '),
         })),
       ]
-    : columnsWithActions.map(applyDensity);
+    : columnsWithActions.map(applyColumnChrome);
 
   // Calculate frozenColumns: if the USER pinned columns, use their left-pinned
   // count; otherwise fall back to the schema default (freeze the first column).
@@ -1885,17 +1975,6 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
     ? schema.searchableFields.length > 0
     : (schema.showSearch !== undefined ? schema.showSearch : true);
 
-  // Server-side pagination applies to the flat, server-fetched list only.
-  // Inline/static data and the grouped view paginate in-memory (grouped mode
-  // keeps whole groups together via its own groupedPage state), so they stay
-  // on DataTable's default client-side slicing.
-  const useServerPagination = !hasInlineData && !isGrouped;
-
-  // Either we own the server fetch (useServerPagination) or a parent does
-  // (externalManualPagination). Grouped mode always keeps in-memory slicing so
-  // whole groups stay together. Both server modes feed DataTable a manual pager
-  // backed by the real match total.
-  const manualPaginationOn = (useServerPagination || externalManualPagination) && !isGrouped;
   const manualRowCount = externalManualPagination ? (rest as any).rowCount : totalMatching;
   const manualPage = externalManualPagination ? (rest as any).page : serverPage;
   const manualPageSize = externalManualPagination
@@ -1908,6 +1987,26 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
     ? (rest as any).onPageSizeChange
     : (size: number) => { setServerPageSize(size); setServerPage(1); };
 
+  // Before anyone clicks, the headers show the sort the view was authored with
+  // — read with the same `schemaSort` → `defaultSort` precedence the fetch path
+  // above uses, so the arrow on screen and the `$orderby` on the wire are the
+  // same sort. Without that a view arriving `created_at desc` would show no
+  // arrow, and the first click on that column would ask for `asc` on a list
+  // that was already `desc`.
+  //
+  // A plain expression, not a `useMemo`: this sits below the component's early
+  // returns, where a hook would be skipped on some renders and change the hook
+  // order. Parsing at most a handful of sort keys costs nothing worth a hook.
+  const declaredSort = parseSchemaSort(
+    schemaSort ?? (schema.defaultSort ? [schema.defaultSort] : undefined),
+  );
+  const manualSort: TableSortItem[] = externalManualPagination
+    ? ((rest as any).sort ?? [])
+    : (headerSort ?? declaredSort);
+  const manualOnSortChange = externalManualPagination
+    ? (rest as any).onSortChange
+    : setHeaderSort;
+
   const dataTableSchema: any = {
     type: 'data-table',
     caption: schema.label || schema.title,
@@ -1927,6 +2026,9 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
     page: manualPaginationOn ? manualPage : undefined,
     onPageChange: manualPaginationOn ? manualOnPageChange : undefined,
     onPageSizeChange: manualPaginationOn ? manualOnPageSizeChange : undefined,
+    manualSorting: manualSortingOn,
+    sort: manualSortingOn ? manualSort : undefined,
+    onSortChange: manualSortingOn ? manualOnSortChange : undefined,
     searchable: searchEnabled,
     selectable: selectionMode,
     // ObjectGrid surfaces the selection via its own bottom BulkActionBar
diff --git a/packages/plugin-grid/src/__tests__/serverSorting.test.tsx b/packages/plugin-grid/src/__tests__/serverSorting.test.tsx
new file mode 100644
index 000000000..468d09856
--- /dev/null
+++ b/packages/plugin-grid/src/__tests__/serverSorting.test.tsx
@@ -0,0 +1,212 @@
+/**
+ * Column-header sorting reaches the server (objectui#3106).
+ *
+ * Before the fix, DataTable's header sort was internal state with no callback
+ * out of the component, so under server pagination it reordered the fifty rows
+ * on screen and stopped there. The list looked sorted by that column; page 2
+ * started over. Nothing said so.
+ *
+ * After the fix a header click becomes a `$orderby` on the refetch — the sort
+ * applies to the whole collection — and the grid returns to page 1, because a
+ * new ordering makes "page 5" a different set of rows.
+ *
+ * The relational-column half is #3096's: a `lookup` column shows a related
+ * record's name while the server can only order by the stored id
+ * (objectstack#4256 settled that no join is coming), so those headers are
+ * withheld rather than offered as an ordering by something invisible.
+ */
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import React from 'react';
+
+import { ObjectGrid, parseSchemaSort } from '../ObjectGrid';
+import { registerAllFields } from '@object-ui/fields';
+import { ActionProvider } from '@object-ui/react';
+
+registerAllFields();
+
+beforeAll(() => {
+  if (!Element.prototype.hasPointerCapture) {
+    Element.prototype.hasPointerCapture = vi.fn(() => false) as any;
+  }
+  if (!Element.prototype.scrollIntoView) {
+    Element.prototype.scrollIntoView = vi.fn() as any;
+  }
+});
+
+const TOTAL = 300;
+const PAGE_SIZE = 50;
+
+function makeDataSource() {
+  const find = vi.fn(async (_object: string, params: any) => {
+    const top = params.$top ?? PAGE_SIZE;
+    const skip = params.$skip ?? 0;
+    const rows = Array.from({ length: Math.max(0, Math.min(top, TOTAL - skip)) }, (_, i) => ({
+      id: `id-${skip + i}`,
+      name: `Row ${skip + i}`,
+      status: 'open',
+      owner: { id: 'u1', name: 'Ada' },
+    }));
+    return { data: rows, total: TOTAL, hasMore: skip + rows.length < TOTAL, pageSize: top };
+  });
+  return {
+    find,
+    getObjectSchema: async (name: string) => ({
+      name,
+      fields: {
+        id: { type: 'text' },
+        name: { type: 'text' },
+        status: { type: 'text' },
+        owner: { type: 'lookup', reference_to: 'user' },
+      },
+    }),
+  } as any;
+}
+
+function renderGrid(dataSource: any, opts?: Record<string, any>) {
+  const schema: any = {
+    type: 'object-grid',
+    objectName: 'task',
+    columns: [
+      { field: 'name', label: 'Name' },
+      { field: 'status', label: 'Status' },
+      { field: 'owner', label: 'Owner' },
+    ],
+    pagination: { pageSize: PAGE_SIZE },
+    ...opts,
+  };
+  return render(
+    <ActionProvider>
+      <ObjectGrid schema={schema} dataSource={dataSource} />
+    </ActionProvider>,
+  );
+}
+
+const lastFindParams = (ds: any) => ds.find.mock.calls[ds.find.mock.calls.length - 1][1];
+
+const headerCell = (container: HTMLElement, label: string) =>
+  Array.from(container.querySelectorAll('thead th')).find((th) =>
+    th.textContent?.includes(label),
+  ) as HTMLElement;
+
+describe('ObjectGrid — column-header sorting is server-side (#3106)', () => {
+  it('turns a header click into an $orderby on the refetch', async () => {
+    const ds = makeDataSource();
+    const { container } = renderGrid(ds);
+    await waitFor(() => expect(screen.getByText('Row 0')).toBeInTheDocument());
+
+    fireEvent.click(headerCell(container, 'Status'));
+
+    await waitFor(() => {
+      expect(lastFindParams(ds).$orderby).toEqual([{ field: 'status', order: 'asc' }]);
+    });
+  });
+
+  it('toggles to descending on the second click', async () => {
+    const ds = makeDataSource();
+    const { container } = renderGrid(ds);
+    await waitFor(() => expect(screen.getByText('Row 0')).toBeInTheDocument());
+
+    fireEvent.click(headerCell(container, 'Status'));
+    await waitFor(() => expect(lastFindParams(ds).$orderby).toEqual([{ field: 'status', order: 'asc' }]));
+
+    fireEvent.click(headerCell(container, 'Status'));
+    await waitFor(() => expect(lastFindParams(ds).$orderby).toEqual([{ field: 'status', order: 'desc' }]));
+  });
+
+  it('returns to page 1 — a new ordering makes the old page index a different set of rows', async () => {
+    const ds = makeDataSource();
+    const { container } = renderGrid(ds);
+    await waitFor(() => expect(screen.getByText('Row 0')).toBeInTheDocument());
+
+    // Advance off page 1 first (last-page button guarantees a forward jump).
+    const navButtons = Array.from(container.querySelectorAll('button')).filter(
+      (b) => !(b as HTMLButtonElement).disabled,
+    );
+    fireEvent.click(navButtons[navButtons.length - 1]);
+    await waitFor(() => expect(lastFindParams(ds).$skip).toBeGreaterThan(0));
+
+    fireEvent.click(headerCell(container, 'Status'));
+
+    await waitFor(() => {
+      const p = lastFindParams(ds);
+      expect(p.$orderby).toEqual([{ field: 'status', order: 'asc' }]);
+      expect(p.$skip ?? 0).toBe(0);
+    });
+  });
+
+  it('replaces the view\'s declared sort rather than stacking on it', async () => {
+    const ds = makeDataSource();
+    const { container } = renderGrid(ds, { sort: 'name desc' });
+    await waitFor(() => expect(screen.getByText('Row 0')).toBeInTheDocument());
+    // The declared sort goes out as the string form it was authored in.
+    expect(lastFindParams(ds).$orderby).toBe('name desc');
+
+    fireEvent.click(headerCell(container, 'Status'));
+
+    await waitFor(() => {
+      expect(lastFindParams(ds).$orderby).toEqual([{ field: 'status', order: 'asc' }]);
+    });
+  });
+
+  it('shows the view\'s declared sort before anyone clicks', async () => {
+    // Otherwise the first click on that column asks for `asc` on a list that is
+    // already `desc`, and the arrow only tells the truth from click two on.
+    const ds = makeDataSource();
+    const { container } = renderGrid(ds, { sort: 'status desc' });
+    await waitFor(() => expect(screen.getByText('Row 0')).toBeInTheDocument());
+
+    expect(headerCell(container, 'Status').querySelector('[class*="chevron-down"]')).not.toBeNull();
+
+    // …and clicking it therefore toggles to ascending rather than restating desc.
+    fireEvent.click(headerCell(container, 'Status'));
+    await waitFor(() => {
+      expect(lastFindParams(ds).$orderby).toEqual([{ field: 'status', order: 'asc' }]);
+    });
+  });
+
+  it('withholds the sort affordance from a relational column (#3096)', async () => {
+    const ds = makeDataSource();
+    const { container } = renderGrid(ds);
+    await waitFor(() => expect(screen.getByText('Row 0')).toBeInTheDocument());
+
+    const owner = headerCell(container, 'Owner');
+    expect(owner.className).not.toContain('cursor-pointer');
+
+    const before = ds.find.mock.calls.length;
+    fireEvent.click(owner);
+    // No refetch: the click is not a sort request.
+    await new Promise((r) => setTimeout(r, 20));
+    expect(ds.find.mock.calls.length).toBe(before);
+  });
+});
+
+describe('parseSchemaSort — the header reads what the fetch path reads', () => {
+  it('reads the bare-string form', () => {
+    expect(parseSchemaSort('name desc')).toEqual([{ field: 'name', order: 'desc' }]);
+  });
+
+  it('defaults an omitted direction to ascending', () => {
+    expect(parseSchemaSort('name')).toEqual([{ field: 'name', order: 'asc' }]);
+  });
+
+  it('reads the array-of-strings form', () => {
+    expect(parseSchemaSort(['status asc', 'name desc'])).toEqual([
+      { field: 'status', order: 'asc' },
+      { field: 'name', order: 'desc' },
+    ]);
+  });
+
+  it('reads the SortNode[] form', () => {
+    expect(parseSchemaSort([{ field: 'name', order: 'desc' }])).toEqual([
+      { field: 'name', order: 'desc' },
+    ]);
+  });
+
+  it('yields nothing for an absent or unreadable sort', () => {
+    expect(parseSchemaSort(undefined)).toEqual([]);
+    expect(parseSchemaSort(null)).toEqual([]);
+    expect(parseSchemaSort(42)).toEqual([]);
+  });
+});
diff --git a/packages/plugin-list/src/ListView.tsx b/packages/plugin-list/src/ListView.tsx
index 61a3b9ffa..15fba7c4e 100644
--- a/packages/plugin-list/src/ListView.tsx
+++ b/packages/plugin-list/src/ListView.tsx
@@ -1780,6 +1780,32 @@ export const ListView = React.forwardRef<ListViewHandle, ListViewProps>(({
     return { sortFields: fields, sortHasRelationalField: excluded };
   }, [filterFields, currentSort, t]);
 
+  /**
+   * A column-header sort from the child grid (#3106).
+   *
+   * It lands in `currentSort` — the same state the toolbar's sort builder
+   * writes — so it becomes a server `$orderby` over the whole collection and
+   * the two controls can never disagree about what the list is sorted by. The
+   * table hands back `{field, order}`; `SortItem` carries an `id` for the
+   * builder's React keys, so one is minted here exactly as `parseSortConfig`
+   * does when reading a view's declared sort.
+   *
+   * The page goes back to 1: a new order makes "page 5" a different set of
+   * rows, and staying there would show a slice of an ordering the user has not
+   * seen the start of. `onSortChange` fires so a host persists this the same
+   * way it persists a builder edit — a header sort is not a lesser sort.
+   */
+  const handleHeaderSort = React.useCallback((next: Array<{ field: string; order: 'asc' | 'desc' }>) => {
+    const items: SortItem[] = next.map((s) => ({
+      id: crypto.randomUUID(),
+      field: s.field,
+      order: s.order,
+    }));
+    setCurrentSort(items);
+    setServerPage(1);
+    onSortChange?.(items);
+  }, [onSortChange]);
+
   // Export handler
   const handleExport = React.useCallback((format: 'csv' | 'xlsx' | 'json' | 'pdf') => {
     // Object-level export permission gate. Default-allow.
@@ -2679,6 +2705,14 @@ export const ListView = React.forwardRef<ListViewHandle, ListViewProps>(({
                   pageSize: effectivePageSize,
                   onPageChange: (p: number) => setServerPage(p),
                   onPageSizeChange: (n: number) => { setDynamicPageSize(n); setServerPage(1); },
+                  // …and its sort from the same place (#3106). The column
+                  // headers and the toolbar's sort builder are two controls over
+                  // ONE `currentSort`, so a header click is a shortcut into the
+                  // builder rather than a second, page-local sort with its own
+                  // rules. That is what makes "priority of a header sort vs. the
+                  // saved view's sort" a non-question: there is one sort.
+                  sort: currentSort,
+                  onSortChange: handleHeaderSort,
                 }
               : {})}
           />
diff --git a/packages/plugin-list/src/__tests__/ListView.headerSort.test.tsx b/packages/plugin-list/src/__tests__/ListView.headerSort.test.tsx
new file mode 100644
index 000000000..02e1c45d0
--- /dev/null
+++ b/packages/plugin-list/src/__tests__/ListView.headerSort.test.tsx
@@ -0,0 +1,188 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * A column-header sort from the child grid becomes THE view's sort (#3106).
+ *
+ * ListView fetches the rows and hands one window down to the grid, so a sort
+ * the grid applied to that window would order fifty rows and claim to have
+ * ordered the list. The header's sort now lands in `currentSort` — the same
+ * state the toolbar's sort builder writes — which makes it a server `$orderby`
+ * over the whole collection.
+ *
+ * Sharing that one state is also what makes "does a header sort outrank the
+ * saved view's sort?" a non-question: there is one sort, with two controls onto
+ * it, so they cannot disagree and there is no precedence to define.
+ *
+ * plugin-grid is not a dependency of plugin-list (that would be a cycle), so
+ * this registers a stub `object-grid` that captures what ListView hands it and
+ * lets the test invoke `onSortChange` — the composition neither package's own
+ * unit tests can reach.
+ */
+import { describe, it, expect, vi, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import { act, cleanup, render, waitFor } from '@testing-library/react';
+import React from 'react';
+import { ComponentRegistry } from '@object-ui/core';
+import { ListView } from '../ListView';
+import { SchemaRendererProvider } from '@object-ui/react';
+import type { ListViewSchema } from '@object-ui/types';
+
+const TOTAL = 3125;
+const PAGE_SIZE = 50;
+
+let lastGridProps: any = null;
+
+function makeDataSource() {
+  const find = vi.fn(async (_object: string, params: any) => {
+    const top = params.$top ?? PAGE_SIZE;
+    const skip = params.$skip ?? 0;
+    const rows = Array.from(
+      { length: Math.max(0, Math.min(top, TOTAL - skip)) },
+      (_, i) => ({ id: `id-${skip + i}`, name: `Row ${skip + i}` }),
+    );
+    return { data: rows, total: TOTAL, hasMore: skip + rows.length < TOTAL };
+  });
+  return {
+    find,
+    findOne: vi.fn(),
+    create: vi.fn(),
+    update: vi.fn(),
+    delete: vi.fn(),
+    getObjectSchema: async (name: string) => ({
+      name,
+      fields: { id: { type: 'text' }, name: { type: 'text' }, status: { type: 'text' } },
+    }),
+  } as any;
+}
+
+const schema: ListViewSchema = {
+  type: 'list-view',
+  objectName: 'task',
+  fields: ['name', 'status'],
+  pagination: { pageSize: PAGE_SIZE },
+} as any;
+
+const lastFindParams = (ds: any) => ds.find.mock.calls[ds.find.mock.calls.length - 1][1];
+
+let prevObjectGrid: any;
+beforeAll(() => {
+  prevObjectGrid = ComponentRegistry.get('object-grid');
+  ComponentRegistry.register('object-grid', (props: any) => {
+    lastGridProps = props;
+    return <div data-testid="grid-stub" />;
+  });
+});
+afterAll(() => {
+  if (prevObjectGrid) ComponentRegistry.register('object-grid', prevObjectGrid);
+  else ComponentRegistry.unregister('object-grid');
+});
+
+beforeEach(() => { lastGridProps = null; });
+afterEach(() => { cleanup(); lastGridProps = null; });
+
+function renderList(ds: any, overrides?: Partial<ListViewSchema>) {
+  return render(
+    <SchemaRendererProvider dataSource={ds}>
+      <ListView schema={{ ...schema, ...overrides } as ListViewSchema} dataSource={ds} />
+    </SchemaRendererProvider>,
+  );
+}
+
+describe('ListView — a column-header sort becomes the view sort (#3106)', () => {
+  it('hands the grid the controlled sort and a way to report one', async () => {
+    const ds = makeDataSource();
+    renderList(ds);
+    await waitFor(() => expect(lastGridProps?.manualPagination).toBe(true));
+    expect(Array.isArray(lastGridProps.sort)).toBe(true);
+    expect(typeof lastGridProps.onSortChange).toBe('function');
+  });
+
+  it('refetches the WHOLE collection with the requested $orderby', async () => {
+    const ds = makeDataSource();
+    renderList(ds);
+    await waitFor(() => expect(typeof lastGridProps?.onSortChange).toBe('function'));
+
+    await act(async () => {
+      lastGridProps.onSortChange([{ field: 'status', order: 'desc' }]);
+    });
+
+    await waitFor(() => {
+      expect(lastFindParams(ds).$orderby).toEqual([{ field: 'status', order: 'desc' }]);
+    });
+  });
+
+  it('returns to page 1 — a new ordering makes the old page a different set of rows', async () => {
+    const ds = makeDataSource();
+    renderList(ds);
+    await waitFor(() => expect(typeof lastGridProps?.onPageChange).toBe('function'));
+
+    await act(async () => { lastGridProps.onPageChange(4); });
+    await waitFor(() => expect(lastFindParams(ds).$skip).toBeGreaterThan(0));
+
+    await act(async () => {
+      lastGridProps.onSortChange([{ field: 'status', order: 'asc' }]);
+    });
+
+    await waitFor(() => {
+      const p = lastFindParams(ds);
+      expect(p.$orderby).toEqual([{ field: 'status', order: 'asc' }]);
+      expect(p.$skip ?? 0).toBe(0);
+    });
+  });
+
+  it('feeds the sort straight back down, so the header renders what the server was asked for', async () => {
+    const ds = makeDataSource();
+    renderList(ds);
+    await waitFor(() => expect(typeof lastGridProps?.onSortChange).toBe('function'));
+
+    await act(async () => {
+      lastGridProps.onSortChange([{ field: 'status', order: 'desc' }]);
+    });
+
+    await waitFor(() => {
+      expect(lastGridProps.sort).toEqual([
+        expect.objectContaining({ field: 'status', order: 'desc' }),
+      ]);
+    });
+  });
+
+  it('REPLACES the view\'s declared sort rather than stacking on it', async () => {
+    const ds = makeDataSource();
+    renderList(ds, { sort: 'name asc' } as any);
+    await waitFor(() => expect(typeof lastGridProps?.onSortChange).toBe('function'));
+
+    await act(async () => {
+      lastGridProps.onSortChange([{ field: 'status', order: 'desc' }]);
+    });
+
+    await waitFor(() => {
+      expect(lastFindParams(ds).$orderby).toEqual([{ field: 'status', order: 'desc' }]);
+    });
+  });
+
+  it('reports the sort through onSortChange, so a host persists it like a builder edit', async () => {
+    // A header sort is not a lesser sort: whatever a host does to remember the
+    // toolbar's sort, it does with this one.
+    const onSortChange = vi.fn();
+    const ds = makeDataSource();
+    render(
+      <SchemaRendererProvider dataSource={ds}>
+        <ListView schema={schema} dataSource={ds} onSortChange={onSortChange} />
+      </SchemaRendererProvider>,
+    );
+    await waitFor(() => expect(typeof lastGridProps?.onSortChange).toBe('function'));
+
+    await act(async () => {
+      lastGridProps.onSortChange([{ field: 'status', order: 'asc' }]);
+    });
+
+    expect(onSortChange).toHaveBeenCalledWith([
+      expect.objectContaining({ field: 'status', order: 'asc' }),
+    ]);
+  });
+});
diff --git a/packages/types/src/data-display.ts b/packages/types/src/data-display.ts
index 1c080ef6c..48d838372 100644
--- a/packages/types/src/data-display.ts
+++ b/packages/types/src/data-display.ts
@@ -198,6 +198,20 @@ export interface ListItem {
   content?: SchemaNode | SchemaNode[];
 }
 
+/**
+ * One key of a table's sort order.
+ *
+ * Structurally the id-less half of `SortItem` in `@object-ui/components` (whose
+ * `id` exists only as a React key for the sort-builder rows), so a `SortItem[]`
+ * is assignable here without conversion. This package takes no dependencies, so
+ * the shared shape is declared rather than imported.
+ */
+export interface TableSortItem {
+  /** Field to sort by — an `accessorKey` of the table's columns. */
+  field: string;
+  order: 'asc' | 'desc';
+}
+
 /**
  * Table column definition
  */
@@ -401,6 +415,50 @@ export interface DataTableSchema extends BaseSchema {
    * Called when the user changes the page size under `manualPagination`.
    */
   onPageSizeChange?: (pageSize: number) => void;
+  /**
+   * Server-side ("manual") sorting. When true the table does NOT sort `data`
+   * locally — it is already in the order the server returned — and a column
+   * header click reports the requested sort through `onSortChange` instead.
+   *
+   * Set this whenever `data` is one window of a larger collection. Sorting a
+   * window locally orders **that page**, which reads on screen as "the list is
+   * sorted by this column" and is not (objectui#3106).
+   *
+   * Deliberately independent of `manualPagination`: a windowed related list
+   * paginates itself (`pagination: false`) while its rows still come from the
+   * server one page at a time.
+   *
+   * The table keeps NO sort state of its own in this mode — `sort` is the only
+   * source of truth, and the header renders and cycles that. A private copy
+   * alongside a controlled prop is how the original defect arose.
+   * @default false
+   */
+  manualSorting?: boolean;
+  /**
+   * The active sort, when `manualSorting` is on. Drives the header indicators
+   * and is the value each header click transforms. Ignored otherwise (the table
+   * owns its sort in client mode).
+   */
+  sort?: TableSortItem[];
+  /**
+   * Called with the sort a header click asks for, when `manualSorting` is on.
+   *
+   * Always exactly one key: a header click REPLACES the order rather than
+   * appending to it, so the column under the cursor is the one the list is
+   * sorted by. Multi-key sorts come from a host's own sort builder, and the
+   * header renders them (numbered) without being able to produce one.
+   *
+   * Never empty. In client mode the third click clears the sort, which is
+   * meaningful there — the rows return to the order they arrived in. Against a
+   * server-paged collection there is no such order to return to: an unsorted
+   * paged read is arbitrary per page (objectstack#4363), so offering it from a
+   * header would hand the user a worse lie than the one being fixed. Removing
+   * a sort entirely stays with the host's sort builder.
+   *
+   * Without this callback the headers render inert (no cursor, no icons) rather
+   * than accepting clicks that go nowhere.
+   */
+  onSortChange?: (sort: TableSortItem[]) => void;
   /**
    * Enable search
    * @default true
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index b1f52fc89..434c8dd4e 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -157,6 +157,7 @@ export type {
   ListSchema,
   ListItem,
   TableColumn,
+  TableSortItem,
   TableSchema,
   DataTableSchema,
   MarkdownSchema,

From e7e0e31771e316b6ede42f7d7efa36815b65db50 Mon Sep 17 00:00:00 2001
From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Date: Fri, 31 Jul 2026 17:36:00 +0800
Subject: [PATCH 2/2] fix(detail): a related list has one sorting semantics
 instead of two (#3106)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A related list carried two. Its own sort-button row (opt-in via `sortable`) went
out as a server `$orderby` over the whole child collection; the `data-table` it
embeds took `sortable`'s default of `true` and sorted the rows it was holding —
which, in windowed mode, is ONE PAGE.

Turning `sortable` on put both in the same card with nothing saying they meant
different things. Leaving it off — the default — was worse: the page-local sort
was then the only one the user could reach, and it looked exactly like the list
being sorted.

The embedded table's column headers now drive this list's sort in both modes:

- Windowed: the header sort becomes the server `$orderby` and resets to page
  one, the same path the buttons took.
- Client mode: this list keeps sorting in memory, where the key is the label
  resolved through its own id → name map (#3096) — a key the table cannot see,
  so its sort was the worse of the two even where both were possible.

The button row survives only where there are no headers to click: a `list`
(`data-list`) related list, or a caller-supplied `schema` whose contents we
cannot assume. `sortable`'s doc comment now says that is what it controls.

Relational columns keep #3096's rule, moved to the header: withheld while the
sort is a server `$orderby` (the key would be the stored foreign-key id while
the cell shows a name), live in client mode where the key is the label.

Three existing suites asserted through the sort buttons — two on #3096's own
guarantee, one using them as a proxy for column order. They now read the
column's `sortable` flag and drive the table's `onSortChange`, so the
guarantees they encode survive the control that carried them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .changeset/relatedlist-one-sort-semantics.md  |  32 +++
 packages/plugin-detail/src/RelatedList.tsx    | 102 +++++++-
 .../__tests__/RelatedList.headerSort.test.tsx | 233 ++++++++++++++++++
 .../RelatedList.relationalSort.test.tsx       |  32 ++-
 .../RelatedList.serverpagination.test.tsx     |   7 +-
 .../RelatedList.systemcolumns.test.tsx        |  25 +-
 6 files changed, 410 insertions(+), 21 deletions(-)
 create mode 100644 .changeset/relatedlist-one-sort-semantics.md
 create mode 100644 packages/plugin-detail/src/__tests__/RelatedList.headerSort.test.tsx

diff --git a/.changeset/relatedlist-one-sort-semantics.md b/.changeset/relatedlist-one-sort-semantics.md
new file mode 100644
index 000000000..c6b606ff2
--- /dev/null
+++ b/.changeset/relatedlist-one-sort-semantics.md
@@ -0,0 +1,32 @@
+---
+"@object-ui/plugin-detail": minor
+---
+
+fix(detail): a related list has one sorting semantics instead of two — #3106
+
+A related list carried two. Its own sort-button row (opt-in via `sortable`) went
+out as a server `$orderby` over the whole child collection; the `data-table` it
+embeds took `sortable`'s default of `true` and sorted the rows it was holding —
+which, in windowed mode, is **one page**.
+
+Turning `sortable` on put both in the same card, with nothing saying they meant
+different things. Leaving it off — the default — was worse: the page-local sort
+was then the *only* one the user could reach, and it looked exactly like the
+list being sorted.
+
+The table's column headers now drive this list's sort in both modes, so there is
+one order behind them:
+
+- **Windowed**: the header sort becomes the server `$orderby` and resets to page
+  one, the same path the buttons took.
+- **Client mode**: this list keeps sorting in memory, where its key is the label
+  resolved through its own id → name map (#3096) — a key the embedded table
+  cannot see, so its sort was the worse of the two even when both were possible.
+
+The button row survives only where there are no headers to click: a `list`
+(`data-list`) related list, or a caller-supplied `schema` whose contents we
+cannot assume. `sortable`'s documentation now says that is what it controls.
+
+Relational columns keep #3096's rule, moved to the header: no sort affordance
+while the sort is a server `$orderby` (the key would be the stored foreign-key
+id while the cell shows a name), live in client mode where the key is the label.
diff --git a/packages/plugin-detail/src/RelatedList.tsx b/packages/plugin-detail/src/RelatedList.tsx
index 380f838e1..52c947fd5 100644
--- a/packages/plugin-detail/src/RelatedList.tsx
+++ b/packages/plugin-detail/src/RelatedList.tsx
@@ -111,7 +111,17 @@ export interface RelatedListProps {
    * `$orderby`, keeping page windows deterministic.
    */
   defaultSort?: string | Array<{ field: string; order: 'asc' | 'desc' }>;
-  /** Enable column sorting */
+  /**
+   * Render the standalone row of sort buttons above the list.
+   *
+   * Only meaningful for a `list` (`data-list`) related list, which has no
+   * column headers to click. A `grid`/`table` one sorts through its table
+   * headers, which are live regardless of this flag — they always were, and
+   * since objectui#3106 they sort the collection rather than the page, so the
+   * button row above them would be a second control over the same order.
+   *
+   * @default false
+   */
   sortable?: boolean;
   /** Enable text filtering */
   filterable?: boolean;
@@ -591,6 +601,38 @@ export const RelatedList: React.FC<RelatedListProps> = ({
     }
   }, [sortField]);
 
+  /**
+   * The order the embedded table's headers display — this list's own sort, so
+   * the arrow on a column header and the rows underneath it come from the same
+   * place (objectui#3106).
+   *
+   * Before any click that is the declared `defaultSort`, which is what the
+   * windowed fetch above sends. A header showing nothing while the server was
+   * asked for `created_at desc` would make the first click on that column
+   * request `asc` on a list that is already `desc`.
+   */
+  const activeSort = React.useMemo(
+    () => (sortField ? [{ field: sortField, order: sortDirection }] : defaultSortSpec),
+    [sortField, sortDirection, defaultSortSpec],
+  );
+
+  /**
+   * A header click from the embedded table. It arrives with the direction
+   * already resolved against {@link activeSort}, so this assigns rather than
+   * toggling — running it back through `handleSort`'s own toggle would undo it
+   * whenever the two disagreed about the current state.
+   */
+  const handleTableSort = React.useCallback(
+    (next: Array<{ field: string; order: 'asc' | 'desc' }>) => {
+      const first = next[0];
+      if (!first) return;
+      setCurrentPage(0);
+      setSortField(first.field);
+      setSortDirection(first.order);
+    },
+    [],
+  );
+
   // Confirm-delete dialog state. Replaces window.confirm() so the related
   // list matches the rest of the app's Shadcn AlertDialog UX.
   const [deleteTarget, setDeleteTarget] = React.useState<any | null>(null);
@@ -836,6 +878,36 @@ export const RelatedList: React.FC<RelatedListProps> = ({
     return pruned.slice(0, Math.max(1, maxColumns));
   }, [columns, objectSchema, objectName, api, resolveFieldLabel, referenceField, relatedData, maxColumns, lookupLabels, perms]);
 
+  /**
+   * The same columns, with the sort affordance withheld from relational ones
+   * while the sort is the server's.
+   *
+   * A windowed sort goes out as `$orderby` on the flat field name, and a
+   * relational column stores a foreign-key id — so "sort by Owner" would order
+   * the collection by `rec_7f3…` while the cells show names (objectui#3096;
+   * objectstack#4256 settled that no relation join is coming). This is the rule
+   * the sort-button row already applied; the headers inherit it rather than
+   * re-opening the same door.
+   *
+   * In client mode the sort keys off the resolved label, so those headers stay
+   * live — the same split `sortedData` makes.
+   */
+  const sortableColumns = React.useMemo(() => {
+    if (!windowed) return effectiveColumns;
+    return effectiveColumns.map((col: any) => {
+      const field = col.accessorKey || col.field || col.name;
+      return field && isExpandableFieldType((objectSchema?.fields as any)?.[field])
+        ? { ...col, sortable: false }
+        : col;
+    });
+  }, [effectiveColumns, windowed, objectSchema]);
+
+  // A `grid`/`table` list renders a real table, whose column headers carry the
+  // sort. `list` renders `data-list`, which has none — so it keeps the button
+  // row as its only sort control. A caller-supplied `schema` renders whatever
+  // it says, so we cannot claim headers for it either.
+  const hasSortableHeaders = !schema && (type === 'grid' || type === 'table');
+
   const hasCustomRowActions = Array.isArray(rowActions) && rowActions.length > 0;
   const hasRowActions = !!onRowEdit || !!onRowDelete || hasCustomRowActions;
   const isMobile = useIsMobile();
@@ -883,11 +955,24 @@ export const RelatedList: React.FC<RelatedListProps> = ({
         return {
           type: 'data-table',
           data: paginatedData,
-          columns: effectiveColumns,
+          columns: sortableColumns,
           pagination: false, // We handle pagination ourselves
           pageSize: effectivePageSize || 10,
           searchable: false,
           exportable: false,
+          // Sorting is THIS list's, in both modes (objectui#3106).
+          //
+          // Windowed: `data` is one page, so a table-local sort would order
+          // that page and call it the list — the defect. Client mode: this
+          // list's own sort resolves a relational column through the label map
+          // it built (`lookupLabels`), which the table cannot see, so its sort
+          // is the better one even when both are possible.
+          //
+          // Either way there is now ONE sort behind the headers instead of a
+          // table-local order sitting on top of a server order.
+          manualSorting: true,
+          sort: activeSort,
+          onSortChange: handleTableSort,
           rowActions: hasRowActions,
           onRowEdit,
           onRowDelete: onRowDelete ? handleDeleteRow : undefined,
@@ -907,7 +992,7 @@ export const RelatedList: React.FC<RelatedListProps> = ({
       default:
         return { type: 'div', children: 'No view configured' };
     }
-  }, [type, paginatedData, effectiveColumns, schema, effectivePageSize, hasRowActions, hasCustomRowActions, rowActions, onRowAction, onRowEdit, onRowDelete, handleDeleteRow, onRowClick, isMobile, api, objectSchema]);
+  }, [type, paginatedData, sortableColumns, effectiveColumns, schema, effectivePageSize, hasRowActions, hasCustomRowActions, rowActions, onRowAction, onRowEdit, onRowDelete, handleDeleteRow, onRowClick, isMobile, api, objectSchema, activeSort, handleTableSort]);
 
   const headerClassName = collapsible ? 'cursor-pointer select-none' : undefined;
   const handleHeaderClick = collapsible ? () => setCollapsed((c) => !c) : undefined;
@@ -1008,8 +1093,15 @@ export const RelatedList: React.FC<RelatedListProps> = ({
           </div>
         )}
 
-        {/* Sortable column headers */}
-        {sortable && effectiveColumns && effectiveColumns.length > 0 && relatedData.length > 0 && (
+        {/* Sort buttons — only where there are no column headers to click.
+            A `grid`/`table` related list renders a real table whose headers now
+            drive this same sort (objectui#3106), so a second row of buttons
+            above it would be two controls over one order — and, before the
+            headers were wired up, two DIFFERENT orders: the buttons sorted the
+            collection through the server while the headers sorted the page in
+            the browser, in one card, with nothing saying so. `data-list` has no
+            headers, so there the buttons stay the only way to sort. */}
+        {sortable && !hasSortableHeaders && effectiveColumns && effectiveColumns.length > 0 && relatedData.length > 0 && (
           <div className="flex flex-wrap gap-1 mb-3">
             {effectiveColumns.map((col: any) => {
               const field = col.accessorKey || col.field || col.name;
diff --git a/packages/plugin-detail/src/__tests__/RelatedList.headerSort.test.tsx b/packages/plugin-detail/src/__tests__/RelatedList.headerSort.test.tsx
new file mode 100644
index 000000000..940b2a465
--- /dev/null
+++ b/packages/plugin-detail/src/__tests__/RelatedList.headerSort.test.tsx
@@ -0,0 +1,233 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * One sorting semantics per related list (objectui#3106).
+ *
+ * A related list used to carry two. Its own sort-button row (opt-in via
+ * `sortable`) went out as a server `$orderby` over the whole child collection;
+ * the table it embeds took `sortable`'s default of `true` and sorted the rows
+ * it held — which, in windowed mode, is one page. Turning `sortable` on put
+ * both in the same card, with nothing saying they meant different things; and
+ * leaving it off — the default — made the page-local one the *only* sort the
+ * user could reach.
+ *
+ * Now the table's headers drive this list's sort in both modes, and the button
+ * row survives only where there are no headers to click (`data-list`).
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, waitFor, screen } from '@testing-library/react';
+import * as React from 'react';
+import { RelatedList } from '../RelatedList';
+
+// Capture the schema RelatedList hands to SchemaRenderer (the data-table).
+const h = vi.hoisted(() => ({ schema: null as any }));
+vi.mock('@object-ui/react', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return {
+    ...actual,
+    SchemaRenderer: (props: any) => {
+      h.schema = props.schema;
+      return null;
+    },
+  };
+});
+
+const rows = (start: number, count: number) =>
+  Array.from({ length: count }, (_, i) => ({
+    id: `c${start + i}`,
+    name: `Row ${start + i}`,
+    owner: `usr_${start + i}`,
+  }));
+
+const columns = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'owner', header: 'Owner' },
+];
+
+const makeWindowedDS = (totalRecords = 12) => ({
+  find: vi.fn(async (_api: string, params: any) => {
+    const skip = params?.$skip ?? 0;
+    const top = params?.$top ?? totalRecords;
+    return {
+      data: rows(skip, Math.max(0, Math.min(top, totalRecords - skip))),
+      total: totalRecords,
+    };
+  }),
+  getObjectSchema: vi.fn(async () => ({
+    name: 'contact',
+    fields: {
+      name: { type: 'text' },
+      owner: { type: 'lookup', reference_to: 'user' },
+      account: { type: 'lookup', reference_to: 'account' },
+    },
+  })),
+});
+
+/**
+ * The most recent fetch OF THE CHILD COLLECTION.
+ *
+ * Not simply the last `find` call: a `lookup` column makes this list resolve
+ * the related records' labels through the same dataSource, so the last call is
+ * usually a label lookup against `user` with no `$orderby` at all.
+ */
+const lastFindParams = (ds: any) => {
+  const calls = ds.find.mock.calls.filter((c: any[]) => c[0] === 'contact');
+  return calls[calls.length - 1]?.[1];
+};
+
+function renderWindowed(ds: any, props?: Record<string, unknown>) {
+  return render(
+    <RelatedList
+      title="Contacts"
+      type="table"
+      api="contact"
+      objectName="contact"
+      referenceField="account"
+      parentId="ACC-1"
+      columns={columns}
+      pageSize={5}
+      dataSource={ds as any}
+      {...props}
+    />,
+  );
+}
+
+beforeEach(() => {
+  h.schema = null;
+});
+
+describe('RelatedList — the embedded table sorts the collection, not the window', () => {
+  it('hands the table controlled sorting instead of letting it sort locally', async () => {
+    const ds = makeWindowedDS();
+    renderWindowed(ds);
+    await waitFor(() => expect(h.schema?.type).toBe('data-table'));
+
+    expect(h.schema.manualSorting).toBe(true);
+    expect(Array.isArray(h.schema.sort)).toBe(true);
+    expect(typeof h.schema.onSortChange).toBe('function');
+  });
+
+  it('turns a header sort into a server $orderby over the whole collection', async () => {
+    const ds = makeWindowedDS();
+    renderWindowed(ds);
+    await waitFor(() => expect(typeof h.schema?.onSortChange).toBe('function'));
+
+    await React.act(async () => {
+      h.schema.onSortChange([{ field: 'name', order: 'desc' }]);
+    });
+
+    await waitFor(() => {
+      expect(lastFindParams(ds).$orderby).toEqual([{ field: 'name', order: 'desc' }]);
+    });
+  });
+
+  it('assigns the direction the header resolved rather than re-toggling it', async () => {
+    // The table sends the direction it computed against `sort`. Running that
+    // back through the button row's own toggle would invert it.
+    const ds = makeWindowedDS();
+    renderWindowed(ds);
+    await waitFor(() => expect(typeof h.schema?.onSortChange).toBe('function'));
+
+    await React.act(async () => {
+      h.schema.onSortChange([{ field: 'name', order: 'desc' }]);
+    });
+    await waitFor(() => expect(lastFindParams(ds).$orderby).toEqual([{ field: 'name', order: 'desc' }]));
+
+    await React.act(async () => {
+      h.schema.onSortChange([{ field: 'name', order: 'desc' }]);
+    });
+    await waitFor(() => expect(lastFindParams(ds).$orderby).toEqual([{ field: 'name', order: 'desc' }]));
+  });
+
+  it('returns to the first page when the order changes', async () => {
+    const ds = makeWindowedDS();
+    renderWindowed(ds);
+    await waitFor(() => expect(typeof h.schema?.onSortChange).toBe('function'));
+
+    await React.act(async () => {
+      h.schema.onSortChange([{ field: 'name', order: 'asc' }]);
+    });
+
+    await waitFor(() => {
+      const p = lastFindParams(ds);
+      expect(p.$orderby).toEqual([{ field: 'name', order: 'asc' }]);
+      expect(p.$skip ?? 0).toBe(0);
+    });
+  });
+
+  it('shows the declared defaultSort before anyone clicks — the same one it fetched with', async () => {
+    const ds = makeWindowedDS();
+    renderWindowed(ds, { defaultSort: '-name' });
+    await waitFor(() => expect(h.schema?.type).toBe('data-table'));
+
+    expect(h.schema.sort).toEqual([{ field: 'name', order: 'desc' }]);
+    expect(lastFindParams(ds).$orderby).toEqual([{ field: 'name', order: 'desc' }]);
+  });
+
+  it('withholds the header from a relational column while windowed (#3096)', async () => {
+    // `$orderby` on `owner` orders by the stored id while the cell shows a
+    // name. This is the rule the sort-button row already applied.
+    const ds = makeWindowedDS();
+    renderWindowed(ds);
+    await waitFor(() => expect(h.schema?.columns?.length).toBeGreaterThan(0));
+
+    const owner = h.schema.columns.find((c: any) => c.accessorKey === 'owner');
+    const name = h.schema.columns.find((c: any) => c.accessorKey === 'name');
+    expect(owner.sortable).toBe(false);
+    expect(name.sortable).not.toBe(false);
+  });
+
+  it('keeps a relational header live in client mode, where the key is the label', async () => {
+    // Not windowed (caller supplied `data`), so this list sorts in memory
+    // through its resolved label map — an honest key, unlike the stored id.
+    render(
+      <RelatedList
+        title="Contacts"
+        type="table"
+        objectName="contact"
+        columns={columns}
+        data={rows(0, 3)}
+        dataSource={makeWindowedDS() as any}
+      />,
+    );
+    await waitFor(() => expect(h.schema?.columns?.length).toBeGreaterThan(0));
+
+    const owner = h.schema.columns.find((c: any) => c.accessorKey === 'owner');
+    expect(owner.sortable).not.toBe(false);
+    // Still controlled: this list owns the order in both modes, so there is
+    // never a table-local sort sitting on top of it.
+    expect(h.schema.manualSorting).toBe(true);
+  });
+});
+
+describe('RelatedList — one sort control per card', () => {
+  it('renders no sort-button row for a table list, even with sortable on', async () => {
+    // The headers carry the sort. A button row above them would be a second
+    // control over one order — and, before #3106, a second ORDER.
+    const ds = makeWindowedDS();
+    renderWindowed(ds, { sortable: true });
+    await waitFor(() => expect(h.schema?.type).toBe('data-table'));
+
+    expect(screen.queryByRole('button', { name: /^Name/ })).toBeNull();
+    expect(screen.queryByRole('button', { name: /^Owner/ })).toBeNull();
+  });
+
+  it('keeps the button row for a `list` related list, which has no headers', async () => {
+    render(
+      <RelatedList
+        title="Contacts"
+        type="list"
+        objectName="contact"
+        columns={columns}
+        data={rows(0, 3)}
+        sortable
+        dataSource={makeWindowedDS() as any}
+      />,
+    );
+    await waitFor(() => expect(h.schema?.type).toBe('data-list'));
+
+    expect(screen.getByRole('button', { name: /Name/ })).toBeTruthy();
+  });
+});
diff --git a/packages/plugin-detail/src/__tests__/RelatedList.relationalSort.test.tsx b/packages/plugin-detail/src/__tests__/RelatedList.relationalSort.test.tsx
index 91182214d..a21432c46 100644
--- a/packages/plugin-detail/src/__tests__/RelatedList.relationalSort.test.tsx
+++ b/packages/plugin-detail/src/__tests__/RelatedList.relationalSort.test.tsx
@@ -13,10 +13,17 @@
  *
  *   - windowed (server `$orderby` over the whole child collection): the key is
  *     the stored foreign-key id, and no join is available to reach the related
- *     record's name (objectstack#4256). The button is withheld.
+ *     record's name (objectstack#4256). The affordance is withheld.
  *   - client mode (sorting the rows already in memory): the key can be — and
  *     now is — the label the cell shows, resolved from this list's own
- *     id → name map. The button stays, and it sorts by the name.
+ *     id → name map. The affordance stays, and it sorts by the name.
+ *
+ * The guarantee is unchanged since #3106 moved the affordance; what carries it
+ * is now the embedded table's column headers rather than a separate row of sort
+ * buttons, so these assertions read the column's `sortable` flag and drive the
+ * table's `onSortChange` instead of clicking buttons that no longer exist for a
+ * `table` list. (The button row survives for `data-list`, which has no headers
+ * — covered in `RelatedList.headerSort.test.tsx`.)
  */
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { render, waitFor, fireEvent, screen } from '@testing-library/react';
@@ -72,14 +79,18 @@ const makeDataSource = () => ({
   }),
 });
 
-const sortButton = (name: RegExp) => screen.queryByRole('button', { name });
+/** Whether the embedded table offers a sort on this column. */
+const columnSortable = (accessorKey: string) => {
+  const col = h.schema?.columns?.find((c: any) => c.accessorKey === accessorKey);
+  return col ? col.sortable !== false : undefined;
+};
 
 beforeEach(() => {
   h.schema = null;
 });
 
 describe('RelatedList sort entry points — relational columns (objectui#3096)', () => {
-  it('withholds the relational sort button when the sort is a server $orderby', async () => {
+  it('withholds the relational column header when the sort is a server $orderby', async () => {
     const dataSource = makeDataSource();
     render(
       <RelatedList
@@ -95,9 +106,9 @@ describe('RelatedList sort entry points — relational columns (objectui#3096)',
         dataSource={dataSource as any}
       />,
     );
-    // A plain column still offers its button — proving the row rendered at all.
-    await waitFor(() => expect(sortButton(/^name/i)).not.toBeNull());
-    expect(sortButton(/^owner/i)).toBeNull();
+    // A plain column stays sortable — proving the table rendered at all.
+    await waitFor(() => expect(columnSortable('name')).toBe(true));
+    expect(columnSortable('owner')).toBe(false);
   });
 
   it('keeps it in client mode and orders by the resolved label, not the id', async () => {
@@ -119,9 +130,10 @@ describe('RelatedList sort entry points — relational columns (objectui#3096)',
     // Wait for the id → name map to resolve; until then the cells show ids.
     await waitFor(() => expect(dataSource.find).toHaveBeenCalledWith('sys_user', expect.anything()));
 
-    const owner = sortButton(/^owner/i);
-    expect(owner).not.toBeNull();
-    fireEvent.click(owner!);
+    expect(columnSortable('owner')).toBe(true);
+    await React.act(async () => {
+      h.schema.onSortChange([{ field: 'owner', order: 'asc' }]);
+    });
 
     await waitFor(() =>
       expect(h.schema.data.map((row: any) => owners[row.owner])).toEqual([
diff --git a/packages/plugin-detail/src/__tests__/RelatedList.serverpagination.test.tsx b/packages/plugin-detail/src/__tests__/RelatedList.serverpagination.test.tsx
index d5b3516fc..a3b7762a6 100644
--- a/packages/plugin-detail/src/__tests__/RelatedList.serverpagination.test.tsx
+++ b/packages/plugin-detail/src/__tests__/RelatedList.serverpagination.test.tsx
@@ -196,7 +196,12 @@ describe('RelatedList — server-windowed pagination (#2711)', () => {
     fireEvent.click(nextButton());
     await screen.findByText('Page 2 of 3');
 
-    fireEvent.click(screen.getByRole('button', { name: /name/i }));
+    // The sort now arrives from the embedded table's column headers rather
+    // than a separate row of sort buttons (objectui#3106) — same server
+    // `$orderby`, same page reset, one control instead of two.
+    await React.act(async () => {
+      h.schema.onSortChange([{ field: 'name', order: 'asc' }]);
+    });
     await waitFor(() => {
       expect(ds.find).toHaveBeenCalledWith('contact', {
         $filter: { account: 'ACC-1' },
diff --git a/packages/plugin-detail/src/__tests__/RelatedList.systemcolumns.test.tsx b/packages/plugin-detail/src/__tests__/RelatedList.systemcolumns.test.tsx
index d59092c2a..7d783bf3b 100644
--- a/packages/plugin-detail/src/__tests__/RelatedList.systemcolumns.test.tsx
+++ b/packages/plugin-detail/src/__tests__/RelatedList.systemcolumns.test.tsx
@@ -9,10 +9,26 @@
  * column cap. System audit fields are now sorted last.
  */
 import { describe, it, expect, vi } from 'vitest';
-import { render, screen, waitFor } from '@testing-library/react';
+import { render, waitFor } from '@testing-library/react';
 import React from 'react';
 import { RelatedList } from '../RelatedList';
 
+// Read the column order straight off the schema handed to the renderer. This
+// used to infer it from the row of sort buttons, which a `table` list no longer
+// renders now that its column headers carry the sort (objectui#3106) — and
+// which was always a proxy for the thing under test anyway.
+const h = vi.hoisted(() => ({ schema: null as any }));
+vi.mock('@object-ui/react', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return {
+    ...actual,
+    SchemaRenderer: (props: any) => {
+      h.schema = props.schema;
+      return null;
+    },
+  };
+});
+
 // Declare the system audit fields FIRST to reproduce the pre-fix ordering.
 const fields = {
   created_at: { type: 'datetime', label: 'Created At' },
@@ -49,13 +65,12 @@ describe('RelatedList — system audit columns are deprioritized', () => {
       />,
     );
 
-    // `sortable` renders one button per effective column, in column order.
     const labels = await waitFor(() => {
-      const texts = screen.getAllByRole('button').map((b) => (b.textContent || '').trim());
-      if (!texts.some((t) => t.includes('Product'))) throw new Error('headers not ready');
+      const texts = (h.schema?.columns ?? []).map((c: any) => String(c.header ?? '').trim());
+      if (!texts.some((t: string) => t.includes('Product'))) throw new Error('columns not ready');
       return texts;
     });
-    const idx = (s: string) => labels.findIndex((t) => t.includes(s));
+    const idx = (s: string) => labels.findIndex((t: string) => t.includes(s));
 
     expect(idx('Product')).toBeGreaterThanOrEqual(0);
     // A business field must lead; any shown system audit column comes after it.