@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
The tables below are a representative import guide, not an exhaustive list —
src/index.ts(re-exportingdates/index.ts) is the authoritative export surface.
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
labels/ # date-component accessibility label helpers
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
''ornullas 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. The full license text ships in the package as LICENSE.