@charcuterie/ui 0.1.0

package/src/Popover/Popover.test.tsx

@@ -0,0 +1,191 @@
+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 "./Popover.stories.tsx"
+
+const {
+  AllStates,
+  AllVariants,
+  Default,
+  Interactive,
+  Responsive,
+} = composeStories(stories)
+
+test("the trigger and the panel agree about each other", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Filters",
+    role: "button",
+  })
+
+  await expect(trigger).toHaveAttribute(
+    "aria-expanded",
+    "false",
+  )
+
+  await userEvent.click(trigger)
+
+  // Found through `canvas`, not `screen` — the panel is in the top
+  // layer and still in this story's DOM, which a portal would have
+  // cost.
+  const panel = expectAgentDrivable(canvas, {
+    name: "Filters",
+    role: "dialog",
+  })
+
+  // `aria-controls` really points at the panel. An id that has
+  // drifted renders identically and announces nothing, which is why
+  // `useRole` owns both ends of it.
+  await expect(trigger).toHaveAttribute(
+    "aria-controls",
+    panel.id,
+  )
+
+  // `manual`, not `auto`: the UA's light-dismiss closes the element
+  // by itself and leaves `isVisible` true.
+  await expect(panel).toHaveAttribute("popover", "manual")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the panel is positioned rather than centred by the UA", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open top",
+      role: "button",
+    }),
+  )
+
+  const panel = expectAgentDrivable(canvas, {
+    name: "Filters — top",
+    role: "dialog",
+  })
+
+  // The thing that silently fails if the UA's `inset: 0; margin:
+  // auto` is left in place: the panel would sit dead centre of the
+  // viewport looking deliberate.
+  const { left, top } = panel.getBoundingClientRect()
+
+  await expect(left).toBeGreaterThan(0)
+
+  await expect(top).toBeGreaterThan(0)
+})
+
+test("a panel with nothing tabbable inside is still reachable", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Text only",
+      role: "button",
+    }),
+  )
+
+  const panel = expectAgentDrivable(canvas, {
+    name: "Read error detail",
+    role: "dialog",
+  })
+
+  // Otherwise a keyboard user is told a dialog opened and then
+  // cannot get to it. `FloatingFocusManager` puts the panel itself
+  // in the tab order — `tabindex="0"`, not `-1`, so Tab reaches it
+  // and not only the programmatic focus does.
+  await expect(panel).toHaveAttribute("tabindex", "0")
+
+  await waitFor(() => {
+    expect(panel.contains(document.activeElement)).toBe(
+      true,
+    )
+  })
+})
+
+test("flip and shift keep the panel inside the viewport", async () => {
+  const { canvas } = await mountStory(Responsive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Top edge, asks for top",
+      role: "button",
+    }),
+  )
+
+  const panel = expectAgentDrivable(canvas, {
+    name: "Filters — top start",
+    role: "dialog",
+  })
+
+  // Inside the viewport is the only thing `flip` and `shift`
+  // actually promise — asserting a specific side would be asserting
+  // the collision *did not* happen.
+  const rect = panel.getBoundingClientRect()
+
+  await expect(rect.top).toBeGreaterThanOrEqual(0)
+
+  await expect(rect.bottom).toBeLessThanOrEqual(
+    globalThis.innerHeight,
+  )
+
+  await expect(rect.left).toBeGreaterThanOrEqual(0)
+
+  await expect(rect.right).toBeLessThanOrEqual(
+    globalThis.innerWidth,
+  )
+})
+
+/**
+ * The dismiss layer, driven. Outside press and Escape both route
+ * through `useDismiss` → `onDismiss` → `hide()`, so the panel is
+ * never closed by anything except the state saying so.
+ *
+ * Escape *is* pressable here, unlike `Modal`'s: `useDismiss` listens
+ * for a keydown rather than relying on a UA default action, and a
+ * synthetic keydown is a real keydown as far as a listener is
+ * concerned.
+ */
+test("Escape and an outside press both dismiss through the state", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Filters",
+    role: "button",
+  })
+
+  await userEvent.click(trigger)
+
+  expectAgentDrivable(canvas, {
+    name: "Bay 3 filters",
+    role: "dialog",
+  })
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(canvas.queryByRole("dialog")).toBeNull()
+  })
+
+  await expect(trigger).toHaveAttribute(
+    "aria-expanded",
+    "false",
+  )
+
+  // Reopened, then dismissed by pressing the page behind it.
+  await userEvent.click(trigger)
+
+  await waitFor(() => {
+    expect(canvas.getByRole("dialog")).toBeInTheDocument()
+  })
+
+  await userEvent.click(document.body)
+
+  await waitFor(() => {
+    expect(canvas.queryByRole("dialog")).toBeNull()
+  })
+})

