@cdx-ui/formatters 0.0.1-beta.132

package/src/dates/datetime/nowDateTimeId.ts

@@ -0,0 +1,53 @@
+import type { DateTimeGranularity, DateTimeId, DateTimeParts } from '../types';
+import { formatDateTimeId } from './formatDateTimeId';
+
+/**
+ * Returns the local device date/time as a `DateTimeId`, truncated to the requested granularity.
+ *
+ * @param options - Optional granularity; defaults to `'minute'`.
+ * @returns Wire `DateTimeId` for the current local time.
+ *
+ * @example
+ * nowDateTimeId({ granularity: 'minute' }) // '2026-07-28T14:30'
+ */
+export function nowDateTimeId(options?: { granularity?: DateTimeGranularity }): DateTimeId {
+  const now = new Date();
+  const parts: DateTimeParts = {
+    year: now.getFullYear(),
+    month: now.getMonth() + 1,
+    day: now.getDate(),
+    hour: now.getHours(),
+    minute: now.getMinutes(),
+    second: now.getSeconds(),
+  };
+
+  switch (options?.granularity ?? 'minute') {
+    case 'day':
+      return formatDateTimeId({
+        year: parts.year,
+        month: parts.month,
+        day: parts.day,
+        hour: 0,
+        minute: 0,
+      });
+    case 'hour':
+      return formatDateTimeId({
+        year: parts.year,
+        month: parts.month,
+        day: parts.day,
+        hour: parts.hour,
+        minute: 0,
+      });
+    case 'minute':
+      return formatDateTimeId({
+        year: parts.year,
+        month: parts.month,
+        day: parts.day,
+        hour: parts.hour,
+        minute: parts.minute,
+      });
+    case 'second':
+    default:
+      return formatDateTimeId(parts);
+  }
+}

package/src/dates/datetime/parseDateTimeId.ts

@@ -0,0 +1,24 @@
+import { parseISO } from 'date-fns';
+import type { DateTimeId, DateTimeParts } from '../types';
+import { isValidDateTimeId } from './isValidDateTimeId';
+
+/**
+ * Parses a wire `DateTimeId` into numeric parts, or `null` when invalid.
+ *
+ * @param dateTimeId - Wire date-time string.
+ * @returns Parsed parts, or `null` when `dateTimeId` is invalid.
+ */
+export function parseDateTimeId(dateTimeId: DateTimeId): DateTimeParts | null {
+  if (!isValidDateTimeId(dateTimeId)) {
+    return null;
+  }
+  const date = parseISO(dateTimeId);
+  return {
+    year: date.getFullYear(),
+    month: date.getMonth() + 1,
+    day: date.getDate(),
+    hour: date.getHours(),
+    minute: date.getMinutes(),
+    second: date.getSeconds(),
+  };
+}

package/src/dates/display/formatDateForDisplay.ts

@@ -0,0 +1,21 @@
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import { getCachedDateFormatter } from '../internal/intlCache';
+import type { DateId, FormatDateDisplayOptions } from '../types';
+
+/**
+ * Formats a locale-aware date string for UI labels (never store the result in form state).
+ *
+ * @param dateId - Wire date string (`YYYY-MM-DD`).
+ * @param options - Locale, date style, and optional time zone.
+ * @returns Locale-formatted date string.
+ *
+ * @example
+ * formatDateForDisplay('2026-07-28', { locale: 'en-US' }) // e.g. '7/28/26'
+ */
+export function formatDateForDisplay(dateId: DateId, options?: FormatDateDisplayOptions): string {
+  const formatter = getCachedDateFormatter(options?.locale ?? 'en-US', {
+    dateStyle: options?.dateStyle ?? 'short',
+    ...(options?.timeZone ? { timeZone: options.timeZone } : {}),
+  });
+  return formatter.format(dateIdToNativeDate(dateId));
+}

package/src/dates/display/formatDateRangeForDisplay.ts

