fix(ui): drive the image preview through flight and zoom state machines (#61951)

This commit is contained in:
Luke Parker
2026-11-05 00:00:54 -06:00
committed by GitHub
Unverified
parent 75e5879d90
commit 0280763488
9 changed files with 1281 additions and 283 deletions
@@ -25,6 +25,79 @@ story("takes the page's clicks as soon as the image preview closes mid-flight",
await expect(clickPage(page)).resolves.toBe(true)
})
story("a close mid-flight after the origin is gone fades out without landing at rest", async ({ mount, page }) => {
await mount("components-image-preview--from-message")
await open(page)
const preview = page.locator('[data-component="image-preview"]')
await preview.waitFor({ state: "attached" })
// In the page, so the close lands mid-flight however slow the runner: the origin goes the moment the flight starts,
// and Escape follows. Every stage the preview shows from then on is recorded.
const stages = await preview.evaluateHandle((element: HTMLElement) => {
const seen: (string | undefined)[] = []
let closed = false
const close = () => {
if (closed || element.dataset.stage === "pending") return
closed = true
document.querySelector('[data-story-image="inline"]')?.remove()
document.activeElement?.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }))
}
new MutationObserver(() => {
if (closed) seen.push(element.dataset.stage)
close()
}).observe(element, { attributes: true, attributeFilter: ["data-stage"] })
close()
return seen
})
await expect(preview).toHaveCount(0)
const seen = await stages.jsonValue()
expect(seen).toContain("closing")
expect(seen).not.toContain("rest")
})
story("a pan whose release never reaches the preview stops following the pointer", async ({ mount, page }) => {
await mount("components-image-preview--from-message")
await open(page)
const body = page.locator('[data-slot="image-preview-body"]')
const image = page.locator('[data-slot="image-preview-image"]')
await expect(page.locator('[data-component="image-preview"]')).toHaveAttribute("data-stage", "rest")
await image.dblclick()
await expect(body).toHaveAttribute("data-zoomed", "")
const box = await body.boundingBox()
if (!box) throw new Error("the preview body is not laid out")
const x = box.x + box.width / 2
const y = box.y + box.height / 2
const pointer = await body.evaluateHandle((element: HTMLElement) => {
const seen = { id: -1 }
element.addEventListener("pointerdown", (event) => (seen.id = event.pointerId), { once: true })
return seen
})
await page.mouse.move(x, y)
await page.mouse.down()
await page.mouse.move(x + 30, y + 10)
await expect(body).toHaveAttribute("data-dragging", "")
// The pointer loses capture, as when the window loses focus mid-drag, and the button comes up outside the body.
await body.evaluate((element, seen) => element.releasePointerCapture(seen.id), pointer)
await page.mouse.move(x, box.y / 2)
await page.mouse.up()
const transform = await image.evaluate((element) => element.style.transform)
await page.mouse.move(x, y)
await page.mouse.move(x - 60, y - 30)
await expect(body).not.toHaveAttribute("data-dragging")
expect(await image.evaluate((element) => element.style.transform)).toBe(transform)
})
async function open(page: Page) {
await page.locator('[data-story-image="inline"]').click()
}
@@ -0,0 +1,184 @@
import { describe, expect, test } from "bun:test"
import type { FlightFrame } from "./image-flight"
import {
INITIAL_PREVIEW_FLIGHT_STATE,
selectFlightInteractive,
selectFlightStage,
selectVideoAtRest,
transitionPreviewFlight,
type PreviewFlightEffect,
type PreviewFlightEvent,
type PreviewFlightStage,
type PreviewFlightState,
} from "./image-flight-machine"
const box = { x: 10, y: 20, width: 80, height: 60 }
const origin: FlightFrame = { image: box, clip: box, radius: 6, surface: box, surfaceRadius: 6, lift: 0 }
type Replay = { state: PreviewFlightState; effects: readonly PreviewFlightEffect[]; stages: PreviewFlightStage[] }
function replay(events: PreviewFlightEvent[], from = INITIAL_PREVIEW_FLIGHT_STATE) {
return events.reduce<Replay>(
(result, event) => {
const next = transitionPreviewFlight(result.state, event)
return { state: next.state, effects: next.effects, stages: [...result.stages, selectFlightStage(next.state)] }
},
{ state: from, effects: [], stages: [] },
)
}
const flyingOpen: PreviewFlightEvent[] = [{ type: "image.loaded" }, { type: "decode.ready", attempt: 1, origin }]
describe("image preview flight", () => {
test("opens by flying out of a visible origin and lands at rest", () => {
const opening = replay(flyingOpen)
expect(opening.state).toEqual({ status: "opening", mode: "flight", borrowed: false })
expect(opening.effects).toEqual([
{ type: "decode.cancel" },
{ type: "origin.hide" },
{ type: "open.flight", from: origin },
])
expect(opening.stages).toEqual(["pending", "flying"])
const open = transitionPreviewFlight(opening.state, { type: "motion.settled" })
expect(open.state).toEqual({ status: "open", originHidden: true, borrowed: false })
expect(selectFlightStage(open.state)).toBe("rest")
})
test("opens by fading without an origin, and when the image fails to load", () => {
expect(replay([{ type: "image.loaded" }, { type: "decode.ready", attempt: 1, origin: undefined }]).effects).toEqual(
[{ type: "decode.cancel" }, { type: "open.fade" }],
)
const failed = replay([{ type: "image.failed" }])
expect(failed.state).toEqual({ status: "opening", mode: "fade", borrowed: false })
expect(failed.effects).toEqual([{ type: "open.fade" }])
expect(selectFlightStage(failed.state)).toBe("rest")
})
// Bug: closing mid-flight once the origin scrolled away kept the opening flight running, left the origin hidden,
// and its landing flipped data-stage back to "rest" in the middle of the close.
test("a close mid-flight with the origin gone fades out, shows the origin and never returns to rest", () => {
const opening = replay(flyingOpen).state
const closing = replay([{ type: "close.started", origin: undefined }, { type: "motion.settled" }], opening)
expect(transitionPreviewFlight(opening, { type: "close.started", origin: undefined }).effects).toEqual([
{ type: "body.closing.acquire" },
{ type: "zoom.settle" },
{ type: "origin.show" },
{ type: "close.fade" },
])
expect(closing.stages).toEqual(["closing", "closing"])
expect(closing.state).toEqual({ status: "closed" })
})
// Bug: a fading close left data-stage at "rest", so a borrowed video kept taking clicks and the window keys and
// wheel stayed captured for the whole exit.
test("a fading close of a video stops taking input and hands the video back once it fades", () => {
const open = replay([{ type: "video.ready", origin }, { type: "motion.settled" }]).state
const closing = transitionPreviewFlight(open, { type: "close.started", origin: undefined })
expect(closing.effects).toEqual([
{ type: "body.closing.acquire" },
{ type: "zoom.fit" },
{ type: "origin.show" },
{ type: "close.fade" },
])
expect(selectFlightStage(closing.state)).toBe("closing")
expect(selectFlightInteractive(closing.state)).toBe(false)
expect(selectVideoAtRest(closing.state)).toBe(true)
expect(transitionPreviewFlight(closing.state, { type: "motion.settled" })).toEqual({
state: { status: "closed" },
effects: [{ type: "video.return" }],
})
})
// Bug: reveal awaited decode with no claim, so a decode that settled after the image changed revealed it anyway.
test("a decode of an image that changed or loaded again is ignored", () => {
const reloaded = replay([{ type: "image.loaded" }, { type: "src.changed" }, { type: "image.loaded" }])
expect(reloaded.state).toEqual({ status: "decoding", attempt: 3 })
expect(reloaded.effects).toEqual([{ type: "decode.start", attempt: 3 }])
const stale = transitionPreviewFlight(reloaded.state, { type: "decode.ready", attempt: 1, origin })
expect(stale.state).toBe(reloaded.state)
expect(stale.effects).toEqual([])
expect(transitionPreviewFlight(reloaded.state, { type: "decode.ready", attempt: 3, origin }).state.status).toBe(
"opening",
)
const again = transitionPreviewFlight({ status: "decoding", attempt: 1 }, { type: "image.loaded" })
expect(again.effects).toEqual([{ type: "decode.cancel" }, { type: "decode.start", attempt: 2 }])
})
test("a close before the preview reveals ends it there, and a late decode is ignored", () => {
const closed = replay([{ type: "image.loaded" }, { type: "close.started", origin }])
expect(closed.state).toEqual({ status: "closed" })
expect(closed.effects).toEqual([{ type: "decode.cancel" }, { type: "body.closing.acquire" }])
expect(transitionPreviewFlight(closed.state, { type: "decode.ready", attempt: 1, origin }).state).toBe(closed.state)
})
test("a close mid-flight with the origin in sight turns the flight around, then veils the stand-in", () => {
const opening = replay(flyingOpen).state
const turned = transitionPreviewFlight(opening, { type: "close.started", origin })
expect(turned.effects).toEqual([
{ type: "body.closing.acquire" },
{ type: "zoom.settle" },
{ type: "close.flight", to: origin, turn: true },
])
const landed = transitionPreviewFlight(turned.state, { type: "motion.settled" })
expect(landed.state).toEqual({ status: "closing", mode: "veil", borrowed: false })
expect(landed.effects).toEqual([{ type: "origin.show" }, { type: "close.veil" }])
expect(selectFlightStage(landed.state)).toBe("flying")
expect(transitionPreviewFlight(landed.state, { type: "motion.settled" }).state).toEqual({ status: "closed" })
})
test("a close from a fade-opened preview hides the origin and flies home from rest", () => {
const open = replay([{ type: "image.failed" }, { type: "motion.settled" }]).state
expect(transitionPreviewFlight(open, { type: "close.started", origin }).effects).toEqual([
{ type: "body.closing.acquire" },
{ type: "zoom.settle" },
{ type: "origin.hide" },
{ type: "close.flight", to: origin, turn: false },
])
})
test("a video flying home is handed back as it lands", () => {
const open = replay([{ type: "video.ready", origin }, { type: "motion.settled" }]).state
const closing = transitionPreviewFlight(open, { type: "close.started", origin })
expect(closing.effects.at(-1)).toEqual({ type: "close.flight", to: origin, turn: false })
expect(transitionPreviewFlight(closing.state, { type: "motion.settled" })).toEqual({
state: { status: "closed" },
effects: [{ type: "origin.show" }, { type: "video.return" }],
})
})
// A throttled frame loop can let the dialog unmount before the close lands.
test("disposal tears down what each phase holds, once", () => {
const flying: PreviewFlightState = { status: "closing", mode: "flight", borrowed: true }
expect(transitionPreviewFlight(flying, { type: "disposed" }).effects).toEqual([
{ type: "loop.stop" },
{ type: "origin.show" },
{ type: "video.return" },
{ type: "body.closing.release" },
])
expect(transitionPreviewFlight({ status: "closed" }, { type: "disposed" }).effects).toEqual([
{ type: "body.closing.release" },
])
expect(transitionPreviewFlight({ status: "decoding", attempt: 2 }, { type: "disposed" }).effects).toEqual([
{ type: "decode.cancel" },
])
const disposed = transitionPreviewFlight(flying, { type: "disposed" }).state
expect(transitionPreviewFlight(disposed, { type: "motion.settled" }).state).toBe(disposed)
expect(transitionPreviewFlight(disposed, { type: "disposed" }).effects).toEqual([])
})
})
@@ -0,0 +1,247 @@
import type { FlightFrame } from "./image-flight"
/**
* How long the preview waits for its image to decode before it opens anyway. Decoding first keeps the flight's first
* frames smooth; a decode that hangs, such as the stand-in's on a slow second fetch, must not keep the preview hidden.
*/
export const DECODE_TIMEOUT_MS = 1000
/** What `data-stage` tells the stylesheet: hidden, a stand-in flying, the preview at rest, or fading out after a close. */
export type PreviewFlightStage = "pending" | "flying" | "rest" | "closing"
/**
* The preview's life from load to close. `attempt` counts image loads, so a decode that settles after the image
* changed or loaded again is ignored. `borrowed` says the preview holds the page's video, which it hands back once the
* close lands. `originHidden` says the origin on the page is hidden because the image flew out of it.
*
* A close flies home when the origin still shows, then fades the stand-in over the page's image (`veil`). It only
* fades when the origin is gone, out of sight, or motion is reduced (`fade`).
*/
export type PreviewFlightState =
| { readonly status: "pending"; readonly attempt: number }
| { readonly status: "decoding"; readonly attempt: number }
| { readonly status: "opening"; readonly mode: "flight" | "fade"; readonly borrowed: boolean }
| { readonly status: "open"; readonly originHidden: boolean; readonly borrowed: boolean }
| { readonly status: "closing"; readonly mode: "flight" | "veil" | "fade"; readonly borrowed: boolean }
| { readonly status: "closed" }
| { readonly status: "disposed" }
/** `origin` is the origin's frame to fly from or to, or nothing when it is gone, out of sight, or motion is reduced. */
export type PreviewFlightEvent =
| { readonly type: "src.changed" }
| { readonly type: "image.loaded" }
| { readonly type: "image.failed" }
| { readonly type: "decode.ready"; readonly attempt: number; readonly origin: FlightFrame | undefined }
| { readonly type: "video.ready"; readonly origin: FlightFrame | undefined }
| { readonly type: "close.started"; readonly origin: FlightFrame | undefined }
/** The flight landed with the backdrop at rest, or, without a flight, the backdrop and the veil came to rest. */
| { readonly type: "motion.settled" }
| { readonly type: "disposed" }
export type PreviewFlightEffect =
| { readonly type: "decode.start"; readonly attempt: number }
| { readonly type: "decode.cancel" }
| { readonly type: "video.borrow" }
| { readonly type: "video.return" }
| { readonly type: "origin.hide" }
| { readonly type: "origin.show" }
| { readonly type: "open.flight"; readonly from: FlightFrame }
| { readonly type: "open.fade" }
/** `turn` turns the opening flight around where it is, keeping its velocity, instead of starting from rest. */
| { readonly type: "close.flight"; readonly to: FlightFrame; readonly turn: boolean }
| { readonly type: "close.veil" }
| { readonly type: "close.fade" }
/** A video eases back to its whole frame on the way home; an image stops where it is and flies as it is shown. */
| { readonly type: "zoom.fit" }
| { readonly type: "zoom.settle" }
| { readonly type: "body.closing.acquire" }
| { readonly type: "body.closing.release" }
| { readonly type: "loop.stop" }
export type PreviewFlightTransition = {
readonly state: PreviewFlightState
readonly effects: readonly PreviewFlightEffect[]
}
export const INITIAL_PREVIEW_FLIGHT_STATE: PreviewFlightState = Object.freeze({ status: "pending", attempt: 0 })
const CLOSED: PreviewFlightState = Object.freeze({ status: "closed" })
const DISPOSED: PreviewFlightState = Object.freeze({ status: "disposed" })
const NONE: readonly PreviewFlightEffect[] = Object.freeze([])
export function transitionPreviewFlight(state: PreviewFlightState, event: PreviewFlightEvent): PreviewFlightTransition {
if (state.status === "disposed") return { state, effects: NONE }
if (event.type === "disposed") return { state: DISPOSED, effects: teardown(state) }
if (event.type === "close.started") return close(state, event.origin)
if (state.status === "pending" || state.status === "decoding") return reveal(state, event)
if (event.type !== "motion.settled") return { state, effects: NONE }
return settle(state)
}
export function selectFlightStage(state: PreviewFlightState): PreviewFlightStage {
if (state.status === "pending" || state.status === "decoding") return "pending"
if (state.status === "opening") return state.mode === "flight" ? "flying" : "rest"
if (state.status === "open") return "rest"
if (state.status === "closing" && state.mode !== "fade") return "flying"
return "closing"
}
/** Whether the preview takes zoom, pan and keyboard input: from the moment it reveals until a close starts. */
export function selectFlightInteractive(state: PreviewFlightState) {
return state.status === "opening" || state.status === "open"
}
/** Whether the preview, its controls and a borrowed video fade with the backdrop rather than flying. */
export function selectFlightFading(state: PreviewFlightState) {
return (state.status === "opening" || state.status === "closing") && state.mode === "fade"
}
/** Whether a borrowed video sits fitted in the preview, not flying, so a resize moves it with the preview. */
export function selectVideoAtRest(state: PreviewFlightState) {
if (state.status === "open") return state.borrowed
return (state.status === "opening" || state.status === "closing") && state.borrowed && state.mode === "fade"
}
/** Whether the preview still waits to reveal, so it is worth measuring where it would fly from. */
export function selectAwaitingReveal(state: PreviewFlightState) {
return state.status === "pending" || state.status === "decoding"
}
/** Whether a decode of image load `attempt` is still the one the preview waits for. */
export function selectDecodeCurrent(state: PreviewFlightState, attempt: number) {
return state.status === "decoding" && state.attempt === attempt
}
function reveal(
state: Extract<PreviewFlightState, { status: "pending" | "decoding" }>,
event: Exclude<PreviewFlightEvent, { type: "close.started" | "disposed" }>,
): PreviewFlightTransition {
const cancel: readonly PreviewFlightEffect[] = state.status === "decoding" ? [{ type: "decode.cancel" }] : []
const attempt = state.attempt + 1
if (event.type === "src.changed") return { state: { status: "pending", attempt }, effects: cancel }
if (event.type === "image.loaded") {
return { state: { status: "decoding", attempt }, effects: [...cancel, { type: "decode.start", attempt }] }
}
if (event.type === "image.failed") return open(cancel, undefined, false)
if (event.type === "decode.ready" && state.status === "decoding" && event.attempt === state.attempt) {
return open(cancel, event.origin, false)
}
if (event.type === "video.ready" && state.status === "pending") {
return open([{ type: "video.borrow" }], event.origin, true)
}
return { state, effects: NONE }
}
function open(
before: readonly PreviewFlightEffect[],
origin: FlightFrame | undefined,
borrowed: boolean,
): PreviewFlightTransition {
if (!origin)
return { state: { status: "opening", mode: "fade", borrowed }, effects: [...before, { type: "open.fade" }] }
return {
state: { status: "opening", mode: "flight", borrowed },
effects: [...before, { type: "origin.hide" }, { type: "open.flight", from: origin }],
}
}
function close(state: PreviewFlightState, origin: FlightFrame | undefined): PreviewFlightTransition {
if (state.status === "pending" || state.status === "decoding") {
return {
state: CLOSED,
effects: [
...(state.status === "decoding" ? [{ type: "decode.cancel" } as const] : []),
{ type: "body.closing.acquire" },
],
}
}
if (state.status !== "opening" && state.status !== "open") return { state, effects: NONE }
const hidden = originHidden(state)
const start: PreviewFlightEffect[] = [
{ type: "body.closing.acquire" },
{ type: state.borrowed ? "zoom.fit" : "zoom.settle" },
]
if (!origin) {
return {
state: { status: "closing", mode: "fade", borrowed: state.borrowed },
effects: [...start, ...(hidden ? [{ type: "origin.show" } as const] : []), { type: "close.fade" }],
}
}
return {
state: { status: "closing", mode: "flight", borrowed: state.borrowed },
effects: [
...start,
...(hidden ? [] : [{ type: "origin.hide" } as const]),
{ type: "close.flight", to: origin, turn: state.status === "opening" && state.mode === "flight" },
],
}
}
function settle(state: PreviewFlightState): PreviewFlightTransition {
if (state.status === "opening") {
return {
state: { status: "open", originHidden: state.mode === "flight", borrowed: state.borrowed },
effects: NONE,
}
}
if (state.status !== "closing") return { state, effects: NONE }
// A video is the surface and goes straight back; an image's stand-in fades over the page's image once it lands.
if (state.mode === "flight" && state.borrowed) {
return { state: CLOSED, effects: [{ type: "origin.show" }, { type: "video.return" }] }
}
if (state.mode === "flight") {
return {
state: { status: "closing", mode: "veil", borrowed: false },
effects: [{ type: "origin.show" }, { type: "close.veil" }],
}
}
return { state: CLOSED, effects: state.borrowed ? [{ type: "video.return" }] : NONE }
}
function teardown(state: PreviewFlightState): readonly PreviewFlightEffect[] {
if (state.status === "pending" || state.status === "disposed") return NONE
if (state.status === "decoding") return [{ type: "decode.cancel" }]
if (state.status === "closed") return [{ type: "body.closing.release" }]
return [
{ type: "loop.stop" },
...(originHidden(state) ? [{ type: "origin.show" } as const] : []),
...(state.borrowed ? [{ type: "video.return" } as const] : []),
...(state.status === "closing" ? [{ type: "body.closing.release" } as const] : []),
]
}
function originHidden(state: Extract<PreviewFlightState, { status: "opening" | "open" | "closing" }>) {
if (state.status === "open") return state.originHidden
return state.mode === "flight"
}
+5 -2
View File
@@ -71,7 +71,8 @@
pointer-events: auto;
}
&[data-stage="flying"] > video {
/* A video fading out after a close, rather than flying home, must not take the page's clicks either. */
&:is([data-stage="flying"], [data-stage="closing"]) > video {
pointer-events: none;
}
@@ -79,7 +80,9 @@
visibility: hidden;
}
&[data-stage="pending"] :is([data-slot="image-preview-scrim"], [data-slot="image-preview-content"]) {
/* A preview closed before it revealed never painted its backdrop; one that did paints over this inline. */
&:is([data-stage="pending"], [data-stage="closing"])
:is([data-slot="image-preview-scrim"], [data-slot="image-preview-content"]) {
opacity: 0;
}
+402 -264
View File
@@ -1,7 +1,8 @@
import { Dialog as Kobalte, useDialogContext } from "@kobalte/core/dialog"
import { makeEventListener } from "@solid-primitives/event-listener"
import { createResizeObserver } from "@solid-primitives/resize-observer"
import { createEffect, createMemo, createSignal, on, onCleanup, Show } from "solid-js"
import { createEffect, createMemo, createSignal, on, onCleanup, Show, untrack } from "solid-js"
import { createStore } from "solid-js/store"
import { useDialogLayer } from "../context/dialog"
import { useI18n } from "../context/i18n"
import { Button } from "@opencode/ui/button"
@@ -19,6 +20,20 @@ import {
type FlightFrame,
} from "./image-flight"
import {
DECODE_TIMEOUT_MS,
INITIAL_PREVIEW_FLIGHT_STATE,
selectAwaitingReveal,
selectDecodeCurrent,
selectFlightFading,
selectFlightInteractive,
selectFlightStage,
selectVideoAtRest,
transitionPreviewFlight,
type PreviewFlightEffect,
type PreviewFlightEvent,
} from "./image-flight-machine"
import {
clampAxis,
clampView,
detailScale,
FIT_VIEW,
@@ -29,6 +44,15 @@ import {
zoomAt,
type ZoomView,
} from "./image-zoom"
import {
INITIAL_PREVIEW_ZOOM_STATE,
selectDragging,
selectPanPointer,
transitionPreviewZoom,
type PanTarget,
type PreviewZoomEffect,
type PreviewZoomEvent,
} from "./image-zoom-machine"
export interface ImagePreviewProps {
src: string
@@ -52,13 +76,19 @@ const fade = { duration: 0.15, bounce: 0 }
// How long the dialog stays mounted after a close starts, in milliseconds: the flight lands and hands the image back
// to the page well within this.
const exitDuration = Math.max(FLIGHT_SPRING.duration, fade.duration) * 3200
const EXIT_DURATION_MS = Math.max(FLIGHT_SPRING.duration, fade.duration) * 3200
const CENTER = { x: 0, y: 0 }
const SETTLED: PreviewFlightEvent = Object.freeze({ type: "motion.settled" })
// Previews closing at once, such as one still flying home under the next, share the body's closing mark.
let closingPreviews = 0
export function ImagePreview(props: ImagePreviewProps) {
const i18n = useI18n()
const dialog = useDialogContext()
const layer = useDialogLayer()
let root!: HTMLDivElement
let scrim!: HTMLDivElement
let content!: HTMLDivElement
@@ -71,13 +101,18 @@ export function ImagePreview(props: ImagePreviewProps) {
let surface!: HTMLDivElement
let edge!: HTMLDivElement
let close: HTMLButtonElement | undefined
// Nothing shows until the image has loaded and the preview knows where it lands; while flying, a stand-in image and
// its shadow travel above the dialog in place of the real one.
const [stage, setStage] = createSignal<"pending" | "flying" | "rest">("pending")
const [flight, setFlight] = createSignal(INITIAL_PREVIEW_FLIGHT_STATE)
const [zoom, setZoom] = createSignal(INITIAL_PREVIEW_ZOOM_STATE)
// What the view shows the controls and the stylesheet, written only when it changes rather than on every frame.
const [shown, setShown] = createStore({ zoomed: false, ownsEscape: false, level: 100 })
// The flight under way: where the stand-in is laid out (the flight only transforms and clips it), the springs, and
// what happens when it lands.
let course: { at: Box; flight: ReturnType<typeof createFlight>; landed: () => void } | undefined
// The flight under way: where the stand-in is laid out (the flight only transforms and clips it) and the springs.
let course: { at: Box; flight: ReturnType<typeof createFlight> } | undefined
let flightJob: (() => void) | undefined
let decodeTimer: ReturnType<typeof setTimeout> | undefined
const dim = Spring.fromDuration(0, FLIGHT_SPRING)
// Once a close lands, the stand-in fades out over the image the page shows again, so whatever the page draws over
@@ -86,162 +121,230 @@ export function ImagePreview(props: ImagePreviewProps) {
// How far the flight has lifted off the page, as last painted: the origin's outline fades out as it rises.
let lift = 0
// Without a flight (reduced motion, or nothing on the page to fly to) the preview only fades with the backdrop.
let plain = false
let stop: (() => void) | undefined
const [view, setView] = createSignal(FIT_VIEW)
const [fitRatio, setFitRatio] = createSignal(1)
const [drag, setDrag] = createSignal<{ id: number; x: number; y: number }>()
// Whether the press that ends in a click began on the backdrop around the image and stayed put. A pan captures the
// pointer, so its click lands on the backdrop wherever it began.
let backdrop = false
// Whether the pan under way has moved, so the click that ends it neither closes the preview nor plays the video.
let panned = false
// Where an eased zoom is heading, so repeated steps build on the destination rather than the frame in flight.
const [goal, setGoal] = createSignal(FIT_VIEW)
const glide = [1, 0, 0].map((value) => Spring.fromDuration(value, FLIGHT_SPRING))
let gliding: (() => void) | undefined
// The view: each spring's value is what shows, and its target is where an eased zoom is heading, so repeated steps
// build on the destination rather than the frame in flight. Scale and offsets ride springs of one shape, so the point
// under the pointer stays put; a new target mid-glide keeps the velocity it has.
const scaleSpring = Spring.fromDuration(1, FLIGHT_SPRING)
const xSpring = Spring.fromDuration(0, FLIGHT_SPRING)
const ySpring = Spring.fromDuration(0, FLIGHT_SPRING)
let glideJob: (() => void) | undefined
// Where the pan under way last saw its pointer.
const cursor = { x: 0, y: 0 }
// Measured when the preview lays out rather than on every move or frame. A video zooms inside its own frame, so its
// controls stay where they are; an image zooms out across the window.
const natural = { width: 0, height: 0 }
const bounds = { width: 0, height: 0, viewportWidth: 0, viewportHeight: 0, maxScale: 1 }
let fitRatio = 1
// Reused on every pointer move of a pan.
const followEvent = { type: "follow" as const, zoomed: false }
const movedEvent = { type: "pointer.moved" as const, pointerId: 0 }
const percent = createMemo(() => new Intl.NumberFormat(i18n.locale(), { style: "percent", maximumFractionDigits: 0 }))
const natural = () =>
image instanceof HTMLImageElement
? { width: image.naturalWidth, height: image.naturalHeight }
: { width: image.width, height: image.height }
const dispatchFlight = (event: PreviewFlightEvent) => {
const prev = untrack(flight)
const next = transitionPreviewFlight(prev, event)
// A video zooms inside its own frame, so its controls stay where they are; an image zooms out across the window.
const bounds = () => ({
width: image.offsetWidth,
height: image.offsetHeight,
viewportWidth: props.video ? image.offsetWidth : viewport.clientWidth,
viewportHeight: props.video ? image.offsetHeight : viewport.clientHeight,
maxScale: maxScale(fitRatio()),
})
if (next.state !== prev) setFlight(next.state)
next.effects.forEach(runFlight)
}
// The fitted size, read when the preview lays out rather than on every frame of a glide.
let size = { width: 0, height: 0 }
const runFlight = (effect: PreviewFlightEffect) => {
if (effect.type === "decode.start") return decode(effect.attempt)
const show = (next: ZoomView) => {
setView(next)
if (effect.type === "decode.cancel") return clearTimeout(decodeTimer)
if (props.video) {
props.video.style.setProperty("object-view-box", viewBox(next, size, natural()))
if (effect.type === "video.borrow") return borrow()
if (effect.type === "video.return") return giveBack()
if (effect.type === "origin.hide") return home()?.setAttribute("data-image-preview-origin", "")
if (effect.type === "origin.show") return home()?.removeAttribute("data-image-preview-origin")
if (effect.type === "open.flight") {
dimTo(1, FLIGHT_SPRING)
const next = createFlight(effect.from)
next.to(restFrame(), KICK.open, FLIGHT_SPRING)
course = { at: place(fitted()), flight: next }
paint()
return run()
}
if (effect.type === "open.fade") {
dimTo(1, fade)
if (props.video) place(fitted())
paint()
return run()
}
if (effect.type === "close.flight") {
dimTo(0, FLIGHT_SPRING)
if (!effect.turn) course = { at: place(fitted()), flight: createFlight(restFrame()) }
course?.flight.to(effect.to, KICK.close, FLIGHT_SPRING)
paint()
return run()
}
if (effect.type === "close.veil") {
veil.omega = (2 * Math.PI) / (FLIGHT_SPRING.duration * 0.75)
veil.set(0)
return
}
image.style.transform = `translate(${next.x}px, ${next.y}px) scale(${next.scale})`
if (effect.type === "close.fade") {
course = undefined
dimTo(0, fade)
return run()
}
if (effect.type === "zoom.fit") return ease(FIT_VIEW)
if (effect.type === "zoom.settle") return follow(scaleSpring.value, xSpring.value, ySpring.value)
// See image-preview.css: the body takes clicks again while the closing flight holds the dialog mounted.
if (effect.type === "body.closing.acquire") {
closingPreviews++
document.body.setAttribute("data-image-preview-closing", "")
return
}
if (effect.type === "body.closing.release") {
closingPreviews--
if (!closingPreviews) document.body.removeAttribute("data-image-preview-closing")
return
}
flightJob?.()
flightJob = undefined
}
const settle = () => {
gliding?.()
gliding = undefined
const dispatchZoom = (event: PreviewZoomEvent) => {
const prev = untrack(zoom)
const next = transitionPreviewZoom(prev, event)
if (next.state !== prev) setZoom(next.state)
next.effects.forEach(runZoom)
}
const runZoom = (effect: PreviewZoomEffect) => {
if (effect.type === "pointer.capture") return panElement(effect.target).setPointerCapture(effect.pointerId)
if (effect.type === "pointer.release") {
const element = panElement(effect.target)
if (element.hasPointerCapture(effect.pointerId)) element.releasePointerCapture(effect.pointerId)
return
}
if (effect.type === "glide.loop.start") {
glideJob = frameLoop.add((dt) => {
scaleSpring.step(dt)
xSpring.step(dt)
ySpring.step(dt)
paintZoom()
if (!scaleSpring.resting || !xSpring.resting || !ySpring.resting) return true
dispatchZoom({ type: "glide.settled", zoomed: scaleSpring.value > 1 })
return false
})
return
}
if (effect.type === "glide.loop.stop") {
glideJob?.()
glideJob = undefined
return
}
if (effect.type === "video.suppress-click") return suppressVideoClick()
dialog.close()
}
// Writes the view to the DOM. A frame allocates nothing but the style string, and touches Solid state only when
// the zoom level's rounded percent or whether the image is zoomed changes.
const paintZoom = () => {
const scale = scaleSpring.value
if (props.video) {
props.video.style.setProperty("object-view-box", viewBox(scale, xSpring.value, ySpring.value, bounds, natural))
}
if (!props.video) image.style.transform = `translate(${xSpring.value}px, ${ySpring.value}px) scale(${scale})`
const level = Math.round(scale * fitRatio * 100)
if (shown.zoomed !== scale > 1) setShown("zoomed", scale > 1)
if (shown.level !== level) setShown("level", level)
}
const view = (): ZoomView => ({ scale: scaleSpring.value, x: xSpring.value, y: ySpring.value })
const goal = (): ZoomView => ({ scale: scaleSpring.target, x: xSpring.target, y: ySpring.target })
const own = (scale: number) => {
if (shown.ownsEscape !== scale > 1) setShown("ownsEscape", scale > 1)
}
// Pinch, wheel and drag follow the hand directly and take over from an eased zoom mid-flight.
const follow = (next: ZoomView) => {
settle()
setGoal(next)
show(next)
const follow = (scale: number, x: number, y: number) => {
followEvent.zoomed = scale > 1
dispatchZoom(followEvent)
scaleSpring.snap(scale)
xSpring.snap(x)
ySpring.snap(y)
own(scale)
paintZoom()
}
// Scale and offsets ride springs of one shape, so the point under the pointer stays put; a new target mid-glide
// keeps the velocity it has.
const ease = (target: ZoomView) => {
setGoal(target)
if (prefersReducedMotion()) return follow(target)
if (!gliding) [view().scale, view().x, view().y].forEach((value, index) => glide[index].snap(value))
;[target.scale, target.x, target.y].forEach((value, index) => glide[index].set(value))
gliding ??= frameLoop.add((dt) => {
const [scale, x, y] = glide.map((spring) => spring.step(dt))
show({ scale, x, y })
if (!glide.every((spring) => spring.resting)) return true
gliding = undefined
return false
})
if (prefersReducedMotion()) return follow(target.scale, target.x, target.y)
scaleSpring.set(target.scale)
xSpring.set(target.x)
ySpring.set(target.y)
own(target.scale)
dispatchZoom({ type: "glide.start" })
}
const step = (factor: number) => ease(zoomAt(goal(), goal().scale * factor, CENTER, bounds()))
const step = (factor: number) => {
const target = goal()
ease(zoomAt(target, target.scale * factor, CENTER, bounds))
}
// Kobalte keeps the content mounted while an exit animation runs; the dialog stack waits for the flight too.
const layer = useDialogLayer()
const [exit, setExit] = createSignal(0)
layer?.setExitDuration(EXIT_DURATION_MS)
const holdExit = () => {
setExit(exitDuration)
layer?.setExitDuration(exit())
const decode = (attempt: number) => {
clearTimeout(decodeTimer)
decodeTimer = setTimeout(() => decoded(attempt), DECODE_TIMEOUT_MS)
if (!(image instanceof HTMLImageElement)) return
void Promise.all([image.decode(), standIn?.decode()])
.catch(() => undefined)
.then(() => decoded(attempt))
}
holdExit()
const reveal = async () => {
if (image instanceof HTMLImageElement) await Promise.all([image.decode(), standIn?.decode()]).catch(() => undefined)
if (stage() !== "pending" || !dialog.isOpen()) return
const from = prefersReducedMotion() ? undefined : originFrame()
if (props.video) borrow(props.video)
holdExit()
dimTo(1, from ? FLIGHT_SPRING : fade)
if (!from) {
plain = true
if (props.video) place(fitted())
paint()
setStage("rest")
return run()
}
const flight = createFlight(from)
const rest = restFrame()
flight.to(rest, KICK.open, FLIGHT_SPRING)
course = { at: place(fitted()), flight, landed: () => setStage("rest") }
hideOrigin()
paint()
setStage("flying")
run()
}
const dismiss = () => {
// A video eases back to its whole frame on the way home; an image flies as it is shown.
if (props.video) ease(FIT_VIEW)
else settle()
if (stage() === "pending") return
const to = prefersReducedMotion() ? undefined : originFrame()
dimTo(0, to ? FLIGHT_SPRING : fade)
if (!to) {
plain = true
return run()
}
// A close mid-open turns the flight around where it is, keeping its velocity.
if (!course) {
const rest = restFrame()
course = { at: place(fitted()), flight: createFlight(rest), landed: showOrigin }
}
course.flight.to(to, KICK.close, FLIGHT_SPRING)
course.landed = () => {
showOrigin()
if (props.video) return giveBack()
veil.omega = (2 * Math.PI) / (FLIGHT_SPRING.duration * 0.75)
veil.set(0)
}
hideOrigin()
paint()
setStage("flying")
run()
// Measuring where the origin shows is not free, so a decode the preview no longer waits for skips it.
const decoded = (attempt: number) => {
if (!selectDecodeCurrent(untrack(flight), attempt)) return
dispatchFlight({ type: "decode.ready", attempt, origin: originFrame() })
}
const dimTo = (target: number, spring: DurationOptions) => {
@@ -252,7 +355,7 @@ export function ImagePreview(props: ImagePreviewProps) {
// One job on the shared frame loop steps the flight and the backdrop together and writes them straight to the DOM.
const run = () => {
stop ??= frameLoop.add((dt) => {
flightJob ??= frameLoop.add((dt) => {
const flying = course?.flight.step(dt)
dim.step(dt)
veil.step(dt)
@@ -260,16 +363,13 @@ export function ImagePreview(props: ImagePreviewProps) {
// The real image takes over only once the panel holding it is fully opaque, so its brightness doesn't step.
if (course && !flying && dim.resting) {
const landed = course.landed
course = undefined
landed()
dispatchFlight(SETTLED)
}
if (course || !dim.resting || !veil.resting) return true
stop = undefined
// A video that faded out rather than flying home goes back once it has.
if (!dialog.isOpen()) giveBack()
flightJob = undefined
dispatchFlight(SETTLED)
return false
})
@@ -280,6 +380,8 @@ export function ImagePreview(props: ImagePreviewProps) {
const paint = () => {
const flying = flyer()
// Without a flight (reduced motion, or nothing on the page to fly to) the preview only fades with the backdrop.
const plain = selectFlightFading(untrack(flight))
scrim.style.opacity = String(dim.value)
surface.style.opacity = course ? "1" : "0"
@@ -310,19 +412,20 @@ export function ImagePreview(props: ImagePreviewProps) {
const place = (box: Box) => {
const flying = flyer()
if (flying)
Object.assign(flying.style, {
left: `${box.x}px`,
top: `${box.y}px`,
width: `${box.width}px`,
height: `${box.height}px`,
})
if (!flying) return box
flying.style.left = `${box.x}px`
flying.style.top = `${box.y}px`
flying.style.width = `${box.width}px`
flying.style.height = `${box.height}px`
return box
}
// Moves the video into the preview, leaving a box of its size in its place to fly back to.
const borrow = (video: HTMLVideoElement) => {
const borrow = () => {
const video = props.video
if (!video) return
const rect = video.getBoundingClientRect()
holder = document.createElement("div")
Object.assign(holder.style, {
@@ -352,19 +455,23 @@ export function ImagePreview(props: ImagePreviewProps) {
// The image as shown now, zoomed and panned and cropped to the viewport. There is no panel: the image is the surface.
const restFrame = (): FlightFrame => {
const shown = image.getBoundingClientRect()
const clip = intersect(shown, viewport.getBoundingClientRect())
const cropped = clip.width < shown.width - 0.5 || clip.height < shown.height - 0.5
const radius = cropped ? 0 : parseFloat(getComputedStyle(image).borderTopLeftRadius) * scale()
const shownBox = image.getBoundingClientRect()
const clip = intersect(shownBox, viewport.getBoundingClientRect())
const cropped = clip.width < shownBox.width - 0.5 || clip.height < shownBox.height - 0.5
return { image: shown, clip, radius, surface: clip, surfaceRadius: radius, lift: 1 }
const radius = cropped
? 0
: parseFloat(getComputedStyle(image).borderTopLeftRadius) * (props.video ? 1 : scaleSpring.value)
return { image: shownBox, clip, radius, surface: clip, surfaceRadius: radius, lift: 1 }
}
// The origin's frame, cropped to the part the page shows, or nothing when it is gone or out of sight.
// The origin's frame, cropped to the part the page shows, or nothing when it is gone, out of sight, or motion is
// reduced.
const originFrame = () => {
const origin = home()
if (!origin?.isConnected || !natural().width) return
if (prefersReducedMotion() || !origin?.isConnected || !natural.width) return
const rect = origin.getBoundingClientRect()
if (!rect.width || !rect.height) return
@@ -379,46 +486,52 @@ export function ImagePreview(props: ImagePreviewProps) {
? "none"
: ([style.boxShadow, getComputedStyle(origin, "::after").boxShadow].find((shadow) => shadow !== "none") ?? "none")
return elementFrame(rect, natural(), style.objectFit, parseFloat(style.borderTopLeftRadius) || 0, visible)
return elementFrame(rect, natural, style.objectFit, parseFloat(style.borderTopLeftRadius) || 0, visible)
}
// The image's fitted layout box, wherever zoom has moved it. A video zooms inside its box, which stays put.
const fitted = (): Box => {
const shown = image.getBoundingClientRect()
const offset = props.video ? CENTER : view()
const shownBox = image.getBoundingClientRect()
const x = props.video ? 0 : xSpring.value
const y = props.video ? 0 : ySpring.value
return {
x: shown.x + shown.width / 2 - offset.x - image.offsetWidth / 2,
y: shown.y + shown.height / 2 - offset.y - image.offsetHeight / 2,
x: shownBox.x + shownBox.width / 2 - x - image.offsetWidth / 2,
y: shownBox.y + shownBox.height / 2 - y - image.offsetHeight / 2,
width: image.offsetWidth,
height: image.offsetHeight,
}
}
const scale = () => (props.video ? 1 : view().scale)
const home = () => holder ?? props.origin ?? props.video
const hideOrigin = () => home()?.setAttribute("data-image-preview-origin", "")
const showOrigin = () => home()?.removeAttribute("data-image-preview-origin")
const panElement = (target: PanTarget) => (target === "video" && props.video ? props.video : viewport)
const suppressVideoClick = () => {
const video = props.video
if (!video) return
const swallow = (event: MouseEvent) => {
event.preventDefault()
event.stopImmediatePropagation()
}
// The click follows its pointerup in the same task; one that never comes must not swallow a later one.
video.addEventListener("click", swallow, { capture: true, once: true })
setTimeout(() => video.removeEventListener("click", swallow, { capture: true }))
}
onCleanup(() => {
stop?.()
settle()
showOrigin()
giveBack()
document.body.removeAttribute("data-image-preview-closing")
dispatchFlight({ type: "disposed" })
dispatchZoom({ type: "disposed" })
})
createEffect(
on(
() => dialog.isOpen(),
(open) => {
// See image-preview.css: the body takes clicks again while the closing flight holds the dialog mounted.
document.body.toggleAttribute("data-image-preview-closing", !open)
const closing = () => (layer ? layer.closing() : !dialog.isOpen())
if (!open) dismiss()
},
{ defer: true },
),
createEffect(
on(closing, (value) => {
if (value) dispatchFlight({ type: "close.started", origin: originFrame() })
}),
)
// From the center of the box zoom is measured in: the window's for an image, the frame's for a video.
@@ -429,17 +542,25 @@ export function ImagePreview(props: ImagePreviewProps) {
}
const measure = () => {
if (!natural().width || !image.offsetWidth) return
size = { width: image.offsetWidth, height: image.offsetHeight }
setFitRatio(size.width / natural().width)
follow(clampView(view(), bounds()))
natural.width = image instanceof HTMLImageElement ? image.naturalWidth : image.width
natural.height = image instanceof HTMLImageElement ? image.naturalHeight : image.height
if (!natural.width || !image.offsetWidth) return
bounds.width = image.offsetWidth
bounds.height = image.offsetHeight
bounds.viewportWidth = props.video ? image.offsetWidth : viewport.clientWidth
bounds.viewportHeight = props.video ? image.offsetHeight : viewport.clientHeight
fitRatio = bounds.width / natural.width
bounds.maxScale = maxScale(fitRatio)
const next = clampView(view(), bounds)
follow(next.scale, next.x, next.y)
if (!props.video) return
// A video is ready as soon as the preview has laid out its box.
if (stage() === "pending") return void reveal()
if (selectAwaitingReveal(untrack(flight))) return dispatchFlight({ type: "video.ready", origin: originFrame() })
if (holder && !course) place(fitted())
if (selectVideoAtRest(untrack(flight))) place(fitted())
}
createResizeObserver(() => [viewport, image], measure)
@@ -447,59 +568,75 @@ export function ImagePreview(props: ImagePreviewProps) {
createEffect(
on(
() => props.src,
() => follow(FIT_VIEW),
() => {
dispatchFlight({ type: "src.changed" })
follow(FIT_VIEW.scale, FIT_VIEW.x, FIT_VIEW.y)
},
{ defer: true },
),
)
const interactive = () => selectFlightInteractive(untrack(flight))
const detail = (event: MouseEvent) => {
if (goal().scale > 1) return ease(FIT_VIEW)
ease(zoomAt(goal(), detailScale(fitRatio()), point(event), bounds()))
if (!interactive()) return
if (scaleSpring.target > 1) return ease(FIT_VIEW)
ease(zoomAt(goal(), detailScale(fitRatio), point(event), bounds))
}
const grab = (event: PointerEvent, target: HTMLElement) => {
if (event.button !== 0 || view().scale <= 1) return
const press = (event: PointerEvent, target: PanTarget | "content", onBackdrop: boolean) => {
if (!interactive()) return
dispatchZoom({
type: "pointer.down",
pointerId: event.pointerId,
button: event.button,
target,
onBackdrop,
zoomed: scaleSpring.value > 1,
})
if (!selectPanPointer(untrack(zoom), event.pointerId)) return
event.preventDefault()
target.setPointerCapture(event.pointerId)
setDrag({ id: event.pointerId, x: event.clientX, y: event.clientY })
cursor.x = event.clientX
cursor.y = event.clientY
}
// The hot path of a pan: no layout reads, and no Solid writes once the pan has moved.
const pan = (event: PointerEvent) => {
const current = drag()
if (!selectPanPointer(untrack(zoom), event.pointerId)) return
if (current?.id !== event.pointerId) return
backdrop = false
panned = true
setDrag({ id: current.id, x: event.clientX, y: event.clientY })
follow(panBy(view(), { x: event.clientX - current.x, y: event.clientY - current.y }, bounds()))
// The button came up without a pointerup reaching the preview, so this is a hover, not a drag.
if ((event.buttons & 1) === 0) return dispatchZoom({ type: "pointer.cancel", pointerId: event.pointerId })
const dx = event.clientX - cursor.x
const dy = event.clientY - cursor.y
if (dx === 0 && dy === 0) return
cursor.x = event.clientX
cursor.y = event.clientY
movedEvent.pointerId = event.pointerId
dispatchZoom(movedEvent)
const scale = scaleSpring.value
follow(
scale,
clampAxis(xSpring.value + dx, bounds.width * scale, bounds.viewportWidth),
clampAxis(ySpring.value + dy, bounds.height * scale, bounds.viewportHeight),
)
}
const release = (event: PointerEvent) => {
if (drag()?.id === event.pointerId) setDrag(undefined)
}
const release = (event: PointerEvent) => dispatchZoom({ type: "pointer.up", pointerId: event.pointerId })
const cancel = (event: PointerEvent) => dispatchZoom({ type: "pointer.cancel", pointerId: event.pointerId })
if (props.video) {
const video = props.video
makeEventListener(video, "pointerdown", (event: PointerEvent) => {
panned = false
if (holder && event.clientY < video.getBoundingClientRect().bottom - CONTROLS) grab(event, video)
if (event.clientY < video.getBoundingClientRect().bottom - CONTROLS) press(event, "video", false)
})
makeEventListener(video, "pointermove", pan)
makeEventListener(video, "pointerup", release)
makeEventListener(video, "pointercancel", release)
makeEventListener(video, "dblclick", (event: MouseEvent) => holder && detail(event))
makeEventListener(
video,
"click",
(event: MouseEvent) => {
if (!panned) return
panned = false
event.preventDefault()
event.stopImmediatePropagation()
},
{ capture: true },
)
makeEventListener(video, "pointercancel", cancel)
makeEventListener(video, "lostpointercapture", cancel)
makeEventListener(video, "dblclick", detail)
}
// The preview owns zoom gestures while it is open: the page behind must neither scroll nor zoom the whole window.
@@ -507,35 +644,23 @@ export function ImagePreview(props: ImagePreviewProps) {
window,
"wheel",
(event: WheelEvent) => {
const inside =
event.target instanceof Node && (viewport.contains(event.target) || (!!holder && event.target === props.video))
if (!interactive()) return
const inside = event.target instanceof Node && (viewport.contains(event.target) || event.target === props.video)
const zoom = event.ctrlKey || event.metaKey
const pinch = event.ctrlKey || event.metaKey
if (!inside && !zoom) return
if (!inside && !pinch) return
event.preventDefault()
event.stopPropagation()
if (!inside) return
const current = view()
if (zoom) {
follow(zoomAt(current, current.scale * wheelZoomFactor(pixels(event, event.deltaY)), point(event), bounds()))
const next = pinch
? zoomAt(current, current.scale * wheelZoomFactor(pixels(event, event.deltaY)), point(event), bounds)
: panBy(current, wheelPan(event), bounds)
return
}
const horizontal = event.shiftKey && event.deltaX === 0
follow(
panBy(
current,
{
x: -pixels(event, horizontal ? event.deltaY : event.deltaX),
y: horizontal ? 0 : -pixels(event, event.deltaY),
},
bounds(),
),
)
follow(next.scale, next.x, next.y)
},
{ passive: false, capture: true },
)
@@ -545,9 +670,10 @@ export function ImagePreview(props: ImagePreviewProps) {
window,
"keydown",
(event: KeyboardEvent) => {
if (!interactive()) return
const bare = !event.metaKey && !event.ctrlKey && !event.altKey
if (bare && event.key === " " && props.video && holder) {
if (bare && event.key === " " && props.video) {
event.preventDefault()
event.stopPropagation()
@@ -572,10 +698,10 @@ export function ImagePreview(props: ImagePreviewProps) {
<div
ref={root}
data-component="image-preview"
data-stage={stage()}
data-stage={selectFlightStage(flight())}
// Zoomed in, the first Escape zooms back out; the dialog stack leaves it to the preview.
data-owns-escape={goal().scale > 1 ? "" : undefined}
style={{ "--image-preview-exit": `${exit()}ms` }}
data-owns-escape={shown.ownsEscape ? "" : undefined}
style={{ "--image-preview-exit": `${EXIT_DURATION_MS}ms` }}
>
<div ref={scrim} data-slot="image-preview-scrim" />
<Kobalte.Content
@@ -587,7 +713,7 @@ export function ImagePreview(props: ImagePreviewProps) {
close?.focus()
}}
onEscapeKeyDown={(event) => {
if (goal().scale <= 1) return
if (scaleSpring.target <= 1) return
event.preventDefault()
ease(FIT_VIEW)
}}
@@ -596,24 +722,28 @@ export function ImagePreview(props: ImagePreviewProps) {
if (props.video && event.target === props.video) event.preventDefault()
}}
onPointerDown={(event: PointerEvent) => {
backdrop = event.target === content || event.target === viewport
}}
onClick={(event: MouseEvent) => {
// The preview fills the window, so a click on the backdrop around the image lands here rather than outside.
if (!backdrop || (event.target !== content && event.target !== viewport)) return
dialog.close()
const target = event.target
const body = target instanceof Node && viewport.contains(target)
press(event, body ? "viewport" : "content", target === content || target === viewport)
}}
// The preview fills the window, so a click on the backdrop around the image lands here rather than outside.
onClick={(event: MouseEvent) =>
dispatchZoom({
type: "backdrop.click",
onBackdrop: event.target === content || event.target === viewport,
})
}
>
<div
ref={viewport}
data-slot="image-preview-body"
data-zoomed={view().scale > 1 ? "" : undefined}
data-dragging={drag() ? "" : undefined}
data-zoomed={shown.zoomed ? "" : undefined}
data-dragging={selectDragging(zoom()) ? "" : undefined}
onDblClick={detail}
onPointerDown={(event) => grab(event, viewport)}
onPointerMove={pan}
onPointerUp={release}
onPointerCancel={release}
onPointerCancel={cancel}
onLostPointerCapture={cancel}
>
<Show
when={props.video}
@@ -626,9 +756,9 @@ export function ImagePreview(props: ImagePreviewProps) {
draggable={false}
onLoad={() => {
measure()
void reveal()
dispatchFlight({ type: "image.loaded" })
}}
onError={() => void reveal()}
onError={() => dispatchFlight({ type: "image.failed" })}
/>
}
>
@@ -658,7 +788,7 @@ export function ImagePreview(props: ImagePreviewProps) {
title={i18n.t("ui.imagePreview.zoomToFit")}
onClick={() => ease(FIT_VIEW)}
>
{percent().format(view().scale * fitRatio())}
{percent().format(shown.level / 100)}
</Button>
<IconButton
data-slot="image-preview-zoom-in"
@@ -758,13 +888,11 @@ function dispose(video: HTMLVideoElement) {
}
function layout(element: HTMLElement, frame: Box, radius: number) {
Object.assign(element.style, {
left: `${frame.x}px`,
top: `${frame.y}px`,
width: `${frame.width}px`,
height: `${frame.height}px`,
borderRadius: `${radius}px`,
})
element.style.left = `${frame.x}px`
element.style.top = `${frame.y}px`
element.style.width = `${frame.width}px`
element.style.height = `${frame.height}px`
element.style.borderRadius = `${radius}px`
}
function shortcut(key: string) {
@@ -775,6 +903,16 @@ function shortcut(key: string) {
if (key === "0") return "fit"
}
// A plain wheel pans; Shift turns a vertical wheel sideways.
function wheelPan(event: WheelEvent) {
const horizontal = event.shiftKey && event.deltaX === 0
return {
x: -pixels(event, horizontal ? event.deltaY : event.deltaX),
y: horizontal ? 0 : -pixels(event, event.deltaY),
}
}
function pixels(event: WheelEvent, delta: number) {
if (event.deltaMode === WheelEvent.DOM_DELTA_LINE) return delta * 16
@@ -0,0 +1,154 @@
import { describe, expect, test } from "bun:test"
import {
INITIAL_PREVIEW_ZOOM_STATE,
selectDragging,
selectPanPointer,
transitionPreviewZoom,
type PreviewZoomEffect,
type PreviewZoomEvent,
type PreviewZoomState,
} from "./image-zoom-machine"
function replay(events: PreviewZoomEvent[], from = INITIAL_PREVIEW_ZOOM_STATE) {
return events.reduce<{ state: PreviewZoomState; effects: PreviewZoomEffect[] }>(
(result, event) => {
const next = transitionPreviewZoom(result.state, event)
return { state: next.state, effects: [...result.effects, ...next.effects] }
},
{ state: from, effects: [] },
)
}
function down(target: "viewport" | "video" | "content", options: { zoomed?: boolean; onBackdrop?: boolean } = {}) {
return {
type: "pointer.down",
pointerId: 1,
button: 0,
target,
onBackdrop: options.onBackdrop ?? false,
zoomed: options.zoomed ?? true,
} satisfies PreviewZoomEvent
}
const moved = { type: "pointer.moved", pointerId: 1 } satisfies PreviewZoomEvent
const up = { type: "pointer.up", pointerId: 1 } satisfies PreviewZoomEvent
describe("image preview zoom gesture", () => {
// Bug: nothing ended a pan whose pointer capture was lost without a pointerup, so plain hover with the same mouse
// pointer kept panning the image under a grabbing cursor. The driver sends `pointer.cancel` on lostpointercapture
// and on a move with the primary button up.
test("a pan that loses its pointer ends", () => {
const panning = replay([down("viewport"), moved])
expect(selectDragging(panning.state)).toBe(true)
expect(panning.effects).toEqual([{ type: "pointer.capture", target: "viewport", pointerId: 1 }])
const ended = transitionPreviewZoom(panning.state, { type: "pointer.cancel", pointerId: 1 })
expect(selectDragging(ended.state)).toBe(false)
expect(selectPanPointer(ended.state, 1)).toBe(false)
expect(ended.effects).toEqual([{ type: "pointer.release", target: "viewport", pointerId: 1 }])
expect(transitionPreviewZoom(ended.state, moved).state).toBe(ended.state)
})
// Bug: Escape or 0 during a press glided back to fit and left the pan, and its grabbing cursor, on a fitted image.
test("an eased zoom takes over from a pan", () => {
const glide = replay([down("viewport"), moved, { type: "glide.start" }])
expect(glide.state).toEqual({ status: "gliding", gesture: { type: "idle" } })
expect(glide.effects.slice(1)).toEqual([
{ type: "pointer.release", target: "viewport", pointerId: 1 },
{ type: "glide.loop.start" },
])
})
test("a press does not stop a glide, the hand moving does, and a pan ends once the image is back at fit", () => {
const pressed = replay([{ type: "glide.start" }, down("viewport")])
expect(pressed.state.status).toBe("gliding")
expect(selectDragging(pressed.state)).toBe(true)
const followed = transitionPreviewZoom(pressed.state, { type: "follow", zoomed: true })
expect(followed.state.status).toBe("still")
expect(followed.effects).toEqual([{ type: "glide.loop.stop" }])
const settled = transitionPreviewZoom(pressed.state, { type: "glide.settled", zoomed: false })
expect(settled.state).toEqual({ status: "still", gesture: { type: "idle" } })
expect(settled.effects).toEqual([
{ type: "glide.loop.stop" },
{ type: "pointer.release", target: "viewport", pointerId: 1 },
])
})
// Bug: the "panned" flag outlived its gesture, so a later click on the video's controls was swallowed.
test("only the release of a moved video pan swallows its click", () => {
expect(replay([down("video"), moved, up]).effects.at(-1)).toEqual({ type: "video.suppress-click" })
expect(replay([down("video"), up]).effects).toEqual([{ type: "pointer.capture", target: "video", pointerId: 1 }])
expect(replay([down("video"), moved, { type: "pointer.cancel", pointerId: 1 }]).effects.at(-1)).toEqual({
type: "pointer.release",
target: "video",
pointerId: 1,
})
})
test.each([
["an unzoomed press on the backdrop closes", [down("viewport", { zoomed: false, onBackdrop: true })], true],
["a press on the band around the body closes", [down("content", { onBackdrop: true })], true],
["a zoomed press on the backdrop that stays put closes", [down("viewport", { onBackdrop: true }), up], true],
[
"a zoomed press on the backdrop that stays put, then loses capture, closes",
[down("viewport", { onBackdrop: true }), up, { type: "pointer.cancel", pointerId: 1 } satisfies PreviewZoomEvent],
true,
],
["a zoomed press on the image, whose captured click lands on the backdrop, stays", [down("viewport"), up], false],
["a zoomed press on the backdrop that pans stays", [down("viewport", { onBackdrop: true }), moved, up], false],
["a press on a control stays", [down("content")], false],
])("on its click, %s", (_, events, closes) => {
const pressed = replay(events)
const clicked = transitionPreviewZoom(pressed.state, { type: "backdrop.click", onBackdrop: true })
expect(clicked.effects).toEqual(closes ? [{ type: "dialog.close" }] : [])
})
test("a secondary button or a second pointer leaves the pan alone; the same pointer again starts over", () => {
const panning = replay([down("viewport"), moved]).state
expect(transitionPreviewZoom(panning, { ...down("viewport"), pointerId: 2 }).state).toBe(panning)
expect(transitionPreviewZoom(panning, { type: "pointer.up", pointerId: 2 }).state).toBe(panning)
expect(transitionPreviewZoom(INITIAL_PREVIEW_ZOOM_STATE, { ...down("viewport"), button: 2 }).state).toBe(
INITIAL_PREVIEW_ZOOM_STATE,
)
const again = transitionPreviewZoom(panning, down("viewport"))
expect(again.state).toEqual({
status: "still",
gesture: { type: "panning", pointerId: 1, target: "viewport", onBackdrop: false, moved: false },
})
expect(again.effects).toEqual([{ type: "pointer.capture", target: "viewport", pointerId: 1 }])
})
test("moves that change nothing answer with the same transition, so a pan allocates nothing", () => {
const panning = replay([down("viewport"), moved]).state
const first = transitionPreviewZoom(panning, moved)
expect(first.state).toBe(panning)
expect(transitionPreviewZoom(panning, moved)).toBe(first)
expect(transitionPreviewZoom(panning, { type: "follow", zoomed: true })).toBe(first)
})
test("disposal releases the pan and stops the glide, then ignores everything", () => {
const busy: PreviewZoomState = {
status: "gliding",
gesture: { type: "panning", pointerId: 1, target: "video", onBackdrop: false, moved: false },
}
const disposed = transitionPreviewZoom(busy, { type: "disposed" })
expect(disposed.effects).toEqual([
{ type: "pointer.release", target: "video", pointerId: 1 },
{ type: "glide.loop.stop" },
])
expect(transitionPreviewZoom(disposed.state, { type: "glide.start" }).effects).toEqual([])
})
})
@@ -0,0 +1,191 @@
/** The element a pan captures the pointer on: the preview's body for an image, the borrowed video for a video. */
export type PanTarget = "viewport" | "video"
/**
* The press under way. A `backdrop-press` began on the backdrop around the image and stayed put, so the click that ends
* it closes the preview. A pan captures the pointer, so its click lands on the backdrop wherever it began: `onBackdrop`
* says whether it began there, and `moved` whether it has moved, so the click that ends a moved pan neither closes the
* preview nor plays the video.
*/
export type PreviewZoomGesture =
| { readonly type: "idle" }
| { readonly type: "backdrop-press" }
| {
readonly type: "panning"
readonly pointerId: number
readonly target: PanTarget
readonly onBackdrop: boolean
readonly moved: boolean
}
/**
* `gliding` is an eased zoom under way on the frame loop. Scale and offsets live on springs in the driver, not here: a
* frame of a glide or a pan writes no state. A press does not stop a glide, so a third click of a double-click zoom
* leaves it running; the hand moving does.
*/
export type PreviewZoomState =
| { readonly status: "still" | "gliding"; readonly gesture: PreviewZoomGesture }
| { readonly status: "disposed" }
/** `zoomed` is whether the image shows above fit once the event's change applies. */
export type PreviewZoomEvent =
| {
readonly type: "pointer.down"
readonly pointerId: number
readonly button: number
/** `content` is anywhere in the preview but its body, such as the band around it or the controls. */
readonly target: PanTarget | "content"
readonly onBackdrop: boolean
readonly zoomed: boolean
}
| { readonly type: "pointer.moved"; readonly pointerId: number }
| { readonly type: "pointer.up"; readonly pointerId: number }
/** `pointercancel`, `lostpointercapture`, or a move with the primary button already up: the pan ends unreleased. */
| { readonly type: "pointer.cancel"; readonly pointerId: number }
| { readonly type: "backdrop.click"; readonly onBackdrop: boolean }
/** Pinch, wheel, drag or a resize set the view directly. */
| { readonly type: "follow"; readonly zoomed: boolean }
| { readonly type: "glide.start" }
| { readonly type: "glide.settled"; readonly zoomed: boolean }
| { readonly type: "disposed" }
export type PreviewZoomEffect =
| { readonly type: "pointer.capture"; readonly target: PanTarget; readonly pointerId: number }
| { readonly type: "pointer.release"; readonly target: PanTarget; readonly pointerId: number }
| { readonly type: "glide.loop.start" }
| { readonly type: "glide.loop.stop" }
/** Swallows the click that ends a moved pan over the video, so it does not play or pause it. */
| { readonly type: "video.suppress-click" }
| { readonly type: "dialog.close" }
export type PreviewZoomTransition = {
readonly state: PreviewZoomState
readonly effects: readonly PreviewZoomEffect[]
}
const IDLE: PreviewZoomGesture = Object.freeze({ type: "idle" })
const BACKDROP_PRESS: PreviewZoomGesture = Object.freeze({ type: "backdrop-press" })
const NONE: readonly PreviewZoomEffect[] = Object.freeze([])
export const INITIAL_PREVIEW_ZOOM_STATE: PreviewZoomState = Object.freeze({ status: "still", gesture: IDLE })
const DISPOSED: PreviewZoomState = Object.freeze({ status: "disposed" })
export function transitionPreviewZoom(state: PreviewZoomState, event: PreviewZoomEvent): PreviewZoomTransition {
if (state.status === "disposed") return unchanged(state)
const gliding = state.status === "gliding"
const pan = state.gesture.type === "panning" ? state.gesture : undefined
if (event.type === "disposed") {
return { state: DISPOSED, effects: [...release(pan), ...(gliding ? [{ type: "glide.loop.stop" } as const] : [])] }
}
if (event.type === "pointer.down") {
// A second pointer leaves the pan alone; the same pointer pressing again means its release never arrived.
if (pan && pan.pointerId !== event.pointerId) return unchanged(state)
if (event.button === 0 && event.zoomed && event.target !== "content") {
return {
state: {
status: state.status,
gesture: {
type: "panning",
pointerId: event.pointerId,
target: event.target,
onBackdrop: event.onBackdrop,
moved: false,
},
},
effects: [{ type: "pointer.capture", target: event.target, pointerId: event.pointerId }],
}
}
return gesture(state, event.button === 0 && event.onBackdrop ? BACKDROP_PRESS : IDLE)
}
if (event.type === "pointer.moved") {
if (pan?.pointerId !== event.pointerId || pan.moved) return unchanged(state)
return gesture(state, { ...pan, onBackdrop: false, moved: true })
}
if (event.type === "pointer.up") {
if (pan?.pointerId !== event.pointerId) return unchanged(state)
if (pan.moved && pan.target === "video") {
return { state: { status: state.status, gesture: IDLE }, effects: [{ type: "video.suppress-click" }] }
}
return gesture(state, !pan.moved && pan.onBackdrop ? BACKDROP_PRESS : IDLE)
}
if (event.type === "pointer.cancel") {
if (pan?.pointerId !== event.pointerId) return unchanged(state)
return { state: { status: state.status, gesture: IDLE }, effects: release(pan) }
}
if (event.type === "backdrop.click") {
if (state.gesture.type !== "backdrop-press") return unchanged(state)
return {
state: { status: state.status, gesture: IDLE },
effects: event.onBackdrop ? [{ type: "dialog.close" }] : NONE,
}
}
// An eased zoom takes over from a pan, so a pan never outlives a zoom back to fit.
if (event.type === "glide.start") {
if (gliding && !pan) return unchanged(state)
return {
state: { status: "gliding", gesture: pan ? IDLE : state.gesture },
effects: [...release(pan), ...(gliding ? [] : [{ type: "glide.loop.start" } as const])],
}
}
if (event.type === "glide.settled" && !gliding) return unchanged(state)
// The hand takes over from an eased zoom; a pan ends once the image is back at fit.
const ends = pan && !event.zoomed ? pan : undefined
if (!gliding && !ends) return unchanged(state)
return {
state: { status: "still", gesture: ends ? IDLE : state.gesture },
effects: [...(gliding ? [{ type: "glide.loop.stop" } as const] : []), ...release(ends)],
}
}
/** Whether a pan holds the pointer, which shows the grabbing cursor. */
export function selectDragging(state: PreviewZoomState) {
return state.status !== "disposed" && state.gesture.type === "panning"
}
/** Whether `pointerId` is the pointer the pan under way follows. */
export function selectPanPointer(state: PreviewZoomState, pointerId: number) {
return state.status !== "disposed" && state.gesture.type === "panning" && state.gesture.pointerId === pointerId
}
function gesture(state: Exclude<PreviewZoomState, { status: "disposed" }>, next: PreviewZoomGesture) {
if (state.gesture === next) return unchanged(state)
return { state: { status: state.status, gesture: next }, effects: NONE }
}
function release(pan: Extract<PreviewZoomGesture, { type: "panning" }> | undefined): readonly PreviewZoomEffect[] {
if (!pan) return NONE
return [{ type: "pointer.release", target: pan.target, pointerId: pan.pointerId }]
}
// Every pointer move of a pan dispatches events that change nothing; answering them with the transition already built
// for that state keeps the hot path allocation-free.
let last: PreviewZoomTransition = Object.freeze({ state: DISPOSED, effects: NONE })
function unchanged(state: PreviewZoomState) {
if (last.state !== state) last = Object.freeze({ state, effects: NONE })
return last
}
@@ -86,11 +86,11 @@ describe("viewBox", () => {
const natural = { width: 1600, height: 900 }
test("shows the whole frame at fit", () => {
expect(viewBox(FIT_VIEW, size, natural)).toBe("none")
expect(viewBox(1, 0, 0, size, natural)).toBe("none")
})
test("shows the middle half at 2x, and more of the left once panned right", () => {
expect(viewBox({ scale: 2, x: 0, y: 0 }, size, natural)).toBe("inset(225px 400px 225px 400px)")
expect(viewBox({ scale: 2, x: 200, y: 0 }, size, natural)).toBe("inset(225px 600px 225px 200px)")
expect(viewBox(2, 0, 0, size, natural)).toBe("inset(225px 400px 225px 400px)")
expect(viewBox(2, 200, 0, size, natural)).toBe("inset(225px 600px 225px 200px)")
})
})
+22 -14
View File
@@ -59,26 +59,25 @@ export function detailScale(fitRatio: number) {
}
/**
* The `object-view-box` that shows `view` of media fitted at `size`, for media that must zoom inside its own box, such
* as a video under its controls. The inset is in the media's natural pixels.
* The `object-view-box` that shows the view at `scale`, `x` and `y` of media fitted at `size`, for media that must zoom
* inside its own box, such as a video under its controls. The inset is in the media's natural pixels. It takes the view
* as numbers, so painting a frame of a glide allocates nothing but the string.
*/
export function viewBox(
view: ZoomView,
scale: number,
x: number,
y: number,
size: { width: number; height: number },
natural: { width: number; height: number },
) {
if (view.scale <= 1) return "none"
if (scale <= 1) return "none"
const edge = (offset: number, fitted: number) => 0.5 - 0.5 / view.scale - offset / (view.scale * fitted)
const top = px(edge(y, size.height, scale) * natural.height)
const right = px(edge(-x, size.width, scale) * natural.width)
const bottom = px(edge(-y, size.height, scale) * natural.height)
const left = px(edge(x, size.width, scale) * natural.width)
const inset = [
edge(view.y, size.height) * natural.height,
edge(-view.x, size.width) * natural.width,
edge(-view.y, size.height) * natural.height,
edge(view.x, size.width) * natural.width,
]
return `inset(${inset.map((value) => `${Math.max(0, Math.round(value * 100) / 100)}px`).join(" ")})`
return `inset(${top} ${right} ${bottom} ${left})`
}
/** The zoom factor for one wheel event, bounded so a coarse mouse-wheel notch is a step rather than a jump. */
@@ -86,13 +85,22 @@ export function wheelZoomFactor(deltaY: number) {
return Math.exp(-clamp(deltaY, -30, 30) / 100)
}
function clampAxis(offset: number, size: number, viewport: number) {
/** Keeps one axis of a zoomed image of `size` covering a `viewport` it overflows, and centered in one it fits. */
export function clampAxis(offset: number, size: number, viewport: number) {
const limit = Math.max(0, (size - viewport) / 2)
// Adding zero turns -0 into 0.
return clamp(offset, -limit, limit) + 0
}
function edge(offset: number, fitted: number, scale: number) {
return 0.5 - 0.5 / scale - offset / (scale * fitted)
}
function px(value: number) {
return `${Math.max(0, Math.round(value * 100) / 100)}px`
}
function clamp(value: number, min: number, max: number) {
return Math.min(Math.max(value, min), max)
}