@dxtmisha/functional 1.15.2 → 1.15.5

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.15.5] - 2026-07-25
+
+### Added
+- **useSearchRef**: Supported reactive `Ref` and getter callbacks for the `columns` parameter via `SearchColumnsInput` (`SearchColumnsRef<T, K>`), dynamically updating search results when target columns change.
+- **searchTypes**: Introduced `SearchColumnsRef` and `SearchColumnsInput` type definitions to support reactive column definitions.
+
+### Changed
+- **GeoIntlRef & useGeoIntlRef**: Added JSDoc `@remarks` guidelines recommending the use of standard non-reactive `GeoIntl` from `@dxtmisha/functional-basic` when reactivity is not required.
+- **package.json**: Updated package `description` and expanded `keywords` list to comprehensively cover composables, `executeUse` singletons, and reactive utilities. Fixed `homepage` and `repository.directory` paths.
+- **README.md**: Updated documentation and Quick Start code examples to showcase `executeUseGlobal` state singletons and reactive composables while preserving original document layout and style.
+
+## [1.15.4] - 2026-07-24
+
+### Changed
+- **useLazyItemByMarginRef**: Added explicit return type annotations (`ReturnType<typeof useLazyRef>`) for `getItemByMargin` and `LazyItemByMargin[]` for `getItems`.
+- **useLazyRef**: Updated `getItem(element?: HTMLElement)` method signature to accept optional element references.
+
+## [1.15.3] - 2026-07-14
+
+### Changed
+- **executeUse**: Refactored singleton lifecycle and cache management to use `ServerStorage` with key `__executeUse::${id}__` via a `storageKey` constant, replacing local closure variables and supporting clean instance removal.
+- **useMeta**: Updated metadata initialization to reference `MetaStatic.getItem()` rather than using the class object itself.
+
+### Fixed
+- **Tests**: Fixed the mock setup in `useMeta.test.ts` to include the `getItem` method on the mocked `MetaStatic` class.
+
 ## [1.15.0] - 2026-07-02
 
 ### Added

package/README.md

@@ -4,25 +4,27 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
 
-`@dxtmisha/functional` is a library of utilities, base classes, and composables for complex web development in Vue 3. The package operates on the foundation of `@dxtmisha/functional-basic`, providing reactive wrappers and architectural solutions designed specifically for the Vue ecosystem (Composition API).
+`@dxtmisha/functional` is a library of utilities, base classes, and composables for complex web development in Vue 3. The package operates on the foundation of `@dxtmisha/functional-basic`, providing reactive wrappers, state singletons, and architectural solutions designed specifically for the Vue ecosystem (Composition API).
 
 ## Why this library?
 
-Every modern frontend application inevitably faces the same set of challenges: managing HTTP requests, localization, dates, cookies, caching, loading states, and side effects. 
+Every modern frontend application inevitably faces the same set of challenges: managing HTTP requests, state synchronization, localization, dates, cookies, caching, loading states, and side effects. 
 
-When developers solve these tasks locally within components, it often leads to code duplication, bloated `.vue` files, and memory leaks from forgotten subscriptions. `functional` solves this by moving business logic into ready-made reactive abstractions. You simply call the necessary composable or class, and under the hood, the library manages `ref` dependencies, monitors the Vue lifecycle, and maintains strict TypeScript typing.
+When developers solve these tasks locally within components, it often leads to code duplication, bloated `.vue` files, memory leaks from forgotten subscriptions, and difficult-to-maintain state. `functional` solves this by moving business logic into ready-made reactive abstractions and state singletons (`executeUse`). You simply call the necessary composable or class, and under the hood, the library manages `ref` dependencies, monitors the Vue lifecycle, handles SSR hydration, and maintains strict TypeScript typing.
 
 ## What does it do?
 
-For **network requests (API)** — a set of composables (`useApiGet`, `useApiPost`, `useApiRequest`, etc.) that encapsulate server interactions. They return a fully reactive object with loading states, errors, and fetched data. They intelligently handle response caching, headers, and automatic cancellation of outdated requests.
+For **network requests (API)** — a set of reactive composables (`useApiRef`, `useApiManagementRef`, `useApiGet`, `useApiPost`, `useApiPut`, `useApiDelete`) that encapsulate server interactions. They return a fully reactive object with loading states, errors, client-side search, schema validation, and fetched data. They intelligently handle response caching, SSR hydration, headers, and automatic cancellation of outdated requests.
 
