@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/skeleton/AGENTS.md

@@ -0,0 +1,166 @@
+# Skeleton
+
+> 진행 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+내용이 들어올 자리를 미리 보여 주는 회색 자리 표시. 실제 레이아웃과 같은 크기로 그려 두면 내용이 들어올 때 화면이 덜컹거리지 않아요. SkeletonGroup으로 감싸면 로딩이 끝날 때 실제 내용으로 부드럽게 바뀌어요.
+
+```tsx
+import { Skeleton, SkeletonText, SkeletonCircle, SkeletonGroup } from '@iamfiro/design'
+```
+
+## API
+
+### Skeleton
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `width` | `number \| string` | `'100%'` | 너비. 숫자는 px. |
+| `height` | `number \| string` | `16` | 높이. 숫자는 px. |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full' \| number` | `'sm'` | 모서리(0 / 6 / 10 / 16px / 원형). |
+| `animation` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | 움직임. shimmer는 빛이 지나가고, pulse는 깜빡여요. |
+| `className / style` | `string / CSSProperties` |  | 블록에 적용돼요. |
+
+### SkeletonText
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `lines` | `number` | `3` | 줄 수. |
+| `lastLineWidth` | `string` | `'62%'` | 마지막 줄 너비(2줄 이상일 때). 문단처럼 보이게 해요. |
+| `variant` | `TextVariant` | `'body-md'` | 맞출 글자 역할. 줄 높이가 실제 Text와 같아져요. |
+| `animation` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | 움직임. shimmer는 빛이 지나가고, pulse는 깜빡여요. |
+| `className` | `string` |  | 루트에 붙일 클래스. |
+
+### SkeletonCircle
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `size` | `number` | `36` | 지름(px). |
+| `animation` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | 움직임. shimmer는 빛이 지나가고, pulse는 깜빡여요. |
+
+### SkeletonGroup
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `loading` (필수) | `boolean` |  | true면 fallback, false면 children을 보여 줘요. |
+| `fallback` (필수) | `ReactNode` |  | 로딩 중에 보여 줄 스켈레톤. |
+| `children` (필수) | `ReactNode` |  | 실제 내용. |
+| `label` | `string` | `'불러오는 중'` | 로딩 중 스크린 리더가 읽는 이름. |
+| `className` | `string` |  | 루트에 붙일 클래스. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본 모양
+
+Skeleton은 크기와 모서리를 정하는 블록, SkeletonCircle은 아바타 자리, SkeletonText는 글자 역할(variant)의 줄 높이에 맞춘 문단이에요.
+
+```tsx
+import { Skeleton, SkeletonCircle, SkeletonText } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 20, width: 360 }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+        <SkeletonCircle size={40} />
+        <div style={{ display: 'grid', gap: 8, flex: 1 }}>
+          <Skeleton width="40%" height={14} />
+          <Skeleton width="65%" height={12} />
+        </div>
+      </div>
+      <Skeleton height={180} radius="lg" />
+      <div style={{ display: 'grid', gap: 6 }}>
+        <div style={{ width: '70%' }}>
+          <SkeletonText variant="heading-sm" lines={1} />
+        </div>
+        <SkeletonText lines={3} lastLineWidth="45%" />
+      </div>
+    </div>
+  )
+}
+```
+
+### 애니메이션
+
+여러 줄이면 줄마다 조금씩 늦게 시작해서 물결처럼 보여요.
+
+```tsx
+import { Text, SkeletonCircle, SkeletonText, type SkeletonAnimation } from '@iamfiro/design'
+
+const ANIMATIONS: Array<[SkeletonAnimation, string]> = [
+  ['shimmer', '빛이 지나가요 (기본)'],
+  ['pulse', '천천히 깜빡여요'],
+  ['none', '움직이지 않아요'],
+]
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))', gap: 28, width: '100%', maxWidth: 640 }}>
+      {ANIMATIONS.map(([animation, label]) => (
+        <div key={animation} style={{ display: 'grid', gap: 12 }}>
+          <SkeletonCircle size={32} animation={animation} />
+          <SkeletonText lines={3} animation={animation} />
+          <Text variant="caption" tone="tertiary">
+            {animation} · {label}
+          </Text>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### 실제 내용으로 바꾸기
+
+SkeletonGroup은 loading 동안 fallback을 보여 주고, 끝나면 children을 서서히 나타내요. 로딩 중에는 aria-busy가 붙어요.
+
+```tsx
+import { useState } from 'react'
+import { FolderKanban } from 'lucide-react'
+import { AvatarGroup, Switch, Card, CardBody, CardFooter, CardHeader, Skeleton, SkeletonGroup, SkeletonText } from '@iamfiro/design'
+
+function ProjectCardSkeleton() {
+  return (
+    <Card style={{ width: 360 }}>
+      <CardHeader
+        icon={<Skeleton width={40} height={40} radius="md" />}
+        title={
+          <div style={{ width: '55%' }}>
+            <SkeletonText variant="heading-sm" lines={1} />
+          </div>
+        }
+        description={
+          <div style={{ width: '80%' }}>
+            <SkeletonText variant="body-sm" lines={1} />
+          </div>
+        }
+      />
+      <CardBody>
+        <SkeletonText lines={2} />
+      </CardBody>
+      <CardFooter align="start">
+        <Skeleton width={84} height={24} radius="full" />
+      </CardFooter>
+    </Card>
+  )
+}
+
+export default function Example() {
+  const [loading, setLoading] = useState(true)
+
+  return (
+    <div style={{ display: 'grid', justifyItems: 'center', gap: 20 }}>
+      <Switch label="불러오는 중" checked={loading} onChange={(e) => setLoading(e.target.checked)} />
+      <SkeletonGroup loading={loading} fallback={<ProjectCardSkeleton />}>
+        <Card style={{ width: 360 }}>
+          <CardHeader icon={<FolderKanban />} title="웹사이트 리뉴얼" description="김민지 외 3명 · 2분 전 수정" />
+          <CardBody>새 랜딩 페이지 시안을 검토하고 있어요. 금요일까지 피드백을 남겨 주세요.</CardBody>
+          <CardFooter align="start">
+            <AvatarGroup names={['김민지', '이도현', '박서연', '최준호']} />
+          </CardFooter>
+        </Card>
+      </SkeletonGroup>
+    </div>
+  )
+}
+```

package/agents/slider/AGENTS.md

@@ -0,0 +1,181 @@
+# Slider
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+끌어서 값을 고르는 슬라이더. 숫자 하나를 주면 단일 값, [시작, 끝]을 주면 범위가 돼요. 끄는 동안은 미리보기(onValueChange), 손을 놓을 때 확정(onValueCommit)하고, 끄는 중에 Esc를 누르면 원래 값으로 돌아가요.
+
+```tsx
+import { Slider } from '@iamfiro/design'
+```
+
+## API
+
+### Slider
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `number \| [number, number]` |  | 값(제어). 튜플이면 범위 슬라이더. |
+| `defaultValue` | `number \| [number, number]` | `min` | 처음 값(비제어). 범위는 반드시 튜플로 주세요. |
+| `onValueChange` | `(value) => void` |  | 끄는 동안·키 입력마다 호출(미리보기). |
+| `onValueCommit` | `(value) => void` |  | 손을 놓을 때 / 키를 누를 때 한 번 호출(확정). Esc로 취소하면 호출되지 않아요. |
+| `min` | `number` | `0` | 최솟값. |
+| `max` | `number` | `100` | 최댓값. |
+| `step` | `number` | `1` | 단위. 소수(0.1 등)도 돼요. |
+| `minDistance` | `number` | `0` | 범위 전용. 두 손잡이 사이 최소 간격. |
+| `marks` | `Array<number \| { value: number; label?: ReactNode }>` |  | 트랙 아래 눈금. label이 있으면 글자도 표시. |
+| `formatValue` | `(value: number) => string` | `String` | 말풍선과 스크린 리더(aria-valuetext)에 쓰는 표시 형식. |
+| `showValue` | `'auto' \| 'always' \| 'never'` | `'auto'` | 값 말풍선: 조작할 때만 / 항상 / 안 보임. |
+| `size` | `'sm' \| 'md'` | `'md'` | 손잡이 18 / 14px. |
+| `disabled` | `boolean` |  | 비활성. |
+| `name` | `string` |  | 폼 제출용 hidden input 이름. 범위는 name[0], name[1]. |
+| `aria-label` | `string` |  | 손잡이 이름. |
+| `getThumbLabel` | `(index: number) => string` |  | 범위에서 손잡이별 이름. 예: (i) => (i === 0 ? '최소 가격' : '최대 가격'). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+트랙 어디를 눌러도 그 위치로 옮겨가요. 끄는 동안 위에 값 말풍선이 뜨고, formatValue로 단위를 붙여요. ←→ 한 칸, PageUp/PageDown 크게, Home/End 끝으로.
+
+```tsx
+import { useState } from 'react'
+import { Volume1, Volume2 } from 'lucide-react'
+import { Slider } from '@iamfiro/design'
+
+export default function Example() {
+  const [volume, setVolume] = useState(60)
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 12, width: 340 }}>
+      <Volume1 size={18} color="var(--text-3)" />
+      <div style={{ flex: 1 }}>
+        <Slider value={volume} onValueChange={setVolume} formatValue={(v) => `${v}%`} aria-label="볼륨" />
+      </div>
+      <Volume2 size={18} color="var(--text-3)" />
+    </div>
+  )
+}
+```
+
+### 범위
+
+눌린 위치에서 가까운 손잡이가 움직여요. minDistance로 두 손잡이 사이 최소 간격을, getThumbLabel로 손잡이별 이름을 정해요.
+
+```tsx
+import { useState } from 'react'
+import { Text, Slider } from '@iamfiro/design'
+
+const won = (v: number) => (v >= 10000 ? `${(v / 10000).toLocaleString('ko-KR')}만원` : `${v.toLocaleString('ko-KR')}원`)
+
+export default function Example() {
+  const [price, setPrice] = useState<[number, number]>([100000, 350000])
+  return (
+    <div style={{ display: 'grid', gap: 12, width: 360 }}>
+      <Text variant="label-md" numeric>
+        가격 {won(price[0])} – {won(price[1])}
+      </Text>
+      <Slider
+        value={price}
+        onValueChange={setPrice}
+        min={0}
+        max={500000}
+        step={10000}
+        minDistance={50000}
+        formatValue={won}
+        getThumbLabel={(i) => (i === 0 ? '최소 가격' : '최대 가격')}
+      />
+    </div>
+  )
+}
+```
+
+### 눈금
+
+marks에 label을 넣으면 트랙 아래에 글자가 찍혀요. 숫자만 넣으면 눈금만 그려요. showValue로 말풍선을 항상 / 끄기 할 수 있어요.
+
+```tsx
+import { useState } from 'react'
+import { Slider } from '@iamfiro/design'
+
+const QUALITY = ['낮음', '보통', '높음', '최고']
+
+export default function Example() {
+  const [quality, setQuality] = useState(2)
+  return (
+    <div style={{ display: 'grid', gap: 32, width: 360 }}>
+      <Slider
+        value={quality}
+        onValueChange={setQuality}
+        min={0}
+        max={3}
+        marks={QUALITY.map((label, value) => ({ value, label }))}
+        formatValue={(v) => QUALITY[v]}
+        showValue="never"
+        aria-label="화질"
+      />
+      <Slider defaultValue={40} step={20} marks={[0, 20, 40, 60, 80, 100]} formatValue={(v) => `${v}%`} showValue="always" aria-label="투명도" />
+    </div>
+  )
+}
+```
+
+### 미리보기와 확정
+
+저장이나 서버 요청은 onValueCommit에서 하세요. 끄는 중 Esc를 누르면 미리보기가 취소되고 아무것도 확정되지 않아요.
+
+```tsx
+import { useState } from 'react'
+import { Text, Slider } from '@iamfiro/design'
+
+export default function Example() {
+  const [preview, setPreview] = useState(120)
+  const [saved, setSaved] = useState(120)
+  return (
+    <div style={{ display: 'grid', gap: 12, width: 360 }}>
+      <Slider
+        value={preview}
+        onValueChange={setPreview}
+        onValueCommit={setSaved}
+        min={30}
+        max={300}
+        step={10}
+        formatValue={(v) => `${v}분`}
+        aria-label="자동 잠금 시간"
+      />
+      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+        <Text variant="body-sm" tone="secondary" numeric>
+          미리보기 {preview}분
+        </Text>
+        <Text variant="body-sm" weight="semibold" numeric>
+          저장됨 {saved}분
+        </Text>
+      </div>
+    </div>
+  )
+}
+```
+
+### 크기와 비활성
+
+size sm / md, disabled.
+
+```tsx
+import { Field, Slider } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 20, width: 340 }}>
+      <Field label="작게 (sm)">
+        <Slider size="sm" defaultValue={40} aria-label="밝기" />
+      </Field>
+      <Field label="작게 (sm) · 범위">
+        <Slider size="sm" defaultValue={[20, 70]} getThumbLabel={(i) => (i === 0 ? '최소 온도' : '최대 온도')} />
+      </Field>
+      <Field label="비활성">
+        <Slider defaultValue={30} disabled aria-label="비활성 슬라이더" />
+      </Field>
+    </div>
+  )
+}
+```

package/agents/social-login-button/AGENTS.md

@@ -0,0 +1,156 @@
+# SocialLoginButton
+
+> 버튼 & 링크 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+Google · Apple 계정으로 로그인하는 버튼. 각 브랜드 가이드대로 Google은 흰 바탕 + 옅은 윤곽 + 색 G 로고, Apple은 검정 바탕 + 흰 로고예요. 문구는 action으로 고르고, 나머지 props는 Button과 같아요.
+
+```tsx
+import { SocialLoginButton } from '@iamfiro/design'
+```
+
+## API
+
+### SocialLoginButton
+
+variant · icon은 provider가 정해요. 나머지 props(size · block · loading · disabled · onClick…)는 Button에 그대로 전달돼요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `provider` (필수) | `'google' \| 'apple'` |  | 로그인 제공자. 색 · 로고 · 이름이 정해져요. |
+| `action` | `'continue' \| 'signin' \| 'signup'` | `'continue'` | "Google로 계속하기" · "Google로 로그인" · "Google로 가입하기". |
+| `children` | `ReactNode` |  | 문구를 직접 바꿀 때. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 높이 28 / 34 / 40px. 로고는 14 / 16 / 18px. |
+| `iconOnly` | `boolean` |  | 로고만 보이는 정사각형 버튼. aria-label은 문구로 붙어요. |
+| `block` | `boolean` |  | 너비 100%. |
+| `loading` | `boolean` |  | 로고 자리에 스피너, 클릭 막음. 인증 창으로 넘어가는 동안 써요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+로그인 화면에선 block으로 폭을 채워 위아래로 쌓아요. 순서는 보통 Google → Apple.
+
+```tsx
+import { SocialLoginButton, Stack } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={2} style={{ width: 320 }}>
+      <SocialLoginButton provider="google" size="lg" block />
+      <SocialLoginButton provider="apple" size="lg" block />
+    </Stack>
+  )
+}
+```
+
+### 문구
+
+action='continue'(기본) · 'signin' · 'signup'. 로그인과 가입을 한 화면에서 받으면 continue를 써요.
+
+```tsx
+import { SocialLoginButton, Inline, Stack } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={3}>
+      <Inline gap={2}>
+        <SocialLoginButton provider="google" action="continue" />
+        <SocialLoginButton provider="google" action="signin" />
+        <SocialLoginButton provider="google" action="signup" />
+      </Inline>
+      <Inline gap={2}>
+        <SocialLoginButton provider="apple" action="continue" />
+        <SocialLoginButton provider="apple" action="signin" />
+        <SocialLoginButton provider="apple" action="signup" />
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 크기 · 아이콘만
+
+sm · md · lg는 Button과 같은 높이. iconOnly면 로고만 보이고 aria-label은 문구로 자동으로 붙어요.
+
+```tsx
+import { SocialLoginButton, Inline, Stack } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={3}>
+      <Inline gap={2}>
+        <SocialLoginButton provider="google" size="sm" />
+        <SocialLoginButton provider="google" />
+        <SocialLoginButton provider="google" size="lg" />
+      </Inline>
+      <Inline gap={2}>
+        <SocialLoginButton provider="google" iconOnly />
+        <SocialLoginButton provider="apple" iconOnly />
+        <SocialLoginButton provider="google" size="lg" iconOnly />
+        <SocialLoginButton provider="apple" size="lg" iconOnly />
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 로그인 카드
+
+Card 안에 소셜 버튼 → "또는" Separator → 이메일 입력. 누르면 loading으로 잠가 두 번 눌리지 않게 해요.
+
+```tsx
+import { useState } from 'react'
+import { Card, CardBody, CardHeader, SocialLoginButton, type SocialProvider, Button, Field, Input, Separator, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [pending, setPending] = useState<SocialProvider | null>(null)
+
+  // 실제 앱에선 여기서 OAuth 창으로 넘어가요. 예제는 2초 뒤 풀어요.
+  const signIn = (provider: SocialProvider) => {
+    setPending(provider)
+    window.setTimeout(() => setPending(null), 2000)
+  }
+
+  return (
+    <Card style={{ width: 360 }}>
+      <CardHeader title="Lumen에 로그인" description="팀 워크스페이스로 계속하려면 로그인하세요." />
+      <CardBody>
+        <Stack gap={4}>
+          <Stack gap={2}>
+            <SocialLoginButton
+              provider="google"
+              size="lg"
+              block
+              loading={pending === 'google'}
+              disabled={pending !== null}
+              onClick={() => signIn('google')}
+            />
+            <SocialLoginButton
+              provider="apple"
+              size="lg"
+              block
+              loading={pending === 'apple'}
+              disabled={pending !== null}
+              onClick={() => signIn('apple')}
+            />
+          </Stack>
+          <Separator label="또는" />
+          <Stack gap={3}>
+            <Field label="이메일" htmlFor="login-email">
+              <Input id="login-email" type="email" placeholder="minji@lumen.co" />
+            </Field>
+            <Button variant="secondary" size="lg" block>
+              이메일로 계속하기
+            </Button>
+          </Stack>
+          <Text variant="caption" tone="secondary">
+            계속하면 서비스 약관과 개인정보 처리방침에 동의하게 돼요.
+          </Text>
+        </Stack>
+      </CardBody>
+    </Card>
+  )
+}
+```