@dxtmisha/functional 1.11.7 → 1.11.9

package/ai-description.txt

@@ -1,5 +1,5 @@
-A Vue 3-centric orchestration framework and utility library designed for reactive data management, API synchronization, and localized UI logic. Its primary function is providing high-level abstractions for network request life cycles, including integrated GET/mutation handling with skeleton support, and complex list state management covering focus, selection, and client-side filtering. It offers specialized reactive primitives such as asynchronous computed properties, demand-cached refs, and multi-strategy singleton management using Global, Local, and Provide/Inject patterns.
+This library provides a reactive framework for Vue 3 application development, focusing on structured UI component construction, complex data management, and orchestrated API interactions. Its core purpose is to standardize component architecture through abstract base classes like DesignConstructorAbstract and to provide reactive, high-level wrappers for localized formatting (GeoIntlRef), date manipulation (DatetimeRef), and state persistence (useStorageRef, useCookieRef, useBroadcastValueRef).
 
-An AI should study this API when implementing robust API-to-UI orchestration involving data transformation and contract validation, or when developing UI components that require standardized class/style resolution through the library’s abstract design classes. It is indispensable for scenarios requiring multi-tab state synchronization via broadcast channels, cookie-backed reactive variables, and SSR-compatible SEO meta-tag management. The library's i18n and localization modules are critical for handling country-specific formatting for currencies, units, relative time, and geographical metadata.
+An AI should study this library when implementing a design system requiring standardized class-based component logic or when building data-intensive interfaces that need integrated searching, filtering, and CRUD operations via useApiManagementRef. It is indispensable for scenarios involving multi-tab state synchronization, SEO management (useMeta), and reactive internationalization (useTranslateRef) where DOM synchronization must be automated.
 
-The library is built upon the Vue 3 Composition API and @dxtmisha/functional-basic, integrating directly with Vue Router for navigation-aware data structures. It functions as a middleware layer between raw data sources and the presentation layer, requiring the dxtFunctionalPlugin for global service initialization including API clients, translation instances, and icon configurations.
+The library integrates directly with Vue 3 and vue-router, acting as a reactive middleware layer over @dxtmisha/functional-basic. It utilizes a singleton management pattern (executeUse) for global service orchestration and relies heavily on Ref and ComputedRef to maintain its internal state machine and lifecycle hooks.

package/ai-doc.ru.txt

@@ -0,0 +1,34 @@
+Это главная функциональная библиотека для среды Vue (@dxtmisha/functional). Здесь собраны утилиты, composables и реактивные классы, заточенные под Vue.
+
+ПРАВИЛА ИСПОЛЬЗОВАНИЯ:
+1. При разработке на Vue всегда отдавайте приоритет этой библиотеке для работы с логикой и composables, а не `@dxtmisha/functional-basic`.
+2. Библиотека оборачивает базовую нереактивную логику в систему реактивности Vue. Если нужная функция или класс есть здесь, они имеют абсолютный приоритет.
+3. Импортируйте утилиты из `@dxtmisha/functional` для реактивного поведения UI, composables и управления состоянием.
+
+РАБОТА С API И СОСТОЯНИЕМ (useApi / executeUse):
+Для работы с сетевыми запросами в библиотеке предусмотрен набор хуков: `useApiGet`, `useApiPost`, `useApiPut`, `useApiDelete`, `useApiRequest`, `useApiRef`, `useApiAsyncRef`, `useApiManagementRef`, `useApiManagementAsyncRef`.
+Строго соблюдайте следующие правила их применения:
+
+1. НЕ ВЫЗЫВАЙТЕ эти хуки напрямую в компонентах (SFC).
+2. Выносите всю настройку и вызовы `useApi*` в ОТДЕЛЬНЫЕ ФАЙЛЫ (сервисы / хранилища).
+3. Оборачивайте настройку API в фабрику `executeUse` (а именно: `executeUseGlobal`, `executeUseProvide` или `executeUseLocal` из `src/functions/executeUse.ts`). Это гарантирует создание синглтонов (одна точка доступа) и предотвращает создание дубликатов запросов и хранилищ состояния.
+4. Выполняйте любую дополнительную обработку запросов (например: маппинг данных, подготовка структуры для отображения скелетона перед загрузкой формы) в этом же файле, внутри коллбэка `executeUse`, а наружу возвращайте уже полностью готовый набор данных и методов.
+   *Пример правильного использования:*
+   ```ts
+   import { executeUseGlobal } from '@dxtmisha/functional';
+   import { useApiManagementRef } from '@dxtmisha/functional';
+
+   export const useUserManagement = executeUseGlobal(() => {
+     return useApiManagementRef(
+       { path: '/api/users' },                 // GET setup
+       { date: (v) => new Date(v).toLocaleString() }, // Formatters
+       { columns: ['name', 'email'] },         // Search
+       { path: '/api/users' },                 // POST
+       { path: (o) => `/api/users/${o.id}` },  // PUT
+       { path: (o) => `/api/users/${o.id}` }   // DELETE
+     );
+     // Здесь же можно добавить логику подготовки скелетонов, форматирования и т.д.
+     // и затем вернуть расширенный объект
+   });
+   ```
+5. В самом Vue-компоненте просто импортируйте и вызывайте созданный синглтон-хук: `const { list, loading, sendPost } = useUserManagement();`

