@primitiv-ui/react 0.1.0 → 0.1.2

package/src/Dropdown/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 DropdownRootBaseProps = {
+/**
+ * Shared base for both {@link DropdownRootProps} variants — `children` plus
+ * the reading-direction control.
+ */
+export type DropdownRootBaseProps = {
   children?: ReactNode;
   /**
    * Reading direction for the menu. Affects which arrow key opens / closes
@@ -14,22 +18,42 @@ type DropdownRootBaseProps = {
   dir?: Direction;
 };
 
-type DropdownRootUncontrolledProps = DropdownRootBaseProps & {
+/**
+ * Uncontrolled variant of {@link DropdownRootProps}: the component owns the
+ * open state. Pass `defaultOpen` (or omit it); `onOpenChange` is optional
+ * and `open` is forbidden.
+ */
+export type DropdownRootUncontrolledProps = DropdownRootBaseProps & {
   defaultOpen?: boolean;
   open?: never;
   onOpenChange?: (open: boolean) => void;
 };
 
-type DropdownRootControlledProps = DropdownRootBaseProps & {
+/**
+ * Controlled variant of {@link DropdownRootProps}: the parent owns the open
+ * state. Pass `open` and `onOpenChange` together; `defaultOpen` is
+ * forbidden.
+ */
+export type DropdownRootControlledProps = DropdownRootBaseProps & {
   defaultOpen?: never;
   open: boolean;
   onOpenChange: (open: boolean) => void;
 };
 
+/**
+ * Props for {@link Dropdown.Root} — the controlled/uncontrolled discriminated
+ * union pairing {@link DropdownRootUncontrolledProps} with
+ * {@link DropdownRootControlledProps}, plus the shared `children` and `dir`.
+ */
 export type DropdownRootProps =
   | DropdownRootUncontrolledProps
   | DropdownRootControlledProps;
 
+/**
+ * Props for {@link Dropdown.Trigger} — the button that opens the menu. Extends
+ * the native `<button>` props (minus the ARIA attributes Dropdown owns) and
+ * adds `asChild` for rendering a custom element.
+ */
 export type DropdownTriggerProps = Omit<
   ComponentProps<"button">,
   "aria-haspopup" | "aria-expanded" | "aria-controls"
@@ -39,6 +63,11 @@ export type DropdownTriggerProps = Omit<
   asChild?: boolean;
 };
 
+/**
+ * Props for {@link Dropdown.Content} — the popover menu surface. Extends the
+ * native `<menu>` props (minus the `role`/`popover`/`id` Dropdown manages) and
+ * adds `asChild` for rendering a custom element.
+ */
 export type DropdownContentProps = Omit<
   ComponentProps<"menu">,
   "role" | "popover" | "id"
@@ -48,6 +77,11 @@ export type DropdownContentProps = Omit<
   asChild?: boolean;
 };
 
+/**
+ * Props for {@link Dropdown.Item} — a selectable menu item. Extends the native
+ * `<li>` props and adds `disabled`, `asChild`, and an `onSelect` callback that
+ * fires on activation (click, Enter, or Space).
+ */
 export type DropdownItemProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "onSelect"
@@ -64,12 +98,21 @@ export type DropdownItemProps = Omit<
   onSelect?: (event: Event) => void;
 };
 
+/**
+ * Props for {@link Dropdown.Separator} — a non-interactive divider between
+ * groups of items. Extends the native `<li>` props and adds `asChild`.
+ */
 export type DropdownSeparatorProps = Omit<ComponentProps<"li">, "role"> & {
   children?: ReactNode;
   ref?: Ref<HTMLLIElement>;
   asChild?: boolean;
 };
 
