npm - @finesoft/front - Versions diffs - 0.1.76 → 0.1.77 - Mend

@finesoft/front 0.1.76 → 0.1.77

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 (51) hide show

package/docs/01-getting-started.md +230 -0
package/docs/02-routing-and-controllers.md +197 -0
package/docs/03-middleware.md +214 -0
package/docs/04-rendering-and-hydration.md +271 -0
package/docs/05-i18n.md +243 -0
package/docs/06-http-client.md +286 -0
package/docs/07-di-container.md +264 -0
package/docs/08-observability.md +290 -0
package/docs/09-server-and-deployment.md +242 -0
package/docs/10-features-platform-pwa.md +238 -0
package/docs/README.md +72 -0
package/docs/advanced/custom-action-handler.md +248 -0
package/docs/advanced/custom-adapter.md +264 -0
package/docs/advanced/custom-event-recorder.md +318 -0
package/docs/advanced/inline-proxy-codegen.md +200 -0
package/docs/advanced/multi-tenant-scopes.md +330 -0
package/docs/engineering/ci-release-flow.md +244 -0
package/docs/engineering/project-structure.md +296 -0
package/docs/engineering/testing.md +317 -0
package/docs/pitfalls/container-scope-leak.md +215 -0
package/docs/pitfalls/i18n-bundle-size.md +182 -0
package/docs/pitfalls/proxy-binary-payloads.md +133 -0
package/docs/pitfalls/redirect-vs-rewrite.md +147 -0
package/docs/pitfalls/ssr-hydration-mismatch.md +163 -0
package/docs/pitfalls/ssr-vs-csr-globals.md +176 -0
package/docs/zh/01-getting-started.md +230 -0
package/docs/zh/02-routing-and-controllers.md +197 -0
package/docs/zh/03-middleware.md +214 -0
package/docs/zh/04-rendering-and-hydration.md +271 -0
package/docs/zh/05-i18n.md +243 -0
package/docs/zh/06-http-client.md +286 -0
package/docs/zh/07-di-container.md +264 -0
package/docs/zh/08-observability.md +287 -0
package/docs/zh/09-server-and-deployment.md +242 -0
package/docs/zh/10-features-platform-pwa.md +238 -0
package/docs/zh/README.md +72 -0
package/docs/zh/advanced/custom-action-handler.md +248 -0
package/docs/zh/advanced/custom-adapter.md +264 -0
package/docs/zh/advanced/custom-event-recorder.md +318 -0
package/docs/zh/advanced/inline-proxy-codegen.md +200 -0
package/docs/zh/advanced/multi-tenant-scopes.md +330 -0
package/docs/zh/engineering/ci-release-flow.md +244 -0
package/docs/zh/engineering/project-structure.md +296 -0
package/docs/zh/engineering/testing.md +317 -0
package/docs/zh/pitfalls/container-scope-leak.md +215 -0
package/docs/zh/pitfalls/i18n-bundle-size.md +182 -0
package/docs/zh/pitfalls/proxy-binary-payloads.md +133 -0
package/docs/zh/pitfalls/redirect-vs-rewrite.md +147 -0
package/docs/zh/pitfalls/ssr-hydration-mismatch.md +163 -0
package/docs/zh/pitfalls/ssr-vs-csr-globals.md +176 -0
package/package.json +2 -1

package/docs/04-rendering-and-hydration.md ADDED Viewed

