forlogic-core 1.8.13 → 1.8.14

package/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')
 ```
 
@@ -5459,6 +5459,240 @@ fetch(url, { headers: { 'un-alias': 'true' } }); // ✅
 
 ---
 
+## 🔍 COMPONENTES DE SELEÇÃO: SelectSearch vs MultiSelect vs EntitySelect
+
+### **Quando Usar Cada Componente?**
+
+| 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 |
+
+### **SelectSearch - Componente Versátil**
+
+**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:**
+
+```typescript
+import { SelectSearch } from 'forlogic-core';
+
+// Seleção única
+const [selectedLanguage, setSelectedLanguage] = useState<string>('');
+
+<SelectSearch
+  options={languageOptions}
+  value={selectedLanguage}
+  onChange={setSelectedLanguage}
+  placeholder="Selecione um idioma..."
+  label="Idioma"
+/>
+
+// Seleção múltipla
+const [selectedTags, setSelectedTags] = useState<string[]>([]);
+
+<SelectSearch
+  multiple
+  options={tagOptions}
+  value={selectedTags}
+  onChange={setSelectedTags}
+  placeholder="Selecione tags..."
+  label="Tags"
+  maxDisplayedBadges={3}
+/>
+```
+
+**Uso dentro de Dialog (scroll funcionando):**
+
+```typescript
+import { Dialog, DialogContent, SelectSearch } from 'forlogic-core';
+
+function MyComponent() {
+  const [dialogContentRef, setDialogContentRef] = useState<HTMLDivElement | null>(null);
+  const [selected, setSelected] = useState<string>('');
+
+  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">
+          <SelectSearch
+            options={categoryOptions}
+            value={selected}
+            onChange={setSelected}
+            placeholder="Selecione..."
+            popoverContainer={dialogContentRef}  {/* ✅ CRÍTICO para scroll funcionar */}
+          />
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+**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
+}
+```
+
+### **MultiSelect - Seleção Múltipla**
+
+**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)
+
+**Exemplo:**
+
+```typescript
+import { MultiSelect } from 'forlogic-core';
+
+const [selectedFrameworks, setSelectedFrameworks] = useState<string[]>([]);
+
+<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]
+/>
+```
+
+**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**
+
+**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
+
+**Exemplo:**
+
+```typescript
+import { EntitySelect } from 'forlogic-core';
+
+const [selectedFramework, setSelectedFramework] = useState<string>('');
+
+<EntitySelect
+  items={frameworks}
+  value={selectedFramework}
+  onChange={setSelectedFramework}
+  getItemValue={(opt) => opt.id}
+  getItemLabel={(opt) => opt.name}
+  placeholder="Selecione um framework..."
+  searchPlaceholder="Buscar framework..."
+/>
+```
+
+### **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**
+
+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
+
+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)
+
+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**
+
+Tanto `SelectSearch` quanto `MultiSelect` funcionam perfeitamente dentro de `Dialog`, mas requerem configuração específica:
+
+**✅ Configuração correta:**
+
+```typescript
+// 1. State para ref do DialogContent
+const [dialogContentRef, setDialogContentRef] = useState<HTMLDivElement | null>(null);
+
+// 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>
+```
+
+**❌ Erros comuns:**
+
+```typescript
+// ❌ ERRADO: Sem popoverContainer
+<SelectSearch options={options} value={selected} onChange={setSelected} />
+
+// ❌ ERRADO: DialogContent sem overflow-visible
+<DialogContent className="max-h-[90vh] overflow-auto">
+
+// ❌ ERRADO: Usar document.body como container (perde scroll)
+<SelectSearch popoverContainer={document.body} />
+```
+
+---
+
 ## 🔍 FILTROS NO BACKEND (Backend Filtering)
 
 ### **Por que Filtros no Backend?**
@@ -6051,4 +6285,4 @@ src/
 
 ## 📝 Licença
 
-MIT License - ForLogic © 2025
+MIT License - ForLogic © 2025

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')
 ```
 