package/src/Popover/Popover.tsx

@@ -0,0 +1,164 @@
+import { useClonedChild } from "@charcuterie/logic"
+import type { Placement } from "@floating-ui/react"
+import {
+  autoUpdate,
+  FloatingFocusManager,
+  flip,
+  offset,
+  shift,
+  useDismiss,
+  useFloating,
+  useInteractions,
+  useRole,
+} from "@floating-ui/react"
+import type { ReactElement, ReactNode } from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type PopoverProps = {
+  children: ReactNode
+  className?: string
+  /**
+   * Required, and it becomes the panel's `aria-label`. A
+   * `role="dialog"` takes **no accessible name from its content**,
+   * so an unnamed one is announced as "dialog" and is unfindable
+   * by `getByRole("dialog", { name })` — the same trap `Spinner`
+   * walked into in M3 with `role="status"`.
+   */
+  heading: string
+  isVisible: boolean
+  /**
+   * Outside press and Escape both land here, through floating-ui's
+   * `useDismiss`. Wire it to a `useVisibility()`'s `hide`.
+   */
+  onDismiss: () => void
+  placement?: Placement
+  /**
+   * The control the panel hangs off. **Cloned, not wrapped** — an
+   * extra `<div>` around a button is how a toolbar's layout
+   * quietly changes.
+   */
+  trigger: ReactElement
+}
+
+/**
+ * Replaces mux-magic's `@radix-ui/react-popover` re-export, and it
+ * is a rewrite rather than a swap for one reason: Radix owns
+ * `open`, so wrapping it leaves `useVisibility` and Radix both
+ * believing they hold it. `@floating-ui/react` is the layer Radix,
+ * Base UI, and Ark UI are all *built on*, and it is controlled by
+ * construction — you pass state in and it never stores any.
+ *
+ * What floating-ui is used for is what only it can do: collision
+ * handling (`flip`, `shift`), a real dismiss layer, and focus
+ * management. Positioning strategy, the top layer, and the ARIA
+ * wiring come from the platform and from `useRole`.
+ *
+ * ### The top layer, from the platform — not a portal
+ *
+ * `popover="manual"` puts the panel in the top layer, which is
+ * what a portal is normally reached for: no `z-index` contest, and
+ * no `overflow: hidden` ancestor clipping it. Unlike a portal it
+ * **stays where it is in the DOM**, so `canvas.getByRole("dialog")`
+ * still finds it and a story keeps its scoping. Same argument as
+ * `Modal`, one layer down.
+ *
+ * `manual`, not `auto`, and that is the state-ownership decision
+ * again: `auto` brings the UA's own light-dismiss, which closes the
+ * element by itself and leaves `isVisible` true. `useDismiss` does
+ * the same job through our callback, so Charcuterie stays the only
+ * thing that decides.
+ *
+ * ### Two UA defaults that have to be undone
+ *
+ * `[popover]` ships `position: fixed; inset: 0; margin: auto`,
+ * which centres the panel in the viewport and fights every
+ * coordinate floating-ui computes — hence `inset-auto m-0`, and
+ * `strategy: "fixed"` so the numbers are viewport-relative like the
+ * top layer itself. Getting either wrong reads as a positioning
+ * bug rather than as a UA default.
+ */
+export const Popover = ({
+  children,
+  className,
+  heading,
+  isVisible,
+  onDismiss,
+  placement = "bottom-start",
+  trigger,
+}: PopoverProps): ReactNode => {
+  const { context, floatingStyles, refs } = useFloating({
+    // Read-only. Charcuterie remains the sole owner; floating-ui
+    // is told what is true and never decides it.
+    open: isVisible,
+    onOpenChange: (isNextVisible) => {
+      if (!isNextVisible) {
+        onDismiss()
+      }
+    },
+    placement,
+    middleware: [offset(8), flip(), shift({ padding: 8 })],
+    strategy: "fixed",
+    whileElementsMounted: autoUpdate,
+  })
+
+  // `useRole` writes `aria-expanded`, `aria-haspopup`, and
+  // `aria-controls` on the trigger and `id` + `role="dialog"` on
+  // the panel, from one source. Hand-writing them alongside is how
+  // an `aria-controls` ends up pointing at an id that moved.
+  const { getFloatingProps, getReferenceProps } =
+    useInteractions([
+      useDismiss(context),
+      useRole(context, { role: "dialog" }),
+    ])
+
+  const clonedTrigger = useClonedChild(trigger, {
+    ...getReferenceProps(),
+    ref: refs.setReference,
+  })
+
+  return (
+    <>
+      {clonedTrigger}
+
+      {isVisible ? (
+        <FloatingFocusManager
+          context={context}
+          modal={false}
+        >
+          <div
+            {...getFloatingProps()}
+            aria-label={heading}
+            className={toClassName(
+              "inset-auto m-0 max-w-xs rounded-md border border-border-default bg-surface-overlay p-3 text-content-primary text-sm shadow-medium",
+              className,
+            )}
+            popover="manual"
+            // Duplicated from `getFloatingProps()` on purpose, and
+            // the two cannot differ — `useRole(context, { role:
+            // "dialog" })` above is where it comes from. Stated
+            // here because a linter cannot see a role through a
+            // spread, and neither can the next reader.
+            role="dialog"
+            ref={(node) => {
+              refs.setFloating(node)
+
+              // In a ref callback rather than an effect, because a
+              // `[popover]` is `display: none` until it is shown —
+              // and `FloatingFocusManager` is a *child*, so its
+              // effect runs first and would be focusing into a
+              // hidden element. Refs are set during commit, before
+              // any of that.
+              if (node && !node.matches(":popover-open")) {
+                node.showPopover()
+              }
+            }}
+            style={floatingStyles}
+          >
+            {children}
+          </div>
+        </FloatingFocusManager>
+      ) : null}
+    </>
+  )
+}

