npm - @simplysm/sd-claude - Versions diffs - 14.0.91 → 14.0.93 - Mend

@simplysm/sd-claude 14.0.91 → 14.0.93

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 (93) hide show

package/claude/references/sd-simplysm14/apis/angular/infra.md CHANGED Viewed

@@ -1,91 +1,82 @@
-# @simplysm/angular — 부트스트랩·전역 프로바이더
+# @simplysm/angular — 앱 부트스트랩·전역 설정
-앱 시작 시 1회 배선하는 `provideSdAngular` 와, `providedIn: "root"` 로 어디서든 inject 하는 전역 프로바이더(테마·로컬스토리지·시스템설정·시스템로그·서비스클라이언트·설정값)를 모은 군. 화면이 아니라 부트스트랩(`provideAppInitializer`)·앱 셸 코드에서 같이 읽힌다.
+앱 시작 시 1회 배선하는 `provideSdAngular` 와, `providedIn: "root"` 로 어디서든 inject 하는 전역 프로바이더(테마·로컬스토리지·시스템설정·시스템로그·서비스클라이언트)를 모은 군. 화면보다 부트스트랩(`provideAppInitializer`)·앱 셸·설정 코드에서 같이 읽힌다.
 ## provideSdAngular
-```ts
-function provideSdAngular(opt: { clientName: string }): EnvironmentProviders
-```
+zoneless Angular 앱의 핵심 프로바이더 묶음을 `EnvironmentProviders` 로 생성. `bootstrapApplication` 의 `providers` 에 한 번 넣음.
-`ApplicationConfig.providers` 에 1개 넣으면 simplysm 클라이언트 동작 전체가 배선됨. 내부 처리:
+- `opt.clientName: string` — 클라이언트 식별명. `SdAngularConfigProvider.clientName` 으로 저장되어 로컬스토리지 키 prefix·서비스 클라이언트 연결명에 쓰임.
-- `clientName` — 이 클라이언트의 식별 이름. `SdAngularConfigProvider.clientName` 으로 보관되어 로컬스토리지 키 prefix, 서비스 클라이언트 이름, 시스템 로그 `clientName` 등에 사용. `provideSdAngular({ clientName: CLIENT_NAME })` 형태로 전달하며, 시스템 로그 배선 시 같은 값을 씀(`client-system-log.md`).
-- ng-icons 전역 설정(strokeWidth 1.5, size 1.33em), `IMAGE_CONFIG`(이미지 경고 비활성), `provideZonelessChangeDetection()`.
-- 테마(dark/fontSize) 를 `SdLocalStorageProvider` 와 양방향 동기화(저장값 복원 + 변경 시 저장).
-- `window` 의 `unhandledrejection`/`error` 를 `ErrorHandler` 로 위임 + `ErrorHandler` 를 `SdGlobalErrorHandlerPlugin` 으로 교체(미처리 에러를 전체화면 표시 + 시스템로그 적재).
-- `EVENT_MANAGER_PLUGINS` 에 `SdOptionEventPlugin`(capture/passive/once 이벤트 옵션 지원) 추가.
-- service-worker(`SwUpdate`) 가 있으면 5분 주기(실패 시 지수 백오프, 최대 1시간)로 업데이트 확인 후 사용자 confirm → reload.
-- 라우터가 있으면 네비게이션 시작/종료에 `SdBusyProvider.globalBusyCount` 를 ±1 → 전역 busy 표시.
+배선 내용(본문 기준): zoneless 변경 감지, ng-icons 기본 설정(stroke 1.5, size 1.33em), `IMAGE_CONFIG` 경고 끔, 전역 `ErrorHandler` 를 `SdGlobalErrorHandlerPlugin` 으로, `EVENT_MANAGER_PLUGINS` 에 `SdOptionEventPlugin` 추가, `window` 의 `error`/`unhandledrejection` 을 `ErrorHandler` 로 위임, 저장된 dark/fontSize 를 `SdThemeProvider` 에 복원하고 변경 시 로컬스토리지에 영속, 서비스워커 업데이트 주기 폴링(확인 시 새로고침 prompt, 실패 시 지수 백오프), 라우터 네비게이션 동안 `SdBusyProvider.globalBusyCount` 증감.
-사용: `bootstrapApplication(AppRoot, { providers: [provideSdAngular({ clientName: CLIENT_NAME }), provideRouter(...), ...] })`.
+```ts
+bootstrapApplication(AppComponent, {
+  providers: [provideSdAngular({ clientName: "wms-admin" }), provideRouter(routes)],
+});
+```
 ## SdAngularConfigProvider
-- `clientName: string` — `provideSdAngular` 가 주입하는 클라이언트 이름. 다른 provider 가 prefix/식별자로 참조. 보통 직접 set 하지 않음.
+`provideSdAngular` 가 채우는 전역 설정 보관소. 직접 set 하지 않고 `provideSdAngular(opt)` 로 주입됨.
+- `clientName: string` — 앱 식별명. 로컬스토리지 키·서비스 클라이언트명으로 참조.
 ## SdThemeProvider
