@darksnow-ui/commander/docs/useCustomCommand-guide.md

Command pattern implementation with React hooks for building command palettes and keyboard-driven UIs

# useCustomCommand - Guia Completo

> 🎯 **O hook principal para criar comandos temporários em componentes React**

## 📋 Índice

1. [Conceito](#conceito)
2. [Anatomia do Hook](#anatomia-do-hook)
3. [Ciclo de Vida](#ciclo-de-vida)
4. [Sistema de Disponibilidade](#sistema-de-disponibilidade)
5. [Retorno do Hook (Invoker)](#retorno-do-hook-invoker)
6. [Hooks Especializados](#hooks-especializados)
7. [Padrões Avançados](#padrões-avançados)
8. [Performance e Otimização](#performance-e-otimização)
9. [Troubleshooting](#troubleshooting)

---

## Conceito

O `useCustomCommand` é um React Hook que permite registrar comandos temporários que:

- ✅ **Existem apenas enquanto o componente está montado**
- ✅ **Aparecem automaticamente no Command Palette**
- ✅ **São removidos quando o componente desmonta**
- ✅ **Mantêm type safety com TypeScript**
- ✅ **Integram com o estado do componente**

### Por que usar?

```tsx
// ❌ Sem useCustomCommand - ações espalhadas
function Modal({ onSave, onClose }) {
  return (
    <div>
      <button onClick={onSave}>Salvar (Ctrl+S)</button>
      <button onClick={onClose}>Fechar (ESC)</button>
    </div>
  )
}

// ✅ Com useCustomCommand - ações centralizadas e descobríveis
function Modal({ onSave, onClose }) {
  useCustomCommand({
    key: 'modal:save',
    label: 'Salvar',
    shortcut: 'ctrl+s',
    handle: async () => onSave()
  })

  useCustomCommand({
    key: 'modal:close',
    label: 'Fechar',
    shortcut: 'escape',
    handle: async () => onClose()
  })

  // Comandos disponíveis via Ctrl+Shift+P
  return <div>{/* ... */}</div>
}
```

---

## Anatomia do Hook

### Interface TypeScript

```typescript
interface UseCustomCommandProps<TInput = any, TOutput = any> {
  // Identificador único do comando
  key: string
  
  // Label exibido no Command Palette
  label?: string
  
  // Descrição detalhada
  description?: string
  
  // Categoria para organização
  category?: CommandCategory
  
  // Tags para busca
  tags?: string[]
  
  // Ícone visual (emoji ou componente)
  icon?: string
  
  // Atalho de teclado
  shortcut?: string
  
  // Função que determina disponibilidade
  when?: () => boolean | Promise<boolean>
  
  // Handler assíncrono do comando
  handle: (input?: TInput) => Promise<TOutput>
  
  // Timeout em ms (padrão: 30000)
  timeout?: number
  
  // Prioridade na busca (maior = primeiro)
  priority?: number
  
  // Proprietário do comando
  owner?: string
  
  // Palavras-chave adicionais para busca
  searchKeywords?: string[]
}
```

### Uso Básico

```tsx
function MyComponent() {
  const [data, setData] = useState(null)

  const saveCommand = useCustomCommand({
    key: 'my:save',
    label: 'Salvar Dados',
    handle: async () => {
      const result = await api.save(data)
      return result
    }
  })

  return (
    <button onClick={() => saveCommand.invoke()}>
      Salvar
    </button>
  )
}
```

---

## Ciclo de Vida

### 1. **Registro (Mount)**

Quando o componente monta, o comando é registrado automaticamente:

```tsx
function FileEditor({ fileId }) {
  // Comando registrado quando FileEditor monta
  useCustomCommand({
    key: `file:save:${fileId}`,
    label: 'Salvar Arquivo',
    handle: async () => saveFile(fileId)
  })
  
  // Se fileId mudar, um novo comando é registrado
  // e o anterior é removido
}
```

### 2. **Atualização (Update)**

O comando é re-registrado quando suas dependências mudam:

```tsx
function DynamicCommand() {
  const [mode, setMode] = useState('view')

  // Re-registra quando 'mode' muda
  useCustomCommand({
    key: 'action',
    label: mode === 'edit' ? 'Salvar' : 'Editar',
    handle: async () => {
      if (mode === 'edit') {
        await save()
        setMode('view')
      } else {
        setMode('edit')
      }
    }
  })
}
```

### 3. **Remoção (Unmount)**

O comando é removido automaticamente quando o componente desmonta:

```tsx
function TemporaryFeature({ isVisible }) {
  if (!isVisible) return null

  // Comando existe apenas quando isVisible = true
  useCustomCommand({
    key: 'temp:action',
    label: 'Ação Temporária',
    handle: async () => doSomething()
  })

  return <div>Feature Temporária</div>
}
```

---

## Sistema de Disponibilidade

### A função `when`

A função `when` determina se o comando está disponível:

```tsx
useCustomCommand({
  key: 'save',
  label: 'Salvar',
  when: () => hasChanges && !isSaving,
  handle: async () => save()
})
```

### Quando é avaliada

1. **Durante busca** - Para filtrar comandos indisponíveis
2. **Antes da execução** - Para validar se ainda pode executar
3. **Na UI** - Para mostrar estado desabilitado

### Importante: Não é reativa!

```tsx
// ❌ ERRADO - Pensa que vai atualizar automaticamente
function BadExample() {
  const [canSave, setCanSave] = useState(false)

  useCustomCommand({
    key: 'save',
    when: () => canSave, // Não re-avalia sozinho!
    handle: async () => save()
  })
}

// ✅ CORRETO - Re-registra quando estado muda
function GoodExample() {
  const [canSave, setCanSave] = useState(false)

  // Re-registra o comando quando canSave muda
  const command = useMemo(() => ({
    key: 'save',
    label: canSave ? 'Salvar' : 'Salvar (desabilitado)',
    when: () => canSave,
    handle: async () => save()
  }), [canSave])

  useCustomCommand(command)
}
```

### Padrões de disponibilidade

```tsx
// Baseado em permissões
when: () => user.role === 'admin'

// Baseado em estado
when: () => form.isValid && !form.isSubmitting

// Baseado em contexto
when: () => selectedItems.length > 0

// Assíncrono (use com cuidado!)
when: async () => {
  const hasPermission = await checkPermission()
  return hasPermission
}
```

---

## Retorno do Hook (Invoker)

O hook retorna um objeto `invoker` com métodos úteis:

```tsx
interface CustomCommandInvoker<TInput, TOutput> {
  // Chave do comando
  key: CommandKey
  
  // Verifica se comando existe
  exists: () => boolean
  
  // Verifica disponibilidade
  isAvailable: () => Promise<boolean>
  
  // Executa o comando
  invoke: (input?: TInput, source?: string) => Promise<TOutput>
  
  // Executa com tratamento de erro
  attempt: (input?: TInput, source?: string) => Promise<ExecutionResult<TOutput>>
  
  // Obtém o comando registrado
  getCommand: () => Command<TInput, TOutput> | undefined
}
```

### Exemplos de uso

```tsx
function MyComponent() {
  const saveCommand = useCustomCommand({
    key: 'save',
    label: 'Salvar',
    handle: async (data: SaveData) => {
      return await api.save(data)
    }
  })

  // Executar diretamente
  const handleSave = async () => {
    const result = await saveCommand.invoke({ title: 'Teste' })
    console.log('Salvo:', result)
  }

  // Executar com tratamento de erro
  const handleSafeSave = async () => {
    const result = await saveCommand.attempt({ title: 'Teste' })
    
    if (result.success) {
      console.log('Sucesso:', result.result)
    } else {
      console.error('Erro:', result.error)
    }
  }

  // Verificar disponibilidade
  const checkCommand = async () => {
    if (await saveCommand.isAvailable()) {
      console.log('Comando disponível')
    }
  }

  // Acessar comando completo
  const command = saveCommand.getCommand()
  console.log('Atalho:', command?.shortcut)
}
```

---

## Hooks Especializados

### useAction

Para ações simples sem input/output:

```tsx
function Toolbar() {
  const refresh = useAction(
    'refresh',
    'Atualizar',
    () => {
      window.location.reload()
    },
    {
      icon: '🔄',
      shortcut: 'f5'
    }
  )

  return <button onClick={() => refresh.invoke()}>Refresh</button>
}
```

### useToggleCommand

Para comandos toggle (on/off):

```tsx
function Settings() {
  const [darkMode, setDarkMode] = useState(false)

  const toggleDark = useToggleCommand(
    'dark-mode',
    'Modo Escuro',
    darkMode,
    setDarkMode,
    {
      icon: darkMode ? '🌙' : '☀️',
      shortcut: 'ctrl+shift+d'
    }
  )

  // Label automático: "Disable Modo Escuro" / "Enable Modo Escuro"
}
```

### useModalCommand

Para comandos que abrem modais:

```tsx
function UserList() {
  const createUser = useModalCommand(
    'user:create',
    'Novo Usuário',
    async () => {
      const userData = await showCreateUserModal()
      if (userData) {
        return await api.createUser(userData)
      }
    },
    {
      icon: '👤',
      shortcut: 'ctrl+n'
    }
  )
}
```

### useNavigationCommand

Para navegação:

```tsx
function ProductPage() {
  const router = useRouter()

  useNavigationCommand(
    'go:home',
    'Ir para Home',
    '/',
    router.push,
    {
      icon: '🏠',
      shortcut: 'alt+h'
    }
  )
}
```

### useContextualCommands

Para listas dinâmicas:

```tsx
function TodoList({ todos }) {
  // Cria um comando para cada todo
  useContextualCommands(
    todos,
    (todo) => ({
      key: `todo:complete:${todo.id}`,
      label: `Completar: ${todo.title}`,
      icon: '✅',
      handle: async () => completeTodo(todo.id)
    })
  )
}
```

---

## Padrões Avançados

### 1. **Comandos com Estado**

```tsx
function StatefulCommand() {
  const [lastExecution, setLastExecution] = useState(null)

  useCustomCommand({
    key: 'stateful',
    label: lastExecution 
      ? `Última execução: ${lastExecution}`
      : 'Executar',
    handle: async () => {
      const now = new Date().toLocaleTimeString()
      setLastExecution(now)
      return { executedAt: now }
    }
  })
}
```

### 2. **Comandos Compostos**

```tsx
function BulkActions({ items }) {
  const [processing, setProcessing] = useState(false)

  useCustomCommand({
    key: 'bulk:process',
    label: `Processar ${items.length} itens`,
    when: () => items.length > 0 && !processing,
    handle: async () => {
      setProcessing(true)
      
      const results = []
      for (const item of items) {
        results.push(await processItem(item))
      }
      
      setProcessing(false)
      return { processed: results.length }
    }
  })
}
```

### 3. **Comandos com Confirmação**

```tsx
function DangerousAction() {
  const deleteCommand = useCustomCommand({
    key: 'delete:all',
    label: 'Deletar Tudo',
    icon: '⚠️',
    category: 'danger',
    priority: -10, // Baixa prioridade
    handle: async () => {
      const confirmed = await showConfirmDialog({
        title: 'Deletar Tudo?',
        message: 'Esta ação não pode ser desfeita.',
        confirmText: 'Deletar',
        danger: true
      })
      
      if (confirmed) {
        await api.deleteAll()
        return { deleted: true }
      }
      
      return { deleted: false }
    }
  })
}
```

### 4. **Comandos com Loading State**

```tsx
function AsyncCommand() {
  const [isLoading, setIsLoading] = useState(false)

  const command = useCustomCommand({
    key: 'async:operation',
    label: isLoading ? 'Processando...' : 'Iniciar Processo',
    when: () => !isLoading,
    handle: async () => {
      setIsLoading(true)
      try {
        const result = await longRunningOperation()
        return result
      } finally {
        setIsLoading(false)
      }
    }
  })
}
```

### 5. **Comandos com Progresso**

```tsx
function ProgressCommand() {
  const [progress, setProgress] = useState(0)

  useCustomCommand({
    key: 'upload',
    label: progress > 0 ? `Upload: ${progress}%` : 'Fazer Upload',
    when: () => progress === 0,
    handle: async () => {
      const file = await selectFile()
      
      return uploadWithProgress(file, (percent) => {
        setProgress(percent)
      }).finally(() => {
        setProgress(0)
      })
    }
  })
}
```

---

## Performance e Otimização

### 1. **Memoização de Comandos**

```tsx
// ❌ Re-cria comando a cada render
function BadPerformance() {
  useCustomCommand({
    key: 'action',
    label: 'Action',
    handle: async () => {
      // Complex logic
    }
  })
}

// ✅ Memoiza comando pesado
function GoodPerformance() {
  const command = useMemo(() => ({
    key: 'action',
    label: 'Action',
    handle: async () => {
      // Complex logic
    }
  }), [/* dependências */])

  useCustomCommand(command)
}
```

### 2. **Callbacks Estáveis**

```tsx
function StableCallbacks() {
  const [data, setData] = useState(null)

  // ✅ useCallback para handler estável
  const handleSave = useCallback(async () => {
    return await api.save(data)
  }, [data])

  useCustomCommand({
    key: 'save',
    label: 'Save',
    handle: handleSave
  })
}
```

### 3. **Evitar Re-registros**

```tsx
// ❌ Re-registra a cada mudança de count
function TooManyRegistrations({ count }) {
  useCustomCommand({
    key: 'show-count',
    label: `Count: ${count}`,
    handle: async () => alert(count)
  })
}

// ✅ Usa closure para acessar valor atual
function OptimizedRegistration({ count }) {
  const countRef = useRef(count)
  countRef.current = count

  const command = useMemo(() => ({
    key: 'show-count',
    label: 'Show Count',
    handle: async () => alert(countRef.current)
  }), []) // Sem dependências!

  useCustomCommand(command)
}
```

### 4. **Batch de Comandos**

```tsx
// ❌ Muitas chamadas individuais
function ManyCommands({ items }) {
  items.forEach(item => {
    useCustomCommand({
      key: `item:${item.id}`,
      label: item.name,
      handle: async () => processItem(item)
    })
  })
}

// ✅ Use useContextualCommands
function OptimizedCommands({ items }) {
  useContextualCommands(items, (item) => ({
    key: `item:${item.id}`,
    label: item.name,
    handle: async () => processItem(item)
  }))
}
```

---

## Troubleshooting

### Comando não aparece no Command Palette

```tsx
// Verifique:
// 1. Key única
useCustomCommand({
  key: `unique:key:${id}`, // ✅ Única por instância
  // ...
})

// 2. Label definido
useCustomCommand({
  key: 'test',
  label: 'Test Command', // ✅ Obrigatório
  // ...
})

// 3. Função when retornando true
useCustomCommand({
  key: 'test',
  when: () => {
    console.log('Checking availability') // Debug
    return true
  },
  // ...
})
```

### Comando não executa

```tsx
// Verifique erros no console
useCustomCommand({
  key: 'test',
  handle: async () => {
    try {
      // Sua lógica
    } catch (error) {
      console.error('Command error:', error)
      throw error // Re-throw para o Commander capturar
    }
  }
})
```

### Memory leaks

```tsx
// ❌ Criar listeners sem cleanup
useCustomCommand({
  key: 'listen',
  handle: async () => {
    window.addEventListener('resize', handler) // Leak!
  }
})

// ✅ Cleanup adequado
useEffect(() => {
  const handler = () => {}
  
  useCustomCommand({
    key: 'listen',
    handle: async () => {
      // Use o handler
    }
  })
  
  window.addEventListener('resize', handler)
  return () => window.removeEventListener('resize', handler)
}, [])
```

### Performance ruim

```tsx
// Use React DevTools Profiler para identificar:
// 1. Re-renders excessivos
// 2. Comandos sendo re-registrados
// 3. Handlers pesados sem memoização

// Habilite logs de debug:
if (process.env.NODE_ENV === 'development') {
  console.log('Registering command:', key)
}
```

---

## 🎯 Resumo

- **useCustomCommand** cria comandos temporários vinculados ao ciclo de vida do componente
- **when** não é reativo - re-registre o comando quando o estado mudar
- **Invoker** retornado permite execução programática
- **Hooks especializados** simplificam casos comuns
- **Memoização** é importante para performance
- **IDs únicos** previnem conflitos entre instâncias

O hook transforma componentes React em interfaces poderosas e acessíveis, onde cada ação importante pode ser descoberta e executada via Command Palette.