datepicker-ui Kit for Companion Packages

The kit entry of @pglejzer/datepicker-ui, the companion of timepicker-ui, exports the building blocks the picker uses, for packages built on top of it.

What the kit is

#

@pglejzer/datepicker-ui/kit exports the building blocks the picker itself uses, for packages built on top of datepicker-ui. It has named exports only.

index.ts

1import {
2  PopoverHost,
3  resolveSurfaceMode,
4  parseDate,
5} from "@pglejzer/datepicker-ui/kit";

Load the CSS

The hosts render dp-ui__container elements, so load main.css or index.css next to them.

Surfaces

#

Export	Signature	Purpose
PopoverHost	new PopoverHost(options)	Docked surface: a popover placed next to an anchor element.
DialogHost	new DialogHost(options)	Modal surface: a native dialog with a backdrop.
InlineHost	new InlineHost({ container, label })	Inline surface inside a container element.
waitForExit	waitForExit(element: HTMLElement): Promise<void>	Waits for an exit animation to finish.

Each host has root and body elements and open(), close() and destroy() methods.

Surface choice

#

Export	Signature	Purpose
resolveSurfaceMode	resolveSurfaceMode(option: "auto" \| "docked" \| "modal", inlineEnabled: boolean, viewportWidth: number, viewportHeight: number): SurfaceMode	Returns "docked", "modal" or "inline". "auto" means modal below 600 px wide or 480 px tall.
isFullscreenRange	isFullscreenRange(mode: CalendarMode, surface: SurfaceMode, viewportWidth: number, fullscreenBelow: number): boolean	Says whether a range picker goes full screen.

Color scheme

#

Export	Signature	Purpose
detectColorScheme	detectColorScheme(from: HTMLElement): Scheme	Returns "light" or "dark" for an element.
watchColorScheme	watchColorScheme(onChange: () => void): () => void	Reports changes and returns a function that stops watching.

Date text

#

A date is { year, month, day }.

Export	Signature	Purpose
resolvePattern	resolvePattern(format: FormatOption, locale: string, precision?: Precision): FormatPattern	Turns "auto" or a pattern string into a pattern for a locale.
formatDate	formatDate(date: PlainDate, pattern: FormatPattern): string	Formats a date as text.
parseDate	parseDate(text: string, pattern: FormatPattern): PlainDate \| null	Parses typed text, or returns null.
maskDateText	maskDateText(text: string, pattern: FormatPattern): string	Formats typed digits to the pattern.
formatHint	formatHint(pattern: FormatPattern): string	Returns a hint for the pattern, such as a placeholder.

index.ts

1import { resolvePattern, parseDate, formatDate } from "@pglejzer/datepicker-ui/kit";
2
3const pattern = resolvePattern("dd.MM.yyyy", "de-DE");
4
5const date = parseDate("14.03.2025", pattern);
6// { year: 2025, month: 3, day: 14 }
7
8if (date) formatDate(date, pattern);
9// "14.03.2025"

Types

#

Type	Meaning
SurfaceHost	Common shape of the three hosts.
SurfaceMode	"docked", "modal" or "inline".
Scheme	"light" or "dark".
FormatPattern	A resolved date pattern.
FormatOption	The value of ui.format.
DatePart	One part of a pattern: day, month or year.
PlainDate	{ year, month, day }.

From a CDN

#

dist/umd/kit.js exposes the exports as the global DatepickerUIKit.

index.html

1<script src="https://unpkg.com/@pglejzer/datepicker-ui/dist/umd/kit.js"></script>
2<script>
3  const { resolvePattern, parseDate } = DatepickerUIKit;
4</script>

#