@stacksjs/stx 0.2.174 → 0.2.176

package/dist/includes.js

@@ -512,14 +512,18 @@ export async function processIncludes(template, context, filePath, options, depe
   }
   const currentFilePath = path.resolve(filePath);
   includeStack.add(currentFilePath);
+  function includeFailure(includePath, message, templateStr, offsetPos) {
+    options.onIncludeError?.({ includePath, templatePath: filePath, message, partialsDir });
+    return createDetailedErrorMessage("Include", message, filePath, templateStr, offsetPos);
+  }
   async function processIncludeHelper(includePath, localVars = {}, templateStr, offsetPos) {
     const includeFilePath = resolvePath(includePath, partialsDir, filePath);
     if (!includeFilePath)
-      return createDetailedErrorMessage("Include", `Could not resolve path for include: ${includePath}`, filePath, templateStr, offsetPos);
+      return includeFailure(includePath, `Could not resolve path for include: ${includePath}`, templateStr, offsetPos);
     const resolvedIncludePath = path.resolve(includeFilePath);
     if (includeStack.has(resolvedIncludePath)) {
       const chain = [...includeStack, resolvedIncludePath].map((p) => path.basename(p)).join(" -> ");
-      return createDetailedErrorMessage("Include", `Circular include detected: ${chain}`, filePath, templateStr, offsetPos);
+      return includeFailure(includePath, `Circular include detected: ${chain}`, templateStr, offsetPos);
     }
     try {
       dependencies.add(includeFilePath);
@@ -529,7 +533,7 @@ export async function processIncludes(template, context, filePath, options, depe
           partialContent = await Bun.file(includeFilePath).text();
         } catch (error) {
           const errorMessage = error instanceof Error ? error.message : String(error);
-          return createDetailedErrorMessage("Include", `Error loading include file ${includePath}: ${errorMessage}`, filePath, templateStr, offsetPos);
+          return includeFailure(includePath, `Error loading include file ${includePath}: ${errorMessage}`, templateStr, offsetPos);
         }
       if (partialContent)
         partialContent = partialContent.replace(/\{\{--[\s\S]*?--\}\}/g, "");
@@ -641,7 +645,7 @@ export async function processIncludes(template, context, filePath, options, depe
       return processedContent;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      return createDetailedErrorMessage("Include", `Error processing include ${includePath}: ${errorMessage}`, filePath, templateStr, offsetPos);
+      return includeFailure(includePath, `Error processing include ${includePath}: ${errorMessage}`, templateStr, offsetPos);
     }
   }
   const includePattern = /@include\s*\(/g;

package/dist/index.d.ts

@@ -204,6 +204,7 @@ export * from './reactive-bindings';
 export * from './client-helpers';
 export * from './client-script';
 export * from './strip-literals';
+export * from './resolve-stx-targets';
 export * from './component-hmr';
 export * from './hydration';
 // ssg moved to stx/ssg

package/dist/index.js

@@ -113,6 +113,7 @@ export * from "./reactive-bindings.js";
 export * from "./client-helpers.js";
 export * from "./client-script.js";
 export * from "./strip-literals.js";
+export * from "./resolve-stx-targets.js";
 export * from "./component-hmr.js";
 export * from "./hydration.js";
 export * from "./ssr.js";

package/dist/process.js

@@ -54,7 +54,7 @@ import { deriveLayoutGroup } from "stx-router/layout-metadata";
 import { initializeComponentClientFactories, injectComponentClientFactories } from "./component-client-factories.js";
 import { importOnce } from "./lazy-module.js";
 export { injectRouterScript } from "./runtime-injection.js";
-import { injectSignalsRuntime, outputNeedsSignalsRuntime, pageShipsSignalsRuntime } from "./runtime-injection.js";
+import { injectSignalsRuntime, injectTooltipRuntime, outputNeedsSignalsRuntime, pageShipsSignalsRuntime } from "./runtime-injection.js";
 export { processJsonDirective, processOnceDirective } from "./misc-directives.js";
 export { validateClientScript } from "./script-validation.js";
 const PARENT_PLACEHOLDER = "<!--PARENT_CONTENT_PLACEHOLDER-->";
@@ -843,6 +843,7 @@ ${runtimeScript}`);
   }
   if (!pageShipsSignalsRuntime(output) && outputNeedsSignalsRuntime(output))
     output = await injectSignalsRuntime(output, opts);
+  output = injectTooltipRuntime(output);
   if (opts.csp?.enabled && opts.csp.useNonce && typeof context.cspNonce === "string")
     output = addNonceToInlineContent(output, context.cspNonce);
   return output;

package/dist/props.d.ts

@@ -1,9 +1,22 @@
 /**
  * Define component props with type safety and validation.
  *
+ * Takes an inline object type or a named `interface`/`type` — the named form is
+ * shown first because it is the one the framework scaffolds, and because every
+ * example here used to be inline. An inline literal has an implicit index
+ * signature and a named `interface` does not, so an inline-only docstring
+ * demonstrated the one spelling that could not fail (stacksjs/stx#1917).
+ *
  * @example
  * ```typescript
- * // Simple usage with types only
+ * // A named type, inline or imported — interface and type alias both work
+ * interface CardProps {
+ *   title: string
+ *   count: number
+ * }
+ * const props = defineProps<CardProps>()
+ *
+ * // Or inline
  * const props = defineProps<{
  *   title: string
  *   count: number
@@ -24,12 +37,12 @@
  * })
  * ```
  */
-export declare function defineProps<T extends Record<string, unknown>>(definitions?: PropsDefinition<T>): T;
+export declare function defineProps<T extends PropsShape>(definitions?: PropsDefinition<T>): T;
 /**
  * Define props with runtime validation.
  * Use this when you need validation errors at runtime.
  */
-export declare function definePropsWithValidation<T extends Record<string, unknown>>(definitions: PropsDefinition<T>, options?: {
+export declare function definePropsWithValidation<T extends PropsShape>(definitions: PropsDefinition<T>, options?: {
     componentName?: string
     throwOnError?: boolean
     logWarnings?: boolean
@@ -49,7 +62,7 @@ export declare function definePropsWithValidation<T extends Record<string, unkno
  * })
  * ```
  */
-export declare function withDefaults<T extends Record<string, unknown>>(props: T, defaults: Partial<{ [K in keyof T]: T[K] | (() => T[K]) }>): T;
+export declare function withDefaults<T extends PropsShape>(props: T, defaults: Partial<{ [K in keyof T]: T[K] | (() => T[K]) }>): T;
 /**
  * Create a prop type definition for a specific type.
  */
@@ -77,7 +90,7 @@ export declare function arrayOf<T>(_itemType: PropType<T>, options?: Omit<PropOp
 /**
  * Create a prop for object with specific shape.
  */
-export declare function shape<T extends Record<string, unknown>>(_shape: PropsDefinition<T>, options?: Omit<PropOptions<T>, 'type'>): PropOptions<T>;
+export declare function shape<T extends PropsShape>(_shape: PropsDefinition<T>, options?: Omit<PropOptions<T>, 'type'>): PropOptions<T>;
 /**
  * Process props passed to a component.
  * Called internally during component rendering.
@@ -100,7 +113,7 @@ export declare function processComponentProps(rawProps: Record<string, unknown>,
  * emit('close', undefined)
  * ```
  */
-export declare function defineEmits<E extends Record<string, unknown>>(): EmitFn<E>;
+export declare function defineEmits<E extends PropsShape>(): EmitFn<E>;
 /**
  * Expose component methods/properties to parent.
  *
@@ -113,7 +126,7 @@ export declare function defineEmits<E extends Record<string, unknown>>(): EmitFn
  * })
  * ```
  */
-export declare function defineExpose<T extends Record<string, unknown>>(exposed: T): void;
+export declare function defineExpose<T extends PropsShape>(exposed: T): void;
 /**
  * Generate TypeScript interface from prop definitions.
  * Useful for documentation and type generation.
@@ -151,6 +164,36 @@ export type PropType<T> = | StringConstructor
   | SymbolConstructor
   | { new (...args: unknown[]): T }
   | PropType<T>[];
+/**
+ * The constraint every props, emits and expose generic is bounded by.
+ *
+ * `object` rather than `Record<string, unknown>`, and the difference is not
+ * cosmetic: **a TypeScript `interface` does not satisfy an index signature.**
+ * Only a type alias gets an implicit one, so
+ *
+ *     interface CardProps { title: string }
+ *     defineProps<CardProps>()   // TS2344, TS2345
+ *     type CardProps = { title: string }
+ *     defineProps<CardProps>()   // fine
+ *
+ * differ on the keyword alone. `interface` is the form the framework scaffolds
+ * — `storage/framework/defaults/` declares props with it 44 times and with a
+ * type alias zero times — so the constraint rejected the entire scaffolded
+ * corpus (stacksjs/stx#1917).
+ *
+ * Two things hid it. Every example in the docstrings passes an inline object
+ * literal, which HAS an implicit index signature and so always passed; the
+ * error appears only once the type is named, which is the moment it is reused
+ * or exported. And apps import from `stx`, which is not a package anyone can
+ * install — the module resolved to `any`, the constraint was never enforced,
+ * and the component type-checked. Correcting the specifier in one app turned 18
+ * "Cannot find module" errors into 36 constraint errors.
+ *
+ * Named rather than written out seven times so the reason lives in one place
+ * and the sites cannot drift apart. `object` still rejects `string`, `number`
+ * and `undefined`, which is everything this constraint has to do.
+ */
+export type PropsShape = object;
 /** Props definition object */
 export type PropsDefinition<T> = {
   [K in keyof T]?: PropOptions<T[K]> | PropType<T[K]>
@@ -167,7 +210,7 @@ export type ExtractPropTypes<T extends PropsDefinition<unknown>> = {
 // eslint-disable-next-line pickier/no-unused-vars
 export type EventHandler<T = unknown> = (payload: T) => void;
 /** Emit function type */
-export type EmitFn<E extends Record<string, unknown>> = <K extends keyof E>(
+export type EmitFn<E extends PropsShape> = <K extends keyof E>(
   event: K,
   payload: E[K],
 ) => void;