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

package/docs/tour.md

@@ -0,0 +1,337 @@
+<!-- index: ./index.md -->
+# tour
+
+`data-ui="tour"` · Guided steps anchored to elements.
+
+## Import
+
+```ts
+import { SlTour, SlTourStep, SlTourCard, provideTourDefaults } from '@slotted/angular/tour';
+```
+
+Selector: `sl-tour, ng-template[slTourStep], ng-template[slTourCard]` · exportAs: `slTour`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<button slButton (click)="open.set(true)">Start tour</button>
+<sl-tour [steps]="steps" [(open)]="open" />
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, portalled | yes |
+| `backdrop` | div | no |
+| `spotlight` | div | no |
+| `surface` | div | yes |
+| `focus-guard` | span, twice | no |
+| `arrow` | div | no |
+| `content` | [slTourContent] | yes |
+| `media` | [slTourMedia] | no |
+| `header` | [slTourHeader] | yes |
+| `progress` | [slTourProgress] | no |
+| `close` | button[slTourClose] | no |
+| `title` | [slTourTitle] | yes |
+| `description` | [slTourDescription] | no |
+| `body` | [slTourBody] | no |
+| `footer` | [slTourFooter] | yes |
+| `skip` | button[slButton][slTourSkip] | no |
+| `prev` | button[slButton][slTourPrev] | no |
+| `next` | button[slButton][slTourNext] | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `steps` | `readonly TourStep[]` | — | sl-tour | Every step, in order |
+| `open` | `model<boolean>` | false | sl-tour | Whether the tour is open; two-way |
+| `step` | `model<string \| null>` | null | sl-tour | The current step’s id; two-way. null is the first available step |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | sl-tour | The card’s type and measure: 16, 20 or 24rem |
+| `layout` | `'auto' \| 'compact' \| 'regular'` | auto | sl-tour, provideTourDefaults | The phone composition — lateral sides turned vertical, the card as wide as the screen — below 600px of viewport under auto, always or never |
+| `side` | `'top' \| 'bottom' \| 'inline-start' \| 'inline-end' \| 'left' \| 'right'` | bottom | sl-tour, TourStep | The side of the target the card stands on; flips when there is no room |
+| `align` | `'start' \| 'center' \| 'end'` | center | sl-tour, TourStep | Along that side |
+| `sideOffset` | `number` | 0 | sl-tour | Extra distance from the spotlight’s edge |
+| `alignOffset` | `number` | 0 | sl-tour | Extra distance along the side |
+| `collisionPadding` | `number` | 8 | sl-tour | How close to the viewport edge the card may come |
+| `arrowPadding` | `number` | 12 | sl-tour | How close to the card’s corner the arrow may come |
+| `arrow` | `boolean` | true | sl-tour | Draws the arrow on an anchored step |
+| `modal` | `boolean` | true | sl-tour | The page is inert and focus stays in the card; an interactive step is never modal |
+| `spotlight` | `boolean` | true | sl-tour, TourStep | Cuts the target out of the scrim |
+| `autoFocus` | `boolean` | true | sl-tour | Focuses the card when the tour opens |
+| `closeOnEscape` | `boolean` | true | sl-tour | Escape closes, with the outcome close |
+| `closeOnOutsidePress` | `boolean` | false | sl-tour | A press outside the card closes; off so a stray press keeps the reader’s place |
+| `scrollIntoView` | `boolean` | true | sl-tour | Scrolls a target that is not wholly on screen to the middle |
+| `missing` | `'center' \| 'skip'` | center | sl-tour | A step whose target cannot be found is shown centred, or passed over |
+| `keyboardNavigation` | `boolean` | true | sl-tour | ArrowRight and ArrowLeft go on and back from the card |
+| `targetTimeout` | `number` | 0 | sl-tour | Milliseconds to watch the page for a target that is not there yet |
+| `messages` | `PartialMessages<TourMessages>` | — | sl-tour | Words laid over the language in force, key by key: next, prev, done, skip, close, preparing, and progress with {position} and {total} |
+| `finalFocus` | `Element \| string` | the element focused at open | sl-tour | Where focus goes when the tour closes |
+| `id` | `string` | — | TourStep | Unique in the tour; the value of step |
+| `target` | `Element \| string \| { current } \| () => Element \| null` | — | TourStep | What the step points at; absent for a centred step |
+| `title` | `string` | — | TourStep | The card’s title and accessible name |
+| `description` | `string` | — | TourStep | The card’s accessible description |
+| `content` | `TemplateRef \| string` | — | TourStep | The body; an ng-template slTourStep="id" in the tour does the same |
+| `media` | `TemplateRef \| string` | — | TourStep | A picture above the header: a template, or an image URL |
+| `when` | `() => boolean` | — | TourStep | Passes over the step while it returns false |
+| `prepare` | `(signal: AbortSignal) => void \| Promise<void>` | — | TourStep | Awaited before the target is looked for; a rejection is a missing target |
+| `interactive` | `boolean` | false | TourStep | The target stays operable and the step is not modal |
+| `advanceOn` | `string` | — | TourStep | An event on the target that goes to the next step |
+| `messages` | `PartialMessages<{ next, prev, skip, done }>` | — | TourStep | The step’s own words, laid over the tour’s: “Start tour”, “Got it” |
+| `actions` | `{ prev?, next?, skip?, close?: boolean }` | by position | TourStep | Shows or hides the card’s own controls for the step |
+| `announcement` | `string` | the title | TourStep | Read out when the step arrives while focus is elsewhere |
+| `slTourStep` | `ng-template, with slTourStepSlot: body \| media` | body | sl-tour content | The lazy body or picture of the step with that id |
+| `slTourCard` | `ng-template` | the whole card | sl-tour content | Your own arrangement of the parts |
+| `slTour` | `exportAs` | — | sl-tour | start(id?), next(), prev(), goTo(id), close(outcome?), reposition(); position(), total(), t() and the rest as signals |
+| `provideTourDefaults` | `(defaults) => Provider` | — | an injector | The decisions an application takes once; a tour or a step that states any of them wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `openChangeRequest` | `ChangeRequest<boolean> & { outcome?: 'complete' \| 'skip' \| 'close' \| 'unavailable' }` | 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. |
+| `stepChangeRequest` | `ChangeRequest<string \| null>` | 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. |
+| `openChange / stepChange` | `boolean / string \| null` | The two-way halves of [(open)] and [(step)], after a request was not cancelled. |
+| `(click) on an action` | `MouseEvent` | Your handler runs on the same button; preventDefault() in it stops the family’s — a Next that validates first. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `side` | `top`, `bottom`, `inline-start`, `inline-end`, `left`, `right` | `bottom` |
+| `align` | `start`, `center`, `end` | `center` |
+| `modal` | `true`, `false` | `true` |
+| `spotlight` | `true`, `false` | `true` |
+| `arrow` | `true`, `false` | `true` |
+| `autoFocus` | `true`, `false` | `true` |
+| `closeOnEscape` | `true`, `false` | `true` |
+| `closeOnOutsidePress` | `true`, `false` | `false` |
+| `scrollIntoView` | `true`, `false` | `true` |
+| `missing` | `center`, `skip` | `center` |
+| `keyboardNavigation` | `true`, `false` | `true` |
+| `layout` | `auto`, `compact`, `regular` | `auto` |
+
+## Rules
+
+- 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
+
+### Where the card stands
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+const steps: TourStep[] = [
+  { id: 'nav', target: '#nav', side: 'inline-end', title: 'Every workspace' },
+  { id: 'export', target: '#export', side: 'top', align: 'end', title: 'Export' },
+];
+```
+
+### A step with no target
+
+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”.
+
+Excerpt — not a complete module
+
+```html
+<sl-tour [steps]="steps" [(open)]="open">
+  <ng-template slTourStep="welcome" slTourStepSlot="media">
+    <img alt="" src="/tour/reports.png" />
+  </ng-template>
+</sl-tour>
+```
+
+### With and without the spotlight
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<sl-tour [steps]="tip" [(open)]="tipOpen" [modal]="false" [spotlight]="false" size="sm" />
+```
+
+### What a modal step does to the page
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<sl-tour [steps]="steps" [(open)]="open" [modal]="false" closeOnOutsidePress />
+```
+
+### A step the reader completes
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+const step: TourStep = {
+  id: 'create',
+  target: '#new-report',
+  title: 'Create your first report',
+  interactive: true,
+  advanceOn: 'click',
+};
+```
+
+### Steps that apply to this reader
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+const step: TourStep = {
+  id: 'billing',
+  target: '#billing',
+  title: 'Invoices and plans',
+  when: () => this.role() === 'owner',
+};
+```
+
+### A target that is not on the page
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<sl-tour [steps]="steps" [(open)]="open" missing="skip" [targetTimeout]="800" />
+```
+
+### Preparing the page for a step
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+const step: TourStep = {
+  id: 'columns',
+  target: '#column-menu',
+  title: 'Choose your columns',
+  prepare: async (signal) => {
+    this.menuOpen.set(true);
+    await this.columns.load({ signal });
+  },
+};
+```
+
+### The product owns the tour
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<sl-tour
+  [steps]="steps"
+  [(open)]="open"
+  [(step)]="step"
+  (stepChangeRequest)="guard($event)"
+  (openChangeRequest)="$event.value || saveOutcome($event.outcome)"
+/>
+```
+
+### Composing the card
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<sl-tour #tour="slTour" [steps]="steps" [(open)]="open">
+  <ng-template slTourCard>
+    <div slTourContent>
+      <h3 slTourTitle></h3>
+      <p slTourDescription></p>
+      <div slTourFooter>
+        <span aria-hidden="true">{{ tour.position() }} / {{ tour.total() }}</span>
+        <button slButton size="sm" variant="ghost" (click)="openGuide()">Read the guide</button>
+        <button slButton slTourNext size="sm" tone="accent">
+          {{ tour.t(tour.last() ? 'done' : 'next') }}
+        </button>
+      </div>
+    </div>
+  </ng-template>
+</sl-tour>
+```
+
+### The tour in another language
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+providers: [provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } })];
+```
+
+### Walking the tour from the keyboard
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<button slButton (click)="tour.start()">Start tour</button>
+<sl-tour #tour="slTour" [steps]="steps" />
+```
+
+### On a phone
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<sl-tour [steps]="steps" [(open)]="open" layout="compact" />
+```
+
+### Targets in the corners, and one that fills the screen
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+const steps: TourStep[] = [
+  { id: 'alerts', target: '#alerts', side: 'top', title: 'Notifications' },
+  { id: 'chart', target: '#chart', title: 'Revenue by region' },
+];
+```
+
+### Over a dialog a step opens
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+const step: TourStep = {
+  id: 'emails',
+  target: '#invite-emails',
+  title: 'Type their emails',
+  prepare: async () => {
+    this.inviteOpen.set(true);
+  },
+};
+```