📊 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.

🚀 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

npm install test-draggable-dashboard
# or
yarn add test-draggable-dashboard

🛠️ Quick Start

import React, { useState } from 'react';
import { DraggableDashboard } from 'test-draggable-dashboard';
import 'test-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:

const dashboardRef = useRef();

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

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

🧩 Tile Object Structure

{
  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]