@jay-framework/compiler-jay-html 0.11.0 → 0.13.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 { JayType, WithValidations, PluginComponentResolution, PluginManifest, JayEnumType, RefsTree, CompilerSourceFile, SourceFileFormat, JayImportLink, MainRuntimeModes, GenerateTarget, Imports, JayObjectType } 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,72 @@ 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>;
+    }>;
+    resolvePluginManifest(pluginName: string, projectRoot: string): WithValidations<PluginManifest>;
 }
 declare const JAY_IMPORT_RESOLVER: JayImportResolver;
 
@@ -71,17 +124,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 +212,71 @@ declare function renderRefsType(refs: RefsTree, refsType: string, generateTarget
 
 declare function generateTypes(types: JayType): string;
 
+/**
+ * Parser for .jay-action files (compact jay-type notation).
+ *
+ * Produces JayType from the compact format used by jay-html data scripts:
+ * - Primitives: string, number, boolean → JayAtomicType
+ * - Enums: enum(a | b | c) → JayEnumType
+ * - Arrays: YAML list / type[] shorthand → JayArrayType
+ * - Objects: nested YAML maps → JayObjectType (with optionalProps tracking)
+ * - Optional: ? suffix on property keys → tracked in JayObjectType.optionalProps
+ * - Contract imports: import: block → JayImportedType
+ */
+
+/**
+ * Parsed action definition from a .jay-action file.
+ * Uses JayType for the type representation.
+ */
+interface ActionDefinition {
+    name: string;
+    description: string;
+    /** Import aliases: alias → contract subpath (e.g., productCard → product-card.jay-contract) */
+    imports: Record<string, string>;
+    /** Input schema as a JayObjectType. Optional props tracked in optionalProps. */
+    inputType: JayObjectType;
+    /** Output type (any JayType shape, or undefined if no output). */
+    outputType?: JayType;
+}
+/**
+ * Parses a .jay-action YAML string into an ActionDefinition using JayType.
+ */
+declare function parseAction(actionYaml: string, fileName: string): WithValidations<ActionDefinition>;
+
+/**
+ * Compiler for .jay-action files → .jay-action.d.ts
+ *
+ * Generates TypeScript Input/Output interfaces from JayType trees,
+ * including import statements for contract references (JayImportedType).
+ */
+
+interface ContractImportInfo {
+    importPath: string;
+    viewStateName: string;
+}
+type ContractResolver = (contractSubpath: string) => ContractImportInfo | null;
+/**
+ * Default contract resolver that derives names from the subpath.
+ */
+declare function defaultContractResolver(contractSubpath: string): ContractImportInfo;
+/**
+ * Compiles an ActionDefinition (with JayType) into a TypeScript .d.ts string.
+ */
+declare function compileAction(actionWithValidations: WithValidations<ActionDefinition>, contractResolver?: ContractResolver): WithValidations<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 +285,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 +320,69 @@ 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;
+/**
+ * A headless instance found inside a preserved forEach (fast phase).
+ * These instances have unresolved prop bindings and need per-item rendering
+ * at fast phase time. They are only allowed if the component has no slow phase.
+ */
+interface ForEachHeadlessInstance {
+    contractName: string;
+    /** The forEach attribute path on the ancestor element (e.g., "allProducts.items") */
+    forEachPath: string;
+    /** TrackBy key for the forEach (e.g., "_id") */
+    trackBy: string;
+    /** Prop bindings referencing forEach item fields (e.g., { productId: "{_id}" }) */
+    propBindings: Record<string, string>;
+    /** Coordinate suffix after trackBy values (e.g., "product-card:0") */
+    coordinateSuffix: string;
+}
+interface HeadlessInstanceDiscoveryResult {
+    instances: DiscoveredHeadlessInstance[];
+    /** Headless instances inside preserved forEach elements (need server-time validation) */
+    forEachInstances: ForEachHeadlessInstance[];
+    /** 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 ActionDefinition, type Contract, type ContractImportInfo, type ContractParam, type ContractProp, type ContractResolver, type ContractTag, ContractTagType, type DiscoveredHeadlessInstance, type EnumToImport, type ForEachHeadlessInstance, type HeadlessContractInfo, type HeadlessInstanceDiscoveryResult, type HeadlessInstanceResolvedData, JAY_IMPORT_RESOLVER, type JayContractImportLink, type JayHtmlSourceFile, type JayImportResolver, type PhaseViewStates, type RenderingPhase, type SlowRenderInput, type SlowRenderOutput, buildInstanceCoordinateKey, compileAction, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, createPhaseContract, defaultContractResolver, discoverHeadlessInstances, filterTagsByPhase, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateSandboxRootFile, generateTypes, getEffectivePhase, getJayHtmlImports, getLinkedContractDir, hasSlowPhaseProperties, isTagInPhase, loadLinkedContract, parseAction, parseContract, parseEnumValues, parseIsEnum, parseJayFile, renderRefsType, resolveHeadlessInstances, slowRenderTransform, validateContractPhases };