@@ -0,0 +1,23 @@
+import { getDateRangeSeparator } from '../internal/intlCopy';
+import type { DateId, DateRangeDisplayOptions } from '../types';
+import { formatDateForDisplay } from './formatDateForDisplay';
+
+/**
+ * Formats an inclusive date range for display.
+ *
+ * @param range - Start and end wire date ids.
+ * @param options - Locale, separator, and display options passed to `formatDateForDisplay`.
+ * @returns Formatted range string.
+ *
+ * @example
+ * formatDateRangeForDisplay({ startId: '2026-07-01', endId: '2026-07-28' })
+ */
+export function formatDateRangeForDisplay(
+  range: { startId: DateId; endId: DateId },
+  options?: DateRangeDisplayOptions,
+): string {
+  const separator = options?.rangeSeparator ?? getDateRangeSeparator(options?.locale);
+  const start = formatDateForDisplay(range.startId, options);
+  const end = formatDateForDisplay(range.endId, options);
+  return `${start}${separator}${end}`;
+}

package/src/dates/display/formatDateTimeForDisplay.ts

@@ -0,0 +1,37 @@
+import { getCachedDateFormatter } from '../internal/intlCache';
+import { parseDateTimeId } from '../datetime/parseDateTimeId';
+import type { DateTimeId, FormatDateTimeDisplayOptions } from '../types';
+
+/**
+ * Formats a locale-aware date-time string for UI labels.
+ *
+ * @param dateTimeId - Wire date-time string.
+ * @param options - Locale, date/time styles, and optional time zone.
+ * @returns Locale-formatted date-time string, or `''` when invalid.
+ *
+ * @example
+ * formatDateTimeForDisplay('2026-07-28T10:01', { locale: 'en-US' })
+ */
+export function formatDateTimeForDisplay(
+  dateTimeId: DateTimeId,
+  options?: FormatDateTimeDisplayOptions,
+): string {
+  const parts = parseDateTimeId(dateTimeId);
+  if (!parts) {
+    return '';
+  }
+  const date = new Date(
+    parts.year,
+    parts.month - 1,
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second ?? 0,
+  );
+  const formatter = getCachedDateFormatter(options?.locale ?? 'en-US', {
+    dateStyle: options?.dateStyle ?? 'medium',
+    timeStyle: options?.timeStyle ?? 'short',
+    ...(options?.timeZone ? { timeZone: options.timeZone } : {}),
+  });
+  return formatter.format(date);
+}

package/src/dates/display/formatMonthForDisplay.ts

@@ -0,0 +1,26 @@
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import { getCachedDateFormatter } from '../internal/intlCache';
+import type { FormatDateDisplayOptions, MonthId } from '../types';
+
+/**
+ * Formats a locale-aware month/year string for UI labels.
+ *
+ * @param monthId - Wire month string (`YYYY-MM-01`).
+ * @param options - Locale, date style, and optional time zone.
+ * @returns Locale-formatted month/year string.
+ *
+ * @example
+ * formatMonthForDisplay('2026-07-01', { locale: 'en-US' }) // e.g. '07/2026'
+ */
+export function formatMonthForDisplay(
+  monthId: MonthId,
+  options?: FormatDateDisplayOptions,
+): string {
+  const formatter = getCachedDateFormatter(options?.locale ?? 'en-US', {
+    month: '2-digit',
+    year: 'numeric',
+    ...(options?.dateStyle === 'long' ? { month: 'long', year: 'numeric' } : {}),
+    ...(options?.timeZone ? { timeZone: options.timeZone } : {}),
+  });
+  return formatter.format(dateIdToNativeDate(monthId));
+}

package/src/dates/index.ts

