@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/menubar/AGENTS.md

@@ -0,0 +1,276 @@
+# Menubar
+
+> 메뉴 & 오버레이 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+데스크톱 앱처럼 파일 · 편집 · 보기 메뉴를 가로로 늘어놓은 막대. 누르는 순간 열리고(누른 채 항목으로 끌어 놓으면 실행), 하나가 열려 있는 동안은 옆 메뉴 이름에 마우스를 올리기만 해도 즉시 바뀌어요. 열린 메뉴 이름 뒤의 회색 채움은 메뉴를 바꿀 때 미끄러져 옮겨 가요. 키보드는 ←/→로 메뉴 사이를 이동(열린 메뉴 안에서도, 하위 메뉴가 아니면)하고 ↓ · Enter · Space로 열어요. 막대 전체가 Tab 한 번(roving tabindex). 항목 · 단축키 · 체크/라디오 · 하위 메뉴는 DropdownMenu와 같은 조각을 써요. 막대에는 테두리가 없어요.
+
+```tsx
+import { Menubar, MenubarMenu, MenubarItem, MenubarCheckboxItem, MenubarRadioGroup, MenubarRadioItem, MenubarLabel, MenubarSeparator, MenubarSub } from '@iamfiro/design'
+```
+
+## API
+
+### Menubar
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | MenubarMenu들(순서대로). |
+| `value / onValueChange` | `string \| null / (value) => void` |  | 열린 메뉴의 value(null = 모두 닫힘). 밖에서 제어할 때. |
+| `defaultValue` | `string \| null` | `null` | 처음 열린 메뉴(비제어). |
+| `aria-label` | `string` |  | 막대(role="menubar")의 접근성 이름. |
+| `className` | `string` |  | 막대에 붙일 클래스. |
+
+### MenubarMenu
+
+막대의 메뉴 하나(이름 버튼 + 패널). 항목은 DropdownMenu와 같아요: MenubarItem(= DropdownMenuItem) · MenubarCheckboxItem · MenubarRadioGroup · MenubarRadioItem · MenubarLabel · MenubarSeparator · MenubarSub.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` (필수) | `ReactNode` |  | 막대에 보이는 메뉴 이름(예: 파일). |
+| `children` (필수) | `ReactNode` |  | 항목, 라벨, 구분선, 하위 메뉴. |
+| `value` | `string` |  | Menubar value에서 이 메뉴를 가리키는 값. 없으면 내부 id. |
+| `disabled` | `boolean` |  | 비활성. 열리지 않고 키보드 이동에서 건너뛰어요. |
+| `minWidth` | `number` | `220` | 패널 최소 폭(px). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 문서 편집기
+
+메뉴 하나를 연 채로 옆 이름 위로 마우스를 옮겨 보세요. 메뉴가 바뀔 때는 패널이 새로 튀어나오지 않고 제자리에 바로 나타나며, 회색 채움만 미끄러져요. 막대를 완전히 닫을 때는 패널이 퇴장 애니메이션으로 사라져요. 하위 메뉴(최근 파일)는 DropdownMenu와 같이 머물면 열리고 →로도 열려요.
+
+```tsx
+import { useState } from 'react'
+import {
+  ClipboardPaste,
+  Copy,
+  FilePlus,
+  FolderOpen,
+  History,
+  LogOut,
+  Printer,
+  Redo2,
+  Save,
+  Scissors,
+  Search,
+  Trash2,
+  Undo2,
+} from 'lucide-react'
+import { Stack, Text, Menubar, MenubarItem, MenubarMenu, MenubarSeparator, MenubarSub, toast } from '@iamfiro/design'
+
+const RECENT = ['3분기 이사회 보고서.docx', '출시 일정.xlsx', '브랜드 가이드.fig']
+
+export default function Example() {
+  const [last, setLast] = useState('없음')
+  const run = (label: string) => () => {
+    setLast(label)
+    toast(`‘${label}’ 실행`)
+  }
+
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 560 }}>
+      <Menubar aria-label="문서 편집기">
+        <MenubarMenu label="파일">
+          <MenubarItem icon={<FilePlus />} shortcut={['mod', 'N']} onSelect={run('새 문서')}>
+            새 문서
+          </MenubarItem>
+          <MenubarItem icon={<FolderOpen />} shortcut={['mod', 'O']} onSelect={run('열기')}>
+            열기…
+          </MenubarItem>
+          <MenubarSub label="최근 파일" icon={<History />}>
+            {RECENT.map((name) => (
+              <MenubarItem key={name} onSelect={run(name)}>
+                {name}
+              </MenubarItem>
+            ))}
+          </MenubarSub>
+          <MenubarSeparator />
+          <MenubarItem icon={<Save />} shortcut={['mod', 'S']} onSelect={run('저장')}>
+            저장
+          </MenubarItem>
+          <MenubarItem icon={<Printer />} shortcut={['mod', 'P']} onSelect={run('인쇄')}>
+            인쇄…
+          </MenubarItem>
+          <MenubarSeparator />
+          <MenubarItem icon={<Trash2 />} danger onSelect={run('휴지통으로 이동')}>
+            휴지통으로 이동
+          </MenubarItem>
+        </MenubarMenu>
+        <MenubarMenu label="편집">
+          <MenubarItem icon={<Undo2 />} shortcut={['mod', 'Z']} onSelect={run('실행 취소')}>
+            실행 취소
+          </MenubarItem>
+          <MenubarItem icon={<Redo2 />} shortcut={['mod', 'shift', 'Z']} disabled>
+            다시 실행
+          </MenubarItem>
+          <MenubarSeparator />
+          <MenubarItem icon={<Scissors />} shortcut={['mod', 'X']} onSelect={run('잘라내기')}>
+            잘라내기
+          </MenubarItem>
+          <MenubarItem icon={<Copy />} shortcut={['mod', 'C']} onSelect={run('복사')}>
+            복사
+          </MenubarItem>
+          <MenubarItem icon={<ClipboardPaste />} shortcut={['mod', 'V']} onSelect={run('붙여넣기')}>
+            붙여넣기
+          </MenubarItem>
+          <MenubarSeparator />
+          <MenubarItem icon={<Search />} shortcut={['mod', 'F']} onSelect={run('찾기')}>
+            찾기…
+          </MenubarItem>
+        </MenubarMenu>
+        <MenubarMenu label="삽입">
+          <MenubarItem onSelect={run('표')}>표</MenubarItem>
+          <MenubarItem onSelect={run('이미지')}>이미지…</MenubarItem>
+          <MenubarItem onSelect={run('링크')} shortcut={['mod', 'K']}>
+            링크
+          </MenubarItem>
+          <MenubarSub label="구분 요소">
+            <MenubarItem onSelect={run('가로줄')}>가로줄</MenubarItem>
+            <MenubarItem onSelect={run('페이지 나누기')} shortcut={['mod', 'enter']}>
+              페이지 나누기
+            </MenubarItem>
+          </MenubarSub>
+        </MenubarMenu>
+        <MenubarMenu label="계정">
+          <MenubarItem description="minji@lumen.kr" onSelect={run('프로필')}>
+            김민지
+          </MenubarItem>
+          <MenubarSeparator />
+          <MenubarItem icon={<LogOut />} onSelect={run('로그아웃')}>
+            로그아웃
+          </MenubarItem>
+        </MenubarMenu>
+      </Menubar>
+      <Text variant="caption" tone="tertiary">
+        하나를 연 채로 옆 메뉴에 마우스를 올리면 바로 바뀌어요. 마지막 동작: {last}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 체크 · 라디오
+
+체크 항목과 라디오 그룹은 고른 뒤에도 메뉴가 열려 있어 여러 설정을 이어서 바꿀 수 있어요. MenubarLabel로 묶음 제목을 붙여요.
+
+```tsx
+import { useState } from 'react'
+import { PanelLeft, Ruler } from 'lucide-react'
+import { Stack, Text, Menubar, MenubarCheckboxItem, MenubarItem, MenubarLabel, MenubarMenu, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, toast } from '@iamfiro/design'
+
+export default function Example() {
+  const [sidebar, setSidebar] = useState(true)
+  const [ruler, setRuler] = useState(false)
+  const [zoom, setZoom] = useState('fit')
+  const [sort, setSort] = useState('updated')
+
+  const ZOOM: Record<string, string> = { fit: '화면에 맞추기', '100': '100%', '150': '150%' }
+  const SORT: Record<string, string> = { updated: '수정한 날짜', name: '이름', size: '크기' }
+
+  return (
+    <Stack gap={3} style={{ width: '100%', maxWidth: 520 }}>
+      <Menubar aria-label="보기 설정">
+        <MenubarMenu label="보기">
+          <MenubarCheckboxItem icon={<PanelLeft />} checked={sidebar} onCheckedChange={setSidebar} shortcut={['mod', '\\']}>
+            사이드바
+          </MenubarCheckboxItem>
+          <MenubarCheckboxItem icon={<Ruler />} checked={ruler} onCheckedChange={setRuler} shortcut={['shift', 'R']}>
+            눈금자
+          </MenubarCheckboxItem>
+          <MenubarSeparator />
+          <MenubarRadioGroup label="확대" value={zoom} onValueChange={setZoom}>
+            {Object.entries(ZOOM).map(([v, label]) => (
+              <MenubarRadioItem key={v} value={v}>
+                {label}
+              </MenubarRadioItem>
+            ))}
+          </MenubarRadioGroup>
+        </MenubarMenu>
+        <MenubarMenu label="정렬">
+          <MenubarRadioGroup label="정렬 기준" value={sort} onValueChange={setSort}>
+            {Object.entries(SORT).map(([v, label]) => (
+              <MenubarRadioItem key={v} value={v}>
+                {label}
+              </MenubarRadioItem>
+            ))}
+          </MenubarRadioGroup>
+        </MenubarMenu>
+        <MenubarMenu label="창">
+          <MenubarLabel>열린 창</MenubarLabel>
+          <MenubarItem onSelect={() => toast('‘10월 회의록’으로 전환했어요')}>10월 회의록</MenubarItem>
+          <MenubarItem onSelect={() => toast('‘디자인 리뷰’로 전환했어요')}>디자인 리뷰</MenubarItem>
+          <MenubarSeparator />
+          <MenubarItem shortcut={['mod', 'M']} onSelect={() => toast('창을 최소화했어요')}>
+            최소화
+          </MenubarItem>
+        </MenubarMenu>
+      </Menubar>
+      <Text variant="caption" tone="tertiary">
+        사이드바 {sidebar ? '켜짐' : '꺼짐'} · 눈금자 {ruler ? '켜짐' : '꺼짐'} · {ZOOM[zoom]} · {SORT[sort]} 순
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 키보드 · 제어
+
+value · onValueChange로 열린 메뉴를 밖에서 읽거나 정해요(null = 닫힘). disabled 메뉴는 ←/→ 이동에서 건너뛰어요. 열린 메뉴 안에서 ←/→를 누르면 이웃 메뉴가 열리고 첫 항목이 강조돼요. Esc는 메뉴를 닫고 그 메뉴 이름으로 포커스를 돌려줘요.
+
+```tsx
+import { useState } from 'react'
+import { Inline, Kbd, Stack, Text, DescriptionList, Menubar, MenubarItem, MenubarMenu, MenubarSeparator, toast } from '@iamfiro/design'
+
+const LABELS: Record<string, string> = { file: '파일', edit: '편집', share: '공유', help: '도움말' }
+
+export default function Example() {
+  const [open, setOpen] = useState<string | null>(null)
+
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 520 }}>
+      <Menubar aria-label="키보드 예제" value={open} onValueChange={setOpen}>
+        <MenubarMenu value="file" label="파일">
+          <MenubarItem shortcut={['mod', 'N']} onSelect={() => toast('새 문서를 만들었어요')}>
+            새 문서
+          </MenubarItem>
+          <MenubarItem shortcut={['mod', 'S']} onSelect={() => toast.success('저장했어요')}>
+            저장
+          </MenubarItem>
+        </MenubarMenu>
+        <MenubarMenu value="edit" label="편집">
+          <MenubarItem shortcut={['mod', 'Z']} onSelect={() => toast('실행을 취소했어요')}>
+            실행 취소
+          </MenubarItem>
+          <MenubarSeparator />
+          <MenubarItem shortcut={['mod', 'A']} onSelect={() => toast('모두 선택했어요')}>
+            모두 선택
+          </MenubarItem>
+        </MenubarMenu>
+        <MenubarMenu value="share" label="공유" disabled>
+          <MenubarItem>링크 복사</MenubarItem>
+        </MenubarMenu>
+        <MenubarMenu value="help" label="도움말">
+          <MenubarItem shortcut={['mod', '/']} onSelect={() => toast('단축키 목록을 열었어요')}>
+            단축키 보기
+          </MenubarItem>
+          <MenubarItem onSelect={() => toast('새 소식을 열었어요')}>새 소식</MenubarItem>
+        </MenubarMenu>
+      </Menubar>
+      <Text variant="caption" tone="tertiary">
+        열린 메뉴: {open ? LABELS[open] : '없음'} · ‘공유’는 비활성이라 건너뛰어요
+      </Text>
+      <DescriptionList
+        variant="soft"
+        layout="inline"
+        items={[
+          { label: '메뉴 사이 이동', value: <Inline gap={1}><Kbd keys={['left']} size="sm" /><Kbd keys={['right']} size="sm" /></Inline> },
+          { label: '열기 (첫 / 마지막 항목)', value: <Inline gap={1}><Kbd keys={['down']} size="sm" /><Kbd keys={['enter']} size="sm" /><Kbd keys={['up']} size="sm" /></Inline> },
+          { label: '처음 · 끝 메뉴', value: <Inline gap={1}><Kbd keys={['Home']} size="sm" /><Kbd keys={['End']} size="sm" /></Inline> },
+          { label: '닫고 메뉴 이름으로', value: <Kbd keys={['esc']} size="sm" /> },
+        ]}
+      />
+    </Stack>
+  )
+}
+```

package/agents/multi-select/AGENTS.md

@@ -0,0 +1,159 @@
+# MultiSelect
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+목록에서 여러 개를 고르는 셀렉트. 고르는 동안 목록이 열린 채로 유지되고, 고른 항목은 지울 수 있는 태그나 "n개 선택됨" 요약으로 보여줘요. 선택지 형태(ListOption)는 Select 페이지를 참고하세요.
+
+```tsx
+import { MultiSelect, type ListOption } from '@iamfiro/design'
+```
+
+## API
+
+### MultiSelect
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `options` (필수) | `ListOption<V>[]` |  | 선택지 목록. ListOption은 Select 페이지 참고. |
+| `value` | `V[]` |  | 선택된 값들(제어). 항상 options 순서로 정렬돼요. |
+| `defaultValue` | `V[]` | `[]` | 처음 선택값(비제어). |
+| `onValueChange` | `(value: V[]) => void` |  | 값이 바뀔 때. |
+| `open / onOpenChange` | `boolean / (open) => void` |  | 열림 상태를 밖에서 제어할 때. |
+| `display` | `'tags' \| 'count'` | `'tags'` | 트리거에 태그로 보여줄지, 개수 요약으로 보여줄지. |
+| `maxTags` | `number` | `2` | 보여줄 태그 수. 나머지는 +N으로 접혀요. |
+| `formatCount` | `(count: number) => ReactNode` | ``${n}개 선택됨`` | display='count'일 때 문구. |
+| `selectAll` | `boolean` |  | 목록 맨 위에 전체 선택 행 추가(Ctrl/⌘ + A). |
+| `selectAllLabel` | `ReactNode` | `'전체 선택'` | 전체 선택 행 문구. |
+| `placeholder` | `ReactNode` | `'선택하세요'` | 선택 전 문구. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 높이 36 / 44 / 52px. |
+| `invalid` | `boolean` |  | 오류 표시. |
+| `disabled` | `boolean` |  | 비활성. 태그의 × 버튼도 숨겨져요. |
+| `leading` | `ReactNode` |  | 값 앞 아이콘. |
+| `renderOption` | `(option, state) => ReactNode` |  | 목록 행을 직접 그릴 때. |
+| `name` | `string` |  | 폼 제출용. 값마다 같은 name의 hidden input이 생겨요. |
+| `maxHeight` | `number` | `300` | 팝오버 최대 높이. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+고른 항목은 태그로 쌓이고 ×로 바로 지울 수 있어요. Space/Enter로 토글, 목록이 닫혀 있을 때 Backspace는 마지막 항목을 지워요.
+
+```tsx
+import { useState } from 'react'
+import { MultiSelect, type ListOption } from '@iamfiro/design'
+
+const LANGUAGES: ListOption[] = [
+  { value: 'ko', label: '한국어' },
+  { value: 'en', label: '영어' },
+  { value: 'ja', label: '일본어' },
+  { value: 'zh', label: '중국어' },
+  { value: 'es', label: '스페인어' },
+]
+
+export default function Example() {
+  const [languages, setLanguages] = useState<string[]>(['ko', 'en'])
+  return (
+    <div style={{ width: 320 }}>
+      <MultiSelect options={LANGUAGES} value={languages} onValueChange={setLanguages} placeholder="언어 선택" aria-label="지원 언어" />
+    </div>
+  )
+}
+```
+
+### 전체 선택 · 그룹
+
+selectAll은 목록 맨 위에 "전체 선택" 행을 붙여요. 열린 상태에서 Ctrl/⌘ + A로도 돼요. 비활성 항목은 전체 선택에서 빠져요.
+
+```tsx
+import { useState } from 'react'
+import { Field, MultiSelect, type ListOption } from '@iamfiro/design'
+
+const CHANNELS: ListOption[] = [
+  { value: 'email', label: '이메일', group: '알림 채널' },
+  { value: 'push', label: '푸시', group: '알림 채널' },
+  { value: 'sms', label: '문자', group: '알림 채널' },
+  { value: 'slack', label: 'Slack', description: '워크스페이스 연결 필요', group: '연동', disabled: true },
+  { value: 'webhook', label: '웹훅', group: '연동' },
+]
+
+export default function Example() {
+  const [channels, setChannels] = useState<string[]>(['email', 'push'])
+  return (
+    <div style={{ width: 320 }}>
+      <Field label="알림 받을 채널" htmlFor="notify-channels">
+        <MultiSelect id="notify-channels" options={CHANNELS} value={channels} onValueChange={setChannels} selectAll />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 개수로 요약
+
+display='count'는 태그 대신 개수만 보여줘요. 문구는 formatCount로 바꿔요.
+
+```tsx
+import { Avatar, Field, MultiSelect, type ListOption } from '@iamfiro/design'
+
+const MEMBERS: ListOption[] = [
+  { value: 'minji', label: '김민지', description: '디자인' },
+  { value: 'dohyun', label: '이도현', description: '프론트엔드' },
+  { value: 'seoyeon', label: '최서연', description: '백엔드' },
+  { value: 'woojin', label: '정우진', description: '프로덕트' },
+  { value: 'jisu', label: '한지수', description: '데이터' },
+].map((member) => ({ ...member, icon: <Avatar name={member.label} size={22} /> }))
+
+export default function Example() {
+  return (
+    <div style={{ width: 300 }}>
+      <Field label="담당자" htmlFor="assignees">
+        <MultiSelect
+          id="assignees"
+          options={MEMBERS}
+          defaultValue={['minji', 'jisu', 'woojin']}
+          display="count"
+          formatCount={(n) => `담당자 ${n}명`}
+          placeholder="담당자 선택"
+        />
+      </Field>
+    </div>
+  )
+}
+```
+
+### 태그 수 · 크기 · 상태
+
+maxTags를 넘는 태그는 +N으로 접혀요. size, invalid, disabled는 Select와 같아요.
+
+```tsx
+import { Field, MultiSelect, type ListOption } from '@iamfiro/design'
+
+const STATUSES: ListOption[] = [
+  { value: 'todo', label: '할 일' },
+  { value: 'doing', label: '진행 중' },
+  { value: 'review', label: '검토 중' },
+  { value: 'done', label: '완료' },
+]
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 260px)', gap: 16 }}>
+      <Field label="태그 1개까지 (maxTags)" htmlFor="status-max">
+        <MultiSelect id="status-max" options={STATUSES} maxTags={1} defaultValue={['todo', 'doing', 'review']} />
+      </Field>
+      <Field label="작게 (sm)" htmlFor="status-sm">
+        <MultiSelect id="status-sm" size="sm" options={STATUSES} defaultValue={['doing']} />
+      </Field>
+      <Field label="오류" invalid hint="상태를 하나 이상 골라 주세요." htmlFor="status-err">
+        <MultiSelect id="status-err" options={STATUSES} invalid />
+      </Field>
+      <Field label="비활성" htmlFor="status-off">
+        <MultiSelect id="status-off" options={STATUSES} defaultValue={['done']} disabled />
+      </Field>
+    </div>
+  )
+}
+```