@flextudio/scenario 0.1.0

package/contract-data/schema/v1/control/input-number.md

@@ -0,0 +1,55 @@
+# InputNumber
+
+순수 숫자 입력. `InputType` 한 키로 정수/소수/마스킹 구분. **1000단위 콤마 (금액) 는 `InputMask` + `InputType:"money"` 사용** (InputNumber 가 아님).
+
+## 스키마
+
+`control/input-number.schema.json` — `controlBase` + `inputBase` + 분기 키 (`ControlType="InputNumber"`, `InputType`, `Events`).
+
+## 예시
+
+```jsonc
+{
+  "ControlType": "InputNumber",
+  "ControlStyle": "styleInputValueLine",
+  "ControlDefaultName": "InputNumber1",
+  "ControlName2": "InputNumber1",
+  "Caption": "{{수량}}",
+  "Id": "f_31",
+  "InputType": "number",
+  "Ckeys": ["Quantity"],
+  "isColumnCtrl": false,
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "SizeValue": "70", "SizeUnit": "px", "MatchText": false }
+}
+```
+
+## `InputType` 값 (제한)
+
+스키마 enum 으로 강제. 그 외 값은 검증 실패. **콤마/소수점/범위 모두 이 한 키로만 결정**.
+
+| 값 | 의미 |
+|---|---|
+| `number` | 정수 (콤마 없음, 순수 숫자) |
+| `decimal` | 소수점 허용 (콤마 없음) |
+| `password` | 마스킹된 숫자 입력 (PIN/패스코드 등) |
+
+## 이벤트 (제한)
+
+`Events` 는 `_base.schema.json#/$defs/inputEventsChangeOnly` 적용. **`change` 만 지원** (실 샘플 기준). `input` / `focusin` / `focusout` 사용 시 enum 검증 실패.
+
+```jsonc
+{
+  "UseEvents": true,
+  "Events": {
+    "InputEventOrder": ["change"],
+    "change": "CALC_AMOUNT_EVENT"
+  }
+}
+```
+
+> EventOrder 에 `change` 등록 시 `change` 핸들러 키 필수 (if/then 강제).
+
+## 데이터 바인딩
+
+`Ckeys` 사용 시 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 필요.

package/contract-data/schema/v1/control/input-number.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/input-number.schema.json",
+  "title": "InputNumber",
+  "description": "숫자 입력. number/decimal/password. 천단위 콤마 (money) 는 InputMask 컨트롤 사용.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    { "$ref": "_base.schema.json#/$defs/inputBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "InputNumber" },
+        "InputType": {
+          "type": "string",
+          "enum": ["number", "decimal", "password"],
+          "description": "number=정수 (콤마 없음, 순수 숫자) / decimal=소수점 허용 (콤마 없음) / password=마스킹된 숫자 입력. 1000단위 콤마는 InputMask + InputType:'money' 사용."
+        },
+        "Events":   { "$ref": "_base.schema.json#/$defs/inputEventsChangeOnly" }
+      }
+    }
+  ]
+}

package/contract-data/schema/v1/control/input-text.md

