componentes / date-time-picker

DateTimePicker

Campo que abre um Calendar e colunas de hora para escolher dia e horário.

Como usar

Combina o `Calendar` e as colunas do `TimePicker` num só painel. O valor é um `Date` com o dia e o horário (segundos são ignorados). Escolher um dia mantém o horário; escolher um horário antes de um dia usa hoje. O painel fica aberto até `OK`, `Esc` ou um clique fora. Com `name`, o formulário recebe `yyyy-mm-ddTHH:mm`.

preview

Agendamento

DateTimePicker.tsx

import { DateTimePicker } from "vaiperui";
 
const [when, setWhen] = useState<Date>();
 
<DateTimePicker label="Agendamento" value={when} onValueChange={setWhen} />
<DateTimePicker label="Agendamento" hour12 minuteStep={15} minDate={new Date()} />

24h e 12h

preview

24h

12h

formato-hora.tsx

<DateTimePicker />
<DateTimePicker hour12 />

Limites

preview

Campo

min / maxDate, step 15

limites.tsx

<DateTimePicker minDate={new Date()} minuteStep={15} />

Tamanhos

preview

tamanhos.tsx

<DateTimePicker size="sm" />
<DateTimePicker size="md" />
<DateTimePicker size="lg" />

Estados

preview

ajudaDetalhe extra

ajuda

erroIsto é obrigatório

erro

desabilitado

somente leitura

estados.tsx

<DateTimePicker label="..." helperText="..." />
<DateTimePicker label="..." errorMessage="..." />
<DateTimePicker label="..." disabled />
<DateTimePicker label="..." readOnly />

Props

Prop	Valores	Padrão	Descrição
value / defaultValue	Date	nenhum	Dia e horário, controlados ou iniciais
onValueChange	(date: Date) => void	nenhum	Chamado quando dia, hora, minuto ou período mudam
confirmLabel	string	"OK"	Texto do botão que fecha o painel
hour12	boolean	false	12h com uma coluna AM/PM
minuteStep	number	1	Granularidade da coluna de minutos
labels	{ hours, minutes, period, am, pm }	nenhum	Textos das colunas de hora
label / helperText	string	nenhum	Rótulo acima do campo e texto de ajuda abaixo
errorMessage	string	nenhum	Texto de erro; só a presença dele já força o estado de erro
placeholder	string	do idioma	Texto quando nada foi escolhido (ex.: dd/mm/aaaa)
name	string	nenhum	Nome do campo no formulário
disabled / readOnly	boolean	false	Não abre o painel; readOnly ainda mostra o valor
variant	ring \| outline	ring	Estilo de foco, igual ao Input
size / radius	sm \| md \| lg / none \| sm \| md \| lg \| full	md / md	Altura do campo e arredondamento dos cantos
aria-label	string	nenhum	Nome acessível quando não há rótulo
panelLabel	string	nenhum	Nome acessível do painel aberto
minDate / maxDate	Date	nenhum	Primeiro e último dia permitidos; o resto e as setas de mês que levam para fora ficam desabilitados
locale	string	"en-US"	Idioma dos nomes de mês/dia e formato da data (BCP 47)
weekStartsOn	0 – 6	0	Primeiro dia da semana (0 = domingo)
previousMonthLabel / nextMonthLabel	string	"Previous month" / "Next month"	Nomes acessíveis dos botões de mês
variantColor / customColor / animation	primary \| success \| warning \| danger / CSS color / none \| smooth \| fast \| bounce	primary / smooth	Cor da seleção e do foco, e velocidade da transição

Acessibilidade

O gatilho é um `<button>` com `aria-haspopup="dialog"` e `aria-expanded` refletindo o estado do painel.
O `label` é ligado por `htmlFor`; sem `label`, o gatilho usa `aria-label`.
`errorMessage` define `aria-invalid` e `aria-describedby` apontando para a mensagem; sem erro, o `helperText` é ligado por `aria-describedby`.
O painel é um `role="dialog"` nomeado por `panelLabel`, renderizado em um portal no `document.body`.
`disabled` desabilita o botão; `readOnly` mantém o foco possível, mas o painel nunca abre.
O painel contém um `Calendar` (com foco ao abrir, padrão de grade) e as colunas de hora, cada uma um `role="group"` nomeado por `labels`.
As opções de hora são `<button>`s com `aria-pressed` na selecionada; um botão final de confirmação (`confirmLabel`) fecha o painel.

Teclado

Tecla	Ação
Enter / Space	Abre ou fecha o painel a partir do gatilho.
Arrow keys, Home, End, Page Up/Down	No calendário, navegam pelos dias (veja Calendar); escolher um dia mantém a hora escolhida e não fecha o painel.
Arrow Up / Down	Em uma coluna de hora, move o foco para a opção anterior / seguinte.
Tab	Passa do calendário para as opções de hora e o botão de confirmação.
Esc	Fecha o painel e devolve o foco ao gatilho.

Tenha em mente

O painel não prende o foco: o Tab sai dele e, como ele é renderizado no fim do `<body>`, o Tab a partir do gatilho não entra nele sozinho.
Clicar fora fecha o painel sem devolver o foco; só o Esc restaura o foco no gatilho.
Data e hora não podem ser digitadas. Passe `labels`, `confirmLabel`, `panelLabel` e os rótulos dos botões de mês traduzidos; os padrões estão em inglês.