diff --git a/.changeset/twenty-waves-sleep.md b/.changeset/twenty-waves-sleep.md new file mode 100644 index 0000000000..cd7939a3fd --- /dev/null +++ b/.changeset/twenty-waves-sleep.md @@ -0,0 +1,5 @@ +--- +'@swisspost/design-system-documentation': minor +--- + +Added usage examples for the header component. diff --git a/packages/documentation/src/stories/components/header/header-selected-class.sample.html b/packages/documentation/src/stories/components/header/header-selected-class.sample.html deleted file mode 100644 index 309269e1d7..0000000000 --- a/packages/documentation/src/stories/components/header/header-selected-class.sample.html +++ /dev/null @@ -1,17 +0,0 @@ - - ... - - - -

Main Navigation

- - - Letters - - Packages - - - ... - diff --git a/packages/documentation/src/stories/components/header/header.docs.mdx b/packages/documentation/src/stories/components/header/header.docs.mdx index 5b2c44af00..a69dcf6207 100644 --- a/packages/documentation/src/stories/components/header/header.docs.mdx +++ b/packages/documentation/src/stories/components/header/header.docs.mdx @@ -1,8 +1,7 @@ -import { Canvas, Controls, Meta, Source } from '@storybook/addon-docs/blocks'; +import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks'; import * as HeaderStories from './header.stories'; import './header.styles.scss'; import StylesPackageImport from '@/shared/styles-package-import.mdx'; -import HeaderSelectedClass from './header-selected-class.sample.html?raw'; @@ -13,38 +12,70 @@ import HeaderSelectedClass from './header-selected-class.sample.html?raw'; -
The header of the Post.
+
+ Allow users to navigate through your application. +
+ +The Header adapts to your needs and can contain a variety of sub-components depending on your use case. + +It is divided into two sections: + +1. **Global Header** (Yellow Background): provides navigation links and information that are global to the entire organization. +2. **Application Header** (White Background): displays navigation links and information specific to the current application. - +
+ +
-## Styling Active Navigation Items with `aria-current="page"` +## Installation -

The `aria-current="page"` attribute highlights the active navigation items. It should be applied by application logic to the `` element inside the active `` of the ``. Once an element has `aria-current="page"`, its hierarchical parent will also inherit the same styling automatically.

+The `` element is part of the `@swisspost/design-system-components` package. +For more information, read the [getting started with components guide](/?path=/docs/edfb619b-fda1-4570-bf25-20830303d483--docs). -### Example + - +### CSS Properties -## CSS Properties +The `` styles expose several custom properties on the `:root` element: -The `` component exposes the following custom properties to the `:root` element: +- `--post-header-height`: the current visible height of the header +- `--post-header-expanded-height`: the height of the header when expanded +- `--post-header-reduced-height`: the height of the header when reduced -
    -
  • - `--post-header-height`: This property represents the height of the header that is currently - visible in the viewport. -
    • -
  • `--post-header-expanded-height`: This property represents the actual size of the header.
    • -
-Additionally, it sets the `scroll-padding-top` property to equal the visible header height, which can -be useful for pages that use scroll navigation. +In addition, the `` styles set the `scroll-padding-top` property on the `` element to match the currently visible header height. +This ensures that when using scroll navigation (e.g. jumping to anchors), content is positioned correctly below the header. -## Installation +## Active Navigation Items -The `` element is part of the `@swisspost/design-system-components` package. -For more information, read the [getting started with components guide](/?path=/docs/edfb619b-fda1-4570-bf25-20830303d483--docs). +**The `aria-current="page"` attribute highlights the active navigation items** - +This attribute is not added automatically, +it must be applied by your application logic to the `` element of the `` that represents the page currently being viewed. +Once applied, parent items in the navigation automatically inherit the correct selected styling. + + + +## Examples + +### Post Portal + +The Header for the Post Portal (post.ch) is a consistently available interface element that provides a consistent navigation experience across the whole Post Portal and other portals. + +It not only contains globally available key elements (such as Language), it also provides a first content selection via the target group buttons. They define the further navigation. + + + +### Microsite + +The Microsite Header is a consistently available interface element that provides a consistent navigation experience across the whole Microsite. + + + +### One Pager + +The One Pager Header is a consistently available interface element that provides a consistent navigation experience across the whole One Pager. + + diff --git a/packages/documentation/src/stories/components/header/header.stories.ts b/packages/documentation/src/stories/components/header/header.stories.ts index 74b5ff84d9..234e93d1a1 100644 --- a/packages/documentation/src/stories/components/header/header.stories.ts +++ b/packages/documentation/src/stories/components/header/header.stories.ts @@ -1,4 +1,4 @@ -import type { Args, StoryObj } from '@storybook/web-components-vite'; +import { Args, StoryContext, StoryFn, StoryObj } from '@storybook/web-components-vite'; import { MetaComponent } from '@root/types'; import { html } from 'lit'; import { fakeContent } from '@/utils'; @@ -17,11 +17,11 @@ const meta: MetaComponent = { }, }, args: { - title: '[Title]', + title: '', mainNavigation: true, metaNavigation: true, - customControls: true, - targetGroup: false, + targetGroup: true, + customControls: false, }, argTypes: { title: { @@ -46,7 +46,8 @@ const meta: MetaComponent = { }, metaNavigation: { name: 'Meta navigation', - description: 'Whether or not the meta navigation is displayed ("about us" and "jobs").', + description: + 'Whether or not the meta navigation is displayed ("jobs" and "create an account").', control: { type: 'boolean', }, @@ -81,196 +82,256 @@ const meta: MetaComponent = {
${story()} ${fakeContent()}
`, ], + render: getHeaderRenderer(), }; +function getHeaderRenderer(mainnavigation = renderMainnavigation()) { + return (args: Args) => html` + + Homepage + + ${args.metaNavigation + ? html` + + + ` + : ''} + + + + + + + + + + + de + fr + it + en + + + ${args.title !== '' + ? html` + +

${args.title}

+ ` + : ''} + ${args.targetGroup + ? html` + + ` + : ''} + ${args.customControls + ? html` + + + ` + : ''} + ${args.mainNavigation ? mainnavigation : ''} + `; +} + +function renderMainnavigation() { + return html` + + + +

