@charcuterie/ui 0.1.1 → 1.0.0

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

package/src/Toast/Toast.stories.tsx

@@ -0,0 +1,192 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import { intentArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { Toast } from "./Toast.tsx"
+import type { ToastRecord } from "./ToastRegion.tsx"
+import { ToastRegion } from "./ToastRegion.tsx"
+
+const noop = () => undefined
+
+/**
+ * `duration={0}` throughout the boards. A toast that removes itself
+ * after five seconds makes a screenshot a race, and pinning it open
+ * is the documented way to hold one for an action anyway.
+ */
+const meta = {
+  title: "Components/Toast",
+  component: Toast,
+  parameters: { layout: "padded" },
+  argTypes: { intent: intentArgType },
+  args: {
+    duration: 0,
+    intent: "neutral",
+    onRemove: noop,
+    title: "Rip finished",
+  },
+} satisfies Meta<typeof Toast>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const ToastList = ({
+  children,
+}: {
+  children: ReactNode
+}): ReactNode => (
+  <ul className="flex w-full max-w-sm list-none flex-col gap-2 p-0">
+    {children}
+  </ul>
+)
+
+export const Default: Story = {
+  args: {
+    children: "Blade Runner (1982) · 9 titles.",
+    title: "Rip finished",
+  },
+  render: (args) => (
+    <ToastList>
+      <Toast {...args} />
+    </ToastList>
+  ),
+}
+
+export const AllVariants: Story = {
+  args: { title: "Rip finished" },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="success">
+        <ToastList>
+          <Toast
+            duration={0}
+            intent="success"
+            onRemove={noop}
+            title="Rip finished"
+          >
+            Blade Runner (1982) · 9 titles.
+          </Toast>
+        </ToastList>
+      </StoryCell>
+
+      <StoryCell label="warning">
+        <ToastList>
+          <Toast
+            duration={0}
+            intent="warning"
+            onRemove={noop}
+            title="Retried title 4"
+          >
+            Two read errors, recovered.
+          </Toast>
+        </ToastList>
+      </StoryCell>
+
+      <StoryCell label="danger">
+        <ToastList>
+          <Toast
+            duration={0}
+            intent="danger"
+            onRemove={noop}
+            title="Bay 3 offline"
+          />
+        </ToastList>
+      </StoryCell>
+
+      <StoryCell label="no description">
+        <ToastList>
+          <Toast
+            duration={0}
+            intent="info"
+            onRemove={noop}
+            title="Order saved"
+          />
+        </ToastList>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * The lifecycle, laid out. `entering` and `exiting` are both
+ * *painted* states — a toast that is leaving still occupies its
+ * slot — which is exactly what a boolean cannot express and why
+ * this is a `Status`.
+ */
+export const AllStates: Story = {
+  args: { title: "Rip finished" },
+  render: () => (
+    <ToastList>
+      <Toast
+        duration={0}
+        intent="success"
+        onRemove={noop}
+        title="Pinned open"
+      >
+        `duration={0}` — stays until dismissed, which is
+        what a toast carrying an action has to do.
+      </Toast>
+
+      <Toast
+        duration={60_000}
+        intent="info"
+        onRemove={noop}
+        title="Timed"
+      >
+        Hovering pauses it, which is why `exiting → visible`
+        is a legal transition.
+      </Toast>
+    </ToastList>
+  ),
+}
+
+/**
+ * The region, doing its actual job. Add a few and watch them stack;
+ * each removes itself when its own machine reaches `removed`, and
+ * the list belongs to the app rather than to this library.
+ */
+export const Interactive: Story = {
+  args: { title: "Rip finished" },
+  render: function InteractiveRegion() {
+    const [toasts, setToasts] = useState<ToastRecord[]>([])
+
+    const [count, setCount] = useState(0)
+
+    return (
+      <>
+        <Button
+          onClick={() => {
+            setCount((previous) => previous + 1)
+
+            setToasts((previous) => [
+              ...previous,
+              {
+                description: `Bay ${count + 1} finished.`,
+                intent: "success",
+                key: `rip-${count}`,
+                title: `Rip ${count + 1} finished`,
+              },
+            ])
+          }}
+        >
+          Finish a rip
+        </Button>
+
+        <ToastRegion
+          onDismiss={(key) => {
+            setToasts((previous) =>
+              previous.filter((one) => one.key !== key),
+            )
+          }}
+          toasts={toasts}
+        />
+      </>
+    )
+  },
+}