@sableui/react 0.6.1 → 0.7.0

package/dist/components/carousel/carousel.js

@@ -0,0 +1,428 @@
+"use client";
+
+// src/components/carousel/carousel.tsx
+import {
+  Children,
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  useSyncExternalStore
+} from "react";
+import { Icon } from "../../icon/Icon.js";
+import { cn } from "../../lib/cn.js";
+import { PlayPauseGlyph } from "../../lib/glyphs.js";
+import { useResizeObserver } from "../../lib/use-resize-observer.js";
+import { useMotion } from "../../motion/MotionProvider.js";
+import { Button } from "../button/button.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var CAROUSEL_BREAKPOINTS = [
+  ["sm", 640],
+  ["md", 768],
+  ["lg", 1024],
+  ["xl", 1280]
+];
+function useSlidesToShow(value) {
+  const set = typeof value === "number" ? null : value;
+  const base = typeof value === "number" ? value : value.base ?? 1;
+  const key = set ? CAROUSEL_BREAKPOINTS.map(([bp]) => set[bp] ?? "").join() : "";
+  const subscribe = useCallback(
+    (onChange) => {
+      if (!key || typeof window === "undefined" || !window.matchMedia)
+        return () => {
+        };
+      const mqls = CAROUSEL_BREAKPOINTS.map(
+        ([, px]) => window.matchMedia(`(min-width: ${px}px)`)
+      );
+      for (const mql of mqls) mql.addEventListener?.("change", onChange);
+      return () => {
+        for (const mql of mqls) mql.removeEventListener?.("change", onChange);
+      };
+    },
+    [key]
+  );
+  const getSnapshot = () => {
+    if (!set || typeof window === "undefined" || !window.matchMedia) return base;
+    let n = base;
+    for (const [bp, px] of CAROUSEL_BREAKPOINTS) {
+      const v = set[bp];
+      if (v != null && window.matchMedia(`(min-width: ${px}px)`).matches) n = v;
+    }
+    return n;
+  };
+  return useSyncExternalStore(subscribe, getSnapshot, () => base);
+}
+function CarouselArrowButton({
+  side,
+  onClick,
+  disabled,
+  className
+}) {
+  return /* @__PURE__ */ jsx(
+    Button,
+    {
+      variant: "floating",
+      size: "icon-sm",
+      onClick,
+      disabled,
+      "aria-label": side === "prev" ? "Previous slide" : "Next slide",
+      className: cn(
+        "absolute top-1/2 z-10 -translate-y-1/2 disabled:opacity-0",
+        side === "prev" ? "left-3" : "right-3",
+        className
+      ),
+      children: /* @__PURE__ */ jsx(Icon, { name: side === "prev" ? "chevron-left" : "chevron-right" })
+    }
+  );
+}
+function Carousel({
+  children,
+  slidesToShow = 1,
+  gap = "0px",
+  loop = false,
+  autoplay = 0,
+  arrows = true,
+  dots = true,
+  counter = false,
+  draggable = true,
+  index: controlledIndex,
+  defaultIndex = 0,
+  onIndexChange,
+  label,
+  className,
+  slideClassName,
+  arrowClassName
+}) {
+  const { enabled } = useMotion();
+  const slides = Children.toArray(children);
+  const count = slides.length;
+  const perView = Math.min(
+    Math.max(useSlidesToShow(slidesToShow), 1),
+    Math.max(count, 1)
+  );
+  const canLoop = loop && count > perView;
+  const clones = canLoop ? perView : 0;
+  const maxIndex = canLoop ? count - 1 : Math.max(0, count - perView);
+  const baseId = useId();
+  const viewportRef = useRef(null);
+  const slideRef = useRef(null);
+  const logicalRef = useRef(0);
+  const committedRef = useRef(
+    Math.min(Math.max(controlledIndex ?? defaultIndex, 0), maxIndex)
+  );
+  const [uncontrolled, setUncontrolled] = useState(
+    () => Math.min(Math.max(defaultIndex, 0), maxIndex)
+  );
+  const logical = Math.min(
+    Math.max(controlledIndex ?? uncontrolled, 0),
+    maxIndex
+  );
+  logicalRef.current = logical;
+  const [docHidden, setDocHidden] = useState(false);
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const onVis = () => setDocHidden(document.hidden);
+    document.addEventListener("visibilitychange", onVis);
+    return () => document.removeEventListener("visibilitychange", onVis);
+  }, []);
+  const [position, setPosition] = useState(logical + clones);
+  const [pitch, setPitch] = useState(0);
+  const [animating, setAnimating] = useState(false);
+  const [drag, setDrag] = useState(
+    null
+  );
+  const [playing, setPlaying] = useState(autoplay > 0);
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  useEffect(() => {
+    if (controlledIndex == null || controlledIndex === committedRef.current)
+      return;
+    const clamped = Math.min(Math.max(controlledIndex, 0), maxIndex);
+    committedRef.current = clamped;
+    setPosition(clamped + clones);
+    setAnimating(enabled);
+  }, [controlledIndex, clones, maxIndex, enabled]);
+  const layoutRef = useRef({ clones, maxIndex });
+  useEffect(() => {
+    const prev2 = layoutRef.current;
+    if (prev2.clones === clones && prev2.maxIndex === maxIndex) return;
+    layoutRef.current = { clones, maxIndex };
+    setAnimating(false);
+    setPosition(logicalRef.current + clones);
+  }, [clones, maxIndex]);
+  const measure = useCallback(() => {
+    const slide = slideRef.current;
+    const track = viewportRef.current?.firstElementChild;
+    if (!slide || !track) return;
+    const gapPx = Number.parseFloat(getComputedStyle(track).columnGap) || 0;
+    const next2 = slide.offsetWidth + gapPx;
+    if (next2 > 0) setPitch((p) => Math.abs(p - next2) < 0.5 ? p : next2);
+  }, []);
+  useResizeObserver(measure, [viewportRef, slideRef]);
+  const commitIndex = useCallback(
+    (next2) => {
+      if (next2 === committedRef.current) return;
+      committedRef.current = next2;
+      if (controlledIndex == null) setUncontrolled(next2);
+      onIndexChange?.(next2);
+    },
+    [controlledIndex, onIndexChange]
+  );
+  const goTo = useCallback(
+    (targetLogical, animate = true) => {
+      const wrapped = canLoop ? (targetLogical % count + count) % count : Math.min(Math.max(targetLogical, 0), maxIndex);
+      logicalRef.current = wrapped;
+      if (canLoop && (targetLogical < 0 || targetLogical >= count)) {
+        const clonePos = targetLogical + clones;
+        if (animate && enabled) {
+          setAnimating(true);
+          setPosition(clonePos);
+        } else {
+          setPosition(wrapped + clones);
+        }
+      } else {
+        setAnimating(animate && enabled);
+        setPosition(wrapped + clones);
+      }
+      commitIndex(wrapped);
+    },
+    [canLoop, count, maxIndex, clones, enabled, commitIndex]
+  );
+  const next = useCallback(() => goTo(logicalRef.current + 1), [goTo]);
+  const prev = useCallback(() => goTo(logicalRef.current - 1), [goTo]);
+  const onTrackTransitionEnd = useCallback(
+    (e) => {
+      if (e.target !== e.currentTarget || e.propertyName !== "translate") return;
+      setAnimating(false);
+      if (!canLoop) return;
+      if (position < clones) setPosition(position + count);
+      else if (position >= clones + count) setPosition(position - count);
+    },
+    [canLoop, clones, count, position]
+  );
+  const dragState = useRef(null);
+  const DRAG_SLOP = 4;
+  const onPointerDown = (e) => {
+    if (!draggable || count <= perView) return;
+    if (e.pointerType === "mouse" && e.button !== 0) return;
+    dragState.current = { id: e.pointerId, startX: e.clientX, captured: false };
+  };
+  const onPointerMove = (e) => {
+    const s = dragState.current;
+    if (!s || s.id !== e.pointerId) return;
+    const delta = e.clientX - s.startX;
+    if (!s.captured) {
+      if (Math.abs(delta) < DRAG_SLOP) return;
+      s.captured = true;
+      e.currentTarget.setPointerCapture?.(e.pointerId);
+      setAnimating(false);
+    }
+    setDrag({ start: s.startX, delta });
+  };
+  const endDrag = (e) => {
+    const s = dragState.current;
+    if (!s || s.id !== e.pointerId) return;
+    dragState.current = null;
+    if (!s.captured) return;
+    e.currentTarget.releasePointerCapture?.(e.pointerId);
+    const delta = e.clientX - s.startX;
+    setDrag(null);
+    if (pitch > 0 && Math.abs(delta) > DRAG_SLOP) {
+      const moved = Math.round(delta / pitch);
+      const steps = moved !== 0 ? moved : delta < 0 ? -1 : 1;
+      const threshold = Math.abs(delta) > pitch * 0.15;
+      if (threshold) goTo(logical - steps);
+      else setAnimating(true);
+    }
+  };
+  const paused = hovered || focused || drag != null || !enabled || docHidden;
+  useEffect(() => {
+    if (autoplay <= 0 || !playing || paused || count <= perView) return;
+    const id = setInterval(next, autoplay);
+    return () => clearInterval(id);
+  }, [autoplay, playing, paused, count, perView, next]);
+  const onKeyDown = (e) => {
+    if (e.key === "ArrowLeft") {
+      e.preventDefault();
+      prev();
+    } else if (e.key === "ArrowRight") {
+      e.preventDefault();
+      next();
+    } else if (e.key === "Home") {
+      e.preventDefault();
+      goTo(0);
+    } else if (e.key === "End") {
+      e.preventDefault();
+      goTo(maxIndex);
+    }
+  };
+  const extended = canLoop ? [...slides.slice(count - clones), ...slides, ...slides.slice(0, clones)] : slides;
+  const basis = `calc((100% - ${perView - 1} * ${gap}) / ${perView})`;
+  const translateX = -(position * pitch) + (drag?.delta ?? 0);
+  const visLo = position - (drag ? 1 : 0);
+  const visHi = position + perView - 1 + (drag ? 1 : 0);
+  const trackStyle = {
+    gap,
+    translate: pitch > 0 ? `${translateX}px 0` : void 0,
+    transition: animating && !drag ? "translate var(--motion-duration-slow) var(--motion-ease-emphasized)" : "none"
+  };
+  const atStart = !canLoop && logical <= 0;
+  const atEnd = !canLoop && logical >= maxIndex;
+  const showArrows = arrows && count > perView;
+  const showDots = dots && count > perView;
+  const liveId = `${baseId}-live`;
+  if (count === 0) return null;
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      "aria-roledescription": "carousel",
+      "aria-label": label ?? "Slides",
+      className: cn("relative flex flex-col", className),
+      onMouseEnter: () => setHovered(true),
+      onMouseLeave: () => setHovered(false),
+      onFocus: () => setFocused(true),
+      onBlur: (e) => {
+        if (!e.currentTarget.contains(e.relatedTarget))
+          setFocused(false);
+      },
+      children: [
+        /* @__PURE__ */ jsxs("div", { className: "relative flex flex-col", children: [
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              ref: viewportRef,
+              role: "group",
+              "aria-label": label ?? "Slides",
+              "aria-keyshortcuts": "ArrowLeft ArrowRight Home End",
+              tabIndex: 0,
+              onKeyDown,
+              onPointerDown,
+              onPointerMove,
+              onPointerUp: endDrag,
+              onPointerCancel: endDrag,
+              style: { "--carousel-bleed": `min(0.25rem, calc(${gap} / 2))` },
+              className: cn(
+                "-m-(--carousel-bleed) overflow-hidden rounded-[calc(var(--radius-lg)+var(--carousel-bleed))] p-(--carousel-bleed) outline-none motion-interactive focus-visible:ring-2 focus-visible:ring-ring",
+                draggable && count > perView && "touch-pan-y",
+                drag ? "cursor-grabbing" : draggable && count > perView && "cursor-grab"
+              ),
+              children: /* @__PURE__ */ jsx(
+                "div",
+                {
+                  className: "flex",
+                  style: trackStyle,
+                  onTransitionEnd: onTrackTransitionEnd,
+                  children: extended.map((slide, i) => {
+                    const realIndex = canLoop ? ((i - clones) % count + count) % count : i;
+                    const offscreen = i < visLo || i > visHi;
+                    return /* @__PURE__ */ jsx(
+                      "div",
+                      {
+                        ref: i === clones ? slideRef : void 0,
+                        role: "group",
+                        "aria-roledescription": "slide",
+                        "aria-label": `${realIndex + 1} of ${count}`,
+                        "aria-hidden": offscreen || void 0,
+                        inert: offscreen || void 0,
+                        className: cn("shrink-0 select-none", slideClassName),
+                        style: { flex: `0 0 ${basis}`, minWidth: 0 },
+                        children: slide
+                      },
+                      i
+                    );
+                  })
+                }
+              )
+            }
+          ),
+          showArrows && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx(
+              CarouselArrowButton,
+              {
+                side: "prev",
+                onClick: prev,
+                disabled: atStart,
+                className: arrowClassName
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              CarouselArrowButton,
+              {
+                side: "next",
+                onClick: next,
+                disabled: atEnd,
+                className: arrowClassName
+              }
+            )
+          ] })
+        ] }),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            id: liveId,
+            "aria-live": playing && !paused ? "off" : "polite",
+            "aria-atomic": true,
+            className: "sr-only",
+            children: `Slide ${logical + 1} of ${count}`
+          }
+        ),
+        (showDots || counter || autoplay > 0) && /* @__PURE__ */ jsxs("div", { className: "mt-3 flex items-center justify-center gap-3", children: [
+          autoplay > 0 && /* @__PURE__ */ jsx(
+            Button,
+            {
+              variant: "ghost",
+              size: "icon-xs",
+              onClick: () => setPlaying((p) => !p),
+              "aria-label": playing ? "Pause autoplay" : "Start autoplay",
+              children: /* @__PURE__ */ jsx(PlayPauseGlyph, { playing })
+            }
+          ),
+          showDots && /* @__PURE__ */ jsx(
+            "div",
+            {
+              role: "group",
+              "aria-label": "Choose slide",
+              className: "flex items-center",
+              children: slides.map((_, i) => (
+                // design-lint-disable-next-line raw-button -- a pagination dot is a 24px hit area around a 6px indicator, not a button-shaped action; Button has no dot anatomy
+                /* @__PURE__ */ jsx(
+                  "button",
+                  {
+                    type: "button",
+                    onClick: () => {
+                      if (i !== logical) goTo(i);
+                    },
+                    "aria-label": `Go to slide ${i + 1}`,
+                    "aria-current": i === logical ? "true" : void 0,
+                    className: "group/dot flex size-6 items-center justify-center rounded-full motion-interactive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                    children: /* @__PURE__ */ jsx(
+                      "span",
+                      {
+                        "aria-hidden": true,
+                        className: cn(
+                          "h-1.5 rounded-full motion-interactive",
+                          i === logical ? "w-4 bg-foreground" : "w-1.5 bg-muted-foreground/40 group-hover/dot:bg-muted-foreground/70"
+                        )
+                      }
+                    )
+                  },
+                  i
+                )
+              ))
+            }
+          ),
+          counter && /* @__PURE__ */ jsxs("span", { className: "text-mono-sm text-muted-foreground tabular-nums", children: [
+            logical + 1,
+            "/",
+            count
+          ] })
+        ] })
+      ]
+    }
+  );
+}
+Carousel.displayName = "Carousel";
+export {
+  Carousel
+};

