@alloy-js/core 0.22.0 → 0.23.0-dev.1

package/src/render-stack.ts

@@ -0,0 +1,222 @@
+import pc from "picocolors";
+import { contextsByKey } from "./context.js";
+import { SourceDirectoryContext } from "./context/source-directory.js";
+import { SourceFileContext } from "./context/source-file.js";
+import { Context, getContext } from "./reactivity.js";
+import { Component, Props, SourceLocation } from "./runtime/component.js";
+
+// Store render stack for error diagnostics
+const renderStack: Array<{
+  component: Component<any>;
+  props: Props;
+  context: Context | null;
+  source?: SourceLocation;
+}> = [];
+
+export function pushStack(
+  component: Component<any>,
+  props: Props,
+  source?: SourceLocation,
+) {
+  renderStack.push({ component, props, context: getContext(), source });
+}
+
+export function popStack() {
+  renderStack.pop();
+}
+
+export function clearRenderStack() {
+  renderStack.length = 0;
+}
+
+// Helper functions
+function getComponentDisplayName(
+  component: Component<any>,
+  props: Props,
+): string {
+  // Check if this is a Provider and if we can find its context name
+  if (component.name === "Provider") {
+    // Try to find the context this provider is associated with
+    for (const ctx of contextsByKey.values()) {
+      if (ctx.Provider === component && ctx.name) {
+        return ctx.name;
+      }
+    }
+  }
+  return component.name;
+}
+
+function inspectProps(props: Props) {
+  const entries = Object.entries(props)
+    .filter(([key]) => key !== "children") // Exclude children prop
+    .map(([key, value]) => {
+      const formattedValue = formatValue(value);
+      return `${pc.dim(key)}: ${formattedValue}`;
+    });
+
+  return entries.length > 0 ? entries.join(pc.dim(", ")) : "";
+}
+
+function formatValue(value: unknown): string {
+  switch (typeof value) {
+    case "string":
+      return pc.blue(`"${value}"`);
+    case "number":
+    case "boolean":
+      return pc.blue(String(value));
+    case "undefined":
+      return pc.gray("undefined");
+    case "object":
+      return value ? pc.gray("{...}") : pc.gray("null");
+    case "function":
+      return pc.gray("function");
+    default:
+      return pc.gray(String(value));
+  }
+}
+
+function formatSourceLocation(source: SourceLocation): string {
+  const cwd = process.cwd();
+  let filePath = source.fileName;
+
+  // Convert to relative path if under cwd
+  if (filePath.startsWith(cwd)) {
+    filePath = filePath.slice(cwd.length + 1); // +1 to remove leading slash
+  }
+
+  return `${filePath}:${source.lineNumber}:${source.columnNumber}`;
+}
+
+/**
+ * Print the current render stack to the console for debugging.
+ *
+ * This differs from debug.component.stack in that this uses a purpose-built
+ * stack rather than walking the context chain. When this is called, the context
+ * chain has been restored. In the future this can probably be unified nicely.
+ */
+export function printRenderStack() {
+  // Find the nearest SourceFileContext or SourceDirectoryContext from the render stack
+  let currentPath: string | undefined;
+  for (let i = renderStack.length - 1; i >= 0; i--) {
+    const { context } = renderStack[i];
+    // Prefer SourceFileContext over SourceDirectoryContext
+    if (context?.context?.[SourceFileContext.id]) {
+      const fileContext = context.context[
+        SourceFileContext.id
+      ] as SourceFileContext;
+      currentPath = fileContext.path;
+      break;
+    }
+    if (!currentPath && context?.context?.[SourceDirectoryContext.id]) {
+      const dirContext = context.context[
+        SourceDirectoryContext.id
+      ] as SourceDirectoryContext;
+      currentPath = dirContext.path;
+      // Don't break - keep looking for a SourceFileContext
+    }
+  }
+
+  if (currentPath) {
+    // eslint-disable-next-line no-console
+    console.error(pc.red(`Error rendering in file ${currentPath}`));
+  } else {
+    // eslint-disable-next-line no-console
+    console.error(pc.red("Error rendering:"));
+  }
+
+  // First pass: determine which providers should be nested vs standalone
+  // A provider should be nested under its parent if it's from a different file
+  // (i.e., it's part of the component's implementation, not user-provided)
+  const nestedProviderIndices = new Set<number>();
+
+  for (let i = renderStack.length - 1; i >= 0; i--) {
+    const { component, source } = renderStack[i];
+
+    // Skip anonymous components and providers
+    if (!component.name || component.name === "Provider") {
+      continue;
+    }
+
+    // Look for providers that come immediately after this component
+    for (let j = i + 1; j < renderStack.length; j++) {
+      const providerEntry = renderStack[j];
+      if (!providerEntry.component.name) continue;
+      if (providerEntry.component.name !== "Provider") break;
+
+      // Nest provider if it's from a different file (component-internal)
+      const shouldNest =
+        !source ||
+        !providerEntry.source ||
+        source.fileName !== providerEntry.source.fileName;
+
+      if (shouldNest) {
+        nestedProviderIndices.add(j);
+      } else {
+        // Stop looking - this provider and all after should be standalone
+        break;
+      }
+    }
+  }
+
+  // Second pass: print stack entries in order, nesting providers where appropriate
+  for (let i = renderStack.length - 1; i >= 0; i--) {
+    const { component, props, source } = renderStack[i];
+
+    // Skip anonymous components
+    if (!component.name) {
+      continue;
+    }
+
+    // Skip providers that will be nested under their parent
+    if (nestedProviderIndices.has(i)) {
+      continue;
+    }
+
+    const displayName = getComponentDisplayName(component, props);
+    const sourceStr =
+      source ? pc.gray(` (${formatSourceLocation(source)})`) : "";
+
+    // eslint-disable-next-line no-console
+    console.error(`  ${pc.cyan("at")} ${pc.bold(displayName)}${sourceStr}`);
+
+    // Print props on next line if there are any
+    const propsStr = inspectProps(props);
+    if (propsStr) {
+      // eslint-disable-next-line no-console
+      console.error(`     ${propsStr}`);
+    }
+
+    // For non-Provider components, print any nested providers
+    if (component.name !== "Provider") {
+      for (let j = i + 1; j < renderStack.length; j++) {
+        if (!nestedProviderIndices.has(j)) break;
+
+        const providerEntry = renderStack[j];
+        if (!providerEntry.component.name) continue;
+
+        const providerName = getComponentDisplayName(
+          providerEntry.component,
+          providerEntry.props,
+        );
+        const providerSourceStr =
+          providerEntry.source ?
+            pc.gray(` (${formatSourceLocation(providerEntry.source)})`)
+          : "";
+
+        // eslint-disable-next-line no-console
+        console.error(
+          `     ${pc.magenta("provides")} ${pc.bold(providerName)}${providerSourceStr}`,
+        );
+
+        const providerPropsStr = inspectProps(providerEntry.props);
+        if (providerPropsStr) {
+          // eslint-disable-next-line no-console
+          console.error(`       ${providerPropsStr}`);
+        }
+      }
+    }
+  }
+
+  // Clear the stack after printing to avoid stale data on subsequent render errors
+  clearRenderStack();
+}

