@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/drawer/AGENTS.md

@@ -0,0 +1,471 @@
+# Drawer · Sheet
+
+> 메뉴 & 오버레이 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+화면 가장자리에서 미끄러져 들어오는 패널. 상세 보기·필터·설정처럼 지금 화면을 떠나지 않고 조금 긴 내용을 다룰 때 써요. Dialog와 같은 장치(포커스 가두기, 배경 스크롤 잠금, Esc·바깥 클릭 닫기, 닫으면 트리거로 포커스 복귀)를 쓰고, 나갈 때는 들어온 방향으로 다시 미끄러져 나가요. 아래에서 올라오는 Sheet는 손잡이·제목줄을 끌어 닫거나 높이를 바꿀 수 있어요.
+
+```tsx
+import { Drawer, Sheet } from '@iamfiro/design'
+```
+
+## API
+
+### Drawer
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` (필수) | `ReactNode` |  | 제목. 패널의 접근성 이름(aria-labelledby)이 돼요. |
+| `description` | `ReactNode` |  | 제목 아래 설명(aria-describedby). |
+| `children` | `ReactNode` |  | 본문. 길면 이 부분만 스크롤돼요. |
+| `footer` | `ReactNode` |  | 아래에 고정되는 버튼 줄(오른쪽 정렬). |
+| `trigger` | `ReactElement` |  | 누르면 여는 버튼. aria-haspopup · aria-expanded가 붙고 원래 onClick도 실행돼요. |
+| `open / onOpenChange` | `boolean / (open) => void` |  | 열림 상태를 밖에서 제어할 때. |
+| `defaultOpen` | `boolean` | `false` | 처음 열림 상태(비제어). |
+| `side` | `'right' \| 'left' \| 'top' \| 'bottom'` | `'right'` | 들어오는 가장자리. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | 좌우: 폭 360 / 440 / 640px / 전체(휴대폰에선 화면 폭 - 40px까지). 위아래: 최대 높이 50 / 75 / 92% / 전체. |
+| `dismissible` | `boolean` | `true` | Esc · 바깥 클릭 · × · 끌어 닫기. 저장 중엔 false로. |
+| `showClose` | `boolean` | `true` | 오른쪽 위 ×. dismissible이 false면 숨겨져요. |
+| `initialFocus` | `RefObject<HTMLElement>` |  | 열릴 때 포커스할 요소. 생략하면 첫 번째 포커스 가능한 요소. |
+| `hideTitle` | `boolean` | `false` | 제목·설명을 화면에서만 숨겨요(스크린 리더는 읽어요). |
+| `modal` | `boolean` | `true` | false면 배경 어둡게·스크롤 잠금·포커스 가두기 없이 뒤 페이지를 그대로 쓸 수 있어요. 바깥 클릭으로는 닫히지 않고 Esc·×로 닫혀요. |
+| `inset` | `boolean` | `false` | 가장자리에서 8px 띄우고 모든 모서리를 둥글게. |
+| `handle` | `boolean` | `side === 'bottom'` | 끌기 손잡이(위·아래 서랍만). 아래 서랍은 제목줄도 함께 끌려요. |
+| `snapPoints` | `number[]` |  | 멈춤 지점 — 전체 높이에 대한 비율(오름차순, 예: [0.5, 1]). 놓으면 가장 가까운 지점에, 튕기면 그 방향으로 넘어가요. |
+| `snap / onSnapChange` | `number / (snap) => void` |  | 현재 멈춤 지점(제어). |
+| `defaultSnap` | `number` | `snapPoints의 가장 큰 값` | 열릴 때마다 처음 멈춤 지점(비제어). |
+| `className` | `string` |  | 패널에 붙는 클래스. |
+
+### Sheet
+
+Drawer side='bottom'과 같아요(손잡이 기본 켜짐). side를 뺀 모든 prop을 받아요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `…DrawerProps` | `Omit<DrawerProps, 'side'>` |  | Drawer와 같아요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+오른쪽에서 열리는 상세 패널. 제목·설명은 위에, 버튼 줄은 아래에 고정되고 본문만 스크롤돼요.
+
+```tsx
+import { Receipt } from 'lucide-react'
+import { Avatar, Badge, Button, Inline, Stack, Text, DescriptionList, Drawer, List, ListItem } from '@iamfiro/design'
+
+const ITEMS = [
+  { id: 'i1', name: '무선 키보드 K3', option: '화이트 · 1개', price: '129,000원' },
+  { id: 'i2', name: '손목 받침대', option: '그레이 · 2개', price: '76,000원' },
+]
+
+export default function Example() {
+  return (
+    <Drawer
+      trigger={<Button icon={<Receipt />}>주문 상세 보기</Button>}
+      title="주문 #20481"
+      description="10월 25일 오후 2:14에 결제됐어요."
+      footer={
+        <>
+          <Button>영수증 받기</Button>
+          <Button variant="primary">배송 조회</Button>
+        </>
+      }
+    >
+      <Stack gap={5}>
+        <Inline gap={2}>
+          <Badge tone="info" dot>
+            배송 중
+          </Badge>
+          <Badge>무료 배송</Badge>
+        </Inline>
+        <DescriptionList
+          size="sm"
+          columns={1}
+          layout="inline"
+          aria-label="주문 정보"
+          items={[
+            {
+              label: '주문자',
+              value: (
+                <Inline gap={2} wrap={false}>
+                  <Avatar name="김민지" size={20} />
+                  김민지
+                </Inline>
+              ),
+            },
+            { label: '받는 곳', value: '서울시 성동구 왕십리로 83' },
+            { label: '결제 수단', value: '카드 · 일시불' },
+            { label: '합계', value: '205,000원' },
+          ]}
+        />
+        <Stack gap={2}>
+          <Text variant="label-md">주문 상품</Text>
+          <List aria-label="주문 상품">
+            {ITEMS.map((it) => (
+              <ListItem
+                key={it.id}
+                title={it.name}
+                description={it.option}
+                trailing={
+                  <Text variant="label-md" numeric>
+                    {it.price}
+                  </Text>
+                }
+              />
+            ))}
+          </List>
+        </Stack>
+      </Stack>
+    </Drawer>
+  )
+}
+```
+
+### 방향
+
+side = 'left' · 'right' · 'top' · 'bottom'. 닫힐 때는 들어온 방향으로 다시 나가요.
+
+```tsx
+import type { ReactNode } from 'react'
+import { ArrowDown, ArrowLeft, ArrowRight, ArrowUp } from 'lucide-react'
+import { Button, Inline, Text, Drawer, type DrawerSide } from '@iamfiro/design'
+
+const SIDES: Array<{ side: DrawerSide; label: string; icon: ReactNode }> = [
+  { side: 'left', label: '왼쪽', icon: <ArrowRight /> },
+  { side: 'right', label: '오른쪽', icon: <ArrowLeft /> },
+  { side: 'top', label: '위', icon: <ArrowDown /> },
+  { side: 'bottom', label: '아래', icon: <ArrowUp /> },
+]
+
+export default function Example() {
+  return (
+    <Inline gap={2}>
+      {SIDES.map(({ side, label, icon }) => (
+        <Drawer
+          key={side}
+          side={side}
+          size="sm"
+          trigger={<Button icon={icon}>{label}</Button>}
+          title={`${label}에서 열리는 서랍`}
+          description="들어온 방향으로 다시 미끄러져 나가요."
+        >
+          <Text variant="body-md" tone="secondary">
+            Esc, 바깥 클릭, 오른쪽 위 ×로 닫을 수 있어요. 닫히면 포커스가 열었던 버튼으로 돌아가요.
+          </Text>
+        </Drawer>
+      ))}
+    </Inline>
+  )
+}
+```
+
+### 폼 · 저장 중 잠금
+
+저장하는 동안 dismissible을 끄면 Esc·바깥 클릭·×·끌어 닫기가 모두 막혀요. initialFocus로 첫 입력칸에 바로 포커스가 가요.
+
+```tsx
+import { useRef, useState } from 'react'
+import { SlidersHorizontal } from 'lucide-react'
+import { Button, Checkbox, Field, Input, Stack, Switch, Text, Drawer, toast } from '@iamfiro/design'
+
+const STATUSES = ['진행 중', '검토 대기', '완료', '보류']
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+export default function Example() {
+  const [open, setOpen] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [keyword, setKeyword] = useState('')
+  const [statuses, setStatuses] = useState<string[]>(['진행 중', '검토 대기'])
+  const [mine, setMine] = useState(true)
+  const keywordRef = useRef<HTMLInputElement>(null)
+
+  const toggle = (s: string) => setStatuses((prev) => (prev.includes(s) ? prev.filter((x) => x !== s) : [...prev, s]))
+
+  const apply = async () => {
+    setSaving(true)
+    await wait(1200)
+    setSaving(false)
+    setOpen(false)
+    toast.success('필터를 저장했어요', { description: `상태 ${statuses.length}개${mine ? ' · 내 작업만' : ''}` })
+  }
+
+  return (
+    <Drawer
+      open={open}
+      onOpenChange={setOpen}
+      trigger={<Button icon={<SlidersHorizontal />}>필터</Button>}
+      title="작업 필터"
+      description="저장한 필터는 다음에 열 때도 그대로 적용돼요."
+      initialFocus={keywordRef}
+      dismissible={!saving}
+      footer={
+        <>
+          <Button disabled={saving} onClick={() => setOpen(false)}>
+            취소
+          </Button>
+          <Button variant="primary" loading={saving} onClick={apply}>
+            필터 저장
+          </Button>
+        </>
+      }
+    >
+      <Stack gap={6}>
+        <Field label="검색어" htmlFor="filter-keyword">
+          <Input
+            ref={keywordRef}
+            id="filter-keyword"
+            placeholder="제목이나 담당자"
+            value={keyword}
+            onChange={(e) => setKeyword(e.target.value)}
+            disabled={saving}
+          />
+        </Field>
+        <Stack gap={3}>
+          <Text variant="label-md">상태</Text>
+          {STATUSES.map((s) => (
+            <Checkbox key={s} label={s} checked={statuses.includes(s)} onChange={() => toggle(s)} disabled={saving} />
+          ))}
+        </Stack>
+        <Switch label="내가 맡은 작업만" checked={mine} onChange={(e) => setMine(e.target.checked)} disabled={saving} />
+      </Stack>
+    </Drawer>
+  )
+}
+```
+
+### 바텀시트
+
+Sheet는 손잡이가 달린 아래쪽 서랍이에요. 손잡이나 제목줄을 아래로 끌어 높이의 35%를 넘기거나 빠르게 튕기면 닫히고, 아니면 제자리로 돌아와요. 위로 끌면 고무줄처럼 버티고, 끄는 도중 Esc를 누르면 원래 자리로 취소돼요.
+
+```tsx
+import { useState } from 'react'
+import { Copy, Link2, Mail, MessageCircle, Share2 } from 'lucide-react'
+import { Button, IconTile, List, ListItem, Sheet, toast } from '@iamfiro/design'
+
+const TARGETS = [
+  { id: 'link', label: '링크 복사', description: '보기 권한이 있는 사람만 열 수 있어요', icon: <Link2 /> },
+  { id: 'mail', label: '메일로 보내기', description: '받는 사람에게 초대 메일을 보내요', icon: <Mail /> },
+  { id: 'chat', label: '팀 채팅에 공유', description: '#디자인-시스템 채널', icon: <MessageCircle /> },
+  { id: 'copy', label: '사본 만들기', description: '내 문서함에 복사본을 만들어요', icon: <Copy /> },
+]
+
+export default function Example() {
+  const [open, setOpen] = useState(false)
+  return (
+    <Sheet
+      open={open}
+      onOpenChange={setOpen}
+      size="sm"
+      trigger={<Button icon={<Share2 />}>공유</Button>}
+      title="10월 디자인 리뷰"
+      description="손잡이나 제목줄을 아래로 끌어 닫을 수 있어요."
+    >
+      <List aria-label="공유 방법">
+        {TARGETS.map((t) => (
+          <ListItem
+            key={t.id}
+            leading={<IconTile>{t.icon}</IconTile>}
+            title={t.label}
+            description={t.description}
+            onClick={() => {
+              setOpen(false)
+              toast.success(`${t.label}을(를) 마쳤어요`)
+            }}
+          />
+        ))}
+      </List>
+    </Sheet>
+  )
+}
+```
+
+### 멈춤 지점
+
+snapPoints(전체 높이에 대한 비율)를 주면 놓을 때 가장 가까운 지점에 멈춰요. 빠르게 튕기면 그 방향으로 넘어가요. 손잡이는 버튼이 되어 누르거나 Enter로 지점을 차례로 옮겨요.
+
+```tsx
+import { useState } from 'react'
+import { MapPin } from 'lucide-react'
+import { Badge, Button, IconTile, Text, List, ListItem, Sheet } from '@iamfiro/design'
+
+const PLACES = [
+  { id: 'p1', name: '성수 카페 온더', distance: '120m', open: true },
+  { id: 'p2', name: '서울숲 북카페', distance: '340m', open: true },
+  { id: 'p3', name: '뚝섬 브루어리', distance: '510m', open: false },
+  { id: 'p4', name: '왕십리 베이커리', distance: '780m', open: true },
+  { id: 'p5', name: '응봉 라운지', distance: '1.1km', open: true },
+  { id: 'p6', name: '옥수 티하우스', distance: '1.4km', open: false },
+  { id: 'p7', name: '금호 로스터스', distance: '1.6km', open: true },
+  { id: 'p8', name: '행당 브런치', distance: '1.9km', open: true },
+]
+
+export default function Example() {
+  const [snap, setSnap] = useState(0.45)
+  return (
+    <Sheet
+      trigger={<Button icon={<MapPin />}>근처 장소</Button>}
+      title="근처 장소 8곳"
+      description={snap < 1 ? '위로 끌거나 손잡이를 누르면 펼쳐져요.' : '아래로 끌면 반만 보이고, 더 끌면 닫혀요.'}
+      size="lg"
+      snapPoints={[0.45, 1]}
+      snap={snap}
+      onSnapChange={setSnap}
+      onOpenChange={(open) => open && setSnap(0.45)}
+    >
+      <List aria-label="근처 장소">
+        {PLACES.map((p) => (
+          <ListItem
+            key={p.id}
+            leading={<IconTile>{p.name.slice(0, 1)}</IconTile>}
+            title={p.name}
+            meta={
+              <Text variant="caption" tone="secondary" numeric>
+                {p.distance}
+              </Text>
+            }
+            trailing={
+              p.open ? (
+                <Badge tone="success" dot size="sm">
+                  영업 중
+                </Badge>
+              ) : (
+                <Badge size="sm">준비 중</Badge>
+              )
+            }
+          />
+        ))}
+      </List>
+    </Sheet>
+  )
+}
+```
+
+### 비모달
+
+modal={false}면 배경이 어두워지지 않고 뒤 페이지를 그대로 쓸 수 있어요(검사 패널). 열릴 때 포커스가 들어오고, Esc로 닫혀요.
+
+```tsx
+import { useState } from 'react'
+import { PanelRightOpen } from 'lucide-react'
+import { Avatar, Button, Inline, Stack, Text, DescriptionList, Drawer, List, ListItem } from '@iamfiro/design'
+
+const PEOPLE = [
+  { id: 'u1', name: '김민지', role: '디자인 리드', team: '디자인 시스템', joined: '2021년 3월' },
+  { id: 'u2', name: '이도현', role: '프론트엔드 개발', team: '플랫폼', joined: '2022년 8월' },
+  { id: 'u3', name: '박서준', role: '프로덕트 매니저', team: '성장', joined: '2023년 1월' },
+]
+
+export default function Example() {
+  const [open, setOpen] = useState(false)
+  // Keep the last person while the drawer slides out.
+  const [selected, setSelected] = useState(PEOPLE[0].id)
+  const person = PEOPLE.find((p) => p.id === selected) ?? PEOPLE[0]
+
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 420 }}>
+      <Text variant="body-sm" tone="secondary">
+        서랍이 열린 채로 다른 사람을 눌러 보세요. 뒤 페이지가 계속 동작해요.
+      </Text>
+      <List aria-label="멤버">
+        {PEOPLE.map((p) => (
+          <ListItem
+            key={p.id}
+            leading={<Avatar name={p.name} size={32} tooltip={false} />}
+            title={p.name}
+            description={p.role}
+            selected={open && p.id === selected}
+            onClick={() => {
+              setSelected(p.id)
+              setOpen(true)
+            }}
+            trailing={<PanelRightOpen size={16} aria-hidden />}
+          />
+        ))}
+      </List>
+      <Drawer
+        open={open}
+        onOpenChange={setOpen}
+        modal={false}
+        inset
+        size="sm"
+        title={person.name}
+        description={person.role}
+        footer={
+          <Button variant="primary" onClick={() => setOpen(false)}>
+            완료
+          </Button>
+        }
+      >
+        <Stack gap={5}>
+          <Inline gap={3} wrap={false}>
+            <Avatar name={person.name} size={48} online tooltip={false} />
+            <Text variant="body-sm" tone="secondary">
+              {person.team} 팀에서 {person.joined}부터 함께하고 있어요.
+            </Text>
+          </Inline>
+          <DescriptionList
+            size="sm"
+            columns={1}
+            layout="inline"
+            aria-label="멤버 정보"
+            items={[
+              { label: '팀', value: person.team },
+              { label: '역할', value: person.role },
+              { label: '입사', value: person.joined },
+            ]}
+          />
+        </Stack>
+      </Drawer>
+    </Stack>
+  )
+}
+```
+
+### 크기 · 띄우기
+
+좌우 서랍은 폭 360 · 440 · 640px · 전체, 위아래는 최대 높이 50 · 75 · 92% · 전체. inset은 가장자리에서 8px 떠 있어요.
+
+```tsx
+import { Button, Inline, Text, Drawer, type DrawerSize } from '@iamfiro/design'
+
+const SIZES: Array<{ size: DrawerSize; label: string }> = [
+  { size: 'sm', label: 'sm · 360px' },
+  { size: 'md', label: 'md · 440px' },
+  { size: 'lg', label: 'lg · 640px' },
+  { size: 'full', label: 'full · 전체 화면' },
+]
+
+export default function Example() {
+  return (
+    <Inline gap={2}>
+      {SIZES.map(({ size, label }) => (
+        <Drawer
+          key={size}
+          size={size}
+          trigger={<Button>{label}</Button>}
+          title={`크기 ${size}`}
+          description="휴대폰에서는 화면 폭에서 40px을 뺀 만큼까지만 넓어져요."
+        >
+          <Text variant="body-md" tone="secondary">
+            좌우 서랍은 폭이, 위아래 서랍은 최대 높이가 바뀌어요. 내용이 길면 본문만 스크롤돼요.
+          </Text>
+        </Drawer>
+      ))}
+      <Drawer
+        size="sm"
+        inset
+        trigger={<Button variant="ghost">띄우기(inset)</Button>}
+        title="띄운 서랍"
+        description="가장자리에서 8px 떨어져 모든 모서리가 둥글어요."
+      >
+        <Text variant="body-md" tone="secondary">
+          화면 가장자리에 붙지 않고 떠 있는 패널이 어울리는 화면에서 써요.
+        </Text>
+      </Drawer>
+    </Inline>
+  )
+}
+```