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

package/src/Form/Autocomplete/Elements/Autocomplete.ts

@@ -0,0 +1,235 @@
+/**
+ * Autocomplete
+ * @file Wires a text input plus a listbox of `<li role="option">` elements into
+ * a WAI-ARIA "combobox with list autocomplete" widget. This component does not
+ * fetch or filter results itself: on every keystroke it dispatches an
+ * `mx-autocomplete-search` event with the current query, and expects the
+ * consuming app to populate the listbox in response (e.g. from a REST or
+ * Elasticsearch call). A MutationObserver watches the listbox for those DOM
+ * changes and updates aria-expanded/aria-activedescendant/the status message
+ * to match whatever options currently exist.
+ */
+
+export type AutocompleteSearchEvent = CustomEvent<{ query: string }>
+export type AutocompleteSelectEvent = CustomEvent<{ value: string; label: string }>
+
+export default class Autocomplete extends HTMLElement {
+  internals_: ElementInternals
+  controller: AbortController
+  observer: MutationObserver
+  activeOption: HTMLLIElement | null
+
+  constructor() {
+    super()
+    this.internals_ = this.attachInternals()
+    this.controller = new AbortController()
+    this.activeOption = null
+  }
+
+  connectedCallback(): void {
+    if (!this.input || !this.listbox || !this.status) return
+
+    const { signal } = this.controller
+    this.input.addEventListener("input", this.handleInput, { signal })
+    this.input.addEventListener("keydown", this.handleKeydown, { signal })
+    this.input.addEventListener("focus", this.handleFocus, { signal })
+    this.input.addEventListener("blur", this.handleBlur, { signal })
+    this.listbox.addEventListener("mousedown", this.handleListboxMousedown, { signal })
+    this.listbox.addEventListener("click", this.handleOptionClick, { signal })
+
+    this.observer = new MutationObserver(this.handleOptionsChange)
+    this.observer.observe(this.listbox, { childList: true })
+  }
+
+  disconnectedCallback(): void {
+    this.controller.abort()
+    this.observer?.disconnect()
+  }
+
+  // The listbox's contents are owned by the consuming app (populated from a
+  // search/API call in response to `mx-autocomplete-search`), so react to
+  // whatever ends up there rather than computing it ourselves.
+  handleOptionsChange = (): void => {
+    if (this.activeOption && !this.options.includes(this.activeOption)) {
+      this.setActive(null)
+    }
+    this.updateVisibility()
+  }
+
+  handleInput = (): void => {
+    this.setActive(null)
+    this.dispatchSearch()
+    this.updateVisibility()
+  }
+
+  handleFocus = (): void => {
+    this.updateVisibility()
+  }
+
+  handleBlur = (): void => {
+    this.close()
+  }
+
+  // Selecting an option is a click on the (unfocusable) listbox, which would
+  // otherwise blur the input and close the list first. Prevent that default so
+  // focus never leaves the input and the click can still select.
+  handleListboxMousedown = (event: MouseEvent): void => {
+    event.preventDefault()
+  }
+
+  handleKeydown = (event: KeyboardEvent): void => {
+    if (!this.isOpen) {
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        event.preventDefault()
+        this.updateVisibility()
+      }
+      return
+    }
+
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault()
+        this.moveActive(1)
+        break
+      case "ArrowUp":
+        event.preventDefault()
+        this.moveActive(-1)
+        break
+      case "Home":
+        event.preventDefault()
+        this.setActive(this.visibleOptions[0] ?? null)
+        break
+      case "End":
+        event.preventDefault()
+        this.setActive(this.visibleOptions.at(-1) ?? null)
+        break
+      case "Enter":
+        if (!this.activeOption) return
+        event.preventDefault()
+        this.select(this.activeOption)
+        break
+      case "Escape":
+        event.preventDefault()
+        this.close()
+        break
+      default:
+        break
+    }
+  }
+
+  handleOptionClick = (event: MouseEvent): void => {
+    const option = (event.target as HTMLElement).closest<HTMLLIElement>('[role="option"]')
+    if (!option) return
+    this.select(option)
+  }
+
+  dispatchSearch(): void {
+    const event: AutocompleteSearchEvent = new CustomEvent("mx-autocomplete-search", {
+      bubbles: true,
+      detail: { query: this.input.value.trim() },
+    })
+    this.dispatchEvent(event)
+  }
+
+  // Derives open/closed, aria-expanded, and the status message from whatever
+  // options currently exist in the listbox — never filters or searches.
+  updateVisibility(): void {
+    const hasQuery = this.input.value.trim().length > 0
+    const matches = this.visibleOptions.length
+    const open = hasQuery && matches > 0
+
+    this.listbox.hidden = !open
+    this.input.setAttribute("aria-expanded", String(open))
+    this.status.textContent = !hasQuery
+      ? ""
+      : matches === 0
+        ? this.noResultsLabel
+        : `${matches} result${matches === 1 ? "" : "s"} available`
+  }
+
+  moveActive(step: 1 | -1): void {
+    const items = this.visibleOptions
+    if (items.length === 0) return
+    const current = this.activeOption ? items.indexOf(this.activeOption) : -1
+    const next = (current + step + items.length) % items.length
+    this.setActive(items[next])
+  }
+
+  setActive(option: HTMLLIElement | null): void {
+    this.activeOption?.setAttribute("aria-selected", "false")
+    this.activeOption = option
+    option?.setAttribute("aria-selected", "true")
+    this.input.setAttribute("aria-activedescendant", option?.id ?? "")
+    option?.scrollIntoView({ block: "nearest" })
+  }
+
+  select(option: HTMLLIElement): void {
+    const label = option.textContent ?? ""
+    this.input.value = label
+    this.close()
+    this.input.focus()
+
+    const event: AutocompleteSelectEvent = new CustomEvent("mx-autocomplete-select", {
+      bubbles: true,
+      detail: { value: option.dataset.value ?? label, label },
+    })
+    this.dispatchEvent(event)
+  }
+
+  close(): void {
+    this.listbox.hidden = true
+    this.input.setAttribute("aria-expanded", "false")
+    this.status.textContent = ""
+    this.setActive(null)
+  }
+
+  get isOpen(): boolean {
+    return !this.listbox.hidden
+  }
+
+  get noResultsLabel(): string {
+    return this.dataset.noResultsLabel || "No results found"
+  }
+
+  get input(): HTMLInputElement {
+    const input = this.querySelector<HTMLInputElement>('input[role="combobox"]')
+    if (!input) {
+      throw new Error(`${this.localName} must contain an <input role="combobox">.`)
+    }
+    return input
+  }
+
+  get listbox(): HTMLUListElement {
+    const listbox = this.querySelector<HTMLUListElement>('[role="listbox"]')
+    if (!listbox) {
+      throw new Error(`${this.localName} must contain a [role="listbox"] element.`)
+    }
+    return listbox
+  }
+
+  get status(): HTMLElement {
+    const status = this.querySelector<HTMLElement>("[data-autocomplete-status]")
+    if (!status) {
+      throw new Error(`${this.localName} must contain a [data-autocomplete-status] element.`)
+    }
+    return status
+  }
+
+  get options(): HTMLLIElement[] {
+    return Array.from(this.listbox.querySelectorAll<HTMLLIElement>('[role="option"]'))
+  }
+
+  get visibleOptions(): HTMLLIElement[] {
+    return this.options.filter(option => !option.hidden)
+  }
+}
+
+if (!customElements.get("mx-autocomplete")) {
+  customElements.define("mx-autocomplete", Autocomplete)
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "mx-autocomplete": Autocomplete
+  }
+}