@@ -0,0 +1,73 @@
+# InputText
+
+한 줄 텍스트 입력. 모드는 `InputType` 으로 결정.
+
+## 스키마
+
+`control/input-text.schema.json` — `controlBase` + `inputBase` + 분기 키 (`ControlType="InputText"`, `InputType`).
+
+## 예시
+
+```jsonc
+{
+  "ControlType": "InputText",
+  "ControlStyle": "styleInputValueLine",
+  "ControlDefaultName": "InputText1",
+  "ControlName2": "InputText1",
+  "Caption": "{{이름}}",
+  "Id": "f_30",
+  "Placeholder": "{{이름을 입력하세요}}",
+  "InputType": "text",
+  "Ckeys": ["UserName"],
+  "isColumnCtrl": false,
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "SizeValue": "70", "SizeUnit": "px", "MatchText": false }
+}
+```
+
+## `InputType` 값 (제한)
+
+스키마 enum 으로 강제. 그 외 값은 검증 실패.
+
+| 값 | 의미 |
+|---|---|
+| `text` | 일반 텍스트 (기본) |
+| `password` | 마스킹 |
+
+> 숫자/이메일/전화 등은 [InputNumber](input-number.md) 또는 [InputMask](input-mask.md) 사용. **1000단위 콤마 (금액) 는 `InputMask` + `InputType:"money"`** (InputNumber 가 아님).
+
+## 데이터 바인딩
+
+`Ckeys` 사용 시 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 필요. 직접 부모가 아닌 조상 Group 도 OK.
+
+## 이벤트 (제한)
+
+`Events` 는 `_base.schema.json#/$defs/inputEventsFull` 적용. `InputEventOrder` enum + EventOrder ↔ 핸들러 일치 강제.
+
+| 이벤트 | 의미 |
+|---|---|
+| `change` | 입력 완료 (Enter 키 포함). 검색/단일 입력 필드의 즉시 실행에 사용. |
+| `input` | 키 입력마다 (실시간 필터링). |
+| `focusin` | 포커스 진입. |
+| `focusout` | 포커스 이탈. |
+
+```jsonc
+{
+  "UseEvents": true,
+  "Events": {
+    "InputEventOrder": ["change"],
+    "change": "DoSearch_E"
+  }
+}
+```
+
+> EventOrder 에 등록한 이벤트는 **동명 핸들러 필수** (if/then 강제).
+> 예: `"InputEventOrder": ["change","input"]` → `change` + `input` 둘 다 핸들러 정의해야 함.
+
+> **검색/단일 입력 필드 패턴**: `change` 는 Enter 키에도 발생하므로 별도 검색 버튼 없이 즉시 실행 가능. 실시간 필터링은 `input` 사용.
+
+## 함정
+
+- `ControlName2` 누락 = 런타임 에러. `ControlDefaultName` 과 같은 값.
+- `isColumnCtrl: false` 항상 명시.
+- 필수 입력은 `ControlKey: "Required"` 로 처리 (스크립트 직접 작성 금지).

package/contract-data/schema/v1/control/input-text.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/input-text.schema.json",
+  "title": "InputText",
+  "description": "한 줄 텍스트 입력. text/password 모드.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    { "$ref": "_base.schema.json#/$defs/inputBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "InputText" },
+        "InputType": {
+          "type": "string",
+          "enum": ["text", "password"],
+          "description": "text=일반 텍스트 / password=마스킹 입력. (숫자/이메일/전화 등은 InputNumber 또는 InputMask 사용.)"
+        },
+        "Events": { "$ref": "_base.schema.json#/$defs/inputEventsFull" }
+      }
+    }
+  ]
+}

package/contract-data/schema/v1/control/label.md

