@charcuterie/ui 0.1.1 → 1.0.0

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} />

package/src/SortableTableHeader/SortableTableHeader.stories.tsx

@@ -0,0 +1,207 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import type { SortDirection } from "./SortableTableHeader.tsx"
+import { SortableTableHeader } from "./SortableTableHeader.tsx"
+
+const noop = () => undefined
+
+const ROWS = [
+  { size: "24.1 GB", title: "Blade Runner", year: 1982 },
+  { size: "31.7 GB", title: "Alien", year: 1979 },
+  { size: "18.2 GB", title: "Solaris", year: 1972 },
+]
+
+const TABLE_CLASS =
+  "w-full border-collapse text-content-primary text-sm"
+
+const CELL_CLASS =
+  "border-border-subtle border-b px-3 py-2 text-start"
+
+/**
+ * The component owns **only** the header cell, so every story has to
+ * bring its own table. That is the point rather than an
+ * inconvenience: sorting the data is app logic that differs per
+ * column type, and announcing *that* a column is sorted is markup
+ * every table gets wrong the same way.
+ */
+const meta = {
+  title: "Components/SortableTableHeader",
+  component: SortableTableHeader,
+  parameters: { layout: "padded" },
+  args: { onSort: noop },
+} satisfies Meta<typeof SortableTableHeader>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { children: "Title", direction: "ascending" },
+  render: (args) => (
+    <table className={TABLE_CLASS}>
+      <thead>
+        <tr>
+          <SortableTableHeader {...args} />
+
+          <SortableTableHeader onSort={noop}>
+            Year
+          </SortableTableHeader>
+        </tr>
+      </thead>
+
+      <tbody>
+        {ROWS.map((row) => (
+          <tr key={row.title}>
+            <td className={CELL_CLASS}>{row.title}</td>
+
+            <td className={CELL_CLASS}>{row.year}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  ),
+}
+
+/**
+ * `aria-sort="none"` on the unsorted columns, not an omitted
+ * attribute. Absent means "this column is not sortable"; `none`
+ * means "sortable, not currently sorted" — and a table mixing the
+ * two tells a screen-reader user the other columns cannot be sorted
+ * at all.
+ */
+export const AllVariants: Story = {
+  args: { children: "Title" },
+  render: () => (
+    <StoryGrid columns={1}>
+      <StoryCell label="ascending · descending · none">
+        <table className={TABLE_CLASS}>
+          <thead>
+            <tr>
+              <SortableTableHeader
+                direction="ascending"
+                onSort={noop}
+              >
+                Title
+              </SortableTableHeader>
+
+              <SortableTableHeader
+                direction="descending"
+                onSort={noop}
+              >
+                Year
+              </SortableTableHeader>
+
+              <SortableTableHeader onSort={noop}>
+                Size
+              </SortableTableHeader>
+            </tr>
+          </thead>
+
+          <tbody>
+            {ROWS.map((row) => (
+              <tr key={row.title}>
+                <td className={CELL_CLASS}>{row.title}</td>
+
+                <td className={CELL_CLASS}>{row.year}</td>
+
+                <td className={CELL_CLASS}>{row.size}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+export const AllStates: Story = {
+  args: { children: "Title", direction: "ascending" },
+  render: (args) => (
+    <table className={TABLE_CLASS}>
+      <thead>
+        <tr>
+          <SortableTableHeader {...args} />
+        </tr>
+      </thead>
+
+      <tbody>
+        <tr>
+          <td className={CELL_CLASS}>Blade Runner</td>
+        </tr>
+      </tbody>
+    </table>
+  ),
+}
+
+/**
+ * Click a header and watch `aria-sort` move — exactly one column
+ * ever holds a direction, which is the invariant a hand-rolled
+ * `▲`/`▼` cannot express at all.
+ */
+export const Interactive: Story = {
+  args: { children: "Title" },
+  render: function SortableTable() {
+    const [sort, setSort] = useState<{
+      column: "title" | "year"
+      direction: SortDirection
+    }>({ column: "title", direction: "ascending" })
+
+    const sorted = [...ROWS].sort((first, second) => {
+      const order =
+        sort.column === "title"
+          ? first.title.localeCompare(second.title)
+          : first.year - second.year
+
+      return sort.direction === "ascending" ? order : -order
+    })
+
+    return (
+      <table className={TABLE_CLASS}>
+        <thead>
+          <tr>
+            <SortableTableHeader
+              direction={
+                sort.column === "title"
+                  ? sort.direction
+                  : undefined
+              }
+              onSort={(direction) => {
+                setSort({ column: "title", direction })
+              }}
+            >
+              Title
+            </SortableTableHeader>
+
+            <SortableTableHeader
+              direction={
+                sort.column === "year"
+                  ? sort.direction
+                  : undefined
+              }
+              onSort={(direction) => {
+                setSort({ column: "year", direction })
+              }}
+            >
+              Year
+            </SortableTableHeader>
+          </tr>
+        </thead>
+
+        <tbody>
+          {sorted.map((row) => (
+            <tr key={row.title}>
+              <td className={CELL_CLASS}>{row.title}</td>
+
+              <td className={CELL_CLASS}>{row.year}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    )
+  },
+}