@primitiv-ui/react 0.1.0

package/src/Avatar/README.md

@@ -0,0 +1,116 @@
+# Avatar
+
+Headless, accessible **Avatar** — a compound component for a user image with
+a graceful fallback for while it loads, or when it is missing or broken. Zero
+styles ship.
+
+```tsx
+import { Avatar } from "@primitiv-ui/react";
+
+<Avatar.Root>
+  <Avatar.Image src="/users/ada.jpg" alt="Ada Lovelace" />
+  <Avatar.Fallback>AL</Avatar.Fallback>
+</Avatar.Root>;
+```
+
+## Sub-components
+
+| Export | Element | Data hooks | `asChild` |
+|--------|---------|------------|-----------|
+| `Avatar.Root` | `<span>` | `data-status` | yes |
+| `Avatar.Image` | `<img>` | `data-status` | yes |
+| `Avatar.Fallback` | `<span>` | `data-status` | yes |
+
+## Props
+
+### `Avatar.Root`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `asChild` | `boolean` | `false` | Render the consumer's own element instead of `<span>`. |
+| `...rest` | `ComponentProps<"span">` | — | All other `<span>` props. |
+
+### `Avatar.Image`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `asChild` | `boolean` | `false` | Render the consumer's own `<img>` instead. |
+| `...rest` | `ComponentProps<"img">` | — | All `<img>` props — `src`, `alt`, etc. |
+
+### `Avatar.Fallback`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `delayMs` | `number` | — | Withhold the fallback for this many ms after mount, to avoid a flash of fallback content on fast connections. |
+| `asChild` | `boolean` | `false` | Render the consumer's own element instead of `<span>`. |
+| `...rest` | `ComponentProps<"span">` | — | All other `<span>` props. |
+
+## Loading status
+
+`Avatar.Root` owns a single loading status, resolved by the descendant
+`Avatar.Image`:
+
+| `data-status` | Meaning |
+|---------------|---------|
+| `"idle"` | No `Avatar.Image` has reported yet — only the fallback has shown. |
+| `"loading"` | An image is mounted and in flight. |
+| `"loaded"` | The image decoded successfully. |
+| `"error"` | The image failed to load. |
+
+`Avatar.Image` also resolves an **already-cached** image — one the browser
+decoded before React could attach its `load` handler — straight to
+`"loaded"`, so a cache hit never gets stuck showing the fallback.
+
+## The fallback
+
+`Avatar.Fallback` renders while the status is anything other than `"loaded"`,
+and unmounts once the image loads. Use it for initials, an icon, or a
+placeholder.
+
+The `Avatar.Image` stays mounted on error so its `load` lifecycle is not lost;
+hide a broken image with CSS via the `data-status` hook:
+
+```css
+.avatar-image:not([data-status="loaded"]) {
+  display: none;
+}
+```
+
+Pass `delayMs` to withhold the fallback briefly — useful when the image
+usually loads fast enough that a flash of initials would be more distracting
+than helpful:
+
+```tsx
+<Avatar.Root>
+  <Avatar.Image src="/users/ada.jpg" alt="Ada Lovelace" />
+  <Avatar.Fallback delayMs={600}>AL</Avatar.Fallback>
+</Avatar.Root>
+```
+
+## Accessibility
+
+Give `Avatar.Image` a meaningful `alt`. When the fallback is purely
+decorative (e.g. it duplicates a name shown elsewhere), an empty `alt` on the
+image plus `aria-hidden` on the fallback keeps assistive technology from
+announcing the avatar twice.
+
+## `asChild` composition
+
+All three sub-components accept `asChild`. The library's `data-status` hook —
+and, for the image, its `ref` and `load` / `error` handlers — are merged onto
+the consumer's element.
+
+```tsx
+<Avatar.Root asChild>
+  <a href="/users/ada">
+    <Avatar.Image src="/users/ada.jpg" alt="Ada Lovelace" />
+    <Avatar.Fallback>AL</Avatar.Fallback>
+  </a>
+</Avatar.Root>
+```
+
+## Styling hooks
+
+| Attribute | Values | Set on |
+|-----------|--------|--------|
+| `data-status` | `"idle"` \| `"loading"` \| `"loaded"` \| `"error"` | `Avatar.Root`, `Avatar.Image`, `Avatar.Fallback` |

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

