@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/controls/gestures.js

@@ -0,0 +1,98 @@
+import { useThree } from '@react-three/fiber';
+import { EventManager, Pan, Rotate, Tap } from 'mjolnir.js';
+import { useEffect } from 'react';
+import { hotState } from '../utils/hot-state';
+/**
+ * Subscribes to one of the canvas's gestures for as long as the component is mounted.
+ *
+ * **Two fingers are why any of this exists.** camera-controls recognizes a pinch and an orbit, but
+ * neither of the two-finger gestures the plan needs: a twist that turns the plan about the point
+ * between the fingers, and a vertical drag that tilts it. Both come off `mjolnir.js`, whose
+ * recognizer configuration is the imperative renderer's verbatim — as does the double tap that
+ * `Zoom` zooms on, which camera-controls does not recognize either.
+ *
+ * The recognizer itself is shared: `Roll`, `Pitch` and `Zoom` want one on the same canvas, and two would
+ * mean two sets of pointer listeners racing over the same fingers. It is built on the first
+ * subscription and torn down with the last, since it attaches its listeners in its constructor and
+ * offers no disconnect. Every recognizer stays dormant until something subscribes to its event, so
+ * mounting `Roll` is literally what turns `rotate` on.
+ * @param type - The gesture event to listen for, e.g. `rotatestart`.
+ * @param handler - What to run when it fires. Re-subscribes whenever its identity changes, so build
+ *   it where the React Compiler can cache it against what it captures.
+ */
+export function useGesture(type, handler) {
+    // The canvas, not `state.events.connected`: R3F points its own pointer events at the canvas
+    // unless a caller names an `eventSource`, which this renderer never does.
+    const element = useThree((state) => state.gl.domElement);
+    useEffect(() => {
+        const manager = acquireGestureManager(element);
+        manager.on(type, handler);
+        return () => {
+            manager.off(type, handler);
+            releaseGestureManager(element);
+        };
+    }, [element, type, handler]);
+}
+/**
+ * Takes out a share in the canvas's recognizer, building it if this is the first.
+ *
+ * The plumbing behind {@link useGesture}, which is what a component uses; exported so the sharing
+ * and the teardown can be pinned by a spec. Every call must be paired with a release.
+ * @param element - The element to recognize on.
+ * @returns The manager.
+ */
+export function acquireGestureManager(element) {
+    const held = managers.get(element);
+    if (held) {
+        held.refs++;
+        return held.manager;
+    }
+    const manager = new EventManager(element, {
+        recognizers: [
+            Rotate,
+            [Pan, { event: 'pitch', pointers: 2 }, 'rotate'],
+            // A mouse's pointer events feed the recognizer as a finger's do, so one double tap is both
+            // the double-click and the double-tap. MapLibre's tap tolerances rather than the
+            // recognizer's own: a finger's second tap rarely lands within 10px of its first, and with
+            // the default `posThreshold` a real double tap on a phone was never recognized.
+            [Tap, { event: 'doubletap', taps: 2, interval: 500, time: 500, posThreshold: 30 }],
+        ],
+    });
+    managers.set(element, { manager, refs: 1 });
+    return manager;
+}
+/**
+ * Gives back a share taken out by {@link acquireGestureManager}, tearing the recognizer down once
+ * the last one is returned.
+ * @param element - The element it was acquired for.
+ */
+export function releaseGestureManager(element) {
+    const held = managers.get(element);
+    if (!held)
+        return;
+    if (--held.refs > 0)
+        return;
+    managers.delete(element);
+    held.manager.destroy();
+}
+/**
+ * Where one of a gesture's pointers sits on the canvas, in css pixels from its top-left corner.
+ *
+ * The one place a DOM event crosses into {@link CanvasPointLike}, which is why the assertion is
+ * written here rather than at each handler: `offsetX`/`offsetY` are canvas coordinates by
+ * definition, being measured from the target's own padding edge.
+ * @param event - One of the pointer events a gesture carries.
+ * @returns The point on the canvas.
+ */
+export function canvasPoint(event) {
+    return { x: event.offsetX, y: event.offsetY };
+}
+/**
+ * The live recognizers by the element they listen on, so the handlers sharing a canvas share one.
+ * Weak, so a canvas that goes away takes its entry with it.
+ *
+ * Kept across hot updates, because the ref count is the whole point of sharing: a fresh map would
+ * attach a second recognizer to a canvas that already has one, and every pan and pinch would be
+ * handled twice (see {@link hotState}).
+ */
+const managers = hotState(import.meta.hot, 'managers', () => new WeakMap());

