@cdx-ui/formatters 0.0.1-beta.132

package/src/dates/wire/monthId.ts

@@ -0,0 +1,42 @@
+import { asMonthId } from '../internal/brand';
+import type { MonthId } from '../types';
+import { formatMonthId } from './formatMonthId';
+import { isValidMonthId } from './isValidMonthId';
+import { isValidMonthParts } from './isValidMonthParts';
+
+/**
+ * Validating smart constructor for a wire {@link MonthId} (`YYYY-MM-01`).
+ *
+ * Accepts either a wire string or numeric parts. Throws `RangeError` on input
+ * that is not a valid month.
+ *
+ * @param iso - A wire month string (`YYYY-MM-01`).
+ * @returns The branded `MonthId`.
+ * @throws RangeError when the string is not a valid `MonthId`.
+ *
+ * @example
+ * monthId('2026-08-01'); // MonthId
+ * monthId(2026, 8);      // MonthId
+ */
+export function monthId(iso: string): MonthId;
+/**
+ * @param year - Full year (e.g. `2026`).
+ * @param month - Month `1`–`12`.
+ */
+export function monthId(year: number, month: number): MonthId;
+export function monthId(yearOrIso: string | number, month?: number): MonthId {
+  if (typeof yearOrIso === 'string') {
+    if (!isValidMonthId(yearOrIso)) {
+      throw new RangeError(
+        `Invalid MonthId: "${yearOrIso}". Expected the first of a month as "YYYY-MM-01".`,
+      );
+    }
+    return yearOrIso;
+  }
+
+  const parts = { year: yearOrIso, month: month ?? NaN };
+  if (!isValidMonthParts(parts)) {
+    throw new RangeError(`Invalid MonthId parts: ${JSON.stringify(parts)}. Month must be 1–12.`);
+  }
+  return asMonthId(formatMonthId(parts));
+}

package/src/dates/wire/parseDateId.ts

@@ -0,0 +1,20 @@
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import type { DateId, DateParts } from '../types';
+import { isValidDateId } from './isValidDateId';
+
+/**
+ * Parses a wire `DateId` into numeric parts, or `null` when invalid.
+ *
+ * @param dateId - Wire date string (`YYYY-MM-DD`).
+ * @returns Parsed parts, or `null` when `dateId` is invalid.
+ *
+ * @example
+ * parseDateId('2026-07-28') // { year: 2026, month: 7, day: 28 }
+ */
+export function parseDateId(dateId: DateId): DateParts | null {
+  if (!isValidDateId(dateId)) {
+    return null;
+  }
+  const date = dateIdToNativeDate(dateId);
+  return { year: date.getFullYear(), month: date.getMonth() + 1, day: date.getDate() };
+}

package/src/dates/wire/parseMonthId.ts

@@ -0,0 +1,20 @@
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import type { MonthId, MonthParts } from '../types';
+import { isValidMonthId } from './isValidMonthId';
+
+/**
+ * Parses a wire `MonthId` into numeric parts, or `null` when invalid.
+ *
+ * @param monthId - Wire month string (`YYYY-MM-01`).
+ * @returns Parsed parts, or `null` when `monthId` is invalid.
+ *
+ * @example
+ * parseMonthId('2026-07-01') // { year: 2026, month: 7 }
+ */
+export function parseMonthId(monthId: MonthId): MonthParts | null {
+  if (!isValidMonthId(monthId)) {
+    return null;
+  }
+  const date = dateIdToNativeDate(monthId);
+  return { year: date.getFullYear(), month: date.getMonth() + 1 };
+}

package/src/dates/wire/toMonthId.ts

@@ -0,0 +1,17 @@
+import { format, startOfMonth } from 'date-fns';
+import { asMonthId } from '../internal/brand';
+import { dateIdToNativeDate } from '../internal/dateIdToNativeDate';
+import type { DateId, MonthId } from '../types';
+
+/**
+ * Truncates a `DateId` to its month wire id.
+ *
+ * @param dateId - Wire date string.
+ * @returns Wire `MonthId` for the same calendar month.
+ *
+ * @example
+ * toMonthId('2026-07-28') // '2026-07-01'
+ */
+export function toMonthId(dateId: DateId): MonthId {
+  return asMonthId(format(startOfMonth(dateIdToNativeDate(dateId)), 'yyyy-MM-dd'));
+}

package/src/dates/wire/todayDateId.ts

@@ -0,0 +1,12 @@
+import { format } from 'date-fns';
+import { asDateId } from '../internal/brand';
+import type { DateId } from '../types';
+
+/**
+ * Returns the device-local calendar date as a wire `DateId`.
+ *
+ * @returns Today's date as `YYYY-MM-DD`.
+ */
+export function todayDateId(): DateId {
+  return asDateId(format(new Date(), 'yyyy-MM-dd'));
+}

package/src/dates/wire/todayMonthId.ts

@@ -0,0 +1,12 @@
+import { format, startOfMonth } from 'date-fns';
+import { asMonthId } from '../internal/brand';
+import type { MonthId } from '../types';
+
+/**
+ * Returns the device-local calendar month as a wire `MonthId`.
+ *
+ * @returns Current month as `YYYY-MM-01`.
+ */
+export function todayMonthId(): MonthId {
+  return asMonthId(format(startOfMonth(new Date()), 'yyyy-MM-dd'));
+}

package/src/formatNumber.ts

