[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,164 @@
+---
+id: react-headless-ui-patterns
+title: Headless UI — Radix / Headless UI / 자체 Build
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [react, headless, radix, accessibility, vibe-coding]
+tech_stack: { language: "TS / React", applicable_to: ["Frontend"] }
+applied_in: []
+aliases: [Radix UI, Headless UI, shadcn/ui, render props, compound components]
+---
+
+# Headless UI
+
+> 행동 + a11y 만 제공, **스타일은 너의 것**. Radix UI / Headless UI (Tailwind Labs) / Ariakit. shadcn/ui = Radix 위에 Tailwind. 직접 dropdown / dialog / combobox 만들지 말 것.
+
+## 📖 핵심 개념
+- Behavior: focus / keyboard / portal / aria.
+- Compound components: `<Dialog><Dialog.Trigger>...<Dialog.Content>` 패턴.
+- Render prop / asChild: child element 가 행동 흡수.
+- Controlled vs uncontrolled.
+
+## 💻 코드 패턴
+
+### Radix Dialog
+```tsx
+import * as Dialog from '@radix-ui/react-dialog';
+
+<Dialog.Root>
+  <Dialog.Trigger asChild>
+    <Button>Open</Button>
+  </Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay className="fixed inset-0 bg-black/50" />
+    <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white p-6 rounded-md">
+      <Dialog.Title>Confirm</Dialog.Title>
+      <Dialog.Description>Are you sure?</Dialog.Description>
+      <div className="flex gap-2 justify-end">
+        <Dialog.Close asChild><Button variant="ghost">Cancel</Button></Dialog.Close>
+        <Button onClick={handleConfirm}>Yes</Button>
+      </div>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog.Root>
+```
+
+자동 처리: focus trap, ESC, click-outside, scroll lock, aria.
+
+### Radix Dropdown
+```tsx
+import * as Menu from '@radix-ui/react-dropdown-menu';
+
+<Menu.Root>
+  <Menu.Trigger asChild><Button>Menu</Button></Menu.Trigger>
+  <Menu.Portal>
+    <Menu.Content className="bg-white rounded shadow p-1" sideOffset={4}>
+      <Menu.Item onSelect={() => navigate('/profile')}>Profile</Menu.Item>
+      <Menu.Item onSelect={logout}>Sign out</Menu.Item>
+      <Menu.Separator className="h-px bg-gray-200 my-1" />
+      <Menu.Sub>
+        <Menu.SubTrigger>More →</Menu.SubTrigger>
+        <Menu.SubContent>...</Menu.SubContent>
+      </Menu.Sub>
+    </Menu.Content>
+  </Menu.Portal>
+</Menu.Root>
+```
+
+### Headless UI Combobox (autocomplete)
+```tsx
+import { Combobox, ComboboxInput, ComboboxOptions, ComboboxOption } from '@headlessui/react';
+
+const [q, setQ] = useState('');
+const filtered = q ? items.filter(i => i.name.includes(q)) : items;
+
+<Combobox value={selected} onChange={setSelected}>
+  <ComboboxInput onChange={(e) => setQ(e.target.value)} displayValue={(i: Item) => i?.name} />
+  <ComboboxOptions>
+    {filtered.map(i => <ComboboxOption key={i.id} value={i}>{i.name}</ComboboxOption>)}
+  </ComboboxOptions>
+</Combobox>
+```
+
+### asChild 패턴 (Radix)
+```tsx
+<Tooltip.Trigger asChild>
+  <button className="...">My button</button>
+</Tooltip.Trigger>
+// 새 element 안 만들고 child 에 trigger props 합침
+```
+
+요구사항: child 가 ref 를 받아야 → forwardRef 컴포넌트 사용.
+
+### Ariakit Toolbar (잘 쓰는 라이브러리)
+```tsx
+import * as Ariakit from '@ariakit/react';
+
+const toolbar = Ariakit.useToolbarStore();
+<Ariakit.Toolbar store={toolbar}>
+  <Ariakit.ToolbarItem>Bold</Ariakit.ToolbarItem>
+  <Ariakit.ToolbarItem>Italic</Ariakit.ToolbarItem>
+</Ariakit.Toolbar>
+```
+
+### shadcn/ui (Radix + Tailwind, copy-paste)
+```bash
+npx shadcn@latest add dialog
+# 컴포넌트 직접 코드베이스에 복사 — 너가 소유 + 수정 자유
+```
+
+### 컴파운드 패턴 자체 구현
+```tsx
+const TabsContext = createContext<TabsCtx | null>(null);
+
+function Tabs({ defaultValue, children }: ...) {
+  const [value, setValue] = useState(defaultValue);
+  return <TabsContext.Provider value={{ value, setValue }}>{children}</TabsContext.Provider>;
+}
+function TabsTrigger({ value, children }: ...) {
+  const ctx = useContext(TabsContext)!;
+  return <button onClick={() => ctx.setValue(value)} aria-selected={ctx.value === value}>{children}</button>;
+}
+function TabsContent({ value, children }: ...) {
+  const ctx = useContext(TabsContext)!;
+  return ctx.value === value ? <div>{children}</div> : null;
+}
+
+Tabs.Trigger = TabsTrigger;
+Tabs.Content = TabsContent;
+```
+
+## 🤔 의사결정 기준
+| 컴포넌트 | 추천 |
+|---|---|
+| Modal / Dialog | Radix Dialog |
+| Dropdown / Popover | Radix DropdownMenu / Popover |
+| Combobox / Listbox | Headless UI / Ariakit |
+| Tabs | Radix Tabs |
+| Toast | Sonner / Radix Toast |
+| Date picker | react-day-picker |
+| Drag & drop | dnd-kit |
+| 자체 디자인 시스템 | shadcn 카피 + 변경 |
+
+## ❌ 안티패턴
+- **자체 dialog (focus trap 없음)**: a11y / 키보드 깨짐. 라이브러리 사용.
+- **Portal 안 쓰면**: z-index / overflow 지옥.
+- **asChild 사용 시 child 가 forwardRef X**: ref 전달 안 됨.
+- **Animation 직접**: Radix `data-state` + Tailwind animate 가 깔끔.
+- **Controlled / uncontrolled 혼용**: 둘 중 하나.
+- **모든 컴포넌트 npm 라이브러리 의존**: 무거움. 자주 쓰는 건 자체.
+- **Radix UI css 미적용**: 기본 unstyled. Tailwind/CSS 직접.
+
+## 🤖 LLM 활용 힌트
+- Radix + Tailwind + shadcn/ui 표준 조합.
+- Combobox = Headless UI / Ariakit.
+- 자체 자체 일 때만 — focus trap / a11y 제대로 구현해야.
+
+## 🔗 관련 문서
+- [[Frontend_Tailwind_Architecture]]
+- [[Frontend_A11y_Testing]]
+- [[React_Component_Composition]]