package/src/render.ts

@@ -3,7 +3,6 @@ import { Doc, doc } from "prettier";
 import prettier from "prettier/doc.js";
 import { useContext } from "./context.js";
 import { SourceFileContext } from "./context/source-file.js";
-import { shouldDebug } from "./debug.js";
 import {
   Context,
   CustomContext,
@@ -15,13 +14,12 @@ import {
   untrack,
 } from "./reactivity.js";
 import { isRefkeyable, toRefkey } from "./refkey.js";
+import { popStack, printRenderStack, pushStack } from "./render-stack.js";
 import {
   Child,
   Children,
-  Component,
   isComponentCreator,
   isRenderableObject,
-  Props,
   RENDERABLE,
 } from "./runtime/component.js";
 import { IntrinsicElement, isIntrinsicElement } from "./runtime/intrinsic.js";
@@ -585,7 +583,8 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
 
         if (context) context.componentOwner = child;
         const componentRoot: RenderedTextTree = [];
-        pushStack(child.component, child.props);
+
+        pushStack(child.component, child.props, child.source);
         renderWorker(componentRoot, untrack(child));
         popStack();
         node.push(componentRoot);
@@ -768,57 +767,3 @@ function printTreeWorker(tree: RenderedTextTree): Doc {
 
   return doc;
 }
-// debugging utilities
-const renderStack: {
-  component: Component<any>;
-  props: Props;
-}[] = [];
-
-export function pushStack(component: Component<any>, props: Props) {
-  if (!shouldDebug()) return;
-  renderStack.push({ component, props });
-}
-
-export function popStack() {
-  if (!shouldDebug()) return;
-  renderStack.pop();
-}
-
-export function printRenderStack() {
-  if (!shouldDebug()) return;
-
-  // eslint-disable-next-line no-console
-  console.error("Error rendering:");
-  for (let i = renderStack.length - 1; i >= 0; i--) {
-    const { component, props } = renderStack[i];
-    // eslint-disable-next-line no-console
-    console.error(`    at ${component.name}(${inspectProps(props)})`);
-  }
-}
-
-function inspectProps(props: Props) {
-  return JSON.stringify(
-    Object.fromEntries(
-      Object.entries(props).map(([key, value]) => {
-        let safeValue;
-        switch (typeof value) {
-          case "string":
-          case "number":
-          case "boolean":
-            safeValue = value;
-            break;
-          case "undefined":
-            safeValue = "undefined";
-            break;
-          case "object":
-            safeValue = value ? "{...}" : null;
-            break;
-          case "function":
-            safeValue = "function";
-            break;
-        }
-        return [key, safeValue];
-      }),
-    ),
-  );
-}

package/src/runtime/component.ts

@@ -51,6 +51,12 @@ export type Child =
 export type Children = Child | Children[];
 export type Props = Record<string, any>;
 
+export interface SourceLocation {
+  fileName: string;
+  lineNumber: number;
+  columnNumber: number;
+}
+
 export interface ComponentDefinition<TProps = Props> {
   (props: TProps): Children;
 }
@@ -64,6 +70,7 @@ export interface ComponentCreator<TProps = Props> {
   (): Children;
   props: TProps;
   tag?: symbol;
+  source?: SourceLocation;
 }
 
 export function isComponentCreator<TProps = any>(
@@ -79,6 +86,7 @@ export function isComponentCreator<TProps = any>(
 export function createComponent<TProps extends Props = Props>(
   C: Component<TProps>,
   props: TProps,
+  source?: SourceLocation,
 ): ComponentCreator<TProps> {
   const creator: ComponentCreator<TProps> = () => /* */ C(props);
   creator.props = props;
@@ -86,6 +94,9 @@ export function createComponent<TProps extends Props = Props>(
   if (C.tag) {
     creator.tag = C.tag;
   }
+  if (source) {
+    creator.source = source;
+  }
 
   return creator;
 }

package/temp/api.json

@@ -3061,6 +3061,34 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/core!ComponentCreator#source:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "source?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "SourceLocation",
+                  "canonicalReference": "@alloy-js/core!SourceLocation:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "source",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/core!ComponentCreator#tag:member",
@@ -4322,6 +4350,15 @@
               "kind": "Content",
               "text": "TProps"
             },
+            {
+              "kind": "Content",
+              "text": ", source?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "SourceLocation",
+              "canonicalReference": "@alloy-js/core!SourceLocation:interface"
+            },
             {
               "kind": "Content",
               "text": "): "
@@ -4342,8 +4379,8 @@
           ],
           "fileUrlPath": "src/runtime/component.ts",
           "returnTypeTokenRange": {
-            "startIndex": 10,
-            "endIndex": 12
+            "startIndex": 12,
+            "endIndex": 14
           },
           "releaseTag": "Public",
           "overloadIndex": 1,
@@ -4363,6 +4400,14 @@
                 "endIndex": 9
               },
               "isOptional": false
+            },
+            {
+              "parameterName": "source",
+              "parameterTypeTokenRange": {
+                "startIndex": 10,
+                "endIndex": 11
+              },
+              "isOptional": true
             }
           ],
           "typeParameters": [
@@ -17135,34 +17180,6 @@
           ],
           "extendsTokenRanges": []
         },
