@byline/host-tanstack-start 4.5.0 → 4.6.0

package/dist/server-fns/collections/list.js

@@ -1,7 +1,10 @@
 import { createServerFn } from "@tanstack/react-start";
-import { getAdminBylineClient } from "@byline/client/server";
+import { getPreferenceCommand } from "@byline/admin/admin-preferences";
+import { getAdminBylineClient, getAdminRequestContext } from "@byline/client/server";
 import { ERR_NOT_FOUND, buildRelationSummaryPopulateMap, getCollectionAdminConfig, getCollectionDefinition, getCollectionSchemasForPath, getLogger, getServerConfig } from "@byline/core";
 import { ensureCollection } from "../../integrations/api-utils.js";
+import { bylineCore } from "../../integrations/byline-core.js";
+import { resolveListViewState, sortableFieldNames } from "./list-view-state.js";
 import { serialise } from "./utils.js";
 const getCollectionDocuments = createServerFn({
     method: 'GET'
@@ -16,23 +19,42 @@ const getCollectionDocuments = createServerFn({
     }).log(getLogger());
     const client = getAdminBylineClient();
     const handle = client.collection(path);
-    const pageSize = params.page_size ?? 20;
     const where = {};
     if (params.status) where.status = params.status;
     if (params.query) where.query = params.query;
     const adminConfig = getCollectionAdminConfig(path);
-    const configuredSort = params.order || true === config.definition.orderable || adminConfig?.defaultSort == null ? void 0 : {
+    const configuredSort = true !== config.definition.orderable && adminConfig?.defaultSort != null ? {
         order: String(adminConfig.defaultSort.field),
         desc: 'desc' === adminConfig.defaultSort.direction
-    };
-    const defaultSort = true === config.definition.orderable ? {
-        order_key: 'asc'
-    } : null != configuredSort ? {
-        [configuredSort.order]: configuredSort.desc ? 'desc' : 'asc'
     } : void 0;
-    const sortSpec = params.order ? {
-        [params.order]: false === params.desc ? 'asc' : 'desc'
-    } : defaultSort;
+    let preference = null;
+    const adminStore = bylineCore().adminStore;
+    if (null != adminStore && (null == params.page_size || null == params.order)) try {
+        const context = await getAdminRequestContext();
+        const res = await getPreferenceCommand(context, {
+            scope: `collections.${path}.list`
+        }, {
+            store: adminStore
+        });
+        preference = res.value ?? null;
+    } catch (err) {
+        getLogger().warn({
+            err,
+            collection: path
+        }, 'list-view preference read failed — using defaults');
+    }
+    const viewState = resolveListViewState({
+        params: {
+            page_size: params.page_size,
+            order: params.order,
+            desc: params.desc
+        },
+        preference,
+        orderable: true === config.definition.orderable,
+        sortableFields: sortableFieldNames(config.definition.fields),
+        configuredSort
+    });
+    const pageSize = viewState.pageSize;
     const populateMap = buildRelationSummaryPopulateMap(config.definition.fields, (targetPath)=>({
             def: getCollectionDefinition(targetPath),
             admin: getCollectionAdminConfig(targetPath)
@@ -41,7 +63,7 @@ const getCollectionDocuments = createServerFn({
     const populate = hasRelations ? populateMap : void 0;
     const result = await handle.find({
         where: Object.keys(where).length > 0 ? where : void 0,
-        sort: sortSpec,
+        sort: viewState.sort,
         locale: params.locale ?? 'en',
         page: params.page,
         pageSize,
@@ -64,8 +86,9 @@ const getCollectionDocuments = createServerFn({
         docs,
         meta: {
             ...result.meta,
-            order: params.order ?? configuredSort?.order,
-            desc: params.desc ?? configuredSort?.desc
+            order: viewState.metaOrder,
+            desc: viewState.metaDesc,
+            pageSize
         },
         included: {
             collection: {

package/dist/server-fns/collections/set-list-view-preference.d.ts

@@ -0,0 +1,18 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export interface SetListViewPreferenceInput {
+    collection: string;
+    value: {
+        page_size?: number;
+        order?: string;
+        desc?: boolean;
+    };
+}
+export declare const setListViewPreference: import("@tanstack/react-start").RequiredFetcher<undefined, (input: SetListViewPreferenceInput) => SetListViewPreferenceInput, Promise<{
+    ok: true;
+}>>;

package/dist/server-fns/collections/set-list-view-preference.js

@@ -0,0 +1,32 @@
+import { createServerFn } from "@tanstack/react-start";
+import { setPreferenceCommand } from "@byline/admin/admin-preferences";
+import { getAdminRequestContext } from "@byline/client/server";
+import { ERR_NOT_FOUND, getLogger } from "@byline/core";
+import { ensureCollection } from "../../integrations/api-utils.js";
+import { bylineCore } from "../../integrations/byline-core.js";
+const setListViewPreference = createServerFn({
+    method: 'POST'
+}).validator((input)=>input).handler(async ({ data })=>{
+    const config = await ensureCollection(data.collection);
+    if (!config) throw ERR_NOT_FOUND({
+        message: 'Collection not found',
+        details: {
+            collectionPath: data.collection
+        }
+    }).log(getLogger());
+    const adminStore = bylineCore().adminStore;
+    if (null == adminStore) return {
+        ok: true
+    };
+    const context = await getAdminRequestContext();
+    await setPreferenceCommand(context, {
+        scope: `collections.${data.collection}.list`,
+        value: data.value
+    }, {
+        store: adminStore
+    });
+    return {
+        ok: true
+    };
+});
+export { setListViewPreference };

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -118,13 +118,13 @@
     "react-json-view-lite": "^2.5.0",
     "react-swipeable": "^7.0.2",
     "zod": "^4.4.3",
-    "@byline/ai": "4.5.0",
-    "@byline/core": "4.5.0",
-    "@byline/client": "4.5.0",
-    "@byline/i18n": "4.5.0",
-    "@byline/ui": "4.5.0",
-    "@byline/admin": "4.5.0",
-    "@byline/auth": "4.5.0"
+    "@byline/admin": "4.6.0",
+    "@byline/client": "4.6.0",
+    "@byline/auth": "4.6.0",
+    "@byline/core": "4.6.0",
+    "@byline/ai": "4.6.0",
+    "@byline/ui": "4.6.0",
+    "@byline/i18n": "4.6.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.167.0",

package/src/admin-shell/chrome/th-sortable.tsx

@@ -37,6 +37,13 @@ export interface TableHeadingCellSortableProps extends TableHeadingCellProps {
    */
   activeOrder?: string
   activeDesc?: boolean
+  /**
+   * Fired after a sort click navigates, with the new order/direction.
+   * The collection list uses this to persist the choice as a sticky
+   * per-user preference; surfaces that omit it (admin-users) are
+   * unaffected.
+   */
+  onSort?: (order: string, desc: boolean) => void
 }
 
 export function TableHeadingCellSortable({
@@ -48,6 +55,7 @@ export function TableHeadingCellSortable({
   className,
   activeOrder,
   activeDesc,
+  onSort,
   ...rest
 }: TableHeadingCellSortableProps & {
   ref?: React.RefObject<HTMLTableCellElement>
@@ -68,6 +76,7 @@ export function TableHeadingCellSortable({
         to: location.pathname as never,
         search: params,
       })
+      onSort?.(fieldName, descending)
     }
   }
 

package/src/admin-shell/collections/create.tsx

@@ -14,6 +14,7 @@ import { useTranslation } from '@byline/i18n/react'
 import { Container, Section, useToastManager } from '@byline/ui/react'
 
 import { getAdminRoutePath } from '../../routes/admin-path.js'
+import { decodeListReturnState } from '../../routes/list-return-state.js'
 import { createCollectionDocument } from '../../server-fns/collections/index.js'
 import { useNavigate } from '../chrome/loose-router.js'
 import { useTanStackNavigationGuard } from './tanstack-navigation-guard.js'
@@ -27,11 +28,14 @@ export const CreateView = ({
   collectionDefinition,
   adminConfig,
   initialData,
+  from,
 }: {
   collectionDefinition: CollectionDefinition
   adminConfig?: CollectionAdminConfig
   // biome-ignore lint/suspicious/noExplicitAny: shape is collection-specific
   initialData?: Record<string, any>
+  /** URL-encoded list search state to return to on cancel — see list-return-state.ts. */
+  from?: string
 }) => {
   const toastManager = useToastManager()
   const { t } = useTranslation('byline-admin')
@@ -62,20 +66,22 @@ export const CreateView = ({
         },
       })
       // Create → edit: land the editor on the new document, where the rest
-      // of the work (content, status, relations) happens. The list-view
-      // fallback covers callers running against an older server fn that
-      // doesn't return the new document's id.
+      // of the work (content, status, relations) happens. `from` threads
+      // forward so closing the brand-new document also returns to the
+      // originating list. The list-view fallback covers callers running
+      // against an older server fn that doesn't return the new document's
+      // id — it restores the return state directly.
       if (result?.documentId) {
         navigate({
           to: getAdminRoutePath('collections', '$collection', '$id'),
           params: { collection: path, id: result.documentId } as never,
-          search: { action: 'created' },
+          search: { action: 'created', from },
         })
       } else {
         navigate({
           to: getAdminRoutePath('collections', '$collection'),
           params: { collection: path },
-          search: { action: 'created' },
+          search: { ...decodeListReturnState(from), action: 'created' },
         })
       }
     } catch (err) {
@@ -120,6 +126,7 @@ export const CreateView = ({
             navigate({
               to: getAdminRoutePath('collections', '$collection'),
               params: { collection: path },
+              search: decodeListReturnState(from),
             })
           }
           collectionPath={path}

package/src/admin-shell/collections/edit.tsx

@@ -44,6 +44,7 @@ export const EditView = ({
   locale,
   contentLocales,
   defaultContentLocale,
+  returnSearch,
 }: {
   collectionDefinition: CollectionDefinition
   adminConfig?: CollectionAdminConfig
@@ -51,6 +52,8 @@ export const EditView = ({
   locale?: string
   contentLocales: ReadonlyArray<ContentLocaleOption>
   defaultContentLocale: string
+  /** URL-encoded list search state to return to on close — see list-return-state.ts. */
+  returnSearch?: Record<string, unknown>
 }) => {
   const toastManager = useToastManager()
   const { t } = useTranslation('byline-admin')
@@ -77,7 +80,7 @@ export const EditView = ({
     navigate({
       to: getAdminRoutePath('collections', '$collection', '$id'),
       params: { collection: path, id: String(initialData.id) },
-      search: { locale: newLocale },
+      search: (prev: Record<string, unknown>) => ({ ...prev, locale: newLocale }),
     })
   }
 
@@ -196,10 +199,13 @@ export const EditView = ({
         status: 'success',
         message: t('collections.edit.duplicatedSuccessMessage', { label: singular }),
       })
-      // Navigate to the new document's edit view.
+      // Navigate to the new document's edit view. Threads the current
+      // search (including `from`) forward so closing the duplicate
+      // returns to the originating list.
       navigate({
         to: getAdminRoutePath('collections', '$collection', '$id'),
         params: { collection: path, id: result.documentId },
+        search: (prev: Record<string, unknown>) => ({ ...prev }),
       })
     } catch (err) {
       console.error('Duplicate error:', err)
@@ -274,7 +280,7 @@ export const EditView = ({
       navigate({
         to: getAdminRoutePath('collections', '$collection', '$id'),
         params: { collection: path, id: String(initialData.id) },
-        search: { locale: targetLocale },
+        search: (prev: Record<string, unknown>) => ({ ...prev, locale: targetLocale }),
       })
     } catch (err) {
       console.error('Copy to locale error:', err)
@@ -326,7 +332,7 @@ export const EditView = ({
       navigate({
         to: getAdminRoutePath('collections', '$collection', '$id'),
         params: { collection: path, id: String(initialData.id) },
-        search: { locale: defaultContentLocale },
+        search: (prev: Record<string, unknown>) => ({ ...prev, locale: defaultContentLocale }),
       })
     } catch (err) {
       console.error('Delete locale error:', err)
@@ -371,6 +377,7 @@ export const EditView = ({
       navigate({
         to: getAdminRoutePath('collections', '$collection'),
         params: { collection: path },
+        search: returnSearch,
       })
     } catch (err) {
       console.error('Delete error:', err)
@@ -533,6 +540,7 @@ export const EditView = ({
             navigate({
               to: getAdminRoutePath('collections', '$collection'),
               params: { collection: path },
+              search: returnSearch,
             })
           }
           collectionPath={path}

package/src/admin-shell/collections/list.tsx

@@ -44,6 +44,8 @@ import {
 import cx from 'classnames'
 
 import { getAdminRoutePath } from '../../routes/admin-path.js'
+import { encodeListReturnState } from '../../routes/list-return-state.js'
+import { setListViewPreference } from '../../server-fns/collections/index.js'
 import { Link, useNavigate } from '../chrome/loose-router.js'
 import { RouterPager } from '../chrome/router-pager.js'
 import { SortAscendingIcon } from '../chrome/sort-icons.js'
@@ -199,6 +201,7 @@ export const ListView = ({
   // the stored order and "drop between A and B" maps onto the wrong
   // neighbour ids.
   const searchParams = location.search as {
+    page_size?: number
     order?: string
     desc?: boolean
     query?: string
@@ -269,6 +272,22 @@ export const ListView = ({
     [workflowStatuses, t]
   )
 
+  // Same identity-stability rationale as `statusItems` above: this Select is
+  // now controlled by `value`, so a fresh `items` array identity on every
+  // render would trip Base UI's SelectRoot store-sync loop.
+  // 15 is also the list server fn's default page size (see list-view-state.ts)
+  // — the default must stay a selectable option so a fresh user with no stored
+  // preference sees the value the control claims.
+  const pageSizeItems = useMemo(
+    () => [
+      { value: '15', label: '15' },
+      { value: '30', label: '30' },
+      { value: '50', label: '50' },
+      { value: '100', label: '100' },
+    ],
+    []
+  )
+
   const handleOnSearch = (query: string): void => {
     if (query != null && query.length > 0) {
       const params = structuredClone(location.search)
@@ -309,6 +328,21 @@ export const ListView = ({
     })
   }
 
+  // Quietly persist sticky view keys as a per-user preference. Fire-and-
+  // forget: the navigation already happened, so a failed save must never
+  // toast, block, or roll anything back.
+  const persistListPreference = (value: {
+    page_size?: number
+    order?: string
+    desc?: boolean
+  }): void => {
+    setListViewPreference({
+      data: { collection: data.included.collection.path as string, value },
+    }).catch((err: unknown) => {
+      console.warn('list-view preference save failed:', err)
+    })
+  }
+
   function handleOnPageSizeChange(value: string | null): void {
     if (typeof value !== 'string' || value.length === 0) return
     const params = structuredClone(location.search)
@@ -319,6 +353,7 @@ export const ListView = ({
       params: { collection: data.included.collection.path },
       search: params,
     })
+    persistListPreference({ page_size: Number.parseInt(value, 10) })
   }
 
   return (
@@ -339,6 +374,7 @@ export const ListView = ({
               <Link
                 to={getAdminRoutePath('collections', '$collection', 'create')}
                 params={{ collection: data.included.collection.path }}
+                search={{ from: encodeListReturnState(location.search as Record<string, unknown>) }}
               />
             }
           >
@@ -460,6 +496,11 @@ export const ListView = ({
                                   collection: data.included.collection.path,
                                   id: document.id,
                                 }}
+                                search={{
+                                  from: encodeListReturnState(
+                                    location.search as Record<string, unknown>
+                                  ),
+                                }}
                               >
                                 {column.formatter
                                   ? renderFormatted(
@@ -509,6 +550,7 @@ export const ListView = ({
                         className={column.className}
                         activeOrder={activeOrder}
                         activeDesc={activeDesc}
+                        onSort={(order, desc) => persistListPreference({ order, desc })}
                       />
                     )
                   })}
@@ -536,6 +578,11 @@ export const ListView = ({
                                 collection: data.included.collection.path,
                                 id: document.id,
                               }}
+                              search={{
+                                from: encodeListReturnState(
+                                  location.search as Record<string, unknown>
+                                ),
+                              }}
                             >
                               {column.formatter
                                 ? renderFormatted(
@@ -583,13 +630,8 @@ export const ListView = ({
             id="page_size"
             name="page_size"
             size="sm"
-            defaultValue="15"
-            items={[
-              { value: '15', label: '15' },
-              { value: '30', label: '30' },
-              { value: '50', label: '50' },
-              { value: '100', label: '100' },
-            ]}
+            value={String(searchParams.page_size ?? data?.meta.pageSize ?? 15)}
+            items={pageSizeItems}
             onValueChange={handleOnPageSizeChange}
           />
           <RouterPager

package/src/routes/create-collection-create-route.tsx

@@ -15,14 +15,21 @@ import {
   getCollectionDefinition,
 } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
+import { z } from 'zod'
 
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { CreateView } from '../admin-shell/collections/create.js'
 import { getAdminRoutePath } from './admin-path.js'
 
+const searchSchema = z.object({
+  /** URL-encoded list search state to return to on cancel — see list-return-state.ts. */
+  from: z.string().optional(),
+})
+
 export function createCollectionCreateRoute(path: string) {
   // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
   const Route: any = createFileRoute(path as never)({
+    validateSearch: searchSchema,
     loader: async ({
       params,
     }: {
@@ -46,6 +53,7 @@ export function createCollectionCreateRoute(path: string) {
       const collectionDef = getCollectionDefinition(collection) as CollectionDefinition
       const adminConfig = getCollectionAdminConfig(collection)
       const { t } = useTranslation('byline-admin')
+      const search = Route.useSearch() as z.infer<typeof searchSchema>
       return (
         <>
           <BreadcrumbsClient
@@ -65,6 +73,7 @@ export function createCollectionCreateRoute(path: string) {
             collectionDefinition={collectionDef}
             adminConfig={adminConfig ?? undefined}
             initialData={initialData}
+            from={search.from}
           />
         </>
       )

package/src/routes/create-collection-edit-route.tsx

@@ -21,11 +21,14 @@ import { EditView } from '../admin-shell/collections/edit.js'
 import { getCollectionDocument } from '../server-fns/collections/index.js'
 import { getAdminRoutePath } from './admin-path.js'
 import { getContentLocaleRouteConfig } from './get-content-locale-route-config.js'
+import { decodeListReturnState } from './list-return-state.js'
 
 const searchSchema = z.object({
   locale: z.string().optional(),
   /** Set by the create view's create → edit redirect; fires the created toast. */
   action: z.enum(['created']).optional(),
+  /** URL-encoded list search state to return to on close — see list-return-state.ts. */
+  from: z.string().optional(),
 })
 
 export function createCollectionEditRoute(path: string) {
@@ -135,6 +138,7 @@ export function createCollectionEditRoute(path: string) {
             locale={locale}
             contentLocales={contentLocales}
             defaultContentLocale={defaultContentLocale}
+            returnSearch={decodeListReturnState(search.from)}
           />
         </>
       )

package/src/routes/create-collection-list-route.tsx

@@ -18,7 +18,7 @@ import {
 } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
 import { useToastManager } from '@byline/ui/react'
-import { z } from 'zod'
+import type { z } from 'zod'
 
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { useNavigate } from '../admin-shell/chrome/loose-router.js'
@@ -31,19 +31,9 @@ import {
   reorderCollectionDocument,
 } from '../server-fns/collections/index.js'
 import { getAdminRoutePath } from './admin-path.js'
+import { collectionListSearchSchema as searchSchema } from './list-return-state.js'
 import type { CollectionTreeRow } from '../server-fns/collections/tree.js'
 
-const searchSchema = z.object({
-  page: z.coerce.number().min(1).optional(),
-  page_size: z.coerce.number().max(100).optional(),
-  order: z.string().optional(),
-  desc: z.coerce.boolean().optional(),
-  query: z.string().optional(),
-  locale: z.string().optional(),
-  status: z.string().optional(),
-  action: z.enum(['created']).optional(),
-})
-
 export function createCollectionListRoute(path: string) {
   // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
   const Route: any = createFileRoute(path as never)({

package/src/routes/list-return-state.test.node.ts

@@ -0,0 +1,55 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { decodeListReturnState, encodeListReturnState } from './list-return-state.js'
+
+describe('encodeListReturnState / decodeListReturnState', () => {
+  it('round-trips a full list search state', () => {
+    const search = {
+      page: 7,
+      page_size: 50,
+      order: 'title',
+      desc: false,
+      query: 'harvest',
+      locale: 'fr',
+      status: 'draft',
+    }
+    const encoded = encodeListReturnState(search)
+    expect(typeof encoded).toBe('string')
+    expect(decodeListReturnState(encoded)).toEqual(search)
+  })
+
+  it('returns undefined for an empty search (no point carrying a bare target)', () => {
+    expect(encodeListReturnState({})).toBeUndefined()
+  })
+
+  it('never carries the transient action param', () => {
+    const encoded = encodeListReturnState({ page: 2, action: 'created' })
+    expect(decodeListReturnState(encoded)).toEqual({ page: 2 })
+  })
+
+  it('decodes desc=false as boolean false (not string-coerced truthiness)', () => {
+    const decoded = decodeListReturnState('order=title&desc=false')
+    expect(decoded).toEqual({ order: 'title', desc: false })
+  })
+
+  it('degrades malformed input to undefined instead of throwing', () => {
+    expect(decodeListReturnState(undefined)).toBeUndefined()
+    expect(decodeListReturnState('')).toBeUndefined()
+    expect(decodeListReturnState('page=notanumber')).toBeUndefined()
+    expect(decodeListReturnState('page=0')).toBeUndefined()
+    expect(decodeListReturnState('page_size=99999')).toBeUndefined()
+  })
+
+  it('drops empty-string values at encode time', () => {
+    const encoded = encodeListReturnState({ page: 3, query: '' })
+    expect(decodeListReturnState(encoded)).toEqual({ page: 3 })
+  })
+})