@simplysm/sd-claude 14.0.89 → 14.0.91

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

@@ -1,103 +1,103 @@
-# @simplysm/angular — 모달·토스트·Busy·인쇄 (오버레이)
+# @simplysm/angular — 모달·토스트·Busy·인쇄 (오버레이/전역 피드백)
 
-화면 위에 띄우는 피드백·오버레이 묶음. 프로그래밍 방식으로 모달/토스트를 띄우거나 작업 진행 표시, 화면 인쇄/PDF 가 필요할 때 함께 읽힘.
+화면에서 프로그래밍 방식으로 모달을 띄우거나, 토스트로 알림·진행률을 표시하거나, busy 인디케이터·인쇄/PDF 출력을 호출할 때 함께 읽히는 군. provider 는 모두 `providedIn: "root"`, 컴포넌트는 provider 가 동적으로 body 에 attach 하므로 템플릿에 직접 둘 일은 거의 없음.
 
 ## SdModalProvider
 
-`@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 — 첫 컨트롤 자동 포커스 비활성(다이얼로그 자체에 포커스).
+컴포넌트를 모달 셸(`SdModal`) 안에 동적 생성해 body 에 띄움. `close.emit(payload)` 또는 닫기(X/배경/ESC)로 종료.
 
 ```ts
-const result = await sdModal.showAsync(
-  { title: "사용자 선택", type: UserSelectModal, inputs: { teamId } },
-  { resizable: true, key: "user-select" },
-);
+showAsync<T extends SdModalContentDef<any>>(
+  modal: SdModalInfo<T>, options?: SdModalOptions,
+): Promise<Parameters<T["close"]["emit"]>[0] | undefined>
 ```
 
-## SdModal
+- `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>` — 현재 열린 모달 수.
 
-`<sd-modal>` — `SdModalProvider` 가 내부적으로 생성하는 셸 컴포넌트. 직접 템플릿에 쓰기보다 provider 경유 권장. 위 `SdModalOptions` 와 동일한 input 들 + `open = model(false)`, `closeRequest = output<void>()`, `title`/`actionTplRef` input 보유.
+### SdModalContentDef<O> (모달 컴포넌트가 구현)
 
-## SdActivatedModalProvider
+- `initialized: Signal<boolean>` — 초기화 완료 여부. busy 표시 해제 기준.
+- `close: OutputEmitterRef<O | undefined>` — 결과 emit. `O` 가 `showAsync` 반환 타입.
+- `actionTplRef?: TemplateRef<any>` — 헤더 우측에 끼울 액션 영역 템플릿(있으면 모달 헤더로 브릿지됨).
+- `_optionalModalInputs?: string` — (타입 전용 마커) 이 컴포넌트의 input 중 optional 로 둘 키 이름 리터럴. 런타임 값 아님.
 
-모달 컨텐츠 컴포넌트 내부에서 inject. 현재 모달 제어.
-- modalComponent: Signal<SdModal | undefined> / contentComponent: Signal<T | undefined>.
-- canDeactivateFn: () => boolean — 닫기 차단 판정. `setupCanDeactivate` 가 설정. true 가 아니면 배경/ESC/버튼 닫기 무시.
+### SdModalOptions (showAsync 2번째 인자)
 
-## SdPromptModal / SdConfirmModal
+- `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 면 첫 입력 요소 자동 포커스를 끔(다이얼로그 자체에 포커스).
 
-provider 에 바로 넘길 수 있는 범용 모달 컴포넌트.
-- SdPromptModal: `SdModalContentDef<string>`. `message = input.required<string>()`. 텍스트 입력(필수) 후 확인 시 입력값, 취소 시 undefined emit.
-- SdConfirmModal: `SdModalContentDef<boolean>`. `message = input.required<string>()`. 확인 시 `true`, 취소 시 undefined emit.
+### 내장 모달 컴포넌트
 
-```ts
-const name = await sdModal.showAsync({ title: "이름", type: SdPromptModal, inputs: { message: "이름?" } });
-```
+- `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;`.
 
-## SdToastProvider
+### SdActivatedModalProvider
 
-`@Injectable({providedIn:"root"})`. 토스트 알림.
+모달 컴포넌트 내부에서 inject. 자기 모달의 셸/콘텐츠 참조와 이탈 가드를 보유.
 
-- 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 — 토스트 표시 직전 콜백(예: 사운드).
+- `modalComponent: Signal<SdModal | undefined>` / `contentComponent: Signal<T | undefined>` — 셸/콘텐츠 컴포넌트 참조.
+- `canDeactivateFn: () => boolean` — 닫기 시도 시 false 면 닫힘 차단. `setupCanDeactivate`(routing-appstructure.md) 가 모달 컨텍스트에서 이걸 설정.
 
-타입: `SdToastSeverity = "info"|"success"|"warning"|"danger"`, `SdToastTheme = "primary"|"secondary"|SdToastSeverity|"gray"|"blue-gray"`.
+### SdModal (모달 셸)
 
-```ts
-await sdToast.try(async () => { await save(); sdToast.success("저장됨"); });
-```
+`SdModalProvider` 가 내부적으로 생성하는 셸 컴포넌트. 상속·직접 배치 대상 아님. `<ng-content>` 로 콘텐츠를 투영하고 위 `SdModalOptions` 와 동일한 input(`title`/`open`/`resizable`/... `closeRequest` output) 을 보유.
+
+## SdToastProvider
+
+화면 우상단(또는 overlap 모드)에 토스트를 띄움. 알림·비동기 에러 가드·진행률에 사용.
+
+- `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` — 토스트 표시 직전 콜백(사운드 등).
 
