@primitiv-ui/react 0.1.28 → 0.1.29

package/src/Carousel/Carousel.tsx

@@ -10,6 +10,7 @@ import { Slot } from "../Slot/index.ts";
 import { CarouselProvider } from "./CarouselContext";
 import {
   useCarouselContext,
+  useCarouselLoop,
   useCarouselRoot,
   useCarouselSlide,
   useCarouselViewport,
@@ -25,6 +26,7 @@ import type {
   CarouselIndicatorProps,
   CarouselIndicatorsProps,
   CarouselPlayPauseTriggerProps,
+  CarouselProgressTextProps,
 } from "./types";
 
 /**
@@ -42,6 +44,13 @@ import type {
  * The discriminated union on the props type rejects both-or-neither at
  * compile time.
  *
+ * **Orientation.** Pass `orientation="vertical"` to page along the block
+ * axis instead of the inline axis: the viewport scroll-snaps vertically,
+ * the viewport `ArrowDown` / `ArrowUp` keys advance / retreat (the
+ * horizontal arrows go inert), and the resolved value is published as
+ * `data-orientation` on the rendered `<section>` so consumer CSS can
+ * switch layout off a single hook. Defaults to `"horizontal"`.
+ *
  * Supports two **page-state modes**, statically discriminated at the type
  * level so only one of the two shapes is accepted by TypeScript:
  *
@@ -51,6 +60,12 @@ import type {
  *   parent owns the active page; the component defers every state
  *   change back through the callback.
  *
+ * The `ref` is an imperative handle ({@link CarouselImperativeApi}), not
+ * the DOM node — the `<section>`'s native attributes are still spread
+ * through from the remaining props.
+ *
+ * @extends HTMLElement
+ *
  * @example Labelled inline, uncontrolled
  * ```tsx
  * <Carousel.Root ariaLabel="Featured products" defaultPage={0}>…</Carousel.Root>
@@ -89,12 +104,20 @@ export const CarouselRoot: ForwardRefExoticComponent<
     playing,
     onPlayingChange,
     autoplay,
+    onAutoplayStatusChange,
     slidesPerPage,
     slidesPerMove,
     translations,
     ids,
     transition,
     snapAlign,
+    orientation,
+    loop,
+    allowMouseDrag,
+    onDragStatusChange,
+    onOverscrollStatusChange,
+    inViewThreshold,
+    snapType,
     children,
     ...rest
   },
@@ -109,12 +132,20 @@ export const CarouselRoot: ForwardRefExoticComponent<
       playing,
       onPlayingChange,
       autoplay,
+      onAutoplayStatusChange,
       slidesPerPage,
       slidesPerMove,
       translations,
       ids,
       transition,
       snapAlign,
+      orientation,
+      loop,
+      allowMouseDrag,
+      onDragStatusChange,
+      onOverscrollStatusChange,
+      inViewThreshold,
+      snapType,
     },
     imperativeRef,
   );
@@ -123,6 +154,9 @@ export const CarouselRoot: ForwardRefExoticComponent<
     <CarouselProvider value={contextValue}>
       <section
         aria-roledescription="carousel"
+        data-orientation={contextValue.orientation}
+        data-transition={contextValue.transition}
+        data-loop={contextValue.loop}
         className={className}
         {...(ariaLabel !== undefined && { "aria-label": ariaLabel })}
         {...(ariaLabelledBy !== undefined && {
@@ -160,7 +194,14 @@ CarouselRoot.displayName = "CarouselRoot";
  *
  * **Styling hooks.** `data-carousel-viewport` is set on the rendered
  * element. The component ships no styles — apply your own scroll-snap
- * recipe via this attribute.
+ * recipe via this attribute. `data-snap-type="mandatory" | "proximity"`
+ * mirrors the resolved root {@link CarouselRootProps.snapType | `snapType`}
+ * — scope `scroll-snap-type`'s strictness to it. `data-mouse-drag` is
+ * present whenever `allowMouseDrag` is `true` (a persistent hook — the
+ * natural place for a `cursor: grab` affordance, since showing that cursor
+ * when dragging isn't actually enabled would be misleading); `data-dragging`
+ * is additionally present only for the duration of an active drag (see
+ * below) — pair it with `cursor: grabbing`.
  *
  * **Keyboard navigation.** The Viewport is in the tab order
  * (`tabIndex={0}`) so keyboard users can reach the rotation control
@@ -177,6 +218,44 @@ CarouselRoot.displayName = "CarouselRoot";
  * target — focus inside a slide (e.g. on a link or form control) keeps
  * its native arrow-key semantics.
  *
+ * **Mouse click-and-drag** — opt-in via {@link CarouselRootProps.allowMouseDrag |
+ * `allowMouseDrag`} on `Carousel.Root` (default `false`; an
+ * unconditionally-on drag could conflict with a consumer's own
+ * drag-sensitive slide content). When enabled: click and hold, then drag,
+ * and the viewport scrolls like a swipe: `scrollLeft`/`scrollTop` track
+ * the pointer, amplified by a sensitivity multiplier (no momentum — the
+ * multiplier only scales the tracked delta, motion still stops dead on
+ * release), once the drag clears a small movement threshold — below it,
+ * nothing happens, so a plain click on a link/button inside a slide
+ * still reaches it. Release lets `scroll-snap-type` settle to the
+ * nearest slide (the same `scrollsnapchange` sync a touch swipe already
+ * drives). A `data-dragging` attribute is set for the duration of an
+ * active drag. Only `pointerType === "mouse"` is handled — touch/pen
+ * already scroll natively regardless of this prop.
+ *
+ * **Mouse-wheel scroll.** A physical wheel's vertical notches already
+ * scroll a `orientation="vertical"` carousel natively. On the default
+ * horizontal orientation, a plain vertical wheel notch (`deltaY`)
+ * translates into horizontal scroll — browsers only do this
+ * automatically when `Shift` is held. Stands down whenever `deltaX` is
+ * non-negligible, so a trackpad/Magic Mouse horizontal swipe (which
+ * already scrolls a horizontal viewport natively via `deltaX`) is never
+ * fought.
+ *
+ * **Overscroll.** Pushing against a boundary with nowhere further to go —
+ * via the keyboard, the wheel, or a mouse drag — fires the root's
+ * {@link CarouselRootProps.onOverscrollStatusChange | `onOverscrollStatusChange`}.
+ * A mouse drag past a boundary additionally sets a persistent
+ * `data-overscroll="start" | "end"` attribute on the Viewport for the
+ * duration (removed once the drag stops pushing past it, whether by
+ * reversing back within bounds or releasing) — the natural hook for a
+ * rubber-band resistance visual. Keyboard/wheel overscroll is a single
+ * instantaneous tap with no equivalent sustained DOM state. Native
+ * touch/swipe overscroll (OS-level rubber-banding) isn't covered — that's
+ * browser-owned scroll physics with no JS hook to observe it from.
+ *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Carousel.Root ariaLabel="Featured products">
@@ -191,21 +270,79 @@ export function CarouselViewport({
   children,
   ...rest
 }: CarouselViewportProps): ReactElement {
-  const { isAutoRotating, ids } = useCarouselContext();
-  const { viewportRef, onKeyDown } = useCarouselViewport();
+  const { isAutoRotating, ids, allowMouseDrag, snapType, slidesPerPage } =
+    useCarouselContext();
+  const {
+    viewportRef,
+    onKeyDown,
+    onDragStart,
+    onPointerDown,
+    onPointerMove,
+    onPointerUp,
+    onPointerCancel,
+    onClickCapture,
+  } = useCarouselViewport();
+  // Infinite loop swaps the native scroll-snap viewport for a JS transform track
+  // (RFC 0018, clone-strip revision): the engine translates one contiguous track
+  // whose real slides are flanked by a full period of aria-hidden clones, so every
+  // seam is already-painted DOM and a settle-time re-base is invisible (no per-slide
+  // shifts, no native snap to fight — the two things that flashed on iOS). Every
+  // other mode renders the slides straight into the scroll viewport as before.
+  const { trackRef, headCloneRef, tailCloneRef, isInfinite, dragHandlers } =
+    useCarouselLoop();
+  // Infinite is transform-driven, so its own pointer engine (drag → fling) owns
+  // the pointer events; the scroll-snap modes keep useCarouselViewport's
+  // mouse-drag handlers.
+  const pointerHandlers = dragHandlers ?? {
+    onPointerDown,
+    onPointerMove,
+    onPointerUp,
+    onPointerCancel,
+  };
 
   return (
     <div
       ref={viewportRef}
       data-carousel-viewport=""
+      data-snap-type={snapType}
       tabIndex={0}
       className={className}
       aria-live={isAutoRotating ? "off" : "polite"}
       onKeyDown={onKeyDown}
+      onDragStart={onDragStart}
+      {...pointerHandlers}
+      onClickCapture={onClickCapture}
+      {...(allowMouseDrag && { "data-mouse-drag": "" })}
       {...(ids.viewport !== undefined && { id: ids.viewport })}
       {...rest}
     >
-      {children}
+      {isInfinite ? (
+        <div
+          className="primitiv-carousel__track"
+          data-carousel-track=""
+          data-slides-per-page={slidesPerPage}
+          ref={trackRef}
+        >
+          {/* Clone buffers (a full period each side) — the engine fills these
+              display:contents holders with aria-hidden copies so the strip is
+              periodic and every seam is contiguous painted DOM. */}
+          <div
+            data-carousel-clones="head"
+            aria-hidden="true"
+            style={{ display: "contents" }}
+            ref={headCloneRef}
+          />
+          {children}
+          <div
+            data-carousel-clones="tail"
+            aria-hidden="true"
+            style={{ display: "contents" }}
+            ref={tailCloneRef}
+          />
+        </div>
+      ) : (
+        children
+      )}
     </div>
   );
 }
