An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-090): touch presentations keep their native exit (#8536)
Kenton Quatmanc4a9ae08dc02
diff --git a/docs/specs/AST-090-exit-motion/spec.md b/docs/specs/AST-090-exit-motion/spec.mdindex 2b2beab406..dcf138257c 100644--- a/docs/specs/AST-090-exit-motion/spec.md+++ b/docs/specs/AST-090-exit-motion/spec.md@@ -39,13 +39,21 @@ review_triggers: [motion, tokens, layering, behavior, accessibility]## IntentA surface that animates in can animate out, so a person sees where it went and-what it uncovered. Whether a kind of surface plays its exit is a theme decision:-with no theme setting, every surface closes at once, as a surface without an-exit does.+what it uncovered. In a pointer presentation, whether a kind of surface plays+its exit is a theme decision: with no theme setting, the surface closes at once,+as a surface without an exit does. A touch presentation plays the exit of its+native counterpart instead (`spec:AST-094` FR7), and the switches here do not+reach it.++A **touch presentation** is a presentation under a coarse primary pointer,+after hydration, as `spec:AST-094` FR13 defines it. Every other presentation,+including a server render and the hydrating render, is a **pointer+presentation**.This record owns the exit vocabulary, the switch that turns exits on for each-kind of surface, how a surface behaves while it leaves, and the browsers in-which layer exits play. Two kinds of surface gain an exit:+kind of surface in a pointer presentation, how a pointer-presented surface+behaves while it leaves, and the browsers in which its layer exits play. Two+kinds of surface gain an exit:- A **dialog surface** is a `Dialog`, including the dialogs that `AlertDialog`,`CommandPalette`, `useImperativeDialog`, and `useImperativeAlertDialog`@@ -63,11 +71,14 @@ components read through two shared primitives is a system fact.## Non-goals+- Exits of touch presentations, which each component's record gives under+ `spec:AST-094` FR7 and FR8 (FR14). The exit tokens here do not reach touch+ motion, whose roles stay internal (`spec:AST-094` FR4, DEC-11).- Surfaces that already animate out (`Drawer`, `BottomSheet`, `MobileNav`,`Toast`, and the `TopNavMegaMenu` panel) keep their exits, durations, and- curves. `BottomSheet`'s close reads `--ease-exit` at the curve it uses- (FR12); moving the others onto the exit vocabulary is a visual change for a- separate decision.+ curves. `BottomSheet`'s close in a pointer presentation reads `--ease-exit`+ at the curve it uses (FR12); moving the others onto the exit vocabulary is a+ visual change for a separate decision.- Layers with no entrance (`Typeahead` suggestions, `MultiSelector`,`Tokenizer`, the date and time pickers, the `TabList` overflow menu, the`TopNav` and `SideNav` menus, and Chat trigger menus) gain no exit here.@@ -86,6 +97,9 @@ components read through two shared primitives is a system fact.## Requirements+FR1–FR13 govern dialog and layer surfaces in a pointer presentation. FR14+governs them in a touch presentation.+- **FR1 — Exits are off by default.** `--duration-exit-dialog` and`--duration-exit-layer` default to `0ms`. A surface whose kind's exitduration is zero closes at once: it is hidden in the update that closes it,@@ -127,8 +141,9 @@ components read through two shared primitives is a system fact.reports the end of its exit. That includes a page that disables animations andtransitions, and a surface that opens and closes in the same update.- **FR10 — Reduced motion closes at once.** Under- `prefers-reduced-motion: reduce`, every dialog and layer surface closes at- once, whatever its kind's exit duration (`design:motion` DR5).+ `prefers-reduced-motion: reduce`, a dialog or layer surface in a pointer+ presentation closes at once, whatever its kind's exit duration+ (`design:reduced-motion` DR3, DR4).- **FR11 — Content stays while it leaves.** A surface keeps rendering thecontent it showed when its close began until it is hidden. A component doesnot unmount or reset its own content before its exit ends: a hover card's@@ -136,7 +151,8 @@ components read through two shared primitives is a system fact.query keep their state until the surface is hidden.- **FR12 — The exit vocabulary.** `--ease-exit` defaults to`cubic-bezier(0.3, 0, 0.6, 0.6)`, a curve that moves off slowly and leaves- fast. Dialog and layer exits use it, and so does `BottomSheet`'s close.+ fast. Dialog and layer exits use it, and so does `BottomSheet`'s close in a+ pointer presentation.`--duration-exit` defaults to `var(--duration-fast)` and is the standarddismissal duration. A theme turns a kind on by setting its exit duration to`var(--duration-exit)` or to any other duration.@@ -146,11 +162,18 @@ components read through two shared primitives is a system fact.above it for the whole exit (`spec:AST-003` FR16). When it is hidden, theymove to the latest remaining outlet with their entries and timers intact(`spec:AST-003` FR18, FR19).+- **FR14 — Touch presentations keep their native exit.** A dialog or layer+ surface in a touch presentation plays the exit its component's record gives+ it under `spec:AST-094` FR7 and FR8. The exit switches, `--ease-exit`, and+ `--duration-exit` do not change that exit: a theme that leaves a kind off+ does not remove it, and a theme that turns a kind on does not replace it.### Platform support- Supported feature and engine floor: the tiers in the `browser-support`consumer doc.+- This section covers pointer presentations; a touch exit follows+ `spec:AST-094`.- Dialog exits play in every Tier 1 and Tier 2 browser.- Layer exits play only in browsers that can keep a closing layer in the toplayer until its exit ends, which takes a transition of `overlay` with@@ -177,6 +200,13 @@ components read through two shared primitives is a system fact.(FR1), and a leaving passive dependent such as `Tooltip` still never shieldsan owner (FR4, DEC-1). A leaving dialog is still the current native modal, soit keeps its outlet and toasts stay operable above it (FR16, FR18).+- `spec:AST-094`: no claim changes. A touch presentation keeps the exit FR7 and+ FR8 give it (FR14), and its motion roles stay internal (FR4, DEC-11). The exit+ tokens here time pointer presentations, which its non-goals leave to the+ theme's duration and easing tokens.+- `design:reduced-motion`: no claim changes. Under reduced motion a pointer+ presentation's exit completes at once (DR3, FR10), and a touch presentation's+ exit cross-fades through `spec:AST-094` FR8 (DR2).- `design:motion` (draft): exits apply DR1, DR2, and DR5. This record holds theexit tokens and behavior that its content boundary leaves to other records.- `component:Dialog`: its `visibility` concept (open, closed) gains a leaving@@ -186,30 +216,33 @@ components read through two shared primitives is a system fact.states when the return happens.- `component:Popover`: AR4 keeps its focus-return claim; FR6 states when thereturn happens for a layer.-- `component:BottomSheet`: its closing curve reads `--ease-exit`.-- Consumer docs: `motion` describes both curves, that exits are off by default,- how a theme turns each kind on, and that callers keep content rendered while a- surface closes. The token tables and the theme template list the new tokens,- and each member component's docs describe its exit.+- `component:BottomSheet`: its closing curve in a pointer presentation reads+ `--ease-exit`.+- Consumer docs: `motion` describes both curves, that exits are off by default+ in a pointer presentation, how a theme turns each kind on, that touch+ presentations keep their native exits, and that callers keep content rendered+ while a surface closes. The token tables and the theme template list the new+ tokens, and each member component's docs describe its exit.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |-| FR1 | Component unit suites run unchanged with default tokens | Every dialog and layer member, opened and closed | A surface stays rendered after its close with default tokens |-| FR2 | Real-browser test under a theme that sets one kind | Dialogs on with layers off; layers on with dialogs off; a nested `Theme` | The unset kind animates, or the set kind closes at once |-| FR3 | Real-browser frame sampling during an exit | A dialog with and without an opener, a fullscreen dialog, a layer in each placement, right-to-left | The surface leaves its entrance path, or keeps the entrance curve |-| FR4 | Real-browser test | A press and an Enter key on a control inside a leaving surface | The control activates |-| FR5 | Dismissal invariant tests | Escape during a leaving Dialog or Popover with an owner beneath; Escape during a leaving Tooltip over a Dialog | The owner beneath a leaving owner closes, or a leaving Tooltip absorbs the press |-| FR6 | Unit and real-browser focus tests | Dialog and layer closes, by keyboard and by pointer | Dialog focus returns before the dialog is hidden or lands on the body; layer focus waits for exit |-| FR7 | Unit tests | Controlled and uncontrolled closes | A callback or `isOpen` waits for the exit |-| FR8 | Unit and real-browser tests | Reopen during an exit, unmount during an exit, `Activity` hidden during an exit | The surface disappears and reappears, or stays after unmount |-| FR9 | Unit test with a suppressed end event; real-browser test with animations and transitions disabled page-wide | Open and close in one update; page-wide `transition: none`; no end event | The surface is present more than 100ms after its exit duration |-| FR10 | Real-browser test with reduced motion emulated | Each kind turned on | An exit plays |-| FR11 | Unit tests | Hover card content, an open sub-menu path, a selector query | Content unmounts or resets before the surface is hidden |-| FR12 | Token default tests, theme template inventory test, token documentation check | Defaults; the `BottomSheet` closing curve | A default drifts, or `BottomSheet` restates the curve |-| FR13 | Real-browser test | A toast action pressed, and a toast dismissed, during a dialog exit; the same toast after the dialog is hidden | The toast ignores input or fades with the dialog during the exit, or loses its entries or timers when the dialog is hidden |-| Platform | Real-browser tests | A browser that plays layer exits and one that does not | A layer paints outside the top layer, or a browser without support delays the close |+| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Component unit suites run unchanged with default tokens | Every dialog and layer member in a pointer presentation, opened and closed | A surface stays rendered after its close with default tokens |+| FR2 | Real-browser test under a theme that sets one kind, fine primary pointer | Dialogs on with layers off; layers on with dialogs off; a nested `Theme` | The unset kind animates, or the set kind closes at once |+| FR3 | Real-browser frame sampling during an exit | A dialog with and without an opener, a fullscreen dialog, a layer in each placement, right-to-left | The surface leaves its entrance path, or keeps the entrance curve |+| FR4 | Real-browser test | A press and an Enter key on a control inside a leaving surface | The control activates |+| FR5 | Dismissal invariant tests | Escape during a leaving Dialog or Popover with an owner beneath; Escape during a leaving Tooltip over a Dialog | The owner beneath a leaving owner closes, or a leaving Tooltip absorbs the press |+| FR6 | Unit and real-browser focus tests | Dialog and layer closes, by keyboard and by pointer | Dialog focus returns before the dialog is hidden or lands on the body; layer focus waits for exit |+| FR7 | Unit tests | Controlled and uncontrolled closes | A callback or `isOpen` waits for the exit |+| FR8 | Unit and real-browser tests | Reopen during an exit, unmount during an exit, `Activity` hidden during an exit | The surface disappears and reappears, or stays after unmount |+| FR9 | Unit test with a suppressed end event; real-browser test with animations and transitions disabled page-wide | Open and close in one update; page-wide `transition: none`; no end event | The surface is present more than 100ms after its exit duration |+| FR10 | Real-browser test with reduced motion emulated, fine primary pointer | Each kind turned on | An exit plays |+| FR11 | Unit tests | Hover card content, an open sub-menu path, a selector query | Content unmounts or resets before the surface is hidden |+| FR12 | Token default tests, theme template inventory test, token documentation check | Defaults; the `BottomSheet` closing curve | A default drifts, or `BottomSheet` restates the curve |+| FR13 | Real-browser test | A toast action pressed, and a toast dismissed, during a dialog exit; the same toast after the dialog is hidden | The toast ignores input or fades with the dialog during the exit, or loses its entries or timers when the dialog is hidden |+| FR14 | Real-browser test with a coarse primary pointer, after hydration | A Dialog, a Popover, and a menu opened and closed by a finger, with each kind switched off and on; the same surfaces under reduced motion | A switch changes the touch exit, or the surface closes without the exit `spec:AST-094` FR7 and FR8 give it |+| Platform | Real-browser tests | A browser that plays layer exits and one that does not | A layer paints outside the top layer, or a browser without support delays the close |## Decision log@@ -218,12 +251,12 @@ components read through two shared primitives is a system fact.**Reference:** `spec:AST-090/DEC-1`**Decider:** pending owner review-Turning exits on changes how every dialog and layer closes in every product at-once, so the capability ships switched off and a theme opts in: the same place-that tunes motion through its motion scale. The switches are tokens because an-exit's timing is an implementation value, not a per-call concept-(`spec:AST-002` FR3), and because a prop cannot reach the layers that other-components compose, such as every `tooltip` prop.+Turning exits on changes how every pointer-presented dialog and layer closes in+every product at once, so the capability ships switched off and a theme opts+in: the same place that tunes motion through its motion scale. The switches are+tokens because an exit's timing is an implementation value, not a per-call+concept (`spec:AST-002` FR3), and because a prop cannot reach the layers that+other components compose, such as every `tooltip` prop.Rejected: an exit prop on each component, which restates timing at every call site and misses composed layers; exits on by default, which changes every overlay in one release.@@ -264,12 +297,26 @@ in the top layer, the layer closes at once, which is also the default.Rejected: replacing native light dismissal with Core-owned outside-press handling so every browser plays layer exits.+### DEC-5 — Touch presentations keep their native exit++**Reference:** `spec:AST-090/DEC-5`+**Decider:** pending owner review++On a touch device a surface moves the way its native counterpart does, by+default and with no opt-in (`spec:AST-094`), and that record leaves pointer+presentations' timing and easing to the theme's tokens. The switches here+therefore govern pointer presentations only, and a touch presentation keeps+its native exit whatever they resolve to.++Rejected: letting the exit switches turn touch exits off, which removes the exit `spec:AST-094` FR7 requires.+## Open questions-- **OQ1 — Whether a dialog's exit ships on, and at which duration**- (`human-design`). Options: keep it off; default `--duration-exit-dialog` to- `var(--duration-exit)`; or default it to a duration from the entrance band,- because a person who closes a dialog deliberately watches it go.+- **OQ1 — Whether a pointer-presented dialog's exit ships on, and at which+ duration** (`human-design`). Options: keep it off; default+ `--duration-exit-dialog` to `var(--duration-exit)`; or default it to a+ duration from the entrance band, because a person who closes a dialog+ deliberately watches it go.- **OQ2 — Whether elements in page flow gain an exit kind** (`human-design`).`FieldStatus` and `useEntryAnimation` animate in and vanish when removed. Anexit would keep a validation message in the layout while it leaves, which