@simplysm/angular 14.0.47 → 14.0.48

package/docs/ui-data.md

@@ -0,0 +1,333 @@
+# UI - Data
+
+## List
+
+### `SdList`
+
+리스트 컴포넌트.
+
+```typescript
+@Component({ selector: "sd-list" })
+class SdList {
+  inset = input(false, { transform: booleanAttribute });
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `inset` | `boolean` | `false` | 삽입 스타일 (테두리 없음) |
+
+### `SdListItem`
+
+리스트 항목 컴포넌트. 접기/펼치기 자식 리스트를 지원한다.
+
+```typescript
+@Component({ selector: "sd-list-item" })
+class SdListItem {
+  open = model(false);
+  selected = input(false, { transform: booleanAttribute });
+  readonly = input(false, { transform: booleanAttribute });
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `open` | `boolean` | `false` | 자식 리스트 펼침 (two-way) |
+| `selected` | `boolean` | `false` | 선택 상태 |
+| `readonly` | `boolean` | `false` | 읽기 전용 |
+
+## Sheet
+
+### `SdSheet`
+
+스프레드시트 컴포넌트. 정렬, 컬럼 고정, 리사이즈, 페이지네이션, 설정 저장을 지원한다.
+
+```typescript
+@Component({ selector: "sd-sheet" })
+class SdSheet<T> {
+  key = input<string>();
+  items = input<T[]>([]);
+  trackByFn = input<(item: T, index: number) => unknown>();
+  selectMode = input<"single" | "multi">();
+  getItemSelectableFn = input<(item: T) => boolean | string>();
+  getChildrenFn = input<(item: T, index: number) => T[] | undefined>();
+  useAutoSort = input(false, { transform: booleanAttribute });
+  visiblePageCount = input(10);
+  totalPageCount = input(0);
+  itemsPerPage = input(0);
+  inset = input(false, { transform: booleanAttribute });
+  hideConfigBar = input(false, { transform: booleanAttribute });
+  cumulativeSelection = input(false, { transform: booleanAttribute });
+
+  itemKeydown = output<SdSheetItemKeydownEventParam<T>>();
+  cellKeydown = output<SdSheetCellKeydownEventParam<T>>();
+
+  selectedItems = model<T[]>([]);
+  expandedItems = model<T[]>([]);
+  sorts = model<SortingDef[]>([]);
+  currentPage = model(0);
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `key` | `string \| undefined` | `undefined` | 설정 저장 키 |
+| `items` | `T[]` | `[]` | 표시할 항목 |
+| `trackByFn` | `((item, index) => unknown) \| undefined` | `undefined` | 트랙킹 함수 |
+| `selectMode` | `"single" \| "multi" \| undefined` | `undefined` | 선택 모드 |
+| `getItemSelectableFn` | `((item) => boolean \| string) \| undefined` | `undefined` | 선택 가능 여부 함수. string은 비활성 사유 |
+| `getChildrenFn` | `((item, index) => T[] \| undefined) \| undefined` | `undefined` | 트리 구조 자식 반환 함수 |
+| `useAutoSort` | `boolean` | `false` | 클라이언트 측 자동 정렬 |
+| `visiblePageCount` | `number` | `10` | 한 번에 표시할 페이지 수 |
+| `totalPageCount` | `number` | `0` | 총 페이지 수 |
+| `itemsPerPage` | `number` | `0` | 페이지당 항목 수 |
+| `inset` | `boolean` | `false` | 삽입 스타일 |
+| `hideConfigBar` | `boolean` | `false` | 설정 바 숨김 |
+| `cumulativeSelection` | `boolean` | `false` | `true`면 `items` 변경(페이지 이동/검색/필터 등) 시 `selectedItems`를 유지하여 다중 페이지 선택 누적을 실현. `false`(기본)면 `items` 변경 시 `selectedItems`를 `[]`로 초기화. 체크 표시 판정은 두 모드 모두 `trackByFn` + `obj.equal` 기반 key 비교이므로 **누적 모드 사용 시 `trackByFn` 지정 필수**(기본 `(item) => item`은 reference 반환이라 서버 페이지네이션 등에서 복원 실패). 누적 모드에서 명시적 초기화는 소비자가 직접 `selectedItems.set([])` 호출. 선택된 키 배열이 필요하면 `selectedItems().map((it, i) => trackByFn()(it, i))` 수동 호출 |
+| `currentPage` | `number` | `0` | 현재 페이지 (two-way) |
+| `sorts` | `SortingDef[]` | `[]` | 정렬 설정 (two-way). **`SortingDef.key`는 컬럼 `key`에 지정된 값 그대로이므로 `"vendor.name"` 같은 체인 경로일 수 있다.** 정렬 처리 시 `item[sort.key]` 단순 접근 금지 → `obj.getChainValue(item, sort.key)` 사용 |
+| `selectedItems` | `T[]` | `[]` | 선택된 항목 (two-way) |
+| `expandedItems` | `T[]` | `[]` | 확장된 항목 (two-way) |
+
+#### `cumulativeSelection` 사용 패턴
+
+시트의 용도에 따라 올바른 값이 다르다:
+
+- **선택 모달**(사용자가 여러 페이지 돌며 체크 후 확인 버튼으로 전체 반환) → `true`. 다중 페이지 선택이 유지되어야 한다
+- **현재 뷰 일괄 작업**(선택 삭제·복구 등 현재 페이지 내 처리) → `false` (기본값). `items` 변경 시 선택이 자동 초기화되어 오작동을 방지한다
+
+정적 `true`/`false`보다 **동적 computed 바인딩**으로 상황에 맞게 쓰는 것을 권장한다:
+
+```html
+<sd-sheet
+  [cumulativeSelection]="viewType() === 'modal' && selectMode() === 'multi'"
+  [trackByFn]="trackById"
+  ...
+>
+```
+
+- `viewType()` = `'modal'` + `selectMode()` = `'multi'`일 때만 누적
+- 그 외(page 뷰 또는 single 선택)는 기본 모드로 동작
+
+#### 주의사항
+
+- **초기 마운트 시 `selectedItems` 보존**: `cumulativeSelection=false`라도 **최초 `items` 구독 시점**의 `selectedItems`는 초기화되지 않는다. 이후 `items`가 교체될 때부터 초기화 규칙이 적용된다. 따라서 소비자가 컴포넌트 마운트 직후 초기 선택을 주입하는 시나리오는 안전하다.
+- **`trackByFn`은 index에 의존하지 않아야 한다**: 누적 모드에서 `selectedItems`는 현재 `displayItems`에 없는 다른 페이지 항목을 포함할 수 있다. 내부 key 비교는 이 항목에 대해 index를 `0`으로 fallback하여 `trackByFn(item, 0)`을 호출한다. `trackByFn`을 `(item, index) => \`${item.category}_${index}\`` 같이 **index에 의존하는 형태로 쓰면 동일 item에 대해 다른 key가 계산되어 `isSelected` 판정이 틀어진다**. 항상 item 속성만으로 key를 만든다: `(item) => item.id` 형태를 사용.
+
+### `SdSheetColumn`
+
+시트 컬럼 정의 디렉티브. 컬럼의 헤더, 너비, 고정, 정렬 등을 설정한다. 셀 내용은 `SdSheetColumnCellTemplate`으로 정의한다.
+
+```typescript
+@Directive({ selector: "sd-sheet-column" })
+class SdSheetColumn<T = unknown> {
+  key = input.required<string>();
+  header = input<string | string[]>("");
+  headerStyle = input<string>();
+  tooltip = input<string>();
+  width = input<string>();
+  fixed = input(false, { transform: booleanAttribute });
+  hidden = input(false, { transform: booleanAttribute });
+  collapse = input(false, { transform: booleanAttribute });
+  disableSorting = input(false, { transform: booleanAttribute });
+  disableResizing = input(false, { transform: booleanAttribute });
+  ordering = input(0);
+
+  cellTplRef = contentChild.required(SdSheetColumnCellTemplate, { read: TemplateRef });
+  headerTplRef = contentChild<TemplateRef<void>>("headerTpl");
+  summaryTplRef = contentChild<TemplateRef<void>>("summaryTpl");
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `key` | `string` | required | 컬럼 식별 키 |
+| `header` | `string \| string[]` | `""` | 헤더 텍스트 (배열이면 멀티 행 헤더) |
+| `headerStyle` | `string \| undefined` | - | 헤더 셀 인라인 스타일 |
+| `tooltip` | `string \| undefined` | - | 헤더 툴팁 텍스트 |
+| `width` | `string \| undefined` | - | 컬럼 너비 (예: `"100px"`) |
+| `fixed` | `boolean` | `false` | 고정 컬럼 |
+| `hidden` | `boolean` | `false` | 숨김 |
+| `collapse` | `boolean` | `false` | 접힘 (너비 축소) |
+| `disableSorting` | `boolean` | `false` | 정렬 비활성화 |
+| `disableResizing` | `boolean` | `false` | 리사이즈 비활성화 |
+| `ordering` | `number` | `0` | 순서 (낮을수록 앞) |
+
+Content children:
+- `SdSheetColumnCellTemplate` (required): 셀 렌더링 템플릿
+- `#headerTpl`: 커스텀 헤더 템플릿
+- `#summaryTpl`: 요약 행 템플릿
+
+### `SdSheetColumnCellTemplate`
+
+시트 컬럼 셀 내용을 정의하는 디렉티브. `ng-template[cell]` 셀렉터를 사용하며, `SdSheetCellContext` 타입 가드를 제공한다.
+
+```typescript
+@Directive({ selector: "ng-template[cell]" })
+class SdSheetColumnCellTemplate<T> {
+  cell = input.required<T[]>();
+
+  static ngTemplateContextGuard<TContextItem>(
+    _dir: SdSheetColumnCellTemplate<TContextItem>,
+    _ctx: unknown,
+  ): _ctx is SdSheetCellContext<TContextItem>;
+}
+```
+
+사용법:
+```html
+<sd-sheet-column key="name" header="이름">
+  <ng-template [cell]="items()" let-item>
+    {{ item.name }}
+  </ng-template>
+</sd-sheet-column>
+```
+
+**셀 내용 작성 지침**:
+
+- **일반 텍스트/값 표시**: 바깥에 `<div class="p-xs-sm">`로 감싸 기본 패딩을 적용한다. 정렬이 필요하면 `tx-right`, `tx-center` 등을 함께 사용한다.
+- **컨트롤(textfield/select/checkbox 등) 삽입**: 반드시 `[inset]="true"`와 `[size]="'sm'"`을 지정한다. `inset`은 컨트롤의 테두리·배경을 제거해 셀에 자연스럽게 녹아들게 하고, `sm` 사이즈는 시트 행 높이에 맞춘다. 이 경우 별도 `p-xs-sm` 래퍼는 사용하지 않는다.
+
+예시:
+```html
+<!-- 일반 값 표시 -->
+<sd-sheet-column [fixed]="true" [header]="'#'" [key]="'id'">
+  <ng-template [cell]="items()" let-item>
+    <div class="p-xs-sm tx-right">{{ item.id }}</div>
+  </ng-template>
+</sd-sheet-column>
+
+<!-- 컨트롤 삽입 -->
+<sd-sheet-column [header]="'코드'" [key]="'code'">
+  <ng-template [cell]="items()" let-item let-edit="edit">
+    <sd-textfield
+      [type]="'text'"
+      [inset]="true"
+      [size]="'sm'"
+      [required]="true"
+      [disabled]="!canEdit()"
+      [readonly]="!edit"
+      [(value)]="item.code"
+      (valueChange)="mark(items)"
+    />
+  </ng-template>
+</sd-sheet-column>
+```
+
+### `SdSheetCellContext`
+
+시트 셀 템플릿 컨텍스트.
+
+```typescript
+interface SdSheetCellContext<T = unknown> {
+  $implicit: T;
+  item: T;
+  index: number;
+  depth: number;
+  edit: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `$implicit` | `T` | 현재 항목 (let-item으로 접근) |
+| `item` | `T` | 현재 항목 (명시적 접근) |
+| `index` | `number` | 행 인덱스 |
+| `depth` | `number` | 트리 깊이 |
+| `edit` | `boolean` | 편집 모드 여부 (인라인 편집 지원 시 셀에서 참조) |
+
+### `SdSheetConfigModal`
+
+시트 설정 모달. 컬럼 표시/숨김, 고정, 너비 등을 설정한다.
+
+```typescript
+@Component({ selector: "sd-sheet-config-modal" })
+class SdSheetConfigModal implements SdModalContentDef<SdSheetConfig> {
+  controls = input.required<readonly SdSheetColumn[]>();
+  config = input.required<SdSheetConfig | undefined>();
+  close = output<SdSheetConfig>();
+  initialized = signal(true);
+}
+```
+
+### `SdSheetColumnDef`
+
+```typescript
+interface SdSheetColumnDef {
+  key: string;
+  header: string | string[];
+  headerStyle: string | undefined;
+  tooltip: string | undefined;
+  width: string | undefined;
+  fixed: boolean;
+  hidden: boolean;
+  collapse: boolean;
+  disableSorting: boolean;
+  disableResizing: boolean;
+  ordering: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | `string` | 컬럼 식별 키 |
+| `header` | `string \| string[]` | 헤더 텍스트 |
+| `headerStyle` | `string \| undefined` | 헤더 셀 인라인 스타일 |
+| `tooltip` | `string \| undefined` | 헤더 툴팁 텍스트 |
+| `width` | `string \| undefined` | 컬럼 너비 |
+| `fixed` | `boolean` | 고정 컬럼 여부 |
+| `hidden` | `boolean` | 숨김 여부 |
+| `collapse` | `boolean` | 접힘 여부 |
+| `disableSorting` | `boolean` | 정렬 비활성화 여부 |
+| `disableResizing` | `boolean` | 리사이즈 비활성화 여부 |
+| `ordering` | `number` | 순서 |
+
+### `SdSheetConfig`
+
+```typescript
+interface SdSheetConfig {
+  columnRecord: Record<string, {
+    width?: string;
+    hidden?: boolean;
+    fixed?: boolean;
+    ordering?: number;
+  }>;
+}
+```
+
+### `SdSheetHeaderDef`
+
+```typescript
+interface SdSheetHeaderDef {
+  text: string;
+  colspan: number;
+  rowspan: number;
+  isLastRow: boolean;
+  colDef: SdSheetColumnDef | undefined;
+}
+```
+
+### `SdSheetItemKeydownEventParam`
+
+```typescript
+interface SdSheetItemKeydownEventParam<T> {
+  item: T;
+  event: KeyboardEvent;
+}
+```
+
+### `SdSheetCellKeydownEventParam`
+
+```typescript
+interface SdSheetCellKeydownEventParam<T> {
+  item: T;
+  key: string;
+  event: KeyboardEvent;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `item` | `T` | 해당 행 항목 |
+| `key` | `string` | 컬럼 키 |
+| `event` | `KeyboardEvent` | 키보드 이벤트 |