feat: Add Column component and Gap and Margin utilities for vertical …

…spacing (#1083)

Co-authored-by: Aram <[email protected]>

packages/css/CHANGELOG.md

@@ -68,7 +68,7 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 * Adjust size of breadcrumb separator and allow natural text wrapping ([#913](https://github.com/Amsterdam/design-system/issues/913)) ([caba940](https://github.com/Amsterdam/design-system/commit/caba94024c5aedf9092a5afbbf625d921fd124b5))
 * Improve examples and documentation for cards ([#936](https://github.com/Amsterdam/design-system/issues/936)) ([0f91370](https://github.com/Amsterdam/design-system/commit/0f913702de12cb7b9ca50e8f9da4899c3d934320))
 * Merge grid cell files into grid files and directories ([#815](https://github.com/Amsterdam/design-system/issues/815)) ([f4b4ec5](https://github.com/Amsterdam/design-system/commit/f4b4ec5de92d283ee2ef083075297a64b3dfd1cb))
-* Resolve malformed outline and remove excessive whitespace on dialog ([#937](https://github.com/Amsterdam/design-system/issues/937)) ([1fc264a](https://github.com/Amsterdam/design-system/commit/1fc264ac577edaa92e37d4c7e81427dd75b6dbe7))
+* Resolve malformed outline and remove excessive white space on dialog ([#937](https://github.com/Amsterdam/design-system/issues/937)) ([1fc264a](https://github.com/Amsterdam/design-system/commit/1fc264ac577edaa92e37d4c7e81427dd75b6dbe7))
 * Use rems for checkbox underline ([#944](https://github.com/Amsterdam/design-system/issues/944)) ([8622326](https://github.com/Amsterdam/design-system/commit/8622326b8686856c44ad03856bac886ee4e5632b))
 
 ## [0.2.0](https://github.com/Amsterdam/design-system/compare/@amsterdam/[email protected]...@amsterdam/[email protected]) (2023-12-01)
@@ -81,7 +81,7 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 * Add common link tokens and use them in all link-like components ([#814](https://github.com/Amsterdam/design-system/issues/814)) ([9b5bd55](https://github.com/Amsterdam/design-system/commit/9b5bd55d0b118f246b828e023b75be1e84f98af4))
 * Allow end-alignment on page menu ([#835](https://github.com/Amsterdam/design-system/issues/835)) ([035ca08](https://github.com/Amsterdam/design-system/commit/035ca08842ee8ad955b260fb26693fe739801df4))
-* Allow small and large vertical whitespace on grids ([#821](https://github.com/Amsterdam/design-system/issues/821)) ([aa54eb9](https://github.com/Amsterdam/design-system/commit/aa54eb911bfed633856a74e0be4e11d4ad8f3ebc))
+* Allow small and large vertical white space on grids ([#821](https://github.com/Amsterdam/design-system/issues/821)) ([aa54eb9](https://github.com/Amsterdam/design-system/commit/aa54eb911bfed633856a74e0be4e11d4ad8f3ebc))
 * Update typography system and values, implement compact theme ([#803](https://github.com/Amsterdam/design-system/issues/803)) ([9b087ec](https://github.com/Amsterdam/design-system/commit/9b087ec5c6e75dfafadcdcde710747ef63951917))
 
 ## [0.1.9](https://github.com/Amsterdam/design-system/compare/@amsterdam/[email protected]...@amsterdam/[email protected]) (2023-11-27)

packages/css/src/common/size.scss

@@ -0,0 +1,13 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright (c) 2024 Gemeente Amsterdam
+ */
+
+/** The set of available options for sizing. */
+$amsterdam-sizes: (
+  "xs": "extra-small",
+  "sm": "small",
+  "md": "medium",
+  "lg": "large",
+  "xl": "extra-large",
+);

packages/css/src/components/alert/README.md

@@ -15,8 +15,8 @@ There are four types of notifications:
 
 - Place an orange Alert directly below the Header for important and urgent information.
   Examples: system outage or changes in the opening hours of a City Office.
-- Ensure sufficient whitespace around the Alert.
-  The grid’s whitespace is a good reference – place the Alert in its own cell.
+- Ensure sufficient white space around the Alert.
+  The grid’s white space is a good reference – place the Alert in its own cell.
 - By default, the Alert cannot be closed.
   This functionality can be added optionally.
 - Optionally, the title can be omitted.

packages/css/src/components/column/README.md

@@ -0,0 +1,3 @@
+# Column
+
+Stacks its children vertically and adds a vertical gap between them.

packages/css/src/components/column/column.scss

@@ -0,0 +1,16 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright (c) 2024 Gemeente Amsterdam
+ */
+
+@import "../../common/size";
+
+.amsterdam-column {
+  display: grid;
+}
+
+@each $size, $label in $amsterdam-sizes {
+  .amsterdam-column--#{$label} {
+    gap: var(--amsterdam-column-gap-#{$size});
+  }
+}

packages/css/src/components/gap/README.md

@@ -0,0 +1,3 @@
+# Gap
+
+Use these utility classes to add consistent white space between a set of elements.

packages/css/src/components/gap/gap.scss

@@ -0,0 +1,16 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright (c) 2024 Gemeente Amsterdam
+ */
+
+@import "../../common/size";
+
+[class|="amsterdam-gap-"] {
+  display: grid !important;
+}
+
+@each $size in map-keys($amsterdam-sizes) {
+  .amsterdam-gap--#{$size} {
+    gap: var(--amsterdam-gap-#{$size}) !important;
+  }
+}

packages/css/src/components/image/image.scss

@@ -15,6 +15,6 @@
 }
 
 // [1] Allow for fluid image sizing while maintaining aspect ratio governed by width/height attributes
-// [2] Remove ‘phantom’ whitespace
+// [2] Remove ‘phantom’ white space
 // [3] Italicise alt text to visually offset it from surrounding copy
 // Source: https://x.com/csswizardry/status/1717841334462005661

packages/css/src/components/index.scss

@@ -4,6 +4,9 @@
  */
 
 /* Append here */
+@import "./column/column";
+@import "./margin/margin";
+@import "./gap/gap";
 @import "./fieldset/fieldset";
 @import "./link-list/link-list";
 @import "./badge/badge";

packages/css/src/components/margin/README.md

@@ -0,0 +1,3 @@
+# Margin
+
+Use these utility classes to add white space below a single element.

packages/css/src/components/margin/margin.scss

@@ -0,0 +1,12 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright (c) 2024 Gemeente Amsterdam
+ */
+
+@import "../../common/size";
+
+@each $size in map-keys($amsterdam-sizes) {
+  .amsterdam-mb--#{$size} {
+    margin-block-end: var(--amsterdam-margin-#{$size}) !important;
+  }
+}

packages/css/src/components/ordered-list/ordered-list.scss

@@ -3,7 +3,7 @@
  * Copyright (c) 2023 Gemeente Amsterdam
  */
 
-/** Apply border box sizing, reset whitespace and list styles. */
+/** Apply border box sizing, reset white space and list styles. */
 @mixin reset {
   box-sizing: border-box;
   list-style-type: none;

packages/css/src/components/unordered-list/unordered-list.scss

@@ -3,7 +3,7 @@
  * Copyright (c) 2023 Gemeente Amsterdam
  */
 
-/** Apply border box sizing, reset whitespace and list styles. */
+/** Apply border box sizing, reset white space and list styles. */
 @mixin reset {
   box-sizing: border-box;
   list-style: none;

packages/react/CHANGELOG.md

@@ -81,7 +81,7 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 * Add common link tokens and use them in all link-like components ([#814](https://github.com/Amsterdam/design-system/issues/814)) ([9b5bd55](https://github.com/Amsterdam/design-system/commit/9b5bd55d0b118f246b828e023b75be1e84f98af4))
 * Allow end-alignment on page menu ([#835](https://github.com/Amsterdam/design-system/issues/835)) ([035ca08](https://github.com/Amsterdam/design-system/commit/035ca08842ee8ad955b260fb26693fe739801df4))
-* Allow small and large vertical whitespace on grids ([#821](https://github.com/Amsterdam/design-system/issues/821)) ([aa54eb9](https://github.com/Amsterdam/design-system/commit/aa54eb911bfed633856a74e0be4e11d4ad8f3ebc))
+* Allow small and large vertical white space on grids ([#821](https://github.com/Amsterdam/design-system/issues/821)) ([aa54eb9](https://github.com/Amsterdam/design-system/commit/aa54eb911bfed633856a74e0be4e11d4ad8f3ebc))
 * Update typography system and values, implement compact theme ([#803](https://github.com/Amsterdam/design-system/issues/803)) ([9b087ec](https://github.com/Amsterdam/design-system/commit/9b087ec5c6e75dfafadcdcde710747ef63951917))
 
 ### Bug Fixes

packages/react/src/Column/Column.test.tsx

@@ -0,0 +1,67 @@
+import { render, screen } from '@testing-library/react'
+import { createRef } from 'react'
+import { Column, columnGapSizes } from './Column'
+import '@testing-library/jest-dom'
+
+describe('Column', () => {
+  it('renders', () => {
+    const { container } = render(<Column />)
+
+    const component = container.querySelector(':only-child')
+
+    expect(component).toBeInTheDocument()
+    expect(component).toBeVisible()
+  })
+
+  it('renders a design system BEM class name', () => {
+    const { container } = render(<Column />)
+
+    const component = container.querySelector(':only-child')
+
+    expect(component).toHaveClass('amsterdam-column--medium')
+  })
+
+  columnGapSizes.map((size) =>
+    it('renders with ${size} gap', () => {
+      const { container } = render(<Column gap={size} />)
+
+      const component = container.querySelector(':only-child')
+
+      expect(component).toHaveClass(`amsterdam-column--${size}`)
+    }),
+  )
+
+  it('renders an additional class name', () => {
+    const { container } = render(<Column className="extra" />)
+
+    const component = container.querySelector(':only-child')
+
+    expect(component).toHaveClass('amsterdam-column--medium extra')
+  })
+
+  it('renders with an article tag', () => {
+    render(<Column as="article" />)
+
+    const component = screen.getByRole('article')
+
+    expect(component).toBeInTheDocument()
+  })
+
+  it('renders with a section tag', () => {
+    const { container } = render(<Column as="section" />)
+
+    const component = container.querySelector('section')
+
+    expect(component).toBeInTheDocument()
+  })
+
+  it('supports ForwardRef in React', () => {
+    const ref = createRef<HTMLDivElement>()
+
+    const { container } = render(<Column ref={ref} />)
+
+    const component = container.querySelector(':only-child')
+
+    expect(ref.current).toBe(component)
+  })
+})

packages/react/src/Column/Column.tsx

@@ -0,0 +1,33 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright (c) 2024 Gemeente Amsterdam
+ */
+
+import clsx from 'clsx'
+import { forwardRef } from 'react'
+import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
+
+export const columnGapSizes: Array<string> = ['extra-small', 'small', 'medium', 'large', 'extra-large']
+
+type ColumnTag = 'article' | 'div' | 'section'
+type ColumnGap = (typeof columnGapSizes)[number]
+
+export type ColumnProps = {
+  /** The element to render the column with. */
+  as?: ColumnTag
+  /** The amount of vertical space between the column’s children. */
+  gap?: ColumnGap
+} & PropsWithChildren<HTMLAttributes<HTMLDivElement>>
+
+export const Column = forwardRef(
+  (
+    { as: Tag = 'div', children, className, gap = 'medium', ...restProps }: ColumnProps,
+    ref: ForwardedRef<HTMLDivElement>,
+  ) => (
+    <Tag {...restProps} ref={ref} className={clsx('amsterdam-column', `amsterdam-column--${gap}`, className)}>
+      {children}
+    </Tag>
+  ),
+)
+
+Column.displayName = 'Column'

packages/react/src/Column/README.md

@@ -0,0 +1,3 @@
+# React Column component
+
+[Column documentation](../../../css/src/components/column/README.md)

packages/react/src/Column/index.ts

@@ -0,0 +1,2 @@
+export { Column } from './Column'
+export type { ColumnProps } from './Column'

packages/react/src/Grid/Grid.test.tsx

@@ -24,7 +24,7 @@ describe('Grid', () => {
     expect(component).toHaveClass('amsterdam-grid')
   })
 
-  it('renders a medium vertical spacing class name', () => {
+  it('renders a medium vertical padding class name', () => {
     const { container } = render(<Grid paddingVertical="medium" />)
     const component = container.querySelector(':only-child')
     expect(component).toHaveClass('amsterdam-grid--padding-vertical--medium')

packages/react/src/Grid/Grid.tsx

@@ -21,20 +21,20 @@ type GridPaddingSize = 'small' | 'medium' | 'large'
 type GridPaddingVerticalProp = {
   paddingBottom?: never
   paddingTop?: never
-  /** The amount of vertical whitespace above and below the grid. */
+  /** The amount of vertical white space above and below the grid. */
   paddingVertical?: GridPaddingSize
 }
 
 type GridPaddingTopAndBottomProps = {
-  /** The amount of vertical whitespace below the grid. */
+  /** The amount of vertical white space below the grid. */
   paddingBottom?: GridPaddingSize
-  /** The amount of vertical whitespace above the grid. */
+  /** The amount of vertical white space above the grid. */
   paddingTop?: GridPaddingSize
   paddingVertical?: never
 }
 
 export type GridProps = {
-  /** The amount of vertical whitespace between rows of the grid. */
+  /** The amount of vertical white space between rows of the grid. */
   gapVertical?: 'none' | 'small' | 'large'
 } & (GridPaddingVerticalProp | GridPaddingTopAndBottomProps) &
   PropsWithChildren<HTMLAttributes<HTMLDivElement>>

packages/react/src/index.ts

@@ -4,6 +4,7 @@
  */
 
 /* Append here */
+export * from './Column'
 export * from './Fieldset'
 export * from './LinkList'
 export * from './Badge'

plop-templates/react.tsx.hbs

@@ -7,7 +7,7 @@ import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 
-export interface {{pascalCase name}}Props extends PropsWithChildren<HTMLAttributes<HTMLElement>> {}
+export type {{pascalCase name}}Props = PropsWithChildren<HTMLAttributes<HTMLElement>>
 
 export const {{pascalCase name}} = forwardRef(
   ({ children, className, ...restProps }: {{pascalCase name}}Props, ref: ForwardedRef<HTMLElement>) => (

proprietary/tokens/src/brand/amsterdam/space.compact.tokens.json

@@ -0,0 +1,11 @@
+{
+  "amsterdam": {
+    "space": {
+      "xs": { "value": "clamp(0.25rem, calc(0.390625vw - 0.015625rem), 0.625rem)" },
+      "sm": { "value": "clamp(0.5rem, calc(0.78125vw - 0.03125rem), 1.25rem)" },
+      "md": { "value": "clamp(1rem, calc(1.5625vw - 0.0625rem), 2.5rem)" },
+      "lg": { "value": "clamp(1.5rem, calc(2.34375vw - 0.09375rem), 3.75rem)" },
+      "xl": { "value": "clamp(2rem, calc(3.125vw - 0.125rem), 5rem)" }
+    }
+  }
+}

proprietary/tokens/src/brand/amsterdam/space.tokens.json

@@ -0,0 +1,11 @@
+{
+  "amsterdam": {
+    "space": {
+      "xs": { "value": "clamp(0.25rem, calc(0.78125vw + 0.09375rem), 0.875rem)" },
+      "sm": { "value": "clamp(0.5rem, calc(1.5625vw + 0.1875rem), 1.75rem)" },
+      "md": { "value": "clamp(1rem, calc(3.125vw + 0.375rem), 3.5rem)" },
+      "lg": { "value": "clamp(1.5rem, calc(4.6875vw + 0.5625rem), 5.25rem)" },
+      "xl": { "value": "clamp(2rem, calc(6.25vw + 0.75rem), 7rem)" }
+    }
+  }
+}

proprietary/tokens/src/components/amsterdam/column.tokens.json

@@ -0,0 +1,13 @@
+{
+  "amsterdam": {
+    "column": {
+      "gap": {
+        "xs": { "value": "{amsterdam.space.xs}" },
+        "sm": { "value": "{amsterdam.space.sm}" },
+        "md": { "value": "{amsterdam.space.md}" },
+        "lg": { "value": "{amsterdam.space.lg}" },
+        "xl": { "value": "{amsterdam.space.xl}" }
+      }
+    }
+  }
+}

proprietary/tokens/src/components/amsterdam/gap.tokens.json

@@ -0,0 +1,11 @@
+{
+  "amsterdam": {
+    "gap": {
+      "xs": { "value": "{amsterdam.space.xs}" },
+      "sm": { "value": "{amsterdam.space.sm}" },
+      "md": { "value": "{amsterdam.space.md}" },
+      "lg": { "value": "{amsterdam.space.lg}" },
+      "xl": { "value": "{amsterdam.space.xl}" }
+    }
+  }
+}

proprietary/tokens/src/components/amsterdam/margin.tokens.json

@@ -0,0 +1,11 @@
+{
+  "amsterdam": {
+    "margin": {
+      "xs": { "value": "{amsterdam.space.xs}" },
+      "sm": { "value": "{amsterdam.space.sm}" },
+      "md": { "value": "{amsterdam.space.md}" },
+      "lg": { "value": "{amsterdam.space.lg}" },
+      "xl": { "value": "{amsterdam.space.xl}" }
+    }
+  }
+}

proprietary/tokens/src/components/amsterdam/mark.tokens.json

@@ -1,7 +1,7 @@
 {
   "amsterdam": {
     "mark": {
-      "background-color": { "value": "var(--amsterdam-color-yellow)" }
+      "background-color": { "value": "{amsterdam.color.yellow}" }
     }
   }
 }