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
SAP · Nov 28, 2023 · 1c71230 · 1c71230
1 parent 3dabefe
commit 1c71230
Show file tree

Hide file tree

Showing 11 changed files with 52 additions and 193 deletions.
diff --git 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 <code>ui5-toolbar</code>
- *
- * @name sap.ui.webc.main.IToolbarItem
- * @interface
- * @public
- */
-const IToolbarItem = "sap.ui.webc.main.IToolbarItem";
-
-/**
- * Interface for toolbar select items for the purpose of <code>ui5-toolbar-select</code>
- *
- * @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
@@ -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
  * <h3>ES6 Module Import</h3>
  * <code>import "@ui5/webcomponents/dist/Toolbar";</code>
  * @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,48 +86,39 @@ 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}`;
 
 	/**
 	 * 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;
 
 	/**
 	 * 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 {
      *
      * <b>Note:</b> Currently only <code>ui5-toolbar-button</code>, <code>ui5-toolbar-select</code>, <code>ui5-toolbar-separator</code> and <code>ui5-toolbar-spacer</code> 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<Boolean> }
 	 */
 	async isOverflowOpen(): Promise<boolean> {
 		const overflowPopover = await this.getOverflowPopover();

diff --git 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";
  * <b>Note:</b> The event will not be fired if the <code>disabled</code>
  * property is set to <code>true</code>.
  *
- * @event sap.ui.webc.main.ToolbarButton#click
  * @public
  */
 @event("click")
@@ -56,9 +51,7 @@ class ToolbarButton extends ToolbarItem {
 	 * <br><br>
 	 * <b>Note:</b> 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 {
 	 * <li><code>Attention</code></li>
 	 * </ul>
 	 *
-	 * @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
 	 * <ui5-link target="_blank" href="https://openui5.hana.ondemand.com/test-resources/sap/m/demokit/iconExplorer/webapp/index.html" class="api-table-content-cell-link">Icon Explorer</ui5-link>.
 	 *
-	 * @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.
 	 * <br>
 	 * <b>Note:</b> 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 {
 	 * 		</li>
 	 * 		<li><code>controls</code>: Identifies the element (or elements) whose contents or presence are controlled by the button element. Accepts a string value.</li>
 	 * </ul>
-	 * @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 {
 	 *
 	 * <b>Note:</b> 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
@@ -8,31 +8,19 @@ type IEventOptions = {
 	preventClosing: boolean;
 }
 
-interface IToolbarItem {
-	overflowPriority: `${ToolbarItemOverflowBehavior}`;
-	preventOverflowClosing: boolean;
-	ignoreSpace?: boolean;
-	isSeparator?: boolean;
-	containsText?: boolean;
-	hasFlexibleWidth?: boolean;
-	stableDomRef: string;
-}
-
 /**
  * @class
  *
  * The <code>ui5-tb-item</code> represents an abstract class for items,
  * used in the <code>ui5-toolbar</code>.
  *
  * @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,27 +31,22 @@ class ToolbarItem extends UI5Element implements IToolbarItem {
 	 * <li><code>Default</code></li>
 	 * </ul>
 	 * @public
-	 * @name sap.ui.webc.main.ToolbarItem.prototype.overflowPriority
-	 * @defaultvalue "Default"
-	 * @type {ToolbarItemOverflowBehavior}
+	 * @default "Default"
 	 */
 	@property({ type: ToolbarItemOverflowBehavior, defaultValue: ToolbarItemOverflowBehavior.Default })
 	overflowPriority!: `${ToolbarItemOverflowBehavior}`;
 
 	/**
 	 * 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<string, IEventOptions> {
 		return new Map();
@@ -142,8 +118,5 @@ class ToolbarItem extends UI5Element implements IToolbarItem {
 	}
 }
 
-export type {
-	IToolbarItem,
-	IEventOptions,
-};
+export type { IEventOptions };
 export default ToolbarItem;