npm package: @kumaran_bk/test-dashboard
Description: A React-based draggable dashboard powered by GridStack.js, optimized for Next.js integration
Latest version: 1.0.0

# Apptimus Dashboard

A React-based draggable dashboard powered by GridStack.js, optimized for Next.js integration.

## Features

- 🎯 **Five Widget Types**: TEXT, NUMBER, CHART, TABLE, and IMAGE
- 🖱️ **Drag & Drop**: Intuitive drag-and-drop interface for rearranging widgets
- 📱 **Responsive**: Mobile-friendly layouts with GridStack.js
- 🔧 **Customizable**: Flexible grid options and widget positioning
- 💾 **Persistent**: Save and load dashboard layouts
- ⚡ **Next.js Ready**: SSR compatible with ESM/CJS outputs

## Installation

```bash
npm install apptimus-dashboard
```

### Peer Dependencies

This package requires the following peer dependencies:

```bash
npm install @apptimus-ui/modal@^1.0.0 @apptimus-ui/table@* @apptimus-ui/theme@^1.3.0
```

## Quick Start

```tsx
import { DraggableDashboard } from 'apptimus-dashboard';
import TextWidget from './TextWidget';

function MyDashboard() {
  const [widgets, setWidgets] = useState([
    {
      id: '1',
      type: 'TEXT',
      x: 0,
      y: 0,
      w: 4,
      h: 2,
      content: <TextWidget text="Dashboard" />
    }
  ]);

  const handleLayoutChange = (layout) => {
    // Save layout to your backend or state
    console.log('Layout changed:', layout);
  };

  return (
    <DraggableDashboard
      widgets={widgets}
      onLayoutChange={handleLayoutChange}
    />
  );
}
```

## Props

### `DraggableDashboardProps`

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `widgets` | `DashboardWidget[]` | Yes | Array of widgets to display |
| `onAddWidget` | `(type: string) => void` | No | Callback when adding a new widget |
| `onRemoveWidget` | `(id: string) => void` | No | Callback when removing a widget |
| `onLayoutChange` | `(layout: GridStackNode[]) => void` | No | Callback when layout changes |
| `gridOptions` | `Partial<GridStackOptions>` | No | Custom GridStack options |

### `DashboardWidget`

```typescript
interface DashboardWidget {
  id: string;
  type: 'TEXT' | 'NUMBER' | 'CHART' | 'TABLE' | 'IMAGE';
  x: number;        // Grid X position
  y: number;        // Grid Y position
  w: number;        // Width in grid units
  h: number;        // Height in grid units
  content: ReactNode; // React component to render
}
```

## Usage Examples

### Basic Dashboard

```tsx
import { DraggableDashboard } from 'apptimus-dashboard';

const widgets = [
  {
    id: '1',
    type: 'TEXT',
    x: 0,
    y: 0,
    w: 4,
    h: 2,
    content: <div>Hello World</div>
  },
  {
    id: '2',
    type: 'CHART',
    x: 4,
    y: 0,
    w: 8,
    h: 4,
    content: <ChartComponent data={chartData} />
  }
];

<DraggableDashboard widgets={widgets} />
```

### With Layout Persistence

```tsx
import { useState, useEffect } from 'react';
import { DraggableDashboard } from 'apptimus-dashboard';

function Dashboard() {
  const [widgets, setWidgets] = useState([]);

  // Load saved layout
  useEffect(() => {
    const saved = localStorage.getItem('dashboard-layout');
    if (saved) {
      setWidgets(JSON.parse(saved));
    }
  }, []);

  // Save layout changes
  const handleLayoutChange = (layout) => {
    const updated = widgets.map(widget => {
      const layoutItem = layout.find(item => item.id === widget.id);
      if (layoutItem) {
        return {
          ...widget,
          x: layoutItem.x || 0,
          y: layoutItem.y || 0,
          w: layoutItem.w || 4,
          h: layoutItem.h || 2,
        };
      }
      return widget;
    });
    setWidgets(updated);
    localStorage.setItem('dashboard-layout', JSON.stringify(updated));
  };

  return (
    <DraggableDashboard
      widgets={widgets}
      onLayoutChange={handleLayoutChange}
    />
  );
}
```

### Custom Grid Options

```tsx
<DraggableDashboard
  widgets={widgets}
  gridOptions={{
    column: 16,        // 16-column grid
    cellHeight: 100,   // Taller cells
    margin: 5,         // Smaller margins
    disableResize: false,
    disableDrag: false,
    animate: true,
  }}
/>
```

### Adding Widgets with Modal

```tsx
import { useState } from 'react';
import { Modal } from '@apptimus-ui/modal';
import { DraggableDashboard } from 'apptimus-dashboard';

function DashboardWithAdd() {
  const [widgets, setWidgets] = useState([]);
  const [showModal, setShowModal] = useState(false);

  const handleAddWidget = (type) => {
    const newWidget = {
      id: Date.now().toString(),
      type,
      x: 0,
      y: 0,
      w: 4,
      h: 2,
      content: <WidgetComponent type={type} />
    };
    setWidgets([...widgets, newWidget]);
    setShowModal(false);
  };

  return (
    <>
      <button onClick={() => setShowModal(true)}>Add Widget</button>
      <DraggableDashboard
        widgets={widgets}
        onAddWidget={handleAddWidget}
      />
      {showModal && (
        <Modal onClose={() => setShowModal(false)}>
          <WidgetTypeSelector onSelect={handleAddWidget} />
        </Modal>
      )}
    </>
  );
}
```

## Widget Types

The dashboard supports five widget types. You provide the React components:

- **TEXT**: Text-based widgets
- **NUMBER**: Numeric displays
- **CHART**: Chart visualizations
- **TABLE**: Data tables (use `@apptimus-ui/table`)
- **IMAGE**: Image displays

## GridStack Options

You can customize the grid behavior using `gridOptions`. Common options:

- `column`: Number of columns (default: 12)
- `cellHeight`: Height of each cell in pixels (default: 70)
- `margin`: Margin between cells (default: 10)
- `disableResize`: Disable widget resizing
- `disableDrag`: Disable widget dragging
- `animate`: Enable animations

See [GridStack documentation](https://gridstackjs.com/) for all options.

## TypeScript

Full TypeScript support is included:

```typescript
import type {
  DraggableDashboardProps,
  DashboardWidget,
  WidgetType,
} from 'apptimus-dashboard';
```

## Next.js Integration

The package is optimized for Next.js with:

- SSR compatibility
- `'use client'` directive for client components
- ESM and CJS build outputs

## License

MIT