@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/Alert/Alert.js

@@ -0,0 +1,70 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Slot } from "../Slot/index.js";
+/**
+ * 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
+ * technology interrupts the user to announce the message as soon as it
+ * appears — use it for errors and other content the user must see now.
+ * For non-urgent updates, reach for `Status` instead.
+ *
+ * **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 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 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>
+ * </Alert>
+ * ```
+ */
+export function Alert({ asChild = false, children, ...rest }) {
+    const rootProps = { role: "alert", ...rest };
+    if (asChild) {
+        return _jsx(Slot, { ...rootProps, children: children });
+    }
+    return _jsx("div", { ...rootProps, children: children });
+}
+/** @internal */
+Alert.displayName = "Alert";

package/dist/Alert/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Alert.js";
+export * from "./types.js";

package/dist/Alert/index.js

@@ -0,0 +1,2 @@
+export * from "./Alert.js";
+export * from "./types.js";

package/dist/Alert/types.d.ts

@@ -0,0 +1,21 @@
+import { ComponentProps, ReactNode } from "react";
+/**
+ * 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/dist/Alert/types.js

@@ -0,0 +1 @@
+export {};

package/dist/Avatar/Avatar.d.ts

@@ -0,0 +1,144 @@
+import type { ReactElement } from "react";
+import { AvatarFallbackProps, AvatarImageProps, AvatarRootProps } from "./types.js";
+/**
+ * The root of an Avatar — a `<span>` container that owns the image loading
+ * status and provides {@link AvatarContext} to a descendant
+ * {@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` 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 declare function AvatarRoot({ asChild, children, ...rest }: AvatarRootProps): ReactElement;
+export declare namespace AvatarRoot {
+    var displayName: string;
+}
+/**
+ * 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 rather than unmounting; hide a broken image with CSS, e.g.
+ * `img:not([data-status="loaded"]) { display: none }`.
+ *
+ * **`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`.
+ */
+export declare function AvatarImage({ asChild, children, ...rest }: AvatarImageProps): ReactElement;
+export declare namespace AvatarImage {
+    var displayName: string;
+}
+/**
+ * The fallback of an Avatar — a `<span>` shown while the parent
+ * {@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.
+ *
+ * **`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.
+ *
+ * @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`.
+ */
+export declare function AvatarFallback({ delayMs, asChild, children, ...rest }: AvatarFallbackProps): ReactElement | null;
+export declare namespace AvatarFallback {
+    var displayName: string;
+}
+/** Static-property shape of the compound {@link Avatar} export: the callable {@link AvatarRoot} plus its namespaced sub-components. */
+export type TAvatarCompound = typeof AvatarRoot & {
+    Root: typeof AvatarRoot;
+    Image: typeof AvatarImage;
+    Fallback: typeof AvatarFallback;
+};
+/**
+ * Headless, accessible **Avatar** — a compound component for a user image
+ * with a graceful fallback. Zero styles ship.
+ *
+ * `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.
+ */
+declare const AvatarCompound: TAvatarCompound;
+export { AvatarCompound as Avatar };

package/dist/Avatar/Avatar.js

