@cdx-ui/formatters

Pure formatters for Forge UI and FI apps — turn wire values into human-readable UI strings (and the reverse for date wire ids). No React dependency.

Aligned in style with @candescent/ui-formatters (display helpers at package root; date helpers under dates/). Prefer named imports from @cdx-ui/formatters only — do not import date-fns or Intl wrappers from this package’s internals.

Wire vs display (dates)

| Representation | Example | Use for | | -------------------------------------------- | ---------------------------- | ----------------------------- | | Wire DateId / MonthId / DateTimeId | '2026-07-28' | Form state, APIs, pickers | | Display string | '7/28/26' / '28/07/2026' | Labels, headers — never store |

Exports

Display (shared with banking UI formatters)

| Import | Purpose | | -------------- | ------------------------------------------------------ | | formatNumber | Locale decimal formatting (cached Intl.NumberFormat) |

Date wire

| Import | Purpose | | ------------------------------------------------------------ | ------------------------ | | parseDateId / formatDateId / isValidDateId | YYYY-MM-DD round-trip | | parseMonthId / formatMonthId / isValidMonthId | YYYY-MM-01 month ids | | parseDateTimeId / formatDateTimeId / isValidDateTimeId | Local YYYY-MM-DDTHH:mm | | todayDateId / todayMonthId / nowDateTimeId | Device-local “now” | | toMonthId / clampDateParts / clampMonthParts | Conversions / clamping |

Date display

| Import | Purpose | | --------------------------- | ------------------------------------ | | formatDateForDisplay | Locale dateStyle short/medium/long | | formatMonthForDisplay | Month + year label | | formatDateTimeForDisplay | Date + time label | | formatDateRangeForDisplay | Inclusive range label |

Ranges & segments

| Import | Purpose | | ------------------------------------------------------------------- | ------------------------ | | normalizeDateRange / compareDateIds / eachDateIdInRange | Range math | | dateRangeFromLastNDays / dateRangeAroundDay | Presets | | getDateFieldSegments / getDateTimeFieldSegments | Segmented field metadata | | parseDateSegment / formatDateSegment / applyDateSegmentChange | Segment edits |

Calendar / list copy

| Import | Purpose | | ---------------------------------------------------------- | --------------------- | | formatCalendarMonthYear / getCalendarWeekdayLabels | Calendar chrome | | formatMonthCalendarMonth / formatMonthCalendarYear | Month grid | | formatDateTimeListDateRow / formatDateTimeListHour / … | DateTime list columns |

Usage

import {
  formatDateId,
  formatDateForDisplay,
  formatNumber,
  normalizeDateRange,
  type DateId,
} from '@cdx-ui/formatters';

formatNumber(3247.19); // '3,247.19'

const id: DateId = formatDateId({ year: 2026, month: 7, day: 28 }); // '2026-07-28'
formatDateForDisplay(id, { locale: 'en-US' }); // e.g. '7/28/26'

normalizeDateRange({ startId: '2026-07-28', endId: '2026-07-01' });
// → { startId: '2026-07-01', endId: '2026-07-28' }

pnpm --filter @cdx-ui/formatters test

File layout

src/
  formatNumber.ts          # shared display helper (merge target with ui-formatters)
  types.ts / utils.ts      # package-private (not barrel-exported)
  __tests__/               # one test file per public helper
  dates/
    types.ts
    index.ts               # date barrel (re-exported from package root)
    wire/                  # DateId / MonthId parse, format, validate, today
    display/               # locale-aware format*ForDisplay
    ranges/                # compare, normalize, presets
    segments/              # segmented field helpers
    calendar/              # calendar + list row copy
    datetime/              # DateTimeId + list hour/minute/period
    internal/              # private adapters (not public API)

Design notes

• date-fns is used internally for wire parse/math; Intl for user-facing display and calendar labels.
• Invalid / nullish inputs return '' or null as documented per helper — never throw for bad display input.
• Package internals under dates/internal/ are not part of the public API.

License

MIT © 2026 Digital First Holdings LLC. See LICENSE for details.