Number and List Formatting

/**
 * Component for locale-aware number formatting
 * Supports all Intl.NumberFormat options plus custom format configurations
 */
const FormattedNumber: React.FC<
  Omit<NumberFormatOptions, 'localeMatcher'> &
  CustomFormatConfig<'number'> & {
    /** Numeric value to format */
    value: Parameters<IntlShape['formatNumber']>[0];
    /** Render prop receiving formatted number string */
    children?(formattedNumber: string): React.ReactElement | null;
  }
>;

import { FormattedNumber } from "react-intl";

// Basic number formatting
<FormattedNumber value={1234.56} />
// en-US: "1,234.56"
// de-DE: "1.234,56"
// fr-FR: "1 234,56"

// Currency formatting
<FormattedNumber 
  value={29.99} 
  style="currency" 
  currency="USD" 
/>
// en-US: "$29.99"
// en-GB: "US$29.99"

<FormattedNumber 
  value={29.99} 
  style="currency" 
  currency="EUR" 
/>
// de-DE: "29,99 €"
// fr-FR: "29,99 €"

// Percentage formatting
<FormattedNumber 
  value={0.75} 
  style="percent" 
/>
// Output: "75%"

// Custom precision
<FormattedNumber 
  value={3.14159} 
  minimumFractionDigits={2}
  maximumFractionDigits={4}
/>
// Output: "3.1416"

// Significant digits
<FormattedNumber 
  value={1234567} 
  notation="compact"
  compactDisplay="short"
/>
// en-US: "1.2M"
// de-DE: "1,2 Mio."

// Custom format (requires format definition in provider)
<FormattedNumber value={1000} format="currency" />

// Render prop pattern
<FormattedNumber value={price}>
  {(formattedPrice) => (
    <span className="price-display">
      Price: {formattedPrice}
    </span>
  )}
</FormattedNumber>

/**
 * Component for locale-aware list formatting
 * Formats arrays of React nodes as grammatically correct lists
 */
const FormattedList: React.FC<
  Intl.ListFormatOptions & {
    /** Array of items to format as a list */
    value: readonly React.ReactNode[];
  }
>;

import { FormattedList } from "react-intl";

// Basic list formatting
<FormattedList value={['Apple', 'Banana', 'Orange']} />
// en-US: "Apple, Banana, and Orange"
// es-ES: "Apple, Banana y Orange"

// Conjunction types
<FormattedList 
  value={['Red', 'Green', 'Blue']} 
  type="conjunction" 
/>
// Output: "Red, Green, and Blue"

<FormattedList 
  value={['Cat', 'Dog']} 
  type="disjunction" 
/>
// Output: "Cat or Dog"

<FormattedList 
  value={['First', 'Second', 'Third']} 
  type="unit" 
/>
// Output: "First, Second, Third" (no conjunction)

// List styles
<FormattedList 
  value={['Monday', 'Tuesday', 'Wednesday']} 
  style="long" 
/>
// Output: "Monday, Tuesday, and Wednesday"

<FormattedList 
  value={['A', 'B', 'C']} 
  style="short" 
/>
// Output: "A, B, & C"

<FormattedList 
  value={['X', 'Y', 'Z']} 
  style="narrow" 
/>
// Output: "X, Y, Z"

// Mixed content (React nodes)
<FormattedList value={[
  <strong>Bold text</strong>,
  <em>Italic text</em>,
  'Plain text'
]} />

/**
 * Component for locale-aware display name formatting
 * Formats language, region, currency, and script names
 */
const FormattedDisplayName: React.FC<
  Intl.DisplayNamesOptions & {
    /** Value to get display name for (language code, country code, etc.) */
    value: string;
  }
>;

import { FormattedDisplayName } from "react-intl";

// Language names
<FormattedDisplayName 
  value="en" 
  type="language" 
/>
// en-US: "English"
// es-ES: "inglés"
// fr-FR: "anglais"

<FormattedDisplayName 
  value="zh-Hans" 
  type="language" 
/>
// en-US: "Chinese (Simplified)"