-다크모드·기본 글자크기 전역 상태. `provideSdAngular` 가 로컬스토리지 동기화를 자동 배선하므로 화면에서는 토글만 호출.
+다크모드·글자크기 전역 상태. `provideSdAngular` 가 로컬스토리지와 동기화. `sd-theme-selector` 가 이 프로바이더를 토글.
-- `dark: WritableSignal<boolean>` — 다크모드 on/off. true 면 `<body>` 에 `sd-theme-dark` 클래스 토글. 테마 전환 UI 에서 set.
-- `fontSize: WritableSignal<number>` — 루트 폰트 크기(px). 변경 시 `<html>` 의 `font-size` 적용(전체 rem 기준 스케일).
-- `fontSizePresets: readonly number[]` — `[12,14,16,20,24,28]`. 증감 단계 후보.
-- `increaseFontSize(): void` / `decreaseFontSize(): void` — presets 안에서 한 단계 위/아래로 이동. 경계면 무변경.
-- 사용: 테마 선택 UI 는 `sd-theme-selector`(features.md) 가 이 provider 를 래핑. 직접 다크 토글은 `inject(SdThemeProvider).dark.update(v => !v)`.
+- `dark: WritableSignal<boolean>` — 다크 모드 여부. true 면 `document.body` 에 `sd-theme-dark` 클래스 토글. 다크/라이트 전환 시.
+- `fontSize: WritableSignal<number>` — 루트 글자 크기(px). 변경 시 `documentElement.style.fontSize` 반영.
+- `fontSizePresets: readonly number[]` — 선택 가능한 글자 크기 단계(`[12,14,16,20,24,28]`).
+- `increaseFontSize()` / `decreaseFontSize()` — 프리셋에서 한 단계 위/아래로 이동.
 ## SdLocalStorageProvider<T>
-`localStorage` 를 `<clientName>.<key>` 네임스페이스로 JSON 직렬화해 읽고 씀. 제네릭 `T` 로 키→값 타입 매핑.
+`clientName` 을 prefix 로 붙여 `localStorage` 에 JSON 직렬화 저장/조회. 제네릭 `T` 로 키→값 타입 매핑.
+- `set<K>(key, value)` — `"{clientName}.{key}"` 키에 `JSON.stringify` 저장.
+- `get<K>(key): T[K] | undefined` — 저장값 파싱. 없거나 파싱 실패 시 `undefined`(결측 보존).
+- `remove(key)` — 키 삭제.
-- `set<K extends keyof T & string>(key: K, value: T[K]): void` — `JSON.stringify` 후 저장.
-- `get<K extends keyof T & string>(key: K): T[K] | undefined` — 파싱해 반환. 미존재·파싱실패 시 `undefined`(결측 보존).
-- `remove(key: keyof T & string): void` — 삭제.
-- 사용: `inject<SdLocalStorageProvider<{ "last-tab": string }>>(SdLocalStorageProvider)`.
+```ts
+private readonly _ls = inject<SdLocalStorageProvider<{ lastTab: string }>>(SdLocalStorageProvider);
+this._ls.set("lastTab", "summary");
+```
 ## SdSystemConfigProvider<T>
-화면별 설정(시트 컬럼 구성, 모달 위치 등) 영속화. 외부 저장 함수(`fn`) 가 꽂혀 있으면 그쪽, 없으면 `SdLocalStorageProvider` 로 폴백.
+화면별 사용자 설정(시트 컬럼 구성 등)을 서버 또는 로컬에 저장/조회. `fn` 미설정 시 `SdLocalStorageProvider` 로 폴백.
-- `fn?: { set(key, data): Promise<void>|void; get(key): PromiseLike<unknown> }` — 서버 등 외부 저장소 연동 훅. 부트스트랩에서 할당하면 모든 설정이 외부로 영속. 미할당이면 로컬스토리지만 사용.
-- `setAsync<K>(key: K, data: T[K] | undefined): Promise<void>` — `fn` 있으면 위임, 없으면 로컬스토리지에 저장(데이터 `null` 이면 remove).
-- `getAsync(key): Promise<unknown>` — `fn` 있으면 위임, 없으면 로컬스토리지 get.
-- 직접 호출보다 `injectSdSystemConfigResource` (아래) 로 컴포넌트별 자동 키 분리·resource 화해 쓰는 게 표준.
+- `fn?: { set(key, data); get(key) }` — 외부 저장 콜백. 설정하면 서버 등에 위임, 미설정 시 로컬스토리지 사용.
+- `setAsync<K>(key, data)` — `data` 가 null 이면 삭제, 아니면 저장.
+- `getAsync(key)` — 저장값 조회.
 ## injectSdSystemConfigResource<T>
