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

@relax.js/core 1.0.4 → 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 (228) hide show

package/dist/DependencyInjection.d.ts +3 -3
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 +2 -2
package/dist/di/index.mjs +1 -1
package/dist/di/index.mjs.map +2 -2
package/dist/elements/index.js +1 -1
package/dist/elements/index.js.map +1 -1
package/dist/forms/FormValidator.d.ts +2 -2
package/dist/forms/ValidationRules.d.ts +2 -6
package/dist/forms/index.js +1 -1
package/dist/forms/index.js.map +3 -3
package/dist/forms/index.mjs +1 -1
package/dist/forms/index.mjs.map +3 -3
package/dist/forms/setFormData.d.ts +39 -1
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/http/ServerSentEvents.d.ts +1 -1
package/dist/http/SimpleWebSocket.d.ts +1 -1
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 +2 -2
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/templates/NodeTemplate.d.ts +1 -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/GettingStarted.md +7 -0
package/docs/api.json +34 -12
package/docs/forms/reading-writing.md +101 -1
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/package.json +3 -2
package/docs/api/.nojekyll +0 -1
package/docs/api/assets/hierarchy.js +0 -1
package/docs/api/assets/highlight.css +0 -120
package/docs/api/assets/icons.js +0 -18
package/docs/api/assets/icons.svg +0 -1
package/docs/api/assets/main.js +0 -60
package/docs/api/assets/navigation.js +0 -1
package/docs/api/assets/search.js +0 -1
package/docs/api/assets/style.css +0 -1633
package/docs/api/classes/http.WebSocketClient.html +0 -26
package/docs/api/classes/i18n.LocaleChangeEvent.html +0 -66
package/docs/api/classes/index.Blueprint.html +0 -3
package/docs/api/classes/index.BoundNode.html +0 -3
package/docs/api/classes/index.DigitsValidation.html +0 -10
package/docs/api/classes/index.FormValidator.html +0 -32
package/docs/api/classes/index.HttpError.html +0 -13
package/docs/api/classes/index.LinkedList.html +0 -26
package/docs/api/classes/index.NavigateRouteEvent.html +0 -76
package/docs/api/classes/index.Node.html +0 -15
package/docs/api/classes/index.PageSelectedEvent.html +0 -61
package/docs/api/classes/index.Pager.html +0 -4
package/docs/api/classes/index.RangeValidation.html +0 -15
package/docs/api/classes/index.RelaxError.html +0 -17
package/docs/api/classes/index.RequiredValidation.html +0 -10
package/docs/api/classes/index.RouteError.html +0 -11
package/docs/api/classes/index.RouteGuardError.html +0 -12
package/docs/api/classes/index.RouteLink.html +0 -779
package/docs/api/classes/index.RouteTarget.html +0 -788
package/docs/api/classes/index.SSEClient.html +0 -13
package/docs/api/classes/index.SSEDataEvent.html +0 -63
package/docs/api/classes/index.ServiceCollection.html +0 -28
package/docs/api/classes/index.ServiceContainer.html +0 -24
package/docs/api/classes/index.SortChangeEvent.html +0 -61
package/docs/api/classes/index.TableRenderer.html +0 -5
package/docs/api/classes/index.TableSorter.html +0 -4
package/docs/api/enums/index.GuardResult.html +0 -9
package/docs/api/functions/elements.formError.html +0 -6
package/docs/api/functions/elements.selectOne.html +0 -6
package/docs/api/functions/i18n.getCurrentLocale.html +0 -3
package/docs/api/functions/i18n.loadNamespace.html +0 -7
package/docs/api/functions/i18n.loadNamespaces.html +0 -6
package/docs/api/functions/i18n.onMissingTranslation.html +0 -7
package/docs/api/functions/i18n.setLocale.html +0 -7
package/docs/api/functions/i18n.setMessageFormatter.html +0 -7
package/docs/api/functions/i18n.t.html +0 -9
package/docs/api/functions/index.BooleanConverter.html +0 -6
package/docs/api/functions/index.ContainerService.html +0 -13
package/docs/api/functions/index.DateConverter.html +0 -11
package/docs/api/functions/index.Inject.html +0 -16
package/docs/api/functions/index.NumberConverter.html +0 -5
package/docs/api/functions/index.RegisterValidator.html +0 -7
package/docs/api/functions/index.applyPipes.html +0 -17
package/docs/api/functions/index.asyncHandler.html +0 -11
package/docs/api/functions/index.capitalizePipe.html +0 -4
package/docs/api/functions/index.clearPendingNavigations.html +0 -1
package/docs/api/functions/index.compileTemplate.html +0 -26
package/docs/api/functions/index.configure.html +0 -5
package/docs/api/functions/index.createBluePrint.html +0 -1
package/docs/api/functions/index.createConverterFromDataType.html +0 -4
package/docs/api/functions/index.createConverterFromInputType.html +0 -5
package/docs/api/functions/index.createPipeRegistry.html +0 -12
package/docs/api/functions/index.currencyPipe.html +0 -9
package/docs/api/functions/index.datePipe.html +0 -9
package/docs/api/functions/index.daysAgoPipe.html +0 -8
package/docs/api/functions/index.defaultPipe.html +0 -5
package/docs/api/functions/index.defineRoutes.html +0 -8
package/docs/api/functions/index.del.html +0 -8
package/docs/api/functions/index.findRouteByName.html +0 -5
package/docs/api/functions/index.findRouteByUrl.html +0 -4
package/docs/api/functions/index.firstPipe.html +0 -4
package/docs/api/functions/index.generateSequentialId.html +0 -21
package/docs/api/functions/index.get.html +0 -9
package/docs/api/functions/index.getDataConverter.html +0 -11
package/docs/api/functions/index.getParentComponent.html +0 -18
package/docs/api/functions/index.getValidator.html +0 -4
package/docs/api/functions/index.html.html +0 -19
package/docs/api/functions/index.joinPipe.html +0 -5
package/docs/api/functions/index.keysPipe.html +0 -4
package/docs/api/functions/index.lastPipe.html +0 -4
package/docs/api/functions/index.lowercasePipe.html +0 -4
package/docs/api/functions/index.mapFormToClass.html +0 -17
package/docs/api/functions/index.matchRoute.html +0 -5
package/docs/api/functions/index.navigate.html +0 -8
package/docs/api/functions/index.onError.html +0 -8
package/docs/api/functions/index.piecesPipe.html +0 -8
package/docs/api/functions/index.post.html +0 -9
package/docs/api/functions/index.printRoutes.html +0 -2
package/docs/api/functions/index.put.html +0 -9
package/docs/api/functions/index.readData.html +0 -17
package/docs/api/functions/index.registerRouteTarget.html +0 -9
package/docs/api/functions/index.reportError.html +0 -10
package/docs/api/functions/index.request.html +0 -8
package/docs/api/functions/index.resolveValue.html +0 -18
package/docs/api/functions/index.setFetch.html +0 -6
package/docs/api/functions/index.setFormData.html +0 -17
package/docs/api/functions/index.shortenPipe.html +0 -5
package/docs/api/functions/index.startRouting.html +0 -6
package/docs/api/functions/index.ternaryPipe.html +0 -6
package/docs/api/functions/index.trimPipe.html +0 -4
package/docs/api/functions/index.unregisterRouteTarget.html +0 -3
package/docs/api/functions/index.uppercasePipe.html +0 -4
package/docs/api/hierarchy.html +0 -1
package/docs/api/index.html +0 -323
package/docs/api/interfaces/http.SimpleDataEvent.html +0 -3
package/docs/api/interfaces/http.WebSocketAbstraction.html +0 -9
package/docs/api/interfaces/http.WebSocketCodec.html +0 -4
package/docs/api/interfaces/http.WebSocketOptions.html +0 -20
package/docs/api/interfaces/index.CompiledTemplate.html +0 -10
package/docs/api/interfaces/index.DataLoader.html +0 -19
package/docs/api/interfaces/index.EngineConfig.html +0 -11
package/docs/api/interfaces/index.ErrorContext.html +0 -4
package/docs/api/interfaces/index.FormReaderOptions.html +0 -8
package/docs/api/interfaces/index.HttpOptions.html +0 -16
package/docs/api/interfaces/index.HttpResponse.html +0 -17
package/docs/api/interfaces/index.LoadRoute.html +0 -7
package/docs/api/interfaces/index.NavigateOptions.html +0 -7
package/docs/api/interfaces/index.PipeRegistry.html +0 -12
package/docs/api/interfaces/index.RegistrationOptions.html +0 -22
package/docs/api/interfaces/index.RenderTemplate.html +0 -7
package/docs/api/interfaces/index.RequestOptions.html +0 -11
package/docs/api/interfaces/index.Routable.html +0 -10
package/docs/api/interfaces/index.Route.html +0 -13
package/docs/api/interfaces/index.RouteGuard.html +0 -2
package/docs/api/interfaces/index.RouteValue.html +0 -6
package/docs/api/interfaces/index.SSEOptions.html +0 -24
package/docs/api/interfaces/index.ValidationContext.html +0 -8
package/docs/api/interfaces/index.ValidatorOptions.html +0 -14
package/docs/api/media/Architecture.md +0 -333
package/docs/api/media/DependencyInjection.md +0 -277
package/docs/api/media/GettingStarted.md +0 -231
package/docs/api/media/HttpClient.md +0 -459
package/docs/api/media/Pipes.md +0 -211
package/docs/api/media/Routing.md +0 -332
package/docs/api/media/WhyRelaxjs.md +0 -336
package/docs/api/media/forms.md +0 -99
package/docs/api/media/html.md +0 -175
package/docs/api/media/i18n.md +0 -354
package/docs/api/media/utilities.md +0 -143
package/docs/api/media/validation.md +0 -351
package/docs/api/modules/collections_Index.html +0 -1
package/docs/api/modules/di.html +0 -1
package/docs/api/modules/elements.html +0 -1
package/docs/api/modules/forms.html +0 -1
package/docs/api/modules/html.html +0 -1
package/docs/api/modules/http.html +0 -1
package/docs/api/modules/i18n.html +0 -1
package/docs/api/modules/index.html +0 -1
package/docs/api/modules/routing.html +0 -1
package/docs/api/modules/utils.html +0 -1
package/docs/api/modules.html +0 -1
package/docs/api/types/http.WebSocketFactory.html +0 -2
package/docs/api/types/i18n.MessageFormatter.html +0 -3
package/docs/api/types/i18n.MissingTranslationHandler.html +0 -1
package/docs/api/types/index.Constructor.html +0 -7
package/docs/api/types/index.ConverterFunc.html +0 -2
package/docs/api/types/index.DataType.html +0 -2
package/docs/api/types/index.InputType.html +0 -2
package/docs/api/types/index.PipeFunction.html +0 -6
package/docs/api/types/index.RouteData.html +0 -1
package/docs/api/types/index.RouteMatchResult.html +0 -9
package/docs/api/types/index.RouteParamType.html +0 -1
package/docs/api/types/index.RouteSegmentType.html +0 -2
package/docs/api/types/index.SSEEventFactory.html +0 -5
package/docs/api/types/index.ServiceScope.html +0 -10
package/docs/api/types/index.SortColumn.html +0 -3
package/docs/api/variables/i18n.formatICU.html +0 -3
package/docs/api/variables/index.container.html +0 -6
package/docs/api/variables/index.defaultPipes.html +0 -6
package/docs/api/variables/index.internalRoutes.html +0 -1
package/docs/api/variables/index.serviceCollection.html +0 -6

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.

