@cdx-ui/formatters 0.0.1-beta.132

package/src/dates/ranges/dateRangeAroundDay.ts

@@ -0,0 +1,24 @@
+import { addDays, format, subDays } from 'date-fns';
+import { asDateId } from '../internal/brand';
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import type { DateId } from '../types';
+
+/**
+ * Builds an inclusive window of dates around an anchor (default: today).
+ *
+ * @param daysBefore - Number of days before the anchor (inclusive).
+ * @param daysAfter - Number of days after the anchor (inclusive).
+ * @param anchorDate - Optional anchor wire date; defaults to today.
+ * @returns Start and end wire date ids for the window.
+ */
+export function dateRangeAroundDay(
+  daysBefore: number,
+  daysAfter: number,
+  anchorDate?: DateId,
+): { startId: DateId; endId: DateId } {
+  const anchor = anchorDate ? dateIdToNativeDate(anchorDate) : new Date();
+  return {
+    startId: asDateId(format(subDays(anchor, daysBefore), 'yyyy-MM-dd')),
+    endId: asDateId(format(addDays(anchor, daysAfter), 'yyyy-MM-dd')),
+  };
+}

package/src/dates/ranges/dateRangeFromLastNDays.ts

@@ -0,0 +1,26 @@
+import { format, subDays } from 'date-fns';
+import { asDateId } from '../internal/brand';
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import type { DateId } from '../types';
+
+/**
+ * Builds an inclusive "last N days" preset ending on `endDate` (default: today).
+ *
+ * @param days - Number of calendar days in the range (inclusive of end).
+ * @param endDate - Optional end wire date; defaults to today.
+ * @returns Normalized start/end wire date ids.
+ *
+ * @example
+ * dateRangeFromLastNDays(30) // { startId, endId } spanning 30 calendar days
+ */
+export function dateRangeFromLastNDays(
+  days: number,
+  endDate?: DateId,
+): { startId: DateId; endId: DateId } {
+  const end = endDate ? dateIdToNativeDate(endDate) : new Date();
+  const start = subDays(end, days - 1);
+  return {
+    startId: asDateId(format(start, 'yyyy-MM-dd')),
+    endId: asDateId(format(end, 'yyyy-MM-dd')),
+  };
+}

package/src/dates/ranges/eachDateIdInRange.ts

@@ -0,0 +1,21 @@
+import { eachDayOfInterval, format } from 'date-fns';
+import { asDateId } from '../internal/brand';
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import type { DateId } from '../types';
+import { normalizeDateRange } from './normalizeDateRange';
+
+/**
+ * Returns an inclusive list of every `DateId` between start and end (order-normalized).
+ *
+ * @param startId - Range start wire date.
+ * @param endId - Range end wire date.
+ * @returns Array of wire `DateId` strings for each day in the range.
+ */
+export function eachDateIdInRange(startId: DateId, endId: DateId): DateId[] {
+  const normalized = normalizeDateRange({ startId, endId });
+  const days = eachDayOfInterval({
+    start: dateIdToNativeDate(normalized.startId),
+    end: dateIdToNativeDate(normalized.endId),
+  });
+  return days.map((day) => asDateId(format(day, 'yyyy-MM-dd')));
+}

package/src/dates/ranges/normalizeDateRange.ts

@@ -0,0 +1,18 @@
+import type { DateId } from '../types';
+import { compareDateIds } from './compareDateIds';
+
+/**
+ * Ensures `startId` ≤ `endId` by swapping when the range is inverted.
+ *
+ * @param range - Start and end wire date ids.
+ * @returns Normalized range with `startId` on or before `endId`.
+ */
+export function normalizeDateRange(range: { startId: DateId; endId: DateId }): {
+  startId: DateId;
+  endId: DateId;
+} {
+  if (compareDateIds(range.startId, range.endId) <= 0) {
+    return range;
+  }
+  return { startId: range.endId, endId: range.startId };
+}

package/src/dates/segments/applyDateSegmentChange.ts

