@rettangoli/fe 1.1.2 → 1.2.0

package/src/cli/vitePlugin.js

@@ -2,6 +2,12 @@ import path from "node:path";
 
 import { isSupportedComponentFile } from "./contracts.js";
 import { generateFrontendEntrySource } from "./frontendEntrySource.js";
+import {
+  buildI18nAssets,
+  getI18nPublicAssetPath,
+  isI18nSourceFilePath,
+  loadI18nBuildContext,
+} from "./i18nBuild.js";
 
 export const RETTANGOLI_FE_VIRTUAL_ENTRY_ID = "virtual:rettangoli-fe-entry";
 const RESOLVED_VIRTUAL_ENTRY_ID = `\0${RETTANGOLI_FE_VIRTUAL_ENTRY_ID}`;
@@ -22,16 +28,29 @@ const normalizePublicEntryPath = (value) => {
   return normalized.startsWith("/") ? normalized : `/${normalized}`;
 };
 
+const getI18nWatchPaths = ({ i18nContext }) => {
+  if (!i18nContext?.enabled) {
+    return [];
+  }
+
+  return [
+    i18nContext.resolvedDir,
+    ...Object.values(i18nContext.localeFiles || {}),
+  ].filter(Boolean);
+};
+
 export const createRettangoliFeVitePlugin = ({
   cwd = process.cwd(),
   dirs = ["./example"],
   setup = "setup.js",
+  i18n = null,
   errorPrefix = "[Build]",
   publicEntryPath = null,
 } = {}) => {
   const resolvedDirs = dirs.map((directory) => path.resolve(cwd, directory));
   const resolvedSetup = path.resolve(cwd, setup);
   const normalizedPublicEntryPath = normalizePublicEntryPath(publicEntryPath);
+  const i18nContext = loadI18nBuildContext({ cwd, i18n, errorPrefix });
 
   let currentCommand = "build";
   let devServer = null;
@@ -42,6 +61,10 @@ export const createRettangoliFeVitePlugin = ({
       return true;
     }
 
+    if (isI18nSourceFilePath({ filePath, i18nContext })) {
+      return true;
+    }
+
     if (!isSupportedComponentFile(filePath)) {
       return false;
     }
@@ -91,12 +114,56 @@ export const createRettangoliFeVitePlugin = ({
         cwd,
         dirs,
         setup,
+        i18n,
         command: currentCommand,
         errorPrefix,
       });
     },
     configureServer(server) {
       devServer = server;
+      const i18nWatchPaths = getI18nWatchPaths({ i18nContext });
+      if (i18nWatchPaths.length > 0) {
+        server.watcher.add(i18nWatchPaths);
+      }
+
+      const serveI18nAsset = (req, res, next) => {
+        if (!i18nContext.enabled || !normalizedPublicEntryPath) {
+          next();
+          return;
+        }
+
+        const reqPath = (req.url || "").split("?")[0];
+
+        try {
+          const currentI18nContext = loadI18nBuildContext({
+            cwd,
+            i18n,
+            errorPrefix,
+          });
+          const asset = buildI18nAssets({
+            i18nContext: currentI18nContext,
+          }).find((candidate) => {
+            const publicPath = getI18nPublicAssetPath({
+              publicEntryPath: normalizedPublicEntryPath,
+              relativeFileName: candidate.relativeFileName,
+            });
+            return reqPath === publicPath;
+          });
+
+          if (!asset) {
+            next();
+            return;
+          }
+
+          res.statusCode = 200;
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.end(asset.content);
+        } catch (error) {
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "text/plain; charset=utf-8");
+          res.end(error.stack || String(error));
+        }
+      };
 
       const onAdd = (filePath) => {
         if (isTrackedFilePath(filePath)) {
@@ -114,6 +181,7 @@ export const createRettangoliFeVitePlugin = ({
       server.watcher.on("unlink", onUnlink);
 
       if (normalizedPublicEntryPath) {
+        server.middlewares.use(serveI18nAsset);
         server.middlewares.use(async (req, res, next) => {
           const reqPath = (req.url || "").split("?")[0];
           if (reqPath !== normalizedPublicEntryPath) {

package/src/cli/watch.js

@@ -39,6 +39,7 @@ export const createWatchServer = async (options = {}) => {
     port = 3001,
     outfile = "./vt/static/main.js",
     setup = "setup.js",
+    i18n = null,
   } = options;
 
   const { root, publicEntryPath } = resolveServeContext({ cwd, outfile });
@@ -56,6 +57,7 @@ export const createWatchServer = async (options = {}) => {
         cwd,
         dirs,
         setup,
+        i18n,
         errorPrefix: "[Watch]",
         publicEntryPath,
       }),

package/src/core/contracts/componentFiles.js

@@ -1,4 +1,5 @@
 import { findUnsupportedTemplatePropertyBindingSyntax } from "../view/templatePropertyBindings.js";
+import { validateViewI18nReferences } from "../i18n/viewReferences.js";
 
 export const FORBIDDEN_VIEW_KEYS = Object.freeze([
   "elementName",
@@ -51,7 +52,8 @@ export const buildComponentContractIndex = (entries = []) => {
   return index;
 };
 
-export const validateComponentContractIndex = (index = {}) => {
+export const validateComponentContractIndex = (index = {}, options = {}) => {
+  const { i18nContext = { enabled: false } } = options;
   const errors = [];
 
   Object.entries(index).forEach(([category, components]) => {
@@ -90,6 +92,13 @@ export const validateComponentContractIndex = (index = {}) => {
           filePath: viewFilePath || representativeFile,
         });
       }
+
+      errors.push(...validateViewI18nReferences({
+        viewYaml,
+        componentLabel,
+        filePath: viewFilePath || representativeFile,
+        i18nContext,
+      }));
     });
   });
 

package/src/core/i18n/viewReferences.js

@@ -0,0 +1,287 @@
+const EXPRESSION_PATTERN = /\$\{([^}]*)\}/g;
+const I18N_PATH_PATTERN = /^i18n\.([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/;
+const SIMPLE_I18N_PATH_PATTERN = /^i18n((?:\.[A-Za-z_$][\w$]*)+)$/;
+
+const createIssue = ({ message, expression, path }) => ({
+  message,
+  expression,
+  path,
+});
+
+const createFindingKey = (finding) => `${finding.path}\u0000${finding.expression}`;
+
+const extractTemplateExpressions = (text) => {
+  const expressions = [];
+  let match;
+  EXPRESSION_PATTERN.lastIndex = 0;
+  while ((match = EXPRESSION_PATTERN.exec(text)) !== null) {
+    expressions.push(match[1].trim());
+  }
+  return expressions;
+};
+
+export const analyzeI18nExpression = ({ expression, path = "$" }) => {
+  const startsFromI18nRoot = /^i18n(?:\b|\.)/.test(expression);
+  const startsFromInternalI18nRoot = /^__rtglI18n(?:\b|\s*\()/.test(expression);
+
+  if (!startsFromI18nRoot && !startsFromInternalI18nRoot) {
+    return { references: [], issues: [] };
+  }
+
+  if (
+    /^__rtglI18n\s*\(/.test(expression) ||
+    /^i18n\s*\(/.test(expression) ||
+    /^i18n(?:\.[A-Za-z_$][\w$]*)+\s*\(/.test(expression)
+  ) {
+    return {
+      references: [],
+      issues: [
+        createIssue({
+          expression,
+          path,
+          message: "i18n function calls are not supported.",
+        }),
+      ],
+    };
+  }
+
+  const exactPathMatch = expression.match(I18N_PATH_PATTERN);
+  if (exactPathMatch) {
+    return {
+      references: [
+        {
+          namespace: exactPathMatch[1],
+          key: exactPathMatch[2],
+          expression,
+          path,
+        },
+      ],
+      issues: [],
+    };
+  }
+
+  const simplePathMatch = expression.match(SIMPLE_I18N_PATH_PATTERN);
+  if (simplePathMatch) {
+    const segments = simplePathMatch[1].split(".").filter(Boolean);
+    const message = segments.length < 2
+      ? "i18n references must use two levels: i18n.namespace.key."
+      : "i18n references must not be deeper than i18n.namespace.key.";
+    return {
+      references: [],
+      issues: [
+        createIssue({
+          expression,
+          path,
+          message,
+        }),
+      ],
+    };
+  }
+
+  if (startsFromI18nRoot || startsFromInternalI18nRoot) {
+    return {
+      references: [],
+      issues: [
+        createIssue({
+          expression,
+          path,
+          message: "i18n references must be direct paths: i18n.namespace.key.",
+        }),
+      ],
+    };
+  }
+
+  return { references: [], issues: [] };
+};
+
+export const collectI18nReferencesFromView = ({
+  value,
+  path = "$",
+  references = [],
+  issues = [],
+} = {}) => {
+  if (typeof value === "string") {
+    const expressions = extractTemplateExpressions(value);
+    expressions.forEach((expression) => {
+      const result = analyzeI18nExpression({ expression, path });
+      references.push(...result.references);
+      issues.push(...result.issues);
+    });
+    return { references, issues };
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      collectI18nReferencesFromView({
+        value: item,
+        path: `${path}[${index}]`,
+        references,
+        issues,
+      });
+    });
+    return { references, issues };
+  }
+
+  if (value && typeof value === "object") {
+    Object.entries(value).forEach(([key, childValue]) => {
+      collectI18nReferencesFromView({
+        value: key,
+        path: `${path}.{key}`,
+        references,
+        issues,
+      });
+      collectI18nReferencesFromView({
+        value: childValue,
+        path: `${path}.${key}`,
+        references,
+        issues,
+      });
+    });
+  }
+
+  return { references, issues };
+};
+
+const collectEventPayloadI18nReferences = ({
+  refs,
+  references,
+  issues,
+}) => {
+  if (!refs || typeof refs !== "object" || Array.isArray(refs)) {
+    return;
+  }
+
+  Object.entries(refs).forEach(([refKey, refConfig]) => {
+    const eventListeners = refConfig?.eventListeners;
+    if (!eventListeners || typeof eventListeners !== "object" || Array.isArray(eventListeners)) {
+      return;
+    }
+
+    Object.entries(eventListeners).forEach(([eventType, eventConfig]) => {
+      if (
+        !eventConfig
+        || typeof eventConfig !== "object"
+        || Array.isArray(eventConfig)
+        || !Object.prototype.hasOwnProperty.call(eventConfig, "payload")
+      ) {
+        return;
+      }
+
+      collectI18nReferencesFromView({
+        value: eventConfig.payload,
+        path: `$.refs.${refKey}.eventListeners.${eventType}.payload`,
+        references,
+        issues,
+      });
+    });
+  });
+};
+
+export const collectRenderableI18nReferencesFromView = ({ viewYaml } = {}) => {
+  const references = [];
+  const issues = [];
+
+  if (viewYaml && typeof viewYaml === "object" && !Array.isArray(viewYaml)) {
+    if (Object.prototype.hasOwnProperty.call(viewYaml, "template")) {
+      collectI18nReferencesFromView({
+        value: viewYaml.template,
+        path: "$.template",
+        references,
+        issues,
+      });
+    }
+
+    collectEventPayloadI18nReferences({
+      refs: viewYaml.refs,
+      references,
+      issues,
+    });
+  } else {
+    collectI18nReferencesFromView({
+      value: viewYaml,
+      references,
+      issues,
+    });
+  }
+
+  return { references, issues };
+};
+
+export const validateViewI18nReferences = ({
+  viewYaml,
+  componentLabel,
+  filePath,
+  i18nContext = { enabled: false },
+} = {}) => {
+  const supported = collectRenderableI18nReferencesFromView({
+    viewYaml,
+  });
+  const all = collectI18nReferencesFromView({
+    value: viewYaml,
+  });
+  const supportedFindingKeys = new Set([
+    ...supported.references.map(createFindingKey),
+    ...supported.issues.map(createFindingKey),
+  ]);
+
+  const unsupportedFindings = [
+    ...all.references,
+    ...all.issues,
+  ].filter((finding) => !supportedFindingKeys.has(createFindingKey(finding)));
+
+  const errors = unsupportedFindings.map((finding) => ({
+    code: "RTGL-I18N-004",
+    message: `${componentLabel}: unsupported i18n expression "\${${finding.expression}}" at ${finding.path}. i18n references are supported only in template values, template bindings, and event listener payloads.`,
+    filePath,
+  }));
+
+  supported.issues.forEach((issue) => {
+    errors.push({
+      code: "RTGL-I18N-001",
+      message: `${componentLabel}: invalid i18n expression "\${${issue.expression}}": ${issue.message}`,
+      filePath,
+    });
+  });
+
+  const references = supported.references;
+
+  if (errors.length > 0) {
+    return errors;
+  }
+
+  if (!i18nContext?.enabled && references.length > 0) {
+    references.forEach((reference) => {
+      errors.push({
+        code: "RTGL-I18N-002",
+        message: `${componentLabel}: i18n reference "\${${reference.expression}}" requires fe.i18n configuration.`,
+        filePath,
+      });
+    });
+    return errors;
+  }
+
+  if (i18nContext?.enabled) {
+    const defaultCatalog = i18nContext.catalogs?.[i18nContext.defaultLocale] || {};
+    references.forEach((reference) => {
+      if (!Object.prototype.hasOwnProperty.call(defaultCatalog, reference.namespace)) {
+        errors.push({
+          code: "RTGL-I18N-003",
+          message: `${componentLabel}: missing i18n namespace "${reference.namespace}" in default locale "${i18nContext.defaultLocale}".`,
+          filePath,
+        });
+        return;
+      }
+
+      const namespaceMessages = defaultCatalog[reference.namespace] || {};
+      if (!Object.prototype.hasOwnProperty.call(namespaceMessages, reference.key)) {
+        errors.push({
+          code: "RTGL-I18N-003",
+          message: `${componentLabel}: missing i18n key "${reference.namespace}.${reference.key}" in default locale "${i18nContext.defaultLocale}".`,
+          filePath,
+        });
+      }
+    });
+  }
+
+  return errors;
+};

package/src/core/runtime/componentOrchestrator.js

@@ -46,6 +46,7 @@ export const runConnectedComponentLifecycle = ({
     refs: instance.refs,
     handlers: instance.transformedHandlers,
     parseAndRenderFn,
+    getPayloadContext: () => instance.viewData,
   });
 
   renderFn();

package/src/core/runtime/events.js

@@ -16,6 +16,7 @@ export const createEventDispatchCallback = ({
   handlers,
   onMissingHandler,
   parseAndRenderFn,
+  getPayloadContext,
 }) => {
   const getPayload = (event) => {
     const payloadTemplate = (
@@ -28,7 +29,11 @@ export const createEventDispatchCallback = ({
     if (typeof parseAndRenderFn !== "function") {
       return payloadTemplate;
     }
+    const payloadContext = typeof getPayloadContext === "function"
+      ? getPayloadContext()
+      : {};
     return parseAndRenderFn(payloadTemplate, {
+      ...(payloadContext && typeof payloadContext === "object" ? payloadContext : {}),
       _event: event,
     });
   };
@@ -162,6 +167,7 @@ export const createConfiguredEventListener = ({
   stateKey,
   fallbackCurrentTarget = null,
   parseAndRenderFn,
+  getPayloadContext,
   onMissingHandler,
   nowFn = Date.now,
   setTimeoutFn = setTimeout,
@@ -178,6 +184,7 @@ export const createConfiguredEventListener = ({
     handlers,
     onMissingHandler,
     parseAndRenderFn,
+    getPayloadContext,
   });
   if (!callback) {
     return null;

package/src/core/runtime/globalListeners.js

@@ -21,6 +21,7 @@ export const attachGlobalRefListeners = ({
     document: globalThis.document,
   },
   parseAndRenderFn,
+  getPayloadContext,
   timing = {
     nowFn: Date.now,
     setTimeoutFn: setTimeout,
@@ -54,6 +55,7 @@ export const attachGlobalRefListeners = ({
         stateKey,
         fallbackCurrentTarget: target,
         parseAndRenderFn,
+        getPayloadContext,
         nowFn: timing.nowFn,
         setTimeoutFn: timing.setTimeoutFn,
         clearTimeoutFn: timing.clearTimeoutFn,

package/src/core/runtime/i18n.js

@@ -0,0 +1,155 @@
+const getDefaultFetch = () => {
+  if (typeof globalThis !== "undefined" && typeof globalThis.fetch === "function") {
+    return globalThis.fetch.bind(globalThis);
+  }
+  return null;
+};
+
+const normalizeAvailableLocales = (locales = []) => [...new Set(locales)];
+
+const createUnknownLocaleError = ({ locale, availableLocales }) => {
+  return new Error(
+    `[i18n] Unknown locale "${locale}". Available locales: ${availableLocales.join(", ")}.`,
+  );
+};
+
+export const createI18nRuntime = ({
+  defaultLocale,
+  fallbackLocale = defaultLocale,
+  locales = [],
+  urls = {},
+  initialCatalogs = {},
+  fetchFn = getDefaultFetch(),
+} = {}) => {
+  const availableLocales = normalizeAvailableLocales(locales);
+  const catalogs = new Map(Object.entries(initialCatalogs || {}));
+  const listeners = new Set();
+  let currentLocale = defaultLocale || fallbackLocale || availableLocales[0] || null;
+  let localeRequestVersion = 0;
+
+  const assertKnownLocale = (locale) => {
+    if (!availableLocales.includes(locale)) {
+      throw createUnknownLocaleError({ locale, availableLocales });
+    }
+  };
+
+  const getMessages = () => {
+    return (
+      catalogs.get(currentLocale) ||
+      catalogs.get(fallbackLocale) ||
+      Object.create(null)
+    );
+  };
+
+  const notify = () => {
+    listeners.forEach((listener) => {
+      listener(currentLocale);
+    });
+  };
+
+  const load = async (locale) => {
+    assertKnownLocale(locale);
+
+    if (catalogs.has(locale)) {
+      return catalogs.get(locale);
+    }
+
+    const url = urls[locale];
+    if (!url) {
+      throw new Error(`[i18n] Missing URL for locale "${locale}".`);
+    }
+    if (!fetchFn) {
+      throw new Error("[i18n] fetch is not available for lazy locale loading.");
+    }
+
+    const response = await fetchFn(url);
+    if (!response?.ok) {
+      throw new Error(`[i18n] Failed to load locale "${locale}" from ${url}.`);
+    }
+
+    const catalog = await response.json();
+    catalogs.set(locale, catalog);
+    return catalog;
+  };
+
+  const activateLocale = (locale) => {
+    currentLocale = locale;
+    notify();
+    return getMessages();
+  };
+
+  const set = async (locale) => {
+    assertKnownLocale(locale);
+    const requestVersion = localeRequestVersion + 1;
+    localeRequestVersion = requestVersion;
+    const isLatestRequest = () => requestVersion === localeRequestVersion;
+
+    try {
+      await load(locale);
+    } catch (error) {
+      if (!isLatestRequest()) {
+        return getMessages();
+      }
+      if (locale === fallbackLocale) {
+        throw error;
+      }
+      try {
+        await load(fallbackLocale);
+      } catch (fallbackError) {
+        if (!isLatestRequest()) {
+          return getMessages();
+        }
+        throw fallbackError;
+      }
+      if (!isLatestRequest()) {
+        return getMessages();
+      }
+      return activateLocale(fallbackLocale);
+    }
+
+    if (!isLatestRequest()) {
+      return getMessages();
+    }
+    return activateLocale(locale);
+  };
+
+  const ready = async () => {
+    if (!currentLocale) {
+      return getMessages();
+    }
+    if (catalogs.has(currentLocale)) {
+      return getMessages();
+    }
+    return set(currentLocale);
+  };
+
+  const current = () => currentLocale;
+  const available = () => [...availableLocales];
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+
+  const localeService = {
+    available,
+    current,
+    load,
+    ready,
+    set,
+    subscribe,
+  };
+
+  return {
+    available,
+    current,
+    getMessages,
+    load,
+    locale: localeService,
+    localeService,
+    ready,
+    set,
+    subscribe,
+  };
+};

package/src/core/runtime/lifecycle.js

@@ -5,13 +5,26 @@ export const createRuntimeDeps = ({
   store,
   render,
 }) => {
-  return {
+  const runtimeDeps = {
     ...baseDeps,
     refs,
     dispatchEvent,
     store,
     render,
   };
+
+  if (baseDeps?.__rtglI18nRuntime) {
+    Object.defineProperty(runtimeDeps, "i18n", {
+      enumerable: true,
+      configurable: true,
+      get() {
+        return baseDeps.__rtglI18nRuntime.getMessages();
+      },
+    });
+    runtimeDeps.locale = baseDeps.__rtglI18nRuntime.locale;
+  }
+
+  return runtimeDeps;
 };
 
 export const createStoreActionDispatcher = ({