forlogic-core 1.11.7 → 1.12.0

package/README.md

@@ -836,6 +836,140 @@ Se você não fornecer um `queryClient`, o `CoreProviders` cria um com as seguin
 
 ---
 
+## 🎯 Ações Principais de Módulo (SidebarActionTrigger)
+
+O `SidebarActionTrigger` permite adicionar ações principais de módulo no sidebar, diferenciadas visualmente da navegação. São gatilhos de ação, não destinos de navegação.
+
+### Conceito
+
+| Característica | Descrição |
+|----------------|-----------|
+| **Ação de módulo** | Válida apenas dentro do contexto do módulo ao qual pertence |
+| **Não global** | Não aplicável a todo o sistema |
+| **Não contextual** | Não depende de seleção de item específico |
+| **Destaque visual** | Exibida com aparência diferenciada da navegação |
+
+### Uso Básico
+
+```tsx
+import { AppSidebar, SidebarConfig } from 'forlogic-core';
+import { Plus, FileText, Folder } from 'lucide-react';
+
+const sidebarConfig: SidebarConfig = {
+  appName: 'Meu Módulo',
+  
+  // Ações principais do módulo
+  moduleActions: {
+    triggerLabel: 'Criar',
+    triggerIcon: Plus,
+    actions: [
+      { 
+        id: 'create-item', 
+        label: 'Novo Item', 
+        icon: FileText, 
+        onClick: () => openCreateDialog() 
+      },
+      { 
+        id: 'create-folder', 
+        label: 'Nova Pasta', 
+        icon: Folder, 
+        onClick: () => openFolderDialog() 
+      },
+    ]
+  },
+  
+  // Navegação
+  navigation: [
+    { label: 'Visão Geral', path: '/', icon: Home },
+    { label: 'Configurações', path: '/settings', icon: Settings },
+  ]
+};
+
+<AppSidebar config={sidebarConfig} />
+```
+
+### Comportamento
+
+| Cenário | Comportamento |
+|---------|---------------|
+| **Uma ação** | Clique executa a ação diretamente |
+| **Múltiplas ações** | Clique exibe dropdown com opções |
+| **Modal aberto** | Gatilho fica desabilitado |
+| **Sidebar colapsada** | Exibe apenas ícone com tooltip |
+
+### Props do SidebarActionTrigger
+
+| Prop | Tipo | Obrigatório | Descrição |
+|------|------|-------------|-----------|
+| `config` | `SidebarActionsConfig` | ✅ | Configuração das ações |
+| `isCollapsed` | `boolean` | ❌ | Se a sidebar está colapsada |
+| `isDisabled` | `boolean` | ❌ | Desabilita o gatilho |
+
+### Interface SidebarModuleAction
+
+```typescript
+interface SidebarModuleAction {
+  id: string;           // Identificador único
+  label: string;        // Texto do botão/opção
+  icon?: LucideIcon;    // Ícone opcional
+  onClick: () => void;  // Callback de execução
+  disabled?: boolean;   // Estado desabilitado
+  permissionCheck?: () => Promise<boolean>;
+}
+```
+
+### Interface SidebarActionsConfig
+
+```typescript
+interface SidebarActionsConfig {
+  triggerLabel?: string;    // Rótulo do gatilho (padrão: 'Criar')
+  triggerIcon?: LucideIcon; // Ícone do gatilho (padrão: Plus)
+  actions: SidebarModuleAction[];
+}
+```
+
+### Gerenciamento de Modais (Opcional)
+
+Para desabilitar o gatilho quando há modais abertos, use o `ModalStateProvider`:
+
+```tsx
+import { CoreProviders, ModalStateProvider, useModalState } from 'forlogic-core';
+
+// No App.tsx (opcional - CoreProviders não inclui por padrão)
+<CoreProviders>
+  <ModalStateProvider>
+    <AppLayout />
+  </ModalStateProvider>
+</CoreProviders>
+
+// Em componentes com modal
+function MeuDialog({ open, onOpenChange }) {
+  const { registerModal, unregisterModal } = useModalState();
+  
+  useEffect(() => {
+    if (open) {
+      registerModal('meu-dialog');
+    } else {
+      unregisterModal('meu-dialog');
+    }
+  }, [open]);
+  
+  return <Dialog open={open} onOpenChange={onOpenChange}>...</Dialog>;
+}
+```
+
+### Diretriz para Uso via Prompt
+
+#### ✅ Prompts corretos:
+- "Adicione uma ação principal 'Criar Processo' no sidebar do módulo"
+- "Configure o módulo para ter duas ações principais: 'Novo Item' e 'Nova Pasta'"
+- "Adicione o botão de criar no topo do sidebar como ação de módulo"
+
+#### ❌ Prompts ambíguos (evitar):
+- "Coloque um botão de criar no menu" (ambíguo - qual menu?)
+- "Adicione navegação para criar" (ação ≠ navegação)
+- "Crie um link para nova entidade" (link = navegação, não ação)
+
 ## 🛠️ CLI: Sincronização de Documentação
 
 O `forlogic-core` disponibiliza um comando CLI para sincronizar a documentação centralizada do banco de dados para projetos consumidores.
