@byline/host-tanstack-start 4.5.0 → 4.6.0

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

@@ -0,0 +1,77 @@
+/**
+ * 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
+ */
+
+/**
+ * Return-to-list state for the collection editor (issue #17).
+ *
+ * The list route holds its complete view state in URL search params, so
+ * "come back to page 7 of the filtered list" needs no storage: the list
+ * encodes its current search into a single `from` param on the editor
+ * link, the editor threads it through its own navigations, and
+ * close/delete decode it back into list search params. Malformed or
+ * absent state degrades to the bare list — never an error.
+ *
+ * The list route's search schema lives here (rather than in the route
+ * factory) so the helpers and the factory share one definition without
+ * a circular import.
+ */
+
+import { z } from 'zod'
+
+export const collectionListSearchSchema = 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 type CollectionListSearch = z.infer<typeof collectionListSearchSchema>
+
+/**
+ * The keys a return target carries. `action` is transient (post-create
+ * toast trigger) and must never round-trip through a return target.
+ */
+const RETURN_KEYS = ['page', 'page_size', 'order', 'desc', 'query', 'locale', 'status'] as const
+
+/** `undefined` when there is nothing worth carrying (bare list). */
+export function encodeListReturnState(search: Record<string, unknown>): string | undefined {
+  const params = new URLSearchParams()
+  for (const key of RETURN_KEYS) {
+    const value = search[key]
+    if (value != null && value !== '') params.set(key, String(value))
+  }
+  const encoded = params.toString()
+  return encoded.length > 0 ? encoded : undefined
+}
+
+/**
+ * Parse a `from` param back into list search params. Runs the decoded
+ * pairs through the list search schema; anything malformed returns
+ * `undefined` (→ bare list). `desc` needs explicit normalisation
+ * because `z.coerce.boolean()` would coerce the string `'false'` to
+ * `true`.
+ */
+export function decodeListReturnState(
+  from: string | undefined
+): Record<string, unknown> | undefined {
+  if (from == null || from.length === 0) return undefined
+  const raw: Record<string, unknown> = Object.fromEntries(new URLSearchParams(from))
+  delete raw.action
+  if (typeof raw.desc === 'string') raw.desc = raw.desc === 'true'
+  const parsed = collectionListSearchSchema.safeParse(raw)
+  if (!parsed.success) return undefined
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(parsed.data)) {
+    if (value !== undefined) result[key] = value
+  }
+  return Object.keys(result).length > 0 ? result : undefined
+}

package/src/server-fns/collections/index.ts

@@ -18,6 +18,7 @@ export * from './list'
 export * from './reindex'
 export * from './reorder'
 export * from './restore-version'
+export * from './set-list-view-preference'
 export * from './stats'
 export * from './status'
 export * from './tree'

