/**
 * 렌더링 관련 헬퍼 함수 모듈
 *
 * DataGrid의 cellChildren, ul의 li 등 반복 컨텍스트에서
 * 자식 컴포넌트를 렌더링할 때 사용하는 헬퍼 함수들을 제공합니다.
 *
 * @packageDocumentation
 */

import React from 'react';
import { DataBindingEngine, BindingContext } from '../DataBindingEngine';
import { TranslationEngine, TranslationContext } from '../TranslationEngine';
import { ComponentDefinition } from '../DynamicRenderer';
import { responsiveManager } from '../ResponsiveManager';
import { getActionDispatcher } from '../ActionDispatcher';
import { createLogger } from '../../utils/Logger';
import { RAW_PREFIX, RAW_MARKER_START, RAW_MARKER_END, RAW_PLACEHOLDER_MARKER, isRawWrapped, unwrapRaw, containsRawMarker, wrapRawDeep } from '../rawMarkers';
import type { G7DevToolsInterface } from '../G7CoreGlobals';
import {
  evaluateConditionExpression,
  evaluateConditionBranches,
  isConditionExpression,
  isConditionBranches,
  type ConditionsProperty,
} from './ConditionEvaluator';

const logger = createLogger('RenderHelpers');

/**
 * JavaScript 리터럴 값 매핑
 *
 * resolve()가 리터럴을 컨텍스트 경로로 해석하는 것을 방지합니다.
 * undefined는 Map에서 get() 시 undefined를 반환하므로 별도 센티널 불필요 —
 * `has()`로 존재 여부를 먼저 확인하지 않고 `get() !== undefined`로 체크합니다.
 * null은 falsy이므로 undefined와 동일하게 처리됩니다.
 *
 * @since engine-v1.29.2
 */
const LITERALS = new Map<string, any>([
  ['true', true],
  ['false', false],
  ['null', null],
  // undefined는 Map.get()의 기본 반환값과 구분 불가하므로 제외
  // → resolve("undefined")는 context에 없으면 undefined 반환 → Boolean(undefined) = false (정상)
]);

/**
 * G7Core.devTools 인터페이스 가져오기
 *
 * G7DevToolsCore.getInstance() 직접 호출 대신 G7Core.devTools를 사용합니다.
 * DevTools가 비활성화되거나 초기화되지 않은 경우 안전하게 undefined 반환
 */
function getDevTools(): G7DevToolsInterface | undefined {
  try {
    const G7Core = (window as any).G7Core;
    return G7Core?.devTools;
  } catch {
    return undefined;
  }
}

/**
 * 공유 DataBindingEngine 인스턴스
 *
 * 표현식 평가에서 재사용하여 성능 최적화
 */
const sharedBindingEngine = new DataBindingEngine();

/**
 * renderItemChildren 함수 옵션
 */
export interface RenderItemChildrenOptions {
  /**
   * TranslationContext - 다국어 번역에 필요
   */
  translationContext?: TranslationContext;

  /**
   * DataBindingEngine 인스턴스 - 미제공 시 새로 생성
   */
  bindingEngine?: DataBindingEngine;

  /**
   * TranslationEngine 인스턴스 - 미제공 시 싱글톤 사용
   */
  translationEngine?: TranslationEngine;

  /**
   * ActionDispatcher 인스턴스 - 미제공 시 싱글톤 사용
   * CardGrid, DataGrid 등 composite 컴포넌트에서 actions 바인딩에 필요
   */
  actionDispatcher?: any;

  /**
   * 부모 컴포넌트 컨텍스트 (state, setState)
   *
   * expandChildren 등에서 부모 컴포넌트의 로컬 상태를 업데이트할 때 사용합니다.
   * 이 컨텍스트가 전달되면 G7Core.state.setLocal()이 부모의 dynamicState를 업데이트합니다.
   */
  componentContext?: { state?: any; setState?: (updates: any) => void };

  /**
   * remount 키 생성 함수
   *
   * DynamicRenderer의 getRemountKey 함수를 전달받아 cellChildren에서도
   * remount 핸들러가 작동하도록 지원합니다.
   *
   * @param componentId - 컴포넌트 ID
   * @param fallbackKey - ID가 없을 때 사용할 기본 키
   * @returns React key로 사용할 문자열
   */
  getRemountKey?: (componentId: string | undefined, fallbackKey: string) => string;
}

/**
 * 복잡한 표현식 여부 감지
 *
 * 삼항 연산자(?:), 논리 연산자(&&, ||), 비교 연산자, 함수 호출,
 * 배열/객체 리터럴 등이 포함된 경우 true 반환
 *
 * true 인 경우 evaluateExpression(JS 평가)로, false 인 경우 resolve(dot/bracket
 * path 탐색)로 라우팅된다.
 *
 * `[`/`]`/`{`/`}` 포함 (@since engine-v1.50.0):
 *   `{{['a','b']}}` 같은 배열 리터럴이나 `{{[{...}]}}` 같은 객체 리터럴이
 *   "단순 경로"로 오판되어 resolve() 경로탐색 → undefined 가 되던 문제를 해결한다.
 *   순수 숫자 대괄호 인덱싱(`items[0]`, `entry[1]`)은 resolve()/evaluateExpression()
 *   양 경로의 결과가 동일하므로(회귀 테스트로 입증) 경로 이동에 따른 동작 변화가 없다.
 *
 * @param expr - 검사할 표현식
 * @returns 복잡한 표현식 여부
 */
function isComplexExpression(expr: string): boolean {
  // () 추가: $localized(menu.name) 같은 함수 호출 표현식도 복잡한 표현식으로 처리
  // []{} 추가: 배열/객체 리터럴(`['a','b']`, `[{...}]`)을 evaluateExpression 으로 라우팅
  return /[?:|&!+\-*/<>=()[\]{}]/.test(expr);
}

