docs(storybook): add Button component

src/stories/components/Button.mdx

@@ -0,0 +1,98 @@
+import { Canvas, Controls, Meta, Source } from "@storybook/blocks";
+import * as ButtonStories from "./Button.stories";
+
+<Meta of={ButtonStories} />
+
+# Button
+
+## Usage notes
+
+Please refer to [GOV.UK Design System documentation on
+buttons](https://design-system.service.gov.uk/components/button/) for more
+information.
+
+## Example
+
+<Canvas of={ButtonStories.Default} />
+<Controls of={ButtonStories.Default} />
+
+## Variants
+
+### Small size
+
+<Canvas of={ButtonStories.Small} />
+
+### Large size
+
+<Canvas of={ButtonStories.Large} />
+
+## Icons
+
+### with left icon
+
+<Canvas of={ButtonStories.WithIcon} />
+
+### with right icon
+
+<Canvas of={ButtonStories.WithIconRight} />
+
+### with icon only
+
+<Canvas of={ButtonStories.WithIconOnly} />
+
+## States
+
+### Disabled
+
+<Canvas of={ButtonStories.Disabled} />
+
+## Button as link
+
+<Canvas of={ButtonStories.Link} />
+
+## Implementation notes
+
+- add `ds-button` as base class to a `button` element
+- combine with one size modifier: `ds-button-small` or `ds-button-large`
+- combine with one appearance modifier: `ds-button-secondary`, `ds-button-tertiary`, `ds-button-ghost`
+
+<Source of={ButtonStories.Large} />
+
+- for full with add `ds-button-full-width`
+
+<Source of={ButtonStories.FullWidth} />
+
+### with icons
+
+- use `svg` for the icon, add `ds-button-icon` class to the icon
+- add `ds-button-with-icon` class to the button
+- wrap text in a `span` with the class `ds-button-label`
+
+<Source of={ButtonStories.WithIcon} />
+
+### with icon only
+
+- add `ds-button-with-icon-only` class
+- wrap (invisible) text in a `span` with class `sr-only`
+- have a look at [Accessible Icon Buttons](https://www.sarasoueidan.com/blog/accessible-icon-buttons/)
+
+<Source of={ButtonStories.WithIconOnly} />
+
+### links that look like buttons
+
+- add `role="button"` to the link
+- have a look at this [discussion on links styled as buttons and a11y implications](https://github.com/alphagov/govuk_elements/pull/272)
+
+<Source of={ButtonStories.Link} />
+
+### "disabled" buttons
+
+- use a `div` as tag and add `is-disabled` class
+
+<Source of={ButtonStories.Disabled} />
+
+## Further documentation
+
+Please check out the code on the given examples and otherwise
+refer to [mdn web docs on \<button\>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button)
+for more technical information.

src/stories/components/Button.stories.ts

@@ -0,0 +1,251 @@
+import type { Meta, StoryObj } from "@storybook/html";
+import { clsx } from "clsx";
+import dedent from "dedent";
+import {
+  htmlAttrs,
+  loremSentences,
+  loremWords,
+} from "../../../.storybook/utils";
+
+type ButtonArgs = {
+  label: string;
+  size?: "default" | "small" | "large";
+  appearance?: "default" | "secondary" | "tertiary" | "ghost";
+  fullWidth?: boolean;
+  withIcon?: boolean;
+  withIconRight?: boolean;
+  withIconOnly?: boolean;
+  disabled?: boolean;
+  isLink?: boolean;
+};
+
+const meta = {
+  title: "Components/Button",
+  render: ({
+    label,
+    size,
+    appearance,
+    fullWidth,
+    withIcon,
+    withIconRight,
+    withIconOnly,
+    disabled,
+    isLink,
+  }) => {
+    const cssClasses = clsx("ds-button", {
+      "ds-button-large": size === "large",
+      "ds-button-small": size === "small",
+      "ds-button-secondary": appearance === "secondary",
+      "ds-button-tertiary": appearance === "tertiary",
+      "ds-button-ghost": appearance === "ghost",
+      "is-disabled": disabled,
+      "ds-button-with-icon": withIcon || withIconRight,
+      "ds-button-with-icon-only": withIconOnly,
+      "ds-button-full-width": fullWidth,
+    });
+    const attrs = htmlAttrs({ className: cssClasses });
+
+    const icon = dedent`
+      <svg class="ds-button-icon" width="36" height="36" viewBox="0 0 36 36" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+        <path d="M28.5 9.615L26.385 7.5L18 15.885L9.615 7.5L7.5 9.615L15.885 18L7.5 26.385L9.615 28.5L18 20.115L26.385 28.5L28.5 26.385L20.115 18L28.5 9.615Z"></path>
+      </svg>
+    `;
+
+    if (disabled) {
+      return dedent`
+        <div ${attrs}>
+          ${label}
+        </div>
+      `;
+    }
+
+    if (isLink) {
+      return dedent`
+        <a href="https://digitalservice.bund.de" target="_blank" role="button" ${attrs}>
+          ${label}
+        </a>
+      `;
+    }
+
+    if (withIcon || withIconRight) {
+      return dedent`
+        <button ${attrs}>
+          ${withIcon ? icon : ""}
+          <span class="ds-button-label">
+            ${label}
+          </span>
+          ${withIconRight ? icon : ""}
+        </button>
+      `;
+    }
+
+    if (withIconOnly) {
+      return dedent`
+        <button ${attrs}>
+          ${icon}
+          <span class="sr-only">
+            ${label}
+          </span>
+        </button>
+      `;
+    }
+
+    return dedent`
+      <button ${attrs}>
+        ${label}
+      </button>
+    `;
+  },
+  argTypes: {
+    disabled: {
+      description: "Is the button not available for interaction?",
+    },
+    label: { control: "text" },
+    withIcon: { control: "boolean" },
+    withIconRight: { control: "boolean" },
+    withIconOnly: { control: "boolean" },
+    size: {
+      options: ["default", "small", "large"],
+      control: { type: "radio" },
+    },
+    appearance: {
+      options: ["default", "secondary", "tertiary", "ghost"],
+      control: { type: "radio" },
+    },
+  },
+  args: {
+    disabled: false,
+    label: loremWords(4),
+    size: "default",
+    appearance: "default",
+    withIcon: false,
+    withIconRight: false,
+    withIconOnly: false,
+  },
+} satisfies Meta<ButtonArgs>;
+
+export default meta;
+
+type Story = StoryObj<ButtonArgs>;
+
+export const Default = {} satisfies Story;
+export const Small = { args: { size: "small" } } satisfies Story;
+export const Large = { args: { size: "large" } } satisfies Story;
+export const Disabled = { args: { disabled: true } } satisfies Story;
+export const Link = { args: { isLink: true } } satisfies Story;
+export const WithIcon = { args: { withIcon: true } } satisfies Story;
+export const WithIconRight = { args: { withIconRight: true } } satisfies Story;
+export const WithIconOnly = { args: { withIconOnly: true } } satisfies Story;
+export const FullWidth = { args: { fullWidth: true } } satisfies Story;
+export const FullWidthWithIcon = {
+  args: { fullWidth: true, withIcon: true },
+} satisfies Story;
+export const LongText = { args: { label: loremSentences(4) } } satisfies Story;
+export const LongTextWithIcon = {
+  args: { label: loremSentences(4), withIcon: true },
+} satisfies Story;
+
+export const Secondary = { args: { appearance: "secondary" } } satisfies Story;
+export const SecondarySmall = {
+  args: { appearance: "secondary", size: "small" },
+} satisfies Story;
+export const SecondaryLarge = {
+  args: { appearance: "secondary", size: "large" },
+} satisfies Story;
+export const SecondaryDisabled = {
+  args: { appearance: "secondary", disabled: true },
+} satisfies Story;
+export const SecondaryLink = {
+  args: { appearance: "secondary", isLink: true },
+} satisfies Story;
+export const SecondaryWithIcon = {
+  args: { appearance: "secondary", withIcon: true },
+} satisfies Story;
+export const SecondaryWithIconRight = {
+  args: { appearance: "secondary", withIconRight: true },
+} satisfies Story;
+export const SecondaryWithIconOnly = {
+  args: { appearance: "secondary", withIconOnly: true },
+} satisfies Story;
+export const SecondaryFullWidth = {
+  args: { appearance: "secondary", fullWidth: true },
+} satisfies Story;
+export const SecondaryFullWidthWithIcon = {
+  args: { appearance: "secondary", fullWidth: true, withIcon: true },
+} satisfies Story;
+export const SecondaryLongText = {
+  args: { appearance: "secondary", label: loremSentences(4) },
+} satisfies Story;
+export const SecondaryLongTextWithIcon = {
+  args: { appearance: "secondary", label: loremSentences(4), withIcon: true },
+} satisfies Story;
+
+export const Tertiary = { args: { appearance: "tertiary" } } satisfies Story;
+export const TertiarySmall = {
+  args: { appearance: "tertiary", size: "small" },
+} satisfies Story;
+export const TertiaryLarge = {
+  args: { appearance: "tertiary", size: "large" },
+} satisfies Story;
+export const TertiaryDisabled = {
+  args: { appearance: "tertiary", disabled: true },
+} satisfies Story;
+export const TertiaryLink = {
+  args: { appearance: "tertiary", isLink: true },
+} satisfies Story;
+export const TertiaryWithIcon = {
+  args: { appearance: "tertiary", withIcon: true },
+} satisfies Story;
+export const TertiaryWithIconRight = {
+  args: { appearance: "tertiary", withIconRight: true },
+} satisfies Story;
+export const TertiaryWithIconOnly = {
+  args: { appearance: "tertiary", withIconOnly: true },
+} satisfies Story;
+export const TertiaryFullWidth = {
+  args: { appearance: "tertiary", fullWidth: true },
+} satisfies Story;
+export const TertiaryFullWidthWithIcon = {
+  args: { appearance: "tertiary", fullWidth: true, withIcon: true },
+} satisfies Story;
+export const TertiaryLongText = {
+  args: { appearance: "tertiary", label: loremSentences(4) },
+} satisfies Story;
+export const TertiaryLongTextWithIcon = {
+  args: { appearance: "tertiary", label: loremSentences(4), withIcon: true },
+} satisfies Story;
+
+export const Ghost = { args: { appearance: "ghost" } } satisfies Story;
+export const GhostSmall = {
+  args: { appearance: "ghost", size: "small" },
+} satisfies Story;
+export const GhostLarge = {
+  args: { appearance: "ghost", size: "large" },
+} satisfies Story;
+export const GhostDisabled = {
+  args: { appearance: "ghost", disabled: true },
+} satisfies Story;
+export const GhostLink = {
+  args: { appearance: "ghost", isLink: true },
+} satisfies Story;
+export const GhostWithIcon = {
+  args: { appearance: "ghost", withIcon: true },
+} satisfies Story;
+export const GhostWithIconRight = {
+  args: { appearance: "ghost", withIconRight: true },
+} satisfies Story;
+export const GhostWithIconOnly = {
+  args: { appearance: "ghost", withIconOnly: true },
+} satisfies Story;
+export const GhostFullWidth = {
+  args: { appearance: "ghost", fullWidth: true },
+} satisfies Story;
+export const GhostFullWidthWithIcon = {
+  args: { appearance: "ghost", fullWidth: true, withIcon: true },
+} satisfies Story;
+export const GhostLongText = {
+  args: { appearance: "ghost", label: loremSentences(4) },
+} satisfies Story;
+export const GhostLongTextWithIcon = {
+  args: { appearance: "ghost", label: loremSentences(4), withIcon: true },
+} satisfies Story;