@flextudio/scenario 0.1.0

package/skill/docs/control/input-mask.md

@@ -0,0 +1,89 @@
+# InputMask
+
+마스크 패턴 입력. `InputType` 으로 시간/통화/날짜/전화 처리.
+
+## 스키마
+
+`control/input-mask.schema.json` — `controlBase` + `inputBase` + 분기 키 (`ControlType="InputMask"`, `InputType`, `MaskType`, `UseNumberOnly`, `UseFixedDecimalPlaces`, `DecimalPlaces`, `RoundingMode`).
+
+## 제한값
+
+### `InputType`
+스키마 enum 으로 강제.
+
+| 값 | 의미 |
+|---|---|
+| `hhmm` | 시간 HH:MM |
+| `money` | 통화 (천단위 콤마). `UseNumberOnly: true` 권장 (필수 아님) |
+| `yyyymmdd` | 날짜 YYYY-MM-DD |
+| `phone` | 전화번호 패턴 |
+
+> `InputType` 은 위 4 enum 만 지원. 4종 외 패턴이 필요하면 다른 컨트롤 (`InputText` + 검증 등) 로 우회.
+
+### `MaskType`
+스키마 enum 으로 강제. 마스크 카테고리 표시용. `InputType` 과 정합되어야 함.
+
+| 값 | 짝 InputType |
+|---|---|
+| `Time` | `hhmm` |
+| `Money` | `money` |
+| `Date` | `yyyymmdd` |
+| `Phone` | `phone` |
+
+## 예시 — 시간
+
+```jsonc
+{
+  "ControlType": "InputMask",
+  "ControlStyle": "styleInputValueLine",
+  "ControlDefaultName": "StartTime",
+  "ControlName2": "StartTime",
+  "InputType": "hhmm",
+  "Placeholder": "18:00",
+  "Caption": "{{시작시간}}",
+  "Id": "f_32",
+  "Ckeys": ["StartTime"],
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — 통화
+
+```jsonc
+{
+  "ControlType": "InputMask",
+  "InputType": "money",
+  "UseNumberOnly": true,
+  "DisplayValue": "",
+  "Ckeys": ["Price"],
+  "ControlDefaultName": "Price",
+  "ControlName2": "Price",
+  "Caption": "{{금액}}",
+  "Id": "f_33",
+  "isColumnCtrl": false,
+  "FontStyle": { "UseFont": true, "FontAlign": "flex-end", "FontSize": "14" }
+}
+```
+
+## 데이터 바인딩
+
+`Ckeys` 사용 시 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 필요.
+
+## 이벤트 (제한)
+
+`Events` 는 `_base.schema.json#/$defs/inputEventsChangeOnly` 적용. **`change` 만 지원** (InputNumber 와 동일). `input` / `focusin` / `focusout` 사용 불가.
+
+```jsonc
+{
+  "UseEvents": true,
+  "Events": {
+    "InputEventOrder": ["change"],
+    "change": "ON_TIME_CHANGED"
+  }
+}
+```
+
+## 함정
+
+- `money` 는 표시는 콤마 포함, 저장값은 숫자 문자열.
+- `hhmm` 은 24시간 형식 — AM/PM 자동 변환 없음.

package/skill/docs/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/skill/docs/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/skill/docs/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/skill/docs/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/skill/docs/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` 필요.