@simplysm/sd-claude 14.0.88 → 14.0.89

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

@@ -1,55 +1,40 @@
-# @simplysm/angular — 부가 기능(테마·주소·에디터·시각화·칸반·프리셋)
-
-화면에 부분적으로 끼워 쓰는 독립 기능 컴포넌트·프로바이더. 테마(다크/폰트), 주소검색 모달, TipTap 리치에디터, 시각화(라벨/노트/진행률/달력/바코드/차트), 칸반 보드, 상태 프리셋.
-
-## SdThemeProvider / SdThemeSelector
-
-- `SdThemeProvider` — 루트 테마 프로바이더. `dark: WritableSignal<boolean>`(다크모드, body 클래스 토글), `fontSize: WritableSignal<number>`(루트 폰트크기 px), `fontSizePresets: readonly number[]`(`[12,14,16,20,24,28]`), `increaseFontSize()`/`decreaseFontSize()`(프리셋 단계 이동). `provideSdAngular` 가 localStorage 영속화 연결.
-- `<sd-theme-selector>` — 드롭다운 UI. 폰트크기 ±버튼·다크모드 스위치로 프로바이더 조작. input 없음.
-
-## SdAddressSearchModal
-
-`<sd-address-search-modal>` — 다음(카카오) 우편번호 검색 모달. `SdModalContentDef<Address>` 구현(`SdModalProvider.showAsync` 의 type 으로 사용). 스크립트 동적 로드 후 임베드, 선택 시 결과 emit.
-
-- `close = output<Address>()` — 선택 결과. `Address = { postNumber?; address?; buildingName? }`(결측 보존).
-- input 없음. 스크립트 로드 실패 시 에러 메시지 표시.
-
-## SdTiptapEditor
-
-`<sd-tiptap-editor>` — TipTap 기반 리치텍스트 에디터(HTML 값, 툴바: 제목·굵게·기울임·밑줄·취소선·색상·리스트 등).
-
-- `value = model<string>()` — HTML 콘텐츠. 빈 내용이면 `undefined`(결측 보존).
-- `disabled`/`readonly` — 비활성/읽기전용(편집 불가, 툴바 숨김).
-- `required` — 필수 검증(폼 연동).
-- `placeholder` — 빈 상태 안내(미지정 확장 시 적용).
-- `validatorFn?: (value) => string | undefined` — 커스텀 검증 메시지.
-- `extensions?: AnyExtension[]` — TipTap 확장 직접 지정(미지정 시 기본 확장 + placeholder).
-- `editor: WritableSignal<Editor | undefined>` — 내부 TipTap 인스턴스(@internal, 고급/테스트용).
-
-## 시각화 컴포넌트
-
-- `<sd-label>` — 인라인 라벨/배지. `theme`(공통 8색), `color?`(임의 배경색), `clickable`(호버 효과·커서).
-- `<sd-note>` — 강조 박스. `theme`(공통 8색), `size`(`"sm"|"lg"`), `inset`.
-- `<sd-progress>` — 진행률 막대. `value = input.required<number>()`(0~1, 퍼센트 표시·막대폭), `theme = input.required<...>()`(공통 8색), `size`, `inset`.
-- `<sd-calendar>` — 월 달력에 항목 배치. 제네릭 `<T>`. `items = input.required<T[]>()`, `getItemDateFn = input.required<(item, index) => DateOnly>()`(항목 날짜), `yearMonth = input(...)`(표시 월, 기본 이번달 1일), `weekStartDay = input(0)`(주 시작 요일), `minDaysInFirstWeek = input(1)`. 셀 항목은 `<ng-template [itemOf]>`.
-- `<sd-barcode>` — 바코드/QR SVG 렌더(bwip-js). `type = input.required<BarcodeType>()`(바코드 종류, `"qrcode"`/`"code128"`/`"ean13"` 등 다수 리터럴 유니온), `value = input<string>()`(인코딩 텍스트, 빈값이면 미표시).
-- `<sd-echarts>` — ECharts 차트. `option = input.required<EChartsOption>()`(차트 옵션), `notMerge = input(false)`(setOption 병합 여부), `loading = input(false)`(로딩 스피너). 리사이즈 자동 반영.
-
-## SdKanbanBoard / SdKanbanLane / SdKanban
-
-드래그 가능한 칸반 보드. 보드 > 레인 > 카드 계층.
-
-- `<sd-kanban-board>` — 보드 컨테이너. 제네릭 `<L, T>`. `selectedValues = model<T[]>([])`(선택된 카드 값), `drop = output<SdKanbanBoardDropInfo<L, T>>()`(드롭 시 `{ sourceKanbanValue?; targetLaneValue?; targetKanbanValue? }`).
-- `<sd-kanban-lane>` — 레인(열). 제네릭 `<L, T>`. `value = input<L>()`(레인 값), `busy`(로딩), `useCollapse`(접기 버튼), `collapse = model(false)`. `#titleTpl`/`#toolTpl` 슬롯. 선택 가능 카드 있으면 전체선택 체크박스.
-- `<sd-kanban>` — 카드. 제네릭 `<L, T>`. `value = input<T>()`(카드 값), `selectable`(Shift클릭 선택), `draggable`(드래그 이동), `contentClass`.
-
-타입: `SdKanbanBoardDropInfo<L,T>`, `SdKanbanDragRef<L,T>`(`value()`/`heightOnDrag()`), `SdKanbanDropTarget<L,T>`(`targetLaneValue()`/`targetKanbanValue?()`).
-
-## SdStatePreset
-
-`<sd-state-preset>` — 화면 상태(필터 등)를 명명 프리셋으로 저장·복원(시스템설정 영속화). 제네릭 `<TState>`.
-
-- `key = input.required<string>()` — 프리셋 저장 키(태그명과 결합).
-- `state = model.required<TState>()` — 현재 상태(저장/적용 대상). 프리셋 클릭 시 이 값으로 복원.
-- `size = input<"sm"|"lg">()` — 크기.
-- ⭐버튼=현재 상태 새 프리셋 저장, 각 프리셋=클릭 적용/저장/삭제. `SdStatePresetDef<TState> = { name: string; state: TState }`.
+# @simplysm/angular — 기능 컴포넌트(주소검색·에디터·시각화·칸반)
+
+특정 도메인 기능을 제공하는 독립 컴포넌트 묶음. 필요한 화면에서 개별적으로 가져다 씀.
+
+## 주소 검색
+
+- **SdAddressSearchModal** — 다음(카카오) 우편번호 검색 모달 컴포넌트. `SdModalContentDef<Address>` 구현이라 `SdModalProvider.showAsync({ type: SdAddressSearchModal, ... })` 로 띄움. 외부 스크립트(daum postcode) 를 동적 로드. `close = output<Address>()`.
+- **Address** — `{ postNumber: string | undefined; address: string | undefined; buildingName: string | undefined }`. 결측은 undefined 보존.
+
+## 에디터
+
+- **SdTiptapEditor** `<sd-tiptap-editor [(value)]="...">` — tiptap 기반 리치텍스트 에디터(HTML 문자열).
+  - value = model<string>() — HTML 본문.
+  - disabled/readonly/required: boolean — 비활성/읽기전용/필수(빈 값 검증).
+  - placeholder?: string.
+  - validatorFn?: (value) => string | undefined — 커스텀 검증 메시지.
+  - extensions?: AnyExtension[] — 추가 tiptap 확장.
+
+## 시각화
+
+- **SdLabel** `<sd-label>` — 작은 배지/태그. `theme`(8색), `color?: string`(임의 배경색), `clickable: boolean`(호버 강조 + 커서).
+- **SdNote** `<sd-note>` — 안내 박스. `theme`(8색), `size`("sm"|"lg"), `inset: boolean`.
+- **SdProgress** `<sd-progress [theme]="..." [value]="...">` — 진행률 막대. `theme: input.required`(8색), `value: input.required<number>`(0~1, 백분율 표시·막대 폭은 0~100% clamp), `size`("sm"|"lg"), `inset: boolean`.
+- **SdCalendar<T>** `<sd-calendar [items]="..." [getItemDateFn]="...">` — 월간 달력에 항목 배치.
+  - items: input.required<T[]>.
+  - getItemDateFn: input.required<(item, index) => DateOnly> — 항목의 날짜.
+  - yearMonth: input(기본 이번 달 1일) — 표시 월.
+  - weekStartDay: number(기본 0=일요일) / minDaysInFirstWeek: number(기본 1) — 주 시작·첫 주 기준.
+  - (contentChild) `itemOf` 템플릿 필수 — 날짜 칸 항목 렌더.
+- **SdBarcode** `<sd-barcode [type]="..." [value]="...">` — bwip-js 로 바코드 SVG 렌더. `type: input.required<BarcodeType>`(qrcode/code128/ean13 등 다수 — `BarcodeType` 유니온 참조), `value?: string`(빈 값이면 미표시).
+- **SdEcharts** `<sd-echarts [option]="...">` — ECharts 차트. `option: input.required<echarts.EChartsOption>`, `notMerge: boolean`(기본 false, true 면 옵션 병합 대신 교체), `loading: boolean`(로딩 오버레이).
+
+## 칸반
+
+- **SdKanbanBoard<L, T>** `<sd-kanban-board>` — 칸반 보드 컨테이너(드래그 앤 드롭 조율).
+  - selectedValues = model<T[]>([]) — 선택된 카드 값(Shift+클릭 다중 선택).
+  - (output) drop: `SdKanbanBoardDropInfo<L,T>` = `{ sourceKanbanValue?; targetLaneValue?; targetKanbanValue? }` — 드롭 시 발생(소스 카드→대상 레인/카드).
+- **SdKanbanLane<L, T>** `<sd-kanban-lane [value]="...">` — 레인(열). `value?: L`(레인 식별), `busy: boolean`, `useCollapse: boolean`(접기 버튼) + `collapse = model(false)`, `toolTpl`/`titleTpl`(도구·제목 템플릿). 전체선택 체크박스(선택가능 카드 있을 때).
+- **SdKanban<L, T>** `<sd-kanban [value]="...">` — 카드. `value?: T`, `selectable: boolean`(Shift+클릭 선택 허용), `draggable: boolean`(드래그 허용), `contentClass?: string`. 드래그 시 다른 카드/레인 위에 드롭 위치 표시.
+- 타입: **SdKanbanBoardDropInfo<L,T>**(위), **SdKanbanDragRef<L,T>**(`{ value(); heightOnDrag() }`), **SdKanbanDropTarget<L,T>**(`{ targetLaneValue(); targetKanbanValue?() }`) — 보드 내부 드래그/드롭 대상 규약.

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

