@alloy-js/core 0.5.0 → 0.6.0

package/package.json

@@ -1,28 +1,24 @@
 {
   "name": "@alloy-js/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "",
   "main": "./dist/src/index.js",
   "exports": {
     ".": {
-      "development": "./src/index.ts",
+      "browser": "./dist/src/index.browser.js",
       "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"
     },
     "./testing": {
-      "development": "./testing/index.ts",
       "import": "./dist/testing/index.js"
     },
     "./stc": {
-      "development": "./src/components/stc/index.ts",
       "import": "./dist/src/components/stc/index.js"
     },
     "./components": {
-      "development": "./src/components/index.ts",
       "import": "./dist/src/components/index.js"
     }
   },
@@ -40,7 +36,8 @@
     "chalk": "^5.3.0",
     "cli-table3": "^0.6.5",
     "pathe": "^1.1.2",
-    "@alloy-js/babel-preset": "~0.1.1"
+    "prettier": "^3.5.1",
+    "@alloy-js/babel-preset": "~0.2.0"
   },
   "devDependencies": {
     "@babel/cli": "^7.24.7",
@@ -49,7 +46,8 @@
     "@rollup/plugin-typescript": "^11.1.6",
     "concurrently": "^8.2.2",
     "typescript": "^5.7.3",
-    "vitest": "^3.0.4"
+    "vitest": "^3.0.4",
+    "vite": "^6.0.1"
   },
   "type": "module",
   "scripts": {

package/src/binder.ts

@@ -265,6 +265,12 @@ export interface Binder {
    */
   createSymbol<T extends OutputSymbol>(args: CreateSymbolOptions<T>): T;
 
+  /**
+   * Delete the given symbol. The symbol will be removed from its parent's
+   * scope. Any resolutions to this symbol will become undefined.
+   */
+  deleteSymbol(symbol: OutputSymbol): void;
+
   /**
    * Instantiate the static members of a symbol into the instance members of
    * another symbol.
@@ -415,6 +421,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   const binder: Binder = {
     createScope,
     createSymbol,
+    deleteSymbol,
     resolveDeclarationByKey,
     addStaticMembersToSymbol,
     addInstanceMembersToSymbol,
@@ -584,6 +591,18 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     return symbol;
   }
 
+  function deleteSymbol(symbol: OutputSymbol) {
+    symbol.scope.symbols.delete(symbol);
+
+    if (!refkey) {
+      return;
+    }
+
+    const resolution = waitingDeclarations.get(symbol.refkey);
+    if (!resolution) return;
+    resolution.value = undefined;
+  }
+
   function instantiateSymbolInto(source: OutputSymbol, target: OutputSymbol) {
     if (~source.flags & OutputSymbolFlags.InstanceMemberContainer) {
       throw new Error("Can only instantiate symbols with instance members");
@@ -800,12 +819,14 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       const refkey = symbol.refkey;
       if (!refkey) return;
 
+      // notify those waiting for this refkey
       knownDeclarations.set(refkey, symbol);
       if (waitingDeclarations.has(refkey)) {
         const signal = waitingDeclarations.get(refkey)!;
         signal.value = symbol;
       }
 
+      // notify those waiting for this symbol name
       const waitingScope = waitingSymbolNames.get(symbol.scope);
       if (waitingScope) {
         const waitingName = waitingScope.get(symbol.name);

package/src/code.ts

@@ -1,16 +1,16 @@
 // this code is split into a tokenizer and a parser of sorts because I feel like
 // it should be psosible to share logic between this and the babel transform, but
 // this is an exercise for the future.
-import { Child, Indent } from "@alloy-js/core";
-
+import { hbr, indent } from "./components/stc/index.js";
+import { Child, Children } from "./jsx-runtime.js";
 interface IndentLevelData {
   kind: "indent";
-  children: (string | Child | IndentLevelData)[];
+  children: (string | Children | IndentLevelData)[];
   pendingLines: string[];
 }
 export function code(
   template: TemplateStringsArray,
-  ...substitutions: Child[]
+  ...substitutions: Children[]
 ) {
   const indentNodes: IndentLevelData[] = [
     {
@@ -39,6 +39,8 @@ export function code(
   popIndent();
   flushLines();
 
+  return childNodesFor(indentNodes[0]);
+
   function childNodesFor(indentNode: IndentLevelData): Child[] {
     return indentNode.children.map((child) => {
       if (
@@ -46,16 +48,13 @@ export function code(
         child !== null &&
         (child as any).kind === "indent"
       ) {
-        return () =>
-          Indent({ children: childNodesFor(child as IndentLevelData) });
+        return indent({ children: childNodesFor(child as IndentLevelData) });
       } else {
         return child as Child;
       }
     });
   }
 
-  return childNodesFor(indentNodes[0]);
-
   function pushIndent() {
     flushLines();
     const newIndent: IndentLevelData = {
@@ -63,7 +62,7 @@ export function code(
       children: [],
       pendingLines: [""],
     };
-    indentNodes.at(-1)!.children.push(newIndent as any);
+    indentNodes.at(-1)!.children.push(newIndent);
     indentNodes.push(newIndent);
   }
 
@@ -84,7 +83,13 @@ export function code(
   }
   function flushLines() {
     const currentIndent = indentNodes.at(-1)!;
-    currentIndent.children.push(currentIndent.pendingLines.join("\n"));
+    currentIndent.children.push(
+      ...currentIndent.pendingLines
+        .map((str, index) =>
+          index < currentIndent.pendingLines.length - 1 ? [str, hbr()] : [str],
+        )
+        .flat(),
+    );
     currentIndent.pendingLines = [];
   }
 }
@@ -103,12 +108,12 @@ interface LineToken extends ChildTokenBase {
 
 interface OtherToken extends ChildTokenBase {
   kind: "other";
-  value: Child;
+  value: Children;
 }
 
 function* childTokens(
   template: TemplateStringsArray,
-  substitutions: Child[],
+  substitutions: Children[],
 ): IterableIterator<ChildToken> {
   let newline = false;
   const indentStack: { level: number; literalIndent: string }[] = [

package/src/components/Block.tsx

@@ -0,0 +1,44 @@
+import { Children, childrenArray, computed, Indent } from "@alloy-js/core";
+
+export interface BlockProps {
+  /**
+   * The opening punctuation of the block. Defaults to "\{".
+   */
+  opener?: string;
+
+  /**
+   * The closing punctuation of the block. Defaults to "\}".
+   */
+  closer?: string;
+
+  /**
+   * Whether the block starts on a new line. When true, a hardline is added
+   * prior to the block.
+   */
+  newline?: boolean;
+
+  /** The block's contents */
+  children?: Children;
+}
+
+/**
+ * Create an indented block of source text. The block has `opener` text which is
+ * added prior to the block, which defaults to "\{", and `closer` text which is
+ * added after the block, which defaults to "\}".
+ */
+export function Block(props: BlockProps) {
+  const childCount = computed(() => childrenArray(() => props.children).length);
+  return (
+    <group>
+      {props.newline && <br />}
+      {props.opener ?? "{"}
+      <Indent break={childCount.value > 0 ? "hard" : "soft"}>
+        {props.children}
+      </Indent>
+      {childCount.value > 0 ?
+        <hbr />
+      : <sbr />}
+      {props.closer ?? "}"}
+    </group>
+  );
+}

package/src/components/Declaration.tsx

@@ -2,7 +2,7 @@ import { OutputSymbol } from "../binder.js";
 import { useContext } from "../context.js";
 import { BinderContext } from "../context/binder.js";
 import { DeclarationContext } from "../context/declaration.js";
-import { Children } from "../jsx-runtime.js";
+import { Children, onCleanup } from "../jsx-runtime.js";
 import { Refkey, refkey } from "../refkey.js";
 
 export interface DeclarationProps {
@@ -45,9 +45,15 @@ export function Declaration(props: DeclarationProps) {
       name: props.name!,
       refkey: rk,
     });
+
+    onCleanup(() => {
+      binder.deleteSymbol(declaration!);
+    });
   }
 
