componentes / time-picker

TimePicker

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

Como usar

O valor é uma string `"HH:mm"` em 24h (`"14:30"`), mesmo com `hour12`, que só muda como aparece e adiciona uma coluna AM/PM. O painel fica aberto enquanto você escolhe: escolha a hora, depois o minuto, e feche com `Esc` ou clicando fora. `minuteStep` limita os minutos (ex.: 15).

preview

Horário

Horário (12h, a cada 15 min)

TimePicker.tsx

import { TimePicker } from "vaiperui";
 
const [time, setTime] = useState("14:30");
 
<TimePicker label="Horário" value={time} onValueChange={setTime} />
<TimePicker label="Horário" hour12 minuteStep={15} />

24h e 12h

preview

24h

12h

formato-hora.tsx

<TimePicker defaultValue="14:30" />
<TimePicker hour12 defaultValue="14:30" />

Passo dos minutos

preview

passo-minutos.tsx

<TimePicker minuteStep={15} />
<TimePicker minuteStep={30} />

Tamanhos

preview

tamanhos.tsx

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

Estados

preview

ajudaDetalhe extra

ajuda

erroIsto é obrigatório

erro

desabilitado

somente leitura

estados.tsx

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

Props

Prop	Valores	Padrão	Descrição
value / defaultValue	string	nenhum	Horário como "HH:mm" (24h), controlado ou inicial
onValueChange	(time: string) => void	nenhum	Chamado com "HH:mm" quando hora, minuto ou período mudam
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
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

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.
Horas, minutos e (com `hour12`) AM/PM são colunas, cada uma um `role="group"` nomeado por `labels.hours`, `labels.minutes` e `labels.period`.
Cada opção é um `<button>` com `aria-pressed` na selecionada; a opção selecionada é rolada para a vista ao abrir o painel.

Teclado

Tecla	Ação
Enter / Space	Abre ou fecha o painel a partir do gatilho.
Arrow Up / Down	Dentro de uma coluna, move o foco para a opção anterior / seguinte.
Tab	Move entre as opções do painel (cada opção é uma parada do Tab).
Enter / Space	Escolhe a opção em foco; o painel continua aberto.
Esc	Fecha o painel e devolve o foco ao gatilho.

Tenha em mente

O foco não vai para o painel ao abrir e o painel continua aberto após a escolha: feche com Esc ou clicando fora.
Clicar fora fecha o painel sem devolver o foco; só o Esc restaura o foco no gatilho.
A hora só é escolhida nas colunas (sem digitação; só os minutos listados por `minuteStep`). Passe `labels` e `panelLabel` traduzidos; os padrões estão em inglês.