@simplysm/sd-claude 14.0.97 → 14.0.99

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

@@ -1,136 +1,104 @@
 # @simplysm/angular — 라우팅·메뉴·권한(app-structure)
 
-라우터 링크·현재 페이지 식별·뷰 컨텍스트(page/control/modal)·이탈 가드, 그리고 앱 구조 트리에서 메뉴·권한을 파생하는 군. 화면 컴포넌트의 표준 시그널 `viewType`, 권한 가드 `injectPermsSignal`, 사이드바/탑바 메뉴가 이 군에 의존.
+라우터 링크·현재 페이지 식별·뷰 컨텍스트(page/control/modal)·이탈 가드, 그리고 앱 구조 트리에서 메뉴·권한을 파생하는 군. 화면 컴포넌트의 표준 시그널 `viewType`, 권한 가드 `injectPermsSignal`, 사이드바/탑바 메뉴가 이 군에 의존. 메뉴·권한 정의 절차는 [client-app-structure.md](../manuals/client-app-structure.md) 참조.
 
 ## 라우팅 디렉티브·프로바이더
 
-### SdRouterLink — `[sdRouterLink]`
+### `SdRouterLink` — `[sdRouterLink]`
 
-```ts
-option = input<{ link: string; params?: Record<string,string>;
-  window?: { width?: number; height?: number };
-  outletName?: string; queryParams?: Record<string,string> } | undefined>(undefined, { alias: "sdRouterLink" });
-```
+- `option: input<{ link: string; params?: Record<string,string>; window?: { width?: number; height?: number }; outletName?: string; queryParams?: Record<string,string> } | undefined>({ alias: "sdRouterLink" })` — 이동 대상. `link` = 라우트 경로, `params` = 라우트 파라미터, `outletName` 지정 시 named outlet, `window` 지정 시 팝업 창 크기.
+- 클릭 동작: `Alt+click` 무시. 팝업 창 모드면 새 창; `Ctrl/Shift+click` 이면 새 탭/창; `outletName` 없으면 `Router.navigate([link, ...params])`; 있으면 outlet navigate.
 
-- 클릭 시 라우터 내비게이트. `option.link`=경로, `params`=matrix 파라미터, `queryParams`=쿼리, `outletName`=명명 outlet. Ctrl/Shift 클릭 또는 윈도우 모드면 새 창으로(`window.width/height`). Alt 클릭은 무시.
-
-```html
-<sd-list-item [sdRouterLink]="{ link: '/home/order/list' }">주문</sd-list-item>
-```
-
-### SdNavigateWindowProvider
-
-```ts
-@Injectable({ providedIn: "root" }) class SdNavigateWindowProvider {
-  get isWindow: boolean;
-  open(navigate: string, params?: Record<string,string>, features?: string): void;
-}
-```
+### `SdNavigateWindowProvider`
 
-- `isWindow` — 현재가 팝업 창 모드인지(hash 의 `window=true`). `open(navigate, params, features)` — 새 창/탭으로 화면을 염(features 있으면 팝업, 없으면 새 탭). 부모 종료 시 자식 창 일괄 닫힘.
+`@Injectable({ providedIn: "root" })`.
 
-## 페이지 식별·뷰 컨텍스트 시그널
+- `get isWindow(): boolean` — 현재 hash query 에 `window=true` 가 있는지(팝업 창 컨텍스트 여부).
+- `open(navigate: string, params?: Record<string,string>, features?: string): void` — 이미 팝업 창이거나 `features` 지정 시 새 브라우저 창(`window.open`), 아니면 `_blank` 탭으로 `#{navigate};{params}` 열기.
 
-주입 컨텍스트(컴포넌트 생성자)에서 호출하는 헬퍼.
+## 현재 페이지·뷰 식별
 
-### injectFullPageCodeSignal / injectCurrentPageCodeSignal
+### `injectCurrentPageCodeSignal` / `injectFullPageCodeSignal`
 
 ```ts
-injectFullPageCodeSignal(): Signal<string>;
-injectCurrentPageCodeSignal(): Signal<string> | undefined;
+function injectCurrentPageCodeSignal(): Signal<string> | undefined
+function injectFullPageCodeSignal(): Signal<string>
 ```
 
-- `injectFullPageCodeSignal` — 현재 URL 의 전체 페이지 코드(`a.b.c`, `/home/` 이후 세그먼트를 `.` 결합). 메뉴 선택 판정에 사용.
-- `injectCurrentPageCodeSignal` — 현재 라우트 컴포넌트 기준 페이지 코드(중첩 라우트의 자기 위치). `ActivatedRoute` 없으면 undefined.
+- `injectCurrentPageCodeSignal` — `ActivatedRoute` 없으면 `undefined`; 있으면 활성 라우트 URL 세그먼트(앞 2개 제외)를 `"."` 로 이은 코드.
+- `injectFullPageCodeSignal` — `Router` URL(`NavigationEnd` 추적)을 `/` 분리, 앞 2개 제외, `;`/`?` 접미 제거 후 `"."` 로 이은 페이지 코드. 메뉴 선택 판정 등에 사용.
 
-### injectViewTitleSignal / injectViewTypeSignal
+### `injectViewTitleSignal`
 
 ```ts
-injectViewTitleSignal(): Signal<string>;
-injectViewTypeSignal(): Signal<SdViewType>; // "page" | "modal" | "control"
+function injectViewTitleSignal(): Signal<string>
 ```
 
-- `injectViewTitleSignal` — 현재 뷰 제목. 모달이면 모달 title, 페이지면 app-structure 에서 코드로 제목 조회. `sd-base-container` 가 사용.
-- `injectViewTypeSignal` — 현재 뷰 컨텍스트. `"modal"`=모달 안, `"page"`=라우팅 진입 단위(컴포넌트 selector 가 라우트 컴포넌트와 일치+풀코드 매칭), 그 외 `"control"`(임베드). crud 골격의 `viewType` 입력에 그대로 전달.
+- 활성 모달 안이면 모달 `title`, 아니면 `SdAppStructureProvider.findTitleByFullCode(...)` 로 화면 제목. 엑셀 파일명·탑바 제목 등에.
 
