@pnx-mixtape/mxds 0.0.21 → 0.0.23

package/src/Component/Card/Card.stories.ts

@@ -5,6 +5,7 @@ import {
   Card as CardType,
   HeadingTypes,
   ListItemModifiers,
+  PopoverPlacementModifier,
   TagTypes,
 } from "@pnx-mixtape/ids-shape"
 import { Icons, BackgroundStyles } from "../../enums"
@@ -25,36 +26,117 @@ export type MxCardType = Omit<CardType, "modifiers"> & {
   background?: BackgroundStyles
 }
 
+/**
+ * A card that uses `@container` queries to be horizontal when there's enough space or vertical when not.
+ */
 const meta: Meta<MxCardType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
-    image: Image({
-      src: "https://picsum.photos/id/56/558/418?grayscale",
-      alt: "Blurry bubbles",
-      width: 558,
-      height: 418,
-    }),
     title: Heading({
       title: "Card title",
       as: HeadingTypes.THREE,
     }),
+    content:
+      "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>",
     link: Link({
       href: "#",
       title: "Find out more",
       more: true,
     }),
-    content:
-      "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>",
+    image: Image({
+      src: "https://picsum.photos/id/56/558/418?grayscale",
+      alt: "Blurry bubbles",
+      width: 558,
+      height: 418,
+    }),
   },
   argTypes: {
     modifiers: {
+      description:
+        "The **block** modifier makes the whole card clickable. The **reverse** modifier positions the image on the left.",
       options: Object.values(ListItemModifiers),
-      control: "multi-select",
+      control: "check",
+      table: { type: { summary: "enum" } },
     },
     background: {
+      description: "Apply a background colour to the card.",
       options: Object.values(BackgroundStyles),
       control: "select",
+      table: { type: { summary: "enum" } },
+    },
+    image: {
+      description: "Optional [Image](/?path=/docs/atom-image--docs) component.",
+      control: "text",
+      table: {
+        type: { summary: "Image" },
+        subcategory: "Card content",
+      },
+    },
+    title: {
+      description: "A [Heading](/?path=/docs/atom-heading--docs) component.",
+      control: "text",
+      type: {
+        name: "string",
+        required: true,
+      },
+      table: {
+        type: { summary: "Heading" },
+        subcategory: "Card content",
+      },
+    },
+    content: {
+      description: "Content.",
+      control: "text",
+      type: {
+        name: "string",
+        required: true,
+      },
+      table: {
+        type: { summary: "WysiwygText" },
+        subcategory: "Card content",
+      },
+    },
+    link: {
+      description: "Optional content [Link](/?path=/docs/atom-link--docs).",
+      control: "text",
+      table: {
+        type: { summary: "Link" },
+        subcategory: "Card content",
+      },
+    },
+    date: {
+      description: "Optional date value (unformatted)",
+      type: "string",
+      control: "text",
+      table: {
+        subcategory: "Card content",
+      },
+    },
+    tags: {
+      description: "Optional [Tags](/?path=/docs/component-tags--docs).",
+      control: "text",
+      table: {
+        type: { summary: "Tags" },
+        subcategory: "Card content",
+      },
+    },
+    linkList: {
+      description: "Optional [LinkList](/?path=/docs/component-linklist--docs).",
+      control: "text",
+      table: {
+        type: { summary: "LinkList" },
+        subcategory: "Card content",
+      },
+    },
+    icon: {
+      description:
+        "Optional [Icon](/?path=/docs/atom-icon--docs), should **not** be used in conjunction with Image.",
+      control: "text",
+      table: {
+        type: { summary: "Icon" },
+        subcategory: "Card content",
+      },
     },
   },
 }
@@ -64,24 +146,36 @@ type Story = StoryObj<MxCardType>
 
 export const Card: Story = {}
 
+/**
+ * Make the whole card clickable.
+ */
 export const BlockLink: Story = {
   args: {
     modifiers: [ListItemModifiers.BLOCK],
   },
 }
 
+/**
+ * Position the image on the right.
+ */
 export const Reverse: Story = {
   args: {
     modifiers: [ListItemModifiers.REVERSE],
   },
 }
 
+/**
+ * Add a date or other value.
+ */
 export const Date: Story = {
   args: {
     date: "25 May 2025",
   },
 }
 
