entangle-ui 0.8.2 → 0.10.0

package/dist/esm/components/primitives/viewport/ViewportStore.js

@@ -0,0 +1,210 @@
+import { computeCenterTransform, computeFitTransform } from './viewportMath.js';
+
+const IDENTITY_TRANSFORM = { x: 0, y: 0, zoom: 1 };
+/**
+ * Single source of truth for viewport runtime state — `transform`, `size`,
+ * `isPanning`, `marqueeRect`, and per-layer invalidation events.
+ *
+ * Designed for React's `useSyncExternalStore`: each slice has its own
+ * subscribe/get pair so subscribers re-render only when their slice
+ * changes (not on every store mutation).
+ *
+ * `Viewport.tsx` configures the imperative methods (`fitToContent`,
+ * `centerOn`, …) at mount via `configureImperative()` so the store knows
+ * how to push transform updates back to React state. Until configured,
+ * those methods are no-ops.
+ */
+class ViewportStore {
+    constructor() {
+        this.transform = IDENTITY_TRANSFORM;
+        this.size = { width: 0, height: 0 };
+        this.isPanning = false;
+        this.marqueeRect = null;
+        this.snapshot = this.computeSnapshot();
+        this.allListeners = new Set();
+        this.transformListeners = new Set();
+        this.sizeListeners = new Set();
+        this.isPanningListeners = new Set();
+        this.marqueeListeners = new Set();
+        this.layerListeners = new Map();
+        this.imperative = null;
+        // ── Public read API (arrow functions so they can be passed as callbacks) ──
+        this.getSnapshot = () => this.snapshot;
+        this.getTransform = () => this.transform;
+        this.getSize = () => this.size;
+        this.getIsPanning = () => this.isPanning;
+        this.getMarqueeRect = () => this.marqueeRect;
+        // ── Subscriptions ──
+        this.subscribe = (cb) => {
+            this.allListeners.add(cb);
+            return () => {
+                this.allListeners.delete(cb);
+            };
+        };
+        this.subscribeTransform = (cb) => {
+            this.transformListeners.add(cb);
+            return () => {
+                this.transformListeners.delete(cb);
+            };
+        };
+        this.subscribeSize = (cb) => {
+            this.sizeListeners.add(cb);
+            return () => {
+                this.sizeListeners.delete(cb);
+            };
+        };
+        this.subscribeIsPanning = (cb) => {
+            this.isPanningListeners.add(cb);
+            return () => {
+                this.isPanningListeners.delete(cb);
+            };
+        };
+        this.subscribeMarquee = (cb) => {
+            this.marqueeListeners.add(cb);
+            return () => {
+                this.marqueeListeners.delete(cb);
+            };
+        };
+        /**
+         * Returns a stable handle object whose methods proxy to the store.
+         * The store keeps its lifecycle, so this handle reference is stable
+         * for the lifetime of the store.
+         */
+        this.handle = {
+            fitToContent: (bounds, padding = 0) => {
+                if (!this.imperative)
+                    return;
+                this.imperative.setTransform(computeFitTransform(bounds, this.size, padding, {
+                    minZoom: this.imperative.minZoom,
+                    maxZoom: this.imperative.maxZoom,
+                }));
+            },
+            zoomToRect: (rect, padding = 0) => {
+                if (!this.imperative)
+                    return;
+                this.imperative.setTransform(computeFitTransform(rect, this.size, padding, {
+                    minZoom: this.imperative.minZoom,
+                    maxZoom: this.imperative.maxZoom,
+                }));
+            },
+            centerOn: (point, zoom) => {
+                if (!this.imperative)
+                    return;
+                this.imperative.setTransform(computeCenterTransform(point, this.size, this.transform, {
+                    minZoom: this.imperative.minZoom,
+                    maxZoom: this.imperative.maxZoom,
+                }, zoom));
+            },
+            getTransform: () => this.transform,
+            getSize: () => this.size,
+            invalidate: (layerName) => {
+                this.invalidate(layerName);
+            },
+        };
+    }
+    subscribeLayer(name, cb) {
+        let set = this.layerListeners.get(name);
+        if (!set) {
+            set = new Set();
+            this.layerListeners.set(name, set);
+        }
+        set.add(cb);
+        return () => {
+            const current = this.layerListeners.get(name);
+            if (!current)
+                return;
+            current.delete(cb);
+            if (current.size === 0)
+                this.layerListeners.delete(name);
+        };
+    }
+    // ── Mutators (called by Viewport / gestures) ──
+    setTransform(next) {
+        if (next === this.transform)
+            return;
+        this.transform = next;
+        this.snapshot = this.computeSnapshot();
+        this.transformListeners.forEach(cb => {
+            cb();
+        });
+        this.allListeners.forEach(cb => {
+            cb();
+        });
+    }
+    setSize(next) {
+        if (next.width === this.size.width && next.height === this.size.height) {
+            return;
+        }
+        this.size = next;
+        this.snapshot = this.computeSnapshot();
+        this.sizeListeners.forEach(cb => {
+            cb();
+        });
+        this.allListeners.forEach(cb => {
+            cb();
+        });
+    }
+    setIsPanning(next) {
+        if (next === this.isPanning)
+            return;
+        this.isPanning = next;
+        this.snapshot = this.computeSnapshot();
+        this.isPanningListeners.forEach(cb => {
+            cb();
+        });
+        this.allListeners.forEach(cb => {
+            cb();
+        });
+    }
+    setMarqueeRect(next) {
+        if (next === this.marqueeRect)
+            return;
+        this.marqueeRect = next;
+        this.snapshot = this.computeSnapshot();
+        this.marqueeListeners.forEach(cb => {
+            cb();
+        });
+        this.allListeners.forEach(cb => {
+            cb();
+        });
+    }
+    /**
+     * Trigger a redraw of one layer (when `layerName` is provided) or all
+     * layers (when omitted). Does not mutate snapshot state — fires only
+     * the layer listeners.
+     */
+    invalidate(layerName) {
+        if (layerName === undefined) {
+            this.layerListeners.forEach(set => {
+                set.forEach(cb => {
+                    cb();
+                });
+            });
+        }
+        else {
+            this.layerListeners.get(layerName)?.forEach(cb => {
+                cb();
+            });
+        }
+    }
+    // ── Imperative handle wiring ──
+    /**
+     * Wire up the React-side bits the imperative methods need
+     * (a `setTransform` that goes through React state + zoom limits).
+     * Viewport calls this on mount and on dependency changes.
+     */
+    configureImperative(config) {
+        this.imperative = config;
+    }
+    computeSnapshot() {
+        return {
+            transform: this.transform,
+            size: this.size,
+            isPanning: this.isPanning,
+            marqueeRect: this.marqueeRect,
+        };
+    }
+}
+
+export { ViewportStore };
+//# sourceMappingURL=ViewportStore.js.map