// Region/country names
<FormattedDisplayName 
  value="US" 
  type="region" 
/>
// en-US: "United States"
// de-DE: "Vereinigte Staaten"

<FormattedDisplayName 
  value="JP" 
  type="region" 
/>
// en-US: "Japan"
// ja-JP: "日本"

// Currency names
<FormattedDisplayName 
  value="USD" 
  type="currency" 
/>
// en-US: "US Dollar"
// es-ES: "dólar estadounidense"

// Script names
<FormattedDisplayName 
  value="Latn" 
  type="script" 
/>
// en-US: "Latin"

// Style variations
<FormattedDisplayName 
  value="fr" 
  type="language"
  style="long"
/>
// Output: "French"

<FormattedDisplayName 
  value="fr" 
  type="language"
  style="short"
/>
// Output: "French" (same as long for languages)

<FormattedDisplayName 
  value="fr" 
  type="language"
  style="narrow"
/>
// Output: "fr" (code form)

/**
 * Component for accessing formatted number parts
 * Useful for custom number rendering and styling
 */
const FormattedNumberParts: React.FC<
  Omit<NumberFormatOptions, 'localeMatcher'> &
  CustomFormatConfig<'number'> & {
    /** Numeric value to format into parts */
    value: Parameters<IntlShape['formatNumber']>[0];
    /** Render prop receiving array of number parts */
    children(val: Intl.NumberFormatPart[]): React.ReactElement | null;
  }
>;

/**
 * Component for accessing formatted list parts
 * Useful for custom list rendering and styling
 */
const FormattedListParts: React.FC<
  Intl.ListFormatOptions & {
    /** Array of items to format into parts */
    value: Parameters<IntlShape['formatList']>[0];
    /** Render prop receiving array of list parts */
    children(val: ReturnType<Intl.ListFormat['formatToParts']>): React.ReactElement | null;
  }
>;

import { FormattedNumberParts, FormattedListParts } from "react-intl";

// Custom currency rendering
<FormattedNumberParts 
  value={1234.56} 
  style="currency" 
  currency="USD"
>
  {(parts) => (
    <div className="currency-display">
      {parts.map((part, index) => (
        <span 
          key={index} 
          className={`number-${part.type}`}
        >
          {part.value}
        </span>
      ))}
    </div>
  )}
</FormattedNumberParts>
// Parts: [
//   { type: 'currency', value: '$' },
//   { type: 'integer', value: '1,234' },
//   { type: 'decimal', value: '.' },
//   { type: 'fraction', value: '56' }
// ]

// Custom list with styled separators
<FormattedListParts value={['Apple', 'Banana', 'Cherry']}>
  {(parts) => (
    <div className="custom-list">
      {parts.map((part, index) => (
        <span 
          key={index}
          className={part.type === 'literal' ? 'separator' : 'item'}
        >
          {part.value}
        </span>
      ))}
    </div>
  )}
</FormattedListParts>
// Parts: [
//   { type: 'element', value: 'Apple' },
//   { type: 'literal', value: ', ' },
//   { type: 'element', value: 'Banana' },
//   { type: 'literal', value: ', and ' },
//   { type: 'element', value: 'Cherry' }
// ]

interface NumberFormatOptions extends Intl.NumberFormatOptions {
  format?: string;
}

interface FormatListOptions extends Intl.ListFormatOptions {
  format?: string;
}

interface FormatDisplayNameOptions extends Intl.DisplayNamesOptions {
  format?: string;
}

// Number format part types
interface NumberFormatPart {
  type: 'currency' | 'decimal' | 'fraction' | 'group' | 'infinity' | 'integer' | 'literal' | 'minusSign' | 'nan' | 'plusSign' | 'percentSign' | 'relatedYear' | 'yearName';
  value: string;
}

// List format part types  
interface ListFormatPart {
  type: 'element' | 'literal';
  value: string;
}

// Display name types
type DisplayNameType = 'language' | 'region' | 'script' | 'currency';
type DisplayNameStyle = 'long' | 'short' | 'narrow';