package/ai-doc.txt

@@ -0,0 +1,34 @@
+This is the main functional library for the Vue environment (@dxtmisha/functional). It contains Vue-specific utilities, composables, and reactive classes.
+
+USAGE RULES:
+1. When developing in Vue, always use this library for functionality, logic, and composables instead of `@dxtmisha/functional-basic` whenever possible.
+2. It wraps basic non-reactive logic into Vue's reactivity system. If the required function or composable exists here, it has absolute priority.
+3. Import utilities from `@dxtmisha/functional` for reactive UI behavior, composables, and state management.
+
+WORKING WITH API AND STATE (useApi / executeUse):
+A set of composables is provided for network requests: `useApiGet`, `useApiPost`, `useApiPut`, `useApiDelete`, `useApiRequest`, `useApiRef`, `useApiAsyncRef`, `useApiManagementRef`, `useApiManagementAsyncRef`.
+Strictly follow these rules for their application:
+
+1. DO NOT call these composables directly in the Vue components (SFC).
+2. Move all API configurations and `useApi*` calls into SEPARATE FILES (services/stores).
+3. Wrap the API configurations inside the `executeUse` factory (specifically: `executeUseGlobal`, `executeUseProvide`, or `executeUseLocal` from `src/functions/executeUse.ts`). This guarantees the creation of managed singletons (single access point) and prevents duplicated requests and reactive states.
+4. Perform any additional request processing (e.g., data mapping, preparing structures for skeletons before loading a form) in the same file, inside the `executeUse` callback, and return a fully prepared set of data and methods.
+   *Example of correct usage:*
+   ```ts
+   import { executeUseGlobal } from '@dxtmisha/functional';
+   import { useApiManagementRef } from '@dxtmisha/functional';
+
+   export const useUserManagement = executeUseGlobal(() => {
+     return useApiManagementRef(
+       { path: '/api/users' },                 // GET setup
+       { date: (v) => new Date(v).toLocaleString() }, // Formatters
+       { columns: ['name', 'email'] },         // Search
+       { path: '/api/users' },                 // POST
+       { path: (o) => `/api/users/${o.id}` },  // PUT
+       { path: (o) => `/api/users/${o.id}` }   // DELETE
+     );
+     // Logic for skeletons, additional formatting, etc., should be added here,
+     // and then return the extended object.
+   });
+   ```
+5. Within the Vue component itself, simply import and call your custom singleton composable: `const { list, loading, sendPost } = useUserManagement();`