Templates & Rendering

import { precompile, compile } from "ember-template-compiler";
import { template } from "@ember/template-compiler";

/**
 * Precompile template string to wire format for production builds
 * @param template - Handlebars template string
 * @param options - Compilation options
 * @returns Precompiled template as JSON string
 */
function precompile(template: string, options?: CompileOptions): string;

/**
 * Compile template string to executable function for runtime use
 * @param template - Handlebars template string  
 * @param options - Compilation options
 * @returns Compiled template function
 */
function compile(template: string, options?: CompileOptions): Template;

/**
 * Runtime template compilation for template-only components and classes
 * @param templateString - Handlebars template string
 * @param options - Template options including scope or eval
 * @returns Component class or template-only component
 */
function template(templateString: string, options?: TemplateOptions): object;

/**
 * Get default compilation options for current environment
 * @param environment - Target environment (development/production)
 * @returns Default compile options
 */
function compileOptions(environment?: string): CompileOptions;

import { precompile, compile } from "ember-template-compiler";

// Precompile for build-time optimization
const precompiled = precompile(`
  <div class="user-card">
    <h3>{{user.name}}</h3>
    <p>{{user.email}}</p>
    {{#if user.isActive}}
      <span class="badge active">Active</span>
    {{/if}}
  </div>
`);

// Runtime compilation (development only)
const template = compile(`
  <button {{on "click" this.handleClick}}>
    {{this.buttonText}}
  </button>
`);

/**
 * Create a template factory from precompiled template
 * @param precompiled - Precompiled template data
 * @returns Template factory function
 */
function createTemplateFactory(precompiled: PrecompiledTemplate): TemplateFactory;

/**
 * Set template for an object (component, controller, etc.)
 * @param object - Target object
 * @param template - Template to associate
 */
function setTemplate(object: any, template: Template): void;

/**
 * Get template associated with an object
 * @param object - Target object
 * @returns Associated template or undefined
 */
function getTemplate(object: any): Template | undefined;

/**
 * Helper base class for creating stateful helpers
 */
class Helper {
  /**
   * Create helper instance
   * @param properties - Helper properties
   * @returns Helper instance
   */
  static create(properties?: object): Helper;
  
  /**
   * Compute helper result
   * @param params - Positional parameters
   * @param hash - Named parameters
   * @returns Helper result
   */
  compute(params: any[], hash: object): any;
  
  /**
   * Called when helper is destroyed
   */
  destroy(): void;
  
  /** Whether helper is destroying */
  isDestroying: boolean;
  
  /** Whether helper is destroyed */
  isDestroyed: boolean;
}

/**
 * Create a simple function-based helper
 * @param fn - Helper function
 * @returns Helper definition
 */
function helper(fn: (params: any[], hash: object) => any): HelperDefinition;

/**
 * Set custom helper manager for advanced helper behavior
 * @param manager - Helper manager factory
 * @param helperDefinition - Helper to manage
 * @returns Helper with manager
 */
function setHelperManager(
  manager: (owner: Owner) => HelperManager, 
  helperDefinition: HelperDefinition
): HelperDefinition;

/**
 * Invoke a helper programmatically
 * @param helper - Helper to invoke
 * @param args - Helper arguments
 * @returns Helper result
 */
function invokeHelper(helper: HelperDefinition, args: HelperArgs): any;

/**
 * Define capabilities for a helper manager
 * @param version - Manager API version
 * @param options - Capability options
 * @returns Capabilities object
 */
function capabilities(version: string, options?: HelperCapabilityOptions): HelperCapabilities;

import { helper } from "@ember/helper";
import Helper from "@ember/helper";
import { service } from "@ember/service";

// Simple function helper
export const formatCurrency = helper(function([amount, currency = 'USD']) {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: currency
  }).format(amount);
});

// Class-based helper with services
export default class AsyncDataHelper extends Helper {
  @service store;
  
  compute([modelName, id]) {
    return this.store.findRecord(modelName, id);
  }
}

// Template usage:
// {{format-currency 29.99 "EUR"}}
// {{async-data "user" userId}}

interface TemplateOptions {
  moduleName?: string;
  strictMode?: boolean;
  scope?(): Record<string, unknown>;
  eval?(): unknown;
  component?: ComponentClass;
}

interface CompileOptions {
  moduleName?: string;
  strictMode?: boolean;
}

/**
 * Create hash object from named arguments
 * Usage: {{hash name="John" age=25}}
 */