@@ -0,0 +1,187 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from "react";
+import { Slot } from "../Slot/index.js";
+import { AvatarContext } from "./AvatarContext.js";
+import { useAvatarContext, useAvatarImage } from "./hooks/index.js";
+/**
+ * The root of an Avatar — a `<span>` container that owns the image loading
+ * status and provides {@link AvatarContext} to a descendant
+ * {@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` 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, children, ...rest }) {
+    const [status, setStatus] = useState("idle");
+    const contextValue = useMemo(() => ({ status, setStatus }), [status]);
+    const rootProps = { ...rest, "data-status": status };
+    return (_jsx(AvatarContext.Provider, { value: contextValue, children: asChild ? (_jsx(Slot, { ...rootProps, children: children })) : (_jsx("span", { ...rootProps, children: children })) }));
+}
+// 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 rather than unmounting; hide a broken image with CSS, e.g.
+ * `img:not([data-status="loaded"]) { display: none }`.
+ *
+ * **`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`.
+ */
+export function AvatarImage({ asChild = false, children, ...rest }) {
+    const { status, setStatus } = useAvatarContext();
+    const { ref, onLoad, onError } = useAvatarImage(setStatus);
+    const imageProps = {
+        ...rest,
+        "data-status": status,
+        onLoad,
+        onError,
+    };
+    if (asChild) {
+        return (_jsx(Slot, { ...imageProps, ref: ref, children: children }));
+    }
+    return _jsx("img", { ...imageProps, ref: ref });
+}
+/** @internal */
+AvatarImage.displayName = "AvatarImage";
+/**
+ * The fallback of an Avatar — a `<span>` shown while the parent
+ * {@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.
+ *
+ * **`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.
+ *
+ * @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`.
+ */
+export function AvatarFallback({ delayMs, asChild = false, children, ...rest }) {
+    const { status } = useAvatarContext();
+    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;
+        }
+        const timer = window.setTimeout(() => setDelayElapsed(true), delayMs);
+        return () => window.clearTimeout(timer);
+    }, [delayMs]);
+    if (status === "loaded" || !delayElapsed) {
+        return null;
+    }
+    const fallbackProps = { ...rest, "data-status": status };
+    if (asChild) {
+        return _jsx(Slot, { ...fallbackProps, children: children });
+    }
+    return _jsx("span", { ...fallbackProps, children: children });
+}
+/** @internal */
+AvatarFallback.displayName = "AvatarFallback";
+/**
+ * Headless, accessible **Avatar** — a compound component for a user image
+ * with a graceful fallback. Zero styles ship.
+ *
+ * `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 = Object.assign(AvatarRoot, {
+    Root: AvatarRoot,
+    Image: AvatarImage,
+    Fallback: AvatarFallback,
+});
+AvatarCompound.displayName = "Avatar";
+export { AvatarCompound as Avatar };

package/dist/Avatar/AvatarContext.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from "react";
+import { AvatarImageLoadingStatus } from "./types.js";
+/**
+ * Value shared by {@link Avatar.Root} with its descendant
+ * {@link Avatar.Image} and {@link Avatar.Fallback}.
+ */
+export type AvatarContextValue = {
+    /** Current image loading status, owned by the root. */
+    status: AvatarImageLoadingStatus;
+    /** Reports a new loading status up to the root. */
+    setStatus: (status: AvatarImageLoadingStatus) => void;
+};
+/** React context carrying the {@link AvatarContextValue} shared by the avatar's sub-components. */
+export declare const AvatarContext: Context<AvatarContextValue | null>;
+/** Hook returning the {@link AvatarContextValue}; throws when used outside an `<Avatar.Root>`. */
+export declare const useAvatarContext: () => AvatarContextValue;

package/dist/Avatar/AvatarContext.js

@@ -0,0 +1,7 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+const avatarContextPair = createStrictContext("Avatar.Image and Avatar.Fallback must be rendered inside an <Avatar.Root>.", "AvatarContext");
+/** React context carrying the {@link AvatarContextValue} shared by the avatar's sub-components. */
+export const AvatarContext = avatarContextPair[0];
+/** Hook returning the {@link AvatarContextValue}; throws when used outside an `<Avatar.Root>`. */
+export const useAvatarContext = avatarContextPair[1];

package/dist/Avatar/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useAvatarContext } from "./useAvatarContext.js";
+export { useAvatarImage } from "./useAvatarImage.js";

package/dist/Avatar/hooks/index.js

@@ -0,0 +1,2 @@
+export { useAvatarContext } from "./useAvatarContext.js";
+export { useAvatarImage } from "./useAvatarImage.js";

package/dist/Avatar/hooks/useAvatarContext.d.ts

@@ -0,0 +1 @@
+export { useAvatarContext } from "../AvatarContext.js";

package/dist/Avatar/hooks/useAvatarContext.js

