@dxtmisha/wiki 0.39.1 → 0.39.3

package/src/media/functional/functional/ref/ref.ru.mdx

@@ -0,0 +1,57 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/# Реактивные классы (Ref)'/>
+
+# Реактивные классы (Ref)
+
+Реактивные версии базовых классов созданы для бесшовной интеграции с **Vue 3 (Composition API)**.
+
+## Особенности
+
+Основная идея заключается в том, что класс сам следит за изменениями входных данных и предоставляет готовые `ComputedRef` для использования в шаблонах. Это избавляет от необходимости вручную пересчитывать значения при смене локали или входных переменных.
+
+## Доступные классы
+
+- `GeoRef` — Управление глобальной локалью (страна, язык) и ее реактивным состоянием.
+- `DatetimeRef` — Реактивная работа с датами, форматирование и вычисление компонентов времени.
+- `GeoIntlRef` — Реактивное форматирование чисел, валют, списков и относительного времени.
+- `EventRef` — Управление слушателями событий с автоматической привязкой к реактивным элементам.
+- `GeoFlagRef` — Реактивное получение ссылок на флаги стран и списков государств.
+
+## Как с ними работать
+
+В отличие от базовых классов из `functional-basic`, которые работают с прямыми значениями, классы с суффиксом `Ref` принимают на вход как обычные данные, так и `ref`. Внутри они настраивают наблюдение (`watch`) таким образом, что любое изменение источника автоматически обновляет все зависимые вычисляемые свойства.
+
+Глобальное состояние приложения управляется через статический класс `GeoRef`. Его методы возвращают реактивные данные о текущей стране и языке, а вызов `GeoRef.set()` мгновенно обновляет форматирование во всех остальных классах, таких как `GeoIntlRef` или `DatetimeRef`.
+
+```javascript
+import { ref } from 'vue'
+import { GeoRef, DatetimeRef, GeoIntlRef } from '@dxtmisha/functional'
+
+// 1. Глобальное управление (GeoRef)
+const country = GeoRef.getCountry() // Всегда актуальный код страны
+
+// 2. Реактивная обертка над датой (DatetimeRef)
+const dateRaw = ref('2024-03-21')
+const date = new DatetimeRef(dateRaw)
+const displayDate = date.locale() // Автоматически обновится при изменении dateRaw или локали
+
+// 3. Форматирование на лету (GeoIntlRef)
+const price = ref(12500)
+const intl = new GeoIntlRef()
+const displayPrice = intl.currency(price, 'RUB')
+```
+
+Этот же подход используется в `EventRef` для работы с событиями. Если целевой элемент (`ref`) меняется или временно становится `null`, класс сам переподключит слушатели, как только элемент снова появится в DOM. Вам не нужно следить за жизненным циклом элементов вручную — достаточно передать ссылку на объект.
+
+```javascript
+import { ref } from 'vue'
+import { EventRef } from '@dxtmisha/functional'
+
+const buttonRef = ref(null)
+
+// Слушатель сам найдет кнопку, когда Vue привяжет ее к buttonRef
+new EventRef(buttonRef, null, 'click', () => {
+  console.log('Клик обработан реактивно')
+})
+```

package/src/media/functional/functional/ref/ref.vi.mdx

