@flextudio/scenario 0.1.0

package/skill/docs/style-objects.md

@@ -0,0 +1,183 @@
+# Style Objects (style-objects.schema.json)
+
+Group / Control / BottomButton 등에서 **반복적으로 등장하는 디자인/레이아웃 객체**를 한 곳에 모은 카탈로그. 다른 schema는 `$ref` 로 참조한다. 모든 정의는 `style-objects.schema.json#/$defs/<name>` 형태.
+
+> **데이터 관련 객체** (`dataConnection`, `sectorFilter`, DataUsage 분기, Filter 카탈로그) 는 별도 `data-objects.{schema.json,md}` 에 정의됨. 본 파일은 디자인/레이아웃만 다룸.
+
+## 1. `sizeObject` — Width / Height
+
+```jsonc
+{
+  "MatchText": false,
+  "SizeValue": 100,        // number 또는 string
+  "SizeUnit": "%"          // %, px, vh, vw, text
+}
+```
+
+규칙:
+- `MatchText: true` → 컨텐츠에 맞춤. `SizeValue` 는 무시되고 보통 빈 문자열 `""`.
+- `SizeUnit: "text"` → MatchText 모드에서 자주 사용 (예: 라벨 너비 = 텍스트 길이).
+- `calc()` 표현 사용 가능: `"SizeValue": "calc(100% - 40px)"` (`+`/`-` 좌우 공백 필수).
+
+## 2. `spacing` — Padding / Margin / AbsolutePosition
+
+```jsonc
+{
+  "UseAuto": true,
+  "UseEach": true,
+  "All": "",
+  "Top": "10",
+  "Right": "8",
+  "Btm": "10",
+  "Left": "8",
+  "SizeUnit": "px"
+}
+```
+
+규칙:
+- **하단 키 명명: `Btm`** 사용 (Padding/Margin/AbsolutePosition). BorderStyle만 `Bottom` 사용.
+- 사용하지 않는 방향은 키 자체를 **생략**. 빈 문자열 `""` 은 "미설정"으로 동작 안 함.
+- `UseEach: true` → 방향별로 다른 값. `UseEach: false` → `All` 만 사용.
+
+## 3. `absolutePosition` — 절대 위치 오버레이
+
+`spacing` 과 동일 구조. 사용처:
+
+```jsonc
+{
+  "UseAbsoluteLayout": true,
+  "AbsolutePosition": { "Btm": "20", "Right": "20", "SizeUnit": "px" }
+}
+```
+
+상단/하단, 좌측/우측 동시 설정 불가 (한쪽만).
+
+## 4. `displayStyle` — Flex/Display 레이아웃
+
+```jsonc
+{
+  "UseDisplay": true,
+  "DisplayType": "Flex",
+  "FlexDirection": "column",          // row | column | wrap
+  "FlexWrap": false,
+  "DisplayAlign": "Left",             // Left | Center | Right | Between
+  "DisplayVerticalAlign": "Top",      // Top | Center | Bottom
+  "flexBoxType": "align",
+  "columnGapValue": "8", "columnGapUnit": "px",
+  "rowGapValue": "8",    "rowGapUnit": "px"
+}
+```
+
+## 5. `fontStyle`
+
+```jsonc
+{
+  "UseFont": true,
+  "FontColor": "var(--colorBlack)",   // 권장 토큰 (§10 컬러 카탈로그). legacy @colorBlack 도 통용.
+  "FontSize": "14",
+  "FontWeight": "Medium",             // Regular | Medium | SemiBold | Bold
+  "FontAlign": "flex-start",          // flex-start | center | flex-end
+  "UseBold": false
+}
+```
+
+## 6. `borderStyle`
+
+```jsonc
+{
+  "Useborder": true,
+  "BorderColor": "var(--colorGray3)",
+  "BorderSize": 1,
+  "BorderType": "solid",
+  "SizeSet": "All",                   // All | Top | Right | Bottom | Left
+  "BorderRadius": "8",
+  "RadiusSet": "All"
+}
+```
+
+**주의:** BorderStyle은 하단 키를 `Bottom` 으로 쓴다 (Padding/Margin/AbsolutePosition은 `Btm`).
+
+## 7. `bgStyle`
+
+```jsonc
+{
+  "UseBackground": true,
+  "BgColor": "var(--colorWhite)",
+  "UseImage": false,
+  "Image": {}
+}
+```
+
+## 8. `captionStyle`
+
+```jsonc
+{
+  "UseDesign": true,
+  "FontWeight": "SemiBold",
+  "CaptionPosition": "",              // "" | Left | Top
+  "FontSize": "13",
+  "FontAlign": "flex-start"
+}
+```
+
+`CaptionPosition` 값:
+- `""` — `styleInputValueLine` 기본 (스타일이 캡션 자체 렌더링)
+- `"Left"` — 입력 옆
+- `"Top"` — 입력 위 (row 레이아웃)
+
+## 9. 데이터 바인딩은 별도 파일
+
+`dataConnection`, `sectorFilter`, DataUsage 분기, Filter 카탈로그 등 **데이터 관련 객체는 `data-objects.{schema.json,md}` 로 분리**되어 있다. 본 파일은 디자인/레이아웃 객체만 다룸.
+
+## 10. `colorToken` — 권장 컬러 토큰 카탈로그
+
+`$defs/colorToken` 에 enum 으로 정의. AI 생성 시 `BgColor`, `FontColor`, `BorderColor` 에 이 토큰 사용 권장. 실 메타는 hex(`#000`), legacy(`@colorBlack`), 임의 `var()` 도 통용 — schema 는 string 으로 유지.
+
+| 토큰 | 용도 |
+|---|---|
+| `var(--colorMain)` | Primary brand color |
+| `var(--colorMainLight)` | Primary light background |
+| `var(--colorWhite)` | White |
+| `var(--colorBlack)` | Black (강조 텍스트, 아이콘) |
+| `var(--colorGray1)` | Darkest gray (primary text) |
+| `var(--colorGray2)` | Dark gray (secondary text) |
+| `var(--colorGray3)` | Medium gray (tertiary text) |
+| `var(--colorGray4)` | Light gray (disabled, placeholder) |
+| `var(--colorGray5)` | Lighter gray (border, divider) |
+| `var(--colorGray9)` | Near-white gray (background) |
+| `var(--colorGray10)` | Lightest gray (tag background) |
+| `var(--colorRed)` | Error / Delete |
+| `var(--colorRedLight)` | Error background |
+| `var(--colorBlue)` | Info / Link |
+| `var(--colorBlueLight)` | Info background |
+| `var(--colorGreen)` | Success / Approved |
+| `var(--colorGreenLight)` | Success background |
+| `var(--colorOrange)` | Warning / Required indicator |
+| `var(--colorPurple)` | Accent |
+| `var(--colorPurpleLight)` | Accent background |
+| `var(--colorYellow)` | Caution / Pending |
+| `var(--colorYellowLight)` | Caution background |
+| `var(--colorMint)` | Mint / Complete |
+| `var(--colorMintLight)` | Mint background |
+| `var(--colorSub0)` | Supplementary color 0 |
+| `var(--colorSub0Light)` | Supplementary color 0 background |
+| `var(--colorSub1)` | Supplementary color 1 |
+| `var(--colorSub3)` | Supplementary color 3 |
+
+총 28개 토큰. catalog.json `colorTokens` 와 동기화.
+
+### 허용되는 색상 값 형태
+
+`BgColor` / `FontColor` / `BorderColor` 등 모든 색상 필드는 `type: string` 으로 자유. 다음 형태 모두 허용:
+
+| 형태 | 예시 | 비고 |
+|---|---|---|
+| 권장 토큰 | `var(--colorMain)`, `var(--colorOrange)` | 위 28개 |
+| Hex | `#333333`, `#000`, `#abc` | 3/6 자리 모두 OK |
+| Hex + alpha | `#33333380` | 8자리 |
+| RGB / RGBA | `rgb(255, 0, 0)`, `rgba(33, 21, 7, 0.654)` | |
+| HSL / HSLA | `hsl(0, 100%, 50%)`, `hsla(0, 100%, 50%, 0.5)` | |
+| Legacy 토큰 | `@colorBlack`, `@colorMain` | 운영 메타에서 등장 |
+| CSS keyword | `red`, `white`, `transparent` | |
+
+→ schema 는 strict enum 강제 안 함. `$defs/colorToken` 은 **AI 생성 가이드** 역할이며, AI가 우선 권장 토큰 중 선택하고, 토큰에 없는 디자인 요청(예: "정확히 #ff5733") 만 hex/rgba 로 폴백.