@@ -0,0 +1,86 @@
+/**
+ * Date / date-time formatters.
+ *
+ * Wire ids (`DateId`, `MonthId`, `DateTimeId`) are fixed-format strings for state and APIs.
+ * Display helpers return locale-dependent strings for UI labels — never store those in form state.
+ */
+
+export type {
+  DateFieldMode,
+  DateFormatOptions,
+  DateId,
+  DateParts,
+  DateRangeDisplayOptions,
+  DateSegment,
+  DateSegmentType,
+  DateTimeGranularity,
+  DateTimeId,
+  DateTimeParts,
+  FormatDateDisplayOptions,
+  FormatDateTimeDisplayOptions,
+  MonthId,
+  MonthParts,
+  TimeParts,
+} from './types';
+
+export { clampDateParts } from './wire/clampDateParts';
+export { clampMonthParts } from './wire/clampMonthParts';
+export { dateId } from './wire/dateId';
+export { monthId } from './wire/monthId';
+export { formatDateId } from './wire/formatDateId';
+export { formatMonthId } from './wire/formatMonthId';
+export { isValidDateId } from './wire/isValidDateId';
+export { isValidDateParts } from './wire/isValidDateParts';
+export { isValidMonthId } from './wire/isValidMonthId';
+export { isValidMonthParts } from './wire/isValidMonthParts';
+export { parseDateId } from './wire/parseDateId';
+export { parseMonthId } from './wire/parseMonthId';
+export { toMonthId } from './wire/toMonthId';
+export { todayDateId } from './wire/todayDateId';
+export { todayMonthId } from './wire/todayMonthId';
+
+export { clampDateTimeId } from './datetime/clampDateTimeId';
+export { compareDateTimeIds } from './datetime/compareDateTimeIds';
+export { dateTimeId } from './datetime/dateTimeId';
+export { formatDateTimeId } from './datetime/formatDateTimeId';
+export { isLocaleHour12 } from './datetime/isLocaleHour12';
+export { formatDateTimeListHour } from './datetime/formatDateTimeListHour';
+export { formatDateTimeListMinute } from './datetime/formatDateTimeListMinute';
+export { formatDateTimeListPeriod } from './datetime/formatDateTimeListPeriod';
+export { isValidDateTimeId } from './datetime/isValidDateTimeId';
+export { nowDateTimeId } from './datetime/nowDateTimeId';
+export { parseDateTimeId } from './datetime/parseDateTimeId';
+
+export { formatDateForDisplay } from './display/formatDateForDisplay';
+export { formatDateRangeForDisplay } from './display/formatDateRangeForDisplay';
+export { formatDateTimeForDisplay } from './display/formatDateTimeForDisplay';
+export { formatMonthForDisplay } from './display/formatMonthForDisplay';
+
+export { compareDateIds } from './ranges/compareDateIds';
+export { compareMonthIds } from './ranges/compareMonthIds';
+export { dateRangeAroundDay } from './ranges/dateRangeAroundDay';
+export { dateRangeFromLastNDays } from './ranges/dateRangeFromLastNDays';
+export { eachDateIdInRange } from './ranges/eachDateIdInRange';
+export { normalizeDateRange } from './ranges/normalizeDateRange';
+
+export { applyDateSegmentChange } from './segments/applyDateSegmentChange';
+export { formatDateSegment } from './segments/formatDateSegment';
+export { getDateFieldSegments } from './segments/getDateFieldSegments';
+export { getDateTimeFieldSegments } from './segments/getDateTimeFieldSegments';
+export { getDateTimeSegmentVisibility } from './segments/getDateTimeSegmentVisibility';
+export { getEmptyDateSegmentText } from './segments/getEmptyDateSegmentText';
+export { parseDateSegment } from './segments/parseDateSegment';
+
+export { formatCalendarMonthYear } from './calendar/formatCalendarMonthYear';
+export { formatDateTimeListDateRow } from './calendar/formatDateTimeListDateRow';
+export { formatMonthCalendarMonth } from './calendar/formatMonthCalendarMonth';
+export { formatMonthCalendarYear } from './calendar/formatMonthCalendarYear';
+export { getCalendarWeekdayLabels } from './calendar/getCalendarWeekdayLabels';
+
+export type { DateComponentLabels } from './labels/dateComponentLabels';
+export {
+  DEFAULT_DATE_COMPONENT_LABELS,
+  formatSelectYear,
+  getDateSegmentAccessibilityLabel,
+  resolveDateComponentLabels,
+} from './labels/dateComponentLabels';