/**
 * 단일 바인딩 표현식 추출
 *
 * `{{expression}}` 형태에서 expression 부분만 추출합니다.
 * 문자열 리터럴 내부의 `}` 문자를 올바르게 처리합니다.
 *
 * @param value - 검사할 문자열
 * @returns 추출된 표현식 또는 null (유효하지 않은 경우)
 *
 * @example
 * ```typescript
 * extractSingleBinding("{{row.name}}") // "row.name"
 * extractSingleBinding("{{row.status === 'active' ? 'yes' : 'no'}}") // "row.status === 'active' ? 'yes' : 'no'"
 * extractSingleBinding("hello {{name}}") // null (단일 바인딩이 아님)
 * ```
 */
function extractSingleBinding(value: string): string | null {
  if (!value.startsWith('{{') || !value.endsWith('}}')) {
    return null;
  }

  const inner = value.slice(2, -2);
  let inString: string | null = null;
  let braceCount = 0;

  for (let i = 0; i < inner.length; i++) {
    const char = inner[i];
    const prevChar = i > 0 ? inner[i - 1] : '';

    // 이스케이프 문자 처리
    if (prevChar === '\\') continue;

    // 문자열 시작/종료 감지 (따옴표 추적)
    if ((char === '"' || char === "'") && !inString) {
      inString = char;
    } else if (char === inString) {
      inString = null;
    }

    // 문자열 외부에서만 중괄호 카운트
    if (!inString) {
      if (char === '{') braceCount++;
      if (char === '}') braceCount--;
      if (braceCount < 0) return null;
    }
  }

  return braceCount === 0 ? inner.trim() : null;
}

/**
 * iteration source 표현식을 평가하여 배열을 반환합니다.
 *
 * 단순 경로(`users.data`)와 복잡한 표현식(`roles?.data ?? []`) 모두 지원합니다.
 * 표현식 여부에 따라 적절한 평가 방식을 선택하여 원본 타입(배열)을 반환합니다.
 *
 * @param source - iteration source 문자열 (예: "roles?.data ?? []", "users.data")
 * @param context - 데이터 컨텍스트
 * @param bindingEngine - DataBindingEngine 인스턴스
 * @returns 평가된 배열 또는 원본 값
 *
 * @example
 * ```typescript
 * // 복잡한 표현식
 * const data = resolveIterationSource("roles?.data ?? []", context, bindingEngine);
 * // 결과: [{id: 1, name: "admin"}, ...]
 *
 * // 단순 경로
 * const data = resolveIterationSource("users.data", context, bindingEngine);
 * // 결과: [{id: 1, name: "홍길동"}, ...]
 * ```
 */
export function resolveIterationSource(
  source: string,
  context: BindingContext,
  bindingEngine: DataBindingEngine
): any {
  // {{...}} 형식의 표현식에서 중괄호 제거
  let normalizedSource = source;
  if (source.startsWith('{{') && source.endsWith('}}')) {
    normalizedSource = source.slice(2, -2).trim();
  }

  // 표현식 여부 확인 (?, :, ||, &&, !, 산술/비교 연산자 등)
  if (isComplexExpression(normalizedSource)) {
    // 표현식인 경우 evaluateExpression 사용 (원본 타입 유지)
    try {
      return bindingEngine.evaluateExpression(normalizedSource, context);
    } catch (error) {
      logger.warn(`resolveIterationSource: 표현식 평가 실패: ${source}`, error);
      return undefined;
    }
  }

  // 단순 경로인 경우 resolve 사용
  return bindingEngine.resolve(normalizedSource, context, { skipCache: true });
}

/**
 * 격리된 상태 컨텍스트 인터페이스
 */
export interface IsolatedContextValue {
  state: Record<string, any>;
  setState: (path: string, value: any) => void;
  getState: (path: string) => any;
  mergeState: (updates: Record<string, any>) => void;
}

/**
 * 컴포넌트 컨텍스트 인터페이스
 */
export interface ComponentContext {
  state?: Record<string, any>;
  setState?: (updates: any) => void;
  isolatedContext?: IsolatedContextValue | null;
  /** 부모 DynamicRenderer의 전체 데이터 컨텍스트 (데이터소스 포함) @since engine-v1.19.1 */
  parentDataContext?: Record<string, any>;
}

/**
 * 효과적인 데이터 컨텍스트를 생성합니다.
 *
 * baseContext에 componentContext의 상태를 병합하여 바인딩에 사용할 수 있는
 * 완전한 컨텍스트를 생성합니다. _local, _global, _isolated 상태를 모두 포함합니다.
 *
 * @param baseContext - 기본 데이터 컨텍스트 (_local, _global 등 포함)
 * @param componentContext - 컴포넌트별 로컬 상태 및 격리 상태 컨텍스트
 * @returns 병합된 효과적인 컨텍스트
 *
 * @example
 * ```typescript
 * const effectiveContext = getEffectiveContext(
 *   { _local: { user: {...} }, _global: { settings: {...} } },
 *   { state: { filter: 'active' }, isolatedContext: { state: { step: 1 } } }
 * );
 * // 결과: {
 * //   _local: { user: {...}, filter: 'active' },
 * //   _global: { settings: {...} },
 * //   _isolated: { step: 1 }
 * // }
 * ```
 */
