@primitiv-ui/react 0.1.27 → 0.1.29

package/src/Breadcrumb/Breadcrumb.tsx

@@ -3,6 +3,7 @@ import type { ReactElement } from "react";
 import { Slot } from "../Slot/index.ts";
 
 import {
+  BreadcrumbEllipsisProps,
   BreadcrumbItemProps,
   BreadcrumbLinkProps,
   BreadcrumbListProps,
@@ -15,9 +16,18 @@ import {
  * The root of a Breadcrumb — a `<nav>` landmark that wraps the breadcrumb
  * trail.
  *
+ * Stateless: `Breadcrumb.Root` holds no context and derives no state — it
+ * is purely a semantic wrapper. All native `<nav>` attributes pass straight
+ * through to the DOM, so there is no controlled/uncontrolled shape to
+ * reason about.
+ *
  * The `<nav>` defaults to `aria-label="Breadcrumb"` so assistive technology
- * announces it as the breadcrumb navigation landmark. Override `aria-label`
- * if your product uses different terminology.
+ * announces it as the breadcrumb navigation landmark, distinguishing it
+ * from any other `<nav>` on the page (e.g. primary site navigation).
+ * Override `aria-label` if your product uses different terminology (e.g.
+ * `"You are here"`).
+ *
+ * @extends HTMLElement
  *
  * @example
  * ```tsx
@@ -25,6 +35,13 @@ import {
  *   <Breadcrumb.List>…</Breadcrumb.List>
  * </Breadcrumb.Root>
  * ```
+ *
+ * @example Custom accessible name
+ * ```tsx
+ * <Breadcrumb.Root aria-label="You are here">
+ *   <Breadcrumb.List>…</Breadcrumb.List>
+ * </Breadcrumb.Root>
+ * ```
  */
 export function BreadcrumbRoot({
   children,
@@ -37,16 +54,25 @@ export function BreadcrumbRoot({
   );
 }
 
-/** @internal */
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "Breadcrumb" at load, so the value is never observable.
+// The assignment stays because it declares `displayName` on
+// `typeof BreadcrumbRoot`, which TBreadcrumbCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 BreadcrumbRoot.displayName = "BreadcrumbRoot";
 
 /**
  * The ordered list of breadcrumb entries — renders an `<ol>`.
  *
  * An ordered list is the correct semantic: breadcrumb entries have a
- * meaningful sequence from the site root to the current page. Contains
+ * meaningful sequence from the site root to the current page (unlike a
+ * `<ul>`, whose items are unordered). Renders as a direct child of
+ * {@link BreadcrumbRoot | `Breadcrumb.Root`}'s `<nav>`, and contains
  * {@link BreadcrumbItem | `Breadcrumb.Item`}s interleaved with
- * {@link BreadcrumbSeparator | `Breadcrumb.Separator`}s.
+ * {@link BreadcrumbSeparator | `Breadcrumb.Separator`}s. Stateless — no
+ * context is read or provided.
+ *
+ * @extends HTMLOListElement
  *
  * @example
  * ```tsx
@@ -71,7 +97,13 @@ BreadcrumbList.displayName = "BreadcrumbList";
  * A single entry in the breadcrumb trail — renders an `<li>`.
  *
  * Wraps either a {@link BreadcrumbLink | `Breadcrumb.Link`} (an ancestor
- * page) or a {@link BreadcrumbPage | `Breadcrumb.Page`} (the current page).
+ * page) or a {@link BreadcrumbPage | `Breadcrumb.Page`} (the current page),
+ * as a child of {@link BreadcrumbList | `Breadcrumb.List`}'s `<ol>`.
+ * {@link BreadcrumbSeparator | `Breadcrumb.Separator`}s are siblings of
+ * `Breadcrumb.Item`, not nested inside it. Purely structural — no ARIA
+ * attributes or state of its own.
+ *
+ * @extends HTMLLIElement
  *
  * @example
  * ```tsx
@@ -93,12 +125,18 @@ BreadcrumbItem.displayName = "BreadcrumbItem";
 /**
  * A link to an ancestor page — renders an `<a>`.
  *
- * Use for every entry except the current page. Pass `href` (and any other
- * anchor attributes) directly.
+ * Use for every entry except the current page (the last entry should be a
+ * {@link BreadcrumbPage | `Breadcrumb.Page`} instead). Pass `href` (and any
+ * other anchor attributes) directly; nothing is inferred or defaulted.
+ *
+ * **`asChild` composition.** Pass `asChild` to render a consumer-supplied
+ * element — typically a routing library's `<Link>` — instead of the native
+ * `<a>`, with all of `Breadcrumb.Link`'s props (`href`, event handlers,
+ * `className`, `ref`, …) merged onto it via the {@link Slot} pattern. The
+ * child **must** be a single React element that accepts a `ref`; the
+ * native `<a>` is dropped entirely rather than wrapping the child.
  *
- * **`asChild` prop.** Pass `asChild` to render a consumer-supplied element —
- * typically a routing library's `<Link>` — with the breadcrumb link's props
- * merged in. The native `<a>` is dropped.
+ * @extends HTMLAnchorElement
  *
  * @example
  * ```tsx
@@ -129,9 +167,13 @@ BreadcrumbLink.displayName = "BreadcrumbLink";
 /**
  * The current page in the trail — renders a `<span aria-current="page">`.
  *
- * The last entry of a breadcrumb is the page the user is on, so it is not a
- * link. `aria-current="page"` tells assistive technology this entry
- * represents the current location.
+ * The last entry of a breadcrumb is the page the user is already on, so it
+ * is deliberately not a {@link BreadcrumbLink | `Breadcrumb.Link`} — a link
+ * to the current page is not a meaningful navigation target.
+ * `aria-current="page"` is fixed by the component (not overridable) and
+ * tells assistive technology this entry represents the current location.
+ *
+ * @extends HTMLSpanElement
  *
  * @example
  * ```tsx
@@ -159,12 +201,18 @@ BreadcrumbPage.displayName = "BreadcrumbPage";
  * `<li role="presentation" aria-hidden="true">`.
  *
  * The separator sits inside the `<ol>` as a sibling of the
- * {@link BreadcrumbItem | `Breadcrumb.Item`}s, but `role="presentation"`
- * removes it from the list semantics and `aria-hidden` hides it from the
- * accessibility tree — it is purely decorative.
+ * {@link BreadcrumbItem | `Breadcrumb.Item`}s (an `<ol>`'s valid children
+ * are all `<li>`s, so the separator is one too), but `role="presentation"`
+ * removes it from the list semantics — screen readers don't announce it as
+ * a list item — and `aria-hidden="true"` hides it from the accessibility
+ * tree entirely. Both attributes are fixed by the component and not
+ * overridable; it is purely decorative.
  *
  * Defaults to a `"/"` glyph; pass `children` to use a custom separator (an
- * icon, a chevron, etc.).
+ * icon, a chevron, `"›"`, etc.) — whatever is passed replaces the default
+ * entirely rather than being appended to it.
+ *
+ * @extends HTMLLIElement
  *
  * @example Default separator
  * ```tsx
@@ -190,6 +238,69 @@ export function BreadcrumbSeparator({
 /** @internal */
 BreadcrumbSeparator.displayName = "BreadcrumbSeparator";
 
+/**
+ * The decorative "more" glyph for an overflow trigger — renders a
+ * `<span role="presentation" aria-hidden="true">`.
+ *
+ * Purely a visual glyph, not itself the interactive element. Breadcrumb
+ * owns no truncation or menu-open state of its own — composing an overflow
+ * trigger means wrapping this glyph in a real interactive element (a
+ * `<button>`, or any {@link Slot}-compatible component) and reaching for
+ * {@link https://primitiv-ui.dev/docs/components/dropdown | `Dropdown`} for
+ * the menu itself. `Breadcrumb.Ellipsis` sits inside that button as its
+ * decorative content; the button's *accessible name* must come from
+ * elsewhere (visible text, or a
+ * {@link https://primitiv-ui.dev/docs/components/visually-hidden | `VisuallyHidden`}
+ * label) — `aria-hidden="true"` excludes this glyph from accessible-name
+ * computation entirely, exactly like {@link BreadcrumbSeparator}.
+ *
+ * Defaults to a `"…"` glyph; pass `children` to use a custom one (an icon,
+ * `"···"`, etc.) — whatever is passed replaces the default entirely rather
+ * than being appended to it.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Default glyph
+ * ```tsx
+ * <Breadcrumb.Ellipsis />
+ * ```
+ *
+ * @example Composed as an overflow trigger with Dropdown
+ * ```tsx
+ * <Breadcrumb.Item>
+ *   <Dropdown.Root>
+ *     <Dropdown.Trigger asChild>
+ *       <button type="button">
+ *         <Breadcrumb.Ellipsis />
+ *         <VisuallyHidden>Show hidden pages</VisuallyHidden>
+ *       </button>
+ *     </Dropdown.Trigger>
+ *     <Dropdown.Content>
+ *       <Dropdown.Item onSelect={() => navigate("/products")}>
+ *         Products
+ *       </Dropdown.Item>
+ *     </Dropdown.Content>
+ *   </Dropdown.Root>
+ * </Breadcrumb.Item>
+ * ```
+ */
+export function BreadcrumbEllipsis({
+  children = "…",
+  asChild = false,
+  ...rest
+}: BreadcrumbEllipsisProps): ReactElement {
+  const ellipsisProps = { ...rest, role: "presentation" as const, "aria-hidden": true as const };
+
+  if (asChild) {
+    return <Slot {...ellipsisProps}>{children}</Slot>;
+  }
+
+  return <span {...ellipsisProps}>{children}</span>;
+}
+
+/** @internal */
+BreadcrumbEllipsis.displayName = "BreadcrumbEllipsis";
+
 /** Type of the {@link Breadcrumb} compound: the root callable plus its attached sub-components. */
 export type TBreadcrumbCompound = typeof BreadcrumbRoot & {
   Root: typeof BreadcrumbRoot;
@@ -198,6 +309,7 @@ export type TBreadcrumbCompound = typeof BreadcrumbRoot & {
   Link: typeof BreadcrumbLink;
   Page: typeof BreadcrumbPage;
   Separator: typeof BreadcrumbSeparator;
+  Ellipsis: typeof BreadcrumbEllipsis;
 };
 
 /**
@@ -217,6 +329,7 @@ export type TBreadcrumbCompound = typeof BreadcrumbRoot & {
  * - {@link BreadcrumbLink | `Breadcrumb.Link`} — `<a>`, an ancestor-page link.
  * - {@link BreadcrumbPage | `Breadcrumb.Page`} — `<span aria-current="page">`, the current page.
  * - {@link BreadcrumbSeparator | `Breadcrumb.Separator`} — decorative `<li>` divider.
+ * - {@link BreadcrumbEllipsis | `Breadcrumb.Ellipsis`} — decorative `<span>` overflow-trigger glyph.
  *
  * @example Minimal usage
  * ```tsx
@@ -239,7 +352,11 @@ export type TBreadcrumbCompound = typeof BreadcrumbRoot & {
  * </Breadcrumb.Root>
  * ```
  *
+ * @see {@link BreadcrumbRoot} for the `aria-label` landmark default.
+ * @see {@link BreadcrumbLink} for the `asChild` router-link pattern.
+ * @see {@link BreadcrumbPage} for marking the current, non-linked entry.
  * @see {@link BreadcrumbSeparator} for customising the divider glyph.
+ * @see {@link BreadcrumbEllipsis} for composing an overflow trigger with `Dropdown`.
  */
 const BreadcrumbCompound: TBreadcrumbCompound = Object.assign(BreadcrumbRoot, {
   Root: BreadcrumbRoot,
@@ -248,6 +365,7 @@ const BreadcrumbCompound: TBreadcrumbCompound = Object.assign(BreadcrumbRoot, {
   Link: BreadcrumbLink,
   Page: BreadcrumbPage,
   Separator: BreadcrumbSeparator,
+  Ellipsis: BreadcrumbEllipsis,
 });
 
 /** @internal */

package/src/Breadcrumb/README.md

@@ -35,6 +35,7 @@ import { Breadcrumb } from "@primitiv-ui/react";
 | `Breadcrumb.Link` | `<a>` | — | yes |
 | `Breadcrumb.Page` | `<span>` | `aria-current="page"` | — |
 | `Breadcrumb.Separator` | `<li>` | `role="presentation"`, `aria-hidden="true"` | — |
+| `Breadcrumb.Ellipsis` | `<span>` | `role="presentation"`, `aria-hidden="true"` | yes |
 
 Every sub-component passes all of its element's native attributes straight
 through to the DOM.
@@ -79,6 +80,52 @@ It defaults to a `"/"` glyph. Pass `children` to use a custom separator:
 <Breadcrumb.Separator><ChevronRight /></Breadcrumb.Separator>
 ```
 
+## Overflow trigger
+
+`Breadcrumb` owns no truncation or menu-open state of its own — deciding
+which crumbs collapse is a styled-surface concern (see the registry `card`
+composite for the same "no data model in the primitive" philosophy). What
+the headless layer provides is `Breadcrumb.Ellipsis`: a purely decorative
+`"…"` glyph for the trigger's visual content.
+
+Compose it with [`Dropdown`](../Dropdown/README.md) to build the actual
+trigger — a real interactive element (a `<button>`, or anything
+`asChild`-compatible) wrapping the glyph, with the accessible name coming
+from visible text or a `VisuallyHidden` label rather than the glyph itself
+(`Breadcrumb.Ellipsis` is `aria-hidden`, exactly like `Breadcrumb.Separator`,
+so it never contributes to accessible-name computation):
+
+```tsx
+import { Breadcrumb, Dropdown, VisuallyHidden } from "@primitiv-ui/react";
+
+<Breadcrumb.Item>
+  <Dropdown.Root>
+    <Dropdown.Trigger asChild>
+      <button type="button">
+        <Breadcrumb.Ellipsis />
+        <VisuallyHidden>Show hidden pages</VisuallyHidden>
+      </button>
+    </Dropdown.Trigger>
+    <Dropdown.Content>
+      <Dropdown.Item onSelect={() => navigate("/products")}>
+        Products
+      </Dropdown.Item>
+      <Dropdown.Item onSelect={() => navigate("/products/electronics")}>
+        Electronics
+      </Dropdown.Item>
+    </Dropdown.Content>
+  </Dropdown.Root>
+</Breadcrumb.Item>;
+```
+
+`Breadcrumb.Ellipsis` defaults to a `"…"` glyph; pass `children` to use a
+custom one:
+
+```tsx
+<Breadcrumb.Ellipsis>···</Breadcrumb.Ellipsis>
+<Breadcrumb.Ellipsis><MoreIcon /></Breadcrumb.Ellipsis>
+```
+
 ## `asChild` composition
 
 `Breadcrumb.Link` accepts `asChild` so it can render a routing library's link

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

@@ -129,4 +129,15 @@ describe("Breadcrumb basic rendering", () => {
       "page",
     );
   });
+
+  it("sets a displayName on the compound and each sub-component", () => {
+    // Assert — an empty displayName would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "Breadcrumb".
+    expect(Breadcrumb.displayName).toBe("Breadcrumb");
+    expect(Breadcrumb.List.displayName).toBe("BreadcrumbList");
+    expect(Breadcrumb.Item.displayName).toBe("BreadcrumbItem");
+    expect(Breadcrumb.Link.displayName).toBe("BreadcrumbLink");
+    expect(Breadcrumb.Page.displayName).toBe("BreadcrumbPage");
+    expect(Breadcrumb.Separator.displayName).toBe("BreadcrumbSeparator");
+  });
 });

package/src/Breadcrumb/__tests__/Breadcrumb.ellipsis.test.tsx

@@ -0,0 +1,110 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Breadcrumb } from "../Breadcrumb";
+import { Dropdown } from "../../Dropdown/Dropdown";
+
+describe("Breadcrumb ellipsis", () => {
+  it("renders the Ellipsis as a decorative <span> with a default glyph", () => {
+    // Arrange & Act
+    render(<Breadcrumb.Ellipsis data-testid="ellipsis" />);
+    const ellipsis = screen.getByTestId("ellipsis");
+
+    // Assert — presentation + aria-hidden keep it out of the accessibility
+    // tree entirely, matching Breadcrumb.Separator's own convention: it is
+    // the interactive element composed AROUND it that must carry the
+    // accessible name, not this glyph.
+    expect(ellipsis.tagName).toBe("SPAN");
+    expect(ellipsis).toHaveAttribute("role", "presentation");
+    expect(ellipsis).toHaveAttribute("aria-hidden", "true");
+    expect(ellipsis).toHaveTextContent("…");
+  });
+
+  it("lets the consumer override the Ellipsis glyph", () => {
+    // Arrange & Act
+    render(
+      <Breadcrumb.Ellipsis data-testid="ellipsis">···</Breadcrumb.Ellipsis>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("ellipsis")).toHaveTextContent("···");
+  });
+
+  it("renders Breadcrumb.Ellipsis as the consumer element via asChild, with no wrapping <span>", () => {
+    // Arrange & Act
+    render(
+      <Breadcrumb.Ellipsis asChild>
+        <i data-testid="custom-ellipsis" />
+      </Breadcrumb.Ellipsis>,
+    );
+    const ellipsis = screen.getByTestId("custom-ellipsis");
+
+    // Assert — the native <span> is dropped entirely
+    expect(ellipsis.tagName).toBe("I");
+    expect(ellipsis.closest("span")).toBeNull();
+  });
+
+  it("merges Breadcrumb.Ellipsis props onto the asChild element", () => {
+    // Arrange & Act
+    render(
+      <Breadcrumb.Ellipsis asChild className="crumb-ellipsis">
+        <i data-testid="custom-ellipsis" />
+      </Breadcrumb.Ellipsis>,
+    );
+
+    // Assert — role/aria-hidden still land on the consumer's element
+    const ellipsis = screen.getByTestId("custom-ellipsis");
+    expect(ellipsis).toHaveClass("crumb-ellipsis");
+    expect(ellipsis).toHaveAttribute("role", "presentation");
+    expect(ellipsis).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("sets a displayName on Ellipsis", () => {
+    // Assert — an empty displayName would render it as anonymous in DevTools.
+    expect(Breadcrumb.Ellipsis.displayName).toBe("BreadcrumbEllipsis");
+  });
+
+  it("composes cleanly as Dropdown.Trigger's asChild child — the trigger owns the interactive element and accessible name, the Ellipsis is purely decorative inside it", async () => {
+    // Arrange — the documented composition pattern: the actual <button> is
+    // a sibling of the aria-hidden Ellipsis glyph, not the Ellipsis itself,
+    // so the button's accessible name comes from the visible text rather
+    // than being swallowed by the glyph's own aria-hidden.
+    const user = userEvent.setup();
+    render(
+      <Breadcrumb.Item>
+        <Dropdown.Root>
+          <Dropdown.Trigger asChild>
+            <button type="button" data-testid="overflow-trigger">
+              <Breadcrumb.Ellipsis />
+              <span>More</span>
+            </button>
+          </Dropdown.Trigger>
+          <Dropdown.Content>
+            <Dropdown.Item>Products</Dropdown.Item>
+          </Dropdown.Content>
+        </Dropdown.Root>
+      </Breadcrumb.Item>,
+    );
+    const trigger = screen.getByTestId("overflow-trigger");
+
+    // Assert — ARIA wiring from Dropdown lands on the real button, and its
+    // accessible name is the visible "More" text, not swallowed by the
+    // aria-hidden ellipsis glyph.
+    expect(trigger).toHaveAttribute("aria-haspopup", "menu");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(
+      screen.getByRole("button", { name: "More" }),
+    ).toBe(trigger);
+
+    // Act
+    await user.click(trigger);
+
+    // Assert — the menu opens with the hidden crumb as a real menu item.
+    // `hidden: true` because jsdom does not compute Popover-API visibility —
+    // the same convention every Dropdown test in this repo already uses.
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    expect(
+      screen.getByRole("menuitem", { name: "Products", hidden: true }),
+    ).toBeInTheDocument();
+  });
+});

package/src/Breadcrumb/types.ts

@@ -1,22 +1,88 @@
 import { ComponentProps } from "react";
 
-/** Props for {@link Breadcrumb.Root} — all `<nav>` attributes. */
+/**
+ * Props for {@link BreadcrumbRoot | `Breadcrumb.Root`} — all native `<nav>`
+ * attributes. `aria-label` defaults to `"Breadcrumb"` when omitted; pass it
+ * explicitly to override the accessible name announced to assistive
+ * technology.
+ *
+ * @extends HTMLElement
+ */
 export type BreadcrumbRootProps = ComponentProps<"nav">;
 
-/** Props for {@link Breadcrumb.List} — all `<ol>` attributes. */
+/**
+ * Props for {@link BreadcrumbList | `Breadcrumb.List`} — all native `<ol>`
+ * attributes. No props are added; content is
+ * {@link BreadcrumbItem | `Breadcrumb.Item`}s interleaved with
+ * {@link BreadcrumbSeparator | `Breadcrumb.Separator`}s.
+ *
+ * @extends HTMLOListElement
+ */
 export type BreadcrumbListProps = ComponentProps<"ol">;
 
-/** Props for {@link Breadcrumb.Item} — all `<li>` attributes. */
+/**
+ * Props for {@link BreadcrumbItem | `Breadcrumb.Item`} — all native `<li>`
+ * attributes. No props are added; wraps a single
+ * {@link BreadcrumbLink | `Breadcrumb.Link`} or
+ * {@link BreadcrumbPage | `Breadcrumb.Page`}.
+ *
+ * @extends HTMLLIElement
+ */
 export type BreadcrumbItemProps = ComponentProps<"li">;
 
-/** Props for {@link Breadcrumb.Link} — all `<a>` attributes plus `asChild`. */
+/**
+ * Props for {@link BreadcrumbLink | `Breadcrumb.Link`} — all native `<a>`
+ * attributes plus the `asChild` escape hatch.
+ *
+ * @extends HTMLAnchorElement
+ */
 export type BreadcrumbLinkProps = ComponentProps<"a"> & {
-  /** Render the consumer's own element instead of the native `<a>`. */
+  /**
+   * Renders the child element instead of a native `<a>`, merging all of
+   * `Breadcrumb.Link`'s props — `href`, event handlers, `className`,
+   * `ref` — onto it via {@link Slot}. Use for routing-library link
+   * components (e.g. React Router's `<Link>`) that need breadcrumb
+   * semantics. See the `asChild` example on {@link BreadcrumbLink}.
+   * @default false
+   */
   asChild?: boolean;
 };
 
-/** Props for {@link Breadcrumb.Page} — all `<span>` attributes. */
+/**
+ * Props for {@link BreadcrumbPage | `Breadcrumb.Page`} — all native
+ * `<span>` attributes. `aria-current="page"` is fixed by the component and
+ * cannot be overridden through these props.
+ *
+ * @extends HTMLSpanElement
+ */
 export type BreadcrumbPageProps = ComponentProps<"span">;
 
-/** Props for {@link Breadcrumb.Separator} — all `<li>` attributes. */
+/**
+ * Props for {@link BreadcrumbSeparator | `Breadcrumb.Separator`} — all
+ * native `<li>` attributes. `role="presentation"` and `aria-hidden="true"`
+ * are fixed by the component; `children` defaults to a `"/"` glyph when
+ * omitted (see {@link BreadcrumbSeparator}'s custom-separator example).
+ *
+ * @extends HTMLLIElement
+ */
 export type BreadcrumbSeparatorProps = ComponentProps<"li">;
+
+/**
+ * Props for {@link BreadcrumbEllipsis | `Breadcrumb.Ellipsis`} — all native
+ * `<span>` attributes plus the `asChild` escape hatch. `role="presentation"`
+ * and `aria-hidden="true"` are fixed by the component; `children` defaults
+ * to a `"…"` glyph when omitted (see {@link BreadcrumbEllipsis}'s
+ * custom-glyph example).
+ *
+ * @extends HTMLSpanElement
+ */
+export type BreadcrumbEllipsisProps = ComponentProps<"span"> & {
+  /**
+   * Renders the child element instead of a native `<span>`, merging all of
+   * `Breadcrumb.Ellipsis`'s props — `role`, `aria-hidden`, `className`,
+   * `ref` — onto it via {@link Slot}. See the `asChild` example on
+   * {@link BreadcrumbEllipsis}.
+   * @default false
+   */
+  asChild?: boolean;
+};

package/src/Button/Button.tsx

@@ -46,6 +46,8 @@ import { ButtonProps } from "./types";
  * </Button>
  * ```
  *
+ * @extends HTMLButtonElement
+ *
  * @example Text button
  * ```tsx
  * <Button onClick={handleSave}>Save</Button>

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

@@ -123,4 +123,10 @@ describe("Button basic rendering", () => {
     // Assert
     expect(onClick).toHaveBeenCalledTimes(1);
   });
+
+  it('sets displayName to "Button" for React DevTools and stack traces', () => {
+    // Assert — the component's identity is observable in DevTools and error
+    // output; an empty displayName would render it as an anonymous component.
+    expect(Button.displayName).toBe("Button");
+  });
 });

package/src/Button/types.ts

@@ -3,10 +3,31 @@ import { ComponentProps, ReactNode, Ref } from "react";
 /**
  * Props for {@link Button} — all native `<button>` attributes (with `type`
  * defaulting to `"button"`) plus the `asChild` escape hatch and a typed `ref`.
+ *
+ * @extends HTMLButtonElement
  */
 export type ButtonProps = Omit<ComponentProps<"button">, "type"> & {
+  /**
+   * The button's native `type` attribute, restricted to the three valid
+   * values. Defaults to `"button"` (not the DOM's own default of
+   * `"submit"`), so a `Button` placed inside a `<form>` never triggers an
+   * accidental submit unless set explicitly.
+   * @default "button"
+   */
   type?: "button" | "submit" | "reset";
+  /**
+   * Renders the child element instead of a native `<button>`, merging all
+   * props — aria-*, data-*, event handlers, ref — onto it via
+   * {@link Slot}. `type` is not forwarded in this mode; the child owns its
+   * own type semantics. See the `asChild` example on {@link Button}.
+   * @default false
+   */
   asChild?: boolean;
+  /**
+   * Forwarded to the underlying `HTMLButtonElement`, or — under
+   * `asChild` — merged onto the rendered child via {@link Slot}.
+   */
   ref?: Ref<HTMLButtonElement>;
+  /** Button content. Under `asChild`, becomes the single child element `Slot` merges props onto. */
   children?: ReactNode;
 };