@stacksjs/stx 0.2.175 → 0.2.177

package/dist/typecheck.js

@@ -3,25 +3,42 @@ import path from "node:path";
 import { STX_RUNTIME_GLOBALS } from "./runtime-globals.js";
 import { stateDir } from "./state-dir.js";
 import {
+  absolutizeRelativeSpecifiers,
   buildVirtualTypeScript,
   extractScriptBlocks,
   resolvePosition,
   clientPayloadDeclarations,
   scrapedBridgeNames,
   serverContextDeclarations,
+  blankScriptDirectives,
   substituteInterpolationsInPlace
 } from "./stx-virtual-ts.js";
 export {
   extractScriptBlocks,
   extractTemplateExpressions
 } from "./stx-virtual-ts.js";
-export function buildVirtualSource(block, serverCode = "") {
+export function buildVirtualSource(block, serverCode = "", originDir = "") {
   const leadingNewlines = block.startLine > 1 ? `
-`.repeat(block.startLine - 1) : "", code = substituteInterpolationsInPlace(block.code), payload = block.kind === "client" || block.kind === "plain" ? clientPayloadDeclarations(serverCode) : "";
-  return `${leadingNewlines + code}
+`.repeat(block.startLine - 1) : "", code = blankScriptDirectives(substituteInterpolationsInPlace(block.code)), payload = block.kind === "client" || block.kind === "plain" ? clientPayloadDeclarations(serverCode, block.code) : "";
+  return absolutizeRelativeSpecifiers(`${leadingNewlines + code}
 ${payload}
 export {}
-`;
+`, originDir);
+}
+function virtualStxModuleDeclaration(files) {
+  const anchor = files.length > 0 ? path.dirname(path.resolve(files[0])) : process.cwd();
+  try {
+    Bun.resolveSync("@stacksjs/stx", anchor);
+  } catch {
+    return "";
+  }
+  return [
+    "// Generated \u2014 `stx` is the virtual specifier client-script.ts strips.",
+    "declare module 'stx' {",
+    "  export * from '@stacksjs/stx'",
+    "}"
+  ].join(`
+`);
 }
 export function virtualPathFor(filePath, kind, index) {
   return `${filePath}.__stx_${kind}${index}.ts`;
@@ -39,6 +56,9 @@ export function findRuntimeTypeDeclarations() {
   return null;
 }
 const TSC_LINE_RE = /^(.*?)\((\d+),(\d+)\):\s+(error|warning)\s+TS(\d+):\s+(.*)$/;
+function isSyntactic(code) {
+  return code >= 1000 && code < 2000;
+}
 function readProjectPathAliases(startDir) {
   let dir = path.resolve(startDir), configPath;
   for (;; ) {
@@ -130,17 +150,15 @@ export async function typecheckStxFiles(files, options = {}) {
     const source = await Bun.file(file).text(), blocks = extractScriptBlocks(source).filter((b) => {
       if (b.kind === "server")
         return checkServer;
-      if (b.kind === "client")
-        return checkClient;
-      return !1;
+      return checkClient;
     }), serverCode = extractScriptBlocks(source).filter((block) => block.kind === "server").map((block) => block.code).join(`
 `);
     if (checkClient && serverCode) {
-      const clientBlocks = blocks.filter((block) => block.kind === "client"), names = [...new Set(clientBlocks.flatMap((block) => scrapedBridgeNames(serverCode, block.code)))];
+      const clientBlocks = blocks.filter((block) => block.kind !== "server"), names = [...new Set(clientBlocks.flatMap((block) => scrapedBridgeNames(serverCode, block.code)))];
       if (names.length > 0)
-        scrapedByFile.set(file, { names, line: clientBlocks[0].startLine });
+        scrapedByFile.set(file, { names, line: clientBlocks[0].startLine, kind: clientBlocks[0].kind });
     }
-    const templateBuffer = checkTemplates ? buildVirtualTypeScript(source, { runtimeGlobals: !runtimeTypes }) : null, expressions = templateBuffer ? [...templateBuffer.lineMap.values()].filter((m) => m.expression).length : 0;
+    const originDir = path.dirname(path.resolve(file)), templateBuffer = checkTemplates ? buildVirtualTypeScript(source, { runtimeGlobals: !runtimeTypes, originDir }) : null, expressions = templateBuffer ? [...templateBuffer.lineMap.values()].filter((m) => m.expression).length : 0;
     if (blocks.length === 0 && expressions === 0)
       continue;
     checkedFiles.push(file);
@@ -148,7 +166,7 @@ export async function typecheckStxFiles(files, options = {}) {
     expressionCount += expressions;
     blocks.forEach((block, i) => {
       virtualFiles.set(virtualPathFor(file, block.kind, i), {
-        source: buildVirtualSource(block, serverCode),
+        source: buildVirtualSource(block, serverCode, originDir),
         origin: file,
         kind: block.kind
       });
@@ -169,8 +187,9 @@ export async function typecheckStxFiles(files, options = {}) {
   const globalsDts = `${stateDir()}/typecheck/__stx_globals.d.ts`, globalDecls = [
     "// Generated \u2014 the context serve.ts injects into <script server> blocks.",
     serverContextDeclarations(),
-    ...runtimeTypes ? [] : ["declare const window: any", ...STX_RUNTIME_GLOBALS.map((name) => `declare const ${name}: any`)]
-  ].join(`
+    ...runtimeTypes ? [] : ["declare const window: any", ...STX_RUNTIME_GLOBALS.map((name) => `declare const ${name}: any`)],
+    virtualStxModuleDeclaration(files)
+  ].filter(Boolean).join(`
 `), workDir = `${stateDir()}/typecheck`;
   await Bun.$`rm -rf ${workDir}`.quiet().nothrow();
   await Bun.$`mkdir -p ${workDir}`.quiet().nothrow();
@@ -182,64 +201,80 @@ export async function typecheckStxFiles(files, options = {}) {
     await Bun.write(`${workDir}/${safe}`, meta.source);
     writtenToOrigin.set(safe, meta);
   }
-  const tsconfig = {
-    compilerOptions: {
-      target: "ESNext",
-      module: "ESNext",
-      moduleResolution: "bundler",
-      strict: !0,
-      noEmit: !0,
-      skipLibCheck: !0,
-      allowJs: !0,
-      esModuleInterop: !0,
-      resolveJsonModule: !0,
-      lib: ["ESNext", "DOM", "DOM.Iterable"],
-      types: [],
-      ...readProjectPathAliases(files.length > 0 ? path.dirname(path.resolve(files[0])) : process.cwd()),
-      ...options.compilerOptions ?? {}
-    },
-    files: [...writtenToOrigin.keys()].map((name) => `${workDir}/${name}`).concat(globalsDts, ...ambient)
-  }, tsconfigPath = `${workDir}/tsconfig.json`;
-  await Bun.write(tsconfigPath, JSON.stringify(tsconfig, null, 2));
-  const proc = Bun.spawnSync(["bun", "x", "tsc", "-p", tsconfigPath, "--pretty", "false"], {
-    stdout: "pipe",
-    stderr: "pipe"
-  }), output = new TextDecoder().decode(proc.stdout) + new TextDecoder().decode(proc.stderr), diagnostics = [], exitCode = proc.exitCode ?? 0;
+  const compilerOptions = {
+    target: "ESNext",
+    module: "ESNext",
+    moduleResolution: "bundler",
+    strict: !0,
+    noEmit: !0,
+    skipLibCheck: !0,
+    allowJs: !0,
+    esModuleInterop: !0,
+    resolveJsonModule: !0,
+    lib: ["ESNext", "DOM", "DOM.Iterable"],
+    types: [],
+    ...readProjectPathAliases(files.length > 0 ? path.dirname(path.resolve(files[0])) : process.cwd()),
+    ...options.compilerOptions ?? {}
+  }, runTsc = async (names, pass) => {
+    const tsconfigPath = `${workDir}/tsconfig${pass === 1 ? "" : `.${pass}`}.json`;
+    await Bun.write(tsconfigPath, JSON.stringify({
+      compilerOptions,
+      files: names.map((name) => `${workDir}/${name}`).concat(globalsDts, ...ambient)
+    }, null, 2));
+    const proc = Bun.spawnSync(["bun", "x", "tsc", "-p", tsconfigPath, "--pretty", "false"], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    return {
+      output: new TextDecoder().decode(proc.stdout) + new TextDecoder().decode(proc.stderr),
+      exitCode: proc.exitCode ?? 0
+    };
+  }, first = await runTsc([...writtenToOrigin.keys()], 1), output = first.output, diagnostics = [], exitCode = first.exitCode;
   let printedDiagnostics = 0;
   const ambientBasenames = new Set(ambient.map((lib) => lib.split("/").pop()));
   let ambientDiagnostics = 0;
-  for (const rawLine of output.split(`
+  const unparseable = new Set, parseTscOutput = (text) => {
+    for (const rawLine of text.split(`
 `)) {
-    const m = rawLine.match(TSC_LINE_RE);
-    if (!m)
-      continue;
-    printedDiagnostics++;
-    if (ambientBasenames.has(m[1].split("/").pop()))
-      ambientDiagnostics++;
-    const [, filePart, lineStr, colStr, category, code, message] = m, entry = writtenToOrigin.get(filePart.split("/").pop());
-    if (!entry)
-      continue;
-    let line = Number(lineStr), column = Number(colStr), expression;
-    if (entry.virtual) {
-      const at = resolvePosition(entry.virtual, line, column);
-      if (!at?.expression)
+      const m = rawLine.match(TSC_LINE_RE);
+      if (!m)
         continue;
-      if (Number(code) === 2774)
+      printedDiagnostics++;
+      if (ambientBasenames.has(m[1].split("/").pop()))
+        ambientDiagnostics++;
+      const [, filePart, lineStr, colStr, category, code, message] = m, written = filePart.split("/").pop(), entry = writtenToOrigin.get(written);
+      if (!entry)
         continue;
-      line = at.line;
-      column = at.column;
-      expression = at.expression.code.trim();
+      if (isSyntactic(Number(code)))
+        unparseable.add(written);
+      let line = Number(lineStr), column = Number(colStr), expression;
+      if (entry.virtual) {
+        const at = resolvePosition(entry.virtual, line, column);
+        if (!at?.expression)
+          continue;
+        if (Number(code) === 2774)
+          continue;
+        line = at.line;
+        column = at.column;
+        expression = at.expression.code.trim();
+      }
+      diagnostics.push({
+        file: entry.origin,
+        line,
+        column,
+        code: Number(code),
+        message,
+        category: category === "error" ? "error" : "warning",
+        blockKind: entry.kind,
+        expression
+      });
     }
-    diagnostics.push({
-      file: entry.origin,
-      line,
-      column,
-      code: Number(code),
-      message,
-      category: category === "error" ? "error" : "warning",
-      blockKind: entry.kind,
-      expression
-    });
+  };
+  parseTscOutput(output);
+  const firstPassPrinted = printedDiagnostics, firstPassAmbient = ambientDiagnostics;
+  if (unparseable.size > 0 && unparseable.size < writtenToOrigin.size) {
+    const survivors = [...writtenToOrigin.keys()].filter((name) => !unparseable.has(name));
+    parseTscOutput((await runTsc(survivors, 2)).output);
   }
   if (checkClient)
     for (const [file, scraped] of scrapedByFile) {
@@ -252,7 +287,7 @@ export async function typecheckStxFiles(files, options = {}) {
         code: 0,
         message: `${scraped.names.length === 1 ? "1 value reaches" : `${scraped.names.length} values reach`} this block on the implicit bridge and ${scraped.names.length === 1 ? "is" : "are"} untyped: ${scraped.names.join(", ")}. Declare them with defineClientPayload({ ${scraped.names.join(", ")} }) in the server block to have them checked.`,
         category: "warning",
-        blockKind: "client"
+        blockKind: scraped.kind
       });
     }
   const seen = new Set, unique = diagnostics.filter((d) => {
@@ -263,7 +298,7 @@ export async function typecheckStxFiles(files, options = {}) {
     return !0;
   });
   unique.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
-  const brokenLib = ambientDiagnostics > 0 && unique.length === 0, failure = brokenLib || exitCode !== 0 && printedDiagnostics === 0 ? `${brokenLib ? "a file passed with --lib has errors of its own, so nothing in your code was checked" : `tsc exited ${exitCode} without reporting any diagnostic, so nothing was checked`}. ` + "A syntax error in an ambient declaration file does this \u2014 skipLibCheck suppresses " + `SEMANTIC diagnostics only. tsc said:
+  const brokenLib = firstPassAmbient > 0 && unique.length === 0, failure = brokenLib || exitCode !== 0 && firstPassPrinted === 0 ? `${brokenLib ? "a file passed with --lib has errors of its own, so nothing in your code was checked" : `tsc exited ${exitCode} without reporting any diagnostic, so nothing was checked`}. ` + "A syntax error in an ambient declaration file does this \u2014 skipLibCheck suppresses " + `SEMANTIC diagnostics only. tsc said:
 ${output.trim().split(`
 `).slice(0, 12).join(`
 `) || "(no output)"}` : void 0;
@@ -271,7 +306,7 @@ ${output.trim().split(`
 }
 export function formatTypecheckDiagnostics(diagnostics) {
   return diagnostics.map((d) => {
-    const where = d.blockKind === "template" ? `[template: ${d.expression ?? ""}]` : `[<script ${d.blockKind}>]`;
+    const where = d.blockKind === "template" ? `[template: ${d.expression ?? ""}]` : `[${d.blockKind === "plain" ? "<script>" : `<script ${d.blockKind}>`}]`;
     return `${d.file}:${d.line}:${d.column}  ${d.category} TS${d.code}  ${d.message}  ${where}`;
   }).join(`
 `);

package/dist/types/config-types.d.ts

@@ -594,6 +594,30 @@ export interface StxConfig {
     enabled: boolean;
     /** Path to partials directory, defaults to 'partials' in the same directory as the template */
     partialsDir: string;
+    /**
+     * Called when an `@include` fails, instead of the failure being silent.
+     *
+     * A failed include renders the error where the markup should have been. In dev
+     * that is the right call — you see it as soon as you look. In a build it
+     * produces a file nobody would knowingly deploy, and nothing else can see it:
+     * one app shipped pre-rendered pages whose header, footer, hero and CTA were
+     * all replaced by an ENOENT banner while the build printed `Failed: 0` and
+     * exited 0 (stacksjs/stx#1921).
+     *
+     * The rendered output is unchanged — this only carries the fact out, so a
+     * caller that builds files can decide to fail. `partialsDir` is included
+     * because "it looked in the wrong place" is the usual cause and the resolved
+     * path is what makes it a ten-second fix.
+     */
+    onIncludeError?: (failure: {
+        /** The path as written in the directive, e.g. `Bench/ConfirmHost`. */
+        includePath: string;
+        /** The template the directive appeared in. */
+        templatePath: string;
+        message: string;
+        /** The directory the include was resolved against. */
+        partialsDir: string;
+    }) => void;
     /** Path to components directory, defaults to 'components' in the same directory as the template */
     componentsDir: string;
     /** @internal Configured component root retained while nested components resolve locally. */

package/dist/utils.js

@@ -558,7 +558,8 @@ ${triedPaths.map((p) => `  - ${p}`).join(`
     const internalKeysToPreserve = new Set([
       "__originalFilePath",
       "__importedComponents",
-      COMPONENT_CLIENT_FACTORIES_CONTEXT_KEY
+      COMPONENT_CLIENT_FACTORIES_CONTEXT_KEY,
+      "__stx_client_signal_names"
     ]), filteredParentContext = {};
     for (const [key, val] of Object.entries(parentContext))
       if (!key.startsWith("__") || internalKeysToPreserve.has(key))
@@ -648,9 +649,9 @@ ${triedPaths.map((p) => `  - ${p}`).join(`
       templateContent = templateContent.replace(/\{\{\s*text\s*\|\|\s*slot\s*\}\}/g, () => slotContent);
     const { applySlots } = await importOnce("stx/slots", () => import("./slots.js")), { defaultSlot, namedSlots } = parsedSlotContent;
     templateContent = await applySlots(templateContent, defaultSlot, namedSlots, componentContext);
-    const hasSignalScripts = clientScripts.some((s) => /\b(?:state|derived|effect|ref|reactive|computed|watch|watchEffect|useReactiveProp|defineProps|withDefaults|defineEmits|defineExpose|defineSlots)\s*(?:<[^<>()]*>)?\s*\(/.test(s)), clientSignalNames = componentClientSignalNames(clientScripts);
-    if (clientSignalNames.length > 0)
-      componentContext.__stx_client_signal_names = clientSignalNames;
+    const hasSignalScripts = clientScripts.some((s) => /\b(?:state|derived|effect|ref|reactive|computed|watch|watchEffect|useReactiveProp|defineProps|withDefaults|defineEmits|defineExpose|defineSlots)\s*(?:<[^<>()]*>)?\s*\(/.test(s)), clientSignalNames = componentClientSignalNames(clientScripts), inheritedClientSignalNames = Array.isArray(componentContext.__stx_client_signal_names) ? componentContext.__stx_client_signal_names : [];
+    if (clientSignalNames.length > 0 || inheritedClientSignalNames.length > 0)
+      componentContext.__stx_client_signal_names = [...new Set([...inheritedClientSignalNames, ...clientSignalNames])];
     const componentOptions = {
       ...options,
       _rootComponentsDir: options._rootComponentsDir || options.componentsDir,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/stx",
   "type": "module",
-  "version": "0.2.175",
+  "version": "0.2.177",
   "description": "A performant UI Framework. Powered by Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -117,12 +117,12 @@
   "dependencies": {
     "@cwcss/crosswind": "^0.2.14",
     "@stacksjs/clapp": "^0.2.0",
-    "@stacksjs/desktop": "0.2.175",
-    "@stacksjs/sanitizer": "0.2.175",
+    "@stacksjs/desktop": "0.2.177",
+    "@stacksjs/sanitizer": "0.2.177",
     "@stacksjs/ts-i18n": "^0.1.11",
-    "bun-plugin-stx": "0.2.175",
+    "bun-plugin-stx": "0.2.177",
     "bunfig": "^0.15.17",
-    "stx-router": "0.2.175",
+    "stx-router": "0.2.177",
     "ts-broadcasting": "^0.0.9",
     "ts-images": "^0.1.9",
     "ts-syntax-highlighter": "^0.2.1"

package/stx.d.ts

@@ -199,11 +199,42 @@ declare function useSearchParams(): {
 // Data fetching
 // ============================================================================
 
-interface StxQueryResult<T> {
+/** How one run of a request should behave. */
+interface StxRefetchOptions {
+  /**
+   * Refresh without touching `loading` or clearing the current error.
+   *
+   * A poll refreshes data that is already on screen, so driving the first-load
+   * state from it puts a spinner over a populated view on every tick — the
+   * reason a polling view could not use these primitives at all (#1929). Bind
+   * `isFetching` for a subtle in-flight indicator instead.
+   */
+  background?: boolean
+}
+
+interface StxFetchResult<T> {
   data: StxSignal<T | null>
+  /** True while a first-load request is in flight. A background one leaves it alone. */
   loading: StxSignal<boolean>
+  /** True while ANY request is in flight, background ones included. */
+  isFetching: StxSignal<boolean>
   error: StxSignal<Error | null>
-  refetch: () => Promise<void>
+  refetch: (_options?: StxRefetchOptions) => Promise<void>
+}
+
+/*
+ * `useQuery` returns more than `useFetch` does, and declaring one shape for
+ * both hid it: `isStale` and `invalidate` existed at runtime and were invisible
+ * to the type, so reading either was an error on a value that was really there
+ * (#1929). Extending rather than widening the shared interface, because the
+ * inverse mistake is worse — declaring `invalidate` on `useFetch` would
+ * type-check a call to something that is undefined at runtime.
+ */
+interface StxQueryResult<T> extends StxFetchResult<T> {
+  /** True when cached data is on screen while a revalidation runs. */
+  isStale: StxSignal<boolean>
+  /** Drop this key from the cache and refetch. */
+  invalidate: (_options?: StxRefetchOptions) => Promise<void>
 }
 
 interface StxMutationResult<T> {
@@ -213,7 +244,7 @@ interface StxMutationResult<T> {
   mutate: (body?: unknown) => Promise<T>
 }
 
-declare function useFetch<T = any>(_url: string, _options?: any): StxQueryResult<T>
+declare function useFetch<T = any>(_url: string, _options?: any): StxFetchResult<T>
 declare function useQuery<T = any>(_url: string, _options?: any): StxQueryResult<T>
 declare function useMutation<T = any>(_url: string, _options?: any): StxMutationResult<T>
 
@@ -271,17 +302,45 @@ declare function useOptimistic<T = any, A = any>(
 // DOM utilities
 // ============================================================================
 
+/**
+ * Options the runtime reads, including the target it binds to.
+ *
+ * The target travels HERE rather than in a leading parameter, because that is
+ * what the implementation does: `var target = (options && options.target) || window`.
+ */
+interface StxEventListenerOptions {
+  /** Element, selector, or document/window. Defaults to `window`. */
+  target?: Window | Document | HTMLElement | string | null
+  capture?: boolean
+  passive?: boolean
+  once?: boolean
+}
+
+/*
+ * Event first, then handler, then options (stacksjs/stx#1923).
+ *
+ * This was declared target-first while the runtime has always been
+ * event-first, so the two disagreed in the worst possible direction: `_target`
+ * accepted `string`, so the CORRECT call got as far as reading 'keydown' as a
+ * selector before failing on the handler, and an author who trusted the type
+ * and added a target wrote `useEventListener(window, 'keydown', fn)` — which
+ * binds an event named "window" with the string 'keydown' as its handler, and
+ * silently attaches nothing.
+ *
+ * `browser-composables.ts` had it right all along; the package shipped two
+ * declarations of one name with different arities and the registry got the
+ * wrong one. Same shape as the `reactive` split: one name, two conventions, and
+ * no way for the call site to tell which it has.
+ */
 declare function useEventListener<K extends keyof WindowEventMap>(
-  _target: Window | Document | HTMLElement | string | null,
   _event: K,
   _handler: (event: WindowEventMap[K]) => void,
-  _options?: boolean | AddEventListenerOptions,
+  _options?: StxEventListenerOptions,
 ): StxCleanup
 declare function useEventListener(
-  _target: Window | Document | HTMLElement | string | null,
   _event: string,
   _handler: (event: Event) => void,
-  _options?: boolean | AddEventListenerOptions,
+  _options?: StxEventListenerOptions,
 ): StxCleanup
 declare function useScrollLock(
   _target?: HTMLElement | null | { current?: HTMLElement | null, value?: HTMLElement | null } | (() => HTMLElement | null | undefined),