@alloy-js/core 0.4.0 → 0.6.0

package/dist/src/render.d.ts

@@ -1,132 +1,83 @@
+import { Doc } from "prettier";
 import { Children, Context } from "./jsx-runtime.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
- * ```
+ * Turning components into source text involves three different trees produced
+ * sequentially:
+ *
+ * 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
+ *
+ * Finally, the document tree is converted to text via `prettier`. Let's look at
+ * each of these trees and the conversions in detail.
+ *
+ * # Component tree
+ *
+ * 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
+ *
+ * ## Primitive values
+ *
+ * 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).
+ *
+ * ## Nullary functions
+ *
+ * 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.
+ *
+ * ## Component creators
+ *
+ * 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.
+ *
+ * ## Refs
+ *
+ * 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 \}`.
+ *
+ * ## Refkey
+ *
+ * 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";
@@ -139,9 +90,33 @@ export interface OutputFile {
     path: string;
     filetype: string;
 }
-export declare function getContextForRenderNode(node: RenderTextTree): Context | undefined;
-export type RenderStructure = {};
-export type RenderTextTree = (string | RenderTextTree)[];
-export declare function render(children: Children): OutputDirectory;
-export declare function renderTree(children: Children): RenderTextTree;
+export declare function getContextForRenderNode(node: RenderedTextTree): Context | undefined;
+export declare const printHookTag: unique symbol;
+export interface PrintHook {
+    [printHookTag]: true;
+    transform?(tree: RenderedTextTree): RenderedTextTree;
+    print?(tree: RenderedTextTree, print: (subtree: RenderedTextTree) => Doc): Doc;
+    subtree: RenderedTextTree;
+}
+export declare function createRenderTreeHook(subtree: RenderedTextTree, hooks: Omit<PrintHook, typeof printHookTag | "subtree">): PrintHook;
+export declare function isPrintHook(type: unknown): type is PrintHook;
+export type RenderedTextTree = (string | RenderedTextTree | PrintHook)[];
+export declare function render(children: Children, options?: PrintTreeOptions): OutputDirectory;
+export declare function renderTree(children: Children): RenderedTextTree;
+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;
+}
+export declare function printTree(tree: RenderedTextTree, options?: PrintTreeOptions): string;
 //# sourceMappingURL=render.d.ts.map

package/dist/src/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/render.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,QAAQ,EACR,OAAO,EASR,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgIG;AAGH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,eAAe,GAAG,UAAU,CAAC,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,cAAc,uBAE3D;AACD,MAAM,MAAM,eAAe,GAAG,EAAE,CAAC;AAEjC,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC;AAOzD,wBAAgB,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,eAAe,CAgE1D;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,kBAe5C"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/render.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAO,MAAM,UAAU,CAAC;AAIpC,OAAO,EAEL,QAAQ,EACR,OAAO,EAcR,MAAM,kBAAkB,CAAC;AAsB1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAEH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,eAAe,GAAG,UAAU,CAAC,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,gBAAgB,uBAE7D;AAED,eAAO,MAAM,YAAY,eAAW,CAAC;AAErC,MAAM,WAAW,SAAS;IACxB,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC;IACrB,SAAS,CAAC,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CAAC;IACrD,KAAK,CAAC,CACJ,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,GAAG,GACxC,GAAG,CAAC;IACP,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,YAAY,GAAG,SAAS,CAAC,GACtD,SAAS,CAMX;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,SAAS,CAE5D;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC,EAAE,CAAC;AAOzE,wBAAgB,MAAM,CACpB,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,CAsFjB;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,oBAY5C;AA4OD,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAOD,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,gBAAgB,UAW3E"}