payload 1.13.4 → 1.14.0

package/dist/versions/types.d.ts

@@ -1,32 +1,32 @@
-export type Autosave = {
-    interval?: number;
-};
-export type IncomingDrafts = {
-    autosave?: boolean | Autosave;
-};
-export type SanitizedDrafts = {
-    autosave: false | Autosave;
-};
-export type IncomingCollectionVersions = {
-    maxPerDoc?: number;
-    drafts?: boolean | IncomingDrafts;
-};
-export interface SanitizedCollectionVersions extends Omit<IncomingCollectionVersions, 'drafts'> {
-    maxPerDoc?: number;
-    drafts: SanitizedDrafts | false;
-}
-export type IncomingGlobalVersions = {
-    max?: number;
-    drafts?: boolean | IncomingDrafts;
-};
-export type SanitizedGlobalVersions = {
-    max: number;
-    drafts: SanitizedDrafts | false;
-};
-export type TypeWithVersion<T> = {
-    id: string;
-    parent: string | number;
-    version: T;
-    createdAt: string;
-    updatedAt: string;
-};
+export type Autosave = {
+    interval?: number;
+};
+export type IncomingDrafts = {
+    autosave?: boolean | Autosave;
+};
+export type SanitizedDrafts = {
+    autosave: false | Autosave;
+};
+export type IncomingCollectionVersions = {
+    maxPerDoc?: number;
+    drafts?: boolean | IncomingDrafts;
+};
+export interface SanitizedCollectionVersions extends Omit<IncomingCollectionVersions, 'drafts'> {
+    maxPerDoc?: number;
+    drafts: SanitizedDrafts | false;
+}
+export type IncomingGlobalVersions = {
+    max?: number;
+    drafts?: boolean | IncomingDrafts;
+};
+export type SanitizedGlobalVersions = {
+    max: number;
+    drafts: SanitizedDrafts | false;
+};
+export type TypeWithVersion<T> = {
+    id: string;
+    parent: string | number;
+    version: T;
+    createdAt: string;
+    updatedAt: string;
+};

package/dist/versions/types.js

@@ -1,3 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=types.js.map

package/docs/configuration/overview.mdx

