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

packages/fiori/src/DynamicPage.ts

@@ -34,14 +34,68 @@ const SCROLL_DEBOUNCE_RATE = 0; // ms
 /**
  * @class
  *
- * <h3 class="comment-api-title">Overview</h3>
+ * A layout control, representing a web page, consisting of a title, header with dynamic behavior, a content area, and an optional floating footer.
  *
+ * <h3>Overview</h3>
+ *
+ * The control consist of several components:
+ *
+ * <ul><li><code>DynamicPageTitle</code> consists of a heading
+ * on the left side, content in the middle, and actions on the right. The displayed
+ * content changes based on the current mode of the DynamicPageHeader.</li>
+ * <li><code>DynamicPageHeader</code> is a generic container, which
+ * can contain a single layout control. The header works in two modes - expanded and snapped and its
+ * behavior can be adjusted with the help of different properties.</li>
+ * <li><code>Content area</code> is a generic container, which can have a single UI5 layout.</li>
+ * <li><code>Footer</code> is positioned at the bottom with a small offset and used for additional
+ * actions, the footer floats above the content.</li></ul>
+ *
+ * <h3>Usage</h3>
+ *
+ * Use the <code>DynamicPage</code> if you need to have a title, that is always visible
+ * and a header, that has configurable Expanding/Snapping functionality.
+ * If you don't need the Expanding/Snapping functionality it is better to use the
+ * <code>ui5-page</code> as a lighter control.
+ *
+ * The app can add to the <code>content</code> slot of the ui5-dynamic-page either content that is designed to fit its container (e.g. has 100% height),
+ * or content with own height that may overflow its container. In the second case the <code>DynamicPage</code> will show a scrollbar that allows the user
+ * scroll through the content.
+ *
+ * <ul><b>Notes:</b>
+ * <li>Snapping of the <code>DynamicPageTitle</code> is not supported in the following case:
+ * When the <code>DynamicPage</code> has a scroll bar, the control usually scrolls to the snapping point - the point,
+ * where the <code>DynamicPageHeader</code> is scrolled out completely.
+ * However, when there is a scroll bar, but not enough content to reach the snapping point,
+ * the snapping is not possible using scrolling.</li>
+ * </ul>
+ *
+ * <h3>Responsive Behavior</h3>
+ *
+ * Dynamic page web component implements the resposive paddings design.
+ *
+ * <h3>Keyboard Handling</h3>
+ *
+ * <h4>Basic Navigation</h4>
+ * <ul>
+ * <li>[SPACE, ENTER, RETURN] - If focus is on a button inside DynamicPageTitle its action is being triggered, once activated.
+ * If focus is on the snap header button (arrow button), or on the header itself, once activated, it triggers the associated action (such as snap/expand the header).
+ * If focus is on pin button (the button with pin icon on the bottom of the header), once activated, it triggers the associated action (pinning of the header). </li>
+ * </ul>
+ *
+ * <h4>Fast Navigation</h4>
+ * <ul>
+ * <li>This component provides a build in fast navigation group which can be used via <code>F6 / Shift + F6</code> or <code> Ctrl + Alt(Option) + Down /  Ctrl + Alt(Option) + Up</code>.
+ * In order to use this functionality, you need to import the following module:
+ * <code>import "@ui5/webcomponents-base/dist/features/F6Navigation.js"</code></li>
+ * </ul>
+ *
+ * <h3>ES6 Module Import</h3>
+ *
+ * <code>import "@ui5/webcomponents-fiori/dist/DynamicPage.js";</code>
  *
  * @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 +122,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 +131,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 +140,7 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines if the footer is shown.
 	 *
-	 * @type {boolean}
-	 * @name sap.ui.webc.fiori.DynamicPage.prototype.showFooter
-	 * @defaultvalue false
+	 * @default false
 	 * @public
 	 */
 	@property({ type: Boolean })
@@ -101,7 +149,6 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines the current media query size.
 	 *
-	 * @type {string}
 	 * @private
 	 */
 	@property()
@@ -110,8 +157,6 @@ class DynamicPage extends UI5Element {
 	/**
 	 * Defines the content of the Dynamic Page.
 	 *
-	 * @name sap.ui.webc.fiori.DynamicPage.prototype.content
-	 * @slot
 	 * @public
 	 */
 	@slot({ "default": true, type: HTMLElement })
@@ -120,9 +165,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
 	 */
 	@slot({ type: DynamicPageTitle })
@@ -131,9 +173,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
 	 */
 	@slot({ type: DynamicPageHeader })
@@ -142,9 +181,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
 	 */
 	@slot({ type: HTMLElement })

packages/fiori/src/DynamicPageHeader.ts

@@ -14,14 +14,32 @@ import DynamicPageHeaderCss from "./generated/themes/DynamicPageHeader.css.js";
 /**
  * @class
  *
- * <h3 class="comment-api-title">Overview</h3>
+ * Header of the DynamicPage.
+ *
+ * <h3>Overview</h3>
+ *
+ * The DynamicPageHeader <code>ui5-dynamic-page-header</code> is part of the DynamicPage family
+ * and is used to serve as header of the <code>DynamicPage</code>.
+ *
+ * <h3>Usage</h3>
+ *
+ * The <code>DynamicPageHeader</code> can hold any layout control and has two states - expanded
+ * and collapsed (snapped). The switching between these states happens when:
+ *
+ * <ul><li>the user scrolls below its bottom margin</li>
+ * <li>the user clicks on the <code>DynamicPageTitle</code></li>
+ * <li>through the <code>DynamicPage</code> property <code>headerSnapped</code></li></ul>
+ *
+ * <h3>Responsive Behavior</h3>
+ *
+ * The responsive behavior of the <code>DynamicPageHeader</code> depends on the behavior of the
+ * content that is displayed.
  *
  *
  * @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 +53,14 @@ class DynamicPageHeader extends UI5Element {
 	static async onDefine() {
 		DynamicPageHeader.i18nBundle = await getI18nBundle("@ui5/webcomponents-fiori");
 	}
-
+	/**
+	 * Defines the content of the Dynamic Page Header.
+	 *
+	 * @public
+	 */
 	@slot({ "default": true, type: HTMLElement })
 	content!: HTMLElement[];
+
 	get classes() {
 		return {
 			root: {

packages/fiori/src/DynamicPageHeaderActions.ts

@@ -23,12 +23,17 @@ import {
  *
  * <h3 class="comment-api-title">Overview</h3>
  *
+ * The <code>DynamicPageHeaderActions</code> component is part of the <code>DynamicPage</code>
+ * family and is holding the action buttons behind the <code>DynamicPageTitle</code> and the <code>DynamicPageHeader</code>.
+ *
+ * The "pin" action is used to attach the header to a certain state (expanded/collapsed).
+ * The expand/collapse action is used to switch between the two states of <code>DynamicPageHeader</code>.
+ *
  *
  * @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 +42,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 +63,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 {}
+	 */
 	@property({ type: Object })
 	accessibilityAttributes!: {controls: string};