package/skill/examples/README.md

@@ -0,0 +1,147 @@
+# examples
+
+flextudio scenarioMeta 검증 샘플 — **5 카테고리 / 16 파일 / 13개 검증 통과**.
+
+각 파일은 실제 운영 메타에서 추출한 패턴이거나, 운영 메타를 v1 컨트랙트 검증 통과 형태로 자동 보정한 것이다.
+
+검증 명령:
+
+```bash
+node ../validate.mjs                                  # 전체 검증 (cross-check 포함)
+node ../validate.mjs basic/delivery-address-popup.json # 단일 파일
+PROTO_STRICT=0 node ../validate.mjs ...               # 운영 메타 모드 (Ckeys/DC 허용)
+IMAGE_PATH_STRICT=0 node ../validate.mjs ...          # ImageBox path 채워진 운영 모드
+```
+
+## 카테고리
+
+| 카테고리 | 파일 수 | 의도 | 디자인 토큰 | 통과 |
+|---|---:|---|---|---:|
+| [minimal/](minimal/)   | 4 | **골격(skeleton)** — 구조/패턴 검증용. 디자인 토큰 0. AI 가 "단순한 화면" 만들 때 / 구조만 빠르게 확인할 때. | 없음 | 4/4 |
+| [basic/](basic/)       | 1 | 단순 1~3 step + 디자인 적용. PopUp 단독. | 풍부 | 1/1 |
+| [enhanced/](enhanced/) | 6 | multi-step + dialog (PopUp/SlideUp) + 디자인. | 풍부 | 5/6 |
+| [complex/](complex/)   | 4 | 5+ step + 깊은 그룹 중첩 (4~7 레벨). | 매우 풍부 | 3/4 |
+| [tile/](tile/)         | 1 | 그리드 카드 패턴 (FlexDirection:wrap). | 풍부 | 0/1 |
+| [tab/](tab/)           | 2 | Tab 컨트롤 + RadioBox styleTab 패턴 표본. 운영 메타 그대로 — 검증보다는 패턴 참조용. | 풍부 | — |
+| [tree/](tree/)         | 1 | Tree 컨트롤 표본 (단일/다중 선택 + 검색바). 운영 메타 그대로. | 보통 | — |
+
+---
+
+## minimal/ — 골격 표본
+
+디자인 토큰 (`BgStyle` / `BorderStyle` / `FontStyle` / `Padding` / `ContentStyle`) **모두 0**. v1 컨트랙트 구조와 패턴만 보여주는 최소 표본.
+
+| 파일 | 패턴 | 핵심 컨트롤 / 메타 |
+|---|---|---|
+| [minimal/basic-list-detail.json](minimal/basic-list-detail.json) | 기본형태-0단계 — List → Input → Detail | `Label` / `RadioBox` / `InputText` / `MultiInputBox` / `ImageBox` |
+| [minimal/list-with-filters.json](minimal/list-with-filters.json) | 기본형태-1단계 — Combo 필터 + List → Input | `Combo`(Dialog→`ComboList`) 필터, status 배지 카드 |
+| [minimal/search-period-popup.json](minimal/search-period-popup.json) | 기본형태-조회강화형 — InputDate 기간 + Search + PopUp 상세조건 | `InputDate`(`FromTo`/`SingleDate`) + `Search`(Dialog→`List`), `StepDialogType:"PopUp"` |
+| [minimal/fixedtop-floating-form.json](minimal/fixedtop-floating-form.json) | 기본형태-혼합강화형 — FixedTop 검색바 + 리스트 + Floating | `FixedContentsTop` 검색바, `UseAbsoluteLayout` Floating, `InputFile` 첨부, `monthCalendar` |
+
+---
+
+## basic/ — 디자인 적용 단순 화면
+
+| 파일 | 패턴 | 특징 |
+|---|---|---|
+| [basic/delivery-address-popup.json](basic/delivery-address-popup.json) | 배송지 변경 PopUp (2 steps) | `BgStyle` 4, `BorderStyle` 14, `FontStyle` 29, `Padding` 8 |
+
+---
+
+## enhanced/ — multi-step + Dialog + 디자인
+
+| 파일 | 패턴 | 특징 |
+|---|---|---|
+| [enhanced/trade-statement-list.json](enhanced/trade-statement-list.json) | 거래명세서 조회 (PDA, 3 steps) | StepView + PopUp + SlideUp 조합 |
+| [enhanced/asset-management.json](enhanced/asset-management.json) | 자산관리 템플릿 (3 steps) | Combo + Search + ImageBox |
+| [enhanced/appointment-booking.json](enhanced/appointment-booking.json) | 약속잡기 (5 steps) | Calendar + CheckBox 다중 |
+| [enhanced/work-report.json](enhanced/work-report.json) | 구매 발주 관리 (4 steps) | DataUsage `query`/`detail`/`new` 혼합, SlideUp/PopUp |
+| [enhanced/salary-contract.json](enhanced/salary-contract.json) | 연봉계약 (5 steps) | `Signature` + `Line` + 깊은 텍스트 |
+| [enhanced/fuel-cost-status.json](enhanced/fuel-cost-status.json) | 유류비 자동등록 (3 steps) | `InputDate` × 3 + `InputMask` |
+
+---
+
+## complex/ — 다중 step + 깊은 중첩
+
+운영급 시나리오. 그룹 중첩 4~7 레벨. **`composition.group-nesting` 가이드의 표본**.
+
+| 파일 | 패턴 | 특징 |
+|---|---|---|
+| [complex/trade-statement-input.json](complex/trade-statement-input.json) | PDA 거래명세서 입력 (7 steps) | StepView × 4 + SlideUp × 3, `BgStyle` 26 / `BorderStyle` 41 / 중첩 7레벨 |
+| [complex/order-management.json](complex/order-management.json) | 오더관리 (7 steps) | Tab 컨트롤, FontStyle 176, 중첩 6레벨 |
+| [complex/crm-main.json](complex/crm-main.json) | CRM 메인 대시보드 (4 steps) | **★ ContentStyle:`styleRectangleShadow` 26회**, `BgStyle` 81 / `BorderStyle` 108 / 중첩 7레벨 |
+| [complex/field-work-register.json](complex/field-work-register.json) | 외근등록 (13 steps + StepSub) | Step 13개, `Embed`, `BgStyle` 72 / `BorderStyle` 132 / 중첩 6레벨 |
+
+---
+
+## tile/ — 그리드 카드 패턴
+
+| 파일 | 패턴 | 특징 |
+|---|---|---|
+| [tile/second-hand-marketplace.json](tile/second-hand-marketplace.json) | 중고거래 마이페이지 (9 steps) | **★ tileWrap > itemWrap > productInfoWrap > priceWrap** 깊은 카드 구조, `composition.list.card-tile-grid` 표본 |
+
+---
+
+## tab/ — 탭형 UI 표본
+
+탭형 UI 두 가지 패턴 표본. 운영 메타 그대로 (`flextudio-ai-studio/scenario_sample_tab/` 원본). v1 컨트랙트 검증보다는 **패턴 참조용**.
+
+| 파일 | 패턴 | 핵심 컨트롤 / 메타 |
+|---|---|---|
+| [tab/tab-control-cafe.json](tab/tab-control-cafe.json) | **Tab 컨트롤** — 탭마다 다른 Step 임베드 (HOME/COFFEE/DRINK/BOTTLE) | `Tab` 본체 + `Items[].LinkedStepId`, `Height: 100%` 패턴, 탭별 `Events.Click` |
+| [tab/radiobox-styletab-approval.json](tab/radiobox-styletab-approval.json) | **RadioBox + ControlStyle:"styleTab"** — 같은 리스트의 필터만 변경 (결재/신청 전환) | `RadioBox` 의 `ControlStyle:"styleTab"`, Click 이벤트로 필터 reload |
+
+---
+
+## tree/ — 트리 컨트롤 표본
+
+| 파일 | 패턴 | 핵심 컨트롤 / 메타 |
+|---|---|---|
+| [tree/tree-sample.json](tree/tree-sample.json) | **Tree 컨트롤** — flat array 계층 (NodeId/ParentId/Title) + 검색바 + 단일·다중 선택 | `Tree` + `CollectionMapper` + `UseExpandAll`/`UseSearchBar`/`UseParentAutoSelect`, DataSourceType 'API' |
+
+---
+
+## 공통 규칙 (모든 샘플)
+
+v1 컨트랙트 강제 항목 — 변환 스크립트가 자동 보정:
+
+- 시나리오 루트 const: `modules: {}`, `Collections: {}`, `htmlkey: "stephtml"`, `ScenarioTitle: ""`, `fConverterVersion: 1`, `FlexSQLService: {}`
+- Step 식별자: `^Step[1-9][0-9]*$`
+- Group/Control/BottomButton Id: `^f_[1-9][0-9]*$` — 시나리오 전체 유일
+- 모든 Control: `ControlDefaultName` + `ControlName2`(같은 값) + `Caption` + `isColumnCtrl: false`
+- Step Reachability: 각 Step 은 `StartSteps` 또는 다른 Step 의 `Next` 에서 정확히 1번
+- Dialog 컨트롤(InputDate / Combo / Search) 본체에는 `UseEvents`/`Events` 두지 않음 — 자식 Calendar / ComboList / List 안에만
+- Ckeys 사용 컨트롤은 상위 Group 어딘가에 `UseDataConnection: true` + `DataConnection`
+- ImageBox: `ViewGroup.{ImgPath, BucketUrl}` 비움 (운영 시 채워짐)
+
+## 프로토타이핑 정책
+
+13개 통과 샘플 모두 **프로토타이핑 모드** — `DataSources: {}`, 정적 라벨 (`LabelType:"labeltext"` + `labeltext`).
+
+운영 메타로 검증할 때는:
+- `PROTO_STRICT=0` — Ckeys / DataConnection / LabelCKey 허용
+- `IMAGE_PATH_STRICT=0` — ImageBox path 채워진 상태 허용
+- `SAMPLE_DATA_STRICT=0` — Service / Collection / API DataSource 허용
+
+## 잔여 검증 비통과 (3건)
+
+| 파일 | 잔여 에러 | 사유 |
+|---|---|---|
+| `complex/order-management.json` | `[schema]` 1건 — Step2.Contents[1] (Tab) | v1 외 컨트롤 + 깊은 중첩 oneOf 폭발 |
+| `enhanced/asset-management.json` | `[schema]` 2건 — BottomButton.Next | `MoveTo:"Next"` + `MoveStepOrder` 빈 배열 (then-require) |
+| `tile/second-hand-marketplace.json` | `[schema]` 39건 — 깊은 ImageBox/Group 중첩 | 운영 특수 패턴 (oneOf 폭발) |
+
+이 3건은 운영 특수 패턴 — 자동 변환으로 의미 손실 없이 해결 어려움. 패턴 참조용으로는 그대로 사용 가능.
+
+## 디자인 시스템과의 매핑
+
+[../schema/v1/design-system/](../schema/v1/design-system/) 의 컴포지션과 매칭:
+
+| 디자인 패턴 (assets.json) | 대응 examples |
+|---|---|
+| `composition.list.card-list` | minimal/basic-list-detail, basic/delivery-address-popup |
+| `composition.dialog.popup` / `dialog.slideup` | minimal/search-period-popup, enhanced/trade-statement-list |
+| `composition.fixed.search-bar` | minimal/fixedtop-floating-form, enhanced/work-report |
+| `composition.list.card-tile-grid` | tile/second-hand-marketplace |
+| `composition.group-nesting` (★ 4~7 레벨) | complex/* (특히 crm-main, field-work-register) |
+| `content-style.rectangle-shadow` | complex/crm-main (26회 사용 — 운영 1위 표본) |