juxscript 1.1.4 → 1.1.6

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

@@ -0,0 +1,142 @@
+import { State } from '../../reactivity/state.js';
+/**
+ * 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 declare abstract class BaseComponent<TState extends Record<string, any>> {
+    state: TState;
+    container: HTMLElement | null;
+    _id: string;
+    id: string;
+    protected _bindings: Array<{
+        event: string;
+        handler: Function;
+    }>;
+    protected _syncBindings: Array<{
+        property: string;
+        stateObj: State<any>;
+        toState?: Function;
+        toComponent?: Function;
+    }>;
+    protected _triggerHandlers: Map<string, Function>;
+    protected _callbackHandlers: Map<string, Function>;
+    constructor(id: string, initialState: TState);
+    protected abstract getTriggerEvents(): readonly string[];
+    protected abstract getCallbackEvents(): readonly string[];
+    abstract render(targetId?: string): this;
+    /**
+     * Set component style
+     */
+    style(value: string): this;
+    /**
+     * Set component class
+     */
+    class(value: string): this;
+    /**
+     * Add a CSS class to the component
+     */
+    addClass(value: string): this;
+    /**
+     * Remove a CSS class from the component
+     */
+    removeClass(value: string): this;
+    /**
+     * Toggle a CSS class on the component
+     */
+    toggleClass(value: string): this;
+    /**
+     * Set component visibility
+     */
+    visible(value: boolean): this;
+    /**
+     * Show the component
+     */
+    show(): this;
+    /**
+     * Hide the component
+     */
+    hide(): this;
+    /**
+     * Toggle component visibility
+     */
+    toggleVisibility(): this;
+    /**
+     * Set a single HTML attribute
+     */
+    attr(name: string, value: string): this;
+    /**
+     * Set multiple HTML attributes
+     */
+    attrs(attributes: Record<string, string>): this;
+    /**
+     * Remove an HTML attribute
+     */
+    removeAttr(name: string): this;
+    /**
+     * Set disabled state for interactive elements
+     */
+    disabled(value: boolean): this;
+    /**
+     * Enable the component
+     */
+    enable(): this;
+    /**
+     * Disable the component
+     */
+    disable(): this;
+    /**
+     * Set loading state
+     */
+    loading(value: boolean): this;
+    /**
+     * Focus the first focusable element in the component
+     */
+    focus(): this;
+    /**
+     * Blur the currently focused element in the component
+     */
+    blur(): this;
+    /**
+     * Remove the component from the DOM
+     */
+    remove(): this;
+    bind(event: string, handler: Function): this;
+    /**
+     * Sync a component property with a State object
+     * @param property - The property to sync
+     * @param stateObj - The State object to sync with
+     * @param toStateOrTransform - Either toState function OR a simple transform function
+     * @param toComponent - Optional toComponent function (if toState was provided)
+     */
+    sync(property: string, stateObj: State<any>, toStateOrTransform?: Function, toComponent?: Function): this;
+    protected _isTriggerEvent(event: string): boolean;
+    protected _isCallbackEvent(event: string): boolean;
+    protected _triggerCallback(eventName: string, ...args: any[]): void;
+    protected _setupContainer(targetId?: string): HTMLElement;
+    protected _wireStandardEvents(element: HTMLElement): void;
+    /**
+     * Automatically wire ALL sync bindings by calling the corresponding method
+     * if it exists on the component
+     */
+    protected _wireAllSyncs(): void;
+    renderTo(juxComponent: any): this;
+    /**
+     * ✅ Read-only accessor for component state
+     * Provides clear separation between setters (fluent methods) and getters
+     *
+     * @example
+     * const myCard = card('example')
+     *   .title('Hello')      // ✅ SETTER (fluent)
+     *   .content('World');   // ✅ SETTER (fluent)
+     *
+     * console.log(myCard.props.title);    // ✅ GETTER: 'Hello'
+     * console.log(myCard.props.content);  // ✅ GETTER: 'World'
+     */
+    get props(): Readonly<TState>;
+}
+//# sourceMappingURL=BaseComponent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BaseComponent.d.ts","sourceRoot":"","sources":["BaseComponent.ts"],"names":[],"mappings":"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"}

package/lib/components/base/BaseComponent.js

