@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/Slider/hooks/useSliderThumb.js

@@ -0,0 +1,57 @@
+"use client";
+import { useCallback, useEffect, useId, useRef } from "react";
+import { useSliderContext } from "../SliderContext.js";
+import { getKeyAction, getThumbStyle, snapToStep } from "../utils.js";
+export function useSliderThumb() {
+    const { values, min, max, step, orientation, dir, inverted, disabled, registerThumb, orderedThumbIds, setThumbValue, commit, } = useSliderContext();
+    const id = useId();
+    const ref = useRef(null);
+    useEffect(() => {
+        registerThumb(id, ref.current);
+        return () => registerThumb(id, null);
+    }, [id, registerThumb]);
+    const registeredIndex = orderedThumbIds.indexOf(id);
+    const index = registeredIndex === -1 ? 0 : registeredIndex;
+    const value = values[index];
+    const style = getThumbStyle(value, min, max, { orientation, dir, inverted });
+    const onKeyDown = useCallback((event) => {
+        if (disabled) {
+            return;
+        }
+        const action = getKeyAction(event.key, { orientation, dir, inverted });
+        if (action === null) {
+            return;
+        }
+        let target;
+        if (action === "min") {
+            target = min;
+        }
+        else if (action === "max") {
+            target = max;
+        }
+        else {
+            const isPageKey = event.key === "PageUp" || event.key === "PageDown";
+            const magnitude = isPageKey ? step * 10 : step;
+            const delta = action === "increase" ? magnitude : -magnitude;
+            target = snapToStep(value + delta, min, step);
+        }
+        event.preventDefault();
+        const next = setThumbValue(index, target);
+        if (next) {
+            commit(next);
+        }
+    }, [
+        value,
+        index,
+        min,
+        max,
+        step,
+        orientation,
+        dir,
+        inverted,
+        disabled,
+        setThumbValue,
+        commit,
+    ]);
+    return { ref, value, min, max, orientation, disabled, style, onKeyDown };
+}

package/dist/Slider/index.d.ts

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

package/dist/Slider/index.js

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

package/dist/Slider/types.d.ts

