@primitiv-ui/react 0.1.0

package/src/Accordion/hooks/useAccordionRoot.ts

@@ -0,0 +1,151 @@
+import { useRef, useMemo, useCallback, useId, useEffect } from "react";
+
+import { useCollection, useControllableState } from "../../hooks";
+
+import type { AccordionReadingDirection } from "../types";
+
+type TriggerMeta = {
+  element: HTMLButtonElement;
+  disabled: boolean;
+};
+
+export function useAccordionRoot(
+  controlledValue: string[] | undefined,
+  defaultValue: string | (readonly string[] & string) | undefined,
+  multiple: boolean,
+  onValueChange: ((values: string[]) => void) | undefined,
+  orientation: "vertical" | "horizontal",
+  dir: AccordionReadingDirection,
+) {
+  const accordionId = useId();
+  // updateKeysOnCleanup is false so trigger unmounts don't fire setState
+  // outside act() after a render-time validation throw.
+  const {
+    register: registerTriggerBase,
+    itemsRef: triggersRef,
+    keys: registeredTriggerItemIds,
+  } = useCollection<string, TriggerMeta>({ updateKeysOnCleanup: false });
+  const panelsRef = useRef<Set<string>>(new Set());
+
+  const registerTrigger = useCallback(
+    (
+      itemId: string,
+      element: HTMLButtonElement | null,
+      disabled = false,
+    ) => {
+      registerTriggerBase(itemId, element ? { element, disabled } : null);
+    },
+    [registerTriggerBase],
+  );
+
+  const disabledItemIds = useMemo(
+    () =>
+      new Set(
+        Array.from(triggersRef.current.entries())
+          .filter(([, meta]) => meta.disabled)
+          .map(([id]) => id),
+      ),
+    // registeredTriggerItemIds is a fresh array on every register call (new
+    // identity even when the keys are the same), so the memo re-runs whenever
+    // any trigger mounts, unmounts, or toggles disabled — which is exactly
+    // the trigger we want for re-deriving disabledItemIds.
+    [registeredTriggerItemIds, triggersRef],
+  );
+
+  const focusTrigger = useCallback(
+    (itemId: string) => {
+      triggersRef.current.get(itemId)?.element.focus();
+    },
+    [triggersRef],
+  );
+
+  // Like Tabs, Accordion's existing public contract is that uncontrolled
+  // mode does NOT call onValueChange — only the controlled path notifies the
+  // consumer. So we don't pass onValueChange to useControllableState; the
+  // toggleItem branch below fires it directly in controlled mode.
+  const [expandedItems, setExpandedItems, isControlled] = useControllableState<
+    Set<string>
+  >(
+    controlledValue !== undefined ? new Set(controlledValue) : undefined,
+    defaultValue !== undefined ? new Set([defaultValue]) : new Set(),
+  );
+
+  const computeNext = (prev: Set<string>, itemId: string): Set<string> => {
+    const next = new Set(prev);
+    if (next.has(itemId)) {
+      next.delete(itemId);
+    } else if (multiple) {
+      next.add(itemId);
+    } else {
+      next.clear();
+      next.add(itemId);
+    }
+    return next;
+  };
+
+  const toggleItem = useCallback(
+    (itemId: string) => {
+      const next = computeNext(expandedItems, itemId);
+      if (isControlled) {
+        onValueChange?.(Array.from(next));
+      } else {
+        setExpandedItems(next);
+      }
+    },
+    [expandedItems, isControlled, multiple, setExpandedItems, onValueChange],
+  );
+
+  // Panels are tracked in a ref only. registerPanel does NOT call setState —
+  // the validation effect reads panelsRef.current directly. Because React 18
+  // runs all effects in a commit before flushing batched state updates, the
+  // panel effect always executes (and updates panelsRef) before the re-render
+  // triggered by trigger registration reaches the validation effect.
+  const registerPanel = useCallback((itemId: string) => {
+    panelsRef.current.add(itemId);
+  }, []);
+
+  const unregisterPanel = useCallback((itemId: string) => {
+    panelsRef.current.delete(itemId);
+  }, []);
+
+  useEffect(() => {
+    for (const triggerId of registeredTriggerItemIds) {
+      if (!panelsRef.current.has(triggerId)) {
+        throw new Error(
+          `AccordionTrigger (item "${triggerId}") has no corresponding AccordionContent. Every AccordionItem with a Trigger must also contain an AccordionContent.`,
+        );
+      }
+    }
+  }, [registeredTriggerItemIds]);
+
+  const contextValue = useMemo(
+    () => ({
+      accordionId,
+      expandedItems,
+      orientation,
+      dir,
+      toggleItem,
+      registerTrigger,
+      registeredTriggerItemIds,
+      disabledItemIds,
+      focusTrigger,
+      registerPanel,
+      unregisterPanel,
+    }),
+    [
+      accordionId,
+      expandedItems,
+      orientation,
+      dir,
+      toggleItem,
+      registerTrigger,
+      registeredTriggerItemIds,
+      disabledItemIds,
+      focusTrigger,
+      registerPanel,
+      unregisterPanel,
+    ],
+  );
+
+  return { contextValue };
+}

package/src/Accordion/hooks/useAccordionTrigger.ts

@@ -0,0 +1,90 @@
+import { useMemo, useRef, useEffect, MouseEvent, KeyboardEvent } from "react";
+
+import { useRovingTabindex } from "../../hooks";
+import { composeRefs } from "../../Slot";
+
+import { AccordionTriggerProps } from "../types";
+
+import { useAccordionContext } from "./useAccordionContext";
+import { useAccordionItemContext } from "./useAccordionItemContext";
+
+export function useAccordionTrigger({
+  ref,
+  onClick,
+  disabled,
+  asChild = false,
+  ...rest
+}: Omit<AccordionTriggerProps, "children">) {
+  const { buttonId, panelId, itemId, isExpanded } = useAccordionItemContext();
+  const {
+    toggleItem,
+    registerTrigger,
+    registeredTriggerItemIds,
+    disabledItemIds,
+    focusTrigger,
+    orientation,
+    dir,
+  } = useAccordionContext();
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const composedRef = ref ? composeRefs(triggerRef, ref) : triggerRef;
+
+  // Register/unregister this trigger with the context. The disabled flag
+  // is now tracked in registration metadata (via useCollection's value
+  // type) instead of being read from the rendered aria-disabled attribute,
+  // which keeps Accordion consistent with RadioGroup and is the model
+  // useRovingTabindex expects.
+  useEffect(() => {
+    registerTrigger(itemId, triggerRef.current, disabled);
+    return () => registerTrigger(itemId, null);
+  }, [itemId, disabled, registerTrigger]);
+
+  function handleClick(e: MouseEvent<HTMLButtonElement>) {
+    if (disabled) return;
+    toggleItem(itemId);
+    onClick?.(e);
+  }
+
+  // Pre-filter disabled triggers out of the navigable list — Accordion's
+  // ARIA contract is that arrow keys skip past disabled triggers (unlike
+  // Tabs, which lands on disabled triggers without activating them).
+  const enabledItemIds = useMemo(
+    () => registeredTriggerItemIds.filter((id) => !disabledItemIds.has(id)),
+    [registeredTriggerItemIds, disabledItemIds],
+  );
+  const { handleKeyDown: rovingKeyDown } = useRovingTabindex<string>({
+    orientation,
+    dir,
+    navigable: enabledItemIds,
+    currentKey: itemId,
+    onNavigate: focusTrigger,
+    includeHomeEnd: true,
+  });
+
+  function handleKeyDown(e: KeyboardEvent<HTMLButtonElement>) {
+    // Accordion-specific: Enter / Space toggle the focused item rather than
+    // activate something else, so they're handled here before delegating
+    // arrow / Home / End to the shared hook.
+    if ((e.key === "Enter" || e.key === " ") && !disabled) {
+      e.preventDefault();
+      toggleItem(itemId);
+      return;
+    }
+    rovingKeyDown(e);
+  }
+
+  const triggerProps = {
+    ref: composedRef,
+    "aria-expanded": isExpanded,
+    id: buttonId,
+    "aria-controls": panelId,
+    "aria-disabled": disabled,
+    "data-disabled": disabled,
+    ...(asChild && disabled ? { role: "button" } : {}),
+    onClick: handleClick,
+    onKeyDown: handleKeyDown,
+    "data-state": isExpanded ? "open" : "closed",
+    ...rest,
+  };
+
+  return { triggerProps };
+}

package/src/Accordion/index.ts

@@ -0,0 +1 @@
+export * from './Accordion';

package/src/Accordion/types.ts

