@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Accordion/types.ts

@@ -1,30 +1,58 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 import { HeadingLevel } from "../types";
 
-/** Props shared by both control modes of `Accordion.Root`. */
-export type AccordionRootBaseProps = ComponentProps<"div"> & {
-  /** Allow more than one section to be expanded at a time. */
+/** Props shared by both control modes of `Accordion.Root`. `dir` is `Omit`ted
+ * from the native `<div>` props because it is narrowed from the DOM's
+ * `string` to {@link AccordionReadingDirection}; without the `Omit` the
+ * docs-data extractor picks the wider native declaration and silently drops
+ * the narrowed type and its JSDoc (§1.16). */
+export type AccordionRootBaseProps = Omit<
+  ComponentProps<"div">,
+  "dir" | "defaultValue"
+> & {
+  /** Allow more than one section to be expanded at a time. When `false`,
+   * opening an item collapses whichever item was previously open.
+   * @default false */
   multiple?: boolean;
-  /** Layout axis, controlling arrow-key navigation. Defaults to `"vertical"`. */
+  /** Layout axis, controlling arrow-key navigation: `"vertical"` binds
+   * ArrowUp/ArrowDown, `"horizontal"` binds ArrowLeft/ArrowRight. Surfaces as
+   * `data-orientation` on the root.
+   * @default "vertical" */
   orientation?: "vertical" | "horizontal";
-  /** Reading direction, controlling left/right key semantics. */
+  /** Reading direction; see {@link AccordionReadingDirection}. In `"rtl"` the
+   * horizontal arrow keys are mirrored. Also set as the container's `dir`
+   * attribute. Inherited from the nearest {@link DirectionProvider} when
+   * omitted, falling back to `"ltr"`. */
   dir?: AccordionReadingDirection;
 };
 
-/** `Accordion.Root` props for the uncontrolled (self-managed) expanded state. */
+/** `Accordion.Root` props for the uncontrolled (self-managed) expanded state.
+ * The component owns and updates the expanded set internally, and — matching
+ * the Tabs contract — does **not** call `onValueChange` in this mode. */
 export type AccordionRootUncontrolledProps = AccordionRootBaseProps & {
-  /** Initially expanded item value when uncontrolled. */
+  /** Value of the item expanded on first render. A single value even in
+   * `multiple` mode — uncontrolled accordions can seed only one open item;
+   * pass controlled {@link AccordionRootControlledProps.value | `value`} to
+   * start with several. Omit to start with everything collapsed. */
   defaultValue?: string;
+  /** Forbidden in uncontrolled mode — use `defaultValue`. */
   value?: never;
+  /** Forbidden in uncontrolled mode. */
   onValueChange?: never;
 };
 
-/** `Accordion.Root` props for the controlled expanded state. */
+/** `Accordion.Root` props for the controlled expanded state — the parent owns
+ * the expanded set and the component defers every change back through the
+ * callback. */
 export type AccordionRootControlledProps = AccordionRootBaseProps & {
+  /** Forbidden in controlled mode — use `value`. */
   defaultValue?: never;
-  /** Controlled set of expanded item values. */
+  /** The full set of currently expanded item values. Must be kept in sync by
+   * the parent via `onValueChange`. In single (`multiple={false}`) mode this
+   * holds at most one value. */
   value: string[];
-  /** Called whenever the set of expanded item values changes. */
+  /** Called with the complete next array of expanded values whenever the user
+   * toggles an item. */
   onValueChange: (values: string[]) => void;
 };
 
@@ -38,20 +66,33 @@ export type AccordionRootProps =
 
 /** Props for `Accordion.Item` — a single collapsible section. */
 export type AccordionItemProps = ComponentProps<"div"> & {
-  /** Section contents — typically a `Header` + `Content` pair. */
+  /** Section contents — typically an {@link AccordionHeaderProps | `Accordion.Header`}
+   * + {@link AccordionContentProps | `Accordion.Content`} pair. */
   children: ReactNode;
-  /** Stable value identifying the item; auto-generated via `useId()` when omitted. */
-  value?: string; // Optional - if not provided, useId() will generate one
+  /** Stable identifier matched against the root's expanded set (and against
+   * `value` / `defaultValue`). When omitted, a stable id is generated via
+   * `useId()` — fine for anonymous items whose state is never driven from
+   * outside. */
+  value?: string;
 };
 
 /** Props for `Accordion.Trigger` — the button that toggles a section. */
 export type AccordionTriggerProps<T extends HTMLElement = HTMLButtonElement> =
   Omit<ComponentProps<"button">, "disabled" | "ref"> & {
-    /** Trigger label / contents. */
+    /** Trigger label / contents — the visible section heading text, plus an
+     * optional {@link AccordionTriggerIconProps | `Accordion.TriggerIcon`}. */
     children: ReactNode;
-    /** Disable the trigger, removing it from keyboard navigation. */
+    /** Disable the trigger. Rendered as `aria-disabled` / `data-disabled`
+     * rather than the native `disabled` attribute, so the button stays
+     * focusable (discoverable by keyboard) but is excluded from arrow-key
+     * navigation and cannot be activated.
+     * @default false */
     disabled?: boolean;
-    /** Render into the consumer's own element instead of a `<button>`. */
+    /** Render the consumer's own element instead of a `<button>`, merging all
+     * accordion ARIA attributes, event handlers, and the ref onto it via the
+     * {@link Slot} pattern. When combined with `disabled`, `role="button"` is
+     * injected so `aria-disabled` is valid on non-button children.
+     * @default false */
     asChild?: boolean;
     /** Ref to the rendered element. Defaults to `HTMLButtonElement`; when using
      * `asChild`, specify the child's element type (e.g. `HTMLAnchorElement`). */
@@ -60,23 +101,33 @@ export type AccordionTriggerProps<T extends HTMLElement = HTMLButtonElement> =
 
 /** Props for `Accordion.Header` — the heading wrapping a trigger. */
 export type AccordionHeaderProps = ComponentProps<"h3"> & {
-  /** Header contents — typically an `Accordion.Trigger`. */
+  /** Header contents — typically an
+   * {@link AccordionTriggerProps | `Accordion.Trigger`}. */
   children: ReactNode;
-  /** Heading level rendered (`h1`–`h6`). Defaults to `3`. */
+  /** Heading level to render (`h1`–`h6`). Choose the level that fits the
+   * surrounding document outline — the WAI-ARIA Accordion pattern requires
+   * each trigger to be wrapped in a heading at the right level.
+   * @default 3 */
   level?: HeadingLevel;
 };
 
 /** Props for `Accordion.Content` — the collapsible panel. */
 export type AccordionContentProps = ComponentProps<"div"> & {
-  /** Panel contents. */
+  /** Panel contents, revealed when the matching trigger is expanded. */
   children: ReactNode;
-  /** Keep the panel mounted even while collapsed. */
+  /** Keep the panel mounted in the DOM even while collapsed (instead of
+   * removing it from view with the `hidden` attribute), so CSS open/close
+   * transitions can run. While closed it receives `aria-hidden="true"` so
+   * assistive tech still ignores it; drive visibility yourself via
+   * `[data-state="closed"]`.
+   * @default false */
   forceMount?: boolean;
 };
 
 /** Props for `Accordion.TriggerIcon` — a decorative open/closed indicator. */
 export type AccordionTriggerIconProps = ComponentProps<"span"> & {
-  /** Icon contents. */
+  /** Icon contents — an inline `<svg>` or any icon component. Rendered inside
+   * an `aria-hidden` `<span>` carrying a `data-state` open/close hook. */
   children: ReactNode;
 };
 

package/src/Alert/Alert.tsx

@@ -4,7 +4,8 @@ import { Slot } from "../Slot/index.ts";
 import { AlertProps } from "./types";
 
 /**
- * An assertive live region for high-priority, time-sensitive messages.
+ * An assertive live region for high-priority, time-sensitive messages,
+ * implementing the WAI-ARIA `alert` role.
  *
  * Renders a `<div role="alert">`. The `alert` role carries an implicit
  * `aria-live="assertive"` and `aria-atomic="true"`, so assistive
@@ -12,20 +13,48 @@ import { AlertProps } from "./types";
  * appears — use it for errors and other content the user must see now.
  * For non-urgent updates, reach for `Status` instead.
  *
- * Render the `Alert` conditionally: the live region announces content
- * that appears *after* it is already in the DOM. Mounting an `Alert`
- * that already contains its message may not be announced reliably.
+ * **Announce on appearance.** A live region announces content that
+ * changes *after* the region is already in the DOM. Render `Alert`
+ * conditionally so the message appears into an already-mounted tree:
+ *
+ * ```tsx
+ * {submitError && <Alert>{submitError}</Alert>}
+ * ```
+ *
+ * Mounting an `Alert` that already contains its message may not be
+ * announced reliably by all assistive technology.
+ *
+ * **Styling hooks.** The component emits no `data-*` attributes — it
+ * carries no internal state. Target the rendered element directly via
+ * `className` or the `[role="alert"]` selector.
  *
  * **`asChild` composition.** Renders the consumer's element instead of
- * a `<div>`, merging `role="alert"` and all other props in via the
- * {@link Slot} utility.
+ * a `<div>`, merging `role="alert"` and all other props onto it via the
+ * {@link Slot} utility. Useful when you already have a semantic element
+ * (e.g. `<section>`, `<aside>`) that should also function as an ARIA
+ * alert.
+ *
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLDivElement` (or, under `asChild`, the consumer's element):
+ *
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null);
+ * <Alert ref={ref}>Something went wrong.</Alert>
+ * ```
+ *
+ * @extends HTMLDivElement
  *
  * @example Form error
  * ```tsx
  * {error && <Alert>{error}</Alert>}
  * ```
  *
- * @example asChild — keep semantic markup
+ * @example Inline styling via className
+ * ```tsx
+ * <Alert className="alert alert--error">Payment declined.</Alert>
+ * ```
+ *
+ * @example asChild — apply the alert role to a semantic element
  * ```tsx
  * <Alert asChild>
  *   <section>Upload failed — try again.</section>

package/src/Alert/__tests__/Alert.test.tsx

@@ -25,4 +25,9 @@ describe("Alert component", () => {
     expect(alert.tagName).toBe("SECTION");
     expect(alert).toHaveTextContent("Upload failed");
   });
+
+  it('sets displayName to "Alert" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(Alert.displayName).toBe("Alert");
+  });
 });

package/src/Alert/types.ts

@@ -1,6 +1,22 @@
-import { ComponentProps } from "react";
+import { ComponentProps, ReactNode } from "react";
 
-/** Props for the `Alert` — a live-region `<div role="alert">`; native `<div>` props plus `asChild`. */
+/**
+ * Props for {@link Alert} — all native `<div>` attributes plus the `asChild`
+ * escape hatch.
+ *
+ * The `role` attribute is managed internally and set to `"alert"` regardless
+ * of what is passed; there is no need to supply it.
+ */
 export type AlertProps = ComponentProps<"div"> & {
+  /**
+   * Renders the child element instead of a native `<div>`, merging
+   * `role="alert"` and all other props onto it via {@link Slot}.
+   * Useful when you already have a semantic element (e.g. `<section>`,
+   * `<aside>`) that should also function as an ARIA alert.
+   * @default false
+   */
   asChild?: boolean;
+  /** The live-region content. Injected after the region is already in the
+   * DOM so that assistive technology announces the change. */
+  children?: ReactNode;
 };

package/src/Avatar/Avatar.tsx

@@ -18,10 +18,37 @@ import {
  * {@link Avatar.Image | `Avatar.Image`} and
  * {@link Avatar.Fallback | `Avatar.Fallback`}.
  *
+ * **Load-state model.** Root holds the single source of truth for the image's
+ * {@link AvatarImageLoadingStatus} in internal state, starting at `"idle"`.
+ * The child `Avatar.Image` reports transitions (`"loading"` → `"loaded"` /
+ * `"error"`) up through context; `Avatar.Fallback` reads that status to decide
+ * whether to render. There is no controlled/uncontrolled split — status is
+ * always driven by the image's own load lifecycle.
+ *
  * **Styling hooks.** `data-status="idle" | "loading" | "loaded" | "error"`.
  *
- * **`asChild` prop.** Pass `asChild` to render the consumer's own element as
- * the container, with the `data-status` hook merged in.
+ * **`asChild` composition.** Pass `asChild` to render the consumer's own
+ * element as the container instead of the native `<span>`, with the
+ * `data-status` hook merged in via the {@link Slot} pattern.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Image with a generated-initials fallback
+ * ```tsx
+ * <Avatar.Root>
+ *   <Avatar.Image src={user.avatarUrl} alt={user.name} />
+ *   <Avatar.Fallback>{initials(user.name)}</Avatar.Fallback>
+ * </Avatar.Root>
+ * ```
+ *
+ * @example Fallback only (no image source)
+ * ```tsx
+ * <Avatar.Root>
+ *   <Avatar.Fallback>
+ *     <UserIcon aria-hidden />
+ *   </Avatar.Fallback>
+ * </Avatar.Root>
+ * ```
  */
 export function AvatarRoot({
   asChild = false,
@@ -45,19 +72,39 @@ export function AvatarRoot({
   );
 }
 
-/** @internal */
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "Avatar" at load, so the value is never observable. The
+// assignment stays because it declares `displayName` on `typeof AvatarRoot`,
+// which TAvatarCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 AvatarRoot.displayName = "AvatarRoot";
 
 /**
  * The image of an Avatar — an `<img>` that reports its load lifecycle to the
  * parent {@link Avatar.Root}.
  *
+ * **Cache-hit safe.** The internal callback ref inspects `naturalWidth` on
+ * attach, so an image already decoded in the browser cache (whose `load` event
+ * fires before React can bind `onLoad`) is still reported as `"loaded"`. Every
+ * other image reports `"loading"` until its `load` / `error` event resolves it.
+ *
  * **Styling hooks.** `data-status` mirrors the root's status. The image stays
- * mounted on error; hide a broken image with CSS, e.g.
+ * mounted on error rather than unmounting; hide a broken image with CSS, e.g.
  * `img:not([data-status="loaded"]) { display: none }`.
  *
- * **`asChild` prop.** Pass `asChild` to render the consumer's own `<img>`,
- * with the load handlers, ref, and `data-status` hook merged in.
+ * **`asChild` composition.** Pass `asChild` to render the consumer's own
+ * `<img>`, with the load handlers, ref, and `data-status` hook merged in via
+ * the {@link Slot} pattern.
+ *
+ * @extends HTMLImageElement
+ *
+ * @example
+ * ```tsx
+ * <Avatar.Root>
+ *   <Avatar.Image src="/ada.png" alt="Ada Lovelace" />
+ *   <Avatar.Fallback>AL</Avatar.Fallback>
+ * </Avatar.Root>
+ * ```
  *
  * @throws if rendered outside an `Avatar.Root`.
  */
@@ -92,14 +139,28 @@ AvatarImage.displayName = "AvatarImage";
 
 /**
  * The fallback of an Avatar — a `<span>` shown while the parent
- * {@link Avatar.Root}'s image is anything other than `"loaded"` (missing,
- * loading, or failed). Once the image loads, the fallback unmounts.
+ * {@link Avatar.Root}'s image is anything other than `"loaded"` (i.e. `"idle"`,
+ * `"loading"`, or `"error"`). Once the image loads, the fallback returns `null`
+ * and unmounts. Its children are the consumer's stand-in content — typically
+ * generated initials or a placeholder silhouette icon.
+ *
+ * Pass {@link AvatarFallbackProps.delayMs | `delayMs`} to withhold the fallback
+ * for that many milliseconds after mount, avoiding a flash of fallback content
+ * when the image loads quickly. Omit it to render the fallback straight away.
  *
- * Pass `delayMs` to withhold the fallback for that many milliseconds after
- * mount, avoiding a flash of fallback content when the image loads quickly.
+ * **`asChild` composition.** Pass `asChild` to render the consumer's own
+ * element as the fallback instead of the native `<span>`, with the
+ * `data-status` hook merged in via the {@link Slot} pattern.
  *
- * **`asChild` prop.** Pass `asChild` to render the consumer's own element as
- * the fallback, with the `data-status` hook merged in.
+ * @extends HTMLSpanElement
+ *
+ * @example Deferred to avoid a flash on fast connections
+ * ```tsx
+ * <Avatar.Root>
+ *   <Avatar.Image src={user.avatarUrl} alt={user.name} />
+ *   <Avatar.Fallback delayMs={600}>{initials(user.name)}</Avatar.Fallback>
+ * </Avatar.Root>
+ * ```
  *
  * @throws if rendered outside an `Avatar.Root`.
  */
@@ -113,6 +174,9 @@ export function AvatarFallback({
   const [delayElapsed, setDelayElapsed] = useState(delayMs === undefined);
 
   useEffect(() => {
+    // Stryker disable next-line all: when delayMs is undefined, delayElapsed is
+    // already initialised true, so skipping vs. running this branch only sets a
+    // timer whose setDelayElapsed(true) is a no-op — no observable difference.
     if (delayMs === undefined) {
       return;
     }
@@ -147,9 +211,29 @@ export type TAvatarCompound = typeof AvatarRoot & {
  * Headless, accessible **Avatar** — a compound component for a user image
  * with a graceful fallback. Zero styles ship.
  *
- * - {@link Avatar.Root | `Avatar.Root`} — container, owns loading status.
- * - {@link Avatar.Image | `Avatar.Image`} — the `<img>`, reports its status.
- * - {@link Avatar.Fallback | `Avatar.Fallback`} — shown until the image loads.
+ * `Avatar` is both callable (an alias of {@link AvatarRoot | `Avatar.Root`})
+ * and carries its sub-components as static properties.
+ *
+ * - {@link Avatar.Root | `Avatar.Root`} — `<span>` container, owns the image
+ *   loading status, context provider.
+ * - {@link Avatar.Image | `Avatar.Image`} — the `<img>`, reports its load
+ *   status (cache-hit safe).
+ * - {@link Avatar.Fallback | `Avatar.Fallback`} — stand-in content shown until
+ *   the image loads, with an optional `delayMs` anti-flash guard.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Avatar } from "@primitiv-ui/react";
+ *
+ * <Avatar.Root>
+ *   <Avatar.Image src={user.avatarUrl} alt={user.name} />
+ *   <Avatar.Fallback>{initials(user.name)}</Avatar.Fallback>
+ * </Avatar.Root>
+ * ```
+ *
+ * @see {@link AvatarRoot} for the load-state model and `asChild`.
+ * @see {@link AvatarImage} for cache-hit handling and error behaviour.
+ * @see {@link AvatarFallback} for the `delayMs` anti-flash guard.
  */
 const AvatarCompound: TAvatarCompound = Object.assign(AvatarRoot, {
   Root: AvatarRoot,

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

@@ -1,6 +1,7 @@
 import { render, screen } from "@testing-library/react";
 
 import { Avatar } from "../Avatar";
+import { AvatarContext } from "../AvatarContext";
 
 describe("Avatar basic rendering", () => {
   it("renders Avatar.Root as a <span>", () => {
@@ -11,4 +12,13 @@ describe("Avatar basic rendering", () => {
     // Assert
     expect(root.tagName).toBe("SPAN");
   });
+
+  it("sets a displayName on the compound, sub-components, and context", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // Root aliases the compound (Object.assign), so its name is "Avatar".
+    expect(Avatar.displayName).toBe("Avatar");
+    expect(Avatar.Image.displayName).toBe("AvatarImage");
+    expect(Avatar.Fallback.displayName).toBe("AvatarFallback");
+    expect(AvatarContext.displayName).toBe("AvatarContext");
+  });
 });

package/src/Avatar/__tests__/Avatar.fallback.test.tsx

@@ -71,5 +71,35 @@ describe("Avatar fallback", () => {
       // Assert — shown once the delay elapses
       expect(screen.getByText("AL")).toBeInTheDocument();
     });
+
+    it("resets the timer when delayMs changes", () => {
+      // Arrange — start a 300ms delay...
+      const { rerender } = render(
+        <Avatar.Root>
+          <Avatar.Fallback delayMs={300}>AL</Avatar.Fallback>
+        </Avatar.Root>,
+      );
+
+      // Act — ...then extend it to 1000ms before the first delay elapses. The
+      // effect must clear the old timer and start a new one; a stale timer (no
+      // cleanup) or a frozen dependency ([] deps) would fire at 300ms.
+      rerender(
+        <Avatar.Root>
+          <Avatar.Fallback delayMs={1000}>AL</Avatar.Fallback>
+        </Avatar.Root>,
+      );
+      act(() => {
+        vi.advanceTimersByTime(300);
+      });
+
+      // Assert — still withheld at 300ms because the delay was reset to 1000ms
+      expect(screen.queryByText("AL")).not.toBeInTheDocument();
+
+      // ...and shown once the new delay elapses
+      act(() => {
+        vi.advanceTimersByTime(700);
+      });
+      expect(screen.getByText("AL")).toBeInTheDocument();
+    });
   });
 });

package/src/Avatar/__tests__/Avatar.image-loading.test.tsx

@@ -21,6 +21,41 @@ describe("Avatar image loading", () => {
     expect(img).toHaveAttribute("src", "/ada.png");
   });
 
+  it('reports data-status="loading" on mount before any load event', () => {
+    // Arrange & Act — jsdom images report naturalWidth 0, so the attach-time
+    // inspection sees no cache hit and reports "loading" until load/error.
+    render(
+      <Avatar.Root data-testid="root">
+        <Avatar.Image src="/ada.png" alt="Ada" data-testid="img" />
+      </Avatar.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("root")).toHaveAttribute("data-status", "loading");
+    expect(screen.getByTestId("img")).toHaveAttribute("data-status", "loading");
+  });
+
+  it("tolerates the image leaving the tree (callback ref receives null)", () => {
+    // Arrange — an Avatar whose Image can be swapped out for a Fallback.
+    const { rerender } = render(
+      <Avatar.Root data-testid="root">
+        <Avatar.Image src="/ada.png" alt="Ada" />
+      </Avatar.Root>,
+    );
+
+    // Act — removing the Image detaches its callback ref, calling it with null.
+    // Without the `img === null` guard this dereferences null.naturalWidth and
+    // throws during the commit, failing the render.
+    rerender(
+      <Avatar.Root data-testid="root">
+        <Avatar.Fallback>AL</Avatar.Fallback>
+      </Avatar.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("AL")).toBeInTheDocument();
+  });
+
   it('reports data-status="loaded" on the Root and Image once the image loads', () => {
     // Arrange
     render(

package/src/Avatar/hooks/useAvatarImage.ts

@@ -24,16 +24,32 @@ export function useAvatarImage(
 
   const ref = useCallback(
     (img: HTMLImageElement | null) => {
+      // The `img === null` guard is load-bearing: without it, detaching the ref
+      // dereferences null.naturalWidth and throws (see the "leaving the tree"
+      // test, which kills the BlockStatement twin of this line). Stryker's
+      // vitest runner does not reliably attribute that React commit-phase throw
+      // for the ConditionalExpression variant, so it can't be scored despite
+      // being covered and defended — a runner limitation, not an equivalent
+      // mutant. The condition->true variant is killed by the "loading on mount"
+      // test.
+      // Stryker disable next-line ConditionalExpression
       if (img === null || reported.current) {
         return;
       }
       reported.current = true;
       setStatus(img.naturalWidth > 0 ? "loaded" : "loading");
     },
+    // Stryker disable next-line ArrayDeclaration: setStatus is a useState
+    // setter with a stable identity, so [] and [setStatus] recreate the
+    // callback identically — the dependency is behaviourally inert (equivalent).
     [setStatus],
   );
 
+  // Stryker disable next-line ArrayDeclaration: setStatus is a stable useState
+  // setter, so the dependency array cannot change the callback — equivalent.
   const onLoad = useCallback(() => setStatus("loaded"), [setStatus]);
+  // Stryker disable next-line ArrayDeclaration: setStatus is a stable useState
+  // setter, so the dependency array cannot change the callback — equivalent.
   const onError = useCallback(() => setStatus("error"), [setStatus]);
 
   return { ref, onLoad, onError };

package/src/Avatar/types.ts

@@ -16,7 +16,11 @@ export type AvatarImageLoadingStatus = "idle" | "loading" | "loaded" | "error";
  * Props for {@link Avatar.Root} — all `<span>` attributes plus `asChild`.
  */
 export type AvatarRootProps = ComponentProps<"span"> & {
-  /** Render the consumer's own element instead of the native `<span>`. */
+  /**
+   * Render the consumer's own element instead of the native `<span>`, merging
+   * the `data-status` hook onto it via {@link Slot}.
+   * @default false
+   */
   asChild?: boolean;
 };
 
@@ -24,7 +28,11 @@ export type AvatarRootProps = ComponentProps<"span"> & {
  * Props for {@link Avatar.Image} — all `<img>` attributes plus `asChild`.
  */
 export type AvatarImageProps = ComponentProps<"img"> & {
-  /** Render the consumer's own element instead of the native `<img>`. */
+  /**
+   * Render the consumer's own `<img>` instead of the native one, merging the
+   * load handlers, ref, and `data-status` hook onto it via {@link Slot}.
+   * @default false
+   */
   asChild?: boolean;
 };
 
@@ -39,6 +47,10 @@ export type AvatarFallbackProps = ComponentProps<"span"> & {
    * loads almost immediately. Omit to render the fallback straight away.
    */
   delayMs?: number;
-  /** Render the consumer's own element instead of the native `<span>`. */
+  /**
+   * Render the consumer's own element instead of the native `<span>`, merging
+   * the `data-status` hook onto it via {@link Slot}.
+   * @default false
+   */
   asChild?: boolean;
 };