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

package/src/Component/SideNavigation/README.md

@@ -0,0 +1,212 @@
+# SideNavigation
+
+A vertical, multi-level navigation rendered as a `<nav>` landmark with a parent page link at the top and a nested list of sibling/child pages below. Designed to live in the aside of content layouts to expose a section's local page tree. Extends the base `.mx-nav` styles from the Navigation component.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/SideNavigation/side-navigation.css";
+```
+
+Depends on the Navigation component's base styles (for `.mx-nav` and sub-list level classes):
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/Navigation/navigation.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/SideNavigation/side-navigation.twig' with {
+  id: 'section-nav',
+  title: 'Section navigation',
+  parent: parent_link,
+  items: menu_tree,
+} %}
+```
+
+`parent` is expected to be a pre-rendered `Link` atom (e.g. the output of `@mixtape/Atom/Link/link.twig`). `items` is a recursive tree of `MenuTree` objects that the template walks via an internal `menutree` macro — each item is rendered as an `<a>` (or plain text if `link.href` is empty) with its children emitted as a nested `<ul>`.
+
+**side-navigation.twig props** (`SideNavigation` type from `ids-shape`):
+
+| Prop         | Type         | Description                                                                                                                              |
+| ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`         | `string`     | Written to `.mx-side-nav__parent` and used as the `<nav>`'s `aria-labelledby` fallback when `title` is empty                             |
+| `title`      | `string`     | `aria-label` for the `<nav>` landmark. Provide a meaningful value so assistive tech can distinguish this nav from the site's primary nav |
+| `parent`     | `Link`       | Pre-rendered Link atom representing the current section's parent page, shown above the list                                              |
+| `items`      | `MenuTree[]` | Recursive menu tree — see shape below                                                                                                    |
+| `attributes` | `Attribute`  | Optional Drupal-style attributes object; the template merges `mx-nav mx-side-nav` onto its classes                                       |
+
+**`MenuTree` shape** (from `@pnx-mixtape/ids-shape`):
+
+| Field          | Type         | Description                                                                                                      |
+| -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `link.title`   | `string`     | Visible label (also rendered as plain text when `link.href` is empty)                                            |
+| `link.href`    | `string`     | Link destination — omit to render the title without an anchor                                                    |
+| `link.current` | `boolean`    | Adds `aria-current="page"` to the `<a>`                                                                          |
+| `items`        | `MenuTree[]` | Optional children — adds `mx-nav__has-subnav` to the parent `<li>` and renders a nested `<ul>` at the next level |
+
+---
+
+## HTML
+
+Minimal working markup:
+
+```html
+<nav class="mx-nav mx-side-nav" aria-label="Section navigation">
+  <div class="mx-side-nav__parent" id="section-nav">
+    <a href="/about">About</a>
+  </div>
+  <ul class="mx-nav__level-1">
+    <li>
+      <a href="/about/news">News</a>
+    </li>
+    <li class="mx-nav__has-subnav">
+      <a href="/about/what-we-do">What we do</a>
+      <ul class="mx-nav__level-2">
+        <li>
+          <a href="/about/what-we-do/events">Events</a>
+        </li>
+        <li class="mx-nav__has-subnav">
+          <a href="/about/what-we-do/who">Who we are</a>
+          <ul class="mx-nav__level-3">
+            <li>
+              <a href="/about/what-we-do/who/team">Our team</a>
+            </li>
+            <li>
+              <a href="/about/what-we-do/who/philosophy" aria-current="page">Our philosophy</a>
+            </li>
+          </ul>
+        </li>
+        <li>
+          <a href="/about/what-we-do/join">Join us</a>
+        </li>
+      </ul>
+    </li>
+    <li>
+      <a href="/about/contact">Contact</a>
+    </li>
+  </ul>
+</nav>
+```
+
+Rules for the markup:
+
+- The parent link sits inside `.mx-side-nav__parent` — it is separated from the list by a heavier divider line and rendered bold.
+- The top list is `mx-nav__level-1`, children are `mx-nav__level-2`, grandchildren are `mx-nav__level-3`. Each level adds more inline-start indent.
+- Any `<li>` that contains a nested `<ul>` must carry `mx-nav__has-subnav`.
+- The current page's `<a>` carries `aria-current="page"` — CSS uses this to bold the label and apply the active background.
+- Sub-lists are **not** collapsed or inert — unlike the dropdown/collapsible navigation, every level is rendered open.
+
+---
+
+## React
+
+Uses a composition pattern — always use `SideNavigationTree` inside `SideNavigation`.
+
+```tsx
+import { SideNavigation, SideNavigationTree, Link } from "@pnx-mixtape/mxds/react"
+import { MenuTree } from "@pnx-mixtape/ids-shape"
+
+const items: MenuTree[] = [
+  { link: { title: "News", href: "/news" } },
+  {
+    link: { title: "What we do", href: "/what-we-do" },
+    items: [
+      { link: { title: "Events", href: "/what-we-do/events" } },
+      { link: { title: "Our philosophy", href: "/what-we-do/philosophy", current: true } },
+    ],
+  },
+  { link: { title: "Contact", href: "/contact" } },
+]
+
+<SideNavigation
+  id="section-nav"
+  title="Section navigation"
+  parent={<Link to="/about">About</Link>}
+>
+  <SideNavigationTree items={items} />
+</SideNavigation>
+```
+
+**`SideNavigation` Props:**
+
+| Prop        | Type        | Required | Description                                                                                                                  |
+| ----------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `parent`    | `ReactNode` | No       | Link/element shown above the list inside `.mx-side-nav__parent`                                                              |
+| `title`     | `string`    | No       | `aria-label` for the `<nav>` landmark. When omitted, falls back to `aria-labelledby` pointing at the parent wrapper          |
+| `id`        | `string`    | No       | `id` on `.mx-side-nav__parent`, also used as the `aria-labelledby` target when `title` is not set. Auto-generated if omitted |
+| `className` | `string`    | No       | Extra class on the `<nav>`                                                                                                   |
+
+**`SideNavigationTree` Props:**
+
+| Prop    | Type         | Required | Description                                                                   |
+| ------- | ------------ | -------- | ----------------------------------------------------------------------------- |
+| `items` | `MenuTree[]` | Yes      | Recursive menu tree — rendered as nested `<ul class="mx-nav__level-N">` lists |
+
+**`MenuTree` shape** (from `@pnx-mixtape/ids-shape`):
+
+| Field          | Type         | Description                                                                  |
+| -------------- | ------------ | ---------------------------------------------------------------------------- |
+| `link.title`   | `string`     | Visible label                                                                |
+| `link.href`    | `string`     | Link destination — omit to render as plain text (no `<a>`)                   |
+| `link.current` | `boolean`    | Adds `aria-current="page"` on the `<a>`                                      |
+| `items`        | `MenuTree[]` | Child items — adds `mx-nav__has-subnav` to the `<li>`, renders a nested list |
+
+---
+
+## Modifiers
+
+SideNavigation uses the base `.mx-nav` class for list reset and the component-specific classes below. There are no variant modifiers — the single layout covers all cases.
+
+| Class                                                     | Applied by                             | Visual intent                                                                                                                        |
+| --------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `mx-nav`                                                  | Always (shared with Navigation)        | Base list reset — no bullets, vertical layout                                                                                        |
+| `mx-side-nav`                                             | Always                                 | Side-nav specific styling: per-item dividers, indent ramp across levels, current-page background                                     |
+| `mx-side-nav__parent`                                     | Always                                 | Parent-page wrapper above the list — bold label, thicker bottom border                                                               |
+| `mx-nav__level-1` / `mx-nav__level-2` / `mx-nav__level-3` | Structural                             | Sub-list nesting level — each level increases `--indent`                                                                             |
+| `mx-nav__has-subnav`                                      | Structural                             | Applied to any `<li>` that contains a child `<ul>`                                                                                   |
+| `mx-nav__toggle`                                          | Structural (inherited from Navigation) | Hidden in side-nav (`display: none`) — the template emits it for markup parity with dropdown nav, but every level is always expanded |
+| `is-active`                                               | Authoring                              | Alternative to `aria-current="page"` for marking the current item — styled identically                                               |
+
+---
+
+## Accessibility
+
+- Renders a `<nav>` landmark with an `aria-label` taken from `title`. Always supply a specific label (e.g. "Section navigation", "About this section") so a screen-reader user can distinguish it from other `<nav>`s on the page.
+- If `title` is empty, the template falls back to `aria-labelledby` pointing at the parent wrapper's `id` — so the parent link's text becomes the nav's accessible name.
+- Uses semantic nested `<ul>` / `<li>` lists, so assistive tech announces list depth and item count at each level.
+- The current page is marked with `aria-current="page"` on the `<a>`. Style-only bolding is a visual reinforcement — the ARIA attribute is what assistive tech announces. Avoid relying on the background/weight alone.
+- Active-trail ancestors (parent items on the path to the current page) are not given `aria-current` — only the exact current page. Apply the `is-active` class if you want to visually mark ancestors with the same active styling.
+- Keyboard navigation: every item is a native `<a>`, so tab order follows source order and no custom key handling is needed. Sub-lists are always visible, so there is no expand/collapse interaction to manage.
+- The `.mx-nav__toggle` button is emitted in the Twig markup for structural parity with the dropdown nav but is hidden via CSS — do not rely on it for any interactive behaviour in this component at this time (future iterations may enable it).
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-side-nav {
+  --line-width: 1px; /* divider between items */
+  --line-colour: var(--colour-border); /* divider colour */
+  --item-spacing: var(--spacing-xxs); /* block padding on each link */
+  --indent: var(--spacing-xxs); /* inline-start padding at level 1 */
+  --nav-active-background: var(--colour-background-alt); /* current-page background */
+  --nav-active-foreground: inherit; /* current-page text colour */
+  --outline-offset: -1px; /* focus-outline offset inside dividers */
+}
+
+.mx-side-nav__parent {
+  --line-width: 2px; /* thicker divider under the parent link */
+  --line-colour: currentcolor;
+  --item-spacing: var(--spacing-xxs);
+}
+```
+
+Level 2 and level 3 sub-lists override `--indent` to step the text further in — at narrow widths with `--spacing-s` / `--spacing-m`, and at the `--global-nav-up` breakpoint with `--spacing-m` / `--spacing-l`.
+
+---
+
+→ Used in context: `mockups/BasicPage.stories.ts:12`

