TypeScript Types

The app-datepicker library is written in TypeScript and provides comprehensive type definitions. This page documents the key types and interfaces you’ll use when working with the library in TypeScript projects.

Core Component Types

DatePickerProperties

Complete type definition for all date picker properties.

interface DatePickerProperties extends
  DatePickerMinMaxProperties,
  DatePickerMixinProperties,
  ElementMixinProperties {}

This interface combines all property types for the main <app-datepicker> component. It includes:

Min/max date constraints
Localization and formatting options
Accessibility labels
Event handlers

Source: src/typings.ts:36-39

DatePickerMinMaxProperties

Properties for date range constraints.

interface DatePickerMinMaxProperties {
  max?: string;
  min?: string;
}

min

string

Minimum selectable date in ISO format (YYYY-MM-DD)

max

string

Maximum selectable date in ISO format (YYYY-MM-DD)

Source: src/mixins/typings.ts:6-9

DatePickerMixinProperties

Core configuration properties for the date picker.

interface DatePickerMixinProperties {
  chooseMonthLabel: string;
  chooseYearLabel: string;
  disabledDates: string;
  disabledDays: string;
  firstDayOfWeek: number;
  locale: string;
  nextMonthLabel: string;
  previousMonthLabel: string;
  selectedDateLabel: string;
  selectedYearLabel: string;
  shortWeekLabel: string;
  showWeekNumber: boolean;
  startView: StartView;
  todayLabel: string;
  toyearLabel: string;
  value?: null | string;
  weekLabel: string;
  weekNumberTemplate: string;
  weekNumberType: WeekNumberType;
}

locale

string

BCP 47 language tag (e.g., “en-US”, “fr-FR”, “ja-JP”)

value

string | null

Selected date value in ISO format (YYYY-MM-DD)

firstDayOfWeek

number

First day of week (0 = Sunday, 1 = Monday, …, 6 = Saturday)

startView

StartView

Initial view to display (“calendar” or “yearGrid”)

disabledDates

string

Comma-separated list of disabled dates (e.g., “2024-01-01, 2024-12-25”)

disabledDays

string

Comma-separated list of disabled weekdays (e.g., “0,6” for Sunday and Saturday)

showWeekNumber

boolean

Whether to display week numbers

weekNumberType

WeekNumberType

Week numbering system (“first-4-day-week”, “first-day-of-year”, “first-full-week”)

All label properties (e.g., todayLabel, nextMonthLabel) are for accessibility and internationalization. Source: src/mixins/typings.ts:11-31

Event Types

CustomEventDetail

Type map for all custom events dispatched by the date picker.

interface CustomEventDetail {
  ['date-updated']: CustomEventAction<'date-updated', CustomEventDetailDateUpdated>;
  ['first-updated']: CustomEventAction<'first-updated', CustomEventDetailFirstUpdated>;
  ['year-updated']: CustomEventAction<'year-updated', CustomEventDetailYearUpdated>;
}

Each property maps an event name to its detail structure. Usage Example:

const picker = document.querySelector('app-datepicker');

picker.addEventListener('date-updated', (event) => {
  const detail = event.detail; // Type: CustomEventDetailDateUpdated
  console.log(detail.value); // Selected date string
  console.log(detail.valueAsDate); // Selected date as Date object
  console.log(detail.valueAsNumber); // Selected date as timestamp
});

Source: src/typings.ts:17-21

ValueUpdatedEvent

Event detail for value update events.

interface ValueUpdatedEvent extends KeyEvent {
  value: string;
}

value

string

The new date value in ISO format

isKeypress

boolean

Whether the update was triggered by keyboard

key

SupportedKey

The key that triggered the update (if isKeypress is true)

Source: src/typings.ts:80-82

Formatting Types

Formatters

Complete set of date formatters for a locale.

interface Formatters extends Pick<DatePicker, 'locale'> {
  dateFormat: DateTimeFormatter;
  dayFormat: DateTimeFormatter;
  fullDateFormat: DateTimeFormatter;
  longMonthFormat: DateTimeFormatter;
  longMonthYearFormat: DateTimeFormatter;
  longWeekdayFormat: DateTimeFormatter;
  narrowWeekdayFormat: DateTimeFormatter;
  yearFormat: DateTimeFormatter;
}

Each formatter is a function that takes a Date and returns a formatted string. Usage Example:

import { toFormatters } from 'app-datepicker/helpers/to-formatters.js';
import type { Formatters } from 'app-datepicker/typings.js';

const formatters: Formatters = toFormatters('en-US');
const date = new Date('2024-01-15');

console.log(formatters.fullDateFormat(date)); // "Jan 15, 2024"
console.log(formatters.longMonthFormat(date)); // "January"

Source: src/typings.ts:43-52

View Types

StartView

The initial view mode for the date picker.

type StartView = StartViewTuple[number];
type StartViewTuple = typeof startViews;

Possible values:

