snice 2.3.0 → 2.5.0

package/dist/index.iife.js

@@ -1,5 +1,5 @@
 /*!
- * snice v2.2.3
+ * snice v2.4.0
  * Imperative TypeScript framework for building vanilla web components with decorators, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.
@@ -40,6 +40,7 @@ var Snice = (function (exports) {
     const READY_PROMISE = getSymbol('ready-promise');
     const READY_RESOLVE = getSymbol('ready-resolve');
     const CONTROLLER = getSymbol('controller');
+    const INITIALIZED = getSymbol('initialized');
     // Event handler symbols
     const ON_HANDLERS = getSymbol('on-handlers');
     // Controller symbols
@@ -65,11 +66,16 @@ var Snice = (function (exports) {
     // Lifecycle symbols
     const READY_HANDLERS = getSymbol('ready-handlers');
     const DISPOSE_HANDLERS = getSymbol('dispose-handlers');
+    const MOVED_HANDLERS = getSymbol('moved-handlers');
+    const ADOPTED_HANDLERS = getSymbol('adopted-handlers');
     // Observer symbols
     const OBSERVERS = getSymbol('observers');
     // Part symbols
     const PARTS = getSymbol('parts');
     const PART_TIMERS = getSymbol('part-timers');
+    // Lifecycle callback timers
+    const MOVED_TIMERS = getSymbol('moved-timers');
+    const ADOPTED_TIMERS = getSymbol('adopted-timers');
     // Dispatch timing symbols
     const DISPATCH_TIMERS = getSymbol('dispatch-timers');
 
@@ -1124,14 +1130,6 @@ var Snice = (function (exports) {
             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
-     */
-    function getController(element) {
-        return element[CONTROLLER_KEY];
-    }
     /**
      * Enable controller support for native HTML elements
      * This sets up a MutationObserver to watch for controller attributes
@@ -1229,17 +1227,6 @@ var Snice = (function (exports) {
         // Store observer reference for cleanup if needed
         globalThis.sniceNativeControllerObserver = observer;
     }
-    /**
-     * Stop watching for native element controllers
-     */
-    function cleanupNativeElementControllers() {
-        const observer = globalThis.sniceNativeControllerObserver;
-        if (observer) {
-            observer.disconnect();
-            delete globalThis.sniceNativeControllerObserver;
-            delete globalThis.sniceNativeControllersInitialized;
-        }
-    }
 
     /**
      * SimpleArray type for arrays that can be safely reflected to attributes
@@ -1503,6 +1490,24 @@ var Snice = (function (exports) {
                     this[READY_RESOLVE] = resolve;
                 });
             }
+            // Only run initialization logic once, but re-establish handlers on reconnection
+            if (this[INITIALIZED]) {
+                // Re-establish handlers that get cleaned up on disconnect
+                setupEventHandlers(this, this);
+                setupResponseHandlers(this, this);
+                // Re-establish observers that get cleaned up on disconnect
+                try {
+                    setupObservers(this, this);
+                }
+                catch (error) {
+                    console.error(`Error setting up observers for ${this.tagName} on reconnection:`, error);
+                }
+                // Call user's connectedCallback
+                if (originalConnectedCallback) {
+                    originalConnectedCallback.call(this);
+                }
+                return;
+            }
             try {
                 // Initialize properties from attributes before rendering
                 const properties = constructor[PROPERTIES];
@@ -1526,8 +1531,6 @@ var Snice = (function (exports) {
                 this[PROPERTIES_INITIALIZED] = true;
                 // Properties are now stateless and read from DOM attributes only
                 // Initial values are not automatically reflected
-                // 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' });
@@ -1600,6 +1603,8 @@ var Snice = (function (exports) {
                 catch (error) {
                     console.error(`Error setting up observers for ${this.tagName}:`, error);
                 }
+                // Mark as initialized
+                this[INITIALIZED] = true;
                 // NOW call the original user-defined connectedCallback after shadow DOM is set up
                 if (originalConnectedCallback) {
                     originalConnectedCallback.call(this);
@@ -1721,6 +1726,36 @@ var Snice = (function (exports) {
                 }
             }
         };
+        // Add connectedMoveCallback for handling DOM moves
+        constructor.prototype.connectedMoveCallback = async function () {
+            // Call @moved handlers
+            const movedHandlers = constructor[MOVED_HANDLERS];
+            if (movedHandlers) {
+                for (const handler of movedHandlers) {
+                    try {
+                        await handler.method.call(this);
+                    }
+                    catch (error) {
+                        console.error(`Error in @moved handler ${handler.methodName}:`, error);
+                    }
+                }
+            }
+        };
+        // Add adoptedCallback for handling document adoption
+        constructor.prototype.adoptedCallback = async function () {
+            // Call @adopted handlers
+            const adoptedHandlers = constructor[ADOPTED_HANDLERS];
+            if (adoptedHandlers) {
+                for (const handler of adoptedHandlers) {
+                    try {
+                        await handler.method.call(this);
+                    }
+                    catch (error) {
+                        console.error(`Error in @adopted handler ${handler.methodName}:`, error);
+                    }
+                }
+            }
+        };
     }
     function element(tagName) {
         return function (constructor, context) {
@@ -2063,6 +2098,148 @@ var Snice = (function (exports) {
             });
         };
     }
+    /**
+     * Decorator for methods that should run when element is moved within DOM
+     * Supports debounce and throttle options to control execution timing
+     */
+    function moved(options = {}) {
+        return function (originalMethod, context) {
+            const methodName = context.name;
+            context.addInitializer(function () {
+                const constructor = this.constructor;
+                if (!constructor[MOVED_HANDLERS]) {
+                    constructor[MOVED_HANDLERS] = [];
+                }
+                constructor[MOVED_HANDLERS].push({
+                    methodName,
+                    method: originalMethod,
+                    options
+                });
+            });
+            // Return wrapped method that handles timing options
+            return function (...args) {
+                // Initialize timers storage if not present
+                if (!this[MOVED_TIMERS]) {
+                    this[MOVED_TIMERS] = new Map();
+                }
+                // Get or create timers for this specific method
+                if (!this[MOVED_TIMERS].has(methodName)) {
+                    this[MOVED_TIMERS].set(methodName, {
+                        throttleTimer: null,
+                        debounceTimer: null,
+                        lastThrottleCall: 0
+                    });
+                }
+                const timers = this[MOVED_TIMERS].get(methodName);
+                // Helper function to execute method
+                const executeMethod = (...methodArgs) => {
+                    return originalMethod.apply(this, methodArgs);
+                };
+                const hasDebounce = options.debounce !== undefined && options.debounce > 0;
+                const hasThrottle = options.throttle !== undefined && options.throttle > 0;
+                // Handle timing based on priority: debounce > throttle > immediate
+                switch (true) {
+                    case hasDebounce: {
+                        clearTimeout(timers.debounceTimer);
+                        timers.debounceTimer = setTimeout(() => executeMethod(...args), options.debounce);
+                        return undefined;
+                    }
+                    case hasThrottle: {
+                        const throttleMs = options.throttle;
+                        const now = Date.now();
+                        const canExecuteImmediately = timers.lastThrottleCall === 0 || now - timers.lastThrottleCall >= throttleMs;
+                        if (canExecuteImmediately) {
+                            timers.lastThrottleCall = now;
+                            return executeMethod(...args);
+                        }
+                        const hasScheduledTimer = !!timers.throttleTimer;
+                        if (!hasScheduledTimer) {
+                            const remainingTime = throttleMs - (now - timers.lastThrottleCall);
+                            timers.throttleTimer = setTimeout(() => {
+                                timers.throttleTimer = null;
+                                timers.lastThrottleCall = Date.now();
+                                executeMethod(...args);
+                            }, remainingTime);
+                        }
+                        return undefined;
+                    }
+                    default:
+                        return executeMethod(...args);
+                }
+            };
+        };
+    }
+    /**
+     * Decorator for methods that should run when element is adopted to new document
+     * Supports debounce and throttle options to control execution timing
+     */
+    function adopted(options = {}) {
+        return function (originalMethod, context) {
+            const methodName = context.name;
+            context.addInitializer(function () {
+                const constructor = this.constructor;
+                if (!constructor[ADOPTED_HANDLERS]) {
+                    constructor[ADOPTED_HANDLERS] = [];
+                }
+                constructor[ADOPTED_HANDLERS].push({
+                    methodName,
+                    method: originalMethod,
+                    options
+                });
+            });
+            // Return wrapped method that handles timing options
+            return function (...args) {
+                // Initialize timers storage if not present
+                if (!this[ADOPTED_TIMERS]) {
+                    this[ADOPTED_TIMERS] = new Map();
+                }
+                // Get or create timers for this specific method
+                if (!this[ADOPTED_TIMERS].has(methodName)) {
+                    this[ADOPTED_TIMERS].set(methodName, {
+                        throttleTimer: null,
+                        debounceTimer: null,
+                        lastThrottleCall: 0
+                    });
+                }
+                const timers = this[ADOPTED_TIMERS].get(methodName);
+                // Helper function to execute method
+                const executeMethod = (...methodArgs) => {
+                    return originalMethod.apply(this, methodArgs);
+                };
+                const hasDebounce = options.debounce !== undefined && options.debounce > 0;
+                const hasThrottle = options.throttle !== undefined && options.throttle > 0;
+                // Handle timing based on priority: debounce > throttle > immediate
+                switch (true) {
+                    case hasDebounce: {
+                        clearTimeout(timers.debounceTimer);
+                        timers.debounceTimer = setTimeout(() => executeMethod(...args), options.debounce);
+                        return undefined;
+                    }
+                    case hasThrottle: {
+                        const throttleMs = options.throttle;
+                        const now = Date.now();
+                        const canExecuteImmediately = timers.lastThrottleCall === 0 || now - timers.lastThrottleCall >= throttleMs;
+                        if (canExecuteImmediately) {
+                            timers.lastThrottleCall = now;
+                            return executeMethod(...args);
+                        }
+                        const hasScheduledTimer = !!timers.throttleTimer;
+                        if (!hasScheduledTimer) {
+                            const remainingTime = throttleMs - (now - timers.lastThrottleCall);
+                            timers.throttleTimer = setTimeout(() => {
+                                timers.throttleTimer = null;
+                                timers.lastThrottleCall = Date.now();
+                                executeMethod(...args);
+                            }, remainingTime);
+                        }
+                        return undefined;
+                    }
+                    default:
+                        return executeMethod(...args);
+                }
+            };
+        };
+    }
     /**
      * Decorator for methods that render specific parts of the template
      * Parts are identified by the 'part' attribute in the HTML template
@@ -2888,6 +3065,7 @@ var Snice = (function (exports) {
     function Router(options) {
         const routes = [];
         let is_sorted = false;
+        let placards = []; // Store collected placards
         let _404; // the 404 page
         let _403; // the 403 forbidden page
         let home; // the home page
@@ -2916,7 +3094,7 @@ var Snice = (function (exports) {
         function page(pageOptions) {
             return function (constructor, context) {
                 // Transfer metadata from context to constructor (for new decorators)
-                if (context.metadata && context.metadata[PROPERTIES]) {
+                if (context?.metadata && context.metadata[PROPERTIES]) {
                     if (!constructor[PROPERTIES]) {
                         constructor[PROPERTIES] = new Map();
                     }
@@ -2961,8 +3139,8 @@ var Snice = (function (exports) {
                 };
                 // Define the custom element
                 customElements.define(pageOptions.tag, constructor);
-                // Register the routes with guards and layout
-                pageOptions.routes.forEach(route => register(route, pageOptions.tag, pageOptions.transition, pageOptions.guards, pageOptions.layout));
+                // Register the routes with guards, layout, and placard
+                pageOptions.routes.forEach(route => register(route, pageOptions.tag, pageOptions.transition, pageOptions.guards, pageOptions.layout, pageOptions.placard));
                 return constructor;
             };
         }
@@ -2973,8 +3151,8 @@ var Snice = (function (exports) {
          * @example
          * register('/custom-route', 'custom-element');
          */
