@primitiv-ui/react 0.1.0

package/src/Progress/Progress.tsx

@@ -0,0 +1,178 @@
+import { useMemo } from "react";
+
+import { Slot } from "../Slot";
+
+import { ProgressContext } from "./ProgressContext";
+import { useProgressContext, useProgressRoot } from "./hooks";
+import { ProgressIndicatorProps, ProgressRootProps } from "./types";
+
+function defaultGetValueLabel(value: number, max: number): string {
+  return `${Math.round((value / max) * 100)}%`;
+}
+
+/**
+ * The root of a Progress bar — a `<div role="progressbar">` that resolves
+ * `value` / `max` into a {@link ProgressState} and provides
+ * {@link ProgressContext} to a descendant
+ * {@link ProgressIndicator | `Progress.Indicator`}.
+ *
+ * Progress is a **display-only** component: it has no internal state and is
+ * never interactive. The `value` prop is always consumer-driven — there is
+ * no controlled/uncontrolled split.
+ *
+ * **Indeterminate.** Omit `value` (or pass `null`) when the completion ratio
+ * is unknown. `aria-valuenow` / `aria-valuetext` are dropped and
+ * `data-state="indeterminate"`.
+ *
+ * **ARIA.** `role="progressbar"`, `aria-valuemin="0"`, `aria-valuemax`, and —
+ * when determinate — `aria-valuenow` and `aria-valuetext` are set
+ * automatically. Provide an accessible name via `aria-label` or
+ * `aria-labelledby`.
+ *
+ * **Styling hooks.** `data-state="indeterminate" | "loading" | "complete"`,
+ * plus `data-value` (determinate only) and `data-max` on the root.
+ *
+ * @example Determinate
+ * ```tsx
+ * <Progress.Root value={60} aria-label="Upload progress">
+ *   <Progress.Indicator />
+ * </Progress.Root>
+ * ```
+ *
+ * @example Indeterminate
+ * ```tsx
+ * <Progress.Root aria-label="Loading">
+ *   <Progress.Indicator />
+ * </Progress.Root>
+ * ```
+ */
+function ProgressRoot({
+  value,
+  max,
+  getValueLabel = defaultGetValueLabel,
+  asChild = false,
+  children,
+  ...rest
+}: ProgressRootProps) {
+  const resolved = useProgressRoot({ value, max });
+  const { state } = resolved;
+
+  const contextValue = useMemo(
+    () => ({ value: resolved.value, max: resolved.max, state }),
+    [resolved.value, resolved.max, state],
+  );
+
+  const valueProps =
+    resolved.value === null
+      ? {}
+      : {
+          "aria-valuenow": resolved.value,
+          "aria-valuetext": getValueLabel(resolved.value, resolved.max),
+          "data-value": resolved.value,
+        };
+
+  const rootProps = {
+    ...rest,
+    role: "progressbar" as const,
+    "aria-valuemin": 0,
+    "aria-valuemax": resolved.max,
+    "data-state": state,
+    "data-max": resolved.max,
+    ...valueProps,
+  };
+
+  return (
+    <ProgressContext.Provider value={contextValue}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <div {...rootProps}>{children}</div>
+      )}
+    </ProgressContext.Provider>
+  );
+}
+
+ProgressRoot.displayName = "ProgressRoot";
+
+/**
+ * The visual fill of a Progress bar — a decorative `<div>` that mirrors the
+ * parent {@link ProgressRoot}'s state via `data-*` attributes so consumers
+ * can drive its width with pure CSS.
+ *
+ * **Styling hooks.** `data-state="indeterminate" | "loading" | "complete"`,
+ * plus `data-value` (determinate only) and `data-max`. Compute the fill
+ * width from these — e.g. `width: calc(var(--value) / var(--max) * 100%)` via
+ * a CSS custom property, or an inline `style` set by the consumer.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element as
+ * the indicator, with the `data-*` hooks merged in.
+ *
+ * @example
+ * ```tsx
+ * <Progress.Root value={75} aria-label="Upload progress">
+ *   <Progress.Indicator />
+ * </Progress.Root>
+ * ```
+ *
+ * @throws if rendered outside a `Progress.Root`.
+ */
+function ProgressIndicator({
+  asChild = false,
+  children,
+  ...rest
+}: ProgressIndicatorProps) {
+  const { value, max, state } = useProgressContext();
+  const indicatorProps = {
+    ...rest,
+    "data-state": state,
+    "data-value": value === null ? undefined : value,
+    "data-max": max,
+  };
+  if (asChild) {
+    return <Slot {...indicatorProps}>{children}</Slot>;
+  }
+  return <div {...indicatorProps}>{children}</div>;
+}
+
+ProgressIndicator.displayName = "ProgressIndicator";
+
+type TProgressCompound = typeof ProgressRoot & {
+  Root: typeof ProgressRoot;
+  Indicator: typeof ProgressIndicator;
+};
+
+/**
+ * Headless, accessible **Progress** — a compound component implementing the
+ * [WAI-ARIA progressbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/)
+ * on a `<div role="progressbar">`. Display-only and non-interactive: it
+ * reflects a consumer-supplied `value`. Zero styles ship.
+ *
+ * `Progress` is both callable (an alias of
+ * {@link ProgressRoot | `Progress.Root`}) and carries its sub-components as
+ * static properties.
+ *
+ * - {@link ProgressRoot | `Progress.Root`} — `role="progressbar"`, value
+ *   resolution, context provider.
+ * - {@link ProgressIndicator | `Progress.Indicator`} — decorative fill;
+ *   width driven by `data-*` via CSS.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Progress } from "@primitiv-ui/react";
+ *
+ * <Progress.Root value={40} aria-label="Upload progress">
+ *   <Progress.Indicator />
+ * </Progress.Root>
+ * ```
+ *
+ * @see {@link ProgressRoot} for value resolution and ARIA details.
+ * @see {@link ProgressIndicator} for styling the fill.
+ */
+const ProgressCompound: TProgressCompound = Object.assign(ProgressRoot, {
+  Root: ProgressRoot,
+  Indicator: ProgressIndicator,
+});
+
+ProgressCompound.displayName = "Progress";
+
+export { ProgressCompound as Progress };