@@ -0,0 +1,81 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+import { HeadingLevel } from "../types";
+
+type AccordionRootBaseProps = ComponentProps<"div"> & {
+  multiple?: boolean;
+  orientation?: "vertical" | "horizontal";
+  dir?: AccordionReadingDirection;
+};
+
+type AccordionRootUncontrolledProps = AccordionRootBaseProps & {
+  defaultValue?: string;
+  value?: never;
+  onValueChange?: never;
+};
+
+type AccordionRootControlledProps = AccordionRootBaseProps & {
+  defaultValue?: never;
+  value: string[];
+  onValueChange: (values: string[]) => void;
+};
+
+export type AccordionReadingDirection = "ltr" | "rtl";
+
+export type AccordionRootProps =
+  | AccordionRootUncontrolledProps
+  | AccordionRootControlledProps;
+
+export type AccordionItemProps = ComponentProps<"div"> & {
+  children: ReactNode;
+  value?: string; // Optional - if not provided, useId() will generate one
+};
+
+export type AccordionTriggerProps<
+  T extends HTMLElement = HTMLButtonElement,
+> = Omit<ComponentProps<"button">, "disabled" | "ref"> & {
+  children: ReactNode;
+  disabled?: boolean;
+  asChild?: boolean;
+  /** Ref to the rendered element. Defaults to `HTMLButtonElement`; when using
+   * `asChild`, specify the child's element type (e.g. `HTMLAnchorElement`). */
+  ref?: Ref<T>;
+};
+
+export type AccordionHeaderProps = ComponentProps<"h3"> & {
+  children: ReactNode;
+  level?: HeadingLevel;
+};
+
+export type AccordionContentProps = ComponentProps<"div"> & {
+  children: ReactNode;
+  forceMount?: boolean;
+};
+
+export type AccordionTriggerIconProps = ComponentProps<"span"> & {
+  children: ReactNode;
+};
+
+export type AccordionContextValue = {
+  accordionId: string;
+  expandedItems: Set<string>;
+  orientation: "vertical" | "horizontal";
+  dir: AccordionReadingDirection;
+  toggleItem: (itemId: string) => void;
+  registerTrigger: (
+    itemId: string,
+    element: HTMLButtonElement | null,
+    disabled?: boolean,
+  ) => void;
+  registeredTriggerItemIds: string[];
+  disabledItemIds: Set<string>;
+  focusTrigger: (itemId: string) => void;
+  registerPanel: (itemId: string) => void;
+  unregisterPanel: (itemId: string) => void;
+};
+
+export type AccordionItemContextValue = {
+  buttonId: string;
+  panelId: string;
+  itemId: string;
+  isExpanded: boolean;
+};

package/src/Alert/Alert.tsx

@@ -0,0 +1,43 @@
+import { Slot } from "../Slot";
+import { AlertProps } from "./types";
+
+/**
+ * An assertive live region for high-priority, time-sensitive messages.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of
+ * a `<div>`, merging `role="alert"` and all other props in via the
+ * {@link Slot} utility.
+ *
+ * @example Form error
+ * ```tsx
+ * {error && <Alert>{error}</Alert>}
+ * ```
+ *
+ * @example asChild — keep semantic markup
+ * ```tsx
+ * <Alert asChild>
+ *   <section>Upload failed — try again.</section>
+ * </Alert>
+ * ```
+ */
+export function Alert({ asChild = false, children, ...rest }: AlertProps) {
+  const rootProps = { role: "alert", ...rest };
+
+  if (asChild) {
+    return <Slot {...rootProps}>{children}</Slot>;
+  }
+
+  return <div {...rootProps}>{children}</div>;
+}
+
+Alert.displayName = "Alert";

package/src/Alert/README.md

