@simplysm/angular 14.0.48 → 14.0.51

package/docs/features/sd-tiptap-editor.md

@@ -0,0 +1,26 @@
+# `SdTiptapEditor`
+
+TipTap 기반 리치 텍스트 에디터 컴포넌트. 툴바를 통해 텍스트 서식(제목, 굵게, 기울임, 색상, 정렬 등)을 제어한다.
+
+```typescript
+@Component({ selector: "sd-tiptap-editor", ... })
+export class SdTiptapEditor
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `value` | model | `string \| undefined` | HTML 콘텐츠 |
+| `disabled` | input | `boolean` | 비활성화 — 툴바 숨김, 편집 불가 (기본값: `false`) |
+| `readonly` | input | `boolean` | 읽기 전용 — 편집 불가, 툴바 표시 (기본값: `false`) |
+| `required` | input | `boolean` | 필수 여부 (기본값: `false`) |
+| `placeholder` | input | `string \| undefined` | 플레이스홀더 텍스트 |
+| `validatorFn` | input | `(value: string \| undefined) => string \| undefined` | 커스텀 유효성 검사 함수 |
+| `extensions` | input | `AnyExtension[] \| undefined` | 추가 TipTap 확장 (기본 확장: StarterKit, TextStyle, Color, Highlight, TextAlign, Image, Underline, Placeholder) |
+
+## Usage
+
+```html
+<sd-tiptap-editor [(value)]="content" [placeholder]="'내용을 입력하세요'" />
+```

package/docs/{pipes.md → pipes/format-pipe.md}

@@ -1,6 +1,4 @@
-# Pipes
-
-## `FormatPipe`
+# `FormatPipe`
 
 DateTime, DateOnly, string 값을 포맷팅하는 파이프. 파이프명: `format`
 
@@ -11,6 +9,19 @@ class FormatPipe implements PipeTransform {
 }
 ```
 
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `value` | `string \| DateTime \| DateOnly \| undefined` | 포맷팅할 값 |
+| `format` | `string` | 포맷 문자열 |
+
+## Returns
+
+`string` — 포맷팅된 문자열. `undefined` 또는 `null` 입력 시 빈 문자열 반환.
+
+## Usage
+
 ### DateTime / DateOnly
 
 `value.toFormatString(format)`을 호출한다.