@@ -0,0 +1,57 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/# Lớp Phản hồi (Ref)'/>
+
+# Lớp Phản hồi (Ref)
+
+Các phiên bản phản hồi của các lớp cơ bản được tạo ra để tích hợp liền mạch với **Vue 3 (Composition API)**.
+
+## Các đặc điểm
+
+Ý tưởng cốt lõi là chính lớp đó sẽ giám sát các thay đổi dữ liệu đầu vào và cung cấp `ComputedRef` sẵn sàng sử dụng cho các mẫu. Điều này loại bỏ nhu cầu tính toán lại các giá trị theo cách thủ công khi địa phương hoặc các biến đầu vào thay đổi.
+
+## Các lớp hiện có
+
+- `GeoRef` — Quản lý địa phương toàn cục (quốc gia, ngôn ngữ) và trạng thái phản hồi của nó.
+- `DatetimeRef` — Thao tác ngày tháng phản hồi, định dạng và tính toán thành phần thời gian.
+- `GeoIntlRef` — Định dạng phản hồi các con số, tiền tệ, danh sách và thời gian tương đối.
+- `EventRef` — Quản lý trình lắng nghe sự kiện với khả năng tự động ràng buộc với các phần tử phản hồi.
+- `GeoFlagRef` — Truy xuất phản hồi các liên kết cờ quốc gia và danh sách các quốc gia.
+
+## Cách làm việc với chúng
+
+Khác với các lớp cơ bản từ `functional-basic` làm việc với các giá trị trực tiếp, các lớp có hậu tố `Ref` chấp nhận cả dữ liệu thô và `ref` làm đầu vào. Bên trong, chúng thiết lập các trình quan sát (`watch`) sao cho bất kỳ thay đổi nào đối với nguồn sẽ tự động cập nhật tất cả các thuộc tính tính toán phụ thuộc.
+
+Trạng thái ứng dụng toàn cục được quản lý thông qua lớp `GeoRef` tĩnh. Các phương thức của nó trả về dữ liệu phản hồi về quốc gia và ngôn ngữ hiện tại, và việc gọi `GeoRef.set()` sẽ ngay lập tức cập nhật định dạng trên tất cả các lớp khác, chẳng hạn như `GeoIntlRef` или `DatetimeRef`.
+
+```javascript
+import { ref } from 'vue'
+import { GeoRef, DatetimeRef, GeoIntlRef } from '@dxtmisha/functional'
+
+// 1. Quản lý toàn cục (GeoRef)
+const country = GeoRef.getCountry() // Luôn cập nhật mã quốc gia
+
+// 2. Bộ bọc ngày phản hồi (DatetimeRef)
+const dateRaw = ref('2024-03-21')
+const date = new DatetimeRef(dateRaw)
+const displayDate = date.locale() // Tự động cập nhật khi dateRaw hoặc địa phương thay đổi
+
+// 3. Định dạng tức thì (GeoIntlRef)
+const price = ref(12500)
+const intl = new GeoIntlRef()
+const displayPrice = intl.currency(price, 'VND')
+```
+
+Cách tiếp cận tương tự được sử dụng trong `EventRef` để xử lý các sự kiện. Nếu phần tử mục tiêu (`ref`) thay đổi hoặc tạm thời trở thành `null`, lớp sẽ tự động gắn lại các trình lặp một khi phần tử xuất hiện lại trong DOM. Bạn không cần phải theo dõi chu kỳ sống của phần tử theo cách thủ công — chỉ cần truyền một tham chiếu đến đối tượng.
+
+```javascript
+import { ref } from 'vue'
+import { EventRef } from '@dxtmisha/functional'
+
+const buttonRef = ref(null)
+
+// Trình lắng nghe sẽ tự tìm thấy nút một khi Vue ràng buộc nó với buttonRef
+new EventRef(buttonRef, null, 'click', () => {
+  console.log('Nhấp chuột được xử lý một cách phản hồi')
+})
+```

package/src/media/functional/functional/use-lazy/use-lazy.en.mdx

