canvu-react 0.3.6 → 0.3.8

package/dist/react.d.ts

@@ -1,224 +1,156 @@
-import * as react from 'react';
-import { CSSProperties, ReactNode, SVGProps } from 'react';
-import { C as Camera2D } from './camera-KwCYYPhm.js';
-import { S as StrokeStyle } from './shape-builders-DTYvub8W.js';
 import { V as VectorSceneItem } from './types-CB0TZZuk.js';
-import { V as VectorToolDefinition, C as CanvasPlugin } from './types--ALu1mF-.js';
-export { a as CanvasPluginComponentProps, b as CanvasPluginContribution, c as CanvasPluginItemsChangeMiddlewareContext, d as CanvasPluginRenderContext, e as CanvuPluginContext, f as CanvuPluginContextValue, g as CanvuPluginViewportSnapshot, h as CustomShapePlacementOptions, P as PlacementPreview, i as VectorViewport, j as VectorViewportHandle, k as VectorViewportProps, W as WorldPointerDownDetail, l as createCanvuPlugin, u as useCanvuDocumentContext, m as useCanvuPluginContext, n as useCanvuPluginContribution, o as useCanvuResolvedTools, p as useCanvuViewportContext } from './types--ALu1mF-.js';
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import { V as VectorViewportAssetKind, a as VectorViewportAssetStore, b as VectorToolDefinition, C as CanvasPlugin, B as BoardComponentPosition } from './types-CpqlbbCP.js';
+export { c as CanvasPluginComponentProps, d as CanvasPluginContribution, e as CanvasPluginItemsChangeMiddlewareContext, f as CanvasPluginRenderContext, g as CanvuChromeActiveToolStyle, h as CanvuChromeContext, i as CanvuChromeContextValue, j as CanvuChromeSelectionStyleChange, k as CanvuPluginContext, l as CanvuPluginContextValue, m as CanvuPluginViewportSnapshot, n as CustomShapePlacementOptions, N as NavMenu, o as NavMenuProps, P as PlacementPreview, p as VectorCanvas, q as VectorCanvasBody, r as VectorCanvasHeader, s as VectorCanvasMain, t as VectorCanvasRoot, u as VectorCanvasSlotProps, v as VectorCanvasSpacePosition, w as VectorCanvasSpaceProps, x as VectorCanvasToolbar, y as VectorCanvasToolbarProps, z as VectorCanvasViewportSurface, A as VectorSelectionInspector, D as VectorSelectionInspectorProps, E as VectorViewport, F as VectorViewportAssetResolveRequest, G as VectorViewportAssetResolveResult, H as VectorViewportAssetUploadRequest, I as VectorViewportAssetUploadResult, J as VectorViewportHandle, K as VectorViewportProps, W as WorldPointerDownDetail, L as createCanvuPlugin, M as getBoardPositionStyle, O as useCanvuChromeContext, Q as useCanvuDocumentContext, R as useCanvuPluginContext, S as useCanvuPluginContribution, T as useCanvuResolvedTools, U as useCanvuViewportContext } from './types-CpqlbbCP.js';
 import { V as VectorCanvasPersistenceAdapter, a as VectorCanvasRemoteAdapter } from './types-DgEArHkA.js';
 export { b as VectorCanvasSnapshot } from './types-DgEArHkA.js';
