snice 4.28.0 → 4.30.0

package/dist/cdn/runtime/README.md

@@ -17,8 +17,8 @@ Load the runtime once, then load any CDN components:
 ```
 
 ## Size
-- Minified: 57.6 KB
-- Gzipped: 17.5 KB
+- Minified: 58.7 KB
+- Gzipped: 17.9 KB
 
 ## Documentation
 https://snice.dev

package/dist/cdn/runtime/snice-runtime.esm.js

@@ -1,11 +1,11 @@
 /*!
- * snice v4.28.0
+ * snice v4.30.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.
  */
 /*!
- * snice v4.27.0
+ * snice v4.29.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.
@@ -4631,20 +4631,45 @@ function Router(options) {
         currentLayoutName = null;
         currentLayoutTimestamp = null;
     }
-    function checkGuards(guards, params, target) {
+    function createLoadingSpinner() {
+        const container = doc.createElement('div');
+        container.setAttribute('data-snice-loading', '');
+        container.innerHTML = /*html*/ `
+      <style>@keyframes snice-spin{to{transform:rotate(360deg)}}</style>
+      <div style="display:flex;align-items:center;justify-content:center;height:100%;min-height:200px">
+        <div style="width:32px;height:32px;border:3px solid rgba(128,128,128,0.3);border-top-color:rgba(128,128,128,0.8);border-radius:50%;animation:snice-spin 0.6s linear infinite"></div>
+      </div>`;
+        return container;
+    }
+    async 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 = guard(context, params);
-            if (!allowed) {
-                renderForbiddenPage(target);
-                return false;
+        let spinner = null;
+        let spinnerTimer = null;
+        // Show spinner after a short delay (avoids flash for fast sync guards)
+        spinnerTimer = setTimeout(() => {
+            spinner = createLoadingSpinner();
+            target.appendChild(spinner);
+        }, 50);
+        try {
+            for (const guard of guardsArray) {
+                const allowed = await guard(context, params);
+                if (!allowed) {
+                    renderForbiddenPage(target);
+                    return false;
+                }
             }
+            return true;
+        }
+        finally {
+            if (spinnerTimer)
+                clearTimeout(spinnerTimer);
+            if (spinner)
+                spinner.remove();
         }
-        return true;
     }
     function createHomeElement() {
         const newPageElement = doc.createElement(home);
@@ -4668,14 +4693,14 @@ function Router(options) {
         div.innerHTML = /*html*/ `<h1>404</h1><p>Page not found</p>`;
         return { element: div, transition: undefined, layout: undefined };
     }
-    function resolveRoute(path, target) {
+    async function resolveRoute(path, target) {
         for (const route of routes) {
             const params = route.route.match(path);
             const isMatch = params !== false;
             if (!isMatch) {
                 continue;
             }
-            const guardsAllowed = checkGuards(route.guards, params, target);
+            const guardsAllowed = await checkGuards(route.guards, params, target);
             if (!guardsAllowed) {
                 return { result: RouteResult.GUARDS_FAILED };
             }
@@ -4788,7 +4813,7 @@ function Router(options) {
         const isHomePath = (path?.trim() === '' || path === '/') && !!home;
         if (isHomePath) {
             const homeRoute = routes.find(r => r.route.match('/'));
-            if (!checkGuards(homeRoute?.guards, {}, target))
+            if (!(await checkGuards(homeRoute?.guards, {}, target)))
                 return;
             const { element, transition, layout } = createHomeElement();
             await renderPage(target, element, transition, layout, path, {});
@@ -4798,7 +4823,7 @@ function Router(options) {
         if (!path)
             return;
         // Resolve route
-        const routeResult = resolveRoute(path, target);
+        const routeResult = await resolveRoute(path, target);
         // Guards failed (403 already rendered by checkGuards)
         if (routeResult.result === RouteResult.GUARDS_FAILED)
             return;
@@ -4905,6 +4930,74 @@ function dispatch(eventName, options) {
     };
 }
 
+/**
+ * createRequestHandler — vanilla JS utility for handling @request channels
+ * outside of the Snice element/controller decorator system.
+ *
+ * Listens for @request CustomEvents on a target element (or document),
+ * performs the discovery/data handshake, and dispatches to your route map.
+ *
+ * @example
+ * ```js
+ * import { createRequestHandler } from 'snice';
+ *
+ * const cleanup = createRequestHandler(document, {
+ *   'fetch-user': async (payload) => {
+ *     const res = await fetch(`/api/users/${payload.id}`);
+ *     return res.json();
+ *   },
+ *   'save-settings': async (payload) => {
+ *     await fetch('/api/settings', { method: 'POST', body: JSON.stringify(payload) });
+ *     return { ok: true };
+ *   }
+ * });
+ *
+ * // Later, to remove all listeners:
+ * cleanup();
+ * ```
+ */
+/**
+ * Attach request handlers to a DOM target.
+ *
+ * @param target  The element or document to listen on. Events bubble, so an
+ *                ancestor element catches requests from any descendant.
+ * @param routes  Map of channel names to handler functions.
+ * @param options Optional configuration.
+ * @returns A cleanup function that removes all listeners.
+ */
+function createRequestHandler(target, routes, options) {
+    const cleanups = [];
+    for (const [channelName, handler] of Object.entries(routes)) {
+        const eventName = `@request/${channelName}`;
+        const listener = (event) => {
+            const ce = event;
+            const { discovery, data, payload } = ce.detail;
+            if (!options?.passive) {
+                ce.preventDefault();
+                ce.stopImmediatePropagation();
+                ce.stopPropagation();
+            }
+            // Signal that we found the handler — clears discovery timeout
+            discovery.resolve();
+            // Execute the handler and wire up the data promise
+            Promise.resolve()
+                .then(() => handler(payload))
+                .then((result) => data.resolve(result))
+                .catch((error) => {
+                data.reject(error);
+                console.error(`createRequestHandler: error in "${channelName}" handler:`, error);
+            });
+        };
+        target.addEventListener(eventName, listener);
+        cleanups.push(() => target.removeEventListener(eventName, listener));
+    }
+    return () => {
+        for (const fn of cleanups)
+            fn();
+        cleanups.length = 0;
+    };
+}
+
 /**
  * Custom element readiness utilities
  * Handles waiting for custom elements to be defined with timeout warnings
@@ -5441,7 +5534,7 @@ if (typeof document !== 'undefined') {
 }
 
 /*!
- * snice v4.27.0
+ * snice v4.29.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.
@@ -5458,7 +5551,7 @@ if (!globalThis.snice) {
 }
 
 /*!
- * snice v4.27.0
+ * snice v4.29.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.
@@ -5478,5 +5571,5 @@ var TransitionMode;
     TransitionMode["SIMULTANEOUS"] = "simultaneous";
 })(TransitionMode || (TransitionMode = {}));
 
-export { Context, ContextAwareFetcher, IS_CONTROLLER_INSTANCE, Router, SimpleArray, adopted, applyElementFunctionality, clearDebounceTimers, clearMemoizeCache, clearThrottleTimers, context$1 as context, context as contextProperty, controller, css, debounce, dispatch, dispose, element, getSymbol, html, layout, memoize, moved, noChange, nothing, observe, on, once, property, query, queryAll, ready, render, request, resetOnce, respond, setDisableElementReadyWarnings, styles, throttle, trackRenders, unsafeHTML, useNativeElementControllers, waitForAllCustomElements, waitForElementDefined, waitForElementReady, watch };
+export { Context, ContextAwareFetcher, IS_CONTROLLER_INSTANCE, Router, SimpleArray, adopted, applyElementFunctionality, clearDebounceTimers, clearMemoizeCache, clearThrottleTimers, context$1 as context, context as contextProperty, controller, createRequestHandler, css, debounce, dispatch, dispose, element, getSymbol, html, layout, memoize, moved, noChange, nothing, observe, on, once, property, query, queryAll, ready, render, request, resetOnce, respond, setDisableElementReadyWarnings, styles, throttle, trackRenders, unsafeHTML, useNativeElementControllers, waitForAllCustomElements, waitForElementDefined, waitForElementReady, watch };
 //# sourceMappingURL=snice-runtime.esm.js.map