package/src/dates/internal/brand.ts

@@ -0,0 +1,11 @@
+import type { DateId, DateTimeId, MonthId } from '../types';
+
+/**
+ * @internal
+ * Unchecked brand casts for wire producers that have already guaranteed a
+ * well-formed wire string. Callers outside `@cdx-ui/formatters` must go through
+ * the validating smart constructors (`dateId`, `monthId`, `dateTimeId`) instead.
+ */
+export const asDateId = (value: string): DateId => value as DateId;
+export const asMonthId = (value: string): MonthId => value as MonthId;
+export const asDateTimeId = (value: string): DateTimeId => value as DateTimeId;

package/src/dates/internal/calendarHelpers.ts

@@ -0,0 +1,18 @@
+import type { DateFormatOptions } from '../types';
+import { getCachedDateFormatter } from './intlCache';
+
+/**
+ * @internal
+ */
+export function formatCalendarWeekday(
+  weekdayIndex: number,
+  options?: DateFormatOptions & { weekday?: 'short' | 'narrow' | 'long' },
+): string {
+  // 2023-01-01 was a Sunday — index 0..6 maps Sun..Sat regardless of locale week start.
+  const ref = new Date(2023, 0, 1 + weekdayIndex);
+  const formatter = getCachedDateFormatter(options?.locale ?? 'en-US', {
+    weekday: options?.weekday ?? 'short',
+    ...(options?.timeZone ? { timeZone: options.timeZone } : {}),
+  });
+  return formatter.format(ref);
+}

package/src/dates/internal/clampHelpers.ts

@@ -0,0 +1,15 @@
+import { getDaysInMonth } from 'date-fns';
+import type { DateParts } from '../types';
+
+export function partsToDate(parts: DateParts): Date {
+  return new Date(parts.year, parts.month - 1, parts.day);
+}
+
+export function clampMonth(month: number): number {
+  return Math.min(12, Math.max(1, month));
+}
+
+export function clampDay(year: number, month: number, day: number): number {
+  const maxDay = getDaysInMonth(new Date(year, month - 1, 1));
+  return Math.min(maxDay, Math.max(1, day));
+}

package/src/dates/internal/dateIdToNativeDate.ts

@@ -0,0 +1,15 @@
+import { parse } from 'date-fns';
+import type { DateId, MonthId } from '../types';
+
+/**
+ * Local calendar `Date` from a wire id. Never use `parseISO` for date-only ids
+ * (UTC midnight shifts the calendar day in western time zones).
+ *
+ * Accepts either a `DateId` or `MonthId` — both share the `YYYY-MM-DD` wire
+ * shape and only the date portion is parsed.
+ *
+ * @internal Not part of the public package API.
+ */
+export function dateIdToNativeDate(dateId: DateId | MonthId): Date {
+  return parse(dateId, 'yyyy-MM-dd', new Date());
+}

package/src/dates/internal/intlCache.ts

@@ -0,0 +1,40 @@
+import type { DateFormatOptions } from '../types';
+
+const formatterCache = new Map<string, Intl.DateTimeFormat>();
+
+function cacheKey(locale: string, options: Intl.DateTimeFormatOptions): string {
+  return `${locale}:${JSON.stringify(options)}`;
+}
+
+/**
+ * Cached `Intl.DateTimeFormat` factory for display helpers.
+ *
+ * @internal Not part of the public package API — prefer `formatDateForDisplay` and related helpers.
+ */
+export function createDateFormatter(
+  options: Intl.DateTimeFormatOptions & DateFormatOptions,
+): Intl.DateTimeFormat {
+  const { locale = 'en-US', timeZone, calendar, ...intlOptions } = options;
+  return new Intl.DateTimeFormat(locale, {
+    ...intlOptions,
+    ...(timeZone ? { timeZone } : {}),
+    ...(calendar ? { calendar } : {}),
+  });
+}
+
+/**
+ * @internal
+ */
+export function getCachedDateFormatter(
+  locale: string,
+  options: Intl.DateTimeFormatOptions & DateFormatOptions,
+): Intl.DateTimeFormat {
+  const key = cacheKey(locale, options);
+  const cached = formatterCache.get(key);
+  if (cached) {
+    return cached;
+  }
+  const formatter = createDateFormatter({ locale, ...options });
+  formatterCache.set(key, formatter);
+  return formatter;
+}