-  return <DeclarationContext.Provider value={declaration}>
-    {props.children}
-  </DeclarationContext.Provider>;
+  return (
+    <DeclarationContext.Provider value={declaration}>
+      {props.children}
+    </DeclarationContext.Provider>
+  );
 }

package/src/components/For.tsx

@@ -0,0 +1,81 @@
+import { Children, memo } from "@alloy-js/core/jsx-runtime";
+import { isRef, Ref } from "@vue/reactivity";
+import { mapJoin } from "../utils.js";
+import { BaseListProps, baseListPropsToMapJoinArgs } from "./List.jsx";
+
+export type ForCallbackArgs<T> =
+  T extends Ref<infer U> ? ForCallbackArgs<U>
+  : T extends () => infer U ? ForCallbackArgs<U>
+  : T extends (infer U)[] ? [value: U]
+  : T extends Map<infer U, infer V> ? [key: U, value: V]
+  : T extends Set<infer U> ? [value: U]
+  : [];
+
+export interface ForProps<
+  T extends
+    | ForSupportedCollections
+    | (() => ForSupportedCollections)
+    | Ref<ForSupportedCollections>,
+  U extends Children,
+> extends BaseListProps {
+  /**
+   * The array to iterate over.
+   */
+  each: T;
+
+  /**
+   * A function to call for each item.
+   */
+  children: (...args: [...ForCallbackArgs<T>, index: number]) => U;
+}
+
+export type ForSupportedCollections = any[] | Map<any, any> | Set<any>;
+/**
+ * The For component iterates over the provided array and invokes the child
+ * callback for each item. It can optionally be provided with a `joiner` which
+ * is placed between each item, and an `ender` which is placed after the last
+ * item when there is at least one item.
+ *
+ * @example
+ *
+ * ```tsx
+ * const items = ["apple", "pear", "plum"];
+ * return <For each={items}>
+ *   {(item) => <>Fruit: {item}</>}
+ * </For>
+ * ```
+ *
+ * @remarks
+ *
+ * When the `each` prop is a reactive (e.g. a reactive array, or ref to an
+ * array), `For` will automatically update when the array changes. When doing
+ * so, it will attempt to avoid re-rendering items which have not changed. For
+ * example, when appending an item to a reactive array, existing items will not
+ * be re-rendered. Note that presently the implementation is fairly simple -
+ * when making modifications to the middle of an array it likely that every
+ * element after the modification will be rerendered.
+ *
+ * @see {@link (mapJoin:1)} for mapping arrays to elements outside of JSX templates.
+ */
+export function For<
+  T extends
+    | ForSupportedCollections
+    | (() => ForSupportedCollections)
+    | Ref<ForSupportedCollections>,
+  U extends Children,
+>(props: ForProps<T, U>) {
+  const cb = props.children;
+  const options = baseListPropsToMapJoinArgs(props);
+  options.skipFalsy = true;
+  return memo(() => {
+    const maybeRef = props.each;
+
+    return (mapJoin as any)(
+      typeof maybeRef === "function" ? maybeRef : (
+        () => (isRef(maybeRef) ? maybeRef.value : maybeRef)
+      ),
+      cb,
+      options,
+    );
+  });
+}

