@epoch32/visage 0.0.0-stage → 0.0.0

package/src/dom/control-flow.ts

@@ -0,0 +1,353 @@
+import { effect, getActiveScope, onCleanup, runInScope, Scope, untrack } from "../signals";
+import { type Child, insertChild, type ReactiveValue, resolveValue } from "./render";
+
+export interface ShowProps<T> {
+  when: ReactiveValue<T | false | null | undefined>;
+  fallback?: Child;
+  children: Child | ((item: () => T) => Child);
+}
+
+/**
+ * Conditionally renders JSX children when the `when` condition evaluates to truthy,
+ * with fine-grained reactive scope lifecycle management and automatic fallback rendering.
+ *
+ * @example
+ * ```tsx
+ * const loggedIn = signal(false);
+ *
+ * <Show when={loggedIn} fallback={<div>Please log in</div>}>
+ *   <Dashboard />
+ * </Show>
+ * ```
+ */
+export function Show<T>(props: ShowProps<T>): any {
+  if (typeof document === "undefined") {
+    const condition = resolveValue(props.when);
+    if (condition) {
+      return typeof props.children === "function" && props.children.length > 0
+        ? (props.children as (item: () => T) => Child)(() => resolveValue(props.when) as T)
+        : typeof props.children === "function"
+          ? (props.children as () => Child)()
+          : props.children;
+    }
+    return props.fallback ?? null;
+  }
+
+  const marker = document.createTextNode("");
+  const initialFrag = document.createDocumentFragment();
+  let currentScope: Scope | null = null;
+  let currentContent: Node[] = [];
+  let isMounted = false;
+
+  effect(() => {
+    const condition = resolveValue(props.when);
+
+    if (currentScope) {
+      currentScope.dispose();
+      currentScope = null;
+    }
+
+    // Clean up old nodes from DOM
+    for (const node of currentContent) {
+      if (node.parentNode) {
+        node.parentNode.removeChild(node);
+      }
+    }
+    currentContent = [];
+
+    const frag = document.createDocumentFragment();
+
+    if (condition) {
+      currentScope = new Scope(getActiveScope());
+      untrack(() => {
+        runInScope(currentScope, () => {
+          const childRes =
+            typeof props.children === "function" && props.children.length > 0
+              ? (props.children as (item: () => T) => Child)(() => resolveValue(props.when) as T)
+              : typeof props.children === "function"
+                ? (props.children as () => Child)()
+                : props.children;
+
+          insertChild(frag, childRes);
+        });
+      });
+    } else if (props.fallback !== undefined) {
+      currentScope = new Scope(getActiveScope());
+      untrack(() => {
+        runInScope(currentScope, () => {
+          insertChild(frag, props.fallback);
+        });
+      });
+    }
+
+    currentContent = Array.from(frag.childNodes);
+
+    if (marker.parentNode) {
+      marker.parentNode.insertBefore(frag, marker);
+    } else if (!isMounted) {
+      initialFrag.appendChild(frag);
+    }
+  });
+
+  isMounted = true;
+  initialFrag.appendChild(marker);
+
+  onCleanup(() => {
+    if (currentScope) {
+      currentScope.dispose();
+    }
+  });
+
+  return initialFrag;
+}
+
+export interface ForProps<T> {
+  each: ReactiveValue<readonly T[] | undefined | null>;
+  fallback?: Child;
+  children: (item: T, index: () => number) => Child;
+}
+
+interface ItemRecord<T> {
+  item: T;
+  scope: Scope;
+  nodes: Node[];
+  indexSignal: (val?: number) => number;
+}
+
+/**
+ * Keyed / referential list renderer with fine-grained item reconciliation.
+ *
+ * Items in the list are reused across array mutations without re-rendering existing items
+ * or tearing down their active reactive scopes.
+ *
+ * @example
+ * ```tsx
+ * const items = signal(["Apple", "Banana", "Cherry"]);
+ *
+ * <For each={items} fallback={<div>No items found</div>}>
+ *   {(item, index) => (
+ *     <li>
+ *       {index() + 1}. {item}
+ *     </li>
+ *   )}
+ * </For>
+ * ```
+ */
+export function For<T>(props: ForProps<T>): any {
+  if (typeof document === "undefined") {
+    const list = resolveValue(props.each) ?? [];
+    if (list.length === 0) {
+      return props.fallback ?? null;
+    }
+    return list.map((item, idx) => props.children(item, () => idx));
+  }
+
+  const marker = document.createTextNode("");
+  const initialFrag = document.createDocumentFragment();
+  let items: ItemRecord<T>[] = [];
+  let fallbackScope: Scope | null = null;
+  let fallbackNodes: Node[] = [];
+  let isMounted = false;
+
+  effect(() => {
+    const list = resolveValue(props.each) ?? [];
+    const parent = marker.parentNode ?? (!isMounted ? initialFrag : null);
+
+    if (list.length === 0) {
+      // Clear items
+      for (const rec of items) {
+        rec.scope.dispose();
+        for (const node of rec.nodes) {
+          if (node.parentNode) node.parentNode.removeChild(node);
+        }
+      }
+      items = [];
+
+      // Render fallback
+      if (props.fallback !== undefined && fallbackNodes.length === 0 && parent) {
+        fallbackScope = new Scope(getActiveScope());
+        untrack(() => {
+          runInScope(fallbackScope, () => {
+            const frag = document.createDocumentFragment();
+            insertChild(frag, props.fallback);
+            fallbackNodes = Array.from(frag.childNodes);
+            if (marker.parentNode) {
+              marker.parentNode.insertBefore(frag, marker);
+            } else if (!isMounted) {
+              initialFrag.appendChild(frag);
+            }
+          });
+        });
+      }
+      return;
+    }
+
+    // Clean up fallback if present
+    if (fallbackNodes.length > 0) {
+      if (fallbackScope) {
+        fallbackScope.dispose();
+        fallbackScope = null;
+      }
+      for (const node of fallbackNodes) {
+        if (node.parentNode) node.parentNode.removeChild(node);
+      }
+      fallbackNodes = [];
+    }
+
+    if (!parent) return;
+
+    const newItems: ItemRecord<T>[] = [];
+    const prevMap = new Map<T, ItemRecord<T>>();
+
+    for (const rec of items) {
+      prevMap.set(rec.item, rec);
+    }
+
+    // Fast-path: map existing or create new item scopes
+    for (let i = 0; i < list.length; i++) {
+      const item = list[i]!;
+      const existing = prevMap.get(item);
+
+      if (existing) {
+        existing.indexSignal(i);
+        newItems.push(existing);
+        prevMap.delete(item);
+      } else {
+        let indexVal = i;
+        const indexSubscribers = new Set<() => void>();
+        const indexSignal = (...args: [number?]): number => {
+          if (args.length > 0 && args[0] !== undefined && args[0] !== indexVal) {
+            indexVal = args[0];
+            for (const sub of Array.from(indexSubscribers)) sub();
+          }
+          return indexVal;
+        };
+
+        const itemScope = new Scope(getActiveScope());
+        let itemNodes: Node[] = [];
+
+        untrack(() => {
+          runInScope(itemScope, () => {
+            const frag = document.createDocumentFragment();
+            const child = props.children(item, indexSignal);
+            insertChild(frag, child);
+            itemNodes = Array.from(frag.childNodes);
+          });
+        });
+
+        newItems.push({
+          item,
+          scope: itemScope,
+          nodes: itemNodes,
+          indexSignal
+        });
+      }
+    }
+
+    // Clean up removed items
+    for (const [, removed] of prevMap) {
+      removed.scope.dispose();
+      for (const node of removed.nodes) {
+        if (node.parentNode) node.parentNode.removeChild(node);
+      }
+    }
+
+    // Reorder / insert DOM nodes
+    if (marker.parentNode) {
+      let currentMarker: Node = marker;
+      for (let i = newItems.length - 1; i >= 0; i--) {
+        const rec = newItems[i]!;
+        for (let j = rec.nodes.length - 1; j >= 0; j--) {
+          const node = rec.nodes[j]!;
+          if (node.nextSibling !== currentMarker) {
+            marker.parentNode.insertBefore(node, currentMarker);
+          }
+          currentMarker = node;
+        }
+      }
+    } else if (!isMounted) {
+      for (const rec of newItems) {
+        for (const node of rec.nodes) {
+          initialFrag.appendChild(node);
+        }
+      }
+    }
+
+    items = newItems;
+  });
+
+  isMounted = true;
+  initialFrag.appendChild(marker);
+
+  onCleanup(() => {
+    for (const rec of items) {
+      rec.scope.dispose();
+    }
+    if (fallbackScope) {
+      fallbackScope.dispose();
+    }
+  });
+
+  return initialFrag;
+}
+
+export interface PortalProps {
+  mount?: HTMLElement | null;
+  children: Child | (() => Child);
+}
+
+/**
+ * Portal renders children into a different DOM container while preserving reactive context
+ */
+export function Portal(props: PortalProps): any {
+  if (typeof document === "undefined") {
+    return null;
+  }
+
+  const marker = document.createTextNode("");
+  let currentScope: Scope | null = null;
+  let nodes: Node[] = [];
+
+  effect(() => {
+    const target = props.mount ?? (typeof document !== "undefined" ? document.body : null);
+    if (!target) return;
+
+    if (currentScope) {
+      currentScope.dispose();
+      currentScope = null;
+    }
+    for (const node of nodes) {
+      if (node.parentNode) {
+        node.parentNode.removeChild(node);
+      }
+    }
+    nodes = [];
+
+    currentScope = new Scope(getActiveScope());
+    untrack(() => {
+      runInScope(currentScope, () => {
+        const childRes =
+          typeof props.children === "function" ? (props.children as () => Child)() : props.children;
+        const frag = document.createDocumentFragment();
+        insertChild(frag, childRes);
+        nodes = Array.from(frag.childNodes);
+        target.appendChild(frag);
+      });
+    });
+  });
+
+  onCleanup(() => {
+    if (currentScope) {
+      currentScope.dispose();
+      currentScope = null;
+    }
+    for (const node of nodes) {
+      if (node.parentNode) {
+        node.parentNode.removeChild(node);
+      }
+    }
+    nodes = [];
+  });
+
+  return marker;
+}

