@relax.js/core 1.0.0

package/docs/DependencyInjection.md

@@ -0,0 +1,237 @@
+# 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 'relaxjs/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 'relaxjs/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:
+
+```typescript
+import { ContainerService, Inject } from 'relaxjs/di';
+
+@ContainerService({ inject: [] })
+class OrderService {
+    @Inject(LoggerService)
+    private logger!: LoggerService;
+
+    @Inject('primaryCache')  // resolve by string key
+    private cache!: CacheService;
+}
+```
+
+`@Inject` resolves the dependency immediately when the class is instantiated, so the field is available in all methods (including the constructor body).
+
+### 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;
+}
+```
+
+## Integration with Web Components
+
+```typescript
+@ContainerService({ inject: [UserService] })
+class UserProfileComponent extends HTMLElement {
+    constructor(private userService: UserService) {
+        super();
+    }
+
+    connectedCallback() {
+        this.loadProfile();
+    }
+
+    async loadProfile() {
+        const user = await this.userService.getCurrentUser();
+        this.render(user);
+    }
+}
+
+customElements.define('user-profile', UserProfileComponent);
+```
+
+## 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 'relaxjs/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

package/docs/Errors.md

@@ -0,0 +1,87 @@
+# Error Handling
+
+Global error handling for Relaxjs. Intercept errors before they throw, inspect structured context, and decide whether to suppress them.
+
+## Overview
+
+By default, Relaxjs throws a `RelaxError` when something goes wrong internally. Register a handler with `onError()` to intercept these errors. The handler receives an `ErrorContext` that lets you control whether the error is thrown.
+
+## Quick Start
+
+```typescript
+import { onError } from 'relaxjs/utils';
+
+onError((error, ctx) => {
+    console.log(error.message);
+    console.log(error.context);
+});
+```
+
+Errors still throw after the handler runs. Call `ctx.suppress()` to prevent that:
+
+```typescript
+onError((error, ctx) => {
+    logToService(error.message, error.context);
+    showToast(error.message);
+    ctx.suppress();
+});
+```
+
+## RelaxError
+
+Extends `Error` with a `context: Record<string, unknown>` field. The context contains specific information from the error source. For example, a routing error includes the route name, component tag, and route data. See each module's documentation for the context fields it provides.
+
+## ErrorContext
+
+The second argument passed to the handler. Call `suppress()` to prevent the error from being thrown.
+
+```typescript
+onError((error, ctx) => {
+    if (error.context.route === 'optional-sidebar') {
+        ctx.suppress();
+        return;
+    }
+
+    showErrorDialog(error.message);
+});
+```
+
+If the handler does not call `suppress()`, the `RelaxError` is thrown after the handler returns.
+
+## Using reportError
+
+Application code can route errors through the same handler using `reportError()`. It returns the `RelaxError` to throw, or `null` if the handler suppressed it:
+
+```typescript
+import { reportError } from 'relaxjs/utils';
+
+const error = reportError('Payment processing failed', {
+    orderId: 123,
+    provider: 'stripe',
+    statusCode: 500,
+});
+if (error) throw error;
+```
+
+## API Reference
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `onError(handler)` | Register a global error handler. Replaces any previous handler. |
+| `reportError(message, context)` | Create and report a `RelaxError`. Returns the error to throw, or `null` if suppressed. |
+
+### Types
+
+```typescript
+interface ErrorContext {
+    suppress(): void;
+}
+
+class RelaxError extends Error {
+    context: Record<string, unknown>;
+}
+
+type ErrorHandler = (error: RelaxError, ctx: ErrorContext) => void;
+```

package/docs/GettingStarted.md

@@ -0,0 +1,231 @@
+Getting Started
+===============
+
+Relaxjs is designed for gradual adoption. Start with full control using vanilla web components, then progressively add features like templating and routing as your app grows.
+
+## Installation
+
+```
+npm i -S relaxjs
+```
+
+---
+
+## Level 1: Plain Web Components
+
+Start with standard custom elements. No Relaxjs features are needed, just your components in HTML.
+
+```html
+<!-- index.html -->
+<body>
+    <my-header></my-header>
+    <my-content></my-content>
+</body>
+```
+
+```ts
+// my-header.ts
+export class MyHeader extends HTMLElement {
+    connectedCallback() {
+        this.innerHTML = `<h1>My App</h1>`;
+    }
+}
+customElements.define('my-header', MyHeader);
+```
+
+You're in complete control. Relaxjs components like `<r-input>`, `<r-button>`, etc. work alongside your own.
+
+---
+
+## Level 2: Add Templating with `html()`
+
+When your components get complex, use `html()` for reactive templates and data binding.
+
+```ts
+import { html } from 'relaxjs/html';
+
+export class UserCard extends HTMLElement {
+    private user = { name: 'Alice', role: 'Admin' };
+
+    connectedCallback() {
+        const result = html`
+            <div class="card">
+                <h2>{{name}}</h2>
+                <span>{{role}}</span>
+                <button onclick=${() => this.edit()}>Edit</button>
+            </div>
+        `(this.user);
+        this.appendChild(result.fragment);
+    }
+
+    private edit() {
+        // Handle edit
+    }
+}
+customElements.define('user-card', UserCard);
+```
+
+Still no routing. You control navigation yourself.
+
+---
+
+## Level 3: Manual Navigation
+
+Swap content programmatically while staying in full control.
+
+```ts
+import { html } from 'relaxjs/html';
+
+export class AppShell extends HTMLElement {
+    private main!: HTMLElement;
+
+    connectedCallback() {
+        const result = html`
+            <nav>
+                <a onclick=${() => this.showMain()}>Home</a>
+                <a onclick=${() => this.showSettings()}>Settings</a>
+            </nav>
+            <main></main>
+        `({});
+        this.appendChild(result.fragment);
+        this.main = this.querySelector('main')!;
+        this.main.innerHTML = '<home-page></home-page>';
+    }
+
+    private showMain() {
+        this.main.innerHTML = '<home-page></home-page>';
+    }
+    private showSettings() {
+        this.main.innerHTML = '<settings-page></settings-page>';
+    }
+}
+customElements.define('app-shell', AppShell);
+```
+
+---
+
+## Level 4: Simple Routing
+
+When your app has multiple pages and you want URL-based navigation, add routing.
+
+```ts
+import { Route, defineRoutes, startRouting } from 'relaxjs/routing';
+
+const routes: Route[] = [
+    { name: 'home', path: '/', componentTagName: 'home-page' },
+    { name: 'settings', path: '/settings', componentTagName: 'settings-page' },
+    { name: 'profile', path: '/profile/:id', componentTagName: 'profile-page' },
+];
+
+defineRoutes(routes);
+startRouting();
+```
+
+```html
+<!-- index.html -->
+<body>
+    <nav>
+        <r-link name="home">Home</r-link>
+        <r-link name="settings">Settings</r-link>
+        <r-link name="profile" param-id="123">Profile</r-link>
+    </nav>
+    <r-route-target></r-route-target>
+</body>
+```
+
+The `<r-link>` component handles navigation by route name. Use `param-*` attributes for route parameters. The `<r-route-target>` renders the matched component.
+
+---
+
+## Level 5: Programmatic Navigation
+
+Use `navigate()` for code-driven navigation.
+
+```ts
+import { navigate } from 'relaxjs/routing';
+
+// Navigate by route name with params
+navigate('profile', { params: { id: '123' } });
+
+// Navigate by path
+navigate('/settings');
+```
+
+---
+
+## Level 6: Route Guards
+
+Protect routes with guards when you need authentication or authorization.
+
+```ts
+// guards.ts
+import { RouteGuard, RouteMatchResult, GuardResult, navigate } from 'relaxjs/routing';
+
+export class AuthGuard implements RouteGuard {
+    check(route: RouteMatchResult): GuardResult {
+        const token = localStorage.getItem('token');
+        if (!token) {
+            navigate('login');
+            return GuardResult.Stop;
+        }
+        return GuardResult.Continue;
+    }
+}
+```
+
+```ts
+// app.ts
+import { Route, defineRoutes } from 'relaxjs/routing';
+import { AuthGuard } from './guards';
+
+const authGuard = new AuthGuard();
+
+const routes: Route[] = [
+    { name: 'login', path: '/login', componentTagName: 'login-page' },
+    { name: 'home', path: '/', componentTagName: 'home-page', guards: [authGuard] },
+    { name: 'admin', path: '/admin', componentTagName: 'admin-page', guards: [authGuard] },
+];
+
+defineRoutes(routes);
+```
+
+---
+
+## Level 7: Layouts
+
+Use different HTML pages for distinct UI structures. Each layout is a separate static HTML file.
+
+```
+/index.html      <- default layout (authenticated app)
+/public.html     <- public layout (login, register)
+```
+
+```ts
+const routes: Route[] = [
+    // Routes using public.html
+    { name: 'login', path: '/login', componentTagName: 'login-page', layout: 'public' },
+    { name: 'register', path: '/register', componentTagName: 'register-page', layout: 'public' },
+
+    // Routes using index.html (default)
+    { name: 'dashboard', path: '/', componentTagName: 'dashboard-page' },
+    { name: 'settings', path: '/settings', componentTagName: 'settings-page' },
+];
+```
+
+When navigating between layouts, the router redirects to the appropriate HTML file automatically.
+
+---
+
+## Summary
+
+| Level | Features | Use When |
+|-------|----------|----------|
+| 1 | Plain components | Starting out, simple pages |
+| 2 | `html()` templating | Complex component rendering |
+| 3 | Manual navigation | Few views, full control needed |
+| 4 | Basic routing | Multiple pages, URL sync needed |
+| 5 | `navigate()` | Code-driven navigation |
+| 6 | Guards | Auth/access control |
+| 7 | Layouts | Shared UI structure |
+
+Start at Level 1 and add features as your app requires them. You're always in control.