{
  "schemaVersion": 1,
  "target": "react",
  "name": "carousel",
  "version": "0.1.1",
  "category": "data",
  "title": "Carousel",
  "description": "A CSS scroll-snap carousel with previous and next buttons, dots, arrow-key support, and optional autoplay that pauses on hover, focus, and reduced motion.",
  "tags": [
    "carousel",
    "slider",
    "scroll-snap",
    "media"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [],
  "docsPath": "/components/carousel",
  "props": [
    {
      "name": "Carousel label",
      "type": "string",
      "description": "Accessible name of the carousel region."
    },
    {
      "name": "Carousel autoplay",
      "type": "number | false",
      "default": "false",
      "description": "Advances every n milliseconds. Pauses on hover, on focus inside, in a hidden tab, and under reduced motion."
    },
    {
      "name": "Carousel loop",
      "type": "boolean",
      "default": "false",
      "description": "The arrows wrap at the ends. Autoplay always wraps."
    },
    {
      "name": "CarouselContent gapClassName",
      "type": "string",
      "default": "\"gap-3\"",
      "description": "Gap between slides."
    },
    {
      "name": "CarouselItem index / total",
      "type": "number",
      "description": "Position for the \"2 of 5\" slide label."
    },
    {
      "name": "CarouselItem className",
      "type": "string",
      "description": "Pass a basis class such as sm:basis-1/2 to show several slides."
    },
    {
      "name": "CarouselPrevious / CarouselNext / CarouselDots / CarouselPlayToggle / CarouselControls",
      "type": "button / div props",
      "description": "Controls; dots map to resting positions, not to slides hidden behind a partial view."
    }
  ],
  "accessibility": [
    "The root is a section with aria-roledescription=\"carousel\" and its label; each slide is a group with aria-roledescription=\"slide\" and an \"n of total\" label.",
    "Left and Right arrow keys move one stop while focus is anywhere inside, except in text fields.",
    "The track is focusable and scrolls natively by touch, trackpad, and wheel; snapping is pure CSS.",
    "Autoplay stops while hovered or focused, in a hidden tab, and entirely under reduced motion; CarouselPlayToggle lets anyone pause it.",
    "Slide changes are announced politely only when autoplay is not running, and smooth scrolling becomes instant under reduced motion."
  ],
  "states": [
    "start",
    "middle",
    "end",
    "autoplaying",
    "paused"
  ],
  "files": [
    {
      "path": "ui/carousel.tsx",
      "content": "\"use client\";\n\nimport {\n  Children,\n  type ComponentProps,\n  createContext,\n  type KeyboardEvent,\n  type ReactNode,\n  type RefObject,\n  useCallback,\n  useContext,\n  useEffect,\n  useRef,\n  useState,\n} from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\ntype CarouselContextValue = {\n  viewportRef: RefObject<HTMLDivElement | null>;\n  /** Scroll offsets the carousel can rest at, one per dot. */\n  stops: number[];\n  index: number;\n  canPrev: boolean;\n  canNext: boolean;\n  goTo: (stop: number) => void;\n  prev: () => void;\n  next: () => void;\n  /** The user's choice from the play toggle. */\n  playing: boolean;\n  /** Whether slides are advancing right now (not held by hover or focus). */\n  running: boolean;\n  autoplay: boolean;\n  togglePlaying: () => void;\n  register: () => void;\n  label: string;\n};\n\nconst CarouselContext = createContext<CarouselContextValue | null>(null);\n\nfunction useCarousel(part: string) {\n  const context = useContext(CarouselContext);\n  if (!context) throw new Error(`${part} must be used inside <Carousel>.`);\n  return context;\n}\n\nfunction prefersReducedMotion() {\n  return typeof window !== \"undefined\" && window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches;\n}\n\nexport interface CarouselProps extends ComponentProps<\"section\"> {\n  /** Accessible name, for example \"Release highlights\". */\n  label: string;\n  /** Advances on a timer, in milliseconds. Pauses on hover, on focus, in a hidden tab, and under reduced motion. */\n  autoplay?: number | false;\n  /** Wraps from the last slide to the first with the arrows. Autoplay always wraps. */\n  loop?: boolean;\n}\n\n/**\n * A carousel built on CSS scroll snapping, so touch, trackpad, and wheel scrolling feel native.\n * Arrow keys move between slides while focus is inside it. Compose it from `CarouselContent`,\n * `CarouselItem`, `CarouselPrevious`, `CarouselNext`, `CarouselDots`, and `CarouselPlayToggle`.\n */\nexport function Carousel({ label, autoplay = false, loop = false, className, children, onKeyDown, ...props }: CarouselProps) {\n  const viewportRef = useRef<HTMLDivElement>(null);\n  const rootRef = useRef<HTMLElement>(null);\n  const [stops, setStops] = useState<number[]>([0]);\n  const stopsRef = useRef<number[]>([0]);\n  const [index, setIndex] = useState(0);\n  const [version, setVersion] = useState(0);\n  // Playing is the user's choice (the play toggle); paused is the temporary hover/focus hold.\n  const [playing, setPlaying] = useState(autoplay !== false);\n  const [held, setHeld] = useState(false);\n  const [reduced, setReduced] = useState(false);\n\n  const measure = useCallback(() => {\n    const viewport = viewportRef.current;\n    if (!viewport) return;\n    const max = viewport.scrollWidth - viewport.clientWidth;\n    const start = viewport.getBoundingClientRect().left - viewport.scrollLeft;\n    const items = Array.from(viewport.querySelectorAll<HTMLElement>(\"[data-slot=carousel-item]\"));\n    const padStart = Number.parseFloat(getComputedStyle(viewport).scrollPaddingInlineStart) || 0;\n    const offsets = items.map((item) => Math.min(max, Math.max(0, Math.round(item.getBoundingClientRect().left - start - padStart))));\n    const unique = offsets.filter((offset, i) => i === 0 || offset - offsets[i - 1]! > 2);\n    stopsRef.current = unique.length ? unique : [0];\n    setStops(stopsRef.current);\n  }, []);\n\n  const sync = useCallback(() => {\n    const viewport = viewportRef.current;\n    if (!viewport) return;\n    const current = stopsRef.current;\n    const left = viewport.scrollLeft;\n    let nearest = 0;\n    current.forEach((stop, i) => {\n      if (Math.abs(stop - left) < Math.abs(current[nearest]! - left)) nearest = i;\n    });\n    setIndex(nearest);\n  }, []);\n\n  useEffect(() => {\n    const viewport = viewportRef.current;\n    if (!viewport) return;\n    measure();\n    sync();\n    const observer = new ResizeObserver(() => {\n      measure();\n      sync();\n    });\n    observer.observe(viewport);\n    let frame = 0;\n    const onScroll = () => {\n      cancelAnimationFrame(frame);\n      frame = requestAnimationFrame(sync);\n    };\n    viewport.addEventListener(\"scroll\", onScroll, { passive: true });\n    return () => {\n      observer.disconnect();\n      viewport.removeEventListener(\"scroll\", onScroll);\n      cancelAnimationFrame(frame);\n    };\n  }, [measure, sync, version]);\n\n  useEffect(() => {\n    const query = window.matchMedia(\"(prefers-reduced-motion: reduce)\");\n    const update = () => setReduced(query.matches);\n    update();\n    query.addEventListener(\"change\", update);\n    return () => query.removeEventListener(\"change\", update);\n  }, []);\n\n  const goTo = useCallback(\n    (stop: number) => {\n      const viewport = viewportRef.current;\n      const target = stops[Math.max(0, Math.min(stops.length - 1, stop))];\n      if (!viewport || target === undefined) return;\n      viewport.scrollTo({ left: target, behavior: prefersReducedMotion() ? \"auto\" : \"smooth\" });\n    },\n    [stops],\n  );\n\n  const last = stops.length - 1;\n  const prev = useCallback(() => goTo(index === 0 && loop ? last : index - 1), [goTo, index, loop, last]);\n  const next = useCallback(() => goTo(index === last && loop ? 0 : index + 1), [goTo, index, loop, last]);\n\n  const running = autoplay !== false && playing && !held && !reduced && last > 0;\n  useEffect(() => {\n    if (!running) return;\n    const timer = setInterval(() => {\n      if (document.hidden) return;\n      goTo(index >= last ? 0 : index + 1);\n    }, autoplay);\n    return () => clearInterval(timer);\n  }, [running, autoplay, goTo, index, last]);\n\n  function handleKeyDown(event: KeyboardEvent<HTMLElement>) {\n    onKeyDown?.(event);\n    if (event.defaultPrevented) return;\n    const target = event.target as HTMLElement;\n    if (target.closest(\"input, textarea, select, [contenteditable=true]\")) return;\n    if (event.key === \"ArrowLeft\") {\n      event.preventDefault();\n      prev();\n    } else if (event.key === \"ArrowRight\") {\n      event.preventDefault();\n      next();\n    }\n  }\n\n  return (\n    <CarouselContext.Provider\n      value={{\n        viewportRef,\n        stops,\n        index,\n        canPrev: loop || index > 0,\n        canNext: loop || index < last,\n        goTo,\n        prev,\n        next,\n        playing,\n        running,\n        autoplay: autoplay !== false && !reduced,\n        togglePlaying: () => setPlaying((value) => !value),\n        register: () => setVersion((value) => value + 1),\n        label,\n      }}\n    >\n      <section\n        ref={rootRef}\n        aria-roledescription=\"carousel\"\n        aria-label={label}\n        data-slot=\"carousel\"\n        data-playing={running || undefined}\n        onKeyDown={handleKeyDown}\n        onPointerEnter={(event) => event.pointerType === \"mouse\" && setHeld(true)}\n        onPointerLeave={(event) => event.pointerType === \"mouse\" && setHeld(false)}\n        onFocus={() => setHeld(true)}\n        onBlur={(event) => {\n          if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setHeld(false);\n        }}\n        className={cx(\"relative grid min-w-0 gap-3\", className)}\n        {...props}\n      >\n        {children}\n      </section>\n    </CarouselContext.Provider>\n  );\n}\n\nexport interface CarouselContentProps extends ComponentProps<\"div\"> {\n  /** Gap between slides, as a Tailwind gap class. */\n  gapClassName?: string;\n}\n\n/**\n * The scrolling track. Slides snap to its start edge; the scrollbar is hidden because the\n * arrows, dots, and swipe already show position.\n */\nexport function CarouselContent({ gapClassName = \"gap-3\", className, children, ...props }: CarouselContentProps) {\n  const { viewportRef, register, running } = useCarousel(\"CarouselContent\");\n  const count = Children.count(children);\n  useEffect(register, [count]); // eslint-disable-line react-hooks/exhaustive-deps\n\n  return (\n    <div\n      ref={viewportRef}\n      data-slot=\"carousel-content\"\n      // Announce slide changes only when the user caused them, not on every autoplay tick.\n      aria-live={running ? \"off\" : \"polite\"}\n      tabIndex={0}\n      className={cx(\n        \"flex snap-x snap-mandatory overflow-x-auto overscroll-x-contain\",\n        \"[scrollbar-width:none] [&::-webkit-scrollbar]:hidden\",\n        \"rounded-xl outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n        gapClassName,\n        className,\n      )}\n      {...props}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport interface CarouselItemProps extends ComponentProps<\"div\"> {\n  /** Position, used for the \"3 of 5\" announcement. Set automatically when omitted. */\n  index?: number;\n  /** Total slides, used with `index`. */\n  total?: number;\n}\n\n/**\n * One slide. Full width by default; pass a basis class such as `basis-1/2 sm:basis-1/3` to show\n * several at once.\n */\nexport function CarouselItem({ index, total, className, ...props }: CarouselItemProps) {\n  return (\n    <div\n      role=\"group\"\n      aria-roledescription=\"slide\"\n      aria-label={index !== undefined && total !== undefined ? `${index + 1} of ${total}` : undefined}\n      data-slot=\"carousel-item\"\n      className={cx(\"min-w-0 shrink-0 grow-0 basis-full snap-start\", className)}\n      {...props}\n    />\n  );\n}\n\nfunction ArrowButton({ direction, className, ...props }: ComponentProps<\"button\"> & { direction: \"prev\" | \"next\" }) {\n  const carousel = useCarousel(direction === \"prev\" ? \"CarouselPrevious\" : \"CarouselNext\");\n  const enabled = direction === \"prev\" ? carousel.canPrev : carousel.canNext;\n  return (\n    <button\n      type=\"button\"\n      aria-label={direction === \"prev\" ? \"Previous slide\" : \"Next slide\"}\n      disabled={!enabled}\n      onClick={direction === \"prev\" ? carousel.prev : carousel.next}\n      className={cx(\n        \"inline-flex size-8 shrink-0 items-center justify-center rounded-lg border select-none\",\n        \"border-zinc-950/12 bg-white text-zinc-700 hover:border-zinc-950/20 hover:bg-zinc-950/[0.03] hover:text-zinc-950\",\n        \"dark:border-white/15 dark:bg-black dark:text-zinc-300 dark:hover:border-white/25 dark:hover:bg-white/[0.06] dark:hover:text-white\",\n        \"transition-[background-color,border-color,color,scale,opacity] duration-150 ease-out active:duration-100 motion-safe:active:scale-[0.94] motion-reduce:transition-none\",\n        \"focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n        \"disabled:pointer-events-none disabled:opacity-40\",\n        className,\n      )}\n      {...props}\n    >\n      <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" className=\"size-4\">\n        <path\n          d={direction === \"prev\" ? \"M10 3.5 5.5 8l4.5 4.5\" : \"M6 3.5 10.5 8 6 12.5\"}\n          stroke=\"currentColor\"\n          strokeWidth=\"1.5\"\n          strokeLinecap=\"round\"\n          strokeLinejoin=\"round\"\n        />\n      </svg>\n    </button>\n  );\n}\n\n/** Scrolls back one stop. Disabled at the start unless the carousel loops. */\nexport function CarouselPrevious(props: ComponentProps<\"button\">) {\n  return <ArrowButton direction=\"prev\" {...props} />;\n}\n\n/** Scrolls forward one stop. Disabled at the end unless the carousel loops. */\nexport function CarouselNext(props: ComponentProps<\"button\">) {\n  return <ArrowButton direction=\"next\" {...props} />;\n}\n\n/** One dot per resting position. The current dot is solid and marked `aria-current`. */\nexport function CarouselDots({ className, ...props }: ComponentProps<\"div\">) {\n  const { stops, index, goTo } = useCarousel(\"CarouselDots\");\n  if (stops.length < 2) return null;\n  return (\n    <div role=\"group\" aria-label=\"Choose slide\" data-slot=\"carousel-dots\" className={cx(\"flex items-center\", className)} {...props}>\n      {stops.map((_, i) => (\n        <button\n          key={i}\n          type=\"button\"\n          aria-label={`Go to slide ${i + 1}`}\n          aria-current={i === index ? \"true\" : undefined}\n          onClick={() => goTo(i)}\n          className=\"group/dot inline-flex size-6 items-center justify-center rounded-md focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-sky-500\"\n        >\n          <span\n            aria-hidden=\"true\"\n            className={cx(\n              \"size-1.5 rounded-full transition-[background-color,scale] duration-200 ease-out motion-reduce:transition-none\",\n              i === index\n                ? \"scale-125 bg-zinc-950 dark:bg-white\"\n                : \"bg-zinc-950/20 group-hover/dot:bg-zinc-950/40 dark:bg-white/25 dark:group-hover/dot:bg-white/45\",\n            )}\n          />\n        </button>\n      ))}\n    </div>\n  );\n}\n\n/**\n * Pauses and resumes autoplay, so moving content can always be stopped. Renders nothing when\n * autoplay is off or reduced motion is preferred.\n */\nexport function CarouselPlayToggle({ className, ...props }: ComponentProps<\"button\">) {\n  const { autoplay, playing, togglePlaying } = useCarousel(\"CarouselPlayToggle\");\n  if (!autoplay) return null;\n  const showPause = playing;\n  return (\n    <button\n      type=\"button\"\n      aria-label={showPause ? \"Pause autoplay\" : \"Start autoplay\"}\n      onClick={togglePlaying}\n      className={cx(\n        \"inline-flex size-8 items-center justify-center rounded-lg text-zinc-500\",\n        \"transition-[background-color,color] duration-150 ease-out motion-reduce:transition-none\",\n        \"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white\",\n        \"focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n        className,\n      )}\n      {...props}\n    >\n      <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" className=\"size-4\">\n        {showPause ? (\n          <path d=\"M5.75 3.75v8.5M10.25 3.75v8.5\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" />\n        ) : (\n          <path d=\"M5.25 3.6v8.8a.5.5 0 0 0 .77.42l6.6-4.4a.5.5 0 0 0 0-.84l-6.6-4.4a.5.5 0 0 0-.77.42Z\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinejoin=\"round\" />\n        )}\n      </svg>\n    </button>\n  );\n}\n\n/** Lays out the arrows, dots, and play toggle in one quiet row. Optional. */\nexport function CarouselControls({ className, children, ...props }: ComponentProps<\"div\"> & { children?: ReactNode }) {\n  return (\n    <div data-slot=\"carousel-controls\" className={cx(\"flex items-center gap-2\", className)} {...props}>\n      {children}\n    </div>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "import { Carousel, CarouselContent, CarouselControls, CarouselDots, CarouselItem, CarouselNext, CarouselPlayToggle, CarouselPrevious } from \"@/components/shaken/ui/carousel\";\n\nconst releases = [\n  { version: \"v0.9\", title: \"Approval gates\", body: \"Pause any tool call until a person approves it, with the exact command shown.\" },\n  { version: \"v0.8\", title: \"Trace inspector\", body: \"Step through every model call and tool result in a run, with timings.\" },\n  { version: \"v0.7\", title: \"Streaming messages\", body: \"Tokens render as they arrive, with a caret that stops when the run ends.\" },\n  { version: \"v0.6\", title: \"Run graphs\", body: \"See how sub-agents hand work to each other, and where a run is waiting.\" },\n  { version: \"v0.5\", title: \"Prompt composer\", body: \"Attach files, pick tools, and send with a shortcut from one field.\" },\n];\n\nexport default function CarouselExample() {\n  return (\n    <Carousel label=\"Release highlights\" autoplay={6000} className=\"w-full max-w-2xl\">\n      <CarouselContent>\n        {releases.map((release, i) => (\n          <CarouselItem key={release.version} index={i} total={releases.length} className=\"sm:basis-[calc(50%-0.375rem)]\">\n            <article className=\"grid h-full content-start gap-2 rounded-xl border border-zinc-950/10 bg-white p-5 text-zinc-950 dark:border-white/10 dark:bg-black dark:text-white\">\n              <span className=\"font-mono text-xs text-zinc-500\">{release.version}</span>\n              <h3 className=\"text-base font-semibold\">{release.title}</h3>\n              <p className=\"text-sm text-zinc-600 dark:text-zinc-400\">{release.body}</p>\n            </article>\n          </CarouselItem>\n        ))}\n      </CarouselContent>\n      <CarouselControls>\n        <CarouselDots className=\"-ms-1.5\" />\n        <div className=\"ms-auto flex items-center gap-1.5\">\n          <CarouselPlayToggle />\n          <CarouselPrevious />\n          <CarouselNext />\n        </div>\n      </CarouselControls>\n    </Carousel>\n  );\n}\n"
  }
}
