forlogic-core 1.16.11 → 1.17.0

package/.note/memory/features/crud-defaults-batteries-included.md

@@ -0,0 +1,14 @@
+# Memory: features/crud-defaults-batteries-included
+
+Todos os CRUDs (CrudTable, createCrudPage) agora incluem por padrão:
+- **Column resize** (`enableColumnResize=true`) — já era default
+- **Column manager** (`enableColumnManager=true`) — botão ⋮ no header da coluna "Ações"
+- **Sort** — já era suportado via `sortable` nas colunas
+- **Busca** — por padrão usa a busca global do header (não a action bar). Para busca na action bar, usar `showSearch=true`
+- **Storage keys** — `createCrudPage` gera automaticamente `columnManagerStorageKey` e `resizeStorageKey` a partir do `entityName`
+
+**NÃO vem por padrão:**
+- **Agrupamento** (`enableGrouping=false`) — precisa ser habilitado explicitamente com `enableGrouping={true}`
+- **Busca na action bar** (`showSearch=false`) — padrão é busca no header
+
+**Paginação:** padrão de 25 itens por página.

package/.note/memory/patterns/alias-url-resolution.md

@@ -0,0 +1,39 @@
+# Alias via URL — Resolução de Unidade por Rota
+
+## Padrão
+
+O alias da unidade ativa deve **sempre** estar presente na URL como primeiro segmento de rota (`/:alias/...`). O `AliasRouteGuard` garante sincronização bidirecional entre URL e sessão.
+
+## Componentes
+
+### `useAliasFromUrl(options?)`
+Hook que extrai o alias do param de rota e valida contra `companies` do `useAuth()`.
+
+Retorna: `{ urlAlias, isAliasMismatch, isValidAlias, isMissing, matchedCompany }`
+
+### `AliasRouteGuard`
+Wrapper de rota que sincroniza alias da URL com a sessão. Comportamento:
+
+| Cenário | Ação |
+|---------|------|
+| Alias ausente na URL | Redireciona para `/{aliasAtivo}/{path}` |
+| Alias diferente do ativo | Chama `switchUnit()` + loading |
+| Alias correto | Renderiza children |
+| Alias inválido | Redireciona para `/{aliasDefault}/{path}` |
+| Troca via seletor de unidades | Atualiza URL automaticamente |
+
+## Uso nos Consumidores
+
+```tsx
+<Route element={<ProtectedRoute><AliasRouteGuard><Outlet /></AliasRouteGuard></ProtectedRoute>}>
+  <Route path="/:alias/documents" element={<DocumentsPage />} />
+  <Route path="/:alias/documents/:id" element={<DocumentDetailPage />} />
+</Route>
+```
+
+## Regras
+- Guard só age após `isLoading=false && isAuthenticated=true`
+- Usa `replace: true` para evitar poluir o histórico
+- Se `switchUnit` falha, mantém alias atual (sem loop)
+- `switchUnit` já faz `queryClient.clear()` — cache é limpo automaticamente
+- Navegação inter-módulos já usa `{alias}` nas URLs (`modulesData.ts`)

package/.note/memory/patterns/doc-sync-rule.md

@@ -4,10 +4,13 @@
 
 Sempre que modificar qualquer arquivo em `lib/`, verificar se existe documentação correspondente em `src/design-system/docs/`.
 
+**Esta regra é obrigatória e deve ser aplicada em toda alteração de componente, sem exceção.**
+
 ## Ações obrigatórias
 
 ### 1. Componente/hook existente com doc existente
-- Atualizar props, exemplos e descrições no `*Doc.tsx` correspondente para refletir a mudança
+- Atualizar props, exemplos, hierarquias e descrições no `*Doc.tsx` correspondente para refletir a mudança
+- Atualizar previews interativos para que reflitam o comportamento atual do componente
 
 ### 2. Componente/hook novo sem doc
 - Criar `*Doc.tsx` usando `ComponentDocTemplate` (com prop `usage` obrigatória)

package/.note/memory/patterns/dynamic-supabase-config.md

