@charcuterie/ui 3.8.1 → 3.10.0

package/src/Slider/Slider.mdx

@@ -0,0 +1,78 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as SliderStories from "./Slider.stories";
+
+<Meta of={SliderStories} />
+
+# Slider
+
+A single-value range control: what `<input type="range">` is, without the OS painting it.
+
+The fleet had no way to ask for a value along a range, so QueuePilot's Now-playing bar
+could not have a scrubber and the choice was a native range input or a hand-rolled one in
+a single app. `ProgressBar` looks like the answer and is not — it is **output**, it takes
+no input, and `role="progressbar"` tells assistive technology exactly that.
+
+<Canvas of={SliderStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why a `div` and not `<input type="range">`
+
+The same reason [`Select` is deprecated](?path=/docs/components-controls-select--docs).
+
+A range input's thumb and track are UA pseudo-elements — `::-webkit-slider-thumb`,
+`::-moz-range-track` — and they are not one surface: the two engines disagree about which
+of them the filled portion even belongs to, so a token-styled range is two stylesheets that
+drift apart. Windows paints its own regardless.
+
+`role="slider"` on a focusable `div` is the APG's own pattern, gets the same AT support, and
+every pixel of it is ours.
+
+## The role, the tab stop and the pointer target are all the track
+
+Putting them on the thumb is what a hand-rolled slider usually does, because the thumb is
+the part that looks draggable. It gives the widget a 16px box: a press on the bar does
+nothing, and a Playwright bounding box is the handle rather than the control.
+
+The hit area is a row taller than the bar, because a 2px track is not a pointer target.
+
+## Drag does not commit
+
+`onChange` fires on every movement — each arrow key, each pointer sample. `onChangeEnd`
+fires once, on release or key up.
+
+This split exists because the expensive consumer of a slider is almost never the paint. A
+seek scrubber issuing its network call from `onChange` would send one request per pointer
+sample and arrive at the right offset **last**, behind a queue of stale ones.
+
+While a drag is in flight the component paints from its own local value rather than from
+the `value` prop. Without that, a controlled slider whose owner only commits on
+`onChangeEnd` would render the thumb pinned at the old position under the finger — the drag
+would look broken while behaving correctly.
+
+<Canvas of={SliderStories.Interactive} />
+
+## Read-only is not disabled
+
+A read-only slider keeps full contrast and stays focusable, so its value is still readable
+and still reachable by a screen reader. A live stream's position is this: the number
+matters and seeking is not offered.
+
+<Canvas of={SliderStories.AllStates} />
+
+## The arithmetic is a tested pure function
+
+`sliderValue.ts`, in the node project. Steps anchor on `min` rather than on zero — a 7–19
+range stepping by 4 anchored on zero can reach 8, 12 and 16, and neither end of its own
+range is one of them. A snap never escapes the range, a float step does not accumulate
+drift into `aria-valuenow`, and a `NaN` cannot reach the style attribute, where it would
+render `inline-size: NaN%` and paint nothing with no error.
+
+`fromFraction` takes an `isRtl` flag because `getBoundingClientRect()` is physical and knows
+nothing about writing direction — without it a right-to-left slider runs backwards under the
+pointer while its keyboard path stays correct.
+
+<Canvas of={SliderStories.AllVariants} />

package/src/Slider/Slider.stories.tsx

@@ -0,0 +1,256 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import {
+  controlSizeArgType,
+  intentArgType,
+} from "../argTypes.storyHelpers.ts"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Slider } from "./Slider.tsx"
+
+/** mm:ss, the format a scrubber actually wants. */
+const toClock = (seconds: number): string => {
+  const whole = Math.max(0, Math.round(seconds))
+
+  const mins = Math.floor(whole / 60)
+
+  const secs = whole % 60
+
+  return `${mins}:${String(secs).padStart(2, "0")}`
+}
+
+/**
+ * A controlled Slider that owns its own value, which is what every real
+ * call site is. The stories that only paint use the plain component.
+ */
+const LiveSlider = ({
+  initialValue = 40,
+  ...sliderProps
+}: {
+  initialValue?: number
+} & Omit<
+  Parameters<typeof Slider>[0],
+  "onChange" | "value"
+>): ReturnType<typeof Slider> => {
+  const [value, setValue] = useState(initialValue)
+
+  return (
+    <Slider
+      {...sliderProps}
+      onChange={setValue}
+      value={value}
+    />
+  )
+}
+
+const meta = {
+  title: "Components/Controls/Slider",
+  component: Slider,
+  parameters: { layout: "padded" },
+  argTypes: {
+    intent: intentArgType,
+    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: {
+    intent: "accent",
+    isDisabled: false,
+    isLabelVisible: false,
+    isReadOnly: false,
+    isValueShown: false,
+    max: 100,
+    min: 0,
+    size: "md",
+    step: 1,
+  },
+} satisfies Meta<typeof Slider>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { label: "Volume", value: 40 },
+}
+
+export const AllVariants: Story = {
+  args: { label: "Volume" },
+  render: (controlProps) => (
+    <StorySection title="Three heights off the density axis, and the six intents on the fill.">
+      <StoryGrid columns={3}>
+        {(["sm", "md", "lg"] as const).map((size) => (
+          <StoryCell
+            align="stretch"
+            key={size}
+            label={size}
+          >
+            <Slider
+              {...controlProps}
+              label={`Volume at ${size}`}
+              size={size}
+              value={55}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+
+      <StoryGrid columns={3}>
+        {(
+          [
+            "accent",
+            "success",
+            "warning",
+            "danger",
+            "info",
+            "neutral",
+          ] as const
+        ).map((intent) => (
+          <StoryCell
+            align="stretch"
+            key={intent}
+            label={intent}
+          >
+            <Slider
+              {...controlProps}
+              intent={intent}
+              label={`Volume, ${intent}`}
+              value={55}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * `isReadOnly` is not `isDisabled`. A read-only slider keeps full
+ * contrast and stays focusable, so its value is still readable and
+ * still reachable by a screen reader — a live stream's position, where
+ * the number matters and seeking is not offered.
+ */
+export const AllStates: Story = {
+  args: { label: "Volume" },
+  render: (controlProps) => (
+    <StorySection title="What varies is the value, and whether it can be changed.">
+      <StoryGrid columns={2}>
+        <StoryCell align="stretch" label="at the minimum">
+          <Slider
+            {...controlProps}
+            label="Empty"
+            value={0}
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="at the maximum">
+          <Slider
+            {...controlProps}
+            label="Full"
+            value={100}
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="disabled">
+          <Slider
+            {...controlProps}
+            isDisabled
+            label="Disabled"
+            value={35}
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="read-only">
+          <Slider
+            {...controlProps}
+            isReadOnly
+            label="Read-only"
+            value={35}
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="label and value shown"
+        >
+          <Slider
+            {...controlProps}
+            isLabelVisible
+            isValueShown
+            label="Position"
+            max={2_700}
+            value={1_274}
+            valueFormat={toClock}
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="a coarse step">
+          <Slider
+            {...controlProps}
+            isValueShown
+            label="Rating"
+            max={5}
+            step={1}
+            value={3}
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The track is the widget, so it fills whatever box it is given and the
+ * thumb stays on the value at every width. Nothing here is a media
+ * query — a slider in a 320px rail and one in a 960px panel are the
+ * same component.
+ */
+export const Responsive: Story = {
+  args: { label: "Volume" },
+  render: (controlProps) => (
+    <ContainerBoard>
+      <Slider
+        {...controlProps}
+        isLabelVisible
+        isValueShown
+        label="Position"
+        max={2_700}
+        value={1_274}
+        valueFormat={toClock}
+      />
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * The complete keyboard path. Tab reaches the track, then:
+ *
+ * - **Arrow Left / Down** and **Arrow Right / Up** move one `step`
+ * - **Page Down / Page Up** move one `largeStep`, ten steps by default
+ * - **Home** and **End** go to `min` and `max`
+ *
+ * A pointer press anywhere on the row jumps the thumb there and starts
+ * a drag, and the drag keeps reporting after the pointer leaves the bar
+ * vertically — the track takes pointer capture, so a thumb dragged off
+ * the bar does not stop dead at the boundary.
+ */
+export const Interactive: Story = {
+  args: { label: "Volume" },
+  render: (controlProps) => (
+    <StorySection title="Drive it with the keyboard, or press anywhere on the row.">
+      <LiveSlider
+        {...controlProps}
+        initialValue={40}
+        isLabelVisible
+        isValueShown
+        label="Volume"
+      />
+    </StorySection>
+  ),
+}

package/src/Slider/Slider.test.tsx

@@ -0,0 +1,241 @@
+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 "./Slider.stories.tsx"
+
+const { AllStates, Default, Interactive } =
+  composeStories(stories)
+
+test("it is a slider a screen reader can name and read", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  const slider = expectAgentDrivable(canvas, {
+    name: "Volume",
+    role: "slider",
+  })
+
+  await expect(slider).toHaveAttribute(
+    "aria-valuenow",
+    "40",
+  )
+
+  await expect(slider).toHaveAttribute("aria-valuemin", "0")
+
+  await expect(slider).toHaveAttribute(
+    "aria-valuemax",
+    "100",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the arrow keys move it one step and Home/End reach both ends", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const slider = expectAgentDrivable(canvas, {
+    name: "Volume",
+    role: "slider",
+  })
+
+  await userEvent.click(slider)
+
+  // The click landed somewhere on the track, so drive from a known
+  // point rather than from wherever the pointer put it.
+  await userEvent.keyboard("{Home}")
+
+  await waitFor(() => {
+    expect(slider).toHaveAttribute("aria-valuenow", "0")
+  })
+
+  await userEvent.keyboard("{ArrowRight}")
+
+  await waitFor(() => {
+    expect(slider).toHaveAttribute("aria-valuenow", "1")
+  })
+
+  await userEvent.keyboard("{ArrowUp}")
+
+  await waitFor(() => {
+    expect(slider).toHaveAttribute("aria-valuenow", "2")
+  })
+
+  await userEvent.keyboard("{ArrowLeft}")
+
+  await waitFor(() => {
+    expect(slider).toHaveAttribute("aria-valuenow", "1")
+  })
+
+  await userEvent.keyboard("{End}")
+
+  await waitFor(() => {
+    expect(slider).toHaveAttribute("aria-valuenow", "100")
+  })
+})
+
+/**
+ * The default `largeStep` is a tenth of the range, so PageDown from the
+ * top of a 0–100 slider lands on 90. The point of asserting the default
+ * rather than a passed-in one is that a caller should not have to know
+ * its own range to get a sensible page key.
+ */
+test("the page keys move it ten steps by default", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const slider = expectAgentDrivable(canvas, {
+    name: "Volume",
+    role: "slider",
+  })
+
+  await userEvent.click(slider)
+
+  await userEvent.keyboard("{End}")
+
+  await userEvent.keyboard("{PageDown}")
+
+  await waitFor(() => {
+    expect(slider).toHaveAttribute("aria-valuenow", "90")
+  })
+
+  await userEvent.keyboard("{PageUp}")
+
+  await waitFor(() => {
+    expect(slider).toHaveAttribute("aria-valuenow", "100")
+  })
+})
+
+test("it never leaves its own range", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const slider = expectAgentDrivable(canvas, {
+    name: "Volume",
+    role: "slider",
+  })
+
+  await userEvent.click(slider)
+
+  await userEvent.keyboard("{Home}")
+
+  // Three presses past the floor. A slider that goes to -3 renders a
+  // thumb off the start of its track and reports a value AT cannot
+  // place on the range it just announced.
+  await userEvent.keyboard(
+    "{ArrowLeft}{ArrowLeft}{ArrowLeft}",
+  )
+
+  await expect(slider).toHaveAttribute("aria-valuenow", "0")
+
+  await userEvent.keyboard("{End}")
+
+  await userEvent.keyboard(
+    "{ArrowRight}{ArrowRight}{ArrowRight}",
+  )
+
+  await expect(slider).toHaveAttribute(
+    "aria-valuenow",
+    "100",
+  )
+})
+
+test("a disabled slider is out of the tab order and does not move", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const disabled = expectAgentDrivable(canvas, {
+    name: "Disabled",
+    role: "slider",
+  })
+
+  await expect(disabled).toHaveAttribute(
+    "aria-disabled",
+    "true",
+  )
+
+  await expect(disabled).toHaveAttribute("tabindex", "-1")
+
+  // Not `userEvent.click` — it refuses, because the disabled class sets
+  // `pointer-events: none` and the helper asserts that before acting.
+  // Its refusal IS the pointer half of this test, so the keyboard half
+  // focuses directly rather than working around the guarantee.
+  await expect(
+    getComputedStyle(disabled).pointerEvents,
+  ).toBe("none")
+
+  disabled.focus()
+
+  await userEvent.keyboard("{ArrowRight}")
+
+  await expect(disabled).toHaveAttribute(
+    "aria-valuenow",
+    "35",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * Read-only is the state that is easy to collapse into `disabled`, and
+ * they are different answers: this one is still focusable and still
+ * full contrast, because its value is worth reading even though it
+ * cannot be changed.
+ */
+test("a read-only slider is announced, focusable, and does not move", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const readOnly = expectAgentDrivable(canvas, {
+    name: "Read-only",
+    role: "slider",
+  })
+
+  await expect(readOnly).toHaveAttribute(
+    "aria-readonly",
+    "true",
+  )
+
+  await expect(readOnly).toHaveAttribute("tabindex", "0")
+
+  await expect(readOnly).not.toHaveAttribute(
+    "aria-disabled",
+  )
+
+  await userEvent.click(readOnly)
+
+  await userEvent.keyboard("{ArrowRight}")
+
+  await expect(readOnly).toHaveAttribute(
+    "aria-valuenow",
+    "35",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * `aria-valuetext` is the whole reason `valueFormat` exists. Without it
+ * a scrubber announces "1274" — a number of seconds nobody has — and
+ * `aria-valuenow` alone is what AT would read.
+ */
+test("valueFormat writes aria-valuetext and the shown value", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const position = expectAgentDrivable(canvas, {
+    name: "Position",
+    role: "slider",
+  })
+
+  await expect(position).toHaveAttribute(
+    "aria-valuetext",
+    "21:14",
+  )
+
+  // The raw number is still there for anything that computes with it.
+  await expect(position).toHaveAttribute(
+    "aria-valuenow",
+    "1274",
+  )
+})