From 0a019187bfeb52c4a2eacb5385d069034c68d34c Mon Sep 17 00:00:00 2001
From: Stoyan <88034608+hinzzx@users.noreply.github.com>
Date: Wed, 26 Jul 2023 14:55:16 +0300
Subject: [PATCH] feat(ui5-switch): add required property (#7324)

Introducing the `required` property for the Switch control.
We now also enable the Form Support feature within the control, which means now the Switch component, could be easily used and integrated within forms as well.
---
 packages/main/src/Switch.hbs                  |  2 +
 packages/main/src/Switch.ts                   | 72 ++++++++++++++++++-
 packages/main/test/pages/Switch.html          | 29 ++++++++
 packages/main/test/pages/styles/Switch.css    |  6 ++
 packages/main/test/specs/Switch.spec.js       | 25 +++++++
 .../_stories/main/Switch/Switch.stories.ts    | 43 ++++++++++-
 6 files changed, 173 insertions(+), 4 deletions(-)

diff --git a/packages/main/src/Switch.hbs b/packages/main/src/Switch.hbs
index 67792aee1a44..d227fec52019 100644
--- a/packages/main/src/Switch.hbs
+++ b/packages/main/src/Switch.hbs
@@ -4,6 +4,7 @@
 	aria-label="{{ariaLabelText}}"
 	aria-checked="{{checked}}"
 	aria-disabled="{{effectiveAriaDisabled}}"
+	aria-required="{{required}}"
 	@click="{{_onclick}}"
 	@keyup="{{_onkeyup}}"
 	@keydown="{{_onkeydown}}"
@@ -47,4 +48,5 @@
 	</div>
 
 	<input type='checkbox' ?checked="{{checked}}" class="ui5-switch-input" data-sap-no-tab-ref/>
+	<slot name="formSupport"></slot>
 </div>
diff --git a/packages/main/src/Switch.ts b/packages/main/src/Switch.ts
index ac22076c1cb7..b37528463932 100644
--- a/packages/main/src/Switch.ts
+++ b/packages/main/src/Switch.ts
@@ -2,6 +2,7 @@ import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
 import property from "@ui5/webcomponents-base/dist/decorators/property.js";
 import event from "@ui5/webcomponents-base/dist/decorators/event.js";
+import slot from "@ui5/webcomponents-base/dist/decorators/slot.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
 
 import { isSpace, isEnter } from "@ui5/webcomponents-base/dist/Keys.js";
@@ -13,6 +14,9 @@ import { getEffectiveAriaLabelText } from "@ui5/webcomponents-base/dist/util/Ari
 import "@ui5/webcomponents-icons/dist/accept.js";
 import "@ui5/webcomponents-icons/dist/decline.js";
 import "@ui5/webcomponents-icons/dist/less.js";
+import { getFeature } from "@ui5/webcomponents-base/dist/FeaturesRegistry.js";
+import type FormSupport from "./features/InputElementsFormSupport.js";
+import type { IFormElement } from "./features/InputElementsFormSupport.js";
 import Icon from "./Icon.js";
 import SwitchDesign from "./types/SwitchDesign.js";
 
@@ -77,7 +81,7 @@ import switchCss from "./generated/themes/Switch.css.js";
  * @event sap.ui.webc.main.Switch#change
  */
 @event("change")
-class Switch extends UI5Element {
+class Switch extends UI5Element implements IFormElement {
 	/**
 	 * Defines the component design.
 	 * <br><br>
@@ -188,8 +192,70 @@ class Switch extends UI5Element {
 	@property()
 	tooltip!: string;
 
+	/**
+	 * Defines whether the component is required.
+	 *
+	 * @type {boolean}
+	 * @name sap.ui.webc.main.Switch.prototype.required
+	 * @defaultvalue false
+	 * @public
+	 * @since 1.16.0
+	 */
+	@property({ type: Boolean })
+	required!: boolean;
+
+	/**
+	 * Determines the name with which the component will be submitted in an HTML form.
+	 *
+	 * <br><br>
+	 * <b>Important:</b> For the <code>name</code> property to have effect, you must add the following import to your project:
+	 * <code>import "@ui5/webcomponents/dist/features/InputElementsFormSupport.js";</code>
+	 *
+	 * <br><br>
+	 * <b>Note:</b> When set, a native <code>input</code> HTML element
+	 * will be created inside the component so that it can be submitted as
+	 * part of an HTML form. Do not use this property unless you need to submit a form.
+	 *
+	 * @type {string}
+	 * @name sap.ui.webc.main.Switch.prototype.name
+	 * @defaultvalue ""
+	 * @public
+	 * @since 1.16.0
+	 */
+	@property()
+	name!: string;
+
+	/**
+	 * The slot is used to render native <code>input</code> HTML element within Light DOM to enable form submit, when <code>Switch</code> is a part of HTML form.
+	 *
+	 * @type {HTMLElement[]}
+	 * @slot
+	 * @private
+	 * @since 1.16.0
+	 */
+	@slot()
+	formSupport!: Array<HTMLElement>;
+
 	static i18nBundle: I18nBundle;
 
+	onBeforeRendering() {
+		this._enableFormSupport();
+	}
+
+	_enableFormSupport() {
+		const formSupport = getFeature<typeof FormSupport>("FormSupport");
+		if (formSupport) {
+			formSupport.syncNativeHiddenInput(this, (element: IFormElement, nativeInput: HTMLInputElement) => {
+				const switchComponent = (element as Switch);
+				nativeInput.checked = !!switchComponent.checked;
+				nativeInput.disabled = !!switchComponent.disabled;
+				nativeInput.value = switchComponent.checked ? "on" : "";
+			});
+		} else if (this.name) {
+			console.warn(`In order for the "name" property to have effect, you should also: import "@ui5/webcomponents/dist/features/InputElementsFormSupport.js";`); // eslint-disable-line
+		}
+	}
+
 	get sapNextIcon() {
 		return this.checked ? "accept" : "less";
 	}
@@ -219,9 +285,9 @@ class Switch extends UI5Element {
 			this.checked = !this.checked;
 			const changePrevented = !this.fireEvent("change", null, true);
 			// Angular two way data binding;
-			const valueChagnePrevented = !this.fireEvent("value-changed", null, true);
+			const valueChangePrevented = !this.fireEvent("value-changed", null, true);
 
-			if (changePrevented || valueChagnePrevented) {
+			if (changePrevented || valueChangePrevented) {
 				this.checked = !this.checked;
 			}
 		}
diff --git a/packages/main/test/pages/Switch.html b/packages/main/test/pages/Switch.html
index 59155605f6c2..bc481cee961e 100644
--- a/packages/main/test/pages/Switch.html
+++ b/packages/main/test/pages/Switch.html
@@ -55,6 +55,28 @@ <h3>Graphical Switch</h3>
 		<ui5-switch design="Graphical" checked text-on="Yes" text-off="No" disabled></ui5-switch>
 	</div>
 
+	<div class="switch2auto">
+		<form id="myForm" class="switch-form">
+			<h3 style="margin: 0 0 1rem 0">Switch in Registration form example</h3>
+			<div style="display: flex; flex-direction: column;">
+				<ui5-input required type="Email" placeholder="Email" value="your@email.com"></ui5-input>
+				<ui5-input required type="Password" placeholder="Password" value="your@email.com"></ui5-input>
+			</div>
+			<p style="margin: 1rem 0 0 0">Please accept the terms and conditions, in order to proceed.</p>
+			<ui5-switch id="requiredSwitch" style="margin: 0" name="switch" text-on="Yes" text-off="No" required></ui5-switch>
+			<br />
+			<ui5-button type="Submit" id="submitBtn">Submit Form</ui5-button>
+		</form>
+	</div>
+
+	<h3>Switch in form test</h3>
+	<form id="switchForm">
+		<ui5-switch id="switch1" checked></ui5-switch>
+		<ui5-switch id="requiredTestSwitch" required></ui5-switch>
+		<br><br>
+		<ui5-button id="switchSubmit" type="Submit">Submit</ui5-button>
+	</form>
+
 	<h3>Custom Switch</h3>
 	<div class="switch2auto">
 		<ui5-switch text-on="Accept" text-off="Reject" class="switch4auto"></ui5-switch>
@@ -83,6 +105,13 @@ <h3>sap_horizon</h3>
 <script>
 	var counter = 0;
 
+	submitBtn.addEventListener("click", function(e) {
+		if (myForm.checkValidity()) {
+			e.preventDefault();
+			alert("Form submitted successfully!");
+		}
+	});
+
 	sw.addEventListener("ui5-change", function(e) {
 		lbl.innerHTML = e.target.checked + " : " + (++counter);
 		field.value = counter;
diff --git a/packages/main/test/pages/styles/Switch.css b/packages/main/test/pages/styles/Switch.css
index e93c9f8aa696..8e3de3b92f99 100644
--- a/packages/main/test/pages/styles/Switch.css
+++ b/packages/main/test/pages/styles/Switch.css
@@ -75,3 +75,9 @@ ui5-switch {
     width: 200px;
     height: 200px;
 }
+
+.switch-form {
+    border: 1px solid var(--sapList_BorderColor);
+    border-radius: var(--sapElement_BorderCornerRadius);
+    padding: 1rem;
+}
diff --git a/packages/main/test/specs/Switch.spec.js b/packages/main/test/specs/Switch.spec.js
index 9400c199053d..5155d54a67a2 100644
--- a/packages/main/test/specs/Switch.spec.js
+++ b/packages/main/test/specs/Switch.spec.js
@@ -62,4 +62,29 @@ describe("Switch general interaction", async () => {
 		assert.strictEqual(await switchPrevented.getProperty("checked"), currentChecked, "The switch is not checked");
 	});
 
+	it("The 'required' attribute is propagated properly", async () => {
+		assert.strictEqual(await browser.$("#requiredSwitch").shadow$(".ui5-switch-root").getAttribute("aria-required"), "true", "The required attribute is set correctly");
+		assert.strictEqual(await browser.$("#switchprevented").shadow$(".ui5-switch-root").getAttribute("aria-required"), "false", "The required attribute is set correctly");
+	})
+
+	it("Form should submit only when the 'required' switch is checked", async () => {
+		const requiredSwitch = await browser.$("#requiredTestSwitch");
+
+		let formValidity = await browser.execute(() => {
+			const form = document.getElementById("switchForm");
+			return form.checkValidity();
+		});
+
+		assert.strictEqual(formValidity, false, "The form could be submitted successfuly, when the 'required' switch is not checked");
+
+		requiredSwitch.click();
+		await browser.pause(1000);
+
+		formValidity = await browser.execute(() => {
+			const form = document.getElementById("switchForm");
+			return form.checkValidity();
+		});
+
+		assert.strictEqual(formValidity, true, "The form could be submitted successfuly, because the 'required' switch is checked");
+	});
 });
diff --git a/packages/playground/_stories/main/Switch/Switch.stories.ts b/packages/playground/_stories/main/Switch/Switch.stories.ts
index 42d52272682f..6b43310b0d9c 100644
--- a/packages/playground/_stories/main/Switch/Switch.stories.ts
+++ b/packages/playground/_stories/main/Switch/Switch.stories.ts
@@ -28,6 +28,8 @@ const Template: UI5StoryArgs<Switch, StoryArgsSlots> = (args) => html`<ui5-switc
 	design="${ifDefined(args.design)}"
 	?checked="${ifDefined(args.checked)}"
 	?disabled="${ifDefined(args.disabled)}"
+	?required="${ifDefined(args.required)}"
+	?name="${ifDefined(args.name)}"
 	text-on="${ifDefined(args.textOn)}"
 	text-off="${ifDefined(args.textOff)}"
 	accessible-name="${ifDefined(args.accessibleName)}"
@@ -60,4 +62,43 @@ export const Design = Template.bind({});
 Design.args = {
 	design: SwitchDesign.Graphical,
 	accessibleName: "graphical",
-};
\ No newline at end of file
+};
+
+export const RequiredInForm = Template.bind({});
+RequiredInForm.args = {
+	required: true,
+	name: "termsAndConditions",
+	disabled: false,
+	design: SwitchDesign.Textual,
+	textOn: "Yes",
+	textOff: "No",
+};
+RequiredInForm.decorators = [
+	(story) => {
+		return html`
+		<style>
+			.switch-form {
+				max-width: fit-content;
+				border: 1px solid var(--sapList_BorderColor);
+				border-radius: 0.5rem;
+				padding: 1rem;
+			}
+		</style>
+		<form id="myForm" class="switch-form">
+			<h3 style="margin: 0 0 1rem 0">Switch in Registration form sample</h3>
+			<div style="display: flex; flex-direction: column;">
+				<ui5-input required type="Email" placeholder="Email" value="your@email.com"></ui5-input>
+				<ui5-input required type="Password" placeholder="Password" value="your@email.com"></ui5-input>
+			</div>
+			<div style="display: flex; flex-direction: column; justify-content: center;">
+				<ui5-label for="mySwitch" style="margin: 1rem 0 0 0">Please accept the terms and conditions, in order to proceed</ui5-label>
+				<div style="width: fit-content">
+					${story()}
+				</div>
+			</div>
+			<br>
+			<ui5-button type="Submit">Submit Form</ui5-button>
+		</form>`
+	}
+];
+