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

package/src/Form/Autocomplete/Autocomplete.stories.ts

@@ -0,0 +1,213 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import { expect, waitFor } from "storybook/test"
+import Component from "./autocomplete.twig"
+import "./autocomplete.css"
+import "./Elements/Autocomplete"
+import type { AutocompleteSearchEvent } from "./Elements/Autocomplete"
+
+const fruits = [
+  "Apple",
+  "Apricot",
+  "Avocado",
+  "Banana",
+  "Blackberry",
+  "Blueberry",
+  "Cherry",
+  "Coconut",
+  "Cranberry",
+  "Fig",
+  "Grape",
+  "Grapefruit",
+  "Guava",
+  "Kiwifruit",
+  "Lemon",
+  "Lime",
+  "Mango",
+  "Nectarine",
+  "Orange",
+  "Papaya",
+  "Passionfruit",
+  "Peach",
+  "Pear",
+  "Pineapple",
+  "Plum",
+  "Pomegranate",
+  "Raspberry",
+  "Strawberry",
+  "Watermelon",
+].map(label => ({ label, value: label.toLowerCase() }))
+
+type AutocompleteTwigProps = {
+  id: string
+  name?: string
+  options: { label: string; value: string }[]
+  value?: string
+  label: string
+  type: "text" | "search"
+  placeholder?: string
+  required?: boolean
+  status?: "default" | "valid" | "invalid"
+  noResultsLabel?: string
+}
+
+// Stands in for the app code a real project would write: listens for the
+// query the component dispatches and populates the listbox itself (here from
+// an in-memory list; in a real app this would be a debounced REST or
+// Elasticsearch call). The component never filters anything on its own.
+// Storybook requires `mount` to be destructured directly in each play
+// function's own signature (it's detected via static analysis), so this only
+// covers the part that can be shared - each play function still calls
+// `mount()` itself before wiring this up.
+const wireSearchDemo = (canvasElement: HTMLElement, id: string): void => {
+  const root = canvasElement.querySelector<HTMLElement>("mx-autocomplete")
+  const listbox = root?.querySelector<HTMLUListElement>('[role="listbox"]')
+  if (!root || !listbox) return
+
+  // Each keystroke fires its own search event - cancel the previous one's
+  // pending response so a stale, since-superseded query can't land after a
+  // newer one, which would yank the currently-tracked active option out from
+  // under the widget mid-interaction.
+  let pending: ReturnType<typeof setTimeout> | null = null
+
+  root.addEventListener("mx-autocomplete-search", event => {
+    if (pending) clearTimeout(pending)
+    const { query } = (event as AutocompleteSearchEvent).detail
+    const matches = query
+      ? fruits.filter(fruit => fruit.label.toLowerCase().includes(query.toLowerCase()))
+      : []
+
+    // Simulate the latency of a real search API.
+    pending = setTimeout(() => {
+      listbox.replaceChildren(
+        ...matches.map((option, index) => {
+          const li = document.createElement("li")
+          li.className = "mx-autocomplete__option"
+          li.id = `${id}-option-${index}`
+          li.setAttribute("role", "option")
+          li.setAttribute("aria-selected", "false")
+          li.dataset.value = option.value
+          li.textContent = option.label
+          return li
+        }),
+      )
+    }, 150)
+  })
+}
+
+const meta: Meta<AutocompleteTwigProps> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    id: "autocomplete-fruit",
+    name: "fruit",
+    type: "text",
+    label: "Choose a fruit",
+    placeholder: "Start typing a fruit…",
+    // Starts empty: the component doesn't filter anything itself, it's
+    // populated below in response to `mx-autocomplete-search`.
+    options: [],
+  },
+  argTypes: {
+    status: {
+      control: { type: "radio" },
+      options: ["default", "valid", "invalid"],
+    },
+    type: {
+      control: { type: "radio" },
+      options: ["text", "search"],
+    },
+  },
+  parameters: {
+    docs: {
+      story: {
+        autoplay: true,
+      },
+    },
+  },
+  play: async ({ canvasElement, args, mount }) => {
+    await mount()
+    wireSearchDemo(canvasElement, args.id)
+  },
+}
+
+export default meta
+type Story = StoryObj<AutocompleteTwigProps>
+
+export const Autocomplete: Story = {
+  play: async ({ canvasElement, args, mount, canvas, userEvent, step }) => {
+    await mount()
+    wireSearchDemo(canvasElement, args.id)
+    const input = canvas.getByRole("combobox", { name: "Choose a fruit" })
+
+    await step("Starts closed", async () => {
+      await expect(input).toHaveAttribute("aria-expanded", "false")
+    })
+
+    // "lu" matches exactly two fruits: Blueberry, then Plum.
+    await step("Typing opens the listbox with matches", async () => {
+      await userEvent.type(input, "lu")
+      await waitFor(
+        () => {
+          expect(input).toHaveAttribute("aria-expanded", "true")
+          expect(canvas.getByRole("option", { name: "Blueberry" })).toBeInTheDocument()
+          expect(canvas.getByRole("option", { name: "Plum" })).toBeInTheDocument()
+        },
+        { timeout: 2000 },
+      )
+    })
+
+    await step("ArrowDown/ArrowUp move aria-activedescendant, with wraparound", async () => {
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(input).toHaveAttribute("aria-activedescendant", `${args.id}-option-0`)
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(input).toHaveAttribute("aria-activedescendant", `${args.id}-option-1`)
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(input).toHaveAttribute("aria-activedescendant", `${args.id}-option-0`)
+      await userEvent.keyboard("{ArrowUp}")
+      await expect(input).toHaveAttribute("aria-activedescendant", `${args.id}-option-1`)
+    })
+
+    await step("Enter selects the active option and closes", async () => {
+      await userEvent.keyboard("{Enter}")
+      await expect(input).toHaveValue("Plum")
+      await expect(input).toHaveAttribute("aria-expanded", "false")
+    })
+
+    await step("Escape reopens then closes without changing the value", async () => {
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(input).toHaveAttribute("aria-expanded", "true")
+      await userEvent.keyboard("{Escape}")
+      await expect(input).toHaveAttribute("aria-expanded", "false")
+      await expect(input).toHaveValue("Plum")
+    })
+
+    await step("Reset: clear the input back to empty", async () => {
+      await userEvent.clear(input)
+      await expect(input).toHaveValue("")
+      await expect(input).toHaveAttribute("aria-expanded", "false")
+      await waitFor(() => expect(canvas.queryByRole("option")).not.toBeInTheDocument(), {
+        timeout: 2000,
+      })
+      // Clear focus.
+      await userEvent.click(canvasElement)
+    })
+  },
+}
+
+export const Required: Story = {
+  args: {
+    required: true,
+  },
+}
+
+export const Invalid: Story = {
+  args: {
+    status: "invalid",
+  },
+}
+
+export const Search: Story = {
+  args: {
+    type: "search",
+  },
+}