-```ts
-function injectSdSystemConfigResource<T>(options: { key: Signal<string | undefined> }): {
-  value: Signal<T | undefined>;
-  isLoading: Signal<boolean>;
-  status: Signal<...>;
-  hasValue(): boolean;
-  reload(): void;
-  set(value: T | undefined): void;
-  update(fn: (prev: T | undefined) => T | undefined): void;
-}
-```
+`SdSystemConfigProvider` 를 host 태그명+key 로 감싼 Angular `resource` 래퍼. 시트가 컬럼 구성 영속화에 사용. injection 컨텍스트에서 호출.
-`SdSystemConfigProvider` 위에 Angular `resource` 를 얹은 컴포넌트 스코프 헬퍼. 실제 저장 키는 `<호스트엘리먼트태그>.<key>` 로 자동 분리되어 같은 컴포넌트 종류끼리 설정을 공유.
-- `options.key: Signal<string | undefined>` — 설정 키 signal. `undefined` 면 로드/저장 스킵. 컴포넌트의 `key` 입력을 그대로 넘김.
-- `set` — 메모리 즉시 반영 후 microtask 로 `setAsync` 영속(실패 시 ErrorHandler 로 전파, silent skip 아님).
-- `sd-sheet` 가 컬럼 설정을 이걸로 보관(sheet.md 참조).
+- `options.key: Signal<string | undefined>` — 설정 식별 키 시그널. `undefined` 면 로드/저장 안 함. 저장 키는 `"{호스트태그}.{key}"`.
+- 반환: `value`/`isLoading`/`status`/`hasValue()`/`reload()` 와, 값을 set 하면 즉시 `setAsync` 로 영속하는 `set(value)`·`update(fn)`.
 ## SdSystemLogProvider
-프레임워크가 잡은 에러/경고를 콘솔 + (배선 시) 외부 저장소로 적재. 자세한 배선·자동 적재 지점은 `client-system-log.md` 참조.
+콘솔 로깅 + 외부(DB 등) 적재를 겸하는 시스템 로그 프로바이더. 전역 에러 핸들러가 이걸로 에러를 기록.
-- `writeFn?: (severity: "error"|"warn"|"log", ...data: any[]) => Promise<void>|void` — 외부 적재 함수. 부트스트랩에서 1회 할당(예: DB insert). 미할당 시 콘솔만.
-- `writeAsync(severity: "error"|"warn"|"log", ...data: any[]): Promise<void>` — 항상 콘솔(`createLogger("angular:system-log")`)로 먼저 찍고, `writeFn` 있으면 추가 적재. `writeFn` 호출은 try/catch 로 감싸 실패해도 throw 하지 않음(로그 싱크 실패가 본 동작을 막지 않게 한 의도된 설계).
-  - `severity` 값 차이: `"error"` = 문제 발생, `"warn"` = 인지 필요, `"log"` = 일반. `SdGlobalErrorHandlerPlugin`·`SdToastProvider.try/danger` 가 자동으로 `"error"` 적재.
-- 직접 적재: `await this._sdSystemLog.writeAsync("error", "결제 승인 실패", err.stack)`.
+- `writeFn?: (severity: "error"|"warn"|"log", ...data) => Promise<void>|void` — 외부 적재 콜백. 설정 시 콘솔 출력 후 호출(실패해도 throw 안 하고 logger.error).
+- `writeAsync(severity, ...data)` — 콘솔에 해당 severity 로 출력하고, `writeFn` 있으면 함께 적재.
+```ts
+const sysLog = inject(SdSystemLogProvider);
+sysLog.writeFn = (sev, ...data) => appService.systemLog.writeAsync(sev, data);
+```
 ## SdServiceClientFactoryProvider
-`@simplysm/service-client` 의 `ServiceClient` 를 key 별로 생성·보관·종료. 요청/응답 진행률을 자동으로 토스트 progress 로 표시.
+키별로 `ServiceClient`(`@simplysm/service-client`) 연결을 생성·보관·종료하고, 요청/응답 진행률을 토스트로 표시.
+- `connectAsync(key, options?)` — 현재 location(host/port/ssl) 기본값에 `options` 머지해 연결. 이미 연결/종료된 키면 throw. 진행 이벤트를 progress 토스트로.
+- `closeAsync(key)` — 해당 키 연결 종료. 미연결 키면 throw.
+- `get(key): ServiceClient` — 연결된 클라이언트 반환. 미연결/종료 키면 throw.
-- `connectAsync(key: string, options?: Partial<ServiceConnectionOptions>): Promise<void>` — key 로 클라이언트 연결. host/port/ssl 미지정 시 현재 `location` 기준 기본값. 이미 연결됐거나 닫힌 key 면 throw. 연결 중 `request-progress`/`response-progress` 를 받아 `SdToastProvider.info(..., true)` progress 로 갱신.
-- `closeAsync(key: string): Promise<void>` — 연결 종료 + 해당 key 를 닫힘 처리(재연결 불가). 미연결 key 면 throw.
-- `get(key: string): ServiceClient` — 연결된 클라이언트 반환. 미연결/닫힘이면 throw(silent 반환 안 함).
-- 앱은 보통 `AppServiceProvider` 가 이걸 래핑(`client-service.md`). 화면에서 직접 inject 하기보다 앱 provider 경유.
+앱 서비스 프로바이더(`AppServiceProvider`)가 이 팩토리를 감싸 쓰는 형태이며, 직접 호출보다 앱 프로바이더 경유가 일반적.

package/claude/references/sd-simplysm14/apis/angular/layout.md CHANGED Viewed

@@ -1,63 +1,53 @@
-# @simplysm/angular — 레이아웃 셸 (사이드바·탑바)
+# @simplysm/angular — 레이아웃(사이드바·탑바)
 앱 셸의 좌측 사이드바·상단바와 그 안의 메뉴/사용자 메뉴 컴포넌트 군. 앱 루트 레이아웃(`app.root` 등)에서 한 번 구성. 메뉴 항목 타입(`SdMenu`)·라우터 링크는 routing-appstructure.md 의 것을 사용.
 ## 사이드바
