@dowel-ui/react 0.1.0

package/src/components/slider/meta.ts

@@ -0,0 +1,19 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "slider",
+  title: "Slider",
+  description: "Selects a value, or a range, from a continuous span.",
+  category: "form",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["slider.tsx"],
+  a11y:
+    'Each thumb is a role="slider" with arrow keys, Home/End and Page Up/Down. The name is ' +
+    "forwarded onto the thumbs, since the root has no role — a range slider should name each " +
+    "thumb separately with thumbLabels. A development-only warning fires if a thumb would be " +
+    "unnamed. Pass aria-valuetext when the raw number is not meaningful on its own " +
+    "(a price, a duration). Show the current value on screen too — a slider is imprecise, so " +
+    "pair it with a numeric input when exactness matters.",
+});

package/src/components/slider/slider.stories.tsx

@@ -0,0 +1,87 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import { Label } from "@/components/label";
+
+import { Slider } from "./slider";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <div className="w-72">
+    <Story />
+  </div>
+);
+
+const meta = {
+  title: "Forms/Slider",
+  component: Slider,
+  args: { defaultValue: [40], min: 0, max: 100, step: 1, "aria-label": "Volume" },
+  argTypes: {
+    step: { control: { type: "number", min: 1, max: 25 } },
+    disabled: { control: "boolean" },
+  },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof Slider>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** A slider is imprecise; showing the value makes it usable. */
+export const WithValue: Story = {
+  parameters: { controls: { disable: true } },
+  render: function WithValue() {
+    const [value, setValue] = useState([40]);
+    return (
+      <div className="grid gap-3">
+        <div className="flex items-center justify-between">
+          <Label htmlFor="quality">Quality</Label>
+          <span className="text-sm text-muted-foreground tabular-nums">{value[0]}%</span>
+        </div>
+        <Slider id="quality" aria-label="Quality" value={value} onValueChange={setValue} />
+      </div>
+    );
+  },
+};
+
+/** Each thumb is its own slider control, so each one gets its own name. */
+export const Range: Story = {
+  parameters: { controls: { disable: true } },
+  render: function Range() {
+    const [range, setRange] = useState([20, 80]);
+    return (
+      <div className="grid gap-3">
+        <div className="flex items-center justify-between">
+          <Label>Price range</Label>
+          <span className="text-sm text-muted-foreground tabular-nums">
+            ${range[0]} – ${range[1]}
+          </span>
+        </div>
+        <Slider
+          value={range}
+          onValueChange={setRange}
+          thumbLabels={["Minimum price", "Maximum price"]}
+          thumbValueTexts={[`$${String(range[0])}`, `$${String(range[1])}`]}
+        />
+      </div>
+    );
+  },
+};
+
+export const Steps: Story = {
+  args: { defaultValue: [50], step: 10 },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+export const Vertical: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex h-44 justify-center">
+      <Slider orientation="vertical" defaultValue={[60]} aria-label="Volume" />
+    </div>
+  ),
+};

package/src/components/slider/slider.test.tsx