package/dist/controls/handlers/DoubleTapZoom.d.ts

@@ -0,0 +1,23 @@
+/** Props for {@link DoubleTapZoom}. */
+export interface DoubleTapZoomProps {
+    /** What a double tap multiplies the zoom factor by. */
+    factor: number;
+}
+/**
+ * A double-click or double-tap: zooms by `factor` about the point under the pointer, which keeps
+ * its place on the canvas throughout.
+ *
+ * Mounted by `Zoom`, and only when a double-click is meant to zoom. One double tap is both the
+ * double-click and the double-tap: the gesture recognizer reads a mouse's pointer events as it
+ * reads a finger's.
+ *
+ * Run as a user transition, so it eases the way a wheel tick does — by `controlSmoothTime`, with the
+ * target on the dolly's clock — and reports itself as the user's hand.
+ *
+ * A component of its own rather than a branch inside `Zoom`, because subscribing is a hook and a
+ * hook cannot be switched off conditionally — mounting this is what switches it on.
+ * @param props - The zoom factor to multiply by.
+ * @returns Nothing; this renders no scene node.
+ */
+export declare function DoubleTapZoom(props: DoubleTapZoomProps): null;
+//# sourceMappingURL=DoubleTapZoom.d.ts.map

package/dist/controls/handlers/DoubleTapZoom.js

