@nexus-cross/design-system 1.1.0 → 1.1.1

package/cursor-rules/nexus-ui-api.mdc

@@ -241,7 +241,7 @@ Individual option within Select.
 
 ## Combobox
 
-Searchable select. Text input + popover listbox. Single/multi-select. Sync (auto-filter) or async (onSearch + loading) modes.
+Searchable select with compound option API. Text input + popover listbox. Single/multi-select. Sync (auto-filter) or async (onSearch + loading) modes.
 
 WHEN TO USE:
   • Options ≥ 7, OR labels are long, OR search/filter is needed → Combobox (not Select)
@@ -249,8 +249,29 @@ WHEN TO USE:
   • Async data from server → set onSearch + loading
 For ≤7 simple options use Select. For free-text tags use TagInput.
 
+COMPOUND API:
+  <Combobox value={v} onValueChange={setV} placeholder="…">
+    <Combobox.Option value="kr">한국</Combobox.Option>
+    <Combobox.Option value="jp" disabled>
+      일본
+      <Combobox.OptionDescription>품절</Combobox.OptionDescription>
+      <Combobox.OptionMeta>JP</Combobox.OptionMeta>
+    </Combobox.Option>
+  </Combobox>
+
+  • <Combobox.Option> requires unique `value` (dev mode warns on duplicates and drops the duplicate)
+  • <Combobox.OptionDescription> = secondary line under label
+  • <Combobox.OptionMeta> = right-aligned slot (price, shortcut, badge)
+  • Both slots are excluded from textValue-based search
+
 ASYNC PATTERN:
-  <Combobox options={results} loading={isFetching} onSearch={(q) => mutate(q)} />
+  <Combobox loading={isFetching} onSearch={(q) => mutate(q)}>
+    {results.map((u) => (
+      <Combobox.Option key={u.id} value={u.id}>{u.name}
+        <Combobox.OptionDescription>{u.email}</Combobox.OptionDescription>
+      </Combobox.Option>
+    ))}
+  </Combobox>
   — onSearch fires after searchDebounce (default 250ms). Do NOT clear input on result update; component preserves user's typing.
 
 IME (Korean/Japanese/Chinese): Enter during composition is ignored automatically — do not add custom keydown handlers.
@@ -258,19 +279,22 @@ IME (Korean/Japanese/Chinese): Enter during composition is ignored automatically
 ANTI-PATTERNS:
   ✗ <Select> with 20 options → <Combobox>
   ✗ Manual <input> + dropdown div + filter logic → <Combobox>
+  ✗ Passing options through a prop array (legacy API removed) → use <Combobox.Option> children
+  ✗ Wrapping options in extra elements (<div><Combobox.Option/></div>) → keep them as direct children
+  ✗ Same `value` on two <Combobox.Option> — duplicates are warned + dropped in dev mode
   ✗ Setting value externally to clear input mid-typing → use onValueChange instead
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `options` | `ReactNode` | - | Available options array (ComboboxOption[], required) |
+| `children` | `ReactNode` | - | <Combobox.Option> elements (required). Other children are ignored with a dev-mode warning. Async-search consumers swap this list as `onSearch` results arrive. |
 | `value` | `ReactNode` | - | Selected value. string for single, string[] for multiple |
 | `defaultValue` | `ReactNode` | - | Initial value (uncontrolled) |
 | `onValueChange` | `ReactNode` | - | Value change callback. (value: string | string[]) => void |
 | `multiple` | `boolean` | `false` | Multi-select mode. Selected values shown as chips inside input |
-| `onSearch` | `ReactNode` | - | Async search callback. (query: string) => void. Triggers external data fetching with debounce |
+| `onSearch` | `ReactNode` | - | Async search callback. (query: string) => void. Triggers external data fetching with debounce. When set, the built-in client filter is disabled — render whatever <Combobox.Option> children match the latest results. |
 | `searchDebounce` | `number` | `250` | Debounce delay (ms) before onSearch fires |
-| `loading` | `boolean` | `false` | Externally-controlled loading state. Shows spinner in input suffix |
-| `filter` | `ReactNode` | - | Custom client-side filter. (option, query) => boolean. Default: case-insensitive label includes match |
+| `loading` | `boolean` | `false` | Externally-controlled loading state. Shows spinner in input suffix and a status row inside the popover. |
+| `filter` | `ReactNode` | - | Custom client-side filter. (option: { value, textValue, disabled }, query: string) => boolean. Default: case-insensitive textValue includes match. Ignored when onSearch is set. |
 | `placeholder` | `string` | - | Input placeholder |
 | `emptyMessage` | `ReactNode` | - | Message when no options match (string | ReactNode). Default: "검색 결과 없음" |
 | `loadingMessage` | `ReactNode` | - | Message during loading state inside popover (string | ReactNode). Default: "검색 중…" |
