forlogic-core 1.8.14 → 1.8.15

package/README.md

@@ -1923,30 +1923,9 @@ KR1 50% dos indicadores de empreendimento e áreas de negócio atingindo a meta
 
 O `forlogic-core` suporta enriquecimento automático de **múltiplos campos de ID de usuário** com dados do Qualiex (nome, email, username).
 
-#### **Configuração Global**
+#### **Como Funciona**
 
-Configure o enrichment uma vez na inicialização do app:
-
-```typescript
-import { setQualiexConfig } from 'forlogic-core';
-
-// Configuração básica (usa localStorage como fallback)
-setQualiexConfig({
-  enableUserEnrichment: true,
-  enableUsersApi: true,
-});
-
-// Configuração avançada (recomendado)
-setQualiexConfig({
-  enableUserEnrichment: true,
-  enableUsersApi: true,
-  getAccessToken: () => localStorage.getItem('qualiex_access_token'),
-  getCompanyId: () => localStorage.getItem('selectedUnitId'),
-  userNameFieldSuffix: '_name',   // default
-  userEmailFieldSuffix: '_email', // default
-  userUsernameFieldSuffix: '_username', // default
-});
-```
+O enriquecimento é **explícito e controlado por serviço**, não requer configuração global. Você decide quando enriquecer ativando `enableQualiexEnrichment` nos serviços.
 
 #### **Uso Básico: Lista de Campos de ID**
 
