Skip to content

feat(core): the rect morph's paths, the rect a grow-out presentation shows at each progress - #9764

Draft
cixzhang wants to merge 10 commits into
mainfrom
motion/morph-path
Draft

cixzhang wants to merge 10 commits into
mainfrom
motion/morph-path

Conversation

@cixzhang

@cixzhang cixzhang commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Supersedes #8909 by @vjeux, who stays the author of this commit. Builds on #9755 (the progress module, merged), which superseded #8497. #8909's branch carries the open chain under #8340 and #8360, about 28,000 lines. This module needs only #9755's mapProgress and the MotionCurve/MotionProperty types already on main, so this pull request is #8909's own change alone.

Stack: #9764 → #9769 → #8485 and #8080 (#8078 and #8508 have merged).

Maintainer impact

Five touch presentations grow a surface out of what the finger touched and shrink it back: menus, Popover, the lifted preview, Lightbox's zoom, and a sub-menu's parent card. Each needs the same geometry: the rect the surface shows at each point of its motion, and how an interrupted motion continues. The shared rect morph builds on this.

Intended invariant

No behavior change. The module is internal, and no component imports it yet. It's pure geometry over a progress curve that the caller supplies, so it sets no timing. A tap-opened presentation can drive it with the theme's motion tokens, and a gesture can drive it from its velocity. It fits the shared rectangle morph that architecture:layer-runtime INV15 describes.

  • Popover keeps its own module for now. Its move onto edgeGrowPath and morphCurves rides feat(core): one rect morph for touch presentations that grow out of a source rect #9769's player, which owns the exit copy and the timing, and it changes Popover's animated properties (translate and scale about 0 0, not scale about its edge point). So it lands later as its own migration, with its records. The popover proofs here import Popover's live popoverCollapsedState, popoverFrame and frameOf, so the two can't drift apart unnoticed.

Change

motion/morphPath.ts, internal, with its unit test, a README row and a [chore] changeset:

  • lerpPath: a straight line between two rects, with an optional companion opacity.
  • edgeGrowPath: a popover's growth out of a point on its edge facing the source. At progress p, its scale across the axis away from the source is s = s₀ + (1 − s₀)·p, its scale along that axis is s·(L₀ + (1 − L₀)·p), and its opacity is p.
  • Each path's restartFrom: the path from the rect on screen to either end, in that path's own law.
  • morphCurves: the x, y, scaleX, scaleY and opacity curves that put the element on the path's rect as a progress curve moves. Only translate, scale and opacity move, so the motion runs on the compositor.

spec:AST-094 FR31 ends with one sentence: motion/morphPath.ts gives the rect a grow-out presentation shows at each progress, motion/rectMorph.ts imports it, and no other motion module maps a progress to a rect.

morphPath.ts's own comments no longer cite a file that isn't on main yet or an undefined "law M1".

Evidence

Scope

  • No intended public API, product behavior, visual direction, or policy change.
  • Product changes discovered during the work were removed or split.
  • Public text and artifacts contain no internal Meta context.

Testing

  • pnpm exec vitest run packages/core/src/motion/morphPath.test.ts packages/core/src/motion/progress.test.ts: 23 passed.
  • pnpm exec tsc -p packages/core --noEmit: clean.
  • Strict ESLint on the two source files, pnpm check:knowledge, pnpm check:changesets: pass.
  • pnpm review:pre: 0 findings.

Writing rubric results

Record changed: spec:AST-094 FR31, one closing sentence that names motion/morphPath.ts.

Item Result
R1 Pass: the sentence states what the module does now (gives the rect at each progress; motion/rectMorph.ts imports it); no plan or history.
R2 Pass: no research in the record.
R3 Pass: no pull request, issue or commit as evidence.
R4 Pass: no rejected alternative.
R5 Pass: no # number, /pull/ or /issues/.
R6 Pass: no open question.

vjeux and others added 3 commits November 3, 2026 06:35
progressCurve, mapProgress, mapRange and presentedProgressVelocity in
motion/progress.ts, internal, one velocity unit (progress per second).
Rebuilt on main from the pull request's own change, without the open
dependency chain it no longer needs.

