@pnx-mixtape/mxds 0.0.21 → 0.0.23

package/src/Component/ContentBlock/ContentBlock.stories.ts

@@ -1,10 +1,7 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./content-block.twig"
 import "./content-block.css"
-import {
-  ContentBlock as ContentBlockType,
-  HeadingTypes,
-} from "@pnx-mixtape/ids-shape"
+import { ContentBlock as ContentBlockType, HeadingTypes } from "@pnx-mixtape/ids-shape"
 import { Icons } from "../../enums"
 
 // Deps.
@@ -15,6 +12,9 @@ import LinkList from "../LinkList/link-list.twig"
 import Icon from "../../Atom/Icon/icon.twig"
 import "../LinkList/link-list.css"
 
+/**
+ * Content Block is similar to a Card, but it is always vertical and usually includes a [LinkList](/?path=/docs/component-linklist--docs).
+ */
 const meta: Meta<ContentBlockType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
@@ -23,13 +23,13 @@ const meta: Meta<ContentBlockType> = {
       title: "Content block 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. 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. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>",
     linkList: LinkList({
       items: [
         Link({
@@ -57,13 +57,57 @@ const meta: Meta<ContentBlockType> = {
     }),
   },
   argTypes: {
-    // @ts-expect-error The controls follow the shape
-    "image.src": { control: "text" },
-    "image.alt": { control: "text" },
-    "title.title": { control: "text" },
-    "title.as": { options: Object.values(HeadingTypes), control: "select" },
-    "link.href": { control: "text" },
-    "link.title": { control: "text" },
+    image: {
+      description: "Optional [Image](/?path=/docs/atom-image--docs) component.",
+      control: "text",
+      table: {
+        type: { summary: "Image" },
+      },
+    },
+    title: {
+      description: "A [Heading](/?path=/docs/atom-heading--docs) component.",
+      control: "text",
+      type: {
+        name: "string",
+        required: true,
+      },
+      table: {
+        type: { summary: "Heading" },
+      },
+    },
+    content: {
+      description: "Content.",
+      control: "text",
+      type: {
+        name: "string",
+        required: true,
+      },
+      table: {
+        type: { summary: "WysiwygText" },
+      },
+    },
+    link: {
+      description: "Optional content [Link](/?path=/docs/atom-link--docs).",
+      control: "text",
+      table: {
+        type: { summary: "Link" },
+      },
+    },
+    linkList: {
+      description: "Optional [LinkList](/?path=/docs/component-linklist--docs).",
+      control: "text",
+      table: {
+        type: { summary: "LinkList" },
+      },
+    },
+    icon: {
+      description:
+        "Optional [Icon](/?path=/docs/atom-icon--docs), should **not** be used in conjunction with Image.",
+      control: "text",
+      table: {
+        type: { summary: "Icon" },
+      },
+    },
   },
 }
 
@@ -72,6 +116,9 @@ type Story = StoryObj<ContentBlockType>
 
 export const ContentBlock: Story = {}
 
+/**
+ * Displays an [Icon](/?path=/docs/atom-icon--docs) component.
+ */
 export const WithIcon: Story = {
   args: {
     icon: Icon({
@@ -80,6 +127,9 @@ export const WithIcon: Story = {
   },
 }
 
+/**
+ * Displays an [Image](/?path=/docs/atom-image--docs) component.
+ */
 export const WithImage: Story = {
   args: {
     image: Image({

package/src/Component/ContentBlock/ContentBlock.stories.tsx

@@ -25,8 +25,8 @@ const meta: Meta<typeof Component> = {
         <ContentBlockContent>
           <Heading as={HeadingTypes.THREE}>Content block</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/ContentBlock/ContentBlock.tsx

@@ -6,11 +6,7 @@ type ContentBlockProps = PropsWithChildren & {
   as?: AsTypes
 }
 
-const ContentBlock = ({
-  children,
-  as = AsTypes.DIV,
-  ...props
-}: ContentBlockProps): JSX.Element => {
+const ContentBlock = ({ children, as = AsTypes.DIV, ...props }: ContentBlockProps): JSX.Element => {
   const Tag: JSX.ElementType = `${as}` as unknown as JSX.ElementType
   return (
     <Tag className={classNames("mx-content-block")} {...props}>

package/src/Component/ContentBlock/__snapshots__/ContentBlock.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/ContentBlock ContentBlock smoke-test 1`] = `
 <div class="mx-page default">
@@ -16,7 +16,7 @@ exports[`Component/ContentBlock ContentBlock smoke-test 1`] = `
             <span>
               Music
             </span>
-            <span class="mx-icon mx-icon--chevron-right ">
+            <span class="mx-icon mx-icon--chevron-right">
             </span>
           </a>
         </li>
@@ -25,7 +25,7 @@ exports[`Component/ContentBlock ContentBlock smoke-test 1`] = `
             <span>
               Performances
             </span>
-            <span class="mx-icon mx-icon--chevron-right ">
+            <span class="mx-icon mx-icon--chevron-right">
             </span>
           </a>
         </li>
@@ -34,7 +34,7 @@ exports[`Component/ContentBlock ContentBlock smoke-test 1`] = `
             <span>
               Get involved
             </span>
-            <span class="mx-icon mx-icon--chevron-right ">
+            <span class="mx-icon mx-icon--chevron-right">
             </span>
           </a>
         </li>
@@ -55,7 +55,7 @@ exports[`Component/ContentBlock WithIcon smoke-test 1`] = `
 <div class="mx-page default">
   <article class="mx-content-block">
     <div class="mx-content-block__icon">
-      <span class="mx-icon mx-icon--heart-selected ">
+      <span class="mx-icon mx-icon--heart-selected">
       </span>
     </div>
     <div class="mx-content-block__content mx-vertical-flow-flex">
@@ -71,7 +71,7 @@ exports[`Component/ContentBlock WithIcon smoke-test 1`] = `
             <span>
               Music
             </span>
-            <span class="mx-icon mx-icon--chevron-right ">
+            <span class="mx-icon mx-icon--chevron-right">
             </span>
           </a>
         </li>
@@ -80,7 +80,7 @@ exports[`Component/ContentBlock WithIcon smoke-test 1`] = `
             <span>
               Performances
             </span>
-            <span class="mx-icon mx-icon--chevron-right ">
+            <span class="mx-icon mx-icon--chevron-right">
             </span>
           </a>
         </li>
@@ -89,7 +89,7 @@ exports[`Component/ContentBlock WithIcon smoke-test 1`] = `
             <span>
               Get involved
             </span>
-            <span class="mx-icon mx-icon--chevron-right ">
+            <span class="mx-icon mx-icon--chevron-right">
             </span>
           </a>
         </li>
@@ -129,7 +129,7 @@ exports[`Component/ContentBlock WithImage smoke-test 1`] = `
             <span>
               Music
             </span>
-            <span class="mx-icon mx-icon--chevron-right ">
+            <span class="mx-icon mx-icon--chevron-right">
             </span>
           </a>
         </li>
@@ -138,7 +138,7 @@ exports[`Component/ContentBlock WithImage smoke-test 1`] = `
             <span>
               Performances
             </span>
-            <span class="mx-icon mx-icon--chevron-right ">
+            <span class="mx-icon mx-icon--chevron-right">
             </span>
           </a>
         </li>
@@ -147,7 +147,7 @@ exports[`Component/ContentBlock WithImage smoke-test 1`] = `
             <span>
               Get involved
             </span>
-            <span class="mx-icon mx-icon--chevron-right ">
+            <span class="mx-icon mx-icon--chevron-right">
             </span>
           </a>
         </li>

package/src/Component/ContentBlock/__snapshots__/ContentBlock.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/ContentBlock ContentBlock smoke-test 1`] = `
 <div class="mx-content-block">

package/src/Component/Dialog/Dialog.stories.ts

@@ -1,23 +1,28 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
+import DrupalAttribute from "drupal-attribute"
 import Component from "./dialog.twig"
 import "./dialog.css"
 import "./Elements/Dialog"
-import {
-  ButtonModifiers,
-  Dialog as DialogType,
-  HeadingTypes,
-} from "@pnx-mixtape/ids-shape"
+import { ButtonModifiers, Dialog as DialogType, HeadingTypes } from "@pnx-mixtape/ids-shape"
 
 // Deps.
 import Heading from "../../Atom/Heading/heading.twig"
 import Button from "../../Atom/Button/button.twig"
 import Link from "../../Atom/Link/link.twig"
-import DrupalAttribute from "drupal-attribute"
 
 type MxDialogType = DialogType & {
   fullscreen?: boolean
 }
 
+/**
+ * The Dialog component creates a native HTML dialog.
+ * It requires the `Dialog` custom element javascript.
+ *
+ * There should be an associated trigger [Button](/?path=/docs/atom-button--docs) or [Link](/?path=/docs/atom-link--docs)
+ * with a valid reference to the dialogs ID: `href="#example-dialog"` or `aria-controls="example-dialog"`.
+ *
+ * Adding the `[data-close]` attribute to a button inside the dialog will also close the dialog when clicked.
+ */
 const meta: Meta<MxDialogType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
@@ -32,14 +37,66 @@ const meta: Meta<MxDialogType> = {
     link: Button({
       title: "Let's go",
       modifiers: [ButtonModifiers.DARK],
-
       attributes: new DrupalAttribute()?.setAttribute("data-close", ""),
     }),
   },
   argTypes: {
-    open: { control: "boolean" },
-    modal: { control: "boolean" },
-    fullscreen: { control: "boolean" },
+    id: {
+      description: "The dialog id, used to connect the dialog to the relevant trigger.",
+      type: {
+        name: "string",
+        required: true,
+      },
+    },
+    open: {
+      description: "Option to set the dialog as open by default.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    modal: {
+      description: "Option to create a Modal dialog.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    fullscreen: {
+      description: "Option to make the dialog display full screen.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    title: {
+      description: "A [Heading](/?path=/docs/atom-heading--docs) component.",
+      control: "text",
+      table: {
+        type: { summary: "Heading" },
+        subcategory: "Dialog content",
+      },
+    },
+    content: {
+      description: "Content.",
+      control: "text",
+      type: {
+        name: "string",
+        required: true,
+      },
+      table: {
+        type: { summary: "WysiwygText" },
+        subcategory: "Dialog content",
+      },
+    },
+    link: {
+      description: "Optional content [Link](/?path=/docs/atom-link--docs).",
+      control: "text",
+      table: {
+        type: { summary: "Link" },
+        subcategory: "Dialog content",
+      },
+    },
   },
   render: args => `
     ${Link({
@@ -54,8 +111,14 @@ const meta: Meta<MxDialogType> = {
 export default meta
 type Story = StoryObj<MxDialogType>
 
+/**
+ * Non-modal dialog, that allows interaction outside of it. See [show()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/show)
+ */
 export const Dialog: Story = {}
 
+/**
+ * Modals display in the top layer and cover all other content (with backdrop). See [showModal()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal)
+ */
 export const Modal: Story = {
   args: {
     id: "example-modal",
@@ -65,31 +128,25 @@ export const Modal: Story = {
     ${Button({
       title: "Open modal",
       modifiers: [ButtonModifiers.DARK],
-
-      attributes: new DrupalAttribute()?.setAttribute(
-        "aria-controls",
-        "example-modal",
-      ),
+      attributes: new DrupalAttribute()?.setAttribute("aria-controls", "example-modal"),
     })}
     ${Component(args)}
   `,
 }
 
+/**
+ * Full screen dialogs always trigger the Modal behaviour.
+ */
 export const Fullscreen: Story = {
   args: {
     id: "example-fullscreen",
     fullscreen: true,
-    modal: true,
   },
   render: args => `
     ${Button({
       title: "Open fullscreen modal",
       modifiers: [ButtonModifiers.DARK],
-
-      attributes: new DrupalAttribute()?.setAttribute(
-        "aria-controls",
-        "example-fullscreen",
-      ),
+      attributes: new DrupalAttribute()?.setAttribute("aria-controls", "example-fullscreen"),
     })}
     ${Component(args)}
   `,

package/src/Component/Dialog/Dialog.stories.tsx

@@ -17,9 +17,8 @@ const meta: Meta<typeof Component> = {
         <DialogContent>
           <Heading as={HeadingTypes.THREE}>Thanks, you're almost done!</Heading>
           <Text>
-            To finish the process, you will need to upload a few more documents.
-            Please have your confirmation email ready before starting. Are you
-            ready?
+            To finish the process, you will need to upload a few more documents. Please have your
+            confirmation email ready before starting. Are you ready?
           </Text>
           <form method="dialog">
             <div className="mx-form-actions">

package/src/Component/Dialog/Elements/Dialog.ts

@@ -3,6 +3,7 @@
  * @file Support opening/closing, and adding a scroll lock to the body.
  */
 
+// Needed until Safari supports https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#closedby
 import { handleOutsideClick, handleEscape } from "../../../Utility/utilities"
 
 export default class Dialog extends HTMLElement {
@@ -22,14 +23,10 @@ export default class Dialog extends HTMLElement {
     const { signal }: AbortController = this.controller
 
     // Open on toggle click.
-    this.openBtns?.forEach(btn =>
-      btn.addEventListener("click", this.handleOpen, { signal }),
-    )
+    this.openBtns?.forEach(btn => btn.addEventListener("click", this.handleOpen, { signal }))
 
     // Close on close button click.
-    this.closeBtns?.forEach(btn =>
-      btn.addEventListener("click", this.handleClose, { signal }),
-    )
+    this.closeBtns?.forEach(btn => btn.addEventListener("click", this.handleClose, { signal }))
 
     // Close on outside click.
     document.addEventListener(
@@ -61,9 +58,7 @@ export default class Dialog extends HTMLElement {
   disconnectedCallback(): void {
     if (!this.dialog) return
     if (typeof this.dialog.close === "function") this.dialog.close()
-    this.openBtns?.forEach((btn: Element) =>
-      btn.setAttribute("aria-expanded", "false"),
-    )
+    this.openBtns?.forEach((btn: Element) => btn.setAttribute("aria-expanded", "false"))
     if (this.isModal) document.body.classList.remove(this.scrollLockClass)
     this.controller.abort()
   }
@@ -74,18 +69,14 @@ export default class Dialog extends HTMLElement {
     if (typeof this.dialog.show === "function") {
       this.isModal ? this.dialog.showModal() : this.dialog.show()
     }
-    this.openBtns?.forEach((btn: Element) =>
-      btn.setAttribute("aria-expanded", "true"),
-    )
+    this.openBtns?.forEach((btn: Element) => btn.setAttribute("aria-expanded", "true"))
     if (this.isModal) document.body.classList.add(this.scrollLockClass)
   }
 
   handleClose = (): void => {
     if (!this.dialog) return
     if (typeof this.dialog.close === "function") this.dialog.close()
-    this.openBtns?.forEach((btn: Element) =>
-      btn.setAttribute("aria-expanded", "false"),
-    )
+    this.openBtns?.forEach((btn: Element) => btn.setAttribute("aria-expanded", "false"))
     if (this.isModal) document.body.classList.remove(this.scrollLockClass)
   }
 
@@ -116,7 +107,7 @@ export default class Dialog extends HTMLElement {
   }
 }
 
-customElements.define("mx-dialog", Dialog)
+if (!customElements.get("mx-dialog")) customElements.define("mx-dialog", Dialog)
 
 declare global {
   interface HTMLElementTagNameMap {

package/src/Component/Dialog/__snapshots__/Dialog.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/Dialog Dialog smoke-test 1`] = `
 <div class="mx-page default">
@@ -10,7 +10,7 @@ exports[`Component/Dialog Dialog smoke-test 1`] = `
     </span>
   </a>
   <mx-dialog id="unique-0">
-    <dialog class="mx-dialog ">
+    <dialog class="mx-dialog">
       <button autofocus
               class="mx-button mx-button--icon-only mx-icon mx-icon--close"
               data-close
@@ -24,8 +24,7 @@ exports[`Component/Dialog Dialog smoke-test 1`] = `
         <p>
           I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.
         </p>
-        <button data-close
-                class="mx-button  mx-button--dark"
+        <button class="mx-button mx-button--dark"
                 type="button"
         >
           <span>
@@ -41,7 +40,7 @@ exports[`Component/Dialog Dialog smoke-test 1`] = `
 exports[`Component/Dialog Fullscreen smoke-test 1`] = `
 <div class="mx-page default">
   <button aria-controls="unique-0"
-          class="mx-button  mx-button--dark"
+          class="mx-button mx-button--dark"
           type="button"
   >
     <span>
@@ -65,8 +64,7 @@ exports[`Component/Dialog Fullscreen smoke-test 1`] = `
         <p>
           I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.
         </p>
-        <button data-close
-                class="mx-button  mx-button--dark"
+        <button class="mx-button mx-button--dark"
                 type="button"
         >
           <span>
@@ -82,7 +80,7 @@ exports[`Component/Dialog Fullscreen smoke-test 1`] = `
 exports[`Component/Dialog Modal smoke-test 1`] = `
 <div class="mx-page default">
   <button aria-controls="unique-0"
-          class="mx-button  mx-button--dark"
+          class="mx-button mx-button--dark"
           type="button"
   >
     <span>
@@ -92,7 +90,7 @@ exports[`Component/Dialog Modal smoke-test 1`] = `
   <mx-dialog id="unique-0"
              data-modal
   >
-    <dialog class="mx-dialog ">
+    <dialog class="mx-dialog">
       <button autofocus
               class="mx-button mx-button--icon-only mx-icon mx-icon--close"
               data-close
@@ -106,8 +104,7 @@ exports[`Component/Dialog Modal smoke-test 1`] = `
         <p>
           I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.
         </p>
-        <button data-close
-                class="mx-button  mx-button--dark"
+        <button class="mx-button mx-button--dark"
                 type="button"
         >
           <span>

package/src/Component/Dialog/__snapshots__/Dialog.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/Dialog Dialog smoke-test 1`] = `
 <dialog class="mx-dialog"

package/src/Component/Dialog/dialog.css

@@ -15,8 +15,7 @@
     overflow: auto hidden;
     overscroll-behavior: contain;
     background-color: var(--dialog-background, var(--colour-background));
-    border: var(--line-width, 1px) solid
-      var(--line-colour, var(--colour-border));
+    border: var(--line-width, 1px) solid var(--line-colour, var(--colour-border));
     padding: 0;
     place-self: center;
     opacity: 0;

package/src/Component/Dialog/dialog.twig

@@ -5,7 +5,7 @@
 ] %}
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
 
-<mx-dialog id="{{ id }}"{% if modal %} data-modal{% endif %}>
+<mx-dialog id="{{ id }}"{% if modal or fullscreen %} data-modal{% endif %}>
   <dialog{{ attributes }}{% if open %} open{% endif %}>
     <button autofocus class="mx-button mx-button--icon-only mx-icon mx-icon--close" data-close>Close dialog</button>
     <div class="mx-dialog__content mx-vertical-flow">

package/src/Component/DropMenu/Components/DropMenuContext.tsx

@@ -36,11 +36,7 @@ type DropMenuContextValues = {
 type DropMenuProviderProps = PropsWithChildren & {
   id: string
   multiple?: boolean
-  onClick?: (
-    event: MouseEvent | KeyboardEvent,
-    key: string,
-    updated?: string[],
-  ) => void
+  onClick?: (event: MouseEvent | KeyboardEvent, key: string, updated?: string[]) => void
   closeOnClick?: boolean
   selectedItem?: string[]
   focusRef?: RefObject<HTMLElement>
@@ -77,7 +73,7 @@ const DropMenuProvider = ({
     if (!popoverRef.current || polyfilled.current) return
     const polyfill = async () => {
       if (!("anchorName" in document.documentElement.style)) {
-        const { default: Polyfills } = await import("../polyfills")
+        const { default: Polyfills } = await import("../../Popover/polyfills")
         new Polyfills(popoverRef.current)
         polyfilled.current = true
       }
@@ -119,8 +115,7 @@ const DropMenuProvider = ({
       popoverRef.current.querySelectorAll(":scope > button")
     if (!items) return
 
-    const attachKeyboardMenu = () =>
-      keyboard.attachMenu(popoverRef.current, items)
+    const attachKeyboardMenu = () => keyboard.attachMenu(popoverRef.current, items)
     popoverRef.current.addEventListener("focusin", attachKeyboardMenu, {
       signal,
     })
@@ -137,10 +132,7 @@ const DropMenuProvider = ({
   }, [on, popoverRef])
 
   // Handle item click events.
-  const handleClick = (
-    event: MouseEvent | KeyboardEvent,
-    key: string,
-  ): void => {
+  const handleClick = (event: MouseEvent | KeyboardEvent, key: string): void => {
     event.preventDefault()
     let updated: string[] = []
     if (selected.includes(key)) {