@pure-ds/core 0.7.32 → 0.7.33

package/src/js/common/msg.js

@@ -0,0 +1,9 @@
+export {
+  msg,
+  str,
+  joinStringsAndValues,
+  configureLocalization,
+  loadLocale,
+  setLocale,
+  getLocalizationState,
+} from "./localization.js";

package/src/js/common/pds-core/pds.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Runtime registry singleton that controls live vs static behavior.
+ * Consumers can call `registry.setDesigner(designer)` to enable live mode
+ * or `registry.setStaticMode(paths)` to point to static asset modules.
+ */
+export interface PDSRegistry {
+  /** Attach a designer instance and switch the registry to live mode. */
+  setDesigner(designer: any, meta?: { presetName?: string }): void;
+  /** Switch to static mode and override static paths (keys: tokens, primitives, components, utilities, styles) */
+  setStaticMode(paths?: Record<string, string>): void;
+  /** Return a constructable stylesheet for the requested layer or null on failure. */
+  getStylesheet(layer: string): Promise<CSSStyleSheet | null>;
+  /** Return a BLOB URL (live mode only) for layer imports used in CSS */
+  getBlobURL(layer: string): string | null;
+  /** 'live' or 'static' */
+  readonly mode: string;
+  /** true when a live designer instance is registered */
+  readonly isLive: boolean;
+  /** true when a designer instance exists */
+  readonly hasDesigner: boolean;
+}
+
+/** A small shape describing component metadata used by the PDS ontology. */
+export interface ComponentDef {
+  /** canonical name of the component (e.g., 'Button') */
+  name: string;
+  /** optional HTML tag name for the component ('pds-button') */
+  tag?: string;
+  /** documented props and their types/metadata */
+  props?: Record<string, any>;
+  /** human-friendly description used by the designer */
+  description?: string;
+}
+
+/**
+ * Generator - programmatic API to produce tokens, layered CSS and helper modules from a config.
+ * Typical usage:
+ * const g = new Generator({ example: true });
+ * // tokens may be returned synchronously or via a Promise
+ * const tokens = await g.generateTokens?.();
+ * const css = await g.generateCSS?.();
+ */
+export class Generator {
+  constructor(options?: any);
+  /** runtime options / config passed to the generator */
+  options: any;
+  /** generated token object */
+  tokens: Record<string, any>;
+  /** concatenated CSS (layered) */
+  css: string;
+  /** Generate the token map (may be async in some implementations) */
+  generateTokens?(): Record<string, any> | Promise<Record<string, any>>;
+  /** Generate the CSS string (may be async) */
+  generateCSS?(): string | Promise<string>;
+}
+
+/** Public runtime surface exported as `PDS` */
+export interface PDSEventMap {
+  'pds:ready': CustomEvent<{ mode: 'live' | 'static'; generator?: Generator; config: any; theme: string; autoDefiner?: any }>;
+  'pds:error': CustomEvent<{ error: any }>;
+  'pds:theme:changed': CustomEvent<{ theme: string; requested?: string; source: 'system' | 'programmatic' }>;
+  'pds:config-changed': CustomEvent<{ at: number; mode?: 'live' | 'static'; source?: string; preset?: string }>;
+  'pds:design:updated': CustomEvent<{ config: any; designer?: any }>;
+  'pds:design:field:changed': CustomEvent<{ field: string; config: any }>;
+  'pds:inspector:mode:changed': CustomEvent<{ active: boolean }>;
+  'pds:inspector:deactivate': CustomEvent<{}>;
+  'pds:docs:view': CustomEvent<{ file: string }>;
+}
+
+export const PDS: {
+  /** Registry singleton to query/adopt styles and control live/static behavior. */
+  registry: PDSRegistry;
+  /** Live-only accessor for the Generator class. */
+  getGenerator?: () => Promise<typeof Generator>;
+  /** Presets keyed by id (lowercased). Available in live mode. */
+  presets?: Record<string, any>;
+  /** Ontology metadata about components (live mode). */
+  ontology?: any;
+  /** Apply generated styles to the document (live mode). */
+  applyStyles?: (generator?: Generator) => void;
+  /** Adopt multiple named layers into a ShadowRoot. See `LAYER-ARCHITECTURE.md` for layer ordering. */
+  adoptLayers: (shadowRoot: ShadowRoot, layers?: string[], additionalSheets?: CSSStyleSheet[]) => Promise<void>;
+  /** Convenience to adopt only primitives/styles commonly needed by components. */
+  adoptPrimitives: (shadowRoot: ShadowRoot, additionalSheets?: CSSStyleSheet[]) => Promise<void>;
+  /** Create a constructable stylesheet from a CSS string. May throw on invalid CSS in some browsers. */
+  createStylesheet: (css: string) => CSSStyleSheet;
+  /** Utility to inspect whether runtime is running in live mode. */
+  isLiveMode: () => boolean;
+  /** Find a component definition for a given DOM element, or null if not matched (live mode). */
+  findComponentForElement?: (el: Element) => ComponentDef | null;
+  /** Primary unified entry point to start PDS in live or static mode. Default mode is 'live'. */
+  start: (config: {
+    mode?: 'live' | 'static';
+    preset?: string;
+    design?: any;
+    autoDefine?: {
+      /** AutoDefiner is bundled with PDS core; external moduleURL overrides are not supported. */
+      baseURL?: string;
+      predefine?: string[];
+  mapper?: (tag: string) => string | undefined | null | false;
+      scanExisting?: boolean;
+      observeShadows?: boolean;
+      patchAttachShadow?: boolean;
+      debounceMs?: number;
+      onError?: (tag: string, err: any) => void;
+    };
+    applyGlobalStyles?: boolean;
+    manageTheme?: boolean;
+    themeStorageKey?: string;
+    // live-only
+    preloadStyles?: boolean;
+    criticalLayers?: string[];
+    // static-only
+    staticPaths?: Record<string, string>;
+    enhancers?: Array<any>;
+  }) => Promise<{ generator?: Generator; config: any; theme: string; autoDefiner?: any }>;
+  /** Preload minimal CSS to prevent flash of unstyled content. Call before DOM content renders. */
+  preloadCritical?: (config: any, options?: {
+    theme?: string;
+    layers?: string[];
+  }) => void;
+  /** EventTarget API (strongly typed for common PDS events). */
+  addEventListener: <K extends keyof PDSEventMap>(type: K, listener: (ev: PDSEventMap[K]) => any, options?: boolean | AddEventListenerOptions) => void;
+  removeEventListener: <K extends keyof PDSEventMap>(type: K, listener: (ev: PDSEventMap[K]) => any, options?: boolean | EventListenerOptions) => void;
+  dispatchEvent: (event: PDSEventMap[keyof PDSEventMap] | Event) => boolean;
+};
+
+export { PDS as default };