-### setupCanDeactivate
+### `injectViewTypeSignal` / `SdViewType`
 
 ```ts
-setupCanDeactivate(fn: () => boolean): void;
+function injectViewTypeSignal(): Signal<SdViewType>
+type SdViewType = "page" | "modal" | "control"
 ```
 
-- 화면 이탈 가드 등록. 모달 안이면 `SdActivatedModalProvider.canDeactivateFn` 에, 페이지면 라우트 `canDeactivate` 에 연결(파괴 시 해제). `fn` 이 false 면 이탈 차단(미저장 변경 보호).
+- `"modal"` = 활성 모달 안에서 렌더; `"page"` = 라우트가 있고 컴포넌트 selector·코드가 일치하는 최상위 페이지; `"control"` = 그 외(라우트 없음·임베드 재사용). 화면 컴포넌트가 `viewType = injectViewTypeSignal()` 으로 받아 `sd-crud-*`/`sd-base-container` 에 전달.
 
-### 메뉴 유틸
+### `setupCanDeactivate`
 
 ```ts
-getMenuRouterLinkOption(menu: SdMenu): { link: string; queryParams: Record<string,string>|undefined } | undefined;
-getIsMenuSelected(menu: SdMenu, fullPageCode: string|undefined, customFn?: (menu: SdMenu)=>boolean): boolean;
+function setupCanDeactivate(fn: () => boolean): void
 ```
 
-- `getMenuRouterLinkOption` — 리프 메뉴(자식·url 없음)면 `/home/<codeChain>` 링크 옵션 반환, 그룹/외부url 이면 undefined(클릭 비내비게이트). `sdRouterLink` 에 전달.
-- `getIsMenuSelected` — 메뉴가 현재 페이지인지. `customFn` 있으면 그 결과, 없으면 코드 일치. 메뉴 컴포넌트가 선택 강조에 사용.
+- 이탈 가드 등록. 모달 컨텍스트면 `SdActivatedModalProvider.canDeactivateFn = fn`; 라우트 페이지면 route config 의 `canDeactivate` 에 `fn()` 반환 가드를 push(파괴 시 제거). `fn()` 이 false 면 이탈 차단. detail 의 미저장 변경 가드에 사용([client-component.md](../manuals/client-component.md)).
 
-## 앱 구조(메뉴·권한)
+## 메뉴 유틸
 
-### SdAppStructureProvider
+### `getMenuRouterLinkOption` / `getIsMenuSelected`
 
 ```ts
-@Injectable({ providedIn: "root" }) class SdAppStructureProvider<TModule = unknown> {
-  usableModules: WritableSignal<TModule[] | undefined>;
-  permRecord: WritableSignal<Record<string, boolean> | undefined>;
-  items: WritableSignal<AppStructureItem<TModule>[]>;
-  initialize(items): void;
-  usableMenus = computed<SdMenu[]>(...);
-  usableFlatMenus = computed<SdFlatMenu<TModule>[]>(...);
-  getPermissionsByStructure(items, codeChain?): SdPermission<TModule>[];
-  getTitleByFullCode(fullCode): string;     // 못 찾으면 throw
-  findTitleByFullCode(fullCode): string | undefined; // 결측 보존
-  getItemChainByFullCode(fullCode): AppStructureItem<TModule>[];
-  getPermsByFullCode<K>(fullCodes: string[], permKeys: K[]): K[];
-}
+function getMenuRouterLinkOption(menu: SdMenu): { link: string; queryParams: Record<string,string> | undefined } | undefined
+function getIsMenuSelected(menu: SdMenu, fullPageCode: string | undefined, customFn?: (menu: SdMenu) => boolean): boolean
 ```
 
-- `initialize(items)` — 앱 구조 트리 주입. `usableModules`/`permRecord` 를 인증 후 채우면 메뉴/권한이 그에 맞게 필터됨.
-- `usableMenus` — 모듈·권한으로 필터된 메뉴 트리(사이드바/탑바용). `usableFlatMenus` — 평탄화된 메뉴(검색 등).
-- `getTitleByFullCode` 는 못 찾으면 throw, `findTitleByFullCode` 는 undefined(결측 보존) — 상황에 맞게 선택. `getPermsByFullCode` 는 주어진 코드들에 대해 보유한 권한 키만 반환.
+- `getMenuRouterLinkOption` — 그룹 메뉴(`children != null`)·외부 링크(`url != null`)면 `undefined`; leaf 면 `link = "/home/" + codeChain.join("/")`(`?query` 는 `queryParams` 로 분리). 사이드바/탑바 메뉴가 라우터 링크 생성에 사용.
+- `getIsMenuSelected` — `customFn` 있으면 그 결과, 아니면 `fullPageCode === menu.codeChain.join(".")`.
+
+## 앱 구조 프로바이더
 
-### injectPermsSignal
+### `injectPermsSignal`
 
 ```ts
-injectPermsSignal<K extends string>(viewCodes: string[], keys: K[]): Signal<K[]>;
+function injectPermsSignal<K extends string>(viewCodes: string[], keys: K[]): Signal<K[]>
 ```
 
-- 화면 권한 가드. `viewCodes`(보통 현재 화면 코드)에 대해 `keys`(`["use","edit"]` 등) 중 보유한 것만 반환하는 시그널. `perms().includes("use")` 로 분기.
+- 화면 fullCode(들)에 대해 사용자가 보유한 권한 action 키 배열을 `computed` 로 반환(`SdAppStructureProvider.getPermsByFullCode` 위임).
 
 ```ts
-perms = injectPermsSignal(["base.role"], ["use", "edit"]);
+perms = injectPermsSignal(["inventory.outbound-instruction"], ["use", "edit"]);
+// this.perms().includes("use")
 ```
 
-### SdAppStructureUtils
+### `SdAppStructureProvider<TModule>`
 
-```ts
-abstract class SdAppStructureUtils {
-  static getTitleByFullCode(items, fullCode): string;
-  static findTitleByFullCode(items, fullCode): string | undefined;
-  static getPermsByFullCode(items, fullCodes, permKeys, permRecord): K[];
-  static getItemChainByFullCode(items, fullCode): AppStructureItem[];
-  static getMenus(items, codeChain, usableModules, permRecord): SdMenu[];
-  static getFlatMenus(items, usableModules, permRecord): SdFlatMenu[];
-  static getPermissions(items, codeChain, usableModules): SdPermission[];
-  static getFlatPermissions(items, usableModules);
-}
-```
+`@Injectable({ providedIn: "root" })`. 앱 메뉴·권한 트리의 단일 소스. 부트스트랩에서 `initialize(items)` 로 연결.
 