function hash(...args: any[]): object;

/**
 * Create array from arguments
 * Usage: {{array "a" "b" "c"}}
 */
function array(...items: any[]): any[];

/**
 * Concatenate values into string
 * Usage: {{concat "Hello " name "!"}}
 */
function concat(...values: any[]): string;

/**
 * Dynamic property access
 * Usage: {{get object propertyName}}
 */
function get(object: any, property: string): any;

/**
 * Bind function with arguments
 * Usage: {{fn this.handleClick user}}
 */
function fn(func: Function, ...args: any[]): Function;

/**
 * Generate unique identifier
 * Usage: {{unique-id}}
 */
function uniqueId(): string;

/**
 * Log values to console (development only)
 * Usage: {{log "Debug:" someValue}}
 */
function log(...values: any[]): void;

/**
 * Create debug breakpoint (development only)
 * Usage: {{debugger}}
 */
function debugger(): void;

/**
 * Precompile template with imports and scope resolution
 * @param template - Template string
 * @param options - Compilation options with module info
 * @returns Compiled template with metadata
 */
function precompileTemplate(template: string, options?: PrecompileTemplateOptions): CompiledTemplate;

/**
 * Transform template AST with plugins
 * @param ast - Template AST
 * @param plugins - Transform plugins to apply
 * @returns Transformed AST
 */
function transform(ast: ASTNode, plugins: TransformPlugin[]): ASTNode;

/**
 * Render template with context
 * @param template - Template to render
 * @param context - Rendering context
 * @param options - Render options
 * @returns Rendered result
 */
function render(template: Template, context: RenderContext, options?: RenderOptions): RenderResult;

/**
 * Create rendering context
 * @param self - Template context object
 * @param args - Template arguments
 * @returns Render context
 */
function createRenderContext(self: any, args?: object): RenderContext;

import { precompileTemplate } from "@ember/template-compilation";
import { setComponentTemplate } from "@ember/component";

// Build-time template compilation
const template = precompileTemplate(`
  <div class="search-results">
    {{#each this.results as |result|}}
      <SearchResult 
        @item={{result}} 
        @onSelect={{fn this.selectResult result}}
        @isSelected={{get this.selectedItems result.id}}
      />
    {{/each}}
    
    {{#unless this.results.length}}
      <div class="no-results">
        {{concat "No results found for \"" this.query "\""}}
      </div>
    {{/unless}}
  </div>
`, {
  moduleName: 'components/search-results.hbs'
});

setComponentTemplate(template, SearchResultsComponent);

interface Template {
  /** Render template with context */
  (context: RenderContext): RenderResult;
  
  /** Template metadata */
  meta?: TemplateMeta;
}

interface TemplateFactory {
  /** Create template instance */
  create(options?: object): Template;
  
  /** Template metadata */
  meta: TemplateMeta;
}

interface PrecompiledTemplate {
  /** Precompiled template data */
  id: string;
  block: string;
  meta: TemplateMeta;
}

interface CompileOptions {
  /** Module name for debugging */
  moduleName?: string;
  
  /** Whether to include source maps */
  includeSourceMaps?: boolean;
  
  /** Custom transform plugins */
  plugins?: TransformPlugin[];
  
  /** Strict mode compilation */
  strictMode?: boolean;
}

interface HelperDefinition {
  /** Helper implementation */
  [Symbol.toStringTag]: 'Helper';
}

interface HelperArgs {
  /** Positional arguments */
  positional: any[];
  
  /** Named arguments */
  named: object;
}

interface HelperManager {
  /** Create helper instance */
  createHelper(definition: HelperDefinition, args: HelperArgs): any;
  
  /** Get helper value */
  getValue(instance: any): any;
  
  /** Destroy helper instance */
  destroyHelper(instance: any): void;
}

interface HelperCapabilityOptions {
  /** Whether helper has state */
  hasValue?: boolean;
  
  /** Whether helper can be destroyed */
  hasDestructor?: boolean;
  
  /** Whether helper schedules updates */
  hasScheduledEffect?: boolean;
}

interface RenderContext {
  /** Template context object */
  self: any;
  
  /** Template arguments */
  args?: object;
  
  /** Local variables */
  locals?: object;
}

interface RenderResult {
  /** Rendered DOM nodes */
  nodes: Node[];
  
  /** Cleanup function */
  destroy(): void;
}

interface TemplateMeta {
  /** Template module name */
  moduleName?: string;
  
  /** Template scope */
  scope?: () => object;
}