package/src/components/Indent.tsx

@@ -1,33 +1,26 @@
-import { useContext } from "../context.js";
-import { IndentContext } from "../context/indent.js";
-import { Children } from "../jsx-runtime.js";
+import { Children } from "@alloy-js/core/jsx-runtime";
 
 export interface IndentProps {
-  children?: Children;
-  indent?: string;
+  children: Children;
+  nobreak?: boolean;
+  break?: "space" | "soft" | "hard";
+  trailingBreak?: boolean;
 }
-
-export interface IndentState {
-  level: number;
-  indent: string;
-  indentString: string; // awful name
-  noLeading?: boolean;
-}
-
 export function Indent(props: IndentProps) {
-  const previousIndent = useContext(IndentContext) ?? {
-    level: 0,
-    indent: props.indent ?? "  ",
-    indentString: "",
-  };
-
-  const level = previousIndent.level + 1;
-
-  const currentIndent = {
-    level,
-    indent: props.indent ?? previousIndent.indent,
-    indentString: (props.indent ?? previousIndent.indent).repeat(level),
-  };
+  const breakStyle = props.break ?? "hard";
+  const breakElem =
+    props.nobreak ? ""
+    : breakStyle === "hard" ? <hbr />
+    : breakStyle === "soft" ? <sbr />
+    : <br />;
 
-  return <IndentContext.Provider value={currentIndent}>{props.children}</IndentContext.Provider>;
+  return (
+    <>
+      <indent>
+        {breakElem}
+        {props.children}
+      </indent>
+      {props.trailingBreak && breakElem}
+    </>
+  );
 }