package/src/Component/SideNavigation/SideNavigation.figma.ts

@@ -0,0 +1,18 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=83-385
+// source=src/Component/SideNavigation/SideNavigation.tsx
+// component=SideNavigation
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const parent = instance.getSlot("Parent")
+const content = instance.getSlot("Content")
+
+export default {
+  example: figma.code`<SideNavigation parent={${parent}}>${content}</SideNavigation>`,
+  imports: ['import { SideNavigation } from "@pnx-mixtape/mxds/react"'],
+  id: "side-navigation",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/SideNavigation/SideNavigation.stories.tsx

@@ -0,0 +1,68 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import Component from "./SideNavigation"
+import SideNavigationTree from "./Components/SideNavigationTree"
+import "../Navigation/navigation.css"
+import "./side-navigation.css"
+import { Page } from "../../../.storybook-react/decorators"
+
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  decorators: [Page],
+  component: Component,
+  args: {
+    id: "sidenav-story",
+    title: "Sidebar nav",
+    parent: (
+      <a className="mx-link" href="#">
+        About
+      </a>
+    ),
+    children: (
+      <SideNavigationTree
+        items={[
+          {
+            link: { title: "News", href: "#" },
+          },
+          {
+            link: { title: "What we do", href: "#" },
+            items: [
+              {
+                link: { title: "Events", href: "#" },
+              },
+              {
+                link: { title: "Who we are", href: "#" },
+                items: [
+                  {
+                    link: { title: "Our team", href: "#" },
+                  },
+                  {
+                    link: { title: "Our philosophy", href: "#", current: true },
+                  },
+                  {
+                    link: { title: "Why music?", href: "#" },
+                  },
+                ],
+              },
+              {
+                link: { title: "Join us", href: "#" },
+              },
+              {
+                link: { title: "Careers", href: "#" },
+              },
+            ],
+          },
+          {
+            link: { title: "Contact", href: "#" },
+          },
+          {
+            link: { title: "Resources", href: "#" },
+          },
+        ]}
+      />
+    ),
+  },
+}
+
+export default meta
+
+export const SideNavigation: StoryObj<typeof meta> = {}

