npm package: @rnednur/draggable-canvas
Description: A React component library for building interactive draggable canvases with TypeScript support and shadcn/ui compatibility
Author: rnednur
Latest version: 0.1.3

# 🎯 Draggable Canvas

A React component library for building interactive draggable canvases with TypeScript support and shadcn/ui compatibility.

[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![shadcn/ui](https://img.shields.io/badge/shadcn%2Fui-Compatible-purple.svg)](https://ui.shadcn.com/)

## ✨ Features

- 🖱️ **Drag & Drop**: Smooth dragging with container bounds and accessibility
- 📏 **Resizable**: Click and drag resize handles with keyboard support  
- 🎨 **Extensible**: Custom renderers, universal components, and type-safe items
- ♿ **Accessible**: Full keyboard navigation, ARIA labels, and screen reader support
- 📱 **Responsive**: Works on desktop and mobile with touch support
- 🎭 **Themeable**: Built with shadcn/ui components and CSS variables
- 📊 **Rich Items**: Built-in support for charts, notes, websites, and data visualizations
- 💾 **Import/Export**: Save and load canvas configurations as JSON

## 🚀 Quick Start

### Installation

```bash
npm install @rnednur/draggable-canvas
# or
yarn add @rnednur/draggable-canvas
# or  
pnpm add @rnednur/draggable-canvas
```

### Basic Usage

```tsx
import { Canvas } from '@rnednur/draggable-canvas'

function MyCanvas() {
  const [items, setItems] = useState([
    {
      id: 'note-1',
      type: 'note',
      x: 100,
      y: 100,
      width: 200,
      height: 150,
      title: 'Hello World',
      content: 'This is a draggable note!',
      noteColor: 'yellow'
    }
  ])

  return (
    <Canvas
      items={items}
      onItemsChange={setItems}
      className="w-full h-screen"
      editable={true}
    />
  )
}
```

## 📖 Usage Modes

### General Canvas Mode
Perfect for prototyping, mind mapping, and general drag-and-drop interfaces:

```tsx
<Canvas
  items={items}
  onItemsChange={setItems}
  variant="minimal"
  showToolbar={false}
  showPalette={false}
/>
```

### Dashboard Mode  
Full-featured with toolbar, palette, and export functionality:

```tsx
<Canvas
  items={items}
  onItemsChange={setItems}
  variant="grid"
  showToolbar={true}
  showPalette={true}
  onSave={(config) => saveToBackend(config)}
  onLoad={() => loadFromBackend()}
/>
```

## 🧩 Built-in Item Types

### Notes
```tsx
{
  type: 'note',
  title: 'My Note',
  content: 'Note content here...',
  noteColor: 'yellow' | 'blue' | 'green' | 'pink' | 'purple'
}
```

### Charts
```tsx
{
  type: 'chart', 
  title: 'Sales Data',
  chartType: 'bar' | 'line' | 'pie' | 'donut',
  chartData: { values: [...], labels: [...] },
  chartLibrary: 'recharts' | 'chartjs' | 'apexcharts'
}
```

### Website Embeds
```tsx
{
  type: 'url',
  url: 'https://example.com',
  title: 'Example Site'
}
```

### Data Items (API Integration)
```tsx
{
  type: 'data-item',
  title: 'Live Data',
  config: {
    apiEndpoint: 'https://api.example.com/data',
    visualizationType: 'table' | 'chart' | 'metric',
    refreshInterval: 30000
  }
}
```

## 🔧 Custom Components

### Universal Components
Register any React component to use in the canvas:

```tsx
import { ComponentRegistry } from '@rnednur/draggable-canvas'

// 1. Create your component
function TodoList({ items, onAdd }) {
  return (
    <div className="p-4 bg-white border rounded">
      {/* Your component JSX */}
    </div>
  )
}

// 2. Register it
ComponentRegistry.register('todo-list', {
  component: TodoList,
  defaultProps: { items: [] },
  defaultDimensions: { width: 300, height: 400 }
})

// 3. Use in canvas
{
  type: 'universal',
  universalType: 'todo-list',
  props: { items: [...] }
}
```

### Custom Renderers
Override rendering for any item type:

```tsx
const customRenderers = {
  'my-type': (item) => (
    <div className="custom-item">
      {/* Custom rendering logic */}
    </div>
  )
}

<Canvas
  items={items}
  customRenderers={customRenderers}
  onItemsChange={setItems}
/>
```

## 🎮 Interactions

### Mouse Controls
- **Drag**: Click and drag items to move them
- **Resize**: Drag the bottom-right corner to resize  
- **Delete**: Click the X button in the top-right corner
- **Multi-select**: Ctrl+click items or drag a selection box

### Keyboard Controls
- **Tab**: Focus items sequentially
- **Arrow Keys**: Move focused items (Shift for faster movement)
- **Ctrl+Arrow Keys**: Resize focused items
- **Delete/Backspace**: Remove focused items
- **Ctrl+Z/Y**: Undo/Redo
- **Ctrl+S**: Save canvas
- **Ctrl+E**: Export canvas

## 📋 API Reference

### Canvas Props

```tsx
interface CanvasProps {
  // Core
  items?: CanvasItem[]
  onItemsChange?: (items: CanvasItem[]) => void
  
  // Behavior
  editable?: boolean
  variant?: 'default' | 'minimal' | 'dark' | 'grid'
  size?: 'default' | 'compact' | 'full'
  
  // UI Controls
  showToolbar?: boolean
  showPalette?: boolean
  toolbarPosition?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'right-center'
  palettePosition?: 'left' | 'right' | 'top' | 'bottom'
  
  // Events
  onItemUpdate?: (id: string, updates: Partial<CanvasItem>) => void
  onItemDelete?: (id: string) => void
  onSave?: (config: CanvasConfig) => void
  onLoad?: () => CanvasConfig | null
  onExport?: () => void
  
  // Customization
  customRenderers?: ItemRenderersRegistry
  className?: string
  children?: React.ReactNode
}
```

### Item Interface

```tsx
interface CanvasItem {
  id: string
  type: string
  x: number
  y: number  
  width: number
  height: number
  // Type-specific properties...
}
```

## 🎨 Styling

The library uses shadcn/ui components and CSS variables for theming. All components accept `className` props and can be styled with Tailwind CSS.

### Custom Themes
```tsx
<Canvas
  variant="dark"
  className="border-2 border-slate-800 bg-slate-900"
/>
```

## 📱 Mobile Support

The canvas works on mobile devices with touch support:
- Touch to drag items
- Pinch to zoom (coming soon)
- Long press for context menus (coming soon)

## 🧪 Examples

### Minimal Example
```tsx
import { Canvas, createCanvasItem } from '@rnednur/draggable-canvas'

const items = [
  createCanvasItem({
    type: 'note',
    x: 100, y: 100,
    width: 200, height: 150,
    title: 'Hello',
    content: 'World!',
    noteColor: 'yellow'
  })
]

<Canvas items={items} />
```

### Dashboard Example  
```tsx
<Canvas
  items={dashboardItems}
  onItemsChange={setItems}
  variant="grid"
  showToolbar={true}
  showPalette={true}
  onSave={saveDashboard}
  onLoad={loadDashboard}
  customRenderers={myRenderers}
/>
```

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
git clone https://github.com/your-org/draggable-canvas
cd draggable-canvas
npm install
npm run dev
```

### Running Tests
```bash
npm test
npm run test:watch
```

## 📄 License

MIT © [Your Name](https://github.com/your-org)

## 🔗 Links

- [Live Demo](https://your-demo-url.com)
- [Documentation](https://your-docs-url.com)
- [Examples](https://your-examples-url.com)
- [Issues](https://github.com/your-org/draggable-canvas/issues)