forlogic-core 2.1.5 → 2.2.1

package/dist/integrations/clarity/clarityTracking.d.ts

@@ -0,0 +1,31 @@
+import type { Module } from '../../components/modules/types';
+interface ModuleClickContext {
+    module: Module;
+    isContracted: boolean;
+    sourceModule?: string;
+    alias?: string;
+}
+/**
+ * Função utilitária `trackModuleClick`.
+ * @example
+ * trackModuleClick();
+ */
+export declare function trackModuleClick({ module, isContracted, sourceModule, alias }: ModuleClickContext): void;
+/**
+ * Função utilitária `trackInterestClick`.
+ * @example
+ * trackInterestClick();
+ */
+export declare function trackInterestClick({ module, sourceModule, alias }: Omit<ModuleClickContext, 'isContracted'>): void;
+interface FooterClickContext {
+    resource: 'educa' | 'saber-gestao' | 'wiki';
+    sourceModule?: string;
+    alias?: string;
+}
+/**
+ * Função utilitária `trackFooterClick`.
+ * @example
+ * trackFooterClick();
+ */
+export declare function trackFooterClick({ resource, sourceModule, alias }: FooterClickContext): void;
+export {};

package/dist/integrations/clarity/index.d.ts

@@ -0,0 +1,3 @@
+export { useClarity } from './useClarity';
+export { trackModuleClick, trackInterestClick, trackFooterClick } from './clarityTracking';
+export type { ClarityMode, ClarityRuntimeMode, ModuleClickEventTags, FooterClickEventTags } from './types';

package/dist/integrations/clarity/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Modos de operação do Clarity na forlogic-core.
+ * - `auto` (padrão): inicializa o Clarity Forlogic se nenhum outro estiver presente; caso contrário, "pega carona" no existente, prefixando eventos com `forlogic_*`.
+ * - `disabled`: nunca inicializa nem dispara eventos.
+ *
+ * @example
+ * const value: ClarityMode = {} as ClarityMode;
+ */
+export type ClarityMode = 'auto' | 'disabled';
+/** Estado interno de operação após detecção/inicialização *
+ * @example
+ * const value: ClarityRuntimeMode = {} as ClarityRuntimeMode;
+ */
+export type ClarityRuntimeMode = 'owned' | 'piggyback' | 'inactive';
+/**
+ * Tipo `ModuleClickEventTags` exportado pela lib.
+ * @example
+ * const value: ModuleClickEventTags = {} as ModuleClickEventTags;
+ */
+export interface ModuleClickEventTags {
+    clicked_module: string;
+    clicked_module_id?: string;
+    is_contracted: string;
+    source_module?: string;
+    alias?: string;
+}
+/**
+ * Tipo `FooterClickEventTags` exportado pela lib.
+ * @example
+ * const value: FooterClickEventTags = {} as FooterClickEventTags;
+ */
+export interface FooterClickEventTags {
+    footer_resource: 'educa' | 'saber-gestao' | 'wiki';
+    source_module?: string;
+    alias?: string;
+}
+declare global {
+    interface Window {
+        /** Função global instanciada pelo snippet do Clarity (qualquer projeto) */
+        clarity?: ((...args: unknown[]) => void) & Record<string, unknown>;
+        /** Sinaliza que a forlogic-core foi quem inicializou o Clarity */
+        __forlogicClarityOwned?: boolean;
+        /** Modo de operação detectado pela forlogic-core */
+        __forlogicClarityMode?: ClarityRuntimeMode;
+    }
+}

package/dist/integrations/clarity/useClarity.d.ts

@@ -0,0 +1,34 @@
+import type { ClarityMode } from './types';
+interface UseClarityOptions {
+    projectId?: string;
+    mode?: ClarityMode;
+}
+/**
+ * Hook que inicializa o Microsoft Clarity de forma idempotente e identifica o usuário autenticado.
+ *
+ * Comportamento:
+ * - Se `mode === 'disabled'`, não faz nada.
+ * - Em preview/local (shouldUseDevTokens), desabilitado.
+ * - Se já existir uma instância Clarity de outro projeto consumidor, entra em modo `piggyback`
+ *   (não reinicializa, mas eventos disparados pela lib serão prefixados com `forlogic_*`).
+ * - Caso contrário, inicializa com o `projectId` informado (modo `owned`).
+ *
+ * Chame **uma única vez** no topo da árvore (App.tsx ou layout raiz) — internamente
+ * sincroniza com o `AuthContext` e re-identifica o usuário em cada login.
+ *
+ * @example
+ * // App.tsx — habilitado apenas em produção
+ * function App() {
+ *   useClarity({
+ *     projectId: import.meta.env.VITE_CLARITY_PROJECT_ID,
+ *     mode: import.meta.env.PROD ? 'auto' : 'disabled',
+ *   });
+ *   return <CoreProviders>...</CoreProviders>;
+ * }
+ *
+ * @example
+ * // Desabilitar explicitamente (ex: ambiente sandbox de cliente)
+ * useClarity({ mode: 'disabled' });
+ */
+export declare function useClarity({ projectId, mode }: UseClarityOptions): void;
+export {};

