Date Picker

O mk-date-picker é o componente de seleção de data do Makuco UI. Ele suporta entrada manual no formato DD/MM/AAAA, seleção por calendário em modo único ou intervalo, e integração nativa com formulários via ElementInternals.

Quando usar

Use mk-date-picker para capturar datas em formulários, filtros de período e fluxos em que a entrada deve seguir um formato estruturado.

• O usuário precisar informar uma data específica.
• O fluxo exigir seleção de um intervalo de datas.
• O formulário precisar de validação e envio nativo com name e required.

• A necessidade for apenas escolher uma hora — use um seletor de horário.
• O valor for uma data e hora em um único campo — considere um componente mais específico.

Seleção simples

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

<MkDatePicker label="Data de nascimento" name="birthDate" />

<mk-date-picker label="Data de nascimento" name="birthDate"></mk-date-picker>

Modo intervalo

Use mode="range" para permitir seleção de um período. O primeiro clique define a data inicial e o segundo define a data final.

<MkDatePicker label="Período" mode="range" name="period" />

<mk-date-picker label="Período" mode="range" name="period"></mk-date-picker>

Limpar

Com o campo preenchido, um botão × aparece antes do ícone de calendário, nos modos single e range. Ele esvazia o valor, emite mkChange com "" e devolve o foco ao campo sem abrir o calendário. O botão não aparece com disabled ou readonly. No modo single, apagar a data digitada ou deixá-la incompleta também emite mkChange com "", uma vez, quando o valor passa de preenchido a vazio.

<MkDatePicker
  label="Data"
  value={data}
  onMkChange={(e) => setData(e.detail === '' ? undefined : (e.detail as string))}
/>

<mk-date-picker
  label="Data"
  [value]="data"
  (mkChange)="data = $event.detail || undefined"
></mk-date-picker>

Limites de data

Defina min e max com datas ISO (YYYY-MM-DD). Os dias fora do limite ficam desabilitados no calendário e datas digitadas fora do limite são ignoradas.

<MkDatePicker label="Data" value="2026-05-14" min="2026-05-05" max="2026-05-25" />

<mk-date-picker label="Data" value="2026-05-14" min="2026-05-05" max="2026-05-25"></mk-date-picker>

Mês e ano

No cabeçalho do calendário, o mês e o ano são botões. Clicar no mês troca a grade de dias pelo painel de meses (3 colunas); clicar no ano troca pelo painel de anos (4 colunas, 24 anos por página, em ordem crescente, na página que contém o ano exibido). As setas do cabeçalho passam a mudar o ano no painel de meses e a página de 24 anos no painel de anos. Escolher um mês volta para os dias nesse mês e ano; escolher um ano volta para os dias e mantém o mês. O popover mantém a altura nos três painéis, e o painel de meses mostra os nomes em maiúsculas.

Meses e anos fora de min e max ficam desabilitados, e as setas do cabeçalho também quando toda a página seguinte está fora do intervalo. Em mode="range" os painéis só mudam o mês e o ano exibidos, sem escolher data.

Abra o calendário e clique no mês ou no ano do cabeçalho.

Idioma e formato

locale define a ordem dia/mês do campo, o placeholder, o rótulo dos dias, o nome do mês, as iniciais dos dias da semana e os textos de acessibilidade. Idiomas suportados: pt, es e en. Com pt ou es o formato é DD/MM/AAAA; com en-US é MM/DD/YYYY. O valor ISO não muda.

<MkDatePicker label="Date" locale="en-US" />

<mk-date-picker label="Date" locale="en-US"></mk-date-picker>

Somente leitura

Use readonly para exibir a data sem permitir digitação. O calendário não abre.

<MkDatePicker label="Data" value="2026-05-14" readonly />

<mk-date-picker label="Data" value="2026-05-14" readonly></mk-date-picker>

Texto de suporte

Defina supportText para exibir um texto de apoio abaixo do campo. Quando errorMessage está definido, a mensagem de erro ocupa o lugar do texto de suporte.

<MkDatePicker label="Vencimento" supportText="Informe a data de vencimento" />