@@ -0,0 +1,127 @@
+# Label
+
+표시 전용 컨트롤. **입력 없음**. `LabelType` 으로 두 모드.
+
+## 스키마
+
+`control/label.schema.json` — `controlBase` + 분기 키 (`ControlType="Label"`, `LabelType`, `labeltext` / `LabelCKey`, `UseClickEvent`/`UseMove`/`MoveSteps`, `ImageStyle`).
+
+## 모드
+
+| LabelType | 동작 | 필수 추가 키 |
+|---|---|---|
+| `labeltext` | 정적 텍스트(+바인딩 표현식) | `labeltext` |
+| `LabelCKey` | 카테고리 필드값 직접 표시 | `LabelCKey` |
+
+스키마는 `if/then` 으로 LabelType 별 필수키를 강제.
+
+## 예시 — labeltext 모드
+
+```jsonc
+{
+  "ControlType": "Label",
+  "ControlStyle": "styleFontNormal",
+  "LabelType": "labeltext",
+  "labeltext": "{{표시할 텍스트}}",
+  "ControlDefaultName": "Label1",
+  "ControlName2": "Label1",
+  "Caption": "Label1",
+  "Id": "f_10",
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "MatchText": true, "SizeValue": "" },
+  "FontStyle": {
+    "UseFont": true, "FontColor": "var(--colorGray1)",
+    "UseBold": true, "FontSize": "14", "FontAlign": "flex-start",
+    "FontWeight": "SemiBold"
+  },
+  "isColumnCtrl": false
+}
+```
+
+## `labeltext` 바인딩 표현식
+
+`Load.sector` 는 **`labeltext` 안에서 사용 불가** (LoadScript 에서만 존재). `{=FieldName}` 으로 현재 섹터 필드 직접 참조.
+
+```
+"labeltext": "{=FieldName}"                                          // 직접 바인딩
+"labeltext": "{=$FieldName}"                                         // 천단위 콤마 자동
+"labeltext": "{{총}} {=Hours}{{시간}}"                                // i18n + 바인딩 혼용
+"labeltext": "{{금액}} {=$Price}{{원}}"                               // i18n + 콤마 숫자
+"labeltext": "{% return '{=AppDate}'.slice(0,4) + '-' + '{=AppDate}'.slice(4,6) + '-' + '{=AppDate}'.slice(6) %}"
+"labeltext": "{% return f.numFormat('{=Price}').format() + '원' %}"
+```
+
+`{% %}` 안의 `{=Field}` 는 **JS 실행 전에** 실제 값으로 치환된다. 즉 `'{=Price}'` 는 런타임에 `'9500'` 같은 문자열로 바뀐 뒤 JS 가 실행된다.
+
+## 예시 — LabelCKey 모드
+
+```jsonc
+{
+  "ControlType": "Label",
+  "LabelType": "LabelCKey",
+  "LabelCKey": "StatusName",
+  "ControlStyle": "StyleRadiusLine",
+  "ControlDefaultName": "LblStatus",
+  "ControlName2": "LblStatus",
+  "Caption": "LblStatus",
+  "Id": "f_11",
+  "Width":  { "MatchText": true },
+  "Height": { "MatchText": true, "SizeValue": "" },
+  "isColumnCtrl": false
+}
+```
+
+`labeltext` 키 자체를 두지 않는다. 카테고리 필드값이 그대로 표시.
+
+## 클릭 / 이동 패턴 (Group / Button 과 동일)
+
+| 모드 | 키 |
+|---|---|
+| 이동 | `UseMove: true` + `MoveSteps: { MoveStepOrder, StepX: { Condition, MoveTo, Direction } }` |
+| 이벤트 | `UseClickEvent: true` + `Events: { Click: "EVENT_NAME" }` |
+
+**둘 다 사용 시**: `UseMove` 가 먼저 동작한 뒤 이벤트 실행.
+
+`Events` 는 `_base.schema.json#/$defs/labelEvents` 가 적용 — `Click` 핸들러만.
+
+## Caption 규칙
+
+Label 의 `Caption` 은 **내부명** (=`ControlDefaultName`). 화면 표시 텍스트는 항상 `labeltext` 또는 `LabelCKey` 가 결정.
+
+## 함정
+
+- `labeltext` 안에서 `Load.sector` 사용 불가 — `{=Field}` 만.
+- `LabelCKey` 모드면 `labeltext` 키 두지 않음.
+- 아이콘 라벨은 `ImageStyle` + (필요시) `labeltext: ""`.
+- `LabelCKey` 사용 시 상위 Group 계층 어딘가에 `UseDataConnection` + `DataConnection` 필요 (다른 Input 컨트롤과 동일).
+
+## PC 전용 키 (스키마 차원 차단)
+
+다음 키는 **PC 환경 전용 툴팁 기능**이라 모바일 기준의 시나리오 생성 시 **키 자체를 두지 않는다**.
+
+| 키 | 의미 |
+|---|---|
+| `TooltipType` | 툴팁 모드 (정적 텍스트 / 카테고리 필드값 등) |
+| `TooltipText` | `TooltipType` 이 정적 텍스트 모드일 때의 툴팁 문자열 |
+| `TooltipCKey` | `TooltipType` 이 카테고리 필드 모드일 때의 컬렉션 필드명 |
+
+### 차단 정책
+
+- **명세**: `properties` 에 description 으로만 의미를 남김 (참조용).
+- **옵션 차단**: `allOf` 의 `not.anyOf.required` 절로 세 키 **존재 자체를 거부**.
+  - AI 생성기든 사용자 편집이든 키가 들어가면 검증 실패.
+  - 차후 PC 시나리오까지 컨트랙트로 다루게 되면 이 `not` 절만 제거하면 됨 (명세는 유지).
+
+```jsonc
+{
+  "not": {
+    "anyOf": [
+      { "required": ["TooltipType"] },
+      { "required": ["TooltipText"] },
+      { "required": ["TooltipCKey"] }
+    ]
+  }
+}
+```
+
+→ `UseFullShape` / `UseTriming` 의 description-only soft 가이드와 달리, Tooltip 3종은 **hard 차단**.