@@ -1,74 +1,74 @@
-# @simplysm/angular — 설정·로깅·서비스 인프라
+# @simplysm/angular — 부트스트랩·설정·로깅·서비스 인프라
 
-앱 부트스트랩과 함께 읽히는 인프라 묶음. `provideSdAngular()` 로 전역 프로바이더를 등록하고, 클라이언트명·테마영속화·시스템로그·로컬스토리지·시스템설정·서비스 클라이언트 연결·전역 에러 처리를 담당.
+앱 시작 시 1회 설정하는 부트스트랩 함수와 전역 프로바이더 묶음. 앱 부팅 코드(`appConfig`/`main.ts`)·전역 에러·서버 연결·시스템 설정 저장을 다룰 때 함께 읽힘.
 
 ## provideSdAngular
 
-`provideSdAngular(opt: { clientName: string }): EnvironmentProviders` — 앱 부트스트랩 시 `providers` 에 넣는 핵심 프로바이더 묶음.
+`provideSdAngular(opt: { clientName: string }): EnvironmentProviders` — 앱 `providers` 에 1개 추가하면 다음을 일괄 설정. zoneless 변경감지 활성, 전역 에러 핸들러(`SdGlobalErrorHandlerPlugin`) 등록, 옵션 이벤트 플러그인(`SdOptionEventPlugin`) 등록, ng-icons 기본설정(strokeWidth 1.5, size 1.33em), `IMAGE_CONFIG` 경고 비활성, 테마 dark/fontSize 를 로컬스토리지(`sd-theme-dark`/`sd-theme-font-size`)에 자동 영속, service worker 업데이트 폴링(5분~최대1시간 지수 백오프, 갱신 감지 시 새로고침 확인), 라우터 네비게이션 동안 글로벌 busy 카운트 증감.
 