-### SdSidebarContainer (`sd-sidebar-container`)
+### SdSidebarContainer — `sd-sidebar-container`
+사이드바 + 본문을 감싸는 컨테이너. 토글 시 본문 패딩을 조정하고 모바일에서 backdrop 표시. 라우팅 시작 시 자동 닫힘. 입력 없음(내부 `toggle` 상태 보유).
-사이드바 + 본문을 감싸는 컨테이너. 데스크톱은 사이드바 폭만큼 좌패딩, 모바일은 오버레이. 라우팅 시작 시 자동으로 토글을 닫음(모바일 메뉴 닫힘).
+### SdSidebar — `sd-sidebar`
+실제 사이드바 패널. 부모 컨테이너의 `toggle` 을 따라 슬라이드. 입력 없음. 자식으로 메뉴/유저 메뉴 배치.
-- `toggle: WritableSignal<boolean>` — 사이드바 접힘(데스크톱) / 닫힘(모바일) 상태. `sd-topbar` 의 햄버거가 이걸 토글. 배경(backdrop) 클릭으로도 토글.
-- 자식으로 `<sd-sidebar>` 와 본문을 둠.
+### SdSidebarMenu — `sd-sidebar-menu`
+메뉴 트리를 리스트로 렌더.
+- `menus: input<SdMenu[]>` — 표시할 메뉴 트리(보통 `appStructure.usableMenus()`).
+- `layout: "accordion"|"flat"` — 펼침 방식. 미지정 시 루트 메뉴 3개 이하면 `"flat"`, 초과면 `"accordion"` 자동.
+- `getMenuIsSelectedFn: (menu) => boolean` — 선택 판정 커스텀(미지정 시 현재 페이지 코드 일치).
-### SdSidebar (`sd-sidebar`)
+### SdSidebarUser — `sd-sidebar-user`
+사이드바 상단 사용자 영역(이름 + 펼침 메뉴).
+- `userMenu: input<SdSidebarUserMenu>` — `{ icon?, title, menus: { title, onClick }[] }`. `title` 이 사용자명, `menus` 가 펼침 항목(로그아웃 등).
-실제 사이드바 패널. 부모 `SdSidebarContainer.toggle` 에 따라 슬라이드 인/아웃.
-- (입력 없음) 부모 컨테이너의 toggle 을 computed 로 반영. 내부에 `<sd-sidebar-user>`·`<sd-sidebar-menu>` 등을 배치.
-### SdSidebarMenu (`sd-sidebar-menu`)
-메뉴 트리를 리스트로 렌더(중첩, 라우터 링크/외부 URL).
-- `menus: SdMenu[]` — 표시할 메뉴 트리(보통 `SdAppStructureProvider.usableMenus()`).
-- `layout: "accordion"|"flat"` — 루트 레벨 레이아웃. 미지정 시 메뉴 3개 이하면 `"flat"`, 초과면 `"accordion"` 자동 선택.
-- `getMenuIsSelectedFn: (menu: SdMenu) => boolean` — 선택 판정 커스텀(미지정 시 현재 페이지 코드 비교).
-- 동작: leaf 메뉴는 `getMenuRouterLinkOption` 으로 라우팅, `url` 메뉴는 새 창.
-### SdSidebarUser (`sd-sidebar-user`)
-사이드바 상단 사용자 영역 + 접이식 사용자 메뉴.
-- `userMenu: SdSidebarUserMenu` — `{ title: string; menus: { title: string; onClick: () => void }[] }`. `title` 클릭 시 메뉴 펼침, 각 메뉴 클릭 시 `onClick`. 로그아웃/설정 등.
-- `<ng-content>` 로 사용자 이름/아바타 영역 배치.
+```html
+<sd-sidebar-container>
+  <sd-sidebar>
+    <sd-sidebar-user [userMenu]="{ title: userName(), menus: [{ title: '로그아웃', onClick: logout }] }" />
+    <sd-sidebar-menu [menus]="menus()" />
+  </sd-sidebar>
+  <router-outlet />
+</sd-sidebar-container>
+```
 ## 탑바
