@byline/host-tanstack-start 1.10.3 → 1.11.0

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

@@ -6,13 +6,14 @@
  * Copyright (c) Infonomic Company Limited
  */
 
-import { useMemo, useState } from 'react'
-import { useRouterState } from '@tanstack/react-router'
+import { useEffect, useMemo, useState } from 'react'
+import { useRouter, useRouterState } from '@tanstack/react-router'
 
 import type { ColumnDefinition, WorkflowStatus } from '@byline/core'
 import type { AnyCollectionSchemaTypes } from '@byline/core/zod-schemas'
 import {
   Container,
+  GripperVerticalIcon,
   IconButton,
   LoaderRing,
   PlusIcon,
@@ -22,15 +23,37 @@ import {
   Select,
   StatusBadge,
   Table,
+  useToastManager,
 } from '@byline/ui/react'
+import {
+  DndContext,
+  type DragEndEvent,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+} from '@dnd-kit/core'
+import {
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable'
 import cx from 'classnames'
 
 import { Link, useNavigate } from '../chrome/loose-router.js'
 import { RouterPager } from '../chrome/router-pager.js'
+import { SortAscendingIcon } from '../chrome/sort-icons.js'
 import { TableHeadingCellSortable } from '../chrome/th-sortable.js'
 import { formatNumber } from '../chrome/utils.js'
 import styles from './list.module.css'
 
+type ReorderFn = (params: {
+  documentId: string
+  beforeDocumentId: string | null
+  afterDocumentId: string | null
+}) => Promise<unknown>
+
 /**
  * Resolve a column value from a document, checking `fields` first (user-defined
  * collection fields) then the root (metadata like status, updated_at).
@@ -76,20 +99,145 @@ function padRows(value: number) {
   ))
 }
 
+/**
+ * One `<tr>` participating in dnd-kit's vertical-list sort. Renders the row
+ * directly (not via `Table.Row`) because the row needs a function `ref`
+ * callback for dnd-kit; `Table.Row`'s typed `RefObject` prop wouldn't
+ * accept that.
+ */
+function SortableTableRow({
+  id,
+  disabled,
+  children,
+}: {
+  id: string
+  disabled: boolean
+  children: React.ReactNode
+}) {
+  const { setNodeRef, attributes, listeners, transform, transition, isDragging } = useSortable({
+    id,
+    disabled,
+  })
+  const style: React.CSSProperties = {
+    transform: transform ? `translate3d(${transform.x}px, ${transform.y}px, 0)` : undefined,
+    transition,
+    position: 'relative',
+    zIndex: isDragging ? 10 : 'auto',
+    opacity: isDragging ? 0.6 : 1,
+  }
+  return (
+    <tr ref={setNodeRef} className="byline-table-row" style={style}>
+      <td className={cx('byline-coll-list-drag-cell', styles.dragCell)}>
+        <button
+          type="button"
+          className={cx('byline-coll-list-drag-handle', styles.dragHandle)}
+          aria-label={
+            disabled ? 'Drag disabled while filters or search are active' : 'Drag to reorder'
+          }
+          disabled={disabled}
+          {...attributes}
+          {...listeners}
+        >
+          <GripperVerticalIcon />
+        </button>
+      </td>
+      {children}
+    </tr>
+  )
+}
+
 export const ListView = ({
   data,
   columns,
   workflowStatuses,
   useAsTitle,
+  orderable = false,
+  onReorder,
 }: {
   data: AnyCollectionSchemaTypes['ListType']
   columns: ColumnDefinition[]
   workflowStatuses?: WorkflowStatus[]
   useAsTitle?: string
+  /** When true, render a drag handle column and enable drag-to-reorder. */
+  orderable?: boolean
+  /** Persists a single-row reorder via the host's reorder server fn. */
+  onReorder?: ReorderFn
 }) => {
   const navigate = useNavigate()
+  const router = useRouter()
+  const toastManager = useToastManager()
   const location = useRouterState({ select: (s) => s.location })
 
+  // Local mirror of the loader docs so drag-and-drop can paint the new
+  // order optimistically before the server roundtrip completes. We resync
+  // from `data.docs` whenever fresh loader data arrives (after a
+  // `router.invalidate()`), unless a reorder is mid-flight — clobbering
+  // an in-flight optimistic state would flash the row back to its old
+  // position. See the dnd-kit + admin-roles list pattern for the same
+  // ordering invariant.
+  const [localDocs, setLocalDocs] = useState(data.docs)
+  const [isReordering, setIsReordering] = useState(false)
+  useEffect(() => {
+    if (!isReordering) {
+      setLocalDocs(data.docs)
+    }
+  }, [data.docs, isReordering])
+
+  // Drag is only meaningful in the canonical view: the default order_key
+  // sort, no search, no status filter. Otherwise the visible order isn't
+  // the stored order and "drop between A and B" maps onto the wrong
+  // neighbour ids.
+  const searchParams = location.search as {
+    order?: string
+    desc?: boolean
+    query?: string
+    status?: string
+  }
+  const isCanonicalView =
+    !searchParams.order && !searchParams.desc && !searchParams.query && !searchParams.status
+  const dragEnabled = orderable && isCanonicalView && !!onReorder
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
+  )
+
+  const handleDragEnd = async (event: DragEndEvent) => {
+    const { active, over } = event
+    if (!over || active.id === over.id || !onReorder) return
+    const oldIndex = localDocs.findIndex((d) => d.id === active.id)
+    const newIndex = localDocs.findIndex((d) => d.id === over.id)
+    if (oldIndex < 0 || newIndex < 0 || oldIndex === newIndex) return
+
+    const previousDocs = localDocs
+    const next = [...localDocs]
+    const [moved] = next.splice(oldIndex, 1)
+    if (!moved) return
+    next.splice(newIndex, 0, moved)
+    setLocalDocs(next)
+    setIsReordering(true)
+
+    const before = next[newIndex - 1]?.id ?? null
+    const after = next[newIndex + 1]?.id ?? null
+    try {
+      await onReorder({
+        documentId: String(active.id),
+        beforeDocumentId: before,
+        afterDocumentId: after,
+      })
+      await router.invalidate()
+    } catch (_err) {
+      setLocalDocs(previousDocs)
+      toastManager.add({
+        title: 'Could not save the new order',
+        description: 'Please try again.',
+        data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
+      })
+    } finally {
+      setIsReordering(false)
+    }
+  }
+
   // Memoized so Base UI's SelectRoot doesn't see a fresh items identity on
   // every render — a non-stable items array combined with a controlled value
   // trips an internal store sync loop (manifests as "Maximum update depth
@@ -204,77 +352,191 @@ export const ListView = ({
           />
         </div>
         <Table.Container className={cx('byline-coll-list-table-wrap', styles.tableWrap)}>
-          <Table>
-            <Table.Header>
-              <Table.Row>
-                {columns.map((column) => {
-                  return (
-                    <TableHeadingCellSortable
-                      key={String(column.fieldName)}
-                      fieldName={String(column.fieldName)}
-                      label={column.label}
-                      sortable={column.sortable}
-                      scope="col"
-                      align={column.align}
-                      className={column.className}
-                    />
-                  )
-                })}
-              </Table.Row>
-            </Table.Header>
+          {orderable ? (
+            <DndContext sensors={sensors} onDragEnd={handleDragEnd}>
+              <SortableContext
+                items={localDocs.map((d) => d.id)}
+                strategy={verticalListSortingStrategy}
+              >
+                <Table>
+                  <Table.Header>
+                    <Table.Row>
+                      <th scope="col" className={cx('byline-coll-list-drag-cell', styles.dragCell)}>
+                        <button
+                          type="button"
+                          className={cx(
+                            'byline-coll-list-order-header',
+                            styles.orderHeader,
+                            isCanonicalView && [
+                              'byline-coll-list-order-header-active',
+                              styles.orderHeaderActive,
+                            ]
+                          )}
+                          onClick={() => {
+                            // Clear any non-canonical sort and search-related
+                            // state so the visible order matches what drag
+                            // operations will mutate. Default sort then falls
+                            // back to `order_key asc` server-side.
+                            const params = structuredClone(
+                              location.search as Record<string, unknown>
+                            )
+                            delete params.page
+                            delete params.order
+                            delete params.desc
+                            navigate({
+                              to: location.pathname as never,
+                              search: params,
+                            })
+                          }}
+                          aria-label="Sort by manual order"
+                          title="Sort by manual order"
+                        >
+                          <SortAscendingIcon />
+                        </button>
+                      </th>
+                      {columns.map((column) => {
+                        return (
+                          <TableHeadingCellSortable
+                            key={String(column.fieldName)}
+                            fieldName={String(column.fieldName)}
+                            label={column.label}
+                            sortable={column.sortable}
+                            scope="col"
+                            align={column.align}
+                            className={column.className}
+                          />
+                        )
+                      })}
+                    </Table.Row>
+                  </Table.Header>
 
-            <Table.Body>
-              {data?.docs?.map((document) => {
-                return (
-                  <Table.Row key={document.id}>
-                    {columns.map((column) => (
-                      <Table.Cell
-                        key={String(column.fieldName)}
-                        className={cx({
-                          'byline-coll-list-cell-right': column.align === 'right',
-                          [styles.cellRight]: column.align === 'right',
-                          'byline-coll-list-cell-center': column.align === 'center',
-                          [styles.cellCenter]: column.align === 'center',
-                        })}
-                      >
-                        {useAsTitle && column.fieldName === useAsTitle ? (
-                          <Link
-                            to={'/admin/collections/$collection/$id' as never}
-                            params={{
-                              collection: data.included.collection.path,
-                              id: document.id,
-                            }}
+                  <Table.Body>
+                    {localDocs.map((document) => (
+                      <SortableTableRow key={document.id} id={document.id} disabled={!dragEnabled}>
+                        {columns.map((column) => (
+                          <Table.Cell
+                            key={String(column.fieldName)}
+                            className={cx({
+                              'byline-coll-list-cell-right': column.align === 'right',
+                              [styles.cellRight]: column.align === 'right',
+                              'byline-coll-list-cell-center': column.align === 'center',
+                              [styles.cellCenter]: column.align === 'center',
+                            })}
                           >
-                            {column.formatter
-                              ? renderFormatted(
-                                  getColumnValue(document, column.fieldName as string),
-                                  document,
-                                  column.formatter
-                                )
-                              : (getColumnValue(document, column.fieldName as string) ?? '------')}
-                          </Link>
-                        ) : column.formatter ? (
-                          renderFormatted(
-                            getColumnValue(document, column.fieldName as string),
-                            document,
-                            column.formatter
-                          )
-                        ) : column.fieldName === 'status' && workflowStatuses ? (
-                          <StatusBadge
-                            status={document.status}
-                            workflowStatuses={workflowStatuses}
-                            hasPublishedVersion={document.hasPublishedVersion}
-                          />
-                        ) : (
-                          String(getColumnValue(document, column.fieldName as string) ?? '')
-                        )}
-                      </Table.Cell>
+                            {useAsTitle && column.fieldName === useAsTitle ? (
+                              <Link
+                                to={'/admin/collections/$collection/$id' as never}
+                                params={{
+                                  collection: data.included.collection.path,
+                                  id: document.id,
+                                }}
+                              >
+                                {column.formatter
+                                  ? renderFormatted(
+                                      getColumnValue(document, column.fieldName as string),
+                                      document,
+                                      column.formatter
+                                    )
+                                  : (getColumnValue(document, column.fieldName as string) ??
+                                    '------')}
+                              </Link>
+                            ) : column.formatter ? (
+                              renderFormatted(
+                                getColumnValue(document, column.fieldName as string),
+                                document,
+                                column.formatter
+                              )
+                            ) : column.fieldName === 'status' && workflowStatuses ? (
+                              <StatusBadge
+                                status={document.status}
+                                workflowStatuses={workflowStatuses}
+                                hasPublishedVersion={document.hasPublishedVersion}
+                              />
+                            ) : (
+                              String(getColumnValue(document, column.fieldName as string) ?? '')
+                            )}
+                          </Table.Cell>
+                        ))}
+                      </SortableTableRow>
                     ))}
-                  </Table.Row>
-                )
-              })}
-            </Table.Body>
-          </Table>
+                  </Table.Body>
+                </Table>
+              </SortableContext>
+            </DndContext>
+          ) : (
+            <Table>
+              <Table.Header>
+                <Table.Row>
+                  {columns.map((column) => {
+                    return (
+                      <TableHeadingCellSortable
+                        key={String(column.fieldName)}
+                        fieldName={String(column.fieldName)}
+                        label={column.label}
+                        sortable={column.sortable}
+                        scope="col"
+                        align={column.align}
+                        className={column.className}
+                      />
+                    )
+                  })}
+                </Table.Row>
+              </Table.Header>
+
+              <Table.Body>
+                {data?.docs?.map((document) => {
+                  return (
+                    <Table.Row key={document.id}>
+                      {columns.map((column) => (
+                        <Table.Cell
+                          key={String(column.fieldName)}
+                          className={cx({
+                            'byline-coll-list-cell-right': column.align === 'right',
+                            [styles.cellRight]: column.align === 'right',
+                            'byline-coll-list-cell-center': column.align === 'center',
+                            [styles.cellCenter]: column.align === 'center',
+                          })}
+                        >
+                          {useAsTitle && column.fieldName === useAsTitle ? (
+                            <Link
+                              to={'/admin/collections/$collection/$id' as never}
+                              params={{
+                                collection: data.included.collection.path,
+                                id: document.id,
+                              }}
+                            >
+                              {column.formatter
+                                ? renderFormatted(
+                                    getColumnValue(document, column.fieldName as string),
+                                    document,
+                                    column.formatter
+                                  )
+                                : (getColumnValue(document, column.fieldName as string) ??
+                                  '------')}
+                            </Link>
+                          ) : column.formatter ? (
+                            renderFormatted(
+                              getColumnValue(document, column.fieldName as string),
+                              document,
+                              column.formatter
+                            )
+                          ) : column.fieldName === 'status' && workflowStatuses ? (
+                            <StatusBadge
+                              status={document.status}
+                              workflowStatuses={workflowStatuses}
+                              hasPublishedVersion={document.hasPublishedVersion}
+                            />
+                          ) : (
+                            String(getColumnValue(document, column.fieldName as string) ?? '')
+                          )}
+                        </Table.Cell>
+                      ))}
+                    </Table.Row>
+                  )
+                })}
+              </Table.Body>
+            </Table>
+          )}
           {padRows(6 - (data?.docs?.length ?? 0))}
         </Table.Container>
         <div

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

@@ -21,7 +21,10 @@ import { z } from 'zod'
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { useNavigate } from '../admin-shell/chrome/loose-router.js'
 import { ListView } from '../admin-shell/collections/list.js'
-import { getCollectionDocuments } from '../server-fns/collections/index.js'
+import {
+  getCollectionDocuments,
+  reorderCollectionDocument,
+} from '../server-fns/collections/index.js'
 
 const searchSchema = z.object({
   page: z.coerce.number().min(1).optional(),
@@ -164,6 +167,17 @@ export function createCollectionListRoute(path: string) {
               columns={columns}
               workflowStatuses={workflowStatuses}
               useAsTitle={collectionDef.useAsTitle}
+              orderable={adminConfig?.orderable === true}
+              onReorder={async ({ documentId, beforeDocumentId, afterDocumentId }) => {
+                await reorderCollectionDocument({
+                  data: {
+                    collection,
+                    documentId,
+                    beforeDocumentId,
+                    afterDocumentId,
+                  },
+                })
+              }}
             />
           )}
         </>

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

@@ -12,6 +12,7 @@ export * from './duplicate'
 export * from './get'
 export * from './history'
 export * from './list'
+export * from './reorder'
 export * from './restore-version'
 export * from './stats'
 export * from './status'

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

@@ -10,6 +10,7 @@ import { createServerFn } from '@tanstack/react-start'
 
 import {
   ERR_NOT_FOUND,
+  getCollectionAdminConfig,
   getCollectionSchemasForPath,
   getLogger,
   getServerConfig,
@@ -65,9 +66,19 @@ export const getCollectionDocuments = createServerFn({ method: 'GET' })
     if (params.status) where.status = params.status
     if (params.query) where.query = params.query
 
+    // Default sort for `orderable: true` collections is the fractional
+    // `order_key` ascending. Caller's explicit `params.order` always wins
+    // so the admin can re-sort by other columns without surprise.
+    const adminConfig = getCollectionAdminConfig(path)
+    const defaultSort: Record<string, 'asc' | 'desc'> | undefined =
+      adminConfig?.orderable === true ? { order_key: 'asc' } : undefined
+    const sortSpec: Record<string, 'asc' | 'desc'> | undefined = params.order
+      ? { [params.order]: params.desc === false ? 'asc' : 'desc' }
+      : defaultSort
+
     const result = await handle.find({
       where: Object.keys(where).length > 0 ? where : undefined,
-      sort: params.order ? { [params.order]: params.desc === false ? 'asc' : 'desc' } : undefined,
+      sort: sortSpec,
       locale: params.locale ?? 'en',
       page: params.page,
       pageSize,