Main Navigation

+ + + Letters + + + Packages + + + + + Letters + + + Close +

Letters title

+ +

Send letters

+ + Letters Switzerland + + + Small items abroad + + + Goods abroad + + + Express and courier + + + +

Step by step

+ + Packages Switzerland + + + Small items abroad + + + Goods abroad + + + Express and courier + + + + + + Packages + + + Close +

Packages title

+ +

Send packages

+ + Packages Switzerland + + + Small items abroad + + + Goods abroad + + + Express and courier + + + +

Step by step

+ + Packages Switzerland + + + Small items abroad + + + Goods abroad + + + Express and courier + + + + + + + `; +} + +function getIframeParameters(iframeHeight: number) { + return { + parameters: { + docs: { + story: { + inline: false, + iframeHeight, + }, + }, + }, + }; +} + export default meta; type Story = StoryObj; -const Template = { - render: (args: Args) => { - return html` - - Homepage +export const Default: Story = {}; - ${args.metaNavigation - ? html` - - - ` - : ''} - - - - - - - +export const ActiveNavigationItem: Story = { + ...getIframeParameters(250), + decorators: [ + (story: StoryFn, context: StoryContext) => { + const renderHeader = getHeaderRenderer(html` ${story(context.args, context)} `); + return renderHeader(context.args); + }, + ], + render: () => html` + + +

Main Navigation

+ + Letters + - - - de - fr - it - en - + + + Packages + + + + `, +}; - ${args.title !== '' - ? html` - -

${args.title}

- ` - : ''} - ${args.targetGroup - ? html` - - ` - : ''} - ${args.customControls - ? html` - - - ` - : ''} - ${args.mainNavigation - ? html` - - - -

Main Navigation

- - Letters - Packages +export const Portal: Story = { + ...getIframeParameters(550), +}; - - - Letters - - - Close -

Letters title

- -

Send letters

- Letters Switzerland - Small items abroad - Goods abroad - Express and courier - - -

Step by step

- Packages Switzerland - Small items abroad - Goods abroad - Express and courier - - - - - Packages - - - Close -

Packages title

- -

Send packages

- Packages Switzerland - Small items abroad - Goods abroad - Express and courier - - -

Step by step

- Packages Switzerland - Small items abroad - Goods abroad - Express and courier - - - - - - ` - : ''} - `; +export const Microsite: Story = { + ...getIframeParameters(550), + args: { + title: '[Microsite Title]', + mainNavigation: true, + metaNavigation: false, + customControls: true, + targetGroup: false, }, }; -export const Default: Story = { - ...Template, +export const OnePager: Story = { + ...getIframeParameters(250), + args: { + title: '[One Pager Title]', + mainNavigation: false, + metaNavigation: false, + customControls: false, + targetGroup: false, + }, }; // Used in target group documentation @@ -278,5 +339,4 @@ export const WithTargetGroup: Story = { args: { targetGroup: true, }, - ...Template, }; diff --git a/packages/documentation/src/stories/components/header/header.styles.scss b/packages/documentation/src/stories/components/header/header.styles.scss index 133eb10dd8..4150ed485f 100644 --- a/packages/documentation/src/stories/components/header/header.styles.scss +++ b/packages/documentation/src/stories/components/header/header.styles.scss @@ -1,8 +1,19 @@ #storybook-docs { .header-story-wrapper { .virtual-body { - height: 500px; + height: 550px; overflow-y: auto; } } + + .docs-story { + &:not(:where(.main-story *)) > :first-child { + overflow: hidden; + } + + &:where(.main-story *) + div { + height: 550px; + resize: vertical; + } + } }