@dxtmisha/functional-basic 1.8.10 → 1.10.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.10.1] - 2026-08-30
+
+### Added
+- **Documentation**:
+  - Migrated package documentation to `src/storybook/` with comprehensive guides across English, Russian, and Vietnamese.
+
+### Changed
+- **Build Configuration**:
+  - Migrated `vite.config.ts` to use `viteBasicFunction()` from `@dxtmisha/configuration`.
+- **AI Type Definitions & Resources**:
+  - Reorganized `ai-types-list/` structure to mirror `src/` directory layout.
+  - Updated `design-config.json` resource metadata descriptor in `ai-types-list/resources/`.
+
+## [1.10.0] - 2026-08-30
+
+### Added
+- **Geo Country Management (`Geo` / `GeoInstance`)**:
+  - Added `add(country: string, item: Partial<GeoItem>)` and `addList(list: Record<string, Partial<GeoItem>>)` methods to dynamically register and merge custom country configurations into the geo registry.
+  - Initialized internal country list directly from the `@dxtmisha/media` dataset, making `getList()` dynamic.
+  - Added unit test coverage for `GeoInstance.add`, `GeoInstance.addList`, `Geo.add`, and `Geo.addList`.
+- **AI Resources**:
+  - Added `error-center.md` architecture guide in `ai-resources/` and metadata descriptor in `ai-types-list/resources/error-center.json`.
+
+## [1.9.0] - 2026-08-24
+
+### Added
+- **`getImageSrc`**: Utility function to safely extract the image source string from `HTMLImageElement`, string URL, or `undefined`.
+- **`resizeImage`**: Asynchronous utility function to scale down images that exceed a maximum size constraint (`maxSize`) returning a Data URL or the original source string.
+- **Unit Tests**: Added test suites for `getImageSrc` and `resizeImage`.
+- **Documentation**: Added MDX documentation and usage examples across English, Russian, and Vietnamese.
+- **AI Types**: Generated type definitions for `getImageSrc` and `resizeImage`.
+
 ## [1.8.10] - 2026-08-20
 
 ### Changed

package/ai-description.md

@@ -1,6 +1,13 @@
-This package is a comprehensive utility library designed for web applications, providing robust core functions for API requests, caching, internationalization (Geo/Intl), state management, DOM manipulation, and SEO metadata control. An AI assistant must study this file when implementing or refactoring features related to HTTP communication, localized data formatting, browser storage, query/hash state synchronization, or search filtering to ensure adherence to established patterns and type definitions.
+### Package Description
+A comprehensive isomorphic utility framework providing client/SSR HTTP client management, locale-aware internationalization, data caching, storage abstraction, DOM event handling, search filtering, and SEO metadata orchestration.
 
-Key Capabilities: API Integration, Request Caching, Internationalization, Cookie Management, Local Storage, URL State, DOM Utilities, Meta Tags, Search Matching, Error Handling
+### Triggers for Studying ai-types.md
+Study `ai-types.md` when configuring or executing HTTP requests, handling SSR hydration, setting up request/response interceptors or mock emulators (`Api`, `ApiFetch`, `ApiResponse`, `ApiPreparation`, `ApiHeaders`), managing persistent and session storage across DOM and server runtimes (`CookieStorage`, `DataStorage`, `ServerStorage`), implementing localized formatting for dates, currencies, numbers, units, or phone numbers (`Geo`, `GeoIntl`, `GeoUnit`, `GeoPhone`, `Datetime`), configuring i18n translation batching or file loaders (`Translate`, `TranslateFile`), setting up centralized error handling (`ErrorCenter`), binding resilient DOM listeners or resize/scroll observers (`EventItem`), building regex-based searchable lists and highlighted match views (`SearchList`, `Formatters`), managing Open Graph and Twitter Card SEO tags (`Meta`, `MetaOg`, `MetaTwitter`), or synchronizing state with URL hash and query parameters (`Query`, `Hash`, `UrlItem`).
+
+### Key Capabilities
+HTTP Client Integration, API Response Caching, SSR State Hydration, Isomorphic Cookie Storage, Web Storage Abstraction, Locale Internationalization, Datetime Manipulation, Multi Unit Conversion, Phone Number Masking, I18n Translation Management, Centralized Error Handling, DOM Event Management, Search Filtering, Match Highlighting, URL State Synchronization, SEO Meta Management, Cross Tab Messaging, Global Loading Tracking
 ## Mandatory Rules
 You MUST evaluate whether your task relates to any of the following topics (even if not working directly with this package). If related material is present, you are strictly obligated to read and study the corresponding file before proceeding:
