@alloy-js/core 0.1.0

package/src/render.ts

@@ -0,0 +1,389 @@
+import {
+  Child,
+  Children,
+  Context,
+  effect,
+  getContext,
+  isComponentCreator,
+  popStack,
+  printRenderStack,
+  pushStack,
+  root,
+  untrack,
+} from "@alloy-js/core/jsx-runtime";
+import { isRef } from "@vue/reactivity";
+import { Indent, IndentState } from "./components/Indent.js";
+import { useContext } from "./context.js";
+import { IndentContext } from "./context/indent.js";
+import { SourceFileContext } from "./context/source-file.js";
+import { isRefkey } from "./refkey.js";
+
+/**
+ * The component tree is constructed as the result of transforming JSX with
+ * `@alloy-js/babel-preset`. Elements in the component tree (represented by the type
+ * Children) are three distinct types of things:
+ *
+ * 1. Primitive data types, which are either literal JSX or substitutions
+ * 2. Components, which are created via `createComponent`
+ * 3. Memos, which are created via `memo`, and represent substitutions like
+ *    property accesses and function calls that might be reactive.
+ *
+ * This tree is then compiled into a render tree, which is a normalized form of
+ * the component tree. The render tree is constructed by traversing the
+ * component tree, invoking components, wrapping memos, doing whitespace
+ * normalization, and other activities. There are four types of nodes in the
+ * render tree.
+ *
+ * 1. Strings, which are either literal JSX or substitutions. Other primitive
+ *    types are either converted to the empty string or stringified as
+ *    appropriate.
+ * 2. Components, which are possibly wrapped if they are indented.
+ * 3. Memos, which are wrapped in a reactive effect which updates its render
+ *    tree nodes when its value changes.
+ * 4. Arrays of these things.
+ *
+ * The render tree is whitespace normalized and indentation preserving. When the
+ * component increases the literal indent level and then embeds a component,
+ * memo, or array, the contents of that substitution are indented appropriately.
+ * This is accomplished by wrapping those substitutions in an indent component.
+ *
+ * So the high level process for rendering while normalizing whitespace is as
+ * follows:
+ *
+ * 1. For an array of elements in the render tree (which may be a component or
+ *    array of elements):
+ *    1. Normalize all primitive values other than strings to strings.
+ *       Recursively normalize nested array elements.
+ *    2. Use the first text node to determine the literal indent level of the
+ *       children. Remove all preceding whitespace - any indent of the first
+ *       line is provided in the text nodes preceding the reference to this
+ *       component. If the first element is not a literal string, then no
+ *       literal indent is applied, and all indentation within the component
+ *       becomes significant.
+ *    3. For each child of the component, render it:
+ *       1. If it is a string, reindent it by splitting on lines and replacing
+ *          the detected literal whitespace with the current indent level,
+ *          skipping the first line. If the string ends with a larger literal
+ *          indent than the detected literal indent, then a subsequent child
+ *          will be indented.
+ *       2. If it's a component, if the next child should be indented, create an
+ *          Indent component and wrap the component's children in it.
+ *       3. If it's a function, if the next child should be indented, wrap it in
+ *          an indent component. Any elements processed as a result of executing
+ *          the memo are treated as first elements in a child array are with
+ *          respect to establishing literal indent level and whitespace trimming
+ *          behavior.
+ *       4. If it's an array, if the next child should be indented, create an
+ *          Indent component and wrap it the array in it.
+ *
+ * Let's look at a few examples of each of these phases:
+ *
+ * ## Explicit indentation
+ *
+ * ### Input
+ * ```
+ * <Indent>
+ *   <Foo />
+ *   <Foo />
+ * </Indent>
+ * ```
+ *
+ * ### Compiled tree
+ * ```
+ * [
+ *   createComponent(Indent, {
+ *     get children() {
+ *       return [
+ *         "\n  ",
+ *         createComponent(Foo, {}),
+ *         "\n  ",
+ *         createComponent(Foo, {}),
+ *         "\n"
+ *       ]
+ *     }
+ *   })
+ * ]
+ * ```
+ *
+ * ### Render tree
+ * ```
+ * [              // node for Indent
+ *   [            // node for Context Provider
+ *     "  ",      // indent from the children of Indent
+ *     [          // component for Foo
+ *       "Foo"    // result of calling Foo
+ *     ],
+ *     "\n  ",    // indent and line break from the children of Ident
+ *     [ "Foo" ]  // second foo component
+ *   ]
+ * ]
+ * ```
+ * ### Rendered text
+ * ```
+ *   FooFoo
+ * ```
+ *
+ * ## Implicit indentation
+ *
+ * ### Input
+ * ```
+ * <>
+ *   base
+ *     <Foo /> <Foo />
+ * </>
+ * ```
+ *
+ * ### Render tree
+ * ```
+ * [                  // node for top-level fragment
+ *   "base\n  ",      // contents of fragment, including trailing indent
+ *   [                // node for implicitly created Indent component
+ *     [              // node for its context provider [ "Foo" ],   // contents of Foo "\n"
+ * ]
+ * ```
+ * ## Rendered text
+ * ```
+ * base
+ *   Foo Foo
+ * ```
+ */
+
+//
+export interface OutputDirectory {
+  kind: "directory";
+  path: string;
+  contents: (OutputDirectory | OutputFile)[];
+}
+
+export interface OutputFile {
+  kind: "file";
+  contents: string;
+  path: string;
+  filetype: string;
+}
+
+const nodesToContext = new WeakMap<RenderTextTree, Context>();
+
+export function getContextForRenderNode(node: RenderTextTree) {
+  return nodesToContext.get(node);
+}
+export type RenderStructure = {};
+
+export type RenderTextTree = (string | RenderTextTree)[];
+
+function traceRender(phase: string, message: string) {
+  return false;
+  // console.log(`[\x1b[34m${phase}\x1b[0m]: ${message}`);
+}
+
+export function render(children: Children): OutputDirectory {
+  const tree = renderTree(children);
+  let rootDirectory: OutputDirectory | undefined = undefined;
+  collectSourceFiles(undefined, tree);
+
+  if (!rootDirectory) {
+    throw new Error(
+      "No root directory found. Make sure you are using the Output component.",
+    );
+  }
+
+  return rootDirectory;
+
+  function collectSourceFiles(
+    currentDirectory: OutputDirectory | undefined,
+    root: RenderTextTree,
+  ) {
+    if (!Array.isArray(root)) {
+      return;
+    }
+    const context = getContextForRenderNode(root);
+
+    if (!context) {
+      return recurse(currentDirectory);
+    }
+
+    if (context.meta?.directory) {
+      const directory: OutputDirectory = {
+        kind: "directory",
+        path: context.meta?.directory.path,
+        contents: [],
+      };
+
+      if (currentDirectory) {
+        currentDirectory.contents.push(directory);
+      } else {
+        rootDirectory = directory;
+      }
+      recurse(directory);
+    } else if (context.meta?.sourceFile) {
+      if (!currentDirectory) {
+        // This shouldn't happen if you're using the Output component.
+        throw new Error(
+          "Source file doesn't have parent directory. Make sure you have used the Output component.",
+        );
+      }
+      const sourceFile: OutputFile = {
+        kind: "file",
+        path: context.meta?.sourceFile.path,
+        filetype: context.meta?.sourceFile.filetype,
+        contents: (root as any).flat(Infinity).join(""),
+      };
+
+      currentDirectory.contents.push(sourceFile);
+    } else {
+      recurse(currentDirectory);
+    }
+
+    function recurse(cwd: OutputDirectory | undefined) {
+      for (const child of root) {
+        collectSourceFiles(cwd, child as RenderTextTree);
+      }
+    }
+  }
+}
+
+export function renderTree(children: Children) {
+  const rootElem: RenderTextTree = [];
+  const state: RenderState = {
+    newline: false,
+  };
+  try {
+    root(() => {
+      renderWorker(rootElem, children, state);
+    }, "render worker");
+  } catch (e) {
+    printRenderStack();
+    throw e;
+  }
+
+  return rootElem;
+}
+
+interface RenderState {
+  newline: boolean;
+}
+
+function renderWorker(
+  node: RenderTextTree,
+  children: Children,
+  state: RenderState,
+) {
+  traceRender("render", dumpChildren(children));
+
+  if (Array.isArray(node)) {
+    nodesToContext.set(node, getContext()!);
+  }
+
+  const indent = useContext(IndentContext)!;
+  if (Array.isArray(children)) {
+    for (const child of children) {
+      appendChild(node, child, indent, state);
+    }
+  } else {
+    appendChild(node, children, indent, state);
+  }
+}
+
+function appendChild(
+  node: RenderTextTree,
+  rawChild: Child,
+  indentState: IndentState,
+  state: RenderState,
+) {
+  traceRender("appendChild", printChild(rawChild));
+  const child = normalizeChild(rawChild);
+
+  if (typeof child === "string") {
+    if (child.match(/\n\s*$/)) {
+      state.newline = true;
+    } else {
+      state.newline = false;
+    }
+    const reindented = reindent(child, indentState.indentString);
+    traceRender("appendChild:string", JSON.stringify(reindented));
+    node.push(reindented);
+  } else if (isComponentCreator(child)) {
+    root(() => {
+      traceRender("appendChild:component", printChild(child));
+      if (child.component === Indent && state.newline) {
+        node.push(indentState.indent);
+      }
+      const componentRoot: RenderTextTree = [];
+      pushStack(child.component, child.props);
+      renderWorker(componentRoot, untrack(child), state);
+      popStack();
+      node.push(componentRoot);
+      traceRender("appendChild:component-done", printChild(child));
+    }, child.component.name);
+  } else if (typeof child === "function") {
+    traceRender("appendChild:memo", child.toString());
+    const index = node.length;
+    effect((prev: any) => {
+      traceRender("memoEffect:run", "");
+      let res = child();
+      while (typeof res === "function" && !isComponentCreator(res)) {
+        res = res();
+      }
+      const newNodes: RenderTextTree = [];
+      renderWorker(newNodes, res, state);
+      //node.splice(index, prev ? prev.length : 0, ...newNodes);
+      node[index] = newNodes;
+      return newNodes;
+    });
+    traceRender("appendChild:memo-done", "");
+  } else {
+    traceRender("appendChild:array", dumpChildren(child));
+    renderWorker(node, child, state);
+    traceRender("appendChild:array-done", dumpChildren(child));
+  }
+}
+
+function reindent(str: string, indent: string) {
+  const lines = str.split("\n");
+  return [lines[0], ...lines.slice(1).map((line) => indent + line)].join("\n");
+}
+type NormalizedChild = string | (() => Child | Children) | NormalizedChild[];
+
+function normalizeChild(child: Child): NormalizedChild {
+  if (Array.isArray(child)) {
+    return child.map(normalizeChild);
+  } else if (typeof child === "string" || typeof child === "function") {
+    return child as NormalizedChild;
+  } else if (
+    typeof child === "undefined" ||
+    child === null ||
+    typeof child === "boolean"
+  ) {
+    return "";
+  } else if (isRef(child)) {
+    return () => child.value as () => Child;
+  } else if (isRefkey(child)) {
+    return () => {
+      const sfContext = useContext(SourceFileContext);
+      if (!sfContext || !sfContext.reference) {
+        throw new Error("Can only emit references inside of source files");
+      }
+
+      return sfContext.reference({ refkey: child });
+    };
+  } else {
+    return String(child);
+  }
+}
+
+function dumpChildren(children: Child | Children): string {
+  if (Array.isArray(children)) {
+    return `[ ${children.map(printChild).join(", ")} ]`;
+  }
+  return printChild(children);
+}
+
+function printChild(child: Child): string {
+  if (isComponentCreator(child)) {
+    return "<" + child.component.name + ">";
+  } else if (typeof child === "function") {
+    return "$memo";
+  } else {
+    return JSON.stringify(child);
+  }
+}

