@brightspace-ui/core 3.301.0 → 3.302.0

package/components/inputs/docs/form-layout-validation.md

@@ -144,3 +144,7 @@ Within the fieldset, `<d2l-input-group>` can still be used to provide a consiste
 * `Default`: Related input components
 * `inline-help`: Help text that will appear below the input. Use this only when other helpful cues are not sufficient, such as a carefully-worded label.
 <!-- docs: end hidden content -->
+
+## Custom Validation [validation-custom]
+
+To attach custom validation logic to an existing component (native or custom), use [d2l-validation-custom](../../../components/validation).

package/components/validation/README.md

@@ -1,25 +1,21 @@
 # Validation
-## d2l-validation-custom
+## Validation Custom [d2l-validation-custom]
 
-The `d2l-validation-custom` component is used to add custom validation logic to native form elements like `input`, `select` and `textarea` or custom form elements created with the [`FormElementMixin`](../form/docs/form-element-mixin.md).
+The `d2l-validation-custom` component is used to add custom validation logic to native form elements like `input`, `select` and `textarea` or custom form elements created with the [`FormElementMixin`](https://github.com/BrightspaceUI/core/blob/main/components/form/docs/form-element-mixin.md).
 
 **Native Form Elements:**
-- When attached to native form elements like `input`, `select` and `textarea`, both the `d2l-validation-custom` and native form element **must** be within a [`d2l-form`](../form/docs/form.md) for the validation custom to function.
+- When attached to native form elements like `input`, `select` and `textarea`, both the `d2l-validation-custom` and native form element **must** be within a [`d2l-form`](../../components/form-layout-validation) for the validation custom to function.
 
 **Custom Form Elements:**
-- When attached to custom form elements created with the [`FormElementMixin`](../form/docs/form-element-mixin.md), the `d2l-validation-custom` will function even if no [`d2l-form`](../form/docs/form.md) is present.
+- When attached to custom form elements created with the [`FormElementMixin`](https://github.com/BrightspaceUI/core/blob/main/components/form/docs/form-element-mixin.md), the `d2l-validation-custom` will function even if no [`d2l-form`](../../components/form-layout-validation) is present.
 
 **Usage:**
+<!-- docs: demo code properties autoSize:false size:small name:d2l-validation-custom sandboxTitle:'Custom Validation' -->
 ```html
 <script type="module">
+  import '@brightspace-ui/core/components/inputs/input-text.js';
   import '@brightspace-ui/core/components/validation/validation-custom.js';
-</script>
-
-<d2l-input-text id="my-text-input"></d2l-input-text>
-<d2l-validation-custom for="my-text-input" failure-text="My custom error message">
-</d2l-validation-custom>
 
-<script>
   const validator = document.querySelector('d2l-validation-custom');
   validator.addEventListener('d2l-validation-custom-validate', e => {
     // Implement your custom validation logic
@@ -28,8 +24,12 @@ The `d2l-validation-custom` component is used to add custom validation logic to
     e.detail.resolve(isValid);
   });
 </script>
-```
 
+<d2l-input-text id="my-text-input" label="name" style="max-width: 200px;"></d2l-input-text>
+<d2l-validation-custom for="my-text-input" failure-text="My custom error message">
+</d2l-validation-custom>
+```
+<!-- docs: start hidden content -->
 **Properties:**
 
 | Property | Type | Description |
@@ -42,7 +42,9 @@ The `d2l-validation-custom` component is used to add custom validation logic to
   * The form element being validated can be accessed from the `detail`'s `forElement` property.
   * When validation is finished, the `detail`'s `resolve` function **must** be called with a `boolean` value to indicate valid or invalid. If it is not called then validation will never complete and the component will be stuck in a validating state.
 
-## ValidationCustomMixin
+<!-- docs: end hidden content -->
+
+## Validation Custom Mixin [ValidationCustomMixin]
 
 If you find yourself duplicating `d2l-validation-custom` validation logic in many places you may want to create your own custom validator using the `ValidationCustomMixin`.
 
@@ -64,7 +66,3 @@ customElements.define('my-validation-custom', MyValidationCustom);
 ```
 
 Once a component has been created using the `ValidationCustomMixin`, it may be used exactly like a `d2l-validation-custom`. However, the `d2l-validation-custom-validate` event isn't needed because the validation logic is included in the component itself.
-
-## Future Enhancements
-
-Looking for an enhancement not listed here? Create a GitHub issue!

package/components/validation/validation-custom-mixin.js

@@ -3,7 +3,15 @@ import { isCustomFormElement } from '../form/form-helper.js';
 export const ValidationCustomMixin = superclass => class extends superclass {
 
 	static properties = {
+		/**
+		 * REQUIRED: The text to display when validation fails.
+		 * @type {string}
+		 */
 		failureText: { type: String, attribute: 'failure-text' },
+		/**
+		 * REQUIRED: The id of the form element to validate.
+		 * @type {string}
+		 */
 		for: { type: String }
 	};
 
@@ -19,6 +27,7 @@ export const ValidationCustomMixin = superclass => class extends superclass {
 	connectedCallback() {
 		super.connectedCallback();
 		this._updateForElement();
+		/**@ignore */
 		this.dispatchEvent(new CustomEvent('d2l-validation-custom-connected', { bubbles: true }));
 	}
 
@@ -28,6 +37,7 @@ export const ValidationCustomMixin = superclass => class extends superclass {
 			this._forElement.validationCustomDisconnected(this);
 		}
 		this._forElement = null;
+		/**@ignore */
 		this.dispatchEvent(new CustomEvent('d2l-validation-custom-disconnected'));
 	}
 

package/components/validation/validation-custom.js

@@ -2,6 +2,10 @@
 import { css, LitElement } from 'lit';
 import { ValidationCustomMixin } from './validation-custom-mixin.js';
 
+/**
+ * A component that can be used to provide custom validation for a form element. The component is hidden and does not render any visible content.
+ * @fires d2l-validation-custom-validate - Dispatched when the component is validated.
+ */
 class ValidationCustom extends ValidationCustomMixin(LitElement) {
 
 	static styles = css`

package/custom-elements.json

@@ -17387,13 +17387,16 @@
     {
       "name": "d2l-validation-custom",
       "path": "./components/validation/validation-custom.js",
+      "description": "A component that can be used to provide custom validation for a form element. The component is hidden and does not render any visible content.",
       "attributes": [
         {
           "name": "failure-text",
+          "description": "REQUIRED: The text to display when validation fails.",
           "type": "string"
         },
         {
           "name": "for",
+          "description": "REQUIRED: The id of the form element to validate.",
           "type": "string"
         }
       ],
@@ -17405,11 +17408,13 @@
         {
           "name": "failureText",
           "attribute": "failure-text",
+          "description": "REQUIRED: The text to display when validation fails.",
           "type": "string"
         },
         {
           "name": "for",
           "attribute": "for",
+          "description": "REQUIRED: The id of the form element to validate.",
           "type": "string"
         },
         {
@@ -17418,13 +17423,8 @@
       ],
       "events": [
         {
-          "name": "d2l-validation-custom-validate"
-        },
-        {
-          "name": "d2l-validation-custom-connected"
-        },
-        {
-          "name": "d2l-validation-custom-disconnected"
+          "name": "d2l-validation-custom-validate",
+          "description": "Dispatched when the component is validated."
         }
       ]
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightspace-ui/core",
-  "version": "3.301.0",
+  "version": "3.302.0",
   "description": "A collection of accessible, free, open-source web components for building Brightspace applications",
   "type": "module",
   "repository": "https://github.com/BrightspaceUI/core.git",