package/src/ProgressBar/ProgressBar.mdx

@@ -0,0 +1,48 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ProgressBarStories from "./ProgressBar.stories";
+
+<Meta of={ProgressBarStories} />
+
+# ProgressBar
+
+Five repos hand-roll one and **only rip-deck's has `role="progressbar"`**. The other four
+are a `<div>` with a percentage width: invisible to assistive technology and to
+`getByRole("progressbar")`.
+
+This is the union — rip-deck's ARIA and its indeterminate sweep, plus threshold colours
+nobody has yet.
+
+<Canvas of={ProgressBarStories.Default} />
+
+## Props
+
+<Controls />
+
+## Three corrections to rip-deck's version
+
+1. **The role goes on the track, not the fill.** rip-deck puts `role="progressbar"` on the
+   filled element, so a 4% rip is a progressbar 4px wide as far as AT and a Playwright
+   bounding box are concerned.
+2. **The name comes from a real label**, wired with `aria-labelledby` — visible or
+   `VisuallyHidden` — rather than a hardcoded `aria-label` that cannot be translated.
+3. **`aria-valuenow` is omitted while indeterminate**, which is what says "unknown" rather
+   than "zero".
+
+## Indeterminate means "no measurable progress yet"
+
+Not zero, and not unknown-therefore-full. rip-deck's case is the AACS/BD+ preamble: ~25 s
+of a real Blu-ray emitting nothing, where a full bar reads as a finished rip and an empty
+one as a wedged drive. The sweep animates `inset-inline-start`, so it runs the other way in
+RTL for free, and its reduced-motion fallback hatches the whole track rather than parking a
+bar at one end.
+
+<Canvas of={ProgressBarStories.Indeterminate} />
+
+## Values arrive from a log parser
+
+`-1`, `101`, `NaN`, and `0 of 0` are all normal in this fleet, so clamping is a tested pure
+function (`progressValue.ts`) and `aria-valuenow` is clamped in the value's own units —
+never disagreeing with what is drawn.
+
+<Canvas of={ProgressBarStories.AllStates} />