package/src/components/List.tsx

@@ -0,0 +1,94 @@
+import { Children, memo, splitProps } from "@alloy-js/core/jsx-runtime";
+import { childrenArray, JoinOptions } from "../utils.js";
+import { For } from "./For.jsx";
+
+export type BreakKind = "none" | "space" | "soft" | "hard" | "literal";
+
+export interface BaseListProps {
+  /** Text to place between each element */
+  joiner?: Children;
+
+  /** Place a comma between each element */
+  comma?: boolean;
+
+  /** Place a semicolon between each element */
+  semicolon?: boolean;
+
+  line?: boolean;
+  softline?: boolean;
+  hardline?: boolean;
+  literalline?: boolean;
+  space?: boolean;
+
+  /**
+   * Text to place at the end of the list when there is at least one item. If
+   * set to true, the joiner is used.
+   **/
+  ender?: Children;
+
+  /**
+   * Place the join punctuation at the end, but without a line break.
+   */
+  enderPunctuation?: boolean;
+}
+
+export function baseListPropsToMapJoinArgs(props: BaseListProps): JoinOptions {
+  let joiner, punctuation;
+  if ("joiner" in props) {
+    joiner = props.joiner;
+  } else {
+    punctuation =
+      props.comma ? ","
+      : props.semicolon ? ";"
+      : "";
+
+    joiner = (
+      <>
+        {punctuation}
+        {props.softline ?
+          <sbr />
+        : props.hardline ?
+          <hbr />
+        : props.literalline ?
+          <lbr />
+        : props.line ?
+          <br />
+        : props.space ?
+          <> </>
+        : <hbr />}
+      </>
+    );
+  }
+
+  const ender =
+    "ender" in props ? props.ender
+    : props.enderPunctuation ? punctuation
+    : undefined;
+
+  return { joiner, ender };
+}
+
+export interface ListProps extends BaseListProps {
+  children?: Children;
+}
+
+/**
+ * Create a list of children with text between each child. The text to join with
+ * is specified by providing either `joiner` children, or providing boolean
+ * props for the punctuation and line breaks. The default joiner is no
+ * punctuation and a hard break. The `ender` prop can provide text to place at
+ * the end of the list when there is at least one child.
+ */
+export function List(props: ListProps) {
+  const [rest, forProps] = splitProps(props, ["children"]);
+  const resolvedChildren = memo(() =>
+    childrenArray(() => rest.children, {
+      preserveFragments: true,
+    }),
+  );
+  return (
+    <For each={resolvedChildren} {...forProps}>
+      {(child) => child}
+    </For>
+  );
+}

package/src/components/MemberDeclaration.tsx

@@ -50,13 +50,16 @@ export function MemberDeclaration(props: MemberDeclarationProps) {
     declaration = binder.createSymbol({
       name: props.name!,
       refkey: rk,
-      flags: props.static ?
-        OutputSymbolFlags.StaticMember
-      : OutputSymbolFlags.InstanceMember,
+      flags:
+        props.static ?
+          OutputSymbolFlags.StaticMember
+        : OutputSymbolFlags.InstanceMember,
     });
   }
 
-  return <MemberDeclarationContext.Provider value={declaration}>
-    {props.children}
-  </MemberDeclarationContext.Provider>;
+  return (
+    <MemberDeclarationContext.Provider value={declaration}>
+      {props.children}
+    </MemberDeclarationContext.Provider>
+  );
 }

