@pnx-mixtape/mxds 0.0.30 → 0.1.0-rc.1

package/src/Component/Tag/TagItem.stories.ts

@@ -0,0 +1,101 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import Component from "./tag-item.twig"
+import "./tag.css"
+import { TagTypes } from "@pnx-mixtape/ids-shape"
+
+type TagItemType = {
+  type: TagTypes
+  item:
+    | string
+    | { title: string; href: string }
+    | { label: string; id: string; name: string; value: string; checked?: boolean }
+  dismissible?: boolean
+  removeLabel?: string
+}
+
+/**
+ * A single tag, rendered inside a [Tag](/?path=/docs/component-tag--docs) list.
+ * The shape of `item` depends on `type`.
+ */
+const meta: Meta<TagItemType> = {
+  tags: ["autodocs", "ids-mvp", "no-snapshot"],
+  component: Component,
+  args: {
+    type: TagTypes.TEXT,
+    item: "Music",
+  },
+  argTypes: {
+    type: {
+      description:
+        "Define the type of the tag. Changing the type also requires a different `item` shape.",
+      options: Object.values(TagTypes),
+      control: "radio",
+      table: {
+        defaultValue: { summary: TagTypes.TEXT },
+        type: { summary: "enum" },
+      },
+    },
+    item: {
+      description: "The tag's data, shape depends on `type`.",
+      table: {
+        type: {
+          summary:
+            "string | { title: string, href: string } | { label: string, id: string, name: string, value: string }",
+        },
+      },
+    },
+    dismissible: {
+      description:
+        "When true, plain (text) tags render a remove button. Wire up removal behaviour in the consuming app.",
+      control: "boolean",
+    },
+  },
+  render: args => {
+    return `<ul class="mx-tags">${Component({ ...args })}</ul>`
+  },
+}
+
+export default meta
+type Story = StoryObj<TagItemType>
+
+export const TagItem: Story = {}
+
+/**
+ * Tags can be links.
+ */
+export const Link: Story = {
+  args: {
+    type: TagTypes.LINK,
+    item: {
+      title: "Music",
+      href: "#0",
+    },
+  },
+}
+
+/**
+ * Plain tags can be made dismissible, rendering a remove button. The consuming
+ * application is responsible for wiring up the removal behaviour.
+ */
+export const Dismissible: Story = {
+  args: {
+    type: TagTypes.TEXT,
+    item: "Music",
+    dismissible: true,
+  },
+}
+
+/**
+ * Tags can also be checkboxes, often used for filters.
+ */
+export const Checkbox: Story = {
+  args: {
+    type: TagTypes.CHECKBOX,
+    item: {
+      label: "Music",
+      id: "music",
+      name: "tag",
+      value: "music",
+    },
+  },
+}

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

@@ -3,44 +3,75 @@
 exports[`Checkbox 1`] = `
 "
 <ul class="mx-tags">
-      <li>
-                  <div class="mx-tag">
-            <input type="checkbox" id="music" name="tag" value="music">
-            <label for="music">Music</label>
-          </div>
-            </li>
-      <li>
-                  <div class="mx-tag">
-            <input type="checkbox" id="news" name="tag" value="news">
-            <label for="news">News</label>
-          </div>
-            </li>
-  </ul>
+  <li>
+          <div class="mx-tag">
+        <input type="checkbox" id="music" name="tag" value="music">
+        <label for="music">Music</label>
+      </div>
+    </li>
+<li>
+          <div class="mx-tag">
+        <input type="checkbox" id="news" name="tag" value="news">
+        <label for="news">News</label>
+      </div>
+    </li>
+
+</ul>
+"
+`;
+
+exports[`Dismissible 1`] = `
+"
+<ul class="mx-tags">
+  <li>
+            <span class="mx-tag mx-tag--dismissible">
+          Music
+                      <button type="button" class="mx-tag__remove mx-icon mx-icon--only mx-icon--close">
+              <span class="sr-only">Remove</span>
+            </button>
+                  </span>
+    </li>
+<li>
+            <span class="mx-tag mx-tag--dismissible">
+          News
+                      <button type="button" class="mx-tag__remove mx-icon mx-icon--only mx-icon--close">
+              <span class="sr-only">Remove</span>
+            </button>
+                  </span>
+    </li>
+
+</ul>
 "
 `;
 
 exports[`Link 1`] = `
 "
 <ul class="mx-tags">
-      <li>
-                    <a class="mx-tag" href="#0">Music</a>
-            </li>
-      <li>
-                    <a class="mx-tag" href="#0">News</a>
-            </li>
-  </ul>
+  <li>
+            <a class="mx-tag" href="#0">Music</a>
+    </li>
+<li>
+            <a class="mx-tag" href="#0">News</a>
+    </li>
+
+</ul>
 "
 `;
 
 exports[`Tag 1`] = `
 "
 <ul class="mx-tags">
-      <li>
-                    <span class="mx-tag">Music</span>
-            </li>
-      <li>
-                    <span class="mx-tag">News</span>
-            </li>
-  </ul>
+  <li>
+            <span class="mx-tag">
+          Music
+                  </span>
+    </li>
+<li>
+            <span class="mx-tag">
+          News
+                  </span>
+    </li>
+
+</ul>
 "
 `;

