@nexus-cross/design-system 1.1.0 → 1.1.1

package/dist/schemas/combobox.d.ts

@@ -1,22 +1,45 @@
 import { z } from 'zod';
-export declare const comboboxOptionSchema: z.ZodObject<{
+export declare const comboboxOptionPropsSchema: z.ZodObject<{
     value: z.ZodString;
-    label: z.ZodAny;
-    description: z.ZodOptional<z.ZodAny>;
     disabled: z.ZodOptional<z.ZodBoolean>;
+    textValue: z.ZodOptional<z.ZodString>;
+    className: z.ZodOptional<z.ZodString>;
+    children: z.ZodOptional<z.ZodAny>;
 }, "strip", z.ZodTypeAny, {
     value: string;
-    label?: any;
-    description?: any;
+    className?: string | undefined;
+    children?: any;
     disabled?: boolean | undefined;
+    textValue?: string | undefined;
 }, {
     value: string;
-    label?: any;
-    description?: any;
+    className?: string | undefined;
+    children?: any;
     disabled?: boolean | undefined;
+    textValue?: string | undefined;
+}>;
+export declare const comboboxOptionDescriptionPropsSchema: z.ZodObject<{
+    children: z.ZodOptional<z.ZodAny>;
+    className: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    className?: string | undefined;
+    children?: any;
+}, {
+    className?: string | undefined;
+    children?: any;
+}>;
+export declare const comboboxOptionMetaPropsSchema: z.ZodObject<{
+    children: z.ZodOptional<z.ZodAny>;
+    className: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    className?: string | undefined;
+    children?: any;
+}, {
+    className?: string | undefined;
+    children?: any;
 }>;
 export declare const comboboxPropsSchema: z.ZodObject<{
-    options: z.ZodAny;
+    children: z.ZodAny;
     value: z.ZodOptional<z.ZodAny>;
     defaultValue: z.ZodOptional<z.ZodAny>;
     onValueChange: z.ZodOptional<z.ZodAny>;
@@ -45,9 +68,9 @@ export declare const comboboxPropsSchema: z.ZodObject<{
     clearable: boolean;
     autoOpenOnFocus: boolean;
     className?: string | undefined;
+    children?: any;
     error?: boolean | undefined;
     filter?: any;
-    options?: any;
     label?: any;
     description?: any;
     value?: any;
@@ -61,9 +84,9 @@ export declare const comboboxPropsSchema: z.ZodObject<{
     popoverClassName?: string | undefined;
 }, {
     className?: string | undefined;
+    children?: any;
     error?: boolean | undefined;
     filter?: any;
-    options?: any;
     label?: any;
     loading?: boolean | undefined;
     description?: any;

package/dist/schemas/combobox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["../../src/schemas/combobox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;EAOK,CAAC;AAEvC,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiF7B,CAAC"}
+{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["../../src/schemas/combobox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;EA0CnC,CAAC;AAEJ,eAAO,MAAM,oCAAoC;;;;;;;;;EAU9C,CAAC;AAEJ,eAAO,MAAM,6BAA6B;;;;;;;;;EAUvC,CAAC;AAEJ,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2G7B,CAAC"}

package/dist/schemas/combobox.json

@@ -4,8 +4,8 @@
     "comboboxPropsSchema": {
       "type": "object",
       "properties": {
-        "options": {
-          "description": "Available options array (ComboboxOption[], required)"
+        "children": {
+          "description": "<Combobox.Option> elements (required). Other children are ignored with a dev-mode warning. Async-search consumers swap this list as `onSearch` results arrive."
         },
         "value": {
           "description": "Selected value. string for single, string[] for multiple"
@@ -22,7 +22,7 @@
           "description": "Multi-select mode. Selected values shown as chips inside input"
         },
         "onSearch": {
-          "description": "Async search callback. (query: string) => void. Triggers external data fetching with debounce"
+          "description": "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": {
           "type": "number",
@@ -32,10 +32,10 @@
         "loading": {
           "type": "boolean",
           "default": false,
-          "description": "Externally-controlled loading state. Shows spinner in input suffix"
+          "description": "Externally-controlled loading state. Shows spinner in input suffix and a status row inside the popover."
         },
         "filter": {
-          "description": "Custom client-side filter. (option, query) => boolean. Default: case-insensitive label includes match"
+          "description": "Custom client-side filter. (option: { value, textValue, disabled }, query: string) => boolean. Default: case-insensitive textValue includes match. Ignored when onSearch is set."
         },
         "placeholder": {
           "type": "string",
@@ -91,7 +91,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Searchable select. Text input + popover listbox. Single/multi-select. Sync (auto-filter) or async (onSearch + loading) modes.\n\nWHEN TO USE:\n  • Options ≥ 7, OR labels are long, OR search/filter is needed → Combobox (not Select)\n  • Multi-select form field → Combobox with multiple (chips render inside input)\n  • Async data from server → set onSearch + loading\nFor ≤7 simple options use Select. For free-text tags use TagInput.\n\nASYNC PATTERN:\n  <Combobox options={results} loading={isFetching} onSearch={(q) => mutate(q)} />\n  — onSearch fires after searchDebounce (default 250ms). Do NOT clear input on result update; component preserves user's typing.\n\nIME (Korean/Japanese/Chinese): Enter during composition is ignored automatically — do not add custom keydown handlers.\n\nANTI-PATTERNS:\n  ✗ <Select> with 20 options → <Combobox>\n  ✗ Manual <input> + dropdown div + filter logic → <Combobox>\n  ✗ Setting value externally to clear input mid-typing → use onValueChange instead"
+      "description": "Searchable select with compound option API. Text input + popover listbox. Single/multi-select. Sync (auto-filter) or async (onSearch + loading) modes.\n\nWHEN TO USE:\n  • Options ≥ 7, OR labels are long, OR search/filter is needed → Combobox (not Select)\n  • Multi-select form field → Combobox with multiple (chips render inside input)\n  • Async data from server → set onSearch + loading\nFor ≤7 simple options use Select. For free-text tags use TagInput.\n\nCOMPOUND API:\n  <Combobox value={v} onValueChange={setV} placeholder=\"…\">\n    <Combobox.Option value=\"kr\">한국</Combobox.Option>\n    <Combobox.Option value=\"jp\" disabled>\n      일본\n      <Combobox.OptionDescription>품절</Combobox.OptionDescription>\n      <Combobox.OptionMeta>JP</Combobox.OptionMeta>\n    </Combobox.Option>\n  </Combobox>\n\n  • <Combobox.Option> requires unique `value` (dev mode warns on duplicates and drops the duplicate)\n  • <Combobox.OptionDescription> = secondary line under label\n  • <Combobox.OptionMeta> = right-aligned slot (price, shortcut, badge)\n  • Both slots are excluded from textValue-based search\n\nASYNC PATTERN:\n  <Combobox loading={isFetching} onSearch={(q) => mutate(q)}>\n    {results.map((u) => (\n      <Combobox.Option key={u.id} value={u.id}>{u.name}\n        <Combobox.OptionDescription>{u.email}</Combobox.OptionDescription>\n      </Combobox.Option>\n    ))}\n  </Combobox>\n  — onSearch fires after searchDebounce (default 250ms). Do NOT clear input on result update; component preserves user's typing.\n\nIME (Korean/Japanese/Chinese): Enter during composition is ignored automatically — do not add custom keydown handlers.\n\nANTI-PATTERNS:\n  ✗ <Select> with 20 options → <Combobox>\n  ✗ Manual <input> + dropdown div + filter logic → <Combobox>\n  ✗ Passing options through a prop array (legacy API removed) → use <Combobox.Option> children\n  ✗ Wrapping options in extra elements (<div><Combobox.Option/></div>) → keep them as direct children\n  ✗ Same `value` on two <Combobox.Option> — duplicates are warned + dropped in dev mode\n  ✗ Setting value externally to clear input mid-typing → use onValueChange instead"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/comboboxOption.json

@@ -1,29 +1,34 @@
 {
-  "$ref": "#/definitions/comboboxOptionSchema",
+  "$ref": "#/definitions/comboboxOptionPropsSchema",
   "definitions": {
-    "comboboxOptionSchema": {
+    "comboboxOptionPropsSchema": {
       "type": "object",
       "properties": {
         "value": {
           "type": "string",
-          "description": "Option value (unique key)"
-        },
-        "label": {
-          "description": "Display label (string | ReactNode)"
-        },
-        "description": {
-          "description": "Secondary text below label (ReactNode)"
+          "description": "Unique value (string, required). Duplicate values within one Combobox produce a dev-mode console.error and the duplicate option is dropped."
         },
         "disabled": {
           "type": "boolean",
-          "description": "Disabled option"
+          "description": "Disable selection. Skipped by keyboard navigation (Arrow Up/Down, Home/End)."
+        },
+        "textValue": {
+          "type": "string",
+          "description": "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": {
+          "type": "string",
+          "description": "Class merged onto the rendered <div role=\"option\">."
+        },
+        "children": {
+          "description": "Label content + optional <Combobox.OptionDescription> / <Combobox.OptionMeta> slots."
         }
       },
       "required": [
         "value"
       ],
       "additionalProperties": false,
-      "description": "Single Combobox option."
+      "description": "Single Combobox option. Direct child of <Combobox> only.\n\nWHEN TO USE:\n  • One per selectable item; `value` MUST be unique within the Combobox\n  • Wrap rich content (icons, badges) directly as children — no escape hatch needed\n  • Use textValue when label is non-text (e.g. <Combobox.Option value=\"apple\" textValue=\"사과 apple\">🍎</Combobox.Option>)\n\nANTI-PATTERNS:\n  ✗ <Combobox><div><Combobox.Option/></div></Combobox> — Option must be a direct child\n  ✗ Same value on two options → dev warning + silent drop; pick unique values\n  ✗ Putting label text inside <Combobox.OptionDescription> — that slot is the secondary line below the label"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/comboboxOptionDescription.json

@@ -0,0 +1,20 @@
+{
+  "$ref": "#/definitions/comboboxOptionDescriptionPropsSchema",
+  "definitions": {
+    "comboboxOptionDescriptionPropsSchema": {
+      "type": "object",
+      "properties": {
+        "children": {
+          "description": "Secondary text below the label (ReactNode)."
+        },
+        "className": {
+          "type": "string",
+          "description": "Class for the description node."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Secondary text shown below an option label. Use for hints like \"Republic of Korea\" beneath \"한국\". Excluded from textValue-based search."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/dist/schemas/comboboxOptionMeta.json

@@ -0,0 +1,20 @@
+{
+  "$ref": "#/definitions/comboboxOptionMetaPropsSchema",
+  "definitions": {
+    "comboboxOptionMetaPropsSchema": {
+      "type": "object",
+      "properties": {
+        "children": {
+          "description": "Right-aligned meta content (price, badge, shortcut, etc.)."
+        },
+        "className": {
+          "type": "string",
+          "description": "Class for the meta slot."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Right-aligned slot inside an option. Use for prices, keyboard shortcuts, version tags, status badges. Excluded from textValue-based search."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/dist/schemas/index.d.ts

@@ -3,7 +3,7 @@ export { buttonPropsSchema } from './button';
 export { textInputPropsSchema } from './text-input';
 export { textAreaPropsSchema } from './text-area';
 export { selectPropsSchema, selectItemPropsSchema } from './select';
-export { comboboxPropsSchema, comboboxOptionSchema } from './combobox';
+export { comboboxPropsSchema, comboboxOptionPropsSchema, comboboxOptionDescriptionPropsSchema, comboboxOptionMetaPropsSchema, } from './combobox';
 export { dropdownMenuPropsSchema } from './dropdown-menu';
 export { toggleGroupPropsSchema } from './toggle-group';
 export { sliderPropsSchema } from './slider';

package/dist/schemas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"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"}

package/dist/schemas.js

@@ -167,22 +167,57 @@ var selectItemPropsSchema = zod.z.object({
   disabled: zod.z.boolean().optional().describe("Disabled"),
   className: zod.z.string().optional().describe("Style override")
 }).describe("Individual option within Select.");
-var comboboxOptionSchema = zod.z.object({
-  value: zod.z.string().describe("Option value (unique key)"),
-  label: zod.z.any().describe("Display label (string | ReactNode)"),
-  description: zod.z.any().optional().describe("Secondary text below label (ReactNode)"),
-  disabled: zod.z.boolean().optional().describe("Disabled option")
-}).describe("Single Combobox option.");
+var comboboxOptionPropsSchema = zod.z.object({
+  value: zod.z.string().describe(
+    "Unique value (string, required). Duplicate values within one Combobox produce a dev-mode console.error and the duplicate option is dropped."
+  ),
+  disabled: zod.z.boolean().optional().describe(
+    "Disable selection. Skipped by keyboard navigation (Arrow Up/Down, Home/End)."
+  ),
+  textValue: zod.z.string().optional().describe(
+    '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 \uC0AC\uACFC fruit").'
+  ),
+  className: zod.z.string().optional().describe('Class merged onto the rendered <div role="option">.'),
+  children: zod.z.any().optional().describe(
+    "Label content + optional <Combobox.OptionDescription> / <Combobox.OptionMeta> slots."
+  )
+}).describe(
+  `Single Combobox option. Direct child of <Combobox> only.
+
+WHEN TO USE:
+  \u2022 One per selectable item; \`value\` MUST be unique within the Combobox
+  \u2022 Wrap rich content (icons, badges) directly as children \u2014 no escape hatch needed
+  \u2022 Use textValue when label is non-text (e.g. <Combobox.Option value="apple" textValue="\uC0AC\uACFC apple">\u{1F34E}</Combobox.Option>)
+
+ANTI-PATTERNS:
+  \u2717 <Combobox><div><Combobox.Option/></div></Combobox> \u2014 Option must be a direct child
+  \u2717 Same value on two options \u2192 dev warning + silent drop; pick unique values
+  \u2717 Putting label text inside <Combobox.OptionDescription> \u2014 that slot is the secondary line below the label`
+);
+var comboboxOptionDescriptionPropsSchema = zod.z.object({
+  children: zod.z.any().optional().describe("Secondary text below the label (ReactNode)."),
+  className: zod.z.string().optional().describe("Class for the description node.")
+}).describe(
+  'Secondary text shown below an option label. Use for hints like "Republic of Korea" beneath "\uD55C\uAD6D". Excluded from textValue-based search.'
+);
+var comboboxOptionMetaPropsSchema = zod.z.object({
+  children: zod.z.any().optional().describe("Right-aligned meta content (price, badge, shortcut, etc.)."),
+  className: zod.z.string().optional().describe("Class for the meta slot.")
+}).describe(
+  "Right-aligned slot inside an option. Use for prices, keyboard shortcuts, version tags, status badges. Excluded from textValue-based search."
+);
 var comboboxPropsSchema = zod.z.object({
-  options: zod.z.any().describe("Available options array (ComboboxOption[], required)"),
+  children: zod.z.any().describe(
+    "<Combobox.Option> elements (required). Other children are ignored with a dev-mode warning. Async-search consumers swap this list as `onSearch` results arrive."
+  ),
   value: zod.z.any().optional().describe("Selected value. string for single, string[] for multiple"),
   defaultValue: zod.z.any().optional().describe("Initial value (uncontrolled)"),
   onValueChange: zod.z.any().optional().describe("Value change callback. (value: string | string[]) => void"),
   multiple: zod.z.boolean().default(false).describe("Multi-select mode. Selected values shown as chips inside input"),
-  onSearch: zod.z.any().optional().describe("Async search callback. (query: string) => void. Triggers external data fetching with debounce"),
+  onSearch: zod.z.any().optional().describe("Async search callback. (query: string) => void. Triggers external data fetching with debounce. When set, the built-in client filter is disabled \u2014 render whatever <Combobox.Option> children match the latest results."),
   searchDebounce: zod.z.number().default(250).describe("Debounce delay (ms) before onSearch fires"),
-  loading: zod.z.boolean().default(false).describe("Externally-controlled loading state. Shows spinner in input suffix"),
-  filter: zod.z.any().optional().describe("Custom client-side filter. (option, query) => boolean. Default: case-insensitive label includes match"),
+  loading: zod.z.boolean().default(false).describe("Externally-controlled loading state. Shows spinner in input suffix and a status row inside the popover."),
+  filter: zod.z.any().optional().describe("Custom client-side filter. (option: { value, textValue, disabled }, query: string) => boolean. Default: case-insensitive textValue includes match. Ignored when onSearch is set."),
   placeholder: zod.z.string().optional().describe("Input placeholder"),
   emptyMessage: zod.z.any().optional().describe('Message when no options match (string | ReactNode). Default: "\uAC80\uC0C9 \uACB0\uACFC \uC5C6\uC74C"'),
   loadingMessage: zod.z.any().optional().describe('Message during loading state inside popover (string | ReactNode). Default: "\uAC80\uC0C9 \uC911\u2026"'),
@@ -196,7 +231,7 @@ var comboboxPropsSchema = zod.z.object({
   className: zod.z.string().optional().describe("Wrapper className"),
   popoverClassName: zod.z.string().optional().describe("Popover content className")
 }).describe(
-  `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:
   \u2022 Options \u2265 7, OR labels are long, OR search/filter is needed \u2192 Combobox (not Select)
@@ -204,8 +239,29 @@ WHEN TO USE:
   \u2022 Async data from server \u2192 set onSearch + loading
 For \u22647 simple options use Select. For free-text tags use TagInput.
 
+COMPOUND API:
+  <Combobox value={v} onValueChange={setV} placeholder="\u2026">
+    <Combobox.Option value="kr">\uD55C\uAD6D</Combobox.Option>
+    <Combobox.Option value="jp" disabled>
+      \uC77C\uBCF8
+      <Combobox.OptionDescription>\uD488\uC808</Combobox.OptionDescription>
+      <Combobox.OptionMeta>JP</Combobox.OptionMeta>
+    </Combobox.Option>
+  </Combobox>
+
+  \u2022 <Combobox.Option> requires unique \`value\` (dev mode warns on duplicates and drops the duplicate)
+  \u2022 <Combobox.OptionDescription> = secondary line under label
+  \u2022 <Combobox.OptionMeta> = right-aligned slot (price, shortcut, badge)
+  \u2022 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>
   \u2014 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 \u2014 do not add custom keydown handlers.
@@ -213,6 +269,9 @@ IME (Korean/Japanese/Chinese): Enter during composition is ignored automatically
 ANTI-PATTERNS:
   \u2717 <Select> with 20 options \u2192 <Combobox>
   \u2717 Manual <input> + dropdown div + filter logic \u2192 <Combobox>
+  \u2717 Passing options through a prop array (legacy API removed) \u2192 use <Combobox.Option> children
+  \u2717 Wrapping options in extra elements (<div><Combobox.Option/></div>) \u2192 keep them as direct children
+  \u2717 Same \`value\` on two <Combobox.Option> \u2014 duplicates are warned + dropped in dev mode
   \u2717 Setting value externally to clear input mid-typing \u2192 use onValueChange instead`
 );
 var dropdownMenuItemSchema = zod.z.object({
@@ -1611,7 +1670,9 @@ exports.carouselSlidePropsSchema = carouselSlidePropsSchema;
 exports.checkBoxPropsSchema = checkBoxPropsSchema;
 exports.chipPropsSchema = chipPropsSchema;
 exports.clientOnlyPropsSchema = clientOnlyPropsSchema;
-exports.comboboxOptionSchema = comboboxOptionSchema;
+exports.comboboxOptionDescriptionPropsSchema = comboboxOptionDescriptionPropsSchema;
+exports.comboboxOptionMetaPropsSchema = comboboxOptionMetaPropsSchema;
+exports.comboboxOptionPropsSchema = comboboxOptionPropsSchema;
 exports.comboboxPropsSchema = comboboxPropsSchema;
 exports.countdownPropsSchema = countdownPropsSchema;
 exports.counterPropsSchema = counterPropsSchema;

package/dist/schemas.mjs

@@ -165,22 +165,57 @@ var selectItemPropsSchema = z.object({
   disabled: z.boolean().optional().describe("Disabled"),
   className: z.string().optional().describe("Style override")
 }).describe("Individual option within Select.");
-var comboboxOptionSchema = z.object({
-  value: z.string().describe("Option value (unique key)"),
-  label: z.any().describe("Display label (string | ReactNode)"),
-  description: z.any().optional().describe("Secondary text below label (ReactNode)"),
-  disabled: z.boolean().optional().describe("Disabled option")
-}).describe("Single Combobox option.");
+var comboboxOptionPropsSchema = z.object({
+  value: z.string().describe(
+    "Unique value (string, required). Duplicate values within one Combobox produce a dev-mode console.error and the duplicate option is dropped."
+  ),
+  disabled: z.boolean().optional().describe(
+    "Disable selection. Skipped by keyboard navigation (Arrow Up/Down, Home/End)."
+  ),
+  textValue: z.string().optional().describe(
+    '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 \uC0AC\uACFC fruit").'
+  ),
+  className: z.string().optional().describe('Class merged onto the rendered <div role="option">.'),
+  children: z.any().optional().describe(
+    "Label content + optional <Combobox.OptionDescription> / <Combobox.OptionMeta> slots."
+  )
+}).describe(
+  `Single Combobox option. Direct child of <Combobox> only.
+
+WHEN TO USE:
+  \u2022 One per selectable item; \`value\` MUST be unique within the Combobox
+  \u2022 Wrap rich content (icons, badges) directly as children \u2014 no escape hatch needed
+  \u2022 Use textValue when label is non-text (e.g. <Combobox.Option value="apple" textValue="\uC0AC\uACFC apple">\u{1F34E}</Combobox.Option>)
+
+ANTI-PATTERNS:
+  \u2717 <Combobox><div><Combobox.Option/></div></Combobox> \u2014 Option must be a direct child
+  \u2717 Same value on two options \u2192 dev warning + silent drop; pick unique values
+  \u2717 Putting label text inside <Combobox.OptionDescription> \u2014 that slot is the secondary line below the label`
+);
+var comboboxOptionDescriptionPropsSchema = z.object({
+  children: z.any().optional().describe("Secondary text below the label (ReactNode)."),
+  className: z.string().optional().describe("Class for the description node.")
+}).describe(
+  'Secondary text shown below an option label. Use for hints like "Republic of Korea" beneath "\uD55C\uAD6D". Excluded from textValue-based search.'
+);
+var comboboxOptionMetaPropsSchema = z.object({
+  children: z.any().optional().describe("Right-aligned meta content (price, badge, shortcut, etc.)."),
+  className: z.string().optional().describe("Class for the meta slot.")
+}).describe(
+  "Right-aligned slot inside an option. Use for prices, keyboard shortcuts, version tags, status badges. Excluded from textValue-based search."
+);
 var comboboxPropsSchema = z.object({
-  options: z.any().describe("Available options array (ComboboxOption[], required)"),
+  children: z.any().describe(
+    "<Combobox.Option> elements (required). Other children are ignored with a dev-mode warning. Async-search consumers swap this list as `onSearch` results arrive."
+  ),
   value: z.any().optional().describe("Selected value. string for single, string[] for multiple"),
   defaultValue: z.any().optional().describe("Initial value (uncontrolled)"),
   onValueChange: z.any().optional().describe("Value change callback. (value: string | string[]) => void"),
   multiple: z.boolean().default(false).describe("Multi-select mode. Selected values shown as chips inside input"),
-  onSearch: z.any().optional().describe("Async search callback. (query: string) => void. Triggers external data fetching with debounce"),
+  onSearch: z.any().optional().describe("Async search callback. (query: string) => void. Triggers external data fetching with debounce. When set, the built-in client filter is disabled \u2014 render whatever <Combobox.Option> children match the latest results."),
   searchDebounce: z.number().default(250).describe("Debounce delay (ms) before onSearch fires"),
-  loading: z.boolean().default(false).describe("Externally-controlled loading state. Shows spinner in input suffix"),
-  filter: z.any().optional().describe("Custom client-side filter. (option, query) => boolean. Default: case-insensitive label includes match"),
+  loading: z.boolean().default(false).describe("Externally-controlled loading state. Shows spinner in input suffix and a status row inside the popover."),
+  filter: z.any().optional().describe("Custom client-side filter. (option: { value, textValue, disabled }, query: string) => boolean. Default: case-insensitive textValue includes match. Ignored when onSearch is set."),
   placeholder: z.string().optional().describe("Input placeholder"),
   emptyMessage: z.any().optional().describe('Message when no options match (string | ReactNode). Default: "\uAC80\uC0C9 \uACB0\uACFC \uC5C6\uC74C"'),
   loadingMessage: z.any().optional().describe('Message during loading state inside popover (string | ReactNode). Default: "\uAC80\uC0C9 \uC911\u2026"'),
@@ -194,7 +229,7 @@ var comboboxPropsSchema = z.object({
   className: z.string().optional().describe("Wrapper className"),
   popoverClassName: z.string().optional().describe("Popover content className")
 }).describe(
-  `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:
   \u2022 Options \u2265 7, OR labels are long, OR search/filter is needed \u2192 Combobox (not Select)
@@ -202,8 +237,29 @@ WHEN TO USE:
   \u2022 Async data from server \u2192 set onSearch + loading
 For \u22647 simple options use Select. For free-text tags use TagInput.
 
+COMPOUND API:
+  <Combobox value={v} onValueChange={setV} placeholder="\u2026">
+    <Combobox.Option value="kr">\uD55C\uAD6D</Combobox.Option>
+    <Combobox.Option value="jp" disabled>
+      \uC77C\uBCF8
+      <Combobox.OptionDescription>\uD488\uC808</Combobox.OptionDescription>
+      <Combobox.OptionMeta>JP</Combobox.OptionMeta>
+    </Combobox.Option>
+  </Combobox>
+
+  \u2022 <Combobox.Option> requires unique \`value\` (dev mode warns on duplicates and drops the duplicate)
+  \u2022 <Combobox.OptionDescription> = secondary line under label
+  \u2022 <Combobox.OptionMeta> = right-aligned slot (price, shortcut, badge)
+  \u2022 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>
   \u2014 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 \u2014 do not add custom keydown handlers.
@@ -211,6 +267,9 @@ IME (Korean/Japanese/Chinese): Enter during composition is ignored automatically
 ANTI-PATTERNS:
   \u2717 <Select> with 20 options \u2192 <Combobox>
   \u2717 Manual <input> + dropdown div + filter logic \u2192 <Combobox>
+  \u2717 Passing options through a prop array (legacy API removed) \u2192 use <Combobox.Option> children
+  \u2717 Wrapping options in extra elements (<div><Combobox.Option/></div>) \u2192 keep them as direct children
+  \u2717 Same \`value\` on two <Combobox.Option> \u2014 duplicates are warned + dropped in dev mode
   \u2717 Setting value externally to clear input mid-typing \u2192 use onValueChange instead`
 );
 var dropdownMenuItemSchema = z.object({
@@ -1596,4 +1655,4 @@ ANTI-PATTERNS:
   \u2717 Storing image as data-URL value (use File via onChange and upload to server)`
 );
 
-export { accordionPropsSchema, alertPropsSchema, avatarPropsSchema, badgePropsSchema, breadcrumbPropsSchema, buttonPropsSchema, carouselButtonPropsSchema, carouselDotsPropsSchema, carouselPropsSchema, carouselSlidePropsSchema, checkBoxPropsSchema, chipPropsSchema, clientOnlyPropsSchema, comboboxOptionSchema, comboboxPropsSchema, countdownPropsSchema, counterPropsSchema, dataGridPropsSchema, dataListPropsSchema, datePickerPropsSchema, dividerPropsSchema, drawerClosePropsSchema, drawerContentPropsSchema, drawerDescriptionPropsSchema, drawerPropsSchema, drawerTitlePropsSchema, drawerTriggerPropsSchema, dropdownMenuPropsSchema, ellipsisPropsSchema, emptyStatePropsSchema, errorBoundaryPropsSchema, imageUploadPropsSchema, infiniteScrollPropsSchema, marqueePropsSchema, modalCallSchema, modalTemplatePropsSchema, numberInputPropsSchema, nxImagePropsSchema, paginationPropsSchema, popoverPropsSchema, priceInputPropsSchema, progressPropsSchema, radioGroupPropsSchema, radioItemPropsSchema, selectItemPropsSchema, selectPropsSchema, skeletonPropsSchema, sliderPropsSchema, spinnerPropsSchema, stepperPropsSchema, switchPropsSchema, tabPropsSchema, tablePropsSchema, tableRowPropsSchema, tagInputPropsSchema, tdColumnPropsSchema, textAreaPropsSchema, textInputPropsSchema, toastOptionsSchema, toasterPropsSchema, toggleGroupPropsSchema, tooltipPropsSchema, virtualGridPropsSchema, virtualListPropsSchema };
+export { accordionPropsSchema, alertPropsSchema, avatarPropsSchema, badgePropsSchema, breadcrumbPropsSchema, buttonPropsSchema, carouselButtonPropsSchema, carouselDotsPropsSchema, carouselPropsSchema, carouselSlidePropsSchema, checkBoxPropsSchema, chipPropsSchema, clientOnlyPropsSchema, comboboxOptionDescriptionPropsSchema, comboboxOptionMetaPropsSchema, comboboxOptionPropsSchema, comboboxPropsSchema, countdownPropsSchema, counterPropsSchema, dataGridPropsSchema, dataListPropsSchema, datePickerPropsSchema, dividerPropsSchema, drawerClosePropsSchema, drawerContentPropsSchema, drawerDescriptionPropsSchema, drawerPropsSchema, drawerTitlePropsSchema, drawerTriggerPropsSchema, dropdownMenuPropsSchema, ellipsisPropsSchema, emptyStatePropsSchema, errorBoundaryPropsSchema, imageUploadPropsSchema, infiniteScrollPropsSchema, marqueePropsSchema, modalCallSchema, modalTemplatePropsSchema, numberInputPropsSchema, nxImagePropsSchema, paginationPropsSchema, popoverPropsSchema, priceInputPropsSchema, progressPropsSchema, radioGroupPropsSchema, radioItemPropsSchema, selectItemPropsSchema, selectPropsSchema, skeletonPropsSchema, sliderPropsSchema, spinnerPropsSchema, stepperPropsSchema, switchPropsSchema, tabPropsSchema, tablePropsSchema, tableRowPropsSchema, tagInputPropsSchema, tdColumnPropsSchema, textAreaPropsSchema, textInputPropsSchema, toastOptionsSchema, toasterPropsSchema, toggleGroupPropsSchema, tooltipPropsSchema, virtualGridPropsSchema, virtualListPropsSchema };