@primitiv-ui/react 0.1.0 → 0.1.2

package/src/ContextMenu/types.ts

@@ -1,9 +1,13 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
 import { CheckedState } from "../Checkbox/types";
-import { Direction } from "../DirectionProvider";
+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

@@ -1,3 +1,5 @@
+import type { ReactElement } from "react";
+
 import { DirectionContext } from "./DirectionContext";
 import { DirectionProviderProps } from "./types";
 
@@ -20,7 +22,10 @@ import { DirectionProviderProps } from "./types";
  * </DirectionProvider>
  * ```
  */
-export function DirectionProvider({ dir, children }: DirectionProviderProps) {
+export function DirectionProvider({
+  dir,
+  children,
+}: DirectionProviderProps): ReactElement {
   return (
     <DirectionContext.Provider value={dir}>
       {children}
@@ -28,4 +33,5 @@ export function DirectionProvider({ dir, children }: DirectionProviderProps) {
   );
 }
 
+/** @internal */
 DirectionProvider.displayName = "DirectionProvider";

package/src/DirectionProvider/__tests__/DirectionProvider.test.tsx

@@ -1,6 +1,6 @@
 import { render, screen } from "@testing-library/react";
 
-import { DirectionProvider, useDirection } from "..";
+import { DirectionProvider, useDirection } from "../index.ts";
 
 function DirectionProbe() {
   return <span data-testid="probe">{useDirection()}</span>;

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

@@ -1,3 +1,5 @@
+import type { ReactElement } from "react";
+
 import { DividerProps } from "./types";
 
 /**
@@ -43,7 +45,7 @@ export function Divider({
   orientation = "horizontal",
   className = "",
   ...rest
-}: DividerProps) {
+}: DividerProps): ReactElement {
   return (
     <span
       role="separator"
@@ -54,4 +56,5 @@ export function Divider({
   );
 }
 
+/** @internal */
 Divider.displayName = "Divider";

package/src/Divider/__tests__/Divider.test.tsx

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

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