{"name":"tour","title":"Tour","description":"A guided product tour: spotlighted targets, a dimmed backdrop, and positioned step popovers with next/prev/skip/finish actions and progress dots.","installCommand":"bunx marko-ui add tour -y","usageTags":"<Tour>","importSnippet":"import Tour from \"@/components/ui/tour/tour.marko\";\nimport type { TourStep } from \"@/components/ui/tour/tour.marko\";","usageSnippet":"static const steps = [\n  { id: \"welcome\", type: \"dialog\", title: \"Welcome\", description: \"A quick look around.\", actions: [{ label: \"Start\", action: \"next\" }] },\n  { id: \"search\", target: \"#search\", title: \"Search\", description: \"Find anything here.\", actions: [{ label: \"Done\", action: \"dismiss\" }] },\n] satisfies TourStep[];\n\n<Tour items=steps>\n  <@trigger|props|>\n    <Button ...props>Start tour</Button>\n  </@trigger>\n</Tour>","tags":["Tour"],"parts":[{"name":"trigger","param":"Record<string, unknown>","description":"Render-prop for the tour trigger (usually a \"Start tour\" button)."}],"props":[{"name":"closeOnEscape","type":"boolean | undefined","required":false,"default":"true","description":"Whether to close the tour when the user presses the escape key"},{"name":"closeOnInteractOutside","type":"boolean | undefined","required":false,"default":"true","description":"Whether to close the tour when the user clicks outside the tour"},{"name":"dir","type":"'ltr' | 'rtl' | undefined","required":false,"default":"ltr","description":"The document's text/writing direction."},{"name":"getRootNode","type":"(() => ShadowRoot | Document | Node) | undefined","required":false,"description":"A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron."},{"name":"ids","type":"ElementIds | undefined","required":false,"description":"The ids of the elements in the tour. Useful for composition."},{"name":"items","type":"TourStep[]","required":false,"description":"Steps with selector targets — the serializable way to describe a tour."},{"name":"keyboardNavigation","type":"boolean | undefined","required":false,"default":"true","description":"Whether to allow keyboard navigation (right/left arrow keys to navigate between steps)"},{"name":"preventInteraction","type":"boolean | undefined","required":false,"default":"false","description":"Prevents interaction with the rest of the page while the tour is open"},{"name":"spotlightOffset","type":"Point | undefined","required":false,"description":"The offsets to apply to the spotlight"},{"name":"spotlightRadius","type":"number | undefined","required":false,"default":"4","description":"The radius of the spotlight clip path"},{"name":"stepId","type":"string | null | undefined","required":false,"description":"The id of the currently highlighted step"},{"name":"translations","type":"IntlTranslations | undefined","required":false,"description":"The translations for the tour"}],"events":[{"name":"onFocusOutside","arg":"FocusOutsideEvent","description":"Function called when the focus is moved outside the component"},{"name":"onInteractOutside","arg":"InteractOutsideEvent","description":"Function called when an interaction happens outside the component"},{"name":"onPointerDownOutside","arg":"PointerDownOutsideEvent","description":"Function called when the pointer is pressed down outside the component"},{"name":"onStatusChange","arg":"StatusChangeDetails","description":"Callback when the tour is opened or closed"},{"name":"onStepChange","arg":"StepChangeDetails","description":"Callback when the highlighted step changes"},{"name":"onStepsChange","arg":"StepsChangeDetails","description":"Callback when the steps change"},{"name":"statusChange","arg":"tourMachine.StepStatus","description":"Sugar for onStatusChange — receives the plain status."},{"name":"stepIdChange","arg":"string","description":"Sugar for onStepChange — receives the plain step id."}],"keyboard":[],"accessibilityNotes":[],"examples":[{"id":"tour-demo","title":"Default","source":"import Tour from \"@marko-ui/shadcn/ui/tour/tour.marko\";\nimport type { TourStep } from \"@marko-ui/shadcn/ui/tour/tour.marko\";\nimport Button from \"@marko-ui/shadcn/ui/button/button.marko\";\n\nstatic const STEPS = [\n  {\n    id: \"welcome\",\n    title: \"Welcome aboard\",\n    description:\n      \"This short tour walks you through the main areas of the dashboard.\",\n    type: \"dialog\",\n    actions: [\n      { label: \"Skip\", action: \"skip\" },\n      { label: \"Start\", action: \"next\" },\n    ],\n  },\n  {\n    id: \"search\",\n    title: \"Search everything\",\n    description: \"Find projects, people and settings from a single input.\",\n    target: \"#tour-search\",\n    placement: \"bottom\",\n    arrow: true,\n    actions: [\n      { label: \"Back\", action: \"prev\" },\n      { label: \"Next\", action: \"next\" },\n    ],\n  },\n  {\n    id: \"notifications\",\n    title: \"Stay in the loop\",\n    description: \"Unread activity shows up here as soon as it happens.\",\n    target: \"#tour-notifications\",\n    placement: \"bottom-end\",\n    arrow: true,\n    actions: [\n      { label: \"Back\", action: \"prev\" },\n      { label: \"Next\", action: \"next\" },\n    ],\n  },\n  {\n    id: \"publish\",\n    title: \"Ship it\",\n    description: \"When you are happy with your changes, publish them here.\",\n    target: \"#tour-publish\",\n    placement: \"top\",\n    arrow: true,\n    actions: [\n      { label: \"Back\", action: \"prev\" },\n      { label: \"Finish\", action: \"dismiss\" },\n    ],\n  },\n] satisfies TourStep[];\n\n<div class=\"flex w-full flex-col gap-4\">\n  <div class=\"flex items-center gap-3\">\n    <input type=\"text\"\n      id=\"tour-search\"\n      class=\"border-input bg-background h-9 w-56 rounded-md border px-3 text-sm\"\n      placeholder=\"Search…\"\n    />\n    <button type=\"button\"\n      id=\"tour-notifications\"\n      class=\"border-input bg-background hover:bg-accent h-9 rounded-md border px-3 text-sm\"\n    >\n      Notifications\n    </button>\n    <div class=\"grow\"/>\n    <button type=\"button\"\n      id=\"tour-publish\"\n      class=\"bg-primary text-primary-foreground h-9 rounded-md px-4 text-sm font-medium\"\n    >\n      Publish\n    </button>\n  </div>\n  <p class=\"text-muted-foreground text-sm\">\n    The tour highlights the toolbar controls above, one step at a time.\n  </p>\n  <div>\n    <Tour items=STEPS>\n      <@trigger|props|>\n        <Button type=\"button\" ...props id=\"start-tour\" variant=\"outline\">Start tour</Button>\n      </@trigger>\n    </Tour>\n  </div>\n</div>","description":"A four-step tour that opens on a dialog and then spotlights toolbar targets by CSS selector, one at a time."},{"id":"tour-sides","title":"Side placement","source":"import Tour from \"@marko-ui/shadcn/ui/tour/tour.marko\";\nimport type { TourStep } from \"@marko-ui/shadcn/ui/tour/tour.marko\";\nimport Button from \"@marko-ui/shadcn/ui/button/button.marko\";\n\nstatic const STEPS = [\n  {\n    id: \"filters\",\n    title: \"Filters\",\n    description: \"Narrow the list down to what matters right now.\",\n    target: \"#tour-filters\",\n    placement: \"right\",\n    arrow: true,\n    actions: [{ label: \"Next\", action: \"next\" }],\n  },\n  {\n    id: \"export\",\n    title: \"Export\",\n    description: \"Download the current view as CSV.\",\n    target: \"#tour-export\",\n    placement: \"left\",\n    arrow: true,\n    actions: [\n      { label: \"Back\", action: \"prev\" },\n      { label: \"Done\", action: \"dismiss\" },\n    ],\n  },\n] satisfies TourStep[];\n\n<div class=\"flex w-full flex-col gap-4\">\n  <div class=\"flex items-center gap-3\">\n    <button type=\"button\"\n      id=\"tour-filters\"\n      class=\"border-input bg-background hover:bg-accent h-9 rounded-md border px-3 text-sm\"\n    >\n      Filters\n    </button>\n    <button type=\"button\"\n      id=\"tour-export\"\n      class=\"border-input bg-background hover:bg-accent h-9 rounded-md border px-3 text-sm\"\n    >\n      Export\n    </button>\n  </div>\n  <div>\n    <Tour items=STEPS>\n      <@trigger|props|>\n        <Button type=\"button\" ...props id=\"start-short-tour\" variant=\"outline\">\n          Start short tour\n        </Button>\n      </@trigger>\n    </Tour>\n  </div>\n</div>","description":"Steps placed to the `right` and `left` of their targets, each with a single action."},{"id":"tour-controlled","title":"Controlled","source":"import Tour from \"@marko-ui/shadcn/ui/tour/tour.marko\";\nimport type { TourStep } from \"@marko-ui/shadcn/ui/tour/tour.marko\";\nimport Button from \"@marko-ui/shadcn/ui/button/button.marko\";\n\nstatic const STEPS = [\n  {\n    id: \"controlled-one\",\n    title: \"First\",\n    description: \"The parent owns the current step id.\",\n    target: \"#tour-controlled-target\",\n    placement: \"bottom\",\n    arrow: true,\n    actions: [{ label: \"Next\", action: \"next\" }],\n  },\n  {\n    id: \"controlled-two\",\n    title: \"Second\",\n    description: \"Driven entirely from parent state.\",\n    target: \"#tour-controlled-target\",\n    placement: \"top\",\n    arrow: true,\n    actions: [\n      { label: \"Back\", action: \"prev\" },\n      { label: \"Done\", action: \"dismiss\" },\n    ],\n  },\n] satisfies TourStep[];\n\n<let/currentStepId=null as string | null/>\n<let/tourStatus=\"idle\" as string/>\n\n<div class=\"flex w-full flex-col gap-4\">\n  <div>\n    <span\n      id=\"tour-controlled-target\"\n      class=\"border-input bg-background inline-block rounded-md border px-3 py-2 text-sm\"\n    >\n      Controlled target\n    </span>\n  </div>\n  <p id=\"tour-state\" class=\"text-muted-foreground text-sm\">\n    stepId: ${currentStepId ?? \"none\"} · status: ${tourStatus}\n  </p>\n  <div>\n    <Tour\n      items=STEPS\n      stepId=currentStepId\n      stepIdChange=(stepId) => { currentStepId = stepId; }\n      statusChange=(status) => { tourStatus = status; }\n    >\n      <@trigger|props|>\n        <Button type=\"button\" ...props id=\"start-controlled-tour\" variant=\"outline\">\n          Start controlled tour\n        </Button>\n      </@trigger>\n    </Tour>\n  </div>\n</div>","description":"Pair `stepId` with `stepIdChange` (or Marko's bind shorthand `stepId:=state`) to drive the current step from parent state, and `statusChange` to observe the tour's lifecycle."}],"importInstallCommand":"bun add @marko-ui/shadcn marko-zag","requires":["button"],"nativeAttributes":"div","itemTypes":[{"prop":"items","typeName":"TourStep","fields":[{"name":"target","type":"string | undefined","required":false,"description":"CSS selector of the element this step highlights. Omit for a modal step."}]}]}