-## SdToast / SdToastContainer
+타입:
 
-`SdToastProvider` 가 내부 생성. 직접 쓸 일 드묾. SdToast: `open`/`progress`/`message` model, `useProgress`/`theme` input, severity 에 따라 `role`/`aria-live` 자동(info·success=status/polite, warning·danger=alert/assertive). SdToastContainer: `overlap` input.
+- `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"> }`.
 
-## SdBusyProvider
+`SdToast`/`SdToastContainer` 는 provider 가 동적 생성하는 표시 컴포넌트(직접 배치 불필요).
 
-`@Injectable({providedIn:"root"})`. 전역 로딩 표시.
-- globalBusyCount: WritableSignal<number> — >0 이면 전역 busy 오버레이 표시(라우팅·인쇄가 자동 증감). 직접 작업 감쌀 때 update 로 증감.
-- type: WritableSignal<SdBusyType> — 기본 표시 유형. `SdBusyType = "spinner"|"bar"|"cube"`.
+## SdBusyProvider / SdBusyContainer
 
-## SdBusyContainer
+영역 단위 busy 오버레이.
 
-`<sd-busy-container [busy]="..." />` — 영역 단위 busy 오버레이. 내부 컨텐츠 위에 표시.
-- busy: boolean — true 면 오버레이 표시 + 영역 내 키입력 차단.
-- message?: string — 표시 메시지.
-- type?: "spinner"|"bar"|"cube" — 미지정 시 `SdBusyProvider.type` 사용.
-- progressPercent?: number — 지정 시 상단 진행 바 표시(0~100).
+- `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` 가 이미 내장).
 
 ## SdPrintProvider
 
-`@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.
+인쇄 템플릿 컴포넌트를 동적 생성해 `window.print()` 하거나 PDF 버퍼로 변환. 호출 동안 `globalBusyCount` ±1.
 
-`SdPrintInput<T, X>` = `{ type: Type<T>; inputs }`. 컨텐츠는 `SdPrint`(= `{ initialized: Signal<boolean>; _optionalPrintInputs?: string }`) 구현. `initialized()` 가 true 가 되고 이미지 로드 완료까지 대기 후 인쇄.
+- `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).

package/claude/references/sd-simplysm14/apis/angular/routing-appstructure.md

@@ -1,69 +1,79 @@
 # @simplysm/angular — 라우팅 / 앱 구조(메뉴·권한)
 
-현재 페이지 식별·뷰 제목/타입 판정, 라우터 링크, 앱 메뉴/권한 트리 구성을 다룰 때 함께 읽힘. 앱 구조 데이터 원본은 `@simplysm/service-common` 의 `AppStructureItem`.
+라우터 링크·현재 페이지 식별·뷰 컨텍스트(page/control/modal)·이탈 가드, 그리고 앱 구조 트리에서 메뉴·권한을 파생하는 군. 화면 컴포넌트의 표준 시그널 `viewType`, 권한 가드 `injectPermsSignal`, 사이드바/탑바 메뉴가 이 군에 의존.
 
-## injectFullPageCodeSignal
+## injectViewTypeSignal / SdViewType
 
-`injectFullPageCodeSignal(): Signal<string>` — 현재 라우터 URL 에서 앞 2 세그먼트(`/home` 등)를 제외한 나머지를 `.` 으로 이은 페이지 코드. 네비게이션 종료마다 갱신. 메뉴 선택 표시·뷰 제목 조회에 사용.
-
-## injectCurrentPageCodeSignal
+```ts
+function injectViewTypeSignal(): Signal<SdViewType>
+type SdViewType = "page" | "modal" | "control"
+```
 
-`injectCurrentPageCodeSignal(): Signal<string> | undefined` — 현재 `ActivatedRoute` 의 pathFromRoot 기준 코드(중첩 outlet/모달 안에서 자기 자신 경로). ActivatedRoute 없으면 undefined. fullPageCode 와 비교해 page/control 판정에 사용.
+현재 컴포넌트가 어느 컨텍스트에서 동작 중인지 판정하는 signal. `"page"` = 라우팅 진입 화면, `"modal"` = 모달로 열림, `"control"` = 다른 화면 안에 임베드된 자식. 판정 기준: 모달 컨텍스트면 modal, 라우트 컴포넌트의 selector 가 현재 엘리먼트 태그와 일치하고 full/current 페이지 코드가 같으면 page, 그 외 control. 매뉴얼 표준 시그널 `viewType = injectViewTypeSignal()` 로 받아 `sd-base-container [viewType]` 에 전달.
 
 ## injectViewTitleSignal
 
-`injectViewTitleSignal(): Signal<string>` — 모달 안이면 모달 제목, 아니면 앱 구조에서 현재 페이지 코드로 찾은 제목(`[상위 > 상위] 현재`). 못 찾으면 `""`. 화면 컨테이너 제목 표시에 사용.
+- `function injectViewTitleSignal(): Signal<string>` — 현재 뷰의 표시 제목. 모달이면 모달 컴포넌트 `title`, 아니면 앱 구조에서 현재 페이지 코드로 찾은 제목(`[상위 > 경로] 현재`). 못 찾으면 `""`. `sd-base-container` 가 page 탑바 제목에 사용.
 
-## injectViewTypeSignal
+## injectFullPageCodeSignal / injectCurrentPageCodeSignal
 
