canvu-react 0.3.5

package/dist/types--ALu1mF-.d.ts

@@ -0,0 +1,356 @@
+import * as react from 'react';
+import { ReactNode, RefObject } from 'react';
+import { R as Rect, V as VectorSceneItem } from './types-CB0TZZuk.js';
+import { C as Camera2D } from './camera-KwCYYPhm.js';
+
+type PlacementPreview = {
+    kind: "rect" | "ellipse";
+    rect: Rect;
+}
+/** Multi-select drag (world rect), like image crop / rubber-band selection. */
+ | {
+    kind: "marquee";
+    rect: Rect;
+} | {
+    kind: "line" | "arrow";
+    start: {
+        x: number;
+        y: number;
+    };
+    end: {
+        x: number;
+        y: number;
+    };
+} | {
+    kind: "stroke";
+    tool: "draw" | "marker" | "laser";
+    points: {
+        x: number;
+        y: number;
+    }[];
+};
+
+/**
+ * Describes one entry in {@link VectorToolbar}.
+ */
+type VectorToolDefinition = {
+    /** Stable id passed to `onChange` (e.g. `"hand"`, `"rect"`). */
+    id: string;
+    /** Visible label and default accessible name. */
+    label: string;
+    /**
+     * English (or other) name for the hover tooltip only. Defaults to {@link label}.
+     */
+    tooltipLabel?: string;
+    /** Optional icon; if omitted, the label text is shown. */
+    icon?: ReactNode;
+    /** Shown in `aria-keyshortcuts` when set (informational only). */
+    shortcutHint?: string;
+    /** Extra `aria-label` when you need more than `label`. */
+    ariaLabel?: string;
+};
+
+type RealtimeConnectionState = "connecting" | "connected" | "reconnecting" | "offline" | "error";
+/**
+ * In-progress freehand stroke from a remote peer (before it becomes a committed `VectorSceneItem`).
+ */
+type RemotePresenceMarkupStroke = {
+    readonly points: readonly {
+        readonly x: number;
+        readonly y: number;
+    }[];
+    readonly tool: "draw" | "pencil" | "brush" | "marker" | "laser";
+};
+/**
+ * One connected participant. Your WebSocket layer maps server messages → this shape;
+ * {@link VectorViewport} renders it in world space.
+ */
+type RemotePresencePeer = {
+    readonly id: string;
+    /** Stable color for cursor + stroke (e.g. `#2563eb`). If omitted, a hue is derived from `id`. */
+    readonly color?: string;
+    /** Short display name near the cursor. */
+    readonly displayName?: string;
+    /** Optional profile image / avatar URL for richer collaboration UIs. */
+    readonly image?: string;
+    /** Last known pointer position in **world** units, or `null` if off-canvas / idle. */
+    readonly cursor: {
+        readonly x: number;
+        readonly y: number;
+    } | null;
+    /** Optional live stroke while the peer is drawing (same semantics as local placement preview). */
+    readonly markupStroke?: RemotePresenceMarkupStroke | null;
+    /** Connection-scoped id when collaboration is backed by a realtime session. */
+    readonly clientId?: string;
+    /** Stable participant identity when collaboration is backed by a realtime session. */
+    readonly peerId?: string;
+    /** Room/session id when provided by the collaboration transport. */
+    readonly roomId?: string;
+    /** Lifecycle timestamps in epoch milliseconds. */
+    readonly joinedAt?: number;
+    readonly lastSeenAt?: number;
+    /** Distinguishes the local participant from remote peers. */
+    readonly isSelf?: boolean;
+    /** Optional active tool hint for richer presence UIs. */
+    readonly activeTool?: string;
+    /** Session-level connection state, useful for richer rosters. */
+    readonly connectionState?: RealtimeConnectionState;
+};
+type PresenceOverlayRenderContext = {
+    camera: Camera2D;
+    /** Bumps when the camera changes so overlays stay aligned with the scene. */
+    cameraVersion: number;
+};
+
+type WorldPointerDownDetail = {
+    worldX: number;
+    worldY: number;
+    toolId: string;
+    pointerType: string;
+};
+/**
+ * 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}.
+ */
+type VectorViewportHandle = {
+    /** The live camera instance, or `null` before mount / after unmount. */
+    getCamera: () => Camera2D | null;
+    /**
+     * Re-run SVG + overlay after changing `x`, `y`, or `zoom` on the camera from {@link getCamera}.
+     */
+    requestRender: () => void;
+    /** CSS pixel size of the scene surface (`clientWidth` / `clientHeight`). */
+    getViewportSize: () => {
+        width: number;
+        height: number;
+    };
+    /**
+     * Sets pan/zoom so `worldRect` fits in the viewport with optional margin (fraction of rect size per side, default `0.08`).
+     */
+    fitWorldRect: (worldRect: Rect, options?: {
+        padding?: number;
+    }) => void;
+};
+/** Drag-to-place a custom shape (same interaction as rectangle). Use with `createCustomShapeItem` from `canvu`. */
+type CustomShapePlacementOptions = {
+    toolId: string;
+    createItem: (args: {
+        id: string;
+        bounds: Rect;
+    }) => VectorSceneItem;
+};
+type VectorViewportProps = {
+    /** Vector items to draw (SVG fragments). */
+    items: readonly VectorSceneItem[];
+    className?: string;
+    /** Accessible name for the application region. */
+    ariaLabel: string;
+    /**
+     * When `applePencilNav` is true, used with `attachApplePencilNavigation` to decide
+     * when finger touches navigate (e.g. `"hand"` vs `"draw"`).
+     */
+    toolId?: string;
+    /** Enable Apple Pencil vs finger split (optional). */
+    applePencilNav?: boolean;
+    /**
+     * When true, selection, drag-to-move, resize handles, and drag-to-create shapes are enabled.
+     * Requires `onItemsChange` to persist mutations.
+     */
+    interactive?: boolean;
+    /** Selected item ids (order preserved). Empty = none. */
+    selectedIds?: readonly string[];
+    onSelectionChange?: (ids: string[]) => void;
+    onItemsChange?: (items: VectorSceneItem[]) => void;
+    /**
+     * Fires on primary pointer down on the viewport in **world** coordinates.
+     * Not called when `toolId` is `"hand"` (use that tool for panning).
+     * Ignored when `interactive` is true (placement uses drag-to-define).
+     */
+    onWorldPointerDown?: (detail: WorldPointerDownDetail) => void;
+    /**
+     * Floating UI above the scene. Compose with `VectorCanvas.Toolbar` + {@link VectorToolbar}
+     * so the strip anchors at the bottom center (`data-slot="vector-canvas-toolbar"`).
+     */
+    toolbar?: ReactNode;
+    /**
+     * Floating bottom-left zoom / undo / minimap bar. Omit to render the default `NavMenu`.
+     * Pass `<VectorCanvas.NavMenu position="..." />` to relocate or style it. Pass `null` to hide it.
+     */
+    navMenu?: ReactNode | null;
+    /**
+     * Floating selection / active-tool style inspector. Omit to render the default `VectorSelectionInspector`.
+     * Pass `<VectorCanvas.SelectionInspector position="..." />` to relocate or style it. Pass `null` to hide it.
+     */
+    selectionInspector?: ReactNode | null;
+    /**
+     * Plug and play board extensions.
+     *
+     * First-party plugins such as `chatbotPlugin(...)` and `realtimeCollaborationPlugin(...)`
+     * should be passed here. Advanced authors can create their own plugins with `createCanvuPlugin(...)`.
+     */
+    plugins?: readonly CanvasPlugin[];
+    /**
+     * Called after the scene/camera redraw (pan, zoom, items update, or {@link VectorViewportHandle.requestRender}).
+     * Can fire often during gestures — throttle/debounce if needed.
+     */
+    onCameraChange?: () => void;
+    /**
+     * When `interactive` is true, enables drag (or tap) placement for `toolId`, like built-in shapes.
+     * Implement `createItem` with `createCustomShapeItem` from `canvu`.
+     */
+    customPlacement?: CustomShapePlacementOptions;
+    /**
+     * Multiple custom placements contributed by plugins or app code.
+     *
+     * When both `customPlacement` and `customPlacements` are provided, they are combined and the active
+     * placement is resolved by the current `toolId`.
+     */
+    customPlacements?: readonly CustomShapePlacementOptions[];
+    /**
+     * When false (default), finishing a draw/place/erase gesture requests switching back to `autoResetToolTo`.
+     * Use with controlled tool state (`onToolChangeRequest`) to keep "select-after-use" behavior.
+     */
+    toolLocked?: boolean;
+    /** Tool id requested after one-shot actions complete. Default `"select"`. */
+    autoResetToolTo?: string;
+    /** Called when viewport requests a tool change (e.g. auto reset to select). */
+    onToolChangeRequest?: (toolId: string) => void;
+    /**
+     * Remote participants (cursors + optional in-progress strokes). Renders a world-space overlay
+     * below the local interaction layer. Transport is your app (WebSocket, party server, …).
+     */
+    remotePresence?: readonly RemotePresencePeer[];
+    /**
+     * Replace the default presence layer (e.g. custom cursors). When set, `remotePresence` is not
+     * rendered unless you read it from the parent closure inside this callback.
+     */
+    presenceOverlay?: (ctx: PresenceOverlayRenderContext) => ReactNode;
+    /**
+     * Throttled pointer position in **world** space while the cursor moves over the viewport
+     * (for broadcasting your cursor). Pair with `onWorldPointerLeave`.
+     */
+    onWorldPointerMove?: (world: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Fires when the pointer leaves the viewport (clear your broadcast cursor). */
+    onWorldPointerLeave?: () => void;
+    /**
+     * Fires when drag placement preview updates (rect, line, freehand stroke, …). Use it to broadcast
+     * {@link RemotePresencePeer.markupStroke} for other participants while drawing.
+     */
+    onPlacementPreviewChange?: (preview: PlacementPreview | null) => void;
+};
+/**
+ * Full-viewport vector canvas: SVG rendering + pan/zoom/pinch + optional Apple Pencil navigation.
+ * Pass a `className` that includes `touch-action: none` (e.g. Tailwind `touch-none`) on the viewport.
+ */
+declare const VectorViewport: react.ForwardRefExoticComponent<VectorViewportProps & react.RefAttributes<VectorViewportHandle>>;
+
+type CanvasPluginRenderContext = {
+    /** Live viewport handle when the plugin needs camera or viewport size. */
+    viewportRef?: RefObject<VectorViewportHandle | null>;
+};
+type CanvasPluginItemsChangeMiddlewareContext = {
+    /** Current board items before the pending change is applied. */
+    currentItems: readonly VectorSceneItem[];
+    /** Continue the item change pipeline. */
+    next: NonNullable<VectorViewportProps["onItemsChange"]>;
+    /** Original consumer callback passed to `VectorViewport`. */
+    consumerOnItemsChange?: VectorViewportProps["onItemsChange"];
+    /** Live viewport handle for advanced integrations. */
+    viewportRef?: RefObject<VectorViewportHandle | null>;
+};
+type CanvasPluginContribution = {
+    /** Additional tools injected into the board toolbar/runtime. */
+    tools?: readonly VectorToolDefinition[];
+    /** Transform the resolved tool list (reorder, replace, or filter existing tools). */
+    toolTransform?: (tools: VectorToolDefinition[]) => VectorToolDefinition[];
+    /** Multiple custom placements contributed by plugins; the active one is resolved by `toolId`. */
+    customPlacements?: readonly CustomShapePlacementOptions[];
+    /** Simple viewport prop overrides owned by the plugin runtime. */
+    viewportProps?: Partial<Pick<VectorViewportProps, "remotePresence" | "presenceOverlay">>;
+    /** Event callbacks chained into the viewport without manual wiring in app code. */
+    callbacks?: Partial<Pick<VectorViewportProps, "onWorldPointerMove" | "onWorldPointerLeave" | "onPlacementPreviewChange" | "onCameraChange">>;
+    /** Middleware around `onItemsChange` for collaboration, comments, persistence, etc. */
+    wrapOnItemsChange?: (nextItems: VectorSceneItem[], ctx: CanvasPluginItemsChangeMiddlewareContext) => void;
+};
+type CanvasPluginComponentProps = {
+    /** Stable plugin id so the component can register contributions. */
+    pluginId: string;
+};
+type CanvasPlugin = {
+    /** Stable id, e.g. `canvu.plugin.chatbot`. */
+    id: string;
+    /**
+     * Legacy/simple rendering path for purely visual plugins.
+     *
+     * Prefer `Component` for plugins that need hooks, document integration, tools, or runtime contributions.
+     */
+    render?: (ctx: CanvasPluginRenderContext) => ReactNode;
+    /**
+     * Preferred plugin entrypoint for first-party and advanced plugins.
+     *
+     * The component can use hooks and register contributions through `useCanvuPluginContribution`.
+     */
+    Component?: (props: CanvasPluginComponentProps) => ReactNode;
+};
+type CanvuPluginViewportSnapshot = Pick<VectorViewportProps, "items" | "onItemsChange" | "toolId" | "interactive" | "toolLocked" | "onToolChangeRequest">;
+type CanvuPluginContextValue = {
+    viewportRef?: RefObject<VectorViewportHandle | null>;
+    viewport: CanvuPluginViewportSnapshot;
+    resolvedTools: VectorToolDefinition[];
+    registerContribution: (pluginId: string, contribution: CanvasPluginContribution) => void;
+    unregisterContribution: (pluginId: string) => void;
+};
+declare const CanvuPluginContext: react.Context<CanvuPluginContextValue | null>;
+/**
+ * Creates a typed canvu plugin descriptor.
+ *
+ * Use this helper when authoring custom plugins so your editor can infer the plugin shape
+ * and surface better hover documentation for the returned object.
+ */
+declare function createCanvuPlugin(plugin: CanvasPlugin): CanvasPlugin;
+/**
+ * Returns the low-level canvu plugin runtime context.
+ *
+ * This is an advanced API for custom plugin authors. Prefer first-party plugin factories such as
+ * `chatbotPlugin(...)` and `realtimeCollaborationPlugin(...)` for the common path.
+ */
+declare function useCanvuPluginContext(): CanvuPluginContextValue;
+/**
+ * Returns the current viewport-facing board state exposed to plugins.
+ *
+ * Use this when a custom plugin needs access to items, the active tool, or the consumer's
+ * `onToolChangeRequest` callback.
+ */
+declare function useCanvuViewportContext(): {
+    viewportRef?: RefObject<VectorViewportHandle | null>;
+    viewport: CanvuPluginViewportSnapshot;
+};
+/**
+ * Returns the board document context exposed to plugins.
+ *
+ * This hook is intended for advanced plugins that need to read items or integrate with the board's
+ * `onItemsChange` lifecycle.
+ */
+declare function useCanvuDocumentContext(): {
+    items: readonly VectorSceneItem[];
+    onItemsChange?: VectorViewportProps["onItemsChange"];
+};
+/**
+ * Returns the tool list already resolved by the plugin runtime.
+ *
+ * `VectorToolbar` consumes this automatically when you omit its `tools` prop, so most apps do not
+ * need this hook directly.
+ */
+declare function useCanvuResolvedTools(): VectorToolDefinition[];
+/**
+ * Registers non-visual plugin contributions with the current `VectorViewport` runtime.
+ *
+ * Use this inside `plugin.Component` when you want to inject tools, viewport behavior, or document
+ * middleware without requiring the consumer to wire hooks manually.
+ */
+declare function useCanvuPluginContribution(pluginId: string, contribution: CanvasPluginContribution): void;
+
+export { type CanvasPlugin as C, type PlacementPreview as P, type RemotePresenceMarkupStroke as R, type VectorToolDefinition as V, type WorldPointerDownDetail as W, type CanvasPluginComponentProps as a, type CanvasPluginContribution as b, type CanvasPluginItemsChangeMiddlewareContext as c, type CanvasPluginRenderContext as d, CanvuPluginContext as e, type CanvuPluginContextValue as f, type CanvuPluginViewportSnapshot as g, type CustomShapePlacementOptions as h, VectorViewport as i, type VectorViewportHandle as j, type VectorViewportProps as k, createCanvuPlugin as l, useCanvuPluginContext as m, useCanvuPluginContribution as n, useCanvuResolvedTools as o, useCanvuViewportContext as p, type RemotePresencePeer as q, type RealtimeConnectionState as r, type PresenceOverlayRenderContext as s, useCanvuDocumentContext as u };

package/dist/types-B58i5k-u.d.cts

@@ -0,0 +1,35 @@
+import { V as VectorSceneItem } from './types-CB0TZZuk.cjs';
+
+/**
+ * Serializable document for persistence (localStorage, API, WebSocket).
+ * Extend with your own fields when saving to your backend.
+ */
+type VectorCanvasSnapshot = {
+    items: VectorSceneItem[];
+    /** Bump when the JSON shape changes. */
+    version?: number;
+};
+/**
+ * Plug your database, IndexedDB, or HTTP API: load/save full snapshots.
+ */
+type VectorCanvasPersistenceAdapter = {
+    load: () => Promise<VectorCanvasSnapshot | null>;
+    save: (snapshot: VectorCanvasSnapshot) => Promise<void>;
+};
+/**
+ * Wire your WebSocket / SSE / polling: receive full `items` from the server
+ * and optionally push local changes upstream.
+ */
+type VectorCanvasRemoteAdapter = {
+    /**
+     * Called when the server sends a new scene. Replace local `items` with this.
+     * Return an unsubscribe function.
+     */
+    subscribe: (onItems: (items: VectorSceneItem[]) => void) => () => void;
+    /**
+     * Optional: called after local edits (debounced) so you can `ws.send(JSON.stringify(items))`.
+     */
+    send?: (items: VectorSceneItem[]) => void;
+};
+
+export type { VectorCanvasPersistenceAdapter as V, VectorCanvasRemoteAdapter as a, VectorCanvasSnapshot as b };

package/dist/types-CB0TZZuk.d.cts

@@ -0,0 +1,157 @@
+/**
+ * Axis-aligned rectangle in 2D (world or screen space).
+ */
+type Rect = {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+};
+/**
+ * Returns whether two axis-aligned rectangles intersect (edges touching count).
+ */
+declare function rectsIntersect(a: Rect, b: Rect): boolean;
+/**
+ * Normalizes a rect so width and height are non-negative.
+ */
+declare function normalizeRect(r: Rect): Rect;
+
+/** Identifies how `childrenSvg` was produced for editing (resize, handles). */
+type VectorToolKind = "rect" | "ellipse" | "line" | "arrow" | "draw" | "pencil" | "brush" | "marker" | "text" | "image" | "custom";
+/** Local segment for line/arrow (relative to item `x`, `y`). */
+type LineEndpointsLocal = {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+};
+type VectorPathPoint = {
+    x: number;
+    y: number;
+    pressure?: number;
+};
+/** Arrow endpoint glued to a shape boundary (normalized anchor in target local 0…1 space). */
+type ArrowEndpointBinding = {
+    targetId: string;
+    anchor: {
+        x: number;
+        y: number;
+    };
+};
+type ArrowBindings = {
+    start?: ArrowEndpointBinding;
+    end?: ArrowEndpointBinding;
+};
+/**
+ * One drawable vector item in world space. `childrenSvg` is inner markup for an SVG `<g>`
+ * (paths, circles, text — no outer `<svg>` wrapper).
+ *
+ * @example
+ * ```ts
+ * const item: VectorSceneItem = {
+ *   id: "a1",
+ *   x: 0,
+ *   y: 0,
+ *   bounds: { x: 0, y: 0, width: 200, height: 100 },
+ *   childrenSvg: '<rect width="200" height="100" fill="#eee" />',
+ * };
+ * ```
+ */
+type VectorSceneItem = {
+    readonly id: string;
+    /** World-space bounds used for visibility culling and selection. */
+    readonly bounds: Rect;
+    /**
+     * SVG fragment placed inside `<g transform="translate(x,y)">`.
+     * Use local coordinates within [0, bounds.width] × [0, bounds.height] for predictable layout.
+     */
+    readonly childrenSvg: string;
+    /** World position of the item’s top-left corner. */
+    readonly x: number;
+    readonly y: number;
+    /** How the SVG was built — used for resize / handle editing. */
+    readonly toolKind?: VectorToolKind;
+    /**
+     * Stroke color for shapes and lines; for {@link toolKind} `"text"` this is used as **fill** color.
+     * Default when omitted: `#2563eb`.
+     */
+    readonly stroke?: string;
+    /** SVG stroke width in local space (same visual scales with zoom). Default `2`. */
+    readonly strokeWidth?: number;
+    /** Optional stroke opacity (e.g. highlighter `~0.45`). */
+    readonly strokeOpacity?: number;
+    /**
+     * Polyline for freehand tools (`draw`, `marker`; legacy `pencil` / `brush`) in **local** coords relative to `x`,`y`.
+     */
+    readonly pathPointsLocal?: readonly VectorPathPoint[];
+    /** Counter-clockwise rotation around the center of `bounds` (radians). Omitted = 0. */
+    readonly rotation?: number;
+    /**
+     * When true, the item still renders but is ignored by direct user interaction
+     * such as selection, resize, rotate, editing, and erasing.
+     * Useful for protected background pages that should allow drawing on top.
+     */
+    readonly locked?: boolean;
+    /** Line/arrow endpoints in local space; required for directed lines/arrows. */
+    readonly line?: LineEndpointsLocal;
+    /** When set on an arrow, endpoints follow the bound shapes when they move or resize. */
+    readonly arrowBind?: ArrowBindings;
+    /** User text for `toolKind === "text"` (plain text, newlines allowed). */
+    readonly text?: string;
+    /**
+     * When true, `bounds` are user-controlled (e.g. resize handles) and text wraps inside;
+     * when false/undefined, bounds grow with content (no fixed width).
+     */
+    readonly textFixedBounds?: boolean;
+    /** Local font size in px for `toolKind === "text"` (default 18). Scales on resize like tldraw. */
+    readonly textFontSize?: number;
+    /**
+     * For `toolKind === "image"`: embedded bitmap as `data:image/...` for a single SVG `<image>`.
+     * Preferred over path-tracing for performance and visual quality on screenshots/photos.
+     */
+    readonly imageRasterHref?: string;
+    /**
+     * Session-scoped `blob:` URL for the 256px thumbnail.
+     * Used for progressive loading: render thumbnail first, swap to full-res in background.
+     * Not persisted — recreated on load by the persistence adapter.
+     */
+    readonly imageThumbnailHref?: string;
+    /** Pixel size of {@link imageRasterHref} before scaling into `bounds`. */
+    readonly imageIntrinsicSize?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * IndexedDB blob ID for the original image file.
+     * When set, the persistence adapter stores the blob separately from the JSON document,
+     * enabling full-resolution images without bloating the serialized snapshot.
+     */
+    readonly imageBlobId?: string;
+    /**
+     * IndexedDB blob ID for the 256px thumbnail.
+     * Used for progressive loading (thumbnail → full-res swap).
+     */
+    readonly imageThumbnailBlobId?: string;
+    /**
+     * Optional: traced SVG fragment (advanced / legacy) in {@link imageVectorLocalSize} space.
+     */
+    readonly imageVectorInnerSvg?: string;
+    readonly imageVectorLocalSize?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * For {@link toolKind} `"custom"`: inner SVG drawn in {@link customIntrinsicSize} space.
+     * When set with {@link customIntrinsicSize}, resize keeps proportions by scaling this markup.
+     */
+    readonly customInnerSvg?: string;
+    /** Pixel size that {@link customInnerSvg} is authored for (usually matches initial `bounds`). */
+    readonly customIntrinsicSize?: {
+        width: number;
+        height: number;
+    };
+    /** Optional app/plugin metadata persisted alongside the item. */
+    readonly pluginData?: Record<string, unknown>;
+};
+
+export { type ArrowEndpointBinding as A, type LineEndpointsLocal as L, type Rect as R, type VectorSceneItem as V, type ArrowBindings as a, type VectorPathPoint as b, normalizeRect as n, rectsIntersect as r };