Foundation · @jengacore/format

format

Money from decimal strings with minor units per ISO 4217, true minus sign, short IDs, dates (05 Oct 2026) and 24 h times.

Install

terminal

npx shadcn@latest add @jengacore/format

Without the namespace configured: npx shadcn@latest add https://ui.jengacore.com/r/<new-york-v4|base-nova>/format.json

Source

lib/jengacore/format.ts

/**
 * Money and reference formatting. Amounts arrive as DECIMAL STRINGS from the API
 * (never floats) and are formatted without converting to Number, so 0.1 + 0.2 never bites.
 */

/** Minor units per currency. SLSH has no ISO 4217 code: agree the private-use code per scheme. */
export const MINOR_UNITS: Record<string, number> = {
  USD: 2, EUR: 2, GBP: 2, KES: 2, UGX: 0, RWF: 0, TZS: 2, GMD: 2, SLSH: 0, XOF: 0,
}

const MINUS = "−"

/** "1250.5", "USD" -> "1,250.50" ; "-32410" -> "−32,410.00" ; signed=true adds "+" to credits. */
export function formatAmount(value: string, currency: string, opts: { signed?: boolean } = {}): string {
  const digits = MINOR_UNITS[currency] ?? 2
  const negative = value.trim().startsWith("-")
  const [intRaw = "0", fracRaw = ""] = value.replace(/^[-+]/, "").split(".")
  const int = intRaw.replace(/^0+(?=\d)/, "").replace(/\B(?=(\d{3})+(?!\d))/g, ",")
  const frac = digits > 0 ? "." + fracRaw.padEnd(digits, "0").slice(0, digits) : ""
  const sign = negative ? MINUS : opts.signed && value !== "0" ? "+" : ""
  return `${sign}${int}${frac}`
}

/** "tx_01J9ZK4Q7MXH3V" -> "tx_01J9…H3V" for tight cells; show the full value in a tooltip. */
export function shortId(id: string, head = 7, tail = 3): string {
  return id.length <= head + tail + 1 ? id : `${id.slice(0, head)}…${id.slice(-tail)}`
}

const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]

/** 05 Oct 2026. Month names are spelled here: ICU writes "Sept" for en-GB, the standard is "Sep". */
export function formatDate(d: Date | string, opts: { year?: boolean } = {}): string {
  const date = typeof d === "string" ? new Date(d) : d
  const day = `${String(date.getDate()).padStart(2, "0")} ${MONTHS[date.getMonth()]}`
  return opts.year === false ? day : `${day} ${date.getFullYear()}`
}

/** 09:41:07 (24 h) */
export function formatTime(d: Date | string): string {
  const date = typeof d === "string" ? new Date(d) : d
  return date.toLocaleTimeString("en-GB", { hour12: false })
}