@primitiv-ui/react 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Revill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@primitiv-ui/react",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "description": "Headless, accessible React components built on the WAI-ARIA authoring patterns. Zero styles ship with this package — bring your own (CSS, Tailwind, CSS-in-JS, design tokens).",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/AccessibleIcon/AccessibleIcon.tsx

@@ -1,5 +1,5 @@
 import { Children, cloneElement, ReactElement } from "react";
-import { VisuallyHidden } from "../VisuallyHidden";
+import { VisuallyHidden } from "../VisuallyHidden/index.ts";
 import { AccessibleIconProps } from "./types";
 
 type DecorativeIconProps = { "aria-hidden": string; focusable: string };
@@ -26,7 +26,10 @@ type DecorativeIconProps = { "aria-hidden": string; focusable: string };
  * </button>
  * ```
  */
-export function AccessibleIcon({ label, children }: AccessibleIconProps) {
+export function AccessibleIcon({
+  label,
+  children,
+}: AccessibleIconProps): ReactElement {
   const icon = Children.only(children) as ReactElement<DecorativeIconProps>;
 
   return (
@@ -37,4 +40,5 @@ export function AccessibleIcon({ label, children }: AccessibleIconProps) {
   );
 }
 
+/** @internal */
 AccessibleIcon.displayName = "AccessibleIcon";

package/src/AccessibleIcon/__tests__/AccessibleIcon.test.tsx

@@ -1,4 +1,4 @@
-import { AccessibleIcon } from "..";
+import { AccessibleIcon } from "../index.ts";
 import { render, screen } from "@testing-library/react";
 
 describe("AccessibleIcon component", () => {

package/src/AccessibleIcon/types.ts

@@ -1,5 +1,9 @@
 import { ReactElement } from "react";
 
+/**
+ * Props for {@link AccessibleIcon} — a single icon element plus the
+ * visually-hidden `label` announced as its accessible name.
+ */
 export type AccessibleIconProps = {
   /** Text announced by assistive technology as the icon's accessible name. */
   label: string;

package/src/Accordion/Accordion.tsx

@@ -1,7 +1,8 @@
 import { Ref, useEffect } from "react";
+import type { ReactElement } from "react";
 
-import { useDirection } from "../DirectionProvider";
-import { Slot } from "../Slot";
+import { useDirection } from "../DirectionProvider/index.ts";
+import { Slot } from "../Slot/index.ts";
 
 import type {
   AccordionRootProps,
@@ -21,7 +22,7 @@ import {
   useAccordionItem,
   useAccordionItemContext,
   useAccordionRoot,
-} from "./hooks";
+} from "./hooks/index.ts";
 import { useAccordionTrigger } from "./hooks/useAccordionTrigger";
 
 /**
@@ -78,7 +79,7 @@ export function AccordionRoot({
   orientation = "vertical",
   dir,
   ...rest
-}: AccordionRootProps) {
+}: AccordionRootProps): ReactElement {
   const resolvedDir = dir ?? useDirection();
   const { contextValue } = useAccordionRoot(
     controlledValue,
@@ -98,6 +99,7 @@ export function AccordionRoot({
   );
 }
 
+/** @internal */
 AccordionRoot.displayName = "AccordionRoot";
 
 /**
@@ -124,7 +126,7 @@ export function AccordionItem({
   children,
   value,
   ...rest
-}: AccordionItemProps) {
+}: AccordionItemProps): ReactElement {
   const { contextValue } = useAccordionItem(value);
 
   return (
@@ -134,6 +136,7 @@ export function AccordionItem({
   );
 }
 
+/** @internal */
 AccordionItem.displayName = "AccordionItem";
 
 /**
@@ -156,13 +159,14 @@ export function AccordionHeader({
   children,
   level = 3,
   ...rest
-}: AccordionHeaderProps) {
+}: AccordionHeaderProps): ReactElement {
   useAccordionHeaderContext();
   const HeadingTag: HeadingTag = `h${level}`;
 
   return <HeadingTag {...rest}>{children}</HeadingTag>;
 }
 
+/** @internal */
 AccordionHeader.displayName = "AccordionHeader";
 
 /**
@@ -229,16 +233,14 @@ AccordionHeader.displayName = "AccordionHeader";
  * </Accordion.Trigger>
  * ```
  */
-export function AccordionTrigger<
-  T extends HTMLElement = HTMLButtonElement,
->({
+export function AccordionTrigger<T extends HTMLElement = HTMLButtonElement>({
   ref,
   children,
   onClick,
   disabled = false,
   asChild = false,
   ...rest
-}: AccordionTriggerProps<T>) {
+}: AccordionTriggerProps<T>): ReactElement {
   // Cast the external ref to match the internal button ref's element type —
   // RefObject<T> is invariant in React's types, but at runtime the callback
   // receives whatever DOM element is actually rendered (button or asChild).
@@ -261,6 +263,7 @@ export function AccordionTrigger<
   );
 }
 
