@primitiv-ui/react 0.1.28 → 0.1.29

package/src/RadioCard/types.ts

@@ -10,63 +10,136 @@ export type RadioCardOrientation = "horizontal" | "vertical" | "both";
 /** Reading direction — swaps the horizontal arrow pair when `"rtl"`. */
 export type RadioCardReadingDirection = "ltr" | "rtl";
 
-/** Props shared by both controlled and uncontrolled `RadioCard.Root` usage.
- * Extends the native `<div>` props (minus `role`). */
-export type RadioCardRootBaseProps = Omit<ComponentProps<"div">, "role"> & {
+/**
+ * Shared base for both {@link RadioCardRootProps} variants — the native
+ * `<div>` attributes (minus the component-owned `role` and the narrowed
+ * `dir`) plus the `asChild` escape hatch, orientation, reading direction,
+ * and a typed `ref`.
+ */
+export type RadioCardRootBaseProps = Omit<
+  ComponentProps<"div">,
+  "role" | "dir" | "defaultValue"
+> & {
+  /** The group's cards — typically {@link RadioCardItemProps | `RadioCard.Item`}
+   * elements, each optionally wrapping a {@link RadioCardIndicatorProps | `RadioCard.Indicator`}. */
   children?: ReactNode;
-  /** Ref to the rendered root element. */
+  /** Forwarded to the underlying `HTMLDivElement`. */
   ref?: Ref<HTMLDivElement>;
-  /** Render the child element instead of the default `<div>`. */
+  /**
+   * When `true`, Root delegates rendering to a single consumer-supplied
+   * element via the {@link Slot} pattern instead of the default `<div>`;
+   * `role="radiogroup"`, `aria-orientation`, `dir`, and remaining props
+   * are merged onto it.
+   * @default false
+   */
   asChild?: boolean;
-  /** Which arrow keys navigate the group. */
+  /**
+   * Which arrow keys move focus and selection through the group.
+   * `"both"` enables all four arrows; `"horizontal"` only Arrow
+   * Left/Right; `"vertical"` only Arrow Up/Down. When not `"both"`, the
+   * value is also reflected as `aria-orientation` on the root.
+   * @default "both"
+   */
   orientation?: RadioCardOrientation;
-  /** Reading direction for horizontal arrow navigation. */
+  /**
+   * Reading direction. In `"rtl"` the horizontal arrow pair is swapped so
+   * Arrow Left moves forward. When omitted, it is inherited from the
+   * nearest {@link DirectionProvider}, falling back to `"ltr"`.
+   */
   dir?: RadioCardReadingDirection;
 };
 
-/** Uncontrolled `RadioCard.Root` props: the component owns the selection,
- * seeded by an optional `defaultValue`. */
+/**
+ * Uncontrolled variant of {@link RadioCardRootProps}: the component owns
+ * the selected value. Pass `defaultValue` (or omit it); `onValueChange` is
+ * optional and `value` is forbidden.
+ */
 export type RadioCardRootUncontrolledProps = RadioCardRootBaseProps & {
-  /** Value selected on first render. */
+  /** Value of the card selected on first render. Omit for nothing selected
+   * on mount. */
   defaultValue?: string;
+  /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
   value?: never;
-  /** Called with the value when the selection changes. */
+  /** Called with the new value whenever the selection changes. Optional in
+   * uncontrolled mode. */
   onValueChange?: (value: string) => void;
 };
 
-/** Controlled `RadioCard.Root` props: the caller owns the selection via
- * `value` and is notified through the required `onValueChange`. */
+/**
+ * Controlled variant of {@link RadioCardRootProps}: the parent owns the
+ * selected value. Pass `value` and `onValueChange` together; `defaultValue`
+ * is forbidden.
+ */
 export type RadioCardRootControlledProps = RadioCardRootBaseProps & {
+  /** Forbidden in controlled mode — use `value` instead. */
   defaultValue?: never;
-  /** Value of the currently selected card. */
+  /** The currently selected value. Must be kept in sync by the parent via
+   * `onValueChange`. */
   value: string;
-  /** Called with the value when the user selects a card. */
+  /** Called with the new value whenever the user selects a card. Required
+   * in controlled mode. */
   onValueChange: (value: string) => void;
 };
 
-/** Props for `RadioCard.Root` — resolves to either the controlled or
- * uncontrolled prop shape. */
+/**
+ * Props for {@link RadioCard.Root}. A discriminated union of
+ * {@link RadioCardRootUncontrolledProps} and
+ * {@link RadioCardRootControlledProps}, so TypeScript accepts exactly one
+ * state mode.
+ */
 export type RadioCardRootProps =
   | RadioCardRootUncontrolledProps
   | RadioCardRootControlledProps;
 
-/** Props for `RadioCard.Item` — a selectable card rendered as a
- * `role="radio"` button, identified by its required `value`. */
+/**
+ * Props for {@link RadioCardItem | `RadioCard.Item`} — a selectable card
+ * rendered as a `role="radio"` button. `value` identifies the option; all
+ * native `<button>` attributes (minus the component-owned `type`, `role`,
+ * `aria-checked`, and `value`) plus the `asChild` escape hatch and a typed
+ * `ref` are passed through.
+ */
 export type RadioCardItemProps = Omit<
   ComponentProps<"button">,
   "type" | "role" | "aria-checked" | "value"
 > & {
+  /** Uniquely identifies this card within the group and is reported to
+   * `onValueChange` / matched against Root's `value` when selected. Required. */
   value: string;
+  /** The card's content — the whole surface is the interactive control,
+   * and typically includes a {@link RadioCardIndicatorProps | `RadioCard.Indicator`}. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLButtonElement`. */
   ref?: Ref<HTMLButtonElement>;
+  /**
+   * When `true`, renders the single child element via the {@link Slot}
+   * pattern instead of the default `<button>`; ARIA, `data-state`,
+   * `tabIndex`, `onClick`, `onKeyDown`, `disabled`, and `ref` are merged
+   * onto it. A non-focusable child must be made focusable by the consumer.
+   * @default false
+   */
   asChild?: boolean;
 };
 
-/** Props for `RadioCard.Indicator` — the visual marker rendered inside the
- * selected item. By default it renders only when its item is checked; set
- * `forceMount` to keep it mounted for exit transitions. */
+/**
+ * Props for {@link RadioCardIndicator | `RadioCard.Indicator`} — the visual
+ * marker rendered inside the selected card. All native `<span>` attributes
+ * plus `forceMount` and the `asChild` escape hatch.
+ */
 export type RadioCardIndicatorProps = ComponentProps<"span"> & {
+  /** The visual mark shown while the parent Item is selected. */
   children?: ReactNode;
+  /**
+   * When `true`, keeps the indicator mounted while unchecked so a CSS exit
+   * animation can play against `data-state="unchecked"`. Consumers who set
+   * it own the exit lifecycle.
+   * @default false
+   */
   forceMount?: boolean;
+  /**
+   * When `true`, renders the single child element via the {@link Slot}
+   * pattern instead of the default `<span>`; `aria-hidden` and `data-state`
+   * are merged onto it.
+   * @default false
+   */
   asChild?: boolean;
 };

package/src/RadioGroup/RadioGroup.tsx

@@ -50,6 +50,8 @@ import {
  * element (e.g. `<menu role="menu">` for dropdown composition) with
  * the RadioGroup's props merged in. The native `<div>` is dropped.
  *
+ * @extends HTMLDivElement
+ *
  * @example Uncontrolled
  * ```tsx
  * <RadioGroup.Root defaultValue="comfortable" aria-label="Density">
@@ -131,6 +133,11 @@ export function RadioGroupRoot({
 }
 
 /** @internal */
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "RadioGroup" at load, so the value is never observable.
+// The assignment stays because it declares `displayName` on
+// `typeof RadioGroupRoot`, which TRadioGroupCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 RadioGroupRoot.displayName = "RadioGroupRoot";
 
 /**
@@ -163,6 +170,8 @@ RadioGroupRoot.displayName = "RadioGroupRoot";
  * consumers who render a non-focusable element are responsible for
  * making it focusable.
  *
+ * @extends HTMLButtonElement
+ *
  * @throws if rendered outside a `RadioGroup.Root`.
  */
 export function RadioGroupItem({
@@ -263,6 +272,8 @@ RadioGroupItem.displayName = "RadioGroupItem";
  * `data-state="unchecked"`. Consumers who use `forceMount` own the
  * exit lifecycle themselves.
  *
+ * @extends HTMLSpanElement
+ *
  * @example Default span wrapper
  * ```tsx
  * <RadioGroup.Item value="red">

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

@@ -69,4 +69,12 @@ describe("RadioGroup basic rendering", () => {
       "unchecked",
     );
   });
+
+  it("sets a displayName on the compound, Item, and Indicator", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "RadioGroup".
+    expect(RadioGroup.displayName).toBe("RadioGroup");
+    expect(RadioGroup.Item.displayName).toBe("RadioGroupItem");
+    expect(RadioGroup.Indicator.displayName).toBe("RadioGroupIndicator");
+  });
 });

