TypeScript Types

TypeScript type definitions and interfaces for type-safe date picker usage

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

---

Navigation Types

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];
  }
}