// --------------------------------------------------------------------------- // ui / fmt.ts — EXIT wave 2 (W2-6, contract Y2). // // THE formatters. Y1's rule 3 is the reason this file exists: *"the server // NEVER sends a pre-formatted string ⇒ one formatter change fixes every page."* // A number arrives as a number with an `fmt` code beside it, and this module is // the only place that decides how it reads. // // ⚠⚠ TWO `fmt` VOCABULARIES EXIST AND THEY ARE NOT INTERCHANGEABLE (Y1 rule 1). // This file owns the **Y1 fmt enum** — `money · num · pct · int · date`, CLOSED — // used by `kpis`, `table` and `validation` blocks. A `chart` block's `fields[]` // instead carries the **viz `FieldType`** vocabulary (`currency · int · pct · // date · text · status`), because those objects are fed straight into // `chartData(spec, rows, fieldByKey)`. `fmt:"money"` inside a chart field // typechecks nowhere near here and renders as raw text — it is the bug that // looks fine. Keep the two apart: `Fmt` below is never assigned to a viz field. // // The rules are the SHIPPED ones, mirrored from `platform/ui/primitives.py` // so a number reads identically in the Streamlit page and in the shell during // the strangle. Where this file deliberately differs, it says so. // --------------------------------------------------------------------------- /** Y1's closed format enum. A column with NO `fmt` renders verbatim (rule 2) — * that is how a text column is expressed without opening the enum. */ export type Fmt = "money" | "num" | "pct" | "int" | "date"; /** What every formatter returns for a value it has nothing to say about. * An em dash, never "0" and never "" — a missing number and a zero are * different facts and a KPI card must not conflate them. */ export const BLANK = "—"; /** Above this, a percentage stops being readable and becomes a multiple. * `+14,975%` reads as noise; `+151×` reads as a fact (Y1 rule 3). */ export const PCT_AS_MULTIPLE_AT = 999; function toNumber(v: unknown): number | null { if (v == null || v === "") return null; const n = typeof v === "number" ? v : Number(v); return Number.isFinite(n) ? n : null; } /** * The house number rule, from `ui/primitives.py:num` verbatim: comma-grouped, * NO decimals — except a non-whole single-digit value (|v| < 10), which keeps * one. So big numbers read clean (1,204,882), small ratios keep their meaning * (7.7), and whole numbers never carry a trailing `.0` ($0, not $0.0). */ export function num(v: unknown, dp?: number): string { const n = toNumber(v); if (n == null) return BLANK; const places = dp ?? (Math.abs(n) < 10 && !Number.isInteger(n) ? 1 : 0); return n.toLocaleString(undefined, { minimumFractionDigits: places, maximumFractionDigits: places, }); } /** Money. The sign goes OUTSIDE the currency mark (`-$1,204`, not `$-1,204`) — * `primitives.py:money`'s shape, and the one that reads as a loss at a glance. */ export function money(v: unknown, dp?: number): string { const n = toNumber(v); if (n == null) return BLANK; return n < 0 ? `-$${num(Math.abs(n), dp)}` : `$${num(n, dp)}`; } /** Whole counts. Always 0 dp — an order count with a decimal is a bug wearing * a format. */ export function int(v: unknown): string { const n = toNumber(v); if (n == null) return BLANK; return Math.round(n).toLocaleString(); } export interface PctOptions { /** Render a leading `+` on non-negative values (deltas do; shares do not). */ signed?: boolean; dp?: number; } /** * ⭐⭐ WAVE 50 · W50-T05 — **HOW A NUMERIC FIELD READS: its value, its share of the view's * grand total, or both.** * * ⛔⛔ A SHARE IS NOT A PERCENTAGE, AND CONFLATING THE TWO IS THIS TICKET'S NAMED TRAP. * `PctOptions` above belongs to `pct()`, which renders a value that ALREADY IS a percentage — * `12.4` means 12.4%, and the doc there says so in bold. A SHARE is a RATIO: this cell's number * over the whole column's number, and the two operands are both plain quantities. Overloading * `PctOptions` to carry a share would put a denominator into a function whose entire contract is * that there isn't one, and the first `pct` column asked to show a share would then divide a * percentage by a percentage and print a number that is true of nothing. * * ⛔ SO THIS MODULE OWNS THE VOCABULARY AND THE COMPOSITION, AND NOT THE ARITHMETIC. * `customer-grid/aggregations.ts::formatShare` is the ONE place a part is divided by a whole * (one decimal, unclamped, absent on a zero or non-finite denominator, and its body is pinned by * `verify_grid_ux.py`). A second implementation here would be a second answer to one question, * which is the defect `numericOrUndefined` and `foldNumeric` were each extracted to close. * `withShare` therefore takes the share ALREADY FORMATTED and only decides what the reader sees. */ export type ShowAs = "value" | "share" | "both"; /** The three offered modes, in the picker's order. Exported so a control cannot write a fourth * spelling of one of them; `showAsLabel` below is the only place they wear words. */ export const SHOW_AS_MODES: readonly ShowAs[] = ["value", "share", "both"]; /** Sentence case, per DESIGN.md §2 — these are menu rows, not headers. */ export const SHOW_AS_LABELS: Record = { value: "Value", share: "% of total", both: "Both", }; /** * ⭐ W50-T05 — the ONE composition of a value and its share, so the canvas cell, the record * panel, the list, the kanban card and every export answer identically (D-121's whole subject: * two formatters over one concept is how the panel drifted from the grid before). * * ⛔ **`value` IS THE DEFAULT AND AN ABSENT SHARE FALLS BACK TO THE VALUE, ALWAYS.** A column * whose aggregate does not COMPOSE (average, median, min, max, percentile, count_distinct — see * `SHARE_AGGS`) has no honest share, and a caller with no total to divide by passes `undefined`. * Either way the reader gets the number rather than a blank cell: "% of total" is a way of * READING a value, never a licence to withhold it. * * ⚠ `both` joins with a NEWLINE, which is the "under the value" of the PRD's design contract. * The grid's `drawCell` splits on it to paint the second line in `theme.textLight`; every other * consumer passes no share at all and therefore never sees one, so no CSV cell can grow a raw * line break out of this. */ export function withShare( value: string, share: string | undefined, showAs: ShowAs | undefined ): string { if (share === undefined || showAs === undefined || showAs === "value") return value; if (showAs === "share") return share; return `${value}\n${share}`; } /** * Percentages, and the ONE place the big-ratio rule lives (Y1 rule 3). * * A percentage over ~1000% is arithmetically fine and rhetorically useless: it * means the prior-year base was tiny, and `+14,975%` invites the reader to * treat a rounding artefact as a result. Past `PCT_AS_MULTIPLE_AT` the value is * restated as the MULTIPLE it actually is — `1 + v/100`, zero decimals, exactly * `app.py:2851`'s formula. The caller supplies the comparison word (Y1 sends * `delta_label: "vs LY"`), so this returns `+151×` and never invents a suffix. * * ⚠ The value is a PERCENTAGE ALREADY — 12.4 means 12.4%. It is never * multiplied by 100 here. Semantic percentages elsewhere in this codebase are * 0–1 while transform `*_pct` values are 0–100 ([[analyst-chart-library]]), and * a blanket rescale would be silently wrong for half of them. */ export function pct(v: unknown, opts: PctOptions = {}): string { const n = toNumber(v); if (n == null) return BLANK; if (n >= PCT_AS_MULTIPLE_AT) { const mult = (1 + n / 100).toLocaleString(undefined, { minimumFractionDigits: 0, maximumFractionDigits: 0, }); return `+${mult}×`; } const sign = opts.signed && n >= 0 ? "+" : ""; return `${sign}${num(n, opts.dp)}%`; } const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]; /** * Dates, from what the server actually sends: an ISO date, an ISO datetime, or * a bare `YYYY-MM` month key. * * ⚠ Every branch is computed in UTC ON PURPOSE. `new Date("2026-05-01")` parses * as UTC midnight, so `toLocaleDateString()` in any negative-offset timezone * renders it as 30 April — a report row dated the last day of the previous * month. The grid's cell formatter (`customer-grid/display.ts:dateTimeText`) * still has that behaviour and documents it as byte-compatibility with a * pre-wave-5 path; a formatter written today should not inherit it, so this one * does not. That is a deliberate difference, not a drift. * * An unparseable value renders VERBATIM rather than "Invalid Date" — the raw * string is at least true. */ export function date(v: unknown): string { if (v == null || v === "") return BLANK; const s = String(v); const month = /^(\d{4})-(\d{2})$/.exec(s); if (month) { const m = Number(month[2]); if (m >= 1 && m <= 12) return `${MONTHS[m - 1]} ${month[1].slice(2)}`; } const iso = s.includes(" ") ? s.replace(" ", "T") : s; const withZone = /T\d{2}:\d{2}/.test(iso) && !/(?:[zZ]|[+-]\d{2}:?\d{2})$/.test(iso) ? `${iso}Z` : iso; const d = new Date(withZone); if (Number.isNaN(d.getTime())) return s; return d.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric", timeZone: "UTC", }); } /** Y2's named surface. The contract fixes these five names. */ export const fmt = { money, num, pct, int, date } as const; /** * Render one value under an OPTIONAL format code — the dispatcher every block * renderer uses. * * ⛔ `code` undefined means RENDER VERBATIM (Y1 rule 2), which is how a text * column exists without opening the closed enum. It does NOT mean "guess": a * formatter picked from the value's runtime type would format an account number * as `4,412` and a postcode as `01,234`. * * An UNKNOWN code also renders verbatim rather than throwing — same reasoning * as Y1 rule 7's unknown-block rule: the server may learn a format before this * client does, and one new code must not blank a whole page. */ export function formatValue(v: unknown, code?: string, opts?: PctOptions): string { if (code === undefined || code === null || code === "") { return v == null || v === "" ? BLANK : String(v); } switch (code) { case "money": return money(v); case "num": return num(v); case "pct": return pct(v, opts); case "int": return int(v); case "date": return date(v); default: return v == null || v === "" ? BLANK : String(v); } }