@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/Portal/Portal.js

@@ -0,0 +1,92 @@
+"use client";
+import { useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+/**
+ * Teleports its children into a DOM node outside the current React subtree
+ * using React's `createPortal`. Renders no host element of its own — the
+ * children appear directly inside the target `container`.
+ *
+ * Use `Portal` whenever a subtree must escape its ancestor's stacking context,
+ * overflow clipping, or z-index hierarchy — tooltips, modals, dropdowns, and
+ * similar overlays are the typical cases. `Portal` carries no state, context,
+ * or open/close awareness; those concerns belong in the composing component
+ * (see `Modal.Portal`, which layers open-state suppression and `forceMount` on
+ * top of this primitive).
+ *
+ * **Conditional rendering.** `Portal` always mounts when rendered. To control
+ * visibility, conditionally render the `Portal` itself, or manage show/hide
+ * logic in the composing component:
+ *
+ * ```tsx
+ * {isOpen && (
+ *   <Portal>
+ *     <div role="dialog">...</div>
+ *   </Portal>
+ * )}
+ * ```
+ *
+ * For CSS-driven exit animations, keep the portal mounted and drive styles
+ * through a `data-state` attribute on its child:
+ *
+ * ```tsx
+ * <Portal>
+ *   <div data-state={isOpen ? "open" : "closed"}>...</div>
+ * </Portal>
+ * ```
+ *
+ * **Server rendering.** There is no `document` on the server, so `Portal`
+ * renders nothing there — and, to match the server HTML, during hydration too —
+ * then portals its children once mounted in the browser. That matters for a
+ * force-mounted overlay (`Modal.Portal` / `Drawer.Portal` with `forceMount`),
+ * which renders its `Portal` while closed and so reaches it on the server.
+ *
+ * **Ref forwarding.** `Portal` does not forward a ref (there is no host
+ * element to attach one to). Attach `ref` directly to the child element
+ * rendered inside the portal.
+ *
+ * @example Mount into document.body (default)
+ * ```tsx
+ * import { Portal } from "@primitiv-ui/react";
+ *
+ * <Portal>
+ *   <div role="dialog" aria-modal="true">
+ *     Modal content rendered directly in document.body
+ *   </div>
+ * </Portal>
+ * ```
+ *
+ * @example Mount into a custom container
+ * ```tsx
+ * const overlayRoot = document.getElementById("overlay-root");
+ *
+ * <Portal container={overlayRoot}>
+ *   <div role="tooltip">Tooltip content</div>
+ * </Portal>
+ * ```
+ */
+function Portal({ children, container }) {
+    // The default target, or `null` where there is no document — the server and,
+    // so its HTML matches, the hydrating render. The snapshot IS the target, not a
+    // mounted flag, so a snapshot that went missing would portal into nothing and
+    // fail loudly rather than quietly read as "not mounted".
+    const target = useSyncExternalStore(subscribe, documentBody, noDocument);
+    return target === null ? null : createPortal(children, container ?? target);
+}
+/** The target never changes once known, so there is nothing to subscribe to. */
+// Stryker disable next-line BlockStatement: equivalent — emptied, this returns
+// `undefined` instead of a no-op unsubscribe, and React treats an `undefined`
+// effect cleanup exactly as a no-op one; there is no store to leave.
+function subscribe() {
+    return () => { };
+}
+/** The browser snapshot: the document body every portal defaults into. */
+function documentBody() {
+    return document.body;
+}
+/** The server (and hydration) snapshot: no document, so nothing to portal into. */
+function noDocument() {
+    return null;
+}
+/** @internal */
+Portal.displayName = "Portal";
+export { Portal };

package/dist/Portal/index.d.ts

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

package/dist/Portal/index.js

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

package/dist/Portal/types.d.ts

@@ -0,0 +1,14 @@
+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/dist/Portal/types.js

@@ -0,0 +1 @@
+export {};

package/dist/Progress/Progress.d.ts

@@ -0,0 +1,126 @@
+import type { ReactElement } from "react";
+import { ProgressIndicatorProps, ProgressRootProps } from "./types.js";
+/**
+ * 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 declare function ProgressRoot({ value, max, getValueLabel, asChild, children, ...rest }: ProgressRootProps): ReactElement;
+export declare namespace ProgressRoot {
+    var displayName: string;
+}
+/**
+ * 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 declare function ProgressIndicator({ asChild, children, ...rest }: ProgressIndicatorProps): ReactElement;
+export declare namespace ProgressIndicator {
+    var displayName: string;
+}
+/** 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.
+ */
+declare const ProgressCompound: TProgressCompound;
+export { ProgressCompound as Progress };

package/dist/Progress/Progress.js

@@ -0,0 +1,172 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { Slot } from "../Slot/index.js";
+import { ProgressContext } from "./ProgressContext.js";
+import { useProgressContext, useProgressRoot } from "./hooks/index.js";
+function defaultGetValueLabel(value, max) {
+    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 }) {
+    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",
+        "aria-valuemin": 0,
+        "aria-valuemax": resolved.max,
+        "data-state": state,
+        "data-max": resolved.max,
+        ...valueProps,
+    };
+    return (_jsx(ProgressContext.Provider, { value: contextValue, children: asChild ? (_jsx(Slot, { ...rootProps, children: children })) : (_jsx("div", { ...rootProps, children: children })) }));
+}
+// 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 }) {
+    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 _jsx(Slot, { ...indicatorProps, children: children });
+    }
+    return _jsx("div", { ...indicatorProps, children: children });
+}
+/** @internal */
+ProgressIndicator.displayName = "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 = Object.assign(ProgressRoot, {
+    Root: ProgressRoot,
+    Indicator: ProgressIndicator,
+});
+/** @internal */
+ProgressCompound.displayName = "Progress";
+export { ProgressCompound as Progress };

