@simplysm/sd-claude 14.0.75 → 14.0.77

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

@@ -1,35 +1,100 @@
 # @simplysm/angular — crud
 
-CRUD 화면 골격. 상단 명령바·필터·toolbar·페이지 페이저·시트를 갖춘 리스트 화면(`SdCrudList`)과 디테일 화면(`SdCrudDetail`)과 공통 컨테이너(`SdBaseContainer`).
+CRUD 화면 골격. 공통 컨테이너(`SdBaseContainer`) + 리스트(`SdCrudList`) + 상세(`SdCrudDetail`) + 사용자 상태 프리셋(`SdStatePreset`).
 
-## `<sd-base-container>`
+## SdBaseContainer — `<sd-base-container>`
 
-페이지/모달 공통 컨테이너. `SdSharedDataProvider.wait()` 완료까지 busy 표시 후 `ready=true`.
+```ts
+ready = model(false);
+initialized = input(false);
+busyCount = model(0);
+restricted = input(false);
+viewType = input.required<SdViewType>();      // "page"|"modal"|"control" (routing.md)
 
-inputs: `viewType: SdViewType` (required), `restricted`, `initialized`. models: `ready`, `busyCount`. content templates: `#topbarTpl`, `#commandTpl`, `#contentTpl`, `#bottomCommandTpl`.
+// content slots: #topbarTpl #commandTpl #contentTpl #bottomCommandTpl
+```
+
+- 모든 simplysm 화면의 기본 컨테이너. 진입 시 `SdSharedDataProvider.wait()` 후 `ready` true.
+- `restricted=true` 면 권한 없음 안내 화면 표시(데이터 로드 스킵).
+- `viewType` — 보통 `injectViewTypeSignal()` 결과 바인딩.
+- 슬롯: `<ng-template #topbarTpl>` 상단 영역, `#commandTpl` 명령바, `#contentTpl` 본문, `#bottomCommandTpl` 하단.
+
+## SdCrudList — `<sd-crud-list>`
+
+```ts
+class SdCrudList<TItem, TKey>
+ready = model(false); initialized = input(false); busyCount = model(0);
+restricted = input(false); readonly = input(false);
+viewType = input.required<SdViewType>();
+selectMode = input<"single"|"multi">();
+key = input.required<string>();                // 시트/프리셋 key prefix
+
+filterSubmit = output(); submit = output();
+create = output(); delete = output<TItem[]>(); restore = output<TItem[]>();
+
+items = input<TItem[]>([]);
+selectedKeys = model<NonNullable<TKey>[]>([]);
+currDeletedItems = input<TItem[]>([]);         // 삭제됨 표시(취소선) 대상
+
+currentPage = model(0); totalPageCount = input(0);
+itemsPerPage = input(0); visiblePageCount = input(10);
+sorts = model<SortingDef[]>([]);
+trackByFn = input.required<(item) => TKey>();
+
+// content slots: #commandTpl #filterTpl #toolTpl #bottomCommandTpl
+// + 자식: <sd-sheet-column> 들
+```
+
+- 표준 리스트 화면: 필터 영역 + 시트 + 페이지바 + 명령(저장/추가/삭제/복원).
+- `filterSubmit` — 필터 폼 submit. 호출자가 데이터 fetch.
+- `submit` — 명령바의 저장 버튼.
+- `create`/`delete`/`restore` — 행 추가/선택 삭제/선택 복원.
+- `currDeletedItems` — soft-delete 표시. 해당 행 셀에 취소선 자동.
+- `readonly=true` 면 명령바·편집 차단.
+- 모달로 띄워서 선택 picker 로도 동작: 모달 confirm 시 `SdActivatedModalProvider.contentComponent.close.emit({ selectedKeys })`.
+- `key` — 자식 `<sd-sheet key>` 와 `SdStatePreset key` 가 이 값을 prefix 로 사용.
 
 ```html
-<sd-base-container [viewType]="vt">
-  <ng-template #commandTpl>...</ng-template>
-  <ng-template #contentTpl>...</ng-template>
-</sd-base-container>
+<sd-crud-list [viewType]="viewType()" key="invoice" [trackByFn]="trackById"
+              [items]="items()" [(selectedKeys)]="sel" selectMode="multi"
+              (filterSubmit)="reload()" (create)="onCreate()" (delete)="onDelete($event)">
+  <ng-template #filterTpl>...필터 폼...</ng-template>
+  <sd-sheet-column key="no" header="번호" />
+</sd-crud-list>
 ```
 
-## `<sd-crud-list<TItem, TKey>>`
+## SdCrudDetail — `<sd-crud-detail>`
 
