@cdx-ui/formatters 0.0.1-beta.132

package/src/__tests__/getDateTimeFieldSegments.test.ts

@@ -0,0 +1,140 @@
+import { getDateTimeFieldSegments } from '../dates/segments/getDateTimeFieldSegments';
+
+describe('getDateTimeFieldSegments', () => {
+  it('returns placeholder date-time segments when value is empty', () => {
+    const segments = getDateTimeFieldSegments(undefined, {
+      granularity: 'minute',
+      locale: 'en-US',
+      hour12: true,
+    });
+    expect(segments.find((s) => s.type === 'month')?.text).toBe('MM');
+    expect(segments.find((s) => s.type === 'hour')?.text).toBe('hh');
+    expect(segments.find((s) => s.type === 'hour')?.value).toBeUndefined();
+    expect(segments.find((s) => s.type === 'minute')?.text).toBe('mm');
+    expect(segments.find((s) => s.type === 'dayPeriod')?.text).toBe('AM');
+  });
+
+  it('returns 12-hour date-time field segments with day period', () => {
+    const segments = getDateTimeFieldSegments('2026-07-28T14:30', {
+      granularity: 'minute',
+      locale: 'en-US',
+      hour12: true,
+    });
+    expect(segments.map((s) => s.type)).toEqual([
+      'month',
+      'literal',
+      'day',
+      'literal',
+      'year',
+      'literal',
+      'hour',
+      'literal',
+      'minute',
+      'literal',
+      'dayPeriod',
+    ]);
+    expect(segments.find((s) => s.type === 'hour')?.text).toBe('2');
+    expect(segments.find((s) => s.type === 'dayPeriod')?.text).toBe('PM');
+  });
+
+  it('returns 24-hour date-time field segments without day period', () => {
+    const segments = getDateTimeFieldSegments('2026-07-28T14:30', {
+      granularity: 'minute',
+      locale: 'en-US',
+      hour12: false,
+    });
+    expect(segments.map((s) => s.type)).toEqual([
+      'month',
+      'literal',
+      'day',
+      'literal',
+      'year',
+      'literal',
+      'hour',
+      'literal',
+      'minute',
+    ]);
+    expect(segments.find((s) => s.type === 'hour')?.text).toBe('14');
+    expect(segments.find((s) => s.type === 'dayPeriod')).toBeUndefined();
+  });
+
+  it('omits minute and second segments at hour granularity', () => {
+    const segments = getDateTimeFieldSegments('2026-07-28T14:30', {
+      granularity: 'hour',
+      locale: 'en-US',
+      hour12: true,
+    });
+    expect(segments.map((s) => s.type)).toEqual([
+      'month',
+      'literal',
+      'day',
+      'literal',
+      'year',
+      'literal',
+      'hour',
+      'literal',
+      'dayPeriod',
+    ]);
+    expect(segments.some((s) => s.type === 'minute')).toBe(false);
+    expect(segments.some((s) => s.type === 'second')).toBe(false);
+  });
+
+  it('places the second segment before the day period at second granularity', () => {
+    const segments = getDateTimeFieldSegments('2026-07-28T14:30:45', {
+      granularity: 'second',
+      locale: 'en-US',
+      hour12: true,
+    });
+    expect(segments.map((s) => s.type)).toEqual([
+      'month',
+      'literal',
+      'day',
+      'literal',
+      'year',
+      'literal',
+      'hour',
+      'literal',
+      'minute',
+      'literal',
+      'second',
+      'literal',
+      'dayPeriod',
+    ]);
+    expect(segments.find((s) => s.type === 'second')?.text).toBe('45');
+    expect(segments.find((s) => s.type === 'dayPeriod')?.text).toBe('PM');
+  });
+
+  it('places the second segment last on a 24-hour clock at second granularity', () => {
+    const segments = getDateTimeFieldSegments('2026-07-28T14:30:45', {
+      granularity: 'second',
+      locale: 'en-US',
+      hour12: false,
+    });
+    expect(segments.map((s) => s.type)).toEqual([
+      'month',
+      'literal',
+      'day',
+      'literal',
+      'year',
+      'literal',
+      'hour',
+      'literal',
+      'minute',
+      'literal',
+      'second',
+    ]);
+    expect(segments.find((s) => s.type === 'second')?.text).toBe('45');
+  });
+
+  it('orders empty placeholder second before the day period', () => {
+    const segments = getDateTimeFieldSegments(undefined, {
+      granularity: 'second',
+      locale: 'en-US',
+      hour12: true,
+    });
+    const secondIndex = segments.findIndex((s) => s.type === 'second');
+    const dayPeriodIndex = segments.findIndex((s) => s.type === 'dayPeriod');
+    expect(secondIndex).toBeGreaterThanOrEqual(0);
+    expect(dayPeriodIndex).toBeGreaterThan(secondIndex);
+  });
+});

