@fc/html-formatado
Vocabulário e sanitização do HTML formatado — o subconjunto de HTML que comunicados e documentos legais da Fábrica de Cálculos podem conter.
O pacote reúne, num só lugar, o que antes vivia espalhado: a lista de tags e atributos aceitos, os normalizadores de estilo, cor e recuo, e a função que sanitiza.
O que exporta
| Export | Para que serve |
|---|---|
sanitizarHtmlFormatado(html) | Devolve o HTML restringido ao vocabulário aceito |
TAGS_HTML_FORMATADO_PERMITIDAS e demais catálogos | A allowlist em forma de dado |
LIMITES_CARACTERES_HTML_FORMATADO | Limites comuns de gravação e leitura defensiva |
normalizarEstiloHtmlFormatado, normalizarCorHtmlFormatado | Normalizam style e cor para a forma canônica |
nivelRecuoHtmlFormatado, comprimentoEmPixelsHtmlFormatado | Convertem recuo de origem em degraus fixos |
Isomórfico por construção
sanitizarHtmlFormatado não usa document nem window: roda igual no servidor e no navegador, e produz os mesmos bytes nos dois. É o que permite renderizar conteúdo em SSR e reidratar no cliente sem divergência.
A garantia é verificada, não prometida: o mesmo conjunto de testes roda em dois ambientes, um sem DOM e outro com, e a saída é comparada com um conjunto de referência congelado. Casos adversariais adicionais remontam a saída como o navegador faz com innerHTML e voltam a conferir tags, atributos, destinos e estilos do DOM resultante.
Limites de conteúdo
O contrato comum permite até 500 mil caracteres de HTML, incluindo a marcação, na gravação. O conteúdo é rejeitado, nunca truncado, se ultrapassar o teto antes ou depois da normalização canônica. Na leitura, 1 milhão de caracteres forma um teto defensivo mais amplo para acomodar conteúdo histórico; acima dele, a interface mostra um aviso seguro sem interpretar o HTML.
Vocabulário
Aceita a, blockquote, br, code, div, em, h1, h2, h3, hr, kbd, li, mark, ol, p, pre, s, span, strong, sub, sup, u e ul. De atributo, apenas style — e href, target e rel em a, com esquema restrito a http, https e mailto. Só a, blockquote, div, h1–h3, p e span levam style; as demais tags — kbd (tecla de atalho) entre elas — não aceitam atributo algum.
Em style, sobrevivem apenas alinhamento de texto, cor, cor de fundo e recuo à esquerda em degraus fixos. Cor é normalizada para hexadecimal de seis dígitos; recuo, para múltiplos de 2,5 rem.
Tags fora da lista perdem a tag e mantêm o texto. Elementos interativos e de script perdem também o conteúdo.
Uso
ts
import { sanitizarHtmlFormatado } from '@fc/html-formatado/sanitizarHtmlFormatado'
sanitizarHtmlFormatado('<p onclick="x()">Olá <b>mundo</b></p>')
// → '<p>Olá <strong>mundo</strong></p>'Como consumir
O pacote não tem barrel raiz: @fc/html-formatado não resolve. Cada módulo é publicado por subpath, e o consumidor importa o arquivo que declara o símbolo.
| Subpath | O que exporta |
|---|---|
@fc/html-formatado/sanitizarHtmlFormatado | sanitizarHtmlFormatado |
@fc/html-formatado/constantes | TAGS_HTML_FORMATADO_PERMITIDAS, TAGS_HTML_FORMATADO_DESCARTADAS, TAGS_HTML_FORMATADO_COM_RECUO, ALIASES_TAGS_HTML_FORMATADO, ATRIBUTOS_HTML_FORMATADO_PERMITIDOS, ALINHAMENTOS_HTML_FORMATADO_PERMITIDOS, ESQUEMAS_LINK_HTML_FORMATADO_PERMITIDOS, ORDEM_ESTILOS_HTML_FORMATADO, RECUO_HTML_FORMATADO, LIMITES_CARACTERES_HTML_FORMATADO |
@fc/html-formatado/normalizadores | normalizarEstiloHtmlFormatado, normalizarCorHtmlFormatado |
@fc/html-formatado/recuo | nivelRecuoHtmlFormatado |
@fc/html-formatado/comprimento | comprimentoEmPixelsHtmlFormatado |
@fc/html-formatado/hrefHtmlFormatadoSeguro | hrefHtmlFormatadoSeguro |
@fc/html-formatado/tagCanonica | tagCanonica |
tagCanonica resolve uma tag de entrada na tag que a allowlist reconhece (b → strong, font → span); é publicada porque a colagem do editor de HTML formatado faz a mesma pergunta no navegador. A pasta sanitizar-html-formatado/ (escape, montagem de atributos) é detalhe de implementação do motor e não é publicada.
Estabilidade da saída
A função é idempotente: sanitizar o que já foi sanitizado não altera nada. É essa propriedade que permite aplicá-la tanto na gravação quanto na exibição sem que o conteúdo mude de forma a cada passagem — o que importa em documentos cuja versão publicada é registro permanente.