@stacksjs/stx 0.2.175 → 0.2.177

package/dist/signals.js

@@ -1065,6 +1065,10 @@ finally {
     // case where a template is most likely driving a spinner off it (#1818).
     const immediate = options.immediate !== false;
     const loading = state(immediate);
+    // Any request in flight, background ones included. loading answers "is
+    // there nothing to show yet"; isFetching answers "is a request open" \u2014 and
+    // a background refresh is the case where those two stop agreeing (#1929).
+    const isFetching = state(immediate);
     const error = state(null);
     if (options.suspense) registerSuspense(loading, error);
 
@@ -1074,17 +1078,24 @@ finally {
     // last in-flight one. State writes are guarded on signal.aborted (#1871).
     let __stxAbort = null;
 
-    const fetchData = async () => {
+    // runOptions: { background: true } refreshes data WITHOUT touching loading
+    // or clearing the current error, so a poll cannot flash a spinner or blank
+    // an error message that is still true. Everything already on screen stays
+    // there until the new response actually lands (#1929).
+    const fetchData = async (runOptions) => {
+      const background = !!(runOptions && runOptions.background);
       if (__stxAbort) __stxAbort.abort();
       __stxAbort = (typeof AbortController !== 'undefined') ? new AbortController() : null;
       const __signal = __stxAbort ? __stxAbort.signal : undefined;
-      loading.set(true);
-      error.set(null);
+      if (!background) loading.set(true);
+      isFetching.set(true);
+      if (!background) error.set(null);
 
       try {
         const url = typeof urlOrFn === 'function' ? urlOrFn() : urlOrFn;
         if (!url) {
-          loading.set(false);
+          if (!background) loading.set(false);
+          isFetching.set(false);
           return;
         }
 
@@ -1114,6 +1125,10 @@ finally {
         // Apply transform if provided
         const transformed = options.transform ? options.transform(result) : result;
         data.set(transformed);
+        // A background run did not clear the error up front, so a recovery has
+        // to clear it here \u2014 otherwise the first failed poll would leave the
+        // message on screen for the life of the page.
+        if (background) error.set(null);
       }
 catch (e) {
         // A superseded/unmounted request rejects with AbortError \u2014 expected,
@@ -1128,7 +1143,10 @@ catch (e) {
       }
 finally {
         // If a newer run (or onDestroy) aborted this one, that run owns loading.
-        if (!__signal || !__signal.aborted) loading.set(false);
+        if (!__signal || !__signal.aborted) {
+          if (!background) loading.set(false);
+          isFetching.set(false);
+        }
       }
     };
 
@@ -1161,6 +1179,7 @@ else if (immediate) {
     return {
       data,
       loading,
+      isFetching,
       error,
       refetch: fetchData,
       // Convenience getters
@@ -1411,6 +1430,10 @@ else if (immediate) {
     var cacheKey = options.cacheKey || (typeof url === 'function' ? null : url);
     var data = state(options.initialData || null);
     var loading = state(true);
+    // See useFetch: loading means "nothing to show yet", isFetching means "a
+    // request is open" \u2014 including a background refresh, which is the case that
+    // makes the distinction necessary (#1929).
+    var isFetching = state(true);
     var error = state(null);
     var isStale = state(false);
     if (options.suspense) registerSuspense(loading, error);
@@ -1429,16 +1452,21 @@ else if (immediate) {
     // can release its claim without cancelling a request someone else joined.
     var __joined = null;
 
-    var fetchData = async function() {
+    // runOptions: { background: true } refreshes without touching loading or
+    // clearing the current error. A poll must not flash a spinner over data
+    // that is already on screen (#1929).
+    var fetchData = async function(runOptions) {
+      var background = !!(runOptions && runOptions.background);
       var resolvedUrl = typeof url === 'function' ? url() : url;
-      if (!resolvedUrl) { loading.set(false); return; }
+      if (!resolvedUrl) { if (!background) loading.set(false); isFetching.set(false); return; }
       var key = cacheKey || resolvedUrl;
 
       // Check cache
       var cached = _queryCache[key];
       if (cached && (Date.now() - cached.timestamp < staleTime)) {
         data.set(cached.data);
-        loading.set(false);
+        if (!background) loading.set(false);
+        isFetching.set(false);
         isStale.set(false);
         if (options.onSuccess) options.onSuccess(cached.data);
         return;
@@ -1458,12 +1486,14 @@ else if (immediate) {
       if (shared && shared.owner !== __instanceId) {
         shared.refs++;
         __joined = shared;
-        loading.set(true);
-        error.set(null);
+        if (!background) loading.set(true);
+        isFetching.set(true);
+        if (!background) error.set(null);
         try {
           var joinedResult = await shared.promise;
           var joinedTransformed = options.transform ? options.transform(joinedResult) : joinedResult;
           data.set(joinedTransformed);
+          if (background) error.set(null);
           isStale.set(false);
           if (options.onSuccess) options.onSuccess(joinedTransformed);
         }
@@ -1475,7 +1505,8 @@ else if (immediate) {
         finally {
           shared.refs--;
           if (__joined === shared) __joined = null;
-          loading.set(false);
+          if (!background) loading.set(false);
+          isFetching.set(false);
         }
         return;
       }
@@ -1490,8 +1521,9 @@ else if (immediate) {
       __joined = null;
       __stxAbort = (typeof AbortController !== 'undefined') ? new AbortController() : null;
       var __signal = __stxAbort ? __stxAbort.signal : undefined;
-      loading.set(true);
-      error.set(null);
+      if (!background) loading.set(true);
+      isFetching.set(true);
+      if (!background) error.set(null);
       try {
         var fetchOpts = { method: 'GET', headers: { 'Content-Type': 'application/json', ...__stxHeaders(options.headers) }, signal: __signal };
         // Published BEFORE it is awaited, so a caller starting in the same tick
@@ -1515,6 +1547,7 @@ else if (immediate) {
         if (__signal && __signal.aborted) return;
         var transformed = options.transform ? options.transform(result) : result;
         data.set(transformed);
+        if (background) error.set(null);
         isStale.set(false);
         _queryCache[key] = { data: transformed, timestamp: Date.now() };
         if (options.onSuccess) options.onSuccess(transformed);
@@ -1529,7 +1562,10 @@ catch (e) {
         if (options.onError) options.onError(e);
       }
 finally {
-        if (!__signal || !__signal.aborted) loading.set(false);
+        if (!__signal || !__signal.aborted) {
+          if (!background) loading.set(false);
+          isFetching.set(false);
+        }
       }
     };
 
@@ -1537,13 +1573,20 @@ finally {
       onMount(fetchData);
     }
 
+    // A refetch nobody asked for does not set loading. Both of these refresh
+    // data that is ALREADY on screen, so driving the first-load state from them
+    // put a spinner over a populated view once a minute, forever \u2014 the reason a
+    // polling view could not use this composable at all (#1929). Bind
+    // isFetching for a subtle in-flight indicator.
+    var backgroundRun = { background: true };
+
     // refetchOnFocus \u2014 removed on destroy, like refetchInterval right below.
     // It used to add a listener and never remove it, so every instance leaked
     // one for the life of the page and each SPA navigation added more; every
     // stale listener still fired, refetching for components long gone (#1818).
     if (options.refetchOnFocus) {
       var onVisibility = function() {
-        if (!document.hidden) fetchData();
+        if (!document.hidden) fetchData(backgroundRun);
       };
       document.addEventListener('visibilitychange', onVisibility);
       onDestroy(function() { document.removeEventListener('visibilitychange', onVisibility); });
@@ -1557,7 +1600,7 @@ finally {
         if (typeof document !== 'undefined' && document.hidden) return;
         var en = options.enabled;
         if (typeof en === 'function' ? !en() : en === false) return;
-        var p = fetchData();
+        var p = fetchData(backgroundRun);
         if (options.stopOnError && p && typeof p.then === 'function') {
           p.then(function() { if (error()) clearInterval(intervalId); });
         }
@@ -1571,13 +1614,14 @@ finally {
     return {
       data: data,
       loading: loading,
+      isFetching: isFetching,
       error: error,
       isStale: isStale,
       refetch: fetchData,
-      invalidate: function() {
+      invalidate: function(runOptions) {
         var key = cacheKey || (typeof url === 'function' ? url() : url);
         delete _queryCache[key];
-        return fetchData();
+        return fetchData(runOptions);
       }
     };
   }
@@ -2145,11 +2189,18 @@ catch (e) {
     if (!el || !el.getAttribute || value === undefined) return;
     var scopeId = el.getAttribute('data-stx-scope');
     var scopeVars = scopeId && window.stx._scopes && window.stx._scopes[scopeId];
-    if (!scopeVars) return;
     var camelName = name.replace(/-([a-z0-9])/g, function(_, character) {
       return character.toUpperCase();
     });
-    var propSignal = scopeVars[name] || scopeVars[camelName];
+    // useReactiveProp signals are often intentionally aliased inside the
+    // child, for example liveClosable = useReactiveProp('closable', true).
+    // The public prop name therefore cannot be inferred from the variable
+    // name exported by the component scope. Keep an element-owned registry as
+    // the canonical bridge, with the scope lookup retained for older output.
+    var propSignals = el.__stx_reactive_prop_signals;
+    var propSignal = propSignals && (propSignals[name] || propSignals[camelName]);
+    if (!propSignal && scopeVars)
+      propSignal = scopeVars[name] || scopeVars[camelName];
     if (!propSignal || !propSignal._isSignal || typeof propSignal.set !== 'function') return;
     var directValues = el.__stx_direct_prop_values || (el.__stx_direct_prop_values = {});
     var directValue = {
@@ -2477,13 +2528,12 @@ else if (part) {
     }
 
     // x-else / x-else-if are owned by their preceding x-if chain (#1734).
-    // A detached chain member reached via the parent's snapshot child-
-    // iteration must be skipped \u2014 bindIfChain manages its lifecycle and
-    // only the active branch is (re)connected. Connected chain members
-    // (the active branch) fall through; their if/else attr was already
-    // removed by bindIfChain, and double-bind guards make any redundant
-    // pass idempotent.
-    if (el.__stx_chain_member && !el.isConnected) return;
+    // An inactive chain member reached via the parent's snapshot child-
+    // iteration must be skipped. Connectivity cannot identify inactivity:
+    // an active inner branch is also disconnected while an outer conditional
+    // temporarily detaches its parent. bindIfChain owns explicit branch state
+    // so nested structural effects can still hydrate active detached subtrees.
+    if (el.__stx_chain_member && !el.__stx_chain_active) return;
 
     // An else/else-if with no preceding if is an orphan. Match Vue: warn,
     // strip the attribute, and render it as a plain element (fall through).
@@ -2769,12 +2819,16 @@ else if (name === 'ref' || name === ':ref' || name === 'x-ref' || name === 'data
             ? event.detail
             : event;
 
-          // Skip clicks on elements that just became visible in this frame.
-          // Prevents modal backdrop from catching the click that opened the modal.
+          // Skip an opener click that reaches UI which just became visible in
+          // this frame. A click whose target is inside the revealed subtree is
+          // a real interaction and must not be discarded, especially for
+          // async lists whose controls are usable as soon as they render.
           if (eventName === 'click') {
             var ancestor = el;
             while (ancestor) {
-              if (ancestor.__stx_shown_at && (performance.now() - ancestor.__stx_shown_at) < 50) return;
+              if (ancestor.__stx_shown_at
+                && (performance.now() - ancestor.__stx_shown_at) < 50
+                && !(ancestor.contains && ancestor.contains(event.target))) return;
               ancestor = ancestor.parentElement;
             }
           }
@@ -4171,6 +4225,7 @@ catch (e) {
       preserveConditionalComponentScopes(b.el, capturedComponentScope);
       b.el.__stx_if_bound = true;
       b.el.__stx_chain_member = true;
+      b.el.__stx_chain_active = false;
       b.capturedElementScope = findElementScope(b.el);
       b.placeholder = document.createComment('stx-if-chain');
       parent.insertBefore(b.placeholder, b.el);
@@ -4270,12 +4325,14 @@ catch (e2) {
       // components under reactive conditionals (#1737). Permanent disposal is
       // still handled by bindFor (item removal) and cleanupContainer (SPA nav).
       if (currentIdx !== -1) {
+        chain[currentIdx].el.__stx_chain_active = false;
         chain[currentIdx].nodes.forEach(function (n) { if (n.parentNode) n.parentNode.removeChild(n); });
       }
 
       // Insert + process the newly-picked branch.
       if (pickedIdx !== -1) {
         var pick = chain[pickedIdx];
+        pick.el.__stx_chain_active = true;
         // Insert this branch's node(s) before the placeholder's next sibling.
         // The anchor is captured once so the nodes stack in source order.
         var anchor = pick.placeholder.nextSibling;
@@ -5474,6 +5531,11 @@ catch (e) {} }
     }
     var s = state(initial);
     if (!root) return s;
+    var propSignals = root.__stx_reactive_prop_signals
+      || (root.__stx_reactive_prop_signals = {});
+    propSignals[name] = s;
+    propSignals[kebabName] = s;
+    propSignals[lowerName] = s;
     var observer = new MutationObserver(function() {
       var attribute = readAttribute();
       var hasAttr = attribute.has;
@@ -5496,7 +5558,12 @@ catch (e) {} }
       if (next !== s()) s.set(next);
     });
     observer.observe(root, { attributes: true, attributeFilter: attributeNames });
-    onDestroy(function() { observer.disconnect(); });
+    onDestroy(function() {
+      observer.disconnect();
+      attributeNames.forEach(function(attributeName) {
+        if (propSignals[attributeName] === s) delete propSignals[attributeName];
+      });
+    });
     return s;
   }
 
@@ -7152,6 +7219,49 @@ else {
     });
     var pageScopeSnapshot = { ...componentScope };
 
+    /*
+     * Any x-data scope the reactive bridge did not reach, initialized here.
+     *
+     * The bridge script addresses each scope by a selector it generated, and
+     * that numbering restarts per render - so a page carrying three component
+     * islands emits three scripts all looking for the same scope id, and two of
+     * the three scopes are never initialized at all. The symptom is the
+     * quietest one available: the markup is there, every binding shows its
+     * initial value, and whatever x-init was meant to start never starts.
+     *
+     * Registered scopes are skipped, so the bridge stays authoritative where it
+     * did run and this only picks up what it missed. The init expression is
+     * read from data-stx-xinit, which the server preserves for exactly this.
+     *
+     * No backticks in this comment, deliberately: it lives inside the runtime
+     * source that is embedded as a template literal, and one would end the
+     * literal and take the whole file's syntax with it.
+     */
+    if (window.__stx_reactive && window.__stx_reactive.initScope) {
+      document.querySelectorAll('[data-stx-xdata]').forEach(function(el) {
+        var scopeId = el.getAttribute('data-stx-scope');
+        if (scopeId && window.stx._scopes && window.stx._scopes[scopeId]) return;
+        if (el.__stx_scope_initialized) return;
+
+        var xdata = el.getAttribute('data-stx-xdata');
+        if (!xdata) return;
+
+        if (!scopeId) {
+          scopeId = '__stx_scope_island_' + (++window.stx._scopeCounter);
+          el.setAttribute('data-stx-scope', scopeId);
+        }
+
+        el.__stx_scope_initialized = true;
+
+        try {
+          window.__stx_reactive.initScope(el, xdata, [], {}, el.getAttribute('data-stx-xinit') || null);
+        }
+        catch (e) {
+          console.error('[stx] island scope init error:', e);
+        }
+      });
+    }
+
     // Process mount queue (from stx.mount() calls during loading) only after
     // caller setup is available for Vue-style projected slot ownership.
     mountQueue.forEach(function(fn) { fn(); });
@@ -7516,7 +7626,11 @@ catch (e) {
     var walker = document.createTreeWalker(root, showText, null);
     var node;
     while ((node = walker.nextNode())) {
-      var text = node.nodeValue || '';
+      // Browsers expose Text.nodeValue as a string, while lightweight DOM and
+      // native embedding shims can preserve an assigned number. Diagnostics
+      // must normalize the boundary instead of aborting the entire audit on a
+      // missing String#indexOf method.
+      var text = node.nodeValue == null ? '' : String(node.nodeValue);
       if (text.indexOf('{{') === -1 || text.indexOf('}}') === -1) continue;
       if (auditSkipped(node)) continue;
       found.push(text.trim().slice(0, 80));
@@ -7772,8 +7886,14 @@ catch (e) { console.warn('[stx] destroy callback error:', e); }
           scopeId = '__stx_scope_spa_' + (++window.stx._scopeCounter);
           el.setAttribute('data-stx-scope', scopeId);
         }
+        // The init expression, which used to be dropped here. A scope
+        // re-initialized with its data and none of its setup renders every
+        // binding at its initial value and starts nothing - a live region
+        // showing its empty state forever, which is indistinguishable from one
+        // where nothing has happened yet.
+        var xinit = el.getAttribute('data-stx-xinit');
         console.log('[stx:load] initializing x-data scope:', scopeId, xdata.substring(0, 40));
-        window.__stx_reactive.initScope(el, xdata, [], {}, null);
+        window.__stx_reactive.initScope(el, xdata, [], {}, xinit || null);
       });
     }
 
@@ -7864,8 +7984,10 @@ catch (e) { console.warn('[stx] destroy callback error:', e); }
     if (el.nodeType !== Node.ELEMENT_NODE) return;
     // Skip scoped elements - they were already processed
     if (el.hasAttribute && el.hasAttribute('data-stx-scope')) return;
-    // Detached chain members are owned by bindIfChain \u2014 skip (#1734).
-    if (el.__stx_chain_member && !el.isConnected) return;
+    // Inactive chain members are owned by bindIfChain. Use explicit branch
+    // state because an active nested branch can live under a detached outer
+    // conditional while its reactive effects continue to run.
+    if (el.__stx_chain_member && !el.__stx_chain_active) return;
     // Process this element's directives without recursing into children
     // (we'll handle children manually to skip scoped ones)
     const hasFor = el.hasAttribute && (el.hasAttribute('@for') || el.hasAttribute(':for') || el.hasAttribute('x-for'));

package/dist/ssg.d.ts

@@ -46,6 +46,29 @@
 export interface SSGConfig {
     /** Directory containing pages (default: 'pages') */
     pagesDir?: string;
+    /**
+     * Directory `@include` resolves against. Defaults to the config's
+     * `partialsDir`.
+     *
+     * `pagesDir`, `publicDir` and `outputDir` were all overridable here and these
+     * two were not, so a caller could point the build at one directory layout and
+     * silently get another for its partials (stacksjs/stx#1921).
+     */
+    partialsDir?: string;
+    /** Directory components resolve against. Defaults to the config's `componentsDir`. */
+    componentsDir?: string;
+    /**
+     * Fail the build when an `@include` cannot be resolved (default: true).
+     *
+     * A failed include renders the error into the page and, before this, left the
+     * build reporting `Failed: 0` with exit 0 — so the only way to find it was to
+     * read the emitted HTML, which is exactly what nobody does when the build says
+     * success. An unresolvable include is not a recoverable condition in a build:
+     * it produces a file you would never knowingly deploy.
+     *
+     * Set `false` for the old behaviour.
+     */
+    failOnIncludeError?: boolean;
     /** Output directory for generated files (default: 'dist') */
     outputDir?: string;
     /** Base URL for the site (default: '/') */