@charcuterie/ui 0.1.1 → 0.2.0

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>
+    )
+  },
+}

package/src/SortableTableHeader/SortableTableHeader.test.tsx

@@ -0,0 +1,180 @@
+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 "./SortableTableHeader.stories.tsx"
+
+const { AllVariants, Default, Interactive } =
+  composeStories(stories)
+
+/**
+ * `aria-sort` exists **nowhere in the fleet** — not in mux-magic,
+ * not in rip-deck, not in castkit. The one sortable table renders
+ * the state as `{sortDirection === "asc" ? "▲" : "▼"}`, which a
+ * screen reader announces as "black up-pointing triangle" if the
+ * font has it at all, and this sandbox's headless Chromium does not.
+ */
+test("the cell announces the sort, not the glyph", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  const title = expectAgentDrivable(canvas, {
+    name: "Title",
+    role: "columnheader",
+  })
+
+  await expect(title).toHaveAttribute(
+    "aria-sort",
+    "ascending",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * `none`, 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.
+ */
+test("an unsorted sortable column says `none`", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllVariants)
+
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Size",
+      role: "columnheader",
+    }),
+  ).toHaveAttribute("aria-sort", "none")
+
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Year",
+      role: "columnheader",
+    }),
+  ).toHaveAttribute("aria-sort", "descending")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The cell announces and the button acts. 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's structure.
+ */
+test("the header is a columnheader containing a button", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const header = expectAgentDrivable(canvas, {
+    name: "Title",
+    role: "columnheader",
+  })
+
+  await expect(header.tagName).toBe("TH")
+
+  await expect(header).toHaveAttribute("scope", "col")
+
+  const button = expectAgentDrivable(canvas, {
+    name: "Title",
+    role: "button",
+  })
+
+  await expect(header).toContainElement(button)
+})
+
+test("clicking an unsorted column asks for ascending", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Year",
+      role: "button",
+    }),
+  )
+
+  await waitFor(() => {
+    expect(
+      expectAgentDrivable(canvas, {
+        name: "Year",
+        role: "columnheader",
+      }),
+    ).toHaveAttribute("aria-sort", "ascending")
+  })
+
+  // Exactly one column ever holds a direction — the invariant a
+  // hand-rolled `▲`/`▼` cannot express at all.
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Title",
+      role: "columnheader",
+    }),
+  ).toHaveAttribute("aria-sort", "none")
+})
+
+test("clicking the sorted column reverses it", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const title = expectAgentDrivable(canvas, {
+    name: "Title",
+    role: "button",
+  })
+
+  await userEvent.click(title)
+
+  await waitFor(() => {
+    expect(
+      expectAgentDrivable(canvas, {
+        name: "Title",
+        role: "columnheader",
+      }),
+    ).toHaveAttribute("aria-sort", "descending")
+  })
+
+  await userEvent.click(title)
+
+  await waitFor(() => {
+    expect(
+      expectAgentDrivable(canvas, {
+        name: "Title",
+        role: "columnheader",
+      }),
+    ).toHaveAttribute("aria-sort", "ascending")
+  })
+})
+
+/**
+ * The name stays the column's name. Appending the state —
+ * "Title, sorted ascending" — duplicates what `aria-sort` already
+ * says *and* breaks `getByRole("columnheader", { name: "Title" })`
+ * the moment somebody sorts it.
+ */
+test("sorting does not rename the column", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Title",
+      role: "button",
+    }),
+  )
+
+  await waitFor(() => {
+    expect(
+      expectAgentDrivable(canvas, {
+        name: "Title",
+        role: "columnheader",
+      }),
+    ).toHaveAttribute("aria-sort", "descending")
+  })
+
+  // Still exactly one match, and still under the same name.
+  expectAgentDrivable(canvas, {
+    name: "Title",
+    role: "columnheader",
+  })
+})

package/src/SortableTableHeader/SortableTableHeader.tsx

