@dxtmisha/wiki 0.39.7 → 0.56.0

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

@@ -0,0 +1,97 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/StorageCallback - Storage Callbacks'/>
+
+# Lớp StorageCallback
+
+Một lớp tiện ích để quản lý các nhóm hàm callback liên kết với các khóa lưu trữ cụ thể. Nó cho phép nhiều thành phần hoặc chức năng phản hồi các thay đổi hoặc kích hoạt lưu trữ một cách phối hợp, bất đồng bộ.
+
+## Các đặc điểm chính
+
+- **Các thực thể có tên** — thực hiện mô hình singleton, trong đó các thực thể được truy xuất theo tên và nhóm, đảm bảo rằng các phần khác nhau của ứng dụng chia sẻ cùng một danh sách callback cho cùng một tài nguyên.
+- **Phân tách theo nhóm** — cho phép tách biệt các danh sách callback theo nhóm (ví dụ: 'main', 'global', 'local'), ngăn chặn xung đột tên giữa các mô-đun khác nhau.
+- **Thực thi bất đồng bộ** — hỗ trợ các callback dựa trên `Promise` và thực thi chúng theo trình tự trong quá trình `run`.
+- **Theo dõi trạng thái tải** — cung cấp cờ `loading` có sẵn, được quản lý tự động trong giai đoạn thực thi callback.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm tạo `StorageCallback(name, group)` hoặc sử dụng phương thức tĩnh `getInstance(name, group)`.
+
+### Các ràng buộc Generic
+
+Để đảm bảo kiểu dữ liệu nghiêm ngặt, lớp hỗ trợ các generic sau:
+- `T = any` — Kiểu dữ liệu được truyền cho các callback.
+- `Callback = (value: T) => void | Promise<void>` — Cấu trúc hàm callback.
+
+**Tham số:**
+- `name: string` — định danh duy nhất cho mục nhập lưu trữ.
+- `group: string = 'main'` — phân loại tùy chọn để ngăn chặn xung đột tên.
+
+```typescript
+import { StorageCallback } from '@dxtmisha/functional-basic'
+
+// 1. Khởi tạo đơn giản (nhóm mặc định là 'main')
+const storage = new StorageCallback('user-data')
+
+// 2. Sử dụng phương thức tĩnh getInstance
+const sharedStorage = StorageCallback.getInstance('settings', 'global')
+
+// 3. Sử dụng generic để kiểm soát kiểu dữ liệu
+const numberStorage = new StorageCallback<number>('counter')
+numberStorage.addCallback((val) => console.log(val + 1))
+```
+
+## Các phương thức
+
+### Thông tin
+
+- `getName(): string` — trả về tên của thực thể lưu trữ.
+- `isLoading(): boolean` — trả về trạng thái tải hiện tại.
+- `getLoading(): boolean` — trả về trạng thái tải hiện tại (tương tự `isLoading`).
+
+### Quản lý
+
+- `addCallback(callback: Callback, isOnce?: boolean): this` — thêm một callback mới vào danh sách thực thi. Nếu `isOnce: true`, callback sẽ bị xóa sau lần thực thi đầu tiên.
+- `removeCallback(callback: Callback): this` — xóa một callback cụ thể khỏi danh sách.
+
+### Điều khiển (Control)
+
+- `preparation(): this` — chuẩn bị trạng thái trước khi thực thi (đặt `loading` thành `true`). Được sử dụng thủ công khi bắt đầu các hoạt động bất đồng bộ.
+- `run(value: T): Promise<this>` — thực thi tất cả các callback theo trình tự với giá trị được cung cấp. Đặt `loading` về `false` khi bắt đầu thực thi.
+
+## Ví dụ sử dụng
+
+### Quản lý trạng thái tải thủ công
+
+Khi dữ liệu được lấy bất đồng bộ từ nguồn bên ngoài (ví dụ: Figma storage), bạn có thể quản lý trạng thái `loading` thủ công để điều phối nhiều yêu cầu.
+
+```typescript
+const storage = new StorageCallback('figma-data')
+
+// 1. Kiểm tra nếu không phải đang tải
+if (!storage.isLoading()) {
+  // 2. Thiết lập trạng thái đang tải
+  storage.preparation()
+  
+  // 3. Yêu cầu dữ liệu
+  fetchFromFigma((data) => {
+    // 4. Thực thi callback (run sẽ đưa loading về false)
+    storage.run(data)
+  })
+}
+```
+
+### Callback một lần
+
+Nếu bạn chỉ cần một hàm kích hoạt một lần (ví dụ: để nạp dữ liệu ban đầu), hãy sử dụng cờ `isOnce`.
+
+```typescript
+const storage = new StorageCallback('initial-data')
+
+storage.addCallback((data) => {
+  console.log('Đã thực thi một lần:', data)
+}, true)
+
+await storage.run('update 1') // 'Đã thực thi một lần: update 1'
+await storage.run('update 2') // (không có đầu ra, callback đã bị xóa)
+```

