@primitiv-ui/react 0.1.1 → 0.1.3

package/src/Dropdown/types.ts

@@ -3,7 +3,11 @@ import { ComponentProps, ReactNode, Ref } from "react";
 import { CheckedState } from "../Checkbox/types";
 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

@@ -36,7 +36,7 @@ import {
  * )}
  * ```
  */
-function EmptyStateRoot({
+export function EmptyStateRoot({
   asChild = false,
   children,
   ...rest
@@ -50,6 +50,7 @@ function EmptyStateRoot({
   return <div {...rootProps}>{children}</div>;
 }
 
+/** @internal */
 EmptyStateRoot.displayName = "EmptyStateRoot";
 
 /**
@@ -74,7 +75,7 @@ EmptyStateRoot.displayName = "EmptyStateRoot";
  * </EmptyState.Media>
  * ```
  */
-function EmptyStateMedia({
+export function EmptyStateMedia({
   asChild = false,
   children,
   ...rest
@@ -88,6 +89,7 @@ function EmptyStateMedia({
   return <div {...mediaProps}>{children}</div>;
 }
 
+/** @internal */
 EmptyStateMedia.displayName = "EmptyStateMedia";
 
 /**
@@ -109,7 +111,7 @@ EmptyStateMedia.displayName = "EmptyStateMedia";
  * </EmptyState.Title>
  * ```
  */
-function EmptyStateTitle({
+export function EmptyStateTitle({
   asChild = false,
   children,
   ...rest
@@ -121,6 +123,7 @@ function EmptyStateTitle({
   return <p {...rest}>{children}</p>;
 }
 
+/** @internal */
 EmptyStateTitle.displayName = "EmptyStateTitle";
 
 /**
@@ -139,7 +142,7 @@ EmptyStateTitle.displayName = "EmptyStateTitle";
  * <EmptyState.Description>Try adjusting your filters.</EmptyState.Description>
  * ```
  */
-function EmptyStateDescription({
+export function EmptyStateDescription({
   asChild = false,
   children,
   ...rest
@@ -151,6 +154,7 @@ function EmptyStateDescription({
   return <p {...rest}>{children}</p>;
 }
 
+/** @internal */
 EmptyStateDescription.displayName = "EmptyStateDescription";
 
 /**
@@ -173,7 +177,7 @@ EmptyStateDescription.displayName = "EmptyStateDescription";
  * </EmptyState.Actions>
  * ```
  */
-function EmptyStateActions({
+export function EmptyStateActions({
   asChild = false,
   children,
   ...rest
@@ -185,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.
@@ -242,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/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

@@ -46,7 +46,7 @@ import {
  * </Field.Root>
  * ```
  */
-function FieldRoot({
+export function FieldRoot({
   id: idProp,
   invalid = false,
   disabled = false,
@@ -84,6 +84,7 @@ function FieldRoot({
   );
 }
 
+/** @internal */
 FieldRoot.displayName = "FieldRoot";
 
 /**
@@ -95,7 +96,7 @@ FieldRoot.displayName = "FieldRoot";
  *
  * @throws If rendered outside a `<Field.Root>`.
  */
-function FieldLabel({
+export function FieldLabel({
   asChild = false,
   children,
   ...rest
@@ -109,6 +110,7 @@ function FieldLabel({
   return <label {...labelProps}>{children}</label>;
 }
 
+/** @internal */
 FieldLabel.displayName = "FieldLabel";
 
 /**
@@ -122,7 +124,7 @@ FieldLabel.displayName = "FieldLabel";
  *
  * @throws If rendered outside a `<Field.Root>`.
  */
-function FieldDescription({
+export function FieldDescription({
   asChild = false,
   children,
   ...rest
@@ -136,6 +138,7 @@ function FieldDescription({
   return <div {...descriptionProps}>{children}</div>;
 }
 
+/** @internal */
 FieldDescription.displayName = "FieldDescription";
 
 /**
@@ -156,7 +159,7 @@ FieldDescription.displayName = "FieldDescription";
  *
  * @throws If rendered outside a `<Field.Root>`.
  */
-function FieldErrorText({
+export function FieldErrorText({
   asChild = false,
   children,
   ...rest
@@ -171,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/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;

package/src/Fieldset/Fieldset.tsx

@@ -29,7 +29,7 @@ import { FieldsetLegendProps, FieldsetProps } from "./types";
  * </Fieldset.Root>
  * ```
  */
-function Fieldset({
+export function FieldsetRoot({
   disabled,
   children,
   ...rest
@@ -45,7 +45,8 @@ function Fieldset({
   );
 }
 
-Fieldset.displayName = "Fieldset";
+/** @internal */
+FieldsetRoot.displayName = "Fieldset";
 
 /**
  * The caption for a {@link Fieldset} — renders a native `<legend>`.
@@ -59,25 +60,25 @@ Fieldset.displayName = "Fieldset";
  * <Fieldset.Legend>Shipping address</Fieldset.Legend>
  * ```
  */
-function FieldsetLegend({
+export function FieldsetLegend({
   children,
   ...rest
 }: FieldsetLegendProps): ReactElement {
   return <legend {...rest}>{children}</legend>;
 }
 
+/** @internal */
 FieldsetLegend.displayName = "FieldsetLegend";
 
-type FieldsetCompound = typeof Fieldset & {
-  Root: typeof Fieldset;
+/**
+ * The shape of the exported `Fieldset` value — callable as
+ * `Fieldset.Root` and carrying `Root` and `Legend` as static properties.
+ */
+export type FieldsetCompound = typeof FieldsetRoot & {
+  Root: typeof FieldsetRoot;
   Legend: typeof FieldsetLegend;
 };
 
-const FieldsetCompound: FieldsetCompound = Object.assign(Fieldset, {
-  Root: Fieldset,
-  Legend: FieldsetLegend,
-});
-
 /**
  * Headless, accessible **Fieldset** — a stateless compound component that
  * groups related form controls, with zero styles.
@@ -108,6 +109,12 @@ const FieldsetCompound: FieldsetCompound = Object.assign(Fieldset, {
  * </Fieldset.Root>
  * ```
  */
+const FieldsetCompound: FieldsetCompound = Object.assign(FieldsetRoot, {
+  Root: FieldsetRoot,
+  Legend: FieldsetLegend,
+});
+
+/** @internal */
 FieldsetCompound.displayName = "Fieldset";
 
 export { FieldsetCompound as Fieldset };

package/src/Fieldset/types.ts

@@ -1,5 +1,7 @@
 import { ComponentProps } from "react";
 
+/** Props for `Fieldset.Root` — the native `<fieldset>` attributes. */
 export type FieldsetProps = ComponentProps<"fieldset">;
 
+/** Props for `Fieldset.Legend` — the native `<legend>` attributes. */
 export type FieldsetLegendProps = ComponentProps<"legend">;

package/src/Input/Input.tsx

@@ -119,4 +119,5 @@ export function Input({
   return <input type={type} {...rootProps} />;
 }
 
+/** @internal */
 Input.displayName = "Input";

package/src/Input/types.ts

@@ -1,5 +1,9 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
+/**
+ * Props for {@link Input} — all native `<input>` attributes plus the
+ * `asChild` escape hatch and a typed `ref`.
+ */
 export type InputProps = ComponentProps<"input"> & {
   asChild?: boolean;
   ref?: Ref<HTMLInputElement>;