Co-authored-by: Cindy Zhang <cindyxz@meta.com>
…ressCurve

CodeBunny on #9755: springProgress solved the same spring as progressCurve.
It now reads progressCurve (remaining = 1 - progress), so one implementation
remains. Same curve, same settle epsilon (0.001) and duration.
…shows at each progress

lerpPath, edgeGrowPath, each path's restartFrom and morphCurves in
motion/morphPath.ts, internal. Pure geometry over a progress curve: the
caller chooses the timing. Rebuilt on the progress module from the pull
request's own change, without the open chain it no longer needs.

Co-authored-by: Cindy Zhang <cindyxz@meta.com>
@vercel

vercel Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 12, 2026 7:09am UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 3, 2026
@astracat-bot

astracat-bot Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 12, 2026, 8:35 AM UTC

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks ready to approve. The new internal motion/morphPath.ts is the shared rectangle morph that the layer-runtime architecture calls for. It stays unexported, and its tests, typecheck and lint pass. It can land once #9755 merges and this pull request retargets to main.

  • Optional: trim the morphPath.ts file header (lines 5–36) to @file, @input, @output, @position and SYNC:. Its two prose paragraphs repeat the exported JSDoc.
  • Optional: the description says comments no longer cite files missing from main. The test models still name popoverSurfaceMotion.ts and four other files that exist only in open pull requests.

[Automated review]

Comment thread packages/core/src/motion/morphPath.ts Resolved
@cixzhang
cixzhang changed the base branch from motion/progress-module to main November 3, 2026 16:10
# Conflicts:
#	packages/core/src/motion/README.md
@github-actions github-actions Bot added the needs:design-review Affects visuals — Design should review label Nov 3, 2026
@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks ready to approve. The new internal motion/morphPath.ts is the shared rectangle morph that the layer-runtime architecture calls for; it stays unexported, and its tests, typecheck and lint pass.

  • Optional: trim the morphPath.ts file header (lines 5–36) to @file, @input, @output, @position and SYNC:; its two prose paragraphs repeat the exported JSDoc.
  • Optional: the description says comments no longer cite files missing from main, but the test models still name popoverSurfaceMotion.ts and four other files that exist only in open pull requests.

[Automated review]

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: one blocking item, caused by a change that merged to main after the earlier approval.

  • Regression: Popover's touch growth now on main plays the same edge-growth law itself (popoverFrame and frameOf in Popover/popoverSurfaceFrame.ts, surfaceCurves and readState in Popover/popoverSurfaceMotion.ts), so growPath in morphPath.ts (lines 134–178) is a second copy that will drift; please move Popover's touch presentation onto edgeGrowPath and morphCurves here, or say in the description why it cannot move yet and have the popover tests import the live popoverCollapsedState and popoverFrame instead of the copy in morphPath.test.ts (lines 152–210).

The test copy already differs from the live code: for a popover that overlaps its source it grows from the left edge, where Popover grows from the top. The description's "Before: none of this exists on main" also no longer holds for the popover. Optional: trim the morphPath.ts file header (lines 5–36) to @file, @input, @output, @position and SYNC:.

[Automated review]

Comment thread packages/core/src/motion/morphPath.ts Resolved
The morph's popover proofs played a copy of Popover's growth that had
drifted: it lacked the overlap rule, so an overlapping popover grew
from its left edge where Popover grows from its top. The proofs now
import popoverCollapsedState, popoverFrame and frameOf from Popover.
A new overlapping case, which the deleted copy fails, pins the growth
from the top edge.

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the one blocking item from the last review still stands, though the test change narrows it.

  • Regression: Popover's touch growth on main still plays the same edge-growth law itself (popoverFrame and frameOf in Popover/popoverSurfaceFrame.ts, surfaceCurves and readState in Popover/popoverSurfaceMotion.ts), so growPath in morphPath.ts (lines 134–178) remains a second copy; please move Popover's touch presentation onto edgeGrowPath, restartFrom and morphCurves, or say in the description why it cannot move yet and drop "Before: none of this exists on main".

