{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "tour",
  "type": "registry:ui",
  "title": "Tour",
  "description": "A guided walk through an interface: a card beside each element in turn, with the element ringed, its step number (\"2 of 5\"), Back, Next and Skip, focus moved into the card, the element scrolled into view, and Escape to end at any point.",
  "categories": [
    "ui"
  ],
  "dependencies": [
    "lucide-react"
  ],
  "registryDependencies": [
    "@rivier-ui/theme",
    "@rivier-ui/button",
    "@rivier-ui/cn",
    "@rivier-ui/use-controllable-state"
  ],
  "files": [
    {
      "path": "registry/ui/tour.tsx",
      "type": "registry:ui",
      "target": "components/ui/tour.tsx",
      "content": "\"use client\";\n/**\n * @name tour\n * @category ui\n * @description A guided walk through an interface: a card beside each element in turn, with the element ringed, its step number (\"2 of 5\"), Back, Next and Skip, focus moved into the card, the element scrolled into view, and Escape to end at any point.\n * @when Showing a new or changed interface once, on request or the first time: where things are, a new feature. Keep it to a few steps and let people leave at once; never block the page. For one hint use tooltip or popover; for a task done in steps use wizard.\n * @example\n * <Tour\n *   open={touring}\n *   onOpenChange={setTouring}\n *   steps={[\n *     { target: \"#search\", title: \"Search\", body: \"Find any file by its name or its words.\" },\n *     { target: \"#share\", title: \"Share\", body: \"Send a link to the people you work with.\" },\n *   ]}\n * />\n */\nimport { X } from \"lucide-react\";\nimport { useEffect, useId, useLayoutEffect, useRef, useState, type ComponentProps, type ReactNode } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { cn } from \"@/lib/cn\";\nimport { useControllableState } from \"@/lib/use-controllable-state\";\nimport { buttonVariants } from \"@/components/ui/button\";\n\nexport type TourStep = {\n  /** A CSS selector for the element the step is about: \"#search\", \"[data-tour=share]\". */\n  target: string;\n  title: string;\n  body: ReactNode;\n};\n\nexport type TourLabels = { back: string; next: string; done: string; skip: string; close: string; progress: (step: number, count: number) => string };\n\nconst LABELS: TourLabels = { back: \"Back\", next: \"Next\", done: \"Done\", skip: \"Skip the tour\", close: \"End the tour\", progress: (step, count) => `${step} of ${count}` };\n\nexport type TourProps = Omit<ComponentProps<\"div\">, \"children\"> & {\n  steps: readonly TourStep[];\n  open?: boolean;\n  defaultOpen?: boolean;\n  onOpenChange?: (open: boolean) => void;\n  /** The step shown, from 0. Controlled with `onStepChange`. */\n  step?: number;\n  defaultStep?: number;\n  onStepChange?: (step: number) => void;\n  /** Called when the last step's button is pressed (not when the tour is skipped). */\n  onComplete?: () => void;\n  labels?: Partial<TourLabels>;\n};\n\ntype Box = { top: number; left: number; width: number; height: number };\n\nexport function Tour({ steps, open: openProp, defaultOpen = false, onOpenChange, step: stepProp, defaultStep = 0, onStepChange, onComplete, labels: given, className, ...props }: TourProps) {\n  const labels = { ...LABELS, ...given };\n  const [open, setOpen] = useControllableState<boolean>({ value: openProp, defaultValue: defaultOpen, onChange: onOpenChange });\n  const [index, setIndex] = useControllableState<number>({ value: stepProp, defaultValue: defaultStep, onChange: onStepChange });\n  const [box, setBox] = useState<Box | null>(null);\n  const card = useRef<HTMLDivElement>(null);\n  const opener = useRef<Element | null>(null);\n  const titleId = useId();\n  const current = steps[Math.max(0, Math.min(steps.length - 1, index))];\n\n  // Follow the target as the page scrolls and resizes; measured in a frame, never during render.\n  useLayoutEffect(() => {\n    if (!open || !current) return;\n    let frame = 0;\n    const measure = (): void => {\n      cancelAnimationFrame(frame);\n      frame = requestAnimationFrame(() => {\n        const element = document.querySelector(current.target);\n        const rect = element?.getBoundingClientRect();\n        setBox(rect ? { top: rect.top, left: rect.left, width: rect.width, height: rect.height } : null);\n      });\n    };\n    document.querySelector(current.target)?.scrollIntoView({ block: \"center\", behavior: \"instant\" });\n    measure();\n    window.addEventListener(\"scroll\", measure, true);\n    window.addEventListener(\"resize\", measure);\n    return () => {\n      cancelAnimationFrame(frame);\n      window.removeEventListener(\"scroll\", measure, true);\n      window.removeEventListener(\"resize\", measure);\n    };\n  }, [open, current]);\n\n  // Focus goes into the card at each step, and back to where it was when the tour ends.\n  useEffect(() => {\n    if (!open) return;\n    opener.current ??= document.activeElement;\n    card.current?.focus();\n  }, [open, index]);\n  const end = (): void => {\n    setOpen(false);\n    const back = opener.current as HTMLElement | null;\n    opener.current = null;\n    requestAnimationFrame(() => back?.focus?.());\n  };\n\n  if (!open || !current || typeof document === \"undefined\") return null;\n  const last = index >= steps.length - 1;\n  const gap = 12;\n  const width = Math.min(320, window.innerWidth - 16);\n  // Below the target when there is room, else above; kept inside the window.\n  const below = !box || box.top + box.height + 200 < window.innerHeight;\n  const top = box ? (below ? box.top + box.height + gap : Math.max(8, box.top - gap)) : window.innerHeight / 2;\n  const left = box ? Math.max(8, Math.min(window.innerWidth - width - 8, box.left + box.width / 2 - width / 2)) : (window.innerWidth - width) / 2;\n\n  return createPortal(\n    <>\n      {box ? (\n        <div\n          data-slot=\"tour-ring\"\n          aria-hidden=\"true\"\n          className=\"pointer-events-none fixed z-[60] rounded-surface outline-2 outline-offset-4 outline-ring\"\n          style={{ top: box.top, left: box.left, width: box.width, height: box.height }}\n        />\n      ) : null}\n      <div\n        ref={card}\n        data-slot=\"tour\"\n        role=\"dialog\"\n        aria-modal=\"false\"\n        aria-labelledby={titleId}\n        tabIndex={-1}\n        onKeyDown={(event) => {\n          if (event.key === \"Escape\") {\n            event.preventDefault();\n            end();\n          }\n        }}\n        className={cn(\"fixed z-[61] flex flex-col gap-3 rounded-surface border bg-popover p-4 text-sm text-popover-foreground outline-none animate-in fade-in-0 motion-reduce:animate-none\", className)}\n        style={{ top, left, width, transform: below ? undefined : \"translateY(-100%)\" }}\n        {...props}\n      >\n        <div className=\"flex items-start justify-between gap-3\">\n          <div className=\"flex flex-col gap-0.5\">\n            <span className=\"text-xs tabular-nums text-muted-foreground\">{labels.progress(index + 1, steps.length)}</span>\n            <h2 id={titleId} className=\"text-base font-medium\">\n              {current.title}\n            </h2>\n          </div>\n          <button type=\"button\" aria-label={labels.close} onClick={end} className=\"-me-2 -mt-2 flex size-9 shrink-0 items-center justify-center rounded-control text-muted-foreground hover:bg-accent\">\n            <X aria-hidden=\"true\" className=\"size-4\" />\n          </button>\n        </div>\n        <div className=\"text-muted-foreground\">{current.body}</div>\n        <div className=\"flex flex-wrap items-center justify-between gap-2\">\n          {!last ? (\n            <button type=\"button\" onClick={end} className={buttonVariants({ variant: \"link\", size: \"sm\" })}>\n              {labels.skip}\n            </button>\n          ) : (\n            <span />\n          )}\n          <div className=\"flex gap-2\">\n            {index > 0 ? (\n              <button type=\"button\" onClick={() => setIndex(index - 1)} className={buttonVariants({ variant: \"outline\", size: \"sm\" })}>\n                {labels.back}\n              </button>\n            ) : null}\n            <button\n              type=\"button\"\n              onClick={() => {\n                if (last) {\n                  onComplete?.();\n                  end();\n                } else setIndex(index + 1);\n              }}\n              className={buttonVariants({ size: \"sm\" })}\n            >\n              {last ? labels.done : labels.next}\n            </button>\n          </div>\n        </div>\n      </div>\n    </>,\n    document.body,\n  );\n}\n"
    }
  ],
  "meta": {
    "category": "ui",
    "when": "Showing a new or changed interface once, on request or the first time: where things are, a new feature. Keep it to a few steps and let people leave at once; never block the page. For one hint use tooltip or popover; for a task done in steps use wizard.",
    "example": "<Tour\n  open={touring}\n  onOpenChange={setTouring}\n  steps={[\n    { target: \"#search\", title: \"Search\", body: \"Find any file by its name or its words.\" },\n    { target: \"#share\", title: \"Share\", body: \"Send a link to the people you work with.\" },\n  ]}\n/>",
    "client": true
  }
}
