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

package/src/components/AccessExpression.tsx

@@ -0,0 +1,344 @@
+import {
+  Children,
+  childrenArray,
+  ComponentCreator,
+  ComponentDefinition,
+  computed,
+  isComponentCreator,
+  OutputSymbol,
+  Refkeyable,
+  symbolForRefkey,
+  takeSymbols,
+} from "../index.js";
+
+/**
+ * Base props that all language-specific Part components must include.
+ * Language packages extend this with additional props.
+ */
+export interface BasePartProps {
+  refkey?: Refkeyable;
+  symbol?: OutputSymbol;
+}
+
+/**
+ * Configuration for creating a language-specific access expression component.
+ *
+ * @typeParam TPartProps - The Part component's props type (extends BasePartProps)
+ * @typeParam TPart - The descriptor type that formatPart receives
+ */
+export interface AccessExpressionConfig<
+  TPartProps extends BasePartProps,
+  TPart,
+> {
+  /**
+   * Convert Part props + resolved symbol into a plain descriptor object.
+   * Called once per Part during children processing. The returned descriptor
+   * is wrapped in a computed + getter delegation for reactive optimization.
+   */
+  createDescriptor(
+    props: TPartProps,
+    symbol: OutputSymbol | undefined,
+    first: boolean,
+  ): TPart;
+
+  /**
+   * Extract the base content from the first part (the leftmost identifier).
+   */
+  getBase(part: TPart): Children;
+
+  /**
+   * Format a non-first part given its descriptor and the previous part.
+   * Returns JSX children for that segment (e.g., `.foo`, `?.bar`, `[idx]`, `(args)`).
+   * `inCallChain` is true when rendering inside a chunked call chain.
+   */
+  formatPart(part: TPart, prevPart: TPart, inCallChain: boolean): Children;
+
+  /**
+   * Identify which parts are function calls, for call chain detection.
+   * When provided, the factory uses the chunked call chain algorithm
+   * (line breaks after each call group) when more than one call is detected.
+   * When omitted, the expression is always formatted linearly.
+   */
+  isCallPart?(part: TPart): boolean;
+
+  /**
+   * Additional check for whether call chain formatting should be used.
+   * Called only when `isCallPart` is provided and more than one call is detected.
+   * Return false to force linear formatting (e.g., TypeScript disables call
+   * chains when any part has `await`).
+   * Defaults to `() => true`.
+   */
+  canUseCallChains?(parts: TPart[]): boolean;
+
+  /**
+   * Post-process the accumulated expression after each part in linear
+   * (non-call-chain) mode. Use this for language-specific wrapping like
+   * TypeScript's `await` which wraps the entire expression so far.
+   * Defaults to identity (returns expression unchanged).
+   */
+  wrapPartResult?(
+    expression: Children,
+    part: TPart,
+    index: number,
+    isLast: boolean,
+  ): Children;
+}
+
+/**
+ * Create a language-specific access/member expression component pair.
+ *
+ * Returns `{ Expression, Part }` where:
+ * - `Expression` is the main component that collects Part children and renders the chain
+ * - `Part` is a no-op component whose props are consumed by Expression
+ *
+ * The factory handles:
+ * - Children collection and Part filtering
+ * - Symbol resolution (refkey → symbol via binder, single computed per part)
+ * - Reactive optimization (getter delegation over single computed per part)
+ * - Flattening nested Expression instances
+ * - `takeSymbols()` to prevent symbol leakage
+ * - Call chain detection and chunked formatting algorithm
+ */
+export function createAccessExpression<
+  TPartProps extends BasePartProps,
+  TPart extends Record<string, unknown>,
+>(config: AccessExpressionConfig<TPartProps, TPart>) {
+  // Additional component references to match during flattening.
+  // Used when the wrapper function (e.g. MemberExpression) differs
+  // from the inner Expression function.
+  const outerComponents: ComponentDefinition<any>[] = [];
+
+  function Expression(props: { children: Children }): Children {
+    const children = flattenExpression(childrenArray(() => props.children));
+    const parts = collectParts(children);
+    takeSymbols();
+
+    if (parts.length === 0) {
+      return <></>;
+    }
+
+    const { isCallPart, canUseCallChains } = config;
+
+    if (!isCallPart) {
+      return formatLinear(config, parts);
+    }
+
+    const isCallChain = computed(() => {
+      if (canUseCallChains && !canUseCallChains(parts)) {
+        return false;
+      }
+      let callCount = 0;
+      for (const part of parts) {
+        if (isCallPart(part)) callCount++;
+      }
+      return callCount > 1;
+    });
+
+    return () => {
+      return isCallChain.value ?
+          formatCallChain(config, parts)
+        : formatLinear(config, parts);
+    };
+  }
+
+  function Part(_props: TPartProps) {
+    // No-op — props are consumed by the parent Expression component.
+  }
+
+  function isExpressionComponent(child: unknown): boolean {
+    if (isComponentCreator(child, Expression)) return true;
+    for (const comp of outerComponents) {
+      if (isComponentCreator(child, comp as any)) return true;
+    }
+    return false;
+  }
+
+  function flattenExpression(children: Children[]): Children[] {
+    const flattened: Children[] = [];
+    for (const child of children) {
+      if (isExpressionComponent(child)) {
+        flattened.push(
+          ...flattenExpression(
+            childrenArray(() => (child as ComponentCreator).props.children),
+          ),
+        );
+      } else {
+        flattened.push(child);
+      }
+    }
+    return flattened;
+  }
+
+  function collectParts(children: Children[]): TPart[] {
+    const parts: TPart[] = [];
+    for (const child of children) {
+      if (!isComponentCreator(child, Part)) continue;
+      const partProps = child.props as TPartProps;
+      const first = parts.length === 0;
+
+      const symbolSource = computed(() => {
+        if (partProps.refkey) {
+          return symbolForRefkey(partProps.refkey).value;
+        } else if (partProps.symbol) {
+          return partProps.symbol;
+        }
+        return undefined;
+      });
+
+      const desc = computed(() =>
+        config.createDescriptor(partProps, symbolSource.value, first),
+      );
+
+      // Create getter-delegation object for reactive optimization.
+      // Property access on this object tracks the single `desc` computed.
+      const keys = Object.keys(
+        config.createDescriptor(partProps, undefined, first),
+      );
+      const proxy: Record<string, unknown> = {};
+      for (const key of keys) {
+        Object.defineProperty(proxy, key, {
+          get() {
+            return (desc.value as Record<string, unknown>)[key];
+          },
+          enumerable: true,
+        });
+      }
+
+      parts.push(proxy as TPart);
+    }
+    return parts;
+  }
+
+  /**
+   * Register an outer wrapper component for flattening support.
+   * Call this after creating the wrapper function:
+   *   `registerOuterComponent(MemberExpression);`
+   */
+  function registerOuterComponent(component: ComponentDefinition<any>) {
+    outerComponents.push(component);
+  }
+
+  return { Expression, Part, registerOuterComponent };
+}
+
+/**
+ * Format parts linearly (no call chain grouping).
+ */
+function formatLinear<TPartProps extends BasePartProps, TPart>(
+  config: AccessExpressionConfig<TPartProps, TPart>,
+  parts: TPart[],
+): Children {
+  return computed(() => {
+    let expression: Children = [];
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+
+      if (i === 0) {
+        (expression as Children[]).push(config.getBase(part));
+      } else {
+        const prevPart = parts[i - 1];
+        const partExpr = config.formatPart(part, prevPart, false);
+
+        if (Array.isArray(expression)) {
+          expression.push(partExpr);
+        } else {
+          expression = (
+            <>
+              {expression}
+              {partExpr}
+            </>
+          );
+        }
+      }
+
+      if (config.wrapPartResult) {
+        expression = config.wrapPartResult(
+          expression,
+          part,
+          i,
+          i === parts.length - 1,
+        );
+      }
+    }
+
+    return expression;
+  });
+}
+
+/**
+ * Format parts as a call chain with indented line breaks at call boundaries.
+ */
+function formatCallChain<TPartProps extends BasePartProps, TPart>(
+  config: AccessExpressionConfig<TPartProps, TPart>,
+  parts: TPart[],
+): Children {
+  return computed(() => {
+    const expression: Children[] = [];
+    const chunks: TPart[][] = [];
+    let pi = 0;
+
+    function pushPart() {
+      chunks.at(-1)!.push(parts[pi]);
+      pi++;
+    }
+
+    function pushChunk() {
+      chunks.push([]);
+    }
+
+    // First chunk: take parts up to and including the first call
+    pushChunk();
+    while (
+      pi < parts.length &&
+      (pi === parts.length - 1 ||
+        chunks.at(-1)!.length === 0 ||
+        !config.isCallPart!(parts[pi + 1]))
+    ) {
+      pushPart();
+      if (config.isCallPart!(chunks.at(-1)!.at(-1)!)) {
+        break;
+      }
+    }
+
+    // Remaining chunks: collect non-call parts then call parts
+    while (pi < parts.length) {
+      pushChunk();
+      while (pi < parts.length && !config.isCallPart!(parts[pi])) {
+        pushPart();
+      }
+      while (pi < parts.length && config.isCallPart!(parts[pi])) {
+        pushPart();
+      }
+    }
+
+    for (let ci = 0; ci < chunks.length; ci++) {
+      const chunk = chunks[ci];
+      const chunkExpr = [];
+      for (let cpi = 0; cpi < chunk.length; cpi++) {
+        if (ci === 0 && cpi === 0) {
+          chunkExpr.push(config.getBase(chunk[0]));
+          continue;
+        }
+        const part = chunk[cpi];
+        const prevPart = cpi === 0 ? chunks[ci - 1].at(-1)! : chunk[cpi - 1];
+        chunkExpr.push(config.formatPart(part, prevPart, true));
+      }
+
+      expression.push(
+        ci === 0 ? chunkExpr : (
+          <>
+            <sbr />
+            {chunkExpr}
+          </>
+        ),
+      );
+    }
+
+    return (
+      <group>
+        <indent>{expression}</indent>
+      </group>
+    );
+  });
+}

