@dxtmisha/functional-basic 1.2.8 → 1.3.3

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.1] - 2026-05-25
+
+### Changed / Improved
+- **Maintenance**: Incremented version to `1.3.1` to align with monorepo release updates.
+
+## [1.3.0] - 2026-05-25
+
+### Added
+- **`getLength`**: Introduced a new `getLength` utility function to determine the length/size of strings, arrays, Maps, Sets, and objects reactively and safely, accompanied by complete bilingual JSDocs.
+- **Tests**: Created a comprehensive unit test suite (`getLength.test.ts`) to validate length computation across all supported data types.
+
+### Changed / Improved
+- **Build System**: Added `ui-priority: 100` attribute to `package.json` to facilitate prioritized build sorting of foundational libraries.
+
+## [1.2.11] - 2026-05-25
+
+### Changed / Improved
+- **Tests**: Configured the vitest runner command to execute with `NODE_OPTIONS="--no-webstorage"` in `package.json` to prevent environment-related web storage warnings.
+
+## [1.2.10] - 2026-05-24
+
+### Added
+- **isTab**: Introduced `isTab` utility function to reliably detect Tab key presses across different browser environments by checking `key`, `code`, and `keyCode`.
+- **isTab**: Added comprehensive unit tests in `src/functions/__tests__/isTab.test.ts` to verify tab-detection behavior under multiple key configurations.
+
+### Changed / Improved
+- **isInput**: Refactored `isInput` helper to correctly return `false` for elements with `readonly` or `disabled` attributes.
+- **getKey**: Updated return type of `getKey` helper function to return `string | number | undefined` instead of forcing a strict `string`.
+- **ErrorCenter**: Enhanced `ErrorCenterCauseItem` type inside `errorCenter.ts` with generic parameter support (`ErrorCenterCauseItem<D = any>`) to support strictly-typed structures for error cause detail records.
+- **Maintenance**: Excluded auto-generated AI description files from package assets, standardized type outputs and version bumped to `1.2.10`.
+
 ## [1.2.5] - 2026-05-17
 
 ### Changed / Improved

package/ai-description.txt

@@ -1,5 +1,14 @@
-This library is a high-level isomorphic utility suite for frontend application development, specifically optimized for Server-Side Rendering (SSR) environments. Its core purpose is to provide a standardized, context-isolated architecture for HTTP transport, internationalization (i18n), error management, metadata control, and DOM state synchronization.
+Core Purpose
+A comprehensive, framework-agnostic utility library designed to simplify common frontend development tasks, including HTTP API communication (with caching and SSR hydration), state management (cookies, local/session storage), internationalization (Geo, Datetime, Translation), and DOM/Event management.
 
-Study this library's API when implementing standardized Fetch-based request logic featuring built-in caching, jittered retries, and automated SSR hydration; managing dynamic SEO metadata (Open Graph and Twitter Cards) with DOM-synchronization; or implementing complex locale-aware data formatting including currencies, relative times, and country-specific phone masks. It is indispensable for handling SSR data isolation via specialized storage abstractions (ServerStorage, DataStorage) and for executing high-performance client-side search with regex-based match highlighting. The library also provides advanced lifecycle management for DOM events, including specialized observers for element resizing and scroll-sync optimizations.
+Usage Scenarios
+Study this library when you need:
+1. Robust API Integration: Standardized fetching, request cancellation (AbortController), automated error handling/retry logic, and response caching.
+2. SSR Data Synchronization: Managing data consistency between server and client via hydration scripts.
+3. Feature-Rich State Persistence: Handling cookies (with SameSite/Secure options) and browser storage (with TTL/caching capabilities).
+4. Complex DOM/UI Logic: Managing event listeners with lifecycle auto-cleanup, scrollbar width calculations, and global loading state management.
+5. Localization/I18n: Handling currency, date formatting, and translation file loading dynamically.
+6. Search Functionality: Implementing client-side search with regex matching and highlight formatting for list data.
 
