Gnuboard7/docs/frontend/layout-json-components-rendering.md

레이아웃 JSON - 조건부/반복 렌더링

메인 문서: layout-json-components.md 관련 문서: data-binding.md | state-management.md

---

목차

1. 조건부 렌더링 (if)
2. 복합 조건 렌더링 (conditions) ⭐ NEW (engine-v1.10.0+)
3. 반복 렌더링 (iteration)
4. 정렬 가능 렌더링 (sortable)

---

조건부 렌더링 (if)

목적: 조건에 따라 컴포넌트를 표시하거나 숨깁니다.

핵심 원칙

필수: if 속성 사용 (type: "conditional" 미지원)
필수: if 속성을 사용한 조건부 렌더링
✅ 필수: 조건이 truthy일 때만 컴포넌트가 렌더링됨

기본 사용법

{
  "id": "warning_message",
  "type": "basic",
  "name": "Div",
  "if": "{{_local.showWarning}}",
  "props": {
    "className": "text-orange-500"
  },
  "text": "경고 메시지입니다."
}

if 표현식

if 속성은 JavaScript 표현식을 사용하여 조건을 평가합니다:

// 단순 boolean 확인
"if": "{{_local.isVisible}}"

// 값 비교
"if": "{{_local.status === 'active'}}"

// 복합 조건
"if": "{{_local.count > 0 && _local.isEnabled}}"

// 데이터 존재 확인
"if": "{{user.data?.name}}"

// 배열 길이 확인
"if": "{{items.data?.length > 0}}"

condition 속성 (if의 별칭)

@since engine-v1.21.1

condition 속성은 if와 동일하게 동작합니다. 컴포넌트 내부 children(예: DataGrid의 cellChildren, footerCells)에서 관례적으로 사용됩니다.

{
  "type": "basic",
  "name": "Span",
  "condition": "{{row.discount_amount > 0}}",
  "text": "-{{row.discount_amount | number}}원"
}

• 엔진이 prop을 사전 해석하여 condition이 boolean이 되어도 정상 동작
• 우선순위: if > condition > conditions (if가 있으면 condition은 무시)

잘못된 패턴과 올바른 패턴

❌ 잘못된 패턴 (type: "conditional" 미지원):

{
  "type": "conditional",
  "condition": "{{_local.isVisible}}",
  "true": {
    "type": "basic",
    "name": "Span",
    "text": "보임"
  },
  "false": null
}

✅ 올바른 패턴 (if 속성 사용):

{
  "id": "visible_text",
  "type": "basic",
  "name": "Span",
  "if": "{{_local.isVisible}}",
  "text": "보임"
}

다중 조건 분기 (if-else 패턴)

여러 조건에 따라 다른 컴포넌트를 표시해야 할 경우, 각 조건에 맞는 if 속성을 가진 개별 컴포넌트를 사용합니다:

{
  "type": "basic",
  "name": "Div",
  "children": [
    {
      "id": "status_active",
      "type": "basic",
      "name": "Span",
      "if": "{{_local.status === 'active'}}",
      "props": { "className": "text-green-500" },
      "text": "활성"
    },
    {
      "id": "status_inactive",
      "type": "basic",
      "name": "Span",
      "if": "{{_local.status === 'inactive'}}",
      "props": { "className": "text-gray-500" },
      "text": "비활성"
    },
    {
      "id": "status_pending",
      "type": "basic",
      "name": "Span",
      "if": "{{_local.status === 'pending'}}",
      "props": { "className": "text-yellow-500" },
      "text": "대기"
    }
  ]
}

iteration과 함께 사용

조건부 렌더링과 반복 렌더링을 함께 사용할 수 있습니다:

{
  "id": "product_list",
  "type": "basic",
  "name": "Div",
  "if": "{{products.data?.length > 0}}",
  "iteration": {
    "source": "products.data",
    "item_var": "product"
  },
  "children": [
    {
      "type": "basic",
      "name": "Span",
      "text": "{{product.name}}"
    }
  ]
}