package/dist/esm/components/primitives/viewport/ViewportStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViewportStore.js","sources":["../../../../../../src/components/primitives/viewport/ViewportStore.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/components/primitives/viewport/ViewportWorld.js

@@ -0,0 +1,38 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { useSyncExternalStore } from 'react';
+import { cx } from '../../../utils/cx.js';
+import { worldLayerStyle } from './Viewport.css.js';
+import { useViewportStore } from './ViewportContext.js';
+
+/**
+ * Container for HTML children positioned in **world coordinates**.
+ *
+ * The wrapper applies the viewport's `translate(x, y) scale(zoom)` so that
+ * children whose `left`/`top` are expressed in world units render at the
+ * correct screen position and follow pan/zoom automatically.
+ *
+ * Subscribes only to the `transform` slice of the store — re-renders when
+ * the transform changes, not when `isPanning` or `marqueeRect` flip.
+ *
+ * @example
+ * ```tsx
+ * <ViewportWorld>
+ *   <div style={{ position: 'absolute', left: 100, top: 200 }}>
+ *     Node at world (100, 200)
+ *   </div>
+ * </ViewportWorld>
+ * ```
+ */
+const ViewportWorld = ({ children, className, style, }) => {
+    const store = useViewportStore();
+    const transform = useSyncExternalStore(store.subscribeTransform, store.getTransform);
+    return (jsx("div", { className: cx(worldLayerStyle, className), style: {
+            ...style,
+            transform: `translate(${transform.x}px, ${transform.y}px) scale(${transform.zoom})`,
+        }, children: children }));
+};
+ViewportWorld.displayName = 'ViewportWorld';
+
+export { ViewportWorld };
+//# sourceMappingURL=ViewportWorld.js.map

package/dist/esm/components/primitives/viewport/ViewportWorld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViewportWorld.js","sources":["../../../../../../src/components/primitives/viewport/ViewportWorld.tsx"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;AAWA;;;;;;;;;;;;;;;;;;AAkBG;AACI;AAKL;AACA;AAKA;AAIM;AACA;;AAMR;AAEA;;"}

