From fb493d282bab554198f373e374ba33148f2e854e Mon Sep 17 00:00:00 2001 From: Nia Peeva Date: Wed, 29 Nov 2023 10:28:17 +0200 Subject: [PATCH] docs(ui5-wizard): improve documentation --- packages/fiori/src/Interfaces.ts | 9 --- packages/fiori/src/Wizard.ts | 68 +++++++------------ packages/fiori/src/WizardStep.ts | 40 +++-------- packages/fiori/src/WizardTab.ts | 45 ++++++------ .../fiori/src/types/WizardContentLayout.ts | 6 -- 5 files changed, 54 insertions(+), 114 deletions(-) diff --git a/packages/fiori/src/Interfaces.ts b/packages/fiori/src/Interfaces.ts index 23e5f405f8ef..9c3ee1f02ffc 100644 --- a/packages/fiori/src/Interfaces.ts +++ b/packages/fiori/src/Interfaces.ts @@ -106,15 +106,6 @@ const ITimelineItem = "sap.ui.webc.fiori.ITimelineItem"; */ const IUploadCollectionItem = "sap.ui.webc.fiori.IUploadCollectionItem"; -/** - * Interface for components that may be slotted inside ui5-wizard as wizard steps - * - * @name sap.ui.webc.fiori.IWizardStep - * @interface - * @public - */ -const IWizardStep = "sap.ui.webc.fiori.IWizardStep"; - export { IBar, IFilterItem, diff --git a/packages/fiori/src/Wizard.ts b/packages/fiori/src/Wizard.ts index 1d980864d2af..e5ff5c67f68d 100644 --- a/packages/fiori/src/Wizard.ts +++ b/packages/fiori/src/Wizard.ts @@ -121,16 +121,6 @@ type StepInfo = { *
* Note: If multiple selected steps are defined, the last step will be selected. * - *

CSS Shadow Parts

- * - * CSS Shadow Parts allow developers to style elements inside the Shadow DOM. - *
- * The ui5-wizard exposes the following CSS Shadow Parts: - * - * *

Keyboard Handling

* The user can navigate using the following keyboard shortcuts: *
@@ -192,13 +182,11 @@ type StepInfo = { * import "@ui5/webcomponents-fiori/dist/Wizard.js"; (includes <ui5-wizard-step/>) * * @constructor - * @author SAP SE - * @alias sap.ui.webc.fiori.Wizard - * @extends sap.ui.webc.base.UI5Element - * @tagname ui5-wizard + * @extends UI5Element * @since 1.0.0-rc.10 - * @appenddocs sap.ui.webc.fiori.WizardStep * @public + * @csspart navigator - Used to style the progress navigator of the ui5-wizard. + * @csspart step-content - Used to style a ui5-wizard-step container. */ @customElement({ tag: "ui5-wizard", @@ -224,16 +212,24 @@ type StepInfo = { * Fired when the step is changed by user interaction - either with scrolling, * or by clicking on the steps within the component header. * - * @event sap.ui.webc.fiori.Wizard#step-change - * @param {sap.ui.webc.fiori.IWizardStep} step The new step. - * @param {sap.ui.webc.fiori.IWizardStep} previousStep The previous step. + * @param {IWizardStep} step The new step. + * @param {IWizardStep} previousStep The previous step. * @param {boolean} changeWithClick The step change occurs due to user's click or 'Enter'/'Space' key press on step within the navigation. * @public */ @event("step-change", { detail: { + /** + * @public + */ step: { type: HTMLElement }, + /** + * @public + */ previousStep: { type: HTMLElement }, + /** + * @public + */ changeWithClick: { Boolean }, }, }) @@ -242,13 +238,11 @@ class Wizard extends UI5Element { /** * Defines how the content of the ui5-wizard would be visualized. * @public - * @type {sap.ui.webc.fiori.types.WizardContentLayout} * @since 1.14.0 - * @name sap.ui.webc.fiori.Wizard.prototype.contentLayout - * @defaultvalue "MultipleSteps" + * @default "MultipleSteps" */ @property({ type: WizardContentLayout, defaultValue: WizardContentLayout.MultipleSteps }) - contentLayout?: WizardContentLayout + contentLayout!: WizardContentLayout /** * Defines the width of the ui5-wizard. @@ -270,8 +264,7 @@ class Wizard extends UI5Element { * Note: Supported values are between 0.5 and 1 * and values out of the range will be normalized to 0.5 and 1 respectively. * @private - * @type {sap.ui.webc.base.types.Float} - * @defaultvalue 0.7 + * @default 0.7 * @since 1.0.0-rc.13 */ @property({ validator: Float, defaultValue: STEP_SWITCH_THRESHOLDS.DEFAULT }) @@ -295,10 +288,7 @@ class Wizard extends UI5Element { *

* Note: Use the available ui5-wizard-step component. * - * @type {sap.ui.webc.fiori.IWizardStep[]} - * @name sap.ui.webc.fiori.Wizard.prototype.default * @public - * @slot steps */ @slot({ "default": true, @@ -484,7 +474,6 @@ class Wizard extends UI5Element { /** * Handles user click on steps' tabs within the header. * Note: the handler is bound in the template. - * @param {MouseEvent} e * @private */ onSelectionChangeRequested(e: MouseEvent) { @@ -495,7 +484,6 @@ class Wizard extends UI5Element { /** * Handles user scrolling with debouncing. * Note: the handler is bound in the template. - * @param {MouseEvent} e * @private */ onScroll(e: MouseEvent) { @@ -510,7 +498,6 @@ class Wizard extends UI5Element { /** * Handles when a step in the header is focused in order to update the ItemNavigation. * Note: the handler is bound in the template. - * @param {FocusEvent} e * @private */ onStepInHeaderFocused(e: FocusEvent) { @@ -696,7 +683,7 @@ class Wizard extends UI5Element { /** * Called upon onScroll. * Selects the closest step, based on the user scroll position. - * @param {Integer} scrollPos the current scroll position + * @param scrollPos the current scroll position * @private */ changeSelectionByScroll(scrollPos: number) { @@ -720,7 +707,7 @@ class Wizard extends UI5Element { * Called upon onSelectionChangeRequested. * Selects the external step (ui5-wizard-step), * based on the clicked or activated via keyboard step in the header (ui5-wizard-tab). - * @param {WizardTab} stepInHeader the step equivalent in the header + * @param stepInHeader the step equivalent in the header * @private */ async changeSelectionByStepAction(stepInHeader: WizardTab) { @@ -882,7 +869,6 @@ class Wizard extends UI5Element { /** * Returns an array of data objects, based on the user defined steps * to later build the steps (tabs) within the header. - * @returns {Array} * @private */ getStepsInfo() { @@ -936,7 +922,6 @@ class Wizard extends UI5Element { /** * Returns the index of the selected step. - * @returns {Integer} * @private */ getSelectedStepIndex() { @@ -948,7 +933,6 @@ class Wizard extends UI5Element { /** * Returns the index of the last enabled step. - * @returns {Integer} * @private */ getLastEnabledStepIndex() { @@ -991,7 +975,7 @@ class Wizard extends UI5Element { * by given step index. * * @private - * @param {Integer} stepIndex the index of a step + * @param stepIndex the index of a step */ scrollToContentItem(stepIndex: number) { this.contentDOM.scrollTop = this.getClosestScrollPosByStepIndex(stepIndex); @@ -1001,7 +985,7 @@ class Wizard extends UI5Element { * Returns to closest scroll position for the given step index. * * @private - * @param {Integer} stepIndex the index of a step + * @param stepIndex the index of a step */ getClosestScrollPosByStepIndex(stepIndex: number) { if (stepIndex === 0) { @@ -1023,7 +1007,7 @@ class Wizard extends UI5Element { /** * Returns the closest step index by given scroll position. * @private - * @param {Integer} scrollPos the scroll position + * @param scrollPos the scroll position */ getClosestStepIndexByScrollPos(scrollPos: number) { for (let closestStepIndex = 0; closestStepIndex <= this.stepScrollOffsets.length - 1; closestStepIndex++) { @@ -1046,10 +1030,10 @@ class Wizard extends UI5Element { /** * Switches the selection from the old step to the newly selected step. * - * @param {WizardStep} selectedStep the old step - * @param {WizardStep} stepToSelect the step to be selected - * @param {Integer} stepToSelectIndex the index of the newly selected step - * @param {boolean} changeWithClick the selection changed due to user click in the step navigation + * @param selectedStep the old step + * @param stepToSelect the step to be selected + * @param stepToSelectIndex the index of the newly selected step + * @param changeWithClick the selection changed due to user click in the step navigation * @private */ switchSelectionFromOldToNewStep(selectedStep: WizardStep | null, stepToSelect: WizardStep, stepToSelectIndex: number, changeWithClick: boolean) { diff --git a/packages/fiori/src/WizardStep.ts b/packages/fiori/src/WizardStep.ts index 883c607b2988..ef173865af7e 100644 --- a/packages/fiori/src/WizardStep.ts +++ b/packages/fiori/src/WizardStep.ts @@ -23,14 +23,11 @@ import property from "@ui5/webcomponents-base/dist/decorators/property.js"; * and should not be used standalone. * * @constructor - * @author SAP SE - * @alias sap.ui.webc.fiori.WizardStep - * @extends sap.ui.webc.base.UI5Element + * @extends UI5Element * @abstract - * @tagname ui5-wizard-step * @since 1.0.0-rc.10 - * @implements sap.ui.webc.fiori.IWizardStep * @public + * @slot {Node[]} default - Defines the step content. */ @customElement("ui5-wizard-step") @@ -41,9 +38,7 @@ class WizardStep extends UI5Element { * * Note: The text is displayed in the ui5-wizard navigation header. * - * @type {string} - * @name sap.ui.webc.fiori.WizardStep.prototype.titleText - * @defaultvalue "" + * @default "" * @public * @since 1.0.0-rc.15 */ @@ -56,9 +51,7 @@ class WizardStep extends UI5Element { * * Note: the text is displayed in the ui5-wizard navigation header. * - * @type {string} - * @name sap.ui.webc.fiori.WizardStep.prototype.subtitleText - * @defaultvalue "" + * @default "" * @public * @since 1.0.0-rc.15 */ @@ -74,9 +67,7 @@ class WizardStep extends UI5Element { * * The SAP-icons font provides numerous options. * See all the available icons in the Icon Explorer. - * @type {string} - * @name sap.ui.webc.fiori.WizardStep.prototype.icon - * @defaultvalue "" + * @default "" * @public */ @property() @@ -90,9 +81,7 @@ class WizardStep extends UI5Element { * Note: Step can't be selected and disabled at the same time. * In this case the selected property would take precedence. * - * @type {boolean} - * @name sap.ui.webc.fiori.WizardStep.prototype.disabled - * @defaultvalue false + * @default false * @public */ @property({ type: Boolean }) @@ -105,9 +94,7 @@ class WizardStep extends UI5Element { * Note: Step can't be selected and disabled at the same time. * In this case the selected property would take precedence. * - * @type {boolean} - * @name sap.ui.webc.fiori.WizardStep.prototype.selected - * @defaultvalue false + * @default false * @public */ @property({ type: Boolean }) @@ -121,23 +108,12 @@ class WizardStep extends UI5Element { * Note: It is recommended to use branching on the last known step * and later add new steps when it becomes clear how the wizard flow should continue. * - * @type {boolean} - * @name sap.ui.webc.fiori.WizardStep.prototype.branching - - * @defaultvalue false + * @default false * @public */ @property({ type: Boolean }) branching!: boolean - /** - * Defines the step content. - * @type {Node[]} - * @name sap.ui.webc.fiori.WizardStep.prototype.default - * @slot - * @public - */ - stretch?: boolean; stepContentAriaLabel?: string; } diff --git a/packages/fiori/src/WizardTab.ts b/packages/fiori/src/WizardTab.ts index 59d1ff6afe17..fcfb1bf0f95f 100644 --- a/packages/fiori/src/WizardTab.ts +++ b/packages/fiori/src/WizardTab.ts @@ -27,10 +27,7 @@ type WizardTabInfo = { * import "@ui5/webcomponents/dist/WizardTab.js"; (imported with ) * * @constructor - * @author SAP SE - * @alias sap.ui.webc.fiori.WizardTab - * @extends sap.ui.webc.base.UI5Element - * @tagname ui5-wizard-tab + * @extends UI5Element * @private */ @@ -45,7 +42,6 @@ type WizardTabInfo = { /** * Fired when clicking on none disabled step. * - * @event sap.ui.webc.fiori.WizardTab#selection-change-requested * @private */ @event("selection-change-requested") @@ -53,8 +49,8 @@ type WizardTabInfo = { class WizardTab extends UI5Element implements ITabbable { /** * Defines the icon of the step. - * @type {string} - * @defaultvalue "" + * + * @default "" * @private */ @property() @@ -62,8 +58,8 @@ class WizardTab extends UI5Element implements ITabbable { /** * Defines the titleText of the step. - * @type {string} - * @defaultvalue "" + * + * @default "" * @private * @since 1.0.0-rc.15 */ @@ -72,8 +68,8 @@ class WizardTab extends UI5Element implements ITabbable { /** * Defines the subtitleText of the step. - * @type {string} - * @defaultvalue "" + * + * @default "" * @private * @since 1.0.0-rc.15 */ @@ -82,8 +78,8 @@ class WizardTab extends UI5Element implements ITabbable { /** * Defines the number that will be displayed in place of the icon, when it's missing. - * @type {string} - * @defaultvalue "" + * + * @default "" * @private */ @property() @@ -91,8 +87,8 @@ class WizardTab extends UI5Element implements ITabbable { /** * Defines if the step is disabled - the step is not responding to user interaction. - * @type {boolean} - * @defaultvalue false + * + * @default false * @private */ @property({ type: Boolean }) @@ -102,8 +98,7 @@ class WizardTab extends UI5Element implements ITabbable { * Defines if the step is selected. *

* - * @type {boolean} - * @defaultvalue false + * @default false * @private */ @property({ type: Boolean }) @@ -111,8 +106,8 @@ class WizardTab extends UI5Element implements ITabbable { /** * Defines if the step's separator is hidden or not. - * @type {boolean} - * @defaultvalue false + * + * @default false * @private */ @property({ type: Boolean }) @@ -120,8 +115,8 @@ class WizardTab extends UI5Element implements ITabbable { /** * Defines if the step's separator is active or not. - * @type {boolean} - * @defaultvalue false + * + * @default false * @private */ @property({ type: Boolean }) @@ -129,8 +124,8 @@ class WizardTab extends UI5Element implements ITabbable { /** * Defines if the step's separator is dashed or not. - * @type {boolean} - * @defaultvalue false + * + * @default false * @private */ @property({ type: Boolean }) @@ -138,8 +133,8 @@ class WizardTab extends UI5Element implements ITabbable { /** * Defines the tabindex of the step. - * @type {string} - * @defaultvalue "-1" + * + * @default "-1" * @private */ @property({ defaultValue: "-1" }) diff --git a/packages/fiori/src/types/WizardContentLayout.ts b/packages/fiori/src/types/WizardContentLayout.ts index 94aa1301f61b..5d64216101cf 100644 --- a/packages/fiori/src/types/WizardContentLayout.ts +++ b/packages/fiori/src/types/WizardContentLayout.ts @@ -1,24 +1,18 @@ /** * Enumeration for different content layouts of the ui5-wizard. * - * @readonly - * @enum {string} * @public - * @author SAP SE - * @alias sap.ui.webc.fiori.types.WizardContentLayout */ enum WizardContentLayout { /** * Display the content of the ui5-wizard as multiple steps in a scroll section. * @public - * @type {MultipleSteps} */ MultipleSteps = "MultipleSteps", /** * Display the content of the ui5-wizard as single step. * @public - * @type {SingleStep} */ SingleStep = "SingleStep", }