package/contract-data/schema/v1/control/label.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/label.schema.json",
+  "title": "Label",
+  "description": "텍스트/아이콘 표시 전용. 입력 없음. labeltext / LabelCKey 두 모드. UseMove / UseClickEvent 로 Group / Button 과 동일한 클릭 패턴 지원.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "Label" },
+        "LabelType": {
+          "type": "string",
+          "enum": ["labeltext", "LabelCKey"],
+          "description": "labeltext=정적 텍스트(+바인딩) / LabelCKey=카테고리 필드값 직접 표시."
+        },
+        "labeltext": {
+          "type": "string",
+          "description": "LabelType='labeltext' 일 때 표시 텍스트. {{i18n}} / {=Field} / {=$Field}(콤마) / {% JS %} 사용 가능. Load.sector 사용 불가."
+        },
+        "LabelCKey": {
+          "type": "string",
+          "description": "LabelType='LabelCKey' 일 때 표시할 컬렉션 필드명."
+        },
+        "ImageStyle": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "아이콘 라벨용 이미지 스타일."
+        },
+        "UseFullShape": { "type": "boolean", "default": false, "description": "라벨 전체 영역 사용 (engine const K.USE_FULLSHAPE='UseFullShape'). ★ AI 생성 시 미포함 (사용자 수동 설정 전용)." },
+        "UseTriming":   { "type": "boolean", "default": false, "description": "텍스트 말줄임 (...) 처리. ★ 오타 'Triming' 운영 키 그대로 — 'Trimming' 아님 (engine const K.USE_TRIMMING='UseTriming'). ★ AI 생성 시 미포함 (사용자 수동 설정 전용)." },
+        "TooltipType": { "type": "string", "description": "툴팁 모드 키 (정적 텍스트 / 카테고리 필드값 등 운영 키 기준). ★ PC 전용 — 모바일 시나리오 생성 시 미포함 (AI 생성 금지, 키 자체를 두지 말 것)." },
+        "TooltipText": { "type": "string", "description": "TooltipType 이 정적 텍스트 모드일 때 표시할 툴팁 문자열. ★ PC 전용 — 모바일 시나리오 생성 시 미포함 (AI 생성 금지, 키 자체를 두지 말 것)." },
+        "TooltipCKey": { "type": "string", "description": "TooltipType 이 카테고리 필드 모드일 때 표시할 컬렉션 필드명. ★ PC 전용 — 모바일 시나리오 생성 시 미포함 (AI 생성 금지, 키 자체를 두지 말 것)." },
+        "UseClickEvent": {
+          "type": "boolean",
+          "default": false,
+          "description": "클릭 이벤트 사용. Events.Click 핸들러 명과 함께. UseMove 와 같이 쓰면 UseMove 가 먼저 동작."
+        },
+        "UseMove": {
+          "type": "boolean",
+          "default": false,
+          "description": "클릭 시 Step 이동. MoveSteps 와 함께."
+        },
+        "MoveSteps": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "이동 대상 Step 정의. UseMove=true 일 때. MoveStepOrder 배열의 각 StepId 마다 동일 레벨에 옵션 객체(MoveTo/Direction 등) 슬롯이 함께 존재해야 한다.",
+          "properties": {
+            "MoveStepOrder": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "pattern": "^Step[1-9][0-9]*$" }
+            }
+          },
+          "patternProperties": {
+            "^Step[1-9][0-9]*$": {
+              "type": "object",
+              "additionalProperties": true,
+              "description": "StepId 별 이동 설정. 신규 생성 시 { MoveTo: 'Next', Direction: 'toRight' } 로 초기화.",
+              "properties": {
+                "Condition": { "type": "string", "description": "이동 조건식 (빈 문자열=무조건)." },
+                "MoveTo": {
+                  "type": "string",
+                  "enum": ["Next", "Prev", "Prev_ReStart", "Init"],
+                  "description": "이동 동작. const.js MOVETYPE 참조."
+                },
+                "Direction": { "type": "string", "description": "MoveTo='Next' 일 때 네비게이션 방향 (예: toBottom, toRight)." }
+              }
+            }
+          }
+        },
+        "Events": { "$ref": "_base.schema.json#/$defs/labelEvents" }
+      }
+    },
+    {
+      "$comment": "LabelType='labeltext' 면 labeltext 필요.",
+      "if": {
+        "properties": { "LabelType": { "const": "labeltext" } },
+        "required": ["LabelType"]
+      },
+      "then": { "required": ["labeltext"] }
+    },
+    {
+      "$comment": "LabelType='LabelCKey' 면 LabelCKey 필요.",
+      "if": {
+        "properties": { "LabelType": { "const": "LabelCKey" } },
+        "required": ["LabelType"]
+      },
+      "then": { "required": ["LabelCKey"] }
+    },
+    {
+      "$comment": "UseMove=true 면 MoveSteps 필요.",
+      "if": {
+        "properties": { "UseMove": { "const": true } },
+        "required": ["UseMove"]
+      },
+      "then": { "required": ["MoveSteps"] }
+    },
+    {
+      "$comment": "PC 전용 툴팁 키는 모바일 시나리오 메타에 등장 금지 — 키 존재 자체 차단 (명세는 properties 에 유지하되 옵션 차원 강제).",
+      "not": {
+        "anyOf": [
+          { "required": ["TooltipType"] },
+          { "required": ["TooltipText"] },
+          { "required": ["TooltipCKey"] }
+        ]
+      }
+    }
+  ]
+}

