juxscript 1.1.4 → 1.1.6

package/lib/components/base/BaseComponent.ts

@@ -0,0 +1,421 @@
+import { State } from '../../reactivity/state.js';
+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 abstract class BaseComponent<TState extends Record<string, any>> {
+    // Common properties (all components have these)
+    state: TState;
+    container: HTMLElement | null = null;
+    _id: string;
+    id: string;
+
+    // Event & sync storage (populated by bind() and sync())
+    protected _bindings: Array<{ event: string, handler: Function }> = [];
+    protected _syncBindings: Array<{
+        property: string,
+        stateObj: State<any>,
+        toState?: Function,
+        toComponent?: Function
+    }> = [];
+    protected _triggerHandlers: Map<string, Function> = new Map();
+    protected _callbackHandlers: Map<string, Function> = new Map();
+
+    constructor(id: string, initialState: TState) {
+        this._id = id;
+        this.id = id;
+        this.state = initialState;
+    }
+
+    /* ═════════════════════════════════════════════════════════════════
+     * ABSTRACT METHODS (Child must implement)
+     * ═════════════════════════════════════════════════════════════════ */
+
+    protected abstract getTriggerEvents(): readonly string[];
+    protected abstract getCallbackEvents(): readonly string[];
+    abstract render(targetId?: string): this;
+
+    /* ═════════════════════════════════════════════════════════════════
+     * COMMON FLUENT API (Inherited by all components)
+     * ═════════════════════════════════════════════════════════════════ */
+
+    /**
+     * Set component style
+     */
+    style(value: string): this {
+        (this.state as any).style = value;
+        return this;
+    }
+
+    /**
+     * Set component class
+     */
+    class(value: string): this {
+        (this.state as any).class = value;
+        return this;
+    }
+
+    /* ═════════════════════════════════════════════════════════════════
+     * CSS CLASS MANAGEMENT
+     * ═════════════════════════════════════════════════════════════════ */
+
+    /**
+     * Add a CSS class to the component
+     */
+    addClass(value: string): this {
+        const current = (this.state as any).class || '';
+        const classes = current.split(' ').filter((c: string) => c);
+        if (!classes.includes(value)) {
+            classes.push(value);
+            (this.state as any).class = classes.join(' ');
+            if (this.container) this.container.classList.add(value);
+        }
+        return this;
+    }
+
+    /**
+     * Remove a CSS class from the component
+     */
+    removeClass(value: string): this {
+        const current = (this.state as any).class || '';
+        const classes = current.split(' ').filter((c: string) => c && c !== value);
+        (this.state as any).class = classes.join(' ');
+        if (this.container) this.container.classList.remove(value);
+        return this;
+    }
+
+    /**
+     * Toggle a CSS class on the component
+     */
+    toggleClass(value: string): this {
+        const current = (this.state as any).class || '';
+        const hasClass = current.split(' ').includes(value);
+        return hasClass ? this.removeClass(value) : this.addClass(value);
+    }
+
+    /* ═════════════════════════════════════════════════════════════════
+     * VISIBILITY CONTROL
+     * ═════════════════════════════════════════════════════════════════ */
+
+    /**
+     * Set component visibility
+     */
+    visible(value: boolean): this {
+        (this.state as any).visible = value;
+        if (this.container) {
+            // Find the actual component wrapper, not the parent container
+            const wrapper = this.container.querySelector(`#${this._id}`) as HTMLElement;
+            if (wrapper) {
+                wrapper.style.display = value ? '' : 'none';
+            }
+        }
+        return this;
+    }
+
+    /**
+     * Show the component
+     */
+    show(): this {
+        return this.visible(true);
+    }
+
+    /**
+     * Hide the component
+     */
+    hide(): this {
+        return this.visible(false);
+    }
+
+    /**
+     * Toggle component visibility
+     */
+    toggleVisibility(): this {
+        const isVisible = (this.state as any).visible ?? true;
+        return this.visible(!isVisible);
+    }
+
+    /* ═════════════════════════════════════════════════════════════════
+     * ATTRIBUTE MANAGEMENT
+     * ═════════════════════════════════════════════════════════════════ */
+
+    /**
+     * Set a single HTML attribute
+     */
+    attr(name: string, value: string): this {
+        const attrs = (this.state as any).attributes || {};
+        (this.state as any).attributes = { ...attrs, [name]: value };
+        if (this.container) this.container.setAttribute(name, value);
+        return this;
+    }
+
+    /**
+     * Set multiple HTML attributes
+     */
+    attrs(attributes: Record<string, string>): this {
+        Object.entries(attributes).forEach(([name, value]) => {
+            this.attr(name, value);
+        });
+        return this;
+    }
+
+    /**
+     * Remove an HTML attribute
+     */
+    removeAttr(name: string): this {
+        const attrs = (this.state as any).attributes || {};
+        delete attrs[name];
+        if (this.container) this.container.removeAttribute(name);
+        return this;
+    }
+
+    /* ═════════════════════════════════════════════════════════════════
+     * DISABLED STATE
+     * ═════════════════════════════════════════════════════════════════ */
+
+    /**
+     * Set disabled state for interactive elements
+     */
+    disabled(value: boolean): this {
+        (this.state as any).disabled = value;
+        if (this.container) {
+            const inputs = this.container.querySelectorAll('input, button, select, textarea');
+            inputs.forEach(el => {
+                (el as HTMLInputElement).disabled = value;
+            });
+            this.container.setAttribute('aria-disabled', String(value));
+        }
+        return this;
+    }
+
+    /**
+     * Enable the component
+     */
+    enable(): this {
+        return this.disabled(false);
+    }
+
+    /**
+     * Disable the component
+     */
+    disable(): this {
+        return this.disabled(true);
+    }
+
+    /* ═════════════════════════════════════════════════════════════════
+     * LOADING STATE
+     * ═════════════════════════════════════════════════════════════════ */
+
+    /**
+     * Set loading state
+     */
+    loading(value: boolean): this {
+        (this.state as any).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(): this {
+        if (this.container) {
+            const focusable = this.container.querySelector('input, button, select, textarea, [tabindex]');
+            if (focusable) (focusable as HTMLElement).focus();
+        }
+        return this;
+    }
+
+    /**
+     * Blur the currently focused element in the component
+     */
+    blur(): this {
+        if (this.container) {
+            const focused = this.container.querySelector(':focus');
+            if (focused) (focused as HTMLElement).blur();
+        }
+        return this;
+    }
+
+    /* ═════════════════════════════════════════════════════════════════
+     * DOM MANIPULATION
+     * ═════════════════════════════════════════════════════════════════ */
+
+    /**
+     * Remove the component from the DOM
+     */
+    remove(): this {
+        if (this.container) {
+            this.container.remove();
+            this.container = null;
+        }
+        return this;
+    }
+
+    /* ═════════════════════════════════════════════════════════════════
+     * EVENT BINDING (Shared logic)
+     * ═════════════════════════════════════════════════════════════════ */
+
+    bind(event: string, handler: Function): this {
+        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: string, stateObj: State<any>, toStateOrTransform?: Function, toComponent?: Function): this {
+        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;
+    }
+
+    protected _isTriggerEvent(event: string): boolean {
+        return this.getTriggerEvents().includes(event);
+    }
+
+    protected _isCallbackEvent(event: string): boolean {
+        return this.getCallbackEvents().includes(event);
+    }
+
+    protected _triggerCallback(eventName: string, ...args: any[]): void {
+
+        if (this._callbackHandlers.has(eventName)) {
+            const handler = this._callbackHandlers.get(eventName)!;
+            handler(...args);
+        } else {
+            console.warn(`🔍 No handler found for "${eventName}"`);
+        }
+    }
+
+    /* ═════════════════════════════════════════════════════════════════
+     * COMMON RENDER HELPERS
+     * ═════════════════════════════════════════════════════════════════ */
+
+    protected _setupContainer(targetId?: string): HTMLElement {
+        let container: HTMLElement;
+        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;
+    }
+
+    protected _wireStandardEvents(element: HTMLElement): void {
+        this._bindings.forEach(({ event, handler }) => {
+            element.addEventListener(event, handler as EventListener);
+        });
+    }
+
+    /**
+     * Automatically wire ALL sync bindings by calling the corresponding method
+     * if it exists on the component
+     */
+    protected _wireAllSyncs(): void {
+        this._syncBindings.forEach(({ property, stateObj, toComponent }) => {
+            const transform = toComponent || ((v: any) => v);
+
+            // Check if component has a method matching the property name
+            const method = (this as any)[property];
+
+            if (typeof method === 'function') {
+                // Set initial value
+                const initialValue = transform(stateObj.value);
+                method.call(this, initialValue);
+
+                // Subscribe to changes
+                stateObj.subscribe((val: any) => {
+                    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: any): this {
+        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(): Readonly<TState> {
+        return this.state as Readonly<TState>;
+    }
+}

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

@@ -0,0 +1,73 @@
+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
+     */
+    protected _renderLabel(): HTMLLabelElement;
+    /**
+     * Build error element
+     */
+    protected _renderError(): HTMLElement;
+    /**
+     * 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

@@ -0,0 +1 @@
+{"version":3,"file":"FormInput.d.ts","sourceRoot":"","sources":["FormInput.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;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;IAmB1C;;OAEG;IACH,SAAS,CAAC,YAAY,IAAI,WAAW;IAUrC;;OAEG;IACH,SAAS,CAAC,aAAa,CAAC,YAAY,EAAE,WAAW,EAAE,SAAS,GAAE,MAAgB,GAAG,IAAI;CA8CxF"}

package/lib/components/base/FormInput.js

@@ -0,0 +1,163 @@
+import { BaseComponent } from './BaseComponent.js';
+/**
+ * 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
+     */
+    _renderLabel() {
+        const { label, required } = this.state;
+        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
+     */
+    _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 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();
+            }
+        });
+    }
+}