package/src/media/functional/functional-basic/functions/addTagHighlightMatch/addTagHighlightMatch.en.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/en/functional-basic/Functions/addTagHighlightMatch - Highlight matches in a string'/>
 
@@ -8,17 +8,20 @@ A utility for highlighting matches in a string by wrapping them in a `<span>` HT
 
 **Parameters:**
 - `value: string` — The initial string to process.
-- `search?: string` — The search string (one or more words separated by spaces).
+- `search?: string | RegExp` — The search string (one or more words separated by spaces) or a regular expression.
 - `className: string = 'sys-highlight-match'` — The CSS class to be added to the `<span>` tag.
+- `shouldEscape: boolean = false` — Whether to escape the string before adding highlighting.
 
 **Returns:**
 `string` — The string with HTML tags added for highlighting.
 
-```typescript
+<Source
+  language='typescript'
+  code={`
 import { addTagHighlightMatch } from '@dxtmisha/functional-basic'
 
 // Highlight a single word
-addTagHighlightMatch('Hello world', 'hello') 
+addTagHighlightMatch('Hello world', 'hello')
 // '<span class="sys-highlight-match">Hello</span> world'
 
 // Highlight multiple words (OR logic)
@@ -28,4 +31,9 @@ addTagHighlightMatch('Apple and Banana', 'apple banana')
 // Custom class
 addTagHighlightMatch('Test', 'test', 'text-red')
 // '<span class="text-red">Test</span>'
-```
+
+// With escaping
+addTagHighlightMatch('<b>bold</b>', 'bold', 'sys-highlight-match', true)
+// '&lt;b&gt;<span class="sys-highlight-match">bold</span>&lt;/b&gt;'
+  `}
+/>

package/src/media/functional/functional-basic/functions/addTagHighlightMatch/addTagHighlightMatch.ru.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/ru/functional-basic/Functions/addTagHighlightMatch - Подсветка совпадений в строке'/>
 
@@ -8,17 +8,20 @@ import { Meta } from '@storybook/addon-docs/blocks'
 
 **Параметры:**
 - `value: string` — Исходная строка для обработки.
-- `search?: string` — Строка поиска (одно или несколько слов через пробел).
+- `search?: string | RegExp` — Строка поиска (одно или несколько слов через пробел) или регулярное выражение.
 - `className: string = 'sys-highlight-match'` — CSS-класс, который будет добавлен к тегу `<span>`.
+- `shouldEscape: boolean = false` — Нужно ли экранировать строку перед добавлением подсветки.
 
 **Возвращает:**
 `string` — Строка с добавленными HTML-тегами для подсветки.
 
-```typescript
+<Source
+  language='typescript'
+  code={`
 import { addTagHighlightMatch } from '@dxtmisha/functional-basic'
 
 // Подсветка одного слова
-addTagHighlightMatch('Hello world', 'hello') 
+addTagHighlightMatch('Hello world', 'hello')
 // '<span class="sys-highlight-match">Hello</span> world'
 
 // Подсветка нескольких слов (OR-логика)
