Web Components
Diálogo, abas, combobox, menu e acordeão com a mesma acessibilidade do kit React, em qualquer página HTML, PHP, Django ou Flask.
O @semec/ds-css dá o visual. Para os componentes que precisam de comportamento (abrir, fechar, mover o foco, navegar pelo teclado), existe o @semec/ds-elements: cinco elementos HTML próprios que você escreve em volta do HTML com as classes .semec-*. Veja também Usar sem React.
Como funciona
- Sem shadow DOM. O HTML continua seu: o CSS do app, os testes e as ferramentas de acessibilidade enxergam tudo.
- Aprimoramento progressivo. Sem JavaScript, o conteúdo continua legível. O elemento só acrescenta comportamento e atributos ARIA.
- Mesmo comportamento do kit. Teclado e foco seguem os padrões WAI-ARIA APG, comparados com os componentes React nos mesmos cenários.
- Sem dependências. Um arquivo de cerca de 29 kB (9 kB com gzip), somente ESM.
| Elemento | Equivale no React | Sem JavaScript |
|---|---|---|
<semec-dialog> | Dialog e AlertDialog | Não abre. Use um link como gatilho para uma página com o mesmo conteúdo. |
<semec-tabs> | Tabs | A lista vira um sumário de links e todos os painéis aparecem. |
<semec-combobox> | Combobox | O <select> nativo funciona sozinho, com o mesmo name. |
<semec-menu> | DropdownMenu | Os itens aparecem como uma lista de botões e links. |
<semec-accordion> | Accordion | Todos os painéis aparecem abertos. |
Instalar
Com npm
npm install @semec/ds-elements "@semec/ds-css@^1.1.0"import "@semec/ds-tokens/fonts.css";
import "@semec/ds-css/index.css";
import "@semec/ds-elements/auto";O auto registra todos os elementos ao importar. Para registrar quando quiser, use import { defineSemecElements } from "@semec/ds-elements" e chame defineSemecElements(). Chamar duas vezes, ou carregar o arquivo do CDN junto, não quebra.
Com CDN ou arquivo copiado
O bloco completo, com versão fixa em cada arquivo: as fontes, o CSS (a partir da 1.1.0) e o script. Não use uma faixa como @1: o integrity vale para um arquivo só.
<link rel="stylesheet" crossorigin="anonymous"
href="https://cdn.jsdelivr.net/npm/@semec/ds-tokens@1.0.0/dist/fonts.css"
integrity="sha384-JPaBLIHnh0Pteb6nPfiQvklhUDnfvln4jCKfD1ASorqT7xYuyugBAs5ZvE32NxXb">
<link rel="stylesheet" crossorigin="anonymous"
href="https://cdn.jsdelivr.net/npm/@semec/ds-css@1.1.1/dist/semec-ds.css"
integrity="sha384-fidW0owPdsWVRx89cAJc3pdox6KepexJueUrreuoNW1MNXGhmRfddyuPv/zT6v/G">
<script type="module" crossorigin="anonymous"
src="https://cdn.jsdelivr.net/npm/@semec/ds-elements@1.0.0/dist/semec-elements.js"
integrity="sha384-X3yHwotBgX64Ja/D0NFwawT1nbyBHXFZKqk2K0M6IK0OLeMfY2fKRZP0eh0VWCco"></script>Estados
Os elementos põem os mesmos atributos que o Radix põe no kit React, e o @semec/ds-css estiliza por eles. Não crie classes de estado próprias:
data-state="open"ou"closed"no diálogo, no menu, na lista do combobox e no acordeão;"active"ou"inactive"nas abas;data-highlightedno item ativo do menu e na opção ativa do combobox;data-disablednos desabilitados;aria-selected="true"na aba ativa e na opção ativa do combobox (a que o leitor de tela anuncia);data-state="checked"na opção escolhida;hiddenem painel ou popup fechado. Nada depende do CSS para esconder.
Diálogo
Sem JavaScript, o diálogo não abre. Por isso o gatilho padrão é um link para uma página com o mesmo conteúdo: com JavaScript, ele abre o diálogo e passa a se comportar como botão.
<a class="semec-btn" href="/contato/editar"
data-semec-dialog-open="editar-contato">Editar contato</a>
<semec-dialog id="editar-contato">
<dialog class="semec-dialog">
<div class="semec-dialog__header">
<h2 class="semec-dialog__title">Editar contato</h2>
<p class="semec-dialog__description">Altere o telefone.</p>
</div>
<!-- campos -->
<div class="semec-dialog__footer">
<button type="button" class="semec-btn semec-btn--outline"
data-semec-dialog-close>Cancelar</button>
<button type="button" class="semec-btn"
data-semec-dialog-close>Salvar</button>
</div>
<!-- O X vem do CSS: sem <svg> dentro do botão. -->
<button type="button" class="semec-dialog__close"
data-semec-dialog-close><span class="semec-sr-only">Fechar</span></button>
</dialog>
</semec-dialog>Para confirmar uma ação destrutiva, acrescente alert ao <semec-dialog>, use class="semec-dialog semec-dialog--alert" no <dialog> (o elemento põe o modificador se faltar) e marque o botão de cancelar com data-semec-dialog-cancel: ele recebe o foco ao abrir e o clique no fundo não fecha.
Confirmar antes de enviar
O gatilho é o próprio botão de envio. Sem JavaScript, ele envia o formulário direto; com JavaScript, abre o diálogo, e o "Confirmar" dentro do formulário envia.
<form method="post" action="/rascunhos/12/excluir">
<button type="submit" class="semec-btn semec-btn--destructive"
data-semec-dialog-open="confirmar-exclusao">Excluir rascunho</button>
<semec-dialog id="confirmar-exclusao" alert>
<dialog class="semec-dialog semec-dialog--alert">
<div class="semec-dialog__header">
<h2 class="semec-dialog__title">Excluir o rascunho?</h2>
<p class="semec-dialog__description">Não pode ser desfeito.</p>
</div>
<div class="semec-dialog__footer">
<button type="button" class="semec-btn semec-btn--outline"
data-semec-dialog-cancel>Cancelar</button>
<button type="submit" class="semec-btn semec-btn--destructive"
>Confirmar</button>
</div>
</dialog>
</semec-dialog>
</form>| Tecla ou ação | O que acontece |
|---|---|
| Enter ou Espaço no gatilho | Abre o diálogo com o foco no primeiro campo (no alerta, no Cancelar). |
| Tab e Shift+Tab | Circulam dentro do diálogo: o foco não sai para a página. |
| Esc | Fecha. O foco volta ao gatilho. |
| Clique no fundo | Fecha, menos no alerta. |
O título e a descrição viram aria-labelledby e aria-describedby, a página para de rolar enquanto o diálogo está aberto e os eventos semec-open e semec-close avisam o seu código.
Abas
<semec-tabs class="semec-tabs">
<nav class="semec-tabs__list" aria-label="Seções da matrícula">
<a class="semec-tabs__trigger" href="#dados">Dados</a>
<a class="semec-tabs__trigger" href="#documentos">Documentos</a>
</nav>
<section class="semec-tabs__panel" id="dados">…</section>
<section class="semec-tabs__panel" id="documentos">…</section>
</semec-tabs>| Tecla ou ação | O que acontece |
|---|---|
| ← e → | Vão para a aba anterior ou a próxima, com volta ao início, e já mostram o painel. |
| ↑ e ↓ | O mesmo, com orientation="vertical". |
| Home e End | Primeira e última aba. |
| Tab | Sai da lista e vai para o painel aberto. |
Use o atributo value para escolher a aba aberta e o evento semec-change para saber quando ela muda. Um link da página para um painel inativo, ou para um campo dentro dele (como o resumo de erros), ativa a aba antes de navegar.
Combobox
<label class="semec-label" for="escola">Escola</label>
<semec-combobox class="semec-combobox">
<select class="semec-field" id="escola" name="escola">
<option value="">Selecione a escola</option>
<option value="rio-madeira">EMEF Rio Madeira</option>
<option value="sao-sebastiao">EMEF São Sebastião</option>
</select>
</semec-combobox>O <semec-combobox> envolve só o <select>: rótulo, dica e erro ficam fora dele. O <select> é a fonte das opções e continua sendo o valor enviado no formulário. Com JavaScript, ele fica escondido e aparece um campo de busca com o mesmo id, rótulo, dica e estado de erro. Digitar filtra sem diferença de acento ("sao" encontra "São") e o leitor de tela ouve quantos resultados sobraram. Um texto que não virou escolha deixa o campo inválido ("Escolha uma opção da lista."), e o formulário não é enviado com ele. Mudanças no <select> depois de carregar (opções novas, disabled, aria-invalid) chegam ao campo.
| Tecla ou ação | O que acontece |
|---|---|
| Digitar | Abre a lista e filtra. |
| ↓ e ↑ | Abrem na opção escolhida e movem pela lista. |
| Home e End | Primeira e última opção, com a lista aberta. |
| Enter | Escolhe a opção ativa e fecha. |
| Esc | Fecha a lista. Com a lista fechada, limpa a escolha e avisa "Escolha removida". |
| Tab | Fecha e vai para o próximo campo. |
Menu
<semec-menu>
<button type="button" class="semec-btn semec-btn--outline"
data-semec-menu-trigger>Ações</button>
<div class="semec-menu">
<button type="button" class="semec-menu__item">Editar</button>
<hr class="semec-menu__separator">
<a class="semec-menu__item" href="/arquivar">Arquivar</a>
</div>
</semec-menu>| Tecla ou ação | O que acontece |
|---|---|
| Enter, Espaço ou ↓ no botão | Abre com o foco no primeiro item. |
| ↑ no botão | Abre com o foco no último item. |
| ↑ e ↓ | Movem entre os itens, com volta ao início. Itens desabilitados ficam de fora. |
| Home, End e letras | Primeiro, último e o próximo item que começa com a letra. |
| Enter ou Espaço | Ativa o item (botão ou link) e fecha. |
| Esc | Fecha e devolve o foco ao botão. |
| Tab | Fecha e segue para o próximo elemento. |
O evento semec-select diz qual item foi escolhido. Chame event.preventDefault() para manter o menu aberto.
Acordeão
<semec-accordion class="semec-accordion" type="single" collapsible>
<div class="semec-accordion__item">
<h3 class="semec-accordion__header">
<button type="button" class="semec-accordion__trigger">
Quem pode pedir transferência?
</button>
</h3>
<div class="semec-accordion__panel">
<p>O responsável legal pelo estudante.</p>
</div>
</div>
</semec-accordion>| Tecla ou ação | O que acontece |
|---|---|
| Enter ou Espaço | Abre ou fecha o item. |
| ↑ e ↓ | Vão para o item anterior ou o próximo, com volta. |
| Home e End | Primeiro e último item. |
Com type="single", abrir um item fecha o outro; collapsible deixa fechar o que está aberto. Com type="multiple", vários ficam abertos. Escolha o nível do heading pela estrutura da página.
Acessibilidade e limites
Cada elemento é testado em navegador real (Chromium, Firefox e WebKit): teclado completo, foco, atributos ARIA e axe-core sem violações em cada estado aberto, com e sem JavaScript. Onde o Radix difere do padrão APG, os elementos seguem o APG: no menu, ↑ abre no último item, as setas voltam ao início e Tab fecha; o combobox é um campo editável.
- O combobox ainda não mostra grupos (
<optgroup>). - O menu não tem submenus nem itens de marcar.
- Os testes automáticos não substituem um leitor de tela: confira os fluxos críticos com NVDA ou VoiceOver antes de publicar.
Para saber mais
- README do @semec/ds-elements, com atributos, eventos e o HTML completo de cada elemento.
- Decisão: ADR-029 (Web Components em light DOM sem dependências).