-- `opt.clientName` — 클라이언트 식별명. `SdAngularConfigProvider.clientName` 에 주입되어 로컬스토리지 키 prefix·서비스 클라이언트 생성에 사용. 앱마다 고유해야 함.
+- opt.clientName: string — 이 클라이언트 식별자. 로컬스토리지 키 prefix·service-client 연결 이름으로 사용. 앱마다 고유 문자열.
 
-등록 내용(본문 기준): 이미지 경고 비활성화, ng-icon 기본 설정, 다크모드/폰트크기 localStorage 영속화 effect, `window` 의 `error`/`unhandledrejection` → ErrorHandler 위임, `SdOptionEventPlugin`(이벤트 옵션 플러그인), `SdGlobalErrorHandlerPlugin`(ErrorHandler), zoneless 변경감지, Service Worker 업데이트 폴링(지수 백오프, 발견 시 confirm 후 reload), 라우터 내비게이션 중 `SdBusyProvider.globalBusyCount` 증감.
-
-```typescript
+```ts
 bootstrapApplication(AppComponent, {
   providers: [provideRouter(routes), provideSdAngular({ clientName: "my-app" })],
 });
 ```
 
-## setupBgTheme
-
-`setupBgTheme(options?: { theme?: ..., lightness?: "lightest" | "lighter" }): void` — 컴포넌트 활성 동안 `document.body` 의 `--background-color` 를 테마 색으로 지정(effect, cleanup 시 복원). 컴포넌트 생성자/필드에서 호출.
-
-- `options.theme` — `"primary"|"secondary"|"info"|"success"|"warning"|"danger"|"gray"|"blue-gray"`. 배경 테마 색. 미지정 시 변수 비움(`""`).
-- `options.lightness` — `"lightest"|"lighter"`. 밝기 단계. 기본 `"lightest"`.
-
 ## SdAngularConfigProvider
 
-`class SdAngularConfigProvider { clientName!: string }` — `provideSdAngular` 가 설정하는 클라이언트명 보관 루트 프로바이더. 다른 프로바이더가 inject 해 prefix 로 사용.
-
-- `clientName` — 클라이언트 식별명. 직접 set 하지 말고 `provideSdAngular({clientName})` 로 주입됨.
+`@Injectable({providedIn:"root"})`. `clientName: string` 필드 1개. `provideSdAngular` 가 채워줌. 다른 프로바이더가 clientName 을 참조할 때 inject.
 
 ## SdSystemLogProvider
 
-`class SdSystemLogProvider` — 시스템 로그 기록 루트 프로바이더. 콘솔 로깅 + 선택적 외부 전송.
+전역 로그 기록 프로바이더. 콘솔 로그 + 선택적 서버 전송.
 
-- `writeFn?: (severity, ...data) => Promise<void> | void` — 외부 로그 싱크. 지정 시 `writeAsync` 가 콘솔 출력 후 이 함수도 호출. 미지정이면 콘솔만.
-- `writeAsync(severity: "error"|"warn"|"log", ...data): Promise<void>` — 로그 기록. `severity` 로 로거 메서드 선택 후 `writeFn` 있으면 await(실패 시 내부 로깅만, throw 안 함).
+- writeFn?: (severity, ...data) => Promise<void> | void — 외부(서버) 전송 훅. 지정하면 매 로그마다 호출. 서버 로그 적재가 필요하면 앱 초기화 때 할당.
+- writeAsync(severity: "error"|"warn"|"log", ...data): Promise<void> — 로그 기록. 콘솔에 먼저 출력 후 writeFn 호출. writeFn 이 throw 해도 로깅 자체는 실패하지 않음(내부 logger.error 로 기록).
 
-## SdLocalStorageProvider
+## SdLocalStorageProvider<T>
 
-`class SdLocalStorageProvider<T>` — `clientName.{key}` prefix 로 localStorage 에 JSON 저장하는 타입드 래퍼.
+`clientName.<key>` 형태로 localStorage 에 JSON 저장/조회. T 는 `{ key: 값타입 }` 맵.
 
-- `set<K>(key, value)` — `JSON.stringify` 후 저장. `key` 는 `T` 의 키.
-- `get<K>(key): T[K] | undefined` — 파싱 반환. 없거나 파싱 실패 시 `undefined`(결측 보존).
-- `remove(key)` — 항목 제거.
+- set<K>(key, value) — JSON.stringify 후 저장.
+- get<K>(key): T[K] | undefined — 없거나 파싱 실패 시 undefined(결측 보존).
+- remove(key) — 삭제.
 
-## SdSystemConfigProvider
+## SdSystemConfigProvider<T>
 
-`class SdSystemConfigProvider<T>` — 시스템 설정 저장소. 외부 `fn` 이 있으면 서버, 없으면 localStorage 폴백.
+화면별 설정(시트 컬럼 상태, 모달 위치, 상태 프리셋 등) 영속 프로바이더. `fn` 미지정 시 로컬스토리지로 폴백.
 
-- `fn?: { set(key, data): ...; get(key): PromiseLike<unknown> }` — 외부 저장 핸들러. 지정 시 서버 영속, 미지정 시 `SdLocalStorageProvider` 사용.
-- `setAsync<K>(key, data: T[K] | undefined)` — 저장. `fn` 있으면 위임, 없고 `data==null` 이면 remove, 아니면 localStorage set.
-- `getAsync(key)` — 조회. `fn` 있으면 위임, 없으면 localStorage get.
+- fn?: { set(key, data): Promise|void; get(key): PromiseLike<unknown> } — 서버 영속 훅. 지정하면 서버에 저장/조회, 미지정이면 `SdLocalStorageProvider` 로 폴백. 서버 동기화가 필요하면 앱 초기화 때 할당.
+- setAsync<K>(key, data) — data 가 null 이면 제거(폴백 시), 아니면 저장.
+- getAsync(key) — 저장된 값 조회.
 
-## injectSdSystemConfigResource
+## injectSdSystemConfigResource<T>
 
-`injectSdSystemConfigResource<T>(options: { key: Signal<string | undefined> })` — 호스트 엘리먼트 태그명 + `key` 로 시스템 설정을 읽고 쓰는 Angular `resource` 래퍼. 시트/상태프리셋이 컬럼·프리셋 영속화에 사용.
+`injectSdSystemConfigResource<T>({ key: Signal<string|undefined> })` — 컴포넌트 내에서 호출. 호스트 엘리먼트 태그명 + key 를 합친 키로 `SdSystemConfigProvider` 에 연동되는 resource 핸들 반환. key 가 undefined 면 로드/저장 안 함.
 
-- `options.key` — 설정 키 시그널. `undefined` 면 로드 안 함(결측). 실제 키는 `{태그명}.{key}`.
-- 반환: `{ value, isLoading, status, hasValue(), reload(), set(value), update(fn) }` — `set` 은 즉시 resource 갱신 + 마이크로태스크로 `setAsync` 영속화(실패 시 ErrorHandler 위임).
+- key: Signal<string|undefined> — 설정 키 signal. 빈 값이면 비활성.
+- 반환: `{ value, isLoading, status, hasValue(), reload(), set(v), update(fn) }`. set/update 는 즉시 로컬 반영 후 microtask 로 비동기 영속(실패 시 errorHandler 로 전달). 시트/상태프리셋이 내부적으로 사용.
 
 ## SdServiceClientFactoryProvider
 
-`class SdServiceClientFactoryProvider` — 키별 `ServiceClient` 연결 풀. 요청/응답 진행률을 토스트 progress 로 표시.
+`@simplysm/service-client` 연결을 key 단위로 관리하는 팩토리. 요청/응답 진행률을 토스트로 표시.
 
-- `connectAsync(key, options?: Partial<ServiceConnectionOptions>)` — `key` 로 클라이언트 연결. 호스트/포트/ssl 은 `location` 기본값 + `options` 머지. 이미 연결/이미 끊긴 키면 throw.
-- `closeAsync(key)` — 연결 종료 후 풀에서 제거(미연결 키면 throw).
-- `get(key): ServiceClient` — 연결된 클라이언트 반환. 미연결/끊긴 키면 throw.
+- connectAsync(key: string, options?: Partial<ServiceConnectionOptions>): Promise<void> — 연결 생성. host/port/ssl 미지정 시 현재 location 기준 기본값. 같은 key 재연결·끊긴 key 재사용 시 throw.
+- closeAsync(key): Promise<void> — 연결 종료. 미연결 key 면 throw.
+- get(key): ServiceClient — 연결된 클라이언트 반환. 미연결/끊김이면 throw. 서비스 호출 시 이걸로 ServiceClient 획득.
 
 ## SdGlobalErrorHandlerPlugin
 
-`class SdGlobalErrorHandlerPlugin implements ErrorHandler` — `provideSdAngular` 가 `ErrorHandler` 로 등록하는 전역 에러 핸들러.
+`ErrorHandler` 구현. `provideSdAngular` 가 등록하므로 직접 쓸 일은 드묾. 처리되지 않은 에러/Promise 거부를 시스템 로그에 기록하고 전체화면 오류 오버레이를 1회 표시 후 앱을 destroy(클릭 시 새로고침). 직접 inject 하지 말고 `throw` 로 위임.
+
+## SdThemeProvider
+
+`@Injectable({providedIn:"root"})`. 다크모드·폰트크기 전역 상태.
+
+- dark: WritableSignal<boolean> — 다크모드. true 면 body 에 `sd-theme-dark` 클래스 토글.
+- fontSize: WritableSignal<number> — 루트 폰트 크기(px). 변경 시 `documentElement.style.fontSize` 반영.
+- fontSizePresets: readonly number[] — `[12,14,16,20,24,28]`. 증감 단계.
+- increaseFontSize() / decreaseFontSize() — 프리셋 내 다음/이전 단계로 이동.
+
+## SdThemeSelector
 
-- `handleError(event)` — `PromiseRejectionEvent`/`ErrorEvent`/`Error`/기타를 분기해 메시지 구성 → 시스템 로그 기록 + 앱 파괴 후 전체화면 에러 오버레이 표시(클릭 시 reload). 최초 1회만 오버레이 노출. 직접 호출보다 Angular 가 자동 호출.
+`<sd-theme-selector />` — 폰트크기 증감·다크모드 스위치를 드롭다운으로 제공하는 컴포넌트. input 없음. `SdThemeProvider` 를 직접 조작. 탑바 등에 배치.

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

@@ -1,55 +1,27 @@
 # @simplysm/angular — 레이아웃(사이드바·탑바)
 
-앱 화면 셸을 구성하는 사이드바/탑바 컨테이너·메뉴·사용자 메뉴. 사이드바는 모바일에서 백드롭+슬라이드, 탑바는 사이드바 토글 버튼을 자동 제공. 메뉴 입력은 `SdMenu[]`(라우팅·앱구조 군 참조)이며 `sdRouterLink`/선택표시가 내장됨.
-
-## SdSidebarContainer
-
-`<sd-sidebar-container>` — 사이드바 + 본문 레이아웃 컨테이너. 본문에 좌측 패딩(`--sidebar-width`)을 주고, 모바일에서는 백드롭 표시. 라우터 내비게이션 시작 시 자동으로 사이드바를 닫음(`toggle` 신호 보유). input 없음.
-
-## SdSidebar
-
-`<sd-sidebar>` — 실제 사이드바 패널. 부모 `SdSidebarContainer.toggle` 을 따라 슬라이드 표시/숨김. 콘텐츠는 투영. input 없음.
-
-## SdSidebarMenu
-
-`<sd-sidebar-menu>` — 사이드바 메뉴 트리.
-
-- `menus = input<SdMenu[]>([])` — 메뉴 트리. `SdAppStructureProvider.usableMenus()` 결과를 주로 넣음.
-- `layout: "accordion"|"flat"` — 루트 메뉴 레이아웃. 미지정 시 메뉴 3개 이하면 flat, 초과면 accordion 자동.
-- `getMenuIsSelectedFn?: (menu) => boolean` — 선택 판정 커스텀(미지정 시 현재 페이지코드와 codeChain 비교).
-
-각 메뉴 항목은 `sdRouterLink` 로 `/home/{codeChain}` 이동, `url` 있으면 새 탭, 자식 있으면 하위 트리.
-
-## SdSidebarUser
-
-`<sd-sidebar-user>` — 사이드바 상단 사용자 영역 + 접이식 메뉴.
-
-- `userMenu = input<SdSidebarUserMenu>()` — `{ title: string; menus: { title; onClick }[] }`. title 클릭 시 메뉴 펼침, 각 항목 클릭 시 `onClick` 실행.
-- 콘텐츠 투영부에 사용자 정보 표시.
-
-## SdTopbarContainer
-
-`<sd-topbar-container>` — 탑바 + 본문 세로 레이아웃 컨테이너. input 없음. `<sd-topbar>` 와 본문을 자식으로 둠.
-
-## SdTopbar
-
-`<sd-topbar>` — 상단 바. 사이드바 컨테이너가 있으면 좌측에 메뉴 토글 버튼 자동 표시.
-
-- `sidebarContainer = input<SdSidebarContainer>()` — 토글 대상 사이드바. 미지정 시 inject 된 부모 `SdSidebarContainer` 사용. 둘 중 하나라도 있으면 토글 버튼 노출.
-- 콘텐츠(제목·액션)는 투영.
-
-## SdTopbarMenu
-
-`<sd-topbar-menu>` — 탑바 가로 메뉴(각 루트 메뉴가 드롭다운).
-
-- `menus = input<SdMenu[]>([])` — 메뉴 트리.
-- `getMenuIsSelectedFn?: (menu) => boolean` — 선택 판정 커스텀.
-
-리프 메뉴 클릭 시 드롭다운 닫힘, `url` 있으면 새 탭.
-
-## SdTopbarUser
-
-`<sd-topbar-user>` — 탑바 우측 사용자 드롭다운 메뉴.
-
-- `menus = input.required<SdTopbarUserMenu[]>()` — `{ title: string; onClick: () => void }[]`. 항목 클릭 시 `onClick` 실행 후 드롭다운 닫힘.
-- 트리거 라벨(사용자명 등)은 콘텐츠 투영.
+화면 골격을 만드는 사이드바·탑바 컴포넌트 묶음. 메뉴 데이터는 `SdMenu`(routing-appstructure.md 참조) 또는 자체 메뉴 객체를 사용.
+
+## 사이드바
+
+- **SdSidebarContainer** `<sd-sidebar-container>` — 사이드바 + 본문 레이아웃 컨테이너. input 없음. `toggle: WritableSignal<boolean>`(접힘 상태, 모바일은 backdrop 표시). 라우터 네비게이션 시작 시 자동 접힘. 자식으로 `sd-sidebar` 와 본문을 둠.
+- **SdSidebar** `<sd-sidebar>` — 사이드바 패널. input 없음(컨테이너의 toggle 을 따름). 좌측 고정, 모바일에서 오버레이.
+- **SdSidebarMenu** `<sd-sidebar-menu>` — 메뉴 트리 렌더. `menus = input<SdMenu[]>([])`, `layout`("accordion"|"flat" — 미지정 시 최상위 3개 이하면 flat, 아니면 accordion), `getMenuIsSelectedFn`(선택 판정 커스텀). leaf 는 `sdRouterLink` 로 이동, `menu.url` 있으면 새 창.
+- **SdSidebarUser** `<sd-sidebar-user>` — 사용자 영역 + 접이식 메뉴. `userMenu = input<SdSidebarUserMenu>()`. 투영 내용(프로필) + 클릭 시 펼쳐지는 메뉴 목록. 타입 `SdSidebarUserMenu = { title: string; menus: { title; onClick }[] }`.
+
+```html
+<sd-sidebar-container>
+  <sd-sidebar>
+    <sd-sidebar-user [userMenu]="userMenu">{{ userName }}</sd-sidebar-user>
+    <sd-sidebar-menu [menus]="appStructure.usableMenus()" />
+  </sd-sidebar>
+  <router-outlet />
+</sd-sidebar-container>
+```
+
+## 탑바
+
+- **SdTopbarContainer** `<sd-topbar-container>` — 탑바 + 본문 세로 레이아웃. input 없음.
+- **SdTopbar** `<sd-topbar>` — 상단 바. `sidebarContainer = input<SdSidebarContainer>()`(미지정 시 주입된 컨테이너 자동 사용). 사이드바가 있으면 좌측 토글(햄버거) 버튼 표시. 제목·도구는 투영.
+- **SdTopbarMenu** `<sd-topbar-menu>` — 드롭다운형 상단 메뉴 트리. `menus = input<SdMenu[]>([])`, `getMenuIsSelectedFn`. 최상위 메뉴별 드롭다운, leaf 클릭 시 이동·드롭다운 닫힘.
+- **SdTopbarUser** `<sd-topbar-user>` — 사용자 드롭다운 메뉴. `menus = input.required<SdTopbarUserMenu[]>()`. 투영 내용(이름) 클릭 시 메뉴 목록. 타입 `SdTopbarUserMenu = { title: string; onClick: () => void }`.

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

@@ -1,115 +1,103 @@
 # @simplysm/angular — 모달·토스트·Busy·인쇄 (오버레이)
 
-프로그래밍 방식으로 동적 컴포넌트를 body 에 부착하는 루트 프로바이더 4종(모달/토스트/Busy/인쇄)과 콘텐츠 컴포넌트가 구현할 인터페이스. 모두 `createComponent` + `ApplicationRef.attachView` 로 동작.
+화면 위에 띄우는 피드백·오버레이 묶음. 프로그래밍 방식으로 모달/토스트를 띄우거나 작업 진행 표시, 화면 인쇄/PDF 가 필요할 때 함께 읽힘.
 
 ## SdModalProvider
 
-`class SdModalProvider` — 모달을 프로그래밍 방식으로 띄우는 루트 프로바이더.
-
-- `modalCount: Signal<number>` — 현재 열린 모달 수.
-- `showAsync<T>(modal: SdModalInfo<T>, options?: SdModalOptions): Promise<결과 | undefined>` — 모달 표시. 콘텐츠 컴포넌트의 `close` emit 값으로 resolve, 배경/ESC/닫기버튼이면 `undefined`. 닫힘 애니메이션·포커스 복원·z-index 스택 처리.
-
-`SdModalInfo<T, X>`:
-- `title: string` — 모달 헤더 제목.
-- `type: Type<T>` — 콘텐츠 컴포넌트 클래스(`SdModalContentDef` 구현).
-- `inputs` — 콘텐츠 컴포넌트의 input 값 객체(`initialized`/`close`/`actionTplRef` 제외, `_optionalModalInputs` 로 지정된 키는 optional).
-
-`SdModalOptions`(모두 optional):
-- `key` — 설정 키. 지정 시 크기·위치를 `SdSystemConfigProvider` 에 영속화.
-- `hideHeader` — 헤더 전체 숨김.
-- `hideCloseButton` — 닫기(X) 버튼만 숨김.
-- `headerStyle` — 헤더 인라인 스타일.
-- `useCloseByBackdrop` — 배경 클릭으로 닫기 허용. 기본 true.
-- `useCloseByEscapeKey` — ESC 로 닫기 허용. 기본 true.
-- `float` — 배경 없는 플로팅 모달(다른 조작 가능).
-- `fill` — 전체화면 채움.
-- `resizable` — 모서리/변 드래그 리사이즈.
-- `movable` — 헤더 드래그 이동.
-- `position` — `"bottom-right"|"top-right"`. 고정 위치.
-- `minHeightPx`/`minWidthPx`/`heightPx`/`widthPx` — 크기 px.
-- `noFirstControlFocusing` — 첫 입력요소 자동 포커스 끔(true 면 dialog 자체 포커스).
-
-`SdModalContentDef<O>`(콘텐츠 컴포넌트 구현 인터페이스):
-- `initialized: Signal<boolean>` — 초기화 완료 신호.
-- `close: OutputEmitterRef<O | undefined>` — 결과 emit 시 모달 닫힘.
-- `actionTplRef?: TemplateRef<any>` — 헤더 우측 액션 영역 템플릿.
-- `_optionalModalInputs?: string` — optional 처리할 input 키(타입 마커).
-
-```typescript
+`@Injectable({providedIn:"root"})`. 컴포넌트를 모달로 동적 생성.
+
+- showAsync<T>(modal: SdModalInfo<T>, options?: SdModalOptions): Promise<close결과 | undefined> — 모달 표시. 컨텐츠 컴포넌트의 `close.emit(result)` 시 result 로 resolve, 배경클릭/ESC/닫기버튼 시 undefined 로 resolve. 첫 탭 가능 컨트롤에 자동 포커스.
+- modalCount: Signal<number> — 현재 열린 모달 수.
+
+`SdModalInfo<T, X>` = `{ title: string; type: Type<T>; inputs: ... }`. inputs 는 컨텐츠 컴포넌트의 input 중 `initialized`/`close`/`actionTplRef`/`_optionalModalInputs` 와 X 로 지정한 키를 제외한 것. `_optionalModalInputs` 로 선언한 키는 optional.
+
+`SdModalContentDef<O>` — 모달 컨텐츠 컴포넌트가 구현할 인터페이스:
+- initialized: Signal<boolean> — 초기화 완료 신호(인쇄/대기 동기화에 사용).
+- close: OutputEmitterRef<O | undefined> — 결과 emit. O 가 모달 반환 타입.
+- actionTplRef?: TemplateRef — 헤더 우측 액션 영역에 투영할 템플릿(있으면 모달 헤더로 브릿지됨).
+- _optionalModalInputs?: string — optional 로 둘 input 키들의 유니온 타입 표식(런타임 값 아님).
+
+`SdModalOptions`:
+- key?: string — 지정 시 크기·위치를 `SdSystemConfigProvider` 에 영속(`sd-modal.<key>`).
+- hideHeader?: boolean — 헤더(제목·닫기버튼) 숨김.
+- hideCloseButton?: boolean — 우상단 닫기 버튼만 숨김.
+- headerStyle?: string — 헤더 인라인 스타일.
+- useCloseByBackdrop?: boolean — 배경 클릭으로 닫기 허용(기본 true). 입력 확인 모달이면 false.
+- useCloseByEscapeKey?: boolean — ESC 로 닫기 허용(기본 true).
+- float?: boolean — 배경(backdrop) 없이 떠 있는 모달. 비차단 패널이면 true.
+- fill?: boolean — 화면 가득 채움(전체화면 모달).
+- resizable?: boolean — 8방향 리사이즈 핸들 표시.
+- movable?: boolean — 헤더 드래그로 이동.
+- position?: "bottom-right" | "top-right" — 고정 위치(알림형 모달).
+- minHeightPx/minWidthPx/heightPx/widthPx?: number — 최소·초기 크기(px).
+- noFirstControlFocusing?: boolean — 첫 컨트롤 자동 포커스 비활성(다이얼로그 자체에 포커스).
+
+```ts
 const result = await sdModal.showAsync(
-  { title: "사용자 선택", type: UserSelectModal, inputs: { deptId } },
+  { title: "사용자 선택", type: UserSelectModal, inputs: { teamId } },
   { resizable: true, key: "user-select" },
 );
 ```
 
 ## SdModal
 
