@primitiv-ui/react 0.1.1 → 0.1.3

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

@@ -5,11 +5,8 @@ import { Slot, composeEventHandlers } from "../Slot/index.ts";
 
 import { CheckboxCardContext } from "./CheckboxCardContext";
 import { useCheckboxCardContext, useCheckboxCardRoot } from "./hooks/index.ts";
-import {
-  CheckboxCardIndicatorProps,
-  CheckboxCardRootProps,
-  CheckedState,
-} from "./types";
+import { CheckboxCardIndicatorProps, CheckboxCardRootProps } from "./types";
+import type { CheckedState } from "../Checkbox/types";
 
 function dataStateOf(checked: CheckedState) {
   if (checked === "indeterminate") return "indeterminate" as const;
@@ -67,7 +64,7 @@ function dataStateOf(checked: CheckedState) {
  * </CheckboxCard.Root>
  * ```
  */
-function CheckboxCardRoot(props: CheckboxCardRootProps): ReactElement {
+export function CheckboxCardRoot(props: CheckboxCardRootProps): ReactElement {
   const {
     defaultChecked,
     checked,
@@ -109,6 +106,7 @@ function CheckboxCardRoot(props: CheckboxCardRootProps): ReactElement {
   );
 }
 
+/** @internal */
 CheckboxCardRoot.displayName = "CheckboxCardRoot";
 
 /**
@@ -137,7 +135,7 @@ CheckboxCardRoot.displayName = "CheckboxCardRoot";
  *
  * @throws if rendered outside a `CheckboxCard.Root`.
  */
-function CheckboxCardIndicator({
+export function CheckboxCardIndicator({
   children,
   forceMount,
   asChild = false,
@@ -157,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,9 +1,12 @@
 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;
 };
 
@@ -11,7 +14,12 @@ 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

@@ -2,7 +2,7 @@ import { useCallback } from "react";
 
 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

@@ -88,6 +88,7 @@ export function CollapsibleRoot({
   );
 }
 
+/** @internal */
 CollapsibleRoot.displayName = "CollapsibleRoot";
 
 /**
@@ -171,6 +172,7 @@ export function CollapsibleTrigger<T extends HTMLElement = HTMLButtonElement>({
   );
 }
 
+/** @internal */
 CollapsibleTrigger.displayName = "CollapsibleTrigger";
 
 /**
@@ -241,6 +243,7 @@ export function CollapsibleContent({
   );
 }
 
+/** @internal */
 CollapsibleContent.displayName = "CollapsibleContent";
 
 /**
@@ -293,15 +296,27 @@ export function CollapsibleTriggerIcon({
   );
 }
 
+/** @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;
 };
 
+/**
+ * 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,
   {

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;
 };

package/src/ContextMenu/ContextMenu.tsx

@@ -68,7 +68,7 @@ import { MENUITEM_SELECTOR, TYPEAHEAD_RESET_MS } from "./constants";
  * keys (`ArrowRight` ↔ `ArrowLeft`). When omitted, the component reads
  * the inherited {@link DirectionProvider} value, falling back to `"ltr"`.
  */
-function ContextMenuRoot({
+export function ContextMenuRoot({
   defaultOpen = false,
   open: controlledOpen,
   onOpenChange,
@@ -119,6 +119,7 @@ function ContextMenuRoot({
   );
 }
 
+/** @internal */
 ContextMenuRoot.displayName = "ContextMenuRoot";
 
 /**
@@ -141,7 +142,7 @@ function useCloseSiblingSub() {
  * the native menu is suppressed and the ContextMenu opens, positioned at
  * the pointer.
  */
-function ContextMenuTrigger({
+export function ContextMenuTrigger({
   children,
   onContextMenu,
   asChild = false,
@@ -172,6 +173,7 @@ function ContextMenuTrigger({
   return <span {...triggerProps}>{children}</span>;
 }
 
+/** @internal */
 ContextMenuTrigger.displayName = "ContextMenuTrigger";
 
 /**
@@ -196,7 +198,7 @@ ContextMenuTrigger.displayName = "ContextMenuTrigger";
  * that flip the menu to the opposite side when it would overflow the
  * viewport. Pass `asChild` to render any element with menu semantics.
  */
-function ContextMenuContent({
+export function ContextMenuContent({
   children,
   style,
   onKeyDown,
@@ -374,6 +376,7 @@ function ContextMenuContent({
   );
 }
 
+/** @internal */
 ContextMenuContent.displayName = "ContextMenuContent";
 
 /**
@@ -387,7 +390,7 @@ ContextMenuContent.displayName = "ContextMenuContent";
  *
  * Disabled items receive `aria-disabled="true"` and no-op on activation.
  */
-function ContextMenuItem({
+export function ContextMenuItem({
   children,
   onClick,
   onSelect,
@@ -431,6 +434,7 @@ function ContextMenuItem({
   return <li {...itemProps}>{children}</li>;
 }
 
+/** @internal */
 ContextMenuItem.displayName = "ContextMenuItem";
 
 /**
@@ -438,7 +442,7 @@ ContextMenuItem.displayName = "ContextMenuItem";
  * by default. Non-interactive — skipped by focus, arrow navigation, and
  * typeahead.
  */
-function ContextMenuSeparator({
+export function ContextMenuSeparator({
   asChild = false,
   children,
   ...rest
@@ -452,6 +456,7 @@ function ContextMenuSeparator({
   return <li {...separatorProps} />;
 }
 
+/** @internal */
 ContextMenuSeparator.displayName = "ContextMenuSeparator";
 
 /**
@@ -462,7 +467,7 @@ ContextMenuSeparator.displayName = "ContextMenuSeparator";
  * Generates a stable id for its accompanying {@link ContextMenuLabel |
  * `ContextMenu.Label`}, wired automatically via `aria-labelledby`.
  */
-function ContextMenuGroup({
+export function ContextMenuGroup({
   children,
   asChild = false,
   ...rest
@@ -488,6 +493,7 @@ function ContextMenuGroup({
   );
 }
 
+/** @internal */
 ContextMenuGroup.displayName = "ContextMenuGroup";
 
 /**
@@ -497,7 +503,7 @@ ContextMenuGroup.displayName = "ContextMenuGroup";
  * consumers don't need to thread ids manually. A caller-supplied `id` takes
  * precedence over the auto-generated one.
  */
-function ContextMenuLabel({
+export function ContextMenuLabel({
   id,
   children,
   asChild = false,
@@ -513,6 +519,7 @@ function ContextMenuLabel({
   return <li {...labelProps}>{children}</li>;
 }
 
+/** @internal */
 ContextMenuLabel.displayName = "ContextMenuLabel";
 
 /**
@@ -527,7 +534,7 @@ ContextMenuLabel.displayName = "ContextMenuLabel";
  *
  * Disabled items receive `aria-disabled="true"` and no-op on activation.
  */
-function ContextMenuCheckboxItem({
+export function ContextMenuCheckboxItem({
   children,
   onClick,
   onSelect,
@@ -590,6 +597,7 @@ function ContextMenuCheckboxItem({
   );
 }
 
+/** @internal */
 ContextMenuCheckboxItem.displayName = "ContextMenuCheckboxItem";
 
 /**
@@ -605,7 +613,7 @@ ContextMenuCheckboxItem.displayName = "ContextMenuCheckboxItem";
  * {@link ContextMenuItemIndicatorProps.forceMount | `forceMount`} to keep
  * the DOM node mounted in both states for animation use cases.
  */
-function ContextMenuItemIndicator({
+export function ContextMenuItemIndicator({
   children,
   asChild = false,
   forceMount = false,
@@ -637,6 +645,7 @@ function ContextMenuItemIndicator({
   return <span {...indicatorProps}>{children}</span>;
 }
 
+/** @internal */
 ContextMenuItemIndicator.displayName = "ContextMenuItemIndicator";
 
 /**
@@ -644,7 +653,7 @@ ContextMenuItemIndicator.displayName = "ContextMenuItemIndicator";
  * {@link ContextMenuRadioItem | `ContextMenu.RadioItem`} elements. Renders a
  * `<li role="group">` wrapping `<ul role="none">`.
  */
-function ContextMenuRadioGroup({
+export function ContextMenuRadioGroup({
   defaultValue,
   value: controlledValue,
   onValueChange,
@@ -673,6 +682,7 @@ function ContextMenuRadioGroup({
   );
 }
 
+/** @internal */
 ContextMenuRadioGroup.displayName = "ContextMenuRadioGroup";
 
 /**
@@ -687,7 +697,7 @@ ContextMenuRadioGroup.displayName = "ContextMenuRadioGroup";
  * {@link ContextMenuRadioItemProps.onSelect | `onSelect`} with a cancellable
  * `Event`. Call `event.preventDefault()` to keep the menu open.
  */
-function ContextMenuRadioItem({
+export function ContextMenuRadioItem({
   children,
   onClick,
   onSelect,
@@ -748,6 +758,7 @@ function ContextMenuRadioItem({
   );
 }
 
+/** @internal */
 ContextMenuRadioItem.displayName = "ContextMenuRadioItem";
 
 /**
@@ -757,7 +768,7 @@ ContextMenuRadioItem.displayName = "ContextMenuRadioItem";
  * menu. Supports uncontrolled (`defaultOpen`) and controlled (`open` +
  * `onOpenChange`) modes.
  */
-function ContextMenuSub({
+export function ContextMenuSub({
   defaultOpen,
   open: controlledOpen,
   onOpenChange,
@@ -813,6 +824,7 @@ function ContextMenuSub({
   );
 }
 
+/** @internal */
 ContextMenuSub.displayName = "ContextMenuSub";
 
 /**
@@ -828,7 +840,7 @@ ContextMenuSub.displayName = "ContextMenuSub";
  * `ArrowRight` in `"ltr"`, `ArrowLeft` in `"rtl"`. Disabled triggers
  * ignore both click and the open arrow key.
  */
-function ContextMenuSubTrigger({
+export function ContextMenuSubTrigger({
   children,
   onClick,
   onKeyDown,
@@ -879,6 +891,7 @@ function ContextMenuSubTrigger({
   return <li {...subTriggerProps}>{children}</li>;
 }
 
+/** @internal */
 ContextMenuSubTrigger.displayName = "ContextMenuSubTrigger";
 
 /**
@@ -890,7 +903,7 @@ ContextMenuSubTrigger.displayName = "ContextMenuSubTrigger";
  * key closes the submenu and returns focus to the SubTrigger —
  * `ArrowLeft` in `"ltr"`, `ArrowRight` in `"rtl"`.
  */
-function ContextMenuSubContent({
+export function ContextMenuSubContent({
   children,
   onKeyDown,
   asChild = false,
@@ -961,9 +974,11 @@ function ContextMenuSubContent({
   );
 }
 
+/** @internal */
 ContextMenuSubContent.displayName = "ContextMenuSubContent";
 
-type TContextMenuCompound = typeof ContextMenuRoot & {
+/** Type of the {@link ContextMenu} compound: the root callable plus its attached sub-components. */
+export type TContextMenuCompound = typeof ContextMenuRoot & {
   Root: typeof ContextMenuRoot;
   Trigger: typeof ContextMenuTrigger;
   Content: typeof ContextMenuContent;
@@ -980,6 +995,15 @@ type TContextMenuCompound = typeof ContextMenuRoot & {
   SubContent: typeof ContextMenuSubContent;
 };
 
+/**
+ * Headless, accessible **ContextMenu** — a compound component implementing the
+ * [WAI-ARIA menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/) opened
+ * by a right-click (or long-press) on its trigger, with submenus, checkbox and
+ * radio items, groups, labels and separators. Zero styles ship.
+ *
+ * The default export is the `Root`; sub-components are attached as static
+ * properties (`ContextMenu.Trigger`, `ContextMenu.Content`, …).
+ */
 const ContextMenuCompound: TContextMenuCompound = Object.assign(
   ContextMenuRoot,
   {
@@ -1000,6 +1024,7 @@ const ContextMenuCompound: TContextMenuCompound = Object.assign(
   },
 );
 
+/** @internal */
 ContextMenuCompound.displayName = "ContextMenu";
 
 export { ContextMenuCompound as ContextMenu };

package/src/ContextMenu/index.ts

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