@primitiv-ui/react 0.1.0

package/src/Carousel/hooks/useCarouselViewport.ts

@@ -0,0 +1,290 @@
+import { KeyboardEvent, useCallback, useEffect, useMemo, useRef } from "react";
+
+import { useCarouselContext } from "./useCarouselContext";
+
+/**
+ * Owns the Viewport-side scroll-state sync — bidirectional.
+ *
+ * **State → scroll.** When `currentPage` flips for any reason
+ * (NextTrigger, Indicator click, autoplay tick, imperative goTo), the
+ * effect locates the first slide of the target page via the published
+ * `slidesRef`, reads its `getBoundingClientRect` relative to the
+ * viewport, and calls `scrollTo` so the visual surface tracks React
+ * state. The current `scrollLeft` is included in the target so the
+ * calculation is correct mid-scroll. The run also asserts
+ * `isProgrammaticScrollRef` so the IntersectionObserver fallback
+ * doesn't treat the in-flight animation as a user scroll and undo the
+ * page change; the flag clears on `scrollend` (with a timeout
+ * fallback for environments that don't fire it).
+ *
+ * **Scroll → state.** When the user swipes the viewport, the browser
+ * fires `scrollsnapchange` with the new snap target. The handler
+ * looks up which slide that target is, computes
+ * `floor(slideIndex / slidesPerPage)`, and calls `goTo` on the new
+ * page (skipping when the page is unchanged so consumers don't see
+ * spurious onPageChange callbacks, and bailing when the snap target
+ * isn't one of our registered slides). An `IntersectionObserver`
+ * provides the same page-drive for browsers without `scrollsnapchange`,
+ * but stands down when the event is supported (it is authoritative);
+ * the observer still always feeds `isInView`.
+ *
+ * **Keyboard → state.** Returns an `onKeyDown` handler that wires the
+ * WAI-ARIA Carousel pattern arrow keys (`ArrowRight` / `ArrowLeft` for
+ * next / previous) plus `Home` / `End` (first / last) onto the same
+ * imperative API the trigger buttons call, so smooth scroll matches
+ * the click path. The handler only fires when the Viewport itself is
+ * the focus target — focus inside a slide keeps its native arrow-key
+ * semantics — and respects `canGoNext` / `canGoPrevious` so it clamps
+ * at the ends.
+ */
+export function useCarouselViewport() {
+  const {
+    slidesRef,
+    slideKeys,
+    effectiveSlidesPerMove,
+    totalPages,
+    currentPage,
+    goTo,
+    next,
+    previous,
+    canGoNext,
+    canGoPrevious,
+    transition,
+    snapAlign,
+    refreshTick,
+    visibleSlideIndicesRef,
+    setSlideInView,
+    isProgrammaticScrollRef,
+  } = useCarouselContext();
+  const internalRef = useRef<HTMLDivElement>(null);
+  // Set to true by the scrollsnapchange handler and the IntersectionObserver
+  // callback before they call goTo(), so the scroll effect knows the page
+  // change originated from a user scroll (CSS snap already positioned the
+  // viewport) and must not call scrollTo() again.
+  const isUserScrollRef = useRef(false);
+
+  // Callback ref so the consumer can compose their own ref with ours
+  // via `composeRefs` later (cycle 22 introduces asChild). For now,
+  // it just stashes the node.
+  const viewportRef = useCallback((node: HTMLDivElement | null) => {
+    internalRef.current = node;
+  }, []);
+
+  // Read prefers-reduced-motion once on mount; choose scrollTo
+  // behavior accordingly so we don't fight the OS-level setting.
+  const scrollBehavior = useMemo<ScrollBehavior>(
+    () =>
+      window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
+        ? "instant"
+        : "smooth",
+    [],
+  );
+
+  useEffect(() => {
+    // transition="none" hands the visual to consumer CSS; we don't
+    // touch viewport.scrollTo at all in that mode.
+    if (transition !== "slide") return;
+    const firstSlideIndex = currentPage * effectiveSlidesPerMove;
+    const firstSlideKey = slideKeys[firstSlideIndex];
+    // No slides registered yet, or page out of range: nothing to scroll to.
+    if (!firstSlideKey) return;
+
+    // Both viewport ref and the slide element are guaranteed populated
+    // here — the effect runs post-commit (after callback refs fire) and
+    // any key in slideKeys was just registered into slidesRef in
+    // lockstep by useCarouselRoot.registerSlide.
+    // A user swipe via CSS scroll-snap has already positioned the viewport;
+    // calling scrollTo on top would start a second animation and cause jank.
+    if (isUserScrollRef.current) {
+      isUserScrollRef.current = false;
+      return;
+    }
+
+    const viewport = internalRef.current!;
+
+    // Mark the scroll as programmatic so the IntersectionObserver
+    // doesn't treat the in-flight animation as a user scroll and undo
+    // the page change. next() / previous() also set this — re-asserting
+    // here covers indicator-driven goTo and the initial scroll on
+    // mount, neither of which goes through next() / previous().
+    isProgrammaticScrollRef.current = true;
+
+    // Native-first: delegate the horizontal scroll to the browser via
+    // scrollIntoView rather than computing scrollLeft ourselves. The
+    // consumer's `scroll-snap-align` then makes the final correction so
+    // we never fight the snap engine. `inline` maps to snapAlign;
+    // `block: "nearest"` keeps the page from scrolling vertically.
+    const targetEl = slidesRef.current!.get(firstSlideKey)!;
+    targetEl.scrollIntoView({
+      behavior: scrollBehavior,
+      inline: snapAlign === "center" ? "center" : "start",
+      block: "nearest",
+    });
+
+    // Clear the programmatic-scroll guard once the animation settles.
+    // `scrollend` is the reliable signal in real browsers; the setTimeout
+    // is a fallback for environments (jsdom, older Safari) that don't fire
+    // it. The timeout is longer than any typical smooth-scroll duration so
+    // real-browser IO entries that fire mid-animation are still suppressed.
+    // Re-clearing the flag is harmless, so no idempotency guard is needed.
+    const clearFlag = () => {
+      isProgrammaticScrollRef.current = false;
+    };
+    viewport.addEventListener("scrollend", clearFlag, { once: true });
+    const timeoutId = setTimeout(() => {
+      viewport.removeEventListener("scrollend", clearFlag);
+      clearFlag();
+    }, 600);
+    return () => {
+      clearTimeout(timeoutId);
+      viewport.removeEventListener("scrollend", clearFlag);
+    };
+  }, [
+    transition,
+    snapAlign,
+    currentPage,
+    effectiveSlidesPerMove,
+    slideKeys,
+    slidesRef,
+    refreshTick,
+    scrollBehavior,
+  ]);
+
+  // User-driven scroll → state. Listen for scrollsnapchange and update
+  // currentPage from the snapped slide's index. The viewport ref is
+  // guaranteed populated post-commit (callback ref runs first).
+  useEffect(() => {
+    if (transition !== "slide") return;
+    const viewport = internalRef.current!;
+
+    const handler = (event: Event) => {
+      const target = (event as Event & { snapTargetInline?: Element })
+        .snapTargetInline;
+
+      // findIndex returns -1 when the snap target isn't one of our
+      // registered slides — e.g. a consumer-wrapped element inside the
+      // viewport. Ignore those; only registered slides drive the page.
+      const slideIndex = slideKeys.findIndex(
+        (key) => slidesRef.current!.get(key) === target,
+      );
+      if (slideIndex < 0) return;
+
+      const targetPage = Math.floor(slideIndex / effectiveSlidesPerMove);
+      if (targetPage !== currentPage) {
+        isUserScrollRef.current = true;
+        goTo(targetPage);
+      }
+    };
+
+    viewport.addEventListener("scrollsnapchange", handler);
+    return () => viewport.removeEventListener("scrollsnapchange", handler);
+  }, [
+    transition,
+    slideKeys,
+    slidesRef,
+    effectiveSlidesPerMove,
+    currentPage,
+    goTo,
+  ]);
+
+  // IntersectionObserver fallback for browsers without scrollsnapchange,
+  // and the source of truth for isInView() on the imperative API. The
+  // observer fires whenever a slide crosses the 0.6 visibility
+  // threshold; the lowest-index visible slide derives the active page.
+  useEffect(() => {
+    if (transition !== "slide") return;
+
+    // When the browser fires scrollsnapchange (Chrome 129+), that event is
+    // the authoritative source of the active page — snapTargetInline is the
+    // precisely-snapped slide. The observer below then only feeds isInView.
+    // Its lowest-index-visible heuristic is a coarse page fallback for
+    // browsers without the event, and would mis-track a centre-aligned
+    // carousel that shows several slides at once (it follows the leftmost
+    // visible slide, not the centred one), so it must not drive the page
+    // when the event is available.
+    const supportsSnapEvents = "onscrollsnapchange" in window;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        // Both lookups (slideKeys.findIndex → registered key, and the
+        // slidesRef get → element) are guaranteed to resolve: the
+        // observer only observes elements registered into slidesRef
+        // alongside their slideKey, and is disconnected on cleanup
+        // before slides can unmount.
+        for (const entry of entries) {
+          const idx = slideKeys.findIndex(
+            (key) => slidesRef.current!.get(key) === entry.target,
+          );
+          setSlideInView(
+            idx,
+            entry.isIntersecting && entry.intersectionRatio >= 0.6,
+          );
+        }
+
+        // isInView is updated above regardless; only the page-drive below
+        // is the fallback that scrollsnapchange supersedes.
+        if (supportsSnapEvents) return;
+
+        const visible = visibleSlideIndicesRef.current;
+        if (visible.size === 0) return;
+        const firstVisible = Math.min(...visible);
+        const targetPage = Math.floor(firstVisible / effectiveSlidesPerMove);
+        // Guard: if a programmatic scroll is in flight (e.g. user clicked
+        // NextTrigger and the smooth-scroll animation hasn't settled), the
+        // IO may still see the old slide as ≥0.6 visible. Calling goTo
+        // here would undo the navigation, so skip until the flag clears.
+        if (targetPage !== currentPage && !isProgrammaticScrollRef.current) {
+          isUserScrollRef.current = true;
+          goTo(targetPage);
+        }
+      },
+      { threshold: 0.6 },
+    );
+
+    for (const key of slideKeys) {
+      observer.observe(slidesRef.current!.get(key)!);
+    }
+
+    return () => observer.disconnect();
+  }, [
+    transition,
+    slideKeys,
+    slidesRef,
+    effectiveSlidesPerMove,
+    currentPage,
+    goTo,
+    setSlideInView,
+    visibleSlideIndicesRef,
+  ]);
+
+  // Keyboard navigation per the WAI-ARIA Carousel pattern: arrow keys
+  // route through the same imperative API as the trigger buttons so the
+  // smooth scroll and loop-wrap animation match the click path. The
+  // event.target === currentTarget guard restricts handling to the
+  // Viewport itself — focus inside a slide (e.g. on a link or form
+  // control) keeps its native arrow-key semantics.
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      // Restrict to keypresses originating on the Viewport itself —
+      // focus inside a slide (e.g. on a link or form control) keeps
+      // its native arrow-key semantics.
+      if (event.target !== event.currentTarget) return;
+      if (event.key === "ArrowRight") {
+        event.preventDefault();
+        if (canGoNext) next();
+      } else if (event.key === "ArrowLeft") {
+        event.preventDefault();
+        if (canGoPrevious) previous();
+      } else if (event.key === "Home") {
+        event.preventDefault();
+        goTo(0);
+      } else if (event.key === "End") {
+        event.preventDefault();
+        goTo(totalPages - 1);
+      }
+    },
+    [canGoNext, canGoPrevious, next, previous, goTo, totalPages],
+  );
+
+  return { viewportRef, onKeyDown };
+}

