@cdx-ui/formatters 0.0.1-beta.132

package/lib/typescript/dates/wire/parseMonthId.d.ts

@@ -0,0 +1,12 @@
+import type { MonthId, MonthParts } from '../types';
+/**
+ * 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 declare function parseMonthId(monthId: MonthId): MonthParts | null;
+//# sourceMappingURL=parseMonthId.d.ts.map

package/lib/typescript/dates/wire/parseMonthId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseMonthId.d.ts","sourceRoot":"","sources":["../../../../src/dates/wire/parseMonthId.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGpD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAMhE"}

package/lib/typescript/dates/wire/toMonthId.d.ts

@@ -0,0 +1,12 @@
+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 declare function toMonthId(dateId: DateId): MonthId;
+//# sourceMappingURL=toMonthId.d.ts.map

package/lib/typescript/dates/wire/toMonthId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toMonthId.d.ts","sourceRoot":"","sources":["../../../../src/dates/wire/toMonthId.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/lib/typescript/dates/wire/todayDateId.d.ts

@@ -0,0 +1,8 @@
+import type { DateId } from '../types';
+/**
+ * Returns the device-local calendar date as a wire `DateId`.
+ *
+ * @returns Today's date as `YYYY-MM-DD`.
+ */
+export declare function todayDateId(): DateId;
+//# sourceMappingURL=todayDateId.d.ts.map

package/lib/typescript/dates/wire/todayDateId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todayDateId.d.ts","sourceRoot":"","sources":["../../../../src/dates/wire/todayDateId.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}

package/lib/typescript/dates/wire/todayMonthId.d.ts

@@ -0,0 +1,8 @@
+import type { MonthId } from '../types';
+/**
+ * Returns the device-local calendar month as a wire `MonthId`.
+ *
+ * @returns Current month as `YYYY-MM-01`.
+ */
+export declare function todayMonthId(): MonthId;
+//# sourceMappingURL=todayMonthId.d.ts.map

package/lib/typescript/dates/wire/todayMonthId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todayMonthId.d.ts","sourceRoot":"","sources":["../../../../src/dates/wire/todayMonthId.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC"}

package/lib/typescript/formatNumber.d.ts

