@dxtmisha/functional 1.15.5 → 1.15.6

package/ai-description.md

@@ -1,29 +1,7 @@
-1. CORE PURPOSE
-This library (@dxtmisha/functional) provides Vue 3 reactive abstractions, abstract base classes for component architecture, and advanced composables. It elevates low-level functional utilities from @dxtmisha/functional-basic into Vue 3 reactivity system (refs, computed, lifecycle, reactive singletons) to handle REST API orchestration, localization, meta management, routing, client-side storage, lazy loading, list/search data structures, and standard component state construction.
-
-2. KEY EXPOSITIONS
-Abstract Component Base Classes: DesignAbstract, DesignAsyncAbstract, DesignChanged, DesignComponents, DesignComp, DesignConstructorAbstract. These manage component state lifecycle, dynamic class and style processing, event hooks, slot rendering, component modifications, and property mutation tracking.
-
-Reactive API Composables: useApiRef, useApiAsyncRef, useApiManagementRef, useApiManagementAsyncRef, useApiGet, useApiPost, useApiPut, useApiDelete, useApiRequest. These handle REST operations with SSR prefetching, response contract validation, mutation handling, error contract mapping, client-side pagination/filtering, and automatic state reactivity.
-
-Singleton State & Execution Control: executeUse, executeUseGlobal, executeUseProvide, executeUseLocal, executeUseGlobalInit. These encapsulate factory initialization into global, component-tree inject/provide, or closure-local singletons.
-
-Localization & Formatting Classes and Composables: DatetimeRef, GeoFlagRef, GeoIntlRef, GeoRef, GeoUnitRef, useGeoIntlRef, useGeoUnitRef, useFormattersRef, useTranslateRef, t. These offer reactive locale-aware date/time formatting, unit conversion, flag retrieval, and multi-key translation refs.
-
-Data Structures & UI Management: ListDataRef, useRouterList, useSearchRef, useSearchValueRef, useLazyRef, useLazyItemByMarginRef, ScrollbarWidthRef, EventRef, EffectScopeGlobal. These provide reactive list data mapping, search query debounce and highlighting, lazy-loading via IntersectionObserver, scrollbar width tracking, and global effect scopes.
-
-State Persistence & Browser Composables: useBroadcastValueRef, useCookieRef, useHashRef, useQueryRef, useSessionRef, useStorageRef, useMeta. These control cross-tab communication, cookies, URL query/hash reactive synchronization, session/local storage, and reactive HTML document metadata.
-
-Utility Functions & Plugin: computedAsync, computedByLanguage, computedEternity, getBind, getBindRef, render, toBind, toBinds, dxtFunctionalPlugin.
-
-3. TRIGGERS FOR STUDYING AI-TYPES.MD
-Reading ai-types.md is mandatory under any of the following conditions, keywords, or implementation tasks:
-- Extending or sub-classing DesignConstructorAbstract, DesignAbstract, DesignAsyncAbstract, or DesignComponents.
-- Configuring API integrations requiring complex typing, specifically ApiManagementGet, ApiManagementSearch, ApiManagementRequest, or ApiOptions.
-- Utilizing component metadata and binding types, such as ConstrBind, ConstrClasses, ConstrStyles, ConstrOptions, ConstrSetup, ConstrComponentMod, or ConstrProps.
-- Constructing managed singletons using executeUse, executeUseGlobal, executeUseProvide, or executeUseLocal.
-- Typing complex list inputs, search items, and reactive parameters using ListList, ListDataItem, ListDataFull, RefOrNormal, RefType, or RefOrNormalOrFunction.
-- Implementing contract validation functions (validateResponseContract, validateRequestContract) or error contracts (ApiErrorStorageList) with schema validation libraries.
-
-4. INTEGRATION CONTEXT
-Initializes as a Vue 3 plugin via dxtFunctionalPlugin. Connects directly with Vue 3 reactivity and rendering APIs (ref, computed, VNode, provide/inject). Wraps base functional logic from @dxtmisha/functional-basic, integrates with vue-router via RouterItemRef, links to @dxtmisha/media for social icons, and supports runtime schema validation (such as @effect/schema) inside API payload contracts.
+This library provides a reactive utility and component abstraction framework for Vue 3 built on top of functional basic utilities, standardizing UI design system architecture, reactive API request orchestration, localized data formatting, and state management. Its core capabilities span five main modules: the API & Network Module (`useApiRef`, `useApiAsyncRef`, `useApiManagementRef`, `useApiRequest`, and HTTP method composables) manages reactive request lifecycle, SSR prefetching, error contracts, response validation, and list mutations; the Design & Component Architecture Module (`DesignConstructorAbstract`, `DesignComponents`, `DesignAbstract`, `DesignChanged`) provides abstract base classes for component setup, dynamic rendering, class and style calculation, slot management, and prop change tracking; the Localization & Geo Module (`GeoRef`, `GeoIntlRef`, `GeoUnitRef`, `GeoFlagRef`, `DatetimeRef`, `useTranslateRef`) handles reactive internationalization, language/country metadata, locale-sensitive number and date formatting, unit conversions, and translation keys; the Storage & State Module (`useStorageRef`, `useCookieRef`, `useSessionRef`, `useBroadcastValueRef`, `useQueryRef`, `useHashRef`, `executeUse`) binds local/session storage, cookies, cross-tab communication, URL state, and singletons to Vue reactive references; and the DOM, Search & Navigation Module (`useLazyRef`, `RouterItemRef`, `useRouterList`, `useSearchRef`, `useMeta`, `EventRef`) provides lazy visibility tracking, router integration, search indexing, DOM event listeners, and reactive meta tag management. AI assistant study of ai-types.md is mandatory when extending design component abstractions like `DesignConstructorAbstract` or `DesignComponents`, typing component properties, modifications, or emits via `ConstrComponentMod`, `ConstrClasses`, `ConstrEmit`, or `ConstrBind`, configuring API management types including `ApiManagementGet`, `ApiManagementRequest`, or `ApiManagementSearch`, handling reactive input wrappers typed with `RefOrNormal` or `RefOrNormalOrFunction`, or structuring dataset records using `ListListInput`, `ListDataItem`, and `ListSelectedList`. The library seamlessly integrates with Vue 3, vue-router, and @dxtmisha/functional-basic to form a cohesive reactive application infrastructure.
+## Mandatory Rules
+Read the corresponding file if your task relates to:
+- 'node_modules/@dxtmisha/functional/ai-prompts/api-reference.md': Scope-isolated singleton factories and reactive REST API management
+- 'node_modules/@dxtmisha/functional/ai-prompts/localization-seo.md': Geographic context, i18n formatting, translation primitives, document metadata, and scrollbar utilities
+- 'node_modules/@dxtmisha/functional/ai-prompts/reactivity-lists.md': Async reactivity composables, list data models, search filters, and DOM observers
+- 'node_modules/@dxtmisha/functional/ai-prompts/storage-state.md': Composables for reactive browser storage, session, cookies, cross-tab broadcasting, and URL hash state

