An open source design system that's fully customizable and agent ready
TypeScript
feat(core): UIScrollView zoom constants and the zoom stage geometry (#8147)
Christopher Chedeau09a9bf337c20
diff --git a/.changeset/uikit-zoom-media.md b/.changeset/uikit-zoom-media.mdnew file mode 100644index 0000000000..56a1344254--- /dev/null+++ b/.changeset/uikit-zoom-media.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[chore] Internal: the UIKit constants table gains UIScrollView zooming for a photo viewer, measured on iOS 26.2. It holds the give past the zoom limits and Photos' aspect-fill double tap and maximum zoom. The zoom stage geometry that Lightbox's touch zoom is built on comes with it. Neither is exported from the package entry point, and no component reads them yet.++@vjeuxdiff --git a/packages/core/src/Lightbox/zoomStage.test.ts b/packages/core/src/Lightbox/zoomStage.test.tsnew file mode 100644index 0000000000..e1f71360b8--- /dev/null+++ b/packages/core/src/Lightbox/zoomStage.test.ts@@ -0,0 +1,316 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file zoomStage.test.ts+ * @input vitest, the zoom stage geometry and the UIKit zoom constants+ * @output Checks the zoom stage against UIKit's measured zooming and+ * Lightbox's double tap. It covers the overshoot, the maximum zoom, the+ * point kept in place, resting places, a drag's rubber band and a resize+ * @position Testing; zoomStage.ts without a browser+ */++import {describe, expect, it} from 'vitest';+import {rubberBand} from '../motion/rubberBand';+import {+ IDENTITY,+ ZOOM_STEP,+ doubleTapScaleFor,+ doubleTapTarget,+ draggedTransform,+ isZoomed,+ maxScaleFor,+ overshootScale,+ pannedBy,+ pinchScaleFor,+ rawForDragged,+ releaseTarget,+ restRange,+ restingTransform,+ transformForResize,+ transformKeepingPoint,+ type ZoomGeometry,+ type ZoomTransform,+} from './zoomStage';++/**+ * The lab's stage: a 402 × 874 screen showing a 3000 × 2000 photo fitted+ * 402 × 268 at its vertical centre, on a 3× screen.+ */+function landscape(overrides: Partial<ZoomGeometry> = {}): ZoomGeometry {+ const width = 402;+ const height = 874;+ const fit = {x: 0, y: (874 - 268) / 2, width: 402, height: 268};+ const doubleTapScale = doubleTapScaleFor(width, height, 402, 268);+ return {+ width,+ height,+ fit,+ minScale: 1,+ maxScale: maxScaleFor(3000, 402, 3, doubleTapScale),+ doubleTapScale,+ ...overrides,+ };+}++/** Where the photo point (u, v) of the fitted box shows on the stage. */+function shown(+ geometry: ZoomGeometry,+ transform: ZoomTransform,+ u: number,+ v: number,+) {+ return {+ x: geometry.fit.x + transform.x + u * transform.scale,+ y: geometry.fit.y + transform.y + v * transform.scale,+ };+}++describe('the overshoot past the zoom limits (UIKit lab, iOS 26.2)', () => {+ const geometry = landscape({minScale: 1, maxScale: 4});++ it('follows the pinch 1:1 inside the limits', () => {+ for (const scale of [1, 1.5, 2.25, 4]) {+ expect(overshootScale(geometry, scale)).toBe(scale);+ }+ });++ it('gives way past the maximum as measured', () => {+ // Pinch 4.5 / 5 / 5.5 / 6 past a maximum of 4.+ const measured = [+ [4.5, 4.444],+ [5, 4.8],+ [5.5, 5.091],+ [6, 5.333],+ ];+ for (const [pinch, zoom] of measured) {+ expect(overshootScale(geometry, pinch)).toBeCloseTo(zoom, 3);+ }+ });++ it('gives way past the minimum as measured', () => {+ const measured = [+ [0.85, 0.87],+ [0.7, 0.769],+ [0.474, 0.655],+ [0.323, 0.596],+ ];+ for (const [pinch, zoom] of measured) {+ expect(overshootScale(geometry, pinch)).toBeCloseTo(zoom, 3);+ }+ });++ it('never reaches twice the maximum or half the minimum', () => {+ expect(overshootScale(geometry, 1e6)).toBeLessThan(8);+ expect(overshootScale(geometry, 1e-6)).toBeGreaterThan(0.5);+ });++ it('inverts, so a pinch can continue from a photo already past a limit', () => {+ for (const pinch of [0.3, 0.6, 0.95, 1, 2, 4, 4.4, 7, 20]) {+ expect(+ pinchScaleFor(geometry, overshootScale(geometry, pinch)),+ ).toBeCloseTo(pinch, 9);+ }+ });+});++describe('the double tap: the larger of filling the stage and 2×, about the tapped point', () => {+ it('zooms until the photo fills the screen when that is more than 2×', () => {+ // Photos' aspect fill: landscape 402 × 268 on an 874 pt screen → 3.261.+ expect(doubleTapScaleFor(402, 874, 402, 268)).toBeCloseTo(3.261, 3);+ });++ it('zooms 2× when filling the screen takes less', () => {+ // A portrait 402 × 603 fills the screen at 1.449×, below the zoom step.+ expect(ZOOM_STEP).toBe(2);+ expect(doubleTapScaleFor(402, 874, 402, 603)).toBe(2);+ expect(doubleTapScaleFor(400, 300, 400, 300)).toBe(2);+ });++ it('keeps a centre tap at the centre, and the photo fills the screen', () => {+ const geometry = landscape();+ const target = doubleTapTarget(geometry, IDENTITY, {x: 201, y: 437});+ expect(target.scale).toBeCloseTo(874 / 268, 9);+ const centre = shown(geometry, target, 201, 134);+ expect(centre.x).toBeCloseTo(201, 9);+ expect(centre.y).toBeCloseTo(437, 9);+ expect(geometry.fit.y + target.y).toBeCloseTo(0, 9);+ });++ it('keeps an off-centre tap where it lands', () => {+ const geometry = landscape();+ // A third of the way across the photo: that point stays under the tap.+ const target = doubleTapTarget(geometry, IDENTITY, {x: 134, y: 437});+ expect(shown(geometry, target, 134, 134).x).toBeCloseTo(134, 9);+ });++ it('stops at the edge for a tap near it', () => {+ // A portrait photo 2000 × 3000, fitted 402 × 603, zooms 2×.+ const fit = {x: 0, y: (874 - 603) / 2, width: 402, height: 603};+ const geometry = landscape({+ fit,+ doubleTapScale: doubleTapScaleFor(402, 874, 402, 603),+ });+ const target = doubleTapTarget(geometry, IDENTITY, {x: 201, y: 700});+ expect(target.scale).toBe(2);+ // The photo's bottom edge rests on the screen's bottom edge.+ expect(fit.y + target.y + fit.height * 2).toBeCloseTo(874, 9);+ });++ it('returns to the fitted size when zoomed', () => {+ const geometry = landscape();+ const zoomed = doubleTapTarget(geometry, IDENTITY, {x: 201, y: 437});+ expect(isZoomed(geometry, zoomed)).toBe(true);+ expect(doubleTapTarget(geometry, zoomed, {x: 50, y: 50})).toEqual(IDENTITY);+ });+});++describe("Photos' maximum zoom (iOS 26.2)", () => {+ it('allows 6 times the zoom that shows one image pixel per device pixel', () => {+ // Measured: 14.93 for 3000 × 2000 and 9.95 for 2000 × 3000, fitted 402 pt+ // wide at 3×.+ expect(maxScaleFor(3000, 402, 3, 3.261)).toBeCloseTo(14.93, 2);+ expect(maxScaleFor(2000, 402, 3, 2)).toBeCloseTo(9.95, 2);+ // Never below the double tap's zoom.+ expect(maxScaleFor(200, 402, 3, 3.261)).toBe(3.261);+ });+});++describe('the point under the fingers', () => {+ it('stays under the centroid as it moves and the zoom changes', () => {+ const geometry = landscape();+ const start: ZoomTransform = {x: -300, y: -100, scale: 2.5};+ const anchor = {x: 150, y: 400};+ const u = (anchor.x - geometry.fit.x - start.x) / start.scale;+ const v = (anchor.y - geometry.fit.y - start.y) / start.scale;+ const centroid = {x: 190, y: 360};+ const next = transformKeepingPoint(geometry, start, anchor, centroid, 4.2);+ const point = shown(geometry, next, u, v);+ expect(point.x).toBeCloseTo(centroid.x, 9);+ expect(point.y).toBeCloseTo(centroid.y, 9);+ expect(next.scale).toBe(4.2);+ });++ it('settles a release past the maximum about the last centroid', () => {+ const geometry = landscape({maxScale: 4});+ const centroid = {x: 220, y: 430};+ // Released at 5.333 with the content point under the centroid at u, v.+ const released: ZoomTransform = {x: -700, y: -500, scale: 5.333};+ const target = releaseTarget(geometry, released, centroid);+ expect(target.scale).toBe(4);+ const u = (centroid.x - geometry.fit.x - released.x) / released.scale;+ const v = (centroid.y - geometry.fit.y - released.y) / released.scale;+ const point = shown(geometry, target, u, v);+ expect(point.x).toBeCloseTo(centroid.x, 9);+ expect(point.y).toBeCloseTo(centroid.y, 9);+ });++ it('keeps a release inside the limits where it is', () => {+ const geometry = landscape();+ const released: ZoomTransform = {x: -100, y: -50, scale: 2};+ expect(releaseTarget(geometry, released, {x: 0, y: 0})).toBe(released);+ });++ it('settles a release past the minimum to the fitted size, centred', () => {+ const geometry = landscape();+ const released: ZoomTransform = {x: 40, y: 30, scale: 0.6};+ expect(releaseTarget(geometry, released, {x: 180, y: 420})).toEqual(+ IDENTITY,+ );+ });+});++describe('the resting place', () => {+ it('centres the photo on an axis where it is smaller than the stage', () => {+ const geometry = landscape();+ // 2× is 804 × 536: wider than the screen, shorter than it.+ const range = restRange(geometry, 2);+ expect(range.x).toEqual({min: 402 - 804, max: 0});+ expect(range.y.min).toBe(range.y.max);+ expect(geometry.fit.y + range.y.min + 536 / 2).toBeCloseTo(874 / 2, 9);+ });++ it('keeps a zoomed photo with no gap at either edge', () => {+ const geometry = landscape();+ expect(restingTransform(geometry, {x: 50, y: 0, scale: 2}).x).toBe(0);+ expect(restingTransform(geometry, {x: -900, y: 0, scale: 2}).x).toBe(+ 402 - 804,+ );+ });++ it('pans by keyboard steps inside those bounds', () => {+ const geometry = landscape();+ const from: ZoomTransform = {+ x: -10,+ y: restRange(geometry, 2).y.min,+ scale: 2,+ };+ expect(pannedBy(geometry, from, 50, 0).x).toBe(0);+ expect(pannedBy(geometry, from, -50, 0).x).toBe(-60);+ expect(pannedBy(geometry, from, 0, 50).y).toBe(from.y);+ });+});++describe('the rubber band of a drag', () => {+ const geometry = landscape();++ it('follows the finger inside the bounds', () => {+ const raw: ZoomTransform = {x: -200, y: 0, scale: 2};+ expect(draggedTransform(geometry, raw).x).toBe(-200);+ });++ it("gives way past an edge with UIScrollView's rubber band over the stage width", () => {+ const raw: ZoomTransform = {x: 120, y: 0, scale: 2};+ expect(draggedTransform(geometry, raw).x).toBeCloseTo(+ rubberBand(120, 402, 0.55),+ 9,+ );+ const far: ZoomTransform = {x: 402 - 804 - 300, y: 0, scale: 2};+ expect(draggedTransform(geometry, far).x).toBeCloseTo(+ 402 - 804 + rubberBand(-300, 402, 0.55),+ 9,+ );+ });++ it('does not move the photo on an axis where it fits', () => {+ const raw: ZoomTransform = {x: -200, y: 500, scale: 2};+ expect(draggedTransform(geometry, raw).y).toBe(+ restRange(geometry, 2).y.min,+ );+ });++ it('inverts, so a finger landing on a banded photo picks it up where it shows', () => {+ const raw: ZoomTransform = {x: 150, y: 0, scale: 2};+ const banded = draggedTransform(geometry, raw);+ expect(rawForDragged(geometry, banded).x).toBeCloseTo(150, 9);+ });+});++describe('a resize while zoomed (rotation)', () => {+ it('keeps the photo point at the centre and its size on screen', () => {+ const before = landscape();+ const transform: ZoomTransform = {x: -500, y: -150, scale: 3};+ const u = (201 - before.fit.x - transform.x) / transform.scale / 402;+ const v = (437 - before.fit.y - transform.y) / transform.scale / 268;+ // Landscape orientation: 874 × 402, the photo fitted 603 × 402.+ const after: ZoomGeometry = {+ width: 874,+ height: 402,+ fit: {x: (874 - 603) / 2, y: 0, width: 603, height: 402},+ minScale: 1,+ maxScale: maxScaleFor(3000, 603, 3, 874 / 603),+ doubleTapScale: 874 / 603,+ };+ const next = transformForResize(before, after, transform);+ // The same on-screen size: 402 × 3 = 1206 px wide either way.+ expect(603 * next.scale).toBeCloseTo(402 * 3, 9);+ const centre = shown(after, next, u * 603, v * 402);+ expect(centre.x).toBeCloseTo(437, 6);+ expect(centre.y).toBeCloseTo(201, 6);+ });++ it('stays at the fitted size when not zoomed', () => {+ const before = landscape();+ const after = landscape({width: 500});+ expect(transformForResize(before, after, IDENTITY)).toEqual(IDENTITY);+ });+});diff --git a/packages/core/src/Lightbox/zoomStage.ts b/packages/core/src/Lightbox/zoomStage.tsnew file mode 100644index 0000000000..4e23831d41--- /dev/null+++ b/packages/core/src/Lightbox/zoomStage.ts@@ -0,0 +1,358 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file zoomStage.ts+ * @input The stage's size, the photo's fitted box and pixel size, a+ * transform (offset from the fitted box, and scale), and finger positions+ * @output The zoom stage's pure geometry: zoom limits, resting places, a+ * drag's rubber band and a pinch's overshoot. Also the transform that keeps+ * a point in place+ * @position Pure math for Lightbox's touch zoom. No DOM and no React.+ *+ * The model is a zooming UIScrollView in a photo viewer. Its constants come+ * from motion/uikit/zoomMedia.ts and motion/uikit/scroll.ts.+ * SYNC: When modified, update zoomStage.test.ts.+ */++import {rubberBandClamp, rubberBandUnclamp} from '../motion/rubberBand';+import {zoomMedia} from '../motion/uikit/zoomMedia';++export interface StagePoint {+ readonly x: number;+ readonly y: number;+}++/**+ * Scales the fitted box about its top-left corner and moves it by (x, y). A+ * photo point at (u, v) in the fitted box shows at (fit.x + x + u·scale,+ * fit.y + y + v·scale).+ */+export interface ZoomTransform {+ /** Offset of the photo's box from its fitted place, px. */+ readonly x: number;+ readonly y: number;+ /** Scale relative to the fitted size. */+ readonly scale: number;+}++export interface ZoomGeometry {+ /** The stage's size, px. */+ readonly width: number;+ readonly height: number;+ /** The photo's box at the fitted size, in stage coordinates. */+ readonly fit: {+ readonly x: number;+ readonly y: number;+ readonly width: number;+ readonly height: number;+ };+ readonly minScale: number;+ readonly maxScale: number;+ /** The zoom a double tap goes to from the fitted size. */+ readonly doubleTapScale: number;+}++export const IDENTITY: ZoomTransform = {x: 0, y: 0, scale: 1};++/** Within this of the fitted size the photo counts as not zoomed. */+export const ZOOMED_EPSILON = 0.001;++/** Lightbox's zoom step: a double tap zooms at least this many times. */+export const ZOOM_STEP = 2;++/**+ * The zoom a double tap goes to from the fitted size. It is the larger of+ * filling the stage and `ZOOM_STEP`, for a stage of `width` × `height` and a+ * photo fitted at `fitWidth` × `fitHeight`. Photos zooms to the fill alone,+ * so Lightbox departs from it on a photo that fills at less than `ZOOM_STEP`.+ */+export function doubleTapScaleFor(+ width: number,+ height: number,+ fitWidth: number,+ fitHeight: number,+): number {+ if (!(fitWidth > 0) || !(fitHeight > 0)) {+ return ZOOM_STEP;+ }+ return Math.max(ZOOM_STEP, width / fitWidth, height / fitHeight);+}++/**+ * The largest zoom for a photo `naturalWidth` image pixels wide, fitted+ * `fitWidth` CSS px wide on a screen of `devicePixelRatio`. It is Photos'+ * multiple of the zoom that shows one image pixel per device pixel. It is+ * never less than `doubleTapScale`, so a double tap lands inside the limits.+ */+export function maxScaleFor(+ naturalWidth: number,+ fitWidth: number,+ devicePixelRatio: number,+ doubleTapScale: number,+): number {+ const {maxPixelZoomMultiple} = zoomMedia.viewer;+ if (!(fitWidth > 0) || !(naturalWidth > 0) || !(devicePixelRatio > 0)) {+ return doubleTapScale;+ }+ const pixelScale = naturalWidth / (fitWidth * devicePixelRatio);+ return Math.max(doubleTapScale, maxPixelZoomMultiple * pixelScale);+}++/** Whether `transform` shows the photo larger than fitted. */+export function isZoomed(+ geometry: ZoomGeometry,+ transform: ZoomTransform,+): boolean {+ return transform.scale > geometry.minScale + ZOOMED_EPSILON;+}++interface AxisRange {+ readonly min: number;+ readonly max: number;+}++function axisRange(+ stageSize: number,+ fitStart: number,+ fitSize: number,+ scale: number,+): AxisRange {+ const size = fitSize * scale;+ if (size <= stageSize) {+ const centred = (stageSize - size) / 2 - fitStart;+ return {min: centred, max: centred};+ }+ // `0 - fitStart`, not `-fitStart`: no negative zero in the style.+ return {min: stageSize - size - fitStart, max: 0 - fitStart};+}++/**+ * Where the photo may rest at `scale`: the offset range on each axis. On an+ * axis where the scaled photo is smaller than the stage, it rests centred, as+ * in every UIKit photo viewer. Where it is larger, it rests with no gap at+ * either edge.+ */+export function restRange(+ geometry: ZoomGeometry,+ scale: number,+): {readonly x: AxisRange; readonly y: AxisRange} {+ const {fit} = geometry;+ return {+ x: axisRange(geometry.width, fit.x, fit.width, scale),+ y: axisRange(geometry.height, fit.y, fit.height, scale),+ };+}++/** The resting transform nearest to `transform`, at its scale. */+export function restingTransform(+ geometry: ZoomGeometry,+ transform: ZoomTransform,+): ZoomTransform {+ const range = restRange(geometry, transform.scale);+ return {+ x: Math.min(range.x.max, Math.max(range.x.min, transform.x)),+ y: Math.min(range.y.max, Math.max(range.y.min, transform.y)),+ scale: transform.scale,+ };+}++/**+ * The scale a pinch shows for its own scale `scale`: 1:1 inside the+ * limits, giving way past them (`zoomMedia.overshoot.limitFactor`).+ */+export function overshootScale(geometry: ZoomGeometry, scale: number): number {+ const f = zoomMedia.overshoot.limitFactor;+ const {minScale: m, maxScale: M} = geometry;+ if (scale > M) {+ return M * (f - ((f - 1) * M) / scale);+ }+ if (scale < m) {+ return m / (f - ((f - 1) * scale) / m);+ }+ return scale;+}++/**+ * The pinch's own scale that shows `shown`: the inverse of+ * `overshootScale`, to continue a pinch from a photo already past a limit.+ */+export function pinchScaleFor(geometry: ZoomGeometry, shown: number): number {+ const f = zoomMedia.overshoot.limitFactor;+ const {minScale: m, maxScale: M} = geometry;+ if (shown > M) {+ // shown = M·(f − (f − 1)·M ÷ s) ⇒ s = (f − 1)·M² ÷ (f·M − shown)+ const gap = f * M - shown;+ return gap > 0 ? ((f - 1) * M * M) / gap : Number.POSITIVE_INFINITY;+ }+ if (shown < m) {+ // shown = m ÷ (f − (f − 1)·s ÷ m) ⇒ s = (f − m ÷ shown)·m ÷ (f − 1)+ return Math.max(0, ((f - m / shown) * m) / (f - 1));+ }+ return shown;+}++/**+ * The transform at `scale` that shows the photo point under `anchor` (as+ * placed by `from`) under `point`. A pinch keeps the point under its first+ * centroid under the current centroid. A double tap and a settle past a limit+ * keep the point where it is (`point` = `anchor`).+ */+export function transformKeepingPoint(+ geometry: ZoomGeometry,+ from: ZoomTransform,+ anchor: StagePoint,+ point: StagePoint,+ scale: number,+): ZoomTransform {+ const {fit} = geometry;+ // The fitted-box point under `anchor`.+ const u = (anchor.x - fit.x - from.x) / from.scale;+ const v = (anchor.y - fit.y - from.y) / from.scale;+ return {+ x: point.x - fit.x - u * scale,+ y: point.y - fit.y - v * scale,+ scale,+ };+}++/**+ * Where a drag shows the photo: `raw` is where the finger's travel would put+ * it with no edges. Past an edge it gives way with UIScrollView's rubber band+ * over the stage's size on that axis. On an axis where the photo is smaller+ * than the stage, it stays centred, as a scroll view whose content fits does+ * not bounce.+ */+export function draggedTransform(+ geometry: ZoomGeometry,+ raw: ZoomTransform,+): ZoomTransform {+ const range = restRange(geometry, raw.scale);+ return {+ x:+ range.x.min === range.x.max+ ? range.x.min+ : rubberBandClamp(raw.x, range.x.min, range.x.max, geometry.width),+ y:+ range.y.min === range.y.max+ ? range.y.min+ : rubberBandClamp(raw.y, range.y.min, range.y.max, geometry.height),+ scale: raw.scale,+ };+}++/** The finger-travel position behind a shown one: `draggedTransform` undone. */+export function rawForDragged(+ geometry: ZoomGeometry,+ shown: ZoomTransform,+): ZoomTransform {+ const range = restRange(geometry, shown.scale);+ return {+ x:+ range.x.min === range.x.max+ ? shown.x+ : rubberBandUnclamp(shown.x, range.x.min, range.x.max, geometry.width),+ y:+ range.y.min === range.y.max+ ? shown.y+ : rubberBandUnclamp(shown.y, range.y.min, range.y.max, geometry.height),+ scale: shown.scale,+ };+}++/**+ * The resting transform a double tap at `point` goes to from `from`. From+ * the fitted size it zooms to `geometry.doubleTapScale` about the tapped+ * point, kept inside the stage. Photos brings the tapped point to the centre+ * instead. When zoomed, it goes back to the fitted size.+ */+export function doubleTapTarget(+ geometry: ZoomGeometry,+ from: ZoomTransform,+ point: StagePoint,+): ZoomTransform {+ if (isZoomed(geometry, from)) {+ return restingTransform(geometry, {...IDENTITY, scale: geometry.minScale});+ }+ const scale = Math.min(+ geometry.maxScale,+ Math.max(geometry.minScale, geometry.doubleTapScale),+ );+ return restingTransform(+ geometry,+ transformKeepingPoint(geometry, from, point, point, scale),+ );+}++/**+ * The resting transform a release goes to. Inside the limits it is `shown`+ * itself, since a drag's coast settles any edge. Past a limit it is the limit,+ * with the point under the last centroid kept in place and the photo kept+ * inside the stage.+ */+export function releaseTarget(+ geometry: ZoomGeometry,+ shown: ZoomTransform,+ centroid: StagePoint,+): ZoomTransform {+ const limit = Math.min(+ geometry.maxScale,+ Math.max(geometry.minScale, shown.scale),+ );+ if (limit === shown.scale) {+ return shown;+ }+ return restingTransform(+ geometry,+ transformKeepingPoint(geometry, shown, centroid, centroid, limit),+ );+}++/** The resting transform after panning by (dx, dy): a keyboard step. */+export function pannedBy(+ geometry: ZoomGeometry,+ from: ZoomTransform,+ dx: number,+ dy: number,+): ZoomTransform {+ return restingTransform(geometry, {+ x: from.x + dx,+ y: from.y + dy,+ scale: from.scale,+ });+}++/**+ * The transform that shows the same photo after the stage resizes, as on a+ * rotation. The photo point at the stage's centre stays at its centre. The+ * photo keeps its size on screen, so the zoom relative to the fitted size+ * changes with the fitted size. The result is within the new limits, at rest.+ */+export function transformForResize(+ before: ZoomGeometry,+ after: ZoomGeometry,+ transform: ZoomTransform,+): ZoomTransform {+ if (!isZoomed(before, transform)) {+ return {...IDENTITY, scale: after.minScale};+ }+ const ratio = after.fit.width > 0 ? before.fit.width / after.fit.width : 1;+ const scale = Math.min(+ after.maxScale,+ Math.max(after.minScale, transform.scale * ratio),+ );+ // The photo point (in fitted-box px of `before`) at the old centre, then+ // the same point in the new fitted box.+ const u =+ (before.width / 2 - before.fit.x - transform.x) /+ transform.scale /+ before.fit.width;+ const v =+ (before.height / 2 - before.fit.y - transform.y) /+ transform.scale /+ before.fit.height;+ return restingTransform(after, {+ x: after.width / 2 - after.fit.x - u * after.fit.width * scale,+ y: after.height / 2 - after.fit.y - v * after.fit.height * scale,+ scale,+ });+}diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.mdindex c5a9677b58..9e7538d4fa 100644--- a/packages/core/src/motion/MEASUREMENTS.md+++ b/packages/core/src/motion/MEASUREMENTS.md@@ -325,3 +325,20 @@ display-link and feedback hooks; real HID touches.| ID | Scene | Gesture | Extract | Method || ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------ || M-MN2 | button on a plain view | hold until the menu is open, then lift still; move 8 pt down, 8 pt right, 12 pt down, (7, 7), (8, 8) and lift; move 6 pt before the open and 6 pt after | row picked or not; handoff and list-selection recognizer states; highlighted row per frame: threshold, metric, where it is counted from | C |++## Zoom media (UIScrollView zooming, Photos)++Values Lightbox's zoom stage reads (`uikit/zoomMedia.ts`). Done (UIKit lab and+Photos, iOS 26.2 simulator, Oct 23 2026; tagged `measured:`): the overshoot+past the limits, the absence of scale momentum and of a two-finger-tap action,+the content point under the centroid staying put, Photos' aspect-fill double+tap and its maximum zoom on 3000 × 2000 and 2000 × 3000 photos. M-ZM2 confirms+that maximum on two other sizes. A zoomed pan flicked into an edge coasts and+bounces like any scroll view (`scroll.*`). UIKit settles a zoom on an eased+curve whose length grows with the zoom ratio (100 ms plus 300 ms per unit of+its log, at most 400 ms). Lightbox's zoom settles on `springs.settle` instead,+since its main interaction is a gesture (`spec:AST-094` FR45).++| ID | What | App and gesture | Extract | Method |+| ----- | ------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------ |+| M-ZM2 | Maximum zoom | Photos: pinch a 4032 × 3024 and a 1200 × 800 photo as far as it goes | the zoom it settles on against the photo's pixel size and the fitted size | B, C |diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.mdindex c0882d0dc1..5175eef4b9 100644--- a/packages/core/src/motion/README.md+++ b/packages/core/src/motion/README.md@@ -28,6 +28,7 @@ roles through `resolveMotion`.| `uikit/switch.ts` | UISwitch on iOS 26.2: geometry, the lift, settle, travel and tracking springs, the flip distance, the track colour. || `uikit/datePicker.ts` | UIDatePicker: the rules it adds to its wheels. || `android/keyboard.ts` | Android's software keyboard (Chrome with Gboard): its slides' durations and curves (no theme's) and when they start against Chrome's report and a blur. |+| `uikit/zoomMedia.ts` | UIScrollView zooming for a photo viewer: overshoot past the limits, double-tap and maximum zoom. || `roles.ts` | The internal motion roles: the springs, durations and curves `spec:AST-094` FR4 names, registered by the shared tables, and a role's CSS form read back. || `roleValue.ts` | A role's CSS form, written: a spring's duration and bounce, a duration in ms, a curve's `cubic-bezier()`. || `resolveMotion.ts` | A role's value: its table value, as the per-role tables stay internal (`spec:AST-094` DEC-15). |diff --git a/packages/core/src/motion/uikit/index.ts b/packages/core/src/motion/uikit/index.tsindex 0ea81c759f..477b9d0251 100644--- a/packages/core/src/motion/uikit/index.ts+++ b/packages/core/src/motion/uikit/index.ts@@ -3,11 +3,12 @@/*** @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`, `picker`, `progressBar`,- * `segmentedControl`, `datePicker`, `slider` and `switchControl`. It also- * re-exports the gesture thresholds: one `UIKIT_*` group per recognizer,- * their union `UIKIT_GESTURES`, and the haptic tables+ * @output Re-exports `springs` and one constant per spring+ * (`SHEET_PRESENT_SPRING`, …), and the `scroll`, `timing`, `navigation`,+ * `picker`, `progressBar`, `segmentedControl`, `datePicker`, `slider`,+ * `switchControl` and `zoomMedia` domains. It also re-exports 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* core: not exported from the package entry point*@@ -85,3 +86,4 @@ export {} from './springs';export {switchControl} from './switch';export {registerTimingTable, timing} from './timing';+export {zoomMedia} from './zoomMedia';diff --git a/packages/core/src/motion/uikit/zoomMedia.ts b/packages/core/src/motion/uikit/zoomMedia.tsnew file mode 100644index 0000000000..fdefa6bf08--- /dev/null+++ b/packages/core/src/motion/uikit/zoomMedia.ts@@ -0,0 +1,73 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file zoomMedia.ts+ * @input Nothing; data only+ * @output Exports `zoomMedia`: UIScrollView zooming in a photo viewer. That+ * is the give past the zoom limits, and Photos' double tap and maximum zoom+ * @position A domain of the UIKit constants table (motion/uikit). Lightbox's+ * zoom stage reads it+ *+ * SYNC: When modified, update /packages/core/src/motion/MEASUREMENTS.md+ */++/**+ * UIScrollView zooming as a photo viewer uses it, with Photos' double tap+ * and maximum zoom. Re-exported from motion/uikit, inside core.+ *+ * Measured on the iOS 26.2 simulator (iPhone 17 Pro, 402 × 874 pt at 3×).+ * The lab was a UIKit host app with a full-screen UIScrollView zooming one+ * image view (minimum zoom = fit, maximum 4, bouncesZoom on). Photos was+ * measured on 3000 × 2000 and 2000 × 3000 photos. Real HID touches drove+ * both, and every `CAAnimation`, zoomScale and contentOffset was logged.+ *+ * Findings with no number: inside the limits, the zoom equals the pinch's+ * scale 1:1. The content point under the fingers' centroid stays under it+ * (within 1 pt), past the limits too. A pinch released inside the limits+ * keeps no scale momentum. A two-finger tap does nothing. The double tap+ * fires on the second lift, with no wait.+ *+ * Every leaf carries one or more `@source`. WebKit and GUESS values also+ * carry the `@measure` task that will confirm or replace them, and+ * uikit.test.ts enforces both.+ */+export const zoomMedia = {+ overshoot: {+ /**+ * Past a zoom limit the zoom gives way. Past the maximum M it reads+ * M·(f − (f − 1)·M ÷ s). Past the minimum m it reads+ * m ÷ (f − (f − 1)·s ÷ m), where s is the pinch's own scale. With f = 2,+ * the zoom leaves the limit at the pinch's pace and approaches f times the+ * limit (2M, m ÷ 2). Pinches of 4.5, 5, 5.5 and 6 past a maximum of 4 read+ * 4.444, 4.8, 5.091 and 5.333. Pinches of 0.85, 0.7, 0.474 and 0.323 past+ * a minimum of 1 read 0.870, 0.769, 0.655 and 0.596.+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,+ * iPhone 17 Pro, zoomScale against the pinch recognizer's scale per+ * event, Oct 23 2026+ */+ limitFactor: 2,+ },+ viewer: {+ /**+ * In Photos, a double tap at the fitted size zooms until the photo fills+ * the stage (aspect fill). A 402 × 268 landscape photo on the 874 pt tall+ * screen zooms 3.261×, and a 402 × 603 portrait 1.449×. Photos brings the+ * tapped point to the centre, kept inside the stage. A double tap while+ * zoomed returns to the fitted size. Both run UIKit's zoom settle.+ * @source measured: Photos, iOS 26.2 simulator, iPhone 17 Pro,+ * zoomScale and contentOffset per frame after double taps at the+ * centre and near the edge of 3000 × 2000 and 2000 × 3000 photos,+ * Oct 23 2026+ */+ doubleTapZoom: 'aspectFill',+ /**+ * The maximum zoom is this many times the zoom at which one image pixel+ * covers one device pixel. That gives 14.93 for a 3000 × 2000 photo fitted+ * 402 pt wide at 3×, and 9.95 for 2000 × 3000.+ * @source measured: Photos, iOS 26.2 simulator, iPhone 17 Pro, the+ * zoomScale a pinch settles on past the maximum, 3000 × 2000 and+ * 2000 × 3000 photos, Oct 23 2026+ */+ maxPixelZoomMultiple: 6,+ },+} as const;