@@ -28,4 +31,9 @@ addTagHighlightMatch('Apple and Banana', 'apple banana')
 // Кастомный класс
 addTagHighlightMatch('Test', 'test', 'text-red')
 // '<span class="text-red">Test</span>'
-```
+
+// С экранированием
+addTagHighlightMatch('<b>bold</b>', 'bold', 'sys-highlight-match', true)
+// '&lt;b&gt;<span class="sys-highlight-match">bold</span>&lt;/b&gt;'
+  `}
+/>

package/src/media/functional/functional-basic/functions/addTagHighlightMatch/addTagHighlightMatch.vi.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/vi/functional-basic/Functions/addTagHighlightMatch - Làm nổi bật các kết quả khớp trong chuỗi'/>
 
@@ -8,17 +8,20 @@ Tiện ích để làm nổi bật các kết quả khớp trong một chuỗi b
 
 **Tham số:**
 - `value: string` — Chuỗi ban đầu để xử lý.
-- `search?: string` — Chuỗi tìm kiếm (một hoặc nhiều từ phân tách bằng dấu cách).
+- `search?: string | RegExp` — Chuỗi tìm kiếm (một hoặc nhiều từ phân tách bằng dấu cách) hoặc biễu thức chính quy.
 - `className: string = 'sys-highlight-match'` — Class CSS sẽ được thêm vào thẻ `<span>`.
+- `shouldEscape: boolean = false` — Có nên thoát chuỗi trước khi thêm làm nổi bật hay không.
 
 **Trả về:**
 `string` — Chuỗi với các thẻ HTML được thêm vào để làm nổi bật.
 
-```typescript
+<Source
+  language='typescript'
+  code={`
 import { addTagHighlightMatch } from '@dxtmisha/functional-basic'
 
 // Làm nổi bật một từ đơn
-addTagHighlightMatch('Hello world', 'hello') 
+addTagHighlightMatch('Hello world', 'hello')
 // '<span class="sys-highlight-match">Hello</span> world'
 
 // Làm nổi bật nhiều từ (logic OR)
@@ -28,4 +31,9 @@ addTagHighlightMatch('Apple and Banana', 'apple banana')
 // Class tùy chỉnh
 addTagHighlightMatch('Test', 'test', 'text-red')
 // '<span class="text-red">Test</span>'
-```
+
+// Với thoát chuỗi (escaping)
+addTagHighlightMatch('<b>bold</b>', 'bold', 'sys-highlight-match', true)
+// '&lt;b&gt;<span class="sys-highlight-match">bold</span>&lt;/b&gt;'
+  `}
+/>

package/src/media/functional/functional-basic/functions/anyToString/anyToString.en.mdx

@@ -1,33 +1,51 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/en/functional-basic/Functions/anyToString - Conversion of a value to a string'/>
 
 # `anyToString`
 
-A utility that safely converts any input data into a string type.
-
-This is useful when outputting data to the interface when the variable type (object, array, boolean, or null) is not known in advance.
+A utility for safely converting any input data into a string type.
 
 **Parameters:**
-- `value: V` — Values for conversion.
-- `isArrayString: boolean` (optional, default: `true`) — If `true`, arrays of primitives will be joined by commas. If `false`, they will be stringified as JSON.
+- `value: V` — The value for conversion.
+- `isArrayString: boolean = true` — If `true`, primitive arrays are joined by commas.
+- `trim: boolean = true` — If `true`, trims leading and trailing whitespace (only for strings).
+
+**Conversion Rules:**
+- **Strings**: Returned as is (with `trim` if enabled).
+- **Arrays**: If `isArrayString: true` and no objects are in the array, elements are joined by commas. Otherwise, JSON stringified.
+- **Objects**: Converted to JSON. In case of error (e.g., circular reference), returns standard `toString()`.
+- **Boolean**: `true` converts to `'1'`, `false` to `'0'`.
+- **Other types**: `null` and `undefined` result in an empty string. Others call `toString()`.
 
 **Returns:**
