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

package/src/Component/Filters/Elements/Filters.ts

@@ -3,8 +3,10 @@
  * @file Support filter count elements and closing the "right" variant on mobile..
  */
 
+import { createFocusTrap, FocusTrap } from "focus-trap"
 import "../../Accordion/Elements/Accordion"
 import "../../Accordion/Elements/AccordionMobile"
+import { validators } from "../../../Utility/utilities"
 
 type EntryType = {
   item: HTMLElement
@@ -16,6 +18,13 @@ export default class Filters extends HTMLElement {
   internals_: ElementInternals
   controller: AbortController
   entries?: Map<string, EntryType>
+  timeout?: ReturnType<typeof setTimeout>
+  mq: string
+  focusTrap!: FocusTrap
+  rafId?: number | null
+  focusTrapTimeout?: ReturnType<typeof setTimeout> | null
+  scrollLockClass: string = "body--scroll-lock"
+  isRight?: boolean
 
   static observedAttributes = ["count"]
 
@@ -23,6 +32,8 @@ export default class Filters extends HTMLElement {
     super()
     this.internals_ = this.attachInternals()
     this.controller = new AbortController()
+    this.mq = this.getAttribute("mq") || "(max-width: 720px)"
+    this.isRight = this.classList.contains(`mx-filters--right`)
   }
 
   connectedCallback(): void {
@@ -43,15 +54,76 @@ export default class Filters extends HTMLElement {
     this.addEventListener("change", this.handleCounters, { signal })
     this.form?.addEventListener("submit", this.handleCounters, { signal })
     this.form?.addEventListener("reset", this.handleReset, { signal })
+
+    if (this.isRight) {
+      this.handleBreakpoint(this.breakpoint)
+      this.breakpoint.addEventListener("change", this.handleBreakpoint, {
+        signal,
+      })
+
+      this.focusTrap = createFocusTrap(this.form, {
+        escapeDeactivates: false,
+        setReturnFocus: this.details,
+        allowOutsideClick: true,
+        onActivate: () => document.body.classList.add(this.scrollLockClass),
+        onDeactivate: () => document.body.classList.remove(this.scrollLockClass),
+        checkCanFocusTrap: ([trapContainer]) =>
+          new Promise<void>(resolve => {
+            // Safety timeout: resolve after 2 seconds if visibility never changes
+            this.focusTrapTimeout = setTimeout(() => {
+              if (this.rafId) {
+                cancelAnimationFrame(this.rafId)
+                this.rafId = null
+              }
+              if (process.env.NODE_ENV !== "production") {
+                // oxlint-disable-next-line no-console
+                console.warn("Focus trap visibility check timed out - proceeding anyway")
+              }
+              resolve()
+            }, 2000)
+
+            // Check visibility using requestAnimationFrame for better performance
+            const checkVisibility = () => {
+              if (getComputedStyle(trapContainer).display !== "none") {
+                if (this.focusTrapTimeout) {
+                  clearTimeout(this.focusTrapTimeout)
+                  this.focusTrapTimeout = null
+                }
+                this.rafId = null
+                resolve()
+              } else {
+                this.rafId = requestAnimationFrame(checkVisibility)
+              }
+            }
+            this.rafId = requestAnimationFrame(checkVisibility)
+          }),
+      })
+    }
   }
 
   disconnectedCallback(): void {
     this.controller.abort()
+    if (this.timeout) {
+      clearTimeout(this.timeout)
+      this.timeout = null
+    }
+
+    // Clean up focus trap timers
+    if (this.rafId) {
+      cancelAnimationFrame(this.rafId)
+      this.rafId = null
+    }
+    if (this.focusTrapTimeout) {
+      clearTimeout(this.focusTrapTimeout)
+      this.focusTrapTimeout = null
+    }
+    this.focusTrap?.deactivate()
+    document.body.classList.remove(this.scrollLockClass)
   }
 
   attributeChangedCallback(name: string, oldValue: string, newValue: string): void {
     if (name === "count" && oldValue !== newValue) {
-      const qualifier = parseInt(newValue, 10) > 0
+      const qualifier = validators.integer(newValue, 1)
       this.resetBtn?.toggleAttribute("disabled", !qualifier)
       this.submitBtn?.toggleAttribute("disabled", !qualifier)
       if (!this.allCounter) return
@@ -73,7 +145,7 @@ export default class Filters extends HTMLElement {
     const input = lastVisible.querySelector("input")
     if (!input) return
     input.focus({ preventScroll: true })
-    setTimeout(() => {
+    this.timeout = setTimeout(() => {
       this.showBtn.setAttribute("hidden", "")
     }, 100)
   }
@@ -99,6 +171,34 @@ export default class Filters extends HTMLElement {
     this.setAttribute("count", totalCount.toString())
   }
 
+  handleBreakpoint = ({ matches }: MediaQueryList | MediaQueryListEvent): void => {
+    if (!this.details) return
+    const { signal }: AbortController = this.controller
+    if (matches) {
+      this.details.addEventListener("toggle", this.handleToggle, { signal })
+    } else {
+      this.details.removeEventListener("toggle", this.handleToggle)
+      document.body.classList.remove(this.scrollLockClass)
+      this.focusTrap?.deactivate()
+    }
+  }
+
+  handleToggle = async (): Promise<void> => {
+    if (this.details.open) {
+      // Handle focus trap activation errors gracefully
+      try {
+        await this.focusTrap?.activate()
+      } catch (error) {
+        if (process.env.NODE_ENV !== "production") {
+          // oxlint-disable-next-line no-console
+          console.warn("Failed to activate focus trap:", error)
+        }
+      }
+    } else {
+      this.focusTrap?.deactivate()
+    }
+  }
+
   get items(): NodeListOf<HTMLElement> | null {
     const items: NodeListOf<HTMLElement> = this.querySelectorAll(".mx-filter-item")
     if (!items) {
@@ -142,6 +242,10 @@ export default class Filters extends HTMLElement {
   get allCounter(): HTMLSpanElement | null {
     return this.querySelector("[data-counters]")
   }
+
+  get breakpoint(): MediaQueryList {
+    return window.matchMedia(this.mq)
+  }
 }
 
 if (!customElements.get("mx-filters")) customElements.define("mx-filters", Filters)

package/src/Component/Filters/FilterItem.figma.ts

@@ -0,0 +1,31 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=96-390
+// source=src/Component/Filters/FilterItem.tsx
+// component=FilterItem
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const collapsible = instance.getEnum("Collapsible", { Off: false, On: true })
+
+// The two variants have genuinely different structure in code, not just a style
+// difference — Collapsible=Off exposes real Label/DescriptionStart/DescriptionEnd/
+// Status SLOTs directly; Collapsible=On is a real Accordion instance instead (real
+// code wraps everything in <Accordion><AccordionTitle>...<AccordionContent>...), so
+// those 4 named slots don't exist on that variant at all.
+const fields = figma.code`[
+  <Checkbox key="1" value="option-1">Option 1</Checkbox>,
+  <Checkbox key="2" value="option-2">Option 2</Checkbox>,
+]`
+
+const example = collapsible
+  ? figma.code`<FilterItem collapsible={{ title: "Filter group" }} fields={${fields}} />`
+  : figma.code`<FilterItem label={${instance.getSlot("Label")}} descriptionStart={${instance.getSlot("DescriptionStart")}} descriptionEnd={${instance.getSlot("DescriptionEnd")}} fields={${fields}} />`
+
+export default {
+  example,
+  imports: ['import { FilterItem, Checkbox } from "@pnx-mixtape/mxds/react"'],
+  id: "filter-item",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Filters/FilterItem.stories.ts

@@ -14,10 +14,17 @@ import FormDescription from "../../Form/Description/form-description.twig"
 import "../../Form/form.css"
 import "../Accordion/accordion.css"
 
+type MxFilterItemType = Omit<FilterItemType, "fields" | "shownItems"> & {
+  fields?: string
+  visibleFields?: string
+  hiddenFields?: string
+  fieldCount?: number
+}
+
 /**
  * Filter Items have some options that only work in the parent Filter context (requires their JS).
  */
-const meta: Meta<FilterItemType> = {
+const meta: Meta<MxFilterItemType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
@@ -56,10 +63,10 @@ const meta: Meta<FilterItemType> = {
     },
     fields: {
       description:
-        "List of FormInput (`FormText | FormTextArea | FormSelect | FormControl`) elements.",
+        "A concatenated string of FormInput (`FormText | FormTextArea | FormSelect | FormControl`) markup.",
       control: "text",
       table: {
-        type: { summary: "FormInput[]" },
+        type: { summary: "string" },
         subcategory: "FilterItem content",
       },
     },
@@ -87,9 +94,17 @@ const meta: Meta<FilterItemType> = {
         defaultValue: { summary: "div" },
       },
     },
-    shownItems: {
+    visibleFields: {
       description:
-        "Collapse the list of fields into an initially visible list, and add a 'show all' toggle. Useful for large numbers of checkboxes/radios.",
+        "A concatenated string of the initially visible fields. When set alongside `hiddenFields`, adds a 'show all' toggle. Useful for large numbers of checkboxes/radios.",
+      control: "text",
+    },
+    hiddenFields: {
+      description: "A concatenated string of the fields hidden behind the 'show all' toggle.",
+      control: "text",
+    },
+    fieldCount: {
+      description: "Total field count, shown in the 'show all' toggle label.",
       type: "number",
     },
     // @ts-expect-error The controls follow the shape
@@ -121,7 +136,7 @@ const meta: Meta<FilterItemType> = {
 }
 
 export default meta
-type Story = StoryObj<FilterItemType>
+type Story = StoryObj<MxFilterItemType>
 
 export const Filters: Story = {}
 
@@ -160,7 +175,7 @@ export const Collapsible: Story = {
         label: "Publications",
         value: "publications",
       }),
-    ],
+    ].join(""),
   },
 }
 
@@ -175,6 +190,28 @@ export const ShownItems: Story = {
       id: "filter-categories",
       title: "Categories",
     }),
-    shownItems: 2,
+    visibleFields: [
+      InputCheckbox({
+        id: "category-news",
+        name: "categories",
+        label: "News",
+        value: "news",
+        checked: true,
+      }),
+      InputCheckbox({
+        id: "category-media",
+        name: "categories",
+        label: "Media Releases",
+        value: "media",
+        checked: true,
+      }),
+    ].join(""),
+    hiddenFields: InputCheckbox({
+      id: "category-publications",
+      name: "categories",
+      label: "Publications",
+      value: "publications",
+    }),
+    fieldCount: 3,
   },
 }

package/src/Component/Filters/FilterItem.stories.tsx

@@ -0,0 +1,75 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import Component from "./FilterItem"
+import FormLabel from "../../Form/Label/FormLabel"
+import FormText from "../../Form/TextInput/FormText"
+import FormCheckbox, { Checkbox } from "../../Form/Checkbox/FormCheckbox"
+import FormDescription from "../../Form/Description/FormDescription"
+import "./filters.css"
+import "../Accordion/accordion.css"
+import "../Tag/tag.css"
+import "../../Form/form.css"
+import { Page } from "../../../.storybook-react/decorators"
+
+/**
+ * FilterItem renders a single filter group inside a Filters form. When used inside
+ * `<Filters>`, the `name` prop wires per-item counter tracking via FiltersContext.
+ *
+ * Note: counters in the Collapsible variant only reflect real counts when the
+ * FilterItem is wrapped inside a `<Filters>` component — the context is not available
+ * in isolation.
+ */
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  decorators: [Page],
+  component: Component,
+  args: {
+    id: "filter-keywords",
+    label: <FormLabel id="filter-keywords" text="Keywords" />,
+    fields: [<FormText key="kw" id="filter-keywords" name="keywords" aria-label="Keywords" />],
+    descriptionStart: <FormDescription id="filter-keywords">Search by keywords</FormDescription>,
+  },
+}
+
+export default meta
+
+export const FilterItemDefault: StoryObj<typeof meta> = {}
+
+/**
+ * Collapse into an Accordion. The counter badge requires a parent `<Filters>` context
+ * and a `name` prop matching the form field name — see the Filters stories for a
+ * working counter example.
+ */
+export const Collapsible: StoryObj<typeof meta> = {
+  args: {
+    id: "filter-categories",
+    name: "categories",
+    label: undefined,
+    descriptionStart: undefined,
+    collapsible: {
+      title: "Categories",
+      counter: true,
+      open: true,
+    },
+    fields: [
+      <FormCheckbox key="cat" name="categories" aria-label="Categories">
+        <Checkbox value="news">News</Checkbox>
+        <Checkbox value="media-releases">Media Releases</Checkbox>
+        <Checkbox value="publications">Publications</Checkbox>
+      </FormCheckbox>,
+    ],
+  },
+}
+
+/**
+ * Long option lists can be truncated with `shownItems`. A "Show all" button reveals
+ * the rest. Requires the parent Filter context for full behaviour — see the Filters
+ * stories.
+ */
+export const ShownItems: StoryObj<typeof meta> = {
+  args: {
+    ...Collapsible.args,
+    collapsible: undefined,
+    label: <FormLabel id="filter-categories" text="Categories" />,
+    shownItems: 2,
+  },
+}

package/src/Component/Filters/FilterItem.tsx

@@ -0,0 +1,120 @@
+import { Fragment, JSX, PropsWithChildren, ReactNode, useState } from "react"
+import classNames from "classnames"
+import Accordion from "../Accordion/Accordion"
+import AccordionTitle from "../Accordion/Components/AccordionTitle"
+import AccordionContent from "../Accordion/Components/AccordionContent"
+import { useFiltersContext } from "./Filters"
+import { EMPTY_ARRAY } from "../../enums"
+
+type CollapsibleOptions = {
+  title: string
+  open?: boolean
+  counter?: boolean
+}
+
+type FilterItemProps = PropsWithChildren & {
+  id?: string
+  /** The form field name — used to look up this item's active count from FiltersContext. */
+  name?: string
+  as?: "div" | "fieldset"
+  label?: ReactNode
+  fields?: ReactNode[]
+  descriptionStart?: ReactNode
+  descriptionEnd?: ReactNode
+  status?: ReactNode
+  inline?: boolean
+  shownItems?: number
+  collapsible?: CollapsibleOptions
+}
+
+const FilterItem = ({
+  id,
+  name,
+  as: Tag = "div",
+  label,
+  fields = EMPTY_ARRAY,
+  descriptionStart,
+  descriptionEnd,
+  status,
+  inline = false,
+  shownItems,
+  collapsible,
+  children,
+}: FilterItemProps): JSX.Element => {
+  const [showAll, setShowAll] = useState(false)
+  const { counts } = useFiltersContext()
+
+  const count = name != null ? (counts.get(name) ?? 0) : 0
+
+  const shouldTruncate = !showAll && typeof shownItems === "number" && fields.length > shownItems
+
+  const visibleFields = shouldTruncate ? fields.slice(0, shownItems) : fields
+  const hiddenFields = shouldTruncate ? fields.slice(shownItems) : []
+
+  const itemClass = classNames(
+    "mx-form-item",
+    Tag === "fieldset" && "mx-fieldset",
+    inline && "mx-form-item--inline",
+    collapsible ? "mx-accordion__content" : "mx-filter-item",
+  )
+
+  const fieldContent = (
+    <Tag className={itemClass} {...(id ? { id } : {})}>
+      {label}
+      {descriptionStart}
+      {fields.length > 0 ? (
+        <>
+          {visibleFields.map((field, i) => (
+            // Opaque ReactNode with no stable id; index is the only available key.
+            // oxlint-disable-next-line react/no-array-index-key
+            <Fragment key={i}>{field}</Fragment>
+          ))}
+          {shouldTruncate && (
+            <button
+              className="mx-button mx-button--light"
+              type="button"
+              onClick={() => setShowAll(true)}
+            >
+              Show all ({fields.length})
+            </button>
+          )}
+          {showAll &&
+            hiddenFields.map((field, i) => (
+              // Opaque ReactNode with no stable id; index is the only available key.
+              // oxlint-disable-next-line react/no-array-index-key
+              <Fragment key={i}>{field}</Fragment>
+            ))}
+        </>
+      ) : (
+        children
+      )}
+      {descriptionEnd}
+      {status}
+    </Tag>
+  )
+
+  if (!collapsible) {
+    return fieldContent
+  }
+
+  return (
+    <Accordion
+      active={collapsible.open ?? false}
+      id={id ? `${id}-container` : undefined}
+      className="mx-filter-item"
+    >
+      <AccordionTitle>
+        {collapsible.title}
+        {collapsible.counter && count > 0 && (
+          <span className="mx-tag" aria-live="polite">
+            {count}
+          </span>
+        )}
+        <span className="mx-icon mx-icon--chevron-down" aria-hidden="true" />
+      </AccordionTitle>
+      <AccordionContent>{fieldContent}</AccordionContent>
+    </Accordion>
+  )
+}
+
+export default FilterItem

package/src/Component/Filters/Filters.figma.ts

@@ -0,0 +1,43 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=96-431
+// source=src/Component/Filters/Filters.tsx
+// component=Filters
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const collapsible = instance.getEnum("Collapsible", { Off: false, On: true })
+const content = instance.getSlot("Content")
+
+const collapsibleProp = collapsible ? " collapsible" : ""
+
+// `actions` (ReactNode[]) gets the same real-Figma-representation-but-fixed-code-
+// example treatment as Carousel's `items` — a real "Actions" SLOT exists so designers
+// can compose/reorder the button row visually, but the exported code is a fixed
+// array literal, not read from the slot (a rendered slot has no clean per-item
+// boundary to split back into an array). The two buttons are shown here as real
+// `Button` component instances (Figma has no separate "raw HTML button" component
+// and they render identically), but the real React usage (Filters.stories.tsx) is
+// raw `<button className="mx-button mx-button--dark/light">` — NOT the `Button`
+// component — so the code example matches that, not the Figma instances.
+const actions = figma.code`[
+  <button key="apply" type="submit" className="mx-button mx-button--dark">
+    Apply filters
+  </button>,
+  <button key="clear" type="reset" className="mx-button mx-button--light">
+    Clear all filters
+  </button>,
+]`
+
+// `direction="right"` is explicitly marked unsupported in the component's own JSDoc
+// ("'right' is not yet supported") — omitted rather than modelled, since there's no
+// honest visual for a documented-incomplete state. `counter` shown as a real prop
+// here, but the badge count itself is derived from live form state at runtime, not
+// settable. `items` (ReactNode[]) not modelled, same reasoning as Carousel's `items`.
+export default {
+  example: figma.code`<Filters title="Filters" direction="down" counter${collapsibleProp} actions={${actions}}>${content}</Filters>`,
+  imports: ['import { Filters } from "@pnx-mixtape/mxds/react"'],
+  id: "filters",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Filters/Filters.stories.ts

@@ -15,6 +15,7 @@ import Button from "../../Atom/Button/button.twig"
 import "../../Form/form.css"
 import "../Accordion/accordion.css"
 import "../Tag/tag.css"
+import { modes } from "../../../.storybook/modes"
 
 /**
  * A Filters form.
@@ -73,9 +74,9 @@ const meta: Meta<FiltersType> = {
             label: "Publications",
             value: "publications",
           }),
-        ],
+        ].join(""),
       }),
-    ],
+    ].join(""),
     actions: [
       Button({
         as: "submit",
@@ -87,7 +88,7 @@ const meta: Meta<FiltersType> = {
         title: "Clear all filters",
         modifiers: [ButtonModifiers.LIGHT],
       }),
-    ],
+    ].join(""),
   },
   argTypes: {
     title: {
@@ -132,30 +133,40 @@ const meta: Meta<FiltersType> = {
       if: { arg: "collapsible", truthy: true },
     },
     actions: {
-      description: "The submit/reset [Buttons](/?path=/docs/atom-button--docs).",
+      description:
+        "A concatenated string of the submit/reset [Buttons](/?path=/docs/atom-button--docs).",
       type: {
         name: "other",
         required: true,
-        value: "array",
+        value: "string",
       },
       table: {
-        type: { summary: "Button[]" },
+        type: { summary: "string" },
         subcategory: "Filter content",
       },
     },
     items: {
-      description: "The list of [FilterItems](/?path=/docs/component-filters-filteritem--docs).",
+      description:
+        "A concatenated string of [FilterItems](/?path=/docs/component-filters-filteritem--docs).",
       type: {
         name: "other",
         required: true,
-        value: "array",
+        value: "string",
       },
       table: {
-        type: { summary: "FilterItem[]" },
+        type: { summary: "string" },
         subcategory: "Filter content",
       },
     },
   },
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
+      },
+    },
+  },
 }
 
 export default meta
@@ -196,10 +207,9 @@ export const CollapsibleCounter: Story = {
           counter: true,
           open: true,
         },
-        shownItems: 2,
         id: "filter-categories",
         as: "fieldset",
-        fields: [
+        visibleFields: [
           InputCheckbox({
             id: "category-news",
             name: "categories",
@@ -214,15 +224,16 @@ export const CollapsibleCounter: Story = {
             value: "media",
             checked: true,
           }),
-          InputCheckbox({
-            id: "category-publications",
-            name: "categories",
-            label: "Publications",
-            value: "publications",
-          }),
-        ],
+        ].join(""),
+        hiddenFields: InputCheckbox({
+          id: "category-publications",
+          name: "categories",
+          label: "Publications",
+          value: "publications",
+        }),
+        fieldCount: 3,
       }),
-    ],
+    ].join(""),
   },
 }
 
@@ -278,9 +289,9 @@ export const CollapsibleRight: Story = {
             label: "Publications",
             value: "publications",
           }),
-        ],
+        ].join(""),
       }),
-    ],
+    ].join(""),
   },
 }
 
@@ -297,6 +308,6 @@ export const Instant: Story = {
         modifiers: [ButtonModifiers.LIGHT],
         disabled: true,
       }),
-    ],
+    ].join(""),
   },
 }