export function getEffectiveContext(
  baseContext: Record<string, any>,
  componentContext?: ComponentContext
): Record<string, any> {
  const result = { ...baseContext };

  // 부모 데이터 컨텍스트 병합 (engine-v1.19.1)
  // DataGrid 등 복합 컴포넌트의 cellChildren/footerCells/footerCardChildren에서
  // 데이터소스(order, active_carriers 등)에 접근할 수 있도록 최상위 컨텍스트에 병합.
  // 기존 baseContext 키(row, value, $value 등)를 덮어쓰지 않음.
  if (componentContext?.parentDataContext) {
    for (const [key, value] of Object.entries(componentContext.parentDataContext)) {
      if (!(key in result)) {
        result[key] = value;
      }
    }
  }

  // componentContext.state를 _local에 병합
  if (componentContext?.state) {
    const existingLocal = result._local || {};
    result._local = {
      ...existingLocal,
      ...componentContext.state,
    };
  }

  // isolatedContext.state를 _isolated에 포함
  if (componentContext?.isolatedContext?.state) {
    result._isolated = componentContext.isolatedContext.state;
  }

  return result;
}

/**
 * bindComponentActions 옵션
 */
export interface BindComponentActionsOptions {
  /**
   * 컴포넌트 컨텍스트 (state, setState, isolatedContext)
   * DynamicRenderer에서 컴포넌트 로컬 상태 관리에 사용
   */
  componentContext?: {
    state?: any;
    setState?: (updates: any) => void;
    /** 격리된 상태 컨텍스트 (isolatedState 속성이 있는 컴포넌트에서 제공) */
    isolatedContext?: IsolatedContextValue | null;
  };

  /**
   * ActionDispatcher 인스턴스
   * 미제공 시 getActionDispatcher() 싱글톤 사용
   * DynamicRenderer에서는 props로 전달받은 인스턴스 사용 권장
   */
  actionDispatcher?: any;
}

/**
 * 컴포넌트의 actions 배열을 props에 바인딩합니다.
 *
 * DynamicRenderer의 액션 바인딩 로직과 동일한 패턴을 사용합니다.
 * actions 배열을 이벤트 핸들러(onClick, onChange 등)로 변환합니다.
 *
 * 코드 중복을 최소화하기 위해 공유 유틸리티로 추출되었습니다.
 * DynamicRenderer와 renderItemChildren에서 동일하게 사용됩니다.
 *
 * @param props - 기존 props 객체
 * @param actions - 액션 정의 배열
 * @param context - 데이터 컨텍스트
 * @param options - 추가 옵션 (componentContext 등)
 * @returns 이벤트 핸들러가 바인딩된 props 객체 (actions prop 제거됨)
 *
 * @example
 * ```typescript
 * const actions = [{ type: 'click', handler: 'openModal', target: 'myModal' }];
 * const boundProps = bindComponentActions({ className: 'btn' }, actions, { row: {...} });
 * // 결과: { className: 'btn', onClick: [Function] }
 * ```
 */
export function bindComponentActions(
  props: Record<string, any>,
  actions: any[] | undefined,
  context: Record<string, any>,
  options?: BindComponentActionsOptions
): Record<string, any> {
  if (!actions || !Array.isArray(actions) || actions.length === 0) {
    return props;
  }

  // options에서 전달된 actionDispatcher를 우선 사용, 없으면 싱글톤 사용
  const actionDispatcher = options?.actionDispatcher ?? getActionDispatcher();
  const propsWithActions = { ...props, actions };
  const boundProps = actionDispatcher.bindActionsToProps(
    propsWithActions,
    context,
    options?.componentContext
  );
  // actions prop 제거 (HTML 속성으로 렌더링되지 않도록)
  delete boundProps.actions;

  return boundProps;
}

/**
 * 조건부 렌더링 평가 함수
 *
 * DynamicRenderer의 shouldRender 로직과 동일한 패턴을 사용합니다.
 * `if` 속성을 평가하여 컴포넌트를 렌더링할지 결정합니다.
 *
 * 코드 중복을 최소화하기 위해 공유 유틸리티로 추출되었습니다.
 * DynamicRenderer와 renderItemChildren에서 동일하게 사용됩니다.
 *
 * @param ifCondition - if 속성 값 (예: "{{row.status == 'active'}}")
 * @param context - 데이터 컨텍스트
 * @param bindingEngine - DataBindingEngine 인스턴스
 * @param componentId - 컴포넌트 ID (디버깅용, 선택)
 * @returns 렌더링 여부 (true: 렌더링, false: 숨김)
 *
 * @example
 * ```typescript
 * // 단순 조건
 * evaluateIfCondition("{{row.active}}", { row: { active: true } }, bindingEngine)
 * // 결과: true
 *
 * // 비교 조건
 * evaluateIfCondition("{{row.status == 'active'}}", { row: { status: 'active' } }, bindingEngine)
 * // 결과: true
 *
 * // falsy 값
 * evaluateIfCondition("{{row.count}}", { row: { count: 0 } }, bindingEngine)
 * // 결과: false
 * ```
 */
