Skip to content
Yet another Kanban/Trello board lib for React.
JavaScript HTML
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Use codecov token from an env var instead of from the secret Feb 25, 2020
__mocks__ Add capability to drag-and-drop lanes (#27) Apr 13, 2019
assets refactor: Rename lane to column (#252) Feb 9, 2020
cypress chore(deps): update dependency eslint-plugin-cypress to v2.10.3 (#239) Feb 21, 2020
src fix: Call onCardDragEnd and onColumnDragEnd only when the movement is… Feb 13, 2020
.all-contributorsrc Pass the moved card on the onCardDragEnd callback (#199) Jan 14, 2020
.codeclimate.yml Enable eslint on CodeClimate Feb 25, 2020
.eslintrc.json Configure eslint properly (#242) Feb 6, 2020
.gitignore Remove docz leftovers Feb 2, 2020
.prettierrc Welcome, Prettier Nov 15, 2019
CHANGELOG.md Add CHANGELOG.md Sep 16, 2019
LICENSE.txt Add MIT license Apr 7, 2019
README.md chore: Use codecov instead of codeclimate for coverage report (#271) Feb 25, 2020
babel.config.js Use babel.config.js insted of .babelrc Feb 3, 2020
cypress.json Add code coverage for Cypress tests (#100) Sep 7, 2019
doczrc.js Install docz (#148) Oct 1, 2019
gatsby-node.js Configure Docz to resolve the webpack's alias (#155) Oct 2, 2019
jest.config.js Upgrade RTL to 9.4.0 (#217) Jan 28, 2020
package.json chore(deps): update dependency @testing-library/react to v9.4.1 (#267) Feb 25, 2020
renovate.json Fix renovate-bot to automerge patches and pins Jan 30, 2020
webpack.dev.js Add source map and don't watch for node_modules in dev server Feb 3, 2020
webpack.prod.js Remove react libs from bundle Feb 3, 2020

README.md

Maintainability Test Coverage Build Status JavaScript Style Guide

Yet another Kanban/Trello board lib for React.

Kanban Demo

▶️ Demo

Usage

Edit react-kanban-demo

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 and Styled Components, you have to install them:

  • react>=16.8.5
  • styled-components>=4

After, Install the lib on your project:

yarn add @lourenci/react-kanban

Import the lib and use it on your project:

import Board from '@lourenci/react-kanban'

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'
        },
      ]
    }
  ]
}

<Board initialBoard={board} />

🔥 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 <Board />, 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 and here.

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:

import Board, { addCard, addColumn, ... } from '@lourenci/react-kanban'

All the helpers you need to pass your board and they will return a new board to pass to your state:

import Board, { addColumn } from '@lourenci/react-kanban'
...
const [board, setBoard] = useState(initialBoard)
...
const newBoard = addColumn(board, newColumn)
setBoard(newBoard)
...
<Board>{board}</Board>

You can see the list of helpers in the end of the props documentation.

🔷 Shape of a board

{
  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 prop.

** The title is required if you are using the column's default template. You can render your own column template through the renderColumnHeader prop.

⚙️ Props

Prop Description Controlled Uncontrolled
children (required if controlled) The board to render 🚫
initialBoard (required if uncontrolled) The board to render 🚫
onCardDragEnd Callback that will be called when the card move ends
onColumnDragEnd Callback that will be called when the column move ends
renderCard A card to be rendered instead of the default card
renderColumnHeader A column header to be rendered instead of the default column header
allowAddColumn Allow a new column be added by the user
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 (required if allowAddColumn or when addColumn is called) Callback that will be called when a new column is added through the default column adder template 🚫
renderColumnAdder A column adder to be rendered instead of the default column adder template
disableColumnDrag Disable the column move
disableCardDrag Disable the card move
allowRemoveColumn Allow to remove a column in default column header
onColumnRemove (required if allowRemoveColumn or when removeColumn is called) Callback that will be called when a column is removed
allowRenameColumn Allow to rename a column in default column header
onColumnRename (required if allowRenameColumn or when renameColumn is called) Callback that will be called when a column is renamed
allowRemoveCard Allow to remove a card in default card template
onCardRemove (required if allowRemoveCard) Callback that will be called when a card is removed
onCardNew (required if addCard is called) Callback that will be called when a new card is added 🚫

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

const board = {
  columns: [{
    id: ${unique-required-columnId},
    title: ${columnTitle},
    cards: [{
      id: ${unique-required-cardId},
      dueDate: ${cardDueDate},
      content: ${cardContent}
    }]
  }]
}

<Board
  renderCard={({ content }, { removeCard, dragging }) => (
    <YourCard dragging={dragging}>
      {content}
      <button type="button" onClick={removeCard}>Remove Card</button>
    </YourCard>
  )}
>
{board}
</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.:

const board = {
  columns: [{
    id: ${unique-required-columnId},
    title: ${columnTitle},
    wip: ${wip},
    cards: [{
      id: ${unique-required-cardId},
      title: ${required-cardTitle},
      description: ${required-cardDescription}
    }]
  }]
}

<Board
  renderColumnHeader={({ title }, { removeColumn, renameColumn, addCard }) => (
    <YourColumnHeader>
      {title}
      <button type='button' onClick={removeColumn}>Remove Column</button>
      <button type='button' onClick={() => renameColumn('New title')}>Rename Column</button>
      <button type='button' onClick={() => addCard({ id: 99, title: 'New Card' })}>Add Card</button>
    </YourColumnHeader
  )}
>
  {board}
</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.:

function onColumnNew (newColumn) {
  const newColumn = { id: ${required-new-unique-columnId}, ...newColumn }
  return newColumn
}

<Board initialBoard={board} allowAddColumn onColumnNew={onColumnNew} />

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

const ColumnAdder = ({ addColumn }) {
  return (
    <div onClick={()=> addColumn({id: ${required-new-unique-columnId}, title: 'Title', cards:[]})}>
      Add column
    </div>
  )
}

<Board
  allowAddColumn
  renderColumnAdder={({ addColumn }) => <ColumnAdder addColumn={addColumn} />}
  {board}
</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

🔩 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

Arg Description
board Your board
{ fromPosition, fromColumnId } Index and columnId of card to be moved
{ toPosition, toColumnId } Index and columnId of the card destination

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' }`

removeCard

Arg Description
board Your board
fromColumn Column where the card is
card Card to be removed

🧪 Tests

Unit

yarn test

Code coverage is saved in coverage folder. Open HTML report for example with

open coverage/lcov-report/index.html

End-to-end

Using Cypress test runner. Start dev server and open Cypress using

yarn dev

All tests are in the cypress/integration folder. These tests also collect code coverage and save in several formats in the coverage folder. Open HTML report

open coverage/lcov-report/index.html

Read Cypress code coverage guide

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 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. Feel welcome to help us with some PRs.

🤝 Contributing

PRs are welcome:

  • Fork this project.
  • Setup it:
    yarn
    yarn start
    
  • Make your change.
  • Add yourself to the contributors table:
    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.

🤖 Contributors

Thanks goes to these wonderful people (emoji key):

Leandro Lourenci
Leandro Lourenci

💬 🐛 💻 📖 💡 ⚠️
Gleb Bahmutov
Gleb Bahmutov

⚠️
Matheus Sabino
Matheus Sabino

💻 📖
Pedro Javier Nicolás
Pedro Javier Nicolás

💻
Matheus Poli
Matheus Poli

💻 ⚠️ 📖
Carlinhos de Sousa Junior
Carlinhos de Sousa Junior

💻 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!

You can’t perform that action at this time.