feat: support custom slugify functions (#14117)

Continuation of #14007.

Supports overriding the default slugify function of the slug field. This
is necessary if the slug requires special treatment, such as character
encoding, additional language support, etc.

For example, if you wanted to use the
[`slugify`](https://www.npmjs.com/package/slugify) package, you could do
something like this:

```ts
import type { CollectionConfig } from 'payload'
import { slugField } from 'payload'
import slugify from 'slugify';

export const MyCollection: CollectionConfig = {
  // ...
  fields: [
    // ...
    slugField({
      slugify: ({ valueToSlugify }) => slugify(valueToSlugify, {
        // ...additional `slugify` options here
      })
    })
  ]
}
```

This PR also deprecates the old `fieldToUse` arg in favor of `useAsSlug`
which is more semantically clear, following the same convention as
`useAsTitle`.

Example:

```ts
import type { CollectionConfig } from 'payload'
import { slugField } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  fields: [
    // ...
    slugField({
      useAsSlug: 'myCustomTitle'
    })
  ]
}
```

In follow-up PRs, we should also:
- Improve the default slugify function to better handle special
characters on its own, etc.
- [Support nested
slugs](#14783)

Author: jacobsfletch

docs/fields/text.mdx

@@ -217,10 +217,11 @@ The slug field exposes a few top-level config options for easy customization:
 | `name`         | To be used as the slug field's name. Defaults to `slug`.                                                                                 |
 | `overrides`    | A function that receives the default fields so you can override on a granular level. See example below. [More details](#slug-overrides). |
 | `checkboxName` | To be used as the name for the `generateSlug` checkbox field. Defaults to `generateSlug`.                                                |
-| `fieldToUse`   | The name of the field to use when generating the slug. This field must exist in the same collection. Defaults to `title`.                |
+| `useAsSlug`    | The name of the top-level field to use when generating the slug. This field must exist in the same collection. Defaults to `title`.      |
 | `localized`    | Enable localization on the `slug` and `generateSlug` fields. Defaults to `false`.                                                        |
 | `position`     | The position of the slug field. [More details](./overview#admin-options).                                                                |
 | `required`     | Require the slug field. Defaults to `true`.                                                                                              |
+| `slugify`      | Override the default slugify function. [More details](#custom-slugify-function).                                                         |
 
 ### Slug Overrides
 
@@ -245,3 +246,38 @@ export const ExampleCollection: CollectionConfig = {
   ],
 }
 ```
+
+### Custom Slugify Function
+
+You can also override the default slugify function of the slug field. This is necessary if the slug requires special treatment, such as character encoding, additional language support, etc.
+
+This functions receives the value of the `useAsSlug` field as `valueToSlugify` and must return a string.
+
+For example, if you wanted to use the [`slugify`](https://www.npmjs.com/package/slugify) package, you could do something like this:
+
+```ts
+import type { CollectionConfig } from 'payload'
+import { slugField } from 'payload'
+import slugify from 'slugify'
+
+export const MyCollection: CollectionConfig = {
+  // ...
+  fields: [
+    // ...
+    slugField({
+      slugify: ({ valueToSlugify }) =>
+        slugify(valueToSlugify, {
+          // ...additional `slugify` options here
+        }),
+    }),
+  ],
+}
+```
+
+The following args are provided to the custom `slugify` function:
+
+| Argument         | Type             | Description                                      |
+| ---------------- | ---------------- | ------------------------------------------------ |
+| `valueToSlugify` | `string`         | The value of the field specified in `useAsSlug`. |
+| `data`           | `object`         | The full document data being saved.              |
+| `req`            | `PayloadRequest` | The Payload request object.                      |

packages/next/src/layouts/Root/index.tsx

@@ -88,6 +88,7 @@ export const RootLayout = async ({
     importMap,
     user: req.user,
   })
+
   await applyLocaleFiltering({ clientConfig, config, req })
 
   return (

packages/next/src/utilities/handleServerFunctions.ts

@@ -10,6 +10,7 @@ import { renderDocumentHandler } from '../views/Document/handleServerFunction.js
 import { renderDocumentSlotsHandler } from '../views/Document/renderDocumentSlots.js'
 import { renderListHandler } from '../views/List/handleServerFunction.js'
 import { initReq } from './initReq.js'
+import { slugifyHandler } from './slugify.js'
 
 const baseServerFunctions: Record<string, ServerFunction<any, any>> = {
   'copy-data-from-locale': copyDataFromLocaleHandler,
@@ -20,6 +21,7 @@ const baseServerFunctions: Record<string, ServerFunction<any, any>> = {
   'render-field': _internal_renderFieldHandler,
   'render-list': renderListHandler,
   'schedule-publish': schedulePublishHandler,
+  slugify: slugifyHandler,
   'table-state': buildTableStateHandler,
 }
 

packages/next/src/utilities/slugify.ts

@@ -0,0 +1,58 @@
+import type { Slugify } from 'payload/shared'
+
+import {
+  flattenAllFields,
+  getFieldByPath,
+  type ServerFunction,
+  type SlugifyServerFunctionArgs,
+  UnauthorizedError,
+} from 'payload'
+import { slugify as defaultSlugify } from 'payload/shared'
+
+/**
+ * This server function is directly related to the {@link https://payloadcms.com/docs/fields/text#slug-field | Slug Field}.
+ * This is a server function that is used to invoke the user's custom slugify function from the client.
+ * This pattern is required, as there is no other way for us to pass their function across the client-server boundary.
+ *   - Not through props
+ *   - Not from a server function defined within a server component (see below)
+ * When a server function contains non-serializable data within its closure, it gets passed through the boundary (and breaks).
+ * The only way to pass server functions to the client (that contain non-serializable data) is if it is globally defined.
+ * But we also cannot define this function alongside the server component, as we will not have access to their custom slugify function.
+ * See `ServerFunctionsProvider` for more details.
+ */
+export const slugifyHandler: ServerFunction<
+  SlugifyServerFunctionArgs,
+  Promise<ReturnType<Slugify>>
+> = async (args) => {
+  const { collectionSlug, data, globalSlug, path, req, valueToSlugify } = args
+
+  if (!req.user) {
+    throw new UnauthorizedError()
+  }
+
+  const docConfig = collectionSlug
+    ? req.payload.collections[collectionSlug]?.config
+    : globalSlug
+      ? req.payload.config.globals.find((g) => g.slug === globalSlug)
+      : null
+
+  if (!docConfig) {
+    throw new Error()
+  }
+
+  const { field } = getFieldByPath({
+    config: req.payload.config,
+    fields: flattenAllFields({ fields: docConfig.fields }),
+    path,
+  })
+
+  const customSlugify = (
+    typeof field?.custom?.slugify === 'function' ? field.custom.slugify : undefined
+  ) as Slugify
+
+  const result = customSlugify
+    ? await customSlugify({ data, req, valueToSlugify })
+    : defaultSlugify(valueToSlugify)
+
+  return result
+}

packages/payload/src/admin/functions/index.ts

@@ -1,7 +1,14 @@
 import type { ImportMap } from '../../bin/generateImportMap/index.js'
 import type { SanitizedConfig } from '../../config/types.js'
 import type { PaginatedDocs } from '../../database/types.js'
-import type { CollectionSlug, ColumnPreference, FolderSortKeys } from '../../index.js'
+import type { Slugify } from '../../fields/baseFields/slug/index.js'
+import type {
+  CollectionSlug,
+  ColumnPreference,
+  FieldPaths,
+  FolderSortKeys,
+  GlobalSlug,
+} from '../../index.js'
 import type { PayloadRequest, Sort, Where } from '../../types/index.js'
 import type { ColumnsFromURL } from '../../utilities/transformColumnPreferences.js'
 
@@ -149,3 +156,9 @@ export type GetFolderResultsComponentAndDataArgs = {
    */
   sort: FolderSortKeys
 }
+
+export type SlugifyServerFunctionArgs = {
+  collectionSlug?: CollectionSlug
+  globalSlug?: GlobalSlug
+  path?: FieldPaths['path']
+} & Omit<Parameters<Slugify>[0], 'req'>

packages/payload/src/admin/types.ts

@@ -583,6 +583,7 @@ export type {
   ServerFunctionClientArgs,
   ServerFunctionConfig,
   ServerFunctionHandler,
+  SlugifyServerFunctionArgs,
 } from './functions/index.js'
 
 export type { LanguageOptions } from './LanguageOptions.js'

packages/payload/src/exports/shared.ts

@@ -13,6 +13,8 @@ export { defaults as collectionDefaults } from '../collections/config/defaults.j
 
 export { serverProps } from '../config/types.js'
 
+export { type Slugify } from '../fields/baseFields/slug/index.js'
+
 export { defaultTimezones } from '../fields/baseFields/timezone/defaultTimezones.js'
 
 export {
@@ -39,8 +41,8 @@ export {
 } from '../fields/config/types.js'
 
 export { getFieldPaths } from '../fields/getFieldPaths.js'
-
 export * from '../fields/validations.js'
+
 export type {
   FolderBreadcrumb,
   FolderDocumentItemKey,
@@ -52,41 +54,41 @@ export type {
 } from '../folders/types.js'
 
 export { buildFolderWhereConstraints } from '../folders/utils/buildFolderWhereConstraints.js'
-
 export { formatFolderOrDocumentItem } from '../folders/utils/formatFolderOrDocumentItem.js'
 export { validOperators, validOperatorSet } from '../types/constants.js'
+
 export { formatFilesize } from '../uploads/formatFilesize.js'
 
 export { isImage } from '../uploads/isImage.js'
-
 export { appendUploadSelectFields } from '../utilities/appendUploadSelectFields.js'
 export { applyLocaleFiltering } from '../utilities/applyLocaleFiltering.js'
 export { combineWhereConstraints } from '../utilities/combineWhereConstraints.js'
+
 export {
   deepCopyObject,
   deepCopyObjectComplex,
   deepCopyObjectSimple,
   deepCopyObjectSimpleWithoutReactComponents,
 } from '../utilities/deepCopyObject.js'
-
 export {
   deepMerge,
   deepMergeWithCombinedArrays,
   deepMergeWithReactComponents,
   deepMergeWithSourceArrays,
 } from '../utilities/deepMerge.js'
+
 export { extractID } from '../utilities/extractID.js'
 
 export { flattenAllFields } from '../utilities/flattenAllFields.js'
-
 export { flattenTopLevelFields } from '../utilities/flattenTopLevelFields.js'
 export { formatAdminURL } from '../utilities/formatAdminURL.js'
 export { formatLabels, toWords } from '../utilities/formatLabels.js'
-export { getBestFitFromSizes } from '../utilities/getBestFitFromSizes.js'
 
+export { getBestFitFromSizes } from '../utilities/getBestFitFromSizes.js'
 export { getDataByPath } from '../utilities/getDataByPath.js'
 export { getFieldPermissions } from '../utilities/getFieldPermissions.js'
 export { getObjectDotNotation } from '../utilities/getObjectDotNotation.js'
+
 export { getSafeRedirect } from '../utilities/getSafeRedirect.js'
 
 export { getSelectMode } from '../utilities/getSelectMode.js'

packages/payload/src/fields/baseFields/slug/generateSlug.ts

@@ -1,33 +1,53 @@
+import type { PayloadRequest } from '../../../types/index.js'
 import type { FieldHook } from '../../config/types.js'
+import type { SlugFieldArgs, Slugify } from './index.js'
 
-import { slugify } from '../../../utilities/slugify.js'
+import { slugify as defaultSlugify } from '../../../utilities/slugify.js'
 import { countVersions } from './countVersions.js'
 
 type HookArgs = {
-  /**
-   * Current field name for the slug. Defaults to `slug`.
-   */
-  fieldName?: string
-  fieldToUse: string
+  slugFieldName: NonNullable<SlugFieldArgs['name']>
+} & Pick<SlugFieldArgs, 'slugify'> &
+  Required<Pick<SlugFieldArgs, 'useAsSlug'>>
+
+const slugify = ({
+  customSlugify,
+  data,
+  req,
+  valueToSlugify,
+}: {
+  customSlugify?: Slugify
+  data: Record<string, unknown>
+  req: PayloadRequest
+  valueToSlugify?: string
+}) => {
+  if (customSlugify) {
+    return customSlugify({ data, req, valueToSlugify })
+  }
+
+  return defaultSlugify(valueToSlugify)
 }
 
 /**
  * This is a `BeforeChange` field hook used to auto-generate the `slug` field.
  * See `slugField` for more details.
  */
 export const generateSlug =
-  ({ fieldName = 'slug', fieldToUse }: HookArgs): FieldHook =>
-  async (args) => {
-    const { collection, data, global, operation, originalDoc, req, value: isChecked } = args
-
-    // Ensure user-defined slugs are not overwritten during create
-    // Use a generic falsy check here to include empty strings
+  ({ slugFieldName, slugify: customSlugify, useAsSlug }: HookArgs): FieldHook =>
+  async ({ collection, data, global, operation, originalDoc, req, value: isChecked }) => {
     if (operation === 'create') {
       if (data) {
-        data[fieldName] = slugify(data?.[fieldName] || data?.[fieldToUse])
+        data[slugFieldName] = slugify({
+          customSlugify,
+          data,
+          req,
+          // Ensure user-defined slugs are not overwritten during create
+          // Use a generic falsy check here to include empty strings
+          valueToSlugify: data?.[slugFieldName] || data?.[useAsSlug],
+        })
       }
 
-      return Boolean(!data?.[fieldName])
+      return Boolean(!data?.[slugFieldName])
     }
 
     if (operation === 'update') {
@@ -45,22 +65,34 @@ export const generateSlug =
       if (!autosaveEnabled) {
         // We can generate the slug at this point
         if (data) {
-          data[fieldName] = slugify(data?.[fieldToUse])
+          data[slugFieldName] = slugify({
+            customSlugify,
+            data,
+            req,
+            valueToSlugify: data?.[useAsSlug],
+          })
         }
 
-        return Boolean(!data?.[fieldName])
+        return Boolean(!data?.[slugFieldName])
       } else {
         // If we're publishing, we can avoid querying as we can safely assume we've exceeded the version threshold (2)
         const isPublishing = data?._status === 'published'
 
         // Ensure the user can take over the generated slug themselves without it ever being overridden back
-        const userOverride = data?.[fieldName] !== originalDoc?.[fieldName]
+        const userOverride = data?.[slugFieldName] !== originalDoc?.[slugFieldName]
 
         if (!userOverride) {
           if (data) {
             // If the fallback is an empty string, we want the slug to return to `null`
             // This will ensure that live preview conditions continue to run as expected
-            data[fieldName] = data?.[fieldToUse] ? slugify(data[fieldToUse]) : null
+            data[slugFieldName] = data?.[useAsSlug]
+              ? slugify({
+                  customSlugify,
+                  data,
+                  req,
+                  valueToSlugify: data?.[useAsSlug],
+                })
+              : null
           }
         }
 
@@ -74,7 +106,7 @@ export const generateSlug =
           collectionSlug: collection?.slug,
           globalSlug: global?.slug,
           parentID: originalDoc?.id,
-          req: args.req,
+          req,
         })
 
         if (versionCount <= 2) {