@primitiv-ui/react 0.1.28 → 0.1.29

package/src/Status/Status.tsx

@@ -4,29 +4,50 @@ import { Slot } from "../Slot/index.ts";
 import { StatusProps } from "./types";
 
 /**
- * A polite live region for low-priority, non-urgent status messages.
+ * A polite live region for low-priority, non-urgent status messages,
+ * implementing the WAI-ARIA `status` role.
  *
- * Renders a `<div role="status">`. The `status` role carries an
- * implicit `aria-live="polite"` and `aria-atomic="true"`, so assistive
- * technology announces the message once the user is idle, without
- * interrupting them — use it for confirmations, counts, and background
- * progress. For errors the user must see immediately, reach for
- * `Alert` instead.
+ * Renders a `<div role="status">`. The `status` role carries an implicit
+ * `aria-live="polite"` and `aria-atomic="true"`, so assistive technology
+ * announces the message once the user is idle, without interrupting
+ * them — use it for confirmations, counts, and background progress. For
+ * errors the user must see immediately, reach for `Alert` instead.
  *
- * Render the `Status` conditionally, or update its text content while
- * it stays mounted: the live region announces content that changes
- * *after* it is already in the DOM.
+ * **Live region timing.** A live region only announces content that
+ * changes *after* the region is already in the DOM. Either render
+ * `Status` conditionally (mount when a message is ready), or keep it
+ * mounted and update its text:
  *
- * **`asChild` composition.** Renders the consumer's element instead of
- * a `<div>`, merging `role="status"` and all other props in via the
- * {@link Slot} utility.
+ * ```tsx
+ * // Conditional mount — announces on first appearance
+ * {saved && <Status>All changes saved.</Status>}
+ *
+ * // Persistent — announces on every content change
+ * <Status>{count} items in your cart</Status>
+ * ```
+ *
+ * **`asChild` composition.** Pass `asChild` to render the consumer's own
+ * element instead of a `<div>`, merging `role="status"` and all other
+ * props onto it via the {@link Slot} utility. Event handlers compose with
+ * the child's own handlers (child runs first).
+ *
+ * @extends HTMLDivElement
  *
  * @example Confirmation message
  * ```tsx
- * {saved && <Status>All changes saved.</Status>}
+ * import { Status } from "@primitiv-ui/react";
+ *
+ * function SaveIndicator({ saved }: { saved: boolean }) {
+ *   return saved ? <Status>All changes saved.</Status> : null;
+ * }
+ * ```
+ *
+ * @example Cart count — persistent live region
+ * ```tsx
+ * <Status>{count} items in your cart</Status>
  * ```
  *
- * @example asChild — keep semantic markup
+ * @example asChild — apply the status role to a semantic element
  * ```tsx
  * <Status asChild>
  *   <output>{count} items in your cart</output>

package/src/Status/__tests__/Status.test.tsx

@@ -25,4 +25,9 @@ describe("Status component", () => {
     expect(status.tagName).toBe("SECTION");
     expect(status).toHaveTextContent("Saved");
   });
+
+  it('sets displayName to "Status" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(Status.displayName).toBe("Status");
+  });
 });

package/src/Status/types.ts

@@ -1,9 +1,20 @@
-import { ComponentProps } from "react";
+import { ComponentProps, ReactNode } from "react";
 
 /**
  * Props for {@link Status} — all native `<div>` attributes plus the
  * `asChild` escape hatch.
  */
 export type StatusProps = ComponentProps<"div"> & {
+  /**
+   * Renders the child element instead of a native `<div>`, merging
+   * `role="status"` and all other props onto it via {@link Slot}.
+   * Event handlers compose with the child's own handlers (child runs
+   * first). Use this to apply the live-region role to a semantically
+   * appropriate element (e.g. `<output>`).
+   * @default false
+   */
   asChild?: boolean;
+  /** Content to announce. A live region announces changes that occur
+   * after the region is already present in the DOM. */
+  children?: ReactNode;
 };

package/src/Switch/Switch.tsx