-`string` — The string representation of the provided value.
+`string` — The string representation of the value.
+
+## Examples
 
-```typescript
+<Source
+  language='typescript'
+  code={`
 import { anyToString } from '@dxtmisha/functional-basic'
 
-console.log(anyToString(' test ')) // 'test' (trimmed)
-console.log(anyToString([1, 2, 3])) // '1,2,3' (isArrayString = true)
-console.log(anyToString([1, 2, 3], false)) // '[1,2,3]' (isArrayString = false)
+// 1. Strings
+anyToString('  Hello  ')               // 'Hello'
+anyToString('  Hello  ', true, false)  // '  Hello  '
+
+// 2. Arrays
+anyToString([1, 2, 3])                 // '1,2,3'
+anyToString([1, 2, 3], false)          // '[1,2,3]'
+
+// 3. Objects
+anyToString({ a: 1 })                  // '{"a":1}'
 
-console.log(anyToString([[1], [2]])) // '[[1],[2]]' (nested arrays are stringified as JSON)
-console.log(anyToString([{ a: 1 }, 2])) // '[{"a":1},2]' (arrays with objects are stringified as JSON)
+// 4. Boolean values (1/0 conversion)
+anyToString(true)                      // '1'
+anyToString(false)                     // '0'
 
-console.log(anyToString({ a: 1 })) // '{"a":1}'
-console.log(anyToString(true)) // '1'
-console.log(anyToString(false)) // '0'
-console.log(anyToString(123)) // '123'
-console.log(anyToString(null)) // ''
-```
+// 5. Empty values and types
+anyToString(null)                      // ''
+anyToString(123)                       // '123'
+anyToString(Symbol('test'))            // 'Symbol(test)'
+  `}
+/>

package/src/media/functional/functional-basic/functions/anyToString/anyToString.ru.mdx

@@ -1,33 +1,51 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/ru/functional-basic/Functions/anyToString - Преобразование значения в строку'/>
 
 # `anyToString`
 
-Утилита, которая безопасно приводит любые входящие данные к строковому типу.
-
-Это полезно при выводе данных в интерфейс, когда заранее неизвестен тип переменной (объект, массив, boolean или null).
+Утилита для безопасного приведения любых данных к строковому типу.
 
 **Параметры:**
-- `value: V` — Значения для преобразования.
-- `isArrayString: boolean` (необязательно, по умолчанию: `true`) — Если `true`, массивы примитивов будут объединены через запятую. Если `false`, они будут преобразованы в строку JSON.
+- `value: V` — Значение для преобразования.
+- `isArrayString: boolean = true` — Если `true`, массивы примитивов объединяются через запятую.
+- `trim: boolean = true` — Если `true`, обрезает лишние пробелы (только для строк).
+
+**Правила преобразования:**
+- **Строки**: Возвращаются как есть (с `trim`, если включено).
+- **Массивы**: Если `isArrayString: true` и в массиве нет объектов, элементы объединяются через запятую. В остальных случаях — JSON.
+- **Объекты**: Преобразуются в JSON. При ошибке (например, циклической ссылке) возвращается стандартный `toString()`.
+- **Boolean**: `true` преобразуется в `'1'`, `false` — в `'0'`.
+- **Прочие типы**: `null` и `undefined` дают пустую строку. Для остальных вызывается `toString()`.
 
 **Возвращает:**
-`string` — Строковое представление переданного значения.
+`string` — Строковое представление значения.
+
+## Примеры
 
-```typescript
+<Source
+  language='typescript'
+  code={`
 import { anyToString } from '@dxtmisha/functional-basic'
 
-console.log(anyToString(' test ')) // 'test' (trimmed)
-console.log(anyToString([1, 2, 3])) // '1,2,3' (isArrayString = true)
-console.log(anyToString([1, 2, 3], false)) // '[1,2,3]' (isArrayString = false)
+// 1. Строки
+anyToString('  Hello  ')               // 'Hello'
+anyToString('  Hello  ', true, false)  // '  Hello  '
+
+// 2. Массивы
+anyToString([1, 2, 3])                 // '1,2,3'
+anyToString([1, 2, 3], false)          // '[1,2,3]'
+
+// 3. Объекты
+anyToString({ a: 1 })                  // '{"a":1}'
 
