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

package/dist/index.d.cts

@@ -1,45 +1,7 @@
-import { CompilerSourceFile, SourceFileFormat, JayType, RefsTree, JayImportLink, WithValidations, MainRuntimeModes, JayEnumType, GenerateTarget, Imports } from '@jay-framework/compiler-shared';
+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';
 
-interface JayHtmlNamespace {
-    prefix: string;
-    namespace: string;
-}
-interface JayHeadlessImports {
-    key: string;
-    refs: RefsTree;
-    rootType: JayType;
-    contractLinks: JayImportLink[];
-    codeLink: JayImportLink;
-}
-interface JayHtmlHeadLink {
-    rel: string;
-    href: string;
-    attributes: Record<string, string>;
-}
-interface JayHtmlSourceFile extends CompilerSourceFile {
-    format: SourceFileFormat.JayHtml;
-    baseElementName: string;
-    types: JayType;
-    body: HTMLElement;
-    namespaces: JayHtmlNamespace[];
-    headlessImports: JayHeadlessImports[];
-    headLinks: JayHtmlHeadLink[];
-    css?: string;
-    filename?: string;
-    contract?: any;
-    contractRef?: string;
-    hasInlineData?: boolean;
-}
-
-declare function generateElementDefinitionFile(parsedFile: WithValidations<JayHtmlSourceFile>): WithValidations<string>;
-declare function generateElementFile(jayFile: JayHtmlSourceFile, importerMode: MainRuntimeModes): WithValidations<string>;
-declare function generateElementBridgeFile(jayFile: JayHtmlSourceFile): string;
-declare function generateSandboxRootFile(jayFile: JayHtmlSourceFile): string;
-
-declare function generateElementFileReactTarget(jayFile: JayHtmlSourceFile, importerMode: MainRuntimeModes): WithValidations<string>;
-
 declare enum ContractTagType {
     data = 0,
     interactive = 1,
@@ -56,6 +18,7 @@ interface ContractTag {
     description?: Array<string>;
     tags?: Array<ContractTag>;
     repeated?: boolean;
+    trackBy?: string;
     link?: string;
     async?: boolean;
     phase?: RenderingPhase;
@@ -69,6 +32,14 @@ declare function compileContract(contractWithValidations: WithValidations<Contra
 
 declare function parseContract(contractYaml: string, fileName: string): WithValidations<Contract>;
 
+interface JayImportResolver {
+    resolveLink(importingModuleDir: string, link: string): string;
+    loadContract(fullPath: string): WithValidations<Contract>;
+    analyzeExportedTypes(fullPath: string, options: ResolveTsConfigOptions): JayType[];
+    resolvePluginComponent(pluginName: string, contractName: string, projectRoot: string): WithValidations<PluginComponentResolution>;
+}
+declare const JAY_IMPORT_RESOLVER: JayImportResolver;
+
 interface JayContractImportLink {
     module: string;
     viewState: string;
@@ -100,14 +71,61 @@ interface PhaseViewStates {
  */
 declare function contractToAllPhaseViewStates(contract: Contract, contractFilePath: string, jayImportResolver: JayImportResolver): Promise<WithValidations<PhaseViewStates>>;
 
-interface JayImportResolver {
-    resolveLink(importingModuleDir: string, link: string): string;
-    loadContract(fullPath: string): WithValidations<Contract>;
-    analyzeExportedTypes(fullPath: string, options: ResolveTsConfigOptions): JayType[];
+interface JayHtmlNamespace {
+    prefix: string;
+    namespace: string;
 }
-declare const JAY_IMPORT_RESOLVER: JayImportResolver;
+interface JayHeadlessImports {
+    key: string;
+    refs: RefsTree;
+    rootType: JayType;
+    contractLinks: JayImportLink[];
+    codeLink: JayImportLink;
+    contract?: Contract;
+}
+interface JayHtmlHeadLink {
+    rel: string;
+    href: string;
+    attributes: Record<string, string>;
+}
+interface JayHtmlSourceFile extends CompilerSourceFile {
+    format: SourceFileFormat.JayHtml;
+    baseElementName: string;
+    types: JayType;
+    body: HTMLElement;
+    namespaces: JayHtmlNamespace[];
+    headlessImports: JayHeadlessImports[];
+    headLinks: JayHtmlHeadLink[];
+    css?: string;
+    /**
+     * Absolute paths to linked CSS files referenced via <link rel="stylesheet">.
+     * Used by the dev server to watch these files for changes.
+     */
+    linkedCssFiles?: string[];
+    filename?: string;
+    contract?: Contract;
+    contractRef?: string;
+    hasInlineData?: boolean;
+    /**
+     * TrackBy map for server-side merge (slow → fast).
+     * Includes all tracked arrays.
+     */
+    serverTrackByMap?: Record<string, string>;
+    /**
+     * TrackBy map for client-side merge (fast → interactive).
+     * Excludes arrays with phase 'fast+interactive' (dynamic arrays that can be fully replaced).
+     */
+    clientTrackByMap?: Record<string, string>;
+}
+
+declare function generateElementDefinitionFile(parsedFile: WithValidations<JayHtmlSourceFile>): WithValidations<string>;
+declare function generateElementFile(jayFile: JayHtmlSourceFile, importerMode: MainRuntimeModes): WithValidations<string>;
+declare function generateElementBridgeFile(jayFile: JayHtmlSourceFile): string;
+declare function generateSandboxRootFile(jayFile: JayHtmlSourceFile): string;
+
+declare function generateElementFileReactTarget(jayFile: JayHtmlSourceFile, importerMode: MainRuntimeModes): WithValidations<string>;
 
-declare function parseJayFile(html: string, filename: string, filePath: string, options: ResolveTsConfigOptions, linkedContractResolver: JayImportResolver): Promise<WithValidations<JayHtmlSourceFile>>;
+declare function parseJayFile(html: string, filename: string, filePath: string, options: ResolveTsConfigOptions, linkedContractResolver: JayImportResolver, projectRoot: string): Promise<WithValidations<JayHtmlSourceFile>>;
 declare function getJayHtmlImports(html: string): string[];
 
 declare function parseIsEnum(expression: string): boolean;
@@ -120,4 +138,42 @@ declare function renderRefsType(refs: RefsTree, refsType: string, generateTarget
 
 declare function generateTypes(types: JayType): string;
 
-export { type Contract, type ContractTag, ContractTagType, type EnumToImport, JAY_IMPORT_RESOLVER, type JayContractImportLink, type JayHtmlSourceFile, type JayImportResolver, type PhaseViewStates, type RenderingPhase, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateSandboxRootFile, generateTypes, getJayHtmlImports, parseContract, parseEnumValues, parseIsEnum, parseJayFile, renderRefsType };
+/**
+ * Input for slow render transformation
+ */
+interface SlowRenderInput {
+    /** Original jay-html content */
+    jayHtmlContent: string;
+    /** Slow phase view state data */
+    slowViewState: Record<string, unknown>;
+    /** Contract metadata for phase detection */
+    contract?: Contract;
+    /**
+     * 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;
+}
+/**
+ * Output of slow render transformation
+ */
+interface SlowRenderOutput {
+    /** Pre-rendered jay-html content */
+    preRenderedJayHtml: string;
+}
+/**
+ * Transform a jay-html file by resolving slow-phase bindings
+ *
+ * This is the main entry point for slow rendering.
+ *
+ * @param input - The input containing jay-html content, slow view state, and contract
+ * @returns The pre-rendered jay-html with slow bindings resolved
+ */
+declare function slowRenderTransform(input: SlowRenderInput): WithValidations<SlowRenderOutput>;
+/**
+ * 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 };