-- 트리에서 메뉴/권한/제목/체인을 계산하는 순수 정적 유틸(`SdAppStructureProvider` 가 위임). provider 없이 트리만으로 파생할 때 직접 호출.
+- 시그널: `usableModules: WritableSignal<TModule[] | undefined>` / `permRecord: WritableSignal<Record<string, boolean> | undefined>` / `items: WritableSignal<AppStructureItem<TModule>[]>`.
+- computed: `usableMenus: Signal<SdMenu[]>` / `usableFlatMenus: Signal<SdFlatMenu<TModule>[]>`.
+- 메서드:
+  - `initialize(items): void` — `items` set.
+  - `getPermissionsByStructure(items, codeChain?): SdPermission<TModule>[]` — 권한 테이블용 권한 트리.
+  - `getTitleByFullCode(fullCode): string`(없으면 throw) / `findTitleByFullCode(fullCode): string | undefined`.
+  - `getItemChainByFullCode(fullCode): AppStructureItem<TModule>[]`.
+  - `getPermsByFullCode<K extends string>(fullCodes, permKeys): K[]`.
 
-### 타입
+### `SdAppStructureUtils`
 
-```ts
-SdMenu { title: string; codeChain: string[]; url?: string; icon?: string; children?: SdMenu[] }
-SdFlatMenu<TModule> { titleChain: string[]; codeChain: string[]; modulesChain: TModule[][] }
-SdPermission<TModule> { title; codeChain; modules?; perms?: ("use"|"edit")[]; children? }
-SdViewType = "page" | "modal" | "control"
-```
+static 메서드만 가진 abstract class(`SdAppStructureProvider` 의 순수 함수 형태). `getTitleByFullCode`/`findTitleByFullCode`/`getPermsByFullCode`/`getItemChainByFullCode`/`getMenus`/`getFlatMenus`/`getPermissions`/`getFlatPermissions` — 각각 `items: AppStructureItem[]` 을 첫 인자로 받아 메뉴·권한·제목을 파생. provider 가 이를 시그널로 래핑.
+
+## 타입
 
-- `SdMenu` — 메뉴 트리 노드(레이아웃 메뉴 컴포넌트 입력). `SdFlatMenu` — 평탄화 메뉴. `SdPermission` — 권한 트리 노드(`SdPermissionTable` 입력, features.md). `SdViewType` — crud/뷰 컨텍스트.
+- `SdMenu` — `{ title: string; codeChain: string[]; url?: string; icon?: string; children?: SdMenu[] }`. 메뉴 트리 노드. 사이드바/탑바 메뉴가 소비.
+- `SdFlatMenu<TModule>` — `{ titleChain: string[]; codeChain: string[]; modulesChain: TModule[][] }`. leaf 메뉴를 평탄화한 형태.
+- `SdPermission<TModule>` — `{ title: string; codeChain: string[]; modules: TModule[] | undefined; perms: ("use"|"edit")[] | undefined; children: SdPermission<TModule>[] | undefined }`. 권한 트리 노드(`perms`: `"use"`=조회·`"edit"`=편집). `SdPermissionTable` 의 `items` 입력 타입([crud.md](./crud.md)).

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

@@ -1,107 +1,115 @@
-# @simplysm/angular — 공유 마스터 데이터
+# @simplysm/angular — 공유 마스터 데이터·선택 매니저
 
-고객사·품목 등 자주 참조하는 마스터 데이터를 한 번 등록해 어느 화면에서든 공유 시그널로 쓰고, 그 데이터를 선택하는 드롭다운/버튼/리스트 컨트롤을 제공하는 군. 등록·항목 추가 절차는 [client-shared-data.md](../manuals/client-shared-data.md) 참조.
+고객사·품목 등 자주 참조하는 마스터 데이터를 한 번 등록해 어느 화면에서든 공유 시그널로 쓰고, 그 데이터를 선택하는 드롭다운/버튼/리스트 컨트롤과, 시트·리스트의 선택/정렬/펼침 상태를 관리하는 composable 매니저를 제공하는 군. 등록·항목 추가·선택 모달·좌측목록+우측상세 절차는 [client-shared-data.md](../manuals/client-shared-data.md) 참조.
 
-## SdSharedDataProvider
+## `SdSharedDataProvider<T>`
 
-```ts
-@Injectable() abstract class SdSharedDataProvider<T extends Record<string, SharedDataBase<string|number>>> {
-  loadingCount: WritableSignal<number>;
-  abstract initialize(): void;
-  register<K>(name: K, info: SharedDataInfo<T[K]>): void;
-  getHandle<K>(name: K): SharedDataHandle<T[K]>;
-  emitAsync<K>(name: K, changeKeys?: (string|number)[]): Promise<void>;
-  wait(): Promise<void>;
-}
-```
+`@Injectable()` **abstract**. 앱이 상속해 `initialize()` 에서 데이터를 `register` (root 별칭 등록 필요). `T extends Record<string, SharedDataBase<string|number>>`.
 
