@pnx-mixtape/mxds 0.0.29 → 0.1.0-rc.0

package/src/Component/Tabs/Tabs.stories.tsx

@@ -1,4 +1,5 @@
 import { Meta, StoryObj } from "@storybook/react-vite"
+import { expect } from "storybook/test"
 import { Fragment } from "react"
 import Component from "./Tabs"
 import TabDropMenu from "./Components/TabDropMenu"
@@ -14,9 +15,27 @@ import { Page } from "../../../.storybook-react/decorators"
 const defaultChildren = (
   <Fragment>
     <TabDropMenu>
-      <DropMenuItem id="tab-1" label="Tab 1" aria-controls="tab-1" role="tab" />
-      <DropMenuItem id="tab-2" label="Tab 2" aria-controls="tab-2" role="tab" />
-      <DropMenuItem id="tab-3" label="Tab 3" aria-controls="tab-3" role="tab" />
+      <DropMenuItem
+        id="tab-1"
+        label="Tab 1"
+        aria-controls="tab-1"
+        role="tab"
+        aria-selected={true}
+      />
+      <DropMenuItem
+        id="tab-2"
+        label="Tab 2"
+        aria-controls="tab-2"
+        role="tab"
+        aria-selected={false}
+      />
+      <DropMenuItem
+        id="tab-3"
+        label="Tab 3"
+        aria-controls="tab-3"
+        role="tab"
+        aria-selected={false}
+      />
     </TabDropMenu>
     <TabList>
       <Tab id="tab-1">Tab 1</Tab>
@@ -34,6 +53,7 @@ const defaultChildren = (
     </TabPanel>
   </Fragment>
 )
+const panel = (id: string): HTMLElement => document.getElementById(id) as HTMLElement
 
 const meta: Meta<typeof Component> = {
   tags: ["autodocs"],
@@ -50,4 +70,47 @@ const meta: Meta<typeof Component> = {
 }
 
 export default meta
-export const Default: StoryObj<typeof meta> = {}
+export const Default: StoryObj<typeof meta> = {
+  play: async ({ canvas, userEvent, step }) => {
+    const tab1 = canvas.getByRole("tab", { name: "Tab 1" })
+    const tab2 = canvas.getByRole("tab", { name: "Tab 2" })
+    const tab3 = canvas.getByRole("tab", { name: "Tab 3" })
+
+    await step("Tab 1 starts selected", async () => {
+      await expect(tab1).toHaveAttribute("aria-selected", "true")
+      await expect(panel("tab-1")).not.toHaveAttribute("inert")
+      await expect(panel("tab-2")).toHaveAttribute("inert")
+    })
+
+    await step("Click selects a tab", async () => {
+      await userEvent.click(tab2)
+      await expect(tab2).toHaveAttribute("aria-selected", "true")
+      await expect(tab1).toHaveAttribute("aria-selected", "false")
+      await expect(panel("tab-2")).not.toHaveAttribute("inert")
+      await expect(panel("tab-1")).toHaveAttribute("inert")
+    })
+
+    await step("ArrowRight/ArrowLeft move focus, with wraparound", async () => {
+      tab2.focus()
+      await userEvent.keyboard("{ArrowRight}")
+      await expect(tab3).toHaveFocus()
+      await userEvent.keyboard("{ArrowRight}")
+      await expect(tab1).toHaveFocus()
+      await userEvent.keyboard("{ArrowLeft}")
+      await expect(tab3).toHaveFocus()
+    })
+
+    await step("Home/End jump to first/last tab", async () => {
+      await userEvent.keyboard("{Home}")
+      await expect(tab1).toHaveFocus()
+      await userEvent.keyboard("{End}")
+      await expect(tab3).toHaveFocus()
+    })
+
+    await step("Reset: reselect Tab 1 and clear the ?tab= param", async () => {
+      await userEvent.click(tab1)
+      await expect(tab1).toHaveAttribute("aria-selected", "true")
+      window.history.replaceState({}, "", window.location.pathname)
+    })
+  },
+}

package/src/Component/Tabs/Tabs.tsx

@@ -4,12 +4,14 @@ import React, {
   Context,
   Dispatch,
   SetStateAction,
+  RefObject,
   createContext,
   use,
   useState,
   useEffect,
   useMemo,
   useId,
+  useRef,
   MouseEvent,
   KeyboardEvent,
 } from "react"
@@ -22,6 +24,7 @@ type TabContextValues = {
   setActiveTab: Dispatch<SetStateAction<string>>
   activeTabLabel: string
   tabsId: string
+  tabListRef: RefObject<HTMLDivElement>
 }
 
 const TabContext: Context<TabContextValues> = createContext<TabContextValues>(null)
@@ -36,7 +39,9 @@ type TabsProps = PropsWithChildren & {
 const Tabs = ({ children, active, modifier, id }: TabsProps): JSX.Element => {
   const [activeTab, setActiveTab] = useState<string>(active)
   const [activeTabLabel, setActiveTabLabel] = useState<string>("Tabs")
-  const tabsId: string = id || useId()
+  const tabListRef = useRef<HTMLDivElement>(null)
+  const rId = useId()
+  const tabsId: string = id || rId
 
   const handleClick = (event: MouseEvent | KeyboardEvent, key: string): void => {
     setActiveTab(key)
@@ -54,6 +59,7 @@ const Tabs = ({ children, active, modifier, id }: TabsProps): JSX.Element => {
     const tabParam = new URLSearchParams(window.location.search).get("tab")
     if (tabParam && tabParam !== activeTab) {
       // eslint-disable-next-line @eslint-react/hooks-extra/no-direct-set-state-in-use-effect
+      // oxlint-disable-next-line react/set-state-in-effect -- synchronizes state with the URL, an external system
       setActiveTab(tabParam)
     }
     const label: string = document.querySelector(`[aria-controls="${activeTab}"]`)?.textContent
@@ -62,13 +68,15 @@ const Tabs = ({ children, active, modifier, id }: TabsProps): JSX.Element => {
   }, [activeTab])
 
   const values = useMemo<TabContextValues>(
-    () => ({ activeTab, setActiveTab, activeTabLabel, tabsId }),
-    [activeTab, activeTabLabel, tabsId],
+    () => ({ activeTab, setActiveTab, activeTabLabel, tabsId, tabListRef }),
+    [activeTab, activeTabLabel, tabsId, tabListRef],
   )
 
+  const selectedItem = useMemo(() => [activeTab], [activeTab])
+
   return (
     <TabContext value={values}>
-      <DropMenuProvider id={tabsId} onClick={handleClick} selectedItem={[activeTab]}>
+      <DropMenuProvider id={tabsId} onClick={handleClick} selectedItem={selectedItem}>
         <div
           className={classNames("mx-tabs", {
             [`mx-tabs--${modifier}`]: modifier,

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

@@ -3,20 +3,18 @@
 exports[`Tabs 1`] = `
 "
 
-<mx-tabs class="mx-tabs mx-tabs--lined" id="tab-example"><mx-dropmenu closeonclick="true"><button id="unique-3" class="mx-popover__trigger mx-button mx-icon mx-icon--chevron-down mx-icon--end" popovertarget="tab-example" style="anchor-name: --tab-example" hidden="">Funk</button><div class="mx-popover mx-drop-menu" id="tab-example" aria-describedby="unique-0" style="position-anchor: --tab-example" data-placement="bottom-start" popover="" role="tablist"><button type="button" role="tab" aria-controls="unique-1" aria-selected="false">Funk</button><button type="button" role="tab" aria-controls="unique-2" aria-selected="false">Soul</button><button type="button" role="tab" aria-controls="unique-3" aria-selected="false">Motown</button></div></mx-dropmenu><div class="mx-tabs__list" role="tablist"><button type="button" role="tab" aria-controls="unique-4" aria-selected="true" tab-index="0">Funk</button><button type="button" role="tab" aria-controls="unique-5" aria-selected="false" tab-index="-1">Soul</button><button type="button" role="tab" aria-controls="unique-6" aria-selected="false" tab-index="-1">Motown</button></div>
-      <div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-0" data-tab="Funk" role="tabpanel" tabindex="0" aria-label="Funk">
+<mx-tabs class="mx-tabs mx-tabs--lined" id="tab-example"><mx-dropmenu closeonclick="true"><button id="unique-3" class="mx-popover__trigger mx-button mx-icon mx-icon--chevron-down mx-icon--end" popovertarget="tab-example" style="anchor-name: --tab-example" hidden="">Funk</button><div class="mx-popover mx-drop-menu" id="tab-example" aria-describedby="unique-0" style="position-anchor: --tab-example" data-placement="bottom-start" popover="" role="tablist"><button type="button" role="tab" aria-controls="unique-1" aria-selected="false">Funk</button><button type="button" role="tab" aria-controls="unique-2" aria-selected="false">Soul</button><button type="button" role="tab" aria-controls="unique-3" aria-selected="false">Motown</button></div></mx-dropmenu><div class="mx-tabs__list" role="tablist"><button type="button" role="tab" aria-controls="unique-4" aria-selected="true" tabindex="0">Funk</button><button type="button" role="tab" aria-controls="unique-5" aria-selected="false" tabindex="-1">Soul</button><button type="button" role="tab" aria-controls="unique-6" aria-selected="false" tabindex="-1">Motown</button></div>
+  <div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-0" data-tab="Funk" role="tabpanel" tabindex="-1" aria-label="Funk">
   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.
 </div>
-
-      <div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-1" data-tab="Soul" role="tabpanel" tabindex="0" aria-label="Soul" inert="">
+<div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-1" data-tab="Soul" role="tabpanel" tabindex="-1" aria-label="Soul" inert="">
   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.
 </div>
-
-      <div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-2" data-tab="Motown" role="tabpanel" tabindex="0" aria-label="Motown" inert="">
+<div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-2" data-tab="Motown" role="tabpanel" tabindex="-1" aria-label="Motown" inert="">
   Motown lorem 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.
 </div>
 
-  </mx-tabs>
+</mx-tabs>
 "
 `;
 
@@ -25,19 +23,17 @@ exports[`With Heading 1`] = `
 
 <h2>Tabs heading</h2>
 
-<mx-tabs class="mx-tabs mx-tabs--lined" id="tab-example"><mx-dropmenu closeonclick="true"><button id="unique-3" class="mx-popover__trigger mx-button mx-icon mx-icon--chevron-down mx-icon--end" popovertarget="tab-example" style="anchor-name: --tab-example" hidden="">Funk</button><div class="mx-popover mx-drop-menu" id="tab-example" aria-describedby="unique-0" style="position-anchor: --tab-example" data-placement="bottom-start" popover="" role="tablist"><button type="button" role="tab" aria-controls="unique-1" aria-selected="false">Funk</button><button type="button" role="tab" aria-controls="unique-2" aria-selected="false">Soul</button><button type="button" role="tab" aria-controls="unique-3" aria-selected="false">Motown</button></div></mx-dropmenu><div class="mx-tabs__list" role="tablist"><button type="button" role="tab" aria-controls="unique-4" aria-selected="true" tab-index="0">Funk</button><button type="button" role="tab" aria-controls="unique-5" aria-selected="false" tab-index="-1">Soul</button><button type="button" role="tab" aria-controls="unique-6" aria-selected="false" tab-index="-1">Motown</button></div>
-      <div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-0" data-tab="Funk" role="tabpanel" tabindex="0" aria-label="Funk">
+<mx-tabs class="mx-tabs mx-tabs--lined" id="tab-example"><mx-dropmenu closeonclick="true"><button id="unique-3" class="mx-popover__trigger mx-button mx-icon mx-icon--chevron-down mx-icon--end" popovertarget="tab-example" style="anchor-name: --tab-example" hidden="">Funk</button><div class="mx-popover mx-drop-menu" id="tab-example" aria-describedby="unique-0" style="position-anchor: --tab-example" data-placement="bottom-start" popover="" role="tablist"><button type="button" role="tab" aria-controls="unique-1" aria-selected="false">Funk</button><button type="button" role="tab" aria-controls="unique-2" aria-selected="false">Soul</button><button type="button" role="tab" aria-controls="unique-3" aria-selected="false">Motown</button></div></mx-dropmenu><div class="mx-tabs__list" role="tablist"><button type="button" role="tab" aria-controls="unique-4" aria-selected="true" tabindex="0">Funk</button><button type="button" role="tab" aria-controls="unique-5" aria-selected="false" tabindex="-1">Soul</button><button type="button" role="tab" aria-controls="unique-6" aria-selected="false" tabindex="-1">Motown</button></div>
+  <div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-0" data-tab="Funk" role="tabpanel" tabindex="-1" aria-label="Funk">
   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.
 </div>
-
-      <div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-1" data-tab="Soul" role="tabpanel" tabindex="0" aria-label="Soul" inert="">
+<div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-1" data-tab="Soul" role="tabpanel" tabindex="-1" aria-label="Soul" inert="">
   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.
 </div>
-
-      <div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-2" data-tab="Motown" role="tabpanel" tabindex="0" aria-label="Motown" inert="">
+<div class="mx-tabs__panel mx-vertical-flow mx-container" id="unique-2" data-tab="Motown" role="tabpanel" tabindex="-1" aria-label="Motown" inert="">
   Motown lorem 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.
 </div>
 
-  </mx-tabs>
+</mx-tabs>
 "
 `;

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

@@ -1,3 +1,3 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Default 1`] = `"<div class="mx-tabs"><div class="mobile-only"><button id="tabs-storybook-target" type="button" class="mx-button mx-icon mx-icon--chevron-down mx-icon--end mx-drop-menu__trigger" popovertarget="tabs-storybook" style="anchor-name: --drop-menu-tabs-storybook;">Tab 1</button><div id="tabs-storybook" class="mx-drop-menu" popover="" aria-labelledby="tabs-storybook-target" aria-describedby="tabs-storybook-description" role="tablist" style="position-anchor: --drop-menu-tabs-storybook;"><div id="tabs-storybook-description" class="sr-only">Results will update when you make a selection. Press escape to close.</div><button type="button" data-id="tab-1" aria-checked="true" role="tab" aria-controls="tab-1">Tab 1</button><button type="button" data-id="tab-2" aria-checked="false" role="tab" aria-controls="tab-2">Tab 2</button><button type="button" data-id="tab-3" aria-checked="false" role="tab" aria-controls="tab-3">Tab 3</button></div></div><div class="mx-tabs__list desktop-only" role="tablist"><button id="tab-1-button" aria-controls="tab-1" role="tab" aria-selected="true" tabindex="0" type="button">Tab 1</button><button id="tab-2-button" aria-controls="tab-2" role="tab" aria-selected="false" tabindex="-1" type="button">Tab 2</button><button id="tab-3-button" aria-controls="tab-3" role="tab" aria-selected="false" tabindex="-1" type="button">Tab 3</button></div><div id="tab-1" class="mx-tabs__panel mx-vertical-flow mx-section--l" aria-labelledby="tab-1-button" role="tabpanel" tabindex="0"><p>This is tab 1</p></div><div id="tab-2" class="mx-tabs__panel mx-vertical-flow mx-section--l" inert="" aria-labelledby="tab-2-button" role="tabpanel" tabindex="0"><p>This is tab 2</p></div><div id="tab-3" class="mx-tabs__panel mx-vertical-flow mx-section--l" inert="" aria-labelledby="tab-3-button" role="tabpanel" tabindex="0"><p>This is tab 3</p></div></div>"`;
+exports[`Default 1`] = `"<div class="mx-tabs"><div class="mobile-only"><button id="tabs-storybook-target" type="button" class="mx-button mx-icon mx-icon--chevron-down mx-icon--end mx-popover__trigger" popovertarget="tabs-storybook" style="anchor-name: --drop-menu-tabs-storybook;">Tab 1</button><div id="tabs-storybook" class="mx-popover mx-drop-menu" popover="" aria-labelledby="tabs-storybook-target" aria-describedby="tabs-storybook-description" role="tablist" style="position-anchor: --drop-menu-tabs-storybook;"><div id="tabs-storybook-description" class="sr-only">Results will update when you make a selection. Press escape to close.</div><span data-focus-scope-start="true" hidden=""></span><button type="button" data-id="tab-1" aria-checked="true" role="tab" aria-controls="tab-1" aria-selected="true">Tab 1</button><button type="button" data-id="tab-2" aria-checked="false" role="tab" aria-controls="tab-2" aria-selected="false">Tab 2</button><button type="button" data-id="tab-3" aria-checked="false" role="tab" aria-controls="tab-3" aria-selected="false">Tab 3</button><span data-focus-scope-end="true" hidden=""></span></div></div><div class="mx-tabs__list desktop-only" role="tablist"><span data-focus-scope-start="true" hidden=""></span><button id="tab-1-button" aria-controls="tab-1" role="tab" aria-selected="true" tabindex="0" type="button">Tab 1</button><button id="tab-2-button" aria-controls="tab-2" role="tab" aria-selected="false" tabindex="-1" type="button">Tab 2</button><button id="tab-3-button" aria-controls="tab-3" role="tab" aria-selected="false" tabindex="-1" type="button">Tab 3</button><span data-focus-scope-end="true" hidden=""></span></div><div id="tab-1" class="mx-tabs__panel mx-vertical-flow mx-section--l" aria-labelledby="tab-1-button" role="tabpanel" tabindex="0"><p>This is tab 1</p></div><div id="tab-2" class="mx-tabs__panel mx-vertical-flow mx-section--l" aria-labelledby="tab-2-button" role="tabpanel" tabindex="0" inert=""><p>This is tab 2</p></div><div id="tab-3" class="mx-tabs__panel mx-vertical-flow mx-section--l" inert="" aria-labelledby="tab-3-button" role="tabpanel" tabindex="0"><p>This is tab 3</p></div></div>"`;

package/src/Component/Tabs/tabs.css

@@ -45,6 +45,7 @@
       padding-inline: var(--horizontal-padding, var(--spacing-m));
       background-color: var(--tab-background, var(--background, var(--colour-background)));
       color: var(--tab-foreground, var(--foreground, var(--colour-foreground)));
+      font-size: var(--tab-font-size, var(--font-size-xs));
 
       &[aria-selected="true"] {
         background-color: var(--tab-active-background, var(--colour-background-alt));

package/src/Component/Tabs/tabs.twig

@@ -7,7 +7,5 @@
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
 {{ title }}
 <mx-tabs{{ attributes }}{% if id is not empty %} id="{{ id }}"{% endif %}>
-  {% for item in items %}
-    {{ item }}
-  {% endfor %}
+  {{ items }}
 </mx-tabs>

package/src/Component/Tag/README.md

@@ -1,19 +1,208 @@
 # Tag
 
-### How to use
+A small inline label used to categorise content. Renders as plain text metadata, a link to a filtered view, or a checkbox inside a filter form. The `Tags` wrapper lays multiple tags out as a wrapping row.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Component/Tag/tag.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Component/Tag/tag.css";
+```
 
-**Twig**
+---
 
-You can setup a twig namespace in your project if you wish to use the twig files directly.
+## Twig
 
-- Eg: `{% extends '@mixtape/Component/Tab/tag.twig' %}`
+```twig
+{% include '@mixtape/Component/Tag/tags.twig' with {
+  type: 'text',
+  items: ['Music', 'News'],
+} %}
 
-Alternatively copy/paste the file for more control.
+{# Link tags #}
+{% include '@mixtape/Component/Tag/tags.twig' with {
+  type: 'link',
+  items: [
+    { title: 'Music', href: '/category/music' },
+    { title: 'News', href: '/category/news' },
+  ],
+} %}
 
-**JSX Components**
+{# Checkbox tags #}
+{% include '@mixtape/Component/Tag/tags.twig' with {
+  type: 'checkbox',
+  items: [
+    { label: 'Music', id: 'music', name: 'tag', value: 'music' },
+    { label: 'News', id: 'news', name: 'tag', value: 'news', checked: true },
+  ],
+} %}
+```
 
-- JSX import: `import { Tag } from '@pnx-mixtape/mxds/src/react';`
+**tags.twig props** (`Tags` type from `ids-shape`):
+
+| Prop            | Type                                  | Description                                                                                                                                  |
+| --------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`          | `TagTypes`                            | Controls which markup is rendered per item. One of `text`, `link`, `checkbox`. Changing the type also changes the required shape of `items`. |
+| `items`         | `string[] \| Link[] \| FormControl[]` | List of tag items. Shape depends on `type` — see below.                                                                                      |
+| `attributes`    | `Attribute`                           | Extra attributes on the outer `<ul class="mx-tags">`                                                                                         |
+| `tagAttributes` | `Attribute`                           | Extra attributes on each `.mx-tag` element                                                                                                   |
+| `dismissible`   | `boolean`                             | When true, plain (`text`) tags render a remove button (`mx-tag--dismissible`). Wire up removal behaviour in the consuming app.               |
+| `removeLabel`   | `string`                              | Accessible label for the remove button. Defaults to `"Remove"`.                                                                              |
+
+**Item shapes per `type`:**
+
+| `type`     | Item shape                                                                      |
+| ---------- | ------------------------------------------------------------------------------- |
+| `text`     | `string` — the tag label                                                        |
+| `link`     | `{ title: string, href: string }`                                               |
+| `checkbox` | `{ label: string, id: string, name: string, value: string, checked?: boolean }` |
+
+---
+
+## HTML
+
+Minimal working markup for a list of plain text tags:
+
+```html
+<ul class="mx-tags">
+  <li><span class="mx-tag">Music</span></li>
+  <li><span class="mx-tag">News</span></li>
+</ul>
+```
+
+Link tags:
+
+```html
+<ul class="mx-tags">
+  <li><a class="mx-tag" href="/category/music">Music</a></li>
+  <li><a class="mx-tag" href="/category/news">News</a></li>
+</ul>
+```
+
+Checkbox tags (the `<input>` is visually hidden off-screen; the `<label>` is the click target):
+
+```html
+<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" checked />
+      <label for="news">News</label>
+    </div>
+  </li>
+</ul>
+```
+
+---
+
+## React
+
+The React `Tag` component renders a single tag. It is an element-agnostic wrapper — use `as` to change the semantic element. Wrap multiple tags in a `<ul className="mx-tags">` (there is no dedicated `Tags` React component; match the HTML/Twig markup above).
+
+```tsx
+import { Tag } from "@pnx-mixtape/mxds/react"
+import { AsTags } from "@pnx-mixtape/mxds/src/enums"
+
+// Plain text tag (metadata)
+<Tag>Music</Tag>
+
+// Inside a tag list — use as={AsTags.LI} so each tag is a list item
+<ul className="mx-tags">
+  <Tag as={AsTags.LI}>Music</Tag>
+  <Tag as={AsTags.LI}>News</Tag>
+</ul>
+
+// As a link tag (wrap an anchor inside, or use className on a custom element)
+<ul className="mx-tags">
+  <li>
+    <a className="mx-tag" href="/category/music">Music</a>
+  </li>
+  <li>
+    <a className="mx-tag" href="/category/news">News</a>
+  </li>
+</ul>
+
+// As a checkbox tag (inside a filter form)
+<ul className="mx-tags">
+  <li>
+    <div className="mx-tag">
+      <input type="checkbox" id="music" name="tag" value="music" />
+      <label htmlFor="music">Music</label>
+    </div>
+  </li>
+</ul>
+```
+
+**`Tag` props:**
+
+| Prop          | Type         | Default    | Description                                                                                     |
+| ------------- | ------------ | ---------- | ----------------------------------------------------------------------------------------------- |
+| `as`          | `AsTags`     | `div`      | Semantic element for the tag: `div`, `li`, `article`, `aside`, `section`                        |
+| `className`   | `string`     | —          | Extra class on the tag element                                                                  |
+| `children`    | `ReactNode`  | —          | Tag label content                                                                               |
+| `onRemove`    | `() => void` | —          | When set, renders a remove button (`mx-tag--dismissible`). Consumer removes the tag from state. |
+| `removeLabel` | `string`     | `"Remove"` | Accessible label for the remove button                                                          |
+
+> For filter UIs, tag removal can also be handled upstream (e.g. via the checkbox type toggling its checked state, or via the Filters component). Use `onRemove` when you need a self-contained dismissible chip.
+
+---
+
+## Modifiers — `TagTypes` enum
+
+The `type` prop on the Twig template maps to `TagTypes` values from `@pnx-mixtape/ids-shape`. The same base `mx-tag` class is used for all variants — the variant changes the inner element, not the class.
+
+| `TagTypes` value | Element rendered                                                      | Visual intent                                                                                        |
+| ---------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `text`           | `<span class="mx-tag">`                                               | Read-only metadata label (e.g. category shown on a Card)                                             |
+| `link`           | `<a class="mx-tag" href>`                                             | Navigational tag — clicking takes the user to a filtered / category view                             |
+| `checkbox`       | `<div class="mx-tag">` wrapping `<input type="checkbox">` + `<label>` | Toggleable filter tag inside a form; checked state is visually indicated via the primary link colour |
+
+---
+
+## Accessibility
+
+- **Text tags** are plain `<span>` elements — they are metadata, not interactive. Do not add click handlers or `role` attributes; if a tag needs to be clickable, use the `link` or `checkbox` variant.
+- **Link tags** use a real `<a href>`. Ensure the destination makes sense out of context — the visible label is the accessible name, so labels like "Music" should lead to an unambiguous page (e.g. `/category/music`).
+- **Checkbox tags** rely on a native `<input type="checkbox">` paired with a `<label for="…">`. The `<input>` is positioned off-screen (not `display: none`) so it remains focusable and announceable. The whole `.mx-tag` gets a focus outline via `:has(input:focus)` — do not remove this selector.
+- The checked state is communicated by colour alone in the default styling. When rendering checkbox tags in a form, ensure surrounding context (a fieldset legend, heading, or `aria-label`) describes what group of filters the tags belong to.
+- If you need to render a list of tags for assistive-tech as a single labelled group, add `aria-label` (or `aria-labelledby`) to the `<ul class="mx-tags">`:
+
+```html
+<ul class="mx-tags" aria-label="Article categories">
+  ...
+</ul>
+```
+
+- All text is `text-transform: uppercase` via CSS — the underlying DOM text should be written in normal case so screen readers pronounce it correctly.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-tag {
+  --tag-background: var(--colour-background); /* tag fill colour */
+  --tag-foreground: var(--colour-foreground); /* label colour (also border via currentcolor) */
+  --tag-font-size: var(--font-size-xs); /* label font size */
+  --horizontal-padding: var(--spacing-xxxs); /* inline padding */
+  --line-width: 1px; /* border width */
+  --line-colour: currentcolor; /* border colour */
+  --font-weight: var(--font-weight-bold); /* label weight */
+  --line-height: 2; /* controls tag height */
+  --border-radius: 0; /* pill vs square corners */
+}
+
+.mx-tags {
+  --tags-gap: var(--spacing-s); /* gap between tags in the list */
+}
+```
+
+Hover (on `a.mx-tag`) and checked (`:has(input:checked)`) states both set `--tag-foreground` to `--link-colour` (falls back to `--colour-primary`).
+
+---
+
+→ Used in context: `mockups/ArticlePage.stories.ts:16`

package/src/Component/Tag/Tag.figma.ts

@@ -0,0 +1,25 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=65-234
+// source=src/Component/Tag/Tag.tsx
+// component=Tag
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const dismissible = instance.getEnum("Dismissible", { Off: false, On: true })
+
+// Real children — a proper Content SLOT (not a fixed text layer), even though
+// real usage is typically just a short text label.
+const content = instance.getSlot("Content")
+
+// `onRemove` is a callback, not a boolean — but its mere presence is what toggles
+// the dismissible style, so a representative no-op function stands in here.
+const onRemoveProp = dismissible ? " onRemove={() => {}}" : ""
+
+export default {
+  example: figma.code`<Tag${onRemoveProp}>${content}</Tag>`,
+  imports: ['import { Tag } from "@pnx-mixtape/mxds/react"'],
+  id: "tag",
+  metadata: {
+    nestable: true,
+  },
+}

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

@@ -1,5 +1,6 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./tags.twig"
+import TagItem from "./tag-item.twig"
 import "./tag.css"
 import { Tags as TagType, TagTypes } from "@pnx-mixtape/ids-shape"
 
@@ -10,27 +11,14 @@ const meta: Meta<TagType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
-    items: ["Music", "News"],
-    type: TagTypes.TEXT,
+    items: ["Music", "News"].map(item => TagItem({ type: TagTypes.TEXT, item })).join(""),
   },
   argTypes: {
-    type: {
-      description:
-        "Define the type of the tags. Changing the type also requires a different item shape.",
-      options: Object.values(TagTypes),
-      control: "radio",
-      table: {
-        defaultValue: { summary: TagTypes.TEXT },
-        type: { summary: "enum" },
-      },
-    },
     items: {
-      description: "A list of items to use for the tags, which is different for each `type`.",
+      description:
+        "A concatenated string of [TagItem](/?path=/docs/component-tag-tagitem--docs) markup.",
       table: {
-        type: {
-          summary:
-            "string[] | { title: string, href: string }[] | { label: string, id: string, name: string, value: string }[]",
-        },
+        type: { summary: "string" },
       },
     },
   },
@@ -46,7 +34,6 @@ export const Tag: Story = {}
  */
 export const Link: Story = {
   args: {
-    type: TagTypes.LINK,
     items: [
       {
         title: "Music",
@@ -56,7 +43,21 @@ export const Link: Story = {
         title: "News",
         href: "#0",
       },
-    ],
+    ]
+      .map(item => TagItem({ type: TagTypes.LINK, item }))
+      .join(""),
+  },
+}
+
+/**
+ * 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: {
+    items: ["Music", "News"]
+      .map(item => TagItem({ type: TagTypes.TEXT, item, dismissible: true }))
+      .join(""),
   },
 }
 
@@ -65,7 +66,6 @@ export const Link: Story = {
  */
 export const Checkbox: Story = {
   args: {
-    type: TagTypes.CHECKBOX,
     items: [
       {
         label: "Music",
@@ -79,6 +79,8 @@ export const Checkbox: Story = {
         name: "tag",
         value: "news",
       },
-    ],
+    ]
+      .map(item => TagItem({ type: TagTypes.CHECKBOX, item }))
+      .join(""),
   },
 }

package/src/Component/Tag/Tag.tsx

@@ -1,15 +1,41 @@
 import { JSX, PropsWithChildren } from "react"
 import classNames from "classnames"
-import { AsTags } from "../../enums"
+import { AsTags, Icons } from "../../enums"
 
 type TagProps = PropsWithChildren & {
   className?: string
   as?: AsTags
+  /**
+   * When provided, renders a remove button. Called when the button is
+   * activated — the consumer is responsible for removing the tag from state.
+   */
+  onRemove?: () => void
+  /** Accessible label for the remove button. Defaults to "Remove". */
+  removeLabel?: string
 }
 
-const Tag = ({ children, className, as = AsTags.DIV }: TagProps): JSX.Element => {
-  const Tag: JSX.ElementType = `${as}` as unknown as JSX.ElementType
-  return <Tag className={classNames("mx-tag", className)}>{children}</Tag>
+const Tag = ({
+  children,
+  className,
+  as = AsTags.DIV,
+  onRemove,
+  removeLabel = "Remove",
+}: TagProps): JSX.Element => {
+  const TagEl: JSX.ElementType = `${as}` as unknown as JSX.ElementType
+  return (
+    <TagEl className={classNames("mx-tag", { "mx-tag--dismissible": onRemove }, className)}>
+      {children}
+      {onRemove && (
+        <button
+          type="button"
+          className={`mx-tag__remove mx-icon mx-icon--only mx-icon--${Icons.CLOSE}`}
+          onClick={onRemove}
+        >
+          <span className="sr-only">{removeLabel}</span>
+        </button>
+      )}
+    </TagEl>
+  )
 }
 
 export default Tag