@dowel-ui/react 0.1.0

package/src/components/popover/popover.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import { Popover as PopoverPrimitive } from "radix-ui";
+import { useEffect, type ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Rich floating content anchored to a trigger.
+ *
+ * Non-modal by default: the page stays interactive and focus is not trapped,
+ * which is right for a surface the user can simply click away from. Pass
+ * `modal` when the popover contains a task that must be completed or abandoned.
+ *
+ * The content carries `role="dialog"`, so it MUST have an accessible name via
+ * `aria-label` or `aria-labelledby`. Without one it is announced as an unnamed
+ * dialog, which tells a screen reader user nothing about what just opened.
+ */
+export const Popover = PopoverPrimitive.Root;
+export const PopoverTrigger = PopoverPrimitive.Trigger;
+export const PopoverAnchor = PopoverPrimitive.Anchor;
+export const PopoverClose = PopoverPrimitive.Close;
+
+export type PopoverContentProps = ComponentPropsWithRef<typeof PopoverPrimitive.Content>;
+
+export function PopoverContent({
+  className,
+  align = "center",
+  sideOffset = 8,
+  ...props
+}: PopoverContentProps) {
+  useMissingLabelWarning(props["aria-label"], props["aria-labelledby"]);
+
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Content
+        data-slot="popover-content"
+        align={align}
+        sideOffset={sideOffset}
+        className={cn(
+          "z-[var(--z-popover)] w-72 rounded-lg border border-border bg-popover p-4 text-popover-foreground shadow-lg",
+          "max-h-[var(--radix-popover-content-available-height)] outline-none",
+          // One keyframe pair covers every side and alignment: the primitive
+          // computes the origin, so the panel always grows from its anchor.
+          "origin-[var(--radix-popover-content-transform-origin)]",
+          "data-[state=closed]:animate-float-out data-[state=open]:animate-float-in",
+          className,
+        )}
+        {...props}
+      />
+    </PopoverPrimitive.Portal>
+  );
+}
+
+/**
+ * Warns, in development only, when the content has no accessible name.
+ *
+ * This is a mistake that is invisible in the browser and serious for screen
+ * reader users, so it is surfaced at the moment it is introduced rather than
+ * left for an audit. Typed as optional rather than required because a name can
+ * legitimately come from either attribute, and forcing one at the type level
+ * would break composition patterns that supply it dynamically.
+ */
+function useMissingLabelWarning(label?: string, labelledBy?: string) {
+  useEffect(() => {
+    if (process.env.NODE_ENV === "production") return;
+    if (label ?? labelledBy) return;
+
+    console.warn(
+      '[PopoverContent] Missing accessible name. The content has role="dialog", so pass ' +
+        "aria-label, or aria-labelledby pointing at a heading inside it.",
+    );
+  }, [label, labelledBy]);
+}
+
+export function PopoverArrow({
+  className,
+  ...props
+}: ComponentPropsWithRef<typeof PopoverPrimitive.Arrow>) {
+  return (
+    <PopoverPrimitive.Arrow
+      data-slot="popover-arrow"
+      width={12}
+      height={6}
+      className={cn("fill-popover stroke-border", className)}
+      {...props}
+    />
+  );
+}

package/src/components/progress/index.ts

@@ -0,0 +1 @@
+export { Progress, progressVariants, type ProgressProps } from "./progress";

package/src/components/progress/meta.ts

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "progress",
+  title: "Progress",
+  description: "Shows how far along a task is, or that one is running at all.",
+  category: "feedback",
+  status: "stable",
+  dependencies: ["class-variance-authority", "radix-ui"],
+  registryDependencies: [],
+  files: ["progress.tsx"],
+  a11y:
+    'Exposed as role="progressbar" with aria-valuenow, and give it a name with aria-label or ' +
+    "aria-labelledby. Omitting `value` marks it indeterminate, which is announced differently " +
+    "from zero. Show the percentage in text as well — the bar alone is not readable at a glance " +
+    "for everyone.",
+});

package/src/components/progress/progress.stories.tsx