export function evaluateIfCondition(
  ifCondition: string | boolean | undefined,
  context: BindingContext,
  bindingEngine: DataBindingEngine,
  componentId?: string
): boolean {
  // boolean 값이 이미 해석된 경우 (엔진 prop 사전 해석으로 condition이 boolean이 될 수 있음)
  if (typeof ifCondition === 'boolean') {
    return ifCondition;
  }

  // if 조건이 없으면 항상 렌더링
  if (!ifCondition) {
    return true;
  }

  try {
    // {{variable}} 형태의 단일 바인딩인지 체크
    const singleBindingPath = extractSingleBinding(ifCondition);

    let resolved: any;
    if (singleBindingPath !== null) {
      // JavaScript 리터럴 값 직접 처리 (resolve 경로 탐색 방지) @since engine-v1.29.2
      const literal = LITERALS.get(singleBindingPath);
      if (literal !== undefined) {
        resolved = literal;
      } else if (isComplexExpression(singleBindingPath)) {
        // Optional chaining(?.)이나 복잡한 표현식은 evaluateExpression 사용
        resolved = bindingEngine.evaluateExpression(singleBindingPath, context);
      } else {
        // 단순 경로는 resolve 메서드 사용 (원본 타입 유지)
        resolved = bindingEngine.resolve(singleBindingPath, context, { skipCache: true });
      }
    } else {
      // 문자열 보간인 경우 resolveBindings 사용
      resolved = bindingEngine.resolveBindings(ifCondition, context, { skipCache: true });
    }

    // 문자열 "false", "0", "", "null", "undefined"를 false로 처리
    if (typeof resolved === 'string') {
      const lowerResolved = resolved.toLowerCase().trim();
      if (lowerResolved === 'false' || lowerResolved === '0' || lowerResolved === '' ||
          lowerResolved === 'null' || lowerResolved === 'undefined') {
        return false;
      }
    }

    // 결과를 boolean으로 변환
    return Boolean(resolved);
  } catch (error) {
    logger.warn(
      `evaluateIfCondition: 조건 평가 실패 (컴포넌트: ${componentId || 'unknown'}):`,
      error
    );
    return false;
  }
}

/**
 * 컴포넌트 렌더링 조건 옵션
 */
export interface EvaluateRenderConditionOptions {
  /**
   * if 속성 (기존 단일 조건, 하위 호환)
   */
  if?: string;

  /**
   * condition 속성 (if의 별칭 — 컴포넌트 내부 children에서 관례적으로 사용)
   * @since engine-v1.17.1
   */
  condition?: string | boolean;

  /**
   * conditions 속성 (AND/OR 그룹 또는 if/else 체인)
   */
  conditions?: ConditionsProperty;
}

/**
 * 컴포넌트의 렌더링 조건을 평가합니다 (if 또는 conditions)
 *
 * `if` 속성과 `conditions` 속성을 모두 지원합니다.
 * - `if`: 기존 단일 조건 (하위 호환)
 * - `conditions`: AND/OR 그룹 또는 if/else 체인
 *
 * 우선순위: `if` 속성이 있으면 먼저 평가, 없으면 `conditions` 평가
 *
 * @param componentDef - 컴포넌트 정의 또는 조건 옵션 ({ if?, conditions? })
 * @param context - 데이터 컨텍스트
 * @param bindingEngine - DataBindingEngine 인스턴스
 * @param componentId - 컴포넌트 ID (디버깅용, 선택)
 * @returns 렌더링 여부 (true: 렌더링, false: 숨김)
 *
 * @example
 * ```typescript
 * // 기존 if 조건 (하위 호환)
 * evaluateRenderCondition(
 *   { if: "{{user.isAdmin}}" },
 *   context,
 *   bindingEngine
 * ); // → true/false
 *
 * // AND 그룹 조건
 * evaluateRenderCondition(
 *   { conditions: { and: ["{{route.id}}", "{{form_data?.data?.author}}"] } },
 *   context,
 *   bindingEngine
 * ); // → 모든 조건이 true일 때만 true
 *
 * // OR 그룹 조건
 * evaluateRenderCondition(
 *   { conditions: { or: ["{{user.isAdmin}}", "{{user.isManager}}"] } },
 *   context,
 *   bindingEngine
 * ); // → 하나라도 true면 true
 *
 * // if/else 체인 (컴포넌트에서 하나라도 true면 렌더링)
 * evaluateRenderCondition(
 *   {
 *     conditions: [
 *       { if: "{{user.role === 'admin'}}" },
 *       { if: "{{user.role === 'manager'}}" }
 *     ]
 *   },
 *   context,
 *   bindingEngine
 * ); // → 어느 조건이라도 true면 렌더링
 * ```
 */
export function evaluateRenderCondition(
  componentDef: EvaluateRenderConditionOptions,
  context: BindingContext,
  bindingEngine: DataBindingEngine,
  componentId?: string
): boolean {
  // 1. 기존 if 속성 우선 (하위 호환)
  if (componentDef.if !== undefined) {
    return evaluateIfCondition(componentDef.if, context, bindingEngine, componentId);
  }

  // 1-1. condition 속성 (if의 별칭 — 컴포넌트 내부 children에서 관례적 사용)
  if (componentDef.condition !== undefined) {
    return evaluateIfCondition(componentDef.condition, context, bindingEngine, componentId);
  }

  // 2. conditions 속성이 없으면 항상 렌더링
  if (componentDef.conditions === undefined) {
    return true;
  }

  const conditions = componentDef.conditions;

  try {
    // 3. 단일 ConditionExpression (문자열, AND, OR)
    if (isConditionExpression(conditions)) {
      return evaluateConditionExpression(conditions, context, bindingEngine);
    }

    // 4. ConditionBranch[] (if/else 체인)
    if (isConditionBranches(conditions)) {
      const result = evaluateConditionBranches(conditions, context, bindingEngine);
      // 컴포넌트에서는 하나라도 매칭되면 렌더링
      return result.matched;
    }

    // 알 수 없는 형식
    logger.warn(
      `evaluateRenderCondition: 알 수 없는 conditions 형식 (컴포넌트: ${componentId || 'unknown'})`
    );
    return true;
  } catch (error) {
    logger.warn(
      `evaluateRenderCondition: conditions 평가 실패 (컴포넌트: ${componentId || 'unknown'}):`,
      error
    );
    return false;
  }
}

/**
 * 컴포넌트 정의에 반응형 오버라이드를 적용합니다.
 *
 * responsive 속성이 있으면 현재 화면 너비에 맞는 오버라이드를 적용합니다.
 * DynamicRenderer의 effectiveComponentDef 로직과 동일한 패턴을 사용합니다.
 *
 * @param componentDef - 원본 컴포넌트 정의
 * @returns 반응형 오버라이드가 적용된 컴포넌트 정의
 */
