ozen-kanban

Özen UI Kanban

Инструментарий для создания канбан–досок из компонентов Ozen UI

---

Установка

Чтобы добавить библиотеку в зависимости вашего проекта, выполните в терминале:

pnpm add ozen-kanban

Использование

Перед началом использования надо подготовить данные в формате подходящем для компонентов. Для этого используется хук useBoard. В качестве параметров он принимает данные, схему и вспомогательные функции.

export function useBoard<T>(
  data: T[],
  options: {
    groups: KanbanGroupSchema[];
    groupBy: (data: T, index: number) => string;
    key: (data: T) => string;
    sort?: (a: T, b: T) => number;
  }
) {}

В параметре groups задаётся структура доски. Она представляет собой массив объектов групп, в которые входят колонки.

ℹ️ Такая структура нужна для поддержки досок, где под одним статусом есть несколько подстатусов.

const todoGroups: KanbanGroupSchema[] = [
  {
    title: 'Надо сделать',
    variant: 'neutral',
    columns: [
      {
        id: 'BACKLOG',
      },
    ],
  },
  {
    title: 'В работе',
    variant: 'info',
    columns: [
      {
        title: 'WIP',
        id: 'IN_PROGRESS',
      },
      {
        title: 'Тестирование'
        id: 'TESTING',
      },
    ],
  },
  {
    title: 'Готово',
    variant: 'success',
    columns: [
      {
        id: 'DONE',
      },
    ],
  },
];

В параметр groupBy нужно передать функцию, которая будет извлекать из объекта группировочный признак и возвращать его строкой, которая является id колонки. Пример более сложной группировки можно увидеть в usecases/partners/schema.ts

{
  groupBy: ({ status }) => status
}

В параметр key нужно передать функцию, которая будет извлекать из объекта уникальный строковый ключ.

{
  key: ({ id }) => id
}

В опциональный параметр sort можно передать сортировчную функцию для карточек. Сигнатура идентична параметра Array.sort.

Компонент

Полученные данные надо передать в компонент, который отрисует доску.

import { DraggableBoard, useBoard } from 'ozen-kanban'

const AwesomeBoard: FC = () => {
  const { columns, groups } = useBoard(data, options);

  return (
    <DraggableBoard
      columns={columns}
      groups={groups}
      renderData={JSON.stringify}
      onDrop={console.log}
    />
  );
};

Параметр renderData принимает компонент или функцию, который отрисуют переданный тип данных в формат карточки.

Кастомизация

С помощью дополнительных свойств компонента DraggableBoard можно заменить компоненты, из которых строится доска:

• cardComponent — Карточка.
• columnComponent — Колонка.

Ограничения

• Максимум 11 колонок;
• Данные обязательно должны иметь уникальный ключ;
• Входный массив не должен мутироваться. Если данные изменились — ссылка тоже должна измениться.

Разработка

Для запуска тестовой площадки в браузере, выполните в терминале:

pnpm dev