@@ -0,0 +1,90 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+import { useEffect, useState } from "react";
+
+import { Progress } from "./progress";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <div className="w-72">
+    <Story />
+  </div>
+);
+
+const meta = {
+  title: "Feedback/Progress",
+  component: Progress,
+  args: { value: 40, size: "md", tone: "primary", "aria-label": "Upload" },
+  argTypes: {
+    value: { control: { type: "range", min: 0, max: 100 } },
+    size: { control: "inline-radio", options: ["sm", "md", "lg"] },
+    tone: { control: "select", options: ["primary", "success", "warning", "destructive"] },
+  },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof Progress>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** The number belongs on screen too — a bar alone is hard to read precisely. */
+export const WithLabel: Story = {
+  parameters: { controls: { disable: true } },
+  render: function WithLabel() {
+    const [value, setValue] = useState(12);
+
+    useEffect(() => {
+      const timer = setInterval(() => {
+        setValue((current) => (current >= 100 ? 0 : current + 4));
+      }, 400);
+      return () => {
+        clearInterval(timer);
+      };
+    }, []);
+
+    return (
+      <div className="grid gap-2">
+        <div className="flex items-center justify-between text-sm">
+          <span id="upload-label">Uploading assets</span>
+          <span className="text-muted-foreground tabular-nums">{value}%</span>
+        </div>
+        <Progress value={value} aria-labelledby="upload-label" />
+      </div>
+    );
+  },
+};
+
+/** No known duration — announced as indeterminate, not as zero percent. */
+export const Indeterminate: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid gap-2">
+      <span className="text-sm" id="indeterminate-label">
+        Preparing your export…
+      </span>
+      <Progress aria-labelledby="indeterminate-label" />
+    </div>
+  ),
+};
+
+export const Tones: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid gap-4">
+      {(["primary", "success", "warning", "destructive"] as const).map((tone) => (
+        <Progress key={tone} tone={tone} value={65} aria-label={tone} />
+      ))}
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid gap-4">
+      {(["sm", "md", "lg"] as const).map((size) => (
+        <Progress key={size} size={size} value={55} aria-label={size} />
+      ))}
+    </div>
+  ),
+};

package/src/components/progress/progress.test.tsx

