@pure-ds/core 0.7.57 → 0.7.58

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

@@ -3,9 +3,24 @@
  * Kept separate to avoid pulling live-only logic into the base runtime bundle.
  */
 
-import { AutoDefiner as CoreAutoDefiner } from "pure-web/auto-definer";
 import { PDS } from "../pds-singleton.js";
 
+let __coreAutoDefinerCtorPromise = null;
+
+async function getCoreAutoDefinerCtor() {
+  if (!__coreAutoDefinerCtorPromise) {
+    __coreAutoDefinerCtorPromise = import("pure-web/auto-definer")
+      .then((mod) => mod?.AutoDefiner || mod?.default?.AutoDefiner || mod?.default)
+      .then((ctor) => {
+        if (typeof ctor !== "function") {
+          throw new Error("AutoDefiner constructor not found in pure-web/auto-definer");
+        }
+        return ctor;
+      });
+  }
+  return __coreAutoDefinerCtorPromise;
+}
+
 const __ABSOLUTE_URL_PATTERN__ = /^[a-z][a-z0-9+\-.]*:\/\//i;
 const __MODULE_URL__ = (() => {
   try {
@@ -357,7 +372,7 @@ export async function setupAutoDefinerAndEnhancers(options, { baseEnhancers = []
   // Setup AutoDefiner in browser context (it already observes shadow DOMs)
   let autoDefiner = null;
   if (typeof window !== "undefined" && typeof document !== "undefined") {
-    const AutoDefinerCtor = CoreAutoDefiner;
+    const AutoDefinerCtor = await getCoreAutoDefinerCtor();
 
     const defaultMapper = (tag) => {
       switch (tag) {

package/src/js/pds.d.ts

@@ -458,6 +458,24 @@ export class PDS extends EventTarget {
    */
   static ask(message: AskMessage, options?: AskOptions): Promise<any>;
   
+  /**
+   * Reactive state container class for building reactive components.
+   * Fires custom events ('change' and 'change:propertyName') when state properties are modified.
+   */
+  static State: typeof State;
+  
+  /**
+   * Create a reactive component with automatic re-rendering on state changes.
+   * Each state mutation will automatically re-render the component.
+   */
+  static createReactiveComponent: typeof createReactiveComponent;
+  
+  /**
+   * Bind a state container to an element, auto-updating specific properties when state changes.
+   * Useful for partial updates without full re-renders.
+   */
+  static bindState: typeof bindState;
+  
   /** 
    * Current configuration after PDS.start() completes - read-only, frozen after initialization.
    * Contains the complete configuration used to initialize PDS, including mode, design, preset, and theme.
@@ -754,3 +772,50 @@ export class SchemaForm extends HTMLElement {
 
 export function parse(html: PDSParseInput, ...values: unknown[]): NodeListOf<ChildNode>;
 export function html(html: PDSParseInput, ...values: unknown[]): DocumentFragment;
+
+/**
+ * Reactive state container that fires custom events on property mutations.
+ * When properties change, it emits "change" and "change:propertyName" events.
+ * 
+ * @example
+ * ```javascript
+ * const state = new State({ count: 0 });
+ * state.on('change:count', (e) => console.log('Count changed to:', e.detail.value));
+ * state.count++;  // Fires events and updates DOM
+ * ```
+ */
+export class State<T extends Record<string, any> = Record<string, any>> {
+  constructor(initialValue?: T, eventTarget?: EventTarget);
+  on(event: string, callback: (e: CustomEvent) => void): this;
+  once(event: string, callback: (e: CustomEvent) => void): this;
+  off(event: string, callback: (e: CustomEvent) => void): this;
+  [key: string]: any;
+}
+
+/**
+ * Create a reactive component with automatic re-rendering on state changes.
+ * 
+ * @param initialState - Initial state object
+ * @param renderFn - Function that takes state and returns a DOM fragment
+ * @param container - Container element where the component renders
+ * @returns The reactive state proxy
+ */
+export function createReactiveComponent<T extends Record<string, any>>(
+  initialState: T,
+  renderFn: (state: State<T>) => DocumentFragment | Node,
+  container: HTMLElement
+): State<T>;
+
+/**
+ * Bind a state container to an element, auto-updating specific properties when state changes.
+ * 
+ * @param element - Element to update
+ * @param state - Reactive state container
+ * @param bindings - Map of property names to update handlers
+ * @returns Cleanup function to remove event listeners
+ */
+export function bindState<T extends Record<string, any>>(
+  element: HTMLElement,
+  state: State<T>,
+  bindings: Record<keyof T, (el: HTMLElement, value: any, oldValue?: any) => void>
+): () => void;

package/src/js/pds.js

@@ -77,6 +77,7 @@ import {
   resolveThemePreference,
 } from "./pds-core/pds-theme-utils.js";
 import { configurePDSLogger, pdsLog } from "./common/pds-log.js";
+import { State, createReactiveComponent, bindState } from "./pds-reactive.js";
 
 let __autoCompletePromise = null;
 let __askPromise = null;
@@ -646,6 +647,15 @@ PDS.parse = parse;
 export const html = common.parseFragment;
 PDS.html = html;
 
+/** Reactive state container for building reactive components */
+PDS.State = State;
+
+// /** Create a reactive component with automatic re-rendering */
+// PDS.createReactiveComponent = createReactiveComponent;
+
+/** Bind state to DOM elements for auto-updating */
+PDS.bindState = bindState;
+
 /** Create a constructable CSSStyleSheet from a CSS string */
 PDS.createStylesheet = createStylesheet;
 
@@ -1184,4 +1194,7 @@ export {
   setLocale,
   getLocalizationState,
   createJSONLocalization,
+  State,
+  createReactiveComponent,
+  bindState,
 };