@@ -42,6 +42,12 @@ function dataStateOf(checked: boolean) {
  * **Keyboard.** Toggles on `Space` (the native checkbox behaviour); `Enter`
  * does not toggle a checkbox-based control.
  *
+ * **`onChange` composition.** The consumer's raw `onChange` fires first; if it
+ * calls `event.preventDefault()`, the internal mirror update and
+ * `onCheckedChange` are skipped for that event. See {@link SwitchRootBaseProps}.
+ *
+ * @extends HTMLInputElement
+ *
  * @example Uncontrolled
  * ```tsx
  * <Switch.Root name="notify" value="on" defaultChecked aria-label="Enable notifications">
@@ -102,7 +108,11 @@ export function SwitchRoot({
   );
 }
 
-/** @internal */
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "Switch" at load, so the value is never observable. The
+// assignment stays because it declares `displayName` on `typeof SwitchRoot`,
+// which TSwitchCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 SwitchRoot.displayName = "SwitchRoot";
 
 /**
@@ -114,7 +124,10 @@ SwitchRoot.displayName = "SwitchRoot";
  * **Styling hook.** Mirrors the root's `data-state="checked" | "unchecked"`.
  *
  * **`asChild` prop.** Pass `asChild` to render the consumer's own element as
- * the thumb, with `aria-hidden` and `data-state` merged in.
+ * the thumb, with `aria-hidden` and `data-state` merged in via the
+ * {@link Slot} pattern. See {@link SwitchThumbProps}.
+ *
+ * @extends HTMLSpanElement
  *
  * @example
  * ```tsx

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

@@ -92,4 +92,11 @@ describe("Switch basic rendering", () => {
     expect(thumb).toHaveAttribute("aria-hidden", "true");
     expect(thumb).toHaveAttribute("data-state", "unchecked");
   });
+
+  it("sets a displayName on the compound and the Thumb", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "Switch".
+    expect(Switch.displayName).toBe("Switch");
+    expect(Switch.Thumb.displayName).toBe("SwitchThumb");
+  });
 });

package/src/Switch/hooks/useSwitchRoot.ts