package/src/Progress/ProgressContext.ts

@@ -0,0 +1,15 @@
+import { createStrictContext } from "../utils";
+
+import { ProgressState } from "./types";
+
+export type ProgressContextValue = {
+  value: number | null;
+  max: number;
+  state: ProgressState;
+};
+
+export const [ProgressContext, useProgressContext] =
+  createStrictContext<ProgressContextValue>(
+    "Progress.Indicator must be rendered inside a <Progress.Root>.",
+    "ProgressContext",
+  );

package/src/Progress/README.md

@@ -0,0 +1,112 @@
+# Progress
+
+Headless, accessible **Progress** — a compound component implementing the
+[WAI-ARIA progressbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/)
+on a `<div role="progressbar">`. Display-only and non-interactive: it
+reflects a consumer-supplied `value`. Zero styles ship.
+
+```tsx
+import { Progress } from "@primitiv-ui/react";
+
+<Progress.Root value={60} aria-label="Upload progress">
+  <Progress.Indicator />
+</Progress.Root>;
+```
+
+## Sub-components
+
+| Export | Element | ARIA / data hooks | `asChild` |
+|--------|---------|-------------------|-----------|
+| `Progress.Root` | `<div>` | `role="progressbar"`, `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext`, `data-state`, `data-value`, `data-max` | yes |
+| `Progress.Indicator` | `<div>` | `data-state`, `data-value`, `data-max` | yes |
+
+## Props
+
+### `Progress.Root`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | `number \| null` | `null` | Current progress between `0` and `max`. `null` (or omitted) renders an indeterminate bar. |
+| `max` | `number` | `100` | Upper bound of `value`. Must be a positive, finite number. |
+| `getValueLabel` | `(value: number, max: number) => string` | rounded percentage | Produces `aria-valuetext`. Not called while indeterminate. |
+| `asChild` | `boolean` | `false` | Render the consumer's own element instead of `<div>`. |
+| `...rest` | `ComponentProps<"div">` | — | All other `<div>` props (`aria-label`, `className`, etc.). |
+
+`Progress.Indicator` accepts all `<div>` props plus `asChild`.
+
+## Determinate vs indeterminate
+
+Pass a numeric `value` for a determinate bar — `aria-valuenow` and
+`aria-valuetext` are set and `data-state` is `"loading"` or `"complete"`.
+
+```tsx
+<Progress.Root value={75} aria-label="Upload progress">
+  <Progress.Indicator />
+</Progress.Root>
+```
+
+Omit `value` (or pass `null`) when the completion ratio is unknown.
+`aria-valuenow` / `aria-valuetext` / `data-value` are dropped and
+`data-state="indeterminate"`.
+
+```tsx
+<Progress.Root aria-label="Loading">
+  <Progress.Indicator />
+</Progress.Root>
+```
+
+## Value label
+
+`aria-valuetext` defaults to a rounded percentage (e.g. `"42%"`). Override it
+with `getValueLabel` when a percentage isn't the most useful description:
+
+```tsx
+<Progress.Root
+  value={3}
+  max={10}
+  getValueLabel={(value, max) => `${value} of ${max} files uploaded`}
+  aria-label="Upload progress"
+>
+  <Progress.Indicator />
+</Progress.Root>
+```
+
+## Accessibility
+
+`Progress` is display-only — it is never focusable or interactive. Always give
+the Root an accessible name with `aria-label` or `aria-labelledby`.
+
+`max` must be a positive, finite number, and a numeric `value` must fall
+between `0` and `max`. Both are validated — an out-of-range prop throws a
+clear error rather than rendering a misleading bar.
+
+## The Indicator
+
+`Progress.Indicator` is the visual fill. It mirrors the Root's `data-state`,
+`data-value`, and `data-max`, so its width can be driven with pure CSS — for
+example via a custom property the consumer sets, or an inline `style`:
+
+```tsx
+<Progress.Root value={value} max={max} aria-label="Upload progress">
+  <Progress.Indicator style={{ inlineSize: `${(value / max) * 100}%` }} />
+</Progress.Root>
+```
+
+## `asChild` composition
+
+Both sub-components accept `asChild`. The library's ARIA attributes and
+`data-*` hooks are merged onto the consumer's element.
+
+```tsx
+<Progress.Root asChild value={50} aria-label="Upload progress">
+  <section>…</section>
+</Progress.Root>
+```
+
+## Styling hooks
+
+| Attribute | Values | Set on |
+|-----------|--------|--------|
+| `data-state` | `"indeterminate"` \| `"loading"` \| `"complete"` | `Progress.Root`, `Progress.Indicator` |
+| `data-value` | the resolved `value` (determinate only) | `Progress.Root`, `Progress.Indicator` |
+| `data-max` | the resolved `max` | `Progress.Root`, `Progress.Indicator` |