-        {
-          "kind": "Function",
-          "canonicalReference": "@alloy-js/core!popStack:function(1)",
-          "docComment": "",
-          "excerptTokens": [
-            {
-              "kind": "Content",
-              "text": "export declare function popStack(): "
-            },
-            {
-              "kind": "Content",
-              "text": "void"
-            },
-            {
-              "kind": "Content",
-              "text": ";"
-            }
-          ],
-          "fileUrlPath": "src/render.ts",
-          "returnTypeTokenRange": {
-            "startIndex": 1,
-            "endIndex": 2
-          },
-          "releaseTag": "Public",
-          "overloadIndex": 1,
-          "parameters": [],
-          "name": "popStack"
-        },
         {
           "kind": "Interface",
           "canonicalReference": "@alloy-js/core!PrintHook:interface",
@@ -17392,34 +17409,6 @@
             "endIndex": 2
           }
         },
-        {
-          "kind": "Function",
-          "canonicalReference": "@alloy-js/core!printRenderStack:function(1)",
-          "docComment": "",
-          "excerptTokens": [
-            {
-              "kind": "Content",
-              "text": "export declare function printRenderStack(): "
-            },
-            {
-              "kind": "Content",
-              "text": "void"
-            },
-            {
-              "kind": "Content",
-              "text": ";"
-            }
-          ],
-          "fileUrlPath": "src/render.ts",
-          "returnTypeTokenRange": {
-            "startIndex": 1,
-            "endIndex": 2
-          },
-          "releaseTag": "Public",
-          "overloadIndex": 1,
-          "parameters": [],
-          "name": "printRenderStack"
-        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!printTree:function(1)",
@@ -17733,73 +17722,6 @@
           ],
           "extendsTokenRanges": []
         },