package/src/Form/Autocomplete/README.md

@@ -0,0 +1,205 @@
+# Autocomplete
+
+An editable combobox: a text input paired with a listbox of suggestions. Implements the [WAI-ARIA APG "Combobox with List Autocomplete"](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) pattern.
+
+**This component never filters, searches, or fetches anything itself.** On every keystroke it tells the consuming app what the user typed — the app decides what counts as a match (a local substring filter, a debounced REST call, an Elasticsearch query, whatever) and supplies the current result set back. This keeps the component usable whether your data is a static in-memory list or a live search backend.
+
+Value and label are the same string: selecting a suggestion replaces the input's text with that suggestion's exact label. If you need a separate underlying id/code, listen for the select event (`onSelect` in React, `mx-autocomplete-select` for Twig/Web Component) and store it yourself (e.g. in a hidden input).
+
+This is a field-level component only — pair it with `FormItem` and `FormLabel`/`FormDescription` for a complete, labelled form control, the same way `FormText` and `FormSelect` are composed.
+
+---
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Form/Autocomplete/autocomplete.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Form/Autocomplete/autocomplete.twig' with {
+  id: 'autocomplete-fruit',
+  name: 'fruit',
+  label: 'Choose a fruit',
+  placeholder: 'Start typing a fruit…',
+  options: [],
+} %}
+```
+
+**autocomplete.twig props:**
+
+| Prop             | Type                                 | Required | Default              | Description                                                                                          |
+| ---------------- | ------------------------------------ | -------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
+| `id`             | `string`                             | Yes      | —                    | `id` on the `<input>`; also used to derive the listbox/option ids                                    |
+| `name`           | `string`                             | No       | —                    | `name` attribute on the `<input>`                                                                    |
+| `label`          | `string`                             | No       | —                    | `aria-label` on the `<input>` (visually hidden)                                                      |
+| `type`           | `"text" \| "search"`                 | No       | `"text"`             | `"search"` also renders an icon-only submit button                                                   |
+| `options`        | `{ label: string, value: string }[]` | No       | —                    | The **current** suggestions to render as `<li role="option">` — not a full list to filter, see below |
+| `value`          | `string`                             | No       | —                    | Initial `<input>` value                                                                              |
+| `placeholder`    | `string`                             | No       | —                    | `<input>` placeholder                                                                                |
+| `required`       | `boolean`                            | No       | `false`              | Adds `required` to the `<input>`                                                                     |
+| `status`         | `"default" \| "valid" \| "invalid"`  | No       | `"default"`          | Adds `.error`/`.success` and `aria-invalid` to the `<input>`                                         |
+| `noResultsLabel` | `string`                             | No       | `"No results found"` | Message announced when there are zero current options and a query                                    |
+
+Registers as `<mx-autocomplete>` — import the element to activate its behaviour:
+
+```js
+import "@pnx-mixtape/mxds/src/Form/Autocomplete/Elements/Autocomplete"
+```
+
+---
+
+## HTML + Web Component
+
+The Web Component wires up the ARIA combobox behaviour (open/close, keyboard navigation, selection) over whatever `<li role="option">` elements currently exist in the listbox — it never adds, removes, or hides any of them itself. Typically you render an **empty** listbox and populate it yourself in response to the search event:
+
+```html
+<mx-autocomplete class="mx-autocomplete">
+  <div class="mx-autocomplete__control">
+    <input
+      class="mx-input__text"
+      id="autocomplete-fruit"
+      name="fruit"
+      type="text"
+      role="combobox"
+      aria-expanded="false"
+      aria-controls="autocomplete-fruit-listbox"
+      aria-autocomplete="list"
+      aria-activedescendant=""
+      autocomplete="off"
+    />
+  </div>
+  <ul class="mx-autocomplete__listbox" id="autocomplete-fruit-listbox" role="listbox" hidden></ul>
+  <output class="sr-only" aria-live="polite" data-autocomplete-status></output>
+</mx-autocomplete>
+```
+
+`<mx-autocomplete>` must contain: an `input[role="combobox"]`, a `[role="listbox"]`, and a `[data-autocomplete-status]` live region — the Web Component throws a descriptive error if any is missing.
+
+**Wiring up a search backend:** on every keystroke the component dispatches a bubbling `mx-autocomplete-search` event with `detail: { query }`. Listen for it, run your own search (debounce it yourself — the component fires on every keystroke), and replace the listbox's children with the matching `<li role="option">` elements. A `MutationObserver` watches the listbox and updates `aria-expanded`/`aria-activedescendant`/the status message to match whatever ends up there:
+
+```js
+const root = document.querySelector("mx-autocomplete")
+const listbox = root.querySelector('[role="listbox"]')
+
+root.addEventListener("mx-autocomplete-search", async ({ detail: { query } }) => {
+  if (!query) return (listbox.innerHTML = "")
+  const results = await searchElasticsearch(query) // however you fetch matches
+  listbox.replaceChildren(
+    ...results.map((result, index) => {
+      const li = document.createElement("li")
+      li.id = `autocomplete-fruit-option-${index}`
+      li.className = "mx-autocomplete__option"
+      li.setAttribute("role", "option")
+      li.setAttribute("aria-selected", "false")
+      li.dataset.value = result.value
+      li.textContent = result.label
+      return li
+    }),
+  )
+})
+```
+
+Set `data-no-results-label="..."` on `<mx-autocomplete>` to override the default "No results found" message.
+
+Selecting an option (click or <kbd>Enter</kbd>) dispatches a bubbling `mx-autocomplete-select` custom event with `detail: { value, label }`.
+
+---
+
+## React
+
+```tsx
+import { useState } from "react"
+import { Autocomplete, AutocompleteOption } from "@pnx-mixtape/mxds/react"
+
+const Example = () => {
+  const [options, setOptions] = useState<AutocompleteOption[]>([])
+
+  const handleSearch = async (query: string) => {
+    if (!query) return setOptions([])
+    setOptions(await searchElasticsearch(query)) // however you fetch matches
+  }
+
+  return (
+    <Autocomplete
+      id="autocomplete-fruit"
+      name="fruit"
+      label="Choose a fruit"
+      placeholder="Start typing a fruit…"
+      options={options}
+      onSearch={handleSearch}
+      onSelect={option => console.log(option)}
+    />
+  )
+}
+```
+
+**`Autocomplete` props:**
+
+| Prop             | Type                                   | Default              | Description                                                                                                          |
+| ---------------- | -------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `id`             | `string`                               | —                    | `id` on the `<input>`; also used to derive the listbox/option ids                                                    |
+| `label`          | `string`                               | —                    | `aria-label` on the `<input>` (visually hidden)                                                                      |
+| `type`           | `"text" \| "search"`                   | `"text"`             | `"search"` also renders an icon-only submit button (`onSubmit`)                                                      |
+| `options`        | `AutocompleteOption[]`                 | —                    | The **current** results to display — not filtered further, see below                                                 |
+| `onSearch`       | `(query: string) => void`              | —                    | Called on every keystroke with the trimmed input value — debounce it yourself and feed matches back in via `options` |
+| `value`          | `string`                               | `""`                 | Initial `<input>` value (uncontrolled after that)                                                                    |
+| `status`         | `FormStatus`                           | `FormStatus.DEFAULT` | Adds `.error`/`.success` and `aria-invalid`                                                                          |
+| `noResultsLabel` | `string`                               | `"No results found"` | Message announced when `options` is empty and there's a query                                                        |
+| `onSelect`       | `(option: AutocompleteOption) => void` | —                    | Called when an option is chosen by click or <kbd>Enter</kbd>                                                         |
+| `hideOnBlur`     | `boolean`                              | `true`               | Close the listbox on blur                                                                                            |
+| `className`      | `string`                               | —                    | Extra class on the root                                                                                              |
+
+Any other native `<input>` prop (e.g. `placeholder`, `required`, `disabled`) is passed through to the `<input>`.
+
+### React ⇄ Twig parity
+
+- React always sets `aria-describedby="help-{id}"` on the `<input>`, matching `FormText`. Twig only adds it as a static attribute (no conditional on whether a description actually exists) — pair with a `FormDescription`/description element sharing that `id` if you render one.
+- Neither implementation filters, searches, or fetches on your behalf — both hand control of the result set to the consuming app (`onSearch` in React; the `mx-autocomplete-search` event and DOM mutation in Twig/Web Component).
+
+---
+
+## Modifiers
+
+This component has no BEM modifier classes — its only visual states (`error`/`success`) come from the shared `.mx-input__text` classes documented in `Form/form.css`.
+
+---
+
+## Accessibility
+
+Implements the WAI-ARIA APG [Combobox with List Autocomplete](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) pattern:
+
+- The `<input>` has `role="combobox"`, `aria-autocomplete="list"`, `aria-expanded`, and `aria-controls` pointing at the listbox.
+- Focus always stays on the `<input>`. The active suggestion is tracked with `aria-activedescendant` rather than moving DOM focus, so screen readers announce the active option without leaving the textbox.
+- Suggestions are `<li role="option">` inside a `<ul role="listbox">`; the currently active one gets `aria-selected="true"`.
+- A visually-hidden live region (`role="status"`, via `<output>`) announces the current result count (or the "no results" message) whenever the option set changes.
+
+**Keyboard support:**
+
+| Key                            | Action                                                                                                    |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| <kbd>↓</kbd>/<kbd>↑</kbd>      | Opens the list (if closed and there are current options); moves the active option, wrapping at either end |
+| <kbd>Home</kbd>/<kbd>End</kbd> | Jumps to the first/last option                                                                            |
+| <kbd>Enter</kbd>               | Selects the active option                                                                                 |
+| <kbd>Escape</kbd>              | Closes the list without changing the input's value                                                        |
+| Typing                         | Reports the query to the app (`onSearch`/`mx-autocomplete-search`) and clears the active option           |
+
+---
+
+## Customisation
+
+Overridable custom properties (set on `.mx-autocomplete` or an ancestor):
+
+| Property                        | Default               | Description                             |
+| ------------------------------- | --------------------- | --------------------------------------- |
+| `--autocomplete-background`     | `--colour-background` | Listbox background                      |
+| `--autocomplete-foreground`     | `--colour-foreground` | Listbox text colour                     |
+| `--autocomplete-radius`         | `--border-radius`     | Listbox corner radius                   |
+| `--autocomplete-shadow`         | `--box-shadow`        | Listbox drop shadow                     |
+| `--autocomplete-max-height`     | `16rem`               | Listbox max block-size before scrolling |
+| `--autocomplete-padding-inline` | `0`                   | Listbox inline padding                  |
+| `--autocomplete-padding-block`  | `0`                   | Listbox block padding                   |

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

@@ -0,0 +1,68 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Autocomplete 1`] = `
+"
+<mx-autocomplete class="mx-autocomplete">
+  <div class="mx-autocomplete__control mx-form--inline-button">
+    <input class="mx-input__text" id="autocomplete-fruit" name="unique-0" type="text" role="combobox" aria-expanded="false" aria-controls="unique-0" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-0" aria-label="Choose a fruit" autocomplete="off" placeholder="Start typing a fruit…">
+      </div>
+  <div class="mx-autocomplete__suggestions">
+    
+    <ul class="mx-autocomplete__listbox" id="unique-0" role="listbox" hidden=""></ul>
+    <output class="sr-only" aria-live="polite" data-autocomplete-status=""></output>
+  </div>
+</mx-autocomplete>
+"
+`;
+
+exports[`Invalid 1`] = `
+"
+<mx-autocomplete class="mx-autocomplete">
+  <div class="mx-autocomplete__control mx-form--inline-button">
+    <input class="mx-input__text error" id="autocomplete-fruit" name="unique-0" type="text" role="combobox" aria-expanded="false" aria-controls="unique-0" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-0" aria-label="Choose a fruit" autocomplete="off" placeholder="Start typing a fruit…" aria-invalid="true">
+      </div>
+  <div class="mx-autocomplete__suggestions">
+    
+    <ul class="mx-autocomplete__listbox" id="unique-0" role="listbox" hidden="">
+          </ul>
+    <output class="sr-only" aria-live="polite" data-autocomplete-status=""></output>
+  </div>
+</mx-autocomplete>
+"
+`;
+
+exports[`Required 1`] = `
+"
+<mx-autocomplete class="mx-autocomplete">
+  <div class="mx-autocomplete__control mx-form--inline-button">
+    <input class="mx-input__text" id="autocomplete-fruit" name="unique-0" type="text" role="combobox" aria-expanded="false" aria-controls="unique-0" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-0" aria-label="Choose a fruit" autocomplete="off" placeholder="Start typing a fruit…" required="">
+      </div>
+  <div class="mx-autocomplete__suggestions">
+    
+    <ul class="mx-autocomplete__listbox" id="unique-0" role="listbox" hidden="">
+          </ul>
+    <output class="sr-only" aria-live="polite" data-autocomplete-status=""></output>
+  </div>
+</mx-autocomplete>
+"
+`;
+
+exports[`Search 1`] = `
+"
+<mx-autocomplete class="mx-autocomplete">
+  <div class="mx-autocomplete__control mx-form--inline-button">
+    <input class="mx-input__text" id="autocomplete-fruit" name="unique-0" type="search" role="combobox" aria-expanded="false" aria-controls="unique-0" aria-autocomplete="list" aria-activedescendant="" aria-describedby="unique-0" aria-label="Choose a fruit" autocomplete="off" placeholder="Start typing a fruit…">
+          <button class="mx-button mx-button--icon-only" type="button">
+        <span class="mx-icon mx-icon--search" aria-hidden="true"></span>
+        <span class="sr-only">Search</span>
+      </button>
+      </div>
+  <div class="mx-autocomplete__suggestions">
+    
+    <ul class="mx-autocomplete__listbox" id="unique-0" role="listbox" hidden="">
+          </ul>
+    <output class="sr-only" aria-live="polite" data-autocomplete-status=""></output>
+  </div>
+</mx-autocomplete>
+"
+`;

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