package/src/dates/internal/intlCopy.ts

@@ -0,0 +1,75 @@
+const DEFAULT_LOCALE = 'en-US';
+
+/**
+ * Locale-aware relative "today" label (e.g. `Today`, `aujourd'hui`).
+ * Falls back when `Intl.RelativeTimeFormat` is missing (Hermes / incomplete Intl).
+ */
+export function formatRelativeToday(locale = DEFAULT_LOCALE): string {
+  if (
+    typeof Intl !== 'undefined' &&
+    typeof (Intl as typeof Intl & { RelativeTimeFormat?: unknown }).RelativeTimeFormat ===
+      'function'
+  ) {
+    try {
+      return new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(0, 'day');
+    } catch {
+      // Incomplete Intl implementations can throw on construct/format.
+    }
+  }
+  return 'Today';
+}
+
+/** Locale-aware day-period label (AM/PM or locale equivalent) for a 0–23 hour value. */
+export function formatDayPeriodFromHour(hour: number, locale = DEFAULT_LOCALE): string {
+  const fallback = hour < 12 ? 'AM' : 'PM';
+  // Hermes (React Native) does not reliably ship `Intl.DateTimeFormat.prototype.formatToParts`;
+  // guard so native falls back to AM/PM instead of throwing.
+  if (
+    typeof Intl === 'undefined' ||
+    !('DateTimeFormat' in Intl) ||
+    !('formatToParts' in Intl.DateTimeFormat.prototype)
+  ) {
+    return fallback;
+  }
+  const sampleHour = hour < 12 ? 9 : 15;
+  const parts = new Intl.DateTimeFormat(locale, { hour: 'numeric', hour12: true }).formatToParts(
+    new Date(2000, 0, 1, sampleHour, 0),
+  );
+  return parts.find((part) => part.type === 'dayPeriod')?.value ?? fallback;
+}
+
+/** Locale-aware separator between two formatted dates in a range label. */
+export function getDateRangeSeparator(locale = DEFAULT_LOCALE): string {
+  if (
+    typeof Intl !== 'undefined' &&
+    'DateTimeFormat' in Intl &&
+    'formatRangeToParts' in Intl.DateTimeFormat.prototype
+  ) {
+    const formatter = new Intl.DateTimeFormat(locale);
+    const parts = formatter.formatRangeToParts(new Date(2000, 0, 15), new Date(2000, 0, 16));
+
+    let pastFirstYear = false;
+    let separator = '';
+    for (const part of parts) {
+      if (!pastFirstYear) {
+        if (part.type === 'year') {
+          pastFirstYear = true;
+        }
+        continue;
+      }
+      if (part.type === 'month' || part.type === 'day') {
+        break;
+      }
+      if (part.type === 'literal') {
+        separator += part.value;
+      }
+    }
+
+    const trimmed = separator.trim();
+    if (trimmed) {
+      return ` ${trimmed} `;
+    }
+  }
+
+  return ' – ';
+}

package/src/dates/internal/segmentBuilders.ts

