## Spec for Dashboard Package

A flexible module for quickly building dashboards.

There are some widgets readily available out of the box, but you have complete control to override them as you wish with your own styles and layout

## Table of Contents

- [Spec for Dashboard Package](#spec-for-dashboard-package)
- [Table of Contents](#table-of-contents)
- [Workflow](#workflow)
- [User Stories](#user-stories)
- [Test Plan](#test-plan)
- [Acceptance Tests](#acceptance-tests)
- [Screens / States](#screens--states)
- [Components](#components)
  - [Layouts](#layouts)
  - [Containers](#containers)
  - [Components](#components-1)
- [Schema](#schema)
  - [Component Schema](#component-schema)
    - [Dashboard](#dashboard)
      - [Schema](#schema-1)
      - [Tests](#tests)
    - [WidgetContainer](#widgetcontainer)
      - [Schema](#schema-2)
      - [Tests](#tests-1)
  - [Database Schema](#database-schema)
  - [Store/Reducers](#storereducers)
  - [APIs/Hook Schema](#apishook-schema)

## Workflow

![]()

## User Stories

- As a user I want to lay out a collection of widgets on a specified grid layout
- As a user I want to be able to easily add/remove widgets to my dashboard
- As a user I want to be able to edit the order, location, and relative sizes of the widgets in my dashboard using Drag and Drop
- As a developer I want to be able to specify actions that users can take with each widget

## Test Plan

| Scenario  | Expected                                                                                                                                     | Automated | Type       |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------- |
| Rendering | Should show a collection of widgets on the dashboard. Amount should be equal to the number of objects in the widgets array found in the prop | Yes       | End to End |
| Rendering | Should show widgets on a grid laid out according to the settings found in the layout prop                                                    | Yes       | End to End |
| Rendering | Should show in "edit" mode when inEditMode prop is true                                                                                      | Yes       | End to End |
| Rendering | Should show a custom style (provided by editModeStyle prop) on widgets when inEditMode prop is true                                          | Yes       | End to End |
| Rendering | Should be able to drag a widget from one column to another when in edit mode                                                                 | Yes       | End to End |
| Rendering | Should show a custom style (provided by the droppableStyle prop) in available dropzones while dragging over                                  | Yes       | End to End |
| Rendering | Should show a custom component (provided by the widgetComponent prop) instead the default widget container when one is provided              | Yes       | End to End |
| Rendering | Should trigger the onCreate() event when a new widget has been added to the dashboard                                                        | Yes       | End to End |
| Rendering | Should trigger the onDelete() event when a widget is removed                                                                                 | Yes       | End to End |
| Rendering | Should trigger the onMove() event when a widget is moved                                                                                     | Yes       | End to End |
| Rendering | Should trigger the "onWidgetCreate" plugin hooks when a new widget has been added to the dashboard                                           | Yes       | End to End |
| Rendering | Should trigger the "onWidgetDelete" plugin hooks when a widget is removed                                                                    | Yes       | End to End |
| Rendering | Should trigger the "onWidgetMove" plugin hooks when a widget is moved                                                                        | Yes       | End to End |
| Rendering | Should trigger the "onWidgetRender" plugin hooks when widget is rendered                                                                     | Yes       | End to End |
| Rendering | Should trigger the "onDashboardRender" plugin hooks when dashboard is rendered                                                               | Yes       | End to End |

## Acceptance Tests

(N/A)

## Screens / States

![](http://ambid-backups.s3.amazonaws.com/screenshots/sandcastle/hf_dashboard.png)

## Components

### Layouts

N/A

### Containers

| Name      | Type       | Description                                        | Behaviors | Exists | Package |
| --------- | ---------- | -------------------------------------------------- | --------- | ------ | ------- |
| Dashboard | Containers | A flexible module for quickly building dashboards. |           | No     | No      |

### Components

| Name            | Type       | Description                                                | Behaviors | Exists | Package |
| --------------- | ---------- | ---------------------------------------------------------- | --------- | ------ | ------- |
| WidgetContainer | Components | A container for showing custom dashboard widget components |           | No     | No      |

## Schema

### Component Schema

#### Dashboard

##### Schema

| Name            | Type                | Description                                                                                                              | Schema Type |
| --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------- |
| name            | string              | The name to use for the Dashboard component. Useful for plugins that want to hook into your specific dashboard vs others | prop        |
| widgets         | any[]               | The widgets that can should be on the dashboard                                                                          | prop        |
| layout          | object              | The layout of the dashboard                                                                                              | prop        |
| inEditMode      | boolean             | Whether or not the dashboard is in edit mode                                                                             | prop        |
| droppableStyle  | React.CSSProperties | Style used to indicate that a column is droppable                                                                        | prop        |
| editModeStyle   | React.CSSProperties | Style used to indicate that widgets are in edit mode                                                                     | prop        |
| widgetComponent | component           | Custom component to be used instead of the default widget component                                                      | prop        |
| onCreate        | () => any           | Trigger when a new widget has been added to the dashboard                                                                | prop        |
| onDelete        | () => any           | Trigger when a widget is removed                                                                                         | prop        |
| onMove          | () => any           | Trigger when a widget is moved                                                                                           | prop        |

##### Tests

| It                                                                                                                                           | Type        |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| Should show a collection of widgets on the dashboard. Amount should be equal to the number of objects in the widgets array found in the prop | Integration |
| Should show widgets on a grid laid out according to the settings found in the layout prop                                                    | Integration |
| Should show in "edit" mode when inEditMode prop is true                                                                                      | Integration |
| Should show a custom style (provided by editModeStyle prop) on widgets when inEditMode prop is true                                          | Integration |
| Should be able to drag a widget from one column to another when in edit mode                                                                 | Integration |
| Should show a custom style (provided by the droppableStyle prop) in available dropzones while dragging over                                  | Integration |
| Should show a custom component (provided by the widgetComponent prop) instead the default widget container when one is provided              | Integration |
| Should trigger the onCreate() event when a new widget has been added to the dashboard                                                        | Integration |
| Should trigger the onDelete() event when a widget is removed                                                                                 | Integration |
| Should trigger the onMove() event when a widget is moved                                                                                     | Integration |
| Should trigger the "onWidgetCreate" plugin hooks when a new widget has been added to the dashboard                                           | Integration |
| Should trigger the "onWidgetDelete" plugin hooks when a widget is removed                                                                    | Integration |
| Should trigger the "onWidgetMove" plugin hooks when a widget is moved                                                                        | Integration |
| Should trigger the "onWidgetRender" plugin hooks when widget is rendered                                                                     | Integration |
| Should trigger the "onDashboardRender" plugin hooks when dashboard is rendered                                                               | Integration |

#### WidgetContainer

##### Schema

| Name            | Schema Type | Type      | Description                                                                                                 |
| --------------- | ----------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| children        | prop        | component | Will contain the actual widget contents                                                                     |
| title           | prop        | string    | The caption to display as the title of the widget                                                           |
| actions         | prop        | object    | An array of objects that represent the items in to show in the dropdown menu and associated actions to take |
| actionComponent | prop        | component | Custom component to use instead of the default action component                                             |

##### Tests

| It                                                                              | Type        |
| ------------------------------------------------------------------------------- | ----------- |
| Should render widget with provided title prop as the caption                    | Integration |
| Should render child component                                                   | Integration |
| Should show an action menu that reflects the items provided in the actions prop | Integration |
| Should render a custom action component if one is provided                      | Integration |

### Database Schema

### Store/Reducers

### APIs/Hook Schema