package/src/Component/Tag/__snapshots__/TagItem.stories.ts.snap

@@ -0,0 +1,39 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Checkbox 1`] = `
+"<li>
+          <div class="mx-tag">
+        <input type="checkbox" id="music" name="tag" value="music">
+        <label for="music">Music</label>
+      </div>
+    </li>
+"
+`;
+
+exports[`Dismissible 1`] = `
+"<li>
+            <span class="mx-tag mx-tag--dismissible">
+          Music
+                      <button type="button" class="mx-tag__remove mx-icon mx-icon--only mx-icon--close">
+              <span class="sr-only">Remove</span>
+            </button>
+                  </span>
+    </li>
+"
+`;
+
+exports[`Link 1`] = `
+"<li>
+            <a class="mx-tag" href="#0">Music</a>
+    </li>
+"
+`;
+
+exports[`Tag Item 1`] = `
+"<li>
+            <span class="mx-tag">
+          Music
+                  </span>
+    </li>
+"
+`;

package/src/Component/Tag/tag-item.twig

@@ -0,0 +1,25 @@
+{% set tagClasses = ['mx-tag', dismissible ? 'mx-tag--dismissible' : null] %}
+{% set tagAttributes = (tagAttributes ?? create_attribute()).addClass(tagClasses) %}
+<li>
+    {% if type == "link" %}
+        <a{{ tagAttributes}} href="{{ item.href }}">{{ item.title }}</a>
+    {% elseif type == "checkbox" %}
+      <div{{ tagAttributes }}>
+        <input type="checkbox"
+               id="{{ item.id }}"
+               name="{{ item.name }}"
+               value="{{ item.value }}"
+            {% if item.checked %} checked{% endif %}>
+        <label for="{{ item.id }}">{{ item.label }}</label>
+      </div>
+    {% else %}
+        <span{{ tagAttributes }}>
+          {{ item }}
+          {% if dismissible %}
+            <button type="button" class="mx-tag__remove mx-icon mx-icon--only mx-icon--close">
+              <span class="sr-only">{{ removeLabel|default('Remove') }}</span>
+            </button>
+          {% endif %}
+        </span>
+    {% endif %}
+</li>

package/src/Component/Tag/tag.css

@@ -3,6 +3,7 @@
  */
 
 @layer design-system.components {
+  /* @public --tag-background --tag-foreground --tag-font-size --tags-gap */
   .mx-tag {
     display: inline-flex;
     inline-size: fit-content;
@@ -16,7 +17,8 @@
     border-radius: var(--border-radius);
     border: var(--line-width, 1px) solid var(--line-colour, currentcolor);
     text-decoration: none;
-    overflow: hidden;
+    overflow: clip;
+    overflow-clip-margin: var(--spacing-xxxs);
 
     &:has(input:focus) {
       outline: var(--outline-size, 2px) var(--outline-style, solid)
@@ -45,6 +47,35 @@
     }
   }
 
+  .mx-tag--dismissible {
+    align-items: center;
+    gap: var(--tag-remove-gap, var(--spacing-xxxs));
+    padding-inline-end: var(--tag-end-spacing, var(--spacing-xxxxs));
+  }
+
+  .mx-tag__remove {
+    --icon-size: var(--spacing-m);
+
+    display: inline-flex;
+    align-items: center;
+    padding: 0;
+    background: none;
+    border: 0;
+    color: inherit;
+    cursor: pointer;
+    border-radius: var(--border-radius);
+
+    &:focus-visible {
+      outline: var(--outline-size, 2px) var(--outline-style, solid)
+        var(--outline-color, currentcolor);
+      outline-offset: var(--outline-offset, -3px);
+    }
+
+    &::before {
+      --icon-size: var(--spacing-xxs);
+    }
+  }
+
   .mx-tags {
     padding-inline: 0;
     list-style: none;

package/src/Component/Tag/tags.twig

@@ -1,23 +1,5 @@
 {% set attributes = (attributes ?? create_attribute()).addClass('mx-tags') %}
-{% set tagAttributes = (tagAttributes ?? create_attribute()).addClass('mx-tag') %}
 
 <ul{{ attributes }}>
-  {% for item in items %}
-    <li>
-        {% if type == "link" %}
-            <a{{ tagAttributes}} href="{{ item.href }}">{{ item.title }}</a>
-        {% elseif type == "checkbox" %}
-          <div{{ tagAttributes }}>
-            <input type="checkbox"
-                   id="{{ item.id }}"
-                   name="{{ item.name }}"
-                   value="{{ item.value }}"
-                {% if item.checked %} checked{% endif %}>
-            <label for="{{ item.id }}">{{ item.label }}</label>
-          </div>
-        {% else %}
-            <span{{ tagAttributes }}>{{ item }}</span>
-        {% endif %}
-    </li>
-  {% endfor %}
+  {{ items }}
 </ul>

package/src/Component/UtilityList/Elements/UtilityList.ts

@@ -8,6 +8,7 @@ export default class UtilityList extends HTMLElement {
   controller: AbortController
   copyOriginalText?: string
   copyOriginalIcon?: string
+  timeout?: ReturnType<typeof setTimeout>
 
   constructor() {
     super()
@@ -49,6 +50,7 @@ export default class UtilityList extends HTMLElement {
 
   disconnectedCallback(): void {
     this.controller.abort()
+    clearTimeout(this.timeout)
   }
 
   handleCopy = async (): Promise<void> => {
@@ -62,13 +64,15 @@ export default class UtilityList extends HTMLElement {
         .then(() => {
           this.copyLabel.textContent = "Copied!"
           this.copyIcon.classList.replace(this.copyOriginalIcon, "mx-icon--tick")
-          setTimeout(() => {
+          this.timeout = setTimeout(() => {
             this.copyLabel.textContent = this.copyOriginalText
             this.copyIcon.classList.replace("mx-icon--tick", this.copyOriginalIcon)
           }, 3000)
         })
     } catch {
-      console.error("Could not copy the url to clipboard")
+      if (process.env.NODE_ENV !== "production")
+        // oxlint-disable-next-line no-console
+        console.error("Could not copy the URL to clipboard")
     }
   }
 

package/src/Component/UtilityList/README.md

@@ -0,0 +1,173 @@
+# UtilityList
+
+A small `<nav>` of page tools — Copy link, Print page, Download PDF, and a Share popover — rendered as an unordered list of icon buttons. Typically used inside a `Masthead` as the header utility nav, or dropped into a page section for per-page tools.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/UtilityList/utility-list.css";
+```
+
+The component relies on a `<mx-utility-list>` custom element for the copy/print/PDF button behaviour. Import the JS alongside the CSS:
+
+```js
+import "@pnx-mixtape/mxds/src/Component/UtilityList/Elements/UtilityList"
+```
+
+The Share option uses the `Popover` component — import its CSS and element too:
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Popover/popover.css"
+import "@pnx-mixtape/mxds/src/Component/Popover/Elements/Popover"
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/UtilityList/utility-list.twig' with {
+  copy: true,
+  print: true,
+  pdf: false,
+  share: social_share_component,
+  horizontal: false,
+} %}
+```
+
+**utility-list.twig props** (`UtilityList` type from `ids-shape`):
+
+| Prop         | Type          | Default              | Description                                                                                                                                          |
+| ------------ | ------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `copy`       | `boolean`     | `false`              | Adds a "Copy link" button. Copies `window.location.href` to the clipboard and swaps the label to "Copied!" for 3 seconds.                            |
+| `print`      | `boolean`     | `false`              | Adds a "Print page" button that calls `window.print()`.                                                                                              |
+| `pdf`        | `boolean`     | `false`              | Adds a "Download PDF" button. By default also calls `window.print()` — extend the `UtilityList` custom element class to provide real PDF generation. |
+| `share`      | `SocialShare` | —                    | A rendered `SocialShare` component. Shown inside a popover triggered by a "Share this page" button.                                                  |
+| `horizontal` | `boolean`     | `false`              | Renders the list inline (`mx-nav--inline`) instead of stacked.                                                                                       |
+| `background` | `string`      | —                    | Background colour key appended to `mx-background--`, e.g. `reverse`, `alt`, `accent`. Adds vertical padding automatically.                           |
+| `id`         | `string`      | `utility-list-share` | Id used for the share popover anchor (`id` / `popovertarget` / `anchor-name`).                                                                       |
+| `attributes` | `Attribute`   | —                    | Drupal-style attribute object merged onto the `<nav>`.                                                                                               |
+
+---
+
+## HTML
+
+Minimal working markup. The `data-copy`, `data-print`, and `data-pdf` attributes are how the custom element wires up click handlers — do not remove them.
+
+```html
+<mx-utility-list>
+  <nav class="mx-utility-list mx-nav" aria-label="Page tools">
+    <ul>
+      <li>
+        <button data-copy type="button" class="mx-button mx-button--small mx-button--light">
+          <span class="mx-icon mx-icon--link"></span>
+          <span data-copy-label class="mx-utility-list__label">Copy link</span>
+        </button>
+      </li>
+      <li>
+        <button data-print type="button" class="mx-button mx-button--small mx-button--light">
+          <span class="mx-icon mx-icon--print"></span>
+          <span class="mx-utility-list__label">Print page</span>
+        </button>
+      </li>
+    </ul>
+  </nav>
+</mx-utility-list>
+```
+
+### Horizontal (inline) layout
+
+Add `mx-nav--inline` to render the buttons in a single row without gaps between them — suitable for placement inside a `Masthead`.
+
+```html
+<mx-utility-list>
+  <nav class="mx-utility-list mx-nav mx-nav--inline" aria-label="Page tools">
+    <ul>
+      ...
+    </ul>
+  </nav>
+</mx-utility-list>
+```
+
+### With a Share popover
+
+The Share entry is a `<mx-popover>` trigger opening a `SocialShare` panel anchored to the button.
+
+```html
+<li>
+  <mx-popover>
+    <button
+      type="button"
+      id="utility-list-share-target"
+      class="mx-popover__trigger mx-button mx-button--small mx-button--light"
+      popovertarget="utility-list-share"
+      style="anchor-name: --utility-list-share"
+    >
+      <span class="mx-icon mx-icon--share"></span>
+      <span class="mx-utility-list__label">Share this page</span>
+      <span class="mx-icon mx-icon--chevron-down"></span>
+    </button>
+    <div
+      class="mx-popover mx-utility-list__share"
+      id="utility-list-share"
+      aria-describedby="utility-list-share-target"
+      style="position-anchor: --utility-list-share"
+      data-placement="bottom"
+      popover
+    >
+      <!-- SocialShare markup -->
+    </div>
+  </mx-popover>
+</li>
+```
+
+---
+
+## React
+
+No React component is shipped for UtilityList — use the Twig template or plain HTML.
+
+---
+
+## Modifiers
+
+| Class                    | Source                | Visual intent                                                                                       |
+| ------------------------ | --------------------- | --------------------------------------------------------------------------------------------------- |
+| `mx-utility-list`        | base                  | Sets the list gap via `--nav-gap`.                                                                  |
+| `mx-nav`                 | base                  | Shared nav list reset (flex list, unstyled).                                                        |
+| `mx-nav--inline`         | `horizontal: true`    | Renders buttons in a single row with `--inline-nav-gap` (default `0`).                              |
+| `mx-background--{key}`   | `background: '{key}'` | Applies a background colour; triggers `padding-block: var(--spacing-xs)`.                           |
+| `mx-utility-list__label` | base                  | Button text span — hidden or styled by the `mx-button--light` variant rules.                        |
+| `mx-utility-list__share` | base                  | Applied to the share popover panel — sets `min-inline-size: fit-content` and overrides link colour. |
+
+The component does not define its own enum in `ids-shape`. `background` accepts any value the `mx-background--*` modifier set supports (see `BackgroundStyles` / `Backgrounds` in the design system).
+
+---
+
+## Accessibility
+
+- Rendered as a `<nav aria-label="Page tools">` wrapping a `<ul>` — screen readers announce it as a navigation landmark with a clear purpose. Change the label if the list is used for something other than page tools.
+- Each action is a semantic `<button type="button">`, not an `<a>` — they trigger in-page behaviour, not navigation.
+- Icons are decorative spans (`mx-icon`) with no `aria-hidden` attribute in the template, but the visible text label (`.mx-utility-list__label`) carries the accessible name. Do not remove the label spans.
+- When a copy succeeds, only the visible label changes to "Copied!"; there is no live region announcement. Add `aria-live="polite"` to the label span if you need screen reader confirmation.
+- The Share popover uses the native `popover` attribute plus CSS anchor positioning. The trigger is `aria-describedby` the popover panel so the popover content is associated with the button.
+- Before the `mx-utility-list` custom element upgrades, the copy/print/PDF buttons are visually dimmed (`opacity: 0.7`) and `pointer-events: none` — avoids a non-functional button flash. The Share button stays interactive because its behaviour is native popover, not JS.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-utility-list {
+  --nav-gap: var(--spacing-xs); /* gap between list items (stacked) */
+  --inline-nav-gap: 0; /* gap between items when .mx-nav--inline */
+}
+
+.mx-utility-list__share {
+  --utility-link-color: var(--colour-link); /* link colour inside the share popover */
+}
+```
+
+---
+
+→ Used in context: `mockups/ArticlePage.stories.ts:17`

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