-`injectViewTypeSignal(): Signal<SdViewType>` — 현재 컴포넌트가 어떤 맥락으로 떠 있는지 판정. `SdViewType = "page"|"modal"|"control"`. 모달 안이면 "page"가 아닌 "modal", 라우트의 페이지 컴포넌트로 직접 떠 있고 fullPageCode===currPageCode 면 "page", 그 외 "control"(다른 화면에 박힌 재사용 컴포넌트). CRUD 컨테이너의 `viewType` input 에 그대로 전달.
+- `function injectFullPageCodeSignal(): Signal<string>` — 라우터 URL 전체에서 파생한 페이지 코드(`/` → `.` 로 합침, 앞 2세그먼트 제외, `;`/`?` 이후 제거). 메뉴 선택 상태·뷰 타입 판정에 사용.
+- `function injectCurrentPageCodeSignal(): Signal<string> | undefined` — 현재 `ActivatedRoute` 기준 상대 페이지 코드. 라우트 컨텍스트 없으면 `undefined`. 중첩 라우트에서 자기 위치 코드가 필요할 때.
 
 ## setupCanDeactivate
 
-`setupCanDeactivate(fn: () => boolean): void` — 컴포넌트 내 호출. 모달 안이면 `SdActivatedModalProvider.canDeactivateFn` 에, 라우트면 해당 route 의 `canDeactivate` 가드에 fn 을 등록(컴포넌트 파괴 시 해제). fn 이 false 면 이탈/닫기 차단. 미저장 변경 보호에 사용.
+- `function setupCanDeactivate(fn: () => boolean): void` — 라우터 이탈/모달 닫기 시점에 `fn()` 이 false 면 이탈/닫기를 차단. 모달 컨텍스트면 `SdActivatedModalProvider.canDeactivateFn` 에, 라우트 컨텍스트면 해당 route 의 `canDeactivate` 에 등록(파괴 시 자동 해제). detail 화면의 변경 가드 표준: `setupCanDeactivate(() => this._checkIgnoreChanges())`(client-component.md).
 
-```ts
-setupCanDeactivate(() => !this.dirty() || confirm("저장하지 않고 나갈까요?"));
-```
+## SdRouterLink (`[sdRouterLink]`)
 
-## SdRouterLink
+라우터 이동을 호스트 클릭에 붙이는 디렉티브. Ctrl/Shift 클릭·window 모드면 새 창/탭으로 분기.
 
-`[sdRouterLink]="option"` 디렉티브. 클릭 시 option 으로 라우터 이동(또는 새 창).
-- option: `{ link: string; params?; window?: {width?;height?}; outletName?: string; queryParams? } | undefined` — undefined 면 동작 없음(커서도 기본). 현재가 window 모드거나 Ctrl/Shift+클릭이면 새 창으로, outletName 있으면 named outlet 으로 이동. Alt+클릭은 무시.
+- `sdRouterLink: { link: string; params?: Record<string,string>; window?: { width?; height? }; outletName?: string; queryParams?: Record<string,string> } | undefined` — 이동 옵션.
+  - `link` — 라우트 경로. `outletName` 있으면 named outlet 이동.
+  - `params` — 매트릭스 파라미터, `queryParams` — 쿼리 파라미터.
+  - `window` — Ctrl/Shift 클릭 또는 window 컨텍스트일 때 팝업 창 크기(기본 800x800).
+  - 미지정(`undefined`) 이면 클릭 무시 + 커서 기본. 메뉴 항목이 leaf 가 아닐 때 등.
+- Alt+클릭은 무시. 사이드바/탑바 메뉴가 `getMenuRouterLinkOption(menu)` 결과를 이 입력에 바인딩.
 
 ## SdNavigateWindowProvider
 
-`@Injectable({providedIn:"root"})`. 새 창/팝업 네비게이션.
-- isWindow: boolean — 현재 URL 해시에 `window=true` 가 있는지(팝업으로 열린 창인지).
-- open(navigate: string, params?, features?): void — window 모드거나 features 지정 시 `window.open` 팝업(닫힐 때 부모와 함께 정리), 아니면 `_blank` 탭.
+- `isWindow: boolean` — 현재 문서가 `window=true` 로 열린 팝업인지(해시 파라미터 검사).
+- `open(navigate: string, params?: Record<string,string>, features?: string): void` — 새 창/탭으로 라우트 열기. window 컨텍스트이거나 `features` 가 있으면 `window=true` 팝업으로(부모 unload 시 자동 close), 아니면 `_blank` 탭으로. `SdRouterLink` 내부 + 화면에서 보조 창을 띄울 때.
 
-## getMenuRouterLinkOption / getIsMenuSelected
+## SdAppStructureProvider<TModule> / injectPermsSignal
+
+앱 구조 트리(`AppStructureItem[]`, `@simplysm/service-common`)에서 메뉴·권한을 파생하는 root provider. 화면은 보통 `injectPermsSignal` 만 직접 씀.
+
+```ts
+function injectPermsSignal<K extends string>(viewCodes: string[], keys: K[]): Signal<K[]>
+```
 
