feat: conditional blocks (#13801)

This PR introduces support for conditionally setting allowable block
types via a new `field.filterOptions` property on the blocks field.

Closes the following feature requests:
#5348,
#4668 (partly)

## Example

```ts
fields: [
  {
      name: 'enabledBlocks',
      type: 'text',
      admin: {
        description:
          "Change the value of this field to change the enabled blocks of the blocksWithDynamicFilterOptions field. If it's empty, all blocks are enabled.",
      },
    },
    {
      name: 'blocksWithFilterOptions',
      type: 'blocks',
      filterOptions: ['block1', 'block2'],
      blocks: [
        {
          slug: 'block1',
          fields: [
            {
              type: 'text',
              name: 'block1Text',
            },
          ],
        },
        {
          slug: 'block2',
          fields: [
            {
              type: 'text',
              name: 'block2Text',
            },
          ],
        },
        {
          slug: 'block3',
          fields: [
            {
              type: 'text',
              name: 'block3Text',
            },
          ],
        },
      ],
    },
    {
      name: 'blocksWithDynamicFilterOptions',
      type: 'blocks',
      filterOptions: ({ siblingData: _siblingData, data }) => {
        const siblingData = _siblingData as { enabledBlocks: string }

        if (siblingData?.enabledBlocks !== data?.enabledBlocks) {
          // Just an extra assurance that the field is working as intended
          throw new Error('enabledBlocks and siblingData.enabledBlocks must be identical')
        }
        return siblingData?.enabledBlocks?.length ? [siblingData.enabledBlocks] : true
      },
      blocks: [
        {
          slug: 'block1',
          fields: [
            {
              type: 'text',
              name: 'block1Text',
            },
          ],
        },
        {
          slug: 'block2',
          fields: [
            {
              type: 'text',
              name: 'block2Text',
            },
          ],
        },
        {
          slug: 'block3',
          fields: [
            {
              type: 'text',
              name: 'block3Text',
            },
          ],
        },
      ],
    },
]
```


https://github.com/user-attachments/assets/e38a804f-22fa-4fd2-a6af-ba9b0a5a04d2

# Rationale

## Why not `block.condition`?

- Individual blocks are often reused in multiple contexts, where the
logic for when they should be available may differ. It’s more
appropriate for the blocks field (typically tied to a single collection)
to determine availability.
- Hiding existing blocks when they no longer satisfy a condition would
cause issues - for example, reordering blocks would break or cause block
data to disappear. Instead, this implementation ensures consistency by
throwing a validation error if a block is no longer allowed. This aligns
with the behavior of `filterOptions` in relationship fields, rather than
`condition`.

## Why not call it `blocksFilterOptions`?

Although the type differs from relationship fields, this property is
named `filterOptions` (and not `blocksFilterOptions`) for consistency
across field types. For example, the Select field also uses
`filterOptions` despite its type being unique.

---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1211334752795631

Author: AlessioGr

docs/fields/blocks.mdx

@@ -389,3 +389,34 @@ As you build your own Block configs, you might want to store them in separate fi
 ```ts
 import type { Block } from 'payload'
 ```
+
+## Conditional Blocks
+
+Blocks can be conditionally enabled using the `filterOptions` property on the blocks field. It allows you to provide a function that returns which block slugs should be available based on the given context.
+
+### Behavior
+
+- `filterOptions` is re-evaluated as part of the form state request, whenever the document data changes.
+- If a block is present in the field but no longer allowed by `filterOptions`, a validation error will occur when saving.
+
+### Example
+
+```ts
+{
+  name: 'blocksWithDynamicFilterOptions',
+  type: 'blocks',
+  filterOptions: ({ siblingData }) => {
+    return siblingData?.enabledBlocks?.length
+      ? [siblingData.enabledBlocks] // allow only the matching block
+      : true // allow all blocks if no value is set
+  },
+  blocks: [
+    { slug: 'block1', fields: [{ type: 'text', name: 'block1Text' }] },
+    { slug: 'block2', fields: [{ type: 'text', name: 'block2Text' }] },
+    { slug: 'block3', fields: [{ type: 'text', name: 'block3Text' }] },
+    // ...
+  ],
+}
+```
+
+In this example, the list of available blocks is determined by the enabledBlocks sibling field. If no value is set, all blocks remain available.

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

@@ -34,6 +34,12 @@ export type FieldState = {
    * See `mergeServerFormState` for more details.
    */
   addedByServer?: boolean
+  /**
+   * If the field is a `blocks` field, this will contain the slugs of blocks that are allowed, based on the result of `field.filterOptions`.
+   * If this is undefined, all blocks are allowed.
+   * If this is an empty array, no blocks are allowed.
+   */
+  blocksFilterOptions?: string[]
   customComponents?: {
     /**
      * This is used by UI fields, as they can have arbitrary components defined if used

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

@@ -323,10 +323,22 @@ export type FilterOptionsFunc<TData = any> = (
   options: FilterOptionsProps<TData>,
 ) => boolean | Promise<boolean | Where> | Where
 
-export type FilterOptions<TData = any> =
-  | ((options: FilterOptionsProps<TData>) => boolean | Promise<boolean | Where> | Where)
-  | null
-  | Where
+export type FilterOptions<TData = any> = FilterOptionsFunc<TData> | null | Where
+
+type BlockSlugOrString = (({} & string) | BlockSlug)[]
+
+export type BlocksFilterOptionsProps<TData = any> = {
+  /**
+   * The `id` of the current document being edited. Will be undefined during the `create` operation.
+   */
+  id: number | string
+} & Pick<FilterOptionsProps<TData>, 'data' | 'req' | 'siblingData' | 'user'>
+
+export type BlocksFilterOptions<TData = any> =
+  | ((
+      options: BlocksFilterOptionsProps<TData>,
+    ) => BlockSlugOrString | Promise<BlockSlugOrString | true> | true)
+  | BlockSlugOrString
 
 type Admin = {
   className?: string
@@ -1515,6 +1527,36 @@ export type BlocksField = {
   blockReferences?: (Block | BlockSlug)[]
   blocks: Block[]
   defaultValue?: DefaultValue
+  /**
+   * Blocks can be conditionally enabled using the `filterOptions` property on the blocks field.
+   * It allows you to provide a function that returns which block slugs should be available based on the given context.
+   *
+   * @behavior
+   *
+   * - `filterOptions` is re-evaluated as part of the form state request, whenever the document data changes.
+   * - If a block is present in the field but no longer allowed by `filterOptions`, a validation error will occur when saving.
+   *
+   * @example
+   *
+   * ```ts
+   * {
+   *   name: 'blocksWithDynamicFilterOptions',
+   *   type: 'blocks',
+   *   filterOptions: ({ siblingData }) => {
+   *     return siblingData?.enabledBlocks?.length
+   *       ? [siblingData.enabledBlocks] // allow only the matching block
+   *       : true // allow all blocks if no value is set
+   *   },
+   *   blocks: [
+   *     { slug: 'block1', fields: [{ type: 'text', name: 'block1Text' }] },
+   *     { slug: 'block2', fields: [{ type: 'text', name: 'block2Text' }] },
+   *     { slug: 'block3', fields: [{ type: 'text', name: 'block3Text' }] },
+   *   ],
+   * }
+   * ```
+   * In this example, the list of available blocks is determined by the enabledBlocks sibling field. If no value is set, all blocks remain available.
+   */
+  filterOptions?: BlocksFilterOptions
   labels?: Labels
   maxRows?: number
   minRows?: number

packages/payload/src/fields/hooks/beforeChange/promise.ts

@@ -2,11 +2,11 @@ import type { RichTextAdapter } from '../../../admin/RichText.js'
 import type { SanitizedCollectionConfig } from '../../../collections/config/types.js'
 import type { ValidationFieldError } from '../../../errors/index.js'
 import type { SanitizedGlobalConfig } from '../../../globals/config/types.js'
-import type { RequestContext } from '../../../index.js'
 import type { JsonObject, Operation, PayloadRequest } from '../../../types/index.js'
 import type { Block, Field, TabAsField, Validate } from '../../config/types.js'
 
 import { MissingEditorProp } from '../../../errors/index.js'
+import { type RequestContext, validateBlocksFilterOptions } from '../../../index.js'
 import { deepMergeWithSourceArrays } from '../../../utilities/deepMerge.js'
 import { getTranslatedLabel } from '../../../utilities/getTranslatedLabel.js'
 import { fieldAffectsData, fieldShouldBeLocalized, tabHasName } from '../../config/types.js'
@@ -200,16 +200,68 @@ export const promise = async ({
       })
 
       if (typeof validationResult === 'string') {
-        const fieldLabel = buildFieldLabel(
-          fieldLabelPath,
-          getTranslatedLabel(field?.label || field?.name, req.i18n),
-        )
-
-        errors.push({
-          label: fieldLabel,
-          message: validationResult,
-          path,
-        })
+        let filterOptionsError = false
+
+        if (field.type === 'blocks' && field.filterOptions) {
+          // Re-run filteroptions. If the validation error is due to filteroptions, we need to add error paths to all the blocks
+          // that are no longer valid
+          const validationResult = validateBlocksFilterOptions({
+            id,
+            data,
+            filterOptions: field.filterOptions,
+            req,
+            siblingData,
+            value: siblingData[field.name],
+          })
+          if (validationResult?.invalidBlockSlugs?.length) {
+            filterOptionsError = true
+            let rowIndex = -1
+            for (const block of siblingData[field.name] as JsonObject[]) {
+              rowIndex++
+              if (validationResult.invalidBlockSlugs.includes(block.blockType as string)) {
+                const blockConfigOrSlug = (field.blockReferences ?? field.blocks).find(
+                  (blockFromField) =>
+                    typeof blockFromField === 'string'
+                      ? blockFromField === block.blockType
+                      : blockFromField.slug === block.blockType,
+                ) as Block | undefined
+                const blockConfig =
+                  typeof blockConfigOrSlug !== 'string'
+                    ? blockConfigOrSlug
+                    : req.payload.config?.blocks?.[blockConfigOrSlug]
+
+                const blockLabelPath =
+                  field?.label === false
+                    ? fieldLabelPath
+                    : buildFieldLabel(
+                        fieldLabelPath,
+                        `${getTranslatedLabel(field?.label || field?.name, req.i18n)} > ${req.t('fields:block')} ${rowIndex + 1} (${getTranslatedLabel(blockConfig?.labels?.singular || block.blockType, req.i18n)})`,
+                      )
+
+                errors.push({
+                  label: blockLabelPath,
+                  message: req.t('validation:invalidBlock', { block: block.blockType }),
+                  path: `${path}.${rowIndex}.id`,
+                })
+              }
+            }
+          }
+        }
+
+        if (!filterOptionsError) {
+          // If the error is due to block filterOptions, we want to push the errors for each individual block, not the blocks
+          // field itself => only push the error if the field is not a block field with validation failure due to filterOptions
+          const fieldLabel = buildFieldLabel(
+            fieldLabelPath,
+            getTranslatedLabel(field?.label || field?.name, req.i18n),
+          )
+
+          errors.push({
+            label: fieldLabel,
+            message: validationResult,
+            path,
+          })
+        }
       }
     }
 
@@ -311,6 +363,14 @@ export const promise = async ({
               (curBlock) => typeof curBlock !== 'string' && curBlock.slug === blockTypeToMatch,
             ) as Block | undefined)
 
+          const blockLabelPath =
+            field?.label === false
+              ? fieldLabelPath
+              : buildFieldLabel(
+                  fieldLabelPath,
+                  `${getTranslatedLabel(field?.label || field?.name, req.i18n)} > ${req.t('fields:block')} ${rowIndex + 1} (${getTranslatedLabel(block?.labels?.singular || blockTypeToMatch, req.i18n)})`,
+                )
+
           if (block) {
             promises.push(
               traverseFields({
@@ -322,13 +382,8 @@ export const promise = async ({
                 doc,
                 docWithLocales,
                 errors,
-                fieldLabelPath:
-                  field?.label === false
-                    ? fieldLabelPath
-                    : buildFieldLabel(
-                        fieldLabelPath,
-                        `${getTranslatedLabel(field?.label || field?.name, req.i18n)} ${rowIndex + 1}`,
-                      ),
+                fieldLabelPath: blockLabelPath,
+
                 fields: block.fields,
                 global,
                 mergeLocaleActions,