@dxtmisha/wiki 0.39.1 → 0.39.3

package/src/media/functional/functional-basic/classes/SearchList/SearchList.en.mdx

@@ -0,0 +1,113 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/SearchList - Advanced Searchable List Management'/>
+
+# SearchList Class
+
+The `SearchList` class is the primary entry point for implementing searchable lists. it coordinates between data storage, search item state, matching logic, and configuration options to provide a seamless search experience.
+
+## Key Features
+
+- **Coordinated Search** — automatically updates the matcher and regenerates results when search values or data change.
+- **Flexible Results** — provides a `to()` method that returns either the full list or filtered results with optional HTML highlights.
+- **Easy Integration** — simple API for setting data, columns, and search values.
+- **Support for "Return Everything"** — can be configured to show the full list with highlights on matches, or only the matching items.
+- **Optimized Performance** — uses a global `forEach` utility for fast processing when search is inactive, bypassing cache generation for maximum efficiency.
+
+## Initialization
+
+To initialize the object, call the `SearchList(list, columns, value, options)` constructor.
+
+**Parameters:**
+- `list: T[]` — the initial array of data items.
+- `columns?: string[]` — the property paths to search in.
+- `value?: string` — the initial search value.
+- `options?: SearchOptions` — search configuration.
+
+```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')
+
+// Get filtered and highlighted results
+const results = search.to()
+```
+
+## Data Management
+
+### `to`
+
+The `to()` method processes the current data list against the search query and returns an array of formatted results.
+
+**Returns:** `SearchFormatList<T, K>` — a list of items where each searchable field is supplemented with a `...Search` property containing HTML highlights.
+
+**Behavior:**
+- **Search Active**: If the search string length is greater than or equal to the `limit`, it filters the list (unless `returnEverything` is true) and applies highlight tags to matching text.
+- **Search Inactive**: If the search is empty or too short, it returns the original list items formatted with their search properties, but without any highlights and with `searchActive: false`.
+
+```javascript
+const results = search.to()
+
+results.forEach(item => {
+  if (item.searchActive) {
+    console.log(`Matched item found: ${item.nameSearch}`)
+  }
+})
+```
+
+## Methods
+
+### Information (Getters)
+
+- `getData(): SearchListData` — Returns the internal data management instance.
+- `getList(): T[]` — Returns the source data list.
+- `getColumns(): string[] | undefined` — Returns the current search columns.
+- `getItem(): SearchListItem` — Returns the search item state instance.
+- `getValue(): string | undefined` — Returns the current search string.
+- `getOptions(): SearchListOptions` — Returns the options management instance.
+
+### Configuration (Setters)
+
+- `setList(list: T[]): this` — Sets a new data list.
+- `setColumns(columns?: string[]): this` — Sets new search columns.
+- `setValue(value?: string): this` — Sets a new search value and triggers a matcher update.
+- `setOptions(options: SearchOptions): this` — Sets new search options.
+
+## Types
+
+### SearchOptions
+
+Configuration object for the `SearchList` behavior:
+
+- `limit?: number` — minimum character length to trigger search (default: `2`).
+- `returnEverything?: boolean` — if `true`, returns all items instead of filtering; non-matches will have `searchActive: false`.
+- `delay?: number` — debouncing delay in milliseconds (used by higher-level components).
+- `findExactMatch?: boolean` — if `true`, uses "Exact Phrase" mode; otherwise uses "Contains All Words".
+- `classSearchName?: string` — custom CSS class for the `<span />` highlight tags.
+
+### SearchFormatItem
+
+The structure of an item returned by the `to()` method. It includes all original fields from the data item plus dynamic search-related fields:
+
+- `[key]Search: string` — (Dynamic) value of the corresponding column, potentially containing `<span />` tags for matches.
+- `searchActive?: boolean` — boolean flag indicating if the item matched the current search criteria.
+
+### SearchFormatList
+
+A list of formatted search items:
+`type SearchFormatList<T, K> = SearchFormatItem<T, K>[]`
+
+### SearchItem
+
+A generic object that can be searched:
+`type SearchItem = Record<string, any>`
+
+### SearchListValue
+
+The input list value:
+`type SearchListValue<T> = T[] | undefined`

package/src/media/functional/functional-basic/classes/SearchList/SearchList.ru.mdx