@@ -0,0 +1,4 @@
+# Memory: patterns/dynamic-supabase-config
+Updated: 2026-03-24
+
+As credenciais do Supabase vêm exclusivamente do `.env` (auto-populado pelo Lovable ao trocar banco). O Vite injeta automaticamente variáveis `VITE_*` em `import.meta.env` — não há bloco `define` manual nem extração de `client.ts`. O `vite.config.ts` usa `loadEnv()` apenas para ler o project ID no contexto Node (CSP headers). O `SupabaseSingleton` lê `import.meta.env.VITE_SUPABASE_URL` e `VITE_SUPABASE_PUBLISHABLE_KEY` em runtime no browser.

package/.note/memory/patterns/environment-detection-logic.md

@@ -0,0 +1,35 @@
+# Memory: patterns/environment-detection-logic
+Updated: 2026-03-24
+
+O sistema separa duas preocupações independentes de ambiente:
+
+## 1. Método de autenticação (`shouldUseDevTokens()` / `isLovablePreview()`)
+Detecta se o app roda em contexto de desenvolvimento (preview Lovable via iframe, `*.lovable.dev`, localhost ou `import.meta.env.DEV`). Quando true, usa a edge function `dev-tokens` do Supabase conectado para autenticar. Quando false (app publicado), usa OAuth padrão do Qualiex.
+
+## 2. Qual API usar (`getEnvironmentConfig()` / `isDevSupabaseProject()`)
+Compara o project ID do Supabase conectado com `PROD_PROJECT_ID` (`ccjfvpnndclajkleyqkc`). Se igual → config PROD (API prod, OAuth prod). Se diferente → config DEV (API dev, OAuth dev).
+
+## Fonte de verdade do Project ID
+O project ID vem do `.env` (auto-populado pelo Lovable ao trocar banco), que o Vite injeta automaticamente em `import.meta.env.VITE_SUPABASE_PROJECT_ID`. **Não** é extraído de `src/integrations/supabase/client.ts`. O `vite.config.ts` usa `loadEnv()` apenas no contexto Node para configurar CSP headers.
+
+## Tabela de regras
+
+| Cenário                      | API  | Auth       |
+|------------------------------|------|------------|
+| Preview + Prod Supabase      | Prod | dev-tokens |
+| Preview + Dev Supabase       | Dev  | dev-tokens |
+| Publicado + Prod Supabase    | Prod | OAuth      |
+| Publicado + Dev Supabase     | Dev  | OAuth      |
+
+## Guard de troca de projeto (`TokenManager.checkProjectMismatch()`)
+Ao inicializar (`AuthService.initialize()`), o sistema compara `import.meta.env.VITE_SUPABASE_PROJECT_ID` com o valor armazenado em `localStorage('supabase_project_id')`. Se diferente, limpa todos os tokens stale automaticamente antes de qualquer chamada a `validate-token`, evitando 401 desnecessários. Após a limpeza, armazena o novo project ID. Isso garante transição limpa ao trocar de banco Supabase sem erros ou blank screen.
+
+## Funções (lib/config/index.ts)
+- `isLovablePreview()` — detecta contexto de preview/localhost
+- `shouldUseDevTokens()` — wrapper semântico sobre `isLovablePreview()`
+- `isDevEnvironment` — alias deprecated, mantido para compatibilidade
+- `getEnvironmentConfig()` — retorna config PROD ou DEV baseado no project ID
+- `isDevSupabaseProject()` — true se project ID ≠ PROD_PROJECT_ID
+
+## Funções (lib/auth/services/TokenManager.ts)
+- `checkProjectMismatch()` — detecta troca de projeto Supabase e limpa tokens stale