@@ -0,0 +1,57 @@
+import { clampDateParts } from '../wire/clampDateParts';
+import { clampMonthParts } from '../wire/clampMonthParts';
+import type { DateFieldMode, DateParts, DateSegmentType, MonthParts } from '../types';
+
+/**
+ * Applies a single segment edit to complete date/month parts, clamping invalid days/months.
+ *
+ * Prefer this when updating a fully known value. Segmented `DateField` mid-entry uses
+ * partial parts internally and does not call this helper.
+ *
+ * @param current - Current parts, or `null` for defaults.
+ * @param segment - Segment type being edited.
+ * @param value - New numeric value for the segment.
+ * @param options - Field mode (`date` or `month`).
+ * @returns Updated parts, or `null` when input cannot be applied.
+ *
+ * @example
+ * applyDateSegmentChange(parseDateId('2026-01-31'), 'month', 2, { mode: 'date' })
+ * // → { year: 2026, month: 2, day: 28 }
+ */
+export function applyDateSegmentChange(
+  current: DateParts | MonthParts | null,
+  segment: DateSegmentType,
+  value: number,
+  options: { mode: DateFieldMode },
+): DateParts | MonthParts | null {
+  if (options.mode === 'month') {
+    const base: MonthParts =
+      current && 'month' in current && !('day' in current)
+        ? { year: current.year, month: current.month }
+        : { year: new Date().getFullYear(), month: 1 };
+
+    if (segment === 'month') {
+      return clampMonthParts({ ...base, month: value });
+    }
+    if (segment === 'year') {
+      return { ...base, year: value };
+    }
+    return base;
+  }
+
+  const base: DateParts =
+    current && 'day' in current
+      ? { year: current.year, month: current.month, day: current.day }
+      : { year: new Date().getFullYear(), month: 1, day: 1 };
+
+  if (segment === 'month') {
+    return clampDateParts({ ...base, month: value });
+  }
+  if (segment === 'day') {
+    return clampDateParts({ ...base, day: value });
+  }
+  if (segment === 'year') {
+    return clampDateParts({ ...base, year: value });
+  }
+  return base;
+}

package/src/dates/segments/formatDateSegment.ts

@@ -0,0 +1,18 @@
+import { padSegment } from '../internal/segmentBuilders';
+import type { DateSegmentType } from '../types';
+
+/**
+ * Formats a numeric segment value for display in a segmented date field.
+ *
+ * @param type - Segment type (year, month, day, etc.).
+ * @param value - Numeric segment value.
+ * @param _options - Reserved for future locale-aware formatting.
+ * @returns Padded segment text.
+ */
+export function formatDateSegment(
+  type: DateSegmentType,
+  value: number,
+  _options?: { locale?: string },
+): string {
+  return padSegment(type, value);
+}

package/src/dates/segments/getDateFieldSegments.ts

@@ -0,0 +1,45 @@
+import { asDateId, asMonthId } from '../internal/brand';
+import { buildDateFieldSegments, buildEmptyDateFieldSegments } from '../internal/segmentBuilders';
+import { parseDateId } from '../wire/parseDateId';
+import { parseMonthId } from '../wire/parseMonthId';
+import type { DateFieldMode, DateId, DateSegment, MonthId } from '../types';
+
+/**
+ * Builds ordered editable and literal segments for a date or month field from a wire value.
+ *
+ * @param value - Wire `DateId` or `MonthId`, or empty for placeholder segments.
+ * @param options - Field mode and optional locale.
+ * @returns Ordered `DateSegment` array matching locale field order.
+ */
+export function getDateFieldSegments(
+  value: DateId | MonthId | null | undefined,
+  options: { mode: DateFieldMode; locale?: string },
+): DateSegment[] {
+  const locale = options.locale ?? 'en-US';
+
+  if (!value) {
+    return buildEmptyDateFieldSegments(options.mode, locale);
+  }
+
+  if (options.mode === 'month') {
+    const parts = parseMonthId(asMonthId(value));
+    if (!parts) {
+      return buildEmptyDateFieldSegments('month', locale);
+    }
+    return buildDateFieldSegments(
+      { year: parts.year, month: parts.month, day: 1 },
+      'month',
+      locale,
+    );
+  }
+
+  const parts = parseDateId(asDateId(value));
+  if (!parts) {
+    return buildEmptyDateFieldSegments('date', locale);
+  }
+  return buildDateFieldSegments(
+    { year: parts.year, month: parts.month, day: parts.day },
+    'date',
+    locale,
+  );
+}

package/src/dates/segments/getDateTimeFieldSegments.ts

