FormDatetime

Calendar/clock date-time picker dengan 8 mode (date, range, multi-pick, time), keyboard navigation penuh, dan typeable input.

Bagian dari: vue-saform · Family: Notch

FormDatetime menutupi 8 bentuk picker sekaligus lewat satu mode prop: tanggal tunggal, rentang tanggal, multi-pick tanggal, tanggal+jam (single/rentang), dan jam saja (single/rentang). Grid kalender/clock-nya full keyboard-navigable — arrow key geser cursor dengan rollover otomatis ke bulan/tahun/dekade berikutnya di tepi grid, Escape selalu menutup panel tanpa keyboard trap. Mode date/dateTime juga bisa diketik langsung (urutan segmen diatur dateOrder), tidak cuma klik kalender. Sama seperti FormSelect, panelnya bisa inline atau detached jadi modal, dengan breakpoint responsif via detach="small".

---

Import

import { FormDatetime } from '@bpmlib/vue-saform';

Instalasi: lihat Installation & Setup di halaman utama.

---

Usage

<script setup lang="ts">
import { ref } from 'vue';
import { FormDatetime, required } from '@bpmlib/vue-saform';

const birthDate = ref<Date | null>(null);
</script>

<template>
  <FormDatetime id="birth-date" v-model="birthDate" label="Tanggal Lahir" mode="date" :validation="required()" />
</template>

---

API Reference

NOTE

Keyboard grid-cursor, typing-guard, dan floating position dibangun di atas composable internal (useDateGridCursor, useDateTyping, useFloatingPosition), tidak diekspos secara publik. Lihat Core Concepts di halaman utama untuk arsitektur detach.

FormDatetime

Cara Penggunaan:

mode menentukan bentuk picker dan shape modelValue. Mode 'date'/'dateTime' mendukung ketik langsung di input (dateOrder mengatur urutan segmen) — mode lain calendar/clock-only.

Accessibility:

Component ini sudah include built-in accessibility features:

• Keyboard navigation: Arrow key menggeser cursor grid (dengan rollover ke bulan/tahun/dekade berikutnya di tepi grid), Space memilih tanpa submit, Enter submit (mode 'date''s day grid saja)
• Escape: Selalu menutup panel, bahkan saat mid-typing — tidak ada keyboard trap

Props

Name	Type	Default	Description
id	string	-	Id input, juga dipakai sebagai name. Wajib.
label	string	-	Teks floating label
placeholder	string	-
disabled	boolean	false
readonly	boolean	false	Native readonly — juga mencegah membuka calendar (sama seperti disabled)
required	boolean	false	Built-in rule required(), dijalankan terhadap modelValue
hasError	boolean	false	Paksa visual error state terlepas dari internal validation state
title	string	-	Native title attribute
mode	DatetimeMode	'date'	Bentuk picker yang di-render/dikembalikan
maxPicks	number	Unlimited	mode="datePicks" saja — batas maksimum tanggal yang bisa dipilih
withSecond	boolean	false	Tampilkan field detik di clock UI (mode dateTime/dateTimeRange/time/timeRange)
withWeekNumber	boolean	false	Tampilkan kolom nomor minggu ISO di day grid
minDate	Date | string	-	Batas bawah inklusif — tanggal sebelum ini disabled
maxDate	Date | string	-	Batas atas inklusif — tanggal setelah ini disabled
returnStringDate	boolean	false	Emit string YYYY-MM-DD HH:mm:ss alih-alih Date object (mode date/dateTime-shaped saja — mode time/timeRange sudah emit string)
dateOrder	'dmy' | 'mdy' | 'ymd'	'dmy'	Urutan segmen untuk parsing teks yang diketik, mode 'date'/'dateTime' saja
detach	boolean | 'small'	false	Detach panel ke Teleport+backdrop modal Lihat selengkapnya
validation	ValidationInput<unknown>	-	Custom validation rule(s), jalan bersama built-in required
messages	ValidationMessages	-	Override pesan validasi default, di-shallow-merge
hideValidation	boolean	false	Skip seluruh perhitungan pesan validasi internal

NOTE

detach di FormDatetime bersifat presentation-only — tidak ada konsep staged-commit seperti FormSelect. Setiap mode sudah hanya commit lewat Confirm button eksplisit, Enter (mode 'date'), atau dblclick, terlepas dari detach.

DatetimeMode

Values:

type DatetimeMode =
  | 'date'            // Satu tanggal
  | 'dateRange'        // Rentang tanggal (start-end)
  | 'dateRangeAll'      // Rentang tanggal, semua hari di antaranya ikut terpilih
  | 'datePicks'         // Multi-pick tanggal individual (lihat maxPicks)
  | 'dateTime'          // Tanggal + jam
  | 'dateTimeRange'      // Rentang tanggal + jam
  | 'time'             // Jam saja
  | 'timeRange';        // Rentang jam

Model

Name	Type	Default	Description
v-model	string | number | Date | Array<string | number | Date> | null	null	Shape tergantung mode — single value untuk date/dateTime/time, array untuk mode range/multi-pick

Events

Name	Payload	Description
change	-	Fired bersamaan dengan update:modelValue saat value ter-commit

Slots

Name	Props	Description
description	-	Baris deskripsi di bawah field
errors	-	Baris pesan error custom, menggantikan pesan validasi bawaan

Exposed

Name	Type	Description
validate()	() => Promise<boolean>	Jalankan validasi, return true jika valid
open()	() => void	Buka panel calendar secara programmatic Lihat selengkapnya

open()

Membuka panel calendar secara programmatic (mis. dari tombol eksternal). No-op jika disabled/readonly.

Signature:

open: () => void

Contoh:

<script setup lang="ts">
const dtRef = ref();
</script>

<template>
  <FormDatetime ref="dtRef" id="date" v-model="date" />
  <button @click="dtRef.open()">Buka Kalender</button>
</template>

Contoh:

<FormDatetime
  id="range"
  v-model="range"
  label="Periode"
  mode="dateRange"
  :min-date="new Date()"
  detach="small"
/>

---

Examples

1. Date + Time dengan Detik

<FormDatetime id="schedule" v-model="schedule" label="Jadwal" mode="dateTime" with-second />

2. Multi-Pick dengan Batas

<FormDatetime id="event-dates" v-model="eventDates" label="Tanggal Event" mode="datePicks" :max-picks="5" />

3. Typeable Input dengan Urutan Segmen

<FormDatetime id="dob" v-model="dob" label="Tanggal Lahir" mode="date" date-order="ymd" />
<!-- User bisa ketik langsung "2024-03-15", bukan hanya klik kalender -->

4. Rentang Waktu dengan Nomor Minggu

<FormDatetime id="working-hours" v-model="hours" label="Jam Kerja" mode="timeRange" with-week-number />

---

Styling

Styling sepenuhnya self-contained — lihat Import CSS di halaman utama. Component akan tampil fully styled langsung setelah import, tanpa setup tambahan.

CSS Variables

Variable	Default	Description
--sa-fm-panel-z	40 (inline) / 50 (detached)	z-index panel calendar/modal. Sama seperti FormSelect
--sa-fm-error-list-style	disc	list-style-type untuk error list. Sama seperti FormInput

---

Related Components

Bagian dari family Notch:

• FormInput — text/number/email/password/currency input
• FormTextarea — versi <textarea>
• FormSelect — single/multi-select, berbagi konsep detach yang sama