From c69d6c7dacfdab0a80bb0647fa203da714ee30ad Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Sat, 20 Jul 2024 00:10:57 +0200
Subject: [PATCH] Add documentation for the Gap utility class

---
 packages/css/src/components/gap/README.md | 13 ++++++-
 packages/css/src/components/gap/gap.scss  |  6 ++-
 storybook/src/utils/Gap/Gap.docs.mdx      | 13 +++++++
 storybook/src/utils/Gap/Gap.stories.tsx   | 46 +++++++++++++++++++++++
 4 files changed, 75 insertions(+), 3 deletions(-)
 create mode 100644 storybook/src/utils/Gap/Gap.docs.mdx
 create mode 100644 storybook/src/utils/Gap/Gap.stories.tsx

diff --git a/packages/css/src/components/gap/README.md b/packages/css/src/components/gap/README.md
index 8c3ca5cd5c..7a500c7786 100644
--- a/packages/css/src/components/gap/README.md
+++ b/packages/css/src/components/gap/README.md
@@ -2,4 +2,15 @@
 
 # Gap
 
-Use these utility classes to add consistent white space between a set of elements.
+Adds white space between a set of elements.
+
+The five sizes of [Component Space](/docs/foundation-design-tokens-space--docs) are available for the length of the gap.
+
+## Guidelines
+
+- Use this utility class to vertically separate the children of a parent element from each other.
+- It can be used on any element and sets the `gap` CSS property.
+  It also makes the element a grid container; the gap would be ignored otherwise.
+  These declarations are marked with the `!important` flag to ensure they override any other gaps and display modes.
+- To add a gap between 2 siblings, the first one can be given a [Margin Bottom](/docs/utilities-css-margin--docs) instead.
+  This may be preferable because it doesn’t change the parent’s display mode.
diff --git a/packages/css/src/components/gap/gap.scss b/packages/css/src/components/gap/gap.scss
index fa3da29bb6..b5e2b5ee2a 100644
--- a/packages/css/src/components/gap/gap.scss
+++ b/packages/css/src/components/gap/gap.scss
@@ -10,7 +10,9 @@
 }
 
 @each $size in map-keys($ams-sizes) {
-  .ams-gap--#{$size} {
-    gap: var(--ams-gap-#{$size}) !important;
+  @if $size != "no" {
+    .ams-gap--#{$size} {
+      grid-gap: var(--ams-gap-#{$size}) !important;
+    }
   }
 }
diff --git a/storybook/src/utils/Gap/Gap.docs.mdx b/storybook/src/utils/Gap/Gap.docs.mdx
new file mode 100644
index 0000000000..770d444af0
--- /dev/null
+++ b/storybook/src/utils/Gap/Gap.docs.mdx
@@ -0,0 +1,13 @@
+{/* @license CC0-1.0 */}
+
+import { Controls, Markdown, Meta, Primary } from "@storybook/blocks";
+import * as GapStories from "./Gap.stories.tsx";
+import README from "../../../../packages/css/src/components/gap/README.md?raw";
+
+<Meta of={GapStories} />
+
+<Markdown>{README}</Markdown>
+
+<Primary />
+
+<Controls />
diff --git a/storybook/src/utils/Gap/Gap.stories.tsx b/storybook/src/utils/Gap/Gap.stories.tsx
new file mode 100644
index 0000000000..979155b658
--- /dev/null
+++ b/storybook/src/utils/Gap/Gap.stories.tsx
@@ -0,0 +1,46 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import { Meta, StoryObj } from '@storybook/react'
+import type { HTMLAttributes } from 'react'
+
+type GapProps = {
+  length: (typeof lengthOptions)[number]
+} & HTMLAttributes<HTMLElement>
+
+const lengthOptions = ['xs', 'sm', 'md', 'lg', 'xl'] as const
+
+const Gap = ({ children, length }: GapProps) => <span className={`ams-gap--${length}`}>{children}</span>
+
+const render = ({ length }: GapProps) => (
+  <div className={`ams-gap--${length}`}>
+    <p className="ams-paragraph">These paragraphs are separated by a gap.</p>
+    <p className="ams-paragraph">These paragraphs are separated by a gap.</p>
+    <p className="ams-paragraph">These paragraphs are separated by a gap.</p>
+  </div>
+)
+
+const meta = {
+  title: 'Utilities/CSS/Gap',
+  component: Gap,
+  args: {
+    length: 'xs',
+  },
+  argTypes: {
+    length: {
+      control: 'radio',
+      description: 'The amount of white space to add between the children.',
+      options: ['xs', 'sm', 'md', 'lg', 'xl'],
+    },
+  },
+} satisfies Meta<typeof Gap>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render,
+}