@@ -0,0 +1,72 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/# Lazy Element Loading'/>
+
+# Element Visibility Tracking (Lazy Loading)
+
+This family of hooks provides a highly performant wrapper around the native browser `IntersectionObserver` API. They are used to track when DOM elements enter the visible viewport (or a specified margin area).
+
+Main use cases:
+- **Lazy loading images**: Load heavy assets only when the user scrolls close to them.
+- **Infinite Scrolling**: Fetch new data when nearing the end of a list.
+- **Scroll animations**: Trigger visual effects exactly when a block becomes visible.
+
+## Features and Which Hook to Choose?
+
+- **`useLazyItemByMarginRef` (Recommended)**: A "smart" singleton hook. It **reuses** the exact same `IntersectionObserver` instance for all elements that share identical `rootMargin` settings. This drastically reduces memory and CPU consumption. If your page has 1,000 lazy images, it creates just 1 shared observer instead of 1,000.
+- **`useLazyRef` (For complex tasks)**: The low-level base hook. It strictly creates an **individual** `IntersectionObserver` scoped to your task. Useful when you need specific configurations (like complex `threshold` arrays, a custom `root` element) or complete manual control over the observer's lifecycle via the `disconnect` method.
+
+## Usage Examples
+
+### 1. Mass Element Tracking (`useLazyItemByMarginRef`)
+
+The most common approach. Pass your element ref and the desired viewport margin (when the trigger should fire). Returns a reactive visibility flag.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useLazyItemByMarginRef } from '@dxtmisha/functional'
+
+const imageRef = ref<HTMLElement>()
+
+// '128px' means the status becomes true 
+// when the element is 128px away from entering the viewport.
+const { lazyItemStatus } = useLazyItemByMarginRef(imageRef, '128px')
+</script>
+
+<template>
+  <!-- Render heavy content only when we get close -->
+  <img 
+    ref="imageRef" 
+    :src="lazyItemStatus ? 'heavy-image.jpg' : 'placeholder.jpg'" 
+  />
+</template>
+```
+
+### 2. Isolated Observer (`useLazyRef`)
+
+Used for fine-grained tasks requiring specific `IntersectionObserver` configurations.
+
+```typescript
+import { ref } from 'vue'
+import { useLazyRef } from '@dxtmisha/functional'
+
+const myContainer = ref<HTMLElement>()
+
+// 1. Create a unique observer
+const observer = useLazyRef({
+  root: document.getElementById('scrollable-area'),
+  rootMargin: '0px',
+  threshold: [0, 0.5, 1.0] // Track every 50% visibility stage
+})
+
+// 2. Add an element to watch
+const isVisible = observer.addLazyItem(myContainer)
+
+// 3. You can extract raw IntersectionObserverEntry data:
+// observer.getItem(myContainer.value)
+
+// 4. Manual cleanup if necessary:
+// observer.removeLazyItem(myContainer.value)
+// observer.disconnectLazy()
+```

package/src/media/functional/functional/use-lazy/use-lazy.ru.mdx

@@ -0,0 +1,72 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/# Ленивая загрузка элементов'/>
+
+# Отслеживание видимости элементов (Ленивая загрузка)
+
+Это семейство хуков предоставляет производительную обертку над нативным браузерным API `IntersectionObserver`. Они используются для отслеживания появления DOM-элементов в зоне видимости экрана (или с заданным отступом). 
+
+Главные сценарии применения:
+- **Ленивая загрузка изображений**: загружать картинки только тогда, когда пользователь почти доскроллил до них.
+- **Бесконечная лента (Infinite Scroll)**: подгружать новые данные при приближении к концу списка.
+- **Анимации при прокрутке**: запускать эффекты только тогда, когда блок реально виден глазам пользователя.
+
+## Особенности и какой хук выбрать?
+
+- **`useLazyItemByMarginRef` (Рекомендуемый)**: "Умный" синглтон-хук. Он **переиспользует** один и тот же `IntersectionObserver` для всех элементов, у которых совпадает настройка `rootMargin`. Это кардинально экономит потребление памяти и CPU. Если у вас список из 1000 ленивых картинок, будет создан только 1 обсервер, а не 1000.
+- **`useLazyRef` (Для сложных задач)**: Низкоуровневый базовый хук. Создает строго **индивидуальный** `IntersectionObserver` для конкретной задачи. Полезен, когда вам нужны специфические настройки (например, сложный массив `threshold`, кастомный `root` элемент) или полный ручной контроль над жизнью обсервера через метод `disconnect`.
+
+## Примеры использования
+
+### 1. Массовое отслеживание (`useLazyItemByMarginRef`)
+
+Самый частый способ работы. Указываете элемент и желаемый отступ (на каком расстоянии до экрана сработает триггер). Возвращает реактивный флаг видимости.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useLazyItemByMarginRef } from '@dxtmisha/functional'
+
+const imageRef = ref<HTMLElement>()
+
+// Параметр '128px' означает, что статус станет true, 
+// когда до элемента останется 128px скролла.
+const { lazyItemStatus } = useLazyItemByMarginRef(imageRef, '128px')
+</script>
+
+<template>
+  <!-- Рендерим тяжелый контент только если мы к нему приблизились -->
+  <img 
+    ref="imageRef" 
+    :src="lazyItemStatus ? 'heavy-image.jpg' : 'placeholder.jpg'" 
+  />
+</template>
+```
+
+### 2. Индивидуальный обсервер (`useLazyRef`)
+
+Используется для точечных задач со специфическими настройками API `IntersectionObserver`.
+
+```typescript
+import { ref } from 'vue'
+import { useLazyRef } from '@dxtmisha/functional'
+
+const myContainer = ref<HTMLElement>()
+
+// 1. Создаем уникальный обсервер
+const observer = useLazyRef({
+  root: document.getElementById('scrollable-area'),
+  rootMargin: '0px',
+  threshold: [0, 0.5, 1.0] // Отслеживаем каждые 50% видимости
+})
+
+// 2. Добавляем элемент для слежения
+const isVisible = observer.addLazyItem(myContainer)
+
+// 3. Вы можете получить сырые данные IntersectionObserverEntry:
+// observer.getItem(myContainer.value)
+
+// 4. Ручная очистка при необходимости:
+// observer.removeLazyItem(myContainer.value)
+// observer.disconnectLazy()
+```

