feat(docs): add modal documentation (#2531)

Co-authored-by: Loïc Fürhoff <[email protected]>
Co-authored-by: Philipp Gfeller <[email protected]>

.changeset/afraid-chicken-pump.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': minor
+---
+
+Added a documentation page for the ng-bootstrap modal component.

packages/documentation/.storybook/preview.ts

@@ -47,11 +47,12 @@ const preview: Preview = {
             'Datepicker',
             'Forms',
             'Heading',
-            'Internet Header',
-            ['Getting Started'],
-            'Intranet Header',
             'Icons',
             ['Getting Started'],
+            'Internet Header',
+            ['Getting Started', 'Header'],
+            'Intranet Header',
+            'Modal',
             'Pagination',
             'Popover',
             'Progressbar',

packages/documentation/src/stories/components/modal/modal-blocking.sample.ts

@@ -0,0 +1,47 @@
+import { Component } from '@angular/core';
+import { NgbActiveModal, NgbModal } from '@ng-bootstrap/ng-bootstrap';
+
+@Component({
+  selector: 'ngb-modal-content',
+  standalone: true,
+  template: `
+    <div class="modal-header">
+      <h4 class="modal-title">Confirmation</h4>
+    </div>
+    <div class="modal-body">
+      <p>Do you confirm?</p>
+    </div>
+    <div class="modal-footer">
+      <button type="button" class="btn btn-secondary" (click)="activeModal.close(false)">No</button>
+      <button type="button" class="btn btn-primary" (click)="activeModal.close(true)">Yes</button>
+    </div>
+  `,
+})
+export class ModalComponent {
+  constructor(public activeModal: NgbActiveModal) {}
+}
+
+@Component({
+  selector: 'ngb-modal-component',
+  standalone: true,
+  template: `
+    <button class="btn btn-secondary" (click)="open()">Open Modal</button>
+  `,
+})
+export class HostComponent {
+  constructor(private modalService: NgbModal) {}
+
+  open() {
+    const modalRef = this.modalService.open(ModalComponent, {
+      backdrop: 'static',
+      keyboard: false,
+    });
+    modalRef.result
+      .catch(() => {
+        console.error('Modal dismissal is actually not be possible.');
+      })
+      .then((isConfirmed: boolean) => {
+        console.info(`Confirmed? ${isConfirmed}`);
+      });
+  }
+}

packages/documentation/src/stories/components/modal/modal-focused-content.sample.ts

@@ -0,0 +1,61 @@
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { NgbActiveModal, NgbModal } from '@ng-bootstrap/ng-bootstrap';
+
+@Component({
+  selector: 'ngb-modal-content',
+  standalone: true,
+  imports: [FormsModule],
+  template: `
+    <div class="modal-header">
+      <h4 id="modalTitle" class="modal-title">What is your name?</h4>
+      <button
+        type="button"
+        class="btn-close"
+        aria-label="Close"
+        (click)="activeModal.dismiss()"
+      ></button>
+    </div>
+    <div class="modal-body">
+      <input
+        ngbAutofocus
+        [(ngModel)]="name"
+        type="text"
+        class="form-control"
+        aria-labelledby="modalTitle"
+      />
+    </div>
+    <div class="modal-footer">
+      <button type="button" class="btn btn-primary" (click)="activeModal.close(name)">
+        Validate
+      </button>
+    </div>
+  `,
+})
+export class ModalComponent {
+  name = '';
+
+  constructor(public activeModal: NgbActiveModal) {}
+}
+
+@Component({
+  selector: 'ngb-modal-component',
+  standalone: true,
+  template: `
+    <button class="btn btn-secondary" (click)="open()">Open modal</button>
+  `,
+})
+export class HostComponent {
+  constructor(private modalService: NgbModal) {}
+
+  open() {
+    const modalRef = this.modalService.open(ModalComponent);
+    modalRef.result
+      .catch(() => {
+        console.error('Modal was dismissed.');
+      })
+      .then((name: string) => {
+        console.info(`The name is: ${name}`);
+      });
+  }
+}

packages/documentation/src/stories/components/modal/modal-varying-content.sample.ts

@@ -0,0 +1,46 @@
+import { Component, Input } from '@angular/core';
+import { NgbActiveModal, NgbModal } from '@ng-bootstrap/ng-bootstrap';
+
+@Component({
+  selector: 'ngb-modal-content',
+  standalone: true,
+  template: `
+    <div class="modal-header">
+      <h4 class="modal-title">Hi there!</h4>
+      <button
+        type="button"
+        class="btn-close"
+        aria-label="Close"
+        (click)="activeModal.dismiss()"
+      ></button>
+    </div>
+    <div class="modal-body">
+      <p>Hello, {{ name }}!</p>
+    </div>
+    <div class="modal-footer">
+      <button type="button" class="btn btn-secondary" (click)="activeModal.close()">Close</button>
+    </div>
+  `,
+})
+export class ModalComponent {
+  @Input() name;
+
+  constructor(public activeModal: NgbActiveModal) {}
+}
+
+@Component({
+  selector: 'ngb-modal-component',
+  standalone: true,
+  template: `
+    <button class="btn btn-secondary" (click)="open('foo')">Open with foo</button>
+    <button class="btn btn-secondary" (click)="open('bar')">Open with bar</button>
+  `,
+})
+export class HostComponent {
+  constructor(private modalService: NgbModal) {}
+
+  open(name: string) {
+    const modalRef = this.modalService.open(ModalComponent);
+    modalRef.componentInstance.name = name;
+  }
+}

packages/documentation/src/stories/components/modal/modal.docs.mdx

@@ -0,0 +1,68 @@
+import { Meta, Source } from '@storybook/blocks';
+import { PostTabs, PostTabHeader, PostTabPanel } from '@swisspost/design-system-components-react';
+import StylesPackageImport from '../../../shared/styles-package-import.mdx';
+import NgbComponentDemoLink from '../../../shared/nb-bootstrap/ngb-component-demo-link.mdx';
+import NgbComponentAlert from '../../../shared/nb-bootstrap/ngb-component-alert.mdx';
+import NgbComponentImport from '../../../shared/nb-bootstrap/ngb-component-import.mdx';
+import * as modalStories from './modal.stories';
+import modalVaryingContent from './modal-varying-content.sample?raw';
+import modalFocusedContent from './modal-focused-content.sample?raw';
+import modalBlocking from './modal-blocking.sample?raw';
+
+<Meta of={modalStories} />
+
+<div className="d-flex align-items-center justify-content-between">
+  # Modal
+
+  <NgbComponentDemoLink component="modal" />
+</div>
+
+<p className="lead">Display information that requires the user’s immediate attention.</p>
+
+<NgbComponentAlert component="modal" />
+
+<ul>
+  <li>
+    <a href="#component-import" target="_self">Component Import</a>
+  </li>
+  <li>
+    <a href="#style-imports" target="_self">Style Imports</a>
+  </li>
+  <li>
+    <a href="#focus-management" target="_self">Focus Management</a>
+  </li>
+  <li>
+    <a href="#examples" target="_self">Examples</a>
+  </li>
+</ul>
+
+<NgbComponentImport module="NgbModalModule" />
+
+<StylesPackageImport components={["modal"]} />
+
+## Focus Management
+Since the modal appears above the page, generally blocking interaction with the content below,
+it is important that the focus is move to an element within it.
+
+By default, it is the first focusable element within the modal that receives focus upon opening.
+However, You can decide to focus any other element by adding an `ngbAutofocus` attribute to it.
+
+## Examples
+
+<PostTabs>
+  <PostTabHeader slot="tabs" panel="varying-content">Varying Content</PostTabHeader>
+  <PostTabPanel name="varying-content">
+    <Source code={modalVaryingContent} language="typescript"/>
+  </PostTabPanel>
+
+  <PostTabHeader slot="tabs" panel="focused-content">Focused Content</PostTabHeader>
+  <PostTabPanel name="focused-content">
+    <Source code={modalFocusedContent} language="typescript"/>
+  </PostTabPanel>
+
+  <PostTabHeader slot="tabs" panel="blocking">Mandatory Confirmation</PostTabHeader>
+  <PostTabPanel name="blocking">
+    <Source code={modalBlocking} language="typescript"/>
+  </PostTabPanel>
+</PostTabs>
+

packages/documentation/src/stories/components/modal/modal.stories.ts

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { html } from 'lit';
+import { BADGE } from '../../../../.storybook/constants';
+
+const meta: Meta = {
+  title: 'Components/Modal',
+  parameters: {
+    badges: [BADGE.WEB_COMPONENT_CANDIDATE],
+  },
+};
+
+export default meta;
+
+export const Default: StoryObj = {
+  render: () => html``,
+};