@pure-ds/core 0.7.30 → 0.7.33

package/src/js/pds-core/pds-start-helpers.js

@@ -4,6 +4,7 @@
  */
 
 import { AutoDefiner as CoreAutoDefiner } from "pure-web/auto-definer";
+import { PDS } from "../pds-singleton.js";
 
 const __ABSOLUTE_URL_PATTERN__ = /^[a-z][a-z0-9+\-.]*:\/\//i;
 const __MODULE_URL__ = (() => {
@@ -238,6 +239,7 @@ export function normalizeInitConfig(
       mode, autoDefine, applyGlobalStyles, manageTheme,
       themeStorageKey, preloadStyles, criticalLayers,
       managerURL, manager,
+      localization,
       preset: _preset, design: _design, enhancers: _enhancers,
       log: userLog,
       ...otherProps
@@ -429,17 +431,19 @@ export async function setupAutoDefinerAndEnhancers(options, { baseEnhancers = []
                                      err?.message?.includes("Failed to resolve module specifier");
 
           if (isLitComponent && isMissingLitError) {
-            console.error(
+            PDS.log(
+              "error",
               `❌ PDS component <${tag}> requires Lit but #pds/lit is not in import map.
               See: https://github.com/Pure-Web-Foundation/pure-ds/blob/main/readme.md#lit-components-not-working`
             );
           } else {
-            console.warn(
+            PDS.log(
+              "warn",
               `⚠️ PDS component <${tag}> not found. Assets may not be installed.`
             );
           }
         } else {
-          console.error(`❌ Auto-define error for <${tag}>:`, err);
+          PDS.log("error", `❌ Auto-define error for <${tag}>:`, err);
         }
       },
       // Apply all user overrides except mapper so we can still wrap it
@@ -457,7 +461,8 @@ export async function setupAutoDefinerAndEnhancers(options, { baseEnhancers = []
             }
             return mapped;
           } catch (e) {
-            console.warn(
+            PDS.log(
+              "warn",
               "Custom autoDefine.mapper error; falling back to default:",
               e?.message || e
             );

package/src/js/pds-singleton.js

@@ -0,0 +1,49 @@
+export class PDSBase extends EventTarget {
+  constructor() {
+    super();
+    /** @type {'live' | 'static' | null} */
+    this.mode = null;
+    /** @type {Record<string, any> | null} */
+    this.compiled = null;
+    /** @type {(level: 'log' | 'warn' | 'error' | 'debug' | 'info', message?: any, ...data: any[]) => void} */
+    this.log = () => {};
+    /** @type {((level: 'log' | 'warn' | 'error' | 'debug' | 'info', message?: any, ...data: any[]) => void) | null} */
+    this.logHandler = null;
+  }
+}
+
+export const PDS_SINGLETON_KEY = "__PURE_DS_PDS_SINGLETON__";
+
+const globalScope = typeof globalThis !== "undefined" ? globalThis : window;
+const existingPDS = globalScope?.[PDS_SINGLETON_KEY];
+
+export const PDS =
+  existingPDS && typeof existingPDS.addEventListener === "function"
+    ? existingPDS
+    : new PDSBase();
+
+if (globalScope) {
+  globalScope[PDS_SINGLETON_KEY] = PDS;
+}
+
+if (typeof PDS.log !== "function") {
+  PDS.log = (level = "log", message, ...data) => {
+    if (typeof console === "undefined") return;
+    const method =
+      typeof console[level] === "function"
+        ? console[level].bind(console)
+        : typeof console.log === "function"
+          ? console.log.bind(console)
+          : null;
+    if (!method) return;
+    if (data.length > 0) {
+      method(message, ...data);
+    } else {
+      method(message);
+    }
+  };
+}
+
+if (typeof PDS.logHandler !== "function") {
+  PDS.logHandler = null;
+}

package/src/js/pds.d.ts

@@ -107,6 +107,73 @@ export interface CompiledState {
 /** Public config types for editor IntelliSense */
 export type PDSInitConfig = import("./pds-core/pds-config.js").PDSInitConfig;
 
+export interface PDSLocalizationMessages {
+  [key: string]: string | { content?: string };
+}
+
+export interface PDSLocalizationTranslateContext {
+  key: string;
+  values: any[];
+  options?: Record<string, any>;
+  locale: string;
+  defaultLocale: string;
+  messages: Record<string, string>;
+  messagesByLocale?: Record<string, Record<string, string>>;
+  template?: { strings: string[]; values: any[] } | null;
+}
+
+export interface PDSLocalizationProvider {
+  translate?: (context: PDSLocalizationTranslateContext) => string | undefined | null;
+  loadLocale?: (context: {
+    locale: string;
+    defaultLocale: string;
+    reason?: string;
+    loadedLocales?: string[];
+    messages?: Record<string, string>;
+    load?: boolean;
+  }) =>
+    | Promise<PDSLocalizationMessages>
+    | PDSLocalizationMessages
+    | void;
+  setLocale?: (context: {
+    locale: string;
+    defaultLocale: string;
+    reason?: string;
+    loadedLocales?: string[];
+    messages?: Record<string, string>;
+    load?: boolean;
+  }) =>
+    | Promise<PDSLocalizationMessages>
+    | PDSLocalizationMessages
+    | void;
+}
+
+export interface PDSLocalizationConfig {
+  locale?: string;
+  locales?: string[];
+  messages?: PDSLocalizationMessages;
+  provider?: PDSLocalizationProvider;
+  translate?: PDSLocalizationProvider["translate"];
+  loadLocale?: PDSLocalizationProvider["loadLocale"];
+  setLocale?: PDSLocalizationProvider["setLocale"];
+}
+
+export interface PDSJSONLocalizationOptions {
+  locale?: string;
+  locales?: string[];
+  basePath?: string;
+  aliases?: Record<string, string[]>;
+  requestInit?: RequestInit;
+  cache?: Map<string, PDSLocalizationMessages>;
+}
+
+export interface PDSStrResult {
+  strTag: true;
+  strings: string[];
+  values: any[];
+  raw?: string[];
+}
+
 /**
  * Generator - programmatic API to produce tokens, layered CSS and helper modules from a config.
  * Typical usage:
@@ -264,6 +331,53 @@ export class PDS extends EventTarget {
   static enums?: Record<string, any>;
   static common?: Record<string, any>;
   static parse?: (html: string) => Element[];
+  static msg: (template: string | PDSStrResult, options?: Record<string, any>) => string;
+  static str: (strings: TemplateStringsArray, ...values: any[]) => PDSStrResult;
+  static configureLocalization: (config?: PDSLocalizationConfig | null) => {
+    locale: string;
+    messages: Record<string, string>;
+    hasProvider: boolean;
+  };
+  static loadLocale: (locale: string) => Promise<Record<string, string>>;
+  static setLocale: (locale: string, options?: { load?: boolean }) => Promise<string>;
+  static getLocalizationState: () => {
+    locale: string;
+    messages: Record<string, string>;
+    hasProvider: boolean;
+  };
+  static createJSONLocalization: (
+    options?: PDSJSONLocalizationOptions
+  ) => PDSLocalizationConfig;
+  static i18n: {
+    msg: (template: string | PDSStrResult, options?: Record<string, any>) => string;
+    str: (strings: TemplateStringsArray, ...values: any[]) => PDSStrResult;
+    configure: (config?: PDSLocalizationConfig | null) => {
+      locale: string;
+      messages: Record<string, string>;
+      hasProvider: boolean;
+    };
+    loadLocale: (locale: string) => Promise<Record<string, string>>;
+    setLocale: (locale: string, options?: { load?: boolean }) => Promise<string>;
+    getState: () => {
+      locale: string;
+      messages: Record<string, string>;
+      hasProvider: boolean;
+    };
+    createJSONLocalization: (
+      options?: PDSJSONLocalizationOptions
+    ) => PDSLocalizationConfig;
+  };
+  /**
+   * Canonical logging entry point for PDS runtime and consuming apps.
+   *
+   * When `config.log(...)` is provided to `PDS.start(...)`, that handler
+   * is invoked through this method.
+   */
+  static log(
+    level: 'log' | 'warn' | 'error' | 'debug' | 'info',
+    message?: any,
+    ...data: any[]
+  ): void;
   static AutoComplete?: any;
   static loadAutoComplete?: () => Promise<any>;
   
@@ -374,6 +488,7 @@ export class PDS extends EventTarget {
     preloadStyles?: boolean;
     criticalLayers?: string[];
     managerURL?: string;
+    localization?: PDSLocalizationConfig;
     // static-only
     staticPaths?: Record<string, string>;
     enhancers?: Array<any>;
@@ -394,6 +509,41 @@ export class PDS extends EventTarget {
   preloadCritical?(config: any, options?: { theme?: string; layers?: string[] }): void;
 }
 
+export declare function msg(
+  template: string | PDSStrResult,
+  options?: Record<string, any>
+): string;
+
+export declare function str(
+  strings: TemplateStringsArray,
+  ...values: any[]
+): PDSStrResult;
+
+export declare function configureLocalization(
+  config?: PDSLocalizationConfig | null
+): {
+  locale: string;
+  messages: Record<string, string>;
+  hasProvider: boolean;
+};
+
+export declare function loadLocale(locale: string): Promise<Record<string, string>>;
+
+export declare function setLocale(
+  locale: string,
+  options?: { load?: boolean }
+): Promise<string>;
+
+export declare function getLocalizationState(): {
+  locale: string;
+  messages: Record<string, string>;
+  hasProvider: boolean;
+};
+
+export declare function createJSONLocalization(
+  options?: PDSJSONLocalizationOptions
+): PDSLocalizationConfig;
+
 export { PDS as default };
 
 // ===== pds-form Types =====