@byline/host-tanstack-start 6.0.2 → 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-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/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "6.0.2",
+  "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/admin": "6.0.2",
-    "@byline/auth": "6.0.2",
-    "@byline/analytics": "6.0.2",
-    "@byline/analytics-agent": "6.0.2",
-    "@byline/client": "6.0.2",
-    "@byline/ai": "6.0.2",
-    "@byline/i18n": "6.0.2",
-    "@byline/core": "6.0.2",
-    "@byline/ui": "6.0.2"
+    "@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-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()
+)