@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/angular/recipes/data-select-button.md

@@ -0,0 +1,368 @@
+# Recipe: 모달 기반 선택 버튼
+
+모달을 띄워 항목을 선택하고, 결과를 `value`(key) ↔ `selectedItems`(표시용 객체) 양방향 바인딩으로 수신하는 버튼 컴포넌트를 조립한다. 표준 `<sd-modal-select-button>`을 직접 사용하거나, 도메인별 데이터 로딩을 감싼 wrapper 컴포넌트로 컴포지션한다.
+
+## When to use / When NOT to use
+
+| 상황 | 적용 패턴 |
+|------|-----------|
+| 1회성 모달을 직접 띄워 선택 (도메인별 wrapper 불필요) | 패턴 1: `<sd-modal-select-button>` 직접 |
+| 메모리 상주 공유 데이터(`SharedDataBase`)에서 선택 | 패턴 2: `<sd-shared-data-select-button>` |
+| key만 저장하고 표시용 데이터는 ORM 등에서 비동기 조회 | 패턴 3: 사용자 정의 wrapper |
+
+- ❌ 단순 enum 정적 옵션 — 대신 `<sd-select>` + `<sd-select-item>` 사용
+- ❌ 공유 데이터 드롭다운(검색 포함) — 대신 `<sd-shared-data-select>` 사용
+- ❌ 공유 데이터 목록형(페이지네이션) — 대신 `<sd-shared-data-select-list>` 사용
+
+## 전제조건
+
+- `provideSdAngular({ clientName })`이 앱 bootstrap에 등록되어 있다
+- 모달 컴포넌트가 `SdSelectModal<T>` 인터페이스를 구현한다 (`packages/angular/src/controls/button/sd-modal-select-button.ts:30`)
+- 표시용 객체(`selectedItems: T[]`)와 선택 key(`value`)는 분리하여 관리한다
+- 선택 결과는 `SelectModalOutputResult<T>` 형식으로 반환된다 (`packages/angular/src/core/select-modal-output-result.ts:4`)
+
+## 기본 레시피 (패턴 1: `<sd-modal-select-button>` 직접 사용)
+
+### 1. 모달 컴포넌트
+
+모달은 `SdSelectModal<T>`를 `implements`한다. `selectMode` / `selectedItemKeys` input과 `close` output을 모두 구현한다.
+
+```typescript
+import {
+  Component,
+  input,
+  output,
+  signal,
+  ViewEncapsulation,
+  type InputSignal,
+} from "@angular/core";
+import {
+  SdSelectModal,
+  type SelectModalOutputResult,
+} from "@simplysm/angular";
+
+interface IItem {
+  id: number;
+  name: string;
+}
+
+@Component({
+  selector: "app-item-select-modal",
+  standalone: true,
+  encapsulation: ViewEncapsulation.None,
+  template: `
+    <div class="p-default">
+      @for (item of _items(); track item.id) {
+        <div (click)="onItemClick(item)">{{ item.name }}</div>
+      }
+      <button (click)="onConfirm()">확인</button>
+      <button (click)="close.emit(undefined)">취소</button>
+    </div>
+  `,
+})
+export class ItemSelectModal implements SdSelectModal<IItem> {
+  initialized = signal(true);
+  close = output<SelectModalOutputResult<IItem> | undefined>();
+  selectMode: InputSignal<"single" | "multi" | undefined> = input<
+    "single" | "multi" | undefined
+  >("single");
+  selectedItemKeys: InputSignal<any[]> = input<any[]>([]);
+
+  protected readonly _items = signal<IItem[]>([]);
+  private readonly _picked = signal<IItem[]>([]);
+
+  onItemClick(item: IItem): void {
+    this._picked.update((prev) =>
+      this.selectMode() === "multi" ? [...prev, item] : [item],
+    );
+  }
+
+  onConfirm(): void {
+    const items = this._picked();
+    this.close.emit({
+      selectedItemKeys: items.map((it) => it.id),
+      selectedItems: items,
+    });
+  }
+}
+```
+
+**핵심**:
+- `close.emit(undefined)`는 취소(value 변경 없음), `close.emit({...})`는 확정 반환
+- `initialized = signal(true)`는 `SdModalContentDef` 계약 필드로, 모달 초기화 완료 신호
+
+### 2. 호출 측 컴포넌트
+
+```typescript
+import { Component, signal } from "@angular/core";
+import {
+  SdModalSelectButton,
+  type SdSelectModalInfo,
+} from "@simplysm/angular";
+import { ItemSelectModal } from "./item-select.modal";
+
+interface IItem {
+  id: number;
+  name: string;
+}
+
+@Component({
+  selector: "app-foo-view",
+  standalone: true,
+  imports: [SdModalSelectButton],
+  template: `
+    <sd-modal-select-button
+      [(value)]="value"
+      [(selectedItems)]="selectedItems"
+      [modal]="modalInfo"
+      [selectMode]="'single'"
+      [required]="true"
+    >
+      @if (selectedItems().length > 0) {
+        {{ selectedItems()[0].name }}
+      } @else {
+        선택하세요
+      }
+    </sd-modal-select-button>
+  `,
+})
+export class FooView {
+  value = signal<number | undefined>(undefined);
+  selectedItems = signal<IItem[]>([]);
+
+  modalInfo: SdSelectModalInfo<ItemSelectModal> = {
+    title: "항목 선택",
+    type: ItemSelectModal,
+    inputs: {},
+  };
+}
+```
+
+**핵심 동작**:
+- `value`는 key(number/string), `selectedItems`는 표시용 객체. 둘 다 `model<>`로 양방향 바인딩
+- 검색 버튼 클릭 시 내부적으로 `SdModalProvider.showAsync`를 호출해 모달을 연다. 모달이 반환한 `selectedItemKeys`가 `value`에, `selectedItems`가 `selectedItems`에 자동 반영된다 (`packages/angular/src/controls/button/sd-modal-select-button.ts:193`)
+- erase 버튼(초기화)은 `!disabled() && !required() && value 존재` 시 자동 표시된다 (`packages/angular/src/controls/button/sd-modal-select-button.ts:54`). `required=true`면 erase가 노출되지 않아 사용자가 값을 비울 수 없다
+- `required=true`인 상태에서 `value`가 비어 있으면 "선택된 항목이 없습니다." invalid 메시지가 붙는다 (`packages/angular/src/controls/button/sd-modal-select-button.ts:179`)
+
+## 변형 (Variation)
+
+### 패턴 2: `<sd-shared-data-select-button>` (메모리 상주 공유 데이터)
+
+메모리에 이미 로드된 `SharedDataBase` 기반 데이터에서 선택한다. `value`(key) 또는 `items` 변경 시 표시용 `_selectedItems`가 내부 effect에서 자동 재계산되므로 외부 로딩이 불필요하다 (`packages/angular/src/data/shared-data/sd-shared-data-select-button.ts:79`).
+
+```typescript
+import { Component, signal } from "@angular/core";
+import {
+  SdSharedDataSelectButton,
+  SdItemOfTemplate,
+  type SdSelectModalInfo,
+  type SharedDataBase,
+} from "@simplysm/angular";
+import { ShopSelectModal } from "./shop-select.modal";
+
+interface IShop extends SharedDataBase<number> {
+  __valueKey: number;      // SharedDataBase 필수 식별자
+  __searchText: string;    // 검색 매칭 대상
+  __isHidden: boolean;     // 숨김 여부
+  name: string;
+  code: string;
+}
+
+@Component({
+  selector: "app-bar-view",
+  standalone: true,
+  imports: [SdSharedDataSelectButton, SdItemOfTemplate],
+  template: `
+    <sd-shared-data-select-button
+      [(value)]="shopId"
+      [items]="shops()"
+      [modal]="shopModalInfo"
+      [selectMode]="'single'"
+    >
+      <ng-template [itemOf]="shops()" let-item>
+        <span>{{ item.code }} - {{ item.name }}</span>
+      </ng-template>
+    </sd-shared-data-select-button>
+  `,
+})
+export class BarView {
+  shopId = signal<number | undefined>(undefined);
+  shops = signal<IShop[]>([]); // SdSharedDataProvider에서 로드
+
+  shopModalInfo: SdSelectModalInfo<ShopSelectModal> = {
+    title: "거래처 선택",
+    type: ShopSelectModal,
+    inputs: {},
+  };
+}
+```
+
+**핵심**:
+- `items`가 source of truth. `selectedItems`는 외부로 노출되지 않고 내부 signal로 관리된다
+- `<ng-template [itemOf]="items()" let-item>` 컨텍스트 디렉티브로 항목 템플릿을 정의한다. multi 모드에서는 선택된 항목들이 `, ` 구분자로 자동 나열된다
+- `selectMode="multi"`이면 `value`는 `number[]`
+
+### 패턴 3: 사용자 정의 wrapper (도메인별 ORM 조회)
+
+도메인별로 자주 쓰는 모달 선택 버튼은 `<sd-modal-select-button>`을 컴포지션한 wrapper로 작성한다. `value`(key)만 외부에 노출하고, 표시용 데이터는 `effect`에서 비동기로 조회한다.
+
+```typescript
+import {
+  booleanAttribute,
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  effect,
+  inject,
+  input,
+  model,
+  signal,
+  ViewEncapsulation,
+} from "@angular/core";
+import {
+  SdModalSelectButton,
+  type SdSelectModalInfo,
+} from "@simplysm/angular";
+import { expr } from "@simplysm/orm-common";
+import { AppOrmProvider } from "../app-orm.provider";
+import { LotSelectModal } from "./lot-select.modal";
+
+interface ILot {
+  id: number;
+  code: string;
+}
+
+@Component({
+  selector: "app-lot-select-button",
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  standalone: true,
+  imports: [SdModalSelectButton],
+  template: `
+    <sd-modal-select-button
+      [(value)]="value"
+      [(selectedItems)]="_selectedItems"
+      [modal]="modalInfo()"
+      [disabled]="disabled()"
+      [required]="required()"
+      [inset]="inset()"
+      [size]="size()"
+      [selectMode]="'single'"
+    >
+      @for (item of _selectedItems(); track item.id; let index = $index) {
+        @if (index !== 0) { <span>,&nbsp;</span> }
+        <span>{{ item.code }}</span>
+      }
+    </sd-modal-select-button>
+  `,
+})
+export class LotSelectButton {
+  private readonly _appOrm = inject(AppOrmProvider);
+
+  value = model<number | undefined>();
+  modalInputs = input<SdSelectModalInfo<LotSelectModal>["inputs"]>({});
+  disabled = input(false, { transform: booleanAttribute });
+  required = input(false, { transform: booleanAttribute });
+  inset = input(false, { transform: booleanAttribute });
+  size = input<"sm" | "lg">();
+
+  protected readonly _selectedItems = signal<ILot[]>([]);
+
+  protected readonly modalInfo = computed<SdSelectModalInfo<LotSelectModal>>(() => ({
+    type: LotSelectModal,
+    title: "LOT 조회",
+    inputs: this.modalInputs(),
+  }));
+
+  constructor() {
+    effect(() => {
+      const v = this.value();
+      if (v == null) {
+        this._selectedItems.set([]);
+        return;
+      }
+
+      // effect 콜백은 동기여야 하므로 void IIFE로 비동기 격리
+      void (async () => {
+        const items = await this._appOrm.connectAsync(async (db) =>
+          db.lot()
+            .where((it) => [expr.in(it.id, [v])])
+            .select((it) => ({ id: it.id, code: it.code }))
+            .execute(),
+        );
+        this._selectedItems.set(items);
+      })();
+    });
+  }
+}
+```
+
+사용:
+
+```html
+<app-lot-select-button
+  [(value)]="data().lotId"
+  [required]="true"
+  [disabled]="!canEdit()"
+/>
+```
+
+**확장 지점**:
+- multi 모드 지원: `value = model<number[] | undefined>()`, `selectMode = input<"single" | "multi">("single")`, effect의 `expr.in(it.id, [v])`를 배열 전체(`expr.in(it.id, v)`)로 바꾸고 `v.length === 0` 분기를 추가한다
+- 모달 inputs 주입: 외부에서 `[modalInputs]="{ filter: ... }"` 형태로 전달하면 `computed` 합성을 통해 `modalInfo`에 반영된다
+
+**근거**: `effect` 콜백에 `async`를 선언하면 cleanup 시점이 반환 Promise 해소 시점과 어긋난다. 관련 규칙: [_common-rules.md — input 의존 로딩 규칙](./_common-rules.md#input-의존-데이터-로딩에-void-this_initasync를-사용하지-않는다).
+
+### 시트 셀 안에 삽입
+
+`[inset]="true" [size]="'sm'"` 규칙은 공통 규칙을 따른다 — [_common-rules.md — 시트 셀 내부 컨트롤 규칙](./_common-rules.md#시트-셀-내부-컨트롤에-insettrue-sizesm을-명시한다) 참조.
+
+```html
+<app-lot-select-button [inset]="true" [size]="'sm'" [(value)]="item.lotId" (valueChange)="mark(items)" />
+```
+
+## 🚫 흔한 실수 (Anti-patterns)
+
+### 1. `SdDataSelectButton` / `SdDataSelectButtonBase` 재도입
+
+```typescript
+// ✅ <sd-modal-select-button> 컴포지션 wrapper (패턴 3)
+@Component({
+  selector: "app-my-select-button",
+  imports: [SdModalSelectButton],
+  template: `<sd-modal-select-button [(value)]="value" [modal]="modalInfo()" ... />`,
+})
+export class MySelectButton { /* value = model<...>(), effect로 load */ }
+```
+
+**근거**: 공통 부모를 재도입하면 도메인별 분기가 상속 트리에 묶여 변경 전파가 불투명해진다. 컴포지션은 각 wrapper가 독립적으로 소멸·교체 가능하다.
+
+### 2. 조회 전용 모달에 `SdSelectModal<T>` 반사적 구현
+
+```typescript
+// ✅ 조회 전용은 SdModalContentDef만 구현, close는 undefined로 emit
+export class OrderHistoryModal implements SdModalContentDef<undefined> {
+  initialized = signal(true);
+  close = output<undefined>();
+}
+```
+
+**근거**: `SdSelectModal<T>`는 선택 결과 반환 계약(`SelectModalOutputResult<T>`)을 강제한다. 조회만 하는 모달에 붙이면 미사용 입력이 누적되어 의도가 흐려진다. 선택 모달 쪽 상세: [`./crud-list/extension-d-select-modal.md`](./crud-list/extension-d-select-modal.md).
+
+### 3. `<sd-shared-data-select-button>`에 `[(selectedItems)]` 외부 바인딩
+
+```html
+<!-- ✅ value + items만 바인딩. 외부 set이 필요하면 패턴 3 wrapper로 전환 -->
+<sd-shared-data-select-button
+  [(value)]="shopId"
+  [items]="allShops()"
+  [modal]="shopModalInfo"
+/>
+```
+
+**근거**: `SdSharedDataSelectButton._selectedItems`는 `protected readonly signal`로, `items` + `value`로부터 내부 effect가 자동 파생한다 (`packages/angular/src/data/shared-data/sd-shared-data-select-button.ts:79`). 외부에서 set하면 자동 파생 값과 즉시 덮어쓰기 경합이 발생한다.
+
+## 관련 Entry
+
+- [`crud-list/extension-d-select-modal.md`](./crud-list/extension-d-select-modal.md) — 차이: 본 레시피는 **호출 측** 조립을 다루고, 해당 확장은 **모달 쪽** `SdSelectModal<T>` 계약 구현(선택 누적, CRUD 리스트 공용 모달화)을 다룬다
+- [`_common-rules.md`](./_common-rules.md) — 시트 셀 `[inset]`/`[size]`, effect 내 비동기 처리, signal 필드 초기값 제약 등 횡단 규칙

package/claude/references/sd-simplysm-v14/angular/recipes/page-modal-container.md

@@ -0,0 +1,238 @@
+# 페이지/모달 컨테이너 직접 조립
+
+소비 화면이 `<sd-busy-container>` · `<sd-topbar-container>` · `<sd-topbar>` 표준 컴포넌트를 직접 조립해 하나의 컴포넌트를 page · modal · control 3뷰로 재사용한다. 추상 컨테이너(`<sd-base-container>` 류)가 감추던 분기·타이틀·권한·초기화 숨김을 화면 내부에 인라인으로 풀어 쓴다.
+
+## When to use / When NOT to use
+
+- ✅ 한 컴포넌트를 page · modal · control 중 둘 이상으로 재사용한다.
+- ✅ page 전용 / modal 전용 / control 전용 화면도 본 레시피에서 필요한 분기만 골라 쓴다 (불필요한 분기는 삭제).
+- ✅ `injectViewTypeSignal()`로 자동 판정된 뷰에 따라 topbar·하단 액션 바·본문 레이아웃을 선택한다.
+- ❌ 단일 화면 컨테이너 추상(`<sd-base-container>`, `useBaseContainer()` 등) 재도입 — 분기·타이틀·권한이 다시 감춰져 화면별 변경이 어려워진다.
+- ❌ 리스트 본문 조립이 필요할 때 — [`crud-list.md`](./crud-list.md) (시트·필터·페이징).
+- ❌ 상세 폼 본문 조립이 필요할 때 — [`crud-detail.md`](./crud-detail.md) (폼·저장 흐름).
+- ❌ modal 뷰의 (a) 다른 화면에서 항목을 골라 돌려주는 **선택 모달** — [`crud-list/extension-d-select-modal.md`](./crud-list/extension-d-select-modal.md).
+- ❌ modal 뷰의 (b) 부모 레코드 자식 목록·이력을 input으로 받아 보여주는 **조회 전용 modal** — [`crud-list/extension-e-readonly-modal.md`](./crud-list/extension-e-readonly-modal.md).
+
+## 전제조건
+
+- `provideSdAngular({ clientName })` 등록 (앱 부트스트랩) — `SdBusyProvider`·`SdAppStructureProvider` 등 의존 provider가 함께 등록된다.
+- page 뷰 사용 시: 라우트 등록 + `SdAppStructureProvider`에 페이지 코드·타이틀이 정의되어 있어야 `injectViewTitleSignal()`이 페이지 타이틀을 반환한다 (`packages/angular/src/core/routing/injectViewTitleSignal.ts:20`).
+- modal 뷰 사용 시: `SdModalProvider.showAsync(...)`로 진입한다. `SdActivatedModalProvider`가 모달 컨텍스트에 자동 주입된다 (`packages/angular/src/core/modal/sd-activated-modal.provider.ts:8`).
+- 공통 규칙: `injectViewTypeSignal()` 호출 시점, page 컴포넌트의 `<sd-topbar>` 소유 → [`_common-rules.md`](./_common-rules.md).
+
+## 기본 레시피
+
+3뷰를 모두 갖춘 최대 구성이다. 화면 요구에 따라 일부 분기·요소를 생략한다 (생략 기준은 [§ 변형](#변형) 참조).
+
+```typescript
+import { NgIcon } from "@ng-icons/core";
+import { tablerAlertTriangle } from "@ng-icons/tabler-icons";
+import {
+  booleanAttribute,
+  ChangeDetectionStrategy,
+  Component,
+  input,
+  ViewEncapsulation,
+} from "@angular/core";
+import {
+  injectViewTitleSignal,
+  injectViewTypeSignal,
+  SdBusyContainer,
+  SdTopbar,
+  SdTopbarContainer,
+} from "@simplysm/angular";
+
+@Component({
+  selector: "app-foo-view",
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  standalone: true,
+  imports: [SdBusyContainer, SdTopbarContainer, SdTopbar, NgIcon],
+  template: `
+    <sd-busy-container [busy]="busy()" [message]="busyMessage()">
+      <!-- initialized() == null(미사용) 또는 true 일 때만 본문 렌더 — 초기 로딩 잔상 방지 -->
+      @if (initialized() == null || initialized()) {
+        @if (restricted()) {
+          <div class="fill tx-theme-gray-light p-xxl tx-center">
+            <br />
+            <ng-icon [svg]="tablerAlertTriangle" [size]="'5em'" />
+            <br />
+            <br />
+            '{{ viewTitle() }}'에 대한 사용권한이 없습니다. 시스템 관리자에게 문의하세요.
+          </div>
+        } @else if (viewType() === "page") {
+          <sd-topbar-container>
+            <sd-topbar>
+              <h4>{{ viewTitle() }}</h4>
+              <!-- 페이지 topbar 보조 영역(버튼·메뉴) 필요 시 여기 -->
+            </sd-topbar>
+            <div class="fill">
+              <!-- 본문: 페이지 레이아웃으로 채우기 -->
+            </div>
+          </sd-topbar-container>
+        } @else if (viewType() === "modal") {
+          <!--
+            modal 용도는 사전에 (a) 선택 모달 / (b) 조회 전용 modal 중 하나로 확정한다.
+            (a) → ./crud-list/extension-d-select-modal.md
+            (b) → ./crud-list/extension-e-readonly-modal.md
+          -->
+          <div class="flex-column fill">
+            <div class="flex-fill">
+              <!-- 본문: 모달 내부 컨텐츠 -->
+            </div>
+            <!-- 모달 하단 액션(확인/취소) 필요 시:
+            <div class="bdt bdt-theme-gray-lightest">...</div>
+            -->
+          </div>
+        } @else {
+          <!-- 본문: control 뷰(다른 화면의 영역으로 삽입) -->
+        }
+      }
+    </sd-busy-container>
+  `,
+})
+export class FooView {
+  // injectViewTypeSignal/injectViewTitleSignal은 inject() 내부 호출이므로
+  // 필드 이니셜라이저(=생성자 시점)에서만 호출한다 → ./_common-rules.md
+  protected readonly viewType = injectViewTypeSignal();
+  protected readonly viewTitle = injectViewTitleSignal();
+
+  initialized = input<boolean | undefined>(undefined);
+  restricted = input(false, { transform: booleanAttribute });
+  busy = input(false, { transform: booleanAttribute });
+  busyMessage = input<string>();
+
+  protected readonly tablerAlertTriangle = tablerAlertTriangle;
+}
+```
+
+뷰 타입 자동 판정 규칙 (`packages/angular/src/core/routing/injectViewTypeSignal.ts:7`):
+
+1. `SdActivatedModalProvider`가 주입 가능하면 `"modal"`
+2. 활성 라우트의 컴포넌트 selector가 호스트 `tagName`과 일치하면 `"page"`
+3. 그 외는 `"control"`
+
+타이틀 자동 판정 규칙 (`packages/angular/src/core/routing/injectViewTitleSignal.ts:7`):
+
+1. 모달 컨텍스트면 `SdActivatedModalProvider.modalComponent()?.title()`
+2. 페이지 컨텍스트면 `SdAppStructureProvider.getTitleByFullCode(...)`
+3. 예외 시 빈 문자열 (별도 try/catch 불필요)
+
+## 변형
+
+### 분기·요소 포함 조건 (생략 가능 기준)
+
+기계적으로 모든 분기·요소를 포함하지 않는다. 화면 요구에 따라 아래 표대로 생략한다.
+
+| 요소 | 포함 조건 | 생략하는 경우 예시 |
+|------|----------|-------------------|
+| `viewType() === "page"` 분기 + `<sd-topbar>` | 라우트로 진입하는 페이지 뷰가 필요할 때 | 모달/control 전용 컴포넌트 |
+| `viewType() === "modal"` 분기 | 모달 뷰로도 재사용될 때 | page 전용 또는 control 전용 컴포넌트 |
+| `@else` (control) 분기 | 다른 화면의 영역으로 삽입될 때 | page/modal 전용 컴포넌트 |
+| `busy` / `busyMessage` input | 비동기 작업이 있어서 busy 표시가 필요할 때 | 동기적으로 렌더되는 화면 |
+| `initialized` input | 초기 로딩 완료 전 본문을 숨겨야 할 때 | 초기 로딩 없이 즉시 렌더 가능한 화면 |
+| `restricted` input + 권한 없음 메시지 | 권한 제어가 있는 화면 | 권한 제어가 없는 화면 |
+| `injectViewTitleSignal()` | topbar에 타이틀을 표시할 때 | 타이틀 불필요한 화면 |
+
+### page 전용 (modal·control 분기 생략)
+
+```typescript
+template: `
+  <sd-busy-container [busy]="busy()">
+    @if (initialized() == null || initialized()) {
+      <sd-topbar-container>
+        <sd-topbar><h4>{{ viewTitle() }}</h4></sd-topbar>
+        <div class="fill"><!-- 본문 --></div>
+      </sd-topbar-container>
+    }
+  </sd-busy-container>
+`,
+```
+
+### modal 전용 (page·control 분기 생략)
+
+```typescript
+template: `
+  <sd-busy-container [busy]="busy()">
+    <div class="flex-column fill">
+      <div class="flex-fill"><!-- 본문 --></div>
+    </div>
+  </sd-busy-container>
+`,
+```
+
+이 분기 안에서 (a) 선택 모달 또는 (b) 조회 전용 modal을 결정한다 — 아래 "🚫 흔한 실수" 섹션의 "modal = 선택 모달 단정 금지" 참조.
+
+### control 전용 (page·modal 분기 생략)
+
+```typescript
+template: `
+  <sd-busy-container [busy]="busy()">
+    <!-- 본문: 다른 화면의 영역으로 삽입 -->
+  </sd-busy-container>
+`,
+```
+
+control 뷰에는 `<sd-topbar-container>`·`<sd-topbar>`를 두지 않는다 (page 컴포넌트가 소유) — [`_common-rules.md` "page 컴포넌트가 <sd-topbar-container>와 <sd-topbar>를 소유한다"](./_common-rules.md#page-컴포넌트가-sd-topbar-container와-sd-topbar를-소유한다).
+
+### viewType 수동 오버라이드 (권장하지 않음)
+
+자동 판정으로 충분하지 않은 특수 상황(예: 특정 페이지 안에서 자기 자신을 모달처럼 보이게 함)에서만 사용한다. 추상화 복원을 부추기므로 기본은 자동 판정을 쓴다.
+
+```typescript
+import { computed, input } from "@angular/core";
+import { injectViewTypeSignal, type SdViewType } from "@simplysm/angular";
+
+override = input<SdViewType>();
+
+// injectViewTypeSignal()은 필드 이니셜라이저에서 한 번만 호출, 이후 computed에서 signal만 읽는다.
+private readonly _autoViewType = injectViewTypeSignal();
+protected readonly viewType = computed(() => this.override() ?? this._autoViewType());
+```
+
+## 🚫 흔한 실수
+
+### `<sd-base-container>` 재도입
+
+```typescript
+// ✅ 표준 조각을 화면이 직접 조립한다 (분기·타이틀·권한 가시화)
+template: `
+  <sd-busy-container [busy]="busy()">
+    @if (restricted()) { ... }
+    @else if (viewType() === "page") { <sd-topbar-container>... </sd-topbar-container> }
+    @else if (viewType() === "modal") { ... }
+    @else { ... }
+  </sd-busy-container>
+`,
+```
+
+**근거**: 추상 컨테이너는 page/modal/control 분기, 타이틀 계산, 권한 차단, 초기화 숨김을 한 번에 감추므로 화면별로 일부 동작만 바꾸기 어렵다. 표준 조각 직접 조립으로 분기를 인라인 노출한다.
+
+### `useBaseContainer()` 같은 공통 헬퍼 추출
+
+```typescript
+// ✅ 화면 코드에 인라인으로 둔다
+@Component({ template: ` <sd-busy-container [busy]="busy()"> ... </sd-busy-container> ` })
+```
+
+**근거**: 헬퍼 함수 형태로 분기·요소를 묶으면 본 레시피가 제거한 추상화가 다시 생긴다. "한 번만 쓰는 화면별 조립 코드"라는 형태가 의도적이다.
+
+### `viewType() === "modal"`만으로 선택 모달이라고 단정한다
+
+```typescript
+// ✅ modal 용도를 사전에 (a)/(b) 중 하나로 확정하고 그 레시피를 따른다
+// (a) 선택 모달: implements SdSelectModal<T> + 하단 액션 바 → ./crud-list/extension-d-select-modal.md
+// (b) 조회 전용 modal: 계약 없음, SdModal 기본 "X"로 닫음 → ./crud-list/extension-e-readonly-modal.md
+```
+
+**근거**: `viewType() === "modal"`은 "모달 컨텍스트에서 렌더 중"만 알려준다. 선택 모달 계약(`SdSelectModal<T>`)은 호출하는 쪽이 `selectMode`를 넘기고 결과를 받는 시나리오 한정이며, 조회 전용 modal과는 input·output·하단 액션 바 구성이 다르다.
+
+## 관련 Entry
+
+- [`_common-rules.md`](./_common-rules.md) — 차이: 4계열 진입점·확장에 걸친 횡단 규칙 (본 레시피의 `injectViewTypeSignal` 호출 시점·`<sd-topbar>` 소유 규칙 정의 위치).
+- [`crud-list.md`](./crud-list.md) — 차이: 리스트 본문(시트·필터·페이징) 조립.
+- [`crud-detail.md`](./crud-detail.md) — 차이: 상세 폼 본문(폼·저장 흐름) 조립.
+- [`crud-list/extension-d-select-modal.md`](./crud-list/extension-d-select-modal.md) — 차이: modal 뷰의 (a) 선택 모달 계약·하단 액션 바.
+- [`crud-list/extension-e-readonly-modal.md`](./crud-list/extension-e-readonly-modal.md) — 차이: modal 뷰의 (b) 조회 전용 패턴.
+- [`crud-detail/extension-c-modal-view.md`](./crud-detail/extension-c-modal-view.md) — 차이: 상세 폼의 modal 분기(canDeactivate·하단 액션 템플릿).
+- [`crud-detail/extension-d-control-view.md`](./crud-detail/extension-d-control-view.md) — 차이: 상세 폼의 control 분기(마스터-디테일 디테일 영역).