@@ -0,0 +1,9 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Autocomplete 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="text" value="" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
+
+exports[`Invalid 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text error" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="true" type="text" value="" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
+
+exports[`Required 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button"><input placeholder="Start typing a fruit…" required="" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="text" value="" name="fruit"></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;
+
+exports[`Search 1`] = `"<div class="mx-autocomplete"><div class="mx-autocomplete__control mx-form--inline-button"><input placeholder="Start typing a fruit…" id="autocomplete-fruit" role="combobox" class="mx-input__text" autocomplete="off" aria-expanded="false" aria-controls="autocomplete-fruit-listbox" aria-autocomplete="list" aria-label="Choose a fruit" aria-describedby="help-autocomplete-fruit" aria-invalid="false" type="search" value="" name="fruit"><button class="mx-button mx-button--icon-only" type="button"><span class="mx-icon mx-icon--search" aria-hidden="true"></span><span class="sr-only">Search</span></button></div><div class="mx-autocomplete__suggestions"><ul id="autocomplete-fruit-listbox" role="listbox" class="mx-autocomplete__listbox" hidden=""></ul><output class="sr-only" aria-live="polite"></output></div></div>"`;

package/src/Form/Autocomplete/autocomplete.css

@@ -0,0 +1,60 @@
+/**
+ * Autocomplete
+ */
+
+@layer design-system.defaults {
+  mx-autocomplete {
+    display: block;
+  }
+}
+
+@layer design-system.components {
+  .mx-autocomplete {
+    position: relative;
+    max-inline-size: var(--container-max-width);
+  }
+
+  /* @public --autocomplete-background --autocomplete-foreground --autocomplete-radius --autocomplete-shadow --autocomplete-max-height --autocomplete-padding-inline --autocomplete-padding-block */
+  .mx-autocomplete__listbox {
+    position: absolute;
+    z-index: 10;
+    inset-block-start: 100%;
+    inset-inline: 0;
+    margin: 0;
+    list-style: none;
+    background-color: var(--autocomplete-background, var(--colour-background));
+    color: var(--autocomplete-foreground, var(--colour-foreground));
+    border-radius: var(--autocomplete-radius, var(--border-radius));
+    box-shadow: var(--autocomplete-shadow, var(--box-shadow));
+    max-block-size: var(--autocomplete-max-height, 16rem);
+    padding-inline: var(--autocomplete-padding-inline, 0);
+    padding-block: var(--autocomplete-padding-block, 0);
+    overflow-y: auto;
+
+    &[hidden] {
+      display: none;
+      opacity: 0;
+
+      @starting-style {
+        opacity: 1;
+        display: block;
+      }
+    }
+  }
+
+  .mx-autocomplete__option {
+    padding-block: var(--spacing-xxxs);
+    padding-inline: var(--spacing-xs);
+    cursor: pointer;
+
+    &[hidden] {
+      display: none;
+    }
+
+    &[aria-selected="true"] {
+      outline: var(--outline-size, 2px) var(--outline-style, solid)
+        var(--outline-color, currentcolor);
+      outline-offset: var(--outline-offset, -2px);
+    }
+  }
+}

package/src/Form/Autocomplete/autocomplete.entry.js

@@ -0,0 +1 @@
+import "./Elements/Autocomplete"

package/src/Form/Autocomplete/autocomplete.twig

@@ -0,0 +1,44 @@
+{% set classes = [
+  'mx-input__text',
+  status == "invalid" ? "error" : null,
+  status == "valid" ? "success" : null,
+] %}
+{% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
+{% set status = status|default("default") %}
+
+<mx-autocomplete class="mx-autocomplete"{% if noResultsLabel %} data-no-results-label="{{ noResultsLabel }}"{% endif %}>
+  <div class="mx-autocomplete__control mx-form--inline-button">
+    <input{{ attributes }}
+        id="{{ id }}"
+        name="{{ name }}"
+        type="{{ type }}"
+        role="combobox"
+        aria-expanded="false"
+        aria-controls="{{ id }}-listbox"
+        aria-autocomplete="list"
+        aria-activedescendant=""
+        aria-describedby="help-{{ id }}"
+        aria-label="{{ label }}"
+        autocomplete="off"
+        {% if value %} value="{{ value }}"{% endif %}
+        {% if placeholder %} placeholder="{{ placeholder }}"{% endif %}
+        {% if status == "invalid" %} aria-invalid="true"{% endif %}
+        {% if required %} required{% endif %}
+    />
+    {% if type == "search" %}
+      <button class="mx-button mx-button--icon-only" type="button">
+        <span class="mx-icon mx-icon--search" aria-hidden="true"></span>
+        <span class="sr-only">Search</span>
+      </button>
+    {% endif %}
+  </div>
+  <div class="mx-autocomplete__suggestions">
+    {{ content }}
+    <ul class="mx-autocomplete__listbox" id="{{ id }}-listbox" role="listbox" hidden>
+      {% for option in options %}
+        <li class="mx-autocomplete__option" id="{{ id }}-option-{{ loop.index0 }}" role="option" data-value="{{ option.value }}" aria-selected="false">{{ option.label }}</li>
+      {% endfor %}
+    </ul>
+    <output class="sr-only" aria-live="polite" data-autocomplete-status></output>
+  </div>
+</mx-autocomplete>

package/src/Form/Checkbox/Checkbox.figma.ts

@@ -0,0 +1,32 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=89-35
+// source=src/Form/Checkbox/FormCheckbox.tsx
+// component=Checkbox
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const status = instance.getEnum("Status", {
+  Default: "FormStatus.DEFAULT",
+  Invalid: "FormStatus.INVALID",
+  Valid: "FormStatus.VALID",
+})
+const content = instance.getSlot("Content")
+
+const statusProp = status === "FormStatus.DEFAULT" ? "" : ` status={${status}}`
+
+// Real finding, checked against react-aria's actual types: AriaCheckboxGroupItemProps
+// is `Omit<AriaCheckboxProps, 'isSelected' | 'defaultSelected'> & { value: string }` —
+// the group-item Checkbox explicitly CANNOT take a checked/selected prop at all.
+// "Checked" here is a Figma-only preview state, derived from the parent FormCheckbox
+// group's own value array matching this item's `value` — same context-derived-not-a-
+// prop shape as Stage 3's DropMenuItem `selected`/Tab `active`. (SingleCheckbox, the
+// standalone sibling export, DOES support isSelected/defaultSelected for real — just
+// not this one.)
+export default {
+  example: figma.code`<Checkbox value="option"${statusProp}>${content}</Checkbox>`,
+  imports: ['import { Checkbox, FormStatus } from "@pnx-mixtape/mxds/react"'],
+  id: "checkbox",
+  metadata: {
+    nestable: true,
+  },
+}