juxscript 1.0.131 → 1.1.0

package/lib/componentsv2/base/BaseEngine.js

@@ -1,279 +0,0 @@
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var _BaseEngine_state, _BaseEngine_listeners, _BaseEngine_cleanupListeners, _BaseEngine_plugins, _BaseEngine_emitHistory, _BaseEngine_debugMode, _BaseEngine_validationResult;
-import { State } from './State.js';
-import { Neighborhood } from './Neighborhood.js';
-import { validateOptions } from './OptionsContract.js';
-/**
- * THE ENGINE AGREEMENT
- *
- * 1. Must define State and Options types.
- * 2. Must implement `prepareState` to map Options -> Initial State.
- * 3. Provides reactivity, eventing, and plugin systems out of the box.
- */
-export class BaseEngine {
-    constructor(id, options) {
-        _BaseEngine_state.set(this, void 0);
-        _BaseEngine_listeners.set(this, new Map());
-        _BaseEngine_cleanupListeners.set(this, []);
-        _BaseEngine_plugins.set(this, new Map());
-        _BaseEngine_emitHistory.set(this, []);
-        _BaseEngine_debugMode.set(this, false);
-        _BaseEngine_validationResult.set(this, null);
-        // Validate options if schema is defined
-        const schema = this.optionsSchema;
-        if (schema) {
-            __classPrivateFieldSet(this, _BaseEngine_validationResult, validateOptions(this.constructor.name, options, schema, __classPrivateFieldGet(this, _BaseEngine_debugMode, "f")), "f");
-            options = __classPrivateFieldGet(this, _BaseEngine_validationResult, "f").normalized;
-        }
-        // Enforce the Contract: Child must define how state is born from options
-        const initialState = this.prepareState(id, options);
-        __classPrivateFieldSet(this, _BaseEngine_state, new State(initialState), "f");
-    }
-    /**
-     * CONTRACT: Override to define the valid options schema for this engine.
-     * Enables option validation with helpful error messages.
-     */
-    get optionsSchema() {
-        return null; // Override in child classes
-    }
-    /**
-     * Access validation results (warnings, errors, normalized options)
-     */
-    get validation() {
-        return __classPrivateFieldGet(this, _BaseEngine_validationResult, "f");
-    }
-    get state() {
-        return __classPrivateFieldGet(this, _BaseEngine_state, "f").value;
-    }
-    subscribe(callback) {
-        return __classPrivateFieldGet(this, _BaseEngine_state, "f").subscribe(callback);
-    }
-    /**
-     * Enable/Disable Active Console Logging
-     */
-    debug(enabled = true) {
-        __classPrivateFieldSet(this, _BaseEngine_debugMode, enabled, "f");
-        if (enabled) {
-            console.info(`%c[JUX DEBUG] Mode Enabled for %c${this.state.id}`, 'color: #ff00ff; font-weight: bold;', 'font-weight: bold;');
-        }
-        return this;
-    }
-    updateState(patch) {
-        if (__classPrivateFieldGet(this, _BaseEngine_debugMode, "f")) {
-            console.groupCollapsed(`%c 💾 STATE %c ${this.state.id}`, 'color: #ff9900; font-weight: bold;', 'color: #888');
-            console.log('Patch:', patch);
-            console.log('Result:', { ...__classPrivateFieldGet(this, _BaseEngine_state, "f").value, ...patch });
-            console.groupEnd();
-        }
-        __classPrivateFieldGet(this, _BaseEngine_state, "f").set({ ...__classPrivateFieldGet(this, _BaseEngine_state, "f").value, ...patch });
-    }
-    /**
-     * Revert the state to the previous snapshot
-     */
-    rollback() {
-        __classPrivateFieldGet(this, _BaseEngine_state, "f").rollback();
-        this.emit('rollback', { index: __classPrivateFieldGet(this, _BaseEngine_state, "f").history.length }); // ✅ Added Emission
-        return this; // ✅ Fluent Return
-    }
-    /**
-     * Redo the previously rolled-back state
-     */
-    rollforward() {
-        __classPrivateFieldGet(this, _BaseEngine_state, "f").rollforward();
-        this.emit('rollforward', { index: __classPrivateFieldGet(this, _BaseEngine_state, "f").history.length }); // ✅ Added Emission
-        return this; // ✅ Fluent Return
-    }
-    // --- Interaction System ---
-    /**
-     * Local Subscription: Subscribe to a specific named event on THIS instance.
-     */
-    on(event, callback) {
-        if (!__classPrivateFieldGet(this, _BaseEngine_listeners, "f").has(event)) {
-            __classPrivateFieldGet(this, _BaseEngine_listeners, "f").set(event, new Set());
-        }
-        __classPrivateFieldGet(this, _BaseEngine_listeners, "f").get(event).add(callback);
-        return this;
-    }
-    /**
-     * Unsubscribe from a local event.
-     */
-    off(event, callback) {
-        __classPrivateFieldGet(this, _BaseEngine_listeners, "f").get(event)?.delete(callback);
-        return this;
-    }
-    /**
-     * THE LISTENER (Neighborhood Watch)
-     * Listen for events broadcasting on the global frequency.
-     * @param channel The global channel name (e.g. 'demo-list-v2:move')
-     * @param callback Reaction logic
-     */
-    listenTo(channel, callback) {
-        Neighborhood.on(channel, callback);
-        // Track for cleanup
-        __classPrivateFieldGet(this, _BaseEngine_cleanupListeners, "f").push(() => Neighborhood.off(channel, callback));
-        return this;
-    }
-    /**
-     * Cleanup all global listeners attached by this engine.
-     */
-    dispose() {
-        // 1. Uninstall Plugins
-        __classPrivateFieldGet(this, _BaseEngine_plugins, "f").forEach(p => {
-            try {
-                if (p.uninstall)
-                    p.uninstall(this);
-            }
-            catch (e) {
-                console.error(`Jux: Error uninstalling plugin ${p.name}`, e);
-            }
-        });
-        __classPrivateFieldGet(this, _BaseEngine_plugins, "f").clear();
-        // 2. Clear Listeners
-        __classPrivateFieldGet(this, _BaseEngine_cleanupListeners, "f").forEach(cleanup => cleanup());
-        __classPrivateFieldSet(this, _BaseEngine_cleanupListeners, [], "f");
-        if (__classPrivateFieldGet(this, _BaseEngine_debugMode, "f"))
-            console.log(`%c[JUX] Disposed ${this.state.id}`, 'color: #888');
-    }
-    /**
-     * BROADCASTER
-     * Emits locally AND to the global neighborhood.
-     */
-    emit(event, data) {
-        const timestamp = new Date().toISOString();
-        // 0. Record History
-        __classPrivateFieldGet(this, _BaseEngine_emitHistory, "f").push(JSON.stringify({ timestamp, event, data }));
-        if (__classPrivateFieldGet(this, _BaseEngine_debugMode, "f")) {
-            console.log(`%c 📡 EMIT %c ${this.state.id}:${event}`, 'color: #00ccff; font-weight: bold;', 'color: #333; font-weight: bold;', data);
-        }
-        // 1. Notify Local Listeners
-        __classPrivateFieldGet(this, _BaseEngine_listeners, "f").get(event)?.forEach(cb => cb(data));
-        // 2. Notify The Neighborhood (Global Bus)
-        // Format: "ComponentID:EventName"
-        const globalChannel = `${this.state.id}:${event}`;
-        Neighborhood.emit(globalChannel, {
-            ...data,
-            _event: event,
-            _source: this.state.id
-        });
-    }
-    /**
-     * DEBUG: Access the Global Event Bus registry to see active channels and listener identities.
-     * Useful for debugging communication topology from the console.
-     */
-    get eventRegistry() {
-        return Neighborhood.registry;
-    }
-    /**
-     * DEBUG: Access the Internal State Ledger (History).
-     * Returns an array of JSON strings representing past states.
-     */
-    get stateHistory() {
-        return __classPrivateFieldGet(this, _BaseEngine_state, "f").history;
-    }
-    /**
-     * DEBUG: Access the Event Emission Ledger.
-     */
-    get emitHistory() {
-        return [...__classPrivateFieldGet(this, _BaseEngine_emitHistory, "f")];
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * EXTENSION SYSTEM (DI / Plugins)
-     * ═════════════════════════════════════════════════════════════════ */
-    /**
-     * Inject a Service/Plugin into this Engine.
-     * @param plugin A contract object { name, install, uninstall? }
-     */
-    addPlugin(plugin) {
-        if (__classPrivateFieldGet(this, _BaseEngine_plugins, "f").has(plugin.name)) {
-            console.warn(`Jux: Plugin "${plugin.name}" already registered on ${this.state.id}.`);
-            return this;
-        }
-        if (__classPrivateFieldGet(this, _BaseEngine_debugMode, "f")) {
-            console.log(`%c 🔌 PLUGIN %c Installed: ${plugin.name} (v${plugin.version || '?'})`, 'color: #cc00ff; font-weight: bold;', 'color: #333');
-        }
-        __classPrivateFieldGet(this, _BaseEngine_plugins, "f").set(plugin.name, plugin);
-        try {
-            plugin.install(this);
-            this.emit('plugin:added', { name: plugin.name });
-        }
-        catch (err) {
-            console.error(`Jux: Failed to install plugin "${plugin.name}"`, err);
-            // Rollback registration on failure
-            __classPrivateFieldGet(this, _BaseEngine_plugins, "f").delete(plugin.name);
-        }
-        return this;
-    }
-    /**
-     * Remove a plugin and run its teardown logic.
-     */
-    removePlugin(name) {
-        const plugin = __classPrivateFieldGet(this, _BaseEngine_plugins, "f").get(name);
-        if (plugin) {
-            if (plugin.uninstall) {
-                try {
-                    plugin.uninstall(this);
-                }
-                catch (err) {
-                    console.error(`Jux: Error uninstalling plugin "${name}"`, err);
-                }
-            }
-            __classPrivateFieldGet(this, _BaseEngine_plugins, "f").delete(name);
-            this.emit('plugin:removed', { name });
-        }
-        return this;
-    }
-    /* ═════════════════════════════════════════════════════════════════
-     * COMMON FLUENT API (Universal Capabilities)
-     * ═════════════════════════════════════════════════════════════════ */
-    addClass(className) {
-        const current = this.state.classes;
-        if (!current.includes(className)) {
-            this.updateState({ classes: [...current, className] });
-            this.emit('classAdd', { className });
-        }
-        return this;
-    }
-    removeClass(className) {
-        const current = this.state.classes;
-        this.updateState({
-            classes: current.filter(c => c !== className)
-        });
-        this.emit('classRemove', { className });
-        return this;
-    }
-    visible(isVisible) {
-        this.updateState({ visible: isVisible });
-        this.emit('visible', { visible: isVisible });
-        return this;
-    }
-    disable(isDisabled = true) {
-        this.updateState({ disabled: isDisabled });
-        this.emit('disabled', { disabled: isDisabled });
-        return this;
-    }
-    loading(isLoading = true) {
-        this.updateState({ loading: isLoading });
-        this.emit('loading', { loading: isLoading });
-        return this;
-    }
-    attr(key, value) {
-        const current = this.state.attributes;
-        this.updateState({
-            attributes: { ...current, [key]: value }
-        });
-        this.emit('attribute', { key, value });
-        return this;
-    }
-}
-_BaseEngine_state = new WeakMap(), _BaseEngine_listeners = new WeakMap(), _BaseEngine_cleanupListeners = new WeakMap(), _BaseEngine_plugins = new WeakMap(), _BaseEngine_emitHistory = new WeakMap(), _BaseEngine_debugMode = new WeakMap(), _BaseEngine_validationResult = new WeakMap();
-//# sourceMappingURL=BaseEngine.js.map

package/lib/componentsv2/base/BaseSkin.d.ts

@@ -1,74 +0,0 @@
-import { BaseEngine, BaseState } from './BaseEngine.js';
-/**
- * THE SKIN AGREEMENT
- *
- * A Skin must:
- * 1. Hold a reference to its Engine.
- * 2. Implement `structureCss` to provide layout styles.
- * 3. Implement hooks for creation (`createRoot`) and event binding (`bindEvents`).
- * 4. Implement `updateSkin(state)` to react to State changes.
- */
-export declare abstract class BaseSkin<TState extends BaseState, TEngine extends BaseEngine<TState>> {
-    protected engine: TEngine;
-    protected root: HTMLElement | null;
-    private _cleanupTasks;
-    constructor(engine: TEngine);
-    /**
-    * CONTRACT: Provide the URL/Path to the structural CSS file.
-    *
-    * 💡 WHY `import.meta.url`?
-    * Standard `import` statements load JS modules. To load ASSETS (like CSS) at runtime,
-    * we need their full URL. `import.meta.url` tells the browser "Start looking from THIS file".
-    *
-    * Usage: return new URL('./structure.css', import.meta.url).href;
-    */
-    protected abstract get structureCss(): string;
-    /**
-     * Utility: Inject or Update a CSS Link tag in the document head.
-     * Allows for external CSS files ('references') and runtime Theme Swapping.
-     * @param id Unique ID for the link tag
-     * @param href The URL to the CSS file
-     */
-    injectCSSLink(id: string, href: string): void;
-    /**
-     * Utility: Subscribe to MY Engine's events.
-     * "Me" refers to this component instance (Engine + Skin).
-     *
-     * Use this for internal signals like "loginSuccess", "error", or "animationStart".
-     */
-    protected onSelf(event: string, callback: (data: any) => void): void;
-    /**
-     * Utility: Subscribe to the Global Bus (The Neighborhood).
-     * "Neighbors" refers to other components or global system events.
-     *
-     * Use this for purely visual coordination like "theme:switched" or "layout:collapse-all".
-     */
-    protected onNeighbor(channel: string, callback: (data: any) => void): void;
-    /**
-     * Component Teardown.
-     * Removes the root element and cleans up all event listeners.
-     */
-    dispose(): void;
-    /**
-     * Utility: Inject CSS into the document head if not already present.
-     * Useful for Skins to seamlessly load their required aesthetics.
-     */
-    /**
-     * API: Hot-Swap the Aesthetic Skin.
-     * Replaces the component-specific CSS styles at runtime.
-     */
-    setTheme(cssContent: string): void;
-    /**
-     * Template Method: Render
-     * Orchestrates the standard lifecycle: Create -> Bind -> Mount -> Subscribe.
-     */
-    renderSkin(targetElement: HTMLElement, mode?: 'append' | 'prepend'): void;
-    protected createRoot(): HTMLElement;
-    protected abstract bindEvents(root: HTMLElement): void;
-    protected abstract updateSkin(state: TState): void;
-    /**
-     * HELPER: Applies universal Jux behavior (visibility, ID, disabled)
-     */
-    protected applySkinAttributes(element: HTMLElement, state: TState): void;
-}
-//# sourceMappingURL=BaseSkin.d.ts.map

package/lib/componentsv2/base/BaseSkin.js

@@ -1,130 +0,0 @@
-import { Neighborhood } from './Neighborhood.js';
-/**
- * THE SKIN AGREEMENT
- *
- * A Skin must:
- * 1. Hold a reference to its Engine.
- * 2. Implement `structureCss` to provide layout styles.
- * 3. Implement hooks for creation (`createRoot`) and event binding (`bindEvents`).
- * 4. Implement `updateSkin(state)` to react to State changes.
- */
-export class BaseSkin {
-    constructor(engine) {
-        this.root = null;
-        this._cleanupTasks = [];
-        this.engine = engine;
-    }
-    /**
-     * Utility: Inject or Update a CSS Link tag in the document head.
-     * Allows for external CSS files ('references') and runtime Theme Swapping.
-     * @param id Unique ID for the link tag
-     * @param href The URL to the CSS file
-     */
-    injectCSSLink(id, href) {
-        if (typeof document === 'undefined')
-            return;
-        let link = document.getElementById(id);
-        if (!link) {
-            link = document.createElement('link');
-            link.id = id;
-            link.rel = 'stylesheet';
-            document.head.appendChild(link);
-        }
-        if (link.href !== href) {
-            link.href = href;
-        }
-    }
-    /**
-     * Utility: Subscribe to MY Engine's events.
-     * "Me" refers to this component instance (Engine + Skin).
-     *
-     * Use this for internal signals like "loginSuccess", "error", or "animationStart".
-     */
-    onSelf(event, callback) {
-        this.engine.on(event, callback);
-        this._cleanupTasks.push(() => this.engine.off(event, callback));
-    }
-    /**
-     * Utility: Subscribe to the Global Bus (The Neighborhood).
-     * "Neighbors" refers to other components or global system events.
-     *
-     * Use this for purely visual coordination like "theme:switched" or "layout:collapse-all".
-     */
-    onNeighbor(channel, callback) {
-        Neighborhood.on(channel, callback);
-        this._cleanupTasks.push(() => Neighborhood.off(channel, callback));
-    }
-    /**
-     * Component Teardown.
-     * Removes the root element and cleans up all event listeners.
-     */
-    dispose() {
-        this._cleanupTasks.forEach(task => task());
-        this._cleanupTasks = [];
-        if (this.root) {
-            this.root.remove();
-            this.root = null;
-        }
-    }
-    /**
-     * Utility: Inject CSS into the document head if not already present.
-     * Useful for Skins to seamlessly load their required aesthetics.
-     */
-    /**
-     * API: Hot-Swap the Aesthetic Skin.
-     * Replaces the component-specific CSS styles at runtime.
-     */
-    setTheme(cssContent) {
-        const id = `jux-skin-${this.engine.state.id}-theme`;
-        const oldStyle = document.getElementById(id);
-        if (oldStyle)
-            oldStyle.remove();
-    }
-    /**
-     * Template Method: Render
-     * Orchestrates the standard lifecycle: Create -> Bind -> Mount -> Subscribe.
-     */
-    renderSkin(targetElement, mode = 'append') {
-        // 0. Inject Immutable Structure (Layout logic)
-        // We use constructor.name to deduplicate style tags across multiple instances of the same component type.
-        // 1. Create Root (Abstract Hook)
-        this.root = this.createRoot();
-        // 2. Bind Events (Hook)
-        this.bindEvents(this.root);
-        // 3. Mount
-        if (mode === 'prepend') {
-            targetElement.prepend(this.root);
-        }
-        else {
-            targetElement.appendChild(this.root);
-        }
-        // 4. Subscribe (Automatic)
-        this.engine.subscribe((state) => this.updateSkin(state));
-    }
-    createRoot() {
-        return document.createElement('div');
-    }
-    /**
-     * HELPER: Applies universal Jux behavior (visibility, ID, disabled)
-     */
-    applySkinAttributes(element, state) {
-        element.style.display = state.visible ? '' : 'none';
-        element.dataset.id = state.id;
-        if (state.disabled) {
-            element.setAttribute('aria-disabled', 'true');
-        }
-        else {
-            element.removeAttribute('aria-disabled');
-        }
-        if (state.loading) {
-            element.setAttribute('aria-busy', 'true');
-        }
-        else {
-            element.removeAttribute('aria-busy');
-        }
-        Object.entries(state.attributes).forEach(([k, v]) => {
-            element.setAttribute(k, v);
-        });
-    }
-}
-//# sourceMappingURL=BaseSkin.js.map

package/lib/componentsv2/base/Neighborhood.d.ts

@@ -1,22 +0,0 @@
-type GlobalListener = (data: any) => void;
-/**
- * THE NEIGHBORHOOD (Global Event Mediator)
- *
- * Acts as the certal nervous system where all components post updates.
- * Other components can tune in to specific frequencies (channels) here.
- */
-export declare class JuxGlobalBus {
-    private listeners;
-    on(channel: string, callback: GlobalListener): void;
-    off(channel: string, callback: GlobalListener): void;
-    emit(channel: string, data: any): void;
-    /**
-     * DEBUG: Read-only Snapshot of active channels and listener identities.
-     * usage: juxV2.events.registry
-     * Returns: { "channelName": ["functionName", "(anonymous)"] }
-     */
-    get registry(): Record<string, string[]>;
-}
-export declare const Neighborhood: JuxGlobalBus;
-export {};
-//# sourceMappingURL=Neighborhood.d.ts.map

package/lib/componentsv2/base/Neighborhood.js

@@ -1,56 +0,0 @@
-/**
- * THE NEIGHBORHOOD (Global Event Mediator)
- *
- * Acts as the certal nervous system where all components post updates.
- * Other components can tune in to specific frequencies (channels) here.
- */
-export class JuxGlobalBus {
-    constructor() {
-        this.listeners = new Map();
-    }
-    on(channel, callback) {
-        if (!this.listeners.has(channel)) {
-            this.listeners.set(channel, new Set());
-        }
-        this.listeners.get(channel).add(callback);
-    }
-    off(channel, callback) {
-        const set = this.listeners.get(channel);
-        if (set) {
-            set.delete(callback);
-            if (set.size === 0) {
-                this.listeners.delete(channel);
-            }
-        }
-    }
-    emit(channel, data) {
-        const set = this.listeners.get(channel);
-        if (set) {
-            set.forEach(callback => {
-                try {
-                    callback(data);
-                }
-                catch (e) {
-                    console.error(`Jux GlobalBus Error [${channel}]:`, e);
-                }
-            });
-        }
-        // Optional: We could have a wildcard '*' listener here for debuggers/loggers
-    }
-    /**
-     * DEBUG: Read-only Snapshot of active channels and listener identities.
-     * usage: juxV2.events.registry
-     * Returns: { "channelName": ["functionName", "(anonymous)"] }
-     */
-    get registry() {
-        const snapshot = {};
-        this.listeners.forEach((set, channel) => {
-            // Map the Set of functions to their names for easier debugging
-            snapshot[channel] = Array.from(set).map(fn => fn.name || '(anonymous)');
-        });
-        return snapshot;
-    }
-}
-// Singleton Instance
-export const Neighborhood = new JuxGlobalBus();
-//# sourceMappingURL=Neighborhood.js.map

package/lib/componentsv2/base/OptionsContract.d.ts

@@ -1,20 +0,0 @@
-export interface OptionDefinition {
-    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'function';
-    required?: boolean;
-    default?: any;
-    description?: string;
-    aliases?: string[];
-}
-export type OptionsContractSchema = Record<string, OptionDefinition>;
-export interface ValidationResult {
-    valid: boolean;
-    warnings: string[];
-    errors: string[];
-    normalized: Record<string, any>;
-}
-/**
- * Validates user-provided options against a defined contract schema.
- * Emits warnings for unknown/misnamed options and errors for type mismatches.
- */
-export declare function validateOptions<T extends Record<string, any>>(componentName: string, userOptions: Record<string, any>, schema: OptionsContractSchema, debugMode?: boolean): ValidationResult;
-//# sourceMappingURL=OptionsContract.d.ts.map