DatePicker
betaSelección de una fecha: un disparador tipo input abre un calendario navegable por teclado (patrón APG). Trabaja con Date nativo y cero dependencias; los nombres de mes y día salen de Intl. El panel vive en el top-layer nativo (Popover API). Con data-ts-range elige un tramo (inicio y fin) en el mismo calendario, con data-ts-date-preset suma atajos (hoy, últimos 7 días, este mes) en una columna junto a la grilla, y con data-ts-date-text se puede escribir la fecha en un campo de texto.
Formularios · TaishoDS Core, en HTML plano.
Ejemplos
Un ejemplo por caso, funcionando. Cada ejemplo es el HTML de su vista previa: se copia tal cual y, con el CSS y el JS del Core cargados, se ve y funciona igual.
Calendario suelto
Fecha de despliegue con mínimo y máximo
Obligatoria, con ayuda
Con mensaje de error
Limpiable
Sin fines de semana ni feriados
Con marcas por día
Densidad compacta
Cargando
Rango de fechas
Con atajos de fecha
Rango con atajos
Fecha escrita a mano
Varios meses
Selector de mes y año
Número de semana
Fecha y hora
Cuándo usarlo
- Capturar una fecha donde ver el calendario ayuda a elegir (reservas, vencimientos).
- Hace falta un tramo con inicio y fin (una ventana de despliegue, un periodo de facturación):
data-ts-range. - El contexto del mes o la semana importa para decidir.
- La gente conoce la fecha de memoria o la pega de otro lado (un vencimiento, un ticket):
data-ts-date-textsuma un campo donde se escribe. - Hay elecciones que se repiten (hoy, los últimos 7 días, este mes): se suman como atajos con
data-ts-date-preset. - Hace falta restringir a un rango (
data-ts-min/data-ts-max) o respetar un locale (data-ts-locale). - Se busca el campo completo, con label, ayuda y error.
- Hay días que no se pueden elegir (fines de semana, feriados, una regla propia) o que conviene señalar con una marca (reuniones, despliegues).
Cuándo no
- La fecha es conocida y tipear es más rápido (una fecha de nacimiento) → un
inputcon formato. - Es sólo una hora, sin fecha, o un valor que no es una fecha → el control que corresponda.
Cómo usarlo
- Se restringe a las fechas válidas con
data-ts-min/data-ts-max, y los días sueltos que no se pueden elegir se marcan condata-ts-disabled-weekdays,data-ts-disabled-datesosetDatePickerDisabledDate. data-ts-day-marksseñala eventos con un punto y un texto corto: el texto llega al lector de pantalla y altitle.- Mientras se traen marcas o días no disponibles del servidor, se llama a
setDatePickerLoading(root, true): no bloquea el campo. - Se arma con el HTML de
fieldpara formularios, o con su label, ayuda y error pegados al campo si va suelto; el formato esperado debe quedar claro. - En el campo tipeable (
data-ts-date-text),readonlymuestra una fecha que no se edita, en vez dedisabled: sigue enfocable y se lee mejor. - Para los atajos relativos se usan las claves (
today,last-7-days,last-30-days,this-week,this-month,last-month): se resuelven al hacer clic, no al armar la página. - Con
data-ts-range, si va en un formulario, se ponenameen los dos<input type="hidden">(data-ts-date-input="start"y"end"): viajan dos fechasyyyy-mm-dd, inicio y fin.
Cómo no usarlo
- No se obliga a navegar meses para una fecha lejana ya conocida.
- No se activa
data-ts-date-textsi sólo se elige entre pocas fechas del calendario: un campo editable invita a errores de tipeo que el calendario evita. - No se espera
ts:changeen el primer clic de un rango: sale recién cuando el rango está completo o se limpia. - No se pasa una clave de rango en un calendario simple (ni
todaycomo rango de varios días): no se dibuja y en desarrollo avisa. - No se asume un formato: se respeta el locale del usuario.
- El color de la marca no es la única señal: siempre se escribe su
label.
TaishoDS Core
Necesita el JS del Core: maneja foco, teclado y estado.
Es un calendario propio con navegación por teclado; el <input> nativo sólo aporta el campo de texto.
El Core lo engancha por estos atributos. Van en el marcado; no hace falta inicializar nada.
data-ts-cleardata-ts-count-suffixdata-ts-date-captiondata-ts-date-griddata-ts-date-inputdata-ts-date-monthsdata-ts-date-nextdata-ts-date-pickerdata-ts-date-presetdata-ts-date-prevdata-ts-date-spinnerdata-ts-date-statusdata-ts-date-textdata-ts-date-timedata-ts-date-titledata-ts-date-weekdaysdata-ts-day-marksdata-ts-disabled-datesdata-ts-disabled-weekdaysdata-ts-end-textdata-ts-granularitydata-ts-hour-cycledata-ts-listboxdata-ts-listbox-labeldata-ts-listbox-loadingdata-ts-listbox-nativedata-ts-listbox-paneldata-ts-listbox-spinnerdata-ts-listbox-triggerdata-ts-localedata-ts-monthdata-ts-numberdata-ts-number-fielddata-ts-number-formatdata-ts-number-rawdata-ts-number-spinnerdata-ts-number-stepdata-ts-placeholderdata-ts-rangedata-ts-required-proxydata-ts-valuedata-ts-visible-monthsdata-ts-week-columndata-ts-week-numbersdata-ts-week-short
Qué hace: Dibuja la grilla del calendario, navega por teclado y formatea la fecha. Con disparador funciona completo, con el calendario en un panel que abre, cierra y devuelve el foco. Cada día lleva su nombre accesible con la fecha completa. Si los atributos de abajo cambian por JavaScript, el calendario se redibuja.
| Atributo | Qué hace |
|---|---|
popovertarget (en el disparador) | El botón abre el calendario con la Popover API nativa y mantiene aria-expanded e is-open. Al abrir, el calendario vuelve al mes del valor con el foco en su día. Elegir un día (clic, Enter o Espacio) cierra el panel, escribe la fecha formateada en el disparador y el valor yyyy-mm-dd en el <input type="hidden" name>, y el foco vuelve al botón. Escape y clic afuera cierran. Mayús + RePág/AvPág navegan por año. |
data-ts-min, data-ts-max | Los días fuera de rango quedan aria-disabled: enfocables, no elegibles. |
data-ts-week-start="0" | Primer día de la semana. |
data-ts-locale | Idioma de los nombres de mes y día, y del formato de la fecha. |
placeholder, disabled, size, density | Los de siempre: atributos nativos y clases del componente. También anda en RTL. |
data-ts-disabled-dates | Días no disponibles, separados por espacio: "2026-12-25 2027-01-01". |
data-ts-disabled-weekdays | Días de la semana no disponibles: "0 6". |
setDatePickerDisabledDate(root, fn) | Una función decide qué días no están disponibles; null la quita. |
data-ts-day-marks | Marcas por día, con JSON: [{"date":"2026-12-25","label":"Despliegue","variant":"success"}]. |
data-ts-visible-months | Cuántos meses se ven a la vez. El Core dibuja una grilla por mes dentro de div.ts.calendar-months[data-ts-date-months], que reemplaza a la grilla única; la raíz lleva is-multi. |
data-ts-caption-layout="dropdown" | Selector de mes y año. En la cabecera van dos Select con data-ts-date-caption="month" y "year" en su disparador, cada uno con su opción vigente: el Core la toma de molde y completa las demás según data-ts-min y data-ts-max. |
data-ts-week-numbers | Columna con la semana ISO. Su valor es el nombre accesible de cada número, con {n} en el lugar del número ("Semana {n}"); data-ts-week-short es el texto del encabezado y data-ts-week-column, su nombre accesible. La raíz lleva has-week-numbers. |
data-ts-granularity="minute", data-ts-hour-cycle | Fecha con hora, sólo en modo simple. data-ts-value, data-ts-min, data-ts-max y el hidden van como yyyy-mm-ddThh:mm en hora local. Bajo la grilla, en div.ts.calendar-time, van dos NumberInput con data-ts-date-time="hour" y "minute" en su input y, con data-ts-hour-cycle="12", un Select con "period" en su disparador. Elegir un día no cierra el panel. |
data-ts-date-preset | Atajos: botones dentro de div.ts.datepicker-presets[role=group] en el panel, con una clave (today, last-7-days…), un día yyyy-mm-dd o un intervalo inicio/fin. Confirman y cierran como elegir un día, y quedan aria-disabled si caen fuera de min/max o no están disponibles. |
ts datepicker-prefix-block | Prefijo: un span primero en el disparador, o un div primero en div.ts.datepicker-field. Es marcado y CSS. |
data-ts-date-text | Campo tipeable: div.ts.datepicker-field con input.ts.datepicker-input[data-ts-date-text] ("start" y "end" con range, dentro de role=group) y el botón .ts.datepicker-toggle con popovertarget. El Core confirma al salir del campo o con Enter (sin consumir la tecla, así un <form> sigue su envío), escribe el hidden y reformatea. Un valor inválido, fuera de rango o no disponible vuelve al último válido, y vacío quita la fecha (ts:change con valor vacío). required, readonly y disabled son los nativos del input. |
data-ts-range | Rango, en la raíz del calendario; data-ts-value es el intervalo ISO (2026-07-01/2026-07-31). El primer clic fija el inicio, la vista previa sigue al puntero y al foco, una región viva anuncia el inicio (plantilla data-ts-end-text) y hay dos hidden, data-ts-date-input="start" y "end". ts:change lleva value, start y end, y sólo sale al completar o limpiar. |
setDatePickerLoading(root, true | false) | Pone is-loading, aria-busy y el Spinner de data-ts-date-spinner; no bloquea. |
ts:change | Elegir un día lo emite, cancelable. form.reset() vuelve a la fecha inicial sin emitirlo. |
Sin build, desde el CDN: taisho.date-picker.css, además de taisho.base.css. También se carga:
taisho.button.csstaisho.checkbox.csstaisho.icon.csstaisho.input.csstaisho.kbd.csstaisho.number-input.csstaisho.popover.csstaisho.select.csstaisho.spinner.css
Para el funcionamiento general del Core, ver Comportamiento.
Accesibilidad
Implementa el patrón Date Picker Dialog de la WAI-ARIA APG.
- El trigger es un
<button>conaria-haspopup="dialog"yaria-expandedque refleja si el calendario está abierto (también en el Core, que lo sincroniza al abrir y cerrar elpopover); el panel es unrole="dialog"con nombre accesible. - La grilla usa
role="grid"con roving tabindex: flechas mueven día/semana, Home/End inicio/fin de semana, RePág/AvPág cambian de mes (con Mayús, de año), Enter/Espacio eligen. El grupo y la grilla se nombran con el mes visible («Julio de 2026»). - Cada día es un
gridcellcon la fecha completa como nombre accesible;aria-selectedindica el elegido y los días fuera de rango llevanaria-disabled(siguen enfocables, no se eligen). El nombre es la fecha completa, no sólo el número del día. form.reset()devuelve la fecha inicial (texto del disparador, hidden y calendario) sin dispararts:change.- El disparador se nombra por
aria-labelledby(label + fecha elegida) yaria-describedbyapunta a la ayuda o al error; un campo inválido llevaaria-invalid="true"y el mensaje se anuncia conaria-live="polite". El asterisco de obligatorio es decorativo (aria-hidden): un<button>no admiterequiredniaria-required, así que el bloqueo del envío lo lleva un<input data-ts-required-proxy>sinname, invisible,aria-hiddeny fuera del orden de Tab: enviar vacío muestra el mensaje nativo del navegador y el foco cae en el disparador. No valida condisablednireadonly. - Los días no disponibles (
data-ts-disabled-dates,data-ts-disabled-weekdayso una función consetDatePickerDisabledDate(root, fn)) llevanaria-disabled="true": siguen enfocables con las flechas (APG) pero Enter, Espacio y clic no los eligen. El calendario se redibuja si cambian por JS. - Las marcas de día (
data-ts-day-marks) agregan al nombre accesible de la celda el texto de la marca («jueves, 25 de diciembre de 2026, Navidad»; con varias, unidas con coma) y lo repiten en eltitle. El punto de color es decorativo (aria-hidden): el color nunca es la única señal. - Para el estado de carga, se llama a
setDatePickerLoading(root, true|false): poneis-loadingyaria-busy="true"en el disparador y la grilla, y muestra un Spinner (unrole="status"que anuncia el estado). Si se pone sólo la clase, no se anuncia. No bloquea: el calendario abre y se puede elegir. - Los atajos (
data-ts-date-preset) son botones dentro de unrole="group"con nombre. Uno que cae fuera del rango permitido, o cuyo extremo es un día no disponible, llevaaria-disabled="true": sigue enfocable y no se elige, como los días. Cada atajo trae una clave (today,last-7-days,this-week…), un díayyyy-mm-ddo un intervaloinicio/fin; las claves se resuelven contra hoy al clic y el Core recalculaaria-disabledcada vez que abre el panel. - Con
data-ts-rangela grilla llevaaria-multiselectable="true"yaria-selected="true"en todo el tramo (extremos e interior; la vista previa también). Tras el primer clic una región viva (role="status",data-ts-date-status) anuncia «Inicio: martes, 14 de julio de 2026. Elegir la fecha de fin.» y se vacía al completar o descartar. El disparador muestra el rango conIntl.DateTimeFormat.formatRange. Los extremos tienen que estar disponibles; el tramo puede cruzar días conaria-disabled. El valor se declara condata-ts-value="inicio/fin"yts:changetraestartyend. - Con el campo tipeable (
data-ts-date-input, patrón APG Date Picker Dialog) el disparador es un<input type="text">nombrado por su label (o poraria-labelsi no hay), conaria-describedbyque suma un texto oculto con el formato esperado («Formato: dd/mm/aaaa») y el mismo patrón comoplaceholder. El botón de calendario aparte llevaaria-label,aria-haspopup="dialog"yaria-expanded.required,readonlyydisabledson los nativos del input (el mensaje de validación es el del navegador; no hace falta el input de validación). Conreadonlyno hay botón. En rango los dos campos viven en unrole="group"nombrado por el label y cada uno lleva suaria-label(«Fecha de inicio» / «Fecha de fin»).aria-invalidyaria-busyvan en los inputs. readonlydeja el disparador enfocable y sindisabled, pero sinaria-haspopup,aria-expandedni calendario: Enter, Espacio y clic no hacen nada y el valor viaja en el form. Es un<button>, así que no llevaaria-readonly(no es válido en su rol).- El botón de limpiar (
data-ts-clear) es un<button>hermano del disparador, con nombre «Limpiar campo»; Tab llega a él después del disparador. Al activarlo cierra el calendario, devuelve el foco al disparador y avisa conts:change. - Hoy se marca con un punto bajo el número (color del texto, así contrasta también sobre el día seleccionado) además del peso; con
forced-colorsno cuenta el punto sino el subrayado. El foco de día es un anillo interno de 2px con la tinta de foco de la familia, sin bordes. - En RTL los chevrones de mes se reflejan (el anterior apunta a la derecha) y, con
forced-colors: active, el día seleccionado usaHighlight/HighlightText, hoy va subrayado (o con punto de sistema si además está seleccionado) y el foco lleva outline de sistema. - Los textos (mes anterior/siguiente, «elegir una fecha») vienen escritos en el HTML; los nombres de mes y de día, de
Intlsegún el locale (data-ts-locale). - Con
data-ts-visible-monthscada mes es su propiarole="grid", nombrada con su mes; hay un solo día tabulable en todo el calendario y las flechas cruzan de una grilla a la otra. La vista sólo se mueve cuando el día enfocado sale de lo visible, y el rótulo con el tramo de meses se anuncia conaria-live. Los días de relleno quedan como celdas vacías, para que ninguna fecha se lea dos veces. - Con
data-ts-caption-layout="dropdown"la cabecera suma dos Select nombrados «Mes» y «Año» (traducibles), en el orden de tabulación entre las flechas. El rótulo del mes sigue en el DOM para el lector y se anuncia conaria-liveal cambiar. Escape con un selector abierto cierra sólo ese selector. Después de saltar de mes, la grilla conserva su día tabulable. - Con
data-ts-week-numberscada fila empieza con unrole="rowheader"nombrado «Semana 29» (traducible) y la columna tiene sucolumnheader. El número no es enfocable ni elegible: las flechas siguen yendo de día a día. - Con
data-ts-granularity="minute"las horas y los minutos sonrole="spinbutton"(flechas, RePág y AvPág) dentro de unrole="group"llamado «Hora», con nombres traducibles; con reloj de 12 horas suma un Select de período. Elegir un día no cierra el panel y el foco sigue en la grilla, así que Tab llega a la hora. Sin fecha elegida los campos quedan deshabilitados. Escape cierra el panel y el valor ya elegido se conserva.
Teclado
Además de lo que ya hace el navegador (Tab mueve el foco, Enter activa un botón).
| Tecla | Qué hace |
|---|---|
| ←→↑↓ | Mueve el día enfocado (día y semana). En RTL la grilla se espeja: ← avanza un día y → retrocede. |
| Home/End | Primer y último día de la semana. |
| RePág/AvPág | Mes anterior y siguiente; si el día no existe en ese mes, cae en el último. |
| Mayús+RePág/AvPág | Año anterior y siguiente. |
| Enter/Espacio | Selecciona el día enfocado, cierra el calendario y devuelve el foco al disparador. |
| Enter/Espacio(con`data-ts-range`) | La primera vez fija el inicio y el calendario sigue abierto; las flechas mueven la vista previa del tramo; la segunda vez fija el fin, cierra y devuelve el foco al disparador. Escape a mitad de camino descarta el inicio. |
| Tab(atajos) | Con atajos (data-ts-date-preset), Tab recorre primero los atajos (columna al inicio del panel) y después el calendario; al abrir, el foco sigue en el día. Enter, Espacio o clic en un atajo confirma el valor, cierra el panel y devuelve el foco al disparador. |
| Escribir/Enter/Tab(`data-ts-date-input`) | Con el campo tipeable, clic o Tab entran sin abrir el calendario (el botón de calendario es otro tabulable, después del campo). Enter o salir del campo confirma lo escrito; si es ilegible, inexistente, fuera del rango permitido o un día no disponible, el texto vuelve al último valor válido, y vacío quita la fecha. Dentro de un <form>, Enter deja seguir el envío. En rango, Tab pasa del campo de inicio al de fin sin confirmar; el par se confirma al salir del grupo. |
| Enter/Espacio/clic(disparador) | Abre el calendario con el foco en el día enfocable (el seleccionado o, sin valor, hoy). Escape lo cierra y devuelve el foco al disparador. |
Verificación
Qué se probó de verdad. Lo que no se probó lo dice: preferimos un «sin verificar» a una afirmación de más.
- axe WCAG 2.2 A + AA en navegador real, en tema claro y oscuro, antes de cada versión.
- teclado Mapa de teclas documentado arriba, contrastado contra el componente.
- lector de pantalla Sin verificar con lector de pantalla. Conviene probarlo en la combinación de componentes propia, no sólo aquí, donde cada uno aparece solo y en su estado feliz.