@@ -0,0 +1,19 @@
+import type { Nullable } from './types';
+export interface FormatNumberOptions {
+    locale?: Nullable<Intl.LocalesArgument>;
+    decimalPlaces?: Nullable<number>;
+}
+/**
+ * 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 declare function formatNumber(value: Nullable<number | string>, options?: Nullable<FormatNumberOptions>): string;
+//# sourceMappingURL=formatNumber.d.ts.map

package/lib/typescript/formatNumber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatNumber.d.ts","sourceRoot":"","sources":["../../src/formatNumber.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACxC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAClC;AA0BD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,EAChC,OAAO,CAAC,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GACtC,MAAM,CAQR"}

package/lib/typescript/index.d.ts

@@ -0,0 +1,5 @@
+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 { clampDateParts, clampMonthParts, dateId, monthId, formatDateId, formatMonthId, isValidDateId, isValidDateParts, isValidMonthId, isValidMonthParts, parseDateId, parseMonthId, toMonthId, todayDateId, todayMonthId, clampDateTimeId, compareDateTimeIds, dateTimeId, formatDateTimeId, isLocaleHour12, isValidDateTimeId, nowDateTimeId, parseDateTimeId, formatDateForDisplay, formatDateRangeForDisplay, formatDateTimeForDisplay, formatMonthForDisplay, compareDateIds, compareMonthIds, dateRangeAroundDay, dateRangeFromLastNDays, eachDateIdInRange, normalizeDateRange, applyDateSegmentChange, formatDateSegment, getDateFieldSegments, getDateTimeFieldSegments, getDateTimeSegmentVisibility, getEmptyDateSegmentText, parseDateSegment, formatCalendarMonthYear, formatDateTimeListDateRow, formatDateTimeListHour, formatDateTimeListMinute, formatDateTimeListPeriod, formatMonthCalendarMonth, formatMonthCalendarYear, getCalendarWeekdayLabels, DEFAULT_DATE_COMPONENT_LABELS, formatSelectYear, getDateSegmentAccessibilityLabel, resolveDateComponentLabels, } from './dates';
+export type { DateComponentLabels } from './dates';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAExE,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,MAAM,EACN,SAAS,EACT,uBAAuB,EACvB,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,aAAa,EACb,wBAAwB,EACxB,4BAA4B,EAC5B,OAAO,EACP,UAAU,EACV,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EAEL,cAAc,EACd,eAAe,EACf,MAAM,EACN,OAAO,EACP,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,WAAW,EACX,YAAY,EAEZ,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,eAAe,EAEf,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,EACxB,qBAAqB,EAErB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAElB,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,4BAA4B,EAC5B,uBAAuB,EACvB,gBAAgB,EAEhB,uBAAuB,EACvB,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,EAC7B,gBAAgB,EAChB,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,SAAS,CAAC;AAEjB,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC"}

package/lib/typescript/types.d.ts

@@ -0,0 +1,2 @@
+export type Nullable<T> = T | null | undefined;
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC"}

package/lib/typescript/utils.d.ts

@@ -0,0 +1,10 @@
+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 declare function toFiniteNumber(value: Nullable<number | string>): number | undefined;
+//# sourceMappingURL=utils.d.ts.map

package/lib/typescript/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAmBnF"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@cdx-ui/formatters",
+  "version": "0.0.1-beta.132",
+  "main": "lib/commonjs/index.js",
+  "module": "lib/module/index.js",
+  "react-native": "src/index.ts",
+  "types": "lib/typescript/index.d.ts",
+  "source": "src/index.ts",
+  "exports": {
+    ".": {
+      "react-native": "./src/index.ts",
+      "types": "./lib/typescript/index.d.ts",
+      "import": "./lib/module/index.js",
+      "require": "./lib/commonjs/index.js",
+      "default": "./lib/module/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "exclude": "**/{__tests__/**,__fixtures__/**,__mocks__/**,*.test.ts,*.test.tsx,*.spec.ts,*.spec.tsx}",
+    "targets": [
+      "commonjs",
+      "module",
+      "typescript"
+    ]
+  },
+  "dependencies": {
+    "date-fns": "4.1.0"
+  },
+  "nx": {
+    "tags": [
+      "type:lib",
+      "scope:formatters"
+    ]
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bob build",
+    "lint": "eslint src/",
+    "test": "jest --config ../../jest.config.js --selectProjects formatters"
+  }
+}

package/src/__tests__/applyDateSegmentChange.test.ts

@@ -0,0 +1,26 @@
+import { applyDateSegmentChange } from '../dates/segments/applyDateSegmentChange';
+import { formatDateId } from '../dates/wire/formatDateId';
+import { parseDateId } from '../dates/wire/parseDateId';
+import { parseMonthId } from '../dates/wire/parseMonthId';
+
+describe('applyDateSegmentChange', () => {
+  it('clamps day when month segment changes to a shorter month', () => {
+    const current = parseDateId('2026-01-31');
+    const next = applyDateSegmentChange(current, 'month', 2, { mode: 'date' });
+    const expected = { year: 2026, month: 2, day: 28 };
+    expect(next).toEqual(expected);
+    expect(formatDateId(expected)).toBe('2026-02-28');
+  });
+
+  it('clamps day segment to the current month length', () => {
+    const current = parseDateId('2026-02-01');
+    const next = applyDateSegmentChange(current, 'day', 31, { mode: 'date' });
+    expect(next).toEqual({ year: 2026, month: 2, day: 28 });
+  });
+
+  it('clamps month segment in month mode', () => {
+    const current = parseMonthId('2026-07-01');
+    const next = applyDateSegmentChange(current, 'month', 13, { mode: 'month' });
+    expect(next).toEqual({ year: 2026, month: 12 });
+  });
+});

package/src/__tests__/calendarFormatters.test.ts

@@ -0,0 +1,35 @@
+import { formatMonthCalendarYear } from '../dates/calendar/formatMonthCalendarYear';
+import { getCalendarWeekdayLabels } from '../dates/calendar/getCalendarWeekdayLabels';
+import { formatDateTimeListDateRow } from '../dates/calendar/formatDateTimeListDateRow';
+import { formatDateTimeListHour } from '../dates/datetime/formatDateTimeListHour';
+import { formatDateTimeListMinute } from '../dates/datetime/formatDateTimeListMinute';
+import { formatDateTimeListPeriod } from '../dates/datetime/formatDateTimeListPeriod';
+
+describe('calendar formatters', () => {
+  it('formats month calendar year as string', () => {
+    expect(formatMonthCalendarYear(2026)).toBe('2026');
+  });
+
+  it('returns seven weekday labels starting from first day of week', () => {
+    const labels = getCalendarWeekdayLabels({ locale: 'en-US', firstDayOfWeek: 1 });
+    expect(labels).toHaveLength(7);
+    expect(labels.every((label) => label.length > 0)).toBe(true);
+  });
+
+  it('formats date list row with today override', () => {
+    expect(
+      formatDateTimeListDateRow('2026-07-28', { locale: 'en-US', todayDateId: '2026-07-28' }),
+    ).toBeTruthy();
+  });
+
+  it('formats date list row for non-today dates', () => {
+    expect(formatDateTimeListDateRow('2026-01-15', { locale: 'en-US' })).toContain('15');
+  });
+
+  it('formats date-time list hour, minute, and period', () => {
+    expect(formatDateTimeListHour(14, { hour12: true })).toBe('2');
+    expect(formatDateTimeListHour(14)).toBe('14');
+    expect(formatDateTimeListMinute(30)).toBe('30');
+    expect(formatDateTimeListPeriod(14, { locale: 'en-US' })).toMatch(/PM/i);
+  });
+});

package/src/__tests__/clampDateParts.test.ts

@@ -0,0 +1,16 @@
+import { clampDateParts } from '../dates/wire/clampDateParts';
+
+describe('clampDateParts', () => {
+  it('clamps date parts to the month length', () => {
+    expect(clampDateParts({ year: 2026, month: 2, day: 31 })).toEqual({
+      year: 2026,
+      month: 2,
+      day: 28,
+    });
+    expect(clampDateParts({ year: 2024, month: 2, day: 31 })).toEqual({
+      year: 2024,
+      month: 2,
+      day: 29,
+    });
+  });
+});

package/src/__tests__/compareDateIds.test.ts

@@ -0,0 +1,7 @@
+import { compareDateIds } from '../dates/ranges/compareDateIds';
+
+describe('compareDateIds', () => {
+  it('compares date ids', () => {
+    expect(compareDateIds('2026-07-01', '2026-07-28')).toBe(-1);
+  });
+});

package/src/__tests__/compareMonthIds.test.ts

@@ -0,0 +1,19 @@
+import { compareMonthIds } from '../dates/ranges/compareMonthIds';
+
+describe('compareMonthIds', () => {
+  it('returns -1 when first month is earlier', () => {
+    expect(compareMonthIds('2026-01-01', '2026-07-01')).toBe(-1);
+  });
+
+  it('returns 1 when first month is later', () => {
+    expect(compareMonthIds('2026-12-01', '2026-07-01')).toBe(1);
+  });
+
+  it('returns 0 for equal months', () => {
+    expect(compareMonthIds('2026-07-01', '2026-07-01')).toBe(0);
+  });
+
+  it('returns 0 when either month is invalid', () => {
+    expect(compareMonthIds('invalid', '2026-07-01')).toBe(0);
+  });
+});

package/src/__tests__/dateComponentLabels.test.ts

@@ -0,0 +1,25 @@
+import {
+  DEFAULT_DATE_COMPONENT_LABELS,
+  formatSelectYear,
+  getDateSegmentAccessibilityLabel,
+  resolveDateComponentLabels,
+} from '../dates/labels/dateComponentLabels';
+
+describe('dateComponentLabels', () => {
+  it('merges partial overrides with defaults', () => {
+    const labels = resolveDateComponentLabels({ previousMonth: 'Back' });
+    expect(labels.previousMonth).toBe('Back');
+    expect(labels.nextMonth).toBe(DEFAULT_DATE_COMPONENT_LABELS.nextMonth);
+  });
+
+  it('formats select year with placeholder', () => {
+    const labels = resolveDateComponentLabels();
+    expect(formatSelectYear(labels, 2030)).toBe('Select year 2030');
+  });
+
+  it('maps segment types to accessibility labels', () => {
+    const labels = resolveDateComponentLabels();
+    expect(getDateSegmentAccessibilityLabel('month', labels)).toBe('Month');
+    expect(getDateSegmentAccessibilityLabel('literal', labels)).toBeUndefined();
+  });
+});

package/src/__tests__/dateRangeAroundDay.test.ts

@@ -0,0 +1,10 @@
+import { dateRangeAroundDay } from '../dates/ranges/dateRangeAroundDay';
+
+describe('dateRangeAroundDay', () => {
+  it('builds a window around an anchor day', () => {
+    expect(dateRangeAroundDay(1, 1, '2026-07-28')).toEqual({
+      startId: '2026-07-27',
+      endId: '2026-07-29',
+    });
+  });
+});

package/src/__tests__/dateRangeFromLastNDays.test.ts

@@ -0,0 +1,8 @@
+import { dateRangeFromLastNDays } from '../dates/ranges/dateRangeFromLastNDays';
+
+describe('dateRangeFromLastNDays', () => {
+  it('builds last N days preset inclusive of end', () => {
+    const range = dateRangeFromLastNDays(3, '2026-07-30');
+    expect(range).toEqual({ startId: '2026-07-28', endId: '2026-07-30' });
+  });
+});

package/src/__tests__/dateSegmentHelpers.test.ts

@@ -0,0 +1,24 @@
+import { getEmptyDateSegmentText } from '../dates/segments/getEmptyDateSegmentText';
+import { formatDateSegment } from '../dates/segments/formatDateSegment';
+import { parseDateSegment } from '../dates/segments/parseDateSegment';
+
+describe('date segment helpers', () => {
+  it('returns placeholder text for empty segments', () => {
+    expect(getEmptyDateSegmentText('month')).toBe('MM');
+    expect(getEmptyDateSegmentText('day')).toBe('DD');
+    expect(getEmptyDateSegmentText('year')).toBe('YYYY');
+    expect(getEmptyDateSegmentText('literal')).toBe('');
+  });
+
+  it('formats segment values with padding', () => {
+    expect(formatDateSegment('month', 7)).toBe('07');
+    expect(formatDateSegment('year', 2026)).toBe('2026');
+  });
+
+  it('parses segment text to numbers', () => {
+    expect(parseDateSegment('month', '07')).toBe(7);
+    expect(parseDateSegment('day', '')).toBeNull();
+    expect(parseDateSegment('literal', ' / ')).toBeNull();
+    expect(parseDateSegment('month', 'abc')).toBeNull();
+  });
+});

package/src/__tests__/datetimeHelpers.test.ts

@@ -0,0 +1,65 @@
+import { compareDateTimeIds } from '../dates/datetime/compareDateTimeIds';
+import { clampDateTimeId } from '../dates/datetime/clampDateTimeId';
+import { nowDateTimeId } from '../dates/datetime/nowDateTimeId';
+import { isLocaleHour12 } from '../dates/datetime/isLocaleHour12';
+
+describe('datetime helpers', () => {
+  describe('compareDateTimeIds', () => {
+    it('compares chronologically', () => {
+      expect(compareDateTimeIds('2026-07-01T09:00', '2026-07-01T10:00')).toBe(-1);
+      expect(compareDateTimeIds('2026-07-02T09:00', '2026-07-01T10:00')).toBe(1);
+      expect(compareDateTimeIds('2026-07-01T10:00', '2026-07-01T10:00')).toBe(0);
+    });
+  });
+
+  describe('clampDateTimeId', () => {
+    it('clamps to inclusive bounds', () => {
+      expect(
+        clampDateTimeId('2026-01-01T00:00', {
+          min: '2026-07-01T00:00',
+          max: '2026-12-31T23:59',
+        }),
+      ).toBe('2026-07-01T00:00');
+      expect(
+        clampDateTimeId('2027-01-01T00:00', {
+          min: '2026-07-01T00:00',
+          max: '2026-12-31T23:59',
+        }),
+      ).toBe('2026-12-31T23:59');
+      expect(
+        clampDateTimeId('2026-08-01T12:00', {
+          min: '2026-07-01T00:00',
+          max: '2026-12-31T23:59',
+        }),
+      ).toBe('2026-08-01T12:00');
+    });
+  });
+
+  describe('nowDateTimeId', () => {
+    beforeEach(() => {
+      jest.useFakeTimers();
+      jest.setSystemTime(new Date(2026, 6, 28, 14, 30, 45));
+    });
+
+    afterEach(() => {
+      jest.useRealTimers();
+    });
+
+    it('returns current local time truncated by granularity', () => {
+      expect(nowDateTimeId({ granularity: 'minute' })).toBe('2026-07-28T14:30');
+      expect(nowDateTimeId({ granularity: 'hour' })).toBe('2026-07-28T14:00');
+      expect(nowDateTimeId({ granularity: 'day' })).toBe('2026-07-28T00:00');
+      expect(nowDateTimeId({ granularity: 'second' })).toBe('2026-07-28T14:30:45');
+    });
+  });
+
+  describe('isLocaleHour12', () => {
+    it('detects 12-hour locales', () => {
+      expect(isLocaleHour12('en-US')).toBe(true);
+    });
+
+    it('falls back to true on invalid locale', () => {
+      expect(isLocaleHour12('invalid-locale-xyz')).toBe(true);
+    });
+  });
+});

package/src/__tests__/displayFormatters.test.ts

@@ -0,0 +1,34 @@
+import { formatDateRangeForDisplay } from '../dates/display/formatDateRangeForDisplay';
+import { formatMonthForDisplay } from '../dates/display/formatMonthForDisplay';
+import { formatDateTimeForDisplay } from '../dates/display/formatDateTimeForDisplay';
+
+describe('display formatters', () => {
+  it('formats date range for display', () => {
+    const result = formatDateRangeForDisplay({
+      startId: '2026-07-01',
+      endId: '2026-07-28',
+    });
+    expect(result).toContain('7/1');
+    expect(result).toMatch(/–|—|-|to/i);
+  });
+
+  it('uses custom range separator when provided', () => {
+    const result = formatDateRangeForDisplay(
+      { startId: '2026-07-01', endId: '2026-07-28' },
+      { rangeSeparator: ' to ' },
+    );
+    expect(result).toContain(' to ');
+  });
+
+  it('formats month for display', () => {
+    expect(formatMonthForDisplay('2026-07-01', { locale: 'en-US' })).toContain('2026');
+    expect(formatMonthForDisplay('2026-07-01', { locale: 'en-US', dateStyle: 'long' })).toMatch(
+      /July/i,
+    );
+  });
+
+  it('formats date-time for display', () => {
+    expect(formatDateTimeForDisplay('2026-07-28T10:01', { locale: 'en-US' })).toContain('2026');
+    expect(formatDateTimeForDisplay('invalid', { locale: 'en-US' })).toBe('');
+  });
+});

package/src/__tests__/eachDateIdInRange.test.ts

@@ -0,0 +1,11 @@
+import { eachDateIdInRange } from '../dates/ranges/eachDateIdInRange';
+
+describe('eachDateIdInRange', () => {
+  it('lists each day in range', () => {
+    expect(eachDateIdInRange('2026-07-27', '2026-07-29')).toEqual([
+      '2026-07-27',
+      '2026-07-28',
+      '2026-07-29',
+    ]);
+  });
+});

package/src/__tests__/formatCalendarMonthYear.test.ts

@@ -0,0 +1,9 @@
+import { formatCalendarMonthYear } from '../dates/calendar/formatCalendarMonthYear';
+import { formatMonthCalendarMonth } from '../dates/calendar/formatMonthCalendarMonth';
+
+describe('formatCalendarMonthYear', () => {
+  it('formats calendar month/year with locale', () => {
+    expect(formatCalendarMonthYear('2026-07-01', { locale: 'en-US' })).toContain('2026');
+    expect(formatMonthCalendarMonth(7, { locale: 'en-US' })).toMatch(/Jul/i);
+  });
+});

package/src/__tests__/formatDateForDisplay.test.ts

@@ -0,0 +1,11 @@
+import { formatDateForDisplay } from '../dates/display/formatDateForDisplay';
+
+describe('formatDateForDisplay', () => {
+  it('formats date for en-US locale', () => {
+    const formatted = formatDateForDisplay('2026-07-28', {
+      locale: 'en-US',
+      dateStyle: 'long',
+    });
+    expect(formatted).toContain('2026');
+  });
+});

package/src/__tests__/formatDateId.test.ts

@@ -0,0 +1,15 @@
+import { formatDateId } from '../dates/wire/formatDateId';
+import { parseDateId } from '../dates/wire/parseDateId';
+
+describe('formatDateId', () => {
+  it('round-trips DateId', () => {
+    const id = formatDateId({ year: 2026, month: 7, day: 28 });
+    expect(id).toBe('2026-07-28');
+    expect(parseDateId(id)).toEqual({ year: 2026, month: 7, day: 28 });
+  });
+
+  it('clamps invalid day instead of rolling over via Date', () => {
+    expect(formatDateId({ year: 2026, month: 2, day: 31 })).toBe('2026-02-28');
+    expect(formatDateId({ year: 2024, month: 2, day: 31 })).toBe('2024-02-29');
+  });
+});

package/src/__tests__/formatMonthId.test.ts

@@ -0,0 +1,7 @@
+import { formatMonthId } from '../dates/wire/formatMonthId';
+
+describe('formatMonthId', () => {
+  it('formats month id', () => {
+    expect(formatMonthId({ year: 2026, month: 7 })).toBe('2026-07-01');
+  });
+});

package/src/__tests__/formatNumber.test.ts

@@ -0,0 +1,35 @@
+import { formatNumber } from '../formatNumber';
+
+describe('formatNumber', () => {
+  it('should format with default decimal places', () => {
+    expect(formatNumber(99.95789)).toEqual('99.96');
+  });
+
+  it('should format a string with custom decimal places', () => {
+    expect(formatNumber('-2000', { decimalPlaces: 3 })).toEqual('-2,000.000');
+  });
+
+  it('should format using locale', () => {
+    expect(formatNumber(1234.5, { locale: 'de-DE' })).toEqual('1.234,50');
+  });
+
+  it('should omit the sign for signed zero (-0)', () => {
+    expect(formatNumber(-0)).toEqual('0.00');
+  });
+
+  it('should use defaults when options is nullish or fields are null', () => {
+    expect(formatNumber(1234.5, null)).toEqual('1,234.50');
+    expect(formatNumber(1234.5, undefined)).toEqual('1,234.50');
+    expect(formatNumber(1234.5, { locale: null, decimalPlaces: null })).toEqual('1,234.50');
+  });
+
+  [null, undefined, Number.NaN, 'asdf', '', ' '].forEach((value) => {
+    it(`should return empty string for ${JSON.stringify(value)}`, () => {
+      expect(formatNumber(value)).toEqual('');
+    });
+  });
+
+  it('should return empty string for already-formatted numbers', () => {
+    expect(formatNumber('1,234.56')).toEqual('');
+  });
+});

package/src/__tests__/getDateFieldSegments.test.ts

@@ -0,0 +1,35 @@
+import { getDateFieldSegments } from '../dates/segments/getDateFieldSegments';
+
+describe('getDateFieldSegments', () => {
+  it('returns date field segments', () => {
+    const segments = getDateFieldSegments('2026-07-28', { mode: 'date', locale: 'en-US' });
+    expect(segments.map((s) => s.type)).toEqual(['month', 'literal', 'day', 'literal', 'year']);
+    expect(segments.filter((s) => s.type === 'literal').map((s) => s.text)).toEqual(['/', '/']);
+  });
+
+  it('orders date field segments by locale', () => {
+    const deSegments = getDateFieldSegments('2026-07-28', { mode: 'date', locale: 'de-DE' });
+    expect(deSegments.map((s) => s.type)).toEqual(['day', 'literal', 'month', 'literal', 'year']);
+    expect(deSegments.filter((s) => s.type === 'literal').map((s) => s.text)).toEqual(['.', '.']);
+
+    const jpSegments = getDateFieldSegments('2026-07-28', { mode: 'date', locale: 'ja-JP' });
+    expect(jpSegments.map((s) => s.type)).toEqual(['year', 'literal', 'month', 'literal', 'day']);
+  });
+
+  it('orders month field segments by locale', () => {
+    const deSegments = getDateFieldSegments('2026-07-01', { mode: 'month', locale: 'de-DE' });
+    expect(deSegments.map((s) => s.type)).toEqual(['month', 'literal', 'year']);
+    const expectedLiteral = new Intl.DateTimeFormat('de-DE', { year: 'numeric', month: '2-digit' })
+      .formatToParts(new Date(2026, 6, 1))
+      .find((part) => part.type === 'literal')?.value;
+    expect(deSegments.find((s) => s.type === 'literal')?.text).toBe(expectedLiteral);
+  });
+
+  it('returns placeholder segments when value is empty', () => {
+    const segments = getDateFieldSegments(undefined, { mode: 'date', locale: 'en-US' });
+    expect(segments.find((s) => s.type === 'month')?.text).toBe('MM');
+    expect(segments.find((s) => s.type === 'month')?.value).toBeUndefined();
+    expect(segments.find((s) => s.type === 'day')?.text).toBe('DD');
+    expect(segments.find((s) => s.type === 'year')?.text).toBe('YYYY');
+  });
+});