HTML Template Processing

/**
 * Compiles an HTML file to a TypeScript variable
 * @param filename - Path to HTML file to convert
 * @param options - Conversion options for naming and output
 * @returns Path to generated TypeScript file
 */
function compileHTML(filename: string, options: IHtml2TSOptions): string;

interface IHtml2TSOptions {
  /** Template function for generating module names */
  moduleFunction: Function;
  /** Template function for generating variable names */
  varFunction: Function;
  /** Custom output template (overrides default) */
  htmlOutputTemplate?: string;
  /** Output directory for generated TypeScript files */
  htmlOutDir?: string;
  /** Flatten directory structure in output */
  flatten?: boolean;
  /** End-of-line character to use */
  eol?: string;
}

interface HTMLProcessingConfig {
  /** HTML file glob patterns to process */
  html?: string[];
  /** Output directory for generated TypeScript files */
  htmlOutDir?: string;
  /** Flatten generated files to single directory */
  htmlOutDirFlatten?: boolean;
  /** Template for module names (supports <%= filename %> placeholder) */
  htmlModuleTemplate?: string;
  /** Template for variable names (supports <%= filename %> placeholder) */
  htmlVarTemplate?: string;
  /** Custom TypeScript output template */
  htmlOutputTemplate?: string;
}

grunt.initConfig({
  ts: {
    default: {
      src: ["src/**/*.ts"],
      html: ["templates/**/*.html"],
      options: {
        htmlModuleTemplate: 'Templates.<%= filename %>',
        htmlVarTemplate: 'content'
      }
    }
  }
});

// Template placeholders available:
interface TemplateContext {
  filename: string; // Base filename without extension
  // Additional context may be available depending on template
}

// Default templates
const defaultTemplates = {
  htmlModuleTemplate: '<%= filename %>', // Generates: MyTemplate  
  htmlVarTemplate: '<%= filename %>',    // Generates: MyTemplate
  htmlOutputTemplate: `/* tslint:disable:max-line-length */
module <%= modulename %> {
  export var <%= varname %> = '<%= content %>';
}`
};

ts: {
  templates: {
    src: ["src/**/*.ts"],
    html: ["views/**/*.html", "partials/**/*.html"],
    options: {
      htmlModuleTemplate: 'Views.<%= filename %>',
      htmlVarTemplate: 'template',
      htmlOutDir: 'generated/templates/',
      htmlOutDirFlatten: true
    }
  }
}

/* tslint:disable:max-line-length */
module Views.profile {
  export var template = '<div class="profile">...</div>';
}

interface CustomTemplateOptions {
  /** Custom TypeScript output template with placeholders */
  htmlOutputTemplate: string;
}

// Available placeholders in htmlOutputTemplate:
interface OutputTemplateContext {
  modulename: string; // Result of htmlModuleTemplate
  varname: string;    // Result of htmlVarTemplate  
  content: string;    // Escaped HTML content
}

ts: {
  external: {
    html: ["templates/**/*.html"],
    options: {
      htmlModuleTemplate: 'html',
      htmlVarTemplate: 'markup',
      htmlOutputTemplate: `/* tslint:disable:max-line-length */
export module <%= modulename %> {
  export var <%= varname %> = '<%= content %>';
}`
    }
  }
}

interface HTMLContentProcessing {
  /** Character used for string quoting (default: single quote) */
  quoteChar?: string;
  /** Replacement for newlines in HTML content (default: empty string) */
  nlReplace?: string;
  /** Whether to remove BOM from UTF-8 files */
  stripBOM?: boolean;
  /** Convert dashed filenames to camelCase for module names */
  toCamel?: boolean;
}

// Internal processing functions
function escapeContent(content: string, quoteChar?: string): string;
function toCamel(str: string): string;
function stripBOM(str: string): string;

interface DirectoryControl {
  /** Root directory for generated TypeScript files */
  htmlOutDir?: string;
  /** 
   * Flatten directory structure - all generated files go to htmlOutDir root
   * Without flatten: templates/user/profile.html -> generated/templates/user/profile.html.ts
   * With flatten: templates/user/profile.html -> generated/profile.html.ts
   */
  htmlOutDirFlatten?: boolean;
}

// Preserve directory structure
ts: {
  preserve: {
    html: ["views/**/*.html"],
    options: {
      htmlOutDir: "generated/",
      htmlOutDirFlatten: false
    }
  }
}
// Result: views/user/profile.html -> generated/views/user/profile.html.ts

// Flatten to single directory
ts: {
  flatten: {
    html: ["views/**/*.html"],  
    options: {
      htmlOutDir: "generated/",
      htmlOutDirFlatten: true
    }
  }
}
// Result: views/user/profile.html -> generated/profile.html.ts

interface HTMLOnlyConfig {
  /** Empty source array when only processing HTML */
  src: [];
  /** HTML files to process */
  html: string[];
  /** Disable TypeScript compilation */
  options: {
    compile: false;
  };
}

ts: {
  htmlOnly: {
    src: [], // Empty - no TypeScript files to compile
    html: ["templates/**/*.html"],
    options: {
      compile: false, // Don't compile the generated .ts files
      htmlModuleTemplate: 'Templates.<%= filename %>',
      htmlOutDir: 'src/generated/'
    }
  }
}

// Processing order:
// 1. HTML files are converted to TypeScript
// 2. Generated TypeScript files are added to compilation if they match src globs
// 3. TypeScript compilation proceeds with original + generated files
// 4. Reference files and transforms are processed
// 5. Final compilation occurs

interface IntegrationBehavior {
  /** Generated HTML TypeScript files are automatically included if they match src patterns */
  autoInclude: boolean;
  /** HTML processing occurs before reference file generation */
  processingOrder: "html-first";
  /** Generated files can be excluded from src globs using negation patterns */
  excludeGenerated: string; // e.g., "!generated/**"
}

ts: {
  fullBuild: {
    src: ["src/**/*.ts", "generated/**/*.ts"], // Include generated HTML files
    html: ["templates/**/*.html"],
    reference: "src/references.ts",
    outDir: "built/",
    options: {
      target: "es5",
      module: "amd",
      htmlModuleTemplate: 'Templates.<%= filename %>',
      htmlOutDir: "generated/templates/"
    }
  }
}