@iamfiro/design 0.0.0-stage → 0.1.0

package/agents/status-icon/AGENTS.md

@@ -0,0 +1,243 @@
+# StatusIcon
+
+> 아이콘 & 아바타 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+체크리스트 · 일정 행 앞에 붙는 작은 단계 아이콘. 대기는 회색 점선 원, 진행 중은 파란 링(돌거나 채워짐), 완료는 회색 체크, 오류는 빨간 ×, 확인 필요는 주황 !예요. 모든 상태가 svg 하나에 들어 있어 상태가 바뀌면 링이 차오르고 체크가 그려지며 자연스럽게 넘어가요.
+
+```tsx
+import { StatusIcon } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 단계 행 앞 아이콘은 `StatusIcon`(대기 = 회색 점선 원, 진행 = 파란 링, 완료 = 회색 체크, 오류 · 확인 필요). 상태마다 아이콘을 바꿔 끼우지 않고 한 svg 안에서 전환한다.
+- 읽기 전용 단계 타임라인(계획 · 활동 기록 · 승인 흐름)은 `StepList`(`ol`, 마커 + 연결선, `meta` 시간, 아래 내용엔 Collapsible inline). 번호 원은 `StatusIcon number`(`persistNumber`면 모든 상태에서 번호). 사용자가 체크하는 목록은 `ProgressTracker`. 카드 아래 상태 띠는 `CardFooter band`.
+
+## API
+
+### StatusIcon
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `status` (필수) | `'pending' \| 'active' \| 'done' \| 'error' \| 'warning'` |  | 단계 상태. |
+| `size` | `'sm' \| 'md' \| 'lg' \| number` | `'md'` | 크기(px 숫자도 가능). |
+| `progress` | `number` |  | active일 때 0–100. 생략하면 링이 계속 돌아요. |
+| `colored` | `boolean` |  | 완료를 회색 대신 초록으로. |
+| `number` | `number \| string` |  | 대기 상태를 회색 실선 원 + 번호("5")로. 다른 상태에선 링 · 기호로 넘어가요. |
+| `persistNumber` | `boolean` |  | number와 함께: 모든 상태에서 번호를 남기고 테두리가 상태 색(완료 회색 · 진행 파랑 · 오류 빨강 · 확인 주황)이 돼요. |
+| `label` | `string` |  | 스크린 리더가 읽을 이름. 기본은 "완료", "진행 중 40%"처럼 상태 이름이에요. |
+| `decorative` | `boolean` |  | 옆 글자가 이미 상태를 말할 때 스크린 리더에서 숨겨요. |
+| `className` | `string` |  | 추가 클래스. |
+| `style` | `CSSProperties` |  | 인라인 스타일. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 상태
+
+pending · active · done · error · warning. colored를 주면 완료가 초록이 돼요.
+
+```tsx
+import { Inline, StatusIcon, Text, type StatusIconStatus } from '@iamfiro/design'
+
+const STATES: Array<{ status: StatusIconStatus; label: string }> = [
+  { status: 'pending', label: '대기' },
+  { status: 'active', label: '진행 중' },
+  { status: 'done', label: '완료' },
+  { status: 'error', label: '오류' },
+  { status: 'warning', label: '확인 필요' },
+]
+
+export default function Example() {
+  return (
+    <Inline gap={6}>
+      {STATES.map((s) => (
+        <Inline key={s.status} gap={2} wrap={false}>
+          <StatusIcon status={s.status} decorative />
+          <Text variant="label-sm">{s.label}</Text>
+        </Inline>
+      ))}
+      <Inline gap={2} wrap={false}>
+        <StatusIcon status="done" colored decorative />
+        <Text variant="label-sm">완료 (colored)</Text>
+      </Inline>
+    </Inline>
+  )
+}
+```
+
+### 작업 단계
+
+ListItem의 leading에 놓아 단계 목록을 만들어요. 버튼을 눌러 상태가 바뀌는 움직임을 확인해 보세요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, Stack, StatusIcon, type StatusIconStatus, List, ListItem } from '@iamfiro/design'
+
+const STEPS = [
+  { id: 'lint', title: '코드 검사', description: '규칙 위반 0건' },
+  { id: 'test', title: '테스트', description: '412개 통과' },
+  { id: 'build', title: '빌드', description: '번들 크기 확인 중' },
+  { id: 'deploy', title: '운영 배포', description: '서울 리전' },
+  { id: 'notify', title: '팀에 알리기', description: '#release 채널' },
+]
+
+export default function Example() {
+  // Index of the step in progress; steps before it are done.
+  const [current, setCurrent] = useState(2)
+  const [failed, setFailed] = useState(false)
+
+  const statusOf = (i: number): StatusIconStatus => {
+    if (i < current) return 'done'
+    if (i === current) return failed ? 'error' : 'active'
+    return 'pending'
+  }
+
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 420 }}>
+      <List label="배포 단계">
+        {STEPS.map((s, i) => (
+          <ListItem
+            key={s.id}
+            leading={<StatusIcon status={statusOf(i)} />}
+            title={s.title}
+            description={i === current && failed ? '빌드 스크립트가 종료 코드 1로 끝났어요' : s.description}
+          />
+        ))}
+      </List>
+      <Inline gap={2}>
+        <Button
+          variant="primary"
+          size="sm"
+          disabled={current >= STEPS.length}
+          onClick={() => {
+            setFailed(false)
+            setCurrent((c) => c + 1)
+          }}
+        >
+          다음 단계
+        </Button>
+        <Button size="sm" disabled={current >= STEPS.length} onClick={() => setFailed((f) => !f)}>
+          {failed ? '다시 시도' : '실패로 표시'}
+        </Button>
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={() => {
+            setFailed(false)
+            setCurrent(0)
+          }}
+        >
+          처음부터
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 번호
+
+number를 주면 대기 상태가 점선 원 대신 회색 실선 원 + 번호가 돼요. 시작하면 링으로, 끝나면 체크로 넘어가요. persistNumber면 모든 상태에서 번호가 남고 테두리 색만 상태를 따라가요(번호 타임라인).
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, Stack, StatusIcon, Text, type StatusIconStatus } from '@iamfiro/design'
+
+const ORDER: StatusIconStatus[] = ['pending', 'active', 'done']
+
+export default function Example() {
+  const [step, setStep] = useState(0)
+  const status = ORDER[step]
+  return (
+    <Stack gap={5}>
+      <Inline gap={6}>
+        <Inline gap={2} wrap={false}>
+          <StatusIcon status="pending" number={5} size="lg" decorative />
+          <Text variant="label-sm">대기 (number)</Text>
+        </Inline>
+        <Inline gap={2} wrap={false}>
+          <StatusIcon status="pending" number={12} size="lg" decorative />
+          <Text variant="label-sm">두 자리</Text>
+        </Inline>
+      </Inline>
+      <Inline gap={4}>
+        {(['pending', 'active', 'done', 'error', 'warning'] as const).map((s, i) => (
+          <StatusIcon key={s} status={s} number={i + 1} persistNumber size="lg" />
+        ))}
+        <Text variant="label-sm" tone="secondary">
+          persistNumber
+        </Text>
+      </Inline>
+      <Inline gap={3}>
+        <StatusIcon status={status} number={3} size="lg" />
+        <Button size="sm" onClick={() => setStep((s) => (s + 1) % ORDER.length)}>
+          {status === 'pending' ? '시작하기' : status === 'active' ? '완료하기' : '처음으로'}
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 진행률
+
+active에 progress(0–100)를 주면 링이 그만큼 채워지고, 없으면 Spinner처럼 돌아요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Inline, Stack, StatusIcon, Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [progress, setProgress] = useState(35)
+  const done = progress >= 100
+
+  return (
+    <Stack gap={4} align="start">
+      <Inline gap={6}>
+        <Inline gap={2} wrap={false}>
+          <StatusIcon status="active" size="lg" />
+          <Text variant="label-sm">파일 정리 중</Text>
+        </Inline>
+        <Inline gap={2} wrap={false}>
+          <StatusIcon status={done ? 'done' : 'active'} progress={progress} size="lg" />
+          <Text variant="label-sm" numeric>
+            {done ? '업로드 완료' : `업로드 ${progress}%`}
+          </Text>
+        </Inline>
+      </Inline>
+      <Inline gap={2}>
+        <Button size="sm" disabled={done} onClick={() => setProgress((p) => Math.min(100, p + 25))}>
+          25% 올리기
+        </Button>
+        <Button variant="ghost" size="sm" onClick={() => setProgress(0)}>
+          초기화
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 크기
+
+sm 14 · md 16 · lg 20px, 또는 px 숫자. 텍스트 옆에서도 찌그러지지 않아요(flex: none).
+
+```tsx
+import { Inline, StatusIcon } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Inline gap={6}>
+      {(['sm', 'md', 'lg', 28] as const).map((size) => (
+        <Inline key={size} gap={2} wrap={false}>
+          <StatusIcon status="done" size={size} />
+          <StatusIcon status="active" progress={60} size={size} />
+          <StatusIcon status="pending" size={size} />
+        </Inline>
+      ))}
+    </Inline>
+  )
+}
+```

package/agents/step-list/AGENTS.md

@@ -0,0 +1,313 @@
+# StepList
+
+> 진행 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+단계를 세로로 이어 보여 주는 읽기 전용 타임라인. 단계마다 왼쪽에 상태 마커(StatusIcon 또는 번호 원)가 있고 가는 연결선으로 이어져요. 제목 오른쪽엔 걸린 시간 같은 meta, 아래엔 회색 설명과 접는 줄 · 경고 줄 같은 내용을 넣어요. 상태가 바뀌면 마커가 자연스럽게 넘어가고, connector="progress"면 끝난 구간의 선이 아래로 차올라요. 사용자가 직접 체크하는 목록은 ProgressTracker를 써요.
+
+```tsx
+import { StepList, StepListItem } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 읽기 전용 단계 타임라인(계획 · 활동 기록 · 승인 흐름)은 `StepList`(`ol`, 마커 + 연결선, `meta` 시간, 아래 내용엔 Collapsible inline). 번호 원은 `StatusIcon number`(`persistNumber`면 모든 상태에서 번호). 사용자가 체크하는 목록은 `ProgressTracker`. 카드 아래 상태 띠는 `CardFooter band`.
+
+## API
+
+### StepList
+
+<ol>로 그려지고 진행 중(active) 단계엔 aria-current="step"이 붙어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `steps` | `StepListStep[]` |  | 단계 데이터. 대신 StepListItem을 children으로 조립해도 돼요. |
+| `marker` | `'status' \| 'number' \| 'status-number'` | `'status'` | status: StatusIcon · number: 모든 단계에 번호(테두리가 상태 색) · status-number: StatusIcon인데 대기 단계만 번호. |
+| `connector` | `'default' \| 'progress' \| 'none'` | `'default'` | default: 회색 선 · progress: 끝난 단계 아래 구간이 파랗게 차올라요 · none: 선 없음. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 마커 16 · 18 · 22px와 제목 · 설명 글자 크기. |
+| `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | 단계 사이 간격 12 · 20 · 32px. |
+| `start` | `number` | `1` | 번호 마커의 첫 번호. |
+| `aria-label` | `string` |  | 목록 이름. |
+| `className / style` | `string / CSSProperties` |  | <ol>에 전달. |
+
+### StepListStep / StepListItem
+
+steps 배열의 항목(id 필수)과 StepListItem의 props는 같아요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `id` (필수) | `string` |  | steps 배열에서만. key로 쓰여요. |
+| `status` (필수) | `'done' \| 'active' \| 'pending' \| 'error' \| 'warning'` |  | 단계 상태. |
+| `title` (필수) | `ReactNode` |  | 제목. |
+| `description` | `ReactNode` |  | 제목 아래 회색 글. Text variant="code" 칩을 함께 넣을 수 있어요. |
+| `meta` | `ReactNode` |  | 제목 줄 오른쪽 끝(걸린 시간 "1.9초", Elapsed). |
+| `children` | `ReactNode` |  | 설명 아래 내용(Collapsible inline, 경고 줄, FileChip). |
+| `marker` | `'status' \| 'number' \| 'status-number' \| ReactNode` |  | 이 단계만 다른 마커. 노드를 넘기면 그대로 그려요. |
+| `number` | `number \| string` |  | 번호 마커의 숫자. 기본은 순서(start부터). |
+| `progress` | `number` |  | active일 때 0–100. 링이 돌지 않고 그만큼 채워져요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 계획 카드
+
+Card + CardHeader(eyebrow 오버라인) + StepList + CardFooter band. marker="status-number"라 대기 단계는 번호, 진행 중은 파란 링, 완료는 회색 체크예요. 진행 중 단계와 아래 띠의 경과 시간은 Elapsed로 계속 올라가요.
+
+```tsx
+import { ListChecks } from 'lucide-react'
+import { Elapsed, Inline, StatusIcon, Text, formatElapsed, Card, CardBody, CardFooter, CardHeader, StepList, type StepListStep } from '@iamfiro/design'
+
+const STEPS: StepListStep[] = [
+  {
+    id: 'collect',
+    status: 'done',
+    title: '분기 실적 자료 모으기',
+    description: (
+      <>
+        재무팀 공유 폴더에서 <Text variant="code">q3-actuals.xlsx</Text> 불러옴
+      </>
+    ),
+    meta: '1.9초',
+  },
+  {
+    id: 'compare',
+    status: 'done',
+    title: '계획 대비 실적 비교',
+    description: (
+      <>
+        부서별 차이를 <Text variant="code">variance</Text> 시트로 정리
+      </>
+    ),
+    meta: '42초',
+  },
+  {
+    id: 'charts',
+    status: 'done',
+    title: '핵심 지표 차트 만들기',
+    description: '매출 · 영업이익 · 현금흐름 차트 3개',
+    meta: '3분 12초',
+  },
+  {
+    id: 'draft',
+    status: 'active',
+    title: '보고서 초안 작성',
+    description: (
+      <>
+        <Text variant="code">board-update-q3.docx</Text>에 요약과 차트를 넣는 중
+      </>
+    ),
+    // The running step keeps its own timer.
+    meta: <Elapsed initial={1052} format={(s) => formatElapsed(s, 'text')} />,
+  },
+  { id: 'review', status: 'pending', title: '검토 요청 보내기', description: '김민지 팀장에게 검토 요청' },
+]
+
+export default function Example() {
+  const done = STEPS.filter((s) => s.status === 'done').length
+  return (
+    <Card style={{ width: '100%', maxWidth: 480 }}>
+      <CardHeader
+        eyebrow={
+          <Inline gap={1} wrap={false}>
+            <ListChecks size={14} aria-hidden />
+            계획 · {STEPS.length}단계
+          </Inline>
+        }
+        title="3분기 이사회 보고서 준비"
+      />
+      <CardBody>
+        <StepList steps={STEPS} marker="status-number" aria-label="보고서 준비 단계" />
+      </CardBody>
+      <CardFooter band align="between">
+        <Inline gap={2} wrap={false}>
+          <StatusIcon status="active" size="sm" decorative />
+          <Text variant="label-sm" tone="secondary" numeric>
+            실행 중 · {done + 1}/{STEPS.length}
+          </Text>
+        </Inline>
+        <Text variant="label-sm" tone="tertiary">
+          <Elapsed initial={1060} />
+        </Text>
+      </CardFooter>
+    </Card>
+  )
+}
+```
+
+### 활동 기록
+
+StepListItem을 직접 조립해요. marker="number"는 모든 단계에 번호를 두고 테두리 색만 상태를 따라가요. 내용 자리엔 IconStack 타일을 단 Collapsible variant="inline"과 주황 경고 줄을 넣었어요. 마지막 단계처럼 marker에 노드를 넘기면 원하는 아이콘을 써요.
+
+```tsx
+import type { ReactNode } from 'react'
+import { FileSearch, ListChecks, Server, ShieldCheck, TestTube } from 'lucide-react'
+import { IconStack, IconTile, Inline, Stack, Text, Collapsible, StepList, StepListItem } from '@iamfiro/design'
+
+const tile = (key: string, icon: ReactNode) => (
+  <IconTile key={key} size={18}>
+    {icon}
+  </IconTile>
+)
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 480 }}>
+      <Text as="h3" variant="heading-xs">
+        활동
+      </Text>
+      <StepList marker="number" aria-label="배포 활동">
+        <StepListItem status="done" title="배포 설정 확인">
+          <Collapsible
+            variant="inline"
+            icon={
+              <IconStack
+                shape="square"
+                size={18}
+                overlap={4}
+                icons={[tile('config', <FileSearch size={11} />), tile('security', <ShieldCheck size={11} />)]}
+                label="설정 검사, 보안 검사"
+              />
+            }
+            label="검사 2개 · 1.2초"
+          >
+            <Text variant="body-sm" tone="secondary">
+              환경 변수 14개, 보안 정책 3개 모두 통과
+            </Text>
+          </Collapsible>
+        </StepListItem>
+        <StepListItem status="done" title="테스트 실행">
+          <Collapsible
+            variant="inline"
+            icon={<IconStack shape="square" size={18} icons={[tile('unit', <TestTube size={11} />)]} label="단위 테스트" />}
+            label="테스트 묶음 1개 · 2분 4초"
+          >
+            <Text variant="body-sm" tone="secondary">
+              812개 통과 · 건너뜀 3개
+            </Text>
+          </Collapsible>
+        </StepListItem>
+        <StepListItem status="done" title="스테이징 서버에 배포" description="v2.14.0 · 서버 4대" />
+        <StepListItem status="warning" title="운영 서버에 배포">
+          <Inline gap={1} wrap={false}>
+            <Text as="span" tone="warning" style={{ display: 'inline-flex' }}>
+              <ListChecks size={14} aria-hidden />
+            </Text>
+            <Text variant="label-sm" tone="warning">
+              승인을 기다리고 있어요
+            </Text>
+          </Inline>
+        </StepListItem>
+        <StepListItem
+          status="pending"
+          title="배포 후 모니터링"
+          description="마커는 직접 넣을 수도 있어요"
+          marker={
+            <IconTile size={18} round>
+              <Server size={11} />
+            </IconTile>
+          }
+        />
+      </StepList>
+    </Stack>
+  )
+}
+```
+
+### 상태 변화
+
+"다음 단계"를 누르면 마커가 링 → 체크로 넘어가고, connector="progress"의 파란 선이 다음 단계까지 위에서 아래로 차올라요.
+
+```tsx
+import { useState } from 'react'
+import { RotateCcw } from 'lucide-react'
+import { Button, Inline, Stack, StepList, type StepListStatus, type StepListStep } from '@iamfiro/design'
+
+const TITLES = ['코드 가져오기', '빌드', '테스트', '이미지 올리기', '배포']
+
+export default function Example() {
+  // How many steps are finished; the one after them is running.
+  const [done, setDone] = useState(1)
+  const steps: StepListStep[] = TITLES.map((title, i) => {
+    const status: StepListStatus = i < done ? 'done' : i === done ? 'active' : 'pending'
+    return { id: title, status, title, meta: i < done ? `${(i + 1) * 7}초` : undefined }
+  })
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 360 }}>
+      <StepList steps={steps} connector="progress" marker="status-number" density="compact" aria-label="배포 파이프라인" />
+      <Inline gap={2}>
+        <Button size="sm" variant="primary" disabled={done >= TITLES.length} onClick={() => setDone((d) => d + 1)}>
+          다음 단계
+        </Button>
+        <Button size="sm" variant="ghost" icon={<RotateCcw />} onClick={() => setDone(0)}>
+          처음부터
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 상태
+
+done · active · pending · error · warning. 기본 marker="status"는 대기를 회색 점선 원으로 그려요.
+
+```tsx
+import { Text, StepList, type StepListStep } from '@iamfiro/design'
+
+const STEPS: StepListStep[] = [
+  { id: 'submit', status: 'done', title: '휴가 신청서 제출', description: '이도현 · 10월 25일 오전 9:30' },
+  { id: 'lead', status: 'done', title: '팀장 승인', description: '김민지', meta: '12분' },
+  {
+    id: 'hr',
+    status: 'error',
+    title: '인사팀 확인',
+    description: (
+      <>
+        남은 연차가 부족해요 · <Text variant="code">잔여 1.5일</Text>
+      </>
+    ),
+    meta: '3분',
+  },
+  { id: 'fix', status: 'warning', title: '신청 기간 수정', description: '3일 → 1.5일로 바꿔 주세요' },
+  { id: 'final', status: 'pending', title: '최종 승인' },
+]
+
+export default function Example() {
+  return <StepList steps={STEPS} aria-label="휴가 승인 단계" style={{ width: '100%', maxWidth: 400 }} />
+}
+```
+
+### 크기 · 밀도
+
+size는 마커와 글자 크기(sm 16 · md 18 · lg 22px), density는 단계 사이 간격(compact 12 · default 20 · comfortable 32px)이에요.
+
+```tsx
+import { Grid, Stack, Text, StepList, type StepListDensity, type StepListSize, type StepListStep } from '@iamfiro/design'
+
+const STEPS: StepListStep[] = [
+  { id: 'quote', status: 'done', title: '견적 요청', meta: '2분' },
+  { id: 'review', status: 'active', title: '견적서 검토' },
+  { id: 'sign', status: 'pending', title: '계약서 서명' },
+]
+
+const VARIANTS: Array<{ size: StepListSize; density: StepListDensity }> = [
+  { size: 'sm', density: 'compact' },
+  { size: 'md', density: 'default' },
+  { size: 'lg', density: 'comfortable' },
+]
+
+export default function Example() {
+  return (
+    <Grid minItemWidth={160} gap={6} style={{ width: '100%' }}>
+      {VARIANTS.map(({ size, density }) => (
+        <Stack key={size} gap={3}>
+          <Text variant="overline">
+            {size} · {density}
+          </Text>
+          <StepList steps={STEPS} size={size} density={density} marker="number" aria-label={`${size} 크기`} />
+        </Stack>
+      ))}
+    </Grid>
+  )
+}
+```