@charcuterie/ui 1.0.1 → 2.0.0

package/src/ColorSchemeToggle/ColorSchemeToggle.stories.tsx

@@ -0,0 +1,161 @@
+import type { ColorSchemeMode } from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import {
+  MonitorIcon,
+  MoonIcon,
+  SunIcon,
+} from "../icons.storyHelpers.tsx"
+import type { ColorSchemeIcons } from "./ColorSchemeToggle.tsx"
+import { ColorSchemeToggle } from "./ColorSchemeToggle.tsx"
+
+/**
+ * The library ships **no icons** — these are the story-only
+ * hand-drawn SVGs an app would replace with lucide `Sun` / `Moon` /
+ * `Monitor`.
+ */
+const ICONS: ColorSchemeIcons = {
+  dark: <MoonIcon />,
+  light: <SunIcon />,
+  system: <MonitorIcon />,
+}
+
+const meta = {
+  title: "Components/ColorSchemeToggle",
+  component: ColorSchemeToggle,
+  parameters: { layout: "padded" },
+  argTypes: {
+    // `mode` is `ColorSchemeMode` from @charcuterie/logic — a bare
+    // specifier docgen cannot enumerate, so it gets an explicit
+    // radio rather than falling through to the object control.
+    mode: {
+      control: "radio",
+      options: ["light", "dark", "system"],
+    },
+    size: controlSizeArgType,
+  },
+  args: {
+    appearance: "ghost",
+    icons: ICONS,
+    isDisabled: false,
+    mode: "system",
+    onCycle: () => {},
+    size: "md",
+  },
+} satisfies Meta<typeof ColorSchemeToggle>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * Controlled and self-contained: this story owns the mode in local
+ * state and advances it on each press, which is what a plain
+ * consumer wires up. `<ColorSchemeSwitcher>` wires the same
+ * `onCycle` to the `useColorScheme` hook instead.
+ *
+ * The accessible name states the current mode and the next one, so
+ * it changes as the button cycles — that is what the test asserts.
+ */
+export const Default: Story = {
+  render: (toggleProps) => {
+    const [mode, setMode] =
+      useState<ColorSchemeMode>("system")
+
+    return (
+      <ColorSchemeToggle
+        {...toggleProps}
+        mode={mode}
+        onCycle={setMode}
+      />
+    )
+  },
+}
+
+/**
+ * Each mode's icon, held fixed so the three glyphs are visible at
+ * once — light is the sun, dark the moon, system the monitor.
+ */
+export const AllModes: Story = {
+  render: (toggleProps) => (
+    <StorySection title="light → dark → system, the order a press cycles through.">
+      <StoryGrid columns={3}>
+        <StoryCell label="light">
+          <ColorSchemeToggle
+            {...toggleProps}
+            mode="light"
+            onCycle={() => {}}
+          />
+        </StoryCell>
+
+        <StoryCell label="dark">
+          <ColorSchemeToggle
+            {...toggleProps}
+            mode="dark"
+            onCycle={() => {}}
+          />
+        </StoryCell>
+
+        <StoryCell label="system">
+          <ColorSchemeToggle
+            {...toggleProps}
+            mode="system"
+            onCycle={() => {}}
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const Sizes: Story = {
+  render: (toggleProps) => (
+    <StorySection title="Square on the control height, so it lines up with the buttons beside it in a toolbar.">
+      <StoryRow>
+        <ColorSchemeToggle
+          {...toggleProps}
+          mode="light"
+          onCycle={() => {}}
+          size="sm"
+        />
+
+        <ColorSchemeToggle
+          {...toggleProps}
+          mode="dark"
+          onCycle={() => {}}
+          size="md"
+        />
+
+        <ColorSchemeToggle
+          {...toggleProps}
+          mode="system"
+          onCycle={() => {}}
+          size="lg"
+        />
+      </StoryRow>
+    </StorySection>
+  ),
+}
+
+export const Responsive: Story = {
+  render: (toggleProps) => (
+    <ContainerBoard>
+      <StoryRow>
+        <ColorSchemeToggle
+          {...toggleProps}
+          mode="system"
+          onCycle={() => {}}
+        />
+      </StoryRow>
+    </ContainerBoard>
+  ),
+}

package/src/ColorSchemeToggle/ColorSchemeToggle.test.tsx

@@ -0,0 +1,80 @@
+import { composeStories } from "@storybook/react"
+import { userEvent } 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 "./ColorSchemeToggle.stories.tsx"
+
+const { AllModes, Default } = composeStories(stories)
+
+/**
+ * The name states the current mode — a screen reader that lands on
+ * the control hears "Colour scheme: system", not a nameless button,
+ * and an agent can find it.
+ */
+test("the toggle is named for its current mode", async () => {
+  const { canvas } = await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: system/i,
+    role: "button",
+  })
+})
+
+test("a press cycles the mode and updates the name", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const button = expectAgentDrivable(canvas, {
+    name: /colour scheme: system/i,
+    role: "button",
+  })
+
+  // system → light
+  await userEvent.click(button)
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: light/i,
+    role: "button",
+  })
+
+  // light → dark
+  await userEvent.click(button)
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: dark/i,
+    role: "button",
+  })
+})
+
+test("the icon is hidden from assistive tech; the name carries it", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme/i,
+    role: "button",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("each mode renders its own control", async () => {
+  const { canvas } = await mountStory(AllModes)
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: light/i,
+    role: "button",
+  })
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: dark/i,
+    role: "button",
+  })
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: system/i,
+    role: "button",
+  })
+})