"calendar" - Shows the month calendar view
"yearGrid" - Shows the year selection grid

Usage Example:

import type { StartView } from 'app-datepicker/typings.js';

const config = {
  startView: 'calendar' as StartView,
  locale: 'en-US',
};

Source: src/typings.ts:63-65

Helper Function Types

MaybeDate

Flexible type for date values that can be in various formats.

type MaybeDate = Date | null | number | string;

Accepts:

Date objects
null for no date
number for timestamps
string for ISO date strings

Usage Example:

import { toResolvedDate } from 'app-datepicker/helpers/to-resolved-date.js';
import type { MaybeDate } from 'app-datepicker/helpers/typings.js';

function processDate(input: MaybeDate): Date {
  return toResolvedDate(input);
}

processDate('2024-01-15'); // ✓
processDate(1705276800000); // ✓
processDate(new Date()); // ✓
processDate(null); // ✓

Source: src/helpers/typings.ts:12

DateValidatorResult

Return type for date validation operations.

interface DateValidatorResult {
  date: Date;
  isValid: boolean;
}

date

Date

The validated date or fallback date if invalid

isValid

boolean

Whether the input date was valid

Usage Example:

import { dateValidator } from 'app-datepicker/helpers/date-validator.js';
import type { DateValidatorResult } from 'app-datepicker/helpers/typings.js';

function validateUserInput(input: string): DateValidatorResult {
  return dateValidator(input, new Date());
}

const result = validateUserInput('2024-01-15');
if (result.isValid) {
  console.log('Valid date:', result.date);
} else {
  console.log('Invalid, using fallback:', result.date);
}

Source: src/helpers/typings.ts:7-10

MultiCalendars

Data structure for multiple calendar months.

interface MultiCalendars extends Omit<Calendar, 'calendar'> {
  calendars: Pick<Calendar, 'calendar' | 'key'>[];
  weekdays: CalendarWeekday[];
}

calendars

Array

Array of calendar data for each month

weekdays

CalendarWeekday[]

Weekday header information

disabledDatesSet

Set<number>

Set of all disabled date timestamps across calendars

disabledDaysSet

Set<number>

Set of all disabled weekday numbers

key

string

Unique key for the calendar configuration

Source: src/helpers/typings.ts:14-17

SupportedKey

Keyboard keys supported for date navigation.

type SupportedKey =
  | typeof keyArrowDown
  | typeof keyArrowLeft
  | typeof keyArrowRight
  | typeof keyArrowUp
  | typeof keyEnd
  | typeof keyEnter
  | typeof keyHome
  | typeof keyPageDown
  | typeof keyPageUp
  | typeof keySpace
  | typeof keyTab;

Supported navigation keys:

Arrow keys: Navigate between dates
Home/End: Jump to start/end of week or month
PageUp/PageDown: Navigate between months
Enter/Space: Select date
Tab: Focus navigation

Source: src/typings.ts:67-78

ToNextSelectableDateInit

Configuration for finding the next selectable date.

interface ToNextSelectableDateInit {
  date: Date;
  disabledDatesSet: Set<number>;
  disabledDaysSet: Set<number>;
  key: SupportedKey;
  maxTime: number;
  minTime: number;
}

date

Date

required

Starting date

key

SupportedKey

required

Navigation key pressed

minTime

number

required

Minimum allowed timestamp

maxTime

number

required

Maximum allowed timestamp

disabledDatesSet

Set<number>

required

Set of disabled date timestamps

disabledDaysSet

Set<number>

required

Set of disabled weekday numbers (0-6)

Source: src/helpers/typings.ts:35-42

Extended Component Types

DatePickerInputProperties

Properties for the <app-datepicker-input> component.

interface DatePickerInputProperties extends 
  DatePickerProperties, 
  Omit<TextField, keyof DatePickerProperties> {}

Combines date picker properties with Material Web Components TextField properties. Source: src/date-picker-input/typings.ts:5

DatePickerDialogProperties

Properties for the <app-datepicker-dialog> component.

interface DatePickerDialogProperties extends DialogProperties, DatePickerProperties {
  confirmLabel: string;
  dismissLabel: string;
  hide(): void;
  resetLabel: string;
  show(): void;
}

confirmLabel

string

required

Label for the confirm button

dismissLabel

string

required

Label for the dismiss button

resetLabel

string

required

Label for the reset button

show

() => void

required

Method to show the dialog

hide

() => void

required

Method to hide the dialog

Source: src/date-picker-dialog/typings.ts:7-13

DialogClosingEventDetail

Event detail for dialog closing events.

interface DialogClosingEventDetail {
  action: DialogClosingEventDetailAction;
}

type DialogClosingEventDetailAction = 'cancel' | 'reset' | 'set';

action

DialogClosingEventDetailAction

The action that closed the dialog:

"set" - User confirmed date selection
"cancel" - User dismissed the dialog
"reset" - User reset the date picker

Usage Example:

const dialog = document.querySelector('app-datepicker-dialog');

dialog.addEventListener('closing', (event) => {
  const detail = event.detail as DialogClosingEventDetail;
  
  if (detail.action === 'set') {
    console.log('Date confirmed:', dialog.value);
  } else if (detail.action === 'cancel') {
    console.log('Dialog cancelled');
  }
});

Source: src/date-picker-dialog/typings.ts:17-21

Utility Types

Constructor

Type for class constructors.

type Constructor<T> = new (...args: any[]) => T;

Used internally for mixin patterns. Source: src/utility-typings.ts:8

ChangedProperties

Type for tracking property changes in Lit elements.

type ChangedProperties<T = Record<string, unknown>> = PropertyValues & Map<keyof T, T[keyof T]>;

Used in lifecycle methods like updated() to track which properties changed. Source: src/typings.ts:10

InferredFromSet

Utility type to infer the element type from a Set.

type InferredFromSet<SetType> = SetType extends Set<infer T> ? T : never;

Source: src/typings.ts:54

Import Paths

Import type definitions from their respective modules:

// Core types
import type {
  DatePickerProperties,
  Formatters,
  StartView,
  CustomEventDetail,
  SupportedKey,
} from 'app-datepicker/typings.js';

// Helper types
import type {
  MaybeDate,
  DateValidatorResult,
  MultiCalendars,
  ToMultiCalendarsInit,
} from 'app-datepicker/helpers/typings.js';

// Dialog types
import type {
  DatePickerDialogProperties,
  DialogClosingEventDetail,
} from 'app-datepicker/date-picker-dialog/typings.js';

// Input types
import type {
  DatePickerInputProperties,
} from 'app-datepicker/date-picker-input/typings.js';

Type-Safe Component Usage

Here’s a complete example of using types for full type safety:

import type { DatePickerProperties, CustomEventDetail } from 'app-datepicker/typings.js';
import type { MaybeDate } from 'app-datepicker/helpers/typings.js';
import { dateValidator } from 'app-datepicker/helpers/date-validator.js';

// Type-safe configuration
const config: Partial<DatePickerProperties> = {
  locale: 'en-US',
  firstDayOfWeek: 1,
  min: '2024-01-01',
  max: '2024-12-31',
  startView: 'calendar',
};

// Type-safe event handling
const picker = document.querySelector('app-datepicker');

picker?.addEventListener('date-updated', (event) => {
  const customEvent = event as CustomEvent<
    CustomEventDetail['date-updated']['detail']
  >;
  
  const { value, valueAsDate, valueAsNumber } = customEvent.detail;
  console.log('Selected:', value); // string
  console.log('As Date:', valueAsDate); // Date
  console.log('As timestamp:', valueAsNumber); // number
});

// Type-safe date validation
function validateAndSet(input: MaybeDate): void {
  const result = dateValidator(input, new Date());
  
  if (result.isValid && picker) {
    picker.value = result.date.toISOString().split('T')[0];
  }
}

Components

Utilities

Core Component Types

DatePickerProperties

DatePickerMinMaxProperties

DatePickerMixinProperties

Event Types

CustomEventDetail

ValueUpdatedEvent

Formatting Types

Formatters

View Types

StartView

Helper Function Types

MaybeDate

DateValidatorResult

MultiCalendars

Navigation Types

SupportedKey

ToNextSelectableDateInit

Extended Component Types

DatePickerInputProperties

DatePickerDialogProperties

DialogClosingEventDetail

Utility Types

Constructor

ChangedProperties

InferredFromSet

Import Paths

Type-Safe Component Usage

Components

Utilities

​Core Component Types

​DatePickerProperties

​DatePickerMinMaxProperties

​DatePickerMixinProperties

​Event Types

​CustomEventDetail

​ValueUpdatedEvent

​Formatting Types

​Formatters

​View Types

​StartView

​Helper Function Types

​MaybeDate

​DateValidatorResult

​MultiCalendars

​Navigation Types

​SupportedKey

​ToNextSelectableDateInit

​Extended Component Types

​DatePickerInputProperties

​DatePickerDialogProperties

​DialogClosingEventDetail

​Utility Types

​Constructor

​ChangedProperties

​InferredFromSet

​Import Paths

​Type-Safe Component Usage

Core Component Types

DatePickerProperties

DatePickerMinMaxProperties

DatePickerMixinProperties

Event Types

CustomEventDetail

ValueUpdatedEvent

Formatting Types

Formatters

View Types

StartView

Helper Function Types

MaybeDate

DateValidatorResult

MultiCalendars

Navigation Types

SupportedKey

ToNextSelectableDateInit

Extended Component Types

DatePickerInputProperties

DatePickerDialogProperties

DialogClosingEventDetail

Utility Types

Constructor

ChangedProperties

InferredFromSet

Import Paths

Type-Safe Component Usage