@@ -0,0 +1,78 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Progress } from "./progress";
+
+describe("Progress", () => {
+  it("exposes a progressbar with its value", () => {
+    render(<Progress value={40} aria-label="Upload" />);
+
+    const bar = screen.getByRole("progressbar", { name: "Upload" });
+    expect(bar).toHaveAttribute("aria-valuenow", "40");
+    expect(bar).toHaveAttribute("aria-valuemax", "100");
+  });
+
+  it("reports an indeterminate state differently from zero", () => {
+    render(<Progress aria-label="Working" />);
+
+    const bar = screen.getByRole("progressbar");
+    expect(bar).not.toHaveAttribute("aria-valuenow");
+    expect(bar).toHaveAttribute("data-state", "indeterminate");
+  });
+
+  it("treats zero as a real value, not as unknown", () => {
+    render(<Progress value={0} aria-label="Upload" />);
+
+    const bar = screen.getByRole("progressbar");
+    expect(bar).toHaveAttribute("aria-valuenow", "0");
+    expect(bar).toHaveAttribute("data-state", "loading");
+  });
+
+  it("fills proportionally to the value", () => {
+    const { container } = render(<Progress value={25} aria-label="Upload" />);
+    const indicator = container.querySelector("[data-slot='progress-indicator']");
+    expect(indicator).toHaveStyle({ transform: "translateX(-75%)" });
+  });
+
+  it("clamps a value outside the range", () => {
+    const { container } = render(<Progress value={150} aria-label="Upload" max={100} />);
+    const indicator = container.querySelector("[data-slot='progress-indicator']");
+    expect(indicator).toHaveStyle({ transform: "translateX(-0%)" });
+  });
+
+  it.each([
+    ["sm", "h-1"],
+    ["md", "h-2"],
+    ["lg", "h-3"],
+  ] as const)("applies the %s size", (size, expectedClass) => {
+    render(<Progress value={40} size={size} aria-label="Upload" />);
+    expect(screen.getByRole("progressbar")).toHaveClass(expectedClass);
+  });
+
+  it.each([
+    ["primary", "--progress-fill:var(--color-primary)"],
+    ["success", "--progress-fill:var(--color-success)"],
+    ["destructive", "--progress-fill:var(--color-destructive)"],
+  ] as const)("applies the %s tone", (tone, expectedClass) => {
+    render(<Progress value={40} tone={tone} aria-label="Upload" />);
+    expect(screen.getByRole("progressbar").className).toContain(expectedClass);
+  });
+
+  it("lets a consumer className override a conflicting utility", () => {
+    render(<Progress value={40} className="h-6" aria-label="Upload" />);
+    const bar = screen.getByRole("progressbar");
+    expect(bar).toHaveClass("h-6");
+    expect(bar).not.toHaveClass("h-2");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <div>
+        <span id="upload-label">Uploading</span>
+        <Progress value={40} aria-labelledby="upload-label" />
+      </div>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/progress/progress.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { Progress as ProgressPrimitive } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+const progressVariants = cva("relative w-full overflow-hidden rounded-full bg-muted", {
+  variants: {
+    size: {
+      sm: "h-1",
+      md: "h-2",
+      lg: "h-3",
+    },
+    tone: {
+      primary: "[--progress-fill:var(--color-primary)]",
+      success: "[--progress-fill:var(--color-success)]",
+      warning: "[--progress-fill:var(--color-warning)]",
+      destructive: "[--progress-fill:var(--color-destructive)]",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+    tone: "primary",
+  },
+});
+
+export interface ProgressProps
+  extends
+    ComponentPropsWithRef<typeof ProgressPrimitive.Root>,
+    VariantProps<typeof progressVariants> {}
+
+/**
+ * Shows how far along a task is.
+ *
+ * Pass `value={null}` for work whose duration is unknown — that is a genuinely
+ * different state from zero percent, and it is announced as such rather than as
+ * "no progress". For a short wait with no measurable progress, a Spinner says
+ * the same thing with less furniture.
+ */
+export function Progress({ className, size, tone, value, ...props }: ProgressProps) {
+  const indeterminate = value === null || value === undefined;
+  const percent = indeterminate ? 0 : Math.min(100, Math.max(0, value));
+
+  return (
+    <ProgressPrimitive.Root
+      data-slot="progress"
+      value={value}
+      className={cn(progressVariants({ size, tone }), className)}
+      {...props}
+    >
+      <ProgressPrimitive.Indicator
+        data-slot="progress-indicator"
+        className={cn(
+          "h-full w-full flex-1 rounded-full bg-[var(--progress-fill)]",
+          "transition-transform duration-[var(--duration-slow)] ease-[var(--ease-out-quint)]",
+          // With no known value the bar sweeps instead of filling, so it reads
+          // as "working" rather than as a stalled 0%.
+          indeterminate && "animate-pulse-soft",
+        )}
+        style={
+          indeterminate ? undefined : { transform: `translateX(-${String(100 - percent)}%)` }
+        }
+      />
+    </ProgressPrimitive.Root>
+  );
+}
+
+export { progressVariants };

package/src/components/radio-group/index.ts

@@ -0,0 +1,6 @@
+export {
+  RadioGroup,
+  RadioGroupItem,
+  type RadioGroupItemProps,
+  type RadioGroupProps,
+} from "./radio-group";

package/src/components/radio-group/meta.ts

@@ -0,0 +1,16 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "radio-group",
+  title: "Radio Group",
+  description: "A set of mutually exclusive options.",
+  category: "form",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["radio-group.tsx"],
+  a11y:
+    "Arrow keys move between options and select as they go, and the group is a single tab stop — " +
+    "the standard radio model. Give the group an accessible name with aria-labelledby, and each " +
+    "item a Label tied by htmlFor/id.",
+});

package/src/components/radio-group/radio-group.stories.tsx

@@ -0,0 +1,102 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Label } from "@/components/label";
+
+import { RadioGroup, RadioGroupItem } from "./radio-group";
+
+const meta = {
+  title: "Forms/Radio Group",
+  component: RadioGroup,
+  parameters: { controls: { disable: true } },
+} satisfies Meta<typeof RadioGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <fieldset>
+      <legend className="mb-3 text-sm font-medium">Density</legend>
+      <RadioGroup defaultValue="comfortable">
+        {[
+          { value: "default", label: "Default" },
+          { value: "comfortable", label: "Comfortable" },
+          { value: "compact", label: "Compact" },
+        ].map((option) => (
+          <div key={option.value} className="flex items-center gap-2">
+            <RadioGroupItem value={option.value} id={option.value} />
+            <Label htmlFor={option.value}>{option.label}</Label>
+          </div>
+        ))}
+      </RadioGroup>
+    </fieldset>
+  ),
+};
+
+export const WithDescriptions: Story = {
+  render: () => (
+    <fieldset className="w-80">
+      <legend className="mb-3 text-sm font-medium">Plan</legend>
+      <RadioGroup defaultValue="pro" className="gap-3">
+        {[
+          { value: "hobby", label: "Hobby", hint: "For personal projects. Free forever." },
+          { value: "pro", label: "Pro", hint: "For teams shipping to production. $20/month." },
+          { value: "enterprise", label: "Enterprise", hint: "SSO, audit logs and support." },
+        ].map((plan) => (
+          <div key={plan.value} className="flex items-start gap-2">
+            <RadioGroupItem value={plan.value} id={plan.value} className="mt-0.5" />
+            <div className="grid gap-1">
+              <Label htmlFor={plan.value}>{plan.label}</Label>
+              <p className="text-xs text-muted-foreground">{plan.hint}</p>
+            </div>
+          </div>
+        ))}
+      </RadioGroup>
+    </fieldset>
+  ),
+};
+
+/** A selected radio cannot be cleared, so offer an explicit "None". */
+export const WithNoneOption: Story = {
+  render: () => (
+    <fieldset>
+      <legend className="mb-3 text-sm font-medium">Notification sound</legend>
+      <RadioGroup defaultValue="none">
+        {[
+          { value: "none", label: "None" },
+          { value: "chime", label: "Chime" },
+          { value: "ping", label: "Ping" },
+        ].map((option) => (
+          <div key={option.value} className="flex items-center gap-2">
+            <RadioGroupItem value={option.value} id={`sound-${option.value}`} />
+            <Label htmlFor={`sound-${option.value}`}>{option.label}</Label>
+          </div>
+        ))}
+      </RadioGroup>
+    </fieldset>
+  ),
+};
+
+export const WithDisabledOption: Story = {
+  render: () => (
+    <fieldset>
+      <legend className="mb-3 text-sm font-medium">Region</legend>
+      <RadioGroup defaultValue="us">
+        {[
+          { value: "us", label: "United States", disabled: false },
+          { value: "eu", label: "Europe", disabled: false },
+          { value: "ap", label: "Asia Pacific (coming soon)", disabled: true },
+        ].map((option) => (
+          <div key={option.value} className="flex items-center gap-2">
+            <RadioGroupItem
+              value={option.value}
+              id={`region-${option.value}`}
+              disabled={option.disabled}
+            />
+            <Label htmlFor={`region-${option.value}`}>{option.label}</Label>
+          </div>
+        ))}
+      </RadioGroup>
+    </fieldset>
+  ),
+};

