@relax.js/core 1.0.4 → 1.0.6

package/docs/api/media/Architecture.md

@@ -1,333 +0,0 @@
-# Architecture Overview
-
-Relaxjs is a library for building web applications with Web Components. It emphasizes explicit control, direct DOM manipulation, and predictable behavior.
-
-## Philosophy
-
-Unlike modern SPA frameworks, Relaxjs takes an explicit approach:
-
-- **No virtual DOM**: The real DOM is the source of truth
-- **No hidden reactivity**: Changes happen when you explicitly make them
-- **No synthetic lifecycle**: Uses native Web Component lifecycle hooks
-- **Full developer control**: You always know what triggered what
-
-## Core Modules
-
-```
-@relax.js/core
-├── Routing          # SPA navigation with guards and layouts
-├── Forms            # Data binding, validation, type conversion
-├── DI               # Dependency injection container
-├── HTTP             # Fetch wrapper and WebSocket client
-├── i18n             # Internationalization with ICU support
-├── Templates        # HTML templating with data binding
-└── Components       # Pre-built UI components
-```
-
-## Module Integration
-
-### Application Startup
-
-```typescript
-import { defineRoutes, startRouting } from '@relax.js/core/routing';
-import { setLocale } from '@relax.js/core/i18n';
-import { serviceCollection } from '@relax.js/core/di';
-
-class Application extends HTMLElement {
-    async connectedCallback() {
-        // 1. Register services
-        serviceCollection.registerByType(ApiService, { inject: [] });
-        serviceCollection.registerByType(AuthService, { inject: [ApiService] });
-
-        // 2. Set locale
-        await setLocale(navigator.language);
-
-        // 3. Define routes
-        defineRoutes([
-            { name: 'home', path: '/', componentTagName: 'app-home' },
-            { name: 'login', path: '/login', componentTagName: 'login-page' }
-        ]);
-
-        // 4. Start routing
-        startRouting();
-    }
-}
-
-customElements.define('app-main', Application);
-```
-
-### Component Pattern
-
-```typescript
-class UserProfile extends HTMLElement {
-    private form: HTMLFormElement;
-    private validator: FormValidator;
-
-    connectedCallback() {
-        this.innerHTML = `
-            <form>
-                <input name="name" required>
-                <input name="email" type="email" required>
-                <button type="submit">Save</button>
-            </form>
-        `;
-
-        this.form = this.querySelector('form')!;
-        this.validator = new FormValidator(this.form, {
-            submitCallback: () => this.save()
-        });
-
-        this.loadUser();
-    }
-
-    async loadUser() {
-        const api = container.resolve(ApiService);
-        const user = await api.get('/user/profile');
-        setFormData(this.form, user.as<User>());
-    }
-
-    async save() {
-        const data = readData(this.form);
-        const api = container.resolve(ApiService);
-        await api.put('/user/profile', JSON.stringify(data));
-    }
-}
-
-customElements.define('user-profile', UserProfile);
-```
-
-## Data Flow
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    User Action                           │
-└─────────────────────────────────────────────────────────┘
-                           │
-                           ▼
-┌─────────────────────────────────────────────────────────┐
-│                  Event Handler                           │
-│                                                          │
-│   element.addEventListener('click', (e) => {             │
-│       // Explicit action                                 │
-│   });                                                    │
-└─────────────────────────────────────────────────────────┘
-                           │
-                           ▼
-┌─────────────────────────────────────────────────────────┐
-│                    DOM Update                            │
-│                                                          │
-│   // Direct manipulation                                 │
-│   element.textContent = newValue;                        │
-│   element.setAttribute('data-state', 'active');          │
-└─────────────────────────────────────────────────────────┘
-```
-
-## Routing Architecture
-
-```
-┌──────────────┐    navigate()     ┌──────────────────┐
-│   User       │ ────────────────► │   Router         │
-│   Action     │                   │                  │
-└──────────────┘                   │  - Match route   │
-                                   │  - Check guards  │
-                                   │  - Update URL    │
-                                   └────────┬─────────┘
-                                            │
-                                   NavigateRouteEvent
-                                            │
-                                            ▼
-                                   ┌──────────────────┐
-                                   │  r-route-target│
-                                   │                  │
-                                   │  - Load component│
-                                   │  - Pass params   │
-                                   └──────────────────┘
-```
-
-### Multiple Targets
-
-```html
-<body>
-    <r-route-target>
-        <!-- Main content renders here -->
-    </r-route-target>
-
-    <r-route-target name="modal">
-        <!-- Modal content renders here -->
-    </r-route-target>
-
-    <r-route-target name="sidebar">
-        <!-- Sidebar content renders here -->
-    </r-route-target>
-</body>
-```
-
-```typescript
-// Navigate to specific target
-navigate('userDetails', { params: { id: '123' }, target: 'modal' });
-```
-
-## Form Data Flow
-
-```
-┌─────────────┐     setFormData()    ┌─────────────────────────────────────┐
-│  Data       │ ──────────────────►  │  Form Elements & Custom Components  │
-│  Object     │                      │                                     │
-└─────────────┘                      │  <input> <select> <textarea>        │
-                                     │  <r-input> <r-checkbox> (FORM API)  │
-      ▲                              └────────┬────────────────────────────┘
-      │                                       │
-      │   readData()                    User edits
-      │                                       │
-      │                                       ▼
-┌─────┴───────┐     FormValidator    ┌─────────────────┐
-│  Updated    │ ◄─────────────────── │  Validation     │
-│  Object     │                      │                 │
-└─────────────┘                      │  - HTML5        │
-                                     │  - Custom rules │
-                                     │  - FORM API     │
-                                     │    components   │
-                                     └─────────────────┘
-```
-
-### Form Component Support
-
-The form utilities support both native HTML form elements and modern form-associated custom elements (those implementing the FORM API with `ElementInternals`). This means:
-
-- **Native elements**: `<input>`, `<select>`, `<textarea>` work as expected
-- **Custom components**: Web components like `<r-input>`, `<r-checkbox>`, `<r-select>` that use `ElementInternals` and `formAssociated = true` are fully integrated
-- **No API differences**: Both types are handled identically by `setFormData()`, `readData()`, `mapFormToClass()`, and `FormValidator`
-
-## Template Rendering
-
-### Static Templates (html)
-
-```typescript
-const template = html`
-    <div class="card">
-        <h2>${'title'}</h2>
-        <p>${'description'}</p>
-    </div>
-`;
-
-// Creates new DOM each time
-const fragment = template({ title: 'Hello', description: 'World' });
-container.appendChild(fragment);
-```
-
-### Updateable Templates (html)
-
-```typescript
-const template = html`
-    <div class="user">
-        <span>{{name}}</span>
-        <span>{{score|number}}</span>
-    </div>
-`;
-
-const rendered = template({ name: 'John', score: 42 });
-container.appendChild(rendered.fragment);
-
-// Later, update without recreating DOM
-rendered.update({ name: 'Jane', score: 100 });
-```
-
-## Service Architecture
-
-```
-┌────────────────────────────────────────────────────────┐
-│                  ServiceCollection                      │
-│                                                         │
-│   Register services with metadata:                      │
-│   - Constructor dependencies                            │
-│   - Property injections                                 │
-│   - Scope (global/closest)                             │
-└───────────────────────────┬────────────────────────────┘
-                            │
-                            │ Configuration
-                            ▼
-┌────────────────────────────────────────────────────────┐
-│                  ServiceContainer                       │
-│                                                         │
-│   Resolve services:                                     │
-│   1. Check cache (for singletons)                       │
-│   2. Resolve dependencies                               │
-│   3. Create instance                                    │
-│   4. Inject properties                                  │
-│   5. Cache if global scope                              │
-└────────────────────────────────────────────────────────┘
-```
-
-## File Organization
-
-Recommended project structure:
-
-```
-src/
-├── components/
-│   ├── forms/           # Form-related components
-│   ├── lists/           # List/table components
-│   └── shared/          # Shared UI components
-├── pages/               # Route components
-├── services/            # Business logic services
-├── guards/              # Route guards
-├── models/              # TypeScript interfaces/types
-└── app.ts              # Application entry point
-```
-
-## Best Practices
-
-1. **Use native HTML when possible**: Don't create components for things HTML already does well
-
-2. **Keep components small**: Each component should do one thing
-
-3. **Form Components Use FORM API**: When building custom form components, use the HTML Form API with `ElementInternals` and `formAssociated = true`. All RelaxJS form utilities automatically support these components without any special handling:
-
-```typescript
-class CustomCheckbox extends HTMLElement {
-  static formAssociated = true;
-  
-  private internals: ElementInternals;
-  
-  constructor() {
-    super();
-    this.internals = this.attachInternals();
-  }
-  
-  connectedCallback() {
-    const checkbox = document.createElement('input');
-    checkbox.type = 'checkbox';
-    this.appendChild(checkbox);
-    
-    checkbox.addEventListener('change', () => {
-      this.internals.setFormValue(checkbox.checked ? 'on' : '');
-    });
-  }
-  
-  get checked() { return (this.querySelector('input') as HTMLInputElement).checked; }
-  set checked(v) { (this.querySelector('input') as HTMLInputElement).checked = v; }
-  
-  get value() { return this.getAttribute('value') || 'on'; }
-}
-
-customElements.define('r-checkbox', CustomCheckbox);
-```
-
-Once defined, use it seamlessly with form utilities:
-
-```typescript
-const form = document.querySelector('form');
-const data = { termsAccepted: true };
-setFormData(form, data);  // Works with <r-checkbox name="termsAccepted"></r-checkbox>
-
-const extracted = readData(form);  // Extracts values from custom components
-const validator = new FormValidator(form);  // Validates custom components
-```
-
-3. **Explicit over implicit**: Prefer explicit method calls over magic bindings
-
-4. **Type everything**: Use TypeScript interfaces for all data structures
-
-5. **CSS variables for theming**: Use semantic variable names
-
-6. **Form-associated components**: Use `ElementInternals` for custom form controls

package/docs/api/media/DependencyInjection.md

@@ -1,277 +0,0 @@
-# Dependency Injection
-
-A lightweight IoC container for managing service dependencies in your application.
-
-## Overview
-
-The DI system provides:
-- Constructor injection
-- Property injection
-- Singleton and scoped lifetimes
-- Decorator-based registration
-
-## Quick Start
-
-```typescript
-import { ContainerService, container } from '@relax.js/core/di';
-
-@ContainerService()
-class LoggerService {
-    log(message: string) {
-        console.log(`[LOG] ${message}`);
-    }
-}
-
-// Resolve and use
-const logger = container.resolve(LoggerService);
-logger.log('Hello!');
-```
-
-## Registration
-
-Use the `@ContainerService` decorator to register services:
-
-```typescript
-@ContainerService()
-class ConfigService {
-    apiUrl = '/api/v1';
-}
-
-@ContainerService({ inject: [ConfigService] })
-class ApiClient {
-    constructor(private config: ConfigService) {}
-
-    fetch(path: string) {
-        return fetch(this.config.apiUrl + path);
-    }
-}
-```
-
-### Manual Registration
-
-For cases where you can't use decorators (e.g. registering an existing instance):
-
-```typescript
-import { serviceCollection } from '@relax.js/core/di';
-
-// Register with existing instance
-const config = { apiUrl: '/api' };
-serviceCollection.register(ConfigService, {
-    inject: [],
-    instance: config
-});
-
-// Register with custom key
-serviceCollection.register(CacheService, {
-    key: 'primaryCache',
-    scope: 'global',
-    inject: []
-});
-```
-
-## Scopes
-
-### Global (Singleton)
-
-Same instance returned every time:
-
-```typescript
-@ContainerService({ scope: 'global' })
-class DatabaseConnection {
-    // ...
-}
-
-const db1 = container.resolve(DatabaseConnection);
-const db2 = container.resolve(DatabaseConnection);
-// db1 === db2
-```
-
-### Closest (Scoped)
-
-New instance for each container scope:
-
-```typescript
-@ContainerService({ scope: 'closest' })
-class RequestContext {
-    // ...
-}
-```
-
-## Constructor Injection
-
-Dependencies are passed to the constructor in order:
-
-```typescript
-@ContainerService({
-    inject: [LoggerService, ConfigService, DatabaseConnection]
-})
-class UserRepository {
-    constructor(
-        private logger: LoggerService,
-        private config: ConfigService,
-        private db: DatabaseConnection
-    ) {}
-}
-```
-
-## Property Injection
-
-### Using the `@Inject` Decorator
-
-The `@Inject` decorator resolves a dependency and assigns it to a class field.
-The service is resolved when the instance is created, so the field is available
-in all methods including `connectedCallback` for web components.
-
-```typescript
-import { ContainerService, Inject } from '@relax.js/core/di';
-
-@ContainerService({ inject: [] })
-class OrderService {
-    @Inject(LoggerService)
-    private logger!: LoggerService;
-
-    @Inject('primaryCache')  // resolve by string key
-    private cache!: CacheService;
-}
-```
-
-### Using the `properties` Option
-
-Alternatively, declare property injection in the registration options:
-
-```typescript
-@ContainerService({
-    inject: [],
-    properties: {
-        logger: LoggerService,
-        cache: 'primaryCache'  // string key
-    }
-})
-class OrderService {
-    logger!: LoggerService;
-    cache!: CacheService;
-}
-```
-
-## Using Services in Web Components
-
-Web components use `@Inject` to access services. Do not use `@ContainerService` on
-components since the browser creates them with zero constructor arguments.
-
-### Property Injection with @Inject
-
-```typescript
-import { Inject } from '@relax.js/core/di';
-
-class UserPanel extends HTMLElement {
-    @Inject(UserService)
-    private userService!: UserService;
-
-    @Inject(LoggerService)
-    private logger!: LoggerService;
-
-    connectedCallback() {
-        // Injected fields are resolved and ready to use
-        const user = this.userService.getCurrentUser();
-        this.logger.log('UserPanel connected');
-        this.render(user);
-    }
-}
-
-customElements.define('user-panel', UserPanel);
-```
-
-This works the same way regardless of how the component is created:
-
-```typescript
-// Created by application code
-document.createElement('user-panel');
-
-// Created by the browser from HTML
-// <user-panel></user-panel>
-```
-
-### Setup Order
-
-Register all services before defining custom elements. Services
-decorated with `@ContainerService` register themselves when imported,
-so import those modules first.
-
-```typescript
-// main.ts - application entry point
-
-// 1. Import services (registers them via @ContainerService)
-import './services/ApiClient';
-import './services/UserService';
-
-// 2. Register any manual services
-serviceCollection.register(ConfigService, {
-    inject: [],
-    instance: { apiUrl: '/api/v1' },
-});
-
-// 3. Define custom elements (components can now resolve services)
-import { UserPanel } from './components/UserPanel';
-customElements.define('user-panel', UserPanel);
-```
-
-## Resolving Dependencies
-
-```typescript
-// By class
-const service = container.resolve(MyService);
-
-// By string key
-const cache = container.resolve<CacheService>('primaryCache');
-```
-
-## Error Handling
-
-All DI errors go through the global [`onError`](Errors.md) handler, so you can log, display, or suppress them.
-
-### Resolution Errors
-
-Thrown when `resolve()` cannot find a registered service.
-
-| Field | Description |
-|-------|-------------|
-| `service` | The class name or string key that was requested |
-| `registeredTypes` | Array of all registered class names |
-| `registeredKeys` | Array of all registered string keys |
-
-```
-RelaxError: Failed to resolve service 'MyService'
-  { service: 'MyService', registeredTypes: ['LoggerService', 'ConfigService'], registeredKeys: ['primaryCache'] }
-```
-
-### Registration Errors
-
-Thrown during `register()` or `registerByType()` to catch configuration mistakes early.
-
-| Error | Context | Cause |
-|-------|---------|-------|
-| Service name collision | `{ service }` | Two different classes registered with the same class name |
-| Service key already registered | `{ key, existingClass, newClass }` | A string key is reused for a different class |
-| Instance and inject conflict | `{ service }` | Both `instance` and non-empty `inject` provided (`inject` is ignored) |
-
-### Suppressing Errors
-
-```typescript
-import { onError } from '@relax.js/core/utils';
-
-onError((error, ctx) => {
-    if (error.context.service === 'OptionalPlugin') {
-        ctx.suppress();
-        return;
-    }
-    console.error(error.message, error.context);
-});
-```
-
-## Best Practices
-
-1. **Register early**: Register all services at application startup
-2. **Prefer constructor injection**: More explicit than property injection
-3. **Use global scope for stateless services**: Like loggers, config
-4. **Use closest scope for request-specific data**: Like user context
-5. **Avoid circular dependencies**: Restructure to use events or mediators