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

<Meta title='@dxtmisha/en/functional/# List Management'/>

# List Management

The **ListDataRef** class is a controller for managing complex data lists, dropdown menus, and trees within the **Vue 3** ecosystem. It automates routine tasks such as filtering, item selection, focus management, and working with nested structures.

## Initialization and Data

The controller takes reactive data sources and provides optimized property sets for rendering components.

```javascript
import { ref } from 'vue'
import { ListDataRef } from '@dxtmisha/functional'

const items = ref([{ value: 1, label: 'Item' }, ...])
const controller = new ListDataRef(items)

// 1. Full data set for rendering (with focus/selected/disabled states)
const list = controller.fullData 

// 2. Optimized list (liteData)
// Automatically simplifies structure for very large data volumes
const fastList = controller.liteData 

// 3. Flat map of all items (including nested ones)
const flatMap = controller.map
```

## Selection and State

Automatic management of multiple or single selection, taking into account limits and the current locale state.

```javascript
const selected = ref([1])
// Use undefined to skip optional arguments and trigger default values
const controller = new ListDataRef(items, undefined, undefined, undefined, undefined, selected)

// 1. Retrieving selected values and names
controller.selectedValues // ComputedRef<[1]>
controller.selectedNames  // ComputedRef<['Item']>

// 2. Checking limits (min/max)
controller.isSelectedMax  // True if the maximum allowed quantity is selected
```

## Navigation and Focus

The controller provides a system of methods for "smart" movement through the list. Navigation automatically skips inactive elements and group headers, working only with items available for selection.

```javascript
const focus = ref(1)
const controller = new ListDataRef(items, focus)

// 1. Focus and Search states
controller.isFocus()        // Verification of current focus correctness
controller.isHighlight()    // Check if there are search matches
controller.highlightFirstItem // Index of the first matching item

// 2. Relative navigation (from selected item)
const next = controller.getSelectedNext() // Index of the next available item
const prev = controller.getSelectedPrev() // Index of the previous available item

// 3. Free navigation (by steps or objects)
const item = controller.getItemByStep(currentItem, 2) // Jump 2 items from current
const firstInGroup = controller.getFirstItemByParent('group-id') // First in group
```

## Working with Nesting

To handle groups or tree-like structures, the `getSubList()` method is used. It creates a new controller instance for the nested data while maintaining a global link to focus and selection states.

```javascript
// Inside a group component or dropdown menu:
const subController = controller.getSubList(groupItem)

// subController will automatically monitor changes in the parent list
const subItems = subController.fullData
```
