@nmvuong92/fluxe 0.1.1 → 0.2.0

package/lib/core/engine.d.ts

@@ -2,10 +2,13 @@ import type { ComponentType } from "react";
 import type { Backend } from "../backends/types";
 import type { HeadMeta } from "./seo";
 import type { Session } from "./auth";
+import type { TFn } from "./i18n";
 export interface Ctx<I> {
     input: I;
     backend: Backend;
     session?: Session | null;
+    locale?: string;
+    t?: TFn;
 }
 export type Loader<I, O> = (ctx: Ctx<I>) => Promise<O>;
 export type Action<I, O> = (ctx: Ctx<I>) => Promise<O>;

package/lib/core/i18n.d.ts

@@ -0,0 +1,17 @@
+export type Messages = Record<string, string>;
+export type TFn = (key: string, vars?: Record<string, string | number>) => string;
+export interface I18n {
+    locales: string[];
+    defaultLocale: string;
+    catalogs: Record<string, Messages>;
+}
+export declare function createI18n(opts: {
+    defaultLocale: string;
+    catalogs: Record<string, Messages>;
+}): I18n;
+export declare function translate(i18n: I18n, locale: string, key: string, vars?: Record<string, string | number>): string;
+export declare function makeT(i18n: I18n, locale: string): TFn;
+export declare function resolveLocale(i18n: I18n, opts: {
+    cookie?: string;
+    acceptLanguage?: string;
+}): string;

package/lib/core/i18n.js

@@ -0,0 +1,40 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* i18n — THUẦN, testable. Catalog message theo locale + t(key, vars) interpolate {var}.
+ * resolveLocale: chọn locale từ cookie / Accept-Language, giới hạn trong locale có thật. */
+export function createI18n(opts) {
+    const locales = Object.keys(opts.catalogs);
+    if (!locales.includes(opts.defaultLocale)) {
+        throw new Error(`i18n: defaultLocale '${opts.defaultLocale}' không có trong catalogs`);
+    }
+    return { locales, defaultLocale: opts.defaultLocale, catalogs: opts.catalogs };
+}
+/* Tra key trong catalog locale → fallback defaultLocale → fallback chính key. Interpolate {var}. */
+export function translate(i18n, locale, key, vars) {
+    const msg = i18n.catalogs[locale]?.[key] ?? i18n.catalogs[i18n.defaultLocale]?.[key] ?? key;
+    if (!vars)
+        return msg;
+    return msg.replace(/\{(\w+)\}/g, (_, k) => (k in vars ? String(vars[k]) : `{${k}}`));
+}
+/* t() đã bind locale — dùng trong loader/view. */
+export function makeT(i18n, locale) {
+    return (key, vars) => translate(i18n, locale, key, vars);
+}
+/* Chọn locale: cookie hợp lệ > Accept-Language (khớp tag hoặc base) > defaultLocale. */
+export function resolveLocale(i18n, opts) {
+    if (opts.cookie && i18n.locales.includes(opts.cookie))
+        return opts.cookie;
+    if (opts.acceptLanguage) {
+        for (const part of opts.acceptLanguage.split(",")) {
+            const tag = part.split(";")[0].trim(); // "en-US"
+            if (!tag)
+                continue;
+            if (i18n.locales.includes(tag))
+                return tag;
+            const base = tag.split("-")[0]; // "en"
+            if (i18n.locales.includes(base))
+                return base;
+        }
+    }
+    return i18n.defaultLocale;
+}

package/lib/index.d.ts

@@ -5,6 +5,7 @@ export * from "./core/resolver.ts";
 export * from "./core/wiring.ts";
 export * from "./core/auth.ts";
 export * from "./core/env.ts";
+export * from "./core/i18n.ts";
 export * from "./core/seo.ts";
 export * from "./core/broker.ts";
 export * from "./core/presence.ts";

package/lib/index.js

@@ -9,6 +9,7 @@ export * from "./core/resolver.js"; // resolve, ResolutionProfile/Manifest, Cell
 export * from "./core/wiring.js"; // backendFromManifest, backendsFromManifest
 export * from "./core/auth.js"; // session HMAC, scrypt password, CSRF, RBAC
 export * from "./core/env.js"; // loadEnv
