@primitiv-ui/react 0.1.28 → 0.1.29

package/src/Textarea/types.ts

@@ -1,11 +1,28 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
 /**
- * Props for {@link Textarea} — all native `<textarea>` attributes plus the
- * `asChild` escape hatch and a typed `ref`.
+ * Props for {@link Textarea} — all native `<textarea>` attributes (with `ref`
+ * typed as `Ref<HTMLTextAreaElement>`) plus the `asChild` escape hatch.
  */
-export type TextareaProps = ComponentProps<"textarea"> & {
+export type TextareaProps = Omit<ComponentProps<"textarea">, "ref"> & {
+  /**
+   * Renders the child element instead of a native `<textarea>`, merging all
+   * props — aria-*, data-*, event handlers, ref — onto it via {@link Slot}.
+   * Event handlers compose (child runs first). Use this to wrap a third-party
+   * autosizing textarea while keeping this component's prop contract.
+   * @default false
+   */
   asChild?: boolean;
+  /**
+   * Forwarded to the underlying `HTMLTextAreaElement`. Under `asChild`, merged
+   * onto the rendered child via {@link Slot}.
+   */
   ref?: Ref<HTMLTextAreaElement>;
+  /**
+   * Child content. Under `asChild`, must be a single React element that
+   * {@link Slot} merges props onto. Not used when rendering a native
+   * `<textarea>` (the element's content is controlled by `value` /
+   * `defaultValue`, not children).
+   */
   children?: ReactNode;
 };

package/src/Toggle/Toggle.tsx

@@ -11,24 +11,50 @@ import { ToggleProps } from "./types";
  * with the `aria-pressed` attribute. Renders a native
  * `<button type="button">` by default.
  *
- * Supports two state modes, statically discriminated at the type level:
+ * **Controlled vs uncontrolled.** Two state modes, statically discriminated at
+ * the type level so TypeScript rejects mixing them:
  *
  * - **Uncontrolled** — pass
- *   {@link ToggleProps.defaultPressed | `defaultPressed`} (or omit for
- *   unpressed on mount). The component owns the value internally.
- * - **Controlled** — pass
- *   {@link ToggleProps.pressed | `pressed`} *and*
- *   {@link ToggleProps.onPressedChange | `onPressedChange`} together.
- *   The parent owns the value; every click defers back through the callback.
+ *   {@link ToggleProps.defaultPressed | `defaultPressed`} (or omit entirely
+ *   for unpressed on mount). The component owns the pressed value internally.
+ * - **Controlled** — pass {@link ToggleProps.pressed | `pressed`} *and*
+ *   {@link ToggleProps.onPressedChange | `onPressedChange`} together. The
+ *   parent owns the value; every click defers back through the callback.
  *
- * **ARIA.** `aria-pressed` is set automatically to reflect the pressed state.
+ * **Keyboard support.** Keyboard activation is provided natively by the
+ * underlying `<button>` element — no custom `keydown` listeners are needed:
  *
- * **Styling hooks.** `data-state="on" | "off"` on the element, plus
- * `data-disabled=""` when disabled.
+ * | Key     | Behaviour                              |
+ * | ------- | -------------------------------------- |
+ * | `Space` | Toggles the button (native `<button>`) |
+ * | `Enter` | Toggles the button (native `<button>`) |
  *
- * **`asChild` prop.** Pass `asChild` to render any consumer-supplied element
- * with the toggle's `aria-pressed`, `data-state`, composed `onClick`, and
- * `ref` merged in. The native `<button>` is dropped.
+ * **Styling hooks.**
+ * - `data-state="on" | "off"` — mirrors the pressed state; use
+ *   `[data-state="on"]` to style the active appearance.
+ * - `data-disabled=""` — set when `disabled` is `true`; lets CSS target
+ *   `[data-disabled]` without relying on the `:disabled` pseudo-class.
+ *
+ * **`asChild` composition.** Pass `asChild` to render any consumer-supplied
+ * element instead of the default `<button>`. The toggle's `aria-pressed`,
+ * `data-state`, composed `onClick`, and `ref` are merged onto the child via
+ * {@link Slot}. The native `<button>` is dropped; the consumer is responsible
+ * for making the element focusable (e.g. `tabIndex={0}`, `role="button"`).
+ *
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLButtonElement` directly (or the `asChild` element when `asChild` is
+ * set):
+ *
+ * ```tsx
+ * const ref = useRef<HTMLButtonElement>(null);
+ * <Toggle ref={ref} aria-label="Bold">B</Toggle>
+ * ```
+ *
+ * **Disabled.** Sets the native `disabled` attribute (removing the button
+ * from the tab order and suppressing clicks) **and** sets `data-disabled=""`
+ * so CSS can target `[data-disabled]` without relying on `:disabled`.
+ *
+ * @extends HTMLButtonElement
  *
  * @example Uncontrolled
  * ```tsx
@@ -41,6 +67,18 @@ import { ToggleProps } from "./types";
  *
  * <Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">B</Toggle>
  * ```
+ *
+ * @example Disabled
+ * ```tsx
+ * <Toggle disabled aria-label="Bold (unavailable)">B</Toggle>
+ * ```
+ *
+ * @example asChild — render a custom element with toggle semantics
+ * ```tsx
+ * <Toggle asChild aria-label="Bold">
+ *   <div role="button" tabIndex={0}>B</div>
+ * </Toggle>
+ * ```
  */
 function Toggle({
   defaultPressed,

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

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

package/src/Toggle/types.ts

@@ -1,27 +1,77 @@
 import { ButtonHTMLAttributes, ReactNode, Ref } from "react";
 
-/** Uncontrolled `Toggle` props: seed with `defaultPressed`; `pressed`/`onPressedChange` are disallowed. */
+/**
+ * Uncontrolled {@link Toggle} props: seed the initial pressed state with
+ * `defaultPressed`; `pressed` and `onPressedChange` are disallowed in this
+ * mode. The component owns the pressed value internally.
+ */
 export type UncontrolledToggleProps = {
+  /**
+   * The pressed state on first render. Omit to start unpressed.
+   * Mutually exclusive with {@link ControlledToggleProps.pressed | `pressed`}.
+   * @default false
+   */
   defaultPressed?: boolean;
   pressed?: never;
   onPressedChange?: never;
 };
 
-/** Controlled `Toggle` props: drive with `pressed` and `onPressedChange`; `defaultPressed` is disallowed. */
+/**
+ * Controlled {@link Toggle} props: drive the pressed state with `pressed` and
+ * respond to toggle requests via `onPressedChange`; `defaultPressed` is
+ * disallowed in this mode. The parent owns the value.
+ */
 export type ControlledToggleProps = {
+  /**
+   * The current pressed state, owned by the caller. Every click fires
+   * {@link ControlledToggleProps.onPressedChange | `onPressedChange`} with the
+   * next value — the component does not update state itself.
+   */
   pressed: boolean;
+  /**
+   * Called with the next pressed value when the user clicks the toggle.
+   * The caller is responsible for updating the `pressed` prop accordingly.
+   */
   onPressedChange: (pressed: boolean) => void;
   defaultPressed?: never;
 };
 
-/** Props common to both `Toggle` modes: `disabled`, `asChild`, `children`, `ref`, and the native `<button>` attributes (minus `type`). */
+/**
+ * Props common to both controlled and uncontrolled {@link Toggle} modes:
+ * `disabled`, `asChild`, `children`, `ref`, and all native `<button>`
+ * attributes except `type` (which is fixed to `"button"` by the component).
+ */
 export type ToggleBaseProps = {
+  /**
+   * When `true`, sets the native `disabled` attribute (removing the button
+   * from the tab order and suppressing clicks) and adds `data-disabled=""`
+   * so CSS can target `[data-disabled]` without relying on `:disabled`.
+   */
   disabled?: boolean;
+  /**
+   * Renders the child element instead of the default `<button>`, merging
+   * `aria-pressed`, `data-state`, the composed `onClick`, and `ref` onto
+   * it via {@link Slot}. The child must be focusable (e.g. carry
+   * `tabIndex={0}` and `role="button"`).
+   * @default false
+   */
   asChild?: boolean;
+  /** Toggle content — text, icons, or any React node. */
   children?: ReactNode;
+  /**
+   * Forwarded to the underlying `HTMLButtonElement`, or — under
+   * `asChild` — merged onto the rendered child element.
+   */
   ref?: Ref<HTMLButtonElement>;
 } & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type">;
 
-/** Props for the `Toggle` button — base props combined with the controlled/uncontrolled discriminated union. */
+/**
+ * Props for the {@link Toggle} button — {@link ToggleBaseProps} combined with
+ * the controlled/uncontrolled discriminated union
+ * ({@link ControlledToggleProps} | {@link UncontrolledToggleProps}).
+ *
+ * TypeScript statically rejects mixing controlled and uncontrolled props
+ * (e.g. passing both `pressed` and `defaultPressed`).
+ */
 export type ToggleProps = ToggleBaseProps &
   (UncontrolledToggleProps | ControlledToggleProps);

package/src/ToggleGroup/ToggleGroup.tsx

@@ -46,6 +46,8 @@ import { ToggleGroupItemProps, ToggleGroupRootProps } from "./types";
  * element in place of the native `<div>`, with the group's `role`,
  * `data-orientation`, and ref merged in.
  *
+ * @extends HTMLDivElement
+ *
  * @example Single mode — text alignment
  * ```tsx
  * <ToggleGroup.Root type="single" defaultValue="left" aria-label="Alignment">
@@ -140,6 +142,7 @@ export function ToggleGroupRoot({
 }
 
 /** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 ToggleGroupRoot.displayName = "ToggleGroupRoot";
 
 /**
@@ -165,9 +168,19 @@ ToggleGroupRoot.displayName = "ToggleGroupRoot";
  *
  * **`asChild` prop.** Pass `asChild` to render any consumer element in
  * place of the native `<button>`, with the Item's `aria-pressed`,
- * `data-state`, `tabIndex`, and event handlers merged onto it.
+ * `data-state`, `tabIndex`, and event handlers merged onto it. The child
+ * must accept a `ref`. Useful for a link or a styled control that needs
+ * toggle-button semantics.
  *
  * @throws if rendered outside a `ToggleGroup.Root`.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
+ * <ToggleGroup.Item value="strike" disabled>Strikethrough</ToggleGroup.Item>
+ * ```
  */
 export function ToggleGroupItem({
   value,

package/src/ToggleGroup/__tests__/ToggleGroup.asChild.test.tsx

@@ -62,4 +62,24 @@ describe("ToggleGroup asChild composition", () => {
     expect(consumerClick).toHaveBeenCalledOnce();
     expect(item).toHaveAttribute("aria-pressed", "true");
   });
+
+  it("Item asChild activates on Space through the keyboard handler", async () => {
+    // A non-button element fires no native click on Space, so toggling can
+    // only come from the roving handler's activate mapping — the guarantee a
+    // native <button> would otherwise mask.
+    const user = userEvent.setup();
+    render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left" asChild>
+          <div>Left</div>
+        </ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+    const item = screen
+      .getByLabelText("Alignment")
+      .querySelector<HTMLElement>("[data-state]")!;
+    item.focus();
+    await user.keyboard(" ");
+    expect(item).toHaveAttribute("aria-pressed", "true");
+  });
 });

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

@@ -47,4 +47,13 @@ describe("ToggleGroup basic rendering", () => {
       "horizontal",
     );
   });
+
+  it("sets a displayName on the compound and Item", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // `ToggleGroup`, `ToggleGroup.Root`, and the underlying function are one
+    // object (Object.assign compound), so the compound's "ToggleGroup" alias is
+    // the observable Root displayName; only Item is a distinct object.
+    expect(ToggleGroup.displayName).toBe("ToggleGroup");
+    expect(ToggleGroup.Item.displayName).toBe("ToggleGroupItem");
+  });
 });