-리스트+페이지+선택+삭제/복원 골격.
+```ts
+ready = model(false); initialized = input(false); busyCount = model(0);
+restricted = input(false); readonly = input(false);
+viewType = input.required<SdViewType>();
+submit = output();
 
-- 필수 input: `viewType`, `key`, `trackByFn: (TItem) => TKey`.
-- inputs: `selectMode: "single"|"multi"`, `items`, `currDeletedItems`, `totalPageCount`, `itemsPerPage`, `visiblePageCount=10`, `readonly`, `restricted`, `initialized`.
-- models: `ready`, `busyCount`, `selectedKeys: NonNullable<TKey>[]`, `currentPage`, `sorts: SortingDef[]`.
-- outputs: `filterSubmit`, `submit`, `create`, `delete: TItem[]`, `restore: TItem[]`.
-- content templates: `#commandTpl`, `#filterTpl`, `#toolTpl`, `#bottomCommandTpl` + `<sd-sheet-column>` 자식들이 자동으로 sheet 에 전달.
-- 삭제된 아이템은 `text-decoration: line-through`.
-- 모달 컨텍스트면 confirm/cancel 핸들러 자동 (`onModalSelectionConfirmClick`/`onModalSelectionCancelClick`).
+// content slots: #commandTpl #contentTpl #bottomCommandTpl
+```
+
+- 상세 화면 골격. 내부에 `<sd-form>` 자동 배치. 저장 버튼 클릭 시 form submit → invalid 없으면 `submit` 발화.
+
+## SdStatePreset — `<sd-state-preset>`
 
-## `<sd-crud-detail>`
+```ts
+key = input.required<string>();
+state = model<any>();              // 적용할 상태 객체 (필터 등)
+size = input<"sm"|"lg">();
+
+interface SdStatePresetDef { name: string; state: any; }
+```
+
+- 사용자가 현재 `state` 를 이름 붙여 저장/불러오기. `SdSystemConfigProvider` 키 `key` 로 `SdStatePresetDef[]` 저장.
+- 별 아이콘 클릭 → 이름 입력(`SdPromptModal`) → 추가. 프리셋 클릭 → `state` 에 적용. 디스켓 아이콘 → 현재 state 덮어쓰기. X 아이콘 → 삭제.
+
+```html
+<sd-state-preset key="invoice-filter" [(state)]="filter" />
+```
 
-단일 레코드 편집.
+## 주의
 
-- 필수: `viewType`. inputs: `restricted`, `readonly`, `initialized`. models: `ready`, `busyCount`. output: `submit`. templates: `#commandTpl`, `#contentTpl`, `#bottomCommandTpl`.
-- 저장 버튼 → 내부 `SdForm.requestSubmit()`.
+- 모든 CRUD 컴포넌트의 `ready` 는 진입 후 데이터 준비 완료 시 true. 호출자가 `[ready]="ready()"` 로 자식 조건부 렌더링.
+- `key` 는 한 클라이언트 내 고유해야 함. 시트 컬럼 설정·프리셋·기타 영구 상태가 이 키로 충돌 없이 저장됨.
+- `SdCrudList` 의 selectMode 가 설정되었고 컨테이너가 모달 안에 있으면 자동으로 picker 모드로 동작.

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

@@ -1,74 +1,200 @@
 # @simplysm/angular — forms
 
-폼 컨테이너 + 입력 컨트롤. 모든 컨트롤은 `value` model 기반. native form validity API 사용 (`SdForm`이 submit 시 reportValidity 호출).
+폼 컨테이너 + 값 입력 컨트롤. 모든 입력 컨트롤은 `value` model 기반. native form validity API 활용.
 
-## `<sd-form>`
+## SdForm — `<sd-form>`
+
+```ts
+formSubmit = output<SubmitEvent>();
+formInvalid = output();
+```
+
+- 내부에 native `<form>` 구성. 자식 `<sd-textfield required>` 등 native invalid 상태가 있으면 submit 막고 `formInvalid` 발화. 모두 valid 면 `formSubmit` 발화.
 
 ```html
-<sd-form (formSubmit)="onSubmit($event)" (formInvalid)="onInvalid()">
-  <sd-textfield [type]="'text'" [(value)]="name" [required]="true" />
-  <sd-button [type]="'submit'">저장</sd-button>
-</sd-form>
+<sd-form (formSubmit)="onSubmit()"><sd-textfield type="text" required [(value)]="name"/></sd-form>
 ```
 