package/dist/esm/components/primitives/viewport/useViewportGestures.js

@@ -0,0 +1,333 @@
+"use client";
+import { useMemo, useRef, useEffect, useCallback } from 'react';
+import '../../../utils/devWarn.js';
+import { useLatest } from '../../../hooks/useLatest/useLatest.js';
+import '../../../hooks/useBreakpoint/useBreakpoint.js';
+import { useDebouncedCallback } from '../../../hooks/useDebounced/useDebouncedCallback.js';
+import './../../../assets/src/theme/lightTheme.css.ts.vanilla-Ct6f9Iym.css';
+import '../../../node_modules/@vanilla-extract/css/dist/vanilla-extract-css.esm.js';
+import './../../../assets/src/theme/darkTheme.css.ts.vanilla-BHZ3ecRn.css';
+import 'react/jsx-runtime';
+import './../../../assets/src/theme/globalScrollbars.css.ts.vanilla-BAJwnUEJ.css';
+import '../../../hooks/useNavigationHistory/useNavigationHistory.js';
+import { clamp } from '../../../utils/mathUtils.js';
+import { screenToWorld } from './viewportCoords.js';
+import { normalizeRect, computeZoomTowardPivot } from './viewportMath.js';
+
+const BUTTON_TO_NAME = {
+    0: 'left',
+    1: 'middle',
+    2: 'right',
+};
+const DEFAULT_PAN = {
+    button: 'middle',
+    spaceKey: true,
+};
+const DEFAULT_ZOOM = {
+    wheel: true,
+    pinch: true,
+    speed: 0.0015,
+};
+const DEFAULT_SELECTION = {
+    enabled: false,
+    button: 'left',
+    additiveModifier: 'shift',
+};
+const ZOOM_END_DELAY_MS = 180;
+const MAX_VELOCITY_PX_PER_MS = 3;
+const VELOCITY_SAMPLE_COUNT = 5;
+/**
+ * Resolves gesture event handlers (pan, zoom, marquee) for the Viewport
+ * wrapper. Used internally by `<Viewport>` — every "live" value (current
+ * transform, current size, latest callbacks) is read through the store
+ * or through a `useLatest` ref so the wheel/keyboard listeners never
+ * re-attach on prop changes.
+ */
+function useViewportGestures(options) {
+    const { viewportRef, store, setTransform, disabled, minZoom, maxZoom, pan, zoom, selectionRect, callbacks, } = options;
+    const panCfg = useMemo(() => pan === false
+        ? { button: false, spaceKey: false }
+        : { ...DEFAULT_PAN, ...pan }, [pan]);
+    const zoomCfg = useMemo(() => zoom === false
+        ? { wheel: false, pinch: false, speed: DEFAULT_ZOOM.speed }
+        : { ...DEFAULT_ZOOM, ...zoom }, [zoom]);
+    const selCfg = useMemo(() => ({ ...DEFAULT_SELECTION, ...selectionRect }), [selectionRect]);
+    const callbacksRef = useLatest(callbacks);
+    const setTransformRef = useLatest(setTransform);
+    const limitsRef = useLatest({ minZoom, maxZoom });
+    const zoomSpeedRef = useLatest(zoomCfg.speed);
+    const activeRef = useRef(null);
+    const spaceHeldRef = useRef(false);
+    const pointerInsideRef = useRef(false);
+    // Ring-buffer of recent pointer-move samples for velocity smoothing.
+    const samplesRef = useRef([]);
+    const zoomActiveRef = useRef(false);
+    const fireZoomEnd = useDebouncedCallback(() => {
+        zoomActiveRef.current = false;
+        callbacksRef.current.onZoomEnd?.();
+    }, ZOOM_END_DELAY_MS);
+    // ── Space-key tracking (window-scoped, gated by pointer/focus state) ──
+    useEffect(() => {
+        if (!panCfg.spaceKey || disabled) {
+            spaceHeldRef.current = false;
+            return;
+        }
+        const isInteractingWithViewport = () => {
+            if (pointerInsideRef.current)
+                return true;
+            const root = viewportRef.current;
+            const active = document.activeElement;
+            if (!root || !active)
+                return false;
+            return root === active || root.contains(active);
+        };
+        const handleDown = (e) => {
+            if (e.code !== 'Space')
+                return;
+            if (!isInteractingWithViewport())
+                return;
+            spaceHeldRef.current = true;
+            e.preventDefault();
+        };
+        const handleUp = (e) => {
+            if (e.code === 'Space') {
+                spaceHeldRef.current = false;
+            }
+        };
+        const handleBlur = () => {
+            spaceHeldRef.current = false;
+        };
+        window.addEventListener('keydown', handleDown);
+        window.addEventListener('keyup', handleUp);
+        window.addEventListener('blur', handleBlur);
+        return () => {
+            window.removeEventListener('keydown', handleDown);
+            window.removeEventListener('keyup', handleUp);
+            window.removeEventListener('blur', handleBlur);
+        };
+    }, [panCfg.spaceKey, disabled, viewportRef]);
+    // ── Native wheel listener (non-passive so we can preventDefault page scroll) ──
+    useEffect(() => {
+        const el = viewportRef.current;
+        if (!el || disabled)
+            return;
+        if (!zoomCfg.wheel && !zoomCfg.pinch)
+            return;
+        const handler = (e) => {
+            const isPinch = e.ctrlKey;
+            if (isPinch && !zoomCfg.pinch)
+                return;
+            if (!isPinch && !zoomCfg.wheel)
+                return;
+            e.preventDefault();
+            if (!zoomActiveRef.current) {
+                zoomActiveRef.current = true;
+                callbacksRef.current.onZoomStart?.();
+            }
+            fireZoomEnd();
+            const rect = el.getBoundingClientRect();
+            const pivot = {
+                x: e.clientX - rect.left,
+                y: e.clientY - rect.top,
+            };
+            const factor = Math.exp(-e.deltaY * zoomSpeedRef.current);
+            const next = computeZoomTowardPivot(pivot, factor, store.getTransform(), limitsRef.current);
+            setTransformRef.current(next);
+        };
+        el.addEventListener('wheel', handler, { passive: false });
+        return () => {
+            el.removeEventListener('wheel', handler);
+        };
+    }, [
+        viewportRef,
+        disabled,
+        zoomCfg.wheel,
+        zoomCfg.pinch,
+        store,
+        callbacksRef,
+        fireZoomEnd,
+        limitsRef,
+        setTransformRef,
+        zoomSpeedRef,
+    ]);
+    const resolveGesture = useCallback((buttonNum) => {
+        const button = BUTTON_TO_NAME[buttonNum];
+        if (!button)
+            return null;
+        if (panCfg.spaceKey && spaceHeldRef.current && panCfg.button !== false) {
+            return 'pan';
+        }
+        if (panCfg.button !== false && button === panCfg.button) {
+            return 'pan';
+        }
+        if (selCfg.enabled && button === selCfg.button) {
+            return 'marquee';
+        }
+        return null;
+    }, [panCfg.spaceKey, panCfg.button, selCfg.enabled, selCfg.button]);
+    const getLocalPoint = useCallback((e) => {
+        const el = viewportRef.current;
+        if (!el)
+            return { x: 0, y: 0 };
+        const rect = el.getBoundingClientRect();
+        return { x: e.clientX - rect.left, y: e.clientY - rect.top };
+    }, [viewportRef]);
+    const emitSelection = useCallback((startScreen, endScreen, additive, inProgress) => {
+        const t = store.getTransform();
+        const startWorld = screenToWorld(startScreen, t);
+        const endWorld = screenToWorld(endScreen, t);
+        const rect = normalizeRect({
+            x: startWorld.x,
+            y: startWorld.y,
+            width: endWorld.x - startWorld.x,
+            height: endWorld.y - startWorld.y,
+        });
+        const screenRect = normalizeRect({
+            x: startScreen.x,
+            y: startScreen.y,
+            width: endScreen.x - startScreen.x,
+            height: endScreen.y - startScreen.y,
+        });
+        store.setMarqueeRect(inProgress ? screenRect : null);
+        callbacksRef.current.onSelectionChange?.({
+            rect,
+            additive,
+            inProgress,
+        });
+    }, [store, callbacksRef]);
+    const onPointerDown = useCallback((e) => {
+        if (disabled)
+            return;
+        if (activeRef.current)
+            return;
+        const kind = resolveGesture(e.button);
+        if (!kind)
+            return;
+        const local = getLocalPoint(e);
+        activeRef.current = {
+            kind,
+            pointerId: e.pointerId,
+            startScreen: local,
+            startTransform: store.getTransform(),
+            additive: (() => {
+                switch (selCfg.additiveModifier) {
+                    case 'shift':
+                        return e.shiftKey;
+                    case 'meta':
+                        return e.metaKey;
+                    case 'ctrl':
+                        return e.ctrlKey;
+                    case 'alt':
+                        return e.altKey;
+                    default:
+                        return false;
+                }
+            })(),
+        };
+        samplesRef.current = [{ point: local, time: performance.now() }];
+        e.currentTarget.setPointerCapture(e.pointerId);
+        e.preventDefault();
+        if (kind === 'pan') {
+            store.setIsPanning(true);
+            callbacksRef.current.onPanStart?.();
+        }
+        else {
+            emitSelection(local, local, activeRef.current.additive, true);
+        }
+    }, [
+        disabled,
+        resolveGesture,
+        getLocalPoint,
+        store,
+        selCfg.additiveModifier,
+        emitSelection,
+        callbacksRef,
+    ]);
+    const onPointerMove = useCallback((e) => {
+        const g = activeRef.current;
+        if (g?.pointerId !== e.pointerId)
+            return;
+        const local = getLocalPoint(e);
+        const samples = samplesRef.current;
+        samples.push({ point: local, time: performance.now() });
+        if (samples.length > VELOCITY_SAMPLE_COUNT)
+            samples.shift();
+        if (g.kind === 'pan') {
+            const dx = local.x - g.startScreen.x;
+            const dy = local.y - g.startScreen.y;
+            setTransformRef.current({
+                x: g.startTransform.x + dx,
+                y: g.startTransform.y + dy,
+                zoom: g.startTransform.zoom,
+            });
+        }
+        else {
+            emitSelection(g.startScreen, local, g.additive, true);
+        }
+    }, [getLocalPoint, emitSelection, setTransformRef]);
+    const endGesture = useCallback((e, cancelled) => {
+        const g = activeRef.current;
+        if (g?.pointerId !== e.pointerId)
+            return;
+        const local = getLocalPoint(e);
+        if (g.kind === 'pan') {
+            let vx = 0;
+            let vy = 0;
+            const samples = samplesRef.current;
+            if (samples.length >= 2) {
+                const first = samples[0];
+                const last = samples[samples.length - 1];
+                if (first && last) {
+                    const dt = last.time - first.time;
+                    if (dt > 0) {
+                        vx = clamp((last.point.x - first.point.x) / dt, -MAX_VELOCITY_PX_PER_MS, MAX_VELOCITY_PX_PER_MS);
+                        vy = clamp((last.point.y - first.point.y) / dt, -MAX_VELOCITY_PX_PER_MS, MAX_VELOCITY_PX_PER_MS);
+                    }
+                }
+            }
+            store.setIsPanning(false);
+            callbacksRef.current.onPanEnd?.({ velocity: { x: vx, y: vy } });
+        }
+        else if (!cancelled) {
+            emitSelection(g.startScreen, local, g.additive, false);
+        }
+        else {
+            store.setMarqueeRect(null);
+        }
+        activeRef.current = null;
+        samplesRef.current = [];
+        if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+            e.currentTarget.releasePointerCapture(e.pointerId);
+        }
+    }, [getLocalPoint, emitSelection, store, callbacksRef]);
+    const onPointerUp = useCallback((e) => {
+        endGesture(e, false);
+    }, [endGesture]);
+    const onPointerCancel = useCallback((e) => {
+        endGesture(e, true);
+    }, [endGesture]);
+    const onPointerEnter = useCallback(() => {
+        pointerInsideRef.current = true;
+    }, []);
+    const onPointerLeave = useCallback(() => {
+        pointerInsideRef.current = false;
+    }, []);
+    const onContextMenu = useCallback((e) => {
+        if (panCfg.button === 'right')
+            e.preventDefault();
+    }, [panCfg.button]);
+    return {
+        handlers: {
+            onPointerDown,
+            onPointerMove,
+            onPointerUp,
+            onPointerCancel,
+            onPointerEnter,
+            onPointerLeave,
+            onContextMenu,
+        },
+    };
+}
+
+export { useViewportGestures };
+//# sourceMappingURL=useViewportGestures.js.map