package/src/dom/index.ts

@@ -0,0 +1,32 @@
+export {
+  type Component,
+  createResource,
+  ErrorBoundary,
+  type ErrorBoundaryProps,
+  type LazyComponent,
+  lazy,
+  type Resource,
+  type ResourceActions,
+  Suspense,
+  SuspenseContext,
+  type SuspenseContextValue,
+  type SuspenseProps
+} from "./async";
+
+export {
+  For,
+  type ForProps,
+  Portal,
+  type PortalProps,
+  Show,
+  type ShowProps
+} from "./control-flow";
+export {
+  type Child,
+  insertChild,
+  isReactive,
+  type ReactiveValue,
+  render,
+  resolveValue,
+  setAttribute
+} from "./render";

package/src/dom/lazy.ts

@@ -0,0 +1,82 @@
+import { useContext } from "../signals/context";
+import type { Child } from "./render";
+import { createResource, SuspenseContext } from "./resource";
+
+export type Component<P = any> = (props: P) => Child;
+
+export type LazyComponent<T extends Component<any>> = T & {
+  preload(): Promise<T>;
+};
+
+/**
+ * Lazy load an asynchronous component with automatic `<Suspense>` boundary coordination and preloading.
+ *
+ * Dynamically imports the component module upon first render or when `.preload()` is invoked.
+ *
+ * @example
+ * ```tsx
+ * // Dynamic code-split component
+ * const HeavyChart = lazy(() => import("./HeavyChart"));
+ *
+ * // Optional early prefetching
+ * HeavyChart.preload();
+ *
+ * // Render inside Suspense
+ * <Suspense fallback={<div>Loading chart...</div>}>
+ *   <HeavyChart data={chartData()} />
+ * </Suspense>
+ * ```
+ *
+ * @param importer - Dynamic import function returning a component or `{ default: Component }`
+ * @returns A lazy component with a `.preload()` method
+ */
+export function lazy<T extends Component<any>>(
+  importer: () => Promise<{ default: T } | T>
+): LazyComponent<T> {
+  let loadedComponent: T | null = null;
+  let loadingPromise: Promise<T> | null = null;
+
+  const preload = (): Promise<T> => {
+    if (loadedComponent) {
+      return Promise.resolve(loadedComponent);
+    }
+    if (!loadingPromise) {
+      loadingPromise = importer()
+        .then((mod) => {
+          const comp =
+            mod && typeof mod === "object" && "default" in mod
+              ? (mod as { default: T }).default
+              : (mod as T);
+          loadedComponent = comp;
+          return comp;
+        })
+        .catch((err) => {
+          loadingPromise = null;
+          throw err;
+        });
+    }
+    return loadingPromise;
+  };
+
+  const LazyWrapper = ((props: any) => {
+    if (loadedComponent) {
+      return loadedComponent(props);
+    }
+
+    const promise = preload();
+    const suspense = useContext(SuspenseContext);
+    if (suspense) {
+      suspense.registerPromise(promise);
+    }
+
+    const res = createResource(() => promise);
+    return () => {
+      const Comp = res();
+      return Comp ? Comp(props) : null;
+    };
+  }) as LazyComponent<T>;
+
+  LazyWrapper.preload = preload;
+
+  return LazyWrapper;
+}