@@ -34,6 +34,9 @@ export function useSwitchRoot({
     onChange?.(event);
     if (event.defaultPrevented) return;
     const next = event.target.checked;
+    // Stryker disable next-line ConditionalExpression: in controlled mode
+    // `checked` reads controlledChecked, never `mirror`, so setting mirror here
+    // (the mutant's always-run form) has no observable effect — equivalent.
     if (!isControlled) setMirror(next);
     onCheckedChange?.(next);
   };

package/src/Switch/types.ts

@@ -1,50 +1,67 @@
 import { ChangeEventHandler, ComponentProps, ReactNode, Ref } from "react";
 
 /**
- * Props common to both controlled and uncontrolled `Switch.Root` modes — the
- * native `<input type="checkbox">` attributes (minus the ones the component
- * owns). `className` / `style` style the **track** (the visible control), not
- * the hidden input; everything else spreads onto the input, because
- * semantically the Root *is* the switch.
+ * Shared base for both {@link SwitchRootProps} variants — the native
+ * `<input type="checkbox">` attributes (minus the ones the component owns:
+ * `type`, `role`, `checked`, and `defaultChecked`), plus `children` and a
+ * typed `ref`.
+ *
+ * Prop routing: `className` / `style` style the **track** (the visible
+ * `<label>`, since the input is visually hidden); every other prop — `name`,
+ * `value`, `id`, `aria-*`, `required`, `disabled`, `ref`, … — spreads onto the
+ * hidden `<input>`, because semantically the Root *is* the switch.
  */
 export type SwitchRootBaseProps = Omit<
   ComponentProps<"input">,
   "type" | "role" | "checked" | "defaultChecked"
 > & {
-  /** Optional content (typically `Switch.Thumb`). */
+  /** Content of the switch — typically a single
+   * {@link SwitchThumbProps | `Switch.Thumb`}. */
   children?: ReactNode;
-  /** Ref to the underlying native `<input>` element. */
+  /** Forwarded to the underlying native `HTMLInputElement` (the real,
+   * visually-hidden checkbox), not the visible track. */
   ref?: Ref<HTMLInputElement>;
 };
 
 /**
- * Props for `Switch.Root` in uncontrolled mode — the **browser** owns the
- * checked state. Pass `defaultChecked` to set the initial value; `checked` is
- * forbidden.
+ * Uncontrolled variant of {@link SwitchRootProps}: the **browser** owns the
+ * checked state, so the switch participates in native form submission and
+ * reset. Pass `defaultChecked` (or omit it); `checked` is forbidden.
  */
 export type SwitchRootUncontrolledProps = SwitchRootBaseProps & {
-  /** Initial checked state when uncontrolled. */
+  /** Checked state on first render. Defaults to `false` when omitted.
+   * @default false */
   defaultChecked?: boolean;
-  /** Forbidden in uncontrolled mode. */
+  /** Forbidden in uncontrolled mode — use `defaultChecked` instead. */
   checked?: never;
-  /** Called whenever the checked state changes. */
+  /** Called with the new boolean state whenever the switch toggles. Optional
+   * in uncontrolled mode. */
   onCheckedChange?: (checked: boolean) => void;
 };
 
 /**
- * Props for `Switch.Root` in controlled mode — the parent owns the checked
- * value. Pass `checked` and `onCheckedChange` together.
+ * Controlled variant of {@link SwitchRootProps}: the parent owns the checked
+ * value. Pass `checked` and `onCheckedChange` together; `defaultChecked` is
+ * forbidden.
  */
 export type SwitchRootControlledProps = SwitchRootBaseProps & {
-  /** Forbidden in controlled mode. */
+  /** Forbidden in controlled mode — use `checked` instead. */
   defaultChecked?: never;
-  /** The controlled checked state. */
+  /** The controlled checked state. Must be kept in sync by the parent via
+   * `onCheckedChange`. */
   checked: boolean;
-  /** Called whenever the component requests a checked-state change. */
+  /** Called with the new boolean state whenever the user requests a toggle.
+   * Required in controlled mode. */
   onCheckedChange: (checked: boolean) => void;
 };
 
-/** Props for `Switch.Root` — discriminated controlled/uncontrolled union. */
+/**
+ * Props for {@link SwitchRoot | `Switch.Root`}.
+ *
+ * Resolves to either {@link SwitchRootUncontrolledProps} or
+ * {@link SwitchRootControlledProps} — only one shape is accepted by TypeScript
+ * at a time.
+ */
 export type SwitchRootProps =
   | SwitchRootUncontrolledProps
   | SwitchRootControlledProps;
@@ -56,11 +73,21 @@ export type SwitchRootProps =
  */
 export type SwitchProps = SwitchRootProps;
 
-/** Props for `Switch.Thumb`, the sliding indicator inside the track. */
+/**
+ * Props for {@link SwitchThumb | `Switch.Thumb`} — the decorative sliding
+ * indicator inside the track. All `HTMLSpanElement` attributes, plus the
+ * `asChild` escape hatch.
+ */
 export type SwitchThumbProps = ComponentProps<"span"> & {
-  /** Optional thumb content. */
+  /** Optional thumb content (rarely needed — the thumb is usually styled
+   * purely with CSS). */
   children?: ReactNode;
-  /** Render the child element instead of the default `<span>`. */
+  /**
+   * When `true`, render the consumer's own element as the thumb instead of the
+   * default `<span>`, merging `aria-hidden` and `data-state` onto it via the
+   * {@link Slot} pattern.
+   * @default false
+   */
   asChild?: boolean;
 };
 

package/src/Table/Table.tsx

@@ -16,13 +16,22 @@ import {
  * The root of a Table widget — renders a plain `<table>` element and passes
  * all `TableHTMLAttributes` through to the DOM.
  *
+ * Stateless: `Table` is a purely structural compound with no context, no
+ * internal state, and no `data-*` attributes of its own (verified by
+ * `Table.contract.test.tsx` against the registry contract) — every part
+ * renders exactly what its native HTML element provides.
+ *
  * The `<table>` element carries an implicit `role="table"` in the accessibility
  * tree. Assistive technology will announce it as a table and report the number
  * of rows and columns to the user.
  *
- * Always pair column headers (`Table.Header`) with the correct
- * {@link TableHeaderProps.scope | `scope`} attribute so screen readers can
- * associate data cells with their headers.
+ * Always pair column headers ({@link TableHeader | `Table.Header`}) with the
+ * correct {@link TableHeaderProps.scope | `scope`} attribute so screen
+ * readers can associate data cells with their headers. Wrap the whole table
+ * in {@link TableScrollArea | `Table.ScrollArea`} when it has many columns
+ * and needs to scroll horizontally on narrow viewports.
+ *
+ * @extends HTMLTableElement
  *
  * @example
  * ```tsx
@@ -54,7 +63,12 @@ TableRoot.displayName = "Table";
  *
  * Browsers and assistive technology treat rows inside `<thead>` as column
  * headers. When a table is printed across multiple pages, the browser may
- * repeat the `<thead>` content at the top of each page.
+ * repeat the `<thead>` content at the top of each page. Renders as a direct
+ * child of {@link TableRoot | `Table.Root`}'s `<table>`, typically
+ * containing a single {@link TableRow | `Table.Row`} of
+ * {@link TableHeader | `Table.Header`}s.
+ *
+ * @extends HTMLTableSectionElement
  *
  * @example
  * ```tsx
@@ -79,7 +93,9 @@ TableHead.displayName = "TableHead";
  * Using `<tbody>` explicitly improves accessibility and allows browsers to
  * scroll the body independently of a fixed header. Multiple `<tbody>` elements
  * are valid and useful for visually separating logical row groups within a
- * single table.
+ * single table — render more than one `Table.Body` as siblings for that case.
+ *
+ * @extends HTMLTableSectionElement
  *
  * @example
  * ```tsx
@@ -103,7 +119,11 @@ TableBody.displayName = "TableBody";
  *
  * Typically used for summary rows — totals, averages, counts. When a table is
  * printed across multiple pages some browsers repeat the `<tfoot>` content at
- * the bottom of each page.
+ * the bottom of each page. Renders as a sibling of
+ * {@link TableHead | `Table.Head`} and {@link TableBody | `Table.Body`}
+ * inside {@link TableRoot | `Table.Root`}.
+ *
+ * @extends HTMLTableSectionElement
  *
  * @example
  * ```tsx
@@ -128,9 +148,13 @@ TableFooter.displayName = "TableFooter";
 /**
  * An individual table row — renders a `<tr>` element.
  *
- * May contain `Table.Header` (`<th>`) or `Table.Cell` (`<td>`) children, or a
- * mix of both when the row contains both header and data cells (e.g. the first
- * column of each row is a row header).
+ * May contain {@link TableHeader | `Table.Header`} (`<th>`) or
+ * {@link TableCell | `Table.Cell`} (`<td>`) children, or a mix of both when
+ * the row contains both header and data cells (e.g. the first column of each
+ * row is a row header). Lives inside {@link TableHead | `Table.Head`},
+ * {@link TableBody | `Table.Body`}, or {@link TableFooter | `Table.Footer`}.
+ *
+ * @extends HTMLTableRowElement
  *
  * @example
  * ```tsx
@@ -166,6 +190,8 @@ TableRow.displayName = "TableRow";
  * All `ThHTMLAttributes` (including `colSpan`, `rowSpan`, `abbr`) pass
  * through to the DOM.
  *
+ * @extends HTMLTableCellElement
+ *
  * @example Column header
  * ```tsx
  * <Table.Header scope="col">Name</Table.Header>
@@ -190,7 +216,11 @@ TableHeader.displayName = "TableHeader";
  * A data cell — renders a `<td>` element.
  *
  * All `TdHTMLAttributes` pass through to the DOM, including `colSpan` and
- * `rowSpan` for spanning multiple columns or rows.
+ * `rowSpan` for spanning multiple columns or rows. Use
+ * {@link TableHeader | `Table.Header`} instead when a cell's content is a
+ * label for a row or column rather than data.
+ *
+ * @extends HTMLTableCellElement
  *
  * @example Basic cell
  * ```tsx
@@ -228,6 +258,8 @@ TableCell.displayName = "TableCell";
  * </Table.ScrollArea>
  * ```
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Table.ScrollArea>
@@ -277,6 +309,8 @@ TableScrollArea.displayName = "TableScrollArea";
  * | `"bottom"` (default) | Below the table |
  * | `"top"` | Above the table |
  *
+ * @extends HTMLTableCaptionElement
+ *
  * @example Default (caption below table)
  * ```tsx
  * <Table.Root>

package/src/Table/types.ts

@@ -6,58 +6,107 @@ import type {
   TdHTMLAttributes,
 } from "react";
 
-/** Props for {@link Table.Root} — all `TableHTMLAttributes` on `<table>`. */
+/**
+ * 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 Table.Head} — all `HTMLAttributes` on `<thead>`. */
+/**
+ * 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 Table.Body} — all `HTMLAttributes` on `<tbody>`. */
+/**
+ * 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 Table.Footer} — all `HTMLAttributes` on `<tfoot>`. */
+/**
+ * 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 Table.Row} — all `HTMLAttributes` on `<tr>`. */
+/**
+ * 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 Table.Header} — all `ThHTMLAttributes` on `<th>`.
+ * 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.
+ * associate data cells with the correct header. See the scope table on
+ * {@link TableHeader}.
+ *
+ * @extends HTMLTableCellElement
  */
 export type TableHeaderProps = ThHTMLAttributes<HTMLTableCellElement>;
 
 /**
- * Props for {@link Table.Cell} — all `TdHTMLAttributes` on `<td>`.
+ * 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 Table.ScrollArea} — `children` plus all `HTMLAttributes`
- * on the wrapping `<div>`.
+ * Props for {@link TableScrollArea | `Table.ScrollArea`} — a required
+ * `children` plus all `HTMLAttributes` on the wrapping `<div>`.
  *
- * Any `style` properties you pass are merged with (and take priority over) the
- * base scroll styles (`display: block`, `overflow-x: auto`, `max-width: 100%`).
+ * @extends HTMLDivElement
  */
 export type TableScrollAreaProps = {
+  /** The table (typically a single {@link TableRoot | `Table.Root`}) to
+   * wrap in the horizontally-scrolling container. */
   children: ReactNode;
-} & HTMLAttributes<HTMLDivElement>;
+  /**
+   * 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">;
 
 /**
- * Props for {@link Table.Caption} — `children`, an optional
- * `captionSide`, plus all `HTMLAttributes` on `<caption>`.
+ * 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.
-   * - `"bottom"` (default) — caption appears below the table.
+   * 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/src/Tabs/Tabs.tsx

@@ -66,6 +66,8 @@ import type {
  * inherited from the nearest {@link DirectionProvider}, falling back to
  * `"ltr"` when there is no provider.
  *
+ * @extends HTMLDivElement
+ *
  * @example Uncontrolled
  * ```tsx
  * <Tabs.Root defaultValue="overview">
@@ -160,6 +162,8 @@ TabsRoot.displayName = "TabsRoot";
  *
  * **Styling hooks.** `data-orientation="horizontal" | "vertical"`.
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Tabs.List label="Document sections">
@@ -241,6 +245,8 @@ TabsList.displayName = "TabsList";
  * - `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>
@@ -345,6 +351,8 @@ TabsTrigger.displayName = "TabsTrigger";
  * - `data-state="active" | "inactive"`.
  * - `data-orientation="horizontal" | "vertical"`.
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Tabs.Content value="account">

package/src/Tabs/types.ts

@@ -60,9 +60,18 @@ export type ControlledTabsRootProps = {
  * the `HTMLDivElement` `ref` left in, a styled wrapper that spreads these props
  * straight back into `Tabs.Root` (`<Tabs.Root {...props} />`) would fail to
  * type-check on incompatible `ref` types (D58). */
-export type TabsRootProps = Omit<ComponentProps<"div">, "onChange" | "ref"> & {
+export type TabsRootProps = Omit<
+  ComponentProps<"div">,
+  "onChange" | "ref" | "dir" | "defaultValue"
+> & {
+  /** Layout axis; see {@link TabsOrientation}.
+   * @default "horizontal" */
   orientation?: TabsOrientation;
+  /** Reading direction; see {@link TabsReadingDirection}. Inherited from the
+   * nearest `DirectionProvider` when omitted, falling back to `"ltr"`. */
   dir?: TabsReadingDirection;
+  /** When a focused trigger becomes active; see {@link TabsActivationMode}.
+   * @default "automatic" */
   activationMode?: TabsActivationMode;
   /** When `true`, a panel's children are not rendered until that tab is first
    * activated. Once mounted they remain in the DOM across subsequent tab
@@ -105,8 +114,19 @@ export type TabsListProps = Omit<
   "label" | "aria-labelledby"
 > &
   (
-    | { label: string; ariaLabelledBy?: never }
-    | { label?: never; ariaLabelledBy: string }
+    | {
+        /** Accessible name for the tablist, announced as `aria-label`. Pick a
+         * short, human-readable description of the set (e.g. `"Account
+         * sections"`, not `"Tabs"`). Mutually exclusive with `ariaLabelledBy`. */
+        label: string;
+        ariaLabelledBy?: never;
+      }
+    | {
+        label?: never;
+        /** Id of an existing element to use as the tablist's accessible name,
+         * set as `aria-labelledby`. Mutually exclusive with `label`. */
+        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.
@@ -114,9 +134,14 @@ export type TabsListProps = Omit<
  * `asChild` and the `ref` type parameter. */
 export type TabsTriggerProps<T extends HTMLElement = HTMLButtonElement> = Omit<
   ComponentProps<"button">,
-  "ref"
+  "ref" | "value"
 > & {
+  /** Removes the trigger from the roving tab order and marks it
+   * `aria-disabled`/`data-disabled`; arrow-key navigation skips it.
+   * @default false */
   disabled?: boolean;
+  /** Identifies this trigger, linking it to the `Tabs.Content` of the same
+   * value. Not the visible label — use `children` for that. */
   value: string;
   /** Render the child element instead of the default `<button>`. All tab
    * ARIA attributes and event handlers are merged onto the child. The child

package/src/Textarea/Textarea.tsx

@@ -39,10 +39,18 @@ import { TextareaProps } from "./types";
  * textarea[data-disabled] { opacity: 0.5; cursor: not-allowed; }
  * ```
  *
+ * **Styling hooks.**
+ * - `data-disabled=""` — present when `disabled` is `true`; omitted otherwise.
+ *   Target with `[data-disabled]` rather than the `:disabled` pseudo-class so
+ *   styles work identically in both native and `asChild` modes.
+ *
  * **`asChild` composition.** Renders the consumer's element instead of
  * `<textarea>`, merging all props (aria-*, data-*, event handlers, ref)
  * via the {@link Slot} utility. Use it to wrap an autosizing textarea
- * implementation while keeping this component's prop contract.
+ * implementation while keeping this component's prop contract. Event handlers
+ * compose with the child's own handlers (child runs first).
+ *
+ * @extends HTMLTextAreaElement
  *
  * @example Basic usage
  * ```tsx

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

@@ -104,4 +104,9 @@ describe("Textarea basic rendering", () => {
     // Assert
     expect(onChange).toHaveBeenCalledTimes(2);
   });
+
+  it('sets displayName to "Textarea" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(Textarea.displayName).toBe("Textarea");
+  });
 });