-        {
-          "kind": "Function",
-          "canonicalReference": "@alloy-js/core!pushStack:function(1)",
-          "docComment": "",
-          "excerptTokens": [
-            {
-              "kind": "Content",
-              "text": "export declare function pushStack(component: "
-            },
-            {
-              "kind": "Reference",
-              "text": "Component",
-              "canonicalReference": "@alloy-js/core!Component:interface"
-            },
-            {
-              "kind": "Content",
-              "text": "<any>"
-            },
-            {
-              "kind": "Content",
-              "text": ", props: "
-            },
-            {
-              "kind": "Reference",
-              "text": "Props",
-              "canonicalReference": "@alloy-js/core!Props:type"
-            },
-            {
-              "kind": "Content",
-              "text": "): "
-            },
-            {
-              "kind": "Content",
-              "text": "void"
-            },
-            {
-              "kind": "Content",
-              "text": ";"
-            }
-          ],
-          "fileUrlPath": "src/render.ts",
-          "returnTypeTokenRange": {
-            "startIndex": 6,
-            "endIndex": 7
-          },
-          "releaseTag": "Public",
-          "overloadIndex": 1,
-          "parameters": [
-            {
-              "parameterName": "component",
-              "parameterTypeTokenRange": {
-                "startIndex": 1,
-                "endIndex": 3
-              },
-              "isOptional": false
-            },
-            {
-              "parameterName": "props",
-              "parameterTypeTokenRange": {
-                "startIndex": 4,
-                "endIndex": 5
-              },
-              "isOptional": false
-            }
-          ],
-          "name": "pushStack"
-        },
         {
           "kind": "Class",
           "canonicalReference": "@alloy-js/core!ReactiveUnionSet:class",
@@ -21565,6 +21487,105 @@
           ],
           "name": "sourceFilesForTreeAsync"
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@alloy-js/core!SourceLocation:interface",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface SourceLocation "
+            }
+          ],
+          "fileUrlPath": "src/runtime/component.ts",
+          "releaseTag": "Public",
+          "name": "SourceLocation",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/core!SourceLocation#columnNumber:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "columnNumber: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "columnNumber",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/core!SourceLocation#fileName:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "fileName: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "fileName",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/core!SourceLocation#lineNumber:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "lineNumber: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "lineNumber",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!splitProps:function(1)",