@charcuterie/ui 0.1.0

package/src/ProgressBar/ProgressBar.tsx

@@ -0,0 +1,172 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { IntentName } from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { INTENT_SOLID_FILL_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+import type { ProgressThreshold } from "./progressValue.ts"
+import {
+  getProgressIntent,
+  toProgressPercent,
+  toProgressValue,
+} from "./progressValue.ts"
+
+export type ProgressBarSize = "lg" | "md" | "sm"
+
+export type ProgressBarProps = Omit<
+  ComponentPropsWithRef<"div">,
+  "children"
+> & {
+  intent?: IntentName
+  /**
+   * Indeterminate means "working, no measurable progress yet" — not
+   * zero and not unknown-therefore-full. rip-deck's is the
+   * AACS/BD+ preamble: ~25 s of a real Blu-ray emitting nothing, in
+   * which a full bar reads as a finished rip and an empty one as a
+   * wedged drive.
+   */
+  isIndeterminate?: boolean
+  isLabelVisible?: boolean
+  isValueShown?: boolean
+  /** Required. A progressbar with no name is a grey rectangle. */
+  label: string
+  max?: number
+  size?: ProgressBarSize
+  thresholds?: readonly ProgressThreshold[]
+  value?: number
+}
+
+const TRACK_SIZE_CLASS: Record<ProgressBarSize, string> = {
+  sm: "h-1",
+  md: "h-2",
+  lg: "h-3",
+}
+
+/**
+ * The union of what the fleet has: rip-deck's ARIA and its
+ * indeterminate sweep, plus threshold colours nobody has yet.
+ *
+ * Five repos hand-roll a progress bar 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")`.
+ *
+ * Three corrections to rip-deck's version, which is otherwise the
+ * best in the fleet:
+ *
+ *  - **The role goes on the track, not the fill.** rip-deck puts
+ *    `role="progressbar"` on the inner filled element, so the
+ *    widget's box is the *filled portion* — a 4% rip is a
+ *    progressbar 4px wide as far as AT and a Playwright bounding
+ *    box are concerned.
+ *  - **The name comes from a real label**, wired with
+ *    `aria-labelledby` when it is visible and `VisuallyHidden` when
+ *    it is not, rather than a hardcoded `aria-label` string that
+ *    cannot be translated or reused.
+ *  - **`aria-valuenow` is omitted while indeterminate**, which is
+ *    what tells AT "unknown" rather than "zero". rip-deck gets this
+ *    right by rendering a separate element; stating it on one
+ *    element is the same answer without the duplication.
+ */
+export const ProgressBar = ({
+  className,
+  intent = "accent",
+  isIndeterminate = false,
+  isLabelVisible = false,
+  isValueShown = false,
+  label,
+  max = 100,
+  size = "md",
+  thresholds,
+  value = 0,
+  ...divProps
+}: ProgressBarProps): ReactNode => {
+  const labelId = useUniqueId()
+
+  const percent = toProgressPercent(value, max)
+
+  const clampedValue = toProgressValue(value, max)
+
+  const fillIntent = getProgressIntent(
+    percent,
+    intent,
+    thresholds,
+  )
+
+  return (
+    <div
+      {...divProps}
+      className={toClassName(
+        "flex flex-col gap-1",
+        className,
+      )}
+    >
+      {isLabelVisible || isValueShown ? (
+        <div className="flex items-baseline justify-between gap-2 text-sm">
+          {isLabelVisible ? (
+            <span
+              className="text-content-secondary"
+              id={labelId}
+            >
+              {label}
+            </span>
+          ) : (
+            <VisuallyHidden id={labelId}>
+              {label}
+            </VisuallyHidden>
+          )}
+
+          {isValueShown && !isIndeterminate ? (
+            <span className="text-content-muted tabular-nums">
+              {percent}%
+            </span>
+          ) : null}
+        </div>
+      ) : (
+        <VisuallyHidden id={labelId}>
+          {label}
+        </VisuallyHidden>
+      )}
+
+      <div
+        aria-busy={isIndeterminate || undefined}
+        aria-labelledby={labelId}
+        aria-valuemax={max}
+        aria-valuemin={0}
+        aria-valuenow={
+          isIndeterminate ? undefined : clampedValue
+        }
+        className={toClassName(
+          "relative w-full overflow-hidden rounded-full bg-surface-sunken",
+          TRACK_SIZE_CLASS[size],
+        )}
+        role="progressbar"
+      >
+        {isIndeterminate ? (
+          <span
+            className={toClassName(
+              // 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 at one end.
+              "charcuterie-sweep absolute inset-y-0 w-2/5 rounded-full",
+              INTENT_SOLID_FILL_CLASS[fillIntent],
+            )}
+          />
+        ) : (
+          <span
+            className={toClassName(
+              "block h-full rounded-full transition-[inline-size] duration-(--duration-normal) ease-standard",
+              INTENT_SOLID_FILL_CLASS[fillIntent],
+            )}
+            style={{ inlineSize: `${percent}%` }}
+          />
+        )}
+      </div>
+    </div>
+  )
+}

package/src/ProgressBar/progressValue.test.ts

@@ -0,0 +1,101 @@
+/**
+ * The arithmetic a progress bar gets handed by a log parser.
+ *
+ * None of these inputs is hypothetical: rip-deck's `fillPercent`
+ * comes out of a ripper's stdout, and `-1`, `101`, `NaN`, and
+ * `0 of 0` all arrive in normal operation. Today each of them
+ * renders as a bar that overflows its track, vanishes, or reads as
+ * finished.
+ */
+
+import { expect, test } from "vitest"
+
+import type { ProgressThreshold } from "./progressValue.ts"
+import {
+  getProgressIntent,
+  toProgressPercent,
+  toProgressValue,
+} from "./progressValue.ts"
+
+test("a normal value becomes a rounded percentage", () => {
+  expect(toProgressPercent(38, 100)).toBe(38)
+
+  expect(toProgressPercent(4, 9)).toBe(44)
+
+  expect(toProgressPercent(1, 3)).toBe(33)
+})
+
+test("out-of-range values clamp rather than overflow", () => {
+  expect(toProgressPercent(-5, 100)).toBe(0)
+
+  expect(toProgressPercent(150, 100)).toBe(100)
+})
+
+test("an empty queue is 0%, not NaN%", () => {
+  // `0 of 0 files done` — every empty queue's first render.
+  expect(toProgressPercent(0, 0)).toBe(0)
+
+  expect(toProgressPercent(1, 0)).toBe(0)
+
+  expect(toProgressPercent(Number.NaN, 100)).toBe(0)
+
+  expect(
+    toProgressPercent(Number.POSITIVE_INFINITY, 100),
+  ).toBe(0)
+})
+
+test("aria-valuenow never leaves its own min/max", () => {
+  // A `valuenow` outside `valuemin`/`valuemax` is read as a nonsense
+  // percentage by some screen readers and dropped by others, and
+  // either way it disagrees with the bar on screen.
+  expect(toProgressValue(38, 100)).toBe(38)
+
+  expect(toProgressValue(-5, 100)).toBe(0)
+
+  expect(toProgressValue(150, 100)).toBe(100)
+
+  expect(toProgressValue(5, 0)).toBe(0)
+
+  expect(toProgressValue(Number.NaN, 100)).toBe(0)
+})
+
+const THRESHOLDS: ProgressThreshold[] = [
+  { from: 100, intent: "success" },
+  { from: 90, intent: "warning" },
+]
+
+test("with no thresholds the component's intent wins", () => {
+  expect(getProgressIntent(50, "accent")).toBe("accent")
+
+  expect(getProgressIntent(50, "accent", [])).toBe("accent")
+})
+
+test("the highest matching threshold wins, whatever the array order", () => {
+  // Order-independence is the point: a caller appending to a config
+  // array should not have to know it was meant to be sorted.
+  expect(getProgressIntent(94, "accent", THRESHOLDS)).toBe(
+    "warning",
+  )
+
+  expect(
+    getProgressIntent(
+      94,
+      "accent",
+      [...THRESHOLDS].reverse(),
+    ),
+  ).toBe("warning")
+
+  expect(getProgressIntent(100, "accent", THRESHOLDS)).toBe(
+    "success",
+  )
+
+  expect(getProgressIntent(89, "accent", THRESHOLDS)).toBe(
+    "accent",
+  )
+})
+
+test("a threshold at the boundary is inclusive", () => {
+  expect(getProgressIntent(90, "accent", THRESHOLDS)).toBe(
+    "warning",
+  )
+})

package/src/ProgressBar/progressValue.ts

@@ -0,0 +1,87 @@
+import type { IntentName } from "@charcuterie/tokens"
+
+/**
+ * A threshold is "from this percentage upward, use this intent".
+ * Order does not matter — the highest matching entry wins — because
+ * a caller sorting a config array by hand is a bug waiting for the
+ * day someone appends to it.
+ */
+export type ProgressThreshold = {
+  from: number
+  intent: IntentName
+}
+
+/**
+ * Clamped, rounded, and NaN-proof, in a file a Node test can reach
+ * without a browser.
+ *
+ * All three cases are real. rip-deck's `fillPercent` comes from a
+ * ripper's stdout, and a progress value that arrives as `-1`,
+ * `101`, or `NaN` from a log parse currently renders as a bar that
+ * overflows its track or vanishes. `max: 0` is the one that looks
+ * hypothetical and is not: it is "0 of 0 files done", which every
+ * empty queue produces on its first render.
+ */
+export const toProgressPercent = (
+  value: number,
+  max: number,
+) => {
+  if (!Number.isFinite(value) || !Number.isFinite(max)) {
+    return 0
+  }
+
+  if (max <= 0) {
+    return 0
+  }
+
+  return Math.min(
+    100,
+    Math.max(0, Math.round((value / max) * 100)),
+  )
+}
+
+/**
+ * The same clamp in the value's own units, for `aria-valuenow`.
+ *
+ * Reporting the raw prop there would hand assistive technology a
+ * `valuenow` outside its own `valuemin`/`valuemax` — which some
+ * screen readers render as a nonsense percentage and others drop
+ * entirely — while the bar on screen showed the clamped one. The
+ * two must not disagree.
+ */
+export const toProgressValue = (
+  value: number,
+  max: number,
+) => {
+  if (!Number.isFinite(value) || !Number.isFinite(max)) {
+    return 0
+  }
+
+  return Math.min(Math.max(0, max), Math.max(0, value))
+}
+
+/**
+ * The threshold colour, or the component's own intent when no
+ * threshold applies.
+ *
+ * This is the piece rip-deck hardcodes as `FILL_CLASS` keyed by a
+ * rip state, and mux-magic does not have at all. Generalising it to
+ * "percentage → intent" covers both the "green when done" case and
+ * the "amber past 80% of the disk" case with one mechanism.
+ */
+export const getProgressIntent = (
+  percent: number,
+  intent: IntentName,
+  thresholds?: readonly ProgressThreshold[],
+): IntentName => {
+  if (!thresholds || thresholds.length === 0) {
+    return intent
+  }
+
+  const matched = thresholds
+    .filter((threshold) => percent >= threshold.from)
+    .sort((first, second) => second.from - first.from)
+    .at(0)
+
+  return matched?.intent ?? intent
+}

package/src/SegmentedControl/SegmentedControl.mdx

@@ -0,0 +1,71 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as SegmentedControlStories from "./SegmentedControl.stories";
+
+<Meta of={SegmentedControlStories} />
+
+# SegmentedControl
+
+One choice out of a handful, all of them on screen at once.
+
+This is `Tabs`' composition — `SinglePicker` + `RovingFocus` — **with the panels taken
+away**, and it is here because taking the panels away used to be impossible. Under M4's
+model a tab bar's selection *was* a group of visibilities, so a control that chooses
+something without revealing anything had nothing to reuse and hand-rolled its own state.
+rip-deck's `ColumnPicker` is that hand-roll
+([decision](../../../docs/decisions/2026-07-30-tab-selection-is-a-single-picker.md)).
+
+<Canvas of={SegmentedControlStories.Default} />
+
+## Props
+
+<Controls />
+
+## `radiogroup`, not a row of pressed buttons
+
+rip-deck's version is five `<button aria-pressed>` inside a `<fieldset>` — the **toolbar of
+independent toggles** pattern. Nothing in it says the five are mutually exclusive, so a
+screen reader announces *"auto, pressed"* with no "1 of 5" and no clue that pressing
+another one un-presses this one.
+
+A single choice from a named set is a radio group, and ARIA has a pattern for it: a
+`radiogroup` with an accessible name, `role="radio"` children carrying `aria-checked`, and
+a roving tabindex so Tab enters and leaves the group once.
+
+<Canvas of={SegmentedControlStories.AllVariants} />
+
+## Selection follows focus, and here that is correct
+
+`Tabs` has two activation modes because a tab panel can cost a network request. A radio
+group has one: APG says the arrow keys both move focus **and** check, and there is nothing
+behind an option here to be expensive. So there is no `activation` prop — a `manual`
+segmented control would be a control the arrow keys appear to do nothing in.
+
+The two kinds are still separate underneath, which is what makes Space trivial rather than
+a special case: it checks whatever focus is on, whether or not focus moved there by arrow.
+`select` is idempotent, so it is one command and not a second code path.
+
+<Canvas of={SegmentedControlStories.AllStates} />
+
+## Registration is membership
+
+A disabled option is out of the **focus** group and still one of the **options** — it can
+even be the one a consumer names as the initial `selectedValue`, which is what a saved
+preference pointing at a layout the window no longer fits looks like.
+
+`SegmentedOption` is its own file for the same reason `TabTrigger` is: both registrations
+are effects, and an effect cannot run in a loop.
+
+<Canvas of={SegmentedControlStories.Responsive} />
+
+## `selectedValue` is initial, not controlled
+
+Read once, on the first render. There is no controlled mode and no prop-sync effect, which
+is [the M2 decision](../../../docs/decisions/2026-07-29-logic-hooks-are-uncontrolled.md).
+
+The first paint reads `pendingValue` as well as `selectedValue`, and that fallback is
+load-bearing: members register from an effect, so `selectedValue` is still `null` when the
+group first paints. Reading only the former renders a group with nothing checked that
+corrects itself a frame later — a flash on a desktop, a visible blank on a kiosk Pi.
+
+<Canvas of={SegmentedControlStories.Interactive} />

package/src/SegmentedControl/SegmentedControl.stories.tsx

@@ -0,0 +1,150 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import type { SegmentedItem } from "./SegmentedControl.tsx"
+import { SegmentedControl } from "./SegmentedControl.tsx"
+
+/**
+ * rip-deck's column picker, which is where this component came
+ * from. `auto` sits first and always, because a control that only
+ * offers numbers once a number has been picked is a one-way door.
+ */
+const COLUMN_ITEMS: SegmentedItem[] = [
+  { label: "auto · 3", value: "auto" },
+  { label: "1", value: "1" },
+  { label: "2", value: "2" },
+  { label: "3", value: "3" },
+  { label: "4", value: "4" },
+]
+
+const meta = {
+  title: "Components/SegmentedControl",
+  component: SegmentedControl,
+  parameters: { layout: "padded" },
+  argTypes: { size: controlSizeArgType },
+  // The component's own defaults, restated — Storybook does not seed
+  // `args` from docgen, so an unstated default shows in the props
+  // table with nothing selected in its control.
+  args: { size: "md" },
+} satisfies Meta<typeof SegmentedControl>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { items: COLUMN_ITEMS, label: "Columns" },
+}
+
+export const AllVariants: Story = {
+  args: { items: COLUMN_ITEMS, label: "Columns" },
+  render: (controlProps) => (
+    <StorySection title="Three control heights, all reading the density axis rather than hardcoding a length.">
+      <StoryGrid columns={3}>
+        {(["sm", "md", "lg"] as const).map((size) => (
+          <StoryCell key={size} label={size}>
+            <SegmentedControl
+              {...controlProps}
+              label={`Columns at ${size}`}
+              size={size}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+const STATE_ITEMS: SegmentedItem[] = [
+  { label: "auto · 3", value: "auto" },
+  { label: "1", value: "1" },
+  { isDisabled: true, label: "2", value: "2" },
+  { label: "3", value: "3" },
+]
+
+/**
+ * A disabled option is out of the *focus* group and still one of the
+ * *options* — it can even be the one a consumer names as the initial
+ * `selectedValue`, which is what a saved preference pointing at a
+ * layout the window no longer fits looks like.
+ */
+export const AllStates: Story = {
+  args: { items: STATE_ITEMS, label: "Columns" },
+  render: (controlProps) => (
+    <StorySection title="What varies is which option is checked and which are reachable.">
+      <StoryGrid columns={2}>
+        <StoryCell label="first option checked">
+          <SegmentedControl
+            {...controlProps}
+            label="Columns starting on auto"
+          />
+        </StoryCell>
+
+        <StoryCell label="starts on the third option">
+          <SegmentedControl
+            {...controlProps}
+            label="Columns starting on 3"
+            selectedValue="3"
+          />
+        </StoryCell>
+
+        <StoryCell label="a disabled option">
+          <SegmentedControl
+            {...controlProps}
+            label="Columns with 2 unavailable"
+          />
+        </StoryCell>
+
+        <StoryCell label="two options">
+          <SegmentedControl
+            {...controlProps}
+            items={[
+              { label: "Grid", value: "grid" },
+              { label: "List", value: "list" },
+            ]}
+            label="Layout"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * It is `inline-flex`, so it takes the width of its options and no
+ * more — a segmented control that stretched to its container would
+ * put four numbers across a whole dashboard header.
+ *
+ * `ContainerBoard` is a width harness here rather than a
+ * container-query claim: `SegmentedControl` declares no container,
+ * because nothing about it needs to *know* its width.
+ */
+export const Responsive: Story = {
+  args: { items: COLUMN_ITEMS, label: "Columns" },
+  render: (controlProps) => (
+    <ContainerBoard>
+      {(width) => (
+        <SegmentedControl
+          {...controlProps}
+          label={`Columns at ${width}`}
+        />
+      )}
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * The complete keyboard path. Tab enters the group **once** — the
+ * roving-tabindex rule — then the arrow keys move and check
+ * together, which is what a radio group does and what `Tabs`'
+ * `manual` mode deliberately does not.
+ */
+export const Interactive: Story = {
+  args: { items: COLUMN_ITEMS, label: "Columns" },
+}