@@ -0,0 +1 @@
+export { useAvatarContext } from "../AvatarContext.js";

package/dist/Avatar/hooks/useAvatarImage.d.ts

@@ -0,0 +1,21 @@
+import { AvatarImageLoadingStatus } from "../types.js";
+/**
+ * Tracks the load lifecycle of an `Avatar.Image` and reports each change to
+ * the Avatar root via `setStatus`.
+ *
+ * The returned `ref` is a callback ref for the `<img>`: the first time the
+ * element attaches it inspects `naturalWidth` to catch a browser cache hit —
+ * an image already decoded before React attached its `onLoad` handler, whose
+ * `load` event would otherwise never reach React. A cache hit is reported as
+ * `"loaded"` straight away; any other image is `"loading"` until its
+ * `load` / `error` event resolves it via `onLoad` / `onError`.
+ *
+ * The initial inspection runs only once: later re-attachments (e.g. when a
+ * `Slot` recomposes the ref on re-render) must not clobber a status the
+ * load events have since moved on from.
+ */
+export declare function useAvatarImage(setStatus: (status: AvatarImageLoadingStatus) => void): {
+    ref: (img: HTMLImageElement | null) => void;
+    onLoad: () => void;
+    onError: () => void;
+};

package/dist/Avatar/hooks/useAvatarImage.js

@@ -0,0 +1,47 @@
+"use client";
+import { useCallback, useRef } from "react";
+/**
+ * Tracks the load lifecycle of an `Avatar.Image` and reports each change to
+ * the Avatar root via `setStatus`.
+ *
+ * The returned `ref` is a callback ref for the `<img>`: the first time the
+ * element attaches it inspects `naturalWidth` to catch a browser cache hit —
+ * an image already decoded before React attached its `onLoad` handler, whose
+ * `load` event would otherwise never reach React. A cache hit is reported as
+ * `"loaded"` straight away; any other image is `"loading"` until its
+ * `load` / `error` event resolves it via `onLoad` / `onError`.
+ *
+ * The initial inspection runs only once: later re-attachments (e.g. when a
+ * `Slot` recomposes the ref on re-render) must not clobber a status the
+ * load events have since moved on from.
+ */
+export function useAvatarImage(setStatus) {
+    const reported = useRef(false);
+    const ref = useCallback((img) => {
+        // 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/dist/Avatar/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./Avatar.js";
+export * from "./AvatarContext.js";
+export * from "./types.js";

package/dist/Avatar/index.js

@@ -0,0 +1,3 @@
+export * from "./Avatar.js";
+export * from "./AvatarContext.js";
+export * from "./types.js";

package/dist/Avatar/types.d.ts

@@ -0,0 +1,52 @@
+import { ComponentProps } from "react";
+/**
+ * The loading status of an Avatar's image.
+ *
+ * - `"idle"` — no {@link Avatar.Image} has reported yet (the root has only
+ *   ever shown its fallback).
+ * - `"loading"` — an {@link Avatar.Image} is mounted and its image is in
+ *   flight.
+ * - `"loaded"` — the image decoded successfully.
+ * - `"error"` — the image failed to load.
+ */
+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>`, merging
+     * the `data-status` hook onto it via {@link Slot}.
+     * @default false
+     */
+    asChild?: boolean;
+};
+/**
+ * Props for {@link Avatar.Image} — all `<img>` attributes plus `asChild`.
+ */
+export type AvatarImageProps = ComponentProps<"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;
+};
+/**
+ * Props for {@link Avatar.Fallback} — all `<span>` attributes plus the
+ * fallback-specific props.
+ */
+export type AvatarFallbackProps = ComponentProps<"span"> & {
+    /**
+     * Withhold the fallback for this many milliseconds after mount. Useful to
+     * avoid a flash of fallback content on fast connections where the image
+     * loads almost immediately. Omit to render the fallback straight away.
+     */
+    delayMs?: number;
+    /**
+     * 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;
+};

package/dist/Avatar/types.js

@@ -0,0 +1 @@
+export {};