@primitiv-ui/react 0.1.28 → 0.1.30

package/src/ContextMenu/types.ts

@@ -8,6 +8,8 @@ import { Direction } from "../DirectionProvider/index.ts";
  * plus the reading-direction control.
  */
 export type ContextMenuRootBaseProps = {
+  /** The {@link ContextMenu.Trigger} and {@link ContextMenu.Content} pair
+   * (Root renders no wrapping element of its own). */
   children?: ReactNode;
   /**
    * Reading direction for the menu. Affects which arrow key opens / closes
@@ -24,8 +26,14 @@ export type ContextMenuRootBaseProps = {
  * optional and `open` is forbidden.
  */
 export type ContextMenuRootUncontrolledProps = ContextMenuRootBaseProps & {
+  /** Whether the menu is open on first render.
+   * @default false */
   defaultOpen?: boolean;
+  /** Forbidden in uncontrolled mode — use `defaultOpen` instead. */
   open?: never;
+  /** Observes open-state transitions. Fires only on user-driven changes
+   * (right-click, Escape, selection, outside click), never on external
+   * flips. Optional in uncontrolled mode. */
   onOpenChange?: (open: boolean) => void;
 };
 
@@ -35,8 +43,13 @@ export type ContextMenuRootUncontrolledProps = ContextMenuRootBaseProps & {
  * forbidden.
  */
 export type ContextMenuRootControlledProps = ContextMenuRootBaseProps & {
+  /** Forbidden in controlled mode — use `open` instead. */
   defaultOpen?: never;
+  /** Whether the menu is open. Must be kept in sync by the parent via
+   * `onOpenChange`. */
   open: boolean;
+  /** Called with the requested open state on each user-driven transition.
+   * Required in controlled mode. */
   onOpenChange: (open: boolean) => void;
 };
 
@@ -56,9 +69,18 @@ export type ContextMenuRootProps =
  * onto a custom element and `disabled` to suppress the gesture.
  */
 export type ContextMenuTriggerProps = ComponentProps<"span"> & {
+  /** The content the right-click gesture is bound to. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLSpanElement` (or the `asChild` host). */
   ref?: Ref<HTMLSpanElement>;
+  /** Render the child element instead of the default `<span>`, merging the
+   * trigger's `contextmenu` handler and data-attributes onto it via the
+   * {@link Slot} pattern. The child must accept a `ref`.
+   * @default false */
   asChild?: boolean;
+  /** When `true`, the trigger ignores the `contextmenu` gesture entirely,
+   * letting the native browser menu through. Exposed as `data-disabled=""`.
+   * @default false */
   disabled?: boolean;
 };
 
@@ -69,10 +91,17 @@ export type ContextMenuTriggerProps = ComponentProps<"span"> & {
  */
 export type ContextMenuContentProps = Omit<
   ComponentProps<"menu">,
-  "role" | "popover" | "id"
+  "role" | "popover" | "id" | "ref"
 > & {
+  /** The menu items — {@link ContextMenuItem}, {@link ContextMenuGroup},
+   * {@link ContextMenuSub}, and friends. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLMenuElement` (or the `asChild` host). */
   ref?: Ref<HTMLMenuElement>;
+  /** Render the child element instead of the default `<menu>`, merging the
+   * managed `role` / `popover` / positioning props and the keyboard handler
+   * onto it via the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
 };
 
@@ -85,9 +114,19 @@ export type ContextMenuItemProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "onSelect"
 > & {
+  /** The item's visible content. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement` (or the `asChild` host). */
   ref?: Ref<HTMLLIElement>;
+  /** Render the child element instead of the default `<li role="menuitem">`,
+   * merging the item's props onto it via the {@link Slot} pattern (e.g. to
+   * render a menu item as an `<a>`).
+   * @default false */
   asChild?: boolean;
+  /** Removes the item from activation and marks it `aria-disabled`; it
+   * still renders for assistive technology but no-ops on click / Enter, and
+   * arrow navigation and typeahead skip it.
+   * @default false */
   disabled?: boolean;
   /**
    * Fires when the item is activated (click, Enter, or Space). Called
@@ -103,8 +142,14 @@ export type ContextMenuItemProps = Omit<
  * `asChild` merges the props onto a custom element.
  */
 export type ContextMenuSeparatorProps = Omit<ComponentProps<"li">, "role"> & {
+  /** Usually empty — a separator renders no content by default. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement` (or the `asChild` host). */
   ref?: Ref<HTMLLIElement>;
+  /** Render the child element instead of the default
+   * `<li role="separator">`, merging the managed `role` onto it via the
+   * {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
 };
 
@@ -114,8 +159,14 @@ export type ContextMenuSeparatorProps = Omit<ComponentProps<"li">, "role"> & {
  * `role` is omitted; `asChild` merges the props onto a custom element.
  */
 export type ContextMenuGroupProps = Omit<ComponentProps<"li">, "role"> & {
+  /** The grouped items, optionally led by a {@link ContextMenu.Label}. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement` (or the `asChild` host). */
   ref?: Ref<HTMLLIElement>;
+  /** Render the child element instead of the default `<li role="group">`
+   * (which otherwise wraps an inner `<ul role="none">`), merging the group's
+   * props onto it via the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
 };
 
@@ -125,8 +176,13 @@ export type ContextMenuGroupProps = Omit<ComponentProps<"li">, "role"> & {
  * onto a custom element.
  */
 export type ContextMenuLabelProps = ComponentProps<"li"> & {
+  /** The label text. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement` (or the `asChild` host). */
   ref?: Ref<HTMLLIElement>;
+  /** Render the child element instead of the default `<li>`, merging the
+   * (auto-wired) `id` onto it via the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
 };
 
@@ -140,9 +196,19 @@ export type ContextMenuCheckboxItemBaseProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "aria-checked" | "defaultChecked" | "onSelect"
 > & {
+  /** The item's visible content, typically including a
+   * {@link ContextMenuItemIndicator}. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement` (or the `asChild` host). */
   ref?: Ref<HTMLLIElement>;
+  /** Render the child element instead of the default
+   * `<li role="menuitemcheckbox">`, merging the item's props onto it via
+   * the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
+  /** Removes the item from activation and marks it `aria-disabled`; it
+   * still renders for assistive technology but no-ops on click / Enter.
+   * @default false */
   disabled?: boolean;
   /**
    * Fires when activation completes and the auto-close fires. Call
@@ -159,8 +225,14 @@ export type ContextMenuCheckboxItemBaseProps = Omit<
  */
 export type ContextMenuCheckboxItemUncontrolledProps =
   ContextMenuCheckboxItemBaseProps & {
+    /** Checked state on first render. Accepts the tri-state
+     * {@link CheckedState} (`true` / `false` / `"indeterminate"`).
+     * @default false */
     defaultChecked?: CheckedState;
+    /** Forbidden in uncontrolled mode — use `defaultChecked` instead. */
     checked?: never;
+    /** Called with the resolved boolean checked state on each toggle.
+     * Optional in uncontrolled mode. */
     onCheckedChange?: (checked: boolean) => void;
   };
 
@@ -171,8 +243,14 @@ export type ContextMenuCheckboxItemUncontrolledProps =
  */
 export type ContextMenuCheckboxItemControlledProps =
   ContextMenuCheckboxItemBaseProps & {
+    /** Forbidden in controlled mode — use `checked` instead. */
     defaultChecked?: never;
+    /** The current checked state. Accepts the tri-state {@link CheckedState}
+     * (`true` / `false` / `"indeterminate"`, the last rendered as
+     * `aria-checked="mixed"`). Must be kept in sync via `onCheckedChange`. */
     checked: CheckedState;
+    /** Called with the resolved boolean checked state on each toggle.
+     * Required in controlled mode. */
     onCheckedChange: (checked: boolean) => void;
   };
 
@@ -193,12 +271,19 @@ export type ContextMenuCheckboxItemProps =
  * onto a custom element.
  */
 export type ContextMenuItemIndicatorProps = ComponentProps<"span"> & {
+  /** The mark to show — usually a checkmark or radio-dot icon. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLSpanElement` (or the `asChild` host). */
   ref?: Ref<HTMLSpanElement>;
+  /** Render the child element instead of the default `<span>`, merging the
+   * `data-state` attribute onto it via the {@link Slot} pattern (e.g. to
+   * compose onto an SVG icon).
+   * @default false */
   asChild?: boolean;
   /**
    * Render the indicator even when its parent item is unchecked. The
    * `data-state` attribute still reflects the live state.
+   * @default false
    */
   forceMount?: boolean;
 };
@@ -206,14 +291,22 @@ export type ContextMenuItemIndicatorProps = ComponentProps<"span"> & {
 /**
  * Shared base for both {@link ContextMenuRadioGroupProps} variants — the
  * `<li>` host props plus `children`, `ref`, and `asChild`. The managed
- * `role` host attribute is omitted.
+ * `role` host attribute is omitted, along with the native `<li>` `value`
+ * and `defaultValue` attributes: the variants below re-declare both as the
+ * radio-group's selection state (`string`), narrowing the native
+ * `string | number | readonly string[]`. They must be `Omit`-ted here or
+ * the docs-data extractor silently drops the narrowed declaration (the
+ * §1.16 narrow-without-omit rule).
  */
 export type ContextMenuRadioGroupBaseProps = Omit<
   ComponentProps<"li">,
-  "role"
+  "role" | "value" | "defaultValue"
 > & {
   children?: ReactNode;
   ref?: Ref<HTMLLIElement>;
+  /** Render the child element instead of the default `<li role="group">`,
+   * merging the group's props onto it via the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
 };
 
@@ -225,8 +318,12 @@ export type ContextMenuRadioGroupBaseProps = Omit<
  */
 export type ContextMenuRadioGroupUncontrolledProps =
   ContextMenuRadioGroupBaseProps & {
+    /** Value of the {@link ContextMenuRadioItem} selected on first render. */
     defaultValue?: string;
+    /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
     value?: never;
+    /** Called with the newly-selected item's `value` on each change.
+     * Optional in uncontrolled mode. */
     onValueChange?: (value: string) => void;
   };
 
@@ -237,8 +334,13 @@ export type ContextMenuRadioGroupUncontrolledProps =
  */
 export type ContextMenuRadioGroupControlledProps =
   ContextMenuRadioGroupBaseProps & {
+    /** Forbidden in controlled mode — use `value` instead. */
     defaultValue?: never;
+    /** The `value` of the currently-selected {@link ContextMenuRadioItem}.
+     * Must be kept in sync by the parent via `onValueChange`. */
     value: string;
+    /** Called with the newly-selected item's `value` on each change.
+     * Required in controlled mode. */
     onValueChange: (value: string) => void;
   };
 
@@ -256,17 +358,32 @@ export type ContextMenuRadioGroupProps =
  * Props for {@link ContextMenu.RadioItem} — a mutually-exclusive choice
  * within a {@link ContextMenu.RadioGroup}, identified by its required
  * `value`. The managed `role`, `tabIndex`, `aria-checked`, and `onSelect`
- * host attributes are omitted.
+ * host attributes are omitted, as is the native `<li>` `value` attribute:
+ * the required `value: string` below narrows it (from the native
+ * `string | number | readonly string[]`), so it must be `Omit`-ted or the
+ * docs-data extractor silently drops it (the §1.16 narrow-without-omit
+ * rule).
  */
 export type ContextMenuRadioItemProps = Omit<
   ComponentProps<"li">,
-  "role" | "tabIndex" | "aria-checked" | "onSelect"
+  "role" | "tabIndex" | "aria-checked" | "onSelect" | "value"
 > & {
   children?: ReactNode;
   ref?: Ref<HTMLLIElement>;
+  /** Render the child element instead of the default `<li role="menuitemradio">`,
+   * merging the item's props onto it via the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
+  /** Removes the item from activation and marks it `aria-disabled`; it
+   * still renders for assistive technology but no-ops on click / Enter.
+   * @default false */
   disabled?: boolean;
+  /** Identifies this choice within the enclosing
+   * {@link ContextMenuRadioGroup}. When it matches the group's active
+   * value, the item is checked. */
   value: string;
+  /** Fires when the item is activated (click, Enter, or Space). Call
+   * `event.preventDefault()` to skip the auto-close after selection. */
   onSelect?: (event: Event) => void;
 };
 
@@ -275,6 +392,8 @@ export type ContextMenuRadioItemProps = Omit<
  * `children` of the submenu.
  */
 export type ContextMenuSubBaseProps = {
+  /** The {@link ContextMenu.SubTrigger} and {@link ContextMenu.SubContent}
+   * pair (Sub renders no wrapping element of its own). */
   children?: ReactNode;
 };
 
@@ -284,8 +403,12 @@ export type ContextMenuSubBaseProps = {
  * is optional and the controlled `open` prop is forbidden.
  */
 export type ContextMenuSubUncontrolledProps = ContextMenuSubBaseProps & {
+  /** Whether the submenu is open on first render.
+   * @default false */
   defaultOpen?: boolean;
+  /** Forbidden in uncontrolled mode — use `defaultOpen` instead. */
   open?: never;
+  /** Observes submenu open-state transitions. Optional in uncontrolled mode. */
   onOpenChange?: (open: boolean) => void;
 };
 
@@ -295,8 +418,12 @@ export type ContextMenuSubUncontrolledProps = ContextMenuSubBaseProps & {
  * `defaultOpen` is forbidden.
  */
 export type ContextMenuSubControlledProps = ContextMenuSubBaseProps & {
+  /** Forbidden in controlled mode — use `open` instead. */
   defaultOpen?: never;
+  /** Whether the submenu is open. Must be kept in sync via `onOpenChange`. */
   open: boolean;
+  /** Called with the requested open state on each transition.
+   * Required in controlled mode. */
   onOpenChange: (open: boolean) => void;
 };
 
@@ -320,9 +447,18 @@ export type ContextMenuSubTriggerProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "aria-haspopup" | "aria-expanded" | "aria-controls"
 > & {
+  /** The trigger's visible content (typically the submenu's name). */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement` (or the `asChild` host). */
   ref?: Ref<HTMLLIElement>;
+  /** Render the child element instead of the default
+   * `<li role="menuitem">`, merging the submenu-wiring ARIA and handlers
+   * onto it via the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
+  /** When `true`, the trigger refuses to open the submenu on both click
+   * and the inline-forward arrow key, and is marked `aria-disabled`.
+   * @default false */
   disabled?: boolean;
 };
 
@@ -334,9 +470,15 @@ export type ContextMenuSubTriggerProps = Omit<
  */
 export type ContextMenuSubContentProps = Omit<
   ComponentProps<"menu">,
-  "role" | "popover" | "id"
+  "role" | "popover" | "id" | "ref"
 > & {
+  /** The submenu's items. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLMenuElement` (or the `asChild` host). */
   ref?: Ref<HTMLMenuElement>;
+  /** Render the child element instead of the default `<menu>`, merging the
+   * managed `role` / `popover` / `id` and the keyboard handler onto it via
+   * the {@link Slot} pattern.
+   * @default false */
   asChild?: boolean;
 };

package/src/DirectionProvider/DirectionProvider.tsx

@@ -5,20 +5,52 @@ import { DirectionProviderProps } from "./types";
 
 /**
  * Broadcasts a reading direction to every descendant so direction-aware
- * components can inherit it instead of each being passed an explicit
- * `dir` prop.
+ * components can inherit it through context instead of each being passed
+ * an explicit `dir` prop.
  *
- * Renders **no DOM** — only a context provider. Direction is never
- * inferred from the DOM; the consumer still owns setting `dir` on their
- * `<html>` (or another element) for CSS. A descendant component's own
- * `dir` prop always wins over the inherited value; components fall back
- * to {@link useDirection} only when their `dir` prop is omitted.
+ * Renders **no DOM host element** — only a React context provider.
+ * Direction is never inferred from the DOM; the consumer still owns
+ * setting `dir` on their `<html>` (or another ancestor element) for
+ * CSS purposes. This component only propagates the {@link Direction}
+ * value to `@primitiv-ui/react` components.
+ *
+ * **Override precedence.** A descendant component's own `dir` prop
+ * always wins over the inherited value; components fall back to
+ * {@link useDirection} only when their `dir` prop is omitted:
+ *
+ * ```tsx
+ * <DirectionProvider dir="rtl">
+ *   {/* inherits rtl *\/}
+ *   <Tabs.Root defaultValue="a">...</Tabs.Root>
+ *   {/* explicit ltr overrides the provider *\/}
+ *   <Tabs.Root dir="ltr" defaultValue="a">...</Tabs.Root>
+ * </DirectionProvider>
+ * ```
+ *
+ * **Nesting.** Providers nest — an inner `DirectionProvider` overrides an
+ * outer one for its subtree.
+ *
+ * **`useDirection` hook.** Direction-aware sub-components read the
+ * inherited value via {@link useDirection}, which falls back to `"ltr"`
+ * when no provider is present.
  *
  * @example Declare direction once near the app root
  * ```tsx
+ * import { DirectionProvider } from "@primitiv-ui/react";
+ *
+ * <DirectionProvider dir="rtl">
+ *   <Tabs.Root defaultValue="overview">...</Tabs.Root>
+ *   <Slider.Root defaultValue={[50]} aria-label="Volume" />
+ * </DirectionProvider>
+ * ```
+ *
+ * @example Nested providers — inner overrides outer for its subtree
+ * ```tsx
  * <DirectionProvider dir="rtl">
- *   <Tabs.Root>…</Tabs.Root>
- *   <Slider.Root>…</Slider.Root>
+ *   <Tabs.Root defaultValue="a">...</Tabs.Root>
+ *   <DirectionProvider dir="ltr">
+ *     <Tabs.Root defaultValue="b">...</Tabs.Root>
+ *   </DirectionProvider>
  * </DirectionProvider>
  * ```
  */

package/src/DirectionProvider/README.md

@@ -12,7 +12,7 @@ Renders **no DOM** — only a React context provider.
 import { DirectionProvider } from "@primitiv-ui/react";
 
 <DirectionProvider dir="rtl">
-  <Tabs.Root defaultValue="overview">…</Tabs.Root>
+  <Tabs.Root defaultValue="overview">...</Tabs.Root>
   <Slider.Root defaultValue={[50]} aria-label="Volume" />
 </DirectionProvider>;
 ```
@@ -23,9 +23,9 @@ components fall back to the provider only when `dir` is omitted:
 ```tsx
 <DirectionProvider dir="rtl">
   {/* inherits rtl */}
-  <Tabs.Root defaultValue="a">…</Tabs.Root>
+  <Tabs.Root defaultValue="a">...</Tabs.Root>
   {/* explicit ltr overrides the provider */}
-  <Tabs.Root dir="ltr" defaultValue="a">…</Tabs.Root>
+  <Tabs.Root dir="ltr" defaultValue="a">...</Tabs.Root>
 </DirectionProvider>;
 ```
 
@@ -48,7 +48,7 @@ import { useDirection } from "@primitiv-ui/react";
 
 function MyControl({ dir }: { dir?: "ltr" | "rtl" }) {
   const resolvedDir = dir ?? useDirection();
-  // …
+  // ...
 }
 ```
 

package/src/DirectionProvider/__tests__/DirectionProvider.test.tsx

@@ -26,4 +26,9 @@ describe("DirectionProvider", () => {
     // Assert
     expect(screen.getByTestId("probe")).toHaveTextContent("rtl");
   });
+
+  it('sets displayName to "DirectionProvider" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(DirectionProvider.displayName).toBe("DirectionProvider");
+  });
 });

package/src/DirectionProvider/types.ts

@@ -1,11 +1,36 @@
 import { ReactNode } from "react";
 
-/** A reading direction — left-to-right or right-to-left. */
+/**
+ * A reading direction value — left-to-right or right-to-left.
+ *
+ * Used as the {@link DirectionProviderProps.dir | `dir`} prop on
+ * {@link DirectionProvider} and as the `dir` prop accepted by every
+ * direction-aware component (e.g. `Tabs.Root`, `Slider.Root`).
+ * {@link useDirection} returns this type.
+ */
 export type Direction = "ltr" | "rtl";
 
-/** Props for {@link DirectionProvider} — the `dir` broadcast to descendants. */
+/**
+ * Props for {@link DirectionProvider} — the reading direction broadcast to
+ * all descendant components.
+ *
+ * `DirectionProvider` accepts no native HTML element props: it renders no
+ * DOM host element and is a pure React context provider.
+ */
 export type DirectionProviderProps = {
-  /** The reading direction broadcast to every descendant. */
+  /**
+   * The reading direction to broadcast to every descendant.
+   * See {@link Direction}.
+   *
+   * Direction-aware components (e.g. `Tabs.Root`, `Slider.Root`) read
+   * this value via {@link useDirection} when their own `dir` prop is
+   * omitted. An explicit `dir` prop on a descendant always takes
+   * precedence over the inherited value.
+   */
   dir: Direction;
+  /**
+   * The subtree whose direction-aware components will inherit `dir`.
+   * Any React content is accepted; there is no DOM wrapper.
+   */
   children?: ReactNode;
 };

package/src/Divider/Divider.tsx

@@ -3,29 +3,38 @@ import type { ReactElement } from "react";
 import { DividerProps } from "./types";
 
 /**
- * A visual and semantic separator between content sections.
+ * A headless `<span role="separator">` that marks a visual and semantic
+ * boundary between content sections.
  *
- * Renders a `<span role="separator">` with the correct `aria-orientation`
- * attribute. Screen readers announce it as a separator element, which is
- * appropriate when the divider conveys structural meaning (e.g. separating
- * navigation groups or distinct content sections).
+ * Renders a native `<span>` with `role="separator"` and the matching
+ * `aria-orientation` attribute. Screen readers announce it as a separator,
+ * which is appropriate when the divider conveys genuine structural meaning
+ * (e.g. separating navigation groups or distinct content areas).
  *
  * **Decorative use.** When the divider is purely visual and carries no
  * semantic meaning, pass `aria-hidden="true"` to remove it from the
- * accessibility tree:
+ * accessibility tree entirely:
  *
  * ```tsx
  * <Divider aria-hidden="true" />
  * ```
  *
- * **Styling hooks.** No styles ship with the component. Use the
- * `aria-orientation` attribute selector to apply orientation-specific styles:
+ * **Styling hooks.** No styles ship with the component. Because Divider
+ * emits no `data-*` attributes, target the rendered element via the
+ * `aria-orientation` attribute selector or a `className`:
  *
  * ```css
- * [role="separator"][aria-orientation="horizontal"] { height: 1px; width: 100%; }
- * [role="separator"][aria-orientation="vertical"]   { width: 1px; height: 100%; }
+ * [role="separator"][aria-orientation="horizontal"] { height: 1px; width: 100%; background: currentColor; }
+ * [role="separator"][aria-orientation="vertical"]   { width: 1px; height: 100%; background: currentColor; }
  * ```
  *
+ * ```tsx
+ * <Divider className="my-divider" />
+ * <Divider orientation="vertical" className="my-divider--vertical" />
+ * ```
+ *
+ * @extends HTMLSpanElement
+ *
  * @example Horizontal (default)
  * ```tsx
  * <Divider />
@@ -40,6 +49,11 @@ import { DividerProps } from "./types";
  * ```tsx
  * <Divider aria-hidden="true" />
  * ```
+ *
+ * @example With a className
+ * ```tsx
+ * <Divider className="my-section-rule" />
+ * ```
  */
 export function Divider({
   orientation = "horizontal",

package/src/Divider/__tests__/Divider.contract.test.tsx

@@ -12,7 +12,7 @@ import { Divider } from "../Divider";
  * and asserted against the rendered headless component* so it can never drift
  * from what the component actually emits. Divider has **no** data-* surface — it
  * styles off `aria-orientation` — so the guard also pins that hook: the registry
- * stylesheet's `[aria-orientation="…"]` selectors depend on it.
+ * stylesheet's `[aria-orientation="..."]` selectors depend on it.
  */
 const contractPath = resolve(
   dirname(fileURLToPath(import.meta.url)),

package/src/Divider/__tests__/Divider.test.tsx

@@ -38,4 +38,9 @@ describe("Divider component", () => {
     const divider = screen.getByRole("separator");
     expect(divider).toHaveAttribute("class", "");
   });
+
+  it('sets displayName to "Divider" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(Divider.displayName).toBe("Divider");
+  });
 });

package/src/Divider/types.ts

@@ -1,10 +1,17 @@
 import { ComponentProps } from "react";
 
 /**
- * Props for the {@link Divider} component. Extends the native `<span>` props
- * with an optional `orientation`.
+ * Props for {@link Divider} — all native `<span>` attributes plus an
+ * `orientation` that controls both the visual axis and the `aria-orientation`
+ * value announced to assistive technology.
  */
 export type DividerProps = ComponentProps<"span"> & {
-  /** Axis the separator runs along. Defaults to `"horizontal"`. */
+  /**
+   * Axis the separator runs along. Sets `aria-orientation` on the rendered
+   * `<span role="separator">` so screen readers announce the correct
+   * orientation. Use `"horizontal"` for row-dividing rules and
+   * `"vertical"` for column-dividing rules.
+   * @default "horizontal"
+   */
   orientation?: "horizontal" | "vertical";
 };