componentes / date-time-picker

DateTimePicker

Campo que abre un Calendar y columnas de hora para elegir día y hora.

Cómo usar

Combina el `Calendar` y las columnas del `TimePicker` en un solo panel. El valor es un `Date` con el día y la hora (los segundos se ignoran). Elegir un día mantiene la hora; elegir una hora antes de un día usa hoy. El panel queda abierto hasta `OK`, `Esc` o un clic fuera. Con `name`, el formulario recibe `yyyy-mm-ddTHH:mm`.

preview

Cita

DateTimePicker.tsx

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

24h y 12h

preview

24h

12h

formato-hora.tsx

<DateTimePicker />
<DateTimePicker hour12 />

Límites

preview

Campo

min / maxDate, step 15

limites.tsx

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

Tamaños

preview

tamanos.tsx

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

Estados

preview

ayudaDetalle extra

ayuda

errorEsto es obligatorio

error

deshabilitado

solo lectura

estados.tsx

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

Props

Prop	Valores	Predeterminado	Descripción
value / defaultValue	Date	ninguno	Día y hora, controlados o iniciales
onValueChange	(date: Date) => void	ninguno	Se llama cuando cambia el día, la hora, el minuto o el período
confirmLabel	string	"OK"	Texto del botón que cierra el panel
hour12	boolean	false	12h con una columna AM/PM
minuteStep	number	1	Granularidad de la columna de minutos
labels	{ hours, minutes, period, am, pm }	ninguno	Textos de las columnas de hora
label / helperText	string	ninguno	Etiqueta sobre el campo y texto de ayuda debajo
errorMessage	string	ninguno	Texto de error; su sola presencia fuerza el estado de error
placeholder	string	del idioma	Texto cuando no se eligió nada (p. ej. dd/mm/aaaa)
name	string	ninguno	Nombre del campo del formulario
disabled / readOnly	boolean	false	No abre el panel; readOnly aún muestra el valor
variant	ring \| outline	ring	Estilo de foco, igual que Input
size / radius	sm \| md \| lg / none \| sm \| md \| lg \| full	md / md	Altura del campo y redondeo de las esquinas
aria-label	string	ninguno	Nombre accesible cuando no hay etiqueta
panelLabel	string	ninguno	Nombre accesible del panel abierto
minDate / maxDate	Date	ninguno	Primer y último día permitidos; el resto y las flechas de mes que llevan fuera quedan deshabilitados
locale	string	"en-US"	Idioma de los nombres de mes/día y formato de la fecha (BCP 47)
weekStartsOn	0 – 6	0	Primer día de la semana (0 = domingo)
previousMonthLabel / nextMonthLabel	string	"Previous month" / "Next month"	Nombres accesibles de los botones de mes
variantColor / customColor / animation	primary \| success \| warning \| danger / CSS color / none \| smooth \| fast \| bounce	primary / smooth	Color de la selección y del foco, y velocidad de la transición

Accesibilidad

El disparador es un `<button>` con `aria-haspopup="dialog"` y `aria-expanded` que refleja el estado del panel.
El `label` se enlaza con `htmlFor`; sin `label`, el disparador usa `aria-label`.
`errorMessage` define `aria-invalid` y `aria-describedby` apuntando al mensaje; sin error, `helperText` se enlaza con `aria-describedby`.
El panel es un `role="dialog"` nombrado por `panelLabel`, renderizado en un portal en `document.body`.
`disabled` deshabilita el botón; `readOnly` mantiene el foco posible, pero el panel nunca se abre.
El panel contiene un `Calendar` (con foco al abrir, patrón de cuadrícula) y las columnas de hora, cada una un `role="group"` nombrado por `labels`.
Las opciones de hora son `<button>`s con `aria-pressed` en la seleccionada; un botón final de confirmación (`confirmLabel`) cierra el panel.

Teclado

Tecla	Acción
Enter / Space	Abre o cierra el panel desde el disparador.
Arrow keys, Home, End, Page Up/Down	En el calendario, navegan por los días (ver Calendar); elegir un día mantiene la hora elegida y no cierra el panel.
Arrow Up / Down	En una columna de hora, mueve el foco a la opción anterior / siguiente.
Tab	Pasa del calendario a las opciones de hora y al botón de confirmación.
Esc	Cierra el panel y devuelve el foco al disparador.

Ten en cuenta

El panel no atrapa el foco: Tab sale de él y, como se renderiza al final de `<body>`, Tab desde el disparador no entra en él por sí solo.
Hacer clic fuera cierra el panel sin devolver el foco; solo Esc restaura el foco en el disparador.
La fecha y la hora no se pueden escribir. Pasa `labels`, `confirmLabel`, `panelLabel` y las etiquetas de los botones de mes traducidos; los valores por defecto están en inglés.