package/dist/esm/components/primitives/viewport/useViewportGestures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useViewportGestures.js","sources":["../../../../../../src/components/primitives/viewport/useViewportGestures.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;;;;;;;;;AA2DA;AACE;AACA;AACA;;AAGF;AACE;AACA;;AAGF;AACE;AACA;AACA;;AAGF;AACE;AACA;AACA;;AAGF;AACA;AACA;AAaA;;;;;;AAMG;AACG;;;;AAoBE;;AAMA;AACA;;AAQN;AACA;;;AAIA;AACA;AACA;;AAGA;AAEA;AAEA;AACE;AACA;;;;AAKA;AACE;;;;;AAI8B;AAC9B;AACA;AACA;AAAsB;;AAExB;AACA;AACE;;;;AAEA;;AAEF;AACA;AACE;AACE;;AAEJ;;AAEE;AACF;AACA;AACA;AACA;AACA;AACE;AACA;AACA;AACF;;;;AAKA;;;;;AAIA;AACE;AACA;;AACA;;;AAIA;AACE;AACA;;AAEF;AAEA;AACA;AACE;AACA;;AAEF;AACA;AAMA;AACF;AAEA;AACA;AACE;AACF;AACF;;;AAGE;AACA;;;;;;;AAOD;AAED;AAEI;AACA;AAAa;AAEb;AACE;;AAEF;AACE;;;AAGA;;AAEF;AACF;AAIF;AAEI;AACA;;AACA;;AAEF;AAIF;AAOI;;;;;;AAME;AACA;AACD;;;;AAIC;AACA;AACD;AACD;AACA;;;;AAIC;AACH;AAIF;AAEI;;;;;AAIA;;AAEA;;;;AAKE;AACA;;AAEE;AACE;;AAEA;;AAEA;;AAEA;;AAEA;AACE;;AAEN;;AAGF;;;AAKA;AACE;AACA;;;AAEA;;AAEJ;;;;;AAME;;;AAGD;AAGH;AAEI;AACA;;AAEA;AAEA;AACA;AACA;;AAEA;;;;AAII;AACA;AACA;AACD;;;AAED;;;;AAQF;AACA;;AAEA;AAEA;;;AAGE;AACA;AACE;;AAEA;;AAEE;;;;;;AAcJ;;;;AAGA;;;AAEA;;AAGF;AACA;;;;;AASJ;AAEI;AACF;AAIF;AAEI;AACF;AAIF;AACE;;AAGF;AACE;;AAGF;AAEI;;AACF;;AAKA;;;;;;;;AAQC;;AAEL;;"}

