feat(ui5-dynamic-page): proper docs added

SAP · Jan 22, 2024 · 54567cf · 54567cf
1 parent 810b08d
commit 54567cf
Show file tree

Hide file tree

Showing 5 changed files with 142 additions and 29 deletions.
diff --git a/packages/fiori/src/DynamicPage.ts b/packages/fiori/src/DynamicPage.ts
@@ -39,9 +39,9 @@ const SCROLL_DEBOUNCE_RATE = 0; // ms
  *
  * @constructor
  * @author SAP SE
- * @alias sap.ui.webc.fiori.DynamicPage
  * @extends sap.ui.webc.base.UI5Element
  * @tagname ui5-dynamic-page
+ * @since 1.122
  * @public
  */
 @customElement({
@@ -68,9 +68,7 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines if the header is snapped.
 	 *
-	 * @type {boolean}
-	 * @name sap.ui.webc.fiori.DynamicPage.prototype.headerSnapped
-	 * @defaultvalue false
+	 * @default false
 	 * @public
 	 */
 	@property({ type: Boolean })
@@ -79,9 +77,7 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines if the header is pinned.
 	 *
-	 * @type {boolean}
-	 * @name sap.ui.webc.fiori.DynamicPage.prototype.headerPinned
-	 * @defaultvalue false
+	 * @default false
 	 * @public
 	 */
 	@property({ type: Boolean })
@@ -90,9 +86,7 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines if the footer is shown.
 	 *
-	 * @type {boolean}
-	 * @name sap.ui.webc.fiori.DynamicPage.prototype.showFooter
-	 * @defaultvalue false
+	 * @defaul false
 	 * @public
 	 */
 	@property({ type: Boolean })
@@ -101,7 +95,6 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines the current media query size.
 	 *
-	 * @type {string}
 	 * @private
 	 */
 	@property()
@@ -110,7 +103,6 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines the content of the Dynamic Page.
 	 *
-	 * @name sap.ui.webc.fiori.DynamicPage.prototype.content
 	 * @slot
 	 * @public
 	 */
@@ -120,8 +112,6 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines the title HTML Element.
 	 *
-	 * @type {sap.ui.webc.fiori.DynamicPageTitle}
-	 * @name sap.ui.webc.fiori.DynamicPage.prototype.titleArea
 	 * @slot
 	 * @public
 	 */
@@ -131,8 +121,6 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines the title HTML Element.
 	 *
-	 * @type {sap.ui.webc.fiori.DynamicPageHeader}
-	 * @name sap.ui.webc.fiori.DynamicPage.prototype.headerArea
 	 * @slot
 	 * @public
 	 */
@@ -142,8 +130,6 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines the title HTML Element.
 	 *
-	 * @type {sap.ui.webc.fiori.IBar}
-	 * @name sap.ui.webc.fiori.DynamicPage.prototype.footer
 	 * @slot
 	 * @public
 	 */

diff --git a/packages/fiori/src/DynamicPageHeader.ts b/packages/fiori/src/DynamicPageHeader.ts
@@ -18,10 +18,9 @@ import DynamicPageHeaderCss from "./generated/themes/DynamicPageHeader.css.js";
  *
  *
  * @constructor
- * @alias sap.ui.webc.fiori.DynamicPageHeader
  * @extends sap.ui.webc.base.UI5Element
- * @tagname ui5-dynamic-page-header
  * @public
+ * @since 1.122
  */
 @customElement({
 	tag: "ui5-dynamic-page-header",
@@ -35,9 +34,15 @@ class DynamicPageHeader extends UI5Element {
 	static async onDefine() {
 		DynamicPageHeader.i18nBundle = await getI18nBundle("@ui5/webcomponents-fiori");
 	}
-
+	/**
+	 * Defines the content of the Dynamic Page Header.
+	 *
+	 * @slot
+	 * @public
+	 */
 	@slot({ "default": true, type: HTMLElement })
 	content!: HTMLElement[];
+
 	get classes() {
 		return {
 			root: {

diff --git a/packages/fiori/src/DynamicPageHeaderActions.ts b/packages/fiori/src/DynamicPageHeaderActions.ts
@@ -25,10 +25,9 @@ import {
  *
  *
  * @constructor
- * @alias sap.ui.webc.fiori.DynamicPageHeaderActions
  * @extends sap.ui.webc.base.UI5Element
- * @tagname ui5-dynamic-page-header-actions
  * @public
+ * @since 1.122
  */
 @customElement({
 	tag: "ui5-dynamic-page-header-actions",
@@ -37,7 +36,18 @@ import {
 	template: DynamicPageHeaderActionsTemplate,
 })
 
+/**
+ * Event that is being fired by clicking on the expand button.
+ *
+ * @public
+ */
 @event("expand-button-click")
+
+/**
+ * Event that is being fired by clicking on the pin button.
+ *
+ * @public
+ */
 @event("pin-button-click")
 
 class DynamicPageHeaderActions extends UI5Element {
@@ -47,12 +57,30 @@ class DynamicPageHeaderActions extends UI5Element {
 		DynamicPageHeaderActions.i18nBundle = await getI18nBundle("@ui5/webcomponents-fiori");
 	}
 
+	/**
+	 * Defines whether the header is pinned.
+	 *
+	 * @public
+	 * @default false
+	 */
 	@property({ type: Boolean })
 	pinned!: boolean;
 
+	/**
+	 * Defines whether the header is snapped.
+	 *
+	 * @public
+	 * @default false
+	 */
 	@property({ type: Boolean })
 	snapped!: boolean;
 
+	/**
+	 * Contains attributes to be added to HTML to gain accessibility.
+	 *
+	 * @public
+	 * @default {controls: ""}
+	 */
 	@property({ type: Object })
 	accessibilityAttributes!: {controls: string};
 

diff --git a/packages/fiori/src/DynamicPageTitle.ts b/packages/fiori/src/DynamicPageTitle.ts
@@ -29,9 +29,7 @@ import {
  *
  *
  * @constructor
- * @alias sap.ui.webc.fiori.DynamicPageTitle
  * @extends sap.ui.webc.base.UI5Element
- * @tagname ui5-dynamic-page-title
  * @public
  */
 @customElement({
@@ -48,37 +46,102 @@ class DynamicPageTitle extends UI5Element {
 		DynamicPageTitle.i18nBundle = await getI18nBundle("@ui5/webcomponents-fiori");
 	}
 
+	/**
+	 * Defines the content of the Heading of the Dynamic Page.
+	 *
+	 * @slot
+	 * @public
+	 */
 	@slot({ type: HTMLElement })
 	heading!: HTMLElement[];
 
+	/**
+	 * Defines the heading that is shown only when the header is snapped.
+	 *
+	 * @slot
+	 * @public
+	 */
 	@slot({ type: HTMLElement })
 	snappedHeading!: HTMLElement[];
 
+	/**
+	 * Defines the heading that is shown only when the header is expanded.
+	 *
+	 * @slot
+	 * @public
+	 */
 	@slot({ type: HTMLElement })
 	expandedHeading!: HTMLElement[];
 
+	/**
+	 * Defines the actions in the Dynamic page title.
+	 *
+	 * @slot
+	 * @public
+	 */
 	@slot({ type: HTMLElement })
 	actions!: HTMLElement[];
 
+	/**
+	 * Defines the navigation actions in the Dynamic page title.
+	 *
+	 * @slot
+	 * @public
+	 */
 	@slot({ type: HTMLElement })
 	navigationActions!: HTMLElement[];
 
+	/**
+	 * Defines the content of the Dynamic page title.
+	 *
+	 * @slot
+	 * @public
+	 */
 	@slot({ "default": true, type: HTMLElement })
 	content!: HTMLElement[];
 
+	/**
+	 * Defines the content of the title that is shown only when the header is snapped.
+	 *
+	 * @slot
+	 * @public
+	 */
 	@slot({ type: HTMLElement })
 	snappedContent!: HTMLElement[];
 
+	/**
+	 * Defines the content of the title that is shown only when the header is expanded.
+	 *
+	 * @slot
+	 * @public
+	 */
 	@slot({ type: HTMLElement })
 	expandedContent!: HTMLElement[];
 
+	/**
+	 * Defines the content of the breadcrumbs inside Dynamic Page Title.
+	 *
+	 * @slot
+	 * @public
+	 */
 	@slot({ type: HTMLElement })
 	breadcrumbs!: HTMLElement[];
 
+	/**
+	 * Defines if the title is snapped.
+	 *
+	 * @property
+	 * @public
+	 */
 	@property({ type: Boolean })
 	snapped!: boolean;
 
-	// private properties
+	/**
+	 * Defines if the mobileNavigationActions are shown.
+	 *
+	 * @property
+	 * @private
+	 */
 	@property({ type: Boolean })
 	mobileNavigationActions!: boolean;
 

diff --git a/packages/playground/_stories/fiori/DynamicPage/DynamicPage.stories.ts b/packages/playground/_stories/fiori/DynamicPage/DynamicPage.stories.ts
@@ -48,7 +48,7 @@ const Template: UI5StoryArgs<DynamicPage, StoryArgsSlots> = (args) => {
     >
       ${unsafeHTML(args.headerArea)}
       ${unsafeHTML(args.titleArea)}
-      ${unsafeHTML(args.content)}
+      ${unsafeHTML(args.default)}
       ${unsafeHTML(args.footer)}
     </ui5-dynamic-page>
 `;
@@ -151,7 +151,8 @@ Basic.args = {
                     <ui5-title level="H5">Supplier:</ui5-title>
                     <ui5-title level="H5" id="lblSupplier"
                         ><b>Titanium</b></ui5-title>
-                    <ui5-button id="scrollBtn">Scroll to bottom</ui5-button>
+                        <ui5-button id="scrollDownBtn">Scroll down</ui5-button>
+                        <ui5-button id="scrollToBottomBtn">Scroll to bottom</ui5-button>
                 </div>
             </div>
         </div>
@@ -167,7 +168,7 @@ Basic.args = {
         <span></span>
     </div>
     </ui5-dynamic-page-header>`,
-    content: `
+    default: `
     <ui5-list
     id="col1list"
     header-text="Products (13)"
@@ -859,6 +860,36 @@ Basic.args = {
     </ui5-bar>`,
 
 };
+
+Basic.decorators = [
+    (story) => html`
+    ${story()}
+<script>
+    const page = document.getElementById("page");
+    const scrollDownStep = 500;
+
+    function getScrollContainer() {
+        return page.shadowRoot.querySelector(".ui5-dynamic-page-scroll-container");
+    }
+
+    document.getElementById("toggleFooterBtn").addEventListener("click", () => {
+        page.showFooter = !page.showFooter;
+    });
+
+    document.getElementById("scrollDownBtn").addEventListener("click", () => {
+        const scrollContainer = getScrollContainer();
+        const scrollTop = scrollContainer.scrollTop;
+        scrollContainer.scrollTop = scrollTop + scrollDownStep;
+    });
+
+    document.getElementById("scrollToBottomBtn").addEventListener("click", () => {
+        const scrollContainer = getScrollContainer();
+        const newScrollTop = scrollContainer.scrollHeight - scrollContainer.offsetHeight;
+        scrollContainer.scrollTop = newScrollTop;
+    });
+</script>`,
+];
+
 Basic.parameters = {
   docs: {
     story: {