@@ -28,13 +28,13 @@ exports[`Horizontal 1`] = `
               
 <nav class="mx-social-share flex gap--s" aria-label="Social share buttons">
   
-          <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="https://www.linkedin.com/shareArticle" target="_blank">
+          <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="https://www.linkedin.com/shareArticle" target="_blank" rel="noopener noreferrer">
       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">
+        <a class="mx-link mx-icon mx-icon--only mx-icon--facebook" href="https://www.facebook.com/sharer.php" target="_blank" rel="noopener noreferrer">
       Share to Facebook
     </a>
-        <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="mailto:" target="_blank">
+        <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="mailto:" target="_blank" rel="noopener noreferrer">
       Share via email
     </a>
   </nav>
@@ -82,13 +82,13 @@ exports[`PDF 1`] = `
               
 <nav class="mx-social-share flex gap--s" aria-label="Social share buttons">
   
-          <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="https://www.linkedin.com/shareArticle" target="_blank">
+          <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="https://www.linkedin.com/shareArticle" target="_blank" rel="noopener noreferrer">
       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">
+        <a class="mx-link mx-icon mx-icon--only mx-icon--facebook" href="https://www.facebook.com/sharer.php" target="_blank" rel="noopener noreferrer">
       Share to Facebook
     </a>
-        <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="mailto:" target="_blank">
+        <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="mailto:" target="_blank" rel="noopener noreferrer">
       Share via email
     </a>
   </nav>
@@ -130,13 +130,13 @@ exports[`Utility List 1`] = `
               
 <nav class="mx-social-share flex gap--s" aria-label="Social share buttons">
   
-          <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="https://www.linkedin.com/shareArticle" target="_blank">
+          <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="https://www.linkedin.com/shareArticle" target="_blank" rel="noopener noreferrer">
       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">
+        <a class="mx-link mx-icon mx-icon--only mx-icon--facebook" href="https://www.facebook.com/sharer.php" target="_blank" rel="noopener noreferrer">
       Share to Facebook
     </a>
-        <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="mailto:" target="_blank">
+        <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="mailto:" target="_blank" rel="noopener noreferrer">
       Share via email
     </a>
   </nav>