<!-- source-hash: dbfaad05e48db5fac78d6f613b9afd1e -->
Utility functions for formatting data across dates, numbers, currencies, bytes, durations, and display strings. Serves as the single source of truth for all presentation-layer formatting in the Flamingo/OpenFrame stack.

## Key Components

| Function | Description |
|---|---|
| `formatDate` | Locale-aware date formatting with `Intl.DateTimeFormatOptions` support |
| `formatDateUTC` | UTC-anchored date formatter with fallback; handles ISO strings, epoch ms, and numeric strings |
| `formatLegalDate` | Fixed `MM/DD/YYYY` format for legal documents |
| `formatNumber` | Thousands-separator number formatting |
| `formatPrice` | Currency-symbol formatting via `Intl.NumberFormat` |
| `formatCurrency` | USD whole-dollar KPI formatter with `'N/A'` null guard |
| `formatWholeDollars` | Configurable whole-dollar formatter (no cents) |
| `formatPercent` | Fixed 2-decimal percent string with `'N/A'` null guard |
| `formatBytes` | Human-readable byte sizes up to YB |
| `formatBytesShort` | Compact byte formatter (`'B'` unit) for tight UI spaces |
| `formatLargeNumber` | Abbreviated integers — `1K`, `2M`, `3B` (floor, no decimals) |
| `formatAbbreviatedNumber` | Abbreviated numbers with one decimal when needed — `1.2K`, `2.5M` |
| `getFirstLastInitials` | First + last word initials (e.g. `"John Michael Doe"` → `"JD"`) |
| `nameInitials` | First + second word initials, max 2 chars, with configurable fallback |
| `formatDurationMMSS` | Duration as `MM:SS` or `HH:MM:SS` |
| `formatDurationCompact` | Duration as `"Xh Xm"` or `"X min"` |
| `formatDurationFromRange` | Duration between two timestamps as compact string |
| `formatTimeWithTimezone` | Time string with optional timezone label |
| `formatCompactMetric` | Metric value with compact notation for KPI cards (partial) |
| `MetricFormat` | Type: `'number' \| 'currency' \| 'percentage' \| 'months'` |
| `TrendPolarity` | Type: `'positive' \| 'negative' \| 'neutral'` |

## Usage Example

```typescript
import {
  formatDate,
  formatDateUTC,
  formatBytes,
  formatBytesShort,
  formatLargeNumber,
  formatAbbreviatedNumber,
  formatPrice,
  formatCurrency,
  formatPercent,
  formatDurationMMSS,
  formatDurationCompact,
  formatDurationFromRange,
  formatTimeWithTimezone,
  nameInitials,
  getFirstLastInitials,
} from './format'

// Dates
formatDate('2024-08-15')
// → "August 15, 2024"

formatDateUTC('2024-08-15')
// → "Aug 15, 2024" (UTC-anchored, no timezone drift)

formatDateUTC(null, { fallback: 'Unknown' })
// → "Unknown"

// Bytes
formatBytes(1536)           // → "1.5 KB"
formatBytesShort(1536)      // → "1.5 KB"  (tight UI variant)

// Numbers
formatLargeNumber(1_500_000)       // → "1M"   (floor, no decimals)
formatAbbreviatedNumber(1_200)     // → "1.2K" (one decimal when needed)

// Currency
formatPrice(49.99)                 // → "$49.99"
formatCurrency(1234567)            // → "$1,234,567"
formatPercent(12.5)                // → "12.50%"

// Duration
formatDurationMMSS(3725)           // → "1:02:05"
formatDurationCompact(3725)        // → "1h 2m"
formatDurationFromRange('2024-01-01T10:00:00Z', '2024-01-01T11:30:00Z')
// → "1h 30m"

formatTimeWithTimezone(new Date(), 'EST')
// → "10:30 AM EST"

// Initials
nameInitials('John Michael Doe')   // → "JM"
getFirstLastInitials('John Michael Doe') // → "JD"
nameInitials(null)                 // → "E"  (default fallback)
```