@nexus-cross/design-system 1.0.13 → 1.1.0

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

@@ -1 +1 @@
-{"version":3,"file":"accordion.d.ts","sourceRoot":"","sources":["../../src/schemas/accordion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmB2C,CAAC"}
+{"version":3,"file":"accordion.d.ts","sourceRoot":"","sources":["../../src/schemas/accordion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmC9B,CAAC"}

package/dist/schemas/accordion.json

@@ -94,7 +94,7 @@
         "items"
       ],
       "additionalProperties": false,
-      "description": "Accordion. Supports both items array and composable patterns."
+      "description": "Accordion — collapsible content sections (FAQ, settings groups).\n\nWHEN TO USE:\n  • FAQ, help docs, settings groups\n  • Long page where each section is independently scannable\n  • Hidden critical info — DO NOT bury what users always need\n  • Tab-like content switching → Tab (Accordion is for stacked, not exclusive)\n\ntype=\"single\" + collapsible=true → all-closed allowed (recommended for FAQ).\ntype=\"multiple\" → multiple sections open at once.\n\nANTI-PATTERNS:\n  ✗ Hiding the page's primary content inside collapsed Accordion\n  ✗ Single-section Accordion (just show the content)\n  ✗ Custom toggle div + state — use Accordion (gets a11y, keyboard nav)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"alert.d.ts","sourceRoot":"","sources":["../../src/schemas/alert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAcoD,CAAC"}
+{"version":3,"file":"alert.d.ts","sourceRoot":"","sources":["../../src/schemas/alert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6B1B,CAAC"}

package/dist/schemas/alert.json

@@ -42,7 +42,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Alert / Banner. Inline notification with icon, title, description."
+      "description": "Alert — persistent inline notification (banner). Auto icon by variant.\n\nWHEN TO USE:\n  • In-page status: form errors, server warnings, info banners, success confirmation\n  • Transient toast/snackbar → use a toast library, NOT Alert\n  • Modal-blocking error → Modal with semantic=\"danger\"\n  • Inline form field error → use error/description prop on TextInput / Select / etc.\n\nvariant maps to semantic colors. closable=true gives users dismiss control. action prop reserved for inline buttons (e.g. \"Retry\").\n\nANTI-PATTERNS:\n  ✗ Stacking 5 alerts at top of page (use one with summary)\n  ✗ Critical destructive action confirmation in Alert → Modal\n  ✗ Wrapping <div className=\"bg-red-100\"> manually → Alert (a11y role + tokens)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../../src/schemas/avatar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBqC,CAAC"}
+{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../../src/schemas/avatar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgC3B,CAAC"}

package/dist/schemas/avatar.json

@@ -48,7 +48,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Avatar. Supports image, fallback text, and children."
+      "description": "Avatar — user/entity profile image with text fallback.\n\nWHEN TO USE:\n  • User profiles, comment authors, team member lists, message sender icons\n  • Image fails / not provided → fallback (initials or icon) shown automatically\n  • Need optimized image (Next.js) → pass <Image> via children, omit src\n  • Larger illustration / logo → use NxImage instead\n\nshape=\"square\" for organization/team logos; \"circle\" for people (default).\n\nANTI-PATTERNS:\n  ✗ <img> + manual fallback handling → Avatar (handles error)\n  ✗ Avatar without alt for screen readers (always set alt or aria-label)\n  ✗ Mixing avatar sizes inconsistently in a list — pick one size"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../src/schemas/badge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAesD,CAAC"}
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../src/schemas/badge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+B1B,CAAC"}

package/dist/schemas/badge.json

@@ -69,7 +69,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Badge indicator. Dot or count display. Wraps children when provided."
+      "description": "Badge — small status / count indicator overlaid on an anchor (icon, avatar, button).\n\nWHEN TO USE:\n  • Notification count on bell icon\n  • Unread message count on inbox tab\n  • Status dot (online/offline) → dot=true\n  • Status label with text (e.g. \"PRO\", \"NEW\") → Chip variant=\"accent\"\n  • Removable filter token → Chip with onClose\n\ncount={0} hides badge by default; pass showZero=true to keep visible.\n\nANTI-PATTERNS:\n  ✗ Using Badge as standalone label without anchor → Chip\n  ✗ count > 999 without max → ugly layout; default max=99 (\"99+\")\n  ✗ Multiple badges on same anchor (visual noise)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"breadcrumb.d.ts","sourceRoot":"","sources":["../../src/schemas/breadcrumb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,yBAAyB;;;;;;;;;EAKoE,CAAC;AAE3G,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EAW/B,CAAC"}
+{"version":3,"file":"breadcrumb.d.ts","sourceRoot":"","sources":["../../src/schemas/breadcrumb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,yBAAyB;;;;;;;;;EAKoE,CAAC;AAE3G,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EAuB/B,CAAC"}

package/dist/schemas/breadcrumb.json

@@ -20,7 +20,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Breadcrumb navigation (compound component pattern). Use <Breadcrumb.Item> children instead of items array. Each Item can wrap arbitrary ReactNode (Link, Select, plain text, etc.)."
+      "description": "Breadcrumb — hierarchical location navigation (Home > Settings > Profile).\n\nWHEN TO USE:\n  • Multi-level information architecture (>=3 levels deep)\n  • Hierarchical category drill-down (file system, taxonomy)\n  • Step-based linear flow → Stepper (not Breadcrumb)\n  • Tab switching → Tab\n  • Single-level navigation → page title alone\n\nCompound pattern: use <Breadcrumb.Item> children. Each Item wraps any ReactNode (Link, Select, plain text). Use maxItems for long paths (auto-collapse with \"…\").\n\nANTI-PATTERNS:\n  ✗ Breadcrumb with 1 level — just show page title\n  ✗ Breadcrumb with > 6 visible items → set maxItems\n  ✗ Last item as a link (it's the current page; should be plain text)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"button.d.ts","sourceRoot":"","sources":["../../src/schemas/button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuC3B,CAAA"}
+{"version":3,"file":"button.d.ts","sourceRoot":"","sources":["../../src/schemas/button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiD3B,CAAA"}

package/dist/schemas/button.json

@@ -82,7 +82,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Interactive button. semantic(color) x variant(style) 2-axis system. Rendering element changeable via asChild."
+      "description": "Interactive button (always prefer over native <button>).\n\nWHEN TO USE: any clickable action — submit, navigate (with asChild), open modal, trigger menu.\n2-axis: semantic (color intent) × variant (visual weight). Use semantic=\"primary\" for the page's main CTA, \"danger\" for destructive actions, \"secondary\" for sub actions, \"normal\" for neutral.\n\nANTI-PATTERNS:\n  ✗ <button className=\"bg-blue-500\"> → <Button semantic=\"primary\">\n  ✗ <a className=\"...\"> styled as button → <Button asChild><a href=\"...\"/></Button>\n  ✗ Mixing variants randomly within one row — pick one per visual hierarchy level\n  ✗ Using primary + contained for every button → only ONE primary CTA per view\n  ✗ <Button className=\"!bg-red-500\"> → <Button semantic=\"danger\"> (no !important)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["../../src/schemas/carousel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;EAa7B,CAAC;AAEJ,eAAO,MAAM,wBAAwB;;;;;;;;;EAKe,CAAC;AAErD,eAAO,MAAM,yBAAyB;;;;;;;;;EAKuC,CAAC;AAE9E,eAAO,MAAM,uBAAuB;;;;;;EAIc,CAAC"}
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["../../src/schemas/carousel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;EA0B7B,CAAC;AAEJ,eAAO,MAAM,wBAAwB;;;;;;;;;EAKe,CAAC;AAErD,eAAO,MAAM,yBAAyB;;;;;;;;;EAKuC,CAAC;AAE9E,eAAO,MAAM,uBAAuB;;;;;;EAIc,CAAC"}

package/dist/schemas/carousel.json

@@ -25,7 +25,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Carousel. Based on Embla Carousel. Sub-components: CarouselSlide, CarouselPrev, CarouselNext, CarouselDots."
+      "description": "Carousel — horizontal slide gallery. Based on Embla Carousel. Compound: CarouselSlide, CarouselPrev/Next, CarouselDots.\n\nWHEN TO USE:\n  • Hero banners, image gallery, product showcase\n  • Multi-card horizontal scroll with snap behavior\n  • Vertical scrolling list → Marquee or VirtualList (not Carousel)\n  • Critical content that must always be visible — Carousel hides slides\n\nopts={{ loop: true, align: 'start' }} for endless loop. Add Embla autoplay plugin for auto-advance.\n\nANTI-PATTERNS:\n  ✗ Critical CTA inside non-first slide (users might never scroll)\n  ✗ Auto-advance without pause-on-hover (a11y)\n  ✗ Manual scroll-snap div → Carousel (gets keyboard nav, indicators)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/checkBox.json

@@ -68,7 +68,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Checkbox. Native input-based, supports square/round shapes."
+      "description": "Checkbox for multi-select form fields. Native input-based, supports square/round shapes.\n\nWHEN TO USE:\n  • Form field with multiple independent options (T&C agreements, multi-select filters submitted later)\n  • Tri-state (parent-child selection) — use indeterminate prop\n  • Single binary that takes effect immediately → Switch instead\n  • Many options with search → Combobox (multiple)\n\nINDETERMINATE: set indeterminate=true when some children are checked, others not. aria-checked becomes \"mixed\" automatically.\n\nANTI-PATTERNS:\n  ✗ <CheckBox> for \"Enable dark mode\" toggle → <Switch>\n  ✗ Native <input type=\"checkbox\"> + manual styling → <CheckBox>\n  ✗ Forgetting indeterminate for \"select all\" parent"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"checkbox.d.ts","sourceRoot":"","sources":["../../src/schemas/checkbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoB0C,CAAC"}
+{"version":3,"file":"checkbox.d.ts","sourceRoot":"","sources":["../../src/schemas/checkbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmC7B,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"chip.d.ts","sourceRoot":"","sources":["../../src/schemas/chip.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiB2C,CAAC"}
+{"version":3,"file":"chip.d.ts","sourceRoot":"","sources":["../../src/schemas/chip.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BzB,CAAC"}

package/dist/schemas/chip.json

@@ -48,7 +48,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Chip/tag/badge. Close button displayed via onClose prop."
+      "description": "Chip — small interactive token for filters, tags, removable selections, status labels.\n\nWHEN TO USE:\n  • Filter token / removable selection (set onClose for X button)\n  • Tag/category indicator\n  • Status indicator with color (variant=\"accent\")\n  • Pure count badge → Badge instead\n  • Toggleable filter → ToggleGroup or Chip with onClick + active state\n\nANTI-PATTERNS:\n  ✗ Building dismiss UI manually with custom div + X icon → use onClose prop\n  ✗ Using Chip as a primary CTA → Button\n  ✗ Using Chip for hover-only labels → Tooltip"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/client-only.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-only.d.ts","sourceRoot":"","sources":["../../src/schemas/client-only.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,qBAAqB;;;;;;;;;EAQoD,CAAC"}
+{"version":3,"file":"client-only.d.ts","sourceRoot":"","sources":["../../src/schemas/client-only.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,qBAAqB;;;;;;;;;EAuB/B,CAAC"}

package/dist/schemas/clientOnly.json

@@ -12,7 +12,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Client-only rendering. Prevents hydration mismatch in SSR environments."
+      "description": "ClientOnly — defers children to client-side render, preventing SSR hydration mismatch.\n\nWHEN TO USE:\n  • Wrap components that read window/document/localStorage at render time\n  • Components depending on browser-only APIs (IntersectionObserver eager init, geolocation)\n  • Server-renderable content → DON'T wrap (loses SEO/SSR perf benefits)\n  • Conditional based on data → use proper SSR-safe state instead\n\nPass fallback to avoid layout shift during hydration.\n\nANTI-PATTERNS:\n  ✗ Wrapping the entire page in ClientOnly (defeats SSR)\n  ✗ ClientOnly without fallback for above-the-fold UI (CLS)\n  ✗ Using ClientOnly to \"fix\" any hydration warning — root-cause the mismatch first"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/combobox.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+export declare const comboboxOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodAny;
+    description: z.ZodOptional<z.ZodAny>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    label?: any;
+    description?: any;
+    disabled?: boolean | undefined;
+}, {
+    value: string;
+    label?: any;
+    description?: any;
+    disabled?: boolean | undefined;
+}>;
+export declare const comboboxPropsSchema: z.ZodObject<{
+    options: z.ZodAny;
+    value: z.ZodOptional<z.ZodAny>;
+    defaultValue: z.ZodOptional<z.ZodAny>;
+    onValueChange: z.ZodOptional<z.ZodAny>;
+    multiple: z.ZodDefault<z.ZodBoolean>;
+    onSearch: z.ZodOptional<z.ZodAny>;
+    searchDebounce: z.ZodDefault<z.ZodNumber>;
+    loading: z.ZodDefault<z.ZodBoolean>;
+    filter: z.ZodOptional<z.ZodAny>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    emptyMessage: z.ZodOptional<z.ZodAny>;
+    loadingMessage: z.ZodOptional<z.ZodAny>;
+    size: z.ZodDefault<z.ZodEnum<["md", "lg", "xl"]>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    error: z.ZodOptional<z.ZodBoolean>;
+    clearable: z.ZodDefault<z.ZodBoolean>;
+    autoOpenOnFocus: z.ZodDefault<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodAny>;
+    description: z.ZodOptional<z.ZodAny>;
+    className: z.ZodOptional<z.ZodString>;
+    popoverClassName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    loading: boolean;
+    size: "xl" | "lg" | "md";
+    multiple: boolean;
+    searchDebounce: number;
+    clearable: boolean;
+    autoOpenOnFocus: boolean;
+    className?: string | undefined;
+    error?: boolean | undefined;
+    filter?: any;
+    options?: any;
+    label?: any;
+    description?: any;
+    value?: any;
+    disabled?: boolean | undefined;
+    defaultValue?: any;
+    onValueChange?: any;
+    placeholder?: string | undefined;
+    onSearch?: any;
+    emptyMessage?: any;
+    loadingMessage?: any;
+    popoverClassName?: string | undefined;
+}, {
+    className?: string | undefined;
+    error?: boolean | undefined;
+    filter?: any;
+    options?: any;
+    label?: any;
+    loading?: boolean | undefined;
+    description?: any;
+    value?: any;
+    size?: "xl" | "lg" | "md" | undefined;
+    multiple?: boolean | undefined;
+    disabled?: boolean | undefined;
+    defaultValue?: any;
+    onValueChange?: any;
+    placeholder?: string | undefined;
+    onSearch?: any;
+    searchDebounce?: number | undefined;
+    emptyMessage?: any;
+    loadingMessage?: any;
+    clearable?: boolean | undefined;
+    autoOpenOnFocus?: boolean | undefined;
+    popoverClassName?: string | undefined;
+}>;
+//# sourceMappingURL=combobox.d.ts.map

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

@@ -0,0 +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"}

package/dist/schemas/combobox.json

@@ -0,0 +1,98 @@
+{
+  "$ref": "#/definitions/comboboxPropsSchema",
+  "definitions": {
+    "comboboxPropsSchema": {
+      "type": "object",
+      "properties": {
+        "options": {
+          "description": "Available options array (ComboboxOption[], required)"
+        },
+        "value": {
+          "description": "Selected value. string for single, string[] for multiple"
+        },
+        "defaultValue": {
+          "description": "Initial value (uncontrolled)"
+        },
+        "onValueChange": {
+          "description": "Value change callback. (value: string | string[]) => void"
+        },
+        "multiple": {
+          "type": "boolean",
+          "default": false,
+          "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"
+        },
+        "searchDebounce": {
+          "type": "number",
+          "default": 250,
+          "description": "Debounce delay (ms) before onSearch fires"
+        },
+        "loading": {
+          "type": "boolean",
+          "default": false,
+          "description": "Externally-controlled loading state. Shows spinner in input suffix"
+        },
+        "filter": {
+          "description": "Custom client-side filter. (option, query) => boolean. Default: case-insensitive label includes match"
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "Input placeholder"
+        },
+        "emptyMessage": {
+          "description": "Message when no options match (string | ReactNode). Default: \"검색 결과 없음\""
+        },
+        "loadingMessage": {
+          "description": "Message during loading state inside popover (string | ReactNode). Default: \"검색 중…\""
+        },
+        "size": {
+          "type": "string",
+          "enum": [
+            "md",
+            "lg",
+            "xl"
+          ],
+          "default": "md",
+          "description": "Input size (matches TextInput tokens)"
+        },
+        "disabled": {
+          "type": "boolean",
+          "description": "Disabled"
+        },
+        "error": {
+          "type": "boolean",
+          "description": "Error state"
+        },
+        "clearable": {
+          "type": "boolean",
+          "default": true,
+          "description": "Show clear button when value(s) exist"
+        },
+        "autoOpenOnFocus": {
+          "type": "boolean",
+          "default": true,
+          "description": "Open popover automatically when input gains focus"
+        },
+        "label": {
+          "description": "Field label (ReactNode)"
+        },
+        "description": {
+          "description": "Helper text below input (ReactNode)"
+        },
+        "className": {
+          "type": "string",
+          "description": "Wrapper className"
+        },
+        "popoverClassName": {
+          "type": "string",
+          "description": "Popover content className"
+        }
+      },
+      "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"
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/dist/schemas/comboboxOption.json

@@ -0,0 +1,30 @@
+{
+  "$ref": "#/definitions/comboboxOptionSchema",
+  "definitions": {
+    "comboboxOptionSchema": {
+      "type": "object",
+      "properties": {
+        "value": {
+          "type": "string",
+          "description": "Option value (unique key)"
+        },
+        "label": {
+          "description": "Display label (string | ReactNode)"
+        },
+        "description": {
+          "description": "Secondary text below label (ReactNode)"
+        },
+        "disabled": {
+          "type": "boolean",
+          "description": "Disabled option"
+        }
+      },
+      "required": [
+        "value"
+      ],
+      "additionalProperties": false,
+      "description": "Single Combobox option."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

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

@@ -1 +1 @@
-{"version":3,"file":"countdown.d.ts","sourceRoot":"","sources":["../../src/schemas/countdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBF,CAAC"}
+{"version":3,"file":"countdown.d.ts","sourceRoot":"","sources":["../../src/schemas/countdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiC9B,CAAC"}

package/dist/schemas/countdown.json

@@ -51,7 +51,7 @@
         "endTimestamp"
       ],
       "additionalProperties": false,
-      "description": "Countdown timer."
+      "description": "Countdown — live timer counting down to endTimestamp (Unix ms).\n\nWHEN TO USE:\n  • Sale ends in / event starts in / token claim window\n  • OTP / verification code expiry\n  • Counting up (since X) → not Countdown; use Counter or custom interval\n  • Persistent server time → pass server-synced endTimestamp (not Date.now offset)\n\nshowDays=false for short timers (<24h) to declutter. Use render prop for fully custom layouts.\n\nANTI-PATTERNS:\n  ✗ Countdown without onEnd handler — UI stuck at 0\n  ✗ Countdown across SSR without hydration safety — pass endTimestamp from server\n  ✗ Updating endTimestamp every render — causes jitter"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"counter.d.ts","sourceRoot":"","sources":["../../src/schemas/counter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBO,CAAC"}
+{"version":3,"file":"counter.d.ts","sourceRoot":"","sources":["../../src/schemas/counter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+B5B,CAAC"}

package/dist/schemas/counter.json

@@ -53,7 +53,7 @@
         "endValue"
       ],
       "additionalProperties": false,
-      "description": "Number count animation."
+      "description": "Counter — animated number tick from startValue to endValue.\n\nWHEN TO USE:\n  • Marketing landing — \"10,000+ users\" KPI displays\n  • Stat dashboards (animate when value changes)\n  • Live tickers / real-time data — re-render plain text instead (Counter is one-shot animation)\n  • Currency input / editable number → NumberInput / PriceInput\n\ntriggerOnView=true delays animation until element scrolls into view (good for landing pages).\n\nANTI-PATTERNS:\n  ✗ Counter for values that update frequently — animation queue conflicts\n  ✗ Long duration on critical numbers (users wait to read)\n  ✗ Counter without separator for large numbers (hard to read)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/data-grid.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+export declare const dataGridPropsSchema: z.ZodObject<{
+    list: z.ZodNullable<z.ZodArray<z.ZodAny, "many">>;
+    columns: z.ZodUnion<[z.ZodNumber, z.ZodObject<{
+        base: z.ZodOptional<z.ZodNumber>;
+        sm: z.ZodOptional<z.ZodNumber>;
+        md: z.ZodOptional<z.ZodNumber>;
+        lg: z.ZodOptional<z.ZodNumber>;
+        xl: z.ZodOptional<z.ZodNumber>;
+        '2xl': z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        base?: number | undefined;
+        xl?: number | undefined;
+        lg?: number | undefined;
+        md?: number | undefined;
+        sm?: number | undefined;
+        '2xl'?: number | undefined;
+    }, {
+        base?: number | undefined;
+        xl?: number | undefined;
+        lg?: number | undefined;
+        md?: number | undefined;
+        sm?: number | undefined;
+        '2xl'?: number | undefined;
+    }>]>;
+    gap: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    noDataMessage: z.ZodOptional<z.ZodAny>;
+    errorFallback: z.ZodOptional<z.ZodAny>;
+    loadingElement: z.ZodOptional<z.ZodAny>;
+    skeletonElement: z.ZodOptional<z.ZodAny>;
+    skeletonCount: z.ZodDefault<z.ZodNumber>;
+    loading: z.ZodDefault<z.ZodBoolean>;
+    children: z.ZodAny;
+    className: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    loading: boolean;
+    list: any[] | null;
+    columns: number | {
+        base?: number | undefined;
+        xl?: number | undefined;
+        lg?: number | undefined;
+        md?: number | undefined;
+        sm?: number | undefined;
+        '2xl'?: number | undefined;
+    };
+    skeletonCount: number;
+    gap?: string | number | undefined;
+    className?: string | undefined;
+    children?: any;
+    loadingElement?: any;
+    skeletonElement?: any;
+    noDataMessage?: any;
+    errorFallback?: any;
+}, {
+    list: any[] | null;
+    columns: number | {
+        base?: number | undefined;
+        xl?: number | undefined;
+        lg?: number | undefined;
+        md?: number | undefined;
+        sm?: number | undefined;
+        '2xl'?: number | undefined;
+    };
+    gap?: string | number | undefined;
+    className?: string | undefined;
+    children?: any;
+    loading?: boolean | undefined;
+    loadingElement?: any;
+    skeletonCount?: number | undefined;
+    skeletonElement?: any;
+    noDataMessage?: any;
+    errorFallback?: any;
+}>;
+//# sourceMappingURL=data-grid.d.ts.map

package/dist/schemas/data-grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-grid.d.ts","sourceRoot":"","sources":["../../src/schemas/data-grid.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0D7B,CAAC"}

package/dist/schemas/data-list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-list.d.ts","sourceRoot":"","sources":["../../src/schemas/data-list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqC7B,CAAC"}
+{"version":3,"file":"data-list.d.ts","sourceRoot":"","sources":["../../src/schemas/data-list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmD7B,CAAC"}

package/dist/schemas/dataGrid.json

@@ -0,0 +1,102 @@
+{
+  "$ref": "#/definitions/dataGridPropsSchema",
+  "definitions": {
+    "dataGridPropsSchema": {
+      "type": "object",
+      "properties": {
+        "list": {
+          "anyOf": [
+            {
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Data array to render. null = loading state (required)"
+        },
+        "columns": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "base": {
+                  "type": "number",
+                  "description": "Default column count (mobile-first)"
+                },
+                "sm": {
+                  "type": "number",
+                  "description": ">= 640px"
+                },
+                "md": {
+                  "type": "number",
+                  "description": ">= 768px"
+                },
+                "lg": {
+                  "type": "number",
+                  "description": ">= 1024px"
+                },
+                "xl": {
+                  "type": "number",
+                  "description": ">= 1280px"
+                },
+                "2xl": {
+                  "type": "number",
+                  "description": ">= 1536px"
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "description": "Column count. number = fixed | { base, sm, md, lg, xl, 2xl } = responsive (required)"
+        },
+        "gap": {
+          "type": [
+            "number",
+            "string"
+          ],
+          "description": "Item gap. number = px | string = CSS value"
+        },
+        "noDataMessage": {
+          "description": "Message for empty array (string | ReactElement)"
+        },
+        "errorFallback": {
+          "description": "Fallback on error (ReactNode)"
+        },
+        "loadingElement": {
+          "description": "Custom loading element (default: Spinner)"
+        },
+        "skeletonElement": {
+          "description": "Skeleton element during loading (ReactElement)"
+        },
+        "skeletonCount": {
+          "type": "number",
+          "default": 3,
+          "description": "Skeleton repeat count"
+        },
+        "loading": {
+          "type": "boolean",
+          "default": false,
+          "description": "Force loading state"
+        },
+        "children": {
+          "description": "Item render function: ({ item, index }) => ReactNode (required)"
+        },
+        "className": {
+          "type": "string",
+          "description": "Root element style"
+        }
+      },
+      "required": [
+        "list",
+        "columns"
+      ],
+      "additionalProperties": false,
+      "description": "DataGrid — card grid version of DataList with responsive columns. Built-in ErrorBoundary, loading/skeleton/empty/error states.\n\nWHEN TO USE:\n  • Card grids: products, gallery, team members, posts\n  • Need responsive column count → pass { base: 1, sm: 2, lg: 3, xl: 4 }\n  • Single column / row layout → DataList\n  • Tabular data → table component (not DataGrid)\n  • Huge dataset → VirtualGrid\n\nANTI-PATTERNS:\n  ✗ Tabular data forced into card grid (use a table)\n  ✗ Hardcoded column count for responsive layouts → use responsive object\n  ✗ Manual loading/empty handling → DataGrid does it"
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/dist/schemas/dataList.json

@@ -49,7 +49,7 @@
         "list"
       ],
       "additionalProperties": false,
-      "description": "Data list. Automatically handles loading/skeleton/empty/data states based on list. Built-in ErrorBoundary."
+      "description": "DataList — render-prop list that handles loading / skeleton / empty / error / data in one component. Built-in ErrorBoundary.\n\nWHEN TO USE:\n  • Any async list (<200 items) — feed, comments, dashboard rows\n  • Pass list={null} during loading (auto-shows skeleton/spinner)\n  • Pass list=[] for empty state (auto-shows noDataMessage)\n  • Card grid → DataGrid (same API + columns prop)\n  • Huge dataset → VirtualList\n\nchildren is render fn: ({ item, index }) => ReactNode.\n\nANTI-PATTERNS:\n  ✗ Manual if (loading) {...} else if (!data.length) {...} chains → DataList handles all\n  ✗ DataList without skeletonElement when component shape is known (use Skeleton)\n  ✗ list=undefined (treated as data, not loading) — use null for loading"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/date-picker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date-picker.d.ts","sourceRoot":"","sources":["../../src/schemas/date-picker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAasD,CAAC"}
+{"version":3,"file":"date-picker.d.ts","sourceRoot":"","sources":["../../src/schemas/date-picker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4B/B,CAAC"}

package/dist/schemas/datePicker.json

@@ -49,7 +49,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "DatePicker. Calendar popup for date selection. Based on react-day-picker."
+      "description": "DatePicker — calendar popup for date selection. Based on react-day-picker.\n\nWHEN TO USE:\n  • Single date selection: birthday, due date, appointment\n  • Date range → use two DatePickers with minDate/maxDate cross-bound\n  • Time selection → not yet supported; use TextInput with type=\"time\" + DatePicker combo\n  • Quick relative ranges (Today/Last 7 days) → DropdownMenu of preset Buttons + DatePicker for \"Custom\"\n\nminDate/maxDate disable out-of-range dates. locale=\"ko\" for Korean labels.\n\nANTI-PATTERNS:\n  ✗ Native <input type=\"date\"> for branded UI (inconsistent across browsers) → DatePicker\n  ✗ Free-text date with parsing → DatePicker (consistent UX)\n  ✗ DatePicker without minDate for past-date-invalid fields (e.g. booking)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"