package/src/server-fns/collections/list-view-state.test.node.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 { resolveListViewState, sortableFieldNames } from './list-view-state.js'
+
+const base = {
+  params: {},
+  preference: null,
+  orderable: false,
+  sortableFields: ['title', 'summary', 'created_at', 'updated_at'],
+  configuredSort: undefined,
+}
+
+describe('resolveListViewState', () => {
+  it('defaults to page size 15 and no sort when nothing is set', () => {
+    expect(resolveListViewState({ ...base })).toEqual({ pageSize: 15 })
+  })
+
+  it('lets explicit URL params win over preference and configured sort', () => {
+    const result = resolveListViewState({
+      ...base,
+      params: { page_size: 15, order: 'title', desc: false },
+      preference: { page_size: 100, order: 'summary', desc: true },
+      configuredSort: { order: 'created_at', desc: true },
+    })
+    expect(result).toEqual({
+      pageSize: 15,
+      sort: { title: 'asc' },
+      metaOrder: 'title',
+      metaDesc: false,
+    })
+  })
+
+  it('preserves the pre-existing "omitted desc means descending" param semantics', () => {
+    const result = resolveListViewState({ ...base, params: { order: 'title' } })
+    expect(result.sort).toEqual({ title: 'desc' })
+    // meta passthrough stays exactly what the URL carried (undefined here).
+    expect(result.metaOrder).toBe('title')
+    expect(result.metaDesc).toBeUndefined()
+  })
+
+  it('applies the preference on a params-less landing', () => {
+    const result = resolveListViewState({
+      ...base,
+      preference: { page_size: 50, order: 'title', desc: true },
+    })
+    expect(result).toEqual({
+      pageSize: 50,
+      sort: { title: 'desc' },
+      metaOrder: 'title',
+      metaDesc: true,
+    })
+  })
+
+  it('skips a stale preference order and falls through to configuredSort', () => {
+    const result = resolveListViewState({
+      ...base,
+      preference: { order: 'removed_field', desc: true },
+      configuredSort: { order: 'created_at', desc: true },
+    })
+    expect(result.sort).toEqual({ created_at: 'desc' })
+    expect(result.metaOrder).toBe('created_at')
+  })
+
+  it('ignores an out-of-range or non-integer preference page_size', () => {
+    expect(resolveListViewState({ ...base, preference: { page_size: 0 } }).pageSize).toBe(15)
+    expect(resolveListViewState({ ...base, preference: { page_size: 999 } }).pageSize).toBe(15)
+    expect(resolveListViewState({ ...base, preference: { page_size: 12.5 } }).pageSize).toBe(15)
+  })
+
+  it('applies page_size but never sort preferences on orderable collections', () => {
+    const result = resolveListViewState({
+      ...base,
+      orderable: true,
+      preference: { page_size: 50, order: 'title', desc: true },
+    })
+    expect(result).toEqual({ pageSize: 50, sort: { order_key: 'asc' } })
+  })
+
+  it('still lets explicit params override the drag order on orderable collections', () => {
+    const result = resolveListViewState({
+      ...base,
+      orderable: true,
+      params: { order: 'title', desc: true },
+    })
+    expect(result.sort).toEqual({ title: 'desc' })
+  })
+
+  it('combines a page_size-only preference with configuredSort', () => {
+    const result = resolveListViewState({
+      ...base,
+      preference: { page_size: 30 },
+      configuredSort: { order: 'created_at', desc: true },
+    })
+    expect(result).toEqual({
+      pageSize: 30,
+      sort: { created_at: 'desc' },
+      metaOrder: 'created_at',
+      metaDesc: true,
+    })
+  })
+})
+
+describe('sortableFieldNames', () => {
+  it('keeps scalar-store fields plus system columns; drops structure, json, file, and relation fields', () => {
+    const fields = [
+      { name: 'title', type: 'text' },
+      { name: 'viewCount', type: 'integer' },
+      { name: 'publishedOn', type: 'datetime' },
+      { name: 'featured', type: 'checkbox' },
+      { name: 'content', type: 'blocks' },
+      { name: 'gallery', type: 'array' },
+      { name: 'body', type: 'richText' },
+      { name: 'featureImage', type: 'image' },
+      { name: 'category', type: 'relation' },
+      { name: 'meta', type: 'group' },
+    ]
+    expect(sortableFieldNames(fields)).toEqual([
+      'title',
+      'viewCount',
+      'publishedOn',
+      'featured',
+      'created_at',
+      'updated_at',
+    ])
+  })
+
+  it('returns only the system columns for a collection with no sortable fields', () => {
+    expect(sortableFieldNames([{ name: 'content', type: 'blocks' }])).toEqual([
+      'created_at',
+      'updated_at',
+    ])
+  })
+})

package/src/server-fns/collections/list-view-state.ts