@@ -0,0 +1,126 @@
+import { formatDayPeriodFromHour } from '../internal/intlCopy';
+import { EMPTY_TIME_SEGMENT_TEXT, padSegment } from '../internal/segmentBuilders';
+import { formatDateId } from '../wire/formatDateId';
+import { isLocaleHour12 } from '../datetime/isLocaleHour12';
+import { parseDateTimeId } from '../datetime/parseDateTimeId';
+import type { DateSegment, DateTimeGranularity, DateTimeId } from '../types';
+import { getDateFieldSegments } from './getDateFieldSegments';
+import { getDateTimeSegmentVisibility } from './getDateTimeSegmentVisibility';
+
+/**
+ * Builds ordered segments for a date-time field for the given granularity.
+ *
+ * @param value - Wire `DateTimeId`, or empty for placeholder segments.
+ * @param options - Granularity, locale, and 12/24-hour preference.
+ * @returns Ordered `DateSegment` array including date and time parts.
+ */
+export function getDateTimeFieldSegments(
+  value: DateTimeId | null | undefined,
+  options: { granularity: DateTimeGranularity; locale?: string; hour12?: boolean },
+): DateSegment[] {
+  const parts = value ? parseDateTimeId(value) : null;
+  const locale = options.locale ?? 'en-US';
+  const hour12 = options.hour12 ?? isLocaleHour12(locale);
+  const segments: DateSegment[] = getDateFieldSegments(parts ? formatDateId(parts) : undefined, {
+    mode: 'date',
+    locale: options.locale,
+  });
+
+  if (options.granularity === 'day') {
+    return segments;
+  }
+
+  const { showMinute, showSecond } = getDateTimeSegmentVisibility(options.granularity);
+
+  if (!parts) {
+    segments.push({ type: 'literal', text: ' ', isEditable: false });
+    segments.push({
+      type: 'hour',
+      text: hour12 ? EMPTY_TIME_SEGMENT_TEXT.hour : 'HH',
+      isEditable: true,
+    });
+
+    if (showMinute) {
+      segments.push({ type: 'literal', text: ':', isEditable: false });
+      segments.push({
+        type: 'minute',
+        text: EMPTY_TIME_SEGMENT_TEXT.minute,
+        isEditable: true,
+      });
+    }
+
+    if (showSecond) {
+      segments.push({ type: 'literal', text: ':', isEditable: false });
+      segments.push({
+        type: 'second',
+        text: EMPTY_TIME_SEGMENT_TEXT.second,
+        isEditable: true,
+      });
+    }
+
+    if (hour12) {
+      segments.push({ type: 'literal', text: ' ', isEditable: false });
+      segments.push({
+        type: 'dayPeriod',
+        text: EMPTY_TIME_SEGMENT_TEXT.dayPeriod,
+        isEditable: true,
+      });
+    }
+
+    return segments;
+  }
+
+  const hour = parts.hour;
+  const minute = parts.minute;
+
+  segments.push({ type: 'literal', text: ' ', isEditable: false });
+  if (hour12) {
+    const hour12Value = hour % 12 || 12;
+    segments.push({
+      type: 'hour',
+      text: String(hour12Value),
+      value: hour12Value,
+      isEditable: true,
+    });
+  } else {
+    segments.push({
+      type: 'hour',
+      text: padSegment('hour', hour),
+      value: hour,
+      isEditable: true,
+    });
+  }
+
+  if (showMinute) {
+    segments.push({ type: 'literal', text: ':', isEditable: false });
+    segments.push({
+      type: 'minute',
+      text: padSegment('minute', minute),
+      value: minute,
+      isEditable: true,
+    });
+  }
+
+  if (showSecond) {
+    segments.push({ type: 'literal', text: ':', isEditable: false });
+    segments.push({
+      type: 'second',
+      text: padSegment('second', parts.second ?? 0),
+      value: parts.second ?? 0,
+      isEditable: true,
+    });
+  }
+
+  if (hour12) {
+    const isPm = hour >= 12;
+    segments.push({ type: 'literal', text: ' ', isEditable: false });
+    segments.push({
+      type: 'dayPeriod',
+      text: formatDayPeriodFromHour(isPm ? 13 : 9, locale),
+      value: isPm ? 1 : 0,
+      isEditable: true,
+    });
+  }
+
+  return segments;
+}

package/src/dates/segments/getDateTimeSegmentVisibility.ts