package/dist/components/carousel/carousel.meta.js

@@ -0,0 +1,100 @@
+// src/components/carousel/carousel.meta.ts
+var carouselMeta = {
+  name: "Carousel",
+  summary: "Generic, accessible, zero-dependency slide carousel. Transform track with measured slide pitch \u2014 multiple slides per view, infinite loop (cloned ends), pointer drag-to-swipe with snap, autoplay (with a pause control + hover/focus/reduced-motion pausing), arrows, dots, counter, and keyboard. Motion is token-driven.",
+  status: "stable",
+  keywords: [
+    "carousel",
+    "gallery",
+    "slides",
+    "horizontal"
+  ],
+  usage: {
+    description: "Use Carousel for a curated, finite sequence of media or cards that benefits from horizontal browsing.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use obvious previous and next controls and make the current position understandable."
+      },
+      {
+        guidance: "do",
+        description: "Keep slide content independent so users do not need every slide to complete a task."
+      },
+      {
+        guidance: "dont",
+        description: "Do not hide critical information or primary conversion actions only inside later slides."
+      },
+      {
+        guidance: "dont",
+        description: "Do not autoplay without a visible pause control. Motion that cannot be stopped fails WCAG 2.2.2 and makes the surrounding text hard to read."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Scroller",
+      "Dialog"
+    ]
+  },
+  props: [
+    { name: "children", type: "ReactNode", description: "Each top-level child becomes one slide." },
+    {
+      name: "slidesToShow",
+      type: "number | { base?: number; sm?: number; md?: number; lg?: number; xl?: number }",
+      default: "1",
+      description: "Slides visible per view. A number, or a mobile-first breakpoint set keyed to Tailwind's default min-widths (sm 640, md 768, lg 1024, xl 1280px); a missing key inherits from the next smaller defined one, and base (default 1) is also the server-render value. Resolved with matchMedia, so no hand-rolled resize hook is needed."
+    },
+    { name: "gap", type: "string", default: '"0px"', description: 'Gap between slides (any CSS length). Use the spacing scale \u2014 e.g. "calc(var(--spacing) * 4)" \u2014 so density moves it.' },
+    { name: "loop", type: "boolean", default: "false", description: "Infinite loop via cloned ends (needs count > slidesToShow)." },
+    { name: "autoplay", type: "number", default: "0", description: "Auto-advance interval in ms (0 = off). Pauses on hover/focus/reduced-motion and exposes a play/pause control." },
+    { name: "arrows", type: "boolean", default: "true", description: "Prev/next arrow buttons." },
+    { name: "dots", type: "boolean", default: "true", description: "Pagination dots." },
+    { name: "counter", type: "boolean", default: "false", description: "An N / M slide counter." },
+    { name: "draggable", type: "boolean", default: "true", description: "Pointer drag-to-swipe." },
+    { name: "index", type: "number", description: "Controlled active index." },
+    { name: "defaultIndex", type: "number", default: "0", description: "Initial index (uncontrolled)." },
+    { name: "onIndexChange", type: "(index: number) => void", description: "Notified when the active index changes." },
+    { name: "label", type: "string", description: "Accessible label for the carousel region." },
+    { name: "slideClassName", type: "string", description: "Class for each slide wrapper (e.g. an aspect ratio)." },
+    {
+      name: "arrowClassName",
+      type: "string",
+      description: "Class for both prev/next arrow buttons. Merged through cn(), so a radius or shadow utility replaces the default rounded-full shadow-md rather than stacking with it."
+    }
+  ],
+  tokensUsed: [
+    "border",
+    "ring",
+    "popover",
+    "popover-foreground",
+    "foreground",
+    "muted-foreground"
+  ],
+  a11y: [
+    "Region carries aria-roledescription='carousel'; each slide is a group with aria-roledescription='slide' and an 'N of M' label; clones are aria-hidden.",
+    "Arrows and dots are real buttons (dots set aria-current); Left/Right arrow keys navigate when the viewport is focused.",
+    "A polite live region announces the active slide; it goes silent while auto-rotating (APG).",
+    "Autoplay exposes a pause/play control and pauses on hover, focus, and under prefers-reduced-motion (which also makes transitions instant)."
+  ],
+  examples: [
+    {
+      label: "Looping media",
+      code: '<Carousel loop dots slideClassName="aspect-video">{images.map((s) => <img key={s.id} src={s.url} alt={s.alt} className="size-full object-cover" />)}</Carousel>'
+    },
+    {
+      label: "Multiple per view",
+      code: '<Carousel slidesToShow={3} gap="calc(var(--spacing) * 4)">{cards}</Carousel>'
+    },
+    {
+      label: "Responsive per view",
+      code: '<Carousel slidesToShow={{ base: 1, sm: 2, lg: 3 }} gap="calc(var(--spacing) * 6)" label="Templates">{cards}</Carousel>'
+    },
+    {
+      label: "Autoplay",
+      code: "<Carousel loop autoplay={4000} counter>{slides}</Carousel>"
+    }
+  ]
+};
+export {
+  carouselMeta
+};

package/dist/components/carousel/index.js

@@ -0,0 +1,7 @@
+// src/components/carousel/index.ts
+import { Carousel } from "./carousel.js";
+import { carouselMeta } from "./carousel.meta.js";
+export {
+  Carousel,
+  carouselMeta
+};