@dxtmisha/wiki 0.25.1 → 0.39.2

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

@@ -0,0 +1,53 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/SearchListItem - Управление Элементом Поиска'/>
+
+# Класс SearchListItem
+
+Класс `SearchListItem` представляет текущее состояние ввода поиска. Он управляет значением для поиска и определяет, следует ли запускать операцию поиска на основе настроенных параметров.
+
+## Ключевые особенности
+
+- **Управление значением** — предоставляет удобные методы для получения и установки строки поиска.
+- **Логика активации** — определяет, должен ли быть запущен поиск, основываясь на длине строки поиска.
+- **Типизация** — включает Type Guards для проверки заполненности значения.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `SearchListItem(value, options)`.
+
+**Параметры:**
+- `value: string | undefined` — начальное значение поиска.
+- `options: SearchListOptions` — экземпляр `SearchListOptions` для получения лимита поиска.
+
+```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 (длина < 3)
+item.set('hello')
+console.log(item.isSearch()) // true (длина >= 3)
+```
+
+## Методы
+
+### Информационные
+
+- `is(): boolean` — Проверяет, что текущее значение не является пустым или undefined.
+- `isSearch(): boolean` — Проверяет, следует ли выполнять поиск (значение существует И длина >= лимита).
+- `get(): string` — Возвращает текущее значение поиска в виде строки.
+
+### Настройка (Сеттеры)
+
+- `set(value?: string): this` — Устанавливает новое значение поиска и возвращает текущий экземпляр.
+
+## Активация поиска
+
+Класс `SearchListItem` выступает в роли фильтра, который определяет, должна ли система поиска начать обработку данных. Это реализуется через метод `isSearch()`, который использует опцию `limit` из `SearchListOptions`.
+
+- **Минимальная длина (`limit`)**: Поиск считается активным только в том случае, если количество символов в строке поиска больше или равно установленному лимиту.
+- **Поведение по умолчанию**: По умолчанию лимит равен `2`. Это означает, что поиск по букве `"а"` не запустит процесс сопоставления, а по `"ад"` или `"админ"` — запустит.
+
+Эта логика помогает избежать лишних вычислений и "шумных" результатов, когда пользователь ввел только один символ.

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

@@ -0,0 +1,53 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/SearchListItem - Quản lý Thành phần Tìm kiếm'/>
+
+# Lớp SearchListItem
+
+Lớp `SearchListItem` đại diện cho trạng thái hiện tại của nội dung nhập tìm kiếm. Nó quản lý giá trị đang được tìm kiếm và xác định liệu có nên kích hoạt thao tác tìm kiếm hay không dựa trên các tùy chọn đã cấu hình.
+
+## Tính năng chính
+
+- **Quản lý giá trị** — cung cấp các phương thức dễ dàng để lấy và thiết lập chuỗi tìm kiếm.
+- **Logic kích hoạt** — xác định liệu có nên bắt đầu tìm kiếm hay không dựa trên độ dài của chuỗi tìm kiếm.
+- **An toàn kiểu dữ liệu** — bao gồm các type guard để xác minh xem giá trị có khác rỗng hay không.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `SearchListItem(value, options)`.
+
+**Tham số:**
+- `value: string | undefined` — giá trị tìm kiếm ban đầu.
+- `options: SearchListOptions` — một thực thể của `SearchListOptions` để cung cấp giới hạn tìm kiếm.
+
+```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 (độ dài < 3)
+item.set('hello')
+console.log(item.isSearch()) // true (độ dài >= 3)
+```
+
+## Phương thức
+
+### Thông tin
+
+- `is(): boolean` — Kiểm tra xem giá trị hiện tại có khác rỗng hoặc không xác định hay không.
+- `isSearch(): boolean` — Kiểm tra xem có nên thực hiện tìm kiếm hay không (giá trị tồn tại VÀ độ dài >= giới hạn).
+- `get(): string` — Trả về giá trị tìm kiếm hiện tại dưới dạng chuỗi.
+
+### Cấu hình (Setters)
+
+- `set(value?: string): this` — Thiết lập giá trị tìm kiếm mới và trả về thực thể hiện tại.
+
+## Kích hoạt tìm kiếm
+
+Lớp `SearchListItem` đóng vai trò như một bộ lọc quyết định xem hệ thống tìm kiếm có nên bắt đầu xử lý dữ liệu hay không. Điều này được xử lý bởi phương thức `isSearch()`, phương thức này sử dụng tùy chọn `limit` từ `SearchListOptions`.
+
+- **Độ dài tối thiểu (`limit`)**: Một tìm kiếm chỉ được coi là hoạt động nếu số lượng ký tự trong chuỗi tìm kiếm lớn hơn hoặc bằng giới hạn đã xác định.
+- **Hành vi mặc định**: Theo mặc định, giới hạn được đặt thành `2`. Điều này có nghĩa là việc tìm kiếm `"a"` sẽ không kích hoạt kết quả khớp, nhưng `"ad"` hoặc `"admin"` thì có.
+
+Logic này giúp ngăn chặn các tính toán không cần thiết và các kết quả "nhiễu" khi người dùng mới chỉ nhập một ký tự duy nhất.

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