+export * from "./core/i18n.js"; // createI18n, resolveLocale, translate, makeT, t(key, vars)
 export * from "./core/seo.js"; // renderHead, renderSitemap, renderRobots, HeadMeta
 export * from "./core/broker.js"; // pub/sub
 export * from "./core/presence.js"; // ai online theo topic

package/lib/react/LocaleSwitch.d.ts

@@ -0,0 +1,6 @@
+export declare function LocaleSwitch({ locales, current, labels, className, }: {
+    locales: string[];
+    current?: string;
+    labels?: Record<string, string>;
+    className?: string;
+}): import("react").JSX.Element;

package/lib/react/LocaleSwitch.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* <LocaleSwitch> — đổi ngôn ngữ qua link ?locale=xx (server set cookie + redirect).
+ * Render HTML thuần → chạy cả trên cell static (0 JS). Active theo `current` (ctx.locale). */
+export function LocaleSwitch({ locales, current, labels, className, }) {
+    return (_jsx("span", { className: className ?? "locale-switch", children: locales.map((l) => (_jsx("a", { href: `?locale=${l}`, className: l === current ? "locale active" : "locale", "aria-current": l === current ? "true" : undefined, children: labels?.[l] ?? l.toUpperCase() }, l))) }));
+}

package/lib/react/index.d.ts

@@ -4,6 +4,7 @@ export { Link } from "./Link";
 export { Nav, type NavItem } from "./Nav";
 export { useTheme, type Theme } from "./theme";
 export { ThemeToggle } from "./ThemeToggle";
+export { LocaleSwitch } from "./LocaleSwitch";
 export { shellScript } from "./shell";
 export { DebugBar } from "./DebugBar";
 export { debug, DebugStore } from "./store";

package/lib/react/index.js

@@ -8,6 +8,7 @@ export { Link } from "./Link";
 export { Nav } from "./Nav";
 export { useTheme } from "./theme";
 export { ThemeToggle } from "./ThemeToggle";
+export { LocaleSwitch } from "./LocaleSwitch";
 export { shellScript } from "./shell";
 export { DebugBar } from "./DebugBar";
 export { debug, DebugStore } from "./store";

package/lib/react/shell.d.ts

@@ -1 +1 @@
-export declare const shellScript = "(function(){\nvar d=document.documentElement;\ntry{var t=localStorage.getItem('theme');if(t==='dark'||t==='light')d.dataset.theme=t;}catch(e){}\nfunction active(){var p=location.pathname;document.querySelectorAll('.nav-link').forEach(function(a){try{a.classList.toggle('active',new URL(a.href).pathname===p);}catch(e){}});}\nfunction wire(){var b=document.querySelector('[data-fluxe-theme-toggle]');if(b&&!b._w){b._w=1;b.addEventListener('click',function(){var n=d.dataset.theme==='dark'?'light':'dark';d.dataset.theme=n;try{localStorage.setItem('theme',n);}catch(e){}});}active();}\nif(document.readyState!=='loading')wire();else document.addEventListener('DOMContentLoaded',wire);\naddEventListener('fluxe:nav',active);addEventListener('popstate',active);\n})();";
+export declare const shellScript = "(function(){\nvar d=document.documentElement;\ntry{var t=localStorage.getItem('theme');if(t==='dark'||t==='light')d.dataset.theme=t;}catch(e){}\nfunction active(){var p=location.pathname;document.querySelectorAll('.nav-link').forEach(function(a){try{a.classList.toggle('active',new URL(a.href).pathname===p);}catch(e){}});}\nfunction wire(){var b=document.querySelector('[data-fluxe-theme-toggle]');if(b&&!b._w){b._w=1;b.addEventListener('click',function(){var n=d.dataset.theme==='dark'?'light':'dark';d.dataset.theme=n;try{localStorage.setItem('theme',n);}catch(e){}document.cookie='theme='+n+';Path=/;Max-Age=31536000;SameSite=Lax';});}active();}\nif(document.readyState!=='loading')wire();else document.addEventListener('DOMContentLoaded',wire);\naddEventListener('fluxe:nav',active);addEventListener('popstate',active);\n})();";

