snice 5.1.0 → 5.2.0

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v5.0.0
+ * snice v5.1.0
  * A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.
  * (c) 2024
  * Released under the MIT License.
@@ -2681,6 +2681,208 @@ function cleanupEventHandlers(instance) {
     instance[CLEANUP].events = [];
 }
 
+/**
+ * @context decorator for receiving router context updates
+ */
+const CONTEXT_HANDLERS = getSymbol('context-handlers');
+/**
+ * @context decorator for receiving router context updates
+ *
+ * Works on both methods and fields:
+ *
+ * - **Method form**: the method is invoked with the current Context on every
+ *   update (and once at register time so the first render sees the context).
+ * - **Field form**: the field is overwritten with the current Context on
+ *   every update (and once at register time). Pair with `@property` if you
+ *   want assignment to also schedule a re-render.
+ *
+ * @example
+ * ```typescript
+ * @element('my-layout')
+ * class MyLayout extends HTMLElement {
+ *   // Method form
+ *   @context()
+ *   handleContext(ctx: Context) {
+ *     this.renderNav(ctx.navigation.placards, ctx.navigation.route);
+ *   }
+ *
+ *   // Field form — the field is populated before first render
+ *   @context() ctx!: Context;
+ *
+ *   // Field + @property — assignment also triggers re-render
+ *   @property({ attribute: false }) @context() reactiveCtx!: Context;
+ * }
+ * ```
+ */
+function context$1(options = {}) {
+    return function (value, decoratorContext) {
+        const name = decoratorContext.name;
+        const kind = decoratorContext.kind;
+        const registerHandler = function () {
+            const constructor = this.constructor;
+            // De-dupe: methods identify by reference, fields identify by name.
+            if (!Object.prototype.hasOwnProperty.call(constructor, CONTEXT_METHODS)) {
+                constructor[CONTEXT_METHODS] = new Set();
+            }
+            const dedupeKey = kind === 'method' ? value : `field:${name}`;
+            if (constructor[CONTEXT_METHODS].has(dedupeKey))
+                return;
+            constructor[CONTEXT_METHODS].add(dedupeKey);
+            if (!Object.prototype.hasOwnProperty.call(constructor, CONTEXT_HANDLERS)) {
+                const inherited = constructor[CONTEXT_HANDLERS];
+                constructor[CONTEXT_HANDLERS] = inherited ? [...inherited] : [];
+            }
+            if (kind === 'method') {
+                constructor[CONTEXT_HANDLERS].push({
+                    kind: 'method',
+                    methodName: name,
+                    method: value,
+                    options,
+                });
+            }
+            else if (kind === 'field' || kind === 'accessor') {
+                constructor[CONTEXT_HANDLERS].push({
+                    kind: 'field',
+                    fieldName: name,
+                    options,
+                });
+            }
+        };
+        if (kind === 'method') {
+            decoratorContext.addInitializer(registerHandler);
+            return value;
+        }
+        // Field decorators: do registration via the init function (fires per
+        // instance during construction, with `this` bound). Returning the init
+        // function is the canonical Stage 3 way for field decorators —
+        // `addInitializer` for fields can be late or unreliable across runtimes.
+        return function (initialValue) {
+            registerHandler.call(this);
+            return initialValue;
+        };
+    };
+}
+/**
+ * Setup context handler for an element instance
+ * Called automatically during element connection
+ */
+// Accepts an HTMLElement OR a controller instance — both are plain objects
+// that may carry CONTEXT_HANDLER and a constructor with CONTEXT_HANDLERS.
+function setupContextHandler(element) {
+    const handlers = element.constructor[CONTEXT_HANDLERS];
+    if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
+        return;
+    }
+    // Get the Context instance from the router
+    const ctx = element[CONTEXT_HANDLER];
+    if (!ctx) {
+        return;
+    }
+    // Store the Context instance for cleanup
+    element[NAVIGATION_CONTEXT_INSTANCE] = ctx;
+    // Per-element Map of handler-name → wrapped function. Symbol-keyed so it
+    // doesn't pollute the element's public surface.
+    let wrapped = element[WRAPPED_CONTEXT_HANDLERS];
+    if (!wrapped) {
+        wrapped = new Map();
+        element[WRAPPED_CONTEXT_HANDLERS] = wrapped;
+    }
+    // Register each handler with the Context
+    for (const handler of handlers) {
+        const { kind, options } = handler;
+        const handlerName = kind === 'field' ? handler.fieldName : handler.methodName;
+        // Create wrapped method with timing controls
+        const wrappedFn = function (context) {
+            // Skip if already called once
+            if (options.once && element[CONTEXT_CALLED]) {
+                return;
+            }
+            const callMethod = () => {
+                if (kind === 'field') {
+                    element[handler.fieldName] = context;
+                }
+                else {
+                    handler.method.call(element, context);
+                }
+                // Handle once option
+                if (options.once) {
+                    element[CONTEXT_CALLED] = true;
+                    // Unregister after first call
+                    const ctx = element[NAVIGATION_CONTEXT_INSTANCE];
+                    if (ctx && typeof ctx[CONTEXT_UNREGISTER] === 'function') {
+                        ctx[CONTEXT_UNREGISTER](element);
+                    }
+                }
+            };
+            // Per-handler timer slot to avoid debounce/throttle handlers on the same
+            // element overwriting each other's state.
+            const timerSlot = element[CONTEXT_TIMER] ||
+                (element[CONTEXT_TIMER] = {});
+            const timerKey = handlerName;
+            if (options.debounce) {
+                clearTimeout(timerSlot[timerKey]?.timeout);
+                timerSlot[timerKey] = {
+                    timeout: setTimeout(callMethod, options.debounce),
+                };
+                return;
+            }
+            if (options.throttle) {
+                const now = Date.now();
+                const lastCall = timerSlot[timerKey]?.lastCall || 0;
+                if (now - lastCall >= options.throttle) {
+                    timerSlot[timerKey] = { lastCall: now };
+                    callMethod();
+                }
+                return;
+            }
+            callMethod();
+        };
+        wrapped.set(handlerName, wrappedFn);
+        // Register with the Context using the handler name (lookup goes through
+        // the WRAPPED_CONTEXT_HANDLERS Map on the element).
+        if (typeof ctx[CONTEXT_REGISTER] === 'function') {
+            ctx[CONTEXT_REGISTER](element, handlerName);
+        }
+        // Synchronously emit current context to the just-registered handler so
+        // field/method values are populated BEFORE the first render microtask
+        // flushes — eliminates the cold-render flicker where ctx is undefined.
+        try {
+            wrappedFn(ctx);
+        }
+        catch (error) {
+            console.error(`Error invoking @context handler at registration:`, error);
+        }
+    }
+}
+/**
+ * Cleanup context handler for an element instance
+ * Called automatically during element disconnection
+ */
+function cleanupContextHandler(element) {
+    const handlers = element.constructor[CONTEXT_HANDLERS];
+    if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
+        return;
+    }
+    // Clear any pending debounce timers (per-handler slots)
+    const timerSlot = element[CONTEXT_TIMER];
+    if (timerSlot && typeof timerSlot === 'object') {
+        for (const key of Object.keys(timerSlot)) {
+            if (timerSlot[key]?.timeout)
+                clearTimeout(timerSlot[key].timeout);
+        }
+        delete element[CONTEXT_TIMER];
+    }
+    // Drop the per-element wrapped-handlers Map.
+    delete element[WRAPPED_CONTEXT_HANDLERS];
+    // Unregister from Context if available
+    const ctx = element[NAVIGATION_CONTEXT_INSTANCE];
+    if (ctx && typeof ctx[CONTEXT_UNREGISTER] === 'function') {
+        ctx[CONTEXT_UNREGISTER](element);
+    }
+    delete element[NAVIGATION_CONTEXT_INSTANCE];
+    delete element[CONTEXT_CALLED];
+}
+
 // Controller-scoped cleanup registry
 class ControllerScope {
     constructor() {
@@ -2786,6 +2988,14 @@ async function attachController(element, controllerName) {
     if (routerContext !== undefined) {
         controllerInstance[ROUTER_CONTEXT] = routerContext;
     }
+    // Mirror the element's CONTEXT_HANDLER onto the controller so
+    // setupContextHandler can wire @context() handlers declared on the
+    // controller class. This makes @context() work identically on elements
+    // and controllers.
+    const ctxHandler = element[CONTEXT_HANDLER];
+    if (ctxHandler !== undefined) {
+        controllerInstance[CONTEXT_HANDLER] = ctxHandler;
+    }
     // Store references
     element[CONTROLLER_KEY] = controllerInstance;
     element[CONTROLLER_NAME_KEY] = controllerName;
@@ -2824,6 +3034,8 @@ async function attachController(element, controllerName) {
     setupResponseHandlers(controllerInstance, element);
     // Setup @on event handlers for controller
     setupEventHandlers(controllerInstance, element);
+    // Setup @context() handlers for controller (fires sync emit at register)
+    setupContextHandler(controllerInstance);
     element.dispatchEvent(new CustomEvent('controller-attached', {
         detail: { name: controllerName, controller: controllerInstance }
     }));
@@ -2860,12 +3072,15 @@ async function detachController(element) {
     cleanupResponseHandlers(controllerInstance);
     // Cleanup @on event handlers for controller
     cleanupEventHandlers(controllerInstance);
+    // Cleanup @context() handlers for controller
+    cleanupContextHandler(controllerInstance);
     // Cleanup the controller scope
     if (scope) {
         await scope.cleanup();
     }
-    // Clean up router context reference
+    // Clean up router/context references
     delete controllerInstance[ROUTER_CONTEXT];
+    delete controllerInstance[CONTEXT_HANDLER];
     delete element[CONTROLLER_KEY];
     delete element[CONTROLLER_NAME_KEY];
     delete element[CONTROLLER_OPERATIONS];
@@ -2960,206 +3175,6 @@ function useNativeElementControllers() {
     globalThis.sniceNativeControllerObserver = observer;
 }
 
-/**
- * @context decorator for receiving router context updates
- */
-const CONTEXT_HANDLERS = getSymbol('context-handlers');
-/**
- * @context decorator for receiving router context updates
- *
- * Works on both methods and fields:
- *
- * - **Method form**: the method is invoked with the current Context on every
- *   update (and once at register time so the first render sees the context).
- * - **Field form**: the field is overwritten with the current Context on
- *   every update (and once at register time). Pair with `@property` if you
- *   want assignment to also schedule a re-render.
- *
- * @example
- * ```typescript
- * @element('my-layout')
- * class MyLayout extends HTMLElement {
- *   // Method form
- *   @context()
- *   handleContext(ctx: Context) {
- *     this.renderNav(ctx.navigation.placards, ctx.navigation.route);
- *   }
- *
- *   // Field form — the field is populated before first render
- *   @context() ctx!: Context;
- *
- *   // Field + @property — assignment also triggers re-render
- *   @property({ attribute: false }) @context() reactiveCtx!: Context;
- * }
- * ```
- */
-function context$1(options = {}) {
-    return function (value, decoratorContext) {
-        const name = decoratorContext.name;
-        const kind = decoratorContext.kind;
-        const registerHandler = function () {
-            const constructor = this.constructor;
-            // De-dupe: methods identify by reference, fields identify by name.
-            if (!Object.prototype.hasOwnProperty.call(constructor, CONTEXT_METHODS)) {
-                constructor[CONTEXT_METHODS] = new Set();
-            }
-            const dedupeKey = kind === 'method' ? value : `field:${name}`;
-            if (constructor[CONTEXT_METHODS].has(dedupeKey))
-                return;
-            constructor[CONTEXT_METHODS].add(dedupeKey);
-            if (!Object.prototype.hasOwnProperty.call(constructor, CONTEXT_HANDLERS)) {
-                const inherited = constructor[CONTEXT_HANDLERS];
-                constructor[CONTEXT_HANDLERS] = inherited ? [...inherited] : [];
-            }
-            if (kind === 'method') {
-                constructor[CONTEXT_HANDLERS].push({
-                    kind: 'method',
-                    methodName: name,
-                    method: value,
-                    options,
-                });
-            }
-            else if (kind === 'field' || kind === 'accessor') {
-                constructor[CONTEXT_HANDLERS].push({
-                    kind: 'field',
-                    fieldName: name,
-                    options,
-                });
-            }
-        };
-        if (kind === 'method') {
-            decoratorContext.addInitializer(registerHandler);
-            return value;
-        }
-        // Field decorators: do registration via the init function (fires per
-        // instance during construction, with `this` bound). Returning the init
-        // function is the canonical Stage 3 way for field decorators —
-        // `addInitializer` for fields can be late or unreliable across runtimes.
-        return function (initialValue) {
-            registerHandler.call(this);
-            return initialValue;
-        };
-    };
-}
-/**
- * Setup context handler for an element instance
- * Called automatically during element connection
- */
-function setupContextHandler(element) {
-    const handlers = element.constructor[CONTEXT_HANDLERS];
-    if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
-        return;
-    }
-    // Get the Context instance from the router
-    const ctx = element[CONTEXT_HANDLER];
-    if (!ctx) {
-        return;
-    }
-    // Store the Context instance for cleanup
-    element[NAVIGATION_CONTEXT_INSTANCE] = ctx;
-    // Per-element Map of handler-name → wrapped function. Symbol-keyed so it
-    // doesn't pollute the element's public surface.
-    let wrapped = element[WRAPPED_CONTEXT_HANDLERS];
-    if (!wrapped) {
-        wrapped = new Map();
-        element[WRAPPED_CONTEXT_HANDLERS] = wrapped;
-    }
-    // Register each handler with the Context
-    for (const handler of handlers) {
-        const { kind, options } = handler;
-        const handlerName = kind === 'field' ? handler.fieldName : handler.methodName;
-        // Create wrapped method with timing controls
-        const wrappedFn = function (context) {
-            // Skip if already called once
-            if (options.once && element[CONTEXT_CALLED]) {
-                return;
-            }
-            const callMethod = () => {
-                if (kind === 'field') {
-                    element[handler.fieldName] = context;
-                }
-                else {
-                    handler.method.call(element, context);
-                }
-                // Handle once option
-                if (options.once) {
-                    element[CONTEXT_CALLED] = true;
-                    // Unregister after first call
-                    const ctx = element[NAVIGATION_CONTEXT_INSTANCE];
-                    if (ctx && typeof ctx[CONTEXT_UNREGISTER] === 'function') {
-                        ctx[CONTEXT_UNREGISTER](element);
-                    }
-                }
-            };
-            // Per-handler timer slot to avoid debounce/throttle handlers on the same
-            // element overwriting each other's state.
-            const timerSlot = element[CONTEXT_TIMER] ||
-                (element[CONTEXT_TIMER] = {});
-            const timerKey = handlerName;
-            if (options.debounce) {
-                clearTimeout(timerSlot[timerKey]?.timeout);
-                timerSlot[timerKey] = {
-                    timeout: setTimeout(callMethod, options.debounce),
-                };
-                return;
-            }
-            if (options.throttle) {
-                const now = Date.now();
-                const lastCall = timerSlot[timerKey]?.lastCall || 0;
-                if (now - lastCall >= options.throttle) {
-                    timerSlot[timerKey] = { lastCall: now };
-                    callMethod();
-                }
-                return;
-            }
-            callMethod();
-        };
-        wrapped.set(handlerName, wrappedFn);
-        // Register with the Context using the handler name (lookup goes through
-        // the WRAPPED_CONTEXT_HANDLERS Map on the element).
-        if (typeof ctx[CONTEXT_REGISTER] === 'function') {
-            ctx[CONTEXT_REGISTER](element, handlerName);
-        }
-        // Synchronously emit current context to the just-registered handler so
-        // field/method values are populated BEFORE the first render microtask
-        // flushes — eliminates the cold-render flicker where ctx is undefined.
-        try {
-            wrappedFn(ctx);
-        }
-        catch (error) {
-            console.error(`Error invoking @context handler at registration:`, error);
-        }
-    }
-}
-/**
- * Cleanup context handler for an element instance
- * Called automatically during element disconnection
- */
-function cleanupContextHandler(element) {
-    const handlers = element.constructor[CONTEXT_HANDLERS];
-    if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
-        return;
-    }
-    // Clear any pending debounce timers (per-handler slots)
-    const timerSlot = element[CONTEXT_TIMER];
-    if (timerSlot && typeof timerSlot === 'object') {
-        for (const key of Object.keys(timerSlot)) {
-            if (timerSlot[key]?.timeout)
-                clearTimeout(timerSlot[key].timeout);
-        }
-        delete element[CONTEXT_TIMER];
-    }
-    // Drop the per-element wrapped-handlers Map.
-    delete element[WRAPPED_CONTEXT_HANDLERS];
-    // Unregister from Context if available
-    const ctx = element[NAVIGATION_CONTEXT_INSTANCE];
-    if (ctx && typeof ctx[CONTEXT_UNREGISTER] === 'function') {
-        ctx[CONTEXT_UNREGISTER](element);
-    }
-    delete element[NAVIGATION_CONTEXT_INSTANCE];
-    delete element[CONTEXT_CALLED];
-}
-
 /**
  * @render and @styles decorators for Snice v3.0.0
  * Provides automatic differential rendering on property changes