@ui5/webcomponents-fiori 1.0.0 → 1.1.1

package/src/DynamicSideContent.js

@@ -0,0 +1,567 @@
+import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
+import { getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
+import ResizeHandler from "@ui5/webcomponents-base/dist/delegate/ResizeHandler.js";
+import SideContentPosition from "./types/SideContentPosition.js";
+import SideContentVisibility from "./types/SideContentVisibility.js";
+import SideContentFallDown from "./types/SideContentFallDown.js";
+import DynamicSideContentTemplate from "./generated/templates/DynamicSideContentTemplate.lit.js";
+
+// Styles
+import DynamicSideContentCss from "./generated/themes/DynamicSideContent.css.js";
+
+// Texts
+import {
+	DSC_SIDE_ARIA_LABEL,
+} from "./generated/i18n/i18n-defaults.js";
+
+// Breakpoint-related constants
+const S_M_BREAKPOINT = 720,	// Breakpoint between S and M screen sizes
+	M_L_BREAKPOINT = 1024, // Breakpoint between M and L screen sizes
+	L_XL_BREAKPOINT = 1440, // Breakpoint between L and XL screen sizes
+	MINIMUM_WIDTH_BREAKPOINT = 960; // Minimum width of the control where main and side contents are side by side
+
+/**
+ * @public
+ */
+const metadata = {
+	tag: "ui5-dynamic-side-content",
+	managedSlots: true,
+	properties: /** @lends sap.ui.webcomponents.fiori.DynamicSideContent.prototype */ {
+
+		/**
+		 * Defines the visibility of the main content.
+		 *
+		 * @type {boolean}
+		 * @defaultvalue false
+		 * @public
+		 *
+		 */
+		 hideMainContent: {
+			type: Boolean,
+		},
+
+		/**
+		 * Defines the visibility of the side content.
+		 *
+		 * @type {boolean}
+		 * @defaultvalue false
+		 * @public
+		 *
+		 */
+		hideSideContent: {
+			type: Boolean,
+		},
+
+		/**
+		 * Defines whether the side content is positioned before the main content (left side
+		 * in LTR mode), or after the the main content (right side in LTR mode).
+		 *
+		 * <br><br>
+		 * <b>The available values are:</b>
+		 *
+		 * <ul>
+		 * <li><code>Start</code></li>
+		 * <li><code>End</code></li>
+		 * </ul>
+		 *
+		 * @type {SideContentPosition}
+		 * @defaultvalue "End"
+		 * @public
+		 *
+		 */
+		 sideContentPosition: {
+			type: SideContentPosition,
+			defaultValue: SideContentPosition.End,
+		},
+
+		/**
+		 * Defines on which breakpoints the side content is visible.
+		 *
+		 * <br><br>
+		 * <b>The available values are:</b>
+		 *
+		 * <ul>
+		 * <li><code>AlwaysShow</code></li>
+		 * <li><code>ShowAboveL</code></li>
+		 * <li><code>ShowAboveM</code></li>
+		 * <li><code>ShowAboveS</code></li>
+		 * <li><code>NeverShow</code></li>
+		 * </ul>
+		 *
+		 * @type {SideContentVisibility}
+		 * @defaultvalue "ShowAboveS"
+		 * @public
+		 *
+		 */
+		sideContentVisibility: {
+			type: SideContentVisibility,
+			defaultValue: SideContentVisibility.ShowAboveS,
+		},
+
+		/**
+		 * Defines on which breakpoints the side content falls down below the main content.
+		 *
+		 * <br><br>
+		 * <b>The available values are:</b>
+		 *
+		 * <ul>
+		 * <li><code>BelowXL</code></li>
+		 * <li><code>BelowL</code></li>
+		 * <li><code>BelowM</code></li>
+		 * <li><code>OnMinimumWidth</code></li>
+		 * </ul>
+		 *
+		 * @type {SideContentFallDown}
+		 * @defaultvalue "OnMinimumWidth"
+		 * @public
+		 *
+		 */
+		sideContentFallDown: {
+			type: SideContentFallDown,
+			defaultValue: SideContentFallDown.OnMinimumWidth,
+		},
+
+		/**
+		 * Defines whether the component is in equal split mode. In this mode, the side and
+		 * the main content take 50:50 percent of the container on all screen sizes
+		 * except for phone, where the main and side contents are switching visibility
+		 * using the toggle method.
+		 *
+		 * @type {boolean}
+		 * @defaultvalue false
+		 * @public
+		 *
+		 */
+		equalSplit: {
+			type: Boolean,
+		},
+
+		/**
+ 		 * @private
+		 */
+		_mcSpan: {
+			type: String,
+			defaultValue: "0",
+			noAttribute: true,
+		},
+
+		/**
+ 		 * @private
+		 */
+		 _scSpan: {
+			type: String,
+			defaultValue: "0",
+			noAttribute: true,
+		},
+
+		/**
+ 		 * @private
+		 */
+		 _toggled: {
+			type: Boolean,
+			noAttribute: true,
+		},
+
+		/**
+ 		 * @private
+		 */
+		 _currentBreakpoint: {
+			type: String,
+			noAttribute: true,
+		},
+
+	},
+	slots: /** @lends sap.ui.webcomponents.fiori.DynamicSideContent.prototype */ {
+
+		/**
+		 * Defines the main content.
+		 *
+		 * @type {HTMLElement[]}
+		 * @slot
+		 * @public
+		 */
+		"default": {
+			type: HTMLElement,
+		},
+
+		/**
+		 * Defines the side content.
+		 *
+		 * @type {HTMLElement[]}
+		 * @slot
+		 * @public
+		 */
+		 "sideContent": {
+			type: HTMLElement,
+		},
+
+	},
+	events: /** @lends sap.ui.webcomponents.fiori.DynamicSideContent.prototype */ {
+
+		/**
+		 * Fires when the current breakpoint has been changed.
+		 * @event sap.ui.webcomponents.fiori.DynamicSideContent#layout-change
+		 * @param {String} currentBreakpoint the current breakpoint.
+		 * @param {String} previousBreakpoint the breakpoint that was active before change to current breakpoint.
+		 * @param {Boolean} mainContentVisible visibility of the main content.
+		 * @param {Boolean} sideContentVisible visibility of the side content.
+		 * @public
+		 */
+		"layout-change": {
+			details: {
+				currentBreakpoint: {
+					type: String,
+				},
+				previousBreakpoint: {
+					type: String,
+				},
+				mainContentVisible: {
+					type: Boolean,
+				},
+				sideContentVisible: {
+					type: Boolean,
+				},
+			},
+		},
+
+	},
+};
+
+/**
+ * @class
+ *
+ * <h3 class="comment-api-title">Overview</h3>
+ *
+ * The DynamicSideContent (<code>ui5-dynamic-side-content</code>) is a layout component that allows additional content
+ * to be displayed in a way that flexibly adapts to different screen sizes. The side
+ * content appears in a container next to or directly below the main content
+ * (it doesn't overlay). When the side content is triggered, the main content becomes
+ * narrower (if appearing side-by-side). The side content contains a separate scrollbar
+ * when appearing next to the main content.
+ *
+ *
+ * <h3>Usage</h3>
+ *
+ * <i>When to use?</i>
+ *
+ * Use this component if you want to display relevant information that is not critical
+ * for users to complete a task. Users should have access to all the key functions and
+ * critical information in the app even if they do not see the side content. This is
+ * important because on smaller screen sizes it may be difficult to display the side
+ * content in a way that is easily accessible for the user.
+ *
+ * <i>When not to use?</i>
+ *
+ * Don't use it if you want to display navigation or critical information that prevents
+ * users from completing a task when they have no access to the side content.
+ *
+ *
+ * <h3>Responsive Behavior</h3>
+ *
+ * Screen width > 1440px
+ *
+ * <ul><li>Main vs. side content ratio is 75 vs. 25 percent (with a minimum of 320px
+ * each).</li>
+ * <li>If the application defines a trigger, the side content can be hidden.</li></ul>
+ *
+ * Screen width <= 1440px and > 1024px
+ *
+ * <ul><li>Main vs. side content ratio is 66.666 vs. 33.333 percent (with a minimum of
+ * 320px each). If the side content width falls below 320 px, it automatically slides
+ * under the main content, unless the app development team specifies that it should
+ * disappear.</li></ul>
+ *
+ * Screen width <= 1024px and > 720px
+ *
+ * <ul><li>The side content ratio is fixed to 340px, and the main content takes the rest
+ * of the width. Only if the <code>sideContentFallDown</code> is set to <code>OnMinimumWidth</code>
+ * and screen width is <= 960px and > 720px the side content falls below the main content.</li></ul>
+ *
+ * Screen width <= 720px (for example on a mobile device)
+ *
+ * <ul><li>In this case, the side content automatically disappears from the screen (unless
+ * specified to stay under the content by setting of <code>sideContentVisibility</code>
+ * property to <code>AlwaysShow</code>) and can be triggered from a pre-set trigger
+ * (specified within the app). When the side content is triggered, it replaces the main
+ * content. We recommend that you always place the trigger for the side content in the
+ * same location, such as in the app footer.</li></ul>
+ *
+ * A special case allows switching the comparison mode between the main and side content.
+ * In this case, the screen is split into 50:50 percent for main vs. side content. The
+ * responsive behavior of the equal split is the same as in the standard view - the
+ * side content disappears on screen widths of less than 720 px and can only be
+ * viewed by triggering it.
+ *
+ * <h3>ES6 Module Import</h3>
+ *
+ * <code>import "@ui5/webcomponents-fiori/dist/DynamicSideContent";</code>
+ *
+ * @constructor
+ * @author SAP SE
+ * @alias sap.ui.webcomponents.fiori.DynamicSideContent
+ * @extends UI5Element
+ * @tagname ui5-dynamic-side-content
+ * @public
+ * @since 1.1.0
+ */
+class DynamicSideContent extends UI5Element {
+	constructor() {
+		super();
+		this._handleResizeBound = this.handleResize.bind(this);
+	}
+
+	static get metadata() {
+		return metadata;
+	}
+
+	static get styles() {
+		return DynamicSideContentCss;
+	}
+
+	static get render() {
+		return litRender;
+	}
+
+	static get template() {
+		return DynamicSideContentTemplate;
+	}
+
+	static async onDefine() {
+		DynamicSideContent.i18nBundle = await getI18nBundle("@ui5/webcomponents-fiori");
+	}
+
+	onAfterRendering() {
+		this._resizeContents();
+	}
+
+	onEnterDOM() {
+		ResizeHandler.register(this, this._handleResizeBound);
+	}
+
+	onExitDOM() {
+		ResizeHandler.deregister(this, this._handleResizeBound);
+	}
+
+	/**
+	 * Toggles visibility of main and side contents on S screen size (mobile device).
+	 * @type {String}
+	 * @public
+	 */
+	 toggleContents() {
+		if (this.breakpoint === this.sizeS && this.sideContentVisibility !== SideContentVisibility.AlwaysShow) {
+			this._toggled = !this._toggled;
+		}
+	}
+
+	get classes() {
+		const gridPrefix = "ui5-dsc-span",
+			mcSpan = this._toggled ? this._scSpan : this._mcSpan,
+			scSpan = this._toggled ? this._mcSpan : this._scSpan,
+			classes = {
+				main: {
+					"ui5-dsc-main": true,
+				},
+				side: {
+					"ui5-dsc-side": true,
+				},
+			};
+
+		classes.main[`${gridPrefix}-${mcSpan}`] = true;
+		classes.side[`${gridPrefix}-${scSpan}`] = true;
+
+		return classes;
+	}
+
+	get styles() {
+		const isToggled = this.breakpoint === this.sizeS && this._toggled,
+			mcSpan = isToggled ? this._scSpan : this._mcSpan,
+			scSpan = isToggled ? this._mcSpan : this._scSpan,
+			contentHeight = this.breakpoint === this.sizeS && this.sideContentVisibility !== SideContentVisibility.AlwaysShow ? "100%" : "auto";
+
+		return {
+			root: {
+				"flex-wrap": this._mcSpan === "12" ? "wrap" : "nowrap",
+			},
+			main: {
+				"height": mcSpan === this.span12 ? contentHeight : "100%",
+				"order": this.sideContentPosition === SideContentPosition.Start ? 2 : 1,
+			},
+			side: {
+				"height": scSpan === this.span12 ? contentHeight : "100%",
+				"order": this.sideContentPosition === SideContentPosition.Start ? 1 : 2,
+			},
+		};
+	}
+
+	get accInfo() {
+		return {
+			"label": DynamicSideContent.i18nBundle.getText(DSC_SIDE_ARIA_LABEL),
+		};
+	}
+
+	get sizeS() {
+		return "S";
+	}
+
+	get sizeM() {
+		return "M";
+	}
+
+	get sizeL() {
+		return "L";
+	}
+
+	get sizeXL() {
+		return "XL";
+	}
+
+	get span0() {
+		return "0";
+	}
+
+	get span3() {
+		return "3";
+	}
+
+	get span4() {
+		return "4";
+	}
+
+	get span6() {
+		return "6";
+	}
+
+	get span8() {
+		return "8";
+	}
+
+	get span9() {
+		return "9";
+	}
+
+	get span12() {
+		return "12";
+	}
+
+	get spanFixed() {
+		return "fixed";
+	}
+
+	get containerWidth() {
+		return this.parentElement.clientWidth;
+	}
+
+	get breakpoint() {
+		let size;
+
+		if (this.containerWidth <= S_M_BREAKPOINT) {
+			size = this.sizeS;
+		} else if (this.containerWidth > S_M_BREAKPOINT && this.containerWidth <= M_L_BREAKPOINT) {
+			size = this.sizeM;
+		} else if (this.containerWidth > M_L_BREAKPOINT && this.containerWidth <= L_XL_BREAKPOINT) {
+			size = this.sizeL;
+		} else {
+			size = this.sizeXL;
+		}
+
+		return size;
+	}
+
+	handleResize() {
+		this._resizeContents();
+	}
+
+	_resizeContents() {
+		let mainSize,
+			sideSize,
+			sideVisible;
+
+		// initial set contents sizes
+		switch (this.breakpoint) {
+		case this.sizeS:
+			mainSize = this.span12;
+			sideSize = this.span12;
+			break;
+		case this.sizeM:
+			if (this.sideContentFallDown === SideContentFallDown.BelowXL
+				|| this.sideContentFallDown === SideContentFallDown.BelowL
+				|| (this.containerWidth <= MINIMUM_WIDTH_BREAKPOINT && this.sideContentFallDown === SideContentFallDown.OnMinimumWidth)) {
+				mainSize = this.span12;
+				sideSize = this.span12;
+			} else {
+				mainSize = this.equalSplit ? this.span6 : this.spanFixed;
+				sideSize = this.equalSplit ? this.span6 : this.spanFixed;
+			}
+			sideVisible = this.sideContentVisibility === SideContentVisibility.ShowAboveS
+				|| this.sideContentVisibility === SideContentVisibility.AlwaysShow;
+			break;
+		case this.sizeL:
+			if (this.sideContentFallDown === SideContentFallDown.BelowXL) {
+				mainSize = this.span12;
+				sideSize = this.span12;
+			} else {
+				mainSize = this.equalSplit ? this.span6 : this.span8;
+				sideSize = this.equalSplit ? this.span6 : this.span4;
+			}
+			sideVisible = this.sideContentVisibility === SideContentVisibility.ShowAboveS
+				|| this.sideContentVisibility === SideContentVisibility.ShowAboveM
+				|| this.sideContentVisibility === SideContentVisibility.AlwaysShow;
+			break;
+		case this.sizeXL:
+			mainSize = this.equalSplit ? this.span6 : this.span9;
+			sideSize = this.equalSplit ? this.span6 : this.span3;
+			sideVisible = this.sideContentVisibility !== SideContentVisibility.NeverShow;
+		}
+
+		if (this.sideContentVisibility === SideContentVisibility.AlwaysShow) {
+			sideVisible = true;
+		}
+
+		// modify sizes of the contents depending on hideMainContent and hideSideContent properties
+		if (this.hideSideContent) {
+			mainSize = this.hideMainContent ? this.span0 : this.span12;
+			sideSize = this.span0;
+			sideVisible = false;
+		}
+
+		if (this.hideMainContent) {
+			mainSize = this.span0;
+			sideSize = this.hideSideContent ? this.span0 : this.span12;
+			sideVisible = true;
+		}
+
+		// set final sizes of the contents
+		if (!sideVisible) {
+			mainSize = this.span12;
+			sideSize = this.span0;
+		}
+
+		// fire "layout-change" event
+		if (this._currentBreakpoint !== this.breakpoint) {
+			const eventParams = {
+				currentBreakpoint: this.breakpoint,
+				previousBreakpoint: this._currentBreakpoint,
+				mainContentVisible: mainSize !== this.span0,
+				sideContentVisible: sideSize !== this.span0,
+			};
+			this.fireEvent("layout-change", eventParams);
+			this._currentBreakpoint = this.breakpoint;
+		}
+
+		// update contents sizes
+		this._setSpanSizes(mainSize, sideSize);
+	}
+
+	_setSpanSizes(mainSize, sideSize) {
+		this._mcSpan = mainSize;
+		this._scSpan = sideSize;
+		if (this.breakpoint !== this.sizeS) {
+			this._toggled = false;
+		}
+	}
+}
+
+DynamicSideContent.define();
+
+export default DynamicSideContent;

package/src/FlexibleColumnLayout.hbs

@@ -1,39 +1,38 @@
 <div class="{{classes.root}}">
 	<div
-		role="region"
+		role="{{accStartColumnRole}}"
 		class="{{classes.columns.start}}"
 		aria-labelledby="{{_id}}-startColumnText"
 	>
+		<span id="{{_id}}-startColumnText" class="ui5-hidden-text">{{accStartColumnText}}</span>
 		<slot name="startColumn"></slot>
 	</div>
 
-	<div class="ui5-fcl-arrow-container" style="{{styles.arrowsContainer.start}}">
+	<div role="{{accStartArrowContainerRole}}" aria-label={{accStartArrowContainerText}} class="ui5-fcl-arrow-container ui5-fcl-arrow-container-start" style="{{styles.arrowsContainer.start}}">
 		{{> startArrow}}
 	</div>
 
 	<div
-		role="region"
+		role="{{accMiddleColumnRole}}"
 		class="{{classes.columns.middle}}"
 		aria-labelledby="{{_id}}-midColumnText"
 	>
+		<span id="{{_id}}-midColumnText" class="ui5-hidden-text">{{accMiddleColumnText}}</span>
 		<slot name="midColumn"></slot>
 	</div>
 
-	<div class="ui5-fcl-arrow-container" style="{{styles.arrowsContainer.end}}">
+	<div role="{{accEndArrowContainerRole}}" aria-label="{{accEndArrowContainerText}}" class="ui5-fcl-arrow-container ui5-fcl-arrow-container-end" style="{{styles.arrowsContainer.end}}">
 		{{> endArrow}}
 	</div>
 
 	<div
-		role="region"
+		role="{{accEndColumnRole}}"
 		class="{{classes.columns.end}}"
 		aria-labelledby="{{_id}}-endColumnText"
 	>
+		<span id="{{_id}}-endColumnText" class="ui5-hidden-text">{{accEndColumnText}}</span>
 		<slot name="endColumn"></slot>
 	</div>
-
-	<span id="{{_id}}-startColumnText" class="ui5-hidden-text">{{accStartColumnText}}</span>
-	<span id="{{_id}}-midColumnText" class="ui5-hidden-text">{{accMiddleColumnText}}</span>
-	<span id="{{_id}}-endColumnText" class="ui5-hidden-text">{{accEndColumnText}}</span>
 </div>
 
 {{#*inline "startArrow"}}

package/src/FlexibleColumnLayout.js

@@ -39,6 +39,7 @@ import FlexibleColumnLayoutCss from "./generated/themes/FlexibleColumnLayout.css
  */
 const metadata = {
 	tag: "ui5-flexible-column-layout",
+	fastNavigation: true,
 	properties: /** @lends sap.ui.webcomponents.fiori.FlexibleColumnLayout.prototype */ {
 		/**
 		 * Defines the columns layout and their proportion.
@@ -94,6 +95,8 @@ const metadata = {
 		 *  - <code>startArrowRightText</code>: the text that the first arrow (between the <code>begin</code> and <code>mid</code> columns) will have when pointing to the right
 		 *  - <code>endArrowLeftText</code>: the text that the second arrow (between the <code>mid</code> and <code>end</code> columns) will have when pointing to the left
 		 *  - <code>endArrowRightText</code>: the text that the second arrow (between the <code>mid</code> and <code>end</code> columns) will have when pointing to the right
+		 *  - <code>startArrowContainerAccessibleName</code>: the text that the first arrow container (between the <code>begin</code> and <code>mid</code> columns) will have as <code>aria-label</code>
+		 *  - <code>endArrowContainerAccessibleName</code>: the text that the second arrow container (between the <code>mid</code> and <code>end</code> columns) will have as <code>aria-label</code>
 		 *
 		 * @type {object}
 		 * @public
@@ -103,6 +106,24 @@ const metadata = {
 			type: Object,
 		},
 
+		/**
+		 * An object of strings that defines additional accessibility roles for further customization.
+		 *
+		 * It supports the following fields:
+		 *  - <code>startColumnRole</code>: the accessibility role for the <code>startColumn</code>
+		 *  - <code>startArrowContainerRole</code>: the accessibility role for the first arrow container (between the <code>begin</code> and <code>mid</code> columns)
+		 *  - <code>midColumnRole</code>: the accessibility role for the <code>midColumn</code>
+		 *  - <code>endArrowContainerRole</code>: the accessibility role for the second arrow container (between the <code>mid</code> and <code>end</code> columns)
+		 *  - <code>endColumnRole</code>: the accessibility role for the <code>endColumn</code>
+		 *
+		 * @type {object}
+		 * @public
+		 * @since 1.1.0
+		 */
+		accessibilityRoles: {
+			type: Object,
+		},
+
 		/**
 		* Defines the component width in px.
 		*
@@ -235,9 +256,18 @@ const metadata = {
  * <br><br>
  * <h3>Keyboard Handling</h3>
  *
+ * <h4>Basic Navigation</h4>
  * <ul>
  * <li>[SPACE, ENTER, RETURN] - If focus is on the layout toggle button (arrow button), once activated, it triggers the associated action (such as expand/collapse the column).</li>
+ * <li>This component provides a build in fast navigation group which can be used via <code>F6 / Shift + F6</code> or <code> Ctrl + Alt(Option) + Down /  Ctrl + Alt(Option) + Up</code>.
+ * In order to use this functionality, you need to import the following module:
+ * <code>import "@ui5/webcomponents-base/dist/features/F6Navigation.js"</code></li>
  * </ul>
+ *
+ * <h4>Fast Navigation</h4>
+ * This component provides a build in fast navigation group which can be used via <code>F6 / Shift + F6</code> or <code> Ctrl + Alt(Option) + Down /  Ctrl + Alt(Option) + Up</code>.
+ * In order to use this functionality, you need to import the following module:
+ * <code>import "@ui5/webcomponents-base/dist/features/F6Navigation.js"</code>
  * <br><br>
  *
  * <h3>ES6 Module Import</h3>
@@ -666,6 +696,34 @@ class FlexibleColumnLayout extends UI5Element {
 		return this.accessibilityTexts.endColumnAccessibleName || FlexibleColumnLayout.i18nBundle.getText(FCL_END_COLUMN_TXT);
 	}
 
+	get accStartArrowContainerText() {
+		return this.accessibilityTexts.startArrowContainerAccessibleName || undefined;
+	}
+
+	get accEndArrowContainerText() {
+		return this.accessibilityTexts.endArrowContainerAccessibleName || undefined;
+	}
+
+	get accStartColumnRole() {
+		return this.accessibilityRoles.startColumnRole || "region";
+	}
+
+	get accMiddleColumnRole() {
+		return this.accessibilityRoles.midColumnRole || "region";
+	}
+
+	get accEndColumnRole() {
+		return this.accessibilityRoles.endColumnRole || "region";
+	}
+
+	get accStartArrowContainerRole() {
+		return this.accessibilityRoles.startArrowContainerRole || undefined;
+	}
+
+	get accEndArrowContainerRole() {
+		return this.accessibilityRoles.endArrowContainerRole || undefined;
+	}
+
 	get _effectiveLayoutsByMedia() {
 		return this._layoutsConfiguration || getLayoutsByMedia();
 	}