forlogic-core 3.0.0 → 3.0.2

package/.note/memory/security/react-router-dom-v7-migration.md

@@ -1,33 +1,33 @@
----
-name: react-router-dom v7 migration + peer dependency
-description: forlogic-core 2.5.0 bumpou react-router-dom 6→7 e moveu pra peerDependencies — consumidores precisam alinhar a própria versão antes de atualizar
-type: feature
----
-
-## O que mudou (forlogic-core 2.5.0)
-
-- `react-router-dom`: `6.30.1` → `7.18.1`.
-- Saiu de `dependencies` e virou `peerDependencies` — o app consumidor agora é responsável por instalar a versão compatível.
-
-## Por que isso quebra apps que não atualizarem
-
-`react-router-dom` era dependência normal mas já tratada como externa no build (`rollup.config.js#externalDeps`) — ou seja, o app sempre precisou fornecer a própria instância em runtime. O problema: sem ser peer, o npm não avisava sobre incompatibilidade de versão, só instalava as duas cópias silenciosamente. Um app ainda em v6 + lib pedindo v7 = duas instâncias de React Router no bundle = contexto de `<Router>` não bate entre os hooks da lib (`useNavigate`, `useLocation`, etc. usados em `lib/components/layout/*`, `lib/crud/*`, `lib/auth/*`) e o `<BrowserRouter>` do app.
-
-## Checklist pra IA/dev atualizando um app consumidor
-
-1. Checar `package.json` do app: `react-router-dom` precisa ser `^7.18.1` (ou compatível) **antes** de subir `forlogic-core` pra `>=2.5.0`.
-2. Se o app usa só API declarativa (`Routes`, `Route`, `Link`, `Navigate`, `Outlet`, `useNavigate`, `useLocation`, `useParams`, `useSearchParams`, `BrowserRouter`) — migração 6→7 tende a ser troca de versão sem mudança de código.
-3. Se o app usa **data router** (`createBrowserRouter`, loaders, actions, `<Form>`) — revisar changelog oficial do react-router v7, há mudanças de API nesse modo que a lib não usa e portanto não foi validado aqui.
-4. Rodar `npm ls react-router-dom` no app depois do install — se aparecer mais de uma versão resolvida (não deduped), o conflito não foi resolvido.
-
-## Risco aceito relacionado: GHSA-qwww-vcr4-c8h2 (high) — RESOLVIDO na 3.0.0
-
-react-router (core, 7.12.0–8.2.0) tem CVE alto de CSRF bypass em "RSC Mode". Fix é `react-router@8.3.0`, mas na época:
-- `react-router-dom` (pacote usado aqui) não tem release 8.x.
-- `react-router@8.3.0` exige React `>=19.2.7` — ver [[react19-migration-roadmap]].
-
-Foi aceito como risco porque não exploitável no padrão de uso desta lib (sem RSC, sem actions/loaders, sem SSR — só roteamento client-side declarativo).
-
-**Corrigido em 2026-08-01 (`forlogic-core@3.0.0`):** migração pra React 19 + `react-router@8.3.0` executada. `npm audit` = 0 vulnerabilidades. Detalhes e checklist pro app consumidor em [[react19-migration-roadmap]].
-
-> **Este documento descreve a 2.5.0 e está superado a partir da 3.0.0.** O pacote `react-router-dom` não existe mais no v8 — quem for atualizar direto de `<2.5.0` pra `^3.0.0` deve seguir o checklist do [[react19-migration-roadmap]], não o daqui.
+---
+name: react-router-dom v7 migration + peer dependency
+description: forlogic-core 2.5.0 bumpou react-router-dom 6→7 e moveu pra peerDependencies — consumidores precisam alinhar a própria versão antes de atualizar
+type: feature
+---
+
+## O que mudou (forlogic-core 2.5.0)
+
+- `react-router-dom`: `6.30.1` → `7.18.1`.
+- Saiu de `dependencies` e virou `peerDependencies` — o app consumidor agora é responsável por instalar a versão compatível.
+
+## Por que isso quebra apps que não atualizarem
+
+`react-router-dom` era dependência normal mas já tratada como externa no build (`rollup.config.js#externalDeps`) — ou seja, o app sempre precisou fornecer a própria instância em runtime. O problema: sem ser peer, o npm não avisava sobre incompatibilidade de versão, só instalava as duas cópias silenciosamente. Um app ainda em v6 + lib pedindo v7 = duas instâncias de React Router no bundle = contexto de `<Router>` não bate entre os hooks da lib (`useNavigate`, `useLocation`, etc. usados em `lib/components/layout/*`, `lib/crud/*`, `lib/auth/*`) e o `<BrowserRouter>` do app.
+
+## Checklist pra IA/dev atualizando um app consumidor
+
+1. Checar `package.json` do app: `react-router-dom` precisa ser `^7.18.1` (ou compatível) **antes** de subir `forlogic-core` pra `>=2.5.0`.
+2. Se o app usa só API declarativa (`Routes`, `Route`, `Link`, `Navigate`, `Outlet`, `useNavigate`, `useLocation`, `useParams`, `useSearchParams`, `BrowserRouter`) — migração 6→7 tende a ser troca de versão sem mudança de código.
+3. Se o app usa **data router** (`createBrowserRouter`, loaders, actions, `<Form>`) — revisar changelog oficial do react-router v7, há mudanças de API nesse modo que a lib não usa e portanto não foi validado aqui.
+4. Rodar `npm ls react-router-dom` no app depois do install — se aparecer mais de uma versão resolvida (não deduped), o conflito não foi resolvido.
+
+## Risco aceito relacionado: GHSA-qwww-vcr4-c8h2 (high) — RESOLVIDO na 3.0.0
+
+react-router (core, 7.12.0–8.2.0) tem CVE alto de CSRF bypass em "RSC Mode". Fix é `react-router@8.3.0`, mas na época:
+- `react-router-dom` (pacote usado aqui) não tem release 8.x.
+- `react-router@8.3.0` exige React `>=19.2.7` — ver [[react19-migration-roadmap]].
+
+Foi aceito como risco porque não exploitável no padrão de uso desta lib (sem RSC, sem actions/loaders, sem SSR — só roteamento client-side declarativo).
+
+**Corrigido em 2026-08-01 (`forlogic-core@3.0.0`):** migração pra React 19 + `react-router@8.3.0` executada. `npm audit` = 0 vulnerabilidades. Detalhes e checklist pro app consumidor em [[react19-migration-roadmap]].
+
+> **Este documento descreve a 2.5.0 e está superado a partir da 3.0.0.** O pacote `react-router-dom` não existe mais no v8 — quem for atualizar direto de `<2.5.0` pra `^3.0.0` deve seguir o checklist do [[react19-migration-roadmap]], não o daqui.

