@primitiv-ui/react 0.1.0 → 0.1.2

package/src/RadioGroup/__tests__/RadioGroup.reading-direction.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { DirectionProvider } from "../../DirectionProvider";
+import { DirectionProvider } from "../../DirectionProvider/index.ts";
 import { RadioGroup } from "../RadioGroup";
 
 describe("RadioGroup reading direction", () => {

package/src/RadioGroup/hooks/useRadioGroupRoot.ts

@@ -1,6 +1,6 @@
 import { useCallback, useMemo } from "react";
 
-import { useCollection, useControllableState } from "../../hooks";
+import { useCollection, useControllableState } from "../../hooks/index.ts";
 
 type UseRadioGroupRootArgs = {
   defaultValue?: string;

package/src/RadioGroup/index.ts

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

package/src/RadioGroup/types.ts

@@ -10,7 +10,12 @@ export type RadioGroupOrientation = "horizontal" | "vertical" | "both";
 /** Reading direction — swaps the horizontal arrow pair when `"rtl"`. */
 export type RadioGroupReadingDirection = "ltr" | "rtl";
 
-type RadioGroupRootBaseProps = Omit<ComponentProps<"div">, "role"> & {
+/**
+ * Shared base for both {@link RadioGroupRootProps} variants — the native
+ * `<div>` attributes (minus `role`) plus the `asChild` escape hatch,
+ * orientation, reading direction, and a typed `ref`.
+ */
+export type RadioGroupRootBaseProps = Omit<ComponentProps<"div">, "role"> & {
   children?: ReactNode;
   ref?: Ref<HTMLDivElement>;
   asChild?: boolean;
@@ -18,22 +23,43 @@ type RadioGroupRootBaseProps = Omit<ComponentProps<"div">, "role"> & {
   dir?: RadioGroupReadingDirection;
 };
 
-type RadioGroupRootUncontrolledProps = RadioGroupRootBaseProps & {
+/**
+ * Uncontrolled variant of {@link RadioGroupRootProps}: the component owns
+ * the selected value. Pass `defaultValue` (or omit it); `onValueChange` is
+ * optional and `value` is forbidden.
+ */
+export type RadioGroupRootUncontrolledProps = RadioGroupRootBaseProps & {
   defaultValue?: string;
   value?: never;
   onValueChange?: (value: string) => void;
 };
 
-type RadioGroupRootControlledProps = RadioGroupRootBaseProps & {
+/**
+ * Controlled variant of {@link RadioGroupRootProps}: the parent owns the
+ * selected value. Pass `value` and `onValueChange` together; `defaultValue`
+ * is forbidden.
+ */
+export type RadioGroupRootControlledProps = RadioGroupRootBaseProps & {
   defaultValue?: never;
   value: string;
   onValueChange: (value: string) => void;
 };
 
+/**
+ * Props for {@link RadioGroup.Root}. A discriminated union of
+ * {@link RadioGroupRootUncontrolledProps} and
+ * {@link RadioGroupRootControlledProps}, so TypeScript accepts exactly one
+ * state mode.
+ */
 export type RadioGroupRootProps =
   | RadioGroupRootUncontrolledProps
   | RadioGroupRootControlledProps;
 
+/**
+ * Props for {@link RadioGroup.Item} — the radio button. `value` identifies
+ * the option; all native `<button>` attributes (minus the component-owned
+ * ones) plus the `asChild` escape hatch and a typed `ref` are passed through.
+ */
 export type RadioGroupItemProps = Omit<
   ComponentProps<"button">,
   "type" | "role" | "aria-checked" | "value"
@@ -44,6 +70,11 @@ export type RadioGroupItemProps = Omit<
   asChild?: boolean;
 };
 
+/**
+ * Props for {@link RadioGroup.Indicator} — all `<span>` attributes plus
+ * `forceMount` (keep mounted while unselected for exit animations) and the
+ * `asChild` escape hatch.
+ */
 export type RadioGroupIndicatorProps = ComponentProps<"span"> & {
   children?: ReactNode;
   forceMount?: boolean;

package/src/Select/Select.tsx

@@ -1,7 +1,8 @@
 import { ChangeEvent, Children, isValidElement, ReactNode } from "react";
+import type { ReactElement } from "react";
 
-import { useFieldProps } from "../Field/hooks";
-import { Slot } from "../Slot";
+import { useFieldProps } from "../Field/hooks/index.ts";
+import { Slot } from "../Slot/index.ts";
 
 import {
   SelectGroupProps,
@@ -51,7 +52,7 @@ function hasPlaceholderChild(children: ReactNode): boolean {
  * ids first, then field-supplied description / error ids). Outside a
  * `<Field.Root>`, behaviour is unchanged.
  */
-function SelectRoot({
+export function SelectRoot({
   children,
   asChild = false,
   onChange,
@@ -59,7 +60,7 @@ function SelectRoot({
   value,
   defaultValue,
   ...consumer
-}: SelectRootProps) {
+}: SelectRootProps): ReactElement {
   const merged = useFieldProps(consumer);
 
   const handleChange = (event: ChangeEvent<HTMLSelectElement>) => {
@@ -95,6 +96,7 @@ function SelectRoot({
   return <select {...rootProps}>{children}</select>;
 }
 
+/** @internal */
 SelectRoot.displayName = "SelectRoot";
 
 /**
@@ -104,10 +106,14 @@ SelectRoot.displayName = "SelectRoot";
  * Native `<option>` only renders text; rich content (icons, descriptions)
  * is not supported.
  */
-function SelectOption({ children, ...rest }: SelectOptionProps) {
+export function SelectOption({
+  children,
+  ...rest
+}: SelectOptionProps): ReactElement {
   return <option {...rest}>{children}</option>;
 }
 
+/** @internal */
 SelectOption.displayName = "SelectOption";
 
 /**
@@ -115,10 +121,14 @@ SelectOption.displayName = "SelectOption";
  * native `<optgroup>` element. The `label` is shown by the browser as a
  * non-selectable heading and is announced as the group's accessible name.
  */
-function SelectGroup({ children, ...rest }: SelectGroupProps) {
+export function SelectGroup({
+  children,
+  ...rest
+}: SelectGroupProps): ReactElement {
   return <optgroup {...rest}>{children}</optgroup>;
 }
 
+/** @internal */
 SelectGroup.displayName = "SelectGroup";
 
 /**
@@ -131,7 +141,10 @@ SelectGroup.displayName = "SelectGroup";
  * Pair with `required` on {@link Select.Root} to make the browser's
  * native form validation catch an unchosen value at submission.
  */
-function SelectPlaceholder({ children, ...rest }: SelectPlaceholderProps) {
+export function SelectPlaceholder({
+  children,
+  ...rest
+}: SelectPlaceholderProps): ReactElement {
   return (
     <option {...rest} value="" disabled hidden>
       {children}
@@ -139,9 +152,11 @@ function SelectPlaceholder({ children, ...rest }: SelectPlaceholderProps) {
   );
 }
 
+/** @internal */
 SelectPlaceholder.displayName = "SelectPlaceholder";
 
-type TSelectCompound = typeof SelectRoot & {
+/** Type of the {@link Select} compound: the root callable plus its attached sub-components. */
+export type TSelectCompound = typeof SelectRoot & {
   Root: typeof SelectRoot;
   Option: typeof SelectOption;
   Group: typeof SelectGroup;

package/src/Select/__tests__/Select.field-integration.test.tsx

@@ -1,6 +1,6 @@
 import { render, screen } from "@testing-library/react";
 
-import { Field } from "../../Field";
+import { Field } from "../../Field/index.ts";
 import { Select } from "../Select";
 
 function renderSelect(children?: React.ReactNode) {

package/src/Select/index.ts

@@ -1,2 +1,2 @@
-export { Select } from "./Select";
+export * from "./Select";
 export * from "./types";

package/src/Select/types.ts

@@ -1,6 +1,11 @@
 import { ChangeEventHandler, ComponentProps, ReactNode, Ref } from "react";
 
-type SelectRootBaseProps = Omit<
+/**
+ * Shared base for both {@link SelectRootProps} variants — the native
+ * `<select>` attributes (minus the state-owning ones), the `asChild`
+ * escape hatch, and the raw `onChange` passthrough.
+ */
+export type SelectRootBaseProps = Omit<
   ComponentProps<"select">,
   "value" | "defaultValue" | "multiple" | "onChange"
 > & {
@@ -22,13 +27,23 @@ type SelectRootBaseProps = Omit<
   asChild?: boolean;
 };
 
-type SelectRootUncontrolledProps = SelectRootBaseProps & {
+/**
+ * Uncontrolled variant of {@link SelectRootProps}: the browser owns the
+ * selection. Pass `defaultValue` (or omit it); `onValueChange` is optional
+ * and `value` is forbidden.
+ */
+export type SelectRootUncontrolledProps = SelectRootBaseProps & {
   defaultValue?: string;
   value?: never;
   onValueChange?: (value: string) => void;
 };
 
-type SelectRootControlledProps = SelectRootBaseProps & {
+/**
+ * Controlled variant of {@link SelectRootProps}: the parent owns the
+ * selection. Pass `value` and `onValueChange` together; `defaultValue` is
+ * forbidden.
+ */
+export type SelectRootControlledProps = SelectRootBaseProps & {
   defaultValue?: never;
   value: string;
   onValueChange: (value: string) => void;

package/src/SkipNav/SkipNav.tsx

@@ -1,3 +1,5 @@
+import type { ReactElement } from "react";
+
 import { SkipNavContentProps, SkipNavLinkProps } from "./types";
 
 const DEFAULT_CONTENT_ID = "primitiv-skip-nav";
@@ -34,7 +36,7 @@ function SkipNavLink({
   children,
   contentId = DEFAULT_CONTENT_ID,
   ...rest
-}: SkipNavLinkProps) {
+}: SkipNavLinkProps): ReactElement {
   return (
     <a href={`#${contentId}`} {...rest}>
       {children}
@@ -63,7 +65,10 @@ SkipNavLink.displayName = "SkipNavLink";
  * </SkipNav.Content>
  * ```
  */
-function SkipNavContent({ children, ...rest }: SkipNavContentProps) {
+function SkipNavContent({
+  children,
+  ...rest
+}: SkipNavContentProps): ReactElement {
   return (
     <div id={DEFAULT_CONTENT_ID} tabIndex={-1} {...rest}>
       {children}

package/src/SkipNav/__tests__/SkipNav.ids.test.tsx

@@ -1,4 +1,4 @@
-import { SkipNav } from "..";
+import { SkipNav } from "../index.ts";
 import { render, screen } from "@testing-library/react";
 
 describe("SkipNav id wiring", () => {

package/src/Slider/Slider.tsx

@@ -1,8 +1,14 @@
-import { useDirection } from "../DirectionProvider";
-import { Slot, composeEventHandlers, composeRefs } from "../Slot";
+import type { ReactElement } from "react";
+
+import { useDirection } from "../DirectionProvider/index.ts";
+import { Slot, composeEventHandlers, composeRefs } from "../Slot/index.ts";
 
 import { SliderContext } from "./SliderContext";
-import { useSliderContext, useSliderRoot, useSliderThumb } from "./hooks";
+import {
+  useSliderContext,
+  useSliderRoot,
+  useSliderThumb,
+} from "./hooks/index.ts";
 import type {
   SliderRangeProps,
   SliderRootProps,
@@ -68,7 +74,7 @@ import { getRangeStyle } from "./utils";
  * </Slider.Root>
  * ```
  */
-function SliderRoot({
+export function SliderRoot({
   min = 0,
   max = 100,
   step = 1,
@@ -87,7 +93,7 @@ function SliderRoot({
   ref,
   children,
   ...rest
-}: SliderRootProps) {
+}: SliderRootProps): ReactElement {
   const resolvedDir = dir ?? useDirection();
   const {
     contextValue,
@@ -136,6 +142,7 @@ function SliderRoot({
   );
 }
 
+/** @internal */
 SliderRoot.displayName = "SliderRoot";
 
 /**
@@ -147,7 +154,11 @@ SliderRoot.displayName = "SliderRoot";
  *
  * @throws if rendered outside a `Slider.Root`.
  */
-function SliderTrack({ children, asChild = false, ...rest }: SliderTrackProps) {
+export function SliderTrack({
+  children,
+  asChild = false,
+  ...rest
+}: SliderTrackProps): ReactElement {
   const { orientation, disabled } = useSliderContext();
   const trackProps = {
     ...rest,
@@ -161,6 +172,7 @@ function SliderTrack({ children, asChild = false, ...rest }: SliderTrackProps) {
   );
 }
 
+/** @internal */
 SliderTrack.displayName = "SliderTrack";
 
 /**
@@ -173,12 +185,12 @@ SliderTrack.displayName = "SliderTrack";
  *
  * @throws if rendered outside a `Slider.Root`.
  */
-function SliderRange({
+export function SliderRange({
   style,
   asChild = false,
   children,
   ...rest
-}: SliderRangeProps) {
+}: SliderRangeProps): ReactElement {
   const { values, min, max, orientation, dir, inverted, disabled } =
     useSliderContext();
   const rangeProps = {
@@ -197,6 +209,7 @@ function SliderRange({
   );
 }
 
+/** @internal */
 SliderRange.displayName = "SliderRange";
 
 /**
@@ -220,14 +233,14 @@ SliderRange.displayName = "SliderRange";
  *
  * @throws if rendered outside a `Slider.Root`.
  */
-function SliderThumb({
+export function SliderThumb({
   style,
   ref: forwardedRef,
   onKeyDown,
   asChild = false,
   children,
   ...rest
-}: SliderThumbProps) {
+}: SliderThumbProps): ReactElement {
   const {
     ref,
     value,
@@ -260,9 +273,11 @@ function SliderThumb({
   );
 }
 
+/** @internal */
 SliderThumb.displayName = "SliderThumb";
 
-type TSliderCompound = typeof SliderRoot & {
+/** Static-property shape of the compound {@link Slider} export: the callable {@link SliderRoot} plus its namespaced sub-components. */
+export type TSliderCompound = typeof SliderRoot & {
   Root: typeof SliderRoot;
   Track: typeof SliderTrack;
   Range: typeof SliderRange;

package/src/Slider/SliderContext.ts

@@ -1,7 +1,9 @@
-import { createStrictContext } from "../utils";
+import type { Context } from "react";
+import { createStrictContext } from "../utils/index.ts";
 
 import type { SliderDirection, SliderOrientation } from "./types";
 
+/** Shared state published by `Slider.Root` to its sub-components: the current values, range/step bounds, orientation and direction, thumb registration, and value-commit callbacks. */
 export type SliderContextValue = {
   values: number[];
   min: number;
@@ -17,8 +19,13 @@ export type SliderContextValue = {
   commit: (values: number[]) => void;
 };
 
-export const [SliderContext, useSliderContext] =
-  createStrictContext<SliderContextValue>(
-    "Slider sub-components must be rendered inside a <Slider.Root>.",
-    "SliderContext",
-  );
+const sliderContextPair = createStrictContext<SliderContextValue>(
+  "Slider sub-components must be rendered inside a <Slider.Root>.",
+  "SliderContext",
+);
+
+/** React context carrying the {@link SliderContextValue} shared by the slider's sub-components. */
+export const SliderContext: Context<SliderContextValue | null> =
+  sliderContextPair[0];
+/** Hook returning the {@link SliderContextValue}; throws when used outside a `<Slider.Root>`. */
+export const useSliderContext: () => SliderContextValue = sliderContextPair[1];

package/src/Slider/__tests__/Slider.reading-direction.test.tsx

@@ -1,7 +1,7 @@
 import { fireEvent, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { DirectionProvider } from "../../DirectionProvider";
+import { DirectionProvider } from "../../DirectionProvider/index.ts";
 import { Slider } from "../Slider";
 
 import { rtlKeyboardCases } from "./Slider.fixtures";

package/src/Slider/hooks/useSliderRoot.ts

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef } from "react";
 import type { PointerEvent as ReactPointerEvent } from "react";
 
-import { useCollection, useControllableState } from "../../hooks";
+import { useCollection, useControllableState } from "../../hooks/index.ts";
 import type { SliderContextValue } from "../SliderContext";
 import type { SliderDirection, SliderOrientation } from "../types";
 import { clamp, getClosestThumbIndex, getPointerValue } from "../utils";

package/src/Slider/types.ts

@@ -1,9 +1,12 @@
 import type { ComponentProps } from "react";
 
+/** Layout axis of the slider track. */
 export type SliderOrientation = "horizontal" | "vertical";
+/** Reading direction of the slider, affecting which end is the minimum. */
 export type SliderDirection = "ltr" | "rtl";
 
-type SliderRootSharedProps = Omit<
+/** Props common to both controlled and uncontrolled `Slider.Root`: range/step bounds, orientation, direction, and the native `<span>` attributes. */
+export type SliderRootSharedProps = Omit<
   ComponentProps<"span">,
   "defaultValue" | "dir"
 > & {
@@ -19,30 +22,36 @@ type SliderRootSharedProps = Omit<
   asChild?: boolean;
 };
 
-type SliderRootUncontrolledProps = SliderRootSharedProps & {
+/** Uncontrolled `Slider.Root` props: seed with `defaultValue`; `value` is disallowed. */
+export type SliderRootUncontrolledProps = SliderRootSharedProps & {
   defaultValue?: number[];
   value?: never;
   onValueChange?: (value: number[]) => void;
   onValueCommit?: (value: number[]) => void;
 };
 
-type SliderRootControlledProps = SliderRootSharedProps & {
+/** Controlled `Slider.Root` props: drive with `value`; `defaultValue` is disallowed. */
+export type SliderRootControlledProps = SliderRootSharedProps & {
   defaultValue?: never;
   value: number[];
   onValueChange?: (value: number[]) => void;
   onValueCommit?: (value: number[]) => void;
 };
 
+/** Props for `Slider.Root` — the discriminated union of controlled ({@link SliderRootControlledProps}) and uncontrolled ({@link SliderRootUncontrolledProps}) modes. */
 export type SliderRootProps =
   | SliderRootUncontrolledProps
   | SliderRootControlledProps;
 
+/** Props for `Slider.Track` — the full-length rail; native `<span>` props plus `asChild`. */
 export type SliderTrackProps = ComponentProps<"span"> & {
   asChild?: boolean;
 };
+/** Props for `Slider.Range` — the filled segment between the minimum and the active thumb; native `<span>` props plus `asChild`. */
 export type SliderRangeProps = ComponentProps<"span"> & {
   asChild?: boolean;
 };
+/** Props for `Slider.Thumb` — a draggable handle; native `<span>` props plus `asChild`. */
 export type SliderThumbProps = ComponentProps<"span"> & {
   asChild?: boolean;
 };

package/src/Status/Status.tsx

@@ -1,4 +1,6 @@
-import { Slot } from "../Slot";
+import type { ReactElement } from "react";
+
+import { Slot } from "../Slot/index.ts";
 import { StatusProps } from "./types";
 
 /**
@@ -31,7 +33,11 @@ import { StatusProps } from "./types";
  * </Status>
  * ```
  */
-export function Status({ asChild = false, children, ...rest }: StatusProps) {
+export function Status({
+  asChild = false,
+  children,
+  ...rest
+}: StatusProps): ReactElement {
   const rootProps = { role: "status", ...rest };
 
   if (asChild) {
@@ -41,4 +47,5 @@ export function Status({ asChild = false, children, ...rest }: StatusProps) {
   return <div {...rootProps}>{children}</div>;
 }
 
+/** @internal */
 Status.displayName = "Status";

package/src/Status/__tests__/Status.test.tsx

@@ -1,4 +1,4 @@
-import { Status } from "..";
+import { Status } from "../index.ts";
 import { render, screen } from "@testing-library/react";
 
 describe("Status component", () => {

package/src/Status/types.ts

@@ -1,5 +1,9 @@
 import { ComponentProps } from "react";
 
+/**
+ * Props for {@link Status} — all native `<div>` attributes plus the
+ * `asChild` escape hatch.
+ */
 export type StatusProps = ComponentProps<"div"> & {
   asChild?: boolean;
 };

package/src/Switch/Switch.tsx

@@ -1,9 +1,10 @@
 import { useMemo } from "react";
+import type { ReactElement } from "react";
 
-import { Slot, composeEventHandlers } from "../Slot";
+import { Slot, composeEventHandlers } from "../Slot/index.ts";
 
 import { SwitchContext } from "./SwitchContext";
-import { useSwitchContext, useSwitchRoot } from "./hooks";
+import { useSwitchContext, useSwitchRoot } from "./hooks/index.ts";
 import { SwitchRootProps, SwitchThumbProps } from "./types";
 
 /**
@@ -48,7 +49,7 @@ import { SwitchRootProps, SwitchThumbProps } from "./types";
  * </Switch.Root>
  * ```
  */
-function SwitchRoot({
+export function SwitchRoot({
   defaultChecked,
   checked,
   onCheckedChange,
@@ -58,7 +59,7 @@ function SwitchRoot({
   children,
   ref,
   ...rest
-}: SwitchRootProps) {
+}: SwitchRootProps): ReactElement {
   const { checked: isChecked, toggle } = useSwitchRoot({
     defaultChecked,
     checked,
@@ -88,6 +89,7 @@ function SwitchRoot({
   );
 }
 
+/** @internal */
 SwitchRoot.displayName = "SwitchRoot";
 
 /**
@@ -111,7 +113,11 @@ SwitchRoot.displayName = "SwitchRoot";
  *
  * @throws if rendered outside a `Switch.Root`.
  */
-function SwitchThumb({ children, asChild = false, ...rest }: SwitchThumbProps) {
+export function SwitchThumb({
+  children,
+  asChild = false,
+  ...rest
+}: SwitchThumbProps): ReactElement {
   const { checked } = useSwitchContext();
   const thumbProps = {
     ...rest,
@@ -124,10 +130,14 @@ function SwitchThumb({ children, asChild = false, ...rest }: SwitchThumbProps) {
   return <span {...thumbProps}>{children}</span>;
 }
 
+/** @internal */
 SwitchThumb.displayName = "SwitchThumb";
 
-type TSwitchCompound = typeof SwitchRoot & {
+/** Type of the {@link Switch} compound — the Root callable plus its sub-components. */
+export type TSwitchCompound = typeof SwitchRoot & {
+  /** The root toggle button, owning checked state and context. */
   Root: typeof SwitchRoot;
+  /** The sliding thumb indicator. */
   Thumb: typeof SwitchThumb;
 };
 

package/src/Switch/SwitchContext.ts

@@ -1,10 +1,18 @@
-import { createStrictContext } from "../utils";
+import type { Context } from "react";
+import { createStrictContext } from "../utils/index.ts";
 
+/** Value shared from `Switch.Root` to `Switch.Thumb` through context. */
 export type SwitchContextValue = {
+  /** Whether the switch is currently checked. */
   checked: boolean;
 };
 
-export const [SwitchContext, useSwitchContext] =
-  createStrictContext<SwitchContextValue>(
-    "Switch.Thumb must be rendered inside a <Switch.Root>.",
-  );
+const switchContextPair = createStrictContext<SwitchContextValue>(
+  "Switch.Thumb must be rendered inside a <Switch.Root>.",
+);
+
+/** React context carrying the {@link SwitchContextValue} for `Switch.Thumb`. */
+export const SwitchContext: Context<SwitchContextValue | null> =
+  switchContextPair[0];
+/** Read the nearest {@link SwitchContextValue}; throws outside `Switch.Root`. */
+export const useSwitchContext: () => SwitchContextValue = switchContextPair[1];

package/src/Switch/hooks/useSwitchRoot.ts

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
 
-import { useControllableState } from "../../hooks";
+import { useControllableState } from "../../hooks/index.ts";
 
 type UseSwitchRootArgs = {
   defaultChecked?: boolean;