@@ -238,10 +375,20 @@ CarouselViewport.displayName = "CarouselViewport";
  *   recipe targets `[data-carousel-slide]`).
  * - `data-index="N"` — the slide's zero-based position in registration order.
  * - `data-total="N"` — the live total slide count.
+ * - `data-snap-align="start" | "center" | "end"` — present only on a page's
+ *   leading slide (every slide when `slidesPerPage` is 1), valued from this
+ *   slide's own {@link CarouselSlideProps.snapAlign | `snapAlign`} prop if
+ *   set, else the root's resolved `snapAlign`. The registry stylesheet
+ *   scopes `scroll-snap-align` to this hook, both so an interior slide of a
+ *   multi-slide page is never a valid scroll-snap resting position, and so
+ *   the native resting position agrees with `snapAlign` rather than always
+ *   being `"start"`.
  *
  * Must be rendered as a descendant of `Carousel.Root`; rendering it
  * elsewhere throws a descriptive error.
  *
+ * @extends HTMLDivElement
+ *
  * @example Auto-labelled
  * ```tsx
  * <Carousel.Viewport>
@@ -254,15 +401,23 @@ CarouselViewport.displayName = "CarouselViewport";
  * ```tsx
  * <Carousel.Slide ariaLabel="Hand-picked for you">…</Carousel.Slide>
  * ```
+ *
+ * @example Per-slide snap alignment (overrides the root default)
+ * ```tsx
+ * <Carousel.Slide snapAlign="end">…</Carousel.Slide>
+ * ```
  */
 export function CarouselSlide({
   className = "",
   ariaLabel,
+  snapAlign: snapAlignOverride,
   children,
   ...rest
 }: CarouselSlideProps): ReactElement {
-  const { slideRef, index, total, state } = useCarouselSlide();
+  const { slideRef, index, total, state, snapAlign } =
+    useCarouselSlide(snapAlignOverride);
   const { translations } = useCarouselContext();
+
   const autoLabel =
     index >= 0 && total > 0
       ? translations.slideLabel({ index: index + 1, total })
@@ -280,6 +435,7 @@ export function CarouselSlide({
       data-state={state}
       className={className}
       {...(label !== undefined && { "aria-label": label })}
+      {...(snapAlign !== undefined && { "data-snap-align": snapAlign })}
       {...rest}
     >
       {children}
@@ -306,6 +462,8 @@ CarouselSlide.displayName = "CarouselSlide";
  * Must be rendered as a descendant of `Carousel.Root`; rendering it
  * elsewhere throws a descriptive error.
  *
+ * @extends HTMLButtonElement
+ *
  * @example
  * ```tsx
  * <Carousel.NextTrigger>Next</Carousel.NextTrigger>
