@simplysm/sd-claude 14.0.88 → 14.0.90

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

@@ -1,44 +1,78 @@
-# @simplysm/angular — 호스트 디렉티브·동작 셋업
+# @simplysm/angular — 디렉티브·signal setup 헬퍼
 
-엘리먼트에 부착하는 동작 디렉티브와, 컴포넌트 생성자에서 호출해 호스트 엘리먼트에 동작을 주입하는 `setup*` 함수, 타입 안전 템플릿 디렉티브. 다른 컴포넌트들이 ripple/검증/리사이즈 감지 등에 내부적으로 사용하며 단독으로도 쓸 수 있음.
+DOM 관찰(리사이즈/교차)·캡처 이벤트·커맨드 단축키·ripple·노출 애니메이션·invalid 표시·타입드 템플릿을 호스트 엘리먼트에 붙이는 군. `setup*` 헬퍼는 컴포넌트 `constructor` 안에서 호출(`inject(ElementRef)` 의존), `Sd*` 디렉티브는 그 헬퍼를 attribute 로 래핑한 것.
 
-## 이벤트 옵저버 디렉티브
+## SdResizeDirective (`[sdResize]`)
 
-- `[sdResize]` (`SdResizeDirective`) — `ResizeObserver` 로 크기 변화 감지. `sdResize = output<SdResizeEvent>()`. `SdResizeEvent = { heightChanged; widthChanged; target: HTMLElement; contentRect: DOMRectReadOnly }`. requestAnimationFrame 디바운스.
-- `[sdIntersection]` (`SdIntersectionDirective`) — `IntersectionObserver` 로 가시성 감지. `sdIntersection = output<SdIntersectionEvent>()`. `SdIntersectionEvent = { entry: IntersectionObserverEntry }`.
+`ResizeObserver` 를 requestAnimationFrame 으로 디바운스해 크기 변화를 emit.
 
-## SdEvents
+- `sdResize: output<SdResizeEvent>` — 크기 변화 시 발화.
+- `SdResizeEvent = { heightChanged: boolean; widthChanged: boolean; target: HTMLElement; contentRect: DOMRectReadOnly }` — 어떤 축이 바뀌었는지·대상·새 사각형. `heightChanged`/`widthChanged` 로 필요한 축만 처리.
+- 사용: `<div (sdResize)="onResize($event)">`. `sd-sheet`·`sd-collapse`·`sd-echarts` 등이 hostDirective 로 사용.
 
-`SdEvents` 디렉티브 — capture/passive/once 옵션 이벤트를 output 으로 노출(Angular 기본 바인딩이 지원 않는 리스너 옵션용). 셀렉터에 해당하는 속성을 호스트에 쓰면 동작. 예: `(click.capture)`, `(scroll.passive)`, `(wheel.capture.passive)`, `(touchstart.passive)`, `(transitionend.once)` 등. 각 output 은 대응 DOM 이벤트 타입(MouseEvent/WheelEvent/TouchEvent 등) emit.
+## SdIntersectionDirective (`[sdIntersection]`)
 
-`SdOptionEventPlugin` — `provideSdAngular` 가 등록하는 `EventManagerPlugin`. `.capture`/`.passive`/`.once` 접미사 이벤트 바인딩을 실제 리스너 옵션으로 변환. 직접 사용 불필요.
+`IntersectionObserver` 로 뷰포트 진입/이탈 emit.
 
-## SdCommandDirective
+- `sdIntersection: output<SdIntersectionEvent>` — 교차 변화 시 발화.
+- `SdIntersectionEvent = { entry: IntersectionObserverEntry }` — `entry.isIntersecting` 으로 진입 판단. 무한 스크롤·지연 로드에 사용.
 
-`[sdRefreshCommand],[sdSaveCommand],[sdInsertCommand]` — 전역 단축키를 명령 이벤트로 변환(최상위 모달 컨텍스트에서만 발동).
+## SdEvents (옵션부 이벤트)
 
