@nexus-cross/design-system 1.1.0 → 2.0.0-beta.1

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 };