-### SdTopbarContainer (`sd-topbar-container`)
-상단바 + 본문 세로 스택 컨테이너(상단 고정 + 본문 fill). `sd-base-container` 가 page 모드에서 내부적으로 사용.
-### SdTopbar (`sd-topbar`)
-상단바 본문. 사이드바가 있으면 좌측에 햄버거 토글 버튼 자동 표시.
-- `sidebarContainer: SdSidebarContainer` — 토글 대상 사이드바 컨테이너(미지정 시 inject 로 자동 탐색). 둘 다 없으면 햄버거 미표시.
-- `hasSidebar: Signal<boolean>` — 사이드바 존재 여부(햄버거 표시 기준).
-- `<ng-content>` 로 제목·메뉴·사용자 영역 배치.
-### SdTopbarMenu (`sd-topbar-menu`)
-상단바 가로 메뉴(드롭다운 펼침).
+### SdTopbarContainer — `sd-topbar-container`
+탑바 + 본문 세로 컨테이너. 입력 없음. (`sd-base-container` 가 page 모드에서 내부적으로 사용.)
-- `menus: SdMenu[]` — 표시할 메뉴 트리. 각 루트 메뉴가 드롭다운 버튼이 되고 children 을 팝업 리스트로.
-- `getMenuIsSelectedFn: (menu: SdMenu) => boolean` — 선택 판정 커스텀.
-- leaf 클릭 시 라우팅 + 드롭다운 닫힘, `url` 메뉴는 새 창.
+### SdTopbar — `sd-topbar`
+상단바. 사이드바 토글 버튼 + 타이틀/명령 슬롯.
+- `sidebarContainer: input<SdSidebarContainer>` — 토글 대상 사이드바 컨테이너(미지정 시 inject 로 상위 컨테이너 사용). 둘 중 하나라도 있으면 토글 버튼 노출.
-### SdTopbarUser (`sd-topbar-user`)
+### SdTopbarMenu — `sd-topbar-menu`
+상단 가로 메뉴.
+- `menus: input<SdMenu[]>` — 메뉴 항목.
+- `getMenuIsSelectedFn: (menu) => boolean` — 선택 판정 커스텀.
-상단바 우측 사용자 드롭다운 메뉴.
+### SdTopbarUser — `sd-topbar-user`
+상단 우측 사용자 드롭다운.
+- `menus: input.required<SdTopbarUserMenu[]>` — `{ title, onClick }[]`. 클릭 시 `onClick` 실행 후 드롭다운 닫힘.
-- `menus: input.required<SdTopbarUserMenu[]>` — `SdTopbarUserMenu = { title: string; onClick: () => void }`. 각 항목 클릭 시 `onClick` 실행 후 드롭다운 닫힘.
-- `<ng-content>` 로 트리거 버튼 라벨(사용자 이름) 배치.
+### 타입
+- `SdSidebarUserMenu` — `{ icon?: string; title: string; menus: { title: string; onClick: () => Promise<void>|void }[] }`.
+- `SdTopbarUserMenu` — `{ title: string; onClick: () => void }`.

package/claude/references/sd-simplysm14/apis/angular/overlay.md CHANGED Viewed

@@ -1,103 +1,111 @@
-# @simplysm/angular — 모달·토스트·Busy·인쇄 (오버레이/전역 피드백)
+# @simplysm/angular — 오버레이(모달·토스트·busy·인쇄)
-화면에서 프로그래밍 방식으로 모달을 띄우거나, 토스트로 알림·진행률을 표시하거나, busy 인디케이터·인쇄/PDF 출력을 호출할 때 함께 읽히는 군. provider 는 모두 `providedIn: "root"`, 컴포넌트는 provider 가 동적으로 body 에 attach 하므로 템플릿에 직접 둘 일은 거의 없음.
+화면에서 프로그래밍 방식으로 모달을 띄우거나, 토스트로 알림·진행률을 표시하거나, busy 인디케이터·인쇄/PDF 출력을 호출할 때 함께 읽히는 군. provider 는 모두 `providedIn: "root"`, 동적으로 body 에 attach 하므로 컴포넌트를 템플릿에 직접 둘 일은 거의 없음.
 ## SdModalProvider
-컴포넌트를 모달 셸(`SdModal`) 안에 동적 생성해 body 에 띄움. `close.emit(payload)` 또는 닫기(X/배경/ESC)로 종료.
+`showAsync` 로 컴포넌트를 모달로 띄움. 컨텐츠 컴포넌트는 `SdModalContentDef<O>` 를 구현해야 함.
-```ts
-showAsync<T extends SdModalContentDef<any>>(
-  modal: SdModalInfo<T>, options?: SdModalOptions,
-): Promise<Parameters<T["close"]["emit"]>[0] | undefined>
-```
-- `modal.type: Type<T>` — `SdModalContentDef<O>` 를 구현한 컴포넌트 클래스(`SdModal` 자체가 아님). `O` 가 close 페이로드 타입.
-- `modal.title: string` — 모달 헤더 제목.
-- `modal.inputs` — 모달 컴포넌트가 받을 input 값. `initialized`/`close`/`actionTplRef` 와 `_optionalModalInputs` 로 표시된 키는 제외/optional 처리됨. 없으면 `{}`.
-- 반환값 — 컴포넌트가 `close.emit` 한 페이로드. 닫기/취소로 닫히면 `undefined`. 매뉴얼 패턴: `const r = await this._sdModal.showAsync({...}); if (!r) return;`.
 - `modalCount: WritableSignal<number>` — 현재 열린 모달 수.