iteration + if 함께 사용 시 주의사항

주의: if가 iteration과 같은 레벨에 있고 item_var를 참조하면 동작하지 않음!
   - if는 iteration보다 먼저 평가됨
   - if 평가 시점에 item_var가 아직 바인딩되지 않음
   - 결과: 조건이 항상 false로 평가되어 아무것도 렌더링되지 않음

❌ 잘못된 패턴: if가 iteration과 같은 레벨에서 item_var 참조

{
  "iteration": {
    "source": "{{types}}",
    "item_var": "itemType"
  },
  "type": "basic",
  "name": "Div",
  "if": "{{activeTab === itemType}}",
  "children": [...]
}

✅ 올바른 패턴: if를 children 내부로 이동

{
  "iteration": {
    "source": "{{types}}",
    "item_var": "itemType"
  },
  "type": "basic",
  "name": "Div",
  "children": [
    {
      "type": "basic",
      "name": "Div",
      "if": "{{activeTab === itemType}}",
      "children": [...]
    }
  ]
}

평가 순서:

1. if 평가 (iteration 이전) → item_var 미바인딩 상태
2. iteration 처리 → item_var 바인딩
3. children 렌더링 → children 내부의 if는 item_var 접근 가능

주의사항

• ✅ if 속성은 DynamicRenderer에서 평가되어 조건이 falsy면 컴포넌트가 렌더링되지 않음
• ✅ if 표현식에서 {{}} 구문 사용 필수
• ❌ type: "conditional", condition, true, false 속성은 미지원
• ❌ 중첩된 조건문보다 평면적인 다중 if 패턴 권장

---

복합 조건 렌더링 (conditions)

버전: engine-v1.10.0+

목적: 여러 조건을 AND/OR 그룹으로 조합하여 복잡한 렌더링 조건을 표현합니다. 기존 if 속성의 완전한 상위호환입니다.

핵심 원칙

✅ conditions는 기존 if의 상위호환 (if가 있으면 if 우선)
✅ AND 그룹: 모든 조건이 true일 때만 렌더링
✅ OR 그룹: 하나라도 true면 렌더링
✅ if-else 체인: 하나라도 매칭되면 렌더링

타입 정의

type ConditionExpression =
  | string                              // 단순 표현식: "{{user.isAdmin}}"
  | { and: ConditionExpression[] }      // AND 그룹: 모든 조건 true → true
  | { or: ConditionExpression[] };      // OR 그룹: 하나라도 true → true

interface ConditionBranch {
  if?: ConditionExpression;             // 조건 (없으면 else 브랜치)
}

type ConditionsProperty = ConditionExpression | ConditionBranch[];

AND 그룹 사용

모든 조건이 true일 때만 컴포넌트가 렌더링됩니다.

{
  "id": "author_info",
  "type": "basic",
  "name": "Div",
  "conditions": {
    "and": ["{{route.id}}", "{{form_data?.data?.author}}"]
  },
  "props": { "className": "author-info" },
  "text": "작성자: {{form_data.data.author.name}}"
}

OR 그룹 사용

하나라도 true면 컴포넌트가 렌더링됩니다.

{
  "id": "admin_section",
  "type": "basic",
  "name": "Div",
  "conditions": {
    "or": ["{{_global.user?.role === 'admin'}}", "{{_global.user?.role === 'manager'}}"]
  },
  "text": "관리자 전용 영역"
}

중첩 AND/OR 조건

복잡한 조건 로직을 표현할 수 있습니다.

{
  "id": "sales_dashboard",
  "type": "basic",
  "name": "Div",
  "conditions": {
    "or": [
      "{{_global.user?.isSuperAdmin}}",
      {
        "and": ["{{_global.user?.isAdmin}}", "{{_global.user?.department === 'sales'}}"]
      }
    ]
  },
  "text": "영업 대시보드"
}

위 조건은 다음과 같이 해석됩니다:

• SuperAdmin이면 렌더링 또는
• Admin이면서 영업부서이면 렌더링