package/src/utils.ts

@@ -0,0 +1,288 @@
+import {
+  Child,
+  Children,
+  ComponentCreator,
+  ComponentDefinition,
+  isComponentCreator,
+  memo,
+} from "@alloy-js/core/jsx-runtime";
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "pathe";
+import { code } from "./code.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { OutputDirectory, OutputFile, render } from "./render.js";
+
+export interface JoinOptions {
+  /**
+   * The string to place between each element.
+   */
+  joiner?: string;
+
+  /**
+   * When true, the joiner is placed at the end of the array. When a string,
+   * that string is placed at the end of the array. The ender is only emitted
+   * when the array has at least one element.
+   */
+  ender?: string | boolean;
+}
+const defaultJoinOptions: JoinOptions = {
+  joiner: "\n",
+  ender: false,
+};
+
+/**
+ * Map a Map to an array using a mapper and place a joiner between each element.
+ * Defaults to joining with a newline.
+ *
+ * @see {@link join} for joining without mapping.
+ * @param src - Source map.
+ * @param cb - Mapper function.
+ * @param options - Join options.
+ * @returns The mapped and joined array.
+ *
+ */
+export function mapJoin<T, U, V>(
+  src: Map<T, U>,
+  cb: (key: T, value: U) => V,
+  options?: JoinOptions,
+): (V | string)[];
+/**
+ * Map a array or iterator to another array using a mapper and place a joiner
+ * between each element. Defaults to joining with a newline.
+ *
+ * @see {@link join} for joining without mapping.
+ * @param src - Source array.
+ * @param cb - Mapper function.
+ * @param options - Join options.
+ * @returns The mapped and joined array.
+ */
+export function mapJoin<T, V>(
+  src: T[] | IterableIterator<T>,
+  cb: (value: T) => V,
+  options?: JoinOptions,
+): (V | string)[];
+export function mapJoin<T, U, V>(
+  src: Map<T, U> | T[] | Iterable<T>,
+  cb: (key: T, value?: U) => V,
+  rawOptions: JoinOptions = {},
+): (V | string)[] {
+  const options = { ...defaultJoinOptions, ...rawOptions };
+  const ender = options.ender === true ? options.joiner : options.ender;
+
+  const mapped: (V | string)[] = [];
+  if (typeof (src as any).next === "function") {
+    src = Array.from(src as Iterable<T>);
+  }
+
+  if (Array.isArray(src)) {
+    for (const [index, item] of src.entries()) {
+      mapped.push(cb(item));
+      if (index !== src.length - 1) {
+        mapped.push(options.joiner!);
+      }
+    }
+    if (src.length > 0 && ender) {
+      mapped.push(ender);
+    }
+  } else {
+    const entries = [...(src as Map<T, U>).entries()];
+    for (const [index, [key, value]] of entries.entries()) {
+      mapped.push(cb(key, value));
+      if (index !== entries.length - 1) {
+        mapped.push(options.joiner!);
+      }
+    }
+    if (entries.length > 0 && ender) {
+      mapped.push(ender);
+    }
+  }
+
+  return mapped;
+}
+
+/**
+ * Place a joiner between each element of an array or iterator. Defaults to
+ * joining with a newline.
+ *
+ * @see mapJoin for mapping before joining.
+ * @returns The joined array
+ */
+export function join<T>(
+  src: T[] | Iterator<T>,
+  options: JoinOptions = {},
+): (T | string)[] {
+  const mergedOptions = { ...defaultJoinOptions, ...options };
+  const joined = [];
+  const ender =
+    mergedOptions.ender === true ? mergedOptions.joiner : mergedOptions.ender;
+  src = Array.from(src as Iterable<T>);
+
+  for (const [index, item] of src.entries()) {
+    joined.push(item);
+    if (index !== src.length - 1) {
+      joined.push(mergedOptions.joiner!);
+    }
+  }
+
+  if (src.length > 0 && ender) {
+    joined.push(ender);
+  }
+
+  return joined;
+}
+
+/**
+ * Returns a memo which is a list of all the provided children.
+ * If you want this as an array, see {@link childrenArray}.
+ */
+export function children(fn: () => Children): () => Children {
+  return memo(() => collectChildren(fn()));
+
+  function collectChildren(children: Children): Children {
+    if (Array.isArray(children)) {
+      return children.map(collectChildren).flat();
+    } else if (
+      typeof children === "function" &&
+      !isComponentCreator(children)
+    ) {
+      return collectChildren(children());
+    } else {
+      return children;
+    }
+  }
+}
+
+export function childrenArray(fn: () => Children): Child[] {
+  const c = children(fn)();
+  if (Array.isArray(c)) {
+    return c;
+  } else if (c === undefined) {
+    return [];
+  } else {
+    return [c];
+  }
+}
+
+export function findKeyedChild(children: Child[], tag: symbol) {
+  for (const child of children) {
+    if (isKeyedChild(child) && child.tag === tag) {
+      return child;
+    }
+  }
+
+  return null;
+}
+
+export function findUnkeyedChildren(children: Child[]) {
+  return children.filter((child) => !isKeyedChild(child));
+}
+
+export function isKeyedChild(child: Child): child is ComponentCreator {
+  return isComponentCreator(child) && !!child.tag;
+}
+
+export function stc<T extends {}>(Component: ComponentDefinition<T>) {
+  return (
+    ...args: unknown extends T ? []
+    : {} extends Omit<T, "children"> ? [props?: T]
+    : [props: T]
+  ) => {
+    const fn: ComponentCreator<T> & {
+      code(
+        template: TemplateStringsArray,
+        ...substitutions: Children[]
+      ): ComponentCreator<T>;
+      children(...children: Children[]): ComponentCreator<T>;
+    } = () => Component(args[0]!);
+    fn.component = Component;
+    fn.props = args[0]!;
+    fn.code = (
+      template: TemplateStringsArray,
+      ...substitutions: Children[]
+    ): ComponentCreator<T> => {
+      const propsWithChildren = {
+        ...(args[0] ?? {}),
+        children: code(template, ...substitutions),
+      };
+
+      const fn = () => Component(propsWithChildren as any);
+      fn.component = Component;
+      fn.props = args[0]!;
+      return fn;
+    };
+
+    fn.children = (...children: Children[]): ComponentCreator<T> => {
+      const propsWithChildren = {
+        ...(args[0] ?? {}),
+        children,
+      };
+
+      const fn = () => Component(propsWithChildren as any);
+      fn.component = Component;
+      fn.props = args[0]!;
+      return fn;
+    };
+
+    return fn;
+  };
+}
+
+/**
+ * A visitor to collect the output from {@link render}. Used by
+ * {@link traverseOutput}.
+ */
+export interface OutputVisitor {
+  visitDirectory(directory: OutputDirectory): void;
+  visitFile(file: OutputFile): void;
+}
+
+/**
+ * Traverse the output from {@link render} and call the visitor for each
+ * file and directory within it.
+ *
+ * @param sourceDirectory - The root directory to traverse.
+ * @param visitor - The visitor to call for each file and directory.
+ */
+export function traverseOutput(
+  sourceDirectory: OutputDirectory,
+  visitor: OutputVisitor,
+) {
+  visitor.visitDirectory(sourceDirectory);
+  for (const item of sourceDirectory.contents) {
+    if (item.kind === "directory") {
+      traverseOutput(item, visitor);
+    } else {
+      visitor.visitFile(item);
+    }
+  }
+}
+
+/**
+ * Write the output from {@link render} to the file system.
+ *
+ */
+export function writeOutput(output: OutputDirectory, basePath: string = "") {
+  traverseOutput(output, {
+    visitDirectory(directory) {
+      const path = resolve(basePath, directory.path);
+      if (statSync(path)) {
+        return;
+      }
+      // eslint-disable-next-line no-console
+      console.log("create", relative(process.cwd(), path));
+      mkdirSync(path, { recursive: true });
+    },
+    visitFile(file) {
+      const path = resolve(basePath, file.path);
+      if (statSync(path)) {
+        // eslint-disable-next-line no-console
+        console.log("overwrite", relative(process.cwd(), path));
+      } else {
+        // eslint-disable-next-line no-console
+        console.log("create", relative(process.cwd(), path));
+      }
+
+      writeFileSync(path, file.contents);
+    },
+  });
+}