@rettangoli/fe 1.1.3 → 1.2.1

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 = ({

package/src/core/runtime/store.js

@@ -2,12 +2,20 @@ import { produce } from "immer";
 
 import { isObjectPayload } from "./payload.js";
 
-export const bindStore = (store, props, constants) => {
+export const bindStore = (store, props, constants, runtimeContext = {}) => {
   const { createInitialState, ...selectorsAndActions } = store;
   const selectors = {};
   const actions = {};
   let currentState = {};
 
+  const createStoreContext = (state) => ({
+    state,
+    props,
+    constants,
+    i18n: runtimeContext.getI18n?.() || {},
+    locale: runtimeContext.locale,
+  });
+
   if (createInitialState) {
     currentState = createInitialState({ props, constants });
   }
@@ -15,7 +23,7 @@ export const bindStore = (store, props, constants) => {
   Object.entries(selectorsAndActions).forEach(([key, fn]) => {
     if (key.startsWith("select")) {
       selectors[key] = (...args) => {
-        return fn({ state: currentState, props, constants }, ...args);
+        return fn(createStoreContext(currentState), ...args);
       };
       return;
     }
@@ -28,7 +36,7 @@ export const bindStore = (store, props, constants) => {
         );
       }
       currentState = produce(currentState, (draft) => {
-        return fn({ state: draft, props, constants }, normalizedPayload);
+        return fn(createStoreContext(draft), normalizedPayload);
       });
       return currentState;
     };

package/src/index.js

@@ -1,5 +1,7 @@
 import createComponent from './createComponent.js';
+import { createI18nRuntime } from "./core/runtime/i18n.js";
 
 export {
   createComponent,
+  createI18nRuntime,
 }

package/src/parser.js

@@ -227,6 +227,7 @@ export const createVirtualDom = ({
                     eventRateLimitState,
                     stateKey,
                     parseAndRenderFn: jemplParseAndRender,
+                    getPayloadContext: () => viewData,
                     onMissingHandler: (missingHandlerName) => {
                       console.warn(
                         `[Parser] Handler '${missingHandlerName}' for refKey '${bestMatchRefKey}' (matching '${matchIdentity}') is referenced but not found in available handlers.`,

package/src/web/createWebComponentClass.js

@@ -52,6 +52,8 @@ export const createWebComponentClass = ({
     _globalListenersCleanup;
     _oldVNode;
     deps;
+    i18nRuntime;
+    _i18nUnsubscribe;
     _propsSchemaKeys = [];
     cssText;
 
@@ -64,7 +66,10 @@ export const createWebComponentClass = ({
       if (this.store.selectViewData) {
         data = this.store.selectViewData();
       }
-      return data;
+      return {
+        ...data,
+        i18n: this.i18nRuntime?.getMessages?.() || {},
+      };
     }
 
     connectedCallback() {
@@ -74,6 +79,11 @@ export const createWebComponentClass = ({
       });
       this.shadow = dom.shadow;
       this.renderTarget = dom.renderTarget;
+      if (this.i18nRuntime?.subscribe && !this._i18nUnsubscribe) {
+        this._i18nUnsubscribe = this.i18nRuntime.subscribe(() => {
+          this.render();
+        });
+      }
       runConnectedComponentLifecycle({
         instance: this,
         parseAndRenderFn: parseAndRender,
@@ -82,6 +92,10 @@ export const createWebComponentClass = ({
     }
 
     disconnectedCallback() {
+      if (this._i18nUnsubscribe) {
+        this._i18nUnsubscribe();
+        this._i18nUnsubscribe = undefined;
+      }
       runDisconnectedComponentLifecycle({
         instance: this,
         clearTimerFn: clearTimeout,
@@ -140,7 +154,11 @@ export const createWebComponentClass = ({
       this._propsSchemaKeys = propsSchemaKeys;
       this.elementName = elementName;
       this.styles = styles;
-      this.store = bindStore(store, this.props, this.constants);
+      this.i18nRuntime = deps?.__rtglI18nRuntime;
+      this.store = bindStore(store, this.props, this.constants, {
+        getI18n: () => this.i18nRuntime?.getMessages?.() || {},
+        locale: this.i18nRuntime?.locale,
+      });
       this.template = template;
       this.handlers = handlers;
       this.methods = methods;
@@ -148,12 +166,20 @@ export const createWebComponentClass = ({
       this.patch = patch;
       this.deps = {
         ...deps,
+        locale: this.i18nRuntime?.locale || deps?.locale,
         store: this.store,
         render: this.render,
         handlers,
         props: this.props,
         constants: this.constants,
       };
+      if (this.i18nRuntime) {
+        Object.defineProperty(this.deps, "i18n", {
+          enumerable: true,
+          configurable: true,
+          get: () => this.i18nRuntime.getMessages(),
+        });
+      }
       bindMethods(this, this.methods);
       // Keep the Snabbdom helper off public prop names (e.g. schema prop "h").
       this._snabbdomH = h;