snice 1.0.0 → 1.2.0

package/README.md

@@ -23,7 +23,7 @@ Snice provides a clear separation of concerns through decorators:
 - **`@page`** - Sets up routing and navigation between different views
 
 ### Property & Query Decorators
-- **`@property`** - Declares reactive properties that can reflect to attributes
+- **`@property`** - Declares properties that can reflect to attributes
 - **`@query`** - Queries a single element from shadow DOM
 - **`@queryAll`** - Queries multiple elements from shadow DOM
 
@@ -219,7 +219,7 @@ class MyClicker extends HTMLElement {
 Automatically dispatch custom events with `@dispatch`:
 
 ```typescript
-import { element, dispatch, on } from 'snice';
+import { element, dispatch, on, query } from 'snice';
 
 @element('toggle-switch')
 class ToggleSwitch extends HTMLElement {
@@ -315,11 +315,22 @@ class AboutPage extends HTMLElement {
   }
 }
 
+// Page with URL parameter
+@page({ tag: 'user-page', routes: ['/users/:id'] })
+class UserPage extends HTMLElement {
+  id = '';  // Automatically set from URL
+  
+  html() {
+    return `<h1>User ${this.id}</h1>`;
+  }
+}
+
 // Start the router
 initialize();
 
 // Navigate programmatically
 navigate('/about');
+navigate('/users/123');  // Sets id="123" on UserPage
 ```
 
 ## Controllers (Data Fetching)
@@ -339,7 +350,7 @@ class UserController {
     (element as any).setUsers(users);
   }
 
-  async detach() {
+  async detach(element: HTMLElement) {
     // Cleanup
   }
 }
@@ -358,7 +369,9 @@ class UserList extends HTMLElement {
 
   setUsers(users: any[]) {
     this.users = users;
-    this.innerHTML = this.html();
+    if (this.shadowRoot) {
+      this.shadowRoot.innerHTML = this.html();
+    }
   }
 }
 ```
@@ -393,6 +406,11 @@ class UserCard extends HTMLElement {
 // --- controllers/user-controller.ts
 @controller('user-controller')
 class UserController {
+  element: HTMLElement | null = null;
+  
+  async attach(element: HTMLElement) {}
+  async detach(element: HTMLElement) {}
+  
   @channel('get-data')
   handleGetData(request) {
     console.log(request);  // { id: 123 }
@@ -491,7 +509,6 @@ class WeatherController {
   element: HTMLElement | null = null;
   
   async attach(element: HTMLElement) {
-    this.element = element;
     
     // Simulate fetching weather data
     await new Promise(resolve => setTimeout(resolve, 1000));
@@ -512,6 +529,10 @@ class WeatherController {
     `);
     (element as any).setFooter('Updated just now');
   }
+  
+  async detach(element: HTMLElement) {
+    // Cleanup if needed
+  }
 }
 ```
 
@@ -557,9 +578,16 @@ Use the same card with different controllers:
 
 ```typescript
 interface PropertyOptions {
-  type?: typeof String | typeof Number | typeof Boolean;  // Type converter
-  reflect?: boolean;     // Reflect property to attribute
-  attribute?: string;    // Custom attribute name
+  type?: typeof String | typeof Number | typeof Boolean | typeof Array | typeof Object;  // Type converter
+  reflect?: boolean;        // Reflect property to attribute
+  attribute?: string | boolean;  // Custom attribute name or false to disable
+  converter?: PropertyConverter;  // Custom converter
+  hasChanged?: (value: any, oldValue: any) => boolean;  // Custom change detector
+}
+
+interface PropertyConverter {
+  fromAttribute?(value: string | null, type?: any): any;
+  toAttribute?(value: any, type?: any): string | null;
 }
 ```
 
@@ -571,6 +599,15 @@ interface DispatchOptions extends EventInit {
 }
 ```
 