+/**
+ * Adds a [Tags](/?path=/docs/component-tags--docs) component
+ */
 export const WithTags: Story = {
   args: {
     tags: Tags({
@@ -91,6 +185,9 @@ export const WithTags: Story = {
   },
 }
 
+/**
+ * Adds a [LinkList](/?path=/docs/component-linklist--docs) component
+ */
 export const WithLinkList: Story = {
   args: {
     link: null,
@@ -122,17 +219,35 @@ export const WithLinkList: Story = {
   },
 }
 
-export const WithIcon: Story = {
+/**
+ * The Tile version is a simple card with a `box` background, the `block` modifier and no image.
+ */
+export const Tile: Story = {
   args: {
-    icon: Icon({
-      icon: Icons.HEART,
+    title: Heading({
+      title: "Tile title",
+      as: HeadingTypes.THREE,
     }),
+    link: Link({
+      href: "#",
+      title: "Find out more",
+      more: true,
+    }),
+    content: "<p>Tiles are just block cards without an image.</p>",
+    background: BackgroundStyles.BOX,
+    modifiers: [ListItemModifiers.BLOCK],
     image: null,
   },
 }
 
-export const NoImage: Story = {
+/**
+ * The Tile version often also has an [Icon](/?path=/docs/atom-icon--docs).
+ */
+export const IconTile: Story = {
   args: {
-    image: null,
+    ...Tile.args,
+    icon: Icon({
+      icon: Icons.HEART,
+    }),
   },
 }

package/src/Component/Card/Card.stories.tsx

@@ -25,8 +25,8 @@ const meta: Meta<typeof Component> = {
         <CardContent>
           <Heading>Key feature or Section Name</Heading>
           <Text>
-            A short description to help explain enough about the subject matter
-            to encourage visitors to learn more.
+            A short description to help explain enough about the subject matter to encourage
+            visitors to learn more.
           </Text>
           <Link more to="http://example.com">
             Learn More

package/src/Component/Card/Components/CardContent.tsx

@@ -2,11 +2,7 @@ import { JSX, PropsWithChildren } from "react"
 import classNames from "classnames"
 
 const CardContent = ({ children }: PropsWithChildren): JSX.Element => {
-  return (
-    <div className={classNames("mx-card__content", "mx-vertical-flow")}>
-      {children}
-    </div>
-  )
+  return <div className={classNames("mx-card__content", "mx-vertical-flow")}>{children}</div>
 }
 
 export default CardContent

package/src/Component/Card/__snapshots__/Card.stories.ts.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Component/Card BlockLink smoke-test 1`] = `
 <div class="mx-page default">
@@ -8,7 +8,7 @@ exports[`Component/Card BlockLink smoke-test 1`] = `
         <h3>
           Card title
         </h3>
-        <div class="mx-text--lede">
+        <div class="mx-text--lede mx-vertical-flow-flex">
           <p>
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
           </p>
@@ -43,7 +43,7 @@ exports[`Component/Card Card smoke-test 1`] = `
         <h3>
           Card title
         </h3>
-        <div class="mx-text--lede">
+        <div class="mx-text--lede mx-vertical-flow-flex">
           <p>
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
           </p>
@@ -81,7 +81,7 @@ exports[`Component/Card Date smoke-test 1`] = `
         <h3>
           Card title
         </h3>
-        <div class="mx-text--lede">
+        <div class="mx-text--lede mx-vertical-flow-flex">
           <p>
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
           </p>
@@ -108,17 +108,21 @@ exports[`Component/Card Date smoke-test 1`] = `
 </div>
 `;
 
-exports[`Component/Card NoImage smoke-test 1`] = `
+exports[`Component/Card IconTile smoke-test 1`] = `
 <div class="mx-page default">
   <div class="mx-container">
-    <article class="mx-card">
+    <article class="mx-card mx-card--block mx-background--box">
+      <div class="mx-card__icon">
+        <span class="mx-icon mx-icon--heart-selected">
+        </span>
+      </div>
       <div class="mx-card__content mx-vertical-flow-flex">
         <h3>
-          Card title
+          Tile title
         </h3>
-        <div class="mx-text--lede">
+        <div class="mx-text--lede mx-vertical-flow-flex">
           <p>
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+            Tiles are just block cards without an image.
           </p>
         </div>
         <a class="mx-link--more"
@@ -142,7 +146,7 @@ exports[`Component/Card Reverse smoke-test 1`] = `
         <h3>
           Card title
         </h3>
-        <div class="mx-text--lede">
+        <div class="mx-text--lede mx-vertical-flow-flex">
           <p>
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
           </p>
@@ -169,21 +173,17 @@ exports[`Component/Card Reverse smoke-test 1`] = `
 </div>
 `;
 
-exports[`Component/Card WithIcon smoke-test 1`] = `
+exports[`Component/Card Tile smoke-test 1`] = `
 <div class="mx-page default">
   <div class="mx-container">
-    <article class="mx-card">
-      <div class="mx-card__icon">
-        <span class="mx-icon mx-icon--heart-selected ">
-        </span>
-      </div>
+    <article class="mx-card mx-card--block mx-background--box">
       <div class="mx-card__content mx-vertical-flow-flex">
         <h3>
-          Card title
+          Tile title
         </h3>
-        <div class="mx-text--lede">
+        <div class="mx-text--lede mx-vertical-flow-flex">
           <p>
-            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+            Tiles are just block cards without an image.
           </p>
         </div>
         <a class="mx-link--more"
@@ -207,7 +207,7 @@ exports[`Component/Card WithLinkList smoke-test 1`] = `
         <h3>
           Card title
         </h3>
-        <div class="mx-text--lede">
+        <div class="mx-text--lede mx-vertical-flow-flex">
           <p>
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
           </p>
@@ -218,7 +218,7 @@ exports[`Component/Card WithLinkList smoke-test 1`] = `
               <span>
                 Link one
               </span>
-              <span class="mx-icon mx-icon--chevron-right ">
+              <span class="mx-icon mx-icon--chevron-right">
               </span>
             </a>
           </li>
@@ -227,7 +227,7 @@ exports[`Component/Card WithLinkList smoke-test 1`] = `
               <span>
                 Link two
               </span>
-              <span class="mx-icon mx-icon--chevron-right ">
+              <span class="mx-icon mx-icon--chevron-right">
               </span>
             </a>
           </li>
@@ -236,7 +236,7 @@ exports[`Component/Card WithLinkList smoke-test 1`] = `
               <span>
                 Link three
               </span>
-              <span class="mx-icon mx-icon--chevron-right ">
+              <span class="mx-icon mx-icon--chevron-right">
               </span>
             </a>
           </li>
@@ -276,7 +276,7 @@ exports[`Component/Card WithTags smoke-test 1`] = `
             </span>
           </li>
         </ul>
-        <div class="mx-text--lede">
+        <div class="mx-text--lede mx-vertical-flow-flex">
           <p>
             Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
           </p>

package/src/Component/Card/__snapshots__/Card.stories.tsx.snap

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

package/src/Component/Card/card.css

@@ -41,10 +41,7 @@
         --card-gap: var(--gap-l);
         --card-alignment: center;
 
-        grid-template: "media content" 1fr / var(--media-col, 1fr) var(
-            --content-col,
-            1fr
-          );
+        grid-template: "media content" 1fr / var(--media-col, 1fr) var(--content-col, 1fr);
 
         &.mx-card--reversed {
           grid-template-areas: "content media";
@@ -114,8 +111,7 @@
  */
 
 @layer design-system.components {
-  .mx-grid:has(> *:nth-child(2):last-child)
-    > :is(.mx-card, .mx-container:has(.mx-card)) {
+  .mx-grid:has(> *:nth-child(2):last-child) > :is(.mx-card, .mx-container:has(.mx-card)) {
     inline-size: min(100%, var(--max-card-width, 37ch));
     margin-inline: auto;
   }

package/src/Component/Card/card.twig

@@ -31,7 +31,7 @@
     {{ title }}
     {{ tags }}
     {% if content is not empty %}
-      <div class="mx-text--lede">{{ content }}</div>
+      <div class="mx-text--lede mx-vertical-flow-flex">{{ content }}</div>
     {% endif %}
     {{ linkList }}
     {{ link }}

package/src/Component/Carousel/Carousel.stories.ts

@@ -2,11 +2,7 @@ import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./carousel.twig"
 import "./carousel.css"
 import "./Elements/Carousel"
-import {
-  Carousel as CarouselType,
-  HeadingTypes,
-  ListItemModifiers,
-} from "@pnx-mixtape/ids-shape"
+import { Carousel as CarouselType, HeadingTypes, ListItemModifiers } from "@pnx-mixtape/ids-shape"
 
 // Deps.
 import Card from "../Card/card.twig"
@@ -15,10 +11,20 @@ import Heading from "../../Atom/Heading/heading.twig"
 import Link from "../../Atom/Link/link.twig"
 import { BackgroundStyles } from "../../enums"
 
+/**
+ * A carousel of GridItems (usually Cards), that natively scrolls.
+ *
+ * Extra features like Forward/Back buttons and counters can be added with the `Carousel` element javascript (if items exceed the container)
+ *
+ * The number if items visible can be controlled with CSS by setting the `--inline-size` property (default to 25ch).
+ */
 const meta: Meta<CarouselType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
+    counter: false,
+    pagination: false,
+    loop: false,
     items: [
       Card({
         title: Heading({
@@ -176,9 +182,42 @@ const meta: Meta<CarouselType> = {
         modifiers: [ListItemModifiers.BLOCK],
       }),
     ],
-    loop: false,
-    pagination: false,
-    counter: false,
+  },
+  argTypes: {
+    items: {
+      description:
+        "A list of `GridItem` objects, usually [Cards](/?path=/docs/component-card--docs) or [ContentBlocks](/?path=/docs/component-contentblock--docs).",
+      type: {
+        name: "other",
+        required: true,
+        value: "array",
+      },
+      table: {
+        type: { summary: "GridItem[]" },
+      },
+    },
+    loop: {
+      description:
+        "Loop back to the start when the end has been reached. Requires the `Carousel` javascript.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    pagination: {
+      description: "Adds numbered pagination. Requires the `Carousel` javascript.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    counter: {
+      description: "Adds counter dot navigation. Requires the `Carousel` javascript.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
   },
 }
 
@@ -187,15 +226,29 @@ type Story = StoryObj<CarouselType>
 
 export const Carousel: Story = {}
 
+/**
+ * Display counter dot navigation.
+ */
 export const Counters: Story = {
   args: {
     counter: true,
   },
 }
 
+/**
+ * Display numbered pagination.
+ */
 export const Paginated: Story = {
   args: {
     pagination: true,
+  },
+}
+
+/**
+ * Loop back to start when the end is reached and the next button is clicked.
+ */
+export const Loop: Story = {
+  args: {
     loop: true,
   },
 }

package/src/Component/Carousel/Elements/Carousel.ts

@@ -32,18 +32,14 @@ export default class Carousel extends HTMLElement {
     const { signal }: AbortController = this.controller
     if (this.prev) {
       this.prev.disabled = true
-      this.prev.addEventListener(
-        "click",
-        () => this.handleNavigation(this.activePage - 1),
-        { signal },
-      )
+      this.prev.addEventListener("click", () => this.handleNavigation(this.activePage - 1), {
+        signal,
+      })
     }
     if (this.next)
-      this.next.addEventListener(
-        "click",
-        () => this.handleNavigation(this.activePage + 1),
-        { signal },
-      )
+      this.next.addEventListener("click", () => this.handleNavigation(this.activePage + 1), {
+        signal,
+      })
     this.list.addEventListener("scroll", this.handleScroll, { signal })
 
     if (this.pagination) {
@@ -56,8 +52,7 @@ export default class Carousel extends HTMLElement {
       })
     }
 
-    const items: NodeListOf<HTMLLIElement> =
-      this.list.querySelectorAll(":scope > li")
+    const items: NodeListOf<HTMLLIElement> = this.list.querySelectorAll(":scope > li")
     this.itemMap = new Map()
     const iO = new IntersectionObserver(
       entries => {
@@ -116,8 +111,7 @@ export default class Carousel extends HTMLElement {
     let isEnd = false
     if (this.prev) this.prev.disabled = this.list.scrollLeft < 1
     if (this.next || this.pagination) {
-      isEnd =
-        this.list.scrollLeft === this.list.scrollWidth - this.list.offsetWidth
+      isEnd = this.list.scrollLeft === this.list.scrollWidth - this.list.offsetWidth
     }
     if (this.next) {
       if (!this.loop) {
@@ -150,10 +144,7 @@ export default class Carousel extends HTMLElement {
 
   handleScroll = () => {
     window.clearTimeout(this.debounced)
-    this.debounced = setTimeout(
-      this.handleDisabled,
-      this.pagination ? 100 : 200,
-    )
+    this.debounced = setTimeout(this.handleDisabled, this.pagination ? 100 : 200)
   }
 
   handleOverflow = () => {
@@ -232,7 +223,7 @@ export default class Carousel extends HTMLElement {
   }
 }
 
-customElements.define("mx-carousel", Carousel)
+if (!customElements.get("mx-carousel")) customElements.define("mx-carousel", Carousel)
 
 declare global {
   interface HTMLElementTagNameMap {