@relax.js/core 1.0.0

package/docs/http/index.md

@@ -0,0 +1,109 @@
+# HTTP, WebSocket & SSE
+
+This module provides HTTP, WebSocket, and Server-Sent Events clients for network communication.
+
+## Available Features
+
+| Feature | Description | Use Case |
+|---------|-------------|----------|
+| [HTTP Client](HttpClient.md#http-client) | Type-safe HTTP functions | REST API calls with JWT handling |
+| [WebSocketClient](HttpClient.md#websocket-client) | WebSocket client with auto-reconnect | Real-time bidirectional messaging |
+| [SSEClient](ServerSentEvents.md) | Server-Sent Events as DOM events | Server push notifications |
+
+## Quick Start
+
+### HTTP Requests
+
+```typescript
+import { configure, get, post } from 'relaxjs/http';
+
+configure({ baseUrl: '/api/v1' });
+
+// GET with query parameters
+const response = await get('/users', { status: 'active' });
+if (response.success) {
+    const users = response.as<User[]>();
+}
+
+// POST with JSON body
+const result = await post('/users', JSON.stringify({ name: 'John' }));
+```
+
+### WebSocket Messaging
+
+```typescript
+import { WebSocketClient } from 'relaxjs/http';
+
+const ws = new WebSocketClient<Message>('wss://api.example.com');
+ws.connect();
+
+// Check connection state
+console.log(ws.connected); // true when connected
+
+// Send (queued if disconnected)
+ws.send({ type: 'chat', text: 'Hello' });
+
+// Receive (rejects if connection closes)
+try {
+    const message = await ws.receive();
+} catch (e) {
+    console.log('Connection closed');
+}
+
+// Disconnect when done
+ws.disconnect();
+```
+
+### Server-Sent Events
+
+```typescript
+import { SSEClient } from 'relaxjs/http';
+
+const sse = new SSEClient('/api/events', {
+    eventTypes: ['user-updated', 'notification']
+});
+sse.connect();
+
+// Events dispatch to document by default
+document.addEventListener('notification', (e: SSEMessageEvent) => {
+    showNotification(e.data);
+});
+
+// Disconnect when done
+sse.disconnect();
+```
+
+## Key Features
+
+### HTTP Client
+
+- Standalone functions (`get`, `post`, `put`, `del`, `request`)
+- Module-wide configuration via `configure()`
+- Automatic base URL prefixing
+- JWT token from localStorage (configurable)
+- Query string building
+- Type-safe response casting
+- Replaceable fetch for testing via `setFetch()`
+
+### WebSocketClient
+
+- Auto-reconnect with exponential backoff
+- Message queuing when disconnected
+- Custom message codecs
+- Type-safe generic messages
+- Connection state tracking
+- Graceful disconnect support
+
+### SSEClient
+
+- Dispatches SSE events as DOM events
+- Configurable target element or document
+- Auto-reconnect with exponential backoff
+- Automatic JSON parsing
+
+## Choosing the Right Tool
+
+- **REST API calls?** → Use `get`, `post`, `put`, `del`
+- **Bidirectional real-time?** → Use `WebSocketClient`
+- **Server push only?** → Use `SSEClient`
+- **Both?** → Use `HttpClient` for requests, `WebSocketClient` or `SSEClient` for subscriptions

package/docs/i18n/i18n.md

@@ -0,0 +1,309 @@
+# 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 'relaxjs/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)
+```
+
+## 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 'relaxjs/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 'relaxjs/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 'relaxjs/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/i18n/intl-standard.md

@@ -0,0 +1,178 @@
+# The Modern Intl Standard
+
+The browser's built-in [`Intl`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) object provides locale-aware formatting for numbers, dates, strings, and more. It is supported in all modern browsers and Node.js, so no polyfills or libraries are needed.
+
+Relaxjs uses `Intl` internally (e.g. `Intl.PluralRules` for ICU pluralization) and exposes the current locale via `getCurrentLocale()` so pipes and components can pass it directly to `Intl` APIs.
+
+## Intl.PluralRules
+
+Determines the plural category (`zero`, `one`, `two`, `few`, `many`, `other`) for a number in a given locale. Different languages have different rules. English has two categories (`one` / `other`), Arabic has six.
+
+```typescript
+const en = new Intl.PluralRules('en');
+en.select(1);   // 'one'
+en.select(0);   // 'other'
+en.select(5);   // 'other'
+
+const sv = new Intl.PluralRules('sv');
+sv.select(1);   // 'one'   → en
+sv.select(0);   // 'other' → flera
+sv.select(5);   // 'other' → flera
+```
+
+The returned strings (`one`, `other`, `few`, etc.) are category identifiers, not localized text. The locale determines *which numbers* map to *which categories*. English and Swedish both use `one`/`other`, while languages like Arabic use all six categories (`zero`, `one`, `two`, `few`, `many`, `other`).
+
+This is the engine behind ICU `{count, plural, ...}` messages. The Relaxjs ICU formatter delegates to `Intl.PluralRules` for category selection.
+
+[MDN: Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules)
+
+## Intl.NumberFormat
+
+Formats numbers according to locale conventions: thousands separators, decimal marks, currency, percentages, units, and compact notation.
+
+```typescript
+new Intl.NumberFormat('en').format(1234.5);        // '1,234.5'
+new Intl.NumberFormat('sv').format(1234.5);        // '1 234,5'
+
+new Intl.NumberFormat('en', {
+    style: 'currency', currency: 'USD'
+}).format(42);                                      // '$42.00'
+
+new Intl.NumberFormat('sv', {
+    style: 'currency', currency: 'SEK'
+}).format(42);                                      // '42,00 kr'
+
+new Intl.NumberFormat('en', {
+    notation: 'compact'
+}).format(1_500_000);                               // '1.5M'
+```
+
+The Relaxjs `currency` pipe uses `Intl.NumberFormat` with `getCurrentLocale()`.
+
+[MDN: Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)
+
+## Intl.DateTimeFormat
+
+Formats dates and times according to locale conventions and configurable options.
+
+```typescript
+const date = new Date('2025-06-15T14:30:00');
+
+new Intl.DateTimeFormat('en').format(date);         // '6/15/2025'
+new Intl.DateTimeFormat('sv').format(date);         // '2025-06-15'
+
+new Intl.DateTimeFormat('en', {
+    dateStyle: 'long', timeStyle: 'short'
+}).format(date);                                     // 'June 15, 2025 at 2:30 PM'
+
+new Intl.DateTimeFormat('sv', {
+    weekday: 'long', month: 'long', day: 'numeric'
+}).format(date);                                     // 'söndag 15 juni'
+```
+
+The Relaxjs `date` pipe uses `Intl.DateTimeFormat` with `getCurrentLocale()`.
+
+[MDN: Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)
+
+## Intl.RelativeTimeFormat
+
+Formats relative time descriptions ("3 days ago", "in 2 hours") with locale-aware phrasing.
+
+```typescript
+const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
+rtf.format(-1, 'day');    // 'yesterday'
+rtf.format(0, 'day');     // 'today'
+rtf.format(3, 'day');     // 'in 3 days'
+
+const svRtf = new Intl.RelativeTimeFormat('sv', { numeric: 'auto' });
+svRtf.format(-1, 'day');  // 'igår'
+svRtf.format(-3, 'day');  // 'för 3 dagar sedan'
+```
+
+[MDN: Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat)
+
+## Intl.Collator
+
+Provides locale-sensitive string comparison for sorting. Handles accents, case, and locale-specific sort orders (e.g. Swedish å/ä/ö sort after z).
+
+```typescript
+const col = new Intl.Collator('sv');
+['ö', 'a', 'å', 'ä'].sort(col.compare);  // ['a', 'å', 'ä', 'ö']
+
+const enCol = new Intl.Collator('en', { sensitivity: 'base' });
+enCol.compare('café', 'cafe');             // 0  (equal, ignoring accent)
+```
+
+[MDN: Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator)
+
+## Intl.Segmenter
+
+Splits text into meaningful segments (graphemes, words, or sentences) while respecting locale rules. Essential for languages without spaces between words (Chinese, Japanese, Thai).
+
+```typescript
+const seg = new Intl.Segmenter('en', { granularity: 'word' });
+const words = [...seg.segment('Hello world!')].filter(s => s.isWordLike);
+// [{segment: 'Hello'}, {segment: 'world'}]
+```
+
+[MDN: Intl.Segmenter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter)
+
+## Intl.ListFormat
+
+Formats lists with locale-appropriate conjunctions and punctuation.
+
+```typescript
+new Intl.ListFormat('en', { type: 'conjunction' })
+    .format(['Alice', 'Bob', 'Charlie']);    // 'Alice, Bob, and Charlie'
+
+new Intl.ListFormat('sv', { type: 'conjunction' })
+    .format(['Alice', 'Bob', 'Charlie']);    // 'Alice, Bob och Charlie'
+```
+
+[MDN: Intl.ListFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat)
+
+## Intl.DisplayNames
+
+Translates language, region, currency, and script codes into human-readable names.
+
+```typescript
+new Intl.DisplayNames('en', { type: 'language' }).of('sv');    // 'Swedish'
+new Intl.DisplayNames('sv', { type: 'language' }).of('en');    // 'engelska'
+new Intl.DisplayNames('en', { type: 'currency' }).of('SEK');  // 'Swedish Krona'
+```
+
+[MDN: Intl.DisplayNames](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames)
+
+## ICU Message Format
+
+ICU (International Components for Unicode) defines a message syntax used across platforms. The three core patterns:
+
+### Simple Interpolation
+
+```
+Hello, {name}!
+```
+
+### Plural
+
+Selects a branch based on `Intl.PluralRules`. The `#` token inserts the numeric value. Exact matches (`=0`, `=1`) take priority over category matches.
+
+```
+{count, plural, =0 {No items} one {# item} other {# items}}
+```
+
+### Select
+
+Selects a branch based on an exact string match. Always include an `other` fallback.
+
+```
+{gender, select, male {He} female {She} other {They}} liked your post.
+```
+
+[ICU User Guide: Formatting Messages](https://unicode-org.github.io/icu/userguide/format_parse/messages/)
+
+## Further Reading
+
+- [MDN: Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl), full API reference
+- [ICU Message Format](https://unicode-org.github.io/icu/userguide/format_parse/messages/), the message syntax standard
+- [Can I Use: Intl](https://caniuse.com/?search=Intl), browser support tables

package/docs/routing/RouteLink.md

@@ -0,0 +1,98 @@
+# RouteLink
+
+A clickable element that triggers client-side navigation to a named route.
+
+## Usage
+
+### Basic Navigation
+
+```html
+<r-link name="home">Home</r-link>
+<r-link name="about">About Us</r-link>
+```
+
+### With Route Parameters
+
+```html
+<r-link name="user" param-id="123">View User</r-link>
+<r-link name="product" param-id="456" param-tab="details">Product Details</r-link>
+```
+
+### With Target
+
+```html
+<r-link name="settings" target="sidebar">Settings</r-link>
+<r-link name="preview" target="modal">Preview</r-link>
+```
+
+### Complex Parameters via JSON
+
+```html
+<r-link name="search" params='{"query":"typescript","page":1}'>
+    Search Results
+</r-link>
+```
+
+## Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Route name to navigate to (required) |
+| `target` | `string` | Target `r-route-target` name |
+| `params` | `string` | JSON object with additional route data |
+| `param-*` | `string` | Individual route parameters (e.g., `param-id="123"`) |
+
+## Behavior
+
+1. Renders as an inline element with `cursor: pointer`
+2. Sets `role="link"` and `tabindex="0"` for accessibility
+3. On click, calls `navigate()` with the route name and collected parameters
+4. Prevents default click behavior
+
+## Combining Parameters
+
+Both `param-*` attributes and `params` JSON can be used together:
+
+```html
+<r-link name="product"
+     param-id="789"
+     params='{"source":"email","campaign":"summer"}'>
+    View Product
+</r-link>
+```
+
+All parameters are merged into a single flat object:
+```typescript
+{ id: '789', source: 'email', campaign: 'summer' }
+```
+
+## Styling
+
+Style as any inline element:
+
+```css
+r-link {
+    color: var(--accent-primary);
+    text-decoration: underline;
+}
+
+r-link:hover {
+    color: var(--accent-hover);
+}
+
+r-link:focus {
+    outline: 2px solid var(--accent-primary);
+    outline-offset: 2px;
+}
+```
+
+## Comparison with Native Links
+
+| Feature | `<a href>` | `<r-link>` |
+|---------|------------|---------|
+| Navigation | Full page reload | Client-side routing |
+| Parameters | Query string | Route params + data |
+| Target | Window/frame | Route target |
+| SEO | Crawlable | Requires SSR |
+
+Use `<r-link>` for SPA navigation within the app. Use native `<a>` for external links or when SEO is critical.