package/src/RadioGroup/__tests__/RadioGroup.disabled.test.tsx

@@ -54,6 +54,33 @@ describe("RadioGroup disabled", () => {
     expect(red).toHaveAttribute("aria-checked", "true");
   });
 
+  it("re-registers an item's disabled flag when it changes after mount", async () => {
+    // Arrange — all enabled at mount; green becomes disabled afterwards.
+    const user = userEvent.setup();
+    function Fixture({ greenDisabled }: { greenDisabled: boolean }) {
+      return (
+        <RadioGroup.Root aria-label="Colour" defaultValue="red">
+          <RadioGroup.Item value="red">Red</RadioGroup.Item>
+          <RadioGroup.Item value="green" disabled={greenDisabled}>
+            Green
+          </RadioGroup.Item>
+          <RadioGroup.Item value="blue">Blue</RadioGroup.Item>
+        </RadioGroup.Root>
+      );
+    }
+    const { rerender } = render(<Fixture greenDisabled={false} />);
+
+    // Act — disable green after mount, then arrow forwards from red.
+    rerender(<Fixture greenDisabled />);
+    screen.getByRole("radio", { name: "Red" }).focus();
+    await user.keyboard("{ArrowDown}");
+
+    // Assert — the registrar effect re-ran, so green is skipped and focus lands
+    // on blue. A stale registration would keep green navigable and strand focus
+    // (a disabled button cannot receive it).
+    expect(screen.getByRole("radio", { name: "Blue" })).toHaveFocus();
+  });
+
   it("skips disabled items when computing the home-base tab stop", () => {
     // Arrange & Act
     render(

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

@@ -42,4 +42,33 @@ describe("RadioGroup.Item ref forwarding", () => {
     const button = screen.getByRole("radio", { name: "Red" });
     expect(objectRef.current).toBe(button);
   });
+
+  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 secondReceived: (HTMLButtonElement | null)[] = [];
+    const firstRef = () => {};
+    const secondRef = (node: HTMLButtonElement | null) => {
+      secondReceived.push(node);
+    };
+
+    // Act — mount with the first ref, then re-render with a different one.
+    const { rerender } = render(
+      <RadioGroup.Root aria-label="Colour">
+        <RadioGroup.Item value="red" ref={firstRef}>
+          Red
+        </RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+    rerender(
+      <RadioGroup.Root aria-label="Colour">
+        <RadioGroup.Item value="red" ref={secondRef}>
+          Red
+        </RadioGroup.Item>
+      </RadioGroup.Root>,
+    );
+
+    // Assert — the replacement ref received the button.
+    expect(secondReceived).toContain(screen.getByRole("radio", { name: "Red" }));
+  });
 });