if-else 체인 (브랜치 배열)

여러 조건 중 하나라도 매칭되면 렌더링됩니다. 기존 if의 다중 조건 분기 패턴을 단순화합니다.

{
  "id": "permission_content",
  "type": "basic",
  "name": "Div",
  "conditions": [
    { "if": "{{_global.user?.role === 'admin'}}" },
    { "if": "{{_global.user?.role === 'manager'}}" },
    { "if": "{{_global.user?.hasSpecialPermission}}" }
  ],
  "text": "권한이 있는 사용자만 볼 수 있습니다"
}

위 조건은 admin, manager, 또는 특별 권한이 있는 경우 렌더링됩니다.

if vs conditions 우선순위

if와 conditions가 동시에 있으면 if가 우선됩니다 (하위 호환).

{
  "id": "test",
  "type": "basic",
  "name": "Div",
  "if": "{{ifCondition}}",
  "conditions": "{{conditionsValue}}",
  "text": "if가 우선됨"
}

if vs conditions 선택 가이드

상황	권장
단순 조건	if
여러 조건 AND	conditions: { "and": [...] }
여러 조건 OR	conditions: { "or": [...] }
복잡한 조합	conditions (중첩 AND/OR)
기존 레이아웃 수정	기존 if 유지

주의사항

✅ conditions의 모든 문자열 표현식은 기존 if와 동일한 문법 지원
✅ Optional Chaining(?.), 비교 연산자, 논리 연산자 모두 지원
if와 conditions를 동시에 사용하면 if가 우선
conditions 배열(브랜치)에서 else 브랜치(if 없음)는 컴포넌트 렌더링에서 의미 없음 (액션에서만 사용)

---

반복 렌더링 (iteration)

목적: 배열 데이터를 기반으로 컴포넌트를 반복 렌더링합니다.

iteration 핵심 원칙

✅ iteration이 있는 컴포넌트는 wrapper로 렌더링됨 (각 아이템마다 해당 컴포넌트 생성)
✅ children이 있으면 wrapper 내부에 children이 렌더링됨
✅ text만 있고 children이 없어도 정상 동작 (wrapper + text)

구조

{
  "id": "error_list",
  "type": "basic",
  "name": "Ul",
  "iteration": {
    "source": "items.data",
    "item_var": "item",
    "index_var": "idx"
  },
  "children": [
    {
      "type": "basic",
      "name": "Li",
      "text": "{{item.name}}"
    }
  ]
}

필드 설명

필드	타입	필수	설명
source	string	✅	반복할 배열 데이터 경로 (표현식 지원)
item_var	string	✅	각 아이템을 참조할 변수명
index_var	string	❌	인덱스를 참조할 변수명 (0부터 시작)

사용 패턴

✅ 패턴 1: iteration이 있는 컴포넌트에 children 포함 (wrapper + children)

{
  "type": "basic",
  "name": "Div",
  "props": { "className": "flex items-center gap-2" },
  "iteration": {
    "source": "items.data",
    "item_var": "item"
  },
  "children": [
    {
      "type": "basic",
      "name": "Icon",
      "props": { "name": "check" }
    },
    {
      "type": "basic",
      "name": "Span",
      "text": "{{item.name}}"
    }
  ]
}

결과 HTML:

<div class="flex items-center gap-2"><i>...</i><span>Item 1</span></div>
<div class="flex items-center gap-2"><i>...</i><span>Item 2</span></div>

✅ 패턴 2: iteration이 있는 컴포넌트에 text만 포함 (wrapper + text)

{
  "type": "basic",
  "name": "Li",
  "iteration": {
    "source": "_local.errors",
    "item_var": "error"
  },
  "text": "{{error}}"
}

결과 HTML:

<li>Error message 1</li>
<li>Error message 2</li>

source 표현식 지원

source에는 단순 경로뿐 아니라 JavaScript 표현식도 사용 가능합니다:

