juxscript 1.1.80 → 1.1.81

package/lib/components/watcher.ts

@@ -0,0 +1,261 @@
+import { BaseComponent } from "./base/BaseComponent.js";
+
+/**
+ * 🔍 WATCHER - Simple Component Observer
+ * 
+ * Watches JUX components and fires callbacks when their state changes.
+ * Think of it as a "subscribe to component updates" utility.
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * BASIC USAGE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * ```javascript
+ * import { input, paragraph, watcher } from 'juxscript';
+ * 
+ * const nameInput = input('name').render('app');
+ * const greeting = paragraph('greeting').render('app');
+ * 
+ * // Watch nameInput and update greeting whenever it changes
+ * watcher('name-watcher')
+ *     .watch(nameInput, () => {
+ *         greeting.text(`Hello, ${nameInput.getValue()}!`);
+ *     });
+ * ```
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * MULTIPLE COMPONENTS
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * ```javascript
+ * const firstNameInput = input('firstName').render();
+ * const lastNameInput = input('lastName').render();
+ * const fullName = paragraph('fullName').render();
+ * 
+ * const formWatcher = watcher('form');
+ * 
+ * // Watch both inputs, same callback
+ * formWatcher
+ *     .watch(firstNameInput, updateFullName)
+ *     .watch(lastNameInput, updateFullName);
+ * 
+ * function updateFullName() {
+ *     const first = firstNameInput.getValue();
+ *     const last = lastNameInput.getValue();
+ *     fullName.text(`${first} ${last}`.trim());
+ * }
+ * ```
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * DECLARATIVE STYLE - Watch Many, Do One Thing
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * ```javascript
+ * const price = input('price').render();
+ * const quantity = input('quantity').render();
+ * const discount = input('discount').render();
+ * const total = paragraph('total').render();
+ * 
+ * // Update total whenever ANY input changes
+ * watcher('calculator')
+ *     .watchMany([price, quantity, discount], () => {
+ *         const p = parseFloat(price.getValue()) || 0;
+ *         const q = parseInt(quantity.getValue()) || 0;
+ *         const d = parseFloat(discount.getValue()) || 0;
+ *         
+ *         const subtotal = p * q;
+ *         const finalTotal = subtotal - (subtotal * d / 100);
+ *         
+ *         total.text(`Total: $${finalTotal.toFixed(2)}`);
+ *     });
+ * ```
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * STOP WATCHING
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * ```javascript
+ * const myWatcher = watcher('temp');
+ * const myInput = input('field').render();
+ * 
+ * const myCallback = () => console.log('Changed!');
+ * 
+ * myWatcher.watch(myInput, myCallback);
+ * 
+ * // Later: stop watching
+ * myWatcher.unwatch(myInput, myCallback);
+ * 
+ * // Or stop watching ALL callbacks for this component
+ * myWatcher.unwatchAll(myInput);
+ * 
+ * // Or clear everything
+ * myWatcher.clear();
+ * ```
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * HOW IT WORKS
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * 1. Watcher stores callbacks keyed by component._id
+ * 2. Component's Proxy detects state changes
+ * 3. Component calls watcher.notify(component) [if integrated]
+ * 4. Watcher runs all registered callbacks for that component
+ * 
+ * Current limitation: Manual notification required. To auto-notify:
+ * 
+ * ```javascript
+ * // In your component after state change:
+ * this._notifyWatchers();
+ * ```
+ * 
+ * Or integrate into BaseComponent.update():
+ * 
+ * ```typescript
+ * update(prop: string, value: any): void {
+ *     // ...existing update logic...
+ *     this._watchers.forEach(w => w.notify(this));
+ * }
+ * ```
+ */
+
+export class Watcher {
+    private _id: string;
+    private _callbacks: Map<string, Set<Function>> = new Map();
+
+    constructor(id: string) {
+        this._id = id;
+    }
+
+    /**
+     * Watch a component and run callback when it changes
+     * 
+     * @param component - Component to watch
+     * @param callback - Function to run on change
+     * @returns this (for chaining)
+     */
+    watch(component: BaseComponent<any>, callback: Function): this {
+        const id = component._id;
+
+        if (!this._callbacks.has(id)) {
+            this._callbacks.set(id, new Set());
+        }
+
+        this._callbacks.get(id)!.add(callback);
+        return this;
+    }
+
+    /**
+     * Watch multiple components with the same callback
+     * 
+     * @param components - Array of components to watch
+     * @param callback - Function to run when ANY of them change
+     * @returns this (for chaining)
+     */
+    watchMany(components: BaseComponent<any>[], callback: Function): this {
+        components.forEach(component => this.watch(component, callback));
+        return this;
+    }
+
+    /**
+     * Stop watching a component (remove specific callback)
+     * 
+     * @param component - Component to stop watching
+     * @param callback - Specific callback to remove
+     * @returns this (for chaining)
+     */
+    unwatch(component: BaseComponent<any>, callback: Function): this {
+        const id = component._id;
+        const callbacks = this._callbacks.get(id);
+
+        if (callbacks) {
+            callbacks.delete(callback);
+
+            // Clean up empty sets
+            if (callbacks.size === 0) {
+                this._callbacks.delete(id);
+            }
+        }
+
+        return this;
+    }
+
+    /**
+     * Stop watching a component (remove ALL callbacks)
+     * 
+     * @param component - Component to stop watching completely
+     * @returns this (for chaining)
+     */
+    unwatchAll(component: BaseComponent<any>): this {
+        this._callbacks.delete(component._id);
+        return this;
+    }
+
+    /**
+     * Notify all callbacks for a component (call this when component changes)
+     * 
+     * @param component - Component that changed
+     * @param args - Optional arguments to pass to callbacks
+     */
+    notify(component: BaseComponent<any>, ...args: any[]): void {
+        const callbacks = this._callbacks.get(component._id);
+
+        if (callbacks && callbacks.size > 0) {
+            callbacks.forEach(callback => {
+                try {
+                    callback(...args);
+                } catch (error) {
+                    console.error(`[Watcher ${this._id}] Callback error:`, error);
+                }
+            });
+        }
+    }
+
+    /**
+     * Clear all watched components and callbacks
+     * 
+     * @returns this (for chaining)
+     */
+    clear(): this {
+        this._callbacks.clear();
+        return this;
+    }
+
+    /**
+     * Get list of component IDs being watched
+     * 
+     * @returns Array of component IDs
+     */
+    getWatchedIds(): string[] {
+        return Array.from(this._callbacks.keys());
+    }
+
+    /**
+     * Get count of callbacks for a component
+     * 
+     * @param component - Component to check
+     * @returns Number of callbacks registered
+     */
+    getCallbackCount(component: BaseComponent<any>): number {
+        return this._callbacks.get(component._id)?.size || 0;
+    }
+
+    /**
+     * Check if watching a component
+     * 
+     * @param component - Component to check
+     * @returns true if watching this component
+     */
+    isWatching(component: BaseComponent<any>): boolean {
+        return this._callbacks.has(component._id);
+    }
+}
+
+/**
+ * Create a new watcher instance
+ * 
+ * @param id - Unique identifier for this watcher
+ * @returns New Watcher instance
+ */
+export function watcher(id: string): Watcher {
+    return new Watcher(id);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "juxscript",
-  "version": "1.1.80",
+  "version": "1.1.81",
   "type": "module",
   "description": "A JavaScript UX authorship platform",
   "main": "index.js",

package/lib/components/base/FormInput.d.ts

@@ -1,77 +0,0 @@
-import { BaseComponent } from './BaseComponent.js';
-/**
- * Base state interface for all form inputs
- */
-export interface FormInputState extends Record<string, any> {
-    label: string;
-    required: boolean;
-    disabled: boolean;
-    name: string;
-    style: string;
-    class: string;
-    errorMessage?: string;
-}
-/**
- * Abstract base class for all form input components
- * Extends BaseComponent with form-specific functionality
- */
-export declare abstract class FormInput<TState extends FormInputState> extends BaseComponent<TState> {
-    protected _inputElement: HTMLElement | null;
-    protected _labelElement: HTMLLabelElement | null;
-    protected _errorElement: HTMLElement | null;
-    protected _onValidate?: (value: any) => boolean | string;
-    protected _hasBeenValidated: boolean;
-    /**
-     * Get the current value of the input
-     */
-    abstract getValue(): any;
-    /**
-     * Set the value of the input
-     */
-    abstract setValue(value: any): this;
-    /**
-     * Build the actual input element (input, select, textarea, etc.)
-     */
-    protected abstract _buildInputElement(): HTMLElement;
-    /**
-     * Validate the current value
-     */
-    protected abstract _validateValue(value: any): boolean | string;
-    label(value: string): this;
-    required(value: boolean): this;
-    name(value: string): this;
-    onValidate(handler: (value: any) => boolean | string): this;
-    /**
-     * Validate the current value and show/hide errors
-     */
-    validate(): boolean;
-    /**
-     * Check if current value is valid without showing errors
-     */
-    isValid(): boolean;
-    /**
-     * Show error message
-     */
-    protected _showError(message: string): void;
-    /**
-     * Clear error message
-     */
-    protected _clearError(): void;
-    /**
-     * Build label element with auto-generated text from ID if not provided
-     */
-    protected _renderLabel(): HTMLLabelElement;
-    /**
-     * Build error element
-     */
-    protected _renderError(): HTMLElement;
-    /**
-     * Default update implementation for form inputs
-     */
-    update(prop: string, value: any): void;
-    /**
-     * Wire up two-way sync for value property
-     */
-    protected _wireFormSync(inputElement: HTMLElement, eventName?: string): void;
-}
-//# sourceMappingURL=FormInput.d.ts.map

package/lib/components/base/FormInput.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"FormInput.d.ts","sourceRoot":"","sources":["FormInput.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,8BAAsB,SAAS,CAAC,MAAM,SAAS,cAAc,CAAE,SAAQ,aAAa,CAAC,MAAM,CAAC;IACxF,SAAS,CAAC,aAAa,EAAE,WAAW,GAAG,IAAI,CAAQ;IACnD,SAAS,CAAC,aAAa,EAAE,gBAAgB,GAAG,IAAI,CAAQ;IACxD,SAAS,CAAC,aAAa,EAAE,WAAW,GAAG,IAAI,CAAQ;IACnD,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,GAAG,MAAM,CAAC;IACzD,SAAS,CAAC,iBAAiB,EAAE,OAAO,CAAS;IAM7C;;OAEG;IACH,QAAQ,CAAC,QAAQ,IAAI,GAAG;IAExB;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAEnC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,kBAAkB,IAAI,WAAW;IAEpD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,GAAG,MAAM;IAM/D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ1B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAK9B,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzB,UAAU,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,GAAG,MAAM,GAAG,IAAI;IAS3D;;OAEG;IACH,QAAQ,IAAI,OAAO;IAcnB;;OAEG;IACH,OAAO,IAAI,OAAO;IAKlB;;OAEG;IACH,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAa3C;;OAEG;IACH,SAAS,CAAC,WAAW,IAAI,IAAI;IAiB7B;;OAEG;IACH,SAAS,CAAC,YAAY,IAAI,gBAAgB;IAqB1C;;OAEG;IACH,SAAS,CAAC,YAAY,IAAI,WAAW;IAUrC;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAItC;;OAEG;IACH,SAAS,CAAC,aAAa,CAAC,YAAY,EAAE,WAAW,EAAE,SAAS,GAAE,MAAgB,GAAG,IAAI;CA8CxF"}

package/lib/components/base/FormInput.js

@@ -1,171 +0,0 @@
-import { BaseComponent } from './BaseComponent.js';
-import { formatIdAsLabel } from '../../utils/formatId.js'; // ✅ Import utility
-/**
- * Abstract base class for all form input components
- * Extends BaseComponent with form-specific functionality
- */
-export class FormInput extends BaseComponent {
-    constructor() {
-        super(...arguments);
-        this._inputElement = null;
-        this._labelElement = null;
-        this._errorElement = null;
-        this._hasBeenValidated = false; // NEW: Track if user has submitted/validated
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * COMMON FORM INPUT API
-     * ═════════════════════════════════════════════════════════════════ */
-    label(value) {
-        this.state.label = value;
-        if (this._labelElement) {
-            this._labelElement.textContent = value;
-        }
-        return this;
-    }
-    required(value) {
-        this.state.required = value;
-        return this;
-    }
-    name(value) {
-        this.state.name = value;
-        return this;
-    }
-    onValidate(handler) {
-        this._onValidate = handler;
-        return this;
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * VALIDATION
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Validate the current value and show/hide errors
-     */
-    validate() {
-        this._hasBeenValidated = true; // Mark as validated
-        const value = this.getValue();
-        const result = this._validateValue(value);
-        if (result === true) {
-            this._clearError();
-            return true;
-        }
-        else {
-            this._showError(result);
-            return false;
-        }
-    }
-    /**
-     * Check if current value is valid without showing errors
-     */
-    isValid() {
-        const value = this.getValue();
-        return this._validateValue(value) === true;
-    }
-    /**
-     * Show error message
-     */
-    _showError(message) {
-        if (this._errorElement) {
-            this._errorElement.textContent = message;
-            this._errorElement.style.display = 'block';
-        }
-        if (this._inputElement) {
-            this._inputElement.classList.add('jux-input-invalid');
-        }
-        this.state.errorMessage = message;
-    }
-    /**
-     * Clear error message
-     */
-    _clearError() {
-        if (this._errorElement) {
-            this._errorElement.textContent = '';
-            this._errorElement.style.display = 'none';
-        }
-        if (this._inputElement) {
-            this._inputElement.classList.remove('jux-input-invalid');
-        }
-        this.state.errorMessage = undefined;
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * COMMON RENDER HELPERS
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Build label element with auto-generated text from ID if not provided
-     */
-    _renderLabel() {
-        const { label, required } = this.state;
-        const labelEl = document.createElement('label');
-        labelEl.className = 'jux-input-label';
-        labelEl.htmlFor = `${this._id}-input`;
-        // ✅ Use provided label or auto-generate from ID
-        labelEl.textContent = label || formatIdAsLabel(this._id);
-        if (required) {
-            const requiredSpan = document.createElement('span');
-            requiredSpan.className = 'jux-input-required';
-            requiredSpan.textContent = ' *';
-            labelEl.appendChild(requiredSpan);
-        }
-        this._labelElement = labelEl;
-        return labelEl;
-    }
-    /**
-     * Build error element
-     */
-    _renderError() {
-        const errorEl = document.createElement('div');
-        errorEl.className = 'jux-input-error';
-        errorEl.id = `${this._id}-error`;
-        errorEl.style.display = 'none';
-        this._errorElement = errorEl;
-        return errorEl;
-    }
-    /**
-     * Default update implementation for form inputs
-     */
-    update(prop, value) {
-        // No reactive updates needed - form inputs handle their own state
-    }
-    /**
-     * Wire up two-way sync for value property
-     */
-    _wireFormSync(inputElement, eventName = 'input') {
-        const valueSync = this._syncBindings.find(b => b.property === 'value');
-        if (valueSync) {
-            const { stateObj, toState, toComponent } = valueSync;
-            // Default transforms
-            const transformToState = toState || ((v) => v);
-            const transformToComponent = toComponent || ((v) => v);
-            let isUpdating = false;
-            // State → Component
-            stateObj.subscribe((val) => {
-                if (isUpdating)
-                    return;
-                const transformed = transformToComponent(val);
-                this.setValue(transformed);
-            });
-            // Component → State
-            inputElement.addEventListener(eventName, () => {
-                if (isUpdating)
-                    return;
-                isUpdating = true;
-                const value = this.getValue();
-                const transformed = transformToState(value);
-                this._clearError();
-                stateObj.set(transformed);
-                setTimeout(() => { isUpdating = false; }, 0);
-            });
-        }
-        else {
-            // Default behavior without sync
-            inputElement.addEventListener(eventName, () => {
-                this._clearError();
-            });
-        }
-        // Only validate on blur IF the field has been validated before (e.g., after submit)
-        inputElement.addEventListener('blur', () => {
-            if (this._hasBeenValidated) {
-                this.validate();
-            }
-        });
-    }
-}