npm package: @piragash13/draggable-dashboard
Description: A draggable dashboard component library
Author: Piragash
Latest version: 0.0.6

# 📊 Test Draggable Dashboard

A fully responsive, highly customizable, grid-based dashboard component for React. It features drag-and-drop tile management, resizable widgets, dynamic theming, and comprehensive layout controls.

![License](https://img.shields.io/npm/l/@apptimus-ui/draggable-dashboard)
![Version](https://img.shields.io/npm/v/@apptimus-ui/draggable-dashboard)

## 🚀 Features

- **Drag & Drop Layout**: Intuitively arrange tiles on a customizable grid.
- **Resizable Tiles**: Resize widgets using corner handles with auto-repacking.
- **Responsive Design**: Automatically switches to a mobile-friendly read-only view on smaller screens (<768px).
- **Theme Support**: Built-in Light and Dark modes, plus full overriding capabilities for every color.
- **Configurable Grid**: Custom columns, rows, gaps, and unit sizes.
- **Extensible Rendering**: Pass custom render functions for different tile types (Charts, Tables, Images, etc.).
- **Built-In Layouts**: One-click alignment tools (Row, Column, Free).
- **Touch Support**: Smooth interactions on touch devices.

## 📦 Installation

```bash
npm install @apptimus-ui/draggable-dashboard
# or
yarn add @apptimus-ui/draggable-dashboard
```

## 🛠️ Quick Start

```jsx
import React, { useState } from 'react';
import { DraggableDashboard } from '@apptimus-ui/draggable-dashboard';
import '@apptimus-ui/draggable-dashboard/dist/DraggableDashboard.css'; // Don't forget CSS!

const App = () => {
  const [tiles, setTiles] = useState([
    { id: '1', x: 0, y: 0, w: 4, h: 4, title: 'Sales Report', type: 'CHART' },
    { id: '2', x: 4, y: 0, w: 4, h: 4, title: 'User Stats', type: 'NUMBER', numberValue: 1250 },
  ]);

  return (
    <div style={{ height: '100vh' }}>
      <DraggableDashboard
        tiles={tiles}
        setTiles={setTiles}
        dashboardId="my-main-dashboard"
        editMode={true}
        theme="light"
        gridCols={12}
      />
    </div>
  );
};

export default App;
```

## ⚙️ Props API

### Core Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `tiles` | `Array` | **Yes** | Array of tile objects to display. |
| `setTiles` | `Func` | **Yes** | State setter for updating tiles. |
| `editMode` | `Boolean` | No | Toggles drag/resize capability and edit controls. |
| `dashboardId` | `String` | No | Identifier used for persistence callbacks. |
| `onEditModeChange`| `Func` | No | Callback when edit mode button is clicked. |

### Grid Configuration

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `gridCols` | `Number` | `12` | Total number of columns in the grid. |
| `gridRows` | `Number` | `12` | Total number of rows in the grid. |
| `gridGap` | `Number` | `10` | Gap between tiles in pixels. |
| `minUnits` | `Number` | `1` | Minimum width/height in grid units for resizing. |
| `maxUnits` | `Number` | `12` | Maximum width/height in grid units for resizing. |
| `initialTileW` | `Number` | `minUnits` | Default width for new tiles. |
| `initialTileH` | `Number` | `minUnits` | Default height for new tiles. |

### Render Props

Custom render functions allow you to control exactly how content is displayed within a tile.

| Prop | Signature | Description |
|------|-----------|-------------|
| `renderTileContent` | `(tile) => Node` | Generic override for tile content. |
| `renderChart` | `({ reportId, chartConfigId }) => Node` | Renders content for `type: "CHART"`. |
| `renderTable` | `({ reportId }) => Node` | Renders content for `type: "TABLE"`. |
| `renderImage` | `({ imageUrl, title }) => Node` | Renders content for `type: "IMAGE"`. |
| `renderNumber` | `({ value, title }) => Node` | Renders content for `type: "NUMBER"`. |

### Event Handlers

| Prop | Description |
|------|-------------|
| `onTilesReload` | Called when tiles are added or deleted, useful for refreshing external data. |
| `onDeleteTile` | Async callback triggered before a tile is removed. Return `{ is_success: true }` to proceed. |
| `onSetPositions` | Called after drag/resize ends. Args: `dashboardId`, `positionMap`. |
| `onRemoveTilePosition` | Called after a tile is deleted to clean up saved positions. |

### Component Overrides

| Prop | Description |
|------|-------------|
| `AddTileModal` | Component to display when "Add Tile" is clicked. Receives `onSave`. |
| `DeleteTileModal` | Component to display for delete confirmation. |
| `AddTileButton` | Component to replace the default "Add Tile" button in empty state. |
| `SVG` | Generic Icon component. Used for icons like trash, edit, etc. |
| `EditModeOnIcon` | Component to replace the "active" edit mode icon. |
| `EditModeOffIcon` | Component to replace the "inactive" edit mode icon. |

### Theme & Styling

You can use the `theme` prop (`'light'` | `'dark'`) or override specific colors.

| Prop | Default (Light) | Default (Dark) | Description |
|------|-----------------|----------------|-------------|
| `dashboardBg` | `#f8f9fa` | `#1a1a1a` | Background color of the entire dashboard area. |
| `tileBg` | `#ffffff` | `#2d2d2d` | Background color of individual tiles. |
| `tileBorderColor` | `transparent` | `#404040` | Border color for tiles. |
| `tileShadow` | `0 4px 6px...` | `0 4px 6px...` | Box shadow for tiles. |
| `tileText` | `#333333` | `#ffffff` | Main text color in tiles. |
| `tileTitle` | `#111111` | `#eeeeee` | Title text color in tiles. |
| `gridCellBg` | `transparent` | `transparent` | Background of grid cells (visible in edit mode). |
| `gridCellBorder` | `#e0e0e0` | `#333333` | Border of grid cells. |
| `resizeHandleBg` | `#cccccc` | `#666666` | Color of the resize handle (bottom-right). |
| `floatingOffsetBottom`| `20` | `20` | Bottom offset for floating controls (px). |
| `floatingOffsetRight` | `20` | `20` | Right offset for floating controls (px). |
| `tileBorderRadius` | `8` | `8` | Border radius for tiles (px or string). |

## 🕹️ Methods (Ref)

The component forwards a ref that exposes helper methods:

```javascript
const dashboardRef = useRef();

// ...
<DraggableDashboard ref={dashboardRef} ... />

// Open the Add Tile Modal programmatically
dashboardRef.current.openAddTileModal();
```

## 🧩 Tile Object Structure

```javascript
{
  id: "unique_id",
  title: "My Widget",
  x: 0,             // Grid column (0-indexed)
  y: 0,             // Grid row (0-indexed)
  w: 4,             // Width in units
  h: 4,             // Height in units
  type: "CHART",    // 'TABLE', 'IMAGE', 'NUMBER', 'visualization', or custom
  // ... other properties specific to your render functions (e.g., reportId, imageUrl)
}
```

## 📄 License

MIT © [Piragash]