-        function register(route, tag, transition, guards, layout) {
-            routes.push({ route: new Route(route), tag, transition, guards, layout });
+        function register(route, tag, transition, guards, layout, placard) {
+            routes.push({ route: new Route(route), tag, transition, guards, layout, placard });
             is_sorted = false;
             if (route === '/404') {
                 _404 = tag;
@@ -3025,10 +3203,28 @@ var Snice = (function (exports) {
                 routes.sort((a, b) => b.route.spec.length - a.route.spec.length);
                 is_sorted = true;
             }
+            // Collect placards from registered routes
+            collectPlacards();
             setupEventListeners();
             const path = getPath();
             navigate(path);
         }
+        function collectPlacards() {
+            placards = routes
+                .filter(route => route.placard)
+                .map(route => {
+                const placard = route.placard;
+                return typeof placard === 'function'
+                    ? placard(context)
+                    : placard;
+            });
+        }
+        function updateLayout(layoutElement, currentPath, routeParams) {
+            // Check if layout implements the update method
+            if (typeof layoutElement.update === 'function') {
+                layoutElement.update(context, placards, currentPath, routeParams);
+            }
+        }
         function getPath() {
             switch (options.type) {
                 case 'hash':
@@ -3037,7 +3233,7 @@ var Snice = (function (exports) {
                     return window.location.pathname;
             }
         }
-        async function renderForbiddenPage(target) {
+        function renderForbiddenPage(target) {
             let newPageElement;
             const has403Page = !!_403;
             if (has403Page) {
@@ -3055,16 +3251,16 @@ var Snice = (function (exports) {
             currentLayoutName = null;
             currentLayoutTimestamp = null;
         }
-        async function checkGuards(guards, params, target) {
+        function checkGuards(guards, params, target) {
             const hasGuards = !!guards;
             if (!hasGuards) {
                 return true;
             }
             const guardsArray = Array.isArray(guards) ? guards : [guards];
             for (const guard of guardsArray) {
-                const allowed = await guard(context, params);
+                const allowed = guard(context, params);
                 if (!allowed) {
-                    await renderForbiddenPage(target);
+                    renderForbiddenPage(target);
                     return false;
                 }
             }
@@ -3092,14 +3288,14 @@ var Snice = (function (exports) {
             div.innerHTML = /*html*/ `<h1>404</h1><p>Page not found</p>`;
             return { element: div, transition: undefined, layout: undefined };
         }
-        async function resolveRoute(path, target) {
+        function resolveRoute(path, target) {
             for (const route of routes) {
                 const params = route.route.match(path);
                 const isMatch = params !== false;
                 if (!isMatch) {
                     continue;
                 }
-                const guardsAllowed = await checkGuards(route.guards, params, target);
+                const guardsAllowed = checkGuards(route.guards, params, target);
                 if (!guardsAllowed) {
                     return { result: RouteResult.GUARDS_FAILED };
                 }
@@ -3107,7 +3303,7 @@ var Snice = (function (exports) {
                 newPageElement[ROUTER_CONTEXT] = context;
                 const routeParams = params;
                 Object.keys(routeParams).forEach(key => newPageElement.setAttribute(key, routeParams[key]));
-                return { result: RouteResult.SUCCESS, element: newPageElement, transition: route.transition, layout: route.layout };
+                return { result: RouteResult.SUCCESS, element: newPageElement, transition: route.transition, layout: route.layout, routeParams };
             }
             return { result: RouteResult.NOT_FOUND };
         }
@@ -3144,11 +3340,13 @@ var Snice = (function (exports) {
             currentLayoutTimestamp = null;
             return { element: null, needsNewLayout: true };
         }
-        async function renderWithLayout(target, pageElement, transition, layoutElement, needsNewLayout) {
+        async function renderWithLayout(target, pageElement, transition, layoutElement, needsNewLayout, currentPath, routeParams) {
             const currentLayout = layoutElement || getCurrentLayoutElement(target);
             if (!currentLayout) {
                 return;
             }
+            // Update layout with current context and placards
+            updateLayout(currentLayout, currentPath, routeParams);
             const oldPageInLayout = currentLayout.querySelector('[slot="page"]');
             const shouldTransition = !!(transition && oldPageInLayout);
             if (shouldTransition) {
@@ -3190,11 +3388,13 @@ var Snice = (function (exports) {
             if (!target) {
                 throw new Error(`Target element not found: ${options.target}`);
             }
+            // Collect fresh placards before navigation
+            collectPlacards();
             window.scrollTo(0, 0);
             const isHomePath = (path.trim() === '' || path === '/') && !!home;
             if (isHomePath) {
                 const homeRoute = routes.find(r => r.route.match('/'));
-                const guardsAllowed = await checkGuards(homeRoute?.guards, {}, target);
+                const guardsAllowed = checkGuards(homeRoute?.guards, {}, target);
                 if (!guardsAllowed) {
                     return;
                 }
@@ -3204,26 +3404,26 @@ var Snice = (function (exports) {
                 const finalTransition = transition || options.transition;
                 const hasLayout = layoutElement !== null || getCurrentLayoutElement(target) !== null;
                 if (hasLayout) {
-                    await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout);
+                    await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout, path, {});
                     return;
                 }
                 await renderDirect(target, element, finalTransition);
                 return;
             }
-            const routeResult = await resolveRoute(path, target);
+            const routeResult = resolveRoute(path, target);
             const isGuardsFailed = routeResult.result === RouteResult.GUARDS_FAILED;
             if (isGuardsFailed) {
                 return;
             }
             const isSuccess = routeResult.result === RouteResult.SUCCESS;
             if (isSuccess) {
-                const { element, transition, layout } = routeResult;
+                const { element, transition, layout, routeParams = {} } = routeResult;
                 const layoutToUse = determineLayout(layout);
                 const { element: layoutElement, needsNewLayout } = setupLayout(layoutToUse);
                 const finalTransition = transition || options.transition;
                 const hasLayout = layoutElement !== null || getCurrentLayoutElement(target) !== null;
                 if (hasLayout) {
-                    await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout);
+                    await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout, path, routeParams);
                     return;
                 }
                 await renderDirect(target, element, finalTransition);
@@ -3235,7 +3435,7 @@ var Snice = (function (exports) {
             const finalTransition = transition || options.transition;
             const hasLayout = layoutElement !== null || getCurrentLayoutElement(target) !== null;
             if (hasLayout) {
-                await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout);
+                await renderWithLayout(target, element, finalTransition, layoutElement, needsNewLayout, path, {});
                 return;
             }
             await renderDirect(target, element, finalTransition);
@@ -3254,18 +3454,16 @@ var Snice = (function (exports) {
     exports.IS_CONTROLLER_INSTANCE = IS_CONTROLLER_INSTANCE;
     exports.Router = Router;
     exports.SimpleArray = SimpleArray;
+    exports.adopted = adopted;
     exports.applyElementFunctionality = applyElementFunctionality;
-    exports.attachController = attachController;
-    exports.cleanupNativeElementControllers = cleanupNativeElementControllers;
     exports.context = context;
     exports.controller = controller;
-    exports.detachController = detachController;
     exports.dispatch = dispatch;
     exports.dispose = dispose;
     exports.element = element;
-    exports.getController = getController;
     exports.getSymbol = getSymbol;
     exports.layout = layout;
+    exports.moved = moved;
     exports.observe = observe;
     exports.on = on;
     exports.part = part;