@wawjs/ngx-datetime

Angular date and time helpers package from Web Art Work.

ngx-datetime extracts the time utilities from the older all-in-one package into a focused Angular package built around TimeService, DatetimeCalendarComponent, and DatetimePickerComponent.

License

MIT

Installation

npm i --save @wawjs/ngx-datetime

Usage

import { provideNgxDatetime } from '@wawjs/ngx-datetime';

export const appConfig = {
	providers: [
		provideNgxDatetime({
			defaultFormat: 'mediumDate',
			defaultTimezone: 'UTC',
			defaultLocale: 'en-GB',
		}),
	],
};

provideNgxDatetime() registers Angular DatePipe and datetime defaults used internally by TimeService.

Available Features

| Name | Description | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | DatetimeCalendarComponent | Inline calendar with single and range selection | | DatetimePickerComponent | Input/popover picker for date, time, datetime, date range, and datetime range values | | DatetimePickerMode, DatetimeRangeValue, DatetimePickerValue | Picker mode and value types | | TimeService | Date formatting, timezone conversion, range helpers, date math, and week/month calculations | | provideNgxDatetime | Environment provider for package setup | | DatetimeConfig, DATETIME_CONFIG, DEFAULT_DATETIME_CONFIG | Provider configuration helpers |

Picker Components

Use DatetimePickerComponent for input-style workflows and DatetimeCalendarComponent when the calendar should render inline.

import { Component, signal } from '@angular/core';
import { DatetimePickerComponent } from '@wawjs/ngx-datetime';

@Component({
	imports: [DatetimePickerComponent],
	template: `
		<ngx-datetime-picker
			mode="datetime-range"
			label="Schedule"
			placeholder="Select range"
			[(value)]="range"
		/>
	`,
})
export class ExampleComponent {
	range = signal({ start: null, end: null });
}

Supported picker modes:

• date
• time
• datetime
• date-range
• datetime-range

Accessibility

DatetimeCalendarComponent's day grid follows the WAI-ARIA APG grid pattern: only one day is in the Tab order at a time (roving tabindex), and Arrow keys/Home/End move focus a day/week at a time within the visible month. DatetimePickerComponent's trigger button is associated with its label via for/id, exposes aria-haspopup="dialog" and aria-expanded/aria-controls for the panel, moves focus into the panel when it opens, closes on Escape, and restores focus to the trigger on close.

Time Service

TimeService provides date formatting, timezone conversion, range helpers, and common date arithmetic.

Naming and formatting

• getDayName(date, format?)
• getMonthName(monthIndex, format?)
• formatDate(date, format?, timezone?)
• convertToTimezone(date, timezone)

Boundaries and ranges

• startOfDay(date)
• endOfDay(date)
• startOfWeek(date, locale?)
• endOfWeek(date, locale?)
• startOfMonth(date)
• endOfMonth(date)
• startOfYear(date)
• endOfYear(date)

Calendar helpers

• getDaysInMonth(month, year)
• isLeapYear(year)
• getWeekNumber(date)
• getWeeksInMonth(month, year)
• isSameDay(date1, date2)

Date math

• addDays(date, days)
• addMonths(date, months)
• addYears(date, years)
• addHours(date, hours)
• addMinutes(date, minutes)
• addSeconds(date, seconds)
• subtractDays(date, days)
• subtractMonths(date, months)
• subtractYears(date, years)
• subtractHours(date, hours)
• subtractMinutes(date, minutes)
• subtractSeconds(date, seconds)
• differenceInDays(date1, date2)
• differenceInHours(date1, date2)
• differenceInMinutes(date1, date2)

Example:

import { TimeService } from '@wawjs/ngx-datetime';

constructor(private timeService: TimeService) {}

ngOnInit() {
	const today = new Date();
	const weekStart = this.timeService.startOfWeek(today);
	const formatted = this.timeService.formatDate(weekStart, 'fullDate', 'UTC');

	console.log(formatted);
}

AI Coding Agents

This package includes AI.md with copyable instructions for Codex, Claude Code, Cursor, and other coding agents.

Copy this into the consuming project's AGENTS.md, CLAUDE.md, or equivalent file:

- This Angular project uses `@wawjs/ngx-datetime` for date/time helpers, calendar helpers, and date/time picker components.
- Import public APIs from `@wawjs/ngx-datetime`.
- Prefer registering the package with `provideNgxDatetime()` in application providers.
- Prefer `TimeService` for date formatting, timezone conversion, date arithmetic, and calendar boundary helpers before adding duplicate app utilities.
- Prefer `DatetimeCalendarComponent` and `DatetimePickerComponent` for date picking before building one-off date widgets.
- Keep date logic centralized in `TimeService` instead of scattering custom helpers across components.