The popover growth proofs now read Popover's live geometry, so a change to Popover's growth fails morphPath.test.ts, and the overlap case is covered. The turn-around case (morphPath.test.ts lines 341–355) still compares restartFrom with lines written in the test, so a change to Popover's readState or surfaceCurves leaves it green; reading Popover's live turn-around there would close that gap. Optional: trim the morphPath.ts file header (lines 5–36) to @file, @input, @output, @position and SYNC:.

[Automated review]

The morph's turn-around proof compared restartFrom with lines written
in the test, so a change to Popover's readState or surfaceCurves left
it green. Popover exports both for the proofs, which now replay its
own turn-around. morphPath.ts's header keeps only its tags: the
paths' own JSDoc says the rest.

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet because the pull request is a draft, and marking it ready for review starts it.

The earlier blocking item is resolved: the description now explains why Popover keeps its own edge growth until the player in #9769, and both popover proofs in morphPath.test.ts replay Popover's live growth and turn-around, so a change to either side fails the test.

  • The Stack: #9764 → #9769 → #8485 line does not hold yet: #8485's head does not contain #9769's head, so this pull request is judged on its own.

Optional: the description says comments no longer cite files missing from main, but four model comments in morphPath.test.ts still name menuSurfaceMotion.ts, ContextMenuLift.tsx, zoomTransition.ts and menuDrillInMotion.ts.

[Automated review]

@cixzhang
cixzhang marked this pull request as ready for review November 8, 2026 14:24
@cixzhang cixzhang added the ci:run A maintainer lets this outside contributor's pull request run CI (AST-030 FR17) label Nov 8, 2026
vjeux added 2 commits November 8, 2026 23:55
Popover's surface curves now stop their opacity at 0 or a floor above
it. Past its end, a turn-around toward the source takes the popover
path's opacity below 0, where Popover's stops at 0. An opacity draws
clamped to 0 through 1, so both draw 0. The proof now compares the two
as drawn, which holds with Popover's curves before and after the
floor.
A popover's grow path read its opacity on a straight line, so before
its start and past its end it went below 0: a turn-around toward the
source read -0.025 at 1.05. An opacity below 0 draws as 0, so
opacityAt now stops at 0. The popover proofs compare opacities as
drawn, since Popover's own model still reads below 0 there.
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 6354fa3

@cixzhang cixzhang added the ci:run-a11y Run the accessibility suite on this PR; write access, next push (AST-030 FR12) label Nov 10, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: the heavy test suites have not run on this head yet; they run before merge.

The new internal motion/morphPath.ts gives the shared rectangle morph its geometry (lerpPath, edgeGrowPath with its restartFrom, and morphCurves), stays unexported, and no component uses it yet; its tests, typecheck and lint pass. Popover keeps its own edge-growth module for now, and the popover proofs pin the two together against Popover's live code.

Two small points, neither blocking:

  • The Testing section's counts are stale: morphPath.test.ts has 11 tests at this head, so the run is 23, not 22.
  • The Stack: #9764 → #9769 → #8485 line doesn't hold right now: #8485's branch doesn't contain #9769's current head.

[Automated review]

@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 12, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 6176b9d

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 12, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: two claims in the description don't match the code at this head. Both are quick edits.

Otherwise the new internal motion/morphPath.ts checks out: it stays unexported, nothing calls it yet, and the spec:AST-094 FR31 sentence has an engineering owner's approval for this head.

  • Newly live check: the description says the morph-path tests are 10 and the run is 22, but morphPath.test.ts has 11 tests at this head, so the run is 23.
  • Newly live check: the description says comments no longer cite a file that isn't on main, but the JSDoc at morphPath.test.ts lines 196, 217, 240 and 270 cites menuSurfaceMotion.ts, ContextMenuLift.tsx, zoomTransition.ts and menuDrillInMotion.ts, none of which is on main; narrow the claim to morphPath.ts or drop those file names.