-For **browser state management** — convenient reactive hooks (`useStorageRef`, `useSessionRef`, `useCookieRef`, `useHashRef`) that seamlessly bind a Vue variable to LocalStorage, URL hash, or a cookie. It automatically synchronizes with browser storage and reacts across tabs.
+For **state management & singletons (`executeUse`)** — `executeUseLocal`, `executeUseGlobal`, and `executeUseProvide` factories that allow creating managed singleton state hooks. This decouples complex API and business logic completely from `.vue` components, ensuring unified state across component trees and preventing duplicate requests.
 
-For **geolocation and internationalization** — utilities like `useTranslateRef`, `useGeoIntlRef`, and `DatetimeRef` that automatically respond strictly to changes in global environment settings (language, currency, region) and dynamically rebuild forms, dates, and translations without custom event listeners.
+For **browser state management** — convenient reactive hooks (`useStorageRef`, `useSessionRef`, `useCookieRef`, `useHashRef`, `useQueryRef`, `useBroadcastValueRef`) that seamlessly bind Vue variables to LocalStorage, SessionStorage, cookies, URL hash/query parameters, or BroadcastChannels with automatic cross-tab synchronization.
 
-For **UI component architecture** — a powerful system of base classes (`DesignAbstract`, `DesignComp`, `DesignAsyncAbstract`) that allows extracting complex internal component logic into separate, testable files. This makes `.vue` templates beautifully clean and business features highly reusable.
+For **geolocation and internationalization** — utilities like `useTranslateRef` (`t`), `useGeoIntlRef`, `useGeoUnitRef`, `GeoFlagRef`, and `DatetimeRef` that automatically respond to changes in global environment settings (language, currency, region) and dynamically rebuild dates, numbers, units, and translations without manual event listeners.
 
-For **auxiliary utilities** — specialized reactive modules for SEO tags (`useMeta`), inter-tab real-time communication (`useBroadcastValueRef`), robust loading indicators (`useLoadingRef`), and executing asynchronous operations cleanly in the Vue render cycle (`computedAsync`, `toComputed`).
+For **UI component architecture** — a powerful system of base classes (`DesignConstructorAbstract`, `DesignComponents`, `DesignComp`, `DesignAbstract`, `DesignAsyncAbstract`) that provides a structured class-based inheritance model for building complex UI component constructors with automatic lifecycle, slot rendering, and BEM styling.
+
+For **auxiliary utilities** — specialized reactive modules for SEO meta tags (`useMeta`), reactive scrollbar tracking (`ScrollbarWidthRef`), IntersectionObserver lazy loading (`useLazyRef`), list selection management (`ListDataRef`), debounced list search (`useSearchRef`), and asynchronous computation primitives (`computedAsync`, `computedEternity`).
 
 ## Installation
 
@@ -33,22 +35,41 @@ npm install @dxtmisha/functional
 ## Quick Start
 
 ```typescript
-import { useGeoIntlRef, useStorageRef, useApiRef } from '@dxtmisha/functional'
-
+import { ref } from 'vue'
+import {
+  executeUseGlobal,
+  useApiManagementRef,
+  useStorageRef,
+  useGeoIntlRef,
+  t
+} from '@dxtmisha/functional'
+
+// 1. Decoupled API & state singleton service
+export const useUserManagement = executeUseGlobal(() => {
+  return useApiManagementRef(
+    { path: '/api/users' },                       // GET list endpoint
+    { date: (v) => new Date(v).toLocaleString() }, // Formatters
+    { columns: ['name', 'email'] }                // Search columns
+  )
+})
+
+// 2. Component usage (Composition API)
 export default {
   setup() {
-    // Reactive geolocation and formatting
-    const { country, language, intl } = useGeoIntlRef()
+    // Reactive storage with cross-tab auto-sync
+    const theme = useStorageRef<'light' | 'dark'>('theme', 'dark')
+
+    // Reactive locale-aware formatting
+    const intl = useGeoIntlRef()
+    const formattedPrice = intl.currency(150, 'EUR')
 
-    // Reactive localStorage with auto-sync across tabs
-    const { value: settings, set: setSettings } = useStorageRef('app-settings', {
-      theme: 'dark'
-    })
+    // Reactive translations
+    const labels = t(['global.save', 'global.cancel'])
 
-    // Reactive API requests with caching and loading states
-    const { data, loading, error, reload } = useApiRef('/api/users')
+    // Shared state singleton hook
+    const users = useUserManagement()
 
-    return { intl, settings, setSettings, data, loading }
+    return { theme, intl, formattedPrice, labels, users }
   }
 }
 ```
