@nexus-cross/design-system 1.0.14 → 1.1.1

package/dist/schemas/spinner.json

@@ -27,7 +27,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Loading indicator. SVG-based. Built-in role=\"status\"."
+      "description": "Loading indicator (spinner). SVG-based. role=\"status\" + aria-label built-in.\n\nWHEN TO USE:\n  • Short loads (<1s), inline indicator (button content while submitting)\n  • Long loads with known structure → Skeleton (better perceived performance)\n  • Quantifiable progress → Progress\n  • Page-level loading boundary inside DataList/DataGrid → use their loading prop instead\n\nANTI-PATTERNS:\n  ✗ Custom CSS spinning div → Spinner (a11y + tokens)\n  ✗ Using Spinner where Skeleton fits (long loads with stable layout)\n  ✗ Forgetting aria-label override when meaning differs from \"Loading\""
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

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

package/dist/schemas/stepper.json

@@ -66,7 +66,7 @@
         "steps"
       ],
       "additionalProperties": false,
-      "description": "Stepper. Step-by-step progress indicator."
+      "description": "Stepper — multi-step linear flow indicator (checkout, onboarding, wizard).\n\nWHEN TO USE:\n  • Sequential workflow with finite steps (3-7)\n  • Show user's current position in flow + completed/upcoming steps\n  • Independent navigation between unrelated sections → Tab\n  • Continuous % progress → Progress\n  • Hierarchy / location → Breadcrumb\n\nstatus=\"error\" highlights the current step with danger color when validation fails.\n\nANTI-PATTERNS:\n  ✗ Stepper with 2 steps (use Progress or just navigation)\n  ✗ Stepper with 10+ steps (overwhelming) — chunk into sub-flows\n  ✗ Letting users skip ahead by clicking future steps (only mark completed → current is allowed)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

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

package/dist/schemas/switch.json

@@ -45,7 +45,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Toggle switch. Native checkbox-based, role=\"switch\"."
+      "description": "Toggle switch for immediate on/off binary state. Native checkbox-based, role=\"switch\".\n\nWHEN TO USE:\n  • Setting that takes effect immediately (notifications on/off, dark mode)\n  • Binary state with no submit step\n  • Form field submitted later → CheckBox instead (semantics: checkbox is form data)\n  • Multiple related options → CheckBox group or ToggleGroup (multiple)\n\nANTI-PATTERNS:\n  ✗ <CheckBox> for \"Enable notifications\" toggle → <Switch>\n  ✗ <Switch> inside form requiring submit → <CheckBox>\n  ✗ Wrapping Switch in <label onClick> manually → use label prop or htmlFor pattern"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"tab.d.ts","sourceRoot":"","sources":["../../src/schemas/tab.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBuB,CAAC"}
+{"version":3,"file":"tab.d.ts","sourceRoot":"","sources":["../../src/schemas/tab.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCxB,CAAC"}

package/dist/schemas/tab.json

@@ -82,7 +82,7 @@
         "items"
       ],
       "additionalProperties": false,
-      "description": "Tab navigation. line/pill variants."
+      "description": "Tab navigation — switch between content panels (settings sections, profile views).\n\nWHEN TO USE:\n  • Page area swap where only one panel is visible at a time\n  • Mutually exclusive content with stable section labels\n  • Form field selection → RadioGroup (semantics: not navigation)\n  • Immediate filter/option toggle → ToggleGroup\n  • Stacked collapsible sections → Accordion\n\ndestroyInactive=true unmounts hidden panels (saves memory but loses state).\n\nANTI-PATTERNS:\n  ✗ Tab with 1 item — just render the panel\n  ✗ Tab with 8+ items — consider sub-routing or DropdownMenu\n  ✗ Using Tab for form value selection → RadioGroup\n  ✗ Custom <button> + onClick + state → Tab (a11y, keyboard, focus management)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/schemas/table.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0B1B,CAAC;AAEJ,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;EAUY,CAAC;AAE7C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyCkC,CAAC"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/schemas/table.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwC1B,CAAC;AAEJ,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;EAiB7B,CAAC;AAEJ,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsD7B,CAAC"}

