@etus/ui 0.1.0

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

@@ -0,0 +1,450 @@
+# ApprovalFlow
+
+## Visão Geral
+
+O ApprovalFlow e um componente de orquestracao de fluxos de aprovacao que gerencia sequencias de decisoes e aprovacoes em processos empresariais. Ele visualiza e controla o progresso atraves de multiplas etapas de aprovacao, permitindo aprovacoes paralelas ou sequenciais com suporte a delegacao e escalacao.
+
+### Classificacao Atomica
+- **Categoria**: Organisms
+- **Subcategoria**: Workflow
+
+### Casos de Uso Comuns
+- Aprovacao de documentos e contratos
+- Fluxos de requisicao de compras
+- Processos de onboarding de funcionarios
+- Revisao e publicacao de conteudo
+- Solicitacoes de ferias e licencas
+- Aprovacao de despesas e reembolsos
+
+### Relacao com Outros Componentes
+- **Stepper**: Usado internamente para visualizar o progresso do fluxo
+- **ApprovalStatus**: Exibe o status de cada etapa de aprovacao
+- **Avatar**: Mostra os aprovadores em cada etapa
+- **Button**: Acoes de aprovar, rejeitar, delegar
+- **Dialog**: Confirmacoes e comentarios de aprovacao
+
+## Design Specs
+
+### Variantes
+- **Linear**: Fluxo sequencial onde cada etapa depende da anterior
+- **Parallel**: Multiplas aprovacoes podem ocorrer simultaneamente
+- **Conditional**: Fluxo com ramificacoes baseadas em condicoes
+- **Hybrid**: Combinacao de etapas lineares e paralelas
+
+### Layouts
+- **Horizontal**: Etapas dispostas horizontalmente (padrao)
+- **Vertical**: Etapas empilhadas verticalmente
+- **Compact**: Versao condensada para espacos reduzidos
+
+### Estados
+- **Pending**: Aguardando inicio do fluxo
+- **In Progress**: Fluxo em andamento
+- **Awaiting Approval**: Aguardando decisao de aprovadores
+- **Approved**: Fluxo aprovado com sucesso
+- **Rejected**: Fluxo rejeitado
+- **Escalated**: Fluxo escalado para nivel superior
+- **Cancelled**: Fluxo cancelado
+
+### Tokens de Design
+
+#### Cores
+- Background Container: `bg-card`
+- Step Pending: `bg-muted`
+- Step Active: `bg-primary`
+- Step Approved: `bg-success`
+- Step Rejected: `bg-destructive`
+- Step Escalated: `bg-warning`
+- Connector Line: `border-muted-foreground/30`
+
+#### Espacamento
+- Padding Container: `p-6`
+- Gap entre Steps: `gap-4`
+- Step Padding: `p-4`
+
+#### Tipografia
+- Step Title: `text-sm font-medium`
+- Step Description: `text-xs text-muted-foreground`
+- Approver Name: `text-sm`
+
+#### Bordas e Arredondamento
+- Container: `rounded-lg border`
+- Step Cards: `rounded-md`
+- Connectors: `border-2 border-dashed`
+
+#### Motion e Transicoes
+- Step Transition: `transition-all duration-300`
+- Status Change: `animate-pulse` (momentaneo)
+
+### Consideracoes de Responsividade
+- **Mobile (< 640px)**: Layout vertical obrigatorio, cards colapsaveis
+- **Tablet (640px - 1024px)**: Layout horizontal com scroll
+- **Desktop (> 1024px)**: Layout horizontal completo
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `steps` | `ApprovalStep[]` | `[]` | Array de etapas do fluxo |
+| `currentStep` | `number` | `0` | Indice da etapa atual |
+| `variant` | `'linear' \| 'parallel' \| 'conditional' \| 'hybrid'` | `'linear'` | Tipo de fluxo |
+| `layout` | `'horizontal' \| 'vertical' \| 'compact'` | `'horizontal'` | Orientacao do layout |
+| `allowDelegation` | `boolean` | `true` | Permite delegacao de aprovacoes |
+| `allowEscalation` | `boolean` | `true` | Permite escalacao para superiores |
+| `showTimeline` | `boolean` | `true` | Exibe linha do tempo de acoes |
+| `showComments` | `boolean` | `true` | Exibe comentarios dos aprovadores |
+| `readOnly` | `boolean` | `false` | Modo somente leitura |
+| `className` | `string` | `''` | Classes CSS adicionais |
+
+### Eventos
+
+| Evento | Payload | Descricao |
+|--------|---------|-----------|
+| `onApprove` | `{ stepId: string, comment?: string }` | Disparado ao aprovar etapa |
+| `onReject` | `{ stepId: string, reason: string }` | Disparado ao rejeitar etapa |
+| `onDelegate` | `{ stepId: string, delegateTo: User }` | Disparado ao delegar aprovacao |
+| `onEscalate` | `{ stepId: string, escalateTo: User }` | Disparado ao escalar aprovacao |
+| `onStepChange` | `{ previousStep: number, currentStep: number }` | Disparado ao mudar de etapa |
+| `onComplete` | `{ status: 'approved' \| 'rejected', history: ApprovalHistory[] }` | Disparado ao completar fluxo |
+
+### Interfaces TypeScript
+
+```typescript
+export interface ApprovalStep {
+  id: string;
+  title: string;
+  description?: string;
+  approvers: Approver[];
+  status: ApprovalStepStatus;
+  requiredApprovals?: number; // Para aprovacoes paralelas
+  deadline?: Date;
+  conditions?: ApprovalCondition[];
+  actions?: ApprovalAction[];
+}
+
+export interface Approver {
+  id: string;
+  name: string;
+  email: string;
+  avatar?: string;
+  role: string;
+  department?: string;
+  canDelegate?: boolean;
+}
+
+export type ApprovalStepStatus =
+  | 'pending'
+  | 'in_progress'
+  | 'awaiting'
+  | 'approved'
+  | 'rejected'
+  | 'escalated'
+  | 'skipped';
+
+export interface ApprovalCondition {
+  field: string;
+  operator: 'equals' | 'greater_than' | 'less_than' | 'contains';
+  value: unknown;
+  nextStepId?: string;
+}
+
+export interface ApprovalAction {
+  type: 'approve' | 'reject' | 'delegate' | 'escalate' | 'request_info';
+  label: string;
+  icon?: React.ReactNode;
+  requiresComment?: boolean;
+  confirmationMessage?: string;
+}
+
+export interface ApprovalHistory {
+  stepId: string;
+  action: string;
+  actor: Approver;
+  timestamp: Date;
+  comment?: string;
+}
+
+export interface ApprovalFlowProps {
+  steps: ApprovalStep[];
+  currentStep?: number;
+  variant?: 'linear' | 'parallel' | 'conditional' | 'hybrid';
+  layout?: 'horizontal' | 'vertical' | 'compact';
+  allowDelegation?: boolean;
+  allowEscalation?: boolean;
+  showTimeline?: boolean;
+  showComments?: boolean;
+  readOnly?: boolean;
+  className?: string;
+  onApprove?: (data: { stepId: string; comment?: string }) => void;
+  onReject?: (data: { stepId: string; reason: string }) => void;
+  onDelegate?: (data: { stepId: string; delegateTo: Approver }) => void;
+  onEscalate?: (data: { stepId: string; escalateTo: Approver }) => void;
+  onStepChange?: (data: { previousStep: number; currentStep: number }) => void;
+  onComplete?: (data: { status: 'approved' | 'rejected'; history: ApprovalHistory[] }) => void;
+}
+```
+
+### Comparacao com Referencias
+- **Ant Design ProFlow**: Oferece componentes visuais para fluxos, ETUS adiciona controle de aprovacoes
+- **Camunda**: Sistema BPM completo, ApprovalFlow e mais leve e focado em UI
+- **Microsoft Power Automate**: Inspiracao para fluxos condicionais
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+- `role="list"`: Container de etapas
+- `role="listitem"`: Cada etapa individual
+- `aria-current="step"`: Etapa atual
+- `aria-label`: Descricao de cada etapa
+- `aria-describedby`: Detalhes do status
+
+### Navegacao por Teclado
+- `Tab`: Navega entre etapas e acoes
+- `Enter/Space`: Ativa acao selecionada
+- `Arrow Keys`: Navega entre opcoes de acao
+- `Escape`: Fecha dialogs de confirmacao
+
+### Anuncios para Screen Readers
+- Mudancas de status sao anunciadas
+- Transicoes de etapa sao vocalizadas
+- Acoes disponiveis sao listadas
+
+### Conformidade WCAG
+- Nivel alvo: WCAG 2.1 AA
+- Contraste de cores adequado para status
+- Indicadores nao dependem apenas de cor
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { ApprovalFlow } from '@etus/ui';
+
+const steps = [
+  {
+    id: '1',
+    title: 'Solicitacao',
+    status: 'approved',
+    approvers: [{ id: '1', name: 'Maria Silva', role: 'Solicitante' }]
+  },
+  {
+    id: '2',
+    title: 'Gerente',
+    status: 'in_progress',
+    approvers: [{ id: '2', name: 'Joao Santos', role: 'Gerente' }]
+  },
+  {
+    id: '3',
+    title: 'Diretor',
+    status: 'pending',
+    approvers: [{ id: '3', name: 'Ana Costa', role: 'Diretor' }]
+  }
+];
+
+export function BasicApprovalFlow() {
+  return (
+    <ApprovalFlow
+      steps={steps}
+      currentStep={1}
+      onApprove={({ stepId, comment }) => console.log('Aprovado:', stepId)}
+      onReject={({ stepId, reason }) => console.log('Rejeitado:', stepId, reason)}
+    />
+  );
+}
+```
+
+### Fluxo Paralelo
+
+```tsx
+import { ApprovalFlow } from '@etus/ui';
+
+const parallelSteps = [
+  {
+    id: '1',
+    title: 'Submissao',
+    status: 'approved',
+    approvers: [{ id: '1', name: 'Autor', role: 'Solicitante' }]
+  },
+  {
+    id: '2',
+    title: 'Aprovacoes Paralelas',
+    status: 'in_progress',
+    requiredApprovals: 2, // Precisa de 2 de 3
+    approvers: [
+      { id: '2', name: 'Financeiro', role: 'Analista' },
+      { id: '3', name: 'Juridico', role: 'Advogado' },
+      { id: '4', name: 'Compliance', role: 'Analista' }
+    ]
+  },
+  {
+    id: '3',
+    title: 'Aprovacao Final',
+    status: 'pending',
+    approvers: [{ id: '5', name: 'CEO', role: 'Diretor' }]
+  }
+];
+
+export function ParallelApprovalFlow() {
+  return (
+    <ApprovalFlow
+      steps={parallelSteps}
+      variant="parallel"
+      currentStep={1}
+    />
+  );
+}
+```
+
+### Layout Vertical com Timeline
+
+```tsx
+import { ApprovalFlow } from '@etus/ui';
+
+export function VerticalApprovalFlow() {
+  return (
+    <ApprovalFlow
+      steps={steps}
+      layout="vertical"
+      showTimeline={true}
+      showComments={true}
+    />
+  );
+}
+```
+
+### Com Delegacao e Escalacao
+
+```tsx
+import { ApprovalFlow } from '@etus/ui';
+
+export function DelegationApprovalFlow() {
+  const handleDelegate = ({ stepId, delegateTo }) => {
+    console.log(`Delegando etapa ${stepId} para ${delegateTo.name}`);
+  };
+
+  const handleEscalate = ({ stepId, escalateTo }) => {
+    console.log(`Escalando etapa ${stepId} para ${escalateTo.name}`);
+  };
+
+  return (
+    <ApprovalFlow
+      steps={steps}
+      allowDelegation={true}
+      allowEscalation={true}
+      onDelegate={handleDelegate}
+      onEscalate={handleEscalate}
+    />
+  );
+}
+```
+
+### Fluxo Condicional
+
+```tsx
+import { ApprovalFlow } from '@etus/ui';
+
+const conditionalSteps = [
+  {
+    id: '1',
+    title: 'Solicitacao de Compra',
+    status: 'approved',
+    approvers: [{ id: '1', name: 'Comprador', role: 'Analista' }],
+    conditions: [
+      { field: 'valor', operator: 'greater_than', value: 10000, nextStepId: '3' },
+      { field: 'valor', operator: 'less_than', value: 10000, nextStepId: '2' }
+    ]
+  },
+  {
+    id: '2',
+    title: 'Gerente (< R$10k)',
+    status: 'pending',
+    approvers: [{ id: '2', name: 'Gerente', role: 'Gerente' }]
+  },
+  {
+    id: '3',
+    title: 'Diretor (>= R$10k)',
+    status: 'pending',
+    approvers: [{ id: '3', name: 'Diretor', role: 'Diretor' }]
+  }
+];
+
+export function ConditionalApprovalFlow() {
+  return (
+    <ApprovalFlow
+      steps={conditionalSteps}
+      variant="conditional"
+    />
+  );
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+- Renderizacao correta das etapas
+- Calculo de etapa atual
+- Validacao de aprovacoes paralelas
+
+#### Testes de Integracao
+- Fluxo completo de aprovacao
+- Delegacao e escalacao
+- Transicoes de estado
+
+#### Testes de Acessibilidade
+- Navegacao por teclado
+- Anuncios de screen reader
+
+### Exemplos de Codigo
+
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ApprovalFlow } from './ApprovalFlow';
+
+describe('ApprovalFlow', () => {
+  const mockSteps = [
+    { id: '1', title: 'Step 1', status: 'approved', approvers: [] },
+    { id: '2', title: 'Step 2', status: 'in_progress', approvers: [] },
+    { id: '3', title: 'Step 3', status: 'pending', approvers: [] }
+  ];
+
+  it('renders all steps', () => {
+    render(<ApprovalFlow steps={mockSteps} />);
+    expect(screen.getByText('Step 1')).toBeInTheDocument();
+    expect(screen.getByText('Step 2')).toBeInTheDocument();
+    expect(screen.getByText('Step 3')).toBeInTheDocument();
+  });
+
+  it('calls onApprove when approve button is clicked', () => {
+    const onApprove = vi.fn();
+    render(<ApprovalFlow steps={mockSteps} currentStep={1} onApprove={onApprove} />);
+
+    fireEvent.click(screen.getByRole('button', { name: /aprovar/i }));
+    expect(onApprove).toHaveBeenCalledWith({ stepId: '2' });
+  });
+
+  it('shows delegation option when allowDelegation is true', () => {
+    render(<ApprovalFlow steps={mockSteps} allowDelegation={true} />);
+    expect(screen.getByRole('button', { name: /delegar/i })).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Considerar integracao com sistemas BPM externos
+- Suporte a webhooks para notificacoes
+- Cache de estado para fluxos longos
+- Auditoria completa de acoes
+
+## Referências
+
+- [Camunda BPM](https://camunda.com)
+- [Microsoft Power Automate](https://powerautomate.microsoft.com)
+- [Ant Design ProFlow](https://procomponents.ant.design)
+- [WAI-ARIA Patterns](https://www.w3.org/WAI/ARIA/apg/)

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

@@ -0,0 +1,38 @@
+export type {
+  ApprovalAction,
+  ApprovalCondition,
+  Approver as ApprovalFlowApprover,
+  ApprovalFlowProps,
+  ApprovalFlowStepProps,
+  ApprovalHistory,
+  ApprovalStep,
+  ApprovalStepStatus,
+  ApprovePayload,
+  CompletePayload,
+  DelegatePayload,
+  EscalatePayload,
+  RejectPayload,
+  StepChangePayload,
+} from "./ApprovalFlow.types"
+
+export {
+  ApprovalFlow,
+  approvalFlowActionsVariants,
+  ApprovalFlowConnector,
+  approvalFlowConnectorVariants,
+  ApprovalFlowMarker,
+  approvalFlowMarkerVariants,
+  ApprovalFlowStep,
+  approvalFlowStepCardVariants,
+  approvalFlowStepVariants,
+  approvalFlowVariants,
+} from "./ApprovalFlow"
+
+export type {
+  ApprovalFlowActionsVariantProps,
+  ApprovalFlowConnectorVariantProps,
+  ApprovalFlowMarkerVariantProps,
+  ApprovalFlowStepCardVariantProps,
+  ApprovalFlowStepVariantProps,
+  ApprovalFlowVariantProps,
+} from "./ApprovalFlow.variants"