Editors / Canvas

Canvas

The infinite surface under every editor: camera, grid, selection, history. Items are yours.

Package
@forgeron/canvas
Layers
core (no React) · /react
Used by
@forgeron/flow · @forgeron/draw · data hub schema
Locked frame
Triggeron.record
Fetchhttp.get
If
Writedb.insert
Notifymail.send
NoteDrag me, resize me, nudge me.

Spacedrag to pan⌘wheelzoom⌥drag a lasso⌘Zundo

/01 → What it covers
  • An infinite surface: wheel pans, ⌘ or Ctrl + wheel and pinch zoom, Space-drag or middle-drag pan.
  • Select: click, Shift-click to toggle, drag a box, Alt-drag a lasso, ⌘A.
  • Move, resize from eight handles, nudge with the arrows (Shift: 10). Snaps to the 20 px grid; Alt frees it.
  • Undo and redo of patches: a whole drag, or a run of nudges, is one step.
  • Duplicate, copy, cut and paste; JSON with a version field.
  • Zoom presets, zoom to fit, a minimap, the zoom controls built from @forgeron/ui.
  • Focusable surface, items in a listbox reached with Tab, selection announced, no glide under reduced motion.
/02 → Use it
/01 → A canvas with your items
import "@forgeron/canvas/styles.css";
import { Canvas, Minimap, useCanvasStore, ZoomControls } from "@forgeron/canvas/react";

export function Board({ items }) {
  const store = useCanvasStore({ items, kinds: { card: { resize: { minW: 120 } } } });
  return (
    <Canvas store={store} label="Board" renderItem={(item) => <Card {...item.data} />}>
      <ZoomControls history />
      <Minimap />
    </Canvas>
  );
}
/02 → The headless core, without React
import { createCanvasStore } from "@forgeron/canvas";

// Named commands over the engine interface: dispatch(command) and query(question), plain data.
const store = createCanvasStore({ items: saved.items, grid: { size: 20 } });
store.query({ type: "hit", point: { x: 120, y: 40 } });
store.select(["a", "b"]);
store.nudge(10, 0);          // one undo step for a run of nudges
store.duplicateSelection();
store.undo();
const json = store.serialize({ viewport: true }); // { "version": 1, "items": [...] }
/03 → A kind and a tool of your own
const kinds = {
  ellipse: {
    hitTest: (item, p) => insideEllipse(item.bounds, p),
    resize: { keepAspect: true, minW: 20, minH: 20 },
  },
};

const rectangle = {
  id: "rect",
  label: "Rectangle",
  shortcut: "r",
  cursor: "crosshair",
  down(pointer, { store, snap }) {
    const start = snap(pointer.world, pointer);
    store.beginGesture("Draw");
    const [item] = store.add({ kind: "rect", bounds: { ...start, w: 1, h: 1 }, data: {} });
    return {
      move: (p) => store.resize(item.id, rectFromPoints(start, snap(p.world, p))),
      up: () => { store.endGesture(); store.setTool("select"); },
      cancel: () => store.cancelGesture(),
    };
  },
};

const store = useCanvasStore({ kinds });
<Canvas store={store} tools={[rectangle]} label="Whiteboard" renderItem={render} />
/03 → Keys
Nudge left←
Nudge right→
Nudge up↑
Nudge down↓
Nudge left by 10⇧←
Nudge right by 10⇧→
Nudge up by 10⇧↑
Nudge down by 10⇧↓
Delete⌫
Select all⌘A
DeselectEsc
Undo⌘Z
Redo⌘⇧Z
Duplicate⌘D
Copy⌘C
Cut⌘X
Paste⌘V
Zoom in=
Zoom out-
Zoom to 100 %0
Zoom to fit1
Zoom to selection2
Select toolV
Hand toolH
Bring to front⌘]
Send to back⌘[
API → <Canvas>
NameTypeDefaultDescription
storeCanvasStore<D>—From useCanvasStore or createCanvasStore.
renderItem(item, { selected }) => ReactNode—Draws one item inside its positioned box.
labelstring—Names the surface for assistive technology.
primitive(item) => Primitive | null—The shape the renderer draws under the overlay.
renderer() => CanvasRenderercreateDomRendererDraws grid, shapes and selection from a Scene; stable.
itemLabel(item) => string<kind> <id>Names an item for assistive technology.
toolsCanvasTool[]—Consumer tools; select and pan are built in.
layers{ below?, above? }—World-space layers: edges, guides, previews.
childrenReactNode—Screen-space chrome: ZoomControls, Minimap, toolbars.
keyboard"focus" | "page" | false"focus"Where the canvas keys listen.
wheel"pan" | "zoom""pan"What the plain wheel does.
boxMode"intersect" | "contain""intersect"What a box selects.
nudge{ small, large }{ 1, 10 }World units of an arrow, and with Shift.
onConnect(from, to, point) => void—End of a drag started on a data-canvas-handle.
canConnect(from, to) => boolean—Whether a target is valid while connecting.
onItemActivate(item) => void—Double click or Enter on an item.
onSurfaceDoubleClick(point) => void—Double click on the empty surface.
onContextMenu(item | null, point, event) => void—Right click; the item is selected first.
API → createCanvasStore(options)
NameTypeDefaultDescription
itemsItem<D>[]—{ id, kind, bounds: { x, y, w, h }, z, locked?, data }.
kindsKindMap<D>—Per kind: hitTest, resize, movable, selectable, duplicate.
grid{ size, snap, visible }{ 20, true, true }The pixel grid.
zoom{ min, max, presets }0.1 – 4Limits and the stops of the buttons.
viewport{ x, y, zoom }—The first camera.
historyLimitnumber200Undo steps kept.
readOnlybooleanfalseSelect and pan only.
createId(kind, exists) => string<kind>-<n>Ids of new items; no randomness.
API → Store commands
NameTypeDefaultDescription
add · update · updateMany · remove · apply→ one undo step each—Change the document.
beginGesture · endGesture · cancelGesture——Group a drag into one undo step, or drop it.
select · selectAll · clearSelection(ids, mode?)—replace, add, toggle, remove.
moveBy · nudge · resize——Locked and unmovable items stay put.
duplicateSelection · copy · cut · paste——Copies one cell away; paste at a point.
bringToFront · sendToBack · undo · redo——Stacking and history.
zoomIn · zoomOut · zoomTo · resetZoom · fitView · centerOnItem——The camera, kept on whole pixels.
setTool · setConnection——The tool state and the connect gesture.
serialize · loadJSON——JSON with a version field.
API → <ZoomControls> · <Minimap>
NameTypeDefaultDescription
toolsbooleantrueZoomControls: the select and hand segments.
historybooleanfalseZoomControls: undo and redo buttons.
fitMaxZoomnumber1ZoomControls: fit never zooms past it.
width · heightnumber180 · 112Minimap: its size in CSS pixels.
colorOf(item) => string—Minimap: a colour or token per item.
API → Hooks
NameTypeDefaultDescription
useCanvasStore(options)CanvasStore<D>—Creates the store once.
useCanvas(){ store, items, selection, viewport, tool, … }—Inside <Canvas> or <CanvasProvider>.
useCanvasState(store, select)T—One slice, re-rendering only when it changes.
useConnection()Connection | null—The wire being drawn, for a preview.