+- `showAsync<T>(modal: SdModalInfo<T>, options?: SdModalOptions): Promise<O | undefined>` — 모달을 띄우고 close 페이로드를 반환. 사용자가 X/취소로 닫으면 `undefined`.
+`SdModalInfo<T>`:
+- `title: string` — 모달 헤더 제목.
+- `type: Type<T>` — `SdModalContentDef` 구현 컴포넌트 클래스.
+- `inputs` — 컴포넌트 input 값들. `initialized`/`close`/`actionTplRef` 제외, optional 입력은 생략 가능.
+`SdModalContentDef<O>` (컨텐츠 컴포넌트가 구현):
+- `initialized: Signal<boolean>` — 로드 완료 시그널.
+- `close: OutputEmitterRef<O | undefined>` — 닫기 + 페이로드 emit. emit 값이 `showAsync` 반환값.
+- `actionTplRef?: TemplateRef` — 헤더 우측에 끼울 액션 영역 템플릿(선택).
+`SdModalOptions` (선택):
+- `key?: string` — 모달 식별 키.
+- `hideHeader: boolean` — 헤더 숨김. true 면 제목/닫기 영역 없음.
+- `hideCloseButton: boolean` — 닫기 버튼만 숨김.
+- `headerStyle?: string` — 헤더 인라인 스타일.
+- `useCloseByBackdrop: boolean` — 배경 클릭으로 닫기 허용(기본 true).
+- `useCloseByEscapeKey: boolean` — ESC 로 닫기 허용(기본 true).
+- `float: boolean` — 화면에 띄우는 플로팅 모드.
+- `fill: boolean` — 화면 가득 채움.
+- `resizable: boolean` — 가장자리 드래그 리사이즈 허용.
+- `movable: boolean` — 헤더 드래그 이동 허용.
+- `position: "bottom-right"|"top-right"` — 고정 위치.
+- `minHeightPx`/`minWidthPx`/`heightPx`/`widthPx: number` — 크기(px).
+- `noFirstControlFocusing: boolean` — true 면 첫 입력에 자동 포커스하지 않고 dialog 에 포커스.
-### SdModalContentDef<O> (모달 컴포넌트가 구현)
-- `initialized: Signal<boolean>` — 초기화 완료 여부. busy 표시 해제 기준.
-- `close: OutputEmitterRef<O | undefined>` — 결과 emit. `O` 가 `showAsync` 반환 타입.
-- `actionTplRef?: TemplateRef<any>` — 헤더 우측에 끼울 액션 영역 템플릿(있으면 모달 헤더로 브릿지됨).
-- `_optionalModalInputs?: string` — (타입 전용 마커) 이 컴포넌트의 input 중 optional 로 둘 키 이름 리터럴. 런타임 값 아님.
-### SdModalOptions (showAsync 2번째 인자)
-- `key?: string` — 설정 저장 키. 지정 시 사용자가 조정한 width/height/위치를 `SdSystemConfigProvider` 에 영속·복원.
-- `hideHeader?: boolean` — true 면 제목/닫기 헤더 숨김. 헤더 없는 풀커스텀 모달용.
-- `hideCloseButton?: boolean` — true 면 헤더 X 버튼만 숨김.
-- `headerStyle?: string` — 헤더 영역 인라인 스타일.
-- `useCloseByBackdrop?: boolean` — 배경 클릭으로 닫기 허용(기본 동작상 컴포넌트 기본 true). false 면 배경 클릭 무시.
-- `useCloseByEscapeKey?: boolean` — ESC 로 닫기 허용. false 면 ESC 무시.
-- `float?: boolean` — true 면 배경(backdrop) 없는 떠있는 패널. 비모달 보조 패널용.
-- `fill?: boolean` — true 면 화면 전체를 채움(풀스크린 모달).
-- `resizable?: boolean` — true 면 8방향 리사이즈 핸들 표시.
-- `movable?: boolean` — true 면 헤더 드래그로 이동.
-- `position?: "bottom-right" | "top-right"` — 고정 위치. 토스트성 알림 모달에 사용.
-- `minHeightPx?/minWidthPx?/heightPx?/widthPx?: number` — 최소/초기 크기.
-- `noFirstControlFocusing?: boolean` — true 면 첫 입력 요소 자동 포커스를 끔(다이얼로그 자체에 포커스).
+```ts
+const result = await inject(SdModalProvider).showAsync(
+  { type: GoodsDetailModal, title: "품목 등록", inputs: { goodsId: 12 } },
+  { resizable: true, widthPx: 720 },
+);
+if (result == null) return;
+```
-### 내장 모달 컴포넌트
+## SdActivatedModalProvider<T>
-- `SdPromptModal` (`SdModalContentDef<string>`) — 메시지 + 텍스트 입력 후 확인/취소. `message: input.required<string>` (innerHTML). 확인 시 입력값, 취소/닫기 시 `undefined`. 입력은 required 라 빈 값이면 네이티브 검증으로 차단.
-- `SdConfirmModal` (`SdModalContentDef<boolean>`) — 메시지 + 확인/취소. `message: input.required<string>`. 확인 시 `true`, 취소/닫기 시 `undefined`.
-- 사용: `const ok = await this._sdModal.showAsync({ type: SdConfirmModal, title: "확인", inputs: { message: "삭제할까요?" } }); if (!ok) return;`.
+모달 컨텐츠 컴포넌트 안에서 inject 해 자기 모달 셸을 제어. `SdModalProvider` 가 컨텐츠 인젝터에 주입.
-### SdActivatedModalProvider
+- `modalComponent: WritableSignal<SdModal | undefined>` — 모달 셸 컴포넌트 참조(제목 등 조회).
+- `contentComponent: WritableSignal<T | undefined>` — 컨텐츠 컴포넌트 참조.
+- `canDeactivateFn: () => boolean` — 닫기 시도 시 가드. `setupCanDeactivate` 가 이 값을 설정.
-모달 컴포넌트 내부에서 inject. 자기 모달의 셸/콘텐츠 참조와 이탈 가드를 보유.
+## SdPromptModal / SdConfirmModal
-- `modalComponent: Signal<SdModal | undefined>` / `contentComponent: Signal<T | undefined>` — 셸/콘텐츠 컴포넌트 참조.
-- `canDeactivateFn: () => boolean` — 닫기 시도 시 false 면 닫힘 차단. `setupCanDeactivate`(routing-appstructure.md) 가 모달 컨텍스트에서 이걸 설정.
+바로 쓰는 범용 모달 컨텐츠 컴포넌트.
-### SdModal (모달 셸)
+- `SdPromptModal` — `SdModalContentDef<string>`. `message: input.required<string>` 를 표시하고 텍스트 입력(필수) 후 확인 시 입력값, 취소 시 `undefined` emit.
+- `SdConfirmModal` — `SdModalContentDef<boolean>`. `message: input.required<string>` 표시 후 확인 시 `true`, 취소 시 `undefined` emit.
-`SdModalProvider` 가 내부적으로 생성하는 셸 컴포넌트. 상속·직접 배치 대상 아님. `<ng-content>` 로 콘텐츠를 투영하고 위 `SdModalOptions` 와 동일한 input(`title`/`open`/`resizable`/... `closeRequest` output) 을 보유.
+```ts
+const ok = await sdModal.showAsync({ type: SdConfirmModal, title: "삭제", inputs: { message: "삭제할까요?" } });
+```
 ## SdToastProvider