@@ -0,0 +1,54 @@
+# Alert
+
+An assertive live region for high-priority, time-sensitive messages,
+implementing the
+[WAI-ARIA `alert` role](https://www.w3.org/TR/wai-aria-1.2/#alert).
+
+```tsx
+import { Alert } from "@primitiv-ui/react";
+
+{
+  error && <Alert>{error}</Alert>;
+}
+```
+
+## Props
+
+| Prop        | Type                    | Default | Notes                                              |
+| ----------- | ----------------------- | ------- | -------------------------------------------------- |
+| `asChild`   | `boolean`               | `false` | Render the consumer's element instead of a `<div>` |
+| `className` | `string`                | —       | Applied directly to the rendered element           |
+| `...rest`   | `ComponentProps<"div">` | —       | All other `<div>` props, including `aria-*`         |
+
+## Behaviour
+
+`Alert` 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`](../Status/README.md).
+
+## Announce on appearance
+
+A live region announces content that changes *after* the region is in
+the DOM. Render the `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.
+
+## asChild
+
+Pass `asChild` to apply `role="alert"` to the consumer's own element:
+
+```tsx
+<Alert asChild>
+  <section>Upload failed — try again.</section>
+</Alert>
+```

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

@@ -0,0 +1,28 @@
+import { Alert } from "..";
+import { render, screen } from "@testing-library/react";
+
+describe("Alert component", () => {
+  it("should render a div with role alert containing its children", () => {
+    // Arrange
+    render(<Alert>Your changes could not be saved</Alert>);
+
+    // Assert
+    const alert = screen.getByRole("alert");
+    expect(alert.tagName).toBe("DIV");
+    expect(alert).toHaveTextContent("Your changes could not be saved");
+  });
+
+  it("should render the consumer element with asChild, keeping role alert", () => {
+    // Arrange
+    render(
+      <Alert asChild>
+        <section>Upload failed</section>
+      </Alert>,
+    );
+
+    // Assert
+    const alert = screen.getByRole("alert");
+    expect(alert.tagName).toBe("SECTION");
+    expect(alert).toHaveTextContent("Upload failed");
+  });
+});

package/src/Alert/index.ts

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

package/src/Alert/types.ts

@@ -0,0 +1,5 @@
+import { ComponentProps } from "react";
+
+export type AlertProps = ComponentProps<"div"> & {
+  asChild?: boolean;
+};

package/src/Avatar/Avatar.tsx

@@ -0,0 +1,149 @@
+import { useEffect, useMemo, useState } from "react";
+
+import { Slot } from "../Slot";
+
+import { AvatarContext } from "./AvatarContext";
+import { useAvatarContext, useAvatarImage } from "./hooks";
+import {
+  AvatarFallbackProps,
+  AvatarImageLoadingStatus,
+  AvatarImageProps,
+  AvatarRootProps,
+} from "./types";
+
+/**
+ * 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`}.
+ *
+ * **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.
+ */
+function AvatarRoot({ asChild = false, children, ...rest }: AvatarRootProps) {
+  const [status, setStatus] = useState<AvatarImageLoadingStatus>("idle");
+
+  const contextValue = useMemo(() => ({ status, setStatus }), [status]);
+
+  const rootProps = { ...rest, "data-status": status };
+
+  return (
+    <AvatarContext.Provider value={contextValue}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <span {...rootProps}>{children}</span>
+      )}
+    </AvatarContext.Provider>
+  );
+}
+
+AvatarRoot.displayName = "AvatarRoot";
+
+/**
+ * The image of an Avatar — an `<img>` that reports its load lifecycle to the
+ * parent {@link Avatar.Root}.
+ *
+ * **Styling hooks.** `data-status` mirrors the root's status. The image stays
+ * mounted on error; 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.
+ *
+ * @throws if rendered outside an `Avatar.Root`.
+ */
+function AvatarImage({ asChild = false, children, ...rest }: AvatarImageProps) {
+  const { status, setStatus } = useAvatarContext();
+  const { ref, onLoad, onError } = useAvatarImage(setStatus);
+
+  const imageProps = {
+    ...rest,
+    "data-status": status,
+    onLoad,
+    onError,
+  };
+
+  if (asChild) {
+    return (
+      <Slot {...imageProps} ref={ref}>
+        {children}
+      </Slot>
+    );
+  }
+
+  return <img {...imageProps} ref={ref} />;
+}
+
+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.
+ *
+ * Pass `delayMs` to withhold the fallback for that many milliseconds after
+ * mount, avoiding a flash of fallback content when the image loads quickly.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element as
+ * the fallback, with the `data-status` hook merged in.
+ *
+ * @throws if rendered outside an `Avatar.Root`.
+ */
+function AvatarFallback({
+  delayMs,
+  asChild = false,
+  children,
+  ...rest
+}: AvatarFallbackProps) {
+  const { status } = useAvatarContext();
+  const [delayElapsed, setDelayElapsed] = useState(delayMs === undefined);
+
+  useEffect(() => {
+    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 <Slot {...fallbackProps}>{children}</Slot>;
+  }
+
+  return <span {...fallbackProps}>{children}</span>;
+}
+
+AvatarFallback.displayName = "AvatarFallback";
+
+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.
+ *
+ * - {@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.
+ */
+const AvatarCompound: TAvatarCompound = Object.assign(AvatarRoot, {
+  Root: AvatarRoot,
+  Image: AvatarImage,
+  Fallback: AvatarFallback,
+});
+
+AvatarCompound.displayName = "Avatar";
+
+export { AvatarCompound as Avatar };

package/src/Avatar/AvatarContext.ts

@@ -0,0 +1,20 @@
+import { createStrictContext } from "../utils";
+
+import { AvatarImageLoadingStatus } from "./types";
+
+/**
+ * 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;
+};
+
+export const [AvatarContext, useAvatarContext] =
+  createStrictContext<AvatarContextValue>(
+    "Avatar.Image and Avatar.Fallback must be rendered inside an <Avatar.Root>.",
+    "AvatarContext",
+  );