@bookklik/senangstart-actions 0.1.0

package/src/index.js

@@ -0,0 +1,106 @@
+/**
+ * SenangStart Actions v0.1.0
+ * Declarative UI framework for humans and AI agents
+ * 
+ * @license MIT
+ * @author Bookklik
+ * @module senangstart-actions
+ */
+
+import { createReactive } from './reactive.js';
+import { walk, setReferences } from './walker.js';
+import { setupObserver } from './observer.js';
+
+// =========================================================================
+// CSS Injection for ss-cloak
+// =========================================================================
+const style = document.createElement('style');
+style.textContent = '[ss-cloak] { display: none !important; }';
+document.head.appendChild(style);
+
+// =========================================================================
+// Internal State
+// =========================================================================
+const registeredDataFactories = {};  // SenangStart.data() registrations
+const stores = {};                   // SenangStart.store() registrations
+
+// Set references in walker module
+setReferences(registeredDataFactories, stores);
+
+// =========================================================================
+// Public API
+// =========================================================================
+
+const SenangStart = {
+    /**
+     * Register a reusable data component
+     * @param {string} name - Component name
+     * @param {Function} factory - Factory function returning data object
+     */
+    data(name, factory) {
+        if (typeof factory !== 'function') {
+            console.error('[SenangStart] data() requires a factory function');
+            return this;
+        }
+        registeredDataFactories[name] = factory;
+        return this;
+    },
+    
+    /**
+     * Register a global reactive store
+     * @param {string} name - Store name
+     * @param {Object} data - Store data object
+     */
+    store(name, data) {
+        if (typeof data !== 'object') {
+            console.error('[SenangStart] store() requires an object');
+            return this;
+        }
+        stores[name] = createReactive(data, () => {});
+        return this;
+    },
+    
+    /**
+     * Manually initialize a DOM tree
+     * @param {Element} root - Root element to initialize
+     */
+    init(root = document.body) {
+        walk(root, null);
+        return this;
+    },
+    
+    /**
+     * Start the framework
+     */
+    start() {
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', () => {
+                this.init();
+                setupObserver();
+            });
+        } else {
+            this.init();
+            setupObserver();
+        }
+        return this;
+    },
+    
+    /**
+     * Version
+     */
+    version: '0.1.0'
+};
+
+// =========================================================================
+// Auto-start
+// =========================================================================
+
+// Expose globally
+if (typeof window !== 'undefined') {
+    window.SenangStart = SenangStart;
+}
+
+// Auto-start when script loads
+SenangStart.start();
+
+export default SenangStart;

package/src/observer.js

@@ -0,0 +1,42 @@
+/**
+ * SenangStart Actions - MutationObserver
+ * Watch for dynamically added elements
+ * 
+ * @module observer
+ */
+
+import { walk } from './walker.js';
+
+/**
+ * Set up observer for dynamically added elements
+ */
+export function setupObserver() {
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            for (const node of mutation.addedNodes) {
+                if (node.nodeType === 1) {
+                    // Check if node or any ancestor already has scope
+                    let current = node;
+                    let parentScope = null;
+                    
+                    while (current.parentElement) {
+                        current = current.parentElement;
+                        if (current.__ssScope) {
+                            parentScope = current.__ssScope;
+                            break;
+                        }
+                    }
+                    
+                    walk(node, parentScope);
+                }
+            }
+        }
+    });
+    
+    observer.observe(document.body, {
+        childList: true,
+        subtree: true
+    });
+    
+    return observer;
+}

package/src/reactive.js

