Events API Reference

Every event of @pglejzer/datepicker-ui, the companion of timepicker-ui, with its payload and when it fires.

Subscribe with picker.on(event, handler) or with the matching callbacks.on* option. Both receive the same payload. on() returns a function that unsubscribes. See Methods.

All events

#

Event	Callback	Payload	Fires
`open`	`callbacks.onOpen`	`{ mode: "docked" \| "modal" \| "inline" }`	The picker opens, or an inline picker is mounted by `create()`.
`close`	`callbacks.onClose`	`{}`	The picker starts closing.
`cancel`	`callbacks.onCancel`	`{ reason: "button" \| "escape" \| "outside" }`	The picker is dismissed without committing.
`confirm`	`callbacks.onConfirm`	`{ value: PickerValue \| null, autoCommit: boolean }`	A value is committed or cleared. `autoCommit` is `true` for `closeOnSelect`, `commitOnChange` and typed input.
`update`	`callbacks.onUpdate`	`{ options: DatepickerOptions }`	`setOptions()` applied a patch.
`error`	`callbacks.onError`	`{ code, message, input?, option?, reason? }`	A typed date is invalid or unavailable, `calendar.validate` returned a message, or an option is rejected.
`select:day`	`callbacks.onSelectDay`	`{ value: DateValue, selected: boolean }`	A day is picked. `selected` is `false` when a click in multiple mode removes it.
`select:month`	`callbacks.onSelectMonth`	`{ year: number, month: number }`	A month is chosen in the month menu. `month` is 1-12.
`select:year`	`callbacks.onSelectYear`	`{ year: number }`	A year is chosen in the year menu or the year grid.
`navigate`	`callbacks.onNavigate`	`{ year, month, direction: -1 \| 0 \| 1, source }`	The displayed month changes.
`range:start`	`callbacks.onRangeStart`	`{ value: DateValue }`	The first day of a range is picked.
`range:end`	`callbacks.onRangeEnd`	`{ start: DateValue, end: DateValue }`	A range is completed.

index.ts

1import DatepickerUI from "@pglejzer/datepicker-ui";
2
3const picker = new DatepickerUI("#date", { calendar: { mode: "range" } });
4
5picker.on("range:start", ({ value }) => {
6  console.log("Start", value.value);
7});
8
9picker.on("range:end", ({ start, end }) => {
10  console.log("Range", start.value, end.value);
11});
12
13picker.on("confirm", ({ value, autoCommit }) => {
14  console.log(value, autoCommit);
15});
16
17picker.create();

The same handlers as options:

index.ts

1new DatepickerUI("#date", {
2  callbacks: {
3    onConfirm: ({ value }) => console.log(value),
4    onError: ({ code, message }) => console.warn(code, message),
5  },
6}).create();

Navigate sources

#

navigate reports source as one of these values. It does not fire for changes made through the API, so setValue() and open() move the view silently. With several months, year and month are the first month shown.

Source	Meaning
`drag`	The user dragged or swiped between months.
`wheel`	The user paged with the mouse wheel.
`button`	The user pressed a previous or next button.
`keyboard`	The user navigated with the keyboard.
`menu`	The user chose a month or year in a menu.

Month and year precision

#

With calendar.precision set to "month" or "year", select:day carries the picked period. value.value is YYYY-MM or YYYY. A preset click emits range:end without select:day.

Error codes

#

The error payload has a code and a human readable message. Which of input, option and reason are set depends on the code.

Code	Meaning
`invalid-date`	Typed text is not a date, or `setValue()` got a value that does not fit `calendar.mode`. `input` holds the text.
`unavailable-date`	A typed date is disabled or out of range. `input` holds the text and `reason` says why.
`invalid-value`	`calendar.validate` returned a message.
`invalid-option`	An option value was rejected and replaced by its default. `option` holds the path, such as `ui.theme`.

index.ts

1picker.on("error", ({ code, input, option, reason }) => {
2  if (code === "unavailable-date") {
3    console.log(input, reason);
4  }
5  if (code === "invalid-option") {
6    console.log(option);
7  }
8});

Unavailable reasons

#

reason is set with unavailable-date. Its type is UnavailableReason, and the values are listed in the order the rules are checked.

Reason	Meaning
`min`	The date is before `calendar.minDate`.
`max`	The date is after `calendar.maxDate`.
`disabled`	The date is excluded by `disabledDates`, `enabledDates` or `isDateDisabled`.
`weekday`	The weekday is in `calendar.disabledWeekdays`.
`range-length`	The range breaks `calendar.range.minLength` or `maxLength`.
`multiple-max`	The selection would exceed `calendar.multiple.max`.

Validation messages

A message from calendar.validate also sets aria-invalid and a custom validity message on the input, and adds dp-ui--error to the host. The same happens for typed text that is not a date.