@relax.js/core 1.0.3 → 1.0.4

package/docs/api/media/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 '@relax.js/core/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 '@relax.js/core/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 '@relax.js/core/html';
+import { createPipeRegistry } from '@relax.js/core/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 '@relax.js/core/utils';
+
+const result = uppercasePipe('hello');  // 'HELLO'
+const formatted = currencyPipe(1234.56);  // '$1,234.56' (depends on locale)
+```

package/docs/api/media/Routing.md

@@ -0,0 +1,332 @@
+# Routing
+
+## Overview
+
+A client-side routing system for single-page applications. The router:
+
+- Matches URLs to route configurations
+- Extracts typed parameters from URL segments
+- Manages browser history (back/forward navigation)
+- Dispatches `NavigateRouteEvent` to render components
+- Supports multiple rendering targets (main content, sidebars, modals)
+- Handles layout switching between different HTML shells
+
+The router itself only handles matching and navigation. Rendering is handled by [`<r-route-target>`](RoutingTarget.md) components that listen for navigation events.
+
+## Quick Start
+
+```typescript
+import { Route, defineRoutes, startRouting } from '@relax.js/core/routing';
+
+const routes: Route[] = [
+    { name: 'home', path: '/', componentTagName: 'home-page' },
+    { name: 'users', path: '/users', componentTagName: 'user-list' },
+    { name: 'user', path: '/users/:id', componentTagName: 'user-profile' },
+];
+
+defineRoutes(routes);
+startRouting();
+```
+
+```html
+<body>
+    <nav>
+        <r-link name="home">Home</r-link>
+        <r-link name="users">Users</r-link>
+    </nav>
+    <main>
+        <r-route-target></r-route-target>
+    </main>
+</body>
+```
+
+## Route Definition
+
+Each route specifies how a URL maps to a component:
+
+```typescript
+interface Route {
+    name?: string;              // Identifier for programmatic navigation
+    path: string;               // URL pattern with parameters
+    componentTagName?: string;  // Custom element tag name
+    component?: WebComponentConstructor;  // Or class reference
+    target?: string;            // Named r-route-target (default: unnamed)
+    layout?: string;            // HTML file for different shells
+    guards?: RouteGuard[];      // Access control
+}
+```
+
+### URL Pattern Syntax
+
+| Syntax | Type | Example | Matches |
+|--------|------|---------|---------|
+| `text` | Static segment | `/users` | Exactly "users" |
+| `:name` | String parameter | `/users/:id` | `/users/john` → `{ id: 'john' }` |
+| `;name` | Number parameter | `/orders/;orderId` | `/orders/123` → `{ orderId: 123 }` |
+
+Number parameters (`;`) validate that the segment contains only digits and convert to `number` type. String parameters (`:`) accept any value and remain as `string`.
+
+```typescript
+const routes: Route[] = [
+    { name: 'home', path: '/' },
+    { name: 'user', path: '/users/:userName' },        // String: userName
+    { name: 'order', path: '/orders/;orderId' },       // Number: orderId
+    { name: 'category', path: '/shop/:category/items' }, // Mixed static + param
+];
+```
+
+## Navigation
+
+### Using RouteLink Component
+
+The simplest way to navigate is with [`<r-link>`](RouteLink.md):
+
+```html
+<r-link name="home">Home</r-link>
+<r-link name="user" param-userName="john">View Profile</r-link>
+<r-link name="order" param-orderId="123">Order Details</r-link>
+```
+
+### Programmatic Navigation
+
+Use `navigate()` for navigation from code:
+
+```typescript
+import { navigate } from '@relax.js/core/routing';
+
+// By route name with parameters
+navigate('user', { params: { userName: 'john' } });
+navigate('order', { params: { orderId: 123 } });
+
+// By URL directly
+navigate('/users/john');
+navigate('/orders/123');
+
+// To a specific target
+navigate('preview', { params: { id: '42' }, target: 'modal' });
+```
+
+## Multiple Targets
+
+Routes can render in different [`<r-route-target>`](RoutingTarget.md) elements:
+
+```html
+<div class="layout">
+    <aside>
+        <r-route-target name="sidebar"></r-route-target>
+    </aside>
+    <main>
+        <r-route-target></r-route-target>
+    </main>
+</div>
+```
+
+```typescript
+const routes: Route[] = [
+    { name: 'home', path: '/', componentTagName: 'home-page' },
+    { name: 'menu', path: '/menu', target: 'sidebar', componentTagName: 'nav-menu' },
+];
+```
+
+Routes without a `target` property render in the default (unnamed) target.
+
+## Browser History
+
+The router integrates with the browser's History API:
+
+- `navigate()` calls `history.pushState()` to add entries
+- Back/forward buttons trigger navigation to previous routes (components receive `loadRoute` again)
+- `startRouting()` reads the current URL and navigates on page load
+
+URLs display the route path (e.g., `/users/john`), not the HTML file.
+
+## Layouts
+
+Different parts of your application may need different HTML shells (navigation, sidebar presence, etc.). See [Layouts](layouts.md) for details.
+
+```typescript
+const routes: Route[] = [
+    { name: 'login', path: '/login', componentTagName: 'login-page', layout: 'public' },
+    { name: 'dashboard', path: '/dashboard', componentTagName: 'dashboard-page' }, // default layout
+];
+```
+
+When navigating between layouts, the router redirects to the appropriate HTML file and resumes navigation.
+
+## Route Guards
+
+Guards control access to routes:
+
+```typescript
+import { RouteGuard, GuardResult, RouteMatchResult } from '@relax.js/core/routing';
+
+class AuthGuard implements RouteGuard {
+    check(route: RouteMatchResult): GuardResult {
+        if (isAuthenticated()) {
+            return GuardResult.Continue;  // Check other guards
+        }
+        navigate('login');
+        return GuardResult.Stop;  // Prevent navigation
+    }
+}
+
+const routes: Route[] = [
+    { name: 'dashboard', path: '/dashboard', componentTagName: 'dashboard-page', guards: [new AuthGuard()] },
+];
+```
+
+### Guard Results
+
+| Result | Behavior |
+|--------|----------|
+| `Allow` | Proceed immediately, skip remaining guards |
+| `Continue` | Check next guard (or proceed if none left) |
+| `Stop` | Cancel navigation silently |
+| `Deny` | Cancel navigation and throw `RouteGuardError` |
+
+## Events
+
+Navigation dispatches `NavigateRouteEvent` on `document`:
+
+```typescript
+import { NavigateRouteEvent } from '@relax.js/core/routing';
+
+document.addEventListener('rlx.navigateRoute', (e: NavigateRouteEvent) => {
+    console.log('Route:', e.route.name);
+    console.log('Params:', e.routeData);
+    console.log('Target:', e.routeTarget ?? 'default');
+});
+```
+
+This event is typed in `HTMLElementEventMap` for full TypeScript support.
+
+## Route Matching
+
+For advanced use cases, match routes without navigating:
+
+```typescript
+import { matchRoute, findRouteByUrl, findRouteByName } from '@relax.js/core/routing';
+
+// Match by URL
+const result = matchRoute(routes, '/users/john');
+// { route: {...}, params: { userName: 'john' }, urlSegments: ['users', 'john'] }
+
+// Match by name
+const result = matchRoute(routes, 'user', { userName: 'john' });
+
+// Direct functions
+findRouteByUrl(routes, '/users/john');
+findRouteByName(routes, 'user', { userName: 'john' });
+```
+
+## Receiving Route Parameters
+
+Components rendered by `<r-route-target>` can receive route parameters in two ways.
+
+### loadRoute (async initialization)
+
+Implement `loadRoute()` to run async setup before the component is added to the DOM. The component is not visible until `loadRoute()` completes.
+
+```typescript
+import { LoadRoute, RouteData } from '@relax.js/core/routing';
+
+class OrderDetail extends HTMLElement implements LoadRoute<{ orderId: number }> {
+    private order: Order;
+
+    async loadRoute(data: { orderId: number }) {
+        this.order = await fetchOrder(data.orderId);
+    }
+
+    connectedCallback() {
+        this.render(this.order);
+    }
+}
+```
+
+### routeData (typed property)
+
+Implement `Routable` to receive parameters as a typed property. The property is optional since it's set by the router after construction.
+
+```typescript
+import { Routable } from '@relax.js/core/routing';
+
+class UserProfile extends HTMLElement implements Routable<{ userName: string }> {
+    routeData?: { userName: string };
+}
+```
+
+For convention-based usage without the interface, declare `routeData` directly on your component. The router always assigns it regardless.
+
+Both can be combined. `loadRoute()` runs first, then `routeData` is assigned.
+
+## Error Handling
+
+```typescript
+import { RouteError, RouteGuardError } from '@relax.js/core/routing';
+
+try {
+    navigate('unknown-route');
+} catch (e) {
+    if (e instanceof RouteGuardError) {
+        console.log('Access denied');
+    } else if (e instanceof RouteError) {
+        console.log('Route not found');
+    }
+}
+```
+
+When no route matches, the error message lists all available routes for debugging.
+
+Routing errors are reported through the global [error handler](../Errors.md). The error context contains:
+
+| Field | Description |
+|-------|-------------|
+| `route` | Route name |
+| `componentTagName` | Custom element tag name |
+| `component` | Component class name (if using class reference) |
+| `routeData` | Parameters extracted from the URL |
+
+## API Reference
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `defineRoutes(routes)` | Register routes at startup |
+| `startRouting()` | Initialize router and navigate to current URL |
+| `navigate(nameOrUrl, options?)` | Navigate to a route |
+| `matchRoute(routes, nameOrUrl, params?)` | Match without navigating |
+| `findRouteByUrl(routes, path)` | Match by URL pattern |
+| `findRouteByName(routes, name, params)` | Match by route name |
+
+### Types
+
+```typescript
+type RouteParamType = string | number;
+type RouteData = Record<string, RouteParamType>;
+
+interface NavigateOptions {
+    params?: Record<string, string | number>;
+    target?: string;
+    routes?: Route[];  // Override registered routes
+}
+
+interface RouteMatchResult {
+    route: Route;
+    params: RouteData;
+    urlSegments: string[];
+}
+
+enum GuardResult {
+    Allow,     // Proceed, skip remaining guards
+    Deny,      // Throw RouteGuardError
+    Continue,  // Check next guard
+    Stop       // Cancel silently
+}
+```
+
+## Related
+
+- [`<r-route-target>`](RoutingTarget.md) - Renders routed components
+- [`<r-link>`](RouteLink.md) - Declarative navigation links
+- [Layouts](layouts.md) - Multiple HTML shells