-- `sdRefreshCommand = output<KeyboardEvent>()` — Ctrl+Alt+L.
-- `sdSaveCommand = output<KeyboardEvent>()` — Ctrl+S.
-- `sdInsertCommand = output<KeyboardEvent>()` — Ctrl+Insert.
+Angular 기본 바인딩이 못 거는 capture/passive/once 이벤트를 output 으로 노출하는 디렉티브. selector 에 든 attribute 중 쓰는 것만 바인딩하면 됨(전부 listen 하지 않음). `SdOptionEventPlugin`(provideSdAngular 가 등록) 이 실제 옵션 처리.
 
-CRUD 컨테이너가 `sdSaveCommand` 를 저장에 연결.
+- 클릭/마우스: `click.capture`, `click.once`, `click.capture.once`, `mousedown.capture`, `mouseup.capture`, `mouseover.capture`, `mouseout.capture` — `output<MouseEvent>`.
+- 키보드: `keydown.capture`, `keyup.capture` — `output<KeyboardEvent>`.
+- 포커스: `focus.capture`, `blur.capture` — `output<FocusEvent>`(버블 안 되므로 capture 필수).
+- 폼: `invalid.capture` — `output<Event>`.
+- 스크롤/휠: `scroll.capture`, `scroll.passive`, `scroll.capture.passive`, `wheel.passive`, `wheel.capture.passive` — passive 로 스크롤 성능 확보.
+- 터치: `touchstart.passive`(+capture), `touchmove.passive`(+capture), `touchend.passive` — `output<TouchEvent>`.
+- 드래그: `dragover.capture`, `dragenter.capture`, `dragleave.capture`, `drop.capture` — `output<DragEvent>`.
+- 애니메이션: `transitionend.once`, `animationend.once` — 1회만.
+- `.capture` = 캡처 단계 수신, `.passive` = preventDefault 불가(스크롤 블로킹 방지), `.once` = 1회 후 자동 해제.
+- 사용: `<div (scroll.passive)="onScroll()">`, `<div (keydown.capture)="onKeydown($event)">`.
 
-## ripple / show-effect / invalid 디렉티브·셋업
+## SdCommandDirective (`[sdRefreshCommand],[sdSaveCommand],[sdInsertCommand]`)
 
-부착형 디렉티브와 동치 셋업 함수 쌍.
+문서 레벨 Ctrl 단축키를 명령 output 으로. 최상위 열린 모달 안에서만 동작(다른 컨텍스트로 새지 않게 가드).
 
-- `[sdRipple]` (`SdRipple`) — 클릭 ripple 효과. `sdRipple = input.required(booleanAttribute)`(활성 여부). `setupRipple(enableFn?: () => boolean)` 는 컴포넌트 생성자에서 호스트에 ripple 주입(버튼/체크박스가 사용).
-- `[sdShowEffect]` (`SdShowEffect`) — 스크롤 진입 시 페이드/슬라이드 인. `sdShowEffect = input.required(booleanAttribute)`(활성), `sdShowEffectType: "l2r"|"t2b"`(슬라이드 방향, 기본 `"t2b"`). `setupRevealOnShow(optFn?)` 가 동치 셋업.
-- `[sdInvalid]` (`SdInvalid`) — 임의 엘리먼트에 폼 검증 메시지 부착. `sdInvalid = input.required<string>()`(메시지, 빈 문자열이면 유효). `setupInvalid(getInvalidMessage: () => string)` 가 동치 셋업(숨김 input + `setCustomValidity` 로 네이티브 검증 연동, `<sd-form>` 제출 시 표시). 모든 `required` 컨트롤이 내부 사용.
+- `sdRefreshCommand: output<KeyboardEvent>` — Ctrl+Alt+L.
+- `sdSaveCommand: output<KeyboardEvent>` — Ctrl+S.
+- `sdInsertCommand: output<KeyboardEvent>` — Ctrl+Insert.
+- 매칭 시 preventDefault + stopPropagation. `sd-crud-list`/`sd-crud-detail` 가 `sdSaveCommand` 를 hostDirective 로 받아 저장 트리거.
 
-## setupModelHook
+## SdRipple (`[sdRipple]`) / setupRipple
 