-- 추상 클래스 — 앱에서 상속(`AppSharedDataProvider`)해 `initialize()` 안에서 `register`. `T` 는 이름→항목타입 매핑.
-- `register(name, info)` — 마스터 데이터 등록. 재등록 시 이전 리스너 정리 + generation 증가로 이전 이벤트 무시 후 재로드.
-- `getHandle(name)` — 핸들 반환(첫 접근 시 lazy 로드 + 변경 이벤트 리스너 등록). 미등록이면 throw.
-- `emitAsync(name, changeKeys?)` — 변경 통지 이벤트 발생. `changeKeys` 지정 시 해당 키만 부분 갱신, 미지정 시 전체 리로드. CRUD 저장/삭제 후 호출해 다른 화면을 동기화.
-- `wait()` — 진행 중인 로드(`loadingCount`)가 끝날 때까지 대기. `sd-base-container` 의 ready 게이트가 사용.
+- `loadingCount: WritableSignal<number>` (초기 0) — 로드 중 카운트.
+- `abstract initialize(): void` — 하위에서 `register` 호출.
+- `register<K>(name: K, info: SharedDataInfo<T[K]>): void` — 데이터 항목 등록(lazy; 즉시 로드 안 함). 재등록 시 기존 리스너 제거·generation 증가로 stale 이벤트 무시.
+- `getHandle<K>(name: K): SharedDataHandle<T[K]>` — 핸들 반환(첫 접근 시 lazy 로드·리스너 등록). 미등록 시 throw.
+- `emitAsync<K>(name: K, changeKeys?: (string|number)[]): Promise<void>` — 변경 통지. `changeKeys` 생략 = 전체 재로드, 지정 = 그 키들만 부분 갱신. 저장·삭제 후 호출해 공유데이터를 최신화.
+- `wait(): Promise<void>` — `loadingCount <= 0` 까지 대기.
 
-### 관련 타입
+타입:
+- `SharedDataBase<TKey extends string|number>` — 항목 매직 필드: `__valueKey: TKey`(키) / `__searchText: string`(검색용) / `__isHidden: boolean`(숨김) / `__parentKey?: TKey`(트리 부모). getter select 결과에 포함 필수.
+- `SharedDataInfo<T>` — `{ serviceKey: string; getter: (changeKeys?) => Promise<T[]>; filter?: unknown; orderBy?: (item) => string|number|DateOnly|DateTime|Time|undefined }`. `getter(changeKeys)` 는 changeKeys 주어지면 그 키만 재조회(incremental).
+- `SharedDataHandle<T>` — `{ items: Signal<T[]>; get(key): T | undefined }`. 화면이 `useSharedSignal(name)` 으로 받아 `items()`·`get(id)` 사용.
+- `SdSharedDataChangeEvent` — `defineEvent<{ name; filter }, (string|number)[] | undefined>("SdSharedDataChange")`. provider 내부 통지 이벤트.
 
-```ts
-SharedDataBase<TKey> { __valueKey: TKey; __searchText: string; __isHidden: boolean; __parentKey?: TKey }
-SharedDataInfo<T> { serviceKey: string; getter: (changeKeys?) => Promise<T[]>; filter?; orderBy?: (item) => ...|undefined }
-SharedDataHandle<T> { items: Signal<T[]>; get(key): T | undefined }
-SdSharedDataChangeEvent // defineEvent — 변경 통지 이벤트 정의
-```
+## `SdSharedDataSelect<TItem, TMode, TModal>` — `<sd-shared-data-select>`
 
-- `SharedDataBase` — 모든 공유 항목이 가져야 할 매직 필드: `__valueKey`(키), `__searchText`(검색 텍스트), `__isHidden`(숨김 여부), `__parentKey`(트리 부모, 선택).
-- `SharedDataInfo.getter(changeKeys)` — DB 조회 함수. changeKeys 주어지면 그 키만 재조회(incremental refresh). `orderBy` 는 정렬 키 반환. `SharedDataHandle.get(key)` 로 단건 O(1) 조회.
+검색·트리(`__parentKey`) 가능한 공유데이터 드롭다운(`sd-select` 래핑). 폼 입력의 공유 데이터 선택지에 사용.
 
-```ts
-sharedProducts = useSharedSignal("품목"); // 앱 헬퍼
-// sharedProducts.items() / sharedProducts.get(id)
+- `items: input.required<TItem[]>` — 소스 목록(`sharedX.items()`).
+- `value: model<...>` — single 이면 `키|undefined`, multi 면 `키[]`.
+- `selectMode: TMode` (기본 `"single"`) — `"single"`/`"multi"`.
+- `required: boolean` — true(single)면 "미지정" 옵션 숨김.
+- `useUndefined: boolean` — multi 에서 "미지정" 항목 표시.
+- `disabled`/`inset`/`inline`/`size: "sm"|"lg"`/`selectClass`/`multiSelectionDisplayDirection: "vertical"`.
+- `filterFn: (item, index, ...params) => boolean` + `filterFnParams: any[]` — 표시 전 필터.
+- `getIsHiddenFn` (기본 `(item) => item.__isHidden`) / `getSearchTextFn` (기본 `(item) => item.__searchText`) / `displayOrderByFn` — 숨김/검색텍스트/정렬 커스터마이즈.
+- `modal: SdSelectModalInfo<TModal>` — 설정 시 검색 모달 버튼(선택 갱신). `editModal: SdModalInfo<SdModalContentDef<boolean>>` — 관리 전용 모달 버튼(선택 안 바꿈). (선택/관리 모달 규약은 [client-shared-data.md](../manuals/client-shared-data.md))
+- 콘텐츠: `[itemOf]` 항목 템플릿, `#undefinedTpl`("미지정" 라벨).
+
+```html
+<sd-shared-data-select [items]="sharedCustomers.items()" [(value)]="data().customerId" (valueChange)="mark(data)">
+  <ng-template [itemOf]="sharedCustomers.items()" let-item="item">{{ item.name }}</ng-template>
+</sd-shared-data-select>
 ```
 
-## 선택 컨트롤
+## `SdSharedDataSelectButton<TItem, TMode, TModal>` — `<sd-shared-data-select-button>`
 
-### SdSharedDataSelect — `<sd-shared-data-select>`
+모달로 선택하는 버튼(`sd-modal-select-button` 래핑).
 
-```ts
-value = model<SelectModeValue<TItem["__valueKey"] | undefined>[TMode]>();
-items = input.required<TItem[]>();
-disabled; required; useUndefined; inset; inline;
-size = input<"sm"|"lg">(); selectMode = input<TMode>("single"); // "single" | "multi"
-filterFn = input<(item, index, ...params) => boolean>(); filterFnParams = input<any[]>();
-modal = input<SdSelectModalInfo<TModal>>(); editModal = input<SdModalInfo<SdModalContentDef<boolean>>>();
-selectClass; multiSelectionDisplayDirection = input<"vertical">();
-getIsHiddenFn = input(item => item.__isHidden); getSearchTextFn = input(item => item.__searchText);
-displayOrderByFn = input<(item) => ...|undefined>();
-// 콘텐츠: [itemOf] 템플릿(항목 렌더), #undefinedTpl(미지정 표시)
-```
+- `items: TItem[]` (기본 `[]`) — 선택 항목 표시 해석용.
+- `modal: input.required<SdSelectModalInfo<TModal>>` — 선택 모달(필수).
+- `value: model<SelectModeValue<string|number>[TMode]>` / `selectMode: TMode`(기본 `"single"`).
+- `disabled`/`required`/`inset`/`size: "sm"|"lg"`.
+- 콘텐츠: `[itemOf]` 항목 템플릿(필수).
+
+## `SdSharedDataSelectList<TItem, TModal>` — `<sd-shared-data-select-list>`
+
+검색·페이지 가능한 단일 선택 리스트. 좌측목록+우측상세 레이아웃의 마스터로 사용.
 