@@ -0,0 +1,53 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+
+import { Avatar } from "../Avatar";
+
+describe("Avatar asChild", () => {
+  it("renders the Root as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <Avatar.Root asChild data-testid="root">
+        <section />
+      </Avatar.Root>,
+    );
+    const root = screen.getByTestId("root");
+
+    // Assert — section rendered, not span; data-* hook merged onto it
+    expect(root.tagName).toBe("SECTION");
+    expect(root).toHaveAttribute("data-status", "idle");
+  });
+
+  it("renders the Image as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <Avatar.Root>
+        <Avatar.Image asChild src="/ada.png" alt="Ada">
+          <img data-testid="img" />
+        </Avatar.Image>
+      </Avatar.Root>,
+    );
+    const img = screen.getByTestId("img");
+
+    fireEvent.load(img);
+
+    // Assert — consumer's img kept; src and the load lifecycle merged onto it
+    expect(img).toHaveAttribute("src", "/ada.png");
+    expect(img).toHaveAttribute("data-status", "loaded");
+  });
+
+  it("renders the Fallback as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <Avatar.Root>
+        <Avatar.Fallback asChild>
+          <div data-testid="fb">AL</div>
+        </Avatar.Fallback>
+      </Avatar.Root>,
+    );
+    const fb = screen.getByTestId("fb");
+
+    // Assert
+    expect(fb.tagName).toBe("DIV");
+    expect(fb).toHaveAttribute("data-status", "idle");
+  });
+});

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

@@ -0,0 +1,14 @@
+import { render, screen } from "@testing-library/react";
+
+import { Avatar } from "../Avatar";
+
+describe("Avatar basic rendering", () => {
+  it("renders Avatar.Root as a <span>", () => {
+    // Arrange & Act
+    render(<Avatar.Root data-testid="avatar" />);
+    const root = screen.getByTestId("avatar");
+
+    // Assert
+    expect(root.tagName).toBe("SPAN");
+  });
+});

package/src/Avatar/__tests__/Avatar.error-handling.test.tsx

@@ -0,0 +1,30 @@
+import { render } from "@testing-library/react";
+
+import { Avatar } from "../Avatar";
+
+const OUTSIDE_ROOT_ERROR =
+  "Avatar.Image and Avatar.Fallback must be rendered inside an <Avatar.Root>.";
+
+describe("Avatar error handling", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("throws when Avatar.Image is rendered outside an Avatar.Root", () => {
+    // Arrange & Act & Assert
+    expect(() =>
+      render(<Avatar.Image src="/ada.png" alt="Ada" />),
+    ).toThrow(OUTSIDE_ROOT_ERROR);
+  });
+
+  it("throws when Avatar.Fallback is rendered outside an Avatar.Root", () => {
+    // Arrange & Act & Assert
+    expect(() => render(<Avatar.Fallback>AL</Avatar.Fallback>)).toThrow(
+      OUTSIDE_ROOT_ERROR,
+    );
+  });
+});

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

@@ -0,0 +1,75 @@
+import { act, fireEvent, render, screen } from "@testing-library/react";
+
+import { Avatar } from "../Avatar";
+
+describe("Avatar fallback", () => {
+  it("renders the fallback while no image has loaded", () => {
+    // Arrange & Act
+    render(
+      <Avatar.Root>
+        <Avatar.Fallback>AL</Avatar.Fallback>
+      </Avatar.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("AL")).toBeInTheDocument();
+  });
+
+  it("renders the fallback as a <span>", () => {
+    // Arrange & Act
+    render(
+      <Avatar.Root>
+        <Avatar.Fallback data-testid="fb">AL</Avatar.Fallback>
+      </Avatar.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("fb").tagName).toBe("SPAN");
+  });
+
+  it("hides the fallback once the image has loaded", () => {
+    // Arrange
+    render(
+      <Avatar.Root>
+        <Avatar.Image src="/ada.png" alt="Ada" data-testid="img" />
+        <Avatar.Fallback>AL</Avatar.Fallback>
+      </Avatar.Root>,
+    );
+
+    // Act
+    fireEvent.load(screen.getByTestId("img"));
+
+    // Assert
+    expect(screen.queryByText("AL")).not.toBeInTheDocument();
+  });
+
+  describe("with delayMs", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it("withholds the fallback until the delay has elapsed", () => {
+      // Arrange
+      render(
+        <Avatar.Root>
+          <Avatar.Fallback delayMs={600}>AL</Avatar.Fallback>
+        </Avatar.Root>,
+      );
+
+      // Assert — withheld before the delay elapses
+      expect(screen.queryByText("AL")).not.toBeInTheDocument();
+
+      // Act
+      act(() => {
+        vi.advanceTimersByTime(600);
+      });
+
+      // Assert — shown once the delay elapses
+      expect(screen.getByText("AL")).toBeInTheDocument();
+    });
+  });
+});

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