package/dist/integrations/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @module integrations
+ * Integrações externas opcionais. Ver `./README.md`.
+ */
+export * from './clarity';

package/dist/providers/CoreProviders.d.ts

@@ -1,6 +1,7 @@
 import { ReactNode } from 'react';
 import { QueryClient } from '@tanstack/react-query';
 import { ModuleAccessGuardProps } from '../components/modules';
+import type { ClarityMode } from '../integrations/clarity/types';
 /**
  * Mapa de traduções por idioma para o namespace 'app' do projeto consumidor.
  *
@@ -54,6 +55,20 @@ export interface CoreProvidersProps {
      * ```
      */
     appTranslations?: AppTranslationsMap;
+    /**
+     * Project ID do Microsoft Clarity para instrumentação centralizada do menu de módulos.
+     * Quando informado, a lib inicializa o Clarity (modo `owned`) ou, se já existir uma
+     * instância no consumidor, entra em modo `piggyback` (eventos com prefixo `forlogic_*`).
+     *
+     * @example "wcqt61e4em"
+     */
+    clarityProjectId?: string;
+    /**
+     * Modo de operação do Clarity.
+     * - `auto` (padrão): comportamento descrito em `clarityProjectId`.
+     * - `disabled`: nunca inicializa nem dispara eventos.
+     */
+    clarityMode?: ClarityMode;
 }
 /**
  * CoreProviders - Encapsulates all essential providers for forlogic-core applications
@@ -76,4 +91,4 @@ export interface CoreProvidersProps {
  * }
  * ```
  */
-export declare function CoreProviders({ children, queryClient, moduleAlias, moduleAccessGuardProps, appTranslations }: CoreProvidersProps): import("react/jsx-runtime").JSX.Element;
+export declare function CoreProviders({ children, queryClient, moduleAlias, moduleAccessGuardProps, appTranslations, clarityProjectId, clarityMode, }: CoreProvidersProps): import("react/jsx-runtime").JSX.Element;

package/dist/qualiex/components/QualiexUserField.d.ts

@@ -2,6 +2,9 @@ import React from 'react';
 import { QualiexUser } from '../../types';
 /**
  * Formato de exibição do usuário no campo
+ *
+ * @example
+ * const value: QualiexUserDisplayFormat = {} as QualiexUserDisplayFormat;
  */
 export type QualiexUserDisplayFormat = 'name' | 'name-email' | 'name-role' | 'custom';
 /**
@@ -121,5 +124,10 @@ interface QualiexUserFieldProps {
     /** Callback ao fechar o popover */
     onClose?: () => void;
 }
+/**
+ * Componente `QualiexUserField` da lib.
+ * @example
+ * <QualiexUserField />
+ */
 export declare const QualiexUserField: React.FC<QualiexUserFieldProps>;
 export {};

package/dist/qualiex/hooks/useQualiexUsers.d.ts

@@ -8,44 +8,34 @@ interface UseQualiexUsersOptions {
      * - `true`: Busca imediata e automática (padrão)
      * - `false`: Não busca (use com `refetch()` para lazy loading)
      * - Condicional: `enabled: isModalOpen` (busca só quando aberto)
-     *
-     * @example
-     * // ✅ Uso padrão (busca automática)
-     * useQualiexUsers()
-     *
-     * @example
-     * // ✅ Modal condicional
-     * useQualiexUsers({ enabled: isModalOpen })
-     *
-     * @example
-     * // ✅ Lazy loading
-     * const { refetch } = useQualiexUsers({ enabled: false });
-     * await refetch(); // Chama quando necessário
      */
     enabled?: boolean;
+    /**
+     * Filtro de status:
+     * - `'active'` (default): Retorna apenas usuários ativos. Use para selectors/comboboxes.
+     * - `'all'`: Retorna ativos + inativos. Use para enrichment de IDs históricos.
+     *
+     * Cada status tem cache independente (queryKey separado).
+     */
+    status?: 'active' | 'all';
 }
 /**
  * Hook para buscar usuários da API Qualiex.
  *
- * Por padrão, a query executa automaticamente quando o hook é montado.
- *
- * @param options - Opções de configuração
- * @param options.enabled - Controla se a query executa (padrão: `true`)
- *
- * @returns Objeto com dados, loading, error e refetch
+ * Por padrão, a query executa automaticamente quando o hook é montado e retorna
+ * apenas usuários **ativos**. Para enrichment de registros históricos, use `status: 'all'`.
  *
  * @example
- * // ✅ Uso padrão - Busca automática
- * const { data: users, isLoading } = useQualiexUsers();
+ * // ✅ Selector — só ativos (padrão)
+ * const { data: users } = useQualiexUsers();
  *
  * @example
- * // ✅ Busca condicional (modal)
- * const { data: users } = useQualiexUsers({ enabled: isModalOpen });
+ * // ✅ Enrichment — inclui inativos
+ * const { data: users } = useQualiexUsers({ status: 'all' });
  *
  * @example
- * // ✅ Lazy loading com controle manual
- * const { data: users, refetch } = useQualiexUsers({ enabled: false });
- * await refetch(); // Chamar quando necessário
+ * // ✅ Modal condicional
+ * const { data: users } = useQualiexUsers({ enabled: isModalOpen });
  */
 export declare const useQualiexUsers: (options?: UseQualiexUsersOptions) => import("@tanstack/react-query").UseQueryResult<QualiexUser[], Error>;
 export {};