@@ -373,6 +531,8 @@ CarouselNextTrigger.displayName = "CarouselNextTrigger";
  * Must be rendered as a descendant of `Carousel.Root`; rendering it
  * elsewhere throws a descriptive error.
  *
+ * @extends HTMLButtonElement
+ *
  * @example
  * ```tsx
  * <Carousel.PreviousTrigger>Previous</Carousel.PreviousTrigger>
@@ -439,6 +599,8 @@ CarouselPreviousTrigger.displayName = "CarouselPreviousTrigger";
  * Must be rendered as a descendant of `Carousel.Root`; rendering it
  * elsewhere throws a descriptive error.
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Carousel.IndicatorGroup label="Choose slide">
@@ -488,6 +650,15 @@ CarouselIndicatorGroup.displayName = "CarouselIndicatorGroup";
  * `aria-disabled="false"`. Both states also flip `data-state` between
  * `"active"` and `"inactive"` so consumer CSS can paint the active dot.
  *
+ * **`readOnly`.** When `true`, the indicator becomes a presentational-only
+ * progress dot instead of a navigation control: it renders a `<span>` (no
+ * button semantics), carries `aria-hidden="true"` (it's decorative, not
+ * announced), and clicking it no longer calls `goTo` — for a carousel whose
+ * only navigation is e.g. `allowMouseDrag`, where clickable dots would be a
+ * redundant/misleading control. It still tracks `data-state`, so CSS-driven
+ * progress display keeps working, and the consumer's own `onClick` (if
+ * passed) still fires — only the internal navigation is suppressed.
+ *
  * **Styling hooks.**
  * - `data-carousel-indicator` — CSS-targeting attribute.
  * - `data-state="active" | "inactive"` — tracks the current page.
@@ -495,15 +666,19 @@ CarouselIndicatorGroup.displayName = "CarouselIndicatorGroup";
  * Must be rendered as a descendant of `Carousel.Root`; rendering it
  * elsewhere throws a descriptive error.
  *
+ * @extends HTMLButtonElement
+ *
  * @example
  * ```tsx
  * <Carousel.Indicator index={0} />