@@ -0,0 +1,82 @@
+import { useThree } from '@react-three/fiber';
+import { Spherical, Vector3 } from 'three';
+import { useSpace, } from '../../space/Space';
+import { clamp } from '../../utils/math';
+import { useGesture } from '../gestures';
+import { useCameraControls } from '../hooks';
+/**
+ * A double-click or double-tap: zooms by `factor` about the point under the pointer, which keeps
+ * its place on the canvas throughout.
+ *
+ * Mounted by `Zoom`, and only when a double-click is meant to zoom. One double tap is both the
+ * double-click and the double-tap: the gesture recognizer reads a mouse's pointer events as it
+ * reads a finger's.
+ *
+ * Run as a user transition, so it eases the way a wheel tick does — by `controlSmoothTime`, with the
+ * target on the dolly's clock — and reports itself as the user's hand.
+ *
+ * A component of its own rather than a branch inside `Zoom`, because subscribing is a hook and a
+ * hook cannot be switched off conditionally — mounting this is what switches it on.
+ * @param props - The zoom factor to multiply by.
+ * @returns Nothing; this renders no scene node.
+ */
+export function DoubleTapZoom(props) {
+    const { factor } = props;
+    const get = useThree((state) => state.get);
+    const invalidate = useThree((state) => state.invalidate);
+    const space = useSpace();
+    // Read, not written: `userTransition` takes the move as a callback, which does the writing.
+    const controls = useCameraControls();
+    const onDoubleTap = (event) => {
+        if (!controls)
+            return;
+        // mjolnir measures the tap from the target's own padding edge, as `canvasPoint` does.
+        const around = space.canvasToPlan(event.offsetCenter, get().camera);
+        if (!around)
+            return;
+        void controls.userTransition(() => zoomAbout(controls, space, factor, around));
+        // The move happens outside a React commit, so a demand frame loop has to be asked for a frame.
+        invalidate();
+    };
+    useGesture('doubletap', onDoubleTap);
+    return null;
+}
+/**
+ * Zooms by a factor about a point on the plan, which keeps its place on the canvas.
+ *
+ * Scaling the whole camera about the point, orientation untouched, is what leaves the point where
+ * it was: the target slides toward it in the proportion the distance shrinks. Exact under a visible
+ * rect too, whose offset rides in the projection this leaves alone. It holds **during** the ease
+ * only inside a user transition, which puts the target on the dolly's clock.
+ *
+ * **Scaled from where the camera is now, sized from where it is heading.** A double tap often lands
+ * while the last one is still easing. The point under the finger is found through the camera as it
+ * is drawn, so it is the camera's current stance that has to be scaled about it — that keeps the
+ * point under the finger from here on. The zoom is sized from the distance the camera is heading
+ * to, so a second double tap zooms a full step past the first rather than a step past wherever the
+ * first had got to, as successive wheel notches do. The clamped distance sets the proportion, so a
+ * zoom stopped short by the camera's limits does not slide the target as far as the one asked for.
+ * @param controls - The controls to move.
+ * @param space - The scene's space.
+ * @param factor - What to multiply the zoom factor by.
+ * @param around - The point to zoom about, in plan units.
+ * @returns When the move has settled.
+ */
+function zoomAbout(controls, space, factor, around) {
+    const from = controls.distance;
+    // The zoom factor is inversely proportional to the distance.
+    const to = clamp(controls.getSpherical(_spherical, true).radius / factor, controls.minDistance, controls.maxDistance);
+    const pivot = space.planToWorld(around, _pivot);
+    const target = controls
+        .getTarget(_target, false)
+        .sub(pivot)
+        .multiplyScalar(to / from)
+        .add(pivot);
+    return Promise.all([
+        controls.moveTo(target.x, target.y, target.z, true),
+        controls.dollyTo(to, true),
+    ]);
+}
+const _pivot = new Vector3();
+const _target = new Vector3();
+const _spherical = new Spherical();

package/dist/controls/handlers/Inertia.d.ts

@@ -0,0 +1,60 @@
+/**
+ * How the glide a motion leaves behind is measured, and how it slows.
+ *
+ * The speed is taken from the motion's own samples over the last stretch of the interaction, so
+ * the threshold is in the motion's units per millisecond: css pixels for a pan.
+ */
+export interface InertiaConfig {
+    /**
+     * How far back the interaction is sampled to measure its speed, in milliseconds; defaults to
+     * `50`. The oldest sample at least this old is the one differenced against, so a flick that ended
+     * in a stall glides at the stall's speed rather than the flick's.
+     */
+    minSampleMs?: number;
+    /** How long the glide lasts, in milliseconds; defaults to `1000`. */
+    durationMs?: number;
+    /**
+     * The speed below which a lifted pointer leaves no glide at all, in the motion's units per
+     * millisecond; defaults to `0.08`, sized for a pan in css pixels.
+     */
+    speedThreshold?: number;
+    /**
+     * How the glide slows, mapping `[0, 1]` to `[0, 1]`; defaults to {@link easeInertia}.
+     *
+     * Called every frame of the glide with the time **remaining**, so it is read as "how much of the
+     * original speed is left" and should return `1` at `1` and `0` at `0`. Hoist it: an inline
+     * function is a fresh identity on every render, which re-syncs the glide's options needlessly.
+     */
+    ease?: (t: number) => number;
+}
+/** Props for {@link Inertia}: the motion it carries on, and how. */
+export interface InertiaProps extends InertiaConfig {
+    /**
+     * How far the motion moved since the last call, or `undefined` when this step of the interaction
+     * was not one of its own. Called on every `control` event the controls report, so it measures the
+     * motion directly rather than inferring it from where the camera went.
+     */
+    sample: () => readonly number[] | undefined;
+    /**
+     * Moves the camera by one step of the glide, in the same units as the samples.
+     * @returns Whether it moved; `false` ends the glide.
+     */
+    apply: (step: readonly number[]) => boolean;
+}
+/**
+ * The glide a lifted pointer leaves behind, for one kind of motion.
+ *
+ * MapLibre's shape: each kind of motion measures itself while the user drives it, and when the
+ * interaction ends it glides on at the speed it ended with — rather than one glide reading the
+ * camera after the fact, where a pan, a pinch's slide toward the fingers and a twist's turn about
+ * them all arrive mixed into the same target. Generic over the motion: the caller says how to
+ * sample it and how to apply a step of it, and this owns the timing.
+ *
+ * Runs its frame callback **ahead of the controls' own** (see {@link INERTIA_PRIORITY}), so the
+ * camera it moves is the one that frame draws rather than the next. It asks for the next frame
+ * itself, which is what keeps a glide alive under the on-demand loop.
+ * @param props - What the glide carries on, and how it is measured and slows.
+ * @returns Nothing; this renders no scene node.
+ */
+export declare function Inertia(props: InertiaProps): null;
+//# sourceMappingURL=Inertia.d.ts.map

