@expofp/renderer 0.0.0-experimental.cf063fc

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

@@ -0,0 +1,28 @@
+import { type ReactNode } from 'react';
+/** Options for the zoom handler, which are also its props. */
+export interface ZoomConfig {
+    /**
+     * What a double-click or a double-tap multiplies the zoom factor by, zooming toward the point
+     * under the pointer and keeping it there. Off when left out.
+     */
+    dblclick?: number;
+}
+/**
+ * Zooming: the wheel, a two-finger pinch, and — when asked for — a double-click or double-tap.
+ *
+ * Nothing here beyond the actions for the first two — camera-controls recognizes both gestures
+ * itself, and `Controls` has already told it to dolly toward the cursor rather than the centre. The
+ * two-finger action pans as well as pinches, which is what makes a pinch feel like it holds the plan
+ * under the fingers; the twist half of a two-finger gesture is `Roll`'s, and comes off the gesture
+ * recognizer rather than from here, so the two never contend for `touches.two`.
+ *
+ * The double-click is not camera-controls' either, so it comes off the gesture recognizer, which
+ * reads a mouse and a finger alike: see {@link DoubleTapZoom}.
+ *
+ * Mounting is enabling. The actions are set when this mounts and returned to `NONE` when it
+ * unmounts, which is the whole of what the imperative renderer's `enable()` / `disable()` did.
+ * @param props - Whether a double-click zooms, and by how much.
+ * @returns The double-click zoom, when there is one.
+ */
+export declare function Zoom(props: ZoomConfig): ReactNode;
+//# sourceMappingURL=Zoom.d.ts.map

package/dist/controls/handlers/Zoom.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { CameraControlsAction } from '../CameraControls';
+import { useControlsEffect } from '../hooks';
+import { DoubleTapZoom } from './DoubleTapZoom';
+/**
+ * Zooming: the wheel, a two-finger pinch, and — when asked for — a double-click or double-tap.
+ *
+ * Nothing here beyond the actions for the first two — camera-controls recognizes both gestures
+ * itself, and `Controls` has already told it to dolly toward the cursor rather than the centre. The
+ * two-finger action pans as well as pinches, which is what makes a pinch feel like it holds the plan
+ * under the fingers; the twist half of a two-finger gesture is `Roll`'s, and comes off the gesture
+ * recognizer rather than from here, so the two never contend for `touches.two`.
+ *
+ * The double-click is not camera-controls' either, so it comes off the gesture recognizer, which
+ * reads a mouse and a finger alike: see {@link DoubleTapZoom}.
+ *
+ * Mounting is enabling. The actions are set when this mounts and returned to `NONE` when it
+ * unmounts, which is the whole of what the imperative renderer's `enable()` / `disable()` did.
+ * @param props - Whether a double-click zooms, and by how much.
+ * @returns The double-click zoom, when there is one.
+ */
+export function Zoom(props) {
+    useControlsEffect((controls) => {
+        controls.mouseButtons.wheel = CameraControlsAction.DOLLY;
+        controls.touches.two = CameraControlsAction.TOUCH_DOLLY_SCREEN_PAN;
+        return () => {
+            controls.mouseButtons.wheel = CameraControlsAction.NONE;
+            controls.touches.two = CameraControlsAction.NONE;
+        };
+    });
+    if (props.dblclick === undefined)
+        return null;
+    return _jsx(DoubleTapZoom, { factor: props.dblclick });
+}