-Technically, it acts as an abstracted transport and utility layer between native Web APIs (Fetch, Intl, BroadcastChannel, ResizeObserver) and application-level logic. It facilitates data consistency between server and client through script-based hydration and provides a centralized ErrorCenter for standardized fault handling across disparate application modules.
+Integration Context
+This library acts as a foundational "glue" layer. It is built using native Web APIs (Fetch, BroadcastChannel, ResizeObserver, Intl) and is intended to be initialized globally. It provides abstract classes that can be extended or injected to fit various architectures (e.g., SSR frameworks like Nuxt or Next.js, or standard SPA setups). It centralizes configuration for API paths, translation endpoints, and geo-data, serving as a unified utility core for the application.

package/ai-doc.ru.txt

@@ -1,5 +1,54 @@
-Это базовая функциональная библиотека (@dxtmisha/functional-basic). Здесь собраны алгоритмы, утилиты и классы, независимые от фреймворка.
+Esto базовая функциональная библиотека (@dxtmisha/functional-basic). Здесь собраны алгоритмы, утилиты и классы, независимые от фреймворка.
 
 ВНИМАНИЕ ДЛЯ СРЕДЫ VUE:
 Если вы разрабатываете под Vue, СНАЧАЛА всегда ищите нужный функционал (composables, реактивные классы) в библиотеке `@dxtmisha/functional`.
 И ТОЛЬКО если там нет нужного реактивного/специфичного для Vue аналога, используйте функционал напрямую из этой библиотеки (@dxtmisha/functional-basic).
+
+=============================================================================
+СТРУКТУРА КЛАССОВ И СТАНДАРТЫ КОДА (ПРАВИЛА ДЛЯ AI)
+=============================================================================
+
+Для обеспечения согласованности и высокого промышленного качества кодовой базы dxt-ui, все классы TypeScript внутри `@dxtmisha/functional-basic` должны строго следовать следующим правилам относительно структуры, порядка членов и стилей.
+
+1. ПОРЯДОК ЧЛЕНОВ ВНУТРИ КЛАССА
+Члены каждого класса ДОЛЖНЫ быть упорядочены в следующей последовательности:
+
+   А. Свойства класса / Переменные-члены:
+      - Располагаются в самом верху тела класса.
+      - Сортируются по видимости: сначала Public, затем Protected и в конце Private.
+      - Внутри каждого уровня видимости группируются по смыслу или по алфавиту.
+      - Инициализируйте значения по умолчанию прямо при объявлении, если это возможно.
+
+   Б. Конструктор:
+      - Располагается сразу после объявлений всех свойств.
+      - Разрешено объявление свойств через параметры конструктора (например, `protected url: string`) для упрощения кода.
+
+   В. Публичные методы (Public Methods):
+      - Располагаются после конструктора.
+      - Группируются логически:
+        1. Геттеры, методы проверки состояния и статуса (например, `is*`, `get*`).
+        2. Сеттеры и методы конфигурации (например, `set*`).
+        3. Основные методы выполнения и экшены (например, `request()`, `fetch()`, `show()`).
+
+   Г. Защищенные методы (Protected Methods):
+      - Располагаются после всех публичных методов.
+      - Содержат внутреннюю вспомогательную логику, доступную для наследников класса.
+
+   Д. Приватные методы (Private Methods):
+      - Располагаются в самом конце класса.
+      - Строгая инкапсуляция внутренней логики.
+
+2. СТИЛЬ И СОГЛАШЕНИЯ ПО НАПИСАНИЮ КОДА
+   - Именование:
+     * Классы: PascalCase (например, `LoadingInstance`).
+     * Методы и свойства: camelCase (например, `registrationEvent`, `registrationList`).
+     * Константы внутри файлов: UPPER_SNAKE_CASE (например, `LOADING_EVENT_NAME`).
+   - Безопасность TypeScript:
+     * Никогда не используйте тип `any`. Используйте дженерики или `unknown`, если тип динамический/неопределенный.
+     * Явно указывайте возвращаемые типы для ВСЕХ публичных, защищенных и приватных методов (включая `void`).
+     * Используйте интерфейсы/типы для определения структурных контрактов сложных входящих и исходящих данных.
+   - SSR Изоляция (Server-Side Rendering):
+     * Библиотека должна быть полностью изоморфной и безопасной для SSR.
+     * Избегайте прямого хранения специфичного для запроса состояния в глобальных/статических свойствах классов.
+     * Используйте `ServerStorage.get('key', () => new Instance())` для синглтонов, изолированных в рамках запроса.
+     * Используйте проверку `isDomRuntime()` перед обращением к браузерным API, таким как `window`, `document` или `location`.

