@pnx-mixtape/mxds 0.0.21 → 0.0.23

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.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, var(--colour-border));
     border-radius: var(--radius, var(--border-radius-l));
     padding-block: var(--vertical-padding, var(--spacing-xxs));
     padding-inline: var(--horizontal-padding, var(--spacing-m));
@@ -57,9 +56,10 @@
     overflow: hidden;
     flex-wrap: wrap;
 
-    &::before {
-      inline-size: 100%;
-      block-size: 100%;
+    &::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 />

package/src/Atom/Icon/Icon.stories.ts

@@ -19,14 +19,60 @@ const meta: Meta<IconArgs> = {
   component: Component,
   args: {
     icon: Icons.ARROW_RIGHT,
+    size: IconSizeModifier.SMALL,
   },
   argTypes: {
-    icon: { options: Object.values(Icons), control: "select" },
-    align: { options: Object.values(AlignmentTypes), control: "select" },
-    color: { options: Object.values(IconColourModifier), control: "select" },
-    rotate: { options: Object.values(IconRotateModifier), control: "select" },
-    size: { options: Object.values(IconSizeModifier), control: "select" },
-    text: { control: "text" },
+    icon: {
+      description: "The name of the icon to use",
+      options: Object.values(Icons),
+      control: "select",
+      type: {
+        name: "string",
+        required: true,
+      },
+      table: {
+        type: { summary: "enum" },
+      },
+    },
+    color: {
+      description: "Icons can be coloured.",
+      options: Object.values(IconColourModifier),
+      control: "select",
+      table: {
+        type: { summary: "enum" },
+      },
+    },
+    size: {
+      description: "Optionally adjust the size of the icon.",
+      options: Object.values(IconSizeModifier),
+      control: "radio",
+      table: {
+        defaultValue: { summary: IconSizeModifier.SMALL },
+        type: { summary: "enum" },
+      },
+    },
+    rotate: {
+      description: "Optionally rotate an icon.",
+      options: Object.values(IconRotateModifier),
+      control: "radio",
+      table: {
+        type: { summary: "enum" },
+      },
+    },
+    text: {
+      description: "Text can be placed next to an icon.",
+      type: "string",
+    },
+    align: {
+      description: "When used with text, you can align to the start or end of it.",
+      options: Object.values(AlignmentTypes),
+      control: "radio",
+      table: {
+        defaultValue: { summary: AlignmentTypes.START },
+        type: { summary: "enum" },
+      },
+      if: { arg: "text" },
+    },
   },
 }
 
@@ -35,12 +81,36 @@ type Story = StoryObj<IconArgs>
 
 export const Icon: Story = {}
 
+/**
+ * Icons by default inherit the current text colour, but they can be explicitly coloured.
+ */
+export const Primary: Story = {
+  args: {
+    color: IconColourModifier.BRAND,
+  },
+}
+
+/**
+ * Icons can be sized.
+ */
+export const Large: Story = {
+  args: {
+    size: IconSizeModifier.XLARGE,
+  },
+}
+
+/**
+ * Add some text to the icon.
+ */
 export const WithText: Story = {
   args: {
     text: "Message with icon",
   },
 }
 
+/**
+ * Align the text to the end instead of the start.
+ */
 export const Alignment: Story = {
   args: {
     text: "Message with icon",

package/src/Atom/Icon/Icon.tsx

@@ -7,14 +7,7 @@ export type IconProps = IconType & {
   icon: Icons
 }
 
-const Icon = ({
-  icon,
-  color,
-  text,
-  align,
-  rotate,
-  size,
-}: IconProps): JSX.Element => (
+const Icon = ({ icon, color, text, align, rotate, size }: IconProps): JSX.Element => (
   <span
     className={classNames("mx-icon", `mx-icon--${icon}`, {
       [`mx-icon--color-${color}`]: color,

package/src/Atom/Icon/__snapshots__/Icon.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/Icon Alignment smoke-test 1`] = `
 <div class="mx-page default">
-  <span class="mx-icon mx-icon--arrow-left mx-icon--end ">
+  <span class="mx-icon mx-icon--arrow-left mx-icon--end mx-icon--size-sm">
     Message with icon
   </span>
 </div>
@@ -10,14 +10,28 @@ exports[`Atom/Icon Alignment smoke-test 1`] = `
 
 exports[`Atom/Icon Icon smoke-test 1`] = `
 <div class="mx-page default">
-  <span class="mx-icon mx-icon--arrow-right ">
+  <span class="mx-icon mx-icon--arrow-right mx-icon--size-sm">
+  </span>
+</div>
+`;
+
+exports[`Atom/Icon Large smoke-test 1`] = `
+<div class="mx-page default">
+  <span class="mx-icon mx-icon--arrow-right mx-icon--size-xl">
+  </span>
+</div>
+`;
+
+exports[`Atom/Icon Primary smoke-test 1`] = `
+<div class="mx-page default">
+  <span class="mx-icon mx-icon--arrow-right mx-icon--color-brand mx-icon--size-sm">
   </span>
 </div>
 `;
 
 exports[`Atom/Icon WithText smoke-test 1`] = `
 <div class="mx-page default">
-  <span class="mx-icon mx-icon--arrow-right ">
+  <span class="mx-icon mx-icon--arrow-right mx-icon--size-sm">
     Message with icon
   </span>
 </div>

package/src/Atom/Icon/__snapshots__/Icon.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/Icon Alignment smoke-test 1`] = `
 <span class="mx-icon mx-icon--arrow-left mx-icon--end">

package/src/Atom/Icon/_icon.css

@@ -5,7 +5,7 @@
  */
 
 @layer design-system.atoms {
-  .mx-icon {
+  :where(.mx-icon) {
     display: inline-flex;
     align-items: center;
     gap: var(--spacing-xxs);

package/src/Atom/Image/Image.stories.ts

@@ -3,6 +3,9 @@ import Component from "./image.twig"
 import "../_base.css"
 import { Image as ImageType } from "@pnx-mixtape/ids-shape"
 
+/**
+ * A simple image atom.
+ */
 const meta: Meta<ImageType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
@@ -15,6 +18,4 @@ const meta: Meta<ImageType> = {
 export default meta
 type Story = StoryObj<ImageType>
 
-export const Image: Story = {
-  args: {},
-}
+export const Image: Story = {}

package/src/Atom/Image/__snapshots__/Image.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/Image Image smoke-test 1`] = `
 <div class="mx-page default">

package/src/Atom/Link/Link.stories.ts

@@ -5,6 +5,9 @@ import "../_base.css"
 import { Link as LinkType } from "@pnx-mixtape/ids-shape"
 import { Icons } from "../../enums"
 
+/**
+ * A link atom, with optional icon.
+ */
 const meta: Meta<LinkType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
@@ -13,13 +16,65 @@ const meta: Meta<LinkType> = {
     title: "Hyperlink",
   },
   argTypes: {
-    more: { control: "boolean" },
-    external: { control: "boolean" },
-    download: { control: "boolean" },
-    current: { 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" },
+    href: {
+      description: "The links URL value.",
+    },
+    title: {
+      description: "The links text.",
+    },
+    current: {
+      description: 'Adds the `aria-current="page"` attribute.',
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    more: {
+      description: "A bolder link, usually combined with the **arrow-right** icon.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+        subcategory: "Special variants",
+      },
+    },
+    external: {
+      description: "Adds the **external-link** icon and screen reader text.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+        subcategory: "Special variants",
+      },
+    },
+    download: {
+      description: "Usually combined with the **download** icon.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+        subcategory: "Special variants",
+      },
+    },
+    iconStart: {
+      description:
+        "An [Icon](/?path=/docs/atom-icon--docs) object, to display **before** the text.",
+      table: {
+        subcategory: "Icon",
+      },
+    },
+    iconEnd: {
+      description: "An [Icon](/?path=/docs/atom-icon--docs) object, to display **after** the text.",
+      table: {
+        subcategory: "Icon",
+      },
+    },
+    iconOnly: {
+      description:
+        "When an icon is added, visually hide the link text so that only the icon is displayed.",
+      control: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+        subcategory: "Icon",
+      },
+    },
   },
 }
 
@@ -28,6 +83,9 @@ type Story = StoryObj<LinkType>
 
 export const Link: Story = {}
 
+/**
+ * More links are bolder and have a slight hover animation on their icon.
+ */
 export const More: Story = {
   args: {
     more: true,
@@ -37,12 +95,18 @@ export const More: Story = {
   },
 }
 
+/**
+ * External links add screen reader text "(opens in a new window)" to reflect their icon.
+ */
 export const External: Story = {
   args: {
     external: true,
   },
 }
 
+/**
+ * Download links have a slight hover animation on their icon.
+ */
 export const Download: Story = {
   args: {
     download: true,
@@ -53,6 +117,9 @@ export const Download: Story = {
   },
 }
 
+/**
+ * Any [Icon](/?path=/docs/atom-icon--docs) from the set can be used on links.
+ */
 export const IconLink: Story = {
   args: {
     iconStart: Icon({

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

@@ -1,11 +1,11 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Atom/Link Download smoke-test 1`] = `
 <div class="mx-page default">
   <a class="mx-link--download"
      href="#"
   >
-    <span class="mx-icon mx-icon--download ">
+    <span class="mx-icon mx-icon--download">
     </span>
     <span>
       Download (PDF 12kb)
@@ -32,7 +32,7 @@ exports[`Atom/Link External smoke-test 1`] = `
 exports[`Atom/Link IconLink smoke-test 1`] = `
 <div class="mx-page default">
   <a href="#">
-    <span class="mx-icon mx-icon--link ">
+    <span class="mx-icon mx-icon--link">
     </span>
     <span>
       Hyperlink
@@ -59,7 +59,7 @@ exports[`Atom/Link More smoke-test 1`] = `
     <span>
       Hyperlink
     </span>
-    <span class="mx-icon mx-icon--arrow-right ">
+    <span class="mx-icon mx-icon--arrow-right">
     </span>
   </a>
 </div>

package/src/Atom/Link/__snapshots__/Link.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/Link External smoke-test 1`] = `
 <a href="http://example.com"