Análise de modal e navegação — issue #38¶
Escopo e versões¶
Análise estática dos submodules fixados pelo projeto: Bootstrap v5.3.8 e
@govbr-ds/core v3.7.0. Nenhum componente foi alterado nesta análise. As
referências abaixo são os fontes dessas tags, não uma promessa de equivalência
visual ou funcional.
Resumo executivo¶
Área |
Diferença principal |
Recomendação |
|---|---|---|
Modal |
Bootstrap implementa o ciclo de vida completo do diálogo; no GOV.BR DS o modal visual e a abertura pelo scrim são peças separadas, com outro markup e outro controlador. |
Manter não suportado até uma issue própria comparar e testar o markup. Não substituir o JavaScript Bootstrap. |
Navbar e menu |
Bootstrap oferece navbar responsiva, Collapse e Dropdown independentes. O GOV.BR DS combina Header, Menu lateral/contextual, scrim e comportamentos próprios. |
Manter Header/Menu
complexos não
suportados. Avaliar
separadamente um
subconjunto simples de
|
Uma camada CSS pode mudar aparência, mas não converte classes, estrutura,
semântica ARIA, ordem de foco ou comportamento. Para modal e navegação complexa,
“reutilizar o plugin Bootstrap” é a opção de menor risco; substituir o plugin
ou exigir markup .br-* mudaria o contrato deste pacote.
Modal¶
Contratos comparados¶
Contrato |
Bootstrap 5.3.8 |
GOV.BR DS 3.7.0 |
Consequência |
|---|---|---|---|
Markup |
|
|
Regras de layout e
seletores dos dois
componentes não se
aplicam
intercambiavelmente.
Traduzir a árvore
Bootstrap em classes
|
CSS |
O overlay, posicionamento,
responsividade, animação, overflow e
z-index pertencem ao |
|
Um tema CSS-only pode adaptar o painel, mas não cria o wrapper/scrim exigido pelo GOV.BR DS. |
JavaScript |
|
|
A aparência pode ser separada do comportamento, mas não se deve afirmar compatibilidade sem validar cada comportamento Bootstrap e cada modo de scrim. |
Acessibilidade |
O Bootstrap aplica |
Exemplos GOV.BR DS
declaram
|
Atributos ARIA semelhantes não provam paridade. Foco inicial, contenção de Tab, retorno de foco, fechamento e conteúdo de fundo precisam de testes com teclado e axe. |
Decisão¶
Não suportar modal nesta versão. Preservar o plugin Bootstrap é tecnicamente
possível e é a recomendação para aplicações existentes, mas ainda não há fixture
que prove que o CSS adaptado cobre os estados do Bootstrap sem quebrar overlay,
rolagem, foco, transições e conteúdo longo. Não implementar conversão automática
para .br-modal/.br-scrim, nem substituir o plugin por BRModal/Scrim.
Critérios para uma futura issue de implementação¶
Fixture com markup Bootstrap puro, nome acessível, título, descrição, botão de fechar, conteúdo longo, dois diálogos sequenciais e acionador externo.
Cobrir modal padrão e backdrop estático; abrir/fechar por API e acionador; Escape configurado; clique no backdrop; eventos do ciclo de vida; rolagem; foco inicial, contenção por Tab/Shift+Tab e retorno ao acionador.
Axe-core com modal fechado e aberto; validar nome do diálogo, foco visível, conteúdo de fundo e operação integral sem mouse.
Capturas desktop/mobile para tamanhos e conteúdo com rolagem; validar também redução de movimento e ausência de regressão nas animações Bootstrap.
Limitar o suporte às opções testadas; manter as opções e eventos públicos do plugin Bootstrap documentados. Se for necessário markup
.br-*ou JavaScript novo, tratar como integração diferente, não como adaptação compatível.
Atualização (issue #67)¶
O <dsgovbr-modal> (dsgovbr-bootstrapped-componentes.js) segue a recomendação
acima: monta o markup do Bootstrap e reusa o plugin Modal (foco, Escape, backdrop
e retorno ao acionador continuam sendo os do Bootstrap). Cobre, em
tests/browser/modal.spec.js, modal padrão e estático, abrir/fechar por API e
acionador, Escape, clique no backdrop, evento dsgovbr:modal, rolagem, contenção
de foco, retorno ao acionador e axe com o modal aberto, no claro e no escuro. A
decisão de não converter para .br-modal/.br-scrim permanece, e o suporte
vale só para as opções testadas (tamanho, rolagem, centralizado e
estatico).
Custo/risco: alto. São muitos estados globais e caminhos assíncronos, e uma diferença de foco ou rolagem pode tornar o diálogo inacessível mesmo quando a captura está visualmente correta. Requer suíte de navegador estável antes de qualquer anúncio de suporte.
Navbar, dropdown, header e menu¶
“Navegação” não é um único componente equivalente. A comparação abaixo separa navbar/collapse, dropdown simples e menu institucional/complexo.
Contrato |
Bootstrap 5.3.8 |
GOV.BR DS 3.7.0 |
Consequência |
|---|---|---|---|
Navbar responsiva |
|
|
|
Collapse |
Plugin |
Menu lateral/contextual controla scrim, classes ativas, foco inicial, fechamento por Escape, navegação por setas e submenus. |
Manter Collapse é viável para um navbar Bootstrap, mas não implementa o contrato do menu GOV.BR DS. |
Dropdown |
Plugin |
Dropdown simples no
Header tem
acionadores e
listeners próprios;
pastas e side menus
do |
Uma adaptação visual de dropdown simples pode preservar o plugin Bootstrap, mas não deve ser anunciada como compatibilidade com menus hierárquicos GOV.BR DS. |
Semântica/teclado |
Usa elementos e relações
Bootstrap, |
|
Mudar roles ou
teclado tem risco
alto: roles
|
Comportamentos do Header |
Sem equivalente nativo em Navbar: busca que abre/foca e fecha, sticky/compact, login/logout e dropdown contextual são específicos. |
|
O componente deve ser avaliado por função. Não copiar só o visual do Header e declarar equivalência. |
Decisão por subconjunto¶
``.navbar`` simples: candidato a adaptação visual limitada em issue própria, com a estrutura oficial Bootstrap mantida e os plugins Bootstrap carregados. Excluir busca, identidade institucional, menu push, scrim e qualquer promessa de equivalência com
.br-header/.br-menu.``.dropdown`` simples: candidato independente, limitado a um acionador e uma lista plana, com Popper e plugin Bootstrap preservados. Excluir pastas hierárquicas, side-menu, menu contextual, cabeçalho de funcionalidades e comportamento do Header GOV.BR DS.
``.br-header`` e ``.br-menu``/navegação hierárquica: não suportar como adaptação Bootstrap neste momento. Exigem estrutura, controle de foco, semântica e interações específicas; integração futura teria que ser explicitamente outro contrato ou componente.
Critérios para issues futuras¶
Para navbar simples, testar breakpoints Bootstrap existentes, estado expandido,
atributos ARIA, Tab/Shift+Tab, links ativos/desabilitados e axe-core em desktop e
mobile. Para dropdown simples, testar click/Enter/Space, setas, Escape, foco após
fechar, menu perto das bordas/scroll/RTL e axe-core. Capturas visuais não
substituem essas verificações. Não introduzir roles menu, menubar ou tree
sem implementar e testar integralmente o modelo de teclado correspondente.
Custo/risco: médio para navbar estática; médio para dropdown plano; alto para header/menu GOV.BR DS ou hierarquia. Popper, breakpoints, foco, RTL e papéis ARIA ampliam a matriz de regressão. Manter cada contrato em issue separada reduz risco e permite rejeitar subcomponentes sem bloquear outros.
Referências upstream fixadas¶
Bootstrap v5.3.8¶
modal.js — ciclo de vida, foco, backdrop, acionadores, retorno de foco e Escape.
focustrap.js — contenção de foco.
_modal.scss — estrutura visual e estados.
collapse.js — acionadores,
aria-expandede transições de Collapse.dropdown.js — Popper, estados e teclado.
_navbar.scss e _dropdown.scss — estruturas, breakpoints e estados visuais.
GOV.BR DS @govbr-ds/core v3.7.0¶
`modal.pug<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/components/modal/modal.pug>`__ e`modal.js<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/components/modal/modal.js>`__ — anatomia visual e inicialização do scrim pelo componente Modal.`_mixins.scss<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/components/modal/_mixins.scss>`__ — tamanhos, cabeçalho, corpo, rodapé e scroll.`scrim.js<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/components/scrim/scrim.js>`__ e`behavior/scrim.js<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/partial/js/behavior/scrim.js>`__ — duas APIs de scrim e seus limites de foco/fechamento.`menu.pug<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/components/menu/menu.pug>`__,`menu.js<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/components/menu/menu.js>`__ e`menu/_mixins.scss<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/components/menu/_mixins.scss>`__ — painel, submenus, roles ARIA e navegação por teclado.`header.pug<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/components/header/header.pug>`__ e`header.js<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/components/header/header.js>`__ — busca, dropdowns, sticky e acionador de menu.`utilities/_dropdown.scss<https://gitlab.com/govbr-ds/bibliotecas/javascript/govbr-ds-core/-/blob/v3.7.0/src/partial/scss/utilities/_dropdown.scss>`__ — regras utilitárias do dropdown GOV.BR DS.
Estado da matriz¶
A matriz em Requisitos §6 permanece conservadora: modal, Header/Menu complexo e navegação hierárquica continuam não suportados. Navbar simples e dropdown plano são possibilidades de avaliação independente, não itens suportados nem compromisso de implementação.