@@ -284,83 +308,140 @@ ANTI-PATTERNS:
 | `className` | `string` | - | Wrapper className |
 | `popoverClassName` | `string` | - | Popover content className |
 
-### ComboboxOption
+### Combobox.Option
+
+Single Combobox option. Direct child of <Combobox> only.
+
+WHEN TO USE:
+  • One per selectable item; `value` MUST be unique within the Combobox
+  • Wrap rich content (icons, badges) directly as children — no escape hatch needed
+  • Use textValue when label is non-text (e.g. <Combobox.Option value="apple" textValue="사과 apple">🍎</Combobox.Option>)
+
+ANTI-PATTERNS:
+  ✗ <Combobox><div><Combobox.Option/></div></Combobox> — Option must be a direct child
+  ✗ Same value on two options → dev warning + silent drop; pick unique values
+  ✗ Putting label text inside <Combobox.OptionDescription> — that slot is the secondary line below the label
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | - | Unique value (string, required). Duplicate values within one Combobox produce a dev-mode console.error and the duplicate option is dropped. |
+| `disabled` | `boolean` | - | Disable selection. Skipped by keyboard navigation (Arrow Up/Down, Home/End). |
+| `textValue` | `string` | - | Text used for client-side filtering and the input display when this option is selected. If omitted, derived from `children` (string nodes only; OptionDescription / OptionMeta are excluded). Set this when label contains icons or non-text nodes you still want searchable (e.g. textValue="apple 사과 fruit"). |
+| `className` | `string` | - | Class merged onto the rendered <div role="option">. |
+| `children` | `ReactNode` | - | Label content + optional <Combobox.OptionDescription> / <Combobox.OptionMeta> slots. |
+
+### Combobox.OptionDescription
+
+Secondary text shown below an option label. Use for hints like "Republic of Korea" beneath "한국". Excluded from textValue-based search.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | - | Secondary text below the label (ReactNode). |
+| `className` | `string` | - | Class for the description node. |
+
+### Combobox.OptionMeta
 
-Single Combobox option.
+Right-aligned slot inside an option. Use for prices, keyboard shortcuts, version tags, status badges. Excluded from textValue-based search.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `string` | - | Option value (unique key) |
-| `label` | `ReactNode` | - | Display label (string | ReactNode) |
-| `description` | `ReactNode` | - | Secondary text below label (ReactNode) |
-| `disabled` | `boolean` | - | Disabled option |
+| `children` | `ReactNode` | - | Right-aligned meta content (price, badge, shortcut, etc.). |
+| `className` | `string` | - | Class for the meta slot. |
 
-Searchable select with popover listbox. Supports single/multi-select and sync (auto-filter) / async (onSearch + loading) modes. **WAI-ARIA Combobox pattern** (Radix Popover under the hood — NOT Radix Select).
+Searchable select with popover listbox. **Compound API** — options are declared as <Combobox.Option> children. Supports single/multi-select and sync (auto-filter) / async (onSearch + loading) modes. **WAI-ARIA Combobox pattern** (Radix Popover under the hood — NOT Radix Select).
 
