@jay-framework/stack-client-runtime 0.13.0 → 0.15.0

package/dist/index.cjs

@@ -80,24 +80,56 @@ function mergeArraysByTrackBy$1(baseArray, overlayArray, trackByField, trackByMa
   });
 }
 const HEADLESS_INSTANCES = runtime.createJayContext();
-function makeSignals$1(obj) {
+function makeSignals$2(obj) {
   return Object.keys(obj).reduce((signals, key) => {
     signals[key] = component.createSignal(obj[key]);
     return signals;
   }, {});
 }
-function makeHeadlessInstanceComponent(preRender, interactiveConstructor, coordinateKey, pluginContexts = []) {
-  const wrappedConstructor = (props, refs, ...pluginResolvedContexts) => {
+function makeHeadlessInstanceComponent(preRender, componentDef, coordinateKey) {
+  const interactiveConstructor = componentDef.comp;
+  const resolvedContexts = componentDef.contexts ?? [];
+  const clientDefaults = componentDef.clientDefaults;
+  const wrappedConstructor = (signalProps, refs, ...pluginResolvedContexts) => {
     const instanceData = runtime.useContext(HEADLESS_INSTANCES);
     const resolvedKey = typeof coordinateKey === "function" ? coordinateKey(runtime.currentConstructionContext()?.dataIds ?? []) : coordinateKey;
-    const fastVS = instanceData?.viewStates?.[resolvedKey];
-    const cf = instanceData?.carryForwards?.[resolvedKey] || {};
-    const signalVS = fastVS ? makeSignals$1(fastVS) : void 0;
-    return interactiveConstructor(props, refs, signalVS, cf, ...pluginResolvedContexts);
+    const suffixKey = resolvedKey.includes("/") && resolvedKey.includes(":") ? resolvedKey.split("/").find((s) => s.includes(":")) ?? resolvedKey : resolvedKey;
+    const fastVS = instanceData?.viewStates?.[resolvedKey] ?? instanceData?.viewStates?.[suffixKey];
+    const cf = instanceData?.carryForwards?.[resolvedKey] ?? instanceData?.carryForwards?.[suffixKey];
+    let resolvedFastVS;
+    let resolvedCf;
+    if (fastVS) {
+      resolvedFastVS = fastVS;
+      resolvedCf = cf || {};
+    } else if (clientDefaults) {
+      const rawProps = signalProps.props();
+      const defaults = clientDefaults(rawProps);
+      resolvedFastVS = defaults.viewState;
+      resolvedCf = defaults.carryForward ?? {};
+    } else {
+      console.warn(
+        `[Jay] Headless instance "${resolvedKey}" has no server data and no clientDefaults. Add .withClientDefaults() to the component definition to provide fallback values.`
+      );
+      resolvedFastVS = {};
+      resolvedCf = {};
+    }
+    const signalVS = makeSignals$2(resolvedFastVS);
+    const compCore = interactiveConstructor(
+      signalProps,
+      refs,
+      signalVS,
+      resolvedCf,
+      ...pluginResolvedContexts
+    );
+    const originalRender = compCore.render;
+    compCore.render = () => {
+      return { ...resolvedFastVS, ...originalRender() };
+    };
+    return compCore;
   };
-  return component.makeJayComponent(preRender, wrappedConstructor, ...pluginContexts);
+  return component.makeJayComponent(preRender, wrappedConstructor, ...resolvedContexts);
 }
-function makeSignals(obj) {
+function makeSignals$1(obj) {
   return Object.keys(obj).reduce((signals, key) => {
     signals[key] = component.createSignal(obj[key]);
     return signals;
@@ -113,21 +145,19 @@ function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward
   if (headlessInstanceCarryForwards)
     delete fastCarryForward.__headlessInstances;
   const comp = (props, refs, ...contexts) => {
-    if (headlessInstanceViewStates || headlessInstanceCarryForwards) {
-      const componentContext = runtime.useContext(component.COMPONENT_CONTEXT);
-      const instancesData = {
-        viewStates: headlessInstanceViewStates || {},
-        carryForwards: headlessInstanceCarryForwards || {}
-      };
-      componentContext.provideContexts.push([HEADLESS_INSTANCES, instancesData]);
-    }
+    const componentContext = runtime.useContext(component.COMPONENT_CONTEXT);
+    const instancesData = {
+      viewStates: headlessInstanceViewStates || {},
+      carryForwards: headlessInstanceCarryForwards || {}
+    };
+    componentContext.provideContexts.push([HEADLESS_INSTANCES, instancesData]);
     const instances = interactiveParts.map(
       (part) => {
         const partRefs = part.key ? refs[part.key] : refs;
         let partContexts;
         if (hasFastRendering) {
           const partViewState = part.key ? defaultViewState?.[part.key] : defaultViewState;
-          const partFastViewState = partViewState ? makeSignals(partViewState) : void 0;
+          const partFastViewState = partViewState ? makeSignals$1(partViewState) : makeSignals$1({});
           const partCarryForward = part.key ? fastCarryForward?.[part.key] : fastCarryForward;
           partContexts = [
             partFastViewState,
@@ -173,6 +203,94 @@ function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward
     ...contextMarkers
   );
 }
+function makeSignals(obj) {
+  return Object.keys(obj).reduce((signals, key) => {
+    signals[key] = component.createSignal(obj[key]);
+    return signals;
+  }, {});
+}
+function hydrateCompositeJayComponent(hydratePreRender, defaultViewState, fastCarryForward, parts, trackByMap = {}, rootElement) {
+  const interactiveParts = parts.filter((part) => part.comp !== void 0);
+  const hasFastRendering = defaultViewState !== null && defaultViewState !== void 0;
+  const headlessInstanceViewStates = defaultViewState?.__headlessInstances;
+  const headlessInstanceCarryForwards = fastCarryForward?.__headlessInstances;
+  if (headlessInstanceViewStates)
+    delete defaultViewState.__headlessInstances;
+  if (headlessInstanceCarryForwards)
+    delete fastCarryForward.__headlessInstances;
+  const comp = (props, refs, ...contexts) => {
+    const componentContext = runtime.useContext(component.COMPONENT_CONTEXT);
+    const instancesData = {
+      viewStates: headlessInstanceViewStates || {},
+      carryForwards: headlessInstanceCarryForwards || {}
+    };
+    componentContext.provideContexts.push([HEADLESS_INSTANCES, instancesData]);
+    const instances = interactiveParts.map(
+      (part) => {
+        const partRefs = part.key ? refs[part.key] : refs;
+        let partContexts;
+        if (hasFastRendering) {
+          const partViewState = part.key ? defaultViewState?.[part.key] : defaultViewState;
+          const partFastViewState = partViewState ? makeSignals(partViewState) : makeSignals({});
+          const partCarryForward = part.key ? fastCarryForward?.[part.key] : fastCarryForward;
+          partContexts = [
+            partFastViewState,
+            partCarryForward,
+            ...contexts.splice(0, part.contextMarkers.length)
+          ];
+        } else {
+          partContexts = [...contexts.splice(0, part.contextMarkers.length)];
+        }
+        return [part.key, part.comp(props, partRefs, ...partContexts)];
+      }
+    );
+    return {
+      render: () => {
+        let viewState = { ...defaultViewState };
+        instances.forEach(([key, instance]) => {
+          const rendered = component.materializeViewState(instance.render());
+          if (key) {
+            viewState[key] = deepMergeViewStates$1(
+              defaultViewState[key],
+              rendered,
+              trackByMap,
+              key
+            );
+          } else {
+            viewState = deepMergeViewStates$1(
+              viewState,
+              rendered,
+              trackByMap
+            );
+          }
+        });
+        return viewState;
+      }
+    };
+  };
+  const contextMarkers = interactiveParts.reduce((cm, part) => {
+    return [...cm, ...part.contextMarkers];
+  }, []);
+  const preRender = (options) => {
+    const [refs, render] = hydratePreRender(rootElement, options);
+    let element;
+    const wrappedRender = (viewState) => {
+      if (!element) {
+        element = render(defaultViewState);
+        element.update(viewState);
+      } else {
+        element.update(viewState);
+      }
+      return element;
+    };
+    return [refs, wrappedRender];
+  };
+  return component.makeJayComponent(
+    preRender,
+    comp,
+    ...contextMarkers
+  );
+}
 const ACTION_ENDPOINT_BASE = "/_jay/actions";
 class ActionError extends Error {
   constructor(code, message) {
@@ -570,6 +688,7 @@ exports.AUTOMATION_CONTEXT = AUTOMATION_CONTEXT;
 exports.ActionError = ActionError;
 exports.HEADLESS_INSTANCES = HEADLESS_INSTANCES;
 exports.createActionCaller = createActionCaller;
+exports.hydrateCompositeJayComponent = hydrateCompositeJayComponent;
 exports.makeCompositeJayComponent = makeCompositeJayComponent;
 exports.makeHeadlessInstanceComponent = makeHeadlessInstanceComponent;
 exports.setActionCallerOptions = setActionCallerOptions;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _jay_framework_component from '@jay-framework/component';
-import { ComponentConstructor, ContextMarkers, JayComponentCore } from '@jay-framework/component';
-import { JayElement, PreRenderElement, ContextMarker } from '@jay-framework/runtime';
+import { ComponentConstructor, ContextMarkers, JayComponentCore, ConcreteJayComponent } from '@jay-framework/component';
+import { JayElement, PreRenderElement, RenderElementOptions, RenderElement, ContextMarker } from '@jay-framework/runtime';
 import { TrackByMap } from '@jay-framework/view-state-merge';
 export { AUTOMATION_CONTEXT, AutomationAPI, AutomationWrappedComponent, Coordinate, Interaction, PageState, wrapWithAutomation } from '@jay-framework/runtime-automation';
 
@@ -17,6 +17,15 @@ interface CompositePart {
 
 declare function makeCompositeJayComponent<PropsT extends object, ViewState extends object, Refs extends object, JayElementT extends JayElement<ViewState, Refs>, CompCore extends JayComponentCore<PropsT, ViewState>>(preRender: PreRenderElement<ViewState, Refs, JayElementT>, defaultViewState: ViewState, fastCarryForward: object, parts: Array<CompositePart>, trackByMap?: TrackByMap): (props: PropsT) => _jay_framework_component.ConcreteJayComponent<PropsT, ViewState, Refs, CompCore, JayElementT>;
 
+/**
+ * Hydrate variant of makeCompositeJayComponent.
+ *
+ * Instead of creating new DOM, this adopts the server-rendered DOM by using
+ * the hydrate target's function signature: (rootElement, options?) => [Refs, RenderElement].
+ * The rootElement is the SSR-rendered DOM already present in the page.
+ */
+declare function hydrateCompositeJayComponent<PropsT extends object, ViewState extends object, Refs extends object, JayElementT extends JayElement<ViewState, Refs>, CompCore extends JayComponentCore<PropsT, ViewState>>(hydratePreRender: (rootElement: Element, options?: RenderElementOptions) => [Refs, RenderElement<ViewState, Refs, JayElementT>], defaultViewState: ViewState, fastCarryForward: object, parts: Array<CompositePart>, trackByMap: TrackByMap, rootElement: Element): (props: PropsT) => _jay_framework_component.ConcreteJayComponent<PropsT, ViewState, Refs, CompCore, JayElementT>;
+
 /**
  * Client-side context and helpers for headless component instances.
  *
@@ -58,7 +67,20 @@ declare const HEADLESS_INSTANCES: ContextMarker<HeadlessInstancesData>;
  *   (accumulated trackBy values from ancestor forEach loops) and returns the key.
  * @param pluginContexts - Additional context markers from the plugin (if any)
  */
-declare function makeHeadlessInstanceComponent<PropsT extends object, ViewState extends object, Refs extends object, JayElementT extends JayElement<ViewState, Refs>, CompCore extends JayComponentCore<PropsT, ViewState>>(preRender: PreRenderElement<ViewState, Refs, JayElementT>, interactiveConstructor: ComponentConstructor<PropsT, Refs, ViewState, any, CompCore>, coordinateKey: string | ((dataIds: string[]) => string), pluginContexts?: ContextMarkers<any>): any;
+/**
+ * Component definition shape expected by makeHeadlessInstanceComponent.
+ * `clientDefaults` receives raw props (not signal-wrapped) since it's called
+ * before the component construction context is set up.
+ */
+interface HeadlessComponentDef {
+    comp: ComponentConstructor<any, any, any, any, any>;
+    contexts?: ContextMarkers<any>;
+    clientDefaults?: (props: any) => {
+        viewState: any;
+        carryForward?: any;
+    };
+}
+declare function makeHeadlessInstanceComponent<PropsT extends object, ViewState extends object, Refs extends object, JayElementT extends JayElement<ViewState, Refs>, CompCore extends JayComponentCore<PropsT, ViewState>>(preRender: PreRenderElement<ViewState, Refs, JayElementT>, componentDef: HeadlessComponentDef, coordinateKey: string | ((dataIds: string[]) => string)): (props: PropsT) => ConcreteJayComponent<PropsT, ViewState, Refs, CompCore, JayElementT>;
 
 /**
  * Client-side action caller for Jay Stack.
@@ -125,4 +147,4 @@ declare function setActionCallerOptions(options: ActionCallerOptions): void;
  */
 declare function createActionCaller<Input, Output>(actionName: string, method?: HttpMethod): (input: Input) => Promise<Output>;
 
-export { type ActionCallerOptions, ActionError, type CompositePart, HEADLESS_INSTANCES, type HeadlessInstancesData, type HttpMethod, createActionCaller, makeCompositeJayComponent, makeHeadlessInstanceComponent, setActionCallerOptions };
+export { type ActionCallerOptions, ActionError, type CompositePart, HEADLESS_INSTANCES, type HeadlessComponentDef, type HeadlessInstancesData, type HttpMethod, createActionCaller, hydrateCompositeJayComponent, makeCompositeJayComponent, makeHeadlessInstanceComponent, setActionCallerOptions };

package/dist/index.js

@@ -78,24 +78,56 @@ function mergeArraysByTrackBy$1(baseArray, overlayArray, trackByField, trackByMa
   });
 }
 const HEADLESS_INSTANCES = createJayContext();
-function makeSignals$1(obj) {
+function makeSignals$2(obj) {
   return Object.keys(obj).reduce((signals, key) => {
     signals[key] = createSignal(obj[key]);
     return signals;
   }, {});
 }
-function makeHeadlessInstanceComponent(preRender, interactiveConstructor, coordinateKey, pluginContexts = []) {
-  const wrappedConstructor = (props, refs, ...pluginResolvedContexts) => {
+function makeHeadlessInstanceComponent(preRender, componentDef, coordinateKey) {
+  const interactiveConstructor = componentDef.comp;
+  const resolvedContexts = componentDef.contexts ?? [];
+  const clientDefaults = componentDef.clientDefaults;
+  const wrappedConstructor = (signalProps, refs, ...pluginResolvedContexts) => {
     const instanceData = useContext(HEADLESS_INSTANCES);
     const resolvedKey = typeof coordinateKey === "function" ? coordinateKey(currentConstructionContext()?.dataIds ?? []) : coordinateKey;
-    const fastVS = instanceData?.viewStates?.[resolvedKey];
-    const cf = instanceData?.carryForwards?.[resolvedKey] || {};
-    const signalVS = fastVS ? makeSignals$1(fastVS) : void 0;
-    return interactiveConstructor(props, refs, signalVS, cf, ...pluginResolvedContexts);
+    const suffixKey = resolvedKey.includes("/") && resolvedKey.includes(":") ? resolvedKey.split("/").find((s) => s.includes(":")) ?? resolvedKey : resolvedKey;
+    const fastVS = instanceData?.viewStates?.[resolvedKey] ?? instanceData?.viewStates?.[suffixKey];
+    const cf = instanceData?.carryForwards?.[resolvedKey] ?? instanceData?.carryForwards?.[suffixKey];
+    let resolvedFastVS;
+    let resolvedCf;
+    if (fastVS) {
+      resolvedFastVS = fastVS;
+      resolvedCf = cf || {};
+    } else if (clientDefaults) {
+      const rawProps = signalProps.props();
+      const defaults = clientDefaults(rawProps);
+      resolvedFastVS = defaults.viewState;
+      resolvedCf = defaults.carryForward ?? {};
+    } else {
+      console.warn(
+        `[Jay] Headless instance "${resolvedKey}" has no server data and no clientDefaults. Add .withClientDefaults() to the component definition to provide fallback values.`
+      );
+      resolvedFastVS = {};
+      resolvedCf = {};
+    }
+    const signalVS = makeSignals$2(resolvedFastVS);
+    const compCore = interactiveConstructor(
+      signalProps,
+      refs,
+      signalVS,
+      resolvedCf,
+      ...pluginResolvedContexts
+    );
+    const originalRender = compCore.render;
+    compCore.render = () => {
+      return { ...resolvedFastVS, ...originalRender() };
+    };
+    return compCore;
   };
-  return makeJayComponent(preRender, wrappedConstructor, ...pluginContexts);
+  return makeJayComponent(preRender, wrappedConstructor, ...resolvedContexts);
 }
-function makeSignals(obj) {
+function makeSignals$1(obj) {
   return Object.keys(obj).reduce((signals, key) => {
     signals[key] = createSignal(obj[key]);
     return signals;
@@ -111,21 +143,19 @@ function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward
   if (headlessInstanceCarryForwards)
     delete fastCarryForward.__headlessInstances;
   const comp = (props, refs, ...contexts) => {
-    if (headlessInstanceViewStates || headlessInstanceCarryForwards) {
-      const componentContext = useContext(COMPONENT_CONTEXT);
-      const instancesData = {
-        viewStates: headlessInstanceViewStates || {},
-        carryForwards: headlessInstanceCarryForwards || {}
-      };
-      componentContext.provideContexts.push([HEADLESS_INSTANCES, instancesData]);
-    }
+    const componentContext = useContext(COMPONENT_CONTEXT);
+    const instancesData = {
+      viewStates: headlessInstanceViewStates || {},
+      carryForwards: headlessInstanceCarryForwards || {}
+    };
+    componentContext.provideContexts.push([HEADLESS_INSTANCES, instancesData]);
     const instances = interactiveParts.map(
       (part) => {
         const partRefs = part.key ? refs[part.key] : refs;
         let partContexts;
         if (hasFastRendering) {
           const partViewState = part.key ? defaultViewState?.[part.key] : defaultViewState;
-          const partFastViewState = partViewState ? makeSignals(partViewState) : void 0;
+          const partFastViewState = partViewState ? makeSignals$1(partViewState) : makeSignals$1({});
           const partCarryForward = part.key ? fastCarryForward?.[part.key] : fastCarryForward;
           partContexts = [
             partFastViewState,
@@ -171,6 +201,94 @@ function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward
     ...contextMarkers
   );
 }
+function makeSignals(obj) {
+  return Object.keys(obj).reduce((signals, key) => {
+    signals[key] = createSignal(obj[key]);
+    return signals;
+  }, {});
+}
+function hydrateCompositeJayComponent(hydratePreRender, defaultViewState, fastCarryForward, parts, trackByMap = {}, rootElement) {
+  const interactiveParts = parts.filter((part) => part.comp !== void 0);
+  const hasFastRendering = defaultViewState !== null && defaultViewState !== void 0;
+  const headlessInstanceViewStates = defaultViewState?.__headlessInstances;
+  const headlessInstanceCarryForwards = fastCarryForward?.__headlessInstances;
+  if (headlessInstanceViewStates)
+    delete defaultViewState.__headlessInstances;
+  if (headlessInstanceCarryForwards)
+    delete fastCarryForward.__headlessInstances;
+  const comp = (props, refs, ...contexts) => {
+    const componentContext = useContext(COMPONENT_CONTEXT);
+    const instancesData = {
+      viewStates: headlessInstanceViewStates || {},
+      carryForwards: headlessInstanceCarryForwards || {}
+    };
+    componentContext.provideContexts.push([HEADLESS_INSTANCES, instancesData]);
+    const instances = interactiveParts.map(
+      (part) => {
+        const partRefs = part.key ? refs[part.key] : refs;
+        let partContexts;
+        if (hasFastRendering) {
+          const partViewState = part.key ? defaultViewState?.[part.key] : defaultViewState;
+          const partFastViewState = partViewState ? makeSignals(partViewState) : makeSignals({});
+          const partCarryForward = part.key ? fastCarryForward?.[part.key] : fastCarryForward;
+          partContexts = [
+            partFastViewState,
+            partCarryForward,
+            ...contexts.splice(0, part.contextMarkers.length)
+          ];
+        } else {
+          partContexts = [...contexts.splice(0, part.contextMarkers.length)];
+        }
+        return [part.key, part.comp(props, partRefs, ...partContexts)];
+      }
+    );
+    return {
+      render: () => {
+        let viewState = { ...defaultViewState };
+        instances.forEach(([key, instance]) => {
+          const rendered = materializeViewState(instance.render());
+          if (key) {
+            viewState[key] = deepMergeViewStates$1(
+              defaultViewState[key],
+              rendered,
+              trackByMap,
+              key
+            );
+          } else {
+            viewState = deepMergeViewStates$1(
+              viewState,
+              rendered,
+              trackByMap
+            );
+          }
+        });
+        return viewState;
+      }
+    };
+  };
+  const contextMarkers = interactiveParts.reduce((cm, part) => {
+    return [...cm, ...part.contextMarkers];
+  }, []);
+  const preRender = (options) => {
+    const [refs, render] = hydratePreRender(rootElement, options);
+    let element;
+    const wrappedRender = (viewState) => {
+      if (!element) {
+        element = render(defaultViewState);
+        element.update(viewState);
+      } else {
+        element.update(viewState);
+      }
+      return element;
+    };
+    return [refs, wrappedRender];
+  };
+  return makeJayComponent(
+    preRender,
+    comp,
+    ...contextMarkers
+  );
+}
 const ACTION_ENDPOINT_BASE = "/_jay/actions";
 class ActionError extends Error {
   constructor(code, message) {
@@ -569,6 +687,7 @@ export {
   ActionError,
   HEADLESS_INSTANCES,
   createActionCaller,
+  hydrateCompositeJayComponent,
   makeCompositeJayComponent,
   makeHeadlessInstanceComponent,
   setActionCallerOptions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-client-runtime",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -27,15 +27,15 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/component": "^0.13.0",
-    "@jay-framework/fullstack-component": "^0.13.0",
-    "@jay-framework/runtime": "^0.13.0",
-    "@jay-framework/runtime-automation": "^0.13.0",
-    "@jay-framework/view-state-merge": "^0.13.0"
+    "@jay-framework/component": "^0.15.0",
+    "@jay-framework/fullstack-component": "^0.15.0",
+    "@jay-framework/runtime": "^0.15.0",
+    "@jay-framework/runtime-automation": "^0.15.0",
+    "@jay-framework/view-state-merge": "^0.15.0"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.13.0",
-    "@jay-framework/jay-cli": "^0.13.0",
+    "@jay-framework/dev-environment": "^0.15.0",
+    "@jay-framework/jay-cli": "^0.15.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",