function applyResponsiveOverrides(componentDef: ComponentDefinition): ComponentDefinition {
  if (!componentDef.responsive) {
    return componentDef;
  }

  const currentWidth = responsiveManager.getWidth();
  const matchedKey = responsiveManager.getMatchingKey(componentDef.responsive, currentWidth);

  if (!matchedKey) {
    return componentDef;
  }

  const override = componentDef.responsive[matchedKey];
  return {
    ...componentDef,
    // props는 얕은 머지 (지정한 속성만 대체, 미지정 속성 유지)
    props: { ...componentDef.props, ...override.props },
    // children, text, if, iteration은 완전 교체
    children: override.children ?? componentDef.children,
    text: override.text ?? componentDef.text,
    if: override.if ?? componentDef.if,
    iteration: override.iteration ?? componentDef.iteration,
  };
}

/**
 * 반복 아이템의 자식 컴포넌트를 렌더링합니다.
 *
 * DataGrid의 cellChildren, ul의 li 등 반복 컨텍스트에서
 * 자식 컴포넌트를 렌더링할 때 사용합니다.
 *
 * 템플릿 엔진의 바인딩, 표현식 평가, 다국어 번역 등
 * 모든 기능을 지원합니다.
 *
 * @param children - 렌더링할 컴포넌트 정의 배열
 * @param itemContext - 반복 아이템 컨텍스트 (row, item, value, index 등)
 * @param componentMap - 컴포넌트 맵 (ComponentRegistry에서 가져온 컴포넌트들)
 * @param keyPrefix - React key 접두사 (선택)
 * @param options - 추가 옵션 (translationContext, bindingEngine 등)
 * @returns React 노드 배열
 *
 * @example
 * ```tsx
 * // DataGrid에서 cellChildren 렌더링
 * const renderedChildren = renderItemChildren(
 *   cellChildren,
 *   { row, value, index },
 *   componentMap,
 *   `cell-${index}`
 * );
 *
 * // ul에서 li 아이템 렌더링
 * const listItems = renderItemChildren(
 *   itemChildren,
 *   { item, index },
 *   componentMap,
 *   `list-item-${index}`
 * );
 * ```
 */