package/lib/react/shell.js

@@ -9,7 +9,7 @@ export const shellScript = `(function(){
 var d=document.documentElement;
 try{var t=localStorage.getItem('theme');if(t==='dark'||t==='light')d.dataset.theme=t;}catch(e){}
 function active(){var p=location.pathname;document.querySelectorAll('.nav-link').forEach(function(a){try{a.classList.toggle('active',new URL(a.href).pathname===p);}catch(e){}});}
-function wire(){var b=document.querySelector('[data-fluxe-theme-toggle]');if(b&&!b._w){b._w=1;b.addEventListener('click',function(){var n=d.dataset.theme==='dark'?'light':'dark';d.dataset.theme=n;try{localStorage.setItem('theme',n);}catch(e){}});}active();}
+function wire(){var b=document.querySelector('[data-fluxe-theme-toggle]');if(b&&!b._w){b._w=1;b.addEventListener('click',function(){var n=d.dataset.theme==='dark'?'light':'dark';d.dataset.theme=n;try{localStorage.setItem('theme',n);}catch(e){}document.cookie='theme='+n+';Path=/;Max-Age=31536000;SameSite=Lax';});}active();}
 if(document.readyState!=='loading')wire();else document.addEventListener('DOMContentLoaded',wire);
 addEventListener('fluxe:nav',active);addEventListener('popstate',active);
 })();`;

package/lib/server_factory.d.ts

@@ -8,5 +8,8 @@ type LayoutEntry = LayoutMeta & {
     }) => any;
 };
 type LayoutMap = Record<string, LayoutEntry>;
-export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+import { type I18n } from "./core/i18n.ts";
+export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: {
+    i18n?: I18n;
+}): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
 export {};

package/lib/server_factory.js

@@ -20,6 +20,7 @@ import { createPresence } from "./core/presence.js";
 import { etagOf, etagMatches } from "./core/etag.js";
 import { createRenderCache } from "./core/rendercache.js";
 import { parseChaos } from "./core/chaos.js";
+import { resolveLocale, makeT } from "./core/i18n.js";
 import { createMemoryBackend } from "./backends/memory.js";
 import { createHttpBackend } from "./backends/http.js";
 // Build backend theo ngôn ngữ (cho live swap trong devtools).
@@ -59,9 +60,10 @@ function sendError(res, wantsJson, err) {
     }
 }
 // Phần head (trước body) và tail (sau body) — body được STREAM ở giữa.
-function shellHead(cell, data) {
+function shellHead(cell, data, lang = "vi", theme = "") {
     const headHtml = renderHead(cell.head ? cell.head(data) : {});
-    return `<!doctype html><html lang="vi"><head><meta charset="utf-8">${headHtml}</head><body><div id="root">`;
+    const themeAttr = theme ? ` data-theme="${theme}"` : ""; // theme-SSR: no-flash ngay lần đầu
+    return `<!doctype html><html lang="${lang}"${themeAttr}><head><meta charset="utf-8">${headHtml}</head><body><div id="root">`;
 }
 function shellTail(cell, data, shipClientJs) {
     const island = shipClientJs
@@ -85,7 +87,8 @@ function renderBodyToString(node) {
         });
     });
 }
