diff --git a/.changeset/uikit-sheet-release-rule.md b/.changeset/uikit-sheet-release-rule.md new file mode 100644 index 0000000000000..d71634effe33d --- /dev/null +++ b/.changeset/uikit-sheet-release-rule.md @@ -0,0 +1,7 @@ +--- +'@astryxdesign/core': patch +--- + +[chore] Internal: the rule a BottomSheet release will follow, measured from UIKit on iOS 26.2, as a pure function. It picks the stop nearest the sheet's offset plus its velocity × 0.1 s (below 250 pt/s, the stop nearest its offset), counting gone below the screen as a stop; from 1008 pt/s a flick goes at least to the next stop in its direction, on the 0.8-damped release spring. A release moving back toward where its drag began returns to the detent nearest that start, and never dismisses. It lands where UIKit did on 149 of 164 measured releases; the other 15 moved back toward their start, where UIKit settled 14 on the stop nearest them and flicked one to large. Not exported from the package entry point. + +@vjeux diff --git a/packages/core/src/BottomSheet/sheetRelease.test.ts b/packages/core/src/BottomSheet/sheetRelease.test.ts new file mode 100644 index 0000000000000..a7a0e16180bc7 --- /dev/null +++ b/packages/core/src/BottomSheet/sheetRelease.test.ts @@ -0,0 +1,549 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file sheetRelease.test.ts + * @input vitest, resolveSheetRelease and the UIKit constants table + * @output Holds the release rule to UIKit's own releases: 164 drags of a + * UISheetPresentationController `[.medium(), .large()]` sheet read from + * UIKit (offset and velocity of the sheet interaction's last drag update + * before the lift, the detent it settled on, and for the 79 whose spring + * was read the damping of the spring it attached); plus the rule's own + * edges + * @position Testing; pure, no DOM + */ + +import {describe, expect, it} from 'vitest'; +import {sheet, springs} from '../motion/uikit'; +import {resolveSheetRelease} from './sheetRelease'; + +/** + * Measured on the iOS 26.2 simulator (iPhone 17 Pro, 402 × 874 pt), in + * UIKit's own interaction offsets: the sheet's top at the large detent is at + * 62 pt, at the medium detent 404.32 pt, and gone at 874 pt. + * [case, offset at the lift (pt), velocity (pt/s, + = down), outcome, ζ of + * the release spring (null: a translate release, whose spring was not read)] + */ +const UIKIT_RELEASES: ReadonlyArray< + [string, number, number, 'large' | 'medium' | 'dismissed', number | null] +> = [ + ['off-300.v0', 120.99, -12.5, 'large', 1], + ['off-300.v500', 122.65, -481.4, 'large', 1], + ['off-300.v1500', 116.65, -1495.6, 'large', 0.8], + ['off-300.v3000', 129.32, -2903.5, 'large', 0.8], + ['off-230.v0', 184.32, 0, 'large', 1], + ['off-230.v500', 188.65, -472, 'large', 1], + ['off-230.v1500', 199.65, -1590, 'large', 0.8], + ['off-230.v3000', 225.65, -4037.7, 'large', 0.8], + ['off-170.v0', 244.32, 0, 'medium', 1], + ['off-170.v500', 250.99, -494.8, 'large', 1], + ['off-170.v1500', 282.99, -2323, 'large', 0.8], + ['off-170.v3000', 258.65, -3292.1, 'large', 0.8], + ['off-120.v0', 294.32, 0, 'medium', 1], + ['off-120.v500', 300.65, -466, 'medium', 1], + ['off-120.v1500', 296.32, -2209.6, 'large', 0.8], + ['off-120.v3000', 356.32, -686.1, 'medium', 1], + ['off-60.v0', 354.32, 0, 'medium', 1], + ['off-60.v500', 365.65, -493.5, 'medium', 1], + ['off-60.v1500', 368.32, -574.9, 'medium', 1], + ['off60.v0', 454.32, 0, 'medium', null], + ['off60.v500', 446.99, 481.5, 'medium', null], + ['off60.v1500', 428.32, 450.6, 'medium', null], + ['off120.v0', 514.32, 0, 'medium', null], + ['off120.v500', 503.65, 453.3, 'medium', null], + ['off120.v1500', 512.32, 1969.9, 'dismissed', null], + ['off120.v3000', 476.32, 1139.7, 'dismissed', null], + ['off200.v0', 594.32, 0, 'medium', null], + ['off200.v500', 583.65, 494.5, 'medium', null], + ['off200.v1500', 579.32, 1400, 'dismissed', null], + ['off200.v3000', 579.32, 3094.6, 'dismissed', null], + ['off300.v0', 694.32, 0, 'dismissed', null], + ['off300.v500', 687.65, 478.4, 'dismissed', null], + ['off300.v1500', 666.65, 1489.2, 'dismissed', null], + ['off300.v3000', 679.32, 3008.2, 'dismissed', null], + ['up.end356.v900', 351.65, -926.5, 'medium', 1], + ['up.end356.v1000', 352.65, -996.7, 'medium', 1], + ['down.end500.v1000', 501.99, 991, 'medium', null], + ['down.end500.v1200', 500.65, 1212.4, 'dismissed', null], + ['up.long.v400', 277.65, -381.2, 'medium', 1], + ['down.end600.v200', 590.32, 210.5, 'medium', null], + ['zeta.towardLarge.v720', 160.32, -726.6, 'large', 1], + ['zeta.towardLarge.v760', 160.65, -736.9, 'large', 1], + ['zeta.towardLarge.v800', 167.65, -746.9, 'large', 1], + ['zeta.towardLarge.v840', 161.32, -837.8, 'large', 1], + ['zeta.awayFromTarget.v760', 224.32, 801.4, 'medium', 1], + ['zeta.awayFromTarget.v840', 224.32, 1147.3, 'medium', 0.8], + ['zeta.awayFromTarget.v1000', 208.32, 76, 'large', 1], +]; + +/** + * The second capture, placed to separate the candidate laws: releases from + * 90 pt above to 180 pt below the medium detent at 600 to 1400 pt/s in + * either direction, the finger at a constant speed for its last 0.15 s and + * lifting while moving (iOS 26.2 simulator, Oct 24 2026). Same columns; ζ + * is null where the release dismissed or its spring was not read. + */ +const UIKIT_FLICK_RELEASES: ReadonlyArray< + readonly [ + string, + number, + number, + 'large' | 'medium' | 'dismissed', + 1 | 0.8 | null, + ] +> = [ + ['d-90.v-1400', 315.99, -1403.9, 'large', 0.8], + ['d-90.v-1200', 310.99, -1195.1, 'large', 0.8], + ['d-90.v-1000', 312.65, -1090.0, 'large', 0.8], + ['d-90.v-800', 310.99, -746.9, 'medium', 1], + ['d-90.v-600', 339.32, -607.5, 'medium', 1], + ['d-90.v600', 319.32, 567.3, 'medium', 1], + ['d-90.v800', 320.99, 776.4, 'medium', 1], + ['d-90.v1000', 324.32, 979.0, 'medium', 1], + ['d-90.v1200', 324.32, 1122.4, 'medium', 0.8], + ['d-90.v1400', 315.99, 1432.4, 'medium', 0.8], + ['d-45.v-1400', 345.99, -1399.9, 'large', 0.8], + ['d-45.v-1200', 369.32, -1288.8, 'large', 0.8], + ['d-45.v-1000', 346.32, -1028.3, 'large', 0.8], + ['d-45.v-800', 349.32, -868.6, 'medium', 1], + ['d-45.v-600', 349.32, -628.2, 'medium', 1], + ['d-45.v600', 372.32, 565.6, 'medium', 1], + ['d-45.v800', 359.32, 814.1, 'medium', 1], + ['d-45.v1000', 352.65, 1290.9, 'medium', 0.8], + ['d-45.v1200', 349.32, 1279.1, 'medium', 0.8], + ['d-45.v1400', 367.65, 2318.6, 'medium', 0.8], + ['d0.v-1400', 417.65, -2014.5, 'large', 0.8], + ['d0.v-1200', 404.32, -1222.1, 'large', 0.8], + ['d0.v-1000', 402.65, -920.3, 'medium', 1], + ['d0.v-800', 400.99, -927.9, 'medium', 1], + ['d0.v-600', 399.32, -594.7, 'medium', 1], + ['d0.v600', 404.32, 533.8, 'medium', null], + ['d0.v800', 414.32, 819.5, 'medium', null], + ['d0.v1000', 397.65, 1088.7, 'medium', 0.8], + ['d0.v1200', 404.32, 1164.9, 'dismissed', null], + ['d0.v1400', 414.32, 1873.1, 'dismissed', null], + ['d30.v-1400', 424.32, -928.4, 'medium', null], + ['d30.v-1200', 424.32, -1402.5, 'medium', null], + ['d30.v-1000', 424.32, -1014.9, 'medium', null], + ['d30.v-800', 427.65, -814.4, 'medium', null], + ['d30.v-600', 429.32, -582.8, 'medium', null], + ['d30.v600', 450.99, 605.9, 'medium', null], + ['d30.v800', 437.65, 803.7, 'medium', null], + ['d30.v1000', 444.32, 977.4, 'medium', null], + ['d30.v1200', 444.32, 1184.7, 'dismissed', null], + ['d30.v1400', 420.99, 1397.1, 'dismissed', null], + ['d60.v-1400', 454.32, -1723.7, 'medium', null], + ['d60.v-1200', 464.32, -1470.6, 'medium', null], + ['d60.v-1000', 450.99, -947.3, 'medium', null], + ['d60.v-800', 454.32, -806.7, 'medium', null], + ['d60.v-600', 450.99, -596.6, 'medium', null], + ['d60.v600', 472.65, 570.9, 'medium', null], + ['d60.v800', 484.32, 806.8, 'medium', null], + ['d60.v1000', 474.32, 967.4, 'medium', null], + ['d60.v1200', 474.32, 1179.4, 'dismissed', null], + ['d60.v1400', 450.99, 1306.2, 'dismissed', null], + ['d90.v-1400', 489.32, -1430.1, 'medium', null], + ['d90.v-1200', 484.32, -1213.0, 'medium', null], + ['d90.v-1000', 484.32, -1071.7, 'medium', null], + ['d90.v-800', 484.32, -924.6, 'medium', null], + ['d90.v-600', 489.32, -610.9, 'medium', null], + ['d90.v600', 479.32, 615.4, 'medium', null], + ['d90.v800', 497.65, 780.5, 'medium', null], + ['d90.v1000', 507.65, 975.6, 'medium', null], + ['d90.v1200', 504.32, 1177.0, 'dismissed', null], + ['d90.v1400', 490.99, 1443.1, 'dismissed', null], + ['d120.v-1400', 525.99, -1430.3, 'medium', null], + ['d120.v-1200', 507.65, -1164.3, 'medium', null], + ['d120.v-1000', 519.32, -1026.1, 'medium', null], + ['d120.v-800', 510.99, -807.4, 'medium', null], + ['d120.v-600', 519.32, -607.2, 'medium', null], + ['d120.v600', 502.65, 605.0, 'medium', null], + ['d120.v800', 484.32, 792.8, 'medium', null], + ['d120.v1000', 529.32, 965.5, 'medium', null], + ['d120.v1200', 534.32, 1177.8, 'dismissed', null], + ['d120.v1400', 522.65, 1408.6, 'dismissed', null], + ['d150.v-1200', 554.32, -1240.1, 'medium', null], + ['d150.v-1000', 552.65, -981.5, 'medium', null], + ['d150.v-800', 540.99, -794.3, 'medium', null], + ['d150.v-600', 537.65, -583.2, 'medium', null], + ['d150.v600', 537.65, 600.3, 'medium', null], + ['d150.v800', 537.65, 810.5, 'medium', null], + ['d150.v1000', 535.99, 1067.8, 'dismissed', null], + ['d150.v1200', 544.32, 1226.5, 'dismissed', null], + ['d150.v1400', 567.65, 1419.1, 'dismissed', null], + ['d180.v-1000', 582.65, -1063.9, 'medium', null], + ['d180.v-800', 570.99, -786.2, 'medium', null], + ['d180.v-600', 574.32, -645.2, 'medium', null], + ['d180.v600', 565.99, 601.9, 'medium', null], + ['d180.v800', 554.32, 800.5, 'medium', null], + ['d180.v1000', 554.32, 990.4, 'dismissed', null], + ['d180.v1200', 524.32, 1183.9, 'dismissed', null], + ['d180.v1400', 600.99, 1424.8, 'dismissed', null], +]; + +/** + * The third capture, back-outs (iOS 26.2 simulator, Oct 25 2026): from the + * medium detent, a drag past the midpoint toward large (to about 174 pt), + * or 90 % of the way to gone, then 40 pt back toward medium at a constant + * speed, lifting while moving. Below 250 pt/s none returns to medium: it + * settles where it is nearest (`sheet.release.minProjectionSpeed`). + */ +const UIKIT_BACKOUT_RELEASES: ReadonlyArray< + readonly [string, number, number, 'large' | 'medium' | 'dismissed', 1 | null] +> = [ + ['back.large.v100.r1', 229.32, 140.0, 'large', 1], + ['back.large.v250.r1', 224.32, 161.4, 'large', 1], + ['back.gone.v100.r1', 778.32, -96.3, 'dismissed', null], + ['back.gone.v250.r1', 781.65, -239.1, 'dismissed', null], + ['back.large.v100.r2', 223.65, 60.2, 'large', 1], + ['back.large.v250.r2', 224.32, 200.9, 'large', 1], + ['back.gone.v100.r2', 778.32, -95.9, 'dismissed', null], + ['back.gone.v250.r2', 779.32, -263.8, 'dismissed', null], + ['back.large.v100.r3', 224.32, 91.9, 'large', 1], + ['back.large.v250.r3', 222.32, 242.4, 'large', 1], + ['back.gone.v100.r3', 777.32, -105.4, 'dismissed', null], + ['back.gone.v250.r3', 777.32, -246.1, 'dismissed', null], + ['back.large224.v300', 224.32, 300.6, 'medium', 1], + ['back.large224.v400', 220.99, 403.9, 'medium', 1], + ['back.large224.v500', 224.32, 451.7, 'medium', 1], + ['back.large224.v650', 224.32, 634.4, 'medium', 1], + ['back.large224.v800', 217.65, 970.0, 'medium', 1], + ['back.large204.v300', 204.32, 327.3, 'medium', 1], + ['back.large204.v500', 196.32, 566.5, 'medium', 1], + ['back.large204.v800', 204.32, 963.1, 'medium', 1], + ['back.large244.v300', 239.32, 296.4, 'medium', 1], + ['back.large244.v500', 244.32, 501.7, 'medium', 1], + ['back.large224.v250.r1', 224.32, 243.6, 'large', 1], + ['back.large224.v262.r1', 224.32, 254.4, 'medium', 1], + ['back.large224.v275.r1', 224.32, 269.8, 'medium', 1], + ['back.large224.v288.r1', 224.32, 282.8, 'medium', 1], + ['back.large224.v250.r2', 222.32, 250.6, 'medium', 1], + ['back.large224.v262.r2', 221.99, 264.7, 'medium', 1], + ['back.large224.v275.r2', 224.32, 272.4, 'medium', 1], + ['back.large224.v288.r2', 222.32, 287.2, 'medium', 1], +]; + +const LARGE = 62; +const MEDIUM = 404.32; +const GONE = 874; + +describe('resolveSheetRelease against UIKit', () => { + // Every measured drag began at the medium detent. A release moving back + // toward it cancels there (spec:AST-094 FR37), where UIKit's own sheet + // settled 14 of those back-outs on the stop nearest them and flicked one + // (`d0.v-1400`) to large (listed below); on every other release the rule + // lands where UIKit landed. + const movingBack = (offset: number, velocity: number) => + velocity !== 0 && Math.sign(velocity) === Math.sign(MEDIUM - offset); + const releases = [ + ...UIKIT_RELEASES, + ...UIKIT_FLICK_RELEASES, + ...UIKIT_BACKOUT_RELEASES, + ]; + for (const [name, offset, velocity, outcome, zeta] of releases) { + const expected = movingBack(offset, velocity) ? 'medium' : outcome; + const note = expected === outcome ? '' : ` (UIKit: ${outcome})`; + it(`${name}: ${velocity} pt/s from ${offset} pt → ${expected}${note}`, () => { + const release = resolveSheetRelease({ + detents: [LARGE, MEDIUM], + dismissedOffset: GONE, + position: offset, + velocity, + start: MEDIUM, + }); + const landed = + release.kind === 'dismiss' + ? 'dismissed' + : release.index === 0 + ? 'large' + : 'medium'; + expect(landed).toBe(expected); + if (zeta != null && expected === outcome) { + expect(release.spring).toBe( + zeta === 1 ? springs.sheetDetent : springs.sheetReleaseFast, + ); + } + }); + } + + // The same releases with the cancel out of the way: each one starts where + // it is lifted, so FR37 never applies and every release lands where + // UIKit's sheet landed. With a start at the medium detent the cancel decides + // every release moving back toward it, and the slowest projected speed, + // the projection time and the tolerance on a stop would go untested on + // those. + describe('with no back-out to cancel (each release starting where it is lifted)', () => { + for (const [name, offset, velocity, outcome, zeta] of releases) { + it(`${name}: ${velocity} pt/s from ${offset} pt → ${outcome}`, () => { + const release = resolveSheetRelease({ + detents: [LARGE, MEDIUM], + dismissedOffset: GONE, + position: offset, + velocity, + start: offset, + }); + const landed = + release.kind === 'dismiss' + ? 'dismissed' + : release.index === 0 + ? 'large' + : 'medium'; + expect(landed).toBe(outcome); + if (zeta != null) { + expect(release.spring).toBe( + zeta === 1 ? springs.sheetDetent : springs.sheetReleaseFast, + ); + } + }); + } + }); + + it('departs from UIKit only on back-outs, which FR37 cancels', () => { + expect( + releases + .filter( + ([, offset, velocity, outcome]) => + movingBack(offset, velocity) && outcome !== 'medium', + ) + .map(([name]) => name), + ).toEqual([ + 'zeta.awayFromTarget.v1000', + 'd0.v-1400', + 'back.large.v100.r1', + 'back.large.v250.r1', + 'back.gone.v100.r1', + 'back.gone.v250.r1', + 'back.large.v100.r2', + 'back.large.v250.r2', + 'back.gone.v100.r2', + 'back.gone.v250.r2', + 'back.large.v100.r3', + 'back.large.v250.r3', + 'back.gone.v100.r3', + 'back.gone.v250.r3', + 'back.large224.v250.r1', + ]); + }); +}); + +describe('resolveSheetRelease', () => { + it('projects linearly: offset plus the velocity times the projection time', () => { + const release = resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 100, + velocity: 500, + start: 0, + }); + expect(release.projected).toBeCloseTo( + 100 + 500 * sheet.release.projectionSeconds, + 9, + ); + }); + + it('at rest, dismisses only past halfway from the shortest detent to gone', () => { + const at = (position: number) => + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position, + velocity: 0, + start: 300, + }).kind; + expect(at(469)).toBe('detent'); + expect(at(471)).toBe('dismiss'); + }); + + it('sends a flick at least to the next position beyond it', () => { + // On the 300 px detent, flicked down at the threshold: its projection + // (about 400 px) is nearer 300, but a flick goes on to the next position. + expect( + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 300, + velocity: sheet.release.fastSpeed, + start: 0, + }), + ).toMatchObject({kind: 'dismiss', offset: 640}); + // Just under the threshold, the same release projects back to 300. + expect( + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 300, + velocity: sheet.release.fastSpeed - 1, + start: 0, + }), + ).toMatchObject({kind: 'detent', offset: 300}); + // Within the tolerance a detent counts as passed; a flick up from just + // below 300 goes on to 0 instead of stopping at 300. + expect( + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 300 + sheet.release.detentTolerance / 2, + velocity: -sheet.release.fastSpeed, + start: 400, + }), + ).toMatchObject({kind: 'detent', offset: 0}); + }); + + it('takes the projection when a flick carries farther than the next position', () => { + // Flicked down at 5000 px/s from 50 px: the next position is 300, but + // the projection (550 px) is nearest gone, so it dismisses. + expect( + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 50, + velocity: 5000, + start: 0, + }), + ).toMatchObject({kind: 'dismiss', offset: 640}); + }); + + it('settles against the motion when the projection says so', () => { + // Just above the shortest detent, moving up slowly: back down to it. + const release = resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 250, + velocity: -200, + start: 300, + }); + expect(release).toMatchObject({kind: 'detent', index: 1, offset: 300}); + }); + + it('projects nothing below sheet.release.minProjectionSpeed', () => { + // From the tallest detent, past the midpoint toward the shorter one and + // let go moving on toward it just under the speed: it stays with the + // tallest, where it is nearest; just over it, the projection takes it on. + // (Moving back toward where the drag began, FR37 would cancel instead.) + const slow = sheet.release.minProjectionSpeed - 1; + const fast = sheet.release.minProjectionSpeed + 1; + expect( + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 140, + velocity: slow, + start: 0, + }), + ).toMatchObject({kind: 'detent', index: 0, projected: 140}); + expect( + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 140, + velocity: fast, + start: 0, + }), + ).toMatchObject({kind: 'detent', index: 1}); + }); + + it('cancels a release moving back toward its start, whatever the travel so far (spec:AST-094 FR37)', () => { + // Dragged from the 300 px detent to 600 px (gone at 640 px) and let go + // moving back up: back to 300, though the projection is nearest gone. + for (const velocity of [-100, -400, -1500]) { + expect( + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 600, + velocity, + start: 300, + }), + ).toMatchObject({kind: 'detent', index: 1, offset: 300}); + } + // Past the midpoint toward the tallest detent, moving back down: 300. + expect( + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 120, + velocity: 80, + start: 300, + }), + ).toMatchObject({kind: 'detent', index: 1, offset: 300}); + // Moving on, away from the start, the projection decides as before. + expect( + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position: 600, + velocity: 100, + start: 300, + }), + ).toMatchObject({kind: 'dismiss'}); + }); + + it('cancels to a detent, never to gone: a drag begun where a finger caught the sheet near gone (spec:AST-094 FR37)', () => { + // Caught at 720 pt, past the midpoint from medium to gone, dragged up to + // 600 and let go moving back down: a cancel commits nothing, so the sheet + // goes to the detent nearest the start, medium, where the same lift from + // a drag begun on medium settles too. + for (const velocity of [60, 400, 1500]) { + expect( + resolveSheetRelease({ + detents: [LARGE, MEDIUM], + dismissedOffset: GONE, + position: 600, + velocity, + start: 720, + }), + ).toMatchObject({kind: 'detent', index: 1, offset: MEDIUM}); + } + expect( + resolveSheetRelease({ + detents: [LARGE, MEDIUM], + dismissedOffset: GONE, + position: 600, + velocity: 60, + start: MEDIUM, + }), + ).toMatchObject({kind: 'detent', index: 1, offset: MEDIUM}); + }); + + it('never dismisses a sheet a drag may not dismiss', () => { + const release = resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: null, + position: 600, + velocity: 3000, + start: 300, + }); + expect(release).toMatchObject({kind: 'detent', index: 1, offset: 300}); + }); + + it('picks the spring by speed alone, from sheet.release.fastSpeed', () => { + const spring = (velocity: number, position = 150) => + resolveSheetRelease({ + detents: [0, 300], + dismissedOffset: 640, + position, + velocity, + // Released where the drag began: the cancel never applies. + start: position, + }).spring; + const fast = sheet.release.fastSpeed; + expect(spring(fast - 1)).toBe(springs.sheetDetent); + expect(spring(-(fast - 1))).toBe(springs.sheetDetent); + expect(spring(fast)).toBe(springs.sheetReleaseFast); + expect(spring(-fast)).toBe(springs.sheetReleaseFast); + // Dismissals: the swipe spring when fast, the detent spring when slow. + expect(spring(fast, 600)).toBe(springs.sheetDismissSwipe); + expect(spring(0, 600)).toBe(springs.sheetDetent); + }); + + it('needs a detent', () => { + expect(() => + resolveSheetRelease({ + detents: [], + dismissedOffset: 640, + position: 0, + velocity: 0, + start: 0, + }), + ).toThrow(RangeError); + }); +}); diff --git a/packages/core/src/BottomSheet/sheetRelease.ts b/packages/core/src/BottomSheet/sheetRelease.ts new file mode 100644 index 0000000000000..c6879062870c1 --- /dev/null +++ b/packages/core/src/BottomSheet/sheetRelease.ts @@ -0,0 +1,186 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file sheetRelease.ts + * @input The UIKit constants table (`sheet.release`, the sheet springs) and + * the motion foundation's snap-point projection + * @output Exports resolveSheetRelease, which says where a released sheet goes + * and on which spring, and the SheetRelease type + * @position Internal to BottomSheet; pure (no DOM, no React). The rule a + * drag's release follows; no gesture calls it yet. + * + * A released sheet goes where UISheetPresentationController sends it. The + * dismissed position (the sheet fully below the screen) counts as one of the + * positions. + * - Below `sheet.release.fastSpeed`, to the position nearest its release + * offset projected `sheet.release.projectionSeconds` ahead at the release + * velocity. Below `sheet.release.minProjectionSpeed` nothing is + * projected: it lands on whatever is nearest where it was let go; at + * rest the sheet dismisses once it is more than halfway from its + * shortest detent to gone. A sheet released just above a detent while + * moving up, but slowly, falls back to it. + * - From that speed on, a flick: at least to the next position beyond where + * it is, in its direction (on a position within + * `sheet.release.detentTolerance`, the one after it), or to the + * projection's nearest position if that is farther. + * - Either way, a release whose velocity points back toward where the + * drag began cancels, to the detent nearest that start, whatever the + * travel so far (spec:AST-094 FR37): a cancel commits nothing, so it never + * dismisses, even for a drag begun where a finger caught the sheet near + * gone. UIKit's own sheet does not: measured, a + * back-out let go below 250 pt/s settles where it is nearest (sheet.ts). + * + * The sheet gets there on UIKit's release spring, picked by the same speed + * (critically damped below it, 80 % damped from it on), and starting at the + * finger's velocity. + * + * Offsets are px down from the tallest detent (0 = fully open), velocities + * px/s with positive meaning downward. + * + * SYNC: When modified, update /packages/core/src/BottomSheet/sheetRelease.test.ts + */ + +import {selectSnapPoint} from '../motion/projection'; +import type {SpringDescription} from '../motion/spring'; +import {sheet} from '../motion/uikit/sheet'; +import { + SHEET_DETENT_SPRING, + SHEET_DISMISS_SWIPE_SPRING, + SHEET_RELEASE_FAST_SPRING, +} from '../motion/uikit/springs'; + +export interface SheetRelease { + /** A detent to settle on, or a dismissal. */ + kind: 'detent' | 'dismiss'; + /** Index into the detents passed in; -1 for a dismissal. */ + index: number; + /** Where the sheet goes: the detent's offset, or the dismissed offset. */ + offset: number; + /** The projected rest offset the choice was made from. */ + projected: number; + /** The spring that takes it there, handed the release velocity. */ + spring: SpringDescription; +} + +/** The deceleration rate whose projection reaches `seconds` of the velocity. */ +function rateForProjection(seconds: number): number { + // WWDC18's projection coasts (v / 1000) · r / (1 − r): r / (1 − r) = 1000·τ. + const ms = seconds * 1000; + return ms / (1 + ms); +} + +const PROJECTION_RATE = rateForProjection(sheet.release.projectionSeconds); + +/** The index of the position nearest `offset` (the first on a tie). */ +function nearestIndex( + positions: ReadonlyArray, + offset: number, +): number { + let best = 0; + for (let i = 1; i < positions.length; i += 1) { + if (Math.abs(positions[i] - offset) < Math.abs(positions[best] - offset)) { + best = i; + } + } + return best; +} + +/** + * Where a sheet released at `position` moving at `velocity` settles, and on + * which spring. + * + * @example + * ``` + * // Detents at 0 (open) and 300 px; gone at 640 px. Released at 300 px + * // moving down at 1200 px/s: a flick, so past the 300 px detent it is on + * // to the next position down, although its projection (420 px) is nearer + * // 300. + * resolveSheetRelease({ + * detents: [0, 300], + * dismissedOffset: 640, + * position: 300, + * velocity: 1200, + * start: 0, + * }); // {kind: 'dismiss', offset: 640, spring: SHEET_DISMISS_SWIPE_SPRING, …} + * ``` + */ +export function resolveSheetRelease({ + detents, + dismissedOffset, + position, + velocity, + start, +}: { + /** Detent offsets, ascending (the tallest first). */ + detents: ReadonlyArray; + /** The offset at which the sheet is fully off screen; null when a drag may not dismiss it. */ + dismissedOffset: number | null; + position: number; + velocity: number; + /** + * Where the drag began (a detent, or where a finger caught the sheet): a + * release moving back toward it cancels (FR37). Every drag has one, so it + * is required: leaving it out cannot skip the cancel. + */ + start: number; +}): SheetRelease { + if (detents.length === 0) { + throw new RangeError('resolveSheetRelease needs at least one detent'); + } + const positions = + dismissedOffset == null ? [...detents] : [...detents, dismissedOffset]; + // Below the slowest projected speed the release is where it was let go. + const projectedVelocity = + Math.abs(velocity) < sheet.release.minProjectionSpeed ? 0 : velocity; + const choice = selectSnapPoint(positions, { + position, + velocity: projectedVelocity, + rate: PROJECTION_RATE, + }); + const isFast = Math.abs(velocity) >= sheet.release.fastSpeed; + let index = choice.index; + if (isFast) { + // A flick goes at least to the next position beyond where it is. + const tolerance = sheet.release.detentTolerance; + let next = -1; + if (velocity > 0) { + next = positions.findIndex(p => p > position + tolerance); + } else { + for (let i = positions.length - 1; i >= 0 && next === -1; i -= 1) { + if (positions[i] < position - tolerance) { + next = i; + } + } + } + if (next !== -1 && (velocity > 0 ? next > index : next < index)) { + index = next; + } + } + // spec:AST-094 FR37: a release whose velocity points back toward where + // the drag began cancels, whatever the travel so far, to the detent nearest + // that start. A cancel commits nothing, so it never dismisses: a drag begun + // where a finger caught the sheet on its way to gone returns to a detent. + if (velocity !== 0 && Math.sign(velocity) === Math.sign(start - position)) { + index = nearestIndex(detents, start); + } + if (dismissedOffset != null && index === detents.length) { + // GUESS (spec:AST-094 FR2): a slow dismissal plays `SHEET_DETENT_SPRING`. + // None of the measured releases that dismissed had its spring read; + // MEASUREMENTS.md's M-SH09 (drags released past the dismiss boundary, + // their release spring read) will confirm or replace it. + return { + kind: 'dismiss', + index: -1, + offset: dismissedOffset, + projected: choice.projected, + spring: isFast ? SHEET_DISMISS_SWIPE_SPRING : SHEET_DETENT_SPRING, + }; + } + return { + kind: 'detent', + index, + offset: positions[index], + projected: choice.projected, + spring: isFast ? SHEET_RELEASE_FAST_SPRING : SHEET_DETENT_SPRING, + }; +} diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md index f21c4d8aa09d9..3e370eaf74bdc 100644 --- a/packages/core/src/motion/README.md +++ b/packages/core/src/motion/README.md @@ -11,25 +11,26 @@ so each keeps its measured value; no shipped component reads the roles yet. ## Files -| File | What it is | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| `uikit/` | THE constants table: every spring, duration, deceleration rate, rubber-band constant and curve, with its source. | -| `uikit/springs.ts` | Interaction springs (navigation, sheets, alerts, menus, controls, keyboard, banners) and the SwiftUI / UIKit presets. | -| `uikit/scroll.ts` | UIScrollView: deceleration rates, rubber band, bounce-back spring, paging, `delaysContentTouches`, scroll to top. | -| `uikit/timing.ts` | Non-spring clocks and curves: press highlight, Core Animation's named curves, keyboard, Reduced Motion cross-fade. | -| `uikit/navigation.ts` | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule. | -| `uikit/gestures.ts` | Gesture recognizer thresholds, the velocity filter and haptic stand-ins, as `{value, unit}` entries (sources in JSDoc). | -| `MEASUREMENTS.md` | The UIKit reference captures each unconfirmed value still needs. | -| `spring.ts` | Closed-form damped spring, every Apple parameterization, settling duration, a spring chasing a moving target. | -| `decay.ts` | UIScrollView's momentum coast. | -| `coast.ts` | A release's momentum curves for `animator.decay`: the coast, the edge spring, a release past an edge. | -| `rubberBand.ts` | UIScrollView's resistance past an edge, and its inverse. | -| `projection.ts` | Release targets: the rest point nearest the projected coast. | -| `resolveSnapPoint.ts` | Release policy: the snap point a release lands on (flick, back-out cancel, step limit), on `selectSnapPoint`. Internal. | -| `selectPage.ts` | Paging: at most one page per release, on `resolveSnapPoint`. | -| `bezier.ts` | Cubic-bézier timing functions (Core Animation's named curves). | -| `animator.ts` | Compositor animator: springs, coasts and any closed-form curve compiled to Web Animations, read back analytically. | -| `reducedMotionPlan.ts` | The animator's Reduce Motion planner: what one call becomes, a cross-fade whose travel lands while transparent or at once. | +| File | What it is | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `uikit/` | THE constants table: every spring, duration, deceleration rate, rubber-band constant and curve, with its source. | +| `uikit/springs.ts` | Interaction springs (navigation, sheets, alerts, menus, controls, keyboard, banners) and the SwiftUI / UIKit presets. | +| `uikit/scroll.ts` | UIScrollView: deceleration rates, rubber band, bounce-back spring, paging, `delaysContentTouches`, scroll to top. | +| `uikit/timing.ts` | Non-spring clocks and curves: press highlight, Core Animation's named curves, keyboard, Reduced Motion cross-fade. | +| `uikit/navigation.ts` | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule. | +| `uikit/gestures.ts` | Gesture recognizer thresholds, the velocity filter and haptic stand-ins, as `{value, unit}` entries (sources in JSDoc). | +| `uikit/sheet.ts` | UISheetPresentationController: the release projection and the slowest speed it projects, and the speed from which a release is a flick on the faster spring. | +| `MEASUREMENTS.md` | The UIKit reference captures each unconfirmed value still needs. | +| `spring.ts` | Closed-form damped spring, every Apple parameterization, settling duration, a spring chasing a moving target. | +| `decay.ts` | UIScrollView's momentum coast. | +| `coast.ts` | A release's momentum curves for `animator.decay`: the coast, the edge spring, a release past an edge. | +| `rubberBand.ts` | UIScrollView's resistance past an edge, and its inverse. | +| `projection.ts` | Release targets: the rest point nearest the projected coast. | +| `resolveSnapPoint.ts` | Release policy: the snap point a release lands on (flick, back-out cancel, step limit), on `selectSnapPoint`. Internal. | +| `selectPage.ts` | Paging: at most one page per release, on `resolveSnapPoint`. | +| `bezier.ts` | Cubic-bézier timing functions (Core Animation's named curves). | +| `animator.ts` | Compositor animator: springs, coasts and any closed-form curve compiled to Web Animations, read back analytically. | +| `reducedMotionPlan.ts` | The animator's Reduce Motion planner: what one call becomes, a cross-fade whose travel lands while transparent or at once. | Component-specific values (a sheet's detents, a switch's geometry, a context menu's timeline) live in a domain file per component, `uikit/.ts`, diff --git a/packages/core/src/motion/uikit/index.ts b/packages/core/src/motion/uikit/index.ts index 317b51207a562..83a83bebb044c 100644 --- a/packages/core/src/motion/uikit/index.ts +++ b/packages/core/src/motion/uikit/index.ts @@ -4,7 +4,7 @@ * @file index.ts * @input The domain files of the UIKit constants table * @output Re-exports `springs` and one constant per spring (`SHEET_PRESENT_SPRING`, - * …), `scroll`, `timing`, `navigation` and the + * …), `scroll`, `timing`, `navigation`, `sheet` and the * gesture thresholds (one `UIKIT_*` group per recognizer, their union * `UIKIT_GESTURES`, and the haptic tables) * @position Entry of the UIKit constants table (motion/uikit). Internal to @@ -40,6 +40,7 @@ export { } from './gestures'; export {navigation, registerNavigationTable} from './navigation'; export {registerScrollTable, scroll} from './scroll'; +export {sheet} from './sheet'; export { ACTION_SHEET_DISMISS_SPRING, ACTION_SHEET_PRESENT_SPRING, diff --git a/packages/core/src/motion/uikit/sheet.ts b/packages/core/src/motion/uikit/sheet.ts new file mode 100644 index 0000000000000..ca72c9f0afb6d --- /dev/null +++ b/packages/core/src/motion/uikit/sheet.ts @@ -0,0 +1,95 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file sheet.ts + * @input Nothing; data only + * @output Exports `sheet`: how UISheetPresentationController resolves a + * drag's release, the target projection and the speed that picks the + * release spring + * @position The sheet domain of the UIKit constants table (motion/uikit); + * its springs are `springs.sheetPresent`, `.sheetDismiss`, `.sheetDetent`, + * `.sheetReleaseFast` and `.sheetDismissSwipe` + * + * Read from UIKit with a `[.medium(), .large()]` sheet in an injected host + * app on the iOS 26.2 simulator: the release velocity UIKit computed, the + * offset it released at and the detent it settled on, for 164 releases, and + * the `CASpringAnimation` it attached for the 55 of the first 134 whose + * spring was read. Speeds are in pt/s (CSS px/s); times in seconds. + * + * Every leaf carries one or more `@source`; webkit and GUESS values also carry + * the `@measure` task that will confirm or replace them. uikit.test.ts + * enforces both. + * + * SYNC: When modified, update /packages/core/src/motion/README.md + */ + +export const sheet = { + release: { + /** + * How far ahead a release is projected, as seconds of its velocity: from + * `minProjectionSpeed` to `fastSpeed` the sheet settles on the position + * nearest `offset + velocity × this`, the dismissed position (fully off + * screen) counting as one of them. Slower, and at rest, the nearest + * position. + * @source measured: UIKit lab (injected host app), iOS 26.2 simulator, + * iPhone 17 Pro, 164 drag releases of a [.medium(), .large()] sheet + * between 0 and 4000 pt/s (offset and velocity of the sheet + * interaction's last drag update before the lift, outcome from the + * detent it settled on), 47 on Oct 23 and 87 on Oct 24 2026 placed to + * separate the candidate laws, and 30 back-outs on Oct 25 2026 (see + * `minProjectionSpeed`): with `fastSpeed`'s flick branch and + * `minProjectionSpeed`, every release fits for any value from 0.092 to + * 0.104 s. Of the first 134, a single linear projection fits at most + * 122 (at 0.103 s), and a quadratic one (offset + k·v·|v|) at most 126 + */ + projectionSeconds: 0.1, + /** + * Release speed (pt/s, in either direction) below which a release is not + * projected: the sheet settles on the position nearest where it was let + * go, whichever way it was moving. UIKit's sheet, turned back toward + * where it started and let go slowly, stays with the position it is + * nearest; the BottomSheet's rule cancels such a back-out instead + * (`spec:AST-094` FR37, BottomSheet/sheetRelease.ts). Inside the measured + * bracket. + * @source measured: UIKit lab (injected host app), iOS 26.2 simulator, + * iPhone 17 Pro, 30 releases on Oct 25 2026 of drags from the medium + * detent that went past the midpoint toward large, or 90 % of the way + * to gone, then turned back toward medium. The seven past the + * midpoint, let go at 60 to 244 pt/s, settled on large, and the six + * near gone, let go at 96 to 264 pt/s, dismissed: each the position + * nearest where it was let go, where a dismissal's projection lands + * too. Past the midpoint, from 250.6 pt/s on, the projection decided + * (back to medium), so the speed lies in (243.6, 250.6] + */ + minProjectionSpeed: 250, + /** + * Release speed (pt/s, in either direction) from which a release is a + * flick: it goes at least to the next position beyond where it is in + * its direction (`detentTolerance`), or to the projection's nearest + * position if that is farther. The same speed switches the settle from + * `springs.sheetDetent` (critically damped) to `springs.sheetReleaseFast` + * (80 % damping); an interactive dismissal at it takes + * `springs.sheetDismissSwipe`. Inside the measured bracket. + * @source measured: UIKit lab (injected host app), iOS 26.2 simulator, + * iPhone 17 Pro, 134 drag releases, 55 of them with the + * CASpringAnimation UIKit attached (29 of the 47 on Oct 23, 26 of the + * 87 on Oct 24 2026): damping 36.515 (ζ 1) at every read release up to + * 996.7 pt/s and 29.212 (ζ 0.8) at every one from 1028.3 pt/s on + * (`d-45.v-1000`, then 1088.7, 1090.0 and 1122.4 pt/s and faster), so + * the spring reads alone bracket the switch to (996.7, 1028.3]; with the + * 0.1 s projection the outcomes of all 134 fit the flick branch for a + * threshold from 997 to 1028 pt/s, the same bracket + */ + fastSpeed: 1008, + /** + * How close to a position (pt) a flick's offset counts as on it, so the + * next position beyond is the one after it. Inside the measured bracket. + * @source measured: UIKit lab (injected host app), iOS 26.2 simulator, + * iPhone 17 Pro, the 134 releases: two flicks released exactly on the + * medium detent go on to the next position in their direction, and one + * released 6.7 pt above it moving down stops at medium, so any value + * from 0 to 6.6 pt fits, Oct 24 2026 + */ + detentTolerance: 1, + }, +} as const;