From 0f5c3b8498b66fe2b8a2e8a32bfc7392a9edbf45 Mon Sep 17 00:00:00 2001
From: leagrdv <lea.gardavaud@post.ch>
Date: Thu, 9 Jan 2025 15:07:02 +0100
Subject: [PATCH] chore(documentation, components): update header documentation

---
 .changeset/cyan-years-pretend.md              |   6 +
 .../components/post-header/post-header.tsx    |  12 +-
 .../src/components/post-header/readme.md      |  13 ++
 .../header/components/header.markup.ts        | 117 ------------
 .../stories/modules/header/header.docs.mdx    |  12 +-
 .../stories/modules/header/header.stories.ts  | 173 +++++++++++++++++-
 6 files changed, 206 insertions(+), 127 deletions(-)
 create mode 100644 .changeset/cyan-years-pretend.md
 delete mode 100644 packages/documentation/src/stories/modules/header/components/header.markup.ts

diff --git a/.changeset/cyan-years-pretend.md b/.changeset/cyan-years-pretend.md
new file mode 100644
index 0000000000..944b3799ef
--- /dev/null
+++ 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
index b71d906cc5..668aeaccf1 100644
--- 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
index 209d14f699..fbe1dd99c8 100644
--- 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
deleted file mode 100644
index 43542e2c62..0000000000
--- a/packages/documentation/src/stories/modules/header/components/header.markup.ts
+++ /dev/null
@@ -1,117 +0,0 @@
-import { html } from 'lit-html';
-
-export default html`<post-header>
-  <!-- Logo -->
-  <post-logo slot="post-logo" url="/">Homepage</post-logo>
-
-  <!-- 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>
-
-  <!-- Application title (optional) -->
-  <h1 slot="title">Application title</h1>
-
-  <!-- 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 p-0">
-      <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 px-0">
-            <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 px-0">
-            <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>`;
diff --git a/packages/documentation/src/stories/modules/header/header.docs.mdx b/packages/documentation/src/stories/modules/header/header.docs.mdx
index 3f23445cb5..e66430121d 100644
--- 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
index 06546b6b31..fcf2d89a86 100644
--- 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,8 +15,43 @@ 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;
@@ -23,7 +59,132 @@ 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>`;
   },
 };