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

<Meta title='@dxtmisha/en/functional/Classes/GeoIntlRef - Reactive Number and Date Formatting'/>

# GeoIntlRef Class

A reactive class for managing the formatting of numbers, dates, currencies, and relative time. Ensures formatted strings automatically update when the locale changes.

## Key Features

- **Reactivity** — automatic formatted string updates when the locale `Ref` changes.
- **Internationalization** — full support for `Intl` standards for numbers, dates, currencies, and units.
- **Relative Time** — convenient methods for displaying time as "2 days ago" with limit support.
- **Lists and Sorting** — built-in methods for retrieving month names, weekdays, and locale-aware sorting.

## Initialization

### `constructor`

Creates a new `GeoIntlRef` instance for reactive formatting management. The class acts as a wrapper around `GeoIntl` and ensures all computed values automatically update when the locale code changes.

**Parameters:**
- `code?: RefOrNormal<string>` — locale code (e.g., `'en-US'`, `'fr-FR'`). Can be a regular string or a reactive `ref` object. If not provided, the current language from `GeoRef` is used.

```typescript
import { GeoIntlRef } from '@dxtmisha/functional'
import { ref } from 'vue'

// 1. Initialization with a reactive locale
const code = ref('en-US')
const geoIntl = new GeoIntlRef(code)

// 2. Using reactive formatting
const price = geoIntl.currency(1000, 'USD') // ComputedRef: '$1,000.00'

// 3. Automatic update
code.value = 'de-DE' // price will update automatically
```

## Display Names

### `display`
Returns the translated name of a language, region, or script.

**Parameters:**
- `value?: RefOrNormal<string>` — the code to translate (e.g., 'fr-FR').
- `typeOptions?: Intl.DisplayNamesOptions['type'] | Intl.DisplayNamesOptions` — display type options.

**Returns:** `ComputedRef<string>`

### `languageName`
Returns the display name of a language.

**Parameters:**
- `value?: RefOrNormal<string>` — language code.
- `style?: Intl.RelativeTimeFormatStyle` — formatting style.

**Returns:** `ComputedRef<string>`

### `countryName`
Returns the display name of a region (country).

**Parameters:**
- `value?: RefOrNormal<string>` — country code.
- `style?: Intl.RelativeTimeFormatStyle` — formatting style.

**Returns:** `ComputedRef<string>`

## Number Formatting

### `number`
Formats a number according to locale rules.

**Parameters:**
- `value: RefOrNormal<NumberOrString>` — value to format.
- `options?: Intl.NumberFormatOptions` — formatting options.

**Returns:** `ComputedRef<string>`

### `decimal`
Returns the decimal separator symbol for the current locale.

**Returns:** `ComputedRef<string>`

### `percent`
Formats a value as a percentage.

**Parameters:**
- `value: RefOrNormal<NumberOrString>` — input value (0.25 -> 25%).
- `options?: Intl.NumberFormatOptions` — formatting options.

**Returns:** `ComputedRef<string>`

### `percentBy100`
Formats a value as a percentage after dividing it by 100.

**Parameters:**
- `value: RefOrNormal<NumberOrString>` — input value (25 -> 25%).
- `options?: Intl.NumberFormatOptions` — formatting options.

**Returns:** `ComputedRef<string>`

### `plural`
Selects the correct plural form for a word based on a numeric value.

**Parameters:**
- `value: RefOrNormal<NumberOrString>` — numeric value.
- `words: string` — pipes-separated list of words (e.g., 'apple|apples').
- `options?: Intl.PluralRulesOptions` — plural rules options.
- `optionsNumber?: Intl.NumberFormatOptions` — numeric formatting options.

**Returns:** `ComputedRef<string>`

## Currencies and Units

### `currency`
Formats a numeric value as a currency string.

**Parameters:**
- `value: RefOrNormal<NumberOrString>` — amount.
- `currencyOptions?: RefOrNormal<string | Intl.NumberFormatOptions>` — currency code or options.
- `numberOnly?: boolean` — if `true`, returns only the number without the currency symbol.

**Returns:** `ComputedRef<string>`

### `currencySymbol`
Returns the currency symbol for a given currency code.

