## Spec for SortableListSection Package

A section for the property builder that is used to provide a user interface which generates an array of objects for the programmer.

• It is useful for editor objects that need to gather informatino from the user in order to gather a list of data (e.g. List, Navigation, Stacks, Accordian, Repeater, Shapes, SmartContainer, Stepper, Tab Switcher)
• The component itself provides a nice UX for data entry of lists. Displays a list of items based on the incoming array, facilitates CRUD actions via drag and drop and customizable buttons and display types.

## Table of Contents

- [Spec for SortableListSection Package](#spec-for-listsortablesection-package)
- [Table of Contents](#table-of-contents)
- [Test Plan](#test-plan)
- [Acceptance Tests](#acceptance-tests)
- [Screens / States](#screens--states) - [Usage](#usage) - [Schema](#schema) - [Tests](#tests)

## Test Plan

| Scenario  | Expected           | Automated | Type       |
| --------- | ------------------ | --------- | ---------- |
| Rendering | Should show in dom | Yes       | End to End |

## Acceptance Tests

(N/A)

## Screens / States

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

##### Usage

To install it...

> npm install @sandcastle/components

Add it to your project...

```
import * as React from 'react'
import * as SortableList from '@sandcastle/components/SortableList`

export default () => (
  <SortableList
    data=""
  />
)
```

##### Schema

| Name                  | Type                                   | Description                                                                                                                             | Schema Type |
| --------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| data                  | ItemComponentProps[]                   | The incoming data that this component will manage                                                                                       | prop        |
| itemComponent         | React.ReactNode                        | The component to use that will represent each item in the incoming data array                                                           | prop        |
| addButtonComponent    | React.ReactNode                        | A component to use instead of the default add button component                                                                          | prop        |
| editButtonComponent   | React.ReactNode                        | A component to use instead of the default edit button component                                                                         | prop        |
| deleteButtonComponent | React.ReactNode                        | A component to use instead of the default delete button component                                                                       | prop        |
| showCRUDOnHover       | boolean                                | Whether or not show the CRUD icons when the mouse is hovered on the item or not (always shows)                                          | prop        |
| showDragHandle        | boolean                                | Whether or not to show a draggable handle indicator next to each item                                                                   | prop        |
| canDragAndDrop        | boolean                                | Whether or not drag and drop is enabled                                                                                                 | prop        |
| canDelete             | boolean                                | Whether or not to display the delete icon next to each item                                                                             | prop        |
| canAdd                | boolean                                | Whether or not to show the add button                                                                                                   | prop        |
| canEdit               | boolean                                | Whether or not to display the edit icon next to each item                                                                               | prop        |
| onChange              | (section:ItemComponentProps[]) => void | Triggered when an item changes. Returns an updated version of the data array. It's up to the component provider to update the data prop | prop        |
| onEdit                | (section:ItemComponentProps) => void   | Triggers when the edit button next to an item is clicked                                                                                | prop        |
| onAdd                 | () => void                             | Triggers when the [Add] button is clicked                                                                                               | prop        |
| onDelete              | (section:ItemComponentProps) => void   | Triggers when the [Delete] button is clicked                                                                                            | prop        |

##### Tests

| It                                                                                                                                            | Type        |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| Rendering --> Should render in the dom                                                                                                        | Integration |
| Rendering --> Should render the same number of item components as the number of items in the provided data prop                               | Integration |
| Rendering --> Should pass along the object's payload as props to the itemCmponent                                                             | Integration |
| Rendering --> Should render an addButtonComponent (instead of the default component) in each item if one is provided                          | Integration |
| Rendering --> Should render an editButtonComponent (instead of the default component) in each item if one is provided                         | Integration |
| Rendering --> Should render an deleteButtonComponent (instead of the default component) in each item if one is provided                       | Integration |
| Rendering --> Should not display a delete button if the canDelete prop is false                                                               | Integration |
| Rendering --> Should not display an add button if the canDelete prop is false                                                                 | Integration |
| Rendering --> Should not display an edit button if the canDelete prop is false                                                                | Integration |
| Actions --> Should not allow drag and drop actions if the canDragAndDrop prop is false                                                        | Integration |
| Events --> Should trigger the onChange event when the items are re-ordered via drag-and-drop                                                  | Integration |
| Events --> Should include an updated list of items from the onChange event return function when the sections are re-ordered via drag and drop | Integration |
| Events --> Should trigger the onEdit event when an edit button is clicked                                                                     | Integration |
| Events --> Should include the associated object's payload when the onEdit event is called                                                     | Integration |
| Events --> Should trigger the onAdd event when a add button is clicked                                                                        | Integration |
| Events --> Should trigger the onDelete event when a delete button is clicked                                                                  | Integration |
| Events --> Should include the associated object's payload when the onDelete event is called                                                   | Integration |