@alloy-js/core 0.4.0 → 0.6.0

package/package.json

@@ -1,27 +1,24 @@
 {
   "name": "@alloy-js/core",
-  "version": "0.4.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": {
-      "development": "./src/jsx-runtime.ts",
+      "types": "./dist/src/jsx-runtime.d.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"
     }
   },
@@ -39,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",
@@ -47,8 +45,9 @@
     "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-typescript": "^11.1.6",
     "concurrently": "^8.2.2",
-    "typescript": "^5.5.4",
-    "vitest": "^3.0.4"
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.4",
+    "vite": "^6.0.1"
   },
   "type": "module",
   "scripts": {

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,19 @@ 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;
+
+  /**
+   * 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
@@ -414,6 +421,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   const binder: Binder = {
     createScope,
     createSymbol,
+    deleteSymbol,
     resolveDeclarationByKey,
     addStaticMembersToSymbol,
     addInstanceMembersToSymbol,
@@ -451,15 +459,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 +518,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,11 +586,23 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     scope.symbolsByRefkey.set(symbol.refkey, symbol);
 
     deconflict(symbol);
-    notifyRefkey(refkey, symbol);
+    notifyRefkey(symbol);
 
     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");
@@ -807,24 +814,27 @@ 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;
+
+      // notify those waiting for this refkey
+      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;
+      // notify those waiting for this symbol name
+      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 +959,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/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>
+  );
 }