# StatusBadge

## 목적

상태 값을 간단한 UI 배지로 표현하는 컴포넌트입니다.

## 공통 설계 원칙

- 샘플(`samples`)을 제외한 컴포넌트에는 API 호출이나 화면 전용 로직을 직접 넣지 않습니다.
- 컴포넌트는 최대한 멍청하게 설계하고, 직관적인 props를 받아 직관적인 UI 동작만 수행합니다.
- 기능 처리와 비즈니스 로직은 `src/features` 또는 해당 화면 전용 패키지 레벨에서 담당합니다.
- 공통 컴포넌트는 여러 곳에서 재사용되므로, 수정 시에는 기존 동작을 바꾸지 않는 범위에서만 보완합니다.

## 폴더 구조

```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` 로 표준화
- 샘플 자동 수집 페이지 구성
