npm - @relax.js/core - Versions diffs - 1.0.3 → 1.0.5 - Mend

@relax.js/core 1.0.3 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (90) hide show

package/README.md +194 -188
package/dist/DependencyInjection.d.ts +45 -27
package/dist/collections/LinkedList.d.ts +9 -8
package/dist/collections/index.js +1 -1
package/dist/collections/index.js.map +3 -3
package/dist/collections/index.mjs +1 -1
package/dist/collections/index.mjs.map +3 -3
package/dist/di/index.js +1 -1
package/dist/di/index.js.map +3 -3
package/dist/di/index.mjs +1 -1
package/dist/di/index.mjs.map +3 -3
package/dist/elements/index.js +1 -1
package/dist/elements/index.js.map +1 -1
package/dist/errors.d.ts +20 -0
package/dist/forms/FormValidator.d.ts +3 -22
package/dist/forms/ValidationRules.d.ts +4 -6
package/dist/forms/index.js +1 -1
package/dist/forms/index.js.map +4 -4
package/dist/forms/index.mjs +1 -1
package/dist/forms/index.mjs.map +4 -4
package/dist/forms/setFormData.d.ts +39 -1
package/dist/html/TableRenderer.d.ts +1 -0
package/dist/html/index.js +1 -1
package/dist/html/index.js.map +3 -3
package/dist/html/index.mjs +1 -1
package/dist/html/index.mjs.map +3 -3
package/dist/html/template.d.ts +4 -0
package/dist/http/ServerSentEvents.d.ts +1 -1
package/dist/http/SimpleWebSocket.d.ts +1 -1
package/dist/http/http.d.ts +1 -0
package/dist/http/index.js +1 -1
package/dist/http/index.js.map +3 -3
package/dist/http/index.mjs +1 -1
package/dist/http/index.mjs.map +3 -3
package/dist/i18n/icu.d.ts +1 -1
package/dist/i18n/index.js +1 -1
package/dist/i18n/index.js.map +2 -2
package/dist/i18n/index.mjs +1 -1
package/dist/i18n/index.mjs.map +2 -2
package/dist/index.js +3 -3
package/dist/index.js.map +3 -3
package/dist/index.mjs +3 -3
package/dist/index.mjs.map +3 -3
package/dist/routing/NavigateRouteEvent.d.ts +4 -4
package/dist/routing/index.js +3 -3
package/dist/routing/index.js.map +3 -3
package/dist/routing/index.mjs +3 -3
package/dist/routing/index.mjs.map +3 -3
package/dist/routing/navigation.d.ts +1 -1
package/dist/routing/routeTargetRegistry.d.ts +1 -0
package/dist/routing/types.d.ts +2 -1
package/dist/templates/NodeTemplate.d.ts +3 -1
package/dist/utils/index.d.ts +1 -1
package/dist/utils/index.js +1 -1
package/dist/utils/index.js.map +3 -3
package/dist/utils/index.mjs +1 -1
package/dist/utils/index.mjs.map +3 -3
package/docs/Architecture.md +333 -333
package/docs/DependencyInjection.md +277 -237
package/docs/Errors.md +87 -87
package/docs/GettingStarted.md +238 -231
package/docs/Pipes.md +5 -5
package/docs/Translations.md +167 -312
package/docs/WhyRelaxjs.md +336 -336
package/docs/api.json +93193 -0
package/docs/elements/dom.md +102 -102
package/docs/forms/creating-form-components.md +924 -924
package/docs/forms/form-api.md +94 -94
package/docs/forms/forms.md +99 -99
package/docs/forms/patterns.md +311 -311
package/docs/forms/reading-writing.md +465 -365
package/docs/forms/validation.md +351 -351
package/docs/html/TableRenderer.md +291 -291
package/docs/html/html.md +175 -175
package/docs/html/index.md +54 -54
package/docs/html/template.md +422 -422
package/docs/http/HttpClient.md +459 -459
package/docs/http/ServerSentEvents.md +184 -184
package/docs/http/index.md +109 -109
package/docs/i18n/i18n.md +49 -4
package/docs/i18n/intl-standard.md +178 -178
package/docs/routing/RouteLink.md +98 -98
package/docs/routing/Routing.md +332 -332
package/docs/routing/layouts.md +207 -207
package/docs/setup/bootstrapping.md +154 -0
package/docs/setup/build-and-deploy.md +183 -0
package/docs/setup/project-structure.md +170 -0
package/docs/setup/vite.md +175 -0
package/docs/utilities.md +143 -143
package/package.json +4 -2

