@pnx-mixtape/mxds 0.1.0-rc.2 → 0.1.0-rc.3

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

@@ -1,12 +1,27 @@
 /**
  * Filters
- * @file Support filter count elements and closing the "right" variant on mobile..
+ * @file Support filter count elements and closing the "right" variant on mobile.
+ *
+ * The `pending` property is fully consumer-controlled — there's no promise to
+ * await here, only a native `submit` event — so intercept the form's submit,
+ * set `el.pending = true` before your fetch/navigation, and `= false` once it
+ * settles. It reflects `aria-busy` on the form, the same contract the React
+ * implementation exposes: one attribute drives both the assistive-tech signal
+ * and the spinner (see the generic `[aria-busy="true"]` utility in
+ * Utility/utilities.css).
+ *
+ * `mx-filters--auto` (the `instant` prop) auto-submits the form as filters
+ * change — immediately for checkbox/radio/select fields, debounced for text
+ * fields — and on reset. The consumer still needs to intercept the form's
+ * `submit` event and call `preventDefault()` to avoid a real page navigation,
+ * same as manual submission, but now it can fire on every keystroke.
  */
 
 import { createFocusTrap, FocusTrap } from "focus-trap"
 import "../../Accordion/Elements/Accordion"
 import "../../Accordion/Elements/AccordionMobile"
 import { validators } from "../../../Utility/utilities"
