feat(wcp-navigation): add togglability to navigation

Author: davidenke

src/components/features/navigation/navigation-item/navigation-item.component.scss

@@ -45,15 +45,33 @@
   }
 }
 
-a,
 span {
   display: block;
   padding: var(---wcp-navigation-item-spacing);
 
+  overflow: hidden;
   text-decoration: none;
   text-overflow: ellipsis;
   white-space: nowrap;
 
   background-color: var(---wcp-navigation-item-background);
   color: var(---wcp-navigation-item-color);
 }
+
+// as the surrounding navigation element might be inset, we add the background
+// in front to fill the whole navigation width to increase the clickable area
+a {
+  position: relative;
+  color: inherit;
+  text-decoration: none;
+
+  &::before {
+    content: '';
+
+    position: absolute;
+    inset: 0 100% 0 auto;
+    width: calc(var(---wcp-aside-max-width, 100vw) - 100%);
+
+    background-color: var(---wcp-navigation-item-background);
+  }
+}

src/components/features/navigation/navigation-item/navigation-item.component.ts

@@ -42,7 +42,11 @@ export class NavigationItem extends ColorSchemable(LitElement) {
     return html`
       ${when(
         this.href !== undefined,
-        () => html`<a href="${ifDefined(this.href)}"><slot></slot></a>`,
+        () => html`
+          <a href="${ifDefined(this.href)}">
+            <span><slot></slot></span>
+          </a>
+        `,
         () => html`<span><slot></slot></span>`,
       )}
     `;

src/components/features/navigation/navigation/EXAMPLES.md

@@ -12,7 +12,38 @@
 ```html
 <wcp-navigation headline="Navigation">
   <wcp-navigation-item href="/home">Home</wcp-navigation-item>
-  <wcp-navigation nested headline="Nested">
+  <wcp-navigation headline="Nested">
+    <wcp-navigation-item href="/about">About</wcp-navigation-item>
+    <wcp-navigation-item href="/imprint">Imprint</wcp-navigation-item>
+  </wcp-navigation>
+</wcp-navigation>
+```
+
+### Togglable navigation
+
+```html
+<wcp-navigation headline="Navigation" togglable>
+  <wcp-navigation-item href="/home">Home</wcp-navigation-item>
+  <wcp-navigation-item href="/about">About</wcp-navigation-item>
+</wcp-navigation>
+```
+
+### Initially opened togglable navigation
+
+```html
+<wcp-navigation headline="Navigation" togglable open>
+  <wcp-navigation-item href="/home">Home</wcp-navigation-item>
+  <wcp-navigation-item href="/about">About</wcp-navigation-item>
+</wcp-navigation>
+```
+
+### Togglable nested navigation
+
+```html
+<wcp-navigation headline="Navigation">
+  <wcp-navigation-item href="/home">Home</wcp-navigation-item>
+  <wcp-navigation-item href="/about">About</wcp-navigation-item>
+  <wcp-navigation togglable headline="Nested">
     <wcp-navigation-item href="/about">About</wcp-navigation-item>
     <wcp-navigation-item href="/imprint">Imprint</wcp-navigation-item>
   </wcp-navigation>

src/components/features/navigation/navigation/README.md

@@ -6,29 +6,52 @@
 
 ## Properties
 
-| Property   | Attribute  | Type                  | Default |
-|------------|------------|-----------------------|---------|
-| `headline` | `headline` | `string \| undefined` |         |
-| `nested`   | `nested`   | `boolean`             | false   |
+| Property    | Attribute   | Type                  | Default | Description                                      |
+|-------------|-------------|-----------------------|---------|--------------------------------------------------|
+| `headline`  | `headline`  | `string \| undefined` |         | An optional headline to be shown for categorization |
+| `open`      | `open`      | `boolean`             | false   | If togglable, this flag indicates if the nested items are currently visible |
+| `togglable` | `togglable` | `boolean`             | false   | Allows the nested items to be toggled            |
+
+## Methods
+
+| Method           | Type                           |
+|------------------|--------------------------------|
+| `toggleClick`    | `(): void`                     |
+| `toggleKeyboard` | `(event: KeyboardEvent): void` |
+
+## Events
+
+| Event                   | Description                                   |
+|-------------------------|-----------------------------------------------|
+| `wcp-navigation-toggle` | Emitted when the togglable open state changes |
 
 ## Slots
 
-| Name | Description                                      |
-|------|--------------------------------------------------|
-|      | Default slot for navigation items or nested navigation |
+| Name     | Description                                      |
+|----------|--------------------------------------------------|
+|          | Default slot for navigation items or nested navigation |
+| `action` | Slot for an action to be shown next to the headline |
+
+## CSS Shadow Parts
+
+| Part       | Description                    |
+|------------|--------------------------------|
+| `headline` | The headline of the navigation |
+| `nav`      | The nested navigation          |
 
 ## CSS Custom Properties
 
-| Property                                     | Description                                      |
-|----------------------------------------------|--------------------------------------------------|
-| `--wcp-navigation-dark-border-color`         | Border color of the navigation headline in dark mode |
-| `--wcp-navigation-headline-dark-background`  | Background color of the navigation headline in dark mode |
-| `--wcp-navigation-headline-light-background` | Background color of the navigation headline in light mode |
-| `--wcp-navigation-headline-size`             | Font size of the navigation headline             |
-| `--wcp-navigation-headline-spacing`          | Letter spacing of the navigation headline        |
-| `--wcp-navigation-headline-weight`           | Font weight of the navigation headline           |
-| `--wcp-navigation-inset`                     | Inset of the navigation if nested (is applied on each level) |
-| `--wcp-navigation-light-border-color`        | Border color of the navigation headline in light mode |
-| `--wcp-navigation-spacing`                   | Spacing between navigation and headline          |
-| `--wcp-navigation-spacing-headline`          | Inner padding of the navigation headline         |
-| `--wcp-navigation-spacing-items`             | Spacing between navigation items                 |
+| Property                                      | Description                                      |
+|-----------------------------------------------|--------------------------------------------------|
+| `--wcp-navigation-dark-border-color`          | Border color of the navigation headline in dark mode |
+| `--wcp-navigation-headline-dark-background`   | Background color of the navigation headline in dark mode |
+| `--wcp-navigation-headline-light-background`  | Background color of the navigation headline in light mode |
+| `--wcp-navigation-headline-size`              | Font size of the navigation headline             |
+| `--wcp-navigation-headline-spacing`           | Letter spacing of the navigation headline        |
+| `--wcp-navigation-headline-weight`            | Font weight of the navigation headline           |
+| `--wcp-navigation-inset`                      | Inset of the navigation if nested (is applied on each level) |
+| `--wcp-navigation-light-border-color`         | Border color of the navigation headline in light mode |
+| `--wcp-navigation-spacing`                    | Spacing between navigation and headline          |
+| `--wcp-navigation-spacing-headline`           | Inner padding of the navigation headline         |
+| `--wcp-navigation-spacing-headline-togglable` | Inner padding of the navigation headline if togglable |
+| `--wcp-navigation-spacing-items`              | Spacing between navigation items                 |

src/components/features/navigation/navigation/navigation.component.scss

@@ -5,6 +5,7 @@
   ---wcp-navigation-spacing: var(--wcp-navigation-spacing, #{0 0 utils.size(1)});
   ---wcp-navigation-spacing-items: var(--wcp-navigation-spacing-items, 0);
   ---wcp-navigation-spacing-headline: var(--wcp-navigation-spacing-headline, #{utils.size(1.5) 0 utils.size(1) utils.size(2)});
+  ---wcp-navigation-spacing-headline-togglable: var(--wcp-navigation-spacing-headline-togglable, #{utils.size(1) utils.size(1) utils.size(1) utils.size(2)});
 
   ---wcp-navigation-inset: var(--wcp-navigation-inset, #{utils.size(1.5)});
 
@@ -36,9 +37,10 @@
 }
 
 h3 {
-  position: sticky;
-  top: 0;
-  z-index: 1;
+  display: flex;
+  flex-direction: row;
+  gap: 1em;
+  align-items: center;
 
   margin: 0;
   padding: var(---wcp-navigation-spacing-headline);
@@ -51,32 +53,55 @@ h3 {
   line-height: 1;
 
   span {
+    flex: 1 1 auto;
     display: block;
+
     overflow: hidden;
     text-overflow: ellipsis;
     text-transform: uppercase;
+    white-space: nowrap;
+  }
+
+  :host([togglable]) & {
+    cursor: pointer;
+    padding: var(---wcp-navigation-spacing-headline-togglable);
+
+    wcp-icon {
+      flex: 0 1 auto;
+      pointer-events: none;
+      color: var(---wcp-navigation-border-color);
+      --wcp-icon-size: 20;
+    }
   }
 
-  :host(:not([nested])) &::before {
-    content: '';
+  // static first level headlines are treated as sticky categories with a separator
+  :host(:not([togglable])) & {
+    position: sticky;
+    top: 0;
+    z-index: 1;
 
-    position: absolute;
-    inset: -1px 0 auto;
-    height: 1px;
+    &::before {
+      content: '';
 
-    background-color: var(---wcp-navigation-border-color);
+      position: absolute;
+      inset: -1px 0 auto;
+      height: 1px;
+
+      background-color: var(---wcp-navigation-border-color);
+    }
   }
 }
 
 nav {
   position: relative;
+  margin-left: var(---wcp-navigation-inset);
   padding: var(---wcp-navigation-spacing);
 
   display: flex;
   flex-direction: column;
   gap: var(---wcp-navigation-spacing-items);
-}
 
-:host([nested]) {
-  margin-left: var(---wcp-navigation-inset);
+  :host([togglable]:not([open])) & {
+    display: none;
+  }
 }

src/components/features/navigation/navigation/navigation.component.ts

@@ -1,5 +1,6 @@
 import { html, LitElement, type TemplateResult, unsafeCSS } from 'lit';
-import { customElement, property } from 'lit/decorators.js';
+import { customElement, eventOptions, property } from 'lit/decorators.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
 import { when } from 'lit/directives/when.js';
 
 import { ColorSchemable } from '@/mixins/color-schemable.mixin.js';
@@ -8,10 +9,15 @@ import styles from './navigation.component.scss';
 
 /**
  * @slot - Default slot for navigation items or nested navigation
+ * @slot action - Slot for an action to be shown next to the headline
+ *
+ * @csspart headline - The headline of the navigation
+ * @csspart nav - The nested navigation
  *
  * @cssprop --wcp-navigation-spacing - Spacing between navigation and headline
  * @cssprop --wcp-navigation-spacing-items - Spacing between navigation items
  * @cssprop --wcp-navigation-spacing-headline - Inner padding of the navigation headline
+ * @cssprop --wcp-navigation-spacing-headline-togglable - Inner padding of the navigation headline if togglable
  * @cssprop --wcp-navigation-inset - Inset of the navigation if nested (is applied on each level)
  * @cssprop --wcp-navigation-dark-border-color - Border color of the navigation headline in dark mode
  * @cssprop --wcp-navigation-light-border-color - Border color of the navigation headline in light mode
@@ -20,28 +26,76 @@ import styles from './navigation.component.scss';
  * @cssprop --wcp-navigation-headline-spacing - Letter spacing of the navigation headline
  * @cssprop --wcp-navigation-headline-dark-background - Background color of the navigation headline in dark mode
  * @cssprop --wcp-navigation-headline-light-background - Background color of the navigation headline in light mode
+ *
+ * @emits wcp-navigation-toggle - Emitted when the togglable open state changes
  */
 @customElement('wcp-navigation')
 export class Navigation extends ColorSchemable(LitElement) {
   static override readonly styles = unsafeCSS(styles);
 
+  /**
+   * An optional headline to be shown for categorization
+   */
   @property({ type: String, reflect: true })
   headline?: string;
 
+  /**
+   * Allows the nested items to be toggled
+   */
+  @property({ type: Boolean, reflect: true })
+  togglable = false;
+
+  /**
+   * If togglable, this flag indicates if the nested items are currently visible
+   */
   @property({ type: Boolean, reflect: true })
-  nested = false;
+  open = false;
+
+  @eventOptions({ passive: true })
+  toggleClick(): void {
+    if (!this.togglable) return;
+    this.open = !this.open;
+    this.dispatchEvent(new CustomEvent('wcp-navigation-toggle', { detail: this.open }));
+  }
+
+  @eventOptions({ capture: true })
+  toggleKeyboard(event: KeyboardEvent): void {
+    if (!this.togglable) return;
+    if (![' ', 'Enter'].includes(event.key)) return;
+
+    event.preventDefault();
+    this.open = !this.open;
+    this.dispatchEvent(new CustomEvent('wcp-navigation-toggle', { detail: this.open }));
+  }
 
   protected override render(): TemplateResult {
     return html`
-      ${when(this.headline !== undefined, () => html`<h3 part="headline"><span>${this.headline}</span></h3>`)}
-      <nav>
-        <slot></slot>
-      </nav>
+      ${when(
+        this.headline !== undefined,
+        () => html`
+          <h3
+            part="headline"
+            tabindex="${ifDefined(this.togglable ? '0' : undefined)}"
+            @click="${this.toggleClick}"
+            @keydown="${this.toggleKeyboard}"
+          >
+            <span>${this.headline}</span>
+            <slot name="action">
+              ${when(this.togglable, () => html`<wcp-icon name="chevron-${this.open ? 'up' : 'down'}"></wcp-icon>`)}
+            </slot>
+          </h3>
+        `,
+      )}
+      <nav part="nav"><slot></slot></nav>
     `;
   }
 }
 
 declare global {
+  interface HTMLElementEventMap {
+    'wcp-navigation-toggle': CustomEvent<boolean>;
+  }
+
   interface HTMLElementTagNameMap {
     'wcp-navigation': Navigation;
   }

src/components/layout/aside/aside.component.scss

@@ -3,6 +3,7 @@
 // prettier-ignore
 :host {
   ---wcp-aside-max-width: var(--wcp-aside-max-width, #{utils.size(24)});
+  ---wcp-aside-min-width: var(--wcp-aside-min-width, var(---wcp-aside-max-width));
 
   ---wcp-aside-spacing: var(--wcp-aside-spacing, 0);
 
@@ -43,7 +44,7 @@
   @include utils.breakpoint(sm) {
     position: relative;
     max-width: var(---wcp-aside-max-width);
-    min-width: var(---wcp-aside-max-width);
+    min-width: var(---wcp-aside-min-width);
 
     transition: margin-left ease-in-out var(--wcp-fx-layout-duration);
     will-change: margin-left;

src/components/root/root-navigation/root-navigation.component.scss

@@ -6,6 +6,10 @@
   ---wcp-root-navigation-empty-message-font-size: var(--wcp-root-navigation-empty-message-font-size, 0.8em);
 }
 
+:host {
+  user-select: none;
+}
+
 p {
   margin: var(---wcp-root-navigation-empty-message-spacing);
   font-size: var(---wcp-root-navigation-empty-message-font-size);