@flextudio/scenario 0.1.0

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

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/radio-box.schema.json",
+  "title": "RadioBox",
+  "description": "라디오 그룹. Fixed Items 또는 DataSource 두 가지 데이터 소스. styleTab 으로 탭 형태 UI 도 가능. UseDataSource 미지정 시 런타임 default=false (Fixed 모드).",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "RadioBox" },
+        "ControlStyle": {
+          "type": "string",
+          "enum": ["", "None", "styleRectangle", "styleTab", "stylePeriod", "styleRadius"],
+          "description": "'None'=기본 라디오 / 'styleRectangle'=사각 카드 (UseItemDesign 과 함께) / 'styleTab'=탭 형태 / 'stylePeriod'=기간 선택형 / 'styleRadius'=라운드."
+        },
+        "Items": {
+          "type": "array",
+          "items": { "$ref": "_base.schema.json#/$defs/selectionItem" },
+          "description": "Fixed 모드 (UseDataSource=false 또는 생략) 일 때 인라인 선택지."
+        },
+        "SaveNameKey":     { "type": "string", "description": "Ckeys 중 표시명 저장 필드. **Fixed 모드(UseDataSource=false 또는 생략) 전용** — DataSource 모드에서는 CollectionMapper 로 매핑하므로 본 키를 사용하지 않는다 (if/then 으로 차단)." },
+        "SaveNameName":    { "type": "string", "description": "표시명 저장 시 사용할 별칭. **Fixed 모드 전용** (UseDataSource=true 시 사용 금지)." },
+        "SaveValueKey":    { "type": "string", "description": "Ckeys 중 값 저장 필드." },
+        "DefaultValue":    { "type": "string", "description": "초기 선택값 — **표시명(RadioBoxItem명) 기준** 문자열. Fixed 모드면 Items[*].ItemName 과 매칭, DataSource 모드면 CollectionMapper 의 ItemName 매핑 대상 필드 값과 매칭. ItemValue 가 아님에 유의. 빈 문자열 \"\" 도 가능." },
+        "UseDefaultValue": false,
+        "Direction":       { "type": "string", "examples": ["horizontal", "vertical", "row", "column"], "description": "선택지 배치 방향." },
+        "UseDataSource": {
+          "type": "boolean",
+          "default": false,
+          "description": "true=DataSource 사용 (DataSourceName 필수), false=Fixed Items. 런타임 default=false. ★ 프로퍼티 EDITOR_CTRL.RADIOBOX boolean 저장 — 진실원본 boolean."
+        },
+        "DataSourceName":  { "type": "string", "description": "UseDataSource=true 일 때 데이터 소스 이름." },
+        "CollectionMapper": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "DataSource 사용 시 { 대상Ckey: 원본필드, ItemName: ..., ItemValue: ... } 매핑."
+        },
+        "UseCategory":     { "type": "boolean", "default": false },
+        "CategoryName":    { "type": "string" },
+        "UseItemDesign":   { "type": "boolean", "default": false, "description": "true=ItemDesign 으로 항목별 커스텀 디자인 적용 (styleRectangle 과 함께)." },
+        "ItemDesign":      { "type": "object", "additionalProperties": true },
+        "ItemBgStyle":     { "type": "object", "additionalProperties": true },
+        "UseAlignRight":   { "type": "boolean", "default": false },
+        "AfterScript":     { "type": "string" },
+        "UniqueKey":       { "type": "string" },
+        "Events":          { "$ref": "_base.schema.json#/$defs/directClickEvents" }
+      }
+    },
+    {
+      "$comment": "UseDataSource=true 면 DataSourceName + CollectionMapper 필수 — 콜렉션 ↔ DataSource 필드 매핑이 있어야 데이터 연결관계가 성립.",
+      "if": {
+        "properties": { "UseDataSource": { "const": true } },
+        "required": ["UseDataSource"]
+      },
+      "then": {
+        "required": ["DataSourceName", "CollectionMapper"],
+        "properties": {
+          "CollectionMapper": { "minProperties": 1 }
+        }
+      }
+    },
+    {
+      "$comment": "UseItemDesign=true 면 ItemDesign 필수.",
+      "if": {
+        "properties": { "UseItemDesign": { "const": true } },
+        "required": ["UseItemDesign"]
+      },
+      "then": { "required": ["ItemDesign"] }
+    },
+    {
+      "$comment": "UseDataSource=true (DataSource 모드) 일 때 SaveNameKey / SaveNameName 사용 금지 — Fixed 모드 전용 키. DataSource 모드의 표시명은 CollectionMapper 로 매핑.",
+      "if": {
+        "properties": { "UseDataSource": { "const": true } },
+        "required": ["UseDataSource"]
+      },
+      "then": {
+        "properties": {
+          "SaveNameKey": false,
+          "SaveNameName": false
+        }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,163 @@
+# Search (Code Help / Lookup)
+
+검색형 선택 컨트롤. **자식 트리 보유** (`Dialog.Layouts[*].Controls[*]` = List). 키워드 검색 + DataSource 기반 lookup.
+
+## 사용 기준 (vs Combo)
+
+- **Search**: 항목 8개 초과 또는 동적으로 늘어나는 데이터 (고객/사용자/거래처/품목 등). DataSource = `Collection`/`Service`.
+- **Combo**: 8개 이하 고정 목록. DataSource = `Fixed`.
+
+## ★ 필수 체크리스트 (생성 전 반드시 확인)
+
+> Search 는 **항상 DataSource 기반**. 모델이 자주 빠뜨리는 항목 — **누락 시 schema 에러(`CollectionMapper`/`KeywordSearchCkey` 필수) 또는 런타임 빈 칸**. 값이 데이터 의존이라 자동 보정 안 됨(`KeywordSearchCkey` 만 표시필드로 보정) — 직접 채운다.
+>
+> ★ **골격만 만들지 말 것 (조회 화면 다중 Search 주의)** — 조회 화면은 검색조건 Search 를 여러 개 둔다. 각 Search 를 `ControlType` 만 있는 빈 껍데기(`Ckeys`/`DataSourceName`/`CtrlDisplayCkey` 미설정)로 두면, 같은 누락이 **컨트롤 수만큼 곱으로 폭증**한다(N개 Search → required `DataSourceName` + `[dsref]` + `[bind]` + `[display-key]` ≈ 4N 에러). **Search 하나를 끝까지 완결**(자식 List `Ckeys`+`DataSourceName`+`CollectionMapper`, 본체 `CtrlDisplayCkey`(또는 `DisplayValue`), `scenario.DataSources` 에 `Fixed`/`Grid` 정의)**한 뒤 복제**하라. ★ **본체(Search 루트)에는 `Ckeys` 를 두지 않는다** — `Ckeys` 는 자식 List 의 속성 (`[combo-body-ckeys]`).
+
+**본체 (Search 루트)**
+1. ★ 루트에는 **`Ckeys` 를 두지 않는다** — `Ckeys` 는 자식 List 의 속성 (`[combo-body-ckeys]`). 스튜디오 속성 패널에도 루트 Ckeys 입력이 없다.
+2. `CtrlDisplayCkey` (또는 비어있지 않은 `DisplayValue:"{=표시Ckey}"`) — 선택 후 표시. 비우면 빈 칸 (`[display-key]`).
+   - 루트에 `Title`/`SubTitle`/`CollectionMapper`/`Items`/`Ckeys` 두지 않기 — List 내부에만.
+
+**자식 List (`Dialog.Layouts[*].Controls[0]`)**
+3. `DataSourceName` — 선택지 데이터 소스 (**required**).
+4. `Ckeys: [값키, 표시키]` — 저장 대상 컬렉션키 (value 키 + name 키 둘 다).
+5. `CollectionMapper: { 대상Ckey: 원본필드, ... }` — `UseDataSource:true` 를 **명시하면 필수**. 매핑을 채울 수 없으면 `UseDataSource` 키를 생략한다 (런타임 default=true, 요구 안 됨). 둘 중 하나로 일관되게.
+6. `UseKeywordSearch: true` → `KeywordSearchCkey: 원본필드` (검색 대상, 보통 표시 필드). 누락 시 materialize 가 `Title` 로 보정하지만 명시 권장.
+
+## 스키마
+
+`control/search.schema.json` — `controlBase` + `inputBase` + 분기 키 (`ControlType="Search"`, `DisplayValue`, `Dialog`).
+
+내부 List 는 `_base.schema.json#/$defs/searchListControl` 가 `dialogLayout` 의 if/then 으로 자동 적용.
+
+## 예시
+
+```jsonc
+{
+  "ControlType": "Search",
+  "ControlStyle": "styleInputValueLine",
+  "ControlDefaultName": "SearchCustomer",
+  "ControlName2": "SearchCustomer",
+  "Caption": "고객 검색",
+  "Id": "f_60",
+  "Placeholder": "고객을 검색하세요",
+  "DisplayValue": "{=CustomerName}",
+  "isColumnCtrl": false,
+  "Dialog": {
+    "Layouts": [{
+      "ContentsType": "Layout",
+      "Controls": [{
+        "Id": "f_61",
+        "ControlType": "List",
+        "Title": "CompanyName",
+        "SubTitle": "ContactName",
+        "DataSourceName": "CustomerDS",
+        "UseKeywordSearch": true,
+        "KeywordSearchCkey": "CompanyName",
+        "CollectionMapper": {
+          "MapperOrder": ["CustomerNo", "CustomerName"],
+          "CustomerNo": "CustomerNo",
+          "CustomerName": "CompanyName"
+        },
+        "Ckeys": ["CustomerNo", "CustomerName"],
+        "UseMultiData": false,
+        "isColumnCtrl": false
+      }]
+    }]
+  }
+}
+```
+
+## Search ↔ List 구조 규칙
+
+**Search 루트에 두면 안 되는 키**: `Ckeys`(루트), `Dialog.Items`, `Dialog.Ckeys`, `Dialog.UseMultiData`, `CollectionMapper`(루트), `Title`(루트), `SubTitle`(루트), `PopupHeight`/`PopupWidth`. `Ckeys` 와 선택값 매핑은 자식 List 내부에서만 처리 (`[combo-body-ckeys]`).
+
+| 프로퍼티 | 위치 | 설명 |
+|---|---|---|
+| `DisplayValue` | Search 루트 | 선택 후 표시 텍스트. `"{=CkeyName}"` 형식 |
+| `CtrlDisplayCkey` | Search 루트 | (대안) 표시할 컬렉션키 등록 |
+| `Title` | List 내부 | 선택지에 표시할 **원본 데이터 필드명** |
+| `SubTitle` | List 내부 | (선택) 보조 텍스트로 표시할 원본 필드명 |
+| `CollectionMapper` | List 내부 | `{ MapperOrder, 대상Ckey: 원본필드, ... }` |
+| `Ckeys` | List 내부 | 대상 카테고리에 저장할 키 `[값키, 표시키]` |
+| `DataSourceName` | List 내부 | 선택지 데이터 소스 |
+| `UseKeywordSearch` | List 내부 | `true` 면 검색 입력 활성화 |
+| `KeywordSearchCkey` | List 내부 | 검색 대상 필드명 (`UseKeywordSearch=true` 일 때 필수) |
+| `UseMultiData` | List 내부 | 다중 선택 (대부분 false) |
+
+## ★ DisplayType / CtrlDisplayCkey / DisplayValue (Search 본체)
+
+Search 본체에 선택값을 어떻게 표시할지 결정. ★ **`DisplayType` 미지정 시 default = `"CtrlDisplayCkey"`** ([property-data.js:5705](public/javascripts/scenario-studio/property-data.js#L5705)).
+
+> ★ **필수 (`[display-key]` 검증)** — Search 는 항상 DataSource 기반이므로 본체에 `CtrlDisplayCkey` 또는 `DisplayValue` (비어있지 않은 값) 가 **반드시 함께 채워져 있어야 한다**. 둘 다 비우면 선택 후 본체가 빈 칸이 된다. 자세히는 [rules.md §5.5](../../../rules.md#55-combo--search-본체-표시-키-필수-display-key).
+
+| 모드 | 짝 키 | 의미 |
+|---|---|---|
+| `"CtrlDisplayCkey"` (default) | `CtrlDisplayCkey: "FieldName"` | 컬렉션 필드값을 그대로 표시. **표시 컬렉션키 등록 필수**. |
+| `"DisplayValue"` | `DisplayValue: "{=Field}"` 또는 `"{% JS %}"` | 표현식으로 표시 — Search 에서 가장 흔한 패턴 (i18n + 바인딩). |
+
+두 키는 **상호배타** — 모드를 정한 다음 그쪽 키만 채우고 다른 쪽은 두지 않는다.
+
+### 모드 1 — `CtrlDisplayCkey` (컬렉션키 등록 패턴)
+
+```jsonc
+{
+  "ControlType": "Search",
+  "DisplayType": "CtrlDisplayCkey",   // 생략 가능 (default)
+  "CtrlDisplayCkey": "CompanyName",   // ★ 표시 컬렉션키 등록 (Ckeys 는 자식 List 에)
+  ...
+}
+```
+
+`DisplayType` 키를 생략해도 default 가 `CtrlDisplayCkey` 라 동일 동작. `CtrlDisplayCkey` 키만 채우면 충분.
+
+### 모드 2 — `DisplayValue` (표현식, 흔한 패턴)
+
+```jsonc
+{
+  "ControlType": "Search",
+  "DisplayType": "DisplayValue",
+  "DisplayValue": "{=CustomerName}",   // 정적 바인딩
+  ...
+}
+```
+
+운영 메타에서 Search 의 표시는 다국어/포맷 처리가 많아 `DisplayValue` 모드가 자주 등장. 단순히 한 필드만 표시하면 `CtrlDisplayCkey` 가 더 짧다.
+
+## 내부 List 제한값
+
+| 키 | 제한 |
+|---|---|
+| `ControlType` | const `List` |
+| `DataSourceName` | required (Search 의 List 는 항상 DataSource 기반) |
+| `isColumnCtrl` | const `false` |
+
+조건부 강제:
+- `UseKeywordSearch=true` → `KeywordSearchCkey` 필수.
+
+## 이벤트 (제한)
+
+**Search 본체가 아니라 자식 List (`Dialog.Layouts[0].Controls[0]`) 안에 둠.** 본체에 `UseEvents`/`Events` 두면 validate.mjs `[event]` cross-check 로 차단.
+
+`Events` 는 `_base.schema.json#/$defs/searchEvents` 가 적용. `SearchOrder` enum: `change` / `Delete` / `DialogClose`.
+
+```jsonc
+{
+  "ControlType": "List",
+  "UseEvents": true,
+  "Events": {
+    "SearchOrder": ["change", "Delete", "DialogClose"],
+    "change": "ON_SEARCH_SELECTED",
+    "Delete": "ON_SEARCH_CLEARED",
+    "DialogClose": "ON_SEARCH_CLOSED"
+  }
+}
+```
+
+## 함정
+
+- Search 루트에 `Title`/`SubTitle`/`CollectionMapper` 두지 않기 — List 내부에만.
+- `KeywordSearchCkey` 는 **원본 데이터 필드명** (대상 Ckey 가 아님).
+- `UseMultiData=true` 는 거의 사용 안 함 — Search 는 단일 선택이 일반.
+- DataSource 가 Fixed 라면 Search 가 아니라 Combo 사용.
+- `Ckeys` 사용 시 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 필요.

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

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/search.schema.json",
+  "title": "Search",
+  "description": "Code Help / Lookup. 자식 트리 보유 (Dialog.Layouts[*].Controls[*] = List). 항목이 8개를 초과하거나 동적으로 늘어나는 데이터 (고객/사용자/거래처 등) 에 사용. DataSource=Collection/Service 면 Search, Fixed 면 Combo.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    { "$ref": "_base.schema.json#/$defs/inputBase" },
+    {
+      "properties": {
+        "ControlType":  { "const": "Search" },
+        "DisplayValue": {
+          "type": "string",
+          "description": "선택 후 표시 텍스트. 일반적으로 '{{=CkeyName}}' 형식 (현재 섹터의 Ckey 값 표시)."
+        },
+        "Dialog": { "$ref": "_base.schema.json#/$defs/searchDialog" }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,240 @@
+# Tab
+
+> 공식 가이드: <https://docs.flextudio.com/flextudio/scenario/component/control/tab>
+
+탭 컨트롤. 각 `Items[].LinkedStepId` 로 **다른 Step 의 전체 UI** 를 탭 내부에 렌더링한다.
+
+## 어떤 케이스에 쓰는가
+
+| 상황 | 추천 |
+|---|---|
+| 같은 리스트를 **필터만 변경** (내 결재/내 신청 등) | **RadioBox + ControlStyle:"styleTab"** (RadioBox.md 참조) |
+| 탭마다 약간의 컨텐츠 show/hide | RadioBox + styleTab |
+| **탭마다 완전히 다른 화면 레이아웃** | **Tab 컨트롤 + 별도 Step** |
+
+탭 전환 시 화면이 거의 통째로 바뀌는 경우에만 Tab 컨트롤을 쓴다.
+
+## 스키마
+
+`control/tab.schema.json` — `controlBase` + Tab 분기 키.
+
+## 필수 / 핵심 속성
+
+| 속성 | 비고 |
+|---|---|
+| `ControlType` | const `"Tab"`. |
+| `Height` | **반드시 `{ SizeValue: "100", SizeUnit: "%", MatchText: false }`**. 고정 px 면 LinkedStep 콘텐츠가 잘림. |
+| `Items[]` | 탭 항목 배열 (`minItems: 1`). 각 항목 `ItemName / ItemValue / LinkedStepId` 필수. |
+| `Items[].LinkedStepId` | 이 탭이 선택되었을 때 렌더할 Step Id. **자기 자신 Step 금지** (무한 재귀). |
+| `Items[].Events.Click` | 탭 클릭 시 실행할 이벤트 (선택). |
+| `Ckeys` | 선택 탭의 ItemValue 저장 키 (선택). |
+| `DefaultValue` | **초기 선택 탭값** — `Items[].ItemValue` 와 일치하는 항목이 선택 상태로 시작. (`""`/미지정 → 첫 항목.) string strict. |
+| `TabHeader` / `SelectTabHeader` / `TabHeaderItem` / `SelectTabHeaderItem` | 헤더 디자인 (선택). |
+
+## 초기 선택값 — `DefaultValue`
+
+| 값 | 동작 |
+|---|---|
+| `""` / 미지정 | 첫 번째 `Items` 항목 자동 선택. |
+| `Items[].ItemValue` 중 하나와 일치 | 해당 항목 선택 상태로 시작. |
+| `Items[].ItemValue` 와 어느 것도 일치 안 함 | 운영 메타에서는 fallback 으로 첫 항목 — **AI 생성 시 반드시 Items[].ItemValue 중 하나와 동일하게**. |
+
+`Ckeys` 와 함께 쓰면, 부모 Group 의 카테고리 필드(=`Ckeys[0]`) 초기값이 `DefaultValue` 로 set 되고, 이후 사용자가 다른 탭을 누르면 그 항목의 `ItemValue` 가 같은 ckey 에 저장.
+
+### ⚠️ DefaultValue 로 초기 선택된 LinkedStep 도 Step 이벤트 미실행
+
+`DefaultValue` 가 가리키는 항목의 `LinkedStepId` 가 진입과 동시에 렌더되지만, **그 Step 의 `Init` / `Loaded` / `OnBackLoaded` / `OnLeave` / `OnForeground` / `ScrollEnd` 은 모두 실행되지 않는다** (Tab 컨트롤 일반 제약 — 아래 "Tab 내부 Step 의 동작 제약" 동일).
+
+| 시점 | 무엇이 일어나는가 | 어디서 처리하는가 |
+|---|---|---|
+| Tab 진입 + `DefaultValue` 매칭 항목 렌더 | LinkedStep UI 만 그려짐, Step 이벤트 미발생 | **부모 Step(Tab 이 있는 Step) Init** 에서 모든 카테고리/리스트 로딩 |
+| 사용자가 다른 탭 클릭 | 새 LinkedStep UI 렌더, Step 이벤트 미발생 | `Items[].Events.Click` 핸들러에서 reload / 필터 변경 |
+
+> **CRITICAL:** "`DefaultValue` 가 있으니 그 Step 의 `Init` 이 한 번은 돌겠지" — **돌지 않는다.** 초기 데이터 로딩까지 모두 부모 Step Init 에서 끝내라. `DefaultValue` 항목에 대응하는 `Items[].Events.Click` 은 사용자가 *명시적으로 그 탭을 다시 누른* 경우에만 동작 (자동 미발화).
+
+```jsonc
+{
+  "ControlType": "Tab",
+  "Ckeys":        ["MenuType"],
+  "DefaultValue": "HOME",
+  "Items": [
+    { "ItemName": "HOME",   "ItemValue": "HOME",   "LinkedStepId": "Step2" },
+    { "ItemName": "COFFEE", "ItemValue": "COFFEE", "LinkedStepId": "Step4", "Events": { "Click": "Query_CategoryMenu" } }
+  ],
+  "...": "..."
+}
+```
+
+→ 진입 시 `HOME` 탭이 선택된 상태로 시작, `Step2` UI 가 렌더. 이때 `Step2.Events.Init` 은 **호출되지 않음**. `HOME` 의 데이터가 필요하면 Tab 이 있는 부모 Step 의 `Init` 에서 같이 로딩.
+
+## 부모 / 형제 제약
+
+- Tab 의 부모 Group 도 **Height 100%** 여야 한다.
+- Tab 은 해당 Step Contents 의 **유일한 컨트롤**. 같은 레벨에 다른 컨트롤을 두면 100% 높이에 밀려 보이지 않는다 — 필터/검색바 등 부가 UI 는 각 LinkedStep 내부에 배치.
+- **조상 Group 에 `UseMove:true` 금지** (`[tab-move]`) — 탭을 감싸는 어떤 조상 Group 이든 `UseMove:true` 가 있으면 탭 헤더 클릭이 그 Group 의 Step 이동을 트리거해 **탭 전환 대신 화면이 넘어가 버린다.** 탭 안에서 다른 화면 이동이 필요하면 각 LinkedStep 내부 Button/Label 컨트롤로 처리. validate.mjs / core 의 `checkTabAncestorMove()` 가 후검증 (`strict_tab_move:false` 로 비활성).
+
+## ★ Tab 내부 Step 의 동작 제약 (공식 가이드 인용)
+
+> "탭 컨트롤은 일반 스텝에서 제공하는 기능이 적용되지 않습니다. 따라서 **스텝버튼을 그려주지 않으며 스텝 이벤트도 실행되지 않습니다.** 서브시나리오 스텝은 탭 컨트롤에서 보여줄 수 없습니다."
+> — flextudio 공식 문서 (Tab)
+
+이로부터 따라오는 실무 규칙:
+
+| 항목 | 동작 | 설계 시 적용 |
+|---|---|---|
+| **StepButton (스텝 하단 버튼)** | 그려지지 않음 | 저장/취소 등 액션은 LinkedStep 내부에 일반 Button/Label 컨트롤로 배치. |
+| **Step Events** (`Init` / `Loaded` / `OnBackLoaded` / `OnLeave` / `OnForeground` / `ScrollEnd`) | **모두 미실행** | LinkedStep 의 Init 에 데이터 로딩 로직 두면 동작하지 않음 → **부모 Step (Tab 이 있는 Step) 의 Init** 에서 모든 카테고리/리스트를 한 번에 로딩. |
+| **카테고리 초기화** | LinkedStep Init 미실행 → `removeCategory + createCategory` 패턴 사용 불가 | 카테고리 초기화/추가 로직 역시 부모 Step Init 에 통합. |
+| **서브시나리오 Step** | 표시 불가 | `LinkedStepId` 에 `StepType: "StepSub"` 인 Step 지정 금지. |
+| **데이터 변경 트리거** | LinkedStep 진입 자체로는 발생 안 함 | 탭 전환 시 동작이 필요하면 **`Items[].Events.Click`** 에 핸들러를 두고, 그 안에서 reload/필터 변경. |
+| **Reachability** | LinkedStep 도 host Step 의 `Next` 에 있어야 함 | `Items[].LinkedStepId` 로 띄우는 Step 도 host Step 의 `Next` 에 포함되어야 도달로 인정 (`[reach]`). **`Next` 연결이 없으면 화면에 안 그려진다.** 탭은 `Next` 요구를 면제하지 않음 — 면제하는 건 아래 이동 트리거(`[step-nav]`)뿐. |
+| **이동 트리거** | LinkedStep 은 `UseMove`/`BottomButton` 트리거 불요 | `Step.Next` 타깃이 탭으로 연결돼 있으면 탭 헤더 클릭이 곧 트리거 — `[step-nav]` 가 `Items[].LinkedStepId` 를 트리거 후보로 인정. |
+
+### ⛔ 탭 내부 LinkedStep 에는 Embed 컨트롤 금지 (`[tab-embed]`)
+
+Step 이벤트(`Init`/`Loaded`)가 미실행이므로, **LinkedStep 안에 `Embed` 컨트롤을 두면 초기화/렌더 시점을 잡을 수 없다** (예: 통계 탭에 차트 Embed). Embed 는 보통 Step 의 `Loaded`/`Init` 에서 DOM 을 조작해 초기화하는데, 탭 내부 Step 에서는 그 이벤트가 돌지 않아 **빈 영역만 그려지거나 차트/지도/QR 이 안 뜬다.**
+
+- 탭 내부에 렌더되는 Step(= 어떤 `Items[].LinkedStepId` 의 대상)의 Contents 트리에 `Embed` 가 있으면 `checkTabLinkedStepEmbed()` 가 거부 (`[tab-embed]`, `strict_tab_embed:false` 로 비활성).
+- Embed 가 필요한 화면(통계/지도/차트 등)은 **탭이 아닌 별도 Step** 으로 분리하거나, RadioBox+`ControlStyle:"styleTab"` 의 show/hide 로 구성.
+
+> **CRITICAL — LinkedStep 의 Init/Loaded 에 의존 금지:** LinkedStep 안에서 Step Event 가 동작한다고 가정하고 메타를 짜면 데이터가 비어 있는 화면이 그려진다. 모든 초기화는 부모 Step Init + `Items[].Events.Click` 조합으로 분산하라.
+
+## 예시
+
+```jsonc
+{
+  "ContentsName": "TabWrap",
+  "ContentsType": "Group",
+  "Height": { "SizeValue": "100", "SizeUnit": "%", "MatchText": false },
+  "Width":  { "SizeValue": 100,   "SizeUnit": "%" },
+  "UseDataConnection": true,
+  "DataConnection": { "TargetType": "category", "CategoryName": "cafeUser" },
+  "Id": "f_154821",
+  "Contents": [{
+    "ControlType": "Tab",
+    "ControlStyle": "None",
+    "ControlDefaultName": "Tab1",
+    "ControlName2": "Tab1",
+    "Caption": "",
+    "Id": "f_154822",
+    "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+    "Height": { "SizeValue": "100", "SizeUnit": "%", "MatchText": false },
+    "isColumnCtrl": false,
+    "Ckeys":        ["MenuType"],
+    "DefaultValue": "HOME",
+    "Items": [
+      { "ItemName": "HOME",   "ItemValue": "HOME",   "LinkedStepId": "Step2", "Events": { "Click": "TapHomeLoaded"      } },
+      { "ItemName": "COFFEE", "ItemValue": "COFFEE", "LinkedStepId": "Step4", "Events": { "Click": "Query_CategoryMenu" } },
+      { "ItemName": "DRINK",  "ItemValue": "DRINK",  "LinkedStepId": "Step4", "Events": { "Click": "Query_CategoryMenu" } },
+      { "ItemName": "BOTTLE", "ItemValue": "BOTTLE", "LinkedStepId": "Step4", "Events": { "Click": "Query_CategoryMenu" } }
+    ],
+    "TabHeader": {
+      "ArrangeItemsStyle": { "UseArrangeItems": true, "ArrangeItemsType": "EqualDistribution" }
+    },
+    "SelectTabHeader": {},
+    "TabHeaderItem":      { "FontStyle": {} },
+    "SelectTabHeaderItem":{ "FontStyle": {} }
+  }]
+}
+```
+
+## 디자인 — 헤더 4종 슬롯
+
+탭 헤더 영역의 외형은 4개 디자인 객체로 분리되어 있고, 각각 스코프가 다르다. 슬롯 안의 하위 키는 모두 공용 [style-objects](../style-objects.md) 의 $def 를 그대로 사용.
+
+| 슬롯 | 스코프 | 사용 키 |
+|---|---|---|
+| `TabHeader` | 헤더 **컨테이너** (아이템들을 감싸는 띠) | `ArrangeItemsStyle` / `Padding` / `Margin` / `BorderStyle` / `BgStyle` |
+| `SelectTabHeader` | 선택 상태 컨테이너 | 동일 (보통 비워둠 — 선택 강조는 `SelectTabHeaderItem` 에서) |
+| `TabHeaderItem` | **각 항목**(미선택) | `FontStyle` / `Padding` / `Margin` / `BorderStyle` / `BgStyle` |
+| `SelectTabHeaderItem` | 선택된 항목 | `FontStyle` / `BgStyle` / `BorderStyle` (보통 Padding/Margin 은 TabHeaderItem 값 상속) |
+
+### `ArrangeItemsStyle` (TabHeader/SelectTabHeader 전용)
+
+| 키 | 값 | 의미 |
+|---|---|---|
+| `UseArrangeItems` | boolean | 정렬 옵션 사용 여부 |
+| `ArrangeItemsType` | `"MatchText"` / `"EqualDistribution"` / `"Fixed"` | 항목 너비 정책 — 텍스트 폭에 맞춤 / 균등 분배 / 고정 |
+| `ArrangeItemsAlign` | `"Left"` / `"Center"` / `"Right"` / `"Between"` | 컨테이너 안 정렬 |
+
+### 디자인 풀 폼 예시 (운영 메타 실사용 형태)
+
+```jsonc
+{
+  "ControlType": "Tab",
+  "ControlStyle": "None",
+  "ControlName2": "Tab1",
+  "Caption": "Tab1",
+  "Id": "f_4187",
+  "Width":  { "SizeValue": "100", "SizeUnit": "%" },
+  "Height": { "SizeValue": "400", "SizeUnit": "px" },
+  "isColumnCtrl": false,
+  "Items": [
+    { "ItemName": "", "ItemValue": "", "LinkedStepId": "undefined" }
+  ],
+  "TabHeader": {
+    "ArrangeItemsStyle": {
+      "UseArrangeItems":   true,
+      "ArrangeItemsType":  "MatchText",
+      "ArrangeItemsAlign": "Left"
+    },
+    "Padding":     { "UseAuto": true },
+    "Margin":      { "UseAuto": true },
+    "BorderStyle": { "Useborder": true },
+    "BgStyle":     { "UseBackground": true }
+  },
+  "SelectTabHeader": {},
+  "TabHeaderItem": {
+    "FontStyle":   { "UseFont": true },
+    "Padding":     { "UseAuto": true },
+    "Margin":      { "UseAuto": true },
+    "BorderStyle": { "Useborder": true },
+    "BgStyle":     { "UseBackground": true }
+  },
+  "SelectTabHeaderItem": {
+    "FontStyle":   { "UseFont": true },
+    "BgStyle":     { "UseBackground": true },
+    "BorderStyle": { "Useborder": true }
+  }
+}
+```
+
+> `Use*` 류 boolean 은 strict — 문자열 `"true"`/`"false"` 금지 (JS truthy 함정). 운영 메타에 잔존 string 형태가 있으면 boolean 으로 마이그레이션. property-data.js `EditControl(EDITOR_CTRL.CHECKBOX)` 진실원본.
+
+## 이벤트
+
+Tab 본체에는 별도 Events 객체가 없고, **각 `Items[].Events.Click`** 으로 항목별 핸들러를 둔다. (validate.mjs 의 control event cross-check 도 항목 단위로 동작.)
+
+## 후검증 (validate.mjs `[tab]`)
+
+스키마로 표현 불가한 cross-reference 는 `validate.mjs` 의 `checkTabLinkedSteps()` 가 검증. 실패 시 `[tab]` 태그로 보고.
+
+| 검증 | 조건 | 메시지 형태 |
+|---|---|---|
+| LinkedStepId 존재 | `Items[].LinkedStepId` 가 `scenario.Steps` 에 정의됨 | `references unknown Step` |
+| 자기 참조 금지 | `Items[].LinkedStepId` ≠ host Step Id | `references its own host Step — infinite recursion` |
+| StepSub 금지 | 가리키는 Step 의 `StepType ≠ "StepSub"` | `points to a StepSub — subscenario Step cannot be rendered inside Tab` |
+| DefaultValue 매칭 | `DefaultValue` 가 `""` 가 아니면 `Items[].ItemValue` 중 하나와 일치 | `does not match any Items[].ItemValue` |
+
+> **`[reach]`** — `Items[].LinkedStepId` 로 띄우는 Step 도 **host Step 의 `Next` 에 포함되어야** 도달로 인정된다(탭은 `Next` 요구를 면제하지 않음). `Next` 연결이 없으면 안 그려지고 `[reach]` 가 고아로 거부.
+>
+> **`[step-nav]` (core `checkStepNavigationSources`)** — `Step.Next` 타깃이 같은 Step 안의 `Tab.Items[].LinkedStepId` 로 연결돼 있으면 이동 트리거 충족으로 인정 (탭 헤더 클릭이 트리거). 즉 탭 연결 Step 에는 `UseMove`/`BottomButton` 을 따로 안 만들어도 됨.
+>
+> **`[tab-move]` (core `checkTabAncestorMove` / validate.mjs)** — Tab 의 조상 Group 에 `UseMove:true` 가 있으면 거부. `strict_tab_move:false` 로 비활성.
+>
+> **`[tab-embed]` (core `checkTabLinkedStepEmbed` / validate.mjs)** — `Items[].LinkedStepId` 로 띄우는 Step 의 Contents 트리에 `Embed` 컨트롤이 있으면 거부. `strict_tab_embed:false` 로 비활성.
+
+## 함정
+
+- **Height 100% 누락** — `48px` 같은 고정 높이를 주면 헤더만 보이고 LinkedStep 콘텐츠가 사라진다.
+- **`LinkedStepId` 자기 참조** — Tab 이 들어있는 Step 자신을 가리키면 무한 재귀(`Maximum call stack size exceeded`). validate.mjs `[tab]` 차단.
+- **부모/형제 레이아웃 미준수** — 부모 Group Height 가 100% 가 아니거나, 같은 레벨에 다른 컨트롤이 있으면 콘텐츠 영역이 깨진다.
+- **LinkedStep Step Event 미실행** — 위 "Tab 내부 Step 의 동작 제약" 참조. 데이터 로딩/초기화는 부모 Step Init 에 두고, 탭 전환 시 동작이 필요하면 `Items[].Events.Click` 활용.
+- **`DefaultValue` 진입에서도 Step Event 미실행** — 초기 선택된 LinkedStep 의 `Init`/`Loaded` 가 한 번이라도 돌 것이라 가정하지 말 것. 모든 초기 로딩은 부모 Step Init 에서 끝낼 것. `DefaultValue` 와 매칭되는 항목의 `Items[].Events.Click` 도 자동 발화하지 않음(사용자 클릭 시에만).
+- **`DefaultValue` 값 불일치** — `Items[].ItemValue` 중 어느 것과도 일치하지 않는 `DefaultValue` 는 운영 메타에서는 첫 항목 fallback 으로 동작하지만 의도치 않은 동작 — AI 생성 시 반드시 일치하는 ItemValue 로.
+- **StepButton 미렌더** — LinkedStep 에 BottomButton 정의해도 그려지지 않음. 저장/취소는 LinkedStep 내부 컨트롤로 직접 그릴 것.
+- **샘플 데이터 위치** — Tab + LinkedStep 구조의 모든 샘플 데이터(리스트, 필터 등)는 **부모 Step (Tab 이 있는 Step) 의 Init** 에서 한 번에 로딩. LinkedStep 의 Init 에 두면 탭 전환마다 `removeCategory + createCategory` 로 데이터가 초기화된다 (Init 자체가 미실행이므로).
+- **서브시나리오 Step 사용 금지** — `LinkedStepId` 에 `StepType: "StepSub"` 인 Step 지정 금지.
+- **조상 Group UseMove 금지** — 탭을 감싸는 Group 에 `UseMove:true` 가 있으면 탭 클릭이 Step 이동을 트리거. `[tab-move]` 차단. 위 "부모/형제 제약" 참조.
+- **탭 내부 LinkedStep 에 Embed 금지** — Step 이벤트 미실행으로 초기화 시점을 못 잡아 차트/지도 등이 안 뜬다. `[tab-embed]` 차단. 위 "탭 내부 LinkedStep 에는 Embed 컨트롤 금지" 참조.
+- 단순 필터 전환에는 RadioBox + `ControlStyle: "styleTab"` 사용 — Tab 컨트롤은 화면 자체가 바뀌는 경우 전용.

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

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/tab.schema.json",
+  "title": "Tab",
+  "description": "탭 컨트롤. 각 Items[].LinkedStepId 로 다른 Step 의 전체 UI 를 탭 내부에 렌더링한다. (탭마다 화면 전체가 바뀌는 경우 전용. 같은 리스트의 필터만 바뀌는 케이스는 RadioBox + ControlStyle:'styleTab' 권장.) Height 는 반드시 100% — 헤더 높이만 주면 LinkedStep 콘텐츠가 표시되지 않는다. Items[].LinkedStepId 가 자기 자신 Step 을 가리키면 무한 재귀. 핵심 제약: '탭 컨트롤은 일반 스텝에서 제공하는 기능이 적용되지 않는다 → 스텝버튼이 그려지지 않고 스텝 이벤트(Init/Loaded/OnBackLoaded/OnLeave/OnForeground/ScrollEnd)가 실행되지 않으며 서브시나리오 스텝은 표시할 수 없다.'",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "Tab" },
+        "ControlStyle": {
+          "type": "string",
+          "examples": ["", "None"],
+          "description": "기본 'None'."
+        },
+
+        "Height": {
+          "$ref": "../style-objects.schema.json#/$defs/sizeObject",
+          "description": "반드시 100% — `{ SizeValue: '100', SizeUnit: '%', MatchText: false }`. 고정 px 면 탭 헤더만 보이고 LinkedStep 콘텐츠가 잘림. (validate.mjs 후검증으로도 강제.)"
+        },
+
+        "DefaultValue": {
+          "type": "string",
+          "default": "",
+          "description": "초기 선택 탭의 값. Items[].ItemValue 와 일치하는 항목이 시작 시 선택 상태로 그려진다. 빈 문자열/미지정 시 첫 번째 Items 항목이 선택. ★ 초기 선택으로 LinkedStep 이 렌더되더라도 그 Step 의 Step 이벤트(Init/Loaded/OnBackLoaded/OnLeave/OnForeground/ScrollEnd)는 실행되지 않음 — Tab 컨트롤의 일반 제약(공식 가이드). 따라서 초기 데이터 로딩은 부모 Step(Tab 이 있는 Step) 의 Init 에서 처리하고, 탭 전환 시 동작이 필요하면 Items[].Events.Click 에 둔다. controlBase.DefaultValue 의 any 타입을 Tab 에서 string 으로 좁힘 (ItemValue 가 항상 string)."
+        },
+        "Items": {
+          "type": "array",
+          "minItems": 1,
+          "description": "탭 항목 배열. 각 항목이 하나의 탭 헤더 + 연결된 Step.",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["ItemName", "ItemValue", "LinkedStepId"],
+            "properties": {
+              "ItemName":     { "type": "string", "description": "탭 헤더 표시 텍스트. 필요시 `{{}}` 다국어." },
+              "ItemValue":    { "type": "string", "description": "선택 시 Ckeys 에 저장되는 값." },
+              "LinkedStepId": { "type": "string", "pattern": "^Step[1-9][0-9]*$", "description": "이 탭이 선택되었을 때 내부에 렌더할 Step Id. 자기 자신 Step 금지 (무한 재귀)." },
+              "Events": {
+                "type": "object",
+                "additionalProperties": true,
+                "description": "탭 항목 단위 이벤트. Click 핸들러 1종.",
+                "properties": {
+                  "Click": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+
+        "Ckeys": {
+          "$ref": "../naming-objects.schema.json#/$defs/ckeysArray",
+          "description": "선택된 탭의 ItemValue 가 저장될 컬렉션 키 (선택). 시스템 게터 / JS 빌트인 차단."
+        },
+
+        "TabHeader": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "탭 헤더 전체 영역(아이템들을 감싸는 컨테이너) 디자인. 정렬·여백·테두리·배경.",
+          "properties": {
+            "ArrangeItemsStyle": { "$ref": "../style-objects.schema.json#/$defs/arrangeItemsStyle" },
+            "Padding":           { "$ref": "../style-objects.schema.json#/$defs/spacing" },
+            "Margin":            { "$ref": "../style-objects.schema.json#/$defs/spacing" },
+            "BorderStyle":       { "$ref": "../style-objects.schema.json#/$defs/borderStyle" },
+            "BgStyle":           { "$ref": "../style-objects.schema.json#/$defs/bgStyle" }
+          }
+        },
+        "SelectTabHeader": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "선택 상태의 탭 헤더 컨테이너 디자인. TabHeader 와 동일 슬롯. 보통 비워두고 SelectTabHeaderItem 으로 항목별 강조를 처리.",
+          "properties": {
+            "ArrangeItemsStyle": { "$ref": "../style-objects.schema.json#/$defs/arrangeItemsStyle" },
+            "Padding":           { "$ref": "../style-objects.schema.json#/$defs/spacing" },
+            "Margin":            { "$ref": "../style-objects.schema.json#/$defs/spacing" },
+            "BorderStyle":       { "$ref": "../style-objects.schema.json#/$defs/borderStyle" },
+            "BgStyle":           { "$ref": "../style-objects.schema.json#/$defs/bgStyle" }
+          }
+        },
+        "TabHeaderItem": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "각 탭 항목 헤더(미선택 상태) 디자인. 폰트·여백·테두리·배경.",
+          "properties": {
+            "FontStyle":   { "$ref": "../style-objects.schema.json#/$defs/fontStyle" },
+            "Padding":     { "$ref": "../style-objects.schema.json#/$defs/spacing" },
+            "Margin":      { "$ref": "../style-objects.schema.json#/$defs/spacing" },
+            "BorderStyle": { "$ref": "../style-objects.schema.json#/$defs/borderStyle" },
+            "BgStyle":     { "$ref": "../style-objects.schema.json#/$defs/bgStyle" }
+          }
+        },
+        "SelectTabHeaderItem": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "선택된 탭 항목 헤더 디자인. 보통 FontStyle / BgStyle / BorderStyle 만 사용 (선택 강조). Padding/Margin 은 TabHeaderItem 값을 그대로 상속.",
+          "properties": {
+            "FontStyle":   { "$ref": "../style-objects.schema.json#/$defs/fontStyle" },
+            "BgStyle":     { "$ref": "../style-objects.schema.json#/$defs/bgStyle" },
+            "BorderStyle": { "$ref": "../style-objects.schema.json#/$defs/borderStyle" },
+            "Padding":     { "$ref": "../style-objects.schema.json#/$defs/spacing" },
+            "Margin":      { "$ref": "../style-objects.schema.json#/$defs/spacing" }
+          }
+        },
+        "ArrangeItems": { "type": "string", "description": "(레거시) 탭 헤더 정렬/배치 옵션 — 운영 메타 잔존 호환. 신규 생성은 TabHeader.ArrangeItemsStyle 사용." }
+      },
+      "required": ["Items"]
+    }
+  ]
+}