package/dist/controls/handlers/Inertia.js

@@ -0,0 +1,222 @@
+import { useFrame, useThree } from '@react-three/fiber';
+import { useEffect, useState } from 'react';
+import { useControlsEffect } from '../hooks';
+/**
+ * The glide a lifted pointer leaves behind, for one kind of motion.
+ *
+ * MapLibre's shape: each kind of motion measures itself while the user drives it, and when the
+ * interaction ends it glides on at the speed it ended with — rather than one glide reading the
+ * camera after the fact, where a pan, a pinch's slide toward the fingers and a twist's turn about
+ * them all arrive mixed into the same target. Generic over the motion: the caller says how to
+ * sample it and how to apply a step of it, and this owns the timing.
+ *
+ * Runs its frame callback **ahead of the controls' own** (see {@link INERTIA_PRIORITY}), so the
+ * camera it moves is the one that frame draws rather than the next. It asks for the next frame
+ * itself, which is what keeps a glide alive under the on-demand loop.
+ * @param props - What the glide carries on, and how it is measured and slows.
+ * @returns Nothing; this renders no scene node.
+ */
+export function Inertia(props) {
+    const minSampleMs = props.minSampleMs ?? DEFAULT_SAMPLE_MS;
+    const durationMs = props.durationMs ?? DEFAULT_DURATION_MS;
+    const speedThreshold = props.speedThreshold ?? DEFAULT_SPEED_THRESHOLD;
+    const ease = props.ease ?? easeInertia;
+    const { sample, apply } = props;
+    const invalidate = useThree((state) => state.invalidate);
+    const [inertia] = useState(() => new InertiaController({ minSampleMs, durationMs, speedThreshold, ease }, sample, apply));
+    // Assignments only, so a caller passing an inline `ease` or a fresh `sample` re-syncs fields and
+    // disturbs nothing else — in particular it never re-subscribes, which is why this is its own
+    // effect.
+    useEffect(() => {
+        inertia.configure({ minSampleMs, durationMs, speedThreshold, ease }, sample, apply);
+    }, [inertia, minSampleMs, durationMs, speedThreshold, ease, sample, apply]);
+    useControlsEffect((controls) => {
+        inertia.connect(controls);
+        return () => inertia.disconnect();
+    });
+    useFrame((_state, delta) => {
+        if (inertia.update(delta))
+            invalidate();
+    }, INERTIA_PRIORITY);
+    return null;
+}
+/**
+ * The default glide easing: an exponential ease-in, so most of the speed is shed early and the last
+ * of it trails off.
+ * @param t - How much of the glide's time is left, from `1` to `0`.
+ * @returns How much of the original speed to carry, from `1` to `0`.
+ */
+function easeInertia(t) {
+    return Math.pow(2, 10 * (t - 1));
+}
+/**
+ * Carries a motion on after the pointer lifts.
+ *
+ * Framework-free on purpose: everything here is arithmetic over a running total and a list of
+ * timestamps, which is the half worth testing without a canvas around it. {@link Inertia} is the
+ * React half — when to connect, when to configure, when to step.
+ *
+ * **The speed comes from the motion's own samples.** Each `control` event adds the motion's delta
+ * to a running total and records it; when the pointer lifts, the oldest record at least
+ * `minSampleMs` old is diffed against the total. A flick that ended in a stall therefore glides at
+ * the stall's speed, because the records covering the stall are the recent ones. A step the motion
+ * sat out adds nothing, so an interaction it never took part in glides nowhere.
+ */
+class InertiaController {
+    minSampleMs;
+    durationMs;
+    speedThreshold;
+    ease;
+    sample;
+    apply;
+    controls;
+    total = [];
+    records = [];
+    velocity = [];
+    step = [];
+    active = false;
+    elapsedMs = 0;
+    prevFactor = 1;
+    /**
+     * Takes every value rather than defaulting any: what an omitted option means is {@link Inertia}'s
+     * to answer, and answering it twice is how the two drift apart.
+     * @param options - How the glide is measured and how it slows.
+     * @param sample - How far the motion moved since the last call.
+     * @param apply - Moves the camera by one step of the glide.
+     */
+    constructor(options, sample, apply) {
+        this.minSampleMs = options.minSampleMs;
+        this.durationMs = options.durationMs;
+        this.speedThreshold = options.speedThreshold;
+        this.ease = options.ease;
+        this.sample = sample;
+        this.apply = apply;
+    }
+    /**
+     * Sets the motion, and how the glide is measured and slows.
+     * @param options - How the glide is measured and how it slows.
+     * @param sample - How far the motion moved since the last call.
+     * @param apply - Moves the camera by one step of the glide.
+     */
+    configure(options, sample, apply) {
+        this.minSampleMs = options.minSampleMs;
+        this.durationMs = options.durationMs;
+        this.speedThreshold = options.speedThreshold;
+        this.ease = options.ease;
+        this.sample = sample;
+        this.apply = apply;
+    }
+    /**
+     * Starts watching a controls instance for the interactions a glide follows.
+     * @param controls - The controls to watch.
+     */
+    connect(controls) {
+        if (this.controls)
+            this.disconnect();
+        this.controls = controls;
+        controls.addEventListener('controlstart', this.onControlStart);
+        controls.addEventListener('control', this.onControl);
+        controls.addEventListener('controlend', this.onControlEnd);
+    }
+    /** Stops watching, and abandons any glide in flight. */
+    disconnect() {
+        const controls = this.controls;
+        if (!controls)
+            return;
+        this.active = false;
+        this.records.length = 0;
+        controls.removeEventListener('controlstart', this.onControlStart);
+        controls.removeEventListener('control', this.onControl);
+        controls.removeEventListener('controlend', this.onControlEnd);
+        this.controls = undefined;
+    }
+    /**
+     * Advances a glide in flight by one frame.
+     *
+     * The speed applied is the average of this frame's easing factor and the last one's, which
+     * integrates the curve over the frame rather than sampling it at one end — so the distance
+     * covered does not depend on how the frames happened to fall.
+     * @param delta - Time since the last frame, in seconds.
+     * @returns Whether the camera moved, and so whether another frame is wanted.
+     */
+    update(delta) {
+        if (!this.active)
+            return false;
+        const deltaMs = delta * 1000;
+        this.elapsedMs += deltaMs;
+        const t = Math.min(1, this.elapsedMs / this.durationMs);
+        const factor = this.ease(1 - t); // 1 -> 0
+        const avgFactor = (factor + this.prevFactor) * 0.5;
+        this.prevFactor = factor;
+        for (let i = 0; i < this.velocity.length; i++) {
+            this.step[i] = this.velocity[i] * avgFactor * deltaMs;
+        }
+        if (!this.apply(this.step)) {
+            this.active = false;
+            return false;
+        }
+        if (factor <= REST_FACTOR || t >= 1)
+            this.active = false;
+        return true;
+    }
+    onControlStart = () => {
+        this.active = false;
+        this.records.length = 0;
+        this.total.fill(0);
+    };
+    onControl = () => {
+        const delta = this.sample();
+        const now = performance.now();
+        if (delta) {
+            for (let i = 0; i < delta.length; i++)
+                this.total[i] = (this.total[i] ?? 0) + delta[i];
+        }
+        this.records.push({ t: now, total: this.total.slice() });
+        const cutoff = now - SAMPLE_WINDOW_MS;
+        while (this.records.length && this.records[0].t < cutoff)
+            this.records.shift();
+    };
+    onControlEnd = () => {
+        const now = performance.now();
+        const oldest = now - this.minSampleMs;
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const record = this.records[i];
+            // The first record old enough to measure against — or the oldest there is, when the whole
+            // interaction was shorter than the sampling window.
+            if (record.t >= oldest && i !== 0)
+                continue;
+            const dt = now - record.t;
+            if (dt <= 0)
+                return;
+            let speedSquared = 0;
+            this.velocity.length = this.total.length;
+            this.step.length = this.total.length;
+            for (let axis = 0; axis < this.total.length; axis++) {
+                this.velocity[axis] = (this.total[axis] - (record.total[axis] ?? 0)) / dt;
+                speedSquared += this.velocity[axis] * this.velocity[axis];
+            }
+            if (Math.sqrt(speedSquared) <= this.speedThreshold)
+                return;
+            this.elapsedMs = 0;
+            this.prevFactor = 1;
+            this.active = true;
+            return;
+        }
+    };
+}
+/**
+ * The frame priority the glide steps at: ahead of the controls, which run at `-1`.
+ *
+ * Negative on both counts, so neither takes over rendering from R3F — a positive priority would.
+ */
+const INERTIA_PRIORITY = -2;
+/** How much of an interaction is kept to measure its speed from, in milliseconds. */
+const SAMPLE_WINDOW_MS = 300;
+/** The easing factor below which what is left of a glide is not worth another frame. */
+const REST_FACTOR = 0.02;
+/** How far back an interaction is sampled to measure the speed it should glide at, in milliseconds. */
+const DEFAULT_SAMPLE_MS = 50;
+/** How long a glide lasts, in milliseconds. */
+const DEFAULT_DURATION_MS = 1000;
+/** The speed below which a lifted pointer leaves no glide, in the motion's units per millisecond. */
+const DEFAULT_SPEED_THRESHOLD = 0.08;

package/dist/controls/handlers/Pan.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from 'react';
+import { type InertiaConfig } from './Inertia';
+/** Options for the pan handler, which are also its props. */
+export interface PanConfig {
+    /** Whether a pan keeps gliding after the pointer lifts, and how. Defaults on. */
+    inertia?: boolean | InertiaConfig;
+}
+/**
+ * Panning: a left-drag, and a one-finger drag.
+ *
+ * Screen-pan rather than truck, so the plan tracks the pointer at any pitch instead of sliding
+ * along the camera's own axes — the imperative renderer's choice, and what makes a tilted plan drag
+ * the way a map does.
+ *
+ * Owns the glide a lifted pointer leaves by rendering {@link PanInertia}, which is the one piece of
+ * panning camera-controls does not do itself.
+ *
+ * Mounting is enabling: the actions are set on mount and returned to `NONE` on unmount.
+ * @param props - Whether a pan glides, and how.
+ * @returns The glide, when there is one.
+ */
+export declare function Pan(props: PanConfig): ReactNode;
+//# sourceMappingURL=Pan.d.ts.map