@relax.js/core 1.0.3 → 1.0.5

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

@@ -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

@@ -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

@@ -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.