@alloy-js/core 0.5.0 → 0.7.0

package/src/render.ts

@@ -1,15 +1,20 @@
 import { isRef } from "@vue/reactivity";
-import { Indent, IndentState } from "./components/Indent.js";
+import { Doc, doc } from "prettier";
+import prettier from "prettier/doc.js";
 import { useContext } from "./context.js";
-import { IndentContext } from "./context/indent.js";
 import { SourceFileContext } from "./context/source-file.js";
 import {
   Child,
   Children,
   Context,
+  CustomContext,
   effect,
   getContext,
+  getElementCache,
+  IntrinsicElement,
   isComponentCreator,
+  isCustomContext,
+  isIntrinsicElement,
   popStack,
   printRenderStack,
   pushStack,
@@ -17,138 +22,107 @@ import {
   untrack,
 } from "./jsx-runtime.js";
 import { isRefkey } from "./refkey.js";
+const {
+  builders: {
+    align,
+    breakParent,
+    dedent,
+    dedentToRoot,
+    fill,
+    group,
+    hardline,
+    indent,
+    indentIfBreak,
+    line,
+    lineSuffix,
+    lineSuffixBoundary,
+    literalline,
+    markAsRoot,
+    softline,
+    ifBreak,
+  },
+} = prettier;
 
 /**
- * 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:
+ * Turning components into source text involves three different trees produced
+ * sequentially:
  *
- * 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.
+ * 1. Component tree, built by the nesting of components
+ * 2. Rendered text tree, produced by *rendering* the component tree
+ * 3. Document tree, produced by *printing* the rendered text tree
  *
- * 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.
+ * Finally, the document tree is converted to text via `prettier`. Let's look at
+ * each of these trees and the conversions in detail.
  *
- * 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.
+ * # Component tree
  *
- * 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.
+ * The component tree is built by JSX or STC templates. The nodes in this tree
+ * are defined by the type `Child` and are one of the following
  *
- * So the high level process for rendering while normalizing whitespace is as
- * follows:
+ * ## Primitive values
  *
- * 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.
+ * Strings in the tree are placed into the rendered text tree as-is. Numbers are
+ * converted to strings. Falsy primitive values and booleans are converted to
+ * empty strings (and may cause a line break to be ignored, see below).
  *
- * Let's look at a few examples of each of these phases:
+ * ## Nullary functions
  *
- * ## Explicit indentation
+ * Nullary functions represent computed or reactive values in the component
+ * tree, such as expressions placed into a JSX template with curly brackets.
+ * Nullary functions return `Children` which are then recursively rendered.
+ * Nullary functions are invoked in an effect which will update the rendered
+ * text tree when any reactive dependencies change.
  *
- * ### Input
- * ```
- * <Indent>
- *   <Foo />
- *   <Foo />
- * </Indent>
- * ```
+ * ## Component creators
  *
- * ### Compiled tree
- * ```
- * [
- *   createComponent(Indent, {
- *     get children() {
- *       return [
- *         "\n  ",
- *         createComponent(Foo, {}),
- *         "\n  ",
- *         createComponent(Foo, {}),
- *         "\n"
- *       ]
- *     }
- *   })
- * ]
- * ```
+ * Component creators are a special kind of nullary function which instantiate
+ * components in order to get their children which are then recursively
+ * rendered. Component creators have some special rendering behavior, such as
+ * tracking the stack of rendered components. Like other nullary functions,
+ * component creators are invoked in an effect which will update the rendered
+ * text tree when any reactive dependencies change.
  *
- * ### 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
- * ```
+ * ## Refs
  *
- * ## Implicit indentation
+ * Refs are wrapped in a nullary function and rendered in an effect which will
+ * update the rendered text tree when the ref's value changes. This is
+ * essentially a syntactic convenience, allowing JSX templates to contain
+ * `\{ someRef \}` instead of `\{ someRef.value \}`.
  *
- * ### Input
- * ```
- * <>
- *   base
- *     <Foo /> <Foo />
- * </>
- * ```
+ * ## Refkey
  *
- * ### 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
- * ```
+ * Refkeys are replaced with a component creator for the Reference component
+ * associated with the current source file. This allows creating references by
+ * placing them directly in the component tree e.g. `{ someRefkey }`.
+ *
+ * ## CustomContext
+ *
+ * CustomContext is a special kind of component which allows rendering children
+ * within a custom reactive context. This enables components to manually manage
+ * the lifetime of their reactive contexts.
+ *
+ * ## IntrinsicElement
+ *
+ * Various intrinsic elements exist to control formatting. These elements
+ * provide Print Hooks that are called during Printing.
+ *
+ * # Rendered Text Tree
+ *
+ * This tree is a nested array structure containing the rendered output of all
+ * the components in the component tree. This structure is updated reactively
+ * when reactive dependencies change. The nodes in this tree are predominantly
+ * strings, but can also be Print Hooks.
+ *
+ * This tree is built by the `renderTree` function.
+ *
+ * # Document Tree
+ *
+ * This tree is constructed by calling `printTree` on the rendered text tree.
+ * The rendered text tree is walked and the appropriate Prettier builders are
+ * called to produce a document tree. The result is then passed to Prettier's
+ * `printDocToString` function to produce the final source text.
  */
 
-//
 export interface OutputDirectory {
   kind: "directory";
   path: string;
@@ -162,23 +136,60 @@ export interface OutputFile {
   filetype: string;
 }
 
-const nodesToContext = new WeakMap<RenderTextTree, Context>();
+const nodesToContext = new WeakMap<RenderedTextTree, Context>();
 
-export function getContextForRenderNode(node: RenderTextTree) {
+export function getContextForRenderNode(node: RenderedTextTree) {
   return nodesToContext.get(node);
 }
-export type RenderStructure = {};
 
-export type RenderTextTree = (string | RenderTextTree)[];
+export const printHookTag = Symbol();
+
+export interface PrintHook {
+  [printHookTag]: true;
+  transform?(tree: RenderedTextTree): RenderedTextTree;
+  print?(
+    tree: RenderedTextTree,
+    print: (subtree: RenderedTextTree) => Doc,
+  ): Doc;
+  subtree: RenderedTextTree;
+}
+
+export function createRenderTreeHook(
+  subtree: RenderedTextTree,
+  hooks: Omit<PrintHook, typeof printHookTag | "subtree">,
+): PrintHook {
+  return {
+    [printHookTag]: true,
+    subtree,
+    ...hooks,
+  };
+}
+
+export function isPrintHook(type: unknown): type is PrintHook {
+  return typeof type === "object" && type !== null && printHookTag in type;
+}
+
+export type RenderedTextTree = (string | RenderedTextTree | PrintHook)[];
 
 function traceRender(phase: string, message: () => string) {
   return false;
-  // console.log(`[\x1b[34m${phase}\x1b[0m]: ${message}`);
+  //console.log(`[\x1b[34m${phase}\x1b[0m]: ${message()}`);
 }
 
-export function render(children: Children): OutputDirectory {
+export function render(
+  children: Children,
+  options?: PrintTreeOptions,
+): OutputDirectory {
   const tree = renderTree(children);
   let rootDirectory: OutputDirectory | undefined = undefined;
+
+  // when passing Output, the first render tree child is the Output component.
+  const rootRenderOptions =
+    Array.isArray(tree) ?
+      (getContextForRenderNode(tree[0] as RenderedTextTree)?.meta
+        ?.printOptions ?? {})
+    : {};
+
   collectSourceFiles(undefined, tree);
 
   if (!rootDirectory) {
@@ -191,7 +202,7 @@ export function render(children: Children): OutputDirectory {
 
   function collectSourceFiles(
     currentDirectory: OutputDirectory | undefined,
-    root: RenderTextTree,
+    root: RenderedTextTree,
   ) {
     if (!Array.isArray(root)) {
       return;
@@ -222,11 +233,25 @@ export function render(children: Children): OutputDirectory {
           "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(""),
+        contents: printTree(root, {
+          printWidth:
+            options?.printWidth ??
+            context.meta?.printOptions?.printWidth ??
+            rootRenderOptions.printWidth,
+          tabWidth:
+            options?.tabWidth ??
+            context.meta?.printOptions?.tabWidth ??
+            rootRenderOptions.tabWidth,
+          useTabs:
+            options?.useTabs ??
+            context.meta?.printOptions?.useTabs ??
+            rootRenderOptions.useTabs,
+        }),
       };
 
       currentDirectory.contents.push(sourceFile);
@@ -236,20 +261,17 @@ export function render(children: Children): OutputDirectory {
 
     function recurse(cwd: OutputDirectory | undefined) {
       for (const child of root) {
-        collectSourceFiles(cwd, child as RenderTextTree);
+        collectSourceFiles(cwd, child as RenderedTextTree);
       }
     }
   }
 }
 
 export function renderTree(children: Children) {
-  const rootElem: RenderTextTree = [];
-  const state: RenderState = {
-    newline: false,
-  };
+  const rootElem: RenderedTextTree = [];
   try {
     root(() => {
-      renderWorker(rootElem, children, state);
+      renderWorker(rootElem, children);
     });
   } catch (e) {
     printRenderStack();
@@ -259,92 +281,204 @@ export function renderTree(children: Children) {
   return rootElem;
 }
 
-interface RenderState {
-  newline: boolean;
-}
-
-function renderWorker(
-  node: RenderTextTree,
-  children: Children,
-  state: RenderState,
-) {
+function renderWorker(node: RenderedTextTree, children: Children) {
   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);
+    for (const child of (children as any).flat(Infinity)) {
+      appendChild(node, child);
     }
   } else {
-    appendChild(node, children, indent, state);
+    appendChild(node, children);
   }
 }
 
-function appendChild(
-  node: RenderTextTree,
-  rawChild: Child,
-  indentState: IndentState,
-  state: RenderState,
-) {
-  traceRender("appendChild", () => printChild(rawChild));
+function appendChild(node: RenderedTextTree, rawChild: Child) {
+  traceRender("appendChild", () => debugPrintChild(rawChild));
   const child = normalizeChild(rawChild);
 
   if (typeof child === "string") {
-    if (child.match(/\n\s*$/)) {
-      state.newline = true;
-    } else {
-      state.newline = false;
+    node.push(child);
+  } else {
+    const cache = getElementCache();
+    if (cache.has(child as any)) {
+      traceRender("appendChild:cached", () => debugPrintChild(child));
+      node.push(cache.get(child as any)!);
+      return;
     }
-    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);
+    if (isCustomContext(child)) {
+      traceRender("appendChild:custom-context", () => debugPrintChild(child));
+      child.useCustomContext((children) => {
+        const newNode: RenderedTextTree = [];
+        renderWorker(newNode, children);
+        node.push(newNode);
+        cache.set(child, newNode);
+      });
+    } else if (isIntrinsicElement(child)) {
+      // don't need a new context here because intrinsics are never reactive
+      traceRender("appendChild:intrinsic-element", () =>
+        debugPrintChild(child),
+      );
+      const newNode: RenderedTextTree = [];
+
+      function formatHookWithChildren(command: (doc: Doc) => Doc) {
+        node.push(
+          createRenderTreeHook(newNode, {
+            print(tree, print) {
+              return command(print(tree));
+            },
+          }),
+        );
+        renderWorker(newNode, (child as any).props.children);
       }
-      const componentRoot: RenderTextTree = [];
-      pushStack(child.component, child.props);
-      renderWorker(componentRoot, untrack(child), state);
-      popStack();
-      node.push(componentRoot);
-      traceRender("appendChild:component-done", () => printChild(child));
-    }, child);
-  } 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();
+
+      function formatHook(command: Doc) {
+        return node.push(
+          createRenderTreeHook(newNode, {
+            print() {
+              return command;
+            },
+          }),
+        );
       }
-      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));
+
+      switch (child.name) {
+        case "indent":
+          return formatHookWithChildren(indent);
+        case "indentIfBreak":
+          node.push(
+            createRenderTreeHook(newNode, {
+              print(tree, print) {
+                return indentIfBreak(print(tree), {
+                  groupId: child.props.groupId,
+                  negate: child.props.negate,
+                });
+              },
+            }),
+          );
+          renderWorker(newNode, child.props.children);
+          return;
+        case "fill":
+          return formatHookWithChildren(fill as any);
+        case "group":
+          node.push(
+            createRenderTreeHook(newNode, {
+              print(tree, print) {
+                return group(print(tree), {
+                  id: child.props.id,
+                  shouldBreak: child.props.shouldBreak,
+                });
+              },
+            }),
+          );
+          renderWorker(newNode, child.props.children);
+          return;
+        case "line":
+        case "br":
+          return formatHook(line);
+        case "hbr":
+        case "hardline":
+          return formatHook(hardline);
+        case "sbr":
+        case "softline":
+          return formatHook(softline);
+        case "literalline":
+        case "lbr":
+          return formatHook(literalline);
+        case "align":
+          node.push(
+            createRenderTreeHook(newNode, {
+              print(tree, print) {
+                return align(
+                  (child.props as any).width ?? (child.props as any).string!,
+                  print(tree),
+                );
+              },
+            }),
+          );
+          renderWorker(newNode, (child as any).props.children);
+          return;
+        case "lineSuffix":
+          return formatHookWithChildren(lineSuffix);
+        case "lineSuffixBoundary":
+          return formatHook(lineSuffixBoundary);
+        case "breakParent":
+          return formatHook(breakParent);
+        case "dedent":
+          return formatHookWithChildren(dedent);
+        case "dedentToRoot":
+          return formatHookWithChildren(dedentToRoot);
+        case "markAsRoot":
+          return formatHookWithChildren(markAsRoot);
+        case "ifBreak":
+          node.push(
+            createRenderTreeHook(newNode, {
+              print(tree, print) {
+                return ifBreak(
+                  print((tree as RenderedTextTree[])[0]),
+                  print((tree as RenderedTextTree[])[1]),
+                );
+              },
+            }),
+          );
+          newNode.push([], []);
+          renderWorker(
+            newNode[0] as RenderedTextTree[],
+            (child as any).props.children,
+          );
+          renderWorker(
+            newNode[1] as RenderedTextTree[],
+            (child as any).props.flatContents,
+          );
+          return;
+        default:
+          throw new Error("Unknown intrinsic element");
+      }
+    } else if (isComponentCreator(child)) {
+      effect(() => {
+        traceRender("appendChild:component", () => debugPrintChild(child));
+        const componentRoot: RenderedTextTree = [];
+        pushStack(child.component, child.props);
+        renderWorker(componentRoot, untrack(child));
+        popStack();
+        node.push(componentRoot);
+        cache.set(child, componentRoot);
+        traceRender("appendChild:component-done", () => debugPrintChild(child));
+      });
+    } else if (typeof child === "function") {
+      traceRender("appendChild:memo", () => child.toString());
+      const index = node.length;
+      effect(() => {
+        traceRender("memoEffect:run", () => "");
+        let res = child();
+        while (typeof res === "function" && !isComponentCreator(res)) {
+          res = res();
+        }
+        const newNodes: RenderedTextTree = [];
+        renderWorker(newNodes, res);
+        node[index] = newNodes;
+        cache.set(child, newNodes);
+        return newNodes;
+      });
+      traceRender("appendChild:memo-done", () => "");
+    } else {
+      throw new Error("Unexpected child type");
+    }
   }
 }
 
-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[];
+type NormalizedChildren = NormalizedChild | NormalizedChildren[];
+type NormalizedChild =
+  | string
+  | (() => Child | Children)
+  | CustomContext
+  | IntrinsicElement;
 
-function normalizeChild(child: Child): NormalizedChild {
+function normalizeChild(child: Child): NormalizedChildren {
   if (Array.isArray(child)) {
     return child.map(normalizeChild);
   } else if (typeof child === "string" || typeof child === "function") {
@@ -366,19 +500,23 @@ function normalizeChild(child: Child): NormalizedChild {
 
       return sfContext.reference({ refkey: child });
     };
+  } else if (isCustomContext(child)) {
+    return child;
+  } else if (isIntrinsicElement(child)) {
+    return child;
   } else {
     return String(child);
   }
 }
 
-function dumpChildren(children: Child | Children): string {
+function dumpChildren(children: Children): string {
   if (Array.isArray(children)) {
-    return `[ ${children.map(printChild).join(", ")} ]`;
+    return `[ ${children.map(debugPrintChild).join(", ")} ]`;
   }
-  return printChild(children);
+  return debugPrintChild(children);
 }
 
-function printChild(child: Child): string {
+function debugPrintChild(child: Children): string {
   if (isComponentCreator(child)) {
     return "<" + child.component.name + ">";
   } else if (typeof child === "function") {
@@ -389,3 +527,59 @@ function printChild(child: Child): string {
     return JSON.stringify(child);
   }
 }
+
+export interface PrintTreeOptions {
+  /**
+   * The number of characters the printer will wrap on. Defaults to 100
+   * characters.
+   */
+  printWidth?: number;
+
+  /**
+   * Whether to use tabs instead of spaces for indentation. Defaults to false.
+   */
+  useTabs?: boolean;
+
+  /**
+   * The number of spaces to use for indentation. Defaults to 2 spaces.
+   */
+  tabWidth?: number;
+}
+
+const defaultPrintTreeOptions: PrintTreeOptions = {
+  printWidth: 80,
+  tabWidth: 2,
+};
+
+export function printTree(tree: RenderedTextTree, options?: PrintTreeOptions) {
+  options = {
+    ...defaultPrintTreeOptions,
+    ...Object.fromEntries(
+      Object.entries(options ?? {}).filter(([_, v]) => v !== undefined),
+    ),
+  };
+
+  const d = printTreeWorker(tree);
+  return doc.printer.printDocToString(d, options as doc.printer.Options)
+    .formatted;
+}
+
+function printTreeWorker(tree: RenderedTextTree): Doc {
+  const doc: Doc = [];
+  for (const node of tree) {
+    if (typeof node === "string") {
+      const normalizedNode = node
+        .split(/\r?\n/)
+        .flatMap((line, index, array) =>
+          index < array.length - 1 ? [line, hardline] : [line],
+        );
+      doc.push(normalizedNode);
+    } else if (isPrintHook(node)) {
+      doc.push(node.print!(node.subtree, printTreeWorker));
+    } else {
+      doc.push(printTreeWorker(node));
+    }
+  }
+
+  return doc;
+}