canvu-react 0.4.63 → 0.4.64

package/dist/{types--jCoyZIF.d.cts → types-Ce4-OZbd.d.cts}

@@ -202,6 +202,101 @@ type VectorItemsChangeInfo = {
     itemIds?: readonly string[];
     toolId?: string;
 };
+/**
+ * Interaction categories emitted by the React viewport lifecycle hooks.
+ *
+ * These describe pointer gestures owned by `VectorViewport`, not every possible
+ * input event. Camera pan/zoom, keyboard shortcuts, paste/drop, toolbar clicks,
+ * and custom UI events are intentionally outside this lifecycle.
+ */
+type CanvuInteractionKind = "move" | "resize" | "rotate" | "marquee" | "stroke" | "erase" | "tap" | "place" | "select-mode-item-click";
+/**
+ * World and client coordinates for a viewport interaction sample.
+ *
+ * `start` stays fixed for the accepted gesture. `current` is updated for the
+ * after hook so integrations can compare where the gesture began and ended.
+ */
+type CanvuInteractionPoint = {
+    readonly worldX: number;
+    readonly worldY: number;
+    readonly clientX: number;
+    readonly clientY: number;
+};
+/**
+ * Stable interaction metadata passed to before/after interaction hooks.
+ *
+ * Use this for custom tool behavior that needs to observe or claim a viewport
+ * gesture before Canvu mutates selection, previews, or items. Do not use it to
+ * intercept item-list writes; use `wrapOnItemsChange` when you need exact
+ * document mutation middleware.
+ *
+ * @example
+ * ```tsx
+ * <VectorViewport
+ *   onBeforeInteraction={(detail) =>
+ *     detail.toolId === "review-pin" ? "handled" : undefined
+ *   }
+ * />
+ * ```
+ */
+type CanvuInteractionDetail = {
+    /** Stable id for this accepted pointer gesture. */
+    readonly interactionId: string;
+    /** Canvu interaction category resolved before built-in state changes. */
+    readonly kind: CanvuInteractionKind;
+    /** Active viewport tool when the gesture started. */
+    readonly toolId: string;
+    /** Browser pointer type such as `"mouse"`, `"pen"`, or `"touch"`. */
+    readonly pointerType: string;
+    /** Pointer button reported by the start event. Touch fallbacks use `0`. */
+    readonly button: number;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly metaKey: boolean;
+    readonly ctrlKey: boolean;
+    /** Pointer position when the interaction started. */
+    readonly start: CanvuInteractionPoint;
+    /** Latest pointer position known to Canvu for this interaction. */
+    readonly current: CanvuInteractionPoint;
+    /** Selection snapshot before Canvu applies this interaction. */
+    readonly selectedIds: readonly string[];
+    /** Primary target item ids when the interaction has known targets. */
+    readonly itemIds: readonly string[];
+    /** Current viewport items when the interaction was accepted. */
+    readonly items: readonly VectorSceneItem[];
+};
+/** Return value that lets a before hook claim a gesture. */
+type CanvuBeforeInteractionResult = "handled" | undefined;
+/**
+ * Runs after Canvu resolves an interaction kind and before built-in mutation.
+ *
+ * Return `"handled"` to claim the gesture. Canvu will prevent the pointer event,
+ * skip later before hooks, skip built-in behavior, and will not emit an after
+ * hook for that gesture.
+ */
+type CanvuBeforeInteractionHook = (detail: CanvuInteractionDetail) => CanvuBeforeInteractionResult;
+/** Final state reported when an accepted interaction leaves Canvu's active state. */
+type CanvuInteractionOutcome = "completed" | "cancelled";
+/**
+ * Metadata passed to after interaction hooks.
+ *
+ * `info` mirrors the best-effort `VectorItemsChangeInfo` used by
+ * `onItemsChange`; it is intentionally advisory and may be omitted when the
+ * gesture did not write items.
+ */
+type CanvuAfterInteractionDetail = CanvuInteractionDetail & {
+    readonly outcome: CanvuInteractionOutcome;
+    readonly info?: VectorItemsChangeInfo;
+};
+/**
+ * Runs once when an accepted Canvu interaction completes or is cancelled.
+ *
+ * Use this for analytics, custom UI cleanup, or tool-specific side effects that
+ * should happen after Canvu's gesture lifecycle finishes. Use
+ * `wrapOnItemsChange` instead when you need to transform or persist item
+ * mutations.
+ */
+type CanvuAfterInteractionHook = (detail: CanvuAfterInteractionDetail) => void;
 /**
  * Imperative API for pan/zoom and integrations (e.g. AI agents following a region).
  * Call {@link requestRender} after mutating the {@link Camera2D} from {@link getCamera}.
@@ -278,6 +373,24 @@ type VectorViewportProps = {
      * omit `info`.
      */
     onItemsChange?: (items: VectorSceneItem[], info?: VectorItemsChangeInfo) => void;
