@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/tour.json

@@ -0,0 +1,773 @@
+{
+  "family": "tour",
+  "ui": "tour",
+  "binding": "react",
+  "catalog": {
+    "group": "Overlays",
+    "summary": "Guided steps anchored to elements."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "side": [
+      "top",
+      "bottom",
+      "inline-start",
+      "inline-end",
+      "left",
+      "right"
+    ],
+    "align": [
+      "start",
+      "center",
+      "end"
+    ],
+    "modal": [
+      true,
+      false
+    ],
+    "spotlight": [
+      true,
+      false
+    ],
+    "arrow": [
+      true,
+      false
+    ],
+    "autoFocus": [
+      true,
+      false
+    ],
+    "closeOnEscape": [
+      true,
+      false
+    ],
+    "closeOnOutsidePress": [
+      true,
+      false
+    ],
+    "scrollIntoView": [
+      true,
+      false
+    ],
+    "missing": [
+      "center",
+      "skip"
+    ],
+    "keyboardNavigation": [
+      true,
+      false
+    ],
+    "layout": [
+      "auto",
+      "compact",
+      "regular"
+    ]
+  },
+  "members": {
+    "tour": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "side": "bottom",
+        "align": "center",
+        "modal": true,
+        "spotlight": true,
+        "arrow": true,
+        "autoFocus": true,
+        "closeOnEscape": true,
+        "closeOnOutsidePress": false,
+        "scrollIntoView": true,
+        "missing": "center",
+        "keyboardNavigation": true,
+        "targetTimeout": 0,
+        "sideOffset": 0,
+        "alignOffset": 0,
+        "collisionPadding": 8,
+        "arrowPadding": 12,
+        "layout": "auto"
+      },
+      "capabilities": [
+        "open",
+        "current",
+        "placement",
+        "size",
+        "appearance",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "open",
+        "loading"
+      ],
+      "parts": [
+        "root",
+        "backdrop",
+        "spotlight",
+        "surface",
+        "focus-guard",
+        "arrow",
+        "content",
+        "media",
+        "header",
+        "progress",
+        "close",
+        "title",
+        "description",
+        "body",
+        "footer",
+        "skip",
+        "prev",
+        "next"
+      ]
+    }
+  },
+  "docs": {
+    "tour": {
+      "imports": {
+        "source": "import { Tour, TourDefaultsProvider, useTour } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, portalled",
+          "required": true,
+          "purpose": "data-ui=\"tour\", fixed over the viewport, takes no pointer. data-open, data-modal, data-spotlight, data-missing, data-placement and data-size; carries the target rectangle as --slotted-tour-target-*."
+        },
+        {
+          "part": "backdrop",
+          "element": "div",
+          "required": false,
+          "purpose": "The scrim, faded in and out as dialog’s is. Takes every press on a modal step. Absent on a non-modal step without a spotlight."
+        },
+        {
+          "part": "spotlight",
+          "element": "div",
+          "required": false,
+          "purpose": "The cutout round the target; its shadow is the scrim. It travels from one target to the next. Absent on a centred step and under spotlight={false}."
+        },
+        {
+          "part": "surface",
+          "element": "div",
+          "required": true,
+          "purpose": "The layer the positioner places, with data-side and data-align; centred by the stylesheet when the step has no target."
+        },
+        {
+          "part": "focus-guard",
+          "element": "span, twice",
+          "required": false,
+          "purpose": "On a non-modal step only: Tab past either edge of the card goes to the target the reader is asked to operate."
+        },
+        {
+          "part": "arrow",
+          "element": "div",
+          "required": false,
+          "purpose": "Points at the target from the card’s edge. Absent on a centred step and under arrow={false}."
+        },
+        {
+          "part": "content",
+          "element": "div role=\"dialog\"",
+          "required": true,
+          "purpose": "TourContent. The card: named by the title, described by the description, aria-modal on a modal step. Takes focus and reads the arrow keys."
+        },
+        {
+          "part": "media",
+          "element": "div",
+          "required": false,
+          "purpose": "TourMedia. The step’s media, full bleed above the header."
+        },
+        {
+          "part": "header",
+          "element": "div",
+          "required": true,
+          "purpose": "TourHeader. The progress and the close control on one row."
+        },
+        {
+          "part": "progress",
+          "element": "p",
+          "required": false,
+          "purpose": "TourProgress. “2 of 5”, counting the steps available now. Absent in a tour of one step."
+        },
+        {
+          "part": "close",
+          "element": "button",
+          "required": false,
+          "purpose": "TourClose. Closes with the outcome close; named by messages.close."
+        },
+        {
+          "part": "title",
+          "element": "h2",
+          "required": true,
+          "purpose": "TourTitle. The step’s title and the card’s accessible name."
+        },
+        {
+          "part": "description",
+          "element": "p",
+          "required": false,
+          "purpose": "TourDescription. The step’s description, and the card’s accessible description."
+        },
+        {
+          "part": "body",
+          "element": "div",
+          "required": false,
+          "purpose": "TourBody. The step’s content: the only part of the card that scrolls."
+        },
+        {
+          "part": "footer",
+          "element": "div",
+          "required": true,
+          "purpose": "TourFooter. Skip at the start, Back and Next at the end; a narrow card lifts Skip to a line of its own."
+        },
+        {
+          "part": "skip",
+          "element": "Button, ghost",
+          "required": false,
+          "purpose": "TourSkip. Closes with the outcome skip. Absent on the last step."
+        },
+        {
+          "part": "prev",
+          "element": "Button, outline",
+          "required": false,
+          "purpose": "TourPrev. The previous available step. Absent on the first."
+        },
+        {
+          "part": "next",
+          "element": "Button, solid accent",
+          "required": false,
+          "purpose": "TourNext. The next available step, or Done on the last (data-last). data-loading while the next step prepares."
+        }
+      ],
+      "api": [
+        {
+          "name": "steps",
+          "type": "readonly TourStep[]",
+          "defaultValue": "—",
+          "appliesTo": "Tour",
+          "description": "Every step, in order"
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "Tour",
+          "description": "Whether the tour is open; controlled"
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Tour",
+          "description": "Opens on mount; uncontrolled"
+        },
+        {
+          "name": "step",
+          "type": "string | null",
+          "defaultValue": "—",
+          "appliesTo": "Tour",
+          "description": "The current step’s id; controlled"
+        },
+        {
+          "name": "defaultStep",
+          "type": "string | null",
+          "defaultValue": "null",
+          "appliesTo": "Tour",
+          "description": "The step an uncontrolled tour starts at; null is the first available"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "Tour",
+          "description": "The card’s type and measure: 16, 20 or 24rem"
+        },
+        {
+          "name": "layout",
+          "type": "'auto' | 'compact' | 'regular'",
+          "defaultValue": "auto",
+          "appliesTo": "Tour",
+          "description": "The phone composition — lateral sides turned vertical, the card as wide as the screen — below 600px of viewport under auto, always or never"
+        },
+        {
+          "name": "side",
+          "type": "'top' | 'bottom' | 'inline-start' | 'inline-end' | 'left' | 'right'",
+          "defaultValue": "bottom",
+          "appliesTo": "Tour, TourStep",
+          "description": "The side of the target the card stands on; flips when there is no room"
+        },
+        {
+          "name": "align",
+          "type": "'start' | 'center' | 'end'",
+          "defaultValue": "center",
+          "appliesTo": "Tour, TourStep",
+          "description": "Along that side"
+        },
+        {
+          "name": "sideOffset",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "Tour",
+          "description": "Extra distance from the spotlight’s edge"
+        },
+        {
+          "name": "alignOffset",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "Tour",
+          "description": "Extra distance along the side"
+        },
+        {
+          "name": "collisionPadding",
+          "type": "number",
+          "defaultValue": "8",
+          "appliesTo": "Tour",
+          "description": "How close to the viewport edge the card may come"
+        },
+        {
+          "name": "arrowPadding",
+          "type": "number",
+          "defaultValue": "12",
+          "appliesTo": "Tour",
+          "description": "How close to the card’s corner the arrow may come"
+        },
+        {
+          "name": "arrow",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Tour",
+          "description": "Draws the arrow on an anchored step"
+        },
+        {
+          "name": "modal",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Tour",
+          "description": "The page is inert and focus stays in the card; an interactive step is never modal"
+        },
+        {
+          "name": "spotlight",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Tour, TourStep",
+          "description": "Cuts the target out of the scrim"
+        },
+        {
+          "name": "autoFocus",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Tour",
+          "description": "Focuses the card when the tour opens"
+        },
+        {
+          "name": "closeOnEscape",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Tour",
+          "description": "Escape closes, with the outcome close"
+        },
+        {
+          "name": "closeOnOutsidePress",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Tour",
+          "description": "A press outside the card closes; off so a stray press keeps the reader’s place"
+        },
+        {
+          "name": "scrollIntoView",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Tour",
+          "description": "Scrolls a target that is not wholly on screen to the middle"
+        },
+        {
+          "name": "missing",
+          "type": "'center' | 'skip'",
+          "defaultValue": "center",
+          "appliesTo": "Tour",
+          "description": "A step whose target cannot be found is shown centred, or passed over"
+        },
+        {
+          "name": "keyboardNavigation",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Tour",
+          "description": "ArrowRight and ArrowLeft go on and back from the card"
+        },
+        {
+          "name": "targetTimeout",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "Tour",
+          "description": "Milliseconds to watch the page for a target that is not there yet"
+        },
+        {
+          "name": "messages",
+          "type": "PartialMessages<TourMessages>",
+          "defaultValue": "—",
+          "appliesTo": "Tour",
+          "description": "Words laid over the language in force, key by key: next, prev, done, skip, close, preparing, and progress with {position} and {total}"
+        },
+        {
+          "name": "finalFocus",
+          "type": "Element | Ref | string",
+          "defaultValue": "the element focused at open",
+          "appliesTo": "Tour",
+          "description": "Where focus goes when the tour closes"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "the whole card",
+          "appliesTo": "Tour",
+          "description": "The consumer’s own arrangement of the parts"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<TourHandle>",
+          "defaultValue": "—",
+          "appliesTo": "Tour",
+          "description": "start(id?), next(), prev(), goTo(id), close(outcome?), reposition()"
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "Unique in the tour; the value of step"
+        },
+        {
+          "name": "target",
+          "type": "Element | Ref | string | () => Element | null",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "What the step points at; absent for a centred step"
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "The card’s title and accessible name"
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "The card’s accessible description"
+        },
+        {
+          "name": "content",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "The body, which scrolls"
+        },
+        {
+          "name": "media",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "An image or a video above the header"
+        },
+        {
+          "name": "when",
+          "type": "() => boolean",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "Passes over the step while it returns false"
+        },
+        {
+          "name": "prepare",
+          "type": "(signal: AbortSignal) => void | Promise<void>",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "Awaited before the target is looked for; a rejection is a missing target"
+        },
+        {
+          "name": "interactive",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TourStep",
+          "description": "The target stays operable and the step is not modal"
+        },
+        {
+          "name": "advanceOn",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "An event on the target that goes to the next step"
+        },
+        {
+          "name": "messages",
+          "type": "PartialMessages<{ next, prev, skip, done }>",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "The step’s own words, laid over the tour’s: “Start tour”, “Got it”"
+        },
+        {
+          "name": "actions",
+          "type": "{ prev?, next?, skip?, close?: boolean }",
+          "defaultValue": "by position",
+          "appliesTo": "TourStep",
+          "description": "Shows or hides the card’s own controls for the step"
+        },
+        {
+          "name": "announcement",
+          "type": "string",
+          "defaultValue": "the title’s text",
+          "appliesTo": "TourStep",
+          "description": "Read out when the step arrives while focus is elsewhere"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactElement",
+          "defaultValue": "the part’s element",
+          "appliesTo": "every part",
+          "description": "Substitutes a part’s element; attach props.ref beside your own"
+        },
+        {
+          "name": "native props",
+          "type": "ComponentPropsWithRef<…>",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "aria-*, data-*, className, style and handlers reach the part’s element"
+        },
+        {
+          "name": "TourDefaultsProvider",
+          "type": "{ size, side, align, modal, spotlight, missing, targetTimeout, container, … }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The decisions an application takes once; a tour or a step that states any of them wins"
+        }
+      ],
+      "composition": [],
+      "events": [
+        {
+          "name": "onOpenChange",
+          "payload": "(open: boolean, request: ChangeRequest<boolean> & { outcome?: 'complete' | 'skip' | 'close' | 'unavailable' })",
+          "when": "Before the tour opens (programmatic, from start()) or closes: Done (pointer, keyboard; outcome complete), Skip (outcome skip), the close control (dismiss; close), Escape (escape; close), a press outside (outsidePress; close), the way back (back; close), or no step being available (programmatic; unavailable). cancel() keeps it open."
+        },
+        {
+          "name": "onStepChange",
+          "payload": "(step: string | null, request: ChangeRequest<string | null>)",
+          "when": "Before the current step moves: Next, Back (pointer, keyboard), the arrow keys (keyboard), advanceOn (the reason of the event on the target), goTo() and start(id) (programmatic), and a step that stood in for an unavailable one (programmatic). cancel() keeps the card where it is."
+        },
+        {
+          "name": "onClick and onKeyDown on each part",
+          "payload": "the element’s own event",
+          "when": "Run before the family’s own handler; preventDefault() in yours stops it — a Next that validates first."
+        }
+      ],
+      "accessibility": [
+        "The APG has no tour pattern. A modal step answers its Dialog (Modal) pattern: the page behind becomes inert — out of reach of the pointer, Tab and a screen reader, not only dimmed — Tab and Shift+Tab stay in the card, and aria-modal is written only while that is true.",
+        "The card is a dialog named by the step’s title and described by its description. It takes focus itself when the tour opens, so a reader hears the step before the buttons and Skip does not arrive armed; closing gives focus back to the element that had it.",
+        "Focus follows the reader rather than the tour: a step change moves focus to the new card only when it was in the old one. A reader operating an interactive target keeps their place, and the new step is read out once through the shared polite live region.",
+        "ArrowRight and ArrowLeft go on and back from the card, mirrored in a right-to-left document, and are left to a text field inside it. Escape closes from the topmost layer only.",
+        "The progress is text in the card’s reading order — “2 of 5” — and not a row of dots a screen reader would count. The spotlight, the scrim and the arrow are hidden from assistive technology; under forced colours the scrim is dropped and the spotlight is drawn as a ring in the system highlight."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-gap-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-radius",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-duration-long",
+    "--slotted-duration-short",
+    "--slotted-easing-exit",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-width",
+    "--slotted-font-family-heading",
+    "--slotted-font-family-sans",
+    "--slotted-font-size-lg",
+    "--slotted-font-size-md",
+    "--slotted-font-size-sm",
+    "--slotted-font-size-xl",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-semibold",
+    "--slotted-line-height-lg",
+    "--slotted-line-height-md",
+    "--slotted-line-height-xs",
+    "--slotted-radius-lg",
+    "--slotted-radius-md",
+    "--slotted-radius-sm",
+    "--slotted-radius-xs",
+    "--slotted-scrim",
+    "--slotted-shadow-lg",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-space-7",
+    "--slotted-surface-raised",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-tour-arrow-size",
+    "--slotted-tour-arrow-tip-radius",
+    "--slotted-tour-border-color",
+    "--slotted-tour-gap",
+    "--slotted-tour-measure",
+    "--slotted-tour-measure-compact",
+    "--slotted-tour-measure-lg",
+    "--slotted-tour-measure-sm",
+    "--slotted-tour-padding-block",
+    "--slotted-tour-padding-block-lg",
+    "--slotted-tour-padding-block-sm",
+    "--slotted-tour-padding-inline",
+    "--slotted-tour-padding-inline-lg",
+    "--slotted-tour-padding-inline-sm",
+    "--slotted-tour-radius",
+    "--slotted-tour-scrim",
+    "--slotted-tour-shadow",
+    "--slotted-tour-spotlight-padding",
+    "--slotted-tour-spotlight-radius",
+    "--slotted-tour-surface",
+    "--slotted-tour-text",
+    "--slotted-z-index-overlay"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "The five stops of a reports workspace, from a welcome card to the export button. Start it, walk it with Next and Back, and read the last request under the screen.",
+      "language": "tsx",
+      "source": "const steps: TourStep[] = [\n  { id: 'welcome', title: 'Welcome to Reports', description: 'Five stops, about a minute.' },\n  { id: 'search', target: '#search', title: 'Find any report' },\n  { id: 'filters', target: '#filters', title: 'Narrow it down' },\n  { id: 'share', target: '#share', title: 'Share with your team' },\n  { id: 'export', target: '#export', title: 'Export what you see' },\n];\n\nconst [open, setOpen] = useState(false);\n\n<Tour onOpenChange={setOpen} open={open} steps={steps} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "placement",
+      "title": "Where the card stands",
+      "note": "Each step names the side of its target; the card flips when that side has no room and slides along the edge to stay on screen, and the arrow keeps pointing at the target.",
+      "language": "tsx",
+      "source": "const steps: TourStep[] = [\n  { id: 'nav', target: '#nav', side: 'inline-end', title: 'Every workspace' },\n  { id: 'export', target: '#export', side: 'top', align: 'end', title: 'Export' },\n];\n\n<Tour side=\"bottom\" steps={steps} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "centered",
+      "title": "A step with no target",
+      "note": "The opening step points at nothing: it stands in the middle of the screen over the whole scrim, with a picture above the header and its own words, “Not now” and “Start tour”.",
+      "language": "tsx",
+      "source": "const step: TourStep = {\n  id: 'welcome',\n  title: 'Welcome to Reports',\n  description: 'Five stops, about a minute.',\n  media: <img alt=\"\" src=\"/tour/reports.png\" />,\n  messages: { next: 'Start tour', skip: 'Not now' },\n};\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "spotlight",
+      "title": "With and without the spotlight",
+      "note": "The spotlight cuts the target out of the scrim and travels to the next one. spotlight={false} on a non-modal tour is a coach mark: a card beside its control and nothing dimmed.",
+      "language": "tsx",
+      "source": "<Tour\n  modal={false}\n  spotlight={false}\n  steps={[{ id: 'views', target: '#views', title: 'Keep this view', messages: { done: 'Got it' } }]}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "modal",
+      "title": "What a modal step does to the page",
+      "note": "On a modal step the page is inert — out of reach of the pointer, the keyboard and a screen reader — Tab stays inside the card, and Escape closes. modal={false} leaves the page reachable.",
+      "language": "tsx",
+      "source": "<Tour closeOnOutsidePress modal={false} steps={steps} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "interactive",
+      "title": "A step the reader completes",
+      "note": "Press New report: the step is interactive, so the target stays operable, Next is gone, and the press on the target itself goes on — advanceOn names the event. Tab from the card reaches the target.",
+      "language": "tsx",
+      "source": "const step: TourStep = {\n  id: 'create',\n  target: '#new-report',\n  title: 'Create your first report',\n  description: 'Press New report. The tour continues once it opens.',\n  interactive: true,\n  advanceOn: 'click',\n};\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "availability",
+      "title": "Steps that apply to this reader",
+      "note": "Billing is only for owners: switch the role and the step drops out of the count — “1 of 3” becomes “1 of 4” — and Next and Back pass over it in both directions.",
+      "language": "tsx",
+      "source": "const step: TourStep = {\n  id: 'billing',\n  target: '#billing',\n  title: 'Invoices and plans',\n  when: () => user.role === 'owner',\n};\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "missing",
+      "title": "A target that is not on the page",
+      "note": "The sidebar is collapsed, so the sidebar step has nothing to point at. Under missing=\"center\" it stands centred with data-missing and says what it had to say; under \"skip\" it is passed over.",
+      "language": "tsx",
+      "source": "<Tour missing=\"skip\" steps={steps} targetTimeout={800} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "prepare",
+      "title": "Preparing the page for a step",
+      "note": "The columns step opens the column menu first: prepare runs, Next carries its loading sweep for as long as it takes, and the card only moves once the menu — the step’s target — is on the page.",
+      "language": "tsx",
+      "source": "const step: TourStep = {\n  id: 'columns',\n  target: '#column-menu',\n  title: 'Choose your columns',\n  prepare: async (signal) => {\n    setMenuOpen(true);\n    await loadColumns({ signal });\n  },\n};\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "controlled",
+      "title": "The product owns the tour",
+      "note": "open and step are the product’s: it starts at the step it saved, refuses to leave the filters step until a filter is chosen, and records the outcome — complete, skip or close — to decide whether to offer the tour again.",
+      "language": "tsx",
+      "source": "<Tour\n  onOpenChange={(next, request) => {\n    setOpen(next);\n    if (!next) saveTourOutcome(request.outcome);\n  }}\n  onStepChange={(next, request) => {\n    if (step === 'filters' && !hasFilter) return request.cancel();\n    setStep(next);\n  }}\n  open={open}\n  step={step}\n  steps={steps}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composing the card",
+      "note": "The card is the product’s own arrangement: dots from useTour() instead of the progress text, an action of its own beside Next, and the title set as a heading one level down.",
+      "language": "tsx",
+      "source": "function Dots() {\n  const { position, total } = useTour();\n  return <span aria-hidden=\"true\">{'●'.repeat(position) + '○'.repeat(total - position)}</span>;\n}\n\n<Tour steps={steps}>\n  <TourContent>\n    <TourTitle render={(props) => <h3 {...props} />} />\n    <TourDescription />\n    <TourFooter>\n      <Dots />\n      <Button onClick={openHelp}>Read the guide</Button>\n      <TourNext />\n    </TourFooter>\n  </TourContent>\n</Tour>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "labels",
+      "title": "The tour in another language",
+      "note": "The language in force says Próximo, Voltar, Concluir, Pular tour and “2 de 5” once for the application; a long German progress and title wrap inside the card rather than widening it.",
+      "language": "tsx",
+      "source": "<SlottedProvider locale=\"pt-BR\" catalogs={{ 'pt-BR': PT_BR }}>\n  <App />\n</SlottedProvider>;\n\n<Tour messages={{ progress: 'Passo {position} de {total}' }} steps={steps} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "Walking the tour from the keyboard",
+      "note": "Start with Enter: focus lands on the card. ArrowRight and ArrowLeft go on and back — mirrored right to left — Tab reaches the buttons, and Escape closes and gives focus back to Start tour.",
+      "language": "tsx",
+      "source": "const tour = useRef<TourHandle>(null);\n\n<>\n  <Button onClick={() => tour.current?.start()}>Start tour</Button>\n  <Tour ref={tour} steps={steps} />\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "compact",
+      "title": "On a phone",
+      "note": "Below 600 pixels of viewport the card stops standing beside its target: a lateral side turns vertical and the card takes the width the screen has. layout=\"compact\" forces it here; on a real phone auto takes it by itself.",
+      "language": "tsx",
+      "source": "<Tour layout=\"compact\" steps={steps} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "edges",
+      "title": "Targets in the corners, and one that fills the screen",
+      "note": "The corner steps ask for a side with no room: the card flips and slides and the arrow keeps pointing. The chart is taller than the room left around it, so its card is centred over it while the spotlight still frames it.",
+      "language": "tsx",
+      "source": "const steps: TourStep[] = [\n  { id: 'alerts', target: '#alerts', side: 'top', title: 'Notifications' },\n  { id: 'chart', target: '#chart', title: 'Revenue by region' },\n];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "layers",
+      "title": "Over a dialog a step opens",
+      "note": "The second step opens the invite dialog in its prepare and points inside it. The tour stays on top — the dialog is the layer made inert, focus stays in the card — and Escape closes the tour while the dialog stays open.",
+      "language": "tsx",
+      "source": "const step: TourStep = {\n  id: 'emails',\n  target: '#invite-emails',\n  title: 'Type their emails',\n  prepare: async () => {\n    setInviteOpen(true);\n  },\n};\n",
+      "verdict": "excerpt"
+    }
+  ]
+}