@alloy-js/core 0.21.0-dev.1 → 0.21.0-dev.10

package/src/binder.ts

@@ -3,7 +3,14 @@ import { useBinder } from "./context/binder.js";
 import { useMemberContext } from "./context/member-scope.js";
 import { useScope } from "./context/scope.js";
 import { effect } from "./reactivity.js";
-import { isMemberRefkey, refkey, Refkey } from "./refkey.js";
+import {
+  isMemberRefkey,
+  MemberRefkey,
+  refkey,
+  Refkey,
+  Refkeyable,
+  toRefkey,
+} from "./refkey.js";
 import { OutputScope } from "./symbols/output-scope.js";
 import { type OutputSymbol } from "./symbols/output-symbol.js";
 import {
@@ -49,7 +56,7 @@ export interface Binder {
    * ref is undefined if the symbol has not been created yet.
    */
   getSymbolForRefkey<TSymbol extends OutputSymbol>(
-    refkey: Refkey,
+    refkey: Refkeyable,
   ): Ref<TSymbol | undefined>;
 
   /**
@@ -392,8 +399,10 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   }
 
   function getSymbolForRefkey<TSymbol extends OutputSymbol = OutputSymbol>(
-    refkey: Refkey,
+    refkeyable: Refkeyable,
   ) {
+    const refkey = toRefkey(refkeyable);
+
     if (waitingDeclarations.has(refkey)) {
       return waitingDeclarations.get(refkey)! as ShallowRef<TSymbol>;
     }
@@ -404,7 +413,9 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       const baseSymbolRef: ShallowRef<TSymbol | undefined> =
         getSymbolForRefkey<TSymbol>(refkey.base);
       const memberSymbolRef: ShallowRef<TSymbol | undefined> =
-        getSymbolForRefkey<TSymbol>(refkey.member);
+        getMemberSymbolFromMemberRefkey(refkey) as ShallowRef<
+          TSymbol | undefined
+        >;
 
       symbolRef = computed(() => {
         // even though we don't necessarily need the base symbol to be available
@@ -558,7 +569,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       return [
         ...getMemberPathFromRefkey(refkey.base),
         {
-          symbol: getSymbolForRefkey(refkey.member).value!,
+          symbol: getMemberSymbolFromMemberRefkey(refkey).value!,
           isMemberAccess: true,
         },
       ];
@@ -572,6 +583,23 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     ];
   }
 
+  function getMemberSymbolFromMemberRefkey(
+    refkey: MemberRefkey,
+  ): Ref<OutputSymbol | undefined> {
+    if (typeof refkey.member === "string") {
+      return computed(() => {
+        const baseSymbol = getSymbolForRefkey(refkey.base).value;
+        if (!baseSymbol) {
+          return undefined;
+        }
+
+        return baseSymbol.resolveMemberByName(refkey.member as string);
+      });
+    } else {
+      return getSymbolForRefkey(refkey.member);
+    }
+  }
+
   function resolveMember(
     base: OutputSymbol,
     member: OutputSymbol,
@@ -692,7 +720,7 @@ export function resolve<
  * not found. The symbol you're looking for may not have been declared yet. When the symbol
  * is declared, the ref will be updated with the symbol.
  */
-export function symbolForRefkey(refkey: Refkey) {
+export function symbolForRefkey(refkey: Refkeyable) {
   const binder = useBinder();
   if (!binder) {
     throw new Error("Can't resolve refkey without a binder");

package/src/index.ts

@@ -27,6 +27,7 @@ export * from "./code.js";
 export * from "./components/index.js";
 export * from "./context.js";
 export * from "./context/index.js";
+export * from "./library-symbol-reference.js";
 export * from "./name-policy.js";
 export * from "./props-combinators.js";
 export * from "./reactive-union-set.js";

package/src/library-symbol-reference.ts

@@ -0,0 +1,20 @@
+import { RefkeyableObject } from "./refkey.js";
+import { OutputSymbol } from "./symbols/output-symbol.js";
+
+export const TO_SYMBOL: unique symbol = Symbol(
+  "Alloy.RefkeyableObject.TO_SYMBOL",
+);
+
+export interface LibrarySymbolReference extends RefkeyableObject {
+  [TO_SYMBOL](): OutputSymbol;
+}
+
+export function isLibrarySymbolReference(
+  value: unknown,
+): value is LibrarySymbolReference {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.hasOwn(value, TO_SYMBOL)
+  );
+}

package/src/pretty-string/pretty-string.test.ts

@@ -0,0 +1,47 @@
+import { expect, it } from "vitest";
+import { pret, PrettyString } from "./pretty-string.js";
+
+function expectRender(
+  pretty: PrettyString,
+  expected: {
+    toString: string;
+    toAnsi: string;
+  },
+) {
+  expect(pretty.toString()).toBe(expected.toString);
+  expect(pretty.toAnsi()).toBe(expected.toAnsi);
+}
+
+it("interpolate basic string", () => {
+  const result = pret`foo ${"bar"} baz`;
+  expectRender(result, {
+    toString: "foo bar baz",
+    toAnsi: "foo bar baz",
+  });
+});
+
+// cspell:ignore mbar
+it("interpolate pretty segment", () => {
+  const result = pret`foo ${pret.red("bar")} baz`;
+  expectRender(result, {
+    toString: "foo bar baz",
+    toAnsi: "foo \x1b[31mbar\x1b[39m baz",
+  });
+});
+
+it("interpolate another pretty string with more formatting", () => {
+  const a = pret`foo ${pret.red("bar")} baz`;
+  const result = pret`Hi, ${pret.bgGreen(a)}`;
+  expectRender(result, {
+    toString: "Hi, foo bar baz",
+    toAnsi: "Hi, \x1b[42mfoo \x1b[31mbar\x1b[39m baz\x1b[49m",
+  });
+});
+
+it("use full rgb", () => {
+  const result = pret`foo ${pret.rgb(123, 45, 67, "bar")} baz`;
+  expectRender(result, {
+    toString: "foo bar baz",
+    toAnsi: "foo \x1b[38;2;123;45;67mbar\x1b[39m baz",
+  });
+});

package/src/pretty-string/pretty-string.ts

@@ -0,0 +1,130 @@
+import { inspect } from "../inspect.js";
+
+export function pret(
+  strings: TemplateStringsArray,
+  ...keys: PrettyStringSegment[]
+): PrettyString {
+  const result: PrettyStringSegment[] = [strings[0]];
+  keys.forEach((key, i) => {
+    result.push(key);
+    result.push(strings[i + 1]);
+  });
+
+  return new PrettyString(result);
+}
+
+pret.black = (x: PrettyStringSegment) => new PrettyStringColored(x, "black");
+pret.red = (x: PrettyStringSegment) => new PrettyStringColored(x, "red");
+pret.green = (x: PrettyStringSegment) => new PrettyStringColored(x, "green");
+pret.yellow = (x: PrettyStringSegment) => new PrettyStringColored(x, "yellow");
+pret.blue = (x: PrettyStringSegment) => new PrettyStringColored(x, "blue");
+pret.magenta = (x: PrettyStringSegment) =>
+  new PrettyStringColored(x, "magenta");
+pret.cyan = (x: PrettyStringSegment) => new PrettyStringColored(x, "cyan");
+pret.white = (x: PrettyStringSegment) => new PrettyStringColored(x, "white");
+pret.gray = (x: PrettyStringSegment) => new PrettyStringColored(x, "gray");
+
+pret.bgBlack = (x: PrettyStringSegment) =>
+  new PrettyStringColored(x, "bgBlack");
+pret.bgRed = (x: PrettyStringSegment) => new PrettyStringColored(x, "bgRed");
+pret.bgGreen = (x: PrettyStringSegment) =>
+  new PrettyStringColored(x, "bgGreen");
+pret.bgYellow = (x: PrettyStringSegment) =>
+  new PrettyStringColored(x, "bgYellow");
+pret.bgBlue = (x: PrettyStringSegment) => new PrettyStringColored(x, "bgBlue");
+pret.bgMagenta = (x: PrettyStringSegment) =>
+  new PrettyStringColored(x, "bgMagenta");
+pret.bgCyan = (x: PrettyStringSegment) => new PrettyStringColored(x, "bgCyan");
+pret.bgWhite = (x: PrettyStringSegment) =>
+  new PrettyStringColored(x, "bgWhite");
+
+pret.rgb = (r: number, g: number, b: number, x: PrettyStringSegment) =>
+  new PrettyStringColored(x, { kind: "rgb", r, g, b });
+
+const ansiColors = {
+  reset: ["\x1b[0m", "\x1b[0m"],
+  bold: ["\x1b[1m", "\x1b[22m"],
+  dim: ["\x1b[2m", "\x1b[22m"],
+  italic: ["\x1b[3m", "\x1b[23m"],
+  underline: ["\x1b[4m", "\x1b[24m"],
+  inverse: ["\x1b[7m", "\x1b[27m"],
+  hidden: ["\x1b[8m", "\x1b[28m"],
+  strikethrough: ["\x1b[9m", "\x1b[29m"],
+  black: ["\x1b[30m", "\x1b[39m"],
+  red: ["\x1b[31m", "\x1b[39m"],
+  green: ["\x1b[32m", "\x1b[39m"],
+  yellow: ["\x1b[33m", "\x1b[39m"],
+  blue: ["\x1b[34m", "\x1b[39m"],
+  magenta: ["\x1b[35m", "\x1b[39m"],
+  cyan: ["\x1b[36m", "\x1b[39m"],
+  white: ["\x1b[37m", "\x1b[39m"],
+  gray: ["\x1b[90m", "\x1b[39m"],
+  bgBlack: ["\x1b[40m", "\x1b[49m"],
+  bgRed: ["\x1b[41m", "\x1b[49m"],
+  bgGreen: ["\x1b[42m", "\x1b[49m"],
+  bgYellow: ["\x1b[43m", "\x1b[49m"],
+  bgBlue: ["\x1b[44m", "\x1b[49m"],
+  bgMagenta: ["\x1b[45m", "\x1b[49m"],
+  bgCyan: ["\x1b[46m", "\x1b[49m"],
+  bgWhite: ["\x1b[47m", "\x1b[49m"],
+} as Record<string, [string, string]>;
+
+export type PrettyStringSegment = string | PrettyStringColored | PrettyString;
+
+export interface RgbColor {
+  kind: "rgb";
+  r: number;
+  g: number;
+  b: number;
+}
+
+export type ColorCodes = keyof typeof ansiColors;
+export type Color = ColorCodes | RgbColor;
+export class PrettyStringColored {
+  #value: PrettyStringSegment;
+  #color: Color;
+
+  constructor(value: PrettyStringSegment, color: Color) {
+    this.#value = value;
+    this.#color = color;
+  }
+
+  toString(): string {
+    return this.#value.toString();
+  }
+
+  toAnsi(): string {
+    if (typeof this.#color === "string") {
+      const [start, end] = ansiColors[this.#color];
+      return `${start}${typeof this.#value === "string" ? this.#value : this.#value.toAnsi()}${end}`;
+    }
+    const { r, g, b } = this.#color;
+    const start = `\x1b[38;2;${r};${g};${b}m`;
+    const end = `\x1b[39m`;
+    return `${start}${typeof this.#value === "string" ? this.#value : this.#value.toAnsi()}${end}`;
+  }
+}
+
+export class PrettyString {
+  #segments: PrettyStringSegment[];
+
+  constructor(segments: PrettyStringSegment[]) {
+    this.#segments = segments;
+  }
+
+  toString(): string {
+    return this.#segments
+      .map((s) => (typeof s === "string" ? s : s.toString()))
+      .join("");
+  }
+
+  toAnsi(): string {
+    return this.#segments
+      .map((s) => (typeof s === "string" ? s : s.toAnsi()))
+      .join("");
+  }
+
+  [inspect.custom]() {
+    return this.toAnsi();
+  }
+}

package/src/refkey.ts

@@ -14,15 +14,20 @@ function getObjectKey(value: WeakKey): string {
   return key;
 }
 
-const RefkeySym: unique symbol = Symbol();
+export const REFKEYABLE: unique symbol = Symbol("Alloy.REFKEYABLE");
 
-export type RefkeyBase = {
-  [RefkeySym]: true;
+export type RefkeyableObject = {
+  [REFKEYABLE](): Refkey;
 };
 
+export function toRefkey(refkey: Refkeyable) {
+  return refkey[REFKEYABLE]();
+}
+
+export type Refkeyable = RefkeyableObject | Refkey;
 export type Refkey = SymbolRefkey | MemberRefkey | Namekey;
 
-export interface SymbolRefkey extends RefkeyBase {
+export interface SymbolRefkey extends RefkeyableObject {
   key: string;
 }
 
@@ -37,15 +42,17 @@ export interface Namekey<TOptions extends NamekeyOptions = NamekeyOptions>
   options: TOptions;
 }
 
-export interface MemberRefkey extends RefkeyBase {
+export interface MemberRefkey extends RefkeyableObject {
   base: Refkey;
-  member: Refkey;
+  member: Refkey | string;
 }
 
 function createSymbolRefkey(key: string): SymbolRefkey {
   const refkey: SymbolRefkey = {
     key,
-    [RefkeySym]: true,
+    [REFKEYABLE]() {
+      return this;
+    },
   };
 
   markRaw(refkey);
@@ -53,11 +60,16 @@ function createSymbolRefkey(key: string): SymbolRefkey {
   return refkey;
 }
 
-export function isRefkey(value: unknown): value is Refkey {
+export function isRefkeyable(value: unknown): value is RefkeyableObject {
   return (
     typeof value === "object" &&
     value !== null &&
-    Object.hasOwn(value, RefkeySym)
+    Object.hasOwn(value, REFKEYABLE)
+  );
+}
+export function isRefkey(value: unknown): value is Refkey {
+  return (
+    isRefkeyable(value) && (value as RefkeyableObject)[REFKEYABLE]() === value
   );
 }
 
@@ -66,11 +78,7 @@ export function isSymbolRefkey(value: unknown): value is SymbolRefkey {
 }
 
 export function isMemberRefkey(value: unknown): value is MemberRefkey {
-  return (
-    isRefkey(value) &&
-    Object.hasOwn(value, "base") &&
-    Object.hasOwn(value, "member")
-  );
+  return isRefkey(value) && Object.hasOwn(value, "base");
 }
 
 export function isNamekey(value: unknown): value is Namekey {
@@ -82,9 +90,14 @@ export function isNamekey(value: unknown): value is Namekey {
  * return the key of that refkey, objects get a unique key for that specific object,
  * and otherwise the key is based on the value.
  */
-function getKey(value: unknown): SymbolRefkey["key"] {
-  if (isSymbolRefkey(value)) {
-    return value.key;
+function getKey(value: unknown): string {
+  if (isRefkeyable(value)) {
+    const refkey = toRefkey(value);
+    if (isSymbolRefkey(refkey)) {
+      return refkey.key;
+    } else {
+      return getObjectKey(value);
+    }
   } else if (typeof value === "object" && value !== null) {
     return getObjectKey(value);
   } else {
@@ -142,7 +155,9 @@ export function namekey(name: string, options: NamekeyOptions = {}): Namekey {
     key: getObjectKey({}),
     name,
     options,
-    [RefkeySym]: true,
+    [REFKEYABLE]() {
+      return this;
+    },
   };
 }
 /**
@@ -168,8 +183,8 @@ export function namekey(name: string, options: NamekeyOptions = {}): Namekey {
  * `refkey(rk1, rk3)`.
  */
 export function memberRefkey(
-  base: Refkey,
-  ...members: [Refkey, ...Refkey[]]
+  base: Refkeyable,
+  ...members: [Refkeyable | string, ...(Refkeyable | string)[]]
 ): MemberRefkey {
   if (members.length < 1) {
     throw new Error("memberRefkey needs at least one member");
@@ -177,18 +192,44 @@ export function memberRefkey(
 
   if (members.length === 1) {
     return {
-      base,
-      member: members[0],
-      [RefkeySym]: true,
+      base: toRefkey(base),
+      member:
+        typeof members[0] === "string" ? members[0] : toRefkey(members[0]),
+      [REFKEYABLE]() {
+        return this;
+      },
     };
   }
 
+  const lastMember = members.at(-1)!;
+
   return {
     base: memberRefkey(
       base,
-      ...(members.slice(0, -1) as [Refkey, ...Refkey[]]),
+      ...(members.slice(0, -1) as [Refkeyable, ...Refkeyable[]]),
     ),
-    member: members.at(-1)!,
-    [RefkeySym]: true,
+    member: typeof lastMember === "string" ? lastMember : toRefkey(lastMember),
+    [REFKEYABLE]() {
+      return this;
+    },
   };
 }
+
+export function inspectRefkey(refkey: Refkey): string {
+  const unwrapped = refkey[REFKEYABLE]();
+
+  const text =
+    isMemberRefkey(unwrapped) ?
+      `memberRefkey[${inspectRefkey(unwrapped.base)} -> ${
+        typeof unwrapped.member === "string" ?
+          unwrapped.member
+        : inspectRefkey(unwrapped.member)
+      }]`
+    : `refkey[${unwrapped.key}]`;
+
+  return text;
+}
+
+export function unresolvedRefkey(refkey: Refkey): string {
+  return `<Unresolved Symbol: ${inspectRefkey(refkey)}>`;
+}

package/src/render.ts

@@ -14,13 +14,15 @@ import {
   root,
   untrack,
 } from "./reactivity.js";
-import { isRefkey } from "./refkey.js";
+import { isRefkeyable, toRefkey } from "./refkey.js";
 import {
   Child,
   Children,
   Component,
   isComponentCreator,
+  isRenderableObject,
   Props,
+  RENDERABLE,
 } from "./runtime/component.js";
 import { IntrinsicElement, isIntrinsicElement } from "./runtime/intrinsic.js";
 import { flushJobs, flushJobsAsync } from "./scheduler.js";
@@ -539,15 +541,19 @@ function normalizeChild(child: Child): NormalizedChildren {
     return "";
   } else if (isRef(child)) {
     return () => child.value as () => Child;
-  } else if (isRefkey(child)) {
+  } else if (isRefkeyable(child)) {
+    const refkey = toRefkey(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 });
+      return sfContext.reference({ refkey });
     };
+  } else if (isRenderableObject(child)) {
+    // For custom renderable objects, we will just normalize them to a bound function.
+    return child[RENDERABLE].bind(child);
   } else if (isCustomContext(child)) {
     return child;
   } else if (isIntrinsicElement(child)) {
@@ -573,6 +579,8 @@ function debugPrintChild(child: Children): string {
     return "$ref";
   } else if (isIntrinsicElement(child)) {
     return `<${child.name}>`;
+  } else if (isRenderableObject(child)) {
+    return `CustomChildElement(${JSON.stringify(child)})`;
   } else {
     return JSON.stringify(child);
   }

package/src/runtime/component.ts

@@ -1,9 +1,41 @@
 import { Ref } from "@vue/reactivity";
 import { CustomContext } from "../reactivity.js";
-import { Refkey } from "../refkey.js";
+import { Refkey, RefkeyableObject } from "../refkey.js";
 import { IntrinsicElement } from "./intrinsic.js";
 
+export const RENDERABLE = Symbol.for("Alloy.CustomElement");
+
+/**
+ * A renderable object is any object that has an `[ay.RENDERABLE]` method that
+ * returns children. This is used to allow custom object types to be used as
+ * children in Alloy components.
+ */
+export interface RenderableObject {
+  /**
+   * Renders this object to children.
+   */
+  [RENDERABLE](): Children;
+}
+
+/**
+ * Returns true if the item is a renderable object, meaning it has an `[ay.RENDERABLE]`
+ * method.
+ *
+ * @param item - The item to check.
+ * @returns True if the item is a renderable object.
+ */
+export function isRenderableObject(item: unknown): item is RenderableObject {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    RENDERABLE in item &&
+    typeof (item as any)[RENDERABLE] === "function"
+  );
+}
+
 export type Child =
+  | RenderableObject
+  | RefkeyableObject
   | string
   | boolean
   | number

package/src/symbols/output-symbol.ts

@@ -94,6 +94,11 @@ export interface OutputSymbolOptions {
    * also ignoring name conflict resolution.
    */
   ignoreNameConflict?: boolean;
+
+  /**
+   * Provide a function which lazy-initializes members when an enumeration of members are needed.
+   */
+  lazyMemberInitializer?: () => void;
 }
 
 let symbolCount = 0;
@@ -459,6 +464,40 @@ export abstract class OutputSymbol {
     return this.#namePolicy;
   }
 
+  #lazyMemberInitializer: (() => void) | undefined;
+  #lazyMembersInitialized: boolean = false;
+
+  #initializeMembers() {
+    if (this.#lazyMemberInitializer && !this.#lazyMembersInitialized) {
+      this.#lazyMemberInitializer();
+    }
+    this.#lazyMembersInitialized = true;
+  }
+
+  /**
+   * Get a member symbol by name from this symbol's member spaces. Checks member
+   * spaces in order until it finds a member with that name.
+   */
+  resolveMemberByName(name: string): OutputSymbol | undefined {
+    this.#initializeMembers();
+
+    if (this.isTyped) {
+      if (!this.hasTypeSymbol) {
+        return undefined;
+      }
+
+      return this.type!.resolveMemberByName(name);
+    }
+    for (const space of this.memberSpaces) {
+      const member = space.symbolNames.get(name);
+      if (member) {
+        return member;
+      }
+    }
+
+    return undefined;
+  }
+
   // Tell \@vue/reactivity that this symbol should never be wrapped in a reactive
   // proxy.
   [ReactiveFlags.SKIP] = true;
@@ -502,6 +541,7 @@ export abstract class OutputSymbol {
     this.#isTransient = !!options.transient;
     this.#isTyped = !!options.type;
     this.type = options.type;
+    this.#lazyMemberInitializer = options.lazyMemberInitializer;
 
     this.#handleNewSpaces(this.#spaces);
     const constructor = this.constructor as typeof OutputSymbol;

package/src/tracer.ts

@@ -1,6 +1,6 @@
 import { effect, ReactiveEffectRunner } from "@vue/reactivity";
 import { untrack } from "./reactivity.js";
-import { isMemberRefkey, type Refkey } from "./refkey.js";
+import { inspectRefkey, type Refkey } from "./refkey.js";
 import { scheduler } from "./scheduler.js";
 import { type OutputScope } from "./symbols/output-scope.js";
 import type {
@@ -429,10 +429,7 @@ export function formatRefkeys(refkeys: Refkey[] | Refkey | undefined) {
 }
 
 function formatRefkey(refkey: Refkey): string {
-  const text =
-    isMemberRefkey(refkey) ?
-      `memberRefkey[${formatRefkey(refkey.base)} -> ${formatRefkey(refkey.member)}]`
-    : `refkey[${refkey.key}]`;
+  const text = inspectRefkey(refkey);
 
   return colorText(text, {
     fg: {