+    /**
+     * Runs before a Canvu-owned pointer interaction mutates viewport state.
+     *
+     * Return `"handled"` to claim the gesture and prevent Canvu's built-in
+     * selection, drawing, placement, or resize behavior for that pointerdown.
+     * Prefer this for custom tool behavior. Prefer `wrapOnItemsChange` when your
+     * integration needs document mutation middleware instead.
+     */
+    onBeforeInteraction?: CanvuBeforeInteractionHook;
+    /**
+     * Runs once after an accepted Canvu-owned pointer interaction completes or is
+     * cancelled.
+     *
+     * This is useful for analytics, custom tool cleanup, and UI side effects.
+     * The optional `info` payload is best-effort mutation metadata; continue to use
+     * `wrapOnItemsChange` for exact item-list interception.
+     */
+    onAfterInteraction?: CanvuAfterInteractionHook;
     /**
      * Fires when a link/bookmark item is activated (double-click / double-tap).
      * When omitted, the link opens in a new browser tab by default (web only).
@@ -417,6 +530,19 @@ type CanvasPluginContribution = {
     viewportProps?: Partial<Pick<VectorViewportProps, "remotePresence" | "presenceOverlay">>;
     /** Event callbacks chained into the viewport without manual wiring in app code. */
     callbacks?: Partial<Pick<VectorViewportProps, "onWorldPointerDown" | "onWorldPointerMove" | "onWorldPointerLeave" | "onPlacementPreviewChange" | "onCameraChange">>;
+    /**
+     * Hooks around Canvu-owned pointer interactions.
+     *
+     * Use these for custom tool behavior that needs to observe or claim a gesture
+     * before the viewport mutates state. Use `wrapOnItemsChange` for exact item
+     * mutation middleware.
+     */
+    interactionHooks?: {
+        /** Return `"handled"` to claim the gesture and skip Canvu's built-in behavior. */
+        onBeforeInteraction?: CanvuBeforeInteractionHook;
+        /** Runs once when an accepted gesture completes or is cancelled. */
+        onAfterInteraction?: CanvuAfterInteractionHook;
+    };
     /** Middleware around `onItemsChange` for collaboration, comments, persistence, etc. */
     wrapOnItemsChange?: (nextItems: VectorSceneItem[], ctx: CanvasPluginItemsChangeMiddlewareContext, info?: VectorItemsChangeInfo) => void;
 };
@@ -498,4 +624,4 @@ declare function useCanvuResolvedTools(): VectorToolDefinition[];
  */
 declare function useCanvuPluginContribution(pluginId: string, contribution: CanvasPluginContribution): void;
 
