snice 5.0.0 → 5.1.0

package/dist/context.d.ts

@@ -15,23 +15,33 @@ export interface ContextOptions {
 /**
  * @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;
  * }
  * ```
  */
-export declare function context(options?: ContextOptions): (originalMethod: any, context: ClassMethodDecoratorContext) => any;
+export declare function context(options?: ContextOptions): (value: any, decoratorContext: ClassMethodDecoratorContext | ClassFieldDecoratorContext) => any;
 /**
  * Setup context handler for an element instance
  * Called automatically during element connection

package/dist/index.cjs

@@ -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.
@@ -91,6 +91,7 @@ const CONTEXT_NOTIFY_ELEMENT = getSymbol('context-notify-element');
 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');
@@ -266,13 +267,17 @@ class Context {
             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);
                     }
                 }
             }
@@ -287,10 +292,13 @@ class Context {
         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);
         }
     }
 }
@@ -2959,46 +2967,78 @@ 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 {
- *   @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;
+        };
     };
 }
 /**
@@ -3017,18 +3057,30 @@ function setupContextHandler(element) {
     }
     // 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;
@@ -3043,7 +3095,7 @@ function setupContextHandler(element) {
             // 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] = {
@@ -3062,9 +3114,20 @@ function setupContextHandler(element) {
             }
             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);
         }
     }
 }
@@ -3086,11 +3149,8 @@ function cleanupContextHandler(element) {
         }
         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') {