-console.log(anyToString([[1], [2]])) // '[[1],[2]]' (вложенные массивы превращаются в JSON)
-console.log(anyToString([{ a: 1 }, 2])) // '[{"a":1},2]' (массивы с объектами превращаются в JSON)
+// 4. Логические значения (преобразование в 1/0)
+anyToString(true)                      // '1'
+anyToString(false)                     // '0'
 
-console.log(anyToString({ a: 1 })) // '{"a":1}'
-console.log(anyToString(true)) // '1'
-console.log(anyToString(false)) // '0'
-console.log(anyToString(123)) // '123'
-console.log(anyToString(null)) // ''
-```
+// 5. Пустые значения и типы
+anyToString(null)                      // ''
+anyToString(123)                       // '123'
+anyToString(Symbol('test'))            // 'Symbol(test)'
+  `}
+/>

package/src/media/functional/functional-basic/functions/anyToString/anyToString.vi.mdx

@@ -1,33 +1,51 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/vi/functional-basic/Functions/anyToString - Chuyển đổi một giá trị thành chuỗi'/>
 
 # `anyToString`
 
-Một tiện ích chuyển đổi an toàn bất kỳ dữ liệu đầu vào nào thành kiểu chuỗi.
-
-Điều này rất hữu ích khi xuất dữ liệu ra giao diện mà không biết trước kiểu của biến (đối tượng, mảng, boolean hoặc null).
+Tiện ích để chuyển đổi an toàn bất kỳ dữ liệu đầu vào nào thành kiểu chuỗi.
 
 **Tham số:**
 - `value: V` — Giá trị cần chuyển đổi.
-- `isArrayString: boolean` (tùy chọn, mặc định: `true`) — Nếu `true`, các mảng nguyên thủy sẽ được nối với nhau bằng dấu phẩy. Nếu `false`, chúng sẽ được chuyển đổi thành chuỗi JSON.
+- `isArrayString: boolean = true` — Nếu `true`, các mảng nguyên thủy sẽ được nối với nhau bằng dấu phẩy.
+- `trim: boolean = true` — Nếu `true`, loại bỏ khoảng trắng dư thừa (chỉ dành cho chuỗi).
+
+**Quy tắc chuyển đổi:**
+- **Chuỗi**: Trả về nguyên bản (có `trim` nếu được bật).
+- **Mảng**: Nếu `isArrayString: true` và không có đối tượng trong mảng, các phần tử sẽ được nối bằng dấu phẩy. Ngược lại — chuyển thành chuỗi JSON.
+- **Đối tượng**: Chuyển đổi thành JSON. Trong trường hợp lỗi (ví dụ: tham chiếu vòng), trả về `toString()` tiêu chuẩn.
+- **Boolean**: `true` chuyển thành `'1'`, `false` thành `'0'`.
+- **Các kiểu khác**: `null` và `undefined` trả về chuỗi rỗng. Các kiểu khác gọi `toString()`.
 
 **Trả về:**
 `string` — Biểu diễn chuỗi của giá trị.
 
-```typescript
+## Ví dụ
+
+<Source
+  language='typescript'
+  code={`
 import { anyToString } from '@dxtmisha/functional-basic'
 
-console.log(anyToString(' test ')) // 'test' (đã trimmed)
-console.log(anyToString([1, 2, 3])) // '1,2,3' (isArrayString = true)
-console.log(anyToString([1, 2, 3], false)) // '[1,2,3]' (isArrayString = false)
+// 1. Chuỗi (Strings)
+anyToString('  Hello  ')               // 'Hello'
+anyToString('  Hello  ', true, false)  // '  Hello  '
+
+// 2. Mảng (Arrays)
+anyToString([1, 2, 3])                 // '1,2,3'
+anyToString([1, 2, 3], false)          // '[1,2,3]'
+
+// 3. Đối tượng (Objects)
+anyToString({ a: 1 })                  // '{"a":1}'
 