@@ -0,0 +1,14 @@
+import type { DateTimeGranularity } from '../types';
+
+/** Which time segments/columns are visible for a given `DateTimeGranularity`. */
+export function getDateTimeSegmentVisibility(granularity: DateTimeGranularity): {
+  showTime: boolean;
+  showMinute: boolean;
+  showSecond: boolean;
+} {
+  return {
+    showTime: granularity !== 'day',
+    showMinute: granularity === 'minute' || granularity === 'second',
+    showSecond: granularity === 'second',
+  };
+}

package/src/dates/segments/getEmptyDateSegmentText.ts

@@ -0,0 +1,12 @@
+import { EMPTY_DATE_SEGMENT_TEXT } from '../internal/segmentBuilders';
+import type { DateSegmentType } from '../types';
+
+/**
+ * Returns placeholder text for an empty editable segment (e.g. `MM`, `DD`, `YYYY`).
+ *
+ * @param type - Segment type.
+ * @returns Placeholder string, or `''` for types without a placeholder.
+ */
+export function getEmptyDateSegmentText(type: DateSegmentType): string {
+  return EMPTY_DATE_SEGMENT_TEXT[type] ?? '';
+}

package/src/dates/segments/parseDateSegment.ts

@@ -0,0 +1,25 @@
+import type { DateSegmentType } from '../types';
+
+/**
+ * Parses user-entered segment text into a number, or `null` when not parseable.
+ *
+ * @param type - Segment type being edited.
+ * @param text - Raw segment text from the field.
+ * @param _options - Reserved for future locale-aware parsing.
+ * @returns Parsed number, or `null` for empty or non-numeric input.
+ */
+export function parseDateSegment(
+  type: DateSegmentType,
+  text: string,
+  _options?: { locale?: string },
+): number | null {
+  const trimmed = text.trim();
+  if (!trimmed || type === 'literal' || type === 'dayPeriod') {
+    return null;
+  }
+  const parsed = Number(trimmed);
+  if (Number.isNaN(parsed)) {
+    return null;
+  }
+  return parsed;
+}

package/src/dates/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared option / parts types for date wire and display helpers.
+ *
+ * Wire brands: `DateId` (`YYYY-MM-DD`), `MonthId` (`YYYY-MM-01`), `DateTimeId` (local ISO-like).
+ *
+ * These are branded string types: a bare `string` no longer assigns to a `DateId`
+ * (etc.) prop. Produce values through the validating smart constructors
+ * (`dateId(...)`, `monthId(...)`, `dateTimeId(...)`) or the wire producers
+ * (`todayDateId()`, `parseDateId(...)`, `formatDateId(...)`, …), all exported from
+ * `@cdx-ui/formatters`. The brand is a compile-time-only tag — at runtime these are
+ * ordinary strings safe to serialize, store, and send over the wire.
+ */
+
+/** Wire date id (`YYYY-MM-DD`). Construct via `dateId(...)`, never a bare string. */
+export type DateId = string & { readonly __brand: 'DateId' };
+/** Wire month id (`YYYY-MM-01`). Construct via `monthId(...)`, never a bare string. */
+export type MonthId = string & { readonly __brand: 'MonthId' };
+/** Wire date-time id (local ISO-like, e.g. `YYYY-MM-DDTHH:mm`). Construct via `dateTimeId(...)`. */
+export type DateTimeId = string & { readonly __brand: 'DateTimeId' };
+
+export interface DateParts {
+  year: number;
+  month: number;
+  day: number;
+}
+
+export interface MonthParts {
+  year: number;
+  month: number;
+}
+
+export interface TimeParts {
+  hour: number;
+  minute: number;
+  second?: number;
+}
+
+export interface DateTimeParts extends DateParts, TimeParts {}
+
+export type DateFieldMode = 'date' | 'month';
+
+export type DateTimeGranularity = 'day' | 'hour' | 'minute' | 'second';
+
+export type DateSegmentType =
+  | 'era'
+  | 'year'
+  | 'month'
+  | 'day'
+  | 'hour'
+  | 'minute'
+  | 'second'
+  | 'dayPeriod'
+  | 'literal';
+
+export interface DateSegment {
+  type: DateSegmentType;
+  text: string;
+  value?: number;
+  isEditable: boolean;
+}
+
+export interface DateFormatOptions {
+  locale?: string;
+  timeZone?: string;
+  calendar?: string;
+}
+
+export interface FormatDateDisplayOptions extends DateFormatOptions {
+  dateStyle?: 'short' | 'medium' | 'long';
+}
+
+export interface FormatDateTimeDisplayOptions extends DateFormatOptions {
+  dateStyle?: 'short' | 'medium' | 'long';
+  timeStyle?: 'short' | 'medium';
+  granularity?: DateTimeGranularity;
+}
+
+export interface DateRangeDisplayOptions extends FormatDateDisplayOptions {
+  rangeSeparator?: string;
+}

