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

<Meta title='@dxtmisha/ru/functional-basic/Classes/SearchList - Продвинутое Управление Списком Поиска'/>

# Класс SearchList

Класс `SearchList` является основной точкой входа для реализации списков с возможностью поиска. Он координирует работу хранилища данных, состояния элемента поиска, логики сопоставления и параметров конфигурации для обеспечения бесперебойного процесса поиска.

## Ключевые особенности

- **Координированный поиск** — автоматически обновляет сопоставитель и регенерирует результаты при изменении поисковых значений или данных.
- **Гибкие результаты** — предоставляет метод `to()`, который возвращает либо весь список, либо отфильтрованные результаты с опциональной HTML-подсветкой.
- **Простая интеграция** — простой API для установки данных, столбцов и значений поиска.
- **Поддержка "Return Everything"** — можно настроить на отображение всего списка с выделением совпадений или только подходящих элементов.
- **Оптимизированная производительность** — использует глобальную утилиту `forEach` для быстрой обработки, когда поиск не активен, обходя генерацию кэша для максимальной эффективности.

## Инициализация

Для инициализации объекта вызовите конструктор `SearchList(list, columns, value, options)`.

**Параметры:**
- `list: T[]` — исходный массив элементов данных.
- `columns?: string[]` — пути к свойствам для поиска.
- `value?: string` — начальное значение поиска.
- `options?: SearchOptions` — конфигурация поиска.

```typescript
import { SearchList } from '@dxtmisha/functional'

const mockData = [
  { id: 1, name: 'Search Engine', category: 'Web' },
  { id: 2, name: 'List Manager', category: 'Utility' }
]

const search = new SearchList(mockData, ['name', 'category'], 'engine')

// Получение отфильтрованных и подсвеченных результатов
const results = search.to()
```

## Управление данными

### `to`

Метод `to()` обрабатывает текущий список данных в соответствии с поисковым запросом и возвращает массив отформатированных результатов.

**Возвращает:** `SearchFormatList<T, K>` — список элементов, где каждое доступное для поиска поле дополнено свойством `...Search`, содержащим HTML-подсветку совпадений.

**Поведение:**
- **Поиск активен**: Если длина поисковой строки больше или равна `limit`, метод фильтрует список (если только `returnEverything` не равно true) и применяет теги подсветки к совпадающему тексту.
- **Поиск неактивен**: Если поиск пуст или слишком короток, метод возвращает исходные элементы списка, отформатированные с их поисковыми свойствами, но без каких-либо выделений и с `searchActive: false`.

```javascript
const results = search.to()

results.forEach(item => {
  if (item.searchActive) {
    console.log(`Найдено совпадение: ${item.nameSearch}`)
  }
})
```

## Методы

### Информационные (Геттеры)

- `getData(): SearchListData` — Возвращает внутренний экземпляр управления данными.
- `getList(): T[]` — Возвращает исходный список данных.
- `getColumns(): string[] | undefined` — Возвращает текущие столбцы поиска.
- `getItem(): SearchListItem` — Возвращает экземпляр состояния элемента поиска.
- `getValue(): string | undefined` — Возвращает текущую строку поиска.
- `getOptions(): SearchListOptions` — Возвращает экземпляр управления опциями.

### Настройка (Сеттеры)

- `setList(list: T[]): this` — Устанавливает новый список данных.
- `setColumns(columns?: string[]): this` — Устанавливает новые столбцы поиска.
- `setValue(value?: string): this` — Устанавливает новое значение поиска и инициирует обновление сопоставителя.
- `setOptions(options: SearchOptions): this` — Устанавливает новые параметры поиска.

## Типы

### SearchOptions

Объект конфигурации для поведения `SearchList`:

- `limit?: number` — минимальная длина символов для запуска поиска (по умолчанию: `2`).
- `returnEverything?: boolean` — если `true`, возвращает все элементы вместо фильтрации; несовпадающие элементы будут иметь `searchActive: false`.
- `delay?: number` — задержка в миллисекундах (используется высокоуровневыми компонентами).
- `findExactMatch?: boolean` — если `true`, использует режим "Точная фраза"; иначе использует "Содержит все слова".
- `classSearchName?: string` — пользовательский CSS класс для тегов подсветки `<span />`.

### SearchFormatItem

Структура элемента, возвращаемого методом `to()`. Она включает в себя все исходные поля элемента данных плюс динамические поля, связанные с поиском:

- `[key]Search: string` — (Динамическое) значение соответствующего столбца, потенциально содержащее теги `<span />` для совпадений.
- `searchActive?: boolean` — логический флаг, указывающий, соответствует ли элемент текущим критериям поиска.

### SearchFormatList

Список отформатированных элементов поиска:
`type SearchFormatList<T, K> = SearchFormatItem<T, K>[]`

### SearchItem

Общий объект, по которому можно осуществлять поиск:
`type SearchItem = Record<string, any>`

### SearchListValue

Значение входного списка:
`type SearchListValue<T> = T[] | undefined`
