Add readme for validations (#49723)

* Add readme for validators

* Add changelog

* Add docs manifest

* Fix product-editor.md

* Fix readme

docs/docs-manifest.json

@@ -716,7 +716,7 @@
           "post_title": "Product editor development handbook",
           "menu_title": "Development handbook",
           "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/product-editor-development/product-editor.md",
-          "hash": "cc5f82b66e949e3df2928b5e6b1217e8804c43b8e7b75ebc930cd0f90aef7bbe",
+          "hash": "a014d4f53a860ff74eec6cefbe868279616bcad5509b2f30f02bb8e118935c98",
           "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/product-editor-development/product-editor.md",
           "id": "59450404de2750d918137e7cf523e52bedfd7214",
           "links": {
@@ -1068,11 +1068,6 @@
       ],
       "categories": []
     },
-    {
-      "category_slug": "utilities",
-      "category_title": "Utilities",
-      "categories": []
-    },
     {
       "content": "\nThis section covers general guidelines, and best practices to follow in order to ensure your product experience aligns with WooCommerce for ease of use, seamless integration, and strong adoption.\n\nWe strongly recommend you review the current [WooCommerce setup experience](https://woocommerce.com/documentation/plugins/woocommerce/getting-started/) to get familiar with the user experience and taxonomy.\n\nWe also recommend you review the [WordPress core guidelines](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/) to ensure your product isn't breaking any rules, and review [this helpful resource](https://woocommerce.com/document/grammar-punctuation-style-guide/) on content style.\n\n## General\n\nUse existing WordPress/WooCommerce UI, built in components (text fields, checkboxes, etc) and existing menu structures.\n\nPlugins which draw on WordPress' core design aesthetic will benefit from future updates to this design as WordPress continues to evolve. If you need to make an exception for your product, be prepared to provide a valid use case.\n\n- [WordPress Components library](https://wordpress.github.io/gutenberg/?path=/story/docs-introduction--page)\n- [Figma for WordPress](https://make.wordpress.org/design/2018/11/19/figma-for-wordpress/) | ([WordPress Design Library Figma](https://www.figma.com/file/e4tLacmlPuZV47l7901FEs/WordPress-Design-Library))\n- [WooCommerce Component Library](https://woocommerce.github.io/woocommerce-admin/)\n",
       "category_slug": "user-experience-extensions",
@@ -1372,5 +1367,5 @@
       "categories": []
     }
   ],
-  "hash": "0f3a825397f5872c1f482a1402a07e71002b2aceec65845f60545f17d7a1d6ff"
+  "hash": "73bcb44585da56302a4dd3056b4a7aab16b58a516f214bbfde7b9b7d7157e84b"
 }

docs/product-editor-development/product-editor.md

@@ -39,3 +39,4 @@ Please note that this check is currently not being enforced: the product editor
 - [Examples on Template API usage](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Admin/Features/ProductBlockEditor/ProductTemplates/README.md/)
 - [Related hooks and Template API documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Admin/BlockTemplates/README.md)
 - [Generic blocks documentation](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/blocks/generic/README.md)
+- [Validations and error handling](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/contexts/validation-context/README.md)

packages/js/product-editor/changelog/add-49721_add_readme_for_validators

@@ -0,0 +1,4 @@
+Significance: minor
+Type: add
+
+Add readme for validations #49723

packages/js/product-editor/src/contexts/validation-context/README.md

@@ -0,0 +1,75 @@
+# Validations and error handling
+
+This directory contains some components and hooks used for validations in the product editor.
+
+## What happens when there is an error in the form?
+
+1. Fields registered in the validator context [will get validated](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/contexts/validation-context/validation-provider.tsx#L87-L110). A field can be registered by making use of the useValidation hook.
+    - For instance:
+
+    ```javascript
+    const {
+      ref: myRef,
+      error: myValidationError,
+      validate: validateMyField,
+    } = useValidation <
+    Product >
+    ( 'myfield',
+    async function myFieldValidator() {
+      if ( ! myField ) {
+        return {
+          message: 'My error message',
+          context: clientId,
+        };
+      }
+    },
+    [ myField ] );
+    ```
+
+2. If a field has an error, it returns an object consisting of the error/validation message, the context, and the validatorId ([link](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/contexts/validation-context/validation-provider.tsx#L74) ).
+    - The `context` contains the block Id, and the `validatorId` a unique ID for the validator specifically ( generally a prefix with the block id ).
+    - If, for instance, the name field is empty, the validation will fail and will throw an object like this:
+
+    ```javascript
+    { message: 'Product name is required.'; context: [block id]; validatorId: [prefix + block id] }
+    ```
+
+    - This is the result of the name validator and the [validatorId addition](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/contexts/validation-context/validation-provider.tsx#L69).
+
+    ```javascript
+    async function nameValidator() {
+      if ( ! name || name === AUTO_DRAFT_NAME ) {
+        return {
+          message: __( 'Product name is required.', 'woocommerce' ),
+          context: clientId,
+        };
+      }
+
+      if ( name.length > 120 ) {
+        return {
+          message: __(
+            'Please enter a product name shorter than 120 characters.',
+            'woocommerce'
+          ),
+          context: clientId,
+        };
+      }
+    },
+    ```
+
+3. If an error is present on the form we will show an error snackbar with the error message. We will actually include a **View error** link if the field with the relevant error is not visible ( like on another tab ). Clicking the **View error** link will direct users to the relevant field.
+    - We create this link by making use of the `context` property (the block id), this makes use of the `useBlocksHelper()` hook to get the parent tab id. We can do this by making use of the `core/block-editor` store and using `getBlockParentsByBlockName` (link to relevant code).
+    - When the field with [the error is not visible](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/hooks/use-error-handler.ts#L105), a link pointing to it will be added to the snackbar.
+    - Otherwise, the error will be dismissed automatically.
+    - The hook `useErrorHandler` is used to get the [error props](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/hooks/use-error-handler.ts#L79).
+    - The error shown will depend [on the error code](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/hooks/use-error-handler.ts#L92).
+    - [As you can see here](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/hooks/use-error-handler.ts#L157-L162), if the error doesn't have a code, the default message will be `Failed to save product.`
+    - The context is used to [get the parent tab](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/hooks/use-blocks-helper/use-blocks-helper.ts#L7) id and the validatorId to [focus on the field](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/hooks/use-error-handler.ts#L68).
+
+Finally, [the snackbar with the error](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/product-editor/src/components/header/publish-button/publish-button.tsx#L70) message and props will be displayed.
+
+![Product editor error snackbar](https://developer.woocommerce.com/wp-content/uploads/sites/2/2024/07/product-editor-error-snack-bar-e1721670028482.png)
+
+## Limitations
+
+The server errors, such as `duplicated SKU`, are not being mapped yet.