@ui5/webcomponents 0.0.0-306572ffa → 0.0.0-3236d56be

package/dist/CheckBox.js

@@ -1,14 +1,20 @@
 import { isDesktop } from "@ui5/webcomponents-base/dist/Device.js";
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
-import { fetchI18nBundle, getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
 import ValueState from "@ui5/webcomponents-base/dist/types/ValueState.js";
 import { getFeature } from "@ui5/webcomponents-base/dist/FeaturesRegistry.js";
+import { getEffectiveAriaLabelText } from "@ui5/webcomponents-base/dist/util/AriaLabelHelper.js";
 import { isSpace, isEnter } from "@ui5/webcomponents-base/dist/Keys.js";
-import "@ui5/webcomponents-icons/dist/icons/accept.js";
+import "@ui5/webcomponents-icons/dist/accept.js";
 import Icon from "./Icon.js";
 import Label from "./Label.js";
-import { VALUE_STATE_ERROR, VALUE_STATE_WARNING } from "./generated/i18n/i18n-defaults.js";
+import WrappingType from "./types/WrappingType.js";
+import {
+	VALUE_STATE_ERROR,
+	VALUE_STATE_WARNING,
+	VALUE_STATE_SUCCESS,
+} from "./generated/i18n/i18n-defaults.js";
 
 // Template
 import CheckBoxTemplate from "./generated/templates/CheckBoxTemplate.lit.js";
@@ -16,6 +22,9 @@ import CheckBoxTemplate from "./generated/templates/CheckBoxTemplate.lit.js";
 // Styles
 import checkboxCss from "./generated/themes/CheckBox.css.js";
 
+let isGlobalHandlerAttached = false;
+let activeCb = null;
+
 /**
  * @public
  */
@@ -25,9 +34,33 @@ const metadata = {
 	properties: /** @lends sap.ui.webcomponents.main.CheckBox.prototype */ {
 
 		/**
-		 * Defines whether the <code>ui5-checkbox</code> is disabled.
+		 * Receives id(or many ids) of the elements that label the component
+		 * @type {string}
+		 * @defaultvalue ""
+		 * @public
+		 * @since 1.1.0
+		 */
+		accessibleNameRef: {
+			type: String,
+			defaultValue: "",
+		},
+
+		/**
+		 * Defines the accessible aria name of the component.
+		 *
+		 * @type {string}
+		 * @public
+		 * @defaultvalue ""
+		 * @since 1.1.0
+		 */
+		accessibleName: {
+			type: String,
+		},
+
+		/**
+		 * Defines whether the component is disabled.
 		 * <br><br>
-		 * <b>Note:</b> A disabled <code>ui5-checkbox</code> is completely noninteractive.
+		 * <b>Note:</b> A disabled component is completely noninteractive.
 		 *
 		 * @type {boolean}
 		 * @defaultvalue false
@@ -38,9 +71,9 @@ const metadata = {
 		},
 
 		/**
-		 * Defines whether the <code>ui5-checkbox</code> is read-only.
+		 * Defines whether the component is read-only.
 		 * <br><br>
-		 * <b>Note:</b> A red-only <code>ui5-checkbox</code> is not editable,
+		 * <b>Note:</b> A red-only component is not editable,
 		 * but still provides visual feedback upon user interaction.
 		 *
 		 * @type {boolean}
@@ -52,10 +85,43 @@ const metadata = {
 		},
 
 		/**
-		 * Defines if the <code>ui5-checkbox</code> is checked.
+		 * Defines whether the component is required.
+		 *
+		 * @type {boolean}
+		 * @defaultvalue false
+		 * @public
+		 * @since 1.3.0
+		 */
+		required: {
+			type: Boolean,
+		},
+
+		/**
+		* Defines whether the component is displayed as partially checked.
+		* <br><br>
+		* <b>Note:</b> The indeterminate state can be set only programatically and can’t be achieved by user
+		* interaction and the resulting visual state depends on the values of the <code>indeterminate</code>
+		* and <code>checked</code> properties:
+		* <ul>
+		* <li> If the component is checked and indeterminate, it will be displayed as partially checked
+		* <li> If the component is checked and it is not indeterminate, it will be displayed as checked
+		* <li> If the component is not checked, it will be displayed as not checked regardless value of the indeterminate attribute
+		* </ul>
+		*
+		* @type {boolean}
+		* @defaultvalue false
+		* @public
+		* @since 1.0.0-rc.15
+		*/
+		indeterminate: {
+			type: Boolean,
+		},
+
+		/**
+		 * Defines if the component is checked.
 		 * <br><br>
 		 * <b>Note:</b> The property can be changed with user interaction,
-		 * either by cliking/tapping on the <code>ui5-checkbox</code>, or by
+		 * either by cliking/tapping on the component, or by
 		 * pressing the Enter or Space key.
 		 *
 		 * @type {boolean}
@@ -67,7 +133,7 @@ const metadata = {
 		},
 
 		/**
-		 * Defines the text of the <code>ui5-checkbox</code>.
+		 * Defines the text of the component.
 		 *
 		 * @type {string}
 		 * @defaultvalue ""
@@ -78,9 +144,18 @@ const metadata = {
 		},
 
 		/**
-		 * Defines the value state of the <code>ui5-checkbox</code>.
+		 * Defines the value state of the component.
+		 *
 		 * <br><br>
-		 * <b>Note:</b> Available options are <code>Warning</code>, <code>Error</code>, and <code>None</code> (default).
+		 * <b>Note:</b>
+		 *
+		 * <ul>
+		 * <li><code>Warning</code></li>
+		 * <li><code>Error</code></li>
+		 * <li><code>None</code>(default)</li>
+		 * <li><code>Success</code></li>
+		 * <li><code>Information</code></li>
+		 * </ul>
 		 *
 		 * @type {ValueState}
 		 * @defaultvalue "None"
@@ -92,20 +167,25 @@ const metadata = {
 		},
 
 		/**
-		 * Defines whether the <code>ui5-checkbox</code> text wraps when there is not enough space.
+		 * Defines whether the component text wraps when there is not enough space.
 		 * <br><br>
-		 * <b>Note:</b> By default, the text truncates when there is not enough space.
+		 * Available options are:
+		 * <ul>
+		 * <li><code>None</code> - The text will be truncated with an ellipsis.</li>
+		 * <li><code>Normal</code> - The text will wrap. The words will not be broken based on hyphenation.</li>
+		 * </ul>
 		 *
-		 * @type {boolean}
-		 * @defaultvalue false
+		 * @type {WrappingType}
+		 * @defaultvalue "None"
 		 * @public
 		 */
-		wrap: {
-			type: Boolean,
+		 wrappingType: {
+			type: WrappingType,
+			defaultValue: WrappingType.None,
 		},
 
 		/**
-		 * Determines the name with which the <code>ui5-checkbox</code> will be submitted in an HTML form.
+		 * 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:
@@ -113,7 +193,7 @@ const metadata = {
 		 *
 		 * <br><br>
 		 * <b>Note:</b> When set, a native <code>input</code> HTML element
-		 * will be created inside the <code>ui5-checkbox</code> so that it can be submitted as
+		 * 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}
@@ -125,31 +205,35 @@ const metadata = {
 		},
 
 		/**
-		 * Determines the <code>aria-label</code>, set on the component root tag.
-		 * @type {string}
-		 * @defaultvalue undefined
+		 * Defines the active state (pressed or not) of the component.
 		 * @private
-		 * @since 1.0.0-rc.8
 		 */
-		ariaLabel: {
-			type: String,
-			defaultValue: undefined,
-		},
-
-		_label: {
-			type: Object,
+		active: {
+			type: Boolean,
 		},
 	},
 	events: /** @lends sap.ui.webcomponents.main.CheckBox.prototype */ {
 
 		/**
-		 * Fired when the <code>ui5-checkbox</code> checked state changes.
+		 * Fired when the component checked state changes.
 		 *
 		 * @public
 		 * @event
 		 */
 		change: {},
 	},
+	slots: /** @lends sap.ui.webcomponents.main.CheckBox.prototype */ {
+		/**
+		 * The slot is used to render native <code>input</code> HTML element within Light DOM to enable form submit,
+		 * when <code>name</code> property is set.
+		 * @type {HTMLElement[]}
+		 * @slot
+		 * @private
+		 */
+		formSupport: {
+			type: HTMLElement,
+		},
+	},
 };
 
 /**
@@ -169,8 +253,8 @@ const metadata = {
  *
  * <h3>Usage</h3>
  *
- * You can manually set the width of the element containing the box and the label using the <code>width</code> property.
- * If the text exceeds the available width, it is truncated.
+ * You can define the checkbox text with via the <code>text</code> property. If the text exceeds the available width, it is truncated by default.
+ * In case you prefer text to wrap, set the <code>wrappingType</code> property to "Normal".
  * The touchable area for toggling the <code>ui5-checkbox</code> ends where the text ends.
  * <br><br>
  * You can disable the <code>ui5-checkbox</code> by setting the <code>disabled</code> property to
@@ -178,6 +262,15 @@ const metadata = {
  * or use the <code>ui5-checkbox</code> in read-only mode by setting the <code>readonly</code>
  * property to <code>true</code>.
  *
+ * <br><br>
+ * <h3>Keyboard Handling</h3>
+ *
+ * The user can use the following keyboard shortcuts to toggle the checked state of the <code>ui5-checkbox</code>.
+ * <ul>
+ * <li>[SPACE, ENTER] - Toggles between different states: checked, not checked.</li>
+ * </ul>
+ * <br><br>
+ *
  * <h3>ES6 Module Import</h3>
  *
  * <code>import "@ui5/webcomponents/dist/CheckBox";</code>
@@ -209,23 +302,22 @@ class CheckBox extends UI5Element {
 	constructor() {
 		super();
 
-		this._label = {};
-		this.i18nBundle = getI18nBundle("@ui5/webcomponents");
+		this._deactivate = () => {
+			if (activeCb) {
+				activeCb.active = false;
+			}
+		};
+
+		if (!isGlobalHandlerAttached) {
+			document.addEventListener("mouseup", this._deactivate);
+			isGlobalHandlerAttached = true;
+		}
 	}
 
 	onBeforeRendering() {
-		this.syncLabel();
-
 		this._enableFormSupport();
 	}
 
-	syncLabel() {
-		this._label = Object.assign({}, this._label);
-		this._label.text = this.text;
-		this._label.wrap = this.wrap;
-		this._label.textDirection = this.textDirection;
-	}
-
 	_enableFormSupport() {
 		const FormSupport = getFeature("FormSupport");
 		if (FormSupport) {
@@ -242,13 +334,32 @@ class CheckBox extends UI5Element {
 		this.toggle();
 	}
 
+	_onmousedown() {
+		if (this.readonly || this.disabled) {
+			return;
+		}
+
+		this.active = true;
+		activeCb = this; // eslint-disable-line
+	}
+
+	_onmouseup() {
+		this.active = false;
+	}
+
+	_onfocusout() {
+		this.active = false;
+	}
+
 	_onkeydown(event) {
 		if (isSpace(event)) {
 			event.preventDefault();
+			this.active = true;
 		}
 
 		if (isEnter(event)) {
 			this.toggle();
+			this.active = true;
 		}
 	}
 
@@ -256,11 +367,19 @@ class CheckBox extends UI5Element {
 		if (isSpace(event)) {
 			this.toggle();
 		}
+
+		this.active = false;
 	}
 
 	toggle() {
 		if (this.canToggle()) {
-			this.checked = !this.checked;
+			if (this.indeterminate) {
+				this.indeterminate = false;
+				this.checked = true;
+			} else {
+				this.checked = !this.checked;
+			}
+
 			this.fireEvent("change");
 			// Angular two way data binding
 			this.fireEvent("value-changed");
@@ -273,14 +392,17 @@ class CheckBox extends UI5Element {
 	}
 
 	valueStateTextMappings() {
-		const i18nBundle = this.i18nBundle;
-
 		return {
-			"Error": i18nBundle.getText(VALUE_STATE_ERROR),
-			"Warning": i18nBundle.getText(VALUE_STATE_WARNING),
+			"Error": CheckBox.i18nBundle.getText(VALUE_STATE_ERROR),
+			"Warning": CheckBox.i18nBundle.getText(VALUE_STATE_WARNING),
+			"Success": CheckBox.i18nBundle.getText(VALUE_STATE_SUCCESS),
 		};
 	}
 
+	get ariaLabelText() {
+		return getEffectiveAriaLabelText(this);
+	}
+
 	get classes() {
 		return {
 			main: {
@@ -297,8 +419,16 @@ class CheckBox extends UI5Element {
 		return this.disabled ? "true" : undefined;
 	}
 
+	get ariaChecked() {
+		return this.indeterminate && this.checked ? "mixed" : this.checked;
+	}
+
 	get ariaLabelledBy() {
-		return this.text ? `${this._id}-label` : undefined;
+		if (!this.ariaLabelText) {
+			return this.text ? `${this._id}-label` : undefined;
+		}
+
+		return undefined;
 	}
 
 	get ariaDescribedBy() {
@@ -318,6 +448,10 @@ class CheckBox extends UI5Element {
 		return this.disabled ? undefined : tabindex || "0";
 	}
 
+	get isCompletelyChecked() {
+		return this.checked && !this.indeterminate;
+	}
+
 	static get dependencies() {
 		return [
 			Label,
@@ -326,7 +460,7 @@ class CheckBox extends UI5Element {
 	}
 
 	static async onDefine() {
-		await fetchI18nBundle("@ui5/webcomponents");
+		CheckBox.i18nBundle = await getI18nBundle("@ui5/webcomponents");
 	}
 }