package/src/Component/SideNavigation/SideNavigation.tsx

@@ -0,0 +1,34 @@
+import { JSX, ReactNode, PropsWithChildren, useId } from "react"
+import classNames from "classnames"
+
+type SideNavigationProps = PropsWithChildren & {
+  parent?: ReactNode
+  title?: string
+  id?: string
+  className?: string
+}
+
+const SideNavigation = ({
+  children,
+  parent,
+  title,
+  id,
+  className,
+}: SideNavigationProps): JSX.Element => {
+  const autoId = useId()
+  const navId = id || autoId
+
+  return (
+    <nav
+      className={classNames("mx-nav", "mx-side-nav", className)}
+      {...(title ? { "aria-label": title } : { "aria-labelledby": navId })}
+    >
+      <div className="mx-side-nav__parent" id={navId}>
+        {parent}
+      </div>
+      {children}
+    </nav>
+  )
+}
+
+export default SideNavigation

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

@@ -0,0 +1,3 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Side Navigation 1`] = `"<nav class="mx-nav mx-side-nav" aria-label="Sidebar nav"><div class="mx-side-nav__parent" id="sidenav-story"><a class="mx-link" href="#">About</a></div><ul class="mx-nav__level-1"><li><a href="#" class="mx-link">News</a></li><li class="mx-nav__has-subnav"><a href="#" class="mx-link">What we do</a><button class="mx-nav__toggle mx-icon mx-icon--chevron-down mx-icon--only" type="button">Sub-navigation</button><ul class="mx-nav__level-2"><li><a href="#" class="mx-link">Events</a></li><li class="mx-nav__has-subnav"><a href="#" class="mx-link">Who we are</a><button class="mx-nav__toggle mx-icon mx-icon--chevron-down mx-icon--only" type="button">Sub-navigation</button><ul class="mx-nav__level-3"><li><a href="#" class="mx-link">Our team</a></li><li><a href="#" class="mx-link" aria-current="page">Our philosophy</a></li><li><a href="#" class="mx-link">Why music?</a></li></ul></li><li><a href="#" class="mx-link">Join us</a></li><li><a href="#" class="mx-link">Careers</a></li></ul></li><li><a href="#" class="mx-link">Contact</a></li><li><a href="#" class="mx-link">Resources</a></li></ul></nav>"`;