@@ -0,0 +1,148 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Slider } from "./slider";
+
+describe("Slider", () => {
+  it("renders a single thumb by default", () => {
+    render(<Slider aria-label="Volume" />);
+    expect(screen.getAllByRole("slider")).toHaveLength(1);
+  });
+
+  it("renders one thumb per value", () => {
+    render(<Slider aria-label="Price range" defaultValue={[20, 80]} />);
+    expect(screen.getAllByRole("slider")).toHaveLength(2);
+  });
+
+  it("exposes its value and bounds", () => {
+    render(<Slider aria-label="Volume" defaultValue={[40]} min={0} max={100} />);
+
+    const thumb = screen.getByRole("slider");
+    expect(thumb).toHaveAttribute("aria-valuenow", "40");
+    expect(thumb).toHaveAttribute("aria-valuemin", "0");
+    expect(thumb).toHaveAttribute("aria-valuemax", "100");
+  });
+
+  it("increments with the arrow keys", async () => {
+    const user = userEvent.setup();
+    render(<Slider aria-label="Volume" defaultValue={[40]} />);
+
+    await user.tab();
+    const thumb = screen.getByRole("slider");
+    expect(thumb).toHaveFocus();
+
+    await user.keyboard("{ArrowRight}");
+    expect(thumb).toHaveAttribute("aria-valuenow", "41");
+
+    await user.keyboard("{ArrowLeft}");
+    expect(thumb).toHaveAttribute("aria-valuenow", "40");
+  });
+
+  it("jumps to the bounds with Home and End", async () => {
+    const user = userEvent.setup();
+    render(<Slider aria-label="Volume" defaultValue={[40]} min={10} max={90} />);
+
+    await user.tab();
+    await user.keyboard("{Home}");
+    expect(screen.getByRole("slider")).toHaveAttribute("aria-valuenow", "10");
+
+    await user.keyboard("{End}");
+    expect(screen.getByRole("slider")).toHaveAttribute("aria-valuenow", "90");
+  });
+
+  it("honours the step", async () => {
+    const user = userEvent.setup();
+    render(<Slider aria-label="Volume" defaultValue={[40]} step={10} />);
+
+    await user.tab();
+    await user.keyboard("{ArrowRight}");
+    expect(screen.getByRole("slider")).toHaveAttribute("aria-valuenow", "50");
+  });
+
+  it("reports changes", async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    render(<Slider aria-label="Volume" defaultValue={[40]} onValueChange={onValueChange} />);
+
+    await user.tab();
+    await user.keyboard("{ArrowRight}");
+    expect(onValueChange).toHaveBeenCalledWith([41]);
+  });
+
+  it("works controlled", async () => {
+    const user = userEvent.setup();
+
+    function Controlled() {
+      const [value, setValue] = useState([30]);
+      return <Slider aria-label="Volume" value={value} onValueChange={setValue} />;
+    }
+
+    render(<Controlled />);
+    await user.tab();
+    await user.keyboard("{ArrowRight}");
+    expect(screen.getByRole("slider")).toHaveAttribute("aria-valuenow", "31");
+  });
+
+  it("does not respond while disabled", async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    render(
+      <Slider aria-label="Volume" defaultValue={[40]} disabled onValueChange={onValueChange} />,
+    );
+
+    await user.tab();
+    await user.keyboard("{ArrowRight}");
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  it("supports vertical orientation", () => {
+    render(<Slider aria-label="Volume" orientation="vertical" data-testid="slider" />);
+    expect(screen.getByTestId("slider")).toHaveAttribute("data-orientation", "vertical");
+  });
+
+  it("forwards aria-valuetext onto the thumb", () => {
+    render(
+      <Slider aria-label="Duration" defaultValue={[90]} aria-valuetext="1 minute 30 seconds" />,
+    );
+    expect(screen.getByRole("slider")).toHaveAttribute("aria-valuetext", "1 minute 30 seconds");
+  });
+
+  it("names each thumb of a range slider separately", () => {
+    render(
+      <Slider
+        defaultValue={[20, 80]}
+        thumbLabels={["Minimum price", "Maximum price"]}
+        thumbValueTexts={["$20", "$80"]}
+      />,
+    );
+
+    const min = screen.getByRole("slider", { name: "Minimum price" });
+    const max = screen.getByRole("slider", { name: "Maximum price" });
+    expect(min).toHaveAttribute("aria-valuetext", "$20");
+    expect(max).toHaveAttribute("aria-valuetext", "$80");
+  });
+
+  it("warns in development when a thumb would be unnamed", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    render(<Slider defaultValue={[40]} />);
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("no accessible name"));
+    warn.mockRestore();
+  });
+
+  it("does not warn when every thumb is named", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    render(<Slider defaultValue={[20, 80]} thumbLabels={["Minimum", "Maximum"]} />);
+
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Slider aria-label="Volume" defaultValue={[40]} />);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/slider/slider.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import { Slider as SliderPrimitive } from "radix-ui";
+import { useEffect, useMemo, type ComponentPropsWithRef } from "react";
+
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/**
+ * Selects a value, or a range, from a continuous span.
+ *
+ * Renders one thumb per value, so a range slider is just two values. Sliders
+ * are imprecise by nature: if the exact number matters, pair it with a numeric
+ * input rather than asking people to land on a pixel.
+ */
+export interface SliderProps extends ComponentPropsWithRef<typeof SliderPrimitive.Root> {
+  /**
+   * Accessible name per thumb, in order.
+   *
+   * A range slider is two independent `role="slider"` controls, and naming both
+   * of them "Price" tells a screen reader user nothing about which one they are
+   * on. Give them distinct names — "Minimum price", "Maximum price".
+   */
+  thumbLabels?: string[];
+  /**
+   * Spoken value per thumb, in order, for values whose raw number is not
+   * meaningful on its own — a price, a duration, a rating.
+   */
+  thumbValueTexts?: string[];
+}
+
+export function Slider({
+  className,
+  value,
+  defaultValue,
+  min = 0,
+  max = 100,
+  thumbLabels,
+  thumbValueTexts,
+  // Every naming and value-describing attribute has to move to the thumbs for
+  // the same reason: the thumb is the element with role="slider".
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-valuetext": ariaValueText,
+  ...props
+}: SliderProps) {
+  // One thumb per value. Falling back to a single thumb keeps the bare
+  // <Slider /> case working without forcing a defaultValue.
+  const thumbCount = useMemo(
+    () => (value ?? defaultValue ?? [min]).length,
+    [value, defaultValue, min],
+  );
+
+  // The name has to live on the thumb, because the thumb is the element with
+  // role="slider". Left on the root it names an element with no role, and the
+  // control a screen reader actually lands on is announced unnamed.
+  useMissingLabelWarning(thumbCount, thumbLabels, ariaLabel, ariaLabelledBy);
+
+  return (
+    <SliderPrimitive.Root
+      data-slot="slider"
+      value={value}
+      defaultValue={defaultValue}
+      min={min}
+      max={max}
+      className={cn(
+        "relative flex w-full touch-none items-center select-none",
+        "data-[orientation=vertical]:h-44 data-[orientation=vertical]:w-auto data-[orientation=vertical]:flex-col",
+        "data-[disabled]:opacity-55",
+        className,
+      )}
+      {...props}
+    >
+      <SliderPrimitive.Track
+        data-slot="slider-track"
+        className={cn(
+          "relative grow overflow-hidden rounded-full bg-muted",
+          "data-[orientation=horizontal]:h-1.5 data-[orientation=horizontal]:w-full",
+          "data-[orientation=vertical]:h-full data-[orientation=vertical]:w-1.5",
+        )}
+      >
+        <SliderPrimitive.Range
+          data-slot="slider-range"
+          className={cn(
+            "absolute bg-primary",
+            "data-[orientation=horizontal]:h-full data-[orientation=vertical]:w-full",
+          )}
+        />
+      </SliderPrimitive.Track>
+      {Array.from({ length: thumbCount }, (_, index) => (
+        <SliderPrimitive.Thumb
+          key={index}
+          data-slot="slider-thumb"
+          aria-label={thumbLabels?.[index] ?? ariaLabel}
+          aria-labelledby={thumbLabels?.[index] ? undefined : ariaLabelledBy}
+          aria-valuetext={thumbValueTexts?.[index] ?? ariaValueText}
+          className={cn(
+            "block size-4 shrink-0 rounded-full border-2 border-primary bg-background shadow-sm",
+            "transition-[box-shadow,transform] duration-[var(--duration-instant)]",
+            "hover:scale-110 disabled:pointer-events-none",
+            focusRing,
+          )}
+        />
+      ))}
+    </SliderPrimitive.Root>
+  );
+}
+
+/**
+ * Warns, in development only, when a thumb would render without a name.
+ *
+ * An unnamed slider is invisible on screen and serious for screen reader users,
+ * so it is surfaced where it is introduced rather than left for an audit.
+ */
+function useMissingLabelWarning(
+  thumbCount: number,
+  thumbLabels: string[] | undefined,
+  ariaLabel: string | undefined,
+  ariaLabelledBy: string | undefined,
+) {
+  useEffect(() => {
+    if (process.env.NODE_ENV === "production") return;
+
+    const fallbackName = ariaLabel ?? ariaLabelledBy;
+    const unnamed = Array.from({ length: thumbCount }).some(
+      (_, index) => !(thumbLabels?.[index] ?? fallbackName),
+    );
+    if (!unnamed) return;
+
+    console.warn(
+      "[Slider] A thumb has no accessible name. Pass aria-label or aria-labelledby, or " +
+        "thumbLabels to name each thumb of a range slider individually.",
+    );
+  }, [thumbCount, thumbLabels, ariaLabel, ariaLabelledBy]);
+}