-- `getMenuRouterLinkOption(menu: SdMenu): { link; queryParams } | undefined` — leaf 메뉴(children/url 없음)면 `/home/<코드체인>` 링크 + 쿼리파라미터 옵션, 그 외 undefined. `SdRouterLink` 에 바로 전달.
-- `getIsMenuSelected(menu, fullPageCode, customFn?): boolean` — customFn 있으면 그 결과, 없으면 `fullPageCode === menu.codeChain.join(".")`. 메뉴 선택 강조에 사용.
+- `viewCodes` — 권한 path 목록(도메인 트리 좌표). `keys` — 확인할 action 목록. 반환 signal 은 사용자가 보유한 action 들의 배열. 매뉴얼 패턴: `perms = injectPermsSignal(["inventory.outbound"], ["use","edit"])` → `this.perms().includes("use")` 인라인 가드.
+- provider 멤버:
+  - `usableModules: WritableSignal<TModule[] | undefined>` / `permRecord: WritableSignal<Record<string, boolean> | undefined>` — 인증 후 주입하는 활성 모듈·권한 레코드. 메뉴/권한 계산의 입력.
+  - `items: WritableSignal<AppStructureItem<TModule>[]>` / `initialize(items): void` — 앱 구조 트리 세팅.
+  - `usableMenus: Signal<SdMenu[]>` — 권한·모듈 필터를 적용한 트리형 메뉴(사이드바용).
+  - `usableFlatMenus: Signal<SdFlatMenu<TModule>[]>` — 평탄화된 메뉴 목록(검색/전체메뉴용).
+  - `getPermsByFullCode<K>(fullCodes, permKeys): K[]` — 코드 목록에 대해 보유 action 계산(`injectPermsSignal` 내부). 권한 정의 자체가 없는 항목은 모든 action 허용으로 간주.
+  - `getPermissionsByStructure(items, codeChain?)` — 권한표(`sd-permission-table`)용 `SdPermission` 트리 생성.
+  - `findTitleByFullCode(fullCode): string | undefined` / `getTitleByFullCode(fullCode): string`(못 찾으면 throw) / `getItemChainByFullCode(fullCode)` — 코드로 제목·항목 체인 조회.
 
-## SdAppStructureProvider<TModule>
+## SdAppStructureUtils (static 유틸)
 
-`@Injectable({providedIn:"root"})`. 앱 메뉴·권한 트리의 단일 소스.
-- usableModules: Signal<TModule[]|undefined> — 활성 모듈 목록. 메뉴/권한 필터에 사용(미설정 시 전체 허용 취급).
-- permRecord: Signal<Record<string,boolean>|undefined> — `<코드>.<권한키>` → 허용 여부 맵.
-- items: Signal<AppStructureItem<TModule>[]> — 구조 원본.
-- initialize(items) — 구조 주입.
-- usableMenus: Signal<SdMenu[]> — 모듈·권한 통과한 메뉴 트리(사이드바/탑바용).
-- usableFlatMenus: Signal<SdFlatMenu<TModule>[]> — 평탄화된 메뉴 목록.
-- getPermissionsByStructure(items, codeChain?) — 권한 편집표용 `SdPermission` 트리 생성.
-- getTitleByFullCode(fullCode) / findTitleByFullCode(fullCode) — 전자는 못 찾으면 throw, 후자는 undefined(결측 보존).
-- getItemChainByFullCode(fullCode) — 코드 체인에 해당하는 항목 배열(없으면 빈 배열).
-- getPermsByFullCode(fullCodes, permKeys) — 해당 코드들에서 보유한 권한 키 목록.
+`SdAppStructureProvider` 가 내부적으로 쓰는 순수 함수 모음(abstract 클래스의 static). 트리 → 메뉴/권한/제목 변환을 provider 밖에서 직접 할 때만 사용.
 
-`injectPermsSignal<K>(viewCodes: string[], keys: K[]): Signal<K[]>` — 현재 보유 권한 키를 computed signal 로. 화면에서 편집/사용 권한 분기에 사용.
+- `getMenus(items, codeChain, usableModules, permRecord): SdMenu[]` — 모듈·`use` 권한 필터 적용 트리 메뉴. `isNotMenu` 항목·빈 그룹 제외.
+- `getFlatMenus(items, usableModules, permRecord): SdFlatMenu[]` — BFS 평탄화 메뉴.
+- `getPermissions(items, codeChain, usableModules): SdPermission[]` — 권한표용 트리(leaf 의 `perms`/`subPerms` 포함).
+- `getFlatPermissions(items, usableModules)` / `findTitleByFullCode` / `getTitleByFullCode` / `getItemChainByFullCode` / `getPermsByFullCode` — provider 동명 메서드의 구현.
 
-## SdAppStructureUtils
+## menu-utils
 
-`abstract class`. `SdAppStructureProvider` 가 내부 사용하는 정적 유틸 모음(직접 호출 가능): `getMenus`/`getFlatMenus`/`getPermissions`/`getFlatPermissions`/`getTitleByFullCode`/`findTitleByFullCode`/`getItemChainByFullCode`/`getPermsByFullCode`. 시그니처는 provider 메서드와 대응(추가로 items/usableModules/permRecord 를 인자로 받음).
+- `getMenuRouterLinkOption(menu: SdMenu): { link: string; queryParams: Record<string,string> | undefined } | undefined` — 메뉴를 `sdRouterLink` 옵션으로 변환. children 이 있거나 `url`(외부 링크) 이면 `undefined`(이동 불가 = leaf 아님). 그 외 `codeChain` 으로 `/home/<코드/...>` 링크 + 쿼리 분리.
+- `getIsMenuSelected(menu: SdMenu, fullPageCode: string | undefined, customFn?: (menu) => boolean): boolean` — 메뉴 선택 여부. `customFn` 있으면 위임, 없으면 `fullPageCode === menu.codeChain.join(".")`.
 
 ## 타입
 
-- **SdMenu** — `{ title; codeChain: string[]; url?; icon?; children?: SdMenu[] }`. 메뉴 트리 노드.
-- **SdFlatMenu<TModule>** — `{ titleChain: string[]; codeChain: string[]; modulesChain: TModule[][] }`. 평탄 메뉴.
-- **SdPermission<TModule>** — `{ title; codeChain; modules; perms: ("use"|"edit")[]|undefined; children }`. 권한 트리 노드(권한표 입력).
+- `SdMenu = { title; codeChain: string[]; url?; icon?; children?: SdMenu[] }` — 트리 메뉴 항목. `url` 있으면 외부 링크, `children` 있으면 그룹.
+- `SdFlatMenu<TModule> = { titleChain: string[]; codeChain: string[]; modulesChain: TModule[][] }` — 평탄 메뉴(경로 누적).
+- `SdPermission<TModule> = { title; codeChain; modules; perms: ("use"|"edit")[] | undefined; children }` — 권한표 노드. `perms` 가 undefined 면 그룹(권한 없음). `sd-permission-table` 의 `items` 입력 타입.

package/claude/references/sd-simplysm14/apis/angular/selection-managers.md

@@ -1,28 +1,68 @@
-# @simplysm/angular — 선택·정렬·확장 매니저(use* 컴포저블)
+# @simplysm/angular — selection/sorting/expanding 매니저 (use* 컴포저블)
 
-커스텀 리스트/그리드 컴포넌트에 선택·정렬·트리 확장 로직을 붙이는 함수형 컴포저블. signal 바인딩을 넘기면 파생 signal 과 조작 메서드를 돌려줌. `sd-sheet` 가 내부적으로 이들을 조합함.
+커스텀 목록 컴포넌트에서 선택·정렬·트리펼침 상태 로직을 signal 기반으로 합성하는 함수 컴포저블 군. `sd-sheet` 가 이들을 조합해 만들어졌고, 직접 그리드/리스트를 만들 때 같은 로직을 재사용. 모두 함수 호출로 signal·메서드 묶음을 반환(컴포넌트 필드에 보관).
 
 ## useSelectionManager<TItem, TKey>
 
-다중/단일 선택 상태 관리.
-- options: `{ displayItems: Signal<TItem[]>; selectedKeys: WritableSignal<TKey[]>; selectMode: Signal<"single"|"multi"|undefined>; getItemSelectableFn: Signal<((item) => boolean|string)|undefined>; trackByFn: Signal<(item,index) => TKey> }` — selectMode 미지정이면 선택 비활성, getItemSelectableFn 이 string 반환 시 그 사유로 불가, trackByFn 으로 키 비교(`obj.equal` 깊은 비교).
-- 반환: `hasSelectable`/`isAllSelected`(Signal), `getSelectable(item): true|string|undefined`, `getCanChangeFn(item)`, `select`/`deselect`/`toggle`/`toggleAll`/`isSelected`. single 은 1개로 교체, multi 는 누적.
+행 선택(single/multi)·전체선택·선택 가능 여부 로직.
+
+```ts
+useSelectionManager<TItem, TKey>(options: {
+  displayItems: Signal<TItem[]>;
+  selectedKeys: WritableSignal<TKey[]>;
+  selectMode: Signal<"single" | "multi" | undefined>;
+  getItemSelectableFn: Signal<((item: TItem) => boolean | string) | undefined>;
+  trackByFn: Signal<(item: TItem, index: number) => TKey>;
+}): { ... }
+```
+
+- `options.displayItems` — 현재 표시 항목. `selectedKeys` — 선택 키(WritableSignal, 키는 `trackByFn` 반환값). `selectMode` — 모드(undefined 면 선택 비활성). `getItemSelectableFn` — 행별 선택 가능: `true`=가능, `false`=불가, 문자열=불가+사유. `trackByFn` — 항목→키.
+- 반환:
+  - `hasSelectable: Signal<boolean>` — 선택 모드가 켜졌는지.
+  - `isAllSelected: Signal<boolean>` — 선택 가능한 항목이 모두 선택됐는지(전체선택 체크 상태).
+  - `getSelectable(item): true | string | undefined` — 항목 선택 가능 여부(문자열=사유 툴팁).
+  - `getCanChangeFn(item): () => boolean` — 체크박스 `canChangeFn` 에 넘길 가드.
+  - `select`/`deselect`/`toggle(item)` — 선택 조작(single 은 단일 키로 대체).
+  - `toggleAll()` — 선택 가능 항목 전체 토글.
+  - `isSelected(item): boolean`.
+- 키 비교는 `===` 후 `obj.equal`(복합 키 지원).
 
 ## useSortingManager
 