@@ -882,7 +1016,7 @@ O comando usa credenciais públicas do Supabase do forlogic-core e não requer c
 
 ### 📚 Estatísticas da Documentação
 
-**49 Componentes UI** | **6 Tokens** | **2 Ferramentas CRUD**
+**47 Componentes UI** | **6 Tokens** | **6 Ferramentas CRUD**
 
 ---
 
@@ -922,10 +1056,8 @@ O comando usa credenciais públicas do Supabase do forlogic-core e não requer c
 - [Icon Picker](./docs/DESIGN_SYSTEM.md#iconpicker) - Seletor de ícones da biblioteca Lucide React com busca integrada.
 - [Input](./docs/DESIGN_SYSTEM.md#input) - Exibe um campo de entrada de texto.
 - [Input Group](./docs/DESIGN_SYSTEM.md#inputgroup) - Agrupe inputs com addons de prefixo, sufixo, ícones, botões, tooltips e dropdowns. Segue a API oficial do shadcn/ui.
-- [Input OTP](./docs/DESIGN_SYSTEM.md#inputotp) - Accessible one-time password component with customizable number of inputs. Available in the UI library but not exported from forlogic-core.
 - [Label](./docs/DESIGN_SYSTEM.md#label) - Renderiza uma label acessível associada a controles.
 - [Loading State](./docs/DESIGN_SYSTEM.md#loadingstate) - Componente para gerenciar estados de loading de forma declarativa com dois tipos: spinner e overlay.
-- [Native Select](./docs/DESIGN_SYSTEM.md#nativeselect) - Elemento select nativo do HTML com estilização.
 - [Pagination](./docs/DESIGN_SYSTEM.md#pagination) - Barra de paginação completa com seletor de itens por página e controles de navegação.
 - [Progress](./docs/DESIGN_SYSTEM.md#progress) - Exibe um indicador mostrando o progresso de conclusão de uma tarefa, tipicamente exibido como uma barra de progresso.
 - [Radio Group](./docs/DESIGN_SYSTEM.md#radiogroup) - Um conjunto de botões marcáveis—conhecidos como botões de rádio—onde apenas um pode ser marcado por vez.
@@ -944,11 +1076,15 @@ O comando usa credenciais públicas do Supabase do forlogic-core e não requer c
 - [Table](./docs/DESIGN_SYSTEM.md#table) - Uma tabela semântica para exibir dados tabulares.
 - [Tabs](./docs/DESIGN_SYSTEM.md#tabs) - Um conjunto de seções de conteúdo em camadas—conhecidas como painéis de abas—que são exibidas uma de cada vez.
 - [Textarea](./docs/DESIGN_SYSTEM.md#textarea) - Exibe um textarea de formulário ou um componente que se parece com um textarea.
-- [Toast](./docs/DESIGN_SYSTEM.md#toast) - Componente de notificação toast usando Sonner. Exibe mensagens temporárias para feedback de ações do usuário.
+- [Toast](./docs/DESIGN_SYSTEM.md#toast) - Componente de notificação toast usando Sonner. Feedback temporário e não bloqueante que informa rapidamente o usuário sem competir visualmente com outros Toasts.
 - [Toggle](./docs/DESIGN_SYSTEM.md#toggle) - Botões de dois estados que podem estar ligados ou desligados, individualmente ou em grupo.
 
 ### 🚀 Sistema CRUD
 
+- [CRUD Avançado](./docs/DESIGN_SYSTEM.md#crudadvanced) - Padrão de tabela CRUD com recursos avançados como avatar de produto, indicadores visuais de estoque, sistema de avaliação com estrelas, métricas de vendas e formatação de moeda. Inclui dialogs para todas as operações CRUD, exportação/importação e ações em massa.
+- [CRUD Básico](./docs/DESIGN_SYSTEM.md#crudbasic) - Padrão de tabela CRUD simples com busca, filtros, ações por linha e paginação. Inclui dialogs interativos para visualização, criação, edição, duplicação, alteração de status e exclusão de itens.
+- [CRUD com Alternância de Visualização](./docs/DESIGN_SYSTEM.md#crudviewtoggle) - Padrão de CRUD que permite alternar entre visualização em lista (cards horizontais) e grade (cards em grid). Inclui todas as operações CRUD com dialogs, exportação/importação e ações em massa.
+- [CRUD de Fornecedores](./docs/DESIGN_SYSTEM.md#crudusers) - Padrão completo de CRUD para gestão de fornecedores com 16 campos, incluindo ordenação, filtros avançados, exportação/importação e ações em massa.
 - [CRUD System](./docs/DESIGN_SYSTEM.md#crudsystem) - Sistema completo para criação rápida de interfaces CRUD com validação, busca, paginação e muito mais.
 - [Wizard Form](./docs/DESIGN_SYSTEM.md#wizardform) - Formulário multi-etapas com validação, navegação entre seções e indicadores de progresso.
 

package/dist/README.md

@@ -836,6 +836,140 @@ Se você não fornecer um `queryClient`, o `CoreProviders` cria um com as seguin
 
 ---
 
+## 🎯 Ações Principais de Módulo (SidebarActionTrigger)
+
+O `SidebarActionTrigger` permite adicionar ações principais de módulo no sidebar, diferenciadas visualmente da navegação. São gatilhos de ação, não destinos de navegação.
+
+### Conceito
+
+| Característica | Descrição |
+|----------------|-----------|
+| **Ação de módulo** | Válida apenas dentro do contexto do módulo ao qual pertence |
+| **Não global** | Não aplicável a todo o sistema |
+| **Não contextual** | Não depende de seleção de item específico |
+| **Destaque visual** | Exibida com aparência diferenciada da navegação |
+
+### Uso Básico
+
+```tsx
+import { AppSidebar, SidebarConfig } from 'forlogic-core';
+import { Plus, FileText, Folder } from 'lucide-react';
+
+const sidebarConfig: SidebarConfig = {
+  appName: 'Meu Módulo',
+  
+  // Ações principais do módulo
+  moduleActions: {
+    triggerLabel: 'Criar',
+    triggerIcon: Plus,
+    actions: [
+      { 
+        id: 'create-item', 
+        label: 'Novo Item', 
+        icon: FileText, 
+        onClick: () => openCreateDialog() 
+      },
+      { 
+        id: 'create-folder', 
+        label: 'Nova Pasta', 
+        icon: Folder, 
+        onClick: () => openFolderDialog() 
+      },
+    ]
+  },
+  
+  // Navegação
+  navigation: [
+    { label: 'Visão Geral', path: '/', icon: Home },
+    { label: 'Configurações', path: '/settings', icon: Settings },
+  ]
+};
+
+<AppSidebar config={sidebarConfig} />
+```
+
+### Comportamento
+
+| Cenário | Comportamento |
+|---------|---------------|
+| **Uma ação** | Clique executa a ação diretamente |
+| **Múltiplas ações** | Clique exibe dropdown com opções |
+| **Modal aberto** | Gatilho fica desabilitado |
+| **Sidebar colapsada** | Exibe apenas ícone com tooltip |
+
+### Props do SidebarActionTrigger
+
+| Prop | Tipo | Obrigatório | Descrição |
+|------|------|-------------|-----------|
+| `config` | `SidebarActionsConfig` | ✅ | Configuração das ações |
+| `isCollapsed` | `boolean` | ❌ | Se a sidebar está colapsada |
+| `isDisabled` | `boolean` | ❌ | Desabilita o gatilho |
+
+### Interface SidebarModuleAction
+
+```typescript
+interface SidebarModuleAction {
+  id: string;           // Identificador único
+  label: string;        // Texto do botão/opção
+  icon?: LucideIcon;    // Ícone opcional
+  onClick: () => void;  // Callback de execução
+  disabled?: boolean;   // Estado desabilitado
+  permissionCheck?: () => Promise<boolean>;
+}
+```
+
+### Interface SidebarActionsConfig
+
+```typescript
+interface SidebarActionsConfig {
+  triggerLabel?: string;    // Rótulo do gatilho (padrão: 'Criar')
+  triggerIcon?: LucideIcon; // Ícone do gatilho (padrão: Plus)
+  actions: SidebarModuleAction[];
+}
+```
+
+### Gerenciamento de Modais (Opcional)
+
+Para desabilitar o gatilho quando há modais abertos, use o `ModalStateProvider`:
+
+```tsx
+import { CoreProviders, ModalStateProvider, useModalState } from 'forlogic-core';
+
+// No App.tsx (opcional - CoreProviders não inclui por padrão)
+<CoreProviders>
+  <ModalStateProvider>
+    <AppLayout />
+  </ModalStateProvider>
+</CoreProviders>
+
+// Em componentes com modal
+function MeuDialog({ open, onOpenChange }) {
+  const { registerModal, unregisterModal } = useModalState();
+  
+  useEffect(() => {
+    if (open) {
+      registerModal('meu-dialog');
+    } else {
+      unregisterModal('meu-dialog');
+    }
+  }, [open]);
+  
+  return <Dialog open={open} onOpenChange={onOpenChange}>...</Dialog>;
+}
+```
+
+### Diretriz para Uso via Prompt
+
+#### ✅ Prompts corretos:
+- "Adicione uma ação principal 'Criar Processo' no sidebar do módulo"
+- "Configure o módulo para ter duas ações principais: 'Novo Item' e 'Nova Pasta'"
+- "Adicione o botão de criar no topo do sidebar como ação de módulo"
+
+#### ❌ Prompts ambíguos (evitar):
+- "Coloque um botão de criar no menu" (ambíguo - qual menu?)
+- "Adicione navegação para criar" (ação ≠ navegação)
+- "Crie um link para nova entidade" (link = navegação, não ação)
+
 ## 🛠️ CLI: Sincronização de Documentação
 
 O `forlogic-core` disponibiliza um comando CLI para sincronizar a documentação centralizada do banco de dados para projetos consumidores.