@expofp/renderer 3.2.5 → 3.27.1

package/dist/controls/gestures.js

@@ -0,0 +1,84 @@
+import { useThree } from '@react-three/fiber';
+import { EventManager, Pan, Rotate } from 'mjolnir.js';
+import { useEffect } from 'react';
+/**
+ * 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.
+ *
+ * The recognizer itself is shared: `Roll` and `Pitch` 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']],
+    });
+    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.
+ */
+const managers = new WeakMap();

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

@@ -0,0 +1,111 @@
+import { type CameraControlsImpl } from '../CameraControls';
+/**
+ * How the glide a pan leaves behind is measured, and how it slows.
+ *
+ * The speed is taken from where the camera's target actually traveled over the last stretch of the
+ * drag, so these are all expressed against that: world units and milliseconds.
+ */
+export interface InertiaConfig {
+    /**
+     * How far back the drag 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 world units per millisecond;
+     * defaults to `0.08`.
+     */
+    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;
+}
+/**
+ * The glide a lifted pointer leaves behind.
+ *
+ * Mounted by {@link Pan}, and only when a pan is meant to keep moving. It watches the controls'
+ * own interaction events to learn how fast the plan was traveling when the pointer left, then eases
+ * that speed away over the following second.
+ *
+ * Runs its frame callback **ahead of the controls' own** (see {@link INERTIA_PRIORITY}), so the
+ * target it moves is the one that frame draws rather than the next — a frame tighter than the
+ * imperative renderer, which updated the controller before its handlers. It asks for the next frame
+ * itself, which is what keeps a glide alive under the on-demand loop.
+ * @param props - How the glide is measured and how it slows.
+ * @returns Nothing; this renders no scene node.
+ */
+export declare function Inertia(props: InertiaConfig): 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`.
+ */
+export declare function easeInertia(t: number): number;
+/**
+ * Carries a pan on after the pointer lifts.
+ *
+ * Framework-free on purpose: everything here is arithmetic over the camera's target 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 where the target actually went**, not from the pointer. Every interaction
+ * frame records the target; when the pointer lifts, the oldest sample at least `minSampleMs` old is
+ * diffed against the current target. A flick that ended in a stall therefore glides at the
+ * stall's speed, because the samples covering the stall are the recent ones.
+ */
+export declare class InertiaController {
+    private minSampleMs;
+    private durationMs;
+    private speedThreshold;
+    private ease;
+    private controls?;
+    private samples;
+    private target;
+    private delta;
+    private velocity;
+    private active;
+    private elapsedMs;
+    private prevFactor;
+    /**
+     * Takes every value rather than defaulting any: what an omitted option means is `resolveControls`'s
+     * to answer, and answering it twice is how the two drift apart.
+     * @param options - How the glide is measured and how it slows.
+     */
+    constructor(options: Required<InertiaConfig>);
+    /**
+     * Sets how the glide is measured and how it slows. Every field is optional, so a partial update
+     * leaves the rest as it was.
+     * @param options - The values to change.
+     */
+    configure(options: InertiaConfig): void;
+    /**
+     * Starts watching a controls instance for the interactions a glide follows.
+     * @param controls - The controls to watch and to move.
+     */
+    connect(controls: CameraControlsImpl): void;
+    /** Stops watching, and abandons any glide in flight. */
+    disconnect(): void;
+    /**
+     * 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: number): boolean;
+    private onControlStart;
+    private onControl;
+    private onControlEnd;
+}
+//# sourceMappingURL=Inertia.d.ts.map

package/dist/controls/handlers/Inertia.js

@@ -0,0 +1,215 @@
+import { useFrame, useThree } from '@react-three/fiber';
+import { useEffect, useState } from 'react';
+import { Vector3 } from 'three';
+import { useControlsEffect } from '../CameraControls';
+/**
+ * The glide a lifted pointer leaves behind.
+ *
+ * Mounted by {@link Pan}, and only when a pan is meant to keep moving. It watches the controls'
+ * own interaction events to learn how fast the plan was traveling when the pointer left, then eases
+ * that speed away over the following second.
+ *
+ * Runs its frame callback **ahead of the controls' own** (see {@link INERTIA_PRIORITY}), so the
+ * target it moves is the one that frame draws rather than the next — a frame tighter than the
+ * imperative renderer, which updated the controller before its handlers. It asks for the next frame
+ * itself, which is what keeps a glide alive under the on-demand loop.
+ * @param props - How the glide is measured and how it 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 invalidate = useThree((state) => state.invalidate);
+    const [inertia] = useState(() => new InertiaController({ minSampleMs, durationMs, speedThreshold, ease }));
+    // Assignments only, so a caller passing an inline `ease` re-syncs four 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 });
+    }, [inertia, minSampleMs, durationMs, speedThreshold, ease]);
+    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`.
+ */
+export function easeInertia(t) {
+    return Math.pow(2, 10 * (t - 1));
+}
+/**
+ * Carries a pan on after the pointer lifts.
+ *
+ * Framework-free on purpose: everything here is arithmetic over the camera's target 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 where the target actually went**, not from the pointer. Every interaction
+ * frame records the target; when the pointer lifts, the oldest sample at least `minSampleMs` old is
+ * diffed against the current target. A flick that ended in a stall therefore glides at the
+ * stall's speed, because the samples covering the stall are the recent ones.
+ */
+export class InertiaController {
+    minSampleMs;
+    durationMs;
+    speedThreshold;
+    ease;
+    controls;
+    samples = [];
+    target = new Vector3();
+    delta = new Vector3();
+    velocity = new Vector3();
+    active = false;
+    elapsedMs = 0;
+    prevFactor = 1;
+    /**
+     * Takes every value rather than defaulting any: what an omitted option means is `resolveControls`'s
+     * to answer, and answering it twice is how the two drift apart.
+     * @param options - How the glide is measured and how it slows.
+     */
+    constructor(options) {
+        this.minSampleMs = options.minSampleMs;
+        this.durationMs = options.durationMs;
+        this.speedThreshold = options.speedThreshold;
+        this.ease = options.ease;
+    }
+    /**
+     * Sets how the glide is measured and how it slows. Every field is optional, so a partial update
+     * leaves the rest as it was.
+     * @param options - The values to change.
+     */
+    configure(options) {
+        if (options.minSampleMs !== undefined)
+            this.minSampleMs = options.minSampleMs;
+        if (options.durationMs !== undefined)
+            this.durationMs = options.durationMs;
+        if (options.speedThreshold !== undefined)
+            this.speedThreshold = options.speedThreshold;
+        if (options.ease !== undefined)
+            this.ease = options.ease;
+    }
+    /**
+     * Starts watching a controls instance for the interactions a glide follows.
+     * @param controls - The controls to watch and to move.
+     */
+    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.samples.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) {
+        const controls = this.controls;
+        if (!this.active || !controls)
+            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;
+        // The current target rather than the one being eased toward: a glide is a chain of immediate
+        // moves, so the two agree — asking for the end value would compound with any transition the
+        // controls happen to be running.
+        controls.getTarget(this.target, false);
+        this.delta.copy(this.velocity).multiplyScalar(avgFactor * deltaMs);
+        this.target.add(this.delta);
+        // Only the target is moved: camera-controls carries the camera along with it, which is why the
+        // imperative renderer's parallel arithmetic on the camera position was never read back.
+        void controls.moveTo(this.target.x, this.target.y, this.target.z, false);
+        if (factor <= REST_FACTOR || t >= 1)
+            this.active = false;
+        return true;
+    }
+    onControlStart = () => {
+        this.active = false;
+        this.samples.length = 0;
+    };
+    onControl = () => {
+        const controls = this.controls;
+        if (!controls)
+            return;
+        const now = performance.now();
+        controls.getTarget(this.target, false);
+        this.samples.push({ t: now, target: this.target.clone() });
+        const cutoff = now - SAMPLE_WINDOW_MS;
+        while (this.samples.length && this.samples[0].t < cutoff)
+            this.samples.shift();
+    };
+    onControlEnd = () => {
+        const controls = this.controls;
+        if (!controls)
+            return;
+        const now = performance.now();
+        const oldest = now - this.minSampleMs;
+        for (let i = this.samples.length - 1; i >= 0; i--) {
+            const sample = this.samples[i];
+            // The first sample old enough to measure against — or the oldest there is, when the whole
+            // drag was shorter than the sampling window.
+            if (sample.t >= oldest && i !== 0)
+                continue;
+            const dt = now - sample.t;
+            if (dt <= 0)
+                return;
+            controls.getTarget(this.target, false);
+            this.velocity.subVectors(this.target, sample.target).divideScalar(dt);
+            // A pan never changes elevation, and a glide must not introduce one.
+            this.velocity.z = 0;
+            if (this.velocity.length() <= 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 a drag 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 a drag 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 world 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 Inertia}, 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

package/dist/controls/handlers/Pan.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { CameraControlsImpl, useControlsEffect } from '../CameraControls';
+import { Inertia } from './Inertia';
+/**
+ * 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 Inertia}, 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 function Pan(props) {
+    const inertia = props.inertia ?? true;
+    useControlsEffect((controls) => {
+        controls.mouseButtons.left = ACTION.SCREEN_PAN;
+        controls.touches.one = ACTION.TOUCH_SCREEN_PAN;
+        return () => {
+            controls.mouseButtons.left = ACTION.NONE;
+            controls.touches.one = ACTION.NONE;
+        };
+    });
+    if (inertia === false)
+        return null;
+    return _jsx(Inertia, { ...(inertia === true ? {} : inertia) });
+}
+const ACTION = CameraControlsImpl.ACTION;

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

@@ -0,0 +1,94 @@
+import { type Point2Like } from '@expofp/geometry';
+import { type MjolnirGestureEvent } from 'mjolnir.js';
+import { Vector2 } from 'three';
+import { CameraControlsImpl } from '../CameraControls';
+/**
+ * How far a two-finger gesture has got toward being judged a pitch.
+ *
+ * Split out from the gesture that holds it so {@link beginsVertically} can be exercised on its own:
+ * the arbitration is the subtle part, and it is pure arithmetic over two movements and a clock.
+ */
+export interface PitchVerdict {
+    /** Whether this gesture is a pitch — `undefined` while the fingers have not said. */
+    isValid?: boolean;
+    /** When the first of the two fingers moved, so the second can be given a moment to follow. */
+    firstMove?: number;
+}
+/**
+ * Pitching: a right-drag, and two fingers dragged vertically together.
+ *
+ * The right-drag is camera-controls' own polar rotation. The vertical drag is not, and the hard
+ * part is not applying it but telling it apart from the pinch and the twist that share two fingers.
+ * That judgement lives in {@link beginsVertically}, and until it is settled the gesture does
+ * nothing.
+ *
+ * The pitch **limits** are not here. They constrain the camera whether or not this handler is
+ * mounted — the imperative renderer applied them from its pitch handler's constructor for exactly
+ * that reason — so they are `Camera`'s, alongside the zoom bounds and the clipping planes derived
+ * from both.
+ *
+ * Mounting is enabling. The mouse action shares a field with `Roll`, so it is set and cleared with
+ * `|=` and `&= ~`, which are idempotent where an exclusive-or would not be.
+ * @returns Nothing; this renders no scene node.
+ */
+export declare function Pitch(): null;
+/**
+ * Two fingers dragged vertically together, tilting the plan.
+ *
+ * A class rather than fields on the component, for two reasons that agree: the React Compiler
+ * refuses a direct write to anything `useState` returned, and the gesture's arbitration is worth
+ * testing without a canvas around it. {@link Pitch} is the React half.
+ */
+export declare class PitchGesture {
+    private verdict;
+    private lastPoints?;
+    private prevTwoFingerAction?;
+    private p0;
+    private p1;
+    /**
+     * Remembers where the fingers started, and rules the gesture out when they are stacked one above
+     * the other — from there a vertical drag is indistinguishable from a pinch.
+     * @param event - The gesture event that began the drag.
+     */
+    start(event: MjolnirGestureEvent): void;
+    /**
+     * Tilts the plan by how far the fingers moved down the screen, once the gesture has been judged
+     * a pitch.
+     * @param event - The gesture event carrying the drag so far.
+     * @param controls - The controls to tilt.
+     */
+    move(event: MjolnirGestureEvent, controls: CameraControlsImpl): void;
+    /**
+     * Puts back the two-finger action this suppressed, if it suppressed one, and forgets the gesture.
+     *
+     * Nothing is restored when the captured action was already `NONE`: there was nothing to suppress,
+     * and writing it back would claim a field this handler does not own.
+     * @param controls - The controls to restore, if they are still there.
+     */
+    end(controls: CameraControlsImpl | undefined): void;
+}
+/**
+ * Whether a two-finger gesture is a pitch, judged from how the fingers first moved.
+ *
+ * Judged once and then held: the verdict is returned unchanged as soon as it has one, so a drag
+ * that started as a pitch stays one even if the fingers wander, and one that did not can never
+ * become one. A `false` verdict is what makes a pinch or a twist stay a pinch or a twist.
+ *
+ * The two fingers rarely start moving on the same frame, so one moving alone is not by itself a
+ * verdict — the other is given {@link ALLOWED_SINGLE_TOUCH_TIME} to follow, and only when it fails
+ * to is the gesture ruled out.
+ * @param a - How far the first finger moved since the last event.
+ * @param b - How far the second finger moved since the last event.
+ * @param timeStamp - When this event happened, in milliseconds.
+ * @param verdict - How far the judgement has got; updated in place.
+ * @returns Whether this is a pitch — `false` both for "not a pitch" and for "not yet decided", the
+ *   two cases a caller treats alike by doing nothing.
+ */
+export declare function beginsVertically(a: Vector2, b: Vector2, timeStamp: number, verdict: PitchVerdict): boolean;
+/**
+ * Whether a movement is more down-the-screen than across it.
+ * @param vector - The movement to judge.
+ * @returns Whether it is vertical.
+ */
+export declare function isVertical(vector: Point2Like): boolean;
+//# sourceMappingURL=Pitch.d.ts.map