Francy51/Neon-Desk
2
0
Fork 0
Code Issues 22 Pull Requests Actions Packages Projects Releases Wiki Activity

Improve financial statement value formatting

Browse Source
This commit is contained in:
francy51
2026-03-09 18:58:15 -04:00
parent fae8c54121
commit fa2de3e259
3 changed files with 306 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
app/financials/page.tsx
View File

@@ -37,6 +37,7 @@ import { useLinkPrefetch } from '@/hooks/use-link-prefetch';
import { queueFilingSync } from '@/lib/api';
import {
formatCurrencyByScale,
formatFinancialStatementValue,
formatPercent,
type NumberScaleUnit
} from '@/lib/format';
@@ -121,32 +122,62 @@ function rowValue(row: DisplayRow, periodId: string) {
return row.values[periodId] ?? null;
}
function formatMetricValue(value: number | null, unit: FinancialUnit, scale: NumberScaleUnit) {
if (value === null) {
return 'n/a';
function isStatementSurfaceKind(surfaceKind: FinancialSurfaceKind) {
return surfaceKind === 'income_statement' || surfaceKind === 'balance_sheet' || surfaceKind === 'cash_flow_statement';
}
switch (unit) {
function formatMetricValue(input: {
value: number | null;
unit: FinancialUnit;
scale: NumberScaleUnit;
rowKey?: string | null;
surfaceKind: FinancialSurfaceKind;
isPercentChange?: boolean;
isCommonSize?: boolean;
}) {
if (input.value === null) {
return isStatementSurfaceKind(input.surfaceKind) ? '—' : 'n/a';
}
if (isStatementSurfaceKind(input.surfaceKind)) {
return formatFinancialStatementValue({
value: input.value,
unit: input.unit,
scale: input.scale,
rowKey: input.rowKey,
surfaceKind: input.surfaceKind,
isPercentChange: input.isPercentChange,
isCommonSize: input.isCommonSize
});
}
switch (input.unit) {
case 'currency':
return formatCurrencyByScale(value, scale);
return formatCurrencyByScale(input.value, input.scale);
case 'percent':
return formatPercent(value * 100);
return formatPercent(input.value * 100);
case 'shares':
case 'count':
return new Intl.NumberFormat('en-US', { notation: 'compact', maximumFractionDigits: 2 }).format(value);
return new Intl.NumberFormat('en-US', { notation: 'compact', maximumFractionDigits: 2 }).format(input.value);
case 'ratio':
return `${value.toFixed(2)}x`;
return `${input.value.toFixed(2)}x`;
default:
return String(value);
return String(input.value);
}
}
function chartTickFormatter(value: number, unit: FinancialUnit, scale: NumberScaleUnit) {
function chartTickFormatter(
value: number,
unit: FinancialUnit,
scale: NumberScaleUnit,
surfaceKind: FinancialSurfaceKind,
rowKey?: string | null
) {
if (!Number.isFinite(value)) {
return 'n/a';
return isStatementSurfaceKind(surfaceKind) ? '—' : 'n/a';
}
return formatMetricValue(value, unit, scale);
return formatMetricValue({ value, unit, scale, surfaceKind, rowKey });
}
function buildDisplayValue(input: {
@@ -165,10 +196,17 @@ function buildDisplayValue(input: {
if (input.showPercentChange && input.previousPeriodId) {
const previous = rowValue(input.row, input.previousPeriodId);
if (current === null || previous === null || previous === 0) {
return 'n/a';
return isStatementSurfaceKind(input.surfaceKind) ? '—' : 'n/a';
}
return formatPercent(((current - previous) / previous) * 100);
return formatMetricValue({
value: (current - previous) / previous,
unit: 'percent',
scale: input.scale,
rowKey: input.row.key,
surfaceKind: input.surfaceKind,
isPercentChange: true
});
}
if (input.showCommonSize) {
@@ -177,21 +215,34 @@ function buildDisplayValue(input: {
}
if (input.displayMode === 'faithful') {
return 'n/a';
return isStatementSurfaceKind(input.surfaceKind) ? '—' : 'n/a';
}
const denominator = input.commonSizeRow ? rowValue(input.commonSizeRow, input.periodId) : null;
if (current === null || denominator === null || denominator === 0) {
return 'n/a';
return isStatementSurfaceKind(input.surfaceKind) ? '—' : 'n/a';
}
return formatPercent((current / denominator) * 100);
return formatMetricValue({
value: current / denominator,
unit: 'percent',
scale: input.scale,
rowKey: input.row.key,
surfaceKind: input.surfaceKind,
isCommonSize: true
});
}
const unit = isTaxonomyRow(input.row)
? 'currency'
: input.row.unit;
return formatMetricValue(current, unit, input.scale);
return formatMetricValue({
value: current,
unit,
scale: input.scale,
rowKey: input.row.key,
surfaceKind: input.surfaceKind
});
}
function groupRows(rows: DisplayRow[], categories: CompanyFinancialStatementsResponse['categories']) {
@@ -694,13 +745,25 @@ function FinancialsPageContent() {
<YAxis
stroke={CHART_MUTED}
fontSize={12}
tickFormatter={(value: number) => chartTickFormatter(value, trendSeries[0]?.unit ?? 'currency', valueScale)}
tickFormatter={(value: number) => chartTickFormatter(
value,
trendSeries[0]?.unit ?? 'currency',
valueScale,
surfaceKind,
trendSeries[0]?.key ?? null
)}
/>
<Tooltip
formatter={(value: unknown, _name, entry) => {
const numeric = Number(value);
const unit = trendSeries.find((series) => series.key === entry.dataKey)?.unit ?? 'currency';
return formatMetricValue(Number.isFinite(numeric) ? numeric : null, unit, valueScale);
const series = trendSeries.find((candidate) => candidate.key === entry.dataKey);
return formatMetricValue({
value: Number.isFinite(numeric) ? numeric : null,
unit: series?.unit ?? 'currency',
scale: valueScale,
rowKey: series?.key ?? null,
surfaceKind
});
}}
contentStyle={{
backgroundColor: CHART_TOOLTIP_BG,
@@ -736,6 +799,12 @@ function FinancialsPageContent() {
) : periods.length === 0 || filteredRows.length === 0 ? (
<p className="text-sm text-[color:var(--terminal-muted)]">No rows available for the selected filters yet.</p>
) : (
<div className="space-y-3">
{isStatementSurfaceKind(surfaceKind) ? (
<p className="text-xs uppercase tracking-[0.24em] text-[color:var(--terminal-muted)]">
USD · {FINANCIAL_VALUE_SCALE_OPTIONS.find((option) => option.value === valueScale)?.label ?? valueScale}
</p>
) : null}
<div className="data-table-wrap">
<table className="data-table min-w-[980px]">
<thead>
@@ -801,6 +870,7 @@ function FinancialsPageContent() {
</tbody>
</table>
</div>
</div>
)}
</Panel>
@@ -870,7 +940,13 @@ function FinancialsPageContent() {
<td>{periods.find((period) => period.id === row.periodId)?.periodLabel ?? row.periodId}</td>
<td>{row.axis}</td>
<td>{row.member}</td>
<td>{formatMetricValue(row.value, 'currency', valueScale)}</td>
<td>{formatMetricValue({
value: row.value,
unit: isTaxonomyRow(selectedRow) ? 'currency' : selectedRow.unit,
scale: valueScale,
rowKey: selectedRow.key,
surfaceKind
})}</td>
</tr>
))}
</tbody>
@@ -905,8 +981,20 @@ function FinancialsPageContent() {
{financials.metrics.validation?.checks.map((check) => (
<tr key={check.metricKey}>
<td>{check.metricKey}</td>
<td>{formatMetricValue(check.taxonomyValue, 'currency', valueScale)}</td>
<td>{formatMetricValue(check.llmValue, 'currency', valueScale)}</td>
<td>{formatMetricValue({
value: check.taxonomyValue,
unit: 'currency',
scale: valueScale,
rowKey: check.metricKey,
surfaceKind
})}</td>
<td>{formatMetricValue({
value: check.llmValue,
unit: 'currency',
scale: valueScale,
rowKey: check.metricKey,
surfaceKind
})}</td>
<td>{check.status}</td>
<td>{check.evidencePages.join(', ') || 'n/a'}</td>
</tr>

62
lib/format.test.ts
View File

@@ -1,5 +1,9 @@
import { describe, expect, it } from 'bun:test';
import { formatCurrencyByScale, formatScaledNumber } from './format';
import {
formatCurrencyByScale,
formatFinancialStatementValue,
formatScaledNumber
} from './format';
describe('formatScaledNumber', () => {
it('keeps values below one thousand unscaled', () => {
@@ -45,3 +49,59 @@ describe('formatCurrencyByScale', () => {
expect(formatCurrencyByScale(-2_500_000, 'millions')).toBe('-$2.5M');
});
});
describe('formatFinancialStatementValue', () => {
it('renders null statement values as em dashes', () => {
expect(formatFinancialStatementValue({
value: null,
unit: 'currency',
scale: 'millions',
rowKey: 'revenue',
surfaceKind: 'income_statement'
})).toBe('—');
});
it('formats scaled currency values without a currency symbol', () => {
expect(formatFinancialStatementValue({
value: 15_940_899_000,
unit: 'currency',
scale: 'millions',
rowKey: 'revenue',
surfaceKind: 'income_statement'
})).toBe('15,940.9');
expect(formatFinancialStatementValue({
value: 1_100_000_000,
unit: 'currency',
scale: 'millions',
rowKey: 'long_term_debt_issued',
surfaceKind: 'cash_flow_statement'
})).toBe('1,100');
});
it('keeps extra precision for per-share rows', () => {
expect(formatFinancialStatementValue({
value: 14.64,
unit: 'currency',
scale: 'millions',
rowKey: 'diluted_eps',
surfaceKind: 'income_statement'
})).toBe('14.64');
});
it('formats statement percents and ratios with trimmed precision', () => {
expect(formatFinancialStatementValue({
value: 0.233,
unit: 'percent',
scale: 'millions',
rowKey: 'effective_tax_rate',
surfaceKind: 'income_statement'
})).toBe('23.3%');
expect(formatFinancialStatementValue({
value: 1.5,
unit: 'ratio',
scale: 'millions',
rowKey: 'debt_to_equity',
surfaceKind: 'ratios'
})).toBe('1.5x');
});
});

70
lib/format.ts
View File

@@ -1,3 +1,8 @@
import type {
FinancialSurfaceKind,
FinancialUnit
} from './types';
export function asNumber(value: string | number | null | undefined) {
if (value === null || value === undefined) {
return 0;
@@ -37,6 +42,37 @@ type FormatScaledCurrencyOptions = {
maximumFractionDigits?: number;
};
type FormatFinancialStatementValueInput = {
value: string | number | null | undefined;
unit: FinancialUnit;
scale: NumberScaleUnit;
rowKey?: string | null;
surfaceKind?: FinancialSurfaceKind | null;
isPercentChange?: boolean;
isCommonSize?: boolean;
};
function isPerShareRowKey(rowKey: string | null | undefined) {
if (!rowKey) {
return false;
}
return rowKey.includes('eps') || rowKey.includes('per_share');
}
function formatPlainNumber(
value: number,
options: {
minimumFractionDigits?: number;
maximumFractionDigits?: number;
} = {}
) {
return new Intl.NumberFormat('en-US', {
minimumFractionDigits: options.minimumFractionDigits ?? 0,
maximumFractionDigits: options.maximumFractionDigits ?? 1
}).format(value);
}
export function formatScaledNumber(
value: string | number | null | undefined,
options: FormatScaledNumberOptions = {}
@@ -99,6 +135,40 @@ export function formatCurrencyByScale(
return `${formatted}${suffix}`;
}
export function formatFinancialStatementValue(input: FormatFinancialStatementValueInput) {
if (input.value === null || input.value === undefined) {
return '—';
}
const numeric = typeof input.value === 'number' ? input.value : Number(input.value);
if (!Number.isFinite(numeric)) {
return '—';
}
if (input.isPercentChange || input.isCommonSize || input.unit === 'percent') {
return `${formatPlainNumber(numeric * 100, { minimumFractionDigits: 0, maximumFractionDigits: 1 })}%`;
}
if (input.unit === 'ratio') {
return `${formatPlainNumber(numeric, { minimumFractionDigits: 0, maximumFractionDigits: 2 })}x`;
}
if (input.unit === 'currency' && isPerShareRowKey(input.rowKey)) {
return formatPlainNumber(numeric, { minimumFractionDigits: 0, maximumFractionDigits: 2 });
}
if (input.unit === 'currency') {
const scaled = numeric / NUMBER_SCALE_UNITS[input.scale].divisor;
return formatPlainNumber(scaled, { minimumFractionDigits: 0, maximumFractionDigits: 1 });
}
if (input.unit === 'shares' || input.unit === 'count') {
return formatPlainNumber(numeric, { minimumFractionDigits: 0, maximumFractionDigits: 0 });
}
return formatPlainNumber(numeric, { minimumFractionDigits: 0, maximumFractionDigits: 2 });
}
export function formatCurrency(value: string | number | null | undefined) {
return new Intl.NumberFormat('en-US', {
style: 'currency',