<mk-date-picker label="Vencimento" support-text="Informe a data de vencimento"></mk-date-picker>

Estado de erro

Defina errorMessage para indicar um valor inválido ou incompleto. A mensagem deve orientar o usuário sobre o formato esperado.

<MkDatePicker label="Data" errorMessage="Data inválida" value="2026-05-14" />

<mk-date-picker label="Data" error-message="Data inválida" value="2026-05-14"></mk-date-picker>

Data inválida

No modo single, o texto digitado que não é uma data aceita permanece no campo e value fica vazio: texto incompleto (12/0), data inexistente (31/02/2026) ou data fora de min e max. Ao sair do campo, o componente exibe a mensagem abaixo do campo e emite mkInvalid com { text, reason }, uma vez por texto digitado (com o calendário aberto, espera o fechamento), em que reason é "incomplete", "invalid" ou "out-of-range". Durante a digitação não há erro. A validade do formulário recebe badInput; em um campo required, o texto inválido mostra "Data inválida" e o campo vazio mostra "Este campo é obrigatório". A errorMessage do consumidor tem precedência. O botão × aparece também com texto inválido.

<MkDatePicker label="Data" onMkInvalid={(e) => console.log(e.detail.reason)} />

<mk-date-picker label="Data" (mkInvalid)="onInvalid($event.detail)"></mk-date-picker>

Desabilitado

Use disabled quando a seleção não deve estar disponível para o usuário em determinado contexto.

<MkDatePicker label="Data" disabled value="2026-05-14" />

<mk-date-picker label="Data" disabled value="2026-05-14"></mk-date-picker>

Autofill do navegador

Defina autocomplete com um token do HTML para habilitar o autofill do navegador. A prop é repassada ao mk-input interno.

<MkDatePicker label="Data de nascimento" autocomplete="bday" />

<mk-date-picker label="Data de nascimento" autocomplete="bday"></mk-date-picker>

Props

Eventos

Acessibilidade

• O campo deve sempre receber um label claro e descritivo.
• O componente usa o calendário como diálogo acessível e comunica seu estado por atributos ARIA.
• O grid de dias tem um único ponto de entrada (o dia em foco). Setas movem por dia e semana, Home/End vão ao início e ao fim da semana, Page Up/Page Down mudam o mês e Shift + Page Up/Page Down mudam o ano. Enter seleciona o dia, e Escape fecha o calendário; nos dois casos o foco volta ao campo.
• O dia selecionado e os dias do intervalo têm aria-selected="true"; o dia de hoje tem aria-current="date".
• O mês e o ano do cabeçalho são botões ("Maio, Escolher mês" e "2026, Escolher ano"). Uma região aria-live="polite" visualmente oculta, só com o texto ("Maio 2026"; "Meses de 2026" e "Anos de 2016 a 2039" nos painéis), anuncia a troca de mês, de ano ou de painel sem ler os botões. aria-expanded indica o painel aberto.
• Os painéis de mês e de ano são grids com um único ponto de entrada (a célula selecionada), nomeados "Meses de 2026" ou "Anos de 2016 a 2039". Setas movem entre as células (3 colunas nos meses, 4 nos anos), Home/End vão ao início e ao fim da linha, Page Up/Page Down mudam o ano (meses) ou a página de 24 anos (anos), Enter/Space escolhem e Escape volta para os dias sem fechar o calendário (nem um mk-dialog ao redor), com o foco no botão do cabeçalho que abriu o painel.
• aria-controls aponta o popup aberto por ariaControlsElements (via controlPopup do mk-input), inclusive com o popup em outro shadow root. O axe-core 4.11.2 acusa aria-required-attr para o combobox expandido mesmo com o vínculo, porque lê só o atributo aria-controls, que a reflexão por elemento deixa vazio; o vínculo é o que as tecnologias assistivas leem.
• Com texto inválido, a mensagem aparece ao sair do campo (não durante a digitação) e o campo recebe aria-invalid. A validade do formulário usa badInput.
• Em formulários, prefira name, required e mensagens de erro explícitas para orientar o usuário.