{
  "iteration": {
    "source": "Object.entries(_local.errors ?? {}).flatMap(([field, messages]) => messages)",
    "item_var": "message"
  }
}

_local 상태 접근

iteration 내부 컴포넌트에서도 _local 상태에 접근할 수 있습니다. 이는 레이아웃 전체에서 상태가 공유되기 때문입니다.

{
  "iteration": {
    "source": "_local.items",
    "item_var": "item"
  },
  "children": [
    {
      "type": "basic",
      "name": "Div",
      "props": {
        "className": "{{_local.selectedId === item.id ? 'selected' : ''}}"
      },
      "text": "{{item.name}}"
    }
  ]
}

실제 사용 예시: API 에러 메시지 표시

{
  "id": "validation_error",
  "type": "basic",
  "name": "Div",
  "if": "{{_local.errors && Object.keys(_local.errors).length > 0}}",
  "props": {
    "className": "bg-red-50 border border-red-200 rounded-lg p-4 mb-6"
  },
  "children": [
    {
      "type": "basic",
      "name": "Ul",
      "props": {
        "className": "list-disc list-inside space-y-1"
      },
      "iteration": {
        "source": "Object.entries(_local.errors ?? {}).flatMap(([field, messages]) => messages)",
        "item_var": "message"
      },
      "children": [
        {
          "type": "basic",
          "name": "Li",
          "props": {
            "className": "text-sm text-red-700"
          },
          "text": "{{message}}"
        }
      ]
    }
  ]
}

주의사항

• ✅ source는 배열로 평가되어야 함 (배열이 아니면 경고 로그 출력)
• ✅ item_var로 지정한 변수명으로 각 아이템에 접근
• ✅ index_var는 선택사항 (필요한 경우에만 지정)
• ✅ children 내부에서 {{item_var}}로 데이터 바인딩
• ✅ iteration이 있는 컴포넌트는 wrapper로 렌더링되며, 각 아이템마다 해당 컴포넌트가 생성됨
• iteration 내 컴포넌트에 고유 id 권장 - React key 안정성 보장 및 상태 동기화 문제 방지

iteration 내 컴포넌트 id 패턴 (권장)

iteration 내부에서 상태를 관리하는 컴포넌트(Input, Select, TagInput 등)는 고유 id를 지정해야 합니다:

// ✅ 권장: index_var를 활용한 고유 id
{
  "iteration": {
    "source": "{{_local.items}}",
    "item_var": "item",
    "index_var": "idx"
  },
  "children": [
    {
      "id": "input_item_{{idx}}",
      "type": "basic",
      "name": "Input",
      "props": {
        "name": "item_name_{{idx}}",
        "value": "{{item.name}}"
      }
    }
  ]
}

// ✅ 권장: item의 고유 식별자 활용
{
  "id": "tag_input_{{item.id}}",
  "type": "composite",
  "name": "TagInput",
  "props": {
    "value": "{{item.values ?? []}}"
  }
}

// ❌ 비권장: id 없음 (동적 추가/삭제 시 상태 혼선 가능)
{
  "type": "composite",
  "name": "TagInput",
  "props": {
    "value": "{{item.values ?? []}}"
  }
}

id가 필요한 이유:

• React의 reconciliation 과정에서 컴포넌트 인스턴스 식별에 사용
• id가 없으면 동적으로 행 추가/삭제 시 이전 인스턴스의 내부 상태가 새 인스턴스에 표시될 수 있음
• 특히 내부 상태를 관리하는 컴포넌트(TagInput, Select, Input 등)에서 중요

iteration id 표현식 보간 (engine-v1.50.0+): 노드의 최상위 id 필드에 쓴 표현식(id: "item_{{$idx}}", id: "row_{{item.id}}" 등)은 일반 렌더 경로(DynamicRenderer)에서 iteration 컨텍스트로 보간되어 행마다 고유 DOM id 가 된다. index_var(예 "index_var": "$idx") 또는 item_var 의 필드를 활용한다. 정적 id 를 iteration 안에 그대로 두면 모든 행이 같은 HTML id 를 갖게 되어 W3C id 유일성을 위반하므로(렌더 누락까지 유발), 반복 항목 노드와 그 자식의 id 는 반드시 동적화한다. 내부 식별(slot 등록·React key)에는 원본 id 가 쓰이므로 보간은 DOM 출력에만 적용된다.

