@charcuterie/ui 0.1.1 → 0.2.0

package/src/Menu/MenuAction.tsx

@@ -0,0 +1,95 @@
+import type { ReactNode } from "react"
+import { useEffect } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import type { MenuItem } from "./Menu.tsx"
+
+export type MenuActionProps = {
+  item: MenuItem
+  onDismiss: () => void
+  /** `RovingFocus.register` — membership of the arrow-key group. */
+  register: (value: string) => () => void
+  tabIndex: number
+  trackElement: (
+    key: string,
+    element: HTMLButtonElement | null,
+  ) => void
+}
+
+/**
+ * Its own file because **registration is an effect**, and an effect
+ * cannot run in a loop — the same reason `TabTrigger` and
+ * `AccordionSection` are separate. Any member of a registering group
+ * ends up shaped like this.
+ *
+ * A disabled item is simply not registered, so the arrow keys skip
+ * it without any command in `RovingFocus` knowing what "disabled"
+ * means. It stays in the DOM and stays announced, which is the
+ * difference between "you cannot do this right now" and "this does
+ * not exist".
+ */
+export const MenuAction = ({
+  item,
+  onDismiss,
+  register,
+  tabIndex,
+  trackElement,
+}: MenuActionProps): ReactNode => {
+  const {
+    icon,
+    isDisabled = false,
+    key,
+    label,
+    onSelect,
+  } = item
+
+  useEffect(() => {
+    if (isDisabled) {
+      return
+    }
+
+    return register(key)
+  }, [isDisabled, key, register])
+
+  return (
+    <button
+      className={toClassName(
+        "flex w-full cursor-pointer items-center gap-2 rounded-sm bg-transparent px-2 py-1.5 text-start text-content-primary text-sm transition-colors duration-(--duration-fast) ease-standard",
+        "hover:bg-intent-neutral-surface",
+        isDisabled &&
+          "cursor-not-allowed text-content-disabled hover:bg-transparent",
+        FOCUS_RING_CLASS,
+      )}
+      disabled={isDisabled}
+      onClick={() => {
+        onSelect()
+
+        // Choosing dismisses. A menu that stays open after an action
+        // has fired is the one interaction users read as "it didn't
+        // work", and every one of the fleet's menus closes here
+        // today by unmounting its whole parent.
+        onDismiss()
+      }}
+      ref={(element) => {
+        trackElement(key, element)
+      }}
+      role="menuitem"
+      tabIndex={tabIndex}
+      type="button"
+    >
+      {icon === undefined ? null : (
+        <span
+          // Decoration beside the item's own text. An icon that
+          // announces itself turns "Delete" into "trash Delete".
+          aria-hidden="true"
+          className="shrink-0 text-content-secondary"
+        >
+          {icon}
+        </span>
+      )}
+
+      {label}
+    </button>
+  )
+}

package/src/Select/Select.mdx

