@pnx-mixtape/mxds 0.0.22 → 0.0.24

package/src/Atom/Blockquote/_blockquote.css

@@ -1,7 +1,6 @@
 @layer design-system.defaults {
   blockquote {
     padding-inline-start: var(--line-gap, var(--gap));
-    border-inline-start: var(--line-width, 6px) solid
-      var(--line-colour, var(--colour-border));
+    border-inline-start: var(--line-width, 6px) solid var(--line-colour, var(--colour-border));
   }
 }

package/src/Atom/Button/Button.stories.ts

@@ -2,15 +2,13 @@ import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./button.twig"
 import Icon from "../Icon/icon.twig"
 import "./button.css"
-import {
-  Button as ButtonType,
-  ButtonModifiers,
-  ButtonTypes,
-} from "@pnx-mixtape/ids-shape"
+import { Button as ButtonType, ButtonModifiers, ButtonTypes } from "@pnx-mixtape/ids-shape"
 import { Icons } from "../../enums"
 
+/**
+ * A button atom with optional icon.
+ */
 const meta: Meta<ButtonType> = {
-  title: "Atom/Button",
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
@@ -18,40 +16,124 @@ const meta: Meta<ButtonType> = {
     as: ButtonTypes.BUTTON,
   },
   argTypes: {
+    title: {
+      description: "The button label",
+      type: {
+        name: "string",
+        required: true,
+      },
+    },
+    as: {
+      description: "Choose the type of button, or use a link instead.",
+      options: Object.values(ButtonTypes),
+      control: "select",
+      table: {
+        defaultValue: { summary: ButtonTypes.BUTTON },
+        type: { summary: "enum" },
+      },
+    },
+    href: {
+      description: "When using a Link, set the `href` value.",
+      type: "string",
+      if: { arg: "as", eq: ButtonTypes.LINK },
+    },
     modifiers: {
+      description:
+        "Define the style of the button. **outline** and **full-width** can be used with the other colour options.",
       options: Object.values(ButtonModifiers),
       control: "multi-select",
+      table: {
+        type: { summary: "enum" },
+      },
+    },
+    disabled: {
+      description: "Add the `[disabled]` attribute to the button.",
+      type: "boolean",
+      table: { defaultValue: { summary: "false" } },
+      if: { arg: "as", neq: ButtonTypes.LINK },
+    },
+    iconStart: {
+      description:
+        "An [Icon](/?path=/docs/atom-icon--docs) object, to display **before** the title.",
+      table: {
+        subcategory: "Icon",
+      },
+    },
+    iconEnd: {
+      description:
+        "An [Icon](/?path=/docs/atom-icon--docs) object, to display **after** the title.",
+      table: {
+        subcategory: "Icon",
+      },
+    },
+    iconOnly: {
+      description:
+        "When an icon is added, visually hide the button text so that only the icon is displayed.",
+      control: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+        subcategory: "Icon",
+      },
     },
-    as: { options: Object.values(ButtonTypes), control: "select" },
-    title: { control: "text" },
-    href: { control: "text" },
-    disabled: { control: "boolean" },
-    // @ts-expect-error The controls follow the shape
-    "iconStart.icon": { options: Object.values(Icons), control: "select" },
-    "iconEnd.icon": { options: Object.values(Icons), control: "select" },
-    iconOnly: { control: "boolean" },
   },
 }
 
 export default meta
 type Story = StoryObj<ButtonType>
 
-export const Button: Story = {
-  args: {},
-}
+export const Button: Story = {}
 