package/contract-data/schema/v1/control/multi-input-box.md

@@ -0,0 +1,51 @@
+# MultiInputBox
+
+여러 줄 텍스트 입력 (TextArea). Enter 로 줄바꿈.
+
+## 스키마
+
+`control/multi-input-box.schema.json` — `controlBase` + `inputBase` + 분기 키 (`ControlType="MultiInputBox"`).
+
+## 예시
+
+```jsonc
+{
+  "ControlType": "MultiInputBox",
+  "ControlStyle": "styleInputValueLine",
+  "ControlDefaultName": "MultiInput1",
+  "ControlName2": "MultiInput1",
+  "Caption": "{{비고}}",
+  "Id": "f_40",
+  "Placeholder": "{{내용을 입력하세요}}",
+  "Ckeys": ["Remarks"],
+  "Maxlength": "500",
+  "isColumnCtrl": false,
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "SizeValue": "120", "SizeUnit": "px", "MatchText": false }
+}
+```
+
+## 이벤트 (제한)
+
+`Events` 는 `_base.schema.json#/$defs/inputEventsFull` 적용 (InputText 와 동일 4종). `InputEventOrder` enum: `change` / `input` / `focusin` / `focusout`. EventOrder ↔ 핸들러 일치 강제.
+
+```jsonc
+{
+  "UseEvents": true,
+  "Events": {
+    "InputEventOrder": ["change", "focusout"],
+    "change":   "ON_TEXT_CHANGED",
+    "focusout": "ON_TEXT_BLURRED"
+  }
+}
+```
+
+## 데이터 바인딩
+
+`Ckeys` 사용 시 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 필요.
+
+## 함정
+
+- 기본 Height 는 `120px` — 다른 Input 계열(70px) 보다 큼.
+- `InputType` 없음 — 항상 일반 텍스트 멀티라인.
+- 줄바꿈 문자(`\n`) 그대로 저장됨.

package/contract-data/schema/v1/control/multi-input-box.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/multi-input-box.schema.json",
+  "title": "MultiInputBox",
+  "description": "여러 줄 텍스트 입력 (TextArea). Enter 로 줄바꿈. Shared Input Base 사용 — Height 기본 120px (다른 입력은 70px).",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    { "$ref": "_base.schema.json#/$defs/inputBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "MultiInputBox" },
+        "Events":      { "$ref": "_base.schema.json#/$defs/inputEventsFull" }
+      }
+    }
+  ]
+}