@@ -0,0 +1,55 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/SearchListMatcher - Search Matcher Logic'/>
+
+# SearchListMatcher Class
+
+The `SearchListMatcher` class is responsible for the core matching logic. It converts the current search string into a regular expression and provides methods to check if various data values match that expression.
+
+## Key Features
+
+- **Dynamic RegExp Generation** — automatically builds or resets the matcher when the search term or options change.
+- **Search Modes** — supports both standard partial matching and exact match modes based on `SearchListOptions`.
+- **Efficient Testing** — uses high-performance regular expression testing to identify matches in the data.
+
+## Initialization
+
+To initialize the object, call the `SearchListMatcher(item, options)` constructor.
+
+**Parameters:**
+- `item: SearchListItem` — the search item state containing the value.
+- `options: SearchListOptions` — configuration options (e.g., `findExactMatch`).
+
+```typescript
+import { SearchListMatcher, SearchListItem, SearchListOptions } from '@dxtmisha/functional-basic'
+
+const options = new SearchListOptions({ findExactMatch: false })
+const item = new SearchListItem('admin', options)
+const matcher = new SearchListMatcher(item, options)
+
+console.log(matcher.isSelection('System Administrator')) // true
+```
+
+## Methods
+
+### Information
+
+- `is(): boolean` — Checks if the inner regular expression matcher is initialized.
+- `isSelection(value: string): boolean` — Checks if the given value matches the current search expression.
+- `get(): RegExp | undefined` — Returns the current regular expression instance.
+
+### Control
+
+- `update(): void` — Re-initializes the matcher based on the current state of the search item and options.
+
+## Search Modes
+
+The class supports two main matching modes, controlled by the `findExactMatch` option in `SearchListOptions`:
+
+### 1. Contains All Words (Default)
+When `findExactMatch` is `false`, the search string is split into individual words. A match is found only if **every word** is present in the target string, regardless of their order.
+- **Example**: Search for `"gaming mouse"` will match `"Mouse for Gaming"` and `"Gaming Pro Mouse"`.
+
+### 2. Exact Phrase
+When `findExactMatch` is `true`, the search string is treated as a single continuous phrase. A match is found only if the **exact sequence** of characters (case-insensitive) exists in the target string.
+- **Example**: Search for `"gaming mouse"` will match `"Cool gaming mouse"`, but will **not** match `"Mouse for gaming"`.

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

