@casmadev/board

A React whiteboard component built with DOM + CSS — no <canvas>. Sticky notes with a handwritten font, slight 3D tilt that responds to camera motion, infinite pan & zoom, multilingual UI (8 shipped locales including RTL), and full TypeScript types.

import { CasmaBoard } from '@casmadev/board';
import '@casmadev/board/styles.css';

export default function App() {
  return <CasmaBoard />;
}

Install

npm install @casmadev/board

Peer dependencies: react >=18, react-dom >=18. The package itself ships with zero runtime deps.

Don't forget the stylesheet:

import '@casmadev/board/styles.css';

Quick start

import { CasmaBoard } from '@casmadev/board';
import { ptBR } from '@casmadev/board/locales';
import '@casmadev/board/styles.css';

export default function App() {
  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <CasmaBoard
        messages={ptBR}
        background="grid"
        snapToGrid
      />
    </div>
  );
}

Props

All optional. The component is uncontrolled by default but accepts controlled state for shapes and camera.

| Prop | Type | Default | What it does | | --- | --- | --- | --- | | shapes / defaultShapes | ShapesState | empty | Controlled or seeded shape state ({ shapes: Record<id, Shape>, order: string[] }). | | onShapesChange | (next: ShapesState) => void | — | Fires on every shape mutation. | | camera / defaultCamera | Camera | { x: 0, y: 0, zoom: 1 } | Controlled or seeded camera. | | onCameraChange | (next: Camera) => void | — | Fires on pan/zoom. | | messages | Partial<Messages> | en defaults | UI strings (toolbar labels, color names, ARIA, hints). Deep-merged with the English defaults. | | direction | 'ltr' \| 'rtl' | 'ltr' | Sets dir on the root; toolbar position + logical CSS flip automatically. | | background | 'dots' \| 'grid' \| 'none' | 'dots' | Infinite backdrop style. Pans & zooms with the camera. | | snapToGrid | boolean | false | Snap created/dragged shape positions to the 24px grid. | | textOverflow | 'shrink-to-fit' \| 'truncate' | 'shrink-to-fit' | Sticky text behavior when content exceeds the note. Shrink auto-fits the font; truncate keeps a fixed font and appends …. | | depth3d | number | 800 | CSS perspective (px) for the sticky tilt. Smaller = stronger perspective. 0 disables 3D. | | hideUI | boolean | false | Hide every default UI surface — slots, default toolbar, context menu. | | generateId | () => string | crypto.randomUUID | Inject a deterministic id generator (useful for SSR / tests). | | className, style | — | — | Passed to the root container. | | shapeKinds | ShapeKind<any>[] | defaultShapeKinds (sticky only) | Plugin array of shape types the board knows how to render and create. See Customization. | | defaultTool | ToolId | 'select' | Initial tool. Either 'select' or any shape kind's tool id. | | slots | Slots | {} | Seven overlay slots — see Slots. Three ship defaults (DefaultToolbar, DefaultZoomWidget, DefaultEmptyHint); omit a key to keep the default, pass null to suppress it. | | contextMenu | (props) => ReactNode | DefaultContextMenu | Render function for the per-shape context menu. |

Internationalization

The component never imports a translation framework — it takes a messages prop and ships locales as named exports.

import { CasmaBoard } from '@casmadev/board';
import { es, ja, ar } from '@casmadev/board/locales';

Shipped locales: en, es, fr, ptBR, de, ja, ar, he. Each is its own subpath export so unused languages tree-shake. RTL is handled by direction="rtl" plus CSS logical properties; the included Arabic and Hebrew locales are paired with this.

Partial overrides are fine — missing keys fall back to English:

<CasmaBoard messages={{ toolbar: { delete: 'Yeet' } }} />

Theming

Every paintable surface is driven by CSS variables defined on .cb-root. Override any of them in your own stylesheet:

.cb-root {
  --cb-bg: #1a1a1a;
  --cb-grid: rgba(255, 255, 255, 0.08);
  --cb-text: #f5f5f5;
  --cb-accent: #f97316;

  --cb-sticky-yellow: #ffd95e;
  --cb-sticky-pink:   #ff9bb3;
  --cb-sticky-blue:   #8ec5ff;
  --cb-sticky-green:  #a8e063;
  --cb-sticky-purple: #c4a7ff;

  --cb-sticky-font: 'Caveat', 'Bradley Hand', cursive;
}

All class names are prefixed cb- to avoid collisions.

Customization

The canvas is fully composable. Every default surface (toolbar, context menu, the sticky note itself) is a plug-in you can replace, and there are seven overlay slots for dropping your own chrome anywhere on the board.

Easy default

import { CasmaBoard } from '@casmadev/board';
import '@casmadev/board/styles.css';

<CasmaBoard />
// ↑ sticky note + default toolbar in bottom-center. Nothing to wire up.

Custom shape kinds

A shape kind is a small object describing how to create + render one shape type. Pass an array of them to shapeKinds:

import {
  CasmaBoard,
  defaultShapeKinds,
} from '@casmadev/board';
import type { ShapeKind, ShapeRenderProps } from '@casmadev/board';

interface BoxShape {
  id: string;
  type: 'box';
  x: number;
  y: number;
  w: number;
  h: number;
  label: string;
}

function BoxRenderer({ shape, pointerHandlers, onSelect, className }: ShapeRenderProps<BoxShape>) {
  return (
    <div
      className={className}           // opts into cb-shape baseline + selected/editing/dragging state classes
      data-shape-id={shape.id}      // required: identifies this DOM node as a shape
      style={{ left: shape.x, top: shape.y, width: shape.w, height: shape.h, background: 'tomato' }}
      tabIndex={0}
      onFocus={onSelect}
      {...pointerHandlers}            // wire drag + select
    >
      {shape.label}
    </div>
  );
}

