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

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

@@ -192,3 +192,16 @@ export function memberRefkey(
     [RefkeySym]: true,
   };
 }
+
+export function inspectRefkey(refkey: Refkey): string {
+  const text =
+    isMemberRefkey(refkey) ?
+      `memberRefkey[${inspectRefkey(refkey.base)} -> ${inspectRefkey(refkey.member)}]`
+    : `refkey[${refkey.key}]`;
+
+  return text;
+}
+
+export function unresolvedRefkey(refkey: Refkey): string {
+  return `<Unresolved Symbol: ${inspectRefkey(refkey)}>`;
+}

package/src/render.ts

@@ -20,7 +20,9 @@ import {
   Children,
   Component,
   isComponentCreator,
+  isRenderableObject,
   Props,
+  RENDERABLE,
 } from "./runtime/component.js";
 import { IntrinsicElement, isIntrinsicElement } from "./runtime/intrinsic.js";
 import { flushJobs, flushJobsAsync } from "./scheduler.js";
@@ -548,6 +550,9 @@ function normalizeChild(child: Child): NormalizedChildren {
 
       return sfContext.reference({ refkey: child });
     };
+  } 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 +578,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

@@ -3,7 +3,38 @@ import { CustomContext } from "../reactivity.js";
 import { Refkey } 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
   | string
   | boolean
   | number

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: {

package/temp/api.json

@@ -2233,9 +2233,14 @@
               "kind": "Content",
               "text": "export type Child = "
             },
+            {
+              "kind": "Reference",
+              "text": "RenderableObject",
+              "canonicalReference": "@alloy-js/core!RenderableObject:interface"
+            },
             {
               "kind": "Content",
-              "text": "string | boolean | number | undefined | null | void | (() => "
+              "text": " | string | boolean | number | undefined | null | void | (() => "
             },
             {
               "kind": "Reference",
@@ -2288,7 +2293,7 @@
           "name": "Child",
           "typeTokenRange": {
             "startIndex": 1,
-            "endIndex": 11
+            "endIndex": 12
           }
         },
         {
@@ -7668,6 +7673,52 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@alloy-js/core!inspectRefkey:function(1)",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function inspectRefkey(refkey: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Refkey",
+              "canonicalReference": "@alloy-js/core!Refkey:type"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/refkey.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "refkey",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "inspectRefkey"
+        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!instantiateTakenMembersTo:function(1)",
@@ -9273,6 +9324,61 @@
           ],
           "name": "isRefkey"
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@alloy-js/core!isRenderableObject:function(1)",
+          "docComment": "/**\n * Returns true if the item is a renderable object, meaning it has an `[ay.RENDERABLE]`\n * method.\n *\n * @param item - The item to check.\n *\n * @returns  True if the item is a renderable object.\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function isRenderableObject(item: "
+            },
+            {
+              "kind": "Content",
+              "text": "unknown"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "item",
+              "canonicalReference": "@alloy-js/core!~item"
+            },
+            {
+              "kind": "Content",
+              "text": " is "
+            },
+            {
+              "kind": "Reference",
+              "text": "RenderableObject",
+              "canonicalReference": "@alloy-js/core!RenderableObject:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/runtime/component.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 6
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "item",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "isRenderableObject"
+        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!isSymbolRefkey:function(1)",
@@ -17634,7 +17740,16 @@
             },
             {
               "kind": "Content",
-              "text": "<string | number | boolean | void | (() => "
+              "text": "<string | number | boolean | void | import(\"../runtime/component.js\")."
+            },
+            {
+              "kind": "Reference",
+              "text": "RenderableObject",
+              "canonicalReference": "@alloy-js/core!RenderableObject:interface"
+            },
+            {
+              "kind": "Content",
+              "text": " | (() => "
             },
             {
               "kind": "Reference",
@@ -17878,7 +17993,7 @@
           "fileUrlPath": "src/components/ReferenceOrContent.tsx",
           "returnTypeTokenRange": {
             "startIndex": 3,
-            "endIndex": 58
+            "endIndex": 60
           },
           "releaseTag": "Public",
           "overloadIndex": 1,
@@ -18158,6 +18273,85 @@
           ],
           "name": "render"
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@alloy-js/core!RENDERABLE:var",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "RENDERABLE: "
+            },
+            {
+              "kind": "Content",
+              "text": "unique symbol"
+            }
+          ],
+          "fileUrlPath": "src/runtime/component.ts",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "RENDERABLE",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@alloy-js/core!RenderableObject:interface",
+          "docComment": "/**\n * A renderable object is any object that has an `[ay.RENDERABLE]` method that\n * returns children. This is used to allow custom object types to be used as\n * children in Alloy components.\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface RenderableObject "
+            }
+          ],
+          "fileUrlPath": "src/runtime/component.ts",
+          "releaseTag": "Public",
+          "name": "RenderableObject",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@alloy-js/core!RenderableObject#[RENDERABLE]:member(1)",
+              "docComment": "/**\n * Renders this object to children.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "["
+                },
+                {
+                  "kind": "Reference",
+                  "text": "RENDERABLE",
+                  "canonicalReference": "@alloy-js/core!RENDERABLE:var"
+                },
+                {
+                  "kind": "Content",
+                  "text": "](): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Children",
+                  "canonicalReference": "@alloy-js/core!Children:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [],
+              "name": "[RENDERABLE]"
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!renderAsync:function(1)",
@@ -23233,6 +23427,52 @@
           ],
           "name": "traverseOutput"
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@alloy-js/core!unresolvedRefkey:function(1)",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function unresolvedRefkey(refkey: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Refkey",
+              "canonicalReference": "@alloy-js/core!Refkey:type"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/refkey.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "refkey",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "unresolvedRefkey"
+        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/core!untrack:function(1)",

package/test/rendering/basic.test.tsx

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { Children } from "../../src/runtime/component.js";
+import { Children, RENDERABLE } from "../../src/runtime/component.js";
 import "../../testing/extend-expect.js";
 describe("string nodes", () => {
   it("renders string nodes with substitutions", () => {
@@ -49,6 +49,40 @@ describe("component nodes", () => {
       </>,
     ).toRenderTo("Str Str");
   });
+
+  it("renders custom elements", () => {
+    const customElement = {
+      [RENDERABLE]() {
+        return (
+          <>
+            <Str /> <Str />
+          </>
+        );
+      },
+    };
+
+    expect(customElement).toRenderTo("Str Str");
+  });
+
+  it("renders nested custom elements", () => {
+    const e1 = {
+      [RENDERABLE]() {
+        return <Str />;
+      },
+    };
+
+    const e2 = {
+      [RENDERABLE]() {
+        return (
+          <>
+            {e1} {e1}
+          </>
+        );
+      },
+    };
+
+    expect(e2).toRenderTo("Str Str");
+  });
 });
 
 describe("memo nodes", () => {