-- 'node_modules/@dxtmisha/functional-basic/ai-resources/api-reference.md': Provides code examples and usage patterns for HTTP clients, caching, data storage, localization, and DOM helpers from the @dxtmisha/functional-basic library. Guides AI assistants on how to properly implement core functional utilities in TypeScript applications.
+- 'node_modules/@dxtmisha/functional-basic/ai-resources/api-reference.md': Comprehensive API reference and code examples for the @dxtmisha/functional-basic utility package. Covers HTTP networking, client/server storage, internationalization, DOM utilities, and general helper functions. Streamlines common frontend and SSR development tasks including state persistence, API integration, and formatting.
+- 'node_modules/@dxtmisha/functional-basic/ai-resources/design-config.md': Specification and configuration reference for design.config.json across DXT UI packages and monorepo roots. Defines rules for configuration inheritance, TypeScript declaration scanning, AI provider integrations, and documentation generation. Standardizes build parameters and toolchain automation across packages.
+- 'node_modules/@dxtmisha/functional-basic/ai-resources/error-center.md': Defines mandatory error management standards and API rules using ErrorCenter in @dxtmisha/functional-basic. Prohibits direct console logging and enforces structured error dispatching across all application domains. Guides error registration, custom group handlers, and external telemetry integration.

package/ai-mcp-resources.json

@@ -13,8 +13,20 @@
   },
   {
     "uri": "@dxtmisha/functional-basic/ai-resources/api-reference.md",
-    "name": "API Reference And Examples (@dxtmisha/functional-basic)",
+    "name": "Functional Basic API Reference (@dxtmisha/functional-basic)",
     "mimeType": "text/markdown",
-    "description": "Provides code examples and usage patterns for HTTP clients, caching, data storage, localization, and DOM helpers from the @dxtmisha/functional-basic library. Guides AI assistants on how to properly implement core functional utilities in TypeScript applications."
+    "description": "Comprehensive API reference and code examples for the @dxtmisha/functional-basic utility package. Covers HTTP networking, client/server storage, internationalization, DOM utilities, and general helper functions. Streamlines common frontend and SSR development tasks including state persistence, API integration, and formatting."
+  },
+  {
+    "uri": "@dxtmisha/functional-basic/ai-resources/design-config.md",
+    "name": "Design Config Guide (@dxtmisha/functional-basic)",
+    "mimeType": "text/markdown",
+    "description": "Specification and configuration reference for design.config.json across DXT UI packages and monorepo roots. Defines rules for configuration inheritance, TypeScript declaration scanning, AI provider integrations, and documentation generation. Standardizes build parameters and toolchain automation across packages."
+  },
+  {
+    "uri": "@dxtmisha/functional-basic/ai-resources/error-center.md",
+    "name": "Centralized Error Handling Guide (@dxtmisha/functional-basic)",
+    "mimeType": "text/markdown",
+    "description": "Defines mandatory error management standards and API rules using ErrorCenter in @dxtmisha/functional-basic. Prohibits direct console logging and enforces structured error dispatching across all application domains. Guides error registration, custom group handlers, and external telemetry integration."
   }
 ]

package/ai-resources/design-config.md

