Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/asseinfo/react-kanban
Yet another Kanban/Trello board lib for React.
https://github.com/asseinfo/react-kanban
hacktoberfest javascript js kanban kanban-board react reactjs trello
Last synced: 3 months ago
JSON representation
Yet another Kanban/Trello board lib for React.
- Host: GitHub
- URL: https://github.com/asseinfo/react-kanban
- Owner: asseinfo
- License: mit
- Archived: true
- Created: 2019-03-28T20:46:28.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2022-10-08T12:19:24.000Z (about 2 years ago)
- Last Synced: 2024-05-15T19:39:36.910Z (6 months ago)
- Topics: hacktoberfest, javascript, js, kanban, kanban-board, react, reactjs, trello
- Language: JavaScript
- Homepage:
- Size: 519 KB
- Stars: 641
- Watchers: 11
- Forks: 165
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
## 🔴🔴🔴 THIS PROJECT IS DEPRECATED 🔴🔴🔴
Unfortunately this project is deprecated and it is not maintained anymore.
In the past, our core product was using `react-kanban` and indirectly we were improving this project. But nowadays we replaced it for another internal simplier version.
As a small dev team, it's impossible for us to continue improving both sources without an external help.
This source is going to continue available here, but, unfortunately, none effort is going to be done to improve the project.
## react-kanban
[](https://codecov.io/gh/lourenci/react-kanban)
[](https://github.com/lourenci/react-kanban/actions?query=branch%3Amain+workflow%3ATest)
[](https://standardjs.com)
Yet another Kanban/Trello board lib for React.
### ▶️ Demo
[Usage](https://nvjp3.csb.app/)
[](https://codesandbox.io/s/react-kanban-demo-nvjp3)
## ❓ Why?
- 👊 Reliable: 100% tested on CI; 100% coverage; 100% SemVer.
- 🎮 Having fun: Play with Hooks 🎣 and ~~Styled Components~~.
- ♿️ Accessible: Keyboard and mobile friendly.
- 🔌 Pluggable: For use in projects.
## 🛠 Install and usage
Since this project use Hooks, you have to install them:
- `react>=16.8.5`
After, Install the lib on your project:
```bash
yarn add @asseinfo/react-kanban
```
Import the lib and use it on your project:
```js
import Board from '@asseinfo/react-kanban'
import '@asseinfo/react-kanban/dist/styles.css'
const board = {
columns: [
{
id: 1,
title: 'Backlog',
cards: [
{
id: 1,
title: 'Add card',
description: 'Add capability to add a card in a column'
},
]
},
{
id: 2,
title: 'Doing',
cards: [
{
id: 2,
title: 'Drag-n-drop support',
description: 'Move a card between the columns'
},
]
}
]
}
```
## 🔥 API
### 🕹 Controlled and Uncontrolled
When you need a better control over the board, you should stick with the controlled board.
A controlled board means you need to deal with the board state yourself, you need to keep the state in your hands (component) and pass this state to the ``, we just reflect this state.
This also means a little more of complexity, although we make available some helpers to deal with the board shape.
You can read more in the React docs, [here](https://reactjs.org/docs/forms.html#controlled-components) and [here](https://reactjs.org/docs/uncontrolled-components.html).
If you go with the controlled one, you need to pass your board through the `children` prop, otherwise you need to pass it through the `initialBoard` prop.
#### Helpers to work with the controlled board
We expose some APIs that you can import to help you to work with the controlled state. Those are the same APIs we use internally to manage the uncontrolled board. We really recommend you to use them, they are 100% unit tested and they don't do any side effect to your board state.
To use them, you just need to import them together with your board:
```js
import Board, { addCard, addColumn, ... } from '@asseinfo/react-kanban'
```
**All the helpers you need to pass your board and they will return a new board to pass to your state:**
```js
import Board, { addColumn } from '@asseinfo/react-kanban'
...
const [board, setBoard] = useState(initialBoard)
...
const newBoard = addColumn(board, newColumn)
setBoard(newBoard)
...
{board}
```
[You can see the list of helpers in the end of the props documentation.](#-helpers-to-be-used-with-an-controlled-board)
### 🔷 Shape of a board
```js
{
columns: [{
id: ${unique-required-columnId},
title: {$required-columnTitle**},
cards: [{
id: ${unique-required-cardId},
title: ${required-cardTitle*}
description: ${required-description*}
}]
}]
}
```
\* The `title` and the `description` are required if you are using the card's default template. You can render your own card template through the [`renderCard`](#rendercard) prop.
\*\* The `title` is required if you are using the column's default template. You can render your own column template through the [`renderColumnHeader`](#rendercolumnheader) prop.
### ⚙️ Props
| Prop | Description | Controlled | Uncontrolled |
| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------- | ------------ |
| [`children`](#children) (required if controlled) | The board to render | ✅ | 🚫 |
| [`initialBoard`](#initialboard) (required if uncontrolled) | The board to render | 🚫 | ✅ |
| [`onCardDragEnd`](#oncarddragend) | Callback that will be called when the card move ends | ✅ | ✅ |
| [`onColumnDragEnd`](#oncolumndragend) | Callback that will be called when the column move ends | ✅ | ✅ |
| [`renderCard`](#rendercard) | A card to be rendered instead of the default card | ✅ | ✅ |
| [`renderColumnHeader`](#rendercolumnheader) | A column header to be rendered instead of the default column header | ✅ | ✅ |
| [`allowAddColumn`](#allowaddcolumn) | Allow a new column be added by the user | ✅ | ✅ |
| [`onNewColumnConfirm`](#onnewcolumnconfirm) (required if use the default column adder template) | Callback that will be called when a new column is confirmed by the user through the default column adder template | ✅ | ✅ |
| [`onColumnNew`](#oncolumnnew) (required if `allowAddColumn` or when [`addColumn`](#rendercolumnadder) is called) | Callback that will be called when a new column is added through the default column adder template | 🚫 | ✅ |
| [`renderColumnAdder`](#rendercolumnadder) | A column adder to be rendered instead of the default column adder template | ✅ | ✅ |
| [`disableColumnDrag`](#disablecolumndrag) | Disable the column move | ✅ | ✅ |
| [`disableCardDrag`](#disablecarddrag) | Disable the card move | ✅ | ✅ |
| [`allowRemoveColumn`](#allowremovecolumn) | Allow to remove a column in default column header | ✅ | ✅ |
| [`onColumnRemove`](#oncolumnremove) (required if `allowRemoveColumn` or when [`removeColumn`](#rendercolumnheader) is called) | Callback that will be called when a column is removed | ✅ | ✅ |
| [`allowRenameColumn`](#allowrenamecolumn) | Allow to rename a column in default column header | ✅ | ✅ |
| [`onColumnRename`](#oncolumnrename) (required if `allowRenameColumn` or when [`renameColumn`](#rendercolumnheader) is called) | Callback that will be called when a column is renamed | ✅ | ✅ |
| [`allowRemoveCard`](#allowremovecard) | Allow to remove a card in default card template | ✅ | ✅ |
| [`onCardRemove`](#oncardremove) (required if `allowRemoveCard`) | Callback that will be called when a card is removed | ✅ | ✅ |
| [`allowAddCard`](#allowaddcard) | Allow to add a card. Expect an object with the position to add the card in the column. | 🚫 | ✅ |
| [`onCardNew`](#oncardnew) (required if `allowAddCard` or when [`addCard`](#rendercolumnheader) is called) | Callback that will be called when a new card is added through the default card adder template | 🚫 | ✅ |
| [`onNewCardConfirm`](#onnewcardconfirm) (required if `allowAddCard`) | Callback that will be called when a new card is confirmed by the user through the default card adder template | 🚫 | ✅ |
#### `children`
The board. Use this prop if you want to control the board's state.
#### `initialBoard`
The board. Use this prop if you don't want to control the board's state.
#### `onCardDragEnd`
When the user moves a card, this callback will be called passing these parameters:
| Arg | Description |
| ------------- | ---------------------------------------------------------------- |
| `board` | The modified board |
| `card` | The moved card |
| `source` | An object with the card source `{ fromColumnId, fromPosition }` |
| `destination` | An object with the card destination `{ toColumnId, toPosition }` |
##### Source and destination
| Prop | Description |
| -------------- | ------------------------------------------- |
| `fromColumnId` | Column source id. |
| `toColumnId` | Column destination id. |
| `fromPosition` | Card's index in column source's array. |
| `toPosition` | Card's index in column destination's array. |
#### `onColumnDragEnd`
When the user moves a column, this callback will be called passing these parameters:
| Arg | Description |
| ------------- | ------------------------------------------------------ |
| `board` | The modified board |
| `column` | The moved column |
| `source` | An object with the column source `{ fromPosition }` |
| `destination` | An object with the column destination `{ toPosition }` |
##### Source and destination
| Prop | Description |
| -------------- | ------------------------------- |
| `fromPosition` | Column index before the moving. |
| `toPosition` | Column index after the moving. |
#### `renderCard`
Use this if you want to render your own card. You have to pass a function and return your card component.
The function will receive these parameters:
| Arg | Description |
| --------- | ---------------------------------------------------------------- |
| `card` | The card props |
| `cardBag` | A bag with some helper functions and state to work with the card |
##### `cardBag`
| function | Description |
| ------------- | ----------------------------------------------------- |
| `removeCard*` | Call this function to remove the card from the column |
| `dragging` | Whether the card is being dragged or not |
\* It's unavailable when the board is controlled.
Ex.:
```js
const board = {
columns: [{
id: ${unique-required-columnId},
title: ${columnTitle},
cards: [{
id: ${unique-required-cardId},
dueDate: ${cardDueDate},
content: ${cardContent}
}]
}]
}
(
{content}
Remove Card
)}
>
{board}
```
#### `renderColumnHeader`
Use this if you want to render your own column header. You have to pass a function and return your column header component.
The function will receive these parameters:
| Arg | Description |
| ----------- | -------------------------------------------------------- |
| `column` | The column props |
| `columnBag` | A bag with some helper functions to work with the column |
##### `columnBag`
| function | Description |
| --------------- | ---------------------------------------------------------- |
| `removeColumn*` | Call this function to remove the column from the board |
| `renameColumn*` | Call this function with a title to rename the column |
| `addCard*` | Call this function with a new card to add it in the column |
**`addCard`**: As a second argument you can pass an option to define where in the column you want to add the card:
- `{ on: 'top' }`: to add on the top of the column.
- `{ on: 'bottom' }`: to add on the bottom of the column (default).
\* It's unavailable when the board is controlled.
Ex.:
```js
const board = {
columns: [{
id: ${unique-required-columnId},
title: ${columnTitle},
wip: ${wip},
cards: [{
id: ${unique-required-cardId},
title: ${required-cardTitle},
description: ${required-cardDescription}
}]
}]
}
(
{title}
Remove Column
renameColumn('New title')}>Rename Column
addCard({ id: 99, title: 'New Card' })}>Add Card
{board}
```
#### `allowAddColumn`
Allow the user to add a new column directly by the board.
#### `onNewColumnConfirm`
When the user confirms a new column through the default column adder template, this callback will be called with a draft of a column with the title typed by the user.
If your board is uncontrolled you **must** return the new column with its new id in this callback.
If your board is controlled use this to get the new column title.
Ex.:
```js
function onColumnNew (newColumn) {
const newColumn = { id: ${required-new-unique-columnId}, ...newColumn }
return newColumn
}
```
#### `onColumnNew`
When the user adds a new column through the default column adder template, this callback will be called passing the updated board and the new column.
This callback will not be called in an uncontrolled board.
#### `renderColumnAdder`
Use this if you want to render your own column adder. You have to pass a function and return your column adder component.
The function will receive these parameters:
| Arg | Description |
| ----------- | -------------------------------- |
| `columnBag` | A bag with some helper functions |
##### `columnBag`
| function | Description |
| ------------ | ---------------------------------------------------------- |
| `addColumn*` | Call this function with a new column to add the new column |
\* It's unavailable when the board is controlled.
Ex.:
```js
const ColumnAdder = ({ addColumn }) {
return (
addColumn({id: ${required-new-unique-columnId}, title: 'Title', cards:[]})}>
Add column
)
}
}
{board}
```
#### `disableColumnDrag`
Disallow the user from move a column.
#### `disableCardDrag`
Disallow the user from move a card.
#### `allowRemoveColumn`
When using the default header template, when you don't pass a template through the `renderColumnHeader`, it will allow the user to remove a column.
#### `onColumnRemove`
When the user removes a column, this callback will be called passing these parameters:
| Arg | Description |
| -------- | ------------------------------------ |
| `board` | The board without the removed column |
| `column` | The removed column |
#### `allowRenameColumn`
When using the default header template, when you don't pass a template through the `renderColumnHeader`, it will allow the user to rename a column.
#### `onColumnRename`
When the user renames a column, this callback will be called passing these parameters:
| Arg | Description |
| -------- | --------------------------------- |
| `board` | The board with the renamed column |
| `column` | The renamed column |
#### `allowRemoveCard`
When using the default card template, when you don't pass a template through the `renderCard`, it will allow the user to remove a card.
#### `onCardRemove`
When the user removes a card, this callback will be called passing these parameters:
| Arg | Description |
| -------- | ------------------------------------ |
| `board` | The board without the removed column |
| `column` | The column without the removed card |
| `card` | The removed card |
#### `allowAddCard`
Allow the user to add a card in the column directly by the board. By default, it adds the card on the bottom of the column, but you can specify whether you want to add at the top or at the bottom of the board by passing an object with 'on' prop.
E.g.:
// at the bottom by default
// in the bottom of the column
// at the top of the column
### 🔩 Helpers to be used with an controlled board
#### `moveColumn`
| Arg | Description |
| ------------------ | --------------------------------------- |
| `board` | Your board |
| `{ fromPosition }` | Index of column to be moved |
| `{ toPosition }` | Index destination of column to be moved |
#### `moveCard`
Use this on a controlled board, the "from" and "to" are the same ones passed to onCardDragEnd callback. You can used this within your onCardDragEnd call back to actually update your board as it will return a new board which you can save down into state.
| Arg | Description |
| -------------------------------- | ------------------------------------------ |
| `board` | Your board |
| `{ fromPosition, fromColumnId }` |An object with the card source `{ fromColumnId, fromPosition }` which are the indexes of the cards current position |
| `{ toPosition, toColumnId }` | An object with the card destination `{ fromColumnId, fromPosition }` which are the indexes of the cards new position |
#### `addColumn`
| Arg | Description |
| -------- | ------------------ |
| `board` | Your board |
| `column` | Column to be added |
#### `removeColumn`
| Arg | Description |
| -------- | -------------------- |
| `board` | Your board |
| `column` | Column to be removed |
#### `changeColumn`
| Arg | Description |
| -------- | ------------------------------------------------------------------------------------------------- |
| `board` | Your board |
| `column` | Column to be renamed |
| `object` | Pass a object to be merged with the column. You can add new props and/or change the existing ones |
#### `addCard`
| Arg | Description |
| ---------------------- | ----------------------------------------------------------------------------------- |
| `board` | Your board |
| `inColumn` | Column to add the card be added |
| `card` | Card to be added |
| `{ on: 'bottom|top' }` | Whether the card will be added on top or bottom of the column (`bottom` is default) |
#### `changeCard`
| Arg | Description |
| -------- | ------------------------------------------------------------------------------------------------- |
| `board` | Your board |
| `cardId` | Card's id to be changed
| `object` | Pass a object to be merged with the card. You can add new props and/or change the existing ones |
#### `onCardNew`
When the user adds a new card through the default card adder template, this callback will be called passing the updated board and the new card.
#### `onNewCardConfirm`
When the user confirms a new card through the default card adder template, this callback will be called with a draft of a card with the title and the description typed by the user.
You **must** return the new card with its new id in this callback.
Ex.:
```js
function onCardNew (newCard) {
const newCard = { id: ${required-new-unique-cardId}, ...newCard }
return newCard
}
```
#### `removeCard`
| Arg | Description |
| ------------ | ------------------------ |
| `board` | Your board |
| `fromColumn` | Column where the card is |
| `card` | Card to be removed |
## 💅🏻 Styling
You can either style all the board or import our style and override it with the styles you want:
| Class |
| ----- |
| `react-kanban-board` |
| `react-kanban-card` |
| `react-kanban-card-skeleton` |
| `react-kanban-card--dragging` |
| `react-kanban-card__description` |
| `react-kanban-card__title` |
| `react-kanban-column` |
| `react-kanban-card-adder-form` |
| `react-kanban-card-adder-button` |
| `react-kanban-card-adder-form__title` |
| `react-kanban-card-adder-form__description` |
| `react-kanban-card-adder-form__button` |
| `react-kanban-column-header` |
| `react-kanban-column-header__button` |
| `react-kanban-column-adder-button` |
## 🧪 Tests
### Unit
```shell
yarn test
```
Code coverage is saved in `coverage` folder. Open HTML report for example with
```shell
open coverage/lcov-report/index.html
```
### End-to-end
Using [Cypress](https://www.cypress.io) test runner. Start dev server and open Cypress using
```shell
yarn dev
```
All tests are in the [cypress/integration](cypress/integration) folder. These tests also collect code coverage and save in several formats in the `coverage` folder. Open HTML report
```shell
open coverage/lcov-report/index.html
```
Read [Cypress code coverage guide](https://on.cypress.io/code-coverage)
Note: to avoid inserting `babel-plugin-istanbul` twice during Jest tests, E2E tests run with `NODE_ENV=cypress` environment variable. The `babel-plugin-istanbul` plugin is included in [.babelrc](.babelrc) file only in the `cypress` Node environment, leaving the default Jest configuration during `NODE_ENV=test` the same.
## 🚴♀️ Roadmap
You can view the next features [here](https://github.com/lourenci/react-kanban/milestone/1).
Feel welcome to help us with some PRs.
## 🤝 Contributing
PRs are welcome:
- Fork this project.
- Setup it:
```
yarn
yarn start
```
- Make your change.
- Please add yourself to the contributors table (we use [all contributors](https://allcontributors.org/docs/en/cli/installation) for that, we you will need that installed first):
```
yarn contributors:add
```
- Open the PR.
### ✍️ Guidelines for contributing
- You need to test your change.
- Try to be clean on your change. CodeClimate will keep an eye on you.
- It has to pass on CI.