@primitiv-ui/react 0.1.28 → 0.1.29

package/src/Tree/Tree.tsx

@@ -36,11 +36,39 @@ import type {
  * `<div role="tree">` and provides every descendant with the expansion
  * set, selection set, and roving-tabstop coordination.
  *
- * Expansion is controlled/uncontrolled via the `expandedValues` /
- * `defaultExpandedValues` pair (with `onExpandedChange`). Selection
- * follows the same shape under `selectionMode="single"` (default) or
- * `"multiple"`, the two modes statically discriminated so passing the
- * wrong prop pair is a type error.
+ * **State ownership.** Root owns two independent axes, each controllable
+ * or uncontrolled:
+ *
+ * - **Expansion** — which branches are open. Controlled via
+ *   {@link TreeRootControlledExpansionProps.expandedValues | `expandedValues`}
+ *   + {@link TreeRootControlledExpansionProps.onExpandedChange | `onExpandedChange`};
+ *   uncontrolled via
+ *   {@link TreeRootUncontrolledExpansionProps.defaultExpandedValues | `defaultExpandedValues`}.
+ * - **Selection** — which node(s) are selected, gated by
+ *   {@link SelectionMode | `selectionMode`} (`"single"` default, or
+ *   `"multiple"`). Each mode has its own controlled / uncontrolled
+ *   `value` / `defaultValue` / `onChange` prop trio, statically
+ *   discriminated so passing the wrong prop pair for the active mode is
+ *   a type error.
+ *
+ * **Roving tabindex.** The whole tree exposes a **single tab stop** — at
+ * most one `treeitem` carries `tabIndex={0}` (the last-focused visible
+ * item, else the first non-disabled item in visible depth-first order);
+ * every other item is `tabIndex={-1}`. `Tab` therefore enters and leaves
+ * the tree once, and the arrow keys move focus *within* it. See
+ * {@link TreeItem} / {@link TreeBranch} for the full key table.
+ *
+ * **Context.** Root provides the `TreeContext` (expansion/selection
+ * state, the node registry, roving bookkeeping, path resolver) and seeds
+ * the `TreeLevelContext` at `{ depth: 0, parentValue: null }`, which each
+ * {@link TreeBranchContent} deepens for its children.
+ *
+ * **Styling hooks.**
+ * - `role="tree"` on the rendered container.
+ * - `aria-multiselectable="true"` only when `selectionMode="multiple"`.
+ * - `data-selection-mode="single" | "multiple"`.
+ *
+ * @extends HTMLDivElement
  *
  * @example Uncontrolled, single selection
  * ```tsx
@@ -120,18 +148,57 @@ export function TreeRoot(props: TreeRootProps): ReactElement {
 TreeRoot.displayName = "TreeRoot";
 
 /**
- * A leaf treeitem — a selectable, focusable node that has no children.
- * Renders a `<div role="treeitem">` by default; pass `asChild` to merge
- * Tree behaviour onto a consumer element (e.g. `<a>`).
+ * A leaf treeitem — a selectable, focusable node with no children.
+ * Renders a `<div role="treeitem">` by default; pass
+ * {@link TreeItemProps.asChild | `asChild`} to merge the tree behaviour
+ * onto a consumer element instead (e.g. an `<a>` for a navigable file).
+ *
+ * **Selection.** Clicking the item *replaces* the selection in single
+ * mode. In multiple mode, `Ctrl`/`Cmd`+click toggles it into or out of
+ * the set, and `Shift`+click selects the contiguous range (in visible
+ * depth-first order, disabled nodes excluded) between the previous
+ * selection anchor and this item.
+ *
+ * **Depth & registry.** The item reads its nesting depth and enclosing
+ * branch from `TreeLevelContext`, emits `aria-level={depth + 1}`, and
+ * registers itself (value, {@link TreeItemProps.label | `label`}, depth,
+ * parent) in the tree's node registry. The registry keeps the last-seen
+ * entry per value even after unmount, so `Tree.SelectionPath` and
+ * {@link useTreePath} can resolve ancestry through a collapsed branch.
+ *
+ * **Keyboard** (while focused; movement is over *visible* items in
+ * depth-first order, skipping collapsed subtrees and disabled nodes):
  *
- * Clicking the item replaces the selection in single mode and toggles
- * it under `Ctrl`/`Cmd` in multiple mode; `Shift+click` selects the
- * range between the previous click and this one.
+ * | Key                     | Behaviour                                     |
+ * | ----------------------- | --------------------------------------------- |
+ * | `ArrowDown` / `ArrowUp` | Move focus to the next / previous visible item |
+ * | `ArrowLeft`             | Move focus to the parent branch (no-op at root)|
+ * | `Home` / `End`          | Focus the first / last visible item            |
+ * | `Enter` / `Space`       | Select the item                                |
+ *
+ * A `disabled` item is removed from the roving order and ignores
+ * selection, but `Home`/`End` still land on non-disabled neighbours.
+ *
+ * **Styling hooks.**
+ * - `role="treeitem"`, `aria-level`, `aria-selected`, and `aria-disabled`
+ *   (omitted when not disabled).
+ * - `data-leaf=""` (always), `data-depth="{n}"`.
+ * - `data-selected=""` when selected, `data-disabled=""` when disabled
+ *   (both omitted otherwise).
+ *
+ * @extends HTMLDivElement
  *
  * @example
  * ```tsx
  * <Tree.Item value="readme">readme</Tree.Item>
  * ```
+ *
+ * @example asChild — a navigable leaf
+ * ```tsx
+ * <Tree.Item asChild value="readme">
+ *   <a href="/readme">readme</a>
+ * </Tree.Item>
+ * ```
  */
 export function TreeItem({
   value,
@@ -212,10 +279,43 @@ TreeItem.displayName = "TreeItem";
  * with `partitionBranchChildren`.
  *
  * The branch carries `aria-expanded`, `aria-selected`, `aria-level`,
- * and is labelled by its control row via `aria-labelledby` so its
- * accessible name is not polluted by descendant text. Content is
- * unmounted while collapsed unless the inner `Tree.BranchContent`
- * opts in to `forceMount`.
+ * and is labelled by its control row via `aria-labelledby` (an id
+ * derived from the root id + this branch's `value`), so its accessible
+ * name is the control text alone and not polluted by descendant text.
+ * Content is unmounted while collapsed unless the inner
+ * {@link TreeBranchContent} opts in to
+ * {@link TreeBranchContentProps.forceMount | `forceMount`}.
+ *
+ * **Composition.** A `Tree.Branch` must contain exactly one
+ * {@link TreeBranchControl} and at most one {@link TreeBranchContent};
+ * both are matched however deeply they are wrapped in fragments (so
+ * `{open && <BranchContent/>}` partitions the same as a bare element).
+ * Violating that throws a descriptive error during render. The branch
+ * provides `TreeItemContext` (its value, expanded/disabled state, and
+ * control id) to those two sub-components.
+ *
+ * **Keyboard** (adds branch semantics on top of the roving keys shared
+ * with {@link TreeItem}):
+ *
+ * | Key          | Behaviour                                                     |
+ * | ------------ | ------------------------------------------------------------- |
+ * | `ArrowRight` | Expand if collapsed; if already open, move focus to first child|
+ * | `ArrowLeft`  | Collapse if open; otherwise move focus to the parent branch    |
+ * | `Enter` / `Space` | Toggle expansion **and** select the branch in one gesture |
+ *
+ * A `disabled` branch keeps its row and current content rendered but
+ * ignores expansion, selection, and the branch arrow keys, and is
+ * skipped by roving navigation.
+ *
+ * **Styling hooks.**
+ * - `role="treeitem"`, `aria-level`, `aria-expanded`, `aria-selected`,
+ *   `aria-labelledby`, and `aria-disabled` (omitted when not disabled).
+ * - `data-branch=""` (always), `data-depth="{n}"`,
+ *   `data-state="open" | "closed"`.
+ * - `data-selected=""` / `data-disabled=""` when applicable (omitted
+ *   otherwise).
+ *
+ * @extends HTMLDivElement
  *
  * @example
  * ```tsx
@@ -307,11 +407,21 @@ export function TreeBranch({
 TreeBranch.displayName = "TreeBranch";
 
 /**
- * The clickable row of a `Tree.Branch`. Renders a `<div>` by default
- * (or any element via `asChild`) and is identified by the id the
- * surrounding branch points `aria-labelledby` at. Clicking the row
- * toggles the branch's expansion and selects it in a single gesture;
- * the inner `Tree.BranchIndicator` is decorative.
+ * The clickable row of a {@link TreeBranch | `Tree.Branch`}. Renders a
+ * `<div>` by default, or any element via
+ * {@link TreeBranchControlProps.asChild | `asChild`}. It carries the
+ * `id` that the surrounding branch points `aria-labelledby` at, so its
+ * text becomes the branch's accessible name — keep the label content
+ * here rather than on the branch.
+ *
+ * Clicking the row toggles the branch's expansion **and** selects it in
+ * a single gesture (with the same `Ctrl`/`Cmd` / `Shift` modifier rules
+ * as {@link TreeItem}); the inner {@link TreeBranchIndicator} is purely
+ * decorative. A disabled branch's control ignores the click. Reads its
+ * value / disabled state / id from the branch's `TreeItemContext`, so it
+ * must be rendered inside a `Tree.Branch`.
+ *
+ * @extends HTMLDivElement
  *
  * @example
  * ```tsx
@@ -356,13 +466,30 @@ export function TreeBranchControl({
 TreeBranchControl.displayName = "TreeBranchControl";
 
 /**
- * The nested group of items inside a `Tree.Branch`. Renders a
- * `<div role="group">` whose children sit at one deeper nesting level.
+ * The nested group of items inside a {@link TreeBranch | `Tree.Branch`}.
+ * Renders a `<div role="group">` and deepens the `TreeLevelContext` for
+ * its children (`depth + 1`, `parentValue` = the enclosing branch), so
+ * they emit the correct `aria-level` and register under the right parent.
+ *
+ * By default the content is **unmounted** while the branch is collapsed —
+ * the lean-DOM strategy. Pass
+ * {@link TreeBranchContentProps.forceMount | `forceMount`} to keep it
+ * mounted while collapsed with `aria-hidden="true"` and
+ * `data-state="closed"`, so CSS can animate it in and out without the
+ * browser tearing the subtree down.
+ *
+ * **Styling hooks.**
+ * - `role="group"`, `data-depth="{n}"`, `data-state="open" | "closed"`.
+ * - `aria-hidden="true"` only while force-mounted and collapsed.
  *
- * By default the content is unmounted while the branch is collapsed —
- * the lean DOM strategy. Pass `forceMount` to keep it mounted with
- * `aria-hidden="true"` and `data-state="closed"`, so CSS can animate
- * it in and out without the browser tearing the subtree down.
+ * @extends HTMLDivElement
+ *
+ * @example forceMount for CSS transitions
+ * ```tsx
+ * <Tree.BranchContent forceMount>
+ *   <Tree.Item value="index">index.ts</Tree.Item>
+ * </Tree.BranchContent>
+ * ```
  */
 export function TreeBranchContent({
   children,
@@ -398,10 +525,15 @@ TreeBranchContent.displayName = "TreeBranchContent";
  * `"closed"` so a consumer's CSS can rotate or swap the glyph. Only
  * meaningful inside a `Tree.BranchControl`.
  *
- * Pass `asChild` to merge the indicator's props — including
- * `aria-hidden` and `data-state` — onto the supplied child element.
- * This is useful when passing an icon component that must receive
- * `data-state` directly rather than inheriting it from a wrapper:
+ * Pass {@link TreeBranchIndicatorProps.asChild | `asChild`} to merge the
+ * indicator's props — including `aria-hidden` and `data-state` — onto the
+ * supplied child element. This is useful when passing an icon component
+ * that must receive `data-state` directly rather than inheriting it from
+ * a wrapper. Reads its `expanded` state from the branch's
+ * `TreeItemContext`, so it must be rendered inside a
+ * {@link TreeBranchControl}.
+ *
+ * @extends HTMLSpanElement
  *
  * @example Default (wraps children in a `<span>`)
  * ```tsx
@@ -456,9 +588,24 @@ TreeBranchIndicator.displayName = "TreeBranchIndicator";
  *
  * Pass `separator` to customise the divider glyph between segments.
  *
- * Pass a function as `children` to take full control of rendering
- * (e.g. wire up router links). The function receives the resolved
- * paths and replaces the default markup entirely.
+ * Pass {@link TreeSelectionPathProps.separator | `separator`} to
+ * customise the divider glyph between segments, or a function as
+ * `children` to take full control of rendering (e.g. wire up router
+ * links). The function receives the resolved
+ * {@link TreeSelectionPathRenderProps.paths | `paths`} and replaces the
+ * default markup entirely.
+ *
+ * Backed by {@link useTreeSelectionPaths}, which reads ancestry from the
+ * persistent node registry — so trails stay resolvable even when an
+ * ancestor branch has collapsed and its descendants have unmounted.
+ *
+ * **Styling hooks.**
+ * - `data-tree-selection-path=""` on the wrapper (always).
+ * - `data-empty=""` on the wrapper when nothing is selected.
+ * - `data-tree-selection-segment=""` + `data-value` (and `data-disabled`
+ *   when the node is disabled) on each rendered segment.
+ *
+ * @extends HTMLDivElement
  *
  * @example Default rendering
  * ```tsx
@@ -600,6 +747,13 @@ export type TreeCompound = typeof TreeRoot & {
  *   </Tree.Branch>
  * </Tree.Root>;
  * ```
+ *
+ * @see {@link TreeRoot} for the expansion / selection state modes and the
+ *   single tree-wide roving tab stop.
+ * @see {@link TreeItem} and {@link TreeBranch} for the keyboard tables and
+ *   selection modifiers.
+ * @see {@link useTreePath} / {@link useTreeSelectionPaths} for reading a
+ *   node's ancestry outside `Tree.SelectionPath`.
  */
 const TreeCompound: TreeCompound = Object.assign(TreeRoot, {
   Root: TreeRoot,

package/src/Tree/types.ts

@@ -7,26 +7,37 @@ export type TreeRootBaseProps = ComponentProps<"div"> & {
 
 /** Uncontrolled expansion — initial expanded branches via `defaultExpandedValues`. */
 export type TreeRootUncontrolledExpansionProps = {
-  /** Branch values expanded on first render when uncontrolled. */
+  /** Branch values expanded on first render when uncontrolled. Omit for a
+   * fully-collapsed tree. */
   defaultExpandedValues?: string[];
   expandedValues?: never;
+  /** Called with the full set of expanded branch values whenever a branch
+   * is toggled. Optional in uncontrolled mode. */
   onExpandedChange?: (values: string[]) => void;
 };
 
 /** Controlled expansion — the expanded set is owned by the consumer. */
 export type TreeRootControlledExpansionProps = {
   defaultExpandedValues?: never;
-  /** The set of expanded branch values, owned by the consumer. */
+  /** The set of expanded branch values, owned by the consumer. Keep in
+   * sync via `onExpandedChange`. */
   expandedValues: string[];
+  /** Called with the full set of expanded branch values the user requested
+   * on each toggle. Required in controlled mode. */
   onExpandedChange: (values: string[]) => void;
 };
 
 /** Single-selection mode, uncontrolled — initial value via `defaultSelectedValue`. */
 export type TreeRootSingleUncontrolledSelectionProps = {
+  /** At most one node may be selected; see {@link SelectionMode}.
+   * @default "single" */
   selectionMode?: "single";
-  /** The value selected on first render when uncontrolled. */
+  /** The value selected on first render when uncontrolled. `null` selects
+   * nothing. */
   defaultSelectedValue?: string | null;
   selectedValue?: never;
+  /** Called with the newly-selected value (or `null` when cleared) on each
+   * user selection. Optional in uncontrolled mode. */
   onSelectedValueChange?: (value: string | null) => void;
   defaultSelectedValues?: never;
   selectedValues?: never;
@@ -35,10 +46,15 @@ export type TreeRootSingleUncontrolledSelectionProps = {
 
 /** Single-selection mode, controlled — the selected value is owned by the consumer. */
 export type TreeRootSingleControlledSelectionProps = {
+  /** At most one node may be selected; see {@link SelectionMode}.
+   * @default "single" */
   selectionMode?: "single";
   defaultSelectedValue?: never;
-  /** The selected value, owned by the consumer. */
+  /** The selected value, owned by the consumer (or `null` for no
+   * selection). Keep it in sync via `onSelectedValueChange`. */
   selectedValue: string | null;
+  /** Called with the value the user requested to select (or `null` when
+   * cleared). Required in controlled mode. */
   onSelectedValueChange: (value: string | null) => void;
   defaultSelectedValues?: never;
   selectedValues?: never;
@@ -47,10 +63,14 @@ export type TreeRootSingleControlledSelectionProps = {
 
 /** Multiple-selection mode, uncontrolled — initial values via `defaultSelectedValues`. */
 export type TreeRootMultipleUncontrolledSelectionProps = {
+  /** Many nodes may be selected via `Ctrl`/`Cmd`+click and `Shift`+click
+   * ranges; see {@link SelectionMode}. */
   selectionMode: "multiple";
   /** The values selected on first render when uncontrolled. */
   defaultSelectedValues?: string[];
   selectedValues?: never;
+  /** Called with the full selected set (in selection order) on each
+   * change. Optional in uncontrolled mode. */
   onSelectedValuesChange?: (values: string[]) => void;
   defaultSelectedValue?: never;
   selectedValue?: never;
@@ -59,10 +79,15 @@ export type TreeRootMultipleUncontrolledSelectionProps = {
 
 /** Multiple-selection mode, controlled — the selected values are owned by the consumer. */
 export type TreeRootMultipleControlledSelectionProps = {
+  /** Many nodes may be selected via `Ctrl`/`Cmd`+click and `Shift`+click
+   * ranges; see {@link SelectionMode}. */
   selectionMode: "multiple";
   defaultSelectedValues?: never;
-  /** The selected values, owned by the consumer. */
+  /** The selected values, owned by the consumer. Keep in sync via
+   * `onSelectedValuesChange`. */
   selectedValues: string[];
+  /** Called with the full selected set (in selection order) the user
+   * requested. Required in controlled mode. */
   onSelectedValuesChange: (values: string[]) => void;
   defaultSelectedValue?: never;
   selectedValue?: never;
@@ -86,7 +111,9 @@ export type TreeRootProps = TreeRootBaseProps &
 
 /** Props for `Tree.Item` — a selectable, focusable leaf treeitem. */
 export type TreeItemProps = ComponentProps<"div"> & {
-  /** Stable identifier for this item, unique within the tree. */
+  /** Stable identifier for this item, unique within the tree. Links the
+   * item to selection / expansion state and to its
+   * {@link TreePathSegment} in a resolved path. */
   value: string;
   /**
    * Optional display label for this item. Stored alongside the value
@@ -95,16 +122,23 @@ export type TreeItemProps = ComponentProps<"div"> & {
    * Has no effect on what `Tree.Item` renders.
    */
   label?: string;
-  /** Disable selection and remove the item from roving navigation. */
+  /** Disable selection and remove the item from roving navigation
+   * (`Home`/`End` still skip past it to a non-disabled neighbour).
+   * @default false */
   disabled?: boolean;
-  /** Render the item as the supplied child element instead of `<div>`. */
+  /** Render the item as the supplied child element instead of `<div>`,
+   * merging the treeitem behaviour onto it via the {@link Slot} pattern.
+   * The child must accept a `ref`.
+   * @default false */
   asChild?: boolean;
   children: ReactNode;
 };
 
 /** Props for `Tree.Branch` — an expandable treeitem with nested children. */
 export type TreeBranchProps = Omit<ComponentProps<"div">, "ref"> & {
-  /** Stable identifier for this branch, unique within the tree. */
+  /** Stable identifier for this branch, unique within the tree. Also seeds
+   * the `parentValue` of its {@link TreeBranchContent}'s children and the
+   * derived `aria-labelledby` control id. */
   value: string;
   /**
    * Optional display label for this branch. Stored alongside the value
@@ -116,6 +150,7 @@ export type TreeBranchProps = Omit<ComponentProps<"div">, "ref"> & {
   /**
    * Disable selection, expansion-toggling, and roving navigation for
    * this branch. The branch and its current content remain rendered.
+   * @default false
    */
   disabled?: boolean;
   children: ReactNode;
@@ -123,7 +158,10 @@ export type TreeBranchProps = Omit<ComponentProps<"div">, "ref"> & {
 
 /** Props for `Tree.BranchControl` — the branch's selectable, toggling control row. */
 export type TreeBranchControlProps = ComponentProps<"div"> & {
-  /** Render the control as the supplied child element instead of `<div>`. */
+  /** Render the control as the supplied child element instead of `<div>`,
+   * merging its props (including the `aria-labelledby` id) onto the child
+   * via the {@link Slot} pattern. The child must accept a `ref`.
+   * @default false */
   asChild?: boolean;
   children: ReactNode;
 };
@@ -134,14 +172,18 @@ export type TreeBranchContentProps = ComponentProps<"div"> & {
   /**
    * Keep the content mounted while the branch is collapsed so CSS can
    * animate it in and out. When collapsed it is hidden from assistive
-   * technology with `aria-hidden`.
+   * technology with `aria-hidden` and carries `data-state="closed"`.
+   * @default false
    */
   forceMount?: boolean;
 };
 
 /** Props for `Tree.BranchIndicator` — the expand/collapse affordance. */
 export type TreeBranchIndicatorProps = ComponentProps<"span"> & {
-  /** Render as the supplied child element instead of `<span>`. */
+  /** Render as the supplied child element instead of `<span>`, merging
+   * `aria-hidden` and `data-state` onto it via the {@link Slot} pattern
+   * (e.g. an icon that rotates on `data-state="open"`).
+   * @default false */
   asChild?: boolean;
 };
 

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -19,18 +19,35 @@ const visuallyHiddenStyle: CSSProperties = {
 /**
  * Visually hides its children while keeping them in the accessibility tree.
  *
- * Renders a `<span>` carrying the canonical screen-reader-only clip styles:
- * the content is removed from the visual layout but still announced by
- * assistive technology. Use it for text that gives a control or region an
- * accessible name without showing on screen.
+ * Renders a `<span>` carrying the canonical screen-reader-only clip styles
+ * (WCAG 2.1 Technique C7): the content is removed from the visual layout but
+ * still announced by assistive technology. Use it for text that gives a control
+ * or region an accessible name without showing on screen.
  *
  * **Functional styles.** Unlike other `@primitiv-ui/react` components, the
- * clip styles are applied inline because they *are* the component's
- * behaviour, not decoration. A consumer `style` is merged on top, so any
- * individual property can still be overridden.
+ * clip styles are applied inline because they *are* the component's behaviour,
+ * not decoration:
+ *
+ * ```css
+ * position: absolute;
+ * width: 1px; height: 1px;
+ * padding: 0; margin: -1px;
+ * overflow: hidden;
+ * clip: rect(0 0 0 0);
+ * clip-path: inset(50%);
+ * white-space: nowrap;
+ * border-width: 0;
+ * ```
+ *
+ * A consumer `style` prop is merged on top, so any individual property can
+ * still be overridden.
  *
  * **`asChild` composition.** Renders the consumer's element instead of a
- * `<span>`, merging the clip styles in via the {@link Slot} utility.
+ * `<span>`, merging the clip styles onto the child via the {@link Slot}
+ * utility. Useful when the hidden content needs specific semantics (e.g. a
+ * heading or landmark). The child must be a single React element.
+ *
+ * @extends HTMLSpanElement
  *
  * @example Accessible name for an icon-only button
  * ```tsx
@@ -40,6 +57,14 @@ const visuallyHiddenStyle: CSSProperties = {
  * </button>
  * ```
  *
+ * @example Region label hidden from sighted users
+ * ```tsx
+ * <nav aria-labelledby="nav-label">
+ *   <VisuallyHidden id="nav-label">Primary navigation</VisuallyHidden>
+ *   …
+ * </nav>
+ * ```
+ *
  * @example asChild — keep semantic markup hidden
  * ```tsx
  * <VisuallyHidden asChild>

package/src/VisuallyHidden/__tests__/VisuallyHidden.test.tsx

@@ -15,15 +15,24 @@ describe("VisuallyHidden component", () => {
     // Arrange
     render(<VisuallyHidden>Loading complete</VisuallyHidden>);
 
-    // Assert
+    // Assert — the full WCAG C7 clip set; every property matters, so each is
+    // asserted (a missing one lets a mutant blank that value undetected).
     const hidden = screen.getByText("Loading complete");
     expect(hidden).toHaveStyle({
       position: "absolute",
       width: "1px",
       height: "1px",
+      padding: "0px",
+      margin: "-1px",
       overflow: "hidden",
       whiteSpace: "nowrap",
+      borderWidth: "0px",
     });
+    // jsdom's computed style doesn't surface clip/clip-path, so assert them on
+    // the inline style directly.
+    // jsdom normalises `rect(0 0 0 0)` to `rect(0px)`.
+    expect(hidden.style.clip).toBe("rect(0px)");
+    expect(hidden.style.clipPath).toBe("inset(50%)");
   });
 
   it("should merge a consumer style over the clip styles", () => {
@@ -56,4 +65,9 @@ describe("VisuallyHidden component", () => {
     expect(hidden.tagName).toBe("LABEL");
     expect(hidden).toHaveStyle({ position: "absolute", overflow: "hidden" });
   });
+
+  it('sets displayName to "VisuallyHidden" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(VisuallyHidden.displayName).toBe("VisuallyHidden");
+  });
 });

package/src/VisuallyHidden/types.ts

@@ -1,9 +1,19 @@
-import { ComponentProps } from "react";
+import { ComponentProps, ReactNode } from "react";
 
 /**
  * Props for {@link VisuallyHidden} — all native `<span>` attributes plus
  * the `asChild` escape hatch.
  */
 export type VisuallyHiddenProps = ComponentProps<"span"> & {
+  /**
+   * Renders the child element instead of a native `<span>`, merging the
+   * clip styles onto it via {@link Slot}. Useful when the hidden content
+   * needs specific semantics (e.g. a heading or landmark element). The
+   * child must be a single React element. See the `asChild` example on
+   * {@link VisuallyHidden}.
+   * @default false
+   */
   asChild?: boolean;
+  /** Content to visually hide. Under `asChild`, becomes the single child element whose clip styles are merged. */
+  children?: ReactNode;
 };

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./Collapsible/index.ts";
 export * from "./ContextMenu/index.ts";
 export * from "./DirectionProvider/index.ts";
 export * from "./Divider/index.ts";
+export * from "./Drawer/index.ts";
 export * from "./Dropdown/index.ts";
 export * from "./EmptyState/index.ts";
 export * from "./Field/index.ts";
@@ -19,11 +20,14 @@ export * from "./Input/index.ts";
 export * from "./InputGroup/index.ts";
 export * from "./MillerColumns/index.ts";
 export * from "./Modal/index.ts";
+export * from "./NavigationMenu/index.ts";
+export * from "./Popover/index.ts";
 export * from "./Portal/index.ts";
 export * from "./Progress/index.ts";
 export * from "./Radio/index.ts";
 export * from "./RadioCard/index.ts";
 export * from "./RadioGroup/index.ts";
+export * from "./SegmentedControl/index.ts";
 export * from "./Select/index.ts";
 export * from "./SkipNav/index.ts";
 export * from "./Slider/index.ts";

package/src/test/intersectionObserverPolyfill.ts

@@ -41,6 +41,13 @@ export class MockIntersectionObserver {
   }
 
   observe(target: Element) {
+    // Mirror the browser: `observe` throws a TypeError when handed anything
+    // that is not an Element (e.g. `undefined` from a stale slide lookup).
+    if (!(target instanceof Element)) {
+      throw new TypeError(
+        "Failed to execute 'observe' on 'IntersectionObserver': parameter 1 is not of type 'Element'.",
+      );
+    }
     this.observed.add(target);
   }
   unobserve(target: Element) {