@simplysm/angular 14.0.48 → 14.0.51

package/docs/recipes/crud-list/extension-c-inline-delete.md

@@ -0,0 +1,87 @@
+← [CRUD 리스트 레시피 진입점](../crud-list.md)
+
+# 확장 C: inline 삭제/복구 열
+
+> **선행:** [확장 A: inline 편집/저장](./extension-a-inline-edit.md) + [확장 B: 선택 기능 + 선택 삭제/복구](./extension-b-selection.md) (`isDeleted` 플래그 / `selectedItems` / `getItemCellStyleFn` 취소선은 확장 B가 도입)
+
+확장 B의 상단 "선택 삭제 / 선택 복구" 바(다건 일괄 토글) 위에, 시트 맨 앞 고정 컬럼에 **row별 inline 삭제/복구 아이콘**을 추가한다. 같은 `isDeleted` 플래그를 row별 빠른 토글 경로로 조작하는 보완 관계 — 다건 일괄 토글과 별도 경로가 아니라 **동일 플래그에 대한 다른 진입 UI**다.
+
+> **적용 조건:** DB Table에 `isDeleted` 컬럼이 있는 경우에만 사용한다. 컬럼이 없는 테이블은 물리 삭제(row DELETE)로 처리하며 이 확장을 사용하지 않는다 → [공통 규칙: 삭제 방식](../_common-rules.md#삭제-방식은-db-스키마에-따라-결정한다).
+
+**이 확장이 도입하는 요소:**
+
+- **imports:** `tablerEraser` / `tablerRestore` (확장 B가 이미 imports에 포함한 경우 추가 불필요)
+- **메서드:** `onToggleDeleteItemButtonClick(item)` — `item.isDeleted` 토글 후 `mark(this.items)`
+- **템플릿:** 시트 맨 앞에 `[fixed]="true" [key]="'_isDeleted'"` 고정 컬럼 추가 + `#headerTpl`(아이콘 헤더) + `[cell]`(`<sd-anchor>` 토글)
+
+> 상세: [`<sd-sheet-column> #headerTpl`](../../ui-data/sd-sheet.md#sdsheetcolumn) · [`<sd-anchor>`](../../ui-form/sd-anchor.md)
+
+> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 선행 확장(A+B) 위에 번호 순서대로 삽입할 지점을 나타낸다. 그대로 컴파일되지 않는다.
+
+```typescript
+// 1) 메서드 추가
+protected onToggleDeleteItemButtonClick(item: ICustomer): void {
+  item.isDeleted = !item.isDeleted;
+  mark(this.items);   // OnPush 재렌더 + diffs computed 알림
+}
+
+// 2) template — <sd-sheet> 가장 앞에 _isDeleted 고정 컬럼 삽입.
+//    canEdit() && viewType() === "page" 조건부 (modal/control 뷰나 권한 없음이면 열 자체 숨김)
+`
+<sd-sheet ...>
+  @if (canEdit() && viewType() === "page") {
+    <sd-sheet-column [fixed]="true" [key]="'_isDeleted'">
+      <ng-template #headerTpl>
+        <div class="p-xs-sm tx-center">
+          <ng-icon [svg]="tablerEraser" />
+        </div>
+      </ng-template>
+      <ng-template [cell]="items()" let-item="item">
+        <div class="p-xs-sm tx-center">
+          <sd-anchor [theme]="'danger'" (click)="onToggleDeleteItemButtonClick(item)">
+            <ng-icon [svg]="item.isDeleted ? tablerRestore : tablerEraser" />
+            {{ item.isDeleted ? "복구" : "삭제" }}
+          </sd-anchor>
+        </div>
+      </ng-template>
+    </sd-sheet-column>
+  }
+  <!-- 나머지 컬럼(id / name / phone / categoryId / ...)은 확장 A/B와 동일 -->
+</sd-sheet>
+`
+```
+
+**포인트:**
+
+- **확장 B와의 보완 관계.** 본 확장의 셀 아이콘 클릭과 확장 B의 상단 바 "선택 삭제 / 선택 복구"가 **같은 `isDeleted` 플래그**를 조작한다. 확장 B가 시트에 바인딩한 `[getItemCellStyleFn]` 취소선 스타일이 본 확장의 row별 토글 결과에도 그대로 반영된다. 선택 체크 없이 한 행만 빠르게 토글할 때는 이 확장, 여러 행을 한 번에 토글할 때는 확장 B를 사용한다.
+- **row 삭제는 `isDeleted` 플래그 토글로 표현.** 확장 A / B와 동일 원리. DB 반영은 확장 A의 저장 버튼(또는 Ctrl+S) 클릭 시 일괄 처리(soft-delete) — 상단 바(확장 B)가 confirm 후 즉시 DB 반영하는 것과 달리, 본 확장의 row별 토글은 저장 버튼을 눌러야 반영된다.
+- **컬럼 key는 `"_isDeleted"`** (언더스코어 prefix). `_` prefix를 붙여 DB 컬럼 key(`isDeleted` 등)와 분리한다 — 서버 정렬 키·시트 컬럼 지속성 설정 저장소와 충돌하지 않는 임의 키이기 때문. 상세는 아래 [🚫 흔한 실수](#컬럼-key를-isdeleted로-둔다) 참조.
+- **`canEdit() && viewType() === "page"` 조건부.** modal/control 뷰나 권한 없음이면 열 자체 숨김. 확장 A의 `canEdit = computed(() => perms().includes("edit") && viewType() === "page")`와 `viewType() === "page"` 이중 조건으로 의도를 선명하게 드러낸다. 본 확장의 셀은 `<sd-anchor>`만 사용하므로 [공통 규칙: 시트 셀 `[inset]/[size]`](../_common-rules.md#시트-셀-내부-컨트롤에-insettrue-sizesm을-명시한다) 대상이 아니다.
+- **`mark(this.items)` 호출 이유.** 필드 mutation(`item.isDeleted = !item.isDeleted`)은 signal의 참조를 바꾸지 않으므로, OnPush 재렌더와 `diffs` computed 통지를 위해 명시적 호출이 필요하다. 저장 감지 용도가 아님에 주의 — [공통 규칙: `mark(sig)`](../_common-rules.md#marksig를-저장-감지-수단으로-사용하지-않는다) 참조.
+
+**🚫 흔한 실수**
+
+> 공통 규칙(`mark` 저장 감지 오해, 시트 셀 `[inset]/[size]`, 삭제 방식 등)은 [레시피 공통 규칙](../_common-rules.md)을 참조한다. 본 섹션은 **inline 삭제/복구 확장 고유 실수**만 다룬다.
+
+### 컬럼 key를 `"isDeleted"`로 둔다
+
+```html
+<!-- ❌ 일반 DB 컬럼 key와 동일한 네이밍 — 서버 정렬 orderBy 키·시트 컬럼 지속성 설정과 충돌 -->
+<sd-sheet-column [fixed]="true" [key]="'isDeleted'">
+  <ng-template #headerTpl>...</ng-template>
+  <ng-template [cell]="items()" let-item="item">...</ng-template>
+</sd-sheet-column>
+
+<!-- ✅ 언더스코어 prefix로 분리 — DB 컬럼 key와 충돌하지 않는 임의 키 -->
+<sd-sheet-column [fixed]="true" [key]="'_isDeleted'">
+  <ng-template #headerTpl>...</ng-template>
+  <ng-template [cell]="items()" let-item="item">...</ng-template>
+</sd-sheet-column>
+```
+
+**근거**: `<sd-sheet-column>`의 `[key]`는 (a) 서버 정렬 `orderBy(key, ...)`의 키, (b) 시트 컬럼 순서·폭 등 지속성 설정(`[key]="'customer-list-sheet'"`에 종속된 저장소)의 컬럼 식별자로 쓰인다. 토글 아이콘 컬럼에 `"isDeleted"`를 그대로 부여하면 실제 DB 컬럼 `isDeleted`와 충돌하여, 사용자가 해당 컬럼 헤더를 드래그해 정렬하거나 폭을 조정할 때 의도하지 않은 저장 키가 덮어써진다. `_` prefix는 레시피 전반의 관례(예: 확장 A의 `_itemsSnapshot`)와 일치하며, 시트 내부 전용 컬럼임을 시각적으로도 구분한다.
+
+## Cross-reference
+
+- 진입점: [crud-list.md](../crud-list.md)
+- 선행: [확장 A: inline 편집/저장](./extension-a-inline-edit.md) + [확장 B: 선택 기능 + 선택 삭제/복구](./extension-b-selection.md)

package/docs/recipes/crud-list/extension-d-select-modal.md

@@ -0,0 +1,207 @@
+← [CRUD 리스트 레시피 진입점](../crud-list.md)
+
+# 확장 D: 선택 모달 전환
+
+> **선행:** [확장 A: inline 편집/저장](./extension-a-inline-edit.md) + [확장 B: 선택 기능](./extension-b-selection.md)
+
+같은 리스트 화면이 **다른 화면에서 항목을 골라주는 "선택 모달"로도 재사용**되도록 한다. 라우트로 진입하면 page 뷰(CRUD 리스트), `SdModalProvider.showAsync()`로 열리면 modal 뷰(selectMode에 따라 single/multi)로 자동 전환되며, 선택 결과를 `close.emit`으로 돌려준다.
+
+## When to use / When NOT to use
+
+- ✅ 같은 리스트를 라우트 페이지와 "선택 모달" 두 용도로 겸용
+- ✅ 항목을 골라 호출 측에 `SelectModalOutputResult<T>`로 돌려주는 selector 화면
+- ✅ multi 선택에서 페이지 이동 후에도 선택을 누적 유지해야 하는 경우
+- ❌ 부모 레코드의 자식 목록·이력을 **읽기 전용으로** 표시(닫기는 SdModal 기본 "X") → [확장 E](./extension-e-readonly-modal.md)
+- ❌ 리스트 **자체는 page** 이고 행 클릭 시 **편집 모달**만 띄우는 경우 → [확장 F](./extension-f-modal-edit.md). 확장 A(inline 편집)와 상호 배타
+- ❌ 리스트가 아닌 단일 값 셀렉트 버튼 → [`data-select-button.md`](../data-select-button.md)
+
+## 전제조건
+
+- 선행: 확장 A(inline 편집/저장) + 확장 B(선택 기능). 본 확장의 코드는 A의 `canEdit` / `_checkIgnoreChanges` 와 B의 `selectedItems` / `isDeleted` / `getItemCellStyleFn` / `selectMode="multi"` 를 그대로 재사용한다
+- 횡단 규칙: [`_common-rules.md`](../_common-rules.md) — 특히 [`injectViewTypeSignal()` 호출 시점](../_common-rules.md#injectviewtypesignal은-생성자-또는-필드-이니셜라이저에서만-호출한다), [signal 필드 초기값에서 다른 signal 읽기 금지](../_common-rules.md#signal-필드-초기값에서-다른-signal을-읽지-않는다)
+- 호출 측: `SdModalProvider.showAsync(CustomerList, { inputs: { selectMode: "multi", selectedItemKeys: [...] } })` 형태로 연다
+
+## 이 확장이 도입하는 요소
+
+| 영역 | 추가 |
+|------|------|
+| imports | `input`, `output` (`@angular/core`), `type SdSelectModal`, `type SelectModalOutputResult` (`@simplysm/angular`) |
+| 계약 | `implements SdSelectModal<ICustomer>` + `selectMode` input + `selectedItemKeys` input + `close` output |
+| 생성자 effect | modal 뷰일 때 `selectedItemKeys` → `selectedItems` 복원 (items 로드 후) |
+| `setupCanDeactivate` | modal 뷰에서 변경사항 체크 스킵 |
+| 메서드 | `onModalConfirmClick`, `onModalCancelClick` |
+| 파생 | `canEdit = computed(() => perms().includes("edit") && viewType() === "page")` — modal에서는 inline 편집 자동 비활성화 |
+| 템플릿 | `<sd-sheet>`에 `[selectMode]` / `[cumulativeSelection]` 조건부 바인딩 + modal 전용 하단 dock (확인/선택 해제) |
+
+## 코드 (확장 A + B 위에 얹는 diff)
+
+> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 선행 확장(A+B) 위에 번호 순서대로 삽입·교체할 지점을 나타낸다. 그대로 컴파일되지 않는다.
+
+```typescript
+// 1) imports 추가
+import { input, output } from "@angular/core";
+import { type SdSelectModal, type SelectModalOutputResult } from "@simplysm/angular";
+
+// 2) 클래스에 SdSelectModal<ICustomer> 계약 구현
+export class CustomerList implements SdSelectModal<ICustomer> {
+  // ... 기존 확장 A + B 멤버 ...
+
+  //== SdSelectModal<ICustomer> 계약 ==
+  selectMode = input<"single" | "multi" | undefined>();
+  selectedItemKeys = input<(number | undefined)[]>([]);
+  close = output<SelectModalOutputResult<ICustomer> | undefined>();
+
+  //== 파생 재정의 — modal 뷰에서는 inline 편집 자동 비활성화 ==
+  // canEdit을 viewType=="page" 조건으로 묶어, modal 뷰에서는 편집 셀·저장·등록 버튼이 자동으로 숨겨진다
+  canEdit = computed(() => this.perms().includes("edit") && this.viewType() === "page");
+
+  constructor() {
+    // ... 기존 초기 effect (필터/페이지/정렬 재조회) ...
+
+    // modal 뷰: selectedItemKeys → selectedItems 복원 (items 로드 후)
+    effect(() => {
+      if (this.viewType() !== "modal") return;
+
+      const keys = this.selectedItemKeys();
+      if (keys.length === 0) return;
+
+      const currItems = this.items();
+      if (currItems.length === 0) return;
+
+      untracked(() => {
+        const sel = currItems.filter((it) => keys.includes(this.trackByFn(it)));
+        if (sel.length > 0) this.selectedItems.set(sel);
+      });
+    });
+
+    // modal 뷰는 라우트 이탈 개념이 없으므로 변경사항 체크 스킵
+    setupCanDeactivate(() => this.viewType() === "modal" || this._checkIgnoreChanges());
+  }
+
+  // 3) 메서드 추가
+  onModalConfirmClick(): void {
+    const sel = this.selectedItems();
+    this.close.emit({
+      // id=undefined 신규 행 제거 — index fallback 금지(아래 Anti-patterns 참조)
+      selectedItemKeys: sel.map((it) => this.trackByFn(it)).filterExists(),
+      selectedItems: sel,
+    });
+  }
+
+  onModalCancelClick(): void {
+    this.selectedItems.set([]);
+
+    // single 모드에서만 즉시 close (multi는 "확인" 버튼 필요 — 아래 Anti-patterns 참조)
+    if (this.selectMode() === "single") {
+      this.close.emit({ selectedItemKeys: [], selectedItems: [] });
+    }
+  }
+}
+```
+
+```html
+<!-- 4) template — <sd-sheet>에 selectMode·cumulativeSelection 추가, 시트 뒤에 modal 하단 dock 배치 -->
+<sd-sheet
+  ...(기존)
+  [selectMode]="selectMode() ?? 'multi'"
+  [(selectedItems)]="selectedItems"
+  [cumulativeSelection]="viewType() === 'modal' && selectMode() === 'multi'"
+>
+  <!-- 컬럼들 동일 -->
+</sd-sheet>
+
+<!-- modal 하단 확인 바 -->
+@if (viewType() === "modal") {
+  <sd-dock
+    [position]="'bottom'"
+    class="p-sm-default flex-row main-align-end gap-sm bdt bdt-theme-gray-lightest"
+  >
+    <sd-button [size]="'sm'" [theme]="'danger'"
+      (click)="onModalCancelClick()"
+      [disabled]="selectedItems().length < 1">
+      선택 해제
+    </sd-button>
+    @if (selectMode() === "multi") {
+      <sd-button [size]="'sm'" [theme]="'primary'" (click)="onModalConfirmClick()">
+        확인({{ selectedItems().length }})
+      </sd-button>
+    }
+  </sd-dock>
+}
+```
+
+## 포인트
+
+- **`cumulativeSelection` 의도 — multi + modal에서만 활성화.** `<sd-sheet>`의 기본값은 `false`(`packages/angular/src/data/sheet/sd-sheet.ts:583`)이며, 켜지면 페이지를 넘어 선택을 **누적**한다. page 뷰의 "선택 삭제/복구"는 현재 페이지 행만 다루므로 누적하지 않는다. single 모드는 누적 개념이 없다.
+- **`canEdit`에 `viewType() === "page"` 조건 추가.** modal 뷰에서 자동으로 inline 편집 셀이 읽기 전용이 되고, 상단 "저장" 버튼과 inline 도구 dock(등록/선택 삭제·복구)이 숨겨진다. 선택 모달은 편집 목적이 아니다.
+- **`setupCanDeactivate`는 modal 뷰에서 무조건 true.** modal은 라우트 이탈 개념이 없으므로 변경사항 확인은 page 뷰에서만 수행한다.
+- **복원 effect는 items 로드 후에만 동작.** `items()`와 `selectedItemKeys()` 두 signal에 의존하고, set 호출이 자기 자신을 재실행하지 않도록 `untracked()`로 감싼다.
+
+## 🚫 Anti-patterns
+
+### modal = 선택 모달로 반사 단정
+
+진입점 [crud-list.md 의 "modal = 선택 모달로 반사적 부착"](../crud-list.md#modal--선택-모달로-반사적-부착)을 먼저 확인한다. 조회 전용 modal은 [확장 E](./extension-e-readonly-modal.md)로 분기하며 `SdSelectModal<T>` 계약을 부착하지 않는다.
+
+### multi 모드에서 "선택 해제"가 close까지 호출
+
+```typescript
+// ❌ multi에서도 close.emit — "선택 해제" 한 번으로 모달이 닫혀 다시 선택하려면 재오픈 필요
+onModalCancelClick(): void {
+  this.selectedItems.set([]);
+  this.close.emit({ selectedItemKeys: [], selectedItems: [] });
+}
+
+// ✅ single에서만 즉시 close. multi는 set([])만 수행 후 "확인" 버튼으로 최종 emit
+onModalCancelClick(): void {
+  this.selectedItems.set([]);
+  if (this.selectMode() === "single") {
+    this.close.emit({ selectedItemKeys: [], selectedItems: [] });
+  }
+}
+```
+
+**근거**: multi에서 "선택 해제" = "취소 + 닫기"가 되면 사용자가 다시 선택을 시작하려고 모달을 재오픈해야 한다. multi는 여러 행을 점진적으로 누적하는 UX이므로 닫는 트리거는 "확인" 버튼에만 둔다.
+
+### `selectedItemKeys` 반환에 index fallback
+
+```typescript
+// ❌ id=undefined 신규 행이 있을 때 index(0, 1, 2…)가 가짜 key로 들어가 호출 측이 잘못된 selection을 돌려받음
+this.close.emit({
+  selectedItemKeys: sel.map((it, i) => this.trackByFn(it) ?? i),
+  selectedItems: sel,
+});
+
+// ✅ undefined를 제거하여 확정된 key만 전달
+this.close.emit({
+  selectedItemKeys: sel.map((it) => this.trackByFn(it)).filterExists(),
+  selectedItems: sel,
+});
+```
+
+**근거**: `SelectModalOutputResult<T>.selectedItemKeys`는 호출 측이 DB 식별자로 사용한다(`packages/angular/src/core/select-modal-output-result.ts:4`). 신규 행 index를 섞으면 `[0, 1, 12345]` 같은 값이 호출 측의 "이미 저장된 id" 집합과 충돌한다. 신규 행은 모달에서 선택 대상이 아니며(DB에 없음), `filterExists`로 제거하는 것이 의미도 맞다.
+
+### `<sd-dock>`의 `[position]="'bottom'"` 생략
+
+```html
+<!-- ❌ position 생략 — 기본값이 top이 아니더라도 명시하지 않으면 레이아웃 의도가 깨질 수 있음 -->
+@if (viewType() === "modal") {
+  <sd-dock class="p-sm-default flex-row ..."> ... </sd-dock>
+}
+
+<!-- ✅ 하단 바는 반드시 [position]="'bottom'" 명시 -->
+@if (viewType() === "modal") {
+  <sd-dock [position]="'bottom'" class="..."> ... </sd-dock>
+}
+```
+
+**근거**: `<sd-dock>`은 부모 `<sd-dock-container>` 내부에서 position에 따라 top/right/bottom/left 중 한 곳에 배치된다. 확인 바는 시트 **아래**에 놓여야 하는 뷰별 고유 조각이므로 position을 누락하면 시트 위나 필터 옆으로 쌓이며 버튼이 본문 스크롤 안에 묻힌다.
+
+## 관련 Entry
+
+- 진입점: [crud-list.md](../crud-list.md)
+- 선행: [확장 A: inline 편집/저장](./extension-a-inline-edit.md) — `canEdit` / `_checkIgnoreChanges` 제공
+- 선행: [확장 B: 선택 기능](./extension-b-selection.md) — `selectedItems` / multi 선택 / `getItemCellStyleFn` 제공
+- 대안: [확장 E: 조회 전용 modal](./extension-e-readonly-modal.md) — 부모 레코드의 자식 목록·이력을 input으로 받아 읽기 전용 표시. `SdSelectModal<T>` 계약을 부착하지 않는다
+- 대안: [확장 F: 모달 편집 모드](./extension-f-modal-edit.md) — page 상에서 행 클릭 시 편집 모달. inline 편집(확장 A)과 상호 배타
+- 계약 타입: `SdSelectModal<T>` (`packages/angular/src/controls/button/sd-modal-select-button.ts:30`), `SelectModalOutputResult<T>` (`packages/angular/src/core/select-modal-output-result.ts:4`)

package/docs/recipes/crud-list/extension-e-readonly-modal.md

@@ -0,0 +1,165 @@
+← [CRUD 리스트 레시피 진입점](../crud-list.md)
+
+# 확장 E: 조회 전용 modal
+
+> **선행:** 없음 (최소 뼈대 §3에 직접 얹음 — 확장 A/B/D 미사용)
+
+호출자(상세 화면 등)가 부모 레코드 식별자를 input으로 전달하면, 이 modal은 해당 부모의 자식 목록·이력만 필터링해 읽기 전용으로 표시한다. 닫기는 SdModal 기본 "X" 버튼이며, 선택·확정·저장·이탈 방지는 전부 불필요하다.
+
+- ✅ 부모 레코드의 자식 목록·이력만 필터링해 읽기 전용으로 표시할 때
+- ❌ 항목을 골라 호출자에게 돌려줘야 할 때 → [확장 D: 선택 모달](./extension-d-select-modal.md)
+- ❌ 부모 레코드에 대한 inline 편집·삭제가 필요할 때 → [확장 A](./extension-a-inline-edit.md)(+B) 또는 [확장 F: 모달 편집](./extension-f-modal-edit.md)
+
+호출 예:
+
+```typescript
+await this._sdModal.showAsync({
+  title: "고객 주문 이력",
+  type: CustomerOrderHistoryModal,
+  inputs: { customerId: 123 },
+});
+```
+
+**이 확장이 도입하는 요소:**
+
+- **imports:** `input`(`@angular/core`), `expr`(`@simplysm/orm-common`) 추가
+- **input:** 부모 식별자(예: `customerId = input.required<number>()`)
+- **초기 effect 의존성:** 부모 식별자 input 추가
+- **`_search` 변경:** where절에 부모 식별자 하드 필터(`expr.eq(...)`), 기존 `filter.searchText` 조건과 AND
+- **부착하지 않는 요소:** `implements SdSelectModal<T>` 계약, `selectedItems` / 하단 확인 바 / `cumulativeSelection` / `canEdit` / `diffs` / `setupCanDeactivate` / `<sd-form #formCtrl>` 래퍼
+
+```typescript
+// 1) imports 추가 — @angular/core의 {input}
+import { input } from "@angular/core";
+
+// 2) 클래스 선언 — implements 없음. SdSelectModal<T> 계약 3종 부착 안 함
+export class CustomerOrderHistoryModal {
+  // ...DI, perms, 상태는 최소 뼈대와 동일
+
+  // 3) 부모 식별자 input (필수) — 맥락에 맞는 이름(customerId / orderId / companyId 등)
+  customerId = input.required<number>();
+
+  // 4) 초기 effect 의존성에 input 추가
+  constructor() {
+    effect(() => {
+      if (!this.perms().includes("use")) {
+        this.initialized.set(true);
+        return;
+      }
+
+      this.lastFilter();
+      this.page();
+      this.sortingDefs();
+      this.customerId();        // ← input 의존성 추가
+
+      void untracked(async () => {
+        this.busyCount.update((v) => v + 1);
+        await this._sdToast.try(async () => { await this._refresh(); });
+        this.busyCount.update((v) => v - 1);
+        this.initialized.set(true);
+      });
+    });
+  }
+
+  // 5) _search — where절에 부모 식별자 하드 필터. filter.searchText 등 기존 조건과 AND
+  private async _search(usePagination: boolean): Promise<{ items: ICustomerOrder[]; pageLength: number }> {
+    const filter = this.lastFilter();
+    const sortingDefs = this.sortingDefs();
+    const page = this.page();
+    const customerId = this.customerId();    // ← input 값
+
+    return this._appOrm.connectAsync(async (db) => {
+      let qr1 = db.customerOrder()
+        .where((item) => [expr.eq(item.customerId, customerId)]);
+
+      if (!str.isNullOrEmpty(filter.searchText)) {
+        qr1 = qr1.search((item) => [item.name], filter.searchText);
+      }
+      // 나머지는 최소 뼈대 _search와 동일 (paging/sorting/select/limit)
+      // ...
+    });
+  }
+}
+
+// 6) template — modal 전용 레이아웃. <sd-sheet>에 selectMode / selectedItems / cumulativeSelection 미사용.
+//    시트 셀은 순수 표시({{ item.name }}). 하단 "선택 해제 / 확인" 바, 상단 inline 도구 dock 부재.
+`
+<sd-topbar-container>
+  <sd-dock-container>
+    <sd-dock class="p-default">
+      <sd-form (formSubmit)="onFilterSubmit()">
+        <!-- 필터 (최소 뼈대와 동일) -->
+      </sd-form>
+    </sd-dock>
+
+    <sd-sheet
+      [key]="'customer-order-history-sheet'"
+      [items]="items()"
+      [(currentPage)]="page"
+      [totalPageCount]="pageLength()"
+      [(sorts)]="sortingDefs"
+      [trackByFn]="trackByFn"
+    >
+      <sd-sheet-column [key]="'name'" [header]="'이름'">
+        <ng-template [cell]="items()" let-item="item">
+          <div class="p-xs-sm">{{ item.name }}</div>
+        </ng-template>
+      </sd-sheet-column>
+      <!-- 필요한 조회 컬럼만 -->
+    </sd-sheet>
+  </sd-dock-container>
+</sd-topbar-container>
+`
+```
+
+**포인트:**
+
+- **부모 식별자는 호출자가 `inputs`으로 전달한다.** 값이 반드시 주어져야 하면 `input.required<T>()`, 없으면 전체 조회로 fallback하는 설계면 `input<T | undefined>()`. 어느 쪽이든 `_search`의 `where` 절과 초기 effect 의존성에 반드시 포함시킨다.
+- **닫기 = SdModal 기본 "X".** `close` output이 없으므로 `SdModalProvider.showAsync`의 리턴값도 사용하지 않는다. 호출 측은 `await showAsync(...)` 결과를 버리거나 `void`로 처리한다.
+- **시트는 읽기 전용.** `[cell]` 템플릿에 `<sd-textfield>` 대신 `{{ item.name }}` 같은 순수 표시만 쓰고, `let-edit="edit"` / `[readonly]="!edit"` / `(valueChange)="mark(items)"`는 제거한다. `canEdit` / `diffs` / `_itemsSnapshot` / `setupCanDeactivate`도 함께 제거한다.
+- **`viewType()` 분기는 쓰지 않아도 된다.** 조회 전용 modal은 보통 modal 전용으로 라우트 없이 등록된다. page/modal 양쪽을 모두 지원해야 할 때만 `viewType()`으로 topbar 영역을 분기하고, 시트·필터는 공통으로 둔다.
+- **input 반영 패턴은 공통 규칙을 따른다.** → [공통 규칙: input 변경을 effect 내부에서 filter·lastFilter·page에 반영한다](../_common-rules.md#input-변경을-effect-내부에서-filterlastfilterpage에-반영한다) · [공통 규칙: input 의존 데이터 로딩에 `void this._initAsync()`를 사용하지 않는다](../_common-rules.md#input-의존-데이터-로딩에-void-this_initasync를-사용하지-않는다)
+
+## 🚫 흔한 실수
+
+### signal 필드 초기값에서 부모 식별자 input 읽기
+
+```typescript
+// ❌ 필드 이니셜라이저는 클래스 생성 시점에 실행된다 — input 기본값만 반환
+filter = signal<IFilter>({
+  customerId: this.customerId(),   // 항상 undefined (required) / 초기값
+});
+
+// ✅ 기본값은 고정, 부모 식별자는 _search 호출부에서 input을 직접 읽는다
+filter = signal<IFilter>({});
+// _search 내부:
+const customerId = this.customerId();
+qr1 = qr1.where((item) => [expr.eq(item.customerId, customerId)]);
+```
+
+**근거**: 필드 이니셜라이저는 부모로부터 input 값이 전달되기 전에 실행되므로 항상 기본값만 반환한다. → [공통 규칙: signal 필드 초기값에서 다른 signal을 읽지 않는다](../_common-rules.md#signal-필드-초기값에서-다른-signal을-읽지-않는다)
+
+### modal = 선택 계약으로 반사 부착
+
+```typescript
+// ❌ 조회 전용인데 SdSelectModal 계약 일체를 그대로 이식
+export class CustomerOrderHistoryModal implements SdSelectModal<ICustomerOrder> {
+  selectMode = input<"single" | "multi">();
+  selectedItemKeys = input<any[]>([]);
+  close = output<SelectModalOutputResult<ICustomerOrder>>();
+  // ... cumulativeSelection, 하단 "선택 해제 / 확인" 바까지 전부
+}
+
+// ✅ 계약 없이 부모 식별자 input만 받는다
+export class CustomerOrderHistoryModal {
+  customerId = input.required<number>();
+  // ...
+}
+```
+
+**근거**: 조회 전용 modal은 선택 결과를 돌려주지 않는다. 계약을 부착하면 호출되지 않아 죽은 코드가 된다. 항목 선택이 필요하면 [확장 D: 선택 모달](./extension-d-select-modal.md).
+
+## Cross-reference
+
+- 진입점: [crud-list.md](../crud-list.md)
+- 관련: [확장 D: 선택 모달 전환](./extension-d-select-modal.md) (계약이 다른 modal 변형) · [확장 F: 모달 편집 모드](./extension-f-modal-edit.md) (부모 레코드 편집 modal)

package/docs/recipes/crud-list/extension-f-modal-edit.md

@@ -0,0 +1,177 @@
+← [CRUD 리스트 레시피 진입점](../crud-list.md)
+
+# 확장 F: 모달 편집 모드
+
+> **선행:** 없음 (최소 뼈대 §3에 직접 얹음 — [확장 A: inline 편집/저장](./extension-a-inline-edit.md)와 **상호 배타**)
+
+시트 셀 직접 수정(inline 편집) + 일괄 저장 대신, **행 클릭 시 편집 모달을 띄워 한 행씩 편집**하는 모드. 확장 A(inline 편집)와 **상호 배타**이므로 확장 A가 덧씌우는 파이프라인(`diffs` / `_itemsSnapshot` / `onSubmit` / `setupCanDeactivate` / `hostDirectives.sdSaveCommand` / `<sd-form #formCtrl>` 래퍼)을 이 확장에서는 부착하지 않는다. 대신 [`SdModalProvider.showAsync`](../../providers/sd-modal-provider.md)로 편집 모달을 호출하고, 모달 close 후 `_refresh()`로 리스트를 재조회한다.
+
+**이 확장이 도입하는 요소:**
+
+- **imports:** `SdAnchor`, `SdModalProvider`, `tablerEdit`
+- **DI:** `SdModalProvider`
+- **클래스 필드:** `tablerEdit` 아이콘 템플릿 참조
+- **메서드:** `onCreateItemButtonClick`, `onEditItemButtonClick`, `_editItem`
+- **템플릿:** 이름 컬럼 셀을 `<sd-anchor>` + 편집 아이콘으로 교체한다. inline 편집용 `<sd-textfield let-edit="edit">`는 사용하지 않는다. 등록 버튼은 `_editItem()` 직접 호출로 전환한다
+- **제거 대상(확장 A가 이미 적용되어 있는 경우):** `hostDirectives.sdSaveCommand` / `host (sdSaveCommand)` / `onSaveButtonClick` / `onSubmit` / `diffs` / `_itemsSnapshot` / `_checkIgnoreChanges` / `_upsertItem` / `getIsItemChanged` / `onRemoveNewItemButtonClick` / `setupCanDeactivate` / `<sd-form #formCtrl (formSubmit)="onSubmit()">` 래퍼
+
+> 상세: [`SdModalProvider.showAsync` 편집 모달 호출](../../providers/sd-modal-provider.md#편집-모달-호출) · [`<sd-anchor>`](../../ui-form/sd-anchor.md)
+
+> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 최소 뼈대 위에 번호 순서대로 삽입할 지점을 나타낸다. 그대로 컴파일되지 않는다.
+
+```typescript
+// 1) imports 추가
+import { SdAnchor, SdModalProvider } from "@simplysm/angular";
+import { tablerEdit } from "@ng-icons/tabler-icons";
+// 앱별 편집 모달 컴포넌트 (crud-detail.md 레시피로 작성):
+import { CustomerEditModal } from "./CustomerEditModal";
+
+// 2) DI 추가
+private readonly _sdModal = inject(SdModalProvider);
+
+// 3) 클래스 필드 추가 — 편집 버튼 아이콘
+protected readonly tablerEdit = tablerEdit;
+
+// 4) template — 이름 컬럼 셀을 <sd-anchor> + 편집 아이콘으로 교체한다.
+//    inline 편집용 <sd-textfield> / let-edit 바인딩은 쓰지 않는다.
+`
+<sd-sheet-column [key]="'name'" [header]="'이름'">
+  <ng-template [cell]="items()" let-item="item">
+    <sd-anchor (click)="onEditItemButtonClick(item, $event)" class="flex-row">
+      <div class="p-xs-sm">
+        <ng-icon [svg]="tablerEdit" />
+      </div>
+      <div class="flex-fill p-xs-sm">{{ item.name }}</div>
+    </sd-anchor>
+  </ng-template>
+</sd-sheet-column>
+`
+
+// 5) inline 편집용 도구 dock의 "등록" 버튼은 _editItem() 호출로 바꾼다.
+//    "선택 삭제/복구"를 남기려면 bulk API로 전환한다(아래 포인트 참조).
+// template:
+`<sd-button ... (click)="onCreateItemButtonClick()">등록</sd-button>`
+
+// 6) 메서드 교체
+protected async onCreateItemButtonClick(): Promise<void> {
+  await this._editItem();
+}
+
+protected async onEditItemButtonClick(item: ICustomer, event: MouseEvent): Promise<void> {
+  event.preventDefault();
+  event.stopPropagation();
+  await this._editItem(item);
+}
+
+private async _editItem(item?: ICustomer): Promise<void> {
+  const r = await this._sdModal.showAsync({
+    title: item == null ? "고객 등록" : "고객 수정",
+    type: CustomerEditModal,
+    inputs: { itemId: item?.id },
+  });
+  if (r != null) await this._refresh();
+}
+
+// 7) 제거 대상 (확장 A가 이미 적용되어 있는 경우 — 위 "제거 대상" 불릿 참조):
+//    - @Component hostDirectives의 sdSaveCommand / host의 (sdSaveCommand)
+//    - onSaveButtonClick / onSubmit / onAddItemButtonClick
+//    - diffs computed / _itemsSnapshot / _checkIgnoreChanges / _upsertItem
+//    - getIsItemChanged / onRemoveNewItemButtonClick
+//    - setupCanDeactivate(...) 호출 (이탈 방지는 편집 모달 쪽 책임)
+//    - <sd-form #formCtrl (formSubmit)="onSubmit()"> 래퍼 → <sd-sheet>를 main 영역에 직접 배치
+```
+
+**전환 후 남는 핵심 요소 체크리스트 (확장 A에서 확장 F로 이관 시 검증용):**
+
+- [x] `hostDirectives`: `sdRefreshCommand`만 유지 (`sdSaveCommand` 제거)
+- [x] host: `(sdRefreshCommand)="onRefreshButtonClick()"`만 유지
+- [x] DI: `_sdModal`, `_appOrm`, `_sdToast` (+ 선택적으로 확장 B 병용 시 `_appAuth`, `_appSharedData`)
+- [x] 상태: `items` / `page` / `pageLength` / `sortingDefs` / `filter` / `lastFilter` / `perms` / `viewType` / `viewTitle` / `busyCount` / `initialized`
+- [x] 메서드: `onFilterSubmit` / `onRefreshButtonClick` / `onCreateItemButtonClick` / `onEditItemButtonClick` / `_editItem` / `_refresh` / `_search` / `trackByFn`
+- [x] 템플릿: `<sd-form (formSubmit)="onFilterSubmit()">` 필터 dock + 이름 컬럼 `<sd-anchor>` + 기타 읽기 전용 셀
+- [x] `onRefreshButtonClick` 선두의 `if (!this._checkIgnoreChanges()) return;` **제거** (확장 A 잔재)
+
+**포인트:**
+
+- **모달 편집 모드에는 inline diff 개념이 없다.** 개별 item 변경은 `CustomerEditModal`(상세 폼) 내부에서 즉시 upsert하고 결과를 `close.emit(true)` 같은 신호로 반환한다. 리스트는 모달 close 후 `_refresh()`로 재조회한다.
+- **`CustomerEditModal`은 [`crud-detail.md`](../crud-detail.md) 레시피로 별도 작성한다.** modal 뷰 분기를 그대로 활용한다.
+- **시트 `[cell]` 템플릿에 `let-edit="edit"` / `[readonly]="!edit"` 바인딩은 불필요** — inline 편집이 아니며 읽기 전용 표시만 한다.
+- **"선택 삭제/복구"를 남길 경우 (확장 B와 병용):** `onToggleDeleteItemsButtonClick(del)` 내부를 diff 방식 대신 **bulk API 호출 + `_refresh()`** 로 구현한다. 확장 F는 `diffs` 파이프라인이 없어 확장 B 원본의 diff 경로가 동작하지 않기 때문이다.
+  ```typescript
+  protected async onToggleDeleteItemsButtonClick(del: boolean): Promise<void> {
+    if (this.busyCount() > 0) return;
+    const ids = this.selectedItems().map((it) => this.trackByFn(it)).filterExists();
+    if (ids.length === 0) return;
+
+    this.busyCount.update((v) => v + 1);
+    await this._sdToast.try(async () => {
+      await this._appOrm.connectAsync((db) =>
+        db.customer().where((c) => [expr.in(c.id, ids)])
+          .update(() => ({ isDeleted: del })));
+      await this._appSharedData.emitAsync(this.SHARED_DATA_KEY, ids);
+      this._sdToast.success(`${del ? "삭제" : "복구"}되었습니다.`);
+      await this._refresh();
+    });
+    this.busyCount.update((v) => v - 1);
+  }
+  ```
+- **`itemId: item?.id`**: `item`이 undefined이면 "등록", id가 있으면 "수정"으로 위임한다. `CustomerEditModal` 내부에서 id 유무로 분기한다.
+
+**🚫 흔한 실수**
+
+> 공통 규칙(`mark` 오용, `setupCanDeactivate` 호출 위치, 시트 셀 `[inset]`/`[size]` 등)은 [레시피 공통 규칙](../_common-rules.md)을 참조한다. 이 섹션은 **모달 편집 모드 고유 실수**만 다룬다.
+
+### 확장 A의 inline 편집 파이프라인과 동시 적용
+
+```typescript
+// ❌ 확장 A의 일괄 저장 경로와 확장 F의 모달 편집 경로를 모두 부착
+@Component({
+  hostDirectives: [
+    { directive: SdCommandDirective, outputs: ["sdRefreshCommand", "sdSaveCommand"] },
+  ],
+  host: {
+    "(sdSaveCommand)": "onSaveButtonClick()",   // 확장 A 경로 잔존
+  },
+  template: `
+    <sd-form #formCtrl (formSubmit)="onSubmit()">    <!-- 확장 A 래퍼 잔존 -->
+      <sd-sheet ...>
+        <sd-sheet-column [key]="'name'">
+          <ng-template [cell]="items()" let-item="item">
+            <sd-anchor (click)="onEditItemButtonClick(item, $event)"> <!-- 확장 F -->
+              <ng-icon [svg]="tablerEdit" /> {{ item.name }}
+            </sd-anchor>
+          </ng-template>
+        </sd-sheet-column>
+      </sd-sheet>
+    </sd-form>
+  `,
+})
+
+// ✅ 두 경로 중 하나만 선택한다. 확장 F를 선택하면 확장 A가 덧씌웠던 파이프라인은 전부 제거한다.
+@Component({
+  hostDirectives: [
+    { directive: SdCommandDirective, outputs: ["sdRefreshCommand"] },
+  ],
+  // (sdSaveCommand) host 바인딩 없음
+  template: `
+    <!-- <sd-form #formCtrl (formSubmit)="onSubmit()"> 래퍼 없음 -->
+    <sd-sheet ...>
+      <sd-sheet-column [key]="'name'">
+        <ng-template [cell]="items()" let-item="item">
+          <sd-anchor (click)="onEditItemButtonClick(item, $event)">
+            <ng-icon [svg]="tablerEdit" /> {{ item.name }}
+          </sd-anchor>
+        </ng-template>
+      </sd-sheet-column>
+    </sd-sheet>
+  `,
+})
+```
+
+**근거**: Ctrl+S가 어느 폼을 submit할지 모호해지고, `setupCanDeactivate`가 편집 모달 open 중에 이중 발동하며, 동일 행 편집 경로(inline vs 모달)가 둘 다 활성화되어 UX가 깨진다. "편집 모드"는 하나만 선택한다.
+
+## Cross-reference
+
+- 진입점: [crud-list.md](../crud-list.md)
+- 관련: [확장 A: inline 편집/저장](./extension-a-inline-edit.md) (이 확장과 상호 배타)
+- 공통 규칙: [_common-rules.md](../_common-rules.md)