@@ -126,22 +126,32 @@ project-name
   here](/docs/admin/webpack#admin-environment-vars) for more info.
 </Banner>
 
-### Customizing & overriding the config location
+### Customizing & Automating Config Location Detection
 
-By default, the Payload config must be in the root of your current working directory and named either `payload.config.js` or `payload.config.ts` if you're using TypeScript.
+Payload is designed to automatically locate your configuration file. By default, it will first look in the root of your current working directory for a file named `payload.config.js` or `payload.config.ts` if you're using TypeScript.
 
-But, you can specify where your Payload config is located as well as what it's named by using the environment variable `PAYLOAD_CONFIG_PATH`. The path you provide via this environment variable can either be absolute or relative to your current working directory.
+In development mode, if the configuration file is not found at the root, Payload will attempt to read your `tsconfig.json`, and search in the directory specified in `compilerOptions.rootDir` (typically "src").
+
+In production mode, Payload will first attempt to find the config file in the output directory specified in `compilerOptions.outDir` of your `tsconfig.json`, then fallback to the source directory (`compilerOptions.rootDir`), and finally will check the 'dist' directory.
+
+Please ensure your `tsconfig.json` is properly configured if you want Payload to accurately auto-detect your configuration file location. If `tsconfig.json` does not exist or doesn't specify `rootDir` or `outDir`, Payload will default to the current working directory.
+
+#### Overriding the Config Location
+
+In addition to the above automated detection, you can specify your own location for the Payload config file. This is done by using the environment variable `PAYLOAD_CONFIG_PATH`. The path you provide via this environment variable can either be absolute or relative to your current working directory. This can be useful in situations where your Payload config is not in a standard location, or you wish to switch between multiple configurations.
 
 **Example in package.json:**
 
-```
+```json
 {
-	"scripts": {
-		"dev": "PAYLOAD_CONFIG_PATH=path/to/custom-config.js node server.js",
-	}
+  "scripts": {
+    "dev": "PAYLOAD_CONFIG_PATH=path/to/custom-config.js node server.js",
+  }
 }
 ```
 
+When `PAYLOAD_CONFIG_PATH` is set, Payload will use this path to load the configuration, bypassing all automated detection.
+
 ### Developing within the Config
 
 Payload comes with `isomorphic-fetch` installed which means that even in Node, you can use the `fetch` API just as you would within the browser. No need to import `axios` or similar, unless you want to!

package/docs/fields/relationship.mdx

@@ -74,7 +74,7 @@ Set to `false` if you'd like to disable the ability to create new documents from
 
 Options can be dynamically limited by supplying a [query constraint](/docs/queries/overview), which will be used both for validating input and filtering available relationships in the UI.
 
-The `filterOptions` property can either be a `Where` query directly, or a function that returns one. When using a function, it will be called with an argument object with the following properties:
+The `filterOptions` property can either be a `Where` query directly, or a function (synchronous or asynchronous) that returns one. When using a function, it will be called with an argument object containing the following properties:
 
 | Property      | Description                                                                          |
 | ------------- | ------------------------------------------------------------------------------------ |

package/docs/fields/rich-text.mdx

@@ -6,7 +6,7 @@ desc: The Rich Text field allows dynamic content to be written through the Admin
 keywords: rich text, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
 ---
 
-<Banner >
+<Banner>
   The Rich Text field is a powerful way to allow editors to write dynamic content. The content is saved as JSON in the database and can be converted into any format, including HTML, that you need.
 </Banner>
 
@@ -25,22 +25,22 @@ The Admin component is built on the powerful [`slatejs`](https://docs.slatejs.or
 
 ### Config
 
-| Option           | Description |
-| ---------------- | ----------- |
-| **`name`** *         | To be used as the property name when stored and retrieved from the database. [More](/docs/fields/overview#field-names) |
-| **`label`**          | Text used as a field label in the Admin panel or an object with keys for each language. |
-| **`validate`**       | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |
-| **`saveToJWT`**      | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT. |
-| **`hooks`**          | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks) |
-| **`access`**         | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
-| **`hidden`**         | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel. |
-| **`defaultValue`**   | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values) |
-| **`localized`**      | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config. |
-| **`required`**       | Require this field to have a value. |
-| **`admin`**          | Admin-specific configuration. See below for [more detail](#admin-config). |
-| **`custom`**         | Extension point for adding custom data (e.g. for plugins) |
-
-*\* An asterisk denotes that a property is required.*
+| Option             | Description                                                                                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`name`** \*      | To be used as the property name when stored and retrieved from the database. [More](/docs/fields/overview#field-names)                                  |
+| **`label`**        | Text used as a field label in the Admin panel or an object with keys for each language.                                                                 |
+| **`validate`**     | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation)            |
+| **`saveToJWT`**    | If this field is top-level and nested in a config supporting [Authentication](/docs/authentication/config), include its data in the user JWT.           |
+| **`hooks`**        | Provide field-based hooks to control logic for this field. [More](/docs/fields/overview#field-level-hooks)                                              |
+| **`access`**       | Provide field-based access control to denote what users can see and do with this field's data. [More](/docs/fields/overview#field-level-access-control) |
+| **`hidden`**       | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel.        |
+| **`defaultValue`** | Provide data to be used for this field's default value. [More](/docs/fields/overview#default-values)                                                    |
+| **`localized`**    | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config.                         |
+| **`required`**     | Require this field to have a value.                                                                                                                     |
+| **`admin`**        | Admin-specific configuration. See below for [more detail](#admin-config).                                                                               |
+| **`custom`**       | Extension point for adding custom data (e.g. for plugins)                                                                                               |
+
+_\* An asterisk denotes that a property is required._
 
 ### Admin config
 
@@ -66,9 +66,11 @@ The default `elements` available in Payload are:
 - `link`
 - `ol`
 - `ul`
+- `textAlign`
 - `indent`
 - [`relationship`](#relationship-element)
 - [`upload`](#upload-element)
+- [`textAlign`](#text-align)
 
 **`leaves`**
 
@@ -93,17 +95,17 @@ This allows [fields](/docs/fields/overview) to be saved as extra fields on a lin
 `link.fields` may either be an array of fields (in which case all fields defined in it will be appended below the default fields) or a function that accepts the default fields as only argument and returns an array defining the entirety of fields to be used (thus providing a mechanism of overriding the default fields).
 
 ![RichText link fields](https://payloadcms.com/images/docs/fields/richText/rte-link-fields-modal.jpg)
-*RichText link with custom fields*
+_RichText link with custom fields_
 
 **`upload.collections[collection-name].fields`**
 
 This allows [fields](/docs/fields/overview) to be saved as meta data on an upload field inside the Rich Text Editor. When this is present, the fields will render inside a modal that can be opened by clicking the "edit" button on the upload element.
 
 ![RichText upload element](https://payloadcms.com/images/docs/fields/richText/rte-upload-element.jpg)
-*RichText field using the upload element*
+_RichText field using the upload element_
 
 ![RichText upload element modal](https://payloadcms.com/images/docs/fields/richText/rte-upload-fields-modal.jpg)
-*RichText upload element modal displaying fields from the config*
+_RichText upload element modal displaying fields from the config_
 
 ### Relationship element
 
@@ -114,12 +116,15 @@ The built-in `relationship` element is a powerful way to reference other Documen
 Similar to the `relationship` element, the `upload` element is a user-friendly way to reference [Upload-enabled collections](/docs/upload/overview) with a UI specifically designed for media / image-based uploads.
 
 <Banner type="success">
-  <strong>Tip:</strong><br/>
-  Collections are automatically allowed to be selected within the Rich Text relationship and upload elements by default. If you want to disable a collection from being able to be referenced in Rich Text fields, set the collection admin options of <strong>enableRichTextLink</strong> and <strong>enableRichTextRelationship</strong> to false.
+  <strong>Tip:</strong><br />Collections are automatically allowed to be selected within the Rich Text relationship and upload elements by default. If you want to disable a collection from being able to be referenced in Rich Text fields, set the collection admin options of <strong>enableRichTextLink</strong> and <strong>enableRichTextRelationship</strong> to false.
 </Banner>
 
 Relationship and Upload elements are populated dynamically into your Rich Text field' content. Within the REST and Local APIs, any present RichText `relationship` or `upload` elements will respect the `depth` option that you pass, and will be populated accordingly. In GraphQL, each `richText` field accepts an argument of `depth` for you to utilize.
 
+### TextAlign element
+
+Text Alignment is not included by default and can be added to a Rich Text Editor by adding `textAlign` to the list of elements. TextAlign will alter the existing element to include a new `textAlign` field in the resulting JSON. This field can be used in combination with other elements and leaves to position content to the left, center or right.
+
 ### Specifying which elements and leaves to allow
 
 To specify which default elements or leaves should be allowed to be used for this field, define arrays that contain string names for each element or leaf you wish to enable. To specify a custom element or leaf, pass an object with all corresponding properties as outlined below. View the [example](#example) to reference how this all works.
@@ -132,71 +137,75 @@ Once you're up to speed with the general concepts involved, you can pass in your
 
 **Both custom elements and leaves are defined via the following config:**
 
-| Property         | Description |
-| ---------------- | ----------- |
-| **`name`** *     | The name to be used as a `type` for this element.  |
-| **`Button`** *   | A React component to be rendered in the Rich Text toolbar. |
-| **`plugins`**    | An array of plugins to provide to the Rich Text editor. |
+| Property        | Description                                                |
+| --------------- | ---------------------------------------------------------- |
+| **`name`** \*   | The default name to be used as a `type` for this element.  |
+| **`Button`** \* | A React component to be rendered in the Rich Text toolbar. |
+| **`plugins`**   | An array of plugins to provide to the Rich Text editor.    |
+| **`type`**      | A type that overrides the default type used by `name`      |
 
 Custom `Element`s also require the `Element` property set to a React component to be rendered as the `Element` within the rich text editor itself.
 
 Custom `Leaf` objects follow a similar pattern but require you to define the `Leaf` property instead.
 
+Specifying custom `Type`s let you extend your custom elements by adding additional fields to your JSON object.
+
 ### Example
 
 `collections/ExampleCollection.ts`
+
 ```ts
-import { CollectionConfig } from 'payload/types';
+import { CollectionConfig } from "payload/types";
 
 export const ExampleCollection: CollectionConfig = {
-  slug: 'example-collection',
+  slug: "example-collection",
   fields: [
     {
-      name: 'content', // required
-      type: 'richText', // required
-      defaultValue: [{
-        children: [{ text: 'Here is some default content for this field' }],
-      }],
+      name: "content", // required
+      type: "richText", // required
+      defaultValue: [
+        {
+          children: [{ text: "Here is some default content for this field" }],
+        },
+      ],
       required: true,
       admin: {
         elements: [
-          'h2',
-          'h3',
-          'h4',
-          'link',
-          'blockquote',
+          "h2",
+          "h3",
+          "h4",
+          "link",
+          "blockquote",
           {
-            name: 'cta',
+            name: "cta",
             Button: CustomCallToActionButton,
             Element: CustomCallToActionElement,
             plugins: [
               // any plugins that are required by this element go here
-            ]
-          }
+            ],
+          },
         ],
         leaves: [
-          'bold',
-          'italic',
+          "bold",
+          "italic",
           {
-            name: 'highlight',
+            name: "highlight",
             Button: CustomHighlightButton,
             Leaf: CustomHighlightLeaf,
             plugins: [
               // any plugins that are required by this leaf go here
-            ]
-          }
+            ],
+          },
         ],
         link: {
           // Inject your own fields into the Link element
           fields: [
             {
-              name: 'rel',
-              label: 'Rel Attribute',
-              type: 'select',
+              name: "rel",
+              label: "Rel Attribute",
+              type: "select",
               hasMany: true,
-              options: [
-                'noopener', 'noreferrer', 'nofollow',
-              ],
+              options: ["noopener", "noreferrer", "nofollow"],
             },
           ],
         },
@@ -210,9 +219,9 @@ export const ExampleCollection: CollectionConfig = {
             },
           },
         },
