Input

O mk-input é o campo de texto padrão do Makuco UI — o ponto de entrada mais comum em formulários para coleta de informações digitadas pelo usuário, como nomes, e-mails, senhas e endereços. Suporta todos os tipos de input nativos, mensagens de erro e suporte, contador de caracteres, ícone de trailing e máscaras de formatação (CPF, CNPJ, CEP, moeda e número). O componente comunica claramente seu propósito, estado atual e, quando necessário, orientações de preenchimento ou mensagens de erro.

Quando usar

Use mk-input para capturar dados textuais livres de forma simples e direta.

• O usuário precisar inserir texto livre de forma curta ou média.
• O dado a ser coletado não tiver uma lista fixa de opções.
• O dado precisar de formatação específica (CPF, CNPJ, CEP, moeda) via máscara.

• As opções forem fixas e limitadas — use mk-select.
• O texto for longo (mais de um parágrafo) — use um campo de texto multilinha (mk-textarea).
• O dado for numérico com formato específico não coberto pelas máscaras disponíveis — use um input especializado.

Anatomia

O campo de texto é formado por três regiões verticalmente empilhadas: área do rótulo, campo de entrada e área de suporte.

Estados

Padrão

import { MkInput } from '@db1/makuco-ui-react';

<MkInput label="Nome" placeholder="Digite seu nome" />

<mk-input label="Nome" placeholder="Digite seu nome"></mk-input>

Tipos

Use type para definir o tipo de entrada nativa. Para password, um botão de alternar visibilidade é renderizado automaticamente.

<MkInput label="E-mail" type="email" placeholder="usuario@exemplo.com" />
<MkInput label="Senha" type="password" />
<MkInput label="Telefone" type="tel" />

<mk-input label="E-mail" type="email" placeholder="usuario@exemplo.com"></mk-input>
<mk-input label="Senha" type="password"></mk-input>
<mk-input label="Telefone" type="tel"></mk-input>

Texto de suporte

Use supportText para exibir uma dica abaixo do campo.

<MkInput label="CPF" supportText="Somente números" />

<mk-input label="CPF" support-text="Somente números"></mk-input>

Estado de erro

O estado de erro deve sempre vir acompanhado de uma mensagem que explique o problema e, quando possível, como corrigi-lo. Nunca exiba o estado de erro sem uma explicação textual — o usuário precisa entender o que errou para conseguir corrigir.

Defina errorMessage para ativar o estado inválido e exibir a mensagem abaixo do campo.

<MkInput label="E-mail" errorMessage="E-mail inválido" value="nao-e-email" />

<mk-input label="E-mail" error-message="E-mail inválido" value="nao-e-email"></mk-input>

Obrigatório

<MkInput label="Nome completo" required />

<mk-input label="Nome completo" required></mk-input>

Desabilitado e somente leitura

<MkInput label="Desabilitado" disabled value="Não editável" />
<MkInput label="Somente leitura" readonly value="Apenas visualização" />

<mk-input label="Desabilitado" [disabled]="true" value="Não editável"></mk-input>
<mk-input label="Somente leitura" [readonly]="true" value="Apenas visualização"></mk-input>

Contador de caracteres

Defina maxLength para habilitar o contador de caracteres.

<MkInput label="Bio" maxLength={120} placeholder="Conte algo sobre você..." />

<mk-input label="Bio" [max-length]="120" placeholder="Conte algo sobre você..."></mk-input>

Ícone de trailing

<MkInput label="Pesquisa" trailingIcon="search" placeholder="Buscar..." />

<mk-input label="Pesquisa" trailing-icon="search" placeholder="Buscar..."></mk-input>

Máscaras

Use mask para formatar automaticamente o valor enquanto o usuário digita.

<MkInput label="CPF" mask="cpf" />
<MkInput label="CNPJ" mask="cnpj" />
<MkInput label="CEP" mask="cep" />
<MkInput label="Valor (BRL)" mask="brl" />

<mk-input label="CPF" mask="cpf"></mk-input>
<mk-input label="CNPJ" mask="cnpj"></mk-input>
<mk-input label="CEP" mask="cep"></mk-input>
<mk-input label="Valor (BRL)" mask="brl"></mk-input>

Formulários

O mk-input é form-associated e integra com <form> nativo. A tecla Enter aciona o submit do formulário pai.

<form onSubmit={handleSubmit}>
  <MkInput label="Nome" name="nome" required />
  <MkButton type="submit">Enviar</MkButton>
</form>

<form (ngSubmit)="handleSubmit()">
  <mk-input label="Nome" name="nome" required></mk-input>
  <mk-button type="submit">Enviar</mk-button>
</form>

Comportamento

O usuário clica no campo para ativá-lo. Enquanto digita, o campo permanece ativo com borda destacada. Ao sair do campo (blur), a validação pode ser acionada — se o valor for inválido, o campo muda para o estado de erro e exibe uma mensagem explicativa abaixo. Se o valor for válido, passa para o estado preenchido.

A validação nativa é acionada automaticamente quando validateMask está ativo: o componente reporta erro se a máscara estiver incompleta ou, para CPF e CNPJ, matematicamente inválida. Para validações de negócio, passe a mensagem via errorMessage após processar o resultado no código da aplicação.

O placeholder serve apenas como exemplo de formato — ele desaparece quando o usuário começa a digitar e nunca deve ser usado como substituto do rótulo.

Props

Eventos

Acessibilidade

• Usa <input> nativo internamente — foco e navegação por teclado estão inclusos.
• aria-invalid="true" aplicado automaticamente quando errorMessage está definida.
• aria-describedby aponta para o texto de suporte ou mensagem de erro.
• Para type="password", o botão de alternância expõe aria-label e aria-pressed.
• Com delegatesFocus: true, o foco é delegado ao <input> interno ao clicar no host.

Rótulo associado: o label deve estar programaticamente associado ao campo. Sem essa associação, leitores de tela não conseguem anunciar para qual campo o rótulo pertence.

Placeholder não substitui rótulo: o placeholder desaparece quando o usuário começa a digitar. Use-o apenas como exemplo de formato, nunca como substituto do rótulo.

Contraste: o texto digitado, o placeholder e o rótulo devem ter contraste suficiente em todos os estados, incluindo o desabilitado.