@pure-ds/core 0.7.30 → 0.7.33

package/src/js/pds.js

@@ -28,26 +28,9 @@
  * @property {(css:string) => CSSStyleSheet} createStylesheet - Create a constructable stylesheet from CSS text. @throws {DOMException} on invalid CSS in some browsers.
  * @property {() => boolean} isLiveMode - Returns true when running in live/designer-backed mode
  * @property {() => Promise<typeof import("./pds-core/pds-generator.js").Generator>} getGenerator - Live-only accessor for the Generator class
+ * @property {(level: 'log'|'warn'|'error'|'debug'|'info', message?: any, ...data: any[]) => void} log - Unified logging entry point used by PDS internals and consumers
  */
-
-/**
- * Workspace for the Pure Design System runtime API
- * PDS is now an EventTarget so consumers can subscribe to a single, consistent
- * event bus instead of listening on window/document or individual elements.
- */
-class PDSBase extends EventTarget {}
-/** @type {PDSAPI & PDSBase} */
-const __PDS_SINGLETON_KEY__ = "__PURE_DS_PDS_SINGLETON__";
-const __globalScope__ = typeof globalThis !== "undefined" ? globalThis : window;
-const __existingPDS__ = __globalScope__?.[__PDS_SINGLETON_KEY__];
-const PDS =
-  __existingPDS__ && typeof __existingPDS__.addEventListener === "function"
-    ? __existingPDS__
-    : new PDSBase();
-
-if (__globalScope__) {
-  __globalScope__[__PDS_SINGLETON_KEY__] = PDS;
-}
+import { PDS } from "./pds-singleton.js";
 
 // State properties
 if (typeof PDS.initializing !== "boolean") {
@@ -65,6 +48,12 @@ if (!("currentConfig" in PDS)) {
 if (!("compiled" in PDS)) {
   PDS.compiled = null;
 }
+if (typeof PDS.logHandler !== "function") {
+  PDS.logHandler = null;
+}
+if (!("mode" in PDS)) {
+  PDS.mode = null;
+}
 
 import {
   adoptLayers,
@@ -87,11 +76,377 @@ import {
   isPresetThemeCompatible,
   resolveThemePreference,
 } from "./pds-core/pds-theme-utils.js";
+import { configurePDSLogger, pdsLog } from "./common/pds-log.js";
 
 let __autoCompletePromise = null;
 let __askPromise = null;
 let __toastPromise = null;
 let __defaultEnhancersPromise = null;
+let __localizationPromise = null;
+let __localizationRuntime = null;
+
+const __LOCALIZATION_RUNTIME_SINGLETON_KEY__ = "__pdsLocalizationRuntime";
+
+function __getLocalizationRuntimeSync() {
+  if (__localizationRuntime) {
+    return __localizationRuntime;
+  }
+
+  const sharedRuntime = PDS?.[__LOCALIZATION_RUNTIME_SINGLETON_KEY__];
+  if (sharedRuntime && typeof sharedRuntime === "object") {
+    __localizationRuntime = sharedRuntime;
+    return sharedRuntime;
+  }
+
+  return null;
+}
+
+function __setLocalizationRuntime(runtime) {
+  const normalizedRuntime = runtime && typeof runtime === "object" ? runtime : null;
+  __localizationRuntime = normalizedRuntime;
+  PDS[__LOCALIZATION_RUNTIME_SINGLETON_KEY__] = normalizedRuntime;
+}
+
+configurePDSLogger({
+  getLogger: () => (typeof PDS.logHandler === "function" ? PDS.logHandler : null),
+  getContext: () => {
+    const mode =
+      PDS?.mode ||
+      PDS?.compiled?.mode ||
+      (PDS?.registry?.isLive ? "live" : "static");
+    const debug =
+      (PDS?.debug ||
+        PDS?.currentConfig?.debug ||
+        PDS?.currentConfig?.design?.debug ||
+        PDS?.compiled?.debug ||
+        PDS?.compiled?.design?.debug ||
+        false) === true;
+    return {
+      mode,
+      debug,
+      thisArg: PDS,
+    };
+  },
+});
+
+PDS.log = (level = "log", message, ...data) => {
+  pdsLog(level, message, ...data);
+};
+
+const __fallbackLocalizationState = {
+  locale: "en",
+  messages: {},
+  hasProvider: false,
+};
+const __pendingLocalizationKeys = new Set();
+
+function __isStrTagged(template) {
+  return (
+    Boolean(template) &&
+    typeof template !== "string" &&
+    typeof template === "object" &&
+    "strTag" in template
+  );
+}
+
+function __collateStrings(strings = []) {
+  let result = "";
+  for (let index = 0; index <= strings.length - 1; index += 1) {
+    result += strings[index];
+    if (index < strings.length - 1) {
+      result += `{${index}}`;
+    }
+  }
+  return result;
+}
+
+function __replacePlaceholders(input, callback) {
+  return String(input).replace(/\{(\d+)\}/g, (_match, index) =>
+    callback(Number(index))
+  );
+}
+
+function __normalizeMessages(messages) {
+  if (!messages || typeof messages !== "object") {
+    return {};
+  }
+
+  const normalized = {};
+  for (const [key, value] of Object.entries(messages)) {
+    if (typeof value === "string") {
+      normalized[key] = value;
+      continue;
+    }
+
+    if (value && typeof value === "object" && typeof value.content === "string") {
+      normalized[key] = value.content;
+    }
+  }
+  return normalized;
+}
+
+function __fallbackStr(strings, ...values) {
+  return {
+    strTag: true,
+    strings: Array.from(strings || []),
+    values,
+    raw: Array.from(strings?.raw || []),
+  };
+}
+
+function __fallbackMsg(template) {
+  if (!template) {
+    return "";
+  }
+
+  if (__isStrTagged(template)) {
+    const key = __collateStrings(template.strings || []);
+    const translated = __fallbackLocalizationState.messages[key] || key;
+    return __replacePlaceholders(translated, (index) => template.values?.[index]);
+  }
+
+  const key = String(template);
+  return __fallbackLocalizationState.messages[key] || key;
+}
+
+function __queuePendingLocalizationKey(template) {
+  if (!template) {
+    return;
+  }
+
+  const key = __isStrTagged(template)
+    ? __collateStrings(template.strings || [])
+    : String(template);
+
+  if (typeof key === "string" && key.length > 0) {
+    __pendingLocalizationKeys.add(key);
+  }
+}
+
+function __flushPendingLocalizationKeys(runtime) {
+  if (
+    !runtime ||
+    typeof runtime.msg !== "function" ||
+    __pendingLocalizationKeys.size === 0
+  ) {
+    return;
+  }
+
+  const pendingKeys = Array.from(__pendingLocalizationKeys);
+  __pendingLocalizationKeys.clear();
+
+  for (const key of pendingKeys) {
+    try {
+      runtime.msg(key);
+    } catch {}
+  }
+}
+
+async function __loadLocalizationRuntime() {
+  const runtime = __getLocalizationRuntimeSync();
+  if (runtime) {
+    return runtime;
+  }
+
+  if (!__localizationPromise) {
+    const localizationModuleURL = __resolveExternalRuntimeModuleURL(
+      "pds-localization.js"
+    );
+
+    __localizationPromise = import(localizationModuleURL)
+      .then((mod) => {
+        if (
+          typeof mod?.msg !== "function" ||
+          typeof mod?.str !== "function" ||
+          typeof mod?.configureLocalization !== "function" ||
+          typeof mod?.loadLocale !== "function" ||
+          typeof mod?.setLocale !== "function" ||
+          typeof mod?.getLocalizationState !== "function"
+        ) {
+          throw new Error("Failed to load localization runtime exports");
+        }
+
+        __setLocalizationRuntime(mod);
+        __flushPendingLocalizationKeys(mod);
+        return mod;
+      })
+      .catch((error) => {
+        __localizationPromise = null;
+        throw error;
+      });
+  }
+
+  return __localizationPromise;
+}
+
+const msg = (template, options = {}) => {
+  const runtime = __getLocalizationRuntimeSync();
+  if (typeof runtime?.msg === "function") {
+    return runtime.msg(template, options);
+  }
+  __queuePendingLocalizationKey(template);
+  return __fallbackMsg(template, options);
+};
+
+const str = (strings, ...values) => {
+  const runtime = __getLocalizationRuntimeSync();
+  if (typeof runtime?.str === "function") {
+    return runtime.str(strings, ...values);
+  }
+  return __fallbackStr(strings, ...values);
+};
+
+const configureLocalization = (config = null) => {
+  const runtime = __getLocalizationRuntimeSync();
+  if (typeof runtime?.configureLocalization === "function") {
+    return runtime.configureLocalization(config);
+  }
+
+  if (!config || typeof config !== "object") {
+    __fallbackLocalizationState.locale = "en";
+    __fallbackLocalizationState.messages = {};
+    __fallbackLocalizationState.hasProvider = false;
+    return {
+      locale: __fallbackLocalizationState.locale,
+      messages: { ...__fallbackLocalizationState.messages },
+      hasProvider: __fallbackLocalizationState.hasProvider,
+    };
+  }
+
+  if (typeof config.locale === "string" && config.locale.trim()) {
+    __fallbackLocalizationState.locale = config.locale.trim();
+  }
+
+  if (Object.prototype.hasOwnProperty.call(config, "messages")) {
+    __fallbackLocalizationState.messages = __normalizeMessages(config.messages);
+  }
+
+  const hasProvider = Boolean(
+    config.provider ||
+      config.translate ||
+      config.loadLocale ||
+      config.setLocale
+  );
+  __fallbackLocalizationState.hasProvider = hasProvider;
+
+  if (hasProvider) {
+    __loadLocalizationRuntime()
+      .then((runtime) => {
+        runtime.configureLocalization(config);
+        __flushPendingLocalizationKeys(runtime);
+      })
+      .catch(() => {});
+  }
+
+  return {
+    locale: __fallbackLocalizationState.locale,
+    messages: { ...__fallbackLocalizationState.messages },
+    hasProvider: __fallbackLocalizationState.hasProvider,
+  };
+};
+
+const loadLocale = async (locale) => {
+  const runtime = await __loadLocalizationRuntime();
+  return runtime.loadLocale(locale);
+};
+
+const setLocale = async (locale, options = {}) => {
+  const runtime = await __loadLocalizationRuntime();
+  return runtime.setLocale(locale, options);
+};
+
+const getLocalizationState = () => {
+  const runtime = __getLocalizationRuntimeSync();
+  if (typeof runtime?.getLocalizationState === "function") {
+    return runtime.getLocalizationState();
+  }
+  return {
+    locale: __fallbackLocalizationState.locale,
+    messages: { ...__fallbackLocalizationState.messages },
+    hasProvider: __fallbackLocalizationState.hasProvider,
+  };
+};
+
+const createJSONLocalization = (options = {}) => {
+  const runtime = __getLocalizationRuntimeSync();
+  if (typeof runtime?.createJSONLocalization === "function") {
+    return runtime.createJSONLocalization(options);
+  }
+
+  const defaultLocale =
+    typeof options?.locale === "string" && options.locale.trim()
+      ? options.locale.trim().toLowerCase()
+      : "en";
+
+  const configuredLocales = Array.isArray(options?.locales)
+    ? options.locales
+        .map((locale) => String(locale || "").trim().toLowerCase())
+        .filter(Boolean)
+    : [];
+
+  const locales = Array.from(new Set([defaultLocale, ...configuredLocales]));
+
+  let __jsonLocalizationConfigPromise = null;
+  const __resolveJSONLocalizationConfig = async () => {
+    if (!__jsonLocalizationConfigPromise) {
+      __jsonLocalizationConfigPromise = __loadLocalizationRuntime()
+        .then((runtime) => {
+          if (typeof runtime?.createJSONLocalization === "function") {
+            return runtime.createJSONLocalization(options);
+          }
+          return null;
+        })
+        .catch(() => null);
+    }
+
+    return __jsonLocalizationConfigPromise;
+  };
+
+  const resolveLoader = async (kind = "loadLocale") => {
+    const runtimeConfig = await __resolveJSONLocalizationConfig();
+    if (!runtimeConfig || typeof runtimeConfig !== "object") {
+      return null;
+    }
+
+    const provider = runtimeConfig.provider;
+    if (!provider || typeof provider !== "object") {
+      return null;
+    }
+
+    const exactLoader = provider[kind];
+    if (typeof exactLoader === "function") {
+      return exactLoader;
+    }
+
+    if (kind === "setLocale" && typeof provider.loadLocale === "function") {
+      return provider.loadLocale;
+    }
+
+    return null;
+  };
+
+  return {
+    locale: defaultLocale,
+    locales: [...locales],
+    provider: {
+      locales: [...locales],
+      async loadLocale(context = {}) {
+        const loader = await resolveLoader("loadLocale");
+        if (typeof loader !== "function") {
+          return {};
+        }
+        return loader(context);
+      },
+      async setLocale(context = {}) {
+        const loader = await resolveLoader("setLocale");
+        if (typeof loader !== "function") {
+          return {};
+        }
+        return loader(context);
+      },
+    },
+  };
+};
 
 function __resolveExternalRuntimeModuleURL(filename, overrideURL) {
   if (overrideURL && typeof overrideURL === "string") {
@@ -208,22 +563,7 @@ __lazyToast.info = async (...args) => {
 };
 
 const __defaultLog = function (level = "log", message, ...data) {
-  const isStaticMode = Boolean(PDS.registry && !PDS.registry.isLive);
-  const debug =
-    (this?.debug || this?.design?.debug || PDS.debug || false) === true;
-
-  if (isStaticMode) {
-    if (!PDS.debug) return;
-  } else if (!debug && level !== "error" && level !== "warn") {
-    return;
-  }
-
-  const method = console[level] || console.log;
-  if (data.length > 0) {
-    method(message, ...data);
-  } else {
-    method(message);
-  }
+  PDS.log(level, message, ...data);
 };
 
 function __stripFunctionsForClone(value) {
@@ -309,6 +649,22 @@ PDS.isLiveMode = () => registry.isLive;
 PDS.ask = __lazyAsk;
 PDS.toast = __lazyToast;
 PDS.common = common;
+PDS.msg = msg;
+PDS.str = str;
+PDS.configureLocalization = configureLocalization;
+PDS.loadLocale = loadLocale;
+PDS.setLocale = setLocale;
+PDS.getLocalizationState = getLocalizationState;
+PDS.createJSONLocalization = createJSONLocalization;
+PDS.i18n = {
+  msg,
+  str,
+  configure: configureLocalization,
+  loadLocale,
+  setLocale,
+  getState: getLocalizationState,
+  createJSONLocalization,
+};
 PDS.AutoComplete = null;
 PDS.loadAutoComplete = async () => {
   if (PDS.AutoComplete && typeof PDS.AutoComplete.connect === "function") {
@@ -504,7 +860,8 @@ if (!__themeDescriptor) {
             PDS.currentPreset?.name ||
             PDS.currentConfig?.preset ||
             "current preset";
-          console.warn(
+          PDS.log(
+            "warn",
             `PDS theme "${resolvedTheme}" not supported by preset "${presetName}".`
           );
           PDS.dispatchEvent(
@@ -592,8 +949,24 @@ async function start(config) {
   try {
     const mode = (config && config.mode) || "live";
     const { mode: _omit, ...rest } = config || {};
+
+    PDS.mode = mode;
+    PDS.logHandler = typeof rest?.log === "function" ? rest.log : null;
+
     PDS.currentConfig = __toReadonlyClone(rest);
 
+    const localizationConfig =
+      rest && typeof rest.localization === "object" && rest.localization
+        ? rest.localization
+        : null;
+
+    if (localizationConfig) {
+      await __loadLocalizationRuntime();
+      configureLocalization(localizationConfig);
+    } else {
+      configureLocalization(null);
+    }
+
     let startResult;
     if (mode === "static") {
       startResult = await staticInit(rest);
@@ -619,9 +992,7 @@ async function start(config) {
     const resolvedExternalIconPath =
       PDS?.compiled?.design?.icons?.externalPath || "/assets/img/icons/";
 
-    if (typeof console !== "undefined" && typeof console.info === "function") {
-      console.info(`[PDS] startup ready; external icon path: ${resolvedExternalIconPath}`);
-    }
+    PDS.log("info", `startup ready; external icon path: ${resolvedExternalIconPath}`);
 
     return startResult;
   } finally {
@@ -798,4 +1169,13 @@ async function staticInit(config) {
 
 export const applyResolvedTheme = __applyResolvedTheme;
 export const setupSystemListenerIfNeeded = __setupSystemListenerIfNeeded;
-export { PDS };
+export {
+  PDS,
+  msg,
+  str,
+  configureLocalization,
+  loadLocale,
+  setLocale,
+  getLocalizationState,
+  createJSONLocalization,
+};