This commit is contained in:
@@ -0,0 +1,292 @@
|
||||
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) {
|
||||
if (
|
||||
!automatic ||
|
||||
paused.current ||
|
||||
!(target instanceof Element) ||
|
||||
target.closest('[data-help-controls]')
|
||||
)
|
||||
return;
|
||||
const code = target.closest<HTMLElement>('[data-investment-step]')
|
||||
?.dataset.investmentStep;
|
||||
if (code && steps.some((step) => step.code === code)) setActive(code);
|
||||
}
|
||||
|
||||
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>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,168 @@
|
||||
export type InvestmentHelp = {
|
||||
code: string;
|
||||
title: string;
|
||||
instruction: string;
|
||||
example: string;
|
||||
purpose: string;
|
||||
};
|
||||
|
||||
// Orientation only: the existing path continues to determine applicability and permissions.
|
||||
const stageHelp: Record<string, [string, string, string]> = {
|
||||
S01: [
|
||||
'Descreva a ideia, o produto ou serviço e os clientes que pretende servir.',
|
||||
'Produzir hortícolas para fornecer mercados locais.',
|
||||
'Definir o investimento que irá preparar nas etapas seguintes.',
|
||||
],
|
||||
S02: [
|
||||
'Reúna informação sobre o mercado, os recursos necessários e os principais riscos. Consulte as ferramentas disponíveis no dossier.',
|
||||
'Compare procura, fornecedores, localização e custos previstos.',
|
||||
'Identificar o que já sabe e a informação que ainda precisa de obter.',
|
||||
],
|
||||
S03: [
|
||||
'Compare as receitas e os custos estimados e registe a sua conclusão sobre a viabilidade.',
|
||||
'Teste como uma redução das vendas afecta o resultado estimado.',
|
||||
'Apoiar a sua decisão com pressupostos explícitos. Uma simulação é uma estimativa.',
|
||||
],
|
||||
S04: [
|
||||
'Organize os recursos, os participantes e o plano de realização do investimento.',
|
||||
'Indique quem fará o quê e quais os recursos a mobilizar.',
|
||||
'Transformar a ideia num plano de preparação e execução.',
|
||||
],
|
||||
S05: [
|
||||
'Confira a situação da entidade e os elementos de constituição e registo aplicáveis. Reutilize os dados já disponíveis.',
|
||||
'Se a empresa já existe, confira os seus dados antes de os voltar a preencher.',
|
||||
'Preparar a identificação da entidade que realizará o investimento.',
|
||||
],
|
||||
S06: [
|
||||
'Reúna os dados e associe os documentos indicados para este investimento. Reveja o que ainda falta.',
|
||||
'Associe um documento já disponível no dossier ao requisito correspondente.',
|
||||
'Organizar o dossier antes de preparar uma entrega.',
|
||||
],
|
||||
S07: [
|
||||
'Confira o destinatário e os requisitos da entrega aplicável. Se já entregou, registe a referência e a evidência disponível.',
|
||||
'Registe a data e o protocolo de uma entrega efectivamente realizada.',
|
||||
'Acompanhar a entrega sem confundir preparação com submissão.',
|
||||
],
|
||||
S08: [
|
||||
'Consulte as licenças indicadas para a actividade e localização. Prepare os elementos em falta e registe os actos já documentados.',
|
||||
'Identifique a entidade competente e associe a licença recebida, quando disponível.',
|
||||
'Acompanhar o licenciamento aplicável ao seu projecto.',
|
||||
],
|
||||
S09: [
|
||||
'Indique se o investimento necessita de terra e explique a situação conhecida.',
|
||||
'Indique se utilizará instalações existentes ou se precisa de uma nova área.',
|
||||
'Adaptar a preparação da terra às necessidades do investimento.',
|
||||
],
|
||||
S10: [
|
||||
'Reúna a informação da localização e os documentos relativos à regularização da terra indicados no percurso.',
|
||||
'Associe o documento disponível e identifique a área a que se refere.',
|
||||
'Organizar a preparação da terra sem presumir direitos ainda não documentados.',
|
||||
],
|
||||
S11: [
|
||||
'Confira a regularização aplicável e registe o resultado com o respectivo fundamento.',
|
||||
'Registe a referência e a data do documento que comprova a situação declarada.',
|
||||
'Distinguir a preparação da confirmação documental da regularização.',
|
||||
],
|
||||
S12: [
|
||||
'Compare os recursos próprios com o investimento previsto e indique se necessita de financiamento externo.',
|
||||
'Separe o capital disponível do montante que ainda precisa de mobilizar.',
|
||||
'Dimensionar a necessidade de financiamento do projecto.',
|
||||
],
|
||||
S13: [
|
||||
'Prepare a informação pedida pelo potencial financiador e registe os pontos de negociação.',
|
||||
'Organize projecções, documentos solicitados e condições em discussão.',
|
||||
'Acompanhar a análise e a negociação do financiamento.',
|
||||
],
|
||||
S14: [
|
||||
'Registe a decisão recebida do financiador e associe a evidência disponível.',
|
||||
'Indique a referência da comunicação recebida e as condições nela apresentadas.',
|
||||
'Conservar a decisão real, sem tratar uma candidatura como aprovação.',
|
||||
],
|
||||
S15: [
|
||||
'Confira as condições de fecho e acompanhe os desembolsos efectivamente documentados.',
|
||||
'Registe a referência e a data de uma disponibilização de fundos confirmada.',
|
||||
'Acompanhar a concretização do financiamento e as condições pendentes.',
|
||||
],
|
||||
S16: [
|
||||
'Organize as actividades de implementação e acompanhe os recursos e os prazos.',
|
||||
'Crie uma tarefa para instalar equipamento com responsável e data prevista.',
|
||||
'Acompanhar a execução do investimento.',
|
||||
],
|
||||
S17: [
|
||||
'Prepare as inspecções e os testes aplicáveis e reúna os documentos para a operação.',
|
||||
'Associe um relatório de inspecção ou a licença recebida à etapa correspondente.',
|
||||
'Identificar o que falta antes do início de operação.',
|
||||
],
|
||||
S18: [
|
||||
'Confira as condições indicadas no percurso e registe o início de operação quando estiver documentado.',
|
||||
'Indique a data efectiva de início e a respectiva referência documental.',
|
||||
'Distinguir a previsão de arranque do início efectivo da actividade.',
|
||||
],
|
||||
S19: [
|
||||
'Actualize o acompanhamento do projecto e reveja as tarefas e os documentos que necessitam de atenção.',
|
||||
'Registe uma tarefa de acompanhamento com responsável e prazo.',
|
||||
'Manter o dossier útil ao longo da operação.',
|
||||
],
|
||||
};
|
||||
|
||||
export function investmentStageHelp(
|
||||
code: string,
|
||||
title: string,
|
||||
): InvestmentHelp {
|
||||
const [instruction, example, purpose] = stageHelp[code] ?? [
|
||||
'Consulte as indicações desta etapa, confira os dados disponíveis e complete o que estiver em falta.',
|
||||
'Registe uma referência documental que sustente a informação preenchida.',
|
||||
'Acompanhar a preparação desta etapa no seu dossier.',
|
||||
];
|
||||
return { code, title, instruction, example, purpose };
|
||||
}
|
||||
|
||||
export const preparationHelp: InvestmentHelp[] = [
|
||||
{
|
||||
code: 'help-choices',
|
||||
title: 'Escolhas e dados do investimento',
|
||||
instruction:
|
||||
'Escolha a oportunidade, o sector e a localização que correspondem ao seu investimento. Confira os dados já recuperados.',
|
||||
example:
|
||||
'Seleccione uma oportunidade existente ou indique o sector e a localização da sua ideia.',
|
||||
purpose: 'Adaptar o percurso ao investimento que pretende realizar.',
|
||||
},
|
||||
{
|
||||
code: 'help-declarations',
|
||||
title: 'Declarações deste investimento',
|
||||
instruction:
|
||||
'Complete apenas as declarações conhecidas e confira os documentos associados. Use as opções apresentadas conforme a sua situação.',
|
||||
example:
|
||||
'Indique a moeda do projecto e confira a situação da entidade.',
|
||||
purpose:
|
||||
'Preparar os dados do processo e identificar o que ainda precisa de esclarecimento.',
|
||||
},
|
||||
{
|
||||
code: 'help-review',
|
||||
title: 'Revisão e confirmação',
|
||||
instruction:
|
||||
'Clique em “Rever dados antes de guardar”. Compare as alterações apresentadas e confirme apenas quando corresponderem ao que pretende.',
|
||||
example:
|
||||
'Ao mudar a localização, confira os dados alterados e as etapas que precisam de revisão.',
|
||||
purpose: 'Permitir que avalie o impacto antes de guardar as escolhas.',
|
||||
},
|
||||
];
|
||||
|
||||
export function helpPreferenceKey(user: string | number, flow: string): string {
|
||||
return `investemoz:step-help:v1:${encodeURIComponent(String(user))}:${encodeURIComponent(flow)}`;
|
||||
}
|
||||
|
||||
export function readHelpPreference(value: string | null): {
|
||||
automatic: boolean;
|
||||
seen: boolean;
|
||||
} {
|
||||
try {
|
||||
const parsed = JSON.parse(value ?? 'null');
|
||||
return {
|
||||
automatic: parsed?.automatic !== false,
|
||||
seen: parsed?.seen === true,
|
||||
};
|
||||
} catch {
|
||||
return { automatic: true, seen: false };
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user