Tour component contract¶
Contract at a glance¶
| Area | Contract |
|---|---|
| Public contract | Unchanged by this record. |
| Behavior | Without a backdrop, a press on the page or on the target leaves the tour running. With a backdrop, a press outside the callout, the target included, ends it with 'backdrop'. |
| End-user impact | A person can use the control a step introduces, or the rest of the page, while a plain tour stays open; a dimmed tour ends on a press outside it. |
| Builder impact | An app that needs a press on the page or the target to end the tour passes hasBackdrop, which also dims the page and reports 'backdrop' (DEC-1). |
| Compatibility/readiness | Lab. |
| Review checks | Reject a press on the page or the target that ends a tour without a backdrop, or a press outside the callout under a backdrop that leaves the tour running. |
| Governing rules | None recorded. |
This table is a review projection; the body below is authoritative.
Intent¶
Tour is the lab's guided walkthrough: a sequence of steps, each a callout
beside a highlighted target. This record states how a press outside the
step's callout affects the tour, and whether keyboard focus can leave the
callout. Consumer usage lives in Tour.doc.mjs.
Compatibility and migration¶
- Released default preserved:
nofor a tour without a backdrop: a press on the page or on the target leaves it running (FR1, DEC-1). - Compatibility class: behavioral, Lab.
- Controlled/uncontrolled behavior: unchanged;
isActiveandonDismissare the app's. - Migration decision: DEC-1. An app that needs an outside press to end a tour passes
hasBackdrop, which also dims the page and reports'backdrop'instead of'close'.
Ownership boundary¶
Owns
- Whether a press outside the step's callout ends the tour.
- Whether keyboard focus can leave the step's callout without a backdrop (AR1).
Does not own / non-goals
- The callout's placement, where focus goes when a step starts or the tour ends, and the step controls. Not recorded here.
- Escape, which ends the tour through the shared layer dismissal stack (
family:overlay-dismissal).
Public concepts¶
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Backdrop | on, off | Whether the step dims the page and ends the tour on a press outside the callout | Every step | off | component:Tour |
experimental | Not applicable |
Behavioral and layout contract¶
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Without a backdrop, a press on the page or on the step's target MUST NOT end the tour. With a backdrop, a press anywhere outside the callout, the target included, MUST end the tour with 'backdrop'. This holds for every pointer. |
DEC-1 |
Accessibility contract¶
- AR1 — the page stays usable. Without a backdrop, keyboard focus can leave the callout for the page and the target, and a press there does not end the tour (FR1).
Design relationships¶
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Backdrop | None recorded | Not applicable | supporting | FR1 |
The component implements design requirements without copying their rationale.
Family and system relationships¶
family:overlay-dismissalowns Escape through the shared dismissal stack. The step adopts it, and this record owns only the step's outside dismissal (FR1) and whether focus can leave the callout (AR1).
Verification map¶
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1 | "keeps the tour running when the target is pressed"; "keeps the tour running when the page is pressed"; "dismisses with \"backdrop\" when the backdrop is clicked"; "pressing the introduced control keeps the tour, and Escape ends it"; "a press on the dimmed page ends a backdrop tour" | No backdrop and backdrop; a card target | A press that ends a plain tour, or leaves a dimmed tour running, fails it | None |
| AR1 | "lets Tab move past the step into the page"; "Tab leaves the callout for the page" | No backdrop | Focus kept in the callout fails it | None |
Decision log¶
DEC-1 — A press does not end a tour without a backdrop¶
Decider: cixzhang, 2026-11-04
Basis: Lab-only behavior, under the owner's standing Lab grant: "Anything lab only gets an ok". Promoted to current under the standing Lab grant.
Decision: A step is a non-modal layer with no light dismiss. Without a backdrop, a press on the page or on the target leaves the tour running, on every pointer. With a backdrop, the dimmed overlay catches every press, the target's included, and ends the tour with 'backdrop'.
Rejected: ending a tour without a backdrop on any press, which ends it when a person uses the control the step introduces.
Open questions¶
None.
Content boundary¶
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx