snice 5.0.0 → 5.1.0

package/dist/index.iife.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.40.0
+ * snice v5.0.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.
@@ -92,6 +92,7 @@ var Snice = (function (exports) {
     const CONTEXT_TIMER = getSymbol('context-timer');
     const CONTEXT_CALLED = getSymbol('context-called');
     const CONTEXT_UPDATE = getSymbol('context-update');
+    const WRAPPED_CONTEXT_HANDLERS = getSymbol('wrapped-context-handlers');
     // Registration de-dup sets on the constructor — replace previous `__*Methods`
     // expando strings that violated the no-double-underscore rule.
     const CONTEXT_METHODS = getSymbol('context-methods');
@@ -267,13 +268,17 @@ var Snice = (function (exports) {
                 const names = elementsMap.get(element);
                 if (!names)
                     continue;
-                for (const methodName of names) {
-                    if (typeof element[methodName] === 'function') {
+                const wrapped = element[WRAPPED_CONTEXT_HANDLERS];
+                if (!wrapped)
+                    continue;
+                for (const handlerName of names) {
+                    const fn = wrapped.get(handlerName);
+                    if (typeof fn === 'function') {
                         try {
-                            element[methodName](this);
+                            fn(this);
                         }
                         catch (error) {
-                            console.error(`Error calling @context method ${methodName}:`, error);
+                            console.error(`Error calling @context handler ${handlerName}:`, error);
                         }
                     }
                 }
@@ -288,10 +293,13 @@ var Snice = (function (exports) {
             const names = this[REGISTERED_ELEMENTS].get(element);
             if (!names)
                 return;
-            for (const methodName of names) {
-                if (typeof element[methodName] === 'function') {
-                    element[methodName](this);
-                }
+            const wrapped = element[WRAPPED_CONTEXT_HANDLERS];
+            if (!wrapped)
+                return;
+            for (const handlerName of names) {
+                const fn = wrapped.get(handlerName);
+                if (typeof fn === 'function')
+                    fn(this);
             }
         }
     }
@@ -2960,46 +2968,78 @@ var Snice = (function (exports) {
     /**
      * @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 {
-     *   @context
+     *   // Method form
+     *   @context()
      *   handleContext(ctx: Context) {
-     *     this.renderNav(ctx.placards, ctx.currentRoute);
+     *     this.renderNav(ctx.navigation.placards, ctx.navigation.route);
      *   }
      *
-     *   @context({ debounce: 300 })
-     *   handleContextDebounced(ctx: Context) {
-     *     // Called after 300ms of no updates
-     *   }
+     *   // 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 (originalMethod, context) {
-            const methodName = context.name;
-            context.addInitializer(function () {
+        return function (value, decoratorContext) {
+            const name = decoratorContext.name;
+            const kind = decoratorContext.kind;
+            const registerHandler = function () {
                 const constructor = this.constructor;
-                // hasOwnProperty guards so subclasses don't mutate parent state via
-                // the prototype chain.
+                // De-dupe: methods identify by reference, fields identify by name.
                 if (!Object.prototype.hasOwnProperty.call(constructor, CONTEXT_METHODS)) {
                     constructor[CONTEXT_METHODS] = new Set();
                 }
-                if (constructor[CONTEXT_METHODS].has(originalMethod))
+                const dedupeKey = kind === 'method' ? value : `field:${name}`;
+                if (constructor[CONTEXT_METHODS].has(dedupeKey))
                     return;
-                constructor[CONTEXT_METHODS].add(originalMethod);
+                constructor[CONTEXT_METHODS].add(dedupeKey);
                 if (!Object.prototype.hasOwnProperty.call(constructor, CONTEXT_HANDLERS)) {
                     const inherited = constructor[CONTEXT_HANDLERS];
                     constructor[CONTEXT_HANDLERS] = inherited ? [...inherited] : [];
                 }
-                constructor[CONTEXT_HANDLERS].push({
-                    methodName,
-                    method: originalMethod,
-                    options,
-                });
-            });
-            return originalMethod;
+                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;
+            };
         };
     }
     /**
@@ -3018,18 +3058,30 @@ var Snice = (function (exports) {
         }
         // 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 { methodName, method, options } = handler;
-            const wrappedMethodName = `__wrapped_${methodName}`;
+            const { kind, options } = handler;
+            const handlerName = kind === 'field' ? handler.fieldName : handler.methodName;
             // Create wrapped method with timing controls
-            element[wrappedMethodName] = function (context) {
+            const wrappedFn = function (context) {
                 // Skip if already called once
                 if (options.once && element[CONTEXT_CALLED]) {
                     return;
                 }
                 const callMethod = () => {
-                    method.call(element, context);
+                    if (kind === 'field') {
+                        element[handler.fieldName] = context;
+                    }
+                    else {
+                        handler.method.call(element, context);
+                    }
                     // Handle once option
                     if (options.once) {
                         element[CONTEXT_CALLED] = true;
@@ -3044,7 +3096,7 @@ var Snice = (function (exports) {
                 // element overwriting each other's state.
                 const timerSlot = element[CONTEXT_TIMER] ||
                     (element[CONTEXT_TIMER] = {});
-                const timerKey = methodName;
+                const timerKey = handlerName;
                 if (options.debounce) {
                     clearTimeout(timerSlot[timerKey]?.timeout);
                     timerSlot[timerKey] = {
@@ -3063,9 +3115,20 @@ var Snice = (function (exports) {
                 }
                 callMethod();
             };
-            // Register with the Context using the wrapped method name
+            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, wrappedMethodName);
+                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);
             }
         }
     }
@@ -3087,11 +3150,8 @@ var Snice = (function (exports) {
             }
             delete element[CONTEXT_TIMER];
         }
-        for (const handler of handlers) {
-            // Clean up wrapped method
-            const wrappedMethodName = `__wrapped_${handler.methodName}`;
-            delete element[wrappedMethodName];
-        }
+        // 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') {