-console.log(anyToString([[1], [2]])) // '[[1],[2]]' (các mảng lồng nhau sẽ được chuyển thành JSON)
-console.log(anyToString([{ a: 1 }, 2])) // '[{"a":1},2]' (các mảng chứa đối tượng sẽ được chuyển thành JSON)
+// 4. Giá trị Boolean (chuyển đổi thành 1/0)
+anyToString(true)                      // '1'
+anyToString(false)                     // '0'
 
-console.log(anyToString({ a: 1 })) // '{"a":1}'
-console.log(anyToString(true)) // '1'
-console.log(anyToString(false)) // '0'
-console.log(anyToString(123)) // '123'
-console.log(anyToString(null)) // ''
-```
+// 5. Giá trị rỗng và các kiểu khác
+anyToString(null)                      // ''
+anyToString(123)                       // '123'
+anyToString(Symbol('test'))            // 'Symbol(test)'
+  `}
+/>

package/src/media/functional/functional-basic/functions/applyTemplate/applyTemplate.en.mdx

@@ -1,35 +1,47 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/en/functional-basic/Functions/applyTemplate - Applying a template to text'/>
 
 # `applyTemplate`
 
-A utility for dynamic text generation based on templates. This is useful for localization (i18n) tasks, generating system messages, or inserting user data into string constants.
-
-It supports:
-- Positional markers (`%d`, `%e`, etc.) to substitute values from an array in order.
-- Named markers (`[key]`, `{key}`) to substitute values from an object by keys.
-- Paired tags (`[key]content[/key]`, `{key}content{/key}`) to wrap content in HTML tags or other constructs (the word `[content]` inside the passed value is replaced by the tag's generic content).
+A utility for replacing markers in text with values from an object or an array.
 
 **Parameters:**
 - `text: string` — The original text containing template markers.
-- `replacement: Record<string, string | number> | string[]` — An object or array containing values for substitution. Defaults to `{}`.
+- `replacement: Record<string, string | number | boolean> | string[]` — An object or array containing values.
+
+**Replacement formats (replacement)**
+- **Array**: Used for positional markers like `%d`, `%e`, `%f`, and so on (alphabetically).
+- **Object**: Used for named markers in brackets `[key]` or `{key}`, as well as paired tags `[tag]text[/tag]`.
 
 **Returns:**
 `string` — The text with substituted values.
 
-```typescript
+## Examples
+
+<Source
+  language='typescript'
+  code={`
 import { applyTemplate } from '@dxtmisha/functional-basic'
 
-// Positional markers
-console.log(applyTemplate('Hello, %d %e!', ['John', 'Doe'])) // 'Hello, John Doe!'
+// 1. Positional markers (array)
+applyTemplate('Hello, %d %e!', ['John', 'Doe']) // 'Hello, John Doe!'
+
+// 2. Named markers (object)
+applyTemplate('Price: [price] {currency}', { price: 100, currency: 'USD' }) // 'Price: 100 USD'
+
+// 3. Handling 0 and false
+applyTemplate('Value: [val]', { val: 0 })      // 'Value: 0'
+applyTemplate('Status: [val]', { val: false })    // 'Status: false'
+
+// 4. Skipping missing keys
+applyTemplate('Missing: [none]', {})           // 'Missing: [none]'
 
-// Named markers
-console.log(applyTemplate('Hello, [name]!', { name: 'John' })) // 'Hello, John!'
-console.log(applyTemplate('Hello, {name}!', { name: 'John' })) // 'Hello, John!'
+// 5. Paired tags with content substitution
+const tags = { link: '<a href="https://google.com">[content]</a>' }
+applyTemplate('Click [link]here[/link]', tags)  // 'Click <a href="https://google.com">here</a>'
 
-// Wrapped tags with content substitution
-console.log(applyTemplate('Click [link]here[/link]', { link: '<a href="#">[content]</a>' }))
-console.log(applyTemplate('Click {link}here{/link}', { link: '<a href="#">{content}</a>' }))
-// 'Click <a href="#">here</a>'
-```
+// 6. List macros (handling out-of-bounds)
+applyTemplate('Macros: %d, %e, %f', ['A', 'B'])  // 'Macros: A, B, '
+  `}
+/>