-- 내부에 hidden submit 버튼 자동 삽입(Enter 키 submit 지원).
-- `requestSubmit()` 메서드 노출.
-- invalid 시 `reportValidity` → `formInvalid` emit, valid 시 `formSubmit` emit.
+## SdTextfield — `<sd-textfield>`
+
+```ts
+class SdTextfield<K extends keyof SdTextfieldTypes>
+value = model<SdTextfieldTypes[K]>();
+type = input.required<K>();
+placeholder = input<string>(); title = input<string>();
+inputStyle = input<string>(); inputClass = input<string>();
+disabled = input(false); readonly = input(false); required = input(false);
+min/max = input<SdTextfieldTypes[K]>(); minlength/maxlength = input<number>();
+pattern = input<string>();
+validatorFn = input<(value) => string|undefined>();
+format = input<string>(); step = input<number>(); autocomplete = input<string>();
+useNumberComma = input(true); minDigits = input<number>();
+inline = input(false); inset = input(false); size = input<"sm"|"lg">();
+theme = input<"primary"|"secondary"|"info"|"success"|"warning"|"danger"|"gray"|"blue-gray">();
+
+type SdTextfieldTypes = {
+  number: number; text: string; password: string; color: string; email: string;
+  format: string; date: DateOnly; month: DateOnly; year: DateOnly;
+  datetime: DateTime; "datetime-sec": DateTime; time: Time; "time-sec": Time;
+}
+const sdTextfieldTypes: (keyof SdTextfieldTypes)[]
+```
 
-## `<sd-textfield<K>>`
+- `type` — 위 13개 중 1개. 각 타입별 핸들러가 파싱/포맷/입력 제한 담당. `number` 는 콤마 표시, `date`/`month`/`year` 는 `DateOnly`, `datetime[-sec]` 는 `DateTime`, `time[-sec]` 는 `Time`, `format` 은 `format` 입력에 따른 자유 포맷.
+- `value` — 양방향. 타입에 맞는 객체/숫자/문자열.
+- `format` — `type=format` 또는 표시 포맷팅용. `XXX-XXXX` 같은 패턴(`X` 자리).
+- `validatorFn` — 반환 문자열이 있으면 invalid 메시지로 표시. undefined 면 통과.
+- `useNumberComma` — `type=number` 기본 true. 천 단위 콤마 표시.
+- `minDigits` — `type=number` 정수부 자릿수(부족 시 0 패딩).
+- `min`/`max`/`minlength`/`maxlength`/`pattern`/`required` — native 검증으로 위임.
+- `inline`/`inset`/`size`/`theme` — 레이아웃 옵션. `inset` 은 sd-sheet/모달 셀 안에 박힌 룩.
+- `readonly` — 편집 차단(포커스 가능). `disabled` — 포커스 불가.
 
 ```html
-<sd-textfield [type]="'number'" [(value)]="qty" [min]="0" [max]="999" [step]="1" />
-<sd-textfield [type]="'date'" [(value)]="dt" />
-<sd-textfield [type]="'format'" [format]="'XXX-XXXX-XXXX'" [(value)]="phone" />
+<sd-textfield type="number" [(value)]="qty" [min]="0" />
+<sd-textfield type="date" [(value)]="dueDate" required />
 ```
 
-`SdTextfieldTypes`: `number→number`, `text|password|color|email|format→string`, `date|month|year→DateOnly`, `datetime|datetime-sec→DateTime`, `time|time-sec→Time`. `sdTextfieldTypes` 배열로 키 목록 enum.
+## SdTextarea — `<sd-textarea>`
+
+```ts
+value = model<string>();
+placeholder/title/inputStyle/inputClass = input<string>(); minRows = input<number>(1);
+disabled/readonly/required/inline/inset = input(false);
+size = input<"sm"|"lg">();
+validatorFn = input<(v) => string|undefined>();
+theme = input<...8 themes>();
+```
 
-주요 input: `value` (model), `type` (required), `placeholder`, `title`, `inputStyle/Class`, `disabled/readonly/required` (booleanAttribute), `min/max/minlength/maxlength`, `pattern`, `validatorFn(value) => string | undefined` (커스텀 메시지), `format`, `step`, `autocomplete`, `useNumberComma` (default `true` — 숫자 표시 시 천단위 콤마), `minDigits` (display 시 최소 자릿수), `size`(`"sm"|"lg"`), `inline`, `inset`, `theme`.
+- 멀티라인 입력. `minRows` 만큼 시작 높이 확보, 내용 늘면 자동 확장.
 
-readonly/disabled 상태에서는 `<input>` 비표시(`_contents` div만 노출).
+## SdNumpad — `<sd-numpad>`
 
-## `<sd-textarea>`
+```ts
+value = model<number>(); placeholder = input<string>();
+required = input(false); inputDisabled = input(false);
+useEnterButton = input(false); useMinusButton = input(false);
+enterButtonClick = output();
+```
 
-`[(value)]: string`, `placeholder`, `title`, `minRows=1` (행수는 값 줄바꿈 수와 minRows 중 큰 값), `disabled/readonly/required`, `inline`, `inset`, `size`, `validatorFn`, `theme`, `inputStyle/Class`.
+- 터치용 숫자 패드. `useEnterButton` true 면 엔터 키 노출, 클릭 시 `enterButtonClick` 발화. `useMinusButton` true 면 부호 토글 키 노출. `inputDisabled` true 면 상단 표시 영역의 직접 타이핑 차단(패드만 사용).
 
-## `<sd-numpad>`
+## SdRange — `<sd-range>`
 
-숫자 키패드. `[(value)]: number`, `text = signal<string|undefined>` (내부 표시값), `placeholder`, `required`, `inputDisabled` (입력란만 비활성), `useEnterButton` (ENT 버튼 노출), `useMinusButton` (- 버튼 노출), `(enterButtonClick)` 출력.
+```ts
+class SdRange<K extends keyof SdTextfieldTypes>
+type = input.required<K>(); from = model<SdTextfieldTypes[K]>(); to = model<SdTextfieldTypes[K]>();
+inputStyle = input<string>(); required = input(false); disabled = input(false);
+```
 
-## `<sd-range<K>>`
+- `SdTextfield` 2개를 `~` 로 묶은 범위 입력. `type` 은 `SdTextfield` 와 동일 키.
 
-`type: K` (TextfieldTypes 키), `[(from)]`, `[(to)]: SdTextfieldTypes[K]`, `required`, `disabled`, `inputStyle`. `to.min`은 `from` 으로 강제.
+## SdDateRangePicker — `<sd-date-range-picker>`
 
-## `<sd-date-range-picker>`
+```ts
+periodType = model<"일"|"월"|"범위">("범위");
+from = model<DateOnly>(); to = model<DateOnly>();
+required = input(false);
+```
 
-`[(periodType)]: "일"|"월"|"범위" = "범위"`, `[(from)]: DateOnly`, `[(to)]: DateOnly`, `required`.
-- `"일"`: 단일 date 입력. `to`는 `from` 따라감.
-- `"월"`: month 입력. `from`은 1일, `to`는 말일 자동 설정.
-- `"범위"`: from~to date 양쪽 입력. from > to 시 to를 from으로 보정.
+- `periodType` — `일`: 단일 날짜(`from`=`to`), `월`: 단일 월, `범위`: from/to 자유 범위. 사용자가 토글 가능.
 
-## `<sd-checkbox>` / `<sd-switch>`
+## SdSelect — `<sd-select>`
 
-```html
-<sd-checkbox [(value)]="agreed" [theme]="'primary'">동의</sd-checkbox>
-<sd-switch [(value)]="enabled" [size]="'sm'" />
+```ts
+class SdSelect<M extends "single"|"multi", T>
+selectMode = input("single" as M);
+value = model<SelectModeValue<any>[M]>();      // single → T, multi → T[]
+placeholder = input<string>();
+disabled/inline/inset/required = input(false); size = input<"sm"|"lg">();
+hideSelectAll = input(false);
+multiSelectionDisplayDirection = input<"vertical">();
+items = input<T[]>(); trackByFn = input<(item, index) => unknown>((item) => item);
+getChildrenFn = input<(item: T) => T[]|undefined>();
+contentClass = input<string>(); contentStyle = input<string>();
+dropdownOpen = model(false);
+
+type SelectModeValue<T> = { multi: T[]; single: T };
 ```
 
-`value: boolean` (model), `canChangeFn(value) => boolean | Promise<boolean>` — false 면 변경 차단 (`setupModelHook` 사용). 공통: `disabled`, `size`, `inline`, `inset`, `theme`. checkbox 추가: `radio` (radio 모드 — 다시 클릭해도 false 안 됨), `icon` (체크 아이콘 변경, default `tablerCheck`), `contentStyle`, `theme` 에 `"white"` 옵션 추가(시트 헤더용).
+- 드롭다운 셀렉트. `items` 를 직접 주거나, content projection 으로 `<sd-select-item>` 나열.
+- `selectMode` — `single`: 단일 선택, `multi`: 체크박스 다중 선택(`hideSelectAll` false 면 전체 선택 옵션 노출).
+- `getChildrenFn` — 트리형 선택지. 자식 있는 노드 펼침.
+- `multiSelectionDisplayDirection` — multi 모드에서 선택값 표시 방향. `vertical` 만.
+- `dropdownOpen` — 양방향. 외부에서 강제 열림 제어 가능.
+- `<ng-content>` — 표시 영역 커스텀 템플릿 또는 `<sd-select-item>` 리스트.
 
-## `<sd-checkbox-group<T>>` / `<sd-checkbox-group-item<T>>`
+## SdSelectItem — `<sd-select-item>`
 
-```html
-<sd-checkbox-group [(value)]="selected">
-  <sd-checkbox-group-item [value]="opt" *ngFor="let opt of options">{{ opt }}</sd-checkbox-group-item>
-</sd-checkbox-group>
+```ts
+class SdSelectItem<T> { value = input<T|undefined>(); disabled = input(false); hidden = input(false); }
+```
+
+- `SdSelect` 자식. content projection 으로 표시할 옵션. `hidden` true 면 필터링 결과 등으로 숨김.
+
+## SdSelectButton — `<sd-select-button>`
+
+- `SdSelect` 트리거 버튼 슬롯. inputs 없음. `<sd-select>` 내부에 표시 영역 커스터마이즈 시 content projection 으로 사용.
+
+## SdCheckbox — `<sd-checkbox>`
+
+```ts
+value = model(false);
+canChangeFn = input<(item: boolean) => boolean|Promise<boolean>>(() => true);
+icon = input(tablerCheck); radio = input(false);
+disabled = input(false); size = input<"sm"|"lg">();
+inline = input(false); inset = input(false);
+theme = input<...8 themes>(); contentStyle = input<string>();
 ```
 