package/ai-doc.txt

@@ -1,5 +1,54 @@
 This is the basic functional library (@dxtmisha/functional-basic). It contains framework-agnostic algorithms, utilities, and classes.
 
-ATTENTION FOR VUE ENVIROMENT:
+ATTENTION FOR VUE ENVIRONMENT:
 If you are developing in Vue, ALWAYS look for the required functionality (composables, reactive wrappers) inside the `@dxtmisha/functional` library FIRST.
 And ONLY if there is no reactive or Vue-specific analog there, you may use the functionality directly from this library (@dxtmisha/functional-basic).
+
+=============================================================================
+CLASS STRUCTURE & CODING STANDARDS (RULES FOR AI)
+=============================================================================
+
+To maintain consistency and high industrial quality across the dxt-ui codebase, all TypeScript classes inside `@dxtmisha/functional-basic` must strictly adhere to the following rules regarding structure, member ordering, and styles.
+
+1. ORDER OF MEMBERS WITHIN A CLASS
+Members in every class MUST be ordered in the following sequence:
+
+   A. Class Properties / Member Variables:
+      - Placed at the very top of the class body.
+      - Ordered by visibility: Public first, then Protected, and Private last.
+      - Within each visibility level, group by logical connection or alphabetically.
+      - Initialize default values directly on declaration when possible.
+
+   B. Constructor:
+      - Placed immediately after all property declarations.
+      - Parameter properties (e.g., `protected url: string`) are allowed to simplify declaration.
+
+   C. Public Methods:
+      - Placed after the constructor.
+      - Grouped logically:
+        1. Getters, checkers, and status-check methods (e.g., `is*`, `get*`).
+        2. Setters and configuration methods (e.g., `set*`).
+        3. Core executors and action methods (e.g., `request()`, `fetch()`, `show()`).
+
+   D. Protected Methods:
+      - Placed after all public methods.
+      - Contain internal utility and helper logic accessible to subclasses.
+
+   E. Private Methods:
+      - Placed at the very end of the class.
+      - Strict encapsulation of internal logic.
+
+2. CODING & STYLE CONVENTIONS
+   - Naming:
+     * Classes: PascalCase (e.g., `LoadingInstance`).
+     * Methods & Properties: camelCase (e.g., `registrationEvent`, `registrationList`).
+     * Constants inside files: UPPER_SNAKE_CASE (e.g., `LOADING_EVENT_NAME`).
+   - TypeScript Safety:
+     * Never use `any`. Use generic parameters or `unknown` if the type is dynamic/undefined.
+     * Explicitly declare return types for ALL public, protected, and private methods (including `void`).
+     * Use interfaces/types to define structural contracts for complex inputs and outputs.
+   - SSR Isolation (Server-Side Rendering):
+     * The library must be fully isomorphic and safe for SSR.
+     * Avoid storing request-specific state in global/static class properties directly.
+     * Use `ServerStorage.get('key', () => new Instance())` for request-isolated singletons.
+     * Use `isDomRuntime()` checks before accessing browser-only APIs like `window`, `document`, or `location`.