package/src/Progress/__tests__/Progress.asChild.test.tsx

@@ -0,0 +1,37 @@
+import { render, screen } from "@testing-library/react";
+
+import { Progress } from "../Progress";
+
+describe("Progress asChild", () => {
+  it("renders the Root as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <Progress.Root asChild value={50} aria-label="Upload">
+        <section>fill</section>
+      </Progress.Root>,
+    );
+    const bar = screen.getByRole("progressbar", { name: "Upload" });
+
+    // Assert — section rendered, not div; ARIA merged onto it
+    expect(bar.tagName).toBe("SECTION");
+    expect(bar).toHaveAttribute("aria-valuenow", "50");
+    expect(bar).toHaveAttribute("data-state", "loading");
+  });
+
+  it("renders the Indicator as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <Progress.Root value={50} aria-label="Upload">
+        <Progress.Indicator asChild>
+          <span data-testid="custom-fill" />
+        </Progress.Indicator>
+      </Progress.Root>,
+    );
+    const fill = screen.getByTestId("custom-fill");
+
+    // Assert — our span rendered; data-* hooks merged onto it
+    expect(fill.tagName).toBe("SPAN");
+    expect(fill).toHaveAttribute("data-state", "loading");
+    expect(fill).toHaveAttribute("data-value", "50");
+  });
+});

package/src/Progress/__tests__/Progress.basic-rendering.test.tsx

@@ -0,0 +1,65 @@
+import { render, screen } from "@testing-library/react";
+
+import { Progress } from "../Progress";
+
+describe("Progress basic rendering", () => {
+  it('renders a <div role="progressbar">', () => {
+    // Arrange & Act
+    render(<Progress.Root aria-label="Loading" />);
+    const bar = screen.getByRole("progressbar", { name: "Loading" });
+
+    // Assert
+    expect(bar.tagName).toBe("DIV");
+  });
+
+  it('defaults aria-valuemin="0" and aria-valuemax="100"', () => {
+    // Arrange & Act
+    render(<Progress.Root aria-label="Loading" />);
+    const bar = screen.getByRole("progressbar", { name: "Loading" });
+
+    // Assert
+    expect(bar).toHaveAttribute("aria-valuemin", "0");
+    expect(bar).toHaveAttribute("aria-valuemax", "100");
+  });
+
+  it('is indeterminate when value is omitted: data-state="indeterminate", no aria-valuenow', () => {
+    // Arrange & Act
+    render(<Progress.Root aria-label="Loading" />);
+    const bar = screen.getByRole("progressbar", { name: "Loading" });
+
+    // Assert
+    expect(bar).toHaveAttribute("data-state", "indeterminate");
+    expect(bar).not.toHaveAttribute("aria-valuenow");
+    expect(bar).not.toHaveAttribute("data-value");
+  });
+
+  it("renders Progress.Indicator as a <div> inside the root", () => {
+    // Arrange & Act
+    render(
+      <Progress.Root aria-label="Loading">
+        <Progress.Indicator data-testid="indicator" />
+      </Progress.Root>,
+    );
+    const indicator = screen.getByTestId("indicator");
+
+    // Assert
+    expect(indicator.tagName).toBe("DIV");
+    expect(indicator).toBeInTheDocument();
+  });
+
+  it("mirrors data-state and data-max from the root onto the Indicator", () => {
+    // Arrange & Act
+    render(
+      <Progress.Root aria-label="Loading">
+        <Progress.Indicator data-testid="indicator" />
+      </Progress.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("indicator")).toHaveAttribute(
+      "data-state",
+      "indeterminate",
+    );
+    expect(screen.getByTestId("indicator")).toHaveAttribute("data-max", "100");
+  });
+});

