@opensaas/stack-ui 0.23.0 → 0.24.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.24.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.24.0 build:css
 > mkdir -p dist/styles && postcss ./src/styles/globals.css -o ./dist/styles/globals.css
 

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @opensaas/stack-ui
 
+## 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,2CAuGd"}

package/dist/components/AdminUI.js

@@ -55,7 +55,12 @@ 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;
+        content = (_jsx(ListView, { context: context, config: config, listKey: listKey, basePath: basePath, search: search, page: page, columns: listView?.initialColumns, initialSort: listView?.initialSort }));
     }
     // 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,15 @@ export interface ListViewProps {
     page?: number;
     pageSize?: number;
     search?: string;
+    /**
+     * Default sort applied to the table (from the list's `ui.listView.initialSort`).
+     * When omitted, no default sort is applied.
+     */
+    initialSort?: 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, }: 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;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"}

package/dist/components/ListView.js

@@ -7,7 +7,7 @@ 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, }) {
     const key = getDbKey(listKey);
     const urlKey = getUrlKey(listKey);
     const listConfig = config.lists[listKey];
@@ -79,5 +79,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: initialSort, 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":"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"}

package/dist/components/ListViewClient.js

@@ -14,10 +14,10 @@ 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 [sortBy, setSortBy] = useState(initialSort?.field ?? null);
+    const [sortOrder, setSortOrder] = useState(initialSort?.direction ?? 'asc');
     const [searchInput, setSearchInput] = useState(initialSearch || '');
     // Determine which columns to show
     const displayColumns = columns ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-ui",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Composable React UI components for OpenSaas Stack",
   "type": "module",
   "main": "./dist/index.js",
@@ -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.24.0"
   },
   "scripts": {
     "build": "tsc && npm run build:css",

package/src/components/AdminUI.tsx

@@ -108,6 +108,12 @@ 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
+
     content = (
       <ListView
         context={context}
@@ -116,6 +122,8 @@ export function AdminUI({
         basePath={basePath}
         search={search}
         page={page}
+        columns={listView?.initialColumns}
+        initialSort={listView?.initialSort}
       />
     )
   }

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,11 @@ export interface ListViewProps {
   page?: number
   pageSize?: number
   search?: string
+  /**
+   * Default sort applied to the table (from the list's `ui.listView.initialSort`).
+   * When omitted, no default sort is applied.
+   */
+  initialSort?: ListViewSort
 }
 
 /**
@@ -27,6 +41,7 @@ export async function ListView({
   page = 1,
   pageSize = 50,
   search,
+  initialSort,
 }: ListViewProps) {
   const key = getDbKey(listKey)
   const urlKey = getUrlKey(listKey)
@@ -142,6 +157,7 @@ export async function ListView({
         )}
         relationshipRefs={relationshipRefs}
         columns={columns}
+        initialSort={initialSort}
         listKey={listKey}
         urlKey={urlKey}
         basePath={basePath}

package/src/components/ListViewClient.tsx

@@ -23,6 +23,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 +47,7 @@ export function ListViewClient({
   fieldTypes,
   relationshipRefs,
   columns,
+  initialSort,
   urlKey,
   basePath,
   page,
@@ -49,8 +56,8 @@ export function ListViewClient({
   search: initialSearch,
 }: ListViewClientProps) {
   const router = useRouter()
-  const [sortBy, setSortBy] = useState<string | null>(null)
-  const [sortOrder, setSortOrder] = useState<'asc' | 'desc'>('asc')
+  const [sortBy, setSortBy] = useState<string | null>(initialSort?.field ?? null)
+  const [sortOrder, setSortOrder] = useState<'asc' | 'desc'>(initialSort?.direction ?? 'asc')
   const [searchInput, setSearchInput] = useState(initialSearch || '')
 
   // Determine which columns to show

package/tests/components/AdminUIListView.test.tsx

@@ -0,0 +1,134 @@
+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 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,6 +73,66 @@ describe('ListViewClient', () => {
       expect(screen.getByText('Status')).toBeInTheDocument()
       expect(screen.queryByText('Views')).not.toBeInTheDocument()
     })
+
+    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']} />)
+
+      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()
+    })
+  })
+
+  describe('initialSort', () => {
+    it('should apply default sort from initialSort without any click', () => {
+      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')
+    })
+
+    it('should respect descending direction from initialSort', () => {
+      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')
+    })
+
+    it('should show sort indicator on the initialSort column', () => {
+      render(
+        <ListViewClient {...defaultProps} initialSort={{ field: 'title', direction: 'desc' }} />,
+      )
+
+      expect(screen.getByText('↓')).toBeInTheDocument()
+    })
+
+    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')
+      expect(screen.queryByText('↑')).not.toBeInTheDocument()
+      expect(screen.queryByText('↓')).not.toBeInTheDocument()
+    })
   })
 
   describe('sorting', () => {