@@ -0,0 +1,131 @@
+import type { ReactNode } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type SortDirection = "ascending" | "descending"
+
+export type SortableTableHeaderProps = {
+  children: ReactNode
+  className?: string
+  /**
+   * The direction **this column** is sorted in, or `undefined` when
+   * it is not the sorted one. Undefined is not "ascending by
+   * default": a table has exactly one sorted column and every other
+   * header has to say `aria-sort="none"`, which is what tells a
+   * screen reader which one is live.
+   */
+  direction?: SortDirection
+  /** Called with the direction the header is asking to move to. */
+  onSort: (direction: SortDirection) => void
+}
+
+const NEXT_DIRECTION: Record<SortDirection, SortDirection> =
+  {
+    ascending: "descending",
+    descending: "ascending",
+  }
+
+/**
+ * **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.
+ *
+ * ### `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 the sandbox's headless Chromium does
+ * not have it — so the same glyph measures blank in a screenshot.
+ * Sighted users see a direction, everyone else gets nothing, and 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
+ * that is invisible to every gate the fleet has.
+ *
+ * ### 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 — "Name, sorted ascending" — and that duplicates what
+ * `aria-sort` already says, so the column is announced twice and
+ * `getByRole("columnheader", { name: "Name" })` stops matching the
+ * moment somebody sorts it.
+ */
+export const SortableTableHeader = ({
+  children,
+  className,
+  direction,
+  onSort,
+}: SortableTableHeaderProps): ReactNode => (
+  <th
+    // `none`, not omitted, on the unsorted columns. An absent
+    // `aria-sort` means "this column is not sortable"; `none` means
+    // "sortable, not currently sorted", and a table of the first
+    // kind with one of the second is how a screen-reader user is
+    // told the other four columns cannot be sorted at all.
+    aria-sort={direction ?? "none"}
+    className={toClassName(
+      "border-border-subtle border-b p-0 text-start",
+      className,
+    )}
+    scope="col"
+  >
+    <button
+      className={toClassName(
+        "flex w-full cursor-pointer items-center gap-1.5 bg-transparent px-3 py-2 text-start font-medium text-content-secondary text-xs uppercase tracking-wide transition-colors duration-(--duration-fast) ease-standard",
+        "hover:text-content-primary",
+        FOCUS_RING_CLASS,
+      )}
+      onClick={() => {
+        onSort(
+          direction === undefined
+            ? "ascending"
+            : NEXT_DIRECTION[direction],
+        )
+      }}
+      type="button"
+    >
+      {children}
+
+      <svg
+        // Decoration. `aria-sort` on the cell above is the same fact
+        // said in a way assistive technology can read, and the fleet
+        // ships only this half.
+        aria-hidden="true"
+        className={toClassName(
+          "size-3.5 shrink-0 transition-[transform,opacity] duration-(--duration-fast) ease-standard",
+          direction === undefined && "opacity-0",
+          direction === "descending" && "rotate-180",
+        )}
+        fill="none"
+        focusable={false}
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        viewBox="0 0 24 24"
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path d="m6 15 6-6 6 6" />
+      </svg>
+    </button>
+  </th>
+)

package/src/Toast/Toast.mdx

@@ -0,0 +1,84 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ToastStories from "./Toast.stories";
+
+<Meta of={ToastStories} />
+
+# Toast
+
+The plan demoted this from P0 with the note *"its duplication evidence was almost entirely
+those two"*, and the M6 survey confirmed it: **the React fleet has no toast at all.**
+mux-magic's only hit is a comment about an undo-toast "rendered elsewhere"; the real ones
+are in plex-channels' and darius-learns' vanilla JavaScript.
+
+It ships anyway, on Kevin's call, and one thing here is genuinely new — the plan wrote a
+machine down and M2 never built it:
+
+> | Toast lifecycle | entering → visible → exiting → removed |
+
+<Canvas of={ToastStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why a `Status`, when a boolean and a timeout would do
+
+Because a boolean cannot express **why** the node is still mounted. A toast that is leaving
+is still painted, still occupies its slot, and must not be announced again — and
+`isVisible === false` says none of that.
+
+| Transition | Legal | Why |
+| --- | --- | --- |
+| `entering → visible` | yes | after one frame, so the enter animation has something to animate *from* |
+| `visible → exiting` | yes | the duration elapsed, or the user dismissed |
+| `visible → removed` | **no** | skipping the exit is the flicker every hand-rolled stack has |
+| `exiting → visible` | yes | hovering a toast that is sliding away has to bring it back |
+| `removed → anything` | **no** | terminal, so `onDismiss` fires exactly once |
+
+The last row is not hypothetical. Hover-to-pause plus a dismiss button means two independent
+timers can be in flight, and the hand-rolled version reconciles them with a `clearTimeout`
+and a ref. Here the second one **throws**.
+
+<Canvas of={ToastStories.AllVariants} />
+
+## One region, and it is polite
+
+Not two. The usual arrangement — a polite region and an assertive one, so a danger toast
+interrupts — was rejected because **the interrupting case does not belong in a toast at
+all.** A message that must be heard *now* is one the user has to be able to go back and
+read, and a toast is gone in five seconds. If it matters that much it is an `Alert` on the
+page, which this library already ships and which stays put.
+
+`Field` draws the same line for its error text. This library announces **once**, in the
+place the user can act on it.
+
+`role="status"` is `aria-live="polite"` *plus `aria-atomic="true"`* by default, and atomic is
+wrong here — it re-reads the entire stack every time one arrives. `aria-atomic="false"` sits
+beside it for exactly that reason.
+
+<Canvas of={ToastStories.AllStates} />
+
+## The stack does not own the toasts
+
+`toasts` comes in and `onDismiss` goes out. There is no `toast()` function, no imperative
+queue, and no context provider — an app already has a store (mux-magic has Jotai, rip-deck
+has its own), and a component library that ships a second one is asking every consumer to
+keep two lists of the same notifications in sync.
+
+The lifecycle *inside* one toast is state a store cannot see, which is why `Toast` owns that
+and nothing more.
+
+## `title` is a string
+
+Not a `ReactNode`. It is what the region announces and what names each toast's own dismiss
+button — a stack of three all offering "Dismiss" is three matches for one query, which
+`expectAgentDrivable` treats as a failure.
+
+## `pointer-events-none` on the container
+
+A fixed overlay across the bottom of the viewport swallows every click in that band,
+including on the app behind it, and it does so invisibly. The container passes clicks through
+and each toast takes them back.
+
+<Canvas of={ToastStories.Interactive} />