forlogic-core 2.0.2 → 2.0.4

package/docs/design-system/notifications-feedback.md

@@ -0,0 +1,137 @@
+<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
+<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
+
+# Notifications & Feedback
+
+Categoria: **Notifications & Feedback** | 4 componentes
+
+### 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.
+
+**Uso:**
+```tsx
+import { toast } from "sonner"
+
+// Informativo (BG #FFFFFF)
+toast("Mensagem simples")
+toast.info("Informação importante")
+
+// Sucesso (BG #E0FBE8)
+toast.success("Operação concluída")
+
+// Alerta (BG #FEF3C8)
+toast.warning("Atenção necessária")
+
+// Erro (BG #FEE1E1)
+toast.error("Algo deu errado")
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `message` | `string | ReactNode` | - | Texto principal ou conteúdo do toast. |
+| `description` | `string | ReactNode` | - | Descrição adicional exibida abaixo do título. |
+| `action` | `{ label: string, onClick: () => void }` | - | Botão de ação principal. |
+| `cancel` | `{ label: string, onClick: () => void }` | - | Botão de cancelamento secundário. |
+| `duration` | `number` | 4000 | Duração em ms antes de dispensar. Use Infinity para persistir. |
+| `closeButton` | `boolean` | false | Exibe botão X para fechar o toast. |
+| `icon` | `ReactNode` | - | Ícone personalizado para o toast. |
+| `id` | `string | number` | - | ID único para atualizar ou dispensar o toast. |
+| `onDismiss` | `(toast) => void` | - | Callback executado quando o toast é dispensado. |
+| `onAutoClose` | `(toast) => void` | - | Callback executado quando o toast fecha automaticamente. |
+
+**Exemplos:**
+```tsx
+// Toast é um feedback temporário e não bloqueante
+// - Informa rapidamente o usuário
+// - Não compete visualmente com outros Toasts
+// - Empilhamento vertical sem sobreposição
+// - Ordem previsível: mais recente no topo
+```
+```tsx
+// Empilhamento vertical com espaçamento consistente
+toast.success(
+```
+```tsx
+// Configuração de posição no Toaster:
+<Sonner
+  position=
+```
+
+**Acessibilidade:**
+- Utiliza ARIA live regions para anunciar toasts aos leitores de tela
+- Dispensável via tecla Escape
+- Auto-dispensa com duração configurável respeitando usabilidade
+- Suporte a swipe para dispensar em dispositivos touch
+- Respeita prefers-reduced-motion do sistema operacional
+- Foco gerenciado corretamente quando toast contém elementos interativos
+
+**Notas:**
+- Informativo (#FFFFFF): toast() e toast.info() - Para informações contextuais e notificações neutras
+- Sucesso (#E0FBE8): toast.success() - Para feedback de operações bem-sucedidas
+- Alerta (#FEF3C8): toast.warning() - Para alertas que requerem atenção do usuário
+- Erro (#FEE1E1): toast.error() - Para erros e falhas, considere incluir ação de retry
+- Use toast.promise() para operações assíncronas com feedback de loading
+- Mantenha mensagens curtas e objetivas (máximo 2 linhas)
+- Forneça ação de 
+-  para operações destrutivas quando possível
+- Evite usar duration: Infinity sem closeButton ou action para dispensar
+
+> Fonte: `src\design-system\docs\components\ToastDoc.tsx`
+
+---
+
+### Updates Notification
+
+Botão com popover para exibir notificações de atualização das aplicações. Possui dois modos: automático (self-contained, busca dados da API sozinho) e controlado (recebe dados via props).
+
+**Uso:**
+```tsx
+// Modo automático — basta importar e usar, sem props
+// O componente busca dados da API internamente usando useAuth() e useUpdatesNotification()
+import { UpdatesNotification } from 'forlogic-core';
+
+<UpdatesNotification />
+
+// Modo controlado — para testes, docs ou lógica customizada
+<UpdatesNotification
+  updates={[{ id: '1', title: 'Nova versão', text: 'Descrição' }]}
+  badgeCount={1}
+  onOpen={() => markAsViewed()}
+  onViewAll={() => window.open('https://apps4.qualiex.com/common/alias/up/view', '_blank')}
+/>
+```
+
+**Exemplos:**
+```tsx
+import { UpdatesNotification } from
+```
+
+**Notas:**
+- O componente possui dois modos: automático (sem props) e controlado (com props). O modo é determinado pela presença da prop updates.
+- No modo automático, o componente usa useAuth() para obter o alias e useUpdatesNotification() para buscar dados da API.
+- No modo controlado, todas as props são fornecidas externamente — útil para testes e documentação.
+- O tipo canônico é UpdateNotificationItem (id, title, text), exportado do hook. UpdateNotification é um alias deprecated.
+- No modo automático, onOpen chama markAsVisualized (POST Updates/userVisualized/3/undefined) e onViewAll abre a rota legada.
+- O ícone utilizado é Coffee do Lucide React — não requer fontes externas nos projetos consumidores.
+- O hook useUpdatesNotification também é exportado separadamente para uso avançado.
+- Todas as chamadas à API incluem o header x-waf-rate (base64 do campo sub do JWT), exigido pelo WAF da API legada.
+- Em caso de 401, o hook faz retry automático regenerando o token via QualiexErrorInterceptor.
+- Em produção, o componente deve ser colocado no AppHeader — já está integrado no forlogic-core.
+
+> Fonte: `src\design-system\docs\components\UpdatesNotificationDoc.tsx`
+
+---
+
+### Electronic Signature
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---
+
+### ErrorBoundary
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---

package/docs/design-system/platform.md

@@ -0,0 +1,95 @@
+<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
+<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
+
+# Plataforma
+
+Categoria: **Plataforma** | 6 componentes
+
+### Autenticação (Auth)
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---
+
+### Alias via URL
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---
+
+### Acesso Módulo (ModuleAccess)
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---
+
+### Assinatura Digital (Sign)
+
+Componente único multi-provider de assinatura digital com fluxo em 3 fases: Upload → Assinatura → Download. Suporta Clicksign (widget JavaScript embedded v2.1.0, API v3) e D4Sign (iframe embedded, API v1). O provedor é resolvido automaticamente pela configuração da unidade na tabela sign_configs.
+
+**Uso:**
+```tsx
+// Uso básico — provedor resolvido automaticamente pela config da unidade
+<DocumentSigner
+  showEventLog
+  onDocumentSigned={(data) => {
+    // data.provider → 'clicksign' ou 'd4sign'
+    // data.envelope_id, data.document_id, data.signer_id, data.environment
+    console.log('Assinado:', data);
+  }}
+  onError={(error) => {
+    console.error('Erro:', error.message);
+  }}
+/>
+
+// Passando PDF programaticamente (sem upload manual)
+<DocumentSigner
+  file={meuArquivoPdf}
+  onDocumentSigned={(data) => console.log('Assinado:', data)}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `file` | `File` | - | PDF passado programaticamente (pula upload manual) |
+| `onDocumentSigned` | `(data: SignEnvelopeResult) => void` | - | Callback quando o documento é assinado. Retorna provider, envelope_id, document_id, signer_id, environment. |
+| `onError` | `(error: Error) => void` | - | Callback em caso de erro |
+| `showEventLog` | `boolean` | false | Exibe log de eventos no componente |
+
+**Exemplos:**
+```tsx
+import { DocumentSigner } from
+```
+```tsx
+import { DocumentSigner } from
+```
+
+**Notas:**
+- Multi-provider: suporta Clicksign e D4Sign. O provedor é resolvido automaticamente pela configuração da unidade na tabela sign_configs.
+- Clicksign: Widget embedded v2.1.0 com script carregado automaticamente pela lib (lazy load sob demanda). Usa API v3 com header 
+-  (sem Bearer). Não é necessário adicionar nenhum script no index.html.
+- D4Sign: iframe embedded apontando para secure.d4sign.com.br/embed/viewblob/{uuid}. Usa API v1 com tokenAPI + cryptKey como query params.
+- D4Sign NÃO possui sandbox automático via secrets. É necessário configurar a unidade diretamente na tabela sign_configs (via /a/cs).
+- Clicksign possui fallback automático para sandbox via secret CLICKSIGN_SANDBOX_API_KEY.
+- Tabela unificada sign_configs com coluna provider (clicksign | d4sign). Campos extras do D4Sign: crypt_key, uuid_safe.
+- Após assinatura: polling automático busca documento assinado a cada 10s, até 6 tentativas (~1 min).
+- Se polling falhar, botão 
+-  permite busca manual ilimitada.
+- Configuração de produção: Admin → /a/cs (aba Assinatura digital).
+
+> Fonte: `src\design-system\docs\components\SignDoc.tsx`
+
+---
+
+### Segurança (Vite Config)
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---
+
+### Environments (Config)
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---

package/docs/design-system/selectors.md

@@ -0,0 +1,424 @@
+<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
+<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
+
+# Seletores
+
+Categoria: **Seletores** | 7 componentes
+
+### TreeSelect (ComboTree)
+
+Componente de seleção hierárquica (tree view) com busca recursiva, expansão por chevron e seleção por label. Também disponível como TreeSelect.
+
+**Uso:**
+```tsx
+import { ComboTree, type ComboTreeOption } from 'forlogic-core';
+// 💡 Alias disponível: import { TreeSelect, type TreeSelectProps } from 'forlogic-core';
+import { Folder, FolderOpen, FileText } from 'lucide-react';
+
+const options: ComboTreeOption[] = [
+  {
+    value: 'quality',
+    label: 'Qualidade',
+    icon: Folder,
+    iconOpen: FolderOpen,
+    children: [
+      { value: 'docs', label: 'Documentos', icon: FileText },
+      { value: 'occurrences', label: 'Ocorrências', icon: FileText },
+    ],
+  },
+  { value: 'hr', label: 'RH' },
+];
+
+<ComboTree
+  options={options}
+  value={selected}
+  onChange={setSelected}
+  label="Departamento"
+  placeholder="Selecione..."
+/>
+```
+
+**Acessibilidade:**
+- Navegação por teclado com Tab e Enter
+- Aria-expanded indica estado de expansão dos nós
+- Role tree e treeitem para semântica correta
+- Busca por texto filtra sem perder contexto hierárquico
+
+**Notas:**
+- 💡 Alias: Também disponível como 
+-  — import { TreeSelect } from 
+- ,
+        
+- ,
+        
+
+> Fonte: `src\design-system\docs\components\ComboTreeDoc.tsx`
+
+---
+
+### AutoComplete (Combobox)
+
+Componente versátil para seleção única ou múltipla com busca inteligente. Combina Popover e Command para autocomplete. Também disponível como AutoComplete. O componente Command é usado internamente para fornecer funcionalidades de busca e navegação por teclado.
+
+**Uso:**
+```tsx
+import { Combobox } from "forlogic-core"
+
+const options = [
+  { value: 'next.js', label: 'Next.js' },
+  { value: 'sveltekit', label: 'SvelteKit' },
+]
+
+// Seleção única
+<Combobox
+  options={options}
+  value={selected}
+  onChange={setSelected}
+  placeholder="Select..."
+/>
+
+// Seleção múltipla
+<Combobox
+  multiple
+  options={options}
+  value={selectedArray}
+  onChange={setSelectedArray}
+  placeholder="Select multiple..."
+/>
+
+// =====================
+// POPOVER COM COMMAND
+// =====================
+import { Popover, PopoverTrigger, PopoverContent, Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, Button } from "forlogic-core"
+
+<Popover open={open} onOpenChange={setOpen}>
+  <PopoverTrigger asChild>
+    <Button variant="outline">
+      {selectedStatus ? selectedStatus.label : "+ Definir status"}
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent className="p-0 bg-popover" side="right" align="start">
+    <Command>
+      <CommandInput placeholder="Alterar status..." />
+      <CommandList>
+        <CommandEmpty>Nenhum resultado.</CommandEmpty>
+        <CommandGroup>
+          {statuses.map((status) => (
+            <CommandItem
+              key={status.value}
+              value={status.value}
+              onSelect={(value) => {
+                setSelectedStatus(statuses.find((s) => s.value === value))
+                setOpen(false)
+              }}
+            >
+              {status.label}
+            </CommandItem>
+          ))}
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  </PopoverContent>
+</Popover>
+
+// =====================
+// DROPDOWN MENU COM COMMAND
+// =====================
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent } from "forlogic-core"
+
+<DropdownMenu open={open} onOpenChange={setOpen}>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost" size="sm">
+      <MoreVertical className="h-4 w-4" />
+    </Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end" className="w-[200px] bg-popover">
+    <DropdownMenuLabel>Ações</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuSub>
+      <DropdownMenuSubTrigger>Aplicar label</DropdownMenuSubTrigger>
+      <DropdownMenuSubContent className="p-0 bg-popover">
+        <Command>
+          <CommandInput placeholder="Filtrar label..." />
+          <CommandList>
+            <CommandEmpty>Nenhum label encontrado.</CommandEmpty>
+            <CommandGroup>
+              {labels.map((label) => (
+                <CommandItem
+                  key={label}
+                  value={label}
+                  onSelect={(value) => {
+                    setLabel(value)
+                    setOpen(false)
+                  }}
+                >
+                  {label}
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </DropdownMenuSubContent>
+    </DropdownMenuSub>
+  </DropdownMenuContent>
+</DropdownMenu>
+
+// =====================
+// RESPONSIVO (Popover/Drawer)
+// =====================
+import { useMediaQuery } from "@/design-system/hooks/useMediaQuery"
+import { Drawer, DrawerTrigger, DrawerContent } from "forlogic-core"
+
+function ResponsiveCombobox() {
+  const isDesktop = useMediaQuery("(min-width: 768px)")
+
+  if (isDesktop) {
+    return (
+      <Popover>
+        <PopoverTrigger asChild>
+          <Button>Definir status</Button>
+        </PopoverTrigger>
+        <PopoverContent className="p-0 bg-popover">
+          <StatusList />
+        </PopoverContent>
+      </Popover>
+    )
+  }
+
+  return (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <Button>Definir status</Button>
+      </DrawerTrigger>
+      <DrawerContent>
+        <StatusList />
+      </DrawerContent>
+    </Drawer>
+  )
+}
+```
+
+**Acessibilidade:**
+- Navegação completa por teclado
+- Busca inteligente (sem acentos, case-insensitive)
+- Segue padrão WAI-ARIA combobox
+- Anúncios para leitores de tela
+- Badges removíveis com teclado (modo múltiplo)
+- Versão responsiva com Drawer para mobile
+
+**Notas:**
+- 💡 Alias: Também disponível como 
+-  — import { AutoComplete } from 
+- ,
+        
+
+> Fonte: `src\design-system\docs\components\ComboboxDoc.tsx`
+
+---
+
+### TreeSelect (ComboTree)
+
+Componente de seleção hierárquica (tree view) com busca recursiva, expansão por chevron e seleção por label. Também disponível como TreeSelect.
+
+**Uso:**
+```tsx
+import { ComboTree, type ComboTreeOption } from 'forlogic-core';
+// 💡 Alias disponível: import { TreeSelect, type TreeSelectProps } from 'forlogic-core';
+import { Folder, FolderOpen, FileText } from 'lucide-react';
+
+const options: ComboTreeOption[] = [
+  {
+    value: 'quality',
+    label: 'Qualidade',
+    icon: Folder,
+    iconOpen: FolderOpen,
+    children: [
+      { value: 'docs', label: 'Documentos', icon: FileText },
+      { value: 'occurrences', label: 'Ocorrências', icon: FileText },
+    ],
+  },
+  { value: 'hr', label: 'RH' },
+];
+
+<ComboTree
+  options={options}
+  value={selected}
+  onChange={setSelected}
+  label="Departamento"
+  placeholder="Selecione..."
+/>
+```
+
+**Acessibilidade:**
+- Navegação por teclado com Tab e Enter
+- Aria-expanded indica estado de expansão dos nós
+- Role tree e treeitem para semântica correta
+- Busca por texto filtra sem perder contexto hierárquico
+
+**Notas:**
+- 💡 Alias: Também disponível como 
+-  — import { TreeSelect } from 
+- ,
+        
+- ,
+        
+
+> Fonte: `src\design-system\docs\components\ComboTreeDoc.tsx`
+
+---
+
+### Color Picker
+
+Seletor de cores com paleta predefinida e seletor customizado.
+
+**Uso:**
+```tsx
+import { ColorPicker } from "forlogic-core"
+import { useState } from 'react'
+
+const [color, setColor] = useState('#3b82f6')
+
+<ColorPicker
+  value={color}
+  onChange={setColor}
+  label="Escolha uma cor"
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `value` | `string` | #3b82f6 | Cor atual selecionada (formato hexadecimal). |
+| `onChange` | `(color: string) => void` | - | Callback quando a cor é alterada. |
+| `label` | `string` | - | Label opcional para o campo. |
+
+**Acessibilidade:**
+- Botão com papel semântico correto
+- Input de cor nativo acessível
+- Labels descritivos para cores predefinidas
+- Navegação por teclado completa
+
+> Fonte: `src\design-system\docs\components\ColorPickerDoc.tsx`
+
+---
+
+### Icon Picker
+
+Seletor de ícones da biblioteca Lucide React com busca integrada.
+
+**Uso:**
+```tsx
+import { IconPicker } from "forlogic-core"
+import { useState } from 'react'
+
+const [icon, setIcon] = useState('Star')
+
+<IconPicker
+  value={icon}
+  onChange={setIcon}
+  label="Escolha um ícone"
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `value` | `string` | Star | Nome do ícone selecionado (Lucide React). |
+| `onChange` | `(iconName: string) => void` | - | Callback quando o ícone é alterado. |
+| `label` | `string` | - | Label opcional para o campo. |
+
+**Acessibilidade:**
+- Busca por nome do ícone
+- Grid acessível por teclado
+- Títulos descritivos em cada ícone
+- Indicador visual de seleção
+- Scroll area com navegação adequada
+
+> Fonte: `src\design-system\docs\components\IconPickerDoc.tsx`
+
+---
+
+### Calendar & Date Picker
+
+Componentes para seleção de datas. O Calendar exibe um calendário interativo, enquanto o Date Picker combina um campo de input com o calendário em um popover.
+
+**Uso:**
+```tsx
+import { Calendar, DatePicker } from "forlogic-core"
+import { useState } from "react"
+
+// Calendar
+const [date, setDate] = useState<Date | undefined>(new Date())
+
+<Calendar
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  className="rounded-md border"
+/>
+
+// Date Picker
+<DatePicker 
+  date={date}
+  onDateChange={setDate}
+  placeholder="Selecione uma data"
+/>
+```
+
+**Acessibilidade:**
+- Navegação completa por teclado
+- Teclas de seta para navegar entre datas
+- Page Up/Down para navegação mensal
+- Labels e roles ARIA apropriados
+- Gerenciamento de foco adequado
+
+> Fonte: `src\design-system\docs\components\CalendarDoc.tsx`
+
+---
+
+### RequiredFieldsCounter
+
+Indica o progresso de preenchimento de campos obrigatórios em formulários com feedback visual e tooltips informativos.
+
+**Uso:**
+```tsx
+import { RequiredFieldsCounter } from "@/design-system/components/RequiredFieldsCounter"
+
+// Progresso parcial
+<RequiredFieldsCounter filled={2} total={5} />
+
+// Formulário completo
+<RequiredFieldsCounter filled={5} total={5} />
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `filled` | `number` | - | Quantidade de campos obrigatórios preenchidos |
+| `total` | `number` | - | Total de campos obrigatórios no formulário |
+
+**Exemplos:**
+```tsx
+<RequiredFieldsCounter filled={2} total={5} />
+```
+```tsx
+<RequiredFieldsCounter filled={5} total={5} />
+```
+
+**Acessibilidade:**
+- Usa Tooltip para fornecer informações adicionais sobre campos faltantes
+- Cores semânticas (success para completo, muted para incompleto) auxiliam na identificação visual
+- Animação sutil no ícone de check fornece feedback de conclusão
+- Texto sempre visível, não depende apenas de cor para transmitir informação
+
+**Notas:**
+- O componente usa a animação 
+-  definida no tailwind.config.ts
+- Importar de 
+-  ou diretamente de 
+- ,
+        
+
+> Fonte: `src\design-system\docs\components\RequiredFieldsCounterDoc.tsx`
+
+---