-`setupModelHook<T, S extends WritableSignal<T>>(model: S, canFn: Signal<(item: T) => boolean | Promise<boolean>>): void` — `model` 의 set/update 를 가로채 `canFn` 통과 시에만 값 적용. 체크박스/스위치/공유선택리스트의 `canChangeFn` 구현.
+클릭 지점에서 퍼지는 물결 효과.
 
-- `model` — 가로챌 WritableSignal.
-- `canFn` — 변경 허용 판정 시그널. `false` 반환 시 무시, `true` 면 즉시 set, Promise 면 resolve 가 `false` 아닐 때 set(에러는 ErrorHandler 위임).
+- `SdRipple.sdRipple: input.required(booleanAttribute)` — true 일 때만 ripple 동작(disabled 토글). `<sd-button [sdRipple]="!disabled()">`.
+- `setupRipple(enableFn?: () => boolean): void` — constructor 에서 호출하는 헬퍼. `enableFn` 이 false 반환 시 해당 클릭은 ripple 생략. 커스텀 컴포넌트 내부에서 직접 ripple 부여 시.
 
-## 타입 안전 템플릿 디렉티브
+## SdShowEffect (`[sdShowEffect]`) / setupRevealOnShow
 
-- `ng-template[typed]` (`SdTypedTemplate<T>`) — `typed = input.required<T>()` 로 템플릿 컨텍스트 타입을 명시(재귀 메뉴 등 `let-x` 타입 추론용). 값은 타입 토큰일 뿐.
-- `ng-template[itemOf]` (`SdItemOfTemplate<TItem>`) — `itemOf = input.required<TItem[]>()` 로 항목 반복 템플릿의 컨텍스트 타입 제공. select/calendar/공유선택이 항목 슬롯에 사용. 컨텍스트 `SdItemOfTemplateContext<TItem> = { $implicit; item; index; depth }`.
+뷰포트 진입 시 페이드+슬라이드로 나타나는 효과.
+
+- `SdShowEffect.sdShowEffect: input.required(booleanAttribute)` — true 면 효과 적용, false 면 효과 없이 즉시 표시.
+- `SdShowEffect.sdShowEffectType: "l2r" | "t2b"` — 등장 방향. `"t2b"`(기본) = 위에서 아래로, `"l2r"` = 왼쪽에서 오른쪽으로.
+- `setupRevealOnShow(optFn?: () => { type?: "l2r"|"t2b"; enabled?: boolean }): void` — constructor 헬퍼. `enabled` false 면 트랜지션 없이 노출.
+
+## SdInvalid (`[sdInvalid]`) / setupInvalid
+
+폼 검증 실패를 좌상단 빨간 점 + 네이티브 form 검증으로 표시. 숨은 input 에 `setCustomValidity` 를 걸어 form submit 시 차단.
+
+- `SdInvalid.sdInvalid: input.required<string>` — 빈 문자열이면 유효, 비어있지 않으면 그 메시지로 invalid 표시.
+- `setupInvalid(getInvalidMessage: () => string): void` — constructor 헬퍼. 반환 문자열이 비면 valid, 아니면 invalid. 모든 입력 컨트롤(`sd-textfield`/`sd-select`/`sd-modal-select-button` 등)이 내부에서 이걸로 required/형식 검증을 구현. 커스텀 입력 컴포넌트 작성 시 동일 패턴.
+
+## SdTypedTemplate (`ng-template[typed]`)
+
+`<ng-template>` 컨텍스트에 타입을 주는 디렉티브(런타임 동작 없음, 타입 가드만).
+
+- `typed: input.required<T>` — 컨텍스트 타입 토큰. `let-x` 변수에 `T` 타입이 추론됨. 사이드바/탑바 메뉴 재귀 템플릿이 사용.
+
+## SdItemOfTemplate (`ng-template[itemOf]`)
+
+항목 반복 템플릿에 항목 타입을 주는 디렉티브.
+
+- `itemOf: input.required<TItem[]>` — 항목 배열(타입 추론용 더미, 실제 반복은 부모가 수행).
+- 컨텍스트: `SdItemOfTemplateContext<TItem> = { $implicit; item; index: number; depth: number }`. `let-item="item"` / `let-index="index"` / `let-depth="depth"`.
+- 사용: `sd-shared-data-select`·`sd-calendar` 의 항목 템플릿. `<ng-template [itemOf]="items()" let-item="item">{{ item.name }}</ng-template>`.

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

@@ -1,55 +1,127 @@
-# @simplysm/angular — 부가 기능(테마·주소·에디터·시각화·칸반·프리셋)
+# @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 없음.
+### SdKanbanBoard<L, T> (`sd-kanban-board`)
 
-## SdAddressSearchModal
+레인(`L`)·카드(`T`) 드래그 보드의 루트. 드래그 종료 시 drop 정보 emit.
 
-`<sd-address-search-modal>` — 다음(카카오) 우편번호 검색 모달. `SdModalContentDef<Address>` 구현(`SdModalProvider.showAsync` 의 type 으로 사용). 스크립트 동적 로드 후 임베드, 선택 시 결과 emit.
+- `selectedValues: model<T[]>` — Shift+클릭으로 선택된 카드 값들.
+- `drop: output<SdKanbanBoardDropInfo<L, T>>` — 카드 drop 시 발화.
+- `SdKanbanBoardDropInfo<L, T> = { sourceKanbanValue?: T; targetLaneValue?: L; targetKanbanValue?: T }` — 옮긴 카드·대상 레인·대상 카드(앞에 끼움).
+- `SdKanbanDragRef`/`SdKanbanDropTarget` — 내부 드래그/드롭 인터페이스.
 
-- `close = output<Address>()` — 선택 결과. `Address = { postNumber?; address?; buildingName? }`(결측 보존).
-- input 없음. 스크립트 로드 실패 시 에러 메시지 표시.
+### SdKanbanLane<L, T> (`sd-kanban-lane`)
 
-## SdTiptapEditor
+레인(컬럼). 카드들을 담고 drop 대상이 됨.
 
-`<sd-tiptap-editor>` — TipTap 기반 리치텍스트 에디터(HTML 값, 툴바: 제목·굵게·기울임·밑줄·취소선·색상·리스트 등).
+- `value: input<L>` — 레인 값(drop 시 `targetLaneValue`).
+- `busy: boolean` — 레인 busy 오버레이.
+- `useCollapse: boolean` — 접기 토글 표시. `collapse: model<boolean>` — 접힘 상태.
+- 슬롯: `#titleTpl`(제목), `#toolTpl`(도구). 전체선택 체크박스는 선택 가능 카드가 있을 때.
 
-- `value = model<string>()` — HTML 콘텐츠. 빈 내용이면 `undefined`(결측 보존).
-- `disabled`/`readonly` — 비활성/읽기전용(편집 불가, 툴바 숨김).
-- `required` — 필수 검증(폼 연동).
-- `placeholder` — 빈 상태 안내(미지정 확장 시 적용).
-- `validatorFn?: (value) => string | undefined` — 커스텀 검증 메시지.
-- `extensions?: AnyExtension[]` — TipTap 확장 직접 지정(미지정 시 기본 확장 + placeholder).
-- `editor: WritableSignal<Editor | undefined>` — 내부 TipTap 인스턴스(@internal, 고급/테스트용).
+### SdKanban<L, T> (`sd-kanban`)
 
-## 시각화 컴포넌트
+카드. 드래그 소스 + 선택 대상.
 
-- `<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)`(로딩 스피너). 리사이즈 자동 반영.
+- `value: input<T>` — 카드 값.
+- `draggable: boolean` — true 면 드래그 가능.
+- `selectable: boolean` — true 면 Shift+클릭 선택 가능.
+- `contentClass: string` — 카드 본문 클래스.
+- 사용: `<sd-kanban-board (drop)="onDrop($event)"><sd-kanban-lane [value]="lane"><sd-kanban [value]="card" [draggable]="true">...</sd-kanban></sd-kanban-lane></sd-kanban-board>`.
 
-## SdKanbanBoard / SdKanbanLane / SdKanban
+## SdPermissionTable<TModule> (`sd-permission-table`)
 
-드래그 가능한 칸반 보드. 보드 > 레인 > 카드 계층.
+권한 트리를 표로 표시·편집(use/edit 체크박스). `SdAppStructureProvider.getPermissionsByStructure(...)` 결과를 입력.
 
-- `<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`.
+- `value: model<Record<string, boolean>>` — `<코드>.<use|edit>` → 부여 여부 맵.
+- `items: SdPermission<TModule>[]` — 권한 트리(routing-appstructure.md 의 `SdPermission`).
+- `disabled: boolean` — 편집 비활성(조회).
 
-타입: `SdKanbanBoardDropInfo<L,T>`, `SdKanbanDragRef<L,T>`(`value()`/`heightOnDrag()`), `SdKanbanDropTarget<L,T>`(`targetLaneValue()`/`targetKanbanValue?()`).
+## SdStatePreset<TState> (`sd-state-preset`)
 
-## SdStatePreset
+화면 검색/필터 상태를 이름붙은 프리셋으로 저장·복원(즐겨찾기). 프리셋은 `injectSdSystemConfigResource` 로 영속.
 
-`<sd-state-preset>` — 화면 상태(필터 등)를 명명 프리셋으로 저장·복원(시스템설정 영속화). 제네릭 `<TState>`.
+- `key: input.required<string>` — 프리셋 저장 키.
+- `state: model.required<TState>` — 현재 상태(프리셋 적용 시 이 모델에 set). 저장은 현재 state 를 스냅샷.
+- `size: "sm"|"lg"` — 버튼 크기.
+- `SdStatePresetDef<TState> = { name: string; state: TState }` — 저장된 프리셋 1개.
+- 별(추가)·저장·삭제 동작은 내장(이름 prompt/덮어쓰기 confirm 모달 사용).
 
-- `key = input.required<string>()` — 프리셋 저장 키(태그명과 결합).
-- `state = model.required<TState>()` — 현재 상태(저장/적용 대상). 프리셋 클릭 시 이 값으로 복원.
-- `size = input<"sm"|"lg">()` — 크기.
-- ⭐버튼=현재 상태 새 프리셋 저장, 각 프리셋=클릭 적용/저장/삭제. `SdStatePresetDef<TState> = { name: string; state: TState }`.
+## SdThemeProvider 관련 — SdThemeSelector (`sd-theme-selector`)
+
+글자 크기 증감 + 다크모드 스위치를 담은 드롭다운 UI. 내부에서 `SdThemeProvider`(infra.md)를 조작.
+
+- (입력 없음) 탑바 등에 `<sd-theme-selector />` 로 배치. 글자 크기는 `fontSizePresets` 단계, 다크는 `dark` 토글.
+
+## SdAddressSearchModal (`sd-address-search-modal`)
+
+다음(카카오) 우편번호 검색 모달(`SdModalContentDef<Address>`). 외부 스크립트를 동적 로드해 임베드.
+
+- `close: output<Address>` — 선택한 주소 emit.
+- `initialized: Signal<boolean>` — 스크립트 로드 완료 여부.
+- `Address = { postNumber?: string; address?: string; buildingName?: string }` — 결과(각 필드 결측 가능).
+- 사용: `const addr = await this._sdModal.showAsync({ type: SdAddressSearchModal, title: "주소 검색", inputs: {} }); if (!addr) return;`.
+
+## SdTiptapEditor (`sd-tiptap-editor`)
+
+Tiptap 기반 리치 텍스트(HTML) 에디터. 툴바 내장.
+
+- `value: model<string>` — HTML 문자열.
+- `disabled: boolean` — 비활성. `readonly: boolean` — 읽기 전용.
+- `required: boolean` — 빈 값이면 invalid. `validatorFn: (value) => string | undefined` — 커스텀 검증.
+- `placeholder: string` — 빈 에디터 안내.
+- `extensions: AnyExtension[]` — 추가 Tiptap 확장.
+
+## 시각화·표시 컴포넌트 (features/visual)
+
+### SdLabel (`sd-label`)
+
+배지/태그. `<ng-content>` 본문.
+
+- `theme: "primary"|"secondary"|"info"|"success"|"warning"|"danger"|"gray"|"blue-gray"` — 배경 색(미지정=회색 darker). 상태 표시에 의미별 색.
+- `color: string` — 임의 배경색 직접 지정(theme 대신).
+- `clickable: boolean` — true 면 포인터 커서 + hover 효과.
+
+### SdNote (`sd-note`)
+
+안내 박스(연한 배경). `<ng-content>` 본문.
+
+- `theme: "primary"|...|"blue-gray"` — 박스 색(미지정=회색 lightest).
+- `size: "sm"|"lg"` — 패딩.
+- `inset: boolean` — 테두리 제거.
+
+### SdProgress (`sd-progress`)
+
+가로 진행 바 + 퍼센트 텍스트.
+
+- `value: input.required<number>` — 진행값(0~1, percent 파이프로 표시).
+- `theme: input.required<...>` — 바 색(필수).
+- `size: "sm"|"lg"` / `inset: boolean` — 크기/테두리.
+
+### SdCalendar<T> (`sd-calendar`)
+
+월 달력 그리드에 항목을 날짜별로 배치. 항목 템플릿으로 셀 내용 렌더.
+
+- `items: input.required<T[]>` — 표시할 항목들.
+- `getItemDateFn: input.required<(item, index) => DateOnly>` — 항목의 날짜 추출.
+- `yearMonth: input<DateOnly>` — 표시 연월(기본 이번 달 1일).
+- `weekStartDay: number` — 주 시작 요일(0=일, 기본 0). `minDaysInFirstWeek: number` — 첫 주 최소 일수(기본 1).
+- 항목 템플릿: `<ng-template [itemOf]="items()" let-item="item">`(필수).
+
+### SdBarcode (`sd-barcode`)
+
+바코드/QR 등을 SVG 로 렌더(bwip-js).
+
+- `type: input.required<BarcodeType>` — 바코드 종류. `BarcodeType` 은 `"code128"|"qrcode"|"ean13"|"datamatrix"|...`(bwip-js 의 100+ 심볼로지 리터럴 유니온). 대표: `"code128"`(범용 1D), `"qrcode"`(QR), `"ean13"`/`"upca"`(상품), `"datamatrix"`(소형 2D).
+- `value: string` — 인코딩할 데이터(빈 값이면 미렌더).
+
+### SdEcharts (`sd-echarts`)
+
+ECharts 차트(SVG 렌더). 리사이즈 자동 대응.
+
+- `option: input.required<echarts.EChartsOption>` — 차트 옵션. 변경 시 재설정.
+- `notMerge: boolean` — true 면 옵션 병합 없이 교체(기본 false=병합).
+- `loading: boolean` — true 면 로딩 인디케이터.

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

@@ -1,74 +1,91 @@
-# @simplysm/angular — 설정·로깅·서비스 인프라
+# @simplysm/angular — 부트스트랩·전역 프로바이더
 
-앱 부트스트랩과 함께 읽히는 인프라 묶음. `provideSdAngular()` 로 전역 프로바이더를 등록하고, 클라이언트명·테마영속화·시스템로그·로컬스토리지·시스템설정·서비스 클라이언트 연결·전역 에러 처리를 담당.
+앱 시작 시 1회 배선하는 `provideSdAngular` 와, `providedIn: "root"` 로 어디서든 inject 하는 전역 프로바이더(테마·로컬스토리지·시스템설정·시스템로그·서비스클라이언트·설정값)를 모은 군. 화면이 아니라 부트스트랩(`provideAppInitializer`)·앱 셸 코드에서 같이 읽힌다.
 
 ## provideSdAngular
 
