@stacksjs/stx 0.2.155 → 0.2.157

package/dist/reactive-bindings.d.ts

@@ -1,3 +1,36 @@
+/**
+ * STX Reactive Bindings
+ *
+ * Provides reactive bindings for STX templates with store integration.
+ *
+ * Syntax:
+ * - class="{{ $appStore.isActive ? 'active' : '' }}"
+ * - text="{{ $appStore.message }}"
+ * - disabled="{{ $appStore.isLoading }}"
+ *
+ * Store references:
+ * - $storeName.property (e.g., $appStore.isRecording)
+ *
+ * Example:
+ * <button
+ *   class="{{ $appStore.isRecording ? 'border-pink' : 'border-gray' }}"
+ *   disabled="{{ $appStore.isProcessing }}"
+ *   @click="voide.toggleRecording()"
+ * >
+ *   <span text="{{ $appStore.isRecording ? '🔴' : '🎤' }}"></span>
+ * </button>
+ */
+interface BindingInfo {
+    elementId: string;
+    attribute: string;
+    expression: string;
+    stores: string[];
+}
+interface ProcessedBindings {
+    html: string;
+    bindings: BindingInfo[];
+    stores: Set<string>;
+}
 /**
  * Process reactive bindings in HTML template
  * Detects {{ $store.value }} patterns in attribute values
@@ -11,14 +44,4 @@ export declare function generateBindingsRuntime(bindings: BindingInfo[], stores:
  * Process template with reactive bindings and generate runtime
  */
 export declare function processTemplateBindings(html: string): string;
-declare interface BindingInfo {
-  elementId: string
-  attribute: string
-  expression: string
-  stores: string[]
-}
-declare interface ProcessedBindings {
-  html: string
-  bindings: BindingInfo[]
-  stores: Set<string>
-}
+export {};

package/dist/reactive.d.ts

@@ -1,7 +1,3 @@
-/**
- * Check if a template contains reactive directives
- */
-export declare function hasReactiveDirectives(template: string): boolean;
 /**
  * Reactive Directives Module
  *
@@ -58,32 +54,64 @@ export declare function hasReactiveDirectives(template: string): boolean;
  *
  * @module reactive
  */