package/dist/auth/components/AliasRouteGuard.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+export interface AliasRouteGuardProps {
+    children: React.ReactNode;
+    /** Nome do param de rota (default: "alias") */
+    paramName?: string;
+}
+/**
+ * Guard de rota que sincroniza o alias da URL com a sessão de autenticação.
+ *
+ * Comportamento:
+ * - **Alias ausente na URL** → Redireciona para `/{aliasAtivo}/{restoDoPath}` (replace)
+ * - **Alias presente mas diferente do ativo** → Chama `switchUnit()` + loading
+ * - **Alias presente e correto** → Renderiza children
+ * - **Alias inválido (não existe em companies)** → Redireciona para `/{aliasDefault}/{restoDoPath}`
+ * - **Troca via seletor de unidades** → Atualiza URL automaticamente
+ *
+ * @example
+ * ```tsx
+ * <Route element={<AliasRouteGuard><Outlet /></AliasRouteGuard>}>
+ *   <Route path="/:alias/documents" element={<DocumentsPage />} />
+ *   <Route path="/:alias/documents/:id" element={<DocumentDetailPage />} />
+ * </Route>
+ * ```
+ */
+export declare function AliasRouteGuard({ children, paramName }: AliasRouteGuardProps): import("react/jsx-runtime").JSX.Element;

package/dist/auth/services/AuthService.d.ts

