@alloy-js/core 0.4.0 → 0.6.0

package/src/jsx-runtime.ts

@@ -1,14 +1,18 @@
 // Much of the implementations in this file are inspired by vuerx-js
 // See: https://github.com/ryansolid/vuerx-jsx.
 import {
+  isReactive,
   pauseTracking,
+  proxyRefs,
   Ref,
   resetTracking,
   shallowRef,
   stop,
+  toRefs,
   effect as vueEffect,
 } from "@vue/reactivity";
 import { Refkey } from "./refkey.js";
+import { RenderedTextTree } from "./render.js";
 
 if ((globalThis as any).ALLOY) {
   throw new Error(
@@ -31,6 +35,11 @@ export interface Context {
   // store random info about the node
   meta?: Record<string, any>;
 
+  /**
+   * A cache of RenderTextTree nodes created within this context,
+   * indexed by the component or function which created them.
+   */
+  elementCache: ElementCache;
   /**
    * When this context was created by a component, this will
    * be the component that created it.
@@ -43,21 +52,35 @@ export function getContext() {
   return globalContext;
 }
 
-export function root<T>(
-  fn: (d: Disposable) => T,
-  componentOwner?: ComponentCreator<any>,
-): T {
-  globalContext = {
-    componentOwner,
+export function getElementCache() {
+  return getContext()!.elementCache;
+}
+
+export type ElementCacheKey =
+  | ComponentCreator
+  | (() => unknown)
+  | CustomContext;
+export type ElementCache = Map<ElementCacheKey, RenderedTextTree>;
+
+export interface RootOptions {
+  componentOwner?: ComponentCreator<any>;
+}
+
+export function root<T>(fn: (d: Disposable) => T, options?: RootOptions): T {
+  const context: Context = {
+    componentOwner: options?.componentOwner,
     disposables: [],
     owner: globalContext,
     context: {},
+    elementCache: new Map(),
   };
+
+  globalContext = context;
   let ret;
   try {
     ret = untrack(() =>
       fn(() => {
-        for (const d of globalContext!.disposables) {
+        for (const d of context!.disposables) {
           d();
         }
       }),
@@ -83,28 +106,31 @@ export function memo<T>(fn: () => T, equal?: boolean): () => T {
     // eslint-disable-next-line @typescript-eslint/no-unused-expressions
     (!equal || prev !== res) && (o.value = res);
     return res;
-  });
+  }, undefined as T);
   return () => o.value;
 }
 
 export function effect<T>(fn: (prev?: T) => T, current?: T) {
-  const context = {
-    src: "effect",
+  const context: Context = {
     context: {},
     disposables: [] as (() => void)[],
     owner: globalContext,
-  } as any;
+    elementCache: new Map(),
+  };
 
   const cleanupFn = (final: boolean) => {
     const d = context.disposables;
     context.disposables = [];
     for (let k = 0, len = d.length; k < len; k++) d[k]();
+
     // eslint-disable-next-line @typescript-eslint/no-unused-expressions
     final && stop(c);
   };
 
+  onCleanup(() => cleanupFn(true));
   const c = vueEffect(() => {
     cleanupFn(false);
+
     const oldContext = globalContext;
     globalContext = context;
     try {
@@ -112,41 +138,90 @@ export function effect<T>(fn: (prev?: T) => T, current?: T) {
     } finally {
       globalContext = oldContext;
     }
-  });
-
-  cleanup(() => cleanupFn(true));
+  }, {});
 }
 
-function cleanup(fn: Disposable) {
+/**
+ * Register a cleanup function which is called when the current reactive scope
+ * is recalculated or disposed. This is useful to clean up any side effects
+ * created in the reactive scope.
+ *
+ * @remarks
+ *
+ * When onCleanup is called inside a component definition, the provided function
+ * is called when the component is removed from the tree. This can be useful to
+ * clean up any side effects created as a result of rendering the component. For
+ * example, if rendering a component creates a symbol, `onCleanup` can be used
+ * to remove the symbol when the component is removed from the tree.
+ *
+ * When onCleanup is called inside a memo or effect, the function is called when
+ * the effect is refreshed (e.g. when a memo or computed recalculates) or
+ * disposed (e.g. it is no longer needed because it is attached to a component
+ * which was removed).
+ */
+export function onCleanup(fn: Disposable) {
   if (globalContext != null) {
     globalContext.disposables.push(fn);
   }
 }
 
+/**
+ * Create a custom reactive context for the children returned by
+ * the provided context.
+ */
+export interface CustomContext {
+  [CUSTOM_CONTEXT_SYM]: true;
+  useCustomContext: (useCb: CustomContextChildrenCallback) => void;
+}
+
+export type CustomContextChildrenCallback = (child: Children) => void;
+const CUSTOM_CONTEXT_SYM = Symbol();
+
+export function createCustomContext(
+  useCallback: (useChildren: CustomContextChildrenCallback) => void,
+): CustomContext {
+  return {
+    [CUSTOM_CONTEXT_SYM]: true,
+    useCustomContext(useCb: (children: Children) => void): void {
+      useCallback(useCb);
+    },
+  };
+}
+
+export function isCustomContext(child: Children): child is CustomContext {
+  return (
+    typeof child === "object" &&
+    child !== null &&
+    Object.hasOwn(child, CUSTOM_CONTEXT_SYM)
+  );
+}
+
 export type Child =
   | string
   | boolean
   | number
   | undefined
   | null
-  | (() => Child | Children)
-  | Child[]
+  | void
+  | (() => Children)
   | Ref
-  | Refkey;
+  | Refkey
+  | CustomContext
+  | IntrinsicElement;
 
-export type Children = Child | Child[];
-export type Props = Record<string, unknown>;
+export type Children = Child | Children[];
+export type Props = Record<string, any>;
 
 export interface ComponentDefinition<TProps = Props> {
-  (props: TProps): Child | Children;
+  (props: TProps): Children;
 }
 export interface Component<TProps = Props> {
-  (props: TProps): Child | Children;
+  (props: TProps): Children;
   tag?: symbol;
 }
 export interface ComponentCreator<TProps = Props> {
   component: Component<TProps>;
-  (): Child | Children;
+  (): Children;
   props: Props;
   tag?: symbol;
 }
@@ -212,6 +287,51 @@ export function isComponentCreator(item: unknown): item is ComponentCreator {
   return typeof item === "function" && (item as any).component;
 }
 
+/**
+ * This namespace is predominantly for interop with React tooling in VSCode
+ * and controls the type of JSX elements, components, and the like.
+ */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace JSX {
+  export interface IntrinsicElements {
+    group: { shouldBreak?: boolean; id?: symbol; children: Children };
+    line: {};
+    br: {};
+    hardline: {};
+    hbr: {};
+    softline: {};
+    sbr: {};
+    literalline: {};
+    lbr: {};
+    indent: { children: Children };
+    fill: { children: Children };
+    breakParent: {};
+    ifBreak: { children: Children; flatContents?: Children; groupId?: symbol };
+    lineSuffix: { children: Children };
+    lineSuffixBoundary: {};
+    dedent: { children: Children };
+    align:
+      | { children: Children; width: number }
+      | { children: Children; string: string };
+    markAsRoot: { children: Children };
+    dedentToRoot: { children: Children };
+  }
+  export type ElementType = string | ComponentDefinition<any>;
+  export type Element = Children;
+  export interface ElementChildrenAttribute {
+    children: {};
+  }
+  export interface ElementAttributesProperty {
+    props: {};
+  }
+}
+
+export function jsx(type: Component<any>, props: Record<string, unknown>) {
+  return createComponent(type, props);
+}
+
+export const jsxs = jsx;
+
 export function createComponent<TProps extends Props = Props>(
   C: Component<TProps>,
   props: TProps,
@@ -234,6 +354,73 @@ export function taggedComponent<TProps = Props>(
   return component;
 }
 
+export const intrinsicElementKey = Symbol();
+
+export type IndentIntrinsicElement = IntrinsicElementBase<"indent">;
+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
+  | BrIntrinsicElement
+  | LineIntrinsicElement
+  | HbrIntrinsicElement
+  | HardlineIntrinsicElement
+  | SbrIntrinsicElement
+  | SoftlineIntrinsicElement
+  | GroupIntrinsicElement
+  | AlignIntrinsicElement
+  | FillIntrinsicElement
+  | BreakParentIntrinsicElement
+  | LineSuffixIntrinsicElement
+  | LineSuffixBoundaryIntrinsicElement
+  | DedentIntrinsicElement
+  | LiterallineIntrinsicElement
+  | LbrIntrinsicElement
+  | DedentToRootIntrinsicElement
+  | MarkAsRootIntrinsicElement
+  | IfBreakIntrinsicElement;
+
+export interface IntrinsicElementBase<
+  TKey extends keyof JSX.IntrinsicElements = keyof JSX.IntrinsicElements,
+> {
+  [intrinsicElementKey]: true;
+  name: TKey;
+  props: JSX.IntrinsicElements[TKey];
+}
+export function createIntrinsic<TKey extends keyof JSX.IntrinsicElements>(
+  name: TKey,
+  props: JSX.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 function mergeProps<T, U>(source: T, source1: U): T & U;
 export function mergeProps<T, U, V>(
   source: T,
@@ -272,6 +459,61 @@ export function mergeProps(...sources: any): any {
   return target;
 }
 
+export type SplitProps<T, K extends (readonly (keyof T)[])[]> = [
+  ...{
+    [P in keyof K]: P extends `${number}` ?
+      Pick<T, Extract<K[P], readonly (keyof T)[]>[number]>
+    : never;
+  },
+  { [P in keyof T as Exclude<P, K[number][number]>]: T[P] },
+];
+
+export function splitProps<
+  T extends Record<any, any>,
+  K extends [readonly (keyof T)[], ...(readonly (keyof T)[])[]],
+>(props: T, ...keys: K): SplitProps<T, K> {
+  if (isReactive(props)) {
+    const refs = untrack(() => toRefs(props));
+    const remainingKeys = new Set(Object.keys(refs));
+
+    const result: any = keys.map((keySet) => {
+      const resultSet: any = {};
+      for (const key of keySet) {
+        resultSet[key] = refs[key];
+        remainingKeys.delete(key as string);
+      }
+      return proxyRefs(resultSet);
+    });
+
+    const remaining: any = {};
+    for (const key of remainingKeys) {
+      remaining[key] = refs[key];
+    }
+
+    return [...result, proxyRefs(remaining)] as any;
+  }
+
+  const descriptors = Object.getOwnPropertyDescriptors(props);
+  const remainingKeys = new Set(Object.keys(descriptors));
+  const result: any = keys.map((keySet) => {
+    const resultSet: any = {};
+    for (const key of keySet) {
+      if (key in descriptors) {
+        Object.defineProperty(resultSet, key, descriptors[key]);
+        remainingKeys.delete(key as string);
+      }
+    }
+    return resultSet;
+  });
+
+  const remaining: any = {};
+  for (const key of remainingKeys) {
+    Object.defineProperty(remaining, key, descriptors[key]);
+  }
+
+  return [...result, remaining] as any;
+}
+
 function shouldDebug() {
   return typeof process !== "undefined" && !!process.env?.ALLOY_DEBUG;
 }