package/src/Component/SideNavigation/twig/side-navigation-story.twig

@@ -1,7 +1,8 @@
 {% extends "../side-navigation.twig" %}
+{% import "@mixtape/Component/Navigation/menu.twig" as nav %}
 {% if items %}
   {% set items %}
-    {% include "@mixtape/Component/Navigation/twig/navigation-items.twig" with { items: items, level: 0, setInert: false } %}
+    {{ nav.menutree(items, 0, false, 'mx-nav') }}
   {% endset %}
 {% endif %}
 

package/src/Component/SocialLinks/README.md

@@ -0,0 +1,122 @@
+# SocialLinks
+
+A horizontal list of outbound links to your organisation's own social media profiles (Facebook, Instagram, LinkedIn, etc.). Use this for "follow us" style navigation — typically in the footer or a contact block. For share-this-page buttons, use [SocialShare](../SocialShare/README.md) instead.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/SocialLinks/social-links.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/SocialLinks/social-links.twig' with {
+  title: heading_component,
+  items: [
+    facebook_link,
+    instagram_link,
+    linkedin_link,
+  ],
+} %}
+```
+
+Each `items` entry is expected to be a pre-rendered icon-only Link. Example item construction:
+
+```twig
+{{ include('@mixtape/Atom/Link/link.twig', {
+  title: 'Facebook',
+  href: 'https://facebook.com/example',
+  iconOnly: true,
+  iconStart: include('@mixtape/Atom/Icon/icon.twig', {
+    icon: 'facebook',
+    size: 'md',
+  }),
+}) }}
+```
+
+**social-links.twig props** (`SocialLinks` type from `ids-shape`):
+
+| Prop    | Type                                    | Required | Description                                                             |
+| ------- | --------------------------------------- | -------- | ----------------------------------------------------------------------- |
+| `title` | `Heading`                               | No       | Optional rendered Heading placed before the links                       |
+| `items` | `Link[] \| LinkedImage[] \| Collection` | Yes      | Rendered Link strings — typically each is icon-only with an `iconStart` |
+
+The template hard-codes the wrapper as `<nav class="mx-social-links" aria-label="Social media links">` — there is no `attributes` hook on this template.
+
+---
+
+## HTML
+
+> SocialLinks does not currently ship a React implementation — it is composed in Twig (or as plain HTML) from existing atoms: a `<nav>` wrapper, an optional `Heading`, and one icon-only `Link` per profile.
+
+```html
+<nav class="mx-social-links" aria-label="Social media links">
+  <h2 class="mx-heading--m">Follow us</h2>
+  <a href="https://facebook.com/example">
+    <span class="mx-icon mx-icon--facebook mx-icon--size-md"></span>
+    <span class="sr-only">Facebook</span>
+  </a>
+  <a href="https://instagram.com/example">
+    <span class="mx-icon mx-icon--instagram mx-icon--size-md"></span>
+    <span class="sr-only">Instagram</span>
+  </a>
+  <a href="https://linkedin.com/company/example">
+    <span class="mx-icon mx-icon--linkedin mx-icon--size-md"></span>
+    <span class="sr-only">LinkedIn</span>
+  </a>
+</nav>
+```
+
+Each link uses an icon with a visually-hidden (`sr-only`) label for screen readers.
+
+---
+
+## Available social icons
+
+Use values from the `Icons` enum (`@pnx-mixtape/mxds/src/enums`) for the `iconStart` of each Link. Social-relevant values include:
+
+| Icon enum         | Class                |
+| ----------------- | -------------------- |
+| `Icons.FACEBOOK`  | `mx-icon--facebook`  |
+| `Icons.INSTAGRAM` | `mx-icon--instagram` |
+| `Icons.LINKEDIN`  | `mx-icon--linkedin`  |
+| `Icons.TWITTER`   | `mx-icon--twitter`   |
+| `Icons.YOUTUBE`   | `mx-icon--youtube`   |
+| `Icons.MASTODON`  | `mx-icon--mastodon`  |
+| `Icons.EMAIL`     | `mx-icon--email`     |
+
+Note: the `Icons` enum does not currently include a Bluesky value — `SocialShare` references `mx-icon--bluesky` directly as a Twig class string.
+
+---
+
+## Modifiers
+
+`SocialLinks` has no modifier classes of its own. Visual variation comes from:
+
+- The child `Link` / `Icon` atoms (size, colour)
+- The surrounding context (e.g. within a dark footer, it inherits `--foreground`)
+
+---
+
+## Accessibility
+
+- Renders as a `<nav>` with `aria-label="Social media links"` — distinguishes this region from site navigation when landmarks are enumerated.
+- Each link is icon-only; the `<span class="sr-only">` text (e.g. "Facebook") provides the accessible name. Never remove the `sr-only` label.
+- Icons carry no accessible text — they rely on the label span, so they do not need `aria-hidden` but should not be the only source of meaning.
+- If links open the profile in the same tab, no extra announcement is needed. If you add `target="_blank"`, also announce that in the label (e.g. "Facebook (opens in a new tab)").
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-social-links {
+  --nav-gap: var(--spacing-s); /* gap between icon links */
+  --foreground: inherit; /* icon/link colour; inherits from parent by default */
+}
+```
+
+The component sets `color: var(--foreground, inherit)` on the wrapper, so placing `SocialLinks` inside a dark surface (e.g. the Footer) will pick up the inverted text colour automatically without further configuration.

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