package/dist/Progress/ProgressContext.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from "react";
+import { ProgressState } from "./types.js";
+/**
+ * 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;
+};
+/** React context carrying the {@link ProgressContextValue}; `null` when no provider is present. */
+export declare const ProgressContext: Context<ProgressContextValue | null>;
+/** Reads the {@link ProgressContextValue}; throws if used outside a {@link Progress.Root}. */
+export declare const useProgressContext: () => ProgressContextValue;

package/dist/Progress/ProgressContext.js

@@ -0,0 +1,7 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+const progressContextPair = createStrictContext("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 = progressContextPair[0];
+/** Reads the {@link ProgressContextValue}; throws if used outside a {@link Progress.Root}. */
+export const useProgressContext = progressContextPair[1];

package/dist/Progress/hooks/index.d.ts

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

package/dist/Progress/hooks/index.js

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

package/dist/Progress/hooks/useProgressContext.d.ts

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

package/dist/Progress/hooks/useProgressContext.js

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

package/dist/Progress/hooks/useProgressRoot.d.ts

@@ -0,0 +1,17 @@
+import { ProgressState } from "../types.js";
+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 declare function useProgressRoot({ value, max, }: UseProgressRootArgs): UseProgressRootResult;
+export {};

package/dist/Progress/hooks/useProgressRoot.js

@@ -0,0 +1,22 @@
+"use client";
+const DEFAULT_MAX = 100;
+/**
+ * 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, }) {
+    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 = isIndeterminate
+        ? "indeterminate"
+        : value >= max
+            ? "complete"
+            : "loading";
+    return { value: isIndeterminate ? null : value, max, state };
+}

package/dist/Progress/index.d.ts

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

package/dist/Progress/index.js

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

package/dist/Progress/types.d.ts

@@ -0,0 +1,53 @@
+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. Drives the
+     * resolved {@link ProgressState} and the `aria-valuenow` / `data-value`
+     * hooks. A non-`null` value outside `0..max` throws.
+     * @default null
+     */
+    value?: number | null;
+    /**
+     * Upper bound of `value`. Must be a positive, finite number, or Root throws
+     * during render.
+     * @default 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.
+     * @default (value, max) => `${Math.round((value / max) * 100)}%`
+     */
+    getValueLabel?: (value: number, max: number) => string;
+    /**
+     * Render the consumer's own element instead of the native `<div>`, merging
+     * the ARIA and `data-*` hooks onto it via {@link Slot}.
+     * @default false
+     */
+    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>`, merging
+     * the `data-*` hooks onto it via {@link Slot}.
+     * @default false
+     */
+    asChild?: boolean;
+};

package/dist/Progress/types.js

@@ -0,0 +1 @@
+export {};