package/src/components/AppendFile.tsx

@@ -2,6 +2,7 @@ import { computed } from "@vue/reactivity";
 import { join } from "pathe";
 import { useContext } from "../context.js";
 import { SourceDirectoryContext } from "../context/source-directory.js";
+import { emitDiagnostic } from "../diagnostics.js";
 import { createFileResource } from "../resource.js";
 import { Children, isComponentCreator } from "../runtime/component.js";
 import { childrenArray } from "../utils.jsx";
@@ -98,9 +99,11 @@ export function AppendFile(props: AppendFileProps): Children {
       } else if ("content" in regionProps) {
         content = regionProps.content;
       } else {
-        throw new Error(
-          `AppendRegion "${regionProps.id}" must have either children or content`,
-        );
+        emitDiagnostic({
+          message: `AppendRegion "${regionProps.id}" must have either children or content`,
+          severity: "error",
+        });
+        // Still register the region to avoid duplicate "region not found" diagnostic
       }
 
       appendRegions[regionProps.id] = content;
@@ -115,9 +118,10 @@ export function AppendFile(props: AppendFileProps): Children {
   // Validate that all requested regions have corresponding AppendRegion children
   for (const regionId of regions) {
     if (!(regionId in appendRegions)) {
-      throw new Error(
-        `Region "${regionId}" specified but no corresponding AppendRegion child found`,
-      );
+      emitDiagnostic({
+        message: `Region "${regionId}" specified but no corresponding AppendRegion child found`,
+        severity: "error",
+      });
     }
   }
 
@@ -181,9 +185,10 @@ export function AppendFile(props: AppendFileProps): Children {
     for (const regionId of regions) {
       const info = sigilInfo[regionId];
       if (info && info.start !== null && info.end === null) {
-        throw new Error(
-          `Region "${regionId}" has start sigil but no corresponding end sigil`,
-        );
+        emitDiagnostic({
+          message: `Region "${regionId}" has start sigil but no corresponding end sigil`,
+          severity: "error",
+        });
       }
     }
 

package/src/components/Block.tsx

@@ -1,5 +1,5 @@
-import { computed } from "@vue/reactivity";
 import { createContentSlot } from "../content-slot.jsx";
+import { computed } from "../reactivity.js";
 import type { Children } from "../runtime/component.js";
 import { Indent } from "./Indent.jsx";
 

package/src/components/Declaration.tsx

@@ -1,3 +1,4 @@
+import { createSymbol } from "../binder.js";
 import { useContext } from "../context.js";
 import { BinderContext } from "../context/binder.js";
 import { DeclarationContext } from "../context/declaration.js";
@@ -83,7 +84,7 @@ export function Declaration(props: DeclarationProps) {
       );
     }
 
-    declaration = new BasicSymbol(props.name, scope.symbols, {
+    declaration = createSymbol(BasicSymbol, props.name, scope.symbols, {
       binder,
       refkeys: [props.refkey ?? []].flat(),
       metadata: props.metadata,

package/src/components/For.tsx

@@ -80,15 +80,19 @@ export function For<
   const cb = props.children;
   const options = baseListPropsToMapJoinArgs(props);
   options.skipFalsy = props.skipFalsy;
-  return memo(() => {
-    const maybeRef = props.each;
+  return memo(
+    () => {
+      const maybeRef = props.each;
 
-    return (mapJoin as any)(
-      typeof maybeRef === "function" ? maybeRef : (
-        () => (isRef(maybeRef) ? maybeRef.value : maybeRef)
-      ),
-      cb,
-      options,
-    );
-  });
+      return (mapJoin as any)(
+        typeof maybeRef === "function" ? maybeRef : (
+          () => (isRef(maybeRef) ? maybeRef.value : maybeRef)
+        ),
+        cb,
+        options,
+      );
+    },
+    undefined,
+    "For",
+  );
 }

package/src/components/List.tsx

@@ -57,10 +57,13 @@ export interface ListProps extends BaseListProps {
  */
 export function List(props: ListProps) {
   const [rest, forProps] = splitProps(props, ["children"]);
-  const resolvedChildren = memo(() =>
-    childrenArray(() => rest.children, {
-      preserveFragments: true,
-    }),
+  const resolvedChildren = memo(
+    () =>
+      childrenArray(() => rest.children, {
+        preserveFragments: true,
+      }),
+    undefined,
+    "List:children",
   );
   return (
     <For each={resolvedChildren} {...forProps} skipFalsy>

package/src/components/Prose.tsx

@@ -22,7 +22,7 @@ export function Prose(props: Prose) {
             .map((word, index, array) => (
               <>
                 {word}
-                {index < array.length - 1 && <br />}
+                {/*@once*/ index < array.length - 1 && <br />}
               </>
             ));
         }

package/src/components/Scope.tsx

@@ -1,4 +1,6 @@
+import { createScope } from "../binder.js";
 import { ScopeContext, useScope } from "../context/scope.js";
+import { debug } from "../debug/index.js";
 import type { Children } from "../runtime/component.js";
 import { BasicScope } from "../symbols/basic-scope.js";
 import { OutputScope } from "../symbols/output-scope.js";
@@ -51,6 +53,7 @@ export function Scope(props: ScopeProps) {
   let scope: OutputScope;
   if ("value" in props) {
     scope = props.value;
+    debug.symbols.relocateScope(scope);
   } else {
     const parentScope = useScope();
     if (parentScope && !(parentScope instanceof BasicScope)) {
@@ -58,7 +61,9 @@ export function Scope(props: ScopeProps) {
         "Scope component can only make scopes within a BasicScope",
       );
     }
-    scope = new BasicScope(props.name ?? "", parentScope, {
+    const binder = parentScope?.binder;
+    scope = createScope(BasicScope, props.name ?? "", parentScope, {
+      binder,
       metadata: props.metadata,
       ownerSymbol: props.ownerSymbol,
     });

package/src/components/SourceDirectory.tsx

@@ -1,8 +1,7 @@
-import { shallowReactive } from "@vue/reactivity";
 import { join } from "pathe";
 import { useContext } from "../context.js";
 import { SourceDirectoryContext } from "../context/source-directory.js";
-import { getContext } from "../reactivity.js";
+import { getContext, shallowReactive } from "../reactivity.js";
 import type { Children } from "../runtime/component.js";
 
 export interface SourceDirectoryProps {

package/src/components/Switch.tsx

@@ -27,15 +27,19 @@ export function Switch(props: SwitchProps) {
   const children = childrenArray(() => props.children);
   const matches = findKeyedChildren(children, matchTag);
 
-  return memo(() => {
-    for (const match of matches) {
-      if (match.props.when || match.props.else) {
-        return match.props.children;
+  return memo(
+    () => {
+      for (const match of matches) {
+        if (match.props.when || match.props.else) {
+          return match.props.children;
+        }
       }
-    }
 
-    return undefined;
-  });
+      return undefined;
+    },
+    undefined,
+    "Switch",
+  );
 }
 
 export interface MatchProps {

package/src/components/TemplateFile.tsx

@@ -1,4 +1,5 @@
 import { computed } from "@vue/reactivity";
+import { emitDiagnostic } from "../diagnostics.js";
 import { createFileResource } from "../resource.js";
 import { Children, isComponentCreator } from "../runtime/component.js";
 import { childrenArray } from "../utils.jsx";
@@ -85,9 +86,12 @@ export function TemplateFile(props: TemplateFileProps): Children {
     } else if ("value" in variableProps) {
       value = variableProps.value;
     } else {
-      throw new Error(
-        `TemplateVariable "${variableProps.name}" must have either children or value`,
-      );
+      emitDiagnostic({
+        message: `TemplateVariable "${variableProps.name}" must have either children or value`,
+        severity: "error",
+      });
+      // Still register the variable to avoid duplicate diagnostics
+      value = "";
     }
 
     templateVariables[variableProps.name] = value;
@@ -100,9 +104,11 @@ export function TemplateFile(props: TemplateFileProps): Children {
     }
 
     if (templateResource.error) {
-      throw new Error(
-        `Failed to read template file "${props.src}": ${templateResource.error}`,
-      );
+      emitDiagnostic({
+        message: `Failed to read template file "${props.src}": ${templateResource.error}`,
+        severity: "error",
+      });
+      return "";
     }
 
     const templateContent = templateResource.data!;
@@ -131,9 +137,12 @@ export function TemplateFile(props: TemplateFileProps): Children {
       if (variableName in templateVariables) {
         result.push(templateVariables[variableName]);
       } else {
-        throw new Error(
-          `Template variable "${variableName}" not found in TemplateVariable children`,
-        );
+        emitDiagnostic({
+          message: `Template variable "${variableName}" not found in TemplateVariable children`,
+          severity: "error",
+        });
+        // Keep the placeholder in the output to make the error visible
+        result.push(`{{ ${variableName} }}`);
       }
 
       lastIndex = matchStart + fullMatch.length;

package/src/components/index.tsx

@@ -1,3 +1,4 @@
+export * from "./AccessExpression.jsx";
 export * from "./AppendFile.jsx";
 export * from "./Block.js";
 export * from "./CopyFile.jsx";

package/src/content-slot.tsx

@@ -1,6 +1,6 @@
-import { effect, Ref, shallowRef } from "@vue/reactivity";
+import { computed, Ref, shallowRef } from "@vue/reactivity";
 import { Show } from "./components/Show.jsx";
-import { getContext } from "./reactivity.js";
+import { ensureIsEmpty, getContext } from "./reactivity.js";
 import { Children, Component } from "./runtime/component.js";
 
 export interface ContentSlot {
@@ -54,14 +54,14 @@ export interface ContentSlot {
  * ```
  */
 export function createContentSlot(): ContentSlot {
-  const isEmpty = shallowRef<boolean>(false);
+  // Holds a reference to the rendering context's isEmpty ref once ContentSlot
+  // renders. Before that, reads fall through to a default of "not empty".
+  const isEmptySource = shallowRef<Ref<boolean>>();
+  const isEmpty = computed(() => isEmptySource.value?.value ?? false);
 
   function ContentSlot(props: { children: Children }) {
     const context = getContext()!;
-    effect(() => {
-      isEmpty.value = context.isEmpty!.value;
-    });
-
+    isEmptySource.value = ensureIsEmpty(context);
     return props.children;
   }
   ContentSlot.ref = isEmpty;

package/src/context.ts

@@ -20,8 +20,8 @@ export function useContext<T>(context: ComponentContext<T>): T | undefined {
   // context must come from a parent
   let current = getContext();
   while (current) {
-    if (Object.hasOwn(current.context!, context.id)) {
-      return current.context![context.id] as T | undefined;
+    if (current.context && Object.hasOwn(current.context, context.id)) {
+      return current.context[context.id] as T | undefined;
     }
     current = current.owner;
   }
@@ -38,12 +38,22 @@ export function createContext<T = unknown>(
   const id = Symbol(name ?? "context");
   function Provider(props: ContextProviderProps<T>) {
     const context = getContext();
+    const contextName = name ?? "anonymous";
 
     const rendered = shallowRef();
-    effect(() => {
-      context!.context![id] = props.value;
-      rendered.value = () => props.children;
-    }, undefined);
+    effect(
+      () => {
+        (context!.context ??= {})[id] = props.value;
+        rendered.value = () => props.children;
+      },
+      undefined,
+      {
+        debug: {
+          name: `context:provider:${contextName}`,
+          type: "context",
+        },
+      },
+    );
 
     return rendered.value;
   }
@@ -54,6 +64,7 @@ export function createContext<T = unknown>(
     Provider,
     ProviderStc: stc(Provider),
   };
+  (Provider as any).contextName = name;
   contextsByKey.set(id, ctx);
   return ctx;
 }