package/dist/esm/components/primitives/viewport/viewportCoords.js

@@ -0,0 +1,37 @@
+/**
+ * Convert a world-space point to a screen-space (CSS-pixel) point.
+ *
+ * Uses the canonical transform: `screenPos = worldPos * zoom + (x, y)`.
+ */
+function worldToScreen(point, transform) {
+    return {
+        x: point.x * transform.zoom + transform.x,
+        y: point.y * transform.zoom + transform.y,
+    };
+}
+/**
+ * Convert a screen-space (CSS-pixel) point to a world-space point.
+ *
+ * Inverse of `worldToScreen`.
+ */
+function screenToWorld(point, transform) {
+    const z = transform.zoom || 1;
+    return {
+        x: (point.x - transform.x) / z,
+        y: (point.y - transform.y) / z,
+    };
+}
+/**
+ * Compute the screen-space (CSS-pixel) position of a pointer event relative
+ * to a viewport element.
+ */
+function getViewportPointerPosition(event, viewport) {
+    const rect = viewport.getBoundingClientRect();
+    return {
+        x: event.clientX - rect.left,
+        y: event.clientY - rect.top,
+    };
+}
+
+export { getViewportPointerPosition, screenToWorld, worldToScreen };
+//# sourceMappingURL=viewportCoords.js.map

package/dist/esm/components/primitives/viewport/viewportCoords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewportCoords.js","sources":["../../../../../../src/components/primitives/viewport/viewportCoords.ts"],"sourcesContent":[null],"names":[],"mappings":"AAGA;;;;AAIG;AACG,SAAU,aAAa,CAC3B,KAAc,EACd,SAA4B,EAAA;IAE5B,OAAO;QACL,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;QACzC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;KAC1C;AACH;AAEA;;;;AAIG;AACG,SAAU,aAAa,CAC3B,KAAc,EACd,SAA4B,EAAA;AAE5B,IAAA,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,IAAI,CAAC;IAC7B,OAAO;QACL,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC;QAC9B,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC;KAC/B;AACH;AAEA;;;AAGG;AACG,SAAU,0BAA0B,CACxC,KAA2C,EAC3C,QAAqB,EAAA;AAErB,IAAA,MAAM,IAAI,GAAG,QAAQ,CAAC,qBAAqB,EAAE;IAC7C,OAAO;AACL,QAAA,CAAC,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI;AAC5B,QAAA,CAAC,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG;KAC5B;AACH;;;;"}