Claims and files checked
  • Claim: the module commit keeps @vjeux as its author: verified (the commit that adds morphPath.ts).
  • Claim: the module needs only mapProgress and the animator's curve types already on main: verified (morphPath.ts imports).
  • Claim: no behavior change; the module is internal and no component imports it: verified (only its test imports it; no exports entry reaches it).
  • Claim: pure geometry over a caller-supplied progress curve, so it sets no timing: verified (morphCurves takes the curve).
  • Claim: it fits the shared rectangle morph the layer-runtime record describes: verified (INV15).
  • Claim: Popover keeps its own module, and its move would change its animated properties to translate and scale about 0 0: verified (morphCurves assumes transform-origin: 0 0; Popover scales about its edge point).
  • Claim: the popover proofs import Popover's live geometry: verified (test imports popoverCollapsedState, popoverFrame, frameOf, readState, surfaceCurves).
  • Claim: lerpPath and edgeGrowPath follow the stated laws, with opacity p: verified (morphPath.ts lines 78-106 and 118-164).
  • Claim: each path continues an interrupted motion in its own law: verified (edgeGrowPath's restartFrom; a path without one, like lerpPath, continues on a straight line by the MorphPath contract).
  • Claim: morphCurves moves only translate, scale and opacity: verified (lines 238-247).
  • Claim: comments no longer cite a file that isn't on main: false (morphPath.test.ts lines 196, 217, 240, 270).
  • Claim: Popover on main already plays the edge-growth law in its own module: verified (popoverFrame, frameOf).
  • Claim: typecheck clean and the tests pass: the source is unchanged from the previous head, where typecheck and lint passed in CI; not rerun here.
  • Claim: the tests are 10 plus 12, 22 in all: false (11 plus 12, 23).
  • Claim: no public API, product behavior or visual change: verified; the description does not mention the FR31 edit.
  • Claim: no internal context in public text: verified.
  • Changeset: an internal [chore] patch for core; the two paths name the rect at each progress and how an interrupted motion continues; morphCurves makes compositor curves; not exported and unused: verified.
  • File .changeset/motion-morph-path.md: clear.
  • File docs/specs/AST-094-touch-presentations/spec.md: owner-approved at this head; the motion/rectMorph.ts clause names a file not yet on main (non-blocking).
  • File packages/core/src/Popover/popoverSurfaceMotion.ts: clear (module exports only; not package surface).
  • File packages/core/src/motion/README.md: clear.
  • File packages/core/src/motion/morphPath.test.ts: four comments cite files not on main (blocking only through the description claim).
  • File packages/core/src/motion/morphPath.ts: clear.

Automated review (maintainer link)

follows the sheet instead.
follows the sheet instead. `motion/morphPath.ts` gives the rect a grow-out
presentation shows at each progress (a straight line, or a popover's edge
grow); `motion/rectMorph.ts` imports it; no other motion module maps a

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: motion/rectMorph.ts is not on main or at this head yet, so this clause makes the current record describe a file that does not exist until #9769 lands. Consider dropping "motion/rectMorph.ts imports it;" here and adding it with #9769.

@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 6176b9d

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet because the pull request is a draft, and marking it ready for review starts it.

The new internal motion/morphPath.ts gives the shared rectangle morph its geometry, stays unexported, and nothing calls it yet; the spec:AST-094 FR31 sentence has an engineering owner's approval for this head. The two description points from the last review are fixed: the test counts now read 11 and 23, and the comment claim is scoped to morphPath.ts.

  • Miss (optional): the header of Popover/popoverSurfaceMotion.ts (@output, lines 10-12, and SYNC:, lines 16-19) does not mention the new surfaceCurves and readState exports or motion/morphPath.test.ts, which now reads them.
Claims and files checked
  • Claim: the module's commit keeps its original author: verified (the commit that adds morphPath.ts).
  • Claim: it builds on the merged progress module and needs only mapProgress and the animator's curve types: verified (morphPath.ts:22-23).
  • Claim: the superseded branch carries about 28,000 lines of an open chain: verified (28,036 added lines).
  • Claim: the two lower stack entries named as merged have merged: verified.
  • Claim: five touch presentations need the same geometry: verified as context (the test models all five).
  • Claim: no behavior change; the module is internal and no component imports it: verified (only its test imports it; no exports entry reaches it).
  • Claim: pure geometry over a caller-supplied progress curve, so it sets no timing, and theme tokens or a gesture's velocity can drive it: verified (morphCurves takes any curve, morphPath.ts:231-249).
  • Claim: it fits the shared rectangle morph the layer-runtime record describes: verified (INV15).
  • Claim: Popover keeps its own module, and moving it changes its animated properties to translate and scale about 0 0: verified (morphCurves assumes transform-origin: 0 0; Popover scales about its edge point, popoverSurfaceMotion.ts:319-320).
  • Claim: the popover proofs import Popover's live geometry: verified (morphPath.test.ts:24-31).
  • Claim: lerpPath is a straight line with an optional companion opacity: verified (morphPath.ts:78-106).
  • Claim: edgeGrowPath follows the stated scale, length and opacity law: verified (morphPath.ts:118-199).
  • Claim: each path continues an interrupted motion in its own law: verified (edgeGrowPath's restartFrom; a path without one continues on a straight line by the MorphPath contract).
  • Claim: morphCurves moves only translate, scale and opacity: verified (morphPath.ts:238-247).
  • Claim: FR31 ends with one sentence naming the module, its importer and that no other motion module maps a progress to a rect: verified (spec.md:634-637).
  • Claim: morphPath.ts's own comments cite no file missing from main and no undefined law: verified.
  • Claim: Popover on main already plays this edge-growth law in its own module: verified for the geometry; main also starts Popover's fade at a small opacity floor that the new path does not model.
  • Claim: typecheck is clean: not rerun here; typecheck passed in CI on an identical package tree.
  • Claim: the tests number 11 plus 12, 23 in all: verified by count (morphPath.test.ts, progress.test.ts); not rerun here.
  • Claim: lint, knowledge and changeset checks and the pre-review script pass: lint passed in CI on an identical package tree; the others were not rerun here.
  • Claim: no public API, product behavior or visual change, and product changes found during the work were removed: verified.
  • Claim: public text carries no internal context: verified.
  • Claim: the FR31 sentence passes writing rubric items R1 to R6: verified; its importer clause names a file that lands with #9769.
  • Changeset: an internal patch for core; the two paths name the rect at each progress and how an interrupted motion continues, morphCurves makes compositor curves, nothing is exported and no component uses them: verified.
  • File .changeset/motion-morph-path.md: clear.
  • File docs/specs/AST-094-touch-presentations/spec.md: clear (owner-approved; the importer clause names a file not here yet).
  • File packages/core/src/Popover/popoverSurfaceMotion.ts: the header note above; otherwise clear.
  • File packages/core/src/motion/README.md: clear.
  • File packages/core/src/motion/morphPath.test.ts: clear.
  • File packages/core/src/motion/morphPath.ts: clear.

Automated review (maintainer link)

* package.
*/
function surfaceCurves(
export function surfaceCurves(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Miss, non-blocking: this file's header still lists only popoverCollapsedState, popoverFrame and createPopoverSurfaceMotion under @output (lines 10-12), and its SYNC: list (lines 16-19) does not name motion/morphPath.test.ts, which now imports surfaceCurves and readState. Adding both exports to @output and the test to SYNC: reminds whoever edits these two functions that the morph's proofs replay them.

This branch was successfully deployed

1 active deployment
Preview — 6176b9dc Deployed Nov 12, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:run A maintainer lets this outside contributor's pull request run CI (AST-030 FR17) ci:run-a11y Run the accessibility suite on this PR; write access, next push (AST-030 FR12) CLA Signed This label is managed by the Meta Open Source bot. needs:design-review Affects visuals — Design should review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants