@simplysm/angular 14.0.51 → 14.0.53

package/docs/recipes/crud-detail/extension-a-edit-save.md

@@ -1,230 +0,0 @@
-← [CRUD 상세폼 레시피 진입점](../crud-detail.md)
-
-# 확장 A: 편집/저장
-
-> **선행:** 없음 (최소 뼈대 §3에 직접 얹음)
-
-최소 뼈대의 읽기 전용 필드를 **편집 가능**으로 바꾸고, topbar에 "저장" 버튼(또는 Ctrl+S)을 추가하여 **일괄 저장**을 도입한다. `obj.clone(this.data())` snapshot + `obj.equal(data, _dataSnapshot)` 기반 변경 감지를 부착하고, 라우트 이탈 시 미저장 변경사항을 확인하는 `setupCanDeactivate` 가드를 등록한다. 편집은 page/modal/control 모든 뷰에서 동작하며, 뷰별 UI 배치는 [확장 C](./extension-c-modal-view.md)/[확장 D](./extension-d-control-view.md)에서 처리한다.
-
-**이 확장이 도입하는 요소:**
-
-- **imports:** `computed`, `viewChild`, `obj`, `setupCanDeactivate`, `mark`, `SdCommandDirective` outputs에 `sdSaveCommand` 추가, 아이콘 `tablerDeviceFloppy`
-- **DI:** 없음 (최소 뼈대와 동일)
-- **파생:** `canEdit = computed(() => perms().includes("edit"))` (뷰 분기 없음 — 편집은 3뷰 모두에서 가능, 뷰별 UI는 [확장 C](./extension-c-modal-view.md)/[확장 D](./extension-d-control-view.md)에서 분기)
-- **상태:** `_dataSnapshot?: ICustomer` (직전 `_refresh()` 시점 data의 깊은 복제), `isNew = computed(() => data().id == null)` (신규 레코드 여부)
-- **권한 키 확장:** `injectPermsSignal` 두 번째 인자 `["use"]` → `["use", "edit"]`
-- **hostDirectives·host:** `outputs`에 `sdSaveCommand` 추가, `host`에 `(sdSaveCommand)="onSaveButtonClick()"` 추가
-- **viewChild:** `formCtrl = viewChild<SdForm>("formCtrl")` (Ctrl+S 경로 통합용)
-- **메서드:** `onSaveButtonClick`, `onSubmit`, `_checkIgnoreChanges`; `onRefreshButtonClick` 선두에 변경 체크 추가
-- **for Template:** `protected readonly mark = mark;` (템플릿 `(valueChange)="mark(data)"` 호출용)
-- **생성자:** 기존 초기 effect 뒤에 `setupCanDeactivate(() => this._checkIgnoreChanges())`
-- **템플릿:** topbar에 "저장" 버튼 추가(`@if (canEdit())`), `<sd-form>` → `<sd-form #formCtrl (formSubmit)="onSubmit()">` 교체, 필드 `[readonly]="true"` → `[disabled]="!canEdit()"` 전환, 모든 입력 필드에 `(valueChange)="mark(data)"` 추가
-- **_refresh 변경:** 말미에 `this._dataSnapshot = data.id == null ? undefined : obj.clone(this.data());` 추가
-
-> 상세: [`<sd-form> #formCtrl / requestSubmit()`](../../ui-form/sd-form.md) · [`setupCanDeactivate`](../../utils/setup-functions.md#setupcandeactivate)
-
-> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 최소 뼈대 위에 번호 순서대로 삽입·교체할 지점을 나타낸다. 그대로 컴파일되지 않는다.
-
-```typescript
-// 1) imports 교체 — @angular/core에 {computed, viewChild} 추가, @simplysm/core-common에 {obj} 추가,
-//    @simplysm/angular에 {setupCanDeactivate, mark} 추가, 아이콘에 tablerDeviceFloppy 추가.
-import { tablerAlertTriangle, tablerDeviceFloppy, tablerRefresh } from "@ng-icons/tabler-icons";
-import {
-  ChangeDetectionStrategy, Component, computed, effect, inject, input, signal, untracked,
-  viewChild, ViewEncapsulation,
-} from "@angular/core";
-import { type DateTime, obj } from "@simplysm/core-common";
-import {
-  FormatPipe, injectPermsSignal, injectViewTitleSignal, mark,
-  SdBusyContainer, SdButton, SdCommandDirective,
-  SdForm, SdTextfield, SdToastProvider, SdTopbar, SdTopbarContainer,
-  setupCanDeactivate,
-} from "@simplysm/angular";
-
-// 2) @Component — hostDirectives outputs에 "sdSaveCommand" 추가, host에 (sdSaveCommand) 바인딩 추가.
-@Component({
-  // ...selector/changeDetection/encapsulation/standalone/imports 동일
-  hostDirectives: [
-    { directive: SdCommandDirective, outputs: ["sdRefreshCommand", "sdSaveCommand"] },
-  ],
-  host: {
-    "(sdRefreshCommand)": "onRefreshButtonClick()",
-    "(sdSaveCommand)": "onSaveButtonClick()",
-  },
-  // template: 아래 6)에서 상세
-})
-
-// 3) 권한 키 확장 — ["use"] → ["use", "edit"]
-perms = injectPermsSignal(["sales.customer"], ["use", "edit"]);
-
-// 4) 파생·상태·viewChild 추가
-protected readonly canEdit = computed(() => this.perms().includes("edit"));
-protected readonly isNew = computed(() => this.data().id == null);
-private _dataSnapshot?: ICustomer;
-
-protected readonly formCtrl = viewChild<SdForm>("formCtrl");
-
-// 5) 생성자에 setupCanDeactivate 추가 (기존 초기 effect 뒤)
-constructor() {
-  // 기존 초기 effect 동일...
-  setupCanDeactivate(() => this._checkIgnoreChanges());
-}
-
-// 6) template — topbar에 "저장" 버튼 추가, <sd-form>을 <sd-form #formCtrl (formSubmit)>로 교체,
-//    필드 [readonly]="true" → [disabled]="!canEdit()"로 전환, 입력 필드에 (valueChange)="mark(data)" 추가.
-template: `
-  <sd-busy-container [busy]="busyCount() > 0">
-    @if (initialized()) {
-      @if (!perms().includes("use")) { <!-- 경고 동일 --> }
-      @else {
-        <sd-topbar-container>
-          <sd-topbar>
-            <h4>{{ viewTitle() }}</h4>
-            @if (canEdit()) {
-              <sd-button [theme]="'link-primary'" (click)="onSaveButtonClick()">
-                <ng-icon [svg]="tablerDeviceFloppy" /> 저장 <small>(CTRL+S)</small>
-              </sd-button>
-            }
-            <sd-button [theme]="'link-info'" (click)="onRefreshButtonClick()">
-              <ng-icon [svg]="tablerRefresh" /> 새로고침 <small>(CTRL+ALT+L)</small>
-            </sd-button>
-          </sd-topbar>
-
-          <div class="flex-column fill">
-            <sd-form #formCtrl (formSubmit)="onSubmit()" class="flex-fill">
-              <div class="p-default">
-                <table class="form-table">
-                  <tbody>
-                    <tr>
-                      <th>명칭</th>
-                      <td>
-                        <sd-textfield
-                          [type]="'text'" [required]="true"
-                          [disabled]="!canEdit()" [(value)]="data().name"
-                          (valueChange)="mark(data)"
-                        />
-                      </td>
-                    </tr>
-                    <tr>
-                      <th>전화번호</th>
-                      <td>
-                        <sd-textfield
-                          [type]="'text'" [disabled]="!canEdit()"
-                          [(value)]="data().phone"
-                          (valueChange)="mark(data)"
-                        />
-                      </td>
-                    </tr>
-                  </tbody>
-                </table>
-              </div>
-            </sd-form>
-            <!-- lastModified 블록 동일 (최소 뼈대 §3) -->
-          </div>
-        </sd-topbar-container>
-      }
-    }
-  </sd-busy-container>
-`
-
-// 7) 메서드 추가 — onSaveButtonClick / onSubmit / _checkIgnoreChanges
-protected onSaveButtonClick(): void {
-  this.formCtrl()?.requestSubmit();
-}
-
-protected async onSubmit(): Promise<void> {
-  if (this.busyCount() > 0) return;
-  if (!this.perms().includes("edit")) return;
-
-  // 신규는 변경 체크 없이 저장. 기존 항목이면 snapshot 대비 변경 여부를 판정.
-  if (!this.isNew() && this._dataSnapshot != null && obj.equal(this.data(), this._dataSnapshot)) {
-    this._sdToast.info("변경사항이 없습니다.");
-    return;
-  }
-
-  this.busyCount.update((v) => v + 1);
-  await this._sdToast.try(async () => {
-    // 앱별 ORM upsert — 예:
-    //   await this._appOrm.connectAsync(async (db) => {
-    //     await db.customer()
-    //       .where((c) => [expr.eq(c.id, this.data().id)])
-    //       .upsert(() => ({ name: this.data().name, phone: this.data().phone }));
-    //   });
-    // 검증 실패 시 throw 하면 sdToast.try가 포착하여 에러 토스트를 표시한다 (이후 흐름은 생략).
-
-    this._sdToast.success("저장되었습니다.");
-    await this._refresh();
-  });
-  this.busyCount.update((v) => v - 1);
-}
-
-private _checkIgnoreChanges(): boolean {
-  return (
-    this._dataSnapshot == null ||
-    obj.equal(this.data(), this._dataSnapshot) ||
-    confirm("변경사항이 있습니다. 무시하고 진행하시겠습니까?")
-  );
-}
-
-// 8) onRefreshButtonClick 선두에 변경 체크 추가
-protected async onRefreshButtonClick(): Promise<void> {
-  if (this.busyCount() > 0) return;
-  if (!this.perms().includes("use")) return;
-  if (!this._checkIgnoreChanges()) return;
-
-  this.busyCount.update((v) => v + 1);
-  await this._sdToast.try(async () => {
-    await this._refresh();
-  });
-  this.busyCount.update((v) => v - 1);
-}
-
-// 9) _refresh 말미에 snapshot 갱신
-private async _refresh(): Promise<void> {
-  // ... (최소 뼈대 동일 조회 로직)
-
-  this.data.set(data);
-  // 신규(id == null)면 snapshot을 비워 변경 체크를 항상 통과시키고 저장을 허용한다.
-  this._dataSnapshot = data.id == null ? undefined : obj.clone(this.data());
-}
-
-// 10) 아이콘 + mark 템플릿 참조 추가
-protected readonly tablerDeviceFloppy = tablerDeviceFloppy;
-protected readonly mark = mark;
-```
-
-**포인트:**
-
-- **`obj.equal`은 deep equal**(`packages/core-common/src/utils/obj.ts:172`)이므로 `data().field = "x"` 같은 field mutation도 snapshot 대비 **저장 판정에 자동 반영**된다. 입력 필드의 `(valueChange)="mark(data)"`는 OnPush 재렌더링·연계 computed 갱신을 위한 **통지** 용도이며, 값 비교(저장 감지)와는 별개다.
-- **snapshot은 반드시 `obj.clone`으로 깊은 복제한다.** `this._dataSnapshot = this.data()` 같은 얕은 참조 대입은 `data().field = "x"` mutation을 snapshot까지 오염시켜 변경 감지가 실패한다. `_refresh()` 말미에서 `obj.clone`(`packages/core-common/src/utils/obj.ts:19`)으로 저장해야 비교가 정확히 동작한다.
-- **`isNew = computed(() => data().id == null)`은 PK 형태에 주의한다.** 클라이언트 UUID 선할당·자연키·복합키처럼 신규 상태에서도 `id`가 존재하는 스키마에서는 이 판정이 깨진다. 해당 스키마는 `isNew`를 `signal<boolean>(false)`로 유지하고 `_refresh()` 내부에서 명시 세팅하며, snapshot 분기도 `this.isNew() ? undefined : obj.clone(this.data())`로 치환한다.
-- **Ctrl+S 경로 통일:** `hostDirectives` → `(sdSaveCommand)="onSaveButtonClick()"` → `formCtrl()?.requestSubmit()` → `<sd-form (formSubmit)="onSubmit()">`. 버튼 클릭과 단축키가 완전히 동일한 경로로 수렴한다.
-- **`setupCanDeactivate(() => this._checkIgnoreChanges())`** — 라우트 이탈 시 snapshot 대비 변경이 있으면 `confirm`으로 사용자 확인을 요청한다. [확장 C](./extension-c-modal-view.md)(modal 뷰)에서는 조건에 `viewType() === "modal" ||`를 추가하여 modal에서는 항상 이탈을 허용한다.
-- **조용한 저장(`hideNoChangeMessage` 대응):** 프로그래밍 저장(예: 출력 직전 저장)에서 "변경사항이 없습니다" info 토스트를 억제하려면 `onSubmit(silent: boolean)` 시그니처를 도입하여 `if (!silent) this._sdToast.info(...)`로 감싼다.
-- **`_checkIgnoreChanges`는 `_dataSnapshot == null`을 true로 취급** — 신규(snapshot 없음)이거나 아직 로드 전이면 이탈·새로고침을 즉시 허용한다. snapshot이 있어도 `obj.equal`로 값이 동일하면 허용.
-
-## 🚫 흔한 실수 (Anti-patterns)
-
-> 공통 규칙(`mark` 오용 전반, `setupCanDeactivate` 호출 위치, `_sdSharedData.wait()` 조건, 시트 셀 `[inset]`/`[size]`, soft-delete 선택 기준)은 [레시피 공통 규칙](../_common-rules.md)을 참조한다. 이 섹션은 **편집/저장 확장 고유 실수**만 다룬다.
-
-### `mark(data)` 호출 여부로 저장 여부를 판정한다
-
-```typescript
-// ❌ mark 호출 여부로 저장 가능 여부를 분기 — 의미 없는 전제
-protected async onSubmit(): Promise<void> {
-  if (!this._lastMarkCalled) return;   // "mark가 호출되지 않았으니 변경이 없다"는 잘못된 판정
-  // ...
-}
-
-// ✅ snapshot과 현재값을 obj.equal로 비교하여 변경 판단
-protected async onSubmit(): Promise<void> {
-  if (!this.isNew() && this._dataSnapshot != null
-      && obj.equal(this.data(), this._dataSnapshot)) {
-    this._sdToast.info("변경사항이 없습니다.");
-    return;
-  }
-  // ... 저장 로직
-}
-```
-
-**근거**: `mark(sig)`는 `WritableSignal` 값을 shallow copy하여 OnPush 재렌더링·연계 computed 알림을 유발하는 **통지** 수단이다(`packages/angular/src/core/mark.ts`). 값이 실제로 바뀌었는지 "감지"하는 역할은 아니며, 값 비교는 `obj.equal` deep equal이 담당한다. → [공통 규칙: `mark(sig)`를 '저장 감지' 수단으로 사용하지 않는다](../_common-rules.md#marksig를-저장-감지-수단으로-사용하지-않는다)

package/docs/recipes/crud-detail/extension-b-delete-restore.md

@@ -1,142 +0,0 @@
-← [CRUD 상세폼 레시피 진입점](../crud-detail.md)
-
-# 확장 B: 삭제/복구 토글
-
-> **선행:** [확장 A: 편집/저장](./extension-a-edit-save.md)
-
-확장 A(편집/저장)를 전제로, 기존 레코드에 대한 **soft-delete 토글**(삭제/복구 버튼)을 추가한다. 도메인 타입에 `isDeleted: boolean` 필드를 추가하고, 삭제·복구 버튼은 최소 뼈대의 topbar에 `@if (!isNew() && canEdit())` 조건으로 배치한다. 뷰별 UI(modal 하단 바 / control 상단 바의 삭제 버튼)는 [확장 C](./extension-c-modal-view.md)/[확장 D](./extension-d-control-view.md)에서 추가로 처리한다.
-
-> **적용 조건: DB Table에 `isDeleted` 컬럼이 있는 경우에만.** `isDeleted` 컬럼이 없는 테이블은 물리 삭제(row DELETE)로 처리하며, 이 확장을 사용하지 않는다. → [공통 규칙: 삭제 방식은 DB 스키마에 따라 결정한다](../_common-rules.md#삭제-방식은-db-스키마에-따라-결정한다)
-
-**이 확장이 도입하는 요소:**
-
-- **imports:** `tablerEraser`, `tablerRestore`
-- **타입 확장:** `ICustomer.isDeleted: boolean` 필드 추가 + `data` 초기값·`_refresh` 빈 객체에 `isDeleted: false` 추가
-- **메서드:** `onDeleteButtonClick`, `onRestoreButtonClick`, `_toggleDelete(del: boolean)`
-- **템플릿:** 최소 뼈대 topbar 내부(`canEdit()` 저장 버튼과 새로고침 버튼 사이)에 `@if (!isNew() && canEdit())` 블록으로 삭제·복구 버튼 추가
-
-> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 선행 확장(A) 위에 번호 순서대로 삽입할 지점을 나타낸다. 그대로 컴파일되지 않는다.
-
-```typescript
-// 1) imports 추가
-import {
-  tablerAlertTriangle, tablerDeviceFloppy, tablerEraser, tablerRefresh, tablerRestore,
-} from "@ng-icons/tabler-icons";
-
-// 2) ICustomer 확장 — isDeleted 필드 추가
-interface ICustomer {
-  id: number | undefined;
-  name: string;
-  phone: string;
-  isDeleted: boolean;     // ← 추가
-  lastModifiedAt: DateTime | undefined;
-  lastModifiedBy: string | undefined;
-}
-
-// 3) data 초기값·_refresh 빈 객체에 isDeleted: false 추가
-protected readonly data = signal<ICustomer>({
-  id: undefined, name: "", phone: "",
-  isDeleted: false,       // ← 추가
-  lastModifiedAt: undefined, lastModifiedBy: undefined,
-});
-
-// 4) template — topbar에 삭제·복구 버튼 추가 (저장 버튼 뒤, 새로고침 버튼 앞)
-template: `
-  <sd-topbar>
-    <h4>{{ viewTitle() }}</h4>
-    @if (canEdit()) {
-      <sd-button [theme]="'link-primary'" (click)="onSaveButtonClick()"> <!-- 저장 (확장 A) --> </sd-button>
-    }
-    @if (!isNew() && canEdit()) {
-      @if (data().isDeleted) {
-        <sd-button [theme]="'link-warning'" (click)="onRestoreButtonClick()">
-          <ng-icon [svg]="tablerRestore" /> 복구
-        </sd-button>
-      } @else {
-        <sd-button [theme]="'link-danger'" (click)="onDeleteButtonClick()">
-          <ng-icon [svg]="tablerEraser" /> 삭제
-        </sd-button>
-      }
-    }
-    <sd-button [theme]="'link-info'" (click)="onRefreshButtonClick()"> <!-- 새로고침 --> </sd-button>
-  </sd-topbar>
-`
-
-// 5) 메서드 추가
-protected async onDeleteButtonClick(): Promise<void> {
-  await this._toggleDelete(true);
-}
-
-protected async onRestoreButtonClick(): Promise<void> {
-  await this._toggleDelete(false);
-}
-
-private async _toggleDelete(del: boolean): Promise<void> {
-  if (this.busyCount() > 0) return;
-  if (!this.perms().includes("edit")) return;
-  if (del && !confirm("삭제하시겠습니까?")) return;
-
-  this.busyCount.update((v) => v + 1);
-  await this._sdToast.try(async () => {
-    // 앱별 ORM delete/restore — 예:
-    //   await this._appOrm.connectAsync(async (db) => {
-    //     await db.customer.where(...).update({ isDeleted: del });
-    //   });
-
-    this._sdToast.success(`${del ? "삭제" : "복구"}되었습니다.`);
-    await this._refresh();
-  });
-  this.busyCount.update((v) => v - 1);
-}
-
-// 6) 아이콘 추가
-protected readonly tablerEraser = tablerEraser;
-protected readonly tablerRestore = tablerRestore;
-```
-
-**포인트:**
-
-- **DB Table에 `isDeleted` 컬럼이 있는 경우의 삭제는 `isDeleted: true` 플래그 업데이트 soft-delete**로 구현한다 — 복구 기능·감사 이력·참조 무결성을 유지하기 위함. 서버는 `isDeleted: true` 레코드를 조회에서 기본 제외하고, 상세 폼에서는 복구 버튼으로 토글할 수 있다. `isDeleted` 컬럼이 없는 테이블은 이 확장을 사용하지 않고 물리 삭제(row DELETE)로 처리한다.
-- **삭제 confirm은 `_toggleDelete`에서 `del === true`일 때만** 호출한다. 복구는 확인 없이 즉시 수행.
-- **`isNew()` 신규 상태에서는 삭제·복구 버튼 노출 안 함** — DB에 저장되지 않은 레코드는 삭제 대상이 없으므로 `@if (!isNew() && canEdit())`로 감싼다.
-- **모달/컨트롤 뷰의 삭제 버튼은 [확장 C](./extension-c-modal-view.md)/[확장 D](./extension-d-control-view.md)에서 별도 배치** — topbar가 없는 뷰에서는 이 확장만으로는 삭제 UI가 보이지 않는다. [확장 C](./extension-c-modal-view.md)(modal 하단 바) / [확장 D](./extension-d-control-view.md)(control 상단 바)에서 동일 `_toggleDelete` 메서드를 재사용하여 배치한다.
-
-## 🚫 흔한 실수 (Anti-patterns)
-
-> 공통 규칙(삭제 방식 선택 기준, `mark` 오용, `setupCanDeactivate` 호출 위치 등)은 [레시피 공통 규칙](../_common-rules.md)을 참조한다. 이 섹션은 **삭제/복구 확장 고유 실수**만 다룬다.
-
-### 물리 삭제 경로와 soft-delete 토글을 한 화면에 혼용한다
-
-```typescript
-// ❌ 같은 화면에서 두 경로를 병행 — 삭제 의미가 불명확해지고,
-//    서버 조회 필터(isDeleted: false)와 물리 DELETE가 충돌한다.
-protected async onHardDeleteButtonClick(): Promise<void> {
-  if (!confirm("영구 삭제하시겠습니까?")) return;
-  await this._appOrm.connectAsync(async (db) => {
-    await db.customer.where((it) => [expr.eq(it.id, this.data().id)]).delete();
-  });
-  // ...
-}
-private async _toggleDelete(del: boolean): Promise<void> {
-  // ... isDeleted: del 업데이트 (soft-delete)
-}
-
-// ✅ isDeleted 컬럼 유무로 단일 경로를 선택한다.
-//    컬럼이 있으면 `_toggleDelete`(soft-delete)만,
-//    컬럼이 없으면 이 확장 자체를 사용하지 않고 물리 삭제 단일 경로로 간다.
-private async _toggleDelete(del: boolean): Promise<void> {
-  if (this.busyCount() > 0) return;
-  if (!this.perms().includes("edit")) return;
-  if (del && !confirm("삭제하시겠습니까?")) return;
-
-  this.busyCount.update((v) => v + 1);
-  await this._sdToast.try(async () => {
-    // await db.customer.where(...).update({ isDeleted: del });
-    this._sdToast.success(`${del ? "삭제" : "복구"}되었습니다.`);
-    await this._refresh();
-  });
-  this.busyCount.update((v) => v - 1);
-}
-```
-
-**근거**: 동일 테이블에 soft-delete와 물리 DELETE 경로가 공존하면 삭제 이력·복구 가능 여부·참조 무결성이 불일치하게 된다. 서버 리스트 조회가 `isDeleted: false` 필터로 삭제 행을 숨기는 전제에서 물리 DELETE가 섞이면, "복구 불가 삭제"와 "복구 가능 삭제"가 같은 화면에서 구분 없이 발동된다. → [공통 규칙: 삭제 방식은 DB 스키마에 따라 결정한다](../_common-rules.md#삭제-방식은-db-스키마에-따라-결정한다)

package/docs/recipes/crud-detail/extension-c-modal-view.md

@@ -1,214 +0,0 @@
-← [CRUD 상세폼 레시피 진입점](../crud-detail.md)
-
-# 확장 C: modal 뷰
-
-> **선행:** [확장 A: 편집/저장](./extension-a-edit-save.md) + [확장 B: 삭제/복구 토글](./extension-b-delete-restore.md)
-
-확장 A(편집/저장) + 확장 B(삭제/복구)를 전제로, 동일 컴포넌트를 **modal 뷰**로도 재사용한다. `SdModalProvider.showAsync`로 띄우면 `viewType() === "modal"`로 자동 판정되며, 기존 `<sd-topbar>`를 `@if (viewType() === "page") { ... }`로 래핑하여 page 뷰 전용으로 돌리고, 모달에는 하단 액션 바(확인·취소·삭제·복구)와 우측 상단 새로고침 아이콘을 추가한다. 모달은 `implements SdModalContentDef<boolean | undefined>`로 계약을 부착하여 호출 측이 저장/닫기 결과를 받을 수 있다.
-
-**이 확장이 도입하는 요소:**
-
-- **imports:** `output`, `TemplateRef`, `injectViewTypeSignal`, `type SdModalContentDef`, `SdActivatedModalProvider`, `SdAnchor`, `SdDockContainer`, `SdDock`
-- **DI:** `_sdActivatedModal = inject(SdActivatedModalProvider, { optional: true })`
-- **계약:** `implements SdModalContentDef<boolean | undefined>`, `close = output<boolean | undefined>()`, `actionTplRef?: TemplateRef<any>` (필드 선언만 — `SdModal`이 setter 프록시로 감쌈)
-- **viewChild:** `_modalActionTpl = viewChild("modalActionTpl", { read: TemplateRef })`
-- **파생:** `viewType = injectViewTypeSignal()` (`viewTitle`은 이미 `injectViewTitleSignal()`로 modal/page 자동 분기됨)
-- **생성자 effect:** `effect(() => { this.actionTplRef = this._modalActionTpl(); })` (모달 헤더 우측 액션 슬롯 브릿지)
-- **setupCanDeactivate 조건 변경:** `() => this.viewType() === "modal" || this._checkIgnoreChanges()` — modal에서는 항상 true(이탈 허용)
-- **onSubmit / `_toggleDelete` 변경:** 성공 경로에 `this.close.emit(true)` 추가
-- **템플릿 교체 1:** 기존 `<sd-topbar>...</sd-topbar>`를 `@if (viewType() === "page") { <sd-topbar>...</sd-topbar> }`로 **래핑** (page 뷰 전용으로 돌림)
-- **템플릿:** topbar 내부 `<h4>{{ viewTitle() }}</h4>` 및 권한 경고의 viewTitle은 그대로 유지 (`injectViewTitleSignal()`이 modal/page 자동 분기)
-- **템플릿 추가:** `<sd-topbar-container>` 내부 main 래퍼(`<div class="flex-column fill">`)를 `<sd-dock-container>`로 감싸고, 그 내부에 `@if (viewType() === "modal" && canEdit())` 블록으로 `<sd-dock [position]="'bottom'">` 하단 액션 바(확인·취소·삭제·복구) 추가
-- **템플릿 추가:** `<sd-busy-container>` 바깥에 `<ng-template #modalActionTpl>`로 모달 우측 상단 새로고침 아이콘 정의
-
-> 상세: [`SdModalContentDef` 구현 패턴](../../provider-types/sd-modal-content-def.md#구현-패턴)
-
-> 상세: [`SdActivatedModalProvider` 사용법](../../providers/sd-activated-modal-provider.md#usage)
-
-> 상세: [`injectViewTypeSignal`](../../utils/inject-routing-signals.md#injectviewtypesignal)
-
-> 상세: [`<sd-dock> position="bottom"`](../../ui-layout/sd-dock.md)
-
-> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 선행 확장(A+B) 위에 번호 순서대로 삽입·교체할 지점을 나타낸다. 그대로 컴파일되지 않는다.
-
-```typescript
-// 1) imports 추가
-import {
-  ChangeDetectionStrategy, Component, computed, effect, inject, input, output, signal,
-  TemplateRef, untracked, viewChild, ViewEncapsulation,
-} from "@angular/core";
-import {
-  FormatPipe, injectPermsSignal,
-  injectViewTitleSignal, injectViewTypeSignal,
-  SdActivatedModalProvider, SdAnchor,
-  SdBusyContainer, SdButton, SdCommandDirective,
-  SdDock, SdDockContainer,
-  SdForm, type SdModalContentDef,
-  SdTextfield, SdToastProvider,
-  SdTopbar, SdTopbarContainer, setupCanDeactivate,
-} from "@simplysm/angular";
-
-// 2) @Component imports 배열에 SdAnchor / SdDockContainer / SdDock 추가
-
-// 3) DI 추가
-private readonly _sdActivatedModal = inject(SdActivatedModalProvider, { optional: true });
-
-// 4) 계약 부착 + viewChild + 파생 추가
-export class CustomerDetail implements SdModalContentDef<boolean | undefined> {
-  //== SdModalContentDef 요구 필드 ==
-  close = output<boolean | undefined>();
-  // actionTplRef는 SdModal이 setter 프록시로 감싸므로 필드 선언만으로 충분
-  actionTplRef?: TemplateRef<any>;
-
-  //== viewChild (modal 우측 상단 액션 브릿지) ==
-  private readonly _modalActionTpl = viewChild("modalActionTpl", { read: TemplateRef });
-
-  //== 파생 ==
-  protected readonly viewType = injectViewTypeSignal();
-  // viewTitle은 최소 뼈대에서 이미 injectViewTitleSignal()로 선언됨 — modal/page 자동 분기
-
-  // ... (이하 기존)
-}
-
-// 5) 생성자 — setupCanDeactivate 조건 변경 + actionTplRef effect 추가
-constructor() {
-  // 기존 초기 effect 동일...
-
-  // 변경: setupCanDeactivate 조건에 viewType() === "modal" || 추가
-  setupCanDeactivate(() => this.viewType() === "modal" || this._checkIgnoreChanges());
-
-  // 추가: 모달 헤더 우측 액션 슬롯 브릿지 (control/page 뷰에선 _modalActionTpl이 렌더되지 않아 undefined)
-  effect(() => {
-    this.actionTplRef = this._modalActionTpl();
-  });
-}
-
-// 6) onSubmit / _toggleDelete 성공 경로에 close.emit(true) 추가
-protected async onSubmit(): Promise<void> {
-  // ...
-  await this._sdToast.try(async () => {
-    // ... (ORM upsert)
-    this._sdToast.success("저장되었습니다.");
-    this.close.emit(true);     // ← 추가 — modal 호출 측이 결과를 받는다
-    await this._refresh();
-  });
-  // ...
-}
-
-private async _toggleDelete(del: boolean): Promise<void> {
-  // ...
-  await this._sdToast.try(async () => {
-    // ... (ORM delete/restore)
-    this._sdToast.success(`${del ? "삭제" : "복구"}되었습니다.`);
-    this.close.emit(true);     // ← 추가
-  });
-  // ...
-}
-
-// 7) template — 기존 <sd-topbar>를 @if (viewType() === "page")로 래핑,
-//    main 래퍼를 <sd-dock-container>로 감싸고
-//    modal 하단 바 + <ng-template #modalActionTpl> 추가
-template: `
-  <sd-busy-container [busy]="busyCount() > 0">
-    @if (initialized()) {
-      @if (!perms().includes("use")) {
-        <!-- '{{ viewTitle() }}'에 대한 사용권한이 없습니다. -->
-      } @else {
-        <sd-topbar-container>
-          @if (viewType() === "page") {
-            <sd-topbar>
-              <h4>{{ viewTitle() }}</h4>
-              <!-- 저장/삭제/복구/새로고침 (확장 A/B 동일) -->
-            </sd-topbar>
-          }
-
-          <sd-dock-container>
-            <!-- modal 하단 바: 확인/취소/삭제/복구 -->
-            @if (viewType() === "modal" && canEdit()) {
-              <sd-dock
-                [position]="'bottom'"
-                class="p-sm-default flex-row gap-sm bdt bdt-theme-gray-lightest"
-              >
-                @if (!isNew() && canEdit()) {
-                  @if (data().isDeleted) {
-                    <sd-button [size]="'sm'" [theme]="'warning'" (click)="onRestoreButtonClick()">
-                      복구
-                    </sd-button>
-                  } @else {
-                    <sd-button [size]="'sm'" [theme]="'danger'" (click)="onDeleteButtonClick()">
-                      삭제
-                    </sd-button>
-                  }
-                }
-                <div class="flex-fill flex-row gap-sm main-align-end">
-                  <sd-button [size]="'sm'" [theme]="'gray'" (click)="close.emit(undefined)">
-                    취소
-                  </sd-button>
-                  <sd-button [size]="'sm'" [theme]="'primary'" (click)="onSaveButtonClick()">
-                    확인
-                  </sd-button>
-                </div>
-              </sd-dock>
-            }
-
-            <!-- main: form + 최종수정 (확장 A/B 동일) -->
-            <div class="flex-column fill"> ... </div>
-          </sd-dock-container>
-        </sd-topbar-container>
-      }
-    }
-  </sd-busy-container>
-
-  <!-- 모달 뷰에서만 사용되는 우측 상단 액션 템플릿.
-       SdModalProvider가 contentComponent.actionTplRef를 setter 프록시로 감싸 SdModal로 브릿지한다.
-       (packages/angular/src/core/modal/sd-modal.provider.ts:140-150) -->
-  <ng-template #modalActionTpl>
-    <sd-anchor
-      [theme]="'gray'"
-      class="p-sm-default"
-      (click)="onRefreshButtonClick()"
-      title="새로고침(CTRL+ALT+L)"
-    >
-      <ng-icon [svg]="tablerRefresh" />
-    </sd-anchor>
-  </ng-template>
-`
-```
-
-**포인트:**
-
-- **modal 하단 바는 `[position]="'bottom'"` 반드시 명시**(`packages/angular/src/layout/dock/sd-dock.ts:97`). 기본값이 `"top"`이라 누락하면 상단에 쌓여 topbar 뒤에 겹친다.
-- **`actionTplRef` setter 프록시는 modal 뷰에서만 동작한다.** `SdModalProvider`는 모달 컨텐츠 컴포넌트 생성 시 `if ("actionTplRef" in contentRef.instance)`로 확인한 뒤 setter 프록시를 설치한다(`sd-modal.provider.ts:141`). page/control 뷰에서는 프록시가 설치되지 않으므로 `this.actionTplRef = ...` 할당이 인스턴스 필드에만 저장되고 부작용이 없다. `<ng-template #modalActionTpl>` 선언 자체는 뷰 타입과 무관하게 TemplateRef를 반환하지만, 소비할 `SdModal`이 없으므로 결과적으로 아무 일도 일어나지 않는다.
-- **`setupCanDeactivate`는 modal에서 true를 돌려 항상 이탈 허용**한다 — modal 자체에 취소 버튼이 있으므로 이중 confirm을 피한다. 페이지 뷰에서는 `_checkIgnoreChanges()`의 confirm 결과로 제어.
-- **modal 취소 버튼은 `close.emit(undefined)`**. 호출 측은 `undefined`를 "취소"로, `true`를 "저장/삭제 성공"으로 해석한다. boolean 대신 사용자 정의 결과 타입이 필요하면 `close = output<FooResult | undefined>()` + `implements SdModalContentDef<FooResult | undefined>`로 변경하고, 호출 측은 `const result = await sdModal.showAsync({ type: CustomerDetail, ... })`로 받는다.
-- **`viewTitle` 우선순위**: 모달 컴포넌트의 `title()` input이 세팅되어 있으면 그것을 우선, 없으면 라우트 기반 타이틀을 사용. `_sdSystemLog.writeAsync("warn", ...)`로 실패 시 로그 남김.
-- **[확장 D](./extension-d-control-view.md)(control 뷰)와 병행 가능** — 두 분기 블록(`@if (viewType() === "modal")` / `@if (viewType() === "control")`)이 상호 배타이므로 같은 `<sd-dock-container>` 내부에 나란히 둘 수 있다.
-
-## 🚫 흔한 실수 (Anti-patterns)
-
-> 공통 규칙(`mark` 오용, `setupCanDeactivate` / `injectViewTypeSignal()` 호출 위치, page 컴포넌트의 topbar 소유 등)은 [레시피 공통 규칙](../_common-rules.md)을 참조한다. 이 섹션은 **modal 뷰 확장 고유 실수**만 다룬다.
-
-### modal 하단 바의 `<sd-dock>`에 `[position]="'bottom'"`을 명시하지 않는다
-
-```typescript
-// ❌ [position] 생략 — 기본값이 "top"이라 하단 바가 <sd-dock-container>의 상단부터
-//    쌓여 topbar 뒤에 겹치거나, topbar가 숨겨진 modal 뷰에서도 의도한
-//    "모달 하단 고정"이 깨진다. 컴파일 에러·린트 경고 없이 silent failure.
-@if (viewType() === "modal" && canEdit()) {
-  <sd-dock class="p-sm-default flex-row gap-sm bdt bdt-theme-gray-lightest">
-    <!-- 확인/취소/삭제/복구 버튼 ... -->
-  </sd-dock>
-}
-
-// ✅ [position]="'bottom'"을 명시하여 <sd-dock-container> 하단에 고정
-@if (viewType() === "modal" && canEdit()) {
-  <sd-dock
-    [position]="'bottom'"
-    class="p-sm-default flex-row gap-sm bdt bdt-theme-gray-lightest"
-  >
-    <!-- 확인/취소/삭제/복구 버튼 ... -->
-  </sd-dock>
-}
-```
-
-**근거**: `SdDock.position`의 기본값이 `"top"`이다(`packages/angular/src/layout/dock/sd-dock.ts:97`). 하단 액션 바 용도로 `<sd-dock>`을 도입할 때 `[position]`을 생략하면 `<sd-dock-container>`가 상단부터 dock을 쌓기 때문에 topbar 영역 뒤에 깔리고, topbar가 없는 modal 뷰에서도 "모달 하단 고정"이 깨진다. 타입 시스템은 기본값으로 통과시키므로 컴파일러·린터가 경고하지 않는다.