@byline/host-tanstack-start 3.21.0 → 4.1.0

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

@@ -26,6 +26,7 @@ import {
 } from '@byline/ui/react'
 import cx from 'classnames'
 
+import { getAdminRouteId, getAdminRoutePath } from '../../routes/admin-path.js'
 import { Link, useNavigate } from '../chrome/loose-router.js'
 import { RouterPager } from '../chrome/router-pager.js'
 import { TableHeadingCellSortable } from '../chrome/th-sortable.js'
@@ -139,8 +140,8 @@ export const HistoryView = ({
   defaultContentLocale: string
 }) => {
   const { id, collection } = useParams({
-    from: '/_byline/admin/collections/$collection/$id/history',
-  })
+    from: getAdminRouteId('collections', '$collection', '$id', 'history') as never,
+  }) as { id: string; collection: string }
   const navigate = useNavigate()
   const { getCollectionDocumentVersion } = useBylineAdminServices()
   const { t } = useTranslation('byline-admin')
@@ -181,7 +182,7 @@ export const HistoryView = ({
       delete params.tab
     }
     navigate({
-      to: '/admin/collections/$collection/$id/history' as never,
+      to: getAdminRoutePath('collections', '$collection', '$id', 'history'),
       params: { collection, id } as never,
       search: params,
     })
@@ -193,7 +194,7 @@ export const HistoryView = ({
     delete params.page
     params.page_size = Number.parseInt(value, 10)
     navigate({
-      to: '/admin/collections/$collection/$id/history' as never,
+      to: getAdminRoutePath('collections', '$collection', '$id', 'history'),
       params: { collection, id } as never,
       search: params,
     })
@@ -382,7 +383,7 @@ export const HistoryView = ({
                                     </button>
                                   ) : (
                                     <Link
-                                      to={'/admin/collections/$collection/$id' as never}
+                                      to={getAdminRoutePath('collections', '$collection', '$id')}
                                       params={{
                                         collection,
                                         id: document.id,

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

@@ -43,6 +43,7 @@ import {
 } from '@dnd-kit/sortable'
 import cx from 'classnames'
 
+import { getAdminRoutePath } from '../../routes/admin-path.js'
 import { Link, useNavigate } from '../chrome/loose-router.js'
 import { RouterPager } from '../chrome/router-pager.js'
 import { SortAscendingIcon } from '../chrome/sort-icons.js'
@@ -274,7 +275,7 @@ export const ListView = ({
       delete params.page
       params.query = query
       navigate({
-        to: '/admin/collections/$collection' as never,
+        to: getAdminRoutePath('collections', '$collection'),
         params: { collection: data.included.collection.path },
         search: params,
       })
@@ -286,7 +287,7 @@ export const ListView = ({
     delete params.page
     delete params.query
     navigate({
-      to: '/admin/collections/$collection' as never,
+      to: getAdminRoutePath('collections', '$collection'),
       params: { collection: data.included.collection.path },
       search: params,
     })
@@ -302,7 +303,7 @@ export const ListView = ({
       params.status = value
     }
     navigate({
-      to: '/admin/collections/$collection' as never,
+      to: getAdminRoutePath('collections', '$collection'),
       params: { collection: data.included.collection.path },
       search: params,
     })
@@ -314,7 +315,7 @@ export const ListView = ({
     delete params.page
     params.page_size = Number.parseInt(value, 10)
     navigate({
-      to: '/admin/collections/$collection' as never,
+      to: getAdminRoutePath('collections', '$collection'),
       params: { collection: data.included.collection.path },
       search: params,
     })
@@ -336,7 +337,7 @@ export const ListView = ({
             aria-label={t('collections.list.createAriaLabel')}
             render={
               <Link
-                to={'/admin/collections/$collection/create' as never}
+                to={getAdminRoutePath('collections', '$collection', 'create')}
                 params={{ collection: data.included.collection.path }}
               />
             }
@@ -454,7 +455,7 @@ export const ListView = ({
                           >
                             {useAsTitle && column.fieldName === useAsTitle ? (
                               <Link
-                                to={'/admin/collections/$collection/$id' as never}
+                                to={getAdminRoutePath('collections', '$collection', '$id')}
                                 params={{
                                   collection: data.included.collection.path,
                                   id: document.id,
@@ -530,7 +531,7 @@ export const ListView = ({
                         >
                           {useAsTitle && column.fieldName === useAsTitle ? (
                             <Link
-                              to={'/admin/collections/$collection/$id' as never}
+                              to={getAdminRoutePath('collections', '$collection', '$id')}
                               params={{
                                 collection: data.included.collection.path,
                                 id: document.id,

package/src/admin-shell/collections/restore-version-modal.tsx

@@ -24,6 +24,7 @@ import { useTranslation } from '@byline/i18n/react'
 import { Alert, Button, LoaderEllipsis, Modal } from '@byline/ui/react'
 import cx from 'classnames'
 
+import { getAdminRoutePath } from '../../routes/admin-path.js'
 import { restoreDocumentVersion } from '../../server-fns/collections/index.js'
 import { useNavigate } from '../chrome/loose-router.js'
 import styles from './restore-version-modal.module.css'
@@ -62,7 +63,7 @@ export function RestoreVersionModal({
       onClose()
       await router.invalidate()
       navigate({
-        to: '/admin/collections/$collection/$id' as never,
+        to: getAdminRoutePath('collections', '$collection', '$id'),
         params: { collection, id: documentId },
       })
     } catch (err) {

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

@@ -7,7 +7,7 @@
  */
 
 import type React from 'react'
-import { useEffect, useMemo, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import { useRouter } from '@tanstack/react-router'
 
 import { renderFormatted, StatusBadge } from '@byline/admin/react'
@@ -41,6 +41,12 @@ import {
 } from '@dnd-kit/sortable'
 import cx from 'classnames'
 
+import { getAdminRoutePath } from '../../routes/admin-path.js'
+import {
+  createAdminTreeMoveController,
+  getAdminTreeMoveUiEffects,
+  shouldSyncAdminTreeRows,
+} from '../../server-fns/collections/tree-mutation.js'
 import { Link } from '../chrome/loose-router.js'
 import { TableHeadingCellSortable } from '../chrome/th-sortable.js'
 import { formatNumber } from '../chrome/utils.js'
@@ -59,7 +65,6 @@ export type TreeMoveFn = (params: {
   afterDocumentId: string | null
 }) => Promise<unknown>
 
-// biome-ignore lint/suspicious/noExplicitAny: tree rows carry heterogeneous fields
 function getColumnValue(row: CollectionTreeRow, fieldName: string): any {
   if (row.fields && fieldName in row.fields) return row.fields[fieldName]
   return (row as Record<string, any>)[fieldName]
@@ -73,19 +78,20 @@ function getColumnValue(row: CollectionTreeRow, fieldName: string): any {
  */
 function SortableTreeRow({
   id,
-  depth,
   dragging,
+  disabled,
   dragHandleLabel,
   children,
 }: {
   id: string
-  depth: number
   dragging: boolean
+  disabled: boolean
   dragHandleLabel: string
   children: React.ReactNode
 }) {
   const { setNodeRef, attributes, listeners, transform, transition, isDragging } = useSortable({
     id,
+    disabled,
   })
   const style: React.CSSProperties = {
     transform: transform ? `translate3d(0, ${transform.y}px, 0)` : undefined,
@@ -103,6 +109,7 @@ function SortableTreeRow({
       <td className={cx('byline-tree-list-drag-cell', styles.dragCell)}>
         <button
           type="button"
+          disabled={disabled}
           className={cx('byline-tree-list-drag-handle', styles.dragHandle)}
           aria-label={dragHandleLabel}
           {...attributes}
@@ -149,8 +156,12 @@ export const TreeListView = ({
   // back). Mirrors the flat-list reorder pattern.
   const [localPlaced, setLocalPlaced] = useState(() => rows.filter((r) => !r.unplaced))
   const [isMoving, setIsMoving] = useState(false)
+  const [moveController] = useState(() => createAdminTreeMoveController())
+  const preserveOptimisticForRows = useRef<CollectionTreeRow[] | null>(null)
   useEffect(() => {
-    if (!isMoving) setLocalPlaced(rows.filter((r) => !r.unplaced))
+    if (!shouldSyncAdminTreeRows(rows, preserveOptimisticForRows.current, isMoving)) return
+    preserveOptimisticForRows.current = null
+    setLocalPlaced(rows.filter((r) => !r.unplaced))
   }, [rows, isMoving])
 
   const [activeId, setActiveId] = useState<string | null>(null)
@@ -174,11 +185,17 @@ export const TreeListView = ({
     setOffsetLeft(0)
   }
 
-  const handleDragStart = ({ active }: DragStartEvent) => setActiveId(String(active.id))
+  const handleDragStart = ({ active }: DragStartEvent) => {
+    if (!moveController.isMoving()) setActiveId(String(active.id))
+  }
   const handleDragMove = ({ delta }: DragMoveEvent) => setOffsetLeft(delta.x)
   const handleDragOver = ({ over }: DragOverEvent) => setOverId(over ? String(over.id) : null)
 
   const handleDragEnd = async ({ active, over }: DragEndEvent) => {
+    if (moveController.isMoving()) {
+      resetDnd()
+      return
+    }
     const proj =
       over != null
         ? getTreeProjection(localPlaced, String(active.id), String(over.id), offsetLeft, INDENT)
@@ -197,24 +214,60 @@ export const TreeListView = ({
 
     setLocalPlaced(next)
     setIsMoving(true)
-    try {
-      await onMove({
-        documentId,
-        parentDocumentId: proj.parentId,
-        beforeDocumentId: proj.beforeId,
-        afterDocumentId: proj.afterId,
-      })
-      await router.invalidate()
-    } catch {
+    const outcome = await moveController.execute(
+      () =>
+        onMove({
+          documentId,
+          parentDocumentId: proj.parentId,
+          beforeDocumentId: proj.beforeId,
+          afterDocumentId: proj.afterId,
+        }),
+      () => router.invalidate()
+    )
+
+    if (outcome.status === 'suppressed') {
       setLocalPlaced(current)
+      setIsMoving(moveController.isMoving())
+      return
+    }
+
+    const effects = getAdminTreeMoveUiEffects(outcome)
+    if (effects.rollback) setLocalPlaced(current)
+
+    if (effects.structuralFailure != null) {
+      const conflict = effects.structuralFailure === 'conflict'
       toastManager.add({
-        title: t('collections.list.reorderFailedToast'),
-        description: t('collections.list.reorderFailedDescription'),
+        title: t(
+          conflict ? 'collections.list.treeConflictToast' : 'collections.list.reorderFailedToast'
+        ),
+        description: t(
+          conflict
+            ? 'collections.list.treeConflictDescription'
+            : 'collections.list.reorderFailedDescription'
+        ),
         data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
       })
-    } finally {
-      setIsMoving(false)
     }
+
+    if (effects.committedHookWarning) {
+      toastManager.add({
+        title: t('collections.list.treeHookFailedToast'),
+        description: t('collections.list.treeHookFailedDescription'),
+        data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+      })
+    }
+
+    if (effects.refreshWarning) {
+      toastManager.add({
+        title: t('collections.list.treeRefreshFailedToast'),
+        description: t('collections.list.treeRefreshFailedDescription'),
+        data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+      })
+    }
+
+    if (effects.preserveOptimistic) preserveOptimisticForRows.current = rows
+
+    setIsMoving(false)
   }
 
   const renderCells = (row: CollectionTreeRow, depth: number) =>
@@ -240,7 +293,7 @@ export const TreeListView = ({
                 </span>
               )}
               <Link
-                to={'/admin/collections/$collection/$id' as never}
+                to={getAdminRoutePath('collections', '$collection', '$id')}
                 params={{ collection, id: row.id }}
               >
                 {column.formatter
@@ -277,7 +330,10 @@ export const TreeListView = ({
           <IconButton
             aria-label={t('collections.list.createAriaLabel')}
             render={
-              <Link to={'/admin/collections/$collection/create' as never} params={{ collection }} />
+              <Link
+                to={getAdminRoutePath('collections', '$collection', 'create')}
+                params={{ collection }}
+              />
             }
           >
             <PlusIcon height="18px" width="18px" svgClassName="stroke-white" />
@@ -323,8 +379,8 @@ export const TreeListView = ({
                       <SortableTreeRow
                         key={row.id}
                         id={row.id}
-                        depth={depth}
                         dragging={row.id === activeId}
+                        disabled={isMoving}
                         dragHandleLabel={t('collections.list.dragHandleAriaLabel')}
                       >
                         {renderCells(row, depth)}

package/src/admin-shell/collections/view-menu.tsx

@@ -13,6 +13,7 @@ import { useTranslation } from '@byline/i18n/react'
 import { Button, HistoryIcon, IconButton, Label, Select } from '@byline/ui/react'
 import cx from 'classnames'
 
+import { getAdminRoutePath } from '../../routes/admin-path.js'
 import { useNavigate } from '../chrome/loose-router.js'
 import { PreviewLink } from './preview-link.js'
 import styles from './view-menu.module.css'
@@ -86,7 +87,7 @@ export const ViewMenu = ({
   useEffect(() => {
     if (activeView === 'edit' && locale === 'all') {
       navigate({
-        to: '/admin/collections/$collection/$id' as never,
+        to: getAdminRoutePath('collections', '$collection', '$id'),
         params: { collection, id: documentId },
         search: (prev: Record<string, unknown>) => ({
           ...prev,
@@ -103,19 +104,19 @@ export const ViewMenu = ({
     const search = (prev: Record<string, unknown>) => ({ ...prev, locale: value })
     if (activeView === 'api') {
       navigate({
-        to: '/admin/collections/$collection/$id/api' as never,
+        to: getAdminRoutePath('collections', '$collection', '$id', 'api'),
         params: { collection, id: documentId },
         search: search as never,
       })
     } else if (activeView === 'history') {
       navigate({
-        to: '/admin/collections/$collection/$id/history' as never,
+        to: getAdminRoutePath('collections', '$collection', '$id', 'history'),
         params: { collection, id: documentId },
         search: search as never,
       })
     } else {
       navigate({
-        to: '/admin/collections/$collection/$id' as never,
+        to: getAdminRoutePath('collections', '$collection', '$id'),
         params: { collection, id: documentId },
         search: search as never,
       })
@@ -127,7 +128,7 @@ export const ViewMenu = ({
     const n = Number.parseInt(value, 10)
     const nextDepth = Number.isFinite(n) ? Math.max(0, Math.min(3, n)) : 0
     navigate({
-      to: '/admin/collections/$collection/$id/api' as never,
+      to: getAdminRoutePath('collections', '$collection', '$id', 'api'),
       params: { collection, id: documentId },
       // Store 0 as undefined so the URL stays clean when the user picks
       // "no populate" — avoids `?depth=0` in bookmarks / share links.
@@ -201,7 +202,7 @@ export const ViewMenu = ({
         variant={activeView === 'history' ? 'filled' : 'text'}
         onClick={() =>
           navigate({
-            to: '/admin/collections/$collection/$id/history' as never,
+            to: getAdminRoutePath('collections', '$collection', '$id', 'history'),
             params: { collection, id: documentId },
             search: locale ? { locale } : {},
           })
@@ -215,7 +216,7 @@ export const ViewMenu = ({
         className={cx('byline-view-menu-button', styles.button)}
         onClick={() =>
           navigate({
-            to: '/admin/collections/$collection/$id' as never,
+            to: getAdminRoutePath('collections', '$collection', '$id'),
             params: { collection, id: documentId },
             search: locale ? { locale } : {},
           })
@@ -229,7 +230,7 @@ export const ViewMenu = ({
         className={cx('byline-view-menu-button', styles.button)}
         onClick={() =>
           navigate({
-            to: '/admin/collections/$collection/$id/api' as never,
+            to: getAdminRoutePath('collections', '$collection', '$id', 'api'),
             params: { collection, id: documentId },
             search: locale ? { locale } : {},
           })

package/src/i18n/resolve-locale.ts

@@ -23,10 +23,10 @@
 import { getRequestHeader } from '@tanstack/react-start/server'
 
 import { AuthError, AuthErrorCodes } from '@byline/auth'
+import { getAdminRequestContext } from '@byline/client/server'
 import type { LocaleCode } from '@byline/i18n'
 import { resolveInterfaceLocale } from '@byline/i18n'
 
-import { getAdminRequestContext } from '../auth/auth-context.js'
 import { bylineCore } from '../integrations/byline-core.js'
 import { readAdminLocaleCookie } from './locale-cookie.js'
 

package/src/index.ts

@@ -19,14 +19,13 @@
  *   - `@byline/host-tanstack-start/server-fns/<module>` — TanStack Start
  *     server functions for each admin module (admin-account, admin-roles,
  *     admin-users, admin-permissions, auth, collections).
- *   - `@byline/host-tanstack-start/auth/auth-context` — request-scoped
- *     `RequestContext` resolution that reads session cookies, refreshes
- *     transparently, and surfaces `ERR_UNAUTHENTICATED` to callers.
  *   - `@byline/host-tanstack-start/integrations/*` — host-side adapters
  *     binding TanStack Start primitives to the framework-neutral
- *     contracts in `@byline/ui` and `@byline/client`
- *     (`bylineFieldServices`, `bylineAdminServices`, the admin
- *     `BylineClient` singleton).
+ *     contracts in `@byline/ui`, `@byline/core`, and `@byline/client`
+ *     (`bylineFieldServices`, `bylineAdminServices`, and `host-bridge` —
+ *     the `HostRequestBridge` implementation behind the
+ *     `@byline/client/server` getters; request-context resolution and the
+ *     client singletons themselves live in `@byline/client/server`).
  *   - `@byline/host-tanstack-start/admin-shell/{chrome,collections,...}` —
  *     router-coupled admin UI: shared shell chrome (menu drawer, app bar,
  *     route-error, breadcrumbs, etc.) plus per-area page containers.

package/src/integrations/abilities.tsx

@@ -38,15 +38,25 @@
 import type React from 'react'
 import { useRouteContext } from '@tanstack/react-router'
 
-/** Route id of the admin shell — the layout route that owns `user` on context. */
-const ADMIN_ROUTE_ID = '/_byline/admin' as const
+import { getAdminRouteId } from '../routes/admin-path.js'
+
+interface AbilityRouteContext {
+  user: {
+    is_super_admin: boolean
+    abilities: string[]
+  }
+}
+
+function useAbilityRouteContext(): AbilityRouteContext {
+  return useRouteContext({ from: getAdminRouteId() as never }) as AbilityRouteContext
+}
 
 /**
  * `true` when the current admin holds the given ability (or is a
  * super-admin). Cosmetic — see file-level docstring.
  */
 export function useAbility(ability: string): boolean {
-  const { user } = useRouteContext({ from: ADMIN_ROUTE_ID })
+  const { user } = useAbilityRouteContext()
   if (user.is_super_admin) return true
   return user.abilities.includes(ability)
 }
@@ -62,7 +72,7 @@ export function useAbilities(): {
   hasAny: (abilities: readonly string[]) => boolean
   isSuperAdmin: boolean
 } {
-  const { user } = useRouteContext({ from: ADMIN_ROUTE_ID })
+  const { user } = useAbilityRouteContext()
   const has = (ability: string): boolean => user.is_super_admin || user.abilities.includes(ability)
   const hasAny = (abilities: readonly string[]): boolean =>
     user.is_super_admin || abilities.some((key) => user.abilities.includes(key))

package/src/integrations/host-bridge.ts

@@ -0,0 +1,56 @@
+/**
+ * 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
+ */
+
+/**
+ * The TanStack Start implementation of `HostRequestBridge` — the three
+ * request primitives (`getRequest` identity, cookie read, cookie write)
+ * that `@byline/client/server` is written against.
+ *
+ * Registered as a module side effect: every module in this package that
+ * fronts the server-side client stack imports this file first, so any
+ * code path that can reach a getter has already registered the bridge.
+ * Registration is idempotent (last-write-wins on a `globalThis` symbol
+ * slot), so repeated evaluation across Vite SSR module graphs is
+ * harmless.
+ */
+
+import { getCookie, getRequest, setCookie } from '@tanstack/react-start/server'
+
+import {
+  type HostCookieSetOptions,
+  type HostRequestBridge,
+  registerHostRequestBridge,
+} from '@byline/core'
+
+const tanstackStartRequestBridge: HostRequestBridge = {
+  getRequest(): object | undefined {
+    try {
+      return getRequest()
+    } catch {
+      // No StartEvent in AsyncLocalStorage — running outside a request.
+      return undefined
+    }
+  },
+  getCookie(name: string): string | undefined {
+    return getCookie(name)
+  },
+  setCookie(name: string, value: string, options?: HostCookieSetOptions): void {
+    setCookie(name, value, options)
+  },
+}
+
+/**
+ * Register the TanStack Start bridge. Safe to call any number of times;
+ * exported for hosts that want registration to be explicit in their
+ * server config rather than relying on a side-effect import.
+ */
+export function registerTanstackStartHostBridge(): void {
+  registerHostRequestBridge(tanstackStartRequestBridge)
+}
+
+registerTanstackStartHostBridge()

package/src/integrations/serve-uploads.ts

@@ -46,6 +46,12 @@ import type { Stats } from 'node:fs'
 import { readFile, stat } from 'node:fs/promises'
 import { resolve as resolvePath } from 'node:path'
 
+// Belt-and-braces bridge registration: `serveUploads` is imported by every
+// scaffolded app's `src/server.ts` at boot, so pulling in the host bridge
+// here guarantees `@byline/client/server` getters can resolve cookies even
+// if a server config forgets the explicit `registerTanstackStartHostBridge()`.
+import './host-bridge.js'
+
 export interface UploadsHandlerOptions {
   /**
    * URL prefix to match. Trailing slash required. Default `'/uploads/'`.

package/src/integrations/start-errors.test.node.ts

@@ -0,0 +1,22 @@
+import { ERR_CONFLICT, ERR_TREE_HOOK_COMMITTED } from '@byline/core'
+import { describe, expect, it } from 'vitest'
+
+import { bylineCodedErrorAdapter } from './start-errors.js'
+
+describe('Byline coded error serialization', () => {
+  it.each([
+    ERR_CONFLICT({ message: 'stale tree' }),
+    ERR_TREE_HOOK_COMMITTED({ message: 'tree committed; hook failed' }),
+  ])('preserves core BylineError code $code', (error) => {
+    expect(bylineCodedErrorAdapter.test(error)).toBe(true)
+
+    const payload = bylineCodedErrorAdapter.toSerializable(error)
+    const restored = bylineCodedErrorAdapter.fromSerializable(payload)
+
+    expect(restored).toMatchObject({
+      name: 'BylineError',
+      code: error.code,
+      message: error.message,
+    })
+  })
+})

package/src/integrations/start-errors.ts

@@ -44,6 +44,7 @@ const CODED_ERROR_NAMES = new Set([
   'AdminRolesError',
   'AdminUsersError',
   'AuthError',
+  'BylineError',
 ])
 
 export interface BylineCodedErrorPayload {