@brightspace-ui/core 3.254.2 → 3.255.0

package/components/form/docs/form-element-container-mixin.md

@@ -0,0 +1,28 @@
+# FormElementContainerMixin
+
+Extending `FormElementContainerMixin` will allow a custom element's children (native or [custom](./form-element-mixin.md)) to participate in the parent `<d2l-form>`.
+
+## Usage
+
+Simply extend the `FormElementContainerMixin`:
+
+```javascript
+import { FormElementContainerMixin } from '@brightspace-ui/core/form/form-element-container-mixin.js';
+
+class MyCustomFormElementContainer extends FormElementContainerMixin(LitElement) {
+	render() {
+		html`
+			<d2l-input-text
+				label="First Name"
+				name="first-name"
+				required></d2l-input-text>
+			<d2l-input-text
+				label="Last Name"
+				name="last-name"
+				required></d2l-input-text>
+		`;
+	}
+}
+
+customElements.define('my-custom-form-element-container', MyCustomFormElementContainer);
+```

package/components/form/form-element-container-mixin.js

@@ -0,0 +1,8 @@
+/**
+ * When applied to a custom element, form elements within will participate in the form.
+ */
+export const FormElementContainerMixin = superClass => class extends superClass {
+	get isCustomFormElementContainer() {
+		return true;
+	}
+};

package/components/form/form-helper.js

@@ -15,24 +15,34 @@ export const isElement = (node) => node && node.nodeType === Node.ELEMENT_NODE;
 
 export const isCustomElement = (node) => isElement(node) && node.nodeName.indexOf('-') !== -1;
 
-export const isCustomFormElement = (node) => isCustomElement(node) && !!node.formAssociated;
+export const isCustomFormElement = (node) => isCustomElement(node) && Boolean(node.formAssociated);
+
+export const isCustomFormElementContainer = (node) => isCustomElement(node) && Boolean(node.isCustomFormElementContainer);
 
 export const isNativeFormElement = (node) => {
 	if (!isElement(node)) {
 		return false;
 	}
 	const nodeName = node.nodeName.toLowerCase();
-	return !!formElements[nodeName];
+	return Boolean(formElements[nodeName]);
+};
+
+const getElementChildren = (elem) => {
+	if (isCustomFormElementContainer(elem)) {
+		return elem.shadowRoot.children;
+	}
+
+	return elem.tagName === 'SLOT' && ['primary', 'secondary'].includes(elem.name) ? elem.assignedNodes() : elem.children;
 };
 
-const _findFormElementsHelper = (ele, eles, isFormElementPredicate, visitChildrenPredicate) => {
-	if (isNativeFormElement(ele) || isCustomFormElement(ele) || isFormElementPredicate(ele)) {
-		eles.push(ele);
+const _findFormElementsHelper = (elem, elems, isFormElementPredicate, visitChildrenPredicate) => {
+	if (isNativeFormElement(elem) || isCustomFormElement(elem) || isFormElementPredicate(elem)) {
+		elems.push(elem);
 	}
-	if (visitChildrenPredicate(ele)) {
-		const children = ele.tagName === 'SLOT' && ['primary', 'secondary'].includes(ele.name) ? ele.assignedNodes() : ele.children;
+	if (visitChildrenPredicate(elem)) {
+		const children = getElementChildren(elem);
 		for (const child of children) {
-			_findFormElementsHelper(child, eles, isFormElementPredicate, visitChildrenPredicate);
+			_findFormElementsHelper(child, elems, isFormElementPredicate, visitChildrenPredicate);
 		}
 	}
 };

package/custom-elements.json

@@ -4967,6 +4967,21 @@
         }
       ]
     },
+    {
+      "name": "d2l-custom-form-element-container",
+      "path": "./components/form/demo/custom-form-element-container.js",
+      "properties": [
+        {
+          "name": "styles",
+          "type": "CSSResult[]",
+          "default": "[\"inputStyles\",\"inputLabelStyles\"]"
+        },
+        {
+          "name": "isCustomFormElementContainer",
+          "type": "boolean"
+        }
+      ]
+    },
     {
       "name": "d2l-form-demo",
       "path": "./components/form/demo/form-demo.js"

package/package.json

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