@alloy-js/core 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "",
   "main": "./dist/src/index.js",
   "exports": {
@@ -9,6 +9,7 @@
       "import": "./dist/src/index.js"
     },
     "./jsx-runtime": {
+      "types": "./dist/src/jsx-runtime.d.ts",
       "development": "./src/jsx-runtime.ts",
       "import": "./dist/src/jsx-runtime.js"
     },
@@ -47,7 +48,7 @@
     "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-typescript": "^11.1.6",
     "concurrently": "^8.2.2",
-    "typescript": "^5.5.4",
+    "typescript": "^5.7.3",
     "vitest": "^3.0.4"
   },
   "type": "module",

package/src/binder.ts

@@ -7,6 +7,7 @@ import {
   ShallowRef,
   shallowRef,
 } from "@vue/reactivity";
+import { useBinder } from "./context/binder.js";
 import { useMemberScope } from "./context/member-scope.js";
 import { useScope } from "./context/scope.js";
 import { memo, untrack } from "./jsx-runtime.js";
@@ -223,6 +224,21 @@ export interface OutputScope {
   getSymbolNames(): Set<string>;
 }
 
+export type CreateSymbolOptions<T extends OutputSymbol = OutputSymbol> = {
+  name: string;
+  scope?: OutputScope;
+  refkey?: Refkey;
+  flags?: OutputSymbolFlags;
+} & Omit<T, keyof OutputSymbol>;
+
+export type CreateScopeOptions<T extends OutputScope = OutputScope> = {
+  kind: T["kind"];
+  name: string;
+  parent?: OutputScope | undefined;
+  flags?: OutputScopeFlags;
+  owner?: OutputSymbol;
+} & Omit<T, keyof OutputScope>;
+
 /**
  * The binder tracks all output scopes and symbols. Scopes are nested containers
  * for symbols.
@@ -241,28 +257,13 @@ export interface Binder {
    * Create a new scope. The scope will be added to the parent scope's children.
    * The returned scope object is reactive.
    */
-  createScope<T extends OutputScope>(
-    args: {
-      kind: T["kind"];
-      name: string;
-      parent?: OutputScope | undefined;
-      flags?: OutputScopeFlags;
-      owner?: OutputSymbol;
-    } & Omit<T, keyof OutputScope>,
-  ): T;
+  createScope<T extends OutputScope>(args: CreateScopeOptions<T>): T;
 
   /**
    * Create a new symbol. The symbol will be added to the parent scope's symbols.
    * The returned symbol object is reactive.
    */
-  createSymbol<T extends OutputSymbol>(
-    args: {
-      name: string;
-      scope?: OutputScope;
-      refkey?: unknown;
-      flags?: OutputSymbolFlags;
-    } & Omit<T, keyof OutputSymbol>,
-  ): T;
+  createSymbol<T extends OutputSymbol>(args: CreateSymbolOptions<T>): T;
 
   /**
    * Instantiate the static members of a symbol into the instance members of
@@ -451,15 +452,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
 
   return binder;
 
-  function createScope<T extends OutputScope>(
-    args: {
-      kind: string;
-      name: string;
-      parent?: OutputScope;
-      flags?: OutputScopeFlags;
-      owner?: OutputSymbol;
-    } & Omit<T, keyof OutputScope>,
-  ): T {
+  function createScope<T extends OutputScope>(args: CreateScopeOptions<T>): T {
     const {
       kind,
       name,
@@ -518,12 +511,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   }
 
   function createSymbol<T extends OutputSymbol>(
-    args: {
-      name: string;
-      scope?: OutputScope;
-      refkey?: Refkey;
-      flags?: OutputSymbolFlags;
-    } & Omit<T, keyof OutputSymbol>,
+    args: CreateSymbolOptions<T>,
   ): T {
     const {
       name,
@@ -591,7 +579,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     scope.symbolsByRefkey.set(symbol.refkey, symbol);
 
     deconflict(symbol);
-    notifyRefkey(refkey, symbol);
+    notifyRefkey(symbol);
 
     return symbol;
   }
@@ -807,24 +795,25 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     return computed(() => cb(declSignal.value));
   }
 
-  function notifyRefkey(
-    refkey: Refkey | undefined,
-    symbol: OutputSymbol,
-  ): void {
-    if (!refkey) return;
-    knownDeclarations.set(refkey, symbol);
-    if (waitingDeclarations.has(refkey)) {
-      const signal = waitingDeclarations.get(refkey)!;
-      signal.value = symbol;
-    }
+  function notifyRefkey(symbol: OutputSymbol): void {
+    effect(() => {
+      const refkey = symbol.refkey;
+      if (!refkey) return;
 
-    const waitingScope = waitingSymbolNames.get(symbol.scope);
-    if (waitingScope) {
-      const waitingName = waitingScope.get(symbol.name);
-      if (waitingName) {
-        waitingName.value = symbol;
+      knownDeclarations.set(refkey, symbol);
+      if (waitingDeclarations.has(refkey)) {
+        const signal = waitingDeclarations.get(refkey)!;
+        signal.value = symbol;
       }
-    }
+
+      const waitingScope = waitingSymbolNames.get(symbol.scope);
+      if (waitingScope) {
+        const waitingName = waitingScope.get(symbol.name);
+        if (waitingName) {
+          waitingName.value = symbol;
+        }
+      }
+    });
   }
 
   function findSymbolName<TSymbol extends OutputSymbol = OutputSymbol>(
@@ -949,7 +938,7 @@ export function resolve<
   TScope extends OutputScope,
   TSymbol extends OutputSymbol,
 >(refkey: Refkey): Ref<ResolutionResult<TScope, TSymbol>> {
-  const scope = useScope();
+  const scope = useScope() ?? useBinder().globalScope;
   const memberScope = useMemberScope();
   const binder = scope.binder;
 

package/src/components/Output.tsx

@@ -7,9 +7,10 @@ import { BinderContext } from "../context/binder.js";
 import { NamePolicyContext } from "../context/name-policy.js";
 import { Children } from "../jsx-runtime.js";
 import { NamePolicy } from "../name-policy.js";
+import { extensionEffects } from "../slot.js";
 import { SourceDirectory } from "./SourceDirectory.js";
+
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-import { extensionEffects } from "../slot.js";
 import { SourceFile } from "./SourceFile.js";
 
 export interface OutputProps {

package/src/components/SourceDirectory.tsx

@@ -6,7 +6,7 @@ import { Children, getContext } from "../jsx-runtime.js";
 
 export interface SourceDirectoryProps {
   path: string;
-  children?: Children[];
+  children?: Children;
 }
 
 export function SourceDirectory(props: SourceDirectoryProps) {

package/src/components/SourceFile.tsx

@@ -17,7 +17,7 @@ export interface SourceFileProps {
    */
   filetype: string;
 