---

정렬 가능 렌더링 (sortable)

버전: engine-v1.14.0+ 기반: @dnd-kit/core + @dnd-kit/sortable

sortable 속성을 사용하면 드래그앤드롭으로 배열 아이템의 순서를 변경할 수 있습니다. iteration과 유사하지만 정렬 기능이 내장되어 있습니다.

핵심 원칙

sortable과 iteration이 같은 컴포넌트에 있으면 sortable만 동작 (우선순위 높음)
sortable 내부에서는 폼 자동 바인딩이 비활성화됨 (stale 값 방지)
onSortEnd에서 setState로 소스 배열을 업데이트해야 정렬 결과가 반영됨

기본 구조

{
  "type": "basic",
  "name": "Div",
  "sortable": {
    "source": "{{_local.form.items}}",
    "itemKey": "id",
    "strategy": "verticalList",
    "handle": "[data-drag-handle]",
    "itemVar": "$item",
    "indexVar": "$index"
  },
  "itemTemplate": {
    "type": "basic",
    "name": "Div",
    "children": [
      {
        "type": "basic",
        "name": "Div",
        "props": { "data-drag-handle": true, "className": "cursor-grab" },
        "children": [{ "type": "basic", "name": "Icon", "props": { "name": "fa-grip-vertical" } }]
      },
      {
        "type": "basic",
        "name": "Span",
        "props": { "textContent": "{{$item.name}}" }
      }
    ]
  },
  "actions": [
    {
      "event": "onSortEnd",
      "handler": "setState",
      "params": {
        "target": "local",
        "form.items": "{{$sortedItems}}"
      }
    }
  ]
}

sortable 속성

필드	타입	필수	기본값	설명
source	string	✅	-	배열 바인딩 표현식
itemKey	string	❌	"id"	아이템 고유 키 필드명
strategy	string	❌	"verticalList"	verticalList / horizontalList / rectSorting
handle	string	❌	-	드래그 핸들 CSS 선택자
itemVar	string	❌	"$item"	아이템 컨텍스트 변수명
indexVar	string	❌	"$index"	인덱스 컨텍스트 변수명
wrapperElement	string	❌	"div"	래퍼 HTML 요소. Table 내부에서 "tr" 지정 시 itemTemplate의 children을 <tr> 안에 직접 렌더링 (engine-v1.30.0+)

itemTemplate

sortable과 함께 사용하는 아이템 템플릿입니다. iteration의 자식 컴포넌트 역할을 합니다. $item과 $index(또는 itemVar/indexVar로 지정한 변수명)로 각 아이템에 접근합니다.

sortable 전용 이벤트

이벤트	컨텍스트 변수	설명
onSortEnd	$sortedItems, $oldIndex, $newIndex	정렬 완료
onSortStart	$activeId	드래그 시작

드래그 핸들

handle을 지정하면 해당 CSS 선택자를 가진 요소만 드래그 가능합니다. DynamicRenderer가 data-drag-handle 속성을 감지하여 @dnd-kit 리스너를 자동 바인딩합니다.

핸들 미지정 시 아이템 전체가 드래그 가능합니다.

iteration과의 차이

항목	iteration	sortable
용도	배열 반복 렌더링	드래그앤드롭 정렬
정렬 지원	❌	✅ (@dnd-kit 내장)
폼 자동 바인딩	✅	❌ (비활성화됨)
아이템 정의	children	itemTemplate
이벤트	없음	onSortEnd, onSortStart

상세: actions-handlers-state.md

---

관련 문서

• 레이아웃 JSON 컴포넌트 인덱스
• 데이터 로딩 및 생명주기
• 슬롯 시스템
• 데이터 바인딩