@@ -0,0 +1,74 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as SelectStories from "./Select.stories";
+
+<Meta of={SelectStories} />
+
+# Select
+
+Eighteen sites in the fleet, and they split cleanly in two: **twelve native `<select>`s**
+that differ only in their Tailwind classes, and **six hand-rolled `role="listbox"`
+controls**. This component is the first twelve. The other six are a different pattern —
+see below.
+
+<Canvas of={SelectStories.Default} />
+
+## Props
+
+<Controls />
+
+## There is no state kind here, and that is the finding
+
+Every other interactive component in this package owns its state through
+`@charcuterie/logic`. This one owns **none**, because the platform already does — a
+`<select>` holds the chosen option in the DOM, and putting a `useSinglePicker` beside it
+would create the exact conflict the state layer exists to prevent:
+
+> Two things believing they hold `value`.
+
+That is the Radix argument from `Popover`, pointed at ourselves. So `value` seeds
+`defaultValue` and changes are reported outward.
+
+The consequence worth knowing: **`Select` is uncontrolled and `Tabs` is not**, and a reader
+should be able to tell why without asking. A tab bar's selection has no DOM representation,
+so something has to hold it. A select's does.
+
+<Canvas of={SelectStories.AllVariants} />
+
+## Native, and what that rules out
+
+| Native gives you | A hand-rolled listbox rebuilds |
+| --- | --- |
+| Type-ahead | a keystroke buffer and a timer |
+| Home / End / PageUp / PageDown | four more key handlers |
+| The mobile wheel picker | nothing that feels native |
+| Form submission and `:invalid` | a hidden input |
+| Autofill | — |
+
+What it cannot do is render a rich option — an icon, two lines, a badge — or filter.
+mux-magic has six controls that need one of those (`CommandPicker`, `PathPicker`,
+`LinkPicker`, `EnumPicker`, `AssFieldPicker`, `RenameTargetPicker`), and **every one of them
+is a `Combobox`**: a text input that filters a listbox. Different pattern, different ARIA
+contract, P2 in the plan.
+
+Building a bare `Listbox` here that none of the six could adopt would have shipped a
+component with no caller — the mistake this milestone was explicitly checking for.
+
+## The placeholder is a disabled option
+
+Not an empty-valued one. An enabled `<option value="">` looks identical, is selectable, and
+silently posts `""`. Disabled, it reads as a prompt and can never be submitted.
+
+<Canvas of={SelectStories.AllStates} />
+
+## `appearance-none` takes the arrow away
+
+Removing the UA's own chevron and forgetting to put one back leaves a control that looks
+exactly like a text input. The replacement is `aria-hidden` decoration in the same grid
+cell, with `pe-9` reserving room for it.
+
+## Naming, once
+
+Either `label` (which becomes `aria-label`) **or** a surrounding `Field` — never both. Two
+naming mechanisms firing at once means the accessible name is whichever won, which is not a
+thing a reader can predict.

package/src/Select/Select.stories.tsx

