@primitiv-ui/react 0.1.0 → 0.1.2

package/src/Breadcrumb/Breadcrumb.tsx

@@ -1,4 +1,6 @@
-import { Slot } from "../Slot";
+import type { ReactElement } from "react";
+
+import { Slot } from "../Slot/index.ts";
 
 import {
   BreadcrumbItemProps,
@@ -24,7 +26,10 @@ import {
  * </Breadcrumb.Root>
  * ```
  */
-function BreadcrumbRoot({ children, ...rest }: BreadcrumbRootProps) {
+export function BreadcrumbRoot({
+  children,
+  ...rest
+}: BreadcrumbRootProps): ReactElement {
   return (
     <nav aria-label="Breadcrumb" {...rest}>
       {children}
@@ -32,6 +37,7 @@ function BreadcrumbRoot({ children, ...rest }: BreadcrumbRootProps) {
   );
 }
 
+/** @internal */
 BreadcrumbRoot.displayName = "BreadcrumbRoot";
 
 /**
@@ -51,10 +57,14 @@ BreadcrumbRoot.displayName = "BreadcrumbRoot";
  * </Breadcrumb.List>
  * ```
  */
-function BreadcrumbList({ children, ...rest }: BreadcrumbListProps) {
+export function BreadcrumbList({
+  children,
+  ...rest
+}: BreadcrumbListProps): ReactElement {
   return <ol {...rest}>{children}</ol>;
 }
 
+/** @internal */
 BreadcrumbList.displayName = "BreadcrumbList";
 
 /**
@@ -70,10 +80,14 @@ BreadcrumbList.displayName = "BreadcrumbList";
  * </Breadcrumb.Item>
  * ```
  */
-function BreadcrumbItem({ children, ...rest }: BreadcrumbItemProps) {
+export function BreadcrumbItem({
+  children,
+  ...rest
+}: BreadcrumbItemProps): ReactElement {
   return <li {...rest}>{children}</li>;
 }
 
+/** @internal */
 BreadcrumbItem.displayName = "BreadcrumbItem";
 
 /**
@@ -98,17 +112,18 @@ BreadcrumbItem.displayName = "BreadcrumbItem";
  * </Breadcrumb.Link>
  * ```
  */
-function BreadcrumbLink({
+export function BreadcrumbLink({
   children,
   asChild = false,
   ...rest
-}: BreadcrumbLinkProps) {
+}: BreadcrumbLinkProps): ReactElement {
   if (asChild) {
     return <Slot {...rest}>{children}</Slot>;
   }
   return <a {...rest}>{children}</a>;
 }
 
+/** @internal */
 BreadcrumbLink.displayName = "BreadcrumbLink";
 
 /**
@@ -125,7 +140,10 @@ BreadcrumbLink.displayName = "BreadcrumbLink";
  * </Breadcrumb.Item>
  * ```
  */
-function BreadcrumbPage({ children, ...rest }: BreadcrumbPageProps) {
+export function BreadcrumbPage({
+  children,
+  ...rest
+}: BreadcrumbPageProps): ReactElement {
   return (
     <span aria-current="page" {...rest}>
       {children}
@@ -133,6 +151,7 @@ function BreadcrumbPage({ children, ...rest }: BreadcrumbPageProps) {
   );
 }
 
+/** @internal */
 BreadcrumbPage.displayName = "BreadcrumbPage";
 
 /**
@@ -157,10 +176,10 @@ BreadcrumbPage.displayName = "BreadcrumbPage";
  * <Breadcrumb.Separator><ChevronRight /></Breadcrumb.Separator>
  * ```
  */
-function BreadcrumbSeparator({
+export function BreadcrumbSeparator({
   children = "/",
   ...rest
-}: BreadcrumbSeparatorProps) {
+}: BreadcrumbSeparatorProps): ReactElement {
   return (
     <li role="presentation" aria-hidden="true" {...rest}>
       {children}
@@ -168,9 +187,11 @@ function BreadcrumbSeparator({
   );
 }
 
+/** @internal */
 BreadcrumbSeparator.displayName = "BreadcrumbSeparator";
 
-type TBreadcrumbCompound = typeof BreadcrumbRoot & {
+/** 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;
@@ -229,6 +250,7 @@ const BreadcrumbCompound: TBreadcrumbCompound = Object.assign(BreadcrumbRoot, {
   Separator: BreadcrumbSeparator,
 });
 
+/** @internal */
 BreadcrumbCompound.displayName = "Breadcrumb";
 
 export { BreadcrumbCompound as Breadcrumb };

package/src/Button/Button.tsx

@@ -1,4 +1,6 @@
-import { Slot } from "../Slot";
+import type { ReactElement } from "react";
+
+import { Slot } from "../Slot/index.ts";
 import { ButtonProps } from "./types";
 
 /**
@@ -73,7 +75,7 @@ export function Button({
   children,
   ref,
   ...rest
-}: ButtonProps) {
+}: ButtonProps): ReactElement {
   const rootProps = {
     ...rest,
     ref,
@@ -92,4 +94,5 @@ export function Button({
   );
 }
 
+/** @internal */
 Button.displayName = "Button";

package/src/Button/types.ts

@@ -1,5 +1,9 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
+/**
+ * Props for {@link Button} — all native `<button>` attributes (with `type`
+ * defaulting to `"button"`) plus the `asChild` escape hatch and a typed `ref`.
+ */
 export type ButtonProps = Omit<ComponentProps<"button">, "type"> & {
   type?: "button" | "submit" | "reset";
   asChild?: boolean;

package/src/Carousel/Carousel.tsx

@@ -1,13 +1,19 @@
 import { forwardRef, MouseEvent, useCallback } from "react";
+import type {
+  ForwardRefExoticComponent,
+  PropsWithoutRef,
+  ReactElement,
+  RefAttributes,
+} from "react";
 
-import { Slot } from "../Slot";
+import { Slot } from "../Slot/index.ts";
 import { CarouselProvider } from "./CarouselContext";
 import {
   useCarouselContext,
   useCarouselRoot,
   useCarouselSlide,
   useCarouselViewport,
-} from "./hooks";
+} from "./hooks/index.ts";
 import type {
   CarouselImperativeApi,
   CarouselRootProps,
@@ -69,10 +75,9 @@ import type {
  * <Carousel.Root ariaLabelledBy="promos">…</Carousel.Root>
  * ```
  */
-export const CarouselRoot = forwardRef<
-  CarouselImperativeApi,
-  CarouselRootProps
->(function CarouselRoot(
+export const CarouselRoot: ForwardRefExoticComponent<
+  PropsWithoutRef<CarouselRootProps> & RefAttributes<CarouselImperativeApi>
+> = forwardRef<CarouselImperativeApi, CarouselRootProps>(function CarouselRoot(
   {
     className = "",
     ariaLabel,
@@ -185,7 +190,7 @@ export function CarouselViewport({
   className = "",
   children,
   ...rest
-}: CarouselViewportProps) {
+}: CarouselViewportProps): ReactElement {
   const { isAutoRotating, ids } = useCarouselContext();
   const { viewportRef, onKeyDown } = useCarouselViewport();
 
@@ -205,6 +210,7 @@ export function CarouselViewport({
   );
 }
 
+/** @internal */
 CarouselViewport.displayName = "CarouselViewport";
 
 /**
@@ -254,7 +260,7 @@ export function CarouselSlide({
   ariaLabel,
   children,
   ...rest
-}: CarouselSlideProps) {
+}: CarouselSlideProps): ReactElement {
   const { slideRef, index, total, state } = useCarouselSlide();
   const { translations } = useCarouselContext();
   const autoLabel =
@@ -281,6 +287,7 @@ export function CarouselSlide({
   );
 }
 
+/** @internal */
 CarouselSlide.displayName = "CarouselSlide";
 
 /**
@@ -311,7 +318,7 @@ export function CarouselNextTrigger({
   asChild = false,
   children,
   ...rest
-}: CarouselNextTriggerProps) {
+}: CarouselNextTriggerProps): ReactElement {
   const { next, canGoNext, ids } = useCarouselContext();
   const isDisabled = disabled === true || !canGoNext;
 
@@ -348,6 +355,7 @@ export function CarouselNextTrigger({
   );
 }
 
+/** @internal */
 CarouselNextTrigger.displayName = "CarouselNextTrigger";
 
 /**
@@ -377,7 +385,7 @@ export function CarouselPreviousTrigger({
   asChild = false,
   children,
   ...rest
-}: CarouselPreviousTriggerProps) {
+}: CarouselPreviousTriggerProps): ReactElement {
   const { previous, canGoPrevious, ids } = useCarouselContext();
   const isDisabled = disabled === true || !canGoPrevious;
 
@@ -410,6 +418,7 @@ export function CarouselPreviousTrigger({
   );
 }
 
+/** @internal */
 CarouselPreviousTrigger.displayName = "CarouselPreviousTrigger";
 
 /**
@@ -445,7 +454,7 @@ export function CarouselIndicatorGroup({
   ariaLabelledBy,
   children,
   ...rest
-}: CarouselIndicatorGroupProps) {
+}: CarouselIndicatorGroupProps): ReactElement {
   const { ids } = useCarouselContext();
 
   return (
@@ -464,6 +473,7 @@ export function CarouselIndicatorGroup({
   );
 }
 
+/** @internal */
 CarouselIndicatorGroup.displayName = "CarouselIndicatorGroup";
 
 /**
@@ -497,7 +507,7 @@ export function CarouselIndicator({
   asChild = false,
   children,
   ...rest
-}: CarouselIndicatorProps) {
+}: CarouselIndicatorProps): ReactElement {
   const { goTo, currentPage, translations } = useCarouselContext();
   const isActive = index === currentPage;
 
@@ -530,6 +540,7 @@ export function CarouselIndicator({
   );
 }
 
+/** @internal */
 CarouselIndicator.displayName = "CarouselIndicator";
 
 /**
@@ -552,7 +563,9 @@ CarouselIndicator.displayName = "CarouselIndicator";
  * <Carousel.Indicators label="Choose slide" />
  * ```
  */
-export function CarouselIndicators(props: CarouselIndicatorsProps) {
+export function CarouselIndicators(
+  props: CarouselIndicatorsProps,
+): ReactElement {
   const { totalPages } = useCarouselContext();
 
   return (
@@ -564,6 +577,7 @@ export function CarouselIndicators(props: CarouselIndicatorsProps) {
   );
 }
 
+/** @internal */
 CarouselIndicators.displayName = "CarouselIndicators";
 
 /**
@@ -594,7 +608,7 @@ export function CarouselPlayPauseTrigger({
   asChild = false,
   children,
   ...rest
-}: CarouselPlayPauseTriggerProps) {
+}: CarouselPlayPauseTriggerProps): ReactElement {
   const { playing, togglePlaying, translations, ids, autoplayEnabled } =
     useCarouselContext();
 
@@ -637,8 +651,10 @@ export function CarouselPlayPauseTrigger({
   );
 }
 
+/** @internal */
 CarouselPlayPauseTrigger.displayName = "CarouselPlayPauseTrigger";
 
+/** Static-property shape of the compound {@link Carousel} export: the callable {@link CarouselRoot} plus its namespaced sub-components. */
 type CarouselCompound = typeof CarouselRoot & {
   Root: typeof CarouselRoot;
   Viewport: typeof CarouselViewport;

package/src/Carousel/CarouselContext.ts

@@ -1,11 +1,15 @@
-import { createContext } from "react";
+import { createContext, type Context, type Provider } from "react";
 
 import type { CarouselContextValue } from "./types";
 
-export const CarouselContext = createContext<CarouselContextValue | null>(null);
+/** React context carrying the {@link CarouselContextValue} shared by the carousel's sub-components. */
+export const CarouselContext: Context<CarouselContextValue | null> =
+  createContext<CarouselContextValue | null>(null);
 
 CarouselContext.displayName = "CarouselContext";
 
-const CarouselProvider = CarouselContext.Provider;
+/** Provider for {@link CarouselContext}; wraps the carousel subtree with its shared state. */
+const CarouselProvider: Provider<CarouselContextValue | null> =
+  CarouselContext.Provider;
 
 export { CarouselProvider };

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

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel.NextTrigger asChild", () => {
   it("should render the supplied child element and route the click through to the page-advance handler", async () => {

package/src/Carousel/__tests__/Carousel.auto-play.test.tsx

@@ -1,6 +1,6 @@
 import { act, fireEvent, render, screen } from "@testing-library/react";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel autoplay timer", () => {
   beforeEach(() => {

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

@@ -1,6 +1,6 @@
 import { render, screen } from "@testing-library/react";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel basic rendering tests", () => {
   describe("Carousel.Root", () => {

package/src/Carousel/__tests__/Carousel.controlled-state.test.tsx

@@ -2,7 +2,7 @@ import { useState } from "react";
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel controlled page state", () => {
   it("should derive the active slide from the controlled page prop", () => {

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

@@ -1,6 +1,6 @@
 import { render, screen } from "@testing-library/react";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel error handling", () => {
   it("should throw when Carousel.PlayPauseTrigger is rendered without autoplay enabled on Carousel.Root", () => {

package/src/Carousel/__tests__/Carousel.ids.test.tsx

@@ -1,6 +1,6 @@
 import { render, screen } from "@testing-library/react";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel custom ids", () => {
   it("should apply ids.root to the rendered <section>", () => {

package/src/Carousel/__tests__/Carousel.imperative-api.test.tsx

@@ -1,8 +1,8 @@
 import { createRef, useRef } from "react";
 import { act, render, screen } from "@testing-library/react";
 
-import { Carousel } from "..";
-import type { CarouselImperativeApi } from "..";
+import { Carousel } from "../index.ts";
+import type { CarouselImperativeApi } from "../index.ts";
 
 function ImperativeFixture({
   apiRef,

package/src/Carousel/__tests__/Carousel.indicators.test.tsx

@@ -2,7 +2,7 @@ import { useState } from "react";
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel.IndicatorGroup", () => {
   it('should render with role="group"', () => {

package/src/Carousel/__tests__/Carousel.intersection-observer.test.tsx

@@ -2,8 +2,8 @@ import { RefObject, useRef } from "react";
 import { act, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
-import type { CarouselImperativeApi } from "..";
+import { Carousel } from "../index.ts";
+import type { CarouselImperativeApi } from "../index.ts";
 import { MockIntersectionObserver } from "../../test/intersectionObserverPolyfill";
 
 describe("Carousel IntersectionObserver fallback + isInView", () => {

package/src/Carousel/__tests__/Carousel.keyboard-navigation.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel keyboard navigation", () => {
   it("should advance the active page when ArrowRight is pressed with the viewport focused", async () => {

package/src/Carousel/__tests__/Carousel.play-pause.test.tsx

@@ -2,7 +2,7 @@ import { useState } from "react";
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel.PlayPauseTrigger basic shape", () => {
   it("should render the PlayPauseTrigger as <button type='button'>", () => {

package/src/Carousel/__tests__/Carousel.prev-next.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 function renderWithSlides(
   rootProps: { defaultPage?: number } = {},

package/src/Carousel/__tests__/Carousel.reduced-motion.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 function mockReducedMotion(matches: boolean) {
   window.matchMedia = vi.fn().mockImplementation((query: string) => ({

package/src/Carousel/__tests__/Carousel.refresh-progress.test.tsx

@@ -1,8 +1,8 @@
 import { createRef } from "react";
 import { act, render, screen } from "@testing-library/react";
 
-import { Carousel } from "..";
-import type { CarouselImperativeApi } from "..";
+import { Carousel } from "../index.ts";
+import type { CarouselImperativeApi } from "../index.ts";
 
 function fixture(apiRef: React.Ref<CarouselImperativeApi>, slides = 3) {
   return (

package/src/Carousel/__tests__/Carousel.scroll-snap-change.test.tsx

@@ -1,6 +1,6 @@
 import { act, render, screen } from "@testing-library/react";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 function fireScrollSnapChange(viewport: HTMLElement, snapTarget: HTMLElement) {
   const event = new Event("scrollsnapchange", { bubbles: false });

package/src/Carousel/__tests__/Carousel.scroll-sync.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel scroll sync (programmatic page change)", () => {
   it("should call scrollIntoView on the first slide of the target page when the active page changes", async () => {

package/src/Carousel/__tests__/Carousel.slides-per-move.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel numeric slidesPerMove", () => {
   it("should render `floor((total - slidesPerPage) / slidesPerMove) + 1` indicators", () => {

package/src/Carousel/__tests__/Carousel.slides-per-page.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel slidesPerPage", () => {
   it("should mark every slide on the active page as active when slidesPerPage > 1", () => {

package/src/Carousel/__tests__/Carousel.touch-interaction.test.tsx

@@ -1,6 +1,6 @@
 import { act, fireEvent, render, screen } from "@testing-library/react";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel autoplay touch-pause (WCAG 2.2.2)", () => {
   beforeEach(() => {

package/src/Carousel/__tests__/Carousel.transition-modes.test.tsx

@@ -1,7 +1,7 @@
 import { act, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 function fireScrollSnapChange(
   viewport: HTMLElement,

package/src/Carousel/__tests__/Carousel.translations.test.tsx

@@ -1,6 +1,6 @@
 import { render, screen } from "@testing-library/react";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel translations", () => {
   it("should override the slide aria-label format via translations.slideLabel", () => {

package/src/Carousel/__tests__/Carousel.uncontrolled-state.test.tsx

@@ -1,7 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
-import { Carousel } from "..";
+import { Carousel } from "../index.ts";
 
 describe("Carousel uncontrolled page state", () => {
   it("should mark the slide at index 0 as active by default when no defaultPage is provided", () => {

package/src/Carousel/types.ts

@@ -153,6 +153,7 @@ export type CarouselTranslations = {
   stopSlideshow?: string;
 };
 
+/** Props for `Carousel.Root` — the labelled `<section>` wrapping the whole widget; combines label, page-state, and playing-state shapes with autoplay, transition, and layout options. */
 export type CarouselRootProps = Omit<
   ComponentProps<"section">,
   "aria-label" | "aria-labelledby"
@@ -278,8 +279,10 @@ export type CarouselContextValue = {
   isProgrammaticScrollRef: RefObject<boolean>;
 };
 
+/** Props for `Carousel.Viewport` — the scroll-snap slide container; accepts all native `<div>` props. */
 export type CarouselViewportProps = ComponentProps<"div">;
 
+/** Props for `Carousel.Slide` — an individual slide that self-registers with the Root; native `<div>` props plus an optional accessible-label override. */
 export type CarouselSlideProps = Omit<ComponentProps<"div">, "aria-label"> & {
   /** Override the auto-generated `"N of M"` `aria-label`. Use this when
    * the slide has a more meaningful description than its position
@@ -288,6 +291,7 @@ export type CarouselSlideProps = Omit<ComponentProps<"div">, "aria-label"> & {
   ariaLabel?: string;
 };
 
+/** Props for `Carousel.NextTrigger` — the button that advances one page; native `<button>` props plus `asChild`. */
 export type CarouselNextTriggerProps = ComponentProps<"button"> & {
   /** Render the child element instead of the default `<button>`. All
    * trigger props (onClick, disabled, ids.nextTrigger, …) are merged
@@ -295,6 +299,7 @@ export type CarouselNextTriggerProps = ComponentProps<"button"> & {
   asChild?: boolean;
 };
 
+/** Props for `Carousel.PreviousTrigger` — the button that retreats one page; native `<button>` props plus `asChild`. */
 export type CarouselPreviousTriggerProps = ComponentProps<"button"> & {
   /** See `CarouselNextTriggerProps.asChild`. */
   asChild?: boolean;
@@ -315,6 +320,7 @@ export type CarouselIndicatorGroupProps = Omit<
     | { label?: never; ariaLabelledBy: string }
   );
 
+/** Props for `Carousel.Indicator` — a button that jumps to its target page; native `<button>` props plus the target `index` and `asChild`. */
 export type CarouselIndicatorProps = ComponentProps<"button"> & {
   /** Zero-based page this indicator targets. Clicking jumps to it. */
   index: number;
@@ -357,6 +363,7 @@ export type CarouselImperativeApi = {
   isInView: (slideIndex: number) => boolean;
 };
 
+/** Live progress snapshot reported by the carousel: the active page, the total page count, and a normalised `value` in `[0, 1]`. */
 export type CarouselProgress = {
   page: number;
   totalPages: number;
@@ -388,6 +395,7 @@ export type CarouselPlayPauseTriggerChildren =
   | ReactNode
   | ((state: { playing: boolean }) => ReactNode);
 
+/** Props for `Carousel.PlayPauseTrigger` — toggles autoplay; native `<button>` props with a state-aware render-prop `children` and `asChild`. */
 export type CarouselPlayPauseTriggerProps = Omit<
   ComponentProps<"button">,
   "children"