@relax.js/core 1.0.0

package/docs/Pipes.md

@@ -0,0 +1,211 @@
+# Pipes
+
+Data transformation functions for use in template expressions. Pipes transform values for display without modifying the underlying data.
+
+## Usage
+
+In templates with `compileTemplate`:
+
+```html
+<span>{{name | uppercase}}</span>
+<span>{{price | currency}}</span>
+<span>{{description | shorten:50}}</span>
+<span>{{tags | join:, }}</span>
+```
+
+Pipes can be chained:
+
+```html
+<span>{{text | trim | uppercase | shorten:20}}</span>
+```
+
+## Localization
+
+Several pipes are locale-aware and use the [i18n](i18n/i18n.md) system:
+
+- `currency` - Formats numbers according to locale
+- `date` - Formats dates according to locale
+- `daysAgo` - Translates "today", "yesterday", "X days ago"
+- `pieces` - Translates piece counts
+
+To use localized pipes:
+
+```typescript
+import { setLocale, loadNamespace } from 'relaxjs/i18n';
+
+// Set locale and load pipe translations
+await setLocale('sv');
+await loadNamespace('r-pipes');
+
+// Now pipes will output Swedish
+// {{createdAt | daysAgo}} → "idag", "igår", "3 dagar sedan"
+// {{price | currency:SEK}} → "1 234,56 kr"
+```
+
+### Translation Keys
+
+Translation keys in the `r-pipes` namespace:
+
+| Key | Message (EN) | Message (SV) |
+|-----|-------------|-------------|
+| `today` | `today` | `idag` |
+| `yesterday` | `yesterday` | `igår` |
+| `daysAgo` | `{count, plural, one {# day ago} other {# days ago}}` | `{count, plural, one {# dag sedan} other {# dagar sedan}}` |
+| `pieces` | `{count, plural, =0 {none} one {one} other {# pcs}}` | `{count, plural, =0 {inga} one {en} other {# st}}` |
+
+### Translation Files
+
+Pipe translations are stored in `src/i18n/locales/{locale}/r-pipes.json`:
+
+```json
+{
+    "today": "today",
+    "yesterday": "yesterday",
+    "daysAgo": "{count, plural, one {# day ago} other {# days ago}}",
+    "pieces": "{count, plural, =0 {none} one {one} other {# pcs}}"
+}
+```
+
+To add a new locale, create `src/i18n/locales/{locale}/r-pipes.json` with the translated strings.
+
+## Programmatic Usage
+
+```typescript
+import { applyPipes, defaultPipes, createPipeRegistry } from 'relaxjs/utils';
+
+// Apply pipes to a value
+const result = applyPipes('hello world', ['uppercase', 'shorten:8']);
+// Returns: 'HELLO...'
+
+// Use the default registry directly
+const upper = defaultPipes.get('uppercase');
+console.log(upper('hello')); // 'HELLO'
+
+// Create a fresh registry
+const registry = createPipeRegistry();
+```
+
+## Built-in Pipes
+
+### Text
+
+| Pipe | Description | Example | Result |
+|------|-------------|---------|--------|
+| `uppercase` | Convert to uppercase | `{{"hello" \| uppercase}}` | `HELLO` |
+| `lowercase` | Convert to lowercase | `{{"HELLO" \| lowercase}}` | `hello` |
+| `capitalize` | Capitalize first letter | `{{"hello" \| capitalize}}` | `Hello` |
+| `trim` | Remove leading/trailing whitespace | `{{" hello " \| trim}}` | `hello` |
+| `shorten:n` | Limit to n characters with ellipsis | `{{"hello world" \| shorten:8}}` | `hello...` |
+
+### Formatting (Locale-Aware)
+
+These pipes use the current i18n locale for formatting.
+
+| Pipe | Description | Example | en | sv |
+|------|-------------|---------|----|----|
+| `currency` | Format as currency (default USD) | `{{1234.5 \| currency}}` | `$1,234.50` | `1 234,50 US$` |
+| `currency:CODE` | Format with specific currency | `{{1234.5 \| currency:SEK}}` | `SEK 1,234.50` | `1 234,50 kr` |
+| `date` | Format date (ISO) | `{{date \| date}}` | `2024-01-15T...` | `2024-01-15T...` |
+| `date:short` | Short date format | `{{date \| date:short}}` | `1/15/2024` | `2024-01-15` |
+| `date:long` | Long date format | `{{date \| date:long}}` | `Monday, January 15, 2024` | `måndag 15 januari 2024` |
+| `daysAgo` | Relative date | `{{date \| daysAgo}}` | `3 days ago` | `3 dagar sedan` |
+| `pieces` | Piece count | `{{3 \| pieces}}` | `3 pcs` | `3 st` |
+
+### Arrays
+
+| Pipe | Description | Example | Result |
+|------|-------------|---------|--------|
+| `join` | Join with comma | `{{tags \| join}}` | `a,b,c` |
+| `join:sep` | Join with custom separator | `{{tags \| join: \| }}` | `a \| b \| c` |
+| `first` | Get first element | `{{items \| first}}` | First item |
+| `last` | Get last element | `{{items \| last}}` | Last item |
+
+### Objects
+
+| Pipe | Description | Example | Result |
+|------|-------------|---------|--------|
+| `keys` | Get object keys as array | `{{user \| keys}}` | `["name", "email"]` |
+
+### Conditionals
+
+| Pipe | Description | Example | Result |
+|------|-------------|---------|--------|
+| `default:val` | Fallback for falsy values | `{{name \| default:Anonymous}}` | Value or `Anonymous` |
+| `ternary:t:f` | Conditional value | `{{active \| ternary:Yes:No}}` | `Yes` or `No` |
+
+## Pipe Arguments
+
+Arguments are passed after a colon:
+
+```html
+<!-- Single argument -->
+<span>{{text | shorten:50}}</span>
+<span>{{price | currency:EUR}}</span>
+
+<!-- Multiple arguments -->
+<span>{{status | ternary:Active:Inactive}}</span>
+```
+
+## Configuration
+
+Pass a pipe registry to `compileTemplate`:
+
+```typescript
+import { compileTemplate } from 'relaxjs/html';
+import { createPipeRegistry } from 'relaxjs/utils';
+
+const pipeRegistry = createPipeRegistry();
+const { content, render } = compileTemplate(
+    '<span>{{name | uppercase}}</span>',
+    { strict: false, pipeRegistry }
+);
+```
+
+## API Reference
+
+### Types
+
+```typescript
+type PipeFunction = (value: any, ...args: any[]) => any;
+
+interface PipeRegistry {
+    lookup(name: string): PipeFunction | null;
+    get(name: string): PipeFunction;  // Throws if not found
+    has(name: string): boolean;
+}
+```
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `createPipeRegistry()` | Create a new registry with all built-in pipes |
+| `applyPipes(value, pipes, registry?)` | Apply an array of pipe strings to a value |
+| `defaultPipes` | Pre-created registry instance |
+
+### Individual Pipe Functions
+
+All pipes are also exported as individual functions for direct use:
+
+```typescript
+import {
+    uppercasePipe,
+    lowercasePipe,
+    capitalizePipe,
+    trimPipe,
+    shortenPipe,
+    currencyPipe,
+    datePipe,
+    daysAgoPipe,
+    piecesPipe,
+    joinPipe,
+    firstPipe,
+    lastPipe,
+    keysPipe,
+    defaultPipe,
+    ternaryPipe
+} from 'relaxjs/utils';
+
+const result = uppercasePipe('hello');  // 'HELLO'
+const formatted = currencyPipe(1234.56);  // '$1,234.56' (depends on locale)
+```

