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

package/src/Layout/Section/Section.stories.tsx

@@ -1,7 +1,7 @@
 import { Meta, StoryObj } from "@storybook/react-vite"
 import Component from "./Section"
-import { PageWidths, SectionFlow, SectionStyles } from "../../enums"
-import { SectionTypes } from "@pnx-mixtape/ids-shape"
+import { PageWidths, SectionFlow } from "../../enums"
+import { SectionTypes, SectionModifiers } from "@pnx-mixtape/ids-shape"
 import { Page } from "../../../.storybook-react/decorators"
 
 const meta: Meta<typeof Component> = {
@@ -13,7 +13,7 @@ const meta: Meta<typeof Component> = {
     containing: true,
   },
   argTypes: {
-    sizes: { options: Object.values(SectionStyles) },
+    sizes: { options: Object.values(SectionModifiers) },
     width: { options: Object.values(PageWidths) },
     as: { options: Object.values(SectionTypes) },
     flow: { options: Object.values(SectionFlow) },
@@ -25,21 +25,21 @@ type Story = StoryObj<typeof meta>
 
 export const Default: Story = {
   args: {
-    sizes: SectionStyles.XL,
+    sizes: SectionModifiers.XL,
     width: PageWidths.FEATURE,
   },
 }
 
 export const Varied: Story = {
   args: {
-    sizes: [SectionStyles.TOP_M, SectionStyles.BOTTOM_XL],
+    sizes: [SectionModifiers.TOP_M, SectionModifiers.BOTTOM_XL],
     as: SectionTypes.ASIDE,
   },
 }
 
 export const List: Story = {
   args: {
-    sizes: SectionStyles.S,
+    sizes: SectionModifiers.S,
     as: SectionTypes.LIST,
     children: (
       <>

package/src/Layout/Section/Section.tsx

@@ -1,7 +1,7 @@
 import { JSX, ComponentPropsWithoutRef, PropsWithChildren, useMemo } from "react"
 import classNames from "classnames"
-import { PageWidths, SectionFlow, SectionStyles } from "../../enums"
-import { SectionTypes } from "@pnx-mixtape/ids-shape"
+import { BackgroundStyles, PageWidths, SectionFlow } from "../../enums"
+import { SectionTypes, SectionModifiers } from "@pnx-mixtape/ids-shape"
 
 type InnerTagProps = ComponentPropsWithoutRef<"div"> &
   PropsWithChildren & {
@@ -12,10 +12,11 @@ const InnerTag = ({ condition, children, ...props }: InnerTagProps): JSX.Element
   condition ? <div {...props}>{children}</div> : <>{children}</>
 
 type SectionProps = PropsWithChildren & {
-  sizes?: SectionStyles | SectionStyles[]
+  sizes?: SectionModifiers | SectionModifiers[]
   width?: PageWidths
   flow?: SectionFlow
   as?: SectionTypes
+  background?: BackgroundStyles
   className?: string
   innerClassName?: string
   containing?: boolean
@@ -29,6 +30,7 @@ const Section = ({
   flow,
   as = SectionTypes.DIV,
   className,
+  background,
   innerClassName,
   containing = false,
   container = false,
@@ -37,7 +39,7 @@ const Section = ({
   const Tag: JSX.ElementType = `${as}` as unknown as JSX.ElementType
   const sizeClasses = useMemo<string[]>(() => {
     if (!sizes) return []
-    if (Array.isArray(sizes)) return sizes.map((size: SectionStyles) => `mx-section--${size}`)
+    if (Array.isArray(sizes)) return sizes.map((size: SectionModifiers) => `mx-section--${size}`)
     return [`mx-section--${sizes}`]
   }, [sizes])
 
@@ -48,8 +50,9 @@ const Section = ({
         [className]: className,
         [sizeClasses.join(" ")]: sizes,
         [`mx-page--${width}`]: width && containing,
-        [`mx-section__${width}`]: width && !containing,
+        [`mx-section--${width}`]: width && !containing,
         [`mx-section--${flow}`]: flow,
+        [`mx-background--${background}`]: background,
       })}
       {...props}
     >

package/src/Layout/Section/SectionGrid.stories.tsx

@@ -1,7 +1,7 @@
 import { Meta, StoryObj } from "@storybook/react-vite"
 import Component from "./SectionGrid"
-import { PageWidths, SectionFlow, SectionStyles } from "../../enums"
-import { SectionTypes, GridModifiers } from "@pnx-mixtape/ids-shape"
+import { PageWidths, SectionFlow } from "../../enums"
+import { SectionTypes, GridModifiers, SectionModifiers } from "@pnx-mixtape/ids-shape"
 import { Page } from "../../../.storybook-react/decorators"
 
 const meta: Meta<typeof Component> = {
@@ -16,10 +16,10 @@ const meta: Meta<typeof Component> = {
         <div>Item 3</div>
       </>
     ),
-    sizes: SectionStyles.XL,
+    sizes: SectionModifiers.XL,
   },
   argTypes: {
-    sizes: { options: Object.values(SectionStyles) },
+    sizes: { options: Object.values(SectionModifiers) },
     cols: { options: Object.values(GridModifiers) },
     as: { options: Object.values(SectionTypes) },
     width: { options: Object.values(PageWidths) },

package/src/Layout/Section/SectionGrid.tsx

@@ -1,11 +1,11 @@
 import { JSX, PropsWithChildren, useMemo } from "react"
 import classNames from "classnames"
 import Grid from "../Grid/Grid"
-import { PageWidths, SectionFlow, SectionStyles } from "../../enums"
-import { SectionTypes, GridModifiers } from "@pnx-mixtape/ids-shape"
+import { PageWidths, SectionFlow } from "../../enums"
+import { SectionTypes, GridModifiers, SectionModifiers } from "@pnx-mixtape/ids-shape"
 
 type SectionGridProps = PropsWithChildren & {
-  sizes?: SectionStyles | SectionStyles[]
+  sizes?: SectionModifiers | SectionModifiers[]
   width?: PageWidths
   flow?: SectionFlow
   as?: SectionTypes
@@ -34,7 +34,7 @@ const SectionGrid = ({
 
   const sizeClasses = useMemo<string[]>(() => {
     if (!sizes) return []
-    if (Array.isArray(sizes)) return sizes.map((size: SectionStyles) => `mx-section--${size}`)
+    if (Array.isArray(sizes)) return sizes.map((size: SectionModifiers) => `mx-section--${size}`)
     return [`mx-section--${sizes}`]
   }, [sizes])
 
@@ -45,7 +45,7 @@ const SectionGrid = ({
         [className]: className,
         [sizeClasses.join(" ")]: sizes,
         [`mx-page--${width}`]: width && containing,
-        [`mx-section__${width}`]: width && !containing,
+        [`mx-section--${width}`]: width && !containing,
       })}
       {...props}
     >

package/src/Layout/Section/__snapshots__/Background.stories.ts.snap

@@ -15,7 +15,7 @@ exports[`Background 1`] = `
 <h2>Section name</h2>
 
           
-<a class="mx-link--more" href="#">
+<a href="#" class="mx-link--more">
   
   <span>See more content</span>
     
@@ -45,7 +45,7 @@ exports[`Dark 1`] = `
 <h2>Section name</h2>
 
           
-<a class="mx-link--more" href="#">
+<a href="#" class="mx-link--more">
   
   <span>See more content</span>
     

package/src/Layout/Section/__snapshots__/Section.stories.ts.snap

@@ -9,7 +9,7 @@ exports[`Background 1`] = `
 <h2>Section name</h2>
 
         
-<a class="mx-link--more" href="#">
+<a href="#" class="mx-link--more">
   
   <span>See more content</span>
     
@@ -33,7 +33,7 @@ exports[`Box 1`] = `
 <h2>Section name</h2>
 
         
-<a class="mx-link--more" href="#">
+<a href="#" class="mx-link--more">
   
   <span>See more content</span>
     
@@ -67,7 +67,7 @@ exports[`Modifiers 1`] = `
 <h2>Section name</h2>
 
         
-<a class="mx-link--more" href="#">
+<a href="#" class="mx-link--more">
   
   <span>See more content</span>
     
@@ -91,7 +91,7 @@ exports[`Section 1`] = `
 <h2>Section name</h2>
 
         
-<a class="mx-link--more" href="#">
+<a href="#" class="mx-link--more">
   
   <span>See more content</span>
     

package/src/Layout/Section/section.css

@@ -4,16 +4,20 @@
 
 @layer design-system.layouts {
   .mx-container {
-    --container-name: container;
-
-    container-name: var(--container-name);
+    container-name: var(--container-name, container);
     container-type: inline-size;
+    list-style: none;
+  }
+
+  ul:has(> .mx-container) {
+    padding-inline-start: unset;
   }
 
   .mx-section--divider {
     border-block-start: 1px solid var(--colour-border);
   }
 
+  /* @public --section-s --section-m --section-l --section-xl */
   .mx-section--s {
     padding-block: var(--section-s, var(--spacing-s));
   }

package/src/Layout/Sidebar/README.md

@@ -0,0 +1,126 @@
+# Sidebar
+
+A two-column layout with a narrow sidebar and a wide main content area. The sidebar collapses below the main content when there isn't enough horizontal space. Uses flexbox intrinsic sizing — no breakpoint class needed.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Layout/Sidebar/sidebar.css";
+```
+
+## Twig
+
+```twig
+{# Sidebar on the right (default) #}
+{% include '@mixtape/Layout/Sidebar/sidebar.twig' with {
+  content: main_content,
+  sidebarContent: sidebar_content,
+} %}
+
+{# Sidebar on the left #}
+{% include '@mixtape/Layout/Sidebar/sidebar.twig' with {
+  before: true,
+  content: main_content,
+  sidebarContent: filters_component,
+} %}
+
+{# Sidebar reversed at large breakpoints — pass an order key as `order` #}
+{% include '@mixtape/Layout/Sidebar/sidebar.twig' with {
+  order: 'sidebar-rev-lg',
+  content: main_content,
+  sidebarContent: sidebar_content,
+  modifiers: ['l'],
+} %}
+```
+
+**sidebar.twig props:**
+
+| Prop                | Type         | Required | Description                                                                                                                |
+| ------------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `content`           | `Collection` | No       | Rendered main content — placed inside `<section class="js-content mx-vertical-flow-grid">`                                 |
+| `sidebarContent`    | `Collection` | No       | Rendered sidebar content — placed inside `<aside class="mx-vertical-flow-grid">`. The aside is omitted entirely when empty |
+| `before`            | `boolean`    | No       | Renders the `<aside>` before the `<section>` (sidebar on the left)                                                         |
+| `order`             | `string`     | No       | Adds `mx-grid--{order}` (e.g. `sidebar-rev`, `sidebar-rev-lg`)                                                             |
+| `modifiers`         | `string[]`   | No       | Each value is appended as `mx-section--{modifier}` for vertical padding                                                    |
+| `attributes`        | `Attribute`  | No       | Optional Drupal-style attributes object on the wrapper — `mx-grid--sidebar` is always merged on top                        |
+| `sidebarAttributes` | `Attribute`  | No       | Optional Drupal-style attributes object on the `<aside>` — `mx-vertical-flow-grid` is merged on top                        |
+| `contentAttributes` | `Attribute`  | No       | Optional Drupal-style attributes object on the `<section>` — `js-content mx-vertical-flow-grid` is merged on top           |
+
+The `Sidebar` layout is not declared as a type in `ids-shape`; the variable list above reflects the template's own contract. Note that `js-content` on the inner `<section>` is required for the `<mx-in-page-navigation>` web component to find the page content automatically.
+
+## HTML
+
+```html
+<!-- Sidebar right -->
+<div class="mx-grid--sidebar">
+  <section>Main content</section>
+  <aside>Sidebar</aside>
+</div>
+
+<!-- Sidebar left -->
+<div class="mx-grid--sidebar">
+  <aside>Sidebar</aside>
+  <section>Main content</section>
+</div>
+
+<!-- Sidebar reversed at medium+ -->
+<div class="mx-grid--sidebar mx-grid--sidebar-rev-lg">
+  <section>Main content</section>
+  <aside>Sidebar</aside>
+</div>
+```
+
+## React
+
+```tsx
+import { Sidebar } from "@pnx-mixtape/mxds/react"
+import { SidebarOrder } from "../../enums"
+
+// Sidebar on the right (default)
+<Sidebar sidebar={<aside>Sidebar content</aside>}>
+  <main>Main content</main>
+</Sidebar>
+
+// Sidebar on the left
+<Sidebar sidebar={<aside>Filters</aside>} before>
+  <main>Results</main>
+</Sidebar>
+
+// Sidebar reversed at large breakpoints only
+<Sidebar sidebar={<aside>Nav</aside>} order={SidebarOrder.REVERSE_L}>
+  <main>Content</main>
+</Sidebar>
+```
+
+**Props:**
+
+| Prop               | Type           | Default                              | Description                                                                                                     |
+| ------------------ | -------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `sidebar`          | `ReactNode`    | —                                    | Content for the `<aside>`                                                                                       |
+| `before`           | `boolean`      | `false`                              | Places the sidebar before (left of) the main content                                                            |
+| `order`            | `SidebarOrder` | —                                    | Reversal modifier (see below)                                                                                   |
+| `sidebarClassName` | `string`       | `"mx-vertical-flow-grid"`            | Class applied to the `<aside>`. Pass an empty string to opt out                                                 |
+| `contentClassName` | `string`       | `"js-content mx-vertical-flow-grid"` | Class applied to the `<section>`. The `js-content` hook is what `<mx-in-page-navigation>` searches for headings |
+
+## Order modifiers (`SidebarOrder` enum)
+
+| Class                     | `SidebarOrder` enum      | Effect                           |
+| ------------------------- | ------------------------ | -------------------------------- |
+| `mx-grid--sidebar-rev`    | `SidebarOrder.REVERSE`   | Always reverses sidebar to left  |
+| `mx-grid--sidebar-rev-lg` | `SidebarOrder.REVERSE_L` | Reverses to left at medium+ only |
+
+> If no `<aside>` is present, the wrapper collapses to `grid-column: narrow` — safe to render conditionally.
+
+## Customisation via CSS custom properties
+
+```css
+.mx-grid--sidebar {
+  --sidebar-width: 18ch; /* max width of the aside (default: 24ch) */
+  --sidebar-gap: var(--gap-l);
+  --content-min: 60%; /* minimum width of the main content before wrapping (default: 50%) */
+}
+```
+
+---
+
+→ Used in context: `mockups/ArticlePage.stories.ts:14`

package/src/Layout/Sidebar/Sidebar.figma.ts

@@ -0,0 +1,23 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=79-290
+// source=src/Layout/Sidebar/Sidebar.tsx
+// component=Sidebar
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const before = instance.getEnum("Before", { Off: false, On: true })
+const sidebarContent = instance.getSlot("Sidebar")
+const mainContent = instance.getSlot("Content")
+
+const beforeProp = before ? " before" : ""
+
+// `order` (SidebarOrder: Reverse/ReverseL) is breakpoint-gated, layered on top of
+// `before` — not modelled, same simplification class as Card's `reversed`.
+export default {
+  example: figma.code`<Sidebar${beforeProp} sidebar={${sidebarContent}}>${mainContent}</Sidebar>`,
+  imports: ['import { Sidebar } from "@pnx-mixtape/mxds/react"'],
+  id: "sidebar",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Layout/Sidebar/Sidebar.stories.ts

@@ -2,6 +2,7 @@ import { Meta, StoryObj } from "@storybook/html-vite"
 import { SidebarOrder } from "../../enums"
 import Component from "./sidebar.twig"
 import "./sidebar.css"
+import { modes } from "../../../.storybook/modes"
 
 type SidebarArgs = {
   content?: string | HTMLElement
@@ -51,6 +52,14 @@ const meta: Meta<SidebarArgs> = {
       },
     },
   },
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
+      },
+    },
+  },
 }
 
 export default meta

package/src/Layout/Sidebar/Sidebar.tsx

@@ -15,8 +15,8 @@ const Sidebar = ({
   sidebar,
   before = false,
   order,
-  sidebarClassName,
-  contentClassName,
+  sidebarClassName = "mx-vertical-flow-grid",
+  contentClassName = "js-content mx-vertical-flow-grid",
 }: PageSidebarProps): JSX.Element => (
   <div
     className={classNames("mx-grid--sidebar", {

package/src/Layout/Sidebar/__snapshots__/Sidebar.stories.tsx.snap

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`No Sidebar 1`] = `"<div class="mx-grid--sidebar"><section><p>Main content</p></section></div>"`;
+exports[`No Sidebar 1`] = `"<div class="mx-grid--sidebar"><section class="js-content mx-vertical-flow-grid"><p>Main content</p></section></div>"`;
 
-exports[`Reverse 1`] = `"<div class="mx-grid--sidebar"><aside><p>Sidebar content</p></aside><section><p>Main content</p></section></div>"`;
+exports[`Reverse 1`] = `"<div class="mx-grid--sidebar"><aside class="mx-vertical-flow-grid"><p>Sidebar content</p></aside><section class="js-content mx-vertical-flow-grid"><p>Main content</p></section></div>"`;
 
-exports[`Sidebar 1`] = `"<div class="mx-grid--sidebar"><section><p>Main content</p></section><aside><p>Sidebar content</p></aside></div>"`;
+exports[`Sidebar 1`] = `"<div class="mx-grid--sidebar"><section class="js-content mx-vertical-flow-grid"><p>Main content</p></section><aside class="mx-vertical-flow-grid"><p>Sidebar content</p></aside></div>"`;

package/src/Layout/Sidebar/sidebar.css

@@ -10,13 +10,20 @@
 
     &:where(:has(> aside)) {
       display: flex;
-      flex-wrap: wrap;
+      flex-flow: var(--sidebar-direction, column) wrap;
       gap: var(--sidebar-gap, var(--gap));
       justify-content: space-between;
 
+      @media (--medium-up) {
+        --sidebar-direction: row;
+      }
+
       & > aside {
         flex-grow: 1;
-        max-inline-size: var(--sidebar-width, 24ch);
+
+        @media (--medium-up) {
+          max-inline-size: var(--sidebar-width, 24ch);
+        }
       }
 
       & > section {
@@ -24,27 +31,23 @@
         flex-grow: 999;
         min-inline-size: var(--content-min, 50%);
         max-inline-size: var(--container-max-width, 76ch);
+
+        & .mx-grid {
+          --grid-min: 18ch;
+        }
       }
 
       &.mx-grid--sidebar-rev {
-        flex-direction: row-reverse;
+        @media (--medium-up) {
+          --sidebar-direction: row-reverse;
+        }
       }
 
       &.mx-grid--sidebar-rev-lg {
-        @media (--medium-up) {
-          flex-direction: row-reverse;
+        @media (--large-up) {
+          --sidebar-direction: row-reverse;
         }
       }
     }
   }
 }
-
-/**
- * Print stylesheet
- */
-
-@media print {
-  .mx-grid--sidebar {
-    flex-direction: column;
-  }
-}

package/src/Utility/Elements/breakpoint-loader.ts

@@ -9,6 +9,7 @@ type BreakpointLoaderOptions = {
 export default class BreakpointLoader {
   el: HTMLElement
   callback: () => any
+  controller: AbortController
   breakpoint: MediaQueryList
   options: BreakpointLoaderOptions
   fallbackBtn?: HTMLButtonElement
@@ -28,12 +29,14 @@ export default class BreakpointLoader {
     this.options = { ...options }
     this.fallbackBtn = this.el.querySelector("[data-load-fallback]")
     this.errorMsg = this.el.querySelector("[data-load-error]")
+    this.controller = new AbortController()
   }
 
   init = (): void => {
     this.responsiveCheck(this.breakpoint)
-    this.breakpoint.addEventListener("change", this.responsiveCheck)
-    this.fallbackBtn?.addEventListener("click", this.handleClick)
+    const { signal }: AbortController = this.controller
+    this.breakpoint.addEventListener("change", this.responsiveCheck, { signal })
+    this.fallbackBtn?.addEventListener("click", this.handleClick, { signal })
   }
 
   responsiveCheck = ({ matches }): void => {
@@ -45,8 +48,13 @@ export default class BreakpointLoader {
       await this.callback()
     } catch (error) {
       this.handleError(error)
+    } finally {
+      this.destroy()
     }
-    this.breakpoint.removeEventListener("change", this.responsiveCheck)
+  }
+
+  destroy = (): void => {
+    this.controller.abort()
   }
 
   handleClick = (): void => {
@@ -54,7 +62,7 @@ export default class BreakpointLoader {
   }
 
   handleError = (error): void => {
-    console.error(error) // eslint-disable-line no-console
+    if (process.env.NODE_ENV !== "production") console.error(error) // eslint-disable-line no-console
     this.errorMsg?.removeAttribute("hidden")
   }