feat(ui5-user-settings-dialog): introduce new components UserSettingsDialog, UserSettingsItem, and UserSettingsView

[dobromiraboycheva]

The change introduces several components - UserSettingsDialog, UserSettingsItem, and UserSettingsView to build application forms more easily and according to the latest design guidelines.

Overview

The user settings dialog is used to display and operate preferences in a size-limited window in front of the regular app screen. It prompts the user for an action or confirmation and acts as a container that can hold any control.

Structure

• UserSettingsDialog (ui5-user-settings-dialog) is the top-level container component, responsible for the content layout and responsiveness.
• UserSettingsItem (ui5-user-setting-item) represents the details of a setting with name, icon, title, and state. It builds the layout based on the content.
• UserSettingsView (ui5-user-settings-view) is each option of the setting which will be shown in the content.
  The user settings dialog contains title, search, settings list as well as fixed settings, content area and close button.
  The content can include a page, tabs or pages with a secondary page.

UserSettingsItem with content page.

<ui5-user-settings-dialog id="settings" header-text="Settings" show-search-field>
	<ui5-user-settings-item icon="user-settings" text="User Account" tooltip="User Account" header-text="User Account">
		<ui5-user-settings-view slot="pages">
			<ui5-icon name="person-placeholder"></ui5-icon><ui5-title level="H3" size="H3" style='display:inline; margin:0.5rem'>Alain Chevalier</ui5-title>
			<div>
				<ui5-label>Name:</ui5-label><ui5-text style="display: inline;">Alain Chevalier</ui5-text><br/>
				<ui5-label>Email:</ui5-label><ui5-text style="display: inline;">[email protected]</ui5-text><br/>
				<ui5-label>Server:</ui5-label><ui5-text style="display: inline;">delivery-001.sap.com</ui5-text><br/>
			</div>
			<ui5-label>Personalization</ui5-label><br/>
			<ui5-button id="reset-all-button">Reset All Personalization</ui5-button>
			<ui5-panel fixed>
				<ui5-label>
					Reset your personalization settings for the launchpad (such as theme, language, user activities, and home page content).
				</ui5-label>
			</ui5-panel>
		</ui5-user-settings-view>
	</ui5-user-settings-item>
</ui5-user-settings-dialog>

UserSettingsItem with content tabs.

<ui5-user-settings-dialog id="settings" header-text="Settings" show-search-field>
	<ui5-user-settings-item icon="palette" text="Appearance" tooltip="Appearance" header-text="Appearance">
		<ui5-user-settings-view text="Themes">
			<ui5-list separators="Inner">
				<ui5-li icon="palette">SAP Morning Horizon</ui5-li>
				<ui5-li icon="palette">SAP Evening Horizon</ui5-li>
				<ui5-li icon="palette">SAP High Contrast Black (SAP Horizon)</ui5-li>
				<ui5-li icon="palette">SAP High Contrast White (SAP Horizon)</ui5-li>
			</ui5-list>
			<ui5-button id="themeSave" style="float: right;">Save</ui5-button>
			<ui5-toast design="Emphasized">Changes applied.</ui5-toast>
		</ui5-user-settings-view>
		<ui5-user-settings-view text="Display settings">
			<ui5-checkbox checked text="Optimized for Touch Input"></ui5-checkbox>
			<ui5-panel fixed>
				<ui5-label>
					Increases the size and spacing of controls to allow you to interact with them more easily using your fingertip.
					This is useful for hybrid devices that combine touch and mouse events.
				</ui5-label>
			</ui5-panel>
		</ui5-user-settings-view>
	</ui5-user-settings-item>
</ui5-user-settings-dialog>

UserSettingsItem content of pages with a secondary page. Here we can navigate back to the main page.

<ui5-user-settings-dialog id="settings" header-text="Settings" show-search-field>
	<ui5-user-settings-item icon="iphone" text="SAP Mobile Start Application" tooltip="SAP Mobile Start Application" header-text="SAP Mobile Start Application">
		<ui5-user-settings-view slot="pages">
			<ui5-button id="mobile1-button">iOS</ui5-button>
			<ui5-button id="mobile2-button">Android</ui5-button>
		</ui5-user-settings-view>

		<ui5-user-settings-view slot="pages" text="Inner Page" id="mobile-second-page" secondary>
			<ui5-text>Enable access to your site from the SAP Mobile Start application.</ui5-text>
			<ui5-button id="mobile-install">Install</ui5-button><ui5-button id="mobile-register">Register</ui5-button>
			<ui5-text>Scan the QR Code to install the mobile application</ui5-text>
			<ui5-icon name="qr-code" style="width: 20rem; height: 20rem;"></ui5-icon>
		</ui5-user-settings-view>
	</ui5-user-settings-item>
</ui5-user-settings-dialog>

To be possible this navigation we should add some JavaScript code.
In this case, it will look like this:

const mobileSecondPage = document.getElementById("mobile-second-page");
const mobile1Button = document.getElementById("mobile1-button");
const mobile2Button = document.getElementById("mobile2-button");
mobile1Button.addEventListener("click", function () {
	mobileSecondPage.selected = true;
	mobileSecondPage.text = "iOS";
});

mobile2Button.addEventListener("click", function () {
	mobileSecondPage.selected = true;
	mobileSecondPage.text = "Android";
}

Responsiveness

The Settings component reacts and changes its layout on predefined breakpoints.

• S (<600px)
  Width - Full width.
  Height - Full height.
• M (600px -1023px)
  Width - 80% of the screen size.
  Height - 80% of the screen size.
  Maximum Width -640px.
  Maximum Height - 680px.
• XLL, XL, L (≥ 600)
  Minimum Width - 960px.
  Height - 680px or 88% of the screen size.
  Maximum Width - 960px.
  Maximum Height - 960px.

API

UserSettingsDialog

props

• open: boolean //false
• headerText?: string
• showSearchField: boolean //false

slot

• items!: Array;
• fixedItems!: Array;

UserSettingsItem

props

• text?: string
• tooltip: string //""
• headerText?: string
• selected: boolean //false
• disabled: boolean //false
• loading: boolean //false
• loadingReason: string // undefined
• icon: string //"globe"
• accessibleName?: string

slot

• tabs!: Array;
• pages!: Array;

UserSettingsView

props

• text?: string
• selected: boolean //false
• secondary: boolean //false

slot

• content!: Array;

Test Pages

fiori/test/pages/UserSettingsDialog.html

[ilhan007]

We have discussed the following changes together with @adrian-bobev

1. Settings to be renamed to UserSettingsDialog (more consistent with ViewSettingsDialog)
   ui5-settings => ui5-user-settings-dialog

2. UserSettingsDialog's headerTitle property to become headerText (headerText is used across the components)

3. SettingItem to be renamed to UserSettingsItem (note settings is in plural form)
   ui5-setting-item => ui5-user-settings-item

4. UserSettingsItem headerTitle to be renamed to headerText

5. SettingView to be renamed to UserSettingsView (note settings is in plural form)
   ui5-setting-view => ui5-user-settings-view

6. UserSettings item-select event => selection-change (because it's the selected property that is being changed and most of the events are called like this)

7. UserSettingsItem view-select event => selection-change

8. UserSettingsItem selection-change (previously view-select) => bubbling false

9. UserSettingsItem selection-change should be fired when clicking on the back button, because the component changes the selected state

10. UserSettingsItem back-click could be obsolete if selection-change is fired as suggested in 9.

[ui5-webcomponents-bot]

🎉 This PR is included in version v2.8.0-rc.3 🎉

The release is available on v2.8.0-rc.3

Your semantic-release bot 📦🚀