@jay-framework/runtime 0.6.10 → 0.8.0

package/dist/index.d.ts

@@ -26,6 +26,7 @@ interface updateFunc<T> {
     _origUpdates?: Array<updateFunc<T>>;
 }
 type MountFunc = () => void;
+declare const noop: () => void;
 declare const noopUpdate: updateFunc<any>;
 declare const noopMount: MountFunc;
 interface BaseJayElement<ViewState> {
@@ -72,6 +73,15 @@ type JayContract<ViewState extends object, Refs extends object> = {
 };
 type ExtractViewState<A> = A extends JayContract<infer ViewState, any> ? ViewState : never;
 type ExtractRefs<A> = A extends JayContract<any, infer Refs> ? Refs : never;
+declare enum LogType {
+    ASYNC_ERROR = 0,
+    CONTEXT_NOT_FOUND = 1
+}
+type JayLog = {
+    log: (type: LogType) => void;
+    error: (type: LogType, error: Error) => void;
+};
+declare const jayLog: JayLog;
 
 declare module '@jay-framework/runtime' {
     interface BaseJayElement<ViewState> {
@@ -433,21 +443,41 @@ interface Conditional<ViewState> {
     condition: (newData: ViewState) => boolean;
     elem: () => BaseJayElement<ViewState> | TextElement<ViewState>;
 }
-declare function isCondition<ViewState>(c: Conditional<ViewState> | ForEach<ViewState, any> | TextElement<ViewState> | BaseJayElement<ViewState>): c is Conditional<ViewState>;
-declare function isForEach<ViewState, Item>(c: Conditional<ViewState> | ForEach<ViewState, Item> | TextElement<ViewState> | BaseJayElement<ViewState>): c is ForEach<ViewState, Item>;
+declare enum WhenRole {
+    pending = 0,
+    resolved = 1,
+    rejected = 2
+}
+interface When<ViewState, ResolvedViewValue> {
+    role: WhenRole;
+    promise: (newData: ViewState) => Promise<ResolvedViewValue>;
+    elem: () => BaseJayElement<ResolvedViewValue> | TextElement<ResolvedViewValue> | string;
+}
+declare const resolved: <ViewState, ResolvedViewValue>(promise: (newData: ViewState) => Promise<ResolvedViewValue>, elem: () => string | BaseJayElement<ResolvedViewValue> | TextElement<ResolvedViewValue>) => When<ViewState, ResolvedViewValue>;
+declare const rejected: <ViewState>(promise: (newData: ViewState) => Promise<any>, elem: () => BaseJayElement<Error> | TextElement<Error> | string) => When<ViewState, any>;
+declare const pending: <ViewState>(promise: (newData: ViewState) => Promise<any>, elem: () => BaseJayElement<never> | TextElement<never> | string) => When<ViewState, any>;
+declare function isCondition<ViewState>(c: Conditional<ViewState> | When<ViewState, any> | ForEach<ViewState, any> | WithData<ViewState, any> | TextElement<ViewState> | BaseJayElement<ViewState>): c is Conditional<ViewState>;
+declare function isForEach<ViewState, Item>(c: Conditional<ViewState> | When<ViewState, any> | ForEach<ViewState, Item> | WithData<ViewState, any> | TextElement<ViewState> | BaseJayElement<ViewState>): c is ForEach<ViewState, Item>;
+declare function isWhen<ViewState, Item>(c: Conditional<ViewState> | When<ViewState, any> | ForEach<ViewState, Item> | WithData<ViewState, any> | TextElement<ViewState> | BaseJayElement<ViewState>): c is When<ViewState, any>;
+declare function isWithData<ViewState, ChildViewState>(c: Conditional<ViewState> | When<ViewState, any> | ForEach<ViewState, any> | WithData<ViewState, ChildViewState> | TextElement<ViewState> | BaseJayElement<ViewState>): c is WithData<ViewState, ChildViewState>;
 declare function forEach<T, Item>(getItems: (T: any) => Array<Item>, elemCreator: (Item: any) => BaseJayElement<Item>, matchBy: string): ForEach<T, Item>;
 interface ForEach<ViewState, Item> {
     getItems: (T: any) => Array<Item>;
     elemCreator: (Item: any, String: any) => BaseJayElement<Item>;
     trackBy: string;
 }
+declare function withData<ParentViewState, ChildViewState>(accessor: (data: ParentViewState) => ChildViewState | null | undefined, elem: () => BaseJayElement<ChildViewState>): WithData<ParentViewState, ChildViewState>;
+interface WithData<ParentViewState, ChildViewState> {
+    accessor: (data: ParentViewState) => ChildViewState | null | undefined;
+    elem: () => BaseJayElement<ChildViewState>;
+}
 declare function mkUpdateCollection<ViewState, Item>(child: ForEach<ViewState, Item>, group: KindergartenGroup): [updateFunc<ViewState>, MountFunc, MountFunc];
 declare function dynamicText<ViewState>(textContent: (vs: ViewState) => string | number | boolean): TextElement<ViewState>;
 type ElementChildren<ViewState> = Array<BaseJayElement<ViewState> | TextElement<ViewState> | string>;
 declare const element: <ViewState>(tagName: string, attributes: Attributes<ViewState>, children?: ElementChildren<ViewState>, ref?: PrivateRef<ViewState, BaseJayElement<ViewState>>) => BaseJayElement<ViewState>;
 declare const svgElement: <ViewState>(tagName: string, attributes: Attributes<ViewState>, children?: ElementChildren<ViewState>, ref?: PrivateRef<ViewState, BaseJayElement<ViewState>>) => BaseJayElement<ViewState>;
 declare const mathMLElement: <ViewState>(tagName: string, attributes: Attributes<ViewState>, children?: ElementChildren<ViewState>, ref?: PrivateRef<ViewState, BaseJayElement<ViewState>>) => BaseJayElement<ViewState>;
-type DynamicElementChildren<ViewState> = Array<Conditional<ViewState> | ForEach<ViewState, any> | TextElement<ViewState> | BaseJayElement<ViewState> | string>;
+type DynamicElementChildren<ViewState> = Array<Conditional<ViewState> | ForEach<ViewState, any> | WithData<ViewState, any> | TextElement<ViewState> | BaseJayElement<ViewState> | When<ViewState, any> | string>;
 declare const dynamicElementNS: (ns: string) => <ViewState>(tagName: string, attributes: Attributes<ViewState>, children?: DynamicElementChildren<ViewState>, ref?: PrivateRef<ViewState, BaseJayElement<ViewState>>) => BaseJayElement<ViewState>;
 declare const dynamicElement: <ViewState>(tagName: string, attributes: Attributes<ViewState>, children?: DynamicElementChildren<ViewState>, ref?: PrivateRef<ViewState, BaseJayElement<ViewState>>) => BaseJayElement<ViewState>;
 declare const svgDynamicElement: <ViewState>(tagName: string, attributes: Attributes<ViewState>, children?: DynamicElementChildren<ViewState>, ref?: PrivateRef<ViewState, BaseJayElement<ViewState>>) => BaseJayElement<ViewState>;
@@ -481,7 +511,8 @@ declare class ConstructContext<ViewState> {
     get currData(): ViewState;
     coordinate: (refName: string) => Coordinate;
     forItem<ChildViewState>(childViewState: ChildViewState, id: string): ConstructContext<ChildViewState>;
+    forAsync<ChildViewState>(childViewState: ChildViewState): ConstructContext<ChildViewState>;
     static withRootContext<ViewState, Refs>(viewState: ViewState, refManager: ReferencesManager, elementConstructor: () => BaseJayElement<ViewState>): JayElement<ViewState, Refs>;
 }
 
-export { type Attribute, type Attributes, type BaseJayElement, BaseReferencesManager, type ComponentCollectionProxy, ComponentCollectionRefImpl, type ComponentProxy, ComponentRefImpl, ComponentRefsImpl, type Conditional, ConstructContext, type ContextMarker, type Coordinate, type DynamicAttributeOrProperty, EVENT_TRAP, type ElementFrom, type EventEmitter, type EventTypeFrom, type ExtractRefs, type ExtractViewState, type ForEach, GetTrapProxy, type GlobalJayEvents, type HTMLElementCollectionProxy, type HTMLElementCollectionProxyTarget, type HTMLElementProxy, type HTMLElementProxyTarget, type HTMLNativeExec, type HeadLink, type JayComponent, type JayComponentConstructor, type JayContract, type JayElement, type JayEvent, type JayEventHandler, type JayEventHandlerWrapper, type JayNativeEventBuilder, type JayNativeFunction, type ManagedRefConstructor, ManagedRefType, type ManagedRefs, type MapEventEmitterViewState, type MountFunc, type OnlyEventEmitters, type PreRenderElement, type PrivateRef, type PrivateRefConstructor, PrivateRefs, type PropsFrom, ReferencesManager, type RenderElement, type RenderElementOptions, type TextElement, type ViewStateFrom, booleanAttribute, childComp, conditional, createJayContext, currentConstructionContext, defaultEventWrapper, dynamicAttribute, dynamicElement, dynamicElementNS, dynamicProperty, dynamicText, element, findContext, forEach, injectHeadLinks, isCondition, isForEach, mathMLDynamicElement, mathMLElement, mkUpdateCollection, noopMount, noopUpdate, normalizeMount, normalizeUpdates, restoreContext, saveContext, svgDynamicElement, svgElement, type updateFunc, useContext, withContext };
+export { type Attribute, type Attributes, type BaseJayElement, BaseReferencesManager, type ComponentCollectionProxy, ComponentCollectionRefImpl, type ComponentProxy, ComponentRefImpl, ComponentRefsImpl, type Conditional, ConstructContext, type ContextMarker, type Coordinate, type DynamicAttributeOrProperty, EVENT_TRAP, type ElementFrom, type EventEmitter, type EventTypeFrom, type ExtractRefs, type ExtractViewState, type ForEach, GetTrapProxy, type GlobalJayEvents, type HTMLElementCollectionProxy, type HTMLElementCollectionProxyTarget, type HTMLElementProxy, type HTMLElementProxyTarget, type HTMLNativeExec, type HeadLink, type JayComponent, type JayComponentConstructor, type JayContract, type JayElement, type JayEvent, type JayEventHandler, type JayEventHandlerWrapper, type JayLog, type JayNativeEventBuilder, type JayNativeFunction, LogType, type ManagedRefConstructor, ManagedRefType, type ManagedRefs, type MapEventEmitterViewState, type MountFunc, type OnlyEventEmitters, type PreRenderElement, type PrivateRef, type PrivateRefConstructor, PrivateRefs, type PropsFrom, ReferencesManager, type RenderElement, type RenderElementOptions, type TextElement, type ViewStateFrom, type When, WhenRole, type WithData, booleanAttribute, childComp, conditional, createJayContext, currentConstructionContext, defaultEventWrapper, dynamicAttribute, dynamicElement, dynamicElementNS, dynamicProperty, dynamicText, element, findContext, forEach, injectHeadLinks, isCondition, isForEach, isWhen, isWithData, jayLog, mathMLDynamicElement, mathMLElement, mkUpdateCollection, noop, noopMount, noopUpdate, normalizeMount, normalizeUpdates, pending, rejected, resolved, restoreContext, saveContext, svgDynamicElement, svgElement, type updateFunc, useContext, withContext, withData };

package/dist/index.js

@@ -80,9 +80,18 @@ class Kindergarten {
     return offset;
   }
 }
-const noopUpdate = (_newData) => {
+const noop = () => {
 };
-const noopMount = () => {
+const noopUpdate = noop;
+const noopMount = noop;
+var LogType = /* @__PURE__ */ ((LogType2) => {
+  LogType2[LogType2["ASYNC_ERROR"] = 0] = "ASYNC_ERROR";
+  LogType2[LogType2["CONTEXT_NOT_FOUND"] = 1] = "CONTEXT_NOT_FOUND";
+  return LogType2;
+})(LogType || {});
+const jayLog = {
+  log: noop,
+  error: noop
 };
 let currentContext = void 0;
 function NewContextStack(context, marker, parent) {
@@ -157,6 +166,9 @@ class ConstructContext {
   forItem(childViewState, id) {
     return new ConstructContext(childViewState, false, [...this.coordinateBase, id]);
   }
+  forAsync(childViewState) {
+    return new ConstructContext(childViewState, false, [...this.coordinateBase]);
+  }
   static withRootContext(viewState, refManager, elementConstructor) {
     let context = new ConstructContext(viewState);
     let element2 = withContext(
@@ -239,15 +251,110 @@ function conditional(condition, elem) {
     }
   };
 }
+var WhenRole = /* @__PURE__ */ ((WhenRole2) => {
+  WhenRole2[WhenRole2["pending"] = 0] = "pending";
+  WhenRole2[WhenRole2["resolved"] = 1] = "resolved";
+  WhenRole2[WhenRole2["rejected"] = 2] = "rejected";
+  return WhenRole2;
+})(WhenRole || {});
+function when(status, promise, elem) {
+  return {
+    role: status,
+    promise,
+    elem
+  };
+}
+const resolved = (promise, elem) => when(1, promise, elem);
+const rejected = (promise, elem) => when(2, promise, elem);
+const pending = (promise, elem) => when(0, promise, elem);
 function isCondition(c) {
   return c.condition !== void 0;
 }
 function isForEach(c) {
   return c.elemCreator !== void 0;
 }
+function isWhen(c) {
+  return c.promise !== void 0;
+}
+function isWithData(c) {
+  return c.accessor !== void 0;
+}
+function mkWhenCondition(when2, group) {
+  switch (when2.role) {
+    case 1:
+      return mkWhenResolvedCondition(when2, group);
+    case 2:
+      return mkWhenRejectedCondition(when2, group);
+    default:
+      return mkWhenPendingCondition(when2, group);
+  }
+}
+const Hide = Symbol();
+function mkWhenConditionBase(when2, group, setupPromise) {
+  let show = false;
+  let savedValue = void 0;
+  const parentContext = currentConstructionContext();
+  const savedContext = saveContext();
+  const [cUpdate, cMouth, cUnmount] = mkUpdateCondition(
+    conditional(
+      () => show,
+      () => {
+        let childContext = parentContext.forAsync(savedValue);
+        return restoreContext(savedContext, () => {
+          return withContext(CONSTRUCTION_CONTEXT_MARKER, childContext, () => {
+            return when2.elem();
+          });
+        });
+      }
+    ),
+    group
+  );
+  let currentPromise = when2.promise(parentContext.currData);
+  const handleValue = (changedPromise) => (value) => {
+    if (changedPromise === currentPromise) {
+      show = value !== Hide;
+      savedValue = value;
+      cUpdate(value);
+    }
+  };
+  setupPromise(currentPromise, handleValue(currentPromise));
+  const update = (viewState) => {
+    const newValue = when2.promise(viewState);
+    if (currentPromise !== newValue) {
+      currentPromise = newValue;
+      setupPromise(currentPromise, handleValue(currentPromise));
+      show = false;
+      restoreContext(savedContext, () => cUpdate(void 0));
+    }
+  };
+  return [update, cMouth, cUnmount];
+}
+function mkWhenResolvedCondition(when2, group) {
+  return mkWhenConditionBase(
+    when2,
+    group,
+    (promise, handleValue) => promise.then(handleValue).catch((err) => jayLog.error(LogType.ASYNC_ERROR, err))
+  );
+}
+function mkWhenRejectedCondition(when2, group) {
+  return mkWhenConditionBase(when2, group, (promise, handleValue) => promise.catch(handleValue));
+}
+function mkWhenPendingCondition(when2, group) {
+  let timeout;
+  return mkWhenConditionBase(when2, group, (promise, handleValue) => {
+    timeout = setTimeout(() => handleValue(void 0), 1);
+    promise.finally(() => {
+      clearTimeout(timeout);
+      handleValue(Hide);
+    }).catch((err) => jayLog.error(LogType.ASYNC_ERROR, err));
+  });
+}
 function forEach(getItems, elemCreator, matchBy) {
   return { getItems, elemCreator, trackBy: matchBy };
 }
+function withData(accessor, elem) {
+  return { accessor, elem };
+}
 function applyListChanges(group, instructions) {
   instructions.forEach((instruction) => {
     if (instruction.action === ITEM_ADDED) {
@@ -303,13 +410,16 @@ function mkUpdateCondition(child, group) {
   let mount = noopMount, unmount = noopMount;
   let lastResult = false;
   let childElement = void 0;
+  const savedContext = saveContext();
   const update = (newData) => {
-    if (!childElement) {
-      childElement = child.elem();
+    const result = child.condition(newData);
+    if (!childElement && result) {
+      restoreContext(savedContext, () => {
+        childElement = child.elem();
+      });
       mount = () => lastResult && childElement.mount();
       unmount = () => childElement.unmount();
     }
-    let result = child.condition(newData);
     if (result) {
       if (!lastResult) {
         group.ensureNode(childElement.dom);
@@ -324,6 +434,46 @@ function mkUpdateCondition(child, group) {
   };
   return [update, mount, unmount];
 }
+function mkUpdateWithData(child, group) {
+  let mount = noopMount, unmount = noopMount;
+  let lastResult = false;
+  let childElement = void 0;
+  const parentContext = currentConstructionContext();
+  const savedContext = saveContext();
+  const update = (newData) => {
+    const childData = child.accessor(newData);
+    const result = childData != null;
+    if (!childElement && result) {
+      const childContext = parentContext.forAsync(childData);
+      childElement = restoreContext(
+        savedContext,
+        () => withContext(CONSTRUCTION_CONTEXT_MARKER, childContext, () => child.elem())
+      );
+      mount = () => lastResult && childElement.mount();
+      unmount = () => childElement.unmount();
+    }
+    if (result) {
+      if (!lastResult) {
+        group.ensureNode(childElement.dom);
+        childElement.mount();
+      }
+      const childContext = parentContext.forAsync(childData);
+      restoreContext(
+        savedContext,
+        () => withContext(
+          CONSTRUCTION_CONTEXT_MARKER,
+          childContext,
+          () => childElement.update(childData)
+        )
+      );
+    } else if (lastResult) {
+      childElement.unmount();
+      group.removeNode(childElement.dom);
+    }
+    lastResult = result;
+  };
+  return [update, mount, unmount];
+}
 function text(content) {
   return {
     dom: document.createTextNode(content),
@@ -386,6 +536,10 @@ const dynamicElementNS = (ns) => (tagName, attributes, children = [], ref) => {
       [update, mount, unmount] = mkUpdateCondition(child, group);
     } else if (isForEach(child)) {
       [update, mount, unmount] = mkUpdateCollection(child, group);
+    } else if (isWithData(child)) {
+      [update, mount, unmount] = mkUpdateWithData(child, group);
+    } else if (isWhen(child)) {
+      [update, mount, unmount] = mkWhenCondition(child, group);
     } else {
       group.ensureNode(child.dom);
       if (child.update !== noopUpdate)
@@ -822,9 +976,11 @@ export {
   ConstructContext,
   EVENT_TRAP,
   GetTrapProxy,
+  LogType,
   ManagedRefType,
   PrivateRefs,
   ReferencesManager,
+  WhenRole,
   booleanAttribute,
   childComp,
   conditional,
@@ -842,17 +998,25 @@ export {
   injectHeadLinks,
   isCondition,
   isForEach,
+  isWhen,
+  isWithData,
+  jayLog,
   mathMLDynamicElement,
   mathMLElement,
   mkUpdateCollection,
+  noop,
   noopMount,
   noopUpdate,
   normalizeMount,
   normalizeUpdates,
+  pending,
+  rejected,
+  resolved,
   restoreContext,
   saveContext,
   svgDynamicElement,
   svgElement,
   useContext,
-  withContext
+  withContext,
+  withData
 };

package/docs/runtime.md

@@ -319,23 +319,271 @@ at which
 
 ## forEach
 
+The `forEach` function creates a dynamic collection of child elements that automatically updates when the underlying array data changes. It efficiently manages adding, removing, and reordering child elements based on a tracking key.
+
+`forEach` is used within a `dynamicElement` to render lists of items, where each item in the array becomes a separate child element. The runtime intelligently tracks elements by a specified key property to minimize DOM manipulations during updates.
+
 ```typescript
 declare function forEach<ViewState, Item>(
-  getItems: (T: any) => Array<Item>,
-  elemCreator: (Item: any) => JayElement<Item>,
-  matchBy: string,
+  getItems: (vs: ViewState) => Array<Item>,
+  elemCreator: (item: Item, trackByValue: string) => BaseJayElement<Item>,
+  trackBy: string,
 ): ForEach<ViewState, Item>;
 ```
 
+at which
+
+- `ViewState` - the type of the parent element's view state containing the array
+- `Item` - the type of individual items in the array
+- `getItems` - a function that extracts the array of items from the parent's view state
+- `elemCreator` - a factory function that creates a child element for each item, receives:
+  - `item` - the current item data
+  - `trackByValue` - the value of the tracking key for this item (useful for setting element IDs)
+- `trackBy` - the property name used to track elements across updates (typically an `id` or `key` field)
+
+The `trackBy` parameter is crucial for performance - it tells Jay how to identify which elements are the same across updates, enabling efficient reordering and minimizing unnecessary DOM operations.
+
+Example usage for a simple list:
+
+```typescript
+import {
+  forEach,
+  dynamicElement as de,
+  element as e,
+  dynamicText as dt,
+} from '@jay-framework/runtime';
+
+interface TodoItem {
+  id: string;
+  text: string;
+  completed: boolean;
+}
+
+interface ViewState {
+  todos: TodoItem[];
+}
+
+de('ul', { class: 'todo-list' }, [
+  forEach(
+    (vs) => vs.todos,
+    (item: TodoItem) =>
+      e('li', { id: item.id, class: item.completed ? 'completed' : '' }, [dt((item) => item.text)]),
+    'id',
+  ),
+]);
+```
+
+Example with nested structure:
+
+```typescript
+interface Message {
+  id: string;
+  author: string;
+  text: string;
+  timestamp: number;
+}
+
+interface ChatViewState {
+  messages: Message[];
+}
+
+de('div', { class: 'chat' }, [
+  forEach(
+    (vs) => vs.messages,
+    (msg: Message) =>
+      e('div', { class: 'message', id: msg.id }, [
+        e('div', { class: 'author' }, [dt((m) => m.author)]),
+        e('div', { class: 'text' }, [dt((m) => m.text)]),
+        e('div', { class: 'time' }, [dt((m) => new Date(m.timestamp).toLocaleTimeString())]),
+      ]),
+    'id',
+  ),
+]);
+```
+
+**Key Features**:
+
+- **Efficient Updates**: Only modifies DOM elements that actually changed
+- **Smart Reordering**: Moves existing elements rather than recreating them when order changes
+- **Memory Management**: Properly unmounts removed elements
+- **Empty Arrays**: Gracefully handles empty arrays and null/undefined values
+
+The Jay-HTML compiler automatically generates `forEach` calls when encountering `forEach` attributes in Jay-HTML files.
+
 ## conditional
 
+The `conditional` function conditionally renders a child element based on a boolean expression. When the condition is true, the element is rendered and mounted; when false, it is unmounted and removed from the DOM.
+
+`conditional` is similar to an `if` statement in programming - it determines whether a piece of UI should be visible based on the current view state. The child element is lazily created only when the condition first becomes true.
+
 ```typescript
 declare function conditional<ViewState>(
-  condition: (newData: ViewState) => boolean,
-  elem: JayElement<ViewState> | TextElement<ViewState> | string,
+  condition: (vs: ViewState) => boolean,
+  elem: () => BaseJayElement<ViewState> | TextElement<ViewState>,
 ): Conditional<ViewState>;
 ```
 
+at which
+
+- `ViewState` - the type of the element's view state
+- `condition` - a function that evaluates to true (render element) or false (hide element)
+- `elem` - a factory function that creates the conditional element (called only when condition is first true)
+
+Example usage for showing/hiding UI elements:
+
+```typescript
+import {
+  conditional,
+  dynamicElement as de,
+  element as e,
+  dynamicText as dt,
+} from '@jay-framework/runtime';
+
+interface ViewState {
+  isLoggedIn: boolean;
+  username: string;
+  hasErrors: boolean;
+  errorMessage: string;
+}
+
+de('div', { class: 'header' }, [
+  conditional(
+    (vs) => vs.isLoggedIn,
+    () => e('div', { class: 'user-info' }, [dt((vs) => `Welcome, ${vs.username}`)]),
+  ),
+  conditional(
+    (vs) => !vs.isLoggedIn,
+    () => e('button', {}, ['Login']),
+  ),
+  conditional(
+    (vs) => vs.hasErrors,
+    () => e('div', { class: 'error' }, [dt((vs) => vs.errorMessage)]),
+  ),
+]);
+```
+
+Example with complex conditions:
+
+```typescript
+interface FormState {
+  step: number;
+  isValid: boolean;
+  isSubmitting: boolean;
+}
+
+de('div', { class: 'form' }, [
+  conditional(
+    (vs) => vs.step === 1,
+    () => e('div', { class: 'step-1' }, ['Step 1: Basic Info']),
+  ),
+  conditional(
+    (vs) => vs.step === 2,
+    () => e('div', { class: 'step-2' }, ['Step 2: Details']),
+  ),
+  conditional(
+    (vs) => vs.step === 3 && vs.isValid,
+    () => e('div', { class: 'step-3' }, ['Step 3: Review']),
+  ),
+  conditional(
+    (vs) => vs.isSubmitting,
+    () => e('div', { class: 'spinner' }, ['Loading...']),
+  ),
+]);
+```
+
+**Key Features**:
+
+- **Lazy Creation**: The element is only created when the condition first becomes true
+- **Efficient Toggling**: Mounting/unmounting is efficient when toggling visibility
+- **Clean DOM**: When false, the element is completely removed from the DOM (not just hidden)
+- **Lifecycle Management**: Properly calls mount/unmount hooks when condition changes
+
+**Note**: Complex boolean expressions with `&&` or `||` may need to be split into nested conditionals depending on the Jay-HTML parser capabilities.
+
+The Jay-HTML compiler automatically generates `conditional` calls when encountering `if` attributes in Jay-HTML files.
+
+## withData
+
+The `withData` function enables context switching for child elements with a different data type. This is primarily used for recursive structures where a child element needs to operate on a subset or related piece of the parent's data.
+
+`withData` is similar to `conditional`, but instead of checking a boolean condition, it:
+
+1. Checks if the accessor function returns a non-null/undefined value
+2. If present, renders the child element with the accessed data as its ViewState
+3. If null/undefined, hides the child element
+
+This is essential for recursive Jay-HTML structures where a node may have optional child nodes (like a tree or linked list).
+
+```typescript
+declare function withData<ParentViewState, ChildViewState>(
+  accessor: (data: ParentViewState) => ChildViewState | null | undefined,
+  elem: () => BaseJayElement<ChildViewState>,
+): WithData<ParentViewState, ChildViewState>;
+```
+
+at which
+
+- `ParentViewState` - the type of the parent element's view state
+- `ChildViewState` - the type of the child element's view state (can be the same as parent for recursive structures)
+- `accessor` - a function that extracts child data from parent data, returns null/undefined if child should not render
+- `elem` - a factory function that creates the child element (called only when accessor returns non-null data)
+
+Example usage for a binary tree structure:
+
+```typescript
+import {
+  element as e,
+  dynamicElement as de,
+  withData,
+  dynamicText as dt,
+} from '@jay-framework/runtime';
+
+interface TreeNode {
+  value: number;
+  left: TreeNode | null;
+  right: TreeNode | null;
+}
+
+function renderTree(): BaseJayElement<TreeNode> {
+  return e('div', { class: 'tree-node' }, [
+    e('div', { class: 'value' }, [dt((vs) => vs.value)]),
+    de('div', { class: 'children' }, [
+      withData(
+        (vs) => vs.left,
+        () => renderTree(),
+      ),
+      withData(
+        (vs) => vs.right,
+        () => renderTree(),
+      ),
+    ]),
+  ]);
+}
+```
+
+Example usage for a linked list:
+
+```typescript
+interface ListNode {
+  value: string;
+  next: ListNode | null;
+}
+
+function renderList(): BaseJayElement<ListNode> {
+  return e('div', { class: 'list-item' }, [
+    e('span', {}, [dt((vs) => vs.value)]),
+    de('div', { class: 'next' }, [
+      withData(
+        (vs) => vs.next,
+        () => renderList(),
+      ),
+    ]),
+  ]);
+}
+```
+
+The generated Jay-HTML compiler automatically uses `withData` when encountering recursive regions with the `<recurse>` element and an `accessor` attribute.
+
 ## ConstructionContext
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/runtime",
-  "version": "0.6.10",
+  "version": "0.8.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -23,11 +23,11 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/list-compare": "^0.6.10",
-    "@jay-framework/reactive": "^0.6.10"
+    "@jay-framework/list-compare": "^0.8.0",
+    "@jay-framework/reactive": "^0.8.0"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.6.10",
+    "@jay-framework/dev-environment": "^0.8.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/jsdom": "^21.1.6",
     "@types/node": "^20.11.5",