@pnx-mixtape/mxds 0.0.21 → 0.0.23

package/src/Component/ResultsBar/Components/ResultsBarSort.tsx

@@ -2,12 +2,7 @@ import { JSX } from "react"
 import FormSelect, { FormSelectProps } from "../../../Form/Select/FormSelect"
 import FormLabel from "../../../Form/Label/FormLabel"
 
-const ResultsBarSort = ({
-  id,
-  name,
-  options,
-  ...props
-}: FormSelectProps): JSX.Element => (
+const ResultsBarSort = ({ id, name, options, ...props }: FormSelectProps): JSX.Element => (
   <div className="mx-results-bar__sort">
     <FormLabel id={id} text="Sort by" />
     <FormSelect name={name} options={options} id={id} {...props} />

package/src/Component/ResultsBar/ResultsBar.stories.ts

@@ -3,6 +3,9 @@ import Component from "./results-bar.twig"
 import "./results-bar.css"
 import { ResultsBar as ResultsBarType } from "@pnx-mixtape/ids-shape"
 
+/**
+ * A bar displaying the number of results available, and an optional sort dropdown.
+ */
 const meta: Meta<ResultsBarType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
@@ -12,10 +15,31 @@ const meta: Meta<ResultsBarType> = {
     total: 250,
   },
   argTypes: {
-    number: { control: "number" },
-    pageCount: { control: "number" },
-    total: { control: "number" },
-    empty: { control: "boolean" },
+    number: {
+      description: "The current page number.",
+      type: "number",
+    },
+    pageCount: {
+      description: "The number of results displayed per page.",
+      type: "number",
+    },
+    total: {
+      description: "The total number of results.",
+      type: "number",
+    },
+    empty: {
+      description: "If true, shows an empty results message.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    sort: {
+      description: "A string array of options to use for sorting.",
+      table: {
+        type: { summary: "string[]" },
+      },
+    },
   },
 }
 
@@ -24,12 +48,18 @@ type Story = StoryObj<ResultsBarType>
 
 export const ResultsBar: Story = {}
 
+/**
+ * Display empty results message.
+ */
 export const Empty: Story = {
   args: {
     empty: true,
   },
 }
 
+/**
+ * Create a sort dropdown from a list of options.
+ */
 export const Sort: Story = {
   args: {
     sort: ["Most recent", "A-Z", "Z-A"],

package/src/Component/ResultsBar/__snapshots__/ResultsBar.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/ResultsBar Empty smoke-test 1`] = `
 <div class="mx-page default">
@@ -14,7 +14,7 @@ exports[`Component/ResultsBar Empty smoke-test 1`] = `
 
 exports[`Component/ResultsBar ResultsBar smoke-test 1`] = `
 <div class="mx-page default">
-  <div class="mx-results-bar ">
+  <div class="mx-results-bar">
     <span aria-live="polite">
       Showing results 1 - 10 of 250 results
     </span>
@@ -24,7 +24,7 @@ exports[`Component/ResultsBar ResultsBar smoke-test 1`] = `
 
 exports[`Component/ResultsBar Sort smoke-test 1`] = `
 <div class="mx-page default">
-  <div class="mx-results-bar ">
+  <div class="mx-results-bar">
     <span aria-live="polite">
       Showing results 1 - 10 of 250 results
     </span>

package/src/Component/ResultsBar/__snapshots__/ResultsBar.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/ResultsBar Empty smoke-test 1`] = `
 <div class="mx-results-bar">

package/src/Component/SideNavigation/SideNavigation.stories.ts

@@ -89,6 +89,46 @@ const meta: Meta<NavigationType> = {
       },
     ],
   },
+  argTypes: {
+    parent: {
+      description:
+        "A [Link](/?path=/docs/atom-link--docs) objects for the parent page shown at the top of the menu.",
+      type: {
+        name: "other",
+        required: true,
+        value: "array",
+      },
+      table: {
+        type: { summary: "Link" },
+      },
+    },
+    items: {
+      description:
+        "A list of [Link](/?path=/docs/atom-link--docs) objects, that can have nested `items` included. The `current` setting should be used for the current page link.",
+      type: {
+        name: "other",
+        required: true,
+        value: "array",
+      },
+      table: {
+        type: { summary: "Link[]" },
+      },
+    },
+    title: {
+      description: "The nav elements `aria-label` value.",
+      type: {
+        name: "string",
+        required: true,
+      },
+    },
+    id: {
+      description: "The unique id for the navigation.",
+      type: {
+        name: "string",
+        required: true,
+      },
+    },
+  },
 }
 
 export default meta

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