package/docs/setup/build-and-deploy.md ADDED Viewed

@@ -0,0 +1,183 @@
+Build and Deploy
+================
+Relaxjs apps build and deploy like any Vite + TypeScript project. This page covers the two things beginners get wrong: the **base path** setting and the **SPA fallback** on the hosting side.
+---
+## Building for production
+```bash
+npm run build
+```
+Vite outputs static files to `dist/`:
+```
+dist/
+├── index.html
+├── assets/
+│   ├── index-a1b2c3.js
+│   └── index-d4e5f6.css
+└── favicon.ico
+```
+All paths inside `dist/` are relative to the root of your domain by default. If you are deploying to `https://example.com/`, you can upload `dist/` as-is.
+---
+## Deploying to a subpath
+If the app lives at `https://example.com/my-app/` instead of the domain root, set `base` in `vite.config.ts`:
+```ts
+import { defineConfig } from 'vite';
+export default defineConfig({
+    base: '/my-app/',
+});
+```
+The trailing slash matters. With this set, Vite rewrites every asset URL in `index.html` to start with `/my-app/`, and relaxjs routing respects it for `<r-link>` and `navigate(...)`.
+If you deploy to both a subpath (staging) and the root (production), read the base from an environment variable:
+```ts
+export default defineConfig({
+    base: process.env.VITE_BASE ?? '/',
+});
+```
+---
+## SPA fallback (the most common deployment bug)
+Relaxjs routing uses the History API. A route like `/profile/42` is a URL the browser shows, but it is **not** a file on disk. When the user reloads that URL, the server looks for `/profile/42/index.html`, doesn't find it, and returns a 404.
+The fix is to tell the server: *for any URL that is not a real file, serve `index.html` instead*. How to configure this depends on the host.
+### Nginx
+```nginx
+location / {
+    try_files $uri $uri/ /index.html;
+}
+```
+### Apache (`.htaccess`)
+```apache
+RewriteEngine On
+RewriteBase /
+RewriteRule ^index\.html$ - [L]
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule . /index.html [L]
+```
+### Netlify (`netlify.toml` or `_redirects`)
+```
+/*    /index.html   200
+```
+### Vercel (`vercel.json`)
+```json
+{
+    "rewrites": [
+        { "source": "/(.*)", "destination": "/index.html" }
+    ]
+}
+```
+### Static file servers (local testing)
+For testing the built app locally:
+```bash
+npx serve dist --single
+```
+The `--single` flag enables SPA fallback.
+---
+## Multiple HTML layouts
+[Level 7](../GettingStarted.md) of the Getting Started guide introduces layouts: separate HTML files for distinct UI structures (for example, `index.html` for the authenticated app and `public.html` for login/register pages).
+Vite builds every HTML file listed in the `rollupOptions.input` config. Add each layout:
+```ts
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+export default defineConfig({
+    build: {
+        rollupOptions: {
+            input: {
+                main: resolve(__dirname, 'index.html'),
+                public: resolve(__dirname, 'public.html'),
+            },
+        },
+    },
+});
+```
+The SPA fallback must still point at the correct layout. With layouts, the rewrite rules get more nuanced: only fall back to `index.html` for authenticated routes, and to `public.html` for public routes. Most hosts handle this with path-prefixed rewrite rules:
+```
+/login       → /public.html
+/register    → /public.html
+/*           → /index.html
+```
+---
+## Environment variables
+Vite exposes variables prefixed with `VITE_` as `import.meta.env.VITE_*` at build time:
+```
+# .env.production
+VITE_API_URL=https://api.example.com
+```
+```ts
+const apiUrl = import.meta.env.VITE_API_URL;
+```
+Do not put secrets here. Everything in `import.meta.env` ends up in the public bundle.
+---
+## Checklist before deploying
+- [ ] `npm run build` succeeds with no warnings
+- [ ] `base` in `vite.config.ts` matches the deployed URL path
+- [ ] SPA fallback is configured on the host
+- [ ] Environment variables are set for the target (dev, staging, prod)
+- [ ] `index.html` references assets via relative URLs (Vite handles this automatically when `base` is correct)
+- [ ] `public/` contains only files that need fixed URLs
+---
+## Troubleshooting
+### Assets load from the wrong path
+The `base` config does not match the deploy path. For `https://example.com/my-app/`, `base` must be `/my-app/` with a trailing slash.
+### Reloading a route shows 404
+The SPA fallback is missing. Configure the host to serve `index.html` for unknown paths.
+### Blank page in production, works in dev
+Check the browser console. Common causes:
+- A service was imported *after* a component that injects it
+- `import.meta.env.VITE_*` is missing (undefined at runtime)
+- A translation namespace failed to load because the JSON file was not copied to `dist/`
+Translation files inside `src/i18n/locales/` are loaded via `fetch()` at runtime, so they need to be reachable from the browser. Either move them to `public/i18n/locales/` or import each JSON statically if your i18n loader is configured for it.