+import { DEBOUNCE_MS } from "../../../enums"
 
 type EntryType = {
   item: HTMLElement
@@ -25,6 +40,8 @@ export default class Filters extends HTMLElement {
   focusTrapTimeout?: ReturnType<typeof setTimeout> | null
   scrollLockClass: string = "body--scroll-lock"
   isRight?: boolean
+  isInstant?: boolean
+  instantDebounce?: ReturnType<typeof setTimeout> | null
 
   static observedAttributes = ["count"]
 
@@ -34,6 +51,7 @@ export default class Filters extends HTMLElement {
     this.controller = new AbortController()
     this.mq = this.getAttribute("mq") || "(max-width: 720px)"
     this.isRight = this.classList.contains(`mx-filters--right`)
+    this.isInstant = this.classList.contains("mx-filters--auto")
   }
 
   connectedCallback(): void {
@@ -55,6 +73,11 @@ export default class Filters extends HTMLElement {
     this.form?.addEventListener("submit", this.handleCounters, { signal })
     this.form?.addEventListener("reset", this.handleReset, { signal })
 
+    if (this.isInstant) {
+      this.addEventListener("change", this.handleInstantSubmit, { signal })
+      this.addEventListener("input", this.handleInstantSubmit, { signal })
+    }
+
     if (this.isRight) {
       this.handleBreakpoint(this.breakpoint)
       this.breakpoint.addEventListener("change", this.handleBreakpoint, {
@@ -107,6 +130,10 @@ export default class Filters extends HTMLElement {
       clearTimeout(this.timeout)
       this.timeout = null
     }
+    if (this.instantDebounce) {
+      clearTimeout(this.instantDebounce)
+      this.instantDebounce = null
+    }
 
     // Clean up focus trap timers
     if (this.rafId) {
@@ -156,6 +183,41 @@ export default class Filters extends HTMLElement {
       if (entry.counter) entry.counter.textContent = ""
     })
     this.setAttribute("count", "0")
+
+    if (this.instantDebounce) {
+      clearTimeout(this.instantDebounce)
+      this.instantDebounce = null
+    }
+    // The "reset" event fires *before* the browser actually clears field
+    // values (per the HTML reset algorithm), so requestSubmit() here would
+    // submit the stale, pre-reset state. Defer to the next task (reusing the
+    // debounce field, since any pending debounce was just cleared above), by
+    // which point the native reset has already applied.
+    if (this.isInstant) {
+      this.instantDebounce = setTimeout(() => this.form?.requestSubmit(), 0)
+    }
+  }
+
+  handleInstantSubmit = (event: Event): void => {
+    const target = event.target as HTMLInputElement | HTMLSelectElement
+    const isImmediate =
+      target instanceof HTMLSelectElement ||
+      (target instanceof HTMLInputElement && ["checkbox", "radio"].includes(target.type))
+
+    // Avoid a double-fire: only act on "change" for immediate-type fields,
+    // and only on "input" for text-type fields (native "change" on a text
+    // input only fires on blur, not per keystroke).
+    if (isImmediate !== (event.type === "change")) return
+
+    if (this.instantDebounce) {
+      clearTimeout(this.instantDebounce)
+      this.instantDebounce = null
+    }
+    if (isImmediate) {
+      this.form?.requestSubmit()
+    } else {
+      this.instantDebounce = setTimeout(() => this.form?.requestSubmit(), DEBOUNCE_MS)
+    }
   }
 
   handleCounters = (): void => {
@@ -246,6 +308,14 @@ export default class Filters extends HTMLElement {
   get breakpoint(): MediaQueryList {
     return window.matchMedia(this.mq)
   }
+
+  get pending(): boolean {
+    return this.form?.getAttribute("aria-busy") === "true"
+  }
+
+  set pending(value: boolean) {
+    this.form?.setAttribute("aria-busy", String(value))
+  }
 }
 
 if (!customElements.get("mx-filters")) customElements.define("mx-filters", Filters)

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

@@ -88,7 +88,8 @@ const meta: Meta<MxFilterItemType> = {
     },
     as: {
       description: "Optionally create a fieldset wrapper, for checkboxes and radio fields.",
-      options: ["div, fieldset"],
+      options: ["div", "fieldset"],
+      control: "radio",
       table: {
         type: { summary: "string" },
         defaultValue: { summary: "div" },

package/src/Component/Filters/FilterItem.tsx

@@ -59,7 +59,7 @@ const FilterItem = ({
   )
 
   const fieldContent = (
-    <Tag className={itemClass} {...(id ? { id } : {})}>
+    <Tag className={itemClass} id={id ? `${id}-item` : undefined}>
       {label}
       {descriptionStart}
       {fields.length > 0 ? (

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

@@ -24,7 +24,7 @@ const actions = figma.code`[
     Apply filters
   </button>,
   <button key="clear" type="reset" className="mx-button mx-button--light">
-    Clear all filters
+    Clear all
   </button>,
 ]`
 

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

@@ -1,4 +1,5 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
+import { expect, waitFor } from "storybook/test"
 import Component from "./filters.twig"
 import FilterItem from "./filter-item.twig"
 import "./Elements/Filters"
@@ -85,7 +86,7 @@ const meta: Meta<FiltersType> = {
       }),
       Button({
         as: "reset",
-        title: "Clear all filters",
+        title: "Clear all",
         modifiers: [ButtonModifiers.LIGHT],
       }),
     ].join(""),
@@ -296,7 +297,14 @@ export const CollapsibleRight: Story = {
 }
 
 /**
- * Instant is currently just an example without a submit button, where some custom javascript handles dynamically submitting (eg. ajax).
+ * `instant` auto-submits the form as filters change: immediately for
+ * checkbox/radio/select fields, debounced (~400ms) for text fields so a fast
+ * typist doesn't trigger a submit per keystroke. Reset also auto-submits.
+ * There's no submit button here - some other UI (e.g. a live result count)
+ * signals that results updated, since there's nothing to click. As with
+ * manual submission, the consumer still needs to intercept the form's
+ * `submit` event and call `preventDefault()` to avoid a real page
+ * navigation - this matters more here since it can fire on every keystroke.
  */
 export const Instant: Story = {
   args: {
@@ -304,10 +312,94 @@ export const Instant: Story = {
     actions: [
       Button({
         as: "reset",
-        title: "Clear all filters",
+        title: "Clear all",
         modifiers: [ButtonModifiers.LIGHT],
         disabled: true,
       }),
     ].join(""),
   },
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    const root = canvasElement.querySelector("mx-filters")
+    const form = root?.querySelector("form")
+    if (!root || !form) throw new Error("mx-filters > form not found")
+
+    let submitCount = 0
+    form.addEventListener("submit", event => {
+      event.preventDefault()
+      submitCount += 1
+    })
+
+    await step("Checking a checkbox submits immediately", async () => {
+      await userEvent.click(canvas.getByRole("checkbox", { name: "News" }))
+      await waitFor(() => expect(submitCount).toBe(1))
+    })
+
+    await step("Typing debounces before submitting", async () => {
+      const input = canvas.getByRole("textbox", { name: "Keywords" })
+      await userEvent.type(input, "abc")
+      expect(submitCount).toBe(1)
+      await waitFor(() => expect(submitCount).toBe(2), { timeout: 1000 })
+    })
+
+    await step("An immediate change cancels a pending debounce", async () => {
+      const input = canvas.getByRole("textbox", { name: "Keywords" })
+      await userEvent.type(input, "d")
+      await userEvent.click(canvas.getByRole("checkbox", { name: "Media Releases" }))
+      await waitFor(() => expect(submitCount).toBe(3))
+      // Give the (cancelled) debounce window time to prove it doesn't also fire.
+      await new Promise(resolve => setTimeout(resolve, 600))
+      expect(submitCount).toBe(3)
+    })
+
+    await step("Reset auto-submits", async () => {
+      await userEvent.click(canvas.getByRole("button", { name: "Clear all" }))
+      await waitFor(() => expect(submitCount).toBe(4))
+    })
+  },
+}
+
+// Demonstrates the built-in pending state: intercepting the form's `submit`
+// event and toggling the consumer-controlled `pending` property (see
+// Elements/Filters.ts) around a simulated fetch delay. The Web Component
+// reflects that as `aria-busy` on the form - the same attribute React's
+// implementation sets. A single generic CSS rule (`[aria-busy="true"]` in
+// Utility/utilities.css) drives the spinner for both, and for any other
+// component that reflects `aria-busy`.
+export const Pending: Story = {
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    const root = canvasElement.querySelector("mx-filters")
+    const form = root?.querySelector("form")
+    if (!root || !form) throw new Error("mx-filters > form not found")
+
+    form.addEventListener("submit", event => {
+      event.preventDefault()
+      root.pending = true
+      setTimeout(() => {
+        root.pending = false
+      }, 150)
+    })
+
+    const submitButton = canvas.getByRole("button", { name: "Apply filters" })
+
+    // The submit button starts disabled until a filter is active (see
+    // Elements/Filters.ts's `count` handling) - check one first.
+    await step("Checking a filter enables Apply", async () => {
+      await userEvent.click(canvas.getByRole("checkbox", { name: "News" }))
+      await waitFor(() => expect(submitButton).toBeEnabled())
+    })
+
+    await step("Shows a pending state while the simulated submit resolves", async () => {
+      await userEvent.click(submitButton)
+      await expect(form).toHaveAttribute("aria-busy", "true")
+    })
+
+    await step("Clears pending once the submit settles", async () => {
+      await waitFor(() => expect(form).toHaveAttribute("aria-busy", "false"), { timeout: 2000 })
+    })
+
+    await step("Reset back to no active filters", async () => {
+      await userEvent.click(canvas.getByRole("button", { name: "Clear all" }))
+      await waitFor(() => expect(submitButton).toBeDisabled())
+    })
+  },
 }

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

@@ -1,5 +1,7 @@
+import { JSX } from "react"
 import { Meta, StoryObj } from "@storybook/react-vite"
-import Component from "./Filters"
+import { expect, waitFor } from "storybook/test"
+import Component, { useFiltersContext } from "./Filters"
 import FilterItem from "./FilterItem"
 import FormLabel from "../../Form/Label/FormLabel"
 import { SingleCheckbox } from "../../Form/Checkbox/FormCheckbox"
@@ -10,6 +12,7 @@ import "../Accordion/accordion.css"
 import "../Tag/tag.css"
 import "../../Form/form.css"
 import { Page } from "../../../.storybook-react/decorators"
+import { modes } from "../../../.storybook/modes"
 
 const keywordsItem = (
   <FilterItem
@@ -70,14 +73,25 @@ const collapsibleCategoriesItem = (
   />
 )
 
-const actions = [
-  <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>,
-]
+// Reads pending/empty state from FiltersContext to disable Apply/Clear the
+// same way the Web Component does via its `count` attribute: both buttons
+// are disabled while no filter is active, and while a submit is pending.
+const FilterActions = ({ hideSubmit = false }: { hideSubmit?: boolean }): JSX.Element => {
+  const { pending, totalCount } = useFiltersContext()
+  const disabled = pending || totalCount === 0
+  return (
+    <>
+      {!hideSubmit && (
+        <button type="submit" className="mx-button mx-button--dark" disabled={disabled}>
+          Apply filters
+        </button>
+      )}
+      <button type="reset" className="mx-button mx-button--light" disabled={disabled}>
+        Clear all
+      </button>
+    </>
+  )
+}
 
 /**
  * A search-refinement form built from FilterItem components. Tracks active-filter
@@ -94,25 +108,56 @@ const meta: Meta<typeof Component> = {
     collapsible: false,
     counter: false,
     items: [keywordsItem, categoriesItem],
-    actions,
+    actions: [<FilterActions key="apply" />],
   },
   argTypes: {
     direction: {
       control: "select",
-      options: ["down"],
-      description:
-        'Layout variant. "right" (drawer) is not yet supported in React — it requires AccordionMobile React parity.',
+      options: ["down", "right"],
+      description: "Layout variant for mobile.",
     },
     collapsible: { control: "boolean" },
     counter: { control: "boolean" },
-    instant: { control: "boolean" },
+    instant: {
+      control: "boolean",
+      description:
+        "Auto-submits the form as filters change (immediately for checkbox/radio/select, debounced for text) and on reset.",
+    },
     sticky: { control: "boolean" },
   },
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
+      },
+    },
+  },
 }
 
 export default meta
 
-export const Default: StoryObj<typeof meta> = {}
+export const Default: StoryObj<typeof meta> = {
+  play: async ({ canvas, userEvent, step }) => {
+    const input = canvas.getByRole("checkbox", { name: "News" })
+    const submit = canvas.getByRole("button", { name: "Apply filters" })
+    const clear = canvas.getByRole("button", { name: "Clear all" })
+    await step("Starts with disabled buttons", async () => {
+      await waitFor(() => expect(submit).toBeDisabled())
+      await waitFor(() => expect(clear).toBeDisabled())
+    })
+    await step("Buttons activate after interaction", async () => {
+      await userEvent.click(input)
+      await waitFor(() => expect(submit).not.toBeDisabled())
+      await waitFor(() => expect(clear).not.toBeDisabled())
+    })
+    await step("Restore original state", async () => {
+      await userEvent.click(input)
+      await waitFor(() => expect(submit).toBeDisabled())
+      await waitFor(() => expect(clear).toBeDisabled())
+    })
+  },
+}
 
 /**
  * The filter panel collapses into a `<details>` accordion on mobile (below 720px).
@@ -124,6 +169,78 @@ export const Collapsible: StoryObj<typeof meta> = {
     direction: "down",
     items: [collapsibleKeywordsItem, collapsibleCategoriesItem],
   },
+  play: async ({ canvasElement, userEvent, step }) => {
+    const summary = canvasElement.querySelector("summary")
+    const details = canvasElement.querySelector("details")
+    if (!summary || !details) throw new Error("details/summary not found")
+    const isMobile = matchMedia("(max-width: 767px)").matches
+    if (!isMobile) {
+      await step("Is open on desktop", async () => {
+        await waitFor(() => expect(details).toHaveAttribute("open"))
+      })
+    } else {
+      await step("Starts closed on mobile", async () => {
+        await waitFor(() => expect(details).not.toHaveAttribute("open"))
+      })
+      await step("Opens and closes", async () => {
+        await userEvent.click(summary)
+        await waitFor(() => expect(details).toHaveAttribute("open"))
+        await userEvent.click(summary)
+        await waitFor(() => expect(details).not.toHaveAttribute("open"))
+      })
+    }
+  },
+}
+
+/**
+ * The filter panel collapses into a `<details>` accordion on mobile (below 720px).
+ * But opens as an off-canvas drawer instead of normal accordion.
+ */
+export const CollapsibleRight: StoryObj<typeof meta> = {
+  args: {
+    collapsible: true,
+    direction: "right",
+    items: [collapsibleKeywordsItem, collapsibleCategoriesItem],
+  },
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    const summary = canvasElement.querySelector("summary")
+    const details = canvasElement.querySelector("details")
+    if (!summary || !details) throw new Error("details/summary not found")
+    const isMobile = matchMedia("(max-width: 767px)").matches
+    if (!isMobile) {
+      await step("Is open on desktop", async () => {
+        await waitFor(() => expect(details).toHaveAttribute("open"))
+      })
+    } else {
+      await step("Starts closed on mobile", async () => {
+        await waitFor(() => expect(details).not.toHaveAttribute("open"))
+      })
+
+      await step("Typed input survives closing the drawer", async () => {
+        await userEvent.click(summary)
+        await waitFor(() => expect(details).toHaveAttribute("open"))
+
+        const input = canvas.getByRole("textbox", { name: "Keywords" })
+        await userEvent.type(input, "hello")
+        await waitFor(() => expect(input).toHaveValue("hello"))
+
+        await userEvent.click(canvas.getByRole("button", { name: "Close filters" }))
+        await waitFor(() => expect(details).not.toHaveAttribute("open"))
+
+        await userEvent.click(summary)
+        await waitFor(() => expect(details).toHaveAttribute("open"))
+        await waitFor(() =>
+          expect(canvas.getByRole("textbox", { name: "Keywords" })).toHaveValue("hello"),
+        )
+      })
+
+      await step("Restore original state", async () => {
+        await userEvent.clear(canvas.getByRole("textbox", { name: "Keywords" }))
+        await userEvent.click(canvas.getByRole("button", { name: "Close filters" }))
+        await waitFor(() => expect(details).not.toHaveAttribute("open"))
+      })
+    }
+  },
 }
 
 /**
@@ -133,9 +250,121 @@ export const Collapsible: StoryObj<typeof meta> = {
  */
 export const WithCounter: StoryObj<typeof meta> = {
   args: {
-    collapsible: true,
     counter: true,
-    direction: "down",
     items: [collapsibleKeywordsItem, collapsibleCategoriesItem],
   },
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    const input = canvas.getByRole("checkbox", { name: "News" })
+    await step("Starts with no count", async () => {
+      const count = canvasElement.querySelectorAll(".mx-tag")
+      await waitFor(() => expect(count).toHaveLength(0))
+    })
+    await step("Count is added after interaction", async () => {
+      await userEvent.click(input)
+      const count = canvasElement.querySelectorAll(".mx-tag")
+      await waitFor(() => expect(count).toHaveLength(2))
+    })
+    await step("Restore original state", async () => {
+      await userEvent.click(input)
+      const count = canvasElement.querySelectorAll(".mx-tag")
+      await waitFor(() => expect(count).toHaveLength(0))
+    })
+  },
+}
+
+// `instant` auto-submits the form as filters change: immediately for
+// checkbox/radio/select fields, debounced (~400ms) for text fields so a fast
+// typist doesn't trigger a submit per keystroke. Reset also auto-submits. As
+// with manual submission, `onSubmit` must call `event.preventDefault()` to
+// avoid a real page navigation - this matters more here since it can fire on
+// every keystroke.
+export const Instant: StoryObj<typeof meta> = {
+  args: {
+    instant: true,
+    actions: [<FilterActions hideSubmit={true} key="clear" />],
+    onSubmit: event => {
+      event.preventDefault()
+    },
+  },
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    const form = canvasElement.querySelector(".mx-filters__form")
+    if (!form) throw new Error("mx-filters__form not found")
+    let submitCount = 0
+    form.addEventListener("submit", () => {
+      submitCount += 1
+    })
+
+    await step("Checking a checkbox submits immediately", async () => {
+      await userEvent.click(canvas.getByRole("checkbox", { name: "News" }))
+      await waitFor(() => expect(submitCount).toBe(1))
+    })
+
+    await step("Typing debounces before submitting", async () => {
+      const input = canvas.getByRole("textbox", { name: "Keywords" })
+      await userEvent.type(input, "abc")
+      expect(submitCount).toBe(1)
+      await waitFor(() => expect(submitCount).toBe(2), { timeout: 1000 })
+    })
+
+    await step("An immediate change cancels a pending debounce", async () => {
+      const input = canvas.getByRole("textbox", { name: "Keywords" })
+      await userEvent.type(input, "d")
+      await userEvent.click(canvas.getByRole("checkbox", { name: "Media Releases" }))
+      await waitFor(() => expect(submitCount).toBe(3))
+      // Give the (cancelled) debounce window time to prove it doesn't also fire.
+      await new Promise(resolve => setTimeout(resolve, 600))
+      expect(submitCount).toBe(3)
+    })
+
+    await step("Reset auto-submits", async () => {
+      await userEvent.click(canvas.getByRole("button", { name: "Clear all" }))
+      await waitFor(() => expect(submitCount).toBe(4))
+      // The Keywords field is a controlled input with its own local state
+      // (FormText) - a native form reset doesn't fire its onChange, so
+      // React's next render re-applies the stale typed value over the
+      // reset DOM. Clear it for real so the story ends in a stable state.
+      const input = canvas.getByRole("textbox", { name: "Keywords" })
+      await userEvent.clear(input)
+      await waitFor(() => expect(submitCount).toBe(5), { timeout: 1000 })
+    })
+  },
+}
+
+// Demonstrates the built-in pending state: `onSubmit` returns a promise
+// (standing in for a real fetch/router navigation), so the component sets
+// `aria-busy` on the form until it resolves. A generic CSS rule
+// (`[aria-busy="true"]` in Utility/utilities.css) shows the spinner - no
+// component-specific markup or class needed.
+export const Pending: StoryObj<typeof meta> = {
+  args: {
+    onSubmit: event => {
+      event.preventDefault()
+      return new Promise(resolve => setTimeout(resolve, 800))
+    },
+  },
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    const form = canvasElement.querySelector(".mx-filters__form")
+    if (!form) throw new Error("mx-filters__form not found")
+    const submitButton = canvas.getByRole("button", { name: "Apply filters" })
+
+    // Apply/Clear start disabled until a filter is active (see FilterActions).
+    await step("Checking a filter enables Apply", async () => {
+      await userEvent.click(canvas.getByRole("checkbox", { name: "News" }))
+      await waitFor(() => expect(submitButton).toBeEnabled())
+    })
+
+    await step("Shows a pending spinner while the submit resolves", async () => {
+      await userEvent.click(submitButton)
+      await expect(form).toHaveAttribute("aria-busy", "true")
+    })
+
+    await step("Clears pending once the submit settles", async () => {
+      await waitFor(
+        () => {
+          expect(form).toHaveAttribute("aria-busy", "false")
+        },
+        { timeout: 2000 },
+      )
+    })
+  },
 }