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

<Meta title='@dxtmisha/en/functional/Composables/useFormattersRef - List Formatting'/>

# `useFormattersRef`

A composable for reactive formatting of data lists based on specified rules for each property.

**Parameters:**
- `list: RefType<List>` — source data list (Ref or ComputedRef).
- `options: Options` — formatting settings for each property:
    - `type: FormattersType` — formatter type (`currency`, `date`, `name`, `number`, `plural`, `unit`).
    - `options?: object` — additional settings for the specific formatter (e.g., currency code, date format).
    - `transformation?: function` — custom function for value transformation.

**Returns:**
- `listFormat: ComputedRef<FormattersReturn<List, Options>>` — formatted data list. For each property specified in `options`, a corresponding `{property}Format` field is added to the items.

### Generic Constraints

- `Options extends FormattersOptionsList` — type of formatting options for each property.
- `List extends FormattersListProp` — type of the source list (can be an array or a single item).

## Architecture: Lazy `computed` (Dynamic Getters)

This composable returns `listFormat` as a native JavaScript getter.
This design allows calling `useFormattersRef()` **outside of the Vue component lifecycle** (e.g., globally or in stores).
The `ComputedRef` object is created and cached by Vue upon the first access to the property during destructuring:

```typescript
// ComputedRef is created during destructuring in setup()
const { listFormat } = useFormattersRef(items, { price: { type: FormattersType.currency } })
```

> **Important**: Avoid multiple accesses via dot notation (e.g., `result.listFormat`). Always destructure the result once at the `setup` level to ensure only one instance of the `computed` property is created.

## Usage Example

```typescript
import { ref } from 'vue'
import { useFormattersRef } from '@dxtmisha/functional'
import { FormattersType } from '@dxtmisha/functional-basic'

const items = ref([
  { id: 1, price: 100, firstName: 'John', lastName: 'Doe' },
  { id: 2, price: 250, firstName: 'Jane', lastName: 'Smith' }
])

const { listFormat } = useFormattersRef(items, {
  price: { type: FormattersType.currency },
  name: { type: FormattersType.name }
})

// listFormat.value will contain:
// [
//   { ..., priceFormat: '$100.00', nameFormat: 'John Doe' },
//   { ..., priceFormat: '$250.00', nameFormat: 'Jane Smith' }
// ]
```
