chore(documentation): Rework getting started section and add Angular CUSTOM_ELEMENTS_SCHEMA info

.changeset/old-pumas-sit.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': patch
+---
+
+Reworked the getting-started section to better understand the different packages and add more info about Angular.

packages/demo/src/app/bootstrap/components/card/complex-card-demo/complex-card-demo.component.html

@@ -140,7 +140,7 @@ <h5 class="card-title">Card title</h5>
 </div>
 
 <h3>Card columns</h3>
-<p>Card columns can be checked out in the swiss post example below.</p>
+<p>Card columns can be checked out in the Swiss Post example below.</p>
 
 <p>
   Default

packages/documentation/.storybook/preview.ts

@@ -25,13 +25,14 @@ const preview: Preview = {
 
           // Category - Getting Started
           'Getting Started',
-          ['Styles', 'Components', 'Components-Angular', 'Compatibility'],
+          ['Introduction', 'Angular', 'Compatibility', 'Packages'],
 
           // Category - Foundations
           'Foundations',
           [
             'Typography',
             'Color',
+            'Search for Icons',
             'Layout',
             ['Breakpoints', 'Containers', 'Grid', 'Columns', 'TODOS'],
             'Elevation',
@@ -40,42 +41,6 @@ const preview: Preview = {
 
           // Category - Components
           'Components',
-          [
-            'Accordion',
-            'Alert',
-            'Badge',
-            'Blockquote',
-            'Button',
-            'Button Group',
-            'Cards',
-            'Carousel',
-            'Collapsible',
-            'Datepicker',
-            'Dropdown',
-            'Forms',
-            'Heading',
-            'Icons',
-            ['Getting Started'],
-            'Internet Header',
-            ['Getting Started', 'Header'],
-            'Intranet Header',
-            'Modal',
-            'Notification overlay',
-            'Pagination',
-            'Popover',
-            'Progressbar',
-            'Rating',
-            'Spinner',
-            'Stepper',
-            'Subnavigation',
-            'Table',
-            'Tabs',
-            'Timepicker',
-            'Toast',
-            'Tooltip',
-            'Topic Teaser',
-            'Typeahead',
-          ],
 
           // Category - Patterns
           'Patterns',

packages/documentation/.storybook/styles/preview.scss

@@ -5,8 +5,6 @@
 
 #storybook-root,
 #storybook-docs {
-  overflow: hidden;
-
   .sbdocs-content .container >,
   .sbdocs-content .container > post-tabs > post-tab-panel >,
   .sbdocs-content .container > migration-global-state {
@@ -38,6 +36,10 @@
     h6 {
       margin-block: 1rem;
     }
+    .table,
+    .table-responsive {
+      margin-block: 1.5rem 1rem;
+    }
   }
 
   .sbdocs-content .container {

packages/documentation/package.json

@@ -35,6 +35,7 @@
   },
   "devDependencies": {
     "@geometricpanda/storybook-addon-badges": "2.0.1",
+    "@lit/task": "1.0.0",
     "@open-wc/lit-helpers": "0.6.0",
     "@percy/cli": "1.27.7",
     "@percy/cypress": "3.1.2",

packages/documentation/src/shared/packages.data.ts

@@ -0,0 +1,152 @@
+import { DEPENDENCIES, getVersion } from '../utils/version';
+import metaStyles from '../stories/getting-started/packages/styles/styles.stories';
+import metaComponents from '../stories/getting-started/packages/components/components.stories';
+import metaComponentsAngular from '../stories/getting-started/packages/components-angular/components-angular.stories';
+import metaInternetHeader from '../stories/getting-started/packages/internet-header/internet-header.stories';
+import metaIntranetHeader from '../stories/getting-started/packages/intranet-header/intranet-header.stories';
+import metaIcons from '../stories/getting-started/packages/icons/package-icons.stories';
+import { PackageType } from '../../types';
+
+interface IPackage {
+  name: string;
+  docsStoryId: string;
+  type: PackageType;
+  link: {
+    [key: string]: {
+      href: string;
+      ariaLabel: string;
+    };
+  };
+  img: {
+    src: string;
+    alt: string;
+  };
+  version: string;
+}
+
+export const packages: IPackage[] = [
+  {
+    name: 'Styles',
+    docsStoryId: metaStyles.id,
+    type: PackageType.Html,
+    link: {
+      github: {
+        href: 'https://github.com/swisspost/design-system/tree/main/packages/styles',
+        ariaLabel: 'Source of Styles package',
+      },
+      docs: {
+        href: generateDocsRelativeLink(metaStyles.id),
+        ariaLabel: 'Getting started with Styles package',
+      },
+    },
+    img: {
+      src: '/assets/images/packages/styles.svg',
+      alt: '',
+    },
+    version: `v${getVersion(DEPENDENCIES['@swisspost/design-system-styles'])}`,
+  },
+  {
+    name: 'Components',
+    docsStoryId: metaComponents.id,
+    type: PackageType.Wc,
+    link: {
+      github: {
+        href: 'https://github.com/swisspost/design-system/tree/main/packages/components',
+        ariaLabel: 'Source of Components package',
+      },
+      docs: {
+        href: generateDocsRelativeLink(metaComponents.id),
+        ariaLabel: 'Getting started with Components package',
+      },
+    },
+    img: {
+      src: '/assets/images/packages/components.svg',
+      alt: '',
+    },
+    version: `v${getVersion(DEPENDENCIES['@swisspost/design-system-components'])}`,
+  },
+  {
+    name: 'Components for Angular',
+    docsStoryId: metaComponentsAngular.id,
+    type: PackageType.Angular,
+    link: {
+      github: {
+        href: 'https://github.com/swisspost/design-system/tree/main/packages/components-angular',
+        ariaLabel: 'Source of Components for Angular package',
+      },
+      docs: {
+        href: generateDocsRelativeLink(metaComponentsAngular.id),
+        ariaLabel: 'Getting started with Components for Angular package',
+      },
+    },
+    img: {
+      src: '/assets/images/packages/components-angular.svg',
+      alt: '',
+    },
+    version: `v${getVersion(DEPENDENCIES['@swisspost/design-system-components-angular'])}`,
+  },
+  {
+    name: 'Internet-Header',
+    docsStoryId: metaInternetHeader.id,
+    type: PackageType.Wc,
+    link: {
+      github: {
+        href: 'https://github.com/swisspost/design-system/tree/main/packages/internet-header',
+        ariaLabel: 'Source of Internet-Header package',
+      },
+      docs: {
+        href: generateDocsRelativeLink(metaInternetHeader.id),
+        ariaLabel: 'Getting started with Internet-Header package',
+      },
+    },
+    img: {
+      src: '/assets/images/packages/internet-header.svg',
+      alt: '',
+    },
+    version: `v${getVersion(DEPENDENCIES['@swisspost/internet-header'])}`,
+  },
+  {
+    name: 'Intranet-Header',
+    docsStoryId: metaIntranetHeader.id,
+    type: PackageType.Angular,
+    link: {
+      github: {
+        href: 'https://github.com/swisspost/design-system/tree/main/packages/intranet-header-workspace/projects/intranet-header',
+        ariaLabel: 'Source of Intranet-Header package',
+      },
+      docs: {
+        href: generateDocsRelativeLink(metaIntranetHeader.id),
+        ariaLabel: 'Getting started with Intranet-Header package',
+      },
+    },
+    img: {
+      src: '/assets/images/packages/intranet-header.svg',
+      alt: '',
+    },
+    version: `v${getVersion(DEPENDENCIES['@swisspost/design-system-intranet-header'])}`,
+  },
+  {
+    name: 'Icons',
+    docsStoryId: metaIcons.id,
+    type: PackageType.Assets,
+    link: {
+      github: {
+        href: 'https://github.com/swisspost/design-system/tree/main/packages/icons',
+        ariaLabel: 'Source of Icons package',
+      },
+      docs: {
+        href: generateDocsRelativeLink(metaIcons.id),
+        ariaLabel: 'Getting started with Icons package',
+      },
+    },
+    img: {
+      src: '/assets/images/packages/icons.svg',
+      alt: '',
+    },
+    version: `v${getVersion(DEPENDENCIES['@swisspost/design-system-icons'])}`,
+  },
+];
+
+function generateDocsRelativeLink(storyId: string) {
+  return `/?path=/docs/${storyId}--docs`;
+}

packages/documentation/src/shared/tile/tile.component.scss

@@ -0,0 +1,100 @@
+@use 'sass:map';
+@use '@swisspost/design-system-styles/core.scss' as post;
+@use '@swisspost/design-system-styles/mixins/utilities';
+
+$tile-size: var(--post-docs-tile-size, 120px);
+$tile-rg-size: var(--post-docs-tile-rg-size, calc($tile-size / 1.2));
+
+:host{
+  .tile {
+    display: flex;
+    flex-direction: column;
+    width: $tile-size;
+    height: $tile-size;
+    background-color: post.$white;
+    border-radius: post.$size-regular;
+    box-shadow: 0 2px 5px 0 rgba(post.$aubergine-dark, 0.3);
+    text-decoration: none;
+    text-align: center;
+
+    @include utilities.high-contrast-mode() {
+      border: 2px solid transparent;
+    }
+
+    .tile--title {
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      flex: 0 0 auto;
+      padding: 0 post.$size-micro;
+      height: calc(#{post.$size-mini * 2} + 2.2em);
+      background-color: post.$yellow;
+      border-top-left-radius: inherit;
+      border-top-right-radius: inherit;
+      font-size: max(12px, calc($tile-size * 0.1));
+      font-weight: post.$font-weight-bold;
+      color: post.$black;
+      z-index: 1;
+      line-height: 1.1;
+      box-shadow: 0 2px 0 1px rgba(post.$yellow, 0.5);
+
+      ~ .tile--icon {
+        img {
+          max-height: 50px;
+        }
+      }
+    }
+
+    .tile--icon {
+      flex: 0 1 100%;
+      display: flex;
+      flex-direction: column;
+      justify-content: center;
+      align-items: center;
+      gap: post.$size-micro;
+      border-bottom-left-radius: inherit;
+      border-bottom-right-radius: inherit;
+
+      ::slotted(img) {
+        height: 0;
+        min-height: min(100%, calc($tile-size * 0.4));
+      }
+
+      ::slotted(span) {
+        font-size: 0.6875em;
+        color: post.$gray-600;
+      }
+    }
+
+    &[href] {
+      transition: transform 150ms ease-out;
+
+      &:hover {
+        transform: scale(1.1);
+      }
+    }
+
+    @include post.media-breakpoint-down(rg) {
+      width: $tile-rg-size;
+      height: $tile-rg-size;
+
+      .tile--title {
+        height: calc(#{post.$size-mini * 1.5} + 2.2em);
+
+        ~ .tile--icon {
+          ::slotted(img) {
+            min-height: calc($tile-size * 0.3);
+          }
+        }
+      }
+
+      .tile--icon {
+        ::slotted(img) {
+          min-height: calc($tile-size * 0.4);
+        }
+      }
+    }
+  }
+}
+
+

packages/documentation/src/shared/tile/tile.component.ts

@@ -0,0 +1,31 @@
+import { css, LitElement, nothing, unsafeCSS } from 'lit';
+import { html, unsafeStatic } from 'lit/static-html.js';
+import { customElement, property } from 'lit/decorators.js';
+import { spread } from '@open-wc/lit-helpers';
+import Styles from './tile.component.scss?inline';
+
+@customElement('ti-le')
+export class TileComponent extends LitElement {
+  @property({ type: String }) title: string = '';
+  @property({ type: String }) ariaLabel: string | null = null;
+  @property({ type: String }) href: string | null = null;
+
+  static get styles() {
+    return css`
+      ${unsafeCSS(Styles)}
+    `;
+  }
+
+  render() {
+    const isLink = this.href !== null;
+    const tag = isLink ? 'a' : 'div';
+    const attributes = isLink ? { href: this.href, target: '_blank' } : {};
+
+    return html` <${unsafeStatic(tag)} class="tile" ${spread(attributes)} aria-label="${
+      this.ariaLabel ?? nothing
+    }">
+      ${this.title ? html`<span class="tile--title">${this.title}</span>` : nothing}
+      <span class="tile--icon"><slot></slot></span>
+    </${unsafeStatic(tag)}>`;
+  }
+}