package/dist/qualiex/services/qualiexApi.d.ts

@@ -13,10 +13,21 @@ declare class QualiexApiService {
      * Retorna null se o formato for inválido.
      */
     private parseUsersResponse;
-    fetchUsers(alias: string, companyId: string): Promise<QualiexUser[]>;
+    /**
+     * Busca usuários do Qualiex.
+     *
+     * @param status - `'active'` (default) retorna apenas usuários ativos.
+     *                 `'all'` retorna ativos e inativos — use para enrichment de IDs históricos.
+     */
+    fetchUsers(alias: string, companyId: string, status?: 'active' | 'all'): Promise<QualiexUser[]>;
     fetchUserById(userId: string, alias: string, companyId: string): Promise<QualiexUser | null>;
     fetchActiveUsersMap(alias: string, companyId: string): Promise<Map<string, QualiexUser>>;
-    getUsers(alias: string): Promise<QualiexUser[]>;
+    /**
+     * Mesma estrutura de `fetchActiveUsersMap`, mas inclui também usuários inativos.
+     * Usado pelo enrichment para resolver IDs históricos.
+     */
+    fetchAllUsersMap(alias: string, companyId: string): Promise<Map<string, QualiexUser>>;
+    getUsers(alias: string, status?: 'active' | 'all'): Promise<QualiexUser[]>;
     /**
      * Busca a lista de todos os módulos/softwares disponíveis na plataforma.
      * GET /api/common/v1/softwares
@@ -35,5 +46,30 @@ declare class QualiexApiService {
      */
     fetchUserAssociations(userId: string, alias: string): Promise<UserAssociation[]>;
 }
+/**
+ * Singleton do serviço Qualiex (API common-v4) — usuários, grupos e unidades organizacionais.
+ *
+ * Resolve `un-alias` automaticamente do token corrente (TokenManager). Para componentes React,
+ * prefira o hook `useQualiexUsers`, que adiciona cache via React Query.
+ *
+ * @example
+ * // Buscar usuários por nome/email/login
+ * const users = await qualiexApi.searchUsers('joao.silva', alias);
+ * // → QualiexUser[] com { userName, name, email, ... }
+ *
+ * @example
+ * // Resolver lote de userNames (ex: enriquecimento de tabela)
+ * const usernames = ['ana.lima', 'bruno.costa'];
+ * const enriched = await qualiexApi.getUsersByUserNames(usernames, alias);
+ *
+ * @example
+ * // Listar softwares contratados pela unidade (Module Access)
+ * const softwares = await qualiexApi.getContractedSoftwares(alias);
+ *
+ * @example
+ * // Em componentes React, prefira o hook
+ * import { useQualiexUsers } from 'forlogic-core';
+ * const { data: users, isLoading } = useQualiexUsers({ search, alias });
+ */
 export declare const qualiexApi: QualiexApiService;
 export {};