package/dist/controls/hooks.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Every hook a component reaches the camera through, and the state they read.
+ *
+ * Beside `CameraControls.tsx` rather than in it, because Fast Refresh swaps a module in place only
+ * when every value it exports is a component. A hook exported next to one sends that module, and
+ * everything importing it, through a full page reload instead.
+ *
+ * The dependency runs one way, from here into `camera-api.ts`. That file holds the commands and the
+ * arithmetic behind them and imports nothing back, which is what lets `useCameraAPI` sit here with
+ * the rest.
+ */
+import { Point } from '@expofp/geometry';
+import { type CameraAPI } from './camera-api';
+import { type CameraControlsImpl } from './CameraControls';
+/**
+ * The scene's camera controls, once {@link Controls} has mounted them.
+ *
+ * For **reading** them, and for handing them to something else that does the writing — a gesture
+ * class, a measurement, a helper taking them as an argument. What the React Compiler rejects is
+ * assigning to a *field* of a hook's return value, which is a build error rather than a bug; a
+ * method call on it, or passing it along, is fine. A component with a write it cannot route through
+ * a function uses {@link useControlsEffect}, which hands the controls over as an argument.
+ * @returns The controls, or `undefined` until they mount.
+ */
+export declare function useCameraControls(): CameraControlsImpl | undefined;
+/**
+ * Runs an effect against the scene's camera controls, for as long as the component is mounted.
+ *
+ * The controls arrive as an argument rather than from a hook, which is what lets the effect write to
+ * them; and the "wait for them to mount" subscription lives here rather than in every caller, so a
+ * component that claims a mouse action is three lines and says only what it claims. Together with
+ * {@link useCameraControls} that is the whole surface — read them, or write to them in an effect.
+ *
+ * Re-runs when the controls change and whenever `effect` does, which — the React Compiler caching
+ * the closure against what it captures — is whenever the component's own inputs move.
+ * @param effect - What to do with the controls; may return a cleanup, as any effect may.
+ */
+export declare function useControlsEffect(effect: (controls: CameraControlsImpl) => (() => void) | void): void;
+/**
+ * Runs a handler once the camera has come to rest after moving — one call per movement rather than
+ * one per frame, whether a gesture or a command drove it. The event the imperative renderer
+ * published as `navigation:change`, under a name that says what happened.
+ *
+ * At rest and not at the start, so a caller that reads the camera back reads where the movement
+ * actually ended: the framing a kiosk saves, or the rect an overlay measures itself against. Every
+ * movement is reported because the one that moved the camera is not always the one that cares — the
+ * zoom buttons reach the camera through the store, and the screen recording the framing never sees
+ * that command.
+ *
+ * `sleep` rather than `rest`, which the library recommends for "the camera has stopped": `rest` is
+ * dispatched from the damping tail, and a pan here has none to dispatch from ({@link Controls}
+ * zeroes the control smoothing for truck and rotate), so a drag can finish without ever resting.
+ * `sleep` is dispatched for every movement, a jump included.
+ *
+ * A camera-level event rather than the controls themselves, so a caller recording where the plan was
+ * left never learns which library drives the camera. For as long as the component is mounted; where
+ * the camera *is* once it settles is `useCameraState`'s business.
+ * @param handler - Called once each movement has come to rest. Re-subscribed when its identity
+ *   changes, so pass a stable function — under the React Compiler an inline closure over stable
+ *   values is one.
+ */
+export declare function useCameraMoveEnd(handler: () => void): void;
+/**
+ * Runs a handler while the user is moving the camera by hand — a drag, a pinch and a wheel tick
+ * alike, as each one reaches the camera.
+ *
+ * The user's own movement and nothing else, which is what an idle timer wants: a kiosk that treated
+ * a command as activity would have the idle reset's own camera restore re-arm the timer it had just
+ * fired, and would never return home. Deliberately not bracketed by the gesture's start and end —
+ * the controls report neither for the wheel, since scrolling arrives in intermittent ticks with no
+ * way to tell a last one from a pause.
+ * @param handler - Called as each movement of the user's reaches the camera, which may be once per
+ *   frame for as long as a drag lasts. Re-subscribed when its identity changes, so pass a stable
+ *   function — under the React Compiler an inline closure over stable values is one.
+ */
+export declare function useCameraGesture(handler: () => void): void;
+/** Where the camera is, at the moment it was asked. */
+export interface CameraState {
+    /** The point on the plan it is looking at, in plan units. */
+    center: Point;
+    /** How far in it is zoomed, as a factor: `1` frames the whole viewbox. */
+    zoom: number;
+    /** Which way the plan is turned, in degrees clockwise from north, in `[0, 360)`. */
+    roll: number;
+    /** How far the plan is tilted away from face-on, in degrees. */
+    pitch: number;
+    /**
+     * How much of the plan one CSS pixel spans, in plan units — the factor anything sized in
+     * pixels is laid out against, and the quantity the imperative renderer published as `ptScale`.
+     * The device ratio is not part of it.
+     */
+    pixelSize: number;
+}
+/**
+ * Reads where the camera is.
+ *
+ * A **getter**, not a value: nothing here belongs in render output — a component that re-rendered
+ * whenever the camera moved would re-render on every frame of every pan — and every caller wants it
+ * at a moment of its own choosing, in an event handler, an effect, or a snapshot a host asked for.
+ * That is the same reading discipline `Space` documents, for the same reason.
+ *
+ * The five numbers come from four different places, which is why this exists at all rather than
+ * being arithmetic a caller could do: the target from the controls and the plan it lands on from the
+ * space, the zoom factor from the camera's handle, and the pixel size from the re-layout registry —
+ * which is what the plan's own labels are sized against, so a caller measuring against anything else
+ * would disagree with what is drawn.
+ *
+ * Outside a mounted scene, or in the frames before the controls publish themselves, it reports the
+ * camera at rest: the middle of the plan, framed whole, facing north.
+ *
+ * As with {@link useCameraAPI}, the reader is **new on every render** and this module memoizes
+ * nothing; a consumer that needs a settled identity holds it in a ref.
+ * @returns A function that reads the current state.
+ */
+export declare function useCameraState(): () => CameraState;
+/**
+ * The scene's camera commands.
+ *
+ * A hook rather than a ref handed out from above, and that is the point: it only resolves inside a
+ * component mounted under `<Renderer>`, and R3F mounts those only once the canvas and its context
+ * exist — so "the camera cannot be driven before the scene is ready" is enforced by where the code
+ * can live rather than by a null check every caller has to remember. A host that needs to drive the
+ * camera from outside React publishes this object from an effect, which is exactly when it is safe.
+ *
+ * Before the controls mount every command is a no-op that resolves at once, which is the same frame
+ * or two the hook's own consumers spend waiting for their effects.
+ *
+ * **The returned object is new on every render, deliberately.** This module is not memoized by hand
+ * — the React Compiler is scoped to `.tsx` under `src/` (see `vitest.config.mts`), and reaching for
+ * `useMemo` here would put a cache in the library that every consumer then has to trust. A consumer
+ * that cannot re-subscribe cheaply should hold this in a ref rather than in a dependency list; that
+ * way the decision, and its cost, sit with the code that knows how often it renders.
+ * @returns The commands.
+ */
+export declare function useCameraAPI(): CameraAPI;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/controls/hooks.js

