@flextudio/scenario 0.1.0

package/skill/docs/bottom-buttons.md

@@ -0,0 +1,155 @@
+# BottomButtons
+
+Step 의 **하단 고정 버튼 채널**. `Step.BottomButtons` 배열의 각 항목 = 하나의 `BottomButton` 객체.
+
+## 식별
+
+- 위치: `Scenario.Steps[StepId].BottomButtons[*]`
+- 토글: 같은 Step 의 `UseBottomButton: true` (false 면 빈 배열만 허용)
+- 부모: **Step 의 직접 자식**. `Contents` / `FixedContentsTop` / `FixedContentsBottom` 의 자식 아님.
+- StepSub 에서는 `UseBottomButton: false` 자동 강제 → BottomButtons 사용 불가.
+
+## 스키마
+
+`bottom-buttons.schema.json` — 단일 BottomButton 객체 정의. Step 스키마는 `BottomButtons: { type: "array", items: { $ref: "bottom-buttons.schema.json" } }` 로 합성.
+
+## 핵심 필드
+
+| 키 | 타입 | 비고 |
+|---|---|---|
+| `Id` | `f_숫자` | 🔴 필수, 시나리오 전체 유일 |
+| `ButtonName` | string | 화면 표시 텍스트, 다국어 `{{}}` 권장 |
+| `MoveTo` | enum | `Next` \| `None` \| `Prev` \| `Prev_ReStart` \| `Init` |
+| `Next` | object | `MoveTo="Next"` 일 때 **필수**. `{ MoveStepOrder: ["StepN"], StepN: "" }` — **슬롯 값은 빈 문자열** |
+| `Prev` | object | `MoveTo="Prev"` / `"Prev_ReStart"` 일 때 **필수**. `{ MoveStepOrder: [] }` |
+| `Direction` | string | 네비게이션 방향 보조값. Next 버튼 canonical emit 은 `""` |
+| `IsRestored` | bool / `""` | 콜렉션 이전 상태로 복원 (취소/Prev 흐름). Flextudio canonical emit 은 `""` |
+| `IsIgnoreRequired` | bool | `MoveTo="Next"` 시 필수입력 검증 무시 여부. Flextudio Next 버튼 canonical emit |
+| `IsRequired` | bool | `MoveTo="Prev"`/`"Prev_ReStart"` 시 필수입력 보존 여부 |
+| `Events` | object | `{ "Click": "핸들러명" }`. UseEvents 토글 없이 직접 사용 |
+| `LoadScript` | string | 동적 표시/숨김 (`f.bottom().style().display(...)`) |
+| `Width`, `Height` | sizeObject | 버튼 크기 |
+| `Padding`, `Margin` | spacing | 여백 |
+| `BgStyle`, `FontStyle`, `BorderStyle` | style | 시각 스타일 |
+| `ImageStyle` | object | ⚠️ **렌더링 시 적용 제외** (`bottombuttons.js`). 신규 생성 시 누락 권장 |
+| `UseFixedSize` | bool | 고정 크기 사용 |
+| `UseDesign` | bool | 디자인 묶음 적용 |
+
+## MoveTo 분기 규칙 (상호배타)
+
+| MoveTo | 동작 | top-level 키 (반드시) | top-level 키 (금지) |
+|---|---|---|---|
+| `Next` | 다음 Step 으로 이동 | `Next.MoveStepOrder` (1개 이상) + 각 StepN 슬롯 `""` | `Prev` |
+| `Prev` | 이전 Step 으로 이동 | `Prev` (보통 `{ MoveStepOrder: [] }`) | `Next` |
+| `Prev_ReStart` | 이전 Step 이동 + 재시작 | `Prev` | `Next` |
+| `None` | 이동 없음, 이벤트만 실행 | (없음) — `Events.Click` 권장 | — |
+| `Init` | 시나리오 처음 Step 이동 | (없음) | — |
+
+> ⚠️ **Next 버튼에 placeholder Prev 박지 말 것**. 그 반대도 마찬가지. Flextudio 스튜디오는 한 쪽만 emit 한다.
+
+## 핵심 함정 (LLM 생성 실패 사례)
+
+1. **`Next.Step{N}` 슬롯 값이 빈 객체 `{}` 가 아니라 빈 문자열 `""`**:
+   ```jsonc
+   // ❌ 잘못됨 — schema 거부
+   "Next": { "MoveStepOrder": ["Step2"], "Step2": {} }
+
+   // ✅ canonical
+   "Next": { "MoveStepOrder": ["Step2"], "Step2": "" }
+   ```
+   문자열을 받는 이유는 조건/Direction 등 향후 슬롯 확장 여지가 있기 때문 (현재 엔진 emit 은 `""`).
+
+2. **MoveTo=Next 인데 placeholder `Prev: { MoveStepOrder: [] }` 까지 emit** → schema 거부.
+
+3. **MoveTo=Next 인데 `Direction` / `IsIgnoreRequired` 누락** — schema 가 강제하진 않지만 Flextudio canonical 형태에 맞추려면 함께 emit.
+
+## Canonical 키 순서 (Flextudio emit 순서)
+
+JSON 자체는 키 순서를 강제하지 않지만, 가능하면 Flextudio 스튜디오 emit 순서로 작성:
+
+```
+Id → ButtonName → MoveTo → (스타일 키: Width/Height/Padding/Margin/BgStyle/BorderStyle/FontStyle)
+   → IsRestored → IsIgnoreRequired → Direction → Next | Prev
+```
+
+## 예시
+
+### 1) 다음 Step 으로 이동 (canonical)
+
+```jsonc
+{
+  "Id": "f_7",
+  "ButtonName": "{{등록}}",
+  "MoveTo": "Next",
+  "Width": { "SizeValue": 100, "SizeUnit": "%" },
+  "BgStyle": { "UseBackground": true, "BgColor": "var(--colorMain)" },
+  "IsRestored": "",
+  "IsIgnoreRequired": false,
+  "Direction": "",
+  "Next": {
+    "MoveStepOrder": ["Step2"],
+    "Step2": ""
+  }
+}
+```
+
+### 2) 이전 Step (저장 후 복귀)
+
+```jsonc
+{
+  "Id": "f_13",
+  "ButtonName": "{{취소}}",
+  "MoveTo": "Prev",
+  "Width": { "SizeValue": 100, "SizeUnit": "%" },
+  "IsRestored": "",
+  "Prev": { "MoveStepOrder": [] }
+}
+```
+
+### 3) 이벤트만 실행 (이동 없음)
+
+```jsonc
+{
+  "Id": "f_2",
+  "ButtonName": "{{승인}}",
+  "MoveTo": "None",
+  "Events": { "Click": "saveAndApprove" }
+}
+```
+
+## Step 트리에서의 위치
+
+```
+Steps[StepN]
+├── UseBottomButton: true        ← 토글
+├── StepButton: { ... }          ← 영역(컨테이너) 스타일
+├── BottomButtons: [             ← 본 스키마
+│     { Id, ButtonName, MoveTo, ... },
+│     ...
+│   ]
+├── Contents: [...]              ← 별개 (메인 영역)
+├── FixedContentsTop: [...]
+└── FixedContentsBottom: [...]
+```
+
+`StepButton` 은 BottomButtons 영역 자체(컨테이너)의 스타일 묶음이며, 개별 버튼은 BottomButtons 배열의 각 항목이 본인 스타일(`BgStyle` 등)을 따로 가진다.
+
+## 제약
+
+1. **Id 유일성**: 시나리오의 모든 컨트롤/버튼과 충돌 금지 (`^f_[1-9][0-9]*$`).
+2. **StepSub 금지**: StepSub Step 은 자체 화면이 없으므로 BottomButtons 비어있어야 함.
+3. **MoveTo 별 키 상호배타**: `MoveTo="Next"` 이면 top-level `Next` 만, `MoveTo="Prev"/"Prev_ReStart"` 이면 top-level `Prev` 만 (반대편 키 emit 금지 — schema if/then 으로 강제).
+4. **`MoveTo='Next'` + `Next.MoveStepOrder` 1개 이상**: 후보 Step 이 없으면 클릭 시 동작 없음.
+5. **`Next.Step{N}` 슬롯 = 문자열**: canonical 빈 문자열 `""`. 빈 객체 `{}` 는 schema 가 거부.
+6. **자기 자신 Step 참조**: BottomButton 의 `Next` 객체는 임의 Step 참조 가능 (`Step.Next` 의 forward-only 규칙과 별개). 단, 자기 자신 StepId 참조는 후검증에서 차단.
+7. **ImageStyle 효과 없음**: 런타임(`bottombuttons.js`) 이 의도적으로 ImageStyle 적용을 건너뜀.
+
+## 런타임 매핑
+
+- 메타 키 ↔ 런타임 상수 (`public/engine/common/const.js`)
+  - `BottomButtons` ↔ `K_BOTTOMBUTTONS`
+  - `UseBottomButton` ↔ `K_USE_BTMBUTTON`
+  - `ButtonName` ↔ `K_BUTTONNAME`
+  - 컴포넌트 단위 ↔ `COMPONENT_UNIT.BOTTOMBUTTON = 'BottomButton'`
+- 렌더러: `public/engine/runtime/bottombuttons.js` `renderBottomButtons()`
+- fquery 컨트롤 함수: `fControlFuncs['bottom']` (`name()`, `style()` 등) + `fControlFuncs['common']`

package/skill/docs/control/button.md

@@ -0,0 +1,147 @@
+# Button
+
+액션 트리거 전용 컨트롤. **입력 없음**. `ButtonName`(텍스트) + `ImageStyle`(아이콘) 단독 또는 조합으로 표현.
+
+## 스키마
+
+`control/button.schema.json` — `controlBase` + 분기 키 (`ControlType="Button"`, `ButtonName`, `ButtonValueCKey`, `ButtonValue`, `ImageStyle`, `UseClickEvent`).
+
+## 표시 모드
+
+| 구성 | 의미 |
+|---|---|
+| `ButtonName` 만 | 텍스트 버튼 |
+| `ImageStyle.UseImage=true` + `ButtonName=""` | 아이콘 전용 버튼 |
+| `ButtonName` + `ImageStyle.UseImage=true` | 아이콘 + 텍스트 |
+
+## 예시 — 텍스트 버튼 + 클릭 이벤트
+
+```jsonc
+{
+  "ControlType": "Button",
+  "ControlStyle": "styleRectangleMain",
+  "ControlDefaultName": "BtnSubmit",
+  "ControlName2": "BtnSubmit",
+  "Caption": "BtnSubmit",
+  "Id": "f_20",
+  "ButtonName": "{{확인}}",
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "SizeValue": "44", "SizeUnit": "px", "MatchText": false },
+  "UseClickEvent": true,
+  "Events": { "Click": "SUBMIT_E" },
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — 아이콘 전용 버튼
+
+```jsonc
+{
+  "ControlType": "Button",
+  "ControlStyle": "styleCircleBackPoint",
+  "ControlDefaultName": "BtnSearch",
+  "ControlName2": "BtnSearch",
+  "Caption": "BtnSearch",
+  "Id": "f_21",
+  "ButtonName": "",
+  "Width":  { "SizeValue": "38", "SizeUnit": "px", "MatchText": false },
+  "Height": { "SizeValue": "38", "SizeUnit": "px", "MatchText": false },
+  "ImageStyle": {
+    "UseImage": true,
+    "IsLineIcon": true,
+    "Img": "B_000_017",
+    "ImageColor": "var(--colorWhite)",
+    "ImageSize": "18"
+  },
+  "BgStyle":     { "UseBackground": true, "BgColor": "var(--colorMain)" },
+  "BorderStyle": { "Useborder": true, "BorderSize": "0", "SizeSet": "All", "BorderRadius": "6", "RadiusSet": "All" },
+  "UseClickEvent": true,
+  "Events": { "Click": "STEP1_Query_E" },
+  "UseFixedSize": true,
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — 값 저장 버튼 (`ButtonValueCKey` + `ButtonValue`)
+
+```jsonc
+{
+  "ControlType": "Button",
+  "ControlDefaultName": "BtnAgreeY",
+  "ControlName2": "BtnAgreeY",
+  "Caption": "BtnAgreeY",
+  "Id": "f_22",
+  "ButtonName": "{{동의}}",
+  "ButtonValueCKey": "AgreeFlag",
+  "ButtonValue": "Y",
+  "UseClickEvent": false,
+  "isColumnCtrl": false
+}
+```
+
+→ 클릭 시 카테고리의 `AgreeFlag` ckey 에 `"Y"` 가 저장. `UseClickEvent` 없이도 동작 (이벤트는 추가 핸들러 실행용).
+
+## `ButtonName` 바인딩 표현식
+
+Label `labeltext` 와 동일 규약. `Load.sector` 사용 불가.
+
+```
+"ButtonName": "{=FieldName}"                                   // 직접 바인딩
+"ButtonName": "{=$FieldName}"                                  // 천단위 콤마 자동
+"ButtonName": "{{삭제}} ({=Count})"                             // i18n + 바인딩
+"ButtonName": "{% return f.numFormat('{=Price}').format() %}"  // JS 실행
+```
+
+## 데이터 바인딩 — `ButtonValueCKey` + `ButtonValue`
+
+| 키 | 타입 | 의미 |
+|---|---|---|
+| `ButtonValueCKey` | string | 클릭 시 값을 저장할 **카테고리 필드명** (ckey). 빈 문자열=저장 안 함. |
+| `ButtonValue` | string | 클릭 시 `ButtonValueCKey` 에 저장될 **정적 값**. 표현식/바인딩 미지원. |
+
+**동작**: 사용자가 버튼을 누르면 카테고리의 `ButtonValueCKey` 필드값이 `ButtonValue` 로 set 된다. 이후 다른 컨트롤이 같은 ckey 를 읽으면 새 값을 받는다.
+
+**대표 패턴** — Y/N 토글 한 쌍:
+```jsonc
+{ "ButtonName": "{{동의}}",     "ButtonValueCKey": "AgreeFlag", "ButtonValue": "Y" }
+{ "ButtonName": "{{비동의}}",   "ButtonValueCKey": "AgreeFlag", "ButtonValue": "N" }
+```
+
+**전제조건**: 상위 Group 계층 어딘가에 `UseDataConnection: true` + `DataConnection` 필요 (다른 ckey 바인딩 컨트롤과 동일 규칙).
+
+## 클릭 이벤트
+
+| 모드 | 키 | 비고 |
+|---|---|---|
+| 이벤트 | `UseClickEvent: true` + `Events: { Click: "EVENT_NAME" }` | 핸들러 호출 |
+| 값 저장 | `ButtonValueCKey` + `ButtonValue` | 이벤트 핸들러 없이도 작동 |
+
+`Events` 는 `_base.schema.json#/$defs/buttonEvents` 가 적용 — `Click` 핸들러만.
+
+## Caption 규칙
+
+Button 의 `Caption` 은 **내부명** (=`ControlDefaultName`). 화면 표시 텍스트는 항상 `ButtonName` 이 결정.
+
+## BottomButton 과의 차이
+
+`Step.BottomButtons[]` 의 항목과는 **별개 컨트롤**.
+
+| 위치 | 키 | 비고 |
+|---|---|---|
+| `Step.Contents[…].Controls[…]` | `ControlType: "Button"` | 본 스키마 적용 — Step 이동 미지원 |
+| `Step.BottomButtons[…]` | `ButtonName` 등 (ControlType 없음) | [bottom-buttons.schema.json](../bottom-buttons.schema.json) 적용 — Step 이동 지원 |
+
+같은 `ButtonName` 키를 쓰지만 컨텍스트와 스키마가 다르므로 혼동 금지. **Step 이동 버튼은 BottomButton 으로**.
+
+## ControlKey 상태 (제한)
+
+Button 은 일부 상태가 미지원 — [control.md §ControlKey 상태](../control.md#controlkey-상태-제한) 표 참조. **`Required` 미지원** (입력 컨트롤 아님 — property-data.js `button()` 의 `status.hideItem(CONTROL_KEY.REQUIRED)`). `Hide` / `Disabled` / `ReadOnly` 는 지원.
+
+## 함정
+
+- `ButtonName` 안에서 `Load.sector` 사용 불가 — `{=Field}` 만.
+- 아이콘 전용 버튼은 `ButtonName: ""` + `ImageStyle.UseImage: true`. `ButtonName` 키 자체를 빼지 말 것 (운영 메타 컨벤션).
+- `UseClickEvent=true` 이면 `Events.Click` 필수.
+- `ButtonValueCKey` 사용 시 상위 Group 계층 어딘가에 `UseDataConnection: true` + `DataConnection` 필요.
+- `ButtonValue` 는 **정적 문자열만** — `{=Field}` / `{{i18n}}` 같은 표현식 미지원.
+- BottomButton 과 스키마/위치가 다름. `Step.BottomButtons[]` 는 별도 스키마.

package/skill/docs/control/calendar-navigator.md

@@ -0,0 +1,143 @@
+# CalendarNavigator
+
+> 공식 가이드: <https://docs.flextudio.com/flextudio/scenario/component/control/calendarnavigator>
+
+캘린더 네비게이터 — 월·주·일 단위로 날짜 범위를 이동하면서 선택한 날짜를 컬렉션에 바인딩한다. 사용 형태는 두 가지.
+
+| 형태 | UseTimeTable | 위치 |
+|---|---|---|
+| **TimeTable 내부 자식** | `true` | `TimeTable.CalendarNavigator.Controls[*]` |
+| **독립 컨트롤** | `false` | Group 직접 자식 (래퍼 그룹은 `UseDataConnection: true` 필수) |
+
+## 스키마
+
+`control/calendar-navigator.schema.json` — `controlBase` 위에 분기 키.
+
+## 핵심 속성
+
+| 속성 | 값 | 설명 |
+|---|---|---|
+| `ControlStyle` | `""` / `"None"` / `"StyleBack"` / `"StyleHalf"` / `"StyleAlignLeft"` | 공식 4종 스타일. |
+| `NavigatorType` | `"Month"` / `"WeekPeriod"` / `"Day"` | **공식 3종.** 월/주/일 단위. (`Custom` 은 공식 가이드 미표기 — **AI 생성 사용 금지.** 운영 메타에 보일 수는 있으나 신규 생성 시 enum 차단.) |
+| `UseDaySelector` | `true` / `false` | 주간 날짜 선택 바(스와이프 지원). **boolean strict** — 문자열 `"true"`/`"false"` 금지. 값에 따라 바인딩 키가 갈림: `true` → `SingleDate.Ckeys`, `false` → `StartDate.Ckeys` + `EndDate.Ckeys`. |
+| `UseTimeTable` | `true` / `false` | 독립 사용 시 `false`. |
+| `NavigatorDateFormat` | 공식 10종 (아래) | 헤더 날짜 표시 포맷. |
+| `SingleDate.Ckeys` | 배열 | Day 모드 또는 `UseDaySelector=true` 의 단일 날짜 바인딩. |
+| `StartDate.Ckeys` / `EndDate.Ckeys` | 배열 | WeekPeriod / Month 모드의 기간 바인딩 (스키마 if/then 으로 두 키 동시 필수). |
+| `DefaultValue` | string | 초기 날짜값 (미지정 시 오늘). |
+
+### NavigatorDateFormat — 공식 10종
+
+| 값 | 분류 | 비고 |
+|---|---|---|
+| `YYYY.MM.DD` / `YYYY/MM/DD` / `YYYY-MM-DD` / `YYYY년MM월DD일` | 일 단위 | Day / WeekPeriod / Month 모두 가능. |
+| `YYYY-MM-W` | 주 단위 | **`NavigatorType: "WeekPeriod"` 전용** (스키마 if/then 차단). |
+| `YYYY.MM` / `YYYY/MM` / `YYYY-MM` / `YYYY년MM월` | 월 단위 | 보통 Month 모드와 짝. |
+| `YYYY년` | 년 단위 | |
+| `""` | — | 런타임 기본 포맷. |
+
+## 빈 객체라도 필수인 속성 (런타임 규약)
+
+- `Events`
+- `DayArea`
+- `DaySetting`
+- `SelectDay`
+- `UseEvents`
+
+스키마에서 `required` 로 강제. 누락 시 런타임 에러.
+
+## 이벤트
+
+`Events.CalendarNaviEventsOrder` 로 등록. 등록한 이벤트명에 동명 핸들러 필수 (if/then).
+
+| 이벤트 | 발생 시점 |
+|---|---|
+| `ClickPrevNextBtn` | 이전/다음 버튼 클릭. |
+| `OnChangeSwipe` | DaySelector 스와이프로 주 변경. |
+| `SelectDay` | DaySelector 에서 날짜 클릭. |
+
+## 예시 — 독립 컨트롤 (WeekPeriod)
+
+```jsonc
+{
+  "ContentsName": "calNavWrap",
+  "ContentsType": "Group",
+  "UseDataConnection": true,
+  "DataConnection": {
+    "TargetType": "category",
+    "DataUsage": "default",
+    "CategoryName": "CtgCalNav",
+    "UseNewSector": true,
+    "OnlyIfNoSector": true
+  },
+  "Id": "f_70",
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "MatchText": true, "SizeValue": "" },
+  "Contents": [{
+    "ControlType": "CalendarNavigator",
+    "ControlDefaultName": "CalNav1",
+    "ControlName2": "CalNav1",
+    "Caption": "CalNav1",
+    "Id": "f_71",
+    "NavigatorType": "WeekPeriod",
+    "UseDaySelector": true,
+    "UseTimeTable": false,
+    "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+    "Height": { "MatchText": true, "SizeValue": "" },
+    "SingleDate": { "Ckeys": ["SelectDate"] },
+    "StartDate":  { "Ckeys": ["StartDate"] },
+    "EndDate":    { "Ckeys": ["EndDate"] },
+    "Events": {
+      "CalendarNaviEventsOrder": ["ClickPrevNextBtn", "SelectDay"],
+      "ClickPrevNextBtn": "NavChange_E",
+      "SelectDay":        "DaySelect_E"
+    },
+    "DayArea":    {},
+    "DaySetting": {},
+    "SelectDay":  {},
+    "UseEvents":  true,
+    "isColumnCtrl": false
+  }]
+}
+```
+
+## 예시 — TimeTable 내부 자식
+
+```jsonc
+{
+  "ControlType": "TimeTable",
+  "UseCalendarNavigator": true,
+  "CalendarNavigator": {
+    "Controls": [{
+      "ControlType": "CalendarNavigator",
+      "UseDaySelector": true,
+      "UseTimeTable": true,
+      "NavigatorType": "Month",
+      "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+      "Height": { "MatchText": true, "SizeValue": "" },
+      "Events": { "CalendarNaviEventsOrder": [] },
+      "DayArea": {},
+      "DaySetting": {},
+      "SelectDay": {},
+      "SingleDate": { "Ckeys": ["SelectDate"] },
+      "UseEvents": false,
+      "Id": "f_72"
+    }]
+  },
+  "...": "..."
+}
+```
+
+## 데이터 바인딩
+
+- 독립 사용 시 **반드시 래퍼 Group 에 `UseDataConnection: true`** + `DataConnection.CategoryName` 설정. `SingleDate/StartDate/EndDate.Ckeys` 가 그 카테고리의 섹터에 자동 저장.
+- TimeTable 내부 사용 시 TimeTable 의 래퍼 Group 카테고리를 공유 (별도 카테고리 불필요).
+
+## 함정
+
+- 빈 객체라도 `Events`, `DayArea`, `DaySetting`, `SelectDay`, `UseEvents` 누락 시 런타임 에러.
+- 독립 사용 시 `UseTimeTable: false` 명시 — 누락 시 TimeTable 컨텍스트로 오인.
+- WeekPeriod / Month 모드에서 `StartDate.Ckeys` 또는 `EndDate.Ckeys` 누락 → 기간 필터 동작 안 함 (스키마 if/then 으로 차단).
+- 날짜 변경 핸들러(`SelectDay`/`ClickPrevNextBtn`)에서 리스트 reload 시 래퍼 Group Id 사용 — 컨트롤 자체 reload 불가.
+- **`NavigatorType: "Custom"` 사용 금지** — 공식 가이드 미표기. AI 생성 메타에는 절대 등장 금지 (스키마 enum 으로 차단).
+- `NavigatorDateFormat: "YYYY-MM-W"` 는 반드시 `NavigatorType: "WeekPeriod"` 와 짝 (스키마 if/then 으로 차단).

package/skill/docs/control/calendar.md

@@ -0,0 +1,128 @@
+# Calendar
+
+> 공식 가이드(DatePicker): <https://docs.flextudio.com/flextudio/scenario/component/control/datepicker>
+
+캘린더 컨트롤. 두 가지 사용 형태가 있고, **둘 다 v1 명시 분기**다.
+
+| 형태 | 위치 | 비고 |
+|---|---|---|
+| **InputDate 자식** | `InputDate.Dialog.Layouts[*].Controls[*]` | 다이얼로그 picker. `CalendarType` / `SelectType` 은 InputDate 본체가 아니라 자식 Calendar 에 위치. |
+| **단독** | Group 직접 자식 (`Step.Contents[…].Controls[…]`) | 인라인 캘린더. Group 안에 Control 로 그대로 배치 — OtherControl 이 아닌 `control/calendar.schema.json` 분기 사용. |
+
+본체 정의는 `_base.schema.json#/$defs/calendarControl` 에 있고, 단독·자식 양쪽이 동일 분기를 공유한다 — InputDate 의 자식으로는 `dialogLayout` 의 if/then 으로, 단독으로는 `control/calendar.schema.json` 으로 적용.
+
+## 스키마
+
+`control/calendar.schema.json` — `controlBase` + `calendarControl` 의 합. `ControlType="Calendar"` const.
+
+## CalendarType / SelectType 매트릭스
+
+| CalendarType | DateFormat 짝 | SelectType | Ckeys 위치 |
+|---|---|---|---|
+| `dayCalendar` | `""` / `YYYY-MM-DD` / `YYYY.MM.DD` / `YYYY/MM/DD` | `SingleDate` 또는 `FromTo` | SingleDate.Ckeys 또는 StartDate.Ckeys + EndDate.Ckeys |
+| `monthCalendar` | `""` 또는 `YYYY-MM` | `SingleDate` 만 | SingleDate.Ckeys |
+| `yearCalendar` | `""` (기본) | `SingleDate` 만 | SingleDate.Ckeys |
+
+스키마 if/then + `[date]` cross-check 강제:
+
+- `SelectType="SingleDate"` → `SingleDate` **객체는 항상 필수**. `SingleDate.Ckeys` 는 **조상(또는 자기) Group 이 `UseDataConnection:true` 인 데이터연결 컨텍스트에서만 1개 이상 필수** — 비연결(프로토타이핑) 캘린더면 `"Ckeys": []` 허용. (단 `Ckeys` 키 자체는 항상 둘 것 — `SingleDate: {}` 빈 객체는 런타임 `dlgJson.SingleDate.Ckeys` 접근 시 TypeError.)
+- `SelectType="FromTo"` → `StartDate` + `EndDate` **객체 모두 항상 필수**. 각 `Ckeys` 도 동일 규칙 — 데이터연결 컨텍스트면 1개 이상, 비연결이면 `[]`.
+- `CalendarType ∈ {monthCalendar, yearCalendar}` → `SelectType` 은 `SingleDate` 만.
+
+> ★ **빈 객체 금지** (`[date]` cross-check) — `SingleDate: {}` / `StartDate: {}` / `EndDate: {}` 처럼 `Ckeys` 누락된 빈 객체는 런타임 `dlgJson.SingleDate.Ckeys` / `dlgJson.StartDate.Ckeys` / `dlgJson.EndDate.Ckeys` 접근 시 TypeError 를 일으킨다. 분기 키 객체는 항상 `Ckeys: ["..."]` 와 함께 채울 것.
+
+## 예시 — InputDate 자식 (가장 일반)
+
+```jsonc
+{
+  "ControlType": "InputDate",
+  "DateFormat": "YYYY-MM-DD",
+  "Dialog": {
+    "Layouts": [{
+      "ContentsType": "Layout",
+      "Controls": [{
+        "ControlType": "Calendar",
+        "CalendarType": "dayCalendar",
+        "SelectType": "SingleDate",
+        "SingleDate": { "Ckeys": ["AppDate"] },
+        "Id": "f_35"
+      }]
+    }]
+  }
+}
+```
+
+## 예시 — 단독 (인라인 캘린더)
+
+Group `Controls[]` 에 직접 배치. 운영 메타에서는 최소 6키만으로도 등장 (`Width`/`Height`/`isColumnCtrl` 생략 형태).
+
+```jsonc
+{
+  "ControlType": "Calendar",
+  "CalendarType": "dayCalendar",
+  "SelectType": "SingleDate",
+  "SingleDate": { "Ckeys": [] },
+  "ControlName2": "Calendar1",
+  "Caption": "Calendar1",
+  "Id": "f_4128"
+}
+```
+
+AI 생성 시에는 controlBase 권장 키 (`ControlDefaultName`/`ControlName2`/`Width`/`Height`) 까지 채워 다음과 같이:
+
+```jsonc
+{
+  "ControlType": "Calendar",
+  "CalendarType": "dayCalendar",
+  "SelectType": "SingleDate",
+  "SingleDate": { "Ckeys": ["SelectDate"] },
+  "ControlDefaultName": "Calendar1",
+  "ControlName2": "Calendar1",
+  "Caption": "Calendar1",
+  "Id": "f_60",
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "MatchText": true, "SizeValue": "" },
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — FromTo (기간 선택, dayCalendar 전용)
+
+```jsonc
+{
+  "ControlType": "Calendar",
+  "CalendarType": "dayCalendar",
+  "SelectType": "FromTo",
+  "StartDate": { "Ckeys": ["FromDate"] },
+  "EndDate":   { "Ckeys": ["ToDate"] },
+  "Id": "f_61"
+}
+```
+
+## 데이터 바인딩
+
+`SingleDate.Ckeys` / `StartDate.Ckeys` / `EndDate.Ckeys` 는 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 이 있어야 동작 (직접 부모 아닌 조상 Group 도 OK).
+
+## 이벤트
+
+`Events` 는 `_base.schema.json#/$defs/dateEvents` 가 적용. `DateOrder` enum: `DialogClose` 만.
+
+```jsonc
+{
+  "ControlType": "Calendar",
+  "UseEvents": true,
+  "Events": {
+    "DateOrder": ["DialogClose"],
+    "DialogClose": "ON_DATE_SELECTED"
+  }
+}
+```
+
+> InputDate 본체에 `UseEvents`/`Events` 두면 안 됨 — 자식 Calendar 안에 둔다.
+
+## 함정
+
+- **`CalendarType` 위치** — InputDate 본체가 아니라 자식 Calendar.
+- `monthCalendar` 면 `DateFormat` 은 `""` 또는 `"YYYY-MM"` 만 (validate.mjs cross-check).
+- `FromTo` 는 `dayCalendar` 전용 — 월/년 picker 에서는 if/then 차단.
+- `Id` 는 시나리오 전체 유일성 검증 대상.