@zoneflow/react 0.0.20 → 0.0.21

package/dist/canvas/UniverseCanvas.d.ts

@@ -1,4 +1,4 @@
-import type { UniverseLayoutModel, UniverseModel } from "@zoneflow/core";
+import type { UniverseLayoutModel, UniverseModel, ZoneId } from "@zoneflow/core";
 import { type BackgroundRenderer, type CameraState, type ComponentLayoutEngine, type DensityEngine, type DrawEngine, type GraphLayoutEngine, type GridOptions, type RendererFrame, type PathComponentRendererMap, type RendererDebugOptions, type RendererInteractionHandlers, type ResolvePathColor, type ResolveZoneColor, type ResolveZoneShape, type TextScaleLevel, type ViewportConfig, type VisibilityEngine, type ZoneComponentRendererMap, type ZoneflowTheme } from "@zoneflow/renderer-dom";
 import { type ZoneMoveEditorConfig } from "../editor/ZoneMoveEditorOverlay";
 import { type BackgroundComponent, type PathSlotComponentMap, type ZoneSlotComponentMap } from "../slots/slotComponents";
@@ -30,4 +30,32 @@ export type UniverseCanvasProps = {
     onFrameChange?: (frame: RendererFrame | null) => void;
     debug?: RendererDebugOptions;
 };
-export declare function UniverseCanvas({ model, layoutModel, theme, textScale, viewport, grid, graphLayoutEngine, densityEngine, visibilityEngine, componentLayoutEngine, drawEngine, zoneComponentRenderers, pathComponentRenderers, resolveZoneShape, resolveZoneColor, resolvePathColor, zoneComponents, pathComponents, backgroundRenderer, background, interactionHandlers, zoneMoveEditor, cameraState, onCameraChange, onFrameChange, debug, }: UniverseCanvasProps): import("react/jsx-runtime").JSX.Element;
+export type UniverseCanvasFocusZoneOptions = {
+    /**
+     * 이동 후 zoom. 미지정 시 현재 zoom 을 유지합니다.
+     * 카메라 컨트롤과 동일하게 0.25 ~ 3 범위로 clamp 됩니다.
+     */
+    zoom?: number;
+};
+export type UniverseCanvasHandle = {
+    /**
+     * 특정 zone 이 화면 중앙에 오도록 카메라를 이동합니다.
+     *
+     * - 아직 첫 프레임이 그려지지 않았거나 zone 을 찾지 못하면 `false` 를 반환합니다.
+     * - controlled camera (`cameraState`/`onCameraChange`) 모드에서도 동작합니다 —
+     *   계산된 카메라가 `onCameraChange` 로 전달됩니다.
+     */
+    focusZone: (zoneId: ZoneId, options?: UniverseCanvasFocusZoneOptions) => boolean;
+};
+/**
+ * zone 이 뷰포트 중앙에 오는 CameraState 를 계산합니다.
+ * ref 핸들 없이 controlled camera 를 직접 관리하는 쪽에서 사용할 수 있습니다.
+ */
+export declare function computeZoneFocusCamera(params: {
+    frame: RendererFrame | null;
+    zoneId: ZoneId;
+    viewportWidth: number;
+    viewportHeight: number;
+    zoom: number;
+}): CameraState | null;
+export declare const UniverseCanvas: import("react").ForwardRefExoticComponent<UniverseCanvasProps & import("react").RefAttributes<UniverseCanvasHandle>>;

package/dist/canvas/UniverseCanvas.js

@@ -1,23 +1,42 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, } from "react";
 import { screenPointToWorldPoint } from "@zoneflow/editor-dom";
 import { createRenderer, } from "@zoneflow/renderer-dom";
-import { useCameraControls } from "../controls/useCameraControls";
+import { CAMERA_MAX_ZOOM, CAMERA_MIN_ZOOM, useCameraControls, } from "../controls/useCameraControls";
 import { ZoneMoveEditorOverlay, } from "../editor/ZoneMoveEditorOverlay";
 import { resolvePermissions } from "../editor/editorPermissions";
 import { SlotPortals, } from "../slots/slotComponents";
