Modelos de servidor

Parciais prontas do SEMEC Design System para PHP, Laravel, Symfony, Django e Flask: a tela sai com o mesmo HTML, o mesmo visual e a mesma acessibilidade dos componentes React.

O @semec/ds-css traz, além das classes, a pasta templates/ com onze parciais em quatro linguagens: PHP puro, Jinja2, Twig e Blade. Os nomes e os parâmetros são os mesmos nas quatro, e todas geram o HTML recomendado nas instruções para usar sem React, com rótulo, dica, erro e aria-* já ligados. Você passa os dados; a parcial cuida da marcação e do escape.

Parciais

ParcialO que gera
paginaLayout base: lang pt-BR, CSS, fontes, script do @semec/ds-elements, pular para o conteúdo, cabeçalho, <main id="conteudo"> e rodapé.
pular-para-o-conteudoLink "Pular para o conteúdo principal", primeiro elemento focável.
cabecalhoMarca, órgão, serviço e menu, com aria-current="page" no item atual.
rodapeSeções de links e a linha final.
campoinput, textarea ou select com rótulo, obrigatório, dica, erro, aria-describedby e aria-invalid.
comboboxCampo de escolha com filtro: um <select> dentro do <semec-combobox>, com rótulo, dica e erro.
radio-grupoGrupo de rádios em <fieldset> com <legend>, dica e erro.
checkboxUma caixa de marcação (declaração, aceite) ou um grupo delas em <fieldset>.
resumo-de-errosLista de links para os campos com erro, focada quando a página volta do envio.
alertaAviso info, success, warning ou danger, com o ícone e o role do Alert do kit.
botao<button> ou link com aparência de botão, nas variantes e tamanhos do Button; aceita os gatilhos do @semec/ds-elements em atributos.

Instalação

npm install @semec/ds-css @semec/ds-elements

Os modelos ficam em node_modules/@semec/ds-css/templates/. Copie a pasta da sua linguagem para o projeto e publique na pasta pública o dist/semec-ds.css do @semec/ds-css, o dist/fonts.css com a pasta dist/fonts/ do @semec/ds-tokens e o dist/semec-elements.js do @semec/ds-elements. O layout procura esses arquivos em /css/semec-ds.css, /css/fonts.css e /js/semec-elements.js; mude com os parâmetros css_href, fontes_href e elements_src.

SistemaPastaChamada
PHP purotemplates/phpsemec_render('campo', [...])
Django (django-jinja) e Flasktemplates/jinja{{ campo(id="cpf", ...) }}
Symfony, Slim (Twig)templates/twig{% include '@semec/campo.html.twig' with {...} only %}
Laravel (Blade)templates/blade@include('semec::campo', [...])

Ao atualizar o pacote, copie a pasta de novo: os modelos acompanham as classes da mesma versão do CSS.

PHP puro

Inclua o semec.php uma vez. semec_render() devolve o HTML da parcial; o conteúdo da página é uma função que imprime o HTML do seu app. Os exemplos desta página usam um único mapa campo → mensagem ($erros) para o resumo e para cada campo: vazio, nada aparece. Os quatro exemplos rodam como estão no teste dos modelos.

<?php
require __DIR__ . '/semec/semec.php'; // templates/php copiado para ./semec

// Um só mapa campo => mensagem serve ao resumo e a cada campo.
$dados = $_POST;
$erros = [];
if ($_SERVER['REQUEST_METHOD'] === 'POST' && trim($dados['cpf'] ?? '') === '') {
    $erros['cpf'] = 'Informe o CPF.';
}

echo semec_render('pagina', [
    'titulo' => 'Transferência escolar — SEMEC',
    'cabecalho' => [
        'marca_src' => '/img/marca.svg', // a marca oficial, servida pelo seu app
        'servico' => 'Matrícula e transferência',
        'nav' => [['href' => '/transferencia', 'texto' => 'Transferência', 'atual' => true]],
    ],
    'conteudo' => function () use ($erros, $dados) {
        echo '<h1 class="semec-heading semec-heading--1">Solicitar transferência</h1>';
        echo semec_render('resumo-de-erros', ['erros' => $erros]);
        echo '<form method="post" novalidate>';
        echo semec_render('campo', [
            'id' => 'cpf', 'rotulo' => 'CPF', 'obrigatorio' => true,
            'valor' => $dados['cpf'] ?? '', 'erro' => $erros['cpf'] ?? null,
            'dica' => 'Somente números.',
            'atributos' => ['inputmode' => 'numeric', 'maxlength' => 11],
        ]);
        echo semec_render('botao', ['texto' => 'Enviar', 'tipo' => 'submit']);
        echo '</form>';
    },
]);

