@bwp-web/canvas 0.4.1 → 0.4.3

package/dist/Canvas/Canvas.d.ts

@@ -1,7 +1,17 @@
 import { Canvas as FabricCanvas } from 'fabric';
-import { CSSProperties } from 'react';
+import { type CSSProperties } from 'react';
 export interface CanvasProps {
+    /**
+     * Canvas width in pixels. When both `width` and `height` are provided,
+     * the canvas uses fixed dimensions. When omitted, the canvas auto-fills
+     * its parent container and resizes with it.
+     */
     width?: number;
+    /**
+     * Canvas height in pixels. When both `width` and `height` are provided,
+     * the canvas uses fixed dimensions. When omitted, the canvas auto-fills
+     * its parent container and resizes with it.
+     */
     height?: number;
     className?: string;
     style?: CSSProperties;

package/dist/Canvas/Canvas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Canvas.d.ts","sourceRoot":"","sources":["../../src/Canvas/Canvas.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,aAAa,EAAqB,MAAM,OAAO,CAAC;AAGzD,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;CAC1C;AAED,wBAAgB,MAAM,CAAC,EACrB,KAAW,EACX,MAAY,EACZ,SAAS,EACT,KAAK,EACL,OAAO,GACR,EAAE,WAAW,2CA2Bb"}
+{"version":3,"file":"Canvas.d.ts","sourceRoot":"","sources":["../../src/Canvas/Canvas.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,KAAK,aAAa,EAAqB,MAAM,OAAO,CAAC;AAG9D,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;CAC1C;AAED,wBAAgB,MAAM,CAAC,EACrB,KAAK,EACL,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,GACR,EAAE,WAAW,2CAqEb"}

package/dist/background.d.ts

@@ -1,4 +1,9 @@
 import { Canvas as FabricCanvas, FabricImage } from 'fabric';
+/**
+ * Get the source URL of the canvas background image, or `null` if no
+ * background image is set.
+ */
+export declare function getBackgroundSrc(canvas: FabricCanvas): string | null;
 export interface FitViewportOptions {
     /**
      * Fraction of the canvas to leave as empty margin around the image.
@@ -69,11 +74,18 @@ export interface ResizeImageOptions {
  * ```
  */
 export declare function resizeImageUrl(url: string, options?: ResizeImageOptions): Promise<ResizeResult>;
+export interface SetBackgroundImageOptions extends ResizeImageOptions {
+    /** Preserve the current background opacity when replacing the image. */
+    preserveOpacity?: boolean;
+}
 /**
  * Set an image URL as the canvas background image.
- * Pass `resize` options to downscale oversized images before loading;
- * omit to load the URL as-is.
+ *
+ * Pass options to control auto-resize (`maxSize`, `minSize`) and/or
+ * preserve the current background opacity when replacing the image.
+ * Omit to load the URL as-is without resizing.
+ *
  * Returns the created FabricImage for further manipulation.
  */
-export declare function setBackgroundImage(canvas: FabricCanvas, url: string, resize?: ResizeImageOptions): Promise<FabricImage>;
+export declare function setBackgroundImage(canvas: FabricCanvas, url: string, options?: SetBackgroundImageOptions): Promise<FabricImage>;
 //# sourceMappingURL=background.d.ts.map

package/dist/background.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"background.d.ts","sourceRoot":"","sources":["../src/background.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,WAAW,EAAW,MAAM,QAAQ,CAAC;AAatE,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,IAAI,CAiCN;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,GACd,IAAI,CAKN;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAGjE;AAID;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,OAAO,GAChB,IAAI,CAgBN;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAInE;AAID,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAkDvB;AAID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAUtB"}
+{"version":3,"file":"background.d.ts","sourceRoot":"","sources":["../src/background.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,WAAW,EAAW,MAAM,QAAQ,CAAC;AAWtE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAIpE;AAID,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,IAAI,CAiCN;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,GACd,IAAI,CAKN;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAGjE;AAID;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,OAAO,GAChB,IAAI,CAgBN;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAInE;AAID,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAkDvB;AAID,MAAM,WAAW,yBAA0B,SAAQ,kBAAkB;IACnE,wEAAwE;IACxE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,WAAW,CAAC,CAmBtB"}

package/dist/hooks/index.d.ts

@@ -2,4 +2,12 @@ export { useEditCanvas } from './useEditCanvas';
 export type { UseEditCanvasOptions } from './useEditCanvas';
 export { useViewCanvas } from './useViewCanvas';
 export type { UseViewCanvasOptions, ViewObjectStyle } from './useViewCanvas';
+export { useCanvasEvents } from './useCanvasEvents';
+export type { CanvasEventHandlers } from './useCanvasEvents';
+export { useCanvasTooltip } from './useCanvasTooltip';
+export type { UseCanvasTooltipOptions, CanvasTooltipState, } from './useCanvasTooltip';
+export { useCanvasClick } from './useCanvasClick';
+export type { UseCanvasClickOptions } from './useCanvasClick';
+export { useObjectOverlay } from './useObjectOverlay';
+export type { UseObjectOverlayOptions } from './useObjectOverlay';
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE7E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EACV,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/hooks/shared.d.ts

@@ -1,6 +1,6 @@
 import { type RefObject } from 'react';
-import { Canvas as FabricCanvas } from 'fabric';
-import { type ViewportController } from '../viewport';
+import { Canvas as FabricCanvas, type FabricObject } from 'fabric';
+import { type PanToObjectOptions, type ViewportController } from '../viewport';
 /** Sync React zoom state with the canvas zoom level. */
 export declare function syncZoom(canvasRef: RefObject<FabricCanvas | null>, setZoom: (z: number) => void): void;
 /**
@@ -11,6 +11,7 @@ export declare function createViewportActions(canvasRef: RefObject<FabricCanvas
     resetViewport: () => void;
     zoomIn: (step?: number) => void;
     zoomOut: (step?: number) => void;
+    panToObject: (object: FabricObject, panOpts?: PanToObjectOptions) => void;
 };
 /**
  * Resolve whether alignment should be enabled based on the master toggle

package/dist/hooks/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/hooks/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAGrB,wDAAwD;AACxD,wBAAgB,QAAQ,CACtB,SAAS,EAAE,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,EACzC,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,GAC3B,IAAI,CAGN;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,EACzC,WAAW,EAAE,SAAS,CAAC,kBAAkB,GAAG,IAAI,CAAC,EACjD,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI;;oBAaL,MAAM;qBAKL,MAAM;EAM/B;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,eAAe,EAAE,OAAO,GAAG,SAAS,EACpC,aAAa,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GAC1C,OAAO,CAGT"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/hooks/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AACnE,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAGrB,wDAAwD;AACxD,wBAAgB,QAAQ,CACtB,SAAS,EAAE,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,EACzC,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,GAC3B,IAAI,CAGN;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,EACzC,WAAW,EAAE,SAAS,CAAC,kBAAkB,GAAG,IAAI,CAAC,EACjD,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI;;oBAaL,MAAM;qBAKL,MAAM;0BAKD,YAAY,YAAY,kBAAkB;EAKxE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,eAAe,EAAE,OAAO,GAAG,SAAS,EACpC,aAAa,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GAC1C,OAAO,CAGT"}

package/dist/hooks/useCanvasClick.d.ts

@@ -0,0 +1,27 @@
+import { type RefObject } from 'react';
+import type { Canvas as FabricCanvas, FabricObject } from 'fabric';
+export interface UseCanvasClickOptions {
+    /** Maximum movement in pixels before the gesture is treated as a pan. Default: 5. */
+    threshold?: number;
+    /** Maximum duration in milliseconds for the gesture to count as a click. Default: 300. */
+    maxDuration?: number;
+}
+/**
+ * Distinguish clicks from pan gestures on a canvas.
+ *
+ * On view-mode canvases where pan is always active, a regular Fabric `mouse:up`
+ * fires for both clicks and drag-to-pan. This hook tracks pointer movement and
+ * timing to determine whether the user intended a click or a pan, then calls
+ * `onClick` only for genuine clicks.
+ *
+ * @example
+ * ```tsx
+ * useCanvasClick(view.canvasRef, (target) => {
+ *   if (target?.data?.id) {
+ *     navigate(`/locations/${target.data.id}`);
+ *   }
+ * });
+ * ```
+ */
+export declare function useCanvasClick(canvasRef: RefObject<FabricCanvas | null>, onClick: (target: FabricObject | undefined) => void, options?: UseCanvasClickOptions): void;
+//# sourceMappingURL=useCanvasClick.d.ts.map

package/dist/hooks/useCanvasClick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCanvasClick.d.ts","sourceRoot":"","sources":["../../src/hooks/useCanvasClick.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1D,OAAO,KAAK,EACV,MAAM,IAAI,YAAY,EAEtB,YAAY,EACb,MAAM,QAAQ,CAAC;AAEhB,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,EACzC,OAAO,EAAE,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,KAAK,IAAI,EACnD,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA2DN"}

package/dist/hooks/useCanvasEvents.d.ts

@@ -0,0 +1,35 @@
+import { type RefObject } from 'react';
+import type { Canvas as FabricCanvas, CanvasEvents } from 'fabric';
+/**
+ * A map of Fabric canvas event names to their handler functions.
+ *
+ * Each key is a valid `CanvasEvents` event name and each handler receives the
+ * correctly-typed event payload. Set a handler to `undefined` to skip it.
+ *
+ * Common events include:
+ * - `'object:added'`, `'object:removed'`, `'object:modified'`
+ * - `'mouse:over'`, `'mouse:out'`, `'mouse:down'`, `'mouse:up'`, `'mouse:move'`
+ * - `'mouse:wheel'`, `'after:render'`
+ * - `'selection:created'`, `'selection:updated'`, `'selection:cleared'`
+ */
+export type CanvasEventHandlers = {
+    [K in keyof CanvasEvents]?: (event: CanvasEvents[K]) => void;
+};
+/**
+ * Subscribe to Fabric canvas events with automatic cleanup.
+ *
+ * Handlers are stored in a ref so they always call the latest version without
+ * re-subscribing. The hook subscribes once when the canvas becomes available
+ * (child `<Canvas>` effects fire before parent effects) and cleans up on unmount.
+ *
+ * @example
+ * ```tsx
+ * useCanvasEvents(editor.canvasRef, {
+ *   'object:added': (e) => updateList(),
+ *   'object:modified': () => setDirty(true),
+ *   'object:removed': () => updateList(),
+ * });
+ * ```
+ */
+export declare function useCanvasEvents(canvasRef: RefObject<FabricCanvas | null>, events: CanvasEventHandlers): void;
+//# sourceMappingURL=useCanvasEvents.d.ts.map

package/dist/hooks/useCanvasEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCanvasEvents.d.ts","sourceRoot":"","sources":["../../src/hooks/useCanvasEvents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,IAAI,YAAY,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEnE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAAG;KAC/B,CAAC,IAAI,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI;CAC7D,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,EACzC,MAAM,EAAE,mBAAmB,GAC1B,IAAI,CA8BN"}

package/dist/hooks/useCanvasTooltip.d.ts

@@ -0,0 +1,45 @@
+import { type RefObject } from 'react';
+import type { Canvas as FabricCanvas, FabricObject } from 'fabric';
+export interface UseCanvasTooltipOptions<T> {
+    /** Extract tooltip content from a hovered object. Return `null` to skip the tooltip. */
+    getContent: (obj: FabricObject) => T | null;
+}
+export interface CanvasTooltipState<T> {
+    /** Whether the tooltip is currently visible. */
+    visible: boolean;
+    /** The content extracted from the hovered object, or `null` when hidden. */
+    content: T | null;
+    /** Screen-space position (relative to the canvas container) for the tooltip. */
+    position: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Track mouse hover over canvas objects and return tooltip state.
+ *
+ * Listens to `mouse:over`, `mouse:out`, `after:render`, and `mouse:wheel` to
+ * maintain a reactive tooltip state. The returned position is in screen-space
+ * coordinates relative to the canvas container element — suitable for absolute
+ * positioning of a tooltip component.
+ *
+ * @example
+ * ```tsx
+ * const tooltip = useCanvasTooltip(view.canvasRef, {
+ *   getContent: (obj) => obj.data ? { id: obj.data.id, type: obj.data.type } : null,
+ * });
+ *
+ * return (
+ *   <>
+ *     <Canvas onReady={view.onReady} />
+ *     {tooltip.visible && (
+ *       <div style={{ position: 'absolute', left: tooltip.position.x, top: tooltip.position.y }}>
+ *         {tooltip.content?.id}
+ *       </div>
+ *     )}
+ *   </>
+ * );
+ * ```
+ */
+export declare function useCanvasTooltip<T>(canvasRef: RefObject<FabricCanvas | null>, options: UseCanvasTooltipOptions<T>): CanvasTooltipState<T>;
+//# sourceMappingURL=useCanvasTooltip.d.ts.map

package/dist/hooks/useCanvasTooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCanvasTooltip.d.ts","sourceRoot":"","sources":["../../src/hooks/useCanvasTooltip.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,KAAK,EACV,MAAM,IAAI,YAAY,EAEtB,YAAY,EACb,MAAM,QAAQ,CAAC;AAEhB,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,wFAAwF;IACxF,UAAU,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IAClB,gFAAgF;IAChF,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,SAAS,EAAE,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,EACzC,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAClC,kBAAkB,CAAC,CAAC,CAAC,CA0EvB"}

package/dist/hooks/useEditCanvas.d.ts

@@ -53,6 +53,12 @@ export interface UseEditCanvasOptions {
      * Pass `false` to disable. Default: enabled (maxSize: 4096, minSize: 480).
      */
     backgroundResize?: boolean | ResizeImageOptions;
+    /**
+     * Track object add/remove/modify events and expose an `isDirty` flag.
+     * Call `resetDirty()` after a successful save to clear the flag.
+     * Default: disabled.
+     */
+    trackChanges?: boolean;
 }
 /**
  * Hook that provides a batteries-included canvas experience with full
@@ -97,6 +103,8 @@ export declare function useEditCanvas(options?: UseEditCanvasOptions): {
         zoomIn: (step?: number) => void;
         /** Zoom out from the canvas center. Default step: 0.2. */
         zoomOut: (step?: number) => void;
+        /** Pan the viewport to center on a specific object. */
+        panToObject: (object: FabricObject, panOpts?: import("../viewport").PanToObjectOptions) => void;
     };
     /** Whether vertex edit mode is currently active (reactive). */
     isEditingVertices: boolean;
@@ -120,7 +128,16 @@ export declare function useEditCanvas(options?: UseEditCanvasOptions): {
      * Set a background image from a URL. Automatically resizes if the image
      * exceeds the configured limits (opt out via `backgroundResize: false`),
      * and fits the viewport after setting if `autoFitToBackground` is enabled.
+     *
+     * Pass `{ preserveOpacity: true }` to keep the current background opacity
+     * when replacing the image.
      */
-    setBackground: (url: string) => Promise<import("fabric").FabricImage<Partial<import("fabric").ImageProps>, import("fabric").SerializedImageProps, import("fabric").ObjectEvents>>;
+    setBackground: (url: string, bgOpts?: {
+        preserveOpacity?: boolean;
+    }) => Promise<import("fabric").FabricImage<Partial<import("fabric").ImageProps>, import("fabric").SerializedImageProps, import("fabric").ObjectEvents>>;
+    /** Whether the canvas has been modified since the last `resetDirty()` call. Requires `trackChanges: true`. */
+    isDirty: boolean;
+    /** Reset the dirty flag (e.g., after a successful save). */
+    resetDirty: () => void;
 };
 //# sourceMappingURL=useEditCanvas.d.ts.map

package/dist/hooks/useEditCanvas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useEditCanvas.d.ts","sourceRoot":"","sources":["../../src/hooks/useEditCanvas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,KAAK,YAAY,EAAW,MAAM,QAAQ,CAAC;AAC5E,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAMrB,OAAO,EAEL,KAAK,sBAAsB,EAE3B,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,UAAU,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACzC,mIAAmI;IACnI,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAC;IAC7C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACzC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB;IA0NxD,8CAA8C;sBAlKrC,YAAY;IAoKrB,oDAAoD;;IAEpD,qCAAqC;;IAErC,6CAA6C;;IAE7C,yBAAyB;;QAEvB,wCAAwC;;QAExC,wDAAwD;wBA9CjB,YAAY;QAgDnD,wFAAwF;;QAExF,2DAA2D;;QAE3D,0DAA0D;;;IAG5D,+DAA+D;;IAE/D;;;;;;;;;;;;;;OAcG;qBAvO+B,SAAS,GAAG,IAAI;IAyOlD;;;;OAIG;yBAlEyC,MAAM;EAqErD"}
+{"version":3,"file":"useEditCanvas.d.ts","sourceRoot":"","sources":["../../src/hooks/useEditCanvas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,KAAK,YAAY,EAAW,MAAM,QAAQ,CAAC;AAC5E,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAMrB,OAAO,EAEL,KAAK,sBAAsB,EAE3B,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,UAAU,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACzC,mIAAmI;IACnI,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAC;IAC7C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACzC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAAC;IAChD;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB;IAuOxD,8CAA8C;sBA9KrC,YAAY;IAgLrB,oDAAoD;;IAEpD,qCAAqC;;IAErC,6CAA6C;;IAE7C,yBAAyB;;QAEvB,wCAAwC;;QAExC,wDAAwD;wBAnDjB,YAAY;QAqDnD,wFAAwF;;QAExF,2DAA2D;;QAE3D,0DAA0D;;QAE1D,uDAAuD;;;IAGzD,+DAA+D;;IAE/D;;;;;;;;;;;;;;OAcG;qBArP+B,SAAS,GAAG,IAAI;IAuPlD;;;;;;;OAOG;yBA3ES,MAAM,WAAW;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE;IA6E1D,8GAA8G;;IAE9G,4DAA4D;;EAG/D"}

package/dist/hooks/useObjectOverlay.d.ts

@@ -0,0 +1,49 @@
+import { type RefObject } from 'react';
+import type { Canvas as FabricCanvas, FabricObject } from 'fabric';
+export interface UseObjectOverlayOptions {
+    /**
+     * Automatically scale the overlay content so it fits within the object
+     * bounds at the current zoom level.
+     * Default: false.
+     */
+    autoScaleContent?: boolean;
+    /**
+     * CSS selector for a text element inside the overlay. When
+     * `autoScaleContent` is enabled and the computed scale drops below a
+     * threshold, elements matching this selector are hidden (via
+     * `display: none`) so only icons remain visible.
+     * Default: undefined (no text hiding).
+     */
+    textSelector?: string;
+    /**
+     * Minimum content scale at which `textSelector` elements remain visible.
+     * Below this threshold, matched elements are hidden.
+     * Default: 0.5.
+     */
+    textMinScale?: number;
+}
+/**
+ * Position a DOM element over a Fabric canvas object, kept in sync with
+ * pan, zoom, move, scale, and rotate transforms.
+ *
+ * Returns a ref to attach to the overlay container element. The element
+ * must be positioned absolutely within a relative-positioned parent that
+ * wraps the `<Canvas>` component.
+ *
+ * @example
+ * ```tsx
+ * const overlayRef = useObjectOverlay(canvasRef, object, {
+ *   autoScaleContent: true,
+ *   textSelector: '.desk-text',
+ * });
+ *
+ * return (
+ *   <div ref={overlayRef} style={{ position: 'absolute', pointerEvents: 'none' }}>
+ *     <CanvasDeskIcon />
+ *     <span className="desk-text">{name}</span>
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useObjectOverlay(canvasRef: RefObject<FabricCanvas | null>, object: FabricObject | null | undefined, options?: UseObjectOverlayOptions): RefObject<HTMLDivElement | null>;
+//# sourceMappingURL=useObjectOverlay.d.ts.map

package/dist/hooks/useObjectOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useObjectOverlay.d.ts","sourceRoot":"","sources":["../../src/hooks/useObjectOverlay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,IAAI,YAAY,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGnE,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,EACzC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACvC,OAAO,CAAC,EAAE,uBAAuB,GAChC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAuElC"}

package/dist/hooks/useViewCanvas.d.ts

@@ -1,4 +1,4 @@
-import { Canvas as FabricCanvas } from 'fabric';
+import { Canvas as FabricCanvas, type FabricObject } from 'fabric';
 import { type PanAndZoomOptions } from '../viewport';
 /** Visual properties that can be updated on view-canvas objects. */
 export interface ViewObjectStyle {
@@ -55,6 +55,8 @@ export declare function useViewCanvas(options?: UseViewCanvasOptions): {
         zoomIn: (step?: number) => void;
         /** Zoom out from the canvas center. Default step: 0.2. */
         zoomOut: (step?: number) => void;
+        /** Pan the viewport to center on a specific object. */
+        panToObject: (object: FabricObject, panOpts?: import("../viewport").PanToObjectOptions) => void;
     };
     /** Update a single object's visual style by its `data.id`. */
     setObjectStyle: (id: string, style: ViewObjectStyle) => void;

package/dist/hooks/useViewCanvas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useViewCanvas.d.ts","sourceRoot":"","sources":["../../src/hooks/useViewCanvas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,IAAI,YAAY,EAA2B,MAAM,QAAQ,CAAC;AACzE,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,aAAa,CAAC;AAKrB,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,UAAU,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACzC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAuBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB;IAgHxD,8CAA8C;sBAzGrC,YAAY;IA2GrB,oDAAoD;;IAEpD,qCAAqC;;IAErC,yBAAyB;;QAEvB,wFAAwF;;QAExF,2DAA2D;;QAE3D,0DAA0D;;;IAG5D,8DAA8D;yBA/DxB,MAAM,SAAS,eAAe;IAiEpE,sFAAsF;8BAxD7E,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IA0DxC,qEAAqE;iCAnC9D,MAAM,SAAS,eAAe;EAsCxC"}
+{"version":3,"file":"useViewCanvas.d.ts","sourceRoot":"","sources":["../../src/hooks/useViewCanvas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,KAAK,YAAY,EAAQ,MAAM,QAAQ,CAAC;AACzE,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,aAAa,CAAC;AAKrB,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,UAAU,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACzC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAuBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB;IAgHxD,8CAA8C;sBAzGrC,YAAY;IA2GrB,oDAAoD;;IAEpD,qCAAqC;;IAErC,yBAAyB;;QAEvB,wFAAwF;;QAExF,2DAA2D;;QAE3D,0DAA0D;;QAE1D,uDAAuD;;;IAGzD,8DAA8D;yBAjExB,MAAM,SAAS,eAAe;IAmEpE,sFAAsF;8BA1D7E,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IA4DxC,qEAAqE;iCArC9D,MAAM,SAAS,eAAe;EAwCxC"}