+## Documentation
+
+- [Elements API](./docs/elements.md) - Complete guide to creating elements with properties, queries, and styling
+- [Controllers API](./docs/controllers.md) - Data fetching, business logic, and controller patterns
+- [Events API](./docs/events.md) - Event handling, dispatching, and custom events
+- [Channels API](./docs/channels.md) - Bidirectional communication between elements and controllers
+- [Routing API](./docs/routing.md) - Single-page application routing with transitions
+- [Migration Guide](./docs/migration-guide.md) - Migrating from React, Vue, Angular, and other frameworks
+
 ## License
 
 MIT

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "snice",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "A TypeScript library",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
   "files": [
-    "dist"
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts"
   ],
   "publishConfig": {
     "access": "public"

package/src/channel.ts

@@ -0,0 +1,181 @@
+import { CHANNEL_HANDLERS, CLEANUP } from './symbols';
+
+export interface ChannelOptions extends EventInit {
+  /**
+   * Timeout for waiting for responses (in ms)
+   */
+  timeout?: number;
+}
+
+/**
+ * Decorator for bidirectional communication channels.
+ * On elements: Opens a channel using async generator
+ * On controllers: Responds to channel requests
+ * 
+ * @param channelName The name of the channel
+ * @param options Optional configuration
+ */
+export function channel(channelName: string, options?: ChannelOptions) {
+  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    const originalMethod = descriptor.value;
+    
+    // We'll determine at runtime whether this is element or controller
+    // by checking if 'this' is an HTMLElement
+    descriptor.value = async function (this: any, ...args: any[]) {
+      // Runtime check: if 'this' is an HTMLElement, it's element-side
+      if (this instanceof HTMLElement) {
+        // Element side - handle async generator
+        const timeout = options?.timeout ?? 100; // Default 100ms timeout
+        
+        // Create the generator
+        const generator = originalMethod.apply(this, args);
+        
+        // Get the first yield (the request payload)
+        const { value: payload, done } = await generator.next();
+        
+        if (done) {
+          // Generator returned without yielding
+          return payload;
+        }
+        
+        // Create data promise and expose resolve/reject
+        let dataResolve: (value: any) => void;
+        let dataReject: (reason?: any) => void;
+        const dataPromise = new Promise((resolve, reject) => {
+          dataResolve = resolve;
+          dataReject = reject;
+        });
+        
+        // Create timeout promise and expose resolve/reject
+        let timeoutResolve: () => void;
+        let timeoutReject: (reason?: any) => void;
+        let timeoutId: NodeJS.Timeout;
+        const timeoutPromise = new Promise<void>((resolve, reject) => {
+          timeoutResolve = resolve;
+          timeoutReject = reject;
+          timeoutId = setTimeout(() => {
+            reject(new Error(`Channel timeout after ${timeout}ms`));
+          }, timeout);
+        });
+        
+        // Dispatch event with promises
+        const eventName = `@channel:${channelName}`;
+        const event = new CustomEvent(eventName, {
+          bubbles: options?.bubbles !== undefined ? options.bubbles : true,
+          cancelable: options?.cancelable || false,
+          composed: true, // Allow crossing shadow DOM boundaries
+          detail: {
+            payload,
+            timeout: {
+              resolve: () => {
+                clearTimeout(timeoutId);
+                timeoutResolve();
+              },
+              reject: timeoutReject!
+            },
+            data: {
+              resolve: dataResolve!,
+              reject: dataReject!
+            }
+          }
+        });
+        
+        this.dispatchEvent(event);
+        
+        try {
+          // Wait for timeout to be resolved or rejected
+          await timeoutPromise;
+          // If we get here, controller responded in time
+          const response = await dataPromise;
+          
+          // Send response back to generator and get final return value
+          const { value: finalValue } = await generator.next(response);
+          return finalValue;
+        } catch (error) {
+          // Send error to generator
+          try {
+            await generator.throw(error);
+          } catch (generatorError) {
+            throw generatorError;
+          }
+        }
+      } else {
+        // Controller side - just call the original method
+        // The actual channel setup happens in setupChannelHandlers
+        return originalMethod.apply(this, args);
+      }
+    };
+    
+    // Store channel metadata on the prototype for controllers
+    // This will be picked up by setupChannelHandlers
+    if (!target[CHANNEL_HANDLERS]) {
+      target[CHANNEL_HANDLERS] = [];
+    }
+    
+    target[CHANNEL_HANDLERS].push({
+      channelName,
+      methodName: propertyKey,
+      method: originalMethod
+    });
+    
+    return descriptor;
+  };
+}
+
+// Helper to setup channel handlers for controllers
+export function setupChannelHandlers(instance: any, element: HTMLElement) {
+  const handlers = instance.constructor.prototype[CHANNEL_HANDLERS];
+  if (!handlers) return;
+  
+  // Store cleanup functions
+  // Initialize cleanup object if needed
+  if (!instance[CLEANUP]) {
+    instance[CLEANUP] = { events: [], channels: [] };
+  }
+  
+  for (const handler of handlers) {
+    const boundMethod = handler.method.bind(instance);
+    const eventName = `@channel:${handler.channelName}`;
+    
+    // Setup channel handler
+    const channelHandler = (event: CustomEvent) => {
+      // Extract promises and payload
+      const { data, timeout, payload } = event.detail;
+      
+      // Prevent other controllers from responding
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      event.stopPropagation();
+      
+      // Call the controller method and handle the result
+      Promise.resolve(boundMethod(payload))
+        .then(result => {
+          // Clear the timeout and resolve the data promise
+          timeout.resolve();
+          data.resolve(result);
+        })
+        .catch(error => {
+          // Clear timeout and reject the data promise on error
+          timeout.resolve();
+          data.reject(error);
+          console.error(`Error in channel handler ${handler.methodName}:`, error);
+        });
+    };
+    
+    element.addEventListener(eventName, channelHandler as EventListener);
+    
+    instance[CLEANUP].channels.push(() => {
+      element.removeEventListener(eventName, channelHandler as EventListener);
+    });
+  }
+}
+
+// Helper to cleanup channel handlers
+export function cleanupChannelHandlers(instance: any) {
+  if (instance[CLEANUP]?.channels) {
+    for (const cleanup of instance[CLEANUP].channels) {
+      cleanup();
+    }
+    instance[CLEANUP].channels = [];
+  }
+}