-- 공유데이터 드롭다운 선택. `value` 는 선택된 `__valueKey`(single) 또는 키 배열(multi). `items` 에 `sharedX.items()` 전달.
-- `selectMode` — `"single"`/`"multi"`. `useUndefined`=multi 에서 "미지정" 항목 노출, `required=false`+single 이면 미지정 선택 가능. 내부 검색바로 `__searchText` 필터(부모키 트리면 자식 매칭 포함).
-- `modal` — 관리·선택 모달(`selectMode:"single"`+현재 키 주입, 결과로 선택 갱신). `editModal` — 관리 전용(선택 변경 없음). 둘 다 `<sd-select-button>` 아이콘으로 노출.
-- `filterFn`/`displayOrderByFn` — 표시 필터/정렬. `getIsHiddenFn`/`getSearchTextFn` — 숨김·검색텍스트 추출 커스텀(기본 매직필드). `__parentKey` 있으면 트리(`getChildrenFn` 자동).
+- `selectedItem: model<TItem>` — 현재 선택(항목 객체). `canChangeFn` 가드(`setupModelHook`). `items` 변경 시 `__valueKey` 로 재해석 자동 동기.
+- `items: input.required<TItem[]>`.
+- `canChangeFn: (item: TItem | undefined) => boolean | Promise<boolean>` (기본 `() => true`) — 선택 변경 가드(다른 마스터로 전환 전 미저장 변경 확인 등).
+- `selectedIcon: string` — 선택 항목 아이콘. `useUndefined: boolean` — "미지정" 항목. `header: string` — 헤더 텍스트. `pageItemCount: number` — `>0` 이면 그 크기로 페이지네이션.
+- `filterFn: (item, index) => boolean`.
+- `modal: SdSelectModalInfo<TModal>` — 설정 시 외부 링크 모달 버튼(목록 관리·선택).
+- 콘텐츠: `#headerTpl` / `#filterTpl`(기본 검색 필드 대체) / `[itemOf]` / `#undefinedTpl`.
+- 메서드: `select(item)` / `toggle(item)` / `onModalButtonClick()`.
 
 ```html
-<sd-shared-data-select [items]="sharedProducts.items()" [(value)]="productId" [required]="true">
-  <ng-template [itemOf]="sharedProducts.items()" let-item="item">{{ item.name }}</ng-template>
-</sd-shared-data-select>
+<sd-shared-data-select-list class="flex-min" [items]="sharedRoles.items()" [(selectedItem)]="selectedRole" [header]="'역할'" [modal]="{ type: RoleList, title: '역할', inputs: {} }">
+  <ng-template [itemOf]="sharedRoles.items()" let-item="item">{{ item.name }}</ng-template>
+</sd-shared-data-select-list>
 ```
 
-### SdSharedDataSelectButton — `<sd-shared-data-select-button>`
+## `matchesSearchText`
 
 ```ts
-value = model<SelectModeValue<string|number>[TMode]>();
-items = input<TItem[]>([]); modal = input.required<SdSelectModalInfo<TModal>>();
-selectMode = input<TMode>("single"); disabled; required; inset; size = input<"sm"|"lg">();
-itemTplRef = contentChild.required(SdItemOfTemplate); // [itemOf] 템플릿(필수)
+function matchesSearchText(itemText: string, searchQuery: string | undefined): boolean
 ```
 
-- 모달로만 선택하는 버튼형(`SdModalSelectButton` 래핑). 선택된 항목을 `[itemOf]` 템플릿으로 표시(multi 면 콤마 구분). 항목이 많아 드롭다운보다 모달 검색이 나을 때.
+- `searchQuery` 를 공백으로 분리한 모든 단어가 `itemText` 에 (대소문자 무시) 부분 포함되면 `true`(AND 매칭). 단어 없으면 `true`. 공유데이터 select 의 검색 매칭에 사용.
 
-### SdSharedDataSelectList — `<sd-shared-data-select-list>`
+## 선택/정렬/펼침 매니저 (composable)
+
+시트·리스트가 내부적으로 쓰는 상태 매니저. 직접 사용은 커스텀 그리드를 만들 때.
+
+### `useSelectionManager<TItem, TKey>`
 
 ```ts
-selectedItem = model<TItem>();
-canChangeFn = input<(item: TItem | undefined) => boolean | Promise<boolean>>(() => true);
-items = input.required<TItem[]>(); selectedIcon = input<string>(); useUndefined;
-filterFn = input<(item, index) => boolean>(); modal = input<SdSelectModalInfo<TModal>>();
-header = input<string>(); pageItemCount = input<number>();
-// 콘텐츠: [itemOf](항목) #headerTpl #filterTpl #undefinedTpl
+useSelectionManager(options: {
+  displayItems: Signal<TItem[]>; selectedKeys: WritableSignal<TKey[]>;
+  selectMode: Signal<"single"|"multi"|undefined>;
+  getItemSelectableFn: Signal<((item) => boolean|string) | undefined>;
+  trackByFn: Signal<(item, index) => TKey>;
+})
 ```
 