@@ -0,0 +1,55 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/SearchListMatcher - Логика Сопоставления Поиска'/>
+
+# Класс SearchListMatcher
+
+Класс `SearchListMatcher` отвечает за основную логику сопоставления. Он преобразует текущую строку поиска в регулярное выражение и предоставляет методы для проверки соответствия различных значений данных этому выражению.
+
+## Ключевые особенности
+
+- **Динамическая генерация RegExp** — автоматически создает или сбрасывает сопоставитель при изменении поискового запроса или опций.
+- **Режимы поиска** — поддерживает как стандартный частичный поиск, так и режим точного совпадения на основе `SearchListOptions`.
+- **Эффективная проверка** — использует высокопроизводительные методы регулярных выражений для поиска совпадений в данных.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `SearchListMatcher(item, options)`.
+
+**Параметры:**
+- `item: SearchListItem` — состояние элемента поиска, содержащее значение.
+- `options: SearchListOptions` — параметры конфигурации (например, `findExactMatch`).
+
+```typescript
+import { SearchListMatcher, SearchListItem, SearchListOptions } from '@dxtmisha/functional-basic'
+
+const options = new SearchListOptions({ findExactMatch: false })
+const item = new SearchListItem('admin', options)
+const matcher = new SearchListMatcher(item, options)
+
+console.log(matcher.isSelection('System Administrator')) // true
+```
+
+## Методы
+
+### Информационные
+
+- `is(): boolean` — Проверяет, инициализировано ли внутреннее регулярное выражение.
+- `isSelection(value: string): boolean` — Проверяет, соответствует ли данное значение текущему поисковому выражению.
+- `get(): RegExp | undefined` — Возвращает текущий экземпляр регулярного выражения.
+
+### Управление
+
+- `update(): void` — Переинициализирует сопоставитель на основе текущего состояния элемента поиска и опций.
+
+## Режимы поиска
+
+Класс поддерживает два основных режима сопоставления, которые управляются опцией `findExactMatch` в `SearchListOptions`:
+
+### 1. Содержит все слова (По умолчанию)
+Когда `findExactMatch` установлено в `false`, строка поиска разбивается на отдельные слова. Совпадение считается найденным только если **каждое слово** присутствует в целевой строке, независимо от их порядка.
+- **Пример**: Поиск `"игровая мышь"` найдет и `"Мышь игровая"`, и `"Игровая профессиональная мышь"`.
+
+### 2. Точная фраза
+Когда `findExactMatch` установлено в `true`, строка поиска рассматривается как единая непрерывная фраза. Совпадение считается найденным только если **точная последовательность** символов (без учета регистра) присутствует в целевой строке.
+- **Пример**: Поиск `"игровая мышь"` найдет `"Классная игровая мышь"`, но **не найдет** `"Мышь для игровой приставки"`.

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

