@relax.js/core 1.0.3 → 1.0.4

package/docs/api/media/i18n.md

@@ -0,0 +1,354 @@
+# Relaxjs i18n
+
+Namespace-based translations with ICU message format, lazy loading, and locale change events. Built on top of the [modern Intl standard](intl-standard.md).
+
+## Quick Start
+
+```typescript
+import { setLocale, loadNamespaces, t } from '@relax.js/core/i18n';
+
+await setLocale('sv');
+await loadNamespaces(['r-pipes', 'r-validation']);
+
+t('greeting', { name: 'Anna' });         // "Hej, Anna!"
+t('items', { count: 3 });                // "3 saker"
+t('r-pipes:daysAgo', { count: 2 });      // "2 dagar sedan"
+```
+
+## Folder Structure
+
+Translations live in `src/i18n/locales/{locale}/{namespace}.json`:
+
+```
+src/i18n/locales/
+├── en/
+│   ├── r-common.json
+│   ├── r-pipes.json
+│   └── r-validation.json
+└── sv/
+    ├── r-common.json
+    ├── r-pipes.json
+    └── r-validation.json
+```
+
+## Translation Keys
+
+Use `t('namespace:key')` to translate. Omit the namespace to use `r-common`:
+
+```typescript
+t('greeting', { name: 'Anna' })           // r-common:greeting
+t('r-common:greeting', { name: 'Anna' })  // explicit namespace
+t('r-pipes:today')                        // r-pipes namespace
+```
+
+If a key is not found, `t()` returns the key itself.
+
+## Translation Files
+
+### Simple Interpolation
+
+```json
+{
+    "greeting": "Hello, {name}!",
+    "welcome": "Welcome to {appName}"
+}
+```
+
+```typescript
+t('greeting', { name: 'John' });  // "Hello, John!"
+```
+
+### Pluralization (ICU)
+
+Uses `Intl.PluralRules` for locale-aware category selection. The `#` token inserts the count.
+
+```json
+{
+    "items": "{count, plural, one {# item} other {# items}}",
+    "daysAgo": "{count, plural, one {# day ago} other {# days ago}}"
+}
+```
+
+```typescript
+t('items', { count: 1 });  // "1 item"
+t('items', { count: 5 });  // "5 items"
+```
+
+### Exact Matches (`=N`)
+
+Exact values take priority over plural categories:
+
+```json
+{
+    "pieces": "{count, plural, =0 {none} one {one} other {# pcs}}"
+}
+```
+
+```typescript
+t('pieces', { count: 0 });  // "none"   (exact =0 match)
+t('pieces', { count: 1 });  // "one"    (plural category)
+t('pieces', { count: 5 });  // "5 pcs"  (plural category)
+```
+
+### Select (ICU)
+
+Chooses a branch based on an exact string match. Always include an `other` fallback.
+
+```json
+{
+    "status": "{role, select, admin {Full access} editor {Can edit} other {Read only}}"
+}
+```
+
+```typescript
+t('status', { role: 'admin' });    // "Full access"
+t('status', { role: 'editor' });   // "Can edit"
+t('status', { role: 'viewer' });   // "Read only"  (other)
+```
+
+### Number and Date Formatting
+
+ICU format supports locale-aware number and date formatting:
+
+```json
+{
+    "price": "Price: {amount, number, currency}",
+    "date": "Date: {date, date, medium}"
+}
+```
+
+## Example Translation Files
+
+**`src/i18n/locales/en/r-common.json`**:
+
+```json
+{
+    "welcome": "Welcome to our site!",
+    "greeting": "Hello, {name}!",
+    "items": "{count, plural, =0 {No items} one {# item} other {# items}}",
+    "goodbye": "Goodbye!"
+}
+```
+
+**`src/i18n/locales/en/errors.json`**:
+
+```json
+{
+    "notFound": "Page not found",
+    "unauthorized": "You are not authorized to view this page",
+    "serverError": "An unexpected error occurred"
+}
+```
+
+**`src/i18n/locales/sv/r-common.json`**:
+
+```json
+{
+    "welcome": "Välkommen till vår sida!",
+    "greeting": "Hej, {name}!",
+    "items": "{count, plural, =0 {Inga föremål} one {# föremål} other {# föremål}}",
+    "goodbye": "Hejdå!"
+}
+```
+
+## Built-in Namespaces
+
+### r-common
+
+General application strings. Loaded automatically with `setLocale()`.
+
+| Key | Message (EN) |
+|-----|-------------|
+| `greeting` | `Hello, {name}!` |
+| `items` | `{count, plural, one {# item} other {# items}}` |
+
+### r-pipes
+
+Translations for [locale-aware pipes](../Pipes.md). Load before using `daysAgo` or `pieces` pipes:
+
+```typescript
+await loadNamespace('r-pipes');
+```
+
+| Key | Message (EN) |
+|-----|-------------|
+| `today` | `today` |
+| `yesterday` | `yesterday` |
+| `daysAgo` | `{count, plural, one {# day ago} other {# days ago}}` |
+| `pieces` | `{count, plural, =0 {none} one {one} other {# pcs}}` |
+
+### r-validation
+
+Translations for [form validation](../forms/validation.md) error messages:
+
+```typescript
+await loadNamespace('r-validation');
+```
+
+| Key | Message (EN) |
+|-----|-------------|
+| `required` | `This field is required.` |
+| `range` | `Number must be between {min} and {max}, was {actual}.` |
+| `digits` | `Please enter only digits.` |
+
+## Locale Switching
+
+```typescript
+await setLocale('sv');  // Clears translations, loads sv/r-common.json, dispatches event
+await setLocale('en');  // Clears translations, loads en/r-common.json, dispatches event
+```
+
+Locale codes are normalized: `en-US` becomes `en`, `sv-SE` becomes `sv`.
+
+## LocaleChangeEvent
+
+`setLocale()` dispatches a `LocaleChangeEvent` on `document` after loading translations. Components can listen for it to re-render:
+
+```typescript
+document.addEventListener('localechange', (e) => {
+    console.log(`Switched to ${e.locale}`);
+    this.render();
+});
+```
+
+The event has a typed `locale` property (the normalized locale code) and is registered on `DocumentEventMap` for type-safe listeners.
+
+## Missing Translation Handler
+
+Register a callback for when `t()` encounters a missing key. Useful for development tooling, logging, or collecting untranslated strings:
+
+```typescript
+import { onMissingTranslation } from '@relax.js/core/i18n';
+
+onMissingTranslation((key, namespace, locale) => {
+    console.warn(`Missing: ${namespace}:${key} [${locale}]`);
+});
+```
+
+Pass `null` to remove the handler:
+
+```typescript
+onMissingTranslation(null);
+```
+
+## Fallback Behavior
+
+1. If a namespace file doesn't exist for the current locale, loads from `en/`
+2. If the key doesn't exist in the namespace, calls the missing handler (if set) and returns the key
+3. If the namespace doesn't exist at all, logs a warning and returns the key
+
+## Custom Message Formatter
+
+The built-in formatter supports interpolation, pluralization, and select. For advanced ICU features (nested arguments, date/time formatting in messages), use an external library:
+
+```typescript
+import { setMessageFormatter } from '@relax.js/core/i18n';
+import { IntlMessageFormat } from 'intl-messageformat';
+
+setMessageFormatter((message, values, locale) => {
+    const fmt = new IntlMessageFormat(message, locale);
+    return fmt.format(values) as string;
+});
+```
+
+## Integration with Pipes
+
+Several [pipes](../Pipes.md) use the i18n system for localized output:
+
+- `currency`: uses `getCurrentLocale()` for number formatting
+- `date`: uses `getCurrentLocale()` for date formatting
+- `daysAgo`: uses `t('r-pipes:...')` for translated text
+- `pieces`: uses `t('r-pipes:...')` for translated text
+
+```typescript
+await setLocale('sv');
+await loadNamespace('r-pipes');
+
+// Now pipes output Swedish
+// {{createdAt | daysAgo}} → "idag", "igår", "3 dagar sedan"
+```
+
+## Adding a New Locale
+
+1. Create `src/i18n/locales/{locale}/r-common.json`
+2. Create `src/i18n/locales/{locale}/r-pipes.json`
+3. Create `src/i18n/locales/{locale}/r-validation.json`
+4. Add translations for all keys
+
+Example for German:
+
+```json
+// src/i18n/locales/de/r-pipes.json
+{
+    "today": "heute",
+    "yesterday": "gestern",
+    "daysAgo": "{count, plural, one {vor # Tag} other {vor # Tagen}}",
+    "pieces": "{count, plural, =0 {keine} one {eins} other {# Stück}}"
+}
+```
+
+## API Reference
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `setLocale(locale)` | Set locale, clear translations, load `r-common`, dispatch event |
+| `loadNamespace(ns)` | Load a single translation namespace |
+| `loadNamespaces(ns[])` | Load multiple namespaces in parallel |
+| `t(key, values?)` | Translate a key with optional interpolation |
+| `getCurrentLocale()` | Get the current normalized locale code |
+| `onMissingTranslation(handler)` | Register/remove missing key handler |
+| `setMessageFormatter(fn)` | Replace the default ICU formatter |
+
+### Types
+
+```typescript
+type MessageFormatter = (
+    message: string,
+    values?: Record<string, any>,
+    locale?: string,
+) => string;
+
+type MissingTranslationHandler = (
+    key: string,
+    namespace: string,
+    locale: string,
+) => void;
+```
+
+### Events
+
+| Event | Target | Property | Description |
+|-------|--------|----------|-------------|
+| `localechange` | `document` | `locale: string` | Fired after `setLocale()` completes |
+
+## Example: Full Setup
+
+```typescript
+import {
+    setLocale, loadNamespaces, t,
+    getCurrentLocale, onMissingTranslation,
+} from '@relax.js/core/i18n';
+
+async function initI18n() {
+    // Dev-time missing key logging
+    onMissingTranslation((key, ns, locale) => {
+        console.warn(`Missing: ${ns}:${key} [${locale}]`);
+    });
+
+    // Detect browser locale or use default
+    const browserLocale = navigator.language || 'en';
+    await setLocale(browserLocale);
+
+    // Load namespaces needed by the app
+    await loadNamespaces(['r-pipes', 'r-validation']);
+
+    console.log(`Locale: ${getCurrentLocale()}`);
+}
+
+// React to locale changes
+document.addEventListener('localechange', (e) => {
+    console.log(`Locale switched to ${e.locale}`);
+});
+```