-export { useCanvuPluginContribution as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, useCanvuResolvedTools as D, useCanvuViewportContext as E, type PlacementPreview as P, type SelectModeItemClickDetail as S, type VectorToolDefinition as V, type WorldPointerDownDetail as W, type CanvasPlugin as a, VectorSelectionInspector as b, type CanvasPluginComponentProps as c, type CanvasPluginContribution as d, type CanvasPluginItemsChangeMiddlewareContext as e, type CanvasPluginRenderContext as f, type CanvuChromeActiveToolStyle as g, CanvuChromeContext as h, type CanvuChromeContextValue as i, type CanvuChromeSelectionStyleChange as j, CanvuPluginContext as k, type CanvuPluginContextValue as l, type CanvuPluginViewportSnapshot as m, type SelectModeItemClickResult as n, type VectorCanvasSpacePosition as o, type VectorItemsChangeInfo as p, type VectorItemsChangeMotive as q, type VectorSelectionInspectorProps as r, VectorViewport as s, type VectorViewportHandle as t, type VectorViewportProps as u, createCanvuPlugin as v, getBoardPositionStyle as w, useCanvuChromeContext as x, useCanvuDocumentContext as y, useCanvuPluginContext as z };
+export { VectorViewport as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, type VectorViewportHandle as D, type VectorViewportProps as E, createCanvuPlugin as F, getBoardPositionStyle as G, useCanvuChromeContext as H, useCanvuDocumentContext as I, useCanvuPluginContext as J, useCanvuPluginContribution as K, useCanvuResolvedTools as L, useCanvuViewportContext as M, type PlacementPreview as P, type SelectModeItemClickDetail as S, type VectorToolDefinition as V, type WorldPointerDownDetail as W, type CanvuBeforeInteractionHook as a, type CanvuAfterInteractionHook as b, type CanvasPlugin as c, VectorSelectionInspector as d, type CanvasPluginComponentProps as e, type CanvasPluginContribution as f, type CanvasPluginItemsChangeMiddlewareContext as g, type CanvasPluginRenderContext as h, type CanvuAfterInteractionDetail as i, type CanvuBeforeInteractionResult as j, type CanvuChromeActiveToolStyle as k, CanvuChromeContext as l, type CanvuChromeContextValue as m, type CanvuChromeSelectionStyleChange as n, type CanvuInteractionDetail as o, type CanvuInteractionKind as p, type CanvuInteractionOutcome as q, type CanvuInteractionPoint as r, CanvuPluginContext as s, type CanvuPluginContextValue as t, type CanvuPluginViewportSnapshot as u, type SelectModeItemClickResult as v, type VectorCanvasSpacePosition as w, type VectorItemsChangeInfo as x, type VectorItemsChangeMotive as y, type VectorSelectionInspectorProps as z };

package/dist/{types-C_PMen-D.d.ts → types-PsLgDGZT.d.ts}

@@ -202,6 +202,101 @@ type VectorItemsChangeInfo = {
     itemIds?: readonly string[];
     toolId?: string;
 };