@@ -0,0 +1,200 @@
+/**
+ * Every hook a component reaches the camera through, and the state they read.
+ *
+ * Beside `CameraControls.tsx` rather than in it, because Fast Refresh swaps a module in place only
+ * when every value it exports is a component. A hook exported next to one sends that module, and
+ * everything importing it, through a full page reload instead.
+ *
+ * The dependency runs one way, from here into `camera-api.ts`. That file holds the commands and the
+ * arithmetic behind them and imports nothing back, which is what lets `useCameraAPI` sit here with
+ * the rest.
+ */
+import { Point, radToDeg } from '@expofp/geometry';
+import { useThree } from '@react-three/fiber';
+import { use, useEffect } from 'react';
+import { Vector3 } from 'three';
+import { LayoutTargetsContext } from '../events/layout-targets';
+import { useCamera } from '../space/camera-handle';
+import { useCanvasSize } from '../space/canvas-size';
+import { useSpace } from '../space/Space';
+import { bearing, CameraCommands } from './camera-api';
+/**
+ * The scene's camera controls, once {@link Controls} has mounted them.
+ *
+ * For **reading** them, and for handing them to something else that does the writing — a gesture
+ * class, a measurement, a helper taking them as an argument. What the React Compiler rejects is
+ * assigning to a *field* of a hook's return value, which is a build error rather than a bug; a
+ * method call on it, or passing it along, is fine. A component with a write it cannot route through
+ * a function uses {@link useControlsEffect}, which hands the controls over as an argument.
+ * @returns The controls, or `undefined` until they mount.
+ */
+export function useCameraControls() {
+    return useThree((state) => state.controls) ?? undefined;
+}
+/**
+ * Runs an effect against the scene's camera controls, for as long as the component is mounted.
+ *
+ * The controls arrive as an argument rather than from a hook, which is what lets the effect write to
+ * them; and the "wait for them to mount" subscription lives here rather than in every caller, so a
+ * component that claims a mouse action is three lines and says only what it claims. Together with
+ * {@link useCameraControls} that is the whole surface — read them, or write to them in an effect.
+ *
+ * Re-runs when the controls change and whenever `effect` does, which — the React Compiler caching
+ * the closure against what it captures — is whenever the component's own inputs move.
+ * @param effect - What to do with the controls; may return a cleanup, as any effect may.
+ */
+export function useControlsEffect(effect) {
+    const get = useThree((state) => state.get);
+    // A subscription, so this re-runs once the controls have mounted. Deliberately not the value the
+    // effect uses: that is read fresh from the store below.
+    const mounted = useThree((state) => state.controls);
+    useEffect(() => {
+        const controls = get().controls;
+        if (!controls)
+            return undefined;
+        return effect(controls) ?? undefined;
+    }, [effect, get, mounted]);
+}
+/**
+ * Runs a handler once the camera has come to rest after moving — one call per movement rather than
+ * one per frame, whether a gesture or a command drove it. The event the imperative renderer
+ * published as `navigation:change`, under a name that says what happened.
+ *
+ * At rest and not at the start, so a caller that reads the camera back reads where the movement
+ * actually ended: the framing a kiosk saves, or the rect an overlay measures itself against. Every
+ * movement is reported because the one that moved the camera is not always the one that cares — the
+ * zoom buttons reach the camera through the store, and the screen recording the framing never sees
+ * that command.
+ *
+ * `sleep` rather than `rest`, which the library recommends for "the camera has stopped": `rest` is
+ * dispatched from the damping tail, and a pan here has none to dispatch from ({@link Controls}
+ * zeroes the control smoothing for truck and rotate), so a drag can finish without ever resting.
+ * `sleep` is dispatched for every movement, a jump included.
+ *
+ * A camera-level event rather than the controls themselves, so a caller recording where the plan was
+ * left never learns which library drives the camera. For as long as the component is mounted; where
+ * the camera *is* once it settles is `useCameraState`'s business.
+ * @param handler - Called once each movement has come to rest. Re-subscribed when its identity
+ *   changes, so pass a stable function — under the React Compiler an inline closure over stable
+ *   values is one.
+ */
+export function useCameraMoveEnd(handler) {
+    useControlsEffect((controls) => {
+        controls.addEventListener('sleep', handler);
+        return () => controls.removeEventListener('sleep', handler);
+    });
+}
+/**
+ * Runs a handler while the user is moving the camera by hand — a drag, a pinch and a wheel tick
+ * alike, as each one reaches the camera.
+ *
+ * The user's own movement and nothing else, which is what an idle timer wants: a kiosk that treated
+ * a command as activity would have the idle reset's own camera restore re-arm the timer it had just
+ * fired, and would never return home. Deliberately not bracketed by the gesture's start and end —
+ * the controls report neither for the wheel, since scrolling arrives in intermittent ticks with no
+ * way to tell a last one from a pause.
+ * @param handler - Called as each movement of the user's reaches the camera, which may be once per
+ *   frame for as long as a drag lasts. Re-subscribed when its identity changes, so pass a stable
+ *   function — under the React Compiler an inline closure over stable values is one.
+ */
+export function useCameraGesture(handler) {
+    useControlsEffect((controls) => {
+        controls.addEventListener('control', handler);
+        return () => controls.removeEventListener('control', handler);
+    });
+}
+/**
+ * Reads where the camera is.
+ *
+ * A **getter**, not a value: nothing here belongs in render output — a component that re-rendered
+ * whenever the camera moved would re-render on every frame of every pan — and every caller wants it
+ * at a moment of its own choosing, in an event handler, an effect, or a snapshot a host asked for.
+ * That is the same reading discipline `Space` documents, for the same reason.
+ *
+ * The five numbers come from four different places, which is why this exists at all rather than
+ * being arithmetic a caller could do: the target from the controls and the plan it lands on from the
+ * space, the zoom factor from the camera's handle, and the pixel size from the re-layout registry —
+ * which is what the plan's own labels are sized against, so a caller measuring against anything else
+ * would disagree with what is drawn.
+ *
+ * Outside a mounted scene, or in the frames before the controls publish themselves, it reports the
+ * camera at rest: the middle of the plan, framed whole, facing north.
+ *
+ * As with {@link useCameraAPI}, the reader is **new on every render** and this module memoizes
+ * nothing; a consumer that needs a settled identity holds it in a ref.
+ * @returns A function that reads the current state.
+ */
+export function useCameraState() {
+    const controls = useCameraControls();
+    const camera = useCamera();
+    const space = useSpace();
+    const targets = use(LayoutTargetsContext);
+    return () => readCameraState({ controls, camera, space, targets });
+}
+/**
+ * Reads the camera, from whatever the scene holds at the moment of asking.
+ * @param context - What the scene holds.
+ * @returns Where the camera is.
+ */
+function readCameraState(context) {
+    const { controls, camera, space, targets } = context;
+    const pixelSize = targets?.pixelSize ?? 1;
+    // A fresh centre every time: a caller that keeps the point it was handed must never find it
+    // moved under them.
+    if (!controls)
+        return { ...atRest(), pixelSize };
+    controls.getTarget(_target);
+    return {
+        center: space.worldToPlan(_target, new Point()),
+        zoom: camera?.zoomFactor ?? 1,
+        roll: radToDeg(bearing(controls)),
+        pitch: radToDeg(controls.polarAngle),
+        pixelSize,
+    };
+}
+/**
+ * The camera as it stands before anything has moved it, which is what a read outside a mounted
+ * scene reports: the middle of the plan, framed whole, facing north.
+ * @returns The state.
+ */
+function atRest() {
+    return { center: new Point(), zoom: 1, roll: 0, pitch: 0, pixelSize: 1 };
+}
+const _target = new Vector3();
+/**
+ * The scene's camera commands.
+ *
+ * A hook rather than a ref handed out from above, and that is the point: it only resolves inside a
+ * component mounted under `<Renderer>`, and R3F mounts those only once the canvas and its context
+ * exist — so "the camera cannot be driven before the scene is ready" is enforced by where the code
+ * can live rather than by a null check every caller has to remember. A host that needs to drive the
+ * camera from outside React publishes this object from an effect, which is exactly when it is safe.
+ *
+ * Before the controls mount every command is a no-op that resolves at once, which is the same frame
+ * or two the hook's own consumers spend waiting for their effects.
+ *
+ * **The returned object is new on every render, deliberately.** This module is not memoized by hand
+ * — the React Compiler is scoped to `.tsx` under `src/` (see `vitest.config.mts`), and reaching for
+ * `useMemo` here would put a cache in the library that every consumer then has to trust. A consumer
+ * that cannot re-subscribe cheaply should hold this in a ref rather than in a dependency list; that
+ * way the decision, and its cost, sit with the code that knows how often it renders.
+ * @returns The commands.
+ */
+export function useCameraAPI() {
+    const get = useThree((state) => state.get);
+    const invalidate = useThree((state) => state.invalidate);
+    const controls = useCameraControls();
+    const camera = useCamera();
+    const space = useSpace();
+    const { width, height, dpr } = useCanvasSize();
+    return new CameraCommands({
+        controls,
+        camera,
+        space,
+        view: () => get().camera.view,
+        width,
+        height,
+        dpr,
+        invalidate,
+    });
+}