package/src/ProgressBar/ProgressBar.stories.tsx

@@ -0,0 +1,232 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import { intentArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { ProgressBar } from "./ProgressBar.tsx"
+import type { ProgressThreshold } from "./progressValue.ts"
+
+/** Green when finished, amber past 90% — the rip-deck case. */
+const DISC_THRESHOLDS: ProgressThreshold[] = [
+  { from: 90, intent: "warning" },
+  { from: 100, intent: "success" },
+]
+
+const meta = {
+  title: "Components/ProgressBar",
+  component: ProgressBar,
+  parameters: { layout: "padded" },
+  argTypes: { intent: intentArgType },
+  args: {
+    intent: "accent",
+    isIndeterminate: false,
+    isLabelVisible: false,
+    isValueShown: false,
+    max: 100,
+    size: "md",
+  },
+} satisfies Meta<typeof ProgressBar>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The name comes from a real `aria-labelledby` even though the label
+ * is not printed, and the value sits on the *track* — so an agent's
+ * bounding box is the widget, not the filled 38%.
+ */
+export const Default: Story = {
+  args: { label: "Ripping title 4 of 9", value: 38 },
+}
+
+export const AllVariants: Story = {
+  args: { label: "Ripping", value: 62 },
+  render: (progressProps) => (
+    <StorySection title="Three track sizes, six intents, and the threshold colours nobody in the fleet has yet.">
+      <StoryGrid columns={3}>
+        <StoryCell align="stretch" label="sm">
+          <ProgressBar {...progressProps} size="sm" />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="md">
+          <ProgressBar {...progressProps} size="md" />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="lg">
+          <ProgressBar {...progressProps} size="lg" />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="intent=success">
+          <ProgressBar
+            {...progressProps}
+            intent="success"
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="thresholds · 94% → warning"
+        >
+          <ProgressBar
+            {...progressProps}
+            thresholds={DISC_THRESHOLDS}
+            value={94}
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="thresholds · 100% → success"
+        >
+          <ProgressBar
+            {...progressProps}
+            thresholds={DISC_THRESHOLDS}
+            value={100}
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllStates: Story = {
+  args: { label: "Ripping title 4 of 9" },
+  render: (progressProps) => (
+    <StoryGrid columns={2}>
+      <StoryCell
+        align="stretch"
+        label="0% — empty, not unknown"
+      >
+        <ProgressBar {...progressProps} value={0} />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="mid">
+        <ProgressBar {...progressProps} value={47} />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="complete">
+        <ProgressBar
+          {...progressProps}
+          thresholds={DISC_THRESHOLDS}
+          value={100}
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="indeterminate — no valuenow at all"
+      >
+        <ProgressBar {...progressProps} isIndeterminate />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="label + value visible"
+      >
+        <ProgressBar
+          {...progressProps}
+          isLabelVisible
+          isValueShown
+          value={47}
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="out of range (value=-5, max=0)"
+      >
+        <ProgressBar
+          {...progressProps}
+          max={0}
+          value={-5}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * "Unknown", not "zero" — so no `aria-valuenow` at all.
+ *
+ * rip-deck's AACS/BD+ preamble is ~25 s of a real Blu-ray emitting
+ * nothing: a full bar reads as a finished rip, an empty one as a
+ * wedged drive.
+ */
+export const Indeterminate: Story = {
+  args: {
+    isIndeterminate: true,
+    isLabelVisible: true,
+    label: "Working — no measurable progress yet",
+  },
+}
+
+export const Responsive: Story = {
+  args: {
+    isLabelVisible: true,
+    isValueShown: true,
+    label: "Ripping title 4 of 9 — Blade Runner (1982)",
+    value: 47,
+  },
+  render: (progressProps) => (
+    <ContainerBoard>
+      <ProgressBar {...progressProps} />
+    </ContainerBoard>
+  ),
+}
+
+const SteppedProgressBar = () => {
+  const [percent, setPercent] = useState(0)
+
+  return (
+    <div className="flex flex-col gap-3">
+      <ProgressBar
+        isLabelVisible
+        isValueShown
+        label="Ripping title 4 of 9"
+        thresholds={DISC_THRESHOLDS}
+        value={percent}
+      />
+
+      <StoryRow>
+        <Button
+          onClick={() => {
+            setPercent((current) =>
+              Math.min(100, current + 25),
+            )
+          }}
+          size="sm"
+        >
+          Advance 25%
+        </Button>
+
+        <Button
+          appearance="ghost"
+          onClick={() => {
+            setPercent(0)
+          }}
+          size="sm"
+        >
+          Reset
+        </Button>
+      </StoryRow>
+    </div>
+  )
+}
+
+/**
+ * A progressbar is not focusable and has no keyboard path — the
+ * contract it owes an agent is that `aria-valuenow` tracks what is
+ * drawn. Advance it to 100% and the threshold flips the fill green.
+ */
+export const Interactive: Story = {
+  args: { label: "Ripping title 4 of 9" },
+  render: () => <SteppedProgressBar />,
+}

package/src/ProgressBar/ProgressBar.test.tsx

@@ -0,0 +1,74 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./ProgressBar.stories.tsx"
+
+const { Default, Indeterminate, Interactive } =
+  composeStories(stories)
+
+test("the name is real and the value sits on the track", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const bar = expectAgentDrivable(canvas, {
+    name: "Ripping title 4 of 9",
+    role: "progressbar",
+  })
+
+  // The label is not printed, so the name has to come from a real
+  // `aria-labelledby`. The value is on the *track* so an agent's
+  // bounding box is the widget, not the filled 38%.
+  await expect(bar).toHaveAttribute("aria-valuenow", "38")
+  await expect(bar).toHaveAttribute("aria-valuemax", "100")
+})
+
+test("indeterminate means no value at all, not zero", async () => {
+  const { canvas } = await mountStory(Indeterminate)
+
+  const bar = expectAgentDrivable(canvas, {
+    name: "Working — no measurable progress yet",
+    role: "progressbar",
+  })
+
+  // rip-deck's AACS/BD+ preamble is ~25 s of a real Blu-ray emitting
+  // nothing: a full bar reads as a finished rip, an empty one as a
+  // wedged drive. Absent is the only honest answer.
+  await expect(bar).not.toHaveAttribute("aria-valuenow")
+  await expect(bar).toHaveAttribute("aria-busy", "true")
+})
+
+/**
+ * A progressbar is not focusable and has no keyboard path — the
+ * contract it owes an agent is that `aria-valuenow` tracks what is
+ * drawn.
+ */
+test("aria-valuenow tracks the fill to completion", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const bar = canvas.getByRole("progressbar")
+
+  await expect(bar).toHaveAttribute("aria-valuenow", "0")
+
+  const advance = canvas.getByRole("button", {
+    name: "Advance 25%",
+  })
+
+  await userEvent.click(advance)
+  await userEvent.click(advance)
+
+  await expect(bar).toHaveAttribute("aria-valuenow", "50")
+  await expect(canvas.getByText("50%")).toBeVisible()
+
+  await userEvent.click(advance)
+  await userEvent.click(advance)
+
+  await expect(bar).toHaveAttribute("aria-valuenow", "100")
+
+  // The 100% threshold turns the fill green, which is the
+  // generalisation of rip-deck's `FILL_CLASS` keyed by rip state.
+  await expect(
+    bar.querySelector(".bg-intent-success-solid"),
+  ).toBeInTheDocument()
+})