export function renderItemChildren(
  children: ComponentDefinition[],
  itemContext: Record<string, any>,
  componentMap: Record<string, React.ComponentType<any>>,
  keyPrefix?: string,
  options?: RenderItemChildrenOptions
): React.ReactNode[] {
  if (!children || children.length === 0) {
    return [];
  }

  // 엔진 인스턴스 확인 - 없으면 새로 생성
  const bindingEngine = options?.bindingEngine ?? new DataBindingEngine();
  const translationEngine = options?.translationEngine ?? TranslationEngine.getInstance();
  const translationContext = options?.translationContext ?? {
    templateId: '',
    locale: 'ko',
  };

  // Phase 1-1: componentContext가 있으면 자동으로 state를 _local에 병합
  // Phase 2: isolatedContext.state를 _isolated에 포함
  // 이전에는 DataGrid 등에서 수동으로 수행하던 로직
  const effectiveContext = getEffectiveContext(itemContext, options?.componentContext);

  /**
   * props 값을 바인딩/표현식 평가하여 해석
   * 반복 렌더링이므로 캐시를 사용하지 않음 (같은 경로가 다른 row에서 다른 값을 가져야 함)
   */
  const resolveValue = (value: any, context: Record<string, any>): any => {
    if (typeof value === 'string') {
      // raw 마커: 번역 면제 — 마커 제거 후 원본 반환
      // @since engine-v1.27.0
      if (isRawWrapped(value)) {
        return unwrapRaw(value);
      }

      // 혼합 보간 시 raw 마커 영역 보호
      // @since engine-v1.27.0
      if (containsRawMarker(value)) {
        const rawSegments: string[] = [];
        const protectedValue = value.replace(
          new RegExp(`${RAW_MARKER_START}([^${RAW_MARKER_END}]*)${RAW_MARKER_END}`, 'g'),
          (_m: string, content: string) => {
            rawSegments.push(content);
            return `${RAW_PLACEHOLDER_MARKER}${rawSegments.length - 1}${RAW_PLACEHOLDER_MARKER}`;
          }
        );
        let translated = protectedValue;
        if (/\$t:[a-zA-Z0-9._-]+/.test(protectedValue)) {
          translated = translationEngine.resolveTranslations(
            protectedValue,
            translationContext,
            context
          );
        }
        return translated.replace(
          new RegExp(`${RAW_PLACEHOLDER_MARKER}(\\d+)${RAW_PLACEHOLDER_MARKER}`, 'g'),
          (_m: string, idx: string) => rawSegments[parseInt(idx)]
        );
      }

      // 다국어 번역
      // $t:defer: prefix는 DynamicRenderer에서 건너뛰고 여기서 처리됨
      // defer: 부분을 제거하고 일반 $t: 번역으로 처리
      if (value.startsWith('$t:defer:')) {
        const normalizedValue = '$t:' + value.slice(9); // '$t:defer:'.length === 9
        return translationEngine.resolveTranslations(
          normalizedValue,
          translationContext,
          context
        );
      }
      if (value.startsWith('$t:')) {
        return translationEngine.resolveTranslations(
          value,
          translationContext,
          context
        );
      }

      // 단일 바인딩 표현식
      const singleBindingPath = extractSingleBinding(value);
      if (singleBindingPath !== null) {
        // raw: 접두사 감지 @since engine-v1.27.0
        let isRawBinding = false;
        let effectivePath = singleBindingPath;
        if (singleBindingPath.startsWith(RAW_PREFIX)) {
          isRawBinding = true;
          effectivePath = singleBindingPath.slice(RAW_PREFIX.length);
        }

        let result;
        if (isComplexExpression(effectivePath)) {
          try {
            result = bindingEngine.evaluateExpression(effectivePath, context);
          } catch (error) {
            logger.warn('renderItemChildren: 표현식 평가 실패:', error);
            return undefined;
          }
        } else {
          // skipCache: true - 반복 렌더링에서 같은 경로가 다른 값을 가져야 함
          result = bindingEngine.resolve(effectivePath, context, { skipCache: true });
        }

        // 표현식 평가 결과가 $t: 접두사 문자열이면 번역 처리
        // 예: {{row.published ? '$t:module.key.published' : '$t:module.key.unpublished'}}
        // → 평가 결과 "$t:module.key.published"를 번역하여 "발행" 반환
        // @since engine-v1.28.1
        if (!isRawBinding && typeof result === 'string' && /\$t:[a-zA-Z0-9._-]+/.test(result)) {
          result = translationEngine.resolveTranslations(
            result,
            translationContext,
            context
          );
        }

        return isRawBinding && result != null ? wrapRawDeep(result) : result;
      }

      // 문자열 보간
      if (value.includes('{{')) {
        // skipCache: true - 반복 렌더링에서 같은 경로가 다른 값을 가져야 함
        const interpolated = bindingEngine.resolveBindings(value, context, { skipCache: true });
        // 보간 결과에 $t: 접두사가 포함되면 번역 처리 @since engine-v1.28.1
        if (typeof interpolated === 'string' && /\$t:[a-zA-Z0-9._-]+/.test(interpolated)) {
          return translationEngine.resolveTranslations(
            interpolated,
            translationContext,
            context
          );
        }
        return interpolated;
      }

      return value;
    }

    if (Array.isArray(value)) {
      return value.map((item) => resolveValue(item, context));
    }

    if (value && typeof value === 'object') {
      const resolved: Record<string, any> = {};
      for (const [k, v] of Object.entries(value)) {
        resolved[k] = resolveValue(v, context);
      }
      return resolved;
    }

    return value;
  };

  /**
   * 컴포넌트 정의의 props를 해석
   */
  const resolveProps = (
    props: Record<string, any> | undefined,
    context: Record<string, any>
  ): Record<string, any> => {
    if (!props) return {};

    const resolved: Record<string, any> = {};
    for (const [key, value] of Object.entries(props)) {
      resolved[key] = resolveValue(value, context);
    }
    return resolved;
  };

  /**
   * iteration이 있는 컴포넌트 렌더링
   * source 배열의 각 아이템에 대해 컴포넌트를 반복 렌더링
   */
  const renderWithIteration = (
    originalChildDef: ComponentDefinition,
    baseKey: string,
    baseContext: Record<string, any>
  ): React.ReactNode[] => {
    // 반응형 오버라이드 적용
    const childDef = applyResponsiveOverrides(originalChildDef);

    const iteration = childDef.iteration as { source: string; item_var: string; index_var?: string } | undefined;
    if (!iteration) return [];

    // source 경로에서 배열 가져오기 (표현식 지원)
    const sourceArray = resolveIterationSource(iteration.source, baseContext, bindingEngine);

    if (!Array.isArray(sourceArray)) {
      logger.warn(`renderItemChildren: iteration.source가 배열이 아닙니다: ${iteration.source}`);
      return [];
    }

    // DevTools: iteration 추적
    const devTools = getDevTools();
    if (devTools?.isEnabled()) {
      const iterationId = `${baseKey}-iteration`;
      devTools.trackIteration(
        iterationId,
        iteration.source,
        iteration.item_var,
        iteration.index_var,
        sourceArray.length
      );
    }

    // 컴포넌트 조회
    const Component = componentMap[childDef.name];
    if (!Component) {
      logger.warn(`renderItemChildren: 컴포넌트를 찾을 수 없습니다: ${childDef.name}`);
      return [];
    }

    // 각 아이템에 대해 컴포넌트 렌더링 (if 조건 실패 시 필터링)
    return sourceArray.flatMap((item: any, itemIndex: number) => {
      // 컨텍스트에 iteration 변수 추가
      // index_var가 지정되어 있으면 해당 이름 사용, 아니면 기본 패턴(item_var + _index) 사용
      const iterationContext = {
        ...baseContext,
        [iteration.item_var]: item,
        [`${iteration.item_var}_index`]: itemIndex,
        // index_var가 명시적으로 지정된 경우 해당 이름으로도 인덱스 추가
        ...(iteration.index_var ? { [iteration.index_var]: itemIndex } : {}),
      };

      // if/condition/conditions 조건 평가 - 조건이 false이면 렌더링하지 않음
      const shouldRender = evaluateRenderCondition(
        { if: childDef.if, condition: childDef.condition, conditions: childDef.conditions },
        iterationContext,
        bindingEngine,
        childDef.id
      );

      // DevTools: if 조건 추적 (iteration 내부)
      // TODO: conditions 속성은 DevTools Phase 5에서 별도 추적 구현 예정
      if (childDef.if && devTools?.isEnabled()) {
        const conditionId = `${baseKey}-iter-${itemIndex}-if`;
        devTools.trackIfCondition(conditionId, childDef.if, shouldRender, childDef.name);
      }

      if (!shouldRender) {
        return [];
      }

      // remount 지원: getRemountKey가 제공되면 사용, 아니면 기본 키 생성
      // childDef.id의 표현식을 해석 (예: "toggle_{{row.id}}" → "toggle_3")
      const resolvedIterationId = childDef.id ? String(resolveValue(childDef.id, iterationContext)) : undefined;
      const iterationFallbackKey = `${baseKey}-iter-${itemIndex}`;
      const iterationKey = options?.getRemountKey
        ? options.getRemountKey(resolvedIterationId, iterationFallbackKey)
        : iterationFallbackKey;

      // props 해석
      const resolvedProps = resolveProps(childDef.props, iterationContext);

      // actions 바인딩 (DynamicRenderer와 동일한 패턴)
      const finalProps = bindComponentActions(resolvedProps, childDef.actions, iterationContext, {
        actionDispatcher: options?.actionDispatcher,
        componentContext: options?.componentContext,
      });

      // text 처리
      let childrenNodes: React.ReactNode = null;
      if (childDef.text !== undefined) {
        childrenNodes = resolveValue(childDef.text, iterationContext);
      } else if (childDef.children && childDef.children.length > 0) {
        childrenNodes = renderItemChildren(
          childDef.children as ComponentDefinition[],
          iterationContext,
          componentMap,
          iterationKey,
          options
        );
      }

      // DevTools: 컴포넌트 렌더링 추적 (iteration 내부)
      if (devTools?.isEnabled()) {
        devTools.trackRender(childDef.name);
      }

      return [React.createElement(Component, { key: iterationKey, ...finalProps }, childrenNodes)];
    });
  };

  /**
   * 자식 컴포넌트 렌더링
   * Phase 1-1: effectiveContext 사용 (componentContext.state가 _local에 자동 병합됨)
   */
  return children.flatMap((originalChildDef, index) => {
    // 반응형 오버라이드 적용
    const childDef = applyResponsiveOverrides(originalChildDef);

    // remount 지원: getRemountKey가 제공되면 사용, 아니면 기본 키 생성
    // childDef.id의 표현식을 해석 (예: "toggle_{{row.id}}" → "toggle_3")
    const resolvedId = childDef.id ? String(resolveValue(childDef.id, effectiveContext)) : undefined;
    const fallbackKey = keyPrefix ? `${keyPrefix}-${resolvedId || index}` : (resolvedId || `child-${index}`);
    const key = options?.getRemountKey
      ? options.getRemountKey(resolvedId, fallbackKey)
      : fallbackKey;

    // iteration이 있는 경우 반복 렌더링
    // if 조건은 renderWithIteration 내부에서 각 아이템 컨텍스트로 평가됨
    if (childDef.iteration) {
      return renderWithIteration(childDef, key, effectiveContext);
    }

    // if/condition/conditions 조건 평가 - 조건이 false이면 렌더링하지 않음
    // iteration이 없는 경우에만 여기서 평가
    const shouldRender = evaluateRenderCondition(
      { if: childDef.if, condition: childDef.condition, conditions: childDef.conditions },
      effectiveContext,
      bindingEngine,
      childDef.id
    );

    // DevTools: if 조건 추적 (일반 컴포넌트)
    // TODO: conditions 속성은 DevTools Phase 5에서 별도 추적 구현 예정
    const devTools = getDevTools();
    if (childDef.if && devTools?.isEnabled()) {
      const conditionId = `${key}-if`;
      devTools.trackIfCondition(conditionId, childDef.if, shouldRender, childDef.name);
    }

    if (!shouldRender) {
      return [];
    }

    // 컴포넌트 조회
    const Component = componentMap[childDef.name];
    if (!Component) {
      logger.warn(`renderItemChildren: 컴포넌트를 찾을 수 없습니다: ${childDef.name}`);
      return [];
    }

    // props 해석
    const resolvedProps = resolveProps(childDef.props, effectiveContext);

    // actions 바인딩 (DynamicRenderer와 동일한 패턴)
    const finalProps = bindComponentActions(resolvedProps, childDef.actions, effectiveContext, {
      actionDispatcher: options?.actionDispatcher,
      componentContext: options?.componentContext,
    });

    // text 처리
    let childrenNodes: React.ReactNode = null;
    if (childDef.text !== undefined) {
      childrenNodes = resolveValue(childDef.text, effectiveContext);
    } else if (childDef.children && childDef.children.length > 0) {
      // 재귀적으로 자식 렌더링
      childrenNodes = renderItemChildren(
        childDef.children as ComponentDefinition[],
        effectiveContext,
        componentMap,
        key,
        options
      );
    }

    // DevTools: 컴포넌트 렌더링 추적 (일반 컴포넌트)
    if (devTools?.isEnabled()) {
      devTools.trackRender(childDef.name);
    }

    return [React.createElement(Component, { key, ...finalProps }, childrenNodes)];
  });
}