@@ -0,0 +1,94 @@
+import type { DateFieldMode, DateSegment, DateSegmentType } from '../types';
+import { getCachedDateFormatter } from './intlCache';
+
+export const DATE_FIELD_FORMAT_OPTIONS: Record<DateFieldMode, Intl.DateTimeFormatOptions> = {
+  date: { year: 'numeric', month: '2-digit', day: '2-digit' },
+  month: { year: 'numeric', month: '2-digit' },
+};
+
+export const EMPTY_DATE_SEGMENT_TEXT: Partial<Record<DateSegmentType, string>> = {
+  year: 'YYYY',
+  month: 'MM',
+  day: 'DD',
+  hour: 'hh',
+  minute: 'mm',
+  second: 'ss',
+  dayPeriod: 'AM',
+};
+
+export const EMPTY_TIME_SEGMENT_TEXT: Record<'hour' | 'minute' | 'second' | 'dayPeriod', string> = {
+  hour: 'hh',
+  minute: 'mm',
+  second: 'ss',
+  dayPeriod: 'AM',
+};
+
+export function padSegment(type: DateSegmentType, value: number): string {
+  if (type === 'year') {
+    return String(value).padStart(4, '0');
+  }
+  if (type === 'month' || type === 'day' || type === 'minute' || type === 'second') {
+    return String(value).padStart(2, '0');
+  }
+  if (type === 'hour') {
+    return String(value).padStart(2, '0');
+  }
+  return String(value);
+}
+
+export function buildEmptyDateFieldSegments(mode: DateFieldMode, locale: string): DateSegment[] {
+  const formatter = getCachedDateFormatter(locale, DATE_FIELD_FORMAT_OPTIONS[mode]);
+  const intlParts = formatter.formatToParts(new Date(2000, 0, 15));
+  const segments: DateSegment[] = [];
+
+  for (const part of intlParts) {
+    if (part.type === 'literal') {
+      segments.push({ type: 'literal', text: part.value, isEditable: false });
+      continue;
+    }
+
+    if (part.type === 'year' || part.type === 'month' || (part.type === 'day' && mode === 'date')) {
+      segments.push({
+        type: part.type,
+        text: EMPTY_DATE_SEGMENT_TEXT[part.type] ?? part.value,
+        isEditable: true,
+      });
+    }
+  }
+
+  return segments;
+}
+
+export function buildDateFieldSegments(
+  values: { year: number; month: number; day: number },
+  mode: DateFieldMode,
+  locale: string,
+): DateSegment[] {
+  const formatter = getCachedDateFormatter(locale, DATE_FIELD_FORMAT_OPTIONS[mode]);
+  const refDate =
+    mode === 'month'
+      ? new Date(values.year, values.month - 1, 1)
+      : new Date(values.year, values.month - 1, values.day);
+  const intlParts = formatter.formatToParts(refDate);
+  const segments: DateSegment[] = [];
+
+  for (const part of intlParts) {
+    if (part.type === 'literal') {
+      segments.push({ type: 'literal', text: part.value, isEditable: false });
+      continue;
+    }
+
+    if (part.type === 'year' || part.type === 'month' || (part.type === 'day' && mode === 'date')) {
+      const value =
+        part.type === 'year' ? values.year : part.type === 'month' ? values.month : values.day;
+      segments.push({
+        type: part.type,
+        text: padSegment(part.type, value),
+        value,
+        isEditable: true,
+      });
+    }
+  }
+
+  return segments;
+}

package/src/dates/labels/dateComponentLabels.ts