package/src/media/functional/functional-basic/functions/applyTemplate/applyTemplate.ru.mdx

@@ -1,35 +1,47 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/ru/functional-basic/Functions/applyTemplate - Применение шаблона к тексту'/>
 
 # `applyTemplate`
 
-Утилита для динамического формирования текста на основе шаблонов. Это полезно для задач локализации (i18n), генерации системных сообщений или подстановки пользовательских данных в строковые константы.
-
-Она поддерживает:
-- Позиционные маркеры (`%d`, `%e` и т.д.) для подстановки значений из массива по порядку.
-- Именованные маркеры (`[key]`, `{key}`) для подстановки значений из объекта по ключам.
-- Парные теги (`[key]контент[/key]`, `{key}контент{/key}`) для оборачивания контента в HTML-теги или другие конструкции (слово `[content]` внутри переданного значения заменяется на содержимое тега).
+Утилита для замены меток в тексте на значения из объекта или массива.
 
 **Параметры:**
 - `text: string` — Исходный текст с шаблоном.
-- `replacement: Record<string, string | number> | string[]` — Объект или массив со значениями для подстановки. По умолчанию `{}`.
+- `replacement: Record<string, string | number | boolean> | string[]` — Объект или массив со значениями.
+
+**Форматы замены (replacement)**
+- **Массив**: Используется для позиционных меток `%d`, `%e`, `%f` и далее по алфавиту.
+- **Объект**: Используется для именованных меток в скобках `[key]` или `{key}`, а также для парных тегов `[tag]текст[/tag]`.
 
 **Возвращает:**
 `string` — Текст с подставленными значениями.
 
-```typescript
+## Примеры
+
+<Source
+  language='typescript'
+  code={`
 import { applyTemplate } from '@dxtmisha/functional-basic'
 
-// Позиционные маркеры
-console.log(applyTemplate('Привет, %d %e!', ['Иван', 'Иванов'])) // 'Привет, Иван Иванов!'
+// 1. Позиционные маркеры (массив)
+applyTemplate('Привет, %d %e!', ['Иван', 'Иванов']) // 'Привет, Иван Иванов!'
+
+// 2. Именованные маркеры (объект)
+applyTemplate('Цена: [price] {currency}', { price: 100, currency: 'USD' }) // 'Цена: 100 USD'
+
+// 3. Обработка 0 и false
+applyTemplate('Значение: [val]', { val: 0 })      // 'Значение: 0'
+applyTemplate('Статус: [val]', { val: false })    // 'Статус: false'
+
+// 4. Пропуск отсутствующих ключей
+applyTemplate('Отсутствует: [none]', {})           // 'Отсутствует: [none]'
 
-// Именованные маркеры
-console.log(applyTemplate('Привет, [name]!', { name: 'Иван' })) // 'Привет, Иван!'
-console.log(applyTemplate('Привет, {name}!', { name: 'Иван' })) // 'Привет, Иван!'
+// 5. Парные теги с подстановкой контента
+const tags = { link: '<a href="https://google.com">[content]</a>' }
+applyTemplate('Нажми [link]здесь[/link]', tags)  // 'Нажми <a href="https://google.com">здесь</a>'
 
-// Обёртка с парными тегами и контентом
-console.log(applyTemplate('Нажми [link]здесь[/link]', { link: '<a href="#">[content]</a>' }))
-console.log(applyTemplate('Нажми {link}здесь{/link}', { link: '<a href="#">{content}</a>' }))
-// 'Нажми <a href="#">здесь</a>'
-```
+// 6. Макросы списка (выход за границы)
+applyTemplate('Список: %d, %e, %f', ['A', 'B'])  // 'Список: A, B, '
+  `}
+/>