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.