-      }
-    }
-  ]
+      },
+    },
+  ],
 };
 ```
 
@@ -223,112 +232,67 @@ For more examples regarding how to define your own elements and leaves, check ou
 As the Rich Text field saves its content in a JSON format, you'll need to render it as HTML yourself. Here is an example for how to generate JSX / HTML from Rich Text content:
 
 ```ts
-import React, { Fragment } from 'react';
-import escapeHTML from 'escape-html';
-import { Text } from 'slate';
-
-const serialize = (children) => children.map((node, i) => {
-  if (Text.isText(node)) {
-    let text = <span dangerouslySetInnerHTML={{ __html: escapeHTML(node.text) }} />;
-
-    if (node.bold) {
-      text = (
-        <strong key={i}>
-          {text}
-        </strong>
+import React, { Fragment } from "react";
+import escapeHTML from "escape-html";
+import { Text } from "slate";
+
+const serialize = (children) =>
+  children.map((node, i) => {
+    if (Text.isText(node)) {
+      let text = (
+        <span dangerouslySetInnerHTML={{ __html: escapeHTML(node.text) }} />
       );
-    }
 
-    if (node.code) {
-      text = (
-        <code key={i}>
-          {text}
-        </code>
-      );
-    }
+      if (node.bold) {
+        text = <strong key={i}>{text}</strong>;
+      }
 
-    if (node.italic) {
-      text = (
-        <em key={i}>
-          {text}
-        </em>
-      );
+      if (node.code) {
+        text = <code key={i}>{text}</code>;
+      }
+
+      if (node.italic) {
+        text = <em key={i}>{text}</em>;
+      }
+
+      // Handle other leaf types here...
+
+      return <Fragment key={i}>{text}</Fragment>;
     }
 
-    // Handle other leaf types here...
-
-    return (
-      <Fragment key={i}>
-        {text}
-      </Fragment>
-    );
-  }
-
-  if (!node) {
-    return null;
-  }
-
-  switch (node.type) {
-    case 'h1':
-      return (
-        <h1 key={i}>
-          {serialize(node.children)}
-        </h1>
-      );
-    // Iterate through all headings here...
-    case 'h6':
-      return (
-        <h6 key={i}>
-          {serialize(node.children)}
-        </h6>
-      );
-    case 'blockquote':
-      return (
-        <blockquote key={i}>
-          {serialize(node.children)}
-        </blockquote>
-      );
-    case 'ul':
-      return (
-        <ul key={i}>
-          {serialize(node.children)}
-        </ul>
-      );
-    case 'ol':
-      return (
-        <ol key={i}>
-          {serialize(node.children)}
-        </ol>
-      );
-    case 'li':
-      return (
-        <li key={i}>
-          {serialize(node.children)}
-        </li>
-      );
-    case 'link':
-      return (
-        <a
-          href={escapeHTML(node.url)}
-          key={i}
-        >
-          {serialize(node.children)}
-        </a>
-      );
+    if (!node) {
+      return null;
+    }
 
-    default:
-      return (
-        <p key={i}>
-          {serialize(node.children)}
-        </p>
-      );
-  }
-});
+    switch (node.type) {
+      case "h1":
+        return <h1 key={i}>{serialize(node.children)}</h1>;
+      // Iterate through all headings here...
+      case "h6":
+        return <h6 key={i}>{serialize(node.children)}</h6>;
+      case "blockquote":
+        return <blockquote key={i}>{serialize(node.children)}</blockquote>;
+      case "ul":
+        return <ul key={i}>{serialize(node.children)}</ul>;
+      case "ol":
+        return <ol key={i}>{serialize(node.children)}</ol>;
+      case "li":
+        return <li key={i}>{serialize(node.children)}</li>;
+      case "link":
+        return (
+          <a href={escapeHTML(node.url)} key={i}>
+            {serialize(node.children)}
+          </a>
+        );
+
+      default:
+        return <p key={i}>{serialize(node.children)}</p>;
+    }
+  });
 ```
 
 <Banner>
-  <strong>Note:</strong><br/>
-   The above example is for how to render to JSX, although for plain HTML the pattern is similar. Just remove the JSX and return HTML strings instead!
+  <strong>Note:</strong><br />The above example is for how to render to JSX, although for plain HTML the pattern is similar. Just remove the JSX and return HTML strings instead!
 </Banner>
 
 ### Built-in SlateJS Plugins
@@ -344,12 +308,12 @@ If you want to utilize this functionality within your own custom elements, you c
 `customLargeBodyElement.js`:
 
 ```ts
-import Button from './Button';
-import Element from './Element';
-import withLargeBody from './plugin';
+import Button from "./Button";
+import Element from "./Element";
+import withLargeBody from "./plugin";
 
 export default {
-  name: 'large-body',
+  name: "large-body",
   Button,
   Element,
   plugins: [
@@ -357,10 +321,11 @@ export default {
       const editor = incomingEditor;
       const { shouldBreakOutOnEnter } = editor;
 
-      editor.shouldBreakOutOnEnter = (element) => (element.type === 'large-body' ? true : shouldBreakOutOnEnter(element));
+      editor.shouldBreakOutOnEnter = (element) =>
+        element.type === "large-body" ? true : shouldBreakOutOnEnter(element);
 
       return editor;
-    }
+    },
   ],
 };
 ```
@@ -374,8 +339,5 @@ The plugin itself extends Payload's built-in `shouldBreakOutOnEnter` Slate funct
 If you are building your own custom Rich Text elements or leaves, you may benefit from importing the following types:
 
 ```ts
-import type {
-  RichTextCustomElement,
-  RichTextCustomLeaf,
-} from 'payload/types';
+import type { RichTextCustomElement, RichTextCustomLeaf } from "payload/types";
 ```