-  children?: Children[];
+  children?: Children;
 
   /**
    * The component to use to render refkeys references within the file's

package/src/context/member-declaration.ts

@@ -1,5 +1,9 @@
 import { OutputSymbol } from "../binder.js";
-import { ComponentContext, createNamedContext } from "../context.js";
+import {
+  ComponentContext,
+  createNamedContext,
+  useContext,
+} from "../context.js";
 
 /**
  * Provides the symbol for the member currently being declared.
@@ -8,3 +12,7 @@ import { ComponentContext, createNamedContext } from "../context.js";
  */
 export const MemberDeclarationContext: ComponentContext<OutputSymbol> =
   createNamedContext("MemberDeclaration");
+
+export function useMemberDeclaration() {
+  return useContext(MemberDeclarationContext);
+}

package/src/index.ts

@@ -17,6 +17,7 @@ export * from "./jsx-runtime.js";
 export * from "./name-policy.js";
 export * from "./refkey.js";
 export * from "./render.js";
+export * from "./tap.js";
 export * from "./utils.js";
 export * from "./write-output.js";
 import "./debug.js";

package/src/jsx-runtime.ts

@@ -117,7 +117,7 @@ export function effect<T>(fn: (prev?: T) => T, current?: T) {
   cleanup(() => cleanupFn(true));
 }
 