package/dist/controls/index.d.ts

@@ -0,0 +1,9 @@
+export { bearing, type CameraAPI, type CameraAxes, CameraCommands, type TransitionOptions, type ZoomToOptions, } from './camera-api';
+export { CameraControls, CameraControlsAction, type CameraControlsImpl } from './CameraControls';
+export { Controls, type ControlsConfig, type ControlsProps } from './Controls';
+export type { InertiaConfig } from './handlers/Inertia';
+export type { PanConfig } from './handlers/Pan';
+export type { RollConfig } from './handlers/Roll';
+export type { ZoomConfig } from './handlers/Zoom';
+export { type CameraState, useCameraAPI, useCameraControls, useCameraGesture, useCameraMoveEnd, useCameraState, useControlsEffect, } from './hooks';
+//# sourceMappingURL=index.d.ts.map

package/dist/controls/index.js

@@ -0,0 +1,7 @@
+// The package's controls surface. A barrel and nothing else: a module that both re-exports and
+// declares a component cannot be a Fast Refresh boundary, and every hook below would send `Controls`
+// through a full reload with it.
+export { bearing, CameraCommands, } from './camera-api';
+export { CameraControls, CameraControlsAction } from './CameraControls';
+export { Controls } from './Controls';
+export { useCameraAPI, useCameraControls, useCameraGesture, useCameraMoveEnd, useCameraState, useControlsEffect, } from './hooks';