-화면 우상단(또는 overlap 모드)에 토스트를 띄움. 알림·비동기 에러 가드·진행률에 사용.
+토스트 알림·진행률·커스텀 토스트를 띄우고, 비동기 try 래퍼를 제공.
-- `info/success/warning/danger(message: string): void` — 심각도별 토스트 1개 표시(3초 후 자동 해제, hover 중이면 지연). `info`/`success` 는 `aria-live=polite`, `warning`/`danger` 는 `assertive`. 심각도 의미는 `sd-design-rules` 의 분류를 따름(error=문제 발생).
-- `info/...(message: string, useProgress: true): WritableSignal<number>` — progress 모드. 반환된 signal 에 0~100 을 set 하면 진행바 갱신, 100 도달 1초 후 자동 해제. 업로드/다운로드 진행률 표시에 사용.
-- `try<R>(fn: () => Promise<R> | R, messageFn?: (err: Error) => string): Promise<R | undefined>` — `fn` 실행 중 `Error` 가 throw 되면 잡아서 `danger` 토스트 + 시스템로그 `error` 적재 후 `undefined` 반환(에러를 외부로 전파하지 않음). `Error` 가 아닌 throw 는 그대로 재전파. 매뉴얼의 비동기 작업 표준 가드: `await this._sdToast.try(async () => { ... })`.
-- `notify<T extends SdToastContentDef<any>>(input: SdToastInput<T>): Promise<...>` — 커스텀 컴포넌트를 토스트로 띄우고 `close` 페이로드를 반환(5초 후 자동 `undefined`).
-- `alertThemes: WritableSignal<SdToastSeverity[]>` — 여기 든 심각도는 토스트 대신 `window.alert` 로 표시(키오스크 등 강제 확인 필요 화면).
-- `overlap: WritableSignal<boolean>` — true 면 새 토스트가 기존 토스트를 제거하고 단독 표시.
-- `beforeShowFn?: (theme: SdToastSeverity) => void` — 토스트 표시 직전 콜백(사운드 등).
+- `info`/`success`/`warning`/`danger(message, useProgress?)` — 해당 severity 토스트. `useProgress: true` 면 진행률 토스트로 `WritableSignal<number>`(0~100) 반환(100 도달 1초 후 자동 닫힘), `false`/생략이면 일정 시간 후 자동 닫힘.
+- `try<R>(fn, messageFn?): Promise<R | undefined>` — `fn` 실행 중 `Error` throw 시 `danger` 토스트로 표시하고 시스템 로그에 기록한 뒤 `undefined` 반환(에러 외 throw 는 재전파). 화면 비동기 작업 표준 래퍼.
+- `notify<T>(input: SdToastInput<T>): Promise<O | undefined>` — 커스텀 컴포넌트(`SdToastContentDef<O>`)를 토스트로 띄움. close emit 값 또는 5초 후 `undefined` 반환.
+- `alertThemes: WritableSignal<SdToastSeverity[]>` — 여기에 든 severity 는 토스트 대신 `window.alert` 로 표시.
+- `overlap: WritableSignal<boolean>` — true 면 새 토스트가 기존 토스트를 모두 치움.
+- `beforeShowFn?: (theme) => void` — 토스트 표시 직전 콜백.
 타입:
 - `SdToastSeverity = "info"|"success"|"warning"|"danger"`.