A função do conteudo só enxerga as variáveis do use (...); se faltar uma, o PHP não avisa por causa do ??. O resumo também aceita a lista [['campo' => 'cpf', 'mensagem' => '…']]; item sem campo ou sem mensagem não vira link.

Django e Flask (Jinja2)

Copie templates/jinja para uma pasta semec/ dentro do diretório de templates. No Django, use o django-jinja (os arquivos .jinja vão para o motor Jinja2); no Flask, a pasta templates/, com o autoescape configurado (abaixo).

{% extends "semec/pagina.jinja" %}
{% from "semec/campo.jinja" import campo %}
{% from "semec/botao.jinja" import botao %}
{% from "semec/resumo-de-erros.jinja" import resumo_de_erros %}
{% block conteudo %}
  <h1 class="semec-heading semec-heading--1">Solicitar transferência</h1>
  {{ resumo_de_erros(erros=erros) }}
  <form method="post" novalidate>
    {{ campo(id="cpf", rotulo="CPF", obrigatorio=true, valor=dados.get("cpf"), erro=erros.get("cpf"), dica="Somente números.", atributos={"inputmode": "numeric", "maxlength": 11}) }}
    {{ botao(texto="Enviar", tipo="submit") }}
  </form>
{% endblock %}

A view passa erros (o mapa, vazio quando não há erro), dados ({} no primeiro acesso) e os parâmetros do layout, por exemplo render(request, "transferencia.jinja", {"titulo": …, "cabecalho": {…}, "erros": erros, "dados": dados}). No Django, ponha {{ csrf_input }} dentro do <form>. As macros têm o nome da parcial com _ no lugar de -. Funciona com StrictUndefined (use .get() para chave que pode faltar).

from jinja2 import select_autoescape

app.jinja_env.autoescape = select_autoescape(["html", "htm", "xml", "xhtml", "jinja"])

No Django com django-jinja, a extensão .jinja precisa estar no match_extension e o motor com "autoescape": True (o padrão do django-jinja).

Symfony e Slim (Twig)

Registre a pasta com o namespace semec: no Symfony, twig.paths no config/packages/twig.yaml; no Twig puro, $loader->addPath($pasta, 'semec').

{% extends '@semec/pagina.html.twig' %}
{% block conteudo %}
  <h1 class="semec-heading semec-heading--1">Solicitar transferência</h1>
  {% include '@semec/resumo-de-erros.html.twig' with {erros: erros} only %}
  <form method="post" novalidate>
    {% include '@semec/campo.html.twig' with {id: 'cpf', rotulo: 'CPF', obrigatorio: true, valor: dados.cpf|default(null), erro: erros.cpf|default(null), dica: 'Somente números.', atributos: {inputmode: 'numeric', maxlength: 11}} only %}
    {% include '@semec/botao.html.twig' with {texto: 'Enviar', tipo: 'submit'} only %}
  </form>
{% endblock %}

Use sempre only, para a parcial não receber as variáveis da página. As parciais funcionam com strict_variables ligado.

Laravel (Blade)

Copie templates/blade para resources/views/vendor/semec e registre o namespace no AppServiceProvider: View::addNamespace('semec', resource_path('views/vendor/semec')).

@extends('semec::pagina')
@section('conteudo')
  <h1 class="semec-heading semec-heading--1">Solicitar transferência</h1>
  {!! view('semec::resumo-de-erros', ['erros' => array_map(fn ($m) => $m[0], $errors->getMessages())])->render() !!}
  <form method="post" novalidate>
    @csrf
    {!! view('semec::campo', ['id' => 'cpf', 'rotulo' => 'CPF', 'obrigatorio' => true, 'valor' => old('cpf'), 'erro' => $errors->first('cpf') ?: null, 'dica' => 'Somente números.', 'atributos' => ['inputmode' => 'numeric', 'maxlength' => 11]])->render() !!}
    {!! view('semec::botao', ['texto' => 'Enviar', 'tipo' => 'submit'])->render() !!}
  </form>
@endsection