@@ -5459,6 +5459,240 @@ fetch(url, { headers: { 'un-alias': 'true' } }); // ✅
 
 ---
 
+## 🔍 COMPONENTES DE SELEÇÃO: SelectSearch vs MultiSelect vs EntitySelect
+
+### **Quando Usar Cada Componente?**
+
+| 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 |
+
+### **SelectSearch - Componente Versátil**
+
+**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:**
+
+```typescript
+import { SelectSearch } from 'forlogic-core';
+
+// Seleção única
+const [selectedLanguage, setSelectedLanguage] = useState<string>('');
+
+<SelectSearch
+  options={languageOptions}
+  value={selectedLanguage}
+  onChange={setSelectedLanguage}
+  placeholder="Selecione um idioma..."
+  label="Idioma"
+/>
+
+// Seleção múltipla
+const [selectedTags, setSelectedTags] = useState<string[]>([]);
+
+<SelectSearch
+  multiple
+  options={tagOptions}
+  value={selectedTags}
+  onChange={setSelectedTags}
+  placeholder="Selecione tags..."
+  label="Tags"
+  maxDisplayedBadges={3}
+/>
+```
+
+**Uso dentro de Dialog (scroll funcionando):**
+
+```typescript
+import { Dialog, DialogContent, SelectSearch } from 'forlogic-core';
+
+function MyComponent() {
+  const [dialogContentRef, setDialogContentRef] = useState<HTMLDivElement | null>(null);
+  const [selected, setSelected] = useState<string>('');
+
+  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">
+          <SelectSearch
+            options={categoryOptions}
+            value={selected}
+            onChange={setSelected}
+            placeholder="Selecione..."
+            popoverContainer={dialogContentRef}  {/* ✅ CRÍTICO para scroll funcionar */}
+          />
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+**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
+}
+```
+
+### **MultiSelect - Seleção Múltipla**
+
+**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)
+
+**Exemplo:**
+
+```typescript
+import { MultiSelect } from 'forlogic-core';
+
+const [selectedFrameworks, setSelectedFrameworks] = useState<string[]>([]);
+
+<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]
+/>
+```
+
+**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**
+
+**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
+
+**Exemplo:**
+
+```typescript
+import { EntitySelect } from 'forlogic-core';
+
+const [selectedFramework, setSelectedFramework] = useState<string>('');
+
+<EntitySelect
+  items={frameworks}
+  value={selectedFramework}
+  onChange={setSelectedFramework}
+  getItemValue={(opt) => opt.id}
+  getItemLabel={(opt) => opt.name}
+  placeholder="Selecione um framework..."
+  searchPlaceholder="Buscar framework..."
+/>
+```
+
+### **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**
+
+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
+
+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)
+
+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**
+
+Tanto `SelectSearch` quanto `MultiSelect` funcionam perfeitamente dentro de `Dialog`, mas requerem configuração específica:
+
+**✅ Configuração correta:**
+
+```typescript
+// 1. State para ref do DialogContent
+const [dialogContentRef, setDialogContentRef] = useState<HTMLDivElement | null>(null);
+
+// 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>
+```
+
+**❌ Erros comuns:**
+
+```typescript
+// ❌ ERRADO: Sem popoverContainer
+<SelectSearch options={options} value={selected} onChange={setSelected} />
+
+// ❌ ERRADO: DialogContent sem overflow-visible
+<DialogContent className="max-h-[90vh] overflow-auto">
+
+// ❌ ERRADO: Usar document.body como container (perde scroll)
+<SelectSearch popoverContainer={document.body} />
+```
+
+---
+
 ## 🔍 FILTROS NO BACKEND (Backend Filtering)
 
 ### **Por que Filtros no Backend?**
@@ -6051,4 +6285,4 @@ src/
 
 ## 📝 Licença
 
-MIT License - ForLogic © 2025
+MIT License - ForLogic © 2025