package/dist/controls/zoom-to.d.ts

@@ -0,0 +1,89 @@
+import { Box, type Point2Like } from '@expofp/geometry';
+import { type PerspectiveCamera } from 'three';
+import { type Space } from '../space/Space';
+/**
+ * The part of the canvas a target is framed inside, in **device** pixels, as the camera's own
+ * framing measures it.
+ *
+ * The offset is from the drawing buffer's centre rather than from its corner, because that is the
+ * only thing the fit does with it — a region centred on the canvas frames exactly as no region at
+ * all, and says so by being all zeroes.
+ */
+export interface FramingRegion {
+    /** How wide the region is. */
+    width: number;
+    /** How tall it is. */
+    height: number;
+    /** How far its centre sits to the right of the buffer's centre; negative for left. */
+    offsetX: number;
+    /** How far below; negative for above. */
+    offsetY: number;
+}
+/**
+ * What a camera's projection was offset by — three's own `camera.view`, which `VisibleRect` is what
+ * writes. Aliased rather than restated so the two can never drift.
+ */
+export type ViewOffset = PerspectiveCamera['view'];
+/** How {@link fitBox} should frame its target. */
+export interface FitOptions {
+    /** The target, in plan units. */
+    target: Box;
+    /** The scene's space, which takes the target into world units. */
+    space: Space;
+    /** How far the plan is turned, in radians — the camera's azimuth, negated. */
+    bearing: number;
+    /** The region to frame the target inside. */
+    region: FramingRegion;
+    /** Fraction of the region left as margin on each side; `0.25` spends half of it. */
+    padding?: number;
+    /** The closest the fit may bring the plan, as a zoom factor. */
+    maxZoom?: number;
+}
+/** Where the camera has to be for a target to fill its region. */
+export interface Fit {
+    /** Where the camera should look, in world units. */
+    center: Point2Like;
+    /** The zoom factor that frames the target. */
+    zoom: number;
+}
+/**
+ * Where the camera has to be for a box of the plan to fill a region of the canvas.
+ *
+ * Pure arithmetic, kept out of the hook so the part that can be wrong is the part that can be
+ * tested. It rests on the one invariant the viewbox fit exists to establish — at zoom factor `1` one
+ * world unit is one device pixel — which is what lets a world size and a pixel size be divided by
+ * each other below.
+ *
+ * The target is measured **in the camera's own frame**: its world box is turned about its centre by
+ * the bearing before its bounds are taken, so a plan the user has rolled frames the box they can see
+ * rather than its axis-aligned shadow. Turning about the centre is what leaves the centre alone,
+ * which is why only the size of that box is read.
+ *
+ * The pan target then picks up the region's offset from the buffer's centre, which is what lands the
+ * box in the middle of *that region* rather than in the middle of the canvas. The offset is divided
+ * by the zoom because it arrives as a distance in pixels and has to leave as one in world units, and
+ * turned by the bearing for the same reason the box was.
+ * @param options - The target, and how to frame it.
+ * @returns The framing, or `undefined` for a target with no area, which nothing can be fitted to.
+ */
+export declare function fitBox(options: FitOptions): Fit | undefined;
+/**
+ * The region a caller named, in the coordinates the fit works in.
+ *
+ * A `within` rect is given in css pixels of the **canvas**, which is where a host's own panels are.
+ * The fit works in the camera's framing instead — the canvas as it would be with no visible rect —
+ * so a rect has to come back through whatever `VisibleRect` put on the projection: a uniform scale
+ * about the rect's centre, and nothing else. With no view offset that reduces to a change of origin
+ * and a multiplication by the device pixel ratio.
+ *
+ * This is the one place in the renderer where a region of the canvas and the camera's framing meet,
+ * and it is the method whose whole job is relating the two. Everything else stays clear of it.
+ * @param within - The region, in css pixels from the canvas's top-left corner; omitted means all of it.
+ * @param width - The canvas width in css pixels.
+ * @param height - The canvas height in css pixels.
+ * @param dpr - Device pixels per css pixel.
+ * @param view - The camera's view offset, when one is in force.
+ * @returns The region in device pixels, offset from the buffer's centre.
+ */
+export declare function framingRegion(within: Box | undefined, width: number, height: number, dpr: number, view?: ViewOffset | null): FramingRegion;
+//# sourceMappingURL=zoom-to.d.ts.map