+ * <Carousel.Indicator index={0} readOnly />
  * ```
  */
 export function CarouselIndicator({
   className = "",
   index,
   onClick,
+  readOnly = false,
   asChild = false,
   children,
   ...rest
@@ -514,18 +689,22 @@ export function CarouselIndicator({
   const handleClick = useCallback(
     (event: MouseEvent<HTMLButtonElement>) => {
       onClick?.(event);
-      goTo(index);
+      if (!readOnly) goTo(index);
     },
-    [goTo, index, onClick],
+    [goTo, index, onClick, readOnly],
   );
 
   const indicatorProps = {
     className,
-    "aria-label": translations.indicatorLabel({ index: index + 1 }),
-    "aria-disabled": isActive,
     "data-carousel-indicator": "",
     "data-state": isActive ? "active" : "inactive",
     onClick: handleClick,
+    ...(readOnly
+      ? { "aria-hidden": true }
+      : {
+          "aria-label": translations.indicatorLabel({ index: index + 1 }),
+          "aria-disabled": isActive,
+        }),
     ...rest,
   };
 
@@ -533,6 +712,10 @@ export function CarouselIndicator({
     return <Slot {...indicatorProps}>{children}</Slot>;
   }
 
+  if (readOnly) {
+    return <span {...indicatorProps}>{children}</span>;
+  }
+
   return (
     <button type="button" {...indicatorProps}>
       {children}
@@ -555,23 +738,30 @@ CarouselIndicator.displayName = "CarouselIndicator";
  * thumbnail previews on hover), drop down to
  * `Carousel.IndicatorGroup` + `Carousel.Indicator` instead.
  *
+ * `readOnly` forwards to every generated indicator — see
+ * `Carousel.Indicator`'s own `readOnly` doc.
+ *
  * Must be rendered as a descendant of `Carousel.Root`; rendering it
  * elsewhere throws a descriptive error.
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Carousel.Indicators label="Choose slide" />
+ * <Carousel.Indicators label="Progress" readOnly />
  * ```
  */