package/src/js/common/pds-log.js

@@ -0,0 +1,144 @@
+const __SUPPORTED_LOG_LEVELS = new Set(["log", "warn", "error", "debug", "info"]);
+const __PDS_SINGLETON_KEY = "__PURE_DS_PDS_SINGLETON__";
+
+let __logProvider = null;
+let __contextProvider = null;
+
+function __resolveGlobalPDS() {
+  try {
+    const scope = typeof globalThis !== "undefined" ? globalThis : window;
+    const candidate = scope?.[__PDS_SINGLETON_KEY];
+    if (candidate && typeof candidate === "object") {
+      return candidate;
+    }
+  } catch (error) {
+    return null;
+  }
+  return null;
+}
+
+function __normalizeContext(context) {
+  if (!context || typeof context !== "object") {
+    return null;
+  }
+  return {
+    mode: context.mode === "live" || context.mode === "static" ? context.mode : null,
+    debug: context.debug === true,
+    thisArg: context.thisArg,
+  };
+}
+
+function __normalizeLevel(level) {
+  if (typeof level !== "string") return "log";
+  const normalized = level.toLowerCase();
+  return __SUPPORTED_LOG_LEVELS.has(normalized) ? normalized : "log";
+}
+
+function __resolveContext() {
+  if (typeof __contextProvider === "function") {
+    try {
+      const configuredContext = __normalizeContext(__contextProvider());
+      if (configuredContext) {
+        return configuredContext;
+      }
+    } catch (error) {}
+  }
+
+  const globalPDS = __resolveGlobalPDS();
+  if (globalPDS) {
+    const mode =
+      globalPDS?.mode ||
+      globalPDS?.compiled?.mode ||
+      (globalPDS?.registry?.isLive ? "live" : "static");
+    const debug =
+      (globalPDS?.debug ||
+        globalPDS?.currentConfig?.debug ||
+        globalPDS?.currentConfig?.design?.debug ||
+        globalPDS?.compiled?.debug ||
+        globalPDS?.compiled?.design?.debug ||
+        false) === true;
+    return {
+      mode,
+      debug,
+      thisArg: globalPDS,
+    };
+  }
+
+  return { mode: null, debug: false };
+}
+
+function __resolveLogger() {
+  if (typeof __logProvider === "function") {
+    try {
+      const logger = __logProvider();
+      if (typeof logger === "function") {
+        return logger;
+      }
+    } catch (error) {}
+  }
+
+  const globalPDS = __resolveGlobalPDS();
+  if (typeof globalPDS?.logHandler === "function") {
+    return globalPDS.logHandler;
+  }
+
+  return null;
+}
+
+function __consoleLog(level, 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);
+  }
+}
+
+function __shouldUseConsoleFallback(level, context) {
+  const debugEnabled = context?.debug === true;
+  const staticMode = context?.mode === "static";
+
+  if (staticMode && !debugEnabled) {
+    return false;
+  }
+
+  if (!debugEnabled && level !== "error" && level !== "warn") {
+    return false;
+  }
+
+  return true;
+}
+
+export function configurePDSLogger({ getLogger, getContext } = {}) {
+  __logProvider = typeof getLogger === "function" ? getLogger : null;
+  __contextProvider = typeof getContext === "function" ? getContext : null;
+}
+
+export function pdsLog(level = "log", message, ...data) {
+  const normalizedLevel = __normalizeLevel(level);
+  const context = __resolveContext();
+  const customLogger = __resolveLogger();
+
+  if (customLogger) {
+    try {
+      customLogger.call(context?.thisArg, normalizedLevel, message, ...data);
+      return;
+    } catch (error) {
+      __consoleLog("error", "Custom log handler failed:", error);
+    }
+  }
+
+  if (!__shouldUseConsoleFallback(normalizedLevel, context)) {
+    return;
+  }
+
+  __consoleLog(normalizedLevel, message, ...data);
+}

