@opensaas/stack-ui 0.24.0 → 0.25.0

package/.turbo/turbo-build.log

@@ -1,11 +1,11 @@
 
-> @opensaas/stack-ui@0.24.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.24.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,15 @@
 # @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

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,2CAuGd"}
+{"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

@@ -60,7 +60,20 @@ export function AdminUI({ context, config, params = [], searchParams = {}, baseP
         // ListView falls back to its existing defaults (all non-system fields,
         // no default sort).
         const listView = config.lists[listKey]?.ui?.listView;
-        content = (_jsx(ListView, { context: context, config: config, listKey: listKey, basePath: basePath, search: search, page: page, columns: listView?.initialColumns, initialSort: listView?.initialSort }));
+        // 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

@@ -17,14 +17,19 @@ export interface ListViewProps {
     pageSize?: number;
     search?: string;
     /**
-     * Default sort applied to the table (from the list's `ui.listView.initialSort`).
-     * When omitted, no default sort is applied.
+     * 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, initialSort, }: 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;;;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;CAC3B;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,EAC7B,OAAO,EACP,MAAM,EACN,OAAO,EACP,QAAmB,EACnB,OAAO,EACP,IAAQ,EACR,QAAa,EACb,MAAM,EACN,WAAW,GACZ,EAAE,aAAa,oDA8Hf"}
+{"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, initialSort, }) {
+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, initialSort: initialSort, 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.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;;;;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"}
+{"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';
@@ -16,38 +15,25 @@ import { getUrlKey } from '@opensaas/stack-core';
  */
 export function ListViewClient({ items, fieldTypes, relationshipRefs, columns, initialSort, urlKey, basePath, page, pageSize, total, search: initialSearch, }) {
     const router = useRouter();
-    const [sortBy, setSortBy] = useState(initialSort?.field ?? null);
-    const [sortOrder, setSortOrder] = useState(initialSort?.direction ?? '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, i
         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, i
         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.24.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.24.0"
+    "@opensaas/stack-core": "0.25.0"
   },
   "scripts": {
     "build": "tsc && npm run build:css",

package/src/components/AdminUI.tsx

@@ -114,6 +114,20 @@ export function AdminUI({
     // 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}
@@ -124,6 +138,7 @@ export function AdminUI({
         page={page}
         columns={listView?.initialColumns}
         initialSort={listView?.initialSort}
+        sort={urlSort}
       />
     )
   }

package/src/components/ListView.tsx

@@ -22,10 +22,15 @@ export interface ListViewProps {
   pageSize?: number
   search?: string
   /**
-   * Default sort applied to the table (from the list's `ui.listView.initialSort`).
-   * When omitted, no default sort is applied.
+   * 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
 }
 
 /**
@@ -42,6 +47,7 @@ export async function ListView({
   pageSize = 50,
   search,
   initialSort,
+  sort,
 }: ListViewProps) {
   const key = getDbKey(listKey)
   const urlKey = getUrlKey(listKey)
@@ -58,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>> = []
@@ -97,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 } : {}),
@@ -157,7 +170,7 @@ export async function ListView({
         )}
         relationshipRefs={relationshipRefs}
         columns={columns}
-        initialSort={initialSort}
+        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'
@@ -56,41 +55,30 @@ export function ListViewClient({
   search: initialSearch,
 }: ListViewClientProps) {
   const router = useRouter()
-  const [sortBy, setSortBy] = useState<string | null>(initialSort?.field ?? null)
-  const [sortOrder, setSortOrder] = useState<'asc' | 'desc'>(initialSort?.direction ?? '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) => {
@@ -99,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) => {
@@ -113,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()}`
   }
@@ -225,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

@@ -61,6 +61,102 @@ function routedContent(tree: React.ReactNode): 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' },

package/tests/components/ListViewClient.test.tsx

@@ -90,101 +90,90 @@ describe('ListViewClient', () => {
   })
 
   describe('initialSort', () => {
-    it('should apply default sort from initialSort without any click', () => {
+    it('should show sort indicator on the initialSort column (asc)', () => {
       render(
         <ListViewClient {...defaultProps} initialSort={{ field: 'title', direction: 'asc' }} />,
       )
 
-      const rows = screen.getAllByRole('row')
-      // Sorted ascending by title: First, Second, Third
-      expect(rows[1]).toHaveTextContent('First Post')
-      expect(rows[2]).toHaveTextContent('Second Post')
-      expect(rows[3]).toHaveTextContent('Third Post')
+      expect(screen.getByText('↑')).toBeInTheDocument()
     })
 
-    it('should respect descending direction from initialSort', () => {
+    it('should show sort indicator on the initialSort column (desc)', () => {
       render(
         <ListViewClient {...defaultProps} initialSort={{ field: 'title', direction: 'desc' }} />,
       )
 
-      const rows = screen.getAllByRole('row')
-      // Sorted descending by title: Third, Second, First
-      expect(rows[1]).toHaveTextContent('Third Post')
-      expect(rows[2]).toHaveTextContent('Second Post')
-      expect(rows[3]).toHaveTextContent('First Post')
+      expect(screen.getByText('↓')).toBeInTheDocument()
     })
 
-    it('should show sort indicator on the initialSort column', () => {
+    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} initialSort={{ field: 'title', direction: 'desc' }} />,
+        <ListViewClient
+          {...defaultProps}
+          items={sortedItems}
+          initialSort={{ field: 'title', direction: 'desc' }}
+        />,
       )
 
-      expect(screen.getByText('↓')).toBeInTheDocument()
+      const rows = screen.getAllByRole('row')
+      expect(rows[1]).toHaveTextContent('Third Post')
+      expect(rows[2]).toHaveTextContent('Second Post')
+      expect(rows[3]).toHaveTextContent('First Post')
     })
 
     it('should not apply any default sort when initialSort is absent', () => {
       render(<ListViewClient {...defaultProps} />)
 
-      const rows = screen.getAllByRole('row')
-      // Unchanged: items render in their original (input) order, no indicator.
-      expect(rows[1]).toHaveTextContent('First Post')
-      expect(rows[2]).toHaveTextContent('Second Post')
-      expect(rows[3]).toHaveTextContent('Third Post')
+      // No sort indicator when no initialSort.
       expect(screen.queryByText('↑')).not.toBeInTheDocument()
       expect(screen.queryByText('↓')).not.toBeInTheDocument()
     })
   })
 
   describe('sorting', () => {
-    it('should sort items ascending when header clicked', async () => {
+    it('should navigate with sort param when column header clicked', async () => {
       const user = userEvent.setup()
       render(<ListViewClient {...defaultProps} />)
 
       await user.click(screen.getByText('Title'))
 
-      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')
+      expect(mockPush).toHaveBeenCalledWith('/admin/post?sort=title%3Aasc&page=1')
     })
 
-    it('should toggle sort order when same header clicked twice', async () => {
+    it('should navigate with toggled direction when already-sorted column clicked', async () => {
       const user = userEvent.setup()
-      render(<ListViewClient {...defaultProps} />)
+      render(
+        <ListViewClient {...defaultProps} initialSort={{ field: 'title', direction: 'asc' }} />,
+      )
 
-      const titleHeader = screen.getByText('Title')
-      await user.click(titleHeader)
-      await user.click(titleHeader)
+      await user.click(screen.getByText('Title'))
 
-      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')
+      expect(mockPush).toHaveBeenCalledWith('/admin/post?sort=title%3Adesc&page=1')
     })
 
     it('should show sort indicator on active column', async () => {
-      const user = userEvent.setup()
-      render(<ListViewClient {...defaultProps} />)
-
-      await user.click(screen.getByText('Title'))
+      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')
     })
   })
 
@@ -241,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} />)
@@ -324,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', () => {