@@ -0,0 +1,59 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/SearchListMatcher - Logic So khớp Tìm kiếm'/>
+
+# Lớp SearchListMatcher
+
+Lớp `SearchListMatcher` chịu trách nhiệm về logic so khớp cốt lõi. Nó chuyển đổi chuỗi tìm kiếm hiện tại thành một biểu thức chính quy (regular expression) và cung cấp các phương thức để kiểm tra xem các giá trị dữ liệu khác nhau có khớp với biểu thức đó hay không.
+
+## Tính năng chính
+
+- **Tạo RegExp động** — tự động xây dựng hoặc thiết lập lại trình so khớp khi cụm từ tìm kiếm hoặc tùy chọn thay đổi.
+- **Chế độ tìm kiếm** — hỗ trợ cả chế độ khớp một phần tiêu chuẩn và khớp chính xác dựa trên `SearchListOptions`.
+- **Kiểm tra hiệu quả** — sử dụng kiểm tra biểu thức chính quy hiệu suất cao để xác định các kết quả khớp trong dữ liệu.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `SearchListMatcher(item, options)`.
+
+**Tham số:**
+- `item: SearchListItem` — trạng thái thành phần tìm kiếm chứa giá trị.
+- `options: SearchListOptions` — các tùy chọn cấu hình (ví dụ: `findExactMatch`).
+
+```typescript
+import { SearchListMatcher, SearchListItem, SearchListOptions } from '@dxtmisha/functional-basic'
+
+const options = new SearchListOptions({ findExactMatch: false })
+const item = new SearchListItem('admin', options)
+const matcher = new SearchListMatcher(item, options)
+
+console.log(matcher.isSelection('System Administrator')) // true
+```
+
+## Phương thức
+
+### Thông tin
+
+- `is(): boolean` — Kiểm tra xem trình so khớp biểu thức chính quy nội bộ đã được khởi tạo hay chưa.
+- `isSelection(value: string): boolean` — Kiểm tra xem giá trị đã cho có khớp với biểu thức tìm kiếm hiện tại hay không.
+- `get(): RegExp | undefined` — Trả về thực thể biểu thức chính quy hiện tại.
+
+### Điều khiển
+
+- `update(): void` — Khởi tạo lại trình so khớp dựa trên trạng thái hiện tại của thành phần tìm kiếm và các tùy chọn.
+
+## Chế độ tìm kiếm
+
+Lớp hỗ trợ hai chế độ so khớp chính, được điều khiển bởi tùy chọn `findExactMatch` trong `SearchListOptions`:
+
+### 1. Chứa tất cả các từ (Mặc định)
+Когда `findExactMatch` là `false`, chuỗi tìm kiếm được chia thành các từ riêng lẻ. Kết quả khớp chỉ được tìm thấy nếu **mọi từ** đều có mặt trong chuỗi đích, bất kể thứ tự của chúng.
+- **Ví dụ**: Tìm kiếm `"chuột chơi game"` sẽ khớp với `"Chuột dành cho chơi game"` và `"Chơi game Pro Chuột"`.
+
+### 2. Cụm từ chính xác
+Когда `findExactMatch` là `true`, chuỗi tìm kiếm được xử lý như một cụm từ liên tục duy nhất. Kết quả khớp chỉ được tìm thấy nếu **chính xác trình tự** các ký tự (không phân biệt hoa thường) tồn tại trong chuỗi đích.
+- **Ví dụ**: Tìm kiếm `"chuột chơi game"` sẽ khớp với `"Chuột chơi game cực ngầu"`, nhưng sẽ **không** khớp với `"Chuột dành cho chơi game"`.
+
+## Các kiểu dữ liệu (Types)
+
+Lớp này chủ yếu sử dụng kiểu gốc `RegExp` và logic nội bộ được quản lý bởi `SearchListOptions`.

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

@@ -0,0 +1,59 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/SearchListOptions - Search List Options Management'/>
+
+# SearchListOptions Class
+
+The `SearchListOptions` class is responsible for managing and providing access to the configuration options used by the `SearchList` system. It ensures that default values are used when specific options are not provided.
+
+## Key Features
+
+- **Centralized Configuration** — provides a single point of access for all search-related settings.
+- **Default Value Handling** — automatically applies sensible defaults (e.g., limit, delay) if they are missing in the provided options.
+- **Fluent Interface** — supports method chaining for setting new options.
+
+## Initialization
+
+To initialize the object, call the `SearchListOptions(options)` constructor.
+
+**Parameters:**
+- `options?: SearchOptions` — an object containing search configuration.
+
+```typescript
+import { SearchListOptions } from '@dxtmisha/functional-basic'
+
+const options = new SearchListOptions({
+  limit: 3,
+  delay: 300,
+  findExactMatch: true
+})
+
+console.log(options.getLimit()) // 3
+```
+
+## Methods
+
+### Information
+
+- `getOptions(): SearchOptions` — Returns the current search options object.
+- `getLimit(): number` — Returns the minimum number of characters required to trigger a search (default is `2`).
+- `getReturnEverything(): boolean` — Returns whether to return all items even if they don't match the search query (default is `false`).
+- `getDelay(): number` — Returns the search delay in milliseconds (default is `0`).
+- `getFindExactMatch(): boolean` — Returns whether to perform an exact match search (default is `false`).
+- `getClassName(): string` — Returns the CSS class name used for highlighting matches (default is `'sys-search-selection'`).
+
+### Configuration (Setters)
+
+- `setOptions(options: SearchOptions): this` — Sets new search options and returns the current instance for chaining.
+
+## Types
+
+### SearchOptions
+
+Main configuration object for the search system. All fields are optional:
+
+- `limit?: number` — minimum character length to trigger search. Default: `2`.
+- `returnEverything?: boolean` — if `true`, returns all items regardless of match. Default: `false`.
+- `delay?: number` — search execution delay in milliseconds. Default: `0`.
+- `findExactMatch?: boolean` — enables strict word matching. Default: `false`.
+- `classSearchName?: string` — CSS class for highlighting matches. Default: `'sys-search-selection'`.

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

