diff --git a/docs/investmoz/unification/traceability-and-manual.md b/docs/investmoz/unification/traceability-and-manual.md index 9e57eced..261e2e52 100644 --- a/docs/investmoz/unification/traceability-and-manual.md +++ b/docs/investmoz/unification/traceability-and-manual.md @@ -10349,3 +10349,5 @@ Simulador: metadados do passo adaptativo e botão junto ao título actual; instr Inventário estático: 112 ficheiros com 160 declarações de formulário, incluindo componentes e páginas; não equivale a 160 demonstrações funcionais individuais. Cobertura comum por tipos/estrutura e botão contextual; origem em main/dialog permite também formulários dinâmicos e modais. Os formulários que não tenham controlos editáveis visíveis não apresentam navegação por campos. Recibo de cobertura: C:/Users/macbook/Documents/Codex/2026-11-17/no/outputs/ajuda-formularios-cobertura.json. QA: seis testes novos (instruções fiscais/financeiras, tipos, percursos adaptativos, ausência de leitura de valores/transporte, preferência e posição móvel); regressão de 1 984 testes frontend aprovada. Lint focado, tipos e compilação QA aprovados; alterações posteriores de indicação/data revistas e testes focados repetidos. Navegador com componente real e dados sintéticos: passos, campo seguinte limitado ao grupo, campos ocultos/desactivados, e-mail, palavra-passe sem exposição do valor, checkbox ARIA com label for, ficheiro dinâmico, fecho/reabertura, preferência após recarregar, zero submissões e ecrã390px sem sobrepor o campo. Testes em StrictMode. A publicação segue o executor normal e terá recibo posterior. Backup/restauro fresco de 195 tabelas/417 ficheiros preparado em /var/backups/investmoz-form-help-20261117/backup; sem alterações de dados, schema, permissões, parâmetros fiscais ou executor. Mantidas as aprovações, limitações anteriores e os restantes critérios da matriz. + +Complemento do mesmo lote: ensaio com Dialog real confirmou a necessidade de manter a ajuda dentro do foco da janela. O painel usa portal React no próprio dialog, conserva os campos montados e volta à página quando a janela fecha. Verificados abrir, fechar/reabrir a ajuda, fechar a janela e regressar ao campo da página, sem submissões. Diálogos nativos abertos também fazem parte do grupo visível. Teste de integração/privacidade acrescentado. diff --git a/resources/js/components/form-field-help.tsx b/resources/js/components/form-field-help.tsx index a8b2b570..54c41d6a 100644 --- a/resources/js/components/form-field-help.tsx +++ b/resources/js/components/form-field-help.tsx @@ -1,4 +1,5 @@ import { useEffect, useId, useRef, useState } from 'react'; +import { createPortal } from 'react-dom'; import { formFieldGuidance, formHelpPlacement, @@ -29,6 +30,7 @@ export default function FormFieldHelp() { const [position, setPosition] = useState<'left' | 'right'>('right'); const [vertical, setVertical] = useState<'top' | 'bottom'>('bottom'); const [panelHeight, setPanelHeight] = useState(); + const [dialog, setDialog] = useState(null); const automaticRef = useRef(true); const paused = useRef(false); const current = useRef(null); @@ -62,6 +64,9 @@ export default function FormFieldHelp() { current.current = target; setControl(target); setStep(formHelpStep(target)); + setDialog( + target.closest('[role="dialog"],dialog[open]'), + ); place(target); if (show) setOpen(true); } @@ -73,6 +78,7 @@ export default function FormFieldHelp() { paused.current = false; lastExplicitStep = ''; setOpen(false); + setDialog(null); } const controls = formHelpControls(document); const explicit = document.querySelector( @@ -102,6 +108,7 @@ export default function FormFieldHelp() { current.current = null; setControl(null); setOpen(false); + setDialog(null); } else if (!current.current && controls[0] && !explicit) { select(controls[0], false); } @@ -131,7 +138,9 @@ export default function FormFieldHelp() { ); if ( target && - target.closest('main,[role="main"],[role="dialog"]') && + target.closest( + 'main,[role="main"],[role="dialog"],dialog[open]', + ) && formHelpControlVisible(target) ) select(target, automaticRef.current && !paused.current); @@ -243,12 +252,16 @@ export default function FormFieldHelp() { } const fields = formHelpGroupControls(document, control); const index = control ? fields.indexOf(control) : -1; - return ( + const content = ( ); + // Keep help inside a modal's focus scope instead of behind its backdrop. + return dialog?.isConnected ? createPortal(content, dialog) : content; } diff --git a/resources/js/lib/form-help-dom.ts b/resources/js/lib/form-help-dom.ts index 036f9659..dd59e8ae 100644 --- a/resources/js/lib/form-help-dom.ts +++ b/resources/js/lib/form-help-dom.ts @@ -50,7 +50,7 @@ export function formHelpControlVisible(control: HTMLElement): boolean { export function formHelpControls(document: Document): HTMLElement[] { const roots = document.querySelectorAll( - 'main,[role="main"],[role="dialog"]', + 'main,[role="main"],[role="dialog"],dialog[open]', ); return [ ...new Set( @@ -68,7 +68,7 @@ export function formHelpGroupControls( control: HTMLElement | null, ): HTMLElement[] { const scope = control?.closest( - 'form,fieldset,[data-form-help-context],[role="dialog"]', + 'form,fieldset,[data-form-help-context],[role="dialog"],dialog[open]', ); const controls = formHelpControls(document); return scope ? controls.filter((node) => scope.contains(node)) : controls; @@ -156,7 +156,9 @@ export function formHelpStep(control: HTMLElement): { code: investment.dataset.investmentStep ?? '', context: 'investor-path', }; - const scope = control.closest('fieldset,section,form,[role="dialog"]'); + const scope = control.closest( + 'fieldset,section,form,[role="dialog"],dialog[open]', + ); const titleId = scope?.getAttribute('aria-labelledby'); const title = (titleId diff --git a/tests/frontend/form-field-help.test.mjs b/tests/frontend/form-field-help.test.mjs index 1e89423a..0a53ee9d 100644 --- a/tests/frontend/form-field-help.test.mjs +++ b/tests/frontend/form-field-help.test.mjs @@ -169,3 +169,24 @@ test('help mounts once across portal pages and the simulator publishes its curre /]*type="button"[^>]*data-form-help-open/s, ); }); + +test('modal assistance remains inside the dialog focus scope and leaves form controls mounted', () => { + const component = readFileSync( + new URL( + '../../resources/js/components/form-field-help.tsx', + import.meta.url, + ), + 'utf8', + ); + assert.match(component, /createPortal\(content, dialog\)/); + assert.doesNotMatch( + component, + /innerHTML|replaceChildren|appendChild|removeChild/, + ); + const dom = readFileSync( + new URL('../../resources/js/lib/form-help-dom.ts', import.meta.url), + 'utf8', + ); + assert.match(dom, /dialog\[open\]/); + assert.doesNotMatch(dom, /cloneNode|\.value\b/); +});