@@ -56,7 +77,7 @@ export default {
 ## Principles
 
 - **Full Composition API integration** — every utility is designed with Vue 3's reactivity system in mind, heavily utilizing `ref`, `computed`, and lifecycle hooks.
-- **Separation of concerns** — ideologically encourages extracting validation, state management, and side-effects into specialized classes, maintaining "thin" components.
+- **Separation of concerns** — ideologically encourages extracting validation, state management, and side-effects into specialized classes and `executeUse` singletons, maintaining "thin" components.
 - **Type safety** — provides 100% TypeScript type coverage between APIs, storages, and the UI, protecting codebase scaling with smart type inference.
 - **Predictable resource management** — safely manages subscriptions and frees memory. When a component is unmounted, associated tasks and watchers are cleanly terminated.
 
@@ -69,7 +90,7 @@ Full API reference, examples, and guides:
 ## Difference from @dxtmisha/functional-basic
 
 - **`@dxtmisha/functional-basic`** — core utilities, no framework dependencies. Use this with vanilla JS, React, or any non-Vue stack, or when building a library.
-- **`@dxtmisha/functional`** — extends `functional-basic` with Vue 3 composables and reactive wrappers. Use this when building complex Vue / Nuxt applications.
+- **`@dxtmisha/functional`** — extends `functional-basic` with Vue 3 composables, reactive wrappers, state singletons, and component design constructors. Use this when building complex Vue / Nuxt applications.
 
 ## License
 

package/ai-description.md

@@ -1,25 +1,29 @@
-### Core Purpose
-A high-level utility library designed for Vue 3 providing architectural abstractions for component design, reactive state management, sophisticated API orchestration with SSR support, and localized geographic/unit formatting.
-
-### Key Expositions
-*   **Design Architecture:** `DesignConstructorAbstract`, `DesignComponents`, and `DesignAbstract` provide a structured class-based inheritance model for building complex, reactive functional components with automatic lifecycle handling, style/class management, and slotted rendering.
-*   **API Orchestration:**
-    *   `useApiRef`: Centralized reactive API request handler with built-in SSR, caching, transformation, validation (supporting `@effect/schema`), and error handling.
-    *   `useApiManagementRef` / `useApiManagementAsyncRef`: High-level orchestration for CRUD operations (GET/POST/PUT/DELETE) with client-side searching, list formatting, and atomic mutation state management.
-    *   Standard wrappers: `useApiGet`, `useApiPost`, `useApiPut`, `useApiDelete` for cleaner endpoint interaction.
-*   **Reactive Utilities:** 
-    *   `executeUse`: A factory for creating managed singletons (`global`, `provide`, `local`) to ensure unified state across component trees.
-    *   `useTranslateRef`, `useStorageRef`, `useCookieRef`, `useSessionRef`: Reactive bridges to local persistence and internationalization.
-    *   `computedAsync`, `computedEternity`: Advanced reactive primitives for asynchronous data flow and on-demand caching.
-*   **Data Formatting:** `GeoIntlRef`, `GeoUnitRef`, and `useFormattersRef` provide reactive, localized formatting for numbers, currencies, units (metric/imperial conversion), and dates.
-*   **List & Search Logic:** `ListDataRef` and `useSearchRef` manage complex hierarchical or flat data structures with optimized search and filtering capabilities.
-
-### Triggers for Studying ai-types.md
-Mandatory to review `ai-types.md` when:
-1.  **System Integration:** You are implementing new API endpoints, configuring `dxtFunctionalPlugin`, or setting up global state providers (`executeUseProvide`).
-2.  **Schema Validation:** You are utilizing `validateResponseContract` or `validateRequestContract` and require the expected structure for `ApiDataValidation` or error storage interfaces.
-3.  **Component Construction:** You are extending `DesignConstructorAbstract` or implementing custom component modifications.
-4.  **Type Mapping:** You encounter complex generic constraints in the `useApiManagementRef` signature or `Constr` prefixed utility types (e.g., `ConstrBind`, `ConstrOptions`, `ConstrEmit`).
-
-### Integration Context
-The library acts as a foundational service layer in the system stack. It integrates directly with Vue 3's composition API, Vue Router for navigation, and `@dxtmisha/functional-basic` for core network and utility logic. It is intended to be used as a singleton-pattern service provider within an application's plugin system via `dxtFunctionalPlugin` to facilitate consistent SSR state hydration and global dependency injection.
+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.

package/ai-doc.md

@@ -1,112 +1,42 @@
 # @dxtmisha/functional Reference
-
-Vue 3 reactive utilities, composables, and classes built on `@dxtmisha/functional-basic`. Refer to [ai-types.md](file:///Volumes/T7/Code/dxt-ui/packages/functional/ai-types.md) for full signatures, types, and exported methods.
-
----
+Vue 3 reactive utilities built on `@dxtmisha/functional-basic`. See `ai-types.md` for full signatures.
 
 ## Usage Rules & Strategies
-
-1. **Priority**: Always prioritize `@dxtmisha/functional` over `@dxtmisha/functional-basic` in Vue environments.
-2. **API & State (`useApi*` / `executeUse*`)**:
-   - **Never** call `useApiGet`, `useApiPost`, `useApiPut`, `useApiDelete`, `useApiRequest`, `useApiRef`, `useApiAsyncRef`, `useApiManagementRef`, `useApiManagementAsyncRef` directly inside components (SFC).
-   - Move all API configurations into separate files (services/stores).
-   - Wrap setups in `executeUse` factories (`executeUseLocal`, `executeUseGlobal`, `executeUseProvide`) to ensure singletons, prevent duplicate requests, and process data (mappings, skeletons) in the callback.
-   - Components only import/call the singleton hook.
-
-```typescript
-import { executeUseGlobal, useApiManagementRef } from '@dxtmisha/functional';
-
-export const useUserManagement = executeUseGlobal(() => {
-  return useApiManagementRef(
-    { path: '/api/users' },                       // GET
-    { 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
-  );
-});
-```
-
-### `executeUse` Strategies:
-- `executeUseLocal` (Preferred): Lazy-loaded when first called. Persists until session end.
-- `executeUseGlobal`: Eagerly loaded at application startup (useful for critical configs, SDKs). Must be initialized via `executeUseGlobalInit()`.
-- `executeUseProvide`: Scoped via `provide/inject` to a component tree branch (useful for form/tab hierarchies).
-
----
-
-## Key API Examples
-
-### 1. Storage & State (Reactive)
-Reactively syncs Vue refs with browser storages or cross-tab broadcast channels.
-
-```typescript
-import { useStorageRef, useSessionRef, useCookieRef, useBroadcastValueRef, useHashRef } from '@dxtmisha/functional';
-
-const theme = useStorageRef<'light' | 'dark'>('theme_key', 'light');
-const step = useSessionRef<number>('form_step', 1);
-const token = useCookieRef<string>('auth_token', '', { secure: true });
-const syncState = useBroadcastValueRef<string>('active_channel', 'idle');
-const hashPage = useHashRef<string>('page', 'home');
-```
-
-### 2. Geolocation & Internationalization
-Static helpers and reactive wrappers for localization and translation.
+- **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 { GeoRef, useGeoIntlRef, useTranslateRef } from '@dxtmisha/functional';
-
-const currentCountry = GeoRef.getCountry();
-const intl = useGeoIntlRef();
-const formattedPrice = intl.currency(150, 'EUR');
-const translations = useTranslateRef(['global.save', 'global.cancel']); // Or alias `t(...)`
-```
-
-### 3. SEO & Layout Utilities
-Metadata manager and reactive scrollbar tracker to solve layout shifts.
-
-```typescript
-import { useMeta, ScrollbarWidthRef } from '@dxtmisha/functional';
-
-const meta = useMeta();
-meta.setTitle('Product Page');
-
-const scrollbar = new ScrollbarWidthRef();
-const w = scrollbar.width;
-const hasScroll = scrollbar.is;
-```
-
-### 4. Advanced Reactivity Helpers
-Helpers for resolving async data reactively or caching computations.
-
-```typescript
-import { computedAsync, computedEternity } from '@dxtmisha/functional';
-
-const asyncData = computedAsync(async () => await fetchSomeData(activeId.value), 'loading...');
-const cachedData = computedEternity(async () => await fetchStaticData(), 'loading...');
-```
-
-### 5. List & Search Orchestration
-Orchestrates list state (selection, pagination, highlights) and performs debounced list searches.
-
-```typescript
-import { ListDataRef, useSearchRef } from '@dxtmisha/functional';
-
-const listData = new ListDataRef(items, selectedId);
-const isSelected = listData.isSelected;
-const nextItem = listData.getSelectedNext();
-
-const query = ref('search_term');
-const { listSearch, loading, length } = useSearchRef(items, ['label'], query);
-```
-
-### 6. DOM & Lazy Rendering
-Lifecycle-aware event listeners and IntersectionObserver wrappers.
-
-```typescript
-import { EventRef, useLazyRef } from '@dxtmisha/functional';
-
-const keyListener = new EventRef(window, window, 'keydown', (e) => console.log(e.key));
-const lazyManager = useLazyRef();
-const isVisible = lazyManager.addLazyItem(elementRef);
+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'));
+
+// 7. DOM Events & Lazy
+const listener = new EventRef(window, window, 'keydown', (e) => console.log(e.key));
+const lazy = useLazyRef(); lazy.addLazyItem(elementRef);
 ```