@dxtmisha/functional-basic 1.8.10 → 1.10.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.10.0] - 2026-08-30
+
+### Added
+- **Geo Country Management (`Geo` / `GeoInstance`)**:
+  - Added `add(item: GeoItem)` and `addList(list: 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`.
+- **Documentation**:
+  - Migrated package documentation to `src/storybook/` with comprehensive guides across English, Russian, and Vietnamese.
+
+## [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,10 @@
-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.
+An isomorphic TypeScript utility library that provides core infrastructure for HTTP client requests, SSR state hydration, internationalization, and client-side data management. It offers robust tools for URL state handling, DOM events, localization formatting, and error tracking across browser and server environments.
 
-Key Capabilities: API Integration, Request Caching, Internationalization, Cookie Management, Local Storage, URL State, DOM Utilities, Meta Tags, Search Matching, Error Handling
+Study ai-types.md when configuring or executing HTTP requests, fetch interceptors, API caching, or SSR hydration; managing cookies, session/local storage, or request-isolated server storage; implementing internationalization, multi-language translations, locale-aware date/time calculations, phone masks, or unit conversions; manipulating URL query parameters and hash routing state; managing SEO meta tags, Open Graph, and Twitter Cards; building searchable list filters with text match highlighting; handling centralized application errors, global loading state, cross-tab broadcast messaging, or DOM event observation and helper utilities.
+
+Key Capabilities: HTTP Client Management, API Response Caching, SSR State Hydration, Centralized Error Handling, Internationalization Formatting, Geographic Localization, Datetime Manipulation, Phone Dialing Masks, Unit Measurement Conversion, Translation Services, Cookie Management, Isomorphic Storage Isolation, URL State Synchronization, Query Parameter Handling, Hash State Routing, SEO Meta Management, Open Graph Tags, Twitter Card Metadata, Search List Filtering, Text Match Highlighting, DOM Event Control, Global Loading Tracking, Cross-Tab Messaging, Image Resizing Utilities, Clipboard Integration, Data Transformation
 ## 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': Defines configuration schemas, inheritance rules, and property references for design.config.json files across DXT UI monorepo packages. It standardizes settings for TypeScript declaration scanning, AI providers, Figma integration, and wiki generation. Serves as the operational guide for setting up design tokens and automated tooling workflows.
+- '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 Specification (@dxtmisha/functional-basic)",
+    "mimeType": "text/markdown",
+    "description": "Defines configuration schemas, inheritance rules, and property references for design.config.json files across DXT UI monorepo packages. It standardizes settings for TypeScript declaration scanning, AI providers, Figma integration, and wiki generation. Serves as the operational guide for setting up design tokens and automated tooling workflows."
+  },
+  {
+    "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
+```