feat: slug field

docs/fields/collapsible.mdx

@@ -66,8 +66,6 @@ The Collapsible Field inherits all of the default admin options from the base [F
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/date.mdx

@@ -96,8 +96,6 @@ When only `pickerAppearance` is set, an equivalent format will be rendered in th
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/email.mdx

@@ -74,8 +74,6 @@ The Email Field inherits all of the default admin options from the base [Field A
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/group.mdx

@@ -77,8 +77,6 @@ The Group Field inherits all of the default admin options from the base [Field A
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/json.mdx

@@ -75,8 +75,6 @@ The JSON Field inherits all of the default admin options from the base [Field Ad
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/number.mdx

@@ -80,8 +80,6 @@ The Number Field inherits all of the default admin options from the base [Field
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/point.mdx

@@ -55,8 +55,6 @@ _\* An asterisk denotes that a property is required._
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/radio.mdx

@@ -90,8 +90,6 @@ The Radio Field inherits all of the default admin options from the base [Field A
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/row.mdx

@@ -43,8 +43,6 @@ _\* An asterisk denotes that a property is required._
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/select.mdx

@@ -149,8 +149,6 @@ The Select Field inherits all of the default admin options from the base [Field
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/tabs.mdx

@@ -56,8 +56,6 @@ _\* An asterisk denotes that a property is required._
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/text.mdx

@@ -80,8 +80,6 @@ The Text Field inherits all of the default admin options from the base [Field Ad
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 
@@ -183,3 +181,66 @@ export const CustomTextFieldLabelClient: TextFieldLabelClientComponent = ({
   )
 }
 ```
+
+## Slug Field
+
+<Banner type="warning">
+  The slug field is experimental and may change, or even be removed, in future
+  releases. Use at your own risk.
+</Banner>
+
+One common use case for the Text Field is to create a "slug" for a document. A slug is a unique, indexed, URL-friendly string that identifies a particular document, often used to construct the URL of a webpage.
+
+Payload provides a built-in Slug Field so you don't have to built one from scratch. This field automatically generates a slug based on the value of another field, such as a title or name field. It provides UI to lock and unlock the field to protect its value, as well as to re-generate the slug on-demand.
+
+To add a Slug Field, import the `slugField` into your field schema:
+
+```ts
+import { slugField } from 'payload'
+import type { CollectionConfig } from 'payload'
+
+export const ExampleCollection: CollectionConfig = {
+  // ...
+  fields: [
+    // ...
+    // highlight-line
+    slugField(),
+    // highlight-line
+  ],
+}
+```
+
+The slug field exposes a few top-level config options for easy customization:
+
+| Option         | Description                                                                                                                               |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `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`.                 |
+| `position`     | The position of the slug field. [More details](./overview#admin-options).                                                                 |
+| `required`     | Require the slug field. Defaults to `true`.                                                                                               |
+
+### Slug Overrides
+
+If the above options aren't sufficient for your use case, you can use the `overrides` function to customize the slug field at a granular level. The `overrides` function receives the default fields that make up the slug field, and you can modify them to any extent you need.
+
+```ts
+import { slugField } from 'payload'
+import type { CollectionConfig } from 'payload'
+
+export const ExampleCollection: CollectionConfig = {
+  // ...
+  fields: [
+    // ...
+    // highlight-line
+    slugField({
+      overrides: (defaultField) => {
+        defaultField.fields[1].label = 'Custom Slug Label'
+        return defaultField
+      },
+    }),
+    // highlight-line
+  ],
+}
+```

docs/fields/textarea.mdx

@@ -78,8 +78,6 @@ The Textarea Field inherits all of the default admin options from the base [Fiel
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/ui.mdx

@@ -41,8 +41,6 @@ _\* An asterisk denotes that a property is required._
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/fields/upload.mdx

@@ -75,8 +75,6 @@ _\* An asterisk denotes that a property is required._
 
 ## Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/rich-text/slate.mdx

@@ -170,8 +170,6 @@ Specifying custom `Type`s let you extend your custom elements by adding addition
 
 ### Example
 
-`collections/ExampleCollection.ts`
-
 ```ts
 import type { CollectionConfig } from 'payload'
 

docs/versions/overview.mdx

@@ -28,7 +28,7 @@ _Comparing an old version to a newer version of a document_
 <Banner type="success">
   Versions are extremely performant and totally opt-in. They don't change the
   shape of your data at all. All versions are stored in a separate Collection
-  and can be turned on and off easily at your discretion.
+  and can be turned on and off easily at your risk.
 </Banner>
 
 ## Options

packages/payload/src/admin/forms/Form.ts

@@ -67,7 +67,7 @@ export type FieldState = {
    * Every time a field is changed locally, this flag is set to true. Prevents form state from server from overwriting local changes.
    * After merging server form state, this flag is reset.
    *
-   * @experimental This property is experimental and may change in the future. Use at your own discretion.
+   * @experimental This property is experimental and may change in the future. Use at your own risk.
    */
   isModified?: boolean
   /**
@@ -149,7 +149,7 @@ export type BuildFormStateArgs = {
    * This will retrieve the client config in its entirety, even when unauthenticated.
    * For example, the create-first-user view needs the entire config, but there is no user yet.
    *
-   * @experimental This property is experimental and may change in the future. Use at your own discretion.
+   * @experimental This property is experimental and may change in the future. Use at your own risk.
    */
   skipClientConfigAuth?: boolean
   skipValidation?: boolean

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

@@ -391,7 +391,7 @@ export type CollectionAdminOptions = {
    * If your cells require specific fields that may be unselected, such as within hooks, etc.,
    * use `forceSelect` in conjunction with this property.
    *
-   * @experimental This is an experimental feature and may change in the future. Use at your own discretion.
+   * @experimental This is an experimental feature and may change in the future. Use at your own risk.
    */
   enableListViewSelectAPI?: boolean
   enableRichTextLink?: boolean
@@ -428,7 +428,7 @@ export type CollectionAdminOptions = {
    * @description Enable grouping by a field in the list view.
    * Uses `payload.findDistinct` under the hood to populate the group-by options.
    *
-   * @experimental This option is currently in beta and may change in future releases. Use at your own discretion.
+   * @experimental This option is currently in beta and may change in future releases. Use at your own risk.
    */
   groupBy?: boolean
   /**

packages/payload/src/config/types.ts

@@ -963,7 +963,7 @@ export type Config = {
      * Configure toast message behavior and appearance in the admin panel.
      * Currently using [Sonner](https://sonner.emilkowal.ski) for toast notifications.
      *
-     * @experimental This property is experimental and may change in future releases. Use at your own discretion.
+     * @experimental This property is experimental and may change in future releases. Use at your own risk.
      */
     toast?: {
       /**
@@ -1006,7 +1006,7 @@ export type Config = {
    * For example, you may want to increase the `limits` imposed by the parser.
    * Currently using @link {https://www.npmjs.com/package/busboy|busboy} under the hood.
    *
-   * @experimental This property is experimental and may change in future releases. Use at your own discretion.
+   * @experimental This property is experimental and may change in future releases. Use at your own risk.
    */
   bodyParser?: Partial<BusboyConfig>
   /**

packages/payload/src/exports/shared.ts

@@ -79,12 +79,11 @@ 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 { getDataByPath } from '../utilities/getDataByPath.js'
 export { getFieldPermissions } from '../utilities/getFieldPermissions.js'
-
 export { getSafeRedirect } from '../utilities/getSafeRedirect.js'
 
 export { getSelectMode } from '../utilities/getSelectMode.js'
@@ -116,6 +115,8 @@ export { sanitizeUserDataForEmail } from '../utilities/sanitizeUserDataForEmail.
 
 export { setsAreEqual } from '../utilities/setsAreEqual.js'
 
+export { slugify } from '../utilities/slugify.js'
+
 export { toKebabCase } from '../utilities/toKebabCase.js'
 
 export {

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

@@ -0,0 +1,51 @@
+import type {
+  CollectionSlug,
+  DefaultDocumentIDType,
+  GlobalSlug,
+  PayloadRequest,
+  Where,
+} from '../../../index.js'
+
+/**
+ * This is a cross-entity way to count the number of versions for any given document.
+ * It will work for both collections and globals.
+ * @returns number of versions
+ */
+export const countVersions = async (args: {
+  collectionSlug?: CollectionSlug
+  globalSlug?: GlobalSlug
+  parentID?: DefaultDocumentIDType
+  req: PayloadRequest
+}): Promise<number> => {
+  const { collectionSlug, globalSlug, parentID, req } = args
+
+  let countFn
+
+  const where: Where = {
+    parent: {
+      equals: parentID,
+    },
+  }
+
+  if (collectionSlug) {
+    countFn = () =>
+      req.payload.countVersions({
+        collection: collectionSlug,
+        depth: 0,
+        where,
+      })
+  }
+
+  if (globalSlug) {
+    countFn = () =>
+      req.payload.countGlobalVersions({
+        depth: 0,
+        global: globalSlug,
+        where,
+      })
+  }
+
+  const res = countFn ? (await countFn()?.then((res) => res.totalDocs || 0)) || 0 : 0
+
+  return res
+}