+/**
+ * Interaction categories emitted by the React viewport lifecycle hooks.
+ *
+ * These describe pointer gestures owned by `VectorViewport`, not every possible
+ * input event. Camera pan/zoom, keyboard shortcuts, paste/drop, toolbar clicks,
+ * and custom UI events are intentionally outside this lifecycle.
+ */
+type CanvuInteractionKind = "move" | "resize" | "rotate" | "marquee" | "stroke" | "erase" | "tap" | "place" | "select-mode-item-click";
+/**
+ * World and client coordinates for a viewport interaction sample.
+ *
+ * `start` stays fixed for the accepted gesture. `current` is updated for the
+ * after hook so integrations can compare where the gesture began and ended.
+ */
+type CanvuInteractionPoint = {
+    readonly worldX: number;
+    readonly worldY: number;
+    readonly clientX: number;
+    readonly clientY: number;
+};
+/**
+ * Stable interaction metadata passed to before/after interaction hooks.
+ *
+ * Use this for custom tool behavior that needs to observe or claim a viewport
+ * gesture before Canvu mutates selection, previews, or items. Do not use it to
+ * intercept item-list writes; use `wrapOnItemsChange` when you need exact
+ * document mutation middleware.
+ *
+ * @example
+ * ```tsx
+ * <VectorViewport
+ *   onBeforeInteraction={(detail) =>
+ *     detail.toolId === "review-pin" ? "handled" : undefined
+ *   }
+ * />
+ * ```
+ */
+type CanvuInteractionDetail = {
+    /** Stable id for this accepted pointer gesture. */
+    readonly interactionId: string;
+    /** Canvu interaction category resolved before built-in state changes. */
+    readonly kind: CanvuInteractionKind;
+    /** Active viewport tool when the gesture started. */
+    readonly toolId: string;
+    /** Browser pointer type such as `"mouse"`, `"pen"`, or `"touch"`. */
+    readonly pointerType: string;
+    /** Pointer button reported by the start event. Touch fallbacks use `0`. */
+    readonly button: number;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly metaKey: boolean;
+    readonly ctrlKey: boolean;
+    /** Pointer position when the interaction started. */
+    readonly start: CanvuInteractionPoint;
+    /** Latest pointer position known to Canvu for this interaction. */
+    readonly current: CanvuInteractionPoint;
+    /** Selection snapshot before Canvu applies this interaction. */
+    readonly selectedIds: readonly string[];
+    /** Primary target item ids when the interaction has known targets. */
+    readonly itemIds: readonly string[];
+    /** Current viewport items when the interaction was accepted. */
+    readonly items: readonly VectorSceneItem[];
+};
+/** Return value that lets a before hook claim a gesture. */
+type CanvuBeforeInteractionResult = "handled" | undefined;
+/**
+ * Runs after Canvu resolves an interaction kind and before built-in mutation.
+ *
+ * Return `"handled"` to claim the gesture. Canvu will prevent the pointer event,
+ * skip later before hooks, skip built-in behavior, and will not emit an after
+ * hook for that gesture.
+ */
+type CanvuBeforeInteractionHook = (detail: CanvuInteractionDetail) => CanvuBeforeInteractionResult;
+/** Final state reported when an accepted interaction leaves Canvu's active state. */
+type CanvuInteractionOutcome = "completed" | "cancelled";
+/**
+ * Metadata passed to after interaction hooks.
+ *
+ * `info` mirrors the best-effort `VectorItemsChangeInfo` used by
+ * `onItemsChange`; it is intentionally advisory and may be omitted when the
+ * gesture did not write items.
+ */
+type CanvuAfterInteractionDetail = CanvuInteractionDetail & {
+    readonly outcome: CanvuInteractionOutcome;
+    readonly info?: VectorItemsChangeInfo;
+};
+/**
+ * Runs once when an accepted Canvu interaction completes or is cancelled.
+ *
+ * Use this for analytics, custom UI cleanup, or tool-specific side effects that
+ * should happen after Canvu's gesture lifecycle finishes. Use
+ * `wrapOnItemsChange` instead when you need to transform or persist item
+ * mutations.
+ */
+type CanvuAfterInteractionHook = (detail: CanvuAfterInteractionDetail) => void;
 /**
  * Imperative API for pan/zoom and integrations (e.g. AI agents following a region).
  * Call {@link requestRender} after mutating the {@link Camera2D} from {@link getCamera}.
@@ -278,6 +373,24 @@ type VectorViewportProps = {
      * omit `info`.
      */
     onItemsChange?: (items: VectorSceneItem[], info?: VectorItemsChangeInfo) => void;
+    /**
+     * Runs before a Canvu-owned pointer interaction mutates viewport state.
+     *
+     * Return `"handled"` to claim the gesture and prevent Canvu's built-in
+     * selection, drawing, placement, or resize behavior for that pointerdown.
+     * Prefer this for custom tool behavior. Prefer `wrapOnItemsChange` when your
+     * integration needs document mutation middleware instead.
+     */
+    onBeforeInteraction?: CanvuBeforeInteractionHook;
+    /**
+     * Runs once after an accepted Canvu-owned pointer interaction completes or is
+     * cancelled.
+     *
+     * This is useful for analytics, custom tool cleanup, and UI side effects.
+     * The optional `info` payload is best-effort mutation metadata; continue to use
+     * `wrapOnItemsChange` for exact item-list interception.
+     */
+    onAfterInteraction?: CanvuAfterInteractionHook;
     /**
      * Fires when a link/bookmark item is activated (double-click / double-tap).
      * When omitted, the link opens in a new browser tab by default (web only).
@@ -417,6 +530,19 @@ type CanvasPluginContribution = {
     viewportProps?: Partial<Pick<VectorViewportProps, "remotePresence" | "presenceOverlay">>;
     /** Event callbacks chained into the viewport without manual wiring in app code. */
     callbacks?: Partial<Pick<VectorViewportProps, "onWorldPointerDown" | "onWorldPointerMove" | "onWorldPointerLeave" | "onPlacementPreviewChange" | "onCameraChange">>;
