Initial commit

2026-06-25 15:53:49 +03:00
commit 1bb0b7e68a
1517 changed files with 218469 additions and 0 deletions
@@ -0,0 +1,141 @@
+# [←](../../../docs/README.md) @crux-kit/intl-name
+
+A lightweight TypeScript service for formatting personal names into display-ready strings with locale support.
+
+The service accepts multiple input formats (objects or strings), normalizes them into a canonical structure, and formats the output according to language-specific patterns.
+
+---
+
+## Quick Start
+
+```ts
+import { intlNameService, INTL_NAME_TOKENS } from 'intl-name';
+
+const IntlName = intlNameService(
+  {
+    language: 'uk',
+    fallbackLanguage: 'uk',
+    localeMap: {
+      uk: {
+        formats: {
+          SURNAME_NAME: `${INTL_NAME_TOKENS.LAST.FULL} ${INTL_NAME_TOKENS.FIRST.FULL}`,
+          INITIALS_LF: `${INTL_NAME_TOKENS.LAST.INITIAL}${INTL_NAME_TOKENS.FIRST.INITIAL}`,
+        },
+      },
+      en: {
+        formats: {
+          SURNAME_NAME: `${INTL_NAME_TOKENS.LAST.FULL} ${INTL_NAME_TOKENS.FIRST.FULL}`,
+          INITIALS_LF: `${INTL_NAME_TOKENS.LAST.INITIAL}${INTL_NAME_TOKENS.FIRST.INITIAL}`,
+        },
+      },
+    },
+  },
+  console,
+);
+
+IntlName.formatToDisplay({ firstName: 'John', lastName: 'Smith' }, 'SURNAME_NAME');
+// → "Smith John"
+```
+
+---
+
+## Supported Input Formats
+
+The service accepts names in three formats:
+
+### camelCase object
+
+```ts
+{ firstName, lastName, patronymic?, middleName?, prefix?, suffix? }
+```
+
+### snake_case object
+
+```ts
+{ first_name, last_name, patronymic?, middle_name?, prefix?, suffix? }
+```
+
+### string
+
+```ts
+'First Last Patronymic';
+```
+
+All input formats are automatically normalized into a canonical internal representation.
+
+---
+
+## Formatting Patterns & Tokens
+
+Name formatting is driven by **patterns** defined in the `localeMap`.
+
+Patterns are plain strings composed of **tokens** that represent different parts of a person’s name.
+At runtime, these tokens are replaced with actual values from the input.
+
+If a token has no value, it is replaced with an empty string.
+
+---
+
+## Conditional Blocks `{ ... }`
+
+Conditional blocks are **optional helpers** mainly intended to control
+**punctuation, separators, and surrounding spaces**.
+
+> Tokens work without conditional blocks.  
+> Missing values are simply replaced with an empty string.
+
+### Why conditional blocks matter
+
+Without conditional blocks, punctuation remains even when a value is missing:
+
+```ts
+// Pattern without a conditional block
+`${INTL_NAME_TOKENS.LAST.FULL}, ${INTL_NAME_TOKENS.FIRST.FULL}`;
+
+// Input: { lastName: "Smith" }
+// Output: "Smith, "
+```
+
+Using a conditional block removes the separator entirely:
+
+```ts
+`${INTL_NAME_TOKENS.LAST.FULL}{, ${INTL_NAME_TOKENS.FIRST.FULL}}`;
+
+// Input: { lastName: "Smith" }
+// Output: "Smith"
+```
+
+The whole block (including commas, dots, or spaces) is rendered
+**only if at least one token inside has a value**.
+
+### Typical use cases
+
+- Commas and dots (`", "`, `"."`)
+- Extra spaces around optional parts
+- Optional patronymic or middle name
+
+Example:
+
+```ts
+`${INTL_NAME_TOKENS.LAST.FULL} ${INTL_NAME_TOKENS.FIRST.FULL}{ ${INTL_NAME_TOKENS.PATRONYMIC.FULL}}`;
+```
+
+- With patronymic → `"Smith John Ivanovich"`
+- Without patronymic → `"Smith John"`
+
+Conditional blocks help keep formatting clean without manual string checks.
+
+---
+
+## API
+
+### `intlNameService(config, logger?)`
+
+Creates a service instance.
+
+Returns:
+
+- `formatToDisplay(input, formatKey)` — formats the name for display
+- `toObject(input)` — converts input into a canonical object
+- `setLanguage(lang)` — changes the active language
+- `setSupportedLanguages(map)` — replaces the supported locale map