@charcuterie/ui 1.0.1 → 2.0.0

package/src/Listbox/Listbox.stories.tsx

@@ -0,0 +1,205 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import { placementArgType } from "../argTypes.storyHelpers.ts"
+import { Badge } from "../Badge/Badge.tsx"
+import { Button } from "../Button/Button.tsx"
+import { StoryRow } from "../board.storyHelpers.tsx"
+import type { ListboxItem } from "./Listbox.tsx"
+import { Listbox } from "./Listbox.tsx"
+
+const LANGUAGES: ListboxItem[] = [
+  { label: "English", value: "eng" },
+  { label: "Spanish", value: "spa" },
+  { label: "French", value: "fra" },
+  { isDisabled: true, label: "German", value: "deu" },
+  { label: "Japanese", value: "jpn" },
+]
+
+/**
+ * The rich options a native `<option>` cannot render — a leading
+ * flag, a two-line detail, a trailing confidence badge — each with a
+ * `textValue` so type-ahead and the accessible name still work.
+ */
+const TRACKS: ListboxItem[] = [
+  {
+    label: (
+      <span className="flex items-center gap-2">
+        <span aria-hidden="true">🇬🇧</span>
+        <span className="flex flex-col">
+          <span>English</span>
+          <span className="text-content-muted text-xs">
+            5.1 · forced
+          </span>
+        </span>
+      </span>
+    ),
+    textValue: "English",
+    value: "eng",
+  },
+  {
+    label: (
+      <span className="flex items-center gap-2">
+        <span aria-hidden="true">🇯🇵</span>
+        <span className="flex flex-col">
+          <span>Japanese</span>
+          <span className="text-content-muted text-xs">
+            2.0 · original
+          </span>
+        </span>
+      </span>
+    ),
+    textValue: "Japanese",
+    value: "jpn",
+  },
+  {
+    label: (
+      <span className="flex items-center gap-2">
+        <span aria-hidden="true">🇫🇷</span>
+        <span>French</span>
+        <Badge intent="warning" size="sm">
+          low confidence
+        </Badge>
+      </span>
+    ),
+    textValue: "French",
+    value: "fra",
+  },
+]
+
+const meta = {
+  title: "Components/Listbox",
+  component: Listbox,
+  parameters: { layout: "padded" },
+  argTypes: { placement: placementArgType },
+  args: { placement: "bottom-start" },
+} satisfies Meta<typeof Listbox>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const ListboxHarness = ({
+  initialSelected,
+  options,
+  triggerLabel,
+}: {
+  initialSelected?: string
+  options: ListboxItem[]
+  triggerLabel: string
+}): ReactNode => {
+  const { hide, isVisible, toggle } = useVisibility()
+
+  const [selected, setSelected] = useState<
+    string | undefined
+  >(initialSelected)
+
+  const current = options.find(
+    (option) => option.value === selected,
+  )
+
+  const label =
+    current === undefined
+      ? triggerLabel
+      : (current.textValue ??
+        (typeof current.label === "string"
+          ? current.label
+          : triggerLabel))
+
+  return (
+    <Listbox
+      isVisible={isVisible}
+      onDismiss={hide}
+      onSelect={setSelected}
+      options={options}
+      selectedValue={selected}
+      trigger={
+        <Button appearance="outline" onClick={toggle}>
+          {label}
+        </Button>
+      }
+    />
+  )
+}
+
+export const Default: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Choose a language</Button>,
+  },
+  render: () => (
+    <ListboxHarness
+      options={LANGUAGES}
+      triggerLabel="Choose a language"
+    />
+  ),
+}
+
+/**
+ * A disabled option stays in the list and stays announced — it joins
+ * the choice but not the focus group, so the arrow keys and type-ahead
+ * skip it. `Spanish` is seeded as the current value.
+ */
+export const AllStates: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Choose a language</Button>,
+  },
+  render: () => (
+    <ListboxHarness
+      initialSelected="spa"
+      options={LANGUAGES}
+      triggerLabel="Choose a language"
+    />
+  ),
+}
+
+/**
+ * The thing a native `<select>` cannot do: two-line options, a leading
+ * flag, and a trailing intent-coloured badge.
+ */
+export const AllVariants: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: TRACKS,
+    trigger: <Button>Choose a track</Button>,
+  },
+  render: () => (
+    <StoryRow>
+      <ListboxHarness
+        options={TRACKS}
+        triggerLabel="Choose a track"
+      />
+    </StoryRow>
+  ),
+}
+
+/**
+ * Open it and drive it from the keyboard: arrows move focus without
+ * selecting, type a letter to jump, Enter chooses, Escape closes.
+ */
+export const Interactive: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Choose a language</Button>,
+  },
+  render: () => (
+    <ListboxHarness
+      options={LANGUAGES}
+      triggerLabel="Choose a language"
+    />
+  ),
+}

