@primitiv-ui/react 0.1.37 → 0.1.39

package/src/Portal/README.md

@@ -1,70 +0,0 @@
-# Portal
-
-A utility component that renders its children outside the current React subtree
-using React's [`createPortal`](https://react.dev/reference/react-dom/createPortal).
-Use it whenever a subtree needs to escape its parent's stacking context, overflow
-clipping, or z-index hierarchy — tooltips, modals, dropdowns, and similar overlays
-are typical candidates.
-
-## Usage
-
-### Default — mount into `document.body`
-
-```tsx
-import { Portal } from "@primitiv-ui/react";
-
-<Portal>
-  <div role="dialog" aria-modal="true">
-    Modal content rendered directly in document.body
-  </div>
-</Portal>
-```
-
-### Custom container
-
-Pass any `HTMLElement` as `container` to mount into a specific node instead of
-`document.body`:
-
-```tsx
-const overlayRoot = document.getElementById("overlay-root");
-
-<Portal container={overlayRoot}>
-  <div role="tooltip">Tooltip content</div>
-</Portal>
-```
-
-### Composing with conditional rendering
-
-`Portal` always renders when mounted. Control visibility by conditionally
-rendering the `Portal` itself, or by wrapping it with open/closed logic:
-
-```tsx
-{isOpen && (
-  <Portal>
-    <div role="dialog">...</div>
-  </Portal>
-)}
-```
-
-For CSS-driven exit animations, keep the portal in the DOM and drive styles
-from a `data-state` attribute:
-
-```tsx
-<Portal>
-  <div data-state={isOpen ? "open" : "closed"}>...</div>
-</Portal>
-```
-
-## Props
-
-| Prop        | Type          | Default          | Description                                          |
-| ----------- | ------------- | ---------------- | ---------------------------------------------------- |
-| `children`  | `ReactNode`   | —                | Content to render inside the portal                  |
-| `container` | `HTMLElement` | `document.body`  | DOM node to mount into                               |
-
-## Notes
-
-- `Portal` is a thin wrapper; it carries no state, context, or open/close
-  awareness of its own. Those concerns belong in the component that composes it.
-- `Modal.Portal` internally uses this component and adds open-state suppression
-  and `forceMount` on top.

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

@@ -1,22 +0,0 @@
-import { render, screen } from "@testing-library/react";
-
-import { Portal } from "../Portal";
-
-describe("Portal basic rendering", () => {
-  it("renders children into document.body", () => {
-    // Arrange & Act
-    render(
-      <Portal>
-        <p>Portal content</p>
-      </Portal>,
-    );
-
-    // Assert
-    expect(screen.getByText("Portal content")).toBeInTheDocument();
-  });
-
-  it('sets displayName to "Portal" for React DevTools and stack traces', () => {
-    // Assert — an empty displayName would render it as an anonymous component.
-    expect(Portal.displayName).toBe("Portal");
-  });
-});

package/src/Portal/index.ts

@@ -1,2 +0,0 @@
-export * from "./Portal";
-export * from "./types";

package/src/Portal/types.ts

@@ -1,15 +0,0 @@
-import { ReactNode } from "react";
-
-/**
- * Props for {@link Portal} — the `children` to teleport and an optional
- * `container` to render into (defaults to `document.body`).
- */
-export type PortalProps = {
-  /** Content to render inside the portal. Appears directly inside `container`
-   * with no wrapping host element added by `Portal` itself. */
-  children?: ReactNode;
-  /** DOM node to mount the portal children into. When omitted, children are
-   * mounted into `document.body`.
-   * @default document.body */
-  container?: HTMLElement;
-};

package/src/Progress/Progress.tsx

