@primitiv-ui/react 0.1.1 → 0.1.2

package/src/Table/Table.tsx

@@ -42,11 +42,12 @@ import {
  * </Table.Root>
  * ```
  */
-function Table({ children, ...rest }: TableRootProps): ReactElement {
+export function TableRoot({ children, ...rest }: TableRootProps): ReactElement {
   return <table {...rest}>{children}</table>;
 }
 
-Table.displayName = "Table";
+/** @internal */
+TableRoot.displayName = "Table";
 
 /**
  * Groups header rows inside a `<thead>` element.
@@ -65,10 +66,11 @@ Table.displayName = "Table";
  * </Table.Head>
  * ```
  */
-function TableHead({ children, ...rest }: TableHeadProps): ReactElement {
+export function TableHead({ children, ...rest }: TableHeadProps): ReactElement {
   return <thead {...rest}>{children}</thead>;
 }
 
+/** @internal */
 TableHead.displayName = "TableHead";
 
 /**
@@ -89,10 +91,11 @@ TableHead.displayName = "TableHead";
  * </Table.Body>
  * ```
  */
-function TableBody({ children, ...rest }: TableBodyProps): ReactElement {
+export function TableBody({ children, ...rest }: TableBodyProps): ReactElement {
   return <tbody {...rest}>{children}</tbody>;
 }
 
+/** @internal */
 TableBody.displayName = "TableBody";
 
 /**
@@ -112,10 +115,14 @@ TableBody.displayName = "TableBody";
  * </Table.Footer>
  * ```
  */
-function TableFooter({ children, ...rest }: TableFooterProps): ReactElement {
+export function TableFooter({
+  children,
+  ...rest
+}: TableFooterProps): ReactElement {
   return <tfoot {...rest}>{children}</tfoot>;
 }
 
+/** @internal */
 TableFooter.displayName = "TableFooter";
 
 /**
@@ -134,10 +141,11 @@ TableFooter.displayName = "TableFooter";
  * </Table.Row>
  * ```
  */
-function TableRow({ children, ...rest }: TableRowProps): ReactElement {
+export function TableRow({ children, ...rest }: TableRowProps): ReactElement {
   return <tr {...rest}>{children}</tr>;
 }
 
+/** @internal */
 TableRow.displayName = "TableRow";
 
 /**
@@ -168,10 +176,14 @@ TableRow.displayName = "TableRow";
  * <Table.Header scope="row">Alice</Table.Header>
  * ```
  */
-function TableHeader({ children, ...rest }: TableHeaderProps): ReactElement {
+export function TableHeader({
+  children,
+  ...rest
+}: TableHeaderProps): ReactElement {
   return <th {...rest}>{children}</th>;
 }
 
+/** @internal */
 TableHeader.displayName = "TableHeader";
 
 /**
@@ -190,10 +202,11 @@ TableHeader.displayName = "TableHeader";
  * <Table.Cell colSpan={2}>Full-width note</Table.Cell>
  * ```
  */
-function TableCell({ children, ...rest }: TableCellProps): ReactElement {
+export function TableCell({ children, ...rest }: TableCellProps): ReactElement {
   return <td {...rest}>{children}</td>;
 }
 
+/** @internal */
 TableCell.displayName = "TableCell";
 
 /**
@@ -224,7 +237,7 @@ TableCell.displayName = "TableCell";
  * </Table.ScrollArea>
  * ```
  */
-function TableScrollArea({
+export function TableScrollArea({
   children,
   style,
   ...rest
@@ -244,6 +257,7 @@ function TableScrollArea({
   );
 }
 
+/** @internal */
 TableScrollArea.displayName = "TableScrollArea";
 
 /**
@@ -279,7 +293,7 @@ TableScrollArea.displayName = "TableScrollArea";
  * </Table.Root>
  * ```
  */
-function TableCaption({
+export function TableCaption({
   children,
   captionSide = "bottom",
   ...rest
@@ -291,10 +305,15 @@ function TableCaption({
   );
 }
 
+/** @internal */
 TableCaption.displayName = "TableCaption";
 
-type TableCompound = typeof Table & {
-  Root: typeof Table;
+/**
+ * The shape of the exported `Table` value — callable as `Table.Root` and
+ * carrying every sub-component as a static property.
+ */
+export type TableCompound = typeof TableRoot & {
+  Root: typeof TableRoot;
   Head: typeof TableHead;
   Body: typeof TableBody;
   Footer: typeof TableFooter;
@@ -305,18 +324,6 @@ type TableCompound = typeof Table & {
   Caption: typeof TableCaption;
 };
 
-const TableCompound: TableCompound = Object.assign(Table, {
-  Root: Table,
-  Head: TableHead,
-  Body: TableBody,
-  Footer: TableFooter,
-  Row: TableRow,
-  Header: TableHeader,
-  Cell: TableCell,
-  ScrollArea: TableScrollArea,
-  Caption: TableCaption,
-});
-
 /**
  * Headless, accessible **Table** — a compound component wrapping standard
  * HTML table elements with zero styles.
@@ -381,6 +388,19 @@ const TableCompound: TableCompound = Object.assign(Table, {
  * @see {@link TableCaption} for caption placement and why it beats `aria-label`.
  * @see {@link TableScrollArea} for the horizontal-scroll style caveat.
  */
+const TableCompound: TableCompound = Object.assign(TableRoot, {
+  Root: TableRoot,
+  Head: TableHead,
+  Body: TableBody,
+  Footer: TableFooter,
+  Row: TableRow,
+  Header: TableHeader,
+  Cell: TableCell,
+  ScrollArea: TableScrollArea,
+  Caption: TableCaption,
+});
+
+/** @internal */
 TableCompound.displayName = "Table";
 
 export { TableCompound as Table };

package/src/Table/index.ts

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

package/src/Tabs/Tabs.tsx

@@ -102,7 +102,7 @@ import type {
  * <button onClick={() => ref.current?.setActiveTab("two")}>Go to two</button>
  * ```
  */
-const TabsRoot: ForwardRefExoticComponent<
+export const TabsRoot: ForwardRefExoticComponent<
   PropsWithoutRef<TabsRootProps> & RefAttributes<TabsImperativeApi>
 > = forwardRef<TabsImperativeApi, TabsRootProps>(function TabsRoot(
   {
@@ -196,6 +196,7 @@ export function TabsList({
   );
 }
 
+/** @internal */
 TabsList.displayName = "TabsList";
 
 /**
@@ -316,6 +317,7 @@ export function TabsTrigger<T extends HTMLElement = HTMLButtonElement>({
   );
 }
 
+/** @internal */
 TabsTrigger.displayName = "TabsTrigger";
 
 /**
@@ -381,9 +383,12 @@ export function TabsContent({
   );
 }
 
+/** @internal */
 TabsContent.displayName = "TabsContent";
 
-type TabsCompound = typeof TabsRoot & {
+/** Type of the {@link Tabs} compound: the callable `Tabs.Root` component
+ * augmented with its sub-components as static properties. */
+export type TabsCompound = typeof TabsRoot & {
   Root: typeof TabsRoot;
   List: typeof TabsList;
   Trigger: typeof TabsTrigger;

package/src/Tabs/TabsContext.ts

@@ -1,4 +1,4 @@
-import type { Context } from "react";
+import type { Context, Provider } from "react";
 import { createStrictContext } from "../utils/index.ts";
 
 import { TabsContextValue } from "./types";
@@ -8,9 +8,14 @@ const tabsContextPair = createStrictContext<TabsContextValue>(
   "TabsContext",
 );
 
+/** Strict React context carrying the {@link TabsContextValue} from `Tabs.Root`
+ * to its descendants. `null` when read outside a `Tabs.Root`. */
 export const TabsContext: Context<TabsContextValue | null> = tabsContextPair[0];
+/** Reads the {@link TabsContextValue}; throws when used outside a `Tabs.Root`. */
 export const useTabsContext: () => TabsContextValue = tabsContextPair[1];
 
-const TabsProvider = TabsContext.Provider;
+/** Provider component for {@link TabsContext}, used by `Tabs.Root` to supply the
+ * {@link TabsContextValue} to its descendants. */
+const TabsProvider: Provider<TabsContextValue | null> = TabsContext.Provider;
 
 export { TabsProvider };

package/src/Tabs/types.ts

@@ -1,9 +1,16 @@
 import { ComponentProps, Ref } from "react";
 
+/** Layout axis of the tab list. `"horizontal"` arranges triggers in a row and
+ * binds ArrowLeft/ArrowRight; `"vertical"` stacks them and binds
+ * ArrowUp/ArrowDown. */
 export type TabsOrientation = "horizontal" | "vertical";
 
+/** Reading direction of the tab list. In `"rtl"` the horizontal arrow keys are
+ * mirrored so navigation follows the visual order. */
 export type TabsReadingDirection = "ltr" | "rtl";
 
+/** When a focused trigger becomes active. `"automatic"` activates a tab as soon
+ * as it receives focus via the arrow keys; `"manual"` requires Enter/Space. */
 export type TabsActivationMode = "automatic" | "manual";
 
 /**
@@ -17,22 +24,34 @@ export type TabsActivationMode = "automatic" | "manual";
  */
 export type TabMetadata = { index: number; name: string };
 
+/** Props common to both controlled and uncontrolled `Tabs.Root` usage. */
 export type BaseTabsRootProps = {
+  /** Fired on every user-driven activation with the activated tab's metadata. */
   onChange?: ({ index, name }: TabMetadata) => void;
 };
 
+/** Uncontrolled `Tabs.Root` props: the component owns the active tab, seeded by
+ * an optional `defaultValue`. Mutually exclusive with the controlled props. */
 export type UncontrolledTabsRootProps = {
+  /** Value of the tab active on first render. */
   defaultValue?: string;
   value?: never;
   onValueChange?: never;
 };
 
-type ControlledTabsRootProps = {
+/** Controlled `Tabs.Root` props: the caller owns the active tab via `value` and
+ * is notified of activation requests through `onValueChange`. */
+export type ControlledTabsRootProps = {
+  /** Value of the currently active tab. */
   value: string;
+  /** Called with the requested value when the user activates a tab. */
   onValueChange: (value: string) => void;
   defaultValue?: never;
 };
 
+/** Props for `Tabs.Root` — the state owner and context provider. Extends the
+ * native `<div>` props (minus `onChange`) and resolves to either the
+ * controlled or uncontrolled prop shape. */
 export type TabsRootProps = Omit<ComponentProps<"div">, "onChange"> & {
   orientation?: TabsOrientation;
   dir?: TabsReadingDirection;
@@ -46,6 +65,9 @@ export type TabsRootProps = Omit<ComponentProps<"div">, "onChange"> & {
 } & BaseTabsRootProps &
   (UncontrolledTabsRootProps | ControlledTabsRootProps);
 
+/** The value shared by `Tabs.Root` with its descendants through context:
+ * resolved configuration, the active tab and its setter, and the registry of
+ * triggers used for roving focus and keyboard navigation. */
 export type TabsContextValue = {
   orientation: TabsOrientation;
   dir: TabsReadingDirection;
@@ -67,6 +89,9 @@ export type TabsContextValue = {
   focusTrigger: (value: string) => void;
 };
 
+/** Props for `Tabs.List` — the `role="tablist"` container. Requires exactly one
+ * accessible name source: either an inline `label` or an `ariaLabelledBy` id
+ * referencing existing label text. */
 export type TabsListProps = Omit<
   ComponentProps<"div">,
   "label" | "aria-labelledby"
@@ -75,6 +100,10 @@ export type TabsListProps = Omit<
     | { label: string; ariaLabelledBy?: never }
     | { label?: never; ariaLabelledBy: string }
   );
+/** Props for `Tabs.Trigger` — an individual `role="tab"` button. Identified by
+ * its required `value`, which links it to the `Tabs.Content` of the same value.
+ * The element type defaults to `HTMLButtonElement` and can be overridden via
+ * `asChild` and the `ref` type parameter. */
 export type TabsTriggerProps<T extends HTMLElement = HTMLButtonElement> = Omit<
   ComponentProps<"button">,
   "ref"
@@ -90,10 +119,15 @@ export type TabsTriggerProps<T extends HTMLElement = HTMLButtonElement> = Omit<
   ref?: Ref<T>;
 };
 
+/** Props for `Tabs.Content` — a `role="tabpanel"`. Its required `value` links
+ * it to the `Tabs.Trigger` of the same value. */
 export type TabsContentProps = ComponentProps<"div"> & {
+  /** Value of the trigger this panel belongs to. */
   value: string;
 };
 
+/** Imperative handle exposed on the `Tabs.Root` ref for programmatic control. */
 export type TabsImperativeApi = {
+  /** Activate the tab with the given value. */
   setActiveTab: (value: string) => void;
 };

package/src/Textarea/Textarea.tsx

@@ -92,4 +92,5 @@ export function Textarea({
   return <textarea {...rootProps} />;
 }
 
+/** @internal */
 Textarea.displayName = "Textarea";

package/src/Textarea/types.ts

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

package/src/Toggle/Toggle.tsx

@@ -82,6 +82,7 @@ function Toggle({
   );
 }
 
+/** @internal */
 Toggle.displayName = "Toggle";
 
 export { Toggle };

package/src/Toggle/types.ts

@@ -1,23 +1,27 @@
 import { ButtonHTMLAttributes, ReactNode, Ref } from "react";
 
-type UncontrolledToggleProps = {
+/** Uncontrolled `Toggle` props: seed with `defaultPressed`; `pressed`/`onPressedChange` are disallowed. */
+export type UncontrolledToggleProps = {
   defaultPressed?: boolean;
   pressed?: never;
   onPressedChange?: never;
 };
 
-type ControlledToggleProps = {
+/** Controlled `Toggle` props: drive with `pressed` and `onPressedChange`; `defaultPressed` is disallowed. */
+export type ControlledToggleProps = {
   pressed: boolean;
   onPressedChange: (pressed: boolean) => void;
   defaultPressed?: never;
 };
 
-type ToggleBaseProps = {
+/** Props common to both `Toggle` modes: `disabled`, `asChild`, `children`, `ref`, and the native `<button>` attributes (minus `type`). */
+export type ToggleBaseProps = {
   disabled?: boolean;
   asChild?: boolean;
   children?: ReactNode;
   ref?: Ref<HTMLButtonElement>;
 } & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type">;
 
+/** Props for the `Toggle` button — base props combined with the controlled/uncontrolled discriminated union. */
 export type ToggleProps = ToggleBaseProps &
   (UncontrolledToggleProps | ControlledToggleProps);

package/src/ToggleGroup/ToggleGroup.tsx

@@ -63,7 +63,7 @@ import { ToggleGroupItemProps, ToggleGroupRootProps } from "./types";
  * </ToggleGroup.Root>
  * ```
  */
-function ToggleGroupRoot({
+export function ToggleGroupRoot({
   type,
   defaultValue,
   value: controlledValue,
@@ -139,6 +139,7 @@ function ToggleGroupRoot({
   );
 }
 
+/** @internal */
 ToggleGroupRoot.displayName = "ToggleGroupRoot";
 
 /**
@@ -168,7 +169,7 @@ ToggleGroupRoot.displayName = "ToggleGroupRoot";
  *
  * @throws if rendered outside a `ToggleGroup.Root`.
  */
-function ToggleGroupItem({
+export function ToggleGroupItem({
   value,
   disabled,
   asChild = false,
@@ -251,9 +252,14 @@ function ToggleGroupItem({
   );
 }
 
+/** @internal */
 ToggleGroupItem.displayName = "ToggleGroupItem";
 
-type TToggleGroupCompound = typeof ToggleGroupRoot & {
+/**
+ * The shape of the exported `ToggleGroup` value — callable as
+ * `ToggleGroup.Root` and carrying `Root` and `Item` as static properties.
+ */
+export type TToggleGroupCompound = typeof ToggleGroupRoot & {
   Root: typeof ToggleGroupRoot;
   Item: typeof ToggleGroupItem;
 };

package/src/ToggleGroup/types.ts

@@ -1,6 +1,14 @@
 import { HTMLAttributes, ButtonHTMLAttributes, ReactNode, Ref } from "react";
 
-type ToggleGroupRootBaseProps = Omit<HTMLAttributes<HTMLDivElement>, "dir"> & {
+/**
+ * Mode-independent props shared by every `ToggleGroup.Root` variant —
+ * orientation, direction, `asChild`, children, and the ref. Combined with
+ * a mode-specific arm to form {@link ToggleGroupRootProps}.
+ */
+export type ToggleGroupRootBaseProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "dir"
+> & {
   orientation?: "horizontal" | "vertical";
   dir?: "ltr" | "rtl";
   asChild?: boolean;
@@ -8,34 +16,56 @@ type ToggleGroupRootBaseProps = Omit<HTMLAttributes<HTMLDivElement>, "dir"> & {
   ref?: Ref<HTMLDivElement>;
 };
 
-type SingleUncontrolledProps = {
+/**
+ * Single-selection mode, uncontrolled — at most one item pressed, with the
+ * initial value supplied via `defaultValue`.
+ */
+export type SingleUncontrolledProps = {
   type: "single";
   defaultValue?: string;
   value?: never;
   onValueChange?: never;
 };
 
-type SingleControlledProps = {
+/**
+ * Single-selection mode, controlled — the pressed value is owned by the
+ * caller via `value` / `onValueChange`.
+ */
+export type SingleControlledProps = {
   type: "single";
   value: string | undefined;
   onValueChange: (value: string | undefined) => void;
   defaultValue?: never;
 };
 
-type MultipleUncontrolledProps = {
+/**
+ * Multiple-selection mode, uncontrolled — items toggle independently, with
+ * the initial set supplied via `defaultValue`.
+ */
+export type MultipleUncontrolledProps = {
   type: "multiple";
   defaultValue?: string[];
   value?: never;
   onValueChange?: never;
 };
 
-type MultipleControlledProps = {
+/**
+ * Multiple-selection mode, controlled — the set of pressed values is owned
+ * by the caller via `value` / `onValueChange`.
+ */
+export type MultipleControlledProps = {
   type: "multiple";
   value: string[];
   onValueChange: (value: string[]) => void;
   defaultValue?: never;
 };
 
+/**
+ * Props for `ToggleGroup.Root`. Combines the shared
+ * {@link ToggleGroupRootBaseProps} with one mode-specific arm — single or
+ * multiple, controlled or uncontrolled — so the `value` / `defaultValue` /
+ * `onValueChange` shape is enforced per `type`.
+ */
 export type ToggleGroupRootProps = ToggleGroupRootBaseProps &
   (
     | SingleUncontrolledProps
@@ -44,6 +74,11 @@ export type ToggleGroupRootProps = ToggleGroupRootBaseProps &
     | MultipleControlledProps
   );
 
+/**
+ * Props for `ToggleGroup.Item` — a pressable toggle button. `value`
+ * identifies the item within the group; `asChild` merges the behaviour
+ * onto a custom child element.
+ */
 export type ToggleGroupItemProps = Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
   "type"
@@ -54,6 +89,11 @@ export type ToggleGroupItemProps = Omit<
   ref?: Ref<HTMLButtonElement>;
 };
 
+/**
+ * Context shared from `ToggleGroup.Root` to its items — the pressed
+ * values, the toggle action, item registration for roving tabindex, and
+ * the resolved orientation / direction.
+ */
 export type ToggleGroupContextValue = {
   value: string[];
   toggle: (itemValue: string) => void;

package/src/Tooltip/Tooltip.tsx

@@ -35,7 +35,7 @@ import type {
  * </Tooltip.Provider>
  * ```
  */
-function TooltipProviderComponent({
+export function TooltipProviderComponent({
   children,
   delayDuration = 700,
   skipDelayDuration = 300,
@@ -51,6 +51,7 @@ function TooltipProviderComponent({
   );
 }
 
+/** @internal */
 TooltipProviderComponent.displayName = "TooltipProvider";
 
 /**
@@ -70,7 +71,7 @@ TooltipProviderComponent.displayName = "TooltipProvider";
  * </Tooltip.Root>
  * ```
  */
-function TooltipRoot({
+export function TooltipRoot({
   children,
   defaultOpen,
   open,
@@ -89,6 +90,7 @@ function TooltipRoot({
   return <TooltipProvider value={contextValue}>{children}</TooltipProvider>;
 }
 
+/** @internal */
 TooltipRoot.displayName = "TooltipRoot";
 
 /**
@@ -109,7 +111,7 @@ TooltipRoot.displayName = "TooltipRoot";
  * </Tooltip.Trigger>
  * ```
  */
-function TooltipTrigger({
+export function TooltipTrigger({
   ref,
   asChild = false,
   onPointerEnter,
@@ -136,6 +138,7 @@ function TooltipTrigger({
   return <button ref={ref} type={type ?? "button"} {...getTriggerProps()} />;
 }
 
+/** @internal */
 TooltipTrigger.displayName = "TooltipTrigger";
 
 /**
@@ -154,7 +157,7 @@ TooltipTrigger.displayName = "TooltipTrigger";
  * </Tooltip.Portal>
  * ```
  */
-function TooltipPortal({
+export function TooltipPortal({
   children,
   container,
   forceMount,
@@ -166,6 +169,7 @@ function TooltipPortal({
   return <Portal container={container}>{children}</Portal>;
 }
 
+/** @internal */
 TooltipPortal.displayName = "TooltipPortal";
 
 /**
@@ -196,7 +200,7 @@ TooltipPortal.displayName = "TooltipPortal";
  * </Tooltip.Content>
  * ```
  */
-function TooltipContent({
+export function TooltipContent({
   ref,
   forceMount,
   onEscapeKeyDown,
@@ -219,6 +223,7 @@ function TooltipContent({
   return <div ref={composeRefs(internalRef, ref)} {...getContentProps()} />;
 }
 
+/** @internal */
 TooltipContent.displayName = "TooltipContent";
 
 /**
@@ -236,7 +241,7 @@ TooltipContent.displayName = "TooltipContent";
  * </Tooltip.Content>
  * ```
  */
-function TooltipArrow({
+export function TooltipArrow({
   ref,
   asChild = false,
   ...rest
@@ -248,9 +253,11 @@ function TooltipArrow({
   return <span ref={ref} {...rest} />;
 }
 
+/** @internal */
 TooltipArrow.displayName = "TooltipArrow";
 
-type TooltipCompound = typeof TooltipRoot & {
+/** Type of the {@link Tooltip} compound: the root callable plus its attached sub-components. */
+export type TooltipCompound = typeof TooltipRoot & {
   Provider: typeof TooltipProviderComponent;
   Root: typeof TooltipRoot;
   Trigger: typeof TooltipTrigger;
@@ -259,6 +266,16 @@ type TooltipCompound = typeof TooltipRoot & {
   Arrow: typeof TooltipArrow;
 };
 
+/**
+ * Headless, accessible **Tooltip** — a compound component implementing the
+ * [WAI-ARIA tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/):
+ * a deferred, hoverable label anchored to a trigger, with a shared
+ * {@link Tooltip.Provider} governing open / skip delays across a group. Zero
+ * styles ship.
+ *
+ * The default export is the `Root`; sub-components are attached as static
+ * properties (`Tooltip.Provider`, `Tooltip.Trigger`, `Tooltip.Content`, …).
+ */
 const TooltipCompound: TooltipCompound = Object.assign(TooltipRoot, {
   Provider: TooltipProviderComponent,
   Root: TooltipRoot,
@@ -268,6 +285,7 @@ const TooltipCompound: TooltipCompound = Object.assign(TooltipRoot, {
   Arrow: TooltipArrow,
 });
 
+/** @internal */
 TooltipCompound.displayName = "Tooltip";
 
 export { TooltipCompound as Tooltip };

package/src/Tooltip/index.ts

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