Document the selectors for the wc/store/validation data store (woocom…

…merce#7086) * Add documentation for validation data store Co-authored-by: Niels Lange <[email protected]> * Use correct file path for validation data store docs * Fix typo in hasValidationErrors documentation * Add parameters and example of getValidationError * Improve description of getValidationErrorId * Fix typo in hasValidationErrors * Document clearValidationErrors * Add documentation and example for setValidationErrors * Add documentation for clearAllValidationErrors * Add documentation for hideValidationError * Add documentation for showValidationError * Add overview section * Update hideValidationError documentation * Add showValidationErrors documentation * Update table of contents * Fix typo in action name and add example * Fix typo in hasValidationErrors Co-authored-by: Thomas Roberts <[email protected]>
senadir · Oct 7, 2022 · d9152c0 · d9152c0
1 parent f4c1d94
commit d9152c0
Show file tree

Hide file tree

Showing 2 changed files with 203 additions and 0 deletions.
diff --git a/docs/third-party-developers/extensibility/data-store/README.md b/docs/third-party-developers/extensibility/data-store/README.md
@@ -3,6 +3,7 @@
 ## Table of Contents
 
 -   [wc/store/checkout](checkout.md)
+-   [wc/store/validation](validation.md)
 
 <!-- FEEDBACK -->
 

diff --git a/docs/third-party-developers/extensibility/data-store/validation.md b/docs/third-party-developers/extensibility/data-store/validation.md
@@ -0,0 +1,202 @@
+# wc/store/validation
+
+## Table of Contents
+
+-   [Overview](#overview)
+-   [Selectors](#selectors)
+    -   [getValidationError](#getvalidationerror)
+    -   [getValidationErrorId](#getvalidationerrorid)
+    -   [hasValidationErrors](#hasvalidationerrors)
+-   [Actions](#actions)
+    -   [clearValidationError](#clearvalidationerror)
+    -   [clearAllValidationErrors](#clearallvalidationerrors)
+    -   [setValidationErrors](#setvalidationerrors)
+    -   [hideValidationError](#hidevalidationerror)
+    -   [showValidationError](#showvalidationerror)
+    -   [showAllValidationErrors](#showallvalidationerrors)
+
+## Overview
+
+The validation data store provides a way to show errors for fields in the Cart or Checkout blocks.
+
+The data in the store should be a single object, the keys of which are the _error IDs_ and values are the data
+associated with that error message. The values in the object should contain _message_ and _hidden_. The _message_
+is the error message to display and _hidden_ is a boolean indicating whether the error should be shown or not.
+
+An example of how the data should be structured:
+
+```js
+{
+    "error-id-1": {
+        message: "This is an error message",
+        hidden: false,
+    },
+    "error-id-2": {
+        message: "This is another error message",
+        hidden: true,
+    },
+}
+```
+
+When the checkout process begins, it will check if this data store has any entries, and if so, it will stop the checkout
+process from proceeding. It will also show any errors that are hidden. Setting an error to hidden will not clear it from
+the data store!
+
+## Selectors
+
+### getValidationError
+
+Returns the validation error.
+
+#### _Parameters_
+
+- _errorId_ `string` - The error ID to get validation errors for.
+
+#### Example
+
+```js
+const store = select( 'wc/store/validation' );
+const billingFirstNameError = store.getValidationError( 'billing-first-name' );
+```
+
+
+#### _Returns_
+
+-   `object`: The validation error which is an object containing _message_ (`string`) and _hidden_ (`boolean`).
+
+### getValidationErrorId
+
+Gets a validation error ID for use in HTML which can be used as a CSS selector, or to reference an error message.
+This will return the error ID prefixed with `validate-error-`, unless the validation error has `hidden` set to true, or
+the validation error does not exist in the store.
+
+#### _Parameters_
+
+- _errorId_ `string` - The error ID to get the validation error ID for.
+
+#### _Returns_
+
+-   `string`: The validation error ID for use in HTML.
+
+### hasValidationErrors
+
+Returns true if validation errors occurred, and false otherwise.
+
+#### _Returns_
+
+-   `boolean`: Whether validation errors occurred.
+
+## Actions
+
+### clearValidationError
+
+Clears a validation error.
+
+#### _Parameters_
+
+- _errorId_ `string` - The error ID to clear validation errors for.
+
+#### Example
+
+```js
+const store = dispatch( 'wc/store/validation' );
+store.clearValidationError( 'billing-first-name' );
+```
+
+### clearAllValidationErrors
+
+Clears all validation errors.
+
+### setValidationErrors
+
+#### _Parameters_
+
+-   _errors_ `object`: An object containing new validation errors, the keys of the object are the validation error IDs,
+and the values should be objects containing _message_ (`string`) and _hidden_ `boolean`.
+
+Sets the validation errors. The entries in _errors_ will be _added_ to the list of validation errors. Any entries that
+already exist in the list will be _updated_ with the new values.
+
+#### Example
+
+```js
+const { dispatch } = wp.data;
+const { setValidationErrors } = dispatch( 'wc/store/validation' );
+
+setValidationErrors( {
+    'billing-first-name': {
+        message: 'First name is required.',
+        hidden: false,
+    },
+    'billing-last-name': {
+        message: 'Last name is required.',
+        hidden: false,
+    },
+} );
+```
+
+#### Example
+
+```js
+const { dispatch } = wp.data;
+const { clearAllValidationErrors } = dispatch( 'wc/store/validation' );
+
+clearAllValidationErrors();
+```
+
+### hideValidationError
+
+Hides a validation error by setting the `hidden` property to `true`. This will _not_ clear it from the data store!
+
+#### _Parameters_
+
+-   _errorId_ `string`: The error ID to hide.
+
+#### Example
+
+```js
+const { dispatch } = wp.data;
+const { hideValidationError } = dispatch( 'wc/store/validation' );
+
+hideValidationError( 'billing-first-name' );
+```
+
+### showValidationError
+
+Shows a validation error by setting the `hidden` property to `false`.
+
+#### _Parameters_
+
+-   _errorId_ `string`: The error ID to show.
+
+#### Example
+
+```js
+const { dispatch } = wp.data;
+const { showValidationError } = dispatch( 'wc/store/validation' );
+
+showValidationError( 'billing-first-name' );
+```
+
+### showAllValidationErrors
+
+Shows all validation errors by setting the `hidden` property to `false`.
+
+#### Example
+
+```js
+const { dispatch } = wp.data;
+const { showAllValidationErrors } = dispatch( 'wc/store/validation' );
+
+showAllValidationErrors();
+```
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/third-party-developers/extensibility/checkout-payment-methods/checkout-flow-and-events.md)
+
+<!-- /FEEDBACK -->