package/src/Component/SideNavigation/side-navigation.css

@@ -4,8 +4,7 @@
 
 @layer design-system.components {
   .mx-side-nav__parent {
-    border-block-end: var(--line-width, 2px) solid
-      var(--line-colour, currentcolor);
+    border-block-end: var(--line-width, 2px) solid var(--line-colour, currentcolor);
 
     & a {
       display: block;
@@ -33,11 +32,9 @@
       & a {
         display: block;
         color: inherit;
-        border-block-end: var(--line-width, 1px) solid
-          var(--line-colour, var(--colour-border));
+        border-block-end: var(--line-width, 1px) solid var(--line-colour, var(--colour-border));
         padding-block: var(--item-spacing, var(--spacing-xxs));
-        padding-inline: var(--indent, var(--spacing-xxs))
-          var(--item-spacing, var(--spacing-xxs));
+        padding-inline: var(--indent, var(--spacing-xxs)) var(--item-spacing, var(--spacing-xxs));
       }
     }
 

package/src/Component/SocialLinks/SocialLinks.stories.ts

@@ -50,6 +50,26 @@ const meta: Meta<SocialLinksType> = {
       }),
     ],
   },
+  argTypes: {
+    title: {
+      description: "Optional [Heading](/?path=/docs/atom-heading--docs) component.",
+      control: "text",
+      table: {
+        type: { summary: "Heading" },
+      },
+    },
+    items: {
+      description: `A list of [Link](/?path=/docs/atom-link--docs) objects to use for the menu. These should include the relevant [Icon](/?path=/docs/atom-icon--docs)`,
+      type: {
+        name: "other",
+        required: true,
+        value: "array",
+      },
+      table: {
+        type: { summary: "Link[]" },
+      },
+    },
+  },
 }
 
 export default meta

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

@@ -1,29 +1,29 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Component/SocialLinks SocialLinks smoke-test 1`] = `
 <div class="mx-page default">
   <nav class="mx-social-links"
        aria-label="Social media links"
   >
-    <h2 class=" mx-heading--m">
+    <h2 class="mx-heading--m">
       Follow us
     </h2>
     <a href="#">
-      <span class="mx-icon mx-icon--facebook  mx-icon--size-md">
+      <span class="mx-icon mx-icon--facebook mx-icon--size-md">
       </span>
       <span class="sr-only">
         Facebook
       </span>
     </a>
     <a href="#">
-      <span class="mx-icon mx-icon--instagram  mx-icon--size-md">
+      <span class="mx-icon mx-icon--instagram mx-icon--size-md">
       </span>
       <span class="sr-only">
         Instagram
       </span>
     </a>
     <a href="#">
-      <span class="mx-icon mx-icon--linkedin  mx-icon--size-md">
+      <span class="mx-icon mx-icon--linkedin mx-icon--size-md">
       </span>
       <span class="sr-only">
         LinkedIn

package/src/Component/SocialShare/SocialShare.stories.ts