package/src/Form/Autocomplete/Autocomplete.stories.tsx

@@ -0,0 +1,149 @@
+import { useState } from "react"
+import { Meta, StoryObj } from "@storybook/react-vite"
+import { expect } from "storybook/test"
+import Component, { AutocompleteOption } from "./Autocomplete"
+import "./autocomplete.css"
+import { Page } from "../../../.storybook-react/decorators"
+import { FormStatus } from "../../enums"
+
+const fruits = [
+  "Apple",
+  "Apricot",
+  "Avocado",
+  "Banana",
+  "Blackberry",
+  "Blueberry",
+  "Cherry",
+  "Coconut",
+  "Cranberry",
+  "Fig",
+  "Grape",
+  "Grapefruit",
+  "Guava",
+  "Kiwifruit",
+  "Lemon",
+  "Lime",
+  "Mango",
+  "Nectarine",
+  "Orange",
+  "Papaya",
+  "Passionfruit",
+  "Peach",
+  "Pear",
+  "Pineapple",
+  "Plum",
+  "Pomegranate",
+  "Raspberry",
+  "Strawberry",
+  "Watermelon",
+].map(label => ({ label, value: label.toLowerCase() }))
+
+const meta: Meta<typeof Component> = {
+  decorators: [Page],
+  component: Component,
+  argTypes: {
+    status: {
+      control: { type: "radio" },
+      options: ["default", "valid", "invalid"],
+    },
+    type: {
+      control: { type: "radio" },
+      options: ["text", "search"],
+    },
+  },
+  args: {
+    id: "autocomplete-fruit",
+    name: "fruit",
+    type: "text",
+    label: "Choose a fruit",
+    placeholder: "Start typing a fruit…",
+  },
+  // Stands in for what a real app would do: own the result set and however
+  // it's produced (here a local substring filter; just as easily a debounced
+  // REST or Elasticsearch call), and feed it back in via `options`. The
+  // component itself never filters or fetches anything.
+  render: args => {
+    const [options, setOptions] = useState<AutocompleteOption[]>([])
+
+    const handleSearch = (query: string): void => {
+      setOptions(
+        query
+          ? fruits.filter(fruit => fruit.label.toLowerCase().includes(query.toLowerCase()))
+          : [],
+      )
+    }
+
+    return (
+      <Component {...args} options={options} onSearch={handleSearch}>
+        {null}
+      </Component>
+    )
+  },
+}
+
+export default meta
+export const Autocomplete: StoryObj<typeof meta> = {
+  play: async ({ canvas, userEvent, step }) => {
+    const input = canvas.getByRole("combobox", { name: "Choose a fruit" })
+
+    await step("Starts closed", async () => {
+      await expect(input).toHaveAttribute("aria-expanded", "false")
+    })
+
+    // "lu" matches exactly two fruits: Blueberry, then Plum.
+    await step("Typing opens the listbox with matches", async () => {
+      await userEvent.type(input, "lu")
+      await expect(input).toHaveAttribute("aria-expanded", "true")
+      await expect(canvas.getByRole("option", { name: "Blueberry" })).toBeInTheDocument()
+      await expect(canvas.getByRole("option", { name: "Plum" })).toBeInTheDocument()
+    })
+
+    await step("ArrowDown/ArrowUp move aria-activedescendant, with wraparound", async () => {
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(input).toHaveAttribute("aria-activedescendant", `${input.id}-option-0`)
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(input).toHaveAttribute("aria-activedescendant", `${input.id}-option-1`)
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(input).toHaveAttribute("aria-activedescendant", `${input.id}-option-0`)
+      await userEvent.keyboard("{ArrowUp}")
+      await expect(input).toHaveAttribute("aria-activedescendant", `${input.id}-option-1`)
+    })
+
+    await step("Enter selects the active option and closes", async () => {
+      await userEvent.keyboard("{Enter}")
+      await expect(input).toHaveValue("Plum")
+      await expect(input).toHaveAttribute("aria-expanded", "false")
+    })
+
+    await step("Escape reopens then closes without changing the value", async () => {
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(input).toHaveAttribute("aria-expanded", "true")
+      await userEvent.keyboard("{Escape}")
+      await expect(input).toHaveAttribute("aria-expanded", "false")
+      await expect(input).toHaveValue("Plum")
+    })
+
+    await step("Reset: clear the input back to empty", async () => {
+      await userEvent.clear(input)
+      await expect(input).toHaveValue("")
+    })
+  },
+}
+
+export const Required: StoryObj<typeof meta> = {
+  args: {
+    required: true,
+  },
+}
+
+export const Invalid: StoryObj<typeof meta> = {
+  args: {
+    status: FormStatus.INVALID,
+  },
+}
+
+export const Search: StoryObj<typeof meta> = {
+  args: {
+    type: "search",
+  },
+}

