chore(documentation, components): update header documentation

swisspost · Jan 9, 2025 · 0f5c3b8 · 0f5c3b8
1 parent a9aadb7
commit 0f5c3b8
Show file tree

Hide file tree

Showing 6 changed files with 206 additions and 127 deletions.
diff --git a/.changeset/cyan-years-pretend.md b/.changeset/cyan-years-pretend.md
@@ -0,0 +1,6 @@
+---
+'@swisspost/design-system-documentation': patch
+'@swisspost/design-system-components': patch
+---
+
+Updated the documentation of the Post header.
diff --git a/packages/components/src/components/post-header/post-header.tsx b/packages/components/src/components/post-header/post-header.tsx
@@ -6,6 +6,16 @@ import { slideDown, slideUp } from '@/animations/slide';
 
 type DEVICE_SIZE = 'mobile' | 'tablet' | 'desktop' | null;
 
+/**
+ * @slot post-logo - Should be used together with the `<post-logo>` component.
+ * @slot meta-navigation - Holds an `<ul>` with meta navigation links.
+ * @slot post-togglebutton - Holds the mobile menu toggler.
+ * @slot post-language-switch - Should be used with the `<post-language-switch>` component.
+ * @slot title - Holds the application title.
+ * @slot default - Custom controls or content, right aligned in the local header.
+ * @slot post-mainnavigation - Has a default slot because it's only meant to be used in the `<post-header>`.
+ */
+
 @Component({
   tag: 'post-header',
   shadow: true,
@@ -113,7 +123,7 @@ export class PostHeader {
       this.mobileMenuAnimation.finish(); // no animation
     }
 
-    const mhh = this.host.shadowRoot.querySelector('.title-header').clientHeight;
+    const mhh = this.host.shadowRoot.querySelector('.title-header')?.clientHeight;
     this.host.style.setProperty('--main-header-height', `${mhh}px`);
 
     // Apply only on change for doing work only when necessary

diff --git a/packages/components/src/components/post-header/readme.md b/packages/components/src/components/post-header/readme.md
@@ -18,6 +18,19 @@ Type: `Promise<void>`
 
 
 
+## Slots
+
+| Slot                     | Description                                                                   |
+| ------------------------ | ----------------------------------------------------------------------------- |
+| `"default"`              | Custom controls or content, right aligned in the local header.                |
+| `"meta-navigation"`      | Holds an `<ul>` with meta navigation links.                                   |
+| `"post-language-switch"` | Should be used with the `<post-language-switch>` component.                   |
+| `"post-logo"`            | Should be used together with the `<post-logo>` component.                     |
+| `"post-mainnavigation"`  | Has a default slot because it's only meant to be used in the `<post-header>`. |
+| `"post-togglebutton"`    | Holds the mobile menu toggler.                                                |
+| `"title"`                | Holds the application title.                                                  |
+
+
 ----------------------------------------------
 
 *Built with [StencilJS](https://stenciljs.com/)*
diff --git a/packages/documentation/src/stories/modules/header/components/header.markup.ts b/packages/documentation/src/stories/modules/header/components/header.markup.ts
diff --git a/packages/documentation/src/stories/modules/header/header.docs.mdx b/packages/documentation/src/stories/modules/header/header.docs.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 import * as HeaderStories from './header.stories';
+import StylesPackageImport from '@/shared/styles-package-import.mdx';
 
 <Meta of={HeaderStories} />
 
@@ -11,11 +12,16 @@ import * as HeaderStories from './header.stories';
   </nav>
 </div>
 
-<div className="lead">
-  The header of the Post.
-</div>
+<div className="lead">The header of the Post.</div>
 
 <Canvas sourceState="shown" of={HeaderStories.Default} />
 <div className="hide-col-default">
   <Controls of={HeaderStories.Default} />
 </div>
+
+## Installation
+
+The `<post-header>` 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).
+
+<StylesPackageImport components={['header', 'list', 'button']} />
diff --git a/packages/documentation/src/stories/modules/header/header.stories.ts b/packages/documentation/src/stories/modules/header/header.stories.ts
@@ -1,11 +1,12 @@
 import type { StoryObj } from '@storybook/web-components';
 import { MetaComponent } from '@root/types';
-import HeaderMarkup from './components/header.markup';
+import { html } from 'lit-html';
 
 const meta: MetaComponent = {
   id: 'header',
   title: 'Modules/Header',
-  tags: ['package:HTML'],
+  tags: ['package:WebComponents'],
+  component: 'post-header',
   parameters: {
     layout: 'fullscreen',
     badges: [],
@@ -14,16 +15,176 @@ const meta: MetaComponent = {
       url: 'https://www.figma.com/design/JIT5AdGYqv6bDRpfBPV8XR/Foundations-%26-Components-Next-Level?node-id=558-7012&t=ywmfJhyvd2euoiGI-1',
     },
   },
-  args: {},
-  argTypes: {},
+  args: {
+    title: 'Application title',
+    metaNavigation: true,
+    customControls: true,
+  },
+  argTypes: {
+    title: {
+      name: 'Application title',
+      description: 'Title of the webpage or application.',
+      control: {
+        type: 'text',
+      },
+      table: {
+        category: 'Content',
+      },
+    },
+    metaNavigation: {
+      name: 'Meta navigation',
+      description: 'Whether or not the meta navigation is displayed ("about us" and "jobs").',
+      control: {
+        type: 'boolean',
+      },
+      table: {
+        category: 'Content',
+      },
+    },
+    customControls: {
+      name: 'Custom controls',
+      description: 'Whether or not the custom controls are displayed ("search" and "login").',
+      control: {
+        type: 'boolean',
+      },
+      table: {
+        category: 'Content',
+      },
+    },
+  },
 };
 
 export default meta;
 
 type Story = StoryObj;
 
 export const Default: Story = {
-  render: () => {
-    return HeaderMarkup;
+  render: args => {
+    return html`<post-header>
+      <!-- Logo -->
+      <post-logo slot="post-logo" url="/">Homepage</post-logo>
+
+      ${args.metaNavigation
+        ? html`
+            <!-- Meta navigation -->
+            <ul class="list-inline" slot="meta-navigation">
+              <li><a href="">Jobs</a></li>
+              <li><a href="">Über uns</a></li>
+            </ul>
+          `
+        : ''}
+
+      <!-- Menu button for mobile -->
+      <post-togglebutton slot="post-togglebutton">
+        <span class="visually-hidden-sm">Menu</span>
+        <post-icon aria-hidden="true" name="burger" data-showWhen="untoggled"></post-icon>
+        <post-icon aria-hidden="true" name="closex" data-showWhen="toggled"></post-icon>
+      </post-togglebutton>
+
+      <!-- Language switch -->
+      <post-language-switch
+        caption="Caption"
+        description="Description"
+        variant="list"
+        name="language-switch-example"
+        slot="post-language-switch"
+      >
+        <post-language-option active="true" code="de" name="Deutsch">DE</post-language-option>
+        <post-language-option active="false" code="fr" name="French">FR</post-language-option>
+        <post-language-option active="false" code="it" name="Italiano">IT</post-language-option>
+        <post-language-option active="false" code="en" name="English">EN</post-language-option>
+      </post-language-switch>
+
+      ${args.title
+        ? html`
+            <!-- Application title (optional) -->
+            <h1 slot="title">${args.title}</h1>
+          `
+        : ''}
+      ${args.customControls
+        ? html`
+            <!-- Custom content (optional) -->
+            <ul class="list-inline">
+              <li>
+                <a href="#">
+                  <span class="visually-hidden-sm">Search</span>
+                  <post-icon aria-hidden="true" name="search"></post-icon>
+                </a>
+              </li>
+              <li>
+                <a href="#">
+                  <span class="visually-hidden-sm">Login</span>
+                  <post-icon aria-hidden="true" name="login"></post-icon>
+                </a>
+              </li>
+            </ul>
+          `
+        : ''}
+
+      <!-- Main navigation -->
+      <post-mainnavigation caption="Hauptnavigation">
+        <button type="button" slot="back-button" class="btn btn-sm btn-tertiary">
+          <post-icon aria-hidden="true" name="3024"></post-icon> Back
+        </button>
+        <post-list title-hidden="">
+          <h2>Main Navigation</h2>
+          <!-- Link only level 1 -->
+          <post-list-item><a href="/briefe">Briefe</a></post-list-item>
+          <post-list-item><a href="/pakete">Pakete</a></post-list-item>
+
+          <!-- Level 1 with megadropdown -->
+          <post-list-item>
+            <post-megadropdown-trigger for="briefe">Briefe</post-megadropdown-trigger>
+            <post-megadropdown id="briefe">
+              <button slot="back-button" class="btn btn-tertiary">
+                <post-icon name="arrowright"></post-icon>
+                Zurück
+              </button>
+              <post-closebutton slot="close-button">Schliessen</post-closebutton>
+              <h2 slot="megadropdown-title"><a href="">Briefe title</a></h2>
+              <post-list>
+                <h3>Briefe senden</h3>
+                <post-list-item><a href="/sch">Briefe Schweiz</a></post-list-item>
+                <post-list-item><a href="/kl">Kleinwaren Ausland</a></post-list-item>
+                <post-list-item><a href="">Waren Ausland</a></post-list-item>
+                <post-list-item><a href="">Express und Kurier</a></post-list-item>
+              </post-list>
+              <post-list>
+                <h3><a href="/schritt-für-schritt">Schritt für Schritt</a></h3>
+                <post-list-item><a href="/sch">Pakete Schweiz</a></post-list-item>
+                <post-list-item><a href="/kl">Kleinwaren Ausland</a></post-list-item>
+                <post-list-item><a href="">Waren Ausland</a></post-list-item>
+                <post-list-item><a href="">Express und Kurier</a></post-list-item>
+              </post-list>
+            </post-megadropdown>
+          </post-list-item>
+          <post-list-item>
+            <post-megadropdown-trigger for="pakete">Pakete</post-megadropdown-trigger>
+            <post-megadropdown id="pakete">
+              <button slot="back-button" class="btn btn-tertiary">
+                <post-icon name="arrowright"></post-icon>
+                Zurück
+              </button>
+              <post-closebutton slot="close-button">Schliessen</post-closebutton>
+              <h2 slot="megadropdown-title"><a href="">Pakete title</a></h2>
+              <post-list>
+                <h3>Pakete senden</h3>
+                <post-list-item><a href="/sch">Pakete Schweiz</a></post-list-item>
+                <post-list-item><a href="/kl">Kleinwaren Ausland</a></post-list-item>
+                <post-list-item><a href="">Waren Ausland</a></post-list-item>
+                <post-list-item><a href="">Express und Kurier</a></post-list-item>
+              </post-list>
+              <post-list>
+                <h3><a href="/schritt-für-schritt">Schritt für Schritt</a></h3>
+                <post-list-item><a href="/sch">Pakete Schweiz</a></post-list-item>
+                <post-list-item><a href="/kl">Kleinwaren Ausland</a></post-list-item>
+                <post-list-item><a href="">Waren Ausland</a></post-list-item>
+                <post-list-item><a href="">Express und Kurier</a></post-list-item>
+              </post-list>
+            </post-megadropdown>
+          </post-list-item>
+        </post-list>
+      </post-mainnavigation>
+    </post-header>`;
   },
 };