@@ -0,0 +1,37 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import Component from "./social-share.twig"
+import { SocialShare as SocialShareType } from "@pnx-mixtape/ids-shape"
+
+const meta: Meta<SocialShareType> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    twitter: "https://twitter.com/intent/tweet",
+    bluesky: "https://bsky.app/intent/compose",
+    facebook: "https://www.facebook.com/sharer.php",
+    linkedin: "https://www.linkedin.com/shareArticle",
+    email: "mailto:",
+  },
+  argTypes: {
+    twitter: {
+      description: "To include a twitter option, add it's share URL with relevant params.",
+    },
+    bluesky: {
+      description: "To include a blueksy option, add it's share URL with relevant params.",
+    },
+    facebook: {
+      description: "To include a facebook option, add it's share URL with relevant params.",
+    },
+    linkedin: {
+      description: "To include a linkedin option, add it's share URL with relevant params.",
+    },
+    email: {
+      description: "To include an email option, add a `mailto:` url",
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<SocialShareType>
+
+export const SocialShare: Story = {}

package/src/Component/SocialShare/SocialShare.tsx

@@ -21,10 +21,8 @@ const SocialShare = ({
   const socialShareUrl: string = useMemo(() => {
     if (type === SocialShareTypes.TWITTER)
       return encodeURI(`${twitterUrl}?url=${shareUrl}&text=${text}`)
-    if (type === SocialShareTypes.FACEBOOK)
-      return encodeURI(`${facebookUrl}?url=${shareUrl}`)
-    if (type === SocialShareTypes.LINKEDIN)
-      return encodeURI(`${linkedInUrl}/?url=${shareUrl}`)
+    if (type === SocialShareTypes.FACEBOOK) return encodeURI(`${facebookUrl}?url=${shareUrl}`)
+    if (type === SocialShareTypes.LINKEDIN) return encodeURI(`${linkedInUrl}/?url=${shareUrl}`)
     return ""
   }, [type])
 

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

@@ -0,0 +1,40 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`Component/SocialShare SocialShare smoke-test 1`] = `
+<div class="mx-page default">
+  <nav class="mx-social-share flex gap--s"
+       aria-label="Social share buttons"
+  >
+    <a class="mx-link mx-icon mx-icon--only mx-icon--bluesky"
+       href="https://bsky.app/intent/compose"
+       target="_blank"
+    >
+      Share to Bluesky
+    </a>
+    <a class="mx-link mx-icon mx-icon--only mx-icon--twitter"
+       href="https://twitter.com/intent/tweet"
+       target="_blank"
+    >
+      Share to X (Twitter)
+    </a>
+    <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin"
+       href="https://www.linkedin.com/shareArticle"
+       target="_blank"
+    >
+      Share to LinkedIn
+    </a>
+    <a class="mx-link mx-icon mx-icon--only mx-icon--facebook"
+       href="https://www.facebook.com/sharer.php"
+       target="_blank"
+    >
+      Share to Facebook
+    </a>
+    <a class="mx-link mx-icon mx-icon--only mx-icon--email"
+       href="mailto:"
+       target="_blank"
+    >
+      Share via email
+    </a>
+  </nav>
+</div>
+`;

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

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Elements/Social Share Facebook smoke-test 1`] = `
 <a href="https://www.facebook.com/sharer/sharer.php?url=https://previousnext.com.au"

package/src/Component/SocialShare/social-share.twig

@@ -0,0 +1,34 @@
+{% set classes = [
+  "mx-social-share",
+  "flex",
+  'gap--s',
+] %}
+{% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
+
+<nav{{ attributes }} aria-label="Social share buttons">
+  {% if bluesky is not empty %}
+    <a class="mx-link mx-icon mx-icon--only mx-icon--bluesky" href="{{ bluesky }}" target="_blank">
+      Share to Bluesky
+    </a>
+  {% endif %}
+  {% if twitter is not empty %}
+    <a class="mx-link mx-icon mx-icon--only mx-icon--twitter" href="{{ twitter }}" target="_blank">
+      Share to X (Twitter)
+    </a>
+  {% endif %}
+  {% if linkedin is not empty %}
+    <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="{{ linkedin }}" target="_blank">
+      Share to LinkedIn
+    </a>
+  {% endif %}
+  {% if facebook is not empty %}
+    <a class="mx-link mx-icon mx-icon--only mx-icon--facebook" href="{{ facebook }}" target="_blank">
+      Share to Facebook
+    </a>
+  {% endif %}
+  {% if email is not empty %}
+    <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="{{ email }}" target="_blank">
+      Share via email
+    </a>
+  {% endif %}
+</nav>

package/src/Component/Steps/StepItem.stories.ts

@@ -0,0 +1,48 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import Component from "./step-item.twig"
+import "./steps.css"
+import { StepItem as StepsItemType } from "@pnx-mixtape/ids-shape"
+
+/**
+ * An individual Steps item, design to be used in its parent context.
+ */
+const meta: Meta<StepsItemType> = {
+  tags: ["autodocs", "ids-mvp"],
+  component: Component,
+  args: {
+    content:
+      "<h2>Funk</h2><p>Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.</p>",
+    status: false,
+  },
+  argTypes: {
+    status: {
+      description: "Fill the marker with a solid colour.",
+      control: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    content: {
+      description: "Content.",
+      control: "text",
+      type: {
+        name: "string",
+        required: true,
+      },
+      table: {
+        type: { summary: "WysiwygText" },
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<StepsItemType>
+
+export const StepItem: Story = {}
+
+export const Filled: Story = {
+  args: {
+    status: true,
+  },
+}

package/src/Component/Steps/Steps.stories.ts

@@ -4,18 +4,16 @@ import StepItem from "./step-item.twig"
 import "./steps.css"
 import { Steps as StepsType, StepsModifier } from "@pnx-mixtape/ids-shape"
 
+/**
+ * Steps create a visually connected group of content displayed in a linear way.
+ */
 const meta: Meta<StepsType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
-  argTypes: {
-    modifiers: {
-      options: Object.values(StepsModifier),
-      control: "multi-select",
-    },
-    fill: { control: "boolean" },
-    counters: { control: "boolean" },
-  },
   args: {
+    modifiers: [StepsModifier.LIGHT],
+    fill: false,
+    counters: false,
     items: [
       StepItem({
         content:
@@ -31,6 +29,43 @@ const meta: Meta<StepsType> = {
       }),
     ],
   },
+  argTypes: {
+    modifiers: {
+      description: "Change the colour of the line and marker.",
+      options: Object.values(StepsModifier),
+      control: "check",
+      type: "string",
+      table: {
+        defaultValue: { summary: StepsModifier.LIGHT },
+      },
+    },
+    fill: {
+      description: "Fill the marker with a solid colour.",
+      control: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    counters: {
+      description: "Add a counter into the marker.",
+      control: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    items: {
+      description:
+        "A list of [StepItem](/?path=/docs/component-steps-stepitem--docs) objects, where `status` fills in it's individual marker only.",
+      type: {
+        name: "other",
+        required: true,
+        value: "array",
+      },
+      table: {
+        type: { summary: "StepItem[]" },
+      },
+    },
+  },
 }
 
 export default meta
@@ -38,21 +73,36 @@ type Story = StoryObj<StepsType>
 
 export const Steps: Story = {}
 
+/**
+ * Add a counter to each step.
+ */
 export const Counters: Story = {
   args: {
     counters: true,
   },
 }
-export const Progress: Story = {
+
+/**
+ * All steps can be filled at once.
+ */
+export const Filled: Story = {
+  args: {
+    fill: true,
+  },
+}
+
+/**
+ * Setting an individual StepItem `status=true` can help highlight a particular item.
+ */
+export const Highlighted: Story = {
   args: {
-    modifiers: [StepsModifier.SUPPLEMENTARY],
     items: [
       StepItem({
-        status: true,
         content:
           "Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.",
       }),
       StepItem({
+        status: true,
         content:
           "Soul music ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem.",
       }),
@@ -64,9 +114,11 @@ export const Progress: Story = {
   },
 }
 
-export const ProgressCounters: Story = {
+/**
+ * Combining individual StepItem `status=true` with counters can help show progress.
+ */
+export const Progress: Story = {
   args: {
-    modifiers: [StepsModifier.DARK],
     counters: true,
     items: [
       StepItem({
@@ -86,3 +138,20 @@ export const ProgressCounters: Story = {
     ],
   },
 }
+
+/**
+ * Brand colours can be applied to steps.
+ */
+export const Primary: Story = {
+  args: {
+    ...Progress.args,
+    modifiers: [StepsModifier.DARK],
+  },
+}
+
+export const Accent: Story = {
+  args: {
+    ...Progress.args,
+    modifiers: [StepsModifier.SUPPLEMENTARY],
+  },
+}

package/src/Component/Steps/__snapshots__/StepItem.stories.ts.snap

@@ -0,0 +1,31 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`Component/Steps/StepItem Filled smoke-test 1`] = `
+<div class="mx-page default">
+  <div class="mx-steps__panel mx-steps--fill">
+    <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
+      <h2>
+        Funk
+      </h2>
+      <p>
+        Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
+      </p>
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Component/Steps/StepItem StepItem smoke-test 1`] = `
+<div class="mx-page default">
+  <div class="mx-steps__panel">
+    <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
+      <h2>
+        Funk
+      </h2>
+      <p>
+        Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
+      </p>
+    </div>
+  </div>
+</div>
+`;