feat(documentation): add docs page on how to use columns

.changeset/gorgeous-clouds-trade.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': minor
+---
+
+Added docs page on how to use columns.

packages/documentation/src/stories/foundation/layout/Columns/columns.docs.mdx

@@ -0,0 +1,87 @@
+import { Meta, Canvas, Source, Controls } from '@storybook/blocks';
+import * as ColumnStories from './columns.stories';
+import './columns.styles.scss';
+
+<Meta of={ColumnStories} />
+
+# Columns
+
+{/* prettier-ignore */}
+<ul>
+<li><b>Columns build on the grid’s flexbox architecture which is based on [Bootstrap](https://getbootstrap.com/docs/4.0/layout/grid/).</b> Flexbox means we have options for changing individual columns and modifying groups of columns at the row level. You choose how columns grow, shrink, or otherwise change.</li>
+<li><b>When building grid layouts, all content goes in columns.</b> The hierarchy of our grid goes from container to row to column to your content.</li>
+</ul>
+
+### Alignment
+
+Use flexbox alignment utilities to vertically and horizontally align columns.
+
+#### Vertical alignment
+
+Change the vertical alignment with any of the responsive <code>align-items-\*</code> classes.
+
+Or, change the alignment of each column individually with any of the responsive <code>align-self-\*</code> classes.
+
+<Canvas sourceState="shown" of={ColumnStories.VerticalExample} />
+<div className="hide-col-default">
+  <Controls of={ColumnStories.VerticalExample} />
+</div>
+
+#### Horizontal alignment
+
+Change the horizontal alignment with any of the responsive <code>justify-content-\*</code> classes.
+
+<Canvas of={ColumnStories.HorizontalExample} />
+<div className="hide-col-default">
+  <Controls of={ColumnStories.HorizontalExample} />
+</div>
+
+#### Column wrapping
+
+If more than 12 columns are placed within a single row, each group of extra columns will, as one unit, wrap onto a new line.
+
+<Canvas of={ColumnStories.ColumnWrapping} />
+<div className="hide-col-default">
+  <Controls of={ColumnStories.ColumnWrapping} />
+</div>
+
+#### Column breaks
+
+Breaking columns to a new line in flexbox requires a small hack: add an element with <code>width: 100%</code> wherever you want to wrap your columns to a new line. Normally this is accomplished with multiple <code>.rows</code>, but not every implementation method can account for this.
+
+<Canvas of={ColumnStories.ColumnBreakExample} />
+<div className="hide-col-default">
+  <Controls of={ColumnStories.ColumnBreakExample} />
+</div>
+
+### Reorderning
+
+#### Order classes
+
+Use <code>.order-</code> classes for controlling the visual order of your content. These classes are responsive, so you can set the order by breakpoint (e.g. <code>.order-1</code><code>.order-md-2</code>). Includes support for 1 through 5 across all seven grid tiers. If you need more <code>.order-\*</code> classes.
+
+<Canvas of={ColumnStories.OrderExample} />
+<div className="hide-col-default">
+  <Controls of={ColumnStories.OrderExample} />
+</div>
+
+There are also responsive <code>.order-first</code> and <code>.order-last</code> classes that change the order of an element by applying <code>order: -1</code> and <code>order: 6</code>, respectively. These classes can also be intermixed with the numbered <code>.order-\*</code> classes as needed.
+
+<Canvas of={ColumnStories.OrderMaxExample} />
+
+### Offsetting columns
+
+You can offset grid columns in two ways: our responsive <code>.offset-</code> grid classes and our margin utilities. Grid classes are sized to match columns while margins are more useful for quick layouts where the width of the offset is variable.
+
+#### Offset classes
+
+Move columns to the right using <code>.offset-\*</code> classes. These classes increase the left margin of a column by \* columns. For example, <code>.offset-4</code> moves <code>.col-1</code> over four columns. You can also apply the offset above a certain breakpoint with the breakpoint infixes e.g. <code>offset-md-4</code>.
+
+<Canvas of={ColumnStories.OffsetExample} />
+<div className="hide-col-default">
+  <Controls of={ColumnStories.OffsetExample} />
+</div>
+
+In addition to column clearing at responsive breakpoints, you may need to reset offsets.
+
+<Canvas of={ColumnStories.ResetOffsetExample} />

packages/documentation/src/stories/foundation/layout/Columns/columns.stories.ts

@@ -0,0 +1,286 @@
+import type { Args, Meta, StoryFn, StoryObj, StoryContext } from '@storybook/web-components';
+import { BADGE } from '../../../../../.storybook/constants';
+import { html, nothing } from 'lit';
+
+const meta: Meta = {
+  title: 'Foundations/Layout/Columns',
+  parameters: {
+    badges: [BADGE.NEEDS_REVISION],
+  },
+  decorators: [
+    (story: StoryFn, { args, context }: StoryContext) => html`
+      <div class="p-regular column-example text-center">${story(args, context)}</div>
+    `,
+  ],
+  args: {
+    alignItems: 'align-items-start',
+    alignSelf: 'no self alignment',
+    justifyContent: 'justify-content-start',
+    offsetItem: 'offset-1',
+    renderBreakingElement: true,
+    ColumnOneOrder: 'no order',
+    ColumnTwoOrder: 'order-5',
+    ColumnThreeOrder: 'order-1',
+    ColumnWidth: 'col-4',
+  },
+  argTypes: {
+    alignItems: {
+      name: 'Align Items',
+      description: 'Aligns the whole row vertically.',
+      control: {
+        type: 'select',
+      },
+      options: ['align-items-start', 'align-items-center', 'align-items-end'],
+    },
+    alignSelf: {
+      name: 'Align Item 1',
+      description: 'Aligns the Item 1 vertically.',
+      control: {
+        type: 'select',
+      },
+      options: ['no self alignment', 'align-self-start', 'align-self-center', 'align-self-end'],
+    },
+    justifyContent: {
+      name: 'Horizontal Alignement',
+      description: 'Aligns the Items horizontally.',
+      control: {
+        type: 'select',
+      },
+      options: [
+        'justify-content-start',
+        'justify-content-center',
+        'justify-content-end',
+        'justify-content-around',
+        'justify-content-between',
+        'justify-content-evenly',
+      ],
+    },
+    offsetItem: {
+      name: 'Offset classes',
+      description: 'Increases the left margin of a column',
+      control: {
+        type: 'select',
+      },
+      options: [
+        'offset-1',
+        'offset-2',
+        'offset-3',
+        'offset-4',
+        'offset-5',
+        'offset-6',
+        'offset-7',
+        'offset-8',
+        'offset-9',
+        'offset-10',
+        'offset-11',
+      ],
+    },
+    renderBreakingElement: {
+      name: 'Render breaking element',
+      description: 'Toggle rendering of breaking element',
+      control: {
+        type: 'boolean',
+      },
+    },
+    ColumnOneOrder: {
+      name: 'Order first column',
+      description: 'Set order-class for first element',
+      control: {
+        type: 'select',
+      },
+      options: ['no order class', 'order-0', 'order-1', 'order-2', 'order-3', 'order-4', 'order-5'],
+    },
+    ColumnTwoOrder: {
+      name: 'Order second column',
+      description: 'Set order-class for second element',
+      control: {
+        type: 'select',
+      },
+      options: ['no order class', 'order-0', 'order-1', 'order-2', 'order-3', 'order-4', 'order-5'],
+    },
+    ColumnThreeOrder: {
+      name: 'Order third column',
+      description: 'Set order-class for third element',
+      control: {
+        type: 'select',
+      },
+      options: ['no order class', 'order-0', 'order-1', 'order-2', 'order-3', 'order-4', 'order-5'],
+    },
+    ColumnWidth: {
+      name: 'Width of second Column',
+      description: 'Set width for second column to see line breaking',
+      control: {
+        type: 'select',
+      },
+      options: [
+        'col-1',
+        'col-2',
+        'col-3',
+        'col-4',
+        'col-5',
+        'col-6',
+        'col-7',
+        'col-8',
+        'col-9',
+        'col-10',
+        'col-11',
+        'col-12',
+      ],
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+export const VerticalExample: Story = {
+  parameters: {
+    controls: {
+      include: ['Align Items', 'Align Item 1'],
+    },
+  },
+  render: (args: Args) => html`
+    <div class="container">
+      <div class="row-height row ${args.alignItems}">
+        <div class="col${args.alignSelf === 'no self alignment' ? '' : ` ${args.alignSelf}`}">
+          Item 1
+        </div>
+        <div class="col">Item 2</div>
+        <div class="col">Item 3</div>
+      </div>
+    </div>
+  `,
+};
+
+export const HorizontalExample: Story = {
+  parameters: {
+    controls: {
+      include: ['Horizontal Alignement'],
+    },
+  },
+  render: (args: Args) => html`
+    <div class="container">
+      <div class="row ${args.justifyContent}">
+        <div class="col-4">Item 1</div>
+        <div class="col-4">Item 2</div>
+      </div>
+    </div>
+  `,
+};
+
+export const OrderExample: Story = {
+  parameters: {
+    controls: {
+      include: ['Order first column', 'Order second column', 'Order third column'],
+    },
+  },
+  render: (args: Args) => html`
+    <div class="container">
+      <div class="row">
+        <div
+          class="col${args.ColumnOneOrder === 'no order class' ? '' : ` ${args.ColumnOneOrder}`}"
+        >
+          First in DOM
+        </div>
+        <div
+          class="col${args.ColumnTwoOrder === 'no order class' ? '' : ` ${args.ColumnTwoOrder}`}"
+        >
+          Second in DOM
+        </div>
+        <div
+          class="col${args.ColumnThreeOrder === 'no order class'
+            ? ''
+            : ` ${args.ColumnThreeOrder}`}"
+        >
+          Third in DOM
+        </div>
+      </div>
+    </div>
+  `,
+};
+
+export const OrderMaxExample: Story = {
+  render: () => html`
+    <div class="container">
+      <div class="row">
+        <div class="col order-last">First in DOM, ordered last</div>
+        <div class="col">Second in DOM, unordered</div>
+        <div class="col order-first">Third in DOM, ordered first</div>
+      </div>
+    </div>
+  `,
+};
+
+export const OffsetExample: Story = {
+  parameters: {
+    controls: {
+      include: ['Offset classes'],
+    },
+  },
+  render: (args: Args) => html`
+    <div class="row">
+      <div class="col-1 ${args.offsetItem}">.${args.offsetItem}</div>
+    </div>
+  `,
+};
+
+export const ColumnBreakExample: Story = {
+  parameters: {
+    controls: {
+      include: ['Render breaking element'],
+    },
+  },
+  render: (args: Args) => html`
+    <div class="row">
+      <div class="col-3">.col-3</div>
+      <div class="col-3">.col-3</div>
+
+      <!-- Force next columns to break to new line -->
+      ${args.renderBreakingElement
+        ? html`
+            <div class="w-100"></div>
+          `
+        : nothing}
+
+      <div class="col-3">.col-3</div>
+      <div class="col-3">.col-3</div>
+    </div>
+  `,
+};
+
+export const ResetOffsetExample: Story = {
+  decorators: [
+    (story: StoryFn, { args, context }: StoryContext) => html`
+      ${story(args, context)}
+      <p class="mt-regular"><small>Resize the browser window to see changes.</small></p>
+    `,
+  ],
+  render: () => html`
+    <div class="row">
+      <div class="col-sm-5 col-md-6">.col-sm-5 .col-md-6</div>
+      <div class="col-sm-5 offset-sm-2 col-md-6 offset-md-0">
+        .col-sm-5 .offset-sm-2 .col-md-6 .offset-md-0
+      </div>
+    </div>
+  `,
+};
+
+export const ColumnWrapping: Story = {
+  parameters: {
+    controls: {
+      include: ['Width of second Column'],
+    },
+  },
+  render: (args: Args) => html`
+    <div class="row">
+      <div class="col-9">.col-9</div>
+      <div class="${args.ColumnWidth}">${args.ColumnWidth}</div>
+      <div class="col-6">
+        .col-6
+        <br />
+        Subsequent columns continue along the new line.
+      </div>
+    </div>
+  `,
+};