npm package: @jeevandev/flow-canvas
Description: A performant page-based design canvas library for React
Latest version: 0.1.6

# @jeevandev/flow-canvas

A powerful, production-ready, page-based canvas editor library for React. Build interactive design experiences like Figma/Canva with drag, resize, rotate, grouping, and multi-page support.

[![NPM Version](https://img.shields.io/npm/v/@jeevandev/flow-canvas)](https://www.npmjs.com/package/@jeevandev/flow-canvas)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)

## ✨ Features

- 🎨 **Multi-Page Canvas** - Create and manage multiple pages with smooth scrolling
- 🖱️ **Interactive Elements** - Drag, resize, rotate with smooth interactions
- 📏 **Smart Snapping & Margins** - Visual snap guides and customizable page margins
- 🔄 **Cross-Page Dragging** - Move elements between pages with ghost preview
- 👥 **Grouping** - Group/ungroup elements with professional editing mode
- 🎯 **Multi-Selection** - Select and manipulate multiple elements
- ⌨️ **Keyboard Shortcuts** - Full keyboard support (Undo/Redo, Copy/Paste, etc.)
- 🔍 **Zoom & Pan** - Smooth zoom controls
- ⚡ **High Performance** - Viewport culling and virtualization for large datasets

- ♿ **Accessible** - ARIA labels and keyboard navigation support
- 📦 **TypeScript** - Full type safety and IntelliSense support
- 🎨 **Customizable** - Extensive configuration options and theming

## 📦 Installation

```bash
npm install @jeevandev/flow-canvas
```

## 🚀 Quick Start

```tsx
import { Editor, Canvas } from "@jeevandev/flow-canvas";
import "@jeevandev/flow-canvas/style.css";

function App() {
  const initialPages = [
    {
      id: "page-1",
      width: 1920,
      height: 1080,
      name: "Page 1",
      backgroundColor: "#ffffff",
    },
  ];

  return (
    <Editor
      initialPages={initialPages}
      config={{
        snapping: true,
        snapGuide: true,
        showGrid: true,
        gridSize: 20,
      }}
    >
      <Canvas />
    </Editor>
  );
}
```

## 📖 Documentation

Complete documentation is available in the [`docs/`](./docs/) directory:

- **[Getting Started](./docs/getting-started.md)** - Installation and basic usage
- **[API Reference](./docs/api.md)** - Complete API documentation
- **[Configuration](./docs/configuration.md)** - Configuration options
- **[Advanced Usage](./docs/advanced.md)** - Advanced features and customization
- **[Architecture](./docs/architecture.md)** - Architecture overview
- **[Examples](./docs/examples/examples.md)** - Code examples and recipes

See [docs/README.md](./docs/README.md) for the complete documentation index.

## 🎯 Core Concepts

### Pages

Pages are the containers for your design elements. Each page has dimensions, background color, and can contain multiple elements.

```tsx
const pages = [
  {
    id: "page-1",
    width: 1920,
    height: 1080,
    backgroundColor: "#ffffff",
    name: "Home Page",
  },
];
```

### Nodes (Elements)

Nodes are the interactive elements on your canvas. They can be dragged, resized, rotated, and grouped.

```tsx
const nodes = [
  {
    id: "node-1",
    x: 100,
    y: 100,
    width: 200,
    height: 100,
    pageId: "page-1",
    draggable: true,
    resizable: true,
    rotatable: true,
    data: { label: "My Element" },
  },
];
```

### Configuration

Customize the editor behavior with the `config` prop:

```tsx
<Editor
  config={{
    snapping: true,        // Enable snapping
    snapGuide: true,        // Show snap guides
    showGrid: true,         // Show grid
    gridSize: 20,          // Grid size in pixels
    pageWidth: 1920,       // Default page width
    pageHeight: 1080,      // Default page height
    minZoom: 0.1,          // Minimum zoom level
    maxZoom: 3,            // Maximum zoom level
    rotation: true,         // Enable rotation
    viewportCulling: true, // Enable viewport culling
  }}
>
```

## 🔧 Basic Usage

### Adding Elements

```tsx
import { useEditor } from "@jeevandev/flow-canvas";

function Toolbar() {
  const addNode = useEditor((state) => state.addNode);

  const handleAddElement = () => {
    addNode({
      id: `element-${Date.now()}`,
      x: 100,
      y: 100,
      width: 200,
      height: 100,
      pageId: "page-1",
      draggable: true,
      resizable: true,
      rotatable: true,
    });
  };

  return <button onClick={handleAddElement}>Add Element</button>;
}
```

### Custom Node Types

```tsx
import { NodeComponentProps } from "@jeevandev/flow-canvas";

const CustomNode = ({ data, style, className }: NodeComponentProps) => (
  <div style={style} className={className}>
    <h2>{data?.title}</h2>
    <p>{data?.description}</p>
  </div>
);

<Canvas nodeTypes={{ custom: CustomNode }} />;
```

### Selection

```tsx
const selectedIds = useEditor((state) => state.selectedIds);
const selectNode = useEditor((state) => state.selectNode);
const deselectAll = useEditor((state) => state.deselectAll);

// Select a node
selectNode("node-1");

// Deselect all
deselectAll();
```

## 🎨 Styling

The library includes default styles that you can import:

```tsx
import "@jeevandev/flow-canvas/style.css";
```

You can customize styles using CSS variables or by overriding the default classes. See [Configuration](./docs/CONFIGURATION.md) for details.

## ⚡ Performance

The library is optimized for performance:

- **Viewport Culling** - Only renders visible elements (enabled by default)
- **Virtualization** - Advanced virtualization for 100+ elements
- **Memoization** - React.memo and useMemo for optimal re-renders
- **Bundle Size** - Optimized bundle (121KB UMD, 38KB gzipped)

## 📊 Bundle Size

| Format    | Size   | Gzipped |
| --------- | ------ | ------- |
| ES Module | 165 KB | 43 KB   |
| UMD       | 121 KB | 38 KB   |
| CSS       | 13 KB  | 2.8 KB  |

## 🧪 Development

```bash
# Install dependencies
npm install

# Start dev server
npm run dev

# Build library
npm run build

# Run tests
npm test

# Type check
npx tsc --noEmit
```

## 📝 Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and code of conduct.

## 📄 License

MIT © [Jeevan Jose](https://github.com/jeevanjose)

## 🙏 Acknowledgments

Built with:

- [React](https://react.dev/)
- [Zustand](https://github.com/pmndrs/zustand) - State management
- [@use-gesture/react](https://use-gesture.netlify.app/) - Gesture handling
- [Vite](https://vitejs.dev/) - Build tool

---

**Ready for production use** ✅ | **TypeScript** ✅ | **Accessible** ✅ | **Well-tested** ✅