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

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

@@ -0,0 +1,141 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import Component from "./Filters"
+import FilterItem from "./FilterItem"
+import FormLabel from "../../Form/Label/FormLabel"
+import { SingleCheckbox } from "../../Form/Checkbox/FormCheckbox"
+import FormText from "../../Form/TextInput/FormText"
+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"
+
+const keywordsItem = (
+  <FilterItem
+    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>}
+  />
+)
+
+const collapsibleKeywordsItem = (
+  <FilterItem
+    id="filter-keywords"
+    collapsible={{ title: "Keywords", counter: true, open: true }}
+    fields={[<FormText key="kw" id="filter-keywords" name="keywords" aria-label="Keywords" />]}
+    descriptionStart={<FormDescription id="filter-keywords">Search by keywords</FormDescription>}
+  />
+)
+
+const categoriesItem = (
+  <FilterItem
+    id="filter-categories"
+    name="categories"
+    as="fieldset"
+    label={<legend className="mx-legend">Categories</legend>}
+    fields={[
+      <SingleCheckbox key="news" name="categories" value="news">
+        News
+      </SingleCheckbox>,
+      <SingleCheckbox key="media-releases" name="categories" value="media-releases">
+        Media Releases
+      </SingleCheckbox>,
+      <SingleCheckbox key="publications" name="categories" value="publications">
+        Publications
+      </SingleCheckbox>,
+    ]}
+  />
+)
+
+const collapsibleCategoriesItem = (
+  <FilterItem
+    id="filter-categories"
+    collapsible={{ title: "Categories", counter: true, open: true }}
+    name="categories"
+    as="fieldset"
+    shownItems={2}
+    fields={[
+      <SingleCheckbox key="news" name="categories" value="news">
+        News
+      </SingleCheckbox>,
+      <SingleCheckbox key="media-releases" name="categories" value="media-releases">
+        Media Releases
+      </SingleCheckbox>,
+      <SingleCheckbox key="publications" name="categories" value="publications">
+        Publications
+      </SingleCheckbox>,
+    ]}
+  />
+)
+
+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>,
+]
+
+/**
+ * A search-refinement form built from FilterItem components. Tracks active-filter
+ * counts via FormData on change — Apply and Clear buttons are enabled only when at
+ * least one filter is active.
+ */
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  decorators: [Page],
+  component: Component,
+  args: {
+    title: "Filters",
+    action: "#",
+    collapsible: false,
+    counter: false,
+    items: [keywordsItem, categoriesItem],
+    actions,
+  },
+  argTypes: {
+    direction: {
+      control: "select",
+      options: ["down"],
+      description:
+        'Layout variant. "right" (drawer) is not yet supported in React — it requires AccordionMobile React parity.',
+    },
+    collapsible: { control: "boolean" },
+    counter: { control: "boolean" },
+    instant: { control: "boolean" },
+    sticky: { control: "boolean" },
+  },
+}
+
+export default meta
+
+export const Default: StoryObj<typeof meta> = {}
+
+/**
+ * The filter panel collapses into a `<details>` accordion on mobile (below 720px).
+ * Enable `counter` to show an active-filter badge in the summary.
+ */
+export const Collapsible: StoryObj<typeof meta> = {
+  args: {
+    collapsible: true,
+    direction: "down",
+    items: [collapsibleKeywordsItem, collapsibleCategoriesItem],
+  },
+}
+
+/**
+ * Total active-filter count shown as a tag badge next to the title.
+ * Per-item counts are shown in each collapsible FilterItem's accordion title when
+ * `collapsible.counter` is true on the item and the item has a `name` prop set.
+ */
+export const WithCounter: StoryObj<typeof meta> = {
+  args: {
+    collapsible: true,
+    counter: true,
+    direction: "down",
+    items: [collapsibleKeywordsItem, collapsibleCategoriesItem],
+  },
+}

package/src/Component/Filters/Filters.tsx