+import * as react from 'react';
+import { SVGProps, CSSProperties, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import './camera-KwCYYPhm.js';
+import './shape-builders-DTYvub8W.js';
 
-type CanvuChromeActiveToolStyle = StrokeStyle & {
-    toolKind: "draw" | "marker";
-    label?: string;
-};
-type CanvuChromeSelectionStyleChange = (patch: {
-    stroke: string;
-    strokeWidth: number;
-    strokeOpacity?: number;
-}) => void;
-/**
- * Runtime data and handlers shared with floating board chrome (e.g. {@link NavMenu},
- * {@link VectorSelectionInspector}). Populated by `VectorViewport` and consumed via
- * {@link useCanvuChromeContext}.
- */
-type CanvuChromeContextValue = {
-    camera: Camera2D | null;
-    viewportWidth: number;
-    viewportHeight: number;
-    items: readonly VectorSceneItem[];
-    selectedItems: readonly VectorSceneItem[];
-    interactive: boolean;
-    canEditSelection: boolean;
-    activeToolStyle: CanvuChromeActiveToolStyle | null;
-    onSelectionStyleChange: CanvuChromeSelectionStyleChange | null;
-    zoomPercent: number;
-    onZoomIn: () => void;
-    onZoomOut: () => void;
-    onUndo: () => void;
-    onRedo: () => void;
-    canUndo: boolean;
-    canRedo: boolean;
-    onRequestRender: () => void;
-};
-declare const CanvuChromeContext: react.Context<CanvuChromeContextValue | null>;
-/** Returns the current chrome context or `null` when used outside `VectorViewport`. */
-declare function useCanvuChromeContext(): CanvuChromeContextValue | null;
+declare class IndexedDbImageStore {
+    private dbPromise;
+    private getDb;
+    storeOriginal(blob: Blob): Promise<string>;
+    getOriginal(id: string): Promise<Blob | undefined>;
+    deleteOriginal(id: string): Promise<void>;
+    storeThumbnail(blob: Blob): Promise<string>;
+    getThumbnail(id: string): Promise<Blob | undefined>;
+    deleteThumbnail(id: string): Promise<void>;
+}
 
-type ActiveToolStyle = StrokeStyle & {
-    toolKind: "draw" | "marker";
-    label?: string;
-};
 /**
- * Color + stroke-width inspector for the current selection (or active drawing tool style).
- * When rendered inside `VectorViewport` (e.g. via the `selectionInspector` slot), `items`,
- * `activeToolStyle`, and `onChange` default to values from {@link CanvuChromeContext};
- * pass any prop to override.
+ * Extra context for each item created by {@link ingestAssetFilesToSceneItems}.
+ *
+ * Use this when you need to lock imported pages, assign custom ids, or attach
+ * additional metadata beyond the `pluginData` returned by {@link VectorViewportAssetStore.upload}.
  */
-type VectorSelectionInspectorProps = {
-    /** Selected items that support stroke/fill styling (caller may filter). */
-    items?: readonly VectorSceneItem[];
-    /** Optional active tool style shown even without a selection. */
-    activeToolStyle?: ActiveToolStyle | null;
-    /** Apply stroke / width / opacity to every item in `items`. */
-    onChange?: CanvuChromeSelectionStyleChange;
-    /** Anchor preset. Defaults to top-left. */
-    position?: BoardComponentPosition;
-    /** Distance (px) from anchored edges. @default 12 */
-    inset?: number;
-    /** @default 24 */
-    zIndex?: number;
-    className?: string;
-    /** Merged on top of position-derived styles for custom tweaks. */
-    style?: CSSProperties;
+type IngestedAssetItemContext = {
+    file: File;
+    kind: VectorViewportAssetKind;
+    itemIndex: number;
+    pageNumber?: number;
 };
 /**
- * Color + stroke width for the current selection. Supports multiple selected shapes: one change applies to all.
+ * Structured error produced while ingesting a file into scene items.
+ *
+ * The helper keeps partial success by default: one file can fail without
+ * preventing the remaining files from being converted.
  */
-declare function VectorSelectionInspector({ items: itemsProp, activeToolStyle: activeToolStyleProp, onChange: onChangeProp, position, inset, zIndex, className, style, }: VectorSelectionInspectorProps): react_jsx_runtime.JSX.Element | null;
-
-type VectorCanvasSlotProps = {
-    children?: ReactNode;
-    className?: string;
-    style?: CSSProperties;
+type IngestAssetFileError = {
+    file: File;
+    kind?: VectorViewportAssetKind;
+    error: unknown;
 };
 /**
- * Anchor presets for floating board components.
+ * Options for {@link ingestAssetFilesToSceneItems}.
  *
- * Names are `<edge>-<position-along-edge>`:
- * - `top-*` / `bottom-*` anchor to the top or bottom edge.
- * - `left-*` / `right-*` anchor to the left or right edge.
+ * This is the shared ingestion pipeline used by canvu's built-in file flow.
+ * Use it when files originate outside the viewport, such as:
  *
- * Corner aliases are equivalent (e.g. `top-left` and `left-top` resolve to the same anchor),
- * but kept distinct so callers can pick whichever reads best in their layout (a vertical
- * strip might prefer `left-top`; a horizontal strip prefers `top-left`).
- */
-type BoardComponentPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | "left-top" | "left-center" | "left-bottom" | "right-top" | "right-center" | "right-bottom" | "center" | "fill";
-/** @deprecated Use {@link BoardComponentPosition}. */
-type VectorCanvasSpacePosition = BoardComponentPosition;
-/**
- * Compute absolute-position CSS for a board component anchor preset.
- * Returns `position`, `zIndex`, and the relevant edge offsets / transforms.
- * Callers merge the result with their own style/className overrides.
- */
-declare function getBoardPositionStyle(position: BoardComponentPosition, inset?: number, zIndex?: number): CSSProperties;
-type VectorCanvasSpaceProps = VectorCanvasSlotProps & {
-    position?: BoardComponentPosition;
-    /** @default 12 */
-    inset?: number;
-    /** @default 40 */
-    zIndex?: number;
-    /** Pointer events value on the content wrapper. @default "auto" */
-    contentPointerEvents?: CSSProperties["pointerEvents"];
-};
-/**
- * Full-viewport column shell for a vector canvas (header + body with stage).
- * Use with {@link VectorCanvasBody}, {@link VectorCanvasMain}. Pass `toolbar` on {@link VectorViewport};
- * Compose the floating tool strip with {@link VectorCanvasToolbar} around {@link VectorToolbar} (see example below).
- */
-declare function VectorCanvasRoot({ children, className, style, }: VectorCanvasSlotProps): react_jsx_runtime.JSX.Element;
-/** Optional top chrome (title, hints, toggles). */
-declare function VectorCanvasHeader({ children, className, style, }: VectorCanvasSlotProps): react_jsx_runtime.JSX.Element;
-/** Fills remaining space below the header (typically one {@link VectorCanvasMain}). */
-declare function VectorCanvasBody({ children, className, style, }: VectorCanvasSlotProps): react_jsx_runtime.JSX.Element;
-/**
- * Stretch area for {@link VectorViewport} (or any child that should fill the stage).
- */
-declare function VectorCanvasMain({ children, className, style, }: VectorCanvasSlotProps): react_jsx_runtime.JSX.Element;
-/**
- * Flex child that fills {@link VectorCanvasMain} and gives {@link VectorViewport} a bounded height
- * (white surface by default). Omit if you set the background on `Main` or the viewport yourself.
- */
-declare function VectorCanvasViewportSurface({ children, className, style, }: VectorCanvasSlotProps): react_jsx_runtime.JSX.Element;
-type VectorCanvasToolbarProps = {
-    children?: ReactNode;
-    className?: string;
-    style?: CSSProperties;
-    /** Anchor preset. @default "bottom-center" */
-    position?: BoardComponentPosition;
-    /** Distance (px) from the anchored edge(s). @default 12 */
-    inset?: number;
-    /** @default 30 */
-    zIndex?: number;
-};
-/**
- * Floating strip anchor for {@link VectorToolbar} or custom controls. Defaults to bottom-center.
- * Renders `pointer-events: none` on the shell and `auto` on children so the canvas keeps receiving hits outside the bar.
- * Pass as the `toolbar` prop of `VectorViewport`; pick a different `position` for top / side anchoring.
- * Z-index defaults to 30 so the strip stays above zoom controls.
- */
-declare function VectorCanvasToolbar({ children, className, style, position, inset, zIndex, }: VectorCanvasToolbarProps): react_jsx_runtime.JSX.Element;
-/**
- * Absolute canvas-aligned space for floating UI such as chats, rosters, inspectors, and overlays.
- * Use this instead of ad-hoc wrapper divs or plugin hosts when a feature can be expressed as React nodes.
- */
-declare function VectorCanvasSpace({ children, className, style, position, inset, zIndex, contentPointerEvents, }: VectorCanvasSpaceProps): react_jsx_runtime.JSX.Element;
-/**
- * Namespaced layout primitives for composing a vector canvas shell without ad-hoc wrapper divs.
+ * - custom upload dialogs
+ * - board/version creation flows
+ * - programmatic imports
+ * - legacy migrations
+ *
+ * Prefer passing `assetStore` directly to `VectorViewport` when the user is
+ * already interacting with canvu's native file picker or drag-and-drop UI.
  *
  * @example
- * ```tsx
- * <VectorCanvas.Root>
- *   <VectorCanvas.Header>…</VectorCanvas.Header>
- *   <VectorCanvas.Body>
- *     <VectorCanvas.Main>
- *       <VectorCanvas.ViewportSurface>
- *         <VectorViewport
- *           toolbar={
- *             <VectorCanvas.Toolbar>
- *               <VectorToolbar … />
- *             </VectorCanvas.Toolbar>
- *           }
- *           …
- *         />
- *       </VectorCanvas.ViewportSurface>
- *     </VectorCanvas.Main>
- *   </VectorCanvas.Body>
- * </VectorCanvas.Root>
+ * ```ts
+ * const result = await ingestAssetFilesToSceneItems({
+ *   files: Array.from(input.files ?? []),
+ *   worldCenter: { x: 0, y: 0 },
+ *   assetStore,
+ *   decorateItem(item) {
+ *     return {
+ *       ...item,
+ *       locked: true,
+ *     };
+ *   },
+ * });
+ *
+ * doc.onItemsChange([...doc.items, ...result.items]);
  * ```
  */
-declare const VectorCanvas: {
-    readonly Root: typeof VectorCanvasRoot;
-    readonly Header: typeof VectorCanvasHeader;
-    readonly Body: typeof VectorCanvasBody;
-    readonly Main: typeof VectorCanvasMain;
-    readonly ViewportSurface: typeof VectorCanvasViewportSurface;
-    readonly Toolbar: typeof VectorCanvasToolbar;
-    readonly Space: typeof VectorCanvasSpace;
-    readonly NavMenu: typeof NavMenu;
-    readonly SelectionInspector: typeof VectorSelectionInspector;
+type IngestAssetFilesToSceneItemsOptions = {
+    files: readonly File[];
+    worldCenter: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Optional binary persistence bridge shared with `VectorViewport`.
+     *
+     * When provided, `upload(...)` is called once per source file before canvu
+     * converts that file into one or more scene items.
+     */
+    assetStore?: VectorViewportAssetStore;
+    /**
+     * Optional local blob store used to keep canvu's default image/PDF runtime
+     * behavior consistent across reload-safe persistence adapters.
+     *
+     * Omit this unless you need to share an existing store instance.
+     */
+    imageStore?: IndexedDbImageStore;
+    /**
+     * Optional custom id factory for imported items.
+     *
+     * Defaults to `createShapeId()`.
+     */
+    createId?: () => string;
+    /**
+     * Vertical gap between stacked PDF pages.
+     *
+     * Defaults to `16`, matching the built-in viewport flow.
+     */
+    gapWorld?: number;
+    /**
+     * Offset step used when placing standalone raster images.
+     *
+     * Defaults to `48`, matching the built-in viewport flow.
+     */
+    stepWorld?: number;
+    /**
+     * PDF rasterization scale forwarded to `pdfjs-dist`.
+     *
+     * Defaults to `1.5` for crisp zoom while keeping payloads reasonable.
+     */
+    pdfScale?: number;
+    /**
+     * Final hook to customize each created item after canvu attaches its own
+     * image metadata and any `assetStore.upload(...)` `pluginData`.
+     */
+    decorateItem?: (item: VectorSceneItem, context: IngestedAssetItemContext) => VectorSceneItem;
+    /**
+     * Optional side-channel for per-file errors.
+     *
+     * This is useful for toasts or telemetry in addition to reading the returned
+     * `errors` array.
+     */
+    onError?: (error: IngestAssetFileError) => void;
 };
-
 /**
- * Floating bottom-bar combining zoom controls, undo/redo, and an expandable minimap.
- * When rendered inside `VectorViewport` (e.g. via the `navMenu` slot), data props default
- * to values from {@link CanvuChromeContext}; pass any prop to override.
+ * Result of {@link ingestAssetFilesToSceneItems}.
  */
-type NavMenuProps = {
-    camera?: Camera2D;
-    viewportWidth?: number;
-    viewportHeight?: number;
-    items?: readonly VectorSceneItem[];
-    zoomPercent?: number;
-    onZoomIn?: () => void;
-    onZoomOut?: () => void;
-    onUndo?: () => void;
-    onRedo?: () => void;
-    canUndo?: boolean;
-    canRedo?: boolean;
-    onRequestRender?: () => void;
-    /** Anchor preset. Defaults to bottom-left. */
-    position?: BoardComponentPosition;
-    /** Distance (px) from anchored edges. @default 12 */
-    inset?: number;
-    /** @default 23 */
-    zIndex?: number;
-    className?: string;
-    /** Merged on top of position-derived styles for custom tweaks. */
-    style?: CSSProperties;
+type IngestAssetFilesToSceneItemsResult = {
+    items: VectorSceneItem[];
+    errors: IngestAssetFileError[];
 };
-declare function NavMenu({ camera: cameraProp, viewportWidth: viewportWidthProp, viewportHeight: viewportHeightProp, items: itemsProp, zoomPercent: zoomPercentProp, onZoomIn: onZoomInProp, onZoomOut: onZoomOutProp, onUndo: onUndoProp, onRedo: onRedoProp, canUndo: canUndoProp, canRedo: canRedoProp, onRequestRender: onRequestRenderProp, position, inset, zIndex, className, style, }: NavMenuProps): react_jsx_runtime.JSX.Element;
+/**
+ * Converts browser files into `VectorSceneItem[]` using the same ingestion
+ * pipeline as canvu's built-in file flow.
+ *
+ * Use this for external imports that should behave like the native canvas
+ * upload experience without reimplementing PDF rasterization, image storage, or
+ * `pluginData` attachment in app code.
+ *
+ * Do not use this as a persistence layer by itself. It only produces runtime
+ * scene items. Persist the resulting snapshot with your existing
+ * `useVectorCanvasDocument(...)` adapter or another app-specific document store.
+ */
+declare function ingestAssetFilesToSceneItems(options: IngestAssetFilesToSceneItemsOptions): Promise<IngestAssetFilesToSceneItemsResult>;
 
 /**
  * Persistence adapter that stores the document JSON in IndexedDB and manages
@@ -478,4 +410,4 @@ type ViewportZoomControlsProps = {
  */
 declare function ViewportZoomControls({ zoomPercent, onZoomIn, onZoomOut, className, position, inset, zIndex, style, }: ViewportZoomControlsProps): react_jsx_runtime.JSX.Element;
 
-export { type BoardComponentPosition, CanvasPlugin, type CanvuChromeActiveToolStyle, CanvuChromeContext, type CanvuChromeContextValue, type CanvuChromeSelectionStyleChange, type CreateLocalStoragePersistenceAdapterOptions, type CreateToolPluginOptions, DEFAULT_OVERFLOW_TOOL_IDS, DEFAULT_VECTOR_CANVAS_STORAGE_KEY, DEFAULT_VECTOR_TOOLS, IconArrow, IconDraw, IconEllipse, IconHand, IconImage, IconLaser, IconLine, IconRect, IconSelect, IconText, NavMenu, type NavMenuProps, ShapeContextMenu, type ShapeContextMenuProps, type UseVectorCanvasDocumentOptions, type UseVectorCanvasDocumentResult, VectorCanvas, VectorCanvasBody, VectorCanvasHeader, VectorCanvasMain, VectorCanvasPersistenceAdapter, VectorCanvasRemoteAdapter, VectorCanvasRoot, type VectorCanvasSlotProps, type VectorCanvasSpacePosition, type VectorCanvasSpaceProps, VectorCanvasToolbar, type VectorCanvasToolbarProps, VectorCanvasViewportSurface, VectorSelectionInspector, type VectorSelectionInspectorProps, VectorToolDefinition, VectorToolbar, type VectorToolbarProps, type VectorToolbarRenderContext, ViewportZoomControls, type ViewportZoomControlsProps, createIndexedDbPersistenceAdapter, createLocalStoragePersistenceAdapter, createNoopPersistenceAdapter, createToolPlugin, cursorForVectorToolId, getBoardPositionStyle, useCanvuChromeContext, useVectorCanvasDocument };
+export { BoardComponentPosition, CanvasPlugin, type CreateLocalStoragePersistenceAdapterOptions, type CreateToolPluginOptions, DEFAULT_OVERFLOW_TOOL_IDS, DEFAULT_VECTOR_CANVAS_STORAGE_KEY, DEFAULT_VECTOR_TOOLS, IconArrow, IconDraw, IconEllipse, IconHand, IconImage, IconLaser, IconLine, IconRect, IconSelect, IconText, type IngestAssetFileError, type IngestAssetFilesToSceneItemsOptions, type IngestAssetFilesToSceneItemsResult, type IngestedAssetItemContext, ShapeContextMenu, type ShapeContextMenuProps, type UseVectorCanvasDocumentOptions, type UseVectorCanvasDocumentResult, VectorCanvasPersistenceAdapter, VectorCanvasRemoteAdapter, VectorToolDefinition, VectorToolbar, type VectorToolbarProps, type VectorToolbarRenderContext, VectorViewportAssetKind, VectorViewportAssetStore, ViewportZoomControls, type ViewportZoomControlsProps, createIndexedDbPersistenceAdapter, createLocalStoragePersistenceAdapter, createNoopPersistenceAdapter, createToolPlugin, cursorForVectorToolId, ingestAssetFilesToSceneItems, useVectorCanvasDocument };