-헤더 클릭 정렬 상태 + 정렬 실행.
-- options: `{ sorts: WritableSignal<SortingDef[]> }`.
-- 반환: `defMap: Signal<Map<key, { indexText?; desc }>>`(다중 정렬 시 순번 표시), `toggle(key, multiple)`(단일/다중 토글: 없음→오름차순→내림차순→해제 순환), `sort<T>(items): T[]`(null 은 앞, 문자열 localeCompare, 숫자 차이 기준).
-- **SortingDef** — `{ key: string; desc: boolean }`. 정렬 1건.
+정렬 상태(다중 컬럼) 토글·적용. `sd-sheet` 의 `sorts` 와 `SortingDef` 를 공유.
+
+```ts
+useSortingManager(options: { sorts: WritableSignal<SortingDef[]> }): {
+  defMap: Signal<Map<string, { indexText?: string; desc: boolean }>>;
+  toggle(key: string, multiple: boolean): void;
+  sort<T>(items: T[]): T[];
+}
+```
+
+- `SortingDef = { key: string; desc: boolean }` — 한 정렬 기준. `key`=컬럼 키, `desc`=내림차순 여부.
+- `defMap` — 키별 정렬 상태(헤더 아이콘 표시용; `indexText` 는 다중 정렬 시 순번).
+- `toggle(key, multiple)` — 정렬 토글. 한 키를 누를 때마다 없음→오름차순→내림차순→해제 순환. `multiple`(Shift) true 면 기존 정렬 유지하고 추가, false 면 단일 정렬로 대체.
+- `sort<T>(items)` — 현재 정렬을 적용한 새 배열 반환. null 은 가장 앞, 문자열은 localeCompare, 숫자는 수치 비교. 클라이언트 정렬 시 사용.
 
 ## useExpandingManager<T>
 
-트리 펼침 상태 + 가시 항목 평탄화.
-- binding: `{ items: Signal<T[]>; expandedItems: WritableSignal<T[]>; getChildrenFn: Signal<((item,index) => T[]|undefined)|undefined>; sort: (items) => T[] }` — getChildrenFn 으로 자식 조회, sort 로 각 레벨 정렬.
-- 반환: `displayItems`/`hasExpandable`/`isAllExpanded`(Signal), `toggle(item)`/`toggleAll()`, `isVisible(item)`(조상이 모두 펼쳐졌는지), `def(item): ExpandItemDef<T>`(못 찾으면 throw).
-- **ExpandItemDef<T>** — `{ item; parentDef: ExpandItemDef<T>|undefined; hasChildren; depth }`. 항목의 트리 위치 정의.
+트리 항목 펼침/접힘 + 표시 항목 평탄화.
 
 ```ts
-const sorting = useSortingManager({ sorts });
-const selection = useSelectionManager({ displayItems, selectedKeys, selectMode, getItemSelectableFn, trackByFn });
+useExpandingManager<T>(binding: {
+  items: Signal<T[]>;
+  expandedItems: WritableSignal<T[]>;
+  getChildrenFn: Signal<((item: T, index: number) => T[] | undefined) | undefined>;
+  sort: (items: T[]) => T[];
+}): { ... }
 ```
+
+- `binding.items` — 루트 항목. `expandedItems` — 펼쳐진 항목(WritableSignal). `getChildrenFn` — 자식 조회(undefined 면 자식 없음). `sort` — 각 레벨 정렬 함수(보통 `useSortingManager.sort`).
+- 반환:
+  - `displayItems: Signal<T[]>` — 펼침 상태를 반영해 평탄화·정렬된 표시 항목.
+  - `hasExpandable: Signal<boolean>` — 펼칠 수 있는 항목이 있는지(토글 컬럼 표시 기준).
+  - `isAllExpanded: Signal<boolean>` — 전체 펼침 상태.
+  - `toggle(item)` / `toggleAll()` — 펼침 토글.
+  - `isVisible(item): boolean` — 조상이 모두 펼쳐져 보이는지.
+  - `def(item): ExpandItemDef<T>` — 항목 메타(못 찾으면 throw).
+- `ExpandItemDef<T> = { item: T; parentDef: ExpandItemDef<T> | undefined; hasChildren: boolean; depth: number }` — 항목의 부모·자식유무·깊이. 들여쓰기·토글 렌더에 사용.

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

@@ -1,57 +1,74 @@
-# @simplysm/angular — 공유 데이터(shared-data)
+# @simplysm/angular — 공유 마스터 데이터 + 선택 컨트롤
 
-서버의 마스터 데이터(코드·거래처 등)를 클라이언트 전역에서 캐시·구독하고, 그 데이터를 고른 select/list/button UI 로 노출하는 묶음. 데이터 변경은 서비스 이벤트로 전파되어 자동 갱신됨.
+고객사·품목 등 자주 참조하는 마스터 데이터를 한 번 등록해 어느 화면에서든 공유 signal 로 쓰고, 그 데이터를 선택하는 드롭다운/버튼/리스트 컨트롤을 제공하는 군. 등록·항목 추가 절차는 `client-shared-data.md` 참조.
 
-## 데이터 규약 타입
+## SdSharedDataProvider<T> (abstract)
 
-- **SharedDataBase<TKey>** — 공유 데이터 항목의 베이스. `{ __valueKey: TKey; __searchText: string; __isHidden: boolean; __parentKey?: TKey }`. `__searchText` 로 검색, `__isHidden` 으로 목록 숨김, `__parentKey` 있으면 트리 구성. 도메인 타입이 이 인터페이스를 확장.
-- **SharedDataInfo<T>** — 등록 정보. `{ serviceKey: string; getter: (changeKeys?) => Promise<T[]>; filter?: unknown; orderBy?: (item) => 비교키 }`. getter 는 전체/부분(changeKeys) 로드, filter 는 이벤트 매칭, orderBy 는 정렬키.
-- **SharedDataHandle<T>** — `{ items: Signal<T[]>; get(key): T | undefined }`. 화면에서 데이터 소비 핸들.
+마스터 데이터를 이름별로 등록·로드·이벤트 동기화하는 root provider. 앱은 이걸 상속한 `AppSharedDataProvider` 를 만들고 `useSharedSignal` 헬퍼를 함께 export(client-shared-data.md).
 
