@jay-framework/compiler-jay-html 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { JayType, WithValidations, PluginComponentResolution, JayEnumType, RefsTree, CompilerSourceFile, SourceFileFormat, JayImportLink, MainRuntimeModes, GenerateTarget, Imports } from '@jay-framework/compiler-shared';
 import { HTMLElement } from 'node-html-parser';
 import { ResolveTsConfigOptions } from '@jay-framework/compiler-analyze-exported-types';
+import { Coordinate } from '@jay-framework/runtime';
 
 declare enum ContractTagType {
     data = 0,
@@ -23,20 +24,71 @@ interface ContractTag {
     async?: boolean;
     phase?: RenderingPhase;
 }
+interface ContractProp {
+    name: string;
+    dataType: JayType;
+    required?: boolean;
+    description?: Array<string>;
+    default?: string;
+}
+/** URL/load params for a page (e.g. [slug]). Always string in generated type (UrlParams = Record<string, string>). Design Log #85. */
+interface ContractParam {
+    name: string;
+}
 interface Contract {
     name: string;
     tags: Array<ContractTag>;
+    props?: Array<ContractProp>;
+    /** URL/load params (e.g. slug for [slug] route). Generates Params extends UrlParams. */
+    params?: Array<ContractParam>;
 }
 
 declare function compileContract(contractWithValidations: WithValidations<Contract>, contractFilePath: string, jayImportResolver: JayImportResolver): Promise<WithValidations<string>>;
 
 declare function parseContract(contractYaml: string, fileName: string): WithValidations<Contract>;
 
+/**
+ * Get the effective phase for a tag (explicit or default)
+ */
+declare function getEffectivePhase(tag: ContractTag, parentPhase?: RenderingPhase): RenderingPhase;
+/**
+ * Check if a tag should be included in a specific phase's ViewState
+ * A tag is included if its effective phase exactly matches the target phase
+ */
+declare function isTagInPhase(tag: ContractTag, targetPhase: RenderingPhase, parentPhase?: RenderingPhase): boolean;
+/**
+ * Validate phase constraints across the entire contract
+ */
+declare function validateContractPhases(contract: Contract): string[];
+/**
+ * Filter tags recursively by phase
+ * Returns only tags that should be included in the target phase's ViewState
+ */
+declare function filterTagsByPhase(tags: ContractTag[], targetPhase: RenderingPhase, parentPhase?: RenderingPhase): ContractTag[];
+/**
+ * Create a phase-specific contract
+ * Returns a contract with only tags that belong to the target phase
+ */
+declare function createPhaseContract(contract: Contract, targetPhase: RenderingPhase): Contract;
+
 interface JayImportResolver {
     resolveLink(importingModuleDir: string, link: string): string;
+    /** Load a contract from an absolute file path */
     loadContract(fullPath: string): WithValidations<Contract>;
     analyzeExportedTypes(fullPath: string, options: ResolveTsConfigOptions): JayType[];
     resolvePluginComponent(pluginName: string, contractName: string, projectRoot: string): WithValidations<PluginComponentResolution>;
+    /**
+     * Load a contract from a plugin, handling both static and dynamic contracts.
+     * For static contracts, loads from the plugin's contract file.
+     * For dynamic contracts, loads from materialized location (build/materialized-contracts/).
+     *
+     * Returns the contract, path, and optional metadata (for dynamic contracts).
+     */
+    loadPluginContract(pluginName: string, contractName: string, projectRoot: string): WithValidations<{
+        contract: Contract;
+        contractPath: string;
+        metadata?: Record<string, unknown>;
+    }>;
 }
 declare const JAY_IMPORT_RESOLVER: JayImportResolver;
 
@@ -71,17 +123,38 @@ interface PhaseViewStates {
  */
 declare function contractToAllPhaseViewStates(contract: Contract, contractFilePath: string, jayImportResolver: JayImportResolver): Promise<WithValidations<PhaseViewStates>>;
 
+/**
+ * Load a linked contract using the import resolver.
+ * Returns the parsed contract or null if not found/failed.
+ *
+ * @param linkPath - The link path from the contract (e.g., "./product-card")
+ * @param baseContractDir - Directory of the contract containing the link
+ * @param importResolver - Import resolver for loading contracts
+ */
+declare function loadLinkedContract(linkPath: string, baseContractDir: string, importResolver: JayImportResolver): Contract | null;
+/**
+ * Get the directory of a linked contract for resolving nested links.
+ *
+ * @param linkPath - The link path from the contract (e.g., "./product-card")
+ * @param baseContractDir - Directory of the contract containing the link
+ * @param importResolver - Import resolver for path resolution
+ */
+declare function getLinkedContractDir(linkPath: string, baseContractDir: string, importResolver: JayImportResolver): string;
+
 interface JayHtmlNamespace {
     prefix: string;
     namespace: string;
 }
 interface JayHeadlessImports {
-    key: string;
+    key?: string;
+    contractName: string;
     refs: RefsTree;
     rootType: JayType;
     contractLinks: JayImportLink[];
     codeLink: JayImportLink;
     contract?: Contract;
+    contractPath?: string;
+    metadata?: Record<string, unknown>;
 }
 interface JayHtmlHeadLink {
     rel: string;
@@ -138,6 +211,19 @@ declare function renderRefsType(refs: RefsTree, refsType: string, generateTarget
 
 declare function generateTypes(types: JayType): string;
 
+/**
+ * Headless contract with its key (used for property path prefix)
+ */
+interface HeadlessContractInfo {
+    /** The key attribute from the headless script tag */
+    key: string;
+    /** The parsed contract */
+    contract: Contract;
+    /** Path to the contract file (used to resolve linked sub-contracts) */
+    contractPath?: string;
+    /** Optional metadata from the generator (for dynamic contracts) */
+    metadata?: Record<string, unknown>;
+}
 /**
  * Input for slow render transformation
  */
@@ -146,14 +232,24 @@ interface SlowRenderInput {
     jayHtmlContent: string;
     /** Slow phase view state data */
     slowViewState: Record<string, unknown>;
-    /** Contract metadata for phase detection */
+    /** Contract metadata for phase detection (page's main contract) */
     contract?: Contract;
+    /**
+     * Headless component contracts, keyed by their `key` attribute.
+     * These contracts provide phase info for properties like `productSearch.categoryName`.
+     */
+    headlessContracts?: HeadlessContractInfo[];
     /**
      * Source directory of the original jay-html file.
      * Used to resolve relative paths (contracts, CSS, components) to absolute paths
      * so the pre-rendered file can be placed in a different directory.
      */
     sourceDir?: string;
+    /**
+     * Import resolver for loading linked sub-contracts.
+     * If not provided, linked sub-contracts will not be resolved.
+     */
+    importResolver?: JayImportResolver;
 }
 /**
  * Output of slow render transformation
@@ -171,9 +267,51 @@ interface SlowRenderOutput {
  * @returns The pre-rendered jay-html with slow bindings resolved
  */
 declare function slowRenderTransform(input: SlowRenderInput): WithValidations<SlowRenderOutput>;
+/**
+ * Discovered headless component instance in pre-rendered jay-html.
+ * Found after Pass 1 (page bindings resolved, slow forEach unrolled).
+ */
+interface DiscoveredHeadlessInstance {
+    /** Contract name from tag name (e.g., "product-card" from <jay:product-card>) */
+    contractName: string;
+    /** Props extracted from element attributes (camelCased keys, string values) */
+    props: Record<string, string>;
+    /**
+     * Coordinate that uniquely identifies this instance in the page tree.
+     * Built from ancestor slowForEach jayTrackBy values + "contractName:localIndex".
+     */
+    coordinate: Coordinate;
+}
+/**
+ * Resolved data for a headless component instance.
+ * Provided by the dev server after calling slowlyRender for each discovered instance.
+ */
+interface HeadlessInstanceResolvedData {
+    /** Coordinate matching the discovered instance */
+    coordinate: Coordinate;
+    /** The component's contract (for phase detection) */
+    contract: Contract;
+    /** Slow phase ViewState data for this instance */
+    slowViewState: Record<string, unknown>;
+}
+/**
+ * Build the full coordinate key string for a <jay:xxx> element.
+ * Format: "jayTrackBy1/jayTrackBy2/.../contractName:ref"
+ *
+ * Uses the element's `ref` attribute if present. If the element has no ref,
+ * a coordinateCounters map must be provided to auto-assign an index.
+ */
+declare function buildInstanceCoordinateKey(element: HTMLElement, contractName: string, coordinateCounters?: Map<string, number>): string;
+interface HeadlessInstanceDiscoveryResult {
+    instances: DiscoveredHeadlessInstance[];
+    /** HTML with auto-generated ref attributes embedded on <jay:xxx> elements */
+    preRenderedJayHtml: string;
+}
+declare function discoverHeadlessInstances(preRenderedJayHtml: string): HeadlessInstanceDiscoveryResult;
+declare function resolveHeadlessInstances(preRenderedJayHtml: string, instanceData: HeadlessInstanceResolvedData[], importResolver?: JayImportResolver): WithValidations<string>;
 /**
  * Check if a jay-html file has any slow-phase properties that can be pre-rendered
  */
 declare function hasSlowPhaseProperties(contract: Contract | undefined): boolean;
 
-export { type Contract, type ContractTag, ContractTagType, type EnumToImport, JAY_IMPORT_RESOLVER, type JayContractImportLink, type JayHtmlSourceFile, type JayImportResolver, type PhaseViewStates, type RenderingPhase, type SlowRenderInput, type SlowRenderOutput, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateSandboxRootFile, generateTypes, getJayHtmlImports, hasSlowPhaseProperties, parseContract, parseEnumValues, parseIsEnum, parseJayFile, renderRefsType, slowRenderTransform };
+export { type Contract, type ContractParam, type ContractProp, type ContractTag, ContractTagType, type DiscoveredHeadlessInstance, type EnumToImport, type HeadlessContractInfo, type HeadlessInstanceDiscoveryResult, type HeadlessInstanceResolvedData, JAY_IMPORT_RESOLVER, type JayContractImportLink, type JayHtmlSourceFile, type JayImportResolver, type PhaseViewStates, type RenderingPhase, type SlowRenderInput, type SlowRenderOutput, buildInstanceCoordinateKey, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, createPhaseContract, discoverHeadlessInstances, filterTagsByPhase, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateSandboxRootFile, generateTypes, getEffectivePhase, getJayHtmlImports, getLinkedContractDir, hasSlowPhaseProperties, isTagInPhase, loadLinkedContract, parseContract, parseEnumValues, parseIsEnum, parseJayFile, renderRefsType, resolveHeadlessInstances, slowRenderTransform, validateContractPhases };