package/src/ColorSchemeToggle/ColorSchemeToggle.tsx

@@ -0,0 +1,107 @@
+import type { ColorSchemeMode } from "@charcuterie/logic"
+import {
+  DEFAULT_COLOR_SCHEME_ORDER,
+  nextColorSchemeMode,
+} from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+
+import { IconButton } from "../IconButton/IconButton.tsx"
+import type { IntentAppearance } from "../intentStyles.ts"
+
+/**
+ * One `ReactNode` per mode. The library ships **no icons** — lucide
+ * (ISC) is the fleet recommendation — so an app passes its own
+ * `Sun` / `Moon` / `Monitor`, exactly as `IconButton` takes its
+ * glyph as `children`
+ * ([decision](../../../../docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md)).
+ */
+export type ColorSchemeIcons = Record<
+  ColorSchemeMode,
+  ReactNode
+>
+
+export type ColorSchemeToggleProps = {
+  appearance?: IntentAppearance
+  className?: string
+  icons: ColorSchemeIcons
+  isDisabled?: boolean
+  /**
+   * Builds the accessible name from the current and next mode.
+   * Default announces the current mode and where a press goes —
+   * "Colour scheme: dark. Activate to switch to system." — so the
+   * name updates as the control cycles and
+   * `getByRole("button", { name: /colour scheme/i })` resolves.
+   */
+  label?: (
+    mode: ColorSchemeMode,
+    nextMode: ColorSchemeMode,
+  ) => string
+  mode: ColorSchemeMode
+  /**
+   * Called with the next mode on activation. **Controlled**: this
+   * component stores nothing — it renders `mode` and reports intent,
+   * which is what keeps it free of `matchMedia`/`document` and
+   * usable in any runtime. `<ColorSchemeSwitcher>` wires this to the
+   * `useColorScheme` hook; a plain consumer wires it to its own
+   * state.
+   */
+  onCycle: (nextMode: ColorSchemeMode) => void
+  order?: readonly ColorSchemeMode[]
+  size?: ControlSize
+}
+
+const MODE_LABEL: Record<ColorSchemeMode, string> = {
+  dark: "Dark",
+  light: "Light",
+  system: "System",
+}
+
+const defaultLabel = (
+  mode: ColorSchemeMode,
+  nextMode: ColorSchemeMode,
+) =>
+  `Colour scheme: ${MODE_LABEL[mode]}. Activate to switch to ${MODE_LABEL[nextMode]}.`
+
+/**
+ * The cycling colour-scheme button — light → dark → system → light.
+ *
+ * Layer 2 of the three: presentational and controlled, with no
+ * browser coupling. It is an `IconButton`, so it inherits the one
+ * rule that makes the fleet agent-drivable — a glyph is not a name,
+ * and this control's name states the current mode rather than
+ * leaving a screen reader to read a sun path as nothing.
+ *
+ * A *segmented* all-three-visible form was considered and deferred
+ * (owner chose cycling-only, 2026-08-03); `icons` and `order` are
+ * shaped so a `ColorSchemePicker` could join later without changing
+ * this API.
+ */
+export const ColorSchemeToggle = ({
+  appearance = "ghost",
+  className,
+  icons,
+  isDisabled = false,
+  label = defaultLabel,
+  mode,
+  onCycle,
+  order = DEFAULT_COLOR_SCHEME_ORDER,
+  size = "md",
+}: ColorSchemeToggleProps): ReactNode => {
+  const nextMode = nextColorSchemeMode(mode, order)
+
+  return (
+    <IconButton
+      appearance={appearance}
+      className={className}
+      isDisabled={isDisabled}
+      label={label(mode, nextMode)}
+      onClick={() => {
+        onCycle(nextMode)
+      }}
+      size={size}
+    >
+      {icons[mode]}
+    </IconButton>
+  )
+}

