import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/en/functional-basic/Classes/GeoIntl - Internationalization (Intl)'/>

# GeoIntl Class

The `GeoIntl` class is a high-level, optimized wrapper over the native browser `Intl` API, designed specifically for seamless integration with `Geo` geolocation capabilities. It provides a unified, locale-aware interface for formatting numbers, currencies, units, dates, times, and geographic names, while automatically handling locale detection and instance management.

The class implements a **Per-locale Singleton pattern**, ensuring that only one instance is created and cached for each unique locale code, significantly reducing the overhead of repetitive `Intl` object construction.

## Key Features

- **Instance Caching** — Automatically manages and reuses instances based on the standard locale string.
- **Unified Formatting API** — Simplifies complex `Intl` configurations into straightforward, high-level methods.
- **Adaptive Geolocation** — Automatically pulls defaults from the global `Geo` state if no explicit locale is provided.
- **Cultural Awareness** — Correctly handles diverse naming conventions, calendar start days, and pluralization rules across different cultures.

## Initialization

### `getInstance`

Retrieves a cached instance or creates a new one for the specified locale code.

**Parameters:**
- `code?: string` — Standardized locale string (e.g., `'en-US'`, `'ru-RU'`). Defaults to `Geo.getLocation()`.

**Returns:** `GeoIntl` — The singleton instance for the requested locale.

```javascript
import { GeoIntl } from '@dxtmisha/functional-basic'

const intl = GeoIntl.getInstance('en-US')
const currentIntl = new GeoIntl() // Also uses the singleton cache internally
```

## Geographic & Localization Methods

- `getLocation(): string` — Returns the normalized standard locale string (e.g., `'en-US'`).
- `getFirstDay(): string` — Returns the first day of the week specification for the locale (e.g., `'Mon'`, `'Sun'`).

## Names & Regions

### `display`

Provides localized translations for languages, regions, and scripts using the `Intl.DisplayNames` engine.

**Parameters:**
- `value?: string` — The identifier code (e.g., `'fr'`, `'US'`).
- `typeOptions?` — A string representing the display type (`'language'`, `'region'`, `'script'`) or a full `Intl.DisplayNamesOptions` object.

**Returns:** `string` — The localized display name.

```javascript
intl.display('fr', 'language') // 'French'
intl.display('DE', 'region')   // 'Germany'
```

### `languageName` / `countryName`

Shorthand methods for retrieving localized names for languages and countries.

**Parameters:**
- `value?: string` — Language or country code.
- `style?` — Formatting style: `'long'`, `'short'`, or `'narrow'`.

**Returns:** `string`

### `fullName`

Formats a person's full name according to the cultural conventions of the current locale. The component order (First-Middle-Last or Last-First-Middle) is determined by the `nameFormat` within the geographic data.

**Parameters:**
- `last: string` — Last name.
- `first: string` — First name.
- `surname?: string` — Middle name or patronymic (optional).
- `short?: boolean` — If `true`, abbreviates names after the first to initials (e.g., `Smith J. D.`).

**Returns:** `string`

## Numeric Formatting

### `number`

Formats a number using the `Intl.NumberFormat` capabilities.

**Parameters:**
- `value: NumberOrString` — The numeric value to format.
- `options?: Intl.NumberFormatOptions` — Configuration for decimal places, grouping, etc.

**Returns:** `string`

### `currency`

Specialized monetary formatter with automatic symbol placement.

**Parameters:**
- `value: NumberOrString` — Amount. Also parses strings with currency suffixes (e.g., `'100 USD'`).
- `currencyOptions?: string | Intl.NumberFormatOptions` — Currency code (`'USD'`) or detailed formatting options.
- `numberOnly?: boolean` — If `true`, returns only the formatted digits without the currency symbol.

**Returns:** `string`

```javascript
intl.currency(1500, 'USD') // '$1,500.00'
intl.currency('1500 EUR')  // '€1,500.00'
```

### `unit` / `sizeFile`

Formats numbers with units of measurement. `sizeFile` provides recursive scaling for byte values (automatically switching to KB, MB, GB).

**Parameters (`sizeFile`):**
- `value: NumberOrString` — Size in bytes.
- `unitOptions?` — Starting unit (defaults to `'byte'`).

**Returns:** `string`

### `plural`

Applies locale-sensitive pluralization rules.

**Parameters:**
- `value: NumberOrString` — The count.
- `words: string` — Pipe-separated forms: `one|two|few|many|other|zero`.
- `options?` — `Intl.PluralRulesOptions`.

**Returns:** `string` — Formatted number followed by the correct word form.

## Dates & Time

### `date` / `time`

Main date formatting engine providing localized representations based on predefined `GeoDate` presets.

**Parameters:**
- `value: NumberOrStringOrDate` — The date input.
- `type?: GeoDate` — Preset identifier: `'date'`, `'time'`, `'datetime'`, `'full'`, etc.
- `styleOptions?` — Custom `Intl.DateTimeFormatOptions` or a month style string.
- `hour24?: boolean` — Forces 24-hour time representation.

**Returns:** `string`

### `months` / `weekdays`

Returns arrays of localized labels for months or days, ideal for populating UI selection components.

**Returns:** `ItemValue<number>[]` — Array of objects with `label` and `value` fields.

## Relative Time

### `relative`

Calculates and formats the relative time difference from a reference point (now), automatically selecting the most appropriate time unit.

**Parameters:**
- `value: NumberOrStringOrDate` — The past or future date.
- `styleOptions?` — Formatting style (e.g., `'long'`, `'short'`).
- `todayValue?: Date` — Explicit reference point (defaults to `new Date()`).

**Returns:** `string` (e.g., `'2 hours ago'`, `'in 3 days'`)

### `relativeLimit`

Conditional formatter that bridge relative and absolute time. If the date is within a certain `limit` of days, it returns relative time; otherwise, it switches to a standard absolute date format.

**Returns:** `string`

## Sorting

### `sort`

Sorts an array of elements using locale-sensitive comparison via `Intl.Collator`.

**Parameters:**
- `data: T[]` — The target array.
- `compareFn?` — An optional transformation function to extract sort keys from complex objects.

**Returns:** `T[]` — The sorted array.

```javascript
intl.sort(['banana', 'apple', 'cherry'])
// ['apple', 'banana', 'cherry']
```
