@primitiv-ui/react 0.1.1 → 0.1.3

package/src/Tooltip/types.ts

@@ -1,5 +1,10 @@
 import { ComponentProps, ReactNode } from "react";
 
+/**
+ * Context published by {@link Tooltip.Provider} — the shared open / skip
+ * delays and the group-wide open coordination callbacks used to suppress
+ * the open delay while another tooltip in the group is already showing.
+ */
 export type TooltipProviderContextValue = {
   delayDuration: number;
   skipDelayDuration: number;
@@ -8,6 +13,11 @@ export type TooltipProviderContextValue = {
   onCloseGlobally: () => void;
 };
 
+/**
+ * Context published by {@link Tooltip.Root} to its descendants — the live
+ * `open` state, the content `id` for ARIA wiring, and the timing callbacks
+ * the trigger and content use to open / close with the correct delays.
+ */
 export type TooltipContextValue = {
   open: boolean;
   contentId: string;
@@ -19,46 +29,84 @@ export type TooltipContextValue = {
   cancelGrace: () => void;
 };
 
+/**
+ * Props for {@link Tooltip.Provider} — sets the `delayDuration` and
+ * `skipDelayDuration` shared by every tooltip in the subtree.
+ */
 export type TooltipProviderProps = {
   children?: ReactNode;
   delayDuration?: number;
   skipDelayDuration?: number;
 };
 
-type UncontrolledTooltipRootProps = {
+/**
+ * Uncontrolled variant of {@link TooltipRootProps}: the component owns the
+ * open state. Pass `defaultOpen` (or omit it); `onOpenChange` is optional
+ * and `open` is forbidden.
+ */
+export type UncontrolledTooltipRootProps = {
   defaultOpen?: boolean;
   open?: never;
   onOpenChange?: (open: boolean) => void;
 };
 
-type ControlledTooltipRootProps = {
+/**
+ * Controlled variant of {@link TooltipRootProps}: the parent owns the open
+ * state. Pass `open` (with an optional `onOpenChange`); `defaultOpen` is
+ * forbidden.
+ */
+export type ControlledTooltipRootProps = {
   open: boolean;
   onOpenChange?: (open: boolean) => void;
   defaultOpen?: never;
 };
 
+/**
+ * Props for {@link Tooltip.Root}. Combines the per-tooltip timing /
+ * hoverable-content options with one of the two state modes
+ * ({@link UncontrolledTooltipRootProps} | {@link ControlledTooltipRootProps}),
+ * so TypeScript accepts exactly one mode.
+ */
 export type TooltipRootProps = {
   children?: ReactNode;
   delayDuration?: number;
   disableHoverableContent?: boolean;
 } & (UncontrolledTooltipRootProps | ControlledTooltipRootProps);
 
+/**
+ * Props for {@link Tooltip.Trigger} — all native `<button>` attributes plus
+ * the `asChild` escape hatch.
+ */
 export type TooltipTriggerProps = ComponentProps<"button"> & {
   asChild?: boolean;
 };
 
+/**
+ * Props for {@link Tooltip.Portal} — the `container` to render the content
+ * into (defaults to `document.body`) and `forceMount` to keep the content
+ * in the DOM while closed for exit animations.
+ */
 export type TooltipPortalProps = {
   children?: ReactNode;
   container?: HTMLElement;
   forceMount?: boolean;
 };
 
+/**
+ * Props for {@link Tooltip.Content} — all native `<div>` attributes plus
+ * `forceMount` and the dismissal callbacks fired on Escape
+ * (`onEscapeKeyDown`) and outside pointer-down (`onPointerDownOutside`).
+ */
 export type TooltipContentProps = ComponentProps<"div"> & {
   forceMount?: boolean;
   onEscapeKeyDown?: (event: KeyboardEvent) => void;
   onPointerDownOutside?: (event: PointerEvent) => void;
 };
 
+/**
+ * Props for {@link Tooltip.Arrow} — all native `<span>` attributes plus the
+ * `asChild` escape hatch.
+ */
 export type TooltipArrowProps = ComponentProps<"span"> & {
   asChild?: boolean;
 };

package/src/Tree/Tree.tsx

@@ -116,6 +116,7 @@ export function TreeRoot(props: TreeRootProps): ReactElement {
   );
 }
 
+/** @internal */
 TreeRoot.displayName = "TreeRoot";
 
 /**
@@ -201,6 +202,7 @@ export function TreeItem({
   );
 }
 
+/** @internal */
 TreeItem.displayName = "TreeItem";
 
 /**
@@ -301,6 +303,7 @@ export function TreeBranch({
   );
 }
 
+/** @internal */
 TreeBranch.displayName = "TreeBranch";
 
 /**
@@ -349,6 +352,7 @@ export function TreeBranchControl({
   );
 }
 
+/** @internal */
 TreeBranchControl.displayName = "TreeBranchControl";
 
 /**
@@ -385,6 +389,7 @@ export function TreeBranchContent({
   );
 }
 
+/** @internal */
 TreeBranchContent.displayName = "TreeBranchContent";
 
 /**
@@ -430,6 +435,7 @@ export function TreeBranchIndicator({
   );
 }
 
+/** @internal */
 TreeBranchIndicator.displayName = "TreeBranchIndicator";
 
 /**
@@ -545,9 +551,14 @@ export function TreeSelectionPath({
   );
 }
 
+/** @internal */
 TreeSelectionPath.displayName = "TreeSelectionPath";
 
-type TreeCompound = typeof TreeRoot & {
+/**
+ * The shape of the exported `Tree` value — callable as `Tree.Root` and
+ * carrying every sub-component as a static property.
+ */
+export type TreeCompound = typeof TreeRoot & {
   Root: typeof TreeRoot;
   Item: typeof TreeItem;
   Branch: typeof TreeBranch;
@@ -557,6 +568,39 @@ type TreeCompound = typeof TreeRoot & {
   SelectionPath: typeof TreeSelectionPath;
 };
 
+/**
+ * Headless, accessible **Tree** — a compound component implementing the
+ * WAI-ARIA tree view pattern (`role="tree"` / `treeitem` / `group`) with
+ * roving tabindex, single or multiple selection, and expandable branches,
+ * with zero styles.
+ *
+ * `Tree` is both callable (an alias of {@link TreeRoot | `Tree.Root`}) and
+ * carries its sub-components as static properties:
+ *
+ * - {@link TreeRoot | `Tree.Root`} — state owner, context provider, `role="tree"`.
+ * - {@link TreeItem | `Tree.Item`} — a leaf `role="treeitem"`.
+ * - {@link TreeBranch | `Tree.Branch`} — an expandable `role="treeitem"` with children.
+ * - {@link TreeBranchControl | `Tree.BranchControl`} — the branch's selectable / toggling control.
+ * - {@link TreeBranchContent | `Tree.BranchContent`} — the collapsible `role="group"` of child nodes.
+ * - {@link TreeBranchIndicator | `Tree.BranchIndicator`} — expand/collapse affordance.
+ * - {@link TreeSelectionPath | `Tree.SelectionPath`} — breadcrumb of the selected node's ancestry.
+ *
+ * @example
+ * ```tsx
+ * import { Tree } from "@primitiv-ui/react";
+ *
+ * <Tree.Root>
+ *   <Tree.Branch value="src">
+ *     <Tree.BranchControl>
+ *       src <Tree.BranchIndicator />
+ *     </Tree.BranchControl>
+ *     <Tree.BranchContent>
+ *       <Tree.Item value="index">index.ts</Tree.Item>
+ *     </Tree.BranchContent>
+ *   </Tree.Branch>
+ * </Tree.Root>;
+ * ```
+ */
 const TreeCompound: TreeCompound = Object.assign(TreeRoot, {
   Root: TreeRoot,
   Item: TreeItem,
@@ -567,6 +611,7 @@ const TreeCompound: TreeCompound = Object.assign(TreeRoot, {
   SelectionPath: TreeSelectionPath,
 });
 
+/** @internal */
 TreeCompound.displayName = "Tree";
 
 export { TreeCompound as Tree };

package/src/Tree/index.ts

@@ -1,3 +1,3 @@
 export * from "./Tree";
+export * from "./types";
 export { useTreePath, useTreeSelectionPaths } from "./hooks/useTreePath";
-export type { TreePathSegment } from "./types";

package/src/Tree/types.ts

@@ -1,24 +1,28 @@
 import type { ComponentProps, ReactNode } from "react";
 
-type TreeRootBaseProps = ComponentProps<"div"> & {
+/** Mode-independent props shared by every `Tree.Root` variant. */
+export type TreeRootBaseProps = ComponentProps<"div"> & {
   children: ReactNode;
 };
 
-type TreeRootUncontrolledExpansionProps = {
+/** Uncontrolled expansion — initial expanded branches via `defaultExpandedValues`. */
+export type TreeRootUncontrolledExpansionProps = {
   /** Branch values expanded on first render when uncontrolled. */
   defaultExpandedValues?: string[];
   expandedValues?: never;
   onExpandedChange?: (values: string[]) => void;
 };
 
-type TreeRootControlledExpansionProps = {
+/** Controlled expansion — the expanded set is owned by the consumer. */
+export type TreeRootControlledExpansionProps = {
   defaultExpandedValues?: never;
   /** The set of expanded branch values, owned by the consumer. */
   expandedValues: string[];
   onExpandedChange: (values: string[]) => void;
 };
 
-type TreeRootSingleUncontrolledSelectionProps = {
+/** Single-selection mode, uncontrolled — initial value via `defaultSelectedValue`. */
+export type TreeRootSingleUncontrolledSelectionProps = {
   selectionMode?: "single";
   /** The value selected on first render when uncontrolled. */
   defaultSelectedValue?: string | null;
@@ -29,7 +33,8 @@ type TreeRootSingleUncontrolledSelectionProps = {
   onSelectedValuesChange?: never;
 };
 
-type TreeRootSingleControlledSelectionProps = {
+/** Single-selection mode, controlled — the selected value is owned by the consumer. */
+export type TreeRootSingleControlledSelectionProps = {
   selectionMode?: "single";
   defaultSelectedValue?: never;
   /** The selected value, owned by the consumer. */
@@ -40,7 +45,8 @@ type TreeRootSingleControlledSelectionProps = {
   onSelectedValuesChange?: never;
 };
 
-type TreeRootMultipleUncontrolledSelectionProps = {
+/** Multiple-selection mode, uncontrolled — initial values via `defaultSelectedValues`. */
+export type TreeRootMultipleUncontrolledSelectionProps = {
   selectionMode: "multiple";
   /** The values selected on first render when uncontrolled. */
   defaultSelectedValues?: string[];
@@ -51,7 +57,8 @@ type TreeRootMultipleUncontrolledSelectionProps = {
   onSelectedValueChange?: never;
 };
 
-type TreeRootMultipleControlledSelectionProps = {
+/** Multiple-selection mode, controlled — the selected values are owned by the consumer. */
+export type TreeRootMultipleControlledSelectionProps = {
   selectionMode: "multiple";
   defaultSelectedValues?: never;
   /** The selected values, owned by the consumer. */
@@ -62,6 +69,12 @@ type TreeRootMultipleControlledSelectionProps = {
   onSelectedValueChange?: never;
 };
 
+/**
+ * Props for `Tree.Root`. Combines the shared {@link TreeRootBaseProps} with
+ * one expansion arm (controlled / uncontrolled) and one selection arm
+ * (single / multiple, controlled / uncontrolled), so the relevant
+ * `value` / `defaultValue` / `onChange` shape is enforced per mode.
+ */
 export type TreeRootProps = TreeRootBaseProps &
   (TreeRootUncontrolledExpansionProps | TreeRootControlledExpansionProps) &
   (
@@ -71,6 +84,7 @@ export type TreeRootProps = TreeRootBaseProps &
     | TreeRootMultipleControlledSelectionProps
   );
 
+/** Props for `Tree.Item` — a selectable, focusable leaf treeitem. */
 export type TreeItemProps = ComponentProps<"div"> & {
   /** Stable identifier for this item, unique within the tree. */
   value: string;
@@ -88,6 +102,7 @@ export type TreeItemProps = ComponentProps<"div"> & {
   children: ReactNode;
 };
 
+/** Props for `Tree.Branch` — an expandable treeitem with nested children. */
 export type TreeBranchProps = Omit<ComponentProps<"div">, "ref"> & {
   /** Stable identifier for this branch, unique within the tree. */
   value: string;
@@ -106,12 +121,14 @@ export type TreeBranchProps = Omit<ComponentProps<"div">, "ref"> & {
   children: ReactNode;
 };
 
+/** Props for `Tree.BranchControl` — the branch's selectable, toggling control row. */
 export type TreeBranchControlProps = ComponentProps<"div"> & {
   /** Render the control as the supplied child element instead of `<div>`. */
   asChild?: boolean;
   children: ReactNode;
 };
 
+/** Props for `Tree.BranchContent` — the collapsible group of a branch's child nodes. */
 export type TreeBranchContentProps = ComponentProps<"div"> & {
   children: ReactNode;
   /**
@@ -122,6 +139,7 @@ export type TreeBranchContentProps = ComponentProps<"div"> & {
   forceMount?: boolean;
 };
 
+/** Props for `Tree.BranchIndicator` — the expand/collapse affordance. */
 export type TreeBranchIndicatorProps = ComponentProps<"span"> & {
   /** Render as the supplied child element instead of `<span>`. */
   asChild?: boolean;
@@ -133,6 +151,10 @@ export type TreeSelectionPathRenderProps = {
   paths: TreePathSegment[][];
 };
 
+/**
+ * Props for `Tree.SelectionPath` — a breadcrumb of the selected node's
+ * root-to-leaf ancestry, with an optional render-prop for custom layout.
+ */
 export type TreeSelectionPathProps = Omit<ComponentProps<"div">, "children"> & {
   /**
    * Either standard React children (ignored — the subcomponent does its
@@ -147,6 +169,7 @@ export type TreeSelectionPathProps = Omit<ComponentProps<"div">, "children"> & {
   separator?: ReactNode;
 };
 
+/** Per-level context — the nesting depth and enclosing branch value, shared down each subtree. */
 export type TreeLevelContextValue = {
   /** Zero-based nesting depth — `0` for items directly inside `Tree.Root`. */
   depth: number;
@@ -154,6 +177,7 @@ export type TreeLevelContextValue = {
   parentValue: string | null;
 };
 
+/** Registry entry for one tree node — its value, element, and structural metadata. */
 export type TreeNodeMeta = {
   value: string;
   element: HTMLElement;
@@ -177,14 +201,21 @@ export type TreePathSegment = {
   depth: number;
 };
 
+/** Whether the tree allows one selected node (`"single"`) or many (`"multiple"`). */
 export type SelectionMode = "single" | "multiple";
 
+/** Keyboard/pointer modifiers that influence a selection gesture. */
 export type TreeSelectModifiers = {
   meta: boolean;
   ctrl: boolean;
   shift: boolean;
 };
 
+/**
+ * Context shared from `Tree.Root` to every descendant — selection and
+ * expansion state, the node registry, roving-tabindex bookkeeping, and the
+ * path resolver.
+ */
 export type TreeContextValue = {
   /** Stable id shared across the tree, used to derive ARIA wiring ids. */
   rootId: string;
@@ -215,6 +246,7 @@ export type TreeContextValue = {
   selectedOrder: readonly string[];
 };
 
+/** Context a branch shares with its own control and content — its value, expanded/disabled state, and control id. */
 export type TreeItemContextValue = {
   value: string;
   expanded: boolean;

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -65,4 +65,5 @@ export function VisuallyHidden({
   return <span {...rootProps}>{children}</span>;
 }
 
+/** @internal */
 VisuallyHidden.displayName = "VisuallyHidden";

package/src/VisuallyHidden/types.ts

@@ -1,5 +1,9 @@
 import { ComponentProps } from "react";
 
+/**
+ * Props for {@link VisuallyHidden} — all native `<span>` attributes plus
+ * the `asChild` escape hatch.
+ */
 export type VisuallyHiddenProps = ComponentProps<"span"> & {
   asChild?: boolean;
 };

package/src/index.ts

@@ -36,3 +36,4 @@ export * from "./ToggleGroup/index.ts";
 export * from "./Tooltip/index.ts";
 export * from "./Tree/index.ts";
 export * from "./VisuallyHidden/index.ts";
+export type { HeadingLevel } from "./types.ts";

package/src/types.ts

@@ -8,6 +8,7 @@ export type PossibleRef<T> = Ref<T> | undefined;
 
 export type AnyProps = Record<string, unknown>;
 
+/** A heading level, `1`–`6`, mapped to an `<h1>`–`<h6>` element. */
 export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 
 export type HeadingTag = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";