Keep contextual filling help within modal form focus scopes
tests / ci (push) Canceled after 0s

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. 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. 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 { useEffect, useId, useRef, useState } from 'react';
import { createPortal } from 'react-dom';
import { import {
formFieldGuidance, formFieldGuidance,
formHelpPlacement, formHelpPlacement,
@@ -29,6 +30,7 @@ export default function FormFieldHelp() {
const [position, setPosition] = useState<'left' | 'right'>('right'); const [position, setPosition] = useState<'left' | 'right'>('right');
const [vertical, setVertical] = useState<'top' | 'bottom'>('bottom'); const [vertical, setVertical] = useState<'top' | 'bottom'>('bottom');
const [panelHeight, setPanelHeight] = useState<number | undefined>(); const [panelHeight, setPanelHeight] = useState<number | undefined>();
const [dialog, setDialog] = useState<HTMLElement | null>(null);
const automaticRef = useRef(true); const automaticRef = useRef(true);
const paused = useRef(false); const paused = useRef(false);
const current = useRef<HTMLElement | null>(null); const current = useRef<HTMLElement | null>(null);
@@ -62,6 +64,9 @@ export default function FormFieldHelp() {
current.current = target; current.current = target;
setControl(target); setControl(target);
setStep(formHelpStep(target)); setStep(formHelpStep(target));
setDialog(
target.closest<HTMLElement>('[role="dialog"],dialog[open]'),
);
place(target); place(target);
if (show) setOpen(true); if (show) setOpen(true);
} }
@@ -73,6 +78,7 @@ export default function FormFieldHelp() {
paused.current = false; paused.current = false;
lastExplicitStep = ''; lastExplicitStep = '';
setOpen(false); setOpen(false);
setDialog(null);
} }
const controls = formHelpControls(document); const controls = formHelpControls(document);
const explicit = document.querySelector<HTMLElement>( const explicit = document.querySelector<HTMLElement>(
@@ -102,6 +108,7 @@ export default function FormFieldHelp() {
current.current = null; current.current = null;
setControl(null); setControl(null);
setOpen(false); setOpen(false);
setDialog(null);
} else if (!current.current && controls[0] && !explicit) { } else if (!current.current && controls[0] && !explicit) {
select(controls[0], false); select(controls[0], false);
} }
@@ -131,7 +138,9 @@ export default function FormFieldHelp() {
); );
if ( if (
target && target &&
target.closest('main,[role="main"],[role="dialog"]') && target.closest(
'main,[role="main"],[role="dialog"],dialog[open]',
) &&
formHelpControlVisible(target) formHelpControlVisible(target)
) )
select(target, automaticRef.current && !paused.current); select(target, automaticRef.current && !paused.current);
@@ -243,12 +252,16 @@ export default function FormFieldHelp() {
} }
const fields = formHelpGroupControls(document, control); const fields = formHelpGroupControls(document, control);
const index = control ? fields.indexOf(control) : -1; const index = control ? fields.indexOf(control) : -1;
return ( const content = (
<aside <aside
ref={root} ref={root}
data-form-field-help data-form-field-help
aria-label="Ajuda ao preenchimento" 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) => { onKeyDown={(event) => {
if (event.key === 'Escape' && open) { if (event.key === 'Escape' && open) {
event.preventDefault(); event.preventDefault();
@@ -262,7 +275,11 @@ export default function FormFieldHelp() {
data-form-help-panel data-form-help-panel
tabIndex={-1} tabIndex={-1}
aria-labelledby={`${id}-title`} 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" 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"> <div className="flex items-start justify-between gap-3">
@@ -381,4 +398,6 @@ export default function FormFieldHelp() {
</button> </button>
</aside> </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[] { export function formHelpControls(document: Document): HTMLElement[] {
const roots = document.querySelectorAll( const roots = document.querySelectorAll(
'main,[role="main"],[role="dialog"]', 'main,[role="main"],[role="dialog"],dialog[open]',
); );
return [ return [
...new Set( ...new Set(
@@ -68,7 +68,7 @@ export function formHelpGroupControls(
control: HTMLElement | null, control: HTMLElement | null,
): HTMLElement[] { ): HTMLElement[] {
const scope = control?.closest( 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); const controls = formHelpControls(document);
return scope ? controls.filter((node) => scope.contains(node)) : controls; return scope ? controls.filter((node) => scope.contains(node)) : controls;
@@ -156,7 +156,9 @@ export function formHelpStep(control: HTMLElement): {
code: investment.dataset.investmentStep ?? '', code: investment.dataset.investmentStep ?? '',
context: 'investor-path', 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 titleId = scope?.getAttribute('aria-labelledby');
const title = const title =
(titleId (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, /<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/);
});