package/docs/setup/project-structure.md ADDED Viewed

@@ -0,0 +1,170 @@
+Project Structure
+=================
+Relaxjs doesn't force a folder layout, but the one below works well for Vite projects and matches how the examples in this documentation are written.
+---
+## Recommended layout
+```
+my-app/
+├── index.html
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+├── public/
+│   └── favicon.ico
+└── src/
+    ├── main.ts
+    ├── styles.css
+    ├── components/
+    │   ├── HomePage.ts
+    │   ├── UserPanel.ts
+    │   └── AppShell.ts
+    ├── services/
+    │   ├── ApiClient.ts
+    │   └── UserService.ts
+    └── i18n/
+        └── locales/
+            ├── en/
+            │   ├── r-common.json
+            │   └── r-validation.json
+            └── sv/
+                ├── r-common.json
+                └── r-validation.json
+```
+Each folder has one job. Beginners can skip folders they don't need yet — a small app may only have `src/main.ts` and `src/components/`.
+---
+## `index.html`
+Vite treats `index.html` as the project entry. It loads `src/main.ts` as an ES module:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8" />
+    <title>My App</title>
+    <link rel="stylesheet" href="/src/styles.css" />
+</head>
+<body>
+    <r-route-target></r-route-target>
+    <script type="module" src="/src/main.ts"></script>
+</body>
+</html>
+```
+Keep the body minimal. Put page content inside components, not in the HTML file.
+---
+## `src/main.ts`
+The bootstrap file. It imports services, components, and starts i18n and routing. See [Bootstrapping](bootstrapping.md) for the exact order and a full example.
+---
+## `src/components/`
+One file per custom element. Use **PascalCase filenames** and **kebab-case tag names**:
+```ts
+// src/components/UserPanel.ts
+import { html } from '@relax.js/core/html';
+export class UserPanel extends HTMLElement {
+    connectedCallback() {
+        const result = html`<h2>Profile</h2>`({});
+        this.appendChild(result.fragment);
+    }
+}
+customElements.define('user-panel', UserPanel);
+```
+The file ends with `customElements.define(...)` so importing the file is enough to register the tag.
+---
+## `src/services/`
+One file per injectable service. Services use `@ContainerService`:
+```ts
+// src/services/ApiClient.ts
+import { ContainerService } from '@relax.js/core/di';
+@ContainerService()
+export class ApiClient {
+    async get(path: string) {
+        const res = await fetch(path);
+        return res.json();
+    }
+}
+```
+Services are plain classes. They don't extend `HTMLElement`.
+---
+## `src/i18n/locales/`
+Translation files, one JSON per locale per namespace:
+```
+src/i18n/locales/en/r-common.json
+src/i18n/locales/en/r-validation.json
+src/i18n/locales/sv/r-common.json
+src/i18n/locales/sv/r-validation.json
+```
+The structure is fixed: `{locale}/{namespace}.json`. See [i18n](../i18n/i18n.md) for the file format.
+---
+## `public/`
+Static files served at the web root. Use it for favicons, robots.txt, and assets that need stable URLs. Vite copies everything in `public/` to the build output unchanged.
+Prefer imports for assets used by code:
+```ts
+import logoUrl from './assets/logo.svg';
+```
+Use `public/` only when the file must have a known fixed URL.
+---
+## `src/styles.css`
+Global styles live in one file, imported from `index.html`. Per-component styles can be inline `<style>` tags inside each component's template, or a sibling `.css` file imported by the component module.
+Relaxjs does not ship reset styles. Style semantic HTML directly and use the `.form` class to scope form layouts. See [Forms](../forms/forms.md).
+---
+## Scaling up
+As the app grows, split `components/` by feature:
+```
+src/components/
+├── home/
+│   ├── HomePage.ts
+│   └── WelcomeBanner.ts
+├── profile/
+│   ├── UserPanel.ts
+│   └── EditForm.ts
+└── shared/
+    ├── AppShell.ts
+    └── NavBar.ts
+```
+Keep `services/` flat until you have more than ten services, then group the same way.
+Avoid a `utils/` dump folder. If a helper is shared by two features, move it into `src/shared/` with a clear filename.

package/docs/setup/vite.md ADDED Viewed

@@ -0,0 +1,175 @@
+Vite Setup
+==========
+Relaxjs uses the modern **Stage 3 decorator** syntax (the one being standardized by TC39, supported by TypeScript 5.0 and newer). This is different from the older "experimental" decorators that many guides still describe.
+This page shows how to set up a Vite + TypeScript project so that relaxjs decorators like `@RegisterValidator` work out of the box.
+---
+## Requirements
+| Tool       | Minimum version | Why |
+|------------|-----------------|-----|
+| Node.js    | 18 or newer     | Required by Vite 5+ |
+| TypeScript | 5.0 or newer    | Stage 3 decorator support |
+| Vite       | 5.3 or newer    | Bundled esbuild transforms Stage 3 decorators |
+If you created your project with `npm create vite@latest` recently, you already meet these.
+---
+## Step 1: Create a Vite project
+```bash
+npm create vite@latest my-app -- --template vanilla-ts
+cd my-app
+npm install
+npm install @relax.js/core
+```
+The `vanilla-ts` template gives you TypeScript without a framework, which is what relaxjs is designed for.
+---
+## Step 2: Configure `tsconfig.json`
+Open `tsconfig.json` and make sure these options are set:
+```json
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "moduleResolution": "Bundler",
+        "experimentalDecorators": false,
+        "useDefineForClassFields": true,
+        "strict": true,
+        "skipLibCheck": true,
+        "lib": ["ES2022", "DOM"]
+    },
+    "include": ["src"]
+}
+```
+The important lines for decorators:
+- **`"experimentalDecorators": false`** — this is the switch. When `false` (or omitted), TypeScript uses the new Stage 3 decorators. When `true`, it uses the old legacy decorators, which are not compatible with relaxjs.
+- **`"target": "ES2022"`** — any value from `ES2022` upward works. Do not pick a lower target; esbuild needs a modern target to emit clean decorator output.
+- **`"useDefineForClassFields": true`** — required so class fields behave as the standard specifies. Relaxjs form components rely on this.
+You do **not** need `emitDecoratorMetadata`. That option only applies to legacy decorators and is ignored here.
+---
+## Step 3: `vite.config.ts`
+A minimal config is enough. Vite picks up your `tsconfig.json` automatically.
+```ts
+import { defineConfig } from 'vite';
+export default defineConfig({
+    server: {
+        port: 3000,
+    },
+});
+```
+No plugins are required for decorators. Vite's built-in esbuild handles the transform.
+---
+## Step 4: Try a relaxjs decorator
+Create `src/main.ts`:
+```ts
+import { RegisterValidator, ValidationContext } from '@relax.js/core/forms';
+@RegisterValidator('even')
+class EvenValidation {
+    validate(value: string, context: ValidationContext) {
+        const num = parseInt(value, 10);
+        if (isNaN(num) || num % 2 !== 0) {
+            context.addError('Value must be an even number');
+        }
+    }
+}
+console.log('EvenValidation registered');
+```
+Run the dev server:
+```bash
+npm run dev
+```
+Open the browser console. If you see `EvenValidation registered` and no errors, your decorator setup is working.
+---
+## Troubleshooting
+### "Decorators are not valid here" or a parse error
+Your TypeScript version is older than 5.0. Update it:
+```bash
+npm install -D typescript@latest
+```
+Then restart your editor so it picks up the new version.
+### Code compiles but decorator never runs
+You probably have `"experimentalDecorators": true` left over from an older template. Set it to `false` and restart the dev server.
+### Syntax error at runtime, only in the browser
+Your Vite (and therefore esbuild) version is too old to transform Stage 3 decorators. Upgrade:
+```bash
+npm install -D vite@latest
+```
+Vite 5.3 and newer bundle an esbuild version that handles the new decorator syntax.
+### Error about `ElementInternals` or missing DOM types
+Make sure `"lib"` includes `"DOM"` in `tsconfig.json`. Without it, TypeScript does not know about browser APIs that relaxjs uses.
+---
+## Vitest (optional)
+If you add Vitest for testing, no extra decorator configuration is needed. Vitest uses the same esbuild transform as Vite, so the settings above apply to tests automatically.
+```bash
+npm install -D vitest jsdom
+```
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        environment: 'jsdom',
+        globals: true,
+    },
+});
+```
+---
+## Summary
+For relaxjs decorators to work, you need three things:
+1. TypeScript 5.0+
+2. `"experimentalDecorators": false` in `tsconfig.json`
+3. Vite 5.3+ (modern esbuild)
+With those in place, decorators like `@RegisterValidator` work without any plugin or extra setup.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
     "name": "@relax.js/core",