package/src/__tests__/getDateTimeSegmentVisibility.test.ts

@@ -0,0 +1,12 @@
+import { getDateTimeSegmentVisibility } from '../dates/segments/getDateTimeSegmentVisibility';
+
+describe('getDateTimeSegmentVisibility', () => {
+  it.each([
+    ['day', { showTime: false, showMinute: false, showSecond: false }],
+    ['hour', { showTime: true, showMinute: false, showSecond: false }],
+    ['minute', { showTime: true, showMinute: true, showSecond: false }],
+    ['second', { showTime: true, showMinute: true, showSecond: true }],
+  ] as const)('matches DateTimeList columns at %s granularity', (granularity, expected) => {
+    expect(getDateTimeSegmentVisibility(granularity)).toEqual(expected);
+  });
+});

package/src/__tests__/intlCopy.test.ts

@@ -0,0 +1,64 @@
+import {
+  formatDayPeriodFromHour,
+  formatRelativeToday,
+  getDateRangeSeparator,
+} from '../dates/internal/intlCopy';
+
+describe('intlCopy', () => {
+  describe('formatRelativeToday', () => {
+    it('returns a locale-aware today label', () => {
+      expect(formatRelativeToday('en-US')).toBeTruthy();
+    });
+
+    it('falls back to Today when RelativeTimeFormat is unavailable', () => {
+      const original = Intl.RelativeTimeFormat;
+      // @ts-expect-error — simulate missing API
+      Intl.RelativeTimeFormat = undefined;
+      expect(formatRelativeToday('en-US')).toBe('Today');
+      Intl.RelativeTimeFormat = original;
+    });
+  });
+
+  describe('formatDayPeriodFromHour', () => {
+    it('returns AM for morning hours', () => {
+      expect(formatDayPeriodFromHour(9, 'en-US')).toMatch(/AM/i);
+    });
+
+    it('returns PM for afternoon hours', () => {
+      expect(formatDayPeriodFromHour(15, 'en-US')).toMatch(/PM/i);
+    });
+
+    it('falls back when formatToParts is unavailable', () => {
+      const prototype = Intl.DateTimeFormat.prototype;
+      const descriptor = Object.getOwnPropertyDescriptor(prototype, 'formatToParts');
+      Reflect.deleteProperty(prototype, 'formatToParts');
+      try {
+        expect(formatDayPeriodFromHour(9, 'en-US')).toBe('AM');
+      } finally {
+        if (descriptor) {
+          Object.defineProperty(prototype, 'formatToParts', descriptor);
+        }
+      }
+    });
+  });
+
+  describe('getDateRangeSeparator', () => {
+    it('returns a separator between formatted dates', () => {
+      const separator = getDateRangeSeparator('en-US');
+      expect(separator.trim().length).toBeGreaterThan(0);
+    });
+
+    it('falls back to en dash when formatRangeToParts is unavailable', () => {
+      const prototype = Intl.DateTimeFormat.prototype;
+      const descriptor = Object.getOwnPropertyDescriptor(prototype, 'formatRangeToParts');
+      Reflect.deleteProperty(prototype, 'formatRangeToParts');
+      try {
+        expect(getDateRangeSeparator('en-US')).toBe(' – ');
+      } finally {
+        if (descriptor) {
+          Object.defineProperty(prototype, 'formatRangeToParts', descriptor);
+        }
+      }
+    });
+  });
+});

package/src/__tests__/isValidDateId.test.ts

@@ -0,0 +1,8 @@
+import { isValidDateId } from '../dates/wire/isValidDateId';
+
+describe('isValidDateId', () => {
+  it('rejects invalid DateId', () => {
+    expect(isValidDateId('2026-13-01')).toBe(false);
+    expect(isValidDateId('07/28/2026')).toBe(false);
+  });
+});

package/src/__tests__/isValidMonthId.test.ts