package/src/Combobox/Combobox.mdx

@@ -0,0 +1,71 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ComboboxStories from "./Combobox.stories";
+
+<Meta of={ComboboxStories} />
+
+# Combobox
+
+The searchable, filtering, virtualized picker — the other half of the picker family, and
+the one that consolidates the fleet's hand-rolled dropdowns
+([decision](../../../docs/decisions/2026-08-03-listbox-and-combobox-are-siblings-of-select.md)).
+Use it when the list is long enough to search or filter; reach for
+[`Listbox`](?path=/docs/components-listbox--docs) for a short rich-option list, and the
+native [`Select`](?path=/docs/components-select--docs) for a plain one.
+
+<Canvas of={ComboboxStories.Default} />
+
+## Props
+
+<Controls />
+
+## The ARIA is forced, not stylistic
+
+Unlike `Listbox`, **focus stays in the text input**, so the active option is tracked with
+`aria-activedescendant`, not roving tabindex. The input is the `role="combobox"`
+(`aria-autocomplete="list"`, `aria-expanded`, `aria-controls`); the popup is a
+`role="listbox"`. Arrows move the active descendant while the caret stays put; Enter
+selects; Escape clears the query before it closes. The options are `<div>`-shaped
+`role="option"`s with **zero** tab stops — a combobox popup legitimately has none.
+
+## Filtering is the consumer's, or the component's
+
+Omit `onQueryChange` and the list filters internally by `textValue`. Supply it — a
+react-query search, say — and you own the query: the `options` then arrive pre-filtered,
+and the debounce, the request token, and the per-parent cache stay yours, exactly the way
+`PathPicker` already splits async work.
+
+```tsx
+<Combobox
+  isVisible={isVisible}
+  onDismiss={hide}
+  onQueryChange={setQuery}   // omit to filter internally
+  onSelect={choose}
+  options={results}          // pre-filtered when you own the query
+  trigger={<Button onClick={toggle}>Search</Button>}
+/>
+```
+
+## Loading, error, empty, footer, creatable, multiple
+
+`isLoading` and `error` are panel states (only `PathPicker` had all of them); an empty
+result shows `emptyLabel` and stays open. `footer` is a sticky hint (`LinkPicker`'s "type a
+path directly"). `isCreatable` lets Enter commit the raw query (`AssFieldPicker`), and Tab
+accepts the active suggestion (`PathPicker`). `isMultiple` renders the chosen values as
+removable chips rather than filling the input, and keeps the popup open.
+
+<Canvas of={ComboboxStories.AllVariants} />
+
+<Canvas of={ComboboxStories.AllStates} />
+
+## Virtualization, and why `aria-setsize` is not optional
+
+Above ~100 options (or with `isVirtualized`), the list is windowed with
+`@tanstack/react-virtual` — the second runtime dependency this package has ever taken (MIT,
+US-origin, ~4 KB gz). Because most of the list is not in the DOM, every windowed option
+**must** carry `aria-setsize` and `aria-posinset`, or a screen reader announces "2 of 12"
+for a 4,000-item list. Below the threshold the list is plain DOM.
+
+<Canvas of={ComboboxStories.Virtualized} />
+
+<Canvas of={ComboboxStories.Interactive} />

package/src/Combobox/Combobox.stories.tsx

@@ -0,0 +1,245 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import type { ListboxItem } from "../Listbox/Listbox.tsx"
+import { Combobox } from "./Combobox.tsx"
+
+const LANGUAGES: ListboxItem[] = [
+  { label: "English", value: "eng" },
+  { label: "Spanish", value: "spa" },
+  { label: "French", value: "fra" },
+  { label: "German", value: "deu" },
+  { label: "Japanese", value: "jpn" },
+  { label: "Korean", value: "kor" },
+  { label: "Portuguese", value: "por" },
+]
+
+const LANGUAGES_DISABLED_FIRST: ListboxItem[] = [
+  { isDisabled: true, label: "English", value: "eng" },
+  { label: "Spanish", value: "spa" },
+  { label: "French", value: "fra" },
+]
+
+// A long list, to trip the auto-virtualization threshold.
+const MANY: ListboxItem[] = Array.from(
+  { length: 500 },
+  (_unused, index) => ({
+    label: `Track ${index + 1}`,
+    textValue: `Track ${index + 1}`,
+    value: `track-${index + 1}`,
+  }),
+)
+
+const meta = {
+  title: "Components/Combobox",
+  component: Combobox,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Combobox>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const ComboboxHarness = ({
+  emptyLabel,
+  error,
+  footer,
+  isCreatable,
+  isInitiallyVisible = false,
+  isLoading,
+  isMultiple,
+  isVirtualized,
+  options,
+  triggerLabel,
+}: {
+  emptyLabel?: string
+  error?: ReactNode
+  footer?: ReactNode
+  isCreatable?: boolean
+  isInitiallyVisible?: boolean
+  isLoading?: boolean
+  isMultiple?: boolean
+  isVirtualized?: boolean
+  options: ListboxItem[]
+  triggerLabel: string
+}): ReactNode => {
+  const { hide, isVisible, toggle } = useVisibility({
+    isVisible: isInitiallyVisible,
+  })
+
+  const [chosen, setChosen] = useState<string[]>([])
+
+  return (
+    <>
+      <Combobox
+        emptyLabel={emptyLabel}
+        error={error}
+        footer={footer}
+        isCreatable={isCreatable}
+        isLoading={isLoading}
+        isMultiple={isMultiple}
+        isVirtualized={isVirtualized}
+        isVisible={isVisible}
+        onDismiss={hide}
+        onSelect={(value) => {
+          setChosen((previous) =>
+            previous.includes(value)
+              ? previous.filter((one) => one !== value)
+              : [...previous, value],
+          )
+        }}
+        options={options}
+        trigger={
+          <Button appearance="outline" onClick={toggle}>
+            {triggerLabel}
+          </Button>
+        }
+      />
+
+      <p className="mt-2 text-content-muted text-xs">
+        Chosen: {chosen.join(", ") || "—"}
+      </p>
+    </>
+  )
+}
+
+export const Default: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Search languages</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      options={LANGUAGES}
+      triggerLabel="Search languages"
+    />
+  ),
+}
+
+/**
+ * The loading and error panel states — the ones only `PathPicker` had
+ * all of, and every fleet picker did differently. Both keep the popup
+ * open.
+ */
+export const AllStates: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Search</Button>,
+  },
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <ComboboxHarness
+        isLoading
+        options={LANGUAGES}
+        triggerLabel="Loading state"
+      />
+
+      <ComboboxHarness
+        error="Could not reach the server."
+        options={LANGUAGES}
+        triggerLabel="Error state"
+      />
+    </div>
+  ),
+}
+
+/**
+ * Multi-select renders the chosen values as removable chips rather
+ * than filling the input, with a sticky footer hint — the
+ * `LanguageCodeField` and `LinkPicker` shapes. `isCreatable` lets Enter
+ * commit the raw query.
+ */
+export const AllVariants: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Pick languages</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      footer="Type a code and press Enter to add it."
+      isCreatable
+      isMultiple
+      options={LANGUAGES}
+      triggerLabel="Pick languages"
+    />
+  ),
+}
+
+/**
+ * Five hundred options, windowed with `@tanstack/react-virtual`: only
+ * the visible rows are in the DOM, so each carries `aria-setsize` and
+ * `aria-posinset` — otherwise a screen reader announces "2 of 12" for
+ * a list that is nothing of the sort.
+ */
+export const Virtualized: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: MANY,
+    trigger: <Button>Search 500 tracks</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      isInitiallyVisible
+      options={MANY}
+      triggerLabel="Search 500 tracks"
+    />
+  ),
+}
+
+/**
+ * Open it and type: the list filters as you go, arrows move the active
+ * option while the caret stays in the input, Enter chooses, and Escape
+ * clears the query before it closes.
+ */
+export const Interactive: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Search languages</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      options={LANGUAGES}
+      triggerLabel="Search languages"
+    />
+  ),
+}
+
+/**
+ * A disabled option in the seed position. Opening seeds the active row at
+ * index 0, so the resolved active descendant must skip past the disabled
+ * first option to the first enabled one — and Enter must never commit the
+ * disabled value.
+ */
+export const DisabledFirstOption: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES_DISABLED_FIRST,
+    trigger: <Button>Pick a language</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      isInitiallyVisible
+      options={LANGUAGES_DISABLED_FIRST}
+      triggerLabel="Pick a language"
+    />
+  ),
+}