Skip to content

feat(ui): stacked dialog motion - #9432

Open
maxyinger wants to merge 7 commits into
max/dialog-stacking-statefrom
max/dialog-stack-motion
Open

feat(ui): stacked dialog motion#9432
maxyinger wants to merge 7 commits into
max/dialog-stacking-statefrom
max/dialog-stack-motion

Conversation

@maxyinger

Copy link
Copy Markdown
Collaborator

Description

Stacked at the top of #9427.

Separates two relationships that were previously one. A dialog opened over a panel or a card is a new surface over a page-like one, and its own scrim is what says so — that behaviour is unchanged. A stack is successive prompts, the confirmation over the form it is confirming: the same conversation one step further in. A stacked prompt paints no scrim at all, because darkening the page again for it makes depth a function of stack count. The composite compounds, so the three-deep panel → prompt → alert case this exists for would have landed on 0.83 against the 0.68 the nested value was solved for.

Depth comes from the prompt beneath instead. Its contents dim toward its own background, and it recedes — scaling down slightly and lifting, with its radius divided by the same factor so the corners render unchanged, the same correction the entrance scale already documents. A veil rather than opacity on the popup, since fading the popup fades the surface with it and lets the scrim through, which reads as the dialog dissolving rather than as depth.

Whether two dialogs form a stack turns on the size of the dialog beneath, which the headless layer has no notion of, so the backdrop resolves it from the parent size carried in context rather than keying on data-stacked alone.

Whichever relationship it is, the thing that opens is always a prompt. panel and card are root-level surfaces — they host, they are never hosted — so a dialog opened inside another one now warns in development if it is any other size. One rule stated on the child covers panel-in-panel and card-in-panel without enumerating what may host what.

Two smaller pieces:

  • Reduced motion keeps the recede and drops only its duration; transitionProperty already narrows to opacity there, so it lands in one frame with nothing interpolating. Removing it outright left a stacked prompt sitting on an identical prompt with no scrim between them, which reads as a rendering fault rather than as a preference being honoured.
  • On a phone, a sheet arriving over another dialog takes the shorter desktop fade. The long fade earns itself against the page, where it gives the travel somewhere to resolve into; over an opaque surface it just shows the dialog underneath through the one arriving. The slide is unchanged.

An exit stagger was built and removed: a prompt's exit runs 0.1s, which leaves no room to separate two of them, and lengthening a dismissal to make the separation visible is the wrong trade. Two commits in the history add it and take it back out.

The Nested story now demonstrates a vetoed close, which makes the panel → prompt → prompt case reachable. It is hand-rolled on purpose and meant to be replaced by the AlertDialog and close-confirmation work rather than kept.

Checklist

  • pnpm test runs as expected.
  • pnpm build runs as expected.
  • (If applicable) JSDoc comments have been added or updated for any package exports
  • (If applicable) Documentation has been updated

Type of change

  • 🐛 Bug fix
  • 🌟 New feature
  • 🔨 Breaking change
  • 📖 Refactoring / dependency upgrade / documentation
  • other:

One backdrop for the whole stack. A stacked dialog paints none, and the
root-level dialog's scrim survives underneath it. The scrim it replaces was
solved so that two levels composited to an intended total, which held only
for the two-deep case: alpha over alpha compounds, so the three-deep stack
this exists for went from an intended 0.68 to 0.83.

Depth comes from the surface beneath receding instead — scale and a lift,
with the radius divided by the same factor so the corners render unchanged,
the correction `ENTER_SCALE` already documents. Only `prompt` recedes;
`panel` and `card` are root-level surfaces and leave the stacked prompt's
shadow to carry the separation. A dialog stacked inside another one warns in
development if it is any size but `prompt`, which covers panel-in-panel and
card-in-panel without enumerating what may host what.

The recede stays live on the phone band where the entrance scale is pinned
flat: those are different gestures, and a stacked sheet covers enough of what
is beneath it that dropping the recede would leave that level with no cue at
all.

Keyed on `data-stacked`, not `data-nested` — the latter reports any floating
ancestor, so a dialog opened from a menu item would have lost its only scrim.
Recede alone reads as smaller more than as further back. Veiling the
contents toward the surface's own background separates the layers on its
own — which is what `panel` and `card` get, since neither moves.

A veil rather than `opacity` on the popup: fading the popup fades the
surface with it, letting the scrim through, which reads as the dialog
dissolving rather than as depth.
A dialog over a `panel` or a `card` keeps the scrim it had — that is a new
surface over a page-like one, and its own scrim is what says so. Only
successive prompts drop it, where a second scrim would darken the page for
what is the same conversation one step further in.

Whether it is a stack turns on the size of the dialog BENEATH, which the
headless layer has no notion of, so the backdrop resolves it from the parent
size carried in context and applies the style rather than keying on
`data-stacked`. The veil moves to `sizes.prompt` for the same reason.

Reduced motion keeps the recede and drops only its duration. Removing it
outright left a stacked prompt sitting on an identical prompt with no scrim
between them, which reads as a rendering fault rather than as a preference
being honoured.

Dismissing a stack in one action now staggers the exits off
`data-stack-exiting`, so it unwinds rather than vanishing on a single frame.
The stagger was invisible, and mostly not because it was short. The veil and
the lift were keyed on `data-stack-base`, which releases the instant the
child closes — so the surface beneath un-dimmed and dropped forward WHILE
fading out, moving toward the viewer at the moment it should have been
receding away. Both now hold through `data-stack-exiting` too, and the lift
rides a custom property so the exit branch carries it without having to know
whether there was ever a stacked child.

The delay goes to a full `fast`. Half of it was 50ms against a 100ms exit —
about a frame and a half, which is nothing.
A prompt's exit runs 0.1s, which leaves no room to separate two of them, and
lengthening a dismissal to make the separation visible is the wrong trade —
the dismissal is the part that should feel immediate.

Takes the veil and lift back to `data-stack-base` alone. They briefly held
through the exit as well, to stop the surface beneath un-dimming as it
faded, but that too is below the threshold over 0.1s.
On a phone a prompt fades over the full length of its slide, which earns
itself against the page — the fade gives the travel somewhere to resolve
into. Over an opaque surface it does the opposite: for a quarter of a second
the dialog underneath shows through the one arriving, and two stacked sheets
read as one muddy surface. There is already a surface there, so the slide
can carry the arrival alone and the fade goes back to the desktop `fast`.

Keyed on being over any open dialog rather than on the narrower
prompt-on-prompt stack: what makes the long fade wrong is arriving over
something opaque, and a panel is as opaque as a prompt.
Makes the panel -> prompt -> prompt case reachable: typing into "add email
address" and then trying to close it stacks a confirmation instead. Every
close request routes through the controlled `onOpenChange`, so declining to
commit there covers Escape, the corner X and Cancel at once.

Hand-rolled, and meant to be replaced by the AlertDialog and close
confirmation work rather than kept.
@changeset-bot

changeset-bot Bot commented Aug 13, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: bbd4a79

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages
Name Type
@clerk/ui Patch
@clerk/chrome-extension Patch
@clerk/swingset Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@vercel

vercel Bot commented Aug 13, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
clerk-js-sandbox Ready Ready Preview Aug 13, 2026 3:27am
swingset Error Error Aug 13, 2026 3:27am

Request Review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant