Initial import

docs/components/status-badge.md

@@ -0,0 +1,106 @@
+# StatusBadge
+
+## 목적
+
+상태 값을 간단한 UI 배지로 표현하는 컴포넌트입니다.
+
+## 폴더 구조
+
+```text
+src/components/status-badge
+├─ plugins/
+│  ├─ index.ts
+│  └─ status-badge.plugin.ts
+├─ samples/
+│  └─ Sample.tsx
+├─ types/
+│  ├─ index.ts
+│  └─ status-badge.ts
+├─ StatusBadgeUI.tsx
+└─ index.ts
+```
+
+## 구성 원칙
+
+- `StatusBadgeUI.tsx`: 실제 UI 렌더링
+- `types/`: props, plugin input 타입 관리
+- `plugins/`: 외부 입력 변환, props 후처리, 커링 플러그인 관리
+- `samples/Sample.tsx`: 대표 샘플
+
+공통 플러그인 제네릭은 `src/types/component-plugin.ts` 에서 관리합니다.
+
+## 기본 Props
+
+```ts
+type StatusBadgeProps = {
+  label: string;
+  tone?: 'success' | 'warning' | 'error' | 'processing' | 'default';
+};
+```
+
+## Plugin Input 예시
+
+```ts
+type StatusBadgePluginInput = {
+  text: string;
+  status?: 'ready' | 'working' | 'blocked' | 'done';
+};
+```
+
+## 공통 Plugin 타입
+
+```ts
+type PropsPlugin<TProps> = (props: TProps) => TProps;
+
+type ComponentPlugin<TInput, TProps = TInput> = (input: TInput) => TProps;
+
+type ComponentPluginFactory<TArgs extends unknown[] = [], TInput = unknown, TProps = TInput> =
+  (...args: TArgs) => ComponentPlugin<TInput, TProps>;
+```
+
+`PropsPlugin<TProps>` 는 질문하신 `plugin<T>(T props) => T` 형태를 직접 표현합니다.  
+`ComponentPlugin` 과 `ComponentPluginFactory` 는 입력 타입과 UI props 타입이 다르거나, 커링이 필요한 경우까지 확장하기 위한 타입입니다.
+
+## 여러 Plugin 합성
+
+```ts
+function plugins<TProps>(
+  props: TProps,
+  pluginList: ReadonlyArray<PropsPlugin<TProps>>,
+): TProps
+```
+
+`plugins<T>(props, Plugin[])` 형태로 여러 props 플러그인을 순서대로 적용합니다.
+
+## Plugin 구현 예시
+
+```ts
+const mapStatusBadgeInputToProps: ComponentPlugin<
+  StatusBadgePluginInput,
+  StatusBadgeProps
+> = (input) => ({
+  label: input.text,
+  tone: input.status ? statusToneMap[input.status] : 'default',
+});
+
+const createStatusBadgeTonePlugin: ComponentPluginFactory<
+  [options?: StatusBadgePluginOptions],
+  StatusBadgeProps
+> = (options) => (props) => ({
+  ...props,
+  tone: props.tone === 'default' ? options?.fallbackTone ?? 'default' : props.tone,
+});
+```
+
+## Sample 활용 목적
+
+- API 게시판에서 예제 UI 노출
+- 문서 페이지에서 동작 방식 설명
+- QA 시 컴포넌트 빠른 확인
+
+## 확장 방향
+
+- `map input -> props` 와 `props -> props` 플러그인 체인을 조합
+- `plugins(props, pluginList)` 로 여러 후처리 플러그인 적용
+- 기본형은 `PropsPlugin<TProps>` 로, 확장형은 `ComponentPluginFactory` 로 표준화
+- 샘플 자동 수집 페이지 구성