feat(editor): two-finger pan, touch hint, loupe, touch-sized handles

useFraming gains twoPointerPan (the editor's pinch also pans by the
midpoint and scales from the spread since the pinch began; the
catalogue passes nothing). A futile one-finger drag shows the R-1
hint unless two fingers already worked in this editor visit (work
store flag). A finger drag of a handle shows the loupe (technique A:
the drawing copied once, data-anno-id stripped, outline on top).
editor-touch.spec covers 1 024, 1 180 and 1 280 px with CDP touch.
measure-drag.ts is the hand-run smoothness measure (MEASURE_DRAG=1).
equineShape moved from editor-zones.spec to support/editor.ts, no
assertion changed.
This commit is contained in:
bchanot committed 2026-11-18 10:54:46 +01:00
1 parent 3a7715486b
commit 85231a2680
18 files changed
+1338 -53

No files matched your search

+70 -10
View File
@@ -30,6 +30,17 @@ export interface FramingOptions {
* caller tells a drag from a click), replacing the 4 px threshold and `canPan`.
*/
panning?: () => boolean
/**
* The editor's pinch: two fingers also pan by their midpoint's movement, and the scale
* follows the fingers' spread since the pinch began (a clamp at the fit never ratchets).
*/
twoPointerPan?: boolean
}
/** Where a pinch began: its spread and the scale then. */
interface PinchStart {
spread: number
scale: number
}
function boxOf(
@@ -48,6 +59,42 @@ function distance(a: Point, b: Point): number {
return Math.hypot(a.x - b.x, a.y - b.y)
}
const midpoint = (a: Point, b: Point, box: { left: number; top: number }) => ({
x: (a.x + b.x) / 2 - box.left,
y: (a.y + b.y) / 2 - box.top,
})
/** The pinch's base, taken whenever exactly two pointers are down. */
function pinchStart(
pointers: Map<number, Point>,
scale: number,
): PinchStart | null {
if (pointers.size !== 2) return null
const [a, b] = [...pointers.values()]
return { spread: Math.max(distance(a, b), 1), scale }
}
/**
* One finger of a two-finger pan moved from `before` to `now`: the drawing scales around
* the old midpoint to the spread's scale, then follows the midpoint (half the move).
*/
function pinchPan(
framing: Framing,
start: PinchStart,
fingers: { before: Point; now: Point; other: Point },
box: Box & { left: number; top: number },
): Framing {
const { before, now, other } = fingers
const target = (start.scale * distance(now, other)) / start.spread
const zoomed = zoomBy(
framing,
target / framing.scale,
box,
midpoint(before, other, box),
)
return panBy(zoomed, (now.x - before.x) / 2, (now.y - before.y) / 2, box)
}
/** One-pointer pan: the caller's gate when it gives one, else past the threshold and allowed. */
function pansNow(
gate: (() => boolean) | undefined,
@@ -81,6 +128,9 @@ export function useFraming(
canPan.current = options.canPan
const panning = useRef(options.panning)
panning.current = options.panning
const twoPointerPan = useRef(options.twoPointerPan ?? false)
twoPointerPan.current = options.twoPointerPan ?? false
const pinch = useRef<PinchStart | null>(null)
useEffect(() => setFraming(FIT), [resetKey])
useEffect(() => {
@@ -128,8 +178,25 @@ export function useFraming(
dragged.current = false
panAllowed.current = canPan.current?.(event) ?? true
}
pinch.current = pinchStart(pointers.current, scale.current)
}, [])
const pinchMove = useCallback(
(fingers: { before: Point; now: Point; other: Point }) => {
const box = boxOf(viewport.current)
const start = pinch.current
if (twoPointerPan.current && start) {
setFraming((f) => pinchPan(f, start, fingers, box))
return
}
const { now, other } = fingers
const factor =
distance(now, other) / Math.max(distance(fingers.before, other), 1)
zoom(factor, midpoint(now, other, box))
},
[viewport, zoom],
)
const onPointerMove = useCallback(
(event: PointerEvent) => {
const before = pointers.current.get(event.pointerId)
@@ -142,15 +209,7 @@ export function useFraming(
moved.current += distance(before, now)
if (moved.current > DRAG_THRESHOLD) dragged.current = true
if (others.length === 1) {
const other = others[0][1]
const box = boxOf(viewport.current)
const at = {
x: (now.x + other.x) / 2 - box.left,
y: (now.y + other.y) / 2 - box.top,
}
const factor =
distance(now, other) / Math.max(distance(before, other), 1)
zoom(factor, at)
pinchMove({ before, now, other: others[0][1] })
} else if (
others.length === 0 &&
pansNow(panning.current, dragged, panAllowed)
@@ -159,11 +218,12 @@ export function useFraming(
pan(now.x - before.x, now.y - before.y)
}
},
[viewport, zoom, pan],
[pinchMove, pan],
)
const onPointerUp = useCallback((event: PointerEvent) => {
pointers.current.delete(event.pointerId)
pinch.current = pinchStart(pointers.current, scale.current)
}, [])
const onKeyDown = useCallback(
@@ -27,6 +27,7 @@ import type { ToolId } from '@/editor/annotations/uiState'
import { useT } from '@/i18n/useT'
import AnnotationOverlay, { type OverlayProps } from './AnnotationOverlay'
import HandleLayer, { type HandleLayerProps } from './HandleLayer'
import Loupe from './Loupe'
import ToolColumn, { type ToolColumnProps } from './ToolColumn'
type OverlayData = Omit<
@@ -64,6 +65,8 @@ export interface AnnotationCanvasProps {
onDrop: Drop
onHandle: (action: HandleAction) => void
onDeselect: () => void
/** A one-finger drag off the handles moved nothing (R-1). */
onFutileDrag: () => void
onTraceKey: (event: KeyboardEvent) => void
}
@@ -99,6 +102,7 @@ export default function AnnotationCanvas(props: AnnotationCanvasProps) {
build={build}
viewport={viewport}
boxProps={withPreview(gestures.boxProps, preview)}
finger={gestures.finger}
layer={{
transform: transformOf(gestures.framing.framing),
overlay: {
@@ -160,14 +164,18 @@ function CanvasBox({
viewName,
tool,
creating,
selectedId,
build,
viewport,
boxProps,
finger,
layer,
}: AnnotationCanvasProps & {
build: Build
viewport: RefObject<HTMLDivElement | null>
boxProps: BoxProps
/** A finger's drag in flight: the loupe above it (board 13). */
finger: XY | null
layer: Omit<LayerProps, 'host' | 'root'>
}) {
const root = build.root?.viewId === viewId ? build.root : null
@@ -186,6 +194,17 @@ function CanvasBox({
>
<DrawingLayer host={build.host} root={root} {...layer} />
</div>
{finger && root && (
<Loupe
finger={finger}
viewport={viewport}
host={build.host}
transform={layer.transform}
root={root}
selectedId={selectedId}
dragged={layer.overlay.dragged}
/>
)}
<CanvasFailure failure={build.failure} retry={build.retry} />
</div>
)
@@ -29,7 +29,7 @@ export interface OverlayProps {
const STROKE = { fill: 'none', vectorEffect: 'non-scaling-stroke' } as const
function Outline({
export function Outline({
geometry,
dashed,
colour,
@@ -55,7 +55,13 @@ function Outline({
return null
}
function Vertices({ geometry, size }: { geometry: Geometry; size: number }) {
export function Vertices({
geometry,
size,
}: {
geometry: Geometry
size: number
}) {
if (geometry.type !== 'polygon') return null
return (
<>
@@ -184,7 +190,7 @@ function TracingPath({ points, size }: { points: Point[]; size: number }) {
}
/** The selection's pending preview (move mode, slider, keys), read without the tab. */
function usePreviewOf(selectedId: string | null): Geometry | null {
export function usePreviewOf(selectedId: string | null): Geometry | null {
return useAnnotationWork((s) =>
selectedId !== null && s.preview?.annotationId === selectedId
? s.preview.geometry
@@ -34,7 +34,10 @@ import {
type OpenDialog,
} from '@/editor/annotations/dialogOpening'
import { creationStart, usePlacement } from '@/editor/annotations/usePlacement'
import { useGestureMessage } from '@/editor/annotations/useGestureMessage'
import {
useGestureMessage,
type GestureMessages,
} from '@/editor/annotations/useGestureMessage'
import {
initialUi,
uiReducer,
@@ -177,6 +180,12 @@ function useScene(props: Props): Scene {
}
}
/** R-1: a finger dragged off the handles, unless two fingers already worked in this visit. */
function hintTwoFingers(message: GestureMessages, t: CommitContext['t']) {
if (useAnnotationWork.getState().twoFingers) return
message.hint(t('editor.annotations.message.two_fingers'))
}
function useCommitContext(): CommitContext {
const t = useT()
const locale = useLocaleStore((s) => s.locale)
@@ -353,6 +362,7 @@ function CanvasStage({
onDrop={work.placement.onDrop}
onHandle={work.zone.onHandle}
onDeselect={() => free && onDeselect()}
onFutileDrag={() => hintTwoFingers(work.message, work.context.t)}
onTraceKey={work.placement.onTraceKey}
/>
)
@@ -0,0 +1,156 @@
import { useLayoutEffect, useRef, useState, type RefObject } from 'react'
import type { Geometry } from '@faunosteo/core-wasm/types'
import { parseFrame, type XY } from '@/editor/annotations/frame'
import type { RootAttributes } from '@/editor/annotations/useCanvasBuild'
import { Outline, usePreviewOf, Vertices } from './AnnotationOverlay'
/** Board 13: a 120 px disc, its centre 90 px above the finger, twice the size on screen. */
const SIZE = 120
const LIFT = 90
const ZOOM = 2
export interface LoupeProps {
/** The finger's client point. */
finger: XY
/** The canvas box: the disc stays inside it. */
viewport: RefObject<HTMLDivElement | null>
/** The core's drawing, copied once when the loupe opens. */
host: RefObject<HTMLDivElement | null>
/** The framing's transform of the drawing layer. */
transform: string
root: RootAttributes
selectedId: string | null
/** The canvas-local drag preview; a move-mode drag previews through the work store. */
dragged: Geometry | null
}
interface Box {
left: number
top: number
width: number
height: number
}
const clamp = (value: number, max: number) =>
Math.min(Math.max(value, 0), Math.max(max, 0))
/** The box read once: a finger's drag never scrolls the page (`touch-action: none`). */
function useBoxAtOpen(viewport: RefObject<HTMLDivElement | null>) {
const [box, setBox] = useState<Box | null>(null)
useLayoutEffect(() => {
const rect = viewport.current?.getBoundingClientRect()
if (rect) setBox(rect)
}, [viewport])
return box
}
/**
* The drawing copied once into `into`: a picture, so every `data-anno-id` is removed and
* no press or locator ever reads the copy as a marker.
*/
function usePicture(
host: RefObject<HTMLDivElement | null>,
into: RefObject<HTMLDivElement | null>,
) {
useLayoutEffect(() => {
const drawing = host.current?.querySelector('svg')
if (!drawing || !into.current) return
const copy = drawing.cloneNode(true) as SVGSVGElement
for (const marked of [copy, ...copy.querySelectorAll('[data-anno-id]')]) {
marked.removeAttribute('data-anno-id')
}
into.current.replaceChildren(copy)
}, [host, into])
}
/** The disc's place in the box and the content's offset that centres it on the finger. */
function placeOf(finger: XY, box: Box) {
const x = finger.x - box.left
const y = finger.y - box.top
const half = SIZE / 2
return {
disc: {
x: clamp(x - half, box.width - SIZE),
y: clamp(y - LIFT - half, box.height - SIZE),
},
content: { x: half - ZOOM * x, y: half - ZOOM * y },
}
}
// `svg-canvas`: the copy's markers keep the canvas's look (the selection's mark).
const DISC =
'svg-canvas pointer-events-none absolute top-0 left-0 z-10 overflow-hidden ' +
'rounded-full border-2 border-[var(--color-ink)] bg-white shadow-lg'
const translate = (at: XY | undefined) =>
`translate(${at?.x ?? 0}px, ${at?.y ?? 0}px)`
/**
* The loupe of a finger's drag (board 13, docs/ANNOTATION-RENDERING.md « Editor overlay »):
* what the finger hides, at twice the size, with the preview outline on top. It never
* takes the pointer and is hidden from assistive technologies.
*/
export default function Loupe(props: LoupeProps) {
const picture = useRef<HTMLDivElement | null>(null)
const box = useBoxAtOpen(props.viewport)
usePicture(props.host, picture)
const preview = usePreviewOf(props.selectedId)
const outline = props.dragged ?? preview
const place = box ? placeOf(props.finger, box) : null
return (
<div
data-testid="loupe"
aria-hidden="true"
inert
className={DISC}
style={{
width: SIZE,
height: SIZE,
transform: translate(place?.disc),
visibility: place ? 'visible' : 'hidden',
}}
>
<div
className="origin-top-left"
style={{
width: box?.width,
height: box?.height,
transform: `${translate(place?.content)} scale(${ZOOM})`,
}}
>
<div
className="relative h-full w-full origin-top-left"
style={{ transform: props.transform }}
>
<div
ref={picture}
className="h-full w-full [&>svg]:block [&>svg]:h-full [&>svg]:w-full"
/>
<LoupeOutline root={props.root} outline={outline} />
</div>
</div>
</div>
)
}
function LoupeOutline({
root,
outline,
}: {
root: RootAttributes
outline: Geometry | null
}) {
const frame = parseFrame(root.viewBox)
if (!outline || !root.viewBox) return null
const size = frame ? Math.max(frame.w, frame.h) / 200 : 1
return (
<svg
viewBox={root.viewBox}
preserveAspectRatio={root.ratio}
className="absolute inset-0 h-full w-full"
>
<Outline geometry={outline} dashed={false} colour="var(--color-accent)" />
<Vertices geometry={outline} size={size} />
</svg>
)
}
@@ -135,6 +135,49 @@ function dragActions(
return { start, follow, drop, cancel }
}
type Actions = ReturnType<typeof dragActions>
/**
* The client point of a finger's drag, for the loupe (board 13): set when the drag really
* starts, followed, cleared by the drop and by every cancel. A mouse or pen sets nothing.
*/
function useFinger(drag: RefObject<Drag | null>, actions: Actions) {
const [finger, setFinger] = useState<XY | null>(null)
const touch = useRef(false)
// A mouse drag never set a finger: no state update (and no render) at its end.
const end = () => {
if (!touch.current) return
touch.current = false
setFinger(null)
}
return {
finger,
start: (
pressedAt: XY,
client: XY,
mode: boolean,
vertex: number | null,
byFinger: boolean,
) => {
actions.start(pressedAt, client, mode, vertex)
touch.current = byFinger && drag.current !== null
if (touch.current) setFinger(client)
},
follow: (client: XY) => {
actions.follow(client)
if (touch.current && drag.current) setFinger(client)
},
drop: (client: XY) => {
end()
actions.drop(client)
},
cancel: () => {
end()
actions.cancel()
},
}
}
/**
* The selection moved as a block (`drag_shape`, `drag_point`) or one of its vertices
* (`drag_vertex`): the overlay previews the outline, kept local to the canvas for speed;
@@ -144,7 +187,7 @@ function dragActions(
export function useBlockDrag(input: BlockDragInput) {
const drag = useRef<Drag | null>(null)
const [preview, setPreview] = useState<Geometry | null>(null)
const actions = dragActions(input, drag, setPreview)
const actions = useFinger(drag, dragActions(input, drag, setPreview))
useDropOnChange(input.target, actions.cancel)
return { preview, ...actions }
}
@@ -1,7 +1,15 @@
import type { CSSProperties, KeyboardEvent, PointerEvent } from 'react'
import {
useEffect,
useRef,
type CSSProperties,
type KeyboardEvent,
type PointerEvent,
} from 'react'
import type { Framing as Frame } from '@/catalogue/framing'
import { useFraming } from '@/catalogue/useFraming'
import type { ToolId } from './uiState'
import { usePressGesture, type PressInput } from './usePressGesture'
import { markTwoFingers } from './workStore'
export interface GestureInput extends PressInput {
viewId: string
@@ -50,6 +58,24 @@ function touchStyle(
return { touchAction: none ? 'none' : 'pan-x pan-y' }
}
const sameFrame = (a: Frame, b: Frame) =>
a.scale === b.scale && a.x === b.x && a.y === b.y
/**
* R-1: a framing that changed while two pointers or more were down is a two-finger pan or
* zoom that worked; the editor visit then never shows the two-finger hint again.
*/
function useTwoFingersWorked(framing: Frame, multi: () => boolean): void {
const last = useRef(framing)
const isMulti = useRef(multi)
isMulti.current = multi
useEffect(() => {
const changed = !sameFrame(last.current, framing)
last.current = framing
if (changed && isMulti.current()) markTwoFingers()
}, [framing])
}
/**
* Everything the canvas box listens to: zoom and pan, the press machine (click, drag,
* tap), and the keys. Keys only count when the box itself is the target: Enter on
@@ -62,7 +88,9 @@ export function useCanvasGestures(input: GestureInput) {
// The press machine decides: the drawing pans only while the press is a pan, so one
// press is either a pan or a click, never both (R-8).
panning: () => input.tool === 'select' && press.panning(),
twoPointerPan: true,
})
useTwoFingersWorked(framing.framing, press.multi)
const onKeyDown = (event: KeyboardEvent) => {
if (event.target !== event.currentTarget) return
framing.handlers.onKeyDown(event)
@@ -71,6 +99,7 @@ export function useCanvasGestures(input: GestureInput) {
return {
framing,
drag: press.preview,
finger: press.finger,
boxProps: {
...composedPointer(framing, press),
onKeyDown,
@@ -40,6 +40,8 @@ export interface PressInput extends BlockDragInput {
onHandle: (action: HandleAction) => void
/** A tap on the empty drawing with the select tool. */
onDeselect: () => void
/** A one-finger drag that moved nothing ended (R-1: the two-finger hint). */
onFutileDrag: () => void
}
const clientOf = (event: { clientX: number; clientY: number }): XY => ({
@@ -206,7 +208,9 @@ function applyEffect(f: Feed, effect: PressEffect, event: PointerEvent | null) {
const { action } = effect
const vertex = action.type === 'drag_vertex' ? action.index : null
const mode = action.type === 'drag_mode'
f.drag.start(f.machine.current.pressedAt, clientOf(event), mode, vertex)
const finger = pointerKindOf(event.pointerType) === 'touch'
const { pressedAt } = f.machine.current
f.drag.start(pressedAt, clientOf(event), mode, vertex, finger)
}
}
@@ -222,13 +226,19 @@ const contextOf = (input: PressInput) => ({
moveMode: inMoveMode(),
})
/** A drag that ends having moved nothing (`none` with `futile`): a finger off the handles. */
const isFutile = (press: Press) =>
press.phase === 'drag' && press.action.type === 'none' && press.action.futile
/** One event through the machine and its effect; at idle the press is over. */
function feed(f: Feed, event: PressEvent, pointer: PointerEvent | null) {
const m = f.machine.current
const context = contextOf(f.input)
const step = stepPress(m.press, event, context)
const futile = step.effect?.type === 'drag_end' && isFutile(m.press)
m.press = step.press
applyEffect(f, step.effect, pointer)
if (futile) f.input.onFutileDrag()
if (m.press.phase !== 'idle') return
m.pointers.clear()
m.stop?.()
@@ -358,6 +368,9 @@ export function usePressGesture(input: PressInput) {
const cancel = () => feed(latest.current, { type: 'cancel' }, null)
return {
preview: drag.preview,
finger: drag.finger,
/** Two pointers or more are down: a pan or zoom of the fingers, never a click. */
multi: () => machine.current.press.phase === 'multi',
panning: () => {
const press = machine.current.press
return press.phase === 'drag' && press.action.type === 'pan'
@@ -74,6 +74,8 @@ interface Work {
*/
dropped: ModeWork['kind'] | 'creation' | null
question: DrawingQuestion | null
/** A two-finger pan or zoom worked in this editor visit: the hint never shows again (R-1). */
twoFingers: boolean
}
const NO_WORK: Work = {
creation: null,
@@ -84,6 +86,7 @@ const NO_WORK: Work = {
chosen: null,
dropped: null,
question: null,
twoFingers: false,
}
export const useAnnotationWork = create<Work>(() => NO_WORK)
@@ -172,6 +175,12 @@ export function dropStale(text: string): void {
})
}
export function markTwoFingers(): void {
if (!useAnnotationWork.getState().twoFingers) {
useAnnotationWork.setState({ twoFingers: true })
}
}
/** Another sheet opened, or the editor closed: nothing of the previous one survives. */
export function resetWork(): void {
useAnnotationWork.setState(NO_WORK)
+2
View File
@@ -1852,6 +1852,8 @@ export const en: Dict = {
'editor.annotations.move.vertex': 'Move vertex',
'editor.annotations.redraw': 'Redraw',
'editor.annotations.message.vertex_moved': 'Vertex moved',
'editor.annotations.message.two_fingers':
'Use two fingers to move or zoom the drawing',
'editor.annotations.message.vertex_added': 'Vertex added',
'editor.annotations.message.vertex_removed': 'Vertex removed',
'editor.annotations.message.vertex_min': 'A zone keeps at least 3 vertices',
+2
View File
@@ -1921,6 +1921,8 @@ export const fr: Dict = {
'editor.annotations.move.vertex': 'Déplacer le sommet',
'editor.annotations.redraw': 'Redessiner',
'editor.annotations.message.vertex_moved': 'Sommet déplacé',
'editor.annotations.message.two_fingers':
'Deux doigts pour déplacer ou zoomer le dessin',
'editor.annotations.message.vertex_added': 'Sommet ajouté',
'editor.annotations.message.vertex_removed': 'Sommet retiré',
'editor.annotations.message.vertex_min': 'Une zone garde au moins 3 sommets',