-`SdCheckboxGroup`: `value: T[]` (model, default `[]`), `disabled`. `SdCheckboxGroupItem`: `value: T` (required), `inline`.
+- `radio` true 면 라디오 룩(원형). false 면 체크박스(사각).
+- `canChangeFn` — 변경 직전 호출, false 반환·Promise<false> 면 무시. 비동기 확인용.
+- `icon` — 체크 상태 아이콘. 기본 `tablerCheck`.
+
+## SdSwitch — `<sd-switch>`
+
+```ts
+value = model(false);
+canChangeFn = input<(item) => boolean|Promise<boolean>>(() => true);
+disabled = input(false); inline = input(false); inset = input(false);
+size = input<"sm"|"lg">(); theme = input<...8 themes>();
+```
+
+- 토글 스위치. `SdCheckbox` 와 의미 같지만 룩만 슬라이더.
+
+## SdCheckboxGroup — `<sd-checkbox-group>`
+
+```ts
+class SdCheckboxGroup<T> { value = model<T[]>([]); disabled = input(false); }
+```
+
+- 자식 `<sd-checkbox-group-item>` 들을 묶어 `value` 배열로 관리.
+
+## SdCheckboxGroupItem — `<sd-checkbox-group-item>`
+
+```ts
+class SdCheckboxGroupItem<T> { value = input.required<T>(); inline = input(false); }
+```
+
+- 그룹의 단일 옵션. `value` 가 그룹 배열에 있으면 체크 상태.
+
+## SdDropdown — `<sd-dropdown>`
+
+```ts
+open = model(false); disabled = input(false);
+```
+
+- 트리거 + 팝업 컨테이너. content projection 으로 트리거와 `<sd-dropdown-popup>` 을 함께 둠.
+
+## SdDropdownPopup — `<sd-dropdown-popup>`
+
+- `SdDropdown` 의 팝업 슬롯. inputs 없음. content projection 으로 내용 채움.
+
+```html
+<sd-dropdown [(open)]="open">트리거<sd-dropdown-popup>...팝업 내용...</sd-dropdown-popup></sd-dropdown>
+```
 
-## 검증
+## 주의
 
-- 컨트롤 내부에서 `setupInvalid(getMessage)` 사용 — 빈 문자열이면 valid, 그 외 메시지는 invalid 사유. 좌상단 빨간 점 인디케이터.
-- `validatorFn` 은 컨트롤 입력값을 검사해 메시지 반환.
-- `SdForm` submit 시 자동으로 reportValidity 호출 + invalid 인디케이터 표시.
+- `value` model 인 컨트롤은 모두 `[(value)]="..."` 양방향.
+- 입력 컨트롤은 `<sd-form>` 안에 두면 invalid 시 native `:invalid` 처리됨. `SdInvalid` 디렉티브로 커스텀 invalid 표시 추가 가능 ([infrastructure.md](./infrastructure.md)).

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

@@ -1,80 +1,231 @@
 # @simplysm/angular — infrastructure
 
-앱 인프라 프로바이더(전부 `providedIn: "root"` 또는 single instance).
+앱 인프라 프로바이더·DOM 이벤트/효과 디렉티브·유틸 함수·타입 헬퍼. 전부 standalone, root 제공자거나 함수.
 
-## `SdServiceClientFactoryProvider`
+## 설정·저장 프로바이더
 
-`@simplysm/service-client` 의 `ServiceClient` 를 키별로 보관.
+### SdSystemLogProvider (root)
 
