@relax.js/core 1.0.4 → 1.0.6

package/docs/api/media/Pipes.md

@@ -1,211 +0,0 @@
-# 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

@@ -1,332 +0,0 @@
-# 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