diff --git a/packages/fiori/src/DynamicPage.ts b/packages/fiori/src/DynamicPage.ts index 6f195b55318c..10bbf4df7d2a 100644 --- a/packages/fiori/src/DynamicPage.ts +++ b/packages/fiori/src/DynamicPage.ts @@ -34,14 +34,68 @@ const SCROLL_DEBOUNCE_RATE = 0; // ms /** * @class * - *

Overview

+ * A layout control, representing a web page, consisting of a title, header with dynamic behavior, a content area, and an optional floating footer. * + *

Overview

+ * + * The control consist of several components: + * + * + * + *

Usage

+ * + * Use the DynamicPage 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 + * ui5-page as a lighter control. + * + * The app can add to the content 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 DynamicPage will show a scrollbar that allows the user + * scroll through the content. + * + * + * + *

Responsive Behavior

+ * + * Dynamic page web component implements the resposive paddings design. + * + *

Keyboard Handling

+ * + *

Basic Navigation

+ * + * + *

Fast Navigation

+ * + * + *

ES6 Module Import

+ * + * import "@ui5/webcomponents-fiori/dist/DynamicPage.js"; * * @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 }) diff --git a/packages/fiori/src/DynamicPageHeader.ts b/packages/fiori/src/DynamicPageHeader.ts index f69ee6056484..7940a0a716c5 100644 --- a/packages/fiori/src/DynamicPageHeader.ts +++ b/packages/fiori/src/DynamicPageHeader.ts @@ -14,14 +14,32 @@ import DynamicPageHeaderCss from "./generated/themes/DynamicPageHeader.css.js"; /** * @class * - *

Overview

+ * Header of the DynamicPage. + * + *

Overview

+ * + * The DynamicPageHeader ui5-dynamic-page-header is part of the DynamicPage family + * and is used to serve as header of the DynamicPage. + * + *

Usage

+ * + * The DynamicPageHeader can hold any layout control and has two states - expanded + * and collapsed (snapped). The switching between these states happens when: + * + * + * + *

Responsive Behavior

+ * + * The responsive behavior of the DynamicPageHeader 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: { diff --git a/packages/fiori/src/DynamicPageHeaderActions.ts b/packages/fiori/src/DynamicPageHeaderActions.ts index 38aad511d3a4..9fe00d8a1dbc 100644 --- a/packages/fiori/src/DynamicPageHeaderActions.ts +++ b/packages/fiori/src/DynamicPageHeaderActions.ts @@ -23,12 +23,17 @@ import { * *

Overview

* + * The DynamicPageHeaderActions component is part of the DynamicPage + * family and is holding the action buttons behind the DynamicPageTitle and the DynamicPageHeader. + * + * 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 DynamicPageHeader. + * * * @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}; diff --git a/packages/fiori/src/DynamicPageTitle.ts b/packages/fiori/src/DynamicPageTitle.ts index 86225698c276..e066fc6f33b9 100644 --- a/packages/fiori/src/DynamicPageTitle.ts +++ b/packages/fiori/src/DynamicPageTitle.ts @@ -25,13 +25,34 @@ import { /** * @class * - *

Overview

+ * Title of the DynamicPage . + * + *

Overview

+ * + * The DynamicPageTitle component is part of the DynamicPage + * family and is used to serve as title of the DynamicPage. + * + *

Usage

+ * + * The DynamicPageTitle can hold any component and displays the most important + * information regarding the object that will always remain visible while scrolling. + * + * Note: The actions slot accepts any UI5 web component, but it`s + * recommended to use components, suitable for ui5-toolbar. + * + * The user can switch between the expanded/collapsed states of the + * DynamicPage by clicking on the DynamicPageTitle + * or by using the expand/collapse visual indicators, positioned at the bottom of the + * DynamicPageTitle and the DynamicPageHeader inside ui5-dynamic-page-header-actions. + * + *

Responsive Behavior

+ * + * The responsive behavior of the DynamicPageTitle depends on the behavior of the + * content that is displayed. * * * @constructor - * @alias sap.ui.webc.fiori.DynamicPageTitle * @extends sap.ui.webc.base.UI5Element - * @tagname ui5-dynamic-page-title * @public */ @customElement({ @@ -48,37 +69,92 @@ class DynamicPageTitle extends UI5Element { DynamicPageTitle.i18nBundle = await getI18nBundle("@ui5/webcomponents-fiori"); } + /** + * Defines the content of the Heading of the Dynamic Page. + * + * @public + */ @slot({ type: HTMLElement }) heading!: HTMLElement[]; + /** + * Defines the heading that is shown only when the header is snapped. + * + * @public + */ @slot({ type: HTMLElement }) snappedHeading!: HTMLElement[]; + /** + * Defines the heading that is shown only when the header is expanded. + * + * @public + */ @slot({ type: HTMLElement }) expandedHeading!: HTMLElement[]; + /** + * Defines the actions in the Dynamic page title. + * + * @public + */ @slot({ type: HTMLElement }) actions!: HTMLElement[]; + /** + * Defines the navigation actions in the Dynamic page title. + * + * @public + */ @slot({ type: HTMLElement }) navigationActions!: HTMLElement[]; + /** + * Defines the content of the Dynamic page title. + * + * @public + */ @slot({ "default": true, type: HTMLElement }) content!: HTMLElement[]; + /** + * Defines the content of the title that is shown only when the header is snapped. + * + * @public + */ @slot({ type: HTMLElement }) snappedContent!: HTMLElement[]; + /** + * Defines the content of the title that is shown only when the header is expanded. + * + * @public + */ @slot({ type: HTMLElement }) expandedContent!: HTMLElement[]; + /** + * Defines the content of the breadcrumbs inside Dynamic Page Title. + * + * @public + */ @slot({ type: HTMLElement }) breadcrumbs!: HTMLElement[]; + /** + * Defines if the title is snapped. + * + * @public + * @default false + */ @property({ type: Boolean }) snapped!: boolean; - // private properties + /** + * Defines if the mobileNavigationActions are shown. + * + * @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 index 8482f711276a..cd58532de0c7 100644 --- a/packages/playground/_stories/fiori/DynamicPage/DynamicPage.stories.ts +++ b/packages/playground/_stories/fiori/DynamicPage/DynamicPage.stories.ts @@ -28,7 +28,7 @@ const stylesDecorator = (storyFn: PartialStoryFn) => html` `; export default { - title: "Fiori/Dynamic Page", + title: "Fiori/Dynamic Page/Dynamic page", component: "DynamicPage", parameters: { docs: { @@ -48,7 +48,7 @@ const Template: UI5StoryArgs = (args) => { > ${unsafeHTML(args.headerArea)} ${unsafeHTML(args.titleArea)} - ${unsafeHTML(args.content)} + ${unsafeHTML(args.default)} ${unsafeHTML(args.footer)} `; @@ -151,7 +151,6 @@ Basic.args = { Supplier: Titanium - Scroll to bottom @@ -167,7 +166,7 @@ Basic.args = { `, - content: ` + default: ` `, }; + +Basic.decorators = [ + (story) => html` + ${story()} +`, +]; + Basic.parameters = { docs: { story: { diff --git a/packages/playground/_stories/fiori/DynamicPage/DynamicPageHeader/DynamicPageHeader.stories.ts b/packages/playground/_stories/fiori/DynamicPage/DynamicPageHeader/DynamicPageHeader.stories.ts new file mode 100644 index 000000000000..ba75945f8900 --- /dev/null +++ b/packages/playground/_stories/fiori/DynamicPage/DynamicPageHeader/DynamicPageHeader.stories.ts @@ -0,0 +1,101 @@ +import { html } from "lit"; +import type { Meta } from "@storybook/web-components"; +import type { PartialStoryFn } from "@storybook/types"; + +import argTypes, { componentInfo } from "./argTypes.js"; +import type { StoryArgsSlots } from "../argTypes.js"; +import type { UI5StoryArgs } from "../../../../types.js"; + +import { DocsPage } from "../../../../.storybook/docs.js"; + +import type DynamicPageHeader from "@ui5/webcomponents-fiori/dist/DynamicPageHeader.js"; + +const component = "ui5-dynamic-page-header"; + +const stylesDecorator = (storyFn: PartialStoryFn) => html` + + ${storyFn()} +`; + +export default { + title: "Fiori/Dynamic Page/ Dynamic Page Header", + component: "DynamicPageHeader", + parameters: { + docs: { + page: DocsPage({ ...componentInfo, component, showDefaultStoryOnly: true }) + }, + }, + decorators: [stylesDecorator], + argTypes, +} as Meta; + +const Template: UI5StoryArgs = (args) => { + return html` + +
+
+ + +
+
+ Product: + +
+
+
+ Description: + +
+
+
+ Supplier: + Titanium +
+
+
+
+ Progress: + +
+ +
+ +`; +}; + +export const Basic = Template.bind({}); +Basic.tags = ["_hidden_"]; diff --git a/packages/playground/_stories/fiori/DynamicPage/DynamicPageHeaderActions/DynamicPageHeaderActions.stories.ts b/packages/playground/_stories/fiori/DynamicPage/DynamicPageHeaderActions/DynamicPageHeaderActions.stories.ts new file mode 100644 index 000000000000..0fddc5c185fa --- /dev/null +++ b/packages/playground/_stories/fiori/DynamicPage/DynamicPageHeaderActions/DynamicPageHeaderActions.stories.ts @@ -0,0 +1,52 @@ +import { html } from "lit"; +import type { Meta } from "@storybook/web-components"; +import type { PartialStoryFn } from "@storybook/types"; + +import argTypes, { componentInfo } from "./argTypes.js"; +import type { StoryArgsSlots } from "../argTypes.js"; +import type { UI5StoryArgs } from "../../../../types.js"; + +import { DocsPage } from "../../../../.storybook/docs.js"; + +import DynamicPageHeaderActions from "@ui5/webcomponents-fiori/dist/DynamicPageHeaderActions.js"; + +const component = "ui5-dynamic-page-header-actions"; + +const stylesDecorator = (storyFn: PartialStoryFn) => html` + + ${storyFn()} +`; + +export default { + title: "Fiori/Dynamic Page/ Dynamic Page Header Actions", + component: "DynamicPageHeaderActions", + parameters: { + docs: { + page: DocsPage({ ...componentInfo, component, showDefaultStoryOnly: true }) + }, + }, + decorators: [stylesDecorator], + argTypes, +} as Meta; + +const Template: UI5StoryArgs = (args) => { + return html` +
+
+ + +
+
+`; +}; + +export const Basic = Template.bind({}); +Basic.tags = ["_hidden_"]; diff --git a/packages/playground/_stories/fiori/DynamicPage/DynamicPageTitle/DynamicPageTitle.stories.ts b/packages/playground/_stories/fiori/DynamicPage/DynamicPageTitle/DynamicPageTitle.stories.ts new file mode 100644 index 000000000000..f8dbc92cbc3f --- /dev/null +++ b/packages/playground/_stories/fiori/DynamicPage/DynamicPageTitle/DynamicPageTitle.stories.ts @@ -0,0 +1,101 @@ +import { html } from "lit"; +import { ifDefined } from "lit/directives/if-defined.js"; +import { unsafeHTML } from "lit/directives/unsafe-html.js"; +import type { Meta } from "@storybook/web-components"; +import type { PartialStoryFn } from "@storybook/types"; + +import argTypes, { componentInfo } from "./argTypes.js"; +import type { StoryArgsSlots } from "../argTypes.js"; +import type { UI5StoryArgs } from "../../../../types.js"; + +import { DocsPage } from "../../../../.storybook/docs.js"; + +import type DynamicPageTitle from "@ui5/webcomponents-fiori/dist/DynamicPageTitle.js"; + +const component = "ui5-dynamic-page-title"; + +const stylesDecorator = (storyFn: PartialStoryFn) => html` + + ${storyFn()} +`; + +export default { + title: "Fiori/Dynamic Page/ Dynamic Page Title", + component: "DynamicPageTitle", + parameters: { + docs: { + page: DocsPage({ ...componentInfo, component, showDefaultStoryOnly: true }) + }, + }, + decorators: [stylesDecorator], + argTypes, +} as Meta; + +const Template: UI5StoryArgs = (args) => { + return html` + + + Link1 + + Link2 + Link3 + Link4 + Link5 + Link6 + Link7 + Location + + + Expanded Heading + + Snapped Heading + +
+ This is an expanded subheading +
+ +
+ This is a snapped subheading +
+ + + + + + + + + + + + + + + + + + +`; +}; + +export const Basic = Template.bind({}); +Basic.tags = ["_hidden_"];