-export const Primary: Story = {
+/**
+ * Primary style uses the **dark** modifier.
+ */
+export const Dark: Story = {
   args: {
     modifiers: [ButtonModifiers.DARK],
   },
 }
 
-export const Text: Story = {
+/**
+ * Outline can be combined with the **dark** or **destructive** modifier.
+ */
+export const Outline: Story = {
+  args: {
+    modifiers: [ButtonModifiers.DARK, ButtonModifiers.OUTLINE],
+  },
+}
+
+/**
+ * Buttons can look more like hyperlinks by using the **light** modifier.
+ */
+export const Light: Story = {
   args: {
     modifiers: [ButtonModifiers.LIGHT],
   },
 }
 
+/**
+ * Destructive style should be reserved for cancel or delete buttons.
+ */
+export const Destructive: Story = {
+  args: {
+    modifiers: [ButtonModifiers.DESTRUCTIVE],
+  },
+}
+
+/**
+ * White style is useful when on a dark background or overlaying an image.
+ */
+export const White: Story = {
+  args: {
+    modifiers: [ButtonModifiers.WHITE],
+  },
+  globals: {
+    background: "mx-background--alt",
+  },
+}
+
+/**
+ * Button's can be a hyperlink element, though this usage should be limited (or combined with the **light** modifier).
+ */
 export const Link: Story = {
   args: {
     as: ButtonTypes.LINK,
@@ -59,10 +141,36 @@ export const Link: Story = {
   },
 }
 
-export const IconButton: Story = {
+/**
+ * Icons can be added after the button text.
+ */
+export const IconEnd: Story = {
   args: {
     iconEnd: Icon({
       icon: Icons.ARROW_RIGHT,
     }),
   },
 }
+
+/**
+ * Icons can be added before the button text.
+ */
+export const IconStart: Story = {
+  args: {
+    iconStart: Icon({
+      icon: Icons.ARROW_LEFT,
+    }),
+  },
+}
+
+/**
+ * Or the icon can visually hide the button text.
+ */
+export const IconOnly: Story = {
+  args: {
+    iconStart: Icon({
+      icon: Icons.SEARCH,
+    }),
+    iconOnly: true,
+  },
+}

package/src/Atom/Button/__snapshots__/Button.stories.ts.snap

@@ -1,8 +1,8 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Atom/Button Button smoke-test 1`] = `
 <div class="mx-page default">
-  <button class="mx-button "
+  <button class="mx-button"
           type="button"
   >
     <span>
@@ -12,15 +12,79 @@ exports[`Atom/Button Button smoke-test 1`] = `
 </div>
 `;
 
-exports[`Atom/Button IconButton smoke-test 1`] = `
+exports[`Atom/Button Dark smoke-test 1`] = `
 <div class="mx-page default">
-  <button class="mx-button "
+  <button class="mx-button mx-button--dark"
           type="button"
   >
     <span>
       Button
     </span>
-    <span class="mx-icon mx-icon--arrow-right ">
+  </button>
+</div>
+`;
+
+exports[`Atom/Button Destructive smoke-test 1`] = `
+<div class="mx-page default">
+  <button class="mx-button mx-button--destructive"
+          type="button"
+  >
+    <span>
+      Button
+    </span>
+  </button>
+</div>
+`;
+
+exports[`Atom/Button IconEnd smoke-test 1`] = `
+<div class="mx-page default">
+  <button class="mx-button"
+          type="button"
+  >
+    <span>
+      Button
+    </span>
+    <span class="mx-icon mx-icon--arrow-right">
+    </span>
+  </button>
+</div>
+`;
+
+exports[`Atom/Button IconOnly smoke-test 1`] = `
+<div class="mx-page default">
+  <button class="mx-button mx-button--icon-only"
+          type="button"
+  >
+    <span class="mx-icon mx-icon--search">
+    </span>
+    <span class="sr-only">
+      Button
+    </span>
+  </button>
+</div>
+`;
+
+exports[`Atom/Button IconStart smoke-test 1`] = `
+<div class="mx-page default">
+  <button class="mx-button"
+          type="button"
+  >
+    <span class="mx-icon mx-icon--arrow-left">
+    </span>
+    <span>
+      Button
+    </span>
+  </button>
+</div>
+`;
+
+exports[`Atom/Button Light smoke-test 1`] = `
+<div class="mx-page default">
+  <button class="mx-button mx-button--light"
+          type="button"
+  >
+    <span>
+      Button
     </span>
   </button>
 </div>
@@ -28,7 +92,7 @@ exports[`Atom/Button IconButton smoke-test 1`] = `
 
 exports[`Atom/Button Link smoke-test 1`] = `
 <div class="mx-page default">
-  <a class="mx-button "
+  <a class="mx-button"
      href="#"
   >
     <span>
@@ -38,9 +102,9 @@ exports[`Atom/Button Link smoke-test 1`] = `
 </div>
 `;
 
-exports[`Atom/Button Primary smoke-test 1`] = `
+exports[`Atom/Button Outline smoke-test 1`] = `
 <div class="mx-page default">
-  <button class="mx-button  mx-button--dark"
+  <button class="mx-button mx-button--dark mx-button--outline"
           type="button"
   >
     <span>
@@ -50,9 +114,9 @@ exports[`Atom/Button Primary smoke-test 1`] = `
 </div>
 `;
 
-exports[`Atom/Button Text smoke-test 1`] = `
-<div class="mx-page default">
-  <button class="mx-button  mx-button--light"
+exports[`Atom/Button White smoke-test 1`] = `
+<div class="mx-page mx-background--alt">
+  <button class="mx-button mx-button--white"
           type="button"
   >
     <span>

package/src/Atom/Button/__snapshots__/Button.stories.tsx.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Atom/Button Button smoke-test 1`] = `
 <button class="mx-button"

package/src/Atom/Button/_buttons-styles.css

@@ -4,19 +4,21 @@
 
 @layer design-system.atoms {
   .mx-button--dark {
-    --line-colour: var(--colour-link);
-    --background: var(--colour-link);
-    --foreground: var(--colour-foreground-reverse);
+    --line-colour: var(--button-dark-bg, var(--colour-link));
+    --background: var(--button-dark-bg, var(--colour-link));
+    --foreground: var(--button-dark-fg, var(--colour-foreground-reverse));
 
     &.mx-button--outline {
       --background: transparent;
-      --foreground: var(--colour-primary);
+      --foreground: var(--button-dark-bg, var(--colour-link));
     }
   }
 
   .mx-button--light {
-    border: transparent;
-    color: var(--link-colour, var(--colour-link));
+    --line-colour: var(--button-light-bg, transparent);
+    --background: var(--button-light-bg, transparent);
+    --foreground: var(--button-light-fg, var(--link-colour, var(--colour-link)));
+
     text-decoration-line: underline;
 
     &:hover {
@@ -24,6 +26,16 @@
     }
   }
 
+  .mx-button--accent {
+    --line-colour: var(--button-light-bg, var(--colour-accent));
+    --background: var(--button-light-bg, var(--colour-accent));
+
+    &.mx-button--outline {
+      --background: transparent;
+      --foreground: var(--button-light-bg, var(--colour-accent));
+    }
+  }
+
   .mx-button--destructive {
     --line-colour: var(--colour-error);
     --background: var(--colour-error);

package/src/Atom/Button/_buttons.css

@@ -13,8 +13,7 @@
     font-weight: var(--font-weight-bold);
     font-family: var(--font-family);
     line-height: var(--line-height-ui);
-    border: var(--line-width, 2px) solid
-      var(--line-colour, var(--colour-border));
+    border: var(--line-width, 2px) solid var(--line-colour, currentcolor);
     border-radius: var(--radius, var(--border-radius-l));
     padding-block: var(--vertical-padding, var(--spacing-xxs));
     padding-inline: var(--horizontal-padding, var(--spacing-m));
@@ -49,9 +48,7 @@
     --horizontal-padding: var(--spacing-s);
   }
 
-  .mx-icon.mx-button--icon-only {
-    --icon-size: 100%;
-
+  .mx-button--icon-only {
     inline-size: var(--spacing-xl);
     block-size: var(--spacing-xl);
     padding: 0;
@@ -61,6 +58,8 @@
 
     &::before,
     &::after {
+      --icon-size: 100%;
+
       mask-size: var(--spacing-s);
     }
 

package/src/Atom/DefinitionList/DefinitionList.stories.ts

@@ -2,7 +2,12 @@ import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./definition-list.twig"
 import "../_base.css"
 import { DefinitionList as DefinitionListType } from "@pnx-mixtape/ids-shape"
+import { Icons } from "../../enums"
 
+/**
+ * The definition list is useful for categorising short pieces of content.
+ * It uses `subgrid` to maintain alignment.
+ */
 const meta: Meta<DefinitionListType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
@@ -22,11 +27,23 @@ const meta: Meta<DefinitionListType> = {
       },
     ],
   },
+  argTypes: {
+    items: {
+      description:
+        "A list of title/content objects to use, where title is the `<dt>` value and content is the `<dd>` value.",
+      type: {
+        name: "other",
+        required: true,
+        value: "array",
+      },
+      table: {
+        type: { summary: "{ title: string, content: string }[]" },
+      },
+    },
+  },
 }
 
 export default meta
 type Story = StoryObj<DefinitionListType>
 
-export const DefinitionList: Story = {
-  args: {},
-}
+export const DefinitionList: Story = {}

package/src/Atom/DefinitionList/DefinitionList.stories.tsx

@@ -7,15 +7,9 @@ const meta: Meta<typeof Component> = {
   args: {
     children: (
       <>
-        <DefinitionListItem title="Item #1">
-          Data for item #1
-        </DefinitionListItem>
-        <DefinitionListItem title="Item #2">
-          Data for item #2
-        </DefinitionListItem>
-        <DefinitionListItem title="Item #3">
-          Data for item #3
-        </DefinitionListItem>
+        <DefinitionListItem title="Item #1">Data for item #1</DefinitionListItem>
+        <DefinitionListItem title="Item #2">Data for item #2</DefinitionListItem>
+        <DefinitionListItem title="Item #3">Data for item #3</DefinitionListItem>
       </>
     ),
   },

package/src/Atom/DefinitionList/DefinitionList.tsx

@@ -2,10 +2,9 @@ import { JSX, ComponentPropsWithoutRef, PropsWithChildren } from "react"
 
 type DefinitionListProps = ComponentPropsWithoutRef<"dl"> & PropsWithChildren
 
-const DefinitionList = ({
-  children,
-  ...props
-}: DefinitionListProps): JSX.Element => <dl {...props}>{children}</dl>
+const DefinitionList = ({ children, ...props }: DefinitionListProps): JSX.Element => (
+  <dl {...props}>{children}</dl>
+)
 
 type DefinitionListItemProps = ComponentPropsWithoutRef<"div"> &
   PropsWithChildren & {

package/src/Atom/DefinitionList/__snapshots__/DefinitionList.stories.ts.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Atom/DefinitionList DefinitionList smoke-test 1`] = `
 <div class="mx-page default">

package/src/Atom/DefinitionList/__snapshots__/DefinitionList.stories.tsx.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Atom/Definition List DefinitionList smoke-test 1`] = `
 <dl>

package/src/Atom/Heading/Heading.stories.ts

@@ -1,28 +1,70 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./heading.twig"
 import "../_base.css"
-import { HeadingTypes } from "@pnx-mixtape/ids-shape"
+import { Heading as HeadingType, HeadingTypes } from "@pnx-mixtape/ids-shape"
 
-const meta: Meta<typeof Component> = {
+/**
+ * Heading element should always follow correct html heading order. The modifier class can be used to visually change the size when needed.
+ */
+const meta: Meta<HeadingType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
+    as: HeadingTypes.TWO,
     title: "Heading",
   },
   argTypes: {
-    as: { options: Object.values(HeadingTypes), control: "select" },
+    as: {
+      description: "The semantic heading level.",
+      options: Object.values(HeadingTypes),
+      control: "select",
+      table: {
+        defaultValue: { summary: HeadingTypes.TWO },
+        type: { summary: "enum" },
+      },
+    },
     modifiers: {
+      description: "The visual heading size (only one applies)",
       // @todo add mixtapes heading modifiers.
       options: Object.values(HeadingTypes),
       control: "multi-select",
+      table: {
+        type: { summary: "enum" },
+      },
+    },
+    title: {
+      description: "The heading text",
+      type: "string",
+    },
+    excluded: {
+      description:
+        "Mark the heading as 'excluded' to remove it from certain javascript contexts (like [InPageNavigation](/?path=/docs/component-inpagenavigation--docs))",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    srOnly: {
+      description:
+        "Mark the heading as visually hidden so that it's only available for screen reader context.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
     },
-    title: { control: "text" },
-    excluded: { control: "boolean" },
-    srOnly: { control: "boolean" },
   },
 }
 
 export default meta
-type Story = StoryObj<typeof meta>
+type Story = StoryObj<HeadingType>
 
 export const Headings: Story = {}
+
+/**
+ * The modifier class can be used to visually change the size when needed.
+ */
+export const Resized: Story = {
+  args: {
+    modifiers: [HeadingTypes.FOUR],
+  },
+}

package/src/Atom/Heading/Heading.tsx

@@ -30,12 +30,7 @@ const Heading = ({
   }, [anchor, ref])
 
   return (
-    <Tag
-      className={classNames(modifier, className)}
-      id={anchor}
-      ref={ref}
-      {...props}
-    >
+    <Tag className={classNames(modifier, className)} id={anchor} ref={ref} {...props}>
       {children}
     </Tag>
   )

package/src/Atom/Heading/__snapshots__/Heading.stories.ts.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Atom/Heading Headings smoke-test 1`] = `
 <div class="mx-page default">
@@ -7,3 +7,11 @@ exports[`Atom/Heading Headings smoke-test 1`] = `
   </h2>
 </div>
 `;
+
+exports[`Atom/Heading Resized smoke-test 1`] = `
+<div class="mx-page default">
+  <h2 class="mx-heading--m">
+    Heading
+  </h2>
+</div>
+`;

package/src/Atom/Heading/__snapshots__/Heading.stories.tsx.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Atom/Typography/Heading Heading smoke-test 1`] = `
 <h2 class

package/src/Atom/Heading/_headings.css

@@ -36,8 +36,7 @@
       .mx-heading--s
     ) {
       --font-min: calc(
-        var(--heading-font-size) - var(--heading-font-size) *
-          var(--font-size-diff, 0.3)
+        var(--heading-font-size) - var(--heading-font-size) * var(--font-size-diff, 0.3)
       );
 
       font-size: clamp(

package/src/Atom/Icon/Icon.mdx

@@ -13,7 +13,7 @@ import { Icons } from "../../enums"
 
 # Icon set
 
-Icons are available as a css image mask.
+SVG icon classes are available (as a css image mask).
 
 <IconGallery>
   {Object.values(Icons).map(name => (
@@ -23,8 +23,12 @@ Icons are available as a css image mask.
   ))}
 </IconGallery>
 
+---
+
 # Icon
 
+An icon atom that is used by other components.
+
 <Primary />
 
 <Controls />