npm - @simplysm/sd-claude - Versions diffs - 14.0.53 → 14.0.55 - Mend

@simplysm/sd-claude 14.0.53 → 14.0.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (328) hide show

package/claude/references/sd-simplysm-v14/angular/styling/classes.md CHANGED Viewed

@@ -1,5 +1,7 @@
 # CSS Classes
+> **읽어야 하는 상황**: 레이아웃/유틸리티 클래스로 스타일링할 때. 커스텀 프로퍼티 오버라이드는 [variables.md](./variables.md), 테마 전환은 [themes.md](./themes.md) 참조.
 전역 유틸리티 CSS 클래스. `@layer base, theme-variant, utilities` 순서로 구성되며, 유틸리티 클래스는 `@layer utilities`에 정의된다.
 ## Layout

package/claude/references/sd-simplysm-v14/angular/styling/mixins.md CHANGED Viewed

@@ -1,5 +1,7 @@
 # Mixins / Functions
+> **읽어야 하는 상황**: SCSS에서 직접 mixin이나 function을 사용할 때.
 공개 SCSS mixin과 function. `scss/commons/_mixins.scss`에 정의된다.
 ## Mixins

package/claude/references/sd-simplysm-v14/angular/styling/themes.md CHANGED Viewed

@@ -1,5 +1,7 @@
 # Themes
+> **읽어야 하는 상황**: 다크 모드 등 테마를 전환하거나 커스텀 테마를 추가할 때.
 ## `.sd-theme-dark`
 다크 모드 테마 클래스. `<body>`에 `SdThemeProvider`가 자동으로 토글한다.

package/claude/references/sd-simplysm-v14/angular/styling/variables.md CHANGED Viewed

@@ -1,5 +1,7 @@
 # CSS Custom Properties
+> **읽어야 하는 상황**: 디자인 토큰(색상, 간격, 폰트 등)을 오버라이드할 때.
 `:root`에 선언되는 CSS 커스텀 프로퍼티. SCSS `$vars` 맵에서 `mixins.writeVars()`로 생성된다.
 ## Theme Colors

package/claude/references/sd-simplysm-v14/angular/type-utilities/directive-input-signals.md CHANGED Viewed

@@ -1,5 +1,7 @@
 # Type Utilities
+> **읽어야 하는 상황**: InputSignal에서 값 타입을 추출하거나, undefined 포함 프로퍼티를 optional로 변환하는 타입 유틸리티가 필요할 때.
 컴포넌트/디렉티브 입력 시그널 타입 추출 유틸리티 모음.
 ## `DirectiveInputSignals`

package/claude/references/sd-simplysm-v14/angular/ui-data/sd-base-container.md ADDED Viewed

@@ -0,0 +1,141 @@
+# `SdBaseContainer`
+> **읽어야 하는 상황**: CRUD 페이지/모달/컨트롤의 기본 컨테이너가 필요할 때 (busy 관리, 권한 검사, viewType별 레이아웃 분기).
+CRUD 페이지/모달/컨트롤의 기본 컨테이너. busy 상태 관리, 공유 데이터 초기화 대기, 접근 권한 검사, viewType별 레이아웃 분기를 제공한다.
+보통 직접 사용하기보다 `SdCrudList`나 `SdCrudDetail`이 내부에서 사용한다. 목록-상세 분할 레이아웃(master-detail)처럼 커스텀 레이아웃이 필요할 때 직접 사용한다.
+## Import
+```typescript
+import { SdBaseContainer } from "@simplysm/angular";
+```
+## Selector
+`sd-base-container`
+## Inputs
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `initialized` | `boolean` | `false` | 외부 초기화 완료 여부. `true`일 때만 내부 콘텐츠가 렌더링된다. 데이터 로딩이 끝난 뒤 `true`로 설정해야 한다. |
+| `restricted` | `boolean` | `false` | `true`이면 "사용권한이 없습니다" 메시지를 표시하고 콘텐츠를 렌더링하지 않는다. |
+| `viewType` | `SdViewType` | **required** | `"page"` \| `"modal"` \| `"control"`. 레이아웃 구조를 결정한다. |
+## Two-way Bindings (model)
+| Model | Type | Default | Description |
+|-------|------|---------|-------------|
+| `ready` | `boolean` | `false` | 공유 데이터(`SdSharedDataProvider.wait()`) 로딩 완료 시 컴포넌트 내부에서 `true`로 설정된다. 소비 컴포넌트는 이 값이 `true`가 된 후에 데이터 로딩을 시작해야 한다. |
+| `busyCount` | `number` | `0` | 로딩 카운터. 0보다 크면 `SdBusyContainer`의 busy overlay가 표시된다. 비동기 작업 시작 시 `+1`, 완료 시 `-1`한다. |
+## Content Children (ng-template)
+| Template Ref | 렌더링 위치 | Description |
+|---|---|---|
+| `#topbarTpl` | `viewType="page"`일 때 `<sd-topbar>` 내부 | 탑바 우측에 버튼(저장, 커스텀 명령 등)을 배치한다. `viewType`이 `"page"`가 아니면 무시된다. |
+| `#commandTpl` | 콘텐츠 영역 상단 | `p-default` 패딩, `flex-row gap-default` 레이아웃의 명령 영역. 하단에 `bdb bdb-theme-gray-lightest` 테두리가 그려진다. |
+| `#bottomCommandTpl` | 콘텐츠 영역 하단 | `p-sm-default` 패딩, `flex-row main-align-end gap-sm` 레이아웃의 명령 영역. 상단에 `bdt bdt-theme-gray-lightest` 테두리가 그려진다. 모달의 "확인" 버튼 등에 사용된다. |
+**`ng-content`**: 위 템플릿 외의 일반 콘텐츠는 `<ng-content>`로 투영되어 상단 명령 영역과 하단 명령 영역 사이의 `flex-fill` 영역에 렌더링된다.
+## 내부 레이아웃 구조
+```
+<sd-busy-container [busy]="initialized && busyCount > 0">
+  ┌─ restricted=true ─────────────────────────────────────┐
+  │  "'{viewTitle}'에 대한 사용권한이 없습니다" 메시지     │
+  └───────────────────────────────────────────────────────┘
+  ┌─ viewType="page" ─────────────────────────────────────┐
+  │  <sd-topbar-container>                                │
+  │    <sd-topbar>                                        │
+  │      <h4>{viewTitle}</h4>                             │
+  │      [#topbarTpl 렌더링]                              │
+  │    </sd-topbar>                                       │
+  │    [#content 렌더링]                                  │
+  │  </sd-topbar-container>                               │
+  └───────────────────────────────────────────────────────┘
+  ┌─ viewType="modal" | "control" ────────────────────────┐
+  │  [#content 렌더링]                                    │
+  └───────────────────────────────────────────────────────┘
+  ┌─ #content ────────────────────────────────────────────┐
+  │  <div class="flex-column fill">                       │
+  │    [#commandTpl 영역] (있을 때만)                      │
+  │    <div class="flex-fill">                            │
+  │      <ng-content /> ← 메인 콘텐츠                     │
+  │    </div>                                             │
+  │    [#bottomCommandTpl 영역] (있을 때만)                │
+  │  </div>                                               │
+  └───────────────────────────────────────────────────────┘
+</sd-busy-container>
+```
+## 초기화 순서 (lifecycle)
+1. 컴포넌트 생성 시 `effect` 등록
+2. `restricted=true`이면 → 즉시 `ready=true` (공유 데이터 로딩 불필요)
+3. `restricted=false`이면 → `busyCount+1` → `SdSharedDataProvider.wait()` → `busyCount-1` → `ready=true`
+4. 소비 컴포넌트의 `effect`에서 `ready()`가 `true`임을 감지 → 데이터 로딩 → `initialized=true`
+5. `initialized=true`가 되면 콘텐츠 렌더링 시작
+## 의존성
+- `SdSharedDataProvider` (abstract, 소비 프로젝트에서 구현체 provide 필요)
+- `SdToastProvider` (에러 래핑용)
+- `injectViewTitleSignal()` — 현재 뷰 타이틀을 가져와 탑바 `<h4>`와 권한 없음 메시지에 표시
+## Usage: master-detail 분할 레이아웃
+목록-상세 분할 뷰에서 `SdBaseContainer`를 직접 사용하는 패턴:
+```html
+<sd-base-container
+  [(ready)]="ready"
+  [initialized]="initialized()"
+  [(busyCount)]="busyCount"
+  [restricted]="!perms().includes('use')"
+  [viewType]="viewType()"
+>
+  <div class="flex-row fill">
+    <!-- 좌측: 목록 (control viewType) -->
+    <app-my-list
+      #headerSheet
+      selectMode="single"
+      class="flex-min bdr bdr-color-lighter"
+    />
+    <!-- 우측: 상세 (control viewType) -->
+    @let _selectedId = headerSheet.selectedKeys().first();
+    @if (_selectedId == null) {
+      <div class="flex-fill tx-theme-gray-default p-xxl" style="font-size: 48px">
+        <ng-icon [svg]="tablerArrowLeft" />
+        선택하세요.
+      </div>
+    } @else {
+      <app-my-detail
+        class="flex-fill"
+        [itemId]="_selectedId"
+        (submitted)="headerSheet.doRefresh()"
+      />
+    }
+  </div>
+</sd-base-container>
+```
+### 소비 컴포넌트 클래스 패턴
+```typescript
+@Component({ /* ... */ })
+export class MyView {
+  perms = injectPermsSignal(["my-module"], ["use"]);
+  viewType = injectViewTypeSignal();
+  ready = signal(false);
+  initialized = signal(true);   // 직접 데이터를 로딩하지 않으므로 즉시 true
+  busyCount = signal(0);
+}
+```