package/contract-data/schema/v1/control/other.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/other.schema.json",
+  "title": "OtherControl",
+  "description": "v1 명시 외 ControlType (InputBox, Sheet, TimeTable, Approval, Scheduler, Image, ComboList 단독, List 단독, Signature, Line 등) — 검증 통과시키는 fallback. 상세 schema 는 v2 에서 정의. Button/Calendar/CalendarNavigator/Tab/Tree/Embed 는 자체 schema 분기로 빠짐.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "properties": {
+    "Id": { "type": "string", "pattern": "^f_[1-9][0-9]*$" },
+    "ControlType": {
+      "type": "string",
+      "not": {
+        "enum": [
+          "InputText", "InputNumber", "InputMask", "InputDate",
+          "MultiInputBox", "Combo", "Search", "CheckBox", "RadioBox",
+          "Label", "ImageBox", "InputFile", "Button",
+          "Calendar", "CalendarNavigator", "Tab",
+          "Tree", "Embed"
+        ]
+      }
+    }
+  }
+}

package/contract-data/schema/v1/control/radio-box.md

@@ -0,0 +1,150 @@
+# RadioBox
+
+라디오 그룹. Fixed `Items` 또는 외부 `DataSource` 두 가지 데이터 소스. `styleTab` 으로 탭 형태 UI 도 가능.
+
+## 스키마
+
+`control/radio-box.schema.json` — `controlBase` + 분기 키 (`ControlType="RadioBox"`, `Items` / `DataSourceName`, `SaveNameKey`/`SaveValueKey`, `ControlStyle`, `Direction`, `UseDataSource`, `UseItemDesign`/`ItemDesign`).
+
+## 예시 — Fixed Items
+
+```jsonc
+{
+  "ControlType": "RadioBox",
+  "ControlStyle": "None",
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "MatchText": true, "SizeValue": "" },
+  "ControlDefaultName": "RadioBox1",
+  "ControlName2": "RadioBox1",
+  "Caption": "{{선택 항목}}",
+  "Id": "f_45",
+  "Ckeys": ["SelectedValue", "SelectedName"],
+  "SaveNameKey": "SelectedName",
+  "SaveValueKey": "SelectedValue",
+  "Items": [
+    { "ItemName": "{{옵션1}}", "ItemValue": "1" },
+    { "ItemName": "{{옵션2}}", "ItemValue": "2" },
+    { "ItemName": "{{옵션3}}", "ItemValue": "3" }
+  ],
+  "UseDataSource": false,
+  "DefaultValue": "{{옵션1}}",
+  "isColumnCtrl": false
+}
+```
+
+> `DefaultValue` 는 **표시명(RadioBoxItem명) 기준** 문자열. Fixed 모드면 `Items[*].ItemName` 과 매칭, DataSource 모드면 `CollectionMapper` 의 `ItemName` 매핑 대상 필드 값과 매칭. `ItemValue` 가 아님에 유의.
+
+## 예시 — DataSource
+
+```jsonc
+{
+  "ControlType": "RadioBox",
+  "Ckeys": ["DeptCode", "DeptName"],
+  "UseDataSource": true,
+  "DataSourceName": "DeptListDS",
+  "CollectionMapper": {
+    "DeptCode": "ItemValue",
+    "DeptName": "ItemName"
+  },
+  "SaveValueKey": "DeptCode",
+  "ControlDefaultName": "RadioDept",
+  "ControlName2": "RadioDept",
+  "Id": "f_46",
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — styleTab (탭 형태)
+
+탭 전환 시 같은 리스트/데이터를 필터링만 하는 경우 Tab 컨트롤 대신 RadioBox 에 `styleTab` 적용.
+
+```jsonc
+{
+  "ControlType": "RadioBox",
+  "ControlStyle": "styleTab",
+  "Items": [
+    { "ItemName": "{{내 결재}}", "ItemValue": "MY" },
+    { "ItemName": "{{내 신청}}", "ItemValue": "REQ" }
+  ],
+  "Ckeys": ["TabValue"],
+  "SaveValueKey": "TabValue",
+  "Direction": "horizontal",
+  "ControlDefaultName": "TabRadio",
+  "ControlName2": "TabRadio",
+  "Id": "f_47",
+  "isColumnCtrl": false,
+  "UseEvents": true,
+  "Events": {
+    "ContentEvent": ["Click"],
+    "Click": "ON_TAB_CHANGED"
+  }
+}
+```
+
+## 제한값
+
+### `ControlStyle`
+스키마 enum 으로 강제.
+
+| 값 | 외형 / 용도 |
+|---|---|
+| `""` / `"None"` | 기본 라디오 |
+| `"styleRectangle"` | 사각 카드 라디오 (`UseItemDesign` 과 함께) |
+| `"styleTab"` | 탭 형태 — 필터/뷰 전환 |
+| `"stylePeriod"` | 기간 선택형 |
+| `"styleRadius"` | 라운드 |
+
+### 조건부 강제 (스키마 if/then)
+
+- `UseDataSource=true` → `DataSourceName` 필수.
+- `UseItemDesign=true` → `ItemDesign` 필수.
+- `UseDataSource=true` → `SaveNameKey` / `SaveNameName` 사용 금지 (Fixed 모드 전용 키). DataSource 모드의 표시명은 `CollectionMapper` 로 매핑.
+
+## DataSource vs Items
+
+★ `UseDataSource` 런타임 default = **false** ([property-data.js:8818](public/javascripts/scenario-studio/property-data.js#L8818)) — 스키마에도 `"default": false` 박힘. ComboList(default=true)와 비대칭이니 헷갈리지 말 것.
+
+| 모드 | 키 | UseDataSource |
+|---|---|---|
+| Fixed | `Items` + `Ckeys` + `SaveNameKey` + `SaveValueKey` (**셋 다 필수** — 고정데이터라고 생략 금지) | 생략 가능 (default=false). 명시한다면 `false`. |
+| External | `DataSourceName` + `CollectionMapper` (표시명은 mapper 안 `ItemName`/`ItemValue` 키로 매핑 — `SaveNameKey` / `SaveNameName` 사용 금지) | `true` 명시 필수 (스키마 if/then 으로 강제). |
+
+> ★ **고정데이터(`UseDataSource:false`)도 `Ckeys`/`SaveNameKey`/`SaveValueKey` 를 무조건 채운다.** 엔진이 `SaveNameKey`/`SaveValueKey` 로 선택 항목의 표시명/값을 Ckeys 에 저장한다 ([radiobox.js:380-381](public/engine/control/radiobox.js#L380-L381)) — 누락 시 선택해도 저장 안 됨. 단 `CtrlDisplayCkey` 는 **RadioBox 엔진이 사용하지 않으므로 넣지 않는다** (Combo/Search 본체 전용). 자세히는 [rules.md §5.5.1](../../../rules.md#551-고정데이터-컨트롤의-저장-키-필수-ckeys--savenamekey--savevaluekey).
+
+스튜디오 패널은 `controlMeta.UseDataSource` truthy 검사로 분기 ([studio-panel-cat.js:1129](public/javascripts/scenario-studio/studio-panel-cat.js#L1129)) — 운영 메타에 문자열 `"true"` 가 있으면 truthy 라 동작하지만 `"false"` 는 JS truthy 라 의도와 반대로 DataSource 모드로 인식되는 코드 경로가 있다. **AI 생성에는 boolean 만**.
+
+`CollectionMapper` 는 외부 데이터 필드를 `ItemName` / `ItemValue` 로 매핑:
+```jsonc
+"CollectionMapper": {
+  "ItemName": "원본필드명",
+  "ItemValue": "원본키필드"
+}
+```
+
+또는 Ckeys 직접 매핑 형태도 사용:
+```jsonc
+"CollectionMapper": {
+  "DeptCode": "ItemValue",
+  "DeptName": "ItemName"
+}
+```
+
+## 이벤트 (제한)
+
+EventOrder 키 없이 `Click` 핸들러 직접. `Events` 는 `_base.schema.json#/$defs/directClickEvents`.
+
+```jsonc
+{
+  "UseEvents": true,
+  "Events": { "Click": "ON_TAB_CHANGED" }
+}
+```
+
+`Click` — 선택이 변경되면 발화.
+
+## 함정
+
+- `SaveValueKey` 누락 시 저장 동작 안 함.
+- `styleRectangle` 은 `UseItemDesign: true` + `ItemDesign` 과 함께 써야 카드 디자인 적용.
+- 외부 데이터인데 `UseDataSource: false` 또는 `DataSourceName` 누락 → 항목 안 보임.
+- `Ckeys` 사용 시 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 필요.