@reforgium/internal 1.0.1 → 1.1.0

package/README.md

@@ -6,42 +6,255 @@
 **Core infrastructure package for Angular (20+) applications.**
 
 `@reforgium/internal` is a foundational layer that sits *under* feature libraries and applications.  
-It provides shared models, DI tokens, and low-level utilities designed for reuse, consistency, and long-term maintainability.
+It provides shared models, typed DI tokens, and low-level utilities designed for reuse, consistency, and long-term maintainability.
 
 This package is **not** a UI kit and **not** a framework replacement.  
 It is a **stable internal contract** for building scalable Angular systems.
 
 ---
 
-## 🎯 Purpose
+## Why
 
 - Centralize shared domain primitives
-- Avoid cross-package circular dependencies
-- Keep feature and UI layers clean
+- Prevent cross-package circular dependencies
+- Keep feature/UI layers clean
 - Enable aggressive tree-shaking and dead-code elimination
-- Serve as a reusable internal base across multiple libraries and apps
+- Provide a reusable internal base across multiple libraries and apps
 
 ---
 
-## 🚀 What’s Inside
+## What’s inside
 
-### 📦 Core Modules
+- **Models** — shared domain models, interfaces, and value objects
+- **Tokens** — typed DI tokens for configuration and infrastructure contracts
+- **Utilities** — framework-agnostic helpers and low-level utilities (including Signal-friendly helpers)
 
-- **[Models](src/models/README.md)**  
-  Shared domain models, interfaces, and value objects.
+> It’s the bedrock, not the building.
 
-- **[Tokens](src/tokens/README.md)**  
-  Typed DI tokens for configuration, environment, and infrastructure contracts.
+---
+
+## Install
+
+```bash
+npm i @reforgium/internal
+```
+
+---
+
+# Public API
+
+## Models
+
+### Component models (`components.ts`)
+
+#### `Appearance`
+Preset UI appearance tokens.
+
+```ts
+import type { Appearance } from '@reforgium/internal';
+
+const appearance: Appearance = 'primary';
+```
+
+#### `SelectOption`
+Basic select option shape: `{ label: string; value: string | number }`.
+
+```ts
+import type { SelectOption } from '@reforgium/internal';
+
+const options: SelectOption[] = [
+  { label: 'Admin', value: 'admin' },
+  { label: 'User', value: 'user' },
+];
+```
+
+#### `SelectIconOption extends SelectOption`
+Select option with an icon: `icon: string`.
+
+```ts
+import type { SelectIconOption } from '@reforgium/internal';
+
+const langOptions: SelectIconOption[] = [
+  { value: 'en', label: 'English', icon: 'flag-en' },
+  { value: 'ru', label: 'Рус', icon: 'flag-ru' },
+];
+```
 
-- **[Utilities](src/utils/README.md)**  
-  Framework-agnostic helpers and low-level utilities.
+### Utility types (`util.ts`)
 
+#### `AnyType`
+Compatibility type (similar to `any`) used in low-level helpers.
 
-It’s the **bedrock**, not the building.
+#### `AnyDict`
+Compatibility dict type (similar to `Record<string, any>`) used across infra/helpers.
+
+#### `LiteralOf<T>`
+Returns a union of literal keys of an object type.
+
+```ts
+import type { LiteralOf } from '@reforgium/internal';
+
+type StatusMap = { new: 1; done: 2 };
+type StatusCode = LiteralOf<StatusMap>; // 'new' | 'done'
+```
+
+#### `ValueOf<T>`
+Returns a union of values of an object type.
+
+```ts
+import type { ValueOf } from '@reforgium/internal';
+
+type StatusMap = { new: 1; done: 2 };
+type StatusCode = ValueOf<StatusMap>; // 1 | 2
+```
+
+#### `Nullable<T>`
+Returns a nullable copy of an object type.
+
+```ts
+import type { Nullable } from '@reforgium/internal';
+
+type StatusMap = { new: number; done: number };
+type StatusCode = Nullable<StatusMap>; // { new: number | null; done: number | null }
+```
+
+### API & pagination models (`api.ts`)
+
+- `RestMethods` — `'GET' | 'POST' | 'PUT' | 'DELETE'`
+- `PageableRequest` — `{ page: number; size?: number; sort?: string }`
+- `PageableResponse<T>` — `content: T[]` + paging metadata
+- `ErrorResponse` — `{ errorCode: number; message: string; fields: Record<string, string> }`
+- `QueryParams<T>` — `page?`, `size?`, `sort?`, `filters?: Partial<T>`
+- `Params` — route/query params dict
+
+Example (typing only):
+
+```ts
+import type { PageableRequest, QueryParams } from '@reforgium/internal';
+
+const params: QueryParams<{ role: string }> = {
+  page: 0,
+  size: 20,
+  filters: { role: 'admin' },
+};
+
+const asPageable: PageableRequest = {
+  page: params.page ?? 0,
+  size: params.size,
+  sort: params.sort,
+};
+```
 
 ---
 
