@wipco/sdui 0.3.0 → 0.4.0

package/dist/meta.d.ts

@@ -122,6 +122,43 @@ interface SduiSlotMeta {
     text?: boolean;
     allow?: readonly string[];
 }
+/**
+ * 이 컴포넌트가 실제로 내놓는 HTML 요소.
+ *
+ * 어휘 이름만으로는 `Text`가 `<p>`가 되고 `Divider`가 `<hr>`이 된다는 것을 알 수 없다.
+ * 그런데 그 둘을 겹치면 **브라우저 파서가 `<p>`를 먼저 닫아** 스펙의 트리와 실제 DOM이
+ * 어긋나고, React가 하이드레이션 오류를 낸다. 빌더가 만들어 준 페이지가 콘솔에 경고를
+ * 남기면 사용자는 자기 잘못인 줄 안다 — 그래서 판정에 필요한 이 사실을 여기 적는다.
+ *
+ * **HTML 콘텐츠 모델을 통째로 옮기지 않는다.** 여기에는 "무슨 태그가 되는가"만 적고,
+ * 무엇이 무엇을 못 담는지는 판정하는 쪽(편집기의 `canDrop`)이 정한다. 규칙이 한곳에
+ * 모여 있어야 "금지로 할지 경고로 할지"를 실측으로 조정할 수 있기 때문이다.
+ */
+interface SduiDomMeta {
+    /**
+     * 루트로 나가는 요소 이름.
+     *
+     * `'fragment'`는 자기 요소 없이 자식을 그대로 흘려보낸다는 뜻이다(Show·Can·ForEach).
+     * 중첩 판정에서 **투명하게** 지나가야 하는 자리라 이름을 따로 뒀다.
+     */
+    element: string;
+    /**
+     * `element`를 바꾸는 프롭 이름 — 값이 곧 태그 이름이다(`Text.as`, `Button.as`).
+     *
+     * 프롭 값을 읽을 수 없는 자리(컴포넌트 이름만 아는 판정)에서는 `element`가 기본값이지만
+     * **확정이 아니다.** 그런 자리에서는 금지 대신 경고로 낮추라는 표시이기도 하다.
+     */
+    elementProp?: string;
+    /**
+     * 기본 자식(children)이 실제로 들어앉는 요소. 생략하면 `element`와 같다.
+     *
+     * 루트와 다른 경우가 실제로 있다 — `Alert`·`Toast`는 `<div>`로 시작하지만 본문은
+     * `<span class="wp-alert__text">` 안에 들어간다.
+     */
+    childElement?: string;
+    /** 이름 붙은 슬롯의 자식이 들어앉는 요소 — 기본 자식 자리와 다를 때만 적는다. */
+    slotElement?: Readonly<Record<string, string>>;
+}
 /** 캔버스의 크기 조정 핸들이 무엇을 건드릴지. */
 interface SduiResizeMeta {
     /**
@@ -160,6 +197,14 @@ interface SduiComponentMeta {
      */
     slots?: readonly SduiSlotMeta[];
     children: SduiChildrenMeta;
+    /**
+     * 이 컴포넌트가 내는 HTML 요소 — {@link SduiDomMeta} 참고.
+     *
+     * 선택 항목이다. 없으면 편집기는 이 컴포넌트가 낀 중첩을 **판정하지 않는다**.
+     * 소비 앱이 레지스트리에 얹은 컴포넌트(`ExcelUploadCard` 등)를 위해 그렇게 뒀다 —
+     * 판단 근거가 없다는 이유로 막으면 잘 도는 화면을 편집기가 거절하게 된다.
+     */
+    dom?: SduiDomMeta;
     /** 팔레트에서 끌어다 놓을 때 삽입할 조각. 그 자체로 렌더 가능해야 한다. */
     preset: SduiNode;
     resize: SduiResizeMeta;
@@ -295,6 +340,130 @@ declare const richComponentMeta: {
     MapPreview: SduiComponentMeta;
 };
 
+/**
+ * `@wipco/sdui/widgets` 어휘 21종의 빌더 메타데이터.
+ *
+ * core와 파일을 나눈 이유는 `rich.ts`와 같다 — 위젯을 얹지 않은 소비자가 이 데이터를
+ * 받지 않게 하려는 것이다. 여기도 값 import는 없다(`import type`만).
+ *
+ * 프롭 목록은 `src/widgets/*.tsx`의 **실제 프롭 인터페이스**와, ERP 스펙 84개를 훑어
+ * 뽑은 **실사용 프롭 집합**의 합집합이다. 대조 결과 이 21종에서 스펙이 쓰는 프롭 중
+ * 구현에 없는 것은 `AutocompleteField.endpoint` 하나뿐이고(아래 `legacy` 주석 참고),
+ * 나머지는 전부 구현에 존재한다.
+ *
+ * ## 함수 프롭을 메타데이터에 넣지 않은 자리
+ *
+ * `AutocompleteField.search`(검색 함수)와 `ImageLightbox.thumbStyle`처럼 JSON으로
+ * 표현할 수 없는 프롭은 빼 뒀다 — 속성 패널에 그려 봐야 채울 수단이 없다.
+ * `Table.columns[].render`를 core가 빼 둔 것과 같은 판단이다.
+ *
+ * ## 크기 조정을 대부분 'none'으로 둔 이유
+ *
+ * `SduiResizeMeta`는 enum 프롭·숫자 프롭·style 셋만 다룬다. `Timeline.maxHeight`나
+ * `TreeView.maxHeight`는 **CSS 길이 문자열**이고 이 위젯들은 `style`을 받지 않아
+ * 어느 갈래에도 들어맞지 않는다. 핸들을 그려 놓고 아무 일도 안 일어나는 것보다
+ * 그리지 않는 편이 낫다고 보고 'none'으로 뒀다.
+ */
+
+declare const AutocompleteFieldMeta: SduiComponentMeta;
+declare const InlineEditMeta: SduiComponentMeta;
+declare const JsonFieldMeta: SduiComponentMeta;
+declare const PeriodFilterMeta: SduiComponentMeta;
+declare const SearchableMultiPickerMeta: SduiComponentMeta;
+declare const TagMultiSelectMeta: SduiComponentMeta;
+declare const TreePickerMeta: SduiComponentMeta;
+declare const DisclosureMeta: SduiComponentMeta;
+declare const ImageLightboxMeta: SduiComponentMeta;
+declare const LiveClockMeta: SduiComponentMeta;
+declare const StackedMeterMeta: SduiComponentMeta;
+declare const TimelineMeta: SduiComponentMeta;
+declare const ColumnBoardMeta: SduiComponentMeta;
+declare const DiffViewMeta: SduiComponentMeta;
+declare const EventCalendarMeta: SduiComponentMeta;
+declare const OrgChartMeta: SduiComponentMeta;
+declare const SummaryTableMeta: SduiComponentMeta;
+declare const TreeViewMeta: SduiComponentMeta;
+declare const PrintSheetMeta: SduiComponentMeta;
+declare const SecureScreenMeta: SduiComponentMeta;
+declare const StripMeta: SduiComponentMeta;
+/**
+ * 위젯 어휘의 메타데이터.
+ *
+ * 키 타입이 `SduiWidgetComponentName | 'AutocompleteField'`인 이유:
+ * 앞의 20종은 `widgetComponents`와 키가 어긋나면 컴파일 에러가 나야 하고(core·rich와 같다),
+ * `AutocompleteField`는 그 묶음에 **일부러 빠져 있는** 이름이라 union에 직접 적어야 한다.
+ * 표시 계층만 라이브러리에 있고 조회는 앱 어댑터가 얹는 구조인데(widgets/index.ts 참고),
+ * 스펙과 빌더 입장에서는 엄연히 쓰는 어휘라 메타데이터까지 빼면 속성 패널이 6곳의
+ * 프롭을 못 그린다.
+ */
+declare const widgetComponentMeta: {
+    AutocompleteField: SduiComponentMeta;
+    ColumnBoard: SduiComponentMeta;
+    DiffView: SduiComponentMeta;
+    Disclosure: SduiComponentMeta;
+    EventCalendar: SduiComponentMeta;
+    ImageLightbox: SduiComponentMeta;
+    InlineEdit: SduiComponentMeta;
+    JsonField: SduiComponentMeta;
+    LiveClock: SduiComponentMeta;
+    OrgChart: SduiComponentMeta;
+    PeriodFilter: SduiComponentMeta;
+    PrintSheet: SduiComponentMeta;
+    SearchableMultiPicker: SduiComponentMeta;
+    SecureScreen: SduiComponentMeta;
+    StackedMeter: SduiComponentMeta;
+    Strip: SduiComponentMeta;
+    SummaryTable: SduiComponentMeta;
+    TagMultiSelect: SduiComponentMeta;
+    Timeline: SduiComponentMeta;
+    TreePicker: SduiComponentMeta;
+    TreeView: SduiComponentMeta;
+};
+
+/**
+ * 기본 어휘에 올라가 있지 않은 디자인 시스템 6종의 빌더 메타데이터.
+ *
+ * `components.tsx`에는 구현이 있고 export도 되지만 `defaultRegistry`에는 없는 이름들이다
+ * (registry.tsx의 주석 참고 — 기본 어휘를 넓히는 것은 별개 결정이라 보류돼 있다).
+ * 그래서 core.ts에 넣을 수 없다. 거기 `coreComponentMeta`는
+ * `Record<SduiComponentName, …>`이라 레지스트리에 없는 이름을 넣으면 컴파일이 막힌다.
+ *
+ * 그렇다고 메타데이터까지 없으면 곤란하다. 소비 앱은 이 여섯을 `createRegistry`로
+ * 직접 얹어 이미 쓰고 있고(ERP 레지스트리가 그렇다), 스펙도 Avatar·SegmentedControl을
+ * 쓴다. 메타데이터가 없으면 빌더가 그 노드의 프롭을 하나도 못 그린다.
+ *
+ * ## `satisfies Record<string, …>`인 이유
+ *
+ * core·rich·widgets는 레지스트리 묶음의 키 union과 대조해 "구현은 있는데 메타가 없다"를
+ * 컴파일 시점에 잡는다. 이 여섯은 그 대조 상대가 되는 묶음 자체가 없다 —
+ * 레지스트리에 안 올라가 있으니 union도 없다. 나중에 `defaultRegistry`에 올리게 되면
+ * 이 항목들을 core.ts로 옮기는 것이 맞고, 그때 대조가 자동으로 붙는다.
+ *
+ * 여기도 값 import는 없다(`import type`만).
+ */
+
+declare const RadioMeta: SduiComponentMeta;
+declare const SegmentedControlMeta: SduiComponentMeta;
+declare const AvatarMeta: SduiComponentMeta;
+declare const BreadcrumbMeta: SduiComponentMeta;
+declare const TooltipMeta: SduiComponentMeta;
+declare const SidebarNavMeta: SduiComponentMeta;
+/**
+ * 기본 어휘 밖 DS 6종의 메타데이터.
+ *
+ * `createRegistry`로 이 여섯을 얹은 소비자만 쓸 것이 있는 묶음이다. 얹지 않았다면
+ * 팔레트에 띄워 봐야 떨어뜨리는 순간 "등록되지 않은 컴포넌트"가 되므로,
+ * 그런 앱은 `paletteGroups(catalog)`에 자기 어휘만 추린 카탈로그를 넘기면 된다.
+ */
+declare const dsComponentMeta: {
+    Avatar: SduiComponentMeta;
+    Breadcrumb: SduiComponentMeta;
+    Radio: SduiComponentMeta;
+    SegmentedControl: SduiComponentMeta;
+    SidebarNav: SduiComponentMeta;
+    Tooltip: SduiComponentMeta;
+};
+
 /**
  * 렌더러 내장 어휘의 메타데이터.
  *
@@ -328,8 +497,17 @@ declare const SDUI_CATEGORIES: ReadonlyArray<{
     label: string;
 }>;
 /**
- * 기본 어휘 + rich 어휘 + 렌더러 내장 어휘 전체.
+ * 라이브러리가 아는 어휘 전체 — 기본 39 + rich 2 + 위젯 21 + DS 6 + 렌더러 내장 1 = 69종.
  * 편집기처럼 어휘 전부를 다뤄야 하는 쪽에서 쓴다.
+ *
+ * **레지스트리와 일대일이 아니다.** `defaultRegistry`에 없는 것도 들어 있다 —
+ * rich 2종, 위젯 21종, DS 6종은 소비자가 `createRegistry`로 직접 얹는 어휘라서
+ * 여기 있다고 곧바로 렌더되지는 않는다. 이 목록은 "빌더가 프롭을 그릴 줄 아는 이름"이지
+ * "지금 렌더할 수 있는 이름"이 아니다.
+ *
+ * 그래서 팔레트를 그리는 쪽은 자기 레지스트리에 맞춰 추린 카탈로그를
+ * `paletteGroups(catalog)`·`getComponentMeta(name, catalog)`에 넘기는 편이 낫다.
+ * 얹지 않은 컴포넌트를 팔레트에서 떨어뜨리면 "등록되지 않은 컴포넌트"가 되기 때문이다.
  */
 declare const allComponentMeta: Record<string, SduiComponentMeta>;
 /** 스펙의 `component` 이름으로 메타데이터를 찾는다. 없으면 undefined. */
@@ -348,4 +526,4 @@ declare function paletteGroups(catalog?: Record<string, SduiComponentMeta>): Arr
     items: SduiComponentMeta[];
 }>;
 