@@ -0,0 +1,59 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/SearchListOptions - Управление Опциями Списка Поиска'/>
+
+# Класс SearchListOptions
+
+Класс `SearchListOptions` отвечает за управление и предоставление доступа к параметрам конфигурации, используемым в системе `SearchList`. Он гарантирует использование значений по умолчанию, когда конкретные параметры не указаны.
+
+## Ключевые особенности
+
+- **Централизованная конфигурация** — предоставляет единую точку доступа ко всем настройкам, связанным с поиском.
+- **Обработка значений по умолчанию** — автоматически применяет разумные параметры (например, лимит, задержку), если они отсутствуют в предоставленных опциях.
+- **Fluent Interface** — поддерживает цепочку вызовов для установки новых опций.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `SearchListOptions(options)`.
+
+**Параметры:**
+- `options?: SearchOptions` — объект, содержащий конфигурацию поиска.
+
+```typescript
+import { SearchListOptions } from '@dxtmisha/functional-basic'
+
+const options = new SearchListOptions({
+  limit: 3,
+  delay: 300,
+  findExactMatch: true
+})
+
+console.log(options.getLimit()) // 3
+```
+
+## Методы
+
+### Информационные
+
+- `getOptions(): SearchOptions` — Возвращает текущий объект настроек поиска.
+- `getLimit(): number` — Возвращает минимальное количество символов, необходимое для запуска поиска (по умолчанию `2`).
+- `getReturnEverything(): boolean` — Возвращает, следует ли возвращать все элементы, даже если они не соответствуют поисковому запросу (по умолчанию `false`).
+- `getDelay(): number` — Возвращает задержку поиска в миллисекундах (по умолчанию `0`).
+- `getFindExactMatch(): boolean` — Возвращает, следует ли выполнять поиск с точным совпадением (по умолчанию `false`).
+- `getClassName(): string` — Возвращает имя CSS-класса, используемое для выделения совпадений (по умолчанию `'sys-search-selection'`).
+
+### Настройка (Сеттеры)
+
+- `setOptions(options: SearchOptions): this` — Устанавливает новые опции поиска и возвращает текущий экземпляр для цепочки вызовов.
+
+## Типы
+
+### SearchOptions
+
+Основной объект конфигурации для системы поиска. Все поля необязательны:
+
+- `limit?: number` — минимальное количество символов для запуска поиска. По умолчанию: `2`.
+- `returnEverything?: boolean` — если `true`, возвращает все элементы независимо от совпадения. По умолчанию: `false`.
+- `delay?: number` — задержка перед выполнением поиска в миллисекундах. По умолчанию: `0`.
+- `findExactMatch?: boolean` — включает режим точного совпадения слов. По умолчанию: `false`.
+- `classSearchName?: string` — CSS класс для выделения совпадений. По умолчанию: `'sys-search-selection'`.

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