package/dist/controls/zoom-to.js

@@ -0,0 +1,91 @@
+import { Box, Point, rectBounds } from '@expofp/geometry';
+/**
+ * Where the camera has to be for a box of the plan to fill a region of the canvas.
+ *
+ * Pure arithmetic, kept out of the hook so the part that can be wrong is the part that can be
+ * tested. It rests on the one invariant the viewbox fit exists to establish — at zoom factor `1` one
+ * world unit is one device pixel — which is what lets a world size and a pixel size be divided by
+ * each other below.
+ *
+ * The target is measured **in the camera's own frame**: its world box is turned about its centre by
+ * the bearing before its bounds are taken, so a plan the user has rolled frames the box they can see
+ * rather than its axis-aligned shadow. Turning about the centre is what leaves the centre alone,
+ * which is why only the size of that box is read.
+ *
+ * The pan target then picks up the region's offset from the buffer's centre, which is what lands the
+ * box in the middle of *that region* rather than in the middle of the canvas. The offset is divided
+ * by the zoom because it arrives as a distance in pixels and has to leave as one in world units, and
+ * turned by the bearing for the same reason the box was.
+ * @param options - The target, and how to frame it.
+ * @returns The framing, or `undefined` for a target with no area, which nothing can be fitted to.
+ */
+export function fitBox(options) {
+    const { target, space, bearing, region, padding = 0, maxZoom } = options;
+    // The bounds of the target once the plan is turned — geometry's own rect maths, given the world
+    // box as a rect with a rotation. Turning is about the centre, so the centre below is still the
+    // target's and only the extent has changed.
+    const world = worldBounds(target, space);
+    const source = rectBounds({ center: world.center, size: world.size, rotation: bearing });
+    const { width: sourceWidth, height: sourceHeight } = source.size;
+    if (sourceWidth <= 0 || sourceHeight <= 0)
+        return undefined;
+    if (region.width <= 0 || region.height <= 0)
+        return undefined;
+    const margin = 1 - 2 * padding;
+    const fitted = Math.min((region.width * margin) / sourceWidth, (region.height * margin) / sourceHeight);
+    const zoom = maxZoom === undefined ? fitted : Math.min(fitted, maxZoom);
+    if (!(zoom > 0))
+        return undefined;
+    const pan = new Point(-region.offsetX / zoom, -region.offsetY / zoom).rotate(bearing, ORIGIN);
+    return { center: { x: source.center.x + pan.x, y: source.center.y + pan.y }, zoom };
+}
+/**
+ * The region a caller named, in the coordinates the fit works in.
+ *
+ * A `within` rect is given in css pixels of the **canvas**, which is where a host's own panels are.
+ * The fit works in the camera's framing instead — the canvas as it would be with no visible rect —
+ * so a rect has to come back through whatever `VisibleRect` put on the projection: a uniform scale
+ * about the rect's centre, and nothing else. With no view offset that reduces to a change of origin
+ * and a multiplication by the device pixel ratio.
+ *
+ * This is the one place in the renderer where a region of the canvas and the camera's framing meet,
+ * and it is the method whose whole job is relating the two. Everything else stays clear of it.
+ * @param within - The region, in css pixels from the canvas's top-left corner; omitted means all of it.
+ * @param width - The canvas width in css pixels.
+ * @param height - The canvas height in css pixels.
+ * @param dpr - Device pixels per css pixel.
+ * @param view - The camera's view offset, when one is in force.
+ * @returns The region in device pixels, offset from the buffer's centre.
+ */
+export function framingRegion(within, width, height, dpr, view) {
+    if (!within) {
+        return { width: width * dpr, height: height * dpr, offsetX: 0, offsetY: 0 };
+    }
+    // What the framing was scaled by, and where its centre landed — read straight back off the
+    // parameters `VisibleRect` handed `setViewOffset`.
+    const scale = view?.enabled ? view.fullWidth / view.width : 1;
+    const landingX = view?.enabled ? view.fullWidth / 2 - view.offsetX : width / 2;
+    const landingY = view?.enabled ? view.fullHeight / 2 - view.offsetY : height / 2;
+    return {
+        width: (within.size.width / scale) * dpr,
+        height: (within.size.height / scale) * dpr,
+        offsetX: ((within.center.x - landingX) / scale) * dpr,
+        offsetY: ((within.center.y - landingY) / scale) * dpr,
+    };
+}
+/**
+ * The target's bounds in world space.
+ *
+ * Two corners are the whole box: the plan-to-world mapping scales and translates, so opposite
+ * corners stay opposite. `fromMinMax` normalizes them, so a transform that mirrors an axis and
+ * hands them over the other way round still comes out right.
+ * @param target - The target, in plan units.
+ * @param space - The scene's space.
+ * @returns The bounds, in world units.
+ */
+function worldBounds(target, space) {
+    const min = space.planToWorld({ ...target.min, z: 0 });
+    const max = space.planToWorld({ ...target.max, z: 0 });
+    return Box.fromMinMax(min, max);
+}
+const ORIGIN = { x: 0, y: 0 };