@opensaas/stack-ui 0.23.0 → 0.25.0

package/.turbo/turbo-build.log

@@ -1,11 +1,11 @@
 
-> @opensaas/stack-ui@0.23.0 build /home/runner/work/stack/stack/packages/ui
+> @opensaas/stack-ui@0.25.0 build /home/runner/work/stack/stack/packages/ui
 > tsc && npm run build:css
 
 npm warn Unknown env config "verify-deps-before-run". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.
 npm warn Unknown env config "npm-globalconfig". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.
 npm warn Unknown env config "_jsr-registry". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.
 
-> @opensaas/stack-ui@0.23.0 build:css
+> @opensaas/stack-ui@0.25.0 build:css
 > mkdir -p dist/styles && postcss ./src/styles/globals.css -o ./dist/styles/globals.css
 

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @opensaas/stack-ui
 
+## 0.25.0
+
+### Patch Changes
+
+- [#607](https://github.com/OpenSaasAU/stack/pull/607) [`61547be`](https://github.com/OpenSaasAU/stack/commit/61547beb5ec7d4aff30753849e36a738c49c91e4) Thanks [@borisno2](https://github.com/borisno2)! - Fix `ui.listView.initialSort` applying sort client-side instead of as a DB-level `orderBy`
+
+  Previously, `initialSort` was applied to the already-fetched page in memory, meaning a 500-row list with `initialSort: { field: 'sentAt', direction: 'desc' }` would only show the 50 most recent rows of the _current page_ rather than the 50 most recent rows overall. The sort is now passed as `orderBy` to `findMany` so pagination and sorting compose correctly.
+
+  Column-header clicks also now navigate with a `?sort=field:direction` URL param (instead of mutating local state), so subsequent sorts are also DB-level and work correctly across pages.
+
+## 0.24.0
+
+### Minor Changes
+
+- [#552](https://github.com/OpenSaasAU/stack/pull/552) [`66496b4`](https://github.com/OpenSaasAU/stack/commit/66496b487bae61f3cdea26fcfcaf605caaaa5520) Thanks [@borisno2](https://github.com/borisno2)! - Add list-level `ui.listView` config (mirroring Keystone) for default columns and sort
+
+  Lists now support a `ui.listView` block in `opensaas.config.ts` that sets the
+  admin list table's default column selection/order and default sort. Naming
+  mirrors Keystone's `ui.listView` so migrators can map defaults directly.
+
+  ```typescript
+  lists: {
+    Post: list({
+      fields: {
+        title: text(),
+        status: text(),
+        createdAt: timestamp(),
+      },
+      ui: {
+        listView: {
+          // Column selection AND order
+          initialColumns: ['title', 'status'],
+          // Default sort
+          initialSort: { field: 'createdAt', direction: 'desc' },
+        },
+      },
+    }),
+  }
+  ```
+
+  When `ui.listView` is absent, behaviour is unchanged: the table shows all
+  non-system fields and applies no default sort.
+
 ## 0.23.0
 
 ### Minor Changes

package/dist/components/AdminUI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AdminUI.d.ts","sourceRoot":"","sources":["../../src/components/AdminUI.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,EACL,KAAK,aAAa,EAGlB,cAAc,EACf,MAAM,sBAAsB,CAAA;AAG7B,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAC/B,MAAM,EAAE,cAAc,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,YAAY,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAA;KAAE,CAAA;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,YAAY,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC5D,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,MAAM,EACN,MAAW,EACX,YAAiB,EACjB,QAAmB,EACnB,YAAY,EACZ,SAAS,GACV,EAAE,YAAY,2CA+Fd"}
+{"version":3,"file":"AdminUI.d.ts","sourceRoot":"","sources":["../../src/components/AdminUI.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,EACL,KAAK,aAAa,EAGlB,cAAc,EACf,MAAM,sBAAsB,CAAA;AAG7B,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAC/B,MAAM,EAAE,cAAc,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,YAAY,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAA;KAAE,CAAA;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,YAAY,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC5D,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,MAAM,EACN,MAAW,EACX,YAAiB,EACjB,QAAmB,EACnB,YAAY,EACZ,SAAS,GACV,EAAE,YAAY,2CAsHd"}

package/dist/components/AdminUI.js

@@ -55,7 +55,25 @@ export function AdminUI({ context, config, params = [], searchParams = {}, baseP
         // List view
         const search = typeof searchParams.search === 'string' ? searchParams.search : undefined;
         const page = typeof searchParams.page === 'string' ? parseInt(searchParams.page, 10) : 1;
-        content = (_jsx(ListView, { context: context, config: config, listKey: listKey, basePath: basePath, search: search, page: page }));
+        // Read list-view defaults (column selection/order + default sort) from the
+        // list-level `ui.listView` config (mirrors Keystone). When absent, the
+        // ListView falls back to its existing defaults (all non-system fields,
+        // no default sort).
+        const listView = config.lists[listKey]?.ui?.listView;
+        // Parse `?sort=field:direction` URL param for user-triggered column sorts.
+        const sortParam = typeof searchParams.sort === 'string' ? searchParams.sort : undefined;
+        let urlSort;
+        if (sortParam) {
+            const colonIdx = sortParam.lastIndexOf(':');
+            if (colonIdx > 0) {
+                const field = sortParam.slice(0, colonIdx);
+                const dir = sortParam.slice(colonIdx + 1);
+                if (dir === 'asc' || dir === 'desc') {
+                    urlSort = { field, direction: dir };
+                }
+            }
+        }
+        content = (_jsx(ListView, { context: context, config: config, listKey: listKey, basePath: basePath, search: search, page: page, columns: listView?.initialColumns, initialSort: listView?.initialSort, sort: urlSort }));
     }
     // Generate theme styles if custom theme is configured
     const themeStyles = config.ui?.theme ? generateThemeCSS(config.ui.theme) : null;

package/dist/components/ListView.d.ts

@@ -1,4 +1,12 @@
 import { type AccessContext, OpenSaasConfig } from '@opensaas/stack-core';
+/**
+ * Default sort for the list table, mirroring Keystone's `ui.listView.initialSort`.
+ * Plain serializable data so it can cross the server/client boundary.
+ */
+export interface ListViewSort {
+    field: string;
+    direction: 'asc' | 'desc';
+}
 export interface ListViewProps {
     context: AccessContext<unknown>;
     config: OpenSaasConfig;
@@ -8,10 +16,20 @@ export interface ListViewProps {
     page?: number;
     pageSize?: number;
     search?: string;
+    /**
+     * Default sort from the list's `ui.listView.initialSort` config.
+     * Used when no URL sort param is present.
+     */
+    initialSort?: ListViewSort;
+    /**
+     * Active sort from the `?sort=field:direction` URL param.
+     * Takes precedence over `initialSort`.
+     */
+    sort?: ListViewSort;
 }
 /**
  * List view component - displays items in a table
  * Server Component that fetches data and renders client table
  */
-export declare function ListView({ context, config, listKey, basePath, columns, page, pageSize, search, }: ListViewProps): Promise<import("react/jsx-runtime").JSX.Element>;
+export declare function ListView({ context, config, listKey, basePath, columns, page, pageSize, search, initialSort, sort, }: ListViewProps): Promise<import("react/jsx-runtime").JSX.Element>;
 //# sourceMappingURL=ListView.d.ts.map

package/dist/components/ListView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ListView.d.ts","sourceRoot":"","sources":["../../src/components/ListView.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,aAAa,EAAuB,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE9F,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAC/B,MAAM,EAAE,cAAc,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,EAC7B,OAAO,EACP,MAAM,EACN,OAAO,EACP,QAAmB,EACnB,OAAO,EACP,IAAQ,EACR,QAAa,EACb,MAAM,GACP,EAAE,aAAa,oDA6Hf"}
+{"version":3,"file":"ListView.d.ts","sourceRoot":"","sources":["../../src/components/ListView.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,aAAa,EAAuB,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE9F;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAC/B,MAAM,EAAE,cAAc,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,YAAY,CAAA;CACpB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,EAC7B,OAAO,EACP,MAAM,EACN,OAAO,EACP,QAAmB,EACnB,OAAO,EACP,IAAQ,EACR,QAAa,EACb,MAAM,EACN,WAAW,EACX,IAAI,GACL,EAAE,aAAa,oDAqIf"}

package/dist/components/ListView.js

@@ -7,13 +7,17 @@ import { getDbKey, getUrlKey } from '@opensaas/stack-core';
  * List view component - displays items in a table
  * Server Component that fetches data and renders client table
  */
-export async function ListView({ context, config, listKey, basePath = '/admin', columns, page = 1, pageSize = 50, search, }) {
+export async function ListView({ context, config, listKey, basePath = '/admin', columns, page = 1, pageSize = 50, search, initialSort, sort, }) {
     const key = getDbKey(listKey);
     const urlKey = getUrlKey(listKey);
     const listConfig = config.lists[listKey];
     if (!listConfig) {
         return (_jsx("div", { className: "p-8", children: _jsxs("div", { className: "bg-destructive/10 border border-destructive text-destructive rounded-lg p-6", children: [_jsx("h2", { className: "text-lg font-semibold mb-2", children: "List not found" }), _jsxs("p", { children: ["The list \"", listKey, "\" does not exist in your configuration."] })] }) }));
     }
+    // URL sort takes precedence over config initialSort, but only if the field
+    // actually exists on the list — an unknown field would cause Prisma to throw.
+    const validatedSort = sort && sort.field in listConfig.fields ? sort : undefined;
+    const activeSort = validatedSort ?? initialSort;
     // Fetch items using access-controlled context
     const skip = (page - 1) * pageSize;
     let items = [];
@@ -49,10 +53,11 @@ export async function ListView({ context, config, listKey, basePath = '/admin',
         });
         const delegate = dbContext[key];
         if (delegate?.findMany && delegate?.count) {
-            ;
+            const orderBy = activeSort ? { [activeSort.field]: activeSort.direction } : undefined;
             [items, total] = await Promise.all([
                 delegate.findMany({
                     where,
+                    orderBy,
                     skip,
                     take: pageSize,
                     ...(Object.keys(include).length > 0 ? { include } : {}),
@@ -79,5 +84,5 @@ export async function ListView({ context, config, listKey, basePath = '/admin',
     return (_jsxs("div", { className: "p-8", children: [_jsxs("div", { className: "flex items-center justify-between mb-8", children: [_jsxs("div", { children: [_jsx("h1", { className: "text-3xl font-bold mb-2", children: formatListName(listKey) }), _jsxs("p", { className: "text-muted-foreground", children: [total, " ", total === 1 ? 'item' : 'items'] })] }), _jsxs(Link, { href: `${basePath}/${urlKey}/create`, className: "inline-flex items-center px-4 py-2 bg-primary text-primary-foreground rounded-md font-medium hover:bg-primary/90 transition-colors", children: [_jsx("span", { className: "mr-2", children: "+" }), "Create ", formatListName(listKey)] })] }), _jsx(ListViewClient, { items: serializedItems || [], fieldTypes: Object.fromEntries(Object.entries(listConfig.fields).map(([key, field]) => [
                     key,
                     field.type,
-                ])), relationshipRefs: relationshipRefs, columns: columns, listKey: listKey, urlKey: urlKey, basePath: basePath, page: page, pageSize: pageSize, total: total || 0, search: search })] }));
+                ])), relationshipRefs: relationshipRefs, columns: columns, initialSort: activeSort, listKey: listKey, urlKey: urlKey, basePath: basePath, page: page, pageSize: pageSize, total: total || 0, search: search })] }));
 }

package/dist/components/ListViewClient.d.ts

@@ -3,6 +3,15 @@ export interface ListViewClientProps {
     fieldTypes: Record<string, string>;
     relationshipRefs: Record<string, string>;
     columns?: string[];
+    /**
+     * Default sort for the table (from the list's `ui.listView.initialSort`).
+     * Seeds the initial sort column/direction. When omitted, the table starts
+     * unsorted (current default behaviour).
+     */
+    initialSort?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
     listKey: string;
     urlKey: string;
     basePath: string;
@@ -15,5 +24,5 @@ export interface ListViewClientProps {
  * Client component for interactive list table
  * Handles sorting, pagination, and row interactions
  */
-export declare function ListViewClient({ items, fieldTypes, relationshipRefs, columns, urlKey, basePath, page, pageSize, total, search: initialSearch, }: ListViewClientProps): import("react/jsx-runtime").JSX.Element;
+export declare function ListViewClient({ items, fieldTypes, relationshipRefs, columns, initialSort, urlKey, basePath, page, pageSize, total, search: initialSearch, }: ListViewClientProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ListViewClient.d.ts.map

package/dist/components/ListViewClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ListViewClient.d.ts","sourceRoot":"","sources":["../../src/components/ListViewClient.tsx"],"names":[],"mappings":"AAoBA,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACrC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EACL,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EAAE,aAAa,GACtB,EAAE,mBAAmB,2CAwOrB"}
+{"version":3,"file":"ListViewClient.d.ts","sourceRoot":"","sources":["../../src/components/ListViewClient.tsx"],"names":[],"mappings":"AAmBA,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACrC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAA;IAC1D,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EACL,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,WAAW,EACX,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EAAE,aAAa,GACtB,EAAE,mBAAmB,2CAwOrB"}

package/dist/components/ListViewClient.js

@@ -1,7 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from 'react';
-import { useState } from 'react';
 import Link from 'next/link.js';
 import { useRouter } from 'next/navigation.js';
 import { formatFieldName, getFieldDisplayValue } from '../lib/utils.js';
@@ -14,40 +13,27 @@ import { getUrlKey } from '@opensaas/stack-core';
  * Client component for interactive list table
  * Handles sorting, pagination, and row interactions
  */
-export function ListViewClient({ items, fieldTypes, relationshipRefs, columns, urlKey, basePath, page, pageSize, total, search: initialSearch, }) {
+export function ListViewClient({ items, fieldTypes, relationshipRefs, columns, initialSort, urlKey, basePath, page, pageSize, total, search: initialSearch, }) {
     const router = useRouter();
-    const [sortBy, setSortBy] = useState(null);
-    const [sortOrder, setSortOrder] = useState('asc');
-    const [searchInput, setSearchInput] = useState(initialSearch || '');
+    const sortBy = initialSort?.field ?? null;
+    const sortOrder = initialSort?.direction ?? 'asc';
+    const [searchInput, setSearchInput] = React.useState(initialSearch || '');
     // Determine which columns to show
     const displayColumns = columns ||
         Object.keys(fieldTypes).filter((key) => !['password', 'createdAt', 'updatedAt'].includes(key));
-    // Sort items if needed
-    const sortedItems = [...items];
-    if (sortBy) {
-        sortedItems.sort((a, b) => {
-            const aVal = a[sortBy];
-            const bVal = b[sortBy];
-            if (aVal === bVal)
-                return 0;
-            // Handle unknown types for comparison - convert to string for safety
-            const aStr = String(aVal ?? '');
-            const bStr = String(bVal ?? '');
-            const comparison = aStr > bStr ? 1 : -1;
-            return sortOrder === 'asc' ? comparison : -comparison;
-        });
-    }
+    // Items are already sorted by the server via orderBy; no in-memory sort needed.
     const totalPages = Math.ceil(total / pageSize);
     const hasNextPage = page < totalPages;
     const hasPrevPage = page > 1;
     const handleSort = (column) => {
-        if (sortBy === column) {
-            setSortOrder(sortOrder === 'asc' ? 'desc' : 'asc');
-        }
-        else {
-            setSortBy(column);
-            setSortOrder('asc');
+        const newDirection = sortBy === column ? (sortOrder === 'asc' ? 'desc' : 'asc') : 'asc';
+        const params = new URLSearchParams();
+        if (initialSearch) {
+            params.set('search', initialSearch);
         }
+        params.set('sort', `${column}:${newDirection}`);
+        params.set('page', '1');
+        router.push(`${basePath}/${urlKey}?${params.toString()}`);
     };
     const handleSearch = (e) => {
         e.preventDefault();
@@ -55,18 +41,29 @@ export function ListViewClient({ items, fieldTypes, relationshipRefs, columns, u
         if (searchInput.trim()) {
             params.set('search', searchInput.trim());
         }
+        if (sortBy) {
+            params.set('sort', `${sortBy}:${sortOrder}`);
+        }
         params.set('page', '1'); // Reset to page 1 on new search
         router.push(`${basePath}/${urlKey}?${params.toString()}`);
     };
     const handleClearSearch = () => {
         setSearchInput('');
-        router.push(`${basePath}/${urlKey}`);
+        const params = new URLSearchParams();
+        if (sortBy) {
+            params.set('sort', `${sortBy}:${sortOrder}`);
+        }
+        const qs = params.toString();
+        router.push(`${basePath}/${urlKey}${qs ? `?${qs}` : ''}`);
     };
     const buildPaginationUrl = (newPage) => {
         const params = new URLSearchParams();
         if (initialSearch) {
             params.set('search', initialSearch);
         }
+        if (sortBy) {
+            params.set('sort', `${sortBy}:${sortOrder}`);
+        }
         params.set('page', newPage.toString());
         return `${basePath}/${urlKey}?${params.toString()}`;
     };
@@ -102,7 +99,7 @@ export function ListViewClient({ items, fieldTypes, relationshipRefs, columns, u
         const displayValue = getFieldDisplayValue(value, 'relationship');
         return (_jsx(Link, { href: `${basePath}/${relatedUrlKey}/${itemId}`, className: "text-primary hover:underline", onClick: (e) => e.stopPropagation(), children: displayValue }));
     };
-    return (_jsxs("div", { className: "space-y-4", children: [_jsx(Card, { className: "p-4", children: _jsxs("form", { onSubmit: handleSearch, className: "flex gap-2", children: [_jsxs("div", { className: "flex-1 relative", children: [_jsx(Input, { type: "text", value: searchInput, onChange: (e) => setSearchInput(e.target.value), placeholder: "Search...", className: "pr-10" }), searchInput && (_jsx("button", { type: "button", onClick: handleClearSearch, className: "absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground", children: "\u2715" }))] }), _jsx(Button, { type: "submit", children: "Search" })] }) }), _jsx("div", { className: "rounded-lg border", children: _jsxs(Table, { children: [_jsx(TableHeader, { children: _jsxs(TableRow, { children: [displayColumns.map((column) => (_jsx(TableHead, { className: "cursor-pointer hover:bg-muted/70 transition-colors", onClick: () => handleSort(column), children: _jsxs("div", { className: "flex items-center space-x-1", children: [_jsx("span", { children: formatFieldName(column) }), sortBy === column && (_jsx("span", { className: "text-primary", children: sortOrder === 'asc' ? '↑' : '↓' }))] }) }, column))), _jsx(TableHead, { className: "text-right", children: "Actions" })] }) }), _jsx(TableBody, { children: sortedItems.length === 0 ? (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: displayColumns.length + 1, className: "h-24 text-center", children: "No items found" }) })) : (sortedItems.map((item) => (_jsxs(TableRow, { children: [displayColumns.map((column) => (_jsx(TableCell, { children: fieldTypes[column] === 'relationship'
+    return (_jsxs("div", { className: "space-y-4", children: [_jsx(Card, { className: "p-4", children: _jsxs("form", { onSubmit: handleSearch, className: "flex gap-2", children: [_jsxs("div", { className: "flex-1 relative", children: [_jsx(Input, { type: "text", value: searchInput, onChange: (e) => setSearchInput(e.target.value), placeholder: "Search...", className: "pr-10" }), searchInput && (_jsx("button", { type: "button", onClick: handleClearSearch, className: "absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground", children: "\u2715" }))] }), _jsx(Button, { type: "submit", children: "Search" })] }) }), _jsx("div", { className: "rounded-lg border", children: _jsxs(Table, { children: [_jsx(TableHeader, { children: _jsxs(TableRow, { children: [displayColumns.map((column) => (_jsx(TableHead, { className: "cursor-pointer hover:bg-muted/70 transition-colors", onClick: () => handleSort(column), children: _jsxs("div", { className: "flex items-center space-x-1", children: [_jsx("span", { children: formatFieldName(column) }), sortBy === column && (_jsx("span", { className: "text-primary", children: sortOrder === 'asc' ? '↑' : '↓' }))] }) }, column))), _jsx(TableHead, { className: "text-right", children: "Actions" })] }) }), _jsx(TableBody, { children: items.length === 0 ? (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: displayColumns.length + 1, className: "h-24 text-center", children: "No items found" }) })) : (items.map((item) => (_jsxs(TableRow, { children: [displayColumns.map((column) => (_jsx(TableCell, { children: fieldTypes[column] === 'relationship'
                                             ? renderRelationshipCell(item[column], column)
                                             : getFieldDisplayValue(item[column], fieldTypes[column]) }, column))), _jsx(TableCell, { className: "text-right", children: _jsx(Link, { href: `${basePath}/${urlKey}/${item.id}`, className: "text-primary hover:underline", children: "Edit" }) })] }, String(item.id))))) })] }) }), totalPages > 1 && (_jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "text-sm text-muted-foreground", children: ["Showing ", (page - 1) * pageSize + 1, " to ", Math.min(page * pageSize, total), " of ", total, ' ', "results"] }), _jsxs("div", { className: "flex items-center space-x-2", children: [_jsx(Button, { variant: "outline", onClick: () => router.push(buildPaginationUrl(page - 1)), disabled: !hasPrevPage, children: "Previous" }), _jsxs("span", { className: "text-sm text-muted-foreground", children: ["Page ", page, " of ", totalPages] }), _jsx(Button, { variant: "outline", onClick: () => router.push(buildPaginationUrl(page + 1)), disabled: !hasNextPage, children: "Next" })] })] }))] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-ui",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Composable React UI components for OpenSaas Stack",
   "type": "module",
   "main": "./dist/index.js",
@@ -58,7 +58,7 @@
   },
   "dependencies": {
     "@radix-ui/react-checkbox": "^1.3.3",
-    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dialog": "^1.1.17",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
     "@radix-ui/react-popover": "^1.1.15",
@@ -94,7 +94,7 @@
     "tailwindcss": "^4.2.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0",
-    "@opensaas/stack-core": "0.23.0"
+    "@opensaas/stack-core": "0.25.0"
   },
   "scripts": {
     "build": "tsc && npm run build:css",

package/src/components/AdminUI.tsx

@@ -108,6 +108,26 @@ export function AdminUI({
     const search = typeof searchParams.search === 'string' ? searchParams.search : undefined
     const page = typeof searchParams.page === 'string' ? parseInt(searchParams.page, 10) : 1
 
+    // Read list-view defaults (column selection/order + default sort) from the
+    // list-level `ui.listView` config (mirrors Keystone). When absent, the
+    // ListView falls back to its existing defaults (all non-system fields,
+    // no default sort).
+    const listView = config.lists[listKey]?.ui?.listView
+
+    // Parse `?sort=field:direction` URL param for user-triggered column sorts.
+    const sortParam = typeof searchParams.sort === 'string' ? searchParams.sort : undefined
+    let urlSort: { field: string; direction: 'asc' | 'desc' } | undefined
+    if (sortParam) {
+      const colonIdx = sortParam.lastIndexOf(':')
+      if (colonIdx > 0) {
+        const field = sortParam.slice(0, colonIdx)
+        const dir = sortParam.slice(colonIdx + 1)
+        if (dir === 'asc' || dir === 'desc') {
+          urlSort = { field, direction: dir }
+        }
+      }
+    }
+
     content = (
       <ListView
         context={context}
@@ -116,6 +136,9 @@ export function AdminUI({
         basePath={basePath}
         search={search}
         page={page}
+        columns={listView?.initialColumns}
+        initialSort={listView?.initialSort}
+        sort={urlSort}
       />
     )
   }

package/src/components/ListView.tsx

@@ -3,6 +3,15 @@ import { ListViewClient } from './ListViewClient.js'
 import { formatListName } from '../lib/utils.js'
 import { type AccessContext, getDbKey, getUrlKey, OpenSaasConfig } from '@opensaas/stack-core'
 
+/**
+ * Default sort for the list table, mirroring Keystone's `ui.listView.initialSort`.
+ * Plain serializable data so it can cross the server/client boundary.
+ */
+export interface ListViewSort {
+  field: string
+  direction: 'asc' | 'desc'
+}
+
 export interface ListViewProps {
   context: AccessContext<unknown>
   config: OpenSaasConfig
@@ -12,6 +21,16 @@ export interface ListViewProps {
   page?: number
   pageSize?: number
   search?: string
+  /**
+   * Default sort from the list's `ui.listView.initialSort` config.
+   * Used when no URL sort param is present.
+   */
+  initialSort?: ListViewSort
+  /**
+   * Active sort from the `?sort=field:direction` URL param.
+   * Takes precedence over `initialSort`.
+   */
+  sort?: ListViewSort
 }
 
 /**
@@ -27,6 +46,8 @@ export async function ListView({
   page = 1,
   pageSize = 50,
   search,
+  initialSort,
+  sort,
 }: ListViewProps) {
   const key = getDbKey(listKey)
   const urlKey = getUrlKey(listKey)
@@ -43,6 +64,11 @@ export async function ListView({
     )
   }
 
+  // URL sort takes precedence over config initialSort, but only if the field
+  // actually exists on the list — an unknown field would cause Prisma to throw.
+  const validatedSort = sort && sort.field in listConfig.fields ? sort : undefined
+  const activeSort = validatedSort ?? initialSort
+
   // Fetch items using access-controlled context
   const skip = (page - 1) * pageSize
   let items: Array<Record<string, unknown>> = []
@@ -82,9 +108,11 @@ export async function ListView({
     })
     const delegate = dbContext[key]
     if (delegate?.findMany && delegate?.count) {
+      const orderBy = activeSort ? { [activeSort.field]: activeSort.direction } : undefined
       ;[items, total] = await Promise.all([
         delegate.findMany({
           where,
+          orderBy,
           skip,
           take: pageSize,
           ...(Object.keys(include).length > 0 ? { include } : {}),
@@ -142,6 +170,7 @@ export async function ListView({
         )}
         relationshipRefs={relationshipRefs}
         columns={columns}
+        initialSort={activeSort}
         listKey={listKey}
         urlKey={urlKey}
         basePath={basePath}

package/src/components/ListViewClient.tsx

@@ -1,7 +1,6 @@
 'use client'
 
 import * as React from 'react'
-import { useState } from 'react'
 import Link from 'next/link.js'
 import { useRouter } from 'next/navigation.js'
 import { formatFieldName, getFieldDisplayValue } from '../lib/utils.js'
@@ -23,6 +22,12 @@ export interface ListViewClientProps {
   fieldTypes: Record<string, string>
   relationshipRefs: Record<string, string>
   columns?: string[]
+  /**
+   * Default sort for the table (from the list's `ui.listView.initialSort`).
+   * Seeds the initial sort column/direction. When omitted, the table starts
+   * unsorted (current default behaviour).
+   */
+  initialSort?: { field: string; direction: 'asc' | 'desc' }
   listKey: string
   urlKey: string
   basePath: string
@@ -41,6 +46,7 @@ export function ListViewClient({
   fieldTypes,
   relationshipRefs,
   columns,
+  initialSort,
   urlKey,
   basePath,
   page,
@@ -49,41 +55,30 @@ export function ListViewClient({
   search: initialSearch,
 }: ListViewClientProps) {
   const router = useRouter()
-  const [sortBy, setSortBy] = useState<string | null>(null)
-  const [sortOrder, setSortOrder] = useState<'asc' | 'desc'>('asc')
-  const [searchInput, setSearchInput] = useState(initialSearch || '')
+  const sortBy = initialSort?.field ?? null
+  const sortOrder = initialSort?.direction ?? 'asc'
+  const [searchInput, setSearchInput] = React.useState(initialSearch || '')
 
   // Determine which columns to show
   const displayColumns =
     columns ||
     Object.keys(fieldTypes).filter((key) => !['password', 'createdAt', 'updatedAt'].includes(key))
 
-  // Sort items if needed
-  const sortedItems = [...items]
-  if (sortBy) {
-    sortedItems.sort((a, b) => {
-      const aVal = a[sortBy]
-      const bVal = b[sortBy]
-      if (aVal === bVal) return 0
-      // Handle unknown types for comparison - convert to string for safety
-      const aStr = String(aVal ?? '')
-      const bStr = String(bVal ?? '')
-      const comparison = aStr > bStr ? 1 : -1
-      return sortOrder === 'asc' ? comparison : -comparison
-    })
-  }
+  // Items are already sorted by the server via orderBy; no in-memory sort needed.
 
   const totalPages = Math.ceil(total / pageSize)
   const hasNextPage = page < totalPages
   const hasPrevPage = page > 1
 
   const handleSort = (column: string) => {
-    if (sortBy === column) {
-      setSortOrder(sortOrder === 'asc' ? 'desc' : 'asc')
-    } else {
-      setSortBy(column)
-      setSortOrder('asc')
+    const newDirection = sortBy === column ? (sortOrder === 'asc' ? 'desc' : 'asc') : 'asc'
+    const params = new URLSearchParams()
+    if (initialSearch) {
+      params.set('search', initialSearch)
     }
+    params.set('sort', `${column}:${newDirection}`)
+    params.set('page', '1')
+    router.push(`${basePath}/${urlKey}?${params.toString()}`)
   }
 
   const handleSearch = (e: React.FormEvent) => {
@@ -92,13 +87,21 @@ export function ListViewClient({
     if (searchInput.trim()) {
       params.set('search', searchInput.trim())
     }
+    if (sortBy) {
+      params.set('sort', `${sortBy}:${sortOrder}`)
+    }
     params.set('page', '1') // Reset to page 1 on new search
     router.push(`${basePath}/${urlKey}?${params.toString()}`)
   }
 
   const handleClearSearch = () => {
     setSearchInput('')
-    router.push(`${basePath}/${urlKey}`)
+    const params = new URLSearchParams()
+    if (sortBy) {
+      params.set('sort', `${sortBy}:${sortOrder}`)
+    }
+    const qs = params.toString()
+    router.push(`${basePath}/${urlKey}${qs ? `?${qs}` : ''}`)
   }
 
   const buildPaginationUrl = (newPage: number) => {
@@ -106,6 +109,9 @@ export function ListViewClient({
     if (initialSearch) {
       params.set('search', initialSearch)
     }
+    if (sortBy) {
+      params.set('sort', `${sortBy}:${sortOrder}`)
+    }
     params.set('page', newPage.toString())
     return `${basePath}/${urlKey}?${params.toString()}`
   }
@@ -218,14 +224,14 @@ export function ListViewClient({
             </TableRow>
           </TableHeader>
           <TableBody>
-            {sortedItems.length === 0 ? (
+            {items.length === 0 ? (
               <TableRow>
                 <TableCell colSpan={displayColumns.length + 1} className="h-24 text-center">
                   No items found
                 </TableCell>
               </TableRow>
             ) : (
-              sortedItems.map((item) => (
+              items.map((item) => (
                 <TableRow key={String(item.id)}>
                   {displayColumns.map((column) => (
                     <TableCell key={column}>

package/tests/components/AdminUIListView.test.tsx

@@ -0,0 +1,230 @@
+import { describe, it, expect, vi } from 'vitest'
+import * as React from 'react'
+import type { AccessContext, OpenSaasConfig } from '@opensaas/stack-core'
+import { list } from '@opensaas/stack-core'
+import { text, timestamp } from '@opensaas/stack-core/fields'
+import { AdminUI } from '../../src/components/AdminUI.js'
+import { ListView } from '../../src/components/ListView.js'
+
+// Mock Next.js navigation — client components call useRouter().
+const mockPush = vi.fn()
+const mockRefresh = vi.fn()
+vi.mock('next/navigation.js', () => ({
+  useRouter: () => ({ push: mockPush, refresh: mockRefresh }),
+}))
+
+vi.mock('next/link.js', () => ({
+  default: ({ children, href }: { children: React.ReactNode; href: string }) => (
+    <a href={href}>{children}</a>
+  ),
+}))
+
+interface DelegateStub {
+  findMany?: (args: unknown) => Promise<Array<Record<string, unknown>>>
+  count?: (args: unknown) => Promise<number>
+}
+
+function makeContext(delegates: Record<string, DelegateStub>): AccessContext<unknown> {
+  const context = {
+    db: delegates,
+    session: null,
+    storage: {},
+    plugins: {},
+    _isSudo: false,
+    _resolveOutputCounter: { depth: 0 },
+  }
+  return context as unknown as AccessContext<unknown>
+}
+
+const noopServerAction = vi.fn(async () => ({ success: true }))
+
+/**
+ * AdminUI returns <> {style?} <div><Navigation/><main>{content}</main></div> </>.
+ * Drill into <main> to recover the routed content element (the <ListView /> the
+ * router chose for the bare [list] route) so we can inspect the props AdminUI
+ * passed to it.
+ */
+function routedContent(tree: React.ReactNode): React.ReactElement {
+  const fragment = tree as React.ReactElement<{ children: React.ReactNode }>
+  const children = React.Children.toArray(fragment.props.children)
+  const wrapper = children.find(
+    (child): child is React.ReactElement<{ children: React.ReactNode }> =>
+      React.isValidElement(child) && child.type === 'div',
+  )
+  if (!wrapper) throw new Error('AdminUI layout wrapper not found')
+  const main = React.Children.toArray(wrapper.props.children).find(
+    (child): child is React.ReactElement<{ children: React.ReactNode }> =>
+      React.isValidElement(child) && child.type === 'main',
+  )
+  if (!main) throw new Error('AdminUI <main> not found')
+  return main.props.children as React.ReactElement
+}
+
+describe('AdminUI ui.listView wiring', () => {
+  it('passes orderBy to findMany based on initialSort', async () => {
+    const findMany = vi.fn(async () => [])
+    const count = vi.fn(async () => 0)
+
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite', url: 'file:./test.db' },
+      lists: {
+        Post: list({
+          fields: { title: text(), sentAt: timestamp() },
+          ui: {
+            listView: {
+              initialSort: { field: 'sentAt', direction: 'desc' },
+            },
+          },
+        }),
+      },
+    }
+
+    const context = makeContext({ post: { findMany, count } })
+
+    await ListView({
+      context,
+      config,
+      listKey: 'Post',
+      basePath: '/admin',
+      initialSort: { field: 'sentAt', direction: 'desc' },
+    })
+
+    expect(findMany).toHaveBeenCalledWith(expect.objectContaining({ orderBy: { sentAt: 'desc' } }))
+  })
+
+  it('URL sort param takes precedence over initialSort in orderBy', async () => {
+    const findMany = vi.fn(async () => [])
+    const count = vi.fn(async () => 0)
+
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite', url: 'file:./test.db' },
+      lists: {
+        Post: list({
+          fields: { title: text(), sentAt: timestamp() },
+          ui: {
+            listView: {
+              initialSort: { field: 'sentAt', direction: 'desc' },
+            },
+          },
+        }),
+      },
+    }
+
+    const context = makeContext({ post: { findMany, count } })
+
+    await ListView({
+      context,
+      config,
+      listKey: 'Post',
+      basePath: '/admin',
+      initialSort: { field: 'sentAt', direction: 'desc' },
+      sort: { field: 'title', direction: 'asc' },
+    })
+
+    expect(findMany).toHaveBeenCalledWith(expect.objectContaining({ orderBy: { title: 'asc' } }))
+  })
+
+  it('discards URL sort param when field does not exist on the list, falling back to initialSort', async () => {
+    const findMany = vi.fn(async () => [])
+    const count = vi.fn(async () => 0)
+
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite', url: 'file:./test.db' },
+      lists: {
+        Post: list({
+          fields: { title: text(), sentAt: timestamp() },
+          ui: {
+            listView: {
+              initialSort: { field: 'sentAt', direction: 'desc' },
+            },
+          },
+        }),
+      },
+    }
+
+    const context = makeContext({ post: { findMany, count } })
+
+    await ListView({
+      context,
+      config,
+      listKey: 'Post',
+      basePath: '/admin',
+      initialSort: { field: 'sentAt', direction: 'desc' },
+      sort: { field: 'nonExistentField', direction: 'asc' },
+    })
+
+    // Unknown field is rejected; falls back to initialSort.
+    expect(findMany).toHaveBeenCalledWith(expect.objectContaining({ orderBy: { sentAt: 'desc' } }))
+  })
+
+  it('passes initialColumns + initialSort from ui.listView to ListView', async () => {
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite', url: 'file:./test.db' },
+      lists: {
+        Post: list({
+          fields: {
+            title: text(),
+            status: text(),
+            createdAt: timestamp(),
+          },
+          ui: {
+            listView: {
+              initialColumns: ['title', 'status'],
+              initialSort: { field: 'createdAt', direction: 'desc' },
+            },
+          },
+        }),
+      },
+    }
+
+    const context = makeContext({
+      post: { findMany: vi.fn(async () => []), count: vi.fn(async () => 0) },
+    })
+
+    const tree = await AdminUI({
+      context,
+      config,
+      params: ['post'],
+      basePath: '/admin',
+      serverAction: noopServerAction,
+    })
+
+    const content = routedContent(tree)
+    expect(content.type).toBe(ListView)
+    // initialColumns drives the `columns` prop (selection + order).
+    expect(content.props.columns).toEqual(['title', 'status'])
+    // initialSort flows through as the default sort.
+    expect(content.props.initialSort).toEqual({ field: 'createdAt', direction: 'desc' })
+  })
+
+  it('passes undefined columns + initialSort when ui.listView is absent', async () => {
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite', url: 'file:./test.db' },
+      lists: {
+        Post: list({
+          fields: {
+            title: text(),
+          },
+        }),
+      },
+    }
+
+    const context = makeContext({
+      post: { findMany: vi.fn(async () => []), count: vi.fn(async () => 0) },
+    })
+
+    const tree = await AdminUI({
+      context,
+      config,
+      params: ['post'],
+      basePath: '/admin',
+      serverAction: noopServerAction,
+    })
+
+    const content = routedContent(tree)
+    expect(content.type).toBe(ListView)
+    // Absent config → current behaviour unchanged (no column override, no default sort).
+    expect(content.props.columns).toBeUndefined()
+    expect(content.props.initialSort).toBeUndefined()
+  })
+})

package/tests/components/ListViewClient.test.tsx

@@ -73,58 +73,107 @@ describe('ListViewClient', () => {
       expect(screen.getByText('Status')).toBeInTheDocument()
       expect(screen.queryByText('Views')).not.toBeInTheDocument()
     })
-  })
 
-  describe('sorting', () => {
-    it('should sort items ascending when header clicked', async () => {
-      const user = userEvent.setup()
-      render(<ListViewClient {...defaultProps} />)
+    it('should render columns in the provided order (initialColumns)', () => {
+      // initialColumns flows through AdminUI as the `columns` prop and drives
+      // both selection AND order.
+      render(<ListViewClient {...defaultProps} columns={['views', 'title']} />)
 
-      await user.click(screen.getByText('Title'))
+      const headers = screen.getAllByRole('columnheader')
+      // First two headers should follow the provided order, then Actions.
+      expect(headers[0]).toHaveTextContent('Views')
+      expect(headers[1]).toHaveTextContent('Title')
+      expect(headers[2]).toHaveTextContent('Actions')
+      // Unlisted column is excluded.
+      expect(screen.queryByText('Status')).not.toBeInTheDocument()
+    })
+  })
 
-      const rows = screen.getAllByRole('row')
-      // First row is header, so data rows start at index 1
-      expect(rows[1]).toHaveTextContent('First Post')
-      expect(rows[2]).toHaveTextContent('Second Post')
-      expect(rows[3]).toHaveTextContent('Third Post')
+  describe('initialSort', () => {
+    it('should show sort indicator on the initialSort column (asc)', () => {
+      render(
+        <ListViewClient {...defaultProps} initialSort={{ field: 'title', direction: 'asc' }} />,
+      )
+
+      expect(screen.getByText('↑')).toBeInTheDocument()
     })
 
-    it('should toggle sort order when same header clicked twice', async () => {
-      const user = userEvent.setup()
-      render(<ListViewClient {...defaultProps} />)
+    it('should show sort indicator on the initialSort column (desc)', () => {
+      render(
+        <ListViewClient {...defaultProps} initialSort={{ field: 'title', direction: 'desc' }} />,
+      )
 
-      const titleHeader = screen.getByText('Title')
-      await user.click(titleHeader)
-      await user.click(titleHeader)
+      expect(screen.getByText('↓')).toBeInTheDocument()
+    })
+
+    it('should preserve item order provided by server (no in-memory sort)', () => {
+      // Items arrive pre-sorted by the server; the client renders them as-is.
+      const sortedItems = [
+        { id: '3', title: 'Third Post', status: 'published', views: 200 },
+        { id: '2', title: 'Second Post', status: 'draft', views: 50 },
+        { id: '1', title: 'First Post', status: 'published', views: 100 },
+      ]
+      render(
+        <ListViewClient
+          {...defaultProps}
+          items={sortedItems}
+          initialSort={{ field: 'title', direction: 'desc' }}
+        />,
+      )
 
       const rows = screen.getAllByRole('row')
-      // Should be descending now
       expect(rows[1]).toHaveTextContent('Third Post')
       expect(rows[2]).toHaveTextContent('Second Post')
       expect(rows[3]).toHaveTextContent('First Post')
     })
 
-    it('should show sort indicator on active column', async () => {
+    it('should not apply any default sort when initialSort is absent', () => {
+      render(<ListViewClient {...defaultProps} />)
+
+      // No sort indicator when no initialSort.
+      expect(screen.queryByText('↑')).not.toBeInTheDocument()
+      expect(screen.queryByText('↓')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('sorting', () => {
+    it('should navigate with sort param when column header clicked', async () => {
       const user = userEvent.setup()
       render(<ListViewClient {...defaultProps} />)
 
       await user.click(screen.getByText('Title'))
 
+      expect(mockPush).toHaveBeenCalledWith('/admin/post?sort=title%3Aasc&page=1')
+    })
+
+    it('should navigate with toggled direction when already-sorted column clicked', async () => {
+      const user = userEvent.setup()
+      render(
+        <ListViewClient {...defaultProps} initialSort={{ field: 'title', direction: 'asc' }} />,
+      )
+
+      await user.click(screen.getByText('Title'))
+
+      expect(mockPush).toHaveBeenCalledWith('/admin/post?sort=title%3Adesc&page=1')
+    })
+
+    it('should show sort indicator on active column', async () => {
+      render(
+        <ListViewClient {...defaultProps} initialSort={{ field: 'title', direction: 'asc' }} />,
+      )
+
       expect(screen.getByText('↑')).toBeInTheDocument()
     })
 
-    it('should sort numeric fields correctly', async () => {
+    it('should navigate with asc when switching to a different column', async () => {
       const user = userEvent.setup()
-      render(<ListViewClient {...defaultProps} />)
+      render(
+        <ListViewClient {...defaultProps} initialSort={{ field: 'title', direction: 'desc' }} />,
+      )
 
       await user.click(screen.getByText('Views'))
 
-      const rows = screen.getAllByRole('row')
-      // Should sort by views: 100, 200, 50 (string comparison)
-      // Note: The current implementation sorts as strings, not numbers
-      expect(rows[1]).toHaveTextContent('100')
-      expect(rows[2]).toHaveTextContent('200')
-      expect(rows[3]).toHaveTextContent('50')
+      expect(mockPush).toHaveBeenCalledWith('/admin/post?sort=views%3Aasc&page=1')
     })
   })
 
@@ -181,6 +230,22 @@ describe('ListViewClient', () => {
       expect(mockPush).toHaveBeenCalledWith('/admin/post')
     })
 
+    it('should preserve active sort when search is cleared', async () => {
+      const user = userEvent.setup()
+      render(
+        <ListViewClient
+          {...defaultProps}
+          search="existing"
+          initialSort={{ field: 'title', direction: 'desc' }}
+        />,
+      )
+
+      const clearButton = screen.getByText('✕')
+      await user.click(clearButton)
+
+      expect(mockPush).toHaveBeenCalledWith('/admin/post?sort=title%3Adesc')
+    })
+
     it('should reset to page 1 when new search submitted', async () => {
       const user = userEvent.setup()
       render(<ListViewClient {...defaultProps} page={3} />)
@@ -264,6 +329,24 @@ describe('ListViewClient', () => {
 
       expect(mockPush).toHaveBeenCalledWith('/admin/post?search=test&page=2')
     })
+
+    it('should preserve sort in pagination URLs', async () => {
+      const user = userEvent.setup()
+      render(
+        <ListViewClient
+          {...defaultProps}
+          total={100}
+          pageSize={10}
+          page={1}
+          initialSort={{ field: 'title', direction: 'desc' }}
+        />,
+      )
+
+      const nextButton = screen.getByRole('button', { name: /next/i })
+      await user.click(nextButton)
+
+      expect(mockPush).toHaveBeenCalledWith('/admin/post?sort=title%3Adesc&page=2')
+    })
   })
 
   describe('relationships', () => {