@jay-framework/compiler-shared 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -71,6 +71,19 @@ declare const Import: {
     injectHeadLinks: ImportName;
     makeJayComponent: ImportName;
     makeHeadlessInstanceComponent: ImportName;
+    HEADLESS_INSTANCES: ImportName;
+    useContext: ImportName;
+    currentConstructionContext: ImportName;
+    adoptText: ImportName;
+    adoptElement: ImportName;
+    childCompHydrate: ImportName;
+    hydrateConditional: ImportName;
+    hydrateForEach: ImportName;
+    adoptDynamicElement: ImportName;
+    STATIC: ImportName;
+    escapeHtml: ImportName;
+    escapeAttr: ImportName;
+    ServerRenderContext: ImportName;
 };
 declare class Imports {
     private readonly imports;
@@ -98,6 +111,7 @@ declare const JAY_RUNTIME = "@jay-framework/runtime";
 declare const JAY_4_REACT = "@jay-framework/4-react";
 declare const JAY_FULLSTACK_COMPONENTS = "@jay-framework/fullstack-component";
 declare const JAY_STACK_CLIENT_RUNTIME = "@jay-framework/stack-client-runtime";
+declare const JAY_SSR_RUNTIME = "@jay-framework/ssr-runtime";
 declare const REACT = "react";
 declare const MAKE_JAY_COMPONENT = "makeJayComponent";
 declare const MAKE_JAY_TSX_COMPONENT = "makeJayTsxComponent";
@@ -287,6 +301,7 @@ declare const JAY_QUERY_PREFIX = "?jay-";
 declare const JAY_QUERY_MAIN_SANDBOX = "?jay-mainSandbox";
 declare const JAY_QUERY_WORKER_TRUSTED = "?jay-workerTrusted";
 declare const JAY_QUERY_WORKER_SANDBOX = "?jay-workerSandbox";
+declare const JAY_QUERY_HYDRATE = "?jay-hydrate";
 declare const JAY_QUERY_MAIN_SANDBOX_TS = "?jay-mainSandbox.ts";
 declare const JAY_QUERY_WORKER_TRUSTED_TS = "?jay-workerTrusted.ts";
 declare const JAY_QUERY_WORKER_SANDBOX_TS = "?jay-workerSandbox.ts";
@@ -341,6 +356,8 @@ interface ParsedJayModuleSpecifier {
     buildEnvironment?: JayBuildEnvironment;
     /** The runtime mode (sandbox modes) if present */
     runtimeMode?: RuntimeMode;
+    /** Whether this is a hydrate target (?jay-hydrate) */
+    isHydrate?: boolean;
     /** Any remaining query parameters (not jay-related) */
     otherQueryParams: string;
     /** The full query string for reconstruction */
@@ -636,4 +653,90 @@ declare function resolvePluginComponent(projectRoot: string, pluginName: string,
  */
 declare function resolvePluginManifest(projectRoot: string, pluginName: string): WithValidations<PluginManifest>;
 
-export { type ActionManifestEntry, CSS_EXTENSION, type CompilerSourceFile, type DynamicContractConfig, GenerateTarget, type GenericTypescriptSourceFile, Import, type ImportName, type ImportedRefsTree, Imports, ImportsFor, JAY_4_REACT, JAY_ACTION_DTS_EXTENSION, JAY_ACTION_EXTENSION, JAY_COMPONENT, JAY_CONTRACT_DTS_EXTENSION, JAY_CONTRACT_EXTENSION, JAY_DTS_EXTENSION, JAY_EXTENSION, JAY_FULLSTACK_COMPONENTS, JAY_QUERY_CLIENT, JAY_QUERY_MAIN_SANDBOX, JAY_QUERY_MAIN_SANDBOX_TS, JAY_QUERY_PREFIX, JAY_QUERY_SERVER, JAY_QUERY_WORKER_SANDBOX, JAY_QUERY_WORKER_SANDBOX_TS, JAY_QUERY_WORKER_TRUSTED, JAY_QUERY_WORKER_TRUSTED_TS, JAY_RUNTIME, JAY_SECURE, JAY_STACK_CLIENT_RUNTIME, JAY_TS_EXTENSION, JayArrayType, JayAtomicType, JayBoolean, JayBuildEnvironment, JayComponentApiMember, JayComponentType, JayDate, JayElementConstructorType, JayElementType, JayEnumType, type JayEnvironment, JayErrorType, JayHTMLType, type JayImportLink, type JayImportName, JayImportedType, JayNumber, JayObjectType, JayOptionalType, JayPromiseType, JayRecursiveType, JayString, type JayType, JayTypeAlias, JayTypeKind, JayUnionType, JayUnknown, type JayValidations, type JsonSchemaProperty, LOCAL_PLUGIN_PATH, MAKE_JAY_4_REACT_COMPONENT, MAKE_JAY_COMPONENT, MAKE_JAY_TSX_COMPONENT, type MainRuntimeModes, type ParsedJayModuleSpecifier, type PluginComponentResolution, type PluginInitConfig, type PluginManifest, REACT, type RecursiveRegion, type Ref, type RefsTree, RenderFragment, RuntimeMode, SourceFileFormat, TSX_EXTENSION, TS_EXTENSION, WithValidations, addBuildEnvironment, checkValidationErrors, equalJayTypes, findDynamicContract, getBasePath, getBuildEnvironment, getJayTsFileSourcePath, getMode, getModeFileExtension, getModeFromExtension, hasBuildEnvironment, hasExtension, hasJayExtension, hasJayModeExtension, hasRefs, isArrayType, isAtomicType, isComponentType, isCurrencyType, isDateWithTimezoneType, isElementConstructorType, isElementType, isEnumType, isHTMLType, isImportedType, isLocalModule, isObjectType, isOptionalType, isPromiseType, isRecursiveType, isTypeAliasType, isUnionType, jayTypeToJsonSchema, loadPluginManifest, mergeRefsTrees, mkRef, mkRefsTree, nestRefs, normalizeActionEntry, parseJayModuleSpecifier, prettify, prettifyHtml, removeComments, resolvePluginComponent, resolvePluginManifest, resolvePrimitiveType, withOriginalTrace, withoutExtension };
+/**
+ * Build-time utilities for coordinate template compilation.
+ *
+ * Coordinates may contain $placeholder segments (e.g. "0/$_id/1") that
+ * reference forEach trackBy variables. These utilities compile templates
+ * into JS string concatenation expressions — no runtime dependency.
+ */
+/**
+ * Compile a coordinate template with $placeholder syntax into a JS expression string.
+ *
+ * Static templates (no placeholders) return a quoted string literal.
+ * Dynamic templates compile to string concatenation expressions.
+ *
+ * @param template - Coordinate template, e.g. "0/$_id/1" or "product-card:0/0"
+ * @param varMappings - Maps placeholder names to JS expressions, e.g. { _id: "vs1._id" }
+ * @returns A JS expression string that evaluates to the final coordinate value
+ *
+ * @example
+ * // Static (no placeholders):
+ * compileCoordinateExpr("product-card:0/0", {})
+ * // → "'product-card:0/0'"
+ *
+ * // Dynamic (with placeholder):
+ * compileCoordinateExpr("0/$_id/1", { _id: "vs1._id" })
+ * // → "'0/' + escapeAttr(String(vs1._id)) + '/1'"
+ *
+ * // Placeholder at start:
+ * compileCoordinateExpr("$_id/product-card:0/0", { _id: "vs1._id" })
+ * // → "escapeAttr(String(vs1._id)) + '/product-card:0/0'"
+ */
+declare function compileCoordinateExpr(template: string, varMappings: Record<string, string>): string;
+/**
+ * Check if a coordinate template contains dynamic placeholders.
+ */
+declare function isStaticCoordinate(template: string): boolean;
+/**
+ * Compute the `__headlessInstances` key for a headless instance.
+ *
+ * The key format differs by context:
+ * - **Static**: `"product-card:0"` (just the coordinate suffix)
+ * - **forEach**: `"trackByValue,product-card:0"` (comma-separated, matching Array.toString())
+ * - **slowForEach**: `"p1/product-card:0"` (slash-separated, same as DOM coordinate)
+ *
+ * This function is used by both:
+ * - Server runtime (dev-server) when storing data in `__headlessInstances`
+ * - Client compiler when generating the key lookup in `makeHeadlessInstanceComponent`
+ *
+ * @param coordinateSuffix - The instance's coordinate suffix, e.g. "product-card:0"
+ * @param context - The context in which the instance appears
+ * @param prefix - For slowForEach: the jayTrackBy value (e.g. "p1").
+ *   For forEach: not used (key is computed at runtime from trackBy values).
+ * @returns For static/slowForEach: a literal key string.
+ *   For forEach: undefined (key must be computed at runtime).
+ */
+declare function computeInstanceKey(coordinateSuffix: string, context: 'static' | 'forEach' | 'slowForEach', prefix?: string): string | undefined;
+/**
+ * Compile a forEach instance key expression for generated code.
+ *
+ * For the server target, produces a JS expression that computes the key
+ * at runtime using the trackBy variable.
+ *
+ * For the client target (hydrate adopt path), the key is computed by
+ * `(dataIds) => dataIds.join(',')` — the coordinateBase already includes
+ * the suffix via `childCompHydrate`'s `forInstance` call.
+ *
+ * @param coordinateSuffix - e.g. "product-card:0"
+ * @param trackByExpr - JS expression for the trackBy value, e.g. "vs1._id"
+ * @returns A JS expression string that evaluates to the key
+ *
+ * @example
+ * compileForEachInstanceKeyExpr("product-card:0", "vs1._id")
+ * // → "String(vs1._id) + ',product-card:0'"
+ */
+declare function compileForEachInstanceKeyExpr(coordinateSuffix: string, trackByExpr: string): string;
+/**
+ * Runtime computation of a forEach instance key.
+ *
+ * Used by the dev server when storing data in `__headlessInstances`.
+ * Produces the same format as `compileForEachInstanceKeyExpr` generates
+ * at compile time: `"trackByValue,coordinateSuffix"`.
+ *
+ * @param trackByValue - The resolved trackBy value for the current item
+ * @param coordinateSuffix - e.g. "product-card:0"
+ */
+declare function computeForEachInstanceKey(trackByValue: string, coordinateSuffix: string): string;
+
+export { type ActionManifestEntry, CSS_EXTENSION, type CompilerSourceFile, type DynamicContractConfig, GenerateTarget, type GenericTypescriptSourceFile, Import, type ImportName, type ImportedRefsTree, Imports, ImportsFor, JAY_4_REACT, JAY_ACTION_DTS_EXTENSION, JAY_ACTION_EXTENSION, JAY_COMPONENT, JAY_CONTRACT_DTS_EXTENSION, JAY_CONTRACT_EXTENSION, JAY_DTS_EXTENSION, JAY_EXTENSION, JAY_FULLSTACK_COMPONENTS, JAY_QUERY_CLIENT, JAY_QUERY_HYDRATE, JAY_QUERY_MAIN_SANDBOX, JAY_QUERY_MAIN_SANDBOX_TS, JAY_QUERY_PREFIX, JAY_QUERY_SERVER, JAY_QUERY_WORKER_SANDBOX, JAY_QUERY_WORKER_SANDBOX_TS, JAY_QUERY_WORKER_TRUSTED, JAY_QUERY_WORKER_TRUSTED_TS, JAY_RUNTIME, JAY_SECURE, JAY_SSR_RUNTIME, JAY_STACK_CLIENT_RUNTIME, JAY_TS_EXTENSION, JayArrayType, JayAtomicType, JayBoolean, JayBuildEnvironment, JayComponentApiMember, JayComponentType, JayDate, JayElementConstructorType, JayElementType, JayEnumType, type JayEnvironment, JayErrorType, JayHTMLType, type JayImportLink, type JayImportName, JayImportedType, JayNumber, JayObjectType, JayOptionalType, JayPromiseType, JayRecursiveType, JayString, type JayType, JayTypeAlias, JayTypeKind, JayUnionType, JayUnknown, type JayValidations, type JsonSchemaProperty, LOCAL_PLUGIN_PATH, MAKE_JAY_4_REACT_COMPONENT, MAKE_JAY_COMPONENT, MAKE_JAY_TSX_COMPONENT, type MainRuntimeModes, type ParsedJayModuleSpecifier, type PluginComponentResolution, type PluginInitConfig, type PluginManifest, REACT, type RecursiveRegion, type Ref, type RefsTree, RenderFragment, RuntimeMode, SourceFileFormat, TSX_EXTENSION, TS_EXTENSION, WithValidations, addBuildEnvironment, checkValidationErrors, compileCoordinateExpr, compileForEachInstanceKeyExpr, computeForEachInstanceKey, computeInstanceKey, equalJayTypes, findDynamicContract, getBasePath, getBuildEnvironment, getJayTsFileSourcePath, getMode, getModeFileExtension, getModeFromExtension, hasBuildEnvironment, hasExtension, hasJayExtension, hasJayModeExtension, hasRefs, isArrayType, isAtomicType, isComponentType, isCurrencyType, isDateWithTimezoneType, isElementConstructorType, isElementType, isEnumType, isHTMLType, isImportedType, isLocalModule, isObjectType, isOptionalType, isPromiseType, isRecursiveType, isStaticCoordinate, isTypeAliasType, isUnionType, jayTypeToJsonSchema, loadPluginManifest, mergeRefsTrees, mkRef, mkRefsTree, nestRefs, normalizeActionEntry, parseJayModuleSpecifier, prettify, prettifyHtml, removeComments, resolvePluginComponent, resolvePluginManifest, resolvePrimitiveType, withOriginalTrace, withoutExtension };

package/dist/index.js

@@ -24,6 +24,7 @@ const JAY_RUNTIME = "@jay-framework/runtime";
 const JAY_4_REACT = "@jay-framework/4-react";
 const JAY_FULLSTACK_COMPONENTS = "@jay-framework/fullstack-component";
 const JAY_STACK_CLIENT_RUNTIME = "@jay-framework/stack-client-runtime";
+const JAY_SSR_RUNTIME = "@jay-framework/ssr-runtime";
 const REACT = "react";
 const MAKE_JAY_COMPONENT = "makeJayComponent";
 const MAKE_JAY_TSX_COMPONENT = "makeJayTsxComponent";
@@ -415,6 +416,84 @@ const Import = {
     "makeHeadlessInstanceComponent",
     1
     /* implementation */
+  ),
+  HEADLESS_INSTANCES: importStatementFragment(
+    JAY_STACK_CLIENT_RUNTIME,
+    "HEADLESS_INSTANCES",
+    1
+    /* implementation */
+  ),
+  useContext: importStatementFragment(
+    JAY_RUNTIME,
+    "useContext",
+    1
+    /* implementation */
+  ),
+  currentConstructionContext: importStatementFragment(
+    JAY_RUNTIME,
+    "currentConstructionContext",
+    1
+    /* implementation */
+  ),
+  adoptText: importStatementFragment(
+    JAY_RUNTIME,
+    "adoptText",
+    1
+    /* implementation */
+  ),
+  adoptElement: importStatementFragment(
+    JAY_RUNTIME,
+    "adoptElement",
+    1
+    /* implementation */
+  ),
+  childCompHydrate: importStatementFragment(
+    JAY_RUNTIME,
+    "childCompHydrate",
+    1
+    /* implementation */
+  ),
+  hydrateConditional: importStatementFragment(
+    JAY_RUNTIME,
+    "hydrateConditional",
+    1
+    /* implementation */
+  ),
+  hydrateForEach: importStatementFragment(
+    JAY_RUNTIME,
+    "hydrateForEach",
+    1
+    /* implementation */
+  ),
+  adoptDynamicElement: importStatementFragment(
+    JAY_RUNTIME,
+    "adoptDynamicElement",
+    1
+    /* implementation */
+  ),
+  STATIC: importStatementFragment(
+    JAY_RUNTIME,
+    "STATIC",
+    1
+    /* implementation */
+  ),
+  escapeHtml: importStatementFragment(
+    JAY_SSR_RUNTIME,
+    "escapeHtml",
+    1
+    /* implementation */
+  ),
+  escapeAttr: importStatementFragment(
+    JAY_SSR_RUNTIME,
+    "escapeAttr",
+    1
+    /* implementation */
+  ),
+  ServerRenderContext: importStatementFragment(
+    JAY_SSR_RUNTIME,
+    "type ServerRenderContext",
+    1
+    /* implementation */
   )
 };
 class Imports {
@@ -710,7 +789,9 @@ function equalJayTypes(a, b) {
   else if (a instanceof JayObjectType && b instanceof JayObjectType) {
     const aProps = new Set(Object.keys(a.props));
     const bProps = new Set(Object.keys(b.props));
-    return aProps.size === bProps.size && [...aProps].map((aProp) => bProps.has(aProp) && equalJayTypes(a[aProp], b[aProp]));
+    return aProps.size === bProps.size && [...aProps].every(
+      (aProp) => bProps.has(aProp) && equalJayTypes(a.props[aProp], b.props[aProp])
+    );
   } else if (a instanceof JayUnionType && b instanceof JayUnionType) {
     return a.ofTypes.length === b.ofTypes.length && a.ofTypes.reduce((res, aType) => res && b.hasType(aType), true);
   } else if (a instanceof JayPromiseType && b instanceof JayPromiseType) {
@@ -778,6 +859,7 @@ const JAY_QUERY_PREFIX = "?jay-";
 const JAY_QUERY_MAIN_SANDBOX = `${JAY_QUERY_PREFIX}${"mainSandbox"}`;
 const JAY_QUERY_WORKER_TRUSTED = `${JAY_QUERY_PREFIX}${"workerTrusted"}`;
 const JAY_QUERY_WORKER_SANDBOX = `${JAY_QUERY_PREFIX}${"workerSandbox"}`;
+const JAY_QUERY_HYDRATE = `${JAY_QUERY_PREFIX}hydrate`;
 const JAY_QUERY_MAIN_SANDBOX_TS = `${JAY_QUERY_PREFIX}${"mainSandbox"}${TS_EXTENSION}`;
 const JAY_QUERY_WORKER_TRUSTED_TS = `${JAY_QUERY_PREFIX}${"workerTrusted"}${TS_EXTENSION}`;
 const JAY_QUERY_WORKER_SANDBOX_TS = `${JAY_QUERY_PREFIX}${"workerSandbox"}${TS_EXTENSION}`;
@@ -840,6 +922,12 @@ var JayBuildEnvironment = /* @__PURE__ */ ((JayBuildEnvironment2) => {
 const JAY_QUERY_CLIENT = `${JAY_QUERY_PREFIX}${"client"}`;
 const JAY_QUERY_SERVER = `${JAY_QUERY_PREFIX}${"server"}`;
 const JAY_QUERY_PATTERNS = [
+  // Hydrate target
+  {
+    pattern: JAY_QUERY_HYDRATE,
+    buildEnv: "client",
+    isHydrate: true
+  },
   // Build environments
   {
     pattern: `${JAY_QUERY_PREFIX}${"client"}`,
@@ -891,13 +979,21 @@ function parseJayModuleSpecifier(specifier) {
   const fullQueryString = specifier.substring(queryIndex);
   let buildEnvironment;
   let runtimeMode;
+  let isHydrate;
   let remainingQuery = fullQueryString;
-  for (const { pattern, buildEnv, runtimeMode: rtMode } of JAY_QUERY_PATTERNS) {
+  for (const {
+    pattern,
+    buildEnv,
+    runtimeMode: rtMode,
+    isHydrate: hydrate
+  } of JAY_QUERY_PATTERNS) {
     if (remainingQuery.includes(pattern)) {
       if (buildEnv)
         buildEnvironment = buildEnv;
       if (rtMode)
         runtimeMode = rtMode;
+      if (hydrate)
+        isHydrate = true;
       remainingQuery = remainingQuery.replace(pattern, "");
     }
   }
@@ -906,6 +1002,7 @@ function parseJayModuleSpecifier(specifier) {
     basePath,
     buildEnvironment,
     runtimeMode,
+    isHydrate,
     otherQueryParams,
     fullQueryString
   };
@@ -1451,6 +1548,53 @@ function resolvePluginManifest(projectRoot, pluginName) {
     `Plugin "${pluginName}" not found. Searched in src/plugins/${pluginName}/ and node_modules/${pluginName}/. Ensure the plugin is installed or exists in your project.`
   ]);
 }
+function compileCoordinateExpr(template, varMappings) {
+  if (!template.includes("$")) {
+    return `'${template}'`;
+  }
+  const parts = [];
+  let remaining = template;
+  while (remaining.length > 0) {
+    const match = remaining.match(/\$([a-zA-Z_]\w*)/);
+    if (!match) {
+      parts.push(`'${remaining}'`);
+      break;
+    }
+    const placeholderName = match[1];
+    const placeholderStart = match.index;
+    if (placeholderStart > 0) {
+      parts.push(`'${remaining.substring(0, placeholderStart)}'`);
+    }
+    const varExpr = varMappings[placeholderName];
+    if (varExpr === void 0) {
+      throw new Error(
+        `compileCoordinateExpr: no mapping for placeholder "$${placeholderName}" in template "${template}"`
+      );
+    }
+    parts.push(`escapeAttr(String(${varExpr}))`);
+    remaining = remaining.substring(placeholderStart + match[0].length);
+  }
+  return parts.join(" + ");
+}
+function isStaticCoordinate(template) {
+  return !template.includes("$");
+}
+function computeInstanceKey(coordinateSuffix, context, prefix) {
+  switch (context) {
+    case "static":
+      return coordinateSuffix;
+    case "slowForEach":
+      return `${prefix}/${coordinateSuffix}`;
+    case "forEach":
+      return void 0;
+  }
+}
+function compileForEachInstanceKeyExpr(coordinateSuffix, trackByExpr) {
+  return `String(${trackByExpr}) + ',${coordinateSuffix}'`;
+}
+function computeForEachInstanceKey(trackByValue, coordinateSuffix) {
+  return [trackByValue, coordinateSuffix].toString();
+}
 const s = createRequire(import.meta.url), e = s("typescript"), u = e, c = new Proxy(e, {
   get(t, r) {
     return t[r];
@@ -1475,6 +1619,7 @@ export {
   JAY_EXTENSION,
   JAY_FULLSTACK_COMPONENTS,
   JAY_QUERY_CLIENT,
+  JAY_QUERY_HYDRATE,
   JAY_QUERY_MAIN_SANDBOX,
   JAY_QUERY_MAIN_SANDBOX_TS,
   JAY_QUERY_PREFIX,
@@ -1485,6 +1630,7 @@ export {
   JAY_QUERY_WORKER_TRUSTED_TS,
   JAY_RUNTIME,
   JAY_SECURE,
+  JAY_SSR_RUNTIME,
   JAY_STACK_CLIENT_RUNTIME,
   JAY_TS_EXTENSION,
   JayArrayType,
@@ -1523,6 +1669,10 @@ export {
   WithValidations,
   addBuildEnvironment,
   checkValidationErrors,
+  compileCoordinateExpr,
+  compileForEachInstanceKeyExpr,
+  computeForEachInstanceKey,
+  computeInstanceKey,
   equalJayTypes,
   findDynamicContract,
   getBasePath,
@@ -1552,6 +1702,7 @@ export {
   isOptionalType,
   isPromiseType,
   isRecursiveType,
+  isStaticCoordinate,
   isTypeAliasType,
   isUnionType,
   jayTypeToJsonSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/compiler-shared",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "type": "module",
   "description": "",
   "license": "Apache-2.0",
@@ -25,10 +25,10 @@
   },
   "author": "",
   "dependencies": {
-    "@jay-framework/component": "^0.13.0",
-    "@jay-framework/runtime": "^0.13.0",
-    "@jay-framework/secure": "^0.13.0",
-    "@jay-framework/typescript-bridge": "^0.8.0",
+    "@jay-framework/component": "^0.15.0",
+    "@jay-framework/runtime": "^0.15.0",
+    "@jay-framework/secure": "^0.15.0",
+    "@jay-framework/typescript-bridge": "^0.10.0",
     "@types/js-yaml": "^4.0.9",
     "change-case": "^4.1.2",
     "js-beautify": "^1.14.11",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@caiogondim/strip-margin": "^1.0.0",
-    "@jay-framework/dev-environment": "^0.13.0",
+    "@jay-framework/dev-environment": "^0.15.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/js-beautify": "^1",
     "@types/node": "^20.11.5",