Date Adapters

Plug in custom date libraries for timezone and locale support.

Overview

The timeline uses a date adapter for all date operations: parsing input dates, calculating tick positions, snapping to time boundaries, and formatting labels. By default, a built-in adapter using the browser's native Date object handles everything. If you need timezone-aware rendering or custom locale formatting, you can register a custom adapter that wraps a library like Luxon or Day.js.

Built-in Native Adapter

The default adapter works out of the box with no configuration. It uses the browser's local timezone and supports the following format tokens for axis labels and tooltips:

Tokens can be combined freely: "ddd D MMMM HH:mm" produces "Mon 5 January 14:05".

TempisTimelineDateAdapter Interface

A custom adapter must implement four methods. All operate on epoch milliseconds internally.

Supported Units

The startOf and add methods receive one of these unit strings:

year, month, week, day, hour, minute, second, millisecond

Registering an Adapter

import { AdapterRegistry } from '@tempis/timeline';

AdapterRegistry.register(myAdapter);

When to Use a Custom Adapter

• Fixed timezone display — show all events in UTC or a specific timezone regardless of the user's local clock.
• Non-Gregorian calendars — render dates in Hijri, Hebrew, or other calendar systems.
• Custom locale formatting — use locale-specific month/day names beyond what the browser provides.
• DST-aware calculations — ensure "add 1 day" always means 24 hours, even across daylight saving transitions.

Example — Luxon Adapter

This adapter renders all dates in the America/New_York timezone using Luxon:

import { DateTime } from 'luxon';
import { AdapterRegistry } from '@tempis/timeline';
import type { TempisTimelineDateAdapter } from '@tempis/timeline';

const luxonAdapter: TempisTimelineDateAdapter = {
  parse(input) {
    if (input instanceof Date) return input.getTime();
    if (typeof input === 'number') return isNaN(input) ? null : input;
    const dt = DateTime.fromISO(input, { zone: 'America/New_York' });
    return dt.isValid ? dt.toMillis() : null;
  },

  startOf(instant, unit) {
    return DateTime.fromMillis(instant, { zone: 'America/New_York' })
      .startOf(unit as any)
      .toMillis();
  },

  add(instant, unit, amount) {
    return DateTime.fromMillis(instant, { zone: 'America/New_York' })
      .plus({ [unit + 's']: amount })
      .toMillis();
  },

  format(instant, pattern) {
    // Luxon uses different tokens — map common ones.
    const luxonPattern = pattern
      .replace('YYYY', 'yyyy')
      .replace('D', 'd')
      .replace('ddd', 'EEE');
    return DateTime.fromMillis(instant, { zone: 'America/New_York' })
      .toFormat(luxonPattern);
  }
};

// Register once at app startup.
AdapterRegistry.register(luxonAdapter);

Example — Day.js Adapter

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';
import { AdapterRegistry } from '@tempis/timeline';
import type { TempisTimelineDateAdapter } from '@tempis/timeline';

dayjs.extend(utc);
dayjs.extend(timezone);

const TZ = 'Europe/London';

const dayjsAdapter: TempisTimelineDateAdapter = {
  parse(input) {
    if (input instanceof Date) return input.getTime();
    if (typeof input === 'number') return isNaN(input) ? null : input;
    const d = dayjs.tz(input, TZ);
    return d.isValid() ? d.valueOf() : null;
  },

  startOf(instant, unit) {
    return dayjs(instant).tz(TZ).startOf(unit as any).valueOf();
  },

  add(instant, unit, amount) {
    return dayjs(instant).tz(TZ).add(amount, unit as any).valueOf();
  },

  format(instant, pattern) {
    return dayjs(instant).tz(TZ).format(pattern);
  }
};

AdapterRegistry.register(dayjsAdapter);