@@ -0,0 +1,210 @@
+/**
+ * SenangStart Actions - Reactive System
+ * Proxy-based reactivity with dependency tracking
+ * 
+ * @module reactive
+ */
+
+// Array methods that mutate the array
+const ARRAY_MUTATING_METHODS = ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse', 'fill', 'copyWithin'];
+
+// Internal state
+let pendingUpdate = false;
+export const pendingEffects = new Set();
+export let currentEffect = null;
+
+/**
+ * Creates a reactive array that triggers updates on mutations
+ */
+function createReactiveArray(arr, onMutate, subscribers) {
+    const handler = {
+        get(target, prop) {
+            // Track dependency for length and numeric indices
+            if (currentEffect && (prop === 'length' || !isNaN(parseInt(prop)))) {
+                if (!subscribers.has('__array__')) {
+                    subscribers.set('__array__', new Set());
+                }
+                subscribers.get('__array__').add(currentEffect);
+            }
+            
+            const value = target[prop];
+            
+            // Intercept mutating array methods
+            if (ARRAY_MUTATING_METHODS.includes(prop) && typeof value === 'function') {
+                return function(...args) {
+                    const result = Array.prototype[prop].apply(target, args);
+                    
+                    // Notify all array subscribers
+                    if (subscribers.has('__array__')) {
+                        subscribers.get('__array__').forEach(callback => {
+                            pendingEffects.add(callback);
+                        });
+                    }
+                    
+                    scheduleUpdate(onMutate);
+                    return result;
+                };
+            }
+            
+            // Recursively wrap nested objects/arrays
+            if (value && typeof value === 'object') {
+                if (Array.isArray(value)) {
+                    return createReactiveArray(value, onMutate, subscribers);
+                } else {
+                    return createReactiveObject(value, onMutate, subscribers);
+                }
+            }
+            
+            return value;
+        },
+        
+        set(target, prop, value) {
+            const oldValue = target[prop];
+            if (oldValue === value) return true;
+            
+            target[prop] = value;
+            
+            // Notify subscribers
+            if (subscribers.has('__array__')) {
+                subscribers.get('__array__').forEach(callback => {
+                    pendingEffects.add(callback);
+                });
+            }
+            
+            scheduleUpdate(onMutate);
+            return true;
+        }
+    };
+    
+    return new Proxy(arr, handler);
+}
+
+/**
+ * Creates a reactive object that triggers updates on property changes
+ */
+function createReactiveObject(obj, onMutate, subscribers) {
+    const handler = {
+        get(target, prop) {
+            // Skip internal properties
+            if (prop === '__subscribers' || prop === '__isReactive') {
+                return target[prop];
+            }
+            
+            // Track dependency if we're in an effect context
+            if (currentEffect) {
+                if (!subscribers.has(prop)) {
+                    subscribers.set(prop, new Set());
+                }
+                subscribers.get(prop).add(currentEffect);
+            }
+            
+            const value = target[prop];
+            
+            // If it's a function, bind it to the proxy
+            if (typeof value === 'function') {
+                return value.bind(proxy);
+            }
+            
+            // Recursively wrap nested objects/arrays
+            if (value && typeof value === 'object') {
+                if (Array.isArray(value)) {
+                    return createReactiveArray(value, onMutate, subscribers);
+                } else if (!value.__isReactive) {
+                    return createReactiveObject(value, onMutate, subscribers);
+                }
+            }
+            
+            return value;
+        },
+        
+        set(target, prop, value) {
+            const oldValue = target[prop];
+            if (oldValue === value) return true;
+            
+            target[prop] = value;
+            
+            // Notify subscribers for this property
+            if (subscribers.has(prop)) {
+                subscribers.get(prop).forEach(callback => {
+                    pendingEffects.add(callback);
+                });
+            }
+            
+            // Schedule batched update
+            scheduleUpdate(onMutate);
+            
+            return true;
+        },
+        
+        deleteProperty(target, prop) {
+            delete target[prop];
+            
+            if (subscribers.has(prop)) {
+                subscribers.get(prop).forEach(callback => {
+                    pendingEffects.add(callback);
+                });
+            }
+            
+            scheduleUpdate(onMutate);
+            return true;
+        }
+    };
+    
+    const proxy = new Proxy(obj, handler);
+    return proxy;
+}
+
+/**
+ * Creates a reactive proxy that tracks dependencies and triggers updates
+ */
+export function createReactive(data, onUpdate) {
+    const subscribers = new Map(); // property -> Set of callbacks
+    
+    let proxy;
+    if (Array.isArray(data)) {
+        proxy = createReactiveArray(data, onUpdate, subscribers);
+    } else {
+        proxy = createReactiveObject(data, onUpdate, subscribers);
+    }
+    
+    proxy.__subscribers = subscribers;
+    proxy.__isReactive = true;
+    return proxy;
+}
+
+/**
+ * Run an effect function while tracking its dependencies
+ */
+export function runEffect(fn) {
+    currentEffect = fn;
+    try {
+        fn();
+    } finally {
+        currentEffect = null;
+    }
+}
+
+/**
+ * Schedule a batched DOM update
+ */
+export function scheduleUpdate(callback) {
+    if (pendingUpdate) return;
+    
+    pendingUpdate = true;
+    queueMicrotask(() => {
+        pendingUpdate = false;
+        
+        // Run all pending effects
+        const effects = [...pendingEffects];
+        pendingEffects.clear();
+        effects.forEach(effect => {
+            try {
+                runEffect(effect);
+            } catch (e) {
+                console.error('[SenangStart] Effect error:', e);
+            }
+        });
+        
+        if (callback) callback();
+    });
+}

