Files
Investidor-V2/resources/js/components/investment-step-help.tsx
T
2026-11-17 09:17:14 +02:00

309 lines
12 KiB
TypeScript

import {
createContext,
useContext,
useEffect,
useId,
useRef,
useState,
type ReactNode,
} from 'react';
import { CircleHelp } from 'lucide-react';
import {
helpPreferenceKey,
readHelpPreference,
type InvestmentHelp,
} from '@/lib/investment-step-help';
type GuideState = {
steps: InvestmentHelp[];
active: string | null;
automatic: boolean;
choose: (code: string | null, reveal?: boolean) => void;
};
const GuideContext = createContext<GuideState | null>(null);
const helpButton =
'inline-flex min-h-11 items-center justify-center gap-2 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';
export function InvestmentHelpGuide({
steps,
user,
flow,
initialCode,
children,
}: {
steps: InvestmentHelp[];
user: string | number;
flow: string;
initialCode?: string;
children: ReactNode;
}) {
const root = useRef<HTMLDivElement>(null);
const [active, setActive] = useState<string | null>(null);
const [automatic, setAutomatic] = useState(true);
const paused = useRef(false);
const key = helpPreferenceKey(user, flow);
const firstCode = steps.some((step) => step.code === initialCode)
? initialCode
: steps[0]?.code;
useEffect(() => {
let preference = readHelpPreference(null);
try {
preference = readHelpPreference(window.localStorage.getItem(key));
} catch {
/* Help also works without browser storage. */
}
setAutomatic(preference.automatic);
setActive(
preference.automatic && !preference.seen
? (firstCode ?? null)
: null,
);
paused.current = false;
try {
window.localStorage.setItem(
key,
JSON.stringify({ ...preference, seen: true }),
);
} catch {
/* Optional preference only. */
}
}, [key]); // A new applicable step does not restart a dismissed guide.
const visibleActive = steps.some((step) => step.code === active)
? active
: null;
useEffect(() => {
if (!visibleActive || !root.current) return;
const target = Array.from(
root.current.querySelectorAll<HTMLElement>(
'[data-investment-step]',
),
).find((node) => node.dataset.investmentStep === visibleActive);
let ancestor: HTMLElement | null = target ?? null;
while (ancestor && ancestor !== root.current) {
if (ancestor.tagName === 'DETAILS')
(ancestor as HTMLDetailsElement).open = true;
ancestor = ancestor.parentElement;
}
}, [visibleActive]);
function choose(code: string | null, reveal = false) {
paused.current = code === null;
if (code === null && visibleActive) {
const panel = Array.from(
root.current?.querySelectorAll<HTMLElement>(
'[data-help-panel]',
) ?? [],
).find((node) => node.dataset.helpPanel === visibleActive);
panel?.parentElement
?.querySelector<HTMLButtonElement>('button')
?.focus({ preventScroll: true });
}
setActive(code);
if (code && reveal) {
// Wait for the selected inline explanation to render before focusing it.
requestAnimationFrame(() => {
const target = Array.from(
root.current?.querySelectorAll<HTMLElement>(
'[data-help-panel]',
) ?? [],
).find((node) => node.dataset.helpPanel === code);
target?.scrollIntoView({ block: 'nearest' });
target?.focus({ preventScroll: true });
});
}
}
function orient(target: EventTarget, disclosure = false) {
if (
!automatic ||
paused.current ||
!(target instanceof Element) ||
target.closest('[data-help-controls]') ||
(!disclosure && target.closest('summary'))
)
return;
const code = target.closest<HTMLElement>('[data-investment-step]')
?.dataset.investmentStep;
if (code && steps.some((step) => step.code === code)) setActive(code);
}
useEffect(() => {
const node = root.current;
if (!node) return;
const onToggle = (event: Event) => {
const target = event.target;
// Native toggle follows the summary click. Observe the opened state
// instead of changing it while focus/click is still being dispatched.
if (target instanceof HTMLDetailsElement && target.open) {
orient(target, true);
}
};
node.addEventListener('toggle', onToggle, true);
return () => node.removeEventListener('toggle', onToggle, true);
}, [automatic, steps]);
return (
<GuideContext.Provider
value={{ steps, active: visibleActive, automatic, choose }}
>
<div
ref={root}
className="space-y-5"
onFocusCapture={(event) => orient(event.target)}
onClickCapture={(event) => orient(event.target)}
onKeyDown={(event) => {
if (
event.key === 'Escape' &&
visibleActive &&
(event.target as Element).closest('[data-help-panel]')
) {
event.preventDefault();
choose(null);
}
}}
>
<section
aria-label="Guia de ajuda do Investemoz"
data-help-controls
className="flex flex-wrap items-center gap-3 rounded-xl border border-emerald-700/30 bg-emerald-50 p-4 text-slate-900 dark:bg-emerald-950 dark:text-slate-100"
>
<div className="min-w-0 flex-1">
<p className="font-semibold">Guia do Investemoz</p>
<p className="text-sm">
Consulte o que fazer, veja um exemplo e avance ao
seu ritmo.
</p>
</div>
<button
type="button"
className={helpButton}
disabled={!steps.length}
onClick={() =>
choose(visibleActive ?? firstCode ?? null, true)
}
>
Ver guia passo a passo
</button>
<label className="flex min-h-11 cursor-pointer items-center gap-2 text-sm">
<input
type="checkbox"
checked={automatic}
onChange={(event) => {
const enabled = event.target.checked;
setAutomatic(enabled);
paused.current = !enabled;
setActive(enabled ? (firstCode ?? null) : null);
try {
window.localStorage.setItem(
key,
JSON.stringify({
automatic: enabled,
seen: true,
}),
);
} catch {
/* Optional preference only. */
}
}}
/>
Orientações automáticas
</label>
</section>
{children}
</div>
</GuideContext.Provider>
);
}
export function HelpAtStep({ code }: { code: string }) {
const guide = useContext(GuideContext);
const id = useId();
const index = guide?.steps.findIndex((step) => step.code === code) ?? -1;
if (!guide || index < 0) return null;
const step = guide.steps[index];
const open = guide.active === code;
return (
<div data-help-controls className="my-3">
<button
type="button"
className={helpButton}
aria-expanded={open}
aria-controls={id}
aria-label={`Ajuda neste passo: ${step.title}`}
onClick={() => guide.choose(open ? null : code)}
>
<CircleHelp className="size-4 shrink-0" aria-hidden="true" />{' '}
Ajuda neste passo
</button>
{open && (
<section
id={id}
data-help-panel={code}
tabIndex={-1}
aria-labelledby={`${id}-title`}
className="mt-3 space-y-3 rounded-xl border-2 border-emerald-700 bg-emerald-50 p-4 text-slate-900 focus-visible:outline-2 focus-visible:outline-offset-2 dark:bg-emerald-950 dark:text-slate-100"
>
<p className="text-sm" role="status">
Ajuda · Passo {index + 1} de {guide.steps.length}
</p>
<h3 id={`${id}-title`} className="font-semibold">
{step.title}
</h3>
<p>
<strong>O que fazer:</strong> {step.instruction}
</p>
<p>
<strong>Exemplo:</strong> {step.example}
</p>
<p>
<strong>Para que serve:</strong> {step.purpose}
</p>
<div className="flex flex-wrap gap-2">
<button
type="button"
className={helpButton}
disabled={index === 0}
onClick={() =>
guide.choose(guide.steps[index - 1].code, true)
}
>
Voltar
</button>
{index < guide.steps.length - 1 ? (
<button
type="button"
className={helpButton}
onClick={() =>
guide.choose(
guide.steps[index + 1].code,
true,
)
}
>
Seguinte
</button>
) : (
<button
type="button"
className={helpButton}
onClick={() => guide.choose(null)}
>
Concluir guia
</button>
)}
<button
type="button"
className={helpButton}
onClick={() => guide.choose(null)}
>
Fechar guia
</button>
</div>
</section>
)}
</div>
);
}