@primitiv-ui/react 0.1.27 → 0.1.29

package/src/Dropdown/types.ts

@@ -8,6 +8,12 @@ import { Direction } from "../DirectionProvider/index.ts";
  * the reading-direction control.
  */
 export type DropdownRootBaseProps = {
+  /**
+   * The menu's sub-components — typically a single {@link DropdownTriggerProps |
+   * `Dropdown.Trigger`} followed by a {@link DropdownContentProps |
+   * `Dropdown.Content`}. Root renders no DOM of its own; it only provides
+   * context to these descendants.
+   */
   children?: ReactNode;
   /**
    * Reading direction for the menu. Affects which arrow key opens / closes
@@ -24,8 +30,19 @@ export type DropdownRootBaseProps = {
  * and `open` is forbidden.
  */
 export type DropdownRootUncontrolledProps = DropdownRootBaseProps & {
+  /**
+   * Open state on first render. Omit to start closed. The component owns
+   * the state thereafter.
+   * @default false
+   */
   defaultOpen?: boolean;
+  /** Forbidden in uncontrolled mode — use `defaultOpen` instead. */
   open?: never;
+  /**
+   * Called whenever a user-driven transition opens or closes the menu
+   * (trigger click, Escape, outside click, selection). Optional in
+   * uncontrolled mode.
+   */
   onOpenChange?: (open: boolean) => void;
 };
 
@@ -35,8 +52,18 @@ export type DropdownRootUncontrolledProps = DropdownRootBaseProps & {
  * forbidden.
  */
 export type DropdownRootControlledProps = DropdownRootBaseProps & {
+  /** Forbidden in controlled mode — use `open` instead. */
   defaultOpen?: never;
+  /**
+   * The current open state. Must be kept in sync by the parent via
+   * `onOpenChange`; the component never mutates it internally.
+   */
   open: boolean;
+  /**
+   * Called whenever a user-driven transition would open or close the menu.
+   * The parent is responsible for reflecting the new value back into
+   * `open`. Required in controlled mode.
+   */
   onOpenChange: (open: boolean) => void;
 };
 
@@ -58,8 +85,17 @@ export type DropdownTriggerProps = Omit<
   ComponentProps<"button">,
   "aria-haspopup" | "aria-expanded" | "aria-controls"
 > & {
+  /** The trigger's visible label (or an element, with `asChild`). */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLButtonElement`. */
   ref?: Ref<HTMLButtonElement>;
+  /**
+   * Render the composed child element instead of the default
+   * `<button type="button">`. The trigger's ARIA contract
+   * (`aria-haspopup`, `aria-expanded`, `aria-controls`) and its click
+   * handler are merged onto the child via the {@link Slot} pattern.
+   * @default false
+   */
   asChild?: boolean;
 };
 
@@ -70,10 +106,26 @@ export type DropdownTriggerProps = Omit<
  */
 export type DropdownContentProps = Omit<
   ComponentProps<"menu">,
-  "role" | "popover" | "id"
+  "role" | "popover" | "id" | "ref"
 > & {
+  /**
+   * The menu items — any mix of {@link DropdownItemProps | `Dropdown.Item`},
+   * {@link DropdownCheckboxItemProps | `Dropdown.CheckboxItem`},
+   * {@link DropdownRadioGroupProps | `Dropdown.RadioGroup`},
+   * {@link DropdownGroupProps | `Dropdown.Group`},
+   * {@link DropdownSeparatorProps | `Dropdown.Separator`}, and
+   * {@link DropdownSubProps | `Dropdown.Sub`}.
+   */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLMenuElement`. */
   ref?: Ref<HTMLMenuElement>;
+  /**
+   * Render the composed child element (with menu semantics) instead of the
+   * default `<menu role="menu" popover="auto">`. The managed `role`,
+   * `popover`, and `id` attributes and the keyboard handler are merged onto
+   * the child via the {@link Slot} pattern.
+   * @default false
+   */
   asChild?: boolean;
 };
 
@@ -86,14 +138,26 @@ export type DropdownItemProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "onSelect"
 > & {
+  /** The item's visible content (or an element, with `asChild`). */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement`. */
   ref?: Ref<HTMLLIElement>;
+  /**
+   * Render the composed child element (with menuitem semantics) instead of
+   * the default `<li role="menuitem">`.
+   * @default false
+   */
   asChild?: boolean;
+  /**
+   * Mark the item non-interactive. Sets `aria-disabled="true"` and skips
+   * the item during arrow navigation, typeahead, and activation.
+   * @default false
+   */
   disabled?: boolean;
   /**
    * Fires when the item is activated (click, Enter, or Space). Called
-   * with an event whose `preventDefault()` skips the auto-close that
-   * Dropdown performs after selection.
+   * with a cancellable event whose `preventDefault()` skips the auto-close
+   * that Dropdown performs after selection.
    */
   onSelect?: (event: Event) => void;
 };
@@ -103,8 +167,15 @@ export type DropdownItemProps = Omit<
  * groups of items. Extends the native `<li>` props and adds `asChild`.
  */
 export type DropdownSeparatorProps = Omit<ComponentProps<"li">, "role"> & {
+  /** Optional content; separators are usually empty. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement`. */
   ref?: Ref<HTMLLIElement>;
+  /**
+   * Render the composed child element (with separator semantics) instead of
+   * the default `<li role="separator">`.
+   * @default false
+   */
   asChild?: boolean;
 };
 
@@ -114,14 +185,21 @@ export type DropdownSeparatorProps = Omit<ComponentProps<"li">, "role"> & {
  * `forceMount` to keep it mounted while unchecked for enter/exit animation.
  */
 export type DropdownItemIndicatorProps = ComponentProps<"span"> & {
+  /** The mark to render — commonly an SVG check or bullet icon. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLSpanElement`. */
   ref?: Ref<HTMLSpanElement>;
+  /**
+   * Render the composed child element instead of the default `<span>`.
+   * @default false
+   */
   asChild?: boolean;
   /**
    * Render the indicator even when its parent item is unchecked. The
    * `data-state` attribute still reflects the live state (`"checked"` /
    * `"unchecked"` / `"indeterminate"`), so consumers can animate the
    * indicator in and out instead of mounting / unmounting it.
+   * @default false
    */
   forceMount?: boolean;
 };
@@ -131,8 +209,18 @@ export type DropdownItemIndicatorProps = ComponentProps<"span"> & {
  * Extends the native `<li>` props and adds `asChild`.
  */
 export type DropdownGroupProps = Omit<ComponentProps<"li">, "role"> & {
+  /**
+   * The grouped items, optionally led by a {@link DropdownLabelProps |
+   * `Dropdown.Label`} that names the group.
+   */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement`. */
   ref?: Ref<HTMLLIElement>;
+  /**
+   * Render the composed child element (with `role="group"`) instead of the
+   * default `<li role="group">` wrapping `<ul role="none">`.
+   * @default false
+   */
   asChild?: boolean;
 };
 
@@ -141,8 +229,14 @@ export type DropdownGroupProps = Omit<ComponentProps<"li">, "role"> & {
  * {@link Dropdown.Group}. Extends the native `<li>` props and adds `asChild`.
  */
 export type DropdownLabelProps = ComponentProps<"li"> & {
+  /** The label text. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement`. */
   ref?: Ref<HTMLLIElement>;
+  /**
+   * Render the composed child element instead of the default `<li>`.
+   * @default false
+   */
   asChild?: boolean;
 };
 
@@ -154,13 +248,29 @@ export type DropdownCheckboxItemBaseProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "aria-checked" | "defaultChecked" | "onSelect"
 > & {
+  /**
+   * The item's content — typically a {@link DropdownItemIndicatorProps |
+   * `Dropdown.ItemIndicator`} plus a text label.
+   */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement`. */
   ref?: Ref<HTMLLIElement>;
+  /**
+   * Render the composed child element (with `role="menuitemcheckbox"`)
+   * instead of the default `<li role="menuitemcheckbox">`.
+   * @default false
+   */
   asChild?: boolean;
+  /**
+   * Mark the item non-interactive. Sets `aria-disabled="true"`; activation
+   * is a no-op.
+   * @default false
+   */
   disabled?: boolean;
   /**
-   * Fires when activation completes and the close auto-fires. Call
-   * `event.preventDefault()` to keep the menu open after toggling.
+   * Fires after activation toggles the checked state, with a cancellable
+   * event. Call `event.preventDefault()` to keep the menu open after
+   * toggling — useful for flipping several checkboxes in a row.
    */
   onSelect?: (event: Event) => void;
 };
@@ -172,8 +282,18 @@ export type DropdownCheckboxItemBaseProps = Omit<
  */
 export type DropdownCheckboxItemUncontrolledProps =
   DropdownCheckboxItemBaseProps & {
+    /**
+     * Checked state on first render — `true`, `false`, or `"indeterminate"`
+     * (rendered as `aria-checked="mixed"`). Omit to start unchecked.
+     * @default false
+     */
     defaultChecked?: CheckedState;
+    /** Forbidden in uncontrolled mode — use `defaultChecked` instead. */
     checked?: never;
+    /**
+     * Called with the new boolean checked state whenever the user toggles
+     * the item. Optional in uncontrolled mode.
+     */
     onCheckedChange?: (checked: boolean) => void;
   };
 
@@ -184,8 +304,18 @@ export type DropdownCheckboxItemUncontrolledProps =
  */
 export type DropdownCheckboxItemControlledProps =
   DropdownCheckboxItemBaseProps & {
+    /** Forbidden in controlled mode — use `checked` instead. */
     defaultChecked?: never;
+    /**
+     * The current checked state — `true`, `false`, or `"indeterminate"`.
+     * Must be kept in sync by the parent via `onCheckedChange`. An
+     * indeterminate value resolves to `true` on the next activation.
+     */
     checked: CheckedState;
+    /**
+     * Called with the new boolean checked state whenever the user toggles
+     * the item. Required in controlled mode.
+     */
     onCheckedChange: (checked: boolean) => void;
   };
 
@@ -201,11 +331,25 @@ export type DropdownCheckboxItemProps =
 
 /**
  * Shared base for both {@link DropdownRadioGroupProps} variants — the native
- * `<li>` props plus `asChild`.
+ * `<li>` props (with the native ordinal `value` omitted so the controlled
+ * variant can narrow it to a `string`) plus `asChild`.
  */
-export type DropdownRadioGroupBaseProps = Omit<ComponentProps<"li">, "role"> & {
+export type DropdownRadioGroupBaseProps = Omit<
+  ComponentProps<"li">,
+  "role" | "value" | "defaultValue"
+> & {
+  /**
+   * The radio choices — a set of {@link DropdownRadioItemProps |
+   * `Dropdown.RadioItem`} elements.
+   */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement`. */
   ref?: Ref<HTMLLIElement>;
+  /**
+   * Render the composed child element (with `role="group"`) instead of the
+   * default `<li role="group">` wrapping `<ul role="none">`.
+   * @default false
+   */
   asChild?: boolean;
 };
 
@@ -216,8 +360,17 @@ export type DropdownRadioGroupBaseProps = Omit<ComponentProps<"li">, "role"> & {
  */
 export type DropdownRadioGroupUncontrolledProps =
   DropdownRadioGroupBaseProps & {
+    /**
+     * The item `value` selected on first render. Omit for no initial
+     * selection.
+     */
     defaultValue?: string;
+    /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
     value?: never;
+    /**
+     * Called with the newly selected item `value` whenever the user picks a
+     * different radio item. Optional in uncontrolled mode.
+     */
     onValueChange?: (value: string) => void;
   };
 
@@ -227,8 +380,18 @@ export type DropdownRadioGroupUncontrolledProps =
  * forbidden.
  */
 export type DropdownRadioGroupControlledProps = DropdownRadioGroupBaseProps & {
+  /** Forbidden in controlled mode — use `value` instead. */
   defaultValue?: never;
+  /**
+   * The `value` of the currently selected {@link DropdownRadioItemProps |
+   * `Dropdown.RadioItem`}. Must be kept in sync by the parent via
+   * `onValueChange`.
+   */
   value: string;
+  /**
+   * Called with the newly selected item `value` whenever the user picks a
+   * different radio item. Required in controlled mode.
+   */
   onValueChange: (value: string) => void;
 };
 
@@ -244,18 +407,43 @@ export type DropdownRadioGroupProps =
 
 /**
  * Props for {@link Dropdown.RadioItem} — one option within a
- * {@link Dropdown.RadioGroup}. Extends the native `<li>` props and adds the
- * required `value`, plus `disabled`, `asChild`, and `onSelect`.
+ * {@link Dropdown.RadioGroup}. Extends the native `<li>` props (with the
+ * native ordinal `value` omitted so it can be narrowed to a required `string`)
+ * and adds `value`, plus `disabled`, `asChild`, and `onSelect`.
  */
 export type DropdownRadioItemProps = Omit<
   ComponentProps<"li">,
-  "role" | "tabIndex" | "aria-checked" | "onSelect"
+  "role" | "tabIndex" | "aria-checked" | "onSelect" | "value"
 > & {
+  /**
+   * The item's content — typically a {@link DropdownItemIndicatorProps |
+   * `Dropdown.ItemIndicator`} plus a text label.
+   */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement`. */
   ref?: Ref<HTMLLIElement>;
+  /**
+   * Render the composed child element (with `role="menuitemradio"`) instead
+   * of the default `<li role="menuitemradio">`.
+   * @default false
+   */
   asChild?: boolean;
+  /**
+   * Mark the item non-interactive. Sets `aria-disabled="true"`; activation
+   * is a no-op.
+   * @default false
+   */
   disabled?: boolean;
+  /**
+   * This item's identifier within the enclosing
+   * {@link DropdownRadioGroupProps | `Dropdown.RadioGroup`}. When it matches
+   * the group's active value the item is checked. Required.
+   */
   value: string;
+  /**
+   * Fires after activation selects this item, with a cancellable event.
+   * Call `event.preventDefault()` to keep the menu open after selecting.
+   */
   onSelect?: (event: Event) => void;
 };
 
@@ -264,6 +452,11 @@ export type DropdownRadioItemProps = Omit<
  * `children`.
  */
 export type DropdownSubBaseProps = {
+  /**
+   * The submenu boundary's content — a {@link DropdownSubTriggerProps |
+   * `Dropdown.SubTrigger`} and its sibling {@link DropdownSubContentProps |
+   * `Dropdown.SubContent`}.
+   */
   children?: ReactNode;
 };
 
@@ -273,8 +466,17 @@ export type DropdownSubBaseProps = {
  * optional and the controlled `open` prop is forbidden.
  */
 export type DropdownSubUncontrolledProps = DropdownSubBaseProps & {
+  /**
+   * Submenu open state on first render. Omit to start closed.
+   * @default false
+   */
   defaultOpen?: boolean;
+  /** Forbidden in uncontrolled mode — use `defaultOpen` instead. */
   open?: never;
+  /**
+   * Called whenever the submenu opens or closes. Optional in uncontrolled
+   * mode.
+   */
   onOpenChange?: (open: boolean) => void;
 };
 
@@ -284,8 +486,17 @@ export type DropdownSubUncontrolledProps = DropdownSubBaseProps & {
  * forbidden.
  */
 export type DropdownSubControlledProps = DropdownSubBaseProps & {
+  /** Forbidden in controlled mode — use `open` instead. */
   defaultOpen?: never;
+  /**
+   * The current submenu open state. Must be kept in sync by the parent via
+   * `onOpenChange`.
+   */
   open: boolean;
+  /**
+   * Called whenever the submenu would open or close. The parent reflects
+   * the new value back into `open`. Required in controlled mode.
+   */
   onOpenChange: (open: boolean) => void;
 };
 
@@ -307,9 +518,21 @@ export type DropdownSubTriggerProps = Omit<
   ComponentProps<"li">,
   "role" | "tabIndex" | "aria-haspopup" | "aria-expanded" | "aria-controls"
 > & {
+  /** The trigger's visible label (or an element, with `asChild`). */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLLIElement`. */
   ref?: Ref<HTMLLIElement>;
+  /**
+   * Render the composed child element (with menuitem + submenu-trigger
+   * semantics) instead of the default `<li role="menuitem">`.
+   * @default false
+   */
   asChild?: boolean;
+  /**
+   * Mark the trigger non-interactive. Sets `aria-disabled="true"` and
+   * ignores both click and the open arrow key.
+   * @default false
+   */
   disabled?: boolean;
 };
 
@@ -320,9 +543,16 @@ export type DropdownSubTriggerProps = Omit<
  */
 export type DropdownSubContentProps = Omit<
   ComponentProps<"menu">,
-  "role" | "popover" | "id"
+  "role" | "popover" | "id" | "ref"
 > & {
+  /** The submenu's items. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLMenuElement`. */
   ref?: Ref<HTMLMenuElement>;
+  /**
+   * Render the composed child element (with menu semantics) instead of the
+   * default `<menu role="menu" popover="auto">`.
+   * @default false
+   */
   asChild?: boolean;
 };

package/src/EmptyState/EmptyState.tsx

@@ -22,11 +22,16 @@ import {
  * Opt out of the live region by passing `role={undefined}` for an empty
  * state that is part of the initial, static page.
  *
+ * **Styling hooks.** `EmptyState.Root` emits no `data-*` attributes — it is a
+ * static layout component. Target it via `className` or element selectors.
+ *
  * **`asChild` composition.** Renders the consumer's element instead of a
  * `<div>`, merging `role="status"` and all other props in via the
  * {@link Slot} utility.
  *
- * @example
+ * @extends HTMLDivElement
+ *
+ * @example Conditional empty state (live region)
  * ```tsx
  * {results.length === 0 && (
  *   <EmptyState.Root>
@@ -35,6 +40,22 @@ import {
  *   </EmptyState.Root>
  * )}
  * ```
+ *
+ * @example Static empty state (opt out of live region)
+ * ```tsx
+ * <EmptyState.Root role={undefined}>
+ *   <EmptyState.Title>No projects yet</EmptyState.Title>
+ * </EmptyState.Root>
+ * ```
+ *
+ * @example asChild — render a `<section>` instead of a `<div>`
+ * ```tsx
+ * <EmptyState.Root asChild>
+ *   <section aria-label="Empty inbox">
+ *     <EmptyState.Title>Your inbox is empty</EmptyState.Title>
+ *   </section>
+ * </EmptyState.Root>
+ * ```
  */
 export function EmptyStateRoot({
   asChild = false,
@@ -50,7 +71,11 @@ export function EmptyStateRoot({
   return <div {...rootProps}>{children}</div>;
 }
 
-/** @internal */
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "EmptyState" at load, so the value is never observable.
+// The assignment stays because it declares `displayName` on
+// `typeof EmptyStateRoot`, which EmptyStateCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 EmptyStateRoot.displayName = "EmptyStateRoot";
 
 /**
@@ -64,16 +89,28 @@ EmptyStateRoot.displayName = "EmptyStateRoot";
  * genuinely informative, pass `aria-hidden={false}` and give it an accessible
  * name yourself.
  *
+ * **Styling hooks.** `EmptyState.Media` emits no `data-*` attributes. Target it
+ * via `className` or the `[aria-hidden]` attribute selector.
+ *
  * **`asChild` composition.** Renders the consumer's element instead of a
  * `<div>`, merging `aria-hidden="true"` and all other props in via the
  * {@link Slot} utility.
  *
- * @example
+ * @extends HTMLDivElement
+ *
+ * @example Decorative icon (default)
  * ```tsx
  * <EmptyState.Media>
  *   <InboxIcon />
  * </EmptyState.Media>
  * ```
+ *
+ * @example Informative artwork — opt back in to accessibility tree
+ * ```tsx
+ * <EmptyState.Media aria-hidden={false}>
+ *   <img src="/chart.svg" alt="Sales trending to zero" />
+ * </EmptyState.Media>
+ * ```
  */
 export function EmptyStateMedia({
   asChild = false,
@@ -101,9 +138,19 @@ EmptyStateMedia.displayName = "EmptyStateMedia";
  * stands in for a titled section, promote the title to a real heading with
  * `asChild` so it joins the page's heading hierarchy.
  *
+ * **Styling hooks.** `EmptyState.Title` emits no `data-*` attributes. Target
+ * it via `className` or the `p` element selector.
+ *
  * **`asChild` composition.** Renders the consumer's element instead of a
  * `<p>`, merging all props in via the {@link Slot} utility.
  *
+ * @extends HTMLParagraphElement
+ *
+ * @example Default paragraph headline
+ * ```tsx
+ * <EmptyState.Title>No results found</EmptyState.Title>
+ * ```
+ *
  * @example Promote to a heading
  * ```tsx
  * <EmptyState.Title asChild>
@@ -134,9 +181,14 @@ EmptyStateTitle.displayName = "EmptyStateTitle";
  * Keep it to guidance the user can act on; the actionable controls themselves
  * belong in {@link EmptyStateActions | `Actions`}.
  *
+ * **Styling hooks.** `EmptyState.Description` emits no `data-*` attributes.
+ * Target it via `className` or the `p` element selector.
+ *
  * **`asChild` composition.** Renders the consumer's element instead of a
  * `<p>`, merging all props in via the {@link Slot} utility.
  *
+ * @extends HTMLParagraphElement
+ *
  * @example
  * ```tsx
  * <EmptyState.Description>Try adjusting your filters.</EmptyState.Description>
@@ -167,9 +219,14 @@ EmptyStateDescription.displayName = "EmptyStateDescription";
  * {@link EmptyStateRoot | `Root`}'s live region, the control labels are
  * included when the empty state is announced.
  *
+ * **Styling hooks.** `EmptyState.Actions` emits no `data-*` attributes. Target
+ * it via `className` or the `div` element selector.
+ *
  * **`asChild` composition.** Renders the consumer's element instead of a
  * `<div>`, merging all props in via the {@link Slot} utility.
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <EmptyState.Actions>
@@ -227,7 +284,7 @@ export type EmptyStateCompound = typeof EmptyStateRoot & {
  * All sub-components are stateless and optional — compose only the parts a
  * given empty state needs.
  *
- * @example
+ * @example Full composition
  * ```tsx
  * import { EmptyState } from "@primitiv-ui/react";
  *
@@ -244,6 +301,19 @@ export type EmptyStateCompound = typeof EmptyStateRoot & {
  *   </EmptyState.Root>
  * )}
  * ```
+ *
+ * @example Minimal — title only
+ * ```tsx
+ * <EmptyState.Root>
+ *   <EmptyState.Title>No messages</EmptyState.Title>
+ * </EmptyState.Root>
+ * ```
+ *
+ * @see {@link EmptyStateRoot} for the live-region opt-out and `asChild` details.
+ * @see {@link EmptyStateMedia} for the `aria-hidden` default and opt-back-in pattern.
+ * @see {@link EmptyStateTitle} for the `<p>` default and heading promotion via `asChild`.
+ * @see {@link EmptyStateDescription} for secondary copy placement guidance.
+ * @see {@link EmptyStateActions} for grouping recovery controls.
  */
 const EmptyState: EmptyStateCompound = Object.assign(EmptyStateRoot, {
   Root: EmptyStateRoot,

package/src/EmptyState/__tests__/EmptyState.Actions.test.tsx

@@ -4,7 +4,7 @@ import { render, screen } from "@testing-library/react";
 describe("EmptyState.Actions component", () => {
   it("should render a div containing its children", () => {
     // Arrange
-    render(
+    const { container } = render(
       <EmptyState.Actions>
         <button>Clear filters</button>
       </EmptyState.Actions>,
@@ -13,11 +13,14 @@ describe("EmptyState.Actions component", () => {
     // Assert
     const button = screen.getByRole("button", { name: "Clear filters" });
     expect(button.parentElement?.tagName).toBe("DIV");
+    // The wrapping <div> is Actions' own render root (default is not asChild),
+    // not the test container.
+    expect((container.firstChild as HTMLElement).tagName).toBe("DIV");
   });
 
   it("should render the consumer element with asChild", () => {
     // Arrange
-    render(
+    const { container } = render(
       <EmptyState.Actions asChild>
         <nav>
           <button>Clear filters</button>
@@ -28,5 +31,7 @@ describe("EmptyState.Actions component", () => {
     // Assert
     const button = screen.getByRole("button", { name: "Clear filters" });
     expect(button.parentElement?.tagName).toBe("NAV");
+    // Slot renders the <nav> in place — no default <div> wrapper around it.
+    expect(container.querySelector("div")).toBeNull();
   });
 });

package/src/EmptyState/__tests__/EmptyState.Description.test.tsx

@@ -17,7 +17,7 @@ describe("EmptyState.Description component", () => {
 
   it("should render the consumer element with asChild", () => {
     // Arrange
-    render(
+    const { container } = render(
       <EmptyState.Description asChild>
         <span>Try adjusting your filters.</span>
       </EmptyState.Description>,
@@ -26,5 +26,7 @@ describe("EmptyState.Description component", () => {
     // Assert
     const description = screen.getByText("Try adjusting your filters.");
     expect(description.tagName).toBe("SPAN");
+    // Slot renders the child in place — no default <p> wrapper around it.
+    expect(container.querySelector("p")).toBeNull();
   });
 });

package/src/EmptyState/__tests__/EmptyState.Root.test.tsx

@@ -25,4 +25,14 @@ describe("EmptyState.Root component", () => {
     expect(root.tagName).toBe("SECTION");
     expect(root).toHaveTextContent("No projects yet");
   });
+
+  it("sets a displayName on the compound and each sub-component", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "EmptyState".
+    expect(EmptyState.displayName).toBe("EmptyState");
+    expect(EmptyState.Media.displayName).toBe("EmptyStateMedia");
+    expect(EmptyState.Title.displayName).toBe("EmptyStateTitle");
+    expect(EmptyState.Description.displayName).toBe("EmptyStateDescription");
+    expect(EmptyState.Actions.displayName).toBe("EmptyStateActions");
+  });
 });