-```typescript
-const factory = inject(SdServiceClientFactoryProvider);
-await factory.connectAsync("main", { host, port, ssl });   // 옵션 생략 시 location 기반
-const client = factory.get("main");
-await factory.closeAsync("main");
+```ts
+writeFn?: (severity, ...data) => Promise<void>|void;
+writeAsync(severity: "error"|"warn"|"log", ...data): Promise<void>;
 ```
 
-- 같은 키 재연결 금지(`이미 연결된`/`이미 연결이 끊긴`). 한 번 close된 키는 재사용 불가.
-- request/response progress → `SdToastProvider.info(message, true)` 로 진행률 토스트 자동.
-- destroy 시 모든 클라이언트 close.
+- consola 태그(`angular:system-log`)로 로컬 로그. `writeFn` 세팅 시 서버 등으로 추가 전송. 전송 실패는 로컬 error 만 남기고 throw 안 함.
 
-## `SdFileDialogProvider`
+### SdLocalStorageProvider<T> (root)
 
-```typescript
-const file  = await inject(SdFileDialogProvider).showAsync();
-const files = await inject(SdFileDialogProvider).showAsync(true, "image/*");
+```ts
+set<K>(key: K, value: T[K]); get<K>(key: K): T[K]|undefined; remove(key: K);
 ```
 
-cancel/empty → `undefined`. 동적 `<input type=file>` 생성/제거.
+- 키 prefix = `clientName` (`SdAngularConfigProvider`). JSON 직렬화. 파싱 실패 시 undefined.
 
-## `SdLocalStorageProvider<T>`
+### SdSystemConfigProvider<T> (root)
 
-```typescript
-const ls = inject<SdLocalStorageProvider<Schema>>(SdLocalStorageProvider);
-ls.set("theme", "dark");
-const v = ls.get("theme");
-ls.remove("theme");
+```ts
+fn?: { set<K>(key, data): Promise<void>|void; get(key): PromiseLike<any> };
+setAsync<K>(key, data): Promise<void>;
+getAsync(key): Promise<...>;
 ```
 
-키는 `<clientName>.<key>` 로 prefix. JSON 직렬화.
+- `fn` 미세팅이면 `SdLocalStorageProvider` 위임. `fn` 세팅 시 서버 영구 저장으로 전환. 모달 사이즈·시트 컬럼 설정·프리셋이 이걸 통함.
 
-## `SdSystemConfigProvider<T>`
+### injectSdSystemConfigResource<T>
 
-```typescript
-const cfg = inject<SdSystemConfigProvider<Schema>>(SdSystemConfigProvider);
-cfg.fn = { set: (k, v) => svc.set(k, v), get: (k) => svc.get(k) };  // 옵션: 서버 연동
-await cfg.setAsync("sheet.order", config);
-const v = await cfg.getAsync("sheet.order");
+```ts
+function injectSdSystemConfigResource<T>(options: { key: Signal<string|undefined> }): {
+  value: Signal<T|undefined>; isLoading: Signal<boolean>;
+  status; hasValue(); reload();
+  set(value: T|undefined): void;
+  update(fn: (prev: T|undefined) => T|undefined): void;
+};
 ```
 
-`fn` 미설정이면 `SdLocalStorageProvider` 폴백. SdSheet/SdModal/SdStatePreset 등이 자동 사용.
+- 컴포넌트의 element tag + key signal 조합으로 `SdSystemConfigProvider` 값 resource 화. `set`/`update` 시 microtask 로 server 저장(에러는 `ErrorHandler.handleError`).
 
-## `injectSdSystemConfigResource<T>({ key })`
+## 서비스 클라이언트
 