package/src/components/MemberScope.tsx

@@ -34,7 +34,9 @@ export function MemberScope(props: MemberScopeProps) {
     instanceMembers: props.owner.instanceMemberScope,
     staticMembers: props.owner.staticMemberScope,
   };
-  return <MemberScopeContext.Provider value={context}>
+  return (
+    <MemberScopeContext.Provider value={context}>
       {props.children}
-    </MemberScopeContext.Provider>;
+    </MemberScopeContext.Provider>
+  );
 }

package/src/components/Output.tsx

@@ -5,15 +5,16 @@ import {
 } from "../binder.js";
 import { BinderContext } from "../context/binder.js";
 import { NamePolicyContext } from "../context/name-policy.js";
-import { Children } from "../jsx-runtime.js";
+import { Children, getContext } from "../jsx-runtime.js";
 import { NamePolicy } from "../name-policy.js";
+import { PrintTreeOptions } from "../render.js";
 import { extensionEffects } from "../slot.js";
 import { SourceDirectory } from "./SourceDirectory.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { SourceFile } from "./SourceFile.js";
 
-export interface OutputProps {
+export interface OutputProps extends PrintTreeOptions {
   children?: Children;
   /**
    * External libraries whose symbols should be available for reference.
@@ -48,10 +49,18 @@ export function Output(props: OutputProps) {
   const binder = createOutputBinder({
     nameConflictResolver: props.nameConflictResolver,
   });
-  const dir =
-    <SourceDirectory path={basePath}>
-    {props.children}
-  </SourceDirectory>;
+
+  const nodeContext = getContext()!;
+  nodeContext.meta ??= {};
+  nodeContext.meta.printOptions = {
+    printWidth: props.printWidth,
+    tabWidth: props.tabWidth,
+    useTabs: props.useTabs,
+  };
+
+  const dir = (
+    <SourceDirectory path={basePath}>{props.children}</SourceDirectory>
+  );
 
   if (props.externals) {
     for (const global of props.externals) {
@@ -59,13 +68,16 @@ export function Output(props: OutputProps) {
     }
   }
 
-  return <BinderContext.Provider value={binder}>
-    {() => { extensionEffects.forEach(e => e())}}{
-      props.namePolicy ?
+  return (
+    <BinderContext.Provider value={binder}>
+      {() => {
+        extensionEffects.forEach((e) => e());
+      }}
+      {props.namePolicy ?
         <NamePolicyContext.Provider value={props.namePolicy}>
           {dir}
-        </NamePolicyContext.Provider> :
-        dir
-    }
-  </BinderContext.Provider>;
+        </NamePolicyContext.Provider>
+      : dir}
+    </BinderContext.Provider>
+  );
 }

package/src/components/Scope.tsx

@@ -21,7 +21,9 @@ export function Scope(props: ScopeProps) {
     scope = binder.createScope({ kind, name: props.name! });
   }
 
-  return <ScopeContext.Provider value={scope}>
+  return (
+    <ScopeContext.Provider value={scope}>
       {props.children}
-    </ScopeContext.Provider>;
+    </ScopeContext.Provider>
+  );
 }

package/src/components/Show.tsx

@@ -0,0 +1,11 @@
+import { Children } from "@alloy-js/core/jsx-runtime";
+
+export interface ShowProps {
+  children: Children;
+  fallback?: Children;
+  when: boolean | undefined | null;
+}
+
+export function Show(props: ShowProps) {
+  return () => (props.when ? props.children : props.fallback);
+}

package/src/components/SourceDirectory.tsx

@@ -20,7 +20,11 @@ export function SourceDirectory(props: SourceDirectoryProps) {
   nodeContext.meta.directory = {
     path: sdPath,
   };
-  return <SourceDirectoryContext.Provider value={context}>{props.children}</SourceDirectoryContext.Provider>;
+  return (
+    <SourceDirectoryContext.Provider value={context}>
+      {props.children}
+    </SourceDirectoryContext.Provider>
+  );
 }
 
 function createSourceDirectoryContext(