diff --git a/packages/fiori/src/DynamicPage.ts b/packages/fiori/src/DynamicPage.ts index 6f195b55318c..02190d15ef66 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

+ *

Overview

* + * A layout component, representing a web page, consisting of a title, header with dynamic behavior, a content area, and an optional floating footer. + * + * The component 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 component. + * + * The app can add to the default 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..90604295925c 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 + * @private + * @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..50cf719c1e6c 100644 --- a/packages/fiori/src/DynamicPageTitle.ts +++ b/packages/fiori/src/DynamicPageTitle.ts @@ -25,13 +25,34 @@ import { /** * @class * - *

Overview

+ *

Overview

+ * + * Title of the DynamicPage. + * + * 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 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..5579d456a846 100644 --- a/packages/playground/_stories/fiori/DynamicPage/DynamicPage.stories.ts +++ b/packages/playground/_stories/fiori/DynamicPage/DynamicPage.stories.ts @@ -1,7 +1,7 @@ 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 { Meta, StoryFn } from "@storybook/web-components"; import type { PartialStoryFn } from "@storybook/types"; import argTypes, { componentInfo } from "./argTypes.js"; @@ -12,6 +12,11 @@ import { DocsPage } from "../../../.storybook/docs.js"; import type DynamicPage from "@ui5/webcomponents-fiori/dist/DynamicPage.js"; +import DynamicPageTitleTemplate from "./DynamicPageTitleTemplate.js" +import DynamicPageHeaderTemplate from "./DynamicPageHeaderTemplate.js" + + + const component = "ui5-dynamic-page"; const stylesDecorator = (storyFn: PartialStoryFn) => html` @@ -28,7 +33,7 @@ const stylesDecorator = (storyFn: PartialStoryFn) => html` `; export default { - title: "Fiori/Dynamic Page", + title: "Fiori/Dynamic page", component: "DynamicPage", parameters: { docs: { @@ -39,16 +44,17 @@ export default { argTypes, } as Meta; + const Template: UI5StoryArgs = (args) => { return html` ${unsafeHTML(args.headerArea)} ${unsafeHTML(args.titleArea)} - ${unsafeHTML(args.content)} + ${unsafeHTML(args.default)} ${unsafeHTML(args.footer)} `; @@ -56,118 +62,10 @@ const Template: UI5StoryArgs = (args) => { export const Basic = Template.bind({}); Basic.args = { - titleArea: ` - - - Link1 - - Link2 - Link3 - Link4 - Link5 - Link6 - Link7 - Location - - - Expanded Heading - - Snapped Heading - -
- This is an expanded subheading -
- -
- This is a snapped subheading -
- - - - - - - - - - - - - - - - - - `, - headerArea: ` - -
-
- - -
-
- Product: - -
-
-
- Description: - -
-
-
- Supplier: - Titanium - Scroll to bottom -
-
-
-
- Progress: - -
- -
- `, - content: ` + showFooter: true, + titleArea: DynamicPageTitleTemplate, + headerArea: DynamicPageHeaderTemplate, + 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..bc1261a494bd --- /dev/null +++ b/packages/playground/_stories/fiori/DynamicPage/DynamicPageHeader/DynamicPageHeader.stories.ts @@ -0,0 +1,32 @@ +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"; +import DynamicPageHeaderTemplate from "../DynamicPageHeaderTemplate.js"; + +const component = "ui5-dynamic-page-header"; + +export default { + title: "Fiori/Dynamic Page/ Dynamic Page Header", + component: "DynamicPageHeader", + parameters: { + docs: { + page: DocsPage({ ...componentInfo, component, showDefaultStoryOnly: true }) + }, + }, + argTypes, +} as Meta; + +const Template: UI5StoryArgs = (args) => { + return DynamicPageHeaderTemplate; +}; + +export const Basic = Template.bind({}); +Basic.tags = ["_hidden_"]; diff --git a/packages/playground/_stories/fiori/DynamicPage/DynamicPageHeaderTemplate.ts b/packages/playground/_stories/fiori/DynamicPage/DynamicPageHeaderTemplate.ts new file mode 100644 index 000000000000..7aec29d82026 --- /dev/null +++ b/packages/playground/_stories/fiori/DynamicPage/DynamicPageHeaderTemplate.ts @@ -0,0 +1,55 @@ +export default ` +
+
+ + +
+
+ Product: + +
+
+
+ Description: + +
+
+
+ Supplier: + Titanium +
+
+
+
+ Progress: + +
+ +
+`; 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..d7318713e29d --- /dev/null +++ b/packages/playground/_stories/fiori/DynamicPage/DynamicPageTitle/DynamicPageTitle.stories.ts @@ -0,0 +1,34 @@ +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"; +import DynamicPageTitleTemplate from "../DynamicPageTitleTemplate.js"; + +const component = "ui5-dynamic-page-title"; + +export default { + title: "Fiori/Dynamic Page/ Dynamic Page Title", + component: "DynamicPageTitle", + parameters: { + docs: { + page: DocsPage({ ...componentInfo, component, showDefaultStoryOnly: true }) + }, + }, + argTypes, +} as Meta; + +const Template: UI5StoryArgs = (args) => { + return DynamicPageTitleTemplate; +}; + +export const Basic = Template.bind({}); +Basic.tags = ["_hidden_"]; diff --git a/packages/playground/_stories/fiori/DynamicPage/DynamicPageTitleTemplate.ts b/packages/playground/_stories/fiori/DynamicPage/DynamicPageTitleTemplate.ts new file mode 100644 index 000000000000..5209e2613686 --- /dev/null +++ b/packages/playground/_stories/fiori/DynamicPage/DynamicPageTitleTemplate.ts @@ -0,0 +1,52 @@ +export default ` + + Link1 + + Link2 + Link3 + Link4 + Link5 + Link6 + Link7 + Location + + + Expanded Heading + + Snapped Heading + +
+ This is an expanded subheading +
+ +
+ This is a snapped subheading +
+ + + + + + + + + + + + + + + + + ` \ No newline at end of file