@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/alert/AGENTS.md

@@ -0,0 +1,212 @@
+# Alert · Banner
+
+> 알림 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+토스트와 달리 화면에 머무르는 메시지. Alert는 폼 오류 · 한도 · 요금제 안내처럼 내용 옆에, Banner는 점검 · 체험 종료 · 새 버전처럼 화면 맨 위에 둬요. 테두리 없이 연한 배경으로 구분하고, 닫으면 접히듯 사라져요.
+
+```tsx
+import { Alert, Banner } from '@iamfiro/design'
+```
+
+## API
+
+### Alert
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `tone` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'info'` | 색과 기본 아이콘. |
+| `title` | `ReactNode` |  | 굵은 첫 줄. |
+| `children` | `ReactNode` |  | 본문. |
+| `icon` | `ReactNode \| false` |  | 아이콘을 바꾸거나 false로 숨겨요. |
+| `actions` | `ReactNode` |  | 버튼들. stacked면 본문 아래, inline이면 오른쪽. |
+| `onClose` | `() => void` |  | × 버튼을 보여주고, 접히는 애니메이션이 끝나면 불려요. |
+| `layout` | `'stacked' \| 'inline'` | `'stacked'` | stacked: 액션이 본문 아래 · inline: 한 줄, 액션은 오른쪽. |
+| `className` | `string` |  | 알림 요소에 전달. |
+
+### Banner
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | 메시지. |
+| `tone` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'info'` | 색과 기본 아이콘. |
+| `action` | `ReactNode` |  | 메시지 뒤 버튼 하나. |
+| `onClose` | `() => void` |  | × 버튼을 보여주고, 접히는 애니메이션이 끝나면 불려요. |
+| `icon` | `ReactNode \| false` |  | 아이콘을 바꾸거나 false로 숨겨요. |
+| `className` | `string` |  | 배너 요소에 전달. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 톤
+
+neutral · info · success · warning · danger. 톤마다 기본 아이콘이 있고, warning · danger는 role="alert"로 바로 읽혀요.
+
+```tsx
+import { Stack, Alert } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ width: 480 }}>
+      <Alert tone="neutral">변경 사항은 자동으로 저장돼요.</Alert>
+      <Alert tone="info">새 대시보드가 10월 28일부터 기본으로 켜져요.</Alert>
+      <Alert tone="success">결제 수단이 등록됐어요.</Alert>
+      <Alert tone="warning">저장 공간을 90% 사용했어요.</Alert>
+      <Alert tone="danger">카드 승인이 거절됐어요. 다른 카드로 다시 시도해 주세요.</Alert>
+    </Stack>
+  )
+}
+```
+
+### 제목과 액션
+
+title로 요점을 먼저 쓰고, actions에 다음 행동 버튼을 둬요. icon으로 아이콘을 바꾸거나 false로 숨겨요.
+
+```tsx
+import { ShieldCheck } from 'lucide-react'
+import { Button, Stack, Alert } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ width: 480 }}>
+      <Alert
+        tone="warning"
+        title="이번 달 API 호출 한도에 가까워요"
+        actions={
+          <>
+            <Button variant="primary" size="sm">
+              요금제 올리기
+            </Button>
+            <Button variant="ghost" size="sm">
+              사용량 보기
+            </Button>
+          </>
+        }
+      >
+        10월 31일까지 남은 호출은 1,240회예요. 한도를 넘으면 요청이 잠시 거절돼요.
+      </Alert>
+      <Alert
+        tone="neutral"
+        icon={<ShieldCheck />}
+        title="2단계 인증을 켜 주세요"
+        actions={
+          <Button size="sm">
+            지금 설정
+          </Button>
+        }
+      >
+        조직 관리자가 11월 1일부터 모든 멤버에게 2단계 인증을 요구해요.
+      </Alert>
+      <Alert tone="info" icon={false}>
+        아이콘 없이 텍스트만 보여줄 수도 있어요.
+      </Alert>
+    </Stack>
+  )
+}
+```
+
+### 한 줄 배치
+
+layout="inline"이면 액션이 오른쪽에 붙어 한 줄로 끝나요.
+
+```tsx
+import { Button, Stack, Alert } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ width: 560 }}>
+      <Alert tone="info" layout="inline" actions={<Button size="sm">새로고침</Button>}>
+        새 버전이 배포됐어요.
+      </Alert>
+      <Alert tone="danger" layout="inline" title="동기화 실패" actions={<Button size="sm">다시 시도</Button>}>
+        2분 전부터 Google Drive와 연결되지 않아요.
+      </Alert>
+    </Stack>
+  )
+}
+```
+
+### 닫기
+
+onClose를 주면 × 버튼이 생겨요. 접히는 애니메이션이 끝난 뒤 onClose가 불리니, 그때 상태에서 지우세요.
+
+```tsx
+import { useState } from 'react'
+import { RotateCcw } from 'lucide-react'
+import { Button, Inline, Stack, Alert, type AlertTone } from '@iamfiro/design'
+
+const NOTICES: Array<{ id: string; tone: AlertTone; title: string; body: string }> = [
+  { id: 'invite', tone: 'success', title: '초대를 보냈어요', body: '박서연님이 수락하면 알려 드릴게요.' },
+  { id: 'export', tone: 'info', title: '내보내기를 준비하고 있어요', body: '완료되면 minji@lumen.app으로 링크를 보내 드려요.' },
+  { id: 'billing', tone: 'warning', title: '결제 정보를 확인해 주세요', body: '등록된 카드가 11월에 만료돼요.' },
+]
+
+const ALL = NOTICES.map((n) => n.id)
+
+export default function Example() {
+  const [visible, setVisible] = useState(ALL)
+  return (
+    <Stack gap={3} style={{ width: 480 }}>
+      {NOTICES.filter((n) => visible.includes(n.id)).map((n) => (
+        <Alert key={n.id} tone={n.tone} title={n.title} onClose={() => setVisible((v) => v.filter((id) => id !== n.id))}>
+          {n.body}
+        </Alert>
+      ))}
+      <Inline>
+        <Button variant="secondary" size="sm" icon={<RotateCcw />} disabled={visible.length === ALL.length} onClick={() => setVisible(ALL)}>
+          다시 보기
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### Banner
+
+앱이나 카드 맨 위의 가로 띠. 액션 하나와 닫기를 둘 수 있어요.
+
+```tsx
+import { useState } from 'react'
+import { RotateCcw, Wrench } from 'lucide-react'
+import { Box, Button, Stack, Text, Banner, Card } from '@iamfiro/design'
+
+export default function Example() {
+  const [trial, setTrial] = useState(true)
+  return (
+    <Stack gap={6} align="start">
+      <Card padding="none" style={{ width: 520, overflow: 'hidden' }}>
+        {trial && (
+          <Banner
+            tone="warning"
+            action={
+              <Button variant="ghost" size="sm">
+                요금제 보기
+              </Button>
+            }
+            onClose={() => setTrial(false)}
+          >
+            무료 체험이 3일 남았어요.
+          </Banner>
+        )}
+        <Box padding={5}>
+          <Stack gap={1}>
+            <Text variant="heading-sm">대시보드</Text>
+            <Text variant="body-sm" tone="secondary">
+              10월 25일 기준 이번 주 방문자는 8,903명이에요.
+            </Text>
+          </Stack>
+        </Box>
+      </Card>
+      <Button variant="secondary" size="sm" icon={<RotateCcw />} disabled={trial} onClick={() => setTrial(true)}>
+        다시 보기
+      </Button>
+      <Box radius="md" style={{ width: 520, overflow: 'hidden' }}>
+        <Banner tone="neutral" icon={<Wrench />}>
+          10월 27일 새벽 2시부터 30분간 점검이 있어요.
+        </Banner>
+      </Box>
+    </Stack>
+  )
+}
+```

package/agents/alert-dialog/AGENTS.md

@@ -0,0 +1,193 @@
+# AlertDialog
+
+> 메뉴 & 오버레이 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+되돌릴 수 없는 작업(영구 삭제, 결제, 대량 발송) 바로 앞에 한 번 더 묻는 확인 창. 버튼에는 "확인" 대신 동작 이름("삭제", "보내기")을 써요. 되돌릴 수 있는 작업(휴지통으로 이동, 보관, 옮기기)이라면 확인 창을 띄우지 말고 바로 실행한 뒤 toast.undo(제목, { onUndo, onCommit })로 "실행 취소"를 보여 주세요 — 실제 영구 처리는 onCommit에서 해요.
+
+```tsx
+import { AlertDialog } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 되돌릴 수 없는 작업의 확인은 `AlertDialog`: 버튼에 동작 이름, 위험하면 포커스는 "취소"에서 시작, 비동기면 진행 중 잠금·실패 시 열린 채 오류 표시, 가장 위험하면 이름 입력 확인(`confirmationText`).
+
+## API
+
+### AlertDialog
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` (필수) | `ReactNode` |  | 질문 형태의 제목. 예: "대화 기록을 삭제할까요?" |
+| `description` | `ReactNode` |  | 무엇이 어떻게 되는지, 되돌릴 수 있는지. |
+| `confirmLabel` (필수) | `ReactNode` |  | 확인 버튼 문구. 동작 이름을 쓰세요("삭제", "29,000원 결제"). |
+| `onConfirm` (필수) | `() => void \| Promise<void>` |  | Promise면 끝날 때까지 로딩·잠금. 던진 Error의 message가 창 안에 표시되고 창은 열린 채 남아요. |
+| `tone` | `'default' \| 'danger'` | `'default'` | danger: 경고 아이콘 + 빨간 버튼 + 취소에 첫 포커스. |
+| `cancelLabel` | `ReactNode` | `'취소'` | 취소 버튼 문구. |
+| `confirmationText` | `string` |  | 이 글자를 정확히 입력해야 확인 버튼이 켜져요(예: 프로젝트 이름). |
+| `children` | `ReactNode` |  | 설명 아래 추가 내용(삭제될 항목, 결제 내역 등). |
+| `trigger` | `ReactElement` |  | 누르면 여는 버튼. |
+| `open / onOpenChange` | `boolean / (open) => void` |  | 열림 상태를 밖에서 제어할 때(메뉴 항목에서 열 때 등). |
+| `defaultOpen` | `boolean` | `false` | 처음 열림 상태(비제어). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 위험한 작업
+
+tone="danger"면 경고 아이콘과 빨간 버튼이 붙고, 포커스가 "취소"에서 시작해 Enter를 눌러도 아무것도 지워지지 않아요.
+
+```tsx
+import { Trash2 } from 'lucide-react'
+import { Button, AlertDialog, toast } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <AlertDialog
+      tone="danger"
+      trigger={
+        <Button variant="danger" icon={<Trash2 />}>
+          대화 기록 삭제
+        </Button>
+      }
+      title="대화 기록을 모두 삭제할까요?"
+      description="지난 90일 동안의 대화 312개가 영구 삭제돼요. 삭제한 기록은 되돌릴 수 없어요."
+      confirmLabel="삭제"
+      onConfirm={() => {
+        toast.success('대화 기록을 삭제했어요')
+      }}
+    />
+  )
+}
+```
+
+### 비동기 확인
+
+onConfirm이 Promise를 돌려주면 버튼이 돌아가고 끝날 때까지 창이 잠겨요(Esc·바깥 클릭·취소 불가). 성공하면 닫히고, 오류를 던지면 열린 채 그 메시지를 보여 줘서 바로 다시 시도할 수 있어요. 두 번째 버튼은 실패하는 경우예요.
+
+```tsx
+import { Send } from 'lucide-react'
+import { Button, Inline, AlertDialog, toast } from '@iamfiro/design'
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+async function sendNotice() {
+  await wait(1500)
+  toast.success('공지를 248명에게 보냈어요')
+}
+
+async function sendNoticeOffline() {
+  await wait(1500)
+  throw new Error('네트워크 연결이 끊겼어요. 연결을 확인하고 다시 시도해 주세요.')
+}
+
+export default function Example() {
+  return (
+    <Inline gap={2}>
+      <AlertDialog
+        trigger={<Button icon={<Send />}>공지 보내기</Button>}
+        title="전체 멤버에게 공지를 보낼까요?"
+        description="248명에게 메일과 앱 알림이 바로 발송돼요. 보낸 뒤에는 취소할 수 없어요."
+        confirmLabel="보내기"
+        onConfirm={sendNotice}
+      />
+      <AlertDialog
+        trigger={<Button icon={<Send />}>공지 보내기 (실패)</Button>}
+        title="전체 멤버에게 공지를 보낼까요?"
+        description="248명에게 메일과 앱 알림이 바로 발송돼요. 보낸 뒤에는 취소할 수 없어요."
+        confirmLabel="보내기"
+        onConfirm={sendNoticeOffline}
+      />
+    </Inline>
+  )
+}
+```
+
+### 이름 입력 확인
+
+가장 위험한 작업은 confirmationText를 정확히 입력해야 버튼이 켜져요. 열리면 입력칸에 바로 포커스가 가요. children으로 함께 사라지는 것을 보여 주세요.
+
+```tsx
+import { Trash2 } from 'lucide-react'
+import { Button, Stack, Text, AlertDialog, toast } from '@iamfiro/design'
+
+const PROJECT = 'lumen-web'
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+export default function Example() {
+  return (
+    <AlertDialog
+      tone="danger"
+      trigger={
+        <Button variant="danger" icon={<Trash2 />}>
+          프로젝트 삭제
+        </Button>
+      }
+      title="프로젝트를 영구 삭제할까요?"
+      description="이 작업은 되돌릴 수 없어요."
+      confirmationText={PROJECT}
+      confirmLabel="프로젝트 삭제"
+      onConfirm={async () => {
+        await wait(1200)
+        toast.success(`${PROJECT} 프로젝트를 삭제했어요`)
+      }}
+    >
+      <Stack gap={1}>
+        <Text variant="body-sm" tone="secondary">
+          함께 삭제되는 항목
+        </Text>
+        <Text variant="body-md">배포 128개 · 환경 변수 24개 · 연결된 도메인 2개</Text>
+      </Stack>
+    </AlertDialog>
+  )
+}
+```
+
+### 기본 톤
+
+파괴적이지 않지만 되돌리기 어려운 작업(결제 등)은 기본 톤을 써요. 검정 버튼에 포커스가 가서 Enter로 바로 진행할 수 있어요.
+
+```tsx
+import { CreditCard } from 'lucide-react'
+import { Button, Inline, Stack, Text, AlertDialog, toast } from '@iamfiro/design'
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+export default function Example() {
+  return (
+    <AlertDialog
+      trigger={
+        <Button variant="primary" icon={<CreditCard />}>
+          팀 플랜으로 업그레이드
+        </Button>
+      }
+      title="팀 플랜을 결제할까요?"
+      description="등록된 카드로 바로 결제되고, 다음 달부터 매월 11월 25일에 자동 결제돼요."
+      confirmLabel="29,000원 결제"
+      onConfirm={async () => {
+        await wait(1200)
+        toast.success('팀 플랜을 시작했어요')
+      }}
+    >
+      <Stack gap={2}>
+        <Inline justify="between">
+          <Text variant="body-md" tone="secondary">
+            팀 플랜 · 월간
+          </Text>
+          <Text variant="body-md" numeric>
+            29,000원
+          </Text>
+        </Inline>
+        <Inline justify="between">
+          <Text variant="body-md" tone="secondary">
+            결제 카드
+          </Text>
+          <Text variant="body-md">신한카드 ···· 4021</Text>
+        </Inline>
+      </Stack>
+    </AlertDialog>
+  )
+}
+```