juxscript 1.1.239 → 1.1.243

package/lib/components/base/BaseComponent.js

@@ -1,735 +0,0 @@
-import { getOrCreateContainer } from '../helpers.js';
-import { registry } from '../registry.js';
-import { stateHistory } from '../history/StateHistory.js';
-import { formatIdAsLabel } from '../../utils/formatId.js';
-import { applyAnimations } from './Animations.js'; // ✅ Import Animations
-/**
- * Abstract base class for all JUX components
- * Provides common storage, event routing, and lifecycle methods
- *
- * Children must provide:
- * - TRIGGER_EVENTS constant (readonly string[])
- * - CALLBACK_EVENTS constant (readonly string[])
- * - render() implementation
- */
-export class BaseComponent {
-    constructor(id, initialState) {
-        this.container = null;
-        // Event & sync storage (populated by bind() and sync())
-        this._bindings = [];
-        this._syncBindings = [];
-        this._triggerHandlers = new Map();
-        this._callbackHandlers = new Map();
-        this._isUpdatingSync = false;
-        // Form-specific protected properties (only used by form components)
-        this._inputElement = null;
-        this._labelElement = null;
-        this._errorElement = null;
-        this._hasBeenValidated = false;
-        this._id = id;
-        this.id = id;
-        const stateWithDefaults = {
-            visible: true,
-            disabled: false,
-            loading: false,
-            class: '',
-            style: '',
-            attributes: {},
-            ...initialState
-        };
-        this.state = new Proxy(stateWithDefaults, {
-            set: (target, prop, value) => {
-                const key = prop;
-                const oldValue = target[key];
-                if (oldValue !== value) {
-                    stateHistory.recordStateChange(this._id, prop, oldValue, value);
-                    target[key] = value;
-                    this.update(prop, value);
-                    if (!this._isUpdatingSync) {
-                        this._notifySyncedState(prop, value);
-                    }
-                }
-                return true;
-            }
-        });
-        // ✅ Apply ONLY animation extensions
-        applyAnimations(this);
-    }
-    /**
-     * REACTIVE UPDATE HOOK (PUBLIC, CONCRETE)
-     * Called automatically when this.state[prop] changes via Proxy.
-     * Default implementation handles base properties.
-     * Children can override to add component-specific logic.
-     */
-    update(prop, value) {
-        if (!this.container)
-            return;
-        const el = this.container.querySelector(`#${this._id}`);
-        if (!el)
-            return;
-        // Handle base properties
-        switch (prop) {
-            case 'visible':
-                el.style.display = value ? '' : 'none';
-                break;
-            case 'class':
-                const baseClasses = el.className.split(' ').filter(c => c.startsWith('jux-'));
-                const userClasses = value.split(' ').filter((c) => c);
-                el.className = [...baseClasses, ...userClasses].join(' ');
-                break;
-            case 'style':
-                el.setAttribute('style', value);
-                break;
-            case 'disabled':
-                el.setAttribute('aria-disabled', String(value));
-                const inputs = el.querySelectorAll('input, button, select, textarea');
-                inputs.forEach(input => {
-                    input.disabled = value;
-                });
-                break;
-            case 'loading':
-                el.classList.toggle('jux-loading', value);
-                el.setAttribute('aria-busy', String(value));
-                break;
-        }
-    }
-    /**
-     * ✨ Notify external State<T> objects when component state changes
-     * Prevents infinite loops with guard flag
-     */
-    _notifySyncedState(prop, value) {
-        const syncBinding = this._syncBindings.find(b => b.property === prop);
-        if (syncBinding) {
-            const { stateObj, toState } = syncBinding;
-            // Set guard flag to prevent recursion
-            this._isUpdatingSync = true;
-            try {
-                const transformedValue = toState ? toState(value) : value;
-                stateObj.set(transformedValue);
-            }
-            finally {
-                // Always clear guard flag
-                this._isUpdatingSync = false;
-            }
-        }
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * COMMON FLUENT API (Inherited by all components)
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Set component style
-     */
-    style(value) {
-        this.state.style = value; // ✅ Triggers update()
-        return this;
-    }
-    /**
-     * Set component class
-     */
-    class(value) {
-        this.state.class = value; // ✅ Triggers update()
-        return this;
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * CSS CLASS MANAGEMENT
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Add a CSS class to the component
-     */
-    addClass(value) {
-        const current = this.state.class || '';
-        const classes = current.split(' ').filter((c) => c && c !== value);
-        classes.push(value);
-        this.state.class = classes.join(' '); // ✅ Triggers update()
-        return this;
-    }
-    /**
-     * Remove a CSS class from the component
-     */
-    removeClass(value) {
-        const current = this.state.class || '';
-        const classes = current.split(' ').filter((c) => c && c !== value);
-        this.state.class = classes.join(' '); // ✅ Triggers update()
-        return this;
-    }
-    /**
-     * Toggle a CSS class on the component
-     */
-    toggleClass(value) {
-        const current = this.state.class || '';
-        const hasClass = current.split(' ').includes(value);
-        return hasClass ? this.removeClass(value) : this.addClass(value);
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * VISIBILITY CONTROL
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Set component visibility
-     */
-    visible(value) {
-        this.state.visible = value; // ✅ Triggers update()
-        return this;
-    }
-    /**
-     * Show the component
-     */
-    show() {
-        return this.visible(true);
-    }
-    /**
-     * Hide the component
-     */
-    hide() {
-        return this.visible(false);
-    }
-    /**
-     * Toggle component visibility
-     */
-    toggleVisibility() {
-        const isVisible = this.state.visible ?? true;
-        return this.visible(!isVisible);
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * ATTRIBUTE MANAGEMENT
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Set a single HTML attribute
-     */
-    attr(name, value) {
-        const attrs = this.state.attributes || {};
-        this.state.attributes = { ...attrs, [name]: value };
-        if (this.container)
-            this.container.setAttribute(name, value);
-        return this;
-    }
-    /**
-     * Set multiple HTML attributes
-     */
-    attrs(attributes) {
-        Object.entries(attributes).forEach(([name, value]) => {
-            this.attr(name, value);
-        });
-        return this;
-    }
-    /**
-     * Remove an HTML attribute
-     */
-    removeAttr(name) {
-        const attrs = this.state.attributes || {};
-        delete attrs[name];
-        if (this.container)
-            this.container.removeAttribute(name);
-        return this;
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * DISABLED STATE
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Set disabled state for interactive elements
-     */
-    disabled(value) {
-        this.state.disabled = value; // ✅ Triggers update()
-        return this;
-    }
-    /**
-     * Enable the component
-     */
-    enable() {
-        return this.disabled(false);
-    }
-    /**
-     * Disable the component
-     */
-    disable() {
-        return this.disabled(true);
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * LOADING STATE
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Set loading state
-     */
-    loading(value) {
-        this.state.loading = value; // ✅ Triggers update()
-        return this;
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * FOCUS MANAGEMENT
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Focus the first focusable element in the component
-     */
-    focus() {
-        if (this.container) {
-            const focusable = this.container.querySelector('input, button, select, textarea, [tabindex]');
-            if (focusable)
-                focusable.focus();
-        }
-        return this;
-    }
-    /**
-     * Blur the currently focused element in the component
-     */
-    blur() {
-        if (this.container) {
-            const focused = this.container.querySelector(':focus');
-            if (focused)
-                focused.blur();
-        }
-        return this;
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * DOM MANIPULATION
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Remove the component from the DOM
-     */
-    remove() {
-        if (this.container) {
-            this.container.remove();
-            this.container = null;
-            // ✅ Unregister when removed
-            registry.unregister(this._id);
-        }
-        return this;
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * EVENT BINDING (Shared logic)
-     * ═════════════════════════════════════════════════════════════════ */
-    bind(event, handler) {
-        // ✅ Record bind event
-        stateHistory.recordEvent(this._id, 'bind', event, { handlerName: handler.name });
-        if (this._isTriggerEvent(event)) {
-            this._triggerHandlers.set(event, handler);
-        }
-        else if (this._isCallbackEvent(event)) {
-            this._callbackHandlers.set(event, handler);
-        }
-        else {
-            this._bindings.push({ event, handler });
-        }
-        return this;
-    }
-    sync(property, stateObj, toStateOrTransform, toComponent) {
-        if (!stateObj || typeof stateObj.subscribe !== 'function') {
-            throw new Error(`${this.constructor.name}.sync: Expected a State object for property "${property}"`);
-        }
-        const actualToState = (toComponent !== undefined) ? toStateOrTransform : undefined;
-        const actualToComponent = (toComponent !== undefined) ? toComponent : toStateOrTransform;
-        // ✅ Record sync event
-        stateHistory.recordEvent(this._id, 'sync', property, {
-            hasToState: !!actualToState,
-            hasToComponent: !!actualToComponent
-        });
-        this._syncBindings.push({
-            property,
-            stateObj,
-            toState: actualToState,
-            toComponent: actualToComponent
-        });
-        return this;
-    }
-    _isTriggerEvent(event) {
-        return this.getTriggerEvents().includes(event);
-    }
-    _isCallbackEvent(event) {
-        return this.getCallbackEvents().includes(event);
-    }
-    _triggerCallback(eventName, ...args) {
-        // ✅ Record callback event
-        stateHistory.recordEvent(this._id, 'callback', eventName, { argsCount: args.length });
-        if (this._callbackHandlers.has(eventName)) {
-            const handler = this._callbackHandlers.get(eventName);
-            handler(...args);
-        }
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * FLUENT EVENT SHORTHANDS
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Register a click event handler
-     */
-    click(handler) {
-        return this.bind('click', handler);
-    }
-    /**
-     * Register a double-click event handler
-     */
-    dblclick(handler) {
-        return this.bind('dblclick', handler);
-    }
-    /**
-     * Register a change event handler
-     */
-    change(handler) {
-        return this.bind('change', handler);
-    }
-    /**
-     * Register an input event handler
-     */
-    input(handler) {
-        return this.bind('input', handler);
-    }
-    /**
-     * Register a mouseover event handler
-     */
-    hover(handler) {
-        return this.bind('mouseover', handler);
-    }
-    /**
-     * Register a mouseout event handler
-     */
-    mouseout(handler) {
-        return this.bind('mouseout', handler);
-    }
-    /**
-     * Register a mousedown event handler
-     */
-    mousedown(handler) {
-        return this.bind('mousedown', handler);
-    }
-    /**
-     * Register a mouseup event handler
-     */
-    mouseup(handler) {
-        return this.bind('mouseup', handler);
-    }
-    /**
-     * Register a focus event handler (renamed to onFocus to avoid conflict with focus() method)
-     */
-    onFocus(handler) {
-        return this.bind('focus', handler);
-    }
-    /**
-     * Register a blur event handler (renamed to onBlur to avoid conflict with blur() method)
-     */
-    onBlur(handler) {
-        return this.bind('blur', handler);
-    }
-    /**
-     * Register a keydown event handler
-     */
-    keydown(handler) {
-        return this.bind('keydown', handler);
-    }
-    /**
-     * Register a keyup event handler
-     */
-    keyup(handler) {
-        return this.bind('keyup', handler);
-    }
-    /**
-     * Register a keypress event handler
-     */
-    keypress(handler) {
-        return this.bind('keypress', handler);
-    }
-    /**
-     * Register a submit event handler
-     */
-    submit(handler) {
-        return this.bind('submit', handler);
-    }
-    /**
-     * Register a scroll event handler
-     */
-    scroll(handler) {
-        return this.bind('scroll', handler);
-    }
-    /**
-     * Register a contextmenu (right-click) event handler
-     */
-    contextmenu(handler) {
-        return this.bind('contextmenu', handler);
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * TIME-TRAVEL DEBUGGING (PUBLIC API)
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Roll back to previous state
-     */
-    rollback() {
-        const snapshot = stateHistory.moveBack();
-        if (snapshot && snapshot.componentId === this._id) {
-            stateHistory.startReplay();
-            this.state[snapshot.property] = snapshot.oldValue;
-            stateHistory.endReplay();
-        }
-        return this;
-    }
-    /**
-     * Roll forward to next state
-     */
-    rollforward() {
-        const snapshot = stateHistory.moveForward();
-        if (snapshot && snapshot.componentId === this._id) {
-            stateHistory.startReplay();
-            this.state[snapshot.property] = snapshot.newValue;
-            stateHistory.endReplay();
-        }
-        return this;
-    }
-    /**
-     * Get complete timeline of this component's changes
-     */
-    timeline() {
-        const stateChanges = stateHistory.getComponentHistory(this._id);
-        const events = stateHistory.getComponentEvents(this._id);
-        return [...stateChanges, ...events].sort((a, b) => a.timestamp - b.timestamp);
-    }
-    /**
-     * Get only state changes for this component
-     */
-    stateHistory() {
-        return stateHistory.getComponentHistory(this._id);
-    }
-    /**
-     * Get only events for this component
-     */
-    eventHistory() {
-        return stateHistory.getComponentEvents(this._id);
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * COMMON RENDER HELPERS
-     * ═════════════════════════════════════════════════════════════════ */
-    _setupContainer(targetId) {
-        // Determine Target Container Type
-        let container;
-        if (targetId) {
-            if (typeof targetId === 'string') {
-                const id = targetId.startsWith('#') ? targetId.slice(1) : targetId;
-                const target = document.getElementById(id);
-                if (target) {
-                    container = target;
-                }
-                else {
-                    console.warn(`[Jux] Target "${targetId}" not found, creating it with graceful fallback`);
-                    container = getOrCreateContainer(id);
-                }
-            }
-            else if (targetId instanceof HTMLElement) {
-                container = targetId;
-            }
-            else if (targetId instanceof BaseComponent) {
-                container = getOrCreateContainer(targetId._id);
-            }
-            else {
-                throw new Error(`[Jux] Invalid targetId type: ${typeof targetId}`);
-            }
-        }
-        else {
-            container = getOrCreateContainer(this._id);
-        }
-        this.container = container;
-        // ✅ Auto-register component when container is set up
-        registry.register(this);
-        return container;
-    }
-    _wireStandardEvents(element) {
-        this._bindings.forEach(({ event, handler }) => {
-            element.addEventListener(event, handler);
-        });
-    }
-    /**
-     * Wire sync subscriptions with guard flag
-     */
-    _wireAllSyncs() {
-        this._syncBindings.forEach(({ property, stateObj, toComponent }) => {
-            const transform = toComponent || ((v) => v);
-            const method = this[property];
-            if (typeof method === 'function') {
-                // Set initial value
-                const initialValue = transform(stateObj.value);
-                this._isUpdatingSync = true;
-                method.call(this, initialValue);
-                this._isUpdatingSync = false;
-                // Subscribe to changes with guard
-                stateObj.subscribe((val) => {
-                    if (this._isUpdatingSync)
-                        return;
-                    const transformed = transform(val);
-                    this._isUpdatingSync = true;
-                    method.call(this, transformed);
-                    this._isUpdatingSync = false;
-                });
-            }
-            else {
-                console.warn(`[Jux] ${this.constructor.name}.sync('${property}'): ` +
-                    `No method .${property}() found. Property will not be synced.`);
-            }
-        });
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * PROPS ACCESSOR - Read-only access to component state
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * ✅ Read-only accessor for component state (getter, not a method)
-     *
-     * Usage:
-     *   const myState = component.props;  // ✅ Correct
-     *   const myState = component.props(); // ❌ Error: props is not a function
-     */
-    get props() {
-        return this.state;
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * FORM INPUT API (Optional - only used by form components)
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Set label for form inputs
-     */
-    label(value) {
-        this.state.label = value;
-        if (this._labelElement) {
-            const requiredSpan = this._labelElement.querySelector('.jux-input-required');
-            this._labelElement.textContent = value;
-            if (requiredSpan)
-                this._labelElement.appendChild(requiredSpan);
-        }
-        return this;
-    }
-    /**
-     * Set required state for form inputs
-     */
-    required(value) {
-        this.state.required = value;
-        return this;
-    }
-    /**
-     * Set name attribute for form inputs
-     */
-    name(value) {
-        this.state.name = value;
-        return this;
-    }
-    /**
-     * Set custom validation handler
-     */
-    onValidate(handler) {
-        this._onValidate = handler;
-        return this;
-    }
-    /**
-     * Validate form input (override in form components)
-     */
-    validate() {
-        console.warn(`${this.constructor.name}.validate() not implemented`);
-        return true;
-    }
-    /**
-     * Check if form input is valid (override in form components)
-     */
-    isValid() {
-        console.warn(`${this.constructor.name}.isValid() not implemented`);
-        return true;
-    }
-    /**
-     * Get current value (override in form components)
-     */
-    getValue() {
-        console.warn(`${this.constructor.name}.getValue() not implemented`);
-        return undefined;
-    }
-    /**
-     * Set current value (override in form components)
-     */
-    setValue(value) {
-        console.warn(`${this.constructor.name}.setValue() not implemented`);
-        return this;
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * FORM VALIDATION HELPERS (Protected - for form components)
-     * ═════════════════════════════════════════════════════════════════ */
-    _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;
-    }
-    _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;
-    }
-    /**
-     * Build label element for form inputs
-     */
-    _renderLabel() {
-        const label = this.state.label || formatIdAsLabel(this._id); // ✅ Auto-generate
-        const required = this.state.required || false;
-        const labelEl = document.createElement('label');
-        labelEl.className = 'jux-input-label';
-        labelEl.htmlFor = `${this._id}-input`;
-        labelEl.textContent = label;
-        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 for form inputs
-     */
-    _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;
-    }
-    /**
-     * Wire up two-way sync for form inputs
-     */
-    _wireFormSync(inputElement, eventName = 'input') {
-        const valueSync = this._syncBindings.find(b => b.property === 'value');
-        if (valueSync) {
-            const { stateObj, toState, toComponent } = valueSync;
-            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
-        inputElement.addEventListener('blur', () => {
-            if (this._hasBeenValidated) {
-                this.validate();
-            }
-        });
-    }
-}