@@ -1,215 +0,0 @@
-import { useMemo } from "react";
-import type { ReactElement } from "react";
-
-import { Slot } from "../Slot/index.ts";
-
-import { ProgressContext } from "./ProgressContext";
-import { useProgressContext, useProgressRoot } from "./hooks/index.ts";
-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.
- *
- * **Validation.** `max` must be a positive, finite number and `value` (when
- * not `null`) must be finite and within `0..max`; either violation throws a
- * descriptive error during render so bad inputs surface early in development.
- *
- * **`asChild` composition.** Pass `asChild` to render the consumer's own
- * element as the root instead of the native `<div>`, merging the ARIA and
- * `data-*` hooks onto it via the {@link Slot} pattern.
- *
- * @extends HTMLDivElement
- *
- * @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>
- * ```
- *
- * @example Custom value label
- * ```tsx
- * <Progress.Root
- *   value={3}
- *   max={5}
- *   getValueLabel={(v, m) => `Step ${v} of ${m}`}
- *   aria-label="Setup progress"
- * >
- *   <Progress.Indicator />
- * </Progress.Root>
- * ```
- */
-export function ProgressRoot({
-  value,
-  max,
-  getValueLabel = defaultGetValueLabel,
-  asChild = false,
-  children,
-  ...rest
-}: ProgressRootProps): ReactElement {
-  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>
-  );
-}
-
-// Runtime-dead: the compound alias below (same object via Object.assign)
-// overwrites this to "Progress" at load, so the value is never observable. The
-// assignment stays because it declares `displayName` on `typeof ProgressRoot`,
-// which TProgressCompound extends.
-// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
-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.
- *
- * @extends HTMLDivElement
- *
- * @example
- * ```tsx
- * <Progress.Root value={75} aria-label="Upload progress">
- *   <Progress.Indicator />
- * </Progress.Root>
- * ```
- *
- * @throws if rendered outside a `Progress.Root`.
- */
-export function ProgressIndicator({
-  asChild = false,
-  children,
-  ...rest
-}: ProgressIndicatorProps): ReactElement {
-  const { value, max, state } = useProgressContext();
-  const indicatorProps = {
-    ...rest,
-    "data-state": state,
-    // Stryker disable next-line ConditionalExpression: `value` is null only
-    // while indeterminate, and React renders null and undefined attributes
-    // identically (both omitted), so the guarded (`undefined`) and unguarded
-    // (`null`) forms produce the same DOM — a provably-equivalent mutant.
-    "data-value": value === null ? undefined : value,
-    "data-max": max,
-  };
-  if (asChild) {
-    return <Slot {...indicatorProps}>{children}</Slot>;
-  }
-  return <div {...indicatorProps}>{children}</div>;
-}
-
-/** @internal */
-ProgressIndicator.displayName = "ProgressIndicator";
-
-/** Type of the {@link Progress} compound: the root callable plus its attached sub-components. */
-export 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,
-});
-
-/** @internal */
-ProgressCompound.displayName = "Progress";
-
-export { ProgressCompound as Progress };

package/src/Progress/ProgressContext.ts

@@ -1,27 +0,0 @@
-import type { Context } from "react";
-import { createStrictContext } from "../utils/index.ts";
-
-import { ProgressState } from "./types";
-
-/**
- * Context value published by {@link Progress.Root} and consumed by
- * {@link Progress.Indicator} — the current `value` (or `null` while
- * indeterminate), the `max`, and the derived loading `state`.
- */
-export type ProgressContextValue = {
-  value: number | null;
-  max: number;
-  state: ProgressState;
-};
-
-const progressContextPair = createStrictContext<ProgressContextValue>(
-  "Progress.Indicator must be rendered inside a <Progress.Root>.",
-  "ProgressContext",
-);
-
-/** React context carrying the {@link ProgressContextValue}; `null` when no provider is present. */
-export const ProgressContext: Context<ProgressContextValue | null> =
-  progressContextPair[0];
-/** Reads the {@link ProgressContextValue}; throws if used outside a {@link Progress.Root}. */
-export const useProgressContext: () => ProgressContextValue =
-  progressContextPair[1];

package/src/Progress/README.md

@@ -1,112 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-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

@@ -1,75 +0,0 @@
-import { render, screen } from "@testing-library/react";
-
-import { Progress } from "../Progress";
-import { ProgressContext } from "../ProgressContext";
-
-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("aria-valuetext");
-    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");
-  });
-
-  it("sets a displayName on the compound, indicator, and context", () => {
-    // Assert — empty displayNames would render each as anonymous in DevTools.
-    // Root aliases the compound (Object.assign), so its name is "Progress".
-    expect(Progress.displayName).toBe("Progress");
-    expect(Progress.Indicator.displayName).toBe("ProgressIndicator");
-    expect(ProgressContext.displayName).toBe("ProgressContext");
-  });
-});

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

@@ -1,40 +0,0 @@
-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

@@ -1,7 +0,0 @@
-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;