@@ -0,0 +1,59 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/SearchListOptions - Quản lý Tùy chọn Danh sách Tìm kiếm'/>
+
+# Lớp SearchListOptions
+
+Lớp `SearchListOptions` chịu trách nhiệm quản lý và cung cấp quyền truy cập vào các tùy chọn cấu hình được sử dụng bởi hệ thống `SearchList`. Nó đảm bảo rằng các giá trị mặc định được sử dụng khi các tùy chọn cụ thể không được cung cấp.
+
+## Tính năng chính
+
+- **Cấu hình tập trung** — cung cấp một điểm truy cập duy nhất cho tất cả các cài đặt liên quan đến tìm kiếm.
+- **Xử lý giá trị mặc định** — tự động áp dụng các giá trị mặc định hợp lý (ví dụ: giới hạn, độ trễ) nếu chúng thiếu trong các tùy chọn được cung cấp.
+- **Giao diện Fluent** — hỗ trợ chuỗi lệnh (method chaining) để thiết lập các tùy chọn mới.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `SearchListOptions(options)`.
+
+**Tham số:**
+- `options?: SearchOptions` — một đối tượng chứa cấu hình tìm kiếm.
+
+```typescript
+import { SearchListOptions } from '@dxtmisha/functional-basic'
+
+const options = new SearchListOptions({
+  limit: 3,
+  delay: 300,
+  findExactMatch: true
+})
+
+console.log(options.getLimit()) // 3
+```
+
+## Phương thức
+
+### Thông tin
+
+- `getOptions(): SearchOptions` — Trả về đối tượng tùy chọn tìm kiếm hiện tại.
+- `getLimit(): number` — Trả về số lượng ký tự tối thiểu cần thiết để kích hoạt tìm kiếm (mặc định là `2`).
+- `getReturnEverything(): boolean` — Trả về liệu có trả về tất cả các mục ngay cả khi chúng không khớp với truy vấn tìm kiếm hay không (mặc định là `false`).
+- `getDelay(): number` — Trả về độ trễ tìm kiếm tính bằng mili giây (mặc định là `0`).
+- `getFindExactMatch(): boolean` — Trả về liệu có thực hiện tìm kiếm khớp chính xác hay không (mặc định là `false`).
+- `getClassName(): string` — Trả về tên lớp CSS được sử dụng để làm nổi bật các kết quả khớp (mặc định là `'sys-search-selection'`).
+
+### Cấu hình (Setters)
+
+- `setOptions(options: SearchOptions): this` — Thiết lập các tùy chọn tìm kiếm mới và trả về thực thể hiện tại để tạo chuỗi lệnh.
+
+## Các kiểu dữ liệu (Types)
+
+### SearchOptions
+
+Đối tượng cấu hình chính cho hệ thống tìm kiếm. Tất cả các trường là tùy chọn:
+
+- `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 bất kể có khớp hay không. Mặc định: `false`.
+- `delay?: number` — độ trễ thực hiện tìm kiếm tính bằng mili giây. Mặc định: `0`.
+- `findExactMatch?: boolean` — cho phép khớp từ chính xác. Mặc định: `false`.
+- `classSearchName?: string` — tên lớp CSS để làm nổi bật các kết quả khớp. Mặc định: `'sys-search-selection'`.

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

@@ -0,0 +1,115 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/Translate - Translation and Text Management'/>
+
+# Translate Class
+
+A static wrapper for a default instance of the `TranslateInstance` class. It manages translations and localized text at a global level, providing tools for retrieving, caching, and displaying content with template support and automatic locale detection.
+
+## Relationship with TranslateInstance
+
+The `Translate` class acts as a global, pre-configured interface for `TranslateInstance`. All static methods call the corresponding methods on an internal instance (`Translate.getItem()`).
+
+While `Translate` is suitable for most application-wide translation needs, you can create independent translation environments using `TranslateInstance`.
+
+## Key Features
+
+- **Batch Loading** — Intelligently groups translation requests, sending them as a single pack 160ms after being queued.
+- **Flexible Templates** — Supports parameter replacement in text using both indices (`[0]`) and named keys (`{key}`).
+- **Sync and Async Access** — Methods for instant text retrieval from cache (`getSync`) or guaranteed server loading (`get`).
+- **Smart Cache** — Stores translations scoped to the current locale and supports fallbacks (Location > Language > Global).
+
+## Initialization
+
+The class is static and does not require instantiation. Configuration applies to the global translation instance.
+
+```javascript
+import { Translate } from '@dxtmisha/functional-basic'
+
+// Configure API URL for the global instance
+Translate.setUrl('/api/v1/translate')
+
+// Preload necessary texts
+await Translate.add(['welcome', 'auth.login'])
+```
+
+## Methods
+
+### Configuration
+
+- `setConfig(config: TranslateConfig): Translate` — Sets the complete configuration for the translation instance.
+- `setUrl(url: string): Translate` — Changes the API endpoint for fetching translations.
+- `setPropsName(name: string): Translate` — Changes the property name used in the API request/response.
+- `setReadApi(value: boolean): Translate` — Enables or disables fetching translations from the API.
+
+### Translation Retrieval
+
+- `async get(name: string, replacement?: any): Promise<string>` — Asynchronously retrieves text. If not in cache and not on localhost, it attempts to load it from the server.
+- `getSync(name: string, first?: boolean, replacement?: any): string` — Returns text from the cache. If `first` is `true`, returns a space ` ` if the text is missing.
+- `async getList<T>(names: T): Promise<TranslateList<T>>` — Retrieves a group of translations (asynchronous).
+- `getListSync<T>(names: T, first?: boolean): TranslateList<T>` — Retrieves a group of translations from the cache (synchronous).
+
+### Batch Update
+
+- `async add(names: string | string[]): Promise<void>` — Adds multiple codes to the queue for batch loading.
+- `addSync(data: Record<string, string>): void` — Directly adds translations to the cache.
+- `async addNormalOrSync(data: Record<string, string>): Promise<void>` — Adds translations directly on localhost, otherwise queues them for loading.
+- `addSyncByLocation(data: Record<string, Record<string, string>>): void` — Adds translations for specific locations/locales.
+- `addSyncByFile(data: TranslateDataFile): void` — Adds translations from a file definition.
+
+### Static vs Instance
+
+- **Usage**: Use `Translate` for global access anywhere in the app. Use `TranslateInstance` for localized, independent instances.
+- **State**: `Translate` state is shared across the entire application. `TranslateInstance` provides isolated state for specific components or modules.
+- **Creation**: `Translate` does not require instantiation (static wrapper). `TranslateInstance` is created via `new TranslateInstance()`.
+
+## Standalone Instances
+
+If you need to manage a separate set of translations (e.g., for a specific sub-application or a specialized widget), use `TranslateInstance` instead of the global `Translate` class.
+
+```javascript
+import { TranslateInstance, TranslateFile } from '@dxtmisha/functional-basic'
+
+// 1. Create a specialized set of translation files
+const widgetFiles = new TranslateFile({
+  'en-US': () => import('./locales/widget.en-US.json')
+})
+
+// 2. Initialize a standalone translation instance
+const widgetTranslate = new TranslateInstance(
+  '/api/widget/translate', 
+  'list', 
+  widgetFiles
+)
+
+// 3. Use independently
+const label = await widgetTranslate.get('widget.welcome')
+```
+
+## Types
+
+### `TranslateCode`
+A string (code name) or an array of strings. Arrays are used for template replacement:
+- `string` — e.g., `'welcome'`
+- `string[]` — e.g., `['welcome', 'Guest']`
+
+### `TranslateList`
+A record where keys are translation codes and values are the resulting translated strings.
+
+## Examples
+
+### Working with Templates
+```javascript
+// In database: "Hello, [0]! You have {count} notifications."
+const text = await Translate.get('user.notifications', ['John', { count: 5 }])
+// Result: "Hello, John! You have 5 notifications."
+```
+
+### Batch List Retrieval
+```javascript
+const labels = await Translate.getList([
+  'home.title',
+  ['home.welcome', 'Guest'], 
+  'home.footer'
+])
+```