@simplysm/sd-claude 14.0.76 → 14.0.77

package/claude/references/sd-simplysm14/apis/angular/shared-data.md

@@ -1,42 +1,134 @@
 # @simplysm/angular — shared-data
 
-서버에서 가져오는 코드성 데이터(부서, 거래처 등)를 키 기반으로 등록/구독, 변경 이벤트로 자동 부분 갱신.
+서버 마스터데이터(부서·거래처·코드 등)를 키 기반으로 등록/구독. 서버 변경 이벤트로 자동 부분 갱신.
 
-## `SdSharedDataProvider<T>` (abstract)
+## SdSharedDataProvider<T> (abstract, 사용자가 상속해 `initialize()` 안에서 `register` 호출)
 
-```typescript
+```ts
+abstract class SdSharedDataProvider<T extends Record<string, SharedDataBase<string|number>>> {
+  loadingCount: WritableSignal<number>;
+  abstract initialize(): void;
+  register<K extends keyof T & string>(name: K, info: SharedDataInfo<T[K]>): void;
+  getHandle<K extends keyof T & string>(name: K): SharedDataHandle<T[K]>;
+  emitAsync<K extends keyof T & string>(name: K, changeKeys?: (string|number)[]): Promise<void>;
+  wait(): Promise<void>;     // loadingCount 가 0 될 때까지
+}
+
+interface SharedDataBase<TKey> {
+  __valueKey: TKey;
+  __searchText: string;
+  __isHidden: boolean;
+  __parentKey?: TKey;
+}
+interface SharedDataInfo<T> {
+  serviceKey: string;                                    // SdServiceClientFactoryProvider 의 client key
+  getter: (changeKeys?: (string|number)[]) => Promise<T[]>;
+  filter?: unknown;
+  orderBy?: (item: T) => any;
+}
+interface SharedDataHandle<T> {
+  items: Signal<T[]>;
+  get(key: T["__valueKey"]|undefined): T|undefined;
+}
+
+const SdSharedDataChangeEvent = defineEvent<{ name: string; filter: unknown }, (string|number)[]|undefined>("SdSharedDataChange");
+```
+
+- `register` — 데이터 소스 등록. `getHandle` 첫 호출 시 `getter()` lazy 로드 + 서버 이벤트 리스너 등록. 이후 `SdSharedDataChangeEvent` 수신 시 `changeKeys` 기준 부분 갱신(또는 undefined 면 전체 reload).
+- `getHandle.items` — readonly signal. orderBy 적용된 정렬 상태.
+- `getHandle.get(key)` — `__valueKey` 로 O(1) 조회.
+- `emitAsync` — 클라이언트에서 변경 발생 시 같은 `serviceKey` 의 다른 클라이언트에 변경 통지(filter 동일한 등록만 수신).
+- `wait` — 초기 로드/갱신이 완료될 때까지. CRUD 컨테이너의 ready 처리에 사용.
+- `SharedDataBase` 의 `__searchText` — `matchesSearchText` 가 사용할 검색 대상 문자열. `__isHidden` — 보이지 않을 항목 마킹. `__parentKey` — 트리형 데이터의 부모 키.
+- `filter` — 서버 측 필터 식별자. 다른 filter 로 등록된 같은 name 은 별개 인스턴스.
+
+```ts
 @Injectable({ providedIn: "root" })