@@ -0,0 +1,194 @@
+import type { ComponentProps } from "react";
+/**
+ * Layout axis of the slider track. `"horizontal"` lays the track out along
+ * the x-axis and binds ArrowLeft/ArrowRight (plus ArrowUp/ArrowDown);
+ * `"vertical"` lays it out along the y-axis, positions thumbs from the
+ * bottom edge, and maps ArrowUp to *increase*.
+ */
+export type SliderOrientation = "horizontal" | "vertical";
+/**
+ * Reading direction of a **horizontal** slider, affecting which end of the
+ * track is the minimum and the arrow-key direction. `"rtl"` mirrors the axis
+ * so the value increases leftwards. Ignored on the vertical axis.
+ */
+export type SliderDirection = "ltr" | "rtl";
+/**
+ * Props common to both the controlled ({@link SliderRootControlledProps}) and
+ * uncontrolled ({@link SliderRootUncontrolledProps}) `Slider.Root` shapes:
+ * the range/step bounds, orientation, reading direction, form `name`, and the
+ * native `<span>` attributes.
+ *
+ * `defaultValue` and `dir` are `Omit`-ted from the inherited `<span>` props
+ * because both are redeclared with narrower slider-specific types — the
+ * native `defaultValue` is a string/number DOM attribute (replaced by the
+ * `number[]` value array) and the native `dir` is `string` (narrowed to
+ * {@link SliderDirection}). Omitting them keeps the narrowed types (and this
+ * JSDoc) visible to the docs-data extractor rather than the wider DOM ones.
+ */
+export type SliderRootSharedProps = Omit<ComponentProps<"span">, "defaultValue" | "dir"> & {
+    /**
+     * Lowest value the slider can take — the value at the track's start edge.
+     * Must be strictly less than {@link SliderRootSharedProps.max | `max`};
+     * `Slider.Root` throws during render otherwise.
+     * @default 0
+     */
+    min?: number;
+    /**
+     * Highest value the slider can take — the value at the track's end edge.
+     * Must be strictly greater than {@link SliderRootSharedProps.min | `min`};
+     * `Slider.Root` throws during render otherwise.
+     * @default 100
+     */
+    max?: number;
+    /**
+     * Granularity of the value: every thumb value snaps to a multiple of `step`
+     * anchored at `min`, and each arrow-key press moves by one `step` (Page
+     * Up/Down move by ten). Fractional steps (e.g. `0.1`) are snapped to the
+     * step's decimal precision. Must be greater than `0`; `Slider.Root` throws
+     * during render otherwise.
+     * @default 1
+     */
+    step?: number;
+    /**
+     * Minimum gap, expressed **in steps**, enforced between adjacent thumbs on a
+     * multi-thumb slider. The gap in value units is `minStepsBetweenThumbs *
+     * step`. A thumb is clamped so it can never come closer than this to its
+     * neighbours (and can never cross them). Has no effect on a single-thumb
+     * slider.
+     * @default 0
+     */
+    minStepsBetweenThumbs?: number;
+    /**
+     * Layout axis of the track; see {@link SliderOrientation}. Sets
+     * `data-orientation` and each thumb's `aria-orientation`, and selects which
+     * pointer axis and arrow keys drive the value.
+     * @default "horizontal"
+     */
+    orientation?: SliderOrientation;
+    /**
+     * Reading direction of a horizontal slider; see {@link SliderDirection}.
+     * Affects which end is the minimum, the arrow-key direction, pointer
+     * mapping, and the inline positioning styles. When omitted, it is inherited
+     * from the nearest {@link DirectionProvider}, falling back to `"ltr"` when
+     * there is no provider; an explicit prop always wins.
+     */
+    dir?: SliderDirection;
+    /**
+     * Reverse the direction the value increases along the axis. Combines with
+     * {@link SliderRootSharedProps.orientation | `orientation`} and
+     * {@link SliderRootSharedProps.dir | `dir`} to flip the pointer mapping,
+     * arrow keys, and the edge the thumb/range offset is anchored to.
+     * @default false
+     */
+    inverted?: boolean;
+    /**
+     * Disable all interaction. Every part receives `data-disabled=""`, thumbs
+     * leave the tab order and gain `aria-disabled="true"`, and both keyboard and
+     * pointer handlers become no-ops.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * When set, `Slider.Root` renders one hidden `<input>` per thumb carrying
+     * that thumb's value so the slider posts with a surrounding `<form>`. A
+     * multi-thumb slider suffixes the name with `[]` (e.g. `name="range"` →
+     * `range[]`); a single-thumb slider uses the bare name. When omitted, no
+     * hidden inputs are rendered.
+     */
+    name?: string;
+    /**
+     * Render the child element in place of the default `<span>` via the
+     * {@link Slot} pattern, merging `Slider.Root`'s `dir`, `data-*` hooks,
+     * pointer handler, and ref onto it.
+     * @default false
+     */
+    asChild?: boolean;
+};
+/**
+ * Uncontrolled variant of {@link SliderRootProps}: the component owns the
+ * value array internally. Seed it with `defaultValue` (or omit it for a
+ * single thumb seeded at `min`); `value` is forbidden.
+ */
+export type SliderRootUncontrolledProps = SliderRootSharedProps & {
+    /**
+     * The value array on first render — one number per
+     * {@link SliderThumb | `Slider.Thumb`}, in order (`[value]` for a single
+     * thumb, `[low, high]` for a range). After mount the component owns the
+     * value. Defaults to `[min]` when omitted.
+     */
+    defaultValue?: number[];
+    /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
+    value?: never;
+    /**
+     * Called with the full next value array on every change (each arrow-key
+     * press and every pointer increment during a drag). Optional in
+     * uncontrolled mode.
+     */
+    onValueChange?: (value: number[]) => void;
+    /**
+     * Called **once** with the settled value array when an interaction ends — a
+     * pointer release, or a completed keyboard press. Use it to persist only the
+     * final value rather than every intermediate step.
+     */
+    onValueCommit?: (value: number[]) => void;
+};
+/**
+ * Controlled variant of {@link SliderRootProps}: the parent owns the value
+ * array via `value` and is expected to keep it in sync through
+ * `onValueChange`. `defaultValue` is forbidden.
+ */
+export type SliderRootControlledProps = SliderRootSharedProps & {
+    /** Forbidden in controlled mode — use `value` instead. */
+    defaultValue?: never;
+    /**
+     * The current value array — one number per
+     * {@link SliderThumb | `Slider.Thumb`}, in order (`[value]` for a single
+     * thumb, `[low, high]` for a range). Must be kept in sync by the parent via
+     * `onValueChange`.
+     */
+    value: number[];
+    /**
+     * Called with the full next value array on every change (each arrow-key
+     * press and every pointer increment during a drag). Update `value` from it
+     * to keep the slider in sync.
+     */
+    onValueChange?: (value: number[]) => void;
+    /**
+     * Called **once** with the settled value array when an interaction ends — a
+     * pointer release, or a completed keyboard press. Use it to persist only the
+     * final value rather than every intermediate step.
+     */
+    onValueCommit?: (value: number[]) => void;
+};
+/** Props for {@link SliderRoot | `Slider.Root`} — the discriminated union of controlled ({@link SliderRootControlledProps}) and uncontrolled ({@link SliderRootUncontrolledProps}) modes; only one shape is accepted by TypeScript at a time. */
+export type SliderRootProps = SliderRootUncontrolledProps | SliderRootControlledProps;
+/** Props for {@link SliderTrack | `Slider.Track`} — the full-length rail the thumbs travel along; all native `<span>` attributes plus `asChild`. */
+export type SliderTrackProps = ComponentProps<"span"> & {
+    /**
+     * Render the child element in place of the default `<span>` via the
+     * {@link Slot} pattern, merging the `data-orientation` / `data-disabled`
+     * hooks onto it.
+     * @default false
+     */
+    asChild?: boolean;
+};
+/** Props for {@link SliderRange | `Slider.Range`} — the filled segment between the lowest and highest thumb (or from the track start to the single thumb); all native `<span>` attributes plus `asChild`. */
+export type SliderRangeProps = ComponentProps<"span"> & {
+    /**
+     * Render the child element in place of the default `<span>` via the
+     * {@link Slot} pattern, merging the `data-orientation` / `data-disabled`
+     * hooks and the computed inline positioning `style` onto it.
+     * @default false
+     */
+    asChild?: boolean;
+};
+/** Props for {@link SliderThumb | `Slider.Thumb`} — a draggable, focusable handle; render one per entry in the value array. All native `<span>` attributes plus `asChild`. */
+export type SliderThumbProps = ComponentProps<"span"> & {
+    /**
+     * Render the child element in place of the default `<span>` via the
+     * {@link Slot} pattern, merging the `role="slider"` semantics, `aria-value*`
+     * attributes, keyboard handler, positioning `style`, and ref onto it.
+     * @default false
+     */
+    asChild?: boolean;
+};