package/src/RadioGroup/__tests__/RadioGroup.roving-tabindex.test.tsx

@@ -75,6 +75,37 @@ describe("RadioGroup roving tabindex", () => {
     expect(green).toHaveAttribute("tabindex", "0");
   });
 
+  it("unregisters an unmounted item so the home-base tab stop moves", () => {
+    // Arrange — nothing selected, so the first item is the home base.
+    function Fixture({ items }: { items: string[] }) {
+      return (
+        <RadioGroup.Root aria-label="Colour">
+          {items.map((v) => (
+            <RadioGroup.Item key={v} value={v}>
+              {v}
+            </RadioGroup.Item>
+          ))}
+        </RadioGroup.Root>
+      );
+    }
+    const { rerender } = render(<Fixture items={["red", "green"]} />);
+    expect(screen.getByRole("radio", { name: "red" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+
+    // Act — remove "red"; its effect cleanup must unregister it.
+    rerender(<Fixture items={["green"]} />);
+
+    // Assert — with "red" gone from the registry, "green" is the home base. A
+    // no-op cleanup would leave "red" registered ahead of it, stranding the tab
+    // stop and leaving "green" at tabindex -1.
+    expect(screen.getByRole("radio", { name: "green" })).toHaveAttribute(
+      "tabindex",
+      "0",
+    );
+  });
+
   it("tabs into the single home-base item and not the others", async () => {
     // Arrange
     const user = userEvent.setup();

package/src/RadioGroup/hooks/useRadioGroupRoot.ts

@@ -52,6 +52,9 @@ export function useRadioGroupRoot({
     ) => {
       registerItemBase(itemValue, element ? { element, disabled } : null);
     },
+    // `registerItemBase` 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.
     [registerItemBase],
   );
 
@@ -71,8 +74,16 @@ export function useRadioGroupRoot({
 
   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 in the same call — so a value that
+      // appears here is guaranteed to already 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/RadioGroup/types.ts

@@ -12,14 +12,40 @@ export type RadioGroupReadingDirection = "ltr" | "rtl";
 
 /**
  * Shared base for both {@link RadioGroupRootProps} variants — the native
- * `<div>` attributes (minus `role`) plus the `asChild` escape hatch,
- * orientation, reading direction, and a typed `ref`.
+ * `<div>` attributes (minus the component-owned `role` and the narrowed
+ * `dir`) plus the `asChild` escape hatch, orientation, reading direction,
+ * and a typed `ref`.
  */
-export type RadioGroupRootBaseProps = Omit<ComponentProps<"div">, "role"> & {
+export type RadioGroupRootBaseProps = Omit<
+  ComponentProps<"div">,
+  "role" | "dir" | "defaultValue"
+> & {
+  /** The group's radios — typically {@link RadioGroupItemProps | `RadioGroup.Item`}
+   * elements, each optionally wrapping a {@link RadioGroupIndicatorProps | `RadioGroup.Indicator`}. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLDivElement`. */
   ref?: Ref<HTMLDivElement>;
+  /**
+   * When `true`, Root delegates rendering to a single consumer-supplied
+   * element (e.g. `<menu role="menu">` for dropdown composition) via the
+   * {@link Slot} pattern instead of the default `<div>`; `role="radiogroup"`,
+   * `aria-orientation`, `dir`, and remaining props are merged onto it.
+   * @default false
+   */
   asChild?: boolean;
+  /**
+   * Which arrow keys move focus and selection through the group.
+   * `"both"` enables all four arrows; `"horizontal"` only Arrow
+   * Left/Right; `"vertical"` only Arrow Up/Down. When not `"both"`, the
+   * value is also reflected as `aria-orientation` on the root.
+   * @default "both"
+   */
   orientation?: RadioGroupOrientation;
+  /**
+   * Reading direction. In `"rtl"` the horizontal arrow pair is swapped so
+   * Arrow Left moves forward. When omitted, it is inherited from the
+   * nearest {@link DirectionProvider}, falling back to `"ltr"`.
+   */
   dir?: RadioGroupReadingDirection;
 };
 
@@ -29,8 +55,13 @@ export type RadioGroupRootBaseProps = Omit<ComponentProps<"div">, "role"> & {
  * optional and `value` is forbidden.
  */
 export type RadioGroupRootUncontrolledProps = RadioGroupRootBaseProps & {
+  /** Value of the radio selected on first render. Omit for nothing
+   * selected on mount. */
   defaultValue?: string;
+  /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
   value?: never;
+  /** Called with the new value whenever the selection changes. Optional
+   * in uncontrolled mode. */
   onValueChange?: (value: string) => void;
 };
 
@@ -40,8 +71,13 @@ export type RadioGroupRootUncontrolledProps = RadioGroupRootBaseProps & {
  * is forbidden.
  */
 export type RadioGroupRootControlledProps = RadioGroupRootBaseProps & {
+  /** Forbidden in controlled mode — use `value` instead. */
   defaultValue?: never;
+  /** The currently selected value. Must be kept in sync by the parent
+   * via `onValueChange`. */
   value: string;
+  /** Called with the new value whenever the selection changes. Required
+   * in controlled mode. */
   onValueChange: (value: string) => void;
 };
 
@@ -56,27 +92,55 @@ export type RadioGroupRootProps =
   | RadioGroupRootControlledProps;
 
 /**
- * Props for {@link RadioGroup.Item} — the radio button. `value` identifies
- * the option; all native `<button>` attributes (minus the component-owned
- * ones) plus the `asChild` escape hatch and a typed `ref` are passed through.
+ * Props for {@link RadioGroupItem | `RadioGroup.Item`} — the radio button.
+ * `value` identifies the option; all native `<button>` attributes (minus
+ * the component-owned `type`, `role`, `aria-checked`, and `value`) plus the
+ * `asChild` escape hatch and a typed `ref` are passed through.
  */
 export type RadioGroupItemProps = Omit<
   ComponentProps<"button">,
   "type" | "role" | "aria-checked" | "value"
 > & {
+  /** Uniquely identifies this radio within the group and is reported to
+   * `onValueChange` / matched against Root's `value` when selected. Required. */
   value: string;
+  /** The radio's visible content — its label, and typically a leading
+   * {@link RadioGroupIndicatorProps | `RadioGroup.Indicator`}. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLButtonElement`. */
   ref?: Ref<HTMLButtonElement>;
+  /**
+   * When `true`, renders the single child element (e.g.
+   * `<li role="menuitemradio">`) via the {@link Slot} pattern instead of
+   * the default `<button>`; ARIA, `data-state`, `tabIndex`, `onClick`,
+   * `onKeyDown`, `disabled`, and `ref` are merged onto it. A non-focusable
+   * child must be made focusable by the consumer.
+   * @default false
+   */
   asChild?: boolean;
 };
 
 /**
- * Props for {@link RadioGroup.Indicator} — all `<span>` attributes plus
- * `forceMount` (keep mounted while unselected for exit animations) and the
- * `asChild` escape hatch.
+ * Props for {@link RadioGroupIndicator | `RadioGroup.Indicator`} — all
+ * native `<span>` attributes plus `forceMount` and the `asChild` escape
+ * hatch.
  */
 export type RadioGroupIndicatorProps = ComponentProps<"span"> & {
+  /** The visual mark (e.g. a filled dot) shown while the parent Item is
+   * selected. */
   children?: ReactNode;
+  /**
+   * When `true`, keeps the indicator mounted while unchecked so a CSS exit
+   * animation can play against `data-state="unchecked"`. Consumers who set
+   * it own the exit lifecycle.
+   * @default false
+   */
   forceMount?: boolean;
+  /**
+   * When `true`, renders the single child element (typically an `<svg>`
+   * dot) via the {@link Slot} pattern instead of the default `<span>`;
+   * `aria-hidden` and `data-state` are merged onto it.
+   * @default false
+   */
   asChild?: boolean;
 };

package/src/SegmentedControl/README.md

@@ -0,0 +1,154 @@
+# SegmentedControl
+
+A headless, accessible compound component for picking **one** option from a
+small linear set — the segmented-control pattern (iOS-style pill strip,
+"consumption mode" switch, view toggles). It implements the
+[WAI-ARIA Radio Group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/),
+so exactly one segment is always selected and the selection can never be
+cleared to nothing.
+
+SegmentedControl renders native `<button role="radio">` elements wrapped in a
+`<div role="radiogroup">` so it gets keyboard activation (`Space` / `Enter`),
+focus ring, and disabled semantics for free from the browser. The React layer
+adds single-selection state, roving tabindex, arrow-key navigation, a
+whole-control `disabled`, and the `asChild` composition every primitive in
+this package supports.
+
+```tsx
+import { SegmentedControl } from "@primitiv-ui/react";
+
+<SegmentedControl.Root defaultValue="headless" aria-label="Consumption mode">
+  <SegmentedControl.Item value="headless">Headless</SegmentedControl.Item>
+  <SegmentedControl.Item value="styled">Styled</SegmentedControl.Item>
+  <SegmentedControl.Item value="figma">Figma</SegmentedControl.Item>
+</SegmentedControl.Root>;
+```
+
+## SegmentedControl vs ToggleGroup
+
+Reach for `SegmentedControl` when the choice is a **value** — one option is
+always active, like a radio group (view mode, density, a tab-like switch).
+Reach for [`ToggleGroup`](../ToggleGroup/README.md) when the buttons are
+**commands or toggles** that can each be on or off (text formatting, a
+toolbar), including single-select-with-clear. The two look similar but carry
+different semantics: `SegmentedControl` is `role="radiogroup"` /
+`role="radio"` + `aria-checked`; `ToggleGroup` is `role="group"` +
+`aria-pressed` and allows deselecting to nothing.
+
+## Sub-components
+
+| Export                     | Element    | Notes                                                                                          |
+| -------------------------- | ---------- | ---------------------------------------------------------------------------------------------- |
+| `SegmentedControl.Root`    | `<div>`    | `role="radiogroup"`, `aria-orientation`, `data-orientation`, `data-disabled`. State owner. `asChild` |
+| `SegmentedControl.Item`    | `<button>` | `role="radio"`, `aria-checked`, `data-state`, `data-disabled`, participates in roving tabindex. `asChild` |
+
+## State modes
+
+- **Uncontrolled** — pass `defaultValue` (or omit for no initial selection).
+- **Controlled** — pass `value` **and** `onValueChange` together.
+
+The two shapes are statically discriminated at the type level; TypeScript
+rejects mixing them.
+
+```tsx
+// Uncontrolled
+<SegmentedControl.Root defaultValue="headless" aria-label="Mode">
+  …
+</SegmentedControl.Root>;
+
+// Controlled
+const [value, setValue] = useState("headless");
+<SegmentedControl.Root value={value} onValueChange={setValue} aria-label="Mode">
+  …
+</SegmentedControl.Root>;
+```
+
+## Keyboard interaction
+
+| Key                        | Behaviour                                                                        |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| `Tab`                      | Moves focus to the control's single tab stop (selected segment, or first if none). |
+| `Space` / `Enter`          | Selects the focused segment (native `<button>` activation).                      |
+| `ArrowRight` / `ArrowLeft` | (horizontal) Moves focus **and** selection to the next / previous segment, wrapping. |
+| `ArrowDown` / `ArrowUp`    | (vertical) Moves focus **and** selection to the next / previous segment, wrapping. |
+
+The control has exactly one tab stop — the selected segment, or the first
+non-disabled segment if nothing is selected. `Tab` takes the user into and out
+of the control in one keystroke; arrow keys navigate inside it.
+
+## Orientation
+
+`orientation` defaults to `"horizontal"` (the usual segmented-control layout),
+which binds `ArrowLeft` / `ArrowRight`. Pass `orientation="vertical"` to bind
+`ArrowUp` / `ArrowDown` instead. Either way the axis is reflected to assistive
+technology via `aria-orientation`, and to CSS via `data-orientation`, on the
+`radiogroup` element.
+
+## Reading direction
+
+Pass `dir` (`"ltr"` / `"rtl"`) to swap the horizontal arrow pair, so
+`ArrowLeft` moves forward and `ArrowRight` moves backward in RTL. The vertical
+pair is never swapped. When `dir` is omitted, it is inherited from the nearest
+[`DirectionProvider`](../DirectionProvider/README.md), falling back to `"ltr"`.
+An explicit `dir` prop always wins over the inherited value.
+
+## Disabled
+
+Disable a **single segment** by passing `disabled` to a
+`SegmentedControl.Item`. It forwards the native `disabled` attribute (removing
+it from the focus ring and suppressing clicks), sets `data-disabled=""`, and
+excludes the segment from arrow-key navigation and the roving-tabindex home
+base.
+
+Disable the **whole control** by passing `disabled` to `SegmentedControl.Root`.
+Every segment becomes disabled, `data-disabled=""` is set on the root, and no
+segment is navigable or takes a tab stop. The current selection is still
+reflected (`aria-checked` / `data-state`) so the control reads correctly while
+inert.
+
+```tsx
+<SegmentedControl.Root aria-label="Plan" disabled defaultValue="pro">
+  <SegmentedControl.Item value="free">Free</SegmentedControl.Item>
+  <SegmentedControl.Item value="pro">Pro</SegmentedControl.Item>
+</SegmentedControl.Root>
+```
+
+## `asChild` composition
+
+`SegmentedControl.Root` and `SegmentedControl.Item` each accept an `asChild`
+boolean. When set, the component delegates rendering to its single child
+element and merges its own ARIA attributes, `data-state`, `data-disabled`,
+composed event handlers, and ref onto the child (the asChild contract: the
+child's handler runs first, the library's runs second unless the child calls
+`preventDefault`).
+
+```tsx
+<SegmentedControl.Root asChild aria-label="View">
+  <nav>
+    <SegmentedControl.Item value="grid" asChild>
+      <a href="#grid">Grid</a>
+    </SegmentedControl.Item>
+    <SegmentedControl.Item value="list" asChild>
+      <a href="#list">List</a>
+    </SegmentedControl.Item>
+  </nav>
+</SegmentedControl.Root>
+```
+
+## Styling hooks
+
+`data-state="checked" | "unchecked"` is set on each `SegmentedControl.Item`,
+and `data-orientation` / `data-disabled` on the root, letting any CSS system
+style the selected segment and the disabled state from plain attribute
+selectors:
+
+```css
+button[role="radio"][data-state="checked"] {
+  background: var(--primitiv-action-primary-default);
+  color: var(--primitiv-action-primary-foreground-default);
+}
+[role="radiogroup"][data-disabled] {
+  opacity: 0.5;
+  pointer-events: none;
+}
+```