@@ -0,0 +1,363 @@
+import { getOrCreateContainer } from '../helpers.js';
+/**
+ * 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._id = id;
+        this.id = id;
+        this.state = initialState;
+    }
+    /* ═════════════════════════════════════════════════════════════════
+     * COMMON FLUENT API (Inherited by all components)
+     * ═════════════════════════════════════════════════════════════════ */
+    /**
+     * Set component style
+     */
+    style(value) {
+        this.state.style = value;
+        return this;
+    }
+    /**
+     * Set component class
+     */
+    class(value) {
+        this.state.class = value;
+        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);
+        if (!classes.includes(value)) {
+            classes.push(value);
+            this.state.class = classes.join(' ');
+            if (this.container)
+                this.container.classList.add(value);
+        }
+        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(' ');
+        if (this.container)
+            this.container.classList.remove(value);
+        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;
+        if (this.container) {
+            // Find the actual component wrapper, not the parent container
+            const wrapper = this.container.querySelector(`#${this._id}`);
+            if (wrapper) {
+                wrapper.style.display = value ? '' : 'none';
+            }
+        }
+        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;
+        if (this.container) {
+            const inputs = this.container.querySelectorAll('input, button, select, textarea');
+            inputs.forEach(el => {
+                el.disabled = value;
+            });
+            this.container.setAttribute('aria-disabled', String(value));
+        }
+        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;
+        if (this.container) {
+            if (value) {
+                this.container.classList.add('jux-loading');
+                this.container.setAttribute('aria-busy', 'true');
+            }
+            else {
+                this.container.classList.remove('jux-loading');
+                this.container.removeAttribute('aria-busy');
+            }
+        }
+        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;
+        }
+        return this;
+    }
+    /* ═════════════════════════════════════════════════════════════════
+     * EVENT BINDING (Shared logic)
+     * ═════════════════════════════════════════════════════════════════ */
+    bind(event, handler) {
+        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 a component property with a State object
+     * @param property - The property to sync
+     * @param stateObj - The State object to sync with
+     * @param toStateOrTransform - Either toState function OR a simple transform function
+     * @param toComponent - Optional toComponent function (if toState was provided)
+     */
+    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}"`);
+        }
+        // If only 3 args provided, treat the function as toComponent (the common case)
+        const actualToState = (toComponent !== undefined) ? toStateOrTransform : undefined;
+        const actualToComponent = (toComponent !== undefined) ? toComponent : toStateOrTransform;
+        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) {
+        if (this._callbackHandlers.has(eventName)) {
+            const handler = this._callbackHandlers.get(eventName);
+            handler(...args);
+        }
+        else {
+            console.warn(`🔍 No handler found for "${eventName}"`);
+        }
+    }
+    /* ═════════════════════════════════════════════════════════════════
+     * COMMON RENDER HELPERS
+     * ═════════════════════════════════════════════════════════════════ */
+    _setupContainer(targetId) {
+        let container;
+        if (targetId) {
+            // Strip leading # if present
+            const id = targetId.startsWith('#') ? targetId.slice(1) : targetId;
+            const target = document.getElementById(id);
+            if (target) {
+                container = target;
+            }
+            else {
+                // Gracefully create the container instead of throwing
+                console.warn(`[Jux] Target "${targetId}" not found, creating it with graceful fallback`);
+                container = getOrCreateContainer(id);
+            }
+        }
+        else {
+            container = getOrCreateContainer(this._id);
+        }
+        // Add universal component class for DOM inspection
+        // container.classList.add('jux-component');
+        this.container = container;
+        return container;
+    }
+    _wireStandardEvents(element) {
+        this._bindings.forEach(({ event, handler }) => {
+            element.addEventListener(event, handler);
+        });
+    }
+    /**
+     * Automatically wire ALL sync bindings by calling the corresponding method
+     * if it exists on the component
+     */
+    _wireAllSyncs() {
+        this._syncBindings.forEach(({ property, stateObj, toComponent }) => {
+            const transform = toComponent || ((v) => v);
+            // Check if component has a method matching the property name
+            const method = this[property];
+            if (typeof method === 'function') {
+                // Set initial value
+                const initialValue = transform(stateObj.value);
+                method.call(this, initialValue);
+                // Subscribe to changes
+                stateObj.subscribe((val) => {
+                    const transformed = transform(val);
+                    method.call(this, transformed);
+                });
+            }
+            else {
+                console.warn(`[Jux] ${this.constructor.name}.sync('${property}'): ` +
+                    `No method .${property}() found. Property will not be synced.`);
+            }
+        });
+    }
+    renderTo(juxComponent) {
+        if (!juxComponent?._id) {
+            throw new Error(`${this.constructor.name}.renderTo: Invalid component`);
+        }
+        return this.render(`#${juxComponent._id}`);
+    }
+    /* ═════════════════════════════════════════════════════════════════
+     * PROPS ACCESSOR - Read-only access to component state
+     * ═════════════════════════════════════════════════════════════════ */
+    /**
+     * ✅ Read-only accessor for component state
+     * Provides clear separation between setters (fluent methods) and getters
+     *
+     * @example
+     * const myCard = card('example')
+     *   .title('Hello')      // ✅ SETTER (fluent)
+     *   .content('World');   // ✅ SETTER (fluent)
+     *
+     * console.log(myCard.props.title);    // ✅ GETTER: 'Hello'
+     * console.log(myCard.props.content);  // ✅ GETTER: 'World'
+     */
+    get props() {
+        return this.state;
+    }
+}