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.
ElementoEquivale no ReactSem JavaScript
<semec-dialog>Dialog e AlertDialogNão abre. Use um link como gatilho para uma página com o mesmo conteúdo.
<semec-tabs>TabsA lista vira um sumário de links e todos os painéis aparecem.
<semec-combobox>ComboboxO <select> nativo funciona sozinho, com o mesmo name.
<semec-menu>DropdownMenuOs itens aparecem como uma lista de botões e links.
<semec-accordion>AccordionTodos 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-highlighted no item ativo do menu e na opção ativa do combobox; data-disabled nos 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;
  • hidden em painel ou popup fechado. Nada depende do CSS para esconder.

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çãoO que acontece
Enter ou Espaço no gatilhoAbre o diálogo com o foco no primeiro campo (no alerta, no Cancelar).
Tab e Shift+TabCirculam dentro do diálogo: o foco não sai para a página.
EscFecha. O foco volta ao gatilho.
Clique no fundoFecha, 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çãoO 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 EndPrimeira e última aba.
TabSai 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çãoO que acontece
DigitarAbre a lista e filtra.
↓ e ↑Abrem na opção escolhida e movem pela lista.
Home e EndPrimeira e última opção, com a lista aberta.
EnterEscolhe a opção ativa e fecha.
EscFecha a lista. Com a lista fechada, limpa a escolha e avisa "Escolha removida".
TabFecha e vai para o próximo campo.
<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çãoO que acontece
Enter, Espaço ou ↓ no botãoAbre com o foco no primeiro item.
↑ no botãoAbre com o foco no último item.
↑ e ↓Movem entre os itens, com volta ao início. Itens desabilitados ficam de fora.
Home, End e letrasPrimeiro, último e o próximo item que começa com a letra.
Enter ou EspaçoAtiva o item (botão ou link) e fecha.
EscFecha e devolve o foco ao botão.
TabFecha 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çãoO que acontece
Enter ou EspaçoAbre ou fecha o item.
↑ e ↓Vão para o item anterior ou o próximo, com volta.
Home e EndPrimeiro 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