package/src/ToggleGroup/__tests__/ToggleGroup.dynamic-items.test.tsx

@@ -0,0 +1,70 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ToggleGroup } from "../ToggleGroup";
+
+function ItemsFixture({ items }: { items: string[] }) {
+  return (
+    <ToggleGroup.Root type="single" aria-label="Alignment">
+      {items.map((v) => (
+        <ToggleGroup.Item key={v} value={v}>
+          {v}
+        </ToggleGroup.Item>
+      ))}
+    </ToggleGroup.Root>
+  );
+}
+
+function DisabledFixture({ disabledItem }: { disabledItem?: string }) {
+  return (
+    <ToggleGroup.Root type="single" aria-label="Alignment">
+      <ToggleGroup.Item value="left" disabled={disabledItem === "left"}>
+        Left
+      </ToggleGroup.Item>
+      <ToggleGroup.Item value="center" disabled={disabledItem === "center"}>
+        Center
+      </ToggleGroup.Item>
+      <ToggleGroup.Item value="right" disabled={disabledItem === "right"}>
+        Right
+      </ToggleGroup.Item>
+    </ToggleGroup.Root>
+  );
+}
+
+describe("ToggleGroup dynamic items — registration lifecycle", () => {
+  it("unregisters an unmounted item so the tab stop moves to the survivor", () => {
+    // Arrange — "a" is the first enabled item, so it holds the tab stop.
+    const { rerender } = render(<ItemsFixture items={["a", "b"]} />);
+    expect(screen.getByRole("button", { name: "a" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+
+    // Act — remove "a"; its effect cleanup must unregister it.
+    rerender(<ItemsFixture items={["b"]} />);
+
+    // Assert — with "a" gone from the registry, "b" is now the tab stop. A
+    // no-op cleanup would leave "a" registered ahead of "b", stranding the
+    // tab stop on the detached element and leaving "b" at tabindex -1.
+    expect(screen.getByRole("button", { name: "b" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+  });
+
+  it("re-registers an item's disabled flag when it changes after mount", async () => {
+    // Arrange — all three enabled; focus can travel Left → Center → Right.
+    const user = userEvent.setup();
+    const { rerender } = render(<DisabledFixture />);
+
+    // Act — disable Center after mount, then navigate rightward from Left.
+    rerender(<DisabledFixture disabledItem="center" />);
+    screen.getByRole("button", { name: "Left" }).focus();
+    await user.keyboard("{ArrowRight}");
+
+    // Assert — the registrar effect re-ran, so Center is skipped and focus
+    // lands on Right. A stale registration would keep Center navigable and
+    // strand focus (a disabled button cannot receive it).
+    expect(screen.getByRole("button", { name: "Right" })).toHaveFocus();
+  });
+});

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

@@ -0,0 +1,23 @@
+import { render } from "@testing-library/react";
+
+import { ToggleGroup } from "../ToggleGroup";
+import { ToggleGroupContext } from "../ToggleGroupContext";
+
+describe("ToggleGroup error handling", () => {
+  it("throws a helpful error when ToggleGroup.Item is rendered outside Root", () => {
+    // Arrange
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Assert
+    expect(() =>
+      render(<ToggleGroup.Item value="left">Left</ToggleGroup.Item>),
+    ).toThrow(/ToggleGroup\.Item must be rendered inside a ToggleGroup\.Root/);
+
+    error.mockRestore();
+  });
+
+  it("names the context for React DevTools", () => {
+    // Assert — an empty displayName would render the provider as anonymous.
+    expect(ToggleGroupContext.displayName).toBe("ToggleGroupContext");
+  });
+});

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

@@ -1,4 +1,4 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
 import { ToggleGroup } from "../ToggleGroup";
@@ -45,6 +45,28 @@ describe("ToggleGroup keyboard — roving tabindex", () => {
       "-1",
     );
   });
+
+  it("moves the tab stop to the focused item (onFocus updates the home base)", () => {
+    // Arrange — nothing selected, so the first item is the initial tab stop.
+    render(<SingleFixture />);
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+
+    // Act — focusing another item should hand it the tab stop.
+    fireEvent.focus(screen.getByRole("button", { name: "Right" }));
+
+    // Assert — Right is now the sole tab stop; Left drops out of the sequence.
+    expect(screen.getByRole("button", { name: "Right" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "tabindex",
+      "-1",
+    );
+  });
 });
 
 describe("ToggleGroup keyboard — arrow key navigation (no auto-select)", () => {

package/src/ToggleGroup/__tests__/ToggleGroup.ref-forwarding.test.tsx

@@ -0,0 +1,58 @@
+import { render, screen } from "@testing-library/react";
+
+import { ToggleGroup } from "../ToggleGroup";
+
+describe("ToggleGroup.Item ref forwarding", () => {
+  it("forwards the underlying button element to a consumer function ref", () => {
+    // Arrange
+    const received: (HTMLButtonElement | null)[] = [];
+    const functionRef = (node: HTMLButtonElement | null) => {
+      received.push(node);
+    };
+
+    // Act
+    render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left" ref={functionRef}>
+          Left
+        </ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+
+    // Assert
+    expect(received).toContain(screen.getByRole("button", { name: "Left" }));
+  });
+
+  it("re-attaches to a replacement ref when the ref prop changes", () => {
+    // Arrange — the item's ref memo must depend on `ref`, or a changed ref
+    // callback is never invoked with the element.
+    const firstReceived: (HTMLButtonElement | null)[] = [];
+    const secondReceived: (HTMLButtonElement | null)[] = [];
+    const firstRef = (node: HTMLButtonElement | null) => {
+      firstReceived.push(node);
+    };
+    const secondRef = (node: HTMLButtonElement | null) => {
+      secondReceived.push(node);
+    };
+
+    // Act — mount with the first ref, then re-render with a different one.
+    const { rerender } = render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left" ref={firstRef}>
+          Left
+        </ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+    rerender(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left" ref={secondRef}>
+          Left
+        </ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+
+    // Assert — the replacement ref received the button.
+    const button = screen.getByRole("button", { name: "Left" });
+    expect(secondReceived).toContain(button);
+  });
+});

package/src/ToggleGroup/hooks/useToggleGroupRoot.ts

@@ -42,7 +42,16 @@ export function useToggleGroupRoot({
     (itemValue: string) => {
       const isSelected = value.includes(itemValue);
       if (type === "single") {
-        const next = isSelected ? [] : [itemValue];
+        // Deselecting clears the selection to the empty array. Stryker's
+        // ArrayDeclaration mutant fills this with a phantom value, but since
+        // that value can never equal a registered item's `value` — and single
+        // mode always overwrites the whole array on the next selection — no
+        // item ever reads it as pressed. The mutation is observationally
+        // identical, so it is isolated here to keep the disable off the tested
+        // `[itemValue]` literal below.
+        // Stryker disable next-line ArrayDeclaration
+        const cleared: string[] = [];
+        const next = isSelected ? cleared : [itemValue];
         setValue(next);
         (onValueChange as ((v: string | undefined) => void) | undefined)?.(
           isSelected ? undefined : itemValue,
@@ -68,6 +77,9 @@ export function useToggleGroupRoot({
     (itemValue: string, element: HTMLButtonElement | null, disabled = false) => {
       registerBase(itemValue, element ? { element, disabled } : null);
     },
+    // `registerBase` is a stable useCollection callback (its own deps never
+    // change), so emptying this array yields the identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
     [registerBase],
   );
 
@@ -83,8 +95,16 @@ export function useToggleGroupRoot({
 
   const focusItem = useCallback(
     (itemValue: string) => {
+      // `itemValue` is always sourced from `navigable` (the enabled subset of
+      // `itemValues`), and useCollection's register() writes `itemsRef` and the
+      // `itemValues` state together — so a value that reaches here is guaranteed
+      // to have a live entry in the map.
+      // Stryker disable next-line OptionalChaining: unreachable given that invariant.
       itemsRef.current.get(itemValue)?.element.focus();
     },
+    // `itemsRef` is a stable RefObject, so emptying this array yields the
+    // identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
     [itemsRef],
   );
 

package/src/ToggleGroup/types.ts

@@ -7,12 +7,27 @@ import { HTMLAttributes, ButtonHTMLAttributes, ReactNode, Ref } from "react";
  */
 export type ToggleGroupRootBaseProps = Omit<
   HTMLAttributes<HTMLDivElement>,
-  "dir"
+  "dir" | "defaultValue"
 > & {
+  /** Layout axis for keyboard navigation. `"horizontal"` binds
+   * ArrowLeft/ArrowRight; `"vertical"` binds ArrowUp/ArrowDown. Surfaces as
+   * `data-orientation` on the root for styling; it does not itself apply any
+   * flex/grid layout.
+   * @default "horizontal" */
   orientation?: "horizontal" | "vertical";
+  /** Reading direction. In `"rtl"` the horizontal arrow keys are mirrored so
+   * focus follows the visual order. Inherited from the nearest
+   * {@link DirectionProvider} when omitted, falling back to `"ltr"`. */
   dir?: "ltr" | "rtl";
+  /** Render a single consumer-supplied element in place of the native
+   * `<div>`, with the group's `role="group"`, `data-orientation`, and `ref`
+   * merged onto it via the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
+  /** The {@link ToggleGroupItemProps | `ToggleGroup.Item`} elements that make
+   * up the segmented control. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLDivElement`. */
   ref?: Ref<HTMLDivElement>;
 };
 
@@ -21,9 +36,15 @@ export type ToggleGroupRootBaseProps = Omit<
  * initial value supplied via `defaultValue`.
  */
 export type SingleUncontrolledProps = {
+  /** Selects single-selection semantics: at most one item pressed at a time,
+   * and pressing the active item again clears the selection. */
   type: "single";
+  /** Value of the item pressed on first render. Omit to start with nothing
+   * pressed. */
   defaultValue?: string;
+  /** Forbidden in uncontrolled mode — use `defaultValue`. */
   value?: never;
+  /** Forbidden in uncontrolled mode. */
   onValueChange?: never;
 };
 
@@ -32,9 +53,16 @@ export type SingleUncontrolledProps = {
  * caller via `value` / `onValueChange`.
  */
 export type SingleControlledProps = {
+  /** Selects single-selection semantics: at most one item pressed at a time,
+   * and pressing the active item again clears the selection. */
   type: "single";
+  /** The currently pressed item's value, or `undefined` when none is pressed.
+   * Must be kept in sync by the caller via `onValueChange`. */
   value: string | undefined;
+  /** Called with the requested next value — the pressed item's value, or
+   * `undefined` when the active item is pressed again to deselect it. */
   onValueChange: (value: string | undefined) => void;
+  /** Forbidden in controlled mode — use `value`. */
   defaultValue?: never;
 };
 
@@ -43,9 +71,15 @@ export type SingleControlledProps = {
  * the initial set supplied via `defaultValue`.
  */
 export type MultipleUncontrolledProps = {
+  /** Selects multiple-selection semantics: any number of items can be pressed
+   * simultaneously and each toggles independently. */
   type: "multiple";
+  /** Values of the items pressed on first render. Omit to start with nothing
+   * pressed. */
   defaultValue?: string[];
+  /** Forbidden in uncontrolled mode — use `defaultValue`. */
   value?: never;
+  /** Forbidden in uncontrolled mode. */
   onValueChange?: never;
 };
 
@@ -54,9 +88,16 @@ export type MultipleUncontrolledProps = {
  * by the caller via `value` / `onValueChange`.
  */
 export type MultipleControlledProps = {
+  /** Selects multiple-selection semantics: any number of items can be pressed
+   * simultaneously and each toggles independently. */
   type: "multiple";
+  /** The full set of currently pressed item values. Must be kept in sync by
+   * the caller via `onValueChange`. */
   value: string[];
+  /** Called with the complete next array of pressed values whenever the user
+   * toggles any item. */
   onValueChange: (value: string[]) => void;
+  /** Forbidden in controlled mode — use `value`. */
   defaultValue?: never;
 };
 
@@ -81,11 +122,23 @@ export type ToggleGroupRootProps = ToggleGroupRootBaseProps &
  */
 export type ToggleGroupItemProps = Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
-  "type"
+  "type" | "value"
 > & {
+  /** Identifies this item within the group. It is this string — not the
+   * visible label — that is compared against the group's pressed
+   * `value` / `defaultValue`; use `children` for the label. */
   value: string;
+  /** Forwards the native `disabled` attribute and removes the item from the
+   * roving tab order so arrow-key navigation skips it. Also sets
+   * `data-disabled=""` for CSS targeting.
+   * @default false */
   disabled?: boolean;
+  /** Render a single consumer-supplied element in place of the native
+   * `<button>`, with the item's `aria-pressed`, `data-state`, `tabIndex`, and
+   * event handlers merged onto it via the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
+  /** Forwarded to the underlying `HTMLButtonElement`. */
   ref?: Ref<HTMLButtonElement>;
 };