@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/dialog/AGENTS.md

@@ -0,0 +1,391 @@
+# Dialog
+
+> 메뉴 & 오버레이 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+페이지 위에 뜨는 모달. 열려 있는 동안 포커스는 안에 갇히고 뒤 페이지는 스크롤되지 않아요. Esc나 바깥 클릭으로 닫히고, 닫히면 포커스가 열었던 버튼으로 돌아가요. 부드럽게 커지며 열리고 반대로 줄어들며 닫히며, 휴대폰에서는 아래에서 올라오는 바텀시트가 돼요. 되돌릴 수 없는 작업의 확인은 AlertDialog를 쓰세요.
+
+```tsx
+import { Dialog } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 모달(`Dialog`): 포커스 가두기(`useFocusTrap`), 배경 스크롤 잠금(`useScrollLock`), Esc·바깥 클릭으로 닫기, 닫으면 트리거로 포커스 복귀. 저장 중엔 `dismissible={false}`. 휴대폰에선 바텀시트.
+
+## API
+
+### Dialog
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` (필수) | `ReactNode` |  | 제목. 대화상자의 접근성 이름(aria-labelledby)이 돼요. |
+| `description` | `ReactNode` |  | 제목 아래 설명(aria-describedby). |
+| `children` | `ReactNode` |  | 본문. 길면 이 부분만 스크롤돼요. |
+| `footer` | `ReactNode` |  | 아래 버튼 줄(오른쪽 정렬). 동작을 이름으로 쓰세요 — "저장", "보내기". |
+| `trigger` | `ReactElement` |  | 누르면 여는 버튼. aria-haspopup · aria-expanded가 붙고, 원래 onClick도 실행돼요. preventDefault하면 열리지 않아요. |
+| `open / onOpenChange` | `boolean / (open) => void` |  | 열림 상태를 밖에서 제어할 때. |
+| `defaultOpen` | `boolean` | `false` | 처음 열림 상태(비제어). |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 패널 폭 400 / 520 / 720px. 휴대폰에선 바텀시트. |
+| `dismissible` | `boolean` | `true` | Esc·바깥 클릭·×로 닫기. 저장 중엔 false로. |
+| `showClose` | `boolean` | `true` | 오른쪽 위 × 버튼. dismissible이 false면 숨겨져요. |
+| `initialFocus` | `RefObject<HTMLElement>` |  | 열릴 때 포커스할 요소. 생략하면 첫 번째 포커스 가능한 요소(× 버튼)예요. |
+| `bare` | `boolean` | `false` | children을 제목줄·본문·버튼 줄 없이 패널에 바로 넣어요. 여백·×도 없고 footer는 무시돼요. 패널은 모서리를 자르는 세로 flex라 자식이 min-height: 0으로 스크롤을 맡을 수 있어요. title은 여전히 필수이고 화면에서만 숨겨져요. |
+| `hideTitle` | `boolean` | `false` | 기본 레이아웃은 그대로 두고 제목·설명만 화면에서 숨겨요(스크린 리더는 읽어요). |
+| `placement` | `'center' \| 'top'` | `'center'` | center는 가운데(휴대폰에선 바텀시트). top은 위에서 12vh 아래에 고정돼 내용 높이가 바뀌어도 움직이지 않고, 휴대폰에서도 좌우 12px 여백의 떠 있는 패널로 남아요. |
+| `className` | `string` |  | 패널에 붙는 클래스. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+trigger에 버튼을 넘기면 누를 때 열려요(버튼의 onClick도 그대로 실행돼요). 오른쪽 위 ×, Esc, 바깥 클릭으로 닫혀요.
+
+```tsx
+import { Keyboard } from 'lucide-react'
+import { Button, Inline, Kbd, Stack, Text, Dialog } from '@iamfiro/design'
+
+const SHORTCUTS = [
+  { label: '빠른 검색', keys: ['mod', 'K'] },
+  { label: '새 문서 만들기', keys: ['mod', 'N'] },
+  { label: '복제', keys: ['mod', 'D'] },
+  { label: '실행 취소', keys: ['mod', 'Z'] },
+]
+
+export default function Example() {
+  return (
+    <Dialog
+      trigger={<Button icon={<Keyboard />}>단축키 보기</Button>}
+      title="키보드 단축키"
+      description="자주 쓰는 동작을 키보드로 바로 실행할 수 있어요."
+    >
+      <Stack gap={3}>
+        {SHORTCUTS.map((s) => (
+          <Inline key={s.label} justify="between" wrap={false}>
+            <Text variant="body-md">{s.label}</Text>
+            <Kbd keys={s.keys} />
+          </Inline>
+        ))}
+      </Stack>
+    </Dialog>
+  )
+}
+```
+
+### 폼
+
+저장하는 동안 dismissible을 끄면 Esc·바깥 클릭·×가 막혀 작업이 중간에 끊기지 않아요. initialFocus로 첫 입력칸에 바로 포커스를 줘요. 모달 안의 Select 팝오버는 모달보다 위에 뜨고, Select의 Esc는 팝오버만 닫아요.
+
+```tsx
+import { useRef, useState } from 'react'
+import { UserPlus } from 'lucide-react'
+import { Button, Field, Input, Stack, Dialog, Select, toast, type ListOption } from '@iamfiro/design'
+
+const ROLES: ListOption[] = [
+  { value: 'viewer', label: '보기 전용', description: '문서를 읽고 댓글만 달 수 있어요' },
+  { value: 'editor', label: '편집자', description: '문서를 만들고 고칠 수 있어요' },
+  { value: 'admin', label: '관리자', description: '멤버와 결제까지 관리해요' },
+]
+
+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 [email, setEmail] = useState('')
+  const [role, setRole] = useState<string | null>('editor')
+  const emailRef = useRef<HTMLInputElement>(null)
+
+  const openDialog = () => {
+    setEmail('')
+    setRole('editor')
+    setOpen(true)
+  }
+
+  const save = async () => {
+    setSaving(true)
+    await wait(1200)
+    setSaving(false)
+    setOpen(false)
+    toast.success('초대를 보냈어요', { description: `${email}에게 메일이 도착할 거예요.` })
+  }
+
+  return (
+    <>
+      <Button variant="primary" icon={<UserPlus />} onClick={openDialog}>
+        멤버 초대
+      </Button>
+      <Dialog
+        open={open}
+        onOpenChange={setOpen}
+        title="멤버 초대"
+        description="초대받은 사람은 메일의 링크로 워크스페이스에 들어와요."
+        initialFocus={emailRef}
+        dismissible={!saving}
+        footer={
+          <>
+            <Button disabled={saving} onClick={() => setOpen(false)}>
+              취소
+            </Button>
+            <Button variant="primary" loading={saving} disabled={!email.includes('@')} onClick={save}>
+              저장
+            </Button>
+          </>
+        }
+      >
+        <Stack gap={5}>
+          <Field label="이메일" htmlFor="invite-email">
+            <Input
+              ref={emailRef}
+              id="invite-email"
+              type="email"
+              placeholder="name@company.com"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              disabled={saving}
+            />
+          </Field>
+          <Field label="권한" htmlFor="invite-role">
+            <Select id="invite-role" options={ROLES} value={role} onValueChange={setRole} disabled={saving} />
+          </Field>
+        </Stack>
+      </Dialog>
+    </>
+  )
+}
+```
+
+### 제어
+
+open과 onOpenChange로 바깥 상태에서 열고 닫아요. trigger 없이 어디서든 열 수 있고, Esc·바깥 클릭으로 닫힐 때도 onOpenChange(false)가 불려요.
+
+```tsx
+import { useState } from 'react'
+import { Sparkles } from 'lucide-react'
+import { Button, Stack, Text, Dialog, toast } from '@iamfiro/design'
+
+export default function Example() {
+  const [open, setOpen] = useState(false)
+
+  const update = () => {
+    setOpen(false)
+    toast.success('최신 버전으로 업데이트했어요')
+  }
+
+  return (
+    <Stack gap={3} align="start">
+      <Button icon={<Sparkles />} onClick={() => setOpen(true)}>
+        새 버전 안내 열기
+      </Button>
+      <Text variant="body-sm" tone="tertiary">
+        지금 상태: {open ? '열림' : '닫힘'}
+      </Text>
+      <Dialog
+        open={open}
+        onOpenChange={setOpen}
+        title="새 버전이 준비됐어요"
+        description="2.4 버전에서는 댓글 알림과 검색 속도가 좋아졌어요. 지금 업데이트하면 열린 문서는 그대로 유지돼요."
+        footer={
+          <>
+            <Button onClick={() => setOpen(false)}>나중에</Button>
+            <Button variant="primary" onClick={update}>
+              지금 업데이트
+            </Button>
+          </>
+        }
+      />
+    </Stack>
+  )
+}
+```
+
+### 크기
+
+sm · md · lg = 400 · 520 · 720px. 휴대폰에서는 모두 바텀시트로 바뀌어요.
+
+```tsx
+import { Button, Inline, Text, Dialog } from '@iamfiro/design'
+
+const SIZES = [
+  { size: 'sm', label: '작게 (400px)', text: '짧은 안내나 한두 개의 입력에 맞아요.' },
+  { size: 'md', label: '보통 (520px)', text: '대부분의 폼과 설정에 쓰는 기본 크기예요.' },
+  { size: 'lg', label: '크게 (720px)', text: '표, 미리보기, 두 단 레이아웃처럼 내용이 넓을 때 써요.' },
+] as const
+
+export default function Example() {
+  return (
+    <Inline gap={2}>
+      {SIZES.map((s) => (
+        <Dialog key={s.size} size={s.size} trigger={<Button>{s.label}</Button>} title={s.label}>
+          <Text variant="body-md" tone="secondary">
+            {s.text} 휴대폰에서는 크기와 관계없이 화면 아래에서 올라오는 시트로 바뀌어요.
+          </Text>
+        </Dialog>
+      ))}
+    </Inline>
+  )
+}
+```
+
+### 긴 내용
+
+내용이 화면보다 길면 본문만 스크롤되고 제목과 버튼 줄은 제자리에 남아요. 바깥에서 시작해 바깥에서 끝난 클릭만 닫기로 봐서, 글자를 드래그하다 밖에서 놓아도 닫히지 않아요.
+
+```tsx
+import { useState } from 'react'
+import { FileText } from 'lucide-react'
+import { Button, Prose, Dialog, toast } from '@iamfiro/design'
+
+const SECTIONS = [
+  { title: '제1조 목적', body: '이 약관은 회사가 제공하는 Lumen 서비스의 이용 조건과 절차, 회사와 이용자의 권리·의무 및 책임 사항을 정하는 것을 목적으로 해요.' },
+  { title: '제2조 정의', body: '"이용자"란 이 약관에 따라 서비스를 이용하는 회원을 말해요. "워크스페이스"란 이용자가 문서와 멤버를 관리하는 공간을 말해요.' },
+  { title: '제3조 약관의 효력과 변경', body: '회사는 관련 법령을 어기지 않는 범위에서 약관을 바꿀 수 있어요. 바뀐 약관은 시행일 7일 전부터 서비스 안에 공지해요.' },
+  { title: '제4조 계정 관리', body: '이용자는 자신의 계정과 비밀번호를 안전하게 관리해야 해요. 계정이 도용된 것을 알게 되면 바로 회사에 알려 주세요.' },
+  { title: '제5조 서비스 제공', body: '회사는 연중무휴, 하루 24시간 서비스를 제공하는 것을 원칙으로 해요. 다만 정기 점검이나 장애 대응을 위해 잠시 멈출 수 있어요.' },
+  { title: '제6조 유료 플랜', body: '유료 플랜은 매월 같은 날짜에 자동으로 결제돼요. 해지하면 남은 기간이 끝날 때까지 계속 이용할 수 있어요.' },
+  { title: '제7조 이용자의 콘텐츠', body: '이용자가 올린 문서와 파일의 권리는 이용자에게 있어요. 회사는 서비스를 제공하는 데 필요한 범위에서만 콘텐츠를 처리해요.' },
+  { title: '제8조 이용 제한', body: '다른 이용자의 서비스 이용을 방해하거나 법령을 어기는 경우, 회사는 사전 안내 후 이용을 제한할 수 있어요.' },
+  { title: '제9조 책임의 한계', body: '천재지변이나 이용자의 귀책 사유로 생긴 손해에 대해서는 회사가 책임지지 않아요.' },
+]
+
+export default function Example() {
+  const [open, setOpen] = useState(false)
+
+  const agree = () => {
+    setOpen(false)
+    toast.success('약관에 동의했어요')
+  }
+
+  return (
+    <>
+      <Button icon={<FileText />} onClick={() => setOpen(true)}>
+        이용약관 보기
+      </Button>
+      <Dialog
+        open={open}
+        onOpenChange={setOpen}
+        title="서비스 이용약관"
+        description="2026년 11월 1일부터 적용돼요."
+        footer={
+          <>
+            <Button onClick={() => setOpen(false)}>닫기</Button>
+            <Button variant="primary" onClick={agree}>
+              동의하고 계속
+            </Button>
+          </>
+        }
+      >
+        <Prose size="sm">
+          {SECTIONS.map((s) => (
+            <section key={s.title}>
+              <h3>{s.title}</h3>
+              <p>{s.body}</p>
+            </section>
+          ))}
+        </Prose>
+      </Dialog>
+    </>
+  )
+}
+```
+
+### 빈 패널 · 위쪽 배치
+
+bare면 제목줄·여백·× 없이 children이 패널에 바로 들어가요(⌘K 명령 팔레트처럼). 제목은 화면에서만 숨겨져 대화상자 이름으로 계속 읽혀요. placement="top"은 화면 위에서 12vh 아래에 고정돼 결과가 걸러지며 높이가 바뀌어도 검색칸이 움직이지 않고, 휴대폰에서도 키보드를 피해 위에 떠 있어요. initialFocus로 검색칸에 바로 포커스가 가요.
+
+```tsx
+import { useRef, useState, type KeyboardEvent } from 'react'
+import { FilePlus, FileText, Search, Settings, UserPlus } from 'lucide-react'
+import { Box, Button, Kbd, SearchInput, Dialog, EmptyState, List, ListItem, toast } from '@iamfiro/design'
+
+const COMMANDS = [
+  { id: 'new', label: '새 문서 만들기', icon: <FilePlus />, keys: ['mod', 'N'] },
+  { id: 'invite', label: '멤버 초대', icon: <UserPlus /> },
+  { id: 'roadmap', label: '2분기 로드맵', description: '김민지 · 10월 25일 수정', icon: <FileText /> },
+  { id: 'notes', label: '주간 회의록', description: '이도현 · 2분 전 수정', icon: <FileText /> },
+  { id: 'settings', label: '설정 열기', icon: <Settings />, keys: ['mod', ','] },
+]
+
+export default function Example() {
+  const [open, setOpen] = useState(false)
+  const [query, setQuery] = useState('')
+  const [active, setActive] = useState(0)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const results = COMMANDS.filter((c) => c.label.includes(query.trim()))
+
+  const openPalette = () => {
+    setQuery('')
+    setActive(0)
+    setOpen(true)
+  }
+
+  const run = (label: string) => {
+    setOpen(false)
+    toast.success(`'${label}' 실행`)
+  }
+
+  const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.nativeEvent.isComposing || !results.length) return
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+      e.preventDefault()
+      const step = e.key === 'ArrowDown' ? 1 : -1
+      setActive((i) => (i + step + results.length) % results.length)
+    } else if (e.key === 'Enter') {
+      e.preventDefault()
+      run(results[Math.min(active, results.length - 1)].label)
+    }
+  }
+
+  return (
+    <>
+      <Button icon={<Search />} onClick={openPalette}>
+        명령 검색
+      </Button>
+      <Dialog
+        bare
+        placement="top"
+        size="lg"
+        open={open}
+        onOpenChange={setOpen}
+        title="명령 검색"
+        description="명령이나 문서 이름을 입력하고 화살표 키로 고른 뒤 Enter로 실행해요."
+        initialFocus={inputRef}
+      >
+        <Box padding={3}>
+          <SearchInput
+            ref={inputRef}
+            placeholder="명령이나 문서 검색"
+            value={query}
+            onChange={(e) => {
+              setQuery(e.target.value)
+              setActive(0)
+            }}
+            onKeyDown={onKeyDown}
+          />
+        </Box>
+        <Box paddingX={2} paddingY={2}>
+          {results.length ? (
+            <List aria-label="검색 결과">
+              {results.map((c, i) => (
+                <ListItem
+                  key={c.id}
+                  leading={c.icon}
+                  title={c.label}
+                  description={c.description}
+                  trailing={c.keys && <Kbd keys={c.keys} size="sm" />}
+                  selected={i === active}
+                  onClick={() => run(c.label)}
+                />
+              ))}
+            </List>
+          ) : (
+            <EmptyState size="sm" icon={<Search />} title="결과가 없어요" description={`'${query}'와 맞는 명령이나 문서가 없어요.`} />
+          )}
+        </Box>
+      </Dialog>
+    </>
+  )
+}
+```