**Parameters:**
- `currency: RefOrNormal<string>` — currency code (e.g., 'EUR').
- `currencyDisplay?: keyof Intl.NumberFormatOptionsCurrencyDisplayRegistry` — how to display the currency.

**Returns:** `ComputedRef<string>`

### `unit`
Formats a number with a specific unit.

**Parameters:**
- `value: RefOrNormal<NumberOrString>` — numeric value.
- `unitOptions?: string | Intl.NumberFormatOptions` — unit name or options.

**Returns:** `ComputedRef<string>`

### `sizeFile`
Formats a file size into a human-readable format (bytes, KB, MB, etc.).

**Parameters:**
- `value: RefOrNormal<NumberOrString>` — size in bytes.
- `unitOptions?: string | Intl.NumberFormatOptions` — starting unit or options.

**Returns:** `ComputedRef<string>`

## Dates and Time

### `date`
Formats a date according to the locale.

**Parameters:**
- `value: RefOrNormal<NumberOrStringOrDate>` — input date.
- `type?: GeoDate` — format type ('date', 'time', 'datetime', etc.).
- `styleOptions?: Intl.DateTimeFormatOptions['month'] | Intl.DateTimeFormatOptions` — display style.
- `hour24?: boolean` — whether to use a 24-hour clock.

**Returns:** `ComputedRef<string>`

### `time`
Formats a time value.

**Parameters:**
- `value: RefOrNormal<NumberOrStringOrDate>` — input date/time.

**Returns:** `ComputedRef<string>`

### `month`
Returns the name of a specific month.

**Parameters:**
- `value?: RefOrNormal<NumberOrStringOrDate>` — input date.
- `style?: Intl.DateTimeFormatOptions['month']` — formatting style (long, short, narrow).

**Returns:** `ComputedRef<string>`

### `months`
Returns a list of all month names.

**Parameters:**
- `style?: Intl.DateTimeFormatOptions['month']` — formatting style.

**Returns:** `ComputedRef<ItemValue<number | undefined>[]>`

### `weekday`
Returns the name of a specific weekday.

**Parameters:**
- `value?: RefOrNormal<NumberOrStringOrDate>` — input date.
- `style?: Intl.DateTimeFormatOptions['weekday']` — formatting style.

**Returns:** `ComputedRef<string>`

### `weekdays`
Returns a list of all weekday names.

**Parameters:**
- `style?: Intl.DateTimeFormatOptions['weekday']` — formatting style.

**Returns:** `ComputedRef<ItemValue<number | undefined>[]>`

## Relative Time

### `relative`
Formats a date as relative time (e.g., "2 days ago").

**Parameters:**
- `value: RefOrNormal<NumberOrStringOrDate>` — input date.
- `styleOptions?: Intl.RelativeTimeFormatStyle | Intl.RelativeTimeFormatOptions` — formatting style.
- `todayValue?: Date` — reference date for "today".

**Returns:** `ComputedRef<string>`

### `relativeLimit`
Formats relative time with an automatic switch to standard date formatting if a limit is reached.

**Parameters:**
- `value: RefOrNormal<NumberOrStringOrDate>` — input date.
- `limit: number` — limit in days.
- `todayValue?: Date` — reference date for "today".
- `relativeOptions?: Intl.RelativeTimeFormatStyle | Intl.RelativeTimeFormatOptions` — relative formatting options.
- `dateOptions?: Intl.DateTimeFormatOptions` — standard date options.

**Returns:** `ComputedRef<string>`

### `relativeByValue`
Formats a numeric interval as relative time.

**Parameters:**
- `value: RefOrNormal<NumberOrString>` — quantity.
- `unit: Intl.RelativeTimeFormatUnit` — time unit (day, month, hour, etc.).
- `styleOptions?: Intl.RelativeTimeFormatStyle | Intl.RelativeTimeFormatOptions` — formatting style.

**Returns:** `ComputedRef<string>`

## Lists and Sorting

### `sort`
Sorts an array of strings or objects based on locale rules.

**Parameters:**
- `data: RefOrNormal<T[]>` — data array.
- `compareFn?: (a: T, b: T) => [string, string]` — mapper function to extract sortable strings.

**Returns:** `ComputedRef<T[]>`
