Convenções de API
Os componentes priorizam HTML, DOM e padrões WAI-ARIA antes de criar contratos próprios. Em releases não-major, a evolução é aditiva: uma API publicada não muda de nome, tipo ou comportamento.
Vocabulário
| Contexto | Convenção | Exemplos |
|---|---|---|
| Estado booleano | adjetivo sem is ou has | active, open, inline |
| Variação funcional | variant | variant="primary" |
| Contexto visual | colorMode | color-mode="dark" |
| Feedback | feedbackState | feedback-state="danger" |
| Direção | orientation | orientation="vertical" |
| Índice técnico | zero-based | index={0} |
| Página apresentada | one-based | current-page={1} |
Propriedades JavaScript seguem os nomes IDL, como readOnly, maxLength, ariaHasPopup e tabIndex. Seus atributos seguem a grafia HTML: readonly, maxlength, aria-haspopup e tabindex.
Eventos e métodos
Eventos nativos são usados quando possuem a mesma semântica da plataforma. Eventos de domínio usam camelCase no formato brComponenteAção; navegação interceptável usa brNavigate. Todo evento customizado novo documenta detail, propagação, composição e cancelamento.
Métodos usam verbos em camelCase e não repetem uma propriedade sem necessidade. Recursos nativos como focus(), validação, dialog e popover são preferidos quando preservam o contrato do componente.
Evolução compatível
Quando um nome melhor é introduzido, a API anterior continua operacional e recebe @deprecated. Os dois nomes usam a mesma implementação; se ambos forem informados, o canônico vence. A documentação e os exemplos recomendam o nome novo; a equivalência é documentada na página do componente correspondente.
Depreciação não significa remoção agendada. Uma possível remoção exige decisão e planejamento separados para uma versão principal.
Estilos e composição
Estado exclusivamente visual novo usa custom properties no formato --br-{componente}-{elemento}-{propriedade}. Props visuais já publicadas continuam funcionando. Slots usam nomes funcionais, como label, description, actions, header, footer e trigger; CSS parts descrevem o papel estrutural, não classes internas.
