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
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>
);
}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": [...] }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>
| Name | Type | Default | Description |
|---|---|---|---|
store | CanvasStore<D> | — | From useCanvasStore or createCanvasStore. |
renderItem | (item, { selected }) => ReactNode | — | Draws one item inside its positioned box. |
label | string | — | Names the surface for assistive technology. |
primitive | (item) => Primitive | null | — | The shape the renderer draws under the overlay. |
renderer | () => CanvasRenderer | createDomRenderer | Draws grid, shapes and selection from a Scene; stable. |
itemLabel | (item) => string | <kind> <id> | Names an item for assistive technology. |
tools | CanvasTool[] | — | Consumer tools; select and pan are built in. |
layers | { below?, above? } | — | World-space layers: edges, guides, previews. |
children | ReactNode | — | 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)
| Name | Type | Default | Description |
|---|---|---|---|
items | Item<D>[] | — | { id, kind, bounds: { x, y, w, h }, z, locked?, data }. |
kinds | KindMap<D> | — | Per kind: hitTest, resize, movable, selectable, duplicate. |
grid | { size, snap, visible } | { 20, true, true } | The pixel grid. |
zoom | { min, max, presets } | 0.1 – 4 | Limits and the stops of the buttons. |
viewport | { x, y, zoom } | — | The first camera. |
historyLimit | number | 200 | Undo steps kept. |
readOnly | boolean | false | Select and pan only. |
createId | (kind, exists) => string | <kind>-<n> | Ids of new items; no randomness. |
API → Store commands
| Name | Type | Default | Description |
|---|---|---|---|
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>
| Name | Type | Default | Description |
|---|---|---|---|
tools | boolean | true | ZoomControls: the select and hand segments. |
history | boolean | false | ZoomControls: undo and redo buttons. |
fitMaxZoom | number | 1 | ZoomControls: fit never zooms past it. |
width · height | number | 180 · 112 | Minimap: its size in CSS pixels. |
colorOf | (item) => string | — | Minimap: a colour or token per item. |
API → Hooks
| Name | Type | Default | Description |
|---|---|---|---|
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. |