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.

Props booleanas em HTML seguem a semântica de presença do atributo: quando o atributo existe, o valor é true, mesmo que seu texto seja "false". Portanto, disabled="false" ainda desabilita o componente. Para definir false explicitamente, use uma propriedade JavaScript ou o binding booleano do framework, como disabled={false} no React, [disabled]="false" no Angular ou :disabled="false" no Vue.

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.

Validação de propriedades

Props com valores restritos documentam explicitamente os valores aceitos, o valor padrão e o comportamento para entradas inválidas. O componente não lança exceção por uma configuração inválida: ele aplica o fallback ou limite definido pela prop e registra um aviso no console.

Por exemplo, density aceita small, medium e large. Uma entrada como density="compact" usa medium e registra um aviso. O valor recebido não é necessariamente sobrescrito na propriedade ou no atributo; a implementação usa o valor efetivo validado para renderização.

Warnings de validação são emitidos uma vez por prop e valor inválido em cada instância. Renderizações repetidas não repetem o aviso. Props opcionais omitidas não geram warning, e valores livres que não possuem um domínio definido não recebem validação genérica.

Props numéricas documentam se aceitam números finitos, inteiros, limites inclusivos ou valores estritamente positivos. Quando o contrato define limites, valores finitos fora da faixa são limitados ao extremo correspondente; valores não numéricos, não finitos ou incompatíveis com o tipo usam o fallback documentado.

Props estruturadas, como arrays e objetos de opções, documentam o formato mínimo de cada entrada. Entradas inválidas são ignoradas ou a coleção inteira usa o fallback seguro indicado pela prop, sem interromper a renderização. O componente preserva a entrada pública sempre que possível e usa uma coleção normalizada apenas no estado interno.