forlogic-core 1.17.4 → 1.20.1

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

@@ -2,7 +2,17 @@
 
 ## 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.
+O alias da unidade ativa deve **sempre** estar presente na URL como primeiro segmento de rota (`/:alias/...`). A **URL é a fonte única de verdade** para o alias ativo.
+
+## Arquitetura (URL como Source of Truth)
+
+```
+Header/Seletor → navigate(/{novoAlias}/...) → URL muda → AliasRouteGuard → switchUnit()
+```
+
+- **Header/UI**: Apenas navega (muda a URL). Nunca chama `switchUnit` diretamente.
+- **AliasRouteGuard**: Detecta que `urlAlias !== activeAlias` e chama `switchUnit()` para sincronizar a sessão.
+- **Resultado**: Um único writer (guard) controla a sessão, eliminando race conditions.
 
 ## Componentes
 
@@ -12,26 +22,34 @@ 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:
+Wrapper de rota com **auto-detect de modo**:
 
-| Cenário | Ação |
+- **Modo URL** (`:alias` presente na rota): comportamento padrão com 1 effect de decisão
+- **Modo Legado** (sem `:alias` na rota): passthrough transparente, sem redirects
+
+| Cenário (Modo URL) | Ação |
 |---------|------|
 | Alias ausente na URL | Redireciona para `/{aliasAtivo}/{path}` |
-| Alias diferente do ativo (navegação URL) | Chama `switchUnit()` + loading |
-| Alias diferente do ativo (troca via seletor) | Atualiza URL (Effect 3), **não** chama `switchUnit()` |
+| Alias inválido | Redireciona para `/{aliasAtivo}/{path}` |
+| Alias válido e diferente do ativo | Chama `switchUnit()` |
 | Alias correto | Renderiza children |
-| Alias inválido | Redireciona para `/{aliasDefault}/{path}` |
-| Troca via seletor de unidades | Atualiza URL automaticamente |
 
-#### Distinção seletor vs. navegação via URL
+Proteção de concorrência: `switchingRef` evita chamadas duplicadas no mesmo ciclo.
+
+### `AppHeader` (mudança de unidade)
 
-O guard usa `prevActiveAliasRef` para distinguir a origem do mismatch:
+O header usa `navigate()` para trocar o segmento de alias na URL:
 
-- **`prevActiveAliasRef.current === null`** → primeiro carregamento (auth ainda inicializando). Effect 2 prossegue normalmente.
-- **`prevActiveAliasRef.current !== null` e `activeAlias !== prevRef`** → `activeAlias` acabou de mudar (troca via seletor). Effect 2 é **pulado** (Effect 3 sincroniza a URL).
-- **`prevActiveAliasRef.current !== null` e `activeAlias === prevRef`** → `activeAlias` não mudou, mismatch veio da URL. Effect 2 chama `switchUnit()`.
+```tsx
+const handleUnitChangeNavigate = (company) => {
+  const segments = pathname.split('/');
+  const aliasIndex = segments.indexOf(alias);
+  segments[aliasIndex] = company.alias;
+  navigate(segments.join('/') + search + hash);
+};
 
-O ref é atualizado **sempre** no Effect 3 (fora do condicional de navegação), garantindo que está sincronizado após qualquer mudança de `activeAlias`.
+<UserInfo onUnitChange={handleUnitChangeNavigate} />
+```
 
 ## Uso nos Consumidores
 
@@ -48,3 +66,4 @@ O ref é atualizado **sempre** no Effect 3 (fora do condicional de navegação),
 - 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`)
+- **Header/seletor NUNCA chama switchUnit diretamente** — apenas navega

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

@@ -7,19 +7,14 @@ export interface AliasRouteGuardProps {
 /**
  * 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
+ * A URL é a fonte única de verdade para o alias ativo.
+ * O header/seletor de unidade apenas navega para a nova URL;
+ * este guard detecta a mudança e chama switchUnit() para sincronizar a sessão.
  *
- * @example
- * ```tsx
- * <Route element={<AliasRouteGuard><Outlet /></AliasRouteGuard>}>
- *   <Route path="/:alias/documents" element={<DocumentsPage />} />
- *   <Route path="/:alias/documents/:id" element={<DocumentDetailPage />} />
- * </Route>
- * ```
+ * Fluxo determinístico (1 effect):
+ * - Alias ausente na URL → redirect para /{aliasAtivo}/...
+ * - Alias inválido → redirect para /{aliasAtivo}/...
+ * - Alias válido e diferente do ativo → switchUnit(matchedCompany)
+ * - Alias correto → renderiza children
  */
 export declare function AliasRouteGuard({ children, paramName }: AliasRouteGuardProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/layout/AppHeader.d.ts

@@ -1,61 +1,4 @@
 import React from 'react';
-/**
- * AppHeader Component
- *
- * Header principal da aplicação com:
- * - Título e subtítulo da página
- * - Busca global integrada ao CRUD
- * - Botão de refresh
- * - Informações do usuário e seleção de unidade
- *
- * @example
- * ```tsx
- * <AppHeader actions={<Button>Nova Ação</Button>} />
- * ```
- *
- * ## 🔍 Busca Global
- *
- * A busca é exibida automaticamente quando `isSearchVisible = true` no AuthContext.
- *
- * **Características:**
- * - ⏱️ Debounce de 500ms (configurável via SEARCH_CONFIG.debounceDelay)
- * - 🔗 Sincroniza com URL (?search=termo)
- * - ♻️ Reset automático para página 1 ao buscar
- * - 🎯 Integração automática com useCrud
- *
- * **Configurar campos pesquisáveis:**
- * ```typescript
- * // No service
- * createSimpleService({
- *   tableName: 'items',
- *   searchFields: ['name', 'description', 'code'], // 🔍 Campos de busca
- * });
- * ```
- *
- * **Customizar placeholder:**
- * ```tsx
- * // Opção 1: Modificar diretamente no AppHeader (linha ~102)
- * <Input placeholder="Buscar artigos..." />
- *
- * // Opção 2: Por rota (já implementado)
- * location.pathname === '/wiki' ? "Buscar artigos..." : "Buscar..."
- * ```
- *
- * **Controle programático:**
- * ```typescript
- * const [searchParams, setSearchParams] = useSearchParams();
- *
- * // Definir busca
- * const newParams = new URLSearchParams(searchParams);
- * newParams.set('search', 'termo');
- * newParams.set('page', '1');
- * setSearchParams(newParams);
- *
- * // Limpar busca
- * newParams.delete('search');
- * setSearchParams(newParams);
- * ```
- */
 interface AppHeaderProps {
     actions?: React.ReactNode;
 }

package/dist/components/layout/SidebarLogo.d.ts

@@ -0,0 +1,5 @@
+interface SidebarLogoProps {
+    appName?: string;
+}
+export declare function SidebarLogo({ appName }: SidebarLogoProps): import("react/jsx-runtime").JSX.Element;
+export {};