@jay-framework/runtime 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -44,6 +44,8 @@ interface JayEvent<EventType, ViewState> {
     coordinate: Coordinate;
 }
 type JayEventHandler<EventType, ViewState, Returns> = (event: JayEvent<EventType, ViewState>) => Returns;
+/** Event type for ViewState change notifications */
+declare const VIEW_STATE_CHANGE_EVENT = "viewStateChange";
 interface JayComponent<Props, ViewState, jayElement extends BaseJayElement<ViewState>> {
     element: jayElement;
     update: updateFunc<Props>;
@@ -51,6 +53,8 @@ interface JayComponent<Props, ViewState, jayElement extends BaseJayElement<ViewS
     unmount: MountFunc;
     addEventListener: (type: string, handler: JayEventHandler<any, ViewState, void>) => void;
     removeEventListener: (type: string, handler: JayEventHandler<any, ViewState, void>) => void;
+    /** Current ViewState (read-only, available when using @jay-framework/component) */
+    readonly viewState?: ViewState;
 }
 type PropsFrom<Type> = Type extends JayComponent<infer Props, any, any> ? Props : null;
 type ViewStateFrom<Type> = Type extends JayComponent<any, infer ViewState, any> ? ViewState : null;
@@ -467,6 +471,25 @@ declare function isForEach<ViewState, Item>(c: Conditional<ViewState> | When<Vie
 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>;
+/**
+ * Runtime support for pre-rendered slow arrays (slowForEach in jay-html).
+ *
+ * This function is used when a forEach loop has been pre-rendered at slow phase.
+ * The array items are statically embedded in the jay-html, but we still need to:
+ * 1. Set up the correct data context for each item (so bindings work)
+ * 2. Enable fast/interactive updates within each item
+ * 3. Support event handling with the correct item coordinates
+ *
+ * The key insight is that slowForEachItem switches the data context to the
+ * specific array item, so child bindings like {price} work correctly
+ * (they resolve to item.price, not viewState.price).
+ *
+ * @param arrayName - The property name of the array in the parent ViewState
+ * @param index - The jayIndex value (position in the pre-rendered array)
+ * @param trackByValue - The jayTrackBy value (identity for reconciliation)
+ * @param elementCreator - Function that creates the pre-rendered element (called within item context)
+ */
+declare function slowForEachItem<ParentVS, ItemVS>(arrayName: keyof ParentVS, index: number, trackByValue: string, elementCreator: () => BaseJayElement<ItemVS>): BaseJayElement<ParentVS>;
 interface ForEach<ViewState, Item> {
     getItems: (T: any) => Array<Item>;
     elemCreator: (Item: any, String: any) => BaseJayElement<Item>;
@@ -502,6 +525,35 @@ interface ContextStack<ContextType> {
     marker: ContextMarker<ContextType>;
     parent?: ContextStack<any>;
 }
+/**
+ * Registers a global context that will be available to all components.
+ * Global contexts are checked after the context stack, so component-provided
+ * contexts can override global ones.
+ *
+ * @param marker - The context marker created with createJayContext()
+ * @param context - The context value to register
+ *
+ * @example
+ * ```typescript
+ * // In lib/init.ts (using makeJayInit pattern)
+ * export const init = makeJayInit()
+ *   .withServer(() => ({ itemsPerPage: 10 }))
+ *   .withClient((serverData) => {
+ *     registerGlobalContext(APP_CONFIG_CONTEXT, serverData);
+ *   });
+ * ```
+ */
+declare function registerGlobalContext<ContextType>(marker: ContextMarker<ContextType>, context: ContextType): void;
+/**
+ * Clears all registered global contexts.
+ * Internal API for testing and hot reload.
+ */
+declare function clearGlobalContextRegistry(): void;
+/**
+ * Gets a global context by marker.
+ * Internal API used by findContext.
+ */
+declare function useGlobalContext<ContextType>(marker: ContextMarker<ContextType>): ContextType | undefined;
 declare function createJayContext<ContextType = unknown>(): ContextMarker<ContextType>;
 declare function withContext<ContextType, Returns>(marker: ContextMarker<ContextType>, context: ContextType, callback: () => Returns): Returns;
 declare function useContext<ContextType>(marker: ContextMarker<ContextType>): ContextType;
@@ -521,4 +573,4 @@ declare class ConstructContext<ViewState> {
     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 ExtractFastViewState, type ExtractInteractiveViewState, type ExtractRefs, type ExtractSlowViewState, 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 };
+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 ExtractFastViewState, type ExtractInteractiveViewState, type ExtractRefs, type ExtractSlowViewState, 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, VIEW_STATE_CHANGE_EVENT, type ViewStateFrom, type When, WhenRole, type WithData, booleanAttribute, childComp, clearGlobalContextRegistry, 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, registerGlobalContext, rejected, resolved, restoreContext, saveContext, slowForEachItem, svgDynamicElement, svgElement, type updateFunc, useContext, useGlobalContext, withContext, withData };

package/dist/index.js

@@ -84,6 +84,7 @@ const noop = () => {
 };
 const noopUpdate = noop;
 const noopMount = noop;
+const VIEW_STATE_CHANGE_EVENT = "viewStateChange";
 var LogType = /* @__PURE__ */ ((LogType2) => {
   LogType2[LogType2["ASYNC_ERROR"] = 0] = "ASYNC_ERROR";
   LogType2[LogType2["CONTEXT_NOT_FOUND"] = 1] = "CONTEXT_NOT_FOUND";
@@ -97,6 +98,16 @@ let currentContext = void 0;
 function NewContextStack(context, marker, parent) {
   return { context, marker, parent };
 }
+const globalContextRegistry = /* @__PURE__ */ new Map();
+function registerGlobalContext(marker, context) {
+  globalContextRegistry.set(marker, context);
+}
+function clearGlobalContextRegistry() {
+  globalContextRegistry.clear();
+}
+function useGlobalContext(marker) {
+  return globalContextRegistry.get(marker);
+}
 function createJayContext() {
   return Symbol();
 }
@@ -122,6 +133,11 @@ function findContext(predicate) {
       return aContext.context;
     aContext = aContext.parent;
   }
+  for (const [marker, context] of globalContextRegistry.entries()) {
+    if (predicate(marker)) {
+      return context;
+    }
+  }
   return void 0;
 }
 function saveContext() {
@@ -352,6 +368,33 @@ function mkWhenPendingCondition(when2, group) {
 function forEach(getItems, elemCreator, matchBy) {
   return { getItems, elemCreator, trackBy: matchBy };
 }
+function slowForEachItem(arrayName, index, trackByValue, elementCreator) {
+  const parentContext = currentConstructionContext();
+  const savedContext = saveContext();
+  const parentData = parentContext.currData;
+  const array = parentData[arrayName];
+  const initialItem = array?.[index];
+  const childContext = parentContext.forItem(initialItem, trackByValue);
+  const element2 = withContext(CONSTRUCTION_CONTEXT_MARKER, childContext, elementCreator);
+  const originalUpdate = element2.update;
+  const update = (newParentData) => {
+    const newArray = newParentData[arrayName];
+    const newItem = newArray?.[index];
+    const updateChildContext = parentContext.forItem(newItem, trackByValue);
+    restoreContext(
+      savedContext,
+      () => withContext(CONSTRUCTION_CONTEXT_MARKER, updateChildContext, () => {
+        originalUpdate(newItem);
+      })
+    );
+  };
+  return {
+    dom: element2.dom,
+    update,
+    mount: element2.mount,
+    unmount: element2.unmount
+  };
+}
 function withData(accessor, elem) {
   return { accessor, elem };
 }
@@ -980,9 +1023,11 @@ export {
   ManagedRefType,
   PrivateRefs,
   ReferencesManager,
+  VIEW_STATE_CHANGE_EVENT,
   WhenRole,
   booleanAttribute,
   childComp,
+  clearGlobalContextRegistry,
   conditional,
   createJayContext,
   currentConstructionContext,
@@ -1010,13 +1055,16 @@ export {
   normalizeMount,
   normalizeUpdates,
   pending,
+  registerGlobalContext,
   rejected,
   resolved,
   restoreContext,
   saveContext,
+  slowForEachItem,
   svgDynamicElement,
   svgElement,
   useContext,
+  useGlobalContext,
   withContext,
   withData
 };

package/package.json

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

package/readme.md

@@ -105,7 +105,57 @@ interface JayElement<ViewState, Refs> extends BaseJayElement<ViewState> {
   These references can be used to set event listeners, interact with child elements or component APIs.
   Read more about `refs` in [refs.md](./docs/refs.md).
 
-## implementation details
+## Slow Rendering Support
+
+The runtime supports pre-rendered "slow" arrays via the `slowForEachItem` function. This is used when a `forEach` loop has been pre-rendered at build time (slow phase), but still needs fast/interactive updates at runtime.
+
+### slowForEachItem
+
+```typescript
+function slowForEachItem<ParentVS, ItemVS>(
+  arrayName: keyof ParentVS,
+  index: number,
+  trackByValue: string,
+  elementCreator: () => BaseJayElement<ItemVS>,
+): BaseJayElement<ParentVS>;
+```
+
+**Parameters:**
+
+- `arrayName` - The property name of the array in the parent ViewState
+- `index` - The position in the pre-rendered array (jayIndex)
+- `trackByValue` - The track-by value for client reconciliation (jayTrackBy)
+- `elementCreator` - Function that creates the element (called within item context)
+
+**How it works:**
+
+1. Sets the data context to `viewState[arrayName][index]`
+2. Calls `elementCreator()` within that context so bindings are item-scoped
+3. On update, retrieves the item from the new ViewState and updates with item context
+
+**Example generated code:**
+
+```typescript
+slowForEachItem('products', 0, 'p1', () =>
+  e('li', {}, [
+    e('span', { class: 'name' }, ['Widget A']), // static (pre-rendered)
+    e('span', { class: 'price' }, [
+      dt((vs) => vs.price), // dynamic (fast phase) - item-scoped
+    ]),
+  ]),
+);
+```
+
+This corresponds to pre-rendered jay-html:
+
+```html
+<li slowForEach="products" trackBy="id" jayIndex="0" jayTrackBy="p1">
+  <span class="name">Widget A</span>
+  <span class="price">{price}</span>
+</li>
+```
+
+## Implementation Details
 
 - See the [Generated JayElement](./docs/jay-element.md) for the details of the `jay-html` generated target.
 - See the [Generated JayElement creation Functions](./docs/runtime.md) for the details of the jay element creation functions used by the `jay-html` generated target.