@invisionapp/shared-studio-canvas

Canvas

There are two main exports to this package CanvasProvider and Canvas. CanvasProvider makes use of the React Context API and must wrap the Canvas component in your app to work appropriately. The only other requirement is to call setProject with your UdfProject/Proxy to get your Canvas to render.

Example:

import { Canvas, CanvasProvider } from '@invisionapp/studio-runtime/canvas';

render() {
  return (
    <App>
      <CanvasProvider>
        ...
        <Canvas assets={ images: {} } />
        ...
      </CanvasProvider>
    </App>
  );
}

API

Custom types can be reviewed here

Components

CanvasProvider - Context-API provider to wrap the use of Canvas and any hooks.

props:

• children: ReactNode
• options?: { selectedLayersAsHovered?: boolean }

Canvas - Component for rendering project data, must call setProject within useProjectActions for rendering to happen

props:

• assets: { images: { [id: string]: ImageElment } }
• canvasCallbackRef: callback ref for getting canvas element
• onFirstRender: () => void; - function called on first render
• onMarkupReady: () => void; - function called when markup is ready for rendering

CanvasAnchor - Component which attaches any descendents to the canvas with a specific location

props:

• id: string
• x: number - X position on the canvas to attach to
• y: number - Y position on the canvas to attach to
• children: ReactNode
• options?: CanvasComponentOptions
• position?: CanvasPositionOptions
• style?: CSSProperties

CanvasPin - Component which attaches any descendents to a layer with specific offsets

props:

• id: string
• layerId: string - ID of the layer to attach to attach to on the canvas
• children: ReactNode
• options?: CanvasComponentOptions
• position?: CanvasPositionOptions
• style?: CSSProperties

Hooks

useProjectData - hook for getting project related data

• project: UdfProject; // Proxy
• page: UdfPage;
• prototype: UdfPrototype;
• homeArtboardId: string;

useProjectActions - hook for getting project related actions

• setProject: (project: UdfProject, options?: ProjectOptions) => void;
• setLayersWithOffset: (layerId: string, position: Coordinate) => void; // currently mutates the project directly
• setLayerPositions: (layerPositions: LayerPositions) => void; // currently mutates the project directly
• setPageId: (pageId: string) => void;

useCanvasSelectionData - hook for getting the currently hovered and selected items

• hoveredItems: CanvasItem[];
• hoveredComponentItems: ComponentCanvasItem[];
• hoveredMarkupItems: MarkupCanvasItem[];
• hoveredLayerItems: LayerCanvasItem[];
• selectedItems: CanvasItem[];
• selectedComponentItems: ComponentCanvasItem[];
• selectedMarkupItems: MarkupCanvasItem[];
• selectedLayerItems: LayerCanvasItem[];

useCanvasSelectionActions - hook for getting hover and selection related actions

• setHoveredItems: (items: CanvasItemIdentifier[]) => void;
• removeHoveredItem: (item: CanvasItemIdentifier) => void;
• clearHoveredItems: () => void;
• setSelectedItems: (items: CanvasItemIdentifier[]) => void;
• addSelectedItem: (item: CanvasItemIdentifier) => void;
• removeSelectedItem: (item: CanvasItemIdentifier) => void;
• clearSelectedItems: () => void;

useCamera: Camera - hook that returns a Camera object

useCameraActions - hook for getting camera related actions

• animateZoomIn: () => void;
• animateZoomOut: () => void;
• setCamera: (camera: Camera) => void;
• setZoom: (scale: number) => void;
• zoomToFit: (layer: any, options?: any) => void;
• panToPoint: (point: Coordinate) => void;

useTool: ToolApi - hook for getting current tool

useCursor: string - hook for getting current cursor

useToolActions - hook for getting tool related actions

• setTool: (tool: ToolApi) => void;
• setCursor: (cursor: string) => void;

useCanvasOptions - hook for getting canvas related options

• pickwhips: boolean;
• selectedLayersAsHovered: boolean;

useCanvasActions - hook for getting canvas related actions

• setPickwhips: (pickwhips: boolean) => void;
• setSelectedLayersAsHovered: (selectedLayersAsHovered: boolean) => void;

Tools

Tools for the canvas must be built with the following API:

{
  name: string;
  defaultCursor: string;
  keyDown(payload: KeyboardEventPayload): void;
  keyUp(payload: KeyboardEventPayload): void;
  mouseDown(payload: MouseEventPayload): void;
  mouseMove(payload: MouseEventPayload): void;
  mouseUp(payload: MouseEventPayload): void;
  wheel(payload: WheelEventPayload): void;
}

Keyboard, Mouse, and Wheel payloads include access to all CanvasProvider data & actions

Pan - tool for panning the canvas

Zoom - tool for zooming the canvas

Utilities

getScarletPreviewer - function that returns the ScarletPreviewerApi instance