+/**
+ * Props for {@link Dropdown.ItemIndicator} — the check/dot rendered inside a
+ * checkbox or radio item. Extends the native `<span>` props and adds
+ * `forceMount` to keep it mounted while unchecked for enter/exit animation.
+ */
 export type DropdownItemIndicatorProps = ComponentProps<"span"> & {
   children?: ReactNode;
   ref?: Ref<HTMLSpanElement>;
@@ -83,19 +126,31 @@ export type DropdownItemIndicatorProps = ComponentProps<"span"> & {
   forceMount?: boolean;
 };
 
+/**
+ * Props for {@link Dropdown.Group} — a labelled grouping of related items.
+ * Extends the native `<li>` props and adds `asChild`.
+ */
 export type DropdownGroupProps = Omit<ComponentProps<"li">, "role"> & {
   children?: ReactNode;
   ref?: Ref<HTMLLIElement>;
   asChild?: boolean;
 };
 
+/**
+ * Props for {@link Dropdown.Label} — an accessible label for a
+ * {@link Dropdown.Group}. Extends the native `<li>` props and adds `asChild`.
+ */
 export type DropdownLabelProps = ComponentProps<"li"> & {
   children?: ReactNode;
   ref?: Ref<HTMLLIElement>;
   asChild?: boolean;
 };
 
-type DropdownCheckboxItemBaseProps = Omit<
+/**
+ * Shared base for both {@link DropdownCheckboxItemProps} variants — the native
+ * `<li>` props plus `disabled`, `asChild`, and the `onSelect` callback.
+ */
+export type DropdownCheckboxItemBaseProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "aria-checked" | "defaultChecked" | "onSelect"
 > & {
@@ -110,44 +165,88 @@ type DropdownCheckboxItemBaseProps = Omit<
   onSelect?: (event: Event) => void;
 };
 
-type DropdownCheckboxItemUncontrolledProps = DropdownCheckboxItemBaseProps & {
-  defaultChecked?: CheckedState;
-  checked?: never;
-  onCheckedChange?: (checked: boolean) => void;
-};
+/**
+ * Uncontrolled variant of {@link DropdownCheckboxItemProps}: the component owns
+ * the checked state. Pass `defaultChecked` (or omit it); `onCheckedChange` is
+ * optional and the controlled `checked` prop is forbidden.
+ */
+export type DropdownCheckboxItemUncontrolledProps =
+  DropdownCheckboxItemBaseProps & {
+    defaultChecked?: CheckedState;
+    checked?: never;
+    onCheckedChange?: (checked: boolean) => void;
+  };
 
-type DropdownCheckboxItemControlledProps = DropdownCheckboxItemBaseProps & {
-  defaultChecked?: never;
-  checked: CheckedState;
-  onCheckedChange: (checked: boolean) => void;
-};
+/**
+ * Controlled variant of {@link DropdownCheckboxItemProps}: the parent owns the
+ * checked state. Pass `checked` and `onCheckedChange` together;
+ * `defaultChecked` is forbidden.
+ */
+export type DropdownCheckboxItemControlledProps =
+  DropdownCheckboxItemBaseProps & {
+    defaultChecked?: never;
+    checked: CheckedState;
+    onCheckedChange: (checked: boolean) => void;
+  };
 
+/**
+ * Props for {@link Dropdown.CheckboxItem} — a togglable menu item. The
+ * controlled/uncontrolled discriminated union pairing
+ * {@link DropdownCheckboxItemUncontrolledProps} with
+ * {@link DropdownCheckboxItemControlledProps}.
+ */
 export type DropdownCheckboxItemProps =
   | DropdownCheckboxItemUncontrolledProps
   | DropdownCheckboxItemControlledProps;
 
-type DropdownRadioGroupBaseProps = Omit<ComponentProps<"li">, "role"> & {
+/**
+ * Shared base for both {@link DropdownRadioGroupProps} variants — the native
+ * `<li>` props plus `asChild`.
+ */
+export type DropdownRadioGroupBaseProps = Omit<ComponentProps<"li">, "role"> & {
   children?: ReactNode;
   ref?: Ref<HTMLLIElement>;
   asChild?: boolean;
 };
 
-type DropdownRadioGroupUncontrolledProps = DropdownRadioGroupBaseProps & {
-  defaultValue?: string;
-  value?: never;
-  onValueChange?: (value: string) => void;
-};
+/**
+ * Uncontrolled variant of {@link DropdownRadioGroupProps}: the component owns
+ * the selected value. Pass `defaultValue` (or omit it); `onValueChange` is
+ * optional and the controlled `value` prop is forbidden.
+ */
+export type DropdownRadioGroupUncontrolledProps =
+  DropdownRadioGroupBaseProps & {
+    defaultValue?: string;
+    value?: never;
+    onValueChange?: (value: string) => void;
+  };
 
-type DropdownRadioGroupControlledProps = DropdownRadioGroupBaseProps & {
+/**
+ * Controlled variant of {@link DropdownRadioGroupProps}: the parent owns the
+ * selected value. Pass `value` and `onValueChange` together; `defaultValue` is
+ * forbidden.
+ */
+export type DropdownRadioGroupControlledProps = DropdownRadioGroupBaseProps & {
   defaultValue?: never;
   value: string;
   onValueChange: (value: string) => void;
 };
 
+/**
+ * Props for {@link Dropdown.RadioGroup} — a single-select group of radio items.
+ * The controlled/uncontrolled discriminated union pairing
+ * {@link DropdownRadioGroupUncontrolledProps} with
+ * {@link DropdownRadioGroupControlledProps}.
+ */
 export type DropdownRadioGroupProps =
   | DropdownRadioGroupUncontrolledProps
   | DropdownRadioGroupControlledProps;
 
+/**
+ * Props for {@link Dropdown.RadioItem} — one option within a
+ * {@link Dropdown.RadioGroup}. Extends the native `<li>` props and adds the
+ * required `value`, plus `disabled`, `asChild`, and `onSelect`.
+ */
 export type DropdownRadioItemProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "aria-checked" | "onSelect"
@@ -160,26 +259,50 @@ export type DropdownRadioItemProps = Omit<
   onSelect?: (event: Event) => void;
 };
 
-type DropdownSubBaseProps = {
+/**
+ * Shared base for both {@link DropdownSubProps} variants — just the submenu
+ * `children`.
+ */
+export type DropdownSubBaseProps = {
   children?: ReactNode;
 };
 
-type DropdownSubUncontrolledProps = DropdownSubBaseProps & {
+/**
+ * Uncontrolled variant of {@link DropdownSubProps}: the component owns the
+ * submenu open state. Pass `defaultOpen` (or omit it); `onOpenChange` is
+ * optional and the controlled `open` prop is forbidden.
+ */
+export type DropdownSubUncontrolledProps = DropdownSubBaseProps & {
   defaultOpen?: boolean;
   open?: never;
   onOpenChange?: (open: boolean) => void;
 };
 
-type DropdownSubControlledProps = DropdownSubBaseProps & {
+/**
+ * Controlled variant of {@link DropdownSubProps}: the parent owns the submenu
+ * open state. Pass `open` and `onOpenChange` together; `defaultOpen` is
+ * forbidden.
+ */
+export type DropdownSubControlledProps = DropdownSubBaseProps & {
   defaultOpen?: never;
   open: boolean;
   onOpenChange: (open: boolean) => void;
 };
 
+/**
+ * Props for {@link Dropdown.Sub} — the root of a nested submenu. The
+ * controlled/uncontrolled discriminated union pairing
+ * {@link DropdownSubUncontrolledProps} with {@link DropdownSubControlledProps}.
+ */
 export type DropdownSubProps =
   | DropdownSubUncontrolledProps
   | DropdownSubControlledProps;
 
+/**
+ * Props for {@link Dropdown.SubTrigger} — the item that opens a submenu.
+ * Extends the native `<li>` props (minus the ARIA attributes Dropdown owns) and
+ * adds `disabled` and `asChild`.
+ */
 export type DropdownSubTriggerProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "aria-haspopup" | "aria-expanded" | "aria-controls"
@@ -190,6 +313,11 @@ export type DropdownSubTriggerProps = Omit<
   disabled?: boolean;
 };
 
+/**
+ * Props for {@link Dropdown.SubContent} — the popover surface of a submenu.
+ * Extends the native `<menu>` props (minus the `role`/`popover`/`id` Dropdown
+ * manages) and adds `asChild`.
+ */
 export type DropdownSubContentProps = Omit<
   ComponentProps<"menu">,
   "role" | "popover" | "id"

package/src/EmptyState/EmptyState.tsx

@@ -1,4 +1,6 @@
-import { Slot } from "../Slot";
+import type { ReactElement } from "react";
+
+import { Slot } from "../Slot/index.ts";
 import {
   EmptyStateActionsProps,
   EmptyStateDescriptionProps,
@@ -34,11 +36,11 @@ import {
  * )}
  * ```
  */
-function EmptyStateRoot({
+export function EmptyStateRoot({
   asChild = false,
   children,
   ...rest
-}: EmptyStateRootProps) {
+}: EmptyStateRootProps): ReactElement {
   const rootProps = { role: "status", ...rest };
 
   if (asChild) {
@@ -48,6 +50,7 @@ function EmptyStateRoot({
   return <div {...rootProps}>{children}</div>;
 }
 
+/** @internal */
 EmptyStateRoot.displayName = "EmptyStateRoot";
 
 /**
@@ -72,11 +75,11 @@ EmptyStateRoot.displayName = "EmptyStateRoot";
  * </EmptyState.Media>
  * ```
  */
-function EmptyStateMedia({
+export function EmptyStateMedia({
   asChild = false,
   children,
   ...rest
-}: EmptyStateMediaProps) {
+}: EmptyStateMediaProps): ReactElement {
   const mediaProps = { "aria-hidden": true, ...rest };
 
   if (asChild) {
@@ -86,6 +89,7 @@ function EmptyStateMedia({
   return <div {...mediaProps}>{children}</div>;
 }
 
+/** @internal */
 EmptyStateMedia.displayName = "EmptyStateMedia";
 
 /**
@@ -107,11 +111,11 @@ EmptyStateMedia.displayName = "EmptyStateMedia";
  * </EmptyState.Title>
  * ```
  */
-function EmptyStateTitle({
+export function EmptyStateTitle({
   asChild = false,
   children,
   ...rest
-}: EmptyStateTitleProps) {
+}: EmptyStateTitleProps): ReactElement {
   if (asChild) {
     return <Slot {...rest}>{children}</Slot>;
   }
@@ -119,6 +123,7 @@ function EmptyStateTitle({
   return <p {...rest}>{children}</p>;
 }
 
+/** @internal */
 EmptyStateTitle.displayName = "EmptyStateTitle";
 
 /**
@@ -137,11 +142,11 @@ EmptyStateTitle.displayName = "EmptyStateTitle";
  * <EmptyState.Description>Try adjusting your filters.</EmptyState.Description>
  * ```
  */
-function EmptyStateDescription({
+export function EmptyStateDescription({
   asChild = false,
   children,
   ...rest
-}: EmptyStateDescriptionProps) {
+}: EmptyStateDescriptionProps): ReactElement {
   if (asChild) {
     return <Slot {...rest}>{children}</Slot>;
   }
@@ -149,6 +154,7 @@ function EmptyStateDescription({
   return <p {...rest}>{children}</p>;
 }
 
+/** @internal */
 EmptyStateDescription.displayName = "EmptyStateDescription";
 
 /**
@@ -171,11 +177,11 @@ EmptyStateDescription.displayName = "EmptyStateDescription";
  * </EmptyState.Actions>
  * ```
  */
-function EmptyStateActions({
+export function EmptyStateActions({
   asChild = false,
   children,
   ...rest
-}: EmptyStateActionsProps) {
+}: EmptyStateActionsProps): ReactElement {
   if (asChild) {
     return <Slot {...rest}>{children}</Slot>;
   }
@@ -183,24 +189,23 @@ function EmptyStateActions({
   return <div {...rest}>{children}</div>;
 }
 
+/** @internal */
 EmptyStateActions.displayName = "EmptyStateActions";
 
-type EmptyStateCompound = typeof EmptyStateRoot & {
+/** Type of the {@link EmptyState} compound — the Root callable plus its sub-components. */
+export type EmptyStateCompound = typeof EmptyStateRoot & {
+  /** The `<div role="status">` live region wrapping the placeholder. */
   Root: typeof EmptyStateRoot;
+  /** The decorative icon/illustration slot. */
   Media: typeof EmptyStateMedia;
+  /** The headline. */
   Title: typeof EmptyStateTitle;
+  /** The supporting copy. */
   Description: typeof EmptyStateDescription;
+  /** The recovery-action slot. */
   Actions: typeof EmptyStateActions;
 };
 
-const EmptyState: EmptyStateCompound = Object.assign(EmptyStateRoot, {
-  Root: EmptyStateRoot,
-  Media: EmptyStateMedia,
-  Title: EmptyStateTitle,
-  Description: EmptyStateDescription,
-  Actions: EmptyStateActions,
-});
-
 /**
  * Headless, accessible **Empty State** — a stateless compound component for
  * the placeholder shown when a collection, search, or view has no content.
@@ -240,6 +245,15 @@ const EmptyState: EmptyStateCompound = Object.assign(EmptyStateRoot, {
  * )}
  * ```
  */
+const EmptyState: EmptyStateCompound = Object.assign(EmptyStateRoot, {
+  Root: EmptyStateRoot,
+  Media: EmptyStateMedia,
+  Title: EmptyStateTitle,
+  Description: EmptyStateDescription,
+  Actions: EmptyStateActions,
+});
+
+/** @internal */
 EmptyState.displayName = "EmptyState";
 
 export { EmptyState };

package/src/EmptyState/__tests__/EmptyState.Actions.test.tsx

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

package/src/EmptyState/__tests__/EmptyState.Description.test.tsx

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

package/src/EmptyState/__tests__/EmptyState.Media.test.tsx

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

package/src/EmptyState/__tests__/EmptyState.Root.test.tsx

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

package/src/EmptyState/__tests__/EmptyState.Title.test.tsx

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

package/src/EmptyState/types.ts

@@ -1,6 +1,7 @@
 import { ComponentProps } from "react";
 
-type WithAsChild = {
+/** Mixin adding the `asChild` opt-in to a sub-component's props. */
+export type WithAsChild = {
   /** Render the consumer's own element instead of the default, via `Slot`. */
   asChild?: boolean;
 };

package/src/Field/Field.tsx

@@ -1,8 +1,9 @@
 import { useId, useMemo } from "react";
+import type { ReactElement } from "react";
 
-import { Slot } from "../Slot";
+import { Slot } from "../Slot/index.ts";
 import { FieldContext } from "./FieldContext";
-import { useFieldContext } from "./hooks";
+import { useFieldContext } from "./hooks/index.ts";
 import {
   FieldDescriptionProps,
   FieldErrorTextProps,
@@ -45,7 +46,7 @@ import {
  * </Field.Root>
  * ```
  */
-function FieldRoot({
+export function FieldRoot({
   id: idProp,
   invalid = false,
   disabled = false,
@@ -53,7 +54,7 @@ function FieldRoot({
   asChild = false,
   children,
   ...rest
-}: FieldRootProps) {
+}: FieldRootProps): ReactElement {
   const autoId = useId();
   const id = idProp ?? autoId;
   const descriptionId = `${id}-description`;
@@ -83,6 +84,7 @@ function FieldRoot({
   );
 }
 
+/** @internal */
 FieldRoot.displayName = "FieldRoot";
 
 /**
@@ -94,7 +96,11 @@ FieldRoot.displayName = "FieldRoot";
  *
  * @throws If rendered outside a `<Field.Root>`.
  */
-function FieldLabel({ asChild = false, children, ...rest }: FieldLabelProps) {
+export function FieldLabel({
+  asChild = false,
+  children,
+  ...rest
+}: FieldLabelProps): ReactElement {
   const { id } = useFieldContext();
   const labelProps = { ...rest, htmlFor: id };
 
@@ -104,6 +110,7 @@ function FieldLabel({ asChild = false, children, ...rest }: FieldLabelProps) {
   return <label {...labelProps}>{children}</label>;
 }
 
+/** @internal */
 FieldLabel.displayName = "FieldLabel";
 
 /**
@@ -117,11 +124,11 @@ FieldLabel.displayName = "FieldLabel";
  *
  * @throws If rendered outside a `<Field.Root>`.
  */
-function FieldDescription({
+export function FieldDescription({
   asChild = false,
   children,
   ...rest
-}: FieldDescriptionProps) {
+}: FieldDescriptionProps): ReactElement {
   const { descriptionId } = useFieldContext();
   const descriptionProps = { ...rest, id: descriptionId };
 
@@ -131,6 +138,7 @@ function FieldDescription({
   return <div {...descriptionProps}>{children}</div>;
 }
 
+/** @internal */
 FieldDescription.displayName = "FieldDescription";
 
 /**
@@ -151,11 +159,11 @@ FieldDescription.displayName = "FieldDescription";
  *
  * @throws If rendered outside a `<Field.Root>`.
  */
-function FieldErrorText({
+export function FieldErrorText({
   asChild = false,
   children,
   ...rest
-}: FieldErrorTextProps) {
+}: FieldErrorTextProps): ReactElement | null {
   const { errorId, invalid } = useFieldContext();
   if (!invalid) return null;
   const errorProps = { ...rest, id: errorId, role: "alert" as const };
@@ -166,12 +174,18 @@ function FieldErrorText({
   return <div {...errorProps}>{children}</div>;
 }
 
+/** @internal */
 FieldErrorText.displayName = "FieldErrorText";
 
-type TFieldCompound = typeof FieldRoot & {
+/** Type of the {@link Field} compound — the Root callable plus its sub-components. */
+export type TFieldCompound = typeof FieldRoot & {
+  /** The wrapper that owns shared field state and context. */
   Root: typeof FieldRoot;
+  /** The field's label. */
   Label: typeof FieldLabel;
+  /** The field's supporting helper text. */
   Description: typeof FieldDescription;
+  /** The error message shown when invalid. */
   ErrorText: typeof FieldErrorText;
 };
 

package/src/Field/FieldContext.ts

@@ -1,4 +1,4 @@
-import { createStrictContext } from "../utils";
+import { createStrictContext } from "../utils/index.ts";
 
 export type FieldContextValue = {
   /** Stable id for the control wired to this field. */

package/src/Field/types.ts

@@ -1,5 +1,6 @@
 import { ComponentProps, ReactNode } from "react";
 
+/** Props for `Field.Root`, the wrapper that owns shared field state. */
 export type FieldRootProps = ComponentProps<"div"> & {
   /** Stable id wired to the control via {@link FieldLabel}'s `htmlFor`. Auto-generated via `useId` when omitted. */
   id?: string;
@@ -14,18 +15,21 @@ export type FieldRootProps = ComponentProps<"div"> & {
   children?: ReactNode;
 };
 
+/** Props for `Field.Label`, the field's `<label>`. */
 export type FieldLabelProps = ComponentProps<"label"> & {
   /** Renders the consumer element instead of `<label>` via Slot. */
   asChild?: boolean;
   children?: ReactNode;
 };
 
+/** Props for `Field.Description`, the field's supporting helper text. */
 export type FieldDescriptionProps = ComponentProps<"div"> & {
   /** Renders the consumer element instead of `<div>` via Slot. */
   asChild?: boolean;
   children?: ReactNode;
 };
 
+/** Props for `Field.ErrorText`, the error message shown when invalid. */
 export type FieldErrorTextProps = ComponentProps<"div"> & {
   /** Renders the consumer element instead of `<div>` via Slot. */
   asChild?: boolean;