@@ -0,0 +1,137 @@
+/**
+ * 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
+ */
+
+/**
+ * Pure precedence resolver for the collection list view's page size and
+ * sort — extracted from the list server fn so the chain is testable
+ * without a database:
+ *
+ *   URL params → user preference → configured defaultSort → storage
+ *   default (created_at desc, expressed as "no sort spec")
+ *
+ * `orderable: true` collections sort by the drag order (`order_key asc`)
+ * and never take sort preferences or a configured default — but explicit
+ * URL params still win (a shared sorted link opens as sent), and a
+ * page-size preference still applies.
+ *
+ * A preference `order` naming a field that is no longer sortable on the
+ * collection is skipped (not an error): the schema may have moved on
+ * since the preference was written.
+ */
+
+import { fieldTypeToStore } from '@byline/core'
+
+/**
+ * Store types whose value column supports ORDER BY. Structure fields
+ * (group/array/blocks) and json/file/relation fields are excluded — a
+ * preference naming one (hand-edited, or stale after a schema change)
+ * must be skipped rather than sent to the sort compiler.
+ */
+const SORTABLE_STORE_TYPES: ReadonlySet<string> = new Set([
+  'text',
+  'numeric',
+  'boolean',
+  'datetime',
+])
+
+/**
+ * The field names a stored sort preference may legitimately name: fields
+ * whose store type carries an orderable scalar column, plus the document
+ * system columns.
+ */
+export function sortableFieldNames(fields: Array<{ name: string; type: string }>): string[] {
+  return [
+    ...fields
+      .filter((f) => SORTABLE_STORE_TYPES.has(fieldTypeToStore[f.type]?.storeType ?? ''))
+      .map((f) => f.name),
+    'created_at',
+    'updated_at',
+  ]
+}
+
+export interface ListViewPreferenceValue {
+  page_size?: number
+  order?: string
+  desc?: boolean
+}
+
+export interface ResolveListViewStateInput {
+  params: { page_size?: number; order?: string; desc?: boolean }
+  preference: ListViewPreferenceValue | null
+  orderable: boolean
+  /** Field names valid as a sort column (collection fields + system columns). */
+  sortableFields: string[]
+  configuredSort?: { order: string; desc: boolean }
+}
+
+export interface ResolvedListViewState {
+  pageSize: number
+  /** Sort spec for `CollectionHandle.find`; undefined → storage default. */
+  sort?: Record<string, 'asc' | 'desc'>
+  /** Effective sort echoed through `meta.order` / `meta.desc` for the header indicator. */
+  metaOrder?: string
+  metaDesc?: boolean
+}
+
+export function resolveListViewState(input: ResolveListViewStateInput): ResolvedListViewState {
+  const { params, preference, orderable, sortableFields, configuredSort } = input
+
+  // Defensive clamp at read time — the write path validates 1–100, but a
+  // hand-edited row must degrade to the default, not a absurd page.
+  const rawPrefPageSize = preference?.page_size
+  const prefPageSize =
+    typeof rawPrefPageSize === 'number' &&
+    Number.isInteger(rawPrefPageSize) &&
+    rawPrefPageSize >= 1 &&
+    rawPrefPageSize <= 100
+      ? rawPrefPageSize
+      : undefined
+  const pageSize = params.page_size ?? prefPageSize ?? 15
+
+  // Explicit URL params always win. Semantics preserved from the original
+  // inline code: an omitted `desc` alongside an explicit `order` sorts
+  // descending, and the meta echo passes the raw param values through.
+  if (params.order) {
+    return {
+      pageSize,
+      sort: { [params.order]: params.desc === false ? 'asc' : 'desc' },
+      metaOrder: params.order,
+      metaDesc: params.desc,
+    }
+  }
+
+  if (orderable) {
+    return { pageSize, sort: { order_key: 'asc' } }
+  }
+
+  const rawPrefOrder = preference?.order
+  const prefOrder =
+    typeof rawPrefOrder === 'string' && sortableFields.includes(rawPrefOrder)
+      ? rawPrefOrder
+      : undefined
+  if (prefOrder != null) {
+    const desc = preference?.desc === true
+    return {
+      pageSize,
+      sort: { [prefOrder]: desc ? 'desc' : 'asc' },
+      metaOrder: prefOrder,
+      metaDesc: desc,
+    }
+  }
+
+  if (configuredSort != null) {
+    return {
+      pageSize,
+      sort: { [configuredSort.order]: configuredSort.desc ? 'desc' : 'asc' },
+      metaOrder: configuredSort.order,
+      metaDesc: configuredSort.desc,
+    }
+  }
+
+  return { pageSize }
+}

package/src/server-fns/collections/list.ts

