@uniwertz/react-board-canvas

Reusable board/canvas component with ReactFlow, multi-select, and position saving.

Installation

npm install @uniwertz/react-board-canvas

Peer Dependencies

This package requires the following peer dependencies:

npm install react react-dom @xyflow/react

Usage

Basic Board

import { BoardCanvas, BaseCardNode, useBoardHandlers } from '@uniwertz/react-board-canvas';

// Custom node component
const MyCardNode = ({ data }) => (
  <BaseCardNode>
    <h3>{data.title}</h3>
    <p>{data.description}</p>
  </BaseCardNode>
);

// Register node types
const nodeTypes = {
  myCard: MyCardNode,
};

function MyBoard({ items, onSavePositions }) {
  const { nodes, onNodesChange, handlers } = useBoardHandlers({
    items,
    itemToNode: (item) => ({
      id: `item-${item.id}`,
      type: 'myCard',
      position: { x: item.x || 0, y: item.y || 0 },
      data: item,
    }),
    onSavePositions,
  });

  return (
    <div style={{ width: '100%', height: '600px' }}>
      <BoardCanvas
        nodes={nodes}
        onNodesChange={onNodesChange}
        nodeTypes={nodeTypes}
        onNodeDragStop={handlers.onNodeDragStop}
      />
    </div>
  );
}

With Selection

import { useBoardSelection } from '@uniwertz/react-board-canvas';

function MyBoardWithSelection({ items }) {
  const selection = useBoardSelection();

  const handleNodeClick = (event, node) => {
    selection.selectNode(node.id, event);
  };

  // ... rest of the board setup

  return (
    <BoardCanvas
      // ...
      onNodeClick={handleNodeClick}
      onPaneClick={selection.clearSelection}
    />
  );
}

Components

BoardCanvas

Main ReactFlow wrapper component.

Props:

• nodes - Array of ReactFlow nodes
• edges - Array of ReactFlow edges (optional)
• onNodesChange - Node change handler
• onEdgesChange - Edge change handler (optional)
• onNodeClick - Node click handler
• onNodeDoubleClick - Node double-click handler
• onPaneClick - Pane click handler
• nodeTypes - Custom node types
• readOnly - Disable editing
• defaultViewport - Initial viewport

BaseCardNode

Base component for card nodes.

Props:

• children - Card content
• className - Additional CSS class
• selected - Selection state
• dragging - Dragging state
• showHandles - Show connection handles
• dragHandleClassName - Custom drag handle class

Hooks

useBoardHandlers

Hook for managing board node positions with automatic saving.

const { nodes, onNodesChange, handlers, updateFromItems } = useBoardHandlers({
  items: myItems,
  itemToNode: (item) => ({ ... }),
  onSavePositions: async (positions) => { ... },
  saveDebounceMs: 300,
});

useBoardSelection

Hook for managing node selection.

const {
  selectedIds,
  selectNode,
  clearSelection,
  toggleSelection,
  isSelected,
} = useBoardSelection();

useBoardStore

Zustand store for centralized board state.

const { nodes, setNodes, viewport, setViewport } = useBoardStore();

Utilities

calculateCenterPosition

Calculate center position for new nodes.

const center = calculateCenterPosition(existingNodes, viewport);

convertToNodes

Convert generic items to ReactFlow nodes.

const nodes = convertToNodes(items, {
  getId: (item) => `item-${item.id}`,
  getPosition: (item) => ({ x: item.x, y: item.y }),
  nodeType: 'myCard',
});

License

MIT