@@ -2059,21 +2038,61 @@ const { service } = createSimpleService({
 ✅ **Type-safe**: TypeScript valida configurações  
 ✅ **Retrocompatível**: Projetos antigos continuam funcionando  
 
+#### **Hook useQualiexUsers - Controle Explícito**
+
+Para buscar usuários do Qualiex em componentes, use `enabled: true` explicitamente:
+
+```typescript
+import { useQualiexUsers } from 'forlogic-core';
+
+// ✅ CORRETO: Busca ativa quando enabled=true
+const { data: users = [] } = useQualiexUsers({ enabled: true });
+
+// ✅ CORRETO: Busca sob demanda com refetch
+const { data: users = [], refetch } = useQualiexUsers({ enabled: false });
+// Depois, quando necessário:
+await refetch();
+```
+
+**Exemplo: Importação de Qualiex**
+
+```typescript
+function ImportQualiexButton() {
+  // Não busca automaticamente
+  const { data: qualiexUsers = [], refetch, isLoading } = useQualiexUsers({ 
+    enabled: false 
+  });
+
+  const handleImport = async () => {
+    // Busca apenas quando usuário clica
+    const { data } = await refetch();
+    // Processar data...
+  };
+
+  return <Button onClick={handleImport}>Importar do Qualiex</Button>;
+}
+```
+
 #### **Boas Práticas**
 
-✅ **BOM**: Configurar `getAccessToken` e `getCompanyId` para evitar dependência de localStorage
+✅ **BOM**: Ativar enrichment apenas onde necessário
 
 ```typescript
-setQualiexConfig({
-  enableUserEnrichment: true,
-  getAccessToken: async () => {
-    // Buscar token de forma segura (ex: context, Zustand, etc)
-    return myAuthStore.getToken();
-  },
-  getCompanyId: () => myAppStore.getSelectedCompanyId(),
+const { service } = createSimpleService({
+  tableName: 'processes',
+  entityName: 'Processo',
+  enableQualiexEnrichment: true, // Enriquece dados de usuário
+  userIdFields: ['created_by_id', 'owner_id'],
 });
 ```
 
+✅ **BOM**: Usar `enabled: true` apenas quando precisar dos dados
+
+```typescript
+// Em um componente que mostra lista de usuários
+const { data: users } = useQualiexUsers({ enabled: true });
+```
+
 ❌ **EVITAR**: Múltiplos campos apontando para o mesmo campo de saída
 
 ```typescript
@@ -5459,78 +5478,131 @@ fetch(url, { headers: { 'un-alias': 'true' } }); // ✅
 
 ---
 
-## 🔍 COMPONENTES DE SELEÇÃO: SelectSearch vs MultiSelect vs EntitySelect
+## 🔍 COMPONENTE DE SELEÇÃO: SelectSearch
 
-### **Quando Usar Cada Componente?**
+### **SelectSearch** - Componente Unificado de Seleção
 
-| Componente | Uso Recomendado | Modo | Características |
-|------------|----------------|------|-----------------|
-| **SelectSearch** | Seleção versátil (única OU múltipla) | Configurável | Mais flexível, ideal para formulários dinâmicos |
-| **MultiSelect** | Seleção múltipla apenas | Múltiplo (default) | Otimizado para badges, limite de badges exibidos |
-| **EntitySelect** | Seleção única de entidades | Único | Mais simples, ideal para foreign keys |
+Componente versátil que suporta **seleção única** ou **múltipla** com busca inteligente, normalização de acentos e funciona perfeitamente dentro de Dialogs.
 
-### **SelectSearch - Componente Versátil**
+⚠️ **IMPORTANTE**: `MultiSelect` e `EntitySelect` estão obsoletos. Use `SelectSearch` para todos os casos de seleção.
+
+---
+
+### **Props Principais**
+
+```typescript
+interface SelectSearchProps<T> {
+  options: T[];                     // Lista de opções
+  value?: string | string[];        // Valor(es) selecionado(s)
+  onChange: (value: string | string[] | undefined) => void; // Callback de mudança
+  
+  // Labels e placeholder
+  placeholder?: string;             // Ex: "Selecione..."
+  emptyMessage?: string;            // Ex: "Nenhum item encontrado"
+  
+  // Configuração de modo
+  multiple?: boolean;               // false (padrão) = seleção única, true = múltipla
+  
+  // Funções de mapeamento (default: { value: 'id', label: 'name' })
+  getOptionValue?: (option: T) => string;
+  getOptionLabel?: (option: T) => string;
+  
+  // Ordenação
+  sortOptions?: boolean;            // true (padrão) = ordena por label
+  
+  // Uso em Dialog (CRÍTICO!)
+  popoverContainer?: HTMLElement | null; // Necessário para funcionar dentro de Dialog
+  
+  // Estados
+  isLoading?: boolean;              // Mostra skeleton
+  error?: string;                   // Mostra mensagem de erro
+  disabled?: boolean;               // Desabilita o componente
+}
+```
 
-**Quando usar:**
-- ✅ Precisa alternar entre modo único e múltiplo dinamicamente
-- ✅ Formulários onde o modo pode mudar com base em lógica
-- ✅ Situações onde você quer um único componente para ambos os casos
+---
 
-**Exemplo básico:**
+### **Exemplo 1: Seleção Única**
 
 ```typescript
 import { SelectSearch } from 'forlogic-core';
 
-// Seleção única
-const [selectedLanguage, setSelectedLanguage] = useState<string>('');
+function MyForm() {
+  const [language, setLanguage] = useState<string>();
 
-<SelectSearch
-  options={languageOptions}
-  value={selectedLanguage}
-  onChange={setSelectedLanguage}
-  placeholder="Selecione um idioma..."
-  label="Idioma"
-/>
+  return (
+    <SelectSearch
+      options={[
+        { id: 'pt', name: 'Português' },
+        { id: 'en', name: 'English' },
+        { id: 'es', name: 'Español' }
+      ]}
+      value={language}
+      onChange={setLanguage}
+      placeholder="Selecione um idioma"
+      getOptionValue={(opt) => opt.id}
+      getOptionLabel={(opt) => opt.name}
+    />
+  );
+}
+```
 
-// Seleção múltipla
-const [selectedTags, setSelectedTags] = useState<string[]>([]);
+---
 
-<SelectSearch
-  multiple
-  options={tagOptions}
-  value={selectedTags}
-  onChange={setSelectedTags}
-  placeholder="Selecione tags..."
-  label="Tags"
-  maxDisplayedBadges={3}
-/>
+### **Exemplo 2: Seleção Múltipla**
+
+```typescript
+import { SelectSearch } from 'forlogic-core';
+
+function MyForm() {
+  const [tags, setTags] = useState<string[]>([]);
+
+  return (
+    <SelectSearch
+      multiple
+      options={[
+        { id: '1', name: 'React' },
+        { id: '2', name: 'TypeScript' },
+        { id: '3', name: 'Tailwind' }
+      ]}
+      value={tags}
+      onChange={(value) => setTags(value as string[])}
+      placeholder="Selecione tecnologias"
+      getOptionValue={(opt) => opt.id}
+      getOptionLabel={(opt) => opt.name}
+    />
+  );
+}
 ```
 
-**Uso dentro de Dialog (scroll funcionando):**
+---
+
+### **Exemplo 3: Dentro de Dialog** ⚠️ **CRÍTICO**
+
+Para funcionar corretamente dentro de um Dialog, você **DEVE** passar o `popoverContainer`:
 
 ```typescript
-import { Dialog, DialogContent, SelectSearch } from 'forlogic-core';
+import { SelectSearch, Dialog, DialogContent } from 'forlogic-core';
 
-function MyComponent() {
-  const [dialogContentRef, setDialogContentRef] = useState<HTMLDivElement | null>(null);
-  const [selected, setSelected] = useState<string>('');
+function MyDialog() {
+  const [open, setOpen] = useState(false);
+  const [category, setCategory] = useState<string>();
+  const dialogContentRef = useRef<HTMLDivElement>(null);
 
   return (
-    <Dialog>
-      <DialogTrigger asChild>
-        <Button>Abrir Seleção</Button>
-      </DialogTrigger>
-      <DialogContent ref={setDialogContentRef} className="max-h-[90vh] overflow-visible">
-        <DialogHeader>
-          <DialogTitle>Selecione uma Categoria</DialogTitle>
-        </DialogHeader>
-        <div className="mt-4 max-h-[60vh] overflow-auto pr-1">
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogContent 
+        ref={dialogContentRef}
+        className="overflow-visible" // ⚠️ IMPORTANTE: overflow-visible no DialogContent
+      >
+        <div className="space-y-4 overflow-auto max-h-[60vh]">
+          {/* ⚠️ CRÍTICO: Passar popoverContainer */}
           <SelectSearch
-            options={categoryOptions}
-            value={selected}
-            onChange={setSelected}
-            placeholder="Selecione..."
-            popoverContainer={dialogContentRef}  {/* ✅ CRÍTICO para scroll funcionar */}
+            options={categories}
+            value={category}
+            onChange={setCategory}
+            placeholder="Selecione categoria"
+            popoverContainer={dialogContentRef.current}
           />
         </div>
       </DialogContent>
@@ -5539,156 +5611,156 @@ function MyComponent() {
 }
 ```
 
-**Props principais:**
+---
 
-```typescript
-interface SelectSearchProps<T> {
-  multiple?: boolean;                    // Modo: false = único, true = múltiplo
-  options: T[];                          // Array de itens
-  value?: string | string[];             // Valor(es) selecionado(s)
-  onChange?: (value: string | string[]) => void;
-  getOptionValue?: (option: T) => string;
-  getOptionLabel?: (option: T) => string;
-  placeholder?: string;
-  label?: string;
-  disabled?: boolean;
-  required?: boolean;
-  isLoading?: boolean;
-  error?: string | boolean;
-  sortOptions?: boolean;                 // Default: true
-  maxDisplayedBadges?: number;           // Limite de badges (modo múltiplo)
-  popoverContainer?: HTMLElement | null; // ✅ Essencial para Dialog
-}
-```
+### **⚠️ IMPORTANTE: Uso em Dialog**
 
-### **MultiSelect - Seleção Múltipla**
+**Configuração Correta:**
+```tsx
+// 1. Ref no DialogContent
+const dialogContentRef = useRef<HTMLDivElement>(null);
 
-**Quando usar:**
-- ✅ Seleção múltipla obrigatória (não precisa alternar para único)
-- ✅ Exibição de badges é importante
-- ✅ Precisa de limite de badges exibidos (+N)
+// 2. overflow-visible no DialogContent
+<DialogContent ref={dialogContentRef} className="overflow-visible">
+  
+  // 3. Div interna com overflow-auto
+  <div className="overflow-auto max-h-[60vh]">
+    
+    // 4. Passar popoverContainer
+    <SelectSearch
+      {...props}
+      popoverContainer={dialogContentRef.current}
+    />
+  </div>
+</DialogContent>
+```
 
-**Exemplo:**
+**❌ Configurações Incorretas Comuns:**
 
-```typescript
-import { MultiSelect } from 'forlogic-core';
+```tsx
+// ❌ ERRADO: Sem popoverContainer
+<SelectSearch options={data} value={value} onChange={onChange} />
 
-const [selectedFrameworks, setSelectedFrameworks] = useState<string[]>([]);
+// ❌ ERRADO: overflow-hidden no DialogContent
+<DialogContent className="overflow-hidden">
 
-<MultiSelect
-  options={frameworks}
-  value={selectedFrameworks}
-  onChange={setSelectedFrameworks}
-  getOptionValue={(opt) => opt.id}
-  getOptionLabel={(opt) => opt.name}
-  placeholder="Selecione frameworks..."
-  label="Frameworks"
-  maxDisplayedBadges={3}  // Exibe: [Badge 1] [Badge 2] [Badge 3] [+5]
-/>
+// ❌ ERRADO: Sem div interna com scroll
+<DialogContent className="overflow-visible">
+  <SelectSearch {...props} />
+</DialogContent>
 ```
 
-**Modo único (suportado mas não recomendado):**
-
-```typescript
-// ⚠️ Use SelectSearch ou EntitySelect para modo único
-<MultiSelect
-  multiple={false}  // Funciona, mas SelectSearch é mais apropriado
-  options={options}
-  value={selected}
-  onChange={setSelected}
-/>
-```
+---
 
-### **EntitySelect - Seleção Única Simples**
+### **Características Avançadas**
 
-**Quando usar:**
-- ✅ Seleção única de entidades (processos, usuários, categorias)
-- ✅ Foreign keys em formulários
-- ✅ Casos simples sem necessidade de badges ou modo múltiplo
+#### **Busca Inteligente**
+- **Case-insensitive**: `react` encontra `React`
+- **Accent-insensitive**: `frances` encontra `Français`
+- **Busca em qualquer parte**: `script` encontra `TypeScript`
 
-**Exemplo:**
+#### **Badges Interativos (modo múltiplo)**
+- Exibe badges com `×` para remover itens
+- Limite de 3 badges exibidos, com `+N` para excedentes
+- Click em `+N` expande para mostrar todos
 
+#### **Estados**
 ```typescript
-import { EntitySelect } from 'forlogic-core';
+// Loading
+<SelectSearch isLoading options={[]} />
 
-const [selectedFramework, setSelectedFramework] = useState<string>('');
+// Erro
+<SelectSearch error="Falha ao carregar opções" options={[]} />
 
-<EntitySelect
-  items={frameworks}
-  value={selectedFramework}
-  onChange={setSelectedFramework}
-  getItemValue={(opt) => opt.id}
-  getItemLabel={(opt) => opt.name}
-  placeholder="Selecione um framework..."
-  searchPlaceholder="Buscar framework..."
-/>
+// Desabilitado
+<SelectSearch disabled options={data} />
 ```
 
-### **Comparação de Props**
-
-| Prop | SelectSearch | MultiSelect | EntitySelect |
-|------|--------------|-------------|--------------|
-| `multiple` | ✅ Configurável | ✅ Default true | ❌ Sempre único |
-| `maxDisplayedBadges` | ✅ Modo múltiplo | ✅ | ❌ |
-| `popoverContainer` | ✅ | ✅ | ❌ |
-| `items` vs `options` | `options` | `options` | `items` |
-| Complexidade | Média | Média | Baixa |
+---
 
-### **Recomendações**
+### **Uso em BaseForm**
 
-1. **Use SelectSearch quando:**
-   - Precisar de flexibilidade para alternar entre único/múltiplo
-   - Estiver dentro de Dialog e precisar de scroll
-   - Quiser um componente versátil para diversos casos
+```typescript
+import { BaseForm, SelectSearch } from 'forlogic-core';
 
-2. **Use MultiSelect quando:**
-   - Seleção múltipla for o único caso de uso
-   - Precisar de controle avançado de badges
-   - Precisar de modo único ocasionalmente (mas prefira SelectSearch)
+const fields = [
+  {
+    name: 'language',
+    label: 'Idioma',
+    type: 'custom' as const,
+    component: ({ field }: any) => (
+      <SelectSearch
+        options={languages}
+        value={field.value}
+        onChange={field.onChange}
+        placeholder="Selecione um idioma"
+      />
+    ),
+    validation: z.string().min(1, 'Idioma obrigatório')
+  },
+  {
+    name: 'tags',
+    label: 'Tags',
+    type: 'custom' as const,
+    component: ({ field }: any) => (
+      <SelectSearch
+        multiple
+        options={allTags}
+        value={field.value}
+        onChange={field.onChange}
+        placeholder="Selecione tags"
+      />
+    ),
+    validation: z.array(z.string()).min(1, 'Selecione ao menos uma tag')
+  }
+];
+```
 
-3. **Use EntitySelect quando:**
-   - Seleção única simples for suficiente
-   - Não precisar de Dialog ou scroll especial
-   - Quiser o componente mais leve e focado
+---
 
-### **⚠️ IMPORTANTE: Uso em Dialog**
+### **Migração de MultiSelect e EntitySelect (DEPRECATED)**
 
-Tanto `SelectSearch` quanto `MultiSelect` funcionam perfeitamente dentro de `Dialog`, mas requerem configuração específica:
+⚠️ **Estes componentes estão obsoletos. Use `SelectSearch` para todos os casos de seleção.**
 
-**✅ Configuração correta:**
+**Migração de MultiSelect:**
 
 ```typescript
-// 1. State para ref do DialogContent
-const [dialogContentRef, setDialogContentRef] = useState<HTMLDivElement | null>(null);
+// ❌ ANTIGO: MultiSelect
+<MultiSelect
+  options={data}
+  value={selected}
+  onChange={setSelected}
+/>
 
-// 2. DialogContent com overflow-visible
-<DialogContent ref={setDialogContentRef} className="max-h-[90vh] overflow-visible">
-  
-  {/* 3. Container interno com overflow-auto */}
-  <div className="mt-4 max-h-[60vh] overflow-auto pr-1">
-    
-    {/* 4. Passar ref como popoverContainer */}
-    <SelectSearch
-      options={options}
-      value={selected}
-      onChange={setSelected}
-      popoverContainer={dialogContentRef}  {/* ✅ CRÍTICO */}
-    />
-  </div>
-</DialogContent>
+// ✅ NOVO: SelectSearch
+<SelectSearch
+  multiple
+  options={data}
+  value={selected}
+  onChange={setSelected}
+/>
 ```
 
-**❌ Erros comuns:**
+**Migração de EntitySelect:**
 
 ```typescript
-// ❌ ERRADO: Sem popoverContainer
-<SelectSearch options={options} value={selected} onChange={setSelected} />
-
-// ❌ ERRADO: DialogContent sem overflow-visible
-<DialogContent className="max-h-[90vh] overflow-auto">
+// ❌ ANTIGO: EntitySelect
+<EntitySelect
+  items={data}
+  value={selected}
+  onChange={setSelected}
+  getItemValue={(item) => item.id}
+  getItemLabel={(item) => item.name}
+/>
 
-// ❌ ERRADO: Usar document.body como container (perde scroll)
-<SelectSearch popoverContainer={document.body} />
+// ✅ NOVO: SelectSearch
+<SelectSearch
+  options={data}
+  value={selected}
+  onChange={setSelected}
+  getOptionValue={(item) => item.id}
+  getOptionLabel={(item) => item.name}
+/>
 ```
 
 ---