docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -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]]
|
||||
Reference in New Issue
Block a user