@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Tabs/__tests__/Tabs.activation-mode.test.tsx

@@ -28,6 +28,64 @@ describe("Activation mode tests", () => {
     expect(secondTabPanel).not.toHaveAttribute("hidden");
   });
 
+  it("does not activate a tab on arrow navigation in manual mode", async () => {
+    // Directly asserts the manual guard: arrow moves focus without activating,
+    // so Tab 1 stays selected and Tab 2 does not.
+    const user = userEvent.setup();
+    render(
+      <Tabs.Root defaultValue="tab1" activationMode="manual">
+        <Tabs.List label="Test tabs">
+          <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+          <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+        </Tabs.List>
+        <Tabs.Content value="tab1">Content 1</Tabs.Content>
+        <Tabs.Content value="tab2">Content 2</Tabs.Content>
+      </Tabs.Root>,
+    );
+
+    await user.tab();
+    await user.keyboard("{ArrowRight}");
+
+    expect(screen.getByRole("tab", { name: "Tab 2" })).toHaveAttribute(
+      "aria-selected",
+      "false",
+    );
+    expect(screen.getByRole("tab", { name: "Tab 1" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  });
+
+  it("activates a non-native asChild tab via the roving Enter handler (manual)", async () => {
+    // A plain <div> fires no synthetic click on Enter, so activation can only
+    // come from the roving hook's includeActivate mapping — the guarantee a
+    // native <button> would mask.
+    const user = userEvent.setup();
+    render(
+      <Tabs.Root defaultValue="tab1" activationMode="manual">
+        <Tabs.List label="Test tabs">
+          <Tabs.Trigger asChild value="tab1">
+            <div>Tab 1</div>
+          </Tabs.Trigger>
+          <Tabs.Trigger asChild value="tab2">
+            <div>Tab 2</div>
+          </Tabs.Trigger>
+        </Tabs.List>
+        <Tabs.Content value="tab1">Content 1</Tabs.Content>
+        <Tabs.Content value="tab2">Content 2</Tabs.Content>
+      </Tabs.Root>,
+    );
+
+    await user.tab();
+    await user.keyboard("{ArrowRight}");
+    await user.keyboard("{Enter}");
+
+    expect(screen.getByRole("tab", { name: "Tab 2" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  });
+
   it("should not activate the second tab when focusing its tab in manual mode", async () => {
     // Arrange
     const user = userEvent.setup();

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

@@ -1,6 +1,21 @@
 import { render, screen } from "@testing-library/react";
 
 import { Tabs, TabsOrientation } from "../index.ts";
+import { TabsContext } from "../TabsContext";
+
+describe("Tabs displayNames", () => {
+  it("sets a displayName on the compound, each sub-component, and the context", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // `Tabs`, `Tabs.Root`, and the underlying component are one object
+    // (Object.assign compound), so the compound's "Tabs" alias is the
+    // observable Root displayName; the sub-components are distinct objects.
+    expect(Tabs.displayName).toBe("Tabs");
+    expect(Tabs.List.displayName).toBe("TabsList");
+    expect(Tabs.Trigger.displayName).toBe("TabsTrigger");
+    expect(Tabs.Content.displayName).toBe("TabsContent");
+    expect(TabsContext.displayName).toBe("TabsContext");
+  });
+});
 
 describe("Tabs basic rendering tests", () => {
   describe("Tabs.Root", () => {

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

@@ -110,6 +110,30 @@ describe('Tabs change event callbacks', () => {
       expect(handleChange).not.toHaveBeenCalled();
     });
 
+    it('does not re-fire onChange when re-clicking a tab activated after mount', async () => {
+      // No defaultValue: the guard reads an activeValue that changes after the
+      // first click, so a stale activateTab closure would re-fire on the second.
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+
+      render(
+        <Tabs.Root onChange={handleChange}>
+          <Tabs.List label="Test tabs">
+            <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+            <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+          </Tabs.List>
+          <Tabs.Content value="tab1">Content 1</Tabs.Content>
+          <Tabs.Content value="tab2">Content 2</Tabs.Content>
+        </Tabs.Root>,
+      );
+
+      const tab2 = screen.getByRole('tab', { name: 'Tab 2' });
+      await user.click(tab2);
+      await user.click(tab2);
+
+      expect(handleChange).toHaveBeenCalledTimes(1);
+    });
+
     it('should not call onValueChange if clicking already active tab in controlled mode', async () => {
       const user = userEvent.setup();
       const handleValueChange = vi.fn();

package/src/Tabs/__tests__/Tabs.disabled-tabs.test.tsx

@@ -2,6 +2,42 @@ import { render, screen } from "@testing-library/react";
 import { Tabs } from "../Tabs";
 import userEvent from "@testing-library/user-event";
 
+describe("Tabs disabled re-registration", () => {
+  it("re-registers a trigger's disabled flag when it changes after mount", async () => {
+    // Arrange — automatic mode: arrowing onto a tab activates it unless the
+    // trigger is registered as disabled. Tab 2 starts enabled, then disables.
+    const user = userEvent.setup();
+    function Fixture({ tab2Disabled }: { tab2Disabled: boolean }) {
+      return (
+        <Tabs.Root defaultValue="tab1">
+          <Tabs.List label="Test tabs">
+            <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+            <Tabs.Trigger value="tab2" disabled={tab2Disabled}>
+              Tab 2
+            </Tabs.Trigger>
+          </Tabs.List>
+          <Tabs.Content value="tab1">Content 1</Tabs.Content>
+          <Tabs.Content value="tab2">Content 2</Tabs.Content>
+        </Tabs.Root>
+      );
+    }
+    const { rerender } = render(<Fixture tab2Disabled={false} />);
+
+    // Act — disable Tab 2 after mount, then arrow onto it.
+    rerender(<Fixture tab2Disabled />);
+    await user.tab();
+    await user.keyboard("{ArrowRight}");
+
+    // Assert — the registrar effect re-ran, so Tab 2 is focused but NOT
+    // activated. A stale registration would treat it as enabled and activate
+    // it on arrow (automatic mode).
+    expect(screen.getByRole("tab", { name: "Tab 2" })).toHaveAttribute(
+      "aria-selected",
+      "false",
+    );
+  });
+});
+
 describe("Tabs disabled tabs tests", () => {
   it("should have the aria-disabled attribute set to false by default", () => {
     // Arrange

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

@@ -26,6 +26,23 @@ describe("Tabs lazyMount", () => {
     expect(screen.getByText("Content 3")).toBeInTheDocument();
   });
 
+  it("defaults lazyMount to off when the prop is omitted (eager render)", () => {
+    // Omitting the prop must fall back to eager mounting — a default of `true`
+    // would hide inactive panel children on mount.
+    render(
+      <Tabs.Root defaultValue="tab1">
+        <Tabs.List label="Test tabs">
+          <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+          <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+        </Tabs.List>
+        <Tabs.Content value="tab1">Content 1</Tabs.Content>
+        <Tabs.Content value="tab2">Content 2</Tabs.Content>
+      </Tabs.Root>,
+    );
+
+    expect(screen.getByText("Content 2")).toBeInTheDocument();
+  });
+
   it("should not render inactive panel children on initial mount when lazyMount is true", () => {
     renderTabs(true);
 

package/src/Tabs/hooks/useTabsContent.ts

@@ -14,6 +14,11 @@ export function useTabsContent({ value }: Pick<TabsContentProps, "value">) {
 
   // Track whether this panel has ever been active. Starts true for the
   // default active panel; flips once on first activation for all others.
+  // The mount effect below sets `activated` for the active panel within the
+  // same commit, so the initialiser's value is only ever observable as a
+  // pre-effect first-paint flash (not reproducible in jsdom); for inactive
+  // panels the initialiser's `false` and a mutated `undefined` are both falsy.
+  // Stryker disable next-line ArrowFunction: equivalent under the test env — see above.
   const [activated, setActivated] = useState(() => isActive);
   useEffect(() => {
     if (isActive) setActivated(true);

package/src/Tabs/hooks/useTabsRoot.ts

@@ -18,15 +18,23 @@ type TriggerMeta = {
 
 export function useTabsRoot(
   {
-    orientation = "horizontal",
-    dir = "ltr",
-    activationMode = "automatic",
+    orientation,
+    dir,
+    activationMode,
     defaultValue,
     value,
     onValueChange,
     onChange,
-    lazyMount = false,
-  }: Omit<TabsRootProps, "className">,
+    lazyMount,
+  }: // `TabsRoot` always resolves these four before calling the hook, so they
+  // are required here (a default would be dead code the tests never reach).
+  Omit<TabsRootProps, "className"> &
+    Required<
+      Pick<
+        TabsRootProps,
+        "orientation" | "dir" | "activationMode" | "lazyMount"
+      >
+    >,
   ref: Ref<TabsImperativeApi>,
 ) {
   const tabsId = useId();
@@ -47,6 +55,10 @@ export function useTabsRoot(
     (
       triggerValue: string,
       element: HTMLButtonElement | null,
+      // The default is only reached by the cleanup call `registerTrigger(value,
+      // null)`, where `element` is null and `disabled` is discarded — so its
+      // value is never observable.
+      // Stryker disable next-line BooleanLiteral
       disabled = false,
     ) => {
       registerTriggerBase(
@@ -54,6 +66,9 @@ export function useTabsRoot(
         element ? { element, disabled } : null,
       );
     },
+    // `registerTriggerBase` is a stable useCollection callback, so emptying this
+    // array yields the identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
     [registerTriggerBase],
   );
 
@@ -71,8 +86,14 @@ export function useTabsRoot(
 
   const focusTrigger = useCallback(
     (triggerValue: string) => {
+      // `triggerValue` is always sourced from the navigable set (registered
+      // triggers), so a value that reaches here has a live entry.
+      // Stryker disable next-line OptionalChaining: unreachable given that invariant.
       triggersRef.current.get(triggerValue)?.element.focus();
     },
+    // `triggersRef` is a stable RefObject, so emptying this array yields the
+    // identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
     [triggersRef],
   );
 
@@ -100,6 +121,9 @@ export function useTabsRoot(
         }
 
         if (isControlled) {
+          // Controlled mode requires `onValueChange` (discriminated-union prop
+          // type), so the optional call can never no-op in valid usage.
+          // Stryker disable next-line OptionalChaining: unreachable — controlled requires onValueChange.
           onValueChange?.(newValue);
         } else {
           setActiveValue(newValue);

package/src/Tabs/hooks/useTabsTrigger.ts

@@ -51,6 +51,9 @@ export function useTabsTrigger({
     (newValue: string, index: number) => {
       if (activeValue === newValue) return;
       if (isControlled) {
+        // Controlled mode requires `onValueChange` (discriminated-union prop
+        // type), so the optional call can never no-op in valid usage.
+        // Stryker disable next-line OptionalChaining: unreachable — controlled requires onValueChange.
         onValueChange?.(newValue);
       } else {
         setActiveValue(newValue);
@@ -87,10 +90,12 @@ export function useTabsTrigger({
     includeActivate: true,
     onNavigate: (targetValue, action) => {
       const isDisabled = disabledTriggerValues.has(targetValue);
+      // Automatic mode activates on any navigation; manual mode activates only
+      // on an explicit activation key (Enter/Space). Since the mode is always
+      // "automatic" or "manual", `automatic || isActivationKey` captures both.
       const shouldActivate =
         !isDisabled &&
-        (activationMode === "automatic" ||
-          (activationMode === "manual" && action === "activate"));
+        (activationMode === "automatic" || action === "activate");
       if (shouldActivate) {
         activateTab(targetValue, triggerValues.indexOf(targetValue));
       }

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");
+  });
 });

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/README.md

@@ -30,13 +30,13 @@ At most one item is pressed at a time. Pressing the active item again
 ```tsx
 // Uncontrolled
 <ToggleGroup.Root type="single" defaultValue="center" aria-label="Alignment">
-  …
+  ...
 </ToggleGroup.Root>
 
 // Controlled — onValueChange receives string | undefined
 const [align, setAlign] = useState<string | undefined>("center");
 <ToggleGroup.Root type="single" value={align} onValueChange={setAlign} aria-label="Alignment">
-  …
+  ...
 </ToggleGroup.Root>
 ```
 
@@ -48,13 +48,13 @@ independently.
 ```tsx
 // Uncontrolled
 <ToggleGroup.Root type="multiple" defaultValue={["bold"]} aria-label="Formatting">
-  …
+  ...
 </ToggleGroup.Root>
 
 // Controlled — onValueChange receives string[]
 const [formats, setFormats] = useState<string[]>([]);
 <ToggleGroup.Root type="multiple" value={formats} onValueChange={setFormats} aria-label="Formatting">
-  …
+  ...
 </ToggleGroup.Root>
 ```