@@ -0,0 +1,81 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+
+import { Avatar } from "../Avatar";
+
+describe("Avatar image loading", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("renders Avatar.Image as an <img> with the given src and alt", () => {
+    // Arrange & Act
+    render(
+      <Avatar.Root>
+        <Avatar.Image src="/ada.png" alt="Ada Lovelace" />
+      </Avatar.Root>,
+    );
+    const img = screen.getByRole("img", { name: "Ada Lovelace" });
+
+    // Assert
+    expect(img.tagName).toBe("IMG");
+    expect(img).toHaveAttribute("src", "/ada.png");
+  });
+
+  it('reports data-status="loaded" on the Root and Image once the image loads', () => {
+    // Arrange
+    render(
+      <Avatar.Root data-testid="root">
+        <Avatar.Image src="/ada.png" alt="Ada" data-testid="img" />
+      </Avatar.Root>,
+    );
+
+    // Act
+    fireEvent.load(screen.getByTestId("img"));
+
+    // Assert
+    expect(screen.getByTestId("root")).toHaveAttribute(
+      "data-status",
+      "loaded",
+    );
+    expect(screen.getByTestId("img")).toHaveAttribute("data-status", "loaded");
+  });
+
+  it('reports data-status="error" on the Root and Image when the image fails', () => {
+    // Arrange
+    render(
+      <Avatar.Root data-testid="root">
+        <Avatar.Image src="/missing.png" alt="Ada" data-testid="img" />
+      </Avatar.Root>,
+    );
+
+    // Act
+    fireEvent.error(screen.getByTestId("img"));
+
+    // Assert
+    expect(screen.getByTestId("root")).toHaveAttribute("data-status", "error");
+    expect(screen.getByTestId("img")).toHaveAttribute("data-status", "error");
+  });
+
+  it('reports data-status="loaded" on mount for an already-cached image', () => {
+    // Arrange — a browser cache hit: the image is decoded before React
+    // attaches its onLoad handler, so no load event will ever fire.
+    vi.spyOn(
+      HTMLImageElement.prototype,
+      "naturalWidth",
+      "get",
+    ).mockReturnValue(64);
+
+    // Act — render without firing any load event
+    render(
+      <Avatar.Root data-testid="root">
+        <Avatar.Image src="/ada.png" alt="Ada" data-testid="img" />
+      </Avatar.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("img")).toHaveAttribute(
+      "data-status",
+      "loaded",
+    );
+  });
+});

package/src/Avatar/hooks/index.ts

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

package/src/Avatar/hooks/useAvatarContext.ts

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

package/src/Avatar/hooks/useAvatarImage.ts

@@ -0,0 +1,40 @@
+import { useCallback, useRef } from "react";
+
+import { AvatarImageLoadingStatus } from "../types";
+
+/**
+ * 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: (status: AvatarImageLoadingStatus) => void,
+) {
+  const reported = useRef(false);
+
+  const ref = useCallback(
+    (img: HTMLImageElement | null) => {
+      if (img === null || reported.current) {
+        return;
+      }
+      reported.current = true;
+      setStatus(img.naturalWidth > 0 ? "loaded" : "loading");
+    },
+    [setStatus],
+  );
+
+  const onLoad = useCallback(() => setStatus("loaded"), [setStatus]);
+  const onError = useCallback(() => setStatus("error"), [setStatus]);
+
+  return { ref, onLoad, onError };
+}

package/src/Avatar/index.ts

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

package/src/Avatar/types.ts

@@ -0,0 +1,44 @@
+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>`. */
+  asChild?: boolean;
+};
+
+/**
+ * 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>`. */
+  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>`. */
+  asChild?: boolean;
+};