-`provideSdAngular(opt: { clientName: string }): EnvironmentProviders` — 앱 부트스트랩 시 `providers` 에 넣는 핵심 프로바이더 묶음.
-
-- `opt.clientName` — 클라이언트 식별명. `SdAngularConfigProvider.clientName` 에 주입되어 로컬스토리지 키 prefix·서비스 클라이언트 생성에 사용. 앱마다 고유해야 함.
-
-등록 내용(본문 기준): 이미지 경고 비활성화, ng-icon 기본 설정, 다크모드/폰트크기 localStorage 영속화 effect, `window` 의 `error`/`unhandledrejection` → ErrorHandler 위임, `SdOptionEventPlugin`(이벤트 옵션 플러그인), `SdGlobalErrorHandlerPlugin`(ErrorHandler), zoneless 변경감지, Service Worker 업데이트 폴링(지수 백오프, 발견 시 confirm 후 reload), 라우터 내비게이션 중 `SdBusyProvider.globalBusyCount` 증감.
-
-```typescript
-bootstrapApplication(AppComponent, {
-  providers: [provideRouter(routes), provideSdAngular({ clientName: "my-app" })],
-});
+```ts
+function provideSdAngular(opt: { clientName: string }): EnvironmentProviders
 ```
 
-## setupBgTheme
+`ApplicationConfig.providers` 에 1개 넣으면 simplysm 클라이언트 동작 전체가 배선됨. 내부 처리:
 
-`setupBgTheme(options?: { theme?: ..., lightness?: "lightest" | "lighter" }): void` — 컴포넌트 활성 동안 `document.body` 의 `--background-color` 를 테마 색으로 지정(effect, cleanup 시 복원). 컴포넌트 생성자/필드에서 호출.
+- `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 표시.
 
-- `options.theme` — `"primary"|"secondary"|"info"|"success"|"warning"|"danger"|"gray"|"blue-gray"`. 배경 테마 색. 미지정 시 변수 비움(`""`).
-- `options.lightness` — `"lightest"|"lighter"`. 밝기 단계. 기본 `"lightest"`.
+사용: `bootstrapApplication(AppRoot, { providers: [provideSdAngular({ clientName: CLIENT_NAME }), provideRouter(...), ...] })`.
 
 ## SdAngularConfigProvider
 
-`class SdAngularConfigProvider { clientName!: string }` — `provideSdAngular` 가 설정하는 클라이언트명 보관 루트 프로바이더. 다른 프로바이더가 inject 해 prefix 로 사용.
+- `clientName: string` — `provideSdAngular` 가 주입하는 클라이언트 이름. 다른 provider 가 prefix/식별자로 참조. 보통 직접 set 하지 않음.
 
-- `clientName` — 클라이언트 식별명. 직접 set 하지 말고 `provideSdAngular({clientName})` 로 주입됨.
+## SdThemeProvider
 
-## SdSystemLogProvider
+다크모드·기본 글자크기 전역 상태. `provideSdAngular` 가 로컬스토리지 동기화를 자동 배선하므로 화면에서는 토글만 호출.
 
-`class SdSystemLogProvider` — 시스템 로그 기록 루트 프로바이더. 콘솔 로깅 + 선택적 외부 전송.
+- `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)`.
 
-- `writeFn?: (severity, ...data) => Promise<void> | void` — 외부 로그 싱크. 지정 시 `writeAsync` 가 콘솔 출력 후 이 함수도 호출. 미지정이면 콘솔만.
-- `writeAsync(severity: "error"|"warn"|"log", ...data): Promise<void>` — 로그 기록. `severity` 로 로거 메서드 선택 후 `writeFn` 있으면 await(실패 시 내부 로깅만, throw 안 함).
+## SdLocalStorageProvider<T>
 
-## SdLocalStorageProvider
+`localStorage` 를 `<clientName>.<key>` 네임스페이스로 JSON 직렬화해 읽고 씀. 제네릭 `T` 로 키→값 타입 매핑.
 
-`class SdLocalStorageProvider<T>` — `clientName.{key}` prefix 로 localStorage 에 JSON 저장하는 타입드 래퍼.
+- `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)`.
 
-- `set<K>(key, value)` — `JSON.stringify` 후 저장. `key` 는 `T` 의 키.
-- `get<K>(key): T[K] | undefined` — 파싱 반환. 없거나 파싱 실패 시 `undefined`(결측 보존).
-- `remove(key)` — 항목 제거.
+## SdSystemConfigProvider<T>
 