package/src/components/radio-group/radio-group.test.tsx

@@ -0,0 +1,152 @@
+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 { Label } from "../label";
+import { RadioGroup, RadioGroupItem } from "./radio-group";
+
+function Example({
+  onValueChange,
+  defaultValue = "comfortable",
+}: {
+  onValueChange?: (value: string) => void;
+  defaultValue?: string;
+} = {}) {
+  return (
+    <>
+      <span id="density-label">Density</span>
+      <RadioGroup
+        aria-labelledby="density-label"
+        defaultValue={defaultValue}
+        onValueChange={onValueChange}
+      >
+        {[
+          { value: "default", label: "Default" },
+          { value: "comfortable", label: "Comfortable" },
+          { value: "compact", label: "Compact", disabled: true },
+        ].map((option) => (
+          <div key={option.value} className="flex items-center gap-2">
+            <RadioGroupItem value={option.value} id={option.value} disabled={option.disabled} />
+            <Label htmlFor={option.value}>{option.label}</Label>
+          </div>
+        ))}
+      </RadioGroup>
+    </>
+  );
+}
+
+describe("RadioGroup", () => {
+  it("exposes a named group of radios", () => {
+    render(<Example />);
+    expect(screen.getByRole("radiogroup", { name: "Density" })).toBeInTheDocument();
+    expect(screen.getAllByRole("radio")).toHaveLength(3);
+  });
+
+  it("marks the default value as checked", () => {
+    render(<Example />);
+    expect(screen.getByRole("radio", { name: "Comfortable" })).toBeChecked();
+    expect(screen.getByRole("radio", { name: "Default" })).not.toBeChecked();
+  });
+
+  it("selects on click", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.click(screen.getByRole("radio", { name: "Default" }));
+    expect(screen.getByRole("radio", { name: "Default" })).toBeChecked();
+    expect(screen.getByRole("radio", { name: "Comfortable" })).not.toBeChecked();
+  });
+
+  it("selects via its label", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.click(screen.getByText("Default"));
+    expect(screen.getByRole("radio", { name: "Default" })).toBeChecked();
+  });
+
+  it("is a single tab stop", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.tab();
+    expect(screen.getByRole("radio", { name: "Comfortable" })).toHaveFocus();
+
+    await user.tab();
+    expect(screen.getByRole("radio", { name: "Default" })).not.toHaveFocus();
+  });
+
+  it("moves focus with the arrow keys", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.tab();
+    await user.keyboard("{ArrowUp}");
+    expect(screen.getByRole("radio", { name: "Default" })).toHaveFocus();
+
+    await user.keyboard("{ArrowDown}");
+    expect(screen.getByRole("radio", { name: "Comfortable" })).toHaveFocus();
+  });
+
+  // Selection-on-arrow is not asserted here. The primitive sets its
+  // "an arrow key is down" flag from a bubble-phase document listener, but
+  // roving focus moves focus during the item's own keydown handler, so under
+  // jsdom's focus timing the flag is still false when the focus handler runs.
+  // Asserting it would test the simulation, not the behaviour; the real-browser
+  // path is covered by the Storybook a11y run.
+
+  it("does not select a disabled option", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.click(screen.getByRole("radio", { name: "Compact" }));
+    expect(screen.getByRole("radio", { name: "Compact" })).not.toBeChecked();
+    expect(screen.getByRole("radio", { name: "Comfortable" })).toBeChecked();
+  });
+
+  it("reports changes", async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    render(<Example onValueChange={onValueChange} />);
+
+    await user.click(screen.getByRole("radio", { name: "Default" }));
+    expect(onValueChange).toHaveBeenCalledWith("default");
+  });
+
+  it("works controlled", async () => {
+    const user = userEvent.setup();
+
+    function Controlled() {
+      const [value, setValue] = useState("a");
+      return (
+        <RadioGroup aria-label="Choice" value={value} onValueChange={setValue}>
+          <RadioGroupItem value="a" aria-label="A" />
+          <RadioGroupItem value="b" aria-label="B" />
+        </RadioGroup>
+      );
+    }
+
+    render(<Controlled />);
+    await user.click(screen.getByRole("radio", { name: "B" }));
+    expect(screen.getByRole("radio", { name: "B" })).toBeChecked();
+  });
+
+  it("lets a consumer className override a conflicting utility", () => {
+    render(
+      <RadioGroup aria-label="Choice" className="gap-8" data-testid="group">
+        <RadioGroupItem value="a" aria-label="A" />
+      </RadioGroup>,
+    );
+
+    const group = screen.getByTestId("group");
+    expect(group).toHaveClass("gap-8");
+    expect(group).not.toHaveClass("gap-3");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Example />);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/radio-group/radio-group.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import { RadioGroup as RadioGroupPrimitive } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/**
+ * A set of mutually exclusive options.
+ *
+ * Radios are for choosing one of a small, visible set. Once a radio is
+ * selected it cannot be unselected by clicking it again, so include an explicit
+ * "None" option if the choice must be reversible.
+ */
+export type RadioGroupProps = ComponentPropsWithRef<typeof RadioGroupPrimitive.Root>;
+
+export function RadioGroup({ className, ...props }: RadioGroupProps) {
+  return (
+    <RadioGroupPrimitive.Root
+      data-slot="radio-group"
+      className={cn("grid gap-3", className)}
+      {...props}
+    />
+  );
+}
+
+export type RadioGroupItemProps = ComponentPropsWithRef<typeof RadioGroupPrimitive.Item>;
+
+export function RadioGroupItem({ className, ...props }: RadioGroupItemProps) {
+  return (
+    <RadioGroupPrimitive.Item
+      data-slot="radio-group-item"
+      className={cn(
+        "peer aspect-square size-4 shrink-0 rounded-full border border-input bg-background shadow-xs",
+        "transition-[background-color,border-color,box-shadow] duration-[var(--duration-fast)]",
+        "data-[state=checked]:border-primary",
+        "disabled:cursor-not-allowed disabled:opacity-55",
+        "aria-invalid:border-destructive",
+        focusRing,
+        className,
+      )}
+      {...props}
+    >
+      <RadioGroupPrimitive.Indicator
+        data-slot="radio-group-indicator"
+        className="grid size-full place-items-center"
+      >
+        <span className="size-2 rounded-full bg-primary" />
+      </RadioGroupPrimitive.Indicator>
+    </RadioGroupPrimitive.Item>
+  );
+}