@@ -0,0 +1,8 @@
+import { isValidMonthId } from '../dates/wire/isValidMonthId';
+
+describe('isValidMonthId', () => {
+  it('validates MonthId day is 01', () => {
+    expect(isValidMonthId('2026-07-01')).toBe(true);
+    expect(isValidMonthId('2026-07-15')).toBe(false);
+  });
+});

package/src/__tests__/normalizeDateRange.test.ts

@@ -0,0 +1,10 @@
+import { normalizeDateRange } from '../dates/ranges/normalizeDateRange';
+
+describe('normalizeDateRange', () => {
+  it('normalizes inverted range', () => {
+    expect(normalizeDateRange({ startId: '2026-07-28', endId: '2026-07-01' })).toEqual({
+      startId: '2026-07-01',
+      endId: '2026-07-28',
+    });
+  });
+});

package/src/__tests__/toMonthId.test.ts

@@ -0,0 +1,7 @@
+import { toMonthId } from '../dates/wire/toMonthId';
+
+describe('toMonthId', () => {
+  it('converts to month id', () => {
+    expect(toMonthId('2026-07-28')).toBe('2026-07-01');
+  });
+});

package/src/__tests__/todayDateId.test.ts

@@ -0,0 +1,7 @@
+import { todayDateId } from '../dates/wire/todayDateId';
+
+describe('todayDateId', () => {
+  it('returns todayDateId in YYYY-MM-DD shape', () => {
+    expect(todayDateId()).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+});

package/src/__tests__/wireConstructors.test.ts

@@ -0,0 +1,74 @@
+import { dateId } from '../dates/wire/dateId';
+import { monthId } from '../dates/wire/monthId';
+import { dateTimeId } from '../dates/datetime/dateTimeId';
+import { isValidDateParts } from '../dates/wire/isValidDateParts';
+import { isValidMonthParts } from '../dates/wire/isValidMonthParts';
+
+describe('wire constructors', () => {
+  describe('dateId', () => {
+    it('accepts valid wire strings', () => {
+      expect(dateId('2026-07-28')).toBe('2026-07-28');
+    });
+
+    it('builds from numeric parts', () => {
+      expect(dateId(2026, 7, 28)).toBe('2026-07-28');
+    });
+
+    it('throws on invalid wire strings', () => {
+      expect(() => dateId('2026-13-01')).toThrow(RangeError);
+    });
+
+    it('throws on invalid parts', () => {
+      expect(() => dateId(2026, 13, 1)).toThrow(RangeError);
+    });
+  });
+
+  describe('monthId', () => {
+    it('accepts valid wire strings', () => {
+      expect(monthId('2026-07-01')).toBe('2026-07-01');
+    });
+
+    it('builds from numeric parts', () => {
+      expect(monthId(2026, 7)).toBe('2026-07-01');
+    });
+
+    it('throws on invalid wire strings', () => {
+      expect(() => monthId('2026-07-15')).toThrow(RangeError);
+    });
+
+    it('throws on invalid parts', () => {
+      expect(() => monthId(2026, 13)).toThrow(RangeError);
+    });
+  });
+
+  describe('dateTimeId', () => {
+    it('accepts valid wire strings', () => {
+      expect(dateTimeId('2026-07-28T10:01')).toBe('2026-07-28T10:01');
+    });
+
+    it('builds from parts', () => {
+      expect(dateTimeId({ year: 2026, month: 7, day: 28, hour: 10, minute: 1 })).toBe(
+        '2026-07-28T10:01',
+      );
+    });
+
+    it('throws on invalid wire strings', () => {
+      expect(() => dateTimeId('not-a-date')).toThrow(RangeError);
+    });
+  });
+
+  describe('isValidDateParts', () => {
+    it('validates real calendar dates', () => {
+      expect(isValidDateParts({ year: 2026, month: 7, day: 28 })).toBe(true);
+      expect(isValidDateParts({ year: 2026, month: 2, day: 30 })).toBe(false);
+    });
+  });
+
+  describe('isValidMonthParts', () => {
+    it('validates month range', () => {
+      expect(isValidMonthParts({ year: 2026, month: 7 })).toBe(true);
+      expect(isValidMonthParts({ year: 2026, month: 0 })).toBe(false);
+      expect(isValidMonthParts({ year: 2026, month: 13 })).toBe(false);
+    });
+  });
+});

package/src/dates/calendar/formatCalendarMonthYear.ts

@@ -0,0 +1,21 @@
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import { getCachedDateFormatter } from '../internal/intlCache';
+import type { DateFormatOptions, MonthId } from '../types';
+
+/**
+ * Formats a calendar header label, e.g. `July 2026`.
+ *
+ * Uses `Intl` so `options.locale` is respected (same pattern as display formatters).
+ *
+ * @param monthId - Wire month string (`YYYY-MM-01`).
+ * @param options - Locale and optional time zone.
+ * @returns Long month and year label.
+ */
+export function formatCalendarMonthYear(monthId: MonthId, options?: DateFormatOptions): string {
+  const formatter = getCachedDateFormatter(options?.locale ?? 'en-US', {
+    month: 'long',
+    year: 'numeric',
+    ...(options?.timeZone ? { timeZone: options.timeZone } : {}),
+  });
+  return formatter.format(dateIdToNativeDate(monthId));
+}

package/src/dates/calendar/formatDateTimeListDateRow.ts

@@ -0,0 +1,41 @@
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import { formatRelativeToday } from '../internal/intlCopy';
+import { getCachedDateFormatter } from '../internal/intlCache';
+import type { DateFormatOptions, DateId } from '../types';
+
+/**
+ * Formats a row label for a scrollable date list. Returns a locale-aware "today" label when the
+ * id matches today (pass a precomputed `todayDateId` when comparing wire ids).
+ *
+ * @param dateId - Wire date string.
+ * @param options - Locale, optional `todayDateId` override, and time zone.
+ * @returns Relative today label or a short weekday/month/day label.
+ */
+export function formatDateTimeListDateRow(
+  dateId: DateId,
+  options?: DateFormatOptions & { todayDateId?: DateId },
+): string {
+  const locale = options?.locale ?? 'en-US';
+  const todayId = options?.todayDateId;
+  if (todayId && dateId === todayId) {
+    return formatRelativeToday(locale);
+  }
+
+  const date = dateIdToNativeDate(dateId);
+  const todayParts = new Date();
+  const isToday =
+    date.getFullYear() === todayParts.getFullYear() &&
+    date.getMonth() === todayParts.getMonth() &&
+    date.getDate() === todayParts.getDate();
+  if (isToday) {
+    return formatRelativeToday(locale);
+  }
+
+  const formatter = getCachedDateFormatter(locale, {
+    weekday: 'short',
+    month: 'short',
+    day: 'numeric',
+    ...(options?.timeZone ? { timeZone: options.timeZone } : {}),
+  });
+  return formatter.format(date);
+}

package/src/dates/calendar/formatMonthCalendarMonth.ts

@@ -0,0 +1,21 @@
+import { getCachedDateFormatter } from '../internal/intlCache';
+import type { DateFormatOptions } from '../types';
+
+/**
+ * Formats a short month name for month-grid cells (1–12).
+ *
+ * @param month - Month number (1–12).
+ * @param options - Locale and optional time zone.
+ * @returns Short month name.
+ *
+ * @example
+ * formatMonthCalendarMonth(7, { locale: 'en-US' }) // 'Jul'
+ */
+export function formatMonthCalendarMonth(month: number, options?: DateFormatOptions): string {
+  const date = new Date(2024, month - 1, 1);
+  const formatter = getCachedDateFormatter(options?.locale ?? 'en-US', {
+    month: 'short',
+    ...(options?.timeZone ? { timeZone: options.timeZone } : {}),
+  });
+  return formatter.format(date);
+}

package/src/dates/calendar/formatMonthCalendarYear.ts

@@ -0,0 +1,9 @@
+/**
+ * Formats a year label for month-calendar decade/year pickers.
+ *
+ * @param year - Four-digit year.
+ * @returns Year as a string.
+ */
+export function formatMonthCalendarYear(year: number): string {
+  return String(year);
+}

package/src/dates/calendar/getCalendarWeekdayLabels.ts

@@ -0,0 +1,23 @@
+import { formatCalendarWeekday } from '../internal/calendarHelpers';
+import type { DateFormatOptions } from '../types';
+
+/**
+ * Returns ordered weekday labels for a calendar week header.
+ *
+ * @param options - Locale, first day of week, and weekday width.
+ * @returns Array of seven weekday label strings.
+ */
+export function getCalendarWeekdayLabels(
+  options?: DateFormatOptions & {
+    firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    weekday?: 'short' | 'narrow' | 'long';
+  },
+): string[] {
+  const firstDayOfWeek = options?.firstDayOfWeek ?? 0;
+  const labels: string[] = [];
+  for (let i = 0; i < 7; i += 1) {
+    const index = (firstDayOfWeek + i) % 7;
+    labels.push(formatCalendarWeekday(index, options));
+  }
+  return labels;
+}

package/src/dates/datetime/clampDateTimeId.ts

@@ -0,0 +1,25 @@
+import type { DateTimeId } from '../types';
+import { compareDateTimeIds } from './compareDateTimeIds';
+
+/**
+ * Clamps a wire date-time into the inclusive `[min, max]` range.
+ *
+ * Returns `min` when `value` is earlier than `min`, `max` when later than `max`,
+ * otherwise `value` unchanged. Omitted bounds are ignored.
+ *
+ * @param value - Wire date-time to clamp.
+ * @param bounds - Optional inclusive `min` / `max` wire date-times.
+ * @returns The clamped `DateTimeId`.
+ */
+export function clampDateTimeId(
+  value: DateTimeId,
+  bounds: { min?: DateTimeId; max?: DateTimeId },
+): DateTimeId {
+  if (bounds.min && compareDateTimeIds(value, bounds.min) < 0) {
+    return bounds.min;
+  }
+  if (bounds.max && compareDateTimeIds(value, bounds.max) > 0) {
+    return bounds.max;
+  }
+  return value;
+}

package/src/dates/datetime/compareDateTimeIds.ts

@@ -0,0 +1,23 @@
+import { compareAsc, parseISO } from 'date-fns';
+import type { DateTimeId } from '../types';
+
+/**
+ * Compares two wire date-times chronologically.
+ *
+ * Handles local (`YYYY-MM-DDTHH:MM`) and UTC (`…Z`) forms alike by parsing each
+ * to an absolute instant before comparing.
+ *
+ * @param a - First wire date-time.
+ * @param b - Second wire date-time.
+ * @returns `-1` if `a` is earlier, `1` if later, `0` if equal.
+ */
+export function compareDateTimeIds(a: DateTimeId, b: DateTimeId): -1 | 0 | 1 {
+  const result = compareAsc(parseISO(a), parseISO(b));
+  if (result < 0) {
+    return -1;
+  }
+  if (result > 0) {
+    return 1;
+  }
+  return 0;
+}

package/src/dates/datetime/dateTimeId.ts

@@ -0,0 +1,36 @@
+import { asDateTimeId } from '../internal/brand';
+import type { DateTimeId, DateTimeParts } from '../types';
+import { formatDateTimeId } from './formatDateTimeId';
+import { isValidDateTimeId } from './isValidDateTimeId';
+
+/**
+ * Validating smart constructor for a wire {@link DateTimeId} (local ISO-like,
+ * e.g. `YYYY-MM-DDTHH:mm`).
+ *
+ * Accepts either a wire string or {@link DateTimeParts}. Throws `RangeError` on
+ * input that does not parse to a valid date-time.
+ *
+ * @param input - A wire date-time string or {@link DateTimeParts}.
+ * @returns The branded `DateTimeId`.
+ * @throws RangeError when the input is not a valid `DateTimeId`.
+ *
+ * @example
+ * dateTimeId('2026-08-07T14:30'); // DateTimeId
+ * dateTimeId({ year: 2026, month: 8, day: 7, hour: 14, minute: 30 }); // DateTimeId
+ */
+export function dateTimeId(input: string | DateTimeParts): DateTimeId {
+  if (typeof input === 'string') {
+    if (!isValidDateTimeId(input)) {
+      throw new RangeError(
+        `Invalid DateTimeId: "${input}". Expected a wire date-time such as "YYYY-MM-DDTHH:mm".`,
+      );
+    }
+    return input;
+  }
+
+  const built = formatDateTimeId(input);
+  if (!isValidDateTimeId(built)) {
+    throw new RangeError(`Invalid DateTimeId parts: ${JSON.stringify(input)}.`);
+  }
+  return asDateTimeId(built);
+}

package/src/dates/datetime/formatDateTimeId.ts

@@ -0,0 +1,35 @@
+import { asDateTimeId } from '../internal/brand';
+import { formatDateId } from '../wire/formatDateId';
+import type { DateTimeId, DateTimeParts } from '../types';
+
+/**
+ * Builds a wire `DateTimeId` from parts. Local by default; pass `{ utc: true }` for ISO UTC.
+ *
+ * @param parts - Date and time parts.
+ * @param options - When `utc` is true, returns an ISO UTC string ending in `Z`.
+ * @returns Wire `DateTimeId` string.
+ */
+export function formatDateTimeId(parts: DateTimeParts, options?: { utc?: boolean }): DateTimeId {
+  const date = options?.utc
+    ? new Date(
+        Date.UTC(
+          parts.year,
+          parts.month - 1,
+          parts.day,
+          parts.hour,
+          parts.minute,
+          parts.second ?? 0,
+        ),
+      )
+    : new Date(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second ?? 0);
+
+  if (options?.utc) {
+    return asDateTimeId(date.toISOString());
+  }
+
+  const datePart = formatDateId(parts);
+  const hour = String(parts.hour).padStart(2, '0');
+  const minute = String(parts.minute).padStart(2, '0');
+  const second = parts.second != null ? `:${String(parts.second).padStart(2, '0')}` : '';
+  return asDateTimeId(`${datePart}T${hour}:${minute}${second}`);
+}

package/src/dates/datetime/formatDateTimeListHour.ts

@@ -0,0 +1,14 @@
+/**
+ * Formats the hour label for a date-time list column.
+ *
+ * @param hour - Hour value (0–23).
+ * @param options - When `hour12` is true, returns 1–12 without leading zero.
+ * @returns Hour label string.
+ */
+export function formatDateTimeListHour(hour: number, options?: { hour12?: boolean }): string {
+  if (options?.hour12) {
+    const h = hour % 12 || 12;
+    return String(h);
+  }
+  return String(hour).padStart(2, '0');
+}

package/src/dates/datetime/formatDateTimeListMinute.ts

@@ -0,0 +1,9 @@
+/**
+ * Formats a zero-padded minute label for a date-time list column.
+ *
+ * @param minute - Minute value (0–59).
+ * @returns Two-digit minute string.
+ */
+export function formatDateTimeListMinute(minute: number): string {
+  return String(minute).padStart(2, '0');
+}

package/src/dates/datetime/formatDateTimeListPeriod.ts

@@ -0,0 +1,12 @@
+import { formatDayPeriodFromHour } from '../internal/intlCopy';
+import type { DateFormatOptions } from '../types';
+
+/**
+ * Returns the day-period label (AM/PM or locale equivalent) derived from a 0–23 hour value.
+ *
+ * @param hour - Hour value (0–23).
+ * @param options - Locale for the day-period label.
+ */
+export function formatDateTimeListPeriod(hour: number, options?: DateFormatOptions): string {
+  return formatDayPeriodFromHour(hour, options?.locale);
+}

package/src/dates/datetime/isLocaleHour12.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether the given locale conventionally uses a 12-hour clock (AM/PM).
+ *
+ * Derived from the locale's resolved hour cycle so date-time components can
+ * default their clock to the locale instead of hardcoding 12-hour. Pass an
+ * explicit `hour12` to override.
+ *
+ * @param locale - BCP-47 locale. Defaults to `en-US`.
+ * @returns `true` when the locale uses a 12-hour clock.
+ */
+export function isLocaleHour12(locale?: string): boolean {
+  try {
+    const resolved = new Intl.DateTimeFormat(locale ?? 'en-US', {
+      hour: 'numeric',
+    }).resolvedOptions() as { hour12?: boolean; hourCycle?: string };
+    if (typeof resolved.hour12 === 'boolean') {
+      return resolved.hour12;
+    }
+    return resolved.hourCycle === 'h11' || resolved.hourCycle === 'h12';
+  } catch {
+    return true;
+  }
+}

package/src/dates/datetime/isValidDateTimeId.ts

@@ -0,0 +1,18 @@
+import { isValid, parseISO } from 'date-fns';
+import type { DateTimeId } from '../types';
+
+const LOCAL_DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?$/;
+
+/**
+ * Type guard for local `DateTimeId` (`YYYY-MM-DDTHH:mm` or with seconds) and UTC `…Z` strings.
+ *
+ * @param dateTimeId - Candidate wire date-time string.
+ * @returns `true` when `dateTimeId` is a valid `DateTimeId`.
+ */
+export function isValidDateTimeId(dateTimeId: string): dateTimeId is DateTimeId {
+  if (!LOCAL_DATE_TIME_PATTERN.test(dateTimeId) && !dateTimeId.endsWith('Z')) {
+    return false;
+  }
+  const parsed = parseISO(dateTimeId);
+  return isValid(parsed);
+}