@dreamtree-org/twreact-ui 1.1.72 → 1.1.73

package/dist/index.js

@@ -247,6 +247,22 @@ const Calendar = createLucideIcon$1("Calendar", [
  */
 
 
+const CheckCircle2 = createLucideIcon$1("CheckCircle2", [
+  [
+    "path",
+    {
+      d: "M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z",
+      key: "14v8dr"
+    }
+  ],
+  ["path", { d: "m9 12 2 2 4-4", key: "dzmm74" }]
+]);
+
+/**
+ * lucide-react v0.0.1 - ISC
+ */
+
+
 const CheckCircle = createLucideIcon$1("CheckCircle", [
   ["path", { d: "M22 11.08V12a10 10 0 1 1-5.93-9.14", key: "g774vq" }],
   ["polyline", { points: "22 4 12 14.01 9 11.01", key: "6xbx8j" }]
@@ -657,6 +673,17 @@ const User = createLucideIcon$1("User", [
  */
 
 
+const XCircle = createLucideIcon$1("XCircle", [
+  ["circle", { cx: "12", cy: "12", r: "10", key: "1mglay" }],
+  ["path", { d: "m15 9-6 6", key: "1uzhvr" }],
+  ["path", { d: "m9 9 6 6", key: "z0biqf" }]
+]);
+
+/**
+ * lucide-react v0.0.1 - ISC
+ */
+
+
 const X = createLucideIcon$1("X", [
   ["path", { d: "M18 6 6 18", key: "1bl5f8" }],
   ["path", { d: "m6 6 12 12", key: "d8bk6v" }]
@@ -19220,13 +19247,57 @@ Dialog.Footer = function (_ref6) {
   }));
 };
 
-var _excluded$7 = ["id", "title", "message", "type", "duration", "onClose", "position"];
+var _excluded$7 = ["id", "title", "message", "description", "type", "duration", "onClose", "position", "statusIcon", "actions", "color", "footerNote", "showFooterNote", "portal", "className"];
 function ownKeys$b(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread$b(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys$b(Object(t), true).forEach(function (r) { _defineProperty$4(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys$b(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+var STATUS_CONFIG = {
+  success: {
+    icon: CheckCircle2,
+    iconClass: 'text-emerald-500 dark:text-emerald-400',
+    progressClass: 'bg-emerald-500 dark:bg-emerald-400'
+  },
+  error: {
+    icon: XCircle,
+    iconClass: 'text-rose-500 dark:text-rose-400',
+    progressClass: 'bg-rose-500 dark:bg-rose-400'
+  },
+  warning: {
+    icon: AlertTriangle,
+    iconClass: 'text-amber-500 dark:text-amber-400',
+    progressClass: 'bg-amber-500 dark:bg-amber-400'
+  },
+  info: {
+    icon: Info,
+    iconClass: 'text-sky-500 dark:text-sky-400',
+    progressClass: 'bg-sky-500 dark:bg-sky-400'
+  },
+  "default": {
+    icon: Bell,
+    iconClass: 'text-primary-500 dark:text-primary-400',
+    progressClass: 'bg-primary-500 dark:bg-primary-400'
+  }
+};
+var POSITION_CLASSES = {
+  'top-right': 'top-4 right-4 items-end',
+  'top-left': 'top-4 left-4 items-start',
+  'bottom-right': 'bottom-4 right-4 items-end',
+  'bottom-left': 'bottom-4 left-4 items-start',
+  'top-center': 'top-4 left-1/2 transform -translate-x-1/2 items-center',
+  'bottom-center': 'bottom-4 left-1/2 transform -translate-x-1/2 items-center'
+};
+var STANDALONE_POSITION_CLASSES = {
+  'top-right': 'top-4 right-4',
+  'top-left': 'top-4 left-4',
+  'bottom-right': 'bottom-4 right-4',
+  'bottom-left': 'bottom-4 left-4',
+  'top-center': 'top-4 left-1/2 transform -translate-x-1/2',
+  'bottom-center': 'bottom-4 left-1/2 transform -translate-x-1/2'
+};
 var Toast = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var id = _ref.id,
     title = _ref.title,
     message = _ref.message,
+    description = _ref.description,
     _ref$type = _ref.type,
     type = _ref$type === void 0 ? 'info' : _ref$type,
     _ref$duration = _ref.duration,
@@ -19234,153 +19305,277 @@ var Toast = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
     onClose = _ref.onClose,
     _ref$position = _ref.position,
     position = _ref$position === void 0 ? 'top-right' : _ref$position,
+    statusIcon = _ref.statusIcon,
+    _ref$actions = _ref.actions,
+    actions = _ref$actions === void 0 ? [] : _ref$actions,
+    color = _ref.color,
+    footerNote = _ref.footerNote,
+    _ref$showFooterNote = _ref.showFooterNote,
+    showFooterNote = _ref$showFooterNote === void 0 ? false : _ref$showFooterNote,
+    _ref$portal = _ref.portal,
+    portal = _ref$portal === void 0 ? true : _ref$portal,
+    _ref$className = _ref.className,
+    className = _ref$className === void 0 ? '' : _ref$className,
     props = _objectWithoutProperties$1(_ref, _excluded$7);
   var _useState = React.useState(true),
     _useState2 = _slicedToArray(_useState, 2),
     isVisible = _useState2[0],
     setIsVisible = _useState2[1];
-  React.useEffect(function () {
-    if (duration > 0) {
-      var timer = setTimeout(function () {
-        handleClose();
-      }, duration);
-      return function () {
-        return clearTimeout(timer);
-      };
-    }
-  }, [duration]);
-  var handleClose = function handleClose() {
-    setIsVisible(false);
+  var _useState3 = React.useState(false),
+    _useState4 = _slicedToArray(_useState3, 2),
+    isLeaving = _useState4[0],
+    setIsLeaving = _useState4[1];
+  var _useState5 = React.useState(false),
+    _useState6 = _slicedToArray(_useState5, 2),
+    isPaused = _useState6[0],
+    setIsPaused = _useState6[1];
+  var progressBarRef = React.useRef(null);
+  var timerTextRef = React.useRef(null);
+  var startTimeRef = React.useRef(null);
+  var remainingRef = React.useRef(duration);
+  var timerRef = React.useRef(null);
+  var animFrameRef = React.useRef(null);
+  var handleClose = React.useCallback(function () {
+    if (isLeaving) return;
+    setIsLeaving(true);
     setTimeout(function () {
+      setIsVisible(false);
       onClose === null || onClose === void 0 || onClose(id);
     }, 300);
-  };
-  var icons = {
-    success: jsxRuntime.jsx(CheckCircle, {
-      className: "h-5 w-5 text-success-500"
-    }),
-    error: jsxRuntime.jsx(AlertCircle, {
-      className: "h-5 w-5 text-error-500"
-    }),
-    warning: jsxRuntime.jsx(AlertTriangle, {
-      className: "h-5 w-5 text-warning-500"
-    }),
-    info: jsxRuntime.jsx(Info, {
-      className: "h-5 w-5 text-primary-500"
-    })
-  };
-  var positionClasses = {
-    'top-right': 'top-4 right-4',
-    'top-left': 'top-4 left-4',
-    'bottom-right': 'bottom-4 right-4',
-    'bottom-left': 'bottom-4 left-4',
-    'top-center': 'top-4 left-1/2 transform -translate-x-1/2',
-    'bottom-center': 'bottom-4 left-1/2 transform -translate-x-1/2'
-  };
+  }, [id, onClose, isLeaving]);
+  var handleStopTimer = React.useCallback(function (e) {
+    e === null || e === void 0 || e.stopPropagation();
+    setIsPaused(true);
+    if (timerRef.current) clearTimeout(timerRef.current);
+    if (animFrameRef.current) cancelAnimationFrame(animFrameRef.current);
+  }, []);
+  // Direct DOM-based progress updates to prevent 60 FPS React re-renders and glitches
+  React.useEffect(function () {
+    if (duration <= 0) return;
+    if (isPaused) {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      if (animFrameRef.current) cancelAnimationFrame(animFrameRef.current);
+      return;
+    }
+    startTimeRef.current = Date.now();
+    timerRef.current = setTimeout(function () {
+      handleClose();
+    }, remainingRef.current);
+    var _updateProgress = function updateProgress() {
+      var elapsed = startTimeRef.current ? Date.now() - startTimeRef.current : 0;
+      var currentRemaining = Math.max(0, remainingRef.current - elapsed);
+      var pct = currentRemaining / duration * 100;
+      if (progressBarRef.current) {
+        progressBarRef.current.style.width = "".concat(pct, "%");
+      }
+      if (timerTextRef.current) {
+        var secs = Math.ceil(currentRemaining / 1000);
+        timerTextRef.current.textContent = "This message will close in ".concat(secs, " seconds. ");
+      }
+      if (currentRemaining > 0 && !isPaused) {
+        animFrameRef.current = requestAnimationFrame(_updateProgress);
+      }
+    };
+    animFrameRef.current = requestAnimationFrame(_updateProgress);
+    return function () {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      if (animFrameRef.current) cancelAnimationFrame(animFrameRef.current);
+      if (!isPaused && startTimeRef.current) {
+        var elapsed = Date.now() - startTimeRef.current;
+        remainingRef.current = Math.max(0, remainingRef.current - elapsed);
+      }
+    };
+  }, [duration, isPaused, handleClose]);
   if (!isVisible) return null;
-  return /*#__PURE__*/ReactDOM.createPortal(jsxRuntime.jsx("div", _objectSpread$b(_objectSpread$b({
+  var statusStyle = STATUS_CONFIG[type] || STATUS_CONFIG.info || STATUS_CONFIG["default"];
+  var StatusIconComponent = statusStyle.icon;
+  var bodyText = description || message;
+  var toastContent = jsxRuntime.jsxs("div", _objectSpread$b(_objectSpread$b({
     ref: ref,
-    className: cn$1('fixed z-50 max-w-sm rounded-lg border border-gray-200 bg-white p-4 shadow-lg animate-slide-up', positionClasses[position])
+    onMouseEnter: function onMouseEnter() {
+      return setIsPaused(true);
+    },
+    onMouseLeave: function onMouseLeave() {
+      return setIsPaused(false);
+    },
+    className: cn$1('relative overflow-hidden rounded-xl border border-slate-200/90 bg-white/95 shadow-xl backdrop-blur-md transition-all duration-300', 'dark:border-slate-800/80 dark:bg-[#18181b] dark:text-slate-100 dark:shadow-2xl', 'max-w-md w-full', isLeaving ? 'opacity-0 scale-95 translate-y-1' : 'animate-slide-up opacity-100 scale-100', portal ? ['fixed z-50', STANDALONE_POSITION_CLASSES[position] || STANDALONE_POSITION_CLASSES['top-right']] : '', className)
   }, props), {}, {
-    children: jsxRuntime.jsxs("div", {
-      className: "flex items-start",
-      children: [jsxRuntime.jsx("div", {
-        className: "flex-shrink-0",
-        children: icons[type]
-      }), jsxRuntime.jsxs("div", {
-        className: "ml-3 flex-1",
-        children: [title && jsxRuntime.jsx("h4", {
-          className: "text-sm font-medium text-primary-900",
-          children: title
-        }), message && jsxRuntime.jsx("p", {
-          className: "mt-1 text-sm text-primary-600",
-          children: message
+    children: [jsxRuntime.jsx("div", {
+      className: "p-4",
+      children: jsxRuntime.jsxs("div", {
+        className: "flex items-start gap-3 justify-between",
+        children: [jsxRuntime.jsx("span", {
+          className: "flex-shrink-0 mt-0.5",
+          children: statusIcon ? statusIcon : jsxRuntime.jsx(StatusIconComponent, {
+            className: cn$1('h-5 w-5', statusStyle.iconClass)
+          })
+        }), jsxRuntime.jsxs("div", {
+          className: "flex-1 min-w-0 pr-2",
+          children: [title && jsxRuntime.jsx("h4", {
+            className: "text-sm font-semibold text-slate-900 dark:text-slate-100 leading-snug",
+            children: title
+          }), bodyText && jsxRuntime.jsx("p", {
+            className: "mt-1 text-xs text-slate-600 dark:text-slate-400 leading-relaxed whitespace-pre-line",
+            children: bodyText
+          }), actions && actions.length > 0 && jsxRuntime.jsx("div", {
+            className: "mt-3 flex items-center gap-2 flex-wrap",
+            children: actions.map(function (actItem, idx) {
+              return jsxRuntime.jsx("button", {
+                type: "button",
+                onClick: function onClick(e) {
+                  var _actItem$onClick;
+                  (_actItem$onClick = actItem.onClick) === null || _actItem$onClick === void 0 || _actItem$onClick.call(actItem, e);
+                  if (actItem.dismiss !== false) {
+                    handleClose();
+                  }
+                },
+                className: cn$1('px-3 py-1.5 text-xs font-medium rounded-lg transition-colors border shadow-xs', actItem.variant === 'primary' ? 'bg-primary-600 hover:bg-primary-700 text-white border-primary-600' : 'bg-slate-100 dark:bg-zinc-800/80 text-slate-700 dark:text-zinc-200 border-slate-200 dark:border-zinc-700 hover:bg-slate-200 dark:hover:bg-zinc-700', actItem.className),
+                children: actItem.label
+              }, actItem.id || actItem.label || "act-".concat(idx));
+            })
+          })]
+        }), jsxRuntime.jsx("button", {
+          type: "button",
+          "aria-label": "Close notification",
+          className: "flex-shrink-0 rounded-lg p-1 text-slate-400 hover:text-slate-600 dark:hover:text-slate-200 hover:bg-slate-100 dark:hover:bg-zinc-800/70 transition-colors outline-none focus:ring-2 focus:ring-primary-500",
+          onClick: handleClose,
+          children: jsxRuntime.jsx(X, {
+            className: "h-4 w-4"
+          })
         })]
-      }), jsxRuntime.jsx("button", {
-        type: "button",
-        className: "ml-4 flex-shrink-0 rounded-md p-1 text-primary-400 hover:text-primary-600 hover:bg-gray-100",
-        onClick: handleClose,
-        children: jsxRuntime.jsx(X, {
-          className: "h-4 w-4"
+      })
+    }), (showFooterNote || footerNote) && duration > 0 && jsxRuntime.jsx("div", {
+      className: "px-4 py-2 bg-slate-50 dark:bg-zinc-950/40 border-t border-slate-100 dark:border-zinc-800/50 text-[11px] text-slate-500 dark:text-zinc-400 flex items-center justify-between",
+      children: jsxRuntime.jsx("span", {
+        children: footerNote ? footerNote : jsxRuntime.jsxs(jsxRuntime.Fragment, {
+          children: [jsxRuntime.jsxs("span", {
+            ref: timerTextRef,
+            children: ["This message will close in ", Math.ceil(duration / 1000), " seconds.", ' ']
+          }), jsxRuntime.jsx("button", {
+            type: "button",
+            onClick: handleStopTimer,
+            className: "font-medium text-slate-700 dark:text-zinc-200 hover:underline inline",
+            children: "Click to stop."
+          })]
         })
-      })]
-    })
-  })), document.body);
+      })
+    }), duration > 0 && jsxRuntime.jsx("div", {
+      className: "absolute bottom-0 left-0 right-0 h-0.5 bg-slate-100 dark:bg-zinc-800/80 overflow-hidden rounded-b-xl",
+      children: jsxRuntime.jsx("div", {
+        ref: progressBarRef,
+        className: cn$1('h-full transition-all ease-linear', color ? '' : statusStyle.progressClass),
+        style: {
+          width: '100%',
+          backgroundColor: color || undefined
+        }
+      })
+    })]
+  }));
+  if (portal) {
+    return /*#__PURE__*/ReactDOM.createPortal(toastContent, document.body);
+  }
+  return toastContent;
 });
 Toast.displayName = 'Toast';
-// Toast Container Component
+// Toast Container Component for vertical stacking & scrollable overflow without visible scrollbars
 var ToastContainer = function ToastContainer(_ref2) {
   var _ref2$toasts = _ref2.toasts,
     toasts = _ref2$toasts === void 0 ? [] : _ref2$toasts,
     _ref2$position = _ref2.position,
     position = _ref2$position === void 0 ? 'top-right' : _ref2$position,
-    onRemove = _ref2.onRemove;
-  return jsxRuntime.jsx("div", {
-    className: "fixed z-50 space-y-2",
-    style: _defineProperty$4(_defineProperty$4({}, position.includes('top') ? 'top' : 'bottom', '1rem'), position.includes('right') ? 'right' : position.includes('left') ? 'left' : 'left', position.includes('center') ? '50%' : '1rem'),
-    children: toasts.map(function (toast) {
-      return jsxRuntime.jsx(Toast, _objectSpread$b(_objectSpread$b({}, toast), {}, {
-        position: position,
-        onClose: onRemove
-      }), toast.id);
+    onRemove = _ref2.onRemove,
+    _ref2$className = _ref2.className,
+    className = _ref2$className === void 0 ? '' : _ref2$className;
+  if (!toasts || toasts.length === 0) {
+    return null;
+  }
+  var posClass = POSITION_CLASSES[position] || POSITION_CLASSES['top-right'];
+  return /*#__PURE__*/ReactDOM.createPortal(jsxRuntime.jsx("div", {
+    className: cn$1('fixed z-50 flex flex-col gap-3 max-h-[calc(100vh-2rem)] overflow-y-auto overflow-x-hidden p-2 pointer-events-none', '[scrollbar-width:none] [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden', posClass, className),
+    children: toasts.map(function (t) {
+      return jsxRuntime.jsx("div", {
+        className: "pointer-events-auto w-full max-w-md",
+        children: jsxRuntime.jsx(Toast, _objectSpread$b(_objectSpread$b({}, t), {}, {
+          portal: false,
+          position: position,
+          onClose: onRemove
+        }))
+      }, t.id);
     })
-  });
+  }), document.body);
 };
 // Toast Hook
 var useToast = function useToast() {
-  var _useState3 = React.useState([]),
-    _useState4 = _slicedToArray(_useState3, 2),
-    toasts = _useState4[0],
-    setToasts = _useState4[1];
-  var addToast = function addToast(toast) {
-    var id = Date.now().toString();
+  var _useState7 = React.useState([]),
+    _useState8 = _slicedToArray(_useState7, 2),
+    toasts = _useState8[0],
+    setToasts = _useState8[1];
+  var addToast = React.useCallback(function (toastOptions) {
+    var id = toastOptions.id || "".concat(Date.now(), "-").concat(Math.random().toString(36).slice(2, 7));
+    var newToast = _objectSpread$b(_objectSpread$b({}, toastOptions), {}, {
+      id: id
+    });
     setToasts(function (prev) {
-      return [].concat(_toConsumableArray$1(prev), [_objectSpread$b(_objectSpread$b({}, toast), {}, {
-        id: id
-      })]);
+      return [].concat(_toConsumableArray$1(prev), [newToast]);
     });
-  };
-  var removeToast = function removeToast(id) {
+    return id;
+  }, []);
+  var removeToast = React.useCallback(function (id) {
     setToasts(function (prev) {
-      return prev.filter(function (toast) {
-        return toast.id !== id;
+      return prev.filter(function (t) {
+        return t.id !== id;
       });
     });
+  }, []);
+  var clearToasts = React.useCallback(function () {
+    setToasts([]);
+  }, []);
+  var toast = React.useCallback(function (options) {
+    return addToast(typeof options === 'string' ? {
+      message: options
+    } : options);
+  }, [addToast]);
+  toast.success = function (title, message, options) {
+    return addToast(_objectSpread$b({
+      title: title,
+      message: message,
+      type: 'success'
+    }, _typeof$4(options) === 'object' ? options : {}));
   };
-  var toast = {
-    success: function success(title, message, options) {
-      return addToast(_objectSpread$b({
-        title: title,
-        message: message,
-        type: 'success'
-      }, options));
-    },
-    error: function error(title, message, options) {
-      return addToast(_objectSpread$b({
-        title: title,
-        message: message,
-        type: 'error'
-      }, options));
-    },
-    warning: function warning(title, message, options) {
-      return addToast(_objectSpread$b({
-        title: title,
-        message: message,
-        type: 'warning'
-      }, options));
-    },
-    info: function info(title, message, options) {
-      return addToast(_objectSpread$b({
-        title: title,
-        message: message,
-        type: 'info'
-      }, options));
-    }
+  toast.error = function (title, message, options) {
+    return addToast(_objectSpread$b({
+      title: title,
+      message: message,
+      type: 'error'
+    }, _typeof$4(options) === 'object' ? options : {}));
+  };
+  toast.warning = function (title, message, options) {
+    return addToast(_objectSpread$b({
+      title: title,
+      message: message,
+      type: 'warning'
+    }, _typeof$4(options) === 'object' ? options : {}));
+  };
+  toast.info = function (title, message, options) {
+    return addToast(_objectSpread$b({
+      title: title,
+      message: message,
+      type: 'info'
+    }, _typeof$4(options) === 'object' ? options : {}));
+  };
+  toast["default"] = function (title, message, options) {
+    return addToast(_objectSpread$b({
+      title: title,
+      message: message,
+      type: 'default'
+    }, _typeof$4(options) === 'object' ? options : {}));
   };
   return {
     toast: toast,
     toasts: toasts,
-    removeToast: removeToast
+    removeToast: removeToast,
+    clearToasts: clearToasts,
+    addToast: addToast
   };
 };
 

package/mcp/catalog.snapshot.json

@@ -2611,7 +2611,7 @@
           "useToast"
         ],
         "hasDoc": true,
-        "description": "Toast notification component and container. Use with `ToastContainer` and optional `useToast` (or your own state) to show temporary messages.",
+        "description": "Toast notification component and container. Use with `ToastContainer` and optional `useToast` hook to show temporary notifications with top status header, message body, action buttons, and animated bottom progress bar with hover-pause functionality.",
         "props": [
           {
             "prop": "id",
@@ -2623,25 +2623,49 @@
             "prop": "title",
             "type": "`string`",
             "default": "",
-            "description": "Toast title"
+            "description": "Toast title rendered in header"
           },
           {
             "prop": "message",
             "type": "`string`",
             "default": "",
-            "description": "Toast message"
+            "description": "Toast message body (alias for `description`)"
+          },
+          {
+            "prop": "description",
+            "type": "`string`",
+            "default": "",
+            "description": "Toast body text"
           },
           {
             "prop": "type",
             "type": "`string`",
             "default": "\"info\"",
-            "description": "`success`, `error`, `warning`, `info`"
+            "description": "Toast status type: `success`, `error`, `warning`, `info`, `default`"
           },
           {
             "prop": "duration",
             "type": "`number`",
             "default": "5000",
-            "description": "Auto-close ms (0 = no auto-close)"
+            "description": "Auto-close timer in ms (0 = no auto-close)"
+          },
+          {
+            "prop": "appIcon",
+            "type": "`ReactNode`",
+            "default": "<Sparkles />",
+            "description": "Icon displayed in header next to status icon badge"
+          },
+          {
+            "prop": "statusIcon",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "Custom status icon component (overrides default type badge)"
+          },
+          {
+            "prop": "actions",
+            "type": "`Array`",
+            "default": "[]",
+            "description": "Action button definitions `[{ label, onClick, variant, dismiss }]`"
           },
           {
             "prop": "onClose",
@@ -2653,10 +2677,16 @@
             "prop": "position",
             "type": "`string`",
             "default": "\"topright\"",
-            "description": "Position key for styling"
+            "description": "Position key: `top-right`, `top-left`, `bottom-right`, `bottom-left`, `top-center`, `bottom-center`"
+          },
+          {
+            "prop": "portal",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Whether to render via React Portal (set to `false` when inside `ToastContainer`)"
           }
         ],
-        "examples": "```jsx\nfunction App() {\n  const [toasts, setToasts] = useState([]);\n  const addToast = (toast) => setToasts((prev) => [...prev, { ...toast, id: Date.now() }]);\n  const removeToast = (id) => setToasts((prev) => prev.filter((t) => t.id !== id));\n\n  return (\n    <>\n      <Button onClick={() => addToast({ title: 'Done', message: 'Saved.', type: 'success' })}>\n        Show toast\n      </Button>\n      <ToastContainer toasts={toasts} onRemove={removeToast} position=\"top-right\" />\n    </>\n  );\n}\n```\n\n[← Component overview](README.md)"
+        "examples": "```jsx\nfunction App() {\n  const { toast, toasts, removeToast } = useToast();\n\n  const handleShowToast = () => {\n    toast.info('System Update', 'A new update is available for download.', {\n      duration: 6000,\n      actions: [\n        { label: 'Update Now', variant: 'primary', onClick: () => alert('Updating...') },\n        { label: 'Later', variant: 'secondary', onClick: () => alert('Postponed') },\n      ],\n    });\n  };\n\n  return (\n    <>\n      <Button onClick={handleShowToast}>\n        Show Notification\n      </Button>\n      <ToastContainer toasts={toasts} onRemove={removeToast} position=\"top-right\" />\n    </>\n  );\n}\n```\n\n[← Component overview](README.md)"
       },
       {
         "name": "Alert",
@@ -3201,7 +3231,7 @@
     "Tabs": "# Tabs\n\nTabbed content with list and panels. Use subcomponents: `Tabs.List`, `Tabs.Tab`, `Tabs.Panels`, `Tabs.Panel`. Supports controlled (`index` + `onChange`) or uncontrolled (`defaultIndex`), keyboard navigation, and variants.\n\n## Import\n\n```jsx\nimport { Tabs } from '@dreamtree-org/twreact-ui';\n```\n\n## Props (Tabs root)\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `children` | `ReactNode` | — | Must include `Tabs.List` and `Tabs.Panels`. |\n| `defaultIndex` | `number` | `0` | Uncontrolled initial active tab index. |\n| `index` | `number` | — | Controlled active index. |\n| `onChange` | `(index: number) => void` | — | Called when tab changes. |\n| `orientation` | `\"horizontal\"` \\| `\"vertical\"` | `\"horizontal\"` | Layout direction. |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `\"md\"` | Tab size. |\n| `variant` | `\"line\"` \\| `\"pills\"` \\| `\"unstyled\"` | `\"line\"` | Tab style. |\n| `animated` | `boolean` | `true` | Fade animation on panel change. |\n| `className` | `string` | `\"\"` | Wrapper CSS classes. |\n\n## Usage\n\n```jsx\n<Tabs defaultIndex={0} variant=\"pills\" size=\"md\">\n  <Tabs.List>\n    <Tabs.Tab>Home</Tabs.Tab>\n    <Tabs.Tab>Profile</Tabs.Tab>\n    <Tabs.Tab>Settings</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panels>\n    <Tabs.Panel>Home content</Tabs.Panel>\n    <Tabs.Panel>Profile content</Tabs.Panel>\n    <Tabs.Panel>Settings content</Tabs.Panel>\n  </Tabs.Panels>\n</Tabs>\n```\n\nControlled:\n\n```jsx\nconst [index, setIndex] = useState(0);\n<Tabs index={index} onChange={setIndex}>\n  ...\n</Tabs>\n```\n\n[← Component overview](README.md)\n",
     "TextToSpeech": "# TextToSpeech\n\nText-to-speech using the browser’s Speech Synthesis API. Renders a default \"Speak\" / \"Stop\" button or a custom button via `renderButton`. Toggling speak while playing stops playback.\n\n## Import\n\n```jsx\nimport { TextToSpeech } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `text` | `string` | `\"\"` | Text to speak (used as initial input if component manages input). |\n| `rate` | `number` | `1` | Speech rate (0.1–10). |\n| `pitch` | `number` | `0.5` | Pitch (0–2). |\n| `onSpeak` | `(text: string) => void` | `() => {}` | Called when speech starts (with the text spoken). |\n| `renderButton` | `(props: { onClick, isSpeaking }) => ReactNode` | — | Custom button; receives `onClick` and `isSpeaking`. |\n\n## Behavior\n\n- Component keeps internal `inputText` state initialized from `text`; speaking uses that.\n- Clicking the button toggles: if not speaking, starts `SpeechSynthesisUtterance` with `inputText`; if speaking, calls `speechSynthesis.cancel()` and sets speaking to false.\n- `onSpeak` is called when speech starts.\n\n## Example\n\n```jsx\n<TextToSpeech text=\"Hello, world!\" rate={1} onSpeak={(t) => console.log('Speaking:', t)} />\n\n<TextToSpeech\n  text={content}\n  renderButton={({ onClick, isSpeaking }) => (\n    <Button onClick={onClick}>{isSpeaking ? 'Stop' : 'Play'} audio</Button>\n  )}\n/>\n```\n\n[← Component overview](README.md)\n",
     "ThreeDotPopover": "# ThreeDotPopover\n\nDropdown menu triggered by a three-dot (kebab) button. Use for row actions (Edit, Delete, etc.). Closes on outside click and Escape; optional close on item select.\n\n## Import\n\n```jsx\nimport { ThreeDotPopover } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `Array` | `[]` | Menu items: `{ key, label, icon?, onClick?, disabled?, destructive? }`. `icon` can be component (e.g. `Edit2`). |\n| `trigger` | `ReactNode` | — | Custom trigger; default is three-dot button. |\n| `className` | `string` | `\"\"` | CSS classes for the **default** trigger button (merged via `cn()`). |\n| `wrapperClassName` | `string` | `\"\"` | CSS classes merged (via `cn()`) onto the root container element. |\n| `menuClass` | `string` | `\"\"` | Menu container CSS classes. |\n| `menuItemClass` | `string` | `\"\"` | Each menu item CSS classes. |\n| `closeOnSelect` | `boolean` | `true` | Close menu when an item is selected. |\n| `ariaLabel` | `string` | `\"More options\"` | Trigger button aria-label. |\n\n## Item shape\n\n- `key` (string): Unique key.\n- `label` (string): Display text.\n- `icon` (optional): React component or node.\n- `onClick(item)` (optional): Called when item is clicked.\n- `disabled` (boolean): Disable the item.\n- `destructive` (boolean): Style as destructive (e.g. red for Delete).\n\n## Example\n\n```jsx\nimport { Edit2, Eye, Trash } from 'lucide-react';\n\n<ThreeDotPopover\n  items={[\n    { key: 'edit', label: 'Edit', icon: Edit2, onClick: () => edit(row) },\n    { key: 'view', label: 'View', icon: Eye, onClick: () => view(row) },\n    { key: 'delete', label: 'Delete', destructive: true, onClick: () => remove(row) },\n  ]}\n  closeOnSelect\n/>\n```\n\n## Notes\n\n- Forwards `ref` to the root container element and spreads unknown props\n  (`...rest`) onto it.\n\n[← Component overview](README.md)\n",
-    "Toast": "# Toast\n\nToast notification component and container. Use with `ToastContainer` and optional `useToast` (or your own state) to show temporary messages.\n\n## Import\n\n```jsx\nimport { Toast, ToastContainer, useToast } from '@dreamtree-org/twreact-ui';\n```\n\n## Props (Toast)\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `id` | `string` | — | Unique id (for key/onClose) |\n| `title` | `string` | — | Toast title |\n| `message` | `string` | — | Toast message |\n| `type` | `string` | `\"info\"` | `success`, `error`, `warning`, `info` |\n| `duration` | `number` | `5000` | Auto-close ms (0 = no auto-close) |\n| `onClose` | `function` | — | Called when toast closes |\n| `position` | `string` | `\"top-right\"` | Position key for styling |\n\n## ToastContainer\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `toasts` | `Array` | `[]` | Array of toast objects `{ id, title, message, type, ... }` |\n| `position` | `string` | `\"top-right\"` | Position |\n| `onRemove` | `function` | — | Called when a toast is removed (pass id) |\n\n## Example\n\n```jsx\nfunction App() {\n  const [toasts, setToasts] = useState([]);\n  const addToast = (toast) => setToasts((prev) => [...prev, { ...toast, id: Date.now() }]);\n  const removeToast = (id) => setToasts((prev) => prev.filter((t) => t.id !== id));\n\n  return (\n    <>\n      <Button onClick={() => addToast({ title: 'Done', message: 'Saved.', type: 'success' })}>\n        Show toast\n      </Button>\n      <ToastContainer toasts={toasts} onRemove={removeToast} position=\"top-right\" />\n    </>\n  );\n}\n```\n\n[← Component overview](README.md)\n",
+    "Toast": "# Toast\n\nToast notification component and container. Use with `ToastContainer` and optional `useToast` hook to show temporary notifications with top status header, message body, action buttons, and animated bottom progress bar with hover-pause functionality.\n\n## Import\n\n```jsx\nimport { Toast, ToastContainer, useToast } from '@dreamtree-org/twreact-ui';\n```\n\n## Props (Toast)\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `id` | `string` | — | Unique id (for key/onClose) |\n| `title` | `string` | — | Toast title rendered in header |\n| `message` | `string` | — | Toast message body (alias for `description`) |\n| `description` | `string` | — | Toast body text |\n| `type` | `string` | `\"info\"` | Toast status type: `success`, `error`, `warning`, `info`, `default` |\n| `duration` | `number` | `5000` | Auto-close timer in ms (0 = no auto-close) |\n| `appIcon` | `ReactNode` | `<Sparkles />` | Icon displayed in header next to status icon badge |\n| `statusIcon` | `ReactNode` | — | Custom status icon component (overrides default type badge) |\n| `actions` | `Array` | `[]` | Action button definitions `[{ label, onClick, variant, dismiss }]` |\n| `onClose` | `function` | — | Called when toast closes |\n| `position` | `string` | `\"top-right\"` | Position key: `top-right`, `top-left`, `bottom-right`, `bottom-left`, `top-center`, `bottom-center` |\n| `portal` | `boolean` | `true` | Whether to render via React Portal (set to `false` when inside `ToastContainer`) |\n\n## ToastContainer\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `toasts` | `Array` | `[]` | Array of toast objects `{ id, title, message, description, type, actions, ... }` |\n| `position` | `string` | `\"top-right\"` | Stacking position on screen |\n| `onRemove` | `function` | — | Callback invoked when a toast is dismissed (passes toast `id`) |\n\n## Example\n\n```jsx\nfunction App() {\n  const { toast, toasts, removeToast } = useToast();\n\n  const handleShowToast = () => {\n    toast.info('System Update', 'A new update is available for download.', {\n      duration: 6000,\n      actions: [\n        { label: 'Update Now', variant: 'primary', onClick: () => alert('Updating...') },\n        { label: 'Later', variant: 'secondary', onClick: () => alert('Postponed') },\n      ],\n    });\n  };\n\n  return (\n    <>\n      <Button onClick={handleShowToast}>\n        Show Notification\n      </Button>\n      <ToastContainer toasts={toasts} onRemove={removeToast} position=\"top-right\" />\n    </>\n  );\n}\n```\n\n[← Component overview](README.md)\n\n",
     "Tooltip": "# Tooltip\n\nTooltip shown on hover, focus, or click. Supports placement (auto/top/bottom/left/right), delay, offset, and optional portal. Content can be string or render prop `({ close }) => ReactNode`.\n\n## Import\n\n```jsx\nimport { Tooltip } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `position` | `\"auto\"` \\| `\"top\"` \\| `\"bottom\"` \\| `\"left\"` \\| `\"right\"` | `\"auto\"` | Preferred placement; `auto` flips to fit. |\n| `trigger` | `\"hover\"` \\| `\"click\"` \\| `\"focus\"` \\| `Array` | `\"hover\"` | How tooltip opens. |\n| `content` | `ReactNode` \\| `({ close }) => ReactNode` | — | Tooltip content. |\n| `customTrigger` | `ReactElement` | — | Use instead of children as trigger. |\n| `children` | `ReactNode` | — | Trigger element when customTrigger not used. |\n| `open` | `boolean` | — | Controlled open state. |\n| `defaultOpen` | `boolean` | `false` | Uncontrolled initial open. |\n| `onChange` | `(open: boolean) => void` | — | Called when open state changes. |\n| `delay` | `number` | `80` | Delay in ms before opening (hover). |\n| `offset` | `number` | `8` | Spacing in px between trigger and tooltip. |\n| `textColor` | `string` (hex) | — | Tooltip text color. |\n| `bgColor` | `string` (hex) | `\"#ffffff\"` | Tooltip background color. |\n| `className` | `string` | `\"\"` | Tooltip box CSS classes. |\n| `portal` | `boolean` | `true` | Render tooltip in document.body. |\n| `id` | `string` | — | Tooltip id (auto-generated if omitted). |\n\n## Example\n\n```jsx\n<Tooltip content=\"Save your changes\">\n  <Button>Save</Button>\n</Tooltip>\n\n<Tooltip trigger=\"click\" content={({ close }) => <span>Click to close <button onClick={close}>OK</button></span>}>\n  <span>Click me</span>\n</Tooltip>\n\n<Tooltip position=\"bottom\" delay={200} content=\"Delayed tip\">\n  <Input placeholder=\"Focus me\" />\n</Tooltip>\n```\n\n[← Component overview](README.md)\n"
   },
   "skill": "# Dreamtree UI — AI assistant reference\n\n> Skill installed by `npx @dreamtree-org/twreact-ui init --ai <provider>`.\n> Source of truth: [`@dreamtree-org/twreact-ui`](https://www.npmjs.com/package/@dreamtree-org/twreact-ui).\n> Re-run the installer to refresh this block when the library updates.\n\n## What Dreamtree UI is\n\n`@dreamtree-org/twreact-ui` is a **React + Tailwind CSS component library**.\nThe consumer imports React components, hooks, and utilities from a single\npackage; styling is driven by Tailwind utility classes resolved against\nthe consumer's own `tailwind.config.js`. Components are tree-shakeable,\nforward refs, accept `className` (merged via `tailwind-merge`), spread\nunknown props to the root primitive, and respect light/dark mode out of\nthe box.\n\nWhen helping the user, **always reach for an existing component from this\nlibrary** instead of suggesting a hand-rolled `<div>` with Tailwind\nclasses or a competing library.\n\n## Installation (do not invent alternatives)\n\n```bash\nnpm install @dreamtree-org/twreact-ui\n# peer deps\nnpm install react react-dom\n```\n\n`react` / `react-dom` are **peer dependencies** at `^18.3.1`. React 19\nis not yet supported.\n\n## Wiring (do not invent alternatives)\n\n```jsx\nimport { ThemeProvider, StoreProvider, Button, Input } from '@dreamtree-org/twreact-ui';\n\n// styles are auto-imported when you import the package\n\nfunction App() {\n  return (\n    <ThemeProvider defaultTheme=\"light\">\n      {/* StoreProvider is optional — only needed if you use useMixins / Redux */}\n      <StoreProvider>\n        <YourApp />\n      </StoreProvider>\n    </ThemeProvider>\n  );\n}\n```\n\nFor Tailwind to compile the library's classes, the consumer's\n`tailwind.config.js` `content[]` MUST include the package:\n\n```js\n// consumer's tailwind.config.js\nmodule.exports = {\n  content: [\n    './src/**/*.{js,jsx,ts,tsx}',\n    './node_modules/@dreamtree-org/twreact-ui/dist/**/*.{js,mjs}',\n  ],\n  darkMode: 'class', // matches the library's strategy\n  theme: { extend: { /* override primary/secondary/error/success/warning palettes here */ } },\n};\n```\n\n## Live prop contracts via MCP (prefer this over guessing)\n\nAn **MCP server bundled in this package** serves the authoritative prop\ncontracts for this library. If your client supports the Model Context Protocol,\nwire it up and **query it instead of guessing prop names**:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"dreamtree-ui\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@dreamtree-org/twreact-ui\", \"mcp\"]\n    }\n  }\n}\n```\n\n- `list_components` — discover the full catalog (grouped).\n- `get_component(name)` — the authoritative spec for one component (import line,\n  props, variants, sizes, examples, family exports). **Call this before using a\n  component.** Accepts a family-export name (`useToast` → `Toast`).\n- `search_components(query)` — keyword search by capability.\n\nResources: `dreamtree://skill` (this guide) and `dreamtree://docs/<Component>`.\nPrompt: `compose_ui`. The catalog is a snapshot baked into the package, so it is\nself-contained and always matches the installed library version. The lists below\nare the fallback when the MCP server isn't connected.\n\n## Public surface\n\nThe library exports four kinds of things from `@dreamtree-org/twreact-ui`:\n\n### Components\n\n| Group           | Components                                                                                                                                                                                                                  |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Core**        | `Input`, `Button`, `Select`, `Table`, `Form`, `Accordion`, `Checkbox`, `ColorPicker`, `DatePicker`, `DateRangePicker`, `Loader`, `LocationPicker`, `PriceRangePicker`, `ProgressBar`, `Radio`, `Rate`, `RoundedTag`, `Skeleton`, `Switch`, `Tabs`, `ThreeDotPopover`, `Tooltip`, `SpeechToText`, `TextToSpeech` |\n| **Navigation**  | `Sidebar`, `Navbar`, `FootNav`, `Breadcrumbs`                                                                                                                                                                              |\n| **Feedback**    | `Dialog`, `Toast` (+ `ToastContainer`, `useToast`), `Alert`                                                                                                                                                                |\n| **Utility**     | `Badge`, `Avatar`, `Card`, `Pagination`, `Stepper`, `FileUpload`, `Condition`, `Carousel`                                                                                                                                  |\n\n### Hooks\n\n| Hook            | Purpose                                                                                                                                       |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| `useTheme`      | Read/write the current theme (`light | dark`); pairs with `<ThemeProvider>`. Throws if used outside the provider.                              |\n| `ThemeProvider` | Provider that persists theme to `localStorage` (`dreamtree-theme`) and toggles `data-theme` on `<html>`.                                       |\n| `useApi`        | Thin axios wrapper. Returns `{data, error, loading, sendRequest}`. Accepts `BASE_URL`, `DEFAULT_HEADERS`, `apiMap`.                            |\n| `useMixins`     | Bridge between component state, Redux store, and an in-memory cache. Power-user hook — prefer local React state for new code.                  |\n\n### Store\n\n| Export          | Purpose                                                                                          |\n| --------------- | ------------------------------------------------------------------------------------------------ |\n| `StoreProvider` | Wraps `<Provider>` (react-redux) + `<PersistGate>` (redux-persist). Boots a slice + listener mw. |\n\n### Utils\n\n| Export    | Signature                                                          | Use for                                                            |\n| --------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |\n| `cn`      | `cn(...inputs: ClassValue[]): string`                              | Merge Tailwind class strings (`twMerge(clsx(...))` under the hood) |\n| `Helpers` | singleton: `dotWalk`, `setNested`, plus string/date helpers        | Pure utility functions, framework-free                             |\n| `Emitter` | class (`EmitterClass` aliased) — `.on`, `.off`, `.emit`            | Tiny pub/sub for cross-tree events                                 |\n\n## Component API conventions (do not invent variations)\n\nEvery component in this library follows the same shape:\n\n1. **`forwardRef`** when wrapping a single DOM element. Consumers may attach refs.\n2. **`className` is merged** via `cn(...)` — caller classes win on conflict.\n3. **`...rest` props pass through** to the root primitive (button, input, …).\n4. **Defaults via destructuring**, e.g. `variant = 'primary', size = 'md'`.\n5. **Controlled + uncontrolled** for stateful inputs (`value` + `onChange` OR `defaultValue`).\n6. **Theming is class-based**, never via a `color` prop. Re-skin via Tailwind config.\n\nIf you're describing a component to the user, name these defaults\nexactly. Do not propose a different shape (e.g. inventing a `color` prop\non `Button` or suggesting `tw` prop merging).\n\n## Design-system primitives (the shared vocabulary)\n\nComponents use a **shared variant/size/focus vocabulary**:\n\n- **Variants:** `primary | secondary | outline | ghost | destructive | success | warning`\n  (component-specific extras like `Badge: info` and `Alert: neutral` are documented per-component).\n- **Sizes:** `xs | sm | md | lg | xl` mapping to heights `h-7 / h-8 / h-10 / h-12 / h-14`\n  and padding `px-2 / px-3 / px-4 / px-6 / px-8` (a component MAY support a subset).\n- **Focus ring:** `focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-primary-500`\n  (the color token swaps for destructive / etc.).\n- **Dark mode:** Tailwind `darkMode: 'class'`. Every color choice has a `dark:` counterpart.\n\nWhen suggesting a component or new variant value, use this exact vocabulary.\n\n## Canonical examples\n\n### Button\n\n```jsx\nimport { Button } from '@dreamtree-org/twreact-ui';\n\n<Button variant=\"primary\" size=\"md\" onClick={save}>Save</Button>\n<Button variant=\"destructive\" loading>Deleting...</Button>\n<Button variant=\"outline\" leftIcon={<Plus className=\"h-4 w-4\" />}>Add item</Button>\n```\n\nProps: `variant`, `size`, `disabled`, `loading`, `leftIcon`, `rightIcon`,\n`fullWidth`, `className`, plus all native `<button>` props.\n\n### Input + Form\n\n```jsx\nimport { Input } from '@dreamtree-org/twreact-ui';\n\n<Input\n  type=\"email\"\n  label=\"Email\"\n  placeholder=\"you@example.com\"\n  required\n  clearable\n  error={errors.email?.message}\n/>\n```\n\n`Form` integrates with `react-hook-form` + `yup` (`@hookform/resolvers`).\nValidation rules live in consumer code.\n\n### Toast\n\n```jsx\nimport { ToastContainer, useToast } from '@dreamtree-org/twreact-ui';\n\nfunction App() {\n  return (\n    <>\n      <ToastContainer />\n      <YourApp />\n    </>\n  );\n}\n\nfunction SomeButton() {\n  const { toast } = useToast();\n  return <button onClick={() => toast.success('Saved!')}>Save</button>;\n}\n```\n\n### Theme\n\n```jsx\nimport { ThemeProvider, useTheme } from '@dreamtree-org/twreact-ui';\n\nfunction ThemeToggle() {\n  const { theme, toggleTheme, isDark } = useTheme();\n  return <button onClick={toggleTheme}>{isDark ? '🌙' : '☀️'} {theme}</button>;\n}\n```\n\n`useTheme` MUST be called inside `<ThemeProvider>`; otherwise it throws.\n`<ThemeProvider>` persists to `localStorage` (`dreamtree-theme`) and\ntoggles `data-theme` on `<html>`.\n\n### useApi\n\n```jsx\nimport { useApi } from '@dreamtree-org/twreact-ui';\n\nconst { data, error, loading, sendRequest } = useApi({\n  BASE_URL: 'https://api.example.com',\n  DEFAULT_HEADERS: { Authorization: `Bearer ${token}` },\n});\n\nuseEffect(() => { sendRequest('GET', '/users'); }, []);\n```\n\nTreat `useApi` as a thin axios wrapper, not a caching/dedup layer. For\ncache, the consumer brings their own (React Query, SWR, etc.).\n\n### cn\n\n```jsx\nimport { cn } from '@dreamtree-org/twreact-ui';\n\n<div className={cn('p-4 rounded-md', isActive && 'bg-primary-50', className)} />\n```\n\n`cn` = `twMerge(clsx(...))` — later classes win on Tailwind conflicts.\n\n## Rules for AI assistants helping consumers\n\n1. **Use library components.** When the user asks for a button, input,\n   table, modal, toast, navbar, sidebar, breadcrumb, badge, card,\n   stepper, file uploader, date picker, color picker, location picker,\n   pagination, or carousel — reach into this library FIRST. Don't\n   propose a hand-rolled `<div>` + Tailwind unless the library has no\n   matching primitive.\n2. **Use the shared vocabulary.** `variant=\"primary\"`, `size=\"md\"`,\n   `leftIcon={...}`, `fullWidth`, `clearable` — these are exact names.\n   Don't invent `color=\"blue\"` or `iconLeft={...}`.\n3. **Wrap in `<ThemeProvider>`.** Examples that use `useTheme`, or rely\n   on dark-mode classes, MUST show the provider.\n4. **`<StoreProvider>` is optional.** Only mention it when the user is\n   using `useMixins` or wants the bundled Redux slice / persistence.\n   Don't insist on it for every example.\n5. **Tailwind content[] config.** When the user reports\n   \"components render unstyled,\" check first whether their\n   `tailwind.config.js` `content[]` includes\n   `./node_modules/@dreamtree-org/twreact-ui/dist/**/*.{js,mjs}`.\n6. **Don't deep-import.** Only `@dreamtree-org/twreact-ui` is public.\n   Don't suggest `@dreamtree-org/twreact-ui/src/components/core/Button`.\n7. **React 18 only.** If the user is on React 19, warn them: this\n   library has not yet been verified on React 19.\n8. **Accessibility-first.** Icon-only buttons need `aria-label`.\n   Dialogs need a focus trap (the library provides it). Don't strip\n   `focus:ring-*` utilities.\n9. **Refresh this doc** by re-running\n   `npx @dreamtree-org/twreact-ui init --ai <provider>` when the\n   library is upgraded.\n"