@primitiv-ui/react 0.1.1 → 0.1.2

package/src/RadioCard/types.ts

@@ -10,30 +10,48 @@ export type RadioCardOrientation = "horizontal" | "vertical" | "both";
 /** Reading direction — swaps the horizontal arrow pair when `"rtl"`. */
 export type RadioCardReadingDirection = "ltr" | "rtl";
 
-type RadioCardRootBaseProps = Omit<ComponentProps<"div">, "role"> & {
+/** Props shared by both controlled and uncontrolled `RadioCard.Root` usage.
+ * Extends the native `<div>` props (minus `role`). */
+export type RadioCardRootBaseProps = Omit<ComponentProps<"div">, "role"> & {
   children?: ReactNode;
+  /** Ref to the rendered root element. */
   ref?: Ref<HTMLDivElement>;
+  /** Render the child element instead of the default `<div>`. */
   asChild?: boolean;
+  /** Which arrow keys navigate the group. */
   orientation?: RadioCardOrientation;
+  /** Reading direction for horizontal arrow navigation. */
   dir?: RadioCardReadingDirection;
 };
 
-type RadioCardRootUncontrolledProps = RadioCardRootBaseProps & {
+/** Uncontrolled `RadioCard.Root` props: the component owns the selection,
+ * seeded by an optional `defaultValue`. */
+export type RadioCardRootUncontrolledProps = RadioCardRootBaseProps & {
+  /** Value selected on first render. */
   defaultValue?: string;
   value?: never;
+  /** Called with the value when the selection changes. */
   onValueChange?: (value: string) => void;
 };
 
-type RadioCardRootControlledProps = RadioCardRootBaseProps & {
+/** Controlled `RadioCard.Root` props: the caller owns the selection via
+ * `value` and is notified through the required `onValueChange`. */
+export type RadioCardRootControlledProps = RadioCardRootBaseProps & {
   defaultValue?: never;
+  /** Value of the currently selected card. */
   value: string;
+  /** Called with the value when the user selects a card. */
   onValueChange: (value: string) => void;
 };
 
+/** Props for `RadioCard.Root` — resolves to either the controlled or
+ * uncontrolled prop shape. */
 export type RadioCardRootProps =
   | RadioCardRootUncontrolledProps
   | RadioCardRootControlledProps;
 
+/** Props for `RadioCard.Item` — a selectable card rendered as a
+ * `role="radio"` button, identified by its required `value`. */
 export type RadioCardItemProps = Omit<
   ComponentProps<"button">,
   "type" | "role" | "aria-checked" | "value"
@@ -44,6 +62,9 @@ export type RadioCardItemProps = Omit<
   asChild?: boolean;
 };
 
+/** Props for `RadioCard.Indicator` — the visual marker rendered inside the
+ * selected item. By default it renders only when its item is checked; set
+ * `forceMount` to keep it mounted for exit transitions. */
 export type RadioCardIndicatorProps = ComponentProps<"span"> & {
   children?: ReactNode;
   forceMount?: boolean;

package/src/RadioGroup/RadioGroup.tsx

@@ -74,7 +74,7 @@ import {
  * </RadioGroup.Root>
  * ```
  */
-function RadioGroupRoot({
+export function RadioGroupRoot({
   defaultValue,
   value: controlledValue,
   onValueChange,
@@ -130,6 +130,7 @@ function RadioGroupRoot({
   );
 }
 
+/** @internal */
 RadioGroupRoot.displayName = "RadioGroupRoot";
 
 /**
@@ -164,7 +165,7 @@ RadioGroupRoot.displayName = "RadioGroupRoot";
  *
  * @throws if rendered outside a `RadioGroup.Root`.
  */
-function RadioGroupItem({
+export function RadioGroupItem({
   value,
   children,
   onClick,
@@ -238,6 +239,7 @@ function RadioGroupItem({
   );
 }
 
+/** @internal */
 RadioGroupItem.displayName = "RadioGroupItem";
 
 /**
@@ -278,7 +280,7 @@ RadioGroupItem.displayName = "RadioGroupItem";
  *
  * @throws if rendered outside a `RadioGroup.Item`.
  */
-function RadioGroupIndicator({
+export function RadioGroupIndicator({
   children,
   forceMount,
   asChild = false,
@@ -297,9 +299,11 @@ function RadioGroupIndicator({
   return <span {...indicatorProps}>{children}</span>;
 }
 
+/** @internal */
 RadioGroupIndicator.displayName = "RadioGroupIndicator";
 
-type TRadioGroupCompound = typeof RadioGroupRoot & {
+/** Type of the {@link RadioGroup} compound: the root callable plus its attached sub-components. */
+export type TRadioGroupCompound = typeof RadioGroupRoot & {
   Root: typeof RadioGroupRoot;
   Item: typeof RadioGroupItem;
   Indicator: typeof RadioGroupIndicator;
@@ -349,6 +353,7 @@ const RadioGroupCompound: TRadioGroupCompound = Object.assign(RadioGroupRoot, {
   Indicator: RadioGroupIndicator,
 });
 
+/** @internal */
 RadioGroupCompound.displayName = "RadioGroup";
 
 export { RadioGroupCompound as RadioGroup };

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

@@ -52,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,
@@ -96,6 +96,7 @@ function SelectRoot({
   return <select {...rootProps}>{children}</select>;
 }
 
+/** @internal */
 SelectRoot.displayName = "SelectRoot";
 
 /**
@@ -105,10 +106,14 @@ SelectRoot.displayName = "SelectRoot";
  * Native `<option>` only renders text; rich content (icons, descriptions)
  * is not supported.
  */
-function SelectOption({ children, ...rest }: SelectOptionProps): ReactElement {
+export function SelectOption({
+  children,
+  ...rest
+}: SelectOptionProps): ReactElement {
   return <option {...rest}>{children}</option>;
 }
 
+/** @internal */
 SelectOption.displayName = "SelectOption";
 
 /**
@@ -116,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): ReactElement {
+export function SelectGroup({
+  children,
+  ...rest
+}: SelectGroupProps): ReactElement {
   return <optgroup {...rest}>{children}</optgroup>;
 }
 
+/** @internal */
 SelectGroup.displayName = "SelectGroup";
 
 /**
@@ -132,7 +141,7 @@ 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({
+export function SelectPlaceholder({
   children,
   ...rest
 }: SelectPlaceholderProps): ReactElement {
@@ -143,9 +152,11 @@ function SelectPlaceholder({
   );
 }
 
+/** @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/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/Slider/Slider.tsx

@@ -74,7 +74,7 @@ import { getRangeStyle } from "./utils";
  * </Slider.Root>
  * ```
  */
-function SliderRoot({
+export function SliderRoot({
   min = 0,
   max = 100,
   step = 1,
@@ -142,6 +142,7 @@ function SliderRoot({
   );
 }
 
+/** @internal */
 SliderRoot.displayName = "SliderRoot";
 
 /**
@@ -153,7 +154,7 @@ SliderRoot.displayName = "SliderRoot";
  *
  * @throws if rendered outside a `Slider.Root`.
  */
-function SliderTrack({
+export function SliderTrack({
   children,
   asChild = false,
   ...rest
@@ -171,6 +172,7 @@ function SliderTrack({
   );
 }
 
+/** @internal */
 SliderTrack.displayName = "SliderTrack";
 
 /**
@@ -183,7 +185,7 @@ SliderTrack.displayName = "SliderTrack";
  *
  * @throws if rendered outside a `Slider.Root`.
  */
-function SliderRange({
+export function SliderRange({
   style,
   asChild = false,
   children,
@@ -207,6 +209,7 @@ function SliderRange({
   );
 }
 
+/** @internal */
 SliderRange.displayName = "SliderRange";
 
 /**
@@ -230,7 +233,7 @@ SliderRange.displayName = "SliderRange";
  *
  * @throws if rendered outside a `Slider.Root`.
  */
-function SliderThumb({
+export function SliderThumb({
   style,
   ref: forwardedRef,
   onKeyDown,
@@ -270,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

@@ -3,6 +3,7 @@ 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;
@@ -23,6 +24,8 @@ const sliderContextPair = createStrictContext<SliderContextValue>(
   "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/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

@@ -47,4 +47,5 @@ export function Status({
   return <div {...rootProps}>{children}</div>;
 }
 
+/** @internal */
 Status.displayName = "Status";

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

@@ -49,7 +49,7 @@ import { SwitchRootProps, SwitchThumbProps } from "./types";
  * </Switch.Root>
  * ```
  */
-function SwitchRoot({
+export function SwitchRoot({
   defaultChecked,
   checked,
   onCheckedChange,
@@ -89,6 +89,7 @@ function SwitchRoot({
   );
 }
 
+/** @internal */
 SwitchRoot.displayName = "SwitchRoot";
 
 /**
@@ -112,7 +113,7 @@ SwitchRoot.displayName = "SwitchRoot";
  *
  * @throws if rendered outside a `Switch.Root`.
  */
-function SwitchThumb({
+export function SwitchThumb({
   children,
   asChild = false,
   ...rest
@@ -129,10 +130,14 @@ function SwitchThumb({
   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,7 +1,9 @@
 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;
 };
 
@@ -9,6 +11,8 @@ 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/types.ts

@@ -1,25 +1,43 @@
 import { ButtonHTMLAttributes, ComponentProps, ReactNode, Ref } from "react";
 
-type SwitchRootBaseProps = Omit<
+/** Props common to both controlled and uncontrolled `Switch.Root` modes. */
+export type SwitchRootBaseProps = Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
   "type" | "role" | "aria-checked"
 > & {
+  /** Render the child element instead of the default `<button>`. */
   asChild?: boolean;
+  /** Ref to the rendered `<button>` element. */
   ref?: Ref<HTMLButtonElement>;
 };
 
-type SwitchRootUncontrolledProps = SwitchRootBaseProps & {
+/**
+ * Props for `Switch.Root` in uncontrolled mode — the component owns the checked
+ * state. Pass `defaultChecked` to set the initial value; `checked` is forbidden.
+ */
+export type SwitchRootUncontrolledProps = SwitchRootBaseProps & {
+  /** Initial checked state when uncontrolled. */
   defaultChecked?: boolean;
+  /** Forbidden in uncontrolled mode. */
   checked?: never;
+  /** Called whenever the checked state changes. */
   onCheckedChange?: (checked: boolean) => void;
 };
 
-type SwitchRootControlledProps = SwitchRootBaseProps & {
+/**
+ * Props for `Switch.Root` in controlled mode — the parent owns the checked
+ * value. Pass `checked` and `onCheckedChange` together.
+ */
+export type SwitchRootControlledProps = SwitchRootBaseProps & {
+  /** Forbidden in controlled mode. */
   defaultChecked?: never;
+  /** The controlled checked state. */
   checked: boolean;
+  /** Called whenever the component requests a checked-state change. */
   onCheckedChange: (checked: boolean) => void;
 };
 
+/** Props for `Switch.Root` — discriminated controlled/uncontrolled union. */
 export type SwitchRootProps =
   | SwitchRootUncontrolledProps
   | SwitchRootControlledProps;
@@ -31,7 +49,10 @@ export type SwitchRootProps =
  */
 export type SwitchProps = SwitchRootProps;
 
+/** Props for `Switch.Thumb`, the sliding indicator inside the track. */
 export type SwitchThumbProps = ComponentProps<"span"> & {
+  /** Optional thumb content. */
   children?: ReactNode;
+  /** Render the child element instead of the default `<span>`. */
   asChild?: boolean;
 };