@@ -20,7 +20,7 @@ export declare class AuthService {
     /**
      * Logout do usuário
      */
-    static logout(): void;
+    static logout(): Promise<void>;
     /**
      * Decodifica um token JWT usando TokenService robusto
      */

package/dist/auth/services/TokenManager.d.ts

@@ -16,6 +16,12 @@ export declare const TokenManager: {
     generateOAuthState: () => string;
     generateOAuthNonce: () => string;
     hasAllTokens: () => boolean;
+    /**
+     * Detecta troca de projeto Supabase e limpa tokens stale automaticamente.
+     * Deve ser chamado ANTES de qualquer validação de token.
+     * Retorna true se houve troca (tokens foram limpos).
+     */
+    checkProjectMismatch: () => boolean;
     setSupabaseToken: (token: string) => void;
     areAllTokensValid: () => boolean;
     clearExpiredTokens: () => boolean;

package/dist/config/index.d.ts

@@ -19,6 +19,14 @@ export declare const CRUD_CONFIG: {
 export declare const SEARCH_CONFIG: {
     readonly debounceDelay: 500;
 };
+export declare const isLovablePreview: () => boolean;
+/**
+ * Determines auth method: true → use dev-tokens edge function, false → use OAuth.
+ * This is independent of which API environment (prod/dev) is used — that's decided
+ * by getEnvironmentConfig() based on the Supabase project ID.
+ */
+export declare const shouldUseDevTokens: () => boolean;
+/** @deprecated Use `isLovablePreview()` or `shouldUseDevTokens()` instead */
 export declare const isDevEnvironment: () => boolean;
 export { isDevSupabaseProject } from './environments';
 export declare const getQualiexApiUrl: () => string;

package/dist/crud/components/ColumnSettingsPopover.d.ts

@@ -5,6 +5,7 @@ export interface ColumnSettingsPopoverProps<T> {
     isColumnHidden: (key: string) => boolean;
     toggleColumn: (key: string) => void;
     showAllColumns: () => void;
+    resetColumns?: () => void;
     reorderColumns: (fromIndex: number, toIndex: number) => void;
     /** @deprecated Use groupByColumns + addGroupByColumn + removeGroupByColumn */
     groupByColumn?: string | null;
@@ -14,4 +15,4 @@ export interface ColumnSettingsPopoverProps<T> {
     addGroupByColumn?: (key: string) => void;
     removeGroupByColumn?: (key: string) => void;
 }
-export declare function ColumnSettingsPopover<T extends BaseEntity>({ columns, columnOrder, isColumnHidden, toggleColumn, showAllColumns, reorderColumns, groupByColumn, setGroupByColumn, groupByColumns, addGroupByColumn, removeGroupByColumn, }: ColumnSettingsPopoverProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function ColumnSettingsPopover<T extends BaseEntity>({ columns, columnOrder, isColumnHidden, toggleColumn, showAllColumns, reorderColumns, groupByColumn, setGroupByColumn, groupByColumns, addGroupByColumn, removeGroupByColumn, resetColumns, }: ColumnSettingsPopoverProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/crud/components/CrudTable.d.ts

@@ -40,6 +40,8 @@ export interface CrudTableProps<T extends BaseEntity & {
     resizeStorageKey?: string;
     enableColumnManager?: boolean;
     columnManagerStorageKey?: string;
+    /** Habilita agrupamento de colunas (GroupDropZone + opções de grupo no ColumnSettings). Default: false */
+    enableGrouping?: boolean;
 }
-export declare const CrudTable: <T extends BaseEntity>({ manager, columns, onEdit, onView, onToggleStatus, onDelete, renderActions, customRowActions, enableBulkActions, rowActionsVariant, onNew, newButtonLabel, showNewButton, customActions, hideActionBar, showActionBar, showSearch, searchValue, onSearchChange, searchPlaceholder, bulkActions, onBulkDelete, filters, viewMode, onViewModeChange, showViewToggle, enableColumnResize, resizeStorageKey, enableColumnManager, columnManagerStorageKey, }: CrudTableProps<T>) => import("react/jsx-runtime").JSX.Element;
+export declare const CrudTable: <T extends BaseEntity>({ manager, columns, onEdit, onView, onToggleStatus, onDelete, renderActions, customRowActions, enableBulkActions, rowActionsVariant, onNew, newButtonLabel, showNewButton, customActions, hideActionBar, showActionBar, showSearch, searchValue, onSearchChange, searchPlaceholder, bulkActions, onBulkDelete, filters, viewMode, onViewModeChange, showViewToggle, enableColumnResize, resizeStorageKey, enableColumnManager, columnManagerStorageKey, enableGrouping, }: CrudTableProps<T>) => import("react/jsx-runtime").JSX.Element;
 export default CrudTable;

package/dist/crud/hooks/useColumnManager.d.ts

@@ -20,6 +20,8 @@ export interface UseColumnManagerReturn<T> {
     toggleColumn: (key: string) => void;
     /** Show all columns */
     showAllColumns: () => void;
+    /** Reset columns to default order and visibility */
+    resetColumns: () => void;
     /** Current column order (keys) */
     columnOrder: string[];
     /** Reorder columns */

package/dist/hooks/useAliasFromUrl.d.ts

@@ -0,0 +1,33 @@
+export interface UseAliasFromUrlOptions {
+    /** Nome do param de rota (default: "alias") */
+    paramName?: string;
+}
+export interface UseAliasFromUrlReturn {
+    /** Alias extraído da URL (ou null se ausente) */
+    urlAlias: string | null;
+    /** true se há alias na URL e é diferente do alias ativo */
+    isAliasMismatch: boolean;
+    /** true se o alias da URL existe nas companies do usuário */
+    isValidAlias: boolean;
+    /** true se não há alias na URL */
+    isMissing: boolean;
+    /** Company correspondente ao alias da URL (ou null) */
+    matchedCompany: {
+        id: string;
+        alias: string;
+        name: string;
+    } | null;
+}
+/**
+ * Hook para extrair e validar o alias da URL contra as companies do usuário.
+ *
+ * Lê o param `:alias` do React Router e verifica se é um alias válido
+ * (presente na lista de companies do token de autenticação).
+ *
+ * @example
+ * ```tsx
+ * // Rota: /:alias/documents
+ * const { urlAlias, isAliasMismatch, isValidAlias, isMissing } = useAliasFromUrl();
+ * ```
+ */
+export declare function useAliasFromUrl(options?: UseAliasFromUrlOptions): UseAliasFromUrlReturn;

package/dist/hooks/useSidebarResize.d.ts

@@ -9,7 +9,7 @@ interface UseSidebarResizeProps {
 }
 export declare function useSidebarResize({ direction, minWidth, // 14rem
 maxWidth, // 24rem
-defaultWidth, // 15rem
+defaultWidth, // ~17.5rem
 storageKey, onResize, isOpen }?: UseSidebarResizeProps): {
     width: number;
     isDragging: boolean;