package/dist/schemas/table.json

@@ -68,7 +68,7 @@
         "list"
       ],
       "additionalProperties": false,
-      "description": "Table. Column definitions via TdColumn, row wrapping via TableRow. Built-in sorting/skeleton loading."
+      "description": "Table — tabular data with sortable columns, skeleton/loading/empty states. Compound: TableRow + TdColumn.\n\nWHEN TO USE:\n  • Comparable structured data (financial reports, transaction history, leaderboard)\n  • Sortable per-column → enableSorting on TdColumn\n  • Card-style entities → DataGrid\n  • Single-column read-only list → DataList\n  • Huge dataset (>500 rows) → wrap with VirtualList logic or paginate\n\nlist={null} → loading state. list=[] → noDataMsg. children: ({ item, index }) => <TableRow>...</TableRow>.\n\nANTI-PATTERNS:\n  ✗ Native <table> + manual loading/empty handling → Table component\n  ✗ Forcing card-style data into Table (use DataGrid)\n  ✗ Sorting in client when server pagination is in use → server-side sort"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/tableRow.json

@@ -25,7 +25,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Table row. Used inside Table."
+      "description": "TableRow — a single row inside Table. Wraps TdColumn cells.\n\nWHEN TO USE:\n  • variant=\"accent\" highlights selected/current row\n  • onClick for row-level navigation (e.g. open detail page)\n  • Per-row checkbox/action → place inside a TdColumn child"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/tag-input.d.ts.map

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

package/dist/schemas/tagInput.json

@@ -63,7 +63,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Tag input. Enter key to add, Backspace to delete last tag."
+      "description": "TagInput — free-form multi-value entry (Enter to add, Backspace to remove last).\n\nWHEN TO USE:\n  • Free-form labels: skills, hashtags, email recipients, keywords\n  • Predefined options → Combobox with multi-select (NOT TagInput)\n  • Single value → TextInput\n  • Limited options → Select / RadioGroup / Checkbox\n\nallowDuplicates=false (default) prevents repeats. Use max to cap count.\n\nANTI-PATTERNS:\n  ✗ TagInput for predefined taxonomy → Combobox (controlled options)\n  ✗ TagInput without max for spam-prone fields\n  ✗ Custom comma-split string field → TagInput (proper UX + a11y)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/tdColumn.json

@@ -100,7 +100,7 @@
         "fieldId"
       ],
       "additionalProperties": false,
-      "description": "Table cell/column definition. Used inside TableRow."
+      "description": "TdColumn — table cell. Drives both <th> and <td> for the column. Provides sorting, alignment, overflow handling.\n\nWHEN TO USE:\n  • textOverflow=\"truncate\" (default) for fixed-width columns; \"wrap\" for narrative\n  • align=\"right\" for numeric/currency columns (a11y readability)\n  • enableSorting=true when column is sortable; supply order + handleClickSort for controlled sort\n  • highlightKey to group columns that highlight together on hover\n\nANTI-PATTERNS:\n  ✗ enableSorting without handleClickSort → sort indicator is dead\n  ✗ align=\"left\" for currency/number columns\n  ✗ Mixing text and numeric in one column without consistent align"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/text-area.d.ts.map

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

package/dist/schemas/text-input.d.ts

