@canvas-harness/react 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,462 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _canvas_harness_core from '@canvas-harness/core';
+import { Node, CanvasStore, EditorAdapterFactory, Renderer, CanvasBackground, NodeId, EdgeId, Edge, CameraState, PointerInfo, InteractionMode, InteractionState, PresenceState, ClientId } from '@canvas-harness/core';
+import { ReactNode, CSSProperties } from 'react';
+
+/**
+ * Defaults applied to every edge the arrow tool creates. Lets a
+ * consumer (e.g. a style-memory hook) inject the user's last-used
+ * pathStyle / arrowheads / style without forcing every edge through
+ * a custom factory.
+ */
+type ArrowToolDefaults = {
+    pathStyle?: _canvas_harness_core.PathStyle;
+    style?: _canvas_harness_core.EdgeStyle;
+};
+
+/**
+ * Theme resolver — see ARCHITECTURE.md §13.10. Returns a color string
+ * (or undefined to fall back to the built-in defaults) for a given
+ * design-system token + context.
+ */
+type ThemeResolver = (token: string, ctx?: {
+    node?: Node;
+    state?: 'idle' | 'hover' | 'selected' | 'drag';
+}) => string | undefined;
+
+/**
+ * Pointer info passed to `onClick` / `onDoubleClick`. Includes the
+ * point in both screen space and world space so consumers don't have
+ * to convert.
+ */
+type CanvasPointerEvent = {
+    /** Position relative to the canvas element. */
+    screen: {
+        x: number;
+        y: number;
+    };
+    /** Position in scene coordinates (camera-adjusted). */
+    world: {
+        x: number;
+        y: number;
+    };
+    /** Tool active when the event fired. */
+    tool: string;
+    /** The native MouseEvent — read modifiers, button, etc. */
+    native: MouseEvent;
+};
+/**
+ * Fired on pointerup after a drag-to-create gesture (non-select tool,
+ * drag larger than ~5px). The consumer maps the rect into a new node
+ * (defaults, type, style — all consumer policy).
+ */
+type CanvasCreateDragEvent = {
+    /** Bounding rect of the drag, in world coordinates. */
+    rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Tool active when the gesture ended. */
+    tool: string;
+    native: PointerEvent;
+};
+type CanvasProps = {
+    /**
+     * Optional — when omitted, the component reads the store from
+     * `<CanvasProvider>` context. Pass directly for tests or
+     * standalone-canvas use.
+     */
+    store?: CanvasStore;
+    /**
+     * Current tool. The library handles `'select'` and `'arrow'`
+     * internally; any other string passes through to `onClick` /
+     * `onCreateDrag` so consumers can wire their own shape-create /
+     * text-tool / lasso / ... logic.
+     */
+    tool: string;
+    /** Theme resolver — see ARCHITECTURE.md §13.10 for the token catalog. */
+    theme?: ThemeResolver;
+    /**
+     * Pluggable in-place editor factory; defaults to the built-in
+     * `<textarea>`. Implement to swap in Lexical / ProseMirror / TipTap.
+     */
+    editorAdapter?: EditorAdapterFactory;
+    /** Called once when the renderer is mounted. Useful for perf overlays. */
+    onRenderer?: (r: Renderer) => void;
+    /** Click on the canvas surface (not over a node handle). */
+    onClick?: (e: CanvasPointerEvent) => void;
+    /** Double-click on the surface. The library has already triggered
+     *  `beginEdit` if the click landed on a node body. */
+    onDoubleClick?: (e: CanvasPointerEvent) => void;
+    /**
+     * Drag-to-create — fires on pointerup when the user dragged with a
+     * non-select tool. Sub-threshold drags fall through to `onClick`.
+     *
+     * @example
+     * onCreateDrag={({ rect, tool }) => {
+     *   if (tool === 'rect') store.addNode({ ...rect, type: 'rect', ... })
+     * }}
+     */
+    onCreateDrag?: (e: CanvasCreateDragEvent) => void;
+    /**
+     * Defaults applied to every edge the built-in arrow tool creates.
+     * Lets a consumer remember the user's last-used pathStyle / style /
+     * arrowheads. Shape + text tools route through `onClick` /
+     * `onCreateDrag` so consumer controls those defaults directly.
+     */
+    arrowDefaults?: ArrowToolDefaults;
+    /**
+     * Page background + optional infinite dot/grid pattern. Local-only
+     * (not part of the synced scene). Update by changing the prop —
+     * `<Canvas>` calls `renderer.setBackground` and forces a repaint.
+     *
+     * @example
+     * <Canvas background={{ color: '#fffaf3', pattern: 'dots', gap: 24 }} />
+     */
+    background?: CanvasBackground;
+    /**
+     * Render a custom node's React subtree. Called once per
+     * library-mounted custom-node id; positioning is handled by the
+     * overlay container (consumer fills the slot).
+     *
+     * @example
+     * renderCustomNodeView={id => {
+     *   const node = store.getNode(id)
+     *   if (node?.type === 'chart-card') return <ChartCardView node={node} />
+     *   return null
+     * }}
+     */
+    renderCustomNodeView?: (id: NodeId) => ReactNode;
+    /** Extra content rendered inside the canvas absolute container. */
+    children?: ReactNode;
+};
+/**
+ * Mounts the canvas surface (static + interactive layers + DOM overlay
+ * for custom-node views + in-place editor mount). Owns the renderer
+ * lifecycle, gesture hooks, resize observer.
+ *
+ * Use inside a {@link CanvasProvider} (or pass `store` directly).
+ *
+ * @example
+ * function App() {
+ *   const store = useRef(createCanvasStore()).current
+ *   const [tool, setTool] = useState('select')
+ *   return (
+ *     <CanvasProvider store={store}>
+ *       <Canvas
+ *         tool={tool}
+ *         onClick={e => console.log('click at', e.world)}
+ *         onCreateDrag={e => {
+ *           store.addNode({ id: asNodeId(store.generateId()), type: e.tool, ...e.rect, angle: 0, z: 0, groups: [] })
+ *         }}
+ *       />
+ *       <Toolbar onSelect={setTool} />
+ *     </CanvasProvider>
+ *   )
+ * }
+ */
+declare function Canvas(props: CanvasProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Bird's-eye overview of the entire scene + a viewport rectangle
+ * showing where the camera is. Click or drag inside to pan.
+ *
+ * Perf model — see IMPROVEMENTS.md and core/render/minimap.ts:
+ *   - Scene content is rendered into an offscreen-canvas cache **once
+ *     per committed batch** (`'change'` event). Cost: O(N) per
+ *     commit, not per frame.
+ *   - On camera changes (pan/zoom), only the viewport rectangle is
+ *     redrawn over the cached image. Cost: O(1) per frame.
+ *   - Above `maxNodes`, the content render is skipped and a small
+ *     placeholder text is shown instead.
+ *
+ * @example
+ * <Minimap width={200} height={150} position="bottom-right" />
+ */
+type MinimapProps = {
+    /** Map width in CSS px. Default 200. */
+    width?: number;
+    /** Map height in CSS px. Default 150. */
+    height?: number;
+    /** Above this many nodes, content render is skipped (placeholder
+     *  shown instead). Default 5000. */
+    maxNodes?: number;
+    /** Fixed-position corner shortcut. Use `style` for custom placement. */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /** Override container styles entirely (skip `position`). */
+    style?: CSSProperties;
+    /** Color of the viewport rect overlay. Default brand blue. */
+    viewportColor?: string;
+    /** Background color drawn behind the cached content + applied to the
+     *  default container background. Default white. */
+    backgroundColor?: string;
+    /** Container border color (the surrounding chip). Default light slate. */
+    borderColor?: string;
+    /** Fallback node color when a node has no `style.backgroundColor`.
+     *  Default neutral slate. */
+    defaultNodeColor?: string;
+};
+declare function Minimap({ width, height, maxNodes, position, style, viewportColor, backgroundColor, borderColor, defaultNodeColor, }: MinimapProps): react_jsx_runtime.JSX.Element;
+
+type CanvasProviderProps = {
+    store: CanvasStore;
+    children: ReactNode;
+};
+/**
+ * Provides a {@link CanvasStore} to descendant hooks via context.
+ * Wrap your app (or just the canvas + its panels) once at the top
+ * level. `<Canvas>` reads the same store from context.
+ *
+ * @example
+ * const store = useRef(createCanvasStore()).current
+ * <CanvasProvider store={store}>
+ *   <Toolbar />
+ *   <Canvas tool="select" />
+ *   <Sidebar />
+ * </CanvasProvider>
+ */
+declare function CanvasProvider({ store, children }: CanvasProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Returns the {@link CanvasStore} from context. Use this when you need
+ * to mutate the store from event handlers (e.g. tool buttons, side
+ * panels). For reactive reads, prefer the more specific hooks
+ * (`useNode`, `useSelection`, `useCamera`, ...).
+ *
+ * Throws if called outside a `<CanvasProvider>`.
+ *
+ * @example
+ * function ClearButton() {
+ *   const store = useCanvasStore()
+ *   return <button onClick={() => store.batch(() => {
+ *     for (const n of store.getAllNodes()) store.removeNode(n.id)
+ *   })}>Clear</button>
+ * }
+ */
+declare function useCanvasStore(): CanvasStore;
+
+/**
+ * Subscribes to a single node. Re-renders **only** when that node
+ * changes — moves on other nodes are free.
+ *
+ * The recommended hook for custom-node React views, layer panels keyed
+ * by id, and any per-node UI.
+ *
+ * @example
+ * function StickyView({ id }: { id: NodeId }) {
+ *   const node = useNode(id)
+ *   if (!node) return null
+ *   return <div>{node.content ?? 'empty'}</div>
+ * }
+ */
+declare function useNode(id: NodeId): Node | undefined;
+/**
+ * Returns every node (optionally filtered). Re-renders on **every**
+ * committed batch — expensive. Use for sidebars / minimaps / layer
+ * panels that legitimately see all nodes; never inside per-node
+ * components.
+ *
+ * @example
+ * // Layer panel: list every node grouped by type.
+ * function Layers() {
+ *   const nodes = useNodes()
+ *   return <ul>{nodes.map(n => <li key={n.id}>{n.type}</li>)}</ul>
+ * }
+ *
+ * @example
+ * // Filtered: only text nodes.
+ * const textNodes = useNodes(n => n.type === 'text')
+ */
+declare function useNodes(predicate?: (n: Node) => boolean): Node[];
+
+/**
+ * Subscribes to a single edge. Re-renders only when that edge mutates
+ * (style change, endpoint reconnect, etc.). Use inside per-edge UI
+ * like a label component or an inspector panel.
+ *
+ * @example
+ * function EdgeLabel({ id }: { id: EdgeId }) {
+ *   const edge = useEdge(id)
+ *   return <span>{edge?.style?.strokeColor ?? 'default'}</span>
+ * }
+ */
+declare function useEdge(id: EdgeId): Edge | undefined;
+/**
+ * Returns every edge (optionally filtered). Re-renders on every
+ * committed batch — expensive. Use for inspector panels or minimaps;
+ * never inside per-edge components.
+ *
+ * @example
+ * const dashed = useEdges(e => e.style?.strokeStyle === 'dashed')
+ */
+declare function useEdges(predicate?: (e: Edge) => boolean): Edge[];
+
+/**
+ * Returns the current selection — an array of node and/or edge ids.
+ * Re-renders only when the selection changes.
+ *
+ * @example
+ * function DeleteButton() {
+ *   const store = useCanvasStore()
+ *   const selection = useSelection()
+ *   return (
+ *     <button disabled={selection.length === 0} onClick={() => {
+ *       for (const id of selection) {
+ *         if (store.getNode(id as NodeId)) store.removeNode(id as NodeId)
+ *         else store.removeEdge(id as EdgeId)
+ *       }
+ *     }}>
+ *       Delete ({selection.length})
+ *     </button>
+ *   )
+ * }
+ */
+declare function useSelection(): (NodeId | EdgeId)[];
+
+/**
+ * Returns the current camera (`{ x, y, z }`). Re-renders on every
+ * camera change — pan / zoom / `store.setCamera(...)`.
+ *
+ * Useful for status bars, minimaps, or positioning overlays in world
+ * coordinates.
+ *
+ * @example
+ * function ZoomReadout() {
+ *   const { z } = useCamera()
+ *   return <span>{Math.round(z * 100)}%</span>
+ * }
+ */
+declare function useCamera(): CameraState;
+
+/**
+ * Full interaction state. Fires on **any** change — mode flips,
+ * pointermoves, drag delta updates, marquee rect updates, ...
+ *
+ * Most consumers want a narrower hook (`useInteractionMode`,
+ * `useCursor`, `useIsMoving`, `useDraggedIds`). Reach for this one only
+ * if you need multiple fields together.
+ *
+ * @example
+ * const state = useInteractionState()
+ * if (state.mode === 'marqueeing') drawMarqueeOverlay(state.marqueeRect)
+ */
+declare function useInteractionState(): InteractionState;
+/**
+ * Just the interaction mode. Re-renders only on mode transitions,
+ * never on pointermove.
+ *
+ * Use to gate heavy effects ("only run X when mode === 'idle'") or
+ * disable UI affordances during a drag.
+ *
+ * @example
+ * const mode = useInteractionMode()
+ * <button disabled={mode !== 'idle'}>Run AI suggestion</button>
+ */
+declare function useInteractionMode(): InteractionMode;
+/**
+ * Latest pointer info — `worldX/Y`, `screenX/Y`, `pointerType`,
+ * optional `pressure` (for pens). Updated on every pointermove.
+ *
+ * @example
+ * const cursor = useCursor()
+ * <div>x: {cursor?.worldX.toFixed(1)}</div>
+ */
+declare function useCursor(): PointerInfo | null;
+/**
+ * `true` while the user is panning, zooming, dragging, resizing, or
+ * rotating. Derived from {@link useInteractionMode}.
+ *
+ * Useful for skipping expensive renders during motion (the library
+ * does this internally for the bitmap cache; consumers can do the same
+ * for custom-node React views).
+ *
+ * @example
+ * const isMoving = useIsMoving()
+ * return isMoving ? <Skeleton /> : <ExpensiveChart />
+ */
+declare function useIsMoving(): boolean;
+declare function useDraggedIds(): readonly (NodeId | EdgeId)[];
+/**
+ * `true` when the most recent pointer was a stylus. Falls back to
+ * `false` before any pointer event has fired.
+ *
+ * Use to surface pen-specific UI (pressure-aware tools, ink hints).
+ *
+ * @example
+ * const isPen = useIsPenActive()
+ * {isPen && <PressureToolbar />}
+ */
+declare function useIsPenActive(): boolean;
+
+/**
+ * This client's own presence — cursor / selection / editing / color /
+ * name. Re-renders when local presence updates.
+ *
+ * Set local presence via `store.presence.setLocal({...})`. The library
+ * forwards it through the attached `SyncAdapter` automatically.
+ *
+ * @example
+ * const me = useLocalPresence()
+ * <div>signed in as {me.name}</div>
+ */
+declare function useLocalPresence(): PresenceState;
+/**
+ * Reads remote presence.
+ *
+ * - `usePresence(clientId)` — one remote client's state, or
+ *   `undefined` if they've left.
+ * - `usePresence()` — map of every remote client. Re-renders on every
+ *   remote update (join / leave / cursor move). Use sparingly.
+ *
+ * @example
+ * // Paint every remote cursor.
+ * const remotes = usePresence()
+ * for (const p of remotes.values()) drawCursor(p)
+ *
+ * @example
+ * // Just one peer.
+ * const peer = usePresence(asClientId('alice'))
+ */
+declare function usePresence(clientId: ClientId): PresenceState | undefined;
+declare function usePresence(): ReadonlyMap<ClientId, PresenceState>;
+
+/**
+ * `true` when there's something to undo. Updates after every committed
+ * batch (the only thing that changes the stack).
+ *
+ * @example
+ * const canUndo = useCanUndo()
+ * <button disabled={!canUndo} onClick={() => store.undo()}>Undo</button>
+ */
+declare function useCanUndo(): boolean;
+/**
+ * `true` when there's something to redo. See {@link useCanUndo}.
+ *
+ * @example
+ * const canRedo = useCanRedo()
+ * <button disabled={!canRedo} onClick={() => store.redo()}>Redo</button>
+ */
+declare function useCanRedo(): boolean;
+
+/**
+ * useInteraction — owns the gesture state machine for the Select tool.
+ *
+ * Handles click-select, shift-toggle, marquee, drag, resize. Talks to the
+ * store via setInteractionState (transient) and applyOp/updateNode (commits).
+ *
+ * The pan/zoom hook (usePanZoom) handles middle-button pan and wheel/pinch
+ * zoom; this hook handles primary-button gestures only.
+ */
+
+type InteractionTool = 'select' | 'rect' | 'ellipse' | 'diamond' | 'capsule' | 'arrow' | 'text';
+
+/**
+ * @canvas-harness/react
+ *
+ * React bindings: `<Canvas>` component + data/interaction/presence/history hooks.
+ * See ARCHITECTURE.md §13 and IMPLEMENTATION.md Phase 9.
+ */
+declare const VERSION = "0.0.0";
+
+export { type ArrowToolDefaults, Canvas, type CanvasCreateDragEvent, type CanvasPointerEvent, type CanvasProps, CanvasProvider, type CanvasProviderProps, type InteractionTool, Minimap, type MinimapProps, type ThemeResolver, VERSION, useCamera, useCanRedo, useCanUndo, useCanvasStore, useCursor, useDraggedIds, useEdge, useEdges, useInteractionMode, useInteractionState, useIsMoving, useIsPenActive, useLocalPresence, useNode, useNodes, usePresence, useSelection };