-```typescript
-const r = injectSdSystemConfigResource<MyConfig>({ key: keySignal });
-r.value(); r.isLoading(); r.status();
-r.set(v); r.update((prev) => ...); r.reload(); r.hasValue();
+### SdServiceClientFactoryProvider (root)
+
+```ts
+connectAsync(key: string, options?: Partial<ServiceConnectionOptions>): Promise<void>;
+closeAsync(key: string): Promise<void>;
+get(key: string): ServiceClient;
+```
+
+- key 별 `ServiceClient` 풀. `connectAsync` 시 기본 host/port 는 현재 `location` 기준(https 면 443, http 면 80). request/response progress 시 자동으로 `SdToastProvider.info(..., true)` progress 토스트.
+- 중복 connect 또는 closed key 재사용은 throw. destroy 시 모든 클라이언트 close.
+
+## 파일·에러·테마
+
+### SdFileDialogProvider (root)
+
+```ts
+showAsync(multiple?: false, accept?: string): Promise<File|undefined>;
+showAsync(multiple: true, accept?: string): Promise<File[]|undefined>;
+```
+
+- `<input type="file">` 동적 생성 → click → 선택 후 결과. 취소 시 undefined.
+- `accept` — MIME/확장자(`"image/*"`·`".pdf,.docx"`).
+
+### SdGlobalErrorHandlerPlugin (Angular `ErrorHandler` 교체용)
+
+- `provideSdAngular` 가 자동 등록. 직접 등록 안 해도 됨.
+- `PromiseRejectionEvent`/`ErrorEvent`/`Error`/임의 값 분류해 `SdSystemLogProvider.writeAsync('error', ...)` + 전체 화면 에러 오버레이 표시 + Angular `ApplicationRef.destroy()`. 오버레이 클릭 → 홈으로 reload.
+
+### SdThemeProvider (root)
+
+```ts
+dark: WritableSignal<boolean>;
+readonly fontSizePresets: readonly number[];   // [12,14,16,20,24,28]
+fontSize: WritableSignal<number>;              // body html font-size px
+increaseFontSize(): void; decreaseFontSize(): void;
+```
+
+- `dark` 효과 → `<body class="sd-theme-dark">`. `fontSize` → `<html style="font-size:Npx">`.
+- `increase`/`decrease` — presets 의 인접 값으로만 이동.
+
+### SdThemeSelector — `<sd-theme-selector>`
+
+- inputs 없음. 팔레트(다크 토글) + 폰트 크기 ± 버튼 UI.
+
+## 유틸 함수
+
+### FormatPipe — `{{ value | format: pattern }}`
+
+- `value: string|DateTime|DateOnly|undefined`, `format: string` → 포맷팅된 string.
+- DateTime/DateOnly → `toFormatString(format)`.
+- 문자열 → `X` 자리에 1글자씩 매핑. `|` 로 여러 패턴 alt 가능(value 길이 일치하는 첫 패턴 선택). 매칭 실패 시 원본 반환.
+- 예: `"01012345678" | format: "XXX-XXXX-XXXX|XXX-XXX-XXXX"` → `"010-1234-5678"`.
+
+### mark
+
+```ts
+function mark(sig: WritableSignal<any>): void
+```
+
+- in-place mutation 후 signal 소비자에게 변경 알림. 배열은 shallow copy, 객체는 spread. mutable 데이터로 setter 호출 누락 방지용.
+
+### setSafeStyle
+
+```ts
+function setSafeStyle(renderer: Renderer2, el: HTMLElement, style: Partial<CSSStyleDeclaration>): void
+```
+
+- `Renderer2.setStyle` 을 객체 단위로 일괄 적용. SSR/zoneless 안전.
+
+### setupBgTheme
+
+```ts
+function setupBgTheme(options?: {
+  theme?: "primary"|"secondary"|"info"|"success"|"warning"|"danger"|"gray"|"blue-gray";
+  lightness?: "lightest"|"lighter";
+}): void
+```
+
+- 컴포넌트 진입 동안 `document.body --background-color` 를 테마 변수로 설정. destroy 시 원복.
+- `lightness` 기본 `lightest`.
+
+### setupModelHook
+
+```ts
+function setupModelHook<T>(model: WritableSignal<T>, canFn: Signal<(item: T) => boolean|Promise<boolean>>): void
+```
+
+- model 의 `set`/`update` 를 가로채 `canFn(value)` 결과가 true(또는 Promise<true>) 일 때만 적용. false 면 무시. Promise reject 는 `ErrorHandler`.
+- 체크박스/스위치 등의 `canChangeFn` 패턴 구현체.
+
+## 타입 헬퍼
+
+```ts
+type UndefToOptional<T>            // undefined 가능 prop 을 optional 로
+type DirectiveInputSignals<T>      // 컴포넌트의 InputSignal prop → 값 타입 객체
+type WithOptional<T, K extends keyof T>   // 일부 키를 optional 로
+```
+
+- `SdModalInfo.inputs` / `SdPrintInput.inputs` 등의 타입 빌딩에 사용.
+
+## DOM 이벤트 디렉티브
+
+### SdEvents — `<el (click.capture)="..." (scroll.passive)="..." ...>`
+
+- 이벤트 이름 끝에 `.capture`/`.passive`/`.once` 조합 가능한 다중 셀렉터 디렉티브. 표준 Angular 이벤트 바인딩으로는 옵션 못 주는 listener option 활성.
+- 지원 이벤트: click/mouse*/keydown/keyup/focus/blur/invalid/scroll/wheel/touch*/drag*/transitionend/animationend.
+
+### SdOptionEventPlugin
+
+- `provideSdAngular` 가 `EVENT_MANAGER_PLUGINS` 에 등록. `SdEvents` 가 의존. 직접 호출 X.
+
+### SdResizeDirective — `[sdResize]`
+
+```ts
+sdResize = output<SdResizeEvent>();
+interface SdResizeEvent { heightChanged: boolean; widthChanged: boolean; target: HTMLElement; contentRect: DOMRectReadOnly; }
+```
+
+- `ResizeObserver` + rAF 디바운스. 너비/높이 변경 플래그 포함.
+
+### SdIntersectionDirective — `[sdIntersection]`
+
+```ts
+sdIntersection = output<SdIntersectionEvent>();
+interface SdIntersectionEvent { entry: IntersectionObserverEntry; }
+```
+
+- `IntersectionObserver` 래퍼. 무한 스크롤 트리거 등.
+
+### SdCommandDirective — `[sdRefreshCommand]`/`[sdSaveCommand]`/`[sdInsertCommand]`
+
+- 전역 키 단축키 출력. `Ctrl+Alt+L` → refresh, `Ctrl+S` → save, `Insert` → insert. 최상위 열린 모달 또는 호스트가 활성 영역일 때만 발화(다른 모달 위면 무시).
+
+## 효과 디렉티브
+
+### SdRipple — `[sdRipple]` + setupRipple
+
+```ts
+enabled = input.required({ alias: "sdRipple", transform: booleanAttribute });
 ```
 
-키는 `<elementTagName>.<key()>` 로 prefix. set 호출 시 화면 즉시 갱신 + queueMicrotask 로 비동기 영속화 (실패 시 ErrorHandler).
+- 클릭 시 머티리얼풍 잉크 효과. `setupRipple(enableFn?)` 은 컴포넌트 안에서 inject 후 직접 호출하는 형태.
+
+### SdShowEffect — `[sdShowEffect]` + setupRevealOnShow
 
-## `SdGlobalErrorHandlerPlugin`
+```ts
+enabled = input.required({ alias: "sdShowEffect", transform: booleanAttribute });
+sdShowEffectType = input<"l2r"|"t2b">("t2b");
+```
 
-`provideSdAngular`가 `ErrorHandler` 로 등록. 처리되지 않은 Error/PromiseRejectionEvent/ErrorEvent 캐치 → `SdSystemLogProvider.writeAsync("error", ...)` + 전면 오버레이 + ApplicationRef destroy. 클릭 시 reload(prod는 hash `/` 로 리셋).
+- 스크롤로 첫 표시 시 페이드인 + 슬라이드. `l2r`: 좌→우, `t2b`: 위→아래(기본).
 
-## `SdOptionEventPlugin`
+### SdInvalid — `[sdInvalid]` + setupInvalid
 
-`provideSdAngular`가 `EVENT_MANAGER_PLUGINS` 로 등록. 이벤트명에 `.capture` / `.passive` / `.once` 접미 허용 (예: `(scroll.passive)`, `(click.capture.once)`).
+```ts
+invalidMessage = input.required<string>({ alias: "sdInvalid" });
+```
 
-## `SdPrintProvider`
+- 호스트 요소를 invalid 상태로 표시(빨간 점 인디케이터 + form submit 막기). 빈 문자열이면 valid. 직접 form 검증 메시지 표시할 때.
 
-```typescript
-await print.printAsync({ type: MyTpl, inputs: { ... } }, { size: "A4", margin: "0" });
-const bytes = await print.getPdfBufferAsync({ type, inputs }, { orientation: "portrait", pageSize: "a4" });
+## 템플릿 디렉티브
+
+### SdTypedTemplate — `<ng-template typed>`
+
+```ts
+class SdTypedTemplate<T> { typed = input.required<T>(); }
+```
+
+- 템플릿 컨텍스트 타입 명시용. `typed` 에 token 값/객체 바인딩.
+
+### SdItemOfTemplate — `<ng-template itemOf>`
+
+```ts
+class SdItemOfTemplate<TItem> { itemOf = input.required<TItem[]>(); }
+interface SdItemOfTemplateContext<TItem> { $implicit: TItem; item: TItem; index: number; depth: number; }
 ```
 