@@ -8,7 +8,8 @@
 
 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 {
   buildRelationSummaryPopulateMap,
   ERR_NOT_FOUND,
@@ -22,7 +23,10 @@ import {
 } 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'
+import type { ListViewPreferenceValue } from './list-view-state.js'
 
 // ---------------------------------------------------------------------------
 // Shared param types
@@ -57,7 +61,6 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
 
     const client = getAdminBylineClient()
     const handle = client.collection(path)
-    const pageSize = params.page_size ?? 20
 
     // Routes through CollectionHandle.find so the read pipeline (beforeRead
     // → findDocuments → afterRead) is identical to any non-admin client.
@@ -69,30 +72,51 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
     if (params.status) where.status = params.status
     if (params.query) where.query = params.query
 
-    // Sort precedence: the caller's explicit `params.order` always wins (a
-    // shared link opens exactly as sent) → `orderable: true` collections
-    // default to the fractional `order_key` ascending → the admin config's
-    // `defaultSort` (boot-validated; mutually exclusive with `orderable`) →
-    // the storage fallback (`created_at desc`). `configuredSort` is also
-    // echoed through `meta.order`/`meta.desc` below so the list header can
-    // render the effective sort indicator on a params-less landing.
+    // Sort/page-size precedence (see list-view-state.ts): the caller's
+    // explicit params always win (a shared link opens exactly as sent) →
+    // the actor's stored per-collection preference → the admin config's
+    // `defaultSort` → the storage fallback (`created_at desc`). The
+    // effective sort is echoed through `meta.order`/`meta.desc` below so
+    // the list header renders the right indicator on a params-less landing.
     const adminConfig = getCollectionAdminConfig(path)
     const configuredSort =
-      !params.order && config.definition.orderable !== true && adminConfig?.defaultSort != null
+      config.definition.orderable !== true && adminConfig?.defaultSort != null
         ? {
             order: String(adminConfig.defaultSort.field),
             desc: adminConfig.defaultSort.direction === 'desc',
           }
         : undefined
-    const defaultSort: Record<string, 'asc' | 'desc'> | undefined =
-      config.definition.orderable === true
-        ? { order_key: 'asc' }
-        : configuredSort != null
-          ? { [configuredSort.order]: configuredSort.desc ? 'desc' : 'asc' }
-          : undefined
-    const sortSpec: Record<string, 'asc' | 'desc'> | undefined = params.order
-      ? { [params.order]: params.desc === false ? 'asc' : 'desc' }
-      : defaultSort
+
+    // Per-user preference — read only when it could matter (some param
+    // absent). Failures (headless context, unauthenticated preview, DB
+    // hiccup) log and fall through: preferences can never break the list.
+    let preference: ListViewPreferenceValue | null = null
+    const adminStore = bylineCore().adminStore
+    if (adminStore != null && (params.page_size == null || params.order == null)) {
+      try {
+        const context = await getAdminRequestContext()
+        const res = await getPreferenceCommand(
+          context,
+          { scope: `collections.${path}.list` },
+          { store: adminStore }
+        )
+        preference = (res.value as ListViewPreferenceValue | null) ?? 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: config.definition.orderable === true,
+      sortableFields: sortableFieldNames(config.definition.fields),
+      configuredSort,
+    })
+    const pageSize = viewState.pageSize
 
     // Auto-populate relation columns (depth 1) so the list renders each
     // target's title (via `relationColumnFormatter`) rather than a raw
@@ -109,7 +133,7 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
 
     const result = await handle.find({
       where: Object.keys(where).length > 0 ? where : undefined,
-      sort: sortSpec,
+      sort: viewState.sort,
       locale: params.locale ?? 'en',
       page: params.page,
       pageSize,
@@ -147,12 +171,13 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
       docs,
       meta: {
         ...result.meta,
-        // The *effective* sort: explicit params, or the configured
-        // `defaultSort` when it filled in. The list header renders its
-        // sort indicator from this, so a params-less landing still shows
-        // which column ordered the rows.
-        order: params.order ?? configuredSort?.order,
-        desc: params.desc ?? configuredSort?.desc,
+        // The *effective* sort/page-size: explicit params, or the
+        // resolved preference/configured `defaultSort` when they filled
+        // in. The list header renders its sort indicator from this, so a
+        // params-less landing still shows which column ordered the rows.
+        order: viewState.metaOrder,
+        desc: viewState.metaDesc,
+        pageSize,
       },
       included: {
         collection: {

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

@@ -0,0 +1,67 @@
+/**
+ * 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
+ */
+
+/**
+ * Persist a per-user list-view preference for one collection.
+ *
+ * Fire-and-forget from the list UI: changing page size or clicking a
+ * column sort quietly upserts the sticky keys for
+ * `collections.<path>.list`. The client sends only the keys the
+ * interaction changed; the repository merges per key, so a page-size
+ * change never wipes a stored sort.
+ *
+ * Self-service: the target user is always the authenticated actor.
+ * `setPreferenceCommand` rejects unauthenticated contexts.
+ */
+
+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'
+
+export interface SetListViewPreferenceInput {
+  collection: string
+  value: {
+    page_size?: number
+    order?: string
+    desc?: boolean
+  }
+}
+
+export const setListViewPreference = createServerFn({ method: 'POST' })
+  .validator((input: SetListViewPreferenceInput) => input)
+  .handler(async ({ data }) => {
+    // Scopes are keyed by collection path — refuse to mint rows for
+    // collections that don't exist, so a scripted caller cannot persist
+    // junk scopes (even self-scoped ones).
+    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 (adminStore == null) {
+      // Headless hosts without an admin store have no preference storage —
+      // the save is a silent no-op, mirroring set-locale's posture.
+      return { ok: true as const }
+    }
+    const context = await getAdminRequestContext()
+    await setPreferenceCommand(
+      context,
+      { scope: `collections.${data.collection}.list`, value: data.value },
+      { store: adminStore }
+    )
+    return { ok: true as const }
+  })