Download web/src/ui/fmt.ts from fsanyoto/loopable: direct link, hf CLI and curl.
- Browser
- Download file 10.7 kB
-
https://huggingface.co/spaces/fsanyoto/loopable/resolve/9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/web/src/ui/fmt.ts
- Command line
-
hf download hf://spaces/fsanyoto/loopable@9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/web/src/ui/fmt.ts
-
curl -L -o fmt.ts https://huggingface.co/spaces/fsanyoto/loopable/resolve/9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/web/src/ui/fmt.ts
10.7 kB
| // --------------------------------------------------------------------------- | |
| // 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<ShowAs, string> = { | |
| 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); | |
| } | |
| } | |