-function cleanup(fn: Disposable) {
+export function cleanup(fn: Disposable) {
   if (globalContext != null) {
     globalContext.disposables.push(fn);
   }
@@ -129,13 +129,14 @@ export type Child =
   | number
   | undefined
   | null
-  | (() => Child | Children)
+  | void
+  | (() => Children)
   | Child[]
   | Ref
   | Refkey;
 
 export type Children = Child | Child[];
-export type Props = Record<string, unknown>;
+export type Props = Record<string, any>;
 
 export interface ComponentDefinition<TProps = Props> {
   (props: TProps): Child | Children;
@@ -212,6 +213,29 @@ export function isComponentCreator(item: unknown): item is ComponentCreator {
   return typeof item === "function" && (item as any).component;
 }
 
+/**
+ * This namespace is predominantly for interop with React tooling in VSCode
+ * and controls the type of JSX elements, components, and the like.
+ */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace JSX {
+  export interface IntrinsicElements {}
+  export type ElementType = ComponentDefinition<any>;
+  export type Element = Children;
+  export interface ElementChildrenAttribute {
+    children: {};
+  }
+  export interface ElementAttributesProperty {
+    props: {};
+  }
+}
+
+export function jsx(type: Component<any>, props: Record<string, unknown>) {
+  return createComponent(type, props);
+}
+
+export const jsxs = jsx;
+
 export function createComponent<TProps extends Props = Props>(
   C: Component<TProps>,
   props: TProps,

package/src/render.ts

@@ -171,7 +171,7 @@ export type RenderStructure = {};
 
 export type RenderTextTree = (string | RenderTextTree)[];
 
-function traceRender(phase: string, message: string) {
+function traceRender(phase: string, message: () => string) {
   return false;
   // console.log(`[\x1b[34m${phase}\x1b[0m]: ${message}`);
 }
@@ -268,7 +268,7 @@ function renderWorker(
   children: Children,
   state: RenderState,
 ) {
-  traceRender("render", dumpChildren(children));
+  traceRender("render", () => dumpChildren(children));
 
   if (Array.isArray(node)) {
     nodesToContext.set(node, getContext()!);
@@ -290,7 +290,7 @@ function appendChild(
   indentState: IndentState,
   state: RenderState,
 ) {
-  traceRender("appendChild", printChild(rawChild));
+  traceRender("appendChild", () => printChild(rawChild));
   const child = normalizeChild(rawChild);
 
   if (typeof child === "string") {
@@ -300,11 +300,11 @@ function appendChild(
       state.newline = false;
     }
     const reindented = reindent(child, indentState.indentString);
-    traceRender("appendChild:string", JSON.stringify(reindented));
+    traceRender("appendChild:string", () => JSON.stringify(reindented));
     node.push(reindented);
   } else if (isComponentCreator(child)) {
     root(() => {
-      traceRender("appendChild:component", printChild(child));
+      traceRender("appendChild:component", () => printChild(child));
       if (child.component === Indent && state.newline) {
         node.push(indentState.indent);
       }
@@ -313,13 +313,13 @@ function appendChild(
       renderWorker(componentRoot, untrack(child), state);
       popStack();
       node.push(componentRoot);
-      traceRender("appendChild:component-done", printChild(child));
+      traceRender("appendChild:component-done", () => printChild(child));
     }, child);
   } else if (typeof child === "function") {
-    traceRender("appendChild:memo", child.toString());
+    traceRender("appendChild:memo", () => child.toString());
     const index = node.length;
     effect((prev: any) => {
-      traceRender("memoEffect:run", "");
+      traceRender("memoEffect:run", () => "");
       let res = child();
       while (typeof res === "function" && !isComponentCreator(res)) {
         res = res();
@@ -330,11 +330,11 @@ function appendChild(
       node[index] = newNodes;
       return newNodes;
     });
-    traceRender("appendChild:memo-done", "");
+    traceRender("appendChild:memo-done", () => "");
   } else {
-    traceRender("appendChild:array", dumpChildren(child));
+    traceRender("appendChild:array", () => dumpChildren(child));
     renderWorker(node, child, state);
-    traceRender("appendChild:array-done", dumpChildren(child));
+    traceRender("appendChild:array-done", () => dumpChildren(child));
   }
 }
 
@@ -383,6 +383,8 @@ function printChild(child: Child): string {
     return "<" + child.component.name + ">";
   } else if (typeof child === "function") {
     return "$memo";
+  } else if (isRef(child)) {
+    return "$ref";
   } else {
     return JSON.stringify(child);
   }

package/src/tap.ts

@@ -0,0 +1,69 @@
+import { ShallowRef, shallowRef } from "@vue/reactivity";
+import { OutputScope, OutputSymbol } from "./binder.js";
+import { useContext } from "./context.js";
+import { DeclarationContext } from "./context/declaration.js";
+import { MemberDeclarationContext } from "./context/member-declaration.js";
+import { useScope } from "./context/scope.js";
+import { SourceFileContext } from "./context/source-file.js";
+import { ComponentDefinition } from "./jsx-runtime.js";
+
+export interface Tap<T> extends ComponentDefinition {
+  ref: ShallowRef<T | undefined>;
+}
+
+export interface Tapper<T> {
+  (): T | undefined;
+}
+
+export interface Handler<T> {
+  (value: T): void;
+}
+
+export function createTap<T = unknown>(
+  tapper: Tapper<T>,
+  handler?: Handler<T>,
+): Tap<T> {
+  const signal = shallowRef<T | undefined>(undefined);
+  const fn = () => {
+    signal.value = tapper();
+    if (handler && signal.value !== undefined) {
+      handler(signal.value);
+    }
+
+    return "";
+  };
+
+  fn.ref = signal;
+
+  return fn;
+}
+
+export function createDeclarationTap<
+  TSymbol extends OutputSymbol = OutputSymbol,
+>(handler?: Handler<TSymbol>) {
+  return createTap<TSymbol>(() => {
+    return useContext(DeclarationContext) as any;
+  }, handler);
+}
+
+export function createMemberTap<TSymbol extends OutputSymbol = OutputSymbol>(
+  handler?: Handler<TSymbol>,
+) {
+  return createTap<TSymbol>(() => {
+    return useContext(MemberDeclarationContext) as any;
+  }, handler);
+}
+
+export function createScopeTap<TScope extends OutputScope = OutputScope>(
+  handler?: Handler<TScope>,
+) {
+  return createTap<TScope>(() => {
+    return useScope() as any;
+  }, handler);
+}
+
+export function createSourceFileTap(handler?: Handler<SourceFileContext>) {
+  return createTap(() => {
+    return useContext(SourceFileContext);
+  }, handler);
+}