@jay-framework/compiler-jay-html 0.15.4 → 0.15.6

package/dist/index.d.cts

@@ -39,6 +39,8 @@ interface ContractParam {
 }
 interface Contract {
     name: string;
+    /** Human-readable description of the contract (for agent-kit and validation). */
+    description?: string;
     tags: Array<ContractTag>;
     props?: Array<ContractProp>;
     /** URL/load params (e.g. slug for [slug] route). Generates Params extends UrlParams. */
@@ -95,10 +97,16 @@ interface JayImportResolver {
     /**
      * Read a jay-html file adjacent to a component module.
      * Given a module src path (e.g., "./header/header"), resolves to the absolute path
-     * and reads the corresponding .jay-html file (same base name + .jay-html extension).
-     * Returns the file content string, or null if not found.
+     * and reads the corresponding .jay-html file. Tries two conventions:
+     * 1. File-based: `<src>.jay-html` (e.g., `header/header.jay-html`)
+     * 2. Directory-based: `<src>/<basename>.jay-html` (e.g., `header/header/header.jay-html`)
+     * Returns the file content and the directory containing the jay-html file, or null if not found.
      */
-    readJayHtml(importingModuleDir: string, src: string): string | null;
+    readJayHtml(importingModuleDir: string, src: string): {
+        content: string;
+        componentDir: string;
+        filePath: string;
+    } | null;
 }
 declare const JAY_IMPORT_RESOLVER: JayImportResolver;
 
@@ -185,6 +193,11 @@ interface JayHtmlSourceFile extends CompilerSourceFile {
      * Used by the dev server to watch these files for changes.
      */
     linkedCssFiles?: string[];
+    /**
+     * Absolute paths to headfull FS component jay-html files included by this page.
+     * Includes nested headfull components. Used by the dev server to watch for changes.
+     */
+    linkedComponentFiles?: string[];
     filename?: string;
     contract?: Contract;
     contractRef?: string;
@@ -229,11 +242,12 @@ declare function generateServerElementFile(jayFile: JayHtmlSourceFile, _options?
 /**
  * Coordinate pre-processing for SSR/hydration consistency.
  *
- * Assigns `jay-coordinate-base` attributes to all elements that need coordinates,
- * in a single pass before either server or hydrate compilation runs.
- * Both compilers read this attribute instead of computing coordinates independently.
+ * Assigns `jay-coordinate-base` and `jay-scope` attributes to all elements
+ * that need coordinates, in a single pass before either server or hydrate
+ * compilation runs. Both compilers read these attributes instead of computing
+ * coordinates independently.
  *
- * See Design Log #103, #106.
+ * See Design Log #103, #106, #126 (scoped coordinates).
  */
 
 interface AssignCoordinatesOptions {
@@ -254,7 +268,7 @@ interface AssignCoordinatesResult {
  */
 declare function assignCoordinatesToJayHtml(jayHtml: string, headlessContractNames: Set<string>): string;
 /**
- * Assign `jay-coordinate-base` attributes to elements in the DOM tree.
+ * Assign `jay-coordinate-base` and `jay-scope` attributes to elements in the DOM tree.
  *
  * Must run after slow-render (which resolves slow conditions, unrolls slowForEach,
  * and wraps multi-child headless inline templates).
@@ -278,9 +292,137 @@ declare function assignCoordinates(body: HTMLElement, options: AssignCoordinates
  * @returns The HTML with headfull FS templates injected (or unchanged if none found)
  */
 declare function injectHeadfullFSTemplates(html: string, sourceDir: string, importResolver: JayImportResolver): string;
-declare function parseJayFile(html: string, filename: string, filePath: string, options: ResolveTsConfigOptions, linkedContractResolver: JayImportResolver, projectRoot: string): Promise<WithValidations<JayHtmlSourceFile>>;
+declare function parseJayFile(html: string, filename: string, filePath: string, options: ResolveTsConfigOptions, linkedContractResolver: JayImportResolver, projectRoot: string, 
+/** Optional source directory for resolving headfull FS files (jay-html, contracts).
+ *  When parsing pre-rendered files, filePath is in build/pre-rendered/ but headfull
+ *  relative paths were written for the original source directory. Pass the source
+ *  directory here so file resolution works correctly while module paths stay relative
+ *  to the actual filePath. */
+sourceDir?: string): Promise<WithValidations<JayHtmlSourceFile>>;
 declare function getJayHtmlImports(html: string): string[];
 
+declare const htmlElementTagNameMap: {
+    a: string;
+    abbr: string;
+    address: string;
+    applet: string;
+    area: string;
+    article: string;
+    aside: string;
+    audio: string;
+    b: string;
+    base: string;
+    basefont: string;
+    bdi: string;
+    bdo: string;
+    blockquote: string;
+    body: string;
+    br: string;
+    button: string;
+    canvas: string;
+    caption: string;
+    cite: string;
+    code: string;
+    col: string;
+    colgroup: string;
+    data: string;
+    datalist: string;
+    dd: string;
+    del: string;
+    details: string;
+    dfn: string;
+    dialog: string;
+    dir: string;
+    div: string;
+    dl: string;
+    dt: string;
+    em: string;
+    embed: string;
+    fieldset: string;
+    figcaption: string;
+    figure: string;
+    font: string;
+    footer: string;
+    form: string;
+    frame: string;
+    frameset: string;
+    h1: string;
+    h2: string;
+    h3: string;
+    h4: string;
+    h5: string;
+    h6: string;
+    head: string;
+    header: string;
+    hgroup: string;
+    hr: string;
+    html: string;
+    i: string;
+    iframe: string;
+    img: string;
+    input: string;
+    ins: string;
+    kbd: string;
+    label: string;
+    legend: string;
+    li: string;
+    link: string;
+    main: string;
+    map: string;
+    mark: string;
+    marquee: string;
+    menu: string;
+    meta: string;
+    meter: string;
+    nav: string;
+    noscript: string;
+    object: string;
+    ol: string;
+    optgroup: string;
+    option: string;
+    output: string;
+    p: string;
+    param: string;
+    picture: string;
+    pre: string;
+    progress: string;
+    q: string;
+    rp: string;
+    rt: string;
+    ruby: string;
+    s: string;
+    samp: string;
+    script: string;
+    section: string;
+    select: string;
+    slot: string;
+    small: string;
+    source: string;
+    span: string;
+    strong: string;
+    style: string;
+    sub: string;
+    summary: string;
+    sup: string;
+    table: string;
+    tbody: string;
+    td: string;
+    template: string;
+    textarea: string;
+    tfoot: string;
+    th: string;
+    thead: string;
+    time: string;
+    title: string;
+    tr: string;
+    track: string;
+    u: string;
+    ul: string;
+    var: string;
+    video: string;
+    wbr: string;
+};
+
 declare function generateTypes(types: JayType): string;
 
 /**
@@ -456,4 +598,4 @@ declare function resolveHeadlessInstances(preRenderedJayHtml: string, instanceDa
  */
 declare function hasSlowPhaseProperties(contract: Contract | undefined): boolean;
 
-export { type ActionDefinition, type AssignCoordinatesOptions, type AssignCoordinatesResult, type Contract, type ContractImportInfo, type ContractParam, type ContractParamKind, 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 ServerElementOptions, type SlowRenderInput, type SlowRenderOutput, assignCoordinates, assignCoordinatesToJayHtml, buildInstanceCoordinateKey, compileAction, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, createPhaseContract, defaultContractResolver, discoverHeadlessInstances, filterTagsByPhase, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateElementHydrateFile, generateSandboxRootFile, generateServerElementFile, generateTypes, getEffectivePhase, getJayHtmlImports, getLinkedContractDir, hasSlowPhaseProperties, injectHeadfullFSTemplates, isTagInPhase, loadLinkedContract, parseAction, parseContract, parseEnumValues, parseIsEnum, parseJayFile, renderRefsType, resolveHeadlessInstances, slowRenderTransform, validateContractPhases };
+export { type ActionDefinition, type AssignCoordinatesOptions, type AssignCoordinatesResult, type Contract, type ContractImportInfo, type ContractParam, type ContractParamKind, 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 ServerElementOptions, type SlowRenderInput, type SlowRenderOutput, assignCoordinates, assignCoordinatesToJayHtml, buildInstanceCoordinateKey, compileAction, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, createPhaseContract, defaultContractResolver, discoverHeadlessInstances, filterTagsByPhase, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateElementHydrateFile, generateSandboxRootFile, generateServerElementFile, generateTypes, getEffectivePhase, getJayHtmlImports, getLinkedContractDir, hasSlowPhaseProperties, htmlElementTagNameMap, injectHeadfullFSTemplates, isTagInPhase, loadLinkedContract, parseAction, parseContract, parseEnumValues, parseIsEnum, parseJayFile, renderRefsType, resolveHeadlessInstances, slowRenderTransform, validateContractPhases };