@@ -0,0 +1,126 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { Field } from "../Field/Field.tsx"
+import type { SelectItem } from "./Select.tsx"
+import { Select } from "./Select.tsx"
+
+const PROFILES: SelectItem[] = [
+  { label: "Lossless remux", value: "lossless" },
+  { label: "Compressed 1080p", value: "compressed" },
+  { isDisabled: true, label: "Dolby Vision", value: "dv" },
+]
+
+const GROUPED: SelectItem[] = [
+  {
+    label: "Video",
+    options: [
+      { label: "Remux", value: "remux" },
+      { label: "Transcode", value: "transcode" },
+    ],
+  },
+  {
+    label: "Audio",
+    options: [
+      { label: "Passthrough", value: "passthrough" },
+      { label: "Downmix", value: "downmix" },
+    ],
+  },
+]
+
+const meta = {
+  title: "Components/Select",
+  component: Select,
+  parameters: { layout: "padded" },
+  argTypes: { size: controlSizeArgType },
+  args: {
+    isDisabled: false,
+    options: PROFILES,
+    size: "md",
+  },
+} satisfies Meta<typeof Select>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { label: "Rip profile", options: PROFILES },
+}
+
+export const AllVariants: Story = {
+  args: { label: "Rip profile", options: PROFILES },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="sm">
+        <Select
+          label="Profile sm"
+          options={PROFILES}
+          size="sm"
+        />
+      </StoryCell>
+
+      <StoryCell label="lg">
+        <Select
+          label="Profile lg"
+          options={PROFILES}
+          size="lg"
+        />
+      </StoryCell>
+
+      <StoryCell label="grouped">
+        <Select label="Stream kind" options={GROUPED} />
+      </StoryCell>
+
+      <StoryCell label="placeholder">
+        <Select
+          label="Profile with prompt"
+          options={PROFILES}
+          placeholder="Choose a profile…"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * The disabled option is still announced and still unselectable —
+ * "you cannot do this right now", rather than the option not
+ * existing. A `placeholder` is the same trick at the top of the
+ * list: disabled, so it reads as a prompt and can never be
+ * submitted.
+ */
+export const AllStates: Story = {
+  args: { label: "Rip profile", options: PROFILES },
+  render: () => (
+    <StoryGrid columns={3}>
+      <StoryCell label="default">
+        <Select
+          label="Profile default"
+          options={PROFILES}
+        />
+      </StoryCell>
+
+      <StoryCell label="disabled">
+        <Select
+          isDisabled
+          label="Profile disabled"
+          options={PROFILES}
+        />
+      </StoryCell>
+
+      <StoryCell label="in a Field">
+        <Field
+          description="Applied to every title on the disc."
+          label="Profile in a field"
+        >
+          <Select options={PROFILES} />
+        </Field>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}

package/src/Select/Select.test.tsx

@@ -0,0 +1,129 @@
+import { composeStories } from "@storybook/react"
+import { expect, 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 "./Select.stories.tsx"
+
+const { AllStates, AllVariants, Default } =
+  composeStories(stories)
+
+test("a select is named, and therefore findable", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  // Twelve of the fleet's fourteen native selects have neither a
+  // `<label for>` nor an `aria-label`, so this query returns nothing
+  // for any of them. A `<select>` reports `role="combobox"`.
+  expectAgentDrivable(canvas, {
+    name: "Rip profile",
+    role: "combobox",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("choosing reports the value outward", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const select = expectAgentDrivable(canvas, {
+    name: "Rip profile",
+    role: "combobox",
+  }) as HTMLSelectElement
+
+  await userEvent.selectOptions(select, "compressed")
+
+  await expect(select.value).toBe("compressed")
+})
+
+/**
+ * The platform owns the value, and this component owns none. Every
+ * other interactive component here holds its state in
+ * `@charcuterie/logic`; putting a `useSinglePicker` beside a
+ * `<select>` would be two things believing they hold one fact —
+ * the Radix argument from `Popover`, pointed at ourselves.
+ */
+test("the initial value seeds the DOM and nothing more", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const select = expectAgentDrivable(canvas, {
+    name: "Profile with prompt",
+    role: "combobox",
+  }) as HTMLSelectElement
+
+  // A placeholder is a *disabled* option, so it shows and cannot be
+  // submitted. An empty-valued enabled option would look identical
+  // and silently post "".
+  await expect(select.value).toBe("")
+
+  const [placeholder] = Array.from(select.options)
+
+  await expect(placeholder).toBeDisabled()
+})
+
+test("a disabled option stays announced", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const select = expectAgentDrivable(canvas, {
+    name: "Rip profile",
+    role: "combobox",
+  }) as HTMLSelectElement
+
+  const dolby = Array.from(select.options).find(
+    (option) => option.value === "dv",
+  )
+
+  // In the tree, and unselectable. Removing it instead would tell a
+  // screen-reader user the profile does not exist rather than that
+  // it is unavailable.
+  await expect(dolby).toBeDisabled()
+
+  await expect(dolby).toHaveTextContent("Dolby Vision")
+})
+
+test("option groups keep their group names", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const select = expectAgentDrivable(canvas, {
+    name: "Stream kind",
+    role: "combobox",
+  }) as HTMLSelectElement
+
+  const groups = Array.from(
+    select.querySelectorAll("optgroup"),
+  ).map((group) => group.label)
+
+  await expect(groups).toEqual(["Video", "Audio"])
+})
+
+test("a disabled select is disabled, not merely dimmed", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Profile disabled",
+      role: "combobox",
+    }),
+  ).toBeDisabled()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("inside a Field, the label does the naming", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  // No `label` prop on this one — `Field` clones an `id` in and its
+  // `<label for>` picks it up. Two naming mechanisms that must not
+  // both fire, or the accessible name is the wrong one.
+  const select = expectAgentDrivable(canvas, {
+    name: "Profile in a field",
+    role: "combobox",
+  })
+
+  await expect(select).not.toHaveAttribute("aria-label")
+
+  await expect(select).toHaveAttribute("aria-describedby")
+})

package/src/Select/Select.tsx

