Improve financial statement value formatting

lib/format.ts

@@ -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',