Add foundations for extensible validation in forms

.github/actions/node_env_setup/action.yml

@@ -36,7 +36,7 @@ runs:
 
     - name: Install Volto dependencies
       shell: bash
-      run: pnpm i
+      run: make install
 
     - name: Install Cypress if not in cache
       if: steps.cache-cypress-binary.outputs.cache-hit != 'true'

.github/workflows/acceptance.yml

@@ -497,45 +497,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      # node setup
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+      - name: Set up Node.js environment
+        uses: ./.github/actions/node_env_setup
         with:
           node-version: ${{ matrix.node-version }}
 
-      - name: Enable corepack
-        run: corepack enable
-
-      - name: Get pnpm store directory
-        shell: bash
-        run: |
-          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-
-      - uses: actions/cache@v4
-        name: Setup pnpm cache
-        with:
-          path: ${{ env.STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
-
-      - name: Cache Cypress Binary
-        id: cache-cypress-binary
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/Cypress
-          key: binary-${{ matrix.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - run: pnpm i
-
-      - name: Build dependencies
-        run: pnpm build:deps
-
-      - name: Install Cypress if not in cache
-        if: steps.cache-cypress-binary.outputs.cache-hit != 'true'
-        working-directory: packages/volto
-        run: make cypress-install
-
       # Generator own tests
       - name: Generator tests
         run: pnpm test

.github/workflows/unit.yml

@@ -16,30 +16,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      # node setup
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+      - name: Set up Node.js environment
+        uses: ./.github/actions/node_env_setup
         with:
           node-version: ${{ matrix.node-version }}
 
-      - name: Enable corepack
-        run: corepack enable
-
-      - name: Get pnpm store directory
-        shell: bash
-        run: |
-          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-
-      - uses: actions/cache@v4
-        name: Setup pnpm cache
-        with:
-          path: ${{ env.STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
-
-      - run: pnpm i
-
       # Locales in place are needed for the tests to pass
       - run: pnpm --filter @plone/volto i18n
 

Makefile

@@ -69,10 +69,11 @@ clean: ## Clean development environment
 	find ./packages -name node_modules -exec rm -rf {} \;
 
 .PHONY: install
-install: build-deps ## Set up development environment
+install: ## Set up development environment
 	# Setup ESlint for VSCode
-	node packages/scripts/vscodesettings.js
 	pnpm i
+	node packages/scripts/vscodesettings.js
+	make build-deps
 
 ##### Documentation
 
@@ -137,10 +138,10 @@ docs-test: docs-clean docs-linkcheckbroken docs-vale  ## Clean docs build, then
 cypress-install: ## Install Cypress for acceptance tests
 	$(NODEBIN)/cypress install
 
-packages/registry/dist: packages/registry/src
+packages/registry/dist: $(shell find packages/registry/src -type f)
 	pnpm build:registry
 
-packages/components/dist: packages/components/src
+packages/components/dist: $(shell find packages/components/src -type f)
 	pnpm build:components
 
 .PHONY: build-deps

docs/source/configuration/index.md

@@ -27,4 +27,5 @@ environmentvariables
 expanders
 locking
 slots
+validation
 ```

docs/source/configuration/validation.md

@@ -0,0 +1,204 @@
+---
+myst:
+  html_meta:
+    "description": "Client side form field validation"
+    "property=og:description": "Client side form field validation"
+    "property=og:title": "Form fields validation"
+    "keywords": "Volto, Plone, frontend, React, configuration, form, fields, validation"
+---
+
+# Client side form field validation
+
+Volto provides a mechanism for delivering form field validation in an extensible way.
+This extensibility is based on the Volto component registry.
+
+## Registering a validator
+
+You can register a validator using the component registry API from your add-on configuration.
+All validators are registered under the name `fieldValidator`.
+The validators are registered using the `dependencies` array of the `registerComponent` API to differentiate the kind of validator to be registered.
+
+### `default` validators
+
+These validators are registered and applied to all fields.
+
+```ts
+config.registerComponent({
+  name: 'fieldValidator',
+  dependencies: ['default', 'minLength'],
+  component: minLengthValidator,
+});
+```
+
+It takes two `dependencies` being the first element a fixed `default` identifier, and the second you can set it up to identify the validator itself.
+In the case of the example, this other dependency is `minLength`.
+It can be any string.
+
+### Per field `type` validators
+
+These validators are applied depending on the specified `type` of the field.
+
+```ts
+config.registerComponent({
+  name: 'fieldValidator',
+  dependencies: ['integer', 'maximum'],
+  component: maximumValidator,
+});
+```
+
+It takes two `dependencies` since we can potentially have several validators for the same `type`.
+The first element should be the field `type`, and the second you should set it up to identify the validator itself.
+You should specify the `type` in the JSON schema of the block (in a content type, it is included in the default serialization of the field).
+If a field does not specify type, it assumes a `string` type as validator.
+The next example is for the use case of JSON schema defined in a block:
+
+```ts
+let blockSchema = {
+  // ... fieldset definition in here
+  properties: {
+    ...schema.properties,
+    customField: {
+      title: 'My custom field',
+      description: '',
+      type: 'integer',
+    },
+  },
+  required: [],
+};
+```
+
+### Per field `widget` validators
+
+These validators are applied depending on the specified `widget` of the field.
+
+```ts
+config.registerComponent({
+  name: 'fieldValidator',
+  dependencies: ['phoneNumber', 'isValidPhone'],
+  component: phoneValidator,
+});
+```
+
+It takes two `dependencies` since we can potentially have several validators for the same `widget`.
+The first element should be the name of the `widget`, and the second you can set it up to identify the validator.
+You should specify the `widget` in the JSON schema of the block (or as additional data in the content type definition).
+The next example is for the use case of a block JSON schema:
+
+```ts
+let blockSchema = {
+  // ... fieldset definition in here
+  properties: {
+    ...schema.properties,
+    phone: {
+      title: 'Phone number',
+      description: '',
+      widget: 'phoneNumber',
+    },
+  },
+  required: [],
+};
+```
+
+### Per behavior and field name validator
+
+These validators are applied depending on the behavior (usually coming from a content type definition) in combination with the name of the field.
+
+```ts
+config.registerComponent({
+  name: 'fieldValidator',
+  dependencies: ['plone.eventbasic', 'start', 'startValidator'],
+  component: startEventDateRangeValidator,
+});
+```
+
+The first dependency should be the name of the behavior, and the second the name (`id`) of the field.
+It can get a third dependency in case you want to specify several validators for the same behavior - field id combination.
+This type of validator only applies to content-type validators.
+
+### Per block type and field name validator
+
+These validators are applied depending on the block type in combination with the name of the field in the block settings JSON schema.
+
+```ts
+config.registerComponent({
+  name: 'fieldValidator',
+  dependencies: ['slider', 'url', 'isURL'],
+  component: urlValidator,
+});
+```
+
+The first dependency should be the `id` of the block, and the second the `id` of the field.
+It can get a third dependency in case you want to specify several validators for the same block type - field id combination.
+This type of validator only applies to blocks.
+
+### Specific validator using the `validator` key in the field
+
+A final type of validator is applied to the field if the `validator` key is present in the JSON schema definition of the form field.
+
+```ts
+config.registerComponent({
+  name: 'fieldValidator',
+  dependencies: ['isURL'],
+  component: urlValidator,
+});
+```
+
+The dependencies take one single name, in this case, the name of the validator.
+You should specify the validator in the JSON schema of the block (or as additional data in the content type definition).
+
+```ts
+let blockSchema = {
+  // ... fieldset definition in here
+  properties: {
+    ...schema.properties,
+    customField: {
+      title: 'Default field',
+      description: '',
+      validator: 'isURL',
+    },
+  },
+  required: [],
+};
+```
+
+It does not need to be tied to any field `type` or `widget` definition.
+It runs in addition to all the above, so it complements the other validators if any apply.
+
+## Volto's default validators
+
+Volto provides a set of validators by default, you can find them in this module: `packages/volto/src/config/validators.ts`
+
+### How to override them
+
+You can override them in your add-on as any other component defined in the registry, by redefining them using the same `dependencies`, and providing your own.
+
+## Signature of a validator
+
+A validator has the following signature:
+
+```ts
+type Validator = {
+  // The field value
+  value: string;
+  // The field schema definition object
+  field: Record<string, any>;
+  // The form data
+  formData?: any;
+  // The intl formatMessage function
+  formatMessage: Function;
+};
+```
+
+This is an example of an `isNumber` validator:
+
+```ts
+export const isNumber = ({ value, formatMessage }: Validator) => {
+  const floatRegex = /^[+-]?\d+(\.\d+)?$/;
+  const isValid =
+    typeof value === 'number' && !isNaN(value) && floatRegex.test(value);
+  return !isValid ? formatMessage(messages.isNumber) : null;
+};
+```
+
+Using the `formData` you can perform validation checks using other field data as source.
+This is interesting in the case that two fields are related, like `start` and `end` dates.

docs/source/upgrade-guide/index.md

@@ -376,6 +376,13 @@ It is unlikely that your code uses it, unless you heavily customized the Jest te
 This was not used by the core since some time ago, and nowadays is more suitable for being an add-on and not being included in core.
 If you still use it, bring it back as your main add-on dependency, bring back the `SocialSharing` component from Volto 17 as a custom component in your add-on code.
 
+### Refactor of `FormValidation` module
+
+The `packages/volto/src/helpers/FormValidation/FormValidation.jsx` module has been heavily refactored.
+Some helper functions have been moved to `packages/volto/src/helpers/FormValidation/validators.ts`, however, none of those functions were exported in the first place, so no imports will be broken.
+In case that you've shadowed the `packages/volto/src/helpers/FormValidation/FormValidation.jsx` module, you should revisit it and update it with the latest refactor.
+If you added more validators manually in that shadow, please refer to the documentation to add the validators in the new way: {doc}`../configuration/validation`.
+
 (volto-upgrade-guide-17.x.x)=
 
 ## Upgrading to Volto 17.x.x

packages/coresandbox/src/components/Blocks/TestBlock/Data.tsx

@@ -3,8 +3,15 @@ import { BlockDataForm } from '@plone/volto/components/manage/Form';
 import type { BlockEditProps } from '@plone/types';
 
 const TestBlockData = (props: BlockEditProps) => {
-  const { block, blocksConfig, contentType, data, navRoot, onChangeBlock } =
-    props;
+  const {
+    block,
+    blocksConfig,
+    contentType,
+    data,
+    navRoot,
+    onChangeBlock,
+    errors,
+  } = props;
   const intl = useIntl();
   const schema = blocksConfig[data['@type']].blockSchema({ intl, props });
 
@@ -24,6 +31,7 @@ const TestBlockData = (props: BlockEditProps) => {
       blocksConfig={blocksConfig}
       navRoot={navRoot}
       contentType={contentType}
+      errors={errors}
     />
   );
 };

packages/coresandbox/src/components/Blocks/TestBlock/schema.ts

@@ -182,6 +182,11 @@ export const multipleFieldsetsSchema: BlockConfigBase['blockSchema'] = ({
       title: 'fourth',
       fields: ['href', 'firstWithDefault', 'style'],
     },
+    {
+      id: 'fifth',
+      title: 'fifth',
+      fields: ['fieldRequiredInFieldset'],
+    },
   ],
   properties: {
     slides: {
@@ -232,6 +237,9 @@ export const multipleFieldsetsSchema: BlockConfigBase['blockSchema'] = ({
       title: 'HTML',
       widget: 'richtext',
     },
+    fieldRequiredInFieldset: {
+      title: 'Field required in fieldset',
+    },
   },
-  required: [],
+  required: ['fieldRequiredInFieldset'],
 });

packages/registry/news/6161.feature

@@ -0,0 +1 @@
+Add `getComponents` that match a partial set of dependencies, given a name. @sneridagh