@stacksjs/stx 0.2.154 → 0.2.156

package/dist/template-tag-balance.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Dev-mode template tag-balance check (stacksjs/stx#1769).
+ *
+ * A single dropped closing tag (e.g. a missing `</div>`) is silently
+ * auto-closed by the HTML parser at EOF, re-parenting every following sibling
+ * INSIDE the unclosed element. Those siblings then inherit the element's
+ * `x-show`/`display:none` state and render blank — with zero diagnostics at any
+ * layer (the server 200s, hydration succeeds, no console output). The failure
+ * is purely structural and only visible by eye.
+ *
+ * This does a coarse, void- and optional-close-aware open/close COUNT per tag
+ * name and reports any mismatch. It intentionally does not attempt a full HTML
+ * parse: the goal is a cheap, high-signal dev heads-up, not a validator.
+ */
+export interface TagBalanceIssue {
+    /** Tag name as written (case preserved, so `<Icon>`/`</Icon>` match). */
+    tag: string;
+    opened: number;
+    closed: number;
+    /** 1-based line of the first opening tag of this name (best-effort). */
+    firstOpenLine: number;
+}
 /**
  * Return the set of tag names whose opening/closing counts don't balance.
  * Pure and side-effect free.
@@ -8,9 +30,3 @@ export declare function findUnbalancedTags(template: string): TagBalanceIssue[];
  * diagnostic must never throw and break the build.
  */
 export declare function warnUnbalancedTags(template: string, filePath: string): void;
-export declare interface TagBalanceIssue {
-  tag: string
-  opened: number
-  closed: number
-  firstOpenLine: number
-}

package/dist/transitions.d.ts

@@ -1,3 +1,69 @@
+/**
+ * STX Transitions
+ *
+ * Vue-inspired transition system for enter/leave animations.
+ * Supports CSS transitions, CSS animations, and JavaScript hooks.
+ *
+ * @module transitions
+ *
+ * @example
+ * ```html
+ * @transition(name: 'fade')
+ *   @if (visible)
+ *     <div class="modal">Content</div>
+ *   @endif
+ * @endtransition
+ * ```
+ *
+ * CSS classes applied:
+ * - `.fade-enter-from` - Starting state for enter
+ * - `.fade-enter-active` - Active state during enter
+ * - `.fade-enter-to` - Ending state for enter
+ * - `.fade-leave-from` - Starting state for leave
+ * - `.fade-leave-active` - Active state during leave
+ * - `.fade-leave-to` - Ending state for leave
+ */
+export interface TransitionOptions {
+    /** Transition name (used for CSS class prefix) */
+    name?: string;
+    /** Duration in milliseconds */
+    duration?: number | {
+        enter: number;
+        leave: number;
+    };
+    /** CSS transition timing function */
+    easing?: string;
+    /** Transition mode: 'in-out' or 'out-in' */
+    mode?: 'in-out' | 'out-in' | 'default';
+    /** Use CSS animations instead of transitions */
+    css?: boolean;
+    /** Custom enter class */
+    enterClass?: string;
+    /** Custom enter-active class */
+    enterActiveClass?: string;
+    /** Custom enter-to class */
+    enterToClass?: string;
+    /** Custom leave class */
+    leaveClass?: string;
+    /** Custom leave-active class */
+    leaveActiveClass?: string;
+    /** Custom leave-to class */
+    leaveToClass?: string;
+    /** JavaScript hooks */
+    onBeforeEnter?: (el: Element) => void;
+    onEnter?: (el: Element, done: () => void) => void;
+    onAfterEnter?: (el: Element) => void;
+    onEnterCancelled?: (el: Element) => void;
+    onBeforeLeave?: (el: Element) => void;
+    onLeave?: (el: Element, done: () => void) => void;
+    onAfterLeave?: (el: Element) => void;
+    onLeaveCancelled?: (el: Element) => void;
+}
+export interface TransitionState {
+    isEntering: boolean;
+    isLeaving: boolean;
+    isCancelled: boolean;
+}
 /**
  * Perform an enter transition on an element.
  */
@@ -31,58 +97,3 @@ export declare function generateTransitionRuntime(): string;
  *   <div @transition.slide-up.300="isOpen">Content</div>
  */
 export declare function processTransitionAttributes(template: string): string;
-/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
-/**
- * STX Transitions
- *
- * Vue-inspired transition system for enter/leave animations.
- * Supports CSS transitions, CSS animations, and JavaScript hooks.
- *
- * @module transitions
- *
- * @example
- * ```html
- * @transition(name: 'fade')
- *   @if (visible)
- *     <div class="modal">Content</div>
- *   @endif
- * @endtransition
- * ```
- *
- * CSS classes applied:
- * - `.fade-enter-from` - Starting state for enter
- * - `.fade-enter-active` - Active state during enter
- * - `.fade-enter-to` - Ending state for enter
- * - `.fade-leave-from` - Starting state for leave
- * - `.fade-leave-active` - Active state during leave
- * - `.fade-leave-to` - Ending state for leave
- */
-// =============================================================================
-// Types
-// =============================================================================
-export declare interface TransitionOptions {
-  name?: string
-  duration?: number | { enter: number; leave: number }
-  easing?: string
-  mode?: 'in-out' | 'out-in' | 'default'
-  css?: boolean
-  enterClass?: string
-  enterActiveClass?: string
-  enterToClass?: string
-  leaveClass?: string
-  leaveActiveClass?: string
-  leaveToClass?: string
-  onBeforeEnter?: (el: Element) => void
-  onEnter?: (el: Element, done: () => void) => void
-  onAfterEnter?: (el: Element) => void
-  onEnterCancelled?: (el: Element) => void
-  onBeforeLeave?: (el: Element) => void
-  onLeave?: (el: Element, done: () => void) => void
-  onAfterLeave?: (el: Element) => void
-  onLeaveCancelled?: (el: Element) => void
-}
-export declare interface TransitionState {
-  isEntering: boolean
-  isLeaving: boolean
-  isCancelled: boolean
-}

package/dist/typecheck.d.ts

@@ -0,0 +1,77 @@
+import { extractScriptBlocks } from './stx-virtual-ts';
+import type { ScriptBlock, ScriptKind } from './stx-virtual-ts';
+export type { ScriptBlock, ScriptKind } from './stx-virtual-ts';
+/**
+ * Build the virtual TypeScript source for one block.
+ *
+ * The body is prefixed with blank lines so its first line lands on the same line
+ * number it occupies in the `.stx` file — which makes every diagnostic's line
+ * number directly usable with no mapping table.
+ *
+ * The trailing `export {}` makes the buffer a MODULE, and that is load-bearing.
+ * Without it a block with no imports is a global script, so every top-level
+ * declaration collides with the DOM lib: `const name = …` and `const status = …`
+ * in a `<script server>` block both reported "Cannot redeclare block-scoped
+ * variable", and those are ordinary names for server-rendered page data. It is
+ * appended rather than prepended so the line numbers above it are untouched.
+ */
+export declare function buildVirtualSource(block: ScriptBlock): string;
+/** Virtual path for a block, stable and traceable back to its origin. */
+export declare function virtualPathFor(filePath: string, kind: DiagnosticOrigin, index: number): string;
+/** Map a virtual path back to the `.stx` file it came from. */
+export declare function sourcePathFor(virtualPath: string): string;
+/**
+ * Locate the package's own `stx.d.ts`, which types the runtime globals.
+ *
+ * Checked rather than assumed: this module runs from `src/` in the repo and
+ * from `dist/` when installed, and both sit one level under the package root.
+ * Returns `null` when it is genuinely absent so the caller can fall back rather
+ * than hand tsc a path to nothing.
+ */
+export declare function findRuntimeTypeDeclarations(): string | null;
+/**
+ * Type-check `.stx` files.
+ *
+ * Runs the `tsc` BINARY over generated virtual files rather than driving the
+ * compiler API. TypeScript 7 ships as a Go port whose npm package exposes only
+ * `version` — no `createProgram`, no `ScriptTarget` — so an API-based checker
+ * would work on TS 5 and break on the version this repo actually resolves.
+ * Shelling out works across both.
+ *
+ * TypeScript is not a declared dependency: anyone running a type-check already
+ * has it, and making the package depend on a compiler to serve a page would be
+ * the wrong trade.
+ */
+export declare function typecheckStxFiles(files: string[], options?: TypecheckOptions): Promise<TypecheckResult>;
+/** Render diagnostics the way a CLI should: file:line:col, then the message. */
+export declare function formatTypecheckDiagnostics(diagnostics: TypecheckDiagnostic[]): string;
+export declare interface TypecheckDiagnostic {
+  file: string
+  line: number
+  column: number
+  code: number
+  message: string
+  category: 'error' | 'warning' | 'suggestion' | 'message'
+  blockKind: DiagnosticOrigin
+  expression?: string
+}
+export declare interface TypecheckOptions {
+  extraLibs?: string[]
+  client?: boolean
+  server?: boolean
+  templates?: boolean
+  compilerOptions?: Record<string, unknown>
+}
+export declare interface TypecheckResult {
+  diagnostics: TypecheckDiagnostic[]
+  checkedFiles: string[]
+  blockCount: number
+  expressionCount: number
+}
+/** Where a diagnostic came from: a script block, or the markup itself. */
+export type DiagnosticOrigin = ScriptKind | 'template';
+export {
+  extractScriptBlocks,
+  extractTemplateExpressions,
+  type TemplateExpression,
+} from './stx-virtual-ts';

package/dist/typecheck.js

@@ -0,0 +1,156 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { STX_RUNTIME_GLOBALS } from "./runtime-globals.js";
+import { stateDir } from "./state-dir.js";
+import {
+  buildVirtualTypeScript,
+  extractScriptBlocks,
+  resolvePosition,
+  serverContextDeclarations
+} from "./stx-virtual-ts.js";
+export {
+  extractScriptBlocks,
+  extractTemplateExpressions
+} from "./stx-virtual-ts.js";
+export function buildVirtualSource(block) {
+  return `${(block.startLine > 1 ? `
+`.repeat(block.startLine - 1) : "") + block.code}
+export {}
+`;
+}
+export function virtualPathFor(filePath, kind, index) {
+  return `${filePath}.__stx_${kind}${index}.ts`;
+}
+export function sourcePathFor(virtualPath) {
+  return virtualPath.replace(/\.__stx_(?:server|client|plain|template)\d+\.ts$/, "");
+}
+export function findRuntimeTypeDeclarations() {
+  for (const candidate of [
+    path.resolve(import.meta.dir, "..", "stx.d.ts"),
+    path.resolve(import.meta.dir, "..", "..", "stx.d.ts")
+  ])
+    if (existsSync(candidate))
+      return candidate;
+  return null;
+}
+const TSC_LINE_RE = /^(.*?)\((\d+),(\d+)\):\s+(error|warning)\s+TS(\d+):\s+(.*)$/;
+export async function typecheckStxFiles(files, options = {}) {
+  const checkClient = options.client !== !1, checkServer = options.server !== !1, checkTemplates = options.templates !== !1, virtualFiles = new Map, checkedFiles = [];
+  let blockCount = 0, expressionCount = 0;
+  const runtimeTypes = findRuntimeTypeDeclarations();
+  for (const file of files) {
+    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;
+    }), templateBuffer = checkTemplates ? buildVirtualTypeScript(source, { runtimeGlobals: !runtimeTypes }) : null, expressions = templateBuffer ? [...templateBuffer.lineMap.values()].filter((m) => m.expression).length : 0;
+    if (blocks.length === 0 && expressions === 0)
+      continue;
+    checkedFiles.push(file);
+    blockCount += blocks.length;
+    expressionCount += expressions;
+    blocks.forEach((block, i) => {
+      virtualFiles.set(virtualPathFor(file, block.kind, i), {
+        source: buildVirtualSource(block),
+        origin: file,
+        kind: block.kind
+      });
+    });
+    if (templateBuffer && expressions > 0)
+      virtualFiles.set(virtualPathFor(file, "template", 0), {
+        source: templateBuffer.text,
+        origin: file,
+        kind: "template",
+        virtual: templateBuffer
+      });
+  }
+  if (virtualFiles.size === 0)
+    return { diagnostics: [], checkedFiles, blockCount: 0, expressionCount: 0 };
+  const ambient = [...options.extraLibs ?? []];
+  if (runtimeTypes)
+    ambient.push(runtimeTypes);
+  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(`
+`), workDir = `${stateDir()}/typecheck`;
+  await Bun.$`rm -rf ${workDir}`.quiet().nothrow();
+  await Bun.$`mkdir -p ${workDir}`.quiet().nothrow();
+  await Bun.write(globalsDts, globalDecls);
+  const writtenToOrigin = new Map;
+  let counter = 0;
+  for (const [virtualPath, meta] of virtualFiles) {
+    const safe = `${counter++}_${virtualPath.replace(/[^\w.-]+/g, "_")}`;
+    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: [],
+      ...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 = [];
+  for (const rawLine of output.split(`
+`)) {
+    const m = rawLine.match(TSC_LINE_RE);
+    if (!m)
+      continue;
+    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)
+        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
+    });
+  }
+  const seen = new Set, unique = diagnostics.filter((d) => {
+    const key = `${d.file}:${d.line}:${d.column}:${d.code}:${d.message}`;
+    if (seen.has(key))
+      return !1;
+    seen.add(key);
+    return !0;
+  });
+  unique.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
+  return { diagnostics: unique, checkedFiles, blockCount, expressionCount };
+}
+export function formatTypecheckDiagnostics(diagnostics) {
+  return diagnostics.map((d) => {
+    const where = d.blockKind === "template" ? `[template: ${d.expression ?? ""}]` : `[<script ${d.blockKind}>]`;
+    return `${d.file}:${d.line}:${d.column}  ${d.category} TS${d.code}  ${d.message}  ${where}`;
+  }).join(`
+`);
+}