{!! view('semec::…', [...])->render() !!} renderiza a parcial isolada; o {!! !!} só imprime o HTML que a parcial já escapou. Não use @include com as parciais: ele passa todas as variáveis da view, e o $titulo do layout viraria o título do resumo de erros; um $id, $tipo ou $erro mudaria o campo.

Combobox, rádios e checkbox

  • combobox: o <semec-combobox> envolve só o <select>, então a lista abre colada ao campo, não depois da dica ou do erro. Sem JavaScript, o select funciona sozinho; com o @semec/ds-elements, vira campo com filtro e o campo de busca assume o id (o link do resumo é #id).
  • radio-grupo e checkbox com opcoes: <fieldset> com <legend>, dica e erro ligados ao grupo. O primeiro controle leva o id (o link do resumo é #id); os outros, id-2, id-3…
  • checkbox sem opcoes: uma caixa só, com o rótulo ao lado (declaração, aceite dos termos).

Atributos extras

campo e botao aceitam atributos, um mapa nome → valor: os gatilhos do @semec/ds-elements (data-semec-dialog-open, data-semec-menu-trigger…), aria-describedby e form num botão, inputmode, maxlength, pattern e rows num campo. Só valem nomes data-*, aria-* e uma lista de atributos de formulário; outros (on*, style, class, href) são ignorados, e o valor sai escapado. true gera o atributo sem valor.

Parâmetros

Os parâmetros são os mesmos nas quatro linguagens. Ausente, nulo ou vazio usa o padrão. Valor fora da lista (variante, tamanho, tipo) também volta ao padrão, então nenhum parâmetro vira classe ou atributo arbitrário. Os parâmetros do campo:

ParâmetroO que faz
idid do controle. A dica vira <id>-hint e o erro, <id>-error.
rotuloTexto do <label>.
tipotext (padrão), email, tel, number, date, password, url, search, textarea ou select.
valorValor atual: value, conteúdo do textarea ou opção selecionada.
obrigatoriorequired no controle e * visual (aria-hidden) no rótulo.
dicaDica ligada por aria-describedby. Com erro, a dica sai, como no FormField do kit.
erroMensagem de erro: marca aria-invalid="true" e entra no aria-describedby.
opcoes, opcao_vaziaOpções do select ({valor, texto}) e a primeira opção vazia ("Selecione").
nome, autocomplete, desabilitadoname (padrão: o id), autocomplete e disabled.
atributosMapa de atributos extras: inputmode, maxlength, pattern, rows, placeholder, data-* e aria-*. Outros nomes (on*, style, class, href) são ignorados; o valor sai escapado.

A tabela completa, com todas as parciais, tipos e padrões, está no README dos modelos.

Segurança

  • Toda saída é escapada: htmlspecialchars com ENT_QUOTES no PHP, autoescape de HTML no Jinja, no Twig e no Blade. O Jinja e o Twig ligam o autoescape dentro de cada parcial, mesmo que o projeto o tenha desligado. Isso não protege a sua tela: no Flask, configure o autoescape para .jinja (veja acima).
  • Nenhum parâmetro aceita HTML. O conteúdo da página entra pelo bloco do template, escrito por você.
  • Endereços (href, marca_src) são escapados, mas não filtrados. Não use como link uma URL digitada pelo usuário sem validar o esquema.

Comportamento e acessibilidade

  • O resumo de erros recebe autofocus: quando o formulário volta do servidor com erros, o foco vai para ele, como no ErrorSummary do kit. Em envio por JavaScript, chame focus() no resumo depois de inseri-lo.
  • Com erro, a mensagem substitui a dica e o campo recebe aria-invalid="true". Mostre os erros no envio, não enquanto a pessoa digita (veja Mensagens de erro).
  • O layout carrega o @semec/ds-elements como módulo. Os elementos <semec-*> (diálogo, abas, combobox, menu e acordeão) funcionam dentro do conteúdo sem outra configuração.

Como é testado

Cada parcial é renderizada nas quatro linguagens com os mesmos dados e comparada com um único HTML de referência. O mesmo teste roda o axe-core no Chromium (zero violações), confere cada classe contra a lista oficial do @semec/ds-css, injeta <script> e aspas em todos os textos e confere a tabela de parâmetros. Os exemplos desta página rodam como estão (com e sem erro), e um app Flask de verdade confirma a configuração de autoescape. Para rodar no monorepo:

npm run build:pacotes
npm run test:modelos

O teste usa PHP 8.2+, Composer e Python 3 da máquina ou, sem eles, o Docker.

Para saber mais