package/src/components/spinner/index.ts

@@ -0,0 +1 @@
+export { Spinner, spinnerVariants, type SpinnerProps } from "./spinner";

package/src/components/spinner/meta.ts

@@ -0,0 +1,15 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "spinner",
+  title: "Spinner",
+  description: "An indeterminate loading indicator for buttons, panels and inline content.",
+  category: "feedback",
+  status: "stable",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: [],
+  files: ["spinner.tsx"],
+  a11y:
+    "Renders aria-hidden by default so it does not announce inside controls that already " +
+    'expose a busy state. Pass `label` to announce it standalone via role="status".',
+});

package/src/components/spinner/spinner.stories.tsx

@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Button } from "@/components/button";
+
+import { Spinner } from "./spinner";
+
+const meta = {
+  title: "Feedback/Spinner",
+  component: Spinner,
+  args: { size: "md" },
+  argTypes: { size: { control: "select", options: ["xs", "sm", "md", "lg", "xl"] } },
+} satisfies Meta<typeof Spinner>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { label: "Loading" },
+};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-4">
+      {(["xs", "sm", "md", "lg", "xl"] as const).map((size) => (
+        <Spinner key={size} size={size} />
+      ))}
+    </div>
+  ),
+};
+
+export const InheritsColour: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Spinner className="text-primary" />
+      <Spinner className="text-destructive" />
+      <Spinner className="text-muted-foreground" />
+    </div>
+  ),
+};
+
+/** Inside a control that already reports its own busy state, omit `label`. */
+export const InsideAButton: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <Button loading>Saving changes</Button>,
+};