@@ -0,0 +1,79 @@
+import type { DateSegmentType } from '../types';
+
+/** Overridable UI copy for date pickers, calendars, and segmented date fields. */
+export interface DateComponentLabels {
+  openDatePicker: string;
+  openDateTimePicker: string;
+  openDateRangePicker: string;
+  openMonthPicker: string;
+  showCalendar: string;
+  showYearPicker: string;
+  showMonths: string;
+  previousMonth: string;
+  nextMonth: string;
+  previousYear: string;
+  nextYear: string;
+  /** Use `{year}` as the year placeholder. */
+  selectYear: string;
+  dateFieldKeyboardInput: string;
+  segmentYear: string;
+  segmentMonth: string;
+  segmentDay: string;
+  segmentHour: string;
+  segmentMinute: string;
+  segmentSecond: string;
+  segmentDayPeriod: string;
+  rangeSeparator: string;
+}
+
+export const DEFAULT_DATE_COMPONENT_LABELS: DateComponentLabels = {
+  openDatePicker: 'Open date picker',
+  openDateTimePicker: 'Open date time picker',
+  openDateRangePicker: 'Open date range picker',
+  openMonthPicker: 'Open month picker',
+  showCalendar: 'Show calendar',
+  showYearPicker: 'Show year picker',
+  showMonths: 'Show months',
+  previousMonth: 'Previous month',
+  nextMonth: 'Next month',
+  previousYear: 'Previous year',
+  nextYear: 'Next year',
+  selectYear: 'Select year {year}',
+  dateFieldKeyboardInput: 'Date field keyboard input',
+  segmentYear: 'Year',
+  segmentMonth: 'Month',
+  segmentDay: 'Day',
+  segmentHour: 'Hour',
+  segmentMinute: 'Minute',
+  segmentSecond: 'Second',
+  segmentDayPeriod: 'AM/PM',
+  rangeSeparator: '–',
+};
+
+export function resolveDateComponentLabels(
+  partial?: Partial<DateComponentLabels>,
+): DateComponentLabels {
+  return { ...DEFAULT_DATE_COMPONENT_LABELS, ...partial };
+}
+
+export function formatSelectYear(labels: DateComponentLabels, year: number): string {
+  return labels.selectYear.replace('{year}', String(year));
+}
+
+const SEGMENT_LABEL_KEYS: Partial<Record<DateSegmentType, keyof DateComponentLabels>> = {
+  year: 'segmentYear',
+  month: 'segmentMonth',
+  day: 'segmentDay',
+  hour: 'segmentHour',
+  minute: 'segmentMinute',
+  second: 'segmentSecond',
+  dayPeriod: 'segmentDayPeriod',
+};
+
+export function getDateSegmentAccessibilityLabel(
+  type: DateSegmentType,
+  labels: DateComponentLabels,
+): string | undefined {
+  const key = SEGMENT_LABEL_KEYS[type];
+  return key ? labels[key] : undefined;
+}

package/src/dates/ranges/compareDateIds.ts

@@ -0,0 +1,21 @@
+import { compareAsc } from 'date-fns';
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import type { DateId } from '../types';
+
+/**
+ * Compares two wire dates.
+ *
+ * @param a - First wire date.
+ * @param b - Second wire date.
+ * @returns `-1` if `a` is earlier, `1` if later, `0` if equal.
+ */
+export function compareDateIds(a: DateId, b: DateId): -1 | 0 | 1 {
+  const result = compareAsc(dateIdToNativeDate(a), dateIdToNativeDate(b));
+  if (result < 0) {
+    return -1;
+  }
+  if (result > 0) {
+    return 1;
+  }
+  return 0;
+}

package/src/dates/ranges/compareMonthIds.ts

@@ -0,0 +1,26 @@
+import { parseMonthId } from '../wire/parseMonthId';
+import type { MonthId } from '../types';
+
+/**
+ * Compares two wire months chronologically.
+ *
+ * @param a - First wire month (`YYYY-MM-01`).
+ * @param b - Second wire month (`YYYY-MM-01`).
+ * @returns `-1` if `a` is earlier, `1` if later, `0` if equal or either is invalid.
+ */
+export function compareMonthIds(a: MonthId, b: MonthId): -1 | 0 | 1 {
+  const pa = parseMonthId(a);
+  const pb = parseMonthId(b);
+  if (!pa || !pb) {
+    return 0;
+  }
+  const av = pa.year * 12 + pa.month;
+  const bv = pb.year * 12 + pb.month;
+  if (av < bv) {
+    return -1;
+  }
+  if (av > bv) {
+    return 1;
+  }
+  return 0;
+}