juxscript 1.0.102 → 1.0.103

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "juxscript",
-  "version": "1.0.102",
+  "version": "1.0.103",
   "type": "module",
   "description": "A JavaScript UX authorship platform",
   "main": "./index.js",
@@ -22,7 +22,12 @@
     "index.js",
     "bin",
     "create",
-    "lib",
+    "lib/**/*.js",
+    "lib/**/*.js.map",
+    "lib/**/*.d.ts",
+    "lib/**/*.d.ts.map",
+    "lib/**/*.css",
+    "lib/**/stubs/*.stub",
     "machinery",
     "types",
     "juxconfig.example.js",

package/lib/componentsv2/base/BaseEngine.ts

@@ -1,332 +0,0 @@
-import { State } from './State.js';
-import { GlobalBus } from './GlobalBus.js';
-import { validateOptions, OptionsContractSchema, ValidationResult } from './OptionsContract.js';
-
-
-export interface JuxServiceContract<TEngine = any> {
-    name: string;
-    version?: string;
-    targetEnv?: 'client' | 'server' | 'universal'; // Environment Constraint
-    install: (engine: TEngine) => void;
-    uninstall?: (engine: TEngine) => void;
-}
-
-export interface BaseState {
-    id: string;
-    classes: string[];
-    visible: boolean;
-    disabled: boolean;
-    loading: boolean;
-    attributes: Record<string, string>;
-}
-
-type EventListener<T = any> = (data: T) => void;
-
-/**
- * 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 abstract class BaseEngine<TState extends BaseState, TOptions = any> {
-    #state: State<TState>;
-    #listeners = new Map<string, Set<EventListener>>();
-    #cleanupListeners: Array<() => void> = [];
-    #plugins = new Map<string, JuxServiceContract>();
-    #emitHistory: string[] = [];
-    #debugMode = false;
-    #validationResult: ValidationResult | null = null;
-
-    constructor(id: string, options: TOptions) {
-        // Validate options if schema is defined
-        const schema = this.optionsSchema;
-        if (schema) {
-            this.#validationResult = validateOptions(
-                this.constructor.name,
-                options as Record<string, any>,
-                schema,
-                this.#debugMode
-            );
-            options = this.#validationResult.normalized as TOptions;
-        }
-
-        // Enforce the Contract: Child must define how state is born from options
-        const initialState = this.prepareState(id, options);
-        this.#state = new State(initialState);
-    }
-
-    /**
-     * CONTRACT: Override to define the valid options schema for this engine.
-     * Enables option validation with helpful error messages.
-     */
-    protected get optionsSchema(): OptionsContractSchema | null {
-        return null; // Override in child classes
-    }
-
-    /**
-     * Access validation results (warnings, errors, normalized options)
-     */
-    get validation(): ValidationResult | null {
-        return this.#validationResult;
-    }
-
-    /**
-     * CONTRACT: Must transform input options into the initial State.
-     * This separates "mapping logic" from "construction/startup logic".
-     */
-    protected abstract prepareState(id: string, options: TOptions): TState;
-
-    get state(): TState {
-        return this.#state.value;
-    }
-
-    subscribe(callback: (value: TState) => void) {
-        return this.#state.subscribe(callback);
-    }
-
-    /**
-     * Enable/Disable Active Console Logging
-     */
-    debug(enabled: boolean = true): this {
-        this.#debugMode = enabled;
-        if (enabled) {
-            console.info(`%c[JUX DEBUG] Mode Enabled for %c${this.state.id}`, 'color: #ff00ff; font-weight: bold;', 'font-weight: bold;');
-        }
-        return this;
-    }
-
-    protected updateState(patch: Partial<TState>): void {
-        if (this.#debugMode) {
-            console.groupCollapsed(`%c 💾 STATE %c ${this.state.id}`, 'color: #ff9900; font-weight: bold;', 'color: #888');
-            console.log('Patch:', patch);
-            console.log('Result:', { ...this.#state.value, ...patch });
-            console.groupEnd();
-        }
-        this.#state.set({ ...this.#state.value, ...patch });
-    }
-
-    /**
-     * Revert the state to the previous snapshot
-     */
-    rollback(): this {
-        this.#state.rollback();
-        this.emit('rollback', { index: this.#state.history.length }); // ✅ Added Emission
-        return this; // ✅ Fluent Return
-    }
-
-    /**
-     * Redo the previously rolled-back state
-     */
-    rollforward(): this {
-        this.#state.rollforward();
-        this.emit('rollforward', { index: this.#state.history.length }); // ✅ Added Emission
-        return this; // ✅ Fluent Return
-    }
-
-    // --- Interaction System ---
-
-    /**
-     * Local Subscription: Subscribe to a specific named event on THIS instance.
-     */
-    on<T = any>(event: string, callback: EventListener<T>): this {
-        if (!this.#listeners.has(event)) {
-            this.#listeners.set(event, new Set());
-        }
-        this.#listeners.get(event)!.add(callback);
-        return this;
-    }
-
-    /**
-     * Unsubscribe from a local event.
-     */
-    off<T = any>(event: string, callback: EventListener<T>): this {
-        this.#listeners.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<T = any>(channel: string, callback: EventListener<T>): this {
-        GlobalBus.on(channel, callback);
-        // Track for cleanup
-        this.#cleanupListeners.push(() => GlobalBus.off(channel, callback));
-        return this;
-    }
-
-    /**
-     * Cleanup all global listeners attached by this engine.
-     */
-    dispose(): void {
-        // 1. Uninstall Plugins
-        this.#plugins.forEach(p => {
-            try {
-                if (p.uninstall) p.uninstall(this);
-            } catch (e) {
-                console.error(`Jux: Error uninstalling plugin ${p.name}`, e);
-            }
-        });
-        this.#plugins.clear();
-
-        // 2. Clear Listeners
-        this.#cleanupListeners.forEach(cleanup => cleanup());
-        this.#cleanupListeners = [];
-
-        if (this.#debugMode) console.log(`%c[JUX] Disposed ${this.state.id}`, 'color: #888');
-    }
-
-    /**
-     * BROADCASTER
-     * Emits locally AND to the global neighborhood.
-     */
-    protected emit(event: string, data: any): void {
-        const timestamp = new Date().toISOString();
-
-        // 0. Record History
-        this.#emitHistory.push(JSON.stringify({ timestamp, event, data }));
-
-        if (this.#debugMode) {
-            console.log(`%c 📡 EMIT %c ${this.state.id}:${event}`, 'color: #00ccff; font-weight: bold;', 'color: #333; font-weight: bold;', data);
-        }
-
-        // 1. Notify Local Listeners
-        this.#listeners.get(event)?.forEach(cb => cb(data));
-
-        // 2. Notify The Neighborhood (Global Bus)
-        // Format: "ComponentID:EventName"
-        const globalChannel = `${this.state.id}:${event}`;
-
-        GlobalBus.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(): Record<string, string[]> {
-        return GlobalBus.registry;
-    }
-
-    /**
-     * DEBUG: Access the Internal State Ledger (History).
-     * Returns an array of JSON strings representing past states.
-     */
-    get stateHistory(): string[] {
-        return this.#state.history;
-    }
-
-    /**
-     * DEBUG: Access the Event Emission Ledger.
-     */
-    get emitHistory(): string[] {
-        return [...this.#emitHistory];
-    }
-
-    /* ═════════════════════════════════════════════════════════════════
-     * EXTENSION SYSTEM (DI / Plugins)
-     * ═════════════════════════════════════════════════════════════════ */
-
-    /**
-     * Inject a Service/Plugin into this Engine.
-     * @param plugin A contract object { name, install, uninstall? }
-     */
-    addPlugin(plugin: JuxServiceContract<this>): this {
-        if (this.#plugins.has(plugin.name)) {
-            console.warn(`Jux: Plugin "${plugin.name}" already registered on ${this.state.id}.`);
-            return this;
-        }
-
-        if (this.#debugMode) {
-            console.log(`%c 🔌 PLUGIN %c Installed: ${plugin.name} (v${plugin.version || '?'})`, 'color: #cc00ff; font-weight: bold;', 'color: #333');
-        }
-
-        this.#plugins.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
-            this.#plugins.delete(plugin.name);
-        }
-
-        return this;
-    }
-
-    /**
-     * Remove a plugin and run its teardown logic.
-     */
-    removePlugin(name: string): this {
-        const plugin = this.#plugins.get(name);
-        if (plugin) {
-            if (plugin.uninstall) {
-                try {
-                    plugin.uninstall(this);
-                } catch (err) {
-                    console.error(`Jux: Error uninstalling plugin "${name}"`, err);
-                }
-            }
-            this.#plugins.delete(name);
-            this.emit('plugin:removed', { name });
-        }
-        return this;
-    }
-
-    /* ═════════════════════════════════════════════════════════════════
-     * COMMON FLUENT API (Universal Capabilities)
-     * ═════════════════════════════════════════════════════════════════ */
-
-    addClass(className: string): this {
-        const current = this.state.classes;
-        if (!current.includes(className)) {
-            this.updateState({ classes: [...current, className] } as Partial<TState>);
-            this.emit('classAdd', { className });
-        }
-        return this;
-    }
-
-    removeClass(className: string): this {
-        const current = this.state.classes;
-        this.updateState({
-            classes: current.filter(c => c !== className)
-        } as Partial<TState>);
-        this.emit('classRemove', { className });
-        return this;
-    }
-
-    visible(isVisible: boolean): this {
-        this.updateState({ visible: isVisible } as Partial<TState>);
-        this.emit('visible', { visible: isVisible });
-        return this;
-    }
-
-    disable(isDisabled: boolean = true): this {
-        this.updateState({ disabled: isDisabled } as Partial<TState>);
-        this.emit('disabled', { disabled: isDisabled });
-        return this;
-    }
-
-    loading(isLoading: boolean = true): this {
-        this.updateState({ loading: isLoading } as Partial<TState>);
-        this.emit('loading', { loading: isLoading });
-        return this;
-    }
-
-    attr(key: string, value: string): this {
-        const current = this.state.attributes;
-        this.updateState({
-            attributes: { ...current, [key]: value }
-        } as Partial<TState>);
-        this.emit('attribute', { key, value });
-        return this;
-    }
-}

package/lib/componentsv2/base/BaseSkin.ts

@@ -1,124 +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 abstract class BaseSkin<TState extends BaseState, TEngine extends BaseEngine<TState>> {
-    protected engine: TEngine;
-    protected root: HTMLElement | null = null;
-
-    constructor(engine: TEngine) {
-        this.engine = engine;
-    }
-
-    /**
-    * 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
-     */
-    public injectCSSLink(id: string, href: string): void {
-        if (typeof document === 'undefined') return;
-
-        let link = document.getElementById(id) as HTMLLinkElement;
-        if (!link) {
-            link = document.createElement('link');
-            link.id = id;
-            link.rel = 'stylesheet';
-            document.head.appendChild(link);
-        }
-
-        if (link.href !== href) {
-            link.href = href;
-        }
-    }
-
-    /**
-     * 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.
-     */
-    public setTheme(cssContent: string): void {
-        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.
-     */
-    public renderSkin(targetElement: HTMLElement, mode: 'append' | 'prepend' = 'append'): void {
-        // 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));
-    }
-
-    protected createRoot(): HTMLElement {
-        return document.createElement('div');
-    }
-
-    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 {
-        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);
-        });
-    }
-}

package/lib/componentsv2/base/GlobalBus.ts

@@ -1,60 +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 class JuxGlobalBus {
-    private listeners = new Map<string, Set<GlobalListener>>();
-
-    on(channel: string, callback: GlobalListener): void {
-        if (!this.listeners.has(channel)) {
-            this.listeners.set(channel, new Set());
-        }
-        this.listeners.get(channel)!.add(callback);
-    }
-
-    off(channel: string, callback: GlobalListener): void {
-        const set = this.listeners.get(channel);
-        if (set) {
-            set.delete(callback);
-            if (set.size === 0) {
-                this.listeners.delete(channel);
-            }
-        }
-    }
-
-    emit(channel: string, data: any): void {
-        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(): Record<string, string[]> {
-        const snapshot: Record<string, string[]> = {};
-        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 GlobalBus = new JuxGlobalBus();

package/lib/componentsv2/base/OptionsContract.ts

@@ -1,139 +0,0 @@
-export interface OptionDefinition {
-    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'function';
-    required?: boolean;
-    default?: any;
-    description?: string;
-    aliases?: string[]; // Common misspellings or alternate names
-}
-
-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 function validateOptions<T extends Record<string, any>>(
-    componentName: string,
-    userOptions: Record<string, any>,
-    schema: OptionsContractSchema,
-    debugMode: boolean = false
-): ValidationResult {
-    const result: ValidationResult = {
-        valid: true,
-        warnings: [],
-        errors: [],
-        normalized: {}
-    };
-
-    const validKeys = new Set(Object.keys(schema));
-    const aliasMap = new Map<string, string>();
-
-    // Build alias lookup
-    for (const [key, def] of Object.entries(schema)) {
-        if (def.aliases) {
-            def.aliases.forEach(alias => aliasMap.set(alias.toLowerCase(), key));
-        }
-    }
-
-    // Check for unknown or aliased options
-    for (const [key, value] of Object.entries(userOptions)) {
-        const lowerKey = key.toLowerCase();
-
-        if (validKeys.has(key)) {
-            // Valid key - validate type
-            const def = schema[key];
-            if (!validateType(value, def.type)) {
-                result.errors.push(
-                    `[${componentName}] Option "${key}" expects type "${def.type}", got "${typeof value}".`
-                );
-                result.valid = false;
-            } else {
-                result.normalized[key] = value;
-            }
-        } else if (aliasMap.has(lowerKey)) {
-            // Found an alias - warn and normalize
-            const correctKey = aliasMap.get(lowerKey)!;
-            result.warnings.push(
-                `[${componentName}] Option "${key}" is not valid. Did you mean "${correctKey}"?`
-            );
-            result.normalized[correctKey] = value;
-        } else {
-            // Unknown option
-            const suggestion = findClosestMatch(key, Array.from(validKeys));
-            const hint = suggestion ? ` Did you mean "${suggestion}"?` : '';
-            result.warnings.push(
-                `[${componentName}] Unknown option "${key}".${hint} Valid options: ${Array.from(validKeys).join(', ')}`
-            );
-        }
-    }
-
-    // Apply defaults for missing required options
-    for (const [key, def] of Object.entries(schema)) {
-        if (!(key in result.normalized)) {
-            if (def.required && def.default === undefined) {
-                result.errors.push(`[${componentName}] Required option "${key}" is missing.`);
-                result.valid = false;
-            } else if (def.default !== undefined) {
-                result.normalized[key] = def.default;
-            }
-        }
-    }
-
-    // Log warnings/errors in debug mode
-    if (debugMode || result.warnings.length || result.errors.length) {
-        result.warnings.forEach(w => console.warn(w));
-        result.errors.forEach(e => console.error(e));
-    }
-
-    return result;
-}
-
-function validateType(value: any, expectedType: string): boolean {
-    if (value === undefined || value === null) return true; // Allow optional
-    switch (expectedType) {
-        case 'string': return typeof value === 'string';
-        case 'number': return typeof value === 'number';
-        case 'boolean': return typeof value === 'boolean';
-        case 'array': return Array.isArray(value);
-        case 'object': return typeof value === 'object' && !Array.isArray(value);
-        case 'function': return typeof value === 'function';
-        default: return true;
-    }
-}
-
-function findClosestMatch(input: string, candidates: string[]): string | null {
-    const lower = input.toLowerCase();
-    let best: string | null = null;
-    let bestScore = Infinity;
-
-    for (const candidate of candidates) {
-        const score = levenshtein(lower, candidate.toLowerCase());
-        if (score < bestScore && score <= 3) { // Max 3 edits
-            bestScore = score;
-            best = candidate;
-        }
-    }
-    return best;
-}
-
-function levenshtein(a: string, b: string): number {
-    const matrix: number[][] = [];
-    for (let i = 0; i <= b.length; i++) matrix[i] = [i];
-    for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
-
-    for (let i = 1; i <= b.length; i++) {
-        for (let j = 1; j <= a.length; j++) {
-            matrix[i][j] = b[i - 1] === a[j - 1]
-                ? matrix[i - 1][j - 1]
-                : Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
-        }
-    }
-    return matrix[b.length][a.length];
-}