-- 템플릿 컴포넌트는 `SdPrint` 구현 필요 (`initialized: Signal<boolean>`, optional `_optionalPrintInputs`).
-- `SdPrintInput<T, X>` = `{ type; inputs: WithOptional<DirectiveInputSignals<T> 제외..., optional 키들> }`.
-- print: `@page` + `@media print` 스타일 임시 주입 → `initialized=true` 및 이미지 로드 대기 → `window.print()`.
-- PDF: `.page` 자식이 있으면 페이지별, 없으면 단일 페이지. `htmlToImage.toCanvas` (pixelRatio=4) → `jspdf.addImage`.
-- 두 메서드 모두 진행 동안 `SdBusyProvider.globalBusyCount` ±1.
+- 리스트 아이템 템플릿 컨텍스트 타입 추론. `let-item`, `let-index="index"`, `let-depth="depth"` 사용 가능. `SdCalendar` 등이 자식으로 요구.
+
+## 주의
+
+- `provideSdAngular` 호출만으로 `SdGlobalErrorHandlerPlugin`/`SdOptionEventPlugin`/`SdEvents` 가 모두 활성. 별도 추가 불필요.
+- `SdLocalStorageProvider`/`SdSystemConfigProvider` 의 키는 `clientName.<key>` 형태. 같은 도메인의 다른 simplysm 앱과 충돌 방지.