@stacksjs/stx 0.2.174 → 0.2.176

package/dist/resolve-stx-targets.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Resolve whatever a user typed — a directory, a file, or a glob — to `.stx` files.
+ *
+ * The CLI commands disagreed about which of those they took, and each was silent
+ * about the shape it did not accept. `stx a11y` joined its argument into a scan
+ * pattern (`path.join(arg, '**' + '/*.stx')`), so a FILE path became
+ * `file.stx/**` + `/*.stx` and matched nothing, and a glob became
+ * `'x/**' + '/*.stx/**' + '/*.stx'` and also matched nothing. Both then took the
+ * empty branch, which printed
+ *
+ *     ✓ No accessibility issues found!
+ *
+ * and exited 0 — on a file with three SERIOUS findings. Meanwhile `typecheck`
+ * globbed and, handed a directory, said it matched nothing. Both halves
+ * inverted, and inverted silently in the direction that costs you: the natural
+ * way to add a checker to CI is to copy the line that already works, so
+ *
+ *     - run: stx a11y 'resources/**' + '/*.stx'
+ *
+ * passes on every commit for the life of the project, indistinguishable from a
+ * project with no accessibility problems (stacksjs/stx#1918).
+ *
+ * So there is one resolver and every command uses it. The separate half of that
+ * fix lives at the call sites and matters more: **an empty match set is not a
+ * pass.** A run that read no files has verified nothing, and has to say so.
+ *
+ * @module resolve-stx-targets
+ */
+/** Is this argument a glob pattern rather than a plain path? */
+export declare function looksLikeGlob(target: string): boolean;
+export interface ResolveStxTargetsOptions {
+    /** Directory to resolve relative targets against. Defaults to the cwd. */
+    cwd?: string;
+    /** Recurse into subdirectories when the target is a directory. Default true. */
+    recursive?: boolean;
+    /** Substrings that exclude a matched path. */
+    ignorePaths?: readonly string[];
+}
+/**
+ * Expand targets to absolute `.stx` file paths, de-duplicated and sorted.
+ *
+ * A named FILE is returned whether or not it ends in `.stx`: naming one is an
+ * explicit request, and silently dropping it is the failure this module exists
+ * to remove. Directories and globs are filtered to `.stx`.
+ *
+ * `node_modules` and `dist` are always excluded — a glob like `**` + `/*.stx`
+ * otherwise sweeps up every template in every installed package.
+ */
+export declare function resolveStxTargets(targets: readonly string[], options?: ResolveStxTargetsOptions): Promise<string[]>;

package/dist/resolve-stx-targets.js

@@ -0,0 +1,38 @@
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+const GLOB_MAGIC = /[*?[\]{}]/;
+export function looksLikeGlob(target) {
+  return GLOB_MAGIC.test(target);
+}
+export async function resolveStxTargets(targets, options = {}) {
+  const cwd = options.cwd ?? process.cwd(), recursive = options.recursive !== !1, ignorePaths = options.ignorePaths ?? [], Glob = globalThis.Bun.Glob, found = new Set, accept = (file) => {
+    if (file.includes(`${path.sep}node_modules${path.sep}`) || file.includes(`${path.sep}dist${path.sep}`))
+      return;
+    if (ignorePaths.some((ignore) => ignore && file.includes(path.normalize(ignore))))
+      return;
+    found.add(file);
+  }, scan = async (pattern) => {
+    try {
+      for await (const file of new Glob(pattern).scan({ cwd, absolute: !0 }))
+        accept(file);
+    } catch {}
+  };
+  for (const target of targets) {
+    if (!target)
+      continue;
+    if (looksLikeGlob(target)) {
+      await scan(target);
+      continue;
+    }
+    const absolute = path.resolve(cwd, target);
+    if (!existsSync(absolute))
+      continue;
+    if (statSync(absolute).isDirectory()) {
+      for await (const file of new Glob(recursive ? "**/*.stx" : "*.stx").scan({ cwd: absolute, absolute: !0 }))
+        accept(file);
+      continue;
+    }
+    accept(absolute);
+  }
+  return [...found].sort();
+}

package/dist/runtime-globals.d.ts

@@ -168,6 +168,30 @@ export declare function templateHasReactiveContext(template: string): boolean;
  * signal-processing.ts would close a cycle through client-script.ts.
  */
 export declare function templateNeedsRuntime(template: string): boolean;
+/**
+ * Colon attributes that are DIRECTIVES, not attribute bindings.
+ *
+ * `:href` and `:disabled` name a real HTML attribute and can be resolved to one.
+ * `:if`, `:for` and `:text` do not — they are instructions to the conditional
+ * processor, the loop runtime and the text binder, and the element carries no
+ * attribute of that name at any point.
+ *
+ * The distinction had never been written down, so `processServerBindings`
+ * evaluated every `:name="expr"` alike. It went unnoticed because its tag regex
+ * required each attribute chunk to start with whitespace and be a single
+ * character, so it never matched a real tag with a real attribute — the pass was
+ * effectively dead. Fixing that regex (0.2.173) switched it on for everything at
+ * once, and `<p :if="error">` started rendering as `<p if="Bad creds">`: the
+ * attribute leaked into the markup AND the conditional stopped applying, so a
+ * falsy condition no longer removed the element. Same for `:show`, `:text`,
+ * `:html`, `:model` and `:key`.
+ *
+ * `:class` and `:style` are deliberately absent: they DO resolve to real
+ * attributes, and `processServerBindings` has specific handling for them.
+ */
+export declare const RUNTIME_OWNED_COLON_ATTRS: readonly string[];
+/** Is this colon attribute a directive rather than something to resolve? */
+export declare function isRuntimeOwnedColonAttr(name: string): boolean;
 /**
  * `x-` attributes the signals runtime consumes itself.
  *

package/dist/runtime-globals.js

@@ -143,6 +143,22 @@ export function templateNeedsRuntime(template) {
     return !1;
   return HAS_EVENT_HANDLER.test(blankInertHtmlRegions(template)) || templateHasReactiveContext(template);
 }
+export const RUNTIME_OWNED_COLON_ATTRS = [
+  "if",
+  "else-if",
+  "elseif",
+  "else",
+  "for",
+  "show",
+  "key",
+  "text",
+  "html",
+  "model",
+  "ref"
+];
+export function isRuntimeOwnedColonAttr(name) {
+  return RUNTIME_OWNED_COLON_ATTRS.includes(name.toLowerCase());
+}
 export const RUNTIME_HANDLED_X_ATTRS = [
   "x-text",
   "x-html",

package/dist/runtime-injection.d.ts

@@ -72,6 +72,42 @@ export declare function outputNeedsSignalsRuntime(html: string): boolean;
  * The runtime provides client-side reactivity.
  */
 export declare function injectSignalsRuntime(template: string, options: StxOptions): Promise<string>;
+/**
+ * Whether the finished page has an element carrying `x-tooltip`.
+ *
+ * Asked of the OUTPUT rather than the source, for the reason
+ * `outputNeedsSignalsRuntime` is: both the attribute and every rewrite that
+ * could have produced it have happened by then, so no processing order can hide
+ * the answer.
+ *
+ * Anchored on `<` … so the name has to sit inside a tag: documentation prose
+ * that merely names the attribute does not pull a runtime onto the page. The
+ * attribute value is allowed to contain `>` — a tooltip reading `a > b` is
+ * ordinary — so the scan walks to the quote rather than to the first `>`.
+ */
+export declare function outputNeedsTooltipRuntime(html: string): boolean;
+/**
+ * Ship the `x-tooltip` runtime on any page that uses the attribute.
+ *
+ * `getTooltipRuntime()` was written, exported from `builtins/index.ts`, and
+ * called by nothing — two definitions and zero call sites, in stx and in
+ * `bun-plugin-stx`. `registerBuiltins()` registers ten builtins and tooltip is
+ * not one of them, so the attribute reached the DOM and nothing ever acted on
+ * it. Hovering showed the native `title` tooltip, which would have shown anyway
+ * (stacksjs/stx#1922).
+ *
+ * The dead export was not merely unused: the codemod's largest and only
+ * auto-fixable rule rewrites `title=` into `x-tooltip=`, so every consuming
+ * codebase was being pointed at an attribute that had never worked. It read as
+ * an adoption problem — `codemod.d.ts` records `x-tooltip` as "delivered and
+ * used zero times" — when the cause was that there was nothing to adopt.
+ *
+ * Not a registered builtin, because it is not a component: it is one delegated
+ * listener pair on `document`, so it costs nothing when no element matches and
+ * covers elements added later without per-element wiring. Injected only when the
+ * attribute is present, and before the CSP pass so a nonce still reaches it.
+ */
+export declare function injectTooltipRuntime(html: string): string;
 /**
  * Inject the SPA router script into the template.
  * The router is provided by the canonical router in packages/router/src/client.ts.

package/dist/runtime-injection.js

@@ -1,6 +1,7 @@
 import { getOwnedRouteMatchers } from "./owned-routes.js";
 import { toScriptJson } from "./script-json.js";
 import { findBodyOpenTag, replaceBodyOpenTag } from "./find-body-tag.js";
+import { getTooltipRuntime } from "./builtins/tooltip.js";
 export function injectBrowserRuntime(template) {
   if (template.includes("window.StacksBrowser") || template.includes("StacksBrowser ="))
     return template;
@@ -32,6 +33,7 @@ export function injectBrowserRuntime(template) {
     "clamp",
     "rand",
     "readableSize",
+    "useActiveElement",
     "useDocumentVisibility",
     "useIntervalFn"
   ].some((sym) => {
@@ -108,6 +110,19 @@ export async function injectSignalsRuntime(template, options) {
   const { getCachedSignalsRuntime } = await import("./caching.js"), runtime = await getCachedSignalsRuntime(options.debug);
   return placeRuntimeTag(template, `<script data-stx-scoped data-stx-runtime>${runtime}</script>`);
 }
+export function outputNeedsTooltipRuntime(html) {
+  return /<[a-z][^>]*?\sx-tooltip\s*=/i.test(html);
+}
+export function injectTooltipRuntime(html) {
+  if (html.includes("data-stx-tooltip-runtime") || !outputNeedsTooltipRuntime(html))
+    return html;
+  const tag = `<script data-stx-scoped data-stx-tooltip-runtime>${getTooltipRuntime()}</script>`, bodyIdx = html.lastIndexOf("</body>");
+  if (bodyIdx === -1)
+    return `${html}
+${tag}`;
+  return `${html.slice(0, bodyIdx)}${tag}
+${html.slice(bodyIdx)}`;
+}
 export async function injectRouterScript(template, options) {
   if (!template.includes("</body>"))
     return template;

package/dist/server-bindings.js

@@ -1,3 +1,4 @@
+import { isRuntimeOwnedColonAttr } from "./runtime-globals.js";
 const BOOLEAN_ATTRS = new Set([
   "disabled",
   "checked",
@@ -96,6 +97,8 @@ export function processServerBindings(template, context) {
     let attrMatch, newAttrs = attrs, hadReplacement = !1;
     while ((attrMatch = bindingRegex.exec(attrs)) !== null) {
       const attrName = attrMatch[1], expression = attrMatch[2];
+      if (isRuntimeOwnedColonAttr(attrName))
+        continue;
       if (expression.includes("()") && !expression.includes(".get(") || expression.includes("$store") || expression.includes("$ref"))
         continue;
       try {

package/dist/signal-processing.js

@@ -801,7 +801,7 @@ export function extractExports(setupContent) {
   }, checkDeclaration = () => {
     if (depth !== 0)
       return;
-    const declMatch = code.slice(i).match(/^(const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=/);
+    const declMatch = code.slice(i).match(/^(const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?:[!:;,\n]|=(?!=)|$)/);
     if (declMatch) {
       const varName = declMatch[2];
       if (!seen.has(varName)) {

package/dist/signals.js

@@ -1183,7 +1183,7 @@ else if (immediate) {
     var ownerScope = currentLifecycleScope() || componentScope;
     return {
       get current() {
-        return ownerScope.$refs ? ownerScope.$refs[name] : null;
+        return (ownerScope.$refs && ownerScope.$refs[name]) || null;
       },
       get value() {
         return this.current;
@@ -2769,12 +2769,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;
             }
           }
@@ -4367,33 +4371,30 @@ catch (e2) {
     }
 
     // Helper to evaluate with captured scope (auto-unwraps signals).
-    // Mirrors bindStyle/bindShow/evalAttrExpr: first try the auto-unwrap
-    // proxy (so a bare-reference comparison like count > 5 reads the signal
-    // as a primitive), then retry with the raw scope so call-syntax
-    // expressions like count() === 0 or !recording() still work. The proxy
-    // unwraps signals to their values, which turns count() into 0() ->
-    // TypeError; pre-fix (stacksjs/stx#1733) the single catch swallowed
-    // that TypeError and returned '' (falsy), silently hiding the element
-    // for EVERY comparison/boolean expression. bindIf was the only
-    // directive missing this retry.
+    // A with-scope resolves only identifiers the expression actually references,
+    // so the conditional subscribes narrowly instead of reading every signal
+    // in a component scope. That broad subscription made an unrelated ref
+    // update re-enter structural removal while the real condition was already
+    // removing the same subtree. First try the auto-unwrap proxy (so a bare
+    // comparison like count > 5 reads the signal value), then retry with the
+    // raw scope so call syntax like count() === 0 still works (#1733).
     const evalExpr = (expression) => {
       // Skip placeholder expressions like __TITLE__ (build-time placeholders)
       if (/^__[A-Z_]+__$/.test(expression.trim())) {
         return expression;
       }
       try {
-        // Use captured componentScope (with @for vars) merged with element scope
         const scope = { ...globalHelpers, ...capturedComponentScope, ...(capturedElementScope || {}) };
         const unwrapScope = createExpressionAutoUnwrapProxy(scope, expression);
-        const fn = new Function(...Object.keys(scope), 'return ' + expression);
-        return fn(...Object.values(unwrapScope));
+        const fn = new Function('__scope__', 'with(__scope__) { return ' + expression + ' }');
+        return fn(unwrapScope);
       }
 catch (e1) {
         try {
           // Retry without the unwrap proxy so call-syntax (signal()) works.
           const scope2 = { ...globalHelpers, ...capturedComponentScope, ...(capturedElementScope || {}) };
-          const fn2 = new Function(...Object.keys(scope2), 'return ' + expression);
-          return fn2(...Object.values(scope2));
+          const fn2 = new Function('__scope__', 'with(__scope__) { return ' + expression + ' }');
+          return fn2(scope2);
         }
 catch (e2) {
           if (!(e2 instanceof ReferenceError) && !(e2 instanceof TypeError)) console.warn('[STX] Expression error:', expression, e2);
@@ -4450,11 +4451,6 @@ catch (e2) {
         value = directSignal();
         console.log('[stx] bindIf effect (direct):', expr, '\u2192', value, 'isInserted:', isInserted);
       } else {
-        // Complex expression: read all signals first for tracking, then evaluate
-        for (var sk in fullScope) {
-          var sv = fullScope[sk];
-          if (sv && typeof sv === 'function' && (sv._isSignal || sv._isDerived)) sv();
-        }
         value = evalExpr(expr);
       }
 
@@ -4892,12 +4888,19 @@ else if (timer === null) {
     };
   }
 
-  // Queue work after the current synchronous signal/effect flush. This mirrors
-  // the Composition API nextTick contract and gives template refs a chance to
-  // resolve after a structural directive inserts their elements.
+  // Queue work after the current synchronous signal/effect flush and after
+  // structural directives finish their deferred subtree hydration. The
+  // microtask schedules this timer only after every subscriber has run, so a
+  // :if/:for timer created later in the same signal flush runs first and its
+  // template refs are available to the callback.
   function nextTick(fn) {
     return Promise.resolve().then(function() {
-      if (fn) fn();
+      return new Promise(function(resolve) {
+        setTimeout(function() {
+          if (fn) fn();
+          resolve();
+        }, 0);
+      });
     });
   }
 

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: '/') */