@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/Table/types.d.ts

@@ -0,0 +1,214 @@
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode, TableHTMLAttributes, ThHTMLAttributes, TdHTMLAttributes } from "react";
+/**
+ * Props for {@link TableRoot | `Table.Root`} — all `TableHTMLAttributes` on
+ * the native `<table>`. No custom props are added.
+ *
+ * @extends HTMLTableElement
+ */
+export type TableRootProps = TableHTMLAttributes<HTMLTableElement>;
+/**
+ * Props for {@link TableHead | `Table.Head`} — all `HTMLAttributes` on the
+ * native `<thead>`. No custom props are added.
+ *
+ * @extends HTMLTableSectionElement
+ */
+export type TableHeadProps = HTMLAttributes<HTMLTableSectionElement>;
+/**
+ * Props for {@link TableBody | `Table.Body`} — all `HTMLAttributes` on the
+ * native `<tbody>`. No custom props are added.
+ *
+ * @extends HTMLTableSectionElement
+ */
+export type TableBodyProps = HTMLAttributes<HTMLTableSectionElement>;
+/**
+ * Props for {@link TableFooter | `Table.Footer`} — all `HTMLAttributes` on
+ * the native `<tfoot>`. No custom props are added.
+ *
+ * @extends HTMLTableSectionElement
+ */
+export type TableFooterProps = HTMLAttributes<HTMLTableSectionElement>;
+/**
+ * Props for {@link TableRow | `Table.Row`} — all `HTMLAttributes` on the
+ * native `<tr>`. No custom props are added.
+ *
+ * @extends HTMLTableRowElement
+ */
+export type TableRowProps = HTMLAttributes<HTMLTableRowElement>;
+/**
+ * Props for {@link TableHeader | `Table.Header`} — all `ThHTMLAttributes` on
+ * the native `<th>`, including `colSpan`, `rowSpan`, and `abbr`.
+ *
+ * The most important prop for accessibility is `scope`: set it to `"col"` for
+ * column headers and `"row"` for row headers so assistive technology can
+ * associate data cells with the correct header. See the scope table on
+ * {@link TableHeader}.
+ *
+ * @extends HTMLTableCellElement
+ */
+export type TableHeaderProps = ThHTMLAttributes<HTMLTableCellElement>;
+/**
+ * Props for {@link TableCell | `Table.Cell`} — all `TdHTMLAttributes` on the
+ * native `<td>`.
+ *
+ * Includes `colSpan` and `rowSpan` for spanning multiple columns or rows.
+ *
+ * @extends HTMLTableCellElement
+ */
+export type TableCellProps = TdHTMLAttributes<HTMLTableCellElement>;
+/**
+ * Props for {@link TableScrollArea | `Table.ScrollArea`} — a required
+ * `children` plus all `HTMLAttributes` on the wrapping `<div>`.
+ *
+ * @extends HTMLDivElement
+ */
+export type TableScrollAreaProps = {
+    /** The table (typically a single {@link TableRoot | `Table.Root`}) to
+     * wrap in the horizontally-scrolling container. */
+    children: ReactNode;
+    /**
+     * Merged with (and taking priority over) the base scroll styles
+     * (`display: block`, `overflow-x: auto`, `max-width: 100%`), so
+     * additional styles can be layered on without repeating the scroll
+     * declarations. See {@link TableScrollArea}'s custom-styles example.
+     */
+    style?: HTMLAttributes<HTMLDivElement>["style"];
+} & Omit<HTMLAttributes<HTMLDivElement>, "style">;
+/**
+ * The value shared by {@link TableExpandable | `Table.Expandable`} with its
+ * {@link TableExpandTrigger | `Table.ExpandTrigger`} and
+ * {@link TableDetailRow | `Table.DetailRow`} children.
+ *
+ * @internal
+ */
+export type TableExpandableContextValue = {
+    /** Whether the detail row is currently revealed. */
+    expanded: boolean;
+    /** The id wired to the detail row's `<tr>` and the trigger's `aria-controls`. */
+    detailId: string;
+    /** Flips `expanded` and notifies `onExpandedChange`. */
+    toggle: () => void;
+};
+/**
+ * Props for {@link TableExpandable | `Table.Expandable`} — the pairing
+ * provider for one expandable row and its detail row.
+ */
+export type TableExpandableProps = {
+    /** The parent {@link TableRow | `Table.Row`} and its
+     * {@link TableDetailRow | `Table.DetailRow`}, as siblings. */
+    children: ReactNode;
+    /**
+     * Whether the detail row is revealed. Pass this (with
+     * `onExpandedChange`) to drive expansion from outside — which is what an
+     * external table engine such as TanStack Table does.
+     */
+    expanded?: boolean;
+    /**
+     * Initial expanded state when running uncontrolled. Ignored when
+     * `expanded` is supplied.
+     * @default false
+     */
+    defaultExpanded?: boolean;
+    /** Called with the next expanded state whenever the trigger is activated. */
+    onExpandedChange?: (expanded: boolean) => void;
+};
+/**
+ * Props for {@link TableExpandTrigger | `Table.ExpandTrigger`} — all
+ * `ButtonHTMLAttributes` on the native `<button>`.
+ *
+ * `aria-expanded`, `aria-controls` and `type` are owned by the component and
+ * therefore `Omit`-ted: they are derived from the surrounding
+ * {@link TableExpandable | `Table.Expandable`} and must not be overridden, or
+ * the relationship the pair exists to express would break.
+ *
+ * @extends HTMLButtonElement
+ */
+export type TableExpandTriggerProps = {
+    /**
+     * Render a consumer-supplied control instead of the native `<button>`, with
+     * this part's `aria-expanded`, `aria-controls`, `data-state` and click
+     * handling merged onto it via the {@link Slot} pattern.
+     *
+     * This is how a styled layer composes a real Button rather than re-creating
+     * one: the registry `data-table` renders a ghost Button through it, matching
+     * the Figma set, whose Expand Trigger is an Icon Button instance rather than a
+     * drawn glyph. The child must be a single element that accepts a `ref`, and it
+     * should be a `<button>` — the wiring assumes a control.
+     * @default false
+     */
+    asChild?: boolean;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-expanded" | "aria-controls" | "type">;
+/**
+ * Props for {@link TableDetailRow | `Table.DetailRow`} — a required `colSpan`
+ * plus all `HTMLAttributes` on the native `<tr>`.
+ *
+ * `id` is component-owned (it is the target of the trigger's `aria-controls`)
+ * and so is `Omit`-ted.
+ *
+ * @extends HTMLTableRowElement
+ */
+export type TableDetailRowProps = {
+    /** The detail panel's content. */
+    children?: ReactNode;
+    /**
+     * How many columns the panel spans — **every** column the table renders,
+     * control columns included.
+     *
+     * Deliberately a required prop rather than a value counted from context:
+     * counting would mean the table registering its own columns, and an
+     * external table engine already knows the number (TanStack Table:
+     * `table.getVisibleLeafColumns().length`).
+     */
+    colSpan: number;
+    /**
+     * How many leading columns to leave empty before the panel starts — the
+     * control columns (select, expand) a row renders in front of its data.
+     *
+     * The panel then spans the columns that remain, so `colSpan` keeps its
+     * meaning: the table's full column count, gutter included.
+     *
+     * This is how a panel aligns with the first **data** column instead of the
+     * table's edge (a panel starting under the checkbox reads as a new section of
+     * the table rather than an opened row). Alignment by empty cell rather than by
+     * a CSS indent is deliberate: the browser's own table layout resolves the
+     * width, so it stays exact across every size, density and control-column set
+     * with nothing measured and no arithmetic to drift.
+     * @default 0
+     */
+    gutter?: number;
+    /**
+     * Keep the row mounted while collapsed so a CSS transition can run.
+     *
+     * Off by default, and that default matters more here than it does on a
+     * `<div>`-based disclosure: a mounted row is still a **row**, so assistive
+     * technology counts it, and a table of 24 rows with 24 force-mounted
+     * detail rows announces 48. Opt in only when you are animating, and note
+     * that the collapsed row remains in the accessibility tree while you do.
+     * @default false
+     */
+    forceMount?: boolean;
+    /** Passed through to the `<td>` that spans the row, for styling the cell
+     * itself rather than the row. */
+    cellProps?: TdHTMLAttributes<HTMLTableCellElement>;
+} & Omit<HTMLAttributes<HTMLTableRowElement>, "id" | "children">;
+/**
+ * Props for {@link TableCaption | `Table.Caption`} — a required `children`,
+ * an optional `captionSide`, plus all `HTMLAttributes` on the native
+ * `<caption>`.
+ *
+ * @extends HTMLTableCaptionElement
+ */
+export type TableCaptionProps = {
+    /** The visible, accessible label for the table. Preferred over
+     * `aria-label`/`aria-labelledby` on the table itself — the browser
+     * programmatically associates a `<caption>` with its `<table>`. */
+    children: ReactNode;
+    /**
+     * Controls the CSS `caption-side` property, positioning the caption
+     * above or below the table. See {@link TableCaption}'s placement
+     * examples.
+     * - `"bottom"` — caption appears below the table.
+     * - `"top"` — caption appears above the table.
+     * @default "bottom"
+     */
+    captionSide?: "bottom" | "top";
+} & HTMLAttributes<HTMLTableCaptionElement>;

package/dist/Table/types.js

@@ -0,0 +1 @@
+export {};

package/dist/Tabs/Tabs.d.ts

@@ -0,0 +1,270 @@
+import type { ForwardRefExoticComponent, PropsWithoutRef, ReactElement, RefAttributes } from "react";
+import type { TabsRootProps, TabsListProps, TabsTriggerProps, TabsContentProps, TabsImperativeApi } from "./types.js";
+/**
+ * The root of a Tabs widget — owns the active value, provides context to
+ * descendants, and renders a single container `<div>`.
+ *
+ * Supports two state modes, statically discriminated at the type level so
+ * only one of the two shapes is accepted by TypeScript:
+ *
+ * - **Uncontrolled** — pass {@link TabsRootProps.defaultValue | `defaultValue`}
+ *   (or omit it and let the first click seed the state). The component
+ *   owns and updates the active value internally.
+ * - **Controlled** — pass {@link TabsRootProps.value | `value`} *and*
+ *   {@link TabsRootProps.onValueChange | `onValueChange`} together. The
+ *   parent owns the active value; the component defers every state change
+ *   back through the callback.
+ *
+ * An additional {@link TabsRootProps.onChange | `onChange({ index, name })`}
+ * callback fires on every user-driven activation (click or keyboard)
+ * independent of the control mode. Use it for analytics or side-effects
+ * that shouldn't re-enter the state update path.
+ *
+ * An imperative handle is exposed via `ref`, exposing
+ * {@link TabsImperativeApi.setActiveTab | `setActiveTab(value)`} for
+ * programmatic activation (e.g. restoring a remembered tab on mount, or
+ * reacting to a deep-linked hash):
+ *
+ * ```tsx
+ * const tabsRef = useRef<TabsImperativeApi>(null);
+ * tabsRef.current?.setActiveTab("settings");
+ * ```
+ *
+ * **Runtime validation.** If `value`/`defaultValue` doesn't match any
+ * registered `Tabs.Trigger`, a descriptive error is thrown during render
+ * and typos surface early in development.
+ *
+ * **Styling hooks.** `data-orientation="horizontal" | "vertical"` is set
+ * on the rendered container.
+ *
+ * **Reading direction.** `dir` (`"ltr"` / `"rtl"`) sets the arrow-key
+ * direction and the container's `dir` attribute. When omitted, it is
+ * inherited from the nearest {@link DirectionProvider}, falling back to
+ * `"ltr"` when there is no provider.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Tabs.Root defaultValue="overview">
+ *   <Tabs.List label="Account sections">
+ *     <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
+ *     <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+ *   </Tabs.List>
+ *   <Tabs.Content value="overview">Dashboard...</Tabs.Content>
+ *   <Tabs.Content value="settings">Preferences...</Tabs.Content>
+ * </Tabs.Root>
+ * ```
+ *
+ * @example Controlled with an analytics hook
+ * ```tsx
+ * const [tab, setTab] = useState("overview");
+ *
+ * <Tabs.Root
+ *   value={tab}
+ *   onValueChange={setTab}
+ *   onChange={({ name, index }) => track("tab_view", { name, index })}
+ * >
+ *   ...
+ * </Tabs.Root>
+ * ```
+ *
+ * @example Vertical orientation + imperative API
+ * ```tsx
+ * const ref = useRef<TabsImperativeApi>(null);
+ *
+ * <Tabs.Root ref={ref} orientation="vertical" defaultValue="one">
+ *   ...
+ * </Tabs.Root>
+ *
+ * <button onClick={() => ref.current?.setActiveTab("two")}>Go to two</button>
+ * ```
+ */
+export declare const TabsRoot: ForwardRefExoticComponent<PropsWithoutRef<TabsRootProps> & RefAttributes<TabsImperativeApi>>;
+/**
+ * The tablist — an accessible container for `Tabs.Trigger` elements.
+ *
+ * Renders a `<div role="tablist">` with `aria-orientation` inherited from
+ * the nearest {@link TabsRoot | `Tabs.Root`}. The
+ * {@link TabsListProps.label | `label`} prop is **required** and becomes
+ * the `aria-label` announced to assistive technology when the tablist
+ * receives focus — pick a short, human-readable description of the set of
+ * tabs (e.g. `"Account sections"`, not `"Tabs"`).
+ *
+ * **Styling hooks.** `data-orientation="horizontal" | "vertical"`.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Tabs.List label="Document sections">
+ *   <Tabs.Trigger value="title">Title</Tabs.Trigger>
+ *   <Tabs.Trigger value="body">Body</Tabs.Trigger>
+ * </Tabs.List>
+ * ```
+ */
+export declare function TabsList({ children, className, label, ariaLabelledBy, ...rest }: TabsListProps): ReactElement;
+export declare namespace TabsList {
+    var displayName: string;
+}
+/**
+ * An individual tab button. Renders `<button role="tab">` with full ARIA
+ * linkage, roving tabindex, and keyboard navigation handled automatically.
+ *
+ * **Value linkage.** Each trigger is identified by a unique
+ * {@link TabsTriggerProps.value | `value`} string; the matching
+ * `Tabs.Content` must share the same value. The IDs used for
+ * `aria-controls` and `aria-labelledby` are derived from the root's
+ * `useId()` plus the trigger's `value`, so they're stable and unique even
+ * when multiple `Tabs` instances coexist on a page.
+ *
+ * **Keyboard support** (WAI-ARIA Tabs pattern):
+ *
+ * | Key                          | Behaviour                                          |
+ * | ---------------------------- | -------------------------------------------------- |
+ * | `ArrowRight` / `ArrowLeft`   | Move between triggers (horizontal)                 |
+ * | `ArrowDown`  / `ArrowUp`     | Move between triggers (vertical)                   |
+ * | `Home` / `End`               | Jump to first / last trigger                       |
+ * | `Enter` / `Space`            | Activate focused trigger (manual mode only)        |
+ *
+ * Movement **wraps** at the ends. In **automatic** activation mode (the default),
+ * focus movement immediately activates the panel. In **manual** mode, arrow keys
+ * move focus without switching the panel — `Enter` or `Space` confirms the
+ * selection. Use manual mode for panels that are expensive to render.
+ *
+ * **`asChild` prop.** Pass `asChild` to render an arbitrary child element
+ * instead of the default `<button>`. All tab ARIA attributes, event handlers,
+ * and the roving `tabIndex` are merged onto the child element following the
+ * Composition pattern:
+ * - Event handlers compose — the child's handler runs first, then the trigger's.
+ * - `style` is shallow-merged (child wins on collisions).
+ * - `className` strings are concatenated.
+ * - Refs from both sides are composed via `composeRefs`.
+ *
+ * The child **must** be a single React element that accepts a `ref`.
+ *
+ * **Styling hooks.**
+ * - `data-state="active" | "inactive"` on the rendered element.
+ * - `data-orientation="horizontal" | "vertical"`.
+ * - `data-disabled=""` when disabled (omitted otherwise), so CSS can target
+ *   `[data-disabled]` without the `:disabled` pseudo-class.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Tabs.Trigger value="account">Account</Tabs.Trigger>
+ * ```
+ *
+ * @example Icon + label
+ * ```tsx
+ * <Tabs.Trigger value="billing">
+ *   <CreditCardIcon aria-hidden />
+ *   <span>Billing</span>
+ * </Tabs.Trigger>
+ * ```
+ *
+ * @example asChild — render a router link with tab semantics
+ * ```tsx
+ * <Tabs.Trigger asChild value="settings">
+ *   <Link to="/settings">Settings</Link>
+ * </Tabs.Trigger>
+ * ```
+ */
+export declare function TabsTrigger<T extends HTMLElement = HTMLButtonElement>({ ref: externalRef, children, className, value, onClick, disabled, asChild, ...rest }: TabsTriggerProps<T>): ReactElement;
+export declare namespace TabsTrigger {
+    var displayName: string;
+}
+/**
+ * A panel associated with a `Tabs.Trigger` of the same
+ * {@link TabsContentProps.value | `value`}.
+ *
+ * Renders `<div role="tabpanel">` with `aria-labelledby` pointing at the
+ * matching trigger, and uses the native `hidden` attribute to toggle
+ * visibility. Inactive panels remain **mounted** — this preserves
+ * component state (scroll position, form input, animation state) across
+ * tab switches. If you need true unmount semantics (e.g. to tear down
+ * expensive subscriptions), render the `Tabs.Content` conditionally
+ * yourself based on the active value.
+ *
+ * When {@link TabsRootProps.lazyMount | `lazyMount`} is set on
+ * `Tabs.Root`, a panel's children are withheld until the tab is first
+ * activated. After that first activation the children remain mounted
+ * across subsequent tab switches (lazy mount, not unmount-on-hide).
+ * The `<div role="tabpanel">` wrapper always renders so the ARIA
+ * relationship between trigger and panel is always present in the DOM.
+ *
+ * **Styling hooks.**
+ * - `data-state="active" | "inactive"`.
+ * - `data-orientation="horizontal" | "vertical"`.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Tabs.Content value="account">
+ *   <AccountForm />
+ * </Tabs.Content>
+ * ```
+ */
+export declare function TabsContent({ children, className, value, ...rest }: TabsContentProps): ReactElement;
+export declare namespace TabsContent {
+    var displayName: string;
+}
+/** 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;
+    Content: typeof TabsContent;
+};
+/**
+ * Headless, accessible **Tabs** — a compound component implementing the
+ * WAI-ARIA Tabs pattern with zero styles.
+ *
+ * `Tabs` is both callable (it's an alias of {@link TabsRoot | `Tabs.Root`})
+ * and carries its sub-components as static properties. Prefer the
+ * namespaced form in application code for readability and grep-ability:
+ *
+ * - {@link TabsRoot | `Tabs.Root`} — state owner, context provider, imperative API holder.
+ * - {@link TabsList | `Tabs.List`} — `role="tablist"` container for triggers.
+ * - {@link TabsTrigger | `Tabs.Trigger`} — individual `role="tab"` button.
+ * - {@link TabsContent | `Tabs.Content`} — `role="tabpanel"` panel, linked to a trigger by `value`.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Tabs } from "@primitiv-ui/react";
+ *
+ * export function Demo() {
+ *   return (
+ *     <Tabs.Root defaultValue="a">
+ *       <Tabs.List label="Demo tabs">
+ *         <Tabs.Trigger value="a">First</Tabs.Trigger>
+ *         <Tabs.Trigger value="b">Second</Tabs.Trigger>
+ *       </Tabs.List>
+ *       <Tabs.Content value="a">First panel</Tabs.Content>
+ *       <Tabs.Content value="b">Second panel</Tabs.Content>
+ *     </Tabs.Root>
+ *   );
+ * }
+ * ```
+ *
+ * @example Styling with any system
+ * Because no styles ship with the component, target the rendered elements
+ * or the `data-state` / `data-orientation` hooks with whatever system you
+ * use (CSS, CSS-in-JS, Tailwind, design-token stylesheets, etc.):
+ *
+ * ```css
+ * [role="tab"][data-state="active"] { border-bottom: 2px solid currentColor; }
+ * [role="tabpanel"][data-state="inactive"] { display: none; }
+ * ```
+ *
+ * @see {@link TabsRoot} for state modes, validation behaviour, and the
+ *   imperative API.
+ * @see {@link TabsList} for the required `label` prop.
+ * @see {@link TabsTrigger} for the full keyboard-interaction table.
+ * @see {@link TabsContent} for panel lifecycle and unmount semantics.
+ */
+declare const TabsCompound: TabsCompound;
+export { TabsCompound as Tabs };