package/src/components/spinner/spinner.test.tsx

@@ -0,0 +1,41 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Spinner } from "./spinner";
+
+describe("Spinner", () => {
+  it("is hidden from assistive technology by default", () => {
+    const { container } = render(<Spinner />);
+    expect(container.querySelector("svg")).toHaveAttribute("aria-hidden", "true");
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+  });
+
+  it("announces itself when given a label", () => {
+    render(<Spinner label="Loading results" />);
+    expect(screen.getByRole("status")).toHaveTextContent("Loading results");
+  });
+
+  it.each([
+    ["xs", "size-3"],
+    ["sm", "size-3.5"],
+    ["md", "size-4"],
+    ["lg", "size-5"],
+    ["xl", "size-6"],
+  ] as const)("applies the %s size", (size, expectedClass) => {
+    const { container } = render(<Spinner size={size} />);
+    expect(container.querySelector("svg")).toHaveClass(expectedClass);
+  });
+
+  it("lets a consumer className override the size", () => {
+    const { container } = render(<Spinner className="size-10" />);
+    const svg = container.querySelector("svg");
+    expect(svg).toHaveClass("size-10");
+    expect(svg).not.toHaveClass("size-4");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Spinner label="Loading" />);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/spinner/spinner.tsx

@@ -0,0 +1,68 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+const spinnerVariants = cva("animate-spin text-current", {
+  variants: {
+    size: {
+      xs: "size-3",
+      sm: "size-3.5",
+      md: "size-4",
+      lg: "size-5",
+      xl: "size-6",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});
+
+export interface SpinnerProps
+  extends Omit<ComponentPropsWithRef<"svg">, "children">, VariantProps<typeof spinnerVariants> {
+  /**
+   * Announced to assistive technology while the spinner is visible.
+   *
+   * Omit it when the spinner sits inside a control that already communicates
+   * its busy state (a loading Button, for example) — announcing twice is worse
+   * than not announcing at all.
+   */
+  label?: string;
+}
+
+/** Indeterminate loading indicator. */
+export function Spinner({ className, size, label, ...props }: SpinnerProps) {
+  return (
+    <>
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        aria-hidden="true"
+        className={cn(spinnerVariants({ size }), className)}
+        {...props}
+      >
+        <circle
+          cx="12"
+          cy="12"
+          r="9.5"
+          stroke="currentColor"
+          strokeWidth="2.5"
+          opacity="0.22"
+        />
+        <path
+          d="M12 2.5a9.5 9.5 0 0 1 9.5 9.5"
+          stroke="currentColor"
+          strokeWidth="2.5"
+          strokeLinecap="round"
+        />
+      </svg>
+      {label ? (
+        <span role="status" className="sr-only">
+          {label}
+        </span>
+      ) : null}
+    </>
+  );
+}
+
+export { spinnerVariants };

package/src/components/switch/index.ts

@@ -0,0 +1 @@
+export { Switch, type SwitchProps } from "./switch";

package/src/components/switch/meta.ts

@@ -0,0 +1,15 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "switch",
+  title: "Switch",
+  description: "An immediate on/off toggle for settings that apply straight away.",
+  category: "form",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["switch.tsx"],
+  a11y:
+    'Exposed as role="switch" and toggled with Space or Enter. Needs a visible label tied with ' +
+    "htmlFor/id. Do not rely on colour alone to show state — position and the label carry it too.",
+});

package/src/components/switch/switch.stories.tsx

@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Label } from "@/components/label";
+
+import { Switch } from "./switch";
+
+const meta = {
+  title: "Forms/Switch",
+  component: Switch,
+  args: { disabled: false },
+  argTypes: { disabled: { control: "boolean" } },
+} satisfies Meta<typeof Switch>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="flex items-center gap-2">
+      <Switch id="airplane" {...args} />
+      <Label htmlFor="airplane">Airplane mode</Label>
+    </div>
+  ),
+};
+
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid gap-3">
+      {[
+        { id: "off", label: "Off", checked: false },
+        { id: "on", label: "On", checked: true },
+      ].map((state) => (
+        <div key={state.id} className="flex items-center gap-2">
+          <Switch id={state.id} checked={state.checked} />
+          <Label htmlFor={state.id}>{state.label}</Label>
+        </div>
+      ))}
+      <div className="flex items-center gap-2">
+        <Switch id="disabled-off" disabled />
+        <Label htmlFor="disabled-off">Disabled</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <Switch id="disabled-on" disabled checked />
+        <Label htmlFor="disabled-on">Disabled and on</Label>
+      </div>
+    </div>
+  ),
+};
+
+/** A switch applies immediately — if it needs a Save button, use a Checkbox. */
+export const SettingsRow: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-80 divide-y divide-border rounded-lg border border-border">
+      {[
+        { id: "row-1", label: "Automatic deploys", hint: "Deploy every push to main." },
+        { id: "row-2", label: "Preview comments", hint: "Comment on pull requests." },
+      ].map((row) => (
+        <div key={row.id} className="flex items-start justify-between gap-4 p-4">
+          <div className="grid gap-1">
+            <Label htmlFor={row.id}>{row.label}</Label>
+            <p className="text-xs text-muted-foreground">{row.hint}</p>
+          </div>
+          <Switch id={row.id} defaultChecked={row.id === "row-1"} />
+        </div>
+      ))}
+    </div>
+  ),
+};