package/src/Listbox/Listbox.test.tsx

@@ -0,0 +1,198 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Listbox.stories.tsx"
+
+const { AllStates, Default, Interactive } =
+  composeStories(stories)
+
+test("a button opens a listbox whose rows are options", async () => {
+  const { body, canvas } = await mountStory(Default)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Choose a language",
+    role: "button",
+  })
+
+  // The trigger stays a native button that *opens* a listbox — it is
+  // not a `combobox`. It gains `aria-haspopup="listbox"`.
+  await expect(trigger).toHaveAttribute(
+    "aria-haspopup",
+    "listbox",
+  )
+
+  await userEvent.click(trigger)
+
+  const listbox = expectAgentDrivable(body, {
+    role: "listbox",
+  })
+
+  // `option`, not `menuitem` — a value being chosen, so it carries
+  // `aria-selected`.
+  const english = expectAgentDrivable(body, {
+    name: "English",
+    role: "option",
+  })
+
+  await expect(english).toHaveAttribute(
+    "aria-selected",
+    "false",
+  )
+
+  await expectNoAxeViolations(listbox)
+})
+
+test("opening focuses the seeded selection, which reads selected", async () => {
+  const { body, canvas } = await mountStory(AllStates)
+
+  // The trigger reflects the seeded value.
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Spanish",
+      role: "button",
+    }),
+  )
+
+  const spanish = expectAgentDrivable(body, {
+    name: "Spanish",
+    role: "option",
+  })
+
+  await expect(spanish).toHaveAttribute(
+    "aria-selected",
+    "true",
+  )
+
+  // The APG rule: a listbox opens on its current value.
+  await waitFor(() => {
+    expect(spanish).toHaveFocus()
+  })
+})
+
+test("the arrow keys move focus and skip the disabled option", async () => {
+  const { body, canvas } = await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Choose a language",
+      role: "button",
+    }),
+  )
+
+  const english = expectAgentDrivable(body, {
+    name: "English",
+    role: "option",
+  })
+
+  const japanese = expectAgentDrivable(body, {
+    name: "Japanese",
+    role: "option",
+  })
+
+  await expect(
+    expectAgentDrivable(body, {
+      name: "German",
+      role: "option",
+    }),
+  ).toBeDisabled()
+
+  await waitFor(() => {
+    expect(english).toHaveFocus()
+  })
+
+  // English → Spanish → French → Japanese, skipping the disabled
+  // German, which never joined the focus group.
+  await userEvent.keyboard(
+    "{ArrowDown}{ArrowDown}{ArrowDown}",
+  )
+
+  await waitFor(() => {
+    expect(japanese).toHaveFocus()
+  })
+})
+
+test("type-ahead jumps to the first match", async () => {
+  const { body, canvas } = await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Choose a language",
+      role: "button",
+    }),
+  )
+
+  const japanese = expectAgentDrivable(body, {
+    name: "Japanese",
+    role: "option",
+  })
+
+  await userEvent.keyboard("j")
+
+  await waitFor(() => {
+    expect(japanese).toHaveFocus()
+  })
+})
+
+test("Enter selects the focused option and closes", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Choose a language",
+      role: "button",
+    }),
+  )
+
+  // English is first and focused; arrow to Spanish and choose it.
+  await userEvent.keyboard("{ArrowDown}{Enter}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("listbox")).toBeNull()
+  })
+
+  // Choosing flows back through `onSelect`, so the trigger now reads
+  // the chosen value.
+  expectAgentDrivable(canvas, {
+    name: "Spanish",
+    role: "button",
+  })
+})
+
+test("Escape dismisses without choosing, and there is one tab stop", async () => {
+  const { body, canvas } = await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Choose a language",
+      role: "button",
+    }),
+  )
+
+  const listbox = expectAgentDrivable(body, {
+    role: "listbox",
+  })
+
+  const tabbable = Array.from(
+    listbox.querySelectorAll<HTMLButtonElement>(
+      '[role="option"]',
+    ),
+  ).filter((one) => one.tabIndex === 0)
+
+  await expect(tabbable).toHaveLength(1)
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("listbox")).toBeNull()
+  })
+
+  // Unchanged trigger — nothing was chosen.
+  expectAgentDrivable(canvas, {
+    name: "Choose a language",
+    role: "button",
+  })
+})