@@ -0,0 +1,176 @@
+/**
+ * Filters.
+ */
+import {
+  createContext,
+  SubmitEventHandler,
+  ChangeEventHandler,
+  FormEventHandler,
+  Fragment,
+  JSX,
+  PropsWithChildren,
+  ReactNode,
+  use,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+import classNames from "classnames"
+import useMediaQuery from "../../Utility/Hooks/useMediaQuery"
+
+type FiltersContextValue = {
+  counts: Map<string, number>
+}
+
+const FiltersContext = createContext<FiltersContextValue>({ counts: new Map() })
+
+export const useFiltersContext = (): FiltersContextValue => use(FiltersContext)
+
+type FiltersProps = PropsWithChildren & {
+  title: string
+  action?: string
+  /** Pass FilterItem components as children. */
+  items?: ReactNode[]
+  actions?: ReactNode[]
+  /** "down" = collapsible panel on mobile (uses native <details>). "right" is not yet supported. */
+  direction?: "down" | "right"
+  instant?: boolean
+  /** When true, the entire filter panel collapses into a <details> accordion on mobile. */
+  collapsible?: boolean
+  sticky?: boolean
+  /** Show a counter badge on the title with the total number of active filter groups. */
+  counter?: boolean
+  onSubmit?: SubmitEventHandler<HTMLFormElement>
+  onReset?: FormEventHandler<HTMLFormElement>
+  onChange?: ChangeEventHandler<HTMLFormElement>
+  className?: string
+  mediaQuery?: string
+}
+
+const Filters = ({
+  title,
+  action,
+  items,
+  actions,
+  direction,
+  instant = false,
+  collapsible = false,
+  sticky = false,
+  counter = false,
+  onSubmit,
+  onReset,
+  onChange,
+  className,
+  children,
+  mediaQuery = "(max-width: 720px)",
+}: FiltersProps): JSX.Element => {
+  const formRef = useRef<HTMLFormElement>(null)
+  const [counts, setCounts] = useState<Map<string, number>>(new Map())
+  const isMobile: boolean = useMediaQuery(mediaQuery)
+
+  const totalCount = useMemo(() => [...counts.values()].filter(n => n > 0).length, [counts])
+
+  const handleChange = useCallback<ChangeEventHandler<HTMLFormElement>>(
+    event => {
+      const form = formRef.current
+      if (!form) return
+      const formData = new FormData(form)
+      const next = new Map<string, number>()
+      // FormData only includes checked checkboxes / non-empty selects.
+      formData.forEach((value, key) => {
+        if (value) next.set(key, (next.get(key) ?? 0) + 1)
+      })
+      setCounts(next)
+      onChange(event)
+    },
+    [onChange],
+  )
+
+  const handleReset = useCallback<FormEventHandler<HTMLFormElement>>(
+    e => {
+      setCounts(new Map())
+      onReset?.(e)
+    },
+    [onReset],
+  )
+
+  const contextValue = useMemo(() => ({ counts }), [counts])
+
+  const titleNode = (
+    <>
+      {title}
+      {counter && totalCount > 0 && (
+        <span className="mx-tag" aria-live="polite">
+          {totalCount}
+        </span>
+      )}
+    </>
+  )
+
+  const formContent = (
+    <form
+      ref={formRef}
+      className="mx-filters__form mx-vertical-flow"
+      action={action}
+      onChangeCapture={handleChange}
+      onSubmit={onSubmit}
+      onReset={handleReset}
+    >
+      {items?.map((item, 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}>{item}</Fragment>
+      ))}
+      {children}
+      {actions && actions.length > 0 && (
+        <div className="mx-form-actions">
+          {actions.map((actionNode, 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}>{actionNode}</Fragment>
+          ))}
+        </div>
+      )}
+    </form>
+  )
+
+  const body = collapsible ? (
+    <details className="mx-accordion" open={!isMobile}>
+      <summary className="mx-accordion__toggle mx-filters__title">
+        {titleNode}
+        <span
+          className={classNames(
+            "mx-icon",
+            direction === "down" ? "mx-icon--chevron-down" : "mx-icon--chevron-right",
+          )}
+          aria-hidden="true"
+        />
+      </summary>
+      {formContent}
+    </details>
+  ) : (
+    <>
+      <h2 className="mx-filters__title">{titleNode}</h2>
+      {formContent}
+    </>
+  )
+
+  return (
+    <FiltersContext value={contextValue}>
+      <div
+        className={classNames(
+          "mx-filters",
+          direction && `mx-filters--${direction}`,
+          sticky && "mx-filters--sticky",
+          instant && "mx-filters--auto",
+          className,
+        )}
+      >
+        {body}
+      </div>
+    </FiltersContext>
+  )
+}
+
+export default Filters