@@ -0,0 +1,271 @@
+# 4. Rendering & hydration
+How a page travels from controller output to bytes on the wire, then back into a live browser app. This chapter covers SSR, CSR, prerender, and the `PrefetchedIntents` machinery that ties them together.
+## The three modes side by side
+|                             | SSR                              | CSR                              | Prerender                        |
+| --------------------------- | -------------------------------- | -------------------------------- | -------------------------------- |
+| When HTML is built          | Per request, on the server       | At build time (shell only)       | At build time, per route         |
+| Initial body                | Fully rendered                   | Empty `<div id="app"></div>`     | Fully rendered                   |
+| Initial fetch on hydration? | No (data in `PrefetchedIntents`) | Yes (controller runs in browser) | No (data in `PrefetchedIntents`) |
+| TTFB                        | One controller execution         | Near-zero                        | Static file serve                |
+| Personalization             | Per-request OK                   | Best — runs entirely client-side | None (same HTML for everyone)    |
+| SEO                         | Good                             | Requires JS-aware crawlers       | Best                             |
+Mode is **per-route**. Mix freely.
+## SSR pipeline
+```
+Request URL
+    │
+    ▼
+Router.resolve()                 → RouteMatch
+    │
+    ▼
+beforeLoad guards                → may rewrite (internal) / redirect / deny
+    │
+    ▼
+IntentDispatcher.dispatch()      → Page
+    │
+    ▼
+afterLoad guards                 → may redirect / deny / signal canonicalization
+    │
+    ▼
+renderApp(page)                  → { html, head, css }
+    │
+    ▼
+injectSSRContent()               → final HTML with:
+    • rendered body in <!--ssr-->
+    • head fragment in <!--head-->
+    • serialized PrefetchedIntents in a <script> tag
+    • <html lang="..." dir="..."> attributes
+```
+### SSR entry
+```ts
+// src/ssr.ts
+import { createSSRRender, serializeServerData } from "@finesoft/front";
+import { createSSRApp } from "vue";
+import { renderToString } from "vue/server-renderer";
+import App from "./App.vue";
+import { bootstrap } from "./bootstrap";
+export const render = createSSRRender({
+    bootstrap,
+    getErrorPage: () => ({ kind: "error", title: "Something went wrong" }),
+    async renderApp(page) {
+        const app = createSSRApp(App, { page });
+        const html = await renderToString(app);
+        return {
+            html,
+            head: `<title>${escape(page.title)}</title>`,
+            css: "",
+        };
+    },
+});
+export { serializeServerData };
+```
+The Vite plugin and adapters call `render(url, options)` for you. You return `{ html, head, css }`; the framework handles injection and serialization.
+### What `createSSRRender` does for you
+- Runs `bootstrap()` once on the server (cached across requests in the same worker)
+- Creates a request-scoped DI container per request
+- Runs the middleware pipeline
+- Calls your `renderApp()` to produce the body
+- Serializes prefetched intent results into a `<script id="__finesoft_data__">` tag
+- Sets `<html lang dir>` from the resolved locale
+- Sets HTTP status from `deny()` / `redirect()` / `rewrite()` results
+- Adds `Content-Location` header when `afterLoad` signaled a rewrite
+## CSR (client-side render)
+For routes marked `renderMode: "csr"`, the server returns a minimal shell:
+```html
+<!doctype html>
+<html lang="en">
+    <head>
+        <!-- head injected here -->
+    </head>
+    <body>
+        <div id="app"></div>
+        <!-- no PrefetchedIntents script — controller runs in browser -->
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>
+```
+The controller runs in the browser when `startBrowserApp()` triggers the first navigation. Use CSR for:
+- Heavily personalized dashboards behind auth
+- Pages where SEO doesn't matter
+- Pages where server-side rendering cost outweighs the latency benefit
+## Prerender (static + ISR)
+```ts
+{ path: "/about", intentId: "about", controller: new AboutController(), renderMode: "prerender" }
+```
+At build time the framework:
+1. Calls `controller.execute({}, container)` (path params from the static path)
+2. Runs `renderApp()` to produce HTML
+3. Writes `dist/about.html` to disk
+The adapter serves these static files directly. No controller runs at request time.
+### Incremental Static Regeneration (ISR)
+The bundled server (`createServer`) and the preview server (`vp preview`) support cached on-demand regeneration. Configure via `finesoftFrontViteConfig`:
+```ts
+finesoftFrontViteConfig({
+    ssr: { entry: "src/ssr.ts" },
+    isr: {
+        // routes that should regenerate on demand
+        routes: ["/blog/*"],
+        // cache TTL in seconds
+        ttl: 300,
+    },
+});
+```
+The first request after expiry triggers a fresh render; concurrent requests get the stale version until the regeneration completes. See [server & deployment](./09-server-and-deployment.md#isr) for details.
+## `PrefetchedIntents` — the SSR → CSR bridge
+The crucial mechanic: **the same controller produces a page on the server, and the browser reuses that result without refetching.**
+### How it works
+1. SSR: controller runs, returns `Page`. The framework stores `(intentId, paramsKey) → Page` in a `PrefetchedIntents` map.
+2. Render: the map is JSON-stringified into `<script id="__finesoft_data__">{...}</script>`.
+3. Browser: `startBrowserApp` reads the script, calls `createPrefetchedIntentsFromDom()`, passes it to `Framework.create()`.
+4. First navigation in the browser: `IntentDispatcher.dispatch()` checks the map by `(intentId, paramsKey)` — if hit, returns the cached `Page` directly without calling the controller.
+### Stable key generation
+The lookup key is generated from `intentId` + the **stable JSON stringification** of `params`. Object key order does not affect the key:
+```ts
+// These produce the same paramsKey:
+dispatch({ intentId: "product", params: { id: "42", color: "red" } });
+dispatch({ intentId: "product", params: { color: "red", id: "42" } });
+```
+If you write a controller that resolves the same logical request from different `params` shapes, factor it into a normalization step before dispatch.
+### When the cache misses
+- New navigation to an intent not prefetched on the server (e.g., dynamic route the user clicked)
+- Stale cache after `PrefetchedIntents.invalidate(intentId, params)`
+- Browser-side mutation guards (custom)
+A miss falls through to the regular dispatcher path — `execute()` runs in the browser.
+## Hydration step-by-step
+```
+Server                        Browser
+──────                        ───────
+bootstrap(framework)
+    ▼                              │
+controller.execute()                │
+    ▼                              │
+Page A                              │
+    ▼                              │
+serialize → <script>                │
+    ▼                              │
+HTML response ────────────────▶  Receive HTML
+                                    ▼
+                              createPrefetchedIntentsFromDom()
+                                    ▼
+                              Framework.create({ prefetchedIntents })
+                                    ▼
+                              bootstrap(framework)    ← same code, same routes
+                                    ▼
+                              dispatch(currentIntent)
+                                    ▼
+                              Cache hit → Page A     ← no refetch
+                                    ▼
+                              mount(app)
+```
+The bootstrap runs twice — once on each side — with identical inputs. This is what guarantees the browser-side initial route matches the server-rendered HTML.
+## SSR head injection
+`renderApp()` returns a `head` fragment. The framework injects it at the `<!--head-->` placeholder along with:
+- `<script id="__finesoft_data__">` with serialized data (SSR mode only)
+- `<link>` / `<script>` for client entry (production builds)
+- `<html lang="..." dir="...">` attributes from the resolved locale
+Custom meta tags go in your `head` string:
+```ts
+async renderApp(page) {
+    return {
+        html: await renderToString(/*...*/),
+        head: [
+            `<title>${escape(page.title)}</title>`,
+            `<meta name="description" content="${escape(page.description)}">`,
+            `<meta property="og:title" content="${escape(page.title)}">`,
+        ].join(""),
+        css: "",
+    };
+}
+```
+Always escape user-provided strings — they go straight into HTML.
+## CSS injection
+If your render produces critical CSS (e.g., Vue scoped styles or `vanilla-extract`), return it as `css`:
+```ts
+return {
+    html,
+    head: `<title>${title}</title>`,
+    css: extractedCriticalCss, // injected as <style> in <head>
+};
+```
+For Vite-managed stylesheets, leave `css: ""` — the Vite plugin handles them.
+## Status codes
+The HTTP status of the SSR response follows this priority:
+1. Middleware result: `deny(404)` → 404; `redirect(url, 301)` → 301 with `Location` header.
+2. Page-level: a `Page` of `kind: "error"` returned by `fallback()` results in 500 (configurable via `getErrorPage`).
+3. Default: 200.
+Override via `afterLoad`:
+```ts
+afterLoad: [
+    (ctx) => {
+        if (ctx.page.kind === "not-found") return deny(404, "Not found");
+        return next();
+    },
+],
+```
+## Streaming SSR
+Currently not supported. The framework awaits `renderApp()` fully before sending bytes. For most apps this is fine — `IntentDispatcher` parallelizes data fetching inside `execute()` if your controller awaits multiple HTTP calls together.
+If you need streaming for a specific large page, consider rendering it CSR and using your view layer's own streaming primitives.
+## Next
+- [i18n](./05-i18n.md) — locale resolution and dictionary loading
+- [Pitfalls: SSR hydration mismatch](./pitfalls/ssr-hydration-mismatch.md) — when the two sides disagree

package/docs/05-i18n.md ADDED Viewed

@@ -0,0 +1,243 @@
+# 5. Internationalization
+The framework handles four i18n concerns:
+1. **Resolving the user's locale** (cookie, accept-language, manual override)
+2. **Loading the right dictionary** without bloating the bundle
+3. **Translating strings** with interpolation and pluralization
+4. **Rendering the correct text direction** (LTR / RTL)
+## Locale resolution
+Pass a default `locale` to `Framework.create()`:
+```ts
+const framework = Framework.create({ locale: "zh-Hans" });
+```
+For SSR, locale priority (highest wins):
+1. `resolveLocale` callback in `createSSRRender({ resolveLocale })` — has access to request headers / cookies
+2. `locale` in `frameworkConfig` (via DI container)
+For the browser, the locale is whatever the server resolved (sent via the `<html lang>` attribute). `startBrowserApp` reads it and writes it back into `documentElement.lang`/`dir` on hydration.
+### Reading at runtime
+```ts
+const { lang, dir } = framework.getLocale();
+// { lang: "zh-Hans", dir: "ltr" }
+```
+## Custom resolver
+```ts
+import { parseAcceptLanguage } from "@finesoft/front";
+createSSRRender({
+    bootstrap,
+    resolveLocale(ctx) {
+        // 1. cookie
+        const fromCookie = ctx.getCookie("locale");
+        if (fromCookie && isSupported(fromCookie)) return fromCookie;
+        // 2. accept-language
+        const accept = ctx.getHeader("accept-language");
+        const best = parseAcceptLanguage(accept ?? "").find((l) => isSupported(l.tag));
+        if (best) return best.tag;
+        // 3. fallback
+        return "en-US";
+    },
+    async renderApp(page) {
+        /* ... */
+    },
+});
+```
+`parseAcceptLanguage` parses `Accept-Language: en;q=0.9,fr;q=0.8` into ranked tags. Tags with `q=0` are filtered out.
+## Dictionary loading via `messagesDir`
+The recommended pattern is JSON files + the Vite plugin:
+```ts
+// vite.config.ts
+finesoftFrontViteConfig({
+    ssr: { entry: "src/ssr.ts" },
+    i18n: { messagesDir: "src/locales" },
+});
+```
+```
+src/locales/
+├── en-US.json
+├── zh-Hans.json
+└── ja-JP.json
+```
+```json
+// src/locales/zh-Hans.json
+{
+    "hello": "你好",
+    "welcome": "欢迎，{name}",
+    "items.one": "{count} 个项目",
+    "items.other": "{count} 个项目"
+}
+```
+The plugin generates code that:
+- Loads only the resolved locale's JSON (server side: read from disk; browser side: dynamic import chunk)
+- Caches across requests on the server
+- Is keyed by the resolved locale, so changing locale triggers a re-fetch
+You **do not** serialize the dictionary into the HTML payload. The browser fetches its locale chunk in parallel with the initial render.
+## `SimpleTranslator`
+For in-memory dictionaries (small apps, tests, or manually loaded data):
+```ts
+import { SimpleTranslator } from "@finesoft/front";
+const t = new SimpleTranslator({
+    locale: "zh-Hans",
+    messages: {
+        hello: "你好",
+        welcome: "欢迎，{name}",
+        "items.one": "{count} 个项目",
+        "items.other": "{count} 个项目",
+    },
+});
+t.t("hello"); // "你好"
+t.t("welcome", { name: "World" }); // "欢迎，World"
+t.plural("items", 5); // "5 个项目"
+t.plural("items", 1); // "1 个项目"
+```
+### Interpolation
+Curly-brace placeholders: `{name}`, `{count}`, `{0}`. Values are HTML-escaped only if you pass them through your view layer's escape — `SimpleTranslator` returns raw strings.
+### Pluralization
+Backed by `Intl.PluralRules`. Keys use CLDR plural categories: `zero`, `one`, `two`, `few`, `many`, `other`. Always provide `other` as the fallback.
+```json
+{
+    "messages.zero": "No messages",
+    "messages.one": "1 message",
+    "messages.other": "{count} messages"
+}
+```
+```ts
+t.plural("messages", 0); // "No messages"
+t.plural("messages", 1); // "1 message"
+t.plural("messages", 5); // "5 messages"
+```
+Languages with richer plural systems (Russian, Arabic) automatically pick `few`/`many` if present.
+## Integrating with DI
+Register the translator in your container:
+```ts
+container.register(
+    "translator",
+    () =>
+        new SimpleTranslator({
+            locale: framework.getLocale().lang,
+            messages: loadedMessages,
+        }),
+);
+```
+Or use the framework's built-in DI key:
+```ts
+import { DEP_KEYS } from "@finesoft/front";
+container.register(DEP_KEYS.TRANSLATOR, () => translator);
+// Later, in any component or controller:
+const t = framework.container.resolve(DEP_KEYS.TRANSLATOR);
+t.t("hello");
+```
+## Custom message source
+If you need to load messages from an API or CDN, override `loadMessages` on `createSSRRender` / `startBrowserApp`:
+```ts
+createSSRRender({
+    bootstrap,
+    async loadMessages(locale) {
+        const resp = await fetch(`https://cdn.example.com/i18n/${locale}.json`);
+        return resp.json();
+    },
+    async renderApp(page) {
+        /* ... */
+    },
+});
+```
+This **overrides** the Vite-generated loader. Use it when:
+- Translations are managed by a service (Lokalise, Phrase) and fetched at runtime
+- You want stale-while-revalidate caching
+- You need to merge multiple namespaces from different sources
+For most apps, the file-based loader is enough — it ships exactly one locale's bytes, no runtime fetch needed.
+## RTL support
+```ts
+import { isRtl, getTextDirection, getLocaleAttributes } from "@finesoft/front";
+isRtl("ar"); // true
+isRtl("he"); // true
+isRtl("zh-Hans"); // false
+getTextDirection("ar"); // "rtl"
+getTextDirection("en"); // "ltr"
+getLocaleAttributes("ar-SA"); // { lang: "ar-SA", dir: "rtl" }
+```
+The framework sets `<html dir="rtl">` automatically for RTL locales. Your CSS should use logical properties (`margin-inline-start` instead of `margin-left`) for layout that mirrors correctly.
+```css
+/* good */
+.card {
+    padding-inline-start: 16px;
+}
+/* avoid — won't mirror in RTL */
+.card {
+    padding-left: 16px;
+}
+```
+## Locale switching
+For a user-initiated locale switch:
+1. Update the cookie / user preference on the server: `Set-Cookie: locale=ja-JP`.
+2. Trigger a full reload (`window.location.reload()`) so the server resolves the new locale, loads the new dictionary, and re-renders.
+A purely client-side switch is possible but skips SSR re-render — first-paint will show the old locale until the new dictionary loads. For most apps the full reload is simpler and correct.
+## Caveats
+- **Don't serialize the entire dictionary into HTML.** It bloats first paint. The file-based loader sends only the current locale, and only its chunk. See [pitfalls: i18n bundle size](./pitfalls/i18n-bundle-size.md).
+- **Don't mutate the dictionary at runtime.** The cache assumes immutability. If you need dynamic strings (user-generated content), keep them separate from translations.
+- **`SimpleTranslator` is synchronous.** If your translation source is async, load it before the controller runs (e.g., in `beforeLoad` or `onBeforeStart`).
+## Next
+- [HTTP client](./06-http-client.md) — making requests, with locale headers when needed
+- [Pitfalls: i18n bundle size](./pitfalls/i18n-bundle-size.md) — keeping translations off the critical path