[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,90 +2,220 @@
|
||||
id: wiki-2026-0508-downshift
|
||||
title: Downshift
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: []
|
||||
aliases: [downshift-js, useCombobox, useSelect]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.92
|
||||
tags: [uncategorized]
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [react, ui, accessibility, combobox, hooks]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-08
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: typescript
|
||||
framework: react
|
||||
---
|
||||
|
||||
# [[Downshift|Downshift]]
|
||||
# Downshift
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
Down[[Shift|Shift]]는 React 환경에서 `useCombobox()`와 같은 기능을 제공하는 헤드리스 컴포넌트([[Headless Components|Headless Components]]) 라이브러리의 대표적인 예시입니다 [1]. 이 라이브러리는 컴포넌트의 내부 상태와 로직만을 노출하고, 실제 UI 마크업의 형태는 개발자가 전적으로 정의하도록 위임합니다 [1]. 이를 통해 특정 디자인에 얽매이지 않고 접근성 높은 UI 라이브러리를 구축할 수 있도록 돕습니다 [1].
|
||||
## 매 한 줄
|
||||
> **"매 headless UI 의 accessibility-first combobox primitive"**. Kent C. Dodds 의 2017 release, 매 render-prop / hook API 의 ARIA 1.2 combobox spec 의 implement. 매 2026 의 매 alternative 의 많음 (Radix, Headless UI, Ariakit, React Aria) 이지만 매 downshift 의 매 mature / battle-tested / tiny (~5KB).
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
* **헤드리스 컴포넌트(Headless Components) 패턴:** Downshift는 UI 마크업 없이 로직만을 제공하는 헤드리스 컴포넌트의 특징을 잘 보여줍니다 [1]. 개발자는 Downshift가 제공하는 로직을 바탕으로 자신이 원하는 대로 시각적 요소를 구현할 수 있습니다 [1].
|
||||
* **로직과 마크업의 완벽한 분리:** 상태 및 동작 로직을 UI 마크업과 철저히 분리하기 때문에 구성 요소의 조합성(Composability)이 매우 뛰어납니다 [1].
|
||||
* **뛰어난 확장성과 호환성:** 특정한 스타일이나 마크업을 강제하지 않으므로 어떠한 디자인 시스템과도 완벽하게 호환되며, 프레임워크에 구애받지 않는(framework-agnostic) 확장 가능한 컴포넌트를 구축하는 데 매우 적합합니다 [1].
|
||||
## 매 핵심
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** [[Headless Components|Headless Components]], React Component Patterns, [[Accessible UI Libraries|Accessible UI Libraries]]
|
||||
- **Projects/Contexts:** [[Design Systems|DesignSystems]], 확장 가능하고 유지보수하기 쉬운 프론트엔드 UI 컴포넌트 아키텍처 구축 [1].
|
||||
- **Contradictions/Notes:** 소스에 관련 정보가 부족합니다.
|
||||
### 매 무엇 의 solve
|
||||
- 매 native `<select>` 의 styling 의 unable.
|
||||
- 매 custom dropdown 의 매 keyboard / screen reader / focus management 의 hard.
|
||||
- 매 ARIA roles (`combobox`, `listbox`, `option`) 의 correctly wire.
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-26*
|
||||
### 매 API 종류
|
||||
- `useCombobox` — 매 typeahead 의 search input + dropdown.
|
||||
- `useSelect` — 매 native select replacement (no input).
|
||||
- `useMultipleSelection` — 매 tag / chip selection.
|
||||
- Render-prop `<Downshift>` — 매 legacy, 매 hooks 권장.
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
### 매 핵심 state
|
||||
- `isOpen` — dropdown open?
|
||||
- `highlightedIndex` — 매 keyboard hover.
|
||||
- `selectedItem` — 매 chosen value.
|
||||
- `inputValue` — 매 typed text.
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
### 매 응용
|
||||
1. Autocomplete / type-ahead search.
|
||||
2. Country / timezone picker.
|
||||
3. Multi-select tag input (with `useMultipleSelection`).
|
||||
4. Async-loading dropdowns.
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
## 💻 패턴
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
### Pattern 1: Basic useCombobox
|
||||
```tsx
|
||||
import { useCombobox } from "downshift";
|
||||
import { useState } from "react";
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
const ALL = ["apple","banana","cherry","date","elderberry"];
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
export function FruitCombo() {
|
||||
const [items, setItems] = useState(ALL);
|
||||
const cb = useCombobox({
|
||||
items,
|
||||
onInputValueChange: ({ inputValue }) => {
|
||||
setItems(ALL.filter(f => f.includes(inputValue?.toLowerCase() ?? "")));
|
||||
},
|
||||
});
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
|
||||
- **과거 데이터와의 충돌:** 없음
|
||||
- **정책 변화:** 없음
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
return (
|
||||
<div>
|
||||
<label {...cb.getLabelProps()}>Fruit</label>
|
||||
<input {...cb.getInputProps()} />
|
||||
<ul {...cb.getMenuProps()}>
|
||||
{cb.isOpen && items.map((item, i) => (
|
||||
<li
|
||||
key={item}
|
||||
{...cb.getItemProps({ item, index: i })}
|
||||
style={{ background: cb.highlightedIndex === i ? "#def" : "white" }}
|
||||
>{item}</li>
|
||||
))}
|
||||
</ul>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Pattern 2: Async items (debounced)
|
||||
```tsx
|
||||
import { useCombobox } from "downshift";
|
||||
import { useState, useEffect } from "react";
|
||||
import { useDebouncedValue } from "./hooks";
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
export function UserPicker() {
|
||||
const [query, setQuery] = useState("");
|
||||
const debounced = useDebouncedValue(query, 250);
|
||||
const [items, setItems] = useState<User[]>([]);
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
useEffect(() => {
|
||||
if (!debounced) return;
|
||||
fetch(`/api/users?q=${debounced}`).then(r => r.json()).then(setItems);
|
||||
}, [debounced]);
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
const cb = useCombobox({
|
||||
items,
|
||||
itemToString: u => u?.name ?? "",
|
||||
onInputValueChange: ({ inputValue }) => setQuery(inputValue ?? ""),
|
||||
});
|
||||
// 매 render UI 동일 패턴.
|
||||
}
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### Pattern 3: Multi-select with chips
|
||||
```tsx
|
||||
import { useCombobox, useMultipleSelection } from "downshift";
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
function TagInput({ all }: { all: string[] }) {
|
||||
const ms = useMultipleSelection<string>({});
|
||||
const remaining = all.filter(t => !ms.selectedItems.includes(t));
|
||||
const cb = useCombobox({
|
||||
items: remaining,
|
||||
onSelectedItemChange: ({ selectedItem }) => {
|
||||
if (selectedItem) ms.addSelectedItem(selectedItem);
|
||||
},
|
||||
selectedItem: null,
|
||||
});
|
||||
return (
|
||||
<div>
|
||||
{ms.selectedItems.map((t, i) => (
|
||||
<span key={t} {...ms.getSelectedItemProps({ selectedItem: t, index: i })}>
|
||||
{t} <button onClick={() => ms.removeSelectedItem(t)}>×</button>
|
||||
</span>
|
||||
))}
|
||||
<input {...cb.getInputProps(ms.getDropdownProps())} />
|
||||
{/* menu... */}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 4: useSelect (no typing)
|
||||
```tsx
|
||||
import { useSelect } from "downshift";
|
||||
|
||||
function SizeSelect() {
|
||||
const items = ["S","M","L","XL"];
|
||||
const sel = useSelect({ items });
|
||||
return (
|
||||
<>
|
||||
<button {...sel.getToggleButtonProps()}>
|
||||
{sel.selectedItem ?? "Pick size"}
|
||||
</button>
|
||||
<ul {...sel.getMenuProps()}>
|
||||
{sel.isOpen && items.map((s, i) => (
|
||||
<li key={s} {...sel.getItemProps({ item: s, index: i })}>{s}</li>
|
||||
))}
|
||||
</ul>
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 5: Controlled state (Redux / Zustand)
|
||||
```tsx
|
||||
const cb = useCombobox({
|
||||
items,
|
||||
selectedItem: store.selected,
|
||||
onSelectedItemChange: ({ selectedItem }) => store.set(selectedItem),
|
||||
inputValue: store.input,
|
||||
onInputValueChange: ({ inputValue }) => store.setInput(inputValue ?? ""),
|
||||
});
|
||||
```
|
||||
|
||||
### Pattern 6: stateReducer for custom keyboard
|
||||
```tsx
|
||||
import { useCombobox } from "downshift";
|
||||
const stateReducer = (state, { type, changes }) => {
|
||||
switch (type) {
|
||||
case useCombobox.stateChangeTypes.InputKeyDownEnter:
|
||||
case useCombobox.stateChangeTypes.ItemClick:
|
||||
// 매 Enter 시 dropdown 의 close 하지 X
|
||||
return { ...changes, isOpen: state.isOpen, highlightedIndex: state.highlightedIndex };
|
||||
default: return changes;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| React + ARIA combobox | downshift |
|
||||
| Full design system (Modal, Tabs, etc.) | Radix UI / Ariakit |
|
||||
| Adobe quality + i18n | React Aria |
|
||||
| Tailwind + simple primitives | Headless UI |
|
||||
| Vue / Svelte | downshift X — find native |
|
||||
|
||||
**기본값**: 매 React combobox 만 필요 시 downshift, 매 design system 전체 시 Radix.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[React]] · [[Headless UI]] · [[Accessibility]]
|
||||
- 변형: [[Radix UI]] · [[Headless UI (Tailwind Labs)]] · [[Ariakit]] · [[React Aria]]
|
||||
- 응용: [[Combobox Pattern]] · [[Autocomplete]]
|
||||
- Adjacent: [[ARIA Authoring Practices]] · [[Render Props]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 React typeahead / select 의 build, 매 a11y 의 mandatory.
|
||||
**언제 X**: 매 native select 의 충분, 매 React 외 framework.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Custom keyboard 의 reinvent**: 매 stateReducer 로 override 의 의도된 path.
|
||||
- **State sync mistakes**: 매 controlled / uncontrolled 의 mix — 매 하나의 choose.
|
||||
- **getXxxProps 의 spread 의 omit**: 매 ARIA attrs 의 lost — 매 a11y 의 break.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (downshift v9 docs, ARIA 1.2 combobox pattern, GitHub 11k+ stars).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — useCombobox + useSelect + multi-select |
|
||||
|
||||
Reference in New Issue
Block a user