-`<sd-modal>` — 모달 셸 컴포넌트. 보통 `SdModalProvider` 가 내부 생성하지만 선언적으로도 사용 가능.
-
-- `open = model(false)` — 열림 여부 양방향.
-- `title`/`hideHeader`/`hideCloseButton`/`headerStyle`/`useCloseByBackdrop`/`useCloseByEscapeKey`/`float`/`fill`/`resizable`/`movable`/`position`/`minHeightPx`/`minWidthPx`/`heightPx`/`widthPx`/`actionTplRef` — `SdModalOptions` 와 동일 의미의 input.
-- `key` — 크기·위치 영속화 키.
-- `closeRequest = output<void>()` — 배경/ESC/닫기버튼으로 닫기 요청 시 emit.
+`<sd-modal>` — `SdModalProvider` 가 내부적으로 생성하는 셸 컴포넌트. 직접 템플릿에 쓰기보다 provider 경유 권장. 위 `SdModalOptions` 와 동일한 input 들 + `open = model(false)`, `closeRequest = output<void>()`, `title`/`actionTplRef` input 보유.
 
 ## SdActivatedModalProvider
 
-`class SdActivatedModalProvider<T>` — 모달 콘텐츠 내부에서 inject 해 모달 컨텍스트에 접근.
-
-- `modalComponent: Signal<SdModal | undefined>` — 부모 `SdModal` 인스턴스.
-- `contentComponent: Signal<T | undefined>` — 콘텐츠 컴포넌트 인스턴스.
-- `canDeactivateFn: () => boolean` — 닫기 차단 함수(true 면 닫힘 허용). `setupCanDeactivate` 가 설정.
+모달 컨텐츠 컴포넌트 내부에서 inject. 현재 모달 제어.
+- modalComponent: Signal<SdModal | undefined> / contentComponent: Signal<T | undefined>.
+- canDeactivateFn: () => boolean — 닫기 차단 판정. `setupCanDeactivate` 가 설정. true 가 아니면 배경/ESC/버튼 닫기 무시.
 
 ## SdPromptModal / SdConfirmModal
 