package/src/Listbox/Listbox.tsx

@@ -0,0 +1,295 @@
+import {
+  selectTabIndex,
+  useRovingFocus,
+  useSinglePicker,
+} from "@charcuterie/logic"
+import type { Placement } from "@floating-ui/react"
+import {
+  FloatingFocusManager,
+  FloatingPortal,
+} from "@floating-ui/react"
+import type { ReactElement, ReactNode } from "react"
+import { useEffect, useRef } from "react"
+
+import { PANEL_SURFACE_CLASS } from "../Overlay/overlayPanelClass.ts"
+import { useAnchoredOverlay } from "../Overlay/useAnchoredOverlay.ts"
+import { toClassName } from "../toClassName.ts"
+import { ListboxOption } from "./ListboxOption.tsx"
+
+export type ListboxItem = {
+  isDisabled?: boolean
+  label: ReactNode
+  /**
+   * Required when `label` is rich (an icon, two lines, a badge): it is
+   * the type-ahead target and the accessible name a screen reader
+   * reads. When `label` is a plain string it is used as the fallback.
+   */
+  textValue?: string
+  value: string
+}
+
+export type ListboxProps = {
+  className?: string
+  isVisible: boolean
+  /** Outside press and Escape both land here. */
+  onDismiss: () => void
+  onSelect: (value: string) => void
+  options: readonly ListboxItem[]
+  placement?: Placement
+  /** The initial seed. The live selection is the listbox's after that. */
+  selectedValue?: string
+  /** The control the listbox hangs off. **Cloned, not wrapped.** */
+  trigger: ReactElement
+}
+
+const getOptionText = (item: ListboxItem) =>
+  (
+    item.textValue ??
+    (typeof item.label === "string" ? item.label : "")
+  ).toLowerCase()
+
+/**
+ * The single-select fancy dropdown — the rich-option sibling of the
+ * native `Select`. `Select` keeps type-ahead, the mobile wheel, form
+ * submission and autofill; `Listbox` is for the cases `<option>`
+ * cannot render: an icon, two lines, a trailing badge.
+ *
+ * A listbox is **not** a menu, and that distinction is the whole
+ * reason it is a separate component from `Menu`. An `option` *is*
+ * something you are choosing — so it carries `aria-selected`, it
+ * type-aheads (which the APG requires of a listbox and `Menu`
+ * deliberately omits), and a screen reader announces "listbox,
+ * selected, 2 of 4". A `menuitem` only ever *does* something.
+ *
+ * ### Two kinds of state, composed
+ *
+ * `useRovingFocus` owns which option is tabbable (exactly one, so Tab
+ * enters and leaves the group once and the arrow keys move within it),
+ * and `useSinglePicker` owns which option is chosen. They are the same
+ * two kinds `Tabs` composes, and they never disturb each other:
+ * arrowing moves focus without selecting, Enter selects the focused
+ * option.
+ *
+ * ### Portalled, and named by its trigger
+ *
+ * Like `Menu`, the panel portals to `document.body` and `useRole` names
+ * it by pointing `aria-labelledby` at the trigger — so there is no
+ * `heading` prop; the button that opens it is its label.
+ */
+export const Listbox = ({
+  className,
+  isVisible,
+  onDismiss,
+  onSelect,
+  options,
+  placement = "bottom-start",
+  selectedValue,
+  trigger,
+}: ListboxProps): ReactNode => {
+  const optionElements = useRef(
+    new Map<string, HTMLButtonElement>(),
+  )
+
+  const typeahead = useRef({ buffer: "", stampMs: 0 })
+
+  const focus = useRovingFocus<string>()
+
+  const picker = useSinglePicker<string>({ selectedValue })
+
+  const { activeValue, registeredValues, setActiveValue } =
+    focus
+
+  const [firstValue] = registeredValues
+
+  const {
+    clonedTrigger,
+    context,
+    floatingStyles,
+    getFloatingProps,
+    setFloating,
+    triggerId,
+  } = useAnchoredOverlay({
+    isVisible,
+    maxHeightPx: 384,
+    offsetValue: 4,
+    onDismiss,
+    placement,
+    role: "listbox",
+    trigger,
+  })
+
+  const chooseValue = (value: string) => {
+    picker.select(value)
+
+    onSelect(value)
+
+    // A single choice closes, the way the native `<select>` it stands
+    // in for does — the consumer's `onDismiss` is the same one an
+    // outside press and Escape use.
+    onDismiss()
+  }
+
+  /**
+   * Opening lands the focus on the chosen option, or the first when
+   * nothing is chosen yet — the APG rule for a listbox, and the reason
+   * a reopened one resumes on the current value rather than the top.
+   */
+  useEffect(() => {
+    if (!isVisible) {
+      return
+    }
+
+    const seed = picker.selectedValue ?? firstValue
+
+    if (seed !== undefined && seed !== null) {
+      setActiveValue(seed)
+    }
+  }, [
+    firstValue,
+    isVisible,
+    picker.selectedValue,
+    setActiveValue,
+  ])
+
+  useEffect(() => {
+    if (!isVisible || activeValue === null) {
+      return
+    }
+
+    optionElements.current.get(activeValue)?.focus()
+  }, [activeValue, isVisible])
+
+  const runTypeahead = (character: string) => {
+    // Reset the buffer once the typing pauses, so "sk" then a beat
+    // then "e" is two searches rather than "ske".
+    const now = Date.now()
+
+    typeahead.current.buffer =
+      now - typeahead.current.stampMs > 500
+        ? character
+        : typeahead.current.buffer + character
+
+    typeahead.current.stampMs = now
+
+    const query = typeahead.current.buffer.toLowerCase()
+
+    const match = options.find(
+      (option) =>
+        !option.isDisabled &&
+        getOptionText(option).startsWith(query),
+    )
+
+    if (match) {
+      setActiveValue(match.value)
+    }
+  }
+
+  return (
+    <>
+      {clonedTrigger}
+
+      {isVisible ? (
+        <FloatingPortal>
+          <FloatingFocusManager
+            context={context}
+            initialFocus={-1}
+            modal={false}
+          >
+            <div
+              {...getFloatingProps()}
+              // A bare `role="listbox"` is an ARIA input field and must
+              // be named; pointing at the trigger across the portal is
+              // the same link `useRole` makes for a `Menu`.
+              aria-labelledby={triggerId}
+              className={toClassName(
+                PANEL_SURFACE_CLASS,
+                // The height is clamped to the viewport by the `size`
+                // middleware (`maxHeightPx`), written as an inline
+                // style; this scrolls within it.
+                "z-[var(--layer-modal)] flex min-w-48 flex-col gap-0.5 overflow-auto p-1",
+                className,
+              )}
+              onKeyDown={(keyEvent) => {
+                const commands: Record<string, () => void> =
+                  {
+                    ArrowDown: focus.next,
+                    ArrowUp: focus.previous,
+                    End: focus.last,
+                    Home: focus.first,
+                  }
+
+                const command = commands[keyEvent.key]
+
+                if (command) {
+                  keyEvent.preventDefault()
+
+                  command()
+
+                  return
+                }
+
+                if (
+                  (keyEvent.key === "Enter" ||
+                    keyEvent.key === " ") &&
+                  activeValue !== null
+                ) {
+                  keyEvent.preventDefault()
+
+                  chooseValue(activeValue)
+
+                  return
+                }
+
+                // Type-ahead: a single printable character with no
+                // modifier is a search, not a shortcut.
+                if (
+                  keyEvent.key.length === 1 &&
+                  !keyEvent.altKey &&
+                  !keyEvent.ctrlKey &&
+                  !keyEvent.metaKey
+                ) {
+                  runTypeahead(keyEvent.key)
+                }
+              }}
+              ref={setFloating}
+              // Duplicated from `getFloatingProps()` on purpose, and
+              // the two cannot differ — `useRole(context, { role:
+              // "listbox" })` in the hook is where it comes from.
+              // Stated here because a linter cannot see a role through
+              // a spread.
+              role="listbox"
+              style={floatingStyles}
+            >
+              {options.map((option) => (
+                <ListboxOption
+                  isSelected={
+                    picker.selectedValue === option.value
+                  }
+                  item={option}
+                  key={option.value}
+                  onSelect={chooseValue}
+                  registerFocus={focus.register}
+                  registerSelection={picker.register}
+                  tabIndex={selectTabIndex(
+                    focus,
+                    option.value,
+                  )}
+                  trackElement={(value, element) => {
+                    if (element) {
+                      optionElements.current.set(
+                        value,
+                        element,
+                      )
+                    } else {
+                      optionElements.current.delete(value)
+                    }
+                  }}
+                />
+              ))}
+            </div>
+          </FloatingFocusManager>
+        </FloatingPortal>
+      ) : null}
+    </>
+  )
+}