const boxKind: ShapeKind<BoxShape> = {
  type: 'box',
  defaultSize: { w: 140, h: 80 },
  create: (id, x, y) => ({ id, type: 'box', x: x - 70, y: y - 40, w: 140, h: 80, label: 'Box' }),
  Component: BoxRenderer,
  toolButton: { icon: <BoxIcon />, label: 'Box' },   // optional: registers a toolbar button
};

<CasmaBoard shapeKinds={[...defaultShapeKinds, boxKind]} />

Your renderer receives selected, editing, editVersion, patch, onSelect, onStartEdit, onCommitEdit, onCancelEdit, and a pre-composed className — everything you need to participate in the board's lifecycle. Spreading className onto your root opts the shape into the shared cb-shape baseline (absolute positioning, grab/grabbing cursor, transitions) plus state modifiers (cb-shape--selected, cb-shape--editing, cb-shape--dragging); you can compose your own classes alongside. The board itself never reads your shape's extra fields; you own how they're stored and rendered.

Slots

Seven fixed overlays anchored over the viewport — six corners/edges plus a centered overlay for empty-state hints and onboarding affordances. Each accepts any ReactNode. The wrapper is transparent to pointer events; only your content captures clicks.

<CasmaBoard
  slots={{
    topLeft:     <MyTitleBar />,
    topCenter:   <MyBreadcrumbs />,
    topRight:    <MyDemoControls />,
    center:      <MyOnboarding />,       // overrides the DefaultEmptyHint
    bottomLeft:  <MyStatusChip />,
    bottomCenter: <MyCustomToolbar />,   // overrides the DefaultToolbar
    bottomRight: <MyZoomWidget />,       // overrides the DefaultZoomWidget
  }}
/>

Three slots ship with defaults — same omit/replace/suppress convention each:

| Slot | Default | Notes | | --- | --- | --- | | bottomCenter | DefaultToolbar | Tool picker. Two opt-in creation flows — see below. | | bottomRight | DefaultZoomWidget | − / % / +. The percentage is clickable and snaps to 100%. | | center | DefaultEmptyHint | Localized "click to add a note" hint that self-suppresses once any shape exists. |

For each: omit the key → default renders, pass null → slot is suppressed, pass any value → that value renders. hideUI short-circuits all three.

DefaultToolbar props

Both default false/true and are wholly owned by the toolbar — the board itself stays agnostic so a custom toolbar can implement its own policy.

| Prop | Default | What it does | | --- | --- | --- | | dragToCreate | true | Press a kind button and drag onto the canvas to create the shape at the release point. A pure tap still sets the tool (two-step flow stays intact). | | clickToCreate | false | Click a kind button to immediately spawn the shape at the viewport center (snap-to-grid still applies). The button becomes a one-shot spawner — no active state, no dragToCreate. |

import { CasmaBoard, DefaultToolbar } from '@casmadev/board';

<CasmaBoard
  slots={{ bottomCenter: <DefaultToolbar clickToCreate /> }}
/>

Custom slot content can drive the board via the useCasmaBoard() hook:

import { useCasmaBoard } from '@casmadev/board';

function ZoomReadout() {
  const { camera, setCamera } = useCasmaBoard();
  return (
    <button onClick={() => setCamera(c => ({ ...c, zoom: 1 }))}>
      {Math.round(camera.zoom * 100)}%
    </button>
  );
}

The hook returns tool, setTool, camera, setCamera, shapes, setShapes, shapeKinds, messages, direction, selectedId, selectedShape, setSelectedId, editingId, setEditingId, patchShape, removeShape, addShape, and viewportRef.

Custom context menu

Override the per-shape context menu with a single render function. It's called whenever a shape is selected (and not being edited) — branch on shape.type to handle each kind.

<CasmaBoard
  contextMenu={({ shape, camera, patch, remove }) => (
    <div style={{ position: 'absolute', left: 0, top: 0 }} onPointerDown={e => e.stopPropagation()}>
      <button onClick={remove}>Delete {shape.type}</button>
    </div>
  )}
/>

DefaultContextMenu is exported too — wrap it, delegate to it, or copy the source as a starting point.

Composable defaults

Every default surface is exported individually so you can mix-and-match:

import {
  DefaultToolbar,           // bottom-center tool picker
  DefaultZoomWidget,        // bottom-right zoom (−/%/+)
  DefaultEmptyHint,         // center empty-state hint
  DefaultContextMenu,       // sticky color picker + delete
  ColorPicker,              // sticky color swatches
  stickyKind,               // the built-in sticky ShapeKind
  defaultShapeKinds,        // [stickyKind]
  StickyNote, StickyIcon,   // sticky's renderer + icon
} from '@casmadev/board';

Behavior summary

• Pan: middle-mouse drag, Space + primary drag, or two-finger trackpad scroll.
• Zoom: Cmd/Ctrl + wheel (macOS pinch arrives as ctrl-wheel). Anchors at the cursor.
• Sticky tool → click canvas: drops a new note at the cursor.
• Double-click sticky: edit in place. The note lifts off the canvas with a smooth transition and the rotation rerolls slightly when you click away — like picking it up and putting it back.
• Selected sticky: context menu pops up under the note with color swatches and the trash button.
• Wheel over editing text: scrolls the text instead of panning the canvas.
• Delete: Backspace / Delete on the selected shape, or the trash button.

Development

git clone …
npm install
npm run dev          # boots the Vite playground at http://localhost:5173
npm test             # vitest
npm run typecheck    # tsc --noEmit
npm run build        # rollup → dist/

The playground (examples/playground/) aliases @casmadev/board to the source so HMR hits TypeScript directly — no rebuild loop.

License

MIT