{
  "name": "Tour",
  "source": "src/components/Tour.tsx",
  "propsType": "TourProps",
  "description": "Tour — Coachmarks in a sequence: one at a time, each pointing at its\ntarget, with where the reader is (\"2 of 4\"), Back, Next, and Done on the\nlast. The close button and Escape end it; focus goes back to what started\nit, once, at the end.\n\nSTEPS ARE DATA\n\nA step names its target by `id`, so a tour is a list anyone can write\nwithout threading refs through the page. A target that is not on the page\nwhen the tour starts — removed, or hidden at a phone's width — is skipped,\nand the count is of the steps that remain: \"3 of 3\", never \"3 of 4\" with a\nstep that points at nothing.\n\nFINISHED IS NOT DISMISSED\n\n`onComplete` fires for Done on the last step only. Ended early, the tour\ncalls `onOpenChange(false)` alone, so a product can offer it again to\nsomeone who stopped halfway and not to someone who saw it through.",
  "import": "import { Tour } from 'ionbase-ui';",
  "status": "stable",
  "summary": "Coachmarks in a sequence — one at a time, each pointing at its target, with \"2 of 4\", Back, Next, and Done on the last. Steps are data, naming their targets by id; a target not on the page is skipped.",
  "useWhen": [
    "a first look round a page someone asked to be shown — \"Take the tour\"",
    "several places matter in an order, and each is best explained beside it",
    "the product wants to know who saw it through: `onComplete` fires for Done only"
  ],
  "useInstead": [
    {
      "when": "one place, one thing to say",
      "use": "Coachmark",
      "why": "a tour of one has no count and no Back; a Coachmark says the same with less"
    },
    {
      "when": "the page itself is new to everyone and needs no pointing — an empty workspace",
      "use": "EmptyState",
      "why": "an empty page explains itself in place; a tour pointing at nothing yet is five dialogs for one sentence"
    },
    {
      "when": "telling people something changed without their asking",
      "use": "Banner",
      "why": "a tour takes focus at every step; opened unasked it takes over the page"
    }
  ],
  "composition": {
    "order": [
      "Tour"
    ],
    "note": "Start it from a button — `isOpen` from its press — and end it through `onOpenChange(false)`. Each step is `{ target: id, title, body, placement? }`. Remember a finished tour in `onComplete`, and offer it again to someone who ended it early. Every string is in `labels`; `progress` receives the current step and the total as numbers.",
    "example": "<Tour isOpen={touring} onOpenChange={setTouring} onComplete={markSeen} steps={[{ target: 'overview-range', title: 'Pick the period', body: 'Every figure follows the dates chosen here.' }]} />"
  },
  "a11y": {
    "requires": [
      "start it from a person's action, never on page load: every step takes focus",
      "an `id` on every target, and a `title` on every step — it names that step's dialog"
    ],
    "guarantees": [
      "one step at a time, each a Coachmark: a non-modal dialog named by its title, focused when it appears so each step is read out",
      "the count, Back and Next / Done sit in each step's footer; there is no Back on the first step, and one step alone has no count",
      "a target not on the page when the tour starts — removed, or not drawn at this width — is skipped, and the count is of the steps that remain",
      "Done on the last step calls `onComplete` and ends the tour; the close button (`labels.close`, \"End tour\") and Escape end it without completing it",
      "focus goes back to what started the tour once, when it ends, not between steps",
      "started again, it begins at the first step",
      "`onStepChange` receives the step's index in `steps`, so a skipped step never appears in it"
    ],
    "notes": [
      "The page is measured once, when the tour starts: a target that appears mid-tour is not added, so the count never changes under the reader."
    ]
  },
  "antiPatterns": [
    {
      "dont": "<Tour isOpen={!seen} … /> on first visit",
      "do": "a \"Take the tour\" button, with `seen` deciding only whether to offer it",
      "why": "a tour that opens itself takes focus from whoever arrived to do something else"
    },
    {
      "dont": "steps pointing at elements that exist only after a click in an earlier step",
      "do": "steps over what is on the page when the tour starts",
      "why": "the page is measured when the tour starts; a target that was not there is skipped, and the step with it"
    },
    {
      "dont": "marking the tour seen in `onOpenChange(false)`",
      "do": "`onComplete`",
      "why": "Escape on step one is not the same as reading it through; only one of them should stop the offer"
    }
  ],
  "stylesheet": null,
  "tokens": [],
  "props": {
    "steps": {
      "type": "TourStep[]",
      "required": true,
      "origin": "own",
      "description": "The steps, in order. A step whose target is not on the page is skipped."
    },
    "isOpen": {
      "type": "boolean",
      "required": true,
      "origin": "own",
      "description": "Running or not. Start it from a button — see Coachmark on why."
    },
    "onOpenChange": {
      "type": "(isOpen: boolean) => void",
      "required": true,
      "origin": "own",
      "description": "`false` when it ends: Done, the close button or Escape."
    },
    "onComplete": {
      "type": "(() => void) | undefined",
      "required": false,
      "origin": "own",
      "description": "Done on the last step — finished, not abandoned. Remember it here."
    },
    "onStepChange": {
      "type": "((index: number) => void) | undefined",
      "required": false,
      "origin": "own",
      "description": "The step shown, by its index in `steps`."
    },
    "labels": {
      "type": "TourLabels | undefined",
      "required": false,
      "origin": "own"
    }
  },
  "propCounts": {
    "own": 6,
    "aria": 0,
    "dom": 0,
    "other": 0
  }
}