+    /**
+     * Hooks around Canvu-owned pointer interactions.
+     *
+     * Use these for custom tool behavior that needs to observe or claim a gesture
+     * before the viewport mutates state. Use `wrapOnItemsChange` for exact item
+     * mutation middleware.
+     */
+    interactionHooks?: {
+        /** Return `"handled"` to claim the gesture and skip Canvu's built-in behavior. */
+        onBeforeInteraction?: CanvuBeforeInteractionHook;
+        /** Runs once when an accepted gesture completes or is cancelled. */
+        onAfterInteraction?: CanvuAfterInteractionHook;
+    };
     /** Middleware around `onItemsChange` for collaboration, comments, persistence, etc. */
     wrapOnItemsChange?: (nextItems: VectorSceneItem[], ctx: CanvasPluginItemsChangeMiddlewareContext, info?: VectorItemsChangeInfo) => void;
 };
@@ -498,4 +624,4 @@ declare function useCanvuResolvedTools(): VectorToolDefinition[];
  */
 declare function useCanvuPluginContribution(pluginId: string, contribution: CanvasPluginContribution): void;
 
-export { useCanvuPluginContribution as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, useCanvuResolvedTools as D, useCanvuViewportContext as E, type PlacementPreview as P, type SelectModeItemClickDetail as S, type VectorToolDefinition as V, type WorldPointerDownDetail as W, type CanvasPlugin as a, VectorSelectionInspector as b, type CanvasPluginComponentProps as c, type CanvasPluginContribution as d, type CanvasPluginItemsChangeMiddlewareContext as e, type CanvasPluginRenderContext as f, type CanvuChromeActiveToolStyle as g, CanvuChromeContext as h, type CanvuChromeContextValue as i, type CanvuChromeSelectionStyleChange as j, CanvuPluginContext as k, type CanvuPluginContextValue as l, type CanvuPluginViewportSnapshot as m, type SelectModeItemClickResult as n, type VectorCanvasSpacePosition as o, type VectorItemsChangeInfo as p, type VectorItemsChangeMotive as q, type VectorSelectionInspectorProps as r, VectorViewport as s, type VectorViewportHandle as t, type VectorViewportProps as u, createCanvuPlugin as v, getBoardPositionStyle as w, useCanvuChromeContext as x, useCanvuDocumentContext as y, useCanvuPluginContext as z };
+export { VectorViewport as A, type BoardComponentPosition as B, type CustomShapePlacementOptions as C, type VectorViewportHandle as D, type VectorViewportProps as E, createCanvuPlugin as F, getBoardPositionStyle as G, useCanvuChromeContext as H, useCanvuDocumentContext as I, useCanvuPluginContext as J, useCanvuPluginContribution as K, useCanvuResolvedTools as L, useCanvuViewportContext as M, type PlacementPreview as P, type SelectModeItemClickDetail as S, type VectorToolDefinition as V, type WorldPointerDownDetail as W, type CanvuBeforeInteractionHook as a, type CanvuAfterInteractionHook as b, type CanvasPlugin as c, VectorSelectionInspector as d, type CanvasPluginComponentProps as e, type CanvasPluginContribution as f, type CanvasPluginItemsChangeMiddlewareContext as g, type CanvasPluginRenderContext as h, type CanvuAfterInteractionDetail as i, type CanvuBeforeInteractionResult as j, type CanvuChromeActiveToolStyle as k, CanvuChromeContext as l, type CanvuChromeContextValue as m, type CanvuChromeSelectionStyleChange as n, type CanvuInteractionDetail as o, type CanvuInteractionKind as p, type CanvuInteractionOutcome as q, type CanvuInteractionPoint as r, CanvuPluginContext as s, type CanvuPluginContextValue as t, type CanvuPluginViewportSnapshot as u, type SelectModeItemClickResult as v, type VectorCanvasSpacePosition as w, type VectorItemsChangeInfo as x, type VectorItemsChangeMotive as y, type VectorSelectionInspectorProps as z };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "canvu-react",
-	"version": "0.4.63",
+	"version": "0.4.64",
 	"description": "Vector-first infinite canvas (SVG) with pan, zoom, React bindings, and optional plugins",
 	"license": "MIT",
 	"type": "module",