package/src/dates/wire/clampDateParts.ts

@@ -0,0 +1,17 @@
+import { clampDay, clampMonth } from '../internal/clampHelpers';
+import type { DateParts } from '../types';
+
+/**
+ * Clamps date parts so month is 1–12 and day fits the month length (no `Date` rollover).
+ *
+ * @param parts - Year, month, and day values to clamp.
+ * @returns Clamped `DateParts` with a valid calendar day for the given month.
+ *
+ * @example
+ * clampDateParts({ year: 2026, month: 2, day: 31 }) // { year: 2026, month: 2, day: 28 }
+ */
+export function clampDateParts(parts: DateParts): DateParts {
+  const month = clampMonth(parts.month);
+  const day = clampDay(parts.year, month, parts.day);
+  return { year: parts.year, month, day };
+}

package/src/dates/wire/clampMonthParts.ts

@@ -0,0 +1,15 @@
+import { clampMonth } from '../internal/clampHelpers';
+import type { MonthParts } from '../types';
+
+/**
+ * Clamps month parts so month is between 1 and 12.
+ *
+ * @param parts - Year and month values to clamp.
+ * @returns Clamped `MonthParts`.
+ *
+ * @example
+ * clampMonthParts({ year: 2026, month: 13 }) // { year: 2026, month: 12 }
+ */
+export function clampMonthParts(parts: MonthParts): MonthParts {
+  return { year: parts.year, month: clampMonth(parts.month) };
+}

package/src/dates/wire/dateId.ts

@@ -0,0 +1,44 @@
+import { asDateId } from '../internal/brand';
+import type { DateId } from '../types';
+import { formatDateId } from './formatDateId';
+import { isValidDateId } from './isValidDateId';
+import { isValidDateParts } from './isValidDateParts';
+
+/**
+ * Validating smart constructor for a wire {@link DateId} (`YYYY-MM-DD`).
+ *
+ * Accepts either a wire string or numeric parts. Throws `RangeError` on input
+ * that is not a real calendar date — use this at the boundary where you first
+ * introduce a date value so a bad id never enters your form state.
+ *
+ * @param iso - A wire date string (`YYYY-MM-DD`).
+ * @returns The branded `DateId`.
+ * @throws RangeError when the string is not a valid `DateId`.
+ *
+ * @example
+ * dateId('2026-08-07'); // DateId
+ * dateId(2026, 8, 7);   // DateId
+ */
+export function dateId(iso: string): DateId;
+/**
+ * @param year - Full year (e.g. `2026`).
+ * @param month - Month `1`–`12`.
+ * @param day - Day of month `1`–`31`.
+ */
+export function dateId(year: number, month: number, day: number): DateId;
+export function dateId(yearOrIso: string | number, month?: number, day?: number): DateId {
+  if (typeof yearOrIso === 'string') {
+    if (!isValidDateId(yearOrIso)) {
+      throw new RangeError(
+        `Invalid DateId: "${yearOrIso}". Expected a real calendar date as "YYYY-MM-DD".`,
+      );
+    }
+    return yearOrIso;
+  }
+
+  const parts = { year: yearOrIso, month: month ?? NaN, day: day ?? NaN };
+  if (!isValidDateParts(parts)) {
+    throw new RangeError(`Invalid DateId parts: ${JSON.stringify(parts)}.`);
+  }
+  return asDateId(formatDateId(parts));
+}

package/src/dates/wire/formatDateId.ts