package/src/walker.js

@@ -0,0 +1,117 @@
+/**
+ * SenangStart Actions - DOM Walker
+ * Recursive DOM traversal and initialization
+ * 
+ * @module walker
+ */
+
+import { createReactive } from './reactive.js';
+import { attributeHandlers, handleBind, handleEvent, handleFor, handleIf, setWalkFunction } from './handlers/index.js';
+
+// Store references
+let registeredDataFactories = {};
+let stores = {};
+
+/**
+ * Set external references (called from index.js)
+ */
+export function setReferences(dataFactories, storeRef) {
+    registeredDataFactories = dataFactories;
+    stores = storeRef;
+}
+
+/**
+ * Walk the DOM tree and initialize SenangStart attributes
+ */
+export function walk(el, parentScope = null) {
+    // Skip non-element nodes
+    if (el.nodeType !== 1) return;
+    
+    // Skip if element has ss-ignore
+    if (el.hasAttribute('ss-ignore')) return;
+    
+    let scope = parentScope;
+    
+    // Check for ss-data to create new scope
+    if (el.hasAttribute('ss-data')) {
+        const dataExpr = el.getAttribute('ss-data').trim();
+        let initialData = {};
+        
+        if (dataExpr) {
+            // Check if it's a registered data factory
+            if (registeredDataFactories[dataExpr]) {
+                initialData = registeredDataFactories[dataExpr]();
+            } else {
+                // Parse as object literal - use Function for safety
+                try {
+                    initialData = new Function(`return (${dataExpr})`)();
+                } catch (e) {
+                    console.error('[SenangStart] Failed to parse ss-data:', dataExpr, e);
+                }
+            }
+        }
+        
+        scope = {
+            data: createReactive(initialData, () => {}),
+            $refs: {},
+            $store: stores
+        };
+        
+        // Store scope on element for MutationObserver
+        el.__ssScope = scope;
+    }
+    
+    // If no scope, skip processing directives
+    if (!scope) {
+        // Still walk children in case they have ss-data
+        Array.from(el.children).forEach(child => walk(child, null));
+        return;
+    }
+    
+    // Handle ss-for (must be on template element)
+    if (el.tagName === 'TEMPLATE' && el.hasAttribute('ss-for')) {
+        handleFor(el, el.getAttribute('ss-for'), scope);
+        return; // ss-for handles its own children
+    }
+    
+    // Handle ss-if (must be on template element)
+    if (el.tagName === 'TEMPLATE' && el.hasAttribute('ss-if')) {
+        handleIf(el, el.getAttribute('ss-if'), scope);
+        return; // ss-if handles its own children
+    }
+    
+    // Process all ss-* attributes
+    const attributes = Array.from(el.attributes);
+    
+    for (const attr of attributes) {
+        const name = attr.name;
+        const value = attr.value;
+        
+        // Skip ss-data (already processed) and ss-describe (metadata only)
+        if (name === 'ss-data' || name === 'ss-describe') continue;
+        
+        // Handle standard attributes
+        if (attributeHandlers[name]) {
+            attributeHandlers[name](el, value, scope);
+        }
+        // Handle ss-bind:[attr]
+        else if (name.startsWith('ss-bind:')) {
+            handleBind(el, name, value, scope);
+        }
+        // Handle ss-on:[event]
+        else if (name.startsWith('ss-on:')) {
+            handleEvent(el, name, value, scope);
+        }
+    }
+    
+    // Remove ss-cloak after processing
+    if (el.hasAttribute('ss-cloak')) {
+        el.removeAttribute('ss-cloak');
+    }
+    
+    // Walk children
+    Array.from(el.children).forEach(child => walk(child, scope));
+}
+
+// Set the walk function reference in directives module
+setWalkFunction(walk);