package/src/js/common/toast.js

@@ -0,0 +1,122 @@
+/**
+ * Toast notification utilities for PDS
+ * Ensures pds-toaster component is properly initialized before use
+ */
+
+/**
+ * Ensures pds-toaster exists in DOM and is fully loaded
+ * @returns {Promise<HTMLElement>} The pds-toaster element
+ * @private
+ */
+async function ensureToaster() {
+  let toaster = document.querySelector('pds-toaster');
+  if (!toaster) {
+    toaster = document.createElement('pds-toaster');
+    document.body.appendChild(toaster);
+    await customElements.whenDefined('pds-toaster');
+  }
+  return toaster;
+}
+
+/**
+ * Display a toast notification
+ * 
+ * This method automatically ensures the pds-toaster component exists and is loaded
+ * before displaying the notification. The toaster element is appended to document.body
+ * if not already present.
+ * 
+ * @param {string} message - The message to display
+ * @param {Object} [options={}] - Toast configuration
+ * @param {"information"|"success"|"warning"|"error"} [options.type="information"] - Toast type/severity
+ * @param {number} [options.duration] - Duration in milliseconds (auto-calculated if not provided based on message length)
+ * @param {boolean} [options.closable=true] - Whether the toast can be manually closed
+ * @param {boolean} [options.persistent=false] - If true, toast won't auto-dismiss (requires manual close)
+ * @param {boolean} [options.html=false] - Render `message` as HTML (trusted content only)
+ * @param {{label: string, onClick?: Function, dismissOnClick?: boolean}} [options.action] - Optional action button config
+ * @returns {Promise<string>} Toast ID (can be used to dismiss programmatically)
+ * 
+ * @example
+ * // Simple success toast
+ * await PDS.toast('Changes saved successfully!', { type: 'success' });
+ * 
+ * @example
+ * // Error with custom duration
+ * await PDS.toast('Failed to save changes', { 
+ *   type: 'error',
+ *   duration: 8000 
+ * });
+ * 
+ * @example
+ * // Persistent warning (must be manually closed)
+ * await PDS.toast('This action cannot be undone', { 
+ *   type: 'warning',
+ *   persistent: true 
+ * });
+ * 
+ * @example
+ * // Get toast ID to dismiss later
+ * const toastId = await PDS.toast('Processing...', { persistent: true });
+ * // ... later
+ * const toaster = document.querySelector('pds-toaster');
+ * toaster.dismissToast(toastId);
+ */
+export async function toast(message, options = {}) {
+  const toaster = await ensureToaster();
+  return toaster.toast(message, options);
+}
+
+/**
+ * Display a success toast (convenience method)
+ * 
+ * @param {string} message - The success message
+ * @param {Object} [options={}] - Additional toast options (type is preset to 'success')
+ * @returns {Promise<string>} Toast ID
+ * 
+ * @example
+ * await PDS.toast.success('Profile updated!');
+ */
+toast.success = async function(message, options = {}) {
+  return toast(message, { ...options, type: 'success' });
+};
+
+/**
+ * Display an error toast (convenience method)
+ * 
+ * @param {string} message - The error message
+ * @param {Object} [options={}] - Additional toast options (type is preset to 'error')
+ * @returns {Promise<string>} Toast ID
+ * 
+ * @example
+ * await PDS.toast.error('Failed to connect to server');
+ */
+toast.error = async function(message, options = {}) {
+  return toast(message, { ...options, type: 'error' });
+};
+
+/**
+ * Display a warning toast (convenience method)
+ * 
+ * @param {string} message - The warning message
+ * @param {Object} [options={}] - Additional toast options (type is preset to 'warning')
+ * @returns {Promise<string>} Toast ID
+ * 
+ * @example
+ * await PDS.toast.warning('Session will expire in 5 minutes');
+ */
+toast.warning = async function(message, options = {}) {
+  return toast(message, { ...options, type: 'warning' });
+};
+
+/**
+ * Display an information toast (convenience method)
+ * 
+ * @param {string} message - The information message
+ * @param {Object} [options={}] - Additional toast options (type is preset to 'information')
+ * @returns {Promise<string>} Toast ID
+ * 
+ * @example
+ * await PDS.toast.info('New features available!');
+ */
+toast.info = async function(message, options = {}) {
+  return toast(message, { ...options, type: 'information' });
+};

package/src/js/pds-core/pds-config.js

@@ -1,5 +1,4 @@
 import { enums } from "./pds-enums.js";
-import { PDS } from "../pds-singleton.js";
 
 /**
  * Design config types (SSoT) - mirror generator input and document output impact.
@@ -2674,5 +2673,24 @@ export const PDS_DEFAULT_CONFIG_FORM_SCHEMA = buildDesignConfigFormSchema(
  * @param {...any} data - additional data to log
  */
 export function defaultLog(level = "log", message, ...data) {
-  PDS.log(level, message, ...data);
+  const runtimeLogger = globalThis?.PDS?.log;
+  if (typeof runtimeLogger === "function") {
+    runtimeLogger(level, message, ...data);
+    return;
+  }
+
+  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);
+  }
 }

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;
+}