package/src/controller.ts

@@ -0,0 +1,329 @@
+import { setupEventHandlers, cleanupEventHandlers } from './events';
+import { setupChannelHandlers, cleanupChannelHandlers } from './channel';
+import { IS_CONTROLLER_CLASS, CONTROLLER_KEY, CONTROLLER_NAME_KEY, CONTROLLER_ID, CONTROLLER_OPERATIONS, NATIVE_CONTROLLER, IS_ELEMENT_CLASS } from './symbols';
+import { snice } from './global';
+
+type Maybe<T> = T | null | undefined;
+
+export interface IController<T extends HTMLElement = HTMLElement> {
+  element: Maybe<T>;
+  attach(element: T): void | Promise<void>;
+  detach(element: T): void | Promise<void>;
+}
+
+export type ControllerClass<T extends HTMLElement = HTMLElement> = new() => IController<T>;
+
+// Controller-scoped cleanup registry
+class ControllerScope {
+  private cleanupFns: Map<string, Function> = new Map();
+  private pendingOperations: Set<Promise<void>> = new Set();
+  
+  register(key: string, cleanup: Function): void {
+    this.cleanupFns.set(key, cleanup);
+  }
+  
+  unregister(key: string): void {
+    this.cleanupFns.delete(key);
+  }
+  
+  async cleanup(): Promise<void> {
+    // Wait for all pending operations
+    await Promise.all(this.pendingOperations);
+    
+    // Run all cleanup functions
+    for (const cleanup of this.cleanupFns.values()) {
+      try {
+        await cleanup();
+      } catch (error) {
+        console.error('Error during cleanup:', error);
+      }
+    }
+    this.cleanupFns.clear();
+  }
+  
+  async runOperation<T>(operation: () => Promise<T>): Promise<T> {
+    const promise = operation();
+    const voidPromise = promise.then(() => {}, () => {});
+    this.pendingOperations.add(voidPromise);
+    
+    try {
+      const result = await promise;
+      this.pendingOperations.delete(voidPromise);
+      return result;
+    } catch (error) {
+      this.pendingOperations.delete(voidPromise);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Decorator to register a controller class with a name
+ * @param name The name to register the controller under
+ */
+export function controller(name: string) {
+  return function <T extends ControllerClass>(constructor: T) {
+    snice.controllerRegistry.set(name, constructor);
+    // Mark as controller class for channel decorator detection
+    (constructor.prototype as any)[IS_CONTROLLER_CLASS] = true;
+    return constructor;
+  };
+}
+
+/**
+ * Attaches a controller to an element
+ * @param element The element to attach the controller to
+ * @param controllerName The name of the controller to attach
+ */
+export async function attachController(element: HTMLElement, controllerName: string): Promise<void> {
+  const existingController = (element as any)[CONTROLLER_KEY] as IController | undefined;
+  const existingName = (element as any)[CONTROLLER_NAME_KEY] as string | undefined;
+  
+  // For native elements, check if this is actually the desired controller
+  const nativeController = (element as any)[NATIVE_CONTROLLER];
+  if (nativeController !== undefined && nativeController !== controllerName) {
+    // This attachment is outdated, skip it
+    return;
+  }
+  
+  if (existingName === controllerName && existingController) {
+    // Already attached and controller exists
+    return;
+  }
+  
+  // If there's an existing controller, detach it first
+  if (existingController) {
+    await detachController(element);
+  }
+  
+  const ControllerClass = snice.controllerRegistry.get(controllerName);
+  if (!ControllerClass) {
+    throw new Error(`Controller "${controllerName}" not found in registry`);
+  }
+  
+  // Create controller instance with unique ID and scope
+  const controllerInstance = new ControllerClass();
+  snice.controllerIdCounter += 1;
+  const controllerId = snice.controllerIdCounter;
+  const scope = new ControllerScope();
+  
+  (controllerInstance as any)[CONTROLLER_ID] = controllerId;
+  controllerInstance.element = element;
+  
+  // Store references
+  (element as any)[CONTROLLER_KEY] = controllerInstance;
+  (element as any)[CONTROLLER_NAME_KEY] = controllerName;
+  (element as any)[CONTROLLER_OPERATIONS] = scope;
+  
+  // Wait for element to be ready (required)
+  await (element as any).ready;
+  
+  // Run attach in the controller's scope
+  await scope.runOperation(async () => {
+    await controllerInstance.attach(element);
+  });
+  
+  // Setup @on event handlers for controller
+  setupEventHandlers(controllerInstance, element);
+  
+  // Setup @channel handlers for controller
+  setupChannelHandlers(controllerInstance, element);
+  
+  element.dispatchEvent(new CustomEvent('controller.attached', {
+    detail: { name: controllerName, controller: controllerInstance }
+  }));
+}
+
+/**
+ * Detaches a controller from an element
+ * @param element The element to detach the controller from
+ */
+export async function detachController(element: HTMLElement): Promise<void> {
+  const controllerInstance = (element as any)[CONTROLLER_KEY] as IController | undefined;
+  const controllerName = (element as any)[CONTROLLER_NAME_KEY] as string | undefined;
+  const scope = (element as any)[CONTROLLER_OPERATIONS] as ControllerScope | undefined;
+  
+  if (!controllerInstance) {
+    return;
+  }
+  
+  // Run detach in the controller's scope
+  if (scope) {
+    await scope.runOperation(async () => {
+      await controllerInstance.detach(element);
+    });
+  } else {
+    await controllerInstance.detach(element);
+  }
+  
+  controllerInstance.element = null;
+  
+  // Cleanup @on event handlers for controller
+  cleanupEventHandlers(controllerInstance);
+  
+  // Cleanup @channel handlers for controller
+  cleanupChannelHandlers(controllerInstance);
+  
+  // Cleanup the controller scope
+  if (scope) {
+    await scope.cleanup();
+  }
+  
+  delete (element as any)[CONTROLLER_KEY];
+  delete (element as any)[CONTROLLER_NAME_KEY];
+  delete (element as any)[CONTROLLER_OPERATIONS];
+  
+  element.dispatchEvent(new CustomEvent('controller.detached', {
+    detail: { name: controllerName, controller: controllerInstance }
+  }));
+}
+
+/**
+ * Gets the controller instance attached to an element
+ * @param element The element to get the controller from
+ * @returns The controller instance or undefined
+ */
+export function getController<T extends IController = IController>(element: HTMLElement): T | undefined {
+  return (element as any)[CONTROLLER_KEY] as T | undefined;
+}
+
+/**
+ * Gets the controller scope for an element
+ * @param element The element to get the scope from
+ * @returns The controller scope or undefined
+ */
+export function getControllerScope(element: HTMLElement): ControllerScope | undefined {
+  return (element as any)[CONTROLLER_OPERATIONS] as ControllerScope | undefined;
+}
+
+/**
+ * Enable controller support for native HTML elements
+ * This sets up a MutationObserver to watch for controller attributes
+ * on non-custom elements (elements without hyphens in their tag names)
+ */
+export function useNativeElementControllers() {
+  // Return if already initialized
+  if ((globalThis as any).sniceNativeControllersInitialized) {
+    return;
+  }
+  (globalThis as any).sniceNativeControllersInitialized = true;
+
+  // Process elements that already have controller attribute
+  function processElement(element: Element) {
+    if (!(element instanceof HTMLElement)) return;
+    
+    // Skip custom elements (they handle controllers themselves)
+    if (element.tagName.includes('-')) return;
+    
+    // Skip elements that are @element decorated (they have their own controller handling)
+    if ((element as any)[IS_ELEMENT_CLASS]) return;
+    
+    const controllerName = element.getAttribute('controller');
+    const currentControllerName = (element as any)[NATIVE_CONTROLLER];
+    
+    if (controllerName && controllerName !== currentControllerName) {
+      // Controller added or changed
+      (element as any)[NATIVE_CONTROLLER] = controllerName;
+      
+      // For non-custom elements, we need to add the ready promise
+      if (!(element as any).ready) {
+        (element as any).ready = Promise.resolve();
+      }
+      
+      // Detach old controller if exists (don't await - let it run async)
+      if (currentControllerName) {
+        detachController(element as HTMLElement).catch(error => {
+          console.error(`Failed to detach old controller from native element:`, error);
+        });
+      }
+      
+      // Attach the new controller
+      attachController(element as HTMLElement, controllerName).catch(error => {
+        console.error(`Failed to attach controller "${controllerName}" to native element:`, error);
+      });
+    } else if (!controllerName && currentControllerName) {
+      // Controller was removed
+      delete (element as any)[NATIVE_CONTROLLER];
+      // Clear the controller name immediately to allow re-attachment
+      delete (element as any)[CONTROLLER_NAME_KEY];
+      detachController(element as HTMLElement).catch(error => {
+        console.error(`Failed to detach controller from native element:`, error);
+      });
+    }
+  }
+
+  // Set up MutationObserver to watch for controller attributes
+  const observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      if (mutation.type === 'attributes' && mutation.attributeName === 'controller') {
+        processElement(mutation.target as Element);
+      } else if (mutation.type === 'childList') {
+        // Process added nodes
+        mutation.addedNodes.forEach(node => {
+          if (node instanceof HTMLElement) {
+            // Process the node itself
+            processElement(node);
+            // Process all descendants with controller attribute
+            node.querySelectorAll('[controller]:not([class*="-"])').forEach(processElement);
+          }
+        });
+      }
+    }
+  });
+
+  // Start observing when DOM is ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => {
+      // Process existing elements (excluding custom elements)
+      document.querySelectorAll('[controller]:not([class*="-"])').forEach(processElement);
+      
+      // Start observing
+      observer.observe(document.body, {
+        attributes: true,
+        attributeFilter: ['controller'],
+        childList: true,
+        subtree: true
+      });
+    });
+  } else {
+    // DOM already loaded
+    document.querySelectorAll('[controller]:not([class*="-"])').forEach(processElement);
+    
+    observer.observe(document.body, {
+      attributes: true,
+      attributeFilter: ['controller'],
+      childList: true,
+      subtree: true
+    });
+  }
+
+  // Store observer reference for cleanup if needed
+  (globalThis as any).sniceNativeControllerObserver = observer;
+}
+
+/**
+ * Stop watching for native element controllers
+ */
+export function cleanupNativeElementControllers() {
+  const observer = (globalThis as any).sniceNativeControllerObserver;
+  if (observer) {
+    observer.disconnect();
+    delete (globalThis as any).sniceNativeControllerObserver;
+    delete (globalThis as any).sniceNativeControllersInitialized;
+  }
+}
+
+/**
+ * Registers a cleanup function for the current controller
+ * @param controller The controller instance
+ * @param key A unique key for this cleanup function
+ * @param cleanup The cleanup function to register
+ */
+export function registerControllerCleanup(controller: IController, key: string, cleanup: Function): void {
+  if (!controller.element) return;
+  
+  const scope = getControllerScope(controller.element as HTMLElement);
+  if (scope) {
+    scope.register(key, cleanup);
+  }
+}