@@ -0,0 +1,56 @@
+import type { Nullable } from './types';
+import { toFiniteNumber } from './utils';
+
+export interface FormatNumberOptions {
+  locale?: Nullable<Intl.LocalesArgument>;
+  decimalPlaces?: Nullable<number>;
+}
+
+const formatterCache = new Map<string, Intl.NumberFormat>();
+
+/**
+ * Cache NumberFormat by locale/fraction digits.
+ * Constructing Intl formatters is expensive on RN/Hermes; reuse the instance and only call `.format`.
+ */
+function getDecimalFormatter(
+  locale: Intl.LocalesArgument,
+  decimalPlaces: number,
+): Intl.NumberFormat {
+  const key = `${String(locale)}|${String(decimalPlaces)}`;
+  let formatter = formatterCache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, {
+      style: 'decimal',
+      notation: 'standard',
+      minimumFractionDigits: decimalPlaces,
+      maximumFractionDigits: decimalPlaces,
+    });
+    formatterCache.set(key, formatter);
+  }
+  return formatter;
+}
+
+/**
+ * Formats a value as a number with decimal places for display.
+ *
+ * @param value - Value to format (`number`, plain numeric `string` like `'1234.56'`, `null`, or `undefined`).
+ * @param options - Formatting options.
+ * @param options.locale - BCP 47 locale; defaults to `en-US`.
+ * @param options.decimalPlaces - Fraction digits; defaults to `2`.
+ * @returns Locale-formatted decimal string, or `''` for nullish, blank, or non-numeric values.
+ *
+ * @example
+ * formatNumber(3247.19) // '3,247.19'
+ */
+export function formatNumber(
+  value: Nullable<number | string>,
+  options?: Nullable<FormatNumberOptions>,
+): string {
+  const locale = options?.locale ?? 'en-US';
+  const decimalPlaces = options?.decimalPlaces ?? 2;
+  const number = toFiniteNumber(value);
+  if (number == null) {
+    return '';
+  }
+  return getDecimalFormatter(locale, decimalPlaces).format(number);
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+export { formatNumber, type FormatNumberOptions } from './formatNumber';
+
+export type {
+  DateFieldMode,
+  DateFormatOptions,
+  DateId,
+  DateParts,
+  DateRangeDisplayOptions,
+  DateSegment,
+  DateSegmentType,
+  DateTimeGranularity,
+  DateTimeId,
+  DateTimeParts,
+  FormatDateDisplayOptions,
+  FormatDateTimeDisplayOptions,
+  MonthId,
+  MonthParts,
+  TimeParts,
+} from './dates/types';
+
+export {
+  // Wire values
+  clampDateParts,
+  clampMonthParts,
+  dateId,
+  monthId,
+  formatDateId,
+  formatMonthId,
+  isValidDateId,
+  isValidDateParts,
+  isValidMonthId,
+  isValidMonthParts,
+  parseDateId,
+  parseMonthId,
+  toMonthId,
+  todayDateId,
+  todayMonthId,
+  // Date-time wire
+  clampDateTimeId,
+  compareDateTimeIds,
+  dateTimeId,
+  formatDateTimeId,
+  isLocaleHour12,
+  isValidDateTimeId,
+  nowDateTimeId,
+  parseDateTimeId,
+  // Display (locale-aware)
+  formatDateForDisplay,
+  formatDateRangeForDisplay,
+  formatDateTimeForDisplay,
+  formatMonthForDisplay,
+  // Ranges
+  compareDateIds,
+  compareMonthIds,
+  dateRangeAroundDay,
+  dateRangeFromLastNDays,
+  eachDateIdInRange,
+  normalizeDateRange,
+  // Segmented field helpers
+  applyDateSegmentChange,
+  formatDateSegment,
+  getDateFieldSegments,
+  getDateTimeFieldSegments,
+  getDateTimeSegmentVisibility,
+  getEmptyDateSegmentText,
+  parseDateSegment,
+  // Calendar / list copy
+  formatCalendarMonthYear,
+  formatDateTimeListDateRow,
+  formatDateTimeListHour,
+  formatDateTimeListMinute,
+  formatDateTimeListPeriod,
+  formatMonthCalendarMonth,
+  formatMonthCalendarYear,
+  getCalendarWeekdayLabels,
+  DEFAULT_DATE_COMPONENT_LABELS,
+  formatSelectYear,
+  getDateSegmentAccessibilityLabel,
+  resolveDateComponentLabels,
+} from './dates';
+
+export type { DateComponentLabels } from './dates';

package/src/types.ts

@@ -0,0 +1 @@
+export type Nullable<T> = T | null | undefined;

package/src/utils.ts

@@ -0,0 +1,29 @@
+import type { Nullable } from './types';
+
+/**
+ * Coerce a nullable number/string to a finite number for display formatters.
+ *
+ * Hermes does not support the `signDisplay` property on iOS (and is unreliable on Android 11),
+ * so `-0` can still format as `"-0.00"`. Normalize before Intl to avoid this issue.
+ * @see https://github.com/facebook/hermes/blob/main/doc/IntlAPIs.md#limited-ios-property-support
+ */
+export function toFiniteNumber(value: Nullable<number | string>): number | undefined {
+  if (value == null) {
+    return undefined;
+  }
+  let number: number;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return undefined;
+    }
+    number = Number(trimmed);
+  } else {
+    number = value;
+  }
+  if (Number.isNaN(number)) {
+    return undefined;
+  }
+
+  return Object.is(number, -0) ? 0 : number;
+}