package/docs/routing/layouts.md CHANGED Viewed

@@ -1,207 +1,207 @@
-Layouts
-=======
-Layouts allow different HTML pages to serve as shells for different parts of your application. Common use cases:
-- Public pages (login, register) with minimal UI
-- Authenticated pages with navigation, sidebar, header
-- Admin pages with different structure
-## How It Works
-Each layout is a separate static HTML file. When navigating to a route with a different layout than the current one, the router:
-1. Stores the target route name and params in `sessionStorage`
-2. Redirects the browser to the new HTML file
-3. On the new page, `startRouting()` reads from `sessionStorage` and navigates to the intended route
-4. The URL is updated to show the route path (not the `.html` file)
-## File Structure
-```
-/index.html      <- default layout (no layout property needed)
-/public.html     <- public layout
-/admin.html      <- admin layout
-```
-## Route Configuration
-```ts
-import { Route, defineRoutes, startRouting } from 'relaxjs/routing';
-const routes: Route[] = [
-    // Uses public.html
-    { name: 'login', path: '/login', componentTagName: 'login-page', layout: 'public' },
-    { name: 'register', path: '/register', componentTagName: 'register-page', layout: 'public' },
-    // Uses index.html (default - no layout property needed)
-    { name: 'home', path: '/', componentTagName: 'home-page' },
-    { name: 'settings', path: '/settings', componentTagName: 'settings-page' },
-    // Uses admin.html
-    { name: 'admin', path: '/admin', componentTagName: 'admin-dashboard', layout: 'admin' },
-];
-defineRoutes(routes);
-startRouting();
-```
-## Layout HTML Files
-Each layout file must:
-- Include `<r-route-target>` where routed components render
-- Import and call `defineRoutes()` and `startRouting()`
-- Register all components that may be rendered in that layout
-### index.html (default layout)
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <title>My App</title>
-    <script type="module" src="/src/app.ts"></script>
-</head>
-<body>
-    <app-header></app-header>
-    <app-sidebar></app-sidebar>
-    <main>
-        <r-route-target></r-route-target>
-    </main>
-</body>
-</html>
-```
-### public.html
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <title>My App - Login</title>
-    <script type="module" src="/src/app.ts"></script>
-</head>
-<body>
-    <div class="auth-container">
-        <r-route-target></r-route-target>
-    </div>
-</body>
-</html>
-```
-## Layout Detection
-The router determines the current layout from the URL:
-| URL | Detected Layout |
-|-----|-----------------|
-| `/index.html` | `default` |
-| `/public.html` | `public` |
-| `/admin.html` | `admin` |
-| `/` or `/settings` | `default` (inferred) |
-## Navigation Flow
-When a user on `/settings` (default layout) navigates to `login` (public layout):
-1. `navigate('login')` is called
-2. Router detects layout mismatch: `default` !== `public`
-3. Stores `{ routeName: 'login', params: {} }` in `sessionStorage`
-4. Redirects browser to `/public.html#layout`
-5. `public.html` loads and calls `startRouting()`
-6. `startRouting()` reads from `sessionStorage`, calls `navigate('login')`
-7. URL updates to `/login`, `login-page` component renders
-## Shared Routes Configuration
-Since all layout files need the same routes, keep route configuration in a shared module:
-```ts
-// routes.ts
-import { Route } from 'relaxjs/routing';
-export const routes: Route[] = [
-    { name: 'login', path: '/login', componentTagName: 'login-page', layout: 'public' },
-    { name: 'home', path: '/', componentTagName: 'home-page' },
-    // ...
-];
-```
-```ts
-// app.ts (imported by all layout HTML files)
-import { defineRoutes, startRouting } from 'relaxjs/routing';
-import { routes } from './routes';
-defineRoutes(routes);
-startRouting();
-```
-## Error Handling
-If a layout redirect fails (e.g., the HTML file doesn't exist), the router throws an error:
-```
-A redirect failed, does the requested layout exist? "admin"?
-```
-The `#layout` hash in the redirect URL is used to detect this: if the hash is still present after redirect, something went wrong.
-## Security Considerations
-Layout files are static HTML served to the browser. This has security implications:
-### Route Exposure
-A file like `admin.html` contains (or imports) route configurations that reveal admin URLs. Anyone requesting the file can see what endpoints exist, even without authentication.
-### Client-Side Guards Are Not Security
-Route guards in Relaxjs prevent components from rendering, but they don't protect data. An attacker can:
-- Read the JavaScript bundle to find all routes
-- Call backend APIs directly, bypassing the UI entirely
-**The real security boundary is always your backend API.** Every API endpoint must validate authentication and authorization.
-### Server-Side Protection
-For defense in depth, protect sensitive layout files at the HTTP server level:
-**Nginx:**
-```nginx
-location /admin.html {
-    auth_request /auth/verify;
-    error_page 401 = @unauthorized;
-}
-location @unauthorized {
-    return 302 /login;
-}
-```
-**Express:**
-```ts
-app.get('/admin.html', verifyJwt, (req, res) => {
-    res.sendFile('admin.html');
-});
-```
-**Caddy:**
-```
-admin.html {
-    forward_auth /auth/verify
-}
-```
-### Alternatives
-If hiding routes is important:
-1. **Single layout with dynamic navigation**: Load admin navigation only after auth verification
-2. **Separate builds**: Build different bundles for public/authenticated/admin with different route configurations
-3. **Server-rendered shells**: Generate layout HTML server-side based on user role
-### Recommendation
-1. Always secure your backend APIs with proper authentication/authorization
-2. Protect sensitive layout files at the server level in production
-3. Don't rely on client-side guards for security. They're for UX, not protection
+Layouts
+=======
+Layouts allow different HTML pages to serve as shells for different parts of your application. Common use cases:
+- Public pages (login, register) with minimal UI
+- Authenticated pages with navigation, sidebar, header
+- Admin pages with different structure
+## How It Works
+Each layout is a separate static HTML file. When navigating to a route with a different layout than the current one, the router:
+1. Stores the target route name and params in `sessionStorage`
+2. Redirects the browser to the new HTML file
+3. On the new page, `startRouting()` reads from `sessionStorage` and navigates to the intended route
+4. The URL is updated to show the route path (not the `.html` file)
+## File Structure
+```
+/index.html      <- default layout (no layout property needed)
+/public.html     <- public layout
+/admin.html      <- admin layout
+```
+## Route Configuration
+```ts
+import { Route, defineRoutes, startRouting } from '@relax.js/core/routing';
+const routes: Route[] = [
+    // Uses public.html
+    { name: 'login', path: '/login', componentTagName: 'login-page', layout: 'public' },
+    { name: 'register', path: '/register', componentTagName: 'register-page', layout: 'public' },
+    // Uses index.html (default - no layout property needed)
+    { name: 'home', path: '/', componentTagName: 'home-page' },
+    { name: 'settings', path: '/settings', componentTagName: 'settings-page' },
+    // Uses admin.html
+    { name: 'admin', path: '/admin', componentTagName: 'admin-dashboard', layout: 'admin' },
+];
+defineRoutes(routes);
+startRouting();
+```
+## Layout HTML Files
+Each layout file must:
+- Include `<r-route-target>` where routed components render
+- Import and call `defineRoutes()` and `startRouting()`
+- Register all components that may be rendered in that layout
+### index.html (default layout)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>My App</title>
+    <script type="module" src="/src/app.ts"></script>
+</head>
+<body>
+    <app-header></app-header>
+    <app-sidebar></app-sidebar>
+    <main>
+        <r-route-target></r-route-target>
+    </main>
+</body>
+</html>
+```
+### public.html
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>My App - Login</title>
+    <script type="module" src="/src/app.ts"></script>
+</head>
+<body>
+    <div class="auth-container">
+        <r-route-target></r-route-target>
+    </div>
+</body>
+</html>
+```
+## Layout Detection
+The router determines the current layout from the URL:
+| URL | Detected Layout |
+|-----|-----------------|
+| `/index.html` | `default` |
+| `/public.html` | `public` |
+| `/admin.html` | `admin` |
+| `/` or `/settings` | `default` (inferred) |
+## Navigation Flow
+When a user on `/settings` (default layout) navigates to `login` (public layout):
+1. `navigate('login')` is called
+2. Router detects layout mismatch: `default` !== `public`
+3. Stores `{ routeName: 'login', params: {} }` in `sessionStorage`
+4. Redirects browser to `/public.html#layout`
+5. `public.html` loads and calls `startRouting()`
+6. `startRouting()` reads from `sessionStorage`, calls `navigate('login')`
+7. URL updates to `/login`, `login-page` component renders
+## Shared Routes Configuration
+Since all layout files need the same routes, keep route configuration in a shared module:
+```ts
+// routes.ts
+import { Route } from '@relax.js/core/routing';
+export const routes: Route[] = [
+    { name: 'login', path: '/login', componentTagName: 'login-page', layout: 'public' },
+    { name: 'home', path: '/', componentTagName: 'home-page' },
+    // ...
+];
+```
+```ts
+// app.ts (imported by all layout HTML files)
+import { defineRoutes, startRouting } from '@relax.js/core/routing';
+import { routes } from './routes';
+defineRoutes(routes);
+startRouting();
+```
+## Error Handling
+If a layout redirect fails (e.g., the HTML file doesn't exist), the router throws an error:
+```
+A redirect failed, does the requested layout exist? "admin"?
+```
+The `#layout` hash in the redirect URL is used to detect this: if the hash is still present after redirect, something went wrong.
+## Security Considerations
+Layout files are static HTML served to the browser. This has security implications:
+### Route Exposure
+A file like `admin.html` contains (or imports) route configurations that reveal admin URLs. Anyone requesting the file can see what endpoints exist, even without authentication.
+### Client-Side Guards Are Not Security
+Route guards in Relaxjs prevent components from rendering, but they don't protect data. An attacker can:
+- Read the JavaScript bundle to find all routes
+- Call backend APIs directly, bypassing the UI entirely
+**The real security boundary is always your backend API.** Every API endpoint must validate authentication and authorization.
+### Server-Side Protection
+For defense in depth, protect sensitive layout files at the HTTP server level:
+**Nginx:**
+```nginx
+location /admin.html {
+    auth_request /auth/verify;
+    error_page 401 = @unauthorized;
+}
+location @unauthorized {
+    return 302 /login;
+}
+```
+**Express:**
+```ts
+app.get('/admin.html', verifyJwt, (req, res) => {
+    res.sendFile('admin.html');
+});
+```
+**Caddy:**
+```
+admin.html {
+    forward_auth /auth/verify
+}
+```
+### Alternatives
+If hiding routes is important:
+1. **Single layout with dynamic navigation**: Load admin navigation only after auth verification
+2. **Separate builds**: Build different bundles for public/authenticated/admin with different route configurations
+3. **Server-rendered shells**: Generate layout HTML server-side based on user role
+### Recommendation
+1. Always secure your backend APIs with proper authentication/authorization
+2. Protect sensitive layout files at the server level in production
+3. Don't rely on client-side guards for security. They're for UX, not protection

package/docs/setup/bootstrapping.md ADDED Viewed

@@ -0,0 +1,154 @@
+Bootstrapping
+=============
+Relaxjs apps need three subsystems started in the right order: **dependency injection**, **i18n**, and **routing** (if used). Getting the order wrong produces "why is my service undefined?" bugs that are hard to trace.
+This page shows the safe pattern for `src/main.ts`.
+---
+## The rule
+> Register services **before** any component that uses `@Inject` is constructed.
+> Load i18n namespaces **before** you render anything that calls `t()`.
+> Start routing **last**.
+A custom element is constructed the moment two things line up: the tag is defined with `customElements.define(...)` **and** the tag appears in the DOM. If DI is not ready at that moment, the component's `@Inject` fields become `undefined`.
+---
+## Minimal `main.ts`
+```ts
+// 1. Import service modules first so their @ContainerService decorators run.
+import './services/ApiClient';
+import './services/UserService';
+// 2. Import component modules. Each file ends with customElements.define(...)
+//    but the tags don't render yet unless they are in index.html.
+import './components/HomePage';
+import './components/UserPanel';
+// 3. Relaxjs subsystems
+import { setLocale, loadNamespaces } from '@relax.js/core/i18n';
+import { defineRoutes, startRouting } from '@relax.js/core/routing';
+async function bootstrap() {
+    // i18n before anything calls t()
+    await setLocale(navigator.language || 'en');
+    await loadNamespaces(['r-validation']);
+    // Routing last — this is when components start mounting
+    defineRoutes([
+        { name: 'home', path: '/', componentTagName: 'home-page' },
+        { name: 'profile', path: '/profile/:id', componentTagName: 'user-panel' },
+    ]);
+    startRouting();
+}
+bootstrap();
+```
+The matching `index.html`:
+```html
+<!DOCTYPE html>
+<html>
+<body>
+    <r-route-target></r-route-target>
+    <script type="module" src="/src/main.ts"></script>
+</body>
+</html>
+```
+Notice the body contains **only** `<r-route-target>`. Page components are created by the router after `startRouting()` runs, so they never construct before DI and i18n are ready.
+---
+## Why the import order matters
+TypeScript imports run top-to-bottom. Decorator side effects (registering a service, defining a custom element) happen at import time.
+If you flip the order:
+```ts
+import './components/UserPanel';   // ❌ custom element defined
+import './services/UserService';   // ❌ service registered AFTER
+```
+...and `<user-panel>` appears in `index.html`, the browser constructs it before `UserService` is registered. Every `@Inject(UserService)` field resolves to `undefined`.
+**Always import services before components.** Then import subsystems (i18n, routing) last.
+---
+## Manual registration (when you can't use decorators)
+Some services wrap existing instances (config objects, third-party clients). Register them before the `bootstrap()` call:
+```ts
+import { serviceCollection } from '@relax.js/core/di';
+const config = {
+    apiUrl: import.meta.env.VITE_API_URL ?? '/api',
+};
+serviceCollection.register(ConfigService, {
+    inject: [],
+    instance: config,
+});
+```
+Do this at the top of `main.ts`, before the subsystem imports.
+---
+## Components that don't use routing
+If your app uses [Level 1-3 patterns](../GettingStarted.md) (plain components, no router), the same rule applies, just without `startRouting()`:
+```ts
+import './services/ApiClient';
+import './components/AppShell';   // defines <app-shell>
+import { setLocale, loadNamespaces } from '@relax.js/core/i18n';
+async function bootstrap() {
+    await setLocale('en');
+    await loadNamespaces(['r-validation']);
+    // Insert the root component now that everything is ready
+    document.body.appendChild(document.createElement('app-shell'));
+}
+bootstrap();
+```
+Key point: the root component is appended **after** async setup, not written directly in `index.html`.
+---
+## Common mistakes
+### `@Inject` field is undefined
+Cause: a component constructed before its service was registered. Fix: move the service import above the component import in `main.ts`.
+### `t('...')` returns the key unchanged
+Cause: the namespace wasn't loaded, or the component rendered before `setLocale()` finished. Fix: `await loadNamespaces([...])` before rendering, and re-render on `localechange` if the user can switch locales.
+### Routing renders a blank page
+Cause: `startRouting()` ran before `defineRoutes(...)`. Fix: always call `defineRoutes` first.
+---
+## Summary
+1. Import service modules (side-effect imports run `@ContainerService`)
+2. Import component modules (`customElements.define`)
+3. `await setLocale(...)` and `await loadNamespaces(...)`
+4. `defineRoutes(...)` then `startRouting()`
+If you follow this order every time, components never see an undefined service or a missing translation.