@slotted/angular 0.0.0-stage → 0.1.0-beta.0

package/docs/tour.json

@@ -0,0 +1,759 @@
+{
+  "family": "tour",
+  "ui": "tour",
+  "binding": "angular",
+  "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 { SlTour, SlTourStep, SlTourCard, provideTourDefaults } from '@slotted/angular/tour';",
+        "selector": "sl-tour, ng-template[slTourStep], ng-template[slTourCard]",
+        "exportAs": "slTour"
+      },
+      "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 slDialog’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": "[slTourContent]",
+          "required": true,
+          "purpose": "The card: role=\"dialog\" unless you wrote a role, named by the title unless you wrote aria-label, aria-modal on a modal step. Reads the arrow keys."
+        },
+        {
+          "part": "media",
+          "element": "[slTourMedia]",
+          "required": false,
+          "purpose": "The step’s media — a template, or an image URL — full bleed above the header; hidden when it has none."
+        },
+        {
+          "part": "header",
+          "element": "[slTourHeader]",
+          "required": true,
+          "purpose": "The progress and the close control on one row."
+        },
+        {
+          "part": "progress",
+          "element": "[slTourProgress]",
+          "required": false,
+          "purpose": "“2 of 5”, counting the steps available now; hidden in a tour of one step."
+        },
+        {
+          "part": "close",
+          "element": "button[slTourClose]",
+          "required": false,
+          "purpose": "Closes with the outcome close; named by messages.close."
+        },
+        {
+          "part": "title",
+          "element": "[slTourTitle]",
+          "required": true,
+          "purpose": "The step’s title and the card’s accessible name; text written inside replaces it."
+        },
+        {
+          "part": "description",
+          "element": "[slTourDescription]",
+          "required": false,
+          "purpose": "The step’s description and the card’s accessible description; hidden when it has none."
+        },
+        {
+          "part": "body",
+          "element": "[slTourBody]",
+          "required": false,
+          "purpose": "The step’s content — step.content, or an ng-template slTourStep with its id — rendered lazily. The only part that scrolls."
+        },
+        {
+          "part": "footer",
+          "element": "[slTourFooter]",
+          "required": true,
+          "purpose": "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[slButton][slTourSkip]",
+          "required": false,
+          "purpose": "Closes with the outcome skip; hidden on the last step."
+        },
+        {
+          "part": "prev",
+          "element": "button[slButton][slTourPrev]",
+          "required": false,
+          "purpose": "The previous available step; hidden on the first."
+        },
+        {
+          "part": "next",
+          "element": "button[slButton][slTourNext]",
+          "required": false,
+          "purpose": "The next available step, or Done on the last (data-last); carries [loading] while the next step prepares."
+        }
+      ],
+      "api": [
+        {
+          "name": "steps",
+          "type": "readonly TourStep[]",
+          "defaultValue": "—",
+          "appliesTo": "sl-tour",
+          "description": "Every step, in order"
+        },
+        {
+          "name": "open",
+          "type": "model<boolean>",
+          "defaultValue": "false",
+          "appliesTo": "sl-tour",
+          "description": "Whether the tour is open; two-way"
+        },
+        {
+          "name": "step",
+          "type": "model<string | null>",
+          "defaultValue": "null",
+          "appliesTo": "sl-tour",
+          "description": "The current step’s id; two-way. null is the first available step"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "sl-tour",
+          "description": "The card’s type and measure: 16, 20 or 24rem"
+        },
+        {
+          "name": "layout",
+          "type": "'auto' | 'compact' | 'regular'",
+          "defaultValue": "auto",
+          "appliesTo": "sl-tour, provideTourDefaults",
+          "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": "sl-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": "sl-tour, TourStep",
+          "description": "Along that side"
+        },
+        {
+          "name": "sideOffset",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "sl-tour",
+          "description": "Extra distance from the spotlight’s edge"
+        },
+        {
+          "name": "alignOffset",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "sl-tour",
+          "description": "Extra distance along the side"
+        },
+        {
+          "name": "collisionPadding",
+          "type": "number",
+          "defaultValue": "8",
+          "appliesTo": "sl-tour",
+          "description": "How close to the viewport edge the card may come"
+        },
+        {
+          "name": "arrowPadding",
+          "type": "number",
+          "defaultValue": "12",
+          "appliesTo": "sl-tour",
+          "description": "How close to the card’s corner the arrow may come"
+        },
+        {
+          "name": "arrow",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-tour",
+          "description": "Draws the arrow on an anchored step"
+        },
+        {
+          "name": "modal",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-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": "sl-tour, TourStep",
+          "description": "Cuts the target out of the scrim"
+        },
+        {
+          "name": "autoFocus",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-tour",
+          "description": "Focuses the card when the tour opens"
+        },
+        {
+          "name": "closeOnEscape",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-tour",
+          "description": "Escape closes, with the outcome close"
+        },
+        {
+          "name": "closeOnOutsidePress",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-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": "sl-tour",
+          "description": "Scrolls a target that is not wholly on screen to the middle"
+        },
+        {
+          "name": "missing",
+          "type": "'center' | 'skip'",
+          "defaultValue": "center",
+          "appliesTo": "sl-tour",
+          "description": "A step whose target cannot be found is shown centred, or passed over"
+        },
+        {
+          "name": "keyboardNavigation",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-tour",
+          "description": "ArrowRight and ArrowLeft go on and back from the card"
+        },
+        {
+          "name": "targetTimeout",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "sl-tour",
+          "description": "Milliseconds to watch the page for a target that is not there yet"
+        },
+        {
+          "name": "messages",
+          "type": "PartialMessages<TourMessages>",
+          "defaultValue": "—",
+          "appliesTo": "sl-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 | string",
+          "defaultValue": "the element focused at open",
+          "appliesTo": "sl-tour",
+          "description": "Where focus goes when the tour closes"
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "Unique in the tour; the value of step"
+        },
+        {
+          "name": "target",
+          "type": "Element | string | { current } | () => Element | null",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "What the step points at; absent for a centred step"
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "The card’s title and accessible name"
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "The card’s accessible description"
+        },
+        {
+          "name": "content",
+          "type": "TemplateRef | string",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "The body; an ng-template slTourStep=\"id\" in the tour does the same"
+        },
+        {
+          "name": "media",
+          "type": "TemplateRef | string",
+          "defaultValue": "—",
+          "appliesTo": "TourStep",
+          "description": "A picture above the header: a template, or an image URL"
+        },
+        {
+          "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",
+          "appliesTo": "TourStep",
+          "description": "Read out when the step arrives while focus is elsewhere"
+        },
+        {
+          "name": "slTourStep",
+          "type": "ng-template, with slTourStepSlot: body | media",
+          "defaultValue": "body",
+          "appliesTo": "sl-tour content",
+          "description": "The lazy body or picture of the step with that id"
+        },
+        {
+          "name": "slTourCard",
+          "type": "ng-template",
+          "defaultValue": "the whole card",
+          "appliesTo": "sl-tour content",
+          "description": "Your own arrangement of the parts"
+        },
+        {
+          "name": "slTour",
+          "type": "exportAs",
+          "defaultValue": "—",
+          "appliesTo": "sl-tour",
+          "description": "start(id?), next(), prev(), goTo(id), close(outcome?), reposition(); position(), total(), t() and the rest as signals"
+        },
+        {
+          "name": "provideTourDefaults",
+          "type": "(defaults) => Provider",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The decisions an application takes once; a tour or a step that states any of them wins"
+        }
+      ],
+      "composition": [],
+      "events": [
+        {
+          "name": "openChangeRequest",
+          "payload": "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": "stepChangeRequest",
+          "payload": "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). cancel() keeps the card where it is."
+        },
+        {
+          "name": "openChange / stepChange",
+          "payload": "boolean / string | null",
+          "when": "The two-way halves of [(open)] and [(step)], after a request was not cancelled."
+        },
+        {
+          "name": "(click) on an action",
+          "payload": "MouseEvent",
+          "when": "Your handler runs on the same button; preventDefault() in it stops the family’s — 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": "html",
+      "source": "<button slButton (click)=\"open.set(true)\">Start tour</button>\n<sl-tour [steps]=\"steps\" [(open)]=\"open\" />\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": "ts",
+      "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",
+      "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": "html",
+      "source": "<sl-tour [steps]=\"steps\" [(open)]=\"open\">\n  <ng-template slTourStep=\"welcome\" slTourStepSlot=\"media\">\n    <img alt=\"\" src=\"/tour/reports.png\" />\n  </ng-template>\n</sl-tour>\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": "html",
+      "source": "<sl-tour [steps]=\"tip\" [(open)]=\"tipOpen\" [modal]=\"false\" [spotlight]=\"false\" size=\"sm\" />\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": "html",
+      "source": "<sl-tour [steps]=\"steps\" [(open)]=\"open\" [modal]=\"false\" closeOnOutsidePress />\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": "ts",
+      "source": "const step: TourStep = {\n  id: 'create',\n  target: '#new-report',\n  title: 'Create your first report',\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": "ts",
+      "source": "const step: TourStep = {\n  id: 'billing',\n  target: '#billing',\n  title: 'Invoices and plans',\n  when: () => this.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": "html",
+      "source": "<sl-tour [steps]=\"steps\" [(open)]=\"open\" missing=\"skip\" [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": "ts",
+      "source": "const step: TourStep = {\n  id: 'columns',\n  target: '#column-menu',\n  title: 'Choose your columns',\n  prepare: async (signal) => {\n    this.menuOpen.set(true);\n    await this.columns.load({ 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": "html",
+      "source": "<sl-tour\n  [steps]=\"steps\"\n  [(open)]=\"open\"\n  [(step)]=\"step\"\n  (stepChangeRequest)=\"guard($event)\"\n  (openChangeRequest)=\"$event.value || saveOutcome($event.outcome)\"\n/>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composing the card",
+      "note": "The card is the product’s own arrangement: dots from the slTour instance instead of the progress text, an action of its own beside Next, and the title set as an h3.",
+      "language": "html",
+      "source": "<sl-tour #tour=\"slTour\" [steps]=\"steps\" [(open)]=\"open\">\n  <ng-template slTourCard>\n    <div slTourContent>\n      <h3 slTourTitle></h3>\n      <p slTourDescription></p>\n      <div slTourFooter>\n        <span aria-hidden=\"true\">{{ tour.position() }} / {{ tour.total() }}</span>\n        <button slButton size=\"sm\" variant=\"ghost\" (click)=\"openGuide()\">Read the guide</button>\n        <button slButton slTourNext size=\"sm\" tone=\"accent\">\n          {{ tour.t(tour.last() ? 'done' : 'next') }}\n        </button>\n      </div>\n    </div>\n  </ng-template>\n</sl-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": "ts",
+      "source": "providers: [provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } })];\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": "html",
+      "source": "<button slButton (click)=\"tour.start()\">Start tour</button>\n<sl-tour #tour=\"slTour\" [steps]=\"steps\" />\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": "html",
+      "source": "<sl-tour [steps]=\"steps\" [(open)]=\"open\" layout=\"compact\" />\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": "ts",
+      "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": "ts",
+      "source": "const step: TourStep = {\n  id: 'emails',\n  target: '#invite-emails',\n  title: 'Type their emails',\n  prepare: async () => {\n    this.inviteOpen.set(true);\n  },\n};\n",
+      "verdict": "excerpt"
+    }
+  ]
+}