snice 1.0.0 → 1.2.0

package/src/element.ts

@@ -0,0 +1,259 @@
+import { attachController, detachController } from './controller';
+import { setupEventHandlers, cleanupEventHandlers } from './events';
+import { IS_ELEMENT_CLASS, READY_PROMISE, READY_RESOLVE, CONTROLLER, PROPERTIES, PROPERTY_VALUES } from './symbols';
+
+export function element(tagName: string) {
+  return function (constructor: any) {
+    // Mark as element class for channel decorator detection
+    (constructor.prototype as any)[IS_ELEMENT_CLASS] = true;
+    
+    // Add controller property to all elements
+    const originalConnectedCallback = constructor.prototype.connectedCallback;
+    const originalDisconnectedCallback = constructor.prototype.disconnectedCallback;
+    const originalAttributeChangedCallback = constructor.prototype.attributeChangedCallback;
+    
+    // Add 'controller' to observed attributes
+    const observedAttributes = constructor.observedAttributes || [];
+    if (!observedAttributes.includes('controller')) {
+      observedAttributes.push('controller');
+    }
+    Object.defineProperty(constructor, 'observedAttributes', {
+      get() { return observedAttributes; },
+      configurable: true
+    });
+    
+    // Add ready property - always returns a promise
+    Object.defineProperty(constructor.prototype, 'ready', {
+      get() {
+        if (!this[READY_PROMISE]) {
+          // Create a pending promise if not yet initialized
+          this[READY_PROMISE] = new Promise<void>((resolve) => {
+            this[READY_RESOLVE] = resolve;
+          });
+        }
+        return this[READY_PROMISE];
+      },
+      enumerable: true,
+      configurable: true
+    });
+    
+    // Add controller property
+    Object.defineProperty(constructor.prototype, 'controller', {
+      get() {
+        return this[CONTROLLER];
+      },
+      set(value: string) {
+        const oldValue = this[CONTROLLER];
+        this[CONTROLLER] = value;
+        if (value !== oldValue && value) {
+          // Attach controller asynchronously
+          attachController(this, value).catch(error => {
+            console.error(`Failed to attach controller "${value}":`, error);
+          });
+        } else if (!value && oldValue) {
+          // Detach controller asynchronously
+          detachController(this).catch(error => {
+            console.error(`Failed to detach controller:`, error);
+          });
+        }
+      },
+      enumerable: true,
+      configurable: true
+    });
+    
+    constructor.prototype.connectedCallback = async function() {
+      // If ready promise was already created (controller attached before connected), use existing resolve
+      // Otherwise create the ready promise now
+      if (!this[READY_PROMISE]) {
+        this[READY_PROMISE] = new Promise<void>((resolve) => {
+          this[READY_RESOLVE] = resolve;
+        });
+      }
+      
+      try {
+        // Clean up any existing event handlers first (for reconnection)
+        cleanupEventHandlers(this);
+        
+        // Create shadow root if it doesn't exist
+        if (!this.shadowRoot) {
+          this.attachShadow({ mode: 'open' });
+        }
+        
+        // Build the shadow DOM content
+        let shadowContent = '';
+        
+        // Add HTML first (maintaining original order)
+        if (this.html) {
+          try {
+            const htmlResult = this.html();
+            // Handle both async and sync html
+            const htmlContent = htmlResult instanceof Promise ? await htmlResult : htmlResult;
+            if (htmlContent !== undefined) {
+              shadowContent += htmlContent;
+            }
+          } catch (error) {
+            console.error(`Error in html() method for ${this.tagName}:`, error);
+          }
+        }
+        
+        // Add CSS after HTML (maintaining original order)
+        if (this.css) {
+          try {
+            const cssResult = this.css();
+            // Handle both async and sync css
+            const cssResolved = cssResult instanceof Promise ? await cssResult : cssResult;
+            if (cssResolved) {
+              // Handle both string and array of strings
+              const cssContent = Array.isArray(cssResolved) ? cssResolved.join('\n') : cssResolved;
+              // No need for scoping with Shadow DOM, but add data attribute for compatibility
+              shadowContent += `<style data-component-css>${cssContent}</style>`;
+            }
+          } catch (error) {
+            console.error(`Error in css() method for ${this.tagName}:`, error);
+          }
+        }
+        
+        // Set shadow DOM content
+        if (shadowContent) {
+          this.shadowRoot.innerHTML = shadowContent;
+        }
+        
+        originalConnectedCallback?.call(this);
+        
+        const controllerName = this.getAttribute('controller');
+        if (controllerName) {
+          this.controller = controllerName;
+        }
+        // Setup @on event handlers - use element for host events, shadow root for delegated events
+        setupEventHandlers(this, this);
+      } finally {
+        // Always mark element as ready, even if there were errors
+        if (this[READY_RESOLVE]) {
+          this[READY_RESOLVE]();
+          this[READY_RESOLVE] = null; // Clear the resolver
+        }
+      }
+    };
+    
+    constructor.prototype.disconnectedCallback = function() {
+      originalDisconnectedCallback?.call(this);
+      if (this[CONTROLLER]) {
+        detachController(this).catch(error => {
+          console.error(`Failed to detach controller:`, error);
+        });
+      }
+      // Cleanup @on event handlers
+      cleanupEventHandlers(this);
+    };
+    
+    constructor.prototype.attributeChangedCallback = function(name: string, oldValue: string, newValue: string) {
+      originalAttributeChangedCallback?.call(this, name, oldValue, newValue);
+      if (name === 'controller') {
+        this.controller = newValue;
+      }
+    };
+    
+    customElements.define(tagName, constructor);
+  };
+}
+
+// Alias for backwards compatibility
+export const customElement = element;
+
+export function property(options?: PropertyOptions) {
+  return function (target: any, propertyKey: string) {
+    const constructor = target.constructor;
+    
+    if (!constructor[PROPERTIES]) {
+      constructor[PROPERTIES] = new Map();
+    }
+    
+    constructor[PROPERTIES].set(propertyKey, options || {});
+    
+    const descriptor: PropertyDescriptor = {
+      get(this: any) {
+        if (!this[PROPERTY_VALUES]) {
+          this[PROPERTY_VALUES] = {};
+        }
+        return this[PROPERTY_VALUES][propertyKey];
+      },
+      set(this: any, value: any) {
+        if (!this[PROPERTY_VALUES]) {
+          this[PROPERTY_VALUES] = {};
+        }
+        const oldValue = this[PROPERTY_VALUES][propertyKey];
+        
+        // Don't update if value hasn't changed
+        if (oldValue === value) return;
+        
+        this[PROPERTY_VALUES][propertyKey] = value;
+        
+        if (options?.reflect && this.setAttribute) {
+          if (value === null || value === undefined || value === false) {
+            this.removeAttribute(options.attribute || propertyKey);
+          } else {
+            this.setAttribute(options.attribute || propertyKey, String(value));
+          }
+        }
+        
+        // Call requestUpdate if available and value changed
+        if (this.requestUpdate) {
+          this.requestUpdate(propertyKey, oldValue);
+        }
+      },
+      enumerable: true,
+      configurable: true,
+    };
+    
+    Object.defineProperty(target, propertyKey, descriptor);
+  };
+}
+
+export function query(selector: string) {
+  return function (target: any, propertyKey: string) {
+    Object.defineProperty(target, propertyKey, {
+      get() {
+        // For elements with shadow DOM, query within shadow root
+        // For controllers, check the element's shadow root first
+        const root = this.element || this;
+        if (root.shadowRoot) {
+          return root.shadowRoot.querySelector(selector);
+        }
+        return root.querySelector(selector);
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  };
+}
+
+export function queryAll(selector: string) {
+  return function (target: any, propertyKey: string) {
+    Object.defineProperty(target, propertyKey, {
+      get() {
+        // For elements with shadow DOM, query within shadow root
+        // For controllers, check the element's shadow root first
+        const root = this.element || this;
+        if (root.shadowRoot) {
+          return root.shadowRoot.querySelectorAll(selector);
+        }
+        return root.querySelectorAll(selector);
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  };
+}
+
+export interface PropertyOptions {
+  type?: StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor;
+  reflect?: boolean;
+  attribute?: string | boolean;
+  converter?: PropertyConverter;
+  hasChanged?: (value: any, oldValue: any) => boolean;
+}
+
+export interface PropertyConverter {
+  fromAttribute?(value: string | null, type?: any): any;
+  toAttribute?(value: any, type?: any): string | null;
+}

package/src/events.ts

@@ -0,0 +1,146 @@
+import { ON_HANDLERS, CLEANUP } from './symbols';
+
+export function on(eventName: string, selector?: string) {
+  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    // Store event handler metadata
+    if (!target[ON_HANDLERS]) {
+      target[ON_HANDLERS] = [];
+    }
+    
+    target[ON_HANDLERS].push({
+      eventName,
+      selector,
+      methodName: propertyKey,
+      method: descriptor.value
+    });
+    
+    return descriptor;
+  };
+}
+
+// Helper to setup event handlers for elements
+export function setupEventHandlers(instance: any, element: HTMLElement) {
+  const handlers = instance.constructor.prototype[ON_HANDLERS];
+  if (!handlers) return;
+  
+  // Initialize cleanup object if needed
+  if (!instance[CLEANUP]) {
+    instance[CLEANUP] = { events: [], channels: [] };
+  }
+  
+  for (const handler of handlers) {
+    const originalMethod = handler.method.bind(instance);
+    
+    // Wrap boundMethod in try-catch for error isolation
+    const boundMethod = (event: Event) => {
+      try {
+        return originalMethod(event);
+      } catch (error) {
+        console.error(`Error in event handler ${handler.methodName}:`, error);
+        // Don't rethrow - allow other handlers to continue
+      }
+    };
+    
+    if (handler.selector) {
+      // Delegated event handling - use shadow root if available
+      const eventRoot = element.shadowRoot || element;
+      const delegatedHandler = (event: Event) => {
+        const target = event.target as HTMLElement;
+        if (target.matches && target.matches(handler.selector)) {
+          boundMethod(event);
+        } else if (target.closest) {
+          const closest = target.closest(handler.selector);
+          if (closest) {
+            boundMethod(event);
+          }
+        }
+      };
+      
+      eventRoot.addEventListener(handler.eventName, delegatedHandler);
+      instance[CLEANUP].events.push(() => {
+        eventRoot.removeEventListener(handler.eventName, delegatedHandler);
+      });
+    } else {
+      // Direct event handling - always on the element itself
+      element.addEventListener(handler.eventName, boundMethod);
+      instance[CLEANUP].events.push(() => {
+        element.removeEventListener(handler.eventName, boundMethod);
+      });
+    }
+  }
+}
+
+// Helper to cleanup event handlers
+export function cleanupEventHandlers(instance: any) {
+  if (instance[CLEANUP]?.events) {
+    for (const cleanup of instance[CLEANUP].events) {
+      cleanup();
+    }
+    instance[CLEANUP].events = [];
+  }
+}
+
+export interface DispatchOptions extends EventInit {
+  /**
+   * Whether to dispatch even if the method returns undefined (default: true)
+   */
+  dispatchOnUndefined?: boolean;
+}
+
+/**
+ * Decorator that automatically dispatches a custom event after a method is called.
+ * The return value of the method becomes the event detail.
+ * 
+ * @param eventName The name of the event to dispatch
+ * @param options Optional configuration extending EventInit
+ */
+export function dispatch(eventName: string, options?: DispatchOptions) {
+  return function (_target: any, _propertyKey: string, descriptor: PropertyDescriptor) {
+    const originalMethod = descriptor.value;
+    
+    descriptor.value = function (this: HTMLElement, ...args: any[]) {
+      // Call the original method
+      const result = originalMethod.apply(this, args);
+      
+      // Handle async methods
+      if (result instanceof Promise) {
+        return result.then((resolvedResult: any) => {
+          // Skip dispatch if result is undefined and dispatchOnUndefined is false
+          if (resolvedResult === undefined && options?.dispatchOnUndefined === false) {
+            return resolvedResult;
+          }
+          
+          // Create event with spread operator for options
+          const event = new CustomEvent(eventName, {
+            bubbles: true,  // Default to true for component events
+            composed: true, // Allow crossing shadow DOM boundaries
+            ...options,     // Spread all EventInit options
+            detail: resolvedResult
+          });
+          
+          this.dispatchEvent(event);
+          return resolvedResult;
+        });
+      }
+      
+      // Skip dispatch if result is undefined and dispatchOnUndefined is false
+      if (result === undefined && options?.dispatchOnUndefined === false) {
+        return result;
+      }
+      
+      // Create event with spread operator for options
+      const event = new CustomEvent(eventName, {
+        bubbles: true,  // Default to true for component events
+        composed: true, // Allow crossing shadow DOM boundaries
+        ...options,     // Spread all EventInit options
+        detail: result
+      });
+      
+      this.dispatchEvent(event);
+      
+      return result;
+    };
+    
+    return descriptor;
+  };
+}

package/src/global.ts

@@ -0,0 +1,31 @@
+// Global namespace for Snice framework
+// Ensures all registries and symbols are shared across different JS files/modules
+
+export interface SniceGlobal {
+  controllerRegistry: Map<string, any>;
+  controllerIdCounter: number;
+  symbols: Map<string, symbol>;
+}
+
+// Initialize or get the global Snice namespace
+function initGlobalNamespace(): SniceGlobal {
+  if (!(globalThis as any).snice) {
+    (globalThis as any).snice = {
+      controllerRegistry: new Map(),
+      controllerIdCounter: 0,
+      symbols: new Map()
+    };
+  }
+  return (globalThis as any).snice;
+}
+
+// Export the global namespace
+export const snice = initGlobalNamespace();
+
+// Helper function to get or create a global symbol
+export function getSymbol(name: string): symbol {
+  if (!snice.symbols.has(name)) {
+    snice.symbols.set(name, Symbol(name));
+  }
+  return snice.symbols.get(name)!;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { element, customElement, property, query, queryAll } from './element';
+export { Router } from './router';
+export { controller, attachController, detachController, getController, useNativeElementControllers, cleanupNativeElementControllers } from './controller';
+export { on, dispatch } from './events';
+export { channel } from './channel';
+export type { PropertyOptions, PropertyConverter } from './element';
+export type { RouterOptions, PageOptions, PageTransition } from './router';
+export type { IController, ControllerClass } from './controller';
+export type { DispatchOptions } from './events';
+export type { ChannelOptions } from './channel';