From 1c712309200b55d14dcea6b70bfd75ab94a9ae2d Mon Sep 17 00:00:00 2001 From: Plamen Ivanov Date: Tue, 28 Nov 2023 09:18:07 +0200 Subject: [PATCH] docs: new cem for Topic-P components - Toolbar (#7814) * docs: new cem for Topic-P components - Toolbar Issue: #7610 * docs: new cem for Topic-P components - Toolbar -refactored toolbar related files docs * docs: new cem for Topic-P components - Toolbar - removed unnecessary tag rom ToolbarSeparator docs * docs: new cem for Topic-P components - Toolbar -fixed review comments * docs: new cem for Topic-P components - Toolbar - fixed review comments * docs: new cem for Topic-P components - Toolbar - fixed review comments * docs: new cem for Topic-P components - Toolbar - fixed review comments * docs: new cem for Topic-P components - Toolbar - fixed review comments * docs: new cem for Topic-P components - Toolbar - fixed review comments --- packages/main/src/Interfaces.ts | 20 -------- packages/main/src/Toolbar.ts | 37 ++++----------- packages/main/src/ToolbarButton.ts | 46 +++++-------------- packages/main/src/ToolbarItem.ts | 37 ++------------- packages/main/src/ToolbarRegistry.ts | 12 ++--- packages/main/src/ToolbarSelect.ts | 42 +++++------------ packages/main/src/ToolbarSelectOption.ts | 13 +----- packages/main/src/ToolbarSeparator.ts | 6 +-- packages/main/src/ToolbarSpacer.ts | 11 ++--- packages/main/src/types/ToolbarAlign.ts | 11 +---- .../src/types/ToolbarItemOverflowBehavior.ts | 10 +--- 11 files changed, 52 insertions(+), 193 deletions(-) diff --git a/packages/main/src/Interfaces.ts b/packages/main/src/Interfaces.ts index 3eb36ee8caf5..c3972e251499 100644 --- a/packages/main/src/Interfaces.ts +++ b/packages/main/src/Interfaces.ts @@ -195,24 +195,6 @@ const IToken = "sap.ui.webc.main.IToken"; */ const ITreeItem = "sap.ui.webc.main.ITreeItem"; -/** - * Interface for toolbar items for the purpose of ui5-toolbar - * - * @name sap.ui.webc.main.IToolbarItem - * @interface - * @public - */ -const IToolbarItem = "sap.ui.webc.main.IToolbarItem"; - -/** - * Interface for toolbar select items for the purpose of ui5-toolbar-select - * - * @name sap.ui.webc.main.IToolbarSelectOption - * @interface - * @public - */ -const IToolbarSelectOption = "sap.ui.webc.main.IToolbarSelectOption"; - export { IAvatar, IBreadcrumbsItem, @@ -236,6 +218,4 @@ export { ITableRow, IToken, ITreeItem, - IToolbarItem, - IToolbarSelectOption, }; diff --git a/packages/main/src/Toolbar.ts b/packages/main/src/Toolbar.ts index 59a0833350d0..dec335f1b4fc 100644 --- a/packages/main/src/Toolbar.ts +++ b/packages/main/src/Toolbar.ts @@ -28,7 +28,7 @@ import ToolbarAlign from "./types/ToolbarAlign.js"; import ToolbarItemOverflowBehavior from "./types/ToolbarItemOverflowBehavior.js"; import HasPopup from "./types/HasPopup.js"; -import type ToolbarItem from "./ToolbarItem.js"; +import ToolbarItem from "./ToolbarItem.js"; import type ToolbarSeparator from "./ToolbarSeparator.js"; import { @@ -69,11 +69,7 @@ function parsePxValue(styleSet: CSSStyleDeclaration, propertyName: string): numb *

ES6 Module Import

* import "@ui5/webcomponents/dist/Toolbar"; * @constructor - * @author SAP SE - * @alias sap.ui.webc.main.Toolbar - * @extends sap.ui.webc.base.UI5Element - * @tagname ui5-toolbar - * @appenddocs sap.ui.webc.main.ToolbarButton sap.ui.webc.main.ToolbarSelect sap.ui.webc.main.ToolbarSelectOption sap.ui.webc.main.ToolbarSeparator sap.ui.webc.main.ToolbarSpacer + * @extends UI5Element * @public * @since 1.17.0 */ @@ -90,10 +86,8 @@ class Toolbar extends UI5Element { /** * Indicated the direction in which the Toolbar items will be aligned. * - * @type {sap.ui.webc.main.types.ToolbarAlign} * @public - * @defaultvalue: "End" - * @name sap.ui.webc.main.Toolbar.prototype.alignContent + * @default "End" */ @property({ type: ToolbarAlign, defaultValue: ToolbarAlign.End }) alignContent!: `${ToolbarAlign}`; @@ -101,27 +95,22 @@ class Toolbar extends UI5Element { /** * Calculated width of the whole toolbar. * @private - * @name sap.ui.webc.main.Toolbar.prototype.width - * @type {sap.ui.webc.base.types.Integer} - * @defaultvalue false + * @default undefined */ - @property({ type: Integer }) + @property({ validator: Integer }) width?: number; /** * Calculated width of the toolbar content. * @private - * @name sap.ui.webc.main.Toolbar.prototype.contentWidth - * @type {sap.ui.webc.base.types.Integer} - * @defaultvalue 0 + * @default undefined */ - @property({ type: Integer }) + @property({ validator: Integer }) contentWidth?: number; /** * Notifies the toolbar if it should show the items in a reverse way if Toolbar Popover needs to be placed on "Top" position. * @private - * @type {Boolean} */ @property({ type: Boolean }) reverseOverflow!: boolean; @@ -129,9 +118,7 @@ class Toolbar extends UI5Element { /** * Defines the accessible ARIA name of the component. * - * @type {string} - * @name sap.ui.webc.main.Toolbar.prototype.accessibleName - * @defaultvalue: "" + * @default "" * @public */ @property() @@ -140,9 +127,7 @@ class Toolbar extends UI5Element { /** * Receives id(or many ids) of the elements that label the input. * - * @type {string} - * @name sap.ui.webc.main.Toolbar.prototype.accessibleNameRef - * @defaultvalue "" + * @default "" * @public */ @property({ defaultValue: "" }) @@ -153,9 +138,6 @@ class Toolbar extends UI5Element { * * Note: Currently only ui5-toolbar-button, ui5-toolbar-select, ui5-toolbar-separator and ui5-toolbar-spacer are allowed here. * - * @type {sap.ui.webc.main.IToolbarItem[]} - * @name sap.ui.webc.main.Toolbar.prototype.default - * @slot items * @public */ @slot({ "default": true, type: HTMLElement, invalidateOnChildChange: true }) @@ -357,7 +339,6 @@ class Toolbar extends UI5Element { * Returns if the overflow popup is open. * * @public - * @return { Promise } */ async isOverflowOpen(): Promise { const overflowPopover = await this.getOverflowPopover(); diff --git a/packages/main/src/ToolbarButton.ts b/packages/main/src/ToolbarButton.ts index 938b8c67f466..d4ac7088cae7 100644 --- a/packages/main/src/ToolbarButton.ts +++ b/packages/main/src/ToolbarButton.ts @@ -26,12 +26,8 @@ import { registerToolbarItem } from "./ToolbarRegistry.js"; * * @constructor * @abstract - * @author SAP SE - * @alias sap.ui.webc.main.ToolbarButton - * @extends sap.ui.webc.main.ToolbarItem - * @tagname ui5-toolbar-button + * @extends ToolbarItem * @public - * @implements sap.ui.webc.main.IToolbarItem * @since 1.17.0 */ @customElement({ @@ -46,7 +42,6 @@ import { registerToolbarItem } from "./ToolbarRegistry.js"; * Note: The event will not be fired if the disabled * property is set to true. * - * @event sap.ui.webc.main.ToolbarButton#click * @public */ @event("click") @@ -56,9 +51,7 @@ class ToolbarButton extends ToolbarItem { *

* Note: a disabled action can't be pressed or focused, and it is not in the tab chain. * - * @type {boolean} - * @defaultvalue false - * @name sap.ui.webc.main.ToolbarButton.prototype.disabled + * @default false * @public */ @property({ type: Boolean }) @@ -77,9 +70,7 @@ class ToolbarButton extends ToolbarItem { *
  • Attention
    • * * - * @type {ButtonDesign} - * @defaultvalue "Default" - * @name sap.ui.webc.main.ToolbarButton.prototype.design + * @default "Default" * @public */ @property({ type: ButtonDesign, defaultValue: ButtonDesign.Default }) @@ -92,9 +83,7 @@ class ToolbarButton extends ToolbarItem { * SAP-icons font provides numerous buil-in icons. To find all the available icons, see the * Icon Explorer. * - * @type {string} - * @defaultvalue "" - * @name sap.ui.webc.main.ToolbarButton.prototype.icon + * @default "" * @public */ @property() @@ -103,9 +92,7 @@ class ToolbarButton extends ToolbarItem { /** * Defines whether the icon should be displayed after the component text. * - * @type {boolean} - * @name sap.ui.webc.main.ToolbarButton.prototype.iconEnd - * @defaultvalue false + * @default false * @public */ @property({ type: Boolean }) @@ -115,9 +102,7 @@ class ToolbarButton extends ToolbarItem { * Defines the tooltip of the component. *
    * Note: A tooltip attribute should be provided for icon-only buttons, in order to represent their exact meaning/function. - * @type {string} - * @name sap.ui.webc.main.ToolbarButton.prototype.tooltip - * @defaultvalue "" + * @default "" * @public */ @property() @@ -126,9 +111,7 @@ class ToolbarButton extends ToolbarItem { /** * Defines the accessible ARIA name of the component. * - * @type {string} - * @name sap.ui.webc.main.ToolbarButton.prototype.accessibleName - * @defaultvalue undefined + * @default undefined * @public */ @property({ defaultValue: undefined }) @@ -137,9 +120,7 @@ class ToolbarButton extends ToolbarItem { /** * Receives id(or many ids) of the elements that label the component. * - * @type {string} - * @name sap.ui.webc.main.ToolbarButton.prototype.accessibleNameRef - * @defaultvalue "" + * @default "" * @public */ @property({ defaultValue: "" }) @@ -169,8 +150,7 @@ class ToolbarButton extends ToolbarItem { * *
  • controls: Identifies the element (or elements) whose contents or presence are controlled by the button element. Accepts a string value.
    • * - * @type {object} - * @name sap.ui.webc.main.ToolbarButton.prototype.accessibilityAttributes + * @default {} * @public */ @property({ type: Object }) @@ -179,9 +159,7 @@ class ToolbarButton extends ToolbarItem { /** * Button text * @public - * @defaultvalue "" - * @type {string} - * @name sap.ui.webc.main.ToolbarButton.prototype.text + * @default "" */ @property() text!: string; @@ -192,9 +170,7 @@ class ToolbarButton extends ToolbarItem { * * Note: all CSS sizes are supported - 'percentage', 'px', 'rem', 'auto', etc. * - * @name sap.ui.webc.main.ToolbarButton.prototype.width - * @defaultvalue undefined - * @type { sap.ui.webc.base.types.CSSSize } + * @default undefined * @public */ @property({ validator: CSSSize }) diff --git a/packages/main/src/ToolbarItem.ts b/packages/main/src/ToolbarItem.ts index 3c3412f1c156..6dac8c263aa2 100644 --- a/packages/main/src/ToolbarItem.ts +++ b/packages/main/src/ToolbarItem.ts @@ -8,16 +8,6 @@ type IEventOptions = { preventClosing: boolean; } -interface IToolbarItem { - overflowPriority: `${ToolbarItemOverflowBehavior}`; - preventOverflowClosing: boolean; - ignoreSpace?: boolean; - isSeparator?: boolean; - containsText?: boolean; - hasFlexibleWidth?: boolean; - stableDomRef: string; -} - /** * @class * @@ -25,14 +15,12 @@ interface IToolbarItem { * used in the ui5-toolbar. * * @constructor - * @author SAP SE - * @alias sap.ui.webc.main.ToolbarItem - * @extends sap.ui.webc.base.UI5Element + * @extends UI5Element * @abstract * @public * @since 1.17.0 */ -class ToolbarItem extends UI5Element implements IToolbarItem { +class ToolbarItem extends UI5Element { /** * Property used to define the access of the item to the overflow Popover. If "NeverOverflow" option is set, * the item never goes in the Popover, if "AlwaysOverflow" - it never comes out of it. @@ -43,9 +31,7 @@ class ToolbarItem extends UI5Element implements IToolbarItem { *
  • Default
    • * * @public - * @name sap.ui.webc.main.ToolbarItem.prototype.overflowPriority - * @defaultvalue "Default" - * @type {ToolbarItemOverflowBehavior} + * @default "Default" */ @property({ type: ToolbarItemOverflowBehavior, defaultValue: ToolbarItemOverflowBehavior.Default }) overflowPriority!: `${ToolbarItemOverflowBehavior}`; @@ -53,17 +39,14 @@ class ToolbarItem extends UI5Element implements IToolbarItem { /** * Defines if the toolbar overflow popup should close upon intereaction with the item. * It will close by default. - * @type {boolean} - * @defaultvalue false + * @default false * @public - * @name sap.ui.webc.main.ToolbarItem.prototype.preventOverflowClosing */ @property({ type: Boolean }) preventOverflowClosing!: boolean; /** * Defines if the width of the item should be ignored in calculating the whole width of the toolbar - * @returns {boolean} * @protected */ get ignoreSpace(): boolean { @@ -74,7 +57,6 @@ class ToolbarItem extends UI5Element implements IToolbarItem { * Returns if the item contains text. Used to position the text properly inside the popover. * Aligned left if the item has text, default aligned otherwise. * @protected - * @returns {boolean} */ get containsText(): boolean { return false; @@ -84,7 +66,6 @@ class ToolbarItem extends UI5Element implements IToolbarItem { * Returns if the item is flexible. An item that is returning true for this property will make * the toolbar expand to fill the 100% width of its container. * @protected - * @returns {Boolean} */ get hasFlexibleWidth(): boolean { return false; @@ -95,7 +76,6 @@ class ToolbarItem extends UI5Element implements IToolbarItem { * This value is used to determinate if the toolbar should have its accessibility role and attributes set. * At least two interactive items are needed for the toolbar to have the role="toolbar" attribute set. * @protected - * @returns {boolean} */ get isInteractive(): boolean { return true; @@ -104,7 +84,6 @@ class ToolbarItem extends UI5Element implements IToolbarItem { /** * Returns if the item is separator. * @protected - * @returns {boolean} */ get isSeparator() { return false; @@ -113,7 +92,6 @@ class ToolbarItem extends UI5Element implements IToolbarItem { /** * Returns the template for the toolbar item. * @protected - * @returns {TemplateFunction} */ static get toolbarTemplate(): TemplateFunction { throw new Error("Template must be defined"); @@ -122,7 +100,6 @@ class ToolbarItem extends UI5Element implements IToolbarItem { /** * Returns the template for the toolbar item popover. * @protected - * @returns {TemplateFunction} */ static get toolbarPopoverTemplate(): TemplateFunction { throw new Error("Popover template must be defined"); @@ -131,7 +108,6 @@ class ToolbarItem extends UI5Element implements IToolbarItem { /** * Returns the events that the item is subscribed to. * @protected - * @returns {Map} */ get subscribedEvents(): Map { return new Map(); @@ -142,8 +118,5 @@ class ToolbarItem extends UI5Element implements IToolbarItem { } } -export type { - IToolbarItem, - IEventOptions, -}; +export type { IEventOptions }; export default ToolbarItem; diff --git a/packages/main/src/ToolbarRegistry.ts b/packages/main/src/ToolbarRegistry.ts index e62cebd76688..4d8bcb401b6e 100644 --- a/packages/main/src/ToolbarRegistry.ts +++ b/packages/main/src/ToolbarRegistry.ts @@ -1,10 +1,10 @@ import getSharedResource from "@ui5/webcomponents-base/dist/getSharedResource.js"; -import type IToolbarItem from "./ToolbarItem.js"; +import type ToolbarItem from "./ToolbarItem.js"; -const registry = getSharedResource>("ToolbarItem.registry", new Map()); +const registry = getSharedResource>("ToolbarItem.registry", new Map()); -const registerToolbarItem = (ElementClass: typeof IToolbarItem) => { +const registerToolbarItem = (ElementClass: typeof ToolbarItem) => { registry.set(ElementClass.name, ElementClass); }; @@ -17,15 +17,15 @@ const getRegisteredToolbarItem = (name: string) => { }; const getRegisteredStyles = () => { - return [...registry.values()].map((ElementClass: typeof IToolbarItem) => ElementClass.styles); + return [...registry.values()].map((ElementClass: typeof ToolbarItem) => ElementClass.styles); }; const getRegisteredStaticAreaStyles = () => { - return [...registry.values()].map((ElementClass: typeof IToolbarItem) => ElementClass.staticAreaStyles); + return [...registry.values()].map((ElementClass: typeof ToolbarItem) => ElementClass.staticAreaStyles); }; const getRegisteredDependencies = () => { - return [...registry.values()].map((ElementClass: typeof IToolbarItem) => ElementClass.dependencies).flat(); + return [...registry.values()].map((ElementClass: typeof ToolbarItem) => ElementClass.dependencies).flat(); }; export { diff --git a/packages/main/src/ToolbarSelect.ts b/packages/main/src/ToolbarSelect.ts index 1951d6b87e32..00e3af3b4b77 100644 --- a/packages/main/src/ToolbarSelect.ts +++ b/packages/main/src/ToolbarSelect.ts @@ -14,7 +14,7 @@ import ToolbarPopoverSelectTemplate from "./generated/templates/ToolbarPopoverSe import ToolbarItem from "./ToolbarItem.js"; import Select from "./Select.js"; import Option from "./Option.js"; -import "./ToolbarSelectOption.js"; +import type ToolbarSelectOption from "./ToolbarSelectOption.js"; import type { SelectChangeEventDetail } from "./Select.js"; type ToolbarSelectChangeEventDetail = SelectChangeEventDetail; @@ -32,13 +32,8 @@ type ToolbarSelectChangeEventDetail = SelectChangeEventDetail; * import "@ui5/webcomponents/dist/ToolbarSelectOption"; (comes with ui5-toolbar-select) * @constructor * @abstract - * @author SAP SE - * @alias sap.ui.webc.main.ToolbarSelect - * @extends sap.ui.webc.base.UI5Element - * @tagname ui5-toolbar-select - * @appenddocs sap.ui.webc.main.ToolbarSelectOption + * @extends UI5Element * @public - * @implements sap.ui.webc.main.IToolbarItem * @since 1.17.0 */ @customElement({ @@ -49,13 +44,15 @@ type ToolbarSelectChangeEventDetail = SelectChangeEventDetail; /** * Fired when the selected option changes. * - * @event sap.ui.webc.main.ToolbarSelect#change * @allowPreventDefault * @param {HTMLElement} selectedOption the selected option. * @public */ @event("change", { detail: { + /** + * @public + */ selectedOption: { type: HTMLElement }, }, }) @@ -63,14 +60,12 @@ type ToolbarSelectChangeEventDetail = SelectChangeEventDetail; /** * Fired after the component's dropdown menu opens. * - * @event sap.ui.webc.main.ToolbarSelect#open * @public */ @event("open") /** * Fired after the component's dropdown menu closes. * - * @event sap.ui.webc.main.ToolbarSelect#close * @public */ @event("close") @@ -82,9 +77,7 @@ class ToolbarSelect extends ToolbarItem { * * Note: all CSS sizes are supported - 'percentage', 'px', 'rem', 'auto', etc. * - * @name sap.ui.webc.main.ToolbarSelect.prototype.width - * @defaultvalue undefined - * @type { sap.ui.webc.base.types.CSSSize } + * @default undefined * @public */ @property({ validator: CSSSize }) @@ -99,21 +92,16 @@ class ToolbarSelect extends ToolbarItem { * *

    * Note: Use the ui5-toolbar-select-option component to define the desired options. - * @type {sap.ui.webc.main.ISelectOption[]} - * @slot options - * @name sap.ui.webc.main.ToolbarSelect.prototype.default * @public */ @slot({ "default": true, type: HTMLElement, invalidateOnChildChange: true }) - options!: Array