chore: refactor sanitizeOrderable

docs/configuration/collections.mdx

@@ -70,6 +70,7 @@ The following options are available:
 | `fields` *         | Array of field types that will determine the structure and functionality of the data stored within this Collection. [More details](../fields/overview).                                                              |
 | `graphQL`          | Manage GraphQL-related properties for this collection. [More](#graphql)                                                                                                                                              |
 | `hooks`            | Entry point for Hooks. [More details](../hooks/overview#collection-hooks).                                                                                                                                           |
+| `orderable`       | If true, enables custom ordering for the collection, and documents can be reordered via drag and drop. Uses [fractional indexing](https://observablehq.com/@dgreensp/implementing-fractional-indexing) for efficient reordering. |
 | `labels`           | Singular and plural labels for use in identifying this Collection throughout Payload. Auto-generated from slug if not defined.                                                                                       |
 | `lockDocuments`    | Enables or disables document locking. By default, document locking is enabled. Set to an object to configure, or set to `false` to disable locking. [More details](../admin/locked-documents).                       |
 | `slug` *           | Unique, URL-friendly string that will act as an identifier for this Collection.                                                                                                                                      |

packages/payload/src/collections/config/sanitize.ts

@@ -1,4 +1,5 @@
 // @ts-strict-ignore
+
 import type { Config, SanitizedConfig } from '../../config/types.js'
 import type {
   CollectionConfig,
@@ -27,6 +28,7 @@ import {
 } from './defaults.js'
 import { sanitizeAuthFields, sanitizeUploadFields } from './reservedFieldNames.js'
 import { sanitizeCompoundIndexes } from './sanitizeCompoundIndexes.js'
+import { sanitizeOrderable } from './sanitizeOrderable.js'
 import { validateUseAsTitle } from './useAsTitle.js'
 
 export const sanitizeCollection = async (
@@ -237,6 +239,8 @@ export const sanitizeCollection = async (
 
   const sanitizedConfig = sanitized as SanitizedCollectionConfig
 
+  sanitizeOrderable(sanitizedConfig)
+
   sanitizedConfig.joins = joins
   sanitizedConfig.polymorphicJoins = polymorphicJoins
 

packages/payload/src/collections/config/sanitizeOrderable.ts

@@ -0,0 +1,60 @@
+import type { Field } from '../../fields/config/types.js'
+import type { BeforeChangeHook, SanitizedCollectionConfig } from './types.js'
+
+import { generateKeyBetween } from '../../utilities/fractional-indexing.js'
+import { getReorderEndpoint } from '../endpoints/reorder.js'
+
+export const ORDER_FIELD_NAME = '_order'
+
+export const sanitizeOrderable = (collection: SanitizedCollectionConfig) => {
+  if (!collection.orderable) {
+    return
+  }
+  // 1. Add field
+  const orderField: Field = {
+    name: ORDER_FIELD_NAME,
+    type: 'text',
+    admin: {
+      disableBulkEdit: true,
+      disabled: true,
+      disableListColumn: true,
+      disableListFilter: true,
+      hidden: true,
+      readOnly: true,
+    },
+    index: true,
+    label: ({ t }) => t('general:order'),
+    required: true,
+    unique: true,
+  }
+
+  collection.fields.unshift(orderField)
+
+  // 2. Add hook
+  const orderBeforeChangeHook: BeforeChangeHook = async ({ data, operation, req }) => {
+    // Only set _order on create, not on update (unless explicitly provided)
+    if (operation === 'create') {
+      // Find the last document to place this one after
+      const lastDoc = await req.payload.find({
+        collection: collection.slug,
+        depth: 0,
+        limit: 1,
+        pagination: false,
+        select: { [ORDER_FIELD_NAME]: true },
+        sort: `-${ORDER_FIELD_NAME}`,
+      })
+
+      const lastOrderValue: null | string = (lastDoc.docs[0]?.[ORDER_FIELD_NAME] as string) || null
+      data[ORDER_FIELD_NAME] = generateKeyBetween(lastOrderValue, null)
+    }
+
+    return data
+  }
+
+  collection.hooks.beforeChange.push(orderBeforeChangeHook)
+
+  // 3. Add endpoint
+  if (collection.endpoints !== false) {
+    collection.endpoints.push(getReorderEndpoint(collection))
+  }
+}

packages/payload/src/collections/config/types.ts

@@ -495,6 +495,17 @@ export type CollectionConfig<TSlug extends CollectionSlug = any> = {
         duration: number
       }
     | false
+  /**
+   * If true, enables custom ordering for the collection, and documents in the listView can be reordered via drag and drop.
+   * New documents are inserted at the end of the list according to this parameter.
+   *
+   * Under the hood, a field with {@link https://observablehq.com/@dgreensp/implementing-fractional-indexing|fractional indexing} is used to optimize inserts and reorderings.
+   *
+   * @default false
+   *
+   * @experimental There may be frequent breaking changes to this API
+   */
+  orderable?: boolean
   slug: string
   /**
    * Add `createdAt` and `updatedAt` fields

packages/payload/src/collections/endpoints/reorder.ts

@@ -0,0 +1,131 @@
+import type { Endpoint, PayloadHandler } from '../../config/types.js'
+import type { PayloadRequest, SanitizedCollectionConfig } from '../../index.js'
+
+import { APIError, executeAccess } from '../../index.js'
+import { generateNKeysBetween } from '../../utilities/fractional-indexing.js'
+import { ORDER_FIELD_NAME } from '../config/sanitizeOrderable.js'
+
+export const getReorderEndpoint = (
+  collection: SanitizedCollectionConfig,
+): Omit<Endpoint, 'root'> => {
+  const reorderHandler: PayloadHandler = async (req: PayloadRequest) => {
+    if (!req.json) {
+      throw new APIError('Unreachable')
+    }
+    const body = await req.json()
+    type KeyAndID = {
+      id: string
+      key: string
+    }
+    const { docsToMove, newKeyWillBe, target } = body as {
+      // array of docs IDs to be moved before or after the target
+      docsToMove: string[]
+      // new key relative to the target. We don't use "after" or "before" as
+      // it can be misleading if the table is sorted in descending order.
+      newKeyWillBe: 'greater' | 'less'
+      target: KeyAndID
+    }
+
+    if (!Array.isArray(docsToMove) || docsToMove.length === 0) {
+      return new Response(JSON.stringify({ error: 'docsToMove must be a non-empty array' }), {
+        headers: { 'Content-Type': 'application/json' },
+        status: 400,
+      })
+    }
+    if (
+      typeof target !== 'object' ||
+      typeof target.id !== 'string' ||
+      typeof target.key !== 'string'
+    ) {
+      return new Response(JSON.stringify({ error: 'target must be an object with id and key' }), {
+        headers: { 'Content-Type': 'application/json' },
+        status: 400,
+      })
+    }
+    if (newKeyWillBe !== 'greater' && newKeyWillBe !== 'less') {
+      return new Response(JSON.stringify({ error: 'newKeyWillBe must be "greater" or "less"' }), {
+        headers: { 'Content-Type': 'application/json' },
+        status: 400,
+      })
+    }
+
+    // Prevent reordering if user doesn't have editing permissions
+    await executeAccess(
+      {
+        // Currently only one doc can be moved at a time. We should review this if we want to allow
+        // multiple docs to be moved at once in the future.
+        id: docsToMove[0],
+        data: {},
+        req,
+      },
+      collection.access.update,
+    )
+
+    const targetId = target.id
+    let targetKey: null | string = target.key
+
+    // If targetKey = pending, we need to find its current key.
+    // This can only happen if the user reorders rows quickly with a slow connection.
+    if (targetKey === 'pending') {
+      const beforeDoc = await req.payload.findByID({
+        id: targetId,
+        collection: collection.slug,
+        depth: 0,
+        select: { [ORDER_FIELD_NAME]: true },
+      })
+      targetKey = (beforeDoc?.[ORDER_FIELD_NAME] as string) || null
+    }
+
+    // The reason the endpoint does not receive this docId as an argument is that there
+    // are situations where the user may not see or know what the next or previous one is. For
+    // example, access control restrictions, if docBefore is the last one on the page, etc.
+    const adjacentDoc = await req.payload.find({
+      collection: collection.slug,
+      depth: 0,
+      limit: 1,
+      pagination: false,
+      select: { [ORDER_FIELD_NAME]: true },
+      sort: newKeyWillBe === 'greater' ? ORDER_FIELD_NAME : `-${ORDER_FIELD_NAME}`,
+      where: {
+        [ORDER_FIELD_NAME]: {
+          [newKeyWillBe === 'greater' ? 'greater_than' : 'less_than']: targetKey,
+        },
+      },
+    })
+    const adjacentDocKey: null | string =
+      (adjacentDoc.docs?.[0]?.[ORDER_FIELD_NAME] as string) || null
+
+    // Currently N (= docsToMove.length) is always 1. Maybe in the future we will
+    // allow dragging and reordering multiple documents at once via the UI.
+    const orderValues =
+      newKeyWillBe === 'greater'
+        ? generateNKeysBetween(targetKey, adjacentDocKey, docsToMove.length)
+        : generateNKeysBetween(adjacentDocKey, targetKey, docsToMove.length)
+
+    // Update each document with its new order value
+
+    for (const id of docsToMove) {
+      await req.payload.update({
+        id,
+        collection: collection.slug,
+        data: {
+          [ORDER_FIELD_NAME]: orderValues.shift(),
+        },
+        depth: 0,
+        req,
+        select: { [ORDER_FIELD_NAME]: true },
+      })
+    }
+
+    return new Response(JSON.stringify({ orderValues, success: true }), {
+      headers: { 'Content-Type': 'application/json' },
+      status: 200,
+    })
+  }
+
+  return {
+    handler: reorderHandler,
+    method: 'post',
+    path: '/reorder',
+  }
+}