@@ -42,13 +42,13 @@ export declare const textInputPropsSchema: z.ZodObject<{
     onChange?: any;
     onValueChange?: any;
     placeholder?: string | undefined;
+    clearable?: boolean | undefined;
     autoComplete?: string | undefined;
     maxLength?: number | undefined;
     readOnly?: boolean | undefined;
     prefixIcon?: any;
     suffixIcon?: any;
     showCount?: boolean | undefined;
-    clearable?: boolean | undefined;
 }, {
     name?: string | undefined;
     className?: string | undefined;
@@ -67,12 +67,12 @@ export declare const textInputPropsSchema: z.ZodObject<{
     onChange?: any;
     onValueChange?: any;
     placeholder?: string | undefined;
+    clearable?: boolean | undefined;
     autoComplete?: string | undefined;
     maxLength?: number | undefined;
     readOnly?: boolean | undefined;
     prefixIcon?: any;
     suffixIcon?: any;
     showCount?: boolean | undefined;
-    clearable?: boolean | undefined;
 }>;
 //# sourceMappingURL=text-input.d.ts.map

package/dist/schemas/text-input.d.ts.map

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

package/dist/schemas/textArea.json

@@ -95,7 +95,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Multi-line text input with label, description, character counter, and resize modes."
+      "description": "Multi-line text input. Always prefer over native <textarea>.\n\nWHEN TO USE:\n  • Long-form text — comments, descriptions, memos, bios\n  • Single-line input → TextInput\n  • Numeric → NumberInput\n\nresize=\"auto\" auto-grows with content (great for chat input). resize=\"none\" locks size for fixed UI.\n\nANTI-PATTERNS:\n  ✗ Native <textarea> + custom counter → showCount + maxLength\n  ✗ <TextArea> for short labels — use TextInput (smaller affordance)\n  ✗ Wrapping with custom <label>/<p> → use built-in label/description props (auto a11y binding)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/textInput.json

@@ -100,7 +100,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Text input field. Supports label, description, prefix/suffix icons, clearable, character counter."
+      "description": "Single-line text input (always prefer over native <input type=\"text\">).\n\nWHEN TO USE: any short text — name, email, search, URL, password.\nUse the built-in label/description props instead of wrapping with your own <label>/<p> tags (auto-binds htmlFor/aria-describedby for accessibility).\nFor numeric input use NumberInput; for currency PriceInput; for long text TextArea; for date DatePicker.\n\nANTI-PATTERNS:\n  ✗ <TextInput type=\"number\"> → <NumberInput> (gives unit, step, ↑↓ keys)\n  ✗ <label>Email <input ...></label> + <p>helper</p> → <TextInput label=\"Email\" description=\"helper\">\n  ✗ Custom red border for error → use error prop (auto aria-invalid + token color)\n  ✗ Manual character counter → use showCount + maxLength\n  ✗ Manual clear X button → use clearable prop"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

@@ -1 +1 @@
-{"version":3,"file":"toast.d.ts","sourceRoot":"","sources":["../../src/schemas/toast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4E5B,CAAC;AAEJ,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwD5B,CAAC"}
+{"version":3,"file":"toast.d.ts","sourceRoot":"","sources":["../../src/schemas/toast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyF5B,CAAC;AAEJ,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkE5B,CAAC"}

package/dist/schemas/toastOptions.json

@@ -74,7 +74,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "toast() call options. Used as toast(message, options). Fully customizable via toast.custom(jsx)."
+      "description": "toast() options. Used as toast(message, options) / toast.success / .error / .warning / .info / .promise / .custom(jsx).\n\nWHEN TO USE TOAST:\n  • Transient feedback after user action: \"Saved\", \"Copied\", \"Network error\"\n  • Persistent in-page banner → Alert\n  • Critical destructive confirmation → Modal (toast can be missed)\n  • Form field error → use error/description prop on the input\n\nrichColors=true gives strong success/error/warning/info colors. Use action for \"Undo\" patterns.\n\nANTI-PATTERNS:\n  ✗ Toast for confirmation that user MUST acknowledge → Modal\n  ✗ Stacking many toasts → set visibleToasts on Toaster\n  ✗ Long-form content in toast (toast is for short messages)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/toaster.json

@@ -69,7 +69,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Toaster config. Place once at app root. Display notifications via toast(). Based on sonner."
+      "description": "Toaster — toast container. Mount ONCE at app root. Then call toast() anywhere. Based on sonner.\n\nWHEN TO USE:\n  • Mount in app shell (layout.tsx / _app.tsx) — exactly one instance globally\n  • Set position once here; per-toast position only when needed\n  • Provide visibleToasts cap to avoid stacking\n\nANTI-PATTERNS:\n  ✗ Multiple Toasters across pages — only one global Toaster\n  ✗ Mounting Toaster inside conditional render — toasts vanish on remount\n  ✗ Forgetting Toaster mount — toast() calls do nothing"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/toggle-group.d.ts

@@ -23,15 +23,16 @@ export declare const toggleGroupPropsSchema: z.ZodObject<{
     value: z.ZodOptional<z.ZodAny>;
     defaultValue: z.ZodOptional<z.ZodAny>;
     onValueChange: z.ZodOptional<z.ZodAny>;
-    variant: z.ZodDefault<z.ZodEnum<["default", "primary", "secondary"]>>;
+    variant: z.ZodDefault<z.ZodEnum<["default", "primary", "secondary", "outline"]>>;
     size: z.ZodDefault<z.ZodEnum<["sm", "md", "lg"]>>;
+    fullWidth: z.ZodDefault<z.ZodBoolean>;
     disabled: z.ZodOptional<z.ZodBoolean>;
     required: z.ZodDefault<z.ZodBoolean>;
     className: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "multiple" | "single";
     size: "lg" | "md" | "sm";
-    variant: "primary" | "secondary" | "default";
+    variant: "primary" | "secondary" | "default" | "outline";
     items: {
         value: string;
         className?: string | undefined;
@@ -39,6 +40,7 @@ export declare const toggleGroupPropsSchema: z.ZodObject<{
         icon?: any;
         disabled?: boolean | undefined;
     }[];
+    fullWidth: boolean;
     required: boolean;
     className?: string | undefined;
     value?: any;
@@ -58,9 +60,10 @@ export declare const toggleGroupPropsSchema: z.ZodObject<{
     value?: any;
     size?: "lg" | "md" | "sm" | undefined;
     disabled?: boolean | undefined;
-    variant?: "primary" | "secondary" | "default" | undefined;
+    variant?: "primary" | "secondary" | "default" | "outline" | undefined;
     defaultValue?: any;
     onValueChange?: any;
+    fullWidth?: boolean | undefined;
     required?: boolean | undefined;
 }>;
 //# sourceMappingURL=toggle-group.d.ts.map

package/dist/schemas/toggle-group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toggle-group.d.ts","sourceRoot":"","sources":["../../src/schemas/toggle-group.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAauC,CAAC"}
+{"version":3,"file":"toggle-group.d.ts","sourceRoot":"","sources":["../../src/schemas/toggle-group.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4ChC,CAAC"}

package/dist/schemas/toggleGroup.json

@@ -58,10 +58,11 @@
           "enum": [
             "default",
             "primary",
-            "secondary"
+            "secondary",
+            "outline"
           ],
           "default": "default",
-          "description": "Style variant (default=slider, primary=accent filled, secondary=accent filled)"
+          "description": "Style variant (default=slider, primary/secondary=accent filled, outline=bordered buttons with no background)"
         },
         "size": {
           "type": "string",
@@ -73,6 +74,11 @@
           "default": "md",
           "description": "Size"
         },
+        "fullWidth": {
+          "type": "boolean",
+          "default": false,
+          "description": "Stretch the group to parent width and split items equally"
+        },
         "disabled": {
           "type": "boolean",
           "description": "Disable all items"
@@ -91,7 +97,7 @@
         "items"
       ],
       "additionalProperties": false,
-      "description": "Toggle group / Segment control. Based on Radix ToggleGroup."
+      "description": "Toggle group / Segment control for immediate-effect option selection. Based on Radix ToggleGroup.\n\nWHEN TO USE:\n  • Sort order, view mode (grid/list), filter chips — selection takes effect immediately\n  • Visual comparison important (icons or short labels)\n  • Form field that submits later → RadioGroup or CheckBox instead\n  • Page area switching (settings tabs) → Tab instead\n\nVARIANTS:\n  • default — slider-style background (sleek)\n  • primary / secondary — accent-filled selected state\n  • outline — bordered buttons with no background (button-style toolbar)\n\nfullWidth=true distributes items equally across parent width (use with outline variant for button-row look).\n\ntype=\"single\" requires at least one selection by default (required=true). Set required=false to allow deselection.\n\nANTI-PATTERNS:\n  ✗ Using ToggleGroup for content tabs → Tab\n  ✗ Using ToggleGroup as form field submitted later → RadioGroup (semantics + a11y)\n  ✗ Mixing icons and text labels of different sizes — keep visual rhythm consistent"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

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

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

package/dist/schemas/tooltip.json

@@ -60,7 +60,7 @@
         }
       },
       "additionalProperties": false,
-      "description": "Tooltip. Based on Radix Tooltip. Built-in Provider."
+      "description": "Tooltip — short text hint shown on hover/focus. Based on Radix Tooltip. Provider built-in.\n\nWHEN TO USE:\n  • Brief explanation of an icon button or truncated label\n  • Hover-only, non-interactive content (text only)\n  • Need clickable content inside → Popover (not Tooltip)\n  • Action menu → DropdownMenu\n  • Force user attention → Modal\n\nANTI-PATTERNS:\n  ✗ Buttons/links inside content → use Popover (Tooltip not focusable)\n  ✗ Long paragraphs in tooltip → consider Popover or Drawer\n  ✗ Tooltip on disabled buttons (won't show in some browsers) — wrap in span instead\n  ✗ Critical info only in tooltip — duplicate visible elsewhere for mobile/touch"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/virtual-scroll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"virtual-scroll.d.ts","sourceRoot":"","sources":["../../src/schemas/virtual-scroll.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBkC,CAAC;AAEtE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAekC,CAAC"}
+{"version":3,"file":"virtual-scroll.d.ts","sourceRoot":"","sources":["../../src/schemas/virtual-scroll.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiChC,CAAC;AAEJ,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BhC,CAAC"}

package/dist/schemas/virtualGrid.json

@@ -55,7 +55,7 @@
         "columns"
       ],
       "additionalProperties": false,
-      "description": "Virtual scroll grid. Based on @tanstack/react-virtual."
+      "description": "VirtualGrid — performant grid for huge lists. Based on @tanstack/react-virtual.\n\nWHEN TO USE:\n  • Image gallery / card grid with 200+ items\n  • Fixed column count (responsive via JS — recompute columns on breakpoint)\n  • Small grid → DataGrid (no virtualization, simpler API)\n  • Single-column list → VirtualList\n\nANTI-PATTERNS:\n  ✗ VirtualGrid with <50 items — DataGrid is simpler\n  ✗ Cards with hover-expanding height (breaks virtualization)\n  ✗ Forgetting to recompute columns on resize → visible empty space"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

package/dist/schemas/virtualList.json

@@ -50,7 +50,7 @@
         "items"
       ],
       "additionalProperties": false,
-      "description": "Virtual scroll list. Based on @tanstack/react-virtual."
+      "description": "VirtualList — performant rendering of huge lists (1000+ items). Based on @tanstack/react-virtual.\n\nWHEN TO USE:\n  • Large datasets (>200 rows): chat history, transactions, logs, leaderboard\n  • Stable item height (or measurable per-item via estimateSize fn)\n  • Small list (<100 items) → DataList (much simpler API)\n  • Grid layout → VirtualGrid\n  • Server-side pagination → InfiniteScroll wrapping plain list\n\nestimateSize is critical — wrong values cause scroll jumps. Pair with onEndReached for server pagination.\n\nANTI-PATTERNS:\n  ✗ VirtualList for short lists (DataList is simpler and renders faster)\n  ✗ Variable estimateSize for uniform items — use a single number\n  ✗ Putting interactive overlays inside virtual rows (mounted/unmounted on scroll)"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"