-- **Sync mode** (no `onSearch` prop): client-side filters `options` by typed query (case-insensitive label includes match by default; override via `filter`).
-- **Async mode** (provide `onSearch`): debounced (`searchDebounce`, default 250ms) callback fires for external data fetch. Set `loading` to show spinner in the input suffix.
-- **Multi-select** (`multiple`): selected values render as removable chips inside the input. Backspace on empty input removes the last chip.
+- **Subcomponents**: `Combobox.Option` (required `value`), `Combobox.OptionDescription` (secondary line), `Combobox.OptionMeta` (right-aligned slot).
+- **Duplicate `value`**: dev mode logs `console.error` and silently drops the duplicate.
+- **textValue**: derived from option children (text nodes only; OptionDescription/OptionMeta excluded). Override per-option when label is non-text.
+- **Sync mode** (no `onSearch`): client-side filters by `textValue` (case-insensitive includes; override with `filter`).
+- **Async mode** (provide `onSearch`): debounced (`searchDebounce`, default 250ms) callback fires for external data fetch. Set `loading` for spinner.
+- **Multi-select** (`multiple`): chips inside input; Backspace on empty input removes the last chip.
 - Keyboard: Arrow Up/Down, Home/End, Enter to select, Escape to close.
 
 ```tsx
-// 1) Sync — auto-filter local options
-const COUNTRIES = [
-  { value: 'kr', label: '한국' },
-  { value: 'jp', label: '일본' },
-  { value: 'us', label: '미국' },
-];
-
-<Combobox
-  options={COUNTRIES}
-  value={value}
-  onValueChange={setValue}
-  placeholder="국가 선택"
-/>
+// 1) Sync — declarative options
+<Combobox value={value} onValueChange={setValue} placeholder="국가 선택">
+  <Combobox.Option value="kr">한국</Combobox.Option>
+  <Combobox.Option value="jp">일본</Combobox.Option>
+  <Combobox.Option value="us" disabled>
+    미국
+    <Combobox.OptionDescription>일시 품절</Combobox.OptionDescription>
+  </Combobox.Option>
+</Combobox>
 
 // 2) Async — external search w/ loading spinner
-const [results, setResults] = useState<ComboboxOption[]>([]);
+const [results, setResults] = useState<{ id: string; name: string; email: string }[]>([]);
 const [loading, setLoading] = useState(false);
 
 const handleSearch = async (q: string) => {
-  if (!q) return setResults([]);
   setLoading(true);
-  const users = await fetchUsers(q);
-  setResults(users.map((u) => ({ value: u.id, label: u.name, description: u.email })));
+  setResults(await fetchUsers(q));
   setLoading(false);
 };
 
 <Combobox
-  options={results}
   loading={loading}
   onSearch={handleSearch}
   value={selectedId}
   onValueChange={setSelectedId}
   placeholder="유저 검색…"
   emptyMessage="검색 결과 없음"
-/>
+>
+  {results.map((u) => (
+    <Combobox.Option key={u.id} value={u.id}>
+      {u.name}
+      <Combobox.OptionDescription>{u.email}</Combobox.OptionDescription>
+    </Combobox.Option>
+  ))}
+</Combobox>
 
 // 3) Multi-select with chips
 <Combobox
   multiple
-  options={results}
   value={selectedIds}
   onValueChange={setSelectedIds}
   loading={loading}
   onSearch={handleSearch}
-/>
-
-// 4) With label / description / error
+>
+  {results.map((u) => (
+    <Combobox.Option key={u.id} value={u.id}>{u.name}</Combobox.Option>
+  ))}
+</Combobox>
+
+// 4) Rich option — meta slot for prices / shortcuts / badges
+<Combobox placeholder="플랜 선택">
+  <Combobox.Option value="free">
+    Free
+    <Combobox.OptionDescription>개인용</Combobox.OptionDescription>
+    <Combobox.OptionMeta>$0/mo</Combobox.OptionMeta>
+  </Combobox.Option>
+  <Combobox.Option value="pro">
+    Pro
+    <Combobox.OptionDescription>소규모 팀</Combobox.OptionDescription>
+    <Combobox.OptionMeta>$12/mo</Combobox.OptionMeta>
+  </Combobox.Option>
+</Combobox>
+
+// 5) Non-text label — explicit textValue for searching
+<Combobox.Option value="apple" textValue="apple 사과 fruit">
+  🍎 사과
+</Combobox.Option>
+
+// 6) With label / description / error
 <Combobox
   label="담당자"
   description="검색 후 선택하세요"
-  options={results}
   loading={loading}
   onSearch={handleSearch}
   value={value}
   onValueChange={setValue}
   error={!value}
   size="lg"
-/>
+>
+  {results.map((u) => (
+    <Combobox.Option key={u.id} value={u.id}>{u.name}</Combobox.Option>
+  ))}
+</Combobox>
 ```
 
 **When to use `Select` vs `Combobox`**:
@@ -368,6 +449,11 @@ const handleSearch = async (q: string) => {
 - Long list / async search / typed input → `Combobox`
 - Free-form tag input (any string) → `TagInput`
 
+**ANTI-PATTERNS**:
+- ✗ `<Combobox options={[...]}>` — legacy prop API removed; use `<Combobox.Option>` children
+- ✗ Wrapping options: `<Combobox><div><Combobox.Option/></div></Combobox>` — Option must be a direct child
+- ✗ Duplicate `value` across options — dev warning + duplicate dropped
+
 ---
 
 ## CheckBox

package/cursor-rules/nexus-ui-decisions.mdc

@@ -40,8 +40,12 @@ UI 작업 시 어떤 컴포넌트를 골라야 할지 결정하는 가이드. **
 // ❌ 옵션 20개에 Select
 <Select><SelectItem>...</SelectItem>...</Select>
 
-// ✅ 옵션 20개에 Combobox
-<Combobox options={options} placeholder="검색하여 선택" />
+// ✅ 옵션 20개에 Combobox (compound API)
+<Combobox placeholder="검색하여 선택">
+  {options.map((o) => (
+    <Combobox.Option key={o.value} value={o.value}>{o.label}</Combobox.Option>
+  ))}
+</Combobox>
 
 // ❌ 옵션 3개에 Select
 <Select><SelectItem>S</SelectItem><SelectItem>M</SelectItem><SelectItem>L</SelectItem></Select>