@@ -28,5 +39,3 @@ format 문자열에서 `X` 문자를 값의 문자로 치환한다. `|`로 구
 <!-- "01012345678" → "010-1234-5678" -->
 {{ phone | format: "XXX-XXXX-XXXX|XX-XXX-XXXX|XX-XXXX-XXXX" }}
 ```
-
-`undefined` 또는 `null` 입력 시 빈 문자열 반환.

package/docs/plugins/sd-global-error-handler.md

@@ -0,0 +1,23 @@
+# `SdGlobalErrorHandlerPlugin`
+
+글로벌 에러 핸들러. Angular `ErrorHandler`를 구현하여 처리되지 않은 에러를 포착하고 화면에 표시한다.
+
+```typescript
+@Injectable({ providedIn: null })
+export class SdGlobalErrorHandlerPlugin implements ErrorHandler
+```
+
+`provideSdAngular()`에 의해 자동 등록된다. 직접 등록할 필요 없다.
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `handleError(event)` | method | `(any) => void` | 에러 처리. `PromiseRejectionEvent`, `ErrorEvent`, `Error` 등을 구분하여 처리 |
+
+## 동작
+
+- `PromiseRejectionEvent` → reason이 `Error`면 메시지+스택, 객체면 JSON 표시
+- `ErrorEvent` → error가 `Error`면 메시지+스택, string이면 그대로 표시
+- `Error` → 메시지+스택 표시
+- devMode에서는 toast로, prodMode에서는 alert로 표시 (중복 표시 방지)

package/docs/{plugins.md → plugins/sd-option-event-plugin.md}

@@ -1,14 +1,6 @@
-# Plugins
+# `SdOptionEventPlugin`
 
-Angular의 `EventManagerPlugin`을 확장하여 커스텀 이벤트 옵션을 지원한다. `provideSdAngular()`에서 `SdOptionEventPlugin`만 자동 등록된다.
-
-> **NOTE:** 이전 버전의 커맨드 플러그인(`sdSaveCommand`, `sdRefreshCommand`, `sdInsertCommand`)과 옵저버 플러그인(`sdResize`, `sdIntersection`)은 디렉티브로 대체되었다. 자세한 내용은 [directives.md](./directives.md)의 `SdCommandDirective`, `SdResizeDirective`, `SdIntersectionDirective` 항목을 참고한다.
-
-## Option Plugin
-
-### `SdOptionEventPlugin`
-
-`.capture`, `.passive`, `.once` 이벤트 수식어 플러그인. 네이티브 DOM 이벤트에 addEventListener options를 적용한다.
+`.capture`, `.passive`, `.once` 이벤트 수식어 플러그인. 네이티브 DOM 이벤트에 addEventListener options를 적용한다. [`provideSdAngular`](../bootstrap/provide-sd-angular.md)에서 자동 등록된다.
 
 ```typescript
 class SdOptionEventPlugin extends EventManagerPlugin {
@@ -16,9 +8,14 @@ class SdOptionEventPlugin extends EventManagerPlugin {
 }
 ```
 
-사용법: `(scroll.passive)="onScroll($event)"`, `(click.capture.once)="onClick($event)"`
+## Usage
+
+```html
+<div (scroll.passive)="onScroll($event)">...</div>
+<div (click.capture.once)="onClick($event)">...</div>
+```
 
-## Error Handler
+## Related Types
 
 ### `SdGlobalErrorHandlerPlugin`
 

package/docs/provider-types/sd-menu.md

@@ -0,0 +1,65 @@
+# `SdMenu`
+
+메뉴 트리 노드.
+
+```typescript
+interface SdMenu {
+  title: string;
+  codeChain: string[];
+  url?: string;
+  icon?: string;
+  children?: SdMenu[];
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | 메뉴 제목 |
+| `codeChain` | `string[]` | 코드 체인 (루트부터 현재까지) |
+| `url` | `string \| undefined` | 외부 URL |
+| `icon` | `string \| undefined` | 아이콘 |
+| `children` | `SdMenu[] \| undefined` | 하위 메뉴 |
+
+## Related Types
+
+### `SdFlatMenu`
+
+플랫 메뉴 항목 (리프만).
+
+```typescript
+interface SdFlatMenu<TModule = unknown> {
+  titleChain: string[];
+  codeChain: string[];
+  modulesChain: TModule[][];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `titleChain` | `string[]` | 타이틀 체인 |
+| `codeChain` | `string[]` | 코드 체인 |
+| `modulesChain` | `TModule[][]` | 모듈 체인 |
+
+### `SdPermission`
+
+권한 트리 노드.
+
+```typescript
+interface SdPermission<TModule = unknown> {
+  title: string;
+  codeChain: string[];
+  modules: TModule[] | undefined;
+  perms: ("use" | "edit")[] | undefined;
+  children: SdPermission<TModule>[] | undefined;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | 권한 제목 |
+| `codeChain` | `string[]` | 코드 체인 |
+| `modules` | `TModule[] \| undefined` | 모듈 제한 |
+| `perms` | `("use" \| "edit")[] \| undefined` | 권한 목록 |
+| `children` | `SdPermission<TModule>[] \| undefined` | 하위 권한 |

package/docs/provider-types/sd-modal-content-def.md

@@ -0,0 +1,148 @@
+# `SdModalContentDef`
+
+모달 컴포넌트가 구현해야 하는 인터페이스.
+
+```typescript
+interface SdModalContentDef<O> {
+  initialized: Signal<boolean>;
+  close: OutputEmitterRef<O | undefined>;
+  actionTplRef?: TemplateRef<any>;
+  readonly _optionalModalInputs?: string;
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `initialized` | `Signal<boolean>` | 초기화 완료 여부 |
+| `close` | `OutputEmitterRef<O \| undefined>` | 닫기 output (결과 전달) |
+| `actionTplRef` | `TemplateRef<any> \| undefined` | 모달 헤더 액션 영역 템플릿 |
+| `_optionalModalInputs` | `string \| undefined` | optional로 취급할 input 키 목록 (리터럴 타입) |
+
+## 구현 패턴
+
+```typescript
+export class CustomerDetail implements SdModalContentDef<boolean | undefined> {
+  initialized = signal(false);
+  close = output<boolean | undefined>();
+  actionTplRef?: TemplateRef<any>;
+
+  private readonly _modalActionTpl = viewChild("modalActionTpl", { read: TemplateRef });
+
+  constructor() {
+    effect(() => {
+      this.actionTplRef = this._modalActionTpl();
+    });
+  }
+
+  protected async onSubmit(): Promise<void> {
+    // ... (ORM upsert)
+    this.close.emit(true);
+  }
+}
+```
+
+## Related Types
+
+### `SdModalInfo`
+
+모달 생성 시 전달하는 정보.
+
+```typescript
+interface SdModalInfo<T extends SdModalContentDef<any>, X extends keyof any = ""> {
+  title: string;
+  type: Type<T>;
+  inputs: WithOptional<Omit<DirectiveInputSignals<T>, SdModalExcludeKeys | X>, ...>;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | 모달 제목 |
+| `type` | `Type<T>` | 모달 컴포넌트 타입 |
+| `inputs` | `object` | 컴포넌트 inputs (initialized, close, actionTplRef 제외) |
+
+### `SdModalOptions`
+
+모달 옵션.
+
+```typescript
+interface SdModalOptions {
+  key?: string;
+  hideHeader?: boolean;
+  hideCloseButton?: boolean;
+  useCloseByBackdrop?: boolean;
+  useCloseByEscapeKey?: boolean;
+  float?: boolean;
+  fill?: boolean;
+  resizable?: boolean;
+  movable?: boolean;
+  position?: "bottom-right" | "top-right";
+  minHeightPx?: number;
+  minWidthPx?: number;
+  heightPx?: number;
+  widthPx?: number;
+  headerStyle?: string;
+  noFirstControlFocusing?: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | `string \| undefined` | 동일 키의 모달이 이미 열려 있으면 재사용 |
+| `hideHeader` | `boolean \| undefined` | 헤더 숨김 |
+| `hideCloseButton` | `boolean \| undefined` | 닫기 버튼 숨김 |
+| `useCloseByBackdrop` | `boolean \| undefined` | 배경 클릭으로 닫기 |
+| `useCloseByEscapeKey` | `boolean \| undefined` | ESC 키로 닫기 |
+| `float` | `boolean \| undefined` | 플로팅 모달 |
+| `fill` | `boolean \| undefined` | 전체 화면 채우기 |
+| `resizable` | `boolean \| undefined` | 크기 조절 가능 |
+| `movable` | `boolean \| undefined` | 이동 가능 |
+| `position` | `"bottom-right" \| "top-right" \| undefined` | 위치 프리셋 |
+| `minHeightPx` | `number \| undefined` | 최소 높이 (px) |
+| `minWidthPx` | `number \| undefined` | 최소 너비 (px) |
+| `heightPx` | `number \| undefined` | 높이 (px) |
+| `widthPx` | `number \| undefined` | 너비 (px) |
+| `headerStyle` | `string \| undefined` | 헤더 인라인 스타일 |
+| `noFirstControlFocusing` | `boolean \| undefined` | 첫 번째 컨트롤 자동 포커스 비활성화 |
+
+### `SelectModalOutputResult`
+
+모달 선택 결과.
+
+```typescript
+interface SelectModalOutputResult<T> {
+  selectedItemKeys: any[];
+  selectedItems: T[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `selectedItemKeys` | `any[]` | 선택된 항목 키 배열 |
+| `selectedItems` | `T[]` | 선택된 항목 배열 |
+
+### `SdSelectModal`
+
+선택 모달 컴포넌트가 구현해야 하는 인터페이스. `SdModalContentDef<SelectModalOutputResult<T>>`를 확장한다.
+
+```typescript
+interface SdSelectModal<T> extends SdModalContentDef<SelectModalOutputResult<T>> {
+  selectMode: InputSignal<"single" | "multi" | undefined>;
+  selectedItemKeys: InputSignal<any[]>;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `selectMode` | `InputSignal<"single" \| "multi" \| undefined>` | 선택 모드 |
+| `selectedItemKeys` | `InputSignal<any[]>` | 이미 선택된 항목 키 배열 (복원용) |
+
+### `SdSelectModalInfo`
+
+모달 선택 정보.
+
+```typescript
+type SdSelectModalInfo<T extends SdSelectModal<any>> = SdModalInfo<T, "selectMode" | "selectedItemKeys">
+```

package/docs/provider-types/sd-toast-content-def.md

@@ -0,0 +1,73 @@
+# `SdToastContentDef`
+
+커스텀 토스트 컴포넌트가 구현해야 하는 인터페이스.
+
+```typescript
+interface SdToastContentDef<O> {
+  close: OutputEmitterRef<O | undefined>;
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `close` | `OutputEmitterRef<O \| undefined>` | 닫기 output |
+
+## Related Types
+
+### `SdToastInput`
+
+커스텀 토스트 생성 입력.
+
+```typescript
+interface SdToastInput<T extends SdToastContentDef<any>> {
+  type: Type<T>;
+  inputs: Omit<DirectiveInputSignals<T>, "close">;
+}
+```
+
+### `SdToastSeverity`
+
+```typescript
+type SdToastSeverity = "info" | "success" | "warning" | "danger";
+```
+
+### `SdToastTheme`
+
+```typescript
+type SdToastTheme = "primary" | "secondary" | SdToastSeverity | "gray" | "blue-gray";
+```
+
+### `SdBusyType`
+
+```typescript
+type SdBusyType = "spinner" | "bar" | "cube";
+```
+
+## Related Types (Print)
+
+### `SdPrint`
+
+인쇄 컴포넌트가 구현해야 하는 인터페이스.
+
+```typescript
+interface SdPrint {
+  initialized: Signal<boolean>;
+  readonly _optionalPrintInputs?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `initialized` | `Signal<boolean>` | 초기화 완료 여부 (true 될 때까지 대기 후 인쇄) |
+| `_optionalPrintInputs` | `string \| undefined` | optional로 취급할 input 키 목록 |
+
+### `SdPrintInput`
+
+```typescript
+interface SdPrintInput<T, X extends keyof any = ""> {
+  type: Type<T>;
+  inputs: WithOptional<Omit<DirectiveInputSignals<T>, "_optionalPrintInputs" | X>, ...>;
+}
+```

package/docs/provider-types/shared-data-base.md

@@ -0,0 +1,59 @@
+# `SharedDataBase`
+
+공유 데이터 기본 인터페이스. 모든 공유 데이터 항목이 구현해야 한다.
+
+```typescript
+interface SharedDataBase<TKey extends string | number> {
+  __valueKey: TKey;
+  __searchText: string;
+  __isHidden: boolean;
+  __parentKey?: TKey;
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `__valueKey` | `TKey` | 고유 키 |
+| `__searchText` | `string` | 검색 대상 텍스트 |
+| `__isHidden` | `boolean` | 숨김 여부 |
+| `__parentKey` | `TKey \| undefined` | 부모 키 (트리 구조용) |
+
+## Related Types
+
+### `SharedDataInfo`
+
+공유 데이터 등록 정보.
+
+```typescript
+interface SharedDataInfo<T extends SharedDataBase<string | number>> {
+  serviceKey: string;
+  getter: (changeKeys?: (string | number)[]) => Promise<T[]>;
+  filter?: unknown;
+  orderBy?: (a: T, b: T) => number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `serviceKey` | `string` | ServiceClient 연결 키 |
+| `getter` | `(changeKeys?) => Promise<T[]>` | 데이터 조회 함수. changeKeys 전달 시 부분 조회 |
+| `filter` | `unknown` | 이벤트 필터 (같은 이름의 다른 필터 구분용) |
+| `orderBy` | `((a, b) => number) \| undefined` | 정렬 함수 |
+
+### `SharedDataHandle`
+
+공유 데이터 핸들. `SdSharedDataProvider.getHandle()`이 반환하는 객체.
+
+```typescript
+interface SharedDataHandle<T extends SharedDataBase<string | number>> {
+  items: Signal<T[]>;
+  get(key: T["__valueKey"] | undefined): T | undefined;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `items` | `Signal<T[]>` | 데이터 항목 signal |
+| `get(key)` | `(key) => T \| undefined` | 키로 항목 조회 |

package/docs/providers/sd-activated-modal-provider.md

@@ -0,0 +1,34 @@
+# `SdActivatedModalProvider`
+
+모달 내부에서 inject하여 모달/컨텐츠 컴포넌트 참조를 얻는 프로바이더. `@Injectable()`로 모달별 인스턴스 생성.
+
+```typescript
+@Injectable()
+class SdActivatedModalProvider<T extends SdModalContentDef<any> = SdModalContentDef<any>> {
+  modalComponent = signal<any>(undefined);
+  contentComponent = signal<T | undefined>(undefined);
+  canDeactivateFn: () => boolean;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `modalComponent` | property | `WritableSignal<any>` | SdModal 인스턴스 |
+| `contentComponent` | property | `WritableSignal<T \| undefined>` | 컨텐츠 컴포넌트 인스턴스 |
+| `canDeactivateFn` | property | `() => boolean` | 모달 닫기 가능 여부 판별 함수 (기본: `() => true`) |
+
+## Usage
+
+모달 내부 컴포넌트에서 `optional: true`로 inject하여 모달 컨텍스트를 확인한다. 타이틀 계산은 `injectViewTitleSignal()`이 내부에서 `SdActivatedModalProvider`를 자동으로 처리하므로 직접 inject할 필요가 없다:
+
+```typescript
+// 타이틀 — injectViewTitleSignal()이 modal/page 분기를 자동 처리
+protected readonly viewTitle = injectViewTitleSignal();
+
+// canDeactivateFn 등 모달 컨텍스트가 직접 필요한 경우에만 inject
+private readonly _sdActivatedModal = inject(SdActivatedModalProvider, { optional: true });
+```
+
+`optional: true`를 사용하는 이유: 동일 컴포넌트가 page 뷰로도 사용될 수 있으며, page 뷰에서는 `SdActivatedModalProvider`가 제공되지 않는다.

package/docs/providers/sd-app-structure-provider.md

@@ -0,0 +1,81 @@
+# `SdAppStructureProvider`
+
+앱 구조(메뉴/권한) 관리 프로바이더. 서브클래스 없이 직접 사용한다.
+
+```typescript
+@Injectable({ providedIn: "root" })
+class SdAppStructureProvider<TModule = unknown> {
+  readonly usableModules = signal<TModule[] | undefined>(undefined);
+  readonly permRecord = signal<Record<string, boolean> | undefined>(undefined);
+  readonly items = signal<AppStructureItem<TModule>[]>([]);
+
+  usableMenus: Signal<SdMenu[]>;
+  usableFlatMenus: Signal<SdFlatMenu<TModule>[]>;
+
+  async initialize(serviceKey: string): Promise<void>;
+  getPermissionsByStructure(items, codeChain?): SdPermission<TModule>[];
+  getTitleByFullCode(fullCode: string): string;
+  getItemChainByFullCode(fullCode: string): AppStructureItem<TModule>[];
+  getPermsByFullCode<K extends string>(fullCodes: string[], permKeys: K[]): K[];
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `usableModules` | property | `WritableSignal<TModule[] \| undefined>` | 사용 가능한 모듈 목록. 외부에서 `set()`/`update()`로 설정 |
+| `permRecord` | property | `WritableSignal<Record<string, boolean> \| undefined>` | 권한 레코드. 외부에서 `set()`/`update()`로 설정 |
+| `items` | property | `WritableSignal<AppStructureItem<TModule>[]>` | 앱 구조 항목 배열 (`initialize()`로 초기화) |
+| `usableMenus` | computed | `Signal<SdMenu[]>` | 사용 가능한 메뉴 트리 |
+| `usableFlatMenus` | computed | `Signal<SdFlatMenu<TModule>[]>` | 사용 가능한 플랫 메뉴 |
+| `initialize(serviceKey)` | method | `(string) => Promise<void>` | 서비스에서 앱 구조 로드 |
+| `getTitleByFullCode(fullCode)` | method | `(string) => string` | fullCode로 타이틀 조회 |
+| `getItemChainByFullCode(fullCode)` | method | `(string) => AppStructureItem<TModule>[]` | fullCode로 항목 체인 조회 |
+| `getPermsByFullCode(fullCodes, permKeys)` | method | `(string[], K[]) => K[]` | fullCode 배열에서 보유 권한 키 반환 |
+
+## Related Types
+
+### `injectPermsSignal`
+
+앱 구조(`SdAppStructureProvider`)에서 지정된 뷰 코드와 키 배열에 대한 권한을 조회하는 signal. 생성자/필드 이니셜라이저에서 호출한다.
+
+```typescript
+function injectPermsSignal<K extends string>(viewCodes: string[], keys: K[]): Signal<K[]>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `viewCodes` | `string[]` | 조회할 뷰 코드 배열 (예: `["sales.customer"]`) |
+| `keys` | `K[]` | 권한 키 배열 (예: `["use", "edit"]`) |
+
+반환: 현재 사용자가 보유한 권한 키 배열의 signal
+
+#### 사용 패턴
+
+```typescript
+protected readonly perms = injectPermsSignal(["sales.customer"], ["use", "edit"]);
+protected readonly canEdit = computed(() => this.perms().includes("edit"));
+```
+
+```html
+@if (!perms().includes("use")) {
+  <sd-note theme="warning">이 화면의 사용 권한이 없습니다.</sd-note>
+}
+```
+
+### `SdAppStructureUtils`
+
+앱 구조 유틸리티. 정적 메서드로 메뉴/권한 조회 로직을 제공한다.
+
+```typescript
+abstract class SdAppStructureUtils {
+  static getTitleByFullCode<TModule>(items, fullCode): string;
+  static getPermsByFullCode<TModule, K extends string>(items, fullCodes, permKeys, permRecord): K[];
+  static getItemChainByFullCode<TModule>(items, fullCode): AppStructureItem<TModule>[];
+  static getMenus<TModule>(items, codeChain, usableModules, permRecord): SdMenu[];
+  static getFlatMenus<TModule>(items, usableModules, permRecord): SdFlatMenu<TModule>[];
+  static getPermissions<TModule>(items, codeChain, usableModules): SdPermission<TModule>[];
+  static getFlatPermissions<TModule>(items, usableModules): FlatPermission<TModule>[];
+}
+```

package/docs/providers/sd-busy-provider.md

@@ -0,0 +1,18 @@
+# `SdBusyProvider`
+
+글로벌 busy 상태 관리 프로바이더.
+
+```typescript
+@Injectable({ providedIn: "root" })
+class SdBusyProvider {
+  type = signal<SdBusyType>("bar");
+  globalBusyCount = signal(0);
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `type` | property | `WritableSignal<SdBusyType>` | busy 표시 유형 (`"spinner" \| "bar" \| "cube"`) |
+| `globalBusyCount` | property | `WritableSignal<number>` | 글로벌 busy 카운트 (0보다 크면 busy 표시) |

package/docs/providers/sd-file-dialog-provider.md

@@ -0,0 +1,40 @@
+# `SdFileDialogProvider`
+
+네이티브 파일 선택 대화상자 프로바이더.
+
+```typescript
+@Injectable({ providedIn: "root" })
+class SdFileDialogProvider {
+  async showAsync(multiple?: false, accept?: string): Promise<File | undefined>;
+  async showAsync(multiple: true, accept?: string): Promise<File[] | undefined>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `showAsync(multiple?, accept?)` | method | overloaded | 파일 선택 대화상자 열기. `multiple=true`이면 `File[]`, 아니면 `File \| undefined` 반환 |
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `multiple` | `boolean \| undefined` | 다중 선택 여부 |
+| `accept` | `string \| undefined` | 허용 파일 타입 (예: `"image/*"`, `".xlsx"`) |
+
+## Usage
+
+엑셀 파일 업로드 시 단일 파일을 선택받는 패턴:
+
+```typescript
+private readonly _sdFileDialog = inject(SdFileDialogProvider);
+
+async onUploadExcelButtonClick(): Promise<void> {
+  const file = await this._sdFileDialog.showAsync(false, ".xlsx");
+  if (file == null) return;
+  if (Array.isArray(file)) return;
+
+  // file: File 객체
+}
+```

package/docs/providers/sd-local-storage-provider.md

@@ -0,0 +1,20 @@
+# `SdLocalStorageProvider`
+
+`clientName` 스코프 localStorage 래퍼. 키가 `{clientName}.{key}` 형태로 저장된다.
+
+```typescript
+@Injectable({ providedIn: "root" })
+class SdLocalStorageProvider<T> {
+  set<K extends keyof T & string>(key: K, value: T[K]): void;
+  get<K extends keyof T & string>(key: K): T[K] | undefined;
+  remove(key: keyof T & string): void;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `set(key, value)` | method | `(K, T[K]) => void` | 값 저장 |
+| `get(key)` | method | `(K) => T[K] \| undefined` | 값 조회 |
+| `remove(key)` | method | `(keyof T & string) => void` | 값 삭제 |