package/src/Form/Autocomplete/Autocomplete.tsx

@@ -0,0 +1,272 @@
+import {
+  JSX,
+  ComponentPropsWithoutRef,
+  ChangeEventHandler,
+  KeyboardEventHandler,
+  MouseEventHandler,
+  useEffect,
+  useRef,
+  ReactNode,
+} from "react"
+import classNames from "classnames"
+import { useComboBoxState, Item } from "react-stately"
+import { FormStatus } from "../../enums"
+
+export type AutocompleteOption = {
+  label: string
+  value: string
+}
+
+export type AutocompleteProps = Omit<ComponentPropsWithoutRef<"input">, "value" | "onSelect"> & {
+  id: string
+  /**
+   * The current results to display — this component does not filter or fetch
+   * them itself. Update this prop (typically from `onSearch`) with whatever
+   * matches the query, whether that's a local substring filter, a debounced
+   * REST call, or an Elasticsearch query.
+   */
+  options: AutocompleteOption[]
+  type: "text" | "search"
+  label: string
+  value?: string
+  status?: FormStatus
+  className?: string
+  noResultsLabel?: string
+  hideOnBlur?: boolean
+  /** Called on every keystroke with the trimmed input value — do the actual search here (debounce it yourself) and feed the results back in via `options`. */
+  onSearch?: (query: string) => void
+  onSelect?: (option: AutocompleteOption) => void
+  onSubmit?: MouseEventHandler<HTMLButtonElement>
+  children?: ReactNode
+}
+
+// The listbox never takes focus (aria-activedescendant keeps focus on the
+// input), so a mousedown here would otherwise blur the input and close the
+// list before the resulting click can select an option.
+const handleListboxMouseDown: MouseEventHandler<HTMLUListElement> = event => {
+  event.preventDefault()
+}
+
+const Autocomplete = ({
+  id,
+  options,
+  value = "",
+  label,
+  type = "text",
+  status = FormStatus.DEFAULT,
+  className = "",
+  noResultsLabel = "No results found",
+  hideOnBlur = true,
+  onSearch,
+  onSelect,
+  onSubmit,
+  children,
+  ...props
+}: AutocompleteProps): JSX.Element => {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const listboxRef = useRef<HTMLUListElement>(null)
+
+  // `useComboBoxState` gives us the collection (for Home/End/next/prev key
+  // lookups), focused-key tracking, and input-value tracking, replacing
+  // manual index math - but we skip `useComboBox` itself, since it assumes a
+  // floating popover (it unconditionally aria-hides the rest of the page
+  // while open via `ariaHideOutside`) and auto-generates option ids we can't
+  // influence to match the `${id}-option-{index}` scheme the Twig side also
+  // uses. `state.collection` only reflects live `items` while `state.isOpen`
+  // is true (it freezes on the last collection while closed, to avoid the
+  // displayed list changing mid-close-animation), so we still drive isOpen
+  // via `state.open()`/`state.toggle()` - but never `state.close()`, which is
+  // aliased to `commitValue` and resets `inputValue` to the react-stately
+  // selection system's own idea of what's "selected" (something we never
+  // populate, since selection is handled by our own `handleSelect` below).
+  const state = useComboBoxState<AutocompleteOption>({
+    items: options,
+    defaultInputValue: value,
+    allowsEmptyCollection: true,
+    menuTrigger: "manual",
+    // Collection keys must be a stable per-item identity (`value`), not a
+    // position - react-stately's collection builder caches nodes per item
+    // reference and will keep a stale index-derived key once one has been
+    // assigned, even after the array is re-filtered to a different order.
+    children: option => <Item key={option.value}>{option.label}</Item>,
+  })
+
+  // `state.close()` is aliased to `commitValue` (see above) - close by
+  // toggling instead, which just flips `isOpen` without resetting the value.
+  const closeMenu = (): void => {
+    if (state.isOpen) state.toggle()
+  }
+
+  // The rendered `${id}-option-{index}` ids are position-based, so resolve
+  // the focused *value* key back to its current index each render.
+  const activeIndex = options.findIndex(
+    option => option.value === state.selectionManager.focusedKey,
+  )
+
+  const listboxId = `${id}-listbox`
+  const activeId = activeIndex >= 0 ? `${id}-option-${activeIndex}` : undefined
+
+  useEffect(() => {
+    listboxRef.current
+      ?.querySelector('[aria-selected="true"]')
+      ?.scrollIntoView({ block: "nearest" })
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies -- re-runs when the active option changes, even though activeIndex itself isn't read here
+  }, [activeIndex])
+
+  const handleSelect = (option: AutocompleteOption): void => {
+    state.setInputValue(option.label)
+    closeMenu()
+    state.selectionManager.setFocusedKey(null)
+    onSelect?.(option)
+    inputRef.current?.focus()
+  }
+
+  const handleChange: ChangeEventHandler<HTMLInputElement> = ({ currentTarget }) => {
+    state.setInputValue(currentTarget.value)
+    state.selectionManager.setFocusedKey(null)
+    if (currentTarget.value.trim().length > 0) state.open()
+    else closeMenu()
+    onSearch?.(currentTarget.value.trim())
+  }
+
+  const handleFocus = (): void => {
+    if (state.inputValue.trim().length > 0) state.open()
+  }
+
+  const handleBlur = (): void => {
+    if (hideOnBlur) closeMenu()
+    state.selectionManager.setFocusedKey(null)
+  }
+
+  const handleKeyDown: KeyboardEventHandler<HTMLInputElement> = event => {
+    if (!state.isOpen) {
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        event.preventDefault()
+        state.open()
+      }
+      return
+    }
+    if (options.length === 0 && event.key !== "Escape") return
+
+    const { collection, selectionManager } = state
+    const currentKey = selectionManager.focusedKey
+
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault()
+        selectionManager.setFocusedKey(
+          currentKey == null
+            ? collection.getFirstKey()
+            : (collection.getKeyAfter(currentKey) ?? collection.getFirstKey()),
+        )
+        break
+      case "ArrowUp":
+        event.preventDefault()
+        selectionManager.setFocusedKey(
+          currentKey == null
+            ? collection.getLastKey()
+            : (collection.getKeyBefore(currentKey) ?? collection.getLastKey()),
+        )
+        break
+      case "Home":
+        event.preventDefault()
+        selectionManager.setFocusedKey(collection.getFirstKey())
+        break
+      case "End":
+        event.preventDefault()
+        selectionManager.setFocusedKey(collection.getLastKey())
+        break
+      case "Enter":
+        if (activeIndex < 0) return
+        event.preventDefault()
+        handleSelect(options[activeIndex])
+        break
+      case "Escape":
+        event.preventDefault()
+        closeMenu()
+        selectionManager.setFocusedKey(null)
+        break
+      default:
+        break
+    }
+  }
+
+  const showListbox = state.isOpen && options.length > 0
+  const statusMessage = state.isOpen
+    ? options.length === 0
+      ? noResultsLabel
+      : `${options.length} result${options.length === 1 ? "" : "s"} available`
+    : ""
+
+  return (
+    <div className={classNames("mx-autocomplete", className)}>
+      <div className="mx-autocomplete__control mx-form--inline-button">
+        <input
+          {...props}
+          ref={inputRef}
+          id={id}
+          type={type}
+          role="combobox"
+          className={classNames("mx-input__text", {
+            error: status === FormStatus.INVALID,
+            success: status === FormStatus.VALID,
+          })}
+          value={state.inputValue}
+          autoComplete="off"
+          aria-expanded={state.isOpen}
+          aria-controls={listboxId}
+          aria-autocomplete="list"
+          aria-activedescendant={activeId}
+          aria-label={label}
+          aria-describedby={`help-${id}`}
+          aria-invalid={status === FormStatus.INVALID}
+          onChange={handleChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onKeyDown={handleKeyDown}
+        />
+        {type === "search" && (
+          <button className="mx-button mx-button--icon-only" type="button" onClick={onSubmit}>
+            <span className="mx-icon mx-icon--search" aria-hidden="true" />
+            <span className="sr-only">Search</span>
+          </button>
+        )}
+      </div>
+      <div className="mx-autocomplete__suggestions">
+        {children}
+        {/* A <ul>/<li> pair with listbox/option roles is the WAI-ARIA APG combobox
+            pattern — <select>/<option> can't support filtering or rich content,
+            and keyboard selection is handled on the <input> via aria-activedescendant. */}
+        <ul
+          ref={listboxRef}
+          id={listboxId}
+          // oxlint-disable-next-line jsx-a11y/no-noninteractive-element-to-interactive-role, jsx-a11y/prefer-tag-over-role
+          role="listbox"
+          className="mx-autocomplete__listbox"
+          hidden={!showListbox}
+          onMouseDown={handleListboxMouseDown}
+        >
+          {options.map((option, index) => (
+            // oxlint-disable-next-line jsx-a11y/click-events-have-key-events -- keyboard selection is handled on the <input>, see handleKeyDown
+            <li
+              key={option.value}
+              id={`${id}-option-${index}`}
+              // oxlint-disable-next-line jsx-a11y/no-noninteractive-element-to-interactive-role, jsx-a11y/prefer-tag-over-role
+              role="option"
+              aria-selected={index === activeIndex}
+              className="mx-autocomplete__option"
+              onClick={() => handleSelect(option)}
+            >
+              {option.label}
+            </li>
+          ))}
+        </ul>
+        <output className="sr-only" aria-live="polite">
+          {statusMessage}
+        </output>
+      </div>
+    </div>
+  )
+}
+
+export default Autocomplete