Add contextual filling help across forms and fiscal simulator steps
tests / ci (push) Canceled after 0s
tests / ci (push) Canceled after 0s
This commit is contained in:
@@ -0,0 +1,174 @@
|
||||
import type { HelpField } from './form-help';
|
||||
|
||||
export type HelpControl =
|
||||
| HTMLInputElement
|
||||
| HTMLSelectElement
|
||||
| HTMLTextAreaElement
|
||||
| HTMLElement;
|
||||
export const formHelpControlSelector =
|
||||
'input:not([type="hidden"]):not([type="submit"]):not([type="button"]):not([type="reset"]):not([type="image"]),select,textarea,[role="combobox"],[role="spinbutton"],[role="checkbox"],[role="radio"]';
|
||||
|
||||
function textWithoutControls(node: Element): string {
|
||||
const walker = node.ownerDocument.createTreeWalker(
|
||||
node,
|
||||
NodeFilter.SHOW_TEXT,
|
||||
);
|
||||
const parts: string[] = [];
|
||||
let text: Node | null;
|
||||
while ((text = walker.nextNode())) {
|
||||
if (
|
||||
!text.parentElement?.closest(
|
||||
'input,select,textarea,button,svg,[data-form-field-help]',
|
||||
)
|
||||
)
|
||||
parts.push(text.textContent ?? '');
|
||||
}
|
||||
return parts.join(' ').replace(/\s+/g, ' ').trim().slice(0, 220);
|
||||
}
|
||||
|
||||
export function formHelpControlVisible(control: HTMLElement): boolean {
|
||||
if (
|
||||
!control.isConnected ||
|
||||
control.closest(
|
||||
'[data-form-field-help],header,nav,[hidden],[inert],[aria-hidden="true"],details:not([open])',
|
||||
)
|
||||
)
|
||||
return false;
|
||||
if (
|
||||
control.matches(
|
||||
':disabled,[disabled],[aria-disabled="true"],[readonly]',
|
||||
)
|
||||
)
|
||||
return false;
|
||||
const style = control.ownerDocument.defaultView?.getComputedStyle(control);
|
||||
return (
|
||||
style?.display !== 'none' &&
|
||||
style?.visibility !== 'hidden' &&
|
||||
control.getClientRects().length > 0
|
||||
);
|
||||
}
|
||||
|
||||
export function formHelpControls(document: Document): HTMLElement[] {
|
||||
const roots = document.querySelectorAll(
|
||||
'main,[role="main"],[role="dialog"]',
|
||||
);
|
||||
return [
|
||||
...new Set(
|
||||
Array.from(roots).flatMap((root) =>
|
||||
Array.from(
|
||||
root.querySelectorAll<HTMLElement>(formHelpControlSelector),
|
||||
),
|
||||
),
|
||||
),
|
||||
].filter(formHelpControlVisible);
|
||||
}
|
||||
|
||||
export function formHelpGroupControls(
|
||||
document: Document,
|
||||
control: HTMLElement | null,
|
||||
): HTMLElement[] {
|
||||
const scope = control?.closest(
|
||||
'form,fieldset,[data-form-help-context],[role="dialog"]',
|
||||
);
|
||||
const controls = formHelpControls(document);
|
||||
return scope ? controls.filter((node) => scope.contains(node)) : controls;
|
||||
}
|
||||
|
||||
export function formHelpField(control: HTMLElement): HelpField {
|
||||
const document = control.ownerDocument;
|
||||
const labelledBy = (control.getAttribute('aria-labelledby') ?? '')
|
||||
.split(/\s+/)
|
||||
.filter(Boolean)
|
||||
.map((id) => document.getElementById(id))
|
||||
.filter((node): node is HTMLElement => Boolean(node));
|
||||
const labels =
|
||||
'labels' in control
|
||||
? Array.from((control as HTMLInputElement).labels ?? [])
|
||||
: Array.from(document.querySelectorAll('label')).filter(
|
||||
(label) =>
|
||||
Boolean(control.id) && label.htmlFor === control.id,
|
||||
);
|
||||
const label =
|
||||
control.getAttribute('aria-label')?.trim() ||
|
||||
labelledBy.map(textWithoutControls).join(' ') ||
|
||||
labels.map(textWithoutControls).join(' ') ||
|
||||
textWithoutControls(
|
||||
control.closest('label') ?? document.createElement('span'),
|
||||
) ||
|
||||
control.getAttribute('placeholder') ||
|
||||
(control.getAttribute('name') ?? '')
|
||||
.replace(/[[\]_.-]+/g, ' ')
|
||||
.trim() ||
|
||||
'Campo deste formulário';
|
||||
const role = control.getAttribute('role');
|
||||
const type =
|
||||
role && ['combobox', 'checkbox', 'radio', 'spinbutton'].includes(role)
|
||||
? role === 'spinbutton'
|
||||
? 'number'
|
||||
: role
|
||||
: control.tagName === 'SELECT'
|
||||
? 'select'
|
||||
: control.tagName === 'TEXTAREA'
|
||||
? 'textarea'
|
||||
: (control.getAttribute('type') ?? 'text');
|
||||
const hint = (control.getAttribute('aria-describedby') ?? '')
|
||||
.split(/\s+/)
|
||||
.filter(Boolean)
|
||||
.map((id) => document.getElementById(id))
|
||||
.filter((node): node is HTMLElement => Boolean(node))
|
||||
.map(textWithoutControls)
|
||||
.join(' ')
|
||||
.slice(0, 450);
|
||||
return {
|
||||
label,
|
||||
type,
|
||||
required:
|
||||
control.hasAttribute('required') ||
|
||||
control.getAttribute('aria-required') === 'true',
|
||||
hint,
|
||||
context: control.closest<HTMLElement>('[data-form-help-context]')
|
||||
?.dataset.formHelpContext,
|
||||
};
|
||||
}
|
||||
|
||||
export function formHelpStep(control: HTMLElement): {
|
||||
title: string;
|
||||
code: string;
|
||||
context: string;
|
||||
} {
|
||||
const explicit = control.closest<HTMLElement>('[data-form-help-context]');
|
||||
if (explicit)
|
||||
return {
|
||||
title: explicit.dataset.formHelpTitle ?? 'Preencher este passo',
|
||||
code: explicit.dataset.formHelpStep ?? '',
|
||||
context: explicit.dataset.formHelpContext ?? '',
|
||||
};
|
||||
const investment = control.closest<HTMLElement>('[data-investment-step]');
|
||||
if (investment)
|
||||
return {
|
||||
title: (
|
||||
investment.querySelector(
|
||||
':scope > summary,:scope > h2,:scope > h3',
|
||||
)?.textContent ?? 'Preencher esta etapa'
|
||||
)
|
||||
.replace(/\s+/g, ' ')
|
||||
.trim(),
|
||||
code: investment.dataset.investmentStep ?? '',
|
||||
context: 'investor-path',
|
||||
};
|
||||
const scope = control.closest('fieldset,section,form,[role="dialog"]');
|
||||
const titleId = scope?.getAttribute('aria-labelledby');
|
||||
const title =
|
||||
(titleId
|
||||
? control.ownerDocument.getElementById(titleId)?.textContent
|
||||
: undefined) ||
|
||||
scope?.getAttribute('aria-label') ||
|
||||
scope?.querySelector('legend,h2,h3,h4')?.textContent ||
|
||||
control.ownerDocument.querySelector('main h1')?.textContent ||
|
||||
'Preencher o formulário';
|
||||
return {
|
||||
title: title.replace(/\s+/g, ' ').trim().slice(0, 180),
|
||||
code: '',
|
||||
context: '',
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,234 @@
|
||||
export type HelpField = {
|
||||
label: string;
|
||||
type: string;
|
||||
required: boolean;
|
||||
hint?: string;
|
||||
context?: string;
|
||||
};
|
||||
|
||||
export function normaliseHelpLabel(value: string): string {
|
||||
return value
|
||||
.normalize('NFD')
|
||||
.replace(/[\u0300-\u036f]/g, '')
|
||||
.toLowerCase();
|
||||
}
|
||||
|
||||
export function formFieldGuidance(field: HelpField): {
|
||||
instruction: string;
|
||||
example?: string;
|
||||
} {
|
||||
const label = normaliseHelpLabel(field.label);
|
||||
if (field.type === 'password')
|
||||
return {
|
||||
instruction:
|
||||
'Introduza a palavra-passe desta conta. Use o controlo de mostrar palavra-passe apenas se precisar de conferir o que escreveu.',
|
||||
};
|
||||
if (field.type === 'file')
|
||||
return {
|
||||
instruction:
|
||||
'Escolha o ficheiro pedido neste campo. Confira o documento e os formatos indicados no formulário antes de o anexar.',
|
||||
};
|
||||
if (field.type === 'checkbox' || field.type === 'radio')
|
||||
return {
|
||||
instruction:
|
||||
'Leia a declaração ou opção apresentada. Seleccione-a apenas se corresponder à sua situação ou à autorização que pretende dar.',
|
||||
};
|
||||
if (/nuit/.test(label))
|
||||
return {
|
||||
instruction:
|
||||
'Transcreva o NUIT da pessoa ou entidade a que este formulário se refere. Confira-o no documento correspondente.',
|
||||
};
|
||||
if (
|
||||
/email|e-mail|correio electronico/.test(label) ||
|
||||
field.type === 'email'
|
||||
)
|
||||
return {
|
||||
instruction:
|
||||
'Indique um endereço de correio electrónico ao qual tenha acesso.',
|
||||
example: 'nome@exemplo.co.mz',
|
||||
};
|
||||
if (
|
||||
/telefone|telemovel|contacto telefonico/.test(label) ||
|
||||
field.type === 'tel'
|
||||
)
|
||||
return {
|
||||
instruction:
|
||||
'Indique o número de contacto e confira o indicativo do país quando o formulário o pedir.',
|
||||
};
|
||||
if (/moeda|currency/.test(label))
|
||||
return {
|
||||
instruction:
|
||||
'Escolha a moeda em que os montantes deste formulário estão expressos. Confira a coerência com os documentos e com os restantes valores.',
|
||||
};
|
||||
if (/residencia fiscal|regime fiscal|tipo de contribuinte/.test(label))
|
||||
return {
|
||||
instruction:
|
||||
'Escolha o enquadramento que corresponde à pessoa ou entidade em análise. Consulte as indicações e fontes apresentadas no formulário se precisar de esclarecer a opção.',
|
||||
};
|
||||
if (/volume de negocios|volume de negocio|facturacao/.test(label))
|
||||
return {
|
||||
instruction:
|
||||
'Indique o volume de negócios relativo ao período pedido, na moeda apresentada. Confira o período e a fonte do montante.',
|
||||
};
|
||||
if (/imposto.*liquidado|colecta/.test(label))
|
||||
return {
|
||||
instruction:
|
||||
'Indique o montante identificado neste campo, a partir do apuramento ou documento correspondente. Confira o exercício e a referência apresentados.',
|
||||
};
|
||||
if (
|
||||
/retenc|montante.*pago|pagamento.*efectuado|pec.*pago|ppc.*pago/.test(
|
||||
label,
|
||||
)
|
||||
)
|
||||
return {
|
||||
instruction:
|
||||
'Introduza apenas o montante documentado a que este campo se refere e confira o período. Distinga os valores já registados das estimativas ou hipóteses de tesouraria.',
|
||||
};
|
||||
if (/taxa|percentagem|percentual/.test(label))
|
||||
return {
|
||||
instruction:
|
||||
'Confira a unidade e o enquadramento indicados neste campo. Se for editável, introduza a percentagem correspondente ao pressuposto ou documento pedido; use os parâmetros apresentados pelo simulador quando forem fornecidos.',
|
||||
};
|
||||
if (/receita|vendas|rendimento/.test(label))
|
||||
return {
|
||||
instruction:
|
||||
'Indique o valor relativo ao período e à unidade pedidos. Quando se tratar de uma previsão, use o seu pressuposto de receitas e conserve a respectiva referência.',
|
||||
};
|
||||
if (/custo|despesa|encargo/.test(label))
|
||||
return {
|
||||
instruction:
|
||||
'Indique o custo ou despesa relativo ao período pedido. Confira se o campo pede valor unitário, mensal, anual ou total.',
|
||||
example:
|
||||
'Se o campo pedir um custo mensal, introduza o valor de um mês.',
|
||||
};
|
||||
if (
|
||||
/investimento|capital|financiamento|orcamento|montante|valor/.test(
|
||||
label,
|
||||
) &&
|
||||
field.type !== 'textarea'
|
||||
)
|
||||
return {
|
||||
instruction:
|
||||
'Indique o montante pedido, na moeda e unidade apresentadas. Distinga recursos disponíveis, necessidades de financiamento e valores previstos.',
|
||||
};
|
||||
if (
|
||||
/provincia|distrito|localidade|localizacao|territorio|posto administrativo/.test(
|
||||
label,
|
||||
)
|
||||
)
|
||||
return {
|
||||
instruction:
|
||||
'Escolha a localização correspondente ao investimento ou registo. Se existirem selecções dependentes, comece pela área mais abrangente e complete as opções seguintes.',
|
||||
};
|
||||
if (
|
||||
/exercicio|ano fiscal|periodo.*fiscal|inicio.*periodo|fim.*periodo/.test(
|
||||
label,
|
||||
)
|
||||
)
|
||||
return {
|
||||
instruction:
|
||||
'Indique a data ou o período a que a informação se refere. Confira a correspondência com os documentos e com os restantes campos deste exercício.',
|
||||
};
|
||||
if (['date', 'month', 'time', 'datetime-local'].includes(field.type))
|
||||
return {
|
||||
instruction:
|
||||
'Indique a data, o mês ou a hora pedidos neste campo, respeitando o formato apresentado. Confira a correspondência com o acontecimento ou prazo a que se refere.',
|
||||
};
|
||||
if (/referencia|fonte|fundamento/.test(label))
|
||||
return {
|
||||
instruction:
|
||||
'Identifique o documento, a origem da informação ou o motivo pedido. Use uma referência que permita recuperar e conferir o que declarou.',
|
||||
};
|
||||
if (/titulo|designacao|nome do projecto|nome do investimento/.test(label))
|
||||
return {
|
||||
instruction:
|
||||
'Escreva uma designação clara que permita reconhecer este investimento ou registo.',
|
||||
example: 'Unidade de transformação de produtos agrícolas',
|
||||
};
|
||||
if (field.type === 'select' || field.type === 'combobox')
|
||||
return {
|
||||
instruction:
|
||||
'Escolha a opção que corresponde à sua situação. As opções disponíveis e as instruções do formulário orientam esta escolha.',
|
||||
};
|
||||
if (field.type === 'number' || field.type === 'range')
|
||||
return {
|
||||
instruction:
|
||||
'Introduza a quantidade ou o valor pedido e confira a unidade apresentada junto do campo. Respeite os limites indicados no formulário.',
|
||||
};
|
||||
if (field.type === 'url')
|
||||
return {
|
||||
instruction:
|
||||
'Introduza a ligação completa para a página ou documento pedido.',
|
||||
example: 'https://exemplo.co.mz/documento',
|
||||
};
|
||||
if (field.type === 'textarea')
|
||||
return {
|
||||
instruction:
|
||||
'Explique a informação pedida neste campo de forma clara e concreta. Inclua os elementos necessários para compreender a sua declaração.',
|
||||
};
|
||||
return {
|
||||
instruction: `Preencha «${field.label}» com a informação correspondente à pessoa, entidade ou investimento deste formulário. Confira as indicações junto do campo.`,
|
||||
};
|
||||
}
|
||||
|
||||
const simulationSteps: Record<string, string> = {
|
||||
purpose:
|
||||
'Indique o que pretende preparar, o nível de detalhe e o percurso adequado à sua situação. As respostas adaptam os passos seguintes.',
|
||||
promoter:
|
||||
'Identifique a situação do promotor e complete apenas os elementos pedidos para o perfil escolhido.',
|
||||
identity:
|
||||
'Confira a identificação e os contactos da pessoa ou entidade a que esta preparação se refere.',
|
||||
project:
|
||||
'Descreva o negócio, a actividade e os objectivos. Reutilize os dados já disponíveis e complete a informação em falta.',
|
||||
market: 'Descreva os clientes, o mercado e os pressupostos de vendas. Indique as fontes disponíveis para sustentar as suas estimativas.',
|
||||
location:
|
||||
'Indique a localização e os recursos relevantes para o investimento. Complete as escolhas territoriais apresentadas.',
|
||||
team: 'Descreva a equipa e a forma prevista de executar o investimento, incluindo as responsabilidades e recursos pedidos.',
|
||||
investment:
|
||||
'Organize o investimento inicial e confira a moeda, a unidade e os montantes previstos.',
|
||||
financial:
|
||||
'Complete os montantes e os pressupostos de investimento e financiamento pedidos. Confira a moeda e o período de cada valor.',
|
||||
operating:
|
||||
'Preencha as estimativas de receitas e custos, respeitando a unidade e o período de cada campo.',
|
||||
cashflow:
|
||||
'Distribua os pressupostos de tesouraria pelos períodos pedidos e compare os cenários apresentados.',
|
||||
tax: 'Seleccione a operação e o enquadramento fiscal. Confira o contribuinte, o período, a moeda, os valores e as referências pedidos antes de calcular.',
|
||||
impact: 'Indique os postos de trabalho e os impactos previstos, distinguindo estimativas de informação já documentada.',
|
||||
opportunity:
|
||||
'Explique a necessidade de negócio e os elementos pedidos para preparar a oportunidade.',
|
||||
documents:
|
||||
'Confira os documentos pedidos, associe os disponíveis e identifique a informação que ainda falta.',
|
||||
scenarios:
|
||||
'Compare os cenários com base nos pressupostos preenchidos. Reveja as entradas antes de interpretar diferenças nos resultados.',
|
||||
procedures:
|
||||
'Consulte os procedimentos e os documentos apresentados para o seu contexto e identifique o que precisa de preparar.',
|
||||
review: 'Reveja as entradas, os resultados e as pendências. Se alterar pressupostos, recalcule quando o formulário o indicar; use a acção de guardar apenas quando pretender conservar as alterações.',
|
||||
};
|
||||
|
||||
export function simulationStepGuidance(step: string): string {
|
||||
return (
|
||||
simulationSteps[step] ??
|
||||
'Confira os dados pedidos neste passo, complete o que souber e consulte a ajuda de cada campo quando precisar.'
|
||||
);
|
||||
}
|
||||
|
||||
export function readFormHelpAutomatic(value: string | null): boolean {
|
||||
return value !== 'off';
|
||||
}
|
||||
|
||||
export function formHelpPlacement(
|
||||
rect: { left: number; top: number; bottom: number },
|
||||
width: number,
|
||||
height: number,
|
||||
) {
|
||||
const above = Math.max(0, rect.top - 84);
|
||||
const below = Math.max(0, height - rect.bottom - 16);
|
||||
return {
|
||||
side: rect.left > width / 2 ? ('left' as const) : ('right' as const),
|
||||
vertical: above > below ? ('top' as const) : ('bottom' as const),
|
||||
maxHeight: Math.max(
|
||||
96,
|
||||
Math.min(height * 0.45, Math.max(above, below) - 64),
|
||||
),
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user