-## SdSystemConfigProvider
+화면별 설정(시트 컬럼 구성, 모달 위치 등) 영속화. 외부 저장 함수(`fn`) 가 꽂혀 있으면 그쪽, 없으면 `SdLocalStorageProvider` 로 폴백.
 
-`class SdSystemConfigProvider<T>` — 시스템 설정 저장소. 외부 `fn` 이 있으면 서버, 없으면 localStorage 폴백.
+- `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): PromiseLike<unknown> }` — 외부 저장 핸들러. 지정 시 서버 영속, 미지정 시 `SdLocalStorageProvider` 사용.
-- `setAsync<K>(key, data: T[K] | undefined)` — 저장. `fn` 있으면 위임, 없고 `data==null` 이면 remove, 아니면 localStorage set.
-- `getAsync(key)` — 조회. `fn` 있으면 위임, 없으면 localStorage get.
+## injectSdSystemConfigResource<T>
 
-## injectSdSystemConfigResource
+```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;
+}
+```
 
-`injectSdSystemConfigResource<T>(options: { key: Signal<string | undefined> })` — 호스트 엘리먼트 태그명 + `key` 로 시스템 설정을 읽고 쓰는 Angular `resource` 래퍼. 시트/상태프리셋이 컬럼·프리셋 영속화에 사용.
+`SdSystemConfigProvider` 위에 Angular `resource` 를 얹은 컴포넌트 스코프 헬퍼. 실제 저장 키는 `<호스트엘리먼트태그>.<key>` 로 자동 분리되어 같은 컴포넌트 종류끼리 설정을 공유.
 
-- `options.key` — 설정 키 시그널. `undefined` 면 로드 안 함(결측). 실제 키는 `{태그명}.{key}`.
-- 반환: `{ value, isLoading, status, hasValue(), reload(), set(value), update(fn) }` — `set` 은 즉시 resource 갱신 + 마이크로태스크로 `setAsync` 영속화(실패 시 ErrorHandler 위임).
+- `options.key: Signal<string | undefined>` — 설정 키 signal. `undefined` 면 로드/저장 스킵. 컴포넌트의 `key` 입력을 그대로 넘김.
+- `set` — 메모리 즉시 반영 후 microtask 로 `setAsync` 영속(실패 시 ErrorHandler 로 전파, silent skip 아님).
+- `sd-sheet` 가 컬럼 설정을 이걸로 보관(sheet.md 참조).
 
-## SdServiceClientFactoryProvider
+## SdSystemLogProvider
 
-`class SdServiceClientFactoryProvider` — 키별 `ServiceClient` 연결 풀. 요청/응답 진행률을 토스트 progress 로 표시.
+프레임워크가 잡은 에러/경고를 콘솔 + (배선 시) 외부 저장소로 적재. 자세한 배선·자동 적재 지점은 `client-system-log.md` 참조.
 
-- `connectAsync(key, options?: Partial<ServiceConnectionOptions>)` — `key` 로 클라이언트 연결. 호스트/포트/ssl 은 `location` 기본값 + `options` 머지. 이미 연결/이미 끊긴 키면 throw.
-- `closeAsync(key)` — 연결 종료 후 풀에서 제거(미연결 키면 throw).
-- `get(key): ServiceClient` — 연결된 클라이언트 반환. 미연결/끊긴 키면 throw.
+- `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)`.
 
-## SdGlobalErrorHandlerPlugin
+## SdServiceClientFactoryProvider
 
-`class SdGlobalErrorHandlerPlugin implements ErrorHandler` — `provideSdAngular` 가 `ErrorHandler` 로 등록하는 전역 에러 핸들러.
+`@simplysm/service-client` 의 `ServiceClient` 를 key 별로 생성·보관·종료. 요청/응답 진행률을 자동으로 토스트 progress 로 표시.
 
-- `handleError(event)` — `PromiseRejectionEvent`/`ErrorEvent`/`Error`/기타를 분기해 메시지 구성 → 시스템 로그 기록 + 앱 파괴 후 전체화면 에러 오버레이 표시(클릭 시 reload). 최초 1회만 오버레이 노출. 직접 호출보다 Angular 가 자동 호출.
+- `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 경유.

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

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