Luego SVG {% svg %}

Extensão Nunjucks para renderizar ícones SVG inline via <use xlink:href>, apontando para um sprite de <symbol>s (ex: gerado com gulp-svgstore).

🚀 Versão 2.1.0

• ✅ viewBox automático: lido do <symbol> correspondente no sprite (options.symbolsPath) e incluído no <svg> gerado — necessário para o navegador escalar width/height corretamente com <use>

Versão 2.0.0

• ✅ HTML determinístico: aria-labelledby/<title id> derivados do conteúdo (sha1), não mais aleatórios
• ✅ Segurança: escape de todos os atributos e do texto do <title>; sem re-render Nunjucks; attr validado
• ✅ Config injetável pelo construtor; erros viram comentário HTML (o build não quebra)
• ✅ Sem Emmet: dependência @emmetio/expand-abbreviation removida
• ✅ Testes: npm test (node:test)

Breaking changes: veja o CHANGELOG.

Instalação

npm i @luego/nunjucks-luego-svg-extension
# ou
yarn add @luego/nunjucks-luego-svg-extension

Requer Node >= 18.

Setup

const NunjucksSVGExtension = require('@luego/nunjucks-luego-svg-extension');

const SVGExtensionHelper = new NunjucksSVGExtension(nunjucks, nunjucksEnv, {
    config: require('./luego.config.js'),      // usa a seção "svg" (opcional)
    symbolsPath: 'src/.tmp/svg-symbols.svg',   // sprite gerado pelo build:svg-symbols (default)
});
nunjucksEnv.addExtension('SVGExtension', SVGExtensionHelper);

Defaults (sobrescrevíveis pela seção svg do config): width: '50rem', height: 'auto', title: '', attr: ''.

O viewBox de cada ícone é lido automaticamente do <symbol> correspondente em symbolsPath (cache invalidado quando o sprite muda). Também pode ser passado manualmente: {% svg 'icone', viewBox='0 0 24 24' %}.

Como usar

{% svg 'logo-luego' %}
{% svg 'logo-luego', width='220', height='151', class='logo-luego', title='Luego' %}
{% svg 'seta', attr='[data-aos="fade"][hidden]' %}

Resultado:

<svg class="icon-logo-luego" viewBox="0 0 220 151" height="151" width="220" aria-labelledby="svg-title-ab12cd34">
    <title id="svg-title-ab12cd34">Luego</title>
    <use xlink:href="#svg-logo-luego"></use>
</svg>

Atributos

| Atributo | Tipo | Default | Descrição | | ------ | ---- | ------- | ----------- | | src | string | — obrigatório — | Nome do símbolo (vira #svg-{src}) | | class | string | slug do src | Classe CSS (recebe prefixo icon- na primeira) | | width | string | 50rem | Largura | | height | string | auto | Altura | | title | string | '' | Acessibilidade: gera <title> + aria-labelledby | | attr | string | '' | Atributos extras: [data-x="1"][hidden] |

Observações

• Com title, o id do <title> é determinístico por src|title — o mesmo ícone com o mesmo title gera sempre o mesmo id
• Erros (src ausente, attr inválido) viram <!-- {% svg %} error: ... --> sem quebrar o build