Skip to content

Commit a5e2879

Browse files
committed
chore(core): the sheet's release rule fits all 134 measured releases
astracat-bot on #8068: the linear 0.114 s projection reproduced 44 of the 47 releases, and its misses were fast downward flicks UIKit dismissed, not reading noise. A second capture of 87 releases placed to separate the candidate laws (M-SH09) settles it: below 1008 pt/s a release goes to the position nearest its offset projected 0.1 s ahead; from 1008 pt/s it is a flick and goes at least to the next position beyond it in its direction (within 1 pt of a position counts as on it), or to the projection's nearest if that is farther. The 80 % damped release spring switches at the same speed. That rule reproduces all 134 releases (a single linear projection at most 122, a quadratic one 126). A slow dismissal's spring stays a stand-in: no measured dismissal recorded one.
1 parent 7cf0336 commit a5e2879

5 files changed

Lines changed: 238 additions & 88 deletions

File tree

‎.changeset/uikit-sheet-release-rule.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
'@astryxdesign/core': patch
33
---
44

5-
[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.114 s, counting gone below the screen as a stop, and picks the 0.8-damped release spring from 1072 pt/s up. Not exported from the package entry point; no component uses it yet.
5+
[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, 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. It reproduces all 134 measured releases. Not exported from the package entry point; no component uses it yet.
66

77
@vjeux

‎packages/core/src/BottomSheet/sheetRelease.test.ts‎

Lines changed: 156 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
/**
44
* @file sheetRelease.test.ts
55
* @input vitest, resolveSheetRelease and the UIKit constants table
6-
* @output Holds the release rule to UIKit's own releases: 47 drags of a
6+
* @output Holds the release rule to UIKit's own releases: 134 drags of a
77
* UISheetPresentationController `[.medium(), .large()]` sheet read from
88
* UIKit (offset and velocity of the sheet interaction's last drag update
99
* before the lift, the detent it settled on, the damping of the spring it
@@ -74,27 +74,120 @@ const UIKIT_RELEASES: ReadonlyArray<
7474
['zeta.awayFromTarget.v1000', 208.32, 76, 'large', 1],
7575
];
7676

77+
/**
78+
* The second capture, placed to separate the candidate laws: releases from
79+
* 90 pt above to 180 pt below the medium detent at 600 to 1400 pt/s in
80+
* either direction, the finger at a constant speed for its last 0.15 s and
81+
* lifting while moving (iOS 26.2 simulator, Oct 24 2026). Same columns; ζ
82+
* is null where the release dismissed or its spring was not read.
83+
*/
84+
const UIKIT_FLICK_RELEASES: ReadonlyArray<
85+
readonly [
86+
string,
87+
number,
88+
number,
89+
'large' | 'medium' | 'dismissed',
90+
1 | 0.8 | null,
91+
]
92+
> = [
93+
['d-90.v-1400', 315.99, -1403.9, 'large', 0.8],
94+
['d-90.v-1200', 310.99, -1195.1, 'large', 0.8],
95+
['d-90.v-1000', 312.65, -1090.0, 'large', 0.8],
96+
['d-90.v-800', 310.99, -746.9, 'medium', 1],
97+
['d-90.v-600', 339.32, -607.5, 'medium', 1],
98+
['d-90.v600', 319.32, 567.3, 'medium', 1],
99+
['d-90.v800', 320.99, 776.4, 'medium', 1],
100+
['d-90.v1000', 324.32, 979.0, 'medium', 1],
101+
['d-90.v1200', 324.32, 1122.4, 'medium', 0.8],
102+
['d-90.v1400', 315.99, 1432.4, 'medium', 0.8],
103+
['d-45.v-1400', 345.99, -1399.9, 'large', 0.8],
104+
['d-45.v-1200', 369.32, -1288.8, 'large', 0.8],
105+
['d-45.v-1000', 346.32, -1028.3, 'large', 0.8],
106+
['d-45.v-800', 349.32, -868.6, 'medium', 1],
107+
['d-45.v-600', 349.32, -628.2, 'medium', 1],
108+
['d-45.v600', 372.32, 565.6, 'medium', 1],
109+
['d-45.v800', 359.32, 814.1, 'medium', 1],
110+
['d-45.v1000', 352.65, 1290.9, 'medium', 0.8],
111+
['d-45.v1200', 349.32, 1279.1, 'medium', 0.8],
112+
['d-45.v1400', 367.65, 2318.6, 'medium', 0.8],
113+
['d0.v-1400', 417.65, -2014.5, 'large', 0.8],
114+
['d0.v-1200', 404.32, -1222.1, 'large', 0.8],
115+
['d0.v-1000', 402.65, -920.3, 'medium', 1],
116+
['d0.v-800', 400.99, -927.9, 'medium', 1],
117+
['d0.v-600', 399.32, -594.7, 'medium', 1],
118+
['d0.v600', 404.32, 533.8, 'medium', null],
119+
['d0.v800', 414.32, 819.5, 'medium', null],
120+
['d0.v1000', 397.65, 1088.7, 'medium', 0.8],
121+
['d0.v1200', 404.32, 1164.9, 'dismissed', null],
122+
['d0.v1400', 414.32, 1873.1, 'dismissed', null],
123+
['d30.v-1400', 424.32, -928.4, 'medium', null],
124+
['d30.v-1200', 424.32, -1402.5, 'medium', null],
125+
['d30.v-1000', 424.32, -1014.9, 'medium', null],
126+
['d30.v-800', 427.65, -814.4, 'medium', null],
127+
['d30.v-600', 429.32, -582.8, 'medium', null],
128+
['d30.v600', 450.99, 605.9, 'medium', null],
129+
['d30.v800', 437.65, 803.7, 'medium', null],
130+
['d30.v1000', 444.32, 977.4, 'medium', null],
131+
['d30.v1200', 444.32, 1184.7, 'dismissed', null],
132+
['d30.v1400', 420.99, 1397.1, 'dismissed', null],
133+
['d60.v-1400', 454.32, -1723.7, 'medium', null],
134+
['d60.v-1200', 464.32, -1470.6, 'medium', null],
135+
['d60.v-1000', 450.99, -947.3, 'medium', null],
136+
['d60.v-800', 454.32, -806.7, 'medium', null],
137+
['d60.v-600', 450.99, -596.6, 'medium', null],
138+
['d60.v600', 472.65, 570.9, 'medium', null],
139+
['d60.v800', 484.32, 806.8, 'medium', null],
140+
['d60.v1000', 474.32, 967.4, 'medium', null],
141+
['d60.v1200', 474.32, 1179.4, 'dismissed', null],
142+
['d60.v1400', 450.99, 1306.2, 'dismissed', null],
143+
['d90.v-1400', 489.32, -1430.1, 'medium', null],
144+
['d90.v-1200', 484.32, -1213.0, 'medium', null],
145+
['d90.v-1000', 484.32, -1071.7, 'medium', null],
146+
['d90.v-800', 484.32, -924.6, 'medium', null],
147+
['d90.v-600', 489.32, -610.9, 'medium', null],
148+
['d90.v600', 479.32, 615.4, 'medium', null],
149+
['d90.v800', 497.65, 780.5, 'medium', null],
150+
['d90.v1000', 507.65, 975.6, 'medium', null],
151+
['d90.v1200', 504.32, 1177.0, 'dismissed', null],
152+
['d90.v1400', 490.99, 1443.1, 'dismissed', null],
153+
['d120.v-1400', 525.99, -1430.3, 'medium', null],
154+
['d120.v-1200', 507.65, -1164.3, 'medium', null],
155+
['d120.v-1000', 519.32, -1026.1, 'medium', null],
156+
['d120.v-800', 510.99, -807.4, 'medium', null],
157+
['d120.v-600', 519.32, -607.2, 'medium', null],
158+
['d120.v600', 502.65, 605.0, 'medium', null],
159+
['d120.v800', 484.32, 792.8, 'medium', null],
160+
['d120.v1000', 529.32, 965.5, 'medium', null],
161+
['d120.v1200', 534.32, 1177.8, 'dismissed', null],
162+
['d120.v1400', 522.65, 1408.6, 'dismissed', null],
163+
['d150.v-1200', 554.32, -1240.1, 'medium', null],
164+
['d150.v-1000', 552.65, -981.5, 'medium', null],
165+
['d150.v-800', 540.99, -794.3, 'medium', null],
166+
['d150.v-600', 537.65, -583.2, 'medium', null],
167+
['d150.v600', 537.65, 600.3, 'medium', null],
168+
['d150.v800', 537.65, 810.5, 'medium', null],
169+
['d150.v1000', 535.99, 1067.8, 'dismissed', null],
170+
['d150.v1200', 544.32, 1226.5, 'dismissed', null],
171+
['d150.v1400', 567.65, 1419.1, 'dismissed', null],
172+
['d180.v-1000', 582.65, -1063.9, 'medium', null],
173+
['d180.v-800', 570.99, -786.2, 'medium', null],
174+
['d180.v-600', 574.32, -645.2, 'medium', null],
175+
['d180.v600', 565.99, 601.9, 'medium', null],
176+
['d180.v800', 554.32, 800.5, 'medium', null],
177+
['d180.v1000', 554.32, 990.4, 'dismissed', null],
178+
['d180.v1200', 524.32, 1183.9, 'dismissed', null],
179+
['d180.v1400', 600.99, 1424.8, 'dismissed', null],
180+
];
181+
77182
const LARGE = 62;
78183
const MEDIUM = 404.32;
79184
const GONE = 874;
80-
const MEDIUM_GONE_BOUNDARY = (MEDIUM + GONE) / 2;
81-
82-
/**
83-
* The releases the rule does not reproduce, and why. The first two land on
84-
* opposite sides of the medium / dismissed boundary less than 1 pt from it
85-
* and from each other: one needs a projection time of at least 0.1145 s, the
86-
* other at most 0.1120 s, so no single value separates them (the noise of the
87-
* velocity reading). The third's last drag update read 1140 pt/s for a
88-
* 3000 pt/s injection (its siblings read ~3000): an under-read, not a rule.
89-
*/
90-
const KNOWN_MISSES: Record<string, 'boundary' | 'under-read'> = {
91-
'down.end500.v1200': 'boundary',
92-
'off200.v500': 'boundary',
93-
'off120.v3000': 'under-read',
94-
};
95185

96186
describe('resolveSheetRelease against UIKit', () => {
97-
for (const [name, offset, velocity, outcome, zeta] of UIKIT_RELEASES) {
187+
for (const [name, offset, velocity, outcome, zeta] of [
188+
...UIKIT_RELEASES,
189+
...UIKIT_FLICK_RELEASES,
190+
]) {
98191
it(`${name}: ${velocity} pt/s from ${offset} pt → ${outcome}`, () => {
99192
const release = resolveSheetRelease({
100193
detents: [LARGE, MEDIUM],
@@ -108,43 +201,14 @@ describe('resolveSheetRelease against UIKit', () => {
108201
: release.index === 0
109202
? 'large'
110203
: 'medium';
111-
const miss = KNOWN_MISSES[name];
112-
if (miss === 'boundary') {
113-
expect(landed).not.toBe(outcome);
114-
expect(Math.abs(release.projected - MEDIUM_GONE_BOUNDARY)).toBeLessThan(
115-
1,
116-
);
117-
} else if (miss === 'under-read') {
118-
expect(landed).not.toBe(outcome);
119-
} else {
120-
expect(landed).toBe(outcome);
121-
}
204+
expect(landed).toBe(outcome);
122205
if (zeta != null) {
123206
expect(release.spring).toBe(
124207
zeta === 1 ? springs.sheetDetent : springs.sheetReleaseFast,
125208
);
126209
}
127210
});
128211
}
129-
130-
it('reproduces all but the three releases it names', () => {
131-
const misses = UIKIT_RELEASES.filter(([, offset, velocity, outcome]) => {
132-
const release = resolveSheetRelease({
133-
detents: [LARGE, MEDIUM],
134-
dismissedOffset: GONE,
135-
position: offset,
136-
velocity,
137-
});
138-
const landed =
139-
release.kind === 'dismiss'
140-
? 'dismissed'
141-
: release.index === 0
142-
? 'large'
143-
: 'medium';
144-
return landed !== outcome;
145-
}).map(([name]) => name);
146-
expect(misses.sort()).toEqual(Object.keys(KNOWN_MISSES).sort());
147-
});
148212
});
149213

150214
describe('resolveSheetRelease', () => {
@@ -173,6 +237,51 @@ describe('resolveSheetRelease', () => {
173237
expect(at(471)).toBe('dismiss');
174238
});
175239

240+
it('sends a flick at least to the next position beyond it', () => {
241+
// On the 300 px detent, flicked down at the threshold: its projection
242+
// (about 400 px) is nearer 300, but a flick goes on to the next position.
243+
expect(
244+
resolveSheetRelease({
245+
detents: [0, 300],
246+
dismissedOffset: 640,
247+
position: 300,
248+
velocity: sheet.release.fastSpeed,
249+
}),
250+
).toMatchObject({kind: 'dismiss', offset: 640});
251+
// Just under the threshold, the same release projects back to 300.
252+
expect(
253+
resolveSheetRelease({
254+
detents: [0, 300],
255+
dismissedOffset: 640,
256+
position: 300,
257+
velocity: sheet.release.fastSpeed - 1,
258+
}),
259+
).toMatchObject({kind: 'detent', offset: 300});
260+
// Within the tolerance a detent counts as passed; a flick up from just
261+
// below 300 goes on to 0 instead of stopping at 300.
262+
expect(
263+
resolveSheetRelease({
264+
detents: [0, 300],
265+
dismissedOffset: 640,
266+
position: 300 + sheet.release.detentTolerance / 2,
267+
velocity: -sheet.release.fastSpeed,
268+
}),
269+
).toMatchObject({kind: 'detent', offset: 0});
270+
});
271+
272+
it('takes the projection when a flick carries farther than the next position', () => {
273+
// Flicked down at 5000 px/s from 50 px: the next position is 300, but
274+
// the projection (550 px) is nearest gone, so it dismisses.
275+
expect(
276+
resolveSheetRelease({
277+
detents: [0, 300],
278+
dismissedOffset: 640,
279+
position: 50,
280+
velocity: 5000,
281+
}),
282+
).toMatchObject({kind: 'dismiss', offset: 640});
283+
});
284+
176285
it('settles against the motion when the projection says so', () => {
177286
// Just above the shortest detent, moving up slowly: back down to it.
178287
const release = resolveSheetRelease({

‎packages/core/src/BottomSheet/sheetRelease.ts‎

Lines changed: 45 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,24 @@
99
* @position Internal to BottomSheet; pure (no DOM, no React). The rule a
1010
* drag's release follows; no gesture calls it yet.
1111
*
12-
* A released sheet goes where UISheetPresentationController sends it: to the
13-
* position nearest its release offset projected `sheet.release
14-
* .projectionSeconds` ahead at the release velocity, with the dismissed
15-
* position (the sheet fully below the screen) counting as one of the
16-
* positions. A slow release projects onto itself, so it lands on whatever is
17-
* nearest; at rest the sheet dismisses once it is more than halfway from its
18-
* shortest detent to gone. Nothing restricts the direction: a sheet released
19-
* just above a detent while moving up, but slowly, falls back to it.
12+
* A released sheet goes where UISheetPresentationController sends it. The
13+
* dismissed position (the sheet fully below the screen) counts as one of the
14+
* positions.
15+
* - Below `sheet.release.fastSpeed`, to the position nearest its release
16+
* offset projected `sheet.release.projectionSeconds` ahead at the release
17+
* velocity. A slow release projects onto itself, so it lands on whatever
18+
* is nearest; at rest the sheet dismisses once it is more than halfway
19+
* from its shortest detent to gone. Nothing restricts the direction: a
20+
* sheet released just above a detent while moving up, but slowly, falls
21+
* back to it.
22+
* - From that speed on, a flick: at least to the next position beyond where
23+
* it is, in its direction (on a position within
24+
* `sheet.release.detentTolerance`, the one after it), or to the
25+
* projection's nearest position if that is farther.
2026
*
21-
* The sheet gets there on UIKit's release spring, picked by the release speed
22-
* alone (`sheet.release.fastSpeed`), and starting at the finger's velocity.
27+
* The sheet gets there on UIKit's release spring, picked by the same speed
28+
* (critically damped below it, 80 % damped from it on), and starting at the
29+
* finger's velocity.
2330
*
2431
* Offsets are px down from the tallest detent (0 = fully open), velocities
2532
* px/s with positive meaning downward.
@@ -59,12 +66,14 @@ const PROJECTION_RATE = rateForProjection(sheet.release.projectionSeconds);
5966
*
6067
* @example
6168
* ```
62-
* // Detents at 0 (open) and 300 px; gone at 640 px. Released at 420 px
63-
* // moving down at 1200 px/s: projected 552 px, nearer gone than 300.
69+
* // Detents at 0 (open) and 300 px; gone at 640 px. Released at 300 px
70+
* // moving down at 1200 px/s: a flick, so past the 300 px detent it is on
71+
* // to the next position down, although its projection (420 px) is nearer
72+
* // 300.
6473
* resolveSheetRelease({
6574
* detents: [0, 300],
6675
* dismissedOffset: 640,
67-
* position: 420,
76+
* position: 300,
6877
* velocity: 1200,
6978
* }); // {kind: 'dismiss', offset: 640, spring: springs.sheetDismissSwipe, …}
7079
* ```
@@ -93,7 +102,27 @@ export function resolveSheetRelease({
93102
rate: PROJECTION_RATE,
94103
});
95104
const isFast = Math.abs(velocity) >= sheet.release.fastSpeed;
96-
if (dismissedOffset != null && choice.index === detents.length) {
105+
let index = choice.index;
106+
if (isFast) {
107+
// A flick goes at least to the next position beyond where it is.
108+
const tolerance = sheet.release.detentTolerance;
109+
let next = -1;
110+
if (velocity > 0) {
111+
next = positions.findIndex(p => p > position + tolerance);
112+
} else {
113+
for (let i = positions.length - 1; i >= 0 && next === -1; i -= 1) {
114+
if (positions[i] < position - tolerance) {
115+
next = i;
116+
}
117+
}
118+
}
119+
if (next !== -1 && (velocity > 0 ? next > index : next < index)) {
120+
index = next;
121+
}
122+
}
123+
if (dismissedOffset != null && index === detents.length) {
124+
// A slow dismissal's spring is a stand-in: none of the measured releases
125+
// that dismissed recorded a spring, so `springs.sheetDetent` is used.
97126
return {
98127
kind: 'dismiss',
99128
index: -1,
@@ -104,8 +133,8 @@ export function resolveSheetRelease({
104133
}
105134
return {
106135
kind: 'detent',
107-
index: choice.index,
108-
offset: choice.value,
136+
index,
137+
offset: positions[index],
109138
projected: choice.projected,
110139
spring: isFast ? springs.sheetReleaseFast : springs.sheetDetent,
111140
};

‎packages/core/src/motion/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ from the package entry point; components import it by path.
1717
| `uikit/timing.ts` | Non-spring clocks and curves: press highlight, Core Animation's named curves, keyboard, Reduced Motion cross-fade. |
1818
| `uikit/navigation.ts` | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule. |
1919
| `uikit/gestures.ts` | Gesture recognizer thresholds, the velocity filter and the haptic stand-ins, as typed entries the gesture system reads. |
20-
| `uikit/sheet.ts` | UISheetPresentationController: the release projection and the speed that picks the release spring. |
20+
| `uikit/sheet.ts` | UISheetPresentationController: the release projection, and the speed from which a release is a flick on the faster spring. |
2121
| `roles.ts` | Motion roles: each spring, duration and curve of a registered table, named by its path, and its CSS variable. |
2222
| `resolveMotion.ts` | A role's value under an element's theme, read once when a motion starts. |
2323
| `MEASUREMENTS.md` | The UIKit reference captures each unconfirmed value still needs. |

0 commit comments

Comments
 (0)