package/.note/memory/security/react19-migration-roadmap.md

@@ -1,66 +1,66 @@
----
-name: React 19 migration roadmap
-description: Migração do forlogic-core para React 19 + react-router v8 — CONCLUÍDA na 3.0.0 (2026-08-01); consumidores precisam estar em React 19 antes de atualizar
-type: feature
----
-
-**Status: concluída na `forlogic-core@3.0.0` (2026-08-01).** Levantada em 2026-07-24 a partir de
-[[react-router-dom-v7-migration]], quando a decisão foi manter React 18 e aceitar o risco do
-CVE GHSA-qwww-vcr4-c8h2. Executada agora porque `react-router@8.3.0` (fix do CVE) exige
-peer `react >=19.2.7`.
-
-## O que foi feito
-
-Os 6 passos do escopo original, todos aplicados:
-
-1. **`react`/`react-dom` movidos de `dependencies` → `peerDependencies` (`^19.2.7`)** — mesmo
-   problema de duplicação silenciosa que motivou mover `react-router-dom` na 2.5.0. Ficaram
-   também em `devDependencies` (`^19.2.8`) para o build e o vite dev do próprio app.
-2. **`next-themes` `^0.3.0` → `^0.4.6`** — era o bloqueio conhecido; a 0.4.6 aceita
-   `react ^19`.
-3. **`react-router-dom` → `react-router`** em 33 imports / 31 arquivos (`lib/` + `src/`),
-   mais o externo em `rollup.config.js#externalDeps` e os snippets em
-   `docs/design-system/examples.md` e `docs/design-system/patterns/core-providers.md`.
-4. **`react`/`react-dom` `^19.2.8`, `@types/react` `^19.2.18`, `@types/react-dom` `^19.2.4`.**
-5. Build e typecheck validados (ver abaixo). **Validação visual do `/ds` continua pendente
-   para quem for publicar** — mudanças de comportamento de render do React 19 não aparecem
-   em erro de compilação.
-6. Coordenação com Forlogic/Qualiex — **pendente do lado dos apps**, ver checklist abaixo.
-
-## Achados da execução
-
-- **O levantamento de 2026-07-24 estava certo:** o código já estava limpo pra React 19.
-  Único ajuste necessário no repo inteiro foi `lib/hooks/useDebounce.ts:60` —
-  `useRef<NodeJS.Timeout>()` → `useRef<NodeJS.Timeout | undefined>(undefined)`, porque os
-  types do React 19 passaram a exigir argumento inicial em `useRef`.
-- **`react-router/dom` não foi necessário.** O guia de upgrade do v8 destaca o subpath, mas
-  ele só serve pra `RouterProvider` (framework mode). Todas as APIs usadas aqui
-  (`BrowserRouter`, `Routes`, `Route`, `Link`, `Navigate`, `Outlet`, `useNavigate`,
-  `useLocation`, `useParams`, `useSearchParams`) continuam no entry point raiz. Verificado
-  direto nos `.d.ts` do pacote, não no guia.
-- **As outras breaking changes do v8 não se aplicam:** `data` → `loaderData` só afeta
-  `meta()`/`useMatches()`, e `cloudflareDevProxy` só framework mode — nada disso é usado.
-- **Requisitos de ambiente do v8:** `node@22.22+` e `vite@7+`. O repo já atendia (node
-  v24.16.0, vite 7.3.0).
-- **`npm audit` = 0 vulnerabilidades** (antes: 2 high). Lint segue em 556 problems /
-  492 errors, idêntico ao baseline pré-migração — ruído pré-existente de
-  `no-explicit-any`, nada relacionado.
-
-## Armadilha do build (não relacionada ao React 19, mas morde aqui)
-
-`npm run build` (vite, `outDir` default = `dist`) e `npm run build:lib` (rollup) escrevem no
-**mesmo `dist/`**, e o vite limpa o diretório antes de escrever. Rodar `npm run build`
-depois de `npm run build:lib` **sobrescreve o artefato publicável com o bundle do app**.
-Sempre rodar `build:lib` por último antes de publicar (idealmente `rm -rf dist` antes).
-
-## Checklist pro app consumidor (Forlogic/Qualiex)
-
-1. Subir o app pra `react`/`react-dom` `>=19.2.7` **antes** de subir `forlogic-core` pra `^3.0.0`.
-2. Trocar `react-router-dom` por `react-router@^8.3.0` no `package.json` do app e reescrever
-   os imports (`from 'react-router-dom'` → `from 'react-router'`).
-3. Se o app usa `RouterProvider`/`createBrowserRouter`, importar de `react-router/dom` — a lib
-   não exercita esse caminho, então não foi validado aqui.
-4. Se o app usa `meta()` ou `useMatches()`, aplicar `data` → `loaderData`.
-5. `node@22.22+` e `vite@7+` no ambiente de build do app.
-6. Rodar `npm ls react react-dom react-router` depois do install — mais de uma versão
-   resolvida (não deduped) significa que o conflito não foi resolvido.
+---
+name: React 19 migration roadmap
+description: Migração do forlogic-core para React 19 + react-router v8 — CONCLUÍDA na 3.0.0 (2026-08-01); consumidores precisam estar em React 19 antes de atualizar
+type: feature
+---
+
+**Status: concluída na `forlogic-core@3.0.0` (2026-08-01).** Levantada em 2026-07-24 a partir de
+[[react-router-dom-v7-migration]], quando a decisão foi manter React 18 e aceitar o risco do
+CVE GHSA-qwww-vcr4-c8h2. Executada agora porque `react-router@8.3.0` (fix do CVE) exige
+peer `react >=19.2.7`.
+
+## O que foi feito
+
+Os 6 passos do escopo original, todos aplicados:
+
+1. **`react`/`react-dom` movidos de `dependencies` → `peerDependencies` (`^19.2.7`)** — mesmo
+   problema de duplicação silenciosa que motivou mover `react-router-dom` na 2.5.0. Ficaram
+   também em `devDependencies` (`^19.2.8`) para o build e o vite dev do próprio app.
+2. **`next-themes` `^0.3.0` → `^0.4.6`** — era o bloqueio conhecido; a 0.4.6 aceita
+   `react ^19`.
+3. **`react-router-dom` → `react-router`** em 33 imports / 31 arquivos (`lib/` + `src/`),
+   mais o externo em `rollup.config.js#externalDeps` e os snippets em
+   `docs/design-system/examples.md` e `docs/design-system/patterns/core-providers.md`.
+4. **`react`/`react-dom` `^19.2.8`, `@types/react` `^19.2.18`, `@types/react-dom` `^19.2.4`.**
+5. Build e typecheck validados (ver abaixo). **Validação visual do `/ds` continua pendente
+   para quem for publicar** — mudanças de comportamento de render do React 19 não aparecem
+   em erro de compilação.
+6. Coordenação com Forlogic/Qualiex — **pendente do lado dos apps**, ver checklist abaixo.
+
+## Achados da execução
+
+- **O levantamento de 2026-07-24 estava certo:** o código já estava limpo pra React 19.
+  Único ajuste necessário no repo inteiro foi `lib/hooks/useDebounce.ts:60` —
+  `useRef<NodeJS.Timeout>()` → `useRef<NodeJS.Timeout | undefined>(undefined)`, porque os
+  types do React 19 passaram a exigir argumento inicial em `useRef`.
+- **`react-router/dom` não foi necessário.** O guia de upgrade do v8 destaca o subpath, mas
+  ele só serve pra `RouterProvider` (framework mode). Todas as APIs usadas aqui
+  (`BrowserRouter`, `Routes`, `Route`, `Link`, `Navigate`, `Outlet`, `useNavigate`,
+  `useLocation`, `useParams`, `useSearchParams`) continuam no entry point raiz. Verificado
+  direto nos `.d.ts` do pacote, não no guia.
+- **As outras breaking changes do v8 não se aplicam:** `data` → `loaderData` só afeta
+  `meta()`/`useMatches()`, e `cloudflareDevProxy` só framework mode — nada disso é usado.
+- **Requisitos de ambiente do v8:** `node@22.22+` e `vite@7+`. O repo já atendia (node
+  v24.16.0, vite 7.3.0).
+- **`npm audit` = 0 vulnerabilidades** (antes: 2 high). Lint segue em 556 problems /
+  492 errors, idêntico ao baseline pré-migração — ruído pré-existente de
+  `no-explicit-any`, nada relacionado.
+
+## Armadilha do build (não relacionada ao React 19, mas morde aqui)
+
+`npm run build` (vite, `outDir` default = `dist`) e `npm run build:lib` (rollup) escrevem no
+**mesmo `dist/`**, e o vite limpa o diretório antes de escrever. Rodar `npm run build`
+depois de `npm run build:lib` **sobrescreve o artefato publicável com o bundle do app**.
+Sempre rodar `build:lib` por último antes de publicar (idealmente `rm -rf dist` antes).
+
+## Checklist pro app consumidor (Forlogic/Qualiex)
+
+1. Subir o app pra `react`/`react-dom` `>=19.2.7` **antes** de subir `forlogic-core` pra `^3.0.0`.
+2. Trocar `react-router-dom` por `react-router@^8.3.0` no `package.json` do app e reescrever
+   os imports (`from 'react-router-dom'` → `from 'react-router'`).
+3. Se o app usa `RouterProvider`/`createBrowserRouter`, importar de `react-router/dom` — a lib
+   não exercita esse caminho, então não foi validado aqui.
+4. Se o app usa `meta()` ou `useMatches()`, aplicar `data` → `loaderData`.
+5. `node@22.22+` e `vite@7+` no ambiente de build do app.
+6. Rodar `npm ls react react-dom react-router` depois do install — mais de uma versão
+   resolvida (não deduped) significa que o conflito não foi resolvido.

