import { useEffect, useId, useRef, useState } from 'react'; import { createPortal } from 'react-dom'; import { formFieldGuidance, formHelpPlacement, readFormHelpAutomatic, simulationStepGuidance, } from '@/lib/form-help'; import { formHelpControls, formHelpGroupControls, formHelpControlSelector, formHelpControlVisible, formHelpField, formHelpStep, } from '@/lib/form-help-dom'; const preferenceKey = 'investemoz:form-field-help:v1'; const button = 'min-h-11 rounded-lg border px-3 py-2 text-sm font-semibold focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-emerald-700'; type Step = { title: string; code: string; context: string }; /** Read-only assistance: observes labels and structure, never form values or submissions. */ export default function FormFieldHelp() { const [control, setControl] = useState(null); const [step, setStep] = useState(null); const [available, setAvailable] = useState(false); const [open, setOpen] = useState(false); const [automatic, setAutomatic] = useState(true); 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); const root = useRef(null); const id = useId(); useEffect(() => { try { automaticRef.current = readFormHelpAutomatic( localStorage.getItem(preferenceKey), ); } catch { /* Optional preference. */ } setAutomatic(automaticRef.current); let frame = 0; let lastExplicitStep = ''; let lastDescription = ''; let page = location.pathname; function place(target: HTMLElement) { const layout = formHelpPlacement( target.getBoundingClientRect(), innerWidth, innerHeight, ); setPosition(layout.side); setVertical(layout.vertical); setPanelHeight(layout.maxHeight); } function select(target: HTMLElement, show: boolean) { current.current = target; setControl(target); setStep(formHelpStep(target)); setDialog( target.closest('[role="dialog"],dialog[open]'), ); place(target); if (show) setOpen(true); } function scan() { frame = 0; if (page !== location.pathname) { page = location.pathname; current.current = null; paused.current = false; lastExplicitStep = ''; setOpen(false); setDialog(null); } const controls = formHelpControls(document); const explicit = document.querySelector( '[data-form-help-context="simulator"]', ); setAvailable(Boolean(controls.length || explicit)); const signature = explicit ? `${page}:${explicit.dataset.formHelpStep}` : ''; if (signature && signature !== lastExplicitStep) { lastExplicitStep = signature; const first = controls.find((node) => explicit?.contains(node)); current.current = first ?? null; setControl(first ?? null); setStep({ title: explicit?.dataset.formHelpTitle ?? 'Preencher este passo', code: explicit?.dataset.formHelpStep ?? '', context: 'simulator', }); if (automaticRef.current && !paused.current) setOpen(true); } else if ( current.current && !formHelpControlVisible(current.current) ) { current.current = null; setControl(null); setOpen(false); setDialog(null); } else if (!current.current && controls[0] && !explicit) { select(controls[0], false); } if (current.current && formHelpControlVisible(current.current)) { place(current.current); const description = JSON.stringify([ formHelpField(current.current), formHelpStep(current.current), ]); if (description !== lastDescription) { lastDescription = description; setStep(formHelpStep(current.current)); } } } const schedule = () => { if (!frame) frame = requestAnimationFrame(scan); }; function focus(event: Event) { if ( !(event.target instanceof Element) || event.target.closest('[data-form-field-help]') ) return; const target = event.target.closest( formHelpControlSelector, ); if ( target && target.closest( 'main,[role="main"],[role="dialog"],dialog[open]', ) && formHelpControlVisible(target) ) select(target, automaticRef.current && !paused.current); } function click(event: Event) { if (!(event.target instanceof Element)) return; const trigger = event.target.closest( '[data-form-help-open]', ); if (!trigger) return; paused.current = false; const scope = trigger.closest( '[data-form-help-context]', ); if (scope) { current.current = null; setControl(null); setStep({ title: scope.dataset.formHelpTitle ?? 'Preencher este passo', code: scope.dataset.formHelpStep ?? '', context: scope.dataset.formHelpContext ?? '', }); } setOpen(true); requestAnimationFrame(() => root.current ?.querySelector('[data-form-help-panel]') ?.focus({ preventScroll: true }), ); } const observer = new MutationObserver((records) => { if ( records.some( (record) => !( record.target instanceof Element ? record.target : record.target.parentElement )?.closest('[data-form-field-help]'), ) ) schedule(); }); observer.observe(document.body, { childList: true, characterData: true, subtree: true, attributes: true, attributeFilter: [ 'hidden', 'disabled', 'readonly', 'aria-hidden', 'aria-disabled', 'required', 'aria-required', 'aria-label', 'aria-labelledby', 'aria-describedby', 'placeholder', 'class', 'style', 'data-form-help-step', 'data-form-help-title', ], }); document.addEventListener('focusin', focus); document.addEventListener('click', click); document.addEventListener('toggle', schedule, true); window.addEventListener('resize', schedule); const scroll = () => { if (current.current) place(current.current); }; window.addEventListener('scroll', scroll, { passive: true }); scan(); return () => { observer.disconnect(); if (frame) cancelAnimationFrame(frame); document.removeEventListener('focusin', focus); document.removeEventListener('click', click); document.removeEventListener('toggle', schedule, true); window.removeEventListener('resize', schedule); window.removeEventListener('scroll', scroll); }; }, []); if (!available) return null; const field = control ? formHelpField(control) : null; const guidance = field ? formFieldGuidance(field) : null; function close() { paused.current = true; setOpen(false); root.current ?.querySelector('[data-form-help-toggle]') ?.focus({ preventScroll: true }); } function move(direction: number) { const fields = formHelpGroupControls(document, control); const index = control ? fields.indexOf(control) : -1; const target = fields[index + direction]; if (!target) return; paused.current = false; target.focus({ preventScroll: true }); target.scrollIntoView({ block: 'center', behavior: 'auto' }); current.current = target; setControl(target); setStep(formHelpStep(target)); } const fields = formHelpGroupControls(document, control); const index = control ? fields.indexOf(control) : -1; const content = ( ); // Keep help inside a modal's focus scope instead of behind its backdrop. return dialog?.isConnected ? createPortal(content, dialog) : content; }