-## SdSharedDataProvider<T>
+- `abstract initialize(): void` — 여기서 `register(name, info)` 로 항목 등록(앱이 구현).
+- `register<K>(name: K, info: SharedDataInfo<T[K]>): void` — 항목 등록. 재호출 시 기존 리스너 정리 + generation 증가로 이전 결과 무시 후 재로드.
+- `getHandle<K>(name: K): SharedDataHandle<T[K]>` — 항목 핸들 반환(첫 접근 시 lazy 로드 + 변경 이벤트 리스너 등록). 미등록 이름이면 throw. `useSharedSignal` 이 이걸 감쌈.
+- `emitAsync<K>(name: K, changeKeys?: (string|number)[]): Promise<void>` — 변경 브로드캐스트. `changeKeys` 주면 해당 키만 부분 갱신, 없으면 전체 리로드(다른 클라이언트 포함).
+- `wait(): Promise<void>` — 진행 중 로드가 끝날 때까지 대기. `sd-base-container` 가 ready 전에 호출.
+- `loadingCount: WritableSignal<number>` — 진행 중 로드 수.
 
-`@Injectable()` abstract. 앱별로 상속해 `initialize()` 구현. T 는 `{ name: SharedDataBase 파생 }` 맵.
-- loadingCount: WritableSignal<number> — 로딩 중 카운트.
-- abstract initialize(): void — 앱 시작 시 각 데이터 register.
-- register<K>(name, info: SharedDataInfo<T[K]>) — 데이터 등록(재호출 시 generation 증가로 이전 이벤트 무시·재로드).
-- getHandle<K>(name): SharedDataHandle<T[K]> — 핸들 획득(첫 호출 시 lazy 로드 + 이벤트 리스너 등록). 미등록이면 throw.
-- emitAsync<K>(name, changeKeys?) — 변경 이벤트 발행(같은 name·filter 구독자 갱신). changeKeys 지정 시 부분 갱신.
-- wait(): Promise<void> — loadingCount 가 0 이 될 때까지 대기(화면 진입 전 데이터 준비).
+### 타입
 
-**SdSharedDataChangeEvent** — `defineEvent` 로 정의된 서비스 이벤트(`{ name; filter }`, 페이로드 `(string|number)[] | undefined`). provider 가 내부 사용.
+- `SharedDataBase<TKey extends string|number>` — 모든 공유 항목이 상속할 베이스. 매직 필드: `__valueKey: TKey`(항목 키), `__searchText: string`(검색용 텍스트), `__isHidden: boolean`(숨김), `__parentKey?: TKey`(트리 부모). getter 의 select 결과에 빠짐없이 포함.
+- `SharedDataInfo<T>` — 등록 정보. `serviceKey: string`(이벤트 채널), `getter: (changeKeys?) => Promise<T[]>`(조회; changeKeys 주면 부분), `filter?: unknown`(이벤트 필터 매칭), `orderBy?: (item) => string|number|DateOnly|DateTime|Time|undefined`(정렬 키).
+- `SharedDataHandle<T>` — `{ items: Signal<T[]>; get(key): T | undefined }`. 화면이 `useSharedSignal(name)` 으로 받아 `.items()`·`.get(id)` 사용.
+- `SdSharedDataChangeEvent` — 변경 동기화에 쓰이는 `defineEvent`. payload `{ name; filter }`, data `(string|number)[] | undefined`.
 
-## SdSharedDataSelect<TItem, TMode, TModal>
+사용(화면): `sharedCustomers = useSharedSignal("고객사"); sharedCustomers.items(); sharedCustomers.get(id)`.
 
-`<sd-shared-data-select [items]="...">` — 공유 데이터 드롭다운 선택(검색·트리·모달 연동).
-- value = model<...>() — 선택값(single=키, multi=키 배열). 키는 `TItem["__valueKey"] | undefined`.
-- items: input.required<TItem[]> — 후보(보통 handle.items()).
-- selectMode: "single"|"multi"(기본 single).
-- disabled/required/inset/inline/size — 컨트롤 공통.
-- useUndefined: boolean — multi 에서도 "미지정" 항목 노출.
-- filterFn?/filterFnParams? — 후보 필터(item,index,...params).
-- modal?: SdSelectModalInfo — 우측 검색 버튼으로 띄울 선택 모달.
-- editModal?: SdModalInfo<SdModalContentDef<boolean>> — 편집 버튼으로 띄울 모달.
-- selectClass?/multiSelectionDisplayDirection?("vertical").
-- getIsHiddenFn?(item,index)/getSearchTextFn?(item,index)/displayOrderByFn?(item) — 기본은 `__isHidden`/`__searchText`/없음. 검색·표시·정렬 재정의.
-- (contentChild) `itemOf` 템플릿 — 항목 렌더. `undefinedTpl` 로 "미지정" 표시 커스텀.
-- `__parentKey` 있으면 자동 트리(자식은 부모 펼침 시 노출).
+## 선택 컨트롤
 
-## SdSharedDataSelectButton<TItem, TMode, TModal>
+공유 데이터(또는 `SharedDataBase` 호환 배열)를 항목으로 받아 선택. 매직 필드(`__searchText`/`__isHidden`/`__parentKey`)를 자동 활용(검색·숨김·트리).
 