-- 좌측 선택 목록형(master-detail 의 좌측 패널). `selectedItem` 은 항목 객체(키 아님). `canChangeFn` 으로 선택 전환 가드(미저장 변경 보호), Promise 가능.
-- `pageItemCount` 지정 시 페이징. `header`/`#headerTpl`=상단 제목, `#filterTpl`=검색 대체, `modal`=목록 관리 모달. 검색은 `__searchText` 매칭, `__isHidden` 항목 제외.
+반환: `hasSelectable`/`isAllSelected: Signal<boolean>`, `getSelectable(item): true | string | undefined`(불가=undefined, 가능=true, 사유=string), `getCanChangeFn(item)`, `select`/`deselect`/`toggle`/`toggleAll`/`isSelected`. single 은 교체, multi 는 추가(`obj.equal` 중복 제거).
 
-```html
-<sd-shared-data-select-list [items]="sharedRoles.items()" [(selectedItem)]="selectedRole"
-  [canChangeFn]="checkCanLeave" [header]="'역할'">
-  <ng-template [itemOf]="sharedRoles.items()" let-item="item">{{ item.name }}</ng-template>
-</sd-shared-data-select-list>
+### `useSortingManager`
+
+```ts
+useSortingManager(options: { sorts: WritableSignal<SortingDef[]> })
 ```
 
-### matchesSearchText
+반환: `defMap: Signal<Map<string, { indexText?: string; desc: boolean }>>`(다중 정렬 시 `indexText` "1"…"n"), `toggle(key, multiple)`(none→asc→desc→제거; `multiple=false` 면 전체 교체), `sort<T>(items): T[]`(안정 다중 키 정렬; null < non-null). `SortingDef` = `{ key: string; desc: boolean }`.
+
+### `useExpandingManager<T>`
 
 ```ts
-matchesSearchText(itemText: string, searchQuery: string | undefined): boolean;
+useExpandingManager(binding: {
+  items: Signal<T[]>; expandedItems: WritableSignal<T[]>;
+  getChildrenFn: Signal<((item, index) => T[] | undefined) | undefined>;
+  sort: (items: T[]) => T[];
+})
 ```
 
-- 공백 분리 AND 부분일치(대소문자 무시). 빈 쿼리면 true. 선택 컨트롤이 내부 검색에 사용하며, 커스텀 필터에서 재사용 가능.
+반환: `displayItems: Signal<T[]>`(평탄화·부모→자식 순), `hasExpandable`/`isAllExpanded: Signal<boolean>`, `toggle(item)`/`toggleAll()`/`isVisible(item)`(모든 조상 펼침 시 true)/`def(item): ExpandItemDef<T>`. `ExpandItemDef<T>` = `{ item: T; parentDef: ExpandItemDef<T> | undefined; hasChildren: boolean; depth: number }`.

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

@@ -1,100 +1,76 @@
 # @simplysm/angular — 시트(sd-sheet)
 
-다건 목록·편집 표(그리드). 컬럼 디렉티브 + 셀 템플릿으로 구성하며, 선택·정렬·페이지·트리펼침·셀 편집·컬럼 고정/리사이즈/설정저장을 내장. `sd-crud-list` 는 이 시트를 감싼 표준 골격([crud.md](./crud.md)). 셀은 항상 `<ng-template [cell]="items()" let-item="item">` 안에 렌더.
-
-## SdSheet — `<sd-sheet>`
-
-```ts
-key = input<string>(); items = input<TItem[]>([]);
-trackByFn = input<(item: TItem, index: number) => unknown>((item) => item);
-selectMode = input<"single" | "multi">();
-autoSelect = input<"click" | "focus">();
-getItemSelectableFn = input<(item: TItem) => boolean | string>();
-getChildrenFn = input<(item: TItem, index: number) => TItem[] | undefined>();
-useAutoSort = input(false);
-visiblePageCount = input(10); totalPageCount = input(0); itemsPerPage = input(0);
-focusMode = input<"row" | "cell">("cell");
-inset = input(false); contentStyle = input<string>(); hideConfigBar = input(false);
-getItemCellClassFn = input<(item, colKey) => string>();
-getItemCellStyleFn = input<(item, colKey) => string | undefined>();
-
-// outputs
-itemKeydown = output<SdSheetItemKeydownEventParam<TItem>>();   // { item, event }
-cellKeydown = output<SdSheetCellKeydownEventParam<TItem>>();   // { item, key, event }
-// models
-selectedKeys = model<unknown[]>([]); expandedItems = model<TItem[]>([]);
-sorts = model<SortingDef[]>([]); currentPage = model(0);
-columnControlsInput = input<readonly SdSheetColumn[]>([]); // 외부에서 컬럼 주입(crud 가 사용)
-```
-
-- `key` — 지정 시 사용자 컬럼 설정(폭/고정/숨김/순서)을 `injectSdSystemConfigResource` 로 영속(설정 버튼·설정 모달 노출). 미지정이면 설정 저장 없음.
-- `trackByFn` — 행 키 함수. `selectedKeys` 가 이 키 기준으로 동작. 서버 키가 있으면 그 키 반환.
-- `selectMode` — `"single"`=단일(좌측 화살표), `"multi"`=다중(좌측 체크박스+전체선택). undefined=선택 비활성. `autoSelect` `"click"`=행/셀 클릭 시 선택, `"focus"`=셀 포커스만으로 선택(키보드 위주).
-- `getItemSelectableFn` — 행별 선택 가능. `true`=가능, `false`=불가, `string`=불가+사유(툴팁). 본인 계정 삭제 차단 등.
-- `getChildrenFn` — 자식 반환(트리). 지정 시 펼침 컬럼·들여쓰기 표시, `expandedItems` 로 펼친 항목 관리.
-- `useAutoSort` — true 면 `sorts` 변경 시 시트가 직접 `items` 클라이언트 정렬. 서버측 정렬/페이징이면 false 로 두고 외부에서 재조회. `itemsPerPage>0`+`useAutoSort` 면 클라이언트 페이징, `totalPageCount>0` 이면 서버 페이징.
-- `focusMode` — `"cell"`=셀 단위 포커스 이동(편집·복사), `"row"`=행 단위(셀 인디케이터 숨김). `hideConfigBar`=상단 설정/페이징 바 숨김, `inset`=테두리 제거.
-- `getItemCellClassFn`/`getItemCellStyleFn` — 행+컬럼키별 클래스/스타일(예: 삭제행 취소선). `columnControlsInput` 은 래퍼(crud)가 자식 컬럼을 시트로 위임 투영할 때 사용.
+다건 목록·편집 표(그리드). 컬럼 디렉티브 + 셀 템플릿으로 구성하며 선택·정렬·페이지·트리펼침·셀 편집·컬럼 고정/리사이즈/설정저장을 내장. `sd-crud-list` 가 이 시트를 감싼 표준 골격([crud.md](./crud.md)). 셀 본문·요약 행 작성 규약은 [client-component.md](../manuals/client-component.md) 의 '시트 컬럼·셀 표준' 참조.
+
+## `SdSheet<TItem>` — `<sd-sheet>`
+
+- `items: TItem[]` (기본 `[]`) — 행 데이터.
+- `trackByFn: (item, index) => unknown` (기본 `(item) => item`) — 행 식별/추적.
+- `selectMode: "single"|"multi"|undefined` — `"multi"` = 체크박스 피처 컬럼 + 헤더 전체선택 + shift-click 범위 선택; `"single"` = 행별 화살표 셀렉터; `undefined` = 선택 UI 없음.
+- `autoSelect: "click"|"focus"|undefined` — `"click"` = 행/셀 클릭 시 선택; `"focus"` = 셀 포커스 시 선택; `undefined` = 자동 선택 없음.
+- `getItemSelectableFn: (item) => boolean | string | undefined` — 행별 선택 가능 여부. `true`=가능, `false`=불가, `string`=불가+사유 툴팁.
+- `getChildrenFn: (item, index) => TItem[] | undefined` — 설정 시 트리펼침 활성(펼침 피처 컬럼·depth·caret).
+- `useAutoSort: boolean` (기본 false) — true 면 표시 전 클라이언트 정렬(정렬 매니저). 서버 정렬/페이징이면 false.
+- `itemsPerPage: number` (기본 0) — 클라이언트 페이징 크기(`0`=페이징 없음).
+- `totalPageCount: number` (기본 0) — 외부 총 페이지 수(서버 페이징). `0` 이면 `items`/`itemsPerPage` 로 산출.
+- `visiblePageCount: number` (기본 10) — 페이지 번호 표시 개수.
+- `key: string` — 컬럼 설정 영속화 키(`injectSdSystemConfigResource`). 설정 시 설정(톱니) 버튼 표시. 설정 모달은 key 없으면 throw.
+- `focusMode: "row"|"cell"` (기본 `"cell"`) — `"cell"` = 포커스 셀 강조; `"row"` = 셀 인디케이터 숨기고 행만 강조.
+- `inset: boolean` (기본 false) — true 면 테두리·라운드 제거(다른 컨테이너 내장용).
+- `hideConfigBar: boolean` (기본 false) — true 면 상단 도구 바(설정 버튼+페이지네이션) 숨김.
+- `contentStyle: string` — 스크롤 컨테이너 인라인 스타일.
+- `getItemCellClassFn: (item, colKey) => string | undefined` / `getItemCellStyleFn: (item, colKey) => string | undefined` — 셀별 클래스/스타일.
+- `columnControlsInput: readonly SdSheetColumn[]` (기본 `[]`) — 투영 컬럼과 합쳐질 프로그래밍 컬럼.
+- model: `selectedKeys: unknown[]` (선택 키) / `expandedItems: TItem[]` (펼친 행) / `sorts: SortingDef[]` (정렬) / `currentPage: number` (0-base).
+- output: `itemKeydown: SdSheetItemKeydownEventParam<TItem>` (`{ item, event }`) / `cellKeydown: SdSheetCellKeydownEventParam<TItem>` (`{ item, key, event }`).
+- 주요 메서드: `onConfigButtonClick()` — `SdSheetConfigModal` 열어 컬럼 설정 영속화(key 없으면 throw). `onHeaderClick(event, cell)` — 정렬 토글(shift=다중 정렬).
 
 ```html
