forlogic-core 2.0.3 → 2.0.4

package/docs/design-system/domain.md

@@ -0,0 +1,651 @@
+<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
+<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
+
+# Business Components
+
+Categoria: **Business Components** | 12 componentes
+
+### Action Plan
+
+Componente de página completa para gerenciar planos de ação. Inclui formulário com abas (Geral, Progresso, Predecessores, Custos, Comentários, Histórico, Anexos), mudança de status e reportes de progresso. As abas de Comentários, Histórico e Anexos são componentes internos portados das libs Angular (flc-comments, flc-history, flc-attachments) e são renderizados automaticamente quando habilitados via config.
+
+**Uso:**
+```tsx
+import { ActionPlanPage, ETaskPlanStatus } from "forlogic-core"
+
+<ActionPlanPage
+  actionPlan={actionPlan}
+  config={{
+    enablePredecessors: true,
+    enableCosts: true,
+    enableAttachments: true,
+    enableComments: true,
+    enableHistory: true,
+  }}
+  users={users}
+  places={places}
+  progress={progress}
+  comments={comments}
+  history={history}
+  attachments={attachments}
+  onSave={handleSave}
+  onCancel={() => navigate(-1)}
+  onChangeStatus={handleChangeStatus}
+  onReportProgress={handleReportProgress}
+  onAddComment={handleAddComment}
+  onUploadAttachment={handleUploadAttachment}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `actionPlan` | `ActionPlan | null` | - | Dados do plano de ação. null/undefined para novo. |
+| `isNew` | `boolean` | - | Se é um novo plano (oculta tabs extras e status). |
+| `config` | `ActionPlanFormConfig` | - | Configuração do formulário: campos obrigatórios, visíveis, tabs habilitadas (enableComments, enableHistory, enableAttachments). |
+| `isLoading` | `boolean` | - | Estado de loading global. |
+
+**Exemplos:**
+```tsx
+<ActionPlanPage
+  actionPlan={actionPlan}
+  config={{
+    enablePredecessors: true,
+    enableCosts: true,
+    enableAttachments: true,
+    enableComments: true,
+    enableHistory: true,
+    hasComments: true,
+  }}
+  users={users}
+  places={places}
+  actionTypes={actionTypes}
+  causes={causes}
+  progress={progress}
+  predecessors={predecessors}
+  costs={costs}
+  comments={comments}
+  history={history}
+  attachments={attachments}
+  onSave={handleSave}
+  onChangeStatus={handleChangeStatus}
+  onReportProgress={handleReportProgress}
+  onAddComment={handleAddComment}
+  onEditComment={handleEditComment}
+  onDeleteComment={handleDeleteComment}
+  onUploadAttachment={handleUploadAttachment}
+  onDeleteAttachment={handleDeleteAttachment}
+  onRenameAttachment={handleRenameAttachment}
+  onDownloadAttachment={handleDownloadAttachment}
+  onViewAttachment={handleViewAttachment}
+/>
+```
+```tsx
+<ActionPlanPage
+  isNew
+  config={{}}
+  users={users}
+  places={places}
+  onSave={handleSave}
+  onCancel={() => navigate(-1)}
+/>
+```
+```tsx
+import { ActionPlanStatusBadge, ETaskPlanStatus } from
+```
+
+**Notas:**
+- Os componentes internos de Comentários, Histórico e Anexos foram portados das libs Angular (flc-comments, flc-history, flc-attachments).
+- Comentários suportam CRUD completo com avatar, timestamps e label 
+- . @menções e Rich Text Editor serão adicionados em versão futura.
+- Histórico exibe timeline vertical com ícone, descrição, avatar do usuário, data/hora e indicador 
+-  para requisições mobile.
+- Anexos suportam upload múltiplo, barra de progresso, renomear inline, context menu (visualizar, download, excluir) e detecção de duplicatas.
+- Slots (attachmentsSlot, commentsSlot, historySlot) permitem substituir os componentes padrão por implementações customizadas do projeto consumidor.
+
+> Fonte: `src\design-system\docs\components\ActionPlanDoc.tsx`
+
+---
+
+### Approval Flow (Fluxo de Aprovação)
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---
+
+### Audit Trail
+
+Componente completo para visualização de trilha de auditoria (logs de alterações). Inclui filtros por módulo, evento, usuário e período, com visualização detalhada de cada registro.
+
+**Uso:**
+```tsx
+import { AuditTrailPage } from 'forlogic-core';
+
+<AuditTrailPage
+  softwares={softwares}
+  onFetchEvents={fetchEvents}
+  onSearch={searchAuditTrails}
+  onFetchDetails={fetchDetails}
+  onFetchUsers={fetchUsers}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `softwares` | `AuditTrailSoftware[]` | - | Lista de módulos disponíveis para filtro |
+| `onFetchEvents` | `(softwareId) => Promise<AuditTrailEvent[]>` | - | Busca eventos por módulo |
+| `onSearch` | `(params) => Promise<AuditTrail[]>` | - | Busca registros de auditoria |
+| `onFetchDetails` | `(id) => Promise<AuditTrailDetails>` | - | Busca detalhes de um registro |
+| `onFetchUsers` | `(query) => Promise<AuditTrailUserOption[]>` | - | Busca usuários para filtro |
+
+**Notas:**
+- Componente de página completa — inclui toolbar, filtros e tabela
+- Requer implementação dos callbacks de busca no backend
+
+> Fonte: `src\design-system\docs\components\AuditTrailDoc.tsx`
+
+---
+
+### Custom Form Fields
+
+Componente container que renderiza campos de formulário dinâmicos baseados em configuração. Suporta 9 tipos de campo: Texto Somente Leitura, Texto, Data, Hora, URL, Numérico, Seleção Única, Seleção Múltipla e Questões. Portado de FlcCustomFormFieldsComponent (flc-custom-form-fields).
+
+**Uso:**
+```tsx
+import { CustomFormFields, ECustomFormFieldType, validateFields } from "forlogic-core"
+import type { FieldAssociation } from "forlogic-core"
+
+const fields: FieldAssociation[] = [
+  {
+    id: 'f1',
+    type: ECustomFormFieldType.text,
+    name: 'Nome',
+    required: true,
+    config: { multiline: false },
+    isActive: true,
+  },
+  // ...mais campos
+];
+
+const [formFields, setFormFields] = useState(fields);
+
+<CustomFormFields
+  fields={formFields}
+  onChange={setFormFields}
+  onFieldChange={(field) => console.log('Changed:', field)}
+/>
+```
+
+**Notas:**
+- Portado de FlcCustomFormFieldsComponent (flc-custom-form-fields) Angular.
+- Tipos de campo: readOnlyText (1), text (2), date (3), time (4), url (5), number (6), singleSelection (7), multiSelection (8), questions (9).
+- Use validateFields() para validar campos obrigatórios e restrições numéricas.
+- Use getFormFieldValues() para extrair valores no formato de envio ao backend.
+- Use setFormFieldValues() para aplicar valores salvos a uma lista de campos.
+- Campos de seleção suportam dataSource custom (dados estáticos) e users (lista de usuários do sistema).
+
+> Fonte: `src\design-system\docs\components\CustomFormFieldsDoc.tsx`
+
+---
+
+### Select
+
+Exibe uma lista de opções para o usuário escolher—acionada por um botão.
+
+**Uso:**
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "forlogic-core"
+
+<Select>
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Theme" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="light">Light</SelectItem>
+    <SelectItem value="dark">Dark</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `defaultValue` | `string` | - | O valor selecionado padrão. |
+| `value` | `string` | - | O valor selecionado controlado. |
+| `onValueChange` | `(value: string) => void` | - | Manipulador de evento quando o valor muda. |
+| `disabled` | `boolean` | false | Se o select está desabilitado. |
+| `container (SelectContent)` | `HTMLElement` | - | Container HTML para portal (útil dentro de Dialog). |
+| `collisionBoundary (SelectContent)` | `HTMLElement` | - | Elemento para detecção de colisão de posicionamento. |
+
+**Acessibilidade:**
+- Navegação completa por teclado
+- Busca por digitação antecipada
+- Segue o padrão de listbox WAI-ARIA
+- Anúncios para leitores de tela
+
+**Notas:**
+- 💡 Use 
+-  e 
+-  quando o Select estiver dentro de um Dialog para evitar problemas de scroll
+- 💡 Para seleção com busca, considere usar 
+-  ao invés de 
+
+> Fonte: `src\design-system\docs\components\SelectDoc.tsx`
+
+---
+
+### Leadership
+
+Módulo hierárquico de liderança para gerenciar relações de liderança entre usuários do Qualiex. Inclui componentes visuais, hooks de API e utilitários para construção de árvores hierárquicas.
+
+**Uso:**
+```tsx
+// Página completa de liderança
+import { LeadershipPage } from 'forlogic-core';
+
+function MyLeadershipPage() {
+  return <LeadershipPage />;
+}
+
+// Ou use componentes individuais
+import { 
+  LeadershipDialog, 
+  useLeadershipApi 
+} from 'forlogic-core';
+
+function CustomLeadershipView() {
+  const { data: leaders, isLoading } = useLeadershipApi();
+  const [dialogOpen, setDialogOpen] = useState(false);
+
+  if (isLoading) return <div>Carregando...</div>;
+
+  return (
+    <div>
+      <Button onClick={() => setDialogOpen(true)}>
+        Adicionar Líder
+      </Button>
+      
+      <LeadershipDialog
+        open={dialogOpen}
+        onOpenChange={setDialogOpen}
+        title="Novo Líder"
+      />
+      
+      {/* Renderizar hierarquia */}
+    </div>
+  );
+}
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `LeadershipDialog.open` | `boolean` | - | Controla a visibilidade do dialog. |
+| `LeadershipDialog.onOpenChange` | `(open: boolean) => void` | - | Callback quando o estado de abertura muda. |
+| `LeadershipDialog.leader` | `Leader` | - | Líder a ser editado (se não fornecido, cria novo). |
+| `LeadershipDialog.prefilledLeaderId` | `string | null` | - | ID do líder superior pré-selecionado (para criação). |
+| `LeadershipDialog.title` | `string` | - | Título do dialog. |
+| `LeaderRow.leader` | `LeaderNode` | - | Nó do líder a ser renderizado. |
+| `LeaderRow.expandedIds` | `Set<string>` | - | IDs dos nós atualmente expandidos. |
+| `LeaderRow.onToggleExpand` | `(id: string) => void` | - | Callback para alternar expansão de um nó. |
+| `LeaderRow.onEdit` | `(leader: Leader) => void` | - | Callback quando o nome do líder é clicado. |
+| `LeadershipForm.leader` | `Leader` | - | Líder a ser editado (modo edição). |
+| `LeadershipForm.prefilledLeaderId` | `string | null` | - | ID do líder superior pré-selecionado. |
+| `LeadershipForm.onSuccess` | `() => void` | - | Callback executado após salvar com sucesso. |
+
+**Acessibilidade:**
+- Os botões de expandir/colapsar são acessíveis via teclado.
+- Os nomes clicáveis têm role=
+-  implícito.
+- O dialog segue padrões WAI-ARIA para modais.
+- Checkboxes de seleção de usuários são navegáveis via Tab.
+- Estados de loading são anunciados para leitores de tela.
+
+**Notas:**
+- O módulo requer autenticação ativa (useAuth) e integração com Qualiex.
+- Os dados são enriquecidos automaticamente com nomes/emails do Qualiex.
+- Líderes 
+-  são criados automaticamente para referências não cadastradas.
+- Validação de ciclos na hierarquia é feita automaticamente.
+- O estado de expansão é persistido no localStorage por alias.
+- Soft delete é usado para remoção (is_removed = true).
+
+> Fonte: `src\design-system\docs\components\LeadershipDoc.tsx`
+
+---
+
+### Media
+
+Módulo completo para upload, edição e renderização de imagens e vídeos. Inclui editores interativos, renderizadores otimizados e hook genérico de upload.
+
+**Uso:**
+```tsx
+// Exemplo básico de upload de imagem
+const { upload, uploading, progress } = useMediaUpload({
+  uploadFunction: async (file, options) => {
+    // Implementação do upload para seu storage
+    const url = await uploadToStorage(file, options);
+    return { url, path: file.name };
+  }
+});
+
+// Renderizar uma imagem
+<ImageRenderer
+  content={{
+    imageUrl: 'https://example.com/image.jpg',
+    caption: 'Legenda da imagem',
+    alignment: 'center'
+  }}
+/>
+
+// Renderizar um vídeo
+<VideoRenderer
+  content={{
+    videoUrl: 'https://youtube.com/watch?v=...',
+    controls: true
+  }}
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `uploadFunction` | `UploadFunction` | - | Função de upload customizada (obrigatória para uploads) |
+| `deleteFunction` | `DeleteFunction` | - | Função de delete customizada |
+| `defaultOptions` | `UploadOptions` | - | Opções padrão: bucket, maxSize, allowedTypes |
+| `onSuccess` | `(result: UploadResult) => void` | - | Callback executado após upload bem-sucedido |
+| `onError` | `(error: Error) => void` | - | Callback executado em caso de erro |
+| `value` | `ImageBlockContent | VideoBlockContent` | - | Valor atual do conteúdo |
+| `onChange` | `(value) => void` | - | Callback para mudanças no conteúdo |
+| `onSubmit` | `(value) => void` | - | Callback ao salvar o conteúdo |
+| `onCancel` | `() => void` | - | Callback ao cancelar edição |
+| `uploadOptions` | `UploadOptions` | - | Opções de upload específicas para o editor |
+| `content` | `ImageBlockContent | VideoBlockContent` | - | Conteúdo a ser renderizado |
+| `className` | `string` | - | Classes CSS adicionais |
+| `style` | `CSSProperties` | - | Estilos inline adicionais |
+
+**Exemplos:**
+```tsx
+import { useMediaUpload, getSupabaseClient } from
+```
+
+**Acessibilidade:**
+- ImageRenderer inclui atributo alt obrigatório para acessibilidade
+- VideoRenderer usa atributo title no iframe para identificação
+- Controles de vídeo habilitados por padrão para navegação por teclado
+- Autoplay sempre acompanhado de muted para conformidade com navegadores
+- Links de download possuem texto descritivo
+- Todos os inputs dos editores possuem labels associados
+
+**Notas:**
+- O hook useMediaUpload requer que o projeto forneça as funções de upload/delete
+- A função uploadFunction deve retornar { url: string, path?: string }
+- VideoRenderer detecta automaticamente YouTube e Vimeo pela URL
+- Para vídeos locais, use o player HTML5 nativo com controles
+- Dimensões são opcionais; imagens usam max-width: 100% por padrão
+- O módulo não inclui implementação de storage - use Supabase, S3, etc.
+- Helpers de imagem usam Canvas API para compressão e resize
+
+> Fonte: `src\design-system\docs\components\MediaDoc.tsx`
+
+---
+
+### Places
+
+Módulo para gerenciar estruturas hierárquicas de locais integrado com a API Qualiex. Inclui visualização em árvore, gestão de acessos e componentes reutilizáveis.
+
+**Uso:**
+```tsx
+// =====================
+// BUSCAR LOCAIS
+// =====================
+import { placeService } from 'forlogic-core';
+
+async function loadPlaces() {
+  const places = await placeService.getPlaces(alias, companyId);
+  // places já vem em estrutura hierárquica
+  console.log(places);
+}
+
+// =====================
+// LISTA SIMPLES (SEM GESTÃO DE ACESSOS)
+// =====================
+import { PlacesList } from 'forlogic-core';
+
+function MyPlacesPage() {
+  const [places, setPlaces] = useState<Place[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    placeService.getPlaces(alias, companyId)
+      .then(setPlaces)
+      .finally(() => setIsLoading(false));
+  }, [alias, companyId]);
+
+  return (
+    <PlacesList 
+      places={places} 
+      isLoading={isLoading} 
+    />
+  );
+}
+
+// =====================
+// COM GESTÃO DE ACESSOS
+// =====================
+import { PlacesList, PlaceCard } from 'forlogic-core';
+
+function PlacesWithAccess() {
+  const [places, setPlaces] = useState<Place[]>([]);
+  const [managers, setManagers] = useState<Record<string, string>>({});
+  const [members, setMembers] = useState<Record<string, string[]>>({});
+
+  const manageAccessConfig = {
+    onMakeManager: async (userId, placeId) => {
+      setManagers(prev => ({ ...prev, [placeId]: userId }));
+      // Chamar API para salvar
+    },
+    onMakeMembers: async (userIds, placeId) => {
+      setMembers(prev => ({ ...prev, [placeId]: userIds }));
+      // Chamar API para salvar
+    },
+    getCurrentManagerId: (placeId) => managers[placeId],
+    getCurrentMemberIds: (placeId) => members[placeId] || []
+  };
+
+  return (
+    <PlacesList 
+      places={places} 
+      isLoading={false}
+      manageAccessConfig={manageAccessConfig}
+    />
+  );
+}
+
+// =====================
+// PLACECARD INDIVIDUAL
+// =====================
+import { PlaceCard } from 'forlogic-core';
+
+<PlaceCard 
+  place={myPlace}
+  level={0}
+  manageAccessConfig={manageAccessConfig}
+/>
+```
+
+**Acessibilidade:**
+- Botões de expandir/colapsar acessíveis via teclado.
+- Modal segue padrões WAI-ARIA.
+- Checkboxes navegáveis por Tab.
+- Estados de loading anunciados para leitores de tela.
+- Busca de usuários com feedback visual.
+
+**Notas:**
+- Requer integração com API Qualiex configurada.
+- O placeService monta a hierarquia automaticamente.
+- O ManageAccessModal usa o hook useQualiexUsers internamente.
+- A gestão de acessos é opcional - sem manageAccessConfig, apenas exibe.
+- Níveis de hierarquia são controlados pela prop level no PlaceCard.
+
+> Fonte: `src\design-system\docs\components\PlacesDoc.tsx`
+
+---
+
+### QualiexUserField
+
+Campo de seleção de usuários integrado com a API Qualiex. Suporta seleção única ou múltipla, display customizado, filtros e funciona perfeitamente dentro de Dialogs.
+
+**Uso:**
+```tsx
+import { QualiexUserField } from "forlogic-core"
+
+// =====================
+// USO BÁSICO
+// =====================
+<QualiexUserField 
+  value={userId} 
+  onChange={setUserId}
+  placeholder="Selecione..."
+/>
+
+// =====================
+// COM LABEL E REQUIRED
+// =====================
+import { UserCheck } from "lucide-react"
+
+<QualiexUserField 
+  label="Responsável"
+  required
+  icon={UserCheck}
+  value={userId} 
+  onChange={setUserId}
+/>
+
+// =====================
+// SELEÇÃO MÚLTIPLA
+// =====================
+const [userIds, setUserIds] = useState<string[]>([])
+
+<QualiexUserField 
+  multiple
+  label="Avaliadores"
+  required
+  value={userIds} 
+  onChange={setUserIds}
+  maxDisplayedBadges={3}
+/>
+
+// =====================
+// DISPLAY CUSTOMIZADO
+// =====================
+
+// Exibir nome + email
+<QualiexUserField 
+  displayFormat="name-email"
+  value={userId} 
+  onChange={setUserId}
+/>
+
+// Exibir nome + cargo
+<QualiexUserField 
+  displayFormat="name-role"
+  value={userId} 
+  onChange={setUserId}
+/>
+
+// Custom display function
+<QualiexUserField 
+  displayFormat="custom"
+  customDisplayFn={(user) => \`\${user.userName} - \${user.placeName || 'Sem local'}\
+```
+
+**Acessibilidade:**
+- Navegação completa por teclado
+- Busca inteligente (sem acentos, case-insensitive)
+- Segue padrão WAI-ARIA combobox
+- Badges removíveis com teclado (modo múltiplo)
+- Estados de loading e erro acessíveis
+- Labels associados corretamente
+
+**Notas:**
+- Requer configuração Qualiex (apiUrl e apiToken) no projeto
+- Use enabled={false} para lazy loading e chame refetch() manualmente
+- Em Dialogs, sempre passe popoverContainer para evitar problemas de z-index
+- O hook useQualiexUsers é usado internamente para buscar os usuários
+- Integrado automaticamente com BaseForm via type=
+
+> Fonte: `src\design-system\docs\components\QualiexUserFieldDoc.tsx`
+
+---
+
+### Report Request List
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---
+
+### Select
+
+Exibe uma lista de opções para o usuário escolher—acionada por um botão.
+
+**Uso:**
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "forlogic-core"
+
+<Select>
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Theme" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="light">Light</SelectItem>
+    <SelectItem value="dark">Dark</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `defaultValue` | `string` | - | O valor selecionado padrão. |
+| `value` | `string` | - | O valor selecionado controlado. |
+| `onValueChange` | `(value: string) => void` | - | Manipulador de evento quando o valor muda. |
+| `disabled` | `boolean` | false | Se o select está desabilitado. |
+| `container (SelectContent)` | `HTMLElement` | - | Container HTML para portal (útil dentro de Dialog). |
+| `collisionBoundary (SelectContent)` | `HTMLElement` | - | Elemento para detecção de colisão de posicionamento. |
+
+**Acessibilidade:**
+- Navegação completa por teclado
+- Busca por digitação antecipada
+- Segue o padrão de listbox WAI-ARIA
+- Anúncios para leitores de tela
+
+**Notas:**
+- 💡 Use 
+-  e 
+-  quando o Select estiver dentro de um Dialog para evitar problemas de scroll
+- 💡 Para seleção com busca, considere usar 
+-  ao invés de 
+
+> Fonte: `src\design-system\docs\components\SelectDoc.tsx`
+
+---
+
+### Internacionalização (i18n)
+
+*Documentação não extraída automaticamente. Consulte o Design System interativo em `/ds`.*
+
+---