@@ -0,0 +1,20 @@
+import { asDateId } from '../internal/brand';
+import type { DateId, DateParts } from '../types';
+import { clampDateParts } from './clampDateParts';
+
+/**
+ * Builds a wire `DateId`, clamping day to the month length (no `Date` rollover).
+ *
+ * @param parts - Year, month, and day values.
+ * @returns Wire `DateId` string (`YYYY-MM-DD`).
+ *
+ * @example
+ * formatDateId({ year: 2026, month: 7, day: 28 }) // '2026-07-28'
+ */
+export function formatDateId(parts: DateParts): DateId {
+  const clamped = clampDateParts(parts);
+  const year = String(clamped.year).padStart(4, '0');
+  const month = String(clamped.month).padStart(2, '0');
+  const day = String(clamped.day).padStart(2, '0');
+  return asDateId(`${year}-${month}-${day}`);
+}

package/src/dates/wire/formatMonthId.ts

@@ -0,0 +1,16 @@
+import { format } from 'date-fns';
+import { asMonthId } from '../internal/brand';
+import type { MonthId, MonthParts } from '../types';
+
+/**
+ * Builds a wire `MonthId` (`YYYY-MM-01`).
+ *
+ * @param parts - Year and month values.
+ * @returns Wire `MonthId` string.
+ *
+ * @example
+ * formatMonthId({ year: 2026, month: 7 }) // '2026-07-01'
+ */
+export function formatMonthId(parts: MonthParts): MonthId {
+  return asMonthId(format(new Date(parts.year, parts.month - 1, 1), 'yyyy-MM-dd'));
+}

package/src/dates/wire/isValidDateId.ts

@@ -0,0 +1,22 @@
+import { format, isValid, parse } from 'date-fns';
+import type { DateId } from '../types';
+
+const DATE_ID_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Type guard for wire `DateId` strings (`YYYY-MM-DD`).
+ *
+ * @param dateId - Candidate wire date string.
+ * @returns `true` when `dateId` is a valid `DateId`.
+ *
+ * @example
+ * isValidDateId('2026-07-28') // true
+ * isValidDateId('07/28/2026') // false
+ */
+export function isValidDateId(dateId: string): dateId is DateId {
+  if (!DATE_ID_PATTERN.test(dateId)) {
+    return false;
+  }
+  const parsed = parse(dateId, 'yyyy-MM-dd', new Date());
+  return isValid(parsed) && format(parsed, 'yyyy-MM-dd') === dateId;
+}

package/src/dates/wire/isValidDateParts.ts

@@ -0,0 +1,17 @@
+import { partsToDate } from '../internal/clampHelpers';
+import type { DateParts } from '../types';
+
+/**
+ * Returns whether the given parts form a valid calendar date.
+ *
+ * @param parts - Year, month, and day values to validate.
+ * @returns `true` when the parts match a real calendar date.
+ */
+export function isValidDateParts(parts: DateParts): boolean {
+  const date = partsToDate(parts);
+  return (
+    date.getFullYear() === parts.year &&
+    date.getMonth() === parts.month - 1 &&
+    date.getDate() === parts.day
+  );
+}

package/src/dates/wire/isValidMonthId.ts

@@ -0,0 +1,22 @@
+import { format, isValid, parse } from 'date-fns';
+import type { MonthId } from '../types';
+
+const MONTH_ID_PATTERN = /^\d{4}-\d{2}-01$/;
+
+/**
+ * Type guard for wire `MonthId` strings (`YYYY-MM-01`).
+ *
+ * @param monthId - Candidate wire month string.
+ * @returns `true` when `monthId` is a valid `MonthId`.
+ *
+ * @example
+ * isValidMonthId('2026-07-01') // true
+ * isValidMonthId('2026-07-15') // false
+ */
+export function isValidMonthId(monthId: string): monthId is MonthId {
+  if (!MONTH_ID_PATTERN.test(monthId)) {
+    return false;
+  }
+  const parsed = parse(monthId, 'yyyy-MM-dd', new Date());
+  return isValid(parsed) && format(parsed, 'yyyy-MM-dd') === monthId;
+}

package/src/dates/wire/isValidMonthParts.ts

@@ -0,0 +1,11 @@
+import type { MonthParts } from '../types';
+
+/**
+ * Returns whether the given parts form a valid month (1–12).
+ *
+ * @param parts - Year and month values to validate.
+ * @returns `true` when month is between 1 and 12.
+ */
+export function isValidMonthParts(parts: MonthParts): boolean {
+  return parts.month >= 1 && parts.month <= 12;
+}