package/ai-doc.md

@@ -1,42 +1,8 @@
 # @dxtmisha/functional Reference
-Vue 3 reactive utilities built on `@dxtmisha/functional-basic`. See `ai-types.md` for full signatures.
-
-## Usage Rules & Strategies
-- **Priority**: Always use this package over `@dxtmisha/functional-basic` in Vue.
-- **API/State Singletons**: **NEVER** call `useApi*` / `executeUse*` hooks directly in Vue components. Wrap them in `executeUseGlobal` (startup), `executeUseLocal` (lazy, session scope), or `executeUseProvide` (scoped tree) inside external service files. Components only import and call the resulting hook.
-
-```typescript
-import { executeUseLocal, useApiManagementRef, useStorageRef, useSessionRef, useCookieRef, useBroadcastValueRef, useHashRef, GeoRef, useGeoIntlRef, useTranslateRef, useMeta, ScrollbarWidthRef, computedAsync, computedEternity, ListDataRef, useSearchRef, EventRef, useLazyRef } from '@dxtmisha/functional';
-
-// 1. API Management
-export const useUsers = executeUseLocal(() => useApiManagementRef(
-  { path: '/api/users' }, { date: (v) => new Date(v).toLocaleString() }, { columns: ['name'] },
-  { path: '/api/users' }, { path: (o) => `/api/users/${o.id}` }, { path: (o) => `/api/users/${o.id}` }
-));
-
-// 2. Storage & State
-const theme = useStorageRef<'light' | 'dark'>('theme', 'light');
-const step = useSessionRef<number>('step', 1);
-const token = useCookieRef<string>('auth', '', { secure: true });
-const sync = useBroadcastValueRef<string>('ch', 'idle');
-const page = useHashRef<string>('page', 'home');
 
-// 3. Geo & Formatting
-const country = GeoRef.getCountry(); const intl = useGeoIntlRef(); intl.currency(150, 'EUR');
-const t = useTranslateRef(['global.save']);
-
-// 4. SEO & Layout
-useMeta().setTitle('Page'); const scrollW = new ScrollbarWidthRef().width;
-
-// 5. Reactivity Helpers
-const asyncData = computedAsync(async () => fetch(), 'loading...');
-const cached = computedEternity(async () => fetch(), 'loading...');
-
-// 6. Lists & Search
-const list = new ListDataRef(items, selectedId); list.isSelected;
-const { listSearch } = useSearchRef(items, ['label'], ref('query'));
+Vue 3 reactive utilities built on `@dxtmisha/functional-basic`. See `ai-types.md` for full signatures.
 
-// 7. DOM Events & Lazy
-const listener = new EventRef(window, window, 'keydown', (e) => console.log(e.key));
-const lazy = useLazyRef(); lazy.addLazyItem(elementRef);
-```
+## Core Architectural Rules & Strategies
+- **Priority**: Always use `@dxtmisha/functional` reactive composables instead of low-level `@dxtmisha/functional-basic` primitives in Vue 3 applications.
+- **API & State Singletons**: **NEVER** call `useApi*` / `executeUse*` hooks directly in Vue components (`<script setup>`). Wrap them in `executeUseGlobal` (startup), `executeUseLocal` (lazy, session scope), or `executeUseProvide` (scoped tree) inside external service files. Components only import and call the resulting hook.
+- **Purity & Atomicity**: Keep Vue components minimal. Extract all reactive state management, network orchestration, and side effects into external composables.