-export function CarouselIndicators(
-  props: CarouselIndicatorsProps,
-): ReactElement {
+export function CarouselIndicators({
+  readOnly,
+  ...props
+}: CarouselIndicatorsProps): ReactElement {
   const { totalPages } = useCarouselContext();
 
   return (
     <CarouselIndicatorGroup {...props}>
       {Array.from({ length: totalPages }, (_, index) => (
-        <CarouselIndicator key={index} index={index} />
+        <CarouselIndicator key={index} index={index} readOnly={readOnly} />
       ))}
     </CarouselIndicatorGroup>
   );
@@ -598,9 +788,23 @@ CarouselIndicators.displayName = "CarouselIndicators";
  * Static children also work — useful when you want a single icon and
  * style it via `[data-state]` selectors.
  *
+ * Requires autoplay to be enabled on `Carousel.Root` — a control that
+ * toggled a non-existent slideshow would be misleading, so rendering
+ * this trigger without an `autoplay` prop on the Root throws a
+ * descriptive error. Toggling `playing` to `true` starts the timer that
+ * advances the page on each tick (see {@link CarouselAutoplay}).
+ *
  * Must be rendered as a descendant of `Carousel.Root`; rendering it
- * elsewhere throws a descriptive error. The autoplay timer that
- * advances the page when `playing` flips to `true` lands in cycle 12.
+ * elsewhere throws a descriptive error.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example State-aware render prop
+ * ```tsx
+ * <Carousel.PlayPauseTrigger>
+ *   {({ playing }) => (playing ? "Pause" : "Play")}
+ * </Carousel.PlayPauseTrigger>
+ * ```
  */
 export function CarouselPlayPauseTrigger({
   className = "",
@@ -654,6 +858,48 @@ export function CarouselPlayPauseTrigger({
 /** @internal */
 CarouselPlayPauseTrigger.displayName = "CarouselPlayPauseTrigger";
 
+/**
+ * A `<span>` rendering the live active-page progress as text — `"1 of
+ * 3"` by default, via `translations.progressText`. Closes the gap
+ * between the imperative `getProgress()` data and an actual DOM node a
+ * consumer can drop in without wiring the announcement themselves.
+ *
+ * ```tsx
+ * <Carousel.ProgressText />
+ * ```
+ *
+ * Pass `children` to render custom content instead of the default
+ * translated text (e.g. an icon alongside the count) — the computed
+ * text is only used as a fallback.
+ *
+ * Must be rendered as a descendant of `Carousel.Root`; rendering it
+ * elsewhere throws a descriptive error (via the shared Carousel
+ * context guard).
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <Carousel.ProgressText />
+ * ```
+ */
+export function CarouselProgressText({
+  children,
+  ...rest
+}: CarouselProgressTextProps): ReactElement {
+  const { currentPage, totalPages, translations } = useCarouselContext();
+
+  return (
+    <span {...rest}>
+      {children ??
+        translations.progressText({ page: currentPage, totalPages })}
+    </span>
+  );
+}
+
+/** @internal */
+CarouselProgressText.displayName = "CarouselProgressText";
+
 /** 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;
@@ -665,6 +911,7 @@ type CarouselCompound = typeof CarouselRoot & {
   Indicator: typeof CarouselIndicator;
   Indicators: typeof CarouselIndicators;
   PlayPauseTrigger: typeof CarouselPlayPauseTrigger;
+  ProgressText: typeof CarouselProgressText;
 };
 
 /**
@@ -717,6 +964,7 @@ const CarouselCompound: CarouselCompound = Object.assign(CarouselRoot, {
   Indicator: CarouselIndicator,
   Indicators: CarouselIndicators,
   PlayPauseTrigger: CarouselPlayPauseTrigger,
+  ProgressText: CarouselProgressText,
 });
 
 CarouselCompound.displayName = "Carousel";