-export { ActionsMeta, AlertMeta, BadgeMeta, ButtonMeta, CanMeta, CardMeta, ChartMeta, CheckboxMeta, ColMeta, DatePickerMeta, DateRangePickerMeta, DialogMeta, DividerMeta, EmptyStateMeta, FieldMeta, ForEachMeta, FormMeta, GridMeta, IconButtonMeta, IconMeta, InputMeta, KeyValueListMeta, MapPreviewMeta, PageHeadMeta, PaginationMeta, ProgressBarMeta, RemoteSearchResultsMeta, RowMeta, SDUI_CATEGORIES, type SduiCategory, type SduiChildrenMeta, type SduiComponentMeta, type SduiEnumOption, type SduiPropGroup, type SduiPropKind, type SduiPropMeta, type SduiResizeMeta, type SduiSlotMeta, SearchResultsMeta, SectionMeta, SelectMeta, ShowMeta, SpacerMeta, SpinnerMeta, StatCardMeta, SwitchMeta, TableMeta, TabsMeta, TagMeta, TextMeta, TextareaMeta, ToastMeta, allComponentMeta, builtinComponentMeta, coreComponentMeta, getComponentMeta, paletteGroups, richComponentMeta, slotNamesOf };
+export { ActionsMeta, AlertMeta, AutocompleteFieldMeta, AvatarMeta, BadgeMeta, BreadcrumbMeta, ButtonMeta, CanMeta, CardMeta, ChartMeta, CheckboxMeta, ColMeta, ColumnBoardMeta, DatePickerMeta, DateRangePickerMeta, DialogMeta, DiffViewMeta, DisclosureMeta, DividerMeta, EmptyStateMeta, EventCalendarMeta, FieldMeta, ForEachMeta, FormMeta, GridMeta, IconButtonMeta, IconMeta, ImageLightboxMeta, InlineEditMeta, InputMeta, JsonFieldMeta, KeyValueListMeta, LiveClockMeta, MapPreviewMeta, OrgChartMeta, PageHeadMeta, PaginationMeta, PeriodFilterMeta, PrintSheetMeta, ProgressBarMeta, RadioMeta, RemoteSearchResultsMeta, RowMeta, SDUI_CATEGORIES, type SduiCategory, type SduiChildrenMeta, type SduiComponentMeta, type SduiDomMeta, type SduiEnumOption, type SduiPropGroup, type SduiPropKind, type SduiPropMeta, type SduiResizeMeta, type SduiSlotMeta, SearchResultsMeta, SearchableMultiPickerMeta, SectionMeta, SecureScreenMeta, SegmentedControlMeta, SelectMeta, ShowMeta, SidebarNavMeta, SpacerMeta, SpinnerMeta, StackedMeterMeta, StatCardMeta, StripMeta, SummaryTableMeta, SwitchMeta, TableMeta, TabsMeta, TagMeta, TagMultiSelectMeta, TextMeta, TextareaMeta, TimelineMeta, ToastMeta, TooltipMeta, TreePickerMeta, TreeViewMeta, allComponentMeta, builtinComponentMeta, coreComponentMeta, dsComponentMeta, getComponentMeta, paletteGroups, richComponentMeta, slotNamesOf, widgetComponentMeta };