feat(documentation): adds container stories (#2030)

Co-authored-by: Alizé Debray <[email protected]>
Co-authored-by: oliverschuerch <[email protected]>

.changeset/tricky-tables-warn.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': minor
+---
+
+Added a documentation page for the `.container` and `.container-fluid` classes.

packages/documentation/.storybook/preview.ts

@@ -28,7 +28,7 @@ const preview: Preview = {
             'Typography',
             'Color',
             'Layout',
-            ['Breakpoints', 'Grid', 'Column', 'TODOS'],
+            ['Breakpoints', 'Containers', 'Grid', 'TODOS'],
             'Elevation',
             'Accessibility',
           ],

packages/documentation/src/stories/foundation/layout/breakpoints/breakpoints-between.sample.scss

@@ -1,3 +1,5 @@
+@use '@swisspost/design-system-styles/core' as post;
+
 @include post.media-breakpoint-between(sm, lg) {
   .custom-class {
     display: block;

packages/documentation/src/stories/foundation/layout/breakpoints/breakpoints-max-width.sample.scss

@@ -1,3 +1,5 @@
+@use '@swisspost/design-system-styles/core' as post;
+
 // No media query necessary for xs breakpoint as it's effectively @media (max-width: 0) { ... }
 @include post.media-breakpoint-down(lg) {
   .custom-class {

packages/documentation/src/stories/foundation/layout/breakpoints/breakpoints-min-width.sample.scss

@@ -1,3 +1,5 @@
+@use '@swisspost/design-system-styles/core' as post;
+
 // No media query necessary for xs breakpoint as it's effectively @media (min-width: 0) { ... }
 .custom-class {
   display: none;

packages/documentation/src/stories/foundation/layout/breakpoints/breakpoints-single.sample.scss

@@ -1,3 +1,5 @@
+@use '@swisspost/design-system-styles/core' as post;
+
 @include post.media-breakpoint-only(xs) {
   .custom-class {
     display: block;

packages/documentation/src/stories/foundation/layout/breakpoints/breakpoints.blocks.tsx

@@ -1,33 +1,36 @@
 import { forEach } from '../../../../utils/react';
 import { parse } from '../../../../utils/sass-export';
+import { SpecTable } from '../shared.blocks';
 import scss from './breakpoints.module.scss';
 
 export const SCSS_VARIABLES = parse(scss);
 
 export const BreakpointTable = () => (
-  <div className="table-responsive">
-    <table className="table">
-      <thead>
-        <tr>
-          <th></th>
-          <th>Class infix</th>
-          <th>Dimensions</th>
-        </tr>
-      </thead>
-      <tbody>
-        {forEach(
-          SCSS_VARIABLES.breakpoint,
-          (data: { key: number; value: { name: string; infix: any; dimensions: string } }) => {
-            return (
-              <tr>
-                <th>{data.value.name}</th>
-                <td dangerouslySetInnerHTML={{ __html: data.value.infix }}></td>
-                <td>{data.value.dimensions}</td>
-              </tr>
-            );
-          },
-        )}
-      </tbody>
-    </table>
-  </div>
+  <SpecTable>
+    <tr>
+      <th>Name</th>
+      {forEach(SCSS_VARIABLES.breakpoint, (data: { key: string; value: { name: string } }) => (
+        <td key={data.key}>
+          <small>{data.value.name}</small>
+        </td>
+      ))}
+    </tr>
+
+    <tr>
+      <th>Code name</th>
+      {forEach(SCSS_VARIABLES.breakpoint, (data: { key: string }) => (
+        <td key={data.key}>
+          <code>{data.key}</code>
+        </td>
+      ))}
+    </tr>
+    <tr>
+      <th>Class infix</th>
+      {forEach(SCSS_VARIABLES.breakpoint, (data: { key: string; value: { infix: string } }) => (
+        <td key={data.key}>
+          {data.value.infix === 'none' ? 'none' : <code>-{data.value.infix}-</code>}
+        </td>
+      ))}
+    </tr>
+  </SpecTable>
 );

packages/documentation/src/stories/foundation/layout/breakpoints/breakpoints.docs.mdx

@@ -1,7 +1,7 @@
 import { Meta, Source } from '@storybook/blocks';
+import { formatAsMap } from '../../../../utils/sass-export';
 import { BreakpointTable, SCSS_VARIABLES } from './breakpoints.blocks';
 import * as BreakpointStories from './breakpoints.stories';
-import SampleAvailable from './breakpoints-available.sample.scss?raw';
 import SampleMinWidth from './breakpoints-min-width.sample.scss?raw';
 import SampleMaxWidth from './breakpoints-max-width.sample.scss?raw';
 import SampleSingle from './breakpoints-single.sample.scss?raw';
@@ -24,18 +24,25 @@ breakpoints, sometimes referred to as grid tiers, for building responsively. The
 
 <BreakpointTable />
 
-You’ll find these breakpoints in a Sass map in our styles core.
+## CSS
+
+When using our source Sass files, you have the option of using Sass variables to change the breakpoints (not recommended).
+
+### Sass variables
 
 <Source
-  code={SampleAvailable}
   language="scss"
-/>
+  dark
+  code={Object.entries(SCSS_VARIABLES.variables)
+    .map(([key, value]) => `$${key}: ${formatAsMap(value)};`)
+    .join('\n')}
+></Source>
 
-## Mixins
+### Sass mixins
 
 There are several mixins available to use in your own Sass to help with building responsive layouts.
 
-### Min-width
+#### Min-width
 
 We primarily use the following media query ranges—or breakpoints—in our source Sass files for our layout, grid system, and components.
 
@@ -44,7 +51,7 @@ We primarily use the following media query ranges—or breakpoints—in our sour
   language="scss"
 />
 
-### Max-width
+#### Max-width
 
 We occasionally use media queries that go in the other direction.
 
@@ -53,7 +60,7 @@ We occasionally use media queries that go in the other direction.
   language="scss"
 />
 
-### Single breakpoint
+#### Single breakpoint
 
 There are also media queries and mixins for targeting a single segment of screen sizes using the minimum and maximum breakpoint widths.
 
@@ -62,7 +69,7 @@ There are also media queries and mixins for targeting a single segment of screen
   language="scss"
 />
 
-### Between breakpoints
+#### Between breakpoints
 
 Similarly, media queries may span multiple breakpoint widths.
 

packages/documentation/src/stories/foundation/layout/breakpoints/breakpoints.module.scss

@@ -1,24 +1,11 @@
-@use 'sass:list';
-@use 'sass:map';
 @use '@swisspost/design-system-styles/core' as post;
-@use '../layout.shared' as shared;
+@use '../shared.module' as shared;
 
 :export {
-  @each $breakpoint, $value in post.$grid-breakpoints {
-    $i: list.index(post.$grid-breakpoints, $breakpoint $value);
-    $name: map.get(shared.$breakpointNames, $breakpoint) or $breakpoint;
-
-    breakpoint_#{$breakpoint}_name: $name;
+  // Variables used in the spec table (some variables used on the page are defined in the shared module)
 
-    @if $i == 1 {
-      $keys: map.keys(post.$grid-breakpoints);
-      $nextValue: map.get(post.$grid-breakpoints, list.nth($keys, $i + 1));
-
-      breakpoint_#{$breakpoint}_infix: none;
-      breakpoint_#{$breakpoint}_dimensions: #{'<' + $nextValue};
-    } @else {
-      breakpoint_#{$breakpoint}_infix: #{'<code>' + $breakpoint + '</code>'};
-      breakpoint_#{$breakpoint}_dimensions: #{'≥' + $value};
-    }
+  // Variables to expose under sass variables section
+  @each $breakpoint, $value in post.$grid-breakpoints {
+    variables_grid-breakpoints_#{$breakpoint}: $value;
   }
 }

packages/documentation/src/stories/foundation/layout/containers/containers.blocks.tsx

@@ -0,0 +1,42 @@
+import { parse } from '../../../../utils/sass-export';
+import { forEach } from '../../../../utils/react';
+import { SpecTable } from '../shared.blocks';
+import scss from './containers.module.scss';
+
+export const SCSS_VARIABLES = parse(scss);
+
+export const ContainersTable = () => (
+  <SpecTable>
+    <tr>
+      <th>
+        Container <code>max-width</code>
+      </th>
+      {forEach(
+        SCSS_VARIABLES.container,
+        (data: { key: string; value: { ['max-width']: string } }) => (
+          <td key={data.key}>{data.value['max-width']}</td>
+        ),
+      )}
+    </tr>
+    <tr>
+      <th>
+        Container <code>padding</code>
+      </th>
+      {forEach(SCSS_VARIABLES.container, (data: { key: string; value: { padding: string } }) => (
+        <td key={data.key}>{data.value.padding}</td>
+      ))}
+    </tr>
+
+    <tr>
+      <th>
+        Container-Fluid <code>padding</code>
+      </th>
+      {forEach(
+        SCSS_VARIABLES.container,
+        (data: { key: string; value: { fluid: { padding: string } } }) => (
+          <td key={data.key}>{data.value.fluid.padding}</td>
+        ),
+      )}
+    </tr>
+  </SpecTable>
+);

packages/documentation/src/stories/foundation/layout/containers/containers.docs.mdx

@@ -0,0 +1,47 @@
+import { Meta, Source } from '@storybook/blocks';
+import { formatAsMap } from '../../../../utils/sass-export';
+import { ContainersTable, SCSS_VARIABLES } from './containers.blocks';
+import * as ContainerStories from './containers.stories';
+
+<Meta of={ContainerStories} />
+
+# Containers
+
+<p className="lead">Containers are a fundamental building block of our Design-System that contain, pad, and align your content within a given device or viewport. They are required, when using our grid-system. While containers can be nested, most layouts do not require a nested container.</p>
+
+We can distinguish between two different container types:
+
+- <code>.container</code>, which defines a <code>max-width</code> on some breakpoints.
+- <code>.container-fluid</code>, which is <code>width: 100%</code> at all breakpoints.
+
+<ContainersTable />
+
+## Default container
+
+Our default `.container` class is a responsive, fixed-width container.
+
+<Source code={`<div class="container">
+  <!-- Content here -->
+</div>`} language="scss"/>
+
+## Fluid containers
+
+Use `.container-fluid` for a full width container, spanning the entire width of the viewport on every breakpoint.
+
+<Source code={`<div class="container-fluid">
+  <!-- Content here -->
+</div>`} language="scss"/>
+
+## CSS
+
+When using our source Sass files, you have the option of using Sass variables for customization (not recommended).
+
+### Sass variables
+
+<Source
+  language="scss"
+  dark
+  code={Object.entries(SCSS_VARIABLES.variables)
+    .map(([key, value]) => `$${key}: ${formatAsMap(value)};`)
+    .join('\n')}
+></Source>

packages/documentation/src/stories/foundation/layout/containers/containers.module.scss

@@ -0,0 +1,30 @@
+@use 'sass:map';
+@use '@swisspost/design-system-styles/core' as post;
+@use '../shared.module' as shared;
+
+:export {
+  // Variables used in the spec table (some variables used on the page are defined in the shared module)
+  @each $breakpoint, $value in post.$grid-breakpoints {
+    container_#{$breakpoint}_max-width: map.get(post.$container-max-widths, $breakpoint) or none;
+    container_#{$breakpoint}_padding: map.get(post.$grid-container-padding, $breakpoint);
+    container_#{$breakpoint}_fluid_padding: map.get(
+      post.$grid-container-fluid-padding,
+      $breakpoint
+    );
+  }
+
+  // Variables to expose under sass variables section
+  @each $breakpoint, $value in post.$grid-breakpoints {
+    variables_container-max-widths_#{$breakpoint}: map.get(post.$container-max-widths, $breakpoint);
+    variables_grid-container-padding_#{$breakpoint}: map.get(
+        post.$grid-container-padding,
+        $breakpoint
+      ) or
+      none;
+    variables_grid-container-fluid-padding_#{$breakpoint}: map.get(
+        post.$grid-container-fluid-padding,
+        $breakpoint
+      ) or
+      none;
+  }
+}

packages/documentation/src/stories/foundation/layout/containers/containers.stories.ts

@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { BADGE } from '../../../../../.storybook/constants';
+
+const meta: Meta = {
+  title: 'Foundations/Layout/Containers',
+  parameters: {
+    badges: [BADGE.NEEDS_REVISION],
+  },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Default: Story = {};

packages/documentation/src/stories/foundation/layout/grid/grid-scss-mixins.sample.scss

@@ -1,12 +1,14 @@
+@use '@swisspost/design-system-styles/core' as post;
+
 // Creates a wrapper for a series of columns
-@include make-row();
+@include post.make-row();
 
 // Make the column element grid-ready (applying everything but the width)
-@include make-col-ready();
+@include post.make-col-ready();
 
 // Without optional size values, the mixin will create equal columns (similar to using .col)
-@include make-col();
-@include make-col($size, $columns: $grid-columns);
+@include post.make-col();
+@include post.make-col($size, $columns: post.$grid-columns);
 
 // Offset with margins
-@include make-col-offset($size, $columns: $grid-columns);
+@include post.make-col-offset($size, $columns: post.$grid-columns);