-`<sd-shared-data-select-button [modal]="...">` — 모달 선택 버튼 + 선택 항목 인라인 표시(`SdModalSelectButton` 래퍼).
-- value = model<...>(), items: TItem[](선택값→표시용 매핑), modal: input.required<SdSelectModalInfo>, selectMode(기본 single), disabled/required/inset/size.
-- (contentChild) `itemOf` 템플릿 필수 — 선택된 항목 표시.
+### SdSharedDataSelect (`sd-shared-data-select`)
 
-## SdSharedDataSelectList<TItem, TModal>
+드롭다운 셀렉트(검색창·트리·미지정 항목·모달 연동 내장).
 
-`<sd-shared-data-select-list [items]="...">` — 단일 선택 리스트(검색·페이징·모달 연동).
-- selectedItem = model<TItem>(), canChangeFn?(item) — 선택 변경 가드.
-- items: input.required<TItem[]>, selectedIcon?, useUndefined(미지정 항목), filterFn?(item,index).
-- modal? — 우상단 외부창 버튼으로 띄울 선택 모달.
-- header?: string — 상단 헤더 텍스트.
-- pageItemCount?: number — >0 이면 페이지당 항목 수로 페이징.
-- (contentChild) `itemOf`/`headerTpl`/`filterTpl`/`undefinedTpl` 템플릿.
+- `value: model<...>` — 선택 키(single) 또는 키 배열(multi). 미지정은 `undefined`.
+- `items: input.required<TItem[]>` — 공유 항목 배열(`SharedDataBase` 상속).
+- `selectMode: "single"|"multi"` — 선택 모드(기본 single).
+- `required: boolean` — 빈 값이면 invalid.
+- `useUndefined: boolean` — multi 에서도 "미지정" 항목 노출(single 은 required 아니면 자동 노출).
+- `filterFn: (item, index, ...params) => boolean` + `filterFnParams: any[]` — 표시 항목 필터.
+- `getIsHiddenFn: (item, index) => boolean` — 숨김 판정(기본 `__isHidden`; 숨김 항목은 취소선 + 검색 시에만 표시).
+- `getSearchTextFn: (item, index) => string` — 검색 대상 텍스트(기본 `__searchText`).
+- `displayOrderByFn: (item) => ...` — 표시 정렬 키.
+- `modal: SdSelectModalInfo<TModal>` — 검색 버튼으로 띄울 선택 모달. `editModal: SdModalInfo<...>` — 편집 버튼 모달.
+- `multiSelectionDisplayDirection: "vertical"` — multi 표시 세로 나열.
+- `disabled`/`inset`/`inline`/`size`/`selectClass` — 공통/스타일.
+- 항목 템플릿: `<ng-template [itemOf]="items()" let-item="item">`, 미지정 표시 `#undefinedTpl`.
+- 사용: `<sd-shared-data-select [items]="sharedCustomers.items()" [(value)]="data().customerId"><ng-template [itemOf]="sharedCustomers.items()" let-item="item">{{ item.name }}</ng-template></sd-shared-data-select>`.
+
+### SdSharedDataSelectButton (`sd-shared-data-select-button`)
+
+값 표시 + 모달 검색 버튼(드롭다운 없이 모달 전용). 항목 수가 많아 드롭다운이 부적합할 때.
+
+- `value: model<...>` — 선택 키/키배열.
+- `items: TItem[]` — 표시명 매핑용 항목 배열.
+- `modal: input.required<SdSelectModalInfo<TModal>>` — 띄울 선택 모달.
+- `selectMode: "single"|"multi"` / `disabled` / `required` / `inset` / `size` — 공통.
+- 선택 항목 표시 템플릿: `<ng-template [itemOf]>`(필수).
+
+### SdSharedDataSelectList (`sd-shared-data-select-list`)
+
+검색창 + 리스트로 단건 선택(좌측 마스터 리스트 패널 등). `flex-column fill`.
+
+- `selectedItem: model<TItem>` — 선택된 항목(키 아닌 항목 객체). `canChangeFn: (item|undefined) => boolean|Promise<boolean>` — 변경 가드.
+- `items: input.required<TItem[]>` — 항목 배열(`__isHidden` 항목 자동 제외).
+- `useUndefined: boolean` — "미지정" 항목 노출.
+- `filterFn: (item, index) => boolean` — 추가 필터.
+- `selectedIcon: string` — 선택 표시 아이콘.
+- `pageItemCount: number` — 페이지당 항목 수(지정 시 페이지네이션).
+- `modal: SdSelectModalInfo<TModal>` — 우상단 외부 링크로 띄울 모달.
+- `header: string` — 상단 헤더 텍스트.
+- 템플릿: `#headerTpl`(헤더 우측), `#filterTpl`(검색창 대체), `<ng-template [itemOf]>`(항목), `#undefinedTpl`(미지정).
 
 ## matchesSearchText
 
-`matchesSearchText(itemText: string, searchQuery: string | undefined): boolean` — 검색어를 공백으로 나눈 모든 토큰이 itemText(소문자)에 포함되면 true(AND 매칭). 빈 검색어면 true. 위 select/list 가 내부 사용하나 커스텀 검색에도 활용 가능.
+- `function matchesSearchText(itemText: string, searchQuery: string | undefined): boolean` — 공백 구분 다중 검색어 AND 매칭(대소문자 무시). 빈 쿼리면 true. 위 선택 컨트롤들이 내부 검색에 사용. 커스텀 목록에서 동일 검색 동작이 필요할 때 직접 호출.