package/ai-mcp.json

@@ -0,0 +1,26 @@
+[
+  {
+    "uri": "@dxtmisha/functional/ai-prompts/api-reference.md",
+    "name": "API Management Reference",
+    "mimeType": "text/markdown",
+    "description": "Guidance and architectural patterns for REST API management and scope-isolated reactive singleton factories using the @dxtmisha/functional library."
+  },
+  {
+    "uri": "@dxtmisha/functional/ai-prompts/localization-seo.md",
+    "name": "Localization SEO Utilities",
+    "mimeType": "text/markdown",
+    "description": "Guidelines and reactive utilities for locale-aware formatting, multi-key translations, geographic context, and dynamic HTML document metadata management."
+  },
+  {
+    "uri": "@dxtmisha/functional/ai-prompts/reactivity-lists.md",
+    "name": "Reactivity and Lists",
+    "mimeType": "text/markdown",
+    "description": "Provides specifications and usage patterns for advanced async reactivity helpers, list selection models, debounced search filters, and DOM observer utilities."
+  },
+  {
+    "uri": "@dxtmisha/functional/ai-prompts/storage-state.md",
+    "name": "Browser State Composables",
+    "mimeType": "text/markdown",
+    "description": "Provides reactive composable wrappers for persistent and synchronized browser state management, including localStorage, sessionStorage, cookies, broadcast channels, and URL hash fragments."
+  }
+]

package/ai-prompts/api-reference.md

@@ -0,0 +1,25 @@
+# API Management & Reactive Singletons
+
+Guidance and usage patterns for REST API management and scope-isolated singleton factories in `@dxtmisha/functional`.
+
+## 1. Scope Factory Initialization (`executeUse*`)
+- **`executeUseGlobal`**: Initializes a global singleton instance at application startup (shared across the entire application).
+- **`executeUseLocal`**: Lazily creates a session-scoped or closure-local instance upon first invocation.
+- **`executeUseProvide`**: Scope-bound singleton bound to a specific component subtree via Vue `provide` / `inject`.
+
+## 2. API Management (`useApiManagementRef`)
+Handles REST CRUD operations with built-in reactivity, client-side caching, filtering, and contract validation.
+
+### Example
+```typescript
+import { executeUseLocal, useApiManagementRef } from '@dxtmisha/functional';
+
+export const useUsers = executeUseLocal(() => useApiManagementRef(
+  { path: '/api/users' },
+  { date: (v: string) => new Date(v).toLocaleString() },
+  { columns: ['name', 'email'] },
+  { path: '/api/users' },
+  { path: (o) => `/api/users/${o.id}` },
+  { path: (o) => `/api/users/${o.id}` }
+));
+```