package/dist/Slider/types.js

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

package/dist/Slider/utils.d.ts

@@ -0,0 +1,48 @@
+import type { CSSProperties } from "react";
+import type { SliderDirection, SliderOrientation } from "./types.js";
+type Edge = "left" | "right" | "top" | "bottom";
+export type SliderAxisArgs = {
+    orientation: SliderOrientation;
+    dir: SliderDirection;
+    inverted: boolean;
+};
+export type SliderKeyAction = "increase" | "decrease" | "min" | "max";
+/** Constrain `value` to the inclusive `[min, max]` range. */
+export declare function clamp(value: number, min: number, max: number): number;
+/** Map a value onto its 0–100 position within the `[min, max]` range. */
+export declare function valueToPercent(value: number, min: number, max: number): number;
+/** Round a value to the nearest step, anchored at `min`, at step precision. */
+export declare function snapToStep(value: number, min: number, step: number): number;
+/**
+ * Resolve which physical edge a thumb's offset is anchored to, accounting
+ * for orientation, reading direction, and the `inverted` flag.
+ */
+export declare function getOffsetEdge({ orientation, dir, inverted }: SliderAxisArgs): Edge;
+/** Inline style positioning a thumb at its value along the track. */
+export declare function getThumbStyle(value: number, min: number, max: number, edgeArgs: SliderAxisArgs): CSSProperties;
+/**
+ * Inline style stretching the range between the lowest and highest thumb
+ * (or from the track start to the single thumb).
+ */
+export declare function getRangeStyle(values: number[], min: number, max: number, edgeArgs: SliderAxisArgs): CSSProperties;
+type PointerValueArgs = SliderAxisArgs & {
+    min: number;
+    max: number;
+    step: number;
+};
+/** Resolve the value at a pointer's position on the track. */
+export declare function getPointerValue(clientX: number, clientY: number, rect: {
+    left: number;
+    width: number;
+    bottom: number;
+    height: number;
+}, { min, max, step, orientation, dir, inverted }: PointerValueArgs): number;
+/**
+ * Map a key press to an abstract value action, accounting for orientation,
+ * reading direction, and the `inverted` flag. Returns `null` for keys the
+ * slider does not handle.
+ */
+export declare function getKeyAction(key: string, { orientation, dir, inverted }: SliderAxisArgs): SliderKeyAction | null;
+/** Index of the thumb whose value sits nearest to `value` (ties favour the first). */
+export declare function getClosestThumbIndex(value: number, values: number[]): number;
+export {};