package/docs/api/media/utilities.md

@@ -0,0 +1,143 @@
+# Utilities
+
+Small helper functions and data structures exported from `@relax.js/core/utils`.
+
+## generateSequentialId
+
+Generates compact, time-ordered unique identifiers. IDs sort lexicographically in creation order, making them useful for ordered collections and databases.
+
+```typescript
+import { generateSequentialId } from '@relax.js/core/utils';
+
+const id = generateSequentialId(1);
+// Returns a Base36 string like 'k2j8m3n5p'
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `baseId` | `number` | Unique identifier for the client/process (0 to 1,048,575) |
+
+Use different `baseId` values for different servers or processes to avoid collisions:
+
+```typescript
+const SERVER_ID = parseInt(process.env.SERVER_ID || '0');
+const orderId = generateSequentialId(SERVER_ID);
+```
+
+### Structure
+
+Each ID encodes 58 bits of data in Base36:
+
+| Bits | Field | Range |
+|------|-------|-------|
+| 30 | Timestamp (seconds since 2025-01-01) | Until ~2059 |
+| 8 | Per-second counter | 256 IDs/second |
+| 20 | Client identifier | ~1M unique sources |
+
+### Time-Sortable
+
+IDs generated later sort after earlier IDs:
+
+```typescript
+const id1 = generateSequentialId(0);
+// ... wait ...
+const id2 = generateSequentialId(0);
+console.log(id1 < id2); // true
+```
+
+### Errors
+
+- Throws if `baseId` is out of range (0 to 1,048,575)
+- Throws if more than 256 IDs are generated in a single second
+- Throws if timestamp exceeds range (after ~2059)
+
+## resolveValue
+
+Safely navigates nested object properties using a path array. Returns `undefined` if any segment is null or missing (no exceptions thrown).
+
+```typescript
+import { resolveValue } from '@relax.js/core/utils';
+
+const user = { address: { city: 'Stockholm' } };
+
+resolveValue(['address', 'city'], user);
+// Returns: 'Stockholm'
+
+resolveValue(['address', 'zip'], user);
+// Returns: undefined
+
+// Safe with null values
+const data = { user: null };
+resolveValue(['user', 'name'], data);
+// Returns: undefined (no error)
+```
+
+### Use with Dot-Notation Paths
+
+```typescript
+const path = 'user.profile.avatar'.split('.');
+const avatar = resolveValue(path, context);
+```
+
+## LinkedList
+
+A doubly-linked list with O(1) insertion and removal at both ends.
+
+```typescript
+import { LinkedList } from '@relax.js/core/utils';
+
+const list = new LinkedList<string>();
+
+list.addFirst('A');
+list.addLast('B');
+list.addLast('C');
+
+console.log(list.length);      // 3
+console.log(list.firstValue);  // 'A'
+console.log(list.lastValue);   // 'C'
+
+list.removeFirst(); // Returns 'A'
+list.removeLast();  // Returns 'C'
+console.log(list.length);      // 1
+```
+
+### Node Access
+
+Access the internal `Node` wrappers to traverse or remove specific nodes:
+
+```typescript
+let node = list.first;
+while (node) {
+    console.log(node.value);
+    node = node.next;
+}
+
+// Remove a specific node
+const node = list.first;
+node.remove(); // Removes from list and updates length
+```
+
+### API
+
+| Method/Property | Description |
+|-----------------|-------------|
+| `addFirst(value)` | Insert at the beginning |
+| `addLast(value)` | Insert at the end |
+| `removeFirst()` | Remove and return the first value |
+| `removeLast()` | Remove and return the last value |
+| `length` | Number of nodes |
+| `first` | First `Node` (or `undefined`) |
+| `last` | Last `Node` (or `undefined`) |
+| `firstValue` | Value of the first node |
+| `lastValue` | Value of the last node |
+
+### Node Properties
+
+| Property | Description |
+|----------|-------------|
+| `value` | The stored value |
+| `next` | Next node (or `null`) |
+| `prev` | Previous node (or `null`) |
+| `remove()` | Remove this node from the list |