@fieldnotes/react 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,171 @@
+# @fieldnotes/react
+
+React bindings for the [Field Notes](https://github.com/IrakliDevelop/fieldnotes) infinite canvas SDK. Embed React components directly onto an infinite, pannable, zoomable canvas.
+
+## Install
+
+```bash
+npm install @fieldnotes/core @fieldnotes/react
+```
+
+Requires React 18+.
+
+## Quick Start
+
+```tsx
+import { FieldNotesCanvas } from '@fieldnotes/react';
+import { HandTool, SelectTool, PencilTool } from '@fieldnotes/core';
+
+function App() {
+  return (
+    <FieldNotesCanvas
+      tools={[new HandTool(), new SelectTool(), new PencilTool()]}
+      defaultTool="select"
+      style={{ width: '100vw', height: '100vh' }}
+    />
+  );
+}
+```
+
+Your container needs a defined size — the canvas fills it.
+
+## Embedding React Components
+
+The main feature — render any React component as a canvas element that pans, zooms, and resizes with the canvas:
+
+```tsx
+import { FieldNotesCanvas, CanvasElement } from '@fieldnotes/react';
+import { SelectTool } from '@fieldnotes/core';
+
+function App() {
+  return (
+    <FieldNotesCanvas
+      tools={[new SelectTool()]}
+      defaultTool="select"
+      style={{ width: '100vw', height: '100vh' }}
+    >
+      <CanvasElement position={{ x: 100, y: 200 }} size={{ w: 300, h: 200 }}>
+        <MyCard />
+      </CanvasElement>
+
+      <CanvasElement position={{ x: 500, y: 100 }}>
+        <button onClick={() => console.log('clicked!')}>Interactive button on the canvas</button>
+      </CanvasElement>
+    </FieldNotesCanvas>
+  );
+}
+```
+
+Embedded React components are fully interactive — clicks, inputs, forms all work normally.
+
+## Hooks
+
+### `useViewport()`
+
+Access the core `Viewport` instance for imperative operations:
+
+```tsx
+import { useViewport } from '@fieldnotes/react';
+
+function Toolbar() {
+  const viewport = useViewport();
+
+  return <button onClick={() => viewport.undo()}>Undo</button>;
+}
+```
+
+Must be used inside `<FieldNotesCanvas>`.
+
+### `useActiveTool()`
+
+Reactive current tool name — re-renders when the tool changes:
+
+```tsx
+import { useActiveTool, useViewport } from '@fieldnotes/react';
+
+function ToolIndicator() {
+  const tool = useActiveTool();
+  const viewport = useViewport();
+
+  return (
+    <div>
+      <span>Current: {tool}</span>
+      <button onClick={() => viewport.toolManager.setTool('pencil', viewport.toolContext)}>
+        Pencil
+      </button>
+    </div>
+  );
+}
+```
+
+### `useCamera()`
+
+Reactive camera state (position + zoom) — re-renders on pan/zoom:
+
+```tsx
+import { useCamera } from '@fieldnotes/react';
+
+function CameraInfo() {
+  const { x, y, zoom } = useCamera();
+
+  return (
+    <span>
+      {zoom.toFixed(2)}x at ({x.toFixed(0)}, {y.toFixed(0)})
+    </span>
+  );
+}
+```
+
+## Component API
+
+### `<FieldNotesCanvas>`
+
+| Prop          | Type                           | Description                             |
+| ------------- | ------------------------------ | --------------------------------------- |
+| `options`     | `ViewportOptions`              | Camera and background config            |
+| `tools`       | `Tool[]`                       | Tools to register on mount              |
+| `defaultTool` | `string`                       | Tool to activate on mount               |
+| `className`   | `string`                       | CSS class for the container div         |
+| `style`       | `CSSProperties`                | Inline styles for the container div     |
+| `onReady`     | `(viewport: Viewport) => void` | Called after Viewport is created        |
+| `children`    | `ReactNode`                    | Child components (have access to hooks) |
+| `ref`         | `Ref<FieldNotesCanvasRef>`     | Exposes `{ viewport }`                  |
+
+### `<CanvasElement>`
+
+| Prop       | Type                       | Default              | Description                        |
+| ---------- | -------------------------- | -------------------- | ---------------------------------- |
+| `position` | `{ x: number; y: number }` | required             | World-space position               |
+| `size`     | `{ w: number; h: number }` | `{ w: 200, h: 150 }` | Element size in world-space pixels |
+| `children` | `ReactNode`                | required             | React content to render on canvas  |
+
+Position and size updates are reactive — change the props and the element moves/resizes on the canvas.
+
+## Accessing the Viewport Directly
+
+For advanced use cases, use a ref:
+
+```tsx
+import { useRef } from 'react';
+import { FieldNotesCanvas, type FieldNotesCanvasRef } from '@fieldnotes/react';
+
+function App() {
+  const canvasRef = useRef<FieldNotesCanvasRef>(null);
+
+  const exportState = () => {
+    const json = canvasRef.current?.viewport?.exportJSON();
+    console.log(json);
+  };
+
+  return (
+    <>
+      <FieldNotesCanvas ref={canvasRef} style={{ width: '100vw', height: '100vh' }} />
+      <button onClick={exportState}>Export</button>
+    </>
+  );
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -20,12 +20,144 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  VERSION: () => VERSION
+  CanvasElement: () => CanvasElement,
+  FieldNotesCanvas: () => FieldNotesCanvas,
+  ViewportContext: () => ViewportContext,
+  useActiveTool: () => useActiveTool,
+  useCamera: () => useCamera,
+  useViewport: () => useViewport
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "0.1.0";
+
+// src/field-notes-canvas.tsx
+var import_react2 = require("react");
+var import_core = require("@fieldnotes/core");
+
+// src/context.ts
+var import_react = require("react");
+var ViewportContext = (0, import_react.createContext)(null);
+
+// src/field-notes-canvas.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var FieldNotesCanvas = (0, import_react2.forwardRef)(
+  function FieldNotesCanvas2({ options, tools, defaultTool, className, style, children, onReady }, ref) {
+    const containerRef = (0, import_react2.useRef)(null);
+    const [viewport, setViewport] = (0, import_react2.useState)(null);
+    (0, import_react2.useImperativeHandle)(ref, () => ({ viewport }), [viewport]);
+    (0, import_react2.useEffect)(() => {
+      const el = containerRef.current;
+      if (!el) return;
+      const vp = new import_core.Viewport(el, options);
+      if (tools) {
+        for (const tool of tools) {
+          vp.toolManager.register(tool);
+        }
+      }
+      if (defaultTool) {
+        vp.toolManager.setTool(defaultTool, vp.toolContext);
+      }
+      setViewport(vp);
+      onReady?.(vp);
+      return () => {
+        vp.destroy();
+        setViewport(null);
+      };
+    }, []);
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { ref: containerRef, className, style, children: viewport && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ViewportContext.Provider, { value: viewport, children }) });
+  }
+);
+
+// src/canvas-element.tsx
+var import_react4 = require("react");
+var import_react_dom = require("react-dom");
+
+// src/use-viewport.ts
+var import_react3 = require("react");
+function useViewport() {
+  const viewport = (0, import_react3.useContext)(ViewportContext);
+  if (!viewport) {
+    throw new Error("useViewport must be used inside <FieldNotesCanvas>");
+  }
+  return viewport;
+}
+
+// src/canvas-element.tsx
+function CanvasElement({ position, size, children }) {
+  const viewport = useViewport();
+  const [portalTarget, setPortalTarget] = (0, import_react4.useState)(null);
+  const elementIdRef = (0, import_react4.useRef)(null);
+  (0, import_react4.useEffect)(() => {
+    const container = document.createElement("div");
+    Object.assign(container.style, {
+      width: "100%",
+      height: "100%"
+    });
+    viewport.domLayer.appendChild(container);
+    const id = viewport.addHtmlElement(container, position, size);
+    elementIdRef.current = id;
+    setPortalTarget(container);
+    return () => {
+      if (elementIdRef.current) {
+        viewport.store.remove(elementIdRef.current);
+        viewport.requestRender();
+        elementIdRef.current = null;
+      }
+      setPortalTarget(null);
+    };
+  }, [viewport]);
+  (0, import_react4.useEffect)(() => {
+    const id = elementIdRef.current;
+    if (!id) return;
+    viewport.store.update(id, { position });
+    if (size) {
+      viewport.store.update(id, { size });
+    }
+    viewport.requestRender();
+  }, [viewport, position.x, position.y, size?.w, size?.h]);
+  if (!portalTarget) return null;
+  return (0, import_react_dom.createPortal)(children, portalTarget);
+}
+
+// src/use-active-tool.ts
+var import_react5 = require("react");
+function useActiveTool() {
+  const viewport = useViewport();
+  const subscribe = (0, import_react5.useCallback)(
+    (onStoreChange) => viewport.toolManager.onChange(() => onStoreChange()),
+    [viewport]
+  );
+  const getSnapshot = (0, import_react5.useCallback)(() => viewport.toolManager.activeTool?.name ?? "", [viewport]);
+  return (0, import_react5.useSyncExternalStore)(subscribe, getSnapshot);
+}
+
+// src/use-camera.ts
+var import_react6 = require("react");
+function useCamera() {
+  const viewport = useViewport();
+  const cachedRef = (0, import_react6.useRef)({ x: 0, y: 0, zoom: 1 });
+  const subscribe = (0, import_react6.useCallback)(
+    (onStoreChange) => viewport.camera.onChange(onStoreChange),
+    [viewport]
+  );
+  const getSnapshot = (0, import_react6.useCallback)(() => {
+    const { position, zoom } = viewport.camera;
+    const cached = cachedRef.current;
+    if (cached.x === position.x && cached.y === position.y && cached.zoom === zoom) {
+      return cached;
+    }
+    const next = { x: position.x, y: position.y, zoom };
+    cachedRef.current = next;
+    return next;
+  }, [viewport]);
+  return (0, import_react6.useSyncExternalStore)(subscribe, getSnapshot);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  VERSION
+  CanvasElement,
+  FieldNotesCanvas,
+  ViewportContext,
+  useActiveTool,
+  useCamera,
+  useViewport
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const VERSION = '0.1.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,UAAU;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/field-notes-canvas.tsx","../src/context.ts","../src/canvas-element.tsx","../src/use-viewport.ts","../src/use-active-tool.ts","../src/use-camera.ts"],"sourcesContent":["export { FieldNotesCanvas } from './field-notes-canvas';\r\nexport type { FieldNotesCanvasProps, FieldNotesCanvasRef } from './field-notes-canvas';\r\nexport { CanvasElement } from './canvas-element';\r\nexport type { CanvasElementProps } from './canvas-element';\r\nexport { useViewport } from './use-viewport';\r\nexport { useActiveTool } from './use-active-tool';\r\nexport { useCamera } from './use-camera';\r\nexport type { CameraState } from './use-camera';\r\nexport { ViewportContext } from './context';\r\n","import {\r\n  useRef,\r\n  useEffect,\r\n  useState,\r\n  forwardRef,\r\n  useImperativeHandle,\r\n  type ReactNode,\r\n  type CSSProperties,\r\n} from 'react';\r\nimport { Viewport } from '@fieldnotes/core';\r\nimport type { ViewportOptions, Tool } from '@fieldnotes/core';\r\nimport { ViewportContext } from './context';\r\n\r\nexport interface FieldNotesCanvasProps {\r\n  options?: ViewportOptions;\r\n  tools?: Tool[];\r\n  defaultTool?: string;\r\n  className?: string;\r\n  style?: CSSProperties;\r\n  children?: ReactNode;\r\n  onReady?: (viewport: Viewport) => void;\r\n}\r\n\r\nexport interface FieldNotesCanvasRef {\r\n  viewport: Viewport | null;\r\n}\r\n\r\nexport const FieldNotesCanvas = forwardRef<FieldNotesCanvasRef, FieldNotesCanvasProps>(\r\n  function FieldNotesCanvas(\r\n    { options, tools, defaultTool, className, style, children, onReady },\r\n    ref,\r\n  ) {\r\n    const containerRef = useRef<HTMLDivElement>(null);\r\n    const [viewport, setViewport] = useState<Viewport | null>(null);\r\n\r\n    useImperativeHandle(ref, () => ({ viewport }), [viewport]);\r\n\r\n    useEffect(() => {\r\n      const el = containerRef.current;\r\n      if (!el) return;\r\n\r\n      const vp = new Viewport(el, options);\r\n\r\n      if (tools) {\r\n        for (const tool of tools) {\r\n          vp.toolManager.register(tool);\r\n        }\r\n      }\r\n\r\n      if (defaultTool) {\r\n        vp.toolManager.setTool(defaultTool, vp.toolContext);\r\n      }\r\n\r\n      setViewport(vp);\r\n      onReady?.(vp);\r\n\r\n      return () => {\r\n        vp.destroy();\r\n        setViewport(null);\r\n      };\r\n    }, []);\r\n\r\n    return (\r\n      <div ref={containerRef} className={className} style={style}>\r\n        {viewport && (\r\n          <ViewportContext.Provider value={viewport}>{children}</ViewportContext.Provider>\r\n        )}\r\n      </div>\r\n    );\r\n  },\r\n);\r\n","import { createContext } from 'react';\r\nimport type { Viewport } from '@fieldnotes/core';\r\n\r\nexport const ViewportContext = createContext<Viewport | null>(null);\r\n","import { useEffect, useRef, useState, type ReactNode } from 'react';\r\nimport { createPortal } from 'react-dom';\r\nimport { useViewport } from './use-viewport';\r\n\r\nexport interface CanvasElementProps {\r\n  position: { x: number; y: number };\r\n  size?: { w: number; h: number };\r\n  children: ReactNode;\r\n}\r\n\r\nexport function CanvasElement({ position, size, children }: CanvasElementProps) {\r\n  const viewport = useViewport();\r\n  const [portalTarget, setPortalTarget] = useState<HTMLElement | null>(null);\r\n  const elementIdRef = useRef<string | null>(null);\r\n\r\n  useEffect(() => {\r\n    const container = document.createElement('div');\r\n    Object.assign(container.style, {\r\n      width: '100%',\r\n      height: '100%',\r\n    });\r\n\r\n    // Append to domLayer immediately so portal children are queryable in the document\r\n    // before the viewport render loop fires via requestAnimationFrame.\r\n    viewport.domLayer.appendChild(container);\r\n\r\n    const id = viewport.addHtmlElement(container, position, size);\r\n    elementIdRef.current = id;\r\n    setPortalTarget(container);\r\n\r\n    return () => {\r\n      if (elementIdRef.current) {\r\n        viewport.store.remove(elementIdRef.current);\r\n        viewport.requestRender();\r\n        elementIdRef.current = null;\r\n      }\r\n      setPortalTarget(null);\r\n    };\r\n  }, [viewport]);\r\n\r\n  useEffect(() => {\r\n    const id = elementIdRef.current;\r\n    if (!id) return;\r\n    viewport.store.update(id, { position });\r\n    if (size) {\r\n      viewport.store.update(id, { size });\r\n    }\r\n    viewport.requestRender();\r\n  }, [viewport, position.x, position.y, size?.w, size?.h]);\r\n\r\n  if (!portalTarget) return null;\r\n  return createPortal(children, portalTarget);\r\n}\r\n","import { useContext } from 'react';\r\nimport type { Viewport } from '@fieldnotes/core';\r\nimport { ViewportContext } from './context';\r\n\r\nexport function useViewport(): Viewport {\r\n  const viewport = useContext(ViewportContext);\r\n  if (!viewport) {\r\n    throw new Error('useViewport must be used inside <FieldNotesCanvas>');\r\n  }\r\n  return viewport;\r\n}\r\n","import { useCallback, useSyncExternalStore } from 'react';\r\nimport { useViewport } from './use-viewport';\r\n\r\nexport function useActiveTool(): string {\r\n  const viewport = useViewport();\r\n\r\n  const subscribe = useCallback(\r\n    (onStoreChange: () => void) => viewport.toolManager.onChange(() => onStoreChange()),\r\n    [viewport],\r\n  );\r\n\r\n  const getSnapshot = useCallback(() => viewport.toolManager.activeTool?.name ?? '', [viewport]);\r\n\r\n  return useSyncExternalStore(subscribe, getSnapshot);\r\n}\r\n","import { useCallback, useRef, useSyncExternalStore } from 'react';\r\nimport { useViewport } from './use-viewport';\r\n\r\nexport interface CameraState {\r\n  x: number;\r\n  y: number;\r\n  zoom: number;\r\n}\r\n\r\nexport function useCamera(): CameraState {\r\n  const viewport = useViewport();\r\n  const cachedRef = useRef<CameraState>({ x: 0, y: 0, zoom: 1 });\r\n\r\n  const subscribe = useCallback(\r\n    (onStoreChange: () => void) => viewport.camera.onChange(onStoreChange),\r\n    [viewport],\r\n  );\r\n\r\n  const getSnapshot = useCallback((): CameraState => {\r\n    const { position, zoom } = viewport.camera;\r\n    const cached = cachedRef.current;\r\n    if (cached.x === position.x && cached.y === position.y && cached.zoom === zoom) {\r\n      return cached;\r\n    }\r\n    const next = { x: position.x, y: position.y, zoom };\r\n    cachedRef.current = next;\r\n    return next;\r\n  }, [viewport]);\r\n\r\n  return useSyncExternalStore(subscribe, getSnapshot);\r\n}\r\n"],"mappings":"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","names":["import_react","FieldNotesCanvas","import_react","import_react","import_react","import_react"]}

package/dist/index.d.cts

@@ -1,3 +1,45 @@
-declare const VERSION = "0.1.0";
+import * as react from 'react';
+import { CSSProperties, ReactNode } from 'react';
+import { ViewportOptions, Tool, Viewport } from '@fieldnotes/core';
 
-export { VERSION };
+interface FieldNotesCanvasProps {
+    options?: ViewportOptions;
+    tools?: Tool[];
+    defaultTool?: string;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+    onReady?: (viewport: Viewport) => void;
+}
+interface FieldNotesCanvasRef {
+    viewport: Viewport | null;
+}
+declare const FieldNotesCanvas: react.ForwardRefExoticComponent<FieldNotesCanvasProps & react.RefAttributes<FieldNotesCanvasRef>>;
+
+interface CanvasElementProps {
+    position: {
+        x: number;
+        y: number;
+    };
+    size?: {
+        w: number;
+        h: number;
+    };
+    children: ReactNode;
+}
+declare function CanvasElement({ position, size, children }: CanvasElementProps): react.ReactPortal | null;
+
+declare function useViewport(): Viewport;
+
+declare function useActiveTool(): string;
+
+interface CameraState {
+    x: number;
+    y: number;
+    zoom: number;
+}
+declare function useCamera(): CameraState;
+
+declare const ViewportContext: react.Context<Viewport | null>;
+
+export { type CameraState, CanvasElement, type CanvasElementProps, FieldNotesCanvas, type FieldNotesCanvasProps, type FieldNotesCanvasRef, ViewportContext, useActiveTool, useCamera, useViewport };

package/dist/index.d.ts

@@ -1,3 +1,45 @@
-declare const VERSION = "0.1.0";
+import * as react from 'react';
+import { CSSProperties, ReactNode } from 'react';
+import { ViewportOptions, Tool, Viewport } from '@fieldnotes/core';
 
-export { VERSION };
+interface FieldNotesCanvasProps {
+    options?: ViewportOptions;
+    tools?: Tool[];
+    defaultTool?: string;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+    onReady?: (viewport: Viewport) => void;
+}
+interface FieldNotesCanvasRef {
+    viewport: Viewport | null;
+}
+declare const FieldNotesCanvas: react.ForwardRefExoticComponent<FieldNotesCanvasProps & react.RefAttributes<FieldNotesCanvasRef>>;
+
+interface CanvasElementProps {
+    position: {
+        x: number;
+        y: number;
+    };
+    size?: {
+        w: number;
+        h: number;
+    };
+    children: ReactNode;
+}
+declare function CanvasElement({ position, size, children }: CanvasElementProps): react.ReactPortal | null;
+
+declare function useViewport(): Viewport;
+
+declare function useActiveTool(): string;
+
+interface CameraState {
+    x: number;
+    y: number;
+    zoom: number;
+}
+declare function useCamera(): CameraState;
+
+declare const ViewportContext: react.Context<Viewport | null>;
+
+export { type CameraState, CanvasElement, type CanvasElementProps, FieldNotesCanvas, type FieldNotesCanvasProps, type FieldNotesCanvasRef, ViewportContext, useActiveTool, useCamera, useViewport };

package/dist/index.js

@@ -1,6 +1,137 @@
-// src/index.ts
-var VERSION = "0.1.0";
+// src/field-notes-canvas.tsx
+import {
+  useRef,
+  useEffect,
+  useState,
+  forwardRef,
+  useImperativeHandle
+} from "react";
+import { Viewport } from "@fieldnotes/core";
+
+// src/context.ts
+import { createContext } from "react";
+var ViewportContext = createContext(null);
+
+// src/field-notes-canvas.tsx
+import { jsx } from "react/jsx-runtime";
+var FieldNotesCanvas = forwardRef(
+  function FieldNotesCanvas2({ options, tools, defaultTool, className, style, children, onReady }, ref) {
+    const containerRef = useRef(null);
+    const [viewport, setViewport] = useState(null);
+    useImperativeHandle(ref, () => ({ viewport }), [viewport]);
+    useEffect(() => {
+      const el = containerRef.current;
+      if (!el) return;
+      const vp = new Viewport(el, options);
+      if (tools) {
+        for (const tool of tools) {
+          vp.toolManager.register(tool);
+        }
+      }
+      if (defaultTool) {
+        vp.toolManager.setTool(defaultTool, vp.toolContext);
+      }
+      setViewport(vp);
+      onReady?.(vp);
+      return () => {
+        vp.destroy();
+        setViewport(null);
+      };
+    }, []);
+    return /* @__PURE__ */ jsx("div", { ref: containerRef, className, style, children: viewport && /* @__PURE__ */ jsx(ViewportContext.Provider, { value: viewport, children }) });
+  }
+);
+
+// src/canvas-element.tsx
+import { useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
+import { createPortal } from "react-dom";
+
+// src/use-viewport.ts
+import { useContext } from "react";
+function useViewport() {
+  const viewport = useContext(ViewportContext);
+  if (!viewport) {
+    throw new Error("useViewport must be used inside <FieldNotesCanvas>");
+  }
+  return viewport;
+}
+
+// src/canvas-element.tsx
+function CanvasElement({ position, size, children }) {
+  const viewport = useViewport();
+  const [portalTarget, setPortalTarget] = useState2(null);
+  const elementIdRef = useRef2(null);
+  useEffect2(() => {
+    const container = document.createElement("div");
+    Object.assign(container.style, {
+      width: "100%",
+      height: "100%"
+    });
+    viewport.domLayer.appendChild(container);
+    const id = viewport.addHtmlElement(container, position, size);
+    elementIdRef.current = id;
+    setPortalTarget(container);
+    return () => {
+      if (elementIdRef.current) {
+        viewport.store.remove(elementIdRef.current);
+        viewport.requestRender();
+        elementIdRef.current = null;
+      }
+      setPortalTarget(null);
+    };
+  }, [viewport]);
+  useEffect2(() => {
+    const id = elementIdRef.current;
+    if (!id) return;
+    viewport.store.update(id, { position });
+    if (size) {
+      viewport.store.update(id, { size });
+    }
+    viewport.requestRender();
+  }, [viewport, position.x, position.y, size?.w, size?.h]);
+  if (!portalTarget) return null;
+  return createPortal(children, portalTarget);
+}
+
+// src/use-active-tool.ts
+import { useCallback, useSyncExternalStore } from "react";
+function useActiveTool() {
+  const viewport = useViewport();
+  const subscribe = useCallback(
+    (onStoreChange) => viewport.toolManager.onChange(() => onStoreChange()),
+    [viewport]
+  );
+  const getSnapshot = useCallback(() => viewport.toolManager.activeTool?.name ?? "", [viewport]);
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+
+// src/use-camera.ts
+import { useCallback as useCallback2, useRef as useRef3, useSyncExternalStore as useSyncExternalStore2 } from "react";
+function useCamera() {
+  const viewport = useViewport();
+  const cachedRef = useRef3({ x: 0, y: 0, zoom: 1 });
+  const subscribe = useCallback2(
+    (onStoreChange) => viewport.camera.onChange(onStoreChange),
+    [viewport]
+  );
+  const getSnapshot = useCallback2(() => {
+    const { position, zoom } = viewport.camera;
+    const cached = cachedRef.current;
+    if (cached.x === position.x && cached.y === position.y && cached.zoom === zoom) {
+      return cached;
+    }
+    const next = { x: position.x, y: position.y, zoom };
+    cachedRef.current = next;
+    return next;
+  }, [viewport]);
+  return useSyncExternalStore2(subscribe, getSnapshot);
+}
 export {
-  VERSION
+  CanvasElement,
+  FieldNotesCanvas,
+  ViewportContext,
+  useActiveTool,
+  useCamera,
+  useViewport
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const VERSION = '0.1.0';\n"],"mappings":";AAAO,IAAM,UAAU;","names":[]}
+{"version":3,"sources":["../src/field-notes-canvas.tsx","../src/context.ts","../src/canvas-element.tsx","../src/use-viewport.ts","../src/use-active-tool.ts","../src/use-camera.ts"],"sourcesContent":["import {\r\n  useRef,\r\n  useEffect,\r\n  useState,\r\n  forwardRef,\r\n  useImperativeHandle,\r\n  type ReactNode,\r\n  type CSSProperties,\r\n} from 'react';\r\nimport { Viewport } from '@fieldnotes/core';\r\nimport type { ViewportOptions, Tool } from '@fieldnotes/core';\r\nimport { ViewportContext } from './context';\r\n\r\nexport interface FieldNotesCanvasProps {\r\n  options?: ViewportOptions;\r\n  tools?: Tool[];\r\n  defaultTool?: string;\r\n  className?: string;\r\n  style?: CSSProperties;\r\n  children?: ReactNode;\r\n  onReady?: (viewport: Viewport) => void;\r\n}\r\n\r\nexport interface FieldNotesCanvasRef {\r\n  viewport: Viewport | null;\r\n}\r\n\r\nexport const FieldNotesCanvas = forwardRef<FieldNotesCanvasRef, FieldNotesCanvasProps>(\r\n  function FieldNotesCanvas(\r\n    { options, tools, defaultTool, className, style, children, onReady },\r\n    ref,\r\n  ) {\r\n    const containerRef = useRef<HTMLDivElement>(null);\r\n    const [viewport, setViewport] = useState<Viewport | null>(null);\r\n\r\n    useImperativeHandle(ref, () => ({ viewport }), [viewport]);\r\n\r\n    useEffect(() => {\r\n      const el = containerRef.current;\r\n      if (!el) return;\r\n\r\n      const vp = new Viewport(el, options);\r\n\r\n      if (tools) {\r\n        for (const tool of tools) {\r\n          vp.toolManager.register(tool);\r\n        }\r\n      }\r\n\r\n      if (defaultTool) {\r\n        vp.toolManager.setTool(defaultTool, vp.toolContext);\r\n      }\r\n\r\n      setViewport(vp);\r\n      onReady?.(vp);\r\n\r\n      return () => {\r\n        vp.destroy();\r\n        setViewport(null);\r\n      };\r\n    }, []);\r\n\r\n    return (\r\n      <div ref={containerRef} className={className} style={style}>\r\n        {viewport && (\r\n          <ViewportContext.Provider value={viewport}>{children}</ViewportContext.Provider>\r\n        )}\r\n      </div>\r\n    );\r\n  },\r\n);\r\n","import { createContext } from 'react';\r\nimport type { Viewport } from '@fieldnotes/core';\r\n\r\nexport const ViewportContext = createContext<Viewport | null>(null);\r\n","import { useEffect, useRef, useState, type ReactNode } from 'react';\r\nimport { createPortal } from 'react-dom';\r\nimport { useViewport } from './use-viewport';\r\n\r\nexport interface CanvasElementProps {\r\n  position: { x: number; y: number };\r\n  size?: { w: number; h: number };\r\n  children: ReactNode;\r\n}\r\n\r\nexport function CanvasElement({ position, size, children }: CanvasElementProps) {\r\n  const viewport = useViewport();\r\n  const [portalTarget, setPortalTarget] = useState<HTMLElement | null>(null);\r\n  const elementIdRef = useRef<string | null>(null);\r\n\r\n  useEffect(() => {\r\n    const container = document.createElement('div');\r\n    Object.assign(container.style, {\r\n      width: '100%',\r\n      height: '100%',\r\n    });\r\n\r\n    // Append to domLayer immediately so portal children are queryable in the document\r\n    // before the viewport render loop fires via requestAnimationFrame.\r\n    viewport.domLayer.appendChild(container);\r\n\r\n    const id = viewport.addHtmlElement(container, position, size);\r\n    elementIdRef.current = id;\r\n    setPortalTarget(container);\r\n\r\n    return () => {\r\n      if (elementIdRef.current) {\r\n        viewport.store.remove(elementIdRef.current);\r\n        viewport.requestRender();\r\n        elementIdRef.current = null;\r\n      }\r\n      setPortalTarget(null);\r\n    };\r\n  }, [viewport]);\r\n\r\n  useEffect(() => {\r\n    const id = elementIdRef.current;\r\n    if (!id) return;\r\n    viewport.store.update(id, { position });\r\n    if (size) {\r\n      viewport.store.update(id, { size });\r\n    }\r\n    viewport.requestRender();\r\n  }, [viewport, position.x, position.y, size?.w, size?.h]);\r\n\r\n  if (!portalTarget) return null;\r\n  return createPortal(children, portalTarget);\r\n}\r\n","import { useContext } from 'react';\r\nimport type { Viewport } from '@fieldnotes/core';\r\nimport { ViewportContext } from './context';\r\n\r\nexport function useViewport(): Viewport {\r\n  const viewport = useContext(ViewportContext);\r\n  if (!viewport) {\r\n    throw new Error('useViewport must be used inside <FieldNotesCanvas>');\r\n  }\r\n  return viewport;\r\n}\r\n","import { useCallback, useSyncExternalStore } from 'react';\r\nimport { useViewport } from './use-viewport';\r\n\r\nexport function useActiveTool(): string {\r\n  const viewport = useViewport();\r\n\r\n  const subscribe = useCallback(\r\n    (onStoreChange: () => void) => viewport.toolManager.onChange(() => onStoreChange()),\r\n    [viewport],\r\n  );\r\n\r\n  const getSnapshot = useCallback(() => viewport.toolManager.activeTool?.name ?? '', [viewport]);\r\n\r\n  return useSyncExternalStore(subscribe, getSnapshot);\r\n}\r\n","import { useCallback, useRef, useSyncExternalStore } from 'react';\r\nimport { useViewport } from './use-viewport';\r\n\r\nexport interface CameraState {\r\n  x: number;\r\n  y: number;\r\n  zoom: number;\r\n}\r\n\r\nexport function useCamera(): CameraState {\r\n  const viewport = useViewport();\r\n  const cachedRef = useRef<CameraState>({ x: 0, y: 0, zoom: 1 });\r\n\r\n  const subscribe = useCallback(\r\n    (onStoreChange: () => void) => viewport.camera.onChange(onStoreChange),\r\n    [viewport],\r\n  );\r\n\r\n  const getSnapshot = useCallback((): CameraState => {\r\n    const { position, zoom } = viewport.camera;\r\n    const cached = cachedRef.current;\r\n    if (cached.x === position.x && cached.y === position.y && cached.zoom === zoom) {\r\n      return cached;\r\n    }\r\n    const next = { x: position.x, y: position.y, zoom };\r\n    cachedRef.current = next;\r\n    return next;\r\n  }, [viewport]);\r\n\r\n  return useSyncExternalStore(subscribe, getSnapshot);\r\n}\r\n"],"mappings":"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","names":["FieldNotesCanvas","useEffect","useRef","useState","useState","useRef","useEffect","useCallback","useRef","useSyncExternalStore","useRef","useCallback","useSyncExternalStore"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fieldnotes/react",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "React wrapper for Field Notes canvas SDK",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -30,6 +30,7 @@
     "react-dom": ">=18"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitest/coverage-v8": "^4.1.0",