-<sd-sheet [items]="items()" [trackByFn]="trackByFn" [(selectedKeys)]="selectedKeys"
-          [selectMode]="'multi'" [(sorts)]="sorts" [key]="'order-list'">
+<sd-sheet [items]="items()" [trackByFn]="trackByFn" [(selectedKeys)]="selectedKeys" [(currentPage)]="page" [totalPageCount]="pageLength()">
   <sd-sheet-column [key]="'name'" [header]="'이름'">
-    <ng-template [cell]="items()" let-item="item">{{ item.name }}</ng-template>
+    <ng-template [cell]="items()" let-item="item"><div class="p-xs-sm">{{ item.name }}</div></ng-template>
   </sd-sheet-column>
 </sd-sheet>
 ```
 
-## SdSheetColumn — `<sd-sheet-column>`
-
-```ts
-key = input.required<string>();
-header = input<string | string[]>(""); // string[] = 다단 헤더(병합)
-headerStyle; tooltip; width = input<string>();
-fixed = input(false); hidden = input(false); collapse = input(false);
-disableSorting = input(false); disableResizing = input(false); ordering = input(0);
-cellTplRef = contentChild.required(SdSheetColumnCellTemplate);  // [cell] 템플릿(필수)
-headerTplRef = contentChild<TemplateRef<void>>("headerTpl");
-summaryTplRef = contentChild<TemplateRef<void>>("summaryTpl");
-```
-
-- `key` — 컬럼 식별자(정렬/설정/cellKeydown 키). `header` 배열이면 다단 헤더로 병합 표시.
-- `width` — CSS 폭(예: `"120px"`). `fixed`=좌측 고정, `hidden`=숨김, `collapse`=설정상 접힘 후보. `disableSorting`/`disableResizing`=정렬/폭조정 비활성, `ordering`=기본 정렬 순서.
-- `#headerTpl`/`#summaryTpl` 로 헤더/요약행 커스터마이즈. 셀 본문은 `<ng-template [cell]="items()">`(필수).
+## `SdSheetColumn<T>` — `<sd-sheet-column>` (디렉티브)
 
-```ts
-// SdSheetCellContext<T> = { $implicit: T; item: T; index: number; depth: number; edit: boolean }
-```
+컬럼 1개 선언. `sd-sheet`/`sd-crud-list` 직속 자식으로 두면 자동 투영.
 