@@ -48,7 +48,7 @@ const meta: Meta<SocialLinksType> = {
           size: IconSizeModifier.MEDIUM,
         }),
       }),
-    ],
+    ].join(""),
   },
   argTypes: {
     title: {
@@ -59,14 +59,14 @@ const meta: Meta<SocialLinksType> = {
       },
     },
     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)`,
+      description: `A concatenated string of [Link](/?path=/docs/atom-link--docs) markup to use for the menu. These should include the relevant [Icon](/?path=/docs/atom-icon--docs)`,
       type: {
         name: "other",
         required: true,
-        value: "array",
+        value: "string",
       },
       table: {
-        type: { summary: "Link[]" },
+        type: { summary: "string" },
       },
     },
   },

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

@@ -5,7 +5,7 @@ exports[`Social Links 1`] = `
                     
 <h2 class="mx-heading--m">Follow us</h2>
 
-      
+  
 <a href="#">
   
 <span class="mx-icon mx-icon--facebook mx-icon--size-md"></span>
@@ -14,7 +14,6 @@ exports[`Social Links 1`] = `
     
 </a>
 
-      
 <a href="#">
   
 <span class="mx-icon mx-icon--instagram mx-icon--size-md"></span>
@@ -23,7 +22,6 @@ exports[`Social Links 1`] = `
     
 </a>
 
-      
 <a href="#">
   
 <span class="mx-icon mx-icon--linkedin mx-icon--size-md"></span>
@@ -32,6 +30,6 @@ exports[`Social Links 1`] = `
     
 </a>
 
-  </nav>
+</nav>
 "
 `;

package/src/Component/SocialLinks/social-links.css

@@ -4,6 +4,8 @@
 
 @layer design-system.components {
   .mx-social-links {
+    list-style: none;
+    padding-inline-start: unset;
     display: flex;
     flex-flow: row wrap;
     align-items: center;

package/src/Component/SocialLinks/social-links.twig

@@ -1,6 +1,4 @@
 <nav class="mx-social-links" aria-label="Social media links">
   {{ title }}
-  {% for item in items %}
-    {{ item }}
-  {% endfor %}
+  {{ items }}
 </nav>