-// =============================================================================
-// Types
-// =============================================================================
-export declare interface ReactiveScope {
-  id: string
-  selector: string
-  stateExpr: string
-  initExpr: string | null
-  bindings: ReactiveBinding[]
-  refs: Map<string, string>
+export interface ReactiveScope {
+    /** Unique scope ID */
+    id: string;
+    /** Element selector */
+    selector: string;
+    /** Initial state expression */
+    stateExpr: string;
+    /** x-init expression if present */
+    initExpr: string | null;
+    /** Child bindings within this scope */
+    bindings: ReactiveBinding[];
+    /** Element references (x-ref) */
+    refs: Map<string, string>;
 }
-export declare interface ReactiveBinding {
-  elementId: string
-  type: 'model' | 'show' | 'hide' | 'text' | 'html' | 'bind' | 'class' | 'style' | 'event'
-  expression: string
-  attribute?: string
-  inputType?: string
-  transition?: TransitionConfig
+export interface ReactiveBinding {
+    /** Element ID or selector */
+    elementId: string;
+    /** Binding type */
+    type: 'model' | 'show' | 'hide' | 'text' | 'html' | 'bind' | 'class' | 'style' | 'event';
+    /** Expression to evaluate */
+    expression: string;
+    /** For x-bind, the attribute name */
+    attribute?: string;
+    /** For x-model, the input type */
+    inputType?: string;
+    /** For x-show/x-hide, transition configuration */
+    transition?: TransitionConfig;
 }
-export declare interface TransitionConfig {
-  enabled: boolean
-  enter?: string
-  enterStart?: string
-  enterEnd?: string
-  leave?: string
-  leaveStart?: string
-  leaveEnd?: string
-  duration?: number
+export interface TransitionConfig {
+    /** Simple transition (uses default classes) */
+    enabled: boolean;
+    /** Enter transition classes */
+    enter?: string;
+    /** Enter start classes (applied before insert) */
+    enterStart?: string;
+    /** Enter end classes (applied one frame after insert) */
+    enterEnd?: string;
+    /** Leave transition classes */
+    leave?: string;
+    /** Leave start classes (applied immediately when leaving) */
+    leaveStart?: string;
+    /** Leave end classes (applied one frame after leave starts) */
+    leaveEnd?: string;
+    /** Duration in ms (optional, defaults to CSS transition duration) */
+    duration?: number;
 }
+/**
+ * Process reactive directives in a template.
+ *
+ * Transforms `x-data`, `x-model`, `x-show`, etc. into client-side reactivity.
+ *
+ * @param template - The HTML template string
+ * @param context - Template context
+ * @param filePath - Source file path for error messages
+ * @returns Processed template with reactive runtime script
+ */
+export declare function processReactiveDirectives(template: string, context: Record<string, unknown>, _filePath: string): string;
+/**
+ * Check if a template contains reactive directives
+ */
+export declare function hasReactiveDirectives(template: string): boolean;

package/dist/reactive.js

@@ -393,7 +393,7 @@ window.__stx_reactive = (function() {
 `;
 }
 function substituteExpressionsInExpr(expr, context) {
-  let out = expr.replace(/\{!!([\s\S]*?)!!\}/g, (match, inner) => {
+  const source = expr.replace(/\{!!([\s\S]*?)!!\}/g, (match, inner) => {
     try {
       const value = evaluateExpression(inner, context, !0);
       if (value === void 0)
@@ -403,25 +403,55 @@ function substituteExpressionsInExpr(expr, context) {
       return match;
     }
   });
-  out = out.replace(/\{\{([\s\S]*?)\}\}/g, (match, inner) => {
-    try {
-      const value = evaluateExpression(inner, context, !0);
-      if (value === void 0)
-        return match;
-      if (typeof value === "string") {
-        const trimmed = value.trim();
-        if (trimmed.startsWith("{") && trimmed.endsWith("}") || trimmed.startsWith("[") && trimmed.endsWith("]"))
-          try {
-            JSON.parse(trimmed);
-            return trimmed;
-          } catch {}
+  let out = "", index = 0, quote = null;
+  while (index < source.length) {
+    const character = source[index];
+    if (quote && character === "\\") {
+      out += character + (source[index + 1] ?? "");
+      index += 2;
+      continue;
+    }
+    if (character === "{" && source[index + 1] === "{") {
+      const end = source.indexOf("}}", index + 2);
+      if (end !== -1) {
+        const match = source.slice(index, end + 2);
+        out += splice(source.slice(index + 2, end), match, quote);
+        index = end + 2;
+        continue;
       }
-      return JSON.stringify(value);
+    }
+    if (quote) {
+      if (character === quote)
+        quote = null;
+    } else if (character === "'" || character === '"' || character === "`")
+      quote = character;
+    out += character;
+    index++;
+  }
+  return out;
+  function splice(inner, match, insideQuote) {
+    let value;
+    try {
+      value = evaluateExpression(inner, context, !0);
     } catch {
       return match;
     }
-  });
-  return out;
+    if (value === void 0)
+      return match;
+    if (insideQuote) {
+      const text = String(value).replace(/\\/g, "\\\\").replace(new RegExp(insideQuote === "`" ? "`" : insideQuote, "g"), `\\${insideQuote}`).replace(/\r/g, "\\r").replace(/\n/g, "\\n");
+      return insideQuote === "`" ? text.replace(/\$\{/g, "\\${") : text;
+    }
+    if (typeof value === "string") {
+      const trimmed = value.trim();
+      if (trimmed.startsWith("{") && trimmed.endsWith("}") || trimmed.startsWith("[") && trimmed.endsWith("]"))
+        try {
+          JSON.parse(trimmed);
+          return trimmed;
+        } catch {}
+    }
+    return JSON.stringify(value);
+  }
 }
 function generateScopeInitializers(scopes, context) {
   if (scopes.length === 0)
@@ -541,23 +571,18 @@ function addAllReactiveIds(template) {
   return output;
 }
 function finalizeTemplate(template, scopes) {
-  let output = template;
-  for (const scope of scopes) {
-    const existingMatch = new RegExp(`<[a-z][a-z0-9-]*\\s+[^>]*data-stx-scope="([^"]*)"[^>]*x-data\\s*=\\s*["']${escapeRegex(scope.stateExpr)}["']`, "gi").exec(output);
-    if (existingMatch) {
-      scope.id = existingMatch[1];
+  let index = 0, output = template.replace(/<([a-z][a-z0-9-]*)(\s+[^>]*x-data\s*=\s*(?:"[^"]*"|'[^']*')[^>]*)>/gi, (match, tagName, attributes) => {
+    const scope = scopes[index++];
+    if (!scope)
+      return match;
+    const existing = /data-stx-scope="([^"]*)"/.exec(attributes);
+    if (existing) {
+      scope.id = existing[1];
       scope.selector = `[data-stx-scope="${scope.id}"]`;
-    } else {
-      const reverseMatch = new RegExp(`<[a-z][a-z0-9-]*\\s+[^>]*x-data\\s*=\\s*["']${escapeRegex(scope.stateExpr)}["'][^>]*data-stx-scope="([^"]*)"`, "gi").exec(output);
-      if (reverseMatch) {
-        scope.id = reverseMatch[1];
-        scope.selector = `[data-stx-scope="${scope.id}"]`;
-      } else {
-        output = output.replace(new RegExp(`(<[a-z][a-z0-9-]*\\s+)([^>]*)(x-data\\s*=\\s*"${escapeRegex(scope.stateExpr)}")([^>]*>)`, "gi"), `$1data-stx-scope="${scope.id}" $2$3$4`);
-        output = output.replace(new RegExp(`(<[a-z][a-z0-9-]*\\s+)([^>]*)(x-data\\s*=\\s*'${escapeRegex(scope.stateExpr)}')([^>]*>)`, "gi"), `$1data-stx-scope="${scope.id}" $2$3$4`);
-      }
+      return match;
     }
-  }
+    return `<${tagName} data-stx-scope="${scope.id}"${attributes}>`;
+  });
   output = output.replace(/\s*x-data\s*=\s*"([^"]*)"/g, ' data-stx-xdata="$1"');
   output = output.replace(/\s*x-data\s*=\s*'([^']*)'/g, " data-stx-xdata='$1'");
   output = output.replace(/\s*x-init\s*=\s*"[^"]*"/g, "");

package/dist/render.d.ts

@@ -1,18 +1,4 @@
 import type { StxOptions } from './types';
-/**
- * Render a .stx template file to an HTML string.
- *
- * This is the primary rendering API. It:
- * 1. Reads the template file
- * 2. Extracts and executes server-side scripts
- * 3. Processes all stx directives (conditionals, loops, expressions, etc.)
- * 4. Injects client-side scripts
- * 5. Returns the final HTML string
- *
- * @param filePath - Path to the .stx template file
- * @param renderOptions - Additional rendering options
- * @returns The rendered HTML string
- */
 export declare function renderTemplate(filePath: string, renderOptions?: RenderOptions): Promise<string>;
 /**
  * Render an inline stx template string to HTML.

package/dist/render.js

@@ -66,6 +66,10 @@ ${html}
 </body>
 </html>`;
 }
+function recordOn(target, key, value) {
+  if (target && typeof target === "object")
+    target[key] = value;
+}
 export async function renderTemplate(filePath, renderOptions = {}) {
   const resolvedPath = resolve(filePath), file = Bun.file(resolvedPath);
   if (!await file.exists())
@@ -111,6 +115,19 @@ export async function renderTemplateString(content, filePath, renderOptions = {}
     __stx_options: options,
     __stx_sfc_mode: !0,
     __stx_inject_css: renderOptions.injectCSS === !0,
+    __stxServeContext: void 0,
+    setResponseStatus: (status) => {
+      if (Number.isInteger(status) && status >= 100 && status <= 599)
+        recordOn(renderOptions.context, "__stxResponseStatus", status);
+    },
+    setResponseHeader: (name, value) => {
+      if (!name)
+        return;
+      const headers = renderOptions.context?.__stxResponseHeaders || {};
+      headers[String(name)] = String(value);
+      recordOn(renderOptions.context, "__stxResponseHeaders", headers);
+    },
+    definePageMeta: () => {},
     ...renderOptions.context || {}
   };
   for (const scriptContent of serverScripts)

package/dist/route-middleware.d.ts

@@ -1,35 +1,2 @@
-export type {
-  AbortNavigationResult,
-  CookieManager,
-  CookieOptions,
-  MiddlewareContext,
-  MiddlewareMode,
-  MiddlewareOptions,
-  MiddlewareResult,
-  NavigateToOptions,
-  NavigateToResult,
-  NavigationError,
-  NavigationResult,
-  RouteLocation,
-  RouteMiddlewareDefinition,
-  RouteMiddlewareHandler,
-  StorageManager,
-} from 'stx-router';
-// Re-export from stx-router
-export {
-  abortNavigation,
-  clearMiddleware,
-  createClientCookieManager,
-  createMiddlewareContext,
-  createRouteLocation,
-  createServerCookieManager,
-  createStorageManager,
-  defineMiddleware,
-  getMiddleware,
-  getMiddlewareNames,
-  hasMiddleware,
-  loadMiddlewareFromDirectory,
-  navigateTo,
-  registerMiddleware,
-  runMiddleware,
-} from 'stx-router';
+export { abortNavigation, clearMiddleware, createClientCookieManager, createMiddlewareContext, createRouteLocation, createServerCookieManager, createStorageManager, defineMiddleware, getMiddleware, getMiddlewareNames, hasMiddleware, loadMiddlewareFromDirectory, navigateTo, registerMiddleware, runMiddleware, } from 'stx-router';
+export type { AbortNavigationResult, CookieManager, CookieOptions, MiddlewareContext, MiddlewareMode, MiddlewareOptions, MiddlewareResult, NavigateToOptions, NavigateToResult, NavigationError, NavigationResult, RouteLocation, RouteMiddlewareDefinition, RouteMiddlewareHandler, StorageManager, } from 'stx-router';

package/dist/route-types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Build a concrete URL from a route pattern.
+ *
+ * The strict half of the pair: `navigate()` stays permissive so computed URLs
+ * keep working, and `$path()` is where a dynamic route gets checked —
+ * `navigate($path('/cars/:id', { id: car.id }))`.
+ *
+ * Consumes the `?`/`*` sigil, drops the preceding slash when an optional
+ * segment is absent, encodes catch-all segments individually so their slashes
+ * survive, and appends anything left over as a query string.
+ */
+export declare function $path<P extends RoutePattern>(pattern: P, ...args: ParamsArg<P>): string;
+/**
+ * Typed route paths that actually type-check (stacksjs/stx#1887).
+ *
+ * `generateRouteTypes()` emitted `declare module "stx/routes" { interface
+ * RouteMap … }` and nothing in the source tree declared or imported
+ * `stx/routes`. Because that specifier does not resolve, TypeScript treated it
+ * as an ambient module declaration rather than an augmentation — so it parsed,
+ * shipped, and constrained nothing. `navigate('/dashbaord')` type-checked.
+ *
+ * ## Why the obvious fix does not work
+ *
+ * The tempting shape is `type RoutePath = KnownRoute | (string & {})`. It
+ * cannot catch anything: a parameter that accepts a computed `string`
+ * necessarily accepts every string literal too. It buys autocomplete and zero
+ * checking, which is the same trade the dangling declaration already made.
+ *
+ * The other tempting shape — a plain union — rejects real code. This repo's own
+ * tests navigate to `'?status=resolved'`, `'guide'` and
+ * `'https://example.com/pricing'`; apps build URLs with template literals and
+ * ternaries. A union rejects all of it, and measured against a real app it
+ * would have produced zero true positives against five false ones, because the
+ * generated union holds *patterns* (`/cars/:id`) while callers pass *URLs*
+ * (`/cars/42`).
+ *
+ * ## What this does instead
+ *
+ * {@link CheckHref} is a generic gate applied to the argument's own literal
+ * type. Non-literals pass through untouched, so anything computed still
+ * compiles; only a leading-slash string literal is checked, against the routes
+ * expanded from patterns. A typo in a hand-written path is the one thing that
+ * fails — which is the only thing worth failing.
+ *
+ * @module route-types
+ */
+/**
+ * Routes that exist, augmented by the generated
+ * `<state-dir>/route-types.d.ts`.
+ *
+ * Empty here on purpose: while it is empty every route type widens to `string`,
+ * so a project that has not generated the declaration — or has not added the
+ * state directory to its tsconfig — is unaffected.
+ *
+ * The value type is the route's params, so one interface serves both the
+ * pattern union and per-route param lookup.
+ */
+export declare interface KnownRoutes {}
+/**
+ * Error carriers. TypeScript reports the property names, so the message says
+ * what is wrong rather than naming an internal type.
+ */
+export declare interface UnknownRoute<T extends string> {
+  'stx: no page matches this path': T
+  'known routes': RoutePattern
+}
+export declare interface RoutePatternUsedAsHref<T extends string> {
+  'stx: that is a route pattern, not a URL — use $path() to fill its params': T
+}
+declare type RouteKeys = keyof KnownRoutes & string;
+/** Tuple-wrapped so a `never` key set does not distribute into `true`. */
+declare type NoRoutes = [RouteKeys] extends [never] ? true : false;
+/** Every known route pattern, or `string` when none were generated. */
+export type RoutePattern = NoRoutes extends true ? string : RouteKeys;
+/** The params a pattern declares. */
+export type RouteParams<P extends RoutePattern> = P extends RouteKeys
+  ? KnownRoutes[P]
+  : Record<string, string>;
+/**
+ * A pattern with its params replaced by wildcards, so a concrete URL matches.
+ *
+ * `/cars/:id` becomes `` `/cars/${string}` ``, which is what a caller actually
+ * passes. Comparing against the raw pattern would reject every dynamic-route
+ * navigation in existence.
+ */
+declare type PatternPrefix<P extends string> = P extends `${infer Head}:${string}` ? `${Head}${string}` : P;
+/** `/settings/:tab?` also matches `/settings` with the segment omitted. */
+declare type OptionalBase<P extends string> = P extends `${infer Base}/:${string}?` ? Base : never;
+/** Every shape a caller may legitimately pass for a known route. */
+export type RouteHref = PatternPrefix<RoutePattern> | OptionalBase<RoutePattern>;
+declare type StripHash<S extends string> = S extends `${infer Base}#${string}` ? Base : S;
+declare type StripQuery<S extends string> = S extends `${infer Base}?${string}` ? Base : S;
+/**
+ * Gate a route argument on its own literal type.
+ *
+ * Each step is load-bearing:
+ *
+ * 1. Not a string literal (a variable, a template literal, a concatenation) —
+ *    pass. This is what keeps computed URLs compiling.
+ * 2. No routes generated — pass, so an un-adopted project is unaffected.
+ * 3. Only absolute paths are checked. A relative href, a bare `?query`, a
+ *    `#hash` and `https://…` all fall through, because the router genuinely
+ *    accepts them.
+ * 4. A raw pattern is a mistake worth naming separately: `/cars/:id` is not a
+ *    URL.
+ * 5. Otherwise the path, minus any query or hash, must match a known route.
+ */
+export type CheckHref<T extends string> = string extends T
+    ? T
+    : string extends RoutePattern
+      ? T
+      : T extends `/${string}`
+        ? T extends `${string}/:${string}`
+          ? RoutePatternUsedAsHref<T>
+          : StripQuery<StripHash<T>> extends RouteHref ? T : UnknownRoute<T>
+        : T;
+/**
+ * A route in an assignment position (a config field, an interface property),
+ * where no generic parameter exists to gate on.
+ *
+ * Autocomplete only — it cannot reject a typo, for the reason given at the top
+ * of this file. Prefer a `CheckHref`-gated function parameter where one is
+ * available.
+ */
+export type RoutePath = RoutePattern | (string & {});
+declare type RouteParamsInput<P extends RoutePattern> = {
+  [K in keyof RouteParams<P>]: string | number | readonly string[]
+}
+/** Params are required only when the pattern has non-optional ones. */
+declare type ParamsArg<P extends RoutePattern> = [keyof RouteParams<P>] extends [never]
+  ? []
+  : Record<never, never> extends RouteParams<P>
+    ? [params?: RouteParamsInput<P>]
+    : [params: RouteParamsInput<P>];

package/dist/route-types.js

@@ -0,0 +1,24 @@
+export function $path(pattern, ...args) {
+  const params = args[0] ?? {}, used = new Set, filled = String(pattern).replace(/(\/)?:([^/?*]+)([?*])?/g, (whole, slash, name, sigil) => {
+    const value = params[name];
+    used.add(name);
+    if (value === void 0 || value === null || value === "") {
+      if (sigil === "?")
+        return "";
+      return whole;
+    }
+    const encoded = Array.isArray(value) ? value.map((part) => encodeURIComponent(String(part))).join("/") : sigil === "*" ? String(value).split("/").map((part) => encodeURIComponent(part)).join("/") : encodeURIComponent(String(value));
+    return `${slash ?? ""}${encoded}`;
+  }), extra = Object.keys(params).filter((key) => !used.has(key));
+  if (extra.length === 0)
+    return filled;
+  const query = new URLSearchParams;
+  for (const key of extra) {
+    const value = params[key];
+    if (Array.isArray(value))
+      value.forEach((part) => query.append(key, String(part)));
+    else if (value !== void 0 && value !== null)
+      query.set(key, String(value));
+  }
+  return `${filled}?${query.toString()}`;
+}

package/dist/router.d.ts

@@ -1,11 +1,9 @@
-import { matchRoute } from 'stx-router';
 import type { Route } from 'stx-router';
 export type { Route, RouteMatch } from 'stx-router';
+export { findErrorPage, formatRoutes, generateRouteManifest, generateRouteTypes, matchRoute } from 'stx-router';
+export interface RouterOptions {
+    pagesDir?: string;
+    extensions?: string[];
+}
 export declare function createRouter(baseDir: string, options?: RouterOptions): Route[];
 export declare function getRouteParams(pathname: string, routes: Route[]): Record<string, string> | null;
-// Backwards-compatible createRouter that returns Route[] (original signature)
-export declare interface RouterOptions {
-  pagesDir?: string
-  extensions?: string[]
-}
-export { findErrorPage, formatRoutes, generateRouteManifest, generateRouteTypes, matchRoute } from 'stx-router';

package/dist/routes.d.ts

@@ -1,8 +1,6 @@
-import { route } from 'stx-router';
+export { defineRoute, defineRoutes, resetRoutes, route, setAppUrl } from 'stx-router';
 /**
  * Process @route directives in stx templates
  * (Kept in core stx because it depends on safe-evaluator)
  */
 export declare function processRouteDirectives(template: string): string;
-// Re-export named route primitives from stx-router
-export { defineRoute, defineRoutes, resetRoutes, route, setAppUrl } from 'stx-router';