package/dist/qualiex/utils/QualiexErrorInterceptor.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Componente `QualiexErrorInterceptor` da lib.
+ * @example
+ * <QualiexErrorInterceptor />
+ */
 export declare class QualiexErrorInterceptor {
     private static isRetrying;
     /**

package/dist/supabase/SupabaseSingleton.d.ts

@@ -1,3 +1,37 @@
 import { SupabaseClient } from '@supabase/supabase-js';
 import type { Database } from './types';
+/**
+ * Retorna a instância singleton do client Supabase já configurada (URL, anon key e schema padrão).
+ *
+ * **Sempre** use esta função — nunca invoque `createClient` manualmente. Toda query exige
+ * `.schema('<schema>')` explícito (multi-tenant). Ver `mem://patterns/supabase-client-guards`.
+ *
+ * @example
+ * // Query em schema específico (obrigatório)
+ * const supabase = getSupabaseClient();
+ * const { data, error } = await supabase
+ *   .schema('central')
+ *   .from('action_plans')
+ *   .select('id, title, status')
+ *   .eq('alias', currentAlias)
+ *   .is('deleted_at', null)
+ *   .order('created_at', { ascending: false });
+ *
+ * @example
+ * // Insert com retorno
+ * const { data } = await supabase
+ *   .schema('central')
+ *   .from('matrices')
+ *   .insert({ alias, title: 'Nova Matriz', id_user: userId })
+ *   .select()
+ *   .single();
+ *
+ * @example
+ * // Soft delete (nunca DELETE físico)
+ * await supabase
+ *   .schema('central')
+ *   .from('requirements')
+ *   .update({ deleted_at: new Date().toISOString() })
+ *   .eq('id', requirementId);
+ */
 export declare function getSupabaseClient(): SupabaseClient<Database>;

package/dist/types.d.ts

@@ -4,8 +4,25 @@ export type ViewMode = 'table';
 export type SortDirection = 'asc' | 'desc';
 export type ActionType = 'create' | 'update' | 'delete' | 'fetch' | 'export';
 /**
- * BaseEntity - Interface mínima para todas as entidades
- * Contém apenas campos essenciais presentes em todas as tabelas
+ * Interface mínima que **toda** entidade da plataforma deve estender.
+ *
+ * Reflete os campos obrigatórios de qualquer tabela multi-tenant: `id`, `alias` (tenant),
+ * timestamps e flags de soft delete (`is_removed`) e ativação (`is_actived`).
+ *
+ * @example
+ * // Estendendo para uma entidade de domínio
+ * interface ActionPlan extends BaseEntity {
+ *   title: string;
+ *   description: string | null;
+ *   status: 'pending' | 'in_progress' | 'completed';
+ *   id_user: string;
+ * }
+ *
+ * @example
+ * // Uso genérico em hooks/serviços CRUD
+ * function useEntities<T extends BaseEntity>(table: string) {
+ *   return useQuery<T[]>(['entities', table], () => fetchAll(table));
+ * }
  */
 export interface BaseEntity {
     id: string;
@@ -69,6 +86,36 @@ export interface CrudManager<T extends BaseEntity> {
 }
 export interface CrudEntity extends BaseEntity {
 }
+/**
+ * Definição de coluna usada por {@link CrudTable} e `createCrudPage`.
+ *
+ * Suporta tipagem semântica (`type`), ordenação (default `true`), filtros, busca textual,
+ * renderização customizada e larguras controladas.
+ *
+ * @example
+ * const columns: CrudColumn<ActionPlan>[] = [
+ *   { key: 'title', header: 'Título', type: 'text', searchable: true, weight: 3 },
+ *   {
+ *     key: 'status',
+ *     header: 'Status',
+ *     type: 'select',
+ *     options: [
+ *       { label: 'Pendente', value: 'pending' },
+ *       { label: 'Concluído', value: 'completed' },
+ *     ],
+ *     filterable: true,
+ *     render: (row) => <StatusBadge status={row.status} />,
+ *   },
+ *   {
+ *     key: 'created_at',
+ *     header: 'Criado em',
+ *     type: 'date',
+ *     sortable: true,
+ *     render: (row) => formatDatetime(row.created_at),
+ *   },
+ *   { key: 'id_user', header: 'Responsável', minWidth: 180 },
+ * ];
+ */
 export interface CrudColumn<T = any> {
     key: keyof T;
     header: string;
@@ -460,6 +507,8 @@ export interface QualiexUser {
     roleName?: string;
     companyId?: string;
     companyName?: string;
+    /** Indica se o usuário está ativo no Qualiex. Default `true` quando ausente. */
+    isActive?: boolean;
 }
 export interface QualiexUserFieldMapping {
     /** Nome do campo de ID de usuário na entidade (ex: "target_user_id") */

package/dist/vite/index.esm.js

@@ -103,7 +103,10 @@ function generateCSPPolicy(isDev, options = {}) {
 
 const DEFAULT_TRUSTED_ORIGINS = [
   "https://lovableproject.com",
-  "https://lovable.dev"
+  "https://*.lovableproject.com",
+  "https://lovable.dev",
+  "https://*.lovable.dev",
+  "https://*.lovable.app"
 ];
 const DEV_TRUSTED_ORIGINS = [
   "http://localhost:8080",

package/dist/vite/index.js

@@ -105,7 +105,10 @@ function generateCSPPolicy(isDev, options = {}) {
 
 const DEFAULT_TRUSTED_ORIGINS = [
   "https://lovableproject.com",
-  "https://lovable.dev"
+  "https://*.lovableproject.com",
+  "https://lovable.dev",
+  "https://*.lovable.dev",
+  "https://*.lovable.app"
 ];
 const DEV_TRUSTED_ORIGINS = [
   "http://localhost:8080",