@primitiv-ui/react 0.1.38 → 0.1.40

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

@@ -1,116 +0,0 @@
-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="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(
-      <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

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

package/src/Avatar/hooks/useAvatarContext.ts

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

package/src/Avatar/hooks/useAvatarImage.ts

@@ -1,56 +0,0 @@
-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) => {
-      // 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/index.ts

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

package/src/Avatar/types.ts

@@ -1,56 +0,0 @@
-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/src/Breadcrumb/Breadcrumb.tsx

@@ -1,374 +0,0 @@
-import type { ReactElement } from "react";
-
-import { Slot } from "../Slot/index.ts";
-
-import {
-  BreadcrumbEllipsisProps,
-  BreadcrumbItemProps,
-  BreadcrumbLinkProps,
-  BreadcrumbListProps,
-  BreadcrumbPageProps,
-  BreadcrumbRootProps,
-  BreadcrumbSeparatorProps,
-} from "./types";
-
-/**
- * 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, 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
- * <Breadcrumb.Root>
- *   <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,
-  ...rest
-}: BreadcrumbRootProps): ReactElement {
-  return (
-    <nav aria-label="Breadcrumb" {...rest}>
-      {children}
-    </nav>
-  );
-}
-
-// 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 (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. Stateless — no
- * context is read or provided.
- *
- * @extends HTMLOListElement
- *
- * @example
- * ```tsx
- * <Breadcrumb.List>
- *   <Breadcrumb.Item>...</Breadcrumb.Item>
- *   <Breadcrumb.Separator />
- *   <Breadcrumb.Item>...</Breadcrumb.Item>
- * </Breadcrumb.List>
- * ```
- */
-export function BreadcrumbList({
-  children,
-  ...rest
-}: BreadcrumbListProps): ReactElement {
-  return <ol {...rest}>{children}</ol>;
-}
-
-/** @internal */
-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),
- * 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
- * <Breadcrumb.Item>
- *   <Breadcrumb.Link href="/library">Library</Breadcrumb.Link>
- * </Breadcrumb.Item>
- * ```
- */
-export function BreadcrumbItem({
-  children,
-  ...rest
-}: BreadcrumbItemProps): ReactElement {
-  return <li {...rest}>{children}</li>;
-}
-
-/** @internal */
-BreadcrumbItem.displayName = "BreadcrumbItem";
-
-/**
- * A link to an ancestor page — renders an `<a>`.
- *
- * 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.
- *
- * @extends HTMLAnchorElement
- *
- * @example
- * ```tsx
- * <Breadcrumb.Link href="/library">Library</Breadcrumb.Link>
- * ```
- *
- * @example With a router link
- * ```tsx
- * <Breadcrumb.Link asChild>
- *   <RouterLink to="/library">Library</RouterLink>
- * </Breadcrumb.Link>
- * ```
- */
-export function BreadcrumbLink({
-  children,
-  asChild = false,
-  ...rest
-}: BreadcrumbLinkProps): ReactElement {
-  if (asChild) {
-    return <Slot {...rest}>{children}</Slot>;
-  }
-  return <a {...rest}>{children}</a>;
-}
-
-/** @internal */
-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 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
- * <Breadcrumb.Item>
- *   <Breadcrumb.Page>Current article</Breadcrumb.Page>
- * </Breadcrumb.Item>
- * ```
- */
-export function BreadcrumbPage({
-  children,
-  ...rest
-}: BreadcrumbPageProps): ReactElement {
-  return (
-    <span aria-current="page" {...rest}>
-      {children}
-    </span>
-  );
-}
-
-/** @internal */
-BreadcrumbPage.displayName = "BreadcrumbPage";
-
-/**
- * The visual divider between two breadcrumb entries — renders an
- * `<li role="presentation" aria-hidden="true">`.
- *
- * The separator sits inside the `<ol>` as a sibling of the
- * {@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.) — whatever is passed replaces the default
- * entirely rather than being appended to it.
- *
- * @extends HTMLLIElement
- *
- * @example Default separator
- * ```tsx
- * <Breadcrumb.Separator />
- * ```
- *
- * @example Custom separator
- * ```tsx
- * <Breadcrumb.Separator><ChevronRight /></Breadcrumb.Separator>
- * ```
- */
-export function BreadcrumbSeparator({
-  children = "/",
-  ...rest
-}: BreadcrumbSeparatorProps): ReactElement {
-  return (
-    <li role="presentation" aria-hidden="true" {...rest}>
-      {children}
-    </li>
-  );
-}
-
-/** @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;
-  List: typeof BreadcrumbList;
-  Item: typeof BreadcrumbItem;
-  Link: typeof BreadcrumbLink;
-  Page: typeof BreadcrumbPage;
-  Separator: typeof BreadcrumbSeparator;
-  Ellipsis: typeof BreadcrumbEllipsis;
-};
-
-/**
- * Headless, accessible **Breadcrumb** — a compound component implementing the
- * [WAI-ARIA breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/):
- * a `<nav>` landmark wrapping an ordered list of links to ancestor pages,
- * ending with the current page. Stateless — purely structural. Zero styles
- * ship.
- *
- * `Breadcrumb` is both callable (an alias of
- * {@link BreadcrumbRoot | `Breadcrumb.Root`}) and carries its sub-components
- * as static properties.
- *
- * - {@link BreadcrumbRoot | `Breadcrumb.Root`} — `<nav aria-label="Breadcrumb">`.
- * - {@link BreadcrumbList | `Breadcrumb.List`} — `<ol>`, the ordered trail.
- * - {@link BreadcrumbItem | `Breadcrumb.Item`} — `<li>`, one entry.
- * - {@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
- * import { Breadcrumb } from "@primitiv-ui/react";
- *
- * <Breadcrumb.Root>
- *   <Breadcrumb.List>
- *     <Breadcrumb.Item>
- *       <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
- *     </Breadcrumb.Item>
- *     <Breadcrumb.Separator />
- *     <Breadcrumb.Item>
- *       <Breadcrumb.Link href="/library">Library</Breadcrumb.Link>
- *     </Breadcrumb.Item>
- *     <Breadcrumb.Separator />
- *     <Breadcrumb.Item>
- *       <Breadcrumb.Page>Current article</Breadcrumb.Page>
- *     </Breadcrumb.Item>
- *   </Breadcrumb.List>
- * </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,
-  List: BreadcrumbList,
-  Item: BreadcrumbItem,
-  Link: BreadcrumbLink,
-  Page: BreadcrumbPage,
-  Separator: BreadcrumbSeparator,
-  Ellipsis: BreadcrumbEllipsis,
-});
-
-/** @internal */
-BreadcrumbCompound.displayName = "Breadcrumb";
-
-export { BreadcrumbCompound as Breadcrumb };