@@ -0,0 +1,113 @@
+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`

package/src/media/functional/functional-basic/classes/SearchList/SearchList.vi.mdx

@@ -0,0 +1,113 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/SearchList - Quản lý Danh sách Tìm kiếm Nâng cao'/>
+
+# Lớp SearchList
+
+Lớp `SearchList` là điểm truy cập chính để triển khai các danh sách có thể tìm kiếm. Nó điều phối giữa việc lưu trữ dữ liệu, trạng thái thành phần tìm kiếm, logic so khớp và các tùy chọn cấu hình để cung cấp trải nghiệm tìm kiếm liền mạch.
+
+## Tính năng chính
+
+- **Tìm kiếm được điều phối** — tự động cập nhật trình so khớp và tạo lại kết quả khi giá trị tìm kiếm hoặc dữ liệu thay đổi.
+- **Kết quả linh hoạt** — cung cấp phương thức `to()` trả về toàn bộ danh sách hoặc các kết quả đã được lọc với các phần làm nổi bật HTML tùy chọn.
+- **Tích hợp dễ dàng** — API đơn giản để thiết lập dữ liệu, cột và giá trị tìm kiếm.
+- **Hỗ trợ "Trả về tất cả" (Return Everything)** — có thể được cấu hình để hiển thị toàn bộ danh sách với các phần nổi bật tại các điểm khớp, hoặc chỉ các thành phần khớp.
+- **Hiệu suất tối ưu** — sử dụng tiện ích `forEach` toàn cục để xử lý nhanh khi tìm kiếm không hoạt động, bỏ qua việc tạo bộ nhớ đệm để đạt hiệu quả tối đa.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `SearchList(list, columns, value, options)`.
+
+**Tham số:**
+- `list: T[]` — mảng dữ liệu ban đầu.
+- `columns?: string[]` — các đường dẫn thuộc tính để tìm kiếm.
+- `value?: string` — giá trị tìm kiếm ban đầu.
+- `options?: SearchOptions` — cấu hình tìm kiếm.
+
+```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')
+
+// Lấy kết quả đã được lọc và làm nổi bật
+const results = search.to()
+```
+
+## Quản lý dữ liệu
+
+### `to`
+
+Phương thức `to()` xử lý danh sách dữ liệu hiện tại dựa trên truy vấn tìm kiếm và trả về một mảng kết quả đã được định dạng.
+
+**Trả về:** `SearchFormatList<T, K>` — một danh sách các mục trong đó mỗi trường có thể tìm kiếm được bổ sung thêm thuộc tính `...Search` chứa các phần làm nổi bật HTML.
+
+**Hành vi:**
+- **Tìm kiếm đang hoạt động**: Nếu độ dài chuỗi tìm kiếm lớn hơn hoặc bằng `limit`, nó sẽ lọc danh sách (trừ khi `returnEverything` là true) và áp dụng các thẻ làm nổi bật cho văn bản khớp.
+- **Tìm kiếm không hoạt động**: Nếu chuỗi tìm kiếm trống hoặc quá ngắn, nó sẽ trả về các mục danh sách ban đầu được định dạng với các thuộc tính tìm kiếm của chúng, nhưng không có bất kỳ phần làm nổi bật nào và với `searchActive: false`.
+
+```javascript
+const results = search.to()
+
+results.forEach(item => {
+  if (item.searchActive) {
+    console.log(`Đã tìm thấy mục khớp: ${item.nameSearch}`)
+  }
+})
+```
+
+## Phương thức
+
+### Thông tin (Getters)
+
+- `getData(): SearchListData` — Trả về thực thể quản lý dữ liệu nội bộ.
+- `getList(): T[]` — Trả về danh sách dữ liệu nguồn.
+- `getColumns(): string[] | undefined` — Trả về các cột tìm kiếm hiện tại.
+- `getItem(): SearchListItem` — Trả về thực thể trạng thái thành phần tìm kiếm.
+- `getValue(): string | undefined` — Trả về chuỗi tìm kiếm hiện tại.
+- `getOptions(): SearchListOptions` — Trả về thực thể quản lý tùy chọn.
+
+### Cấu hình (Setters)
+
+- `setList(list: T[]): this` — Thiết lập danh sách dữ liệu mới.
+- `setColumns(columns?: string[]): this` — Thiết lập các cột tìm kiếm mới.
+- `setValue(value?: string): this` — Thiết lập giá trị tìm kiếm mới và kích hoạt cập nhật trình so khớp.
+- `setOptions(options: SearchOptions): this` — Thiết lập các tùy chọn tìm kiếm mới.
+
+## Các kiểu dữ liệu (Types)
+
+### SearchOptions
+
+Đối tượng cấu hình cho hành vi của `SearchList`:
+
+- `limit?: number` — độ dài ký tự tối thiểu để kích hoạt tìm kiếm (mặc định: `2`).
+- `returnEverything?: boolean` — nếu là `true`, trả về tất cả các mục thay vì lọc; các mục không khớp sẽ có `searchActive: false`.
+- `delay?: number` — độ trễ debounce tính bằng mili giây (được sử dụng bởi các thành phần cấp cao hơn).
+- `findExactMatch?: boolean` — nếu là `true`, sử dụng chế độ "Phân đoạn chính xác"; nếu không sẽ sử dụng "Chứa tất cả các từ".
+- `classSearchName?: string` — lớp CSS tùy chỉnh cho các thẻ làm nổi bật `<span />`.
+
+### SearchFormatItem
+
+Cấu trúc của một mục được trả về bởi phương thức `to()`. Nó bao gồm tất cả các trường ban đầu từ mục dữ liệu cộng với các trường liên quan đến tìm kiếm động:
+
+- `[key]Search: string` — (Động) giá trị của cột tương ứng, có thể chứa các thẻ `<span />` cho các phần khớp.
+- `searchActive?: boolean` — cờ boolean cho biết mục đó có khớp với tiêu chí tìm kiếm hiện tại hay không.
+
+### SearchFormatList
+
+Danh sách các mục tìm kiếm đã được định dạng:
+`type SearchFormatList<T, K> = SearchFormatItem<T, K>[]`
+
+### SearchItem
+
+Một đối tượng chung có thể được tìm kiếm:
+`type SearchItem = Record<string, any>`
+
+### SearchListValue
+
+Giá trị danh sách đầu vào:
+`type SearchListValue<T> = T[] | undefined`

package/src/media/functional/functional-basic/classes/SearchListData/SearchListData.en.mdx

@@ -0,0 +1,83 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/SearchListData - Search Data Management'/>
+
+# SearchListData Class
+
+The `SearchListData` class manages the source data list and its associated search cache. It handles the formatting of items, extraction of values from nested paths, and the application of highlight tags to matching strings.
+
+## Key Features
+
+- **Lazy Initialization** — implements on-demand cache generation, ensuring performance overhead only occurs when a search is actively performed.
+- **Search Caching** — generates a flattened string representation of specified columns for each item to enable fast searching.
+- **Nested Path Support** — ability to extract data from deep object structures (e.g., `'user.profile.name'`).
+- **Automatic Highlighting** — wraps matching parts of the string in HTML tags for visual feedback.
+- **CamelCase Formatting** — transforms column paths into convenient property names (e.g., `'user.name'` becomes `'userNameSearch'`).
+
+## Initialization
+
+To initialize the object, call the `SearchListData(list, columns, item, options)` constructor.
+
+**Parameters:**
+- `list: T[]` — the original array of data items.
+- `columns?: string[]` — an array of property paths to search in.
+- `item: SearchListItem` — the search item state.
+- `options: SearchListOptions` — configuration options.
+
+```typescript
+import { SearchListData, SearchListItem, SearchListOptions } from '@dxtmisha/functional-basic'
+
+const options = new SearchListOptions()
+const item = new SearchListItem('alice', options)
+const data = new SearchListData(
+  [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }],
+  ['name'],
+  item,
+  options
+)
+
+const results = data.forEach((origItem, value) => {
+  return data.toFormatItem(origItem, true)
+})
+```
+
+## Methods
+
+### Information
+
+- `is(): boolean` — Checks if both the list and columns are initialized.
+- `isList(): boolean` — Checks if the source list is provided.
+- `getList(): T[]` — Returns the original data list.
+- `getColumns(): string[] | undefined` — Returns the current search columns.
+- `findCacheItem(item: T)` — Finds the cached search value for a specific original item.
+
+### Configuration (Setters)
+
+- `setList(list: T[]): this` — Updates the data list and regenerates the cache.
+- `setColumns(columns?: string[]): this` — Updates the search columns and regenerates the cache.
+
+### Processing
+
+- `toFormatItem(item: T, selection: boolean): object` — Converts an original item into a formatted one with highlight tags.
+- `forEach(callback: Function): Array` — Iterates over the cache and returns a list of items formatted via the callback.
+
+## Cache Generation
+
+The search system uses a lazy initialization strategy to optimize performance when working with large lists:
+- **On-Demand Generation**: The cache is not built when the class is instantiated. Instead, it is generated the very first time a search operation requires it.
+- **Cache Invalidation**: Calling `setList()` or `setColumns()` automatically destroys the existing cache. It will be seamlessly rebuilt during the next search.
+- **Flattened Representation**: To create the cache, the class iterates through the original list and extracts values from the specified `columns` (including deep paths). These values are converted to strings and concatenated into a single, space-separated string. This composite string is saved in `SearchCacheItem.value` and used for all subsequent, high-speed regular expression matching. This approach completely eliminates complex object traversal during active user typing.
+
+## Types
+
+### SearchCacheItem
+
+Object representing a single item in the search cache:
+
+- `item: T` — reference to the original data item.
+- `value: string` — flattened string representation of the searchable columns.
+
+### SearchCache
+
+A collection of `SearchCacheItem` objects used for efficient searching:
+`type SearchCache<T> = SearchCacheItem<T>[]`

package/src/media/functional/functional-basic/classes/SearchListData/SearchListData.ru.mdx

@@ -0,0 +1,83 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/SearchListData - Управление Данными Поиска'/>
+
+# Класс SearchListData
+
+Класс `SearchListData` управляет исходным списком данных и связанным с ним кэшем поиска. Он отвечает за форматирование элементов, извлечение значений из вложенных путей и применение тегов выделения к совпадающим строкам.
+
+## Ключевые особенности
+
+- **Отложенная инициализация (Lazy)** — реализует генерацию кэша по требованию, гарантируя, что затраты производительности происходят только при активном выполнении поиска.
+- **Кэширование поиска** — генерирует плоское строковое представление указанных столбцов для каждого элемента для быстрого поиска.
+- **Поддержка вложенных путей** — возможность извлекать данные из глубоких структур объектов (например, `'user.profile.name'`).
+- **Автоматическое выделение** — оборачивает совпадающие части строки в HTML-теги для визуальной обратной связи.
+- **Форматирование CamelCase** — преобразует пути столбцов в удобные имена свойств (например, `'user.name'` превращается в `'userNameSearch'`).
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `SearchListData(list, columns, item, options)`.
+
+**Параметры:**
+- `list: T[]` — исходный массив элементов данных.
+- `columns?: string[]` — массив путей к свойствам для поиска.
+- `item: SearchListItem` — состояние элемента поиска.
+- `options: SearchListOptions` — параметры конфигурации.
+
+```typescript
+import { SearchListData, SearchListItem, SearchListOptions } from '@dxtmisha/functional-basic'
+
+const options = new SearchListOptions()
+const item = new SearchListItem('alice', options)
+const data = new SearchListData(
+  [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }],
+  ['name'],
+  item,
+  options
+)
+
+const results = data.forEach((origItem, value) => {
+  return data.toFormatItem(origItem, true)
+})
+```
+
+## Методы
+
+### Информационные
+
+- `is(): boolean` — Проверяет, инициализированы ли и список, и столбцы.
+- `isList(): boolean` — Проверяет, предоставлен ли исходный список.
+- `getList(): T[]` — Возвращает исходный список данных.
+- `getColumns(): string[] | undefined` — Возвращает текущие столбцы поиска.
+- `findCacheItem(item: T)` — Находит кэшированное значение поиска для конкретного исходного элемента.
+
+### Настройка (Сеттеры)
+
+- `setList(list: T[]): this` — Обновляет список данных и регенерирует кэш.
+- `setColumns(columns?: string[]): this` — Обновляет столбцы поиска и регенерирует кэш.
+
+### Обработка
+
+- `toFormatItem(item: T, selection: boolean): object` — Преобразует исходный элемент в отформатированный с тегами выделения.
+- `forEach(callback: Function): Array` — Перебирает кэш и возвращает список элементов, отформатированных через callback.
+
+## Формирование кэша
+
+Система поиска использует стратегию отложенной инициализации (lazy initialization) для оптимизации производительности при работе с большими списками:
+- **Генерация по требованию**: Кэш не создается при создании экземпляра класса. Вместо этого он формируется только в тот момент, когда операция поиска запрашивает его в первый раз.
+- **Инвалидация кэша**: Вызов `setList()` или `setColumns()` автоматически сбрасывает существующий кэш. Он будет незаметно перестроен при следующем поиске.
+- **Плоское представление**: Для создания кэша класс проходит по исходному списку и извлекает значения из указанных `columns` (включая глубокие пути). Эти значения преобразуются в строки и объединяются в одну длинную строку, разделенную пробелами. Эта объединенная строка сохраняется в `SearchCacheItem.value` и используется во всех последующих высокоскоростных проверках регулярными выражениями. Такой подход полностью исключает сложный обход объектов во время активного набора текста пользователем.
+
+## Типы
+
+### SearchCacheItem
+
+Объект, представляющий отдельный элемент в кэше поиска:
+
+- `item: T` — ссылка на исходный элемент данных.
+- `value: string` — плоское строковое представление доступных для поиска столбцов.
+
+### SearchCache
+
+Коллекция объектов `SearchCacheItem`, используемая для эффективного поиска:
+`type SearchCache<T> = SearchCacheItem<T>[]`

package/src/media/functional/functional-basic/classes/SearchListData/SearchListData.vi.mdx

@@ -0,0 +1,83 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/SearchListData - Quản lý Dữ liệu Tìm kiếm'/>
+
+# Lớp SearchListData
+
+Lớp `SearchListData` quản lý danh sách dữ liệu nguồn và bộ nhớ đệm (cache) tìm kiếm liên quan. Nó xử lý việc định dạng các thành phần, trích xuất các giá trị từ các đường dẫn lồng nhau và áp dụng các thẻ làm nổi bật (highlight tags) cho các chuỗi khớp.
+
+## Tính năng chính
+
+- **Khởi tạo trễ (Lazy Initialization)** — thực hiện tạo bộ nhớ đệm theo yêu cầu, đảm bảo chi phí hiệu suất chỉ xảy ra khi tìm kiếm đang được thực hiện tích cực.
+- **Bộ nhớ đệm tìm kiếm** — tạo ra một biểu diễn chuỗi phẳng của các cột được chỉ định cho mỗi thành phần để cho phép tìm kiếm nhanh chóng.
+- **Hỗ trợ đường dẫn lồng nhau** — khả năng trích xuất dữ liệu từ các cấu trúc đối tượng sâu (ví dụ: `'user.profile.name'`).
+- **Làm nổi bật tự động** — bao quanh các phần khớp của chuỗi trong các thẻ HTML để phản hồi trực quan.
+- **Định dạng CamelCase** — biến đổi các đường dẫn cột thành các tên thuộc tính tiện lợi (ví dụ: `'user.name'` trở thành `'userNameSearch'`).
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `SearchListData(list, columns, item, options)`.
+
+**Tham số:**
+- `list: T[]` — mảng ban đầu của các thành phần dữ liệu.
+- `columns?: string[]` — một mảng các đường dẫn thuộc tính để tìm kiếm.
+- `item: SearchListItem` — trạng thái thành phần tìm kiếm.
+- `options: SearchListOptions` — các tùy chọn cấu hình.
+
+```typescript
+import { SearchListData, SearchListItem, SearchListOptions } from '@dxtmisha/functional-basic'
+
+const options = new SearchListOptions()
+const item = new SearchListItem('alice', options)
+const data = new SearchListData(
+  [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }],
+  ['name'],
+  item,
+  options
+)
+
+const results = data.forEach((origItem, value) => {
+  return data.toFormatItem(origItem, true)
+})
+```
+
+## Phương thức
+
+### Thông tin
+
+- `is(): boolean` — Kiểm tra xem cả danh sách và các cột đã được khởi tạo hay chưa.
+- `isList(): boolean` — Kiểm tra xem danh sách nguồn có được cung cấp hay không.
+- `getList(): T[]` — Trả về danh sách dữ liệu ban đầu.
+- `getColumns(): string[] | undefined` — Trả về các cột tìm kiếm hiện tại.
+- `findCacheItem(item: T)` — Tìm thành phần tìm kiếm đã lưu trong bộ nhớ đệm cho một thành phần gốc cụ thể.
+
+### Cấu hình (Setters)
+
+- `setList(list: T[]): this` — Cập nhật danh sách dữ liệu và tạo lại bộ nhớ đệm.
+- `setColumns(columns?: string[]): this` — Cập nhật các cột tìm kiếm và tạo lại bộ nhớ đệm.
+
+### Xử lý
+
+- `toFormatItem(item: T, selection: boolean): object` — Chuyển đổi một thành phần gốc thành một thành phần đã định dạng với các thẻ làm nổi bật.
+- `forEach(callback: Function): Array` — Lặp qua bộ nhớ đệm và trả về danh sách các thành phần được định dạng thông qua hàm gọi lại (callback).
+
+## Quá trình tạo bộ nhớ đệm
+
+Hệ thống tìm kiếm sử dụng chiến lược khởi tạo trễ (lazy initialization) để tối ưu hóa hiệu suất khi làm việc với các danh sách lớn:
+- **Tạo theo yêu cầu**: Bộ nhớ đệm không được xây dựng khi lớp được khởi tạo. Thay vào đó, nó chỉ được tạo ra vào lần đầu tiên một thao tác tìm kiếm yêu cầu.
+- **Vô hiệu hóa bộ nhớ đệm**: Gọi `setList()` hoặc `setColumns()` sẽ tự động phá hủy bộ nhớ đệm hiện tại. Nó sẽ được xây dựng lại một cách liền mạch trong lần tìm kiếm tiếp theo.
+- **Biểu diễn phẳng**: Để tạo bộ nhớ đệm, lớp sẽ lặp qua danh sách ban đầu và trích xuất các giá trị từ các `columns` (bao gồm cả các đường dẫn sâu). Các giá trị này được chuyển đổi thành chuỗi và nối thành một chuỗi duy nhất, cách nhau bằng dấu cách. Chuỗi tổng hợp này được lưu trong `SearchCacheItem.value` и được sử dụng cho tất cả các kiểm tra biểu thức chính quy tốc độ cao tiếp theo. Phương pháp này loại bỏ hoàn toàn việc duyệt đối tượng phức tạp trong quá trình người dùng đang gõ phím.
+
+## Các kiểu dữ liệu (Types)
+
+### SearchCacheItem
+
+Đối tượng đại diện cho một mục duy nhất trong bộ nhớ đệm tìm kiếm:
+
+- `item: T` — tham chiếu đến thành phần dữ liệu gốc.
+- `value: string` — biểu diễn chuỗi phẳng của các cột có thể tìm kiếm.
+
+### SearchCache
+
+Một tập hợp các đối tượng `SearchCacheItem` được sử dụng để tìm kiếm hiệu quả:
+`type SearchCache<T> = SearchCacheItem<T>[]`

package/src/media/functional/functional-basic/classes/SearchListItem/SearchListItem.en.mdx

@@ -0,0 +1,53 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/SearchListItem - Search Item Management'/>
+
+# SearchListItem Class
+
+The `SearchListItem` class represents the current state of a single search input. It manages the value being searched and determines whether a search operation should be triggered based on configured options.
+
+## Key Features
+
+- **Value Management** — provides easy methods to get and set the search string.
+- **Activation Logic** — determines if a search should be triggered based on the length of the search string.
+- **Type Safety** — includes type guards to verify if the value is non-empty.
+
+## Initialization
+
+To initialize the object, call the `SearchListItem(value, options)` constructor.
+
+**Parameters:**
+- `value: string | undefined` — the initial search value.
+- `options: SearchListOptions` — an instance of `SearchListOptions` to provide the search limit.
+
+```typescript
+import { SearchListItem, SearchListOptions } from '@dxtmisha/functional-basic'
+
+const options = new SearchListOptions({ limit: 3 })
+const item = new SearchListItem('he', options)
+
+console.log(item.isSearch()) // false (length < 3)
+item.set('hello')
+console.log(item.isSearch()) // true (length >= 3)
+```
+
+## Methods
+
+### Information
+
+- `is(): boolean` — Checks if the current value is not empty or undefined.
+- `isSearch(): boolean` — Checks if a search should be performed (value exists AND length >= limit).
+- `get(): string` — Returns the current search value as a string.
+
+### Configuration (Setters)
+
+- `set(value?: string): this` — Sets a new search value and returns the current instance.
+
+## Search Activation
+
+The `SearchListItem` class acts as a filter that determines whether the search system should start processing data. This is handled by the `isSearch()` method, which uses the `limit` option from `SearchListOptions`.
+
+- **Minimum Length (`limit`)**: A search is only considered active if the number of characters in the search string is greater than or equal to the defined limit.
+- **Default Behavior**: By default, the limit is set to `2`. This means searching for `"a"` will not trigger a match, but `"ad"` or `"admin"` will.
+
+This logic helps prevent unnecessary computations and "noisy" results when the user has only typed a single character.