-- `SdToastTheme = "primary"|"secondary"|SdToastSeverity|"gray"|"blue-gray"` — `sd-toast` 컴포넌트 `theme` 입력 범위.
-- `SdToastContentDef<O> = { close: OutputEmitterRef<O | undefined> }` — `notify` 커스텀 컴포넌트 규약.
-- `SdToastInput<T> = { type: Type<T>; inputs: Omit<DirectiveInputSignals<T>, "close"> }`.
+- `SdToastTheme = "primary"|"secondary"|SdToastSeverity|"gray"|"blue-gray"`.
+- `SdToastContentDef<O>` — `close: OutputEmitterRef<O | undefined>` 보유.
+- `SdToastInput<T>` — `{ type: Type<T>; inputs }`(`close` 제외).
+```ts
+this.busyCount.update((v) => v + 1);
+await this._sdToast.try(async () => { await this._refresh(); });
+this.busyCount.update((v) => v - 1);
+this._sdToast.success("저장되었습니다.");
+```
-`SdToast`/`SdToastContainer` 는 provider 가 동적 생성하는 표시 컴포넌트(직접 배치 불필요).
+## SdBusyProvider
-## SdBusyProvider / SdBusyContainer
+전역 busy 인디케이터 상태. `provideSdAngular` 가 라우팅 동안 증감, 인쇄 provider 도 사용.
-영역 단위 busy 오버레이.
+- `type: WritableSignal<SdBusyType>` — 인디케이터 모양(`"spinner"|"bar"|"cube"`, 기본 `"bar"`).
+- `globalBusyCount: WritableSignal<number>` — 0 보다 크면 화면 전체 busy 오버레이 표시. 비동기 작업 시작 `+1`, 종료 `-1`.
-- `SdBusyProvider.type: WritableSignal<SdBusyType>` — 전역 기본 인디케이터 종류. `SdBusyType = "spinner"|"bar"|"cube"`. `"bar"` = 상단 가는 진행바, `"spinner"` = 회전 원, `"cube"` = 큐브 애니메이션.
-- `SdBusyProvider.globalBusyCount: WritableSignal<number>` — 전역 busy 카운트(>0 이면 화면 전체 busy). 라우팅·인쇄가 ±1. 직접 ±1 해 전역 차단 가능.
-- `SdBusyContainer` (`sd-busy-container`) — 자식 영역에 busy 오버레이를 씌우는 컨테이너 컴포넌트.
-  - `busy: boolean` — true 면 오버레이 표시 + 영역 내 키입력 차단.
-  - `message: string` — 인디케이터 옆/아래 표시 메시지.
-  - `type: SdBusyType` — 이 영역만의 인디케이터 종류(미지정 시 provider 기본값).
-  - `progressPercent: number` — 지정 시 상단 진행바(0~100). 결정형 작업 진행률에 사용.
-  - 사용: `<sd-busy-container [busy]="busyCount() > 0">...</sd-busy-container>` (단, `sd-base-container` 가 이미 내장).
+`SdBusyContainer` 컴포넌트(영역 단위 busy): `busy: boolean`, `message?: string`, `type?: SdBusyType`, `progressPercent?: number`(진행 바). 화면 영역을 감싸 그 영역만 busy 표시.
 ## SdPrintProvider
-인쇄 템플릿 컴포넌트를 동적 생성해 `window.print()` 하거나 PDF 버퍼로 변환. 호출 동안 `globalBusyCount` ±1.
+화면 컴포넌트(`SdPrint` 구현)를 인쇄하거나 PDF 버퍼로 변환. 처리 동안 `globalBusyCount` 증감.
-- `printAsync<T extends SdPrint>(template: SdPrintInput<T>, options?: { size?: string; margin?: string }): Promise<void>` — 템플릿을 숨겨 붙인 뒤 `@media print` CSS 로 그것만 출력. `size` 기본 `"A4 auto"`, `margin` 기본 `"0"`. 이미지 로드 완료를 기다린 후 인쇄.
-- `getPdfBufferAsync<T extends SdPrint>(template: SdPrintInput<T>, options?: { orientation?: "portrait"|"landscape"; pageSize?: string }): Promise<Uint8Array>` — `.page` 요소들(없으면 루트)을 캔버스로 렌더해 jsPDF 로 PDF 바이트 생성. `orientation` 기본 portrait, `pageSize` 기본 `"a4"`. 첨부/저장용 PDF 가 필요할 때.
-- `SdPrint = { initialized: Signal<boolean>; _optionalPrintInputs?: string }` — 인쇄 템플릿 컴포넌트 규약. `initialized` 가 true 가 되어야 인쇄 진행(데이터 로드 대기).
-- `SdPrintInput<T> = { type: Type<T>; inputs: ... }` — 인쇄 컴포넌트 + input 값(`_optionalPrintInputs` 표시 키는 optional).
-- 사용: `await this._sdPrint.printAsync({ type: OutboundPrintTemplate, inputs: { id } })`. 인쇄 템플릿 파일은 `<domain>.print-template.ts`(client-component.md).
+- `printAsync<T>(template: SdPrintInput<T>, options?: { size?: string; margin?: string }): Promise<void>` — 컴포넌트를 렌더해 `@page` 스타일을 걸고 `window.print` 호출. `initialized()` 와 이미지 로드를 대기.
+- `getPdfBufferAsync<T>(template, options?: { orientation?: "portrait"|"landscape"; pageSize?: string }): Promise<Uint8Array>` — `.page` 요소(없으면 전체)를 캔버스로 떠 jsPDF 로 PDF 바이트 생성.
+`SdPrint` (템플릿 컴포넌트가 구현): `initialized: Signal<boolean>`(렌더 완료 시그널). `SdPrintInput<T>` — `{ type: Type<T>; inputs }`.
+```ts
+await inject(SdPrintProvider).printAsync(
+  { type: InvoicePrintTemplate, inputs: { invoiceId: 5 } },
+  { size: "A4", margin: "10mm" },
+);
+```