+/**
+ * zone 이 뷰포트 중앙에 오는 CameraState 를 계산합니다.
+ * ref 핸들 없이 controlled camera 를 직접 관리하는 쪽에서 사용할 수 있습니다.
+ */
+export function computeZoneFocusCamera(params) {
+    const { frame, zoneId, viewportWidth, viewportHeight, zoom } = params;
+    const rect = frame?.pipeline.graphLayout.zonesById[zoneId]?.rect;
+    if (!rect)
+        return null;
+    if (viewportWidth <= 0 || viewportHeight <= 0)
+        return null;
+    return {
+        x: viewportWidth / 2 - (rect.x + rect.width / 2) * zoom,
+        y: viewportHeight / 2 - (rect.y + rect.height / 2) * zoom,
+        zoom,
+    };
+}
 const DEFAULT_CAMERA = {
     x: 0,
     y: 0,
     zoom: 1,
 };
 const noopRenderer = () => { };
-export function UniverseCanvas({ model, layoutModel, theme, textScale = "md", viewport, grid, graphLayoutEngine, densityEngine, visibilityEngine, componentLayoutEngine, drawEngine, zoneComponentRenderers, pathComponentRenderers, resolveZoneShape, resolveZoneColor, resolvePathColor, zoneComponents, pathComponents, backgroundRenderer, background, interactionHandlers, zoneMoveEditor, cameraState, onCameraChange, onFrameChange, debug, }) {
+const HOST_RESIZE_DEBOUNCE_MS = 150;
+export const UniverseCanvas = forwardRef(function UniverseCanvas({ model, layoutModel, theme, textScale = "md", viewport, grid, graphLayoutEngine, densityEngine, visibilityEngine, componentLayoutEngine, drawEngine, zoneComponentRenderers, pathComponentRenderers, resolveZoneShape, resolveZoneColor, resolvePathColor, zoneComponents, pathComponents, backgroundRenderer, background, interactionHandlers, zoneMoveEditor, cameraState, onCameraChange, onFrameChange, debug, }, handleRef) {
     const viewportRef = useRef(null);
     const ref = useRef(null);
     const rendererRef = useRef(createRenderer());
     const [internalCamera, setInternalCamera] = useState(DEFAULT_CAMERA);
     const [frame, setFrame] = useState(null);
+    const frameRef = useRef(null);
     const [exclusionState, setExclusionState] = useState(undefined);
     const [mounts, setMounts] = useState({
         zones: [],
@@ -83,6 +102,24 @@ export function UniverseCanvas({ model, layoutModel, theme, textScale = "md", vi
         camera,
         setCamera,
     });
+    const focusZone = useCallback((zoneId, options) => {
+        const viewportEl = viewportRef.current;
+        if (!viewportEl)
+            return false;
+        const zoom = Math.min(Math.max(options?.zoom ?? cameraRef.current.zoom, CAMERA_MIN_ZOOM), CAMERA_MAX_ZOOM);
+        const nextCamera = computeZoneFocusCamera({
+            frame: frameRef.current,
+            zoneId,
+            viewportWidth: viewportEl.clientWidth,
+            viewportHeight: viewportEl.clientHeight,
+            zoom,
+        });
+        if (!nextCamera)
+            return false;
+        setCamera(nextCamera);
+        return true;
+    }, [setCamera]);
+    useImperativeHandle(handleRef, () => ({ focusZone }), [focusZone]);
     useEffect(() => {
         if (!ref.current)
             return;
@@ -91,6 +128,53 @@ export function UniverseCanvas({ model, layoutModel, theme, textScale = "md", vi
             rendererRef.current.destroy();
         };
     }, []);
+    // 렌더러는 update 시점에 host.clientWidth/Height 로 world viewport 를 계산해
+    // 화면 밖 zone/path 노드를 컬링한다. props 가 전혀 안 바뀌는 정적 viewer 는
+    // update 가 다시 돌지 않아 mount 시점 측정값이 stale 해질 수 있으므로
+    // (초기 0×0 측정, 윈도우/컨테이너 리사이즈 등) host 크기 변화를 감지해 재렌더한다.
+    // update 한 번이 캔버스 전체 redraw 라 리사이즈 중 매 프레임 그리지 않고,
+    // 크기 변화가 멈춘 시점에 한 번만 반영한다 (debounce).
+    const [hostSizeVersion, setHostSizeVersion] = useState(0);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        if (typeof ResizeObserver === "undefined")
+            return;
+        let lastWidth = el.clientWidth;
+        let lastHeight = el.clientHeight;
+        let debounceTimer = null;
+        const observer = new ResizeObserver(() => {
+            const nextWidth = el.clientWidth;
+            const nextHeight = el.clientHeight;
+            if (nextWidth === lastWidth && nextHeight === lastHeight)
+                return;
+            // 0×0 측정 상태에서는 아무것도 안 그려져 있으므로, 처음 실제 크기를
+            // 얻는 순간만큼은 디바운스 없이 즉시 그려 mount 직후 공백을 줄인다.
+            const wasEmpty = lastWidth === 0 || lastHeight === 0;
+            lastWidth = nextWidth;
+            lastHeight = nextHeight;
+            if (debounceTimer !== null) {
+                window.clearTimeout(debounceTimer);
+                debounceTimer = null;
+            }
+            if (wasEmpty) {
+                setHostSizeVersion((version) => version + 1);
+                return;
+            }
+            debounceTimer = window.setTimeout(() => {
+                debounceTimer = null;
+                setHostSizeVersion((version) => version + 1);
+            }, HOST_RESIZE_DEBOUNCE_MS);
+        });
+        observer.observe(el);
+        return () => {
+            observer.disconnect();
+            if (debounceTimer !== null) {
+                window.clearTimeout(debounceTimer);
+            }
+        };
+    }, []);
     useEffect(() => {
         if (zoneMoveEditor?.enabled)
             return;
@@ -120,6 +204,7 @@ export function UniverseCanvas({ model, layoutModel, theme, textScale = "md", vi
             exclusionState,
             debug,
         });
+        frameRef.current = frame ?? null;
         setFrame(frame ?? null);
         setMounts(frame?.mounts ?? {
             zones: [],
@@ -155,6 +240,7 @@ export function UniverseCanvas({ model, layoutModel, theme, textScale = "md", vi
         cameraState,
         onCameraChange,
         onFrameChange,
+        hostSizeVersion,
     ]);
     return (_jsxs("div", { ref: viewportRef, onDragOver: (event) => {
             if (!externalDropEnabled)
@@ -198,4 +284,4 @@ export function UniverseCanvas({ model, layoutModel, theme, textScale = "md", vi
                     inset: 0,
                     zIndex: 1,
                 } }), _jsx(SlotPortals, { mounts: mounts, zoneComponents: zoneComponents, pathComponents: pathComponents, background: background }), _jsx(ZoneMoveEditorOverlay, { model: model, layoutModel: layoutModel, camera: camera, frame: frame, zoneComponents: zoneComponents, pathComponents: pathComponents, editor: zoneMoveEditor, resolveZoneShape: resolveZoneShape, onExclusionStateChange: setExclusionState })] }));
-}
+});

package/dist/controls/useCameraControls.d.ts

@@ -5,5 +5,7 @@ type UseCameraControlsParams = {
     camera: CameraState;
     setCamera: React.Dispatch<React.SetStateAction<CameraState>>;
 };
+export declare const CAMERA_MIN_ZOOM = 0.25;
+export declare const CAMERA_MAX_ZOOM = 3;
 export declare function useCameraControls({ hostRef, camera, setCamera, }: UseCameraControlsParams): void;
 export {};

package/dist/controls/useCameraControls.js

@@ -1,6 +1,8 @@
 import { useEffect, useRef } from "react";
-const MIN_ZOOM = 0.25;
-const MAX_ZOOM = 3;
+export const CAMERA_MIN_ZOOM = 0.25;
+export const CAMERA_MAX_ZOOM = 3;
+const MIN_ZOOM = CAMERA_MIN_ZOOM;
+const MAX_ZOOM = CAMERA_MAX_ZOOM;
 const ZOOM_STEP = 1.1;
 const TOUCH_PAN_MIN_POINTERS = 2;
 function clamp(value, min, max) {

package/dist/editor/UniverseEditorCanvas.d.ts

@@ -1,4 +1,5 @@
-import { type UniverseCanvasProps } from "../canvas/UniverseCanvas";
+import type { ZoneId } from "@zoneflow/core";
+import { type UniverseCanvasFocusZoneOptions, type UniverseCanvasProps } from "../canvas/UniverseCanvas";
 import type { ZoneMoveEditorConfig } from "./ZoneMoveEditorOverlay";
 import type { UniverseEditorController } from "./useUniverseEditor";
 type ControlledZoneMoveEditorConfig = Omit<ZoneMoveEditorConfig, "enabled" | "gridSnap" | "onModelChange" | "onLayoutModelChange" | "onTransactionStart" | "onTransactionCommit" | "onTransactionCancel" | "history">;
@@ -6,5 +7,14 @@ export type UniverseEditorCanvasProps = Omit<UniverseCanvasProps, "model" | "lay
     editor: UniverseEditorController;
     editorConfig?: ControlledZoneMoveEditorConfig;
 };
-export declare function UniverseEditorCanvas(props: UniverseEditorCanvasProps): import("react/jsx-runtime").JSX.Element;
+export type UniverseEditorCanvasHandle = {
+    /** 특정 zone 이 화면 중앙에 오도록 카메라를 이동. zone 을 못 찾으면 false. */
+    focusZone: (zoneId: ZoneId, options?: UniverseCanvasFocusZoneOptions) => boolean;
+    /** 모든 zone/path 가 화면에 들어오도록 카메라를 맞춤. */
+    fitToView: () => void;
+};
+export declare const UniverseEditorCanvas: import("react").ForwardRefExoticComponent<Omit<UniverseCanvasProps, "model" | "layoutModel" | "zoneMoveEditor" | "cameraState" | "onCameraChange" | "onFrameChange"> & {
+    editor: UniverseEditorController;
+    editorConfig?: ControlledZoneMoveEditorConfig;
+} & import("react").RefAttributes<UniverseEditorCanvasHandle>>;
 export {};

package/dist/editor/UniverseEditorCanvas.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useMemo, useRef, useState } from "react";
-import { UniverseCanvas } from "../canvas/UniverseCanvas";
+import { forwardRef, useCallback, useImperativeHandle, useMemo, useRef, useState, } from "react";
+import { computeZoneFocusCamera, UniverseCanvas, } from "../canvas/UniverseCanvas";
 import { getGridToggleLabel, getGridSnapToggleLabel, getObjectSnapToggleLabel, getZoneflowEditorStrings, resolveEditorLocale, } from "./strings";
 import { resolveEditorTheme } from "./theme";
 const DEFAULT_CAMERA = {
@@ -69,7 +69,7 @@ function fitCameraToWorldRect(params) {
         zoom,
     };
 }
-export function UniverseEditorCanvas(props) {
+export const UniverseEditorCanvas = forwardRef(function UniverseEditorCanvas(props, handleRef) {
     const { editor, editorConfig, grid, ...canvasProps } = props;
     const hostRef = useRef(null);
     const frameRef = useRef(null);
@@ -129,6 +129,26 @@ export function UniverseEditorCanvas(props) {
             viewportHeight: rect.height,
         }));
     }, []);
+    const focusZone = useCallback((zoneId, options) => {
+        const rect = hostRef.current?.getBoundingClientRect();
+        const frame = frameRef.current;
+        const zoneRect = frame?.pipeline.graphLayout.zonesById[zoneId]?.rect;
+        if (!rect || rect.width <= 0 || rect.height <= 0 || !zoneRect) {
+            return false;
+        }
+        setCamera((prev) => {
+            const zoom = clamp(options?.zoom ?? prev.zoom, MIN_ZOOM, MAX_ZOOM);
+            return (computeZoneFocusCamera({
+                frame,
+                zoneId,
+                viewportWidth: rect.width,
+                viewportHeight: rect.height,
+                zoom,
+            }) ?? prev);
+        });
+        return true;
+    }, []);
+    useImperativeHandle(handleRef, () => ({ focusZone, fitToView }), [focusZone, fitToView]);
     const zoneMoveEditor = editor.isEditMode
         ? {
             ...editorConfig,
@@ -241,4 +261,4 @@ export function UniverseEditorCanvas(props) {
                                     ...viewerHudButtonStyle,
                                     fontVariantNumeric: "tabular-nums",
                                 }, children: [Math.round(camera.zoom * 100), "%"] })) : (_jsx("div", {})), editorConfig?.overlayControls?.showZoomControls !== false ? (_jsx("button", { type: "button", onClick: () => zoomAtCenter(ZOOM_STEP), style: viewerHudButtonStyle, children: "+" })) : (_jsx("div", {}))] })) : null] })) : null] }));