package/dist/components/ui/updates-notification.d.ts

@@ -21,12 +21,18 @@ export interface UpdatesNotificationProps {
     badgeCount?: number;
     onOpen?: () => void;
     onViewAll?: () => void;
+    /**
+     * Rota interna (relativa ao router do app, sem base path) do portal de
+     * atualizações. Quando informada, navega internamente em vez de abrir o app
+     * Common V5. Default: abre `{commonV5AppUrl}{alias}/up/view` em nova aba.
+     */
+    viewAllPath?: string;
 }
 /**
  * Botão de notificações do header (ícone de café ☕). Possui dois modos:
  *
  * - **Automático** (sem props): busca atualizações via `useUpdatesNotification`,
- *   marca como visualizado ao abrir e abre o portal Qualiex no "Ver todas".
+ *   marca como visualizado ao abrir e navega para a rota de atualizações do app.
  * - **Controlado**: passe `updates` + `badgeCount` + `onOpen` + `onViewAll`.
  *
  * @example Automático (recomendado dentro do AppHeader)

package/dist/config/environments.d.ts

@@ -51,6 +51,12 @@ export interface EnvironmentConfig {
      * ao V4 as unidades SEM a flag `has_common_v5` ao trocar de unidade.
      */
     commonV4AppUrl: string;
+    /**
+     * URL do app V5 (React) do módulo common, COM barra final
+     * (ex.: `https://apps5.qualiex.com/common/`). Único app que hospeda a página
+     * de atualizações (`{alias}/up/view`).
+     */
+    commonV5AppUrl: string;
 }
 /**
  * Override parcial injetado em runtime pelo app consumidor (ex.: a partir de um

package/dist/config/index.d.ts

@@ -56,6 +56,11 @@ export declare const getLoginApiUrlOverride: () => string;
  * de unidades SEM a flag `has_common_v5` ao trocar de unidade no V5.
  */
 export declare const getCommonV4AppUrl: () => string;
+/**
+ * URL do app V5 (React) do módulo common, COM barra final. Único app que hospeda
+ * a página de atualizações (`{alias}/up/view`).
+ */
+export declare const getCommonV5AppUrl: () => string;
 export declare const QUERY_KEYS: {
     readonly crud: (entity: string) => readonly [string];
     readonly list: (entity: string, filters?: Record<string, any>) => readonly [string, "list", Record<string, any>];