@primitiv-ui/react 0.1.0 → 0.1.2

package/src/Checkbox/Checkbox.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 { CheckboxContext } from "./CheckboxContext";
-import { useCheckboxContext, useCheckboxRoot } from "./hooks";
+import { useCheckboxContext, useCheckboxRoot } from "./hooks/index.ts";
 import {
   CheckboxIndicatorProps,
   CheckboxRootProps,
@@ -76,7 +77,7 @@ function dataStateOf(checked: CheckedState) {
  * </Checkbox.Root>
  * ```
  */
-function CheckboxRoot(props: CheckboxRootProps) {
+export function CheckboxRoot(props: CheckboxRootProps): ReactElement {
   const {
     defaultChecked,
     checked,
@@ -118,6 +119,7 @@ function CheckboxRoot(props: CheckboxRootProps) {
   );
 }
 
+/** @internal */
 CheckboxRoot.displayName = "CheckboxRoot";
 
 /**
@@ -164,12 +166,12 @@ CheckboxRoot.displayName = "CheckboxRoot";
  *
  * @throws if rendered outside a `Checkbox.Root`.
  */
-function CheckboxIndicator({
+export function CheckboxIndicator({
   children,
   forceMount,
   asChild = false,
   ...rest
-}: CheckboxIndicatorProps) {
+}: CheckboxIndicatorProps): ReactElement | null {
   const { checked } = useCheckboxContext();
   const isVisible = checked !== false;
   if (!isVisible && !forceMount) return null;
@@ -184,9 +186,11 @@ function CheckboxIndicator({
   return <span {...indicatorProps}>{children}</span>;
 }
 
+/** @internal */
 CheckboxIndicator.displayName = "CheckboxIndicator";
 
-type TCheckboxCompound = typeof CheckboxRoot & {
+/** Type of the {@link Checkbox} compound: the root callable plus its attached sub-components. */
+export type TCheckboxCompound = typeof CheckboxRoot & {
   Root: typeof CheckboxRoot;
   Indicator: typeof CheckboxIndicator;
 };
@@ -223,6 +227,7 @@ const CheckboxCompound: TCheckboxCompound = Object.assign(CheckboxRoot, {
   Indicator: CheckboxIndicator,
 });
 
+/** @internal */
 CheckboxCompound.displayName = "Checkbox";
 
 export { CheckboxCompound as Checkbox };

package/src/Checkbox/CheckboxContext.ts

@@ -1,4 +1,4 @@
-import { createStrictContext } from "../utils";
+import { createStrictContext } from "../utils/index.ts";
 
 import { CheckedState } from "./types";
 

package/src/Checkbox/hooks/useCheckboxRoot.ts

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
 
-import { useControllableState } from "../../hooks";
+import { useControllableState } from "../../hooks/index.ts";
 
 import { CheckedState } from "../types";
 

package/src/Checkbox/index.ts

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

package/src/Checkbox/types.ts

@@ -1,14 +1,25 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
+/** The checked value of a checkbox — `true`, `false`, or `"indeterminate"` (the tri-state). */
 export type CheckedState = boolean | "indeterminate";
 
+/**
+ * Props for {@link Checkbox.Indicator} — all `<span>` attributes plus
+ * `forceMount` (keep mounted while unchecked for exit animations) and the
+ * `asChild` escape hatch.
+ */
 export type CheckboxIndicatorProps = ComponentProps<"span"> & {
   children?: ReactNode;
   forceMount?: boolean;
   asChild?: boolean;
 };
 
-type CheckboxRootBaseProps = Omit<
+/**
+ * Shared base for both {@link CheckboxRootProps} variants — the native
+ * `<button>` attributes (minus the ones the component owns) plus the
+ * `asChild` escape hatch and a typed `ref`.
+ */
+export type CheckboxRootBaseProps = Omit<
   ComponentProps<"button">,
   "type" | "role" | "aria-checked" | "defaultChecked"
 > & {
@@ -16,18 +27,34 @@ type CheckboxRootBaseProps = Omit<
   ref?: Ref<HTMLButtonElement>;
 };
 
-type CheckboxRootUncontrolledProps = CheckboxRootBaseProps & {
+/**
+ * Uncontrolled variant of {@link CheckboxRootProps}: the component owns the
+ * checked value. Pass `defaultChecked` (or omit it); `onCheckedChange` is
+ * optional and `checked` is forbidden.
+ */
+export type CheckboxRootUncontrolledProps = CheckboxRootBaseProps & {
   defaultChecked?: CheckedState;
   checked?: never;
   onCheckedChange?: (checked: boolean) => void;
 };
 
-type CheckboxRootControlledProps = CheckboxRootBaseProps & {
+/**
+ * Controlled variant of {@link CheckboxRootProps}: the parent owns the
+ * checked value. Pass `checked` and `onCheckedChange` together;
+ * `defaultChecked` is forbidden.
+ */
+export type CheckboxRootControlledProps = CheckboxRootBaseProps & {
   defaultChecked?: never;
   checked: CheckedState;
   onCheckedChange: (checked: boolean) => void;
 };
 
+/**
+ * Props for {@link Checkbox.Root}. A discriminated union of
+ * {@link CheckboxRootUncontrolledProps} and
+ * {@link CheckboxRootControlledProps}, so TypeScript accepts exactly one
+ * state mode.
+ */
 export type CheckboxRootProps =
   | CheckboxRootUncontrolledProps
   | CheckboxRootControlledProps;

package/src/CheckboxCard/CheckboxCard.tsx

@@ -1,14 +1,12 @@
 import { useMemo } from "react";
+import type { ReactElement } from "react";
 
-import { Slot, composeEventHandlers } from "../Slot";
+import { Slot, composeEventHandlers } from "../Slot/index.ts";
 
 import { CheckboxCardContext } from "./CheckboxCardContext";
-import { useCheckboxCardContext, useCheckboxCardRoot } from "./hooks";
-import {
-  CheckboxCardIndicatorProps,
-  CheckboxCardRootProps,
-  CheckedState,
-} from "./types";
+import { useCheckboxCardContext, useCheckboxCardRoot } from "./hooks/index.ts";
+import { CheckboxCardIndicatorProps, CheckboxCardRootProps } from "./types";
+import type { CheckedState } from "../Checkbox/types";
 
 function dataStateOf(checked: CheckedState) {
   if (checked === "indeterminate") return "indeterminate" as const;
@@ -66,7 +64,7 @@ function dataStateOf(checked: CheckedState) {
  * </CheckboxCard.Root>
  * ```
  */
-function CheckboxCardRoot(props: CheckboxCardRootProps) {
+export function CheckboxCardRoot(props: CheckboxCardRootProps): ReactElement {
   const {
     defaultChecked,
     checked,
@@ -108,6 +106,7 @@ function CheckboxCardRoot(props: CheckboxCardRootProps) {
   );
 }
 
+/** @internal */
 CheckboxCardRoot.displayName = "CheckboxCardRoot";
 
 /**
@@ -136,12 +135,12 @@ CheckboxCardRoot.displayName = "CheckboxCardRoot";
  *
  * @throws if rendered outside a `CheckboxCard.Root`.
  */
-function CheckboxCardIndicator({
+export function CheckboxCardIndicator({
   children,
   forceMount,
   asChild = false,
   ...rest
-}: CheckboxCardIndicatorProps) {
+}: CheckboxCardIndicatorProps): ReactElement | null {
   const { checked } = useCheckboxCardContext();
   const isVisible = checked !== false;
   if (!isVisible && !forceMount) return null;
@@ -156,9 +155,12 @@ function CheckboxCardIndicator({
   return <span {...indicatorProps}>{children}</span>;
 }
 
+/** @internal */
 CheckboxCardIndicator.displayName = "CheckboxCardIndicator";
 
-type TCheckboxCardCompound = typeof CheckboxCardRoot & {
+/** Type of the {@link CheckboxCard} compound: the callable `CheckboxCard.Root`
+ * component augmented with its sub-components as static properties. */
+export type TCheckboxCardCompound = typeof CheckboxCardRoot & {
   Root: typeof CheckboxCardRoot;
   Indicator: typeof CheckboxCardIndicator;
 };

package/src/CheckboxCard/CheckboxCardContext.ts

@@ -1,12 +1,25 @@
-import { createStrictContext } from "../utils";
+import type { Context } from "react";
+import { createStrictContext } from "../utils/index.ts";
 
-import { CheckedState } from "./types";
+import type { CheckedState } from "../Checkbox/types";
 
+/** The value shared by `CheckboxCard.Root` with its `CheckboxCard.Indicator`,
+ * exposing the current checked state. */
 export type CheckboxCardContextValue = {
+  /** Current checked state of the card. */
   checked: CheckedState;
 };
 
-export const [CheckboxCardContext, useCheckboxCardContext] =
-  createStrictContext<CheckboxCardContextValue>(
-    "CheckboxCard sub-components must be rendered inside a <CheckboxCard.Root>.",
-  );
+const checkboxCardContextPair = createStrictContext<CheckboxCardContextValue>(
+  "CheckboxCard sub-components must be rendered inside a <CheckboxCard.Root>.",
+);
+
+/** Strict React context carrying the {@link CheckboxCardContextValue} from
+ * `CheckboxCard.Root` to its indicator. `null` when read outside a
+ * `CheckboxCard.Root`. */
+export const CheckboxCardContext: Context<CheckboxCardContextValue | null> =
+  checkboxCardContextPair[0];
+/** Reads the {@link CheckboxCardContextValue}; throws when used outside a
+ * `CheckboxCard.Root`. */
+export const useCheckboxCardContext: () => CheckboxCardContextValue =
+  checkboxCardContextPair[1];

package/src/CheckboxCard/hooks/useCheckboxCardRoot.ts

@@ -1,8 +1,8 @@
 import { useCallback } from "react";
 
-import { useControllableState } from "../../hooks";
+import { useControllableState } from "../../hooks/index.ts";
 
-import { CheckedState } from "../types";
+import type { CheckedState } from "../../Checkbox/types";
 
 type UseCheckboxCardRootArgs = {
   defaultChecked?: CheckedState;

package/src/CheckboxCard/types.ts

@@ -1,33 +1,49 @@
 import { ComponentProps, ReactNode, Ref } from "react";
+import type { CheckedState } from "../Checkbox/types";
 
-export type CheckedState = boolean | "indeterminate";
-
+/** Props for `CheckboxCard.Indicator` — the visual marker shown when the card
+ * is checked. By default it renders only while checked; set `forceMount` to
+ * keep it mounted for exit transitions. */
 export type CheckboxCardIndicatorProps = ComponentProps<"span"> & {
   children?: ReactNode;
   forceMount?: boolean;
   asChild?: boolean;
 };
 
-type CheckboxCardRootBaseProps = Omit<
+/** Props shared by both controlled and uncontrolled `CheckboxCard.Root` usage.
+ * Extends the native `<button>` props (minus the checkbox-managed ones). */
+export type CheckboxCardRootBaseProps = Omit<
   ComponentProps<"button">,
   "type" | "role" | "aria-checked" | "defaultChecked"
 > & {
+  /** Render the child element instead of the default `<button>`. */
   asChild?: boolean;
+  /** Ref to the rendered element. */
   ref?: Ref<HTMLButtonElement>;
 };
 
-type CheckboxCardRootUncontrolledProps = CheckboxCardRootBaseProps & {
+/** Uncontrolled `CheckboxCard.Root` props: the component owns the checked
+ * state, seeded by an optional `defaultChecked`. */
+export type CheckboxCardRootUncontrolledProps = CheckboxCardRootBaseProps & {
+  /** Checked state on first render. */
   defaultChecked?: CheckedState;
   checked?: never;
+  /** Called with the new boolean checked state when it changes. */
   onCheckedChange?: (checked: boolean) => void;
 };
 
-type CheckboxCardRootControlledProps = CheckboxCardRootBaseProps & {
+/** Controlled `CheckboxCard.Root` props: the caller owns the checked state via
+ * `checked` and is notified through the required `onCheckedChange`. */
+export type CheckboxCardRootControlledProps = CheckboxCardRootBaseProps & {
   defaultChecked?: never;
+  /** Current checked state. */
   checked: CheckedState;
+  /** Called with the new boolean checked state when the user toggles. */
   onCheckedChange: (checked: boolean) => void;
 };
 
+/** Props for `CheckboxCard.Root` — resolves to either the controlled or
+ * uncontrolled prop shape. */
 export type CheckboxCardRootProps =
   | CheckboxCardRootUncontrolledProps
   | CheckboxCardRootControlledProps;

package/src/Collapsible/Collapsible.tsx

@@ -1,9 +1,13 @@
 import { Ref } from "react";
+import type { ReactElement } from "react";
 
-import { Slot } from "../Slot";
+import { Slot } from "../Slot/index.ts";
 
-import { CollapsibleContext, useCollapsibleContext } from "./CollapsibleContext";
-import { useCollapsibleRoot, useCollapsibleTrigger } from "./hooks";
+import {
+  CollapsibleContext,
+  useCollapsibleContext,
+} from "./CollapsibleContext";
+import { useCollapsibleRoot, useCollapsibleTrigger } from "./hooks/index.ts";
 
 import type {
   CollapsibleRootProps,
@@ -63,7 +67,7 @@ export function CollapsibleRoot({
   onOpenChange,
   disabled = false,
   ...rest
-}: CollapsibleRootProps) {
+}: CollapsibleRootProps): ReactElement {
   const { contextValue } = useCollapsibleRoot(
     controlledOpen,
     defaultOpen,
@@ -84,6 +88,7 @@ export function CollapsibleRoot({
   );
 }
 
+/** @internal */
 CollapsibleRoot.displayName = "CollapsibleRoot";
 
 /**
@@ -140,16 +145,14 @@ CollapsibleRoot.displayName = "CollapsibleRoot";
  * </Collapsible.Trigger>
  * ```
  */
-export function CollapsibleTrigger<
-  T extends HTMLElement = HTMLButtonElement,
->({
+export function CollapsibleTrigger<T extends HTMLElement = HTMLButtonElement>({
   ref,
   children,
   onClick,
   onKeyDown,
   asChild = false,
   ...rest
-}: CollapsibleTriggerProps<T>) {
+}: CollapsibleTriggerProps<T>): ReactElement {
   const { triggerProps } = useCollapsibleTrigger({
     ref: ref as Ref<HTMLButtonElement>,
     onClick,
@@ -169,6 +172,7 @@ export function CollapsibleTrigger<
   );
 }
 
+/** @internal */
 CollapsibleTrigger.displayName = "CollapsibleTrigger";
 
 /**
@@ -222,7 +226,7 @@ export function CollapsibleContent({
   children,
   forceMount = false,
   ...rest
-}: CollapsibleContentProps) {
+}: CollapsibleContentProps): ReactElement {
   const { open, disabled, contentId } = useCollapsibleContext();
 
   return (
@@ -239,6 +243,7 @@ export function CollapsibleContent({
   );
 }
 
+/** @internal */
 CollapsibleContent.displayName = "CollapsibleContent";
 
 /**
@@ -281,35 +286,46 @@ CollapsibleContent.displayName = "CollapsibleContent";
 export function CollapsibleTriggerIcon({
   children,
   ...rest
-}: CollapsibleTriggerIconProps) {
+}: CollapsibleTriggerIconProps): ReactElement {
   const { open } = useCollapsibleContext();
 
   return (
-    <span
-      aria-hidden="true"
-      data-state={open ? "open" : "closed"}
-      {...rest}
-    >
+    <span aria-hidden="true" data-state={open ? "open" : "closed"} {...rest}>
       {children}
     </span>
   );
 }
 
+/** @internal */
 CollapsibleTriggerIcon.displayName = "CollapsibleTriggerIcon";
 
+/** Type of the {@link Collapsible} compound — the Root callable plus its sub-components. */
 type CollapsibleCompound = typeof CollapsibleRoot & {
+  /** The root, owning open/closed state and context. */
   Root: typeof CollapsibleRoot;
+  /** The button that toggles the panel. */
   Trigger: typeof CollapsibleTrigger;
+  /** The collapsible panel. */
   Content: typeof CollapsibleContent;
+  /** An aria-hidden icon wrapper with an open/closed `data-state` hook. */
   TriggerIcon: typeof CollapsibleTriggerIcon;
 };
 
-const CollapsibleCompound: CollapsibleCompound = Object.assign(CollapsibleRoot, {
-  Root: CollapsibleRoot,
-  Trigger: CollapsibleTrigger,
-  Content: CollapsibleContent,
-  TriggerIcon: CollapsibleTriggerIcon,
-});
+/**
+ * Collapsible — a single disclosure widget pairing a trigger with a panel
+ * that expands and collapses. Use as a namespace (`Collapsible.Root`,
+ * `Collapsible.Trigger`, `Collapsible.Content`, `Collapsible.TriggerIcon`);
+ * the default export is also callable as the Root.
+ */
+const CollapsibleCompound: CollapsibleCompound = Object.assign(
+  CollapsibleRoot,
+  {
+    Root: CollapsibleRoot,
+    Trigger: CollapsibleTrigger,
+    Content: CollapsibleContent,
+    TriggerIcon: CollapsibleTriggerIcon,
+  },
+);
 
 CollapsibleCompound.displayName = "Collapsible";
 

package/src/Collapsible/CollapsibleContext.ts

@@ -1,4 +1,4 @@
-import { createStrictContext } from "../utils";
+import { createStrictContext } from "../utils/index.ts";
 import { CollapsibleContextValue } from "./types";
 
 export const [CollapsibleContext, useCollapsibleContext] =

package/src/Collapsible/hooks/useCollapsibleRoot.ts

@@ -1,6 +1,6 @@
 import { useCallback, useId, useMemo } from "react";
 
-import { useControllableState } from "../../hooks";
+import { useControllableState } from "../../hooks/index.ts";
 
 export function useCollapsibleRoot(
   controlledOpen: boolean | undefined,

package/src/Collapsible/hooks/useCollapsibleTrigger.ts

@@ -1,6 +1,6 @@
 import { useRef, MouseEvent, KeyboardEvent } from "react";
 
-import { composeRefs } from "../../Slot";
+import { composeRefs } from "../../Slot/index.ts";
 
 import { CollapsibleTriggerProps } from "../types";
 import { useCollapsibleContext } from "../CollapsibleContext";

package/src/Collapsible/index.ts

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

package/src/Collapsible/types.ts

@@ -1,48 +1,81 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
-type CollapsibleRootBaseProps = Omit<ComponentProps<"div">, "onChange"> & {
+/** Props common to both controlled and uncontrolled `Collapsible.Root` modes. */
+export type CollapsibleRootBaseProps = Omit<
+  ComponentProps<"div">,
+  "onChange"
+> & {
+  /** When `true`, disables the widget and short-circuits trigger activation. */
   disabled?: boolean;
 };
 
-type CollapsibleRootUncontrolledProps = CollapsibleRootBaseProps & {
+/**
+ * Props for `Collapsible.Root` in uncontrolled mode — the component owns the
+ * open state. Pass `defaultOpen` to set the initial value; `open` is forbidden.
+ */
+export type CollapsibleRootUncontrolledProps = CollapsibleRootBaseProps & {
+  /** Initial open state when uncontrolled. Defaults to `false`. */
   defaultOpen?: boolean;
+  /** Forbidden in uncontrolled mode. */
   open?: never;
+  /** Called whenever the open state changes. */
   onOpenChange?: (open: boolean) => void;
 };
 
-type CollapsibleRootControlledProps = CollapsibleRootBaseProps & {
+/**
+ * Props for `Collapsible.Root` in controlled mode — the parent owns the open
+ * value. Pass `open` and `onOpenChange` together; `defaultOpen` is forbidden.
+ */
+export type CollapsibleRootControlledProps = CollapsibleRootBaseProps & {
+  /** The controlled open state. */
   open: boolean;
+  /** Called whenever the component requests an open-state change. */
   onOpenChange: (open: boolean) => void;
+  /** Forbidden in controlled mode. */
   defaultOpen?: never;
 };
 
+/** Props for `Collapsible.Root` — discriminated controlled/uncontrolled union. */
 export type CollapsibleRootProps =
   | CollapsibleRootUncontrolledProps
   | CollapsibleRootControlledProps;
 
-export type CollapsibleTriggerProps<
-  T extends HTMLElement = HTMLButtonElement,
-> = Omit<ComponentProps<"button">, "ref"> & {
-  children: ReactNode;
-  asChild?: boolean;
-  /** Ref to the rendered element. Defaults to `HTMLButtonElement`; when using
-   * `asChild`, specify the child's element type (e.g. `HTMLAnchorElement`). */
-  ref?: Ref<T>;
-};
+/** Props for `Collapsible.Trigger`, the button that toggles the panel. */
+export type CollapsibleTriggerProps<T extends HTMLElement = HTMLButtonElement> =
+  Omit<ComponentProps<"button">, "ref"> & {
+    /** Trigger content (label, icon, etc.). */
+    children: ReactNode;
+    /** Render the child element instead of the default `<button>`. */
+    asChild?: boolean;
+    /** Ref to the rendered element. Defaults to `HTMLButtonElement`; when using
+     * `asChild`, specify the child's element type (e.g. `HTMLAnchorElement`). */
+    ref?: Ref<T>;
+  };
 
+/** Props for `Collapsible.Content`, the panel revealed when open. */
 export type CollapsibleContentProps = ComponentProps<"div"> & {
+  /** Panel content. */
   children: ReactNode;
+  /** Keep the panel mounted when closed so transitions can be CSS-driven. */
   forceMount?: boolean;
 };
 
+/** Props for `Collapsible.TriggerIcon`, the aria-hidden icon wrapper. */
 export type CollapsibleTriggerIconProps = ComponentProps<"span"> & {
+  /** The icon to render (inline SVG or icon component). */
   children: ReactNode;
 };
 
+/** Value shared through Collapsible context to all sub-components. */
 export type CollapsibleContextValue = {
+  /** Whether the panel is currently open. */
   open: boolean;
+  /** Whether the widget is disabled. */
   disabled: boolean;
+  /** Toggle the open state. */
   toggle: () => void;
+  /** Generated id linking trigger to content. */
   triggerId: string;
+  /** Generated id of the content panel. */
   contentId: string;
 };