-class MySharedData extends SdSharedDataProvider<{ depts: DeptDto; vendors: VendorDto }> {
-  initialize(): void {
+class MySharedData extends SdSharedDataProvider<{ depts: Dept }> {
+  initialize() {
     this.register("depts", {
       serviceKey: "main",
-      getter: (changeKeys) => svc.depts.getList(changeKeys),
-      orderBy: (it) => it.name,
+      getter: async (keys) => await api.depts.list(keys),
+      orderBy: (d) => d.name,
     });
   }
 }
+const depts = mySharedData.getHandle("depts").items();
 ```
 
-- 각 아이템 타입은 `SharedDataBase<TKey>` 확장: `{ __valueKey: TKey, __searchText: string, __isHidden: boolean, __parentKey? }`.
-- `register(name, info)` 후 `getHandle(name)` → `SharedDataHandle<T> { items: Signal<T[]>; get(key) }`. 첫 호출 시 lazy load + 이벤트 리스너 등록.
-- `emitAsync(name, changeKeys?)` → 다른 클라이언트(또는 자기 자신)에 `SdSharedDataChangeEvent` 발행. `changeKeys` 없으면 전체 리로드, 있으면 해당 키들만 재조회 후 merge (orderBy 재적용).
-- `loadingCount = signal(0)`, `wait()` (loadingCount 0까지).
-- `SdSharedDataChangeEvent` = `defineEvent<{ name; filter }, (string|number)[] | undefined>("SdSharedDataChange")` — 동일 name+filter 매칭 리스너에 키 발행.
+## SdSharedDataSelect — `<sd-shared-data-select>`
 
-## `<sd-shared-data-select<TItem, TMode, TModal>>`
+```ts
+class SdSharedDataSelect<TMode, TModal, TItem extends SharedDataBase<...>>
+value = model<SelectModeValue<TItem["__valueKey"]|undefined>[TMode]>();
+items = input.required<TItem[]>();
+disabled/required/useUndefined/inset/inline = input(false); size = input<"sm"|"lg">();
+selectMode = input("single" as TMode);
+filterFn = input<(item, index, ...params) => boolean>();
+filterFnParams = input<any[]>();
+modal = input<SdSelectModalInfo<TModal>>();
+editModal = input<SdModalInfo<SdModalContentDef<boolean>>>();
+selectClass = input<string>();
+multiSelectionDisplayDirection = input<"vertical">();
+getIsHiddenFn = input<(item, index) => boolean>(...);    // 기본 (i)=>i.__isHidden
+getSearchTextFn = input<(item, index) => string>(...);   // 기본 (i)=>i.__searchText
+displayOrderKeyProp = input<string>();
+```
 
-`SharedDataBase` 항목에서 키를 선택하는 셀렉트. `__isHidden`/`__searchText` 활용.
+- 공유데이터 전용 셀렉트. `items` 는 보통 `sharedData.getHandle("xx").items()`.
+- `useUndefined` — true 면 "선택 안 함" 옵션 노출. 단일 모드에서 null 가능.
+- `filterFn` + `filterFnParams` — 추가 필터(signal 변경 시 재계산).
+- `modal` — "더보기" 검색 모달. 미지정 시 모달 버튼 안 보임.
+- `editModal` — 항목 편집 모달(연필 아이콘). true emit 시 데이터 reload.
+- `getIsHiddenFn`/`getSearchTextFn` — 기본은 `SharedDataBase` 의 `__isHidden`/`__searchText` 사용. 커스텀 가능.
+- `displayOrderKeyProp` — 트리 표시 시 정렬에 쓸 prop 이름.
 
-inputs: `items` (required), `value` (model: 단일/배열 키), `selectMode`, `disabled`, `required`, `useUndefined`, `inset`, `inline`, `size`, `filterFn(item, index, ...params)`, `filterFnParams`, `modal: SdSelectModalInfo<TModal>` (검색 모달), `editModal: SdModalInfo<SdModalContentDef<boolean>>` (신규 등록), `selectClass`, `multiSelectionDisplayDirection: "vertical"`, `getIsHiddenFn` (default `__isHidden`), `getSearchTextFn` (default `__searchText`), `displayOrderKeyProp`.
+## SdSharedDataSelectButton — `<sd-shared-data-select-button>`
 
-## `<sd-shared-data-select-button>`
+```ts
+value = model<SelectModeValue<string|number>[TMode]>();
+items = input<TItem[]>([]);
+modal = input.required<SdSelectModalInfo<TModal>>();
+selectMode = input<TMode>("single" as TMode);
+disabled/required/inset = input(false); size = input<"sm"|"lg">();
+```
+
+- 셀렉트 드롭다운 대신 항상 모달로 검색. `<ng-content>` 가 선택값 표시 슬롯. `modal` 필수.
+
+## SdSharedDataSelectList — `<sd-shared-data-select-list>`
+
+```ts
+class SdSharedDataSelectList<TItem extends SharedDataBase<...>, TModal>
+selectedItem = model<TItem>();
+canChangeFn = input<(item: TItem|undefined) => boolean|Promise<boolean>>(...);
+items = input.required<TItem[]>();
+selectedIcon = input<string>();
+useUndefined = input(false);
+filterFn = input<(item, index) => boolean>();
+modal = input<SdSelectModalInfo<TModal>>();
+header = input<string>();
+pageItemCount = input<number>();
+```
 
-modal 강제(검색 모달 필수). value: 단일/배열 키.
+- 사이드 패널형 리스트(단일 선택). 검색 박스 + 페이지네이션 자동.
+- `canChangeFn` — 변경 직전 비동기 확인.
+- `pageItemCount` — 페이지당 항목 수. 미지정 시 페이지 분할 없음.
 
-## `<sd-shared-data-select-list>`
+## matchesSearchText
 
-list 형태 단일 선택. inputs: `items` (req), `selectedItem` (model), `canChangeFn(item) => boolean | Promise<boolean>`, `selectedIcon`, `useUndefined`, `filterFn`, `modal`, `header`, `pageItemCount`.
+```ts
+function matchesSearchText(itemText: string, searchQuery: string|undefined): boolean
+```
+
+- 공백 분리 AND 검색. 모든 단어가 `itemText` (대소문자 무시) 안에 포함되면 true. 빈 query 는 true.
+- 커스텀 선택 리스트에서 검색 필터 짤 때 사용.
+
+```ts
+items.filter((it) => matchesSearchText(it.name + " " + it.code, q()))
+```
 
-## `matchesSearchText(itemText, searchQuery)`
+## 주의
 
-공백 분리 AND 매칭(lowercase). 빈 쿼리는 true.
+- `SdSharedDataProvider` 상속 후 `initialize()` 안에서만 `register`. 부트스트랩 시 1회 호출.
+- 같은 name 으로 다시 `register` 호출 시 generation 증가 + listener 교체 → 이전 비동기 결과는 무시.
+- 변경 이벤트는 같은 `serviceKey` 의 같은 `name`·동일 `filter` 등록만 수신.

package/claude/references/sd-simplysm14/apis/angular/sheet.md

@@ -1,52 +1,127 @@
 # @simplysm/angular — sheet
 
-가상 스크롤 데이터 그리드. 컬럼·셀 템플릿·정렬·페이징·선택·확장 트리·설정 모달 내장.
+데이터 그리드. 컬럼·셀 템플릿·정렬·페이징·선택·확장 트리·컬럼 설정 모달 내장.
 
-## 기본 사용
+## SdSheet — `<sd-sheet>`
+
+```ts
+class SdSheet<TItem>
+key = input<string>();
+items = input<TItem[]>([]);
+trackByFn = input<(item: TItem, index: number) => unknown>((i) => i);
+selectMode = input<"single"|"multi">();
+autoSelect = input<"click"|"focus">();
+getItemSelectableFn = input<(item) => boolean|string>();
+getChildrenFn = input<(item, index) => TItem[]|undefined>();
+useAutoSort = input(false);
+visiblePageCount = input(10);
+totalPageCount = input(0);
+itemsPerPage = input(0);
+focusMode = input<"row"|"cell">("cell");
+inset = input(false);
+contentStyle = input<string>();
+getItemCellClassFn = input<(item, colKey: string) => string>();
+getItemCellStyleFn = input<(item, colKey: string) => string|undefined>();
+hideConfigBar = input(false);
+
+itemKeydown = output<SdSheetItemKeydownEventParam<TItem>>();
+cellKeydown = output<SdSheetCellKeydownEventParam<TItem>>();
+
+selectedKeys = model<unknown[]>([]);
+expandedItems = model<TItem[]>([]);
+sorts = model<SortingDef[]>([]);
+currentPage = model(0);
+
+columnControlsInput = input<readonly SdSheetColumn[]>([]);  // 동적 컬럼 주입용
+```
+
+- `key` — 지정 시 `SdSystemConfigProvider` 키 `sd-sheet.<key>` 로 컬럼 width/hidden/fixed/ordering 자동 저장·복원. 미지정이면 세션 한정.
+- `items` + `trackByFn` — 데이터와 키 추출. 트리는 `getChildrenFn` 으로 자식 반환(`expandedItems` 양방향 model 로 펼침 상태).
+- `selectMode` — `single`/`multi`. 미지정이면 선택 안 함. `selectedKeys` 는 `trackByFn` 반환값 배열.
+- `autoSelect` — `click`: 행 클릭 시 선택, `focus`: 포커스만 들어가도 선택. 미지정이면 명시적 체크박스만.
+- `getItemSelectableFn` — true 면 선택 가능, false/string 이면 불가(string 은 사유 툴팁).
+- `useAutoSort` — true 면 `sorts` 변경 시 클라이언트 자체 정렬. false 면 서버 사이드 페치 가정.
+- `totalPageCount`/`itemsPerPage`/`visiblePageCount`/`currentPage` — 페이지네이션. `totalPageCount=0` 이면 페이지바 숨김.
+- `focusMode` — `row` 면 행 단위 포커스, `cell` 면 셀 단위(엑셀형).
+- `inset` — 컨테이너 안에 박힌 룩(보더 제거).
+- `getItemCellClassFn`/`getItemCellStyleFn` — 셀별 동적 class/style.
+- `hideConfigBar` — 상단 컬럼 설정 바(컬럼 표시/순서 조작) 숨김.
+- `itemKeydown`/`cellKeydown` — 단축키 처리. focusMode 에 따라 둘 중 1개 활용.
+- 자식: `<sd-sheet-column>` 들을 content projection 으로 배치.
 
 ```html
-<sd-sheet
-  [key]="'order-list'"
-  [items]="items"
-  [trackByFn]="byId"
-  [selectMode]="'multi'"
-  [(selectedKeys)]="selectedKeys"
-  [(sorts)]="sorts"
-  [(currentPage)]="page"
-  [totalPageCount]="totalPages"
-  [itemsPerPage]="50"
-  [useAutoSort]="false">
-
-  <sd-sheet-column [key]="'no'" [header]="'번호'" [width]="'80px'" [fixed]="true">
-    <ng-template cell let-item="item" let-index="index">{{ index + 1 }}</ng-template>
+<sd-sheet [items]="rows()" [trackByFn]="trackById" [(selectedKeys)]="sel" selectMode="multi" key="invoice-list">
+  <sd-sheet-column key="no" header="번호" width="80px" />
+  <sd-sheet-column key="name" header="이름">
+    <ng-template cell [cell]="rows()" let-item>{{ item.name }}</ng-template>
   </sd-sheet-column>
 </sd-sheet>
 ```
 
-## `<sd-sheet<TItem>>` 입력/출력
+## SdSheetColumn — `<sd-sheet-column>` (Directive)
 
-- inputs: `key`, `items`, `trackByFn`, `selectMode`, `autoSelect: "click"|"focus"`, `getItemSelectableFn`, `getChildrenFn` (트리), `useAutoSort`, `visiblePageCount=10`, `totalPageCount`, `itemsPerPage`, `focusMode: "row"|"cell" = "cell"`, `inset`, `contentStyle`, `getItemCellClassFn`, `getItemCellStyleFn`, `hideConfigBar`, `columnControlsInput: readonly SdSheetColumn[]` (외부 정의된 컬럼 추가, `<sd-sheet-column>` 자식 + 이 입력을 합쳐 처리).
-- outputs: `itemKeydown: SdSheetItemKeydownEventParam<T> { item, event }`, `cellKeydown: SdSheetCellKeydownEventParam<T> { item, key, event }`.
-- models: `selectedKeys: unknown[]`, `expandedItems: TItem[]`, `sorts: SortingDef[]`, `currentPage: number`.
-- `key` 지정 시 설정 모달(`SdSheetConfigModal`)로 너비/숨김/고정/순서를 `SdSystemConfigProvider`에 영속화.
+```ts
+class SdSheetColumn<T = unknown>
+key = input.required<string>();
+header = input<string|string[]>("");        // 배열이면 다단 헤더
+headerStyle = input<string>();
+tooltip = input<string>();
+width = input<string>();                     // CSS 값 ("120px"·"1fr")
+fixed = input(false);                        // 좌측 고정 컬럼
+hidden = input(false);
+collapse = input(false);                     // 접힘(헤더만 좁게)
+disableSorting = input(false);
+disableResizing = input(false);
+ordering = input(0);                         // 표시 순서 weight
 
-## `<sd-sheet-column<T> [key] [header]>`
+interface SdSheetCellContext<T = unknown> { ... }   // 셀 템플릿 컨텍스트
+```
 
-inputs: `key`(required), `header: string|string[]` (배열은 다중 행 헤더), `headerStyle`, `tooltip`, `width`, `fixed`, `hidden`, `collapse`, `disableSorting`, `disableResizing`, `ordering`.
+- `key` — 정렬·설정 저장 식별자. 시트 내 unique.
+- `header` 배열 — `["상위", "하위"]` 형태로 2단·3단 헤더 그룹화. 인접 컬럼이 같은 상위 헤더면 머지.
+- `fixed` — 좌측 sticky.
+- `ordering` — 사용자가 드래그로 바꾼 순서가 우선. 같은 ordering 끼리는 선언 순서.
 
-자식 template:
-- `<ng-template cell let-item="item">` (필수, `SdSheetColumnCellTemplate`, ctx: `SdSheetCellContext<T> = { $implicit, item, index, depth, edit }`).
-- `<ng-template #headerTpl>` (선택, 커스텀 헤더).
-- `<ng-template #summaryTpl>` (선택, 합계 행).
+## SdSheetColumnCellTemplate — `<ng-template cell>` (Directive)
+
+```ts
+class SdSheetColumnCellTemplate<T> { cell = input.required<T[]>(); }
+```
+
+- `<sd-sheet-column>` 안의 셀 템플릿 마커. `[cell]` 에 items 배열 바인딩(type guard 용도). let-item, let-index, let-depth 사용 가능.
+
+## SdSheetConfigModal — `<sd-sheet-config-modal>` (SdModalContentDef)
+
+```ts
+sheetKey = input.required<string>();
+controls = input.required<readonly SdSheetColumn[]>();
+config = input.required<SdSheetConfig|undefined>();
+close = output<SdSheetConfig|undefined>();
+```
+
+- 컬럼 표시/숨김/순서/너비 설정 모달. `SdSheet` 내부에서 호출. 직접 부를 일은 거의 없음.
 
 ## 타입
 
-```typescript
-interface SdSheetColumnDef { key; header; headerStyle?; tooltip?; width?; fixed; hidden; collapse; disableSorting; disableResizing; ordering }
-interface SdSheetHeaderDef { text; colspan; rowspan; isLastRow; fixed; colDef?; colIndex }
-interface SdSheetConfig    { columnRecord: Record<string, { width?; hidden?; fixed?; ordering? }> }
+```ts
+interface SdSheetColumnDef {
+  key, header, headerStyle, tooltip, width, fixed, hidden, collapse,
+  disableSorting, disableResizing, ordering
+}
+interface SdSheetHeaderDef {
+  text, colspan, rowspan, isLastRow, fixed, colDef, colIndex
+}
+interface SdSheetConfig {
+  columnRecord: Record<string, { width?, hidden?, fixed?, ordering? }>;
+}
+interface SdSheetItemKeydownEventParam<T> { item: T; event: KeyboardEvent; }
+interface SdSheetCellKeydownEventParam<T> { item: T; key: string; event: KeyboardEvent; }
 ```
 
-## 설정 모달
+- `SdSheetCellContext<T>` 는 셀 템플릿 안에서 노출되는 context 타입(item/index/depth/edit mode 등).
+
+## 주의
 
-`SdSheetConfigModal` (`SdModalContentDef<SdSheetConfig | undefined>`): `sheetKey`, `controls: SdSheetColumn[]`, `config: SdSheetConfig | undefined` inputs. 사용자가 컬럼 너비/숨김/고정/순서 편집 후 저장 → `close.emit(config)`.
+- `key` 지정 시 `SdSystemConfigProvider` 가 부착되어 있어야 영구 저장. 미부착이면 `SdLocalStorageProvider` 경유.
+- `selectMode=multi` 일 때 `selectedKeys` 는 `trackByFn` 반환 키. `items` 와 별개 배열.
+- 트리(`getChildrenFn`) + 정렬(`useAutoSort=true`) 동시 사용 시 정렬은 각 depth 안에서만 적용.

package/claude/references/sd-simplysm14/apis/angular/toast.md

@@ -1,46 +1,97 @@
-# @simplysm/angular — toast
+# @simplysm/angular — toast / busy / print
 
-전역 토스트. `SdToastContainer`는 첫 호출 시 body에 자동 생성.
+전역 알림·로딩·인쇄 프로바이더. 컨테이너는 첫 호출 시 body 에 자동 생성.
 
-## 기본 사용
+## SdToastProvider (root)
 
-```typescript
-const toast = inject(SdToastProvider);
-toast.info("저장되었습니다.");
-toast.success("...");
-toast.warning("...");
-toast.danger("...");
+```ts
+alertThemes: WritableSignal<SdToastSeverity[]>;        // 여기에 포함된 severity 는 window.alert 로 강제
+overlap: WritableSignal<boolean>;                       // true 면 동시 표시 안 함(새 토스트가 기존 제거)
+beforeShowFn?: (theme: SdToastSeverity) => void;
 
-const progress = toast.info("업로드 중", true);   // WritableSignal<number>
-progress.set(50);   // 100 도달 시 1초 후 자동 dismiss
+info/success/warning/danger(message: string, useProgress?: false): void;
+info/success/warning/danger(message: string, useProgress: true): WritableSignal<number>;
+notify<T extends SdToastContentDef<O>>(input: SdToastInput<T>): Promise<O|undefined>;
+try<R>(fn: () => Promise<R>|R, messageFn?: (err) => string): Promise<R|undefined>|R|undefined;
 
-await toast.try(async () => svc.save(), (e) => `저장 실패: ${e.message}`);
-// 에러 시 danger 토스트 + systemLog, 성공 시 결과 반환
+type SdToastSeverity = "info"|"success"|"warning"|"danger";
+type SdToastTheme = "primary"|"secondary"|SdToastSeverity|"gray"|"blue-gray";
+interface SdToastContentDef<O> { close: OutputEmitterRef<O|undefined>; }
+interface SdToastInput<T> { type: Type<T>; inputs: <T 의 input prop 들, close 제외>; }
 ```
 
-- 일반 토스트: 3초 후 자동 해제(호버 중이면 leave 후 1초 지연).
-- progress 토스트: 100% 도달 후 1초.
-- `alertThemes = signal<SdToastSeverity[]>([])`: 포함된 severity는 토스트 대신 `window.alert`.
-- `overlap = signal(false)`: 새 토스트 표시 시 기존 토스트 모두 제거.
-- `beforeShowFn?: (theme) => void`: 표시 직전 후크 (예: 사운드).
+- `info`/`success` 는 `polite` aria-live, `warning`/`danger` 는 `assertive`/`alert` role.
+- `useProgress=true` 면 진행률 토스트. 반환 signal 에 0~100 set. 100 도달 후 1초 뒤 자동 해제. progress 모드가 아니면 3초(호버 중이면 마우스 떠난 뒤 1초) 자동 해제.
+- `alertThemes` 에 severity 포함되면 토스트 대신 `window.alert(message)`. 키오스크/PWA 백그라운드 알림 강제용.
+- `beforeShowFn` — 매 토스트 표시 직전 호출(소리·진동 등 부수효과).
+- `notify` — 커스텀 컴포넌트 컨텐츠로 토스트. 컴포넌트가 `close.emit(result)` 호출 시 Promise resolve, 5초 후 자동 dismiss(undefined resolve).
+- `try` — fn 실행 후 throw 된 Error 의 메시지로 `danger` 토스트 + `SdSystemLogProvider.writeAsync('error', ...)` 호출. 비-Error throw 는 다시 던짐.
 
-## 커스텀 컨텐츠 토스트
+```ts
+sdToast.success("저장 완료");
+const sig = sdToast.info("업로드 중...", true); sig.set(50);
+await sdToast.try(async () => await api.save(item));
+```
+
+## SdToast / SdToastContainer
+
+내부 사용 컴포넌트. 직접 쓸 일 거의 없음. `SdToastProvider` 가 첫 호출 시 `<sd-toast-container>` 를 body 에 append.
+
+```ts
+// SdToastContainer
+overlap = input(false);   // true 면 절대배치로 1개만 표시되는 룩
+```
+
+## SdBusyProvider (root)
+
+```ts
+type: WritableSignal<SdBusyType>;            // "spinner"|"bar"|"cube", default "bar"
+globalBusyCount: WritableSignal<number>;     // >0 이면 전역 busy 표시. provideSdAngular 가 navigation 동안 증감
+type SdBusyType = "spinner"|"bar"|"cube";
+```
 
-```typescript
-interface SdToastContentDef<O> { close: OutputEmitterRef<O | undefined>; }
-interface SdToastInput<T>      { type: Type<T>; inputs: DirectiveInputSignals<T> 제외 close }
+- `globalBusyCount` 증가/감소로 전역 잠금 화면 토글.
+- `type` — 인디케이터 모양. `spinner` 는 원형 회전, `bar` 는 상단 진행 바(슬림), `cube` 는 4분할 큐브 애니메이션.
 
-const result = await toast.notify({ type: MyToastComp, inputs: { kind: "x" } });
+## SdBusyContainer — `<sd-busy-container>`
+
+```ts
+busy = input(false); message = input<string|undefined>();
+type = input<SdBusyType|undefined>();        // 미지정이면 SdBusyProvider.type() 사용
+progressPercent = input<number|undefined>(); // 0~100, null 이면 막대 숨김
+```
+
+- 일부 영역만 busy 표시. `busy` true 동안 자식 영역에 오버레이 + 키보드 입력 차단.
+
+```html
+<sd-busy-container [busy]="loading()" [progressPercent]="pct()">...영역 내용...</sd-busy-container>
 ```
 
-`close.emit` 시 resolve. 5초 자동 dismiss (resolve undefined).
+## SdPrintProvider (root)
 
-## 타입
+```ts
+printAsync<T extends SdPrint>(template: SdPrintInput<T>, options?: { size?: string; margin?: string }): Promise<void>;
+getPdfBufferAsync<T extends SdPrint>(template: SdPrintInput<T>, options?: { orientation?: "portrait"|"landscape"; pageSize?: string }): Promise<Uint8Array>;
 
-- `SdToastSeverity = "info" | "success" | "warning" | "danger"`
-- `SdToastTheme = "primary" | "secondary" | SdToastSeverity | "gray" | "blue-gray"` (SdToast 컴포넌트의 theme input)
+interface SdPrint { initialized: Signal<boolean>; readonly _optionalPrintInputs?: string; }
+interface SdPrintInput<T, X = ""> { type: Type<T>; inputs: <T 의 input prop 들>; }
+```
+
+- 인쇄용 컴포넌트를 동적으로 body 에 부착 → `initialized() === true` 대기 → 이미지 로드 완료 대기 → `window.print()` 또는 jsPDF + html-to-image 로 PDF 버퍼 생성.
+- `printAsync.options.size` — `@page size`. 기본 `"A4 auto"`.
+- `printAsync.options.margin` — `@page margin`. 기본 `"0"`.
+- `getPdfBufferAsync.options.pageSize` — jsPDF page 크기. 기본 `"a4"`.
+- `getPdfBufferAsync.options.orientation` — `"portrait"`/`"landscape"`. 기본 `"portrait"`(`"p"`).
+- PDF 생성 시 컴포넌트 안 `.page` 클래스 요소 각각 1페이지로 처리, 없으면 컴포넌트 전체 1페이지.
+- 인쇄 진행 동안 `SdBusyProvider.globalBusyCount` 자동 증감.
+
+```ts
+await sdPrint.printAsync({ type: InvoicePrint, inputs: { order: data } }, { size: "A4 portrait" });
+const buf = await sdPrint.getPdfBufferAsync({ type: InvoicePrint, inputs: { order } });
+```
 
-## `SdToast` / `SdToastContainer` (직접 사용은 비권장)
+## 주의
 
-- `<sd-toast [open] [theme] [useProgress] [(progress)] [(message)]>` — aria-live 자동 (`polite` info/success, `assertive` warning/danger).
-- `<sd-toast-container [overlap]>` — 위치 컨테이너. `SdToastProvider`가 lazily 생성.
+- `SdToastProvider.try` 는 `Error` 가 아닌 throw 는 그대로 re-throw. 일반 함수에서 throw 시 반드시 Error 인스턴스 던질 것.
+- `SdBusyContainer` 의 `min-height: 70px` 가 기본. 빈 컨테이너에서도 인디케이터 보이도록.
+- `SdPrint.initialized` 를 컴포넌트가 true 로 안 set 하면 `wait.until` 이 영원히 대기. 비동기 데이터 로드 후 반드시 set.

package/claude/references/sd-simplysm14/apis/angular/visual.md

@@ -1,59 +1,167 @@
 # @simplysm/angular — visual
 
-데이터 시각화/표시 전용 컴포넌트.
+시각/표시 컴포넌트 (라벨·뱃지·진행률·달력·바코드·차트·에디터·주소검색) + 보조 레이아웃 컨테이너 (collapse·tab·list·gap·pagination·dropdown).
 
-## `<sd-label>`
+## SdLabel — `<sd-label>`
 
-배지 형 라벨. `theme`(테마 컬러), `color` (커스텀 background), `clickable`. content projection.
+```ts
+theme = input<"primary"|"secondary"|"info"|"success"|"warning"|"danger"|"gray"|"blue-gray">();
+color = input<string>();      // 직접 색상 hex
+clickable = input(false);
+```
 
-## `<sd-note>`
+- 작은 텍스트 뱃지. `theme` 또는 `color` 중 하나. `clickable=true` 면 커서 pointer + 호버 효과.
 
-알림 박스 형. `theme`, `size: "sm"|"lg"`, `inset`. content projection.
+## SdNote — `<sd-note>`
 
-## `<sd-progress>`
+```ts
+theme = input<...8 themes>();
+size = input<"sm"|"lg">();
+inset = input(false);
+```
 
-```html
-<sd-progress [theme]="'primary'" [value]="0.6" [size]="'sm'" [inset]="false" />
+- 정보 박스(노트). `<ng-content>` 가 본문. 페이지 안내문구.
+
+## SdProgress — `<sd-progress>`
+
+```ts
+inset = input(false); size = input<"sm"|"lg">();
+theme = input.required<...8 themes>();
+value = input.required<number>();   // 0~100
 ```
 
-`theme` (required), `value: number` (required, **0~1 비율**), `size`, `inset`. 표시 텍스트는 `value | percent: "1.0-2"`, 진행바 폭은 `value*100%` (0~100 클램프).
+- 가로 진행 바. value/100 만큼 채움.
 
-## `<sd-calendar<T>>`
+## SdCalendar — `<sd-calendar>`
 
-월별 달력 렌더. 6행 × 7열 고정. `<ng-template itemOf>` 로 각 셀의 아이템 렌더.
+```ts
+class SdCalendar<T>
+items = input.required<T[]>();
+getItemDateFn = input.required<(item: T, index: number) => DateOnly>();
+yearMonth = input(new DateOnly().setDay(1));
+weekStartDay = input(0);          // 0=일요일, 1=월요일
+minDaysInFirstWeek = input(1);
+// 자식: <ng-template itemOf>...</ng-template> 로 셀별 아이템 렌더
+```
+
+- 월별 달력 그리드. 각 날짜 셀에 해당하는 items 만 추려 itemOf 템플릿으로 렌더.
+- `weekStartDay` — 0~6.
+- `minDaysInFirstWeek` — 첫 주에 포함될 최소 일수(ISO 주차 규칙).
 
 ```html
-<sd-calendar [items]="events" [getItemDateFn]="byDate" [yearMonth]="curMonth">
-  <ng-template [itemOf]="events" let-item="item">
-    <div>{{ item.title }}</div>
-  </ng-template>
+<sd-calendar [items]="events()" [getItemDateFn]="getDate" [yearMonth]="ym()">
+  <ng-template itemOf [itemOf]="events()" let-item>{{ item.title }}</ng-template>
 </sd-calendar>
 ```
 
-- 필수 input: `items: T[]`, `getItemDateFn: (item, idx) => DateOnly`.
-- `yearMonth = input(new DateOnly().setDay(1))` (해당 월).
-- `weekStartDay = 0`, `minDaysInFirstWeek = 1`.
-- 필수 content: `<ng-template [itemOf]="items">` (`SdItemOfTemplate`, ctx: `$implicit/item/index/depth`).
+## SdBarcode — `<sd-barcode>`
 
-## `<sd-barcode>`
+```ts
+type = input.required<BarcodeType>();
+value = input<string>();
 
-`bwip-js` 래퍼. `type: BarcodeType` (required), `value: string`. `BarcodeType` 은 bwip-js 지원 심볼로지 union (`code128`, `qrcode`, `ean13`, ... — 전체 목록은 `sd-barcode.ts` 참조).
+type BarcodeType = "code128"|"qrcode"|"ean13"|"ean8"|"code39"|... (bwip-js bcid 전체)
+```
 
-```html
-<sd-barcode [type]="'qrcode'" [value]="data" />
+- bwip-js 로 SVG 바코드 렌더. value 비면 빈 출력. 인식 불가 데이터면 catch 후 빈 출력.
+
+## SdEcharts — `<sd-echarts>`
+
+```ts
+option = input.required<echarts.EChartsOption>();
+notMerge = input(false);    // setOption merge 비활성
+loading = input(false);     // showLoading/hideLoading
 ```
 
-내부적으로 `bwipjs.toSVG`로 생성 후 `bypassSecurityTrustHtml`. value 빈 문자열/렌더 실패 시 빈 출력.
+- ECharts 래퍼. `option` 변경 시 자동 setOption.
 
-## `<sd-echarts>`
+## SdTiptapEditor — `<sd-tiptap-editor>`
 
-ECharts 5/6 래퍼.
+```ts
+value = model<string>();              // HTML 문자열
+disabled = input(false); readonly = input(false); required = input(false);
+placeholder = input<string>();
+validatorFn = input<(value) => string|undefined>();
+extensions = input<AnyExtension[]>();  // 추가 tiptap extensions
+```
 
-```html
-<sd-echarts [option]="option" [notMerge]="false" [loading]="false" />
+- WYSIWYG HTML 에디터. tiptap 기반. 기본 extension(헤딩/볼드/리스트 등) 내장.
+
+## SdAddressSearchModal — `<sd-address-search-modal>` (SdModalContentDef<Address>)
+
+```ts
+close = output<Address>();
+initialized = signal(false);
+interface Address { postNumber: string|undefined; address: string|undefined; buildingName: string|undefined; }
+```
+
+- 다음(daum) 우편번호 검색 위젯 모달. `SdModalProvider.showAsync({ type: SdAddressSearchModal, ... })` 로 호출.
+- 다음 postcode 스크립트 로드 실패 시 에러 메시지 표시.
+
+## SdCollapse — `<sd-collapse>`
+
+```ts
+open = input(false);
 ```
 
-- `option: echarts.EChartsOption` (required) — 변경 시 `chart.setOption(option, { notMerge })`.
-- `notMerge` (default `false`).
-- `loading` (default `false`) — `showLoading`/`hideLoading` 토글.
-- `hostDirectives: SdResizeDirective` 로 호스트 리사이즈 감지 → `chart.resize()`. renderer `"svg"` 고정.
+- 접힘/펼침 컨테이너. transition 으로 height 애니메이션. `<ng-content>` 가 본문.
+
+## SdCollapseIcon — `<sd-collapse-icon>`
+
+```ts
+icon = input(tablerChevronDown);
+open = input(false);
+openRotate = input(90);     // open 일 때 회전 각도
+```
+
+- 펼침/접힘 표시 아이콘. open 토글 시 회전 애니메이션.
+
+## SdTab — `<sd-tab>` / SdTabItem — `<sd-tab-item>`
+
+```ts
+class SdTab { value = model<any>(); }
+class SdTabItem { value = input<any>(); }
+```
+
+- 탭 컨테이너 + 탭 항목. `<sd-tab-item value="a">A</sd-tab-item>` 클릭 시 `SdTab.value` 가 `"a"` 로.
+
+## SdList — `<sd-list>` / SdListItem — `<sd-list-item>`
+
+```ts
+class SdList { inset = input(false); }
+class SdListItem {
+  layout = input<"accordion"|"flat">("accordion");
+  open = model(false);
+  selected = input(false); selectedIcon = input<string>();
+  readonly = input(false);
+  contentStyle = input<string>(); contentClass = input<string>();
+}
+```
+
+- 세로 메뉴/리스트. `layout="accordion"` 이면 자식 리스트 펼침 가능, `flat` 이면 상시 전개.
+- `selected=true` → 강조 + `selectedIcon` 표시.
+
+## SdGap — `<sd-gap>`
+
+```ts
+height = input<"xxs"|"xs"|"sm"|"default"|"lg"|"xl"|"xxl">();
+heightPx = input<number>();
+width = input<"xxs"|...|"xxl">(); widthPx = input<number>(); widthEm = input<number>();
+```
+
+- 빈 공간 채움. 토큰 키워드(디자인 변수) 또는 px/em 직접 지정.
+
+## SdPagination — `<sd-pagination>`
+
+```ts
+currentPage = model(0);
+totalPageCount = input(0);
+visiblePageCount = input(10);
+```
+
+- 페이지 번호 바. 0-based. `<sd-sheet>`/`<sd-crud-list>` 내부에서 사용되지만 단독 사용도 가능.
+
+## 주의
+
+- `SdCalendar` 의 자식 `<ng-template itemOf>` 의 `[itemOf]` 는 `items()` 와 같은 배열 바인딩(type token 용도).
+- `SdBarcode` 는 `bypassSecurityTrustHtml` 사용. value 가 사용자 입력이라도 bwip-js 가 SVG 만 생성하므로 안전(코드 주입 불가).