aplance-ui 1.2.2 → 1.3.0

package/registry/components/primitives/slider/slider.tsx

@@ -10,6 +10,7 @@ import {
   useRef,
   useState,
   type CSSProperties,
+  type MouseEvent as ReactMouseEvent,
   type PointerEvent as ReactPointerEvent,
   type ReactNode,
   type TransitionEvent as ReactTransitionEvent,
@@ -21,11 +22,16 @@ import { useResizeObserver } from "../../../hooks/useResizeObserver";
 import { SliderContext, useSlider, type SliderApi } from "./slider-context";
 import type {
   SliderAutoplayOptions,
+  SliderArrowProps,
+  SliderDotsProps,
+  SliderIndicatorProps,
   SliderNavigationOptions,
+  SliderPaginationItems,
   SliderPaginationOptions,
   SliderPaginationType,
   SliderProps,
   SliderSlideState,
+  SliderVariantOptions,
 } from "./types";
 import {
   clamp,
@@ -41,13 +47,18 @@ export {
   sliderAlignments,
   sliderEffects,
   sliderPaginationTypes,
+  sliderVariants,
 } from "./types";
 export type {
   SliderAlign,
   SliderAutoplayOptions,
+  SliderArrowProps,
+  SliderDotsProps,
   SliderEffect,
   SliderHandle,
+  SliderIndicatorProps,
   SliderNavigationOptions,
+  SliderPaginationItems,
   SliderPaginationOptions,
   SliderPaginationType,
   SliderProps,
@@ -55,17 +66,65 @@ export type {
   SliderResponsiveOptions,
   SliderSlideState,
   SliderSlidesPerView,
+  SliderVariant,
+  SliderVariantOptions,
 } from "./types";
 
+// Swallow the browser click after a swipe so linked slides stay draggable.
+const DRAG_CLICK_TOLERANCE = 6;
+const EMPTY_VARIANT_OPTIONS: SliderVariantOptions = {};
+
+type SliderCssProperties = CSSProperties &
+  Record<`--slider-${string}`, string | number | undefined>;
+
+const resolveVariantOptions = (
+  variant: "default" | "cards" | "coverflow",
+  options: SliderVariantOptions,
+): Required<SliderVariantOptions> => {
+  const offset = typeof options.offset === "number" && Number.isFinite(options.offset)
+    ? Math.max(0, options.offset)
+    : variant === "cards"
+      ? 6
+      : 0;
+  const scaleStep = typeof options.scaleStep === "number" && Number.isFinite(options.scaleStep)
+    ? clamp(options.scaleStep, 0, 1)
+    : variant === "cards"
+      ? 0.07
+      : 0.08;
+  const opacityStep = typeof options.opacityStep === "number" && Number.isFinite(options.opacityStep)
+    ? clamp(options.opacityStep, 0, 1)
+    : variant === "cards"
+      ? 0.16
+      : 0.2;
+  const rotate = typeof options.rotate === "number" && Number.isFinite(options.rotate)
+    ? clamp(options.rotate, 0, 90)
+    : 38;
+  const depth = typeof options.depth === "number" && Number.isFinite(options.depth)
+    ? Math.max(0, options.depth)
+    : 96;
+
+  return {
+    offset,
+    scaleStep,
+    opacityStep,
+    rotate,
+    depth,
+  };
+};
+
 // ─── Slider ───────────────────────────────────────────────────────────────────
 
 export const Slider = ({
   children,
   className,
+  viewportClassName,
+  trackClassName,
   style,
   ref,
   ariaLabel = "Slider",
   effect: effectProp = "slide",
+  variant: variantProp = "default",
+  variantOptions: variantOptionsProp = EMPTY_VARIANT_OPTIONS,
   align: alignProp = "start",
   centered: centeredProp = false,
   slidesPerView: slidesPerViewProp = 1,
@@ -82,7 +141,8 @@ export const Slider = ({
   easing = "cubic-bezier(0.4, 0, 0.2, 1)",
   draggable = true,
   swipeThreshold = 30,
-  dragIgnoreSelector = "a, button, input, textarea, select, summary, [role='button'], [data-slider-no-drag]",
+  // Linked slides stay draggable. Click suppression distinguishes swipes from taps.
+  dragIgnoreSelector = "button, input, textarea, select, summary, [role='button'], [data-slider-no-drag]",
   keyboard = false,
   mousewheel = false,
   autoHeight = false,
@@ -166,6 +226,8 @@ export const Slider = ({
           centered: centeredProp,
           align: alignProp,
           effect: effectProp,
+          variant: variantProp,
+          variantOptions: variantOptionsProp,
         },
         responsive,
       ),
@@ -177,6 +239,8 @@ export const Slider = ({
       slidesPerGroupProp,
       slidesPerViewProp,
       spaceBetweenProp,
+      variantProp,
+      variantOptionsProp,
       viewportWidth,
     ],
   );
@@ -200,6 +264,8 @@ export const Slider = ({
   const align = responsiveOptions.centered ? "center" : responsiveOptions.align;
   const effect = responsiveOptions.effect;
   const effectMode = effect;
+  const variant = effectMode === "slide" ? responsiveOptions.variant : "default";
+  const variantOptions = resolveVariantOptions(variant, responsiveOptions.variantOptions);
   const canLoop = loop && count > 1 && effectMode === "slide";
   const baseMaxIndex =
     effectMode === "slide" ? getSnapMax(count, slidesPerView) : Math.max(0, count - 1);
@@ -255,6 +321,10 @@ export const Slider = ({
     }
   }, [count, isControlled, loop, maxIndex]);
 
+  useLayoutEffect(() => {
+    if (autoHeight) measure();
+  }, [autoHeight, logicalIndex, measure]);
+
   // Clone N slides on each side so dragging/grouping past the edge always
   // has real DOM under the cursor. `+1` is a buffer for partial-view layouts;
   // `slidesPerView=auto` is unknowable up-front so we clone the full set.
@@ -294,6 +364,13 @@ export const Slider = ({
   const [isFocusWithin, setIsFocusWithin] = useState(false);
   const [autoplayStopped, setAutoplayStopped] = useState(false);
   const wheelLockRef = useRef(false);
+  const suppressClickRef = useRef(false);
+  // True once a pointer interaction has crossed the drag threshold and become a
+  // real drag (so we capture the pointer + move the track). A plain tap never
+  // flips this, so it never captures the pointer - which is what lets a card's
+  // <a> receive the click (a captured pointer makes the browser dispatch the
+  // `click` to the captured viewport, not the link, so navigation silently dies).
+  const dragActiveRef = useRef(false);
   const layoutSignatureRef = useRef("");
   const dragStartRef = useRef<{
     x: number;
@@ -310,6 +387,7 @@ export const Slider = ({
     slidesPerGroup,
     slidesPerView,
     spaceBetween,
+    variant,
     viewportWidth,
   ].join("|");
 
@@ -387,6 +465,9 @@ export const Slider = ({
       ? clamp(baseOffset - alignmentOffset, 0, maxScroll)
       : baseOffset - alignmentOffset;
   const translate = -targetOffset + dragOffset;
+  const visualPosition = visualIndex - dragOffset / Math.max(1, averageStride);
+  const visibleStart = targetOffset - dragOffset;
+  const visibleEnd = visibleStart + viewportWidth;
   const progress = snapCount <= 1 ? 1 : clamp(logicalIndex / (snapCount - 1), 0, 1);
   const canNavigateLoop = loop && count > 1;
   const isFirst = !canNavigateLoop && logicalIndex <= 0;
@@ -636,6 +717,8 @@ export const Slider = ({
   // ─── Pointer / keyboard / wheel ─────────────────────────────────────────────
 
   const handlePointerDown = (event: ReactPointerEvent<HTMLDivElement>) => {
+    suppressClickRef.current = false;
+    dragActiveRef.current = false;
     if (
       !draggable ||
       count <= 1 ||
@@ -647,6 +730,11 @@ export const Slider = ({
     if (event.pointerType === "mouse" && event.button !== 0) return;
 
     markInteraction();
+    // Record the START point only. We do NOT capture the pointer or enter the
+    // dragging state yet: a plain click must stay a plain click so the card's
+    // <a> receives it (a captured pointer makes the browser deliver the `click`
+    // to the captured viewport, not the link). The drag is promoted in
+    // `handlePointerMove` once the pointer travels past the threshold.
     dragStartRef.current = {
       x: event.clientX,
       y: event.clientY,
@@ -654,9 +742,6 @@ export const Slider = ({
       logicalIndex,
     };
     verticalLockRef.current = false;
-    setIsDragging(true);
-    setIsAnimating(false);
-    event.currentTarget.setPointerCapture?.(event.pointerId);
   };
 
   const handlePointerMove = (event: ReactPointerEvent<HTMLDivElement>) => {
@@ -666,17 +751,31 @@ export const Slider = ({
     const dx = event.clientX - start.x;
     const dy = event.clientY - start.y;
 
-    if (event.pointerType !== "mouse" && !verticalLockRef.current) {
+    // Before the drag is committed, a clearly-vertical touch is a page scroll -
+    // abandon the gesture so the page scrolls normally.
+    if (
+      event.pointerType !== "mouse" &&
+      !verticalLockRef.current &&
+      !dragActiveRef.current
+    ) {
       if (Math.abs(dy) > Math.abs(dx) && Math.abs(dy) > 8) {
         verticalLockRef.current = true;
         dragStartRef.current = null;
-        setIsDragging(false);
-        setDragOffset(0);
-        event.currentTarget.releasePointerCapture?.(event.pointerId);
         return;
       }
     }
 
+    // Promote to a real drag only once past the threshold. Until then this is
+    // still a potential tap, so we neither capture the pointer nor move the
+    // track - which is what keeps link clicks working.
+    if (!dragActiveRef.current) {
+      if (Math.abs(dx) <= DRAG_CLICK_TOLERANCE) return;
+      dragActiveRef.current = true;
+      setIsDragging(true);
+      setIsAnimating(false);
+      event.currentTarget.setPointerCapture?.(event.pointerId);
+    }
+
     // Rubber-band at non-loop edges: dampen drag so users feel the bound
     // without breaking the snap-back on release.
     const shouldRubberBand =
@@ -690,9 +789,14 @@ export const Slider = ({
 
     const dx = clientX - start.x;
     dragStartRef.current = null;
+    dragActiveRef.current = false;
     setIsDragging(false);
     setDragOffset(0);
 
+    if (Math.abs(dx) > DRAG_CLICK_TOLERANCE) {
+      suppressClickRef.current = true;
+    }
+
     if (Math.abs(dx) < resolvedSwipeThreshold) return;
 
     const steps = Math.max(1, Math.round(Math.abs(dx) / Math.max(1, averageStride)));
@@ -700,16 +804,31 @@ export const Slider = ({
     else prev(steps);
   };
 
+  const releaseCapture = (event: ReactPointerEvent<HTMLDivElement>) => {
+    if (event.currentTarget.hasPointerCapture?.(event.pointerId)) {
+      event.currentTarget.releasePointerCapture?.(event.pointerId);
+    }
+  };
+
   const handlePointerUp = (event: ReactPointerEvent<HTMLDivElement>) => {
     finishDrag(event.clientX);
-    event.currentTarget.releasePointerCapture?.(event.pointerId);
+    releaseCapture(event);
   };
 
   const handlePointerCancel = (event: ReactPointerEvent<HTMLDivElement>) => {
     dragStartRef.current = null;
+    dragActiveRef.current = false;
     setIsDragging(false);
     setDragOffset(0);
-    event.currentTarget.releasePointerCapture?.(event.pointerId);
+    releaseCapture(event);
+  };
+
+  const handleClickCapture = (event: ReactMouseEvent<HTMLDivElement>) => {
+    if (suppressClickRef.current) {
+      event.preventDefault();
+      event.stopPropagation();
+      suppressClickRef.current = false;
+    }
   };
 
   const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
@@ -845,9 +964,15 @@ export const Slider = ({
         className={clsx(
           s.container,
           effectMode !== "slide" && s.container_effect,
+          isDragging && s.container_dragging,
+          (!isMotionReady || transitionOff) && s.container_no_transition,
           className,
         )}
-        style={style}
+        style={{
+          "--slider-transition-duration": `${transitionDuration}ms`,
+          "--slider-transition-easing": easing,
+          ...style,
+        } as SliderCssProperties}
         role="region"
         aria-roledescription="carousel"
         aria-label={ariaLabel}
@@ -876,7 +1001,11 @@ export const Slider = ({
       >
         <div
           ref={viewportRef}
-          className={s.viewport}
+          className={clsx(
+            s.viewport,
+            variant === "coverflow" && s.viewport_coverflow,
+            viewportClassName,
+          )}
           style={{
             ...viewportStyle,
             visibility: hasMeasured ? undefined : "hidden",
@@ -887,6 +1016,7 @@ export const Slider = ({
           onPointerMove={handlePointerMove}
           onPointerUp={handlePointerUp}
           onPointerCancel={handlePointerCancel}
+          onClickCapture={handleClickCapture}
           onDragStart={(event) => event.preventDefault()}
         >
           <div
@@ -895,6 +1025,9 @@ export const Slider = ({
               s.track,
               effectMode === "fade" && s.track_fade,
               effectMode === "scale" && s.track_scale,
+              effectMode === "flip" && s.track_flip,
+              variant === "coverflow" && s.track_coverflow,
+              trackClassName,
             )}
             style={trackStyle}
             onTransitionEnd={handleTrackTransitionEnd}
@@ -907,13 +1040,21 @@ export const Slider = ({
                 canLoop && (renderedIndex < cloneCount || renderedIndex >= cloneCount + count);
               const visibleCount =
                 slidesPerView === "auto" ? 1 : Math.ceil(slidesPerView);
+              const slideOffset = slideOffsets[renderedIndex];
+              const slideSize = slideSizes[renderedIndex];
               const isActive =
                 realIndex === logicalIndex &&
                 (effectMode === "slide" ? renderedIndex === visualIndex : !isClone);
               const isVisible = effectMode !== "slide"
                   ? realIndex === logicalIndex
-                  : renderedIndex >= visualIndex &&
-                    renderedIndex < visualIndex + visibleCount;
+                  : hasMeasured &&
+                      viewportWidth > 0 &&
+                      slideOffset !== undefined &&
+                      slideSize !== undefined
+                    ? slideOffset + slideSize > visibleStart &&
+                      slideOffset < visibleEnd
+                    : renderedIndex >= visualIndex &&
+                      renderedIndex < visualIndex + visibleCount;
               const state: SliderSlideState = {
                 index: realIndex,
                 renderedIndex,
@@ -921,6 +1062,24 @@ export const Slider = ({
                 isVisible,
                 isClone,
               };
+              const slideDistance = clamp(renderedIndex - visualPosition, -3, 3);
+              const slideAbsDistance = Math.abs(slideDistance);
+              const variantStyle = variant === "default"
+                ? undefined
+                : {
+                    "--slider-slide-offset": `${slideAbsDistance * variantOptions.offset}px`,
+                    "--slider-slide-scale": Math.max(
+                      variant === "cards" ? 0.86 : 0.82,
+                      1 - slideAbsDistance * variantOptions.scaleStep,
+                    ),
+                    "--slider-slide-depth": `${slideAbsDistance * variantOptions.depth * -1}px`,
+                    "--slider-slide-rotate": `${slideDistance * variantOptions.rotate * -1}deg`,
+                    opacity: Math.max(
+                      variant === "cards" ? 0.64 : 0.5,
+                      1 - slideAbsDistance * variantOptions.opacityStep,
+                    ),
+                    zIndex: Math.max(0, 10 - Math.round(slideAbsDistance)),
+                  } as SliderCssProperties;
 
               return (
                 <div
@@ -936,11 +1095,22 @@ export const Slider = ({
                   className={clsx(
                     s.slide,
                     effectMode !== "slide" && s.slide_overlay,
+                    variant === "cards" && s.slide_cards,
+                    variant === "coverflow" && s.slide_coverflow,
                     isActive && s.slide_active,
                     isVisible && s.slide_visible,
                   )}
-                  style={slideStyle}
-                  aria-hidden={isClone || (!isVisible && effectMode !== "slide") || undefined}
+                  style={variantStyle ? { ...slideStyle, ...variantStyle } : slideStyle}
+                  // Only CLONES are inert + hidden from AT (they're duplicate,
+                  // non-interactive copies). REAL slides stay interactive even
+                  // when scrolled out of view: they're clipped by the viewport's
+                  // `overflow`, so an off-screen card can't be clicked anyway,
+                  // and gating `inert` on the measurement-dependent `isVisible`
+                  // flag would intermittently make an on-screen card
+                  // non-clickable (the swipe/measure race the user hit - the
+                  // link shows on hover, but the click lands while inert).
+                  aria-hidden={isClone || undefined}
+                  inert={isClone ? true : undefined}
                   data-active={isActive ? "true" : undefined}
                   data-visible={isVisible ? "true" : undefined}
                   data-clone={isClone ? "true" : undefined}
@@ -1022,7 +1192,7 @@ const SliderNavButton = ({
 type SliderPaginationViewProps = {
   type: SliderPaginationType;
   clickable: boolean;
-  items: "snaps" | "slides";
+  items: SliderPaginationItems;
   className?: string;
 };
 
@@ -1092,11 +1262,7 @@ export const SliderPrev = ({
   className,
   children,
   ariaLabel = "Previous slide",
-}: {
-  className?: string;
-  children?: ReactNode;
-  ariaLabel?: string;
-}) => {
+}: SliderArrowProps) => {
   const { prev, isFirst } = useSlider();
   return (
     <button
@@ -1116,11 +1282,7 @@ export const SliderNext = ({
   className,
   children,
   ariaLabel = "Next slide",
-}: {
-  className?: string;
-  children?: ReactNode;
-  ariaLabel?: string;
-}) => {
+}: SliderArrowProps) => {
   const { next, isLast } = useSlider();
   return (
     <button
@@ -1140,11 +1302,7 @@ export const SliderDots = ({
   className,
   clickable = true,
   items = "snaps",
-}: {
-  className?: string;
-  clickable?: boolean;
-  items?: "snaps" | "slides";
-}) => (
+}: SliderDotsProps) => (
   <SliderPaginationView
     type="dots"
     clickable={clickable}
@@ -1153,7 +1311,7 @@ export const SliderDots = ({
   />
 );
 
-export const SliderFraction = ({ className }: { className?: string }) => (
+export const SliderFraction = ({ className }: SliderIndicatorProps) => (
   <SliderPaginationView
     type="fraction"
     clickable={false}
@@ -1162,7 +1320,7 @@ export const SliderFraction = ({ className }: { className?: string }) => (
   />
 );
 
-export const SliderProgress = ({ className }: { className?: string }) => (
+export const SliderProgress = ({ className }: SliderIndicatorProps) => (
   <SliderPaginationView
     type="progress"
     clickable={false}

package/registry/components/primitives/slider/types.ts

@@ -6,17 +6,35 @@ import type {
 } from "react";
 import type { SliderApi } from "./slider-context";
 
-export const sliderEffects = ["slide", "fade", "scale"] as const;
+export const sliderEffects = ["slide", "fade", "scale", "flip"] as const;
 export type SliderEffect = (typeof sliderEffects)[number];
 
+export const sliderVariants = ["default", "cards", "coverflow"] as const;
+export type SliderVariant = (typeof sliderVariants)[number];
+
 export const sliderAlignments = ["start", "center", "end"] as const;
 export type SliderAlign = (typeof sliderAlignments)[number];
 
 export const sliderPaginationTypes = ["dots", "fraction", "progress"] as const;
 export type SliderPaginationType = (typeof sliderPaginationTypes)[number];
 
+export type SliderPaginationItems = "snaps" | "slides";
+
 export type SliderSlidesPerView = number | "auto";
 
+export type SliderVariantOptions = {
+  /** Vertical offset per slide distance in px. */
+  offset?: number;
+  /** Scale reduction per slide distance. */
+  scaleStep?: number;
+  /** Opacity reduction per slide distance. */
+  opacityStep?: number;
+  /** Coverflow rotation per slide distance in degrees. */
+  rotate?: number;
+  /** Coverflow depth reduction per slide distance in px. */
+  depth?: number;
+};
+
 export type SliderResponsiveOptions = {
   slidesPerView?: SliderSlidesPerView;
   slidesPerGroup?: number;
@@ -24,6 +42,8 @@ export type SliderResponsiveOptions = {
   centered?: boolean;
   align?: SliderAlign;
   effect?: SliderEffect;
+  variant?: SliderVariant;
+  variantOptions?: SliderVariantOptions;
 };
 
 /** Responsive overrides keyed by minimum viewport width in px. */
@@ -55,7 +75,23 @@ export type SliderPaginationOptions = {
   /** When true, dots/fraction items are clickable. */
   clickable?: boolean;
   /** Paginate by snap pages or every real slide. */
-  items?: "snaps" | "slides";
+  items?: SliderPaginationItems;
+  className?: string;
+};
+
+export type SliderArrowProps = {
+  className?: string;
+  children?: ReactNode;
+  ariaLabel?: string;
+};
+
+export type SliderDotsProps = {
+  className?: string;
+  clickable?: boolean;
+  items?: SliderPaginationItems;
+};
+
+export type SliderIndicatorProps = {
   className?: string;
 };
 
@@ -81,12 +117,29 @@ export type SliderHandle = {
 export type SliderProps = {
   children: ReactNode;
   className?: string;
+  /** Class merged onto the inner clipping viewport. Use it to add vertical
+   *  breathing room (e.g. `padding-block`) when slides carry borders /
+   *  shadows / hover states that would otherwise be shaved by the viewport's
+   *  `overflow: hidden`. Keep it to vertical padding only - horizontal padding
+   *  would skew the slide-width measurement. */
+  viewportClassName?: string;
+  /** Class merged onto the moving track (the flex strip that holds the slides).
+   *  Use it when the slider must fill a definite-height parent (e.g. a
+   *  full-screen lightbox): set the track to `height: 100%` so it - and the
+   *  stretch-aligned slides - inherit the viewport height instead of collapsing
+   *  to slide content. */
+  trackClassName?: string;
   style?: CSSProperties;
   ref?: Ref<SliderHandle>;
   ariaLabel?: string;
 
-  /** Slide transition effect. `fade` and `scale` are single-view effects. */
+  /** Slide transition effect. `fade`, `scale`, and `flip` are single-view effects. */
   effect?: SliderEffect;
+  /** Visual treatment for slide layouts. `cards` and `coverflow` enhance the
+   *  standard slide effect without changing navigation behavior. */
+  variant?: SliderVariant;
+  /** Optional tuning for `cards` and `coverflow` presentation variants. */
+  variantOptions?: SliderVariantOptions;
   /** Alignment of the active slide inside the viewport. */
   align?: SliderAlign;
   /** Center active slides. Alias for align="center". */

package/registry/components/primitives/slider/utils.ts

@@ -73,6 +73,15 @@ export const resolveResponsive = (
     if (options.effect !== undefined) {
       active.effect = options.effect;
     }
+    if (options.variant !== undefined) {
+      active.variant = options.variant;
+    }
+    if (options.variantOptions !== undefined) {
+      active.variantOptions = {
+        ...active.variantOptions,
+        ...options.variantOptions,
+      };
+    }
   }
 
   return active;