-}
+});

package/dist/editor/ZoneMoveEditorOverlay.d.ts

@@ -103,6 +103,20 @@ export type ZoneMoveEditorConfig = {
     onPathLabelClick?: (event: PathLabelEventPayload) => void;
     onPathLabelDoubleClick?: (event: PathLabelEventPayload) => void;
     onPathLabelContextMenu?: (event: PathLabelEventPayload) => void;
+    /**
+     * zone 선택이 바뀔 때마다 호출됩니다.
+     *
+     * - 단일 클릭, shift/ctrl/cmd 토글, 마퀴(드래그 박스) 선택 모두 같은 콜백으로 옵니다.
+     * - 선택 해제(빈 캔버스 클릭, 편집 모드 종료, 선택된 zone 삭제 등) 시 빈 배열로 호출됩니다.
+     * - 선택 내용이 실제로 바뀔 때만 호출됩니다 (같은 zone 재클릭 시 재호출되지 않음).
+     * - zone 과 path 선택은 상호 배타라서, zone 선택 시 path 선택이 비워지며
+     *   `onPathSelectionChange` 도 빈 배열로 함께 호출될 수 있습니다.
+     */
+    onZoneSelectionChange?: (zoneIds: ZoneId[]) => void;
+    /**
+     * path 선택이 바뀔 때마다 호출됩니다. 규칙은 `onZoneSelectionChange` 와 동일합니다.
+     */
+    onPathSelectionChange?: (pathIds: PathId[]) => void;
     /**
      * 외부에서 zone 간 path 연결 가능 여부를 검증하는 콜백.
      *

package/dist/editor/ZoneMoveEditorOverlay.js

@@ -176,6 +176,10 @@ function togglePathSelection(pathIds, pathId) {
         ? pathIds.filter((current) => current !== pathId)
         : [...pathIds, pathId];
 }
+function areIdListsEqual(left, right) {
+    return (left.length === right.length &&
+        left.every((id, index) => id === right[index]));
+}
 function clamp(value, min, max) {
     return Math.min(Math.max(value, min), max);
 }
@@ -576,6 +580,8 @@ export function ZoneMoveEditorOverlay(props) {
     const marqueeSelectionRef = useRef(null);
     const selectedZoneIdsRef = useRef([]);
     const selectedPathIdsRef = useRef([]);
+    const notifiedZoneSelectionRef = useRef([]);
+    const notifiedPathSelectionRef = useRef([]);
     const longPressRef = useRef(null);
     const longPressTimerRef = useRef(null);
     const deleteUndoTimerRef = useRef(null);
@@ -601,6 +607,8 @@ export function ZoneMoveEditorOverlay(props) {
         canConnectPath: editor?.canConnectPath,
         onPathCreated: editor?.onPathCreated,
         onPathDropOnEmptySpace: editor?.onPathDropOnEmptySpace,
+        onZoneSelectionChange: editor?.onZoneSelectionChange,
+        onPathSelectionChange: editor?.onPathSelectionChange,
         resolveZoneShape,
         onExclusionStateChange,
     });
@@ -622,6 +630,8 @@ export function ZoneMoveEditorOverlay(props) {
             canConnectPath: editor?.canConnectPath,
             onPathCreated: editor?.onPathCreated,
             onPathDropOnEmptySpace: editor?.onPathDropOnEmptySpace,
+            onZoneSelectionChange: editor?.onZoneSelectionChange,
+            onPathSelectionChange: editor?.onPathSelectionChange,
             resolveZoneShape,
             onExclusionStateChange,
         };
@@ -640,6 +650,22 @@ export function ZoneMoveEditorOverlay(props) {
     useEffect(() => {
         selectedPathIdsRef.current = selectedPathIds;
     }, [selectedPathIds]);
+    // state 배열의 identity 가 아니라 내용이 바뀔 때만 외부에 알린다 —
+    // 같은 선택을 유지한 채 새 배열로 set 되는 경로(모델 prune, 재클릭 등)가 많다.
+    useEffect(() => {
+        if (areIdListsEqual(notifiedZoneSelectionRef.current, selectedZoneIds)) {
+            return;
+        }
+        notifiedZoneSelectionRef.current = selectedZoneIds;
+        latestRef.current.onZoneSelectionChange?.([...selectedZoneIds]);
+    }, [selectedZoneIds]);
+    useEffect(() => {
+        if (areIdListsEqual(notifiedPathSelectionRef.current, selectedPathIds)) {
+            return;
+        }
+        notifiedPathSelectionRef.current = selectedPathIds;
+        latestRef.current.onPathSelectionChange?.([...selectedPathIds]);
+    }, [selectedPathIds]);
     useEffect(() => {
         if (typeof window === "undefined")
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoneflow/react",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "license": "MIT",
   "description": "React renderer and editor components for Zoneflow.",
   "type": "module",
@@ -23,9 +23,9 @@
     "react-dom": "^18 || ^19"
   },
   "dependencies": {
-    "@zoneflow/core": "0.0.20",
-    "@zoneflow/editor-dom": "0.0.20",
-    "@zoneflow/renderer-dom": "0.0.20"
+    "@zoneflow/core": "0.0.21",
+    "@zoneflow/editor-dom": "0.0.21",
+    "@zoneflow/renderer-dom": "0.0.21"
   },
   "devDependencies": {
     "@types/react": "^19.2.14",