@@ -0,0 +1,200 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type {
+  ChangeEvent,
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import {
+  CONTROL_SIZE_CLASS,
+  MIN_TOUCH_TARGET_CLASS,
+} from "../controlStyles.ts"
+import {
+  DISABLED_CLASS,
+  FOCUS_RING_CLASS,
+} from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type SelectOption = {
+  isDisabled?: boolean
+  label: string
+  value: string
+}
+
+export type SelectOptionGroup = {
+  label: string
+  options: SelectOption[]
+}
+
+export type SelectItem = SelectOption | SelectOptionGroup
+
+/**
+ * The HTML attributes are passed through, and that is not
+ * convenience — it is what makes the `Field` slot work at all.
+ *
+ * `Field` clones `id`, `aria-describedby`, `aria-invalid` and
+ * `required` onto whatever control it is given. A component with a
+ * closed prop list **silently drops all four**: the field renders,
+ * the label still points at nothing, and every assertion about the
+ * control's own props passes because they never arrived. Found by
+ * the one test that asked the control what it had been handed.
+ *
+ * Same arrangement as `Button`, for the same reason.
+ */
+export type SelectProps = Omit<
+  ComponentPropsWithRef<"select">,
+  "disabled" | "onChange" | "size" | "value"
+> & {
+  className?: string
+  isDisabled?: boolean
+  /**
+   * The accessible name, when this is **not** inside a `Field`. A
+   * `<select>` with neither a `<label for>` nor an `aria-label` is
+   * announced as "combobox" and is unfindable by
+   * `getByRole("combobox", { name })` — twelve of the fleet's
+   * fourteen native selects are in exactly that state.
+   */
+  label?: string
+  onChange?: (value: string) => void
+  options: SelectItem[]
+  /**
+   * A disabled first entry, not a real option. Reads as a prompt to
+   * a sighted user and cannot be submitted, which is what a
+   * placeholder should mean — unlike an empty-valued option, which
+   * is selectable and silently posts "".
+   */
+  placeholder?: string
+  size?: ControlSize
+  /** **Initial** only, like every other value prop in this library. */
+  value?: string
+}
+
+const getIsGroup = (
+  item: SelectItem,
+): item is SelectOptionGroup => "options" in item
+
+/**
+ * A styled native `<select>`, and the fleet's fourteen hand-rolled
+ * ones collapse onto it.
+ *
+ * ### There is no state kind here, and that is the finding
+ *
+ * Every other interactive component in this package owns its state
+ * through `@charcuterie/logic`. This one owns none, because the
+ * platform already does: a `<select>` holds the chosen option in the
+ * DOM, and putting a `useSinglePicker` beside it would create the
+ * exact conflict the state layer exists to prevent — two things
+ * believing they hold `value`, which is the Radix argument from
+ * `Popover` pointed at ourselves. So `value` seeds `defaultValue`
+ * and changes are reported outward.
+ *
+ * The consequence worth knowing: **`Select` is uncontrolled and
+ * `Tabs` is not**, and a reader should be able to tell why without
+ * asking. A tab bar's selection has no DOM representation, so
+ * something has to hold it; a select's does.
+ *
+ * ### Native, and what that rules out
+ *
+ * A `<select>` cannot render a rich option — an icon, two lines, a
+ * badge — and cannot filter. mux-magic has six controls that need
+ * one of those (`CommandPicker`, `PathPicker`, `LinkPicker`,
+ * `EnumPicker`, `AssFieldPicker`, `RenameTargetPicker`), and every
+ * one of them is a **`Combobox`**: a text input that filters a
+ * listbox. That is a different pattern with a different ARIA
+ * contract, it is P2 in the plan, and building a bare `Listbox`
+ * here that none of the six could adopt would have shipped a
+ * component with no caller.
+ *
+ * What native buys, and what a hand-rolled listbox has to rebuild
+ * from nothing: type-ahead, Home/End, PageUp/PageDown, the mobile
+ * wheel picker, form submission, `:invalid`, and autofill.
+ */
+export const Select = ({
+  className,
+  isDisabled = false,
+  label,
+  onChange,
+  options,
+  placeholder,
+  size = "md",
+  value,
+  ...selectProps
+}: SelectProps): ReactNode => (
+  <div className="relative inline-grid w-full items-center">
+    <select
+      {...selectProps}
+      aria-label={label}
+      className={toClassName(
+        "w-full cursor-pointer appearance-none rounded-md border border-border-default bg-surface-raised text-content-primary transition-colors duration-(--duration-fast) ease-standard",
+        // Room for the chevron below, which sits in the same grid
+        // cell. A `<select>`'s own arrow is what `appearance-none`
+        // removes, and forgetting to put one back leaves a control
+        // that looks exactly like a text input.
+        "pe-9",
+        CONTROL_SIZE_CLASS[size],
+        MIN_TOUCH_TARGET_CLASS,
+        "hover:border-border-strong",
+        FOCUS_RING_CLASS,
+        DISABLED_CLASS,
+        className,
+      )}
+      defaultValue={
+        value ??
+        (placeholder === undefined ? undefined : "")
+      }
+      disabled={isDisabled}
+      onChange={(
+        changeEvent: ChangeEvent<HTMLSelectElement>,
+      ) => {
+        onChange?.(changeEvent.currentTarget.value)
+      }}
+    >
+      {placeholder === undefined ? null : (
+        <option disabled value="">
+          {placeholder}
+        </option>
+      )}
+
+      {options.map((item) =>
+        getIsGroup(item) ? (
+          <optgroup key={item.label} label={item.label}>
+            {item.options.map((option) => (
+              <option
+                disabled={option.isDisabled}
+                key={option.value}
+                value={option.value}
+              >
+                {option.label}
+              </option>
+            ))}
+          </optgroup>
+        ) : (
+          <option
+            disabled={item.isDisabled}
+            key={item.value}
+            value={item.value}
+          >
+            {item.label}
+          </option>
+        ),
+      )}
+    </select>
+
+    <svg
+      // Decoration. The control beside it already has a name, and an
+      // announced "chevron" is noise on every select in the fleet.
+      aria-hidden="true"
+      className="pointer-events-none absolute end-3 size-4 text-content-secondary"
+      fill="none"
+      focusable={false}
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth={1.75}
+      viewBox="0 0 24 24"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="m6 9 6 6 6-6" />
+    </svg>
+  </div>
+)

package/src/SortableTableHeader/SortableTableHeader.mdx

@@ -0,0 +1,67 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as SortableTableHeaderStories from "./SortableTableHeader.stories";
+
+<Meta of={SortableTableHeaderStories} />
+
+# SortableTableHeader
+
+**The header cell, and nothing else.** No `DataTable`, no rows, no comparator — the plan is
+explicit about that, and the reason is that sorting *data* is app logic that differs per
+column type, while announcing *that* a column is sorted is markup every table gets wrong the
+same way.
+
+<Canvas of={SortableTableHeaderStories.Default} />
+
+## Props
+
+<Controls />
+
+## `aria-sort` does not exist anywhere in the fleet
+
+Not in mux-magic, not in rip-deck, not in castkit. mux-magic's `FileExplorerModal` — the one
+sortable table there is — renders the state as a character:
+
+```tsx
+{sortDirection === "asc" ? "▲" : "▼"}
+```
+
+A screen reader announces that as "black up-pointing triangle", if the font has it at all —
+and this sandbox's headless Chromium does not, so the same glyph measures **blank** in a
+screenshot. Sighted users see a direction; everyone else gets nothing.
+
+No automated check anywhere reports it. **axe has no rule for a missing `aria-sort`**,
+because a table with none is a table that is simply not sorted as far as the accessibility
+tree knows.
+
+This is therefore the one component in M6 whose payoff is not duplication — there is a
+single site — but a class of failure invisible to every gate the fleet has.
+
+## `none` is not the same as absent
+
+| `aria-sort` | means |
+| --- | --- |
+| absent | this column **cannot** be sorted |
+| `"none"` | sortable, not currently sorted |
+| `"ascending"` / `"descending"` | this is the sorted column |
+
+A table that omits the attribute on its unsorted columns tells a screen-reader user the other
+four cannot be sorted at all. Exactly one column ever holds a direction.
+
+<Canvas of={SortableTableHeaderStories.AllVariants} />
+
+## The cell announces, the button acts
+
+`aria-sort` belongs on the `<th>`; the click target is a `<button>` inside it. Putting the
+role on the button instead is the common mistake and it breaks the grid semantics — a `<th>`
+that *is* a button is no longer a column header to anything reading the table structure.
+
+## The name stays the column's name
+
+It is tempting to append the state — "Title, sorted ascending" — and that duplicates what
+`aria-sort` already says, so the column is announced twice **and**
+`getByRole("columnheader", { name: "Title" })` stops matching the moment somebody sorts it.
+
+<Canvas of={SortableTableHeaderStories.AllStates} />
+
+<Canvas of={SortableTableHeaderStories.Interactive} />