-- 셀 템플릿 컨텍스트: `item`/`index`/`depth`(트리 깊이)/`edit`(현재 셀 편집모드 여부).
+- `key: string` (required) — 컬럼 키(설정·셀/헤더 템플릿 lookup·정렬 키). select 별칭과 일치시키면 서버 정렬에 컬럼 분기 없이 처리([client-crud.md](../manuals/client-crud.md)).
+- `header: string | string[]` (기본 `""`) — 헤더 텍스트; `string[]` = 다단/그룹 헤더.
+- `headerStyle: string` / `tooltip: string` — 헤더 셀 스타일/툴팁.
+- `width: string` — 컬럼 폭(미지정=자동; px 지정은 명시 지시 시만, 매뉴얼 '폭 약속').
+- `fixed: boolean` — true 면 좌측 고정(sticky).
+- `hidden: boolean` — true 면 미렌더.
+- `collapse: boolean` — 레이아웃 엔진 collapse 플래그.
+- `disableSorting: boolean` — true 면 헤더 정렬 클릭·아이콘 비활성.
+- `disableResizing: boolean` — true 면 리사이저 핸들 제거.
+- `ordering: number` (기본 0) — 컬럼 순서 가중치(작을수록 앞).
+- 콘텐츠: `[cell]` 셀 템플릿(필수, `SdSheetColumnCellTemplate`), `#headerTpl`(커스텀 헤더), `#summaryTpl`(요약 행 셀).
 
-## SdSheetColumnCellTemplate — `ng-template[cell]`
+## `SdSheetColumnCellTemplate<T>` — `ng-template[cell]` (디렉티브)
 
-```ts
-cell = input.required<T[]>(); // 타입 추론용 — items() 를 그대로 전달
-```
+`<ng-template [cell]="items()">` 를 셀 본문으로 표시하고 컨텍스트 타입을 좁힘.
 
-- 셀 본문 템플릿 마커. `[cell]="items()"` 로 항목 배열을 넘겨 `let-item` 타입을 추론. 값 자체는 추론에만 쓰임.
+- `cell: T[]` (required) — items 배열(타입 추론용 더미, 실제 데이터는 `sd-sheet` 의 `[items]` 보유).
+- 정적 `ngTemplateContextGuard` — 컨텍스트를 `SdSheetCellContext<T>` 로 좁힘.
 
-## SdSheetConfigModal — `<sd-sheet-config-modal>`
+셀 컨텍스트 `SdSheetCellContext<T>` 필드: `$implicit: T` / `item: T` / `index: number`(표시 페이지 내 행 인덱스) / `depth: number`(트리 깊이) / `edit: boolean`(인라인 편집 모드 여부). 템플릿에서 `let-item="item"`·`let-index="index"`·`let-depth="depth"`·`let-edit="edit"` 로 받음.
 
-```ts
-sheetKey = input.required<string>();
-controls = input.required<readonly SdSheetColumn[]>();
-config = input.required<SdSheetConfig | undefined>();
-close = output<SdSheetConfig | undefined>(); // SdModalContentDef
-```
+## `SdSheetConfigModal` — `<sd-sheet-config-modal>`
 
-- 컬럼 고정/순서/폭/숨김을 편집하는 설정 모달. `sd-sheet` 가 설정 버튼 클릭 시 자동으로 띄우며 결과를 `key` 설정으로 저장. 직접 호출할 일은 거의 없음.
+컬럼 설정(고정·순서·폭·숨김) 편집 모달. `SdModalContentDef<SdSheetConfig | undefined>` 구현. `sd-sheet` 가 설정 버튼 클릭 시 자동으로 띄움 — 화면에서 직접 다룰 일은 드묾.
 
-## 관련 타입
+- `sheetKey: string` (required) / `controls: readonly SdSheetColumn[]` (required) / `config: SdSheetConfig | undefined` (required).
+- `close: SdSheetConfig | undefined` — OK 시 빌드된 설정, 취소 시 `undefined`, 초기화 확정 시 `{ columnRecord: {} }`.
 
-```ts
-SdSheetColumnDef { key; header: string|string[]; headerStyle?; tooltip?; width?; fixed; hidden; collapse; disableSorting; disableResizing; ordering }
-SdSheetHeaderDef { text; colspan; rowspan; isLastRow; fixed; colDef?; colIndex }
-SdSheetConfig { columnRecord: Record<string, { width?; hidden?; fixed?; ordering? }> }
-SdSheetItemKeydownEventParam<T> { item: T; event: KeyboardEvent }
-SdSheetCellKeydownEventParam<T> { item: T; key: string; event: KeyboardEvent }
-```
+## 타입
 
-- `SdSheetColumnDef`/`SdSheetHeaderDef` — 레이아웃 엔진이 산출하는 컬럼/헤더셀 메타(내부 타입). `SdSheetConfig` — 영속 컬럼 설정. `SdSheet*KeydownEventParam` — `itemKeydown`/`cellKeydown` 출력 페이로드(행 단축키·셀 단축키 처리용).
+- `SdSheetColumnDef` — `{ key: string; header: string|string[]; headerStyle?: string; tooltip?: string; width?: string; fixed: boolean; hidden: boolean; collapse: boolean; disableSorting: boolean; disableResizing: boolean; ordering: number }`. 컬럼 디렉티브에서 파생한 정규화 정의.
+- `SdSheetHeaderDef` — `{ text: string; colspan: number; rowspan: number; isLastRow: boolean; fixed: boolean; colDef: SdSheetColumnDef | undefined; colIndex: number }`. 다단 헤더 셀 1개 정의.
+- `SdSheetConfig` — `{ columnRecord: Record<string, { width?: string; hidden?: boolean; fixed?: boolean; ordering?: number }> }`. 사용자별 영속 설정.
+- `SdSheetItemKeydownEventParam<T>` — `{ item: T; event: KeyboardEvent }`. `itemKeydown` 페이로드.
+- `SdSheetCellKeydownEventParam<T>` — `{ item: T; key: string; event: KeyboardEvent }`. `cellKeydown` 페이로드(`key`=컬럼 키).
+- `SdSheetCellContext<T>` — 위 셀 컨텍스트(`sd-sheet-column.ts` 에서 export).
+- `SortingDef` — `{ key: string; desc: boolean }`(`sd-sheet.ts` 재export; 정렬 매니저 원본은 [shared-data.md](./shared-data.md)).