/**
 * 문자열 내의 모든 바인딩 표현식을 컨텍스트 데이터로 치환
 *
 * 단순 변수({{route.id}})뿐 아니라 복잡한 표현식({{route?.id}}, {{a ? b : c}})도 지원합니다.
 * 코드 중복을 피하기 위해 DataBindingEngine의 기능을 재사용합니다.
 *
 * @param template 바인딩 표현식이 포함된 문자열 (예: "/api/users/{{route?.id}}")
 * @param context 데이터 컨텍스트 (예: { route: { id: "123" } })
 * @param bindingEngine DataBindingEngine 인스턴스 (선택, 미제공 시 공유 인스턴스 사용)
 * @returns 치환된 문자열 (예: "/api/users/123")
 *
 * @example
 * ```typescript
 * // 단순 변수 치환
 * resolveExpressionString("/api/users/{{route.id}}", { route: { id: "123" } });
 * // 결과: "/api/users/123"
 *
 * // Optional chaining 지원
 * resolveExpressionString("/api/users/{{route?.id}}", { route: { id: "456" } });
 * // 결과: "/api/users/456"
 *
 * // 복잡한 표현식 지원
 * resolveExpressionString("{{isEdit ? 'update' : 'create'}}", { isEdit: true });
 * // 결과: "update"
 * ```
 */
