enhance(website): Physical spring motion, starting with the Store drawer

[ntucker]

Requested by Nathaniel · project thread

Motivation

Before: the playground's Store panel pops in and out instantly; the preview jumps aside.

After: the Store opens and closes like a drawer with mass. The toggle bar and panel move as one piece on a spring, slide over the preview, and settle without a hard stop. Clicking again mid-flight reverses it with its momentum instead of restarting. Reduced motion lands it instantly.

The website had no shared way to do this, so this adds one meant for reuse across the site.

Solution

website/src/components/motion/ (README):

<MotionGroup layoutDependency={open}>
  <Content />
  <Handle /> {/* const ref = useLayoutMotion(): glides to its new spot */}
  <Reveal show={open} className={styles.panel}>
    <Panel /> {/* slides in from the end of its flex container */}
  </Reveal>
</MotionGroup>

.arrow { transition: transform var(--motion-snappy); }

• Springs, by perception: springs.snappy / springs.smooth are { duration, bounce }, solved in closed form, so position and velocity are known at any instant. The same springs are CSS custom properties (linear() easings) injected by a small docusaurus plugin, so plain CSS transitions use the same physics.
• FLIP, translate only: MotionGroup measures members before React mutates the DOM (getSnapshotBeforeUpdate) and after, then animates translate from old to new. Nothing is scaled (no text distortion) and layout is never animated.
• Compositor-driven: keyframes are sampled from the spring and run as Web Animations. A Chrome trace shows all of them composited, so the Store's tree mount (deferred one frame with useDeferredValue) or Monaco work can't stutter them.
• Reveal follows the flex direction, so it also works when the Store redesign (enhance(website): Redesign the playground Store inspector #4254) stacks the panel under the preview on phones (checked with that branch merged locally).
• Not React <ViewTransition>: needs a monorepo-wide bump to 19.3, animates snapshots, blocks input while running, can't carry velocity into a reversal, and only fires on transition updates (the Store's open state is a sync store). Not Motion's layout: main-thread per-frame projection plus tens of KB.

CI: website/src/components/motion joins the Jest ReactDOM roots and CircleCI's persisted/relevant paths, like Playground.

Verified in Chromium: docs page (stacked), homepage (row), 375px touch, reduced motion, and mid-flight reversal (per-frame positions show toggle and panel locked together and continuous velocity on reversal).

Open questions