package/src/Progress/__tests__/Progress.error-handling.test.tsx

@@ -0,0 +1,40 @@
+import { render } from "@testing-library/react";
+
+import { Progress } from "../Progress";
+
+describe("Progress error handling", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("throws when Progress.Indicator is rendered outside a Progress.Root", () => {
+    // Arrange & Act & Assert
+    expect(() => render(<Progress.Indicator />)).toThrow(
+      "Progress.Indicator must be rendered inside a <Progress.Root>.",
+    );
+  });
+
+  it.each([0, -10, NaN, Infinity])(
+    "throws when max is not a positive finite number (%s)",
+    (max) => {
+      // Arrange & Act & Assert
+      expect(() =>
+        render(<Progress.Root max={max} aria-label="Upload" />),
+      ).toThrow(/`max` must be a positive, finite number/);
+    },
+  );
+
+  it.each([-1, 101, NaN, Infinity])(
+    "throws when value falls outside 0..max (%s)",
+    (value) => {
+      // Arrange & Act & Assert
+      expect(() =>
+        render(<Progress.Root value={value} aria-label="Upload" />),
+      ).toThrow(/`value` must be a finite number between 0 and/);
+    },
+  );
+});

package/src/Progress/__tests__/Progress.fixtures.ts

@@ -0,0 +1,7 @@
+export const determinateStateCases = [
+  { value: 0, max: 100, expectedState: "loading" },
+  { value: 60, max: 100, expectedState: "loading" },
+  { value: 100, max: 100, expectedState: "complete" },
+  { value: 30, max: 60, expectedState: "loading" },
+  { value: 60, max: 60, expectedState: "complete" },
+] as const;

package/src/Progress/__tests__/Progress.value.test.tsx

@@ -0,0 +1,83 @@
+import { render, screen } from "@testing-library/react";
+
+import { Progress } from "../Progress";
+
+import { determinateStateCases } from "./Progress.fixtures";
+
+describe("Progress value", () => {
+  it("sets aria-valuenow and data-value from value", () => {
+    // Arrange & Act
+    render(<Progress.Root value={42} aria-label="Upload" />);
+    const bar = screen.getByRole("progressbar", { name: "Upload" });
+
+    // Assert
+    expect(bar).toHaveAttribute("aria-valuenow", "42");
+    expect(bar).toHaveAttribute("data-value", "42");
+  });
+
+  it("defaults aria-valuetext to a rounded percentage", () => {
+    // Arrange & Act
+    render(<Progress.Root value={1} max={3} aria-label="Upload" />);
+
+    // Assert
+    expect(screen.getByRole("progressbar", { name: "Upload" })).toHaveAttribute(
+      "aria-valuetext",
+      "33%",
+    );
+  });
+
+  it("honours a custom max for aria-valuemax and the percentage label", () => {
+    // Arrange & Act
+    render(<Progress.Root value={25} max={50} aria-label="Upload" />);
+    const bar = screen.getByRole("progressbar", { name: "Upload" });
+
+    // Assert
+    expect(bar).toHaveAttribute("aria-valuemax", "50");
+    expect(bar).toHaveAttribute("aria-valuetext", "50%");
+  });
+
+  it("uses a custom getValueLabel for aria-valuetext", () => {
+    // Arrange & Act
+    render(
+      <Progress.Root
+        value={3}
+        max={10}
+        getValueLabel={(v, m) => `${v} of ${m} files`}
+        aria-label="Upload"
+      />,
+    );
+
+    // Assert
+    expect(screen.getByRole("progressbar", { name: "Upload" })).toHaveAttribute(
+      "aria-valuetext",
+      "3 of 10 files",
+    );
+  });
+
+  it("mirrors data-value onto the Indicator when determinate", () => {
+    // Arrange & Act
+    render(
+      <Progress.Root value={70} aria-label="Upload">
+        <Progress.Indicator data-testid="indicator" />
+      </Progress.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("indicator")).toHaveAttribute("data-value", "70");
+  });
+
+  describe.each(determinateStateCases)(
+    "value $value of $max",
+    ({ value, max, expectedState }) => {
+      it(`derives data-state="${expectedState}"`, () => {
+        // Arrange & Act
+        render(<Progress.Root value={value} max={max} aria-label="Upload" />);
+
+        // Assert
+        expect(
+          screen.getByRole("progressbar", { name: "Upload" }),
+        ).toHaveAttribute("data-state", expectedState);
+      });
+    },
+  );
+});

package/src/Progress/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useProgressContext } from "./useProgressContext";
+export { useProgressRoot } from "./useProgressRoot";

package/src/Progress/hooks/useProgressContext.ts

@@ -0,0 +1 @@
+export { useProgressContext } from "../ProgressContext";

package/src/Progress/hooks/useProgressRoot.ts

@@ -0,0 +1,45 @@
+import { ProgressState } from "../types";
+
+const DEFAULT_MAX = 100;
+
+type UseProgressRootArgs = {
+  value?: number | null;
+  max?: number;
+};
+
+type UseProgressRootResult = {
+  value: number | null;
+  max: number;
+  state: ProgressState;
+};
+
+/**
+ * Resolves a Progress root's `value` / `max` props into the canonical
+ * `{ value, max, state }` triple consumed by the Root element and shared
+ * through {@link ProgressContext}.
+ */
+export function useProgressRoot({
+  value = null,
+  max = DEFAULT_MAX,
+}: UseProgressRootArgs): UseProgressRootResult {
+  if (!Number.isFinite(max) || max <= 0) {
+    throw new Error(
+      `Progress.Root: \`max\` must be a positive, finite number. Received: ${max}.`,
+    );
+  }
+
+  if (value != null && (!Number.isFinite(value) || value < 0 || value > max)) {
+    throw new Error(
+      `Progress.Root: \`value\` must be a finite number between 0 and ${max}, or null for an indeterminate bar. Received: ${value}.`,
+    );
+  }
+
+  const isIndeterminate = value == null;
+  const state: ProgressState = isIndeterminate
+    ? "indeterminate"
+    : value >= max
+      ? "complete"
+      : "loading";
+
+  return { value: isIndeterminate ? null : value, max, state };
+}

package/src/Progress/index.ts

@@ -0,0 +1,3 @@
+export * from "./Progress";
+export * from "./ProgressContext";
+export * from "./types";

package/src/Progress/types.ts

@@ -0,0 +1,43 @@
+import { ComponentProps } from "react";
+
+/**
+ * The lifecycle state of a progress bar, derived from `value` and `max`.
+ *
+ * - `"indeterminate"` — `value` is `null` / omitted; the operation's
+ *   completion ratio is unknown.
+ * - `"loading"` — `value` is a number below `max`.
+ * - `"complete"` — `value` has reached `max`.
+ */
+export type ProgressState = "indeterminate" | "loading" | "complete";
+
+/**
+ * Props for {@link Progress.Root} — all `<div>` attributes except the ones
+ * the component derives itself (`role` and the `aria-value*` family), plus
+ * the progress-specific props.
+ */
+export type ProgressRootProps = Omit<
+  ComponentProps<"div">,
+  "role" | "aria-valuemin" | "aria-valuemax" | "aria-valuenow" | "aria-valuetext"
+> & {
+  /**
+   * Current progress, between `0` and `max`. Pass `null` (or omit) for an
+   * indeterminate progress bar whose completion ratio is unknown.
+   */
+  value?: number | null;
+  /** Upper bound of `value`. Must be a positive finite number. Defaults to `100`. */
+  max?: number;
+  /**
+   * Produces the human-readable `aria-valuetext`. Receives the resolved
+   * `value` and `max`. Defaults to a rounded percentage (e.g. `"42%"`).
+   * Not called while indeterminate.
+   */
+  getValueLabel?: (value: number, max: number) => string;
+  /** Render the consumer's own element instead of the native `<div>`. */
+  asChild?: boolean;
+};
+
+/** Props for {@link Progress.Indicator} — all `<div>` attributes plus `asChild`. */
+export type ProgressIndicatorProps = ComponentProps<"div"> & {
+  /** Render the consumer's own element instead of the native `<div>`. */
+  asChild?: boolean;
+};