-    "version": "1.0.4",
+    "version": "1.0.5",
     "description": "Ship faster with less code. Web Component library with routing, forms, DI, templating, and i18n. No virtual DOM, no build magic, no surprise re-renders.",
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",
@@ -11,7 +11,8 @@
         "test:coverage": "vitest run --coverage",
         "test:ui": "vitest --ui",
         "buildOld": "tsc",
-        "build": "tsc --emitDeclarationOnly && node build.js && npx typedoc",
+        "build": "tsc --emitDeclarationOnly && node build.js",
+        "docs": "npx typedoc",
         "yalc:publish": "yalc publish && yalc push",
         "yalc:watch": "nodemon --ext ts,js,json --exec \"npm run yalc:publish\"",
         "bp": "npm run build && npm run yalc:publish",

package/docs/api/.nojekyll DELETED Viewed

	@@ -1 +0,0 @@
1	- TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

package/docs/api/assets/hierarchy.js DELETED Viewed

	@@ -1 +0,0 @@
1	- window.hierarchyData = "eJyVjr0KwjAUhd/lzGlFoeWSXdxdpUNorjSYJnCTgFDy7hI6FFzE6cD54TsbJMacoB800qQg/PQ8ZxdDgt5AIzUJZmVo3GPJfBWJAoWXCxb6fCGFIh4aszcpcTq5YPndH91+yauH2nNo5GS7Nu52Q2FenLfCoZ2gYaoKRMM39laM2H/Yx+DHgVrrB1OXV70="