package/src/Carousel/index.ts

@@ -0,0 +1,3 @@
+export * from "./Carousel";
+export * from "./CarouselContext";
+export * from "./types";

package/src/Carousel/types.ts

@@ -0,0 +1,400 @@
+import { ComponentProps, ReactNode, RefObject } from "react";
+
+/**
+ * Discriminated label shape for `Carousel.Root` — exactly one of
+ * `ariaLabel` or `ariaLabelledBy` must be supplied so every carousel
+ * has an accessible name (per the WAI-ARIA Carousel pattern). TypeScript
+ * rejects shapes that supply both or neither.
+ */
+export type CarouselRootLabelProps =
+  | { ariaLabel: string; ariaLabelledBy?: never }
+  | { ariaLabel?: never; ariaLabelledBy: string };
+
+/**
+ * Uncontrolled page state — the Root owns the active page internally,
+ * optionally seeded by `defaultPage`. The discriminated union below
+ * rejects passing `page` or `onPageChange` alongside it.
+ */
+export type UncontrolledCarouselPageProps = {
+  /** Uncontrolled active page index. Defaults to `0`. */
+  defaultPage?: number;
+  page?: never;
+  onPageChange?: never;
+};
+
+/**
+ * Controlled page state — the parent owns the active page; the Root
+ * defers every state change back through `onPageChange`. Both props
+ * must be supplied together.
+ */
+export type ControlledCarouselPageProps = {
+  /** Controlled active page index. */
+  page: number;
+  /** Callback invoked when the active page should change (e.g. when the
+   * user clicks `Carousel.NextTrigger` or `Carousel.PreviousTrigger`).
+   * The callback is responsible for re-rendering with the new `page`. */
+  onPageChange: (page: number) => void;
+  defaultPage?: never;
+};
+
+/**
+ * Discriminated state union — TypeScript rejects mixed shapes (e.g.
+ * `defaultPage` + `page`, or `page` without `onPageChange`).
+ */
+export type CarouselRootPageStateProps =
+  | UncontrolledCarouselPageProps
+  | ControlledCarouselPageProps;
+
+/**
+ * Uncontrolled playing state — the Root owns the "playing" flag
+ * internally, optionally seeded by `defaultPlaying`.
+ */
+export type UncontrolledCarouselPlayingProps = {
+  /** Uncontrolled initial playing flag. Defaults to `false`. */
+  defaultPlaying?: boolean;
+  playing?: never;
+  onPlayingChange?: never;
+};
+
+/**
+ * Controlled playing state — the parent owns the "playing" flag; the
+ * Root defers every change back through `onPlayingChange`. Both props
+ * must be supplied together.
+ */
+export type ControlledCarouselPlayingProps = {
+  /** Controlled playing flag. */
+  playing: boolean;
+  /** Callback invoked when the playing flag should toggle. The callback
+   * is responsible for re-rendering with the new `playing` value. */
+  onPlayingChange: (playing: boolean) => void;
+  defaultPlaying?: never;
+};
+
+/**
+ * Discriminated playing-state union — mirrors the page-state pattern.
+ */
+export type CarouselRootPlayingStateProps =
+  | UncontrolledCarouselPlayingProps
+  | ControlledCarouselPlayingProps;
+
+/**
+ * Autoplay configuration. Pass `true` for the default 4000ms cadence,
+ * `false` (default) to disable autoplay entirely, or `{ delay: N }` to
+ * tune the interval. The active page advances on each tick while
+ * `playing` is `true`; the timer stops once the active page reaches the
+ * last slide.
+ */
+export type CarouselAutoplay = boolean | { delay: number };
+
+/**
+ * Visual transition mode for the viewport.
+ *
+ * - `"slide"` (default) — relies on native CSS scroll-snap; the
+ *   Viewport scrolls programmatically when the page changes and
+ *   listens for `scrollsnapchange` to update React state when the
+ *   user swipes.
+ * - `"none"` — the Viewport installs no scroll wiring at all.
+ *   Consumer CSS owns the visual transition (e.g. crossfade,
+ *   dissolve) via the `data-state` hook on each slide, which still
+ *   flips with the active page.
+ */
+export type CarouselTransition = "slide" | "none";
+
+/**
+ * Scroll-snap alignment that the Viewport should target when
+ * programmatically scrolling to a page.
+ *
+ * - `"start"` (default) — scrolls so the first slide of the target
+ *   page aligns with the **start** (left) edge of the Viewport.
+ *   Matches `scroll-snap-align: start` in consumer CSS.
+ * - `"center"` — scrolls so the first slide of the target page is
+ *   **centred** in the Viewport. The target is offset inward by
+ *   `(viewportWidth − slideWidth) / 2`. Use this with
+ *   `scroll-snap-align: center` in consumer CSS (e.g. Cover Flow
+ *   layouts where slides are narrower than the Viewport).
+ */
+export type CarouselSnapAlign = "start" | "center";
+
+/**
+ * Pin DOM `id`s on the rendered sub-components for SSR / hydration
+ * stability or for external `aria-controls` references. Any keys you
+ * omit leave the corresponding element unidentified (or with whatever
+ * the consumer attaches to that sub-component directly via its own
+ * `id` prop, which always wins).
+ */
+export type CarouselIds = {
+  root?: string;
+  viewport?: string;
+  previousTrigger?: string;
+  nextTrigger?: string;
+  playPauseTrigger?: string;
+  indicatorGroup?: string;
+};
+
+/**
+ * Override the default user-visible strings the component owns —
+ * intended for internationalisation. Any keys you omit fall back to
+ * the English defaults.
+ */
+export type CarouselTranslations = {
+  /** Format used for the auto-generated slide aria-label. Receives
+   * 1-indexed `index` and the live `total`. Default:
+   * `({ index, total }) => "${index} of ${total}"`. */
+  slideLabel?: (params: { index: number; total: number }) => string;
+  /** Format used for the auto-generated indicator aria-label. Receives
+   * the 1-indexed page position. Default:
+   * `({ index }) => "Slide ${index}"`. */
+  indicatorLabel?: (params: { index: number }) => string;
+  /** Accessible name for `Carousel.PlayPauseTrigger` while paused.
+   * Default: `"Start automatic slide show"`. */
+  startSlideshow?: string;
+  /** Accessible name for `Carousel.PlayPauseTrigger` while playing.
+   * Default: `"Stop automatic slide show"`. */
+  stopSlideshow?: string;
+};
+
+export type CarouselRootProps = Omit<
+  ComponentProps<"section">,
+  "aria-label" | "aria-labelledby"
+> &
+  CarouselRootLabelProps &
+  CarouselRootPageStateProps &
+  CarouselRootPlayingStateProps & {
+    /** Autoplay configuration — see {@link CarouselAutoplay}. */
+    autoplay?: CarouselAutoplay;
+    /** Visual transition mode — see {@link CarouselTransition}.
+     * Defaults to `"slide"`. */
+    transition?: CarouselTransition;
+    /** Number of slides visible per page. Defaults to `1`. With values
+     * greater than `1`, slides are grouped into pages of that size for
+     * navigation purposes: indicators auto-render per page, boundary
+     * clamp moves to the last page, and `Carousel.NextTrigger` /
+     * `Carousel.PreviousTrigger` advance one page at a time. */
+    slidesPerPage?: number;
+    /** Number of slides advanced by `Carousel.NextTrigger` /
+     * `Carousel.PreviousTrigger`. `"auto"` (default) advances one
+     * full page at a time (= `slidesPerPage`); a number advances
+     * exactly that many slides per click and pages are computed so
+     * the visible window always stays full. */
+    slidesPerMove?: number | "auto";
+    /** Override the default user-visible strings the component owns —
+     * see {@link CarouselTranslations}. Useful for i18n. */
+    translations?: CarouselTranslations;
+    /** Pin DOM `id`s on the rendered sub-components — see
+     * {@link CarouselIds}. Useful for SSR hydration stability and
+     * external `aria-controls` linkage. */
+    ids?: CarouselIds;
+    /** Scroll-snap alignment the Viewport targets when programmatically
+     * scrolling to a page — see {@link CarouselSnapAlign}.
+     * Defaults to `"start"`. Set to `"center"` when consumer CSS uses
+     * `scroll-snap-align: center` on slides (e.g. Cover Flow layouts
+     * where slides are narrower than the Viewport). */
+    snapAlign?: CarouselSnapAlign;
+  };
+
+/**
+ * Shape of the context published by `Carousel.Root` to descendants.
+ * Fields are added as future cycles introduce shared state (active
+ * page, autoplay, etc.).
+ */
+export type CarouselContextValue = {
+  /** Self-registers a slide. Called as a callback ref by `Carousel.Slide`
+   * with the rendered DOM node on mount and `null` on unmount. */
+  registerSlide: (key: string, element: HTMLDivElement | null) => void;
+  /** Live map from slide key to rendered DOM node. Used by the
+   * Viewport to read `getBoundingClientRect` on the first slide of
+   * the target page when programmatically scrolling. */
+  slidesRef: RefObject<Map<string, HTMLDivElement>>;
+  /** Ordered list of currently-mounted slide keys. The slide's index is
+   * its position in this array; the array's length is the total. */
+  slideKeys: string[];
+  /** Number of slides visible per page (default `1`). */
+  slidesPerPage: number;
+  /** Resolved slides advanced per Prev/Next click — equal to
+   * `slidesPerPage` when the consumer left `slidesPerMove="auto"`,
+   * else the numeric value. */
+  effectiveSlidesPerMove: number;
+  /** Live total page count — `ceil(total / slidesPerPage)` in `"auto"`
+   * mode (partial last page allowed), else
+   * `floor((total - slidesPerPage) / effectiveSlidesPerMove) + 1`
+   * (always full-windowed). Drives indicator count and boundary
+   * clamp. */
+  totalPages: number;
+  /** Zero-based index of the currently-active page. */
+  currentPage: number;
+  /** `true` when there is a forward navigation target (a page ahead of
+   * the active one). Drives the `disabled` attribute on
+   * `Carousel.NextTrigger` and short-circuits `next()` when there's
+   * nowhere to go. */
+  canGoNext: boolean;
+  /** `true` when there is a backward navigation target. Drives the
+   * `disabled` attribute on `Carousel.PreviousTrigger`. */
+  canGoPrevious: boolean;
+  /** Advance the active page by one step. No-op when `!canGoNext`. */
+  next: () => void;
+  /** Retreat the active page by one step. No-op when `!canGoPrevious`. */
+  previous: () => void;
+  /** Jump directly to `target` (zero-based page index). Used by
+   * `Carousel.Indicator` to dispatch click-to-jump. */
+  goTo: (target: number) => void;
+  /** Whether autoplay is currently in the "playing" state. */
+  playing: boolean;
+  /** Toggles `playing`. Used by `Carousel.PlayPauseTrigger`. */
+  togglePlaying: () => void;
+  /** `true` when the consumer enabled autoplay (regardless of the
+   * `playing` flag). Used by `Carousel.PlayPauseTrigger` to validate
+   * its own configuration. */
+  autoplayEnabled: boolean;
+  /** `true` when autoplay is enabled AND `playing` is `true` — i.e. the
+   * timer could fire any moment. Drives the Viewport's `aria-live`
+   * flip ("off" while auto-rotating, "polite" otherwise) so screen
+   * readers don't get spammed by every tick. */
+  isAutoRotating: boolean;
+  /** Translations merged with English defaults — every field is
+   * present, even if the consumer passed only a subset. */
+  translations: Required<CarouselTranslations>;
+  /** Custom DOM ids — every field optional. Sub-components apply
+   * their respective entry via spread, so consumer-supplied `id`
+   * props on the sub-component still win. */
+  ids: CarouselIds;
+  /** Resolved visual transition mode (defaults to `"slide"`). */
+  transition: CarouselTransition;
+  /** Resolved scroll-snap alignment (defaults to `"start"`). */
+  snapAlign: CarouselSnapAlign;
+  /** Bumped by `refresh()` to force the viewport's scroll-align
+   * effect to re-run without a page change. */
+  refreshTick: number;
+  /** Live set of slide indices currently visible per IntersectionObserver
+   * (≥ 60% intersection). Mutated by the Viewport hook and read by
+   * the imperative `isInView`. */
+  visibleSlideIndicesRef: RefObject<Set<number>>;
+  /** Used by the Viewport hook to record visibility transitions. */
+  setSlideInView: (slideIndex: number, inView: boolean) => void;
+  /** Set to `true` by `next()` and `previous()` the moment programmatic
+   * navigation begins, and cleared by the Viewport hook once the scroll
+   * animation settles (`scrollend` or a timeout fallback). The
+   * IntersectionObserver callback checks this flag before calling `goTo`
+   * so that IO entries firing mid-animation cannot undo the navigation. */
+  isProgrammaticScrollRef: RefObject<boolean>;
+};
+
+export type CarouselViewportProps = ComponentProps<"div">;
+
+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
+   * (e.g. `"Hand-picked for you"`). When omitted, slides are labelled
+   * with their live index and total in registration order. */
+  ariaLabel?: string;
+};
+
+export type CarouselNextTriggerProps = ComponentProps<"button"> & {
+  /** Render the child element instead of the default `<button>`. All
+   * trigger props (onClick, disabled, ids.nextTrigger, …) are merged
+   * onto the child via `Slot`. The child must accept a `ref`. */
+  asChild?: boolean;
+};
+
+export type CarouselPreviousTriggerProps = ComponentProps<"button"> & {
+  /** See `CarouselNextTriggerProps.asChild`. */
+  asChild?: boolean;
+};
+
+/**
+ * Discriminated label shape for `Carousel.IndicatorGroup` — exactly one
+ * of `label` (becomes `aria-label`) or `ariaLabelledBy` (points at an
+ * external label element) must be supplied. TypeScript rejects
+ * both-or-neither at compile time.
+ */
+export type CarouselIndicatorGroupProps = Omit<
+  ComponentProps<"div">,
+  "label" | "aria-labelledby"
+> &
+  (
+    | { label: string; ariaLabelledBy?: never }
+    | { label?: never; ariaLabelledBy: string }
+  );
+
+export type CarouselIndicatorProps = ComponentProps<"button"> & {
+  /** Zero-based page this indicator targets. Clicking jumps to it. */
+  index: number;
+  /** Render the child element instead of the default `<button>`.
+   * Trigger props (onClick, aria-label, aria-disabled, data-state)
+   * are merged onto the child via `Slot`. The child must accept a
+   * `ref`. */
+  asChild?: boolean;
+};
+
+/**
+ * Imperative handle exposed via `ref` on `Carousel.Root`. Routes
+ * through the same internal state machine the trigger components
+ * use, so controlled-mode `onPageChange` / `onPlayingChange` still
+ * fire as if the user had clicked.
+ */
+export type CarouselImperativeApi = {
+  /** Advance the active page by one. No-op on the last page. */
+  next: () => void;
+  /** Retreat the active page by one. No-op on the first page. */
+  previous: () => void;
+  /** Jump directly to `target` (zero-based page index). */
+  goTo: (target: number) => void;
+  /** Set `playing` to `true`. Dismisses the hover/focus pause for the
+   * lifetime of the resulting playing session. */
+  play: () => void;
+  /** Set `playing` to `false`. */
+  pause: () => void;
+  /** Re-issue the viewport's scrollTo for the current page. Call when
+   * external layout changes (window resize, container reflow) leave
+   * the scroll position misaligned with React state. */
+  refresh: () => void;
+  /** Live progress snapshot: the active page, the total page count,
+   * and a normalised `value` in `[0, 1]` (0 when there's at most one
+   * page). */
+  getProgress: () => { page: number; totalPages: number; value: number };
+  /** Reports whether the slide at the zero-based index is currently
+   * visible in the viewport (per IntersectionObserver, ≥ 60%
+   * intersection). Useful for lazy-loading slide content. */
+  isInView: (slideIndex: number) => boolean;
+};
+
+export type CarouselProgress = {
+  page: number;
+  totalPages: number;
+  value: number;
+};
+
+/**
+ * Convenience wrapper that auto-renders one `Carousel.Indicator` per
+ * registered slide. Reuses the same discriminated label shape as
+ * `Carousel.IndicatorGroup`. `children` is reserved (the auto-mapped
+ * indicators take that slot) — drop down to `Carousel.IndicatorGroup`
+ * + `Carousel.Indicator` if you need custom indicator content.
+ */
+export type CarouselIndicatorsProps = Omit<
+  ComponentProps<"div">,
+  "label" | "aria-labelledby" | "children"
+> &
+  (
+    | { label: string; ariaLabelledBy?: never }
+    | { label?: never; ariaLabelledBy: string }
+  );
+
+/**
+ * Render-prop or static children supported by
+ * `Carousel.PlayPauseTrigger`. The function form receives the live
+ * `playing` flag so consumers can swap icons / labels per state.
+ */
+export type CarouselPlayPauseTriggerChildren =
+  | ReactNode
+  | ((state: { playing: boolean }) => ReactNode);
+
+export type CarouselPlayPauseTriggerProps = Omit<
+  ComponentProps<"button">,
+  "children"
+> & {
+  children?: CarouselPlayPauseTriggerChildren;
+  /** Render the child element instead of the default `<button>`.
+   * The child must accept a `ref`. The render-prop form of `children`
+   * is not supported under `asChild`; pass a single element instead. */
+  asChild?: boolean;
+};