@byline/host-tanstack-start 6.0.1 → 6.0.3

package/dist/admin-shell/chrome/th-sortable.js

@@ -3,6 +3,7 @@ import { useEffect, useState } from "react";
 import { useRouterState } from "@tanstack/react-router";
 import { Table } from "@byline/ui/react";
 import clsx from "clsx";
+import { searchBooleanSchema } from "../../routes/search-boolean.js";
 import { useNavigate } from "./loose-router.js";
 import { SortAscendingIcon, SortDescendingIcon, SortNeutralIcon } from "./sort-icons.js";
 import th_sortable_module from "./th-sortable.module.js";
@@ -30,7 +31,7 @@ function TableHeadingCellSortable({ path: _path = '/', fieldName, label, sortabl
         if (null != fieldName) {
             const order = void 0 !== activeOrder ? activeOrder : location.search.order;
             const d = void 0 !== activeOrder ? activeDesc : location.search.desc;
-            order === fieldName ? setDesc(d ?? false) : setDesc(null);
+            order === fieldName ? setDesc(searchBooleanSchema.safeParse(d).data ?? true) : setDesc(null);
         }
     }, [
         fieldName,

package/dist/admin-shell/chrome/th-sortable.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/admin-shell/collections/list.js

@@ -11,6 +11,7 @@ import { SortableContext, sortableKeyboardCoordinates, useSortable, verticalList
 import clsx from "clsx";
 import { getAdminRoutePath } from "../../routes/admin-path.js";
 import { encodeListReturnState } from "../../routes/list-return-state.js";
+import { searchBooleanSchema } from "../../routes/search-boolean.js";
 import { setListViewPreference } from "../../server-fns/collections/index.js";
 import { Link, useNavigate } from "../chrome/loose-router.js";
 import { RouterPager } from "../chrome/router-pager.js";
@@ -94,10 +95,11 @@ const ListView = ({ data, columns, workflowStatuses, useAsTitle, orderable = fal
         mutation.blocked
     ]);
     const searchParams = location.search;
-    const isCanonicalView = !searchParams.order && !searchParams.desc && !searchParams.query && !searchParams.status;
+    const searchDesc = searchBooleanSchema.safeParse(searchParams.desc).data;
+    const isCanonicalView = !searchParams.order && !searchDesc && !searchParams.query && !searchParams.status;
     const dragEnabled = orderable && isCanonicalView && !!onReorder && !mutation.blocked;
     const activeOrder = searchParams.order ?? data?.meta.order;
-    const activeDesc = null != searchParams.order ? searchParams.desc : data?.meta.desc;
+    const activeDesc = null != searchParams.order ? searchDesc : data?.meta.desc;
     const sensors = useSensors(useSensor(PointerSensor, {
         activationConstraint: {
             distance: 5

package/dist/routes/create-admin-analytics-route.js

@@ -6,7 +6,7 @@ import { useTranslation } from "@byline/i18n/react";
 import { z } from "zod";
 import { BreadcrumbsClient } from "../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js";
 import { useNavigate } from "../admin-shell/chrome/loose-router.js";
-import { getAnalyticsCountries, getAnalyticsReferrers, getAnalyticsReportCoverage, getAnalyticsRuntime, getAnalyticsSummary, getAnalyticsTop } from "../server-fns/analytics/index.js";
+import { getAnalyticsCountries, getAnalyticsDashboardPreference, getAnalyticsReferrers, getAnalyticsReportCoverage, getAnalyticsRuntime, getAnalyticsSummary, getAnalyticsTop, setAnalyticsDashboardPreference } from "../server-fns/analytics/index.js";
 import { getAdminRoutePath } from "./admin-path.js";
 import { buildAnalyticsDashboardRange } from "./analytics-range.js";
 const periodSchema = z.preprocess((value)=>{
@@ -21,13 +21,19 @@ function createAdminAnalyticsRoute(path) {
     const Route = createFileRoute(path)({
         validateSearch: searchSchema,
         loaderDeps: ({ search })=>({
-                period: search.period ?? 30
+                period: search.period
             }),
         loader: async ({ deps })=>{
             const runtime = await getAnalyticsRuntime();
             if (!runtime.enabled) throw notFound();
-            const coverage = await getAnalyticsReportCoverage();
-            const range = buildAnalyticsDashboardRange(deps.period, new Date(), coverage.summaryFrom);
+            const [coverage, preference] = await Promise.all([
+                getAnalyticsReportCoverage(),
+                null == deps.period ? getAnalyticsDashboardPreference() : Promise.resolve({
+                    period: null
+                })
+            ]);
+            const period = deps.period ?? preference.period ?? 30;
+            const range = buildAnalyticsDashboardRange(period, new Date(), coverage.summaryFrom);
             const [summary, pages, downloads, referrers, countries] = await Promise.all([
                 getAnalyticsSummary({
                     data: range
@@ -66,7 +72,7 @@ function createAdminAnalyticsRoute(path) {
                     range,
                     coverage
                 },
-                period: deps.period
+                period
             };
         },
         component: function() {
@@ -109,6 +115,13 @@ function createAdminAnalyticsRoute(path) {
                                     period: nextPeriod
                                 }
                             });
+                            setAnalyticsDashboardPreference({
+                                data: {
+                                    period: nextPeriod
+                                }
+                            }).catch((err)=>{
+                                console.warn('analytics dashboard preference save failed:', err);
+                            });
                         }
                     })
                 ]

package/dist/routes/create-admin-users-list-route.js

@@ -6,6 +6,7 @@ import { AdminUsersListView } from "../admin-shell/admin-users/list.js";
 import { BreadcrumbsClient } from "../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js";
 import { listAdminUsers } from "../server-fns/admin-users/index.js";
 import { getAdminRoutePath } from "./admin-path.js";
+import { searchBooleanSchema } from "./search-boolean.js";
 const orderSchema = z["enum"]([
     'given_name',
     'family_name',
@@ -19,7 +20,7 @@ const searchSchema = z.object({
     page_size: z.coerce.number().int().min(1).max(100).optional(),
     query: z.string().optional(),
     order: orderSchema.optional(),
-    desc: z.coerce.boolean().optional()
+    desc: searchBooleanSchema
 });
 function createAdminUsersListRoute(path) {
     const Route = createFileRoute(path)({

package/dist/routes/create-collection-history-route.js

@@ -9,11 +9,12 @@ import { getCollectionDocument, getCollectionDocumentAuditLog, getCollectionDocu
 import { getAdminRoutePath } from "./admin-path.js";
 import { getContentLocaleRouteConfig } from "./get-content-locale-route-config.js";
 import { getMultiCollectionDefinition } from "./get-multi-collection-definition.js";
+import { searchBooleanSchema } from "./search-boolean.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(),
+    desc: searchBooleanSchema,
     locale: z.string().optional(),
     tab: z["enum"]([
         'versions',

package/dist/routes/create-singleton-history-route.js

@@ -9,11 +9,12 @@ import { getSingleton, getSingletonHistory } from "../server-fns/singletons/inde
 import { getAdminRoutePath } from "./admin-path.js";
 import { getContentLocaleRouteConfig } from "./get-content-locale-route-config.js";
 import { getSingletonDefinition } from "./get-singleton-definition.js";
+import { searchBooleanSchema } from "./search-boolean.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(),
+    desc: searchBooleanSchema,
     locale: z.string().optional()
 });
 function createSingletonHistoryRoute(path) {

package/dist/routes/list-return-state.d.ts

@@ -24,7 +24,7 @@ export declare const collectionListSearchSchema: z.ZodObject<{
     page: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
     page_size: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
     order: z.ZodOptional<z.ZodString>;
-    desc: z.ZodOptional<z.ZodCoercedBoolean<unknown>>;
+    desc: z.ZodPreprocess<z.ZodOptional<z.ZodBoolean>, unknown>;
     query: z.ZodOptional<z.ZodString>;
     locale: z.ZodOptional<z.ZodString>;
     status: z.ZodOptional<z.ZodString>;
@@ -38,8 +38,7 @@ export declare function encodeListReturnState(search: Record<string, unknown>):
 /**
  * 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`.
+ * `undefined` (→ bare list). The schema accepts both boolean and wire-string
+ * directions, including `'false'` for ascending.
  */
 export declare function decodeListReturnState(from: string | undefined): Record<string, unknown> | undefined;

package/dist/routes/list-return-state.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
+import { searchBooleanSchema } from "./search-boolean.js";
 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(),
+    desc: searchBooleanSchema,
     query: z.string().optional(),
     locale: z.string().optional(),
     status: z.string().optional(),
@@ -33,7 +34,6 @@ function decodeListReturnState(from) {
     if (null == from || 0 === from.length) return;
     const raw = Object.fromEntries(new URLSearchParams(from));
     delete raw.action;
-    if ('string' == typeof raw.desc) raw.desc = 'true' === raw.desc;
     const parsed = collectionListSearchSchema.safeParse(raw);
     if (!parsed.success) return;
     const result = {};

package/dist/routes/search-boolean.d.ts

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export declare const searchBooleanSchema: z.ZodPreprocess<z.ZodOptional<z.ZodBoolean>, unknown>;

package/dist/routes/search-boolean.js

@@ -0,0 +1,3 @@
+import { z } from "zod";
+const searchBooleanSchema = z.preprocess((value)=>'true' === value ? true : 'false' === value ? false : value, z.boolean().optional());
+export { searchBooleanSchema };

package/dist/server-fns/analytics/index.d.ts

@@ -6,4 +6,5 @@
  * Copyright (c) Infonomic Company Limited
  */
 export { type DeleteAnalyticsEventsInput, deleteAnalyticsEvents, rebuildAnalyticsDay, } from './maintenance.js';
+export { getAnalyticsDashboardPreference, setAnalyticsDashboardPreference, } from './preferences.js';
 export { type AnalyticsRuntimeState, type AnalyticsTopInput, getAnalyticsCountries, getAnalyticsReferrers, getAnalyticsReportCoverage, getAnalyticsRuntime, getAnalyticsSummary, getAnalyticsTop, } from './queries.js';

package/dist/server-fns/analytics/index.js

@@ -1,2 +1,3 @@
 export { deleteAnalyticsEvents, rebuildAnalyticsDay } from "./maintenance.js";
+export { getAnalyticsDashboardPreference, setAnalyticsDashboardPreference } from "./preferences.js";
 export { getAnalyticsCountries, getAnalyticsReferrers, getAnalyticsReportCoverage, getAnalyticsRuntime, getAnalyticsSummary, getAnalyticsTop } from "./queries.js";

package/dist/server-fns/analytics/preferences.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 type { AnalyticsDashboardPeriod } from '@byline/admin/analytics';
+export interface SetAnalyticsDashboardPreferenceInput {
+    period: AnalyticsDashboardPeriod;
+}
+/**
+ * The stored period, or `null` when the user has never chosen one (or
+ * this host has no admin store).
+ *
+ * Never throws: a preference read must not be able to take the
+ * dashboard down. A headless context, an unauthenticated preview, or a
+ * database hiccup logs and yields `null`, and the caller falls back to
+ * the built-in default — the same posture the collection list's
+ * preference read takes.
+ */
+export declare const getAnalyticsDashboardPreference: import("@tanstack/react-start").OptionalFetcher<readonly [import("@tanstack/react-start").FunctionMiddlewareAfterServer<{}, unknown, undefined, undefined, {
+    bylineExpectedSessionId: string | null;
+}, undefined, undefined>], undefined, Promise<{
+    period: AnalyticsDashboardPeriod | null;
+}>>;
+/**
+ * Persist the chosen period. Fire-and-forget from the dashboard: the
+ * navigation has already happened, so a failed save must never toast,
+ * block, or roll anything back.
+ */
+export declare const setAnalyticsDashboardPreference: import("@tanstack/react-start").RequiredFetcher<readonly [import("@tanstack/react-start").FunctionMiddlewareAfterServer<{}, unknown, undefined, undefined, {
+    bylineExpectedSessionId: string | null;
+}, undefined, undefined>], (input: SetAnalyticsDashboardPreferenceInput) => SetAnalyticsDashboardPreferenceInput, Promise<{
+    ok: true;
+}>>;

package/dist/server-fns/analytics/preferences.js

@@ -0,0 +1,60 @@
+import { createServerFn } from "@tanstack/react-start";
+import { getPreferenceCommand, setPreferenceCommand } from "@byline/admin/admin-preferences";
+import { isAnalyticsDashboardPeriod } from "@byline/analytics/config";
+import { getAdminRequestContext } from "@byline/client/server";
+import { getLogger } from "@byline/core";
+import { bylineCore } from "../../integrations/byline-core.js";
+import { adminSessionMiddleware } from "../../integrations/session-middleware.js";
+const ANALYTICS_DASHBOARD_SCOPE = 'analytics.dashboard';
+const getAnalyticsDashboardPreference = createServerFn({
+    method: 'GET'
+}).middleware([
+    adminSessionMiddleware
+]).handler(async ()=>{
+    const adminStore = bylineCore().adminStore;
+    if (null == adminStore) return {
+        period: null
+    };
+    try {
+        const context = await getAdminRequestContext();
+        const result = await getPreferenceCommand(context, {
+            scope: ANALYTICS_DASHBOARD_SCOPE
+        }, {
+            store: adminStore
+        });
+        const period = result.value?.period;
+        return {
+            period: isAnalyticsDashboardPeriod(period) ? period : null
+        };
+    } catch (err) {
+        getLogger().warn({
+            err
+        }, 'analytics dashboard preference read failed — using default');
+        return {
+            period: null
+        };
+    }
+});
+const setAnalyticsDashboardPreference = createServerFn({
+    method: 'POST'
+}).middleware([
+    adminSessionMiddleware
+]).validator((input)=>input).handler(async ({ data })=>{
+    const adminStore = bylineCore().adminStore;
+    if (null == adminStore) return {
+        ok: true
+    };
+    const context = await getAdminRequestContext();
+    await setPreferenceCommand(context, {
+        scope: ANALYTICS_DASHBOARD_SCOPE,
+        value: {
+            period: data.period
+        }
+    }, {
+        store: adminStore
+    });
+    return {
+        ok: true
+    };
+});
+export { getAnalyticsDashboardPreference, setAnalyticsDashboardPreference };

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "6.0.1",
+  "version": "6.0.3",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -125,15 +125,15 @@
     "react-json-view-lite": "^2.5.0",
     "react-swipeable": "^7.0.2",
     "zod": "^4.6.2",
-    "@byline/analytics-agent": "6.0.1",
-    "@byline/admin": "6.0.1",
-    "@byline/auth": "6.0.1",
-    "@byline/analytics": "6.0.1",
-    "@byline/ai": "6.0.1",
-    "@byline/client": "6.0.1",
-    "@byline/core": "6.0.1",
-    "@byline/ui": "6.0.1",
-    "@byline/i18n": "6.0.1"
+    "@byline/admin": "6.0.3",
+    "@byline/ai": "6.0.3",
+    "@byline/auth": "6.0.3",
+    "@byline/client": "6.0.3",
+    "@byline/analytics-agent": "6.0.3",
+    "@byline/i18n": "6.0.3",
+    "@byline/analytics": "6.0.3",
+    "@byline/core": "6.0.3",
+    "@byline/ui": "6.0.3"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.167.0",

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

@@ -0,0 +1,142 @@
+import { act, type ComponentProps } from 'react'
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+  RouterProvider,
+  useRouterState,
+} from '@tanstack/react-router'
+
+import { createRoot } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { collectionListSearchSchema } from '../../routes/list-return-state.js'
+import { resolveListViewState } from '../../server-fns/collections/list-view-state.js'
+import { TableHeadingCellSortable } from './th-sortable.js'
+
+vi.mock('@byline/ui/react', () => ({
+  Table: {
+    HeadingCell: (props: ComponentProps<'th'>) => <th {...props} />,
+  },
+}))
+
+// FORRU preserves wire values as strings and repeated keys as arrays for its
+// public library URLs. Admin routes share that router and must parse booleans.
+function parseWireSearch(search: string): Record<string, unknown> {
+  const params = new URLSearchParams(search)
+  return Object.fromEntries(
+    [...new Set(params.keys())].map((key) => {
+      const values = params.getAll(key)
+      return [key, values.length === 1 ? values[0] : values]
+    })
+  )
+}
+
+function stringifyWireSearch(search: Record<string, unknown>): string {
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(search)) {
+    if (value == null) continue
+    for (const entry of Array.isArray(value) ? value : [value]) {
+      params.append(key, String(entry))
+    }
+  }
+  return params.size ? `?${params}` : ''
+}
+
+beforeEach(() => {
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  vi.spyOn(window, 'scrollTo').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
+describe.each(['default', 'wire'] as const)('%s search parser', (parser) => {
+  it.each([true, false])(
+    'toggles sort requests and indicators with effective metadata: %s',
+    async (effective) => {
+      const rootRoute = createRootRoute()
+      const route = createRoute({
+        getParentRoute: () => rootRoute,
+        path: '/admin/collections/news',
+        validateSearch: collectionListSearchSchema,
+        loaderDeps: ({ search }) => search,
+        loader: ({ deps }) =>
+          resolveListViewState({
+            params: deps,
+            preference: null,
+            orderable: false,
+            sortableFields: ['title'],
+          }),
+        component: () => {
+          const data = route.useLoaderData()
+          // Match ListView: location.search is the host parser's raw output,
+          // unlike route.useSearch(), which has already passed validation.
+          const location = useRouterState({ select: (s) => s.location })
+          const search = location.search as { order?: string; desc?: boolean }
+          return (
+            <table>
+              <thead>
+                <tr>
+                  <TableHeadingCellSortable
+                    fieldName="title"
+                    label="Title"
+                    sortable
+                    {...(effective
+                      ? {
+                          activeOrder: search.order ?? data.metaOrder,
+                          activeDesc: search.order != null ? search.desc : data.metaDesc,
+                        }
+                      : {})}
+                  />
+                </tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td>{JSON.stringify(data.sort)}</td>
+                </tr>
+              </tbody>
+            </table>
+          )
+        },
+      })
+      const router = createRouter({
+        routeTree: rootRoute.addChildren([route]),
+        history: createMemoryHistory({
+          initialEntries: ['/admin/collections/news?order=title&desc=true'],
+        }),
+        ...(parser === 'wire'
+          ? { parseSearch: parseWireSearch, stringifySearch: stringifyWireSearch }
+          : {}),
+      })
+      const container = document.createElement('div')
+      document.body.append(container)
+      const root = createRoot(container)
+      try {
+        await act(async () => {
+          await router.load()
+          root.render(<RouterProvider router={router} />)
+        })
+        expect(container.querySelector('button')?.textContent).toBe('TitleZA')
+        for (const direction of ['asc', 'desc', 'asc']) {
+          await act(async () => {
+            container.querySelector('button')?.click()
+            await vi.waitFor(() => expect(router.state.status).toBe('idle'))
+          })
+          expect(container.querySelector('td')?.textContent).toBe(
+            JSON.stringify({ title: direction })
+          )
+          expect(container.querySelector('button')?.textContent).toBe(
+            direction === 'asc' ? 'TitleAZ' : 'TitleZA'
+          )
+        }
+      } finally {
+        await act(async () => root.unmount())
+        container.remove()
+      }
+    }
+  )
+})

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

@@ -13,6 +13,7 @@ import { useRouterState } from '@tanstack/react-router'
 import { Table } from '@byline/ui/react'
 import cx from 'clsx'
 
+import { searchBooleanSchema } from '../../routes/search-boolean.js'
 import { useNavigate } from './loose-router.js'
 import { SortAscendingIcon, SortDescendingIcon, SortNeutralIcon } from './sort-icons.js'
 import styles from './th-sortable.module.css'
@@ -91,7 +92,9 @@ export function TableHeadingCellSortable({
           ? activeDesc
           : ((location.search as Record<string, unknown>).desc as boolean | undefined)
       if (order === fieldName) {
-        setDesc(d ?? false)
+        // location.search can contain wire strings with a custom host parser.
+        // The route validator normalizes loader deps, not this raw location.
+        setDesc(searchBooleanSchema.safeParse(d).data ?? true)
       } else {
         setDesc(null)
       }

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

@@ -47,6 +47,7 @@ import cx from 'clsx'
 
 import { getAdminRoutePath } from '../../routes/admin-path.js'
 import { encodeListReturnState } from '../../routes/list-return-state.js'
+import { searchBooleanSchema } from '../../routes/search-boolean.js'
 import { setListViewPreference } from '../../server-fns/collections/index.js'
 import { Link, useNavigate } from '../chrome/loose-router.js'
 import { RouterPager } from '../chrome/router-pager.js'
@@ -206,12 +207,13 @@ export const ListView = ({
   const searchParams = location.search as {
     page_size?: number
     order?: string
-    desc?: boolean
+    desc?: boolean | string
     query?: string
     status?: string
   }
+  const searchDesc = searchBooleanSchema.safeParse(searchParams.desc).data
   const isCanonicalView =
-    !searchParams.order && !searchParams.desc && !searchParams.query && !searchParams.status
+    !searchParams.order && !searchDesc && !searchParams.query && !searchParams.status
   const dragEnabled = orderable && isCanonicalView && !!onReorder && !mutation.blocked
 
   // The *effective* sort for the header indicators: explicit URL params win;
@@ -220,7 +222,7 @@ export const ListView = ({
   // which column ordered the rows. (Orderable collections never set
   // `meta.order` — their default is the drag order, indicated separately.)
   const activeOrder = searchParams.order ?? data?.meta.order
-  const activeDesc = searchParams.order != null ? searchParams.desc : data?.meta.desc
+  const activeDesc = searchParams.order != null ? searchDesc : data?.meta.desc
 
   const sensors = useSensors(
     useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),

package/src/routes/create-admin-analytics-route.tsx

@@ -21,11 +21,13 @@ import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs
 import { useNavigate } from '../admin-shell/chrome/loose-router.js'
 import {
   getAnalyticsCountries,
+  getAnalyticsDashboardPreference,
   getAnalyticsReferrers,
   getAnalyticsReportCoverage,
   getAnalyticsRuntime,
   getAnalyticsSummary,
   getAnalyticsTop,
+  setAnalyticsDashboardPreference,
 } from '../server-fns/analytics/index.js'
 import { getAdminRoutePath } from './admin-path.js'
 import { buildAnalyticsDashboardRange } from './analytics-range.js'
@@ -47,15 +49,29 @@ interface AnalyticsSearch {
 export function createAdminAnalyticsRoute(path: string) {
   const Route: any = createFileRoute(path as never)({
     validateSearch: searchSchema,
+    // `period` stays possibly-undefined here rather than defaulting to 30:
+    // "no period in the URL" is a distinct state from "30 in the URL", and
+    // only the former defers to the user's stored preference. It is still a
+    // loader dep, so an explicit period change refetches.
     loaderDeps: ({ search }: { search: AnalyticsSearch }) => ({
-      period: search.period ?? 30,
+      period: search.period,
     }),
-    loader: async ({ deps }: { deps: { period: AnalyticsDashboardPeriod } }) => {
+    loader: async ({ deps }: { deps: { period?: AnalyticsDashboardPeriod } }) => {
       const runtime = await getAnalyticsRuntime()
       if (!runtime.enabled) throw notFound()
 
-      const coverage = await getAnalyticsReportCoverage()
-      const range = buildAnalyticsDashboardRange(deps.period, new Date(), coverage.summaryFrom)
+      // Both are roundtrips the dashboard has to make before it can build a
+      // range, so the preference read rides along in parallel and costs no
+      // added latency. It is skipped entirely when the URL already decides.
+      const [coverage, preference] = await Promise.all([
+        getAnalyticsReportCoverage(),
+        deps.period == null ? getAnalyticsDashboardPreference() : Promise.resolve({ period: null }),
+      ])
+
+      // Precedence, matching the collection list: explicit URL param →
+      // stored per-user preference → the built-in default.
+      const period: AnalyticsDashboardPeriod = deps.period ?? preference.period ?? 30
+      const range = buildAnalyticsDashboardRange(period, new Date(), coverage.summaryFrom)
       const [summary, pages, downloads, referrers, countries] = await Promise.all([
         getAnalyticsSummary({ data: range }),
         // Fetch exactly the preview depth each card shows; the full list is
@@ -76,7 +92,9 @@ export function createAdminAnalyticsRoute(path: string) {
           range,
           coverage,
         } satisfies AnalyticsDashboardData,
-        period: deps.period,
+        // The *effective* period, so a params-less landing still highlights
+        // the period that actually ordered the data.
+        period,
       }
     },
     component: function AdminAnalyticsComponent() {
@@ -116,6 +134,14 @@ export function createAdminAnalyticsRoute(path: string) {
                 to: getAdminRoutePath('analytics'),
                 search: { period: nextPeriod },
               })
+              // Quietly make the choice sticky for next session. Fire-and-
+              // forget: the navigation already happened, so a failed save
+              // must never toast, block, or roll anything back.
+              setAnalyticsDashboardPreference({ data: { period: nextPeriod } }).catch(
+                (err: unknown) => {
+                  console.warn('analytics dashboard preference save failed:', err)
+                }
+              )
             }}
           />
         </>

package/src/routes/create-admin-users-list-route.tsx

@@ -15,6 +15,7 @@ import { AdminUsersListView } from '../admin-shell/admin-users/list.js'
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { type AdminUserListResponse, listAdminUsers } from '../server-fns/admin-users/index.js'
 import { getAdminRoutePath } from './admin-path.js'
+import { searchBooleanSchema } from './search-boolean.js'
 
 const orderSchema = z.enum([
   'given_name',
@@ -30,7 +31,7 @@ const searchSchema = z.object({
   page_size: z.coerce.number().int().min(1).max(100).optional(),
   query: z.string().optional(),
   order: orderSchema.optional(),
-  desc: z.coerce.boolean().optional(),
+  desc: searchBooleanSchema,
 })
 
 export function createAdminUsersListRoute(path: string) {

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

@@ -23,12 +23,13 @@ import {
 import { getAdminRoutePath } from './admin-path.js'
 import { getContentLocaleRouteConfig } from './get-content-locale-route-config.js'
 import { getMultiCollectionDefinition } from './get-multi-collection-definition.js'
+import { searchBooleanSchema } from './search-boolean.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(),
+  desc: searchBooleanSchema,
   locale: z.string().optional(),
   // Which sub-view of the history page is active (docs/07-auth-and-security/02-auditability.md — Workstream
   // 3). 'versions' is the content version stream; 'document' is the

package/src/routes/create-singleton-history-route.tsx

@@ -18,13 +18,14 @@ import { getSingleton, getSingletonHistory } from '../server-fns/singletons/inde
 import { getAdminRoutePath } from './admin-path.js'
 import { getContentLocaleRouteConfig } from './get-content-locale-route-config.js'
 import { getSingletonDefinition } from './get-singleton-definition.js'
+import { searchBooleanSchema } from './search-boolean.js'
 import type { VersionHistoryData } from '../admin-shell/collections/version-history.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(),
+  desc: searchBooleanSchema,
   locale: z.string().optional(),
 })
 

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

@@ -23,11 +23,13 @@
 
 import { z } from 'zod'
 
+import { searchBooleanSchema } from './search-boolean.js'
+
 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(),
+  desc: searchBooleanSchema,
   query: z.string().optional(),
   locale: z.string().optional(),
   status: z.string().optional(),
@@ -56,9 +58,8 @@ export function encodeListReturnState(search: Record<string, unknown>): string |
 /**
  * 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`.
+ * `undefined` (→ bare list). The schema accepts both boolean and wire-string
+ * directions, including `'false'` for ascending.
  */
 export function decodeListReturnState(
   from: string | undefined
@@ -66,7 +67,6 @@ export function decodeListReturnState(
   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> = {}

package/src/routes/search-boolean.test.node.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+
+import { resolveListViewState } from '../server-fns/collections/list-view-state.js'
+import { collectionListSearchSchema, decodeListReturnState } from './list-return-state.js'
+import { searchBooleanSchema } from './search-boolean.js'
+
+describe('search booleans', () => {
+  it.each([
+    [true, true],
+    [false, false],
+    ['true', true],
+    ['false', false],
+    [undefined, undefined],
+  ])('parses %s as %s', (input, expected) => {
+    expect(searchBooleanSchema.parse(input)).toBe(expected)
+  })
+
+  it.each(['invalid', '', ['false'], null, 0, 1])('rejects ambiguous input %s', (input) => {
+    expect(searchBooleanSchema.safeParse(input).success).toBe(false)
+  })
+
+  it.each(['true', 'false'])('carries desc=%s from wire params into the list query', (desc) => {
+    const params = collectionListSearchSchema.parse(
+      Object.fromEntries(new URLSearchParams(`order=title&desc=${desc}`))
+    )
+    const result = resolveListViewState({
+      params,
+      preference: null,
+      orderable: false,
+      sortableFields: ['title'],
+    })
+    expect(result.sort).toEqual({ title: desc === 'true' ? 'desc' : 'asc' })
+    expect(result.metaDesc).toBe(desc === 'true')
+  })
+
+  it('rejects a malformed return direction instead of silently changing it to ascending', () => {
+    expect(decodeListReturnState('order=title&desc=invalid')).toBeUndefined()
+  })
+})

package/src/routes/search-boolean.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+// Host routers may preserve URL values as strings. Boolean('false') is true,
+// so boolean coercion cannot be used for an explicit URL direction.
+export const searchBooleanSchema = z.preprocess(
+  (value) => (value === 'true' ? true : value === 'false' ? false : value),
+  z.boolean().optional()
+)

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

@@ -11,6 +11,10 @@ export {
   deleteAnalyticsEvents,
   rebuildAnalyticsDay,
 } from './maintenance.js'
+export {
+  getAnalyticsDashboardPreference,
+  setAnalyticsDashboardPreference,
+} from './preferences.js'
 export {
   type AnalyticsRuntimeState,
   type AnalyticsTopInput,

package/src/server-fns/analytics/preferences.ts

@@ -0,0 +1,99 @@
+/**
+ * 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
+ */
+
+/**
+ * Read and persist the signed-in admin user's sticky analytics
+ * dashboard period.
+ *
+ * The dashboard keeps its period in the URL (`?period=90`), so a shared
+ * link still opens exactly as sent; this preference only supplies the
+ * period when the URL carries none. Same precedence the collection list
+ * uses for page size and sort — explicit params win, the stored
+ * preference fills in, the built-in default is last.
+ *
+ * The scope is a singleton (`analytics.dashboard`), unlike the
+ * collection list's per-path scopes, so there is nothing to validate
+ * the way `set-list-view-preference` validates a collection path.
+ *
+ * Self-service: the target user is always the authenticated actor.
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+
+import { getPreferenceCommand, setPreferenceCommand } from '@byline/admin/admin-preferences'
+import type { AnalyticsDashboardPeriod } from '@byline/admin/analytics'
+import { isAnalyticsDashboardPeriod } from '@byline/analytics/config'
+import { getAdminRequestContext } from '@byline/client/server'
+import { getLogger } from '@byline/core'
+
+import { bylineCore } from '../../integrations/byline-core.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+
+const ANALYTICS_DASHBOARD_SCOPE = 'analytics.dashboard'
+
+export interface SetAnalyticsDashboardPreferenceInput {
+  period: AnalyticsDashboardPeriod
+}
+
+/**
+ * The stored period, or `null` when the user has never chosen one (or
+ * this host has no admin store).
+ *
+ * Never throws: a preference read must not be able to take the
+ * dashboard down. A headless context, an unauthenticated preview, or a
+ * database hiccup logs and yields `null`, and the caller falls back to
+ * the built-in default — the same posture the collection list's
+ * preference read takes.
+ */
+export const getAnalyticsDashboardPreference = createServerFn({ method: 'GET' })
+  .middleware([adminSessionMiddleware])
+  .handler(async (): Promise<{ period: AnalyticsDashboardPeriod | null }> => {
+    const adminStore = bylineCore().adminStore
+    if (adminStore == null) return { period: null }
+
+    try {
+      const context = await getAdminRequestContext()
+      const result = await getPreferenceCommand(
+        context,
+        { scope: ANALYTICS_DASHBOARD_SCOPE },
+        { store: adminStore }
+      )
+      const period = (result.value as { period?: unknown } | null)?.period
+      // Re-validated on the way out, not just on the way in: a row
+      // written before a period was retired from the dashboard must
+      // degrade to the default rather than reach `buildAnalyticsDashboardRange`.
+      return { period: isAnalyticsDashboardPeriod(period) ? period : null }
+    } catch (err) {
+      getLogger().warn({ err }, 'analytics dashboard preference read failed — using default')
+      return { period: null }
+    }
+  })
+
+/**
+ * Persist the chosen period. Fire-and-forget from the dashboard: the
+ * navigation has already happened, so a failed save must never toast,
+ * block, or roll anything back.
+ */
+export const setAnalyticsDashboardPreference = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .validator((input: SetAnalyticsDashboardPreferenceInput) => input)
+  .handler(async ({ data }) => {
+    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: ANALYTICS_DASHBOARD_SCOPE, value: { period: data.period } },
+      { store: adminStore }
+    )
+    return { ok: true as const }
+  })