+/** @internal */
 AccordionTrigger.displayName = "AccordionTrigger";
 
 /**
@@ -306,7 +309,7 @@ export function AccordionContent({
   children,
   forceMount = false,
   ...rest
-}: AccordionContentProps) {
+}: AccordionContentProps): ReactElement {
   const { panelId, buttonId, itemId, isExpanded } = useAccordionItemContext();
   const { registerPanel, unregisterPanel } = useAccordionContext();
 
@@ -330,6 +333,7 @@ export function AccordionContent({
   );
 }
 
+/** @internal */
 AccordionContent.displayName = "AccordionContent";
 
 /**
@@ -373,7 +377,7 @@ AccordionContent.displayName = "AccordionContent";
 export function AccordionTriggerIcon({
   children,
   ...rest
-}: AccordionTriggerIconProps) {
+}: AccordionTriggerIconProps): ReactElement {
   const { isExpanded } = useAccordionItemContext();
 
   return (
@@ -387,8 +391,10 @@ export function AccordionTriggerIcon({
   );
 }
 
+/** @internal */
 AccordionTriggerIcon.displayName = "AccordionTriggerIcon";
 
+/** @internal */
 type AccordionCompound = typeof AccordionRoot & {
   Root: typeof AccordionRoot;
   Item: typeof AccordionItem;
@@ -398,6 +404,22 @@ type AccordionCompound = typeof AccordionRoot & {
   TriggerIcon: typeof AccordionTriggerIcon;
 };
 
+/**
+ * Headless, accessible **Accordion** — a compound component for a vertically
+ * (or horizontally) stacked set of collapsible sections, following the
+ * [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
+ * with zero styles.
+ *
+ * `Accordion` is both callable (an alias of {@link AccordionRoot | `Accordion.Root`})
+ * and carries its sub-components as static properties:
+ *
+ * - {@link AccordionRoot | `Accordion.Root`} — state owner and context provider.
+ * - {@link AccordionItem | `Accordion.Item`} — one collapsible section.
+ * - {@link AccordionHeader | `Accordion.Header`} — heading wrapper for the trigger.
+ * - {@link AccordionTrigger | `Accordion.Trigger`} — button that toggles the section.
+ * - {@link AccordionContent | `Accordion.Content`} — the collapsible panel.
+ * - {@link AccordionTriggerIcon | `Accordion.TriggerIcon`} — decorative state indicator.
+ */
 const AccordionCompound: AccordionCompound = Object.assign(AccordionRoot, {
   Root: AccordionRoot,
   Item: AccordionItem,

package/src/Accordion/AccordionContext.ts

@@ -1,4 +1,4 @@
-import { createStrictContext } from "../utils";
+import { createStrictContext } from "../utils/index.ts";
 import { AccordionContextValue, AccordionItemContextValue } from "./types";
 
 export const [AccordionContext, useAccordionContext] =

package/src/Accordion/__tests__/Accordion.reading-direction.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { DirectionProvider } from "../../DirectionProvider";
+import { DirectionProvider } from "../../DirectionProvider/index.ts";
 import { Accordion } from "../Accordion";
 
 describe("Accordion reading direction tests", () => {

package/src/Accordion/hooks/useAccordionItem.ts

@@ -1,6 +1,6 @@
 import { useId, useMemo } from "react";
 
-import { deriveId } from "../../utils";
+import { deriveId } from "../../utils/index.ts";
 
 import { useAccordionContext } from "./useAccordionContext";
 

package/src/Accordion/hooks/useAccordionRoot.ts

@@ -1,6 +1,6 @@
 import { useRef, useMemo, useCallback, useId, useEffect } from "react";
 
-import { useCollection, useControllableState } from "../../hooks";
+import { useCollection, useControllableState } from "../../hooks/index.ts";
 
 import type { AccordionReadingDirection } from "../types";
 

package/src/Accordion/hooks/useAccordionTrigger.ts

@@ -1,7 +1,7 @@
 import { useMemo, useRef, useEffect, MouseEvent, KeyboardEvent } from "react";
 
-import { useRovingTabindex } from "../../hooks";
-import { composeRefs } from "../../Slot";
+import { useRovingTabindex } from "../../hooks/index.ts";
+import { composeRefs } from "../../Slot/index.ts";
 
 import { AccordionTriggerProps } from "../types";
 

package/src/Accordion/index.ts

@@ -1 +1,2 @@
-export * from './Accordion';
+export * from "./Accordion";
+export * from "./types";

package/src/Accordion/types.ts

@@ -1,81 +1,123 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 import { HeadingLevel } from "../types";
 
-type AccordionRootBaseProps = ComponentProps<"div"> & {
+/** 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. */
   multiple?: boolean;
+  /** Layout axis, controlling arrow-key navigation. Defaults to `"vertical"`. */
   orientation?: "vertical" | "horizontal";
+  /** Reading direction, controlling left/right key semantics. */
   dir?: AccordionReadingDirection;
 };
 
-type AccordionRootUncontrolledProps = AccordionRootBaseProps & {
+/** `Accordion.Root` props for the uncontrolled (self-managed) expanded state. */
+export type AccordionRootUncontrolledProps = AccordionRootBaseProps & {
+  /** Initially expanded item value when uncontrolled. */
   defaultValue?: string;
   value?: never;
   onValueChange?: never;
 };
 
-type AccordionRootControlledProps = AccordionRootBaseProps & {
+/** `Accordion.Root` props for the controlled expanded state. */
+export type AccordionRootControlledProps = AccordionRootBaseProps & {
   defaultValue?: never;
+  /** Controlled set of expanded item values. */
   value: string[];
+  /** Called whenever the set of expanded item values changes. */
   onValueChange: (values: string[]) => void;
 };
 
+/** Reading direction for an accordion. */
 export type AccordionReadingDirection = "ltr" | "rtl";
 
+/** Props for `Accordion.Root`, in either the controlled or uncontrolled mode. */
 export type AccordionRootProps =
   | AccordionRootUncontrolledProps
   | AccordionRootControlledProps;
 
+/** Props for `Accordion.Item` — a single collapsible section. */
 export type AccordionItemProps = ComponentProps<"div"> & {
+  /** Section contents — typically a `Header` + `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
 };
 
-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>;
-};
+/** 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. */
+    children: ReactNode;
+    /** Disable the trigger, removing it from keyboard navigation. */
+    disabled?: boolean;
+    /** Render into the consumer's own element instead of a `<button>`. */
+    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>;
+  };
 
+/** Props for `Accordion.Header` — the heading wrapping a trigger. */
 export type AccordionHeaderProps = ComponentProps<"h3"> & {
+  /** Header contents — typically an `Accordion.Trigger`. */
   children: ReactNode;
+  /** Heading level rendered (`h1`–`h6`). Defaults to `3`. */
   level?: HeadingLevel;
 };
 
+/** Props for `Accordion.Content` — the collapsible panel. */
 export type AccordionContentProps = ComponentProps<"div"> & {
+  /** Panel contents. */
   children: ReactNode;
+  /** Keep the panel mounted even while collapsed. */
   forceMount?: boolean;
 };
 
+/** Props for `Accordion.TriggerIcon` — a decorative open/closed indicator. */
 export type AccordionTriggerIconProps = ComponentProps<"span"> & {
+  /** Icon contents. */
   children: ReactNode;
 };
 
+/** Context value published by `Accordion.Root` to coordinate its sections. */
 export type AccordionContextValue = {
+  /** Generated id namespacing the accordion's element ids. */
   accordionId: string;
+  /** Set of currently expanded item values. */
   expandedItems: Set<string>;
+  /** Layout axis used for arrow-key navigation. */
   orientation: "vertical" | "horizontal";
+  /** Reading direction used for left/right key semantics. */
   dir: AccordionReadingDirection;
+  /** Toggles the expanded state of the given item. */
   toggleItem: (itemId: string) => void;
+  /** Registers a trigger element so roving focus can reach it. */
   registerTrigger: (
     itemId: string,
     element: HTMLButtonElement | null,
     disabled?: boolean,
   ) => void;
+  /** Ordered ids of registered triggers, used for focus movement. */
   registeredTriggerItemIds: string[];
+  /** Set of item ids whose triggers are disabled. */
   disabledItemIds: Set<string>;
+  /** Moves focus to the given item's trigger. */
   focusTrigger: (itemId: string) => void;
+  /** Registers a content panel as mounted. */
   registerPanel: (itemId: string) => void;
+  /** Removes a previously registered content panel. */
   unregisterPanel: (itemId: string) => void;
 };
 
+/** Context value published by `Accordion.Item` to its header and content. */
 export type AccordionItemContextValue = {
+  /** Id of the trigger button. */
   buttonId: string;
+  /** Id of the content panel. */
   panelId: string;
+  /** Stable value identifying this item. */
   itemId: string;
+  /** Whether this item is currently expanded. */
   isExpanded: boolean;
 };

package/src/Alert/Alert.tsx

@@ -1,4 +1,6 @@
-import { Slot } from "../Slot";
+import type { ReactElement } from "react";
+
+import { Slot } from "../Slot/index.ts";
 import { AlertProps } from "./types";
 
 /**
@@ -30,7 +32,11 @@ import { AlertProps } from "./types";
  * </Alert>
  * ```
  */
-export function Alert({ asChild = false, children, ...rest }: AlertProps) {
+export function Alert({
+  asChild = false,
+  children,
+  ...rest
+}: AlertProps): ReactElement {
   const rootProps = { role: "alert", ...rest };
 
   if (asChild) {
@@ -40,4 +46,5 @@ export function Alert({ asChild = false, children, ...rest }: AlertProps) {
   return <div {...rootProps}>{children}</div>;
 }
 
+/** @internal */
 Alert.displayName = "Alert";

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

@@ -1,4 +1,4 @@
-import { Alert } from "..";
+import { Alert } from "../index.ts";
 import { render, screen } from "@testing-library/react";
 
 describe("Alert component", () => {

package/src/Alert/types.ts

@@ -1,5 +1,6 @@
 import { ComponentProps } from "react";
 
+/** Props for the `Alert` — a live-region `<div role="alert">`; native `<div>` props plus `asChild`. */
 export type AlertProps = ComponentProps<"div"> & {
   asChild?: boolean;
 };

package/src/Avatar/Avatar.tsx

@@ -1,9 +1,10 @@
 import { useEffect, useMemo, useState } from "react";
+import type { ReactElement } from "react";
 
-import { Slot } from "../Slot";
+import { Slot } from "../Slot/index.ts";
 
 import { AvatarContext } from "./AvatarContext";
-import { useAvatarContext, useAvatarImage } from "./hooks";
+import { useAvatarContext, useAvatarImage } from "./hooks/index.ts";
 import {
   AvatarFallbackProps,
   AvatarImageLoadingStatus,
@@ -22,7 +23,11 @@ import {
  * **`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) {
+export function AvatarRoot({
+  asChild = false,
+  children,
+  ...rest
+}: AvatarRootProps): ReactElement {
   const [status, setStatus] = useState<AvatarImageLoadingStatus>("idle");
 
   const contextValue = useMemo(() => ({ status, setStatus }), [status]);
@@ -40,6 +45,7 @@ function AvatarRoot({ asChild = false, children, ...rest }: AvatarRootProps) {
   );
 }
 
+/** @internal */
 AvatarRoot.displayName = "AvatarRoot";
 
 /**
@@ -55,7 +61,11 @@ AvatarRoot.displayName = "AvatarRoot";
  *
  * @throws if rendered outside an `Avatar.Root`.
  */
-function AvatarImage({ asChild = false, children, ...rest }: AvatarImageProps) {
+export function AvatarImage({
+  asChild = false,
+  children,
+  ...rest
+}: AvatarImageProps): ReactElement {
   const { status, setStatus } = useAvatarContext();
   const { ref, onLoad, onError } = useAvatarImage(setStatus);
 
@@ -77,6 +87,7 @@ function AvatarImage({ asChild = false, children, ...rest }: AvatarImageProps) {
   return <img {...imageProps} ref={ref} />;
 }
 
+/** @internal */
 AvatarImage.displayName = "AvatarImage";
 
 /**
@@ -92,12 +103,12 @@ AvatarImage.displayName = "AvatarImage";
  *
  * @throws if rendered outside an `Avatar.Root`.
  */
-function AvatarFallback({
+export function AvatarFallback({
   delayMs,
   asChild = false,
   children,
   ...rest
-}: AvatarFallbackProps) {
+}: AvatarFallbackProps): ReactElement | null {
   const { status } = useAvatarContext();
   const [delayElapsed, setDelayElapsed] = useState(delayMs === undefined);
 
@@ -122,9 +133,11 @@ function AvatarFallback({
   return <span {...fallbackProps}>{children}</span>;
 }
 
+/** @internal */
 AvatarFallback.displayName = "AvatarFallback";
 
-type TAvatarCompound = typeof AvatarRoot & {
+/** 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;

package/src/Avatar/AvatarContext.ts

@@ -1,4 +1,5 @@
-import { createStrictContext } from "../utils";
+import type { Context } from "react";
+import { createStrictContext } from "../utils/index.ts";
 
 import { AvatarImageLoadingStatus } from "./types";
 
@@ -13,8 +14,13 @@ export type AvatarContextValue = {
   setStatus: (status: AvatarImageLoadingStatus) => void;
 };
 
-export const [AvatarContext, useAvatarContext] =
-  createStrictContext<AvatarContextValue>(
-    "Avatar.Image and Avatar.Fallback must be rendered inside an <Avatar.Root>.",
-    "AvatarContext",
-  );
+const avatarContextPair = createStrictContext<AvatarContextValue>(
+  "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: Context<AvatarContextValue | null> =
+  avatarContextPair[0];
+/** Hook returning the {@link AvatarContextValue}; throws when used outside an `<Avatar.Root>`. */
+export const useAvatarContext: () => AvatarContextValue = avatarContextPair[1];