package/docs/Translations.md

@@ -0,0 +1,312 @@
+# Translation Library Documentation
+
+This library helps you internationalize (i18n) your application using namespace-based translations and ICU message format for pluralization and formatting.
+
+---
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Initialization and Loading Translations](#initialization-and-loading-translations)
+3. [Setting the Locale](#setting-the-locale)
+4. [Translation Function (`t`)](#translation-function-t)
+5. [Using Parameters in Translations](#using-parameters-in-translations)
+6. [Namespaces](#namespaces)
+7. [ICU Message Format](#icu-message-format)
+8. [Error Handling](#error-handling)
+9. [Example Translation Files](#example-translation-files)
+10. [Best Practices](#best-practices)
+
+---
+
+## Installation
+
+Import the library functions in your code:
+
+```ts
+import { setLocale, loadNamespace, t, getCurrentLocale } from 'relaxjs/i18n';
+```
+
+---
+
+## Initialization and Loading Translations
+
+When you first start your application, set the locale and the library will automatically load the `common` namespace.
+
+**Example:**
+
+```ts
+import { setLocale } from 'relaxjs/i18n';
+
+// Set locale at application startup
+await setLocale('en');
+```
+
+Under the hood, the library will:
+1. Normalize the locale (e.g., 'en-US' becomes 'en')
+2. Clear any previously loaded translations
+3. Load the `common` namespace from `/locales/{locale}/common.json`
+4. Fall back to English (`en`) if the requested locale is not found
+
+---
+
+## Setting the Locale
+
+Use `setLocale(locale: string)` to switch or explicitly set the user's locale. The function returns a Promise that resolves once the `common` namespace is loaded.
+
+**Example:**
+
+```ts
+import { setLocale } from 'relaxjs/i18n';
+
+async function switchToSwedish() {
+  await setLocale('sv');
+  console.log('Switched to Swedish!');
+}
+```
+
+> **Important**: Setting the locale clears all previously loaded translations and reloads the `common` namespace.
+
+---
+
+## Translation Function (`t`)
+
+Use the `t` function to translate a key into the current locale's string. The signature is:
+```ts
+t(fullKey: string, values?: Record<string, any>): string;
+```
+
+- **fullKey**: A string key in format `namespace:key` or just `key` (defaults to `common` namespace)
+- **values**: An optional object for ICU message interpolation
+
+**Basic Example:**
+```ts
+import { t } from 'relaxjs/i18n';
+
+console.log(t("welcome_message"));
+// Uses common:welcome_message
+
+console.log(t("errors:notFound"));
+// Uses errors namespace
+```
+
+---
+
+## Using Parameters in Translations
+
+If your translation string includes placeholders, provide dynamic values in the `values` argument. The library uses ICU message format for interpolation.
+
+**Example:**
+
+```ts
+// In your .json translation file (e.g. locales/en/common.json)
+{
+  "greeting": "Hello, {name}!"
+}
+
+// In your code:
+import { t } from 'relaxjs/i18n';
+
+console.log(t("greeting", { name: "Alice" }));
+// Output: "Hello, Alice!"
+```
+
+---
+
+## Namespaces
+
+Translations are organized into namespaces. Each namespace corresponds to a JSON file in the locales directory.
+
+### Directory Structure
+
+```
+/locales
+  /en
+    common.json
+    errors.json
+    shop.json
+  /sv
+    common.json
+    errors.json
+    shop.json
+```
+
+### Loading Namespaces
+
+The `common` namespace is loaded automatically when setting the locale. Load additional namespaces on demand:
+
+```ts
+import { loadNamespace, t } from 'relaxjs/i18n';
+
+// Load the shop namespace before using its translations
+await loadNamespace('shop');
+
+// Now you can use shop translations
+const price = t('shop:priceLabel');
+const items = t('shop:itemCount', { count: 5 });
+```
+
+### Key Format
+
+Use `namespace:key` format to reference translations:
+
+```ts
+t('common:greeting');     // Explicit common namespace
+t('greeting');            // Implicit common namespace (same as above)
+t('errors:notFound');     // errors namespace
+t('shop:checkout');       // shop namespace
+```
+
+---
+
+## ICU Message Format
+
+The library uses ICU message format for advanced formatting, including pluralization and selection.
+
+### Simple Interpolation
+
+```json
+{
+  "welcome": "Welcome, {name}!"
+}
+```
+
+```ts
+t('welcome', { name: 'John' }); // "Welcome, John!"
+```
+
+### Pluralization
+
+```json
+{
+  "items": "{count, plural, =0 {No items} one {# item} other {# items}}"
+}
+```
+
+```ts
+t('items', { count: 0 }); // "No items"
+t('items', { count: 1 }); // "1 item"
+t('items', { count: 5 }); // "5 items"
+```
+
+### Selection
+
+```json
+{
+  "userStatus": "{gender, select, male {He is online} female {She is online} other {They are online}}"
+}
+```
+
+```ts
+t('userStatus', { gender: 'female' }); // "She is online"
+```
+
+### Number and Date Formatting
+
+ICU format supports locale-aware number and date formatting:
+
+```json
+{
+  "price": "Price: {amount, number, currency}",
+  "date": "Date: {date, date, medium}"
+}
+```
+
+---
+
+## Error Handling
+
+1. **Missing translations**: If a translation key is not found, the function returns the key itself
+2. **Missing namespace**: If a namespace fails to load, the library falls back to the English locale
+3. **Format errors**: If ICU formatting fails, the function returns the key
+
+**Example:**
+
+```ts
+// If 'unknownKey' doesn't exist
+const result = t('unknownKey');
+// Returns: "unknownKey"
+
+// Namespace loading with fallback
+try {
+  await loadNamespace('shop');
+} catch (error) {
+  console.warn('Shop namespace not found, using fallback');
+}
+```
+
+---
+
+## Example Translation Files
+
+Below are example JSON translation files:
+
+**`/locales/en/common.json`**:
+```json
+{
+  "welcome_message": "Welcome to our site!",
+  "greeting": "Hello, {name}!",
+  "items": "{count, plural, =0 {No items} one {# item} other {# items}}",
+  "goodbye": "Goodbye!"
+}
+```
+
+**`/locales/en/errors.json`**:
+```json
+{
+  "notFound": "Page not found",
+  "unauthorized": "You are not authorized to view this page",
+  "serverError": "An unexpected error occurred"
+}
+```
+
+**`/locales/sv/common.json`** (Swedish):
+```json
+{
+  "welcome_message": "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å!"
+}
+```
+
+---
+
+## Best Practices
+
+- **Keep your translation keys consistent**: Use descriptive keys like `"user_profile_update_success"` instead of just `"message4"`.
+- **Organize by feature**: Use namespaces to group related translations (e.g., `shop`, `auth`, `errors`)
+- **Load namespaces lazily**: Only load namespaces when needed to reduce initial load time
+- **Use ICU format for plurals**: Instead of `item`/`items` keys, use ICU plural syntax
+- **Test across locales**: Different locales format numbers, dates, and plurals differently
+- **Provide fallbacks**: The library falls back to English, so ensure all keys exist in the English locale
+
+---
+
+## API Reference
+
+### `setLocale(locale: string): Promise<void>`
+Sets the current locale and loads the `common` namespace.
+
+### `loadNamespace(namespace: string): Promise<void>`
+Loads a translation namespace on demand.
+
+### `t(fullKey: string, values?: Record<string, any>): string`
+Translates a key with optional value interpolation using ICU format.
+
+### `getCurrentLocale(): string`
+Returns the current normalized locale code.
+
+---
+
+## Summary
+
+With this translation library, you can:
+
+- Organize translations into namespaces for better structure
+- Use the `t` function to substitute placeholders using ICU message format
+- Handle pluralization and selection with standard ICU syntax
+- Load namespaces on demand to optimize performance
+- Fall back to English for missing translations
+
+For more information on ICU message format, see the [ICU User Guide](https://unicode-org.github.io/icu/userguide/format_parse/messages/).