forlogic-core 3.0.11 → 4.0.0

package/docs/design-system/domain.md

@@ -1,671 +0,0 @@
-<!-- ⚠️ 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. O item selecionado é destacado por background (accent), fonte medium e borda esquerda na cor primary. A prop `showCheck` (opcional) adiciona um ícone de check à esquerda do item selecionado.
-
-**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. |
-| `showCheck` | `boolean` | false | Exibe o ícone de check à esquerda do item selecionado. Quando false, o item selecionado é destacado apenas pelo background, fonte medium e borda esquerda primary. |
-| `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 
-- ,
-        
-- rounded-lg
-- hover:border-primary
-- transition-colors
-- ,
-        
-- Combobox
-- showCheck
-
-> 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. O item selecionado é destacado por background (accent), fonte medium e borda esquerda na cor primary. A prop `showCheck` (opcional) adiciona um ícone de check à esquerda do item selecionado.
-
-**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. |
-| `showCheck` | `boolean` | false | Exibe o ícone de check à esquerda do item selecionado. Quando false, o item selecionado é destacado apenas pelo background, fonte medium e borda esquerda primary. |
-| `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 
-- ,
-        
-- rounded-lg
-- hover:border-primary
-- transition-colors
-- ,
-        
-- Combobox
-- showCheck
-
-> 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`.*
-
----