@primitiv-ui/react 0.1.0 → 0.1.2

package/src/Switch/types.ts

@@ -1,25 +1,43 @@
 import { ButtonHTMLAttributes, ComponentProps, ReactNode, Ref } from "react";
 
-type SwitchRootBaseProps = Omit<
+/** Props common to both controlled and uncontrolled `Switch.Root` modes. */
+export type SwitchRootBaseProps = Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
   "type" | "role" | "aria-checked"
 > & {
+  /** Render the child element instead of the default `<button>`. */
   asChild?: boolean;
+  /** Ref to the rendered `<button>` element. */
   ref?: Ref<HTMLButtonElement>;
 };
 
-type SwitchRootUncontrolledProps = SwitchRootBaseProps & {
+/**
+ * Props for `Switch.Root` in uncontrolled mode — the component owns the checked
+ * state. Pass `defaultChecked` to set the initial value; `checked` is forbidden.
+ */
+export type SwitchRootUncontrolledProps = SwitchRootBaseProps & {
+  /** Initial checked state when uncontrolled. */
   defaultChecked?: boolean;
+  /** Forbidden in uncontrolled mode. */
   checked?: never;
+  /** Called whenever the checked state changes. */
   onCheckedChange?: (checked: boolean) => void;
 };
 
-type SwitchRootControlledProps = SwitchRootBaseProps & {
+/**
+ * Props for `Switch.Root` in controlled mode — the parent owns the checked
+ * value. Pass `checked` and `onCheckedChange` together.
+ */
+export type SwitchRootControlledProps = SwitchRootBaseProps & {
+  /** Forbidden in controlled mode. */
   defaultChecked?: never;
+  /** The controlled checked state. */
   checked: boolean;
+  /** Called whenever the component requests a checked-state change. */
   onCheckedChange: (checked: boolean) => void;
 };
 
+/** Props for `Switch.Root` — discriminated controlled/uncontrolled union. */
 export type SwitchRootProps =
   | SwitchRootUncontrolledProps
   | SwitchRootControlledProps;
@@ -31,7 +49,10 @@ export type SwitchRootProps =
  */
 export type SwitchProps = SwitchRootProps;
 
+/** Props for `Switch.Thumb`, the sliding indicator inside the track. */
 export type SwitchThumbProps = ComponentProps<"span"> & {
+  /** Optional thumb content. */
   children?: ReactNode;
+  /** Render the child element instead of the default `<span>`. */
   asChild?: boolean;
 };

package/src/Table/Table.tsx

@@ -1,3 +1,5 @@
+import type { ReactElement } from "react";
+
 import {
   TableBodyProps,
   TableCaptionProps,
@@ -40,11 +42,12 @@ import {
  * </Table.Root>
  * ```
  */
-function Table({ children, ...rest }: TableRootProps) {
+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.
@@ -63,10 +66,11 @@ Table.displayName = "Table";
  * </Table.Head>
  * ```
  */
-function TableHead({ children, ...rest }: TableHeadProps) {
+export function TableHead({ children, ...rest }: TableHeadProps): ReactElement {
   return <thead {...rest}>{children}</thead>;
 }
 
+/** @internal */
 TableHead.displayName = "TableHead";
 
 /**
@@ -87,10 +91,11 @@ TableHead.displayName = "TableHead";
  * </Table.Body>
  * ```
  */
-function TableBody({ children, ...rest }: TableBodyProps) {
+export function TableBody({ children, ...rest }: TableBodyProps): ReactElement {
   return <tbody {...rest}>{children}</tbody>;
 }
 
+/** @internal */
 TableBody.displayName = "TableBody";
 
 /**
@@ -110,10 +115,14 @@ TableBody.displayName = "TableBody";
  * </Table.Footer>
  * ```
  */
-function TableFooter({ children, ...rest }: TableFooterProps) {
+export function TableFooter({
+  children,
+  ...rest
+}: TableFooterProps): ReactElement {
   return <tfoot {...rest}>{children}</tfoot>;
 }
 
+/** @internal */
 TableFooter.displayName = "TableFooter";
 
 /**
@@ -132,10 +141,11 @@ TableFooter.displayName = "TableFooter";
  * </Table.Row>
  * ```
  */
-function TableRow({ children, ...rest }: TableRowProps) {
+export function TableRow({ children, ...rest }: TableRowProps): ReactElement {
   return <tr {...rest}>{children}</tr>;
 }
 
+/** @internal */
 TableRow.displayName = "TableRow";
 
 /**
@@ -166,10 +176,14 @@ TableRow.displayName = "TableRow";
  * <Table.Header scope="row">Alice</Table.Header>
  * ```
  */
-function TableHeader({ children, ...rest }: TableHeaderProps) {
+export function TableHeader({
+  children,
+  ...rest
+}: TableHeaderProps): ReactElement {
   return <th {...rest}>{children}</th>;
 }
 
+/** @internal */
 TableHeader.displayName = "TableHeader";
 
 /**
@@ -188,10 +202,11 @@ TableHeader.displayName = "TableHeader";
  * <Table.Cell colSpan={2}>Full-width note</Table.Cell>
  * ```
  */
-function TableCell({ children, ...rest }: TableCellProps) {
+export function TableCell({ children, ...rest }: TableCellProps): ReactElement {
   return <td {...rest}>{children}</td>;
 }
 
+/** @internal */
 TableCell.displayName = "TableCell";
 
 /**
@@ -222,7 +237,11 @@ TableCell.displayName = "TableCell";
  * </Table.ScrollArea>
  * ```
  */
-function TableScrollArea({ children, style, ...rest }: TableScrollAreaProps) {
+export function TableScrollArea({
+  children,
+  style,
+  ...rest
+}: TableScrollAreaProps): ReactElement {
   return (
     <div
       style={{
@@ -238,6 +257,7 @@ function TableScrollArea({ children, style, ...rest }: TableScrollAreaProps) {
   );
 }
 
+/** @internal */
 TableScrollArea.displayName = "TableScrollArea";
 
 /**
@@ -273,11 +293,11 @@ TableScrollArea.displayName = "TableScrollArea";
  * </Table.Root>
  * ```
  */
-function TableCaption({
+export function TableCaption({
   children,
   captionSide = "bottom",
   ...rest
-}: TableCaptionProps) {
+}: TableCaptionProps): ReactElement {
   return (
     <caption style={{ captionSide }} {...rest}>
       {children}
@@ -285,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;
@@ -299,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.
@@ -375,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/__tests__/Table.Body.test.tsx

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

package/src/Table/__tests__/Table.Caption.test.tsx

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

package/src/Table/__tests__/Table.Cell.test.tsx

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

package/src/Table/__tests__/Table.Footer.test.tsx

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

package/src/Table/__tests__/Table.Head.test.tsx

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

package/src/Table/__tests__/Table.Header.test.tsx

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

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

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

package/src/Table/__tests__/Table.Row.test.tsx

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

package/src/Table/__tests__/Table.ScrollArea.test.tsx

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

package/src/Table/index.ts

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

package/src/Tabs/Tabs.tsx

@@ -1,14 +1,20 @@
 import { forwardRef, Ref } from "react";
+import type {
+  ForwardRefExoticComponent,
+  PropsWithoutRef,
+  ReactElement,
+  RefAttributes,
+} from "react";
 
-import { useDirection } from "../DirectionProvider";
-import { Slot, composeRefs } from "../Slot";
+import { useDirection } from "../DirectionProvider/index.ts";
+import { Slot, composeRefs } from "../Slot/index.ts";
 
 import {
   useTabsRoot,
   useTabsContext,
   useTabsTrigger,
   useTabsContent,
-} from "./hooks";
+} from "./hooks/index.ts";
 import { TabsProvider } from "./TabsContext";
 import type {
   TabsRootProps,
@@ -96,7 +102,9 @@ import type {
  * <button onClick={() => ref.current?.setActiveTab("two")}>Go to two</button>
  * ```
  */
-const TabsRoot = forwardRef<TabsImperativeApi, TabsRootProps>(function TabsRoot(
+export const TabsRoot: ForwardRefExoticComponent<
+  PropsWithoutRef<TabsRootProps> & RefAttributes<TabsImperativeApi>
+> = forwardRef<TabsImperativeApi, TabsRootProps>(function TabsRoot(
   {
     className = "",
     orientation = "horizontal",
@@ -166,7 +174,7 @@ export function TabsList({
   label,
   ariaLabelledBy,
   ...rest
-}: TabsListProps) {
+}: TabsListProps): ReactElement {
   const { orientation } = useTabsContext();
 
   return (
@@ -188,6 +196,7 @@ export function TabsList({
   );
 }
 
+/** @internal */
 TabsList.displayName = "TabsList";
 
 /**
@@ -259,7 +268,7 @@ export function TabsTrigger<T extends HTMLElement = HTMLButtonElement>({
   disabled = false,
   asChild = false,
   ...rest
-}: TabsTriggerProps<T>) {
+}: TabsTriggerProps<T>): ReactElement {
   const {
     buttonRef,
     triggerId,
@@ -308,6 +317,7 @@ export function TabsTrigger<T extends HTMLElement = HTMLButtonElement>({
   );
 }
 
+/** @internal */
 TabsTrigger.displayName = "TabsTrigger";
 
 /**
@@ -345,9 +355,16 @@ export function TabsContent({
   className = "",
   value,
   ...rest
-}: TabsContentProps) {
-  const { panelId, triggerId, orientation, isActive, state, tabIndex, shouldRender } =
-    useTabsContent({ value });
+}: TabsContentProps): ReactElement {
+  const {
+    panelId,
+    triggerId,
+    orientation,
+    isActive,
+    state,
+    tabIndex,
+    shouldRender,
+  } = useTabsContent({ value });
 
   return (
     <div
@@ -366,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,13 +1,21 @@
-import { createStrictContext } from "../utils";
+import type { Context, Provider } from "react";
+import { createStrictContext } from "../utils/index.ts";
 
 import { TabsContextValue } from "./types";
 
-export const [TabsContext, useTabsContext] =
-  createStrictContext<TabsContextValue>(
-    "Component must be rendered as a child of Tabs.Root",
-    "TabsContext",
-  );
+const tabsContextPair = createStrictContext<TabsContextValue>(
+  "Component must be rendered as a child of Tabs.Root",
+  "TabsContext",
+);
 
-const TabsProvider = TabsContext.Provider;
+/** 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];
+
+/** 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/__tests__/Tabs.asChild.test.tsx

@@ -2,7 +2,7 @@ import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { createRef } from "react";
 
-import { Tabs } from "..";
+import { Tabs } from "../index.ts";
 
 describe("Tabs.Trigger asChild", () => {
   it("renders the child element instead of a <button> when asChild is true", () => {

package/src/Tabs/__tests__/Tabs.basic-rendering.test.tsx

@@ -1,6 +1,6 @@
 import { render, screen } from "@testing-library/react";
 
-import { Tabs, TabsOrientation } from "..";
+import { Tabs, TabsOrientation } from "../index.ts";
 
 describe("Tabs basic rendering tests", () => {
   describe("Tabs.Root", () => {

package/src/Tabs/__tests__/Tabs.change-event-callbacks.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
-import { Tabs } from '..';
+import { Tabs } from '../index.ts';
 
 import { mouseChangeEventCases, keyboardChangeEventCases } from './Tabs.fixtures';
 

package/src/Tabs/__tests__/Tabs.controlled-state.test.tsx

@@ -2,7 +2,7 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { useState } from 'react';
 
-import { Tabs } from '..';
+import { Tabs } from '../index.ts';
 
 describe('Tabs controlled state tests', () => {
   it('should respect the value prop for active tab', () => {

package/src/Tabs/__tests__/Tabs.error-handling.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from '@testing-library/react';
 import { act, useState } from 'react';
 
-import { Tabs } from '..';
+import { Tabs } from '../index.ts';
 
 import { errorCases } from './Tabs.fixtures';
 

package/src/Tabs/__tests__/Tabs.imperative-api.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen, waitFor } from "@testing-library/react";
 import { createRef } from "react";
 
-import { Tabs, TabsImperativeApi } from "..";
+import { Tabs, TabsImperativeApi } from "../index.ts";
 
 describe("Tabs Imperative API", () => {
   it("should expose setActiveTab method via ref", () => {

package/src/Tabs/__tests__/Tabs.keyboard-interaction.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
-import { Tabs } from '..';
+import { Tabs } from '../index.ts';
 
 import { arrowKeyCases } from './Tabs.fixtures';
 

package/src/Tabs/__tests__/Tabs.lazy-mount.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Tabs } from "..";
+import { Tabs } from "../index.ts";
 
 function renderTabs(lazyMount: boolean) {
   return render(

package/src/Tabs/__tests__/Tabs.mouse-interaction.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
-import { Tabs } from '..';
+import { Tabs } from '../index.ts';
 
 describe('Tabs mouse interaction tests', () => {
   describe('tab and panel activation', () => {

package/src/Tabs/__tests__/Tabs.reading-direction.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { DirectionProvider } from "../../DirectionProvider";
+import { DirectionProvider } from "../../DirectionProvider/index.ts";
 import { Tabs } from "../Tabs";
 import { TabsReadingDirection } from "../types";
 

package/src/Tabs/__tests__/Tabs.uncontrolled-state.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
-import { Tabs } from '..';
+import { Tabs } from '../index.ts';
 
 describe('Tabs state tests', () => {
   describe('no defaultValue provided', () => {

package/src/Tabs/hooks/useTabsContent.ts

@@ -3,7 +3,7 @@ import { useEffect, useState } from "react";
 import { TabsContentProps } from "../types";
 import { getTriggerAndPanelIds } from "../utils";
 
-import { useTabsContext } from ".";
+import { useTabsContext } from "./index.ts";
 
 export function useTabsContent({ value }: Pick<TabsContentProps, "value">) {
   const { orientation, activeValue, tabsId, lazyMount } = useTabsContext();

package/src/Tabs/hooks/useTabsRoot.ts

@@ -7,7 +7,7 @@ import {
   Ref,
 } from "react";
 
-import { useCollection, useControllableState } from "../../hooks";
+import { useCollection, useControllableState } from "../../hooks/index.ts";
 
 import type { TabsRootProps, TabsImperativeApi } from "../types";
 

package/src/Tabs/hooks/useTabsTrigger.ts

@@ -5,7 +5,7 @@ import {
   MouseEvent,
 } from "react";
 
-import { useRovingTabindex } from "../../hooks";
+import { useRovingTabindex } from "../../hooks/index.ts";
 
 import { TabsTriggerProps } from "../types";
 import { getTriggerAndPanelIds } from "../utils";