@primitiv-ui/react 0.1.1 → 0.1.3

package/src/ContextMenu/types.ts

@@ -3,7 +3,11 @@ import { ComponentProps, ReactNode, Ref } from "react";
 import { CheckedState } from "../Checkbox/types";
 import { Direction } from "../DirectionProvider/index.ts";
 
-type ContextMenuRootBaseProps = {
+/**
+ * Shared base for both {@link ContextMenuRootProps} variants — `children`
+ * plus the reading-direction control.
+ */
+export type ContextMenuRootBaseProps = {
   children?: ReactNode;
   /**
    * Reading direction for the menu. Affects which arrow key opens / closes
@@ -14,22 +18,43 @@ type ContextMenuRootBaseProps = {
   dir?: Direction;
 };
 
-type ContextMenuRootUncontrolledProps = ContextMenuRootBaseProps & {
+/**
+ * Uncontrolled variant of {@link ContextMenuRootProps}: the component owns
+ * the open state. Pass `defaultOpen` (or omit it); `onOpenChange` is
+ * optional and `open` is forbidden.
+ */
+export type ContextMenuRootUncontrolledProps = ContextMenuRootBaseProps & {
   defaultOpen?: boolean;
   open?: never;
   onOpenChange?: (open: boolean) => void;
 };
 
-type ContextMenuRootControlledProps = ContextMenuRootBaseProps & {
+/**
+ * Controlled variant of {@link ContextMenuRootProps}: the parent owns the
+ * open state. Pass `open` and `onOpenChange` together; `defaultOpen` is
+ * forbidden.
+ */
+export type ContextMenuRootControlledProps = ContextMenuRootBaseProps & {
   defaultOpen?: never;
   open: boolean;
   onOpenChange: (open: boolean) => void;
 };
 
+/**
+ * Props for {@link ContextMenu.Root} — the open-state owner and
+ * direction provider. A discriminated union of the uncontrolled
+ * ({@link ContextMenuRootUncontrolledProps}) and controlled
+ * ({@link ContextMenuRootControlledProps}) variants.
+ */
 export type ContextMenuRootProps =
   | ContextMenuRootUncontrolledProps
   | ContextMenuRootControlledProps;
 
+/**
+ * Props for {@link ContextMenu.Trigger} — the `<span>` whose right-click
+ * (context menu) gesture opens the menu. Supports `asChild` to merge
+ * onto a custom element and `disabled` to suppress the gesture.
+ */
 export type ContextMenuTriggerProps = ComponentProps<"span"> & {
   children?: ReactNode;
   ref?: Ref<HTMLSpanElement>;
@@ -37,6 +62,11 @@ export type ContextMenuTriggerProps = ComponentProps<"span"> & {
   disabled?: boolean;
 };
 
+/**
+ * Props for {@link ContextMenu.Content} — the `<menu>` popover holding the
+ * menu items. The managed `role`, `popover`, and `id` attributes are
+ * omitted; `asChild` merges the props onto a custom element.
+ */
 export type ContextMenuContentProps = Omit<
   ComponentProps<"menu">,
   "role" | "popover" | "id"
@@ -46,6 +76,11 @@ export type ContextMenuContentProps = Omit<
   asChild?: boolean;
 };
 
+/**
+ * Props for {@link ContextMenu.Item} — a selectable `<li>` menu item. The
+ * managed `role`, `tabIndex`, and `onSelect` are omitted from the host
+ * props; `disabled` skips activation and `onSelect` fires on activation.
+ */
 export type ContextMenuItemProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "onSelect"
@@ -62,25 +97,46 @@ export type ContextMenuItemProps = Omit<
   onSelect?: (event: Event) => void;
 };
 
+/**
+ * Props for {@link ContextMenu.Separator} — a non-interactive `<li>`
+ * divider between groups of items. The managed `role` is omitted;
+ * `asChild` merges the props onto a custom element.
+ */
 export type ContextMenuSeparatorProps = Omit<ComponentProps<"li">, "role"> & {
   children?: ReactNode;
   ref?: Ref<HTMLLIElement>;
   asChild?: boolean;
 };
 
+/**
+ * Props for {@link ContextMenu.Group} — an `<li>` that groups related
+ * items, optionally labelled by a {@link ContextMenu.Label}. The managed
+ * `role` is omitted; `asChild` merges the props onto a custom element.
+ */
 export type ContextMenuGroupProps = Omit<ComponentProps<"li">, "role"> & {
   children?: ReactNode;
   ref?: Ref<HTMLLIElement>;
   asChild?: boolean;
 };
 
+/**
+ * Props for {@link ContextMenu.Label} — a non-interactive `<li>` caption
+ * for a {@link ContextMenu.Group}. Supports `asChild` to merge the props
+ * onto a custom element.
+ */
 export type ContextMenuLabelProps = ComponentProps<"li"> & {
   children?: ReactNode;
   ref?: Ref<HTMLLIElement>;
   asChild?: boolean;
 };
 
-type ContextMenuCheckboxItemBaseProps = Omit<
+/**
+ * Shared base for both {@link ContextMenuCheckboxItemProps} variants —
+ * the `<li>` host props plus `children`, `ref`, `asChild`, `disabled`,
+ * and `onSelect`. The managed `role`, `tabIndex`, `aria-checked`,
+ * `defaultChecked`, and `onSelect` host attributes are omitted.
+ */
+export type ContextMenuCheckboxItemBaseProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "aria-checked" | "defaultChecked" | "onSelect"
 > & {
@@ -95,24 +151,47 @@ type ContextMenuCheckboxItemBaseProps = Omit<
   onSelect?: (event: Event) => void;
 };
 
-type ContextMenuCheckboxItemUncontrolledProps =
+/**
+ * Uncontrolled variant of {@link ContextMenuCheckboxItemProps}: the
+ * component owns the checked state. Pass `defaultChecked` (or omit it);
+ * `onCheckedChange` is optional and the controlled `checked` prop is
+ * forbidden.
+ */
+export type ContextMenuCheckboxItemUncontrolledProps =
   ContextMenuCheckboxItemBaseProps & {
     defaultChecked?: CheckedState;
     checked?: never;
     onCheckedChange?: (checked: boolean) => void;
   };
 
-type ContextMenuCheckboxItemControlledProps =
+/**
+ * Controlled variant of {@link ContextMenuCheckboxItemProps}: the parent
+ * owns the checked state. Pass `checked` and `onCheckedChange` together;
+ * `defaultChecked` is forbidden.
+ */
+export type ContextMenuCheckboxItemControlledProps =
   ContextMenuCheckboxItemBaseProps & {
     defaultChecked?: never;
     checked: CheckedState;
     onCheckedChange: (checked: boolean) => void;
   };
 
+/**
+ * Props for {@link ContextMenu.CheckboxItem} — a toggleable menu item. A
+ * discriminated union of the uncontrolled
+ * ({@link ContextMenuCheckboxItemUncontrolledProps}) and controlled
+ * ({@link ContextMenuCheckboxItemControlledProps}) variants.
+ */
 export type ContextMenuCheckboxItemProps =
   | ContextMenuCheckboxItemUncontrolledProps
   | ContextMenuCheckboxItemControlledProps;
 
+/**
+ * Props for {@link ContextMenu.ItemIndicator} — the `<span>` that renders
+ * inside a checkbox or radio item to show its checked state. Set
+ * `forceMount` to render even when unchecked; `asChild` merges the props
+ * onto a custom element.
+ */
 export type ContextMenuItemIndicatorProps = ComponentProps<"span"> & {
   children?: ReactNode;
   ref?: Ref<HTMLSpanElement>;
@@ -124,29 +203,61 @@ export type ContextMenuItemIndicatorProps = ComponentProps<"span"> & {
   forceMount?: boolean;
 };
 
-type ContextMenuRadioGroupBaseProps = Omit<ComponentProps<"li">, "role"> & {
+/**
+ * Shared base for both {@link ContextMenuRadioGroupProps} variants — the
+ * `<li>` host props plus `children`, `ref`, and `asChild`. The managed
+ * `role` host attribute is omitted.
+ */
+export type ContextMenuRadioGroupBaseProps = Omit<
+  ComponentProps<"li">,
+  "role"
+> & {
   children?: ReactNode;
   ref?: Ref<HTMLLIElement>;
   asChild?: boolean;
 };
 
-type ContextMenuRadioGroupUncontrolledProps =
+/**
+ * Uncontrolled variant of {@link ContextMenuRadioGroupProps}: the
+ * component owns the selected-value state. Pass `defaultValue` (or omit
+ * it); `onValueChange` is optional and the controlled `value` prop is
+ * forbidden.
+ */
+export type ContextMenuRadioGroupUncontrolledProps =
   ContextMenuRadioGroupBaseProps & {
     defaultValue?: string;
     value?: never;
     onValueChange?: (value: string) => void;
   };
 
-type ContextMenuRadioGroupControlledProps = ContextMenuRadioGroupBaseProps & {
-  defaultValue?: never;
-  value: string;
-  onValueChange: (value: string) => void;
-};
+/**
+ * Controlled variant of {@link ContextMenuRadioGroupProps}: the parent
+ * owns the selected-value state. Pass `value` and `onValueChange`
+ * together; `defaultValue` is forbidden.
+ */
+export type ContextMenuRadioGroupControlledProps =
+  ContextMenuRadioGroupBaseProps & {
+    defaultValue?: never;
+    value: string;
+    onValueChange: (value: string) => void;
+  };
 
+/**
+ * Props for {@link ContextMenu.RadioGroup} — the container that tracks
+ * which {@link ContextMenu.RadioItem} is selected. A discriminated union
+ * of the uncontrolled ({@link ContextMenuRadioGroupUncontrolledProps})
+ * and controlled ({@link ContextMenuRadioGroupControlledProps}) variants.
+ */
 export type ContextMenuRadioGroupProps =
   | ContextMenuRadioGroupUncontrolledProps
   | ContextMenuRadioGroupControlledProps;
 
+/**
+ * Props for {@link ContextMenu.RadioItem} — a mutually-exclusive choice
+ * within a {@link ContextMenu.RadioGroup}, identified by its required
+ * `value`. The managed `role`, `tabIndex`, `aria-checked`, and `onSelect`
+ * host attributes are omitted.
+ */
 export type ContextMenuRadioItemProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "aria-checked" | "onSelect"
@@ -159,26 +270,52 @@ export type ContextMenuRadioItemProps = Omit<
   onSelect?: (event: Event) => void;
 };
 
-type ContextMenuSubBaseProps = {
+/**
+ * Shared base for both {@link ContextMenuSubProps} variants — just the
+ * `children` of the submenu.
+ */
+export type ContextMenuSubBaseProps = {
   children?: ReactNode;
 };
 
-type ContextMenuSubUncontrolledProps = ContextMenuSubBaseProps & {
+/**
+ * Uncontrolled variant of {@link ContextMenuSubProps}: the component owns
+ * the submenu open state. Pass `defaultOpen` (or omit it); `onOpenChange`
+ * is optional and the controlled `open` prop is forbidden.
+ */
+export type ContextMenuSubUncontrolledProps = ContextMenuSubBaseProps & {
   defaultOpen?: boolean;
   open?: never;
   onOpenChange?: (open: boolean) => void;
 };
 
-type ContextMenuSubControlledProps = ContextMenuSubBaseProps & {
+/**
+ * Controlled variant of {@link ContextMenuSubProps}: the parent owns the
+ * submenu open state. Pass `open` and `onOpenChange` together;
+ * `defaultOpen` is forbidden.
+ */
+export type ContextMenuSubControlledProps = ContextMenuSubBaseProps & {
   defaultOpen?: never;
   open: boolean;
   onOpenChange: (open: boolean) => void;
 };
 
+/**
+ * Props for {@link ContextMenu.Sub} — a nested submenu's open-state
+ * owner. A discriminated union of the uncontrolled
+ * ({@link ContextMenuSubUncontrolledProps}) and controlled
+ * ({@link ContextMenuSubControlledProps}) variants.
+ */
 export type ContextMenuSubProps =
   | ContextMenuSubUncontrolledProps
   | ContextMenuSubControlledProps;
 
+/**
+ * Props for {@link ContextMenu.SubTrigger} — the `<li>` that opens its
+ * parent {@link ContextMenu.Sub} on hover or arrow key. The managed
+ * `role`, `tabIndex`, `aria-haspopup`, `aria-expanded`, and
+ * `aria-controls` host attributes are omitted; `disabled` suppresses it.
+ */
 export type ContextMenuSubTriggerProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "aria-haspopup" | "aria-expanded" | "aria-controls"
@@ -189,6 +326,12 @@ export type ContextMenuSubTriggerProps = Omit<
   disabled?: boolean;
 };
 
+/**
+ * Props for {@link ContextMenu.SubContent} — the `<menu>` popover for a
+ * nested submenu's items. The managed `role`, `popover`, and `id`
+ * attributes are omitted; `asChild` merges the props onto a custom
+ * element.
+ */
 export type ContextMenuSubContentProps = Omit<
   ComponentProps<"menu">,
   "role" | "popover" | "id"

package/src/DirectionProvider/DirectionProvider.tsx

@@ -33,4 +33,5 @@ export function DirectionProvider({
   );
 }
 
+/** @internal */
 DirectionProvider.displayName = "DirectionProvider";

package/src/DirectionProvider/types.ts

@@ -3,6 +3,7 @@ import { ReactNode } from "react";
 /** A reading direction — left-to-right or right-to-left. */
 export type Direction = "ltr" | "rtl";
 
+/** Props for {@link DirectionProvider} — the `dir` broadcast to descendants. */
 export type DirectionProviderProps = {
   /** The reading direction broadcast to every descendant. */
   dir: Direction;

package/src/Divider/Divider.tsx

@@ -56,4 +56,5 @@ export function Divider({
   );
 }
 
+/** @internal */
 Divider.displayName = "Divider";

package/src/Divider/index.ts

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

package/src/Divider/types.ts

@@ -1,5 +1,10 @@
 import { ComponentProps } from "react";
 
+/**
+ * Props for the {@link Divider} component. Extends the native `<span>` props
+ * with an optional `orientation`.
+ */
 export type DividerProps = ComponentProps<"span"> & {
+  /** Axis the separator runs along. Defaults to `"horizontal"`. */
   orientation?: "horizontal" | "vertical";
 };

package/src/Dropdown/Dropdown.tsx

@@ -85,7 +85,7 @@ import { MENUITEM_SELECTOR } from "./constants";
  * </Dropdown.Root>
  * ```
  */
-function DropdownRoot({
+export function DropdownRoot({
   defaultOpen,
   open,
   onOpenChange,
@@ -107,6 +107,7 @@ function DropdownRoot({
   );
 }
 
+/** @internal */
 DropdownRoot.displayName = "DropdownRoot";
 
 /**
@@ -127,7 +128,7 @@ DropdownRoot.displayName = "DropdownRoot";
  * </Dropdown.Trigger>
  * ```
  */
-function DropdownTrigger({
+export function DropdownTrigger({
   children,
   onClick,
   asChild = false,
@@ -146,6 +147,7 @@ function DropdownTrigger({
   );
 }
 
+/** @internal */
 DropdownTrigger.displayName = "DropdownTrigger";
 
 /**
@@ -179,7 +181,7 @@ DropdownTrigger.displayName = "DropdownTrigger";
  * lands on the next sibling item in the parent rather than getting
  * stuck on a non-focusable item inside a closed sub-popover.
  */
-function DropdownContent({
+export function DropdownContent({
   children,
   onKeyDown,
   asChild = false,
@@ -201,6 +203,7 @@ function DropdownContent({
   );
 }
 
+/** @internal */
 DropdownContent.displayName = "DropdownContent";
 
 /**
@@ -216,7 +219,7 @@ DropdownContent.displayName = "DropdownContent";
  * Disabled items receive `aria-disabled="true"` and are skipped by arrow
  * navigation, typeahead, and activation handlers.
  */
-function DropdownItem({
+export function DropdownItem({
   children,
   onClick,
   onSelect,
@@ -238,6 +241,7 @@ function DropdownItem({
   return <li {...itemProps}>{children}</li>;
 }
 
+/** @internal */
 DropdownItem.displayName = "DropdownItem";
 
 /**
@@ -245,7 +249,7 @@ DropdownItem.displayName = "DropdownItem";
  * by default; pass `asChild` to render any element with separator semantics.
  * Non-interactive — skipped by focus, arrow navigation, and typeahead.
  */
-function DropdownSeparator({
+export function DropdownSeparator({
   asChild = false,
   children,
   ...rest
@@ -259,6 +263,7 @@ function DropdownSeparator({
   return <li {...separatorProps} />;
 }
 
+/** @internal */
 DropdownSeparator.displayName = "DropdownSeparator";
 
 /**
@@ -271,7 +276,7 @@ DropdownSeparator.displayName = "DropdownSeparator";
  * first child to provide the accessible name; screen readers will announce
  * the group when arrowing into it.
  */
-function DropdownGroup({
+export function DropdownGroup({
   children,
   asChild = false,
   ...rest
@@ -291,6 +296,7 @@ function DropdownGroup({
   );
 }
 
+/** @internal */
 DropdownGroup.displayName = "DropdownGroup";
 
 /**
@@ -302,7 +308,7 @@ DropdownGroup.displayName = "DropdownGroup";
  * Renders a `<li>` by default; pass `asChild` to render any element. A
  * caller-supplied `id` takes precedence over the auto-generated one.
  */
-function DropdownLabel({
+export function DropdownLabel({
   id,
   children,
   asChild = false,
@@ -316,6 +322,7 @@ function DropdownLabel({
   return <li {...labelProps}>{children}</li>;
 }
 
+/** @internal */
 DropdownLabel.displayName = "DropdownLabel";
 
 /**
@@ -344,7 +351,7 @@ DropdownLabel.displayName = "DropdownLabel";
  *
  * Disabled items receive `aria-disabled="true"` and no-op on activation.
  */
-function DropdownCheckboxItem({
+export function DropdownCheckboxItem({
   children,
   onClick,
   onSelect,
@@ -404,6 +411,7 @@ function DropdownCheckboxItem({
   );
 }
 
+/** @internal */
 DropdownCheckboxItem.displayName = "DropdownCheckboxItem";
 
 /**
@@ -418,7 +426,7 @@ DropdownCheckboxItem.displayName = "DropdownCheckboxItem";
  *   Optional `onValueChange` observes selections.
  * - **Controlled** — pass `value` *and* `onValueChange` together.
  */
-function DropdownRadioGroup({
+export function DropdownRadioGroup({
   defaultValue,
   value: controlledValue,
   onValueChange,
@@ -446,6 +454,7 @@ function DropdownRadioGroup({
   );
 }
 
+/** @internal */
 DropdownRadioGroup.displayName = "DropdownRadioGroup";
 
 /**
@@ -468,7 +477,7 @@ DropdownRadioGroup.displayName = "DropdownRadioGroup";
  *
  * Disabled items receive `aria-disabled="true"` and no-op on activation.
  */
-function DropdownRadioItem({
+export function DropdownRadioItem({
   children,
   onClick,
   onSelect,
@@ -526,6 +535,7 @@ function DropdownRadioItem({
   );
 }
 
+/** @internal */
 DropdownRadioItem.displayName = "DropdownRadioItem";
 
 /**
@@ -555,7 +565,7 @@ DropdownRadioItem.displayName = "DropdownRadioItem";
  * </Dropdown.CheckboxItem>
  * ```
  */
-function DropdownItemIndicator({
+export function DropdownItemIndicator({
   children,
   asChild = false,
   forceMount = false,
@@ -582,6 +592,7 @@ function DropdownItemIndicator({
   return <span {...indicatorProps}>{children}</span>;
 }
 
+/** @internal */
 DropdownItemIndicator.displayName = "DropdownItemIndicator";
 
 /**
@@ -609,7 +620,7 @@ DropdownItemIndicator.displayName = "DropdownItemIndicator";
  * </Dropdown.Root>
  * ```
  */
-function DropdownSub({
+export function DropdownSub({
   defaultOpen,
   open: controlledOpen,
   onOpenChange,
@@ -651,6 +662,7 @@ function DropdownSub({
   );
 }
 
+/** @internal */
 DropdownSub.displayName = "DropdownSub";
 
 /**
@@ -672,7 +684,7 @@ DropdownSub.displayName = "DropdownSub";
  * Disabled triggers receive `aria-disabled="true"` and ignore both click
  * and the open arrow key.
  */
-function DropdownSubTrigger({
+export function DropdownSubTrigger({
   children,
   onClick,
   onKeyDown,
@@ -721,6 +733,7 @@ function DropdownSubTrigger({
   return <li {...subTriggerProps}>{children}</li>;
 }
 
+/** @internal */
 DropdownSubTrigger.displayName = "DropdownSubTrigger";
 
 /**
@@ -737,7 +750,7 @@ DropdownSubTrigger.displayName = "DropdownSubTrigger";
  * to the parent {@link DropdownContent | `Dropdown.Content`} so arrow
  * navigation and typeahead apply to the submenu's items.
  */
-function DropdownSubContent({
+export function DropdownSubContent({
   children,
   onKeyDown,
   asChild = false,
@@ -802,9 +815,11 @@ function DropdownSubContent({
   );
 }
 
+/** @internal */
 DropdownSubContent.displayName = "DropdownSubContent";
 
-type TDropdownCompound = typeof DropdownRoot & {
+/** Type of the {@link Dropdown} compound: the root callable plus its attached sub-components. */
+export type TDropdownCompound = typeof DropdownRoot & {
   Root: typeof DropdownRoot;
   Trigger: typeof DropdownTrigger;
   Content: typeof DropdownContent;
@@ -821,6 +836,15 @@ type TDropdownCompound = typeof DropdownRoot & {
   SubContent: typeof DropdownSubContent;
 };
 
+/**
+ * Headless, accessible **Dropdown** menu — a compound component implementing the
+ * [WAI-ARIA menu-button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/)
+ * 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 (`Dropdown.Trigger`, `Dropdown.Content`, …).
+ */
 const DropdownCompound: TDropdownCompound = Object.assign(DropdownRoot, {
   Root: DropdownRoot,
   Trigger: DropdownTrigger,
@@ -838,6 +862,7 @@ const DropdownCompound: TDropdownCompound = Object.assign(DropdownRoot, {
   SubContent: DropdownSubContent,
 });
 
+/** @internal */
 DropdownCompound.displayName = "Dropdown";
 
 export { DropdownCompound as Dropdown };

package/src/Dropdown/index.ts

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