-## 📦 Installation
+## Tokens
+The localization system is built around a service that manages translations across different languages and namespaces. It supports:
 
-```bash
-npm install @reforgium/internal
+- Multiple languages (Russian 'ru', Kyrgyz 'kg'/'ky')
+- Namespace-based translation loading
+- Dynamic language switching with persistence
+- Translation caching for performance
+- Parameter interpolation in translations
+- Reactive translation updates using Angular signals
+
+## Utilities
+
+### Dates (`date.utils.ts`)
+
+- `formatDate(date, format = 'yyyy-MM-dd')`
+- `formatToLocaledDate(date)` (ru-RU localized format)
+- `parseToDate(value, format = 'dd.MM.yyyy')`
+- `parseToDatePeriod(value, format = 'dd.MM.yyyy')`
+- `isDatePeriod(value)`
+
+```ts
+import { formatDate, parseToDatePeriod } from '@reforgium/internal';
+
+formatDate(new Date(2025, 0, 2), 'dd.MM.yyyy'); // '02.01.2025'
+parseToDatePeriod('01.01.2025 - 31.01.2025');  // [Date, Date]
+```
+
+### Formatting (`format.utils.ts`)
+
+- `formatToSpacedNumber(num)` — thousand separators
+- `truncate(text, limit)`
+
+```ts
+import { formatToSpacedNumber, truncate } from '@reforgium/internal';
+
+formatToSpacedNumber(1234567); // '1 234 567'
+truncate('Very long text', 8); // 'Very lon…'
+```
+
+### Routes & query (`routes.utils.ts`, `types.utils.ts`)
+Sources: `src/common/utils/routes.utils.ts`, `src/common/utils/types.utils.ts`
+
+- `makeQuery(object, concatType: 'comma' | 'json' | 'multi')`
+- `materializeRoutePath(actualRoute, pureRoute)`
+- `compareRoutes(actualRoute, pureRoute, withSubroute = false)`
+- `parseQueryArray(val, mode, key?)`
+- `concatArray(value, mode, key?)`
+
+```ts
+import { makeQuery, compareRoutes } from '@reforgium/internal';
+
+makeQuery({ a: 1, b: [1, 2] }, 'comma'); // 'a=1&b=1,2'
+compareRoutes('/users/42', '/users/:id'); // true
+```
+
+### Signal timers (`times.utils.ts`)
+
+- `debounceSignal(src, ms = 150, opts?)`
+- `throttleSignal(src, ms = 100, opts?)`
+
+### Web helpers (`web.utils.ts`)
+
+- `downloadFile(blob, fileName?)`
+- `downloadUrl(url, fileName?)`
+- `copyText(text)`
+- `base64ToBlob(base64, mimeType = '')`
+
+### DOM (`available-height.utils.ts`)
+
+- `getAvailableHeight(el, margin = 20)`
+
+### Positioning (`positions.utils.ts`)
+
+- `getCorrectedPosition(anchor, triggerSize, boundBox, directions, offset)`
+
+### Object access (`get-chained-value.utils.ts`)
+
+- `getChainedValue(obj, path)`
+
+```ts
+import { getChainedValue } from '@reforgium/internal';
+
+getChainedValue({ a: { b: [{ c: 1 }] } }, 'a.b.0.c'); // 1
+```
+
+### Deep compare (`deep-equal.utils.ts`)
+
+- `deepEqual(a, b)` (supports Map/Set/Date/RegExp/NaN, cycle-safe)
+
+### Type guards (`types.utils.ts`)
+
+- `isNullable(value, withEmptyString = false)`
+- `isNumber(value, fromString = false)`
+- `isObject(val)`
+
+### Misc (`generate.utils.ts`)
+
+- `generateId(limit = 15, radix = 36)`
+
+```ts
+import { generateId } from '@reforgium/internal';
+
+generateId();       // e.g. 'k3f9mz72q'
+generateId(10, 16); // hex-like
+```
+
+---
+
+## License
+
+MIT

package/fesm2022/reforgium-internal.mjs

@@ -1,25 +1,74 @@
 import { InjectionToken, signal, effect, untracked } from '@angular/core';
 
 /**
- * Текущий язык приложения как Signal.
- * Можно переопределить в app.config своим провайдером.
+ * Injection token for the current application language as a Signal.
+ * Provides reactive access to the currently selected language.
+ * Can be overridden in app.config with a custom provider.
+ *
+ * @type {InjectionToken<Signal<Langs>>}
  */
 const SELECTED_LANG = new InjectionToken('RE_SELECTED_LANG');
+/**
+ * Injection token for language change provider.
+ * Provides access to method for changing the current application language.
+ * Can be overridden in app.config with a custom provider.
+ *
+ * @type {InjectionToken<ChangeLangProvider>}
+ */
+const CHANGE_LANG = new InjectionToken('RE_CHANGE_LANG');
+/**
+ * Injection token for translation provider.
+ * Provides access to translation methods for message retrieval and namespace loading.
+ *
+ * @type {InjectionToken<TranslationProvider>}
+ */
+const TRANSLATION = new InjectionToken('RE_GET_LANG');
 
 /**
- * Текущий язык приложения как Signal.
- * Можно переопределить в app.config своим провайдером.
+ * Current application theme as Signal.
+ * Can be overridden in app.config with a custom provider.
  */
 const SELECTED_THEME = new InjectionToken('RE_SELECTED_THEME');
+const CHANGE_THEME = new InjectionToken('RE_CHANGE_THEME');
 
 /**
- * Текущий язык приложения как Signal.
- * Можно переопределить в app.config своим провайдером.
+ * Injection token for the current device type as a Signal.
+ *
+ * Provides reactive access to the current device type throughout the application.
+ * Can be overridden in app.config with a custom provider to supply device detection logic.
+ *
+ * @example
+ * ```typescript
+ * // In app.config.ts
+ * providers: [
+ *   {
+ *     provide: CURRENT_DEVICE,
+ *     useValue: signal<Devices>('mobile')
+ *   }
+ * ]
+ *
+ * // In a component or service
+ * private readonly currentDevice = inject(CURRENT_DEVICE);
+ * ```
  */
 const CURRENT_DEVICE = new InjectionToken('RE_CURRENT_DEVICE');
 
 /**
- * Токен карты сообщений валидации (переопределяй в feature-модуле).
+ * Injection token for a validation messages map.
+ * Can be overridden in feature modules to provide custom validation messages.
+ * Defaults to an empty object when not provided.
+ *
+ * @example
+ * // In a feature module:
+ * providers: [
+ *   {
+ *     provide: VALIDATION_MESSAGES,
+ *     useValue: {
+ *       required: () => 'This field is required',
+ *       minlength: (error) => `Min length: ${error.requiredLength}`
+ *     }
+ *   }
+ * ]
  */
 const VALIDATION_MESSAGES = new InjectionToken('RE_VALIDATION_MESSAGES', {
     providedIn: 'root',
@@ -809,5 +858,5 @@ const generateId = (limit = 15, radix = 36) => Math.random()
  * Generated bundle index. Do not edit.
  */
 
-export { CURRENT_DEVICE, SELECTED_LANG, SELECTED_THEME, VALIDATION_MESSAGES, appendQueryParams, base64ToBlob, compareRoutes, concatArray, copyText, debounceSignal, deepEqual, downloadByBlob, downloadByUrl, fillUrlWithParams, formatDate, formatToLocaledDate, formatToSpacedNumber, generateId, getAvailableHeight, getChainedValue, getCorrectedPosition, isDatePeriod, isNullable, isNumber, isObject, makeQuery, materializeRoutePath, normalizeUrl, parseQueryArray, parseQueryParams, parseToDate, parseToDatePeriod, reformatDateToISO, throttleSignal, toDate, truncate };
+export { CHANGE_LANG, CHANGE_THEME, CURRENT_DEVICE, SELECTED_LANG, SELECTED_THEME, TRANSLATION, VALIDATION_MESSAGES, appendQueryParams, base64ToBlob, compareRoutes, concatArray, copyText, debounceSignal, deepEqual, downloadByBlob, downloadByUrl, fillUrlWithParams, formatDate, formatToLocaledDate, formatToSpacedNumber, generateId, getAvailableHeight, getChainedValue, getCorrectedPosition, isDatePeriod, isNullable, isNumber, isObject, makeQuery, materializeRoutePath, normalizeUrl, parseQueryArray, parseQueryParams, parseToDate, parseToDatePeriod, reformatDateToISO, throttleSignal, toDate, truncate };
 //# sourceMappingURL=reforgium-internal.mjs.map