package/dist/Slider/utils.js

@@ -0,0 +1,105 @@
+"use client";
+const OPPOSITE_EDGE = {
+    left: "right",
+    right: "left",
+    top: "bottom",
+    bottom: "top",
+};
+/** Constrain `value` to the inclusive `[min, max]` range. */
+export function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/** Map a value onto its 0–100 position within the `[min, max]` range. */
+export function valueToPercent(value, min, max) {
+    return clamp(((value - min) / (max - min)) * 100, 0, 100);
+}
+/** Round a value to the nearest step, anchored at `min`, at step precision. */
+export function snapToStep(value, min, step) {
+    const snapped = min + Math.round((value - min) / step) * step;
+    const decimals = (String(step).split(".")[1] ?? "").length;
+    return Number(snapped.toFixed(decimals));
+}
+/**
+ * Resolve which physical edge a thumb's offset is anchored to, accounting
+ * for orientation, reading direction, and the `inverted` flag.
+ */
+export function getOffsetEdge({ orientation, dir, inverted }) {
+    const base = orientation === "vertical" ? "bottom" : dir === "rtl" ? "right" : "left";
+    return inverted ? OPPOSITE_EDGE[base] : base;
+}
+/** Inline style positioning a thumb at its value along the track. */
+export function getThumbStyle(value, min, max, edgeArgs) {
+    const edge = getOffsetEdge(edgeArgs);
+    return { position: "absolute", [edge]: `${valueToPercent(value, min, max)}%` };
+}
+/**
+ * Inline style stretching the range between the lowest and highest thumb
+ * (or from the track start to the single thumb).
+ */
+export function getRangeStyle(values, min, max, edgeArgs) {
+    const edge = getOffsetEdge(edgeArgs);
+    const percents = values.map((value) => valueToPercent(value, min, max));
+    const startPercent = values.length > 1 ? Math.min(...percents) : 0;
+    const endPercent = Math.max(...percents);
+    return {
+        position: "absolute",
+        [edge]: `${startPercent}%`,
+        [OPPOSITE_EDGE[edge]]: `${100 - endPercent}%`,
+    };
+}
+/** Resolve the value at a pointer's position on the track. */
+export function getPointerValue(clientX, clientY, rect, { min, max, step, orientation, dir, inverted }) {
+    let percent = orientation === "vertical"
+        ? (rect.bottom - clientY) / rect.height
+        : (clientX - rect.left) / rect.width;
+    const reversed = orientation === "vertical" ? inverted : (dir === "ltr") === inverted;
+    if (reversed) {
+        percent = 1 - percent;
+    }
+    percent = clamp(percent, 0, 1);
+    return clamp(snapToStep(min + percent * (max - min), min, step), min, max);
+}
+/**
+ * Map a key press to an abstract value action, accounting for orientation,
+ * reading direction, and the `inverted` flag. Returns `null` for keys the
+ * slider does not handle.
+ */
+export function getKeyAction(key, { orientation, dir, inverted }) {
+    switch (key) {
+        case "Home":
+            return "min";
+        case "End":
+            return "max";
+        case "PageUp":
+            return "increase";
+        case "PageDown":
+            return "decrease";
+        case "ArrowUp":
+        case "ArrowDown": {
+            const upIncreases = orientation === "vertical" ? !inverted : true;
+            const increases = key === "ArrowUp" ? upIncreases : !upIncreases;
+            return increases ? "increase" : "decrease";
+        }
+        case "ArrowRight":
+        case "ArrowLeft": {
+            const rightIncreases = orientation === "vertical" ? true : (dir === "ltr") !== inverted;
+            const increases = key === "ArrowRight" ? rightIncreases : !rightIncreases;
+            return increases ? "increase" : "decrease";
+        }
+        default:
+            return null;
+    }
+}
+/** Index of the thumb whose value sits nearest to `value` (ties favour the first). */
+export function getClosestThumbIndex(value, values) {
+    let closestIndex = 0;
+    let smallestDistance = Infinity;
+    values.forEach((thumbValue, index) => {
+        const distance = Math.abs(thumbValue - value);
+        if (distance < smallestDistance) {
+            smallestDistance = distance;
+            closestIndex = index;
+        }
+    });
+    return closestIndex;
+}

