@dxtmisha/functional 1.15.3 → 1.15.6

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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

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,7 @@
-### 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.
+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,112 +1,8 @@
 # @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.
-
-```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);
-```
+## 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');
+```