Keep contextual filling help within modal form focus scopes
tests / ci (push) Waiting to run

This commit is contained in:
2026-11-17 10:08:07 +02:00
parent ded66878af
commit 953602fb85
4 changed files with 51 additions and 7 deletions
@@ -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.
+23 -4
View File
@@ -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<number | undefined>();
const [dialog, setDialog] = useState<HTMLElement | null>(null);
const automaticRef = useRef(true);
const paused = useRef(false);
const current = useRef<HTMLElement | null>(null);
@@ -62,6 +64,9 @@ export default function FormFieldHelp() {
current.current = target;
setControl(target);
setStep(formHelpStep(target));
setDialog(
target.closest<HTMLElement>('[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<HTMLElement>(
@@ -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 = (
<aside
ref={root}
data-form-field-help
aria-label="Ajuda ao preenchimento"
className={`fixed z-40 max-w-[calc(100%-1.5rem)] text-slate-900 ${vertical === 'top' ? 'top-20' : 'bottom-3'} ${position === 'left' ? 'left-3' : 'right-3'}`}
className={
dialog
? 'mt-3 max-w-full min-w-0 text-slate-900'
: `fixed z-40 max-w-[calc(100%-1.5rem)] text-slate-900 ${vertical === 'top' ? 'top-20' : 'bottom-3'} ${position === 'left' ? 'left-3' : 'right-3'}`
}
onKeyDown={(event) => {
if (event.key === 'Escape' && open) {
event.preventDefault();
@@ -262,7 +275,11 @@ export default function FormFieldHelp() {
data-form-help-panel
tabIndex={-1}
aria-labelledby={`${id}-title`}
style={{ maxHeight: panelHeight }}
style={{
maxHeight: dialog
? Math.min(innerHeight * 0.3, 260)
: panelHeight,
}}
className="mb-2 max-h-[45dvh] w-96 max-w-full space-y-3 overflow-y-auto rounded-xl border-2 border-emerald-700 bg-white p-4 shadow-xl focus-visible:outline-2"
>
<div className="flex items-start justify-between gap-3">
@@ -381,4 +398,6 @@ export default function FormFieldHelp() {
</button>
</aside>
);
// Keep help inside a modal's focus scope instead of behind its backdrop.
return dialog?.isConnected ? createPortal(content, dialog) : content;
}
+5 -3
View File
@@ -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
+21
View File
@@ -169,3 +169,24 @@ test('help mounts once across portal pages and the simulator publishes its curre
/<button[^>]*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/);
});