package/src/media/functional/functional/use-lazy/use-lazy.vi.mdx

@@ -0,0 +1,72 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/# Tải Lười (Lazy Loading)'/>
+
+# Theo Dõi Tầm Nhìn Và Tải Lười Phần Tử
+
+Bộ nhóm các hook này mang đến một lớp bọc hiệu năng vượt trội để làm việc với API `IntersectionObserver` nguyên bản của trình duyệt. Chúng được dùng chủ yếu để thu nhận sự kiện khi phần tử DOM bắt đầu đi vào khung hình nhìn thấy (hoặc trong một khoảng từ màn hình được định trước).
+
+Các ứng dụng thực tiễn điển hình:
+- **Tải lười (Lazy load) hình ảnh**: Chỉ tải tài nguyên đồ họa nặng khi người dùng chuẩn bị cuộn tới sát chúng.
+- **Cuộn vô tận (Infinite Scroll)**: Tự động nạp thêm dữ liệu danh sách ngay lúc người dùng lướt đến điểm cuối mốc cuộn.
+- **Diễn hoạt đồ họa (Animations)**: Kích hoạt các hiệu ứng đúng ngay khi phần tử DOM xuất hiện trên tầm mắt người quan sát.
+
+## Những Đặc Tính Khác Biệt Và Nên Dùng Hàm Nào?
+
+- **`useLazyItemByMarginRef` (Khuyên dùng)**: Đây là một hook thông minh. Việc duy nhất nó làm là **tái sử dụng** chính xác một đối tượng `IntersectionObserver` cho tất thảy phần tử thẻ nào khai báo thông số `rootMargin` tương đồng. Phép phân luồng ngầm này giảm thiểu khổng lồ bộ nhớ và sức mạnh CPU. Lấy ví dụ bạn đang tải một danh sách 1,000 thẻ — hệ thống chỉ khởi tạo bảo vệ đúng 1 cái quan sát (thay vì lạm phát lên 1,000).
+- **`useLazyRef` (Cho thiết lập tùy chọn sâu)**: Một dạng hàm base nguyên thủy cấu thành từ đầu. Tự sinh ra một **IntersectionObserver duy nhất** đi theo yêu cầu cục bộ của bạn. Cực kì lý tưởng cho lúc bạn hứng những thông số thiết lập dằn vặt (như mảng array cho phép đo `threshold`, tùy sửa `root`) hay thao tác dập quyền tuyệt đối hủy `disconnect` trình quan sát.
+
+## Ví Dụ Cách Sử Dụng Ngắn Gọn
+
+### 1. Phủ Sóng Mọi Mặt Trận (`useLazyItemByMarginRef`)
+
+Biện pháp căn bản nhất. Định đoạn đối tượng Ref của bạn gửi kèm biên giới khung viền (rootMargin - ví dụ cách bao xa thì trạng thái nảy lên true). Kết quả trả về một biến trạng thái phản ứng boolean.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useLazyItemByMarginRef } from '@dxtmisha/functional'
+
+const imageRef = ref<HTMLElement>()
+
+// Chỉ dấu '128px' ám chỉ là hệ biến status sẽ lật sang True
+// trước lúc bức ảnh xê dịch tiến tới sát màn hình đúng 128px
+const { lazyItemStatus } = useLazyItemByMarginRef(imageRef, '128px')
+</script>
+
+<template>
+  <!-- Render thứ đồ nặng nề một lúc khi đã tới quá gần -->
+  <img 
+    ref="imageRef" 
+    :src="lazyItemStatus ? 'heavy-image.jpg' : 'placeholder.jpg'" 
+  />
+</template>
+```
+
+### 2. Thu Trắc Liên Lẻ (`useLazyRef`)
+
+Giáp nối vào khi thông số API `IntersectionObserver` trở nên cần tính chi li hơn.
+
+```typescript
+import { ref } from 'vue'
+import { useLazyRef } from '@dxtmisha/functional'
+
+const myContainer = ref<HTMLElement>()
+
+// 1. Dựng trạm dò tìm đặc quyền 
+const observer = useLazyRef({
+  root: document.getElementById('scrollable-area'),
+  rootMargin: '0px',
+  threshold: [0, 0.5, 1.0] // Báo tín hiệu ở các mốc 0, 50% và hiển thị 100% lần
+})
+
+// 2. Bắt nó nhìn theo một mục tiêu
+const isVisible = observer.addLazyItem(myContainer)
+
+// 3. Lấy trực tiếp đối tượng dữ liệu đồ sộ của IntersectionObserverEntry:
+// observer.getItem(myContainer.value)
+
+// 4. Giải tán và tước quyền thủ công (khi thực sự cần thiết):
+// observer.removeLazyItem(myContainer.value)
+// observer.disconnectLazy()
+```

package/src/media/functional/functional-basic/about/about.en.mdx

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/! About the Library'/>
+
+# [@dxtmisha/functional-basic](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional-basic)
+
+`@dxtmisha/functional-basic` is a small utility library for everyday web development. It is framework-agnostic and can be used in any TypeScript project, including Vue, React, Nuxt, or plain browser code.
+
+## Installation
+
+To start using the library in your project, install it via npm:
+
+```bash
+npm i @dxtmisha/functional-basic
+```
+
+## Why this library?
+
+Most web projects face similar tasks: API requests, handling dates, cookies, or loading states. Instead of copying these functions between projects, we gathered them here for easier reuse.
+
+It is not a complex framework, but a simple collection of tools: you can pick only what you need for your specific task.
+
+## What does it do?
+
+The library covers common tasks encountered during development:
+
+For **networking** — a basic HTTP client with hook support, caching, and loading indicators. This allows you to handle requests without adding heavy external dependencies.
+
+For **localization and geography** — user country and language detection, phone codes, country flags, and data formatting via the `Intl` API. It also includes tools for interface translations.
+
+For **state management** — simple wrappers for `localStorage`, `sessionStorage`, `cookie`, and URL hash. They help persist data across sessions with TypeScript support.
+
+For **SEO** — tools to manage `<title>`, Open Graph, and Twitter Card. They help keep meta tags updated in both browser and SSR environments.
+
+For **data manipulation** — utilities for deep object cloning, array processing, safe type conversion, and string formatting.
+
+For **search and filtering** — functions for text matching and easy searching through complex data lists.
+
+For **events and broadcasting** — tools for communication between components or browser tabs (via `BroadcastChannel`).
+
+For **DOM and UI** — helper functions for working with elements, attributes, images, clipboard, and scrolling.
+
+## Who is it for?
+
+The library is for developers who prefer using common solutions for simple tasks instead of writing them from scratch each time. It works well for both small scripts and larger applications.
+
+While it is part of the `@dxtmisha` ecosystem, it can be used independently in any project.
+
+## Principles
+
+- **Minimalist** — the library uses no external dependencies, making maintenance easier.
+- **TypeScript Support** — all tools are typed to improve the developer experience.
+- **Clear API** — method names and their behavior are designed to be predictable.
+- **Tested** — core functions are covered by tests to ensure basic stability.
+
+## Git
+
+[https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional-basic](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional-basic)

package/src/media/functional/functional-basic/about/about.ru.mdx

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/! О библиотеке'/>
+
+# [@dxtmisha/functional-basic](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional-basic)
+
+`@dxtmisha/functional-basic` — небольшая библиотека утилит для повседневной веб-разработки. Она не привязана к фреймворкам и может использоваться в любом TypeScript-проекте — от Vue и React до простого браузерного кода.
+
+## Установка
+
+Чтобы начать использовать библиотеку, установите ее через npm:
+
+```bash
+npm i @dxtmisha/functional-basic
+```
+
+## Для чего эта библиотека?
+
+В большинстве веб-проектов возникают одни и те же задачи: запросы к API, работа с датами, куками или состоянием загрузки. Чтобы не копировать одни и те же функции из проекта в проект, мы собрали их в этой библиотеке.
+
+Это не сложный фреймворк, а просто набор инструментов: вы можете брать только то, что нужно для конкретной задачи.
+
+## Что в ней есть?
+
+Библиотека содержит инструменты для обычных задач разработчика:
+
+Для **работы с сетью** — простой HTTP-клиент с поддержкой хуков, кешированием и индикацией загрузки. Это позволяет выполнять запросы без подключения тяжелых внешних зависимостей.
+
+Для **локализации и географии** — определение страны и языка пользователя, телефонные коды, флаги стран и форматирование данных через `Intl` API. Также есть инструменты для перевода интерфейса.
+
+Для **управления состоянием** — обертки для `localStorage`, `sessionStorage`, `cookie` и URL-хеша. Они помогают сохранять данные между сессиями с поддержкой типизации TypeScript.
+
+Для **SEO** — инструменты для управления `<title>`, Open Graph и Twitter Card. Помогают поддерживать актуальность мета-тегов в браузере и при SSR.
+
+Для **работы с данными** — утилиты для глубокого копирования объектов, обработки массивов, безопасного преобразования типов и форматирования строк.
+
+Для **поиска и фильтрации** — функции для сопоставления текста и удобного поиска по сложным спискам данных.
+
+Для **событий и сообщений** — инструменты для обмена данными между компонентами или вкладками браузера (через `BroadcastChannel`).
+
+Для **DOM и UI** — вспомогательные функции для работы с элементами, атрибутами, изображениями, клипбордом и прокруткой.
+
+## Для кого это?
+
+Библиотека подходит тем, кто хочет использовать готовые решения для простых задач вместо того, чтобы писать их с нуля в каждом проекте. Она работает как в небольших скриптах, так и в более крупных приложениях.
+
+Хотя она входит в экосистему `@dxtmisha`, её можно использовать отдельно в любом проекте.
+
+## Принципы
+
+- **Минимализм** — библиотека не использует сторонние пакеты, что упрощает поддержку.
+- **Поддержка TypeScript** — все инструменты типизированы для удобства разработки.
+- **Понятный API** — названия методов и их поведение стараются быть предсказуемыми.
+- **Наличие тестов** — основные функции проверяются тестами для стабильной работы.
+
+## Git
+
+[https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional-basic](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional-basic)

package/src/media/functional/functional-basic/about/about.vi.mdx

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/! Giới thiệu'/>
+
+# [@dxtmisha/functional-basic](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional-basic)
+
+`@dxtmisha/functional-basic` là một tập hợp các hàm và lớp tiện ích nhỏ cho phát triển web hàng ngày. Thư viện không phụ thuộc vào framework và có thể sử dụng trong bất kỳ dự án TypeScript nào — từ Vue, React cho đến code trình duyệt thuần.
+
+## Cài đặt
+
+Để bắt đầu sử dụng thư viện trong dự án của bạn, hãy cài đặt qua npm:
+
+```bash
+npm i @dxtmisha/functional-basic
+```
+
+## Tại sao cần thư viện này?
+
+Hầu hết các dự án web đều gặp các tác vụ tương tự nhau: yêu cầu API, xử lý ngày tháng, cookie hoặc trạng thái tải. Thay vì sao chép các hàm này giữa các dự án, chúng tôi tập hợp chúng lại ở đây để dễ dàng tái sử dụng.
+
+Đây không phải là một framework phức tạp, mà chỉ là một tập hợp các công cụ đơn giản: bạn có thể chọn chỉ những gì cần thiết cho tác vụ cụ thể của mình.
+
+## Thư viện làm được gì?
+
+Thư viện hỗ trợ các tác vụ phổ biến trong quá trình phát triển:
+
+Về **mạng** — một HTTP client cơ bản hỗ trợ hook, bộ nhớ đệm và chỉ báo tải. Điều này cho phép bạn xử lý các yêu cầu mà không cần thêm các dependency bên ngoài nặng nề.
+
+Về **bản địa hóa và địa lý** — phát hiện quốc gia và ngôn ngữ người dùng, mã điện thoại, cờ quốc gia và định dạng dữ liệu qua API `Intl`. Nó cũng bao gồm các công cụ dịch thuật giao diện.
+
+Về **quản lý trạng thái** — các wrapper đơn giản cho `localStorage`, `sessionStorage`, `cookie` và URL hash. Chúng giúp lưu trữ dữ liệu giữa các phiên làm việc với hỗ trợ của TypeScript.
+
+Về **SEO** — công cụ quản lý thẻ `<title>`, Open Graph và Twitter Card. Giúp cập nhật các thẻ meta trong cả môi trường trình duyệt và SSR.
+
+Về **xử lý dữ liệu** — các tiện ích để sao chép sâu đối tượng, xử lý mảng, chuyển đổi kiểu an toàn và định dạng chuỗi.
+
+Về **tìm kiếm và lọc** — các hàm để khớp văn bản và tìm kiếm dễ dàng qua các danh sách dữ liệu phức tạp.
+
+Về **sự kiện và phát tin** — các công cụ để giao tiếp giữa các thành phần hoặc các tab trình duyệt (qua `BroadcastChannel`).
+
+Về **DOM và UI** — các hàm helper để làm việc với phần tử, thuộc tính, hình ảnh, clipboard và cuộn trang.
+
+## Dành cho ai?
+
+Thư viện dành cho các nhà phát triển muốn sử dụng các giải pháp phổ biến cho các tác vụ đơn giản thay vì phải viết lại từ đầu mỗi lần. Nó hoạt động tốt cho cả các script nhỏ và các ứng dụng lớn hơn.
+
+Mặc dù là một phần của hệ sinh thái `@dxtmisha`, nó có thể được sử dụng độc lập trong bất kỳ dự án nào.
+
+## Nguyên tắc
+
+- **Tối giản** — thư viện không sử dụng dependency bên ngoài, giúp việc bảo trì dễ dàng hơn.
+- **Hỗ trợ TypeScript** — tất cả các công cụ đều được định nghĩa kiểu dữ liệu để cải thiện trải nghiệm lập trình.
+- **API rõ ràng** — tên phương thức và hành vi của chúng được thiết kế để dễ dự đoán.
+- **Được kiểm thử** — các chức năng chính được kiểm thử đầy đủ để đảm bảo tính ổn định cơ bản.
+
+## Git
+
+[https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional-basic](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional-basic)

package/src/media/functional/functional-basic/api/api.en.mdx

@@ -0,0 +1,135 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/# Api'/>
+
+# Api
+
+The `Api` class is a central utility for making HTTP requests. It provides a simple interface for common methods and manages global settings like base URL, default headers, and lifecycle hooks.
+
+## Basic Usage
+
+The simplest way to make a request is by using the static methods `get`, `post`, `put`, or `delete`. All methods support response typing via Generics.
+
+```javascript
+import { Api } from '@dxtmisha/functional-basic'
+
+// Simple GET request with typing
+const data = await Api.get<User[]>({ path: 'users' })
+
+// POST request with data in the body
+const newUser = await Api.post<User>({
+  path: 'users',
+  request: { name: 'John Doe', job: 'Developer' }
+})
+```
+
+## Global Configuration
+
+You can configure the API behavior globally, for example, during application initialization. This removes the need to specify full paths and common headers in every call.
+
+```javascript
+// Set the base URL for all relative paths
+Api.setUrl('https://api.example.com/v1/')
+
+// Add common headers (e.g., an authorization token)
+Api.setHeaders({
+  'Authorization': 'Bearer YOUR_TOKEN'
+})
+
+// Set common parameters to be added to every request
+Api.setRequestDefault({
+  app_version: '1.0.0'
+})
+```
+
+## Lifecycle Hooks
+
+The library allows you to inject global logic that will trigger for every request. This is useful for dynamically adding tokens, logging, or centralized server error handling.
+
+### Preparation Hook (setPreparation)
+
+Executed immediately before a request is sent to the server.
+
+- **Parameters**: Receives the `apiFetch` object, which contains all parameters of the current request (path, method, data, etc.).
+- **Usage**: Checking access rights, adding dynamic parameters to `apiFetch.request`, or simply logging the start of an operation.
+
+```javascript
+Api.setPreparation(async (apiFetch) => {
+  // You can modify apiFetch before sending
+  console.log(`Starting request to: ${apiFetch.path}`)
+})
+```
+
+### End Hook (setEnd)
+
+Executed after the server returns a response, but before the data reaches your code.
+
+- **Parameters**: Receives the native `Response` object and the `apiFetch` settings object.
+- **Returns**: A Promise with an object `{ reset?: boolean, data?: any }`.
+- **Reset Flag**: If `true` is returned, the library will abort the current chain and execute the request again. This is useful for automatically handling an expired token (Refresh Token).
+- **Data Field**: Allows you to replace or supplement the data returned by the `Api.request` method.
+
+```javascript
+Api.setEnd(async (response, apiFetch) => {
+  // For example, handling a 401 Unauthorized error
+  if (response.status === 401) {
+    const isRefreshed = await myAuthService.refreshToken()
+    
+    if (isRefreshed) {
+      return { reset: true } // Retry the request with the new token
+    }
+  }
+  
+  return {} // Continue with standard processing
+})
+```
+
+## Response Emulation
+
+The built-in `ApiResponse` manager (accessible via `Api.getResponse()`) allows you to intercept requests and return mock data. This is extremely useful for UI development when the backend is not ready, or for writing tests.
+
+### Registering Mocks
+
+You can add both static responses and dynamic functions.
+
+```javascript
+const responseManager = Api.getResponse()
+
+// 1. Static response for a GET request
+responseManager.add({
+  path: 'profile',
+  method: 'GET',
+  response: { id: 1, name: 'Admin' },
+  lag: true // Simulate network delay (0-2 sec)
+})
+
+// 2. Dynamic response based on request parameters
+responseManager.add({
+  path: 'users/search',
+  method: 'GET',
+  response: (request) => {
+    return {
+      results: [`Result for: ${request.query}`],
+      count: 1
+    }
+  }
+})
+
+// 3. Intercept a POST request with any body
+responseManager.add({
+  path: 'users/update',
+  method: 'POST',
+  request: '*any', // Ignore request body validation
+  response: { success: true }
+})
+```
+
+### Developer Mode
+
+For easier debugging, you can enable emulation logging in the console. In this mode, the manager will warn in the console about every intercepted request.
+
+```javascript
+Api.getResponse().setDevMode(true)
+```
+
+The emulator triggers **before** the real `fetch` is executed. If no matching mock is found, `Api` will perform a regular network request.