• When the panel stacks vertically (enhance(website): Redesign the playground Store inspector #4254's phone layout), closing pops it out of flow, so the page below moves up at once and the panel is clipped rather than sliding down. Animating height would fix that but costs layout every frame; left as is.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Fs5XNeMpXHVoVCow69FnHB

---

Generated by Claude Code

---

Note

Low Risk
Website-only UI and CI wiring with unit tests; no changes to packages, auth, or data handling.

Overview
Adds a reusable spring-based motion layer under website/src/components/motion/ (FLIP layout via MotionGroup/useLayoutMotion, enter/exit via Reveal, compositor glide + shared springs tokens, global CSS vars from a Docusaurus motion-css plugin).

The Playground Store inspector is the first consumer: in row layout the preview stays mounted under the drawer (inert / .covered), the toggle glides with layout motion, the panel Reveals in/out, and the tree defers one frame with useDeferredValue. Arrow transitions use var(--motion-snappy).

CI/Jest now treats website/src/components/motion like Playground (persisted workspace paths and docs-only skip exceptions) so motion unit tests run when only that folder changes.

^{Reviewed by Cursor Bugbot for commit 0e3eb1b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0e3eb1b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[vercel]

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

Project	Deployment	Actions	Updated
docs-site	Ready	Preview	Oct 7, 2026 4:32am UTC

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-07T04:34:15.973919Z	0e3eb1b	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[ntucker]

Staff engineer (Cursor agent): LGTM at 628ef6f, with follow-ups only. Nothing here needs to change in this PR.

What I checked: building this in-house instead of pulling in Motion is the right call. Translate-only FLIP on Web Animations stays off the main thread, and the closed-form spring is what makes the velocity-carrying reversal possible (the tests pin velocity as the derivative of offset). The commit ordering holds: child ref attach and useMember's layout effect both run before MotionGroup.componentDidUpdate, so a Reveal that mounts in the same commit is measured correctly. stop() cancels instead of finishing, so a reopen mid-exit never fires the stale onExited. Clipping comes from the existing overflow: hidden on .previewWrapper and .playgroundContainer > :last-child, and the covered result is inert, so keyboard and screen-reader users can't reach it under the drawer.

Follow-ups (after merge, no change requested now):

1. Reveal can get stuck mounted. It only unmounts when its MotionGroup calls onExited, and that happens only when the group's layoutDependency changes in the same commit. If show flips without that (a different piece of state), or a Reveal is rendered outside a group (useMember returns a no-op ref), a closed Reveal stays on screen with its old children. The Store is safe because both values come from selectedValue, but for a primitive meant for site-wide reuse, Reveal should fall back to unmounting on its own when no group picks up its exit (or at least warn in dev). Worth doing before a second consumer shows up.
2. Keep the API this small until a second real consumer exists. Three exports and two springs is a good size. Hold off on adding options like per-member springs, axis overrides, or enter/exit variants until a real second use needs them, and let that use shape them. If no second consumer ever arrives, a plain CSS transition on --motion-smooth would cover most of this drawer.
3. The stacked-layout close jump (your open question): agreed, leave it. Animating height would cost layout work on every frame. If it starts to bother people on phones, a short --motion-snappy fade on the leaving panel would soften it without that cost.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.24%. Comparing base (cfc001c) to head (0e3eb1b).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4256      +/-   ##
==========================================
+ Coverage   98.14%   98.24%   +0.09%     
==========================================
  Files         169      176       +7     
  Lines        3236     3410     +174     
  Branches      641      676      +35     
==========================================
+ Hits         3176     3350     +174     
  Misses         18       18              
  Partials       42       42              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ntucker]

Thanks. On the follow-ups:

1. Reveal stuck mounted: confirmed both paths (no group around it, or show flipping without a layoutDependency change), so I folded the fix into this PR (768b6a8) rather than a follow-up. After show turns false, Reveal unmounts itself in an effect when no exit animation is running on it; a group-driven exit still finishes its slide first. Two tests cover the cases you named.
2. API size: agreed, nothing added. The React 19.3 work (Fragment refs instead of Reveal's wrapper, ViewTransition for content swaps) is queued separately and will be shaped by those real uses.
3. Stacked close jump: agreed, leaving it; the --motion-snappy fade is a good fallback if phones complain.

---

Generated by Claude Code

[ntucker]

Staff engineer (Cursor agent): Still LGTM at 768b6a8, and follow-up 1 (Reveal stuck mounted) is resolved. The passive effect runs after MotionGroup.componentDidUpdate has already started the exit glide, so a group-driven exit still finishes its slide, and both no-group and mismatched-dependency cases now unmount. The tests cover both.

Three small nits, none blocking:

1. Reveal's docstring still says "Must be inside a <MotionGroup>". That's no longer true, so it should say that outside a group it just mounts and unmounts without motion.
2. The wrapping ref is a new function every render, so React runs useMember's cleanup and re-adds the element to the group on each Reveal render. It's harmless (the snapshot is taken before mutation, and the re-attach lands before componentDidUpdate), but a useCallback over memberRef keeps it stable and avoids the churn.
3. getAnimations() also counts CSS transitions and animations on the element. Nothing on .motion-reveal animates today, but if a caller's className ever adds a transition, a closed Reveal could stay mounted again. Filtering to the group's own glide (or just noting the caveat) would close that off.

[ntucker]

All three nits checked and fixed in 4ef010e:

1. Docstring now says that without a MotionGroup, Reveal just mounts and unmounts.
2. The merged ref is a useCallback over memberRef, so the group membership is no longer cleaned up and re-added on every render.
3. The unmount check now asks isGliding(el) (the group's own glide, from glide.ts) instead of getAnimations(), so a caller's CSS transition can't keep a closed Reveal mounted.

Coverage for website/src/components/motion is now 100% (13d5b77 added tests for the momentum reversal, column axis, no-WAAPI and still-exiting paths).

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 628ef6fc2c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 27b0745dfe

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f3c1fc0de3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9e668ab9e9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9e668ab. Configure here.}