caldwell619 React Kanban

asseinfo's React Kanban

Forked from asseinfo's React Kanban

Shout out to all the contributors.

Leandro Lourenci 💬 🐛 💻 📖 💡 ⚠️

Gleb Bahmutov ⚠️

Matheus Sabino 💻 📖 ⚠️

Pedro Javier Nicolás 💻

Matheus Poli 💻 ⚠️ 📖

Carlinhos de Sousa Junior 💻 ⚠️

Pete Duncanson 💻 📖 💡

Why fork?

• The original library seems to not be maintained anymore. The last commit at this time is September of 2021.
• The original library did not include TypeScript types. It was written in JS without providing any types. This fork is natively written in TypeScript.

Road Map

Here is what's in the queue. If you want to see something, make an issue

Demo

Link

Setup

yarn add @caldwell619/react-kanban

You will also need to install the peer dependencies on your own:

  "peerDependencies": {
    "react": ">=16",
    "react-dom": ">=16",
    "@hello-pangea/dnd": ">=16"
  },

These are listed as peer dependencies because I do not want to pin specific versions as dependencies if you are already using them.

Usage

There are 2 main boards, Controlled and Uncontrolled.

This is a deviation from the original, as there was only one board exported. In the original, there's an in-library determination on whether or not the board is controlled. That is not quite how this works, as you will know upfront whether or not your board is controlled.

With that in mind, you can import each of the boards like this:

import { UncontrolledBoard, KanbanBoard } from '@caldwell619/react-kanban'
// import { ControlledBoard } from '@caldwell619/react-kanban'
import '@caldwell619/react-kanban/dist/styles.css' // import here for "builtin" styles

const board: KanbanBoard = {
  columns: [
    {
      id: 1,
      title: 'Backlog',
      cards: [
        {
          id: 1,
          title: 'Add card',
          description: 'Add capability to add a card in a column'
        },
      ]
    },
    { ... }
  ]
}

<UncontrolledBoard initialBoard={board} />

Uncontrolled

With an uncontrolled board, you pass an initialBoard prop, which will be the basis of the internal state. When a user moves something, that is all controlled by internal state.

Controlled

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.

If you go with the controlled one, you need to pass your board through the children prop.

Board

If you really want to use the one unified board, you can still do so with Board. Whether or not you provide initialBoard or children will determine which board you're using. If you provide both, UncontrolledBoard takes priority.

See an example, here.

Helpers to work with the controlled board

Helpers are exposed to help with the management of your board state when using the ControlledBoard. They are the same helpers used internally, so you can utilize them to assist in your controlled state.

import { ControlledBoard, moveCard, KanbanBoard, OnDragEndNotification, Card } from '@caldwell619/react-kanban'

const MyBoard = () => {
  const [board, setBoard] = useState<KanbanBoard>(initialBoard)

  const handleCardMove: OnDragEndNotification<Card> = (_card, source, destination) => {
    setBoard((currentBoard) => {
      return moveCard(currentBoard, source, destination)
    })
  }

  return <ControlledBoard onCardDragEnd={handleCardMove}>{board}</ControlledBoard>
}

Full list of helpers.

Board type

If you're using JS, this section doesn't have any effect on you.

The TypeScript type for the board is KanbanBoard. It is a generic that accepts TCard extends Card. Your data will undoubtedly need to be customized, so all the helpers and Board will accept your TCard.

import { Card } from '@caldwell619/react-kanban'

interface CustomCard extends Card {
  storyPoints: number
}
export const renderCard: UncontrolledBoardProps<CustomCard>['renderCard'] = (card) => {
  // Can access with `card.storyPoints`
  return <CardWithStoryPoints {...card} />
}

This behavior will applied throughout the render and confirm methods.

import { ControlledBoard, KanbanBoard } from '@caldwell619/react-kanban'

const CustomBoard = () => {
  return (
    <ControlledBoard<CustomCard>
      renderCard={(card) => {
        // `card.storyPoints`
        return <CardWithStoryPoints {...card} />
      }}
    >
      {board}
    </ControlledBoard>
  )
}

Props

For an exhaustive ( yet still WIP ) list of props you can pass, refer to this page.

Styling

You can either style all the board or import our style and override it with the styles you want. Ideally you would render the column instead of overriding CSS, however this may be helpful for you if your use case needs it.

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

Usage with Remix

Shout out to @vjanssens for discovering there are some extra steps for compatibility with Remix.

Add the following to your Vite config:

export default defineConfig({
  // the rest of your config
  ssr: {
    noExternal: ["@caldwell619/react-kanban"]
  },
});

Contributing

PRs are welcome.

Steps

• File an issue, using the issue template.
• Fork this project.
• Clone your fork
• In your fork, run yarn to install deps
• Begin work
• Add yourself to the contributors table, this is powered by all-contributors
  • yarn all-contributors add
  • yarn all-contributors generate
• Submit your PR across forks with the target base as christopher-caldwell:master.