@@ -0,0 +1,104 @@
+# `design.config.json` Configuration Guide
+
+Configuration specification for DXT UI packages and monorepo root.
+
+---
+
+## 1. Overview & Inheritance Mechanism
+
+`design.config.json` configures design system parameters, type scanning, AI generation, and wiki generation.
+
+- **Inheritance via `extends`**: Packages extend parent configs using relative paths (`"extends": "../../design.config.json"`).
+- **Merging Strategy**: Recursive shallow merge. Properties in child configs override inherited parent values.
+- **Search Order**: Tools look for `design.config.json` in the current working directory, then scan up the directory tree up to 32 levels.
+
+---
+
+## 2. Property Reference
+
+- `extends` (`string`): Relative path to parent configuration file to inherit from (e.g. `"../../design.config.json"`).
+- `project` (`string`, default: `'ui'`): Project / namespace identifier (e.g. `"Ui"`, `"Basic"`), used in component prefixes and story paths.
+- `name` (`string`, default: `'ui'`): Design system package name (e.g. `"d1"`, `"functional-basic"`).
+- `alternativeName` (`string[]`): Array of alternative aliases or abbreviations for the design system.
+- `typesPaths` (`string[]`, default: `['src']`): Whitelist of directory paths to scan for TypeScript declarations during `dxt-types`.
+- `typesMatch` (`string | string[]`): Regex or substring patterns to include in declaration scanning.
+- `typesExclude` (`string | string[]`): Regex or substring patterns to exclude from declaration scanning (e.g. `["\\.wiki\\.d\\.ts$", "wiki/", "library/"]`).
+- `typesWithoutVue` (`boolean`, default: `false`): When `true`, skips Vue SFC scanning and forces standard `tsc` compilation instead of `vue-tsc`.
+- `typesDir` (`string`, default: `'ai-types-temp'`): Directory path for temporary TypeScript declarations compilation.
+- `distDir` (`string`, default: `'dist'`): Output directory path for compiled JavaScript files.
+- `aiResourcesDir` (`string`, default: `'ai-resources'`): Directory path containing AI resource and prompt files.
+- `promptScanDepth` (`number`, default: `6`): Maximum directory scan depth for collecting AI prompt packages.
+- `separator` (`string`, default: `'/'`): Token path delimiter used when splitting design tokens into sub-branches.
+- `separatorBasicName` (`string`): Base token name stripped during branch segmentation.
+- `separatorLimit` (`number`): Maximum recursion depth for token key splitting.
+- `wikiLanguage` (`string`, default: `'en'`): Target localization language code for wiki and Storybook docs (e.g. `'ru'`, `'en'`).
+- `packagePrefix` (`string`): Monorepo scope prefix for package imports (e.g. `'@dxtmisha'`).
+- `aiType` (`AiType`): AI backend provider (`'claude'`, `'claude-cli'`, `'claude-agent'`, `'gemini'`, `'gemini-cli'`, `'openai'`, `'zai'`).
+- `aiModel` (`string`): Specific model identifier (e.g. `'gemini-3.7-flash'`, `'gpt-4o'`).
+- `aiKey` (`string`): API key or token for AI provider.
+- `aiConfig` (`Record<string, any>`, default: `{}`): Provider-specific options (temperature, tokens, headers).
+- `aiTypesConcurrency` (`number`, default: `8`): Maximum number of type definition files processed by AI concurrently.
+- `figmaToken` (`string`): Personal access token for Figma REST API integration.
+
+---
+
+## 3. Full Configuration Example
+
+Complete `design.config.json` incorporating all available configuration properties:
+
+```json
+{
+  "extends": "../../design.config.json",
+  "project": "Ui",
+  "name": "d1",
+  "alternativeName": [
+    "dd"
+  ],
+  "typesPaths": [
+    "src/components"
+  ],
+  "typesMatch": [
+    "Button",
+    "Input"
+  ],
+  "typesExclude": [
+    "\\.wiki\\.(d\\.)?ts$",
+    "wiki\\.(d\\.)?ts$",
+    "wikiData\\.(d\\.)?ts$",
+    "wiki/",
+    "library/"
+  ],
+  "typesWithoutVue": true,
+  "typesDir": "ai-types-temp",
+  "distDir": "dist",
+  "aiResourcesDir": "ai-resources",
+  "promptScanDepth": 6,
+  "separator": "/",
+  "separatorBasicName": "basic",
+  "separatorLimit": 3,
+  "wikiLanguage": "ru",
+  "packagePrefix": "@dxtmisha",
+  "aiType": "gemini",
+  "aiModel": "gemini-3.7-flash",
+  "aiKey": "AIzaSy...",
+  "aiConfig": {
+    "temperature": 0.2
+  },
+  "aiTypesConcurrency": 8,
+  "figmaToken": "figd_..."
+}
+```
+
+---
+
+## 4. Operational Guidelines for AI Assistants
+
+1. **Always extend root**: Child package configs must define `"extends": "../../design.config.json"` unless creating a standalone root.
+2. **Pure TS packages**: Always set `"typesWithoutVue": true` in non-Vue packages to prevent unnecessary `vue-tsc` invocations.
+3. **Filtering declarations**: Use `typesExclude` with regex patterns (`"\\.wiki\\.d\\.ts$"`, `"wiki/"`) to keep `ai-types.md` clean of internal build artifacts.
+4. **Accessing in code**: In scripts, read configuration through the static accessor `PropertiesConfig`:
+   ```typescript
+   import { PropertiesConfig } from '../Properties/PropertiesConfig'
+   const isExcluded = PropertiesConfig.getTypesExclude()
+   const skipVue = PropertiesConfig.isTypesWithoutVue()
+   ```

package/ai-resources/error-center.md

