@flextudio/scenario 0.1.0

package/contract-data/schema/v1/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/contract-data/schema/v1/control/button.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/button.schema.json",
+  "title": "Button",
+  "description": "액션 트리거 전용 컨트롤. 입력 없음. ButtonName(텍스트) + ImageStyle(아이콘) 단독 또는 조합. UseClickEvent 로 Events.Click 핸들러만 지원. ButtonValueCKey + ButtonValue 로 클릭 시 카테고리 필드에 값 저장 가능. Step 이동 미지원 — Label.UseMove 또는 BottomButton 사용.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "Button" },
+        "ButtonName": {
+          "type": "string",
+          "description": "버튼에 표시할 텍스트. 빈 문자열 가능 (아이콘 전용 버튼). `{{i18n}}` / `{=Field}` / `{=$Field}`(콤마) / `{% JS %}` 사용 가능. Load.sector 사용 불가."
+        },
+        "ButtonValueCKey": {
+          "type": "string",
+          "default": "",
+          "description": "클릭 시 값을 저장할 카테고리 필드명 (ckey 바인딩). 빈 문자열=저장 안 함. ButtonValue 와 함께 사용 — 클릭하면 이 ckey 에 ButtonValue 가 set. 사용 시 상위 Group 계층에 UseDataConnection + DataConnection 필요 (다른 ckey 바인딩 컨트롤과 동일)."
+        },
+        "ButtonValue": {
+          "type": "string",
+          "default": "",
+          "description": "클릭 시 ButtonValueCKey 에 저장할 값. 문자열. ButtonValueCKey 가 비어 있으면 의미 없음. 정적 값만 — 표현식/바인딩 미지원."
+        },
+        "ImageStyle": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "아이콘 버튼용 이미지 스타일. ButtonName='' 와 조합 시 아이콘 전용, ButtonName 과 함께 두면 아이콘+텍스트 버튼."
+        },
+        "UseClickEvent": {
+          "type": "boolean",
+          "default": false,
+          "description": "클릭 이벤트 사용. true 일 때 Events.Click 핸들러 명 필수."
+        },
+        "Events": { "$ref": "_base.schema.json#/$defs/buttonEvents" }
+      }
+    },
+    {
+      "$comment": "UseClickEvent=true 면 Events.Click 필요.",
+      "if": {
+        "properties": { "UseClickEvent": { "const": true } },
+        "required": ["UseClickEvent"]
+      },
+      "then": {
+        "required": ["Events"],
+        "properties": {
+          "Events": { "required": ["Click"] }
+        }
+      }
+    }
+  ]
+}