package/claude/references/sd-simplysm-v14/angular/ui-data/sd-crud-detail.md ADDED Viewed

@@ -0,0 +1,273 @@
+# `SdCrudDetail`
+> **읽어야 하는 상황**: CRUD 상세 화면(폼 + 저장)을 만들 때. 목록 화면은 [`SdCrudList`](./sd-crud-list.md) 참조.
+CRUD 상세 화면 스캐폴드. `SdBaseContainer`를 내부에 사용하며, 폼 제출(`Ctrl+S` 저장), readonly 모드, viewType별 저장 버튼 배치를 제공한다.
+## Import
+```typescript
+import { SdCrudDetail } from "@simplysm/angular";
+```
+## Selector
+`sd-crud-detail`
+## Inputs
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `initialized` | `boolean` | `false` | 외부 초기화 완료 여부. `true`일 때만 콘텐츠 렌더링. |
+| `restricted` | `boolean` | `false` | `true`이면 "사용권한이 없습니다" 메시지 표시 (SdBaseContainer에 전달). |
+| `readonly` | `boolean` | `false` | 읽기 전용 모드. `true`이면 저장 버튼이 숨겨지고 `<sd-form>` 대신 일반 `<div>`로 콘텐츠를 감싼다. |
+| `viewType` | `SdViewType` | **required** | `"page"` \| `"modal"` \| `"control"`. 저장 버튼 위치와 레이아웃을 결정한다. |
+## Two-way Bindings (model)
+| Model | Type | Default | Description |
+|-------|------|---------|-------------|
+| `ready` | `boolean` | `false` | SdBaseContainer의 공유 데이터 로딩 완료 시 `true`. |
+| `busyCount` | `number` | `0` | 로딩 카운터. SdBaseContainer에 전달. |
+## Outputs
+| Output | Type | Description |
+|--------|------|-------------|
+| `submit` | `void` | 폼 제출 시 발생. 저장 버튼 클릭, `Ctrl+S` 단축키, 또는 폼 내부 `Enter` 키 모두 이 이벤트를 트리거한다. |
+## Content Children (ng-template)
+### `#commandTpl` — 추가 명령 버튼 영역
+viewType에 따라 렌더링 위치가 달라진다:
+| viewType | 렌더링 위치 | 저장 버튼과의 관계 |
+|----------|------------|-------------------|
+| `page` | `<sd-topbar>` 내부 (저장 버튼 우측) | 저장 버튼 뒤에 이어서 렌더링 |
+| `control` | 상단 명령 영역 (저장 버튼 우측) | 저장 버튼 뒤에 이어서 렌더링 |
+| `modal` | 상단 명령 영역 | 저장 버튼은 하단에 별도 배치되므로 독립적 |
+```html
+<ng-template #commandTpl>
+  @if (canEdit()) {
+    <sd-button [theme]="'danger'" (click)="onDeleteButtonClick()">
+      <ng-icon [svg]="tablerEraser" />
+      삭제
+    </sd-button>
+  }
+  <sd-button [theme]="'link-info'" (click)="onSomeAction()">
+    <ng-icon [svg]="tablerSend" />
+    추가동작
+  </sd-button>
+</ng-template>
+```
+### `#bottomCommandTpl` — 하단 명령 버튼 영역
+하단 영역은 `viewType() === "modal" || bottomCommandTplRef()` 조건으로 표시된다. 즉, modal viewType이면 항상 표시되고, 다른 viewType에서는 사용자가 `#bottomCommandTpl`을 제공할 때만 표시된다. 하단 영역이 표시되면 "확인" 버튼이 **항상** 함께 추가된다 (viewType 무관). `#bottomCommandTpl`의 내용은 "확인" 버튼 **좌측**에 `flex-fill flex-row main-align-start gap-sm` 레이아웃으로 배치된다.
+```html
+<ng-template #bottomCommandTpl>
+  <sd-button [size]="'sm'" (click)="onSomeBottomAction()">
+    추가 하단 버튼
+  </sd-button>
+</ng-template>
+```
+## Host Directives
+- `SdCommandDirective` — `Ctrl+S` 키보드 단축키를 `sdSaveCommand` 이벤트로 변환. 이 이벤트가 발생하면 내부 `<sd-form>`의 `requestSubmit()`을 호출하여 폼 유효성 검사 후 `submit` 이벤트를 발생시킨다.
+## viewType별 저장 버튼 배치 상세
+### `viewType="page"`
+```
+┌─ sd-topbar ─────────────────────────────────────────┐
+│  <h4>{viewTitle}</h4>                               │
+│  [저장 버튼: link-primary] [#commandTpl 내용]       │
+└─────────────────────────────────────────────────────┘
+┌─ 콘텐츠 ────────────────────────────────────────────┐
+│  <sd-form>                                          │
+│    <ng-content /> ← 폼 필드들                       │
+│  </sd-form>                                         │
+└─────────────────────────────────────────────────────┘
+```
+- 저장 버튼: `<sd-button [theme]="'link-primary'">` + floppy 아이콘 + "저장 (CTRL+S)"
+- `readonly=true`이면 저장 버튼 숨김, `<sd-form>` 대신 `<div class="fill">`
+### `viewType="control"`
+```
+┌─ 상단 명령 영역 ────────────────────────────────────┐
+│  [저장 버튼: primary] [#commandTpl 내용]            │
+└─────────────────────────────────────────────────────┘
+┌─ 콘텐츠 ────────────────────────────────────────────┐
+│  <sd-form>                                          │
+│    <ng-content /> ← 폼 필드들                       │
+│  </sd-form>                                         │
+└─────────────────────────────────────────────────────┘
+┌─ 하단 명령 영역 (bottomCommandTpl이 있을 때만) ─────┐
+│  [#bottomCommandTpl 내용 (좌측)]   [확인 버튼 (우측)]│
+└─────────────────────────────────────────────────────┘
+```
+- 저장 버튼: `<sd-button [theme]="'primary'">` + floppy 아이콘 + "저장 (CTRL+S)"
+- bottomCommandTpl을 제공하면 하단에 확인 버튼도 함께 표시됨 (저장 버튼과 동일 동작: `formCtrl.requestSubmit()`)
+### `viewType="modal"`
+```
+┌─ 상단 명령 영역 (commandTpl이 있을 때만) ───────────┐
+│  [#commandTpl 내용]                                 │
+└─────────────────────────────────────────────────────┘
+┌─ 콘텐츠 ────────────────────────────────────────────┐
+│  <sd-form>                                          │
+│    <ng-content /> ← 폼 필드들                       │
+│  </sd-form>                                         │
+└─────────────────────────────────────────────────────┘
+┌─ 하단 명령 영역 (항상 표시) ────────────────────────┐
+│  [#bottomCommandTpl 내용 (좌측)]   [확인 버튼 (우측)]│
+└─────────────────────────────────────────────────────┘
+```
+- 확인 버튼: `<sd-button [size]="'sm'" [theme]="'primary'">확인</sd-button>` (클릭 시 `formCtrl.requestSubmit()` → `submit` 이벤트)
+- `readonly=true`여도 확인 버튼은 항상 표시됨 (modal viewType 조건으로 하단 영역이 렌더링되므로)
+## readonly 모드 상세
+`readonly=true`일 때:
+- 모든 viewType에서 저장 버튼이 숨겨진다
+- `<sd-form>` 대신 `<div class="fill">`로 콘텐츠를 감싼다 (폼 유효성 검사 비활성)
+- `Ctrl+S` 단축키는 여전히 동작하지만 `formCtrl`이 없으므로 아무 효과 없음
+- `#commandTpl`이 있으면 해당 영역은 여전히 표시된다 (삭제 버튼 등 readonly에서도 필요한 명령)
+## Usage: control viewType (master-detail 패턴)
+```typescript
+@Component({
+  template: `
+    <sd-crud-detail
+      [viewType]="'control'"
+      [initialized]="initialized()"
+      [(busyCount)]="busyCount"
+      [readonly]="!canEdit()"
+      (submit)="onSubmit()"
+    >
+      <ng-template #commandTpl>
+        @if (canEdit()) {
+          <sd-button [theme]="'danger'" (click)="onDeleteButtonClick()">
+            <ng-icon [svg]="tablerEraser" />
+            삭제
+          </sd-button>
+        }
+        <sd-button [theme]="'link-info'" (click)="onSpecialAction()">
+          <ng-icon [svg]="tablerSend" />
+          특별동작
+        </sd-button>
+      </ng-template>
+      <div class="fill p-default">
+        <sd-dock-container>
+          <sd-dock class="pb-sm">
+            <div class="form-box-inline p-sm-default bd-radius-default bd bd-trans-light fill">
+              <div>
+                <label>문서번호</label>
+                <div>{{ data().code }}</div>
+              </div>
+              <div>
+                <label>날짜</label>
+                <sd-textfield
+                  [type]="'date'"
+                  [disabled]="!canEdit()"
+                  [(value)]="data().dueDate"
+                  (valueChange)="mark(data)"
+                />
+              </div>
+            </div>
+          </sd-dock>
+          <!-- 탭이나 서브 리스트 등 -->
+          <div class="fill">
+            <app-sub-list [(items)]="data().items" (itemsChange)="mark(data)" />
+          </div>
+        </sd-dock-container>
+      </div>
+    </sd-crud-detail>
+  `,
+})
+export class MyDetail {
+  instructionId = input.required<number>();
+  submitted = output<boolean>();
+  initialized = signal(false);
+  busyCount = signal(0);
+  data = signal<IData>({ code: "", items: [] });
+  private _orgData: IData | undefined;
+  canEdit = computed(() => this.perms().includes("edit") && this.data().state === "작성");
+  constructor() {
+    effect(() => {
+      this.instructionId(); // 변경 감지 트리거
+      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);
+      });
+    });
+    setupCanDeactivate(() => this._checkIgnoreChanges());
+  }
+  async onSubmit(): Promise<void> {
+    if (this.busyCount() > 0) return;
+    // ... 저장 로직
+    await this._refresh();
+    this.submitted.emit(true);
+  }
+}
+```
+## Usage: modal viewType
+```html
+<sd-crud-detail
+  [(ready)]="ready"
+  [initialized]="initialized()"
+  [(busyCount)]="busyCount"
+  [viewType]="'modal'"
+  (submit)="onSubmit()"
+>
+  <div class="p-default">
+    <div class="form-box-inline">
+      <div>
+        <label>이름</label>
+        <sd-textfield [(value)]="data().name" [required]="true" />
+      </div>
+    </div>
+  </div>
+</sd-crud-detail>
+```
+## Anti-patterns
+```html
+<!-- ❌ readonly일 때 commandTpl 안에 저장 버튼을 별도로 넣지 않는다 -->
+<!-- SdCrudDetail이 viewType에 맞는 저장 버튼을 자동 배치한다 -->
+<ng-template #commandTpl>
+  <sd-button (click)="onSave()">저장</sd-button>  <!-- ❌ -->
+</ng-template>
+<!-- ✅ commandTpl에는 저장 외의 추가 명령만 넣는다 -->
+<ng-template #commandTpl>
+  <sd-button [theme]="'danger'" (click)="onDelete()">삭제</sd-button>  <!-- ✅ -->
+</ng-template>
+```