@@ -0,0 +1,150 @@
+# Centralized Error Handling Guide (`ErrorCenter`)
+
+Mandatory instructions for AI coding assistants on error management in `@dxtmisha/functional-basic`.
+
+---
+
+## 1. 🔴 Mandatory Rule: Zero Direct Console Logging
+
+> **STRICT PROHIBITION**: Direct error logging via `console.error()`, `console.warn()`, or `console.log()` is **FORBIDDEN** across all library and application code.
+> **MANDATORY**: Every caught exception, validation failure, network error, or unexpected state **MUST** be routed strictly through `ErrorCenter.on(...)`.
+
+---
+
+## 2. Core Architecture
+
+`ErrorCenter` is a static facade (bridge) that delegates all operations to `ErrorCenterInstance`.
+
+```typescript
+import { ErrorCenter, type ErrorCenterInstance } from '@dxtmisha/functional-basic';
+
+// 1. Static global access
+ErrorCenter.on({ group: 'api', code: 'timeout' });
+
+// 2. Class Dependency Injection (DI) pattern
+export class MyService {
+  constructor(
+    private errorCenter: ErrorCenterInstance = ErrorCenter.getItem()
+  ) {}
+
+  doAction() {
+    try {
+      // logic
+    } catch (e) {
+      this.errorCenter.on({ group: 'storage', code: 'error', details: e });
+    }
+  }
+}
+```
+
+---
+
+## 3. Error Structure (`ErrorCenterCauseItem`)
+
+| Property | Type | Required | Description |
+|---|---|:---:|---|
+| `group` | `string \| undefined` | No | Domain category (`'api'`, `'intl'`, `'storage'`, `'auth'`, etc.). |
+| `code` | `string` | **Yes** | Unique error code identifier within the group. |
+| `priority` | `number` | No | Merge priority (default `500`). Higher priority overrides lower. |
+| `label` | `string` | No | Short human-readable title / header. |
+| `message` | `string` | No | Descriptive error message. |
+| `details` | `unknown` | No | Raw error payload (Error instance, response data, context). |
+
+---
+
+## 4. Triggering Errors (`ErrorCenter.on`)
+
+Use `ErrorCenter.on(...)` whenever handling exceptions or error conditions:
+
+```typescript
+import { ErrorCenter } from '@dxtmisha/functional-basic';
+
+// Try/Catch handling
+try {
+  JSON.parse(invalidJsonString);
+} catch (error) {
+  ErrorCenter.on({
+    group: 'transformation',
+    code: 'error',
+    details: error
+  });
+}
+
+// Custom domain error with payload
+if (!isUserAuthorized) {
+  ErrorCenter.on({
+    group: 'auth',
+    code: 'unauthorized',
+    message: 'Session has expired.',
+    details: { userId: '123' }
+  });
+}
+```
+
+---
+
+## 5. Built-in Standard Error Groups & Codes
+
+Pre-registered in `errorCauseList` (no manual registration needed):
+
+| Group | Codes | Description |
+|---|---|---|
+| `api` | `forbidden` (403), `notFound` (404), `offline`, `server` (500), `timeout`, `unauthorized` (401), `unknown`, `cacheClear`, `cacheGet`, `cacheRemove`, `cacheSet` | HTTP requests & API cache failures |
+| `intl` | `datetime`, `display`, `number`, `plural`, `relative`, `invalid` | Internationalization & date parsing errors |
+| `storage` | `context`, `error` | `DataStorage`, `CookieStorage`, `ServerStorage` |
+| `broadcast` | `error` | Cross-tab `BroadcastChannel` communication |
+| `clipboard` | `error` | Clipboard read / write operations |
+| `hydration` | `error` | Server / client state hydration mismatches |
+| `share` | `error` | Web Share API errors |
+| `transformation` | `error` | Data serialization / parsing errors |
+| `translate` | `error` | Localization dictionary loading |
+
+---
+
+## 6. Registration & Handlers
+
+### 6.1 Registering Custom Causes (`add` / `addList`)
+Store error templates in advance to keep code clean and decoupled:
+```typescript
+ErrorCenter.add({
+  group: 'payment',
+  code: 'INSUFFICIENT_FUNDS',
+  label: 'Payment Failed',
+  message: 'You have insufficient funds to complete this transaction.'
+});
+
+ErrorCenter.addList([
+  { group: 'upload', code: 'TOO_LARGE', label: 'File Too Large', message: 'Max size is 10MB.' }
+]);
+```
+
+### 6.2 Group Handlers (`addHandler` / `addHandlerList`)
+Subscribe to specific groups (e.g., to trigger UI toasts or alerts):
+```typescript
+ErrorCenter.addHandler('api', (cause) => {
+  showToast(cause.label || 'Network Error', cause.message);
+});
+
+// Fallback handler for unassigned groups
+ErrorCenter.addHandler(undefined, (cause) => {
+  showToast('Error', cause.message);
+});
+```
+
+### 6.3 Universal Telemetry Callback (`addCallback`)
+Invoked on **every** error event (ideal for Sentry, Datadog, logging services):
+```typescript
+ErrorCenter.addCallback((cause) => {
+  Sentry.captureException(cause.details || new Error(cause.message), {
+    tags: { group: cause.group, code: cause.code },
+    extra: cause
+  });
+});
+```
+
+### 6.4 Console Output Control (`setIsConsole`)
+Control automatic console logging (supports boolean or filter callback):
+```typescript
+ErrorCenter.setIsConsole(false); // Disable console logging completely
+ErrorCenter.setIsConsole((cause) => cause.group !== 'analytics'); // Conditional filter
+```