/**
 * 표현식 해석 옵션
 */
export interface ResolveExpressionOptions {
  /**
   * 캐시 사용 안 함 (기본값: false)
   * true로 설정하면 매 호출마다 새로운 컨텍스트로 평가
   */
  skipCache?: boolean;
}

export function resolveExpressionString(
  template: string,
  context: BindingContext,
  bindingEngineOrOptions?: DataBindingEngine | ResolveExpressionOptions,
  options?: ResolveExpressionOptions
): string {
  // 파라미터 오버로드 처리: (template, context, options) 또는 (template, context, bindingEngine, options)
  let engine: DataBindingEngine;
  let opts: ResolveExpressionOptions | undefined;

  if (bindingEngineOrOptions instanceof DataBindingEngine) {
    engine = bindingEngineOrOptions;
    opts = options;
  } else {
    engine = sharedBindingEngine;
    opts = bindingEngineOrOptions;
  }

  return engine.resolveBindings(template, context, opts);
}

/**
 * 객체 내의 모든 문자열 값에서 바인딩 표현식을 치환
 *
 * 중첩된 객체와 배열도 재귀적으로 처리합니다.
 *
 * @param obj 바인딩 표현식이 포함된 객체
 * @param context 데이터 컨텍스트
 * @param bindingEngine DataBindingEngine 인스턴스 (선택)
 * @returns 치환된 객체
 *
 * @example
 * ```typescript
 * resolveExpressionObject(
 *   { endpoint: "/api/users/{{route?.id}}", params: { status: "{{filter}}" } },
 *   { route: { id: "123" }, filter: "active" }
 * );
 * // 결과: { endpoint: "/api/users/123", params: { status: "active" } }
 * ```
 */
export function resolveExpressionObject<T extends Record<string, any>>(
  obj: T,
  context: BindingContext,
  bindingEngine?: DataBindingEngine
): T {
  const engine = bindingEngine ?? sharedBindingEngine;
  return engine.resolveObject(obj, context) as T;
}

/**
 * classMap 정의 인터페이스
 */
export interface ClassMapDefinition {
  /** 항상 적용되는 기본 클래스 */
  base?: string;
  /** 키 값에 따른 클래스 변형 */
  variants: Record<string, string>;
  /** 변형을 결정하는 키 표현식 (예: "{{row.status}}") */
  key: string;
  /** 매칭되는 변형이 없을 때 사용할 기본 클래스 */
  default?: string;
}

/**
 * resolveClassMap 옵션
 */
export interface ResolveClassMapOptions {
  /**
   * 캐시 사용 안 함 (기본값: true)
   *
   * iteration/cellChildren 컨텍스트에서 사용될 수 있으므로 기본적으로 캐시 비활성화
   */
  skipCache?: boolean;
}

/**
 * classMap 정의를 해석하여 CSS 클래스 문자열로 변환
 *
 * 동적 값에 따라 다른 CSS 클래스를 적용합니다.
 * 중첩 삼항 연산자를 사용하는 복잡한 className 표현식을 대체합니다.
 *
 * 트러블슈팅 주의사항:
 * - iteration 컨텍스트에서 key 평가 시 skipCache: true 적용 (각 row별 다른 값)
 * - variants 객체 자체는 정적이므로 캐싱 가능
 *
 * @param classMap classMap 정의 객체
 * @param context 데이터 컨텍스트
 * @param bindingEngine DataBindingEngine 인스턴스 (선택, 미제공 시 공유 인스턴스 사용)
 * @param options 해석 옵션
 * @returns 최종 CSS 클래스 문자열
 *
 * @example
 * ```typescript
 * const classMap = {
 *   base: "px-2 py-1 rounded-full text-xs font-medium",
 *   variants: {
 *     success: "bg-green-100 text-green-800",
 *     danger: "bg-red-100 text-red-800",
 *     warning: "bg-yellow-100 text-yellow-800"
 *   },
 *   key: "{{row.status}}",
 *   default: "bg-gray-100 text-gray-600"
 * };
 *
 * const context = { row: { status: "success" } };
 * resolveClassMap(classMap, context);
 * // 결과: "px-2 py-1 rounded-full text-xs font-medium bg-green-100 text-green-800"
 * ```
 */
export function resolveClassMap(
  classMap: ClassMapDefinition,
  context: BindingContext,
  bindingEngine?: DataBindingEngine,
  options?: ResolveClassMapOptions
): string {
  const engine = bindingEngine ?? sharedBindingEngine;
  const opts = { skipCache: true, ...options }; // 기본적으로 캐시 비활성화

  // 1. key 표현식 평가 (항상 skipCache)
  let keyValue: string;
  try {
    const resolved = engine.resolveBindings(classMap.key, context, { skipCache: opts.skipCache });
    // 빈 문자열이거나 undefined/null인 경우 처리
    keyValue = resolved?.toString()?.trim() ?? '';
  } catch (error) {
    logger.warn('resolveClassMap: key 평가 실패:', classMap.key, error);
    keyValue = '';
  }

  // 2. variants에서 매칭되는 클래스 찾기
  let variantClass = '';
  if (keyValue && classMap.variants && keyValue in classMap.variants) {
    variantClass = classMap.variants[keyValue];
  } else if (classMap.default) {
    // 매칭되는 variant가 없으면 default 사용
    variantClass = classMap.default;
  }

  // 3. base와 variant 클래스 결합
  const classes: string[] = [];

  if (classMap.base?.trim()) {
    classes.push(classMap.base.trim());
  }

  if (variantClass?.trim()) {
    classes.push(variantClass.trim());
  }

  return classes.join(' ');
}