@etus/ui 0.1.0

package/src/components/workflow/KanbanBoard/README.md

@@ -0,0 +1,495 @@
+# KanbanBoard
+
+## Visão Geral
+
+O KanbanBoard e um componente de gerenciamento visual de tarefas baseado no metodo Kanban. Ele organiza itens em colunas que representam estagios de um processo, permitindo movimentacao por drag-and-drop e visualizacao do fluxo de trabalho.
+
+### Classificacao Atomica
+- **Categoria**: Organisms
+- **Subcategoria**: Workflow / Project Management
+
+### Casos de Uso Comuns
+- Gerenciamento de projetos ageis
+- Acompanhamento de tarefas de equipe
+- Pipeline de vendas
+- Fluxos de atendimento ao cliente
+- Gerenciamento de conteudo editorial
+
+### Relacao com Outros Componentes
+- **TaskCard**: Cards dentro das colunas
+- **DragAndDrop**: Sistema de movimentacao
+- **Avatar**: Responsaveis por tarefas
+- **Badge**: Tags e prioridades
+- **Dialog**: Detalhes e edicao de tarefas
+
+## Design Specs
+
+### Variantes
+- **Default**: Colunas horizontais scrollaveis
+- **Compact**: Cards menores, mais densidade
+- **Swimlanes**: Linhas horizontais por categoria
+- **Collapsed**: Colunas colapsaveis
+
+### Layouts
+- **Horizontal**: Colunas lado a lado (padrao)
+- **Vertical**: Colunas empilhadas (mobile)
+
+### Estados
+- **Normal**: Visualizacao padrao
+- **Dragging**: Item sendo arrastado
+- **Filtering**: Filtros aplicados
+- **Loading**: Carregando dados
+- **Empty**: Sem tarefas
+
+### Tokens de Design
+
+#### Cores
+- Board Background: `bg-muted/30`
+- Column Background: `bg-muted/50`
+- Column Header: `bg-card`
+- Card Background: `bg-card`
+- Drop Indicator: `bg-primary/20 border-primary`
+- WIP Limit Warning: `text-warning`
+- WIP Limit Exceeded: `text-destructive`
+
+#### Espacamento
+- Board Padding: `p-4`
+- Column Gap: `gap-4`
+- Card Gap: `gap-2`
+- Card Padding: `p-3`
+- Column Width: `w-72` ou `w-80`
+
+#### Tipografia
+- Column Title: `text-sm font-semibold`
+- Card Title: `text-sm font-medium`
+- Card Description: `text-xs text-muted-foreground`
+
+#### Bordas e Arredondamento
+- Column: `rounded-lg`
+- Card: `rounded-md border shadow-sm`
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `columns` | `Column[]` | `[]` | Colunas do board |
+| `items` | `KanbanItem[]` | `[]` | Itens (tarefas) |
+| `variant` | `'default' \| 'compact' \| 'swimlanes' \| 'collapsed'` | `'default'` | Estilo visual |
+| `columnWidth` | `number \| string` | `288` | Largura das colunas |
+| `allowAddColumn` | `boolean` | `false` | Permite adicionar colunas |
+| `allowAddItem` | `boolean` | `true` | Permite adicionar itens |
+| `allowColumnReorder` | `boolean` | `false` | Permite reordenar colunas |
+| `showWipLimits` | `boolean` | `true` | Exibe limites WIP |
+| `showColumnCount` | `boolean` | `true` | Exibe contagem de itens |
+| `groupBy` | `string` | - | Campo para swimlanes |
+| `filterBy` | `FilterConfig` | - | Configuracao de filtros |
+| `searchable` | `boolean` | `false` | Habilita busca |
+| `className` | `string` | `''` | Classes CSS adicionais |
+
+### Eventos
+
+| Evento | Payload | Descricao |
+|--------|---------|-----------|
+| `onItemMove` | `{ itemId: string, fromColumn: string, toColumn: string, index: number }` | Item movido |
+| `onItemClick` | `{ item: KanbanItem }` | Item clicado |
+| `onItemAdd` | `{ columnId: string }` | Novo item solicitado |
+| `onItemUpdate` | `{ itemId: string, updates: Partial<KanbanItem> }` | Item atualizado |
+| `onItemDelete` | `{ itemId: string }` | Item deletado |
+| `onColumnAdd` | - | Nova coluna solicitada |
+| `onColumnUpdate` | `{ columnId: string, updates: Partial<Column> }` | Coluna atualizada |
+| `onColumnDelete` | `{ columnId: string }` | Coluna deletada |
+| `onColumnReorder` | `{ columnId: string, newIndex: number }` | Coluna reordenada |
+
+### Interfaces TypeScript
+
+```typescript
+export interface Column {
+  id: string;
+  title: string;
+  color?: string;
+  wipLimit?: number;
+  isCollapsed?: boolean;
+  order?: number;
+}
+
+export interface KanbanItem {
+  id: string;
+  title: string;
+  description?: string;
+  columnId: string;
+  order: number;
+  priority?: 'low' | 'medium' | 'high' | 'urgent';
+  assignees?: User[];
+  labels?: Label[];
+  dueDate?: Date;
+  estimate?: number;
+  progress?: number;
+  attachments?: number;
+  comments?: number;
+  subtasks?: { completed: number; total: number };
+  customFields?: Record<string, unknown>;
+}
+
+export interface Label {
+  id: string;
+  name: string;
+  color: string;
+}
+
+export interface User {
+  id: string;
+  name: string;
+  avatar?: string;
+}
+
+export interface FilterConfig {
+  assignees?: string[];
+  labels?: string[];
+  priority?: string[];
+  dueDate?: { from?: Date; to?: Date };
+}
+
+export interface KanbanBoardProps {
+  columns: Column[];
+  items: KanbanItem[];
+  variant?: 'default' | 'compact' | 'swimlanes' | 'collapsed';
+  columnWidth?: number | string;
+  allowAddColumn?: boolean;
+  allowAddItem?: boolean;
+  allowColumnReorder?: boolean;
+  showWipLimits?: boolean;
+  showColumnCount?: boolean;
+  groupBy?: string;
+  filterBy?: FilterConfig;
+  searchable?: boolean;
+  className?: string;
+  onItemMove?: (data: { itemId: string; fromColumn: string; toColumn: string; index: number }) => void;
+  onItemClick?: (data: { item: KanbanItem }) => void;
+  onItemAdd?: (data: { columnId: string }) => void;
+  onItemUpdate?: (data: { itemId: string; updates: Partial<KanbanItem> }) => void;
+  onItemDelete?: (data: { itemId: string }) => void;
+  onColumnAdd?: () => void;
+  onColumnUpdate?: (data: { columnId: string; updates: Partial<Column> }) => void;
+  onColumnDelete?: (data: { columnId: string }) => void;
+  onColumnReorder?: (data: { columnId: string; newIndex: number }) => void;
+}
+```
+
+### Comparacao com Referencias
+- **Trello**: Inspiracao principal para UX
+- **Jira Board**: Referencia para swimlanes e filtros
+- **Linear**: Modelo para design minimalista
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+- `role="region"`: Container do board
+- `role="list"`: Cada coluna
+- `role="listitem"`: Cada card
+- `aria-grabbed`: Item sendo arrastado
+- `aria-dropeffect`: Coluna como zona de drop
+
+### Navegacao por Teclado
+- `Tab`: Navega entre colunas e cards
+- `Arrow Keys`: Move entre cards na coluna
+- `Space`: Inicia/termina arrasto
+- `Enter`: Abre detalhes do card
+- `Delete`: Remove card selecionado
+
+### Screen Readers
+- Anuncio de coluna e posicao
+- Confirmacao de movimentacao
+- Contagem de itens por coluna
+
+### Conformidade WCAG
+- Nivel: WCAG 2.1 AA
+- Criterios: 1.3.1, 2.1.1, 4.1.2
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { KanbanBoard } from '@etus/ui';
+
+const columns = [
+  { id: 'todo', title: 'A Fazer' },
+  { id: 'doing', title: 'Em Progresso' },
+  { id: 'done', title: 'Concluido' }
+];
+
+const items = [
+  { id: '1', title: 'Tarefa 1', columnId: 'todo', order: 0 },
+  { id: '2', title: 'Tarefa 2', columnId: 'doing', order: 0 },
+  { id: '3', title: 'Tarefa 3', columnId: 'done', order: 0 }
+];
+
+export function BasicKanban() {
+  const handleMove = ({ itemId, fromColumn, toColumn }) => {
+    console.log(`Movendo ${itemId} de ${fromColumn} para ${toColumn}`);
+  };
+
+  return (
+    <KanbanBoard
+      columns={columns}
+      items={items}
+      onItemMove={handleMove}
+    />
+  );
+}
+```
+
+### Com Limites WIP
+
+```tsx
+import { KanbanBoard } from '@etus/ui';
+
+const columnsWithWip = [
+  { id: 'todo', title: 'A Fazer' },
+  { id: 'doing', title: 'Em Progresso', wipLimit: 3 },
+  { id: 'review', title: 'Em Revisao', wipLimit: 2 },
+  { id: 'done', title: 'Concluido' }
+];
+
+export function KanbanWithWipLimits() {
+  return (
+    <KanbanBoard
+      columns={columnsWithWip}
+      items={items}
+      showWipLimits={true}
+    />
+  );
+}
+```
+
+### Cards Detalhados
+
+```tsx
+import { KanbanBoard } from '@etus/ui';
+
+const detailedItems = [
+  {
+    id: '1',
+    title: 'Implementar autenticacao',
+    description: 'Adicionar login com OAuth',
+    columnId: 'doing',
+    order: 0,
+    priority: 'high',
+    assignees: [{ id: '1', name: 'Maria', avatar: '/maria.jpg' }],
+    labels: [{ id: '1', name: 'Backend', color: 'blue' }],
+    dueDate: new Date('2024-02-01'),
+    subtasks: { completed: 2, total: 5 },
+    comments: 3
+  }
+];
+
+export function KanbanWithDetailedCards() {
+  return (
+    <KanbanBoard
+      columns={columns}
+      items={detailedItems}
+      onItemClick={({ item }) => openItemDetail(item)}
+    />
+  );
+}
+```
+
+### Com Swimlanes
+
+```tsx
+import { KanbanBoard } from '@etus/ui';
+
+const itemsWithCategory = [
+  { id: '1', title: 'Bug critico', columnId: 'todo', category: 'Bugs' },
+  { id: '2', title: 'Nova feature', columnId: 'todo', category: 'Features' },
+  { id: '3', title: 'Outro bug', columnId: 'doing', category: 'Bugs' }
+];
+
+export function KanbanWithSwimlanes() {
+  return (
+    <KanbanBoard
+      columns={columns}
+      items={itemsWithCategory}
+      variant="swimlanes"
+      groupBy="category"
+    />
+  );
+}
+```
+
+### Com Filtros
+
+```tsx
+import { KanbanBoard } from '@etus/ui';
+import { useState } from 'react';
+
+export function KanbanWithFilters() {
+  const [filters, setFilters] = useState({
+    priority: ['high', 'urgent'],
+    assignees: []
+  });
+
+  return (
+    <KanbanBoard
+      columns={columns}
+      items={items}
+      filterBy={filters}
+      searchable={true}
+    />
+  );
+}
+```
+
+### Colunas Reordenaveis
+
+```tsx
+import { KanbanBoard } from '@etus/ui';
+import { useState } from 'react';
+
+export function KanbanWithReorderableColumns() {
+  const [columns, setColumns] = useState(initialColumns);
+
+  const handleColumnReorder = ({ columnId, newIndex }) => {
+    // Reordenar colunas
+  };
+
+  return (
+    <KanbanBoard
+      columns={columns}
+      items={items}
+      allowColumnReorder={true}
+      allowAddColumn={true}
+      onColumnReorder={handleColumnReorder}
+      onColumnAdd={() => console.log('Adicionar coluna')}
+    />
+  );
+}
+```
+
+### Variante Compacta
+
+```tsx
+import { KanbanBoard } from '@etus/ui';
+
+export function CompactKanban() {
+  return (
+    <KanbanBoard
+      columns={columns}
+      items={items}
+      variant="compact"
+      columnWidth={240}
+    />
+  );
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+- Renderizacao de colunas e cards
+- Calculo de WIP limits
+- Aplicacao de filtros
+
+#### Testes de Integracao
+- Drag and drop entre colunas
+- Adicao e remocao de itens
+- Reordenacao
+
+#### Testes de Acessibilidade
+- Navegacao por teclado
+- Movimentacao sem mouse
+
+### Exemplos de Codigo
+
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react';
+import { KanbanBoard } from './KanbanBoard';
+
+describe('KanbanBoard', () => {
+  const mockColumns = [
+    { id: 'todo', title: 'To Do' },
+    { id: 'done', title: 'Done' }
+  ];
+
+  const mockItems = [
+    { id: '1', title: 'Task 1', columnId: 'todo', order: 0 }
+  ];
+
+  it('renders all columns', () => {
+    render(<KanbanBoard columns={mockColumns} items={mockItems} />);
+    expect(screen.getByText('To Do')).toBeInTheDocument();
+    expect(screen.getByText('Done')).toBeInTheDocument();
+  });
+
+  it('renders items in correct columns', () => {
+    render(<KanbanBoard columns={mockColumns} items={mockItems} />);
+    const todoColumn = screen.getByText('To Do').closest('[role="list"]');
+    expect(todoColumn).toContainElement(screen.getByText('Task 1'));
+  });
+
+  it('calls onItemMove when dragging item', async () => {
+    const onItemMove = vi.fn();
+    render(
+      <KanbanBoard
+        columns={mockColumns}
+        items={mockItems}
+        onItemMove={onItemMove}
+      />
+    );
+
+    const item = screen.getByText('Task 1');
+    const doneColumn = screen.getByText('Done').closest('[role="list"]');
+
+    fireEvent.dragStart(item);
+    fireEvent.drop(doneColumn);
+
+    expect(onItemMove).toHaveBeenCalledWith(
+      expect.objectContaining({
+        itemId: '1',
+        fromColumn: 'todo',
+        toColumn: 'done'
+      })
+    );
+  });
+
+  it('shows WIP limit warning', () => {
+    const columnsWithWip = [
+      { id: 'doing', title: 'Doing', wipLimit: 2 }
+    ];
+    const items = [
+      { id: '1', title: 'Task 1', columnId: 'doing', order: 0 },
+      { id: '2', title: 'Task 2', columnId: 'doing', order: 1 }
+    ];
+
+    render(
+      <KanbanBoard
+        columns={columnsWithWip}
+        items={items}
+        showWipLimits={true}
+      />
+    );
+
+    expect(screen.getByText('2/2')).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Usar @dnd-kit para drag-and-drop
+- Virtualizar cards para boards grandes
+- Otimistic updates para movimentacao
+- Persistir estado no localStorage
+
+## Referências
+
+- [Trello](https://trello.com)
+- [Jira Board](https://www.atlassian.com/software/jira)
+- [Linear](https://linear.app)
+- [@dnd-kit](https://dndkit.com/)

package/src/components/workflow/KanbanBoard/index.ts

@@ -0,0 +1,40 @@
+export type {
+  ColumnDeletePayload,
+  ColumnReorderPayload,
+  ColumnUpdatePayload,
+  ItemAddPayload,
+  ItemClickPayload,
+  ItemDeletePayload,
+  ItemMovePayload,
+  ItemUpdatePayload,
+  KanbanBoardProps,
+  KanbanCardProps,
+  KanbanColumn,
+  KanbanColumnProps,
+  KanbanFilterConfig,
+  KanbanItem,
+  KanbanLabel,
+  KanbanSubtasks,
+  KanbanUser,
+} from "./KanbanBoard.types"
+
+export {
+  KanbanBoard,
+  kanbanBoardVariants,
+  KanbanCard,
+  kanbanCardVariants,
+  kanbanColumnVariants,
+} from "./KanbanBoard"
+
+export {
+  kanbanAddButtonVariants,
+  kanbanCardDescriptionVariants,
+  kanbanCardMetaVariants,
+  kanbanCardTitleVariants,
+  kanbanColumnContentVariants,
+  kanbanColumnHeaderVariants,
+  kanbanDropIndicatorVariants,
+  kanbanLabelVariants,
+  kanbanSearchVariants,
+  kanbanSwimlaneVariants,
+} from "./KanbanBoard.variants"