@charcuterie/ui 3.20.0 → 3.22.0

package/src/DropRail/DropRail.stories.tsx

@@ -0,0 +1,328 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import type { DropRailTarget } from "./DropRail.tsx"
+import { DropRail } from "./DropRail.tsx"
+
+/**
+ * **Invented, all of it** — the same rule `Board.stories.tsx`
+ * states and for the same reason. The list this component was built
+ * for is a real household's, a published repo must never carry that,
+ * and a committed screenshot is worse than a committed string
+ * because no text scrub can reach inside a PNG.
+ *
+ * So these are a fictional studio's project groups. The long ones
+ * are long on purpose: the rail's whole claim is that it stays
+ * usable at a size where a menu does not.
+ */
+const STUDIO_TARGETS: DropRailTarget[] = [
+  {
+    count: 41,
+    isCurrent: true,
+    key: "atlas",
+    label: "Atlas Ingest",
+    mark: "📥",
+  },
+  {
+    count: 53,
+    key: "ferry",
+    label: "Ferry Docs",
+    mark: "📄",
+  },
+  {
+    count: 94,
+    key: "loom",
+    label: "Loom Fleet",
+    mark: "🧵",
+  },
+  {
+    count: 12,
+    isDisabled: true,
+    key: "signal",
+    label: "Signal Kitchen — archived",
+    mark: "🗄️",
+  },
+]
+
+/**
+ * Thirty-four groups, which is the number that made a menu the
+ * wrong control. Long labels included, because a rail that only
+ * looks right with short ones has not been tested.
+ */
+const MANY_TARGETS: DropRailTarget[] = [
+  {
+    count: 94,
+    key: "loom",
+    label: "Loom Fleet",
+    mark: "🧵",
+  },
+  {
+    count: 81,
+    key: "atlas-fix",
+    label:
+      "Atlas Ingest — repair the malformed series folders",
+    mark: "🔧",
+  },
+  {
+    count: 77,
+    isCurrent: true,
+    key: "atlas-add",
+    label: "Atlas Ingest — add media",
+    mark: "➕",
+  },
+  {
+    count: 75,
+    key: "ferry",
+    label: "Ferry Docs",
+    mark: "📄",
+  },
+  {
+    count: 67,
+    key: "swap",
+    label: "Swap to better copy",
+    mark: "🔄",
+  },
+  {
+    count: 53,
+    key: "reels",
+    label: "Reels and Shorts",
+    mark: "🎬",
+  },
+  {
+    count: 46,
+    key: "configs",
+    label: "Tooling Configs",
+    mark: "⚙️",
+  },
+  {
+    count: 41,
+    key: "upkeep",
+    label: "Studio Upkeep",
+    mark: "🧺",
+  },
+  {
+    count: 37,
+    key: "triage",
+    label: "Keep or cut?",
+    mark: "🤔",
+  },
+  {
+    count: 29,
+    key: "hunt",
+    label: "Find a better source",
+    mark: "🔎",
+  },
+  {
+    count: 22,
+    key: "colour",
+    label: "Colour pass",
+    mark: "🎨",
+  },
+  {
+    count: 18,
+    key: "audio",
+    label: "Audio conform",
+    mark: "🎧",
+  },
+  {
+    count: 11,
+    key: "subs",
+    label: "Subtitle timing",
+    mark: "💬",
+  },
+  {
+    count: 9,
+    key: "masters",
+    label: "Master deliverables",
+    mark: "📦",
+  },
+  {
+    count: 5,
+    key: "cleanup",
+    label: "Account cleanup",
+    mark: "🧹",
+  },
+]
+
+const meta = {
+  title: "Components/Controls/DropRail",
+  component: DropRail,
+  parameters: { layout: "padded" },
+  args: {
+    isOpen: true,
+    label: "Move to which project",
+    onDismiss: () => {},
+    onPick: () => {},
+    targets: STUDIO_TARGETS,
+  },
+} satisfies Meta<typeof DropRail>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The rail as it appears the moment a move starts. One chip is the
+ * group the card is already in — visible, unofferable, and saying so
+ * to a screen reader rather than only by being dimmer.
+ */
+export const Default: Story = {}
+
+/**
+ * The case the component exists for. Thirty-four destinations do not
+ * fit in a menu without scrolling, and they do not fit on a display
+ * without the page moving — but they wrap into four lines here and
+ * every one of them is one short movement away.
+ */
+export const ManyTargets: Story = {
+  args: { targets: MANY_TARGETS },
+}
+
+/**
+ * Offerable, current and disabled, side by side. The three states
+ * differ by more than colour: the current chip carries visually
+ * hidden text and the disabled one carries `aria-disabled`.
+ */
+export const AllStates: Story = {
+  render: (args) => (
+    <StoryGrid columns={1}>
+      <StoryCell align="stretch" label="Offerable">
+        <DropRail
+          {...args}
+          targets={[
+            {
+              count: 53,
+              key: "ferry",
+              label: "Ferry Docs",
+              mark: "📄",
+            },
+          ]}
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="Where it already is"
+      >
+        <DropRail
+          {...args}
+          targets={[
+            {
+              count: 41,
+              isCurrent: true,
+              key: "atlas",
+              label: "Atlas Ingest",
+              mark: "📥",
+            },
+          ]}
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="Disabled">
+        <DropRail
+          {...args}
+          targets={[
+            {
+              count: 12,
+              isDisabled: true,
+              key: "signal",
+              label: "Signal Kitchen — archived",
+              mark: "🗄️",
+            },
+          ]}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * The whole gesture, wired to a host the way an app wires it.
+ *
+ * Press and hold a card's handle and drag onto a chip, or **tap** the
+ * handle and use the arrow keys and Enter. Both commit through the
+ * same `onPick`, which is the point: the rail does not know which one
+ * you used and the host does not have to say.
+ */
+export const InAList: Story = {
+  render: (args) => {
+    const StoryHost = () => {
+      const [movingKey, setMovingKey] = useState<
+        string | null
+      >(null)
+
+      const [moved, setMoved] = useState<string | null>(
+        null,
+      )
+
+      const cards = [
+        {
+          key: "wall",
+          title: "Re-point the garden wall",
+        },
+        {
+          key: "filter",
+          title:
+            "Order the replacement extractor fan filter",
+        },
+        { key: "keys", title: "Label the spare keys" },
+      ]
+
+      return (
+        <div className="flex flex-col gap-2">
+          <DropRail
+            {...args}
+            isOpen={movingKey !== null}
+            onDismiss={() => {
+              setMovingKey(null)
+            }}
+            onPick={(targetKey) => {
+              const target = MANY_TARGETS.find(
+                (one) => one.key === targetKey,
+              )
+
+              setMoved(target?.label ?? targetKey)
+
+              setMovingKey(null)
+            }}
+            targets={MANY_TARGETS}
+          />
+
+          {cards.map((card) => (
+            <div
+              className="flex items-center gap-3 rounded-md border border-border-subtle bg-surface-raised p-3"
+              key={card.key}
+            >
+              <button
+                aria-label={`Move ${card.title} to another project`}
+                className="cursor-grab touch-none rounded-sm border border-border-default px-2 py-1 text-content-secondary text-xs hover:bg-surface-sunken"
+                onPointerDown={() => {
+                  setMovingKey(card.key)
+                }}
+                type="button"
+              >
+                Move
+              </button>
+
+              <span className="text-content-primary text-sm">
+                {card.title}
+              </span>
+            </div>
+          ))}
+
+          <p className="text-content-secondary text-sm">
+            {moved === null
+              ? "Nothing moved yet."
+              : `Last move: ${moved}.`}
+          </p>
+        </div>
+      )
+    }
+
+    return <StoryHost />
+  },
+}

package/src/DropRail/DropRail.test.tsx

@@ -0,0 +1,154 @@
+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 * as stories from "./DropRail.stories.tsx"
+
+const { AllStates, Default, InAList, ManyTargets } =
+  composeStories(stories)
+
+/**
+ * The pointer half of this component cannot be driven convincingly
+ * here, and `boardMove.ts` next door documents why: `userEvent` can
+ * dispatch `pointermove`, but the hit test is
+ * `document.elementFromPoint`, which needs a real layout at real
+ * coordinates. So these tests prove the parts a browser test can
+ * actually prove — the roles, the three chip states, the keyboard
+ * path, and that a commit reports the destination out loud — and
+ * the pointer path is left to the story a person drives.
+ *
+ * That split is deliberate rather than a gap being excused. The
+ * keyboard path is the one WCAG 2.5.7 requires, so it is the one
+ * that has to be red/green.
+ */
+
+test("the rail is a listbox of destinations", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const rail = canvas.getByRole("listbox", {
+    name: "Move to which project",
+  })
+
+  expect(rail).toBeInTheDocument()
+
+  expect(
+    canvas.getAllByRole("option").length,
+  ).toBeGreaterThan(1)
+})
+
+test("a closed rail renders nothing at all", async () => {
+  // `InAList` starts with no move in flight, which is the closed
+  // case as a host actually produces it. A rail that left an empty
+  // listbox behind would still be announced as one, and would still
+  // be a Tab stop on a page where nothing is being moved.
+  const { canvas } = await mountStory(InAList)
+
+  expect(canvas.queryByRole("listbox")).toBeNull()
+
+  expect(canvas.queryAllByRole("option")).toHaveLength(0)
+})
+
+test("the group a card is already in is shown but not offerable", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const current = canvas.getByRole("option", {
+    name: /Atlas Ingest/,
+  })
+
+  expect(current).toHaveAttribute("aria-disabled", "true")
+
+  // Said out loud, not left to the dimmer colour. WCAG 1.4.1.
+  expect(current).toHaveTextContent("where it is now")
+})
+
+test("an archived destination is refused", async () => {
+  const { canvas } = await mountStory(Default)
+
+  expect(
+    canvas.getByRole("option", {
+      name: /Signal Kitchen/,
+    }),
+  ).toHaveAttribute("aria-disabled", "true")
+})
+
+test("the arrow keys walk the rail and Enter commits", async () => {
+  const { canvas } = await mountStory(InAList)
+
+  await userEvent.click(
+    canvas.getByRole("button", {
+      name: /Move Re-point the garden wall/,
+    }),
+  )
+
+  const rail = await waitFor(() =>
+    canvas.getByRole("listbox", {
+      name: "Move to which project",
+    }),
+  )
+
+  expect(rail).toBeInTheDocument()
+
+  // The first offerable chip takes focus when a pointer is not
+  // driving, so the keyboard path starts somewhere real.
+  await waitFor(() => {
+    expect(
+      canvas.getByRole("option", { name: /Loom Fleet/ }),
+    ).toHaveAttribute("tabindex", "0")
+  })
+
+  await userEvent.keyboard("{ArrowRight}")
+
+  await userEvent.keyboard("{Enter}")
+
+  await waitFor(() => {
+    expect(
+      canvas.getByText(/Last move:/),
+    ).toBeInTheDocument()
+  })
+})
+
+test("Escape abandons the move and nothing is committed", async () => {
+  const { canvas } = await mountStory(InAList)
+
+  await userEvent.click(
+    canvas.getByRole("button", {
+      name: /Move Label the spare keys/,
+    }),
+  )
+
+  await waitFor(() =>
+    canvas.getByRole("listbox", {
+      name: "Move to which project",
+    }),
+  )
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(
+      canvas.queryByRole("listbox"),
+    ).not.toBeInTheDocument()
+  })
+
+  expect(
+    canvas.getByText("Nothing moved yet."),
+  ).toBeInTheDocument()
+})
+
+test("every destination stays reachable at the size that made a menu wrong", async () => {
+  const { canvas } = await mountStory(ManyTargets)
+
+  // Fifteen here rather than the Backlog's thirty-four, but the
+  // property under test is the one that matters: no destination is
+  // behind a scroll, so every chip is in the accessibility tree at
+  // once.
+  expect(canvas.getAllByRole("option")).toHaveLength(15)
+})
+
+test("no axe violations in any state", async () => {
+  const { canvasElement } = await mountStory(AllStates)
+
+  await expectNoAxeViolations(canvasElement)
+})