@alloy-js/core 0.16.0 → 0.18.0-dev.2

package/src/render.ts

@@ -3,26 +3,29 @@ import { Doc, doc } from "prettier";
 import prettier from "prettier/doc.js";
 import { useContext } from "./context.js";
 import { SourceFileContext } from "./context/source-file.js";
+import { shouldDebug } from "./debug.js";
 import {
-  Child,
-  Children,
   Context,
   CustomContext,
   effect,
   getContext,
   getElementCache,
-  IntrinsicElement,
-  isComponentCreator,
   isCustomContext,
-  isIntrinsicElement,
-  popStack,
-  printRenderStack,
-  pushStack,
   root,
   untrack,
-} from "./jsx-runtime.js";
+} from "./reactivity.js";
 import { isRefkey } from "./refkey.js";
+import {
+  Child,
+  Children,
+  Component,
+  isComponentCreator,
+  Props,
+} from "./runtime/component.js";
+import { IntrinsicElement, isIntrinsicElement } from "./runtime/intrinsic.js";
 import { flushJobs } from "./scheduler.js";
+import { trace, TracePhase } from "./tracer.js";
+
 const {
   builders: {
     align,
@@ -172,11 +175,6 @@ export function isPrintHook(type: unknown): type is PrintHook {
 
 export type RenderedTextTree = (string | RenderedTextTree | PrintHook)[];
 
-function traceRender(phase: string, message: () => string) {
-  return false;
-  //console.log(`[\x1b[34m${phase}\x1b[0m]: ${message()}`);
-}
-
 export function render(
   children: Children,
   options?: PrintTreeOptions,
@@ -284,7 +282,12 @@ export function renderTree(children: Children) {
 }
 
 function renderWorker(node: RenderedTextTree, children: Children) {
-  traceRender("render", () => dumpChildren(children));
+  if (!getContext()) {
+    throw new Error(
+      "Cannot render without a context. Make sure you are using the Output component.",
+    );
+  }
+  trace(TracePhase.render.worker, () => dumpChildren(children));
 
   if (Array.isArray(node)) {
     nodesToContext.set(node, getContext()!);
@@ -300,7 +303,7 @@ function renderWorker(node: RenderedTextTree, children: Children) {
 }
 
 function appendChild(node: RenderedTextTree, rawChild: Child) {
-  traceRender("appendChild", () => debugPrintChild(rawChild));
+  trace(TracePhase.render.appendChild, () => debugPrintChild(rawChild));
   const child = normalizeChild(rawChild);
 
   if (typeof child === "string") {
@@ -308,12 +311,18 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
   } else {
     const cache = getElementCache();
     if (cache.has(child as any)) {
-      traceRender("appendChild:cached", () => debugPrintChild(child));
+      trace(
+        TracePhase.render.appendChild,
+        () => "Cached: " + debugPrintChild(child),
+      );
       node.push(cache.get(child as any)!);
       return;
     }
     if (isCustomContext(child)) {
-      traceRender("appendChild:custom-context", () => debugPrintChild(child));
+      trace(
+        TracePhase.render.appendChild,
+        () => "CustomContext: " + debugPrintChild(child),
+      );
       child.useCustomContext((children) => {
         const newNode: RenderedTextTree = [];
         renderWorker(newNode, children);
@@ -321,10 +330,11 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
         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),
+      trace(
+        TracePhase.render.appendChild,
+        () => "IntrinsicElement: " + debugPrintChild(child),
       );
+      // don't need a new context here because intrinsics are never reactive
       const newNode: RenderedTextTree = [];
 
       function formatHookWithChildren(command: (doc: Doc) => Doc) {
@@ -442,20 +452,26 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
       }
     } else if (isComponentCreator(child)) {
       effect(() => {
-        traceRender("appendChild:component", () => debugPrintChild(child));
+        trace(
+          TracePhase.render.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));
+        trace(
+          TracePhase.render.appendChild,
+          () => "Component done: " + debugPrintChild(child),
+        );
       });
     } else if (typeof child === "function") {
-      traceRender("appendChild:memo", () => child.toString());
+      trace(TracePhase.render.appendChild, () => "Memo: " + child.toString());
       const index = node.length;
       effect(() => {
-        traceRender("memoEffect:run", () => "");
+        trace(TracePhase.render.renderEffect, () => "");
         let res = child();
         while (typeof res === "function" && !isComponentCreator(res)) {
           res = res();
@@ -466,7 +482,6 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
         cache.set(child, newNodes);
         return newNodes;
       });
-      traceRender("appendChild:memo-done", () => "");
     } else {
       throw new Error("Unexpected child type");
     }
@@ -525,6 +540,8 @@ function debugPrintChild(child: Children): string {
     return "$memo";
   } else if (isRef(child)) {
     return "$ref";
+  } else if (isIntrinsicElement(child)) {
+    return `<${child.name}>`;
   } else {
     return JSON.stringify(child);
   }
@@ -588,3 +605,57 @@ function printTreeWorker(tree: RenderedTextTree): Doc {
 
   return doc;
 }
+// debugging utilities
+const renderStack: {
+  component: Component<any>;
+  props: Props;
+}[] = [];
+
+export function pushStack(component: Component<any>, props: Props) {
+  if (!shouldDebug()) return;
+  renderStack.push({ component, props });
+}
+
+export function popStack() {
+  if (!shouldDebug()) return;
+  renderStack.pop();
+}
+
+export function printRenderStack() {
+  if (!shouldDebug()) return;
+
+  // eslint-disable-next-line no-console
+  console.error("Error rendering:");
+  for (let i = renderStack.length - 1; i >= 0; i--) {
+    const { component, props } = renderStack[i];
+    // eslint-disable-next-line no-console
+    console.error(`    at ${component.name}(${inspectProps(props)})`);
+  }
+}
+
+function inspectProps(props: Props) {
+  return JSON.stringify(
+    Object.fromEntries(
+      Object.entries(props).map(([key, value]) => {
+        let safeValue;
+        switch (typeof value) {
+          case "string":
+          case "number":
+          case "boolean":
+            safeValue = value;
+            break;
+          case "undefined":
+            safeValue = "undefined";
+            break;
+          case "object":
+            safeValue = value ? "{...}" : null;
+            break;
+          case "function":
+            safeValue = "function";
+            break;
+        }
+        return [key, safeValue];
+      }),
+    ),
+  );
+}

package/src/runtime/component.ts

@@ -0,0 +1,67 @@
+import { Ref } from "@vue/reactivity";
+import { CustomContext } from "../reactivity.js";
+import { Refkey } from "../refkey.js";
+import { IntrinsicElement } from "./intrinsic.js";
+
+export type Child =
+  | string
+  | boolean
+  | number
+  | undefined
+  | null
+  | void
+  | (() => Children)
+  | Ref
+  | Refkey
+  | CustomContext
+  | IntrinsicElement;
+
+export type Children = Child | Children[];
+export type Props = Record<string, any>;
+
+export interface ComponentDefinition<TProps = Props> {
+  (props: TProps): Children;
+}
+export interface Component<TProps = Props> {
+  (props: TProps): Children;
+  tag?: symbol;
+}
+
+export interface ComponentCreator<TProps = Props> {
+  component: Component<TProps>;
+  (): Children;
+  props: TProps;
+  tag?: symbol;
+}
+
+export function isComponentCreator<TProps = any>(
+  item: unknown,
+  component?: Component<TProps>,
+): item is ComponentCreator<TProps> {
+  if (!component) {
+    return typeof item === "function" && (item as any).component;
+  }
+  return typeof item === "function" && (item as any).component === component;
+}
+
+export function createComponent<TProps extends Props = Props>(
+  C: Component<TProps>,
+  props: TProps,
+): ComponentCreator<TProps> {
+  const creator: ComponentCreator<TProps> = () => /* */ C(props);
+  creator.props = props;
+  creator.component = C;
+  if (C.tag) {
+    creator.tag = C.tag;
+  }
+
+  return creator;
+}
+
+export function taggedComponent<TProps = Props>(
+  tag: symbol,
+  component: Component<TProps>,
+): Component<TProps> & Required<Pick<Component<TProps>, "tag">> {
+  component.tag = tag;
+  return component as any;
+}

package/src/runtime/intrinsic.ts

@@ -0,0 +1,199 @@
+import type { Children } from "./component.js";
+export interface IntrinsicElements {
+  /**
+   * Attempt to render the children on a single line if possible. If a group
+   * contains `<breakParent />` or a hard line, or if the group exceeds the
+   * print width, all linebreaks in the group will be broken.
+   */
+  group: { shouldBreak?: boolean; id?: symbol; children: Children };
+
+  /**
+   * A regular line break. This will break if the line exceeds the print
+   * width, otherwise it will be a space.
+   */
+  line: {};
+
+  /**
+   * A regular line break. This will break if the line exceeds the print
+   * width, otherwise it will be a space.
+   */
+  br: {};
+
+  /**
+   * A hard line break. This is a line that will always break, even if the
+   * group does not exceed print width.
+   */
+  hardline: {};
+
+  /**
+   * A hard line break. This is a line that will always break, even if the
+   * group does not exceed print width.
+   */
+  hbr: {};
+
+  /**
+   * A soft line break. This will break if the line exceeds the print width,
+   * otherwise it will be be nothing.
+   */
+  softline: {};
+
+  /**
+   * A soft line break. This will break if the line exceeds the print width,
+   * otherwise it will be be nothing.
+   */
+  sbr: {};
+
+  /**
+   * A literal line break. This will always break, even if the group does not
+   * exceed print width. The new line will ignore indentation.
+   */
+  literalline: {};
+
+  /**
+   * A literal line break. This will always break, even if the group does not
+   * exceed print width. The new line will ignore indentation.
+   */
+  lbr: {};
+
+  /**
+   * Increase the indentation level of the children of this component.
+   * Indentation is determined by the print options provided to the Output
+   * component or source file.
+   */
+  indent: { children: Children };
+
+  /**
+   * Indent the children of this component if the group specified by `groupId`
+   * is broken (or not broken if `negate` is passed). The specified group must
+   * already be printed.
+   */
+  indentIfBreak: { children: Children; groupId: symbol; negate?: boolean };
+
+  /**
+   * Similar to `group`, but will only place a line break before the last
+   * segment to exceed the print width. This is useful for formatting
+   * paragraphs of text where breaks are inserted prior to words which would
+   * otherwise exceed the print width.
+   */
+  fill: { children: Children };
+
+  /**
+   * Force the parent group to break.
+   */
+  breakParent: {};
+
+  /**
+   * Print children if the current group or already printed group specified by
+   * `groupId` is broken. Otherwise, `flatContents` is printed instead.
+   */
+  ifBreak: { children: Children; flatContents?: Children; groupId?: symbol };
+
+  /**
+   * Print this content at the end of the line. Useful for things like line
+   * comments.
+   */
+  lineSuffix: { children: Children };
+
+  /**
+   * Force any line suffixes to print at this point.
+   */
+  lineSuffixBoundary: {};
+
+  /**
+   * Decrease the indentation level of the children of this component.
+   * Indentation is determined by the print options provided to the Output
+   * component or source file.
+   */
+  dedent: { children: Children };
+
+  /**
+   * Indent the children of this component by either the number of characters
+   * indicated by the `width` prop, or by the provided string indicated by the
+   * `string` prop.
+   */
+  align:
+    | { children: Children; width: number }
+    | { children: Children; string: string };
+
+  /**
+   * Mark the current indentation level as "root" for the purposes of literal
+   * line breaks and `dedentToRoot`.
+   */
+  markAsRoot: { children: Children };
+
+  /**
+   * Decrease the indentation level to the root level specified by
+   * `<markAsRoot />`, or else to no indentation.
+   */
+  dedentToRoot: { children: Children };
+}
+export interface IntrinsicElementBase<
+  TKey extends keyof IntrinsicElements = keyof IntrinsicElements,
+> {
+  [intrinsicElementKey]: true;
+  name: TKey;
+  props: IntrinsicElements[TKey];
+}
+
+export function createIntrinsic<TKey extends keyof IntrinsicElements>(
+  name: TKey,
+  props: IntrinsicElements[TKey],
+): IntrinsicElementBase<TKey> {
+  return {
+    [intrinsicElementKey]: true,
+    name,
+    props,
+  };
+}
+
+export function isIntrinsicElement(type: unknown): type is IntrinsicElement {
+  return (
+    typeof type === "object" && type !== null && intrinsicElementKey in type
+  );
+}
+
+export const intrinsicElementKey = Symbol();
+export type IndentIntrinsicElement = IntrinsicElementBase<"indent">;
+export type IndentIfBreakIntrinsicElement =
+  IntrinsicElementBase<"indentIfBreak">;
+export type BrIntrinsicElement = IntrinsicElementBase<"br">;
+export type LineIntrinsicElement = IntrinsicElementBase<"line">;
+export type HbrIntrinsicElement = IntrinsicElementBase<"hbr">;
+export type HardlineIntrinsicElement = IntrinsicElementBase<"hardline">;
+export type SbrIntrinsicElement = IntrinsicElementBase<"sbr">;
+export type SoftlineIntrinsicElement = IntrinsicElementBase<"softline">;
+export type GroupIntrinsicElement = IntrinsicElementBase<"group">;
+export type AlignIntrinsicElement = IntrinsicElementBase<"align">;
+export type FillIntrinsicElement = IntrinsicElementBase<"fill">;
+export type BreakParentIntrinsicElement = IntrinsicElementBase<"breakParent">;
+export type LineSuffixIntrinsicElement = IntrinsicElementBase<"lineSuffix">;
+export type LineSuffixBoundaryIntrinsicElement =
+  IntrinsicElementBase<"lineSuffixBoundary">;
+export type DedentIntrinsicElement = IntrinsicElementBase<"dedent">;
+export type DedentToRootIntrinsicElement = IntrinsicElementBase<"dedentToRoot">;
+export type MarkAsRootIntrinsicElement = IntrinsicElementBase<"markAsRoot">;
+export type LiterallineIntrinsicElement = IntrinsicElementBase<"literalline">;
+export type LbrIntrinsicElement = IntrinsicElementBase<"lbr">;
+export type IfBreakIntrinsicElement = IntrinsicElementBase<"ifBreak">;
+
+export type IntrinsicElement =
+  | IndentIntrinsicElement
+  | IndentIfBreakIntrinsicElement
+  | BrIntrinsicElement
+  | LineIntrinsicElement
+  | HbrIntrinsicElement
+  | HardlineIntrinsicElement
+  | SbrIntrinsicElement
+  | SoftlineIntrinsicElement
+  | GroupIntrinsicElement
+  | AlignIntrinsicElement
+  | FillIntrinsicElement
+  | BreakParentIntrinsicElement
+  | LineSuffixIntrinsicElement
+  | LineSuffixBoundaryIntrinsicElement
+  | DedentIntrinsicElement
+  | LiterallineIntrinsicElement
+  | LbrIntrinsicElement
+  | DedentToRootIntrinsicElement
+  | MarkAsRootIntrinsicElement
+  | IfBreakIntrinsicElement;

package/src/scheduler.ts

@@ -3,22 +3,47 @@ import { ReactiveEffectRunner } from "@vue/reactivity";
 export interface QueueJob {
   (): any;
 }
+const immediateQueue = new Set<QueueJob>();
 const queue = new Set<QueueJob>();
 
-export function scheduler(jobGetter: () => ReactiveEffectRunner) {
+export function scheduler(
+  jobGetter: () => ReactiveEffectRunner,
+  immediate = false,
+) {
   return () => {
-    queueJob(jobGetter());
+    queueJob(jobGetter(), immediate);
   };
 }
-export function queueJob(job: QueueJob) {
+export function queueJob(job: QueueJob, immediate = false) {
+  // if we have an immediate job, we don't need to queue the normal job.
   // the set is serving an important purpose here in deduping the effects we run
   // (which in effect coalesces multiple update effects together).
-  queue.add(job);
+  if (immediate) {
+    immediateQueue.add(job);
+  } else {
+    queue.add(job);
+  }
 }
 
 export function flushJobs() {
-  for (const job of queue) {
-    queue.delete(job);
+  let job;
+  while ((job = takeJob()) !== null) {
     job();
   }
 }
+
+function takeJob() {
+  if (immediateQueue.size > 0) {
+    // return first item in immediateQueue
+    const job = immediateQueue.values().next().value!;
+    immediateQueue.delete(job);
+    return job;
+  }
+  if (queue.size > 0) {
+    // return first item in queue
+    const job = queue.values().next().value!;
+    queue.delete(job);
+    return job;
+  }
+  return null;
+}

package/src/slot.ts

@@ -1,12 +1,11 @@
 import { ref, Ref } from "@vue/reactivity";
-import { OutputSymbol } from "./binder.js";
+import { effect, memo } from "./reactivity.js";
 import {
   Children,
   Component,
   ComponentDefinition,
-  effect,
-  memo,
-} from "./jsx-runtime.js";
+} from "./runtime/component.js";
+import type { OutputSymbol } from "./symbols/output-symbol.js";
 
 export interface SlotInstance extends ComponentDefinition {}
 

package/src/stc.ts

@@ -1,9 +1,9 @@
+import { code, text } from "./code.js";
 import {
   Children,
   ComponentCreator,
   ComponentDefinition,
-} from "@alloy-js/core/jsx-runtime";
-import { code, text } from "./code.js";
+} from "./runtime/component.js";
 
 export type MakeChildrenOptional<T extends object> =
   T extends { children?: any } ?

package/src/sti.ts

@@ -1,19 +1,19 @@
+import { code, text } from "./code.js";
+import { Children } from "./runtime/component.js";
 import {
-  Children,
   createIntrinsic,
   IntrinsicElementBase,
-  JSX,
-} from "@alloy-js/core/jsx-runtime";
-import { code, text } from "./code.js";
+  IntrinsicElements,
+} from "./runtime/intrinsic.js";
 
-export type StiSignature<T extends keyof JSX.IntrinsicElements> = (
+export type StiSignature<T extends keyof IntrinsicElements> = (
   ...args: unknown extends T ? []
-  : {} extends Omit<JSX.IntrinsicElements[T], "children"> ?
-    [props?: JSX.IntrinsicElements[T]]
-  : [props: JSX.IntrinsicElements[T]]
+  : {} extends Omit<IntrinsicElements[T], "children"> ?
+    [props?: IntrinsicElements[T]]
+  : [props: IntrinsicElements[T]]
 ) => StiComponentCreator<T>;
 
-export type StiComponentCreator<T extends keyof JSX.IntrinsicElements> =
+export type StiComponentCreator<T extends keyof IntrinsicElements> =
   (() => IntrinsicElementBase<T>) & {
     code(
       template: TemplateStringsArray,
@@ -26,11 +26,11 @@ export type StiComponentCreator<T extends keyof JSX.IntrinsicElements> =
     children(...children: Children[]): () => IntrinsicElementBase<T>;
   };
 
-export function sti<T extends keyof JSX.IntrinsicElements>(
+export function sti<T extends keyof IntrinsicElements>(
   name: T,
 ): StiSignature<T> {
   return (...args) => {
-    const props: JSX.IntrinsicElements[T] | undefined = args[0];
+    const props: IntrinsicElements[T] | undefined = args[0];
     const fn: StiComponentCreator<T> = () => createIntrinsic(name, props!);
     fn.children = (...children: Children[]) => {
       const propsWithChildren = {

package/src/symbols/flags.ts

@@ -0,0 +1,82 @@
+/**
+ * Flags that describe an output scope.
+ */
+export enum OutputScopeFlags {
+  None = 0,
+
+  /**
+   * This scope is a static member scope.
+   */
+  StaticMemberScope = 1 << 0,
+
+  /**
+   * This scope is an instance member scope.
+   */
+  InstanceMemberScope = 1 << 1,
+
+  /**
+   * This scope is transient, and only exists to be merged with other scopes.
+   */
+  Transient = 1 << 2,
+
+  /**
+   * This scope is a member scope. Scopes with this flag will have an `owner`
+   * property that points to the symbol whose member this scope holds.
+   */
+  MemberScope = StaticMemberScope | InstanceMemberScope,
+}
+
+/**
+ * Flags that describe an output symbol.
+ */
+export enum OutputSymbolFlags {
+  None = 0,
+
+  /**
+   * The symbol is an instance member container. Symbols with this flag will have a
+   * instanceMemberScope property that contains symbols for instance members.
+   */
+  InstanceMemberContainer = 1 << 0,
+
+  /**
+   * The symbol is a static member container. Symbols with this flag will have a
+   * staticMemberScope property that contains symbols for static members.
+   */
+  StaticMemberContainer = 1 << 1,
+
+  /**
+   * Whether this symbol contains members of any kind.
+   */
+  MemberContainer = InstanceMemberContainer | StaticMemberContainer,
+
+  /**
+   * Whether this symbol is an instance member of another symbol (i.e that it is
+   * stored in an instance member scope).
+   */
+  InstanceMember = 1 << 2,
+
+  /**
+   * Whether this symbol is a static member of another symbol (i.e that it is
+   * stored in a static member scope).
+   */
+  StaticMember = 1 << 3,
+
+  /**
+   * Transient symbols are not added to symbol tables and do not create
+   * referencable refkeys. They are used for temporary symbols that are intended
+   * to be used to calculate other symbols.
+   */
+  Transient = 1 << 4,
+
+  /**
+   * This symbol aliases another symbol. Only its name, flags, and scope are
+   * stored in this symbol. Otherwise, everything else is located on the alias
+   * target.
+   */
+  Alias = 1 << 5,
+
+  /**
+   * Whether this is an instance member or static member of another symbol.
+   */
+  Member = InstanceMember | StaticMember,
+}

package/src/symbols/index.ts

@@ -0,0 +1,6 @@
+export * from "./flags.js";
+export * from "./output-scope.js";
+export * from "./output-symbol.js";
+export * from "./symbol-flow.js";
+export * from "./symbol-slot.js";
+export * from "./symbol-table.js";