package/ai-prompts/localization-seo.md

@@ -0,0 +1,29 @@
+# Localization, Geo & SEO Management
+
+Locale-aware formatting, translation primitives, and reactive HTML document metadata handling.
+
+## Available Utilities
+- **`GeoRef`**: Access country information and geographic context (`GeoRef.getCountry()`).
+- **`useGeoIntlRef()`**: Reactive internationalization helper for currency, numbers, and dates.
+- **`useTranslateRef(keys)`**: Multi-key reactive translation resolver.
+- **`useMeta()`**: Reactive manager for HTML document title, meta tags, and open graph social tags.
+- **`ScrollbarWidthRef`**: Helper to measure dynamic scrollbar width for fixed overlay calculations.
+
+### Example
+```typescript
+import {
+  GeoRef,
+  useGeoIntlRef,
+  useTranslateRef,
+  useMeta,
+  ScrollbarWidthRef
+} from '@dxtmisha/functional';
+
+const country = GeoRef.getCountry();
+const intl = useGeoIntlRef();
+intl.currency(150, 'EUR');
+
+const t = useTranslateRef(['global.save']);
+useMeta().setTitle('User Dashboard');
+const scrollW = new ScrollbarWidthRef().width;
+```

package/ai-prompts/reactivity-lists.md

@@ -0,0 +1,34 @@
+# Reactivity Helpers, Lists & DOM Utilities
+
+Advanced async reactivity, list data models, search filters, and DOM observers.
+
+## Available Composables & Classes
+- **`computedAsync(evaluator, defaultVal)`**: Asynchronous computed reference for promise resolution.
+- **`computedEternity(evaluator, defaultVal)`**: Cached asynchronous computed ref that preserves state across re-evaluations.
+- **`ListDataRef(items, selectedId)`**: Reactive list structure supporting selection state management.
+- **`useSearchRef(items, fields, queryRef)`**: Debounced multi-field search and highlighting composable.
+- **`EventRef(target, element, event, callback)`**: Managed DOM event listener with automatic lifecycle cleanup.
+- **`useLazyRef()`**: IntersectionObserver helper for lazy rendering and dynamic element loading.
+
+### Example
+```typescript
+import { ref } from 'vue';
+import {
+  computedAsync,
+  computedEternity,
+  ListDataRef,
+  useSearchRef,
+  EventRef,
+  useLazyRef
+} from '@dxtmisha/functional';
+
+const asyncData = computedAsync(async () => fetch('/api/data').then(r => r.json()), 'loading...');
+const cachedData = computedEternity(async () => fetch('/api/cached').then(r => r.json()), 'loading...');
+
+const list = new ListDataRef(items, selectedId);
+const query = ref('');
+const { listSearch } = useSearchRef(items, ['name', 'description'], query);
+
+const listener = new EventRef(window, window, 'keydown', (e) => console.log(e.key));
+const lazy = useLazyRef();
+```

package/ai-prompts/storage-state.md

@@ -0,0 +1,27 @@
+# Reactive Storage & Browser State
+
+Composable wrappers for persistent and synchronized browser state management.
+
+## Available Composables
+- **`useStorageRef<T>(key, defaultVal)`**: Reactive `localStorage` wrapper with cross-tab synchronization.
+- **`useSessionRef<T>(key, defaultVal)`**: Reactive `sessionStorage` wrapper for session-scoped data.
+- **`useCookieRef<T>(key, defaultVal, options)`**: SSR-safe reactive cookie state wrapper.
+- **`useBroadcastValueRef<T>(channel, defaultVal)`**: Reactive cross-tab broadcast messaging using `BroadcastChannel`.
+- **`useHashRef<T>(key, defaultVal)`**: Reactive synchronization with URL hash fragments.
+
+### Example
+```typescript
+import {
+  useStorageRef,
+  useSessionRef,
+  useCookieRef,
+  useBroadcastValueRef,
+  useHashRef
+} from '@dxtmisha/functional';
+
+const theme = useStorageRef<'light' | 'dark'>('theme', 'light');
+const step = useSessionRef<number>('step', 1);
+const token = useCookieRef<string>('auth', '', { secure: true });
+const sync = useBroadcastValueRef<string>('ch', 'idle');
+const page = useHashRef<string>('page', 'home');
+```