forlogic-core 1.9.0 → 1.9.2

package/README.md

@@ -2071,41 +2071,248 @@ const { service } = createSimpleService({
 ✅ **Type-safe**: TypeScript valida configurações  
 ✅ **Retrocompatível**: Projetos antigos continuam funcionando  
 
-#### **Hook useQualiexUsers - Controle Explícito**
+#### **Hook useQualiexUsers - ⚠️ Controle Explícito Obrigatório**
 
-Para buscar usuários do Qualiex em componentes, use `enabled: true` explicitamente:
+**IMPORTANTE:** O hook `useQualiexUsers` tem **`enabled: false` como padrão**. Você **DEVE** passar `enabled: true` explicitamente para buscar usuários.
+
+##### **Por Que enabled é false por Padrão?**
+
+1. ✅ **Performance**: Evita chamadas automáticas desnecessárias à API Qualiex
+2. ✅ **Controle**: Desenvolvedor decide QUANDO buscar dados
+3. ✅ **Otimização**: Modais/tabs só buscam quando abertos
+4. ✅ **Lazy Loading**: Permite controle manual com `refetch()`
+
+##### **Uso Básico**
 
 ```typescript
 import { useQualiexUsers } from 'forlogic-core';
 
-// ✅ CORRETO: Busca ativa quando enabled=true
-const { data: users = [] } = useQualiexUsers({ enabled: true });
+// ✅ CORRETO - Busca ativa
+const { data: users = [], isLoading } = useQualiexUsers({ enabled: true });
+
+// ✅ CORRETO - Busca condicional (modal)
+const { data: users = [] } = useQualiexUsers({ enabled: isModalOpen });
 
-// ✅ CORRETO: Busca sob demanda com refetch
+// ✅ CORRETO - Lazy loading (controle manual)
 const { data: users = [], refetch } = useQualiexUsers({ enabled: false });
-// Depois, quando necessário:
+// Chamar refetch() quando necessário:
 await refetch();
+
+// ❌ ERRADO - Retorna [] sempre! (enabled = false por padrão)
+const { data: users = [] } = useQualiexUsers();
 ```
 
-**Exemplo: Importação de Qualiex**
+##### **Parâmetros**
+
+| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
+|-----------|------|-------------|--------|-----------|
+| `enabled` | `boolean` | Sim* | `false` | Controla se a query executa |
+
+*Tecnicamente opcional, mas **obrigatório na prática** para que a query funcione.
+
+##### **Retorno**
+
+| Propriedade | Tipo | Descrição |
+|-------------|------|-----------|
+| `data` | `QualiexUser[]` | Array de usuários (vazio se `enabled: false`) |
+| `isLoading` | `boolean` | Estado de carregamento |
+| `error` | `Error \| null` | Erro da API (se houver) |
+| `refetch` | `() => Promise<...>` | Função para rebuscar manualmente |
+
+##### **Quando Usar Cada Modo**
+
+| Cenário | Configuração | Exemplo |
+|---------|-------------|---------|
+| **Lista sempre visível** | `{ enabled: true }` | Tabela de funcionários |
+| **Modal/Dialog** | `{ enabled: isOpen }` | Form de criar liderança |
+| **Tab/Accordion** | `{ enabled: isTabActive }` | Tabs de configuração |
+| **Botão de importação** | `{ enabled: false }` + `refetch()` | Import do Qualiex |
+| **Conditional render** | `{ enabled: shouldLoad }` | Baseado em lógica customizada |
+
+##### **Exemplos Completos**
+
+###### **Exemplo 1: Lista Sempre Visível**
+
+```typescript
+function EmployeesList() {
+  const { data: users = [], isLoading } = useQualiexUsers({ 
+    enabled: true 
+  });
+
+  if (isLoading) return <Skeleton />;
+
+  return (
+    <ul>
+      {users.map(user => (
+        <li key={user.userId}>{user.userName}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+###### **Exemplo 2: Modal Condicional**
+
+```typescript
+function LeadershipDialog({ isOpen }: { isOpen: boolean }) {
+  // Só busca quando modal aberto
+  const { data: users = [], isLoading } = useQualiexUsers({ 
+    enabled: isOpen 
+  });
+
+  if (!isOpen) return null;
+  if (isLoading) return <Skeleton />;
+
+  return (
+    <Dialog open={isOpen}>
+      <Select>
+        {users.map(user => (
+          <SelectItem key={user.userId} value={user.userId}>
+            {user.userName}
+          </SelectItem>
+        ))}
+      </Select>
+    </Dialog>
+  );
+}
+```
+
+###### **Exemplo 3: Lazy Loading (Botão de Importação)**
 
 ```typescript
 function ImportQualiexButton() {
   // Não busca automaticamente
-  const { data: qualiexUsers = [], refetch, isLoading } = useQualiexUsers({ 
+  const { data: users = [], refetch, isLoading } = useQualiexUsers({ 
     enabled: false 
   });
 
   const handleImport = async () => {
     // Busca apenas quando usuário clica
     const { data } = await refetch();
-    // Processar data...
+    
+    if (data && data.length > 0) {
+      console.log(`Importando ${data.length} usuários`);
+      // Processar importação...
+    }
+  };
+
+  return (
+    <Button onClick={handleImport} disabled={isLoading}>
+      {isLoading ? 'Importando...' : 'Importar do Qualiex'}
+    </Button>
+  );
+}
+```
+
+###### **Exemplo 4: Hook Personalizado (useUsersMap)**
+
+```typescript
+// src/shared/hooks/useUsersMap.ts
+import { useMemo } from 'react';
+import { useQualiexUsers } from 'forlogic-core';
+
+export const useUsersMap = () => {
+  // ✅ Ativa query para buscar usuários
+  const { data: usersData = [], isLoading, error } = useQualiexUsers({ 
+    enabled: true 
+  });
+
+  const usersMap = useMemo(() => {
+    const map = new Map();
+    usersData.forEach(user => {
+      map.set(user.userId, user);
+    });
+    return map;
+  }, [usersData]);
+
+  return {
+    usersMap,
+    usersData,
+    isLoading,
+    error
   };
+};
 
-  return <Button onClick={handleImport}>Importar do Qualiex</Button>;
+// Uso em componente:
+function SomeComponent() {
+  const { usersMap, isLoading } = useUsersMap();
+  
+  if (isLoading) return <Skeleton />;
+  
+  const user = usersMap.get('some-user-id');
+  return <div>{user?.userName}</div>;
 }
 ```
 
+##### **Tratamento de Erros**
+
+```typescript
+const { data: users = [], isLoading, error } = useQualiexUsers({ 
+  enabled: true 
+});
+
+if (error) {
+  console.error('Erro ao buscar usuários Qualiex:', error);
+  return (
+    <Alert variant="destructive">
+      Erro ao carregar usuários. Tente novamente.
+    </Alert>
+  );
+}
+
+if (isLoading) return <Skeleton />;
+```
+
+##### **Boas Práticas**
+
+✅ **SEMPRE** especifique `enabled` explicitamente  
+✅ **SEMPRE** desestruture `isLoading` e trate estados de loading  
+✅ **SEMPRE** trate erros com `error`  
+✅ **USE** `enabled: isOpen` em modais para evitar chamadas desnecessárias  
+✅ **USE** `enabled: false` + `refetch()` para lazy loading  
+
+❌ **NUNCA** confie no padrão (`enabled: false`)  
+❌ **EVITE** `enabled: true` em componentes que nem sempre estão visíveis  
+❌ **EVITE** esquecer de tratar `isLoading` (causa UI vazia temporária)  
+
+##### **Troubleshooting**
+
+**Problema:** Lista de usuários sempre vazia
+
+```typescript
+// ❌ ERRADO
+const { data: users = [] } = useQualiexUsers();
+console.log(users); // []
+
+// ✅ SOLUÇÃO
+const { data: users = [] } = useQualiexUsers({ enabled: true });
+console.log(users); // [{ userId: "123", userName: "João", ... }]
+```
+
+**Problema:** Modal mostra usuários mesmo fechado (performance)
+
+```typescript
+// ❌ ERRADO - Busca mesmo se modal fechado
+const { data: users } = useQualiexUsers({ enabled: true });
+
+// ✅ SOLUÇÃO - Só busca se modal aberto
+const { data: users } = useQualiexUsers({ enabled: isModalOpen });
+```
+
+##### **Características Técnicas**
+
+✅ **Cache inteligente**: Usuários são cacheados por query key (`['qualiex-users', alias]`)  
+✅ **Retry automático**: 2 tentativas com delay de 1s  
+✅ **Auth automático**: Usa `useAuth()` internamente (não precisa passar `alias`)  
+✅ **Type-safe**: Totalmente tipado com TypeScript  
+✅ **React Query**: Baseado em `@tanstack/react-query`  
+
+##### **Ver Também**
+
+- 📖 **Migration Guide**: [MIGRATION.md - Seção 8 (useQualiexUsers)](MIGRATION.md#8️⃣-hook-usequaliexusers---breaking-change-)
+- 📖 **Qualiex Enrichment**: [README.md - Seção Qualiex](#enrichment-automático-de-dados-de-usuários-qualiex)
+- 🔧 **QualiexUserField Component**: [README.md - QualiexUserField](#qualiexuserfield-componente)
+
 #### **Boas Práticas**
 
 ✅ **BOM**: Ativar enrichment apenas onde necessário

package/dist/README.md

@@ -2071,41 +2071,248 @@ const { service } = createSimpleService({
 ✅ **Type-safe**: TypeScript valida configurações  
 ✅ **Retrocompatível**: Projetos antigos continuam funcionando  
 
-#### **Hook useQualiexUsers - Controle Explícito**
+#### **Hook useQualiexUsers - ⚠️ Controle Explícito Obrigatório**
 
-Para buscar usuários do Qualiex em componentes, use `enabled: true` explicitamente:
+**IMPORTANTE:** O hook `useQualiexUsers` tem **`enabled: false` como padrão**. Você **DEVE** passar `enabled: true` explicitamente para buscar usuários.
+
+##### **Por Que enabled é false por Padrão?**
+
+1. ✅ **Performance**: Evita chamadas automáticas desnecessárias à API Qualiex
+2. ✅ **Controle**: Desenvolvedor decide QUANDO buscar dados
+3. ✅ **Otimização**: Modais/tabs só buscam quando abertos
+4. ✅ **Lazy Loading**: Permite controle manual com `refetch()`
+
+##### **Uso Básico**
 
 ```typescript
 import { useQualiexUsers } from 'forlogic-core';
 
-// ✅ CORRETO: Busca ativa quando enabled=true
-const { data: users = [] } = useQualiexUsers({ enabled: true });
+// ✅ CORRETO - Busca ativa
+const { data: users = [], isLoading } = useQualiexUsers({ enabled: true });
+
+// ✅ CORRETO - Busca condicional (modal)
+const { data: users = [] } = useQualiexUsers({ enabled: isModalOpen });
 
-// ✅ CORRETO: Busca sob demanda com refetch
+// ✅ CORRETO - Lazy loading (controle manual)
 const { data: users = [], refetch } = useQualiexUsers({ enabled: false });
-// Depois, quando necessário:
+// Chamar refetch() quando necessário:
 await refetch();
+
+// ❌ ERRADO - Retorna [] sempre! (enabled = false por padrão)
+const { data: users = [] } = useQualiexUsers();
 ```
 
-**Exemplo: Importação de Qualiex**
+##### **Parâmetros**
+
+| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
+|-----------|------|-------------|--------|-----------|
+| `enabled` | `boolean` | Sim* | `false` | Controla se a query executa |
+
+*Tecnicamente opcional, mas **obrigatório na prática** para que a query funcione.
+
+##### **Retorno**
+
+| Propriedade | Tipo | Descrição |
+|-------------|------|-----------|
+| `data` | `QualiexUser[]` | Array de usuários (vazio se `enabled: false`) |
+| `isLoading` | `boolean` | Estado de carregamento |
+| `error` | `Error \| null` | Erro da API (se houver) |
+| `refetch` | `() => Promise<...>` | Função para rebuscar manualmente |
+
+##### **Quando Usar Cada Modo**
+
+| Cenário | Configuração | Exemplo |
+|---------|-------------|---------|
+| **Lista sempre visível** | `{ enabled: true }` | Tabela de funcionários |
+| **Modal/Dialog** | `{ enabled: isOpen }` | Form de criar liderança |
+| **Tab/Accordion** | `{ enabled: isTabActive }` | Tabs de configuração |
+| **Botão de importação** | `{ enabled: false }` + `refetch()` | Import do Qualiex |
+| **Conditional render** | `{ enabled: shouldLoad }` | Baseado em lógica customizada |
+
+##### **Exemplos Completos**
+
+###### **Exemplo 1: Lista Sempre Visível**
+
+```typescript
+function EmployeesList() {
+  const { data: users = [], isLoading } = useQualiexUsers({ 
+    enabled: true 
+  });
+
+  if (isLoading) return <Skeleton />;
+
+  return (
+    <ul>
+      {users.map(user => (
+        <li key={user.userId}>{user.userName}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+###### **Exemplo 2: Modal Condicional**
+
+```typescript
+function LeadershipDialog({ isOpen }: { isOpen: boolean }) {
+  // Só busca quando modal aberto
+  const { data: users = [], isLoading } = useQualiexUsers({ 
+    enabled: isOpen 
+  });
+
+  if (!isOpen) return null;
+  if (isLoading) return <Skeleton />;
+
+  return (
+    <Dialog open={isOpen}>
+      <Select>
+        {users.map(user => (
+          <SelectItem key={user.userId} value={user.userId}>
+            {user.userName}
+          </SelectItem>
+        ))}
+      </Select>
+    </Dialog>
+  );
+}
+```
+
+###### **Exemplo 3: Lazy Loading (Botão de Importação)**
 
 ```typescript
 function ImportQualiexButton() {
   // Não busca automaticamente
-  const { data: qualiexUsers = [], refetch, isLoading } = useQualiexUsers({ 
+  const { data: users = [], refetch, isLoading } = useQualiexUsers({ 
     enabled: false 
   });
 
   const handleImport = async () => {
     // Busca apenas quando usuário clica
     const { data } = await refetch();
-    // Processar data...
+    
+    if (data && data.length > 0) {
+      console.log(`Importando ${data.length} usuários`);
+      // Processar importação...
+    }
+  };
+
+  return (
+    <Button onClick={handleImport} disabled={isLoading}>
+      {isLoading ? 'Importando...' : 'Importar do Qualiex'}
+    </Button>
+  );
+}
+```
+
+###### **Exemplo 4: Hook Personalizado (useUsersMap)**
+
+```typescript
+// src/shared/hooks/useUsersMap.ts
+import { useMemo } from 'react';
+import { useQualiexUsers } from 'forlogic-core';
+
+export const useUsersMap = () => {
+  // ✅ Ativa query para buscar usuários
+  const { data: usersData = [], isLoading, error } = useQualiexUsers({ 
+    enabled: true 
+  });
+
+  const usersMap = useMemo(() => {
+    const map = new Map();
+    usersData.forEach(user => {
+      map.set(user.userId, user);
+    });
+    return map;
+  }, [usersData]);
+
+  return {
+    usersMap,
+    usersData,
+    isLoading,
+    error
   };
+};
 
-  return <Button onClick={handleImport}>Importar do Qualiex</Button>;
+// Uso em componente:
+function SomeComponent() {
+  const { usersMap, isLoading } = useUsersMap();
+  
+  if (isLoading) return <Skeleton />;
+  
+  const user = usersMap.get('some-user-id');
+  return <div>{user?.userName}</div>;
 }
 ```
 
+##### **Tratamento de Erros**
+
+```typescript
+const { data: users = [], isLoading, error } = useQualiexUsers({ 
+  enabled: true 
+});
+
+if (error) {
+  console.error('Erro ao buscar usuários Qualiex:', error);
+  return (
+    <Alert variant="destructive">
+      Erro ao carregar usuários. Tente novamente.
+    </Alert>
+  );
+}
+
+if (isLoading) return <Skeleton />;
+```
+
+##### **Boas Práticas**
+
+✅ **SEMPRE** especifique `enabled` explicitamente  
+✅ **SEMPRE** desestruture `isLoading` e trate estados de loading  
+✅ **SEMPRE** trate erros com `error`  
+✅ **USE** `enabled: isOpen` em modais para evitar chamadas desnecessárias  
+✅ **USE** `enabled: false` + `refetch()` para lazy loading  
+
+❌ **NUNCA** confie no padrão (`enabled: false`)  
+❌ **EVITE** `enabled: true` em componentes que nem sempre estão visíveis  
+❌ **EVITE** esquecer de tratar `isLoading` (causa UI vazia temporária)  
+
+##### **Troubleshooting**
+
+**Problema:** Lista de usuários sempre vazia
+
+```typescript
+// ❌ ERRADO
+const { data: users = [] } = useQualiexUsers();
+console.log(users); // []
+
+// ✅ SOLUÇÃO
+const { data: users = [] } = useQualiexUsers({ enabled: true });
+console.log(users); // [{ userId: "123", userName: "João", ... }]
+```
+
+**Problema:** Modal mostra usuários mesmo fechado (performance)
+
+```typescript
+// ❌ ERRADO - Busca mesmo se modal fechado
+const { data: users } = useQualiexUsers({ enabled: true });
+
+// ✅ SOLUÇÃO - Só busca se modal aberto
+const { data: users } = useQualiexUsers({ enabled: isModalOpen });
+```
+
+##### **Características Técnicas**
+
+✅ **Cache inteligente**: Usuários são cacheados por query key (`['qualiex-users', alias]`)  
+✅ **Retry automático**: 2 tentativas com delay de 1s  
+✅ **Auth automático**: Usa `useAuth()` internamente (não precisa passar `alias`)  
+✅ **Type-safe**: Totalmente tipado com TypeScript  
+✅ **React Query**: Baseado em `@tanstack/react-query`  
+
+##### **Ver Também**
+
+- 📖 **Migration Guide**: [MIGRATION.md - Seção 8 (useQualiexUsers)](MIGRATION.md#8️⃣-hook-usequaliexusers---breaking-change-)
+- 📖 **Qualiex Enrichment**: [README.md - Seção Qualiex](#enrichment-automático-de-dados-de-usuários-qualiex)
+- 🔧 **QualiexUserField Component**: [README.md - QualiexUserField](#qualiexuserfield-componente)
+
 #### **Boas Práticas**
 
 ✅ **BOM**: Ativar enrichment apenas onde necessário