canvu-react 0.3.6 → 0.3.8

package/dist/types-D1ftVsOQ.d.cts

@@ -1,356 +0,0 @@
-import * as react from 'react';
-import { ReactNode, RefObject } from 'react';
-import { R as Rect, V as VectorSceneItem } from './types-CB0TZZuk.cjs';
-import { C as Camera2D } from './camera-BwQjm5oh.cjs';
-
-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 };