-내장 범용 모달 콘텐츠. `SdModalProvider.showAsync` 의 `type` 으로 사용.
+provider 에 바로 넘길 수 있는 범용 모달 컴포넌트.
+- SdPromptModal: `SdModalContentDef<string>`. `message = input.required<string>()`. 텍스트 입력(필수) 후 확인 시 입력값, 취소 시 undefined emit.
+- SdConfirmModal: `SdModalContentDef<boolean>`. `message = input.required<string>()`. 확인 시 `true`, 취소 시 undefined emit.
 
-- `SdPromptModal` — `SdModalContentDef<string>`. `message: input.required<string>()` 표시 후 텍스트 입력. 확인 시 입력값 emit(필수 검증), 취소 시 `undefined`.
-- `SdConfirmModal` — `SdModalContentDef<boolean>`. `message` 표시 후 확인 시 `true`, 취소 시 `undefined` emit.
+```ts
+const name = await sdModal.showAsync({ title: "이름", type: SdPromptModal, inputs: { message: "이름?" } });
+```
 
 ## SdToastProvider
 
-`class SdToastProvider` — 토스트 알림 루트 프로바이더.
-
-- `alertThemes: WritableSignal<SdToastSeverity[]>` — 이 심각도는 토스트 대신 `window.alert` 로 표시.
-- `overlap: WritableSignal<boolean>` — true 면 새 토스트가 기존 토스트를 모두 치우고 겹쳐 표시.
-- `beforeShowFn?: (theme) => void` — 토스트 표시 직전 콜백.
-- `info/success/warning/danger(message, useProgress?)` — 심각도별 토스트. `useProgress: true` 면 `WritableSignal<number>`(0~100) 반환(100 도달 1초 후 자동 해제), 아니면 3초 후 자동 해제(호버 시 지연).
-- `notify<T>(input: SdToastInput<T>): Promise<결과|undefined>` — 커스텀 컴포넌트 토스트. `close` emit 값으로 resolve, 5초 후 자동 `undefined`.
-- `try<R>(fn, messageFn?): Promise<R|undefined>` — `fn` 실행, `Error` 발생 시 `danger` 토스트 + 시스템로그 후 `undefined` 반환(비-Error 는 rethrow). `messageFn` 으로 메시지 커스터마이즈.
-
-타입:
-- `SdToastSeverity` — `"info"|"success"|"warning"|"danger"`.
-- `SdToastTheme` — `"primary"|"secondary"|SdToastSeverity|"gray"|"blue-gray"`.
-- `SdToastContentDef<O>` — `{ close: OutputEmitterRef<O|undefined> }`. notify 콘텐츠 구현.
-- `SdToastInput<T>` — `{ type: Type<T>; inputs }`(`close` 제외 input).
-
-```typescript
-sdToast.danger("저장 실패");
-const progress = sdToast.info("업로드 중", true);
-progress.set(50);
-await sdToast.try(() => api.saveAsync());
+`@Injectable({providedIn:"root"})`. 토스트 알림.
+
+- info/success/warning/danger(message: string, useProgress?: boolean) — 심각도별 토스트. useProgress=true 면 진행률 토스트가 되어 `WritableSignal<number>`(0~100) 반환, 100 도달 1초 뒤 자동 해제. useProgress 없거나 false 면 3초 후 자동 해제(호버 중 지연), 반환 void.
+- notify<T>(input: SdToastInput<T>): Promise<close결과 | undefined> — 커스텀 컴포넌트 토스트. `SdToastInput<T>` = `{ type: Type<T>; inputs }`(컨텐츠는 `SdToastContentDef<O>` = `{ close: OutputEmitterRef<O|undefined> }` 구현). 5초 후 자동 해제.
+- try<R>(fn, messageFn?): Promise<R | undefined> — fn 실행 중 Error 발생 시 danger 토스트 + 시스템로그 기록 후 undefined 반환(Error 아닌 throw 는 재throw). 화면 액션 핸들러를 감싸는 표준 패턴.
+- alertThemes: WritableSignal<SdToastSeverity[]> — 이 심각도들은 토스트 대신 `window.alert`.
+- overlap: WritableSignal<boolean> — true 면 새 토스트가 기존 토스트 모두 제거 후 표시(겹침 방지).
+- beforeShowFn?: (theme) => void — 토스트 표시 직전 콜백(예: 사운드).
+
+타입: `SdToastSeverity = "info"|"success"|"warning"|"danger"`, `SdToastTheme = "primary"|"secondary"|SdToastSeverity|"gray"|"blue-gray"`.
+
+```ts
+await sdToast.try(async () => { await save(); sdToast.success("저장됨"); });
 ```
 
 ## SdToast / SdToastContainer
 
-- `<sd-toast>` — 개별 토스트. `open`/`progress`/`message` 는 `model`, `useProgress`/`theme` 는 input. theme 에 따라 `role`/`aria-live`(info·success=polite/status, warning·danger=assertive/alert) 자동.
-- `<sd-toast-container>` — 토스트 컨테이너. `overlap = input(false)` — 겹침 모드.
+`SdToastProvider` 가 내부 생성. 직접 쓸 일 드묾. SdToast: `open`/`progress`/`message` model, `useProgress`/`theme` input, severity 에 따라 `role`/`aria-live` 자동(info·success=status/polite, warning·danger=alert/assertive). SdToastContainer: `overlap` input.
 
-## SdBusyProvider / SdBusyContainer
+## SdBusyProvider
 
-전역·지역 로딩 표시.
+`@Injectable({providedIn:"root"})`. 전역 로딩 표시.
+- globalBusyCount: WritableSignal<number> — >0 이면 전역 busy 오버레이 표시(라우팅·인쇄가 자동 증감). 직접 작업 감쌀 때 update 로 증감.
+- type: WritableSignal<SdBusyType> — 기본 표시 유형. `SdBusyType = "spinner"|"bar"|"cube"`.
 
-- `SdBusyProvider` — `type: WritableSignal<SdBusyType>` 기본 스피너 종류, `globalBusyCount: WritableSignal<number>` 0 초과 시 전역 busy 오버레이 표시. 라우팅·인쇄가 자동 증감.
-- `SdBusyType` — `"spinner"|"bar"|"cube"`. 인디케이터 모양.
-- `<sd-busy-container>` — 지역 busy 래퍼. `busy = input(false)` 표시 여부, `message`/`type`(미지정 시 프로바이더 type 따름)/`progressPercent`(0~100 막대) input. busy 중 키입력 차단.
+## SdBusyContainer
 
-## SdPrintProvider
+`<sd-busy-container [busy]="..." />` — 영역 단위 busy 오버레이. 내부 컨텐츠 위에 표시.
+- busy: boolean — true 면 오버레이 표시 + 영역 내 키입력 차단.
+- message?: string — 표시 메시지.
+- type?: "spinner"|"bar"|"cube" — 미지정 시 `SdBusyProvider.type` 사용.
+- progressPercent?: number — 지정 시 상단 진행 바 표시(0~100).
 
-`class SdPrintProvider` — 컴포넌트를 인쇄하거나 PDF 버퍼로 만드는 루트 프로바이더. 진행 중 전역 busy 증가.
+## SdPrintProvider
 
-- `printAsync<T>(template: SdPrintInput<T>, options?: { size?: string; margin?: string }): Promise<void>` — 템플릿 컴포넌트를 body 에 부착·`@page` 스타일 주입 후 `window.print()`. 이미지 로드 대기.
-- `getPdfBufferAsync<T>(template, options?: { orientation?: "portrait"|"landscape"; pageSize?: string }): Promise<Uint8Array>` — `.page` 요소(없으면 전체)를 캔버스화해 jsPDF 로 PDF 버퍼 생성.
+`@Injectable({providedIn:"root"})`. 컴포넌트를 인쇄/PDF 로 렌더.
+- printAsync<T>(template: SdPrintInput<T>, options?: { size?: string; margin?: string }): Promise<void> — 컴포넌트를 body 에 임시 렌더 후 `window.print()`. size 기본 `"A4 auto"`, margin 기본 `"0"`. 인쇄 동안 글로벌 busy.
+- getPdfBufferAsync<T>(template, options?: { orientation?: "portrait"|"landscape"; pageSize?: string }): Promise<Uint8Array> — `.page` 엘리먼트별로 캔버스 변환(jsPDF) 후 PDF 버퍼 반환. pageSize 기본 `"a4"`, orientation 기본 portrait.
 
-타입:
-- `SdPrint` — `{ initialized: Signal<boolean>; _optionalPrintInputs?: string }`. 인쇄 콘텐츠 구현.
-- `SdPrintInput<T, X>` — `{ type: Type<T>; inputs }`(`_optionalPrintInputs` 키는 optional).
+`SdPrintInput<T, X>` = `{ type: Type<T>; inputs }`. 컨텐츠는 `SdPrint`(= `{ initialized: Signal<boolean>; _optionalPrintInputs?: string }`) 구현. `initialized()` 가 true 가 되고 이미지 로드 완료까지 대기 후 인쇄.