package/dist/Slot/Slot.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Slot — a React composition utility following the asChild pattern.
+ *
+ * When a component renders `<Slot {...ownProps}>{child}</Slot>`, the child
+ * element is cloned with ownProps merged in:
+ * - Event handlers are **composed** (child's handler runs first, then Slot's).
+ * - `style` objects are shallow-merged (child wins on collisions).
+ * - `className` strings are concatenated.
+ * - All other props default to the child's value, with Slot providing the
+ *   fallback when the child doesn't specify one.
+ * - Refs from both sides are composed via {@link composeRefs}.
+ *
+ * This file is intentionally self-contained — no external dependencies
+ * beyond React itself.
+ */
+import { type ForwardRefExoticComponent, type PropsWithoutRef, type RefAttributes } from "react";
+import { SlotProps } from "./types.js";
+import { PossibleRef } from "../types.js";
+/**
+ * Combines multiple refs into a single callback ref that sets all of them
+ * simultaneously. Handles function refs, object refs (`{ current }`), and
+ * `undefined` — any of which may be mixed freely, in any order, and any
+ * number of them.
+ *
+ * Used throughout the headless components whenever a sub-component owns an
+ * internal ref (for measuring, focus management, roving-tabindex, etc.)
+ * *and* needs to forward the consumer's own `ref` to the same DOM node —
+ * two refs, one element, one callback ref that satisfies both. `Slot`
+ * itself uses `composeRefs` internally to merge its `forwardedRef` with the
+ * child element's own ref (see {@link Slot}).
+ *
+ * @example Compose an internal ref with a consumer-supplied external ref:
+ * ```tsx
+ * const internalRef = useRef<HTMLButtonElement>(null);
+ * const composedRef = externalRef
+ *   ? composeRefs(internalRef, externalRef)
+ *   : internalRef;
+ *
+ * return <button ref={composedRef} />;
+ * ```
+ */
+export declare function composeRefs<T>(...refs: PossibleRef<T>[]): (node: T) => void;
+/**
+ * Renders its single child element with the Slot's own props merged in.
+ *
+ * `Slot` is the composition primitive behind every `asChild` prop in this
+ * library (`Button`, `Tabs.Trigger`, `Select.Root`, `Breadcrumb.Link`, and
+ * more). A component that normally renders its own DOM element (say,
+ * `<button>`) can instead delegate rendering to a single consumer-supplied
+ * element — typically a routing library's `<Link>` or a custom styled
+ * element — while preserving all of its own behaviour: ARIA attributes,
+ * data attributes, event handlers, and `ref` all still land on the
+ * rendered DOM node, just not the node `Slot` itself would have created.
+ * The pattern avoids an extra wrapper element in the DOM, which matters for
+ * layout (no unwanted `<button><a>...</a></button>` nesting) and for CSS
+ * selectors that expect a single element.
+ *
+ * **Usage shape** — every component using `Slot` follows the same
+ * branch:
+ *
+ * ```tsx
+ * if (asChild) {
+ *   return <Slot {...ownProps}>{children}</Slot>;
+ * }
+ * return <button {...ownProps}>{children}</button>;
+ * ```
+ *
+ * `ownProps` is the exact same object passed to both branches — `Slot`'s
+ * job is only to change *where* those props land, never to change what
+ * they are.
+ *
+ * **Prop-merging rules** (`Slot`'s own props are the "slot" side, the
+ * single child's own props are the "child" side):
+ * - **Event handlers** (any prop matching `/^on[A-Z]/`) compose — the
+ *   **child's** handler fires first, then the **slot's**. This is the
+ *   opposite composition direction, and a different merge strategy, from
+ *   the standalone {@link composeEventHandlers} helper (their-handler-first
+ *   with a `preventDefault()` veto) — the two are unrelated mechanisms
+ *   that happen to solve adjacent problems. `Slot`'s handlers always both
+ *   run; there is no opt-out.
+ * - **`style`** is shallow-merged — the child's style object wins on key
+ *   collisions, so a consumer's inline `style` can override individual
+ *   properties Slot would otherwise set.
+ * - **`className`** strings are concatenated (`"slotClass childClass"`),
+ *   so both the component's own class hooks and the consumer's class
+ *   survive.
+ * - **All other props** default to the child's value; Slot's value is only
+ *   used as a fallback when the child doesn't specify that prop at all
+ *   (key absent, or explicitly `undefined`).
+ * - **Refs** from both sides are composed via {@link composeRefs}, so
+ *   neither the component's internal ref nor the consumer's own ref on the
+ *   child element is lost.
+ *
+ * **Constraints.** Exactly one React element child is required — `Slot`
+ * throws `"Slot requires exactly one React element child."` for zero
+ * children or a non-element child (e.g. a plain string). The child must
+ * also accept a `ref` (a DOM element or a `forwardRef` component); passing
+ * a plain function component as the child silently drops the ref.
+ *
+ * **React version compatibility.** Slot reads the child's own ref from
+ * `element.props.ref` (React 19+) with a fallback to `element.ref`
+ * (React ≤18) so both runtime versions compose refs correctly.
+ *
+ * @extends HTMLElement
+ *
+ * @example Basic `asChild` branch inside a component
+ * ```tsx
+ * // Inside a component that normally renders <button>:
+ * if (asChild) {
+ *   return <Slot {...buttonProps}>{children}</Slot>;
+ * }
+ * return <button {...buttonProps}>{children}</button>;
+ * ```
+ *
+ * @example Consumer rendering a router link in place of the default element
+ * ```tsx
+ * <Button asChild onClick={trackClick}>
+ *   <RouterLink to="/settings" className="settings-link">
+ *     Settings
+ *   </RouterLink>
+ * </Button>
+ * // Rendered DOM: a single <a class="...settings-link"> — trackClick and the
+ * // link's own onClick both fire; no wrapping <button>.
+ * ```
+ */
+export declare const Slot: ForwardRefExoticComponent<PropsWithoutRef<SlotProps> & RefAttributes<HTMLElement>>;