@reforgium/internal 1.1.0 → 1.2.0

package/README.md

@@ -1,260 +1,82 @@
-# @reforgium/internal
-
-[![npm version](https://badge.fury.io/js/%40reforgium%2Finternal.svg)](https://www.npmjs.com/package/@reforgium/internal)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-**Core infrastructure package for Angular (20+) applications.**
-
-`@reforgium/internal` is a foundational layer that sits *under* feature libraries and applications.  
-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.
-
----
-
-## Why
-
-- Centralize shared domain primitives
-- Prevent cross-package circular dependencies
-- Keep feature/UI layers clean
-- Enable aggressive tree-shaking and dead-code elimination
-- Provide a reusable internal base across multiple libraries and apps
-
----
-
-## What’s inside
-
-- **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)
-
-> It’s the bedrock, not the building.
-
----
-
-## 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' },
-];
-```
-
-### Utility types (`util.ts`)
-
-#### `AnyType`
-Compatibility type (similar to `any`) used in low-level helpers.
-
-#### `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,
-};
-```
-
----
-
-## Tokens
-The localization system is built around a service that manages translations across different languages and namespaces. It supports:
-
-- 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
-
+# @reforgium/internal
+
+[![npm version](https://badge.fury.io/js/%40reforgium%2Finternal.svg)](https://www.npmjs.com/package/@reforgium/internal)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Shared infrastructure package for Reforgium Angular libraries.
+
+## Install
+
+```bash
+npm i @reforgium/internal
+```
+
+## Public API
+
+`@reforgium/internal` exports:
+- `models`
+- `tokens`
+- `utils`
+
+### Models
+
+Main model groups:
+- `api.ts`: `RestMethods`, `SortToken`, `PageableRequest`, `PageableResponse<T>`, `ErrorResponse`, `QueryParams`, `Query`
+- `components.ts`: `Appearance`, `SelectOption`, `SelectIconOption`
+- `elements.ts`: `Direction`, `ElementRect`, `ElementSize`, `ElementPosition`, `ElementEdges`
+- `util.ts`: `AnyType`, `AnyDict`, `LiteralOf`, `ValueOf`, `Nullable`, `Nullish`, `NullableProps`, `OptionalExcept`, `RequiredExcept`, `Mutable`, JSON helper types
+
+### Tokens
+
+Language tokens:
+- `SELECTED_LANG: InjectionToken<Signal<Langs>>`
+- `CHANGE_LANG: InjectionToken<(lang: Langs) => void>`
+- `TRANSLATION`
+- `REGISTER_LANG` (multi-token)
+- `BUILTIN_LANGS`
+- `provideLangs(...langs: string[])`
+- `Langs = BuiltInLangs | (string & {})`
+
+Theme/device/validation tokens:
+- `SELECTED_THEME`, `CHANGE_THEME`, `Themes`
+- `CURRENT_DEVICE`, `Devices`
+- `VALIDATION_MESSAGES`, `ValidationMessages`, `ValidationErrorData`
+
+Example:
+
+```ts
+import { provideLangs } from '@reforgium/internal';
+
+export const appConfig = {
+  providers: [provideLangs('de', 'fr')],
+};
+```
+
+### Utilities
+
+Exported utilities:
+- `web.utils.ts`: `downloadByBlob`, `downloadByUrl`, `copyText`, `base64ToBlob`
+- `timers.utils.ts`: `throttleSignal`, `debounceSignal`
+- `date.utils.ts`: `toDate`, `formatDate`, `formatToLocaledDate`, `parseToDate`, `parseToDatePeriod`, `isDatePeriod`, `reformatDateToISO`
+- `types.utils.ts`: `isNumber`, `isNullable`, `isObject`, `parseQueryArray`, `concatArray`
+- `format.utils.ts`: `formatToSpacedNumber`, `truncate`
+- `positions.utils.ts`: `getCorrectedPosition`
+- `available-height.utils.ts`: `getAvailableHeight`
+- `get-chained-value.utils.ts`: `getChainedValue`
+- `urls.utils.ts`: `normalizeUrl`, `fillUrlWithParams`, `appendQueryParams`, `parseQueryParams`
+- `routes.utils.ts`: `materializeRoutePath`, `compareRoutes`, `makeQuery`
+- `deep-equal.utils.ts`: `deepEqual`
+- `generate.utils.ts`: `generateId`
+
+`makeQuery(..., 'multi')` behavior:
+
+```ts
+import { makeQuery } from '@reforgium/internal';
+
+makeQuery({ ids: [1, 2, 3], q: 'ok' }, 'multi');
+// ids=1&ids=2&ids=3&q=ok
+```
+
+## License
+
 MIT