-export function makeServer(manifest, cells, layouts = {}) {
+export function makeServer(manifest, cells, layouts = {}, opts = {}) {
+    const i18n = opts.i18n;
     // Cells được TIÊM từ app (DI) — engine không import ngược vào app/. Thêm trang = sửa app/app.ts.
     const matchRoute = makeRouter(cells);
     const byId = new Map(cells.map((c) => [c.id, c]));
@@ -108,7 +111,20 @@ export function makeServer(manifest, cells, layouts = {}) {
         // CSRF double-submit: đảm bảo có cookie csrf (đặt nếu chưa) — client gửi lại qua header.
         let csrf = cookies.csrf;
         const csrfCookie = csrf ? "" : (csrf = newCsrfToken(), `csrf=${csrf}; Path=/; SameSite=Lax`);
+        // Resolved Shell: locale (i18n) + theme — giải từ cookie/header, đưa vào loader + <html>.
+        const locale = i18n ? resolveLocale(i18n, { cookie: cookies.locale, acceptLanguage: req.headers["accept-language"] }) : "vi";
+        const t = i18n ? makeT(i18n, locale) : (k) => k;
+        const theme = cookies.theme === "dark" || cookies.theme === "light" ? cookies.theme : "";
         try {
+            // Đổi ngôn ngữ qua ?locale=xx → set cookie + redirect (chạy cả trên cell static, 0 JS).
+            {
+                const ql = url.searchParams.get("locale");
+                if (i18n && ql && i18n.locales.includes(ql)) {
+                    url.searchParams.delete("locale");
+                    res.writeHead(303, { "set-cookie": `locale=${ql}; Path=/; SameSite=Lax`, location: url.pathname + (url.search || "") });
+                    return res.end();
+                }
+            }
             if (url.pathname === "/client.js") {
                 if (clientJs === undefined && existsSync("./dist/client.js"))
                     clientJs = readFileSync("./dist/client.js");
@@ -243,7 +259,7 @@ export function makeServer(manifest, cells, layouts = {}) {
             if (cell.requireRole && !hasRole(session, cell.requireRole)) {
                 throw new FluxeError("forbidden", `Cần quyền '${cell.requireRole}'`, 403);
             }
-            const data = await cell.loader({ input: match.params, backend: backendFor(cell.id), session });
+            const data = await cell.loader({ input: match.params, backend: backendFor(cell.id), session, locale, t });
             if (wantsJson) {
                 const body = JSON.stringify({ cell: cell.id, data, layout: cell.layout });
                 const etag = etagOf(body); // render cache: 304 nếu props không đổi
@@ -255,8 +271,9 @@ export function makeServer(manifest, cells, layouts = {}) {
                 return res.end(body);
             }
             let node = h(cell.view, { data });
+            const shellCtx = { locale, t, theme, path: url.pathname }; // Resolved Shell ctx cho layout
             for (const id of layoutChain(cell.layout, layouts)) { // inner→outer: bọc dần
-                node = h(layouts[id].component, { children: node });
+                node = h(layouts[id].component, { children: node, ctx: shellCtx });
             }
             const shipClientJs = manifest.cells[cell.id]?.render.shipClientJs ?? false;
             const pageHeaders = { "content-type": "text/html; charset=utf-8" };
@@ -265,10 +282,10 @@ export function makeServer(manifest, cells, layouts = {}) {
             // Ý B — render cache cell static: render 1 lần → giữ Buffer → ghi lại (zero-copy).
             // Gate etag(data): data đổi ⇒ miss ⇒ render lại (không trả HTML cũ). Chỉ cell static & public.
             if (manifest.cells[cell.id]?.render.mode === "static" && cell.cache !== false && !cell.requireAuth && !cell.requireRole) {
-                const etag = etagOf(JSON.stringify(data));
+                const etag = etagOf(JSON.stringify(data) + "|" + locale + "|" + theme); // lang/theme đổi → bust cache
                 let hit = renderCache.get(url.pathname);
                 if (!hit || hit.etag !== etag) {
-                    const full = shellHead(cell, data) + await renderBodyToString(node) + shellTail(cell, data, shipClientJs);
+                    const full = shellHead(cell, data, locale, theme) + await renderBodyToString(node) + shellTail(cell, data, shipClientJs);
                     hit = { etag, buf: Buffer.from(full, "utf8") };
                     renderCache.set(url.pathname, hit);
                 }
@@ -277,7 +294,7 @@ export function makeServer(manifest, cells, layouts = {}) {
             }
             // Streaming SSR: gửi head ngay → stream body (Suspense chảy dần) → tail khi xong.
             res.writeHead(200, pageHeaders);
-            res.write(shellHead(cell, data));
+            res.write(shellHead(cell, data, locale, theme));
             const through = new PassThrough();
             through.on("data", (c) => res.write(c));
             through.on("end", () => { res.write(shellTail(cell, data, shipClientJs)); res.end(); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nmvuong92/fluxe",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "fluxe — khung fullstack tối giản polyglot (RCA: Resolved Cell Architecture).",
   "license": "Apache-2.0",
   "author": "nmvuong92",