forlogic-core 1.8.13 → 1.8.15

package/dist/README.md

@@ -1,12 +1,12 @@
 # 🧱 forlogic-core - Guia de Desenvolvimento
 
-> **IMPORTANTE**: Este README é genérico para todos os projetos. Para configurações específicas do projeto (como schema padrão), consulte o arquivo **KNOWLEDGE.md**.
+> **IMPORTANTE**: Este README é genérico para todos os projetos. Para configurações específicas do projeto (como schema padrão), consulte o **Custom Knowledge** do projeto nas configurações do Lovable.
 
 ---
 
 ## 🤖 REGRAS CRÍTICAS
 
-> **📋 Schema Padrão**: Veja no arquivo **KNOWLEDGE.md** qual é o schema padrão deste projeto específico.
+> **📋 Schema Padrão**: Veja no **Custom Knowledge** do projeto (Settings → Manage Knowledge) qual é o schema padrão deste projeto específico.
 
 ### ⚠️ TOP 4 ERROS MAIS COMUNS
 
@@ -16,7 +16,7 @@
 // ❌ ERRADO
 .from('table')
 
-// ✅ CORRETO (verifique o schema padrão no KNOWLEDGE.md)
+// ✅ CORRETO (verifique o schema padrão no Custom Knowledge)
 .schema('SEU_SCHEMA').from('table')
 ```
 
@@ -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,6 +5478,293 @@ fetch(url, { headers: { 'un-alias': 'true' } }); // ✅
 
 ---
 
+## 🔍 COMPONENTE DE SELEÇÃO: SelectSearch
+
+### **SelectSearch** - Componente Unificado de Seleção
+
+Componente versátil que suporta **seleção única** ou **múltipla** com busca inteligente, normalização de acentos e funciona perfeitamente dentro de Dialogs.
+
+⚠️ **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
+}
+```
+
+---
+
+### **Exemplo 1: Seleção Única**
+
+```typescript
+import { SelectSearch } from 'forlogic-core';
+
+function MyForm() {
+  const [language, setLanguage] = useState<string>();
+
+  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}
+    />
+  );
+}
+```
+
+---
+
+### **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}
+    />
+  );
+}
+```
+
+---
+
+### **Exemplo 3: Dentro de Dialog** ⚠️ **CRÍTICO**
+
+Para funcionar corretamente dentro de um Dialog, você **DEVE** passar o `popoverContainer`:
+
+```typescript
+import { SelectSearch, Dialog, DialogContent } from 'forlogic-core';
+
+function MyDialog() {
+  const [open, setOpen] = useState(false);
+  const [category, setCategory] = useState<string>();
+  const dialogContentRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <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={categories}
+            value={category}
+            onChange={setCategory}
+            placeholder="Selecione categoria"
+            popoverContainer={dialogContentRef.current}
+          />
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+---
+
+### **⚠️ IMPORTANTE: Uso em Dialog**
+
+**Configuração Correta:**
+```tsx
+// 1. Ref no DialogContent
+const dialogContentRef = useRef<HTMLDivElement>(null);
+
+// 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>
+```
+
+**❌ Configurações Incorretas Comuns:**
+
+```tsx
+// ❌ ERRADO: Sem popoverContainer
+<SelectSearch options={data} value={value} onChange={onChange} />
+
+// ❌ ERRADO: overflow-hidden no DialogContent
+<DialogContent className="overflow-hidden">
+
+// ❌ ERRADO: Sem div interna com scroll
+<DialogContent className="overflow-visible">
+  <SelectSearch {...props} />
+</DialogContent>
+```
+
+---
+
+### **Características Avançadas**
+
+#### **Busca Inteligente**
+- **Case-insensitive**: `react` encontra `React`
+- **Accent-insensitive**: `frances` encontra `Français`
+- **Busca em qualquer parte**: `script` encontra `TypeScript`
+
+#### **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
+// Loading
+<SelectSearch isLoading options={[]} />
+
+// Erro
+<SelectSearch error="Falha ao carregar opções" options={[]} />
+
+// Desabilitado
+<SelectSearch disabled options={data} />
+```
+
+---
+
+### **Uso em BaseForm**
+
+```typescript
+import { BaseForm, SelectSearch } from 'forlogic-core';
+
+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')
+  }
+];
+```
+
+---
+
+### **Migração de MultiSelect e EntitySelect (DEPRECATED)**
+
+⚠️ **Estes componentes estão obsoletos. Use `SelectSearch` para todos os casos de seleção.**
+
+**Migração de MultiSelect:**
+
+```typescript
+// ❌ ANTIGO: MultiSelect
+<MultiSelect
+  options={data}
+  value={selected}
+  onChange={setSelected}
+/>
+
+// ✅ NOVO: SelectSearch
+<SelectSearch
+  multiple
+  options={data}
+  value={selected}
+  onChange={setSelected}
+/>
+```
+
+**Migração de EntitySelect:**
+
+```typescript
+// ❌ ANTIGO: EntitySelect
+<EntitySelect
+  items={data}
+  value={selected}
+  onChange={setSelected}
+  getItemValue={(item) => item.id}
+  getItemLabel={(item) => item.name}
+/>
+
+// ✅ NOVO: SelectSearch
+<SelectSearch
+  options={data}
+  value={selected}
+  onChange={setSelected}
+  getOptionValue={(item) => item.id}
+  getOptionLabel={(item) => item.name}
+/>
+```
+
+---
+
 ## 🔍 FILTROS NO BACKEND (Backend Filtering)
 
 ### **Por que Filtros no Backend?**
@@ -6051,4 +6357,4 @@ src/
 
 ## 📝 Licença
 
-MIT License - ForLogic © 2025
+MIT License - ForLogic © 2025