@flextudio/scenario 0.1.0

package/contract-data/schema/v1/patterns/_base.controls.mjs

@@ -0,0 +1,759 @@
+// _base.controls.mjs
+// ─────────────────────────────────────────────────────────────────────────────
+// Engine ControlType 별 1:1 Factory
+// 엔진이 요구하는 boilerplate를 만족
+// 디자인 결정은 materializer 가 spread + override 로 주입.
+//
+// 사용 패턴 (materializer 측):
+//   import { makeInputText } from "../_base.controls.mjs";
+//   import { font, border, bg, padding } from "../_base.style.mjs";
+//
+//   return {
+//     ...makeInputText({ name: "Email" }),
+//     Id: generateId(ctx),
+//     FontStyle: font({ size: "body-md", color: "text.body" }),
+//     BorderStyle: border({ radius: 8, color: "border.default" }),
+//     Padding: padding({ x: "md", y: "sm" }),
+//   };
+//
+// 규칙:
+// - 팩토리 인자는 control-discriminator 최소값만 (name/caption/text/items/children/html…).
+//   색/크기/radius/padding 등 디자인 값은 절대 인자로 받지 않는다.
+// - 팩토리 반환물은 mutate 금지 — 매번 새 인스턴스 생성 후 spread.
+// - Id 는 팩토리가 생성하지 않는다. materializer 에서 generateId(ctx) 로 주입.
+// - name 과 caption 은 다른 개념:
+//     · name    → ControlName / ControlName2. 스튜디오 explorer 에서 표시되는 식별자.
+//     · caption → Caption. 화면에 보이는 라벨 텍스트. 다국어 (`{{필드명}}`) / 바인딩 가능.
+//   caption 미지정 시 name 으로 fallback (실무에서 같은 경우가 많음).
+//   Embed 는 schema const "" — caption 인자 무시.
+// - 스타일 객체:
+//     · FontStyle / BorderStyle / BgStyle / Padding / Margin = 빈 `{}` placeholder.
+//       _base.style.mjs 의 헬퍼 결과로 spread override.
+//     · CaptionStyle = factory 가 emit 하지 않음. 디자인이 적용될 때만 materializer 가
+//       `{ UseDesign: true, FontSize, FontWeight, ... }` 형태로 추가 (FontStyle 과
+//       동일 shape + CaptionPosition). ★ Use* 류는 모두 native boolean 사용 — schema
+//       전체가 boolean 강제하므로 string "true"/"false" emit 금지.
+// - inputBase 의 UseEvents / Events 는 Combo / Search / InputDate 본체에 두지 않는다
+//   ([event] 정합). 자식 Dialog 컨트롤(makeInnerComboList / makeInnerSearchList /
+//   makeInnerCalendar) 에서 처리.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ============================================================================
+// 내부 상수
+// ============================================================================
+
+// 가이드 §5 "Defaults to preserve": Width 100%, Height MatchText.
+const W_FULL = { SizeValue: "100", SizeUnit: "%", MatchText: false };
+const H_TEXT = { MatchText: true, SizeValue: "", SizeUnit: "text" };
+
+// 스타일 placeholder. materializer 의 _base.style.mjs 헬퍼 결과로 spread override.
+// CaptionStyle 은 디자인이 있을 때만 — factory 가 emit 하지 않는다.
+function emptyStyles() {
+  return {
+    FontStyle: {},
+    BorderStyle: {},
+    BgStyle: {},
+    Padding: {},
+    Margin: {},
+  };
+}
+
+// 모든 Control 공통 base.
+// - ControlDefaultName = engine ControlType
+// - ControlName / ControlName2 = name (스튜디오 explorer 식별자)
+// - Caption = caption ?? name (화면 표시 라벨). 두 값은 다른 개념이지만 미지정 시 fallback.
+function controlBase(controlType, name, caption) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError(
+      `_base.controls: '${controlType}' 팩토리는 name (string, non-empty) 필수`,
+    );
+  }
+  return {
+    ControlType: controlType,
+    ControlDefaultName: controlType,
+    ControlName: name,
+    ControlName2: name,
+    ControlStyle: "None",
+    Caption: caption != null ? String(caption) : "",
+    isColumnCtrl: false,
+    Width: { ...W_FULL },
+    Height: { ...H_TEXT },
+    ...emptyStyles(),
+  };
+}
+
+// inputBase 추가 키. Combo / Search / InputDate 는 호출하지 않는다 ([event] 정합).
+function inputExtras() {
+  return {
+    UseEvents: false,
+    DisplayType: "CtrlDisplayCkey",
+  };
+}
+
+/**
+ * wrapDialog — Combo / Search / InputDate 의 Dialog 필드 합성 헬퍼.
+ * 단일 inner 컨트롤(ComboList / List / Calendar) 을 받아 engine 이 요구하는
+ * { Layouts: [{ ContentsType:"Layout", Controls:[inner] }] } 구조로 감싼다.
+ *
+ *   const body = makeCombo({ name: "Status" });
+ *   return {
+ *     ...body,
+ *     Id: generateId(ctx),
+ *     Dialog: wrapDialog(makeInnerComboList({ items: [...] })),
+ *   };
+ *
+ * Dialog 는 schema 상 optional 이지만 emit 한다면 Controls.minItems:1 강제 —
+ * factory 자체는 Dialog 를 emit 하지 않고 materializer 가 합성한다.
+ */
+export function wrapDialog(innerControl) {
+  if (!innerControl || typeof innerControl !== "object") {
+    throw new TypeError(
+      "_base.controls: wrapDialog 는 inner control object 필수",
+    );
+  }
+  return {
+    Layouts: [{ ContentsType: "Layout", Controls: [innerControl] }],
+  };
+}
+
+// ============================================================================
+// Public API — 단말 컨트롤 (catalog.json#controlTypes 1:1)
+// ============================================================================
+
+/**
+ * Label — 텍스트/아이콘 표시. labeltext 모드 (정적 텍스트) 가 표준.
+ *
+ *   makeLabel({ text: "안녕", name: "Greeting" })
+ *   makeLabel({ name: "ProductName", labelCKey: "ProductName" })  // LabelCKey 모드
+ *
+ * labeltext: 메인 표시 텍스트 (바인딩 / 다국어 / JS 지원).
+ * Caption:   별개의 화면 라벨 (Label 컨트롤도 Caption 영역이 있음). 미지정 시 name fallback.
+ */
+export function makeLabel({ text, name, caption, labelCKey } = {}) {
+  const out = controlBase("Label", name, caption);
+  if (labelCKey != null) {
+    out.LabelType = "LabelCKey";
+    out.LabelCKey = labelCKey;
+  } else {
+    out.LabelType = "labeltext";
+    out.labeltext = text != null ? String(text) : "";
+  }
+  return out;
+}
+
+/**
+ * InputText — 한 줄 텍스트 입력. text / password / number / email / tel.
+ *
+ *   makeInputText({ name: "Email", caption: "이메일" })
+ *   makeInputText({ name: "Password", inputType: "password", caption: "비밀번호" })
+ */
+export function makeInputText({ name, caption, inputType = "text" } = {}) {
+  return {
+    ...controlBase("InputText", name, caption),
+    ...inputExtras(),
+    InputType: inputType,
+  };
+}
+
+/**
+ * InputNumber — 숫자 입력. decimal / integer.
+ *
+ *   makeInputNumber({ name: "Quantity", caption: "수량" })
+ *   makeInputNumber({ name: "Price", inputType: "decimal", caption: "단가" })
+ */
+export function makeInputNumber({ name, caption, inputType = "decimal" } = {}) {
+  return {
+    ...controlBase("InputNumber", name, caption),
+    ...inputExtras(),
+    InputType: inputType,
+  };
+}
+
+/**
+ * InputMask — 마스크 패턴 입력 (hhmm / money).
+ *
+ *   makeInputMask({ name: "Time", inputType: "hhmm", caption: "시간" })
+ *   makeInputMask({ name: "Money", inputType: "money", caption: "금액" })  // UseNumberOnly 권장
+ */
+export function makeInputMask({ name, caption, inputType } = {}) {
+  if (inputType !== "hhmm" && inputType !== "money") {
+    throw new Error(
+      `_base.controls: makeInputMask 의 inputType 은 'hhmm' | 'money' 만 허용`,
+    );
+  }
+  const out = {
+    ...controlBase("InputMask", name, caption),
+    ...inputExtras(),
+    InputType: inputType,
+    MaskType: inputType === "hhmm" ? "Time" : "Money",
+  };
+  if (inputType === "money") out.UseNumberOnly = true;
+  return out;
+}
+
+/**
+ * MultiInputBox — 여러 줄 텍스트 (TextArea). Enter 줄바꿈.
+ *
+ *   makeMultiInputBox({ name: "Memo", caption: "메모" })
+ */
+export function makeMultiInputBox({ name, caption } = {}) {
+  return {
+    ...controlBase("MultiInputBox", name, caption),
+    ...inputExtras(),
+  };
+}
+
+/**
+ * InputDate — 날짜 입력 + 캘린더 다이얼로그.
+ *
+ * Dialog 는 factory 가 emit 하지 않는다 (Controls.minItems:1 강제 때문).
+ * materializer 가 makeInnerCalendar + wrapDialog 로 합성:
+ *
+ *   return {
+ *     ...makeInputDate({ name: "PeriodInput", caption: "조회 기간", dateFormat: "YYYY.MM.DD" }),
+ *     Id: generateId(ctx),
+ *     Dialog: wrapDialog(makeInnerCalendar({ calendarType: "dayCalendar", selectType: "FromTo" })),
+ *   };
+ *
+ * [event] 정합: 본체에 UseEvents / Events 두지 않는다.
+ */
+export function makeInputDate({
+  name,
+  caption,
+  dateFormat = "YYYY-MM-DD",
+} = {}) {
+  return {
+    ...controlBase("InputDate", name, caption),
+    DisplayType: "CtrlDisplayCkey",
+    DateFormat: dateFormat,
+  };
+}
+
+/**
+ * Combo — 드롭다운 (8개 이하 고정 목록). 8개 초과/동적 데이터는 Search.
+ *
+ *   return {
+ *     ...makeCombo({
+ *       name: "DeptCombo", caption: "부서선택",
+ *       ckeys: ["DeptCode", "DeptName"],
+ *       ctrlDisplayCkey: "DeptName",   // 본체에 표시할 컬렉션/목업 필드명
+ *     }),
+ *     Id: generateId(ctx),
+ *     Dialog: wrapDialog(makeInnerComboList({
+ *       items: [...], ckeys: ["DeptCode", "DeptName"],
+ *       saveNameKey: "DeptName", saveValueKey: "DeptCode",
+ *     })),
+ *   };
+ *
+ * ★ ckeys / ctrlDisplayCkey 는 섹터(목업/카테고리 데이터)의 필드명에 맞춘다 (rules.md §5.5.1).
+ *   ctrlDisplayCkey 를 비우면 선택 후 본체가 빈 칸 — 고정데이터든 외부데이터든 채운다.
+ */
+export function makeCombo({ name, caption, ckeys, ctrlDisplayCkey } = {}) {
+  const out = {
+    ...controlBase("Combo", name, caption),
+    DisplayType: "CtrlDisplayCkey",
+  };
+  if (Array.isArray(ckeys) && ckeys.length) out.Ckeys = ckeys;
+  // 본체 표시 키 — DisplayType:"CtrlDisplayCkey" 모드에서 본체에 그릴 컬렉션/목업 필드명.
+  // 비우면 선택 후 본체가 빈 칸 ([display-key]). 고정데이터든 외부데이터든 채운다.
+  if (ctrlDisplayCkey) out.CtrlDisplayCkey = ctrlDisplayCkey;
+  return out;
+}
+
+/**
+ * Search — Code Help / Lookup. DataSource(Collection/Service) 기반 lookup.
+ *
+ *   return {
+ *     ...makeSearch({
+ *       name: "CustomerSearch", caption: "거래처",
+ *       ckeys: ["CustomerCode", "CustomerName"],
+ *       ctrlDisplayCkey: "CustomerName",   // 본체에 표시할 컬렉션/목업 필드명
+ *     }),
+ *     Id: generateId(ctx),
+ *     Dialog: wrapDialog(makeInnerSearchList({ dataSourceName: "CustomerQuery", title: "CustomerName" })),
+ *   };
+ *
+ * ★ Search 는 늘 DataSource 기반 — ctrlDisplayCkey 필수 (비우면 선택 후 본체 빈 칸).
+ */
+export function makeSearch({ name, caption, ckeys, ctrlDisplayCkey } = {}) {
+  const out = {
+    ...controlBase("Search", name, caption),
+    DisplayType: "CtrlDisplayCkey",
+  };
+  if (Array.isArray(ckeys) && ckeys.length) out.Ckeys = ckeys;
+  // 본체 표시 키 — Search 는 늘 DataSource 기반이라 CtrlDisplayCkey 필수.
+  // 비우면 선택 후 본체가 빈 칸 ([display-key]).
+  if (ctrlDisplayCkey) out.CtrlDisplayCkey = ctrlDisplayCkey;
+  return out;
+}
+
+/**
+ * CheckBox — 다중 항목 또는 단일 toggle.
+ *
+ *   makeCheckBox({ name: "Agreements", items: [
+ *     { ItemName: "약관1", ItemValue: "Y" },
+ *     { ItemName: "약관2", ItemValue: "Y" },
+ *   ]})
+ *
+ * Items 는 minItems:1 (schema 강제). 인자 누락 시 placeholder 1건.
+ */
+export function makeCheckBox({ name, caption, items } = {}) {
+  const list =
+    Array.isArray(items) && items.length > 0
+      ? items
+      : [{ ItemName: name, ItemValue: "Y", ItemValueDel: "" }];
+  return {
+    ...controlBase("CheckBox", name, caption),
+    Items: list,
+  };
+}
+
+/**
+ * RadioBox — 라디오 그룹. Fixed Items 또는 DataSource (UseDataSource:true).
+ *
+ *   makeRadioBox({
+ *     name: "PaymentMethod",
+ *     items: [
+ *       { ItemName: "법인카드", ItemValue: "법인카드" },
+ *       { ItemName: "개인경비 후정산", ItemValue: "개인경비 후정산" },
+ *     ],
+ *     ckeys: ["PaymentValue", "PaymentName"],
+ *     saveValueKey: "PaymentValue",
+ *     saveNameKey: "PaymentName",
+ *   })
+ *
+ * Items 는 schema 상 optional (Fixed/DataSource 분기) — 인자 없으면 빈 배열.
+ *
+ * ★ 저장 키 (Fixed 모드 데이터 바인딩) — 엔진이 선택 항목의 ItemValue 를
+ *   `sector[saveValueKey]`, ItemName 을 `sector[saveNameKey]` 에 기록
+ *   (public/engine/control/radiobox.js#L380-L428). 즉 saveValueKey/saveNameKey 는
+ *   **섹터(목업/카테고리 데이터)의 필드명** 이어야 한다 — 목업 데이터를 생성했다면
+ *   거기서 쓰는 키로 맞춘다 (rules.md §5.5.1). 데이터 바인딩(폼 입력)으로 쓰는
+ *   RadioBox 는 셋 다 넘긴다. 순수 필터/뷰 토글이면 생략 가능.
+ *   `CtrlDisplayCkey` 는 RadioBox 엔진이 사용하지 않으므로 emit 하지 않는다.
+ */
+export function makeRadioBox({ name, caption, items, ckeys, saveValueKey, saveNameKey } = {}) {
+  const out = {
+    ...controlBase("RadioBox", name, caption),
+    Items: Array.isArray(items) ? items : [],
+  };
+  if (Array.isArray(ckeys) && ckeys.length) out.Ckeys = ckeys;
+  if (saveNameKey) out.SaveNameKey = saveNameKey;
+  if (saveValueKey) out.SaveValueKey = saveValueKey;
+  return out;
+}
+
+/**
+ * ImageBox — 이미지 표시/업로드. mode='View'|'Edit'.
+ *
+ *   makeImageBox({ name: "ProductImage", mode: "View" })
+ *   makeImageBox({ name: "Avatar", mode: "Edit" })
+ *
+ * ViewGroup/EditGroup 은 factory 가 emit 하지 않는다 — image-box.schema.json 가
+ * "데이터 바인딩 메타는 생략 가능 (스튜디오/사용자가 사후 설정)" 명시.
+ * emit 한다면 ImageSrcType 별 필수 키가 강제되므로 materializer 가 바인딩 정보를
+ * 알고 있을 때만 추가한다 (가이드 §5: 빈 ImageBox.ViewGroup.{ImgPath,BucketUrl} 만 정합).
+ */
+export function makeImageBox({ name, caption, mode = "View" } = {}) {
+  if (mode !== "View" && mode !== "Edit") {
+    throw new Error(`_base.controls: makeImageBox mode 는 'View'|'Edit' 만`);
+  }
+  return {
+    ...controlBase("ImageBox", name, caption),
+    ImageBoxType: mode,
+  };
+}
+
+/**
+ * InputFile — 파일 첨부.
+ *
+ *   makeInputFile({ name: "Attachment" })
+ *
+ * Attributes.UseCategory / CategoryName / Limit / AcceptType 는 materializer 가 결정.
+ */
+export function makeInputFile({ name, caption } = {}) {
+  return {
+    ...controlBase("InputFile", name, caption),
+    UseEvents: false,
+    Attributes: {},
+  };
+}
+
+/**
+ * Calendar (standalone) — 단독 캘린더 picker.
+ * 일반적으로 InputDate.Dialog 의 자식으로 사용 (makeInnerCalendar 사용).
+ *
+ *   makeCalendar({ name: "DatePicker", calendarType: "dayCalendar", selectType: "SingleDate" })
+ */
+export function makeCalendar({
+  name,
+  caption,
+  calendarType = "dayCalendar",
+  selectType = "SingleDate",
+} = {}) {
+  const out = {
+    ...controlBase("Calendar", name, caption),
+    CalendarType: calendarType,
+    SelectType: selectType,
+  };
+  if (selectType === "SingleDate") {
+    out.SingleDate = { Ckeys: [] };
+  } else if (selectType === "FromTo") {
+    out.StartDate = { Ckeys: [] };
+    out.EndDate = { Ckeys: [] };
+  }
+  return out;
+}
+
+/**
+ * CalendarNavigator — 월/주/일 단위 네비게이션.
+ * TimeTable 내부 또는 독립. 독립 사용 시 래퍼 Group 의 UseDataConnection:true 필수.
+ *
+ *   makeCalendarNavigator({ name: "MonthNav", navigatorType: "Month" })
+ *
+ * DayArea / DaySetting / SelectDay / Events / UseEvents 는 빈 객체라도 필수
+ * (engine 런타임 규약 — schema 의 required 에 포함).
+ */
+export function makeCalendarNavigator({
+  name,
+  caption,
+  navigatorType = "Month",
+  useTimeTable = false,
+} = {}) {
+  const out = {
+    ...controlBase("CalendarNavigator", name, caption),
+    NavigatorType: navigatorType,
+    NavigatorDateFormat: "",
+    UseTimeTable: useTimeTable,
+    UseDaySelector: false,
+    UseDataConnection: false,
+    UseDaySetting: false,
+    UseDayArea: false,
+    DayArea: {},
+    DaySetting: {},
+    SelectDay: {},
+    UseEvents: false,
+    Events: {},
+  };
+  // schema if/then: WeekPeriod/Month → StartDate + EndDate / Day → SingleDate
+  if (navigatorType === "Day") {
+    out.SingleDate = { Ckeys: [] };
+  } else {
+    out.StartDate = { Ckeys: [] };
+    out.EndDate = { Ckeys: [] };
+  }
+  return out;
+}
+
+/**
+ * Tab — 탭 컨트롤. Items[].LinkedStepId 로 다른 Step 임베드.
+ * Height 는 반드시 100% (engine 규약 + [tab] 후검증).
+ *
+ *   makeTab({ name: "MainTab", items: [
+ *     { ItemName: "탭1", ItemValue: "T1", LinkedStepId: "Step2" },
+ *     { ItemName: "탭2", ItemValue: "T2", LinkedStepId: "Step3" },
+ *   ]})
+ */
+export function makeTab({ name, caption, items } = {}) {
+  if (!Array.isArray(items) || items.length === 0) {
+    throw new Error(`_base.controls: makeTab 은 items (minItems:1) 필수`);
+  }
+  return {
+    ...controlBase("Tab", name, caption),
+    Height: { SizeValue: "100", SizeUnit: "%", MatchText: false }, // ★ 강제
+    Items: items,
+    TabHeader: {},
+    SelectTabHeader: {},
+    TabHeaderItem: {},
+    SelectTabHeaderItem: {},
+  };
+}
+
+/**
+ * Tree — 계층형 트리. NodeId/ParentId/Title 로 flat array 의 부모-자식 관계.
+ *
+ *   makeTree({
+ *     name: "MenuTree",
+ *     dataSourceName: "MenuTreeQuery",
+ *     nodeId: "MenuId",
+ *     parentId: "ParentMenuId",
+ *     title: "MenuName",
+ *   })
+ *
+ * UseMultiData=true 모드는 별도 옵션으로 활성화.
+ */
+export function makeTree({
+  name,
+  caption,
+  dataSourceName,
+  nodeId,
+  parentId,
+  title,
+  subTitle,
+} = {}) {
+  if (
+    typeof dataSourceName !== "string" ||
+    typeof nodeId !== "string" ||
+    typeof parentId !== "string" ||
+    typeof title !== "string"
+  ) {
+    throw new Error(
+      `_base.controls: makeTree 는 { dataSourceName, nodeId, parentId, title } 필수`,
+    );
+  }
+  const out = {
+    ...controlBase("Tree", name, caption),
+    DataSourceName: dataSourceName,
+    NodeId: nodeId,
+    ParentId: parentId,
+    Title: title,
+    UseExpandAll: false,
+    UseSearchBar: false,
+    UseMultiData: false,
+    UseEvents: false,
+  };
+  if (subTitle != null) out.SubTitle = subTitle;
+  return out;
+}
+
+/**
+ * Embed — raw HTML 삽입. <script> 직접 삽입 금지 — 외부 라이브러리는 Scenario.StyleURLs 등록 우선
+ * (f.Script.load 는 동적 URL 한정). ★ Tab 내부 LinkedStep 에는 Embed 금지([tab-embed]).
+ *
+ *   makeEmbed({ name: "ChartHost", html: '<div id="myChart" style="width:100%;height:240px"></div>' })
+ *
+ * Caption 은 schema 가 const "" 강제 — Embed 본체에 그대로 노출되므로 caption 인자 받지 않음.
+ */
+export function makeEmbed({ name, html } = {}) {
+  if (typeof html !== "string") {
+    throw new Error(`_base.controls: makeEmbed 의 html 은 string 필수`);
+  }
+  return {
+    ...controlBase("Embed", name, ""), // ★ schema const "" 강제
+    Embed: html,
+  };
+}
+
+// ============================================================================
+// Public API — Dialog 자식 (Combo / Search / InputDate 의 inner 컨트롤)
+// ============================================================================
+
+/**
+ * InnerCalendar — InputDate.Dialog.Layouts[0].Controls[0] 위치의 Calendar.
+ * CalendarType / SelectType / Single|FromTo 바인딩 객체 포함.
+ * [event] 정합: dateEvents 는 여기에 둔다 (본체 아님).
+ *
+ *   makeInnerCalendar({ calendarType: "dayCalendar", selectType: "FromTo" })
+ *   makeInnerCalendar({ calendarType: "monthCalendar", selectType: "SingleDate" })
+ */
+export function makeInnerCalendar({
+  calendarType = "dayCalendar",
+  selectType = "SingleDate",
+} = {}) {
+  const out = {
+    ControlType: "Calendar",
+    CalendarType: calendarType,
+    SelectType: selectType,
+    UseMultiData: false,
+    isColumnCtrl: false,
+  };
+  if (selectType === "SingleDate") {
+    out.SingleDate = { Ckeys: [] };
+  } else if (selectType === "FromTo") {
+    if (calendarType !== "dayCalendar") {
+      throw new Error(
+        `_base.controls: FromTo 는 dayCalendar 에서만 사용 가능 (schema if/then)`,
+      );
+    }
+    out.StartDate = { Ckeys: [] };
+    out.EndDate = { Ckeys: [] };
+  }
+  return out;
+}
+
+/**
+ * InnerComboList — Combo.Dialog.Layouts[0].Controls[0] 위치의 ComboList.
+ * Fixed 모드 (UseDataSource:false + Items[]) 또는 DataSource 모드.
+ *
+ *   makeInnerComboList({ items: [{ ItemName: "활성", ItemValue: "A" }, ...] })
+ *   makeInnerComboList({ dataSourceName: "StatusDS", title: "StatusName" })
+ */
+export function makeInnerComboList({
+  items,
+  dataSourceName,
+  title,
+  saveNameKey = "ItemName",
+  saveValueKey = "ItemValue",
+  ckeys,
+} = {}) {
+  const useDS = typeof dataSourceName === "string";
+  const out = {
+    ControlType: "ComboList",
+    DlgCtrlType: "Common",
+    Ckeys: Array.isArray(ckeys) ? ckeys : [],
+    SaveNameKey: saveNameKey,
+    SaveValueKey: saveValueKey,
+    UseDataSource: useDS,
+    UseEvents: false,
+    isColumnCtrl: false,
+  };
+  if (useDS) {
+    out.DataSourceName = dataSourceName;
+    if (title != null) out.Title = title;
+  } else {
+    out.Items = Array.isArray(items) ? items : [];
+  }
+  return out;
+}
+
+/**
+ * InnerSearchList — Search.Dialog.Layouts[0].Controls[0] 위치의 List.
+ * Search 는 항상 DataSource 기반 — dataSourceName 필수.
+ *
+ *   makeInnerSearchList({
+ *     dataSourceName: "CustomerQuery",
+ *     title: "CustomerName",
+ *     useKeywordSearch: true,
+ *     keywordSearchCkey: "CustomerName",
+ *   })
+ */
+export function makeInnerSearchList({
+  dataSourceName,
+  title,
+  subTitle,
+  useKeywordSearch = false,
+  keywordSearchCkey,
+  useMultiData = false,
+  ckeys,
+} = {}) {
+  if (typeof dataSourceName !== "string") {
+    throw new Error(
+      `_base.controls: makeInnerSearchList 는 dataSourceName 필수`,
+    );
+  }
+  if (useKeywordSearch && typeof keywordSearchCkey !== "string") {
+    throw new Error(
+      `_base.controls: useKeywordSearch=true 면 keywordSearchCkey 필수 (schema if/then)`,
+    );
+  }
+  const out = {
+    ControlType: "List",
+    DataSourceName: dataSourceName,
+    Ckeys: Array.isArray(ckeys) ? ckeys : [],
+    UseKeywordSearch: useKeywordSearch,
+    UseMultiData: useMultiData,
+    UseEvents: false,
+    isColumnCtrl: false,
+  };
+  if (title != null) out.Title = title;
+  if (subTitle != null) out.SubTitle = subTitle;
+  if (useKeywordSearch) out.KeywordSearchCkey = keywordSearchCkey;
+  return out;
+}
+
+// ============================================================================
+// Public API — Group (컨테이너)
+// ============================================================================
+
+/**
+ * Group — ContentsType:"Group" 단일 컨테이너 노드 (Layout 통합됨).
+ *
+ *   makeGroup({ name: "ListWrap" })                        // 세로 (default)
+ *   makeGroup({ name: "TitleRow", direction: "horizontal" }) // 가로
+ *   makeGroup({ name: "Wrap", children: [c1, c2] })          // 자식 포함
+ *
+ * 규칙 (가이드 §6):
+ * - direction="horizontal" → DisplayStyle = { UseDisplay:true, DisplayType:"Flex", FlexDirection:"row" }
+ * - direction="vertical" (default) → DisplayStyle 키 자체를 emit 하지 않는다.
+ * - ContentsName 은 semantic ("ListWrap" / "TitleRow"). "Group1" 등 placeholder 금지 (가이드 §5).
+ */
+export function makeGroup({
+  name,
+  direction = "vertical",
+  children = [],
+} = {}) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError(`_base.controls: makeGroup 은 name 필수`);
+  }
+  if (direction !== "vertical" && direction !== "horizontal") {
+    throw new Error(
+      `_base.controls: makeGroup direction 은 'vertical' | 'horizontal' 만 허용`,
+    );
+  }
+  const out = {
+    ContentsType: "Group",
+    ContentsName: name,
+    ContentStyle: "None",
+    Width: { ...W_FULL },
+    UseDataConnection: false,
+    BgStyle: {},
+    BorderStyle: {},
+    Padding: {},
+    Margin: {},
+    Contents: Array.isArray(children) ? children : [],
+  };
+  if (direction === "horizontal") {
+    out.DisplayStyle = {
+      UseDisplay: true,
+      DisplayType: "Flex",
+      FlexDirection: "row",
+    };
+  }
+  // direction="vertical" → DisplayStyle 키 emit 안 함 (가이드 §10 hard don't).
+  return out;
+}
+
+// ============================================================================
+// Public API — 보조 메타 구조
+// ============================================================================
+
+const STEP_ID_RE = /^Step[1-9][0-9]*$/;
+
+/**
+ * MoveSteps — UseMove:true 일 때 Label / Group 의 "클릭 시 Step 이동" 정의.
+ * 단일 대상 Step 으로 단순 이동 (MoveTo:"Next" + Direction:"toRight").
+ *
+ *   { ...out, UseMove: true, MoveSteps: makeMoveSteps("Step3") }
+ *
+ * → { MoveStepOrder: ["Step3"], Step3: { MoveTo: "Next", Direction: "toRight" } }
+ *
+ * 더 복잡한 조건/방향이 필요하면 override(L1) 로 MoveSteps 를 직접 덮어쓴다.
+ */
+export function makeMoveSteps(stepId) {
+  if (typeof stepId !== "string" || !STEP_ID_RE.test(stepId)) {
+    throw new Error(
+      `_base.controls: makeMoveSteps 의 stepId 는 'Step<N>' 형식 (받은: ${JSON.stringify(stepId)})`,
+    );
+  }
+  return {
+    MoveStepOrder: [stepId],
+    [stepId]: { MoveTo: "Next", Direction: "toRight" },
+  };
+}
+
+// ============================================================================
+// 디스패처 / introspection
+// ============================================================================
+
+/**
+ * ControlType 문자열 → 팩토리 함수 매핑. resolvePattern 등에서 generic 호출용.
+ */
+export const factoryByControlType = Object.freeze({
+  Label: makeLabel,
+  InputText: makeInputText,
+  InputNumber: makeInputNumber,
+  InputMask: makeInputMask,
+  MultiInputBox: makeMultiInputBox,
+  InputDate: makeInputDate,
+  Combo: makeCombo,
+  Search: makeSearch,
+  CheckBox: makeCheckBox,
+  RadioBox: makeRadioBox,
+  ImageBox: makeImageBox,
+  InputFile: makeInputFile,
+  Calendar: makeCalendar,
+  CalendarNavigator: makeCalendarNavigator,
+  Tab: makeTab,
+  Tree: makeTree,
+  Embed: makeEmbed,
+});