package/contract-data/schema/v1/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/contract-data/schema/v1/control/calendar-navigator.schema.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/calendar-navigator.schema.json",
+  "title": "CalendarNavigator",
+  "description": "캘린더 네비게이터. 월/주/일 단위로 날짜 범위를 이동·선택. (1) TimeTable 내부 자식 (UseTimeTable=true), (2) 독립 컨트롤 (UseTimeTable=false) 두 가지 사용 형태. 독립 사용 시 래퍼 Group 에 UseDataConnection:true 필수. Events / DayArea / DaySetting / SelectDay / UseEvents 는 빈 객체/기본값이라도 반드시 존재해야 한다 (런타임 규약).",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "CalendarNavigator" },
+        "ControlStyle": {
+          "type": "string",
+          "enum": ["", "None", "StyleBack", "StyleHalf", "StyleAlignLeft"],
+          "description": "공식 4종. ''/'None'=기본 / 'StyleBack'=뒤 배경형 / 'StyleHalf'=절반 표시 / 'StyleAlignLeft'=좌측 정렬."
+        },
+
+        "NavigatorType": {
+          "type": "string",
+          "enum": ["Month", "WeekPeriod", "Day"],
+          "description": "공식 3종 — Month=월 단위 / WeekPeriod=주 단위 / Day=일 단위. (운영 메타에 'Custom' 이 있을 수 있으나 AI 생성에서는 사용 금지 — 공식 가이드 미표기.)"
+        },
+        "NavigatorDateFormat": {
+          "type": "string",
+          "enum": [
+            "",
+            "YYYY.MM.DD", "YYYY/MM/DD", "YYYY-MM-DD", "YYYY년MM월DD일",
+            "YYYY-MM-W",
+            "YYYY.MM", "YYYY/MM", "YYYY-MM", "YYYY년MM월",
+            "YYYY년"
+          ],
+          "description": "헤더 날짜 표시 포맷 (공식 10종). 'YYYY-MM-W' 는 NavigatorType='WeekPeriod' (주 단위) 전용. ''=런타임 기본."
+        },
+
+        "UseDaySelector": {
+          "type": "boolean",
+          "default": false,
+          "description": "true=주간 날짜 선택 바 표시 (스와이프 지원). **boolean strict** — true/false 만. 문자열 \"true\"/\"false\" 금지 (JS truthy 함정). 이 값에 따라 바인딩 키가 갈림 — true → SingleDate.Ckeys, false → StartDate.Ckeys + EndDate.Ckeys (studio-panel-cat.js 진실원본)."
+        },
+        "UseTimeTable": {
+          "type": "boolean",
+          "default": false,
+          "description": "true=TimeTable 내부에 종속. false=독립 컨트롤로 사용."
+        },
+        "UseDataConnection": { "type": "boolean", "default": false },
+        "UseDaySetting":     { "type": "boolean", "default": false },
+        "UseDayArea":        { "type": "boolean", "default": false },
+
+        "SingleDate": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Day 모드 또는 UseDaySelector=true 일 때 단일 날짜 바인딩.",
+          "properties": {
+            "Ckeys": { "$ref": "../naming-objects.schema.json#/$defs/ckeysArray" }
+          }
+        },
+        "StartDate": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "WeekPeriod / Month 모드에서 기간 시작일 바인딩.",
+          "properties": {
+            "Ckeys": { "$ref": "../naming-objects.schema.json#/$defs/ckeysArray" }
+          }
+        },
+        "EndDate": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "WeekPeriod / Month 모드에서 기간 종료일 바인딩.",
+          "properties": {
+            "Ckeys": { "$ref": "../naming-objects.schema.json#/$defs/ckeysArray" }
+          }
+        },
+
+        "DayArea":    { "type": "object", "default": {}, "additionalProperties": true, "description": "필수(빈 객체 허용). 일자별 영역 표시 정의." },
+        "DaySetting": { "type": "object", "default": {}, "additionalProperties": true, "description": "필수(빈 객체 허용). 일자별 부가 설정." },
+        "SelectDay":  { "type": "object", "default": {}, "additionalProperties": true, "description": "필수(빈 객체 허용). 선택 일자 디자인." },
+
+        "DayDsKey":   { "type": "string", "description": "DayArea/DaySetting 의 DataSource 키 (선택)." },
+        "TypeDsKey":  { "type": "string", "description": "Day 타입 분류용 DataSource 키 (선택)." },
+
+        "UseEvents": { "type": "boolean", "default": false, "description": "필수(false 라도 키 존재). Events 핸들러 사용 여부." },
+        "Events": {
+          "type": "object",
+          "default": {},
+          "additionalProperties": true,
+          "description": "필수(빈 객체라도). CalendarNaviEventsOrder 로 등록.",
+          "properties": {
+            "CalendarNaviEventsOrder": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": ["ClickPrevNextBtn", "OnChangeSwipe", "SelectDay"]
+              }
+            },
+            "ClickPrevNextBtn": { "type": "string", "description": "이전/다음 버튼 클릭." },
+            "OnChangeSwipe":    { "type": "string", "description": "DaySelector 스와이프로 주 변경." },
+            "SelectDay":        { "type": "string", "description": "DaySelector 에서 날짜 클릭." }
+          },
+          "allOf": [
+            { "if": { "properties": { "CalendarNaviEventsOrder": { "type": "array", "contains": { "const": "ClickPrevNextBtn" } } }, "required": ["CalendarNaviEventsOrder"] }, "then": { "required": ["ClickPrevNextBtn"] } },
+            { "if": { "properties": { "CalendarNaviEventsOrder": { "type": "array", "contains": { "const": "OnChangeSwipe"    } } }, "required": ["CalendarNaviEventsOrder"] }, "then": { "required": ["OnChangeSwipe"]    } },
+            { "if": { "properties": { "CalendarNaviEventsOrder": { "type": "array", "contains": { "const": "SelectDay"        } } }, "required": ["CalendarNaviEventsOrder"] }, "then": { "required": ["SelectDay"]        } }
+          ]
+        }
+      },
+      "required": ["DayArea", "DaySetting", "SelectDay", "Events", "UseEvents"]
+    },
+    {
+      "$comment": "NavigatorType='Day' 또는 UseDaySelector=true → SingleDate 권장(검증은 후검증). NavigatorType='WeekPeriod'|'Month' → StartDate + EndDate 필수, 각각의 Ckeys (1개 이상) 도 필수. 런타임이 dlgJson.StartDate.Ckeys / dlgJson.EndDate.Ckeys 로 직접 접근하므로 빈 객체 {} 는 TypeError.",
+      "if": {
+        "properties": { "NavigatorType": { "enum": ["WeekPeriod", "Month"] } },
+        "required": ["NavigatorType"]
+      },
+      "then": {
+        "required": ["StartDate", "EndDate"],
+        "properties": {
+          "StartDate": {
+            "required": ["Ckeys"],
+            "properties": {
+              "Ckeys": { "minItems": 1 }
+            }
+          },
+          "EndDate": {
+            "required": ["Ckeys"],
+            "properties": {
+              "Ckeys": { "minItems": 1 }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "NavigatorType='Day' 면 SingleDate + SingleDate.Ckeys (1개 이상) 필수. 런타임이 dlgJson.SingleDate.Ckeys 로 직접 접근.",
+      "if": {
+        "properties": { "NavigatorType": { "const": "Day" } },
+        "required": ["NavigatorType"]
+      },
+      "then": {
+        "required": ["SingleDate"],
+        "properties": {
+          "SingleDate": {
+            "required": ["Ckeys"],
+            "properties": {
+              "Ckeys": { "minItems": 1 }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "NavigatorDateFormat='YYYY-MM-W' 는 NavigatorType='WeekPeriod' 전용 (공식 가이드).",
+      "if": {
+        "properties": { "NavigatorDateFormat": { "const": "YYYY-MM-W" } },
+        "required": ["NavigatorDateFormat"]
+      },
+      "then": {
+        "properties": { "NavigatorType": { "const": "WeekPeriod" } },
+        "required": ["NavigatorType"]
+      }
+    }
+  ]
+}

package/contract-data/schema/v1/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` 는 시나리오 전체 유일성 검증 대상.

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

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/calendar.schema.json",
+  "title": "Calendar",
+  "description": "캘린더 (날짜 선택). 일반적으로 InputDate.Dialog.Layouts[*].Controls[*] 위치에 자식으로 배치되며, 단독 컨트롤로도 사용 가능. CalendarType / SelectType 으